@fusion.dev/helix-headless 0.2.0 → 0.3.0

package/dist/table/root/table-root.js

@@ -7,82 +7,18 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, MixinCollection } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary Tabular data laid out on a grid.
- *
- * @description
- * A grid rather than a `<table>`, so every column lines up across rows while
- * each row stays a real element that can be styled, hidden, or made
- * interactive. Table layout gives column alignment and takes away almost
- * everything else; grid gives both.
- *
- * The cost is that the roles have to be declared, since a grid of divs is not a
- * table to anyone reading it. `table`, `row`, `cell`, and `columnheader` are
- * all set explicitly, and rows are `display: contents` so their cells become
- * items of the one grid that does the aligning.
- *
- * The properties below are written by this component and read by whoever draws
- * it. A consumer sets none of them: they carry a number this element computed
- * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
- * without measuring anything itself.
- *
- * @since 0.1.0
- * @status experimental
- * @category data
- * @aliases DataTable, Grid table
- * @documentation https://helix.fusion.dev/components/table
- *
- * @slot - The table's rows.
- *
- * @csspart empty - Shown when there are no rows to show.
- * @csspart head - The row the column headings sit in. `display: contents`, so it takes no space.
- * @csspart loading - Shown while the rows are still on their way.
- * @csspart table - The grid.
- *
- * @cssproperty --table-columns - Track list for the columns.
- * @cssproperty --table-template - The column track list this element worked out from the columns declared in it. Written by the component, read by the sheet that paints: a stylesheet takes it to lay the grid out, and setting it does nothing, because the component writes it inline on the very element that reads it and an inline declaration beats any sheet. `--table-columns` is the one to set.
- */
 let HelixHeadlessTable = class HelixHeadlessTable extends MixinCollection(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Column track list, as CSS. Deprecated: declare columns instead.
-         *
-         * Kept for a table that has no `helix-table-column` children, and ignored the
-         * moment it has one. A raw track list is the right shape for the value and
-         * the wrong place for it: the headings and the widths were two halves of one
-         * fact held in two places, and nothing checked that they agreed. Worse, the
-         * value is CSS, so handing it headings by mistake produced an invalid track
-         * list, which a grid ignores in silence: the table collapsed to one column
-         * and said nothing. Columns carry both halves now.
-         */
         this.columns = '';
-        /**
-         * Accessible name for the table.
-         */
         this.label = '';
-        /* Columns arrive from the light DOM, which changes no property here, so
-           nothing would schedule the render that reads them. */
         this.handleSlotChange = () => {
             this.requestUpdate();
         };
     }
-    /** The columns declared as children, in the order they are written. */
     get tableColumns() {
-        /* `?? []` is the server. Lit's element shim carries attributes and not a
-           tree, so `children` is undefined there, and this getter is reached from
-           `template`, which is read during `render`: spreading it throws and takes
-           the whole SSR render down with it. */
         return [...(this.children ?? [])].filter((child) => 'isTableColumn' in child && child.isTableColumn === true);
     }
-    /**
-     * The track list, from the columns if there are any.
-     *
-     * Read from the DOM rather than kept, so adding or removing a column needs
-     * nothing else to be told. Falls back to the `columns` string for a table
-     * written before columns existed, and to a single track for one that declares
-     * neither.
-     */
     get template() {
         const declared = this.tableColumns;
         if (declared.length > 0) {
@@ -90,24 +26,6 @@ let HelixHeadlessTable = class HelixHeadlessTable extends MixinCollection(HelixE
         }
         return this.columns;
     }
-    /**
-     * Nothing is assigned by name, so the columns can be put in a row.
-     *
-     * The table pattern is `table > row > columnheader`, and a header cell
-     * landing directly under `role="table"` with no owning row is invalid: it is
-     * a cell belonging to nothing. The columns are ordinary children the consumer
-     * writes with no `slot`, so the only way to put a wrapper around them without
-     * changing what a consumer writes is to assign them here.
-     *
-     * Manual rather than a `slot` attribute this element would set on the
-     * consumer's own markup, which is the change a React consumer's hydration
-     * reports and does not patch up. Assignment writes nothing at all.
-     *
-     * Safe against the server because this repo ships no declarative shadow DOM:
-     * the shadow root exists only after upgrade, and the assignment below runs in
-     * that same update. There is no window in which the shadow is present and the
-     * assignment has not happened.
-     */
     static { this.shadowRootOptions = {
         ...HelixElement.shadowRootOptions,
         slotAssignment: 'manual',

package/dist/table/row/table-row.js

@@ -6,30 +6,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
-/**
- * @summary One row of a table.
- *
- * @description
- * `display: contents` in the styled tier, so the row's cells become items of
- * the table's own grid and every column lines up across every row. The row
- * still exists as an element, which is what a `<table>` gives away when its
- * cells are laid out by the table algorithm.
- *
- * @since 0.1.0
- * @status experimental
- * @aliases Row, TableRow
- * @documentation https://helix.fusion.dev/components/table
- *
- * @slot - The row's cells.
- */
 let HelixHeadlessTableRow = class HelixHeadlessTableRow extends HelixElement {
     willUpdate(changed) {
         super.willUpdate(changed);
-        // On the host, and required: `display: contents` removes the row's box but
-        // not the row from the table's structure. Without this the table has cells
-        // and no rows, which is a broken table rather than a plain one.
-        //
-        // Set in `willUpdate`, which the server does call, unlike `connectedCallback`.
         hostAria(this.internals, { role: 'row' });
     }
     render() {

package/dist/tabs/panel/tab-panel.js

@@ -7,62 +7,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary The content shown for one tab.
- *
- * @description
- * Hidden rather than unmounted when inactive, so anything typed into a panel is
- * still there when the reader comes back to it, and so the content is in the
- * server's markup for a crawler regardless of which tab is open.
- *
- * @since 0.1.0
- * @status experimental
- * @aliases TabPanel
- * @documentation https://helix.fusion.dev/components/tabs
- *
- * @slot - The panel's content.
- *
- * @csspart panel - The panel container.
- */
 let HelixHeadlessTabPanel = class HelixHeadlessTabPanel extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * The name of the panel, which is the text of the tab that opens it.
-         *
-         * Set by the root, which is the only thing that sees both. No attribute,
-         * because it is coordination between elements rather than anything a consumer
-         * writes: the tab already says it.
-         *
-         * A string and not a reference: an IDREF resolves only in the tree it is
-         * written in, and an element reference cannot reach a sibling shadow tree
-         * either, so `aria-labelledby` to the tab's own id leaves the panel with no
-         * accessible name. `aria-label` on a `tabpanel` is how the pattern names one
-         * anyway.
-         */
         this.label = '';
-        /**
-         * Whether this panel is the visible one.
-         */
         this.selected = false;
-        /**
-         * Pairs the panel with the tab of the same value.
-         */
         this.value = '';
     }
-    /**
-     * Mirrors the chosen state where a stylesheet can select on it.
-     *
-     * **A custom state, never a reflected `selected` attribute.** The parent
-     * writes this, so reflecting it would put the element's own bookkeeping onto
-     * markup a consumer wrote and their server never sent, which React reports as
-     * a hydration mismatch and which a serialized element pasted back declares as
-     * a choice nobody made. `ElementInternals` holds it instead.
-     *
-     * The attribute still seeds the property, which is what
-     * `<helix-tab-panel selected>` in a consumer's markup means. Only the write
-     * back is gone.
-     */
     willUpdate(changed) {
         super.willUpdate(changed);
         this.toggleState('selected', this.selected);

package/dist/tabs/root/tabs-root.js

@@ -9,87 +9,24 @@ import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessTabPanel } from '../panel/tab-panel.js';
 import { HelixHeadlessTab } from '../tab/tab.js';
-/**
- * @summary A row of tabs and the panel each one shows.
- *
- * @description
- * Selection is coordinated by event, the same shape the accordion and the tree
- * use: a tab dispatches `helix-select` and the root pairs it with the panel of
- * the same value. Nothing registers with anything, so tabs added later work
- * without the root being told.
- *
- * The tab list is a single tab stop, moved with the arrow keys through
- * `KeyboardNavigationController`, the same one the radio and toggle groups use.
- * Selection follows focus, which is the right default for a small set where
- * showing a panel is cheap; a set where it is not should use `manual`.
- *
- * @since 0.1.0
- * @status experimental
- * @category navigation
- * @aliases TabList, Segmented control
- * @documentation https://helix.fusion.dev/components/tabs
- *
- * @slot - The tabs.
- * @slot panels - The panels.
- *
- * @event {HelixActivateEvent} helix-activate - Fired once the current one has moved, so the element already holds it.
- * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current tab moves, and cancelable. The only way to refuse one.
- * @event {HelixSelectEvent} helix-select - Fired when a tab is chosen. Dispatched by the tab and listened for here, because the root is what a consumer holds. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart indicator - The mark that travels to the selected tab.
- * @csspart panels - The panel container.
- * @csspart tabs - The tab list.
- */
 let HelixHeadlessTabs = class HelixHeadlessTabs extends MixinControllerActive(HelixElement) {
     constructor() {
         super(...arguments);
-        /* Arrow keys, Home and End. Same controller as the radio group and the toggle
-           group: `origin: 'focus'` because `manual` lets focus and selection diverge,
-           and `selects` because `manual` is what decides whether arriving chooses. */
         this.keys = new KeyboardNavigationController(this, {
             items: () => this.tabs,
             origin: 'focus',
             selects: () => !this.manual,
         });
-        /* The mark. Same controller as the nav bar, the toggle group and the page nav. */
         this.indicator = new IndicatorController(this, {
             active: () => this.tabs.find((tab) => tab.selected),
             indicator: () => this.renderRoot?.querySelector('[part="indicator"]'),
             surface: () => this.renderRoot?.querySelector('[part="tabs"]'),
         });
-        /**
-         * Accessible name for the tab list.
-         */
         this.label = 'Tabs';
-        /**
-         * Whether arrowing to a tab also selects it.
-         *
-         * Automatic is the default because showing a panel is usually cheap. Set this
-         * where it is not, so a reader arrowing past four tabs does not load four
-         * panels on the way.
-         */
         this.manual = false;
-        /* Through the mixin, so a consumer can refuse the change. Moving `active`
-           straight from the event leaves `helix-before-activate` an announcement
-           nobody can answer. */
         this.handleSelection = (event) => {
             this.requestActive(event.detail.value);
         };
-        /**
-         * The set changed: pair it up, watch it, and measure it.
-         *
-         * All three, and dropping `place()` leaves an indicator unplaced for the life
-         * of the page. The order of events is what does it: the host renders and
-         * measures before its tabs have upgraded, so there is no selected tab to
-         * measure and `place` refuses; the ResizeObserver's one initial callback
-         * lands in that same gap; and then the tabs upgrade, `slotchange` pairs them,
-         * nothing measures, and nothing ever will again, because the host's size
-         * never changes.
-         *
-         * Invisible in every example, because a tab strip that is only tabs is
-         * exactly as tall as its tabs, so a mark at the top of the strip is a mark on
-         * the tab. It shows only where something gives the strip a height of its own.
-         */
         this.handleSlotChange = () => {
             this.sync();
             this.watch();
@@ -102,19 +39,12 @@ let HelixHeadlessTabs = class HelixHeadlessTabs extends MixinControllerActive(He
     get panels() {
         return [...this.children].filter((child) => child instanceof HelixHeadlessTabPanel);
     }
-    /** Pushes the current value down to whichever tab and panel own it. */
     sync() {
         const tabs = this.tabs;
-        /* Through the mixin, which also skips a disabled first tab. A hand-written
-           fallback to the first child shows a disabled tab as current and opens its
-           panel with it. */
         const value = this.resolveActive(tabs)?.value ?? '';
         for (const tab of tabs) {
             tab.selected = tab.value === value;
         }
-        /* The panel's name comes from its tab, and only this element sees both.
-           Read from the tab's light DOM, which is where the consumer wrote the
-           words, so it is whatever the reader sees on the tab. */
         const names = new Map(tabs.map((tab) => [tab.value, (tab.textContent ?? '').trim()]));
         for (const panel of this.panels) {
             panel.selected = panel.value === value;
@@ -124,14 +54,6 @@ let HelixHeadlessTabs = class HelixHeadlessTabs extends MixinControllerActive(He
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('helix-select', this.handleSelection);
-        /* The observer is rebuilt here, because nothing else does it.
-         *
-         * `firstUpdated` runs once for the life of the element and
-         * `disconnectedCallback` runs every time it moves, so a framework
-         * reordering a list left this permanently dead: the observer gone, nothing
-         * to rebuild it, and the component still rendering as though it were
-         * watching. Guarded on `hasUpdated`, because the first connection happens
-         * before the first render and there is nothing to watch yet. */
         if (this.hasUpdated) {
             this.measure();
             this.watch();
@@ -146,36 +68,16 @@ let HelixHeadlessTabs = class HelixHeadlessTabs extends MixinControllerActive(He
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.sync();
-        /* Straight away, and again after a frame. The first call is what places it
-           in a document that is already laid out; the second covers a first paint
-           that has not happened yet, where every tab measures zero and `place`
-           refuses rather than writing a wrong position.
-    
-           Not the frame alone: `requestAnimationFrame` does not run in a document
-           the browser is not painting, so a tab set rendered in a hidden tab or an
-           inactive pane would never place its mark at all and would slide in from
-           the origin the moment the page was looked at. */
         this.indicator.place();
         requestAnimationFrame(() => this.indicator.place());
         this.measure();
         this.watch();
     }
-    /** The host's own size, which moves every tab and therefore the mark. */
     measure() {
         this.observer?.disconnect();
         this.observer = new ResizeObserver(() => this.indicator.place());
         this.observer.observe(this);
     }
-    /**
-     * Watches every tab for a change of size.
-     *
-     * Called again whenever the set changes, because `tabs` reads `this.children`
-     * and filters on `instanceof`, so it is empty until the tab elements upgrade.
-     * At `firstUpdated` it frequently is empty, and observing nothing is silent.
-     *
-     * `observe` is idempotent per element, so re-running this costs nothing and
-     * needs no bookkeeping about which tabs are already watched.
-     */
     watch() {
         for (const tab of this.tabs) {
             this.observer?.observe(tab);

package/dist/tabs/tab/tab.js

@@ -7,86 +7,27 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, HelixSelectEvent } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary One tab in a tab list.
- *
- * @description
- * An element rather than a slot because it owns selection and its own tab stop.
- *
- * Its id and the id it controls are both derived from `value`, so the pairing
- * between a tab and its panel survives server rendering. A generated id would
- * differ between the server's render and the client's and break the link, and
- * `aria-controls` pointing at nothing is worse than not being there.
- *
- * @since 0.1.0
- * @status experimental
- * @aliases Tab
- * @documentation https://helix.fusion.dev/components/tabs
- *
- * @slot - The tab's label.
- *
- * @event {HelixSelectEvent} helix-select - Fired when the tab is chosen. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart tab - The tab itself.
- */
 let HelixHeadlessTab = class HelixHeadlessTab extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether the tab can be chosen.
-         */
         this.disabled = false;
-        /**
-         * Whether this tab is the current one.
-         */
         this.selected = false;
-        /**
-         * Identifies the tab, and pairs it with the panel of the same value.
-         */
         this.value = '';
     }
-    /** Moves focus to this tab, for the list's arrow keys. */
     focusItem() {
         this.renderRoot.querySelector('[part="tab"]')?.focus();
     }
-    /** Selects this tab and announces it. */
     select() {
         if (this.disabled) {
             return;
         }
         this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
     }
-    /**
-     * Mirrors the chosen state where a stylesheet can select on it.
-     *
-     * **A custom state, not a reflected `selected` attribute.** The parent writes
-     * this: a listbox choosing a row, a tab strip moving the tab, a radio group
-     * answering for its set. Reflected, it puts the element's own bookkeeping onto
-     * markup a consumer wrote and a consumer's server never sent, which React
-     * reconciles and reports as a mismatch, and which a serialized element pasted
-     * back declares as a choice nobody made. `ElementInternals` holds it instead,
-     * where it is not in the DOM at all.
-     *
-     * Reading `selected` is unaffected and so is writing it: the attribute still
-     * seeds the property, which is what `<helix-tab selected>` in a consumer's
-     * markup means. What stops is the write back.
-     */
     willUpdate(changed) {
         super.willUpdate(changed);
         this.toggleState('selected', this.selected);
     }
     render() {
-        /* No `aria-controls`, and no id for one to point at.
-         *
-         * An IDREF resolves only within the tree it is written in, and the panel's
-         * id is rendered inside the panel's *own* shadow root, so an `aria-controls`
-         * here would point at nothing on every tab.
-         *
-         * There is no id form that could work and no element reference either: a
-         * reference is valid only into the same tree or a shadow-including ancestor
-         * of it, and the panel's shadow root is neither, it is a sibling. The
-         * relationship a reader actually needs is the panel's name, and the panel
-         * takes that as a string, which crosses anything. */
         return html `<button
       part="tab"
       role="tab"

package/dist/tag/root/tag-root.js

@@ -8,40 +8,9 @@ import { customElement, HelixElement, MixinDismissible } from '@fusion.dev/helix
 import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/**
- * @summary Labels content with a short piece of metadata.
- *
- * @description
- * A tag is a label, and optionally a label the reader can take off.
- * `dismissible` is what separates it from a badge: a badge reports a state the
- * reader cannot change, a tag names something they can.
- *
- * Dismissing is a request. The tag does not remove itself, because the consumer
- * owns the list it sits in and taking the node out from under them would put
- * their state and the document out of step. Canceling `helix-dismiss` is a
- * refusal.
- *
- * @since 0.1.0
- * @status stable
- * @category markers
- * @aliases Chip, Pill, Label
- * @documentation https://helix.fusion.dev/components/tag
- *
- * @slot - The tag's label.
- * @slot prefix - A category the label belongs to, set before it and weightier.
- *
- * @event {HelixDismissEvent} helix-dismiss - Fired when the reader asks to remove the tag. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart dismiss - The control that asks to remove the tag.
- * @csspart dismiss-mark - The glyph on the dismiss control, where none is slotted.
- * @csspart prefix - The category before the label.
- */
 let HelixHeadlessTag = class HelixHeadlessTag extends MixinDismissible(HelixElement) {
     constructor() {
         super(...arguments);
-        /* "Remove" rather than the mixin's "Dismiss". A tag is taken out of a set,
-           which is a different act from closing a message, and the control's name is
-           what a screen-reader user hears. */
         this.dismissLabel = 'Remove';
     }
     render() {