Call for ideas on webcomponents.org reboot

[justinfagnani]

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:

• A great landing page for web components
• Documentation for specs and patterns that apply to all web components
• A library-agnostic catalog
• Links to popular web component helper libraries and frameworks
• Links to tooling, configuration, and guides for users of common tools, eg Rollup, Webpack, Karma, Storybook, etc.

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:

1. This issue is the call for ideas and a place to brainstorm.
2. A requirements document as a markdown file in this repo, built via PRs.
3. A detailed design document as a markdown file in this repo, built via PRs.
4. Individual issues for specific questions.
5. Implementation...

[justinfagnani]

cc @thepassle, @LarsDenBakker, @Westbrook, @daKmoR, @bennypowers, @graynorton, @kevinpschaaf, @arthurevans, @treshugart, @matthewp, @adamdbradley, @caridy, @diervo, @robwormald

[thepassle]

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;

• developing a single web component (think a <google-maps> type of component)
• developing a UI component library
• developing applications using web components
• using web components in CMS type of environments

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]

Some of my person ideas:

Landing Page

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).

Catalog

Features

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:

• Filtered to actual web components
• Structured documentation, especially around web components specifics like slots, custom CSS properties, parts, etc.
• Inline demos
• Inline sample editor
• Component type
• Collections
• Metrics/validation? (Pika does interesting thing around modules, do we have similar for WCs?)

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

Indexing Pipeline

The catalog and indexing pipeline should be built around the custom-elements.json file proposed by @octref in WICG/webcomponents#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)

Inclusion Criteria

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.

Documentation

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:

• Custom elements
• Shadow DOM
• Styling with custom variables, parts, constructible stylesheets
• Accessibility
• Form association
• Data: attributes, properties, children, some class basics like accessors.
• Communication between elements: events, etc.
• Best practices
• Browser support
• Polyfills

Getting Started / Tooling

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]

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]

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.

---

Syndicated Content

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.

Workflow and Tooling Docs

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?

Window on the Spec Process

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]

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]

@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]

@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:

• create a module JS file
• extend HTMLElement
• load the module into HTML with <script type="module">
• serve the module with just about any static file server
• see the result

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]

Agree with @matthewp about documentation about frameworks - Very commonly asked.
Also useful would be:

• Best practices for publishing on npm - package.json etc
• Docs on accessibility
• Much better demos/code especially in the catalog
• Perhaps hosting a REPL (or links to codesandbox) with Vanilla Javascript, lit, stencil, other libs

[petecarapetyan]

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]

slack feed

https://gitter.im/webcomponents/home

[web-padawan]

I'm also interested in contributing to the project reboot. Let me add some notes.

Knowledge base

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

• thumbs (pictures),
• categories (e.g. "tutorial", "video", "podcast")
• tags (e.g. "polymer", "stencil" etc),
• year filter.

Community

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.

https://gitter.im/webcomponents/home

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).

Demo snippets

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]

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]

@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]

@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]

@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]

@georges-gomes

Oh, that logo… 🙃

The correct icon: 😉

[georges-gomes]

@FluorescentHallucinogen 😱 I fix it today!

[dbatiste]

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.

• Pulling from the GitHub readme sometimes results in content in webcomponents.org that we don't want to show. For instance, a screenshot of a component may be included for the purpose of GitHub, but such content becomes somewhat redundant on webcomponents.org when a live demo is provided. There is sometimes also associated text content that becomes unnecessary. In addition, the GitHub readme is bloated with live-demo code. I think it would be great to pull this info from elsewhere. Presumably these things would be referenced from entries in custom-elements.json.
• Resizable components - currently I think the size of the live demo is initially set, so components requiring additional height (ex. opening a dropdown, displaying a dialog, absolute positioned elements) requires the demo code to modify the demo document dimensions. I think the live demo could be more accommodating.

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]

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:

• Syndication - easy ability to pull in lots of sources of articles and what not
• Something that brings up just how much of the web now supports web components without polyfills. With Edge and Firefox ESR getting full support by the end of the year, I see the polyfills notion come up a lot and yet is less and less of an issue for general traffic
• hello-world - Something like the LitElement "try lit" that steps through getting a vanillaJS hello world OR even better, allow different element communities to supply their own "Try" / Hello-world tutorial and link off to them
• Moon shots / Showcase - Huge initiatives that surround web components and help enforce their usage being legit. For example BYU adoption for branding on all properties, Sales force Lightning, Red Hat's PatternFly, StencilJS, HAXTheWeb (all webcomponent cms). Things that are both "oh wow that organization uses it" as well as things that can break the "this is just leaf nodes" FUD.
• Have people supply a link in their package.json that is to the thing to be marked as a demo. Many demo's don't work on the current site, are polymer analyze driven (as brought up above) and many people put in READMEs a demo link.
• documented package.json or webcomponents.json file inclusion that the website then will read to build out bits of the UI for the element
• Registry should still be prominent in my mind, it's the biggest selling point in a V1 world view and among the trainings I give to know you can leverage others work
• FAQ for things like "What about SSR", "What about state management", "What about..." there's a lot of these that I know everyone commonly gets asked and while there isn't a definitive singular truth, there's many that can be debunked or at least pointed off to resources for additional nuance (SSR being a big one that comes up)
• Bring parts of open-wc and custom-elements-everywhere into the mix. Many lessons to learn from those resources
• Clear governance that this isn't "just a google thing" - I know this... but there is still that perception when the word Polymer comes up. If that's logos at the bottom of a "who's using this" or "Who supports this" sorta thing then so be it, but anything to suggest this isn't just a google thing.

[octref]

Some thoughts on the JSON file.

It should be an union of:

• Properties needed for editor (doc, schema), so people who download a component would get all editor tooling support
• Metadata needed for generating the componetn's page. For example a link to docs that describe the component.

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]

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]

@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]

i've had some success

[benjamind]

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]

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]

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.

Demos

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...

Tooling / Ecosystem Interop

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

• npm, yarn, et all
• webpack, Rollup, Parcel (?)
• babel, PostCSS
• Karma
• Redux
• Custom Elements Everywhere

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...

Documentation

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.

Design Systems / CSS

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]

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]

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]

cc @pshihn @castastrophe @muan @bengfarrell @marcushellberg for thoughts from component maintainers

[castastrophe]

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]

I will be very happy to help! Thank you all!

[stevenfowler16]

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]

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?

1. It's all about getting started as soon as possible
2. It provides an extensive knowledge base

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]

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]

I would like to see the following feature request if possible #1240

[daKmoR]

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:

1. fuzzy search (obvious 😬 ) - e.g. search for card shows all web components that have card somewhere in the name, description, attributes, properties, ...
2. size - e.g. show only packages with a maximal size/gzip size/self size/...
3. dependencies - e.g. show only packages which depend on lit-element 2.x or haunted 4.1.x
4. ...?

what would be important for you?

[e111077]

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]

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

• 0 design (only functional)
• show interaction for desktop and mobile
• define possible metrics to show on the list view (size, github stars, dependencies, last release, npm downloads)
• define possible metrics which can be filtered (dependencies, size, module, demo, ...)
• implement filtering per dependency
• define detail view data (info, readme, demo, links, source)
• include demos directly from unpkg (if in npm artifact or via configured link)
• allow for swiping through search results in detail view on mobile
• require a custom-elements.json
• allow to manually index new components (POC for an npm couchdb follow has also been done)
• tested on latest chrome/safari and android/iphone

Still open

• open demo in codepen
• ...

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 open-wc/catalog#8 (there are also some more details)

[georges-gomes]

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]

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]

@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]

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]

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]

@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]

Several problems I have with polymer slack as a web components ecosystem forum are:

• It is branded as Polymer which is inherently (not that we would kick them out) non-inclusive to other web component brands
• It is not indexable via search engine which makes the community seem small to people new to WCs
• The signup workflow breaks down often
• It is primarily (though not solely) intended as a Polymer support and topic community e.g. lit, polymer lib, lit-element, vanilla web components, but WCs that use everything but shadow dom or shady dom typically don't fall into conversation there

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:

• packaging & publishing WCs guidelines
• guidelines on theming naming conventions across WCs owned by different people
• webcomponents SSR standardization guidelines

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.

[web-padawan]

@e111077 I totally agree with the problems of lacking a community where e.g. Polymer, Stencil and let's say Salesforce developers could reach one another and discuss the ideas and solutions.

I was looking into Spectrum but unfortunately it does not seem to be actively maintained.

[abdonrd]

I totally agree. I am not sure which platform would be the most appropriate, but Slack sure not.

Requirements:

• Indexable
• Easy signup
• Welcome the whole community: Polymer, LitElement, Stencil, Salesforce LWC, Haunted, etc
• Some kind of threads system to sort the discussions? Like Slack threads or GitHub issues.

In all these cases I always miss a "GitHub Discussions". haha

In addition to Spectrum, could another option be to use the issues of a new repository called webcomponents/community or something? Would it make sense?

[thepassle]

I think a shared web component community would be a great idea, and would be really nice for sharing ideas/tooling/solutions. Just today there were some discussions in the polymer slacks open-wc channel on test runners, and for example what Stencil uses.

Maybe Pika communities by @FredKSchott could be an option? https://www.pika.dev/community/

[georges-gomes]

I agree with the vision that is build here.
webcomponents.org should maybe just become a gateway to the different content types:

• Pointing to the official "Forum/chat"
  I agree we need something else than Slack and not labels "Polymer" - makes no sense for a new comer.

• Pointing to Web Components specs, documentations, tutorials
  Very curated - shouldn't be too hard
  The right place to get started

• Pointing to the open community best practices
  open-wc.org is doing a great job on this and we could maybe embrace and aggregate around it more.

• Pointing to one or more catalogs
  The existing catalog is not up to date with what today's developer expect. This is a repellent.
  We want modern, ES Module only, custom-elements with a single install experience.
  open-wc started some prototype, I think once we have custom-elements.json stabilised it can go quick from here.

That's all we need really.

My 2 cents

[web-padawan]

Regarding the content / knowledge base that I mentioned, here is my current POC:
https://www.notion.so/webcomponents/Web-Components-bookmarks-64066078f891433dbc74997dc4d64302

I'm planning to convert that to a static website based on 11ty.

[justinfagnani]

This work has started. The main branch is now the burgeoning new site and catalog implementation. You can see the related issues under the New Site label.

[ghost]

Hi all.

I would like to know if it would be possible to have a donation link for the web components I develop on the webcomponents.org website?

Would it be possible to have a donation link for the web components I develop on the webcomponents.org site?

[justinfagnani]

@codehangen we will display either the main README or a different catalog README as specified in the custom elements manifest. You can include whatever links you want in there, including donation links.

It might not be a bad idea to have funding links as part of the custom elements manifest schema, then we could show them along with npm, GitHub, and homepage links. I would file an issue at https://github.com/webcomponents/custom-elements-manifest/issues to discuss that.