webcomponents/gold-standard

gold-standard's Issues

Tools for enforcing the gold-standard?

I have been working on creating a open-element template that comes with a number of services and features built in so that new elements can start with best practices from day one (and without all extra overhead of setting up services each time). For example, it uses Travis CI for builds, SauceLabs for cross-browser testing, Istanbul for code coverage, semantic-release to enforce semver, Commitizen to enforce conventional commits and changelogs, etc.

I was wondering if there are things on the gold-standard list that can be automatically tested for -- like accessibility or localization. To any extent possible, I would love to see the open-element automatically enforce the gold-standard.

Any thoughts on tools or libraries that can be used for enforcing the gold-standard?

Clarify Child Independence

Breaking out this feedback from @arkihillel in #10:

Child Independence — Can you use the component with a wide range of child element types?

This too is unclear. What's considered a wide range? The <span> tag only accepts a very limited set of child elements. Putting a <div> as a child of a <span> will somehow work but it's supposed to be invalid. If the HTML does not always allow child Independence, it shouldn't be considered standard for web components too.

I've expanded the Child Independence topic somewhat. Does that clarify the intent better? The concern here is that devs often create components that only work with a single type of child element, which is generally too limiting.

Bug in examples: Uncaught SyntaxError: await is only valid in async function

When you try executing this code

await import('./smart/component.m.js');

in browser (Chrome) it would through

Uncaught SyntaxError: await is only valid in async function

Feedback

I've re-read the list for the tenth time, it's very useful

A problem I have, though, is that the list doesn't differentiate between UI and functional components

Otherwise, I have some feedback about the rules that are already present in the list:

Relative Paths — Are all paths relative to required resources (images, etc.) relative to the component source?

A web component should appear self sufficient as far as the user is concerned. If resources are required, they should be packaged with the component. The distribution and packaging standards should be a matter of their own

Local Effects — Does the component limit its effects to itself (or a designated target element)?

This rule is not very clear. Does an overlay affect over elements?

Child Independence — Can you use the component with a wide range of child element types?

This too is unclear. What's considered a wide range? The <span> tag only accepts a very limited set of child elements. Putting a <div> as a child of a <span> will somehow work but it's supposed to be invalid. If the HTML does not always allow child Independence, it shouldn't be considered standard for web components too.

Back-End Independence — Can the component retrieve its content from a variety of a back-end services?

This rule will be practically impossible to enforce in some cases. Take the <google-map> Polymer element for example. While, in theory, it could support other services, it just wouldn't make sense to bundle them all under the same component

Responsive — Does the component scale well to standard mobile, tablet, and desktop screen sizes?

This one is really tricky. While it is very important on visually large components like a text editor, it doesn't necessarily make sense on more atomic ones like buttons. The HTML is not responsive per spec, responsiveness is "only" a UX standard. Then, a more atomic element shouldn't deal with that

Progress Feedback — For long operations, does the component provide appropriate feedback?

Long operations should only be allowed whenever the network is used (think API calls or lazy loading external resources). If an UI element does need computations in order to work, it should be coupled with an external, functional, element.

e.g. a Fibonacci calculator should be composed of two elements <fib-view> and <fib-calc>. Each one should have its own set of events and the user should be in control of whether or not to show a loader and what this loader would look like. Then again, this concern may already be solved by letting the user customize the calculator loader styling

I may have misunderstood the intent of some of the rules, don't hesitate to correct me if I'm wrong.

Clarify Progress Feedback guideline

Breaking out this feedback from @arkihillel in #10:

Progress Feedback — For long operations, does the component provide appropriate feedback?

Long operations should only be allowed whenever the network is used (think API calls or lazy loading external resources). If an UI element does need computations in order to work, it should be coupled with an external, functional, element.

e.g. a Fibonacci calculator should be composed of two elements <fib-view> and <fib-calc>. Each one should have its own set of events and the user should be in control of whether or not to show a loader and what this loader would look like. Then again, this concern may already be solved by letting the user customize the calculator loader styling

I agree that such factoring is a good idea. I'm not sure how much detail to provide at this point on strategies for doing so, as we're still figuring out the best techniques.

In the meantime, I've tweaked the wording of the Progress Feedback guideline a bit, changing "does the component" to "can the component", and adding a little more content. Let me know if that helps address your point.

Clarify Responsive guideline

Breaking out this feedback from @arkihillel in #10:

Responsive — Does the component scale well to standard mobile, tablet, and desktop screen sizes?

This one is really tricky. While it is very important on visually large components like a text editor, it doesn't necessarily make sense on more atomic ones like buttons. The HTML is not responsive per spec, responsiveness is "only" a UX standard. Then, a more atomic element shouldn't deal with that

I've taken a shot at expanding the Responsive guideline. Can you please review and see if that helps address your concern?

Duplicate checklist item: Child independence

https://github.com/webcomponents/gold-standard/wiki/Parent-Child-Independence
https://github.com/webcomponents/gold-standard/wiki/Child-Independence

It looks like the latter is a less elaborate version of the former? Even the example is almost the same.

Refine Back-End Independence

Breaking out this feedback from @arkihillel in #10:

Back-End Independence — Can the component retrieve its content from a variety of a back-end services?

This rule will be practically impossible to enforce in some cases. Take the <google-map> Polymer element for example. While, in theory, it could support other services, it just wouldn't make sense to bundle them all under the same component

Agreed. I think it's appropriate for a component to depend on a specific backend if that's the entire purpose of the component. The main concern here is to avoid components that depend on a specific service that's incidental to the component's stated purpose.

If the page were rewritten along the following lines, would that help?

✓ Back-End Independence

Does the component avoid unnecessary dependency on a specific back-end service?

Some components are designed to be used only with a specific company or organization's services. A case in point might be the google-map component which renders a map using Google Maps. Since the purpose of the component is to expose that specific back-end service, it's reasonable that the component only works with that service. The component's name clearly expresses that focus/limitation.

However, front-end components that solve more general-purpose problems should ideally support a range of back-end services. If you are creating a rich text editor component and want to offer a way to store and load editing preferences, it's probably best to avoid embedding a dependency on a specific back-end service like Dropbox into your otherwise general-purpose editor. A better solution might be to factor the preference storage aspect into something that permits storing preferences in a variety of services (both public and private), and offer a connector that saves preferences to Dropbox as a separable option.

Clarify/refine Relative Paths

Breaking out this feedback from @arkihillel in #10:

Relative Paths — Are all paths relative to required resources (images, etc.) relative to the component source?

A web component should appear self sufficient as far as the user is concerned. If resources are required, they should be packaged with the component. The distribution and packaging standards should be a matter of their own

As with the other guidelines in the Loading section, this guideline is admittedly challenging to define. It's a critical issue — I've seen numerous web components that made assumptions about where they were located in the source tree, and were effectively unusable outside a project that wasn't organized exactly like the component's original project. And yet none of the Loading criteria can be defined with reference to HTML elements — the native ones are built-in, so they don't have any loading issues.

This particular issue has actually gotten worse since it was first written. Web components originally could depend upon HTML Imports. Since those have died, we're left with a world in which there's no standard means for a bit of source code to load a required resource from a relative location.

I'm debating whether to remove this guideline for the time being, or reword it.

Organize into Levels?

This is a truly awesome list!

But it might a bit on the long side. I wonder if it would useful to organize it into levels of importance. For instance, loading dependencies and reattachment are way more critical than say restrained colors.

Some of the more important and trickier parts, like supporting content re-projection, or non-obvious enough that they could benefit from being part of a lower level (assuming Level 0 or 1 is the most important).

Naming & namespacing

Best practices on naming & namespacing should be addressed. Here is an example by @zenorocha http://webcomponents.org/articles/how-should-i-name-my-element/

Recommendations for generating change events when an attribute has updated?

From @robdodson:

Before I forget, I'm not sure if the checklist includes well behaved components firing change events when an attribute has updated, but I think this is important for data binding systems like Angular 2.

I assume the idea here is that if you create an instance of , then change the foo attribute, you may be expecting the element to raise a “change” event.

I'm not sure whether there's any behavior here that's recognized as good by enough people that we can craft a checklist item for it, but I'm open to the idea.

Needs something about style separation

Seems like a good component would not pollute main document with its styles?

Consider adding an item to address validation of input elements

Generally speaking, it's not clear how people should create web components as form input elements. But as that gets resolved, we may want to add checklist items to cover such components.

As an example, components that are intended for use in forms should probably take advantage of validation APIs.

• https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation
• http://www.w3.org/TR/wai-aria/states_and_properties#aria-invalid

[Hat tip to Alice Boxhall and Rob Dodson for suggesting this item.]

Potential Logo for Adherence

I needed a symbol for the gold standard and I was thinking it might be a nice logo. What do you think? What would you change?

Gold standards should include unit tests

On glaring omission from this standard is unit tests. I ideally these tests would be run with npm test to ensure that they would be run constantly. The description should perhaps have some target coverage percentage and what a good test should look like.

This should be added to the development section.

[WIKI] Declared Semantics contains dead links to Aria

The following links are dead

• ARIA Roles Model
• ARIA States and Properties

It's new address is
ARIA Roles Model https://www.w3.org/TR/wai-aria-1.1/#usage_intro
ARIA States and Properties https://www.w3.org/TR/wai-aria-1.1/#introstates

Clarify/refine Local Effects

Breaking out this feedback from @arkihillel in #10:

Local Effects — Does the component limit its effects to itself (or a designated target element)?

This rule is not very clear. Does an overlay affect over elements?

The intent is more about programmatic manipulation of other elements rather than visual effects. An overlay may appear on top of other elements but leave them otherwise alone, in which case (in my mind) it would pass this criteria. My concern is more with components that manipulate other elements, typically their parent elements or sibling elements in some unexpected way. E.g., they might change styles on another element outside their local DOM tree, or add or remove subelements.

This criteria does not mean that such techniques are necessarily awful, just that they're surprising and deviate from developer expectations set by the examples of the native elements. So, if a component wants to meet the Gold Standard, it should avoid those techniques.

If that clarifies things a bit, I (or anyone else) could expand the page for Local Effects. If there's more to discuss here, though, let me know.