@fusion.dev/helix-core 0.2.0 → 0.4.0

package/dist/mixins/mixin-field/mixin-field.js

@@ -7,161 +7,22 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { hostAria } from '../../utils/host-aria/host-aria.js';
-/** Fixed ids, scoped to the shadow root that holds them. See the mixin's note. */
 const HINT_ID = 'helix-hint';
 const FEEDBACK_ID = 'helix-feedback';
-/**
- * Grafts a label, help text, and a validation message onto a control.
- *
- * **Over `HelixElement` rather than `HelixFormElement`, because not every
- * control that wants a label is form-associated.** A checkbox group is the
- * case: each box in it submits itself already, so the group deliberately
- * reports no value of its own, and every form-related member of
- * `ElementInternals` throws `NotSupportedError` on an element that is not
- * form-associated. Measured, and the ARIA members are fine on the same
- * element, which is why the naming and describing work there and only the
- * validity has to ask first.
- *
- * Every form control wants the same three things around it and wants them in a
- * different arrangement: a label above an input, beside a checkbox, and over a
- * group. So this owns the properties, the parts, and the wiring, and each
- * control places the nodes where its own geometry needs them. Same part names
- * either way, so one stylesheet in the styled tier dresses all of them.
- *
- * **Not a wrapping `Field` component, and that is not a style preference.** A
- * wrapper cannot name what it wraps. Its label would live in its own shadow
- * root and the control in another, and measured in Chrome 148: an
- * `aria-labelledby` IDREF cannot see across, and
- * `control.ariaLabelledByElements = [labelInTheWrapper]` reads back as zero
- * elements, the reference dropped. The same assignment with a label in the
- * control's own tree is kept. That pattern works in React libraries because
- * they have no shadow boundary; bringing it here brings the ergonomics and none
- * of the conditions that made it work.
- *
- * **A control whose label is its content renders its own.** A checkbox is named
- * by the words beside it, inside the `<label>` that forwards the press, so it
- * uses its default slot and nesting `renderLabel`'s `<label>` in there would be
- * invalid markup. `label` is that slot's fallback either way.
- *
- * Worth knowing, because it costs a label and gives no warning: **a
- * whitespace-only text node is assigned to the default slot and defeats its
- * fallback.** Measured in Chrome 148, and a newline between the tags is enough,
- * so `<helix-checkbox label="Accept">` closed on the next line renders no label
- * at all. A named slot does not have this problem, because `slot="label"` is an
- * attribute and a text node has none. It is the platform's behavior rather
- * than ours, and the same is already true of every slot fallback here.
- *
- * **The ids are fixed rather than generated.** IDREFs resolve within the tree
- * that holds them, so two controls on a page each carrying `helix-hint` in
- * their own shadow root do not collide. That also removes the usual hydration
- * hazard, since there is no generated value for a server and a client to
- * disagree about.
- *
- * **A group has to say it differently.** A control's `<input>` and its hint
- * are both in the shadow root, so a plain `aria-describedby` resolves. A
- * group's host is in the light DOM and its hint is not, so the IDREF cannot
- * reach and `element.ariaDescribedByElements` drops the reference. Only
- * `internals.ariaDescribedByElements` keeps it, which is what `describeHost`
- * uses. Measured the same way, and the failure is silent either way: the
- * description simply never reaches the accessibility tree.
- *
- * **The label, the hint and the feedback are documented on each component that
- * applies this, rather than here.** Declaring them once on this mixin is the
- * obvious fix and does not work: the analyzer reads `@csspart` off a custom
- * element class, so a class-level tag here reaches the manifest as nothing at
- * all, on this JSDoc and on the inner class alike. Measured both ways, and the
- * inner-class version is the dangerous one, since it satisfies the rule while
- * every API page stays exactly as wrong as before. Members are different and
- * do inherit, which is what the note about the inner class in the area rules
- * is about.
- */
 export const MixinField = (Base) => {
-    // JSDoc is duplicated from MixinFieldInterface deliberately. The interface is
-    // what TypeScript consumers see; this class is what the manifest analyzer
-    // reads when resolving inherited members into dependent packages.
     class FieldElement extends Base {
         constructor() {
             super(...arguments);
-            /**
-             * What is wrong, in the reader's words rather than the browser's.
-             */
             this.feedback = '';
-            /**
-             * Help under the control, shown while there is nothing wrong.
-             */
             this.hint = '';
-            /**
-             * The accessible name, and the fallback for the `label` slot.
-             */
             this.label = '';
-            /**
-             * Whether the form refuses to submit without it.
-             */
             this.required = false;
-            /**
-             * Whether the reader has had a go at the field yet.
-             *
-             * **Not `:user-invalid`**, which is the platform's own answer to "is this
-             * field wrong *yet*" and cannot work here, for a structural reason rather
-             * than a browser bug: it tracks interaction with the element it is on, and
-             * nobody interacts with this element. The reader types into an `<input>`
-             * inside its shadow root, so the host's interaction flag is never set and
-             * the selector never matches. Measured after submitting an invalid required
-             * field and again after editing one and leaving it: false both times, while
-             * `:invalid` matched both times.
-             *
-             * So the moments are listened for instead, and both of them demonstrably
-             * reach the host: `invalid` when a form is submitted with this control
-             * failing, and `change` when the reader has edited and committed. Focus
-             * alone is deliberately not one of them. Tabbing past an empty required
-             * field should not be answered with an error.
-             *
-             * **A composite control has to construct its own `change`, and this mixin
-             * deliberately does not do it for them.** A native `change` is
-             * `composed: false`, so a control built from several inner inputs never
-             * relays one to its host: `Input` gets this free from its one control,
-             * while a `PinInput` of four boxes has no inner `change` that means the
-             * code is entered, so a half-entered code is never `touched` and can never
-             * say what is wrong with it.
-             *
-             * **The obvious shared fix is for `touched` to take a `focusout`, and it is
-             * the wrong one**, because it is the paragraph above undone: a `focusout`
-             * fires on the reader who tabbed past and typed nothing, which is exactly
-             * the case this refuses to call an error. What a composite needs is not a
-             * focus moment, it is the native meaning of `change`, "edited, then left",
-             * and the editing half is the part a mixin up here cannot see.
-             *
-             * **Nor is there one shape to extract yet.** The two composites solve it
-             * differently and both are right: `PinInput` is focus-driven, taking a
-             * baseline when focus arrives from outside the row and announcing on the
-             * way out if it moved, and `DateInput` is value-driven, stopping its inner
-             * `change` and announcing once the date itself moves. Only one of them has
-             * a leaving moment at all, so generalizing from the pair is generalizing
-             * from one. The trigger for lifting it is a third control that needs the
-             * focus-driven shape, at which point what moves up is the
-             * baseline-and-commit pair rather than `touched`.
-             */
             this.touched = false;
-            /** What the last render put on screen, so a change can be noticed. */
             this.shownFeedback = '';
         }
-        /**
-         * Whether this element may be asked about its own validity at all.
-         *
-         * Reading the static the platform itself reads to decide, rather than
-         * probing: `validity` and `validationMessage` throw `NotSupportedError` on
-         * an element that is not form-associated, and a group whose members each
-         * submit themselves is not. Such a control still shows a message, it just
-         * has to be given one.
-         */
         get validates() {
             return this.constructor.formAssociated === true;
         }
-        /**
-         * @internal The message actually shown: the consumer's, or the platform's,
-         * or none. Wiring a field does to itself, read by its own template. A
-         * consumer sets `feedback` and reads validity from the platform.
-         */
         get resolvedFeedback() {
             if (this.feedback !== '') {
                 return this.feedback;
@@ -171,32 +32,13 @@ export const MixinField = (Base) => {
             }
             return this.internals.validationMessage;
         }
-        /**
-         * @internal Id of the description node, for `aria-describedby` on the
-         * control. Written by the field's own template into its own shadow root.
-         *
-         * One at a time, because only one of the two is ever rendered. Naming both
-         * would point a screen reader at an id that resolves to nothing, which it
-         * reads as a description it cannot find.
-         */
         get describedBy() {
             if (this.resolvedFeedback !== '') {
                 return FEEDBACK_ID;
             }
             return this.hint === '' ? undefined : HINT_ID;
         }
-        /**
-         * A label over a set rather than beside a control.
-         *
-         * A plain element and not a `<label for>`, because a group is not a single
-         * control and there is nothing for `for` to point at. What names the group
-         * is `linkHost`, pointing the host's internals at this element.
-         */
         renderGroupLabel() {
-            /* A set names itself through `hostAria`, so an `aria-label` here already
-               reaches the group. The label is still rendered and clipped, because
-               `renderGroupLabel` is what the styled tier lays out and a group that
-               drew nothing would collapse its own first row. */
             const hidden = this.label === '' ? this.getAttribute('aria-label') : null;
             if (this.label === '' && !hidden) {
                 return nothing;
@@ -205,31 +47,6 @@ export const MixinField = (Base) => {
         ><slot name="label">${this.label || hidden}</slot></span
       >`;
         }
-        /**
-         * A label above the control, pointing at it.
-         *
-         * A real `<label for>`, so pressing the words focuses the field and the
-         * browser does the forwarding. It resolves because `for` looks within the
-         * same tree, and the control it names is in this shadow root.
-         *
-         * **Nothing at all when there is no label**, which is the same rule the
-         * hint and the feedback follow: none of the three is always used, and an
-         * element rendered empty is not free. It still generates a box, so it still
-         * takes a row of the grid and a gap on either side of it, which is a field
-         * that has moved down the page for a label nobody wrote. `nothing` leaves
-         * comment markers rather than a node, so the gap has nothing to sit between.
-         *
-         * **`aria-label` names without showing**, and it is forwarded rather than
-         * left where the consumer put it. A custom element has no way to delegate a
-         * label to the control inside it, so an `aria-label` on the host reaches
-         * nothing: measured, the inner input came back with no label and no name of
-         * its own while the attribute sat on the wrapper. What happens instead is
-         * that the label is rendered and clipped, so the name arrives through the
-         * same `<label for>` a visible one does.
-         *
-         * The rule is that `label` means a label, `aria-label` means a name, and
-         * neither means an unnamed field a screen reader announces as "edit text".
-         */
         renderLabel() {
             const hidden = this.label === '' ? this.getAttribute('aria-label') : null;
             if (this.label === '' && !hidden) {
@@ -239,27 +56,12 @@ export const MixinField = (Base) => {
         ><slot name="label">${this.label || hidden}</slot></label
       >`;
         }
-        /**
-         * Help under the control, unless something has gone wrong.
-         *
-         * The two share a place rather than stacking, so a field is one line of
-         * small text either way and nothing below it moves when the message
-         * changes. What the reader needs at that moment is what is wrong, and a
-         * hint that survives the error it describes is a second line to read before
-         * getting to the one that matters.
-         */
         renderHint() {
             if (this.hint === '' || this.resolvedFeedback !== '') {
                 return nothing;
             }
             return html `<p part="hint" id=${HINT_ID}><slot name="hint">${this.hint}</slot></p>`;
         }
-        /**
-         * The validation message, in the hint's place.
-         *
-         * `role="alert"` rather than a live region on the whole field, so what is
-         * announced is the message and not the label and help along with it.
-         */
         renderFeedback() {
             const message = this.resolvedFeedback;
             if (message === '') {
@@ -269,23 +71,6 @@ export const MixinField = (Base) => {
         <slot name="feedback">${message}</slot>
       </p>`;
         }
-        /**
-         * Points the host at its own label and description nodes, for a group.
-         *
-         * A control's `<input>` and its hint are both in the shadow root, so a
-         * plain `aria-describedby` resolves between them. A group's host is in the
-         * light DOM and its hint is not, so the IDREF cannot reach and
-         * `element.ariaDescribedByElements` drops the reference outright. Only the
-         * `ElementInternals` form keeps it, measured in Chrome 148: two of two
-         * kept through internals, zero of one through the element.
-         *
-         * Client only, and deliberately, because element references need the nodes
-         * to exist and on the server they do not. The name is therefore also set as
-         * a plain string by the component, which a server can write, and the
-         * reference here overrides it wherever a consumer slotted something richer
-         * than a string. A group with only a property for a label reads the same
-         * either way.
-         */
         linkHost() {
             const label = this.renderRoot.querySelector('[part="label"]');
             hostAria(this.internals, {
@@ -295,19 +80,6 @@ export const MixinField = (Base) => {
                 labelledBy: label ? [label] : [],
             });
         }
-        /**
-         * Re-reads the platform's verdict, for a control that has just reported one.
-         *
-         * Validity changes through `ElementInternals` rather than through a
-         * property, so nothing schedules an update for it. Worse, the order is
-         * against us: this mixin sits above the control in the prototype chain, so
-         * its `updated` runs before the control's own, which is where `setValidity`
-         * is called. Reading the verdict here would always read the previous one,
-         * which is what left a corrected field still showing the error it had
-         * before. So the control says when it has reported, and this schedules the
-         * one further update that needs. It converges because the second pass finds
-         * nothing changed.
-         */
         refreshFeedback() {
             const next = this.resolvedFeedback;
             if (next !== this.shownFeedback) {
@@ -315,19 +87,6 @@ export const MixinField = (Base) => {
                 this.requestUpdate();
             }
         }
-        /**
-         * Reports "required and empty" and refreshes the message, or clears both.
-         *
-         * Two things differ between the controls that call this, so those are the
-         * arguments: whether the control is empty, which only it can say, and the
-         * sentence to say about it, which is different for a box, a switch and a
-         * set. The anchor is looked up here because every one of them anchors on a
-         * rendered part and the browser needs somewhere to point the bubble.
-         *
-         * The message is not derived from the control's kind, deliberately. "Tick
-         * this box" and "Choose one" are not the same instruction and a lookup
-         * table would be one more thing to keep in step with the components.
-         */
         reportRequired(empty, message, anchor) {
             if (this.required && empty) {
                 this.internals.setValidity({ valueMissing: true }, message, this.renderRoot?.querySelector(`[part="${anchor}"]`) ?? undefined);
@@ -335,40 +94,14 @@ export const MixinField = (Base) => {
             else {
                 this.internals.setValidity({});
             }
-            // Straight after, because validity moved without any property moving.
             this.refreshFeedback();
         }
-        /**
-         * Records "wrong, and the reader knows it" as the custom state `invalid`.
-         *
-         * The styled tier selects on this rather than on `:host(:user-invalid)`,
-         * which cannot match for the reason above. One state, and the message and
-         * the border agree by construction.
-         *
-         * **A state and not `data-invalid`.** A field served with a `feedback`
-         * message already failing is written invalid on its first update, which
-         * would be an attribute the consumer's server never sent.
-         * `HelixElement.toggleState` carries the argument.
-         *
-         * In `willUpdate`, which is where the resolved message is first known.
-         */
         willUpdate(changed) {
             super.willUpdate(changed);
             this.shownFeedback = this.resolvedFeedback;
             this.toggleState('invalid', this.shownFeedback !== '');
-            /* And say it to the accessibility tree. Describing a field with its
-             * `feedback` message through `aria-describedby` never announces it as
-             * being *wrong*: a reader hears the message as though it were help text.
-             * `aria-invalid` is the one word for it, and this is the one place that
-             * knows, so every field in the library gets it from here. */
             this.internals.ariaInvalid = this.shownFeedback === '' ? null : 'true';
         }
-        /**
-         * The two moments a field becomes wrong, neither of which is a property
-         * change, so nothing else would schedule an update for them.
-         *
-         * In `firstUpdated` rather than `connectedCallback`, which SSR never calls.
-         */
         firstUpdated(changed) {
             super.firstUpdated(changed);
             const touch = () => {
@@ -393,15 +126,5 @@ export const MixinField = (Base) => {
     __decorate([
         state()
     ], FieldElement.prototype, "touched", void 0);
-    /* Through `unknown`, which the protected members make necessary: TypeScript
-       treats two protected members as compatible only when they come from the
-       same declaration, and these come from two, the class here and the declared
-       interface above. Making them public would type-check without a word and put
-       five render helpers on the public API page of every form control, which is
-       what the interface exists to prevent.
-  
-       The contract is enforced by use rather than by the cast. Every helper is
-       called from `Input` or `Checkbox`, so an interface that drifts from the
-       class fails their builds. */
     return FieldElement;
 };

package/dist/utils/anchor-element/anchor-element.js

@@ -1,27 +1,4 @@
-/** How far to descend before giving up on finding a box. */
 const DEPTH = 4;
-/**
- * The element a floating surface should open against, given the slot it wraps.
- *
- * **A wrapper with no box is not an anchor.** `display: contents` puts an
- * element's children into the layout and leaves the element itself without a
- * box, so its `getBoundingClientRect()` is `0 0 0 0`. Measured: a tooltip host
- * reports exactly that while the button inside it reports 32 by 32. Anchoring
- * to it opens the surface against the top left of the window, and focusing it
- * on close puts focus nowhere.
- *
- * That is not an edge case, because wrapping is how a tooltip attaches to the
- * thing it describes. Without this, an icon button used as a trigger is the one
- * button on a toolbar that cannot have a tooltip.
- *
- * So this descends past anything that draws nothing, and the first child with a
- * box is the anchor. The wrapper is transparent by construction, so the thing
- * with the box is the thing the reader is pointing at.
- *
- * Bounded rather than a walk to the leaves: a chain of box-less wrappers is
- * already unusual, and descending without a limit through a tree this library
- * does not own is worse than stopping and anchoring to something imperfect.
- */
 export const anchorElement = (slot, fallback) => {
     const assigned = slot?.assignedElements({ flatten: true })[0];
     if (!assigned) {

package/dist/utils/capture-pointer/capture-pointer.js

@@ -1,21 +1,3 @@
-/**
- * Takes the pointer for a drag, and carries on if the platform refuses.
- *
- * **Capture is an enhancement, and the drag has to survive losing it.** What it
- * buys is events continuing to arrive once the pointer leaves the target, which
- * matters because a thin divider is easy to outrun. What it costs, called bare,
- * is the rest of the handler: `setPointerCapture` throws `NotFoundError` when
- * the id names no active pointer, and every one of these calls sits above the
- * lines that set the dragging flag and call `preventDefault`. So a refusal did
- * not degrade the drag, it canceled it.
- *
- * That is reachable outside a test: a pointer released between the event being
- * queued and the handler running is gone by the time this is called, and a
- * synthetic `pointerdown` has no active pointer at all.
- *
- * Returns whether it took, for the callers that then ask `hasPointerCapture`
- * before believing a move belongs to them.
- */
 export const capturePointer = (target, pointerId) => {
     try {
         target.setPointerCapture(pointerId);

package/dist/utils/closest-instance/closest-instance.js

@@ -1,23 +1,3 @@
-/**
- * The nearest ancestor that is an instance of a class, crossing shadow roots.
- *
- * **Identity rather than tag name.** Matching `helix-accordion-item` ties the
- * headless tier to the styled one by string, and only `@fusion.dev/helix`
- * registers a `helix-*` tag.
- *
- * The consequence is silent rather than loud. Subclassing a headless element under
- * a different tag is exactly what the headless tier exists to allow, and it is
- * what `helix/styled` itself does. Under a third tag a lookup by tag returns
- * `null`, so an accordion's `mode` is ignored and every section behaves as
- * `multiple` with no error anywhere.
- *
- * **`closest()` alone is not enough**, which is why this walks rather than
- * delegating. `closest()` stops at a shadow boundary: a component slotted into
- * another component's shadow root has a `parentNode` chain that ends at a
- * `ShadowRoot`, and `closest` will not step across it. Following `host` is what
- * makes a nested arrangement resolve, and nesting through a slot is the
- * ordinary case for anything composable.
- */
 export const closestInstance = (from, Ctor) => {
     let node = from ?? null;
     while (node) {

package/dist/utils/create-sheet/create-sheet.js

@@ -1,16 +1,2 @@
 import { unsafeCSS } from 'lit';
-/**
- * Builds a stylesheet from CSS authored in a `.css` file.
- *
- * Component styles live in real `.css` files rather than `css` tagged
- * templates, so they get CSS tooling: syntax highlighting, formatters, the
- * token linter, and a diff that reads as CSS. `turbo run styles` compiles each
- * one into a sibling `.css.ts` that calls this.
- *
- * The `unsafe` in `unsafeCSS` warns about interpolating untrusted input into a
- * stylesheet. That is not what happens here: the argument is a build-time
- * constant read from a file in this repo, never a runtime value. Wrapping it
- * keeps the warning where it belongs, on `unsafeCSS` itself, and gives one seam
- * to change if constructable stylesheets become the better primitive.
- */
 export const createSheet = (cssText) => unsafeCSS(cssText);

package/dist/utils/custom-element/custom-element.js

@@ -1,90 +1,8 @@
-/*
- * Registers a custom element, once.
- *
- * A drop-in replacement for Lit's `@customElement` that does not throw when the
- * tag is already registered.
- *
- * The duplicate is not hypothetical. Next.js evaluates a module in both the
- * server and client graphs, so a component imported by a server component and a
- * client component runs its registration twice against one registry, and
- * `customElements.define` throws:
- *
- * > Failed to execute 'define': the name "helix-card" has already been used
- *
- * That failure takes down the whole prerender, and it appears only once an app
- * mixes server and client usage of the same component, which is exactly what a
- * real app does.
- *
- * The analyzer detects `@customElement` **by decorator name**, not by where it
- * is imported from, so the manifest still records `tagName` and nothing
- * downstream changes.
- */
-/**
- * Tags already reported, so a page holding duplicates says each one once rather
- * than once per module that tried.
- */
 const reported = new Set();
-/**
- * The tags this page registered twice, for a reader that is not a person.
- *
- * **The warning below is the right thing and it is not a readable output.** It
- * fires at the moment of the second registration, which is the best possible
- * position and better than anything a later pass can do, and it goes to a
- * console: a CI job cannot see it, and a developer whose console already has
- * forty lines in it will not. `@fusion.dev/helix-diagnostics` reads this instead, so the
- * same fault reaches a structured report without a second detector guessing at
- * it from the outside. Detect once, at the source; surface twice.
- */
 const duplicates = new Set();
-/** Every tag registered twice by different classes, in registration order. */
 export const duplicateRegistrations = () => [...duplicates];
-/**
- * Every tag this decorator has defined, in definition order.
- *
- * **Recorded here because here is the only place that sees all of them once.** A
- * spec wanting "every element this package defines" reached for patching
- * `customElements.define` around an import of the barrel, and that answers
- * correctly only for the first importer in the process: a second import is a
- * module-cache hit and defines nothing, so any spec that touched a component
- * first silently shrank the list. Measured when one did, and what it reported
- * was a floor count, 164 against 250, which names nothing about the cause.
- *
- * Not `registerElementEvents`, which was tried and is a different set: the
- * generated map holds the tags that *dispatch* something, so it came out 68
- * against 90. Definition is the question, so the definition site is the answer.
- */
 const defined = [];
-/** Every tag registered through `customElement`, whoever imported it first. */
 export const definedTags = () => [...defined];
-/**
- * Says so when a second, different class asks for a tag that is already taken.
- *
- * **Returning quietly is right and saying nothing is not.** The registry keeps
- * the first constructor, so on a page carrying two copies of Helix every
- * `<helix-button>` is the first copy's class whatever the second copy exports.
- * Nothing fails: the element renders, behaves, and answers its own API. What
- * breaks is identity, `el instanceof HelixButton` returning `false` against an
- * element that is visibly a button, and a version's fixes being absent from
- * elements the consumer believes are on that version. Both are hours of
- * debugging with no error to search for, which is the worst shape a library
- * failure can take.
- *
- * **Only in a browser, which is the line that keeps this quiet where the guard
- * was written for.** The prerender case above is a server one: Lit's SSR shim
- * provides `customElements` and `document` and leaves `window` undefined, so
- * `typeof window` separates a real page from a render pass exactly. Measured
- * against `@lit-labs/ssr`'s global DOM shim rather than assumed, because a
- * diagnostic that fires during a build is a diagnostic somebody turns off.
- *
- * **Different constructors, not merely a second call.** A module evaluated
- * twice in one graph produces two class objects and is a genuine duplicate; the
- * same class arriving twice through two import specifiers is not, and has
- * nothing to report.
- *
- * No `throw`. The first definition is already live and elements are already
- * upgraded against it, so there is nothing left to refuse and a lot to take
- * down.
- */
 const warnDuplicate = (tagName) => {
     if (typeof window === 'undefined' || reported.has(tagName)) {
         return;
@@ -98,7 +16,6 @@ const warnDuplicate = (tagName) => {
         'bundler shipping the same version twice is the other. Deduplicate the dependency.');
 };
 export const customElement = (tagName) => (target) => {
-    // Lit SSR shims the registry, but a bare Node context may have none.
     if (typeof customElements === 'undefined') {
         return;
     }

package/dist/utils/draw-icon/draw-icon.js

@@ -1,33 +1,5 @@
 import { html, nothing } from 'lit';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/**
- * Draws an icon that was imported by name, rather than looked up by string.
- *
- * **`<helix-icon name="play">` indexes the whole icon set at runtime.** Its
- * render is `icons[this.name]`, and no bundler can shake a dynamic index, so
- * every consumer of any component that renders one ships all of the generated
- * path data: measured at 50,814 bytes raw and 15,010 gzipped for 102 icons, and
- * growing about 147 gzipped bytes per icon added. A named import ships one path
- * and is checked when the package compiles rather than by a name lookup later.
- *
- * That element still earns its place as *public* API, where a consumer writes a
- * name in markup and a lookup is the only thing that can work. What it should
- * not be is how this library draws its own marks.
- *
- * **There is no `part` option, and there cannot be.** A part name behind an
- * interpolation is a part the manifest cannot see, so the component's own
- * stylesheet matches nothing and the part stops being
- * API. `Trend` needs one and therefore writes its `<svg>` out with a literal
- * `part="icon"`, which is the honest cost: a helper can carry everything except
- * the thing static analysis has to read.
- *
- * `data-glyph` rather than a class, because the sizing lives in
- * `helix/styled/src/icon/glyph.css` and a component's own `--icon-size`
- * declarations have to keep working untouched: the variable was read by
- * `helix-icon`, and now it is read by the rule that sheet carries. Without it
- * every one of those declarations would go quietly dead and every mark in six
- * families would change size.
- */
 export const drawIcon = (icon, options = {}) => html `<svg
     aria-hidden="true"
     data-glyph