Open justinfagnani opened 5 years ago
justinfagnani
commented
5 years ago cc @thepassle, @LarsDenBakker, @westbrook, @daKmoR, @bennypowers, @graynorton, @kevinpschaaf, @arthurevans, @treshugart, @matthewp, @adamdbradley, @caridy, @diervo, @robwormald
thepassle
commented
5 years ago Thanks for starting the discussion Justin! As discussed earlier, we at open-wc are very happy to collaborate and contribute to this effort, and very happy with the community driven approach.
I think it would be great if we can get some people from other parts of the web component ecosystem (stencil/hybrids/skate/vue/etc) in this discussion as well to ask about their needs/wishes, and hopefully contributions, so if anyone has any names to tag, please do so.
Im very much on board with making webcomponents.org more of a landing place for web components, perhaps not unlike how frameworks tend to approach these things. Some things that I think would be interesting to somehow address are different usecases for web components;
<google-maps> type of component)One thing that we've had a lot of very good feedback on is our demos. People find it very useful to quickly be able to look at a demo and fiddle with it to discover a pattern on how to do something, that are a little bit more than just reading the MDN documentation. Maybe we can somehow incorporate something similar as well; eg how to use slots, slot changed, attribute reflection, etc. (Disclaimer: our demos are targeted at LitElement, these demos probably should be vanilla)
justinfagnani
commented
5 years ago Some of my person ideas:
Web components as a whole really need a home. The equivalent to angular.io, emberjs.com, etc. It should lean towards the high-level, introduce web components to those who are unfamiliar with them, and speak at least a little to the mission and benefits the standards.
Marketing-wise, it could feature a rotation of particularly successful components or projects, like <model-viewer>, a component set, a product (Beaker, Salesforce, Microsoft Edge settings pages, etc).
The catalog needs to deliver some value above and beyond npmjs.com in order to be worth it. A few features that would justify its existence:
The current demos hosted here work quite well, we should just make sure that any project can include them and that we document how to make them work with our demo server. But we should expand the demos into inline sample editing / playground, like what @e111077 is doing in https://github.com/PolymerLabs/code-sample-editor
The catalog and indexing pipeline should be built around the custom-elements.json file proposed by @octref in https://github.com/w3c/webcomponents/issues/776
Rather than do any analysis on the webcomponents.org servers, we'll simply read and display the data from custom-elements.json. In fact, a valid custom-elements.json should be required for listing in the catalog, which will help weed out packages that have just added a web-components keyword to their package.json, but aren't actual web components. This will also encourage projects the generate and publish custom-elements.json which will improve editor experiences.
We will probably need to expand on the fields in custom-elements.json for demos and such. (cc @ocrtref and @rictic)
Lots of people use the term "web components" more generally than we do, and we want to make sure that components here are truly custom elements. We'll have to figure out what to do around frameworks that optionally allow you to wrap or compile to web components, but my inclination would be that if it's published as a custom element it counts, and if not it doesn't. After all, just about anything can be wrapped.
We should strive to have the go-to documentation for web components basics, so that every other library, blog post, or spicy Twitter thread can link to well-written nearly canonical docs. This includes:
I think webcomponents.org should have some information on getting started, but stick to the most standards-based, tool-free aspects, ie: write a module with a class, load it into an HTML file, see it go, etc.
More opinionated or tool-specific instructions, ie bundling, compilation, testing, should generally be left to sites like open-wc.org, or library-specific sites. There are some exceptions, like talking about the need for custom elements classes to do real super() calls into HTMLElement's constructor.
We should absolutely talk about the polyfills in this context too.
matthewp
commented
5 years ago Thanks for starting this @justinfagnani. I agree that focusing on documentation is a good way to go. I think the component library still has value though, so I wouldn't want to see it going away.
The polyfill documentation is one thing that I want to link to but it seems outdated.
Another is an explanation on how to use web components with popular frameworks. Frameworks should really host this documentation themselves. But some of them do and it's pretty bad, like this one: https://reactjs.org/docs/web-components.html
It's pretty hard to find good documentation on newer features like ElementInternals, so stuff like that would be great too.
So I'd probably start by coming up with an outline on what this should all look like.
bennypowers
commented
5 years ago One of the things I love about web components is the flexibility they offer for programming styles etc. I'd like to hear from @smalluban, @eavichay, and other web component framework authors how they'd like to see this community resource develop.
Along the lines of @justinfagnani's idea for a rotating feature of projects, we may consider featuring sites, frameworks, recipes, or projects from the community in a blog. In addition to the low-level, high-quality docs and explainers around the spec that would be the major portion of the site's static content, I think there's an opportunity to highlight (without endorsing as canonical) different approaches and tools as they develop. A blog of news and releases from the community would also show the strength and diversity of thought in the field.
A question: while we all agree on things like what the Shadow DOM is and how the custom elements API works, there still is (and maybe always will be) tonnes of room for opinionated approaches in terms of workflow and tooling. Is there some threshold that a given tool can pass at which point it would be considered canonical enough to warrant pride of place on wc.org? For example, does the custom-element.json spec meet that criteria? If we decide to document any kind of tooling or workflow, How will we decide that a given tool has enough community buy-in? Alternatively, do we want to set a clear boundary now that anything that runs in-browser as part of the web platform is in the docs, and anything that doesn't is better addressed in syndicated posts or by open-wc et al?
More generally, how will we balance the standards-based, low level, and stylistically permissive nature of the field with the desire to provide that framework-like homepage feeling that developers crave?
webcomponents.org should also be a central location for exposing the broader community to the goings-on of the specification process. There's so much interesting information available in tersely annotated minutes of whatwg or tc39 meetings and in w3c/webcomponents issue and pr threads, and there are things like is and css modules which have tremendous developer appeal but have perhaps failed to catch among implementers. webcomponents.org is the ideal place to publish explainers and canvas developer opinion.
diervo
commented
5 years ago We would love to be heavily involved (speaking as Salesforce) as resources allow. So much we can help and contribute specially when it comes to polyfills and tools (which I know Google is heavily invested in as well).
Already sent emails internally see how much we can commit as an ongoing basis, but for sure Caridy and I will be helping.
On the documentation aspect, the team recently built our docs (https://lwc.dev/) architecture purely on markdown and web components, so hopefully an interesting architecture to consider for making it accessible for everyone to contribute easily.
@justinfagnani let us know how and when you want to proceed to move this forward.
justinfagnani
commented
5 years ago @thepassle
One thing that we've had a lot of very good feedback on is our demos. People find it very useful to quickly be able to look at a demo and fiddle with it to discover a pattern on how to do something, that are a little bit more than just reading the MDN documentation. Maybe we can somehow incorporate something similar as well; eg how to use slots, slot changed, attribute reflection, etc. (Disclaimer: our demos are targeted at LitElement, these demos probably should be vanilla)
I like this idea, but I also like just how far you've run with these types of samples on open-wc.org. To scope things down for an initial version, I'd probably start with editable samples demonstrating usage of the components in the catalog itself. Even that may be a bit much for a first cut.
justinfagnani
commented
5 years ago @bennypowers
A question: while we all agree on things like what the Shadow DOM is and how the custom elements API works, there still is (and maybe always will be) tonnes of room for opinionated approaches in terms of workflow and tooling. Is there some threshold that a given tool can pass at which point it would be considered canonical enough to warrant pride of place on wc.org?
This is a great question. I'd personally draw the line extremely close to "no tools" as possible, and leave everything else up to sites like open-wc.org and libraries.
For example, does the custom-element.json spec meet that criteria?
custom-element.json would deserve documentation as the way to get components into the catalog in the first place, and as best practices in order to integrate with other tools and IDEs. It itself isn't a specific tool though, but a bridge across many.
I'd stick to simple things in any examples, like:
<script type="module">With some references like "if you need to load modules into browsers that don't support them, see {these tools | these lists of recommendations}".
If we decide to document any kind of tooling or workflow, How will we decide that a given tool has enough community buy-in?
Exactly why I'd steer clear of this area :) Also, there are clearly quite a few tools with enough adoption to warrant documentation somewhere. wc.org likely can't or shouldn't host them all.
Not to mention that most of the tools-specific documentation amounts to "get your tools to support modules and modern JavaScript fully". That can happen elsewhere while we just use modules and modern JavaScript as needed on wc.org.
pshihn
commented
5 years ago Agree with @matthewp about documentation about frameworks - Very commonly asked.
Also useful would be:
petecarapetyan
commented
5 years ago If webcomponents.org had its own slack feed, that would allow for a lot of the same kind of discussion that is both helpful to members and inappropriate for some of the more canonical aspects of the site - especially as distinct from the Polymer feed.
A pipe dream: No idea how, but if there were a way to share ratings or other validations of best and worst aspects of each listing - that would be nifty. For example, I think the world of the captain's efforts to microsize his own material clones, but other folks would have different metrics for what they want from a component. Usage would be super interesting to me also. If I know that something is used by a lot of shops that I respect, that means something to me. But how would one even think about collecting and presenting that kind of data?
bennypowers
commented
5 years ago slack feed
web-padawan
commented
5 years ago I'm also interested in contributing to the project reboot. Let me add some notes.
I already collected a lot of web components resources in the "awesome" list: https://github.com/mateusortiz/webcomponents-the-right-way
And I think we could represent such resources in a better way than long README. These could fit into https://www.webcomponents.org/community with some additions such as
One real problem is that web components do not have a community where e.g. LitElement and Stencil users could reach one another.
The more I stay in Polymer Slack channel (despite I learned a lot from there), the more it feels like staying in the "walled garden", as Polymer has pretty much closed ecosystem at the moment.
Gitter does not provide a good UX to me. How about https://spectrum.chat community? It seems also to be a better alternative than Slack in terms of SEO (e.g. forum with permalinks).
I feel that we lack a framework-agnostic multi purpose demo snippet component. We could investigate using @pikapkg CDN as part of the setup for such a component.
I see it as a common base, which could be extended and reused e.g. by lit-html demo snippet (accepting a html tagged literal) or any other library-specific demo snippet.
georges-gomes
commented
5 years ago Hi All, we just opened https://webcomponents.dev and I think it could be a nice addon to webcomponents.org to show case components and frameworks (@matthewp we just added Haunted yesterday ;)).
Our starter kits are simple but they have links to the reference materials. Our demos could be improved, for each framework and it would be a nice playground/learning experience. Don't take my word for it! Please check it out! https://webcomponents.dev
We are happy to improve it to fit the need of webcomponents.org via embeds and contribute to the documentation.
Web components with ❤️
smalluban
commented
5 years ago @bennypowers Thanks for mentioning, I wasn't aware of this discussion. From my observation, web components from the catalog have docs at a very different level. Some of them are even useless, as they show more general information about the project, but not about a specific element. It would be great to go with custom-elements.json idea. I think it could be possible to create a tool for an automatic generation of that file for easy migration (for sure, for hybrids). Then we could give up on just copying README from the project.
I would like to suggest another addition to the site. For now, we don't have the recommended solution for web components distribution. In hybrids, you can export the structure of the element, and leave the define step to the user. It is pretty the same in other libraries, or with vanilla ones. The web component author might export class definition, or use customElements.define in the body of the element. I am not sure which solution is more appropriate. I suppose, that web components authors too. The problem applies also to file format - should we only support ES modules, or should we build for older browsers, etc.. I think wc.org could provide a helpful section for web components authors, where they can learn what is the best way to distribute their components (with the docs for custom-elements.json file requirement).
A section like this could encourage tool authors to wrap them into the custom elements and distribute them for the community.
web-padawan
commented
5 years ago @georges-gomes congrats with the launch!
I think it would make sense for us to cooperate more, rather than building a bunch of similar projects independently. So I really hope we all can merge the effort at some point.
Also, the domain name is really cool (I recently checked it and noticed the "coming soon" redirect).
georges-gomes
commented
5 years ago @smalluban +1
On packaging web components. webcomponents.dev actually have one-click components publish to NPM and we worked a lot to find the best packaging.
We opinionated went with src and bare es6 module for bundlers with the right package.json entries. We left the iife bundling for the moment because it's another beast if you want standalone operability in any browser...
Our plan for iife is to generate a stub to support this html import:
<script src="mywebcomponentURL/iife/index.js" tag="nice-tag"/>This would make the define with the tag and include all dependencies and polyfills. This is just a plan for now.
We also choosed to recommend export default on class so it's easy to import and customElements.define avoiding name registry conflicts. It's also a nice way to point to the class programmatically. Otherwise, we customElements.define in the module, you can't intercept or discover anything before the customElements.define. We use this property a lot.
This is all opinionated obviously but it took a lot of time for us to figure it out.
Having a standard way to do it and a custom-elements.json meta-data file would be awesome I think.
We are with you!
PS: @smalluban we added hybrids support yesterday as well ;P Cheers
FluorescentHallucinogen
commented
5 years ago @georges-gomes
Oh, that logo… :upside_down_face:
The correct icon: :wink:
georges-gomes
commented
5 years ago @FluorescentHallucinogen 😱 I fix it today!
dbatiste
commented
5 years ago I haven't been involved in this previously, but am certainly willing to contribute to this effort.
The editable live demos for each component is a helpful feature that I would really like to see. There are a few short-comings of the existing live-demo solution that hopefully can be improved.
custom-elements.json.The ability for the catalog to reference many components per package via custom-elements.json would be good. We are currently in the process of moving our core components to a single repo (with conversion to Lit), with no current intention of using Lerna.
btopro
commented
5 years ago As one who had to rewrite most of the docs last year so that I could stop arguing w/ people about V0 arguments in a V1 spec world... I'm super happy to see this discussion kicked off. Critical things in my mind:
octref
commented
5 years ago Some thoughts on the JSON file.
It should be an union of:
I also think you should provide a docs / schema & build a tool (based on Polymer Analyzer) that can handle raw web components, but refrain from analyzing component built with any web component framework. Projects like Stencil has their own analyzer (see @manucorporat's PR that added the JSON for completion in VS Code), and frameworks like Vue can compile to WC.
I think it'd be much easier for each framework to analyze their components in their raw form as compared to you building something universal to analyze all WC output (I might be wrong).
bennypowers
commented
5 years ago based on Polymer Analyzer
This is perhaps jumping the gun, but I'd like to see docgen that uses built-in rather than custom JSDoc tags. (i.e. @mixin rather than @mixinFunction). If there are any corner cases not covered atm we should push upstream.
justinfagnani
commented
5 years ago @mixin in JSdoc had different semantics, we can't use it directly. In class mixins you're not mixing in properties of the function.
bennypowers
commented
5 years ago i've had some success
benjamind
commented
5 years ago We've been doing automatic doc generation using web-component-analyzer - https://github.com/runem/web-component-analyzer worth a look if you haven't already seen it.
justinfagnani
commented
5 years ago I really think the right thing here is to adopt a file format and leave generation of it to any tool that the component author chooses. Baking a specific tool into the catalog means that we adopt its quirks and limitations, and we'd have to run it, increasing the complexity of the indexing pipeline.
thescientist13
commented
5 years ago First and foremost just wanted to say thank you for opening this up to the community @justinfagnani and happy to see a great start to the discussion already and a promising sign of what's possible. I think this is not only a great idea, but a great opportunity for all those enthusiastic about the web in general.
Had a couple thoughts of my own to share as well and definitely also see the value in providing a strong set of resources / documentation.
I think the demos idea @thepassle highlighted would be great. High quality examples that can run right in the browser with minimal fuss and setup, allowing for ease of reproducibility in one's own project (basically copy / paste) could really help with making Web Components (and the web) more accessible to developers in general.
I know there will likely be a strong leaning towards examples without tools and services like unpkg make this especially possible, but this leads me to my next thought...
Although a strong "vanilla" presence is likely a desire, I think a big part of the adoption of more Web APIs is showing just how much interop there is with the existing set of JavaScript tools out there, and that in particular, developing with Web Components, Shadow DOM, etc can be done just as easily with all the great tools developers are already familiar with like
And of course all the community maintainers now already providing great "vanilla" solutions for tools often provided by most frameworks like for routing, state management, and of course, custom components.
However, as mentioned, the story around publishing (in general) needs much more clarity in the ecosystem, especially the shift towards ESM based publishing gaining more traction. Hopefully webcomponents.org can help drive that trend towards greater adoption.
Of course, all of this won't be possible without...
This of course is huge, and I think, to my point above, could provide one of the biggest opportunities to help drive adoption of modern web standards / APIs.
I think though the balance of what to cover vs what not cover will obviously be an important decision. However, I think it would be naive for us to not expect developers to want to know how to use Web Components with webpack and Karma, for example. Having solid, non abstracted examples here could be really useful for those who might want to work out of the context of a CLI tool. (I would like to share / offer some of my own technical docs that I would be happy to contribute / rewrite instead of putting into a new website I'm working on).
Maybe we can consider a variety of differing mediums, since many people learn in different ways? So emphasizing different platforms like a blog (Headless CMS?), live streams, podcasts, YouTube, etc could be a fun way to expand the learning / contribution pool!
Lastly, want to give a plug here to @open-wc, their documentation TOC makes a great starting point for the reboot to follow / cover, IMO.
Who can forget our good friend CSS and the thriving APIs and ecosystem around modern CSS development? (Shadow DOM aside) One thing as a dabbler in Web Components I would love to see more information on (and help with) is how to create a modern design system for an application. Design systems, variables, theming, CSS Modules, etc are all things framework users can rely on, and I think it would be a great companion to the Web Components website and could help deliver a more compelling story for Web Components overall.
Ultimately I am totally happy to help and contribute in anyway I can, as I'm sure other members of my little side project @ProjectEvergreen would be as well. Looking forward to contributing and helping spread the good word about what the web can today and how developers can start taking advantage of it.
There’s more to a web app than just the component model, and there’s more to the web than just web apps. Let's tell that story!
petecarapetyan
commented
5 years ago It seems intriguing that the same features that make WC useful make demo and docs a bit more straightforward to execute?
In that - the harder it is for your WC to demo, document, and test - the less likely it is to meet a swap-ability or plug-ability standard at a human level.
So the action of installing your WC into this site functions as an ergonomics test for your WC, just by that action? Hmm.
eavichay
commented
5 years ago I think that the webcomponents website should be built with multiple web component libraries, to prove the idea it works everywhere.
Plus source code, examples and even different build systems for them. I think it may be powerful.
justinfagnani
commented
5 years ago cc @pshihn @castastrophe @muan @bengfarrell @marcushellberg for thoughts from component maintainers
bengfarrell
commented
5 years ago Thanks for tagging! I wasn't aware of this effort. Reading through, I'm think I'm mostly of the same mind as lots of comments here. A major challenge with this effort will be documenting across a wide array of web component flavors. I wasn't aware of the custom-elements.json previously, but I dig that as a way forward for the notion of tagging elements to be featured. For example, if a component were tagged with metadata like "haunted", "rollup", and "karma", I could filter by any or all of those tags and get component examples. Even better, submitted blog posts, tutorials and videos could be tagged with the same metadata to give learning resources as well with the same search. The sum of all of these tags could potentially be exposed through a dashboard to give some indication of popularity and how solid a workflow is. LitElement might be the strongest showing at first, but to pick on Haunted again, if that picks up steam, I'd love to see the uptick on the dashboard as new elements, tutorials and blogposts come in, and I'd be motivated to explore tools and techniques across the board on the subject. The approach probably needs to be somewhat opinionated and weighted though - just to give newcomers a solid direction before they give up. I'll def follow this convo and look for ways to help out!
web-padawan
commented
5 years ago @justinfagnani any idea on how should we proceed?
As I mentioned, personally I'm interested in contributing to this project, especially "Knowledge Base" idea from my above comment https://github.com/webcomponents/webcomponents.org/issues/1250#issuecomment-506620396.
In short, I really like how https://web.dev collections are structured, and would like to create something similar. I can create a document and write down a more detailed proposal.
Note: I'm not acting on behalf of Vaadin, but there is an interest inside the company as well, especially regarding public API for webcomponents.org catalog which could be reused in Vaadin Directory.
Westbrook
commented
5 years ago Should we create a branch wc.org@next branch to serve as the root of the above task points from in OP? Having something forked here at the main repo seems like the best way to keep the conversation as much in the open and as easy to access as possible. Then we can start to hash out individual sections (e.g. Knowledge Base, Getting Started, Tools, Indexing/Catalog, Demos, Landing/Marketing, etc) in PRs that should start to shed light on the requirements of a design document.
petecarapetyan
commented
5 years ago re: @web-padawan
especially regarding public API for webcomponents.org catalog which could be reused in Vaadin Directory.
This seems like an especially powerful aspect of the discussion - when companies can all share an API - for their own internal and external subsets of web components.
Kind of like Honda and Subaru being able to source [door opening hardware internals] from the same external vendor - if that's an apt comparison.
castastrophe
commented
5 years ago Loving this robust conversation from so many contributors!
+1 to @btopro idea of syndication. I would love the ability to contribute how-to articles (standardized tagging could help make this more usable too).
+1 to prominent placement of the "Can I Use" chart showing where they work without polyfills.
I'd like to see more discussion and documentation on the site about the pros and cons of pure Shadow DOM components versus hybrid components that use slots heavily and style Light DOM. Concepts around theming components also a plus (this might be content inside a Design System section).
abdonrd
commented
5 years ago I will be very happy to help! Thank you all!
stevenfowler16
commented
5 years ago As a newbie who is building plain web components it would be great to see everything in one place. I had to scour a lot of different websites to put all the pieces together.
That being said I love it. I know my component library will work just about anywhere. I'd love to see more documentation on best practices, how to use web components, how to document properly, and how to use some tools. I have started creating web-component packages with NPM, documentation and devlopement with storybook, bundling with rollup, testing with jest and its a big leap if you haven't had any experience with those things especially when there isn't a lot of information to guide you. Most people are going to go with something that has a lot of documentation or guides(React, Vue, etc) rather than try something new that doesn't have such a big following.
Looking forward to what comes of this.
StefanNieuwenhuis
commented
5 years ago I completely agree with @justinfagnani that Web Components need a home, a hub of knowledge like angular.io is for Angular or vuejs.org is for Vue.
What do those hubs have in common?
WebComponents.org is IMHO (no offense) a collection of Web Components with very limited information on how to get started as soon as possible and it cannot serve as an extensive knowledge base due to the lack of information.
I think it's a great idea to make WebComponents.org the Center of Excellence of Web Components. I think we need to focus on getting developers started as soon as possible and extend the knowledge base.
I think that we need to focus on Framework integration (Angular/React/Vue/...) as well because most of the developers are using one and because of the interoperable nature of Web Components they are perfectly fit to be used in them as well.
I would love to contribute to this cause!
CaptainCodeman
commented
5 years ago Being able to see the size of a component would be nice - both the component itself and the dependencies it relies on. Something along the lines of bundlephobia.
e.g. if I am tempted to add paper-input to a project, the impact varies depending on whether that project already uses Polymer or if it causes Polymer to be pulled in.
I think we can do better with the top-level categories, probably grouping them by established UI concepts (e.g. here are all the chips type input components). I'm sure someone must be interested in "emoji" but is it really "top level" stuff?
ymaz
commented
5 years ago I would like to see the following feature request if possible #1240
daKmoR
commented
5 years ago Hey, we are building a POC for the search... so I was wondering what are the most important metrics you would like to be able to search/filter for.
Examples what we have/or plan now:
card shows all web components that have card somewhere in the name, description, attributes, properties, ...what would be important for you?
e111077
commented
5 years ago I don't have too much input on what is important to me, but I wanted to mention that we heavily leveraged github stars as a sign of package quality.
Additionally, npm has done a great job on this where they surface in their search popularity, quality, and maintenance gathered from https://npms.io (see their about page).
daKmoR
commented
5 years ago This is our POC for a web catalog feature. Note that it is a "true" POC e.g. code is not nice and not optimized at all. The goal was/is
custom-elements.jsonStill open
We are eager to hear your feedback on the functionality and interaction 🤗
It is live at https://catalog.open-wc.org/
If no huge changes are required we will start focusing on the design 💪
PS: I don't really want to hijack this issue for catalog details 🙈so for catalog only details feel free to also use https://github.com/open-wc/catalog/issues/8 (there are also some more details)
georges-gomes
commented
5 years ago Hi Thomas I'm obviously biais but it would be nice to have the demo open in webcomponents.dev instead of codepen :) We can help! and we have the embedded form ready now so you don't even need to go out of the catalog. Happy to discuss the details on slack anytime. Cheers Georges
btopro
commented
5 years ago for longevity / flexibility could the "demo" be configurable by the dev who made the element as far as location? Somethings work better on stackblitz for example but I know that teams who have their own pattern library in place might have a custom one driven by storybookJS / comparable. Also some projects like Material Web Design component rewrite or Vaadin have their own stand alone portfolio and might want to link directly to pieces of that for demo purposes as to not need to maintain two things.
daKmoR
commented
5 years ago @georges-gomes nice 🤗 makes totally sense to give the option to open it in multiple environments 👍
@btopro idea is to show something in an iframe - preferable something small - if you want to show something bigger like an external website or storybook then it is probably best to "just" have a link in the iframed demo... or if you want to show something else in that iframe then you can provide a url in the package.json. (Note that you will lose versioning unless you create a versionend url) Some more details you can see here: https://catalog.open-wc.org/storybook/?path=/docs/item--single (search for demo)
e111077
commented
5 years ago I was wondering what y'all think about the future WC org being more than a catalog and also including a place for the community to have a common forum (that is search indexable) to have conversations about web component conventions or conformance (in a consensus-based-soft-standardization kind of way).
Do you think this place we're brainstorming would function as a good place to have these types of conversations or do you think the current channels (it seems like the current channel for this is the webcomponents spec github issues section).
A great example of community forums I would say is the Glitch Support Forums which seems to double as support forum and issue tracker. It has a sense of structure to conversations that aren't as heavy-handed as standards organizations yet not as free-wheeling as a reddit subreddit or github thread.
CaptainCodeman
commented
5 years ago I don't think more channels are going to improve things, they simply fragment the community and make it look small & somewhat abandoned (e.g. polymer reddit). If forums are used (and I think they are way better than things like slack, because they are searchable and help build up a knowledge base of sorts plus work better async) then others should be hidden if possible.
It depends on the purpose of the discussion though - people wanting to learn / get support vs developers wanting to contribute vs people wanting to bounce ideas & chat.
thescientist13
commented
5 years ago @CaptainCodeman Would it still be useful to link everyone to Polymer Slack? Having that as a melting pot might be good, given how active and helpful it seems to have been so far?
e111077
commented
5 years ago Several problems I have with polymer slack as a web components ecosystem forum are:
What I'm envisioning is a place specific for webcomponents like the current webcomponents gitter but with indexibility via search engines and with a focus on consensus-building on guidelines rather than Q&A.
Examples of what I think would be tackled there:
If anything, perhaps this can just fit into the github issues of wc.org but just have a standardized process of submitting a proposal, discussion, review, then in the end, instead of a standard, the result can simply be a PR to the webcomponents guidelines docs. Sorta like TPAC but without the physical travel. The difficult part is just figuring out how discussion will be organized and who decides the final merge.
Where webcomponents.org is at now
webcomponents.org was launched in a very different environment than we have today: the web component specs were at "v0" with v1 not even on the horizon yet, Bower was still relevant, the Polymer Library was the most common way web components were authored, and HTML Imports were the primary loading format.
We've kept webcomponents.org somewhat up-to-date by adding npm support, and support for analyzing Polymer 2, 3, and to some extent "vanilla" web components. But it has fallen behind on the ability to analyze non-Polymer web components like Stencil, LitElement, etc. And it's web components documentation is not prominent or complete enough. The community section is very out of date.
Problems with the current architecture
Lack of introduction and approachability
webcomponents.org is designed primarily as a catalog, and secondarily as a documentation site and blog. This means that the landing page starts with listing elements and element collections, and doesn't even explain what web components are. Given that there's no singular implementor or owner of web components, and therefore no official site like many frameworks and libraries have, webcomponents.org is about as close as we have, but it doesn't introduce potential users to the concepts and benefits.
Complicated and limited analysis/indexing pipeline
The indexing pipeline runs the Polymer Analyzer against source code to determine what elements a package contains and generate documentation and demos. This has a benefit in that often times component maintainers don't need to do anything to support webcomponents.org, but it limits the catalog to the elements that the Polymer Analyzer support, which obviously unfairly tilts the catalog towards the Polymer Library.
Low prominence of documentation
Not enough prominence and attention has been given to documentation. Without a central location for web components information, many libraries have had to duplicate documentation on shared foundational concepts like custom elements and shadow DOM, and few seem to link to webcomponents.org for this information.
What would a reboot look like?
We'd like to kick off a community-driven, collaborative reboot of webcomponents.org. Google can provide guidance, resources, and contributions, but we want the vision to be set, and work to be done, collaboratively with the growing web components community.
The reboot should probably not over-focus on the catalog aspect of the current site. There are several areas of need for the site and the community as a whole, including:
How should we go about this?
In order to have a collaborative effort we'll need a detailed plan and agreement across contributors, so that work from multiple contributors can actually proceed in an organized fashion.
The process could possibly look something like this, though the process itself is open to brainstorming: