@fusion.dev/helix-headless 0.0.0-dev

package/dist/button-group/root/button-group-root.d.ts

@@ -0,0 +1,62 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary Groups related buttons into one control.
+ *
+ * @description
+ * The host is the group, so `role="group"` sits on it through internals and
+ * `label` names it. A group of buttons with no name is announced as a run of
+ * separate controls, which is what the grouping exists to say it is not.
+ *
+ * It manages no focus. A group is not a toolbar: the APG toolbar pattern asks
+ * for one tab stop with arrow keys inside it, and that is what Toolbar is for.
+ * Here every button keeps its own tab stop, which is what a reader expects from
+ * buttons sitting side by side.
+ *
+ * Buttons are slotted rather than wrapped, so they stay the consumer's own
+ * elements and keep whatever appearance and size they were given.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category actions
+ * @aliases Segmented buttons, Split button
+ * @documentation https://helix.fusion.dev/components/button-group
+ *
+ * @slot - The buttons in the group.
+ */
+export declare class HelixHeadlessButtonGroup extends HelixElement {
+    /**
+     * Accessible name for the group.
+     *
+     * On the host through internals, so an author's `aria-label` still overrides
+     * it and nothing lands on the host that a consumer's markup did not have.
+     */
+    label: string;
+    /**
+     * Which way the buttons are stacked.
+     *
+     * Unset is a row and stays unset, so a reflected default cannot appear on a
+     * host whose server output never had it.
+     *
+     * **A property and not an `auto`, which the splitter and the carousel earned
+     * and this has not.** Turning those two changes what they *do*: a drag axis,
+     * arrow keys, how many slides a page holds. A group of buttons turning is
+     * paint, so there is no state to resolve and nothing to observe; what it needs
+     * is for a consumer who knows the column is narrow to be able to say so.
+     *
+     * **What it is for, measured.** Three buttons at 320 come to 322 and overflow
+     * the page by 26. A row of joined buttons cannot answer that by wrapping,
+     * which is the obvious reach and the wrong one: the group's whole contract is
+     * buttons sharing edges as one shape, and a wrapped row carries the corners of
+     * a first row into a second. Stacked, the same three keep one shape and one
+     * column.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-button-group': HelixHeadlessButtonGroup;
+    }
+}

package/dist/button-group/root/button-group-root.js

@@ -0,0 +1,62 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary Groups related buttons into one control.
+ *
+ * @description
+ * The host is the group, so `role="group"` sits on it through internals and
+ * `label` names it. A group of buttons with no name is announced as a run of
+ * separate controls, which is what the grouping exists to say it is not.
+ *
+ * It manages no focus. A group is not a toolbar: the APG toolbar pattern asks
+ * for one tab stop with arrow keys inside it, and that is what Toolbar is for.
+ * Here every button keeps its own tab stop, which is what a reader expects from
+ * buttons sitting side by side.
+ *
+ * Buttons are slotted rather than wrapped, so they stay the consumer's own
+ * elements and keep whatever appearance and size they were given.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category actions
+ * @aliases Segmented buttons, Split button
+ * @documentation https://helix.fusion.dev/components/button-group
+ *
+ * @slot - The buttons in the group.
+ */
+let HelixHeadlessButtonGroup = class HelixHeadlessButtonGroup extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Accessible name for the group.
+         *
+         * On the host through internals, so an author's `aria-label` still overrides
+         * it and nothing lands on the host that a consumer's markup did not have.
+         */
+        this.label = '';
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label, role: 'group' });
+    }
+    render() {
+        return html `<slot></slot>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessButtonGroup.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessButtonGroup.prototype, "orientation", void 0);
+HelixHeadlessButtonGroup = __decorate([
+    customElement('helix-headless-button-group')
+], HelixHeadlessButtonGroup);
+export { HelixHeadlessButtonGroup };

package/dist/callout/index.d.ts

@@ -0,0 +1 @@
+export * from './root/callout-root.js';

package/dist/callout/index.js

@@ -0,0 +1 @@
+export * from './root/callout-root.js';

package/dist/callout/root/callout-root.d.ts

@@ -0,0 +1,72 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary Sets a passage apart as information, a warning, or an error.
+ *
+ * @description
+ * `tone` lives on the headless tier rather than being a treatment on the styled
+ * one, because it is meaning and not decoration. It picks the icon and that
+ * icon's accessible name, so a reader who cannot see that the box is red still
+ * hears "Error". A callout whose meaning existed only as a color would say
+ * nothing to them at all.
+ *
+ * The icon is the fallback content of a slot, so a consumer replaces it by
+ * slotting their own and the default disappears with no emptiness check. That
+ * is what slot fallback is for.
+ *
+ * Not an `Announcement`, which is the other thing this could be mistaken for.
+ * A callout interrupts a document to set a passage apart and is read where it
+ * sits; an announcement is page-level chrome above the masthead, announces
+ * itself as a live region, and can be dismissed. Neither is a variant of the
+ * other.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category markers
+ * @aliases Admonition, Notice, Note, Alert
+ * @documentation https://helix.fusion.dev/components/callout
+ *
+ * @slot - The callout's content.
+ * @slot icon - Replaces the icon chosen by `tone`.
+ * @slot title - A heading above the content.
+ *
+ * @csspart content - The content region.
+ * @csspart icon - The icon region.
+ * @csspart icon-mark - The tone glyph, where none is slotted.
+ */
+export declare class HelixHeadlessCallout extends HelixElement {
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * What kind of attention the passage needs.
+     *
+     * **`severity` was a sixth spelling of `tone`**, which is the axis for what a
+     * thing means, and a subset of it: a callout reports a status and never a
+     * brand role, so it takes four of the seven. One word per axis is the whole
+     * of the registry, and two words for one axis is how `tone` had drifted into
+     * five incompatible value sets before anything held it.
+     */
+    tone?: 'danger' | 'info' | 'success' | 'warning';
+    /**
+     * The mark for the callout's tone, behind a seam.
+     *
+     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
+     * tier above replaces it by overriding. Those answer different people: the
+     * slot is for the page and the method is for whoever is building the styled
+     * layer, and a fallback with only the first is one a tier can restyle and
+     * cannot change.
+     *
+     * The mark and its label are passed in rather than looked up again, since
+     * `render` has already resolved the tone and a second lookup is a second
+     * place for the fallback to disagree with the tone around it.
+     */
+    protected renderIcon(icon: {
+        content: string;
+        viewBox: string;
+    }, label: string): TemplateResult;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-callout': HelixHeadlessCallout;
+    }
+}

package/dist/callout/root/callout-root.js

@@ -0,0 +1,90 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement, hostAria, TONE_MARKS, toneMark } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+/**
+ * @summary Sets a passage apart as information, a warning, or an error.
+ *
+ * @description
+ * `tone` lives on the headless tier rather than being a treatment on the styled
+ * one, because it is meaning and not decoration. It picks the icon and that
+ * icon's accessible name, so a reader who cannot see that the box is red still
+ * hears "Error". A callout whose meaning existed only as a color would say
+ * nothing to them at all.
+ *
+ * The icon is the fallback content of a slot, so a consumer replaces it by
+ * slotting their own and the default disappears with no emptiness check. That
+ * is what slot fallback is for.
+ *
+ * Not an `Announcement`, which is the other thing this could be mistaken for.
+ * A callout interrupts a document to set a passage apart and is read where it
+ * sits; an announcement is page-level chrome above the masthead, announces
+ * itself as a live region, and can be dismissed. Neither is a variant of the
+ * other.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category markers
+ * @aliases Admonition, Notice, Note, Alert
+ * @documentation https://helix.fusion.dev/components/callout
+ *
+ * @slot - The callout's content.
+ * @slot icon - Replaces the icon chosen by `tone`.
+ * @slot title - A heading above the content.
+ *
+ * @csspart content - The content region.
+ * @csspart icon - The icon region.
+ * @csspart icon-mark - The tone glyph, where none is slotted.
+ */
+let HelixHeadlessCallout = class HelixHeadlessCallout extends HelixElement {
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        // On the host, since the host is the box.
+        hostAria(this.internals, { role: 'note' });
+    }
+    /**
+     * The mark for the callout's tone, behind a seam.
+     *
+     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
+     * tier above replaces it by overriding. Those answer different people: the
+     * slot is for the page and the method is for whoever is building the styled
+     * layer, and a fallback with only the first is one a tier can restyle and
+     * cannot change.
+     *
+     * The mark and its label are passed in rather than looked up again, since
+     * `render` has already resolved the tone and a second lookup is a second
+     * place for the fallback to disagree with the tone around it.
+     */
+    renderIcon(icon, label) {
+        return html `<slot name="icon">
+      <svg part="icon-mark" fill="currentColor" viewBox=${icon.viewBox} role="img" aria-label=${label}>
+        ${unsafeSVG(icon.content)}
+      </svg>
+    </slot>`;
+    }
+    render() {
+        /* Falls back to `info`, because a callout exists to set a passage apart and
+           is therefore always *about* something. `Toast.Item` takes the same lookup
+           and draws nothing instead, since a message is just the next thing that
+           happened. Same vocabulary, two honest answers to an absent tone. */
+        const { icon, label } = toneMark(this.tone) ?? TONE_MARKS.info;
+        return html `<span part="icon">${this.renderIcon(icon, label)}</span>
+      <div part="content">
+        <slot name="title"></slot>
+        <slot></slot>
+      </div>`;
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessCallout.prototype, "tone", void 0);
+HelixHeadlessCallout = __decorate([
+    customElement('helix-headless-callout')
+], HelixHeadlessCallout);
+export { HelixHeadlessCallout };

package/dist/card/index.d.ts

@@ -0,0 +1 @@
+export * from './root/card-root.js';

package/dist/card/index.js

@@ -0,0 +1 @@
+export * from './root/card-root.js';

package/dist/card/root/card-root.d.ts

@@ -0,0 +1,54 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary Groups related content and actions into a single surface.
+ *
+ * @description
+ * Regions are slots rather than separate elements, because a header, body, and
+ * footer carry no state, no behavior, and no API of their own. Slotting them
+ * costs one custom element instead of five and lets the consumer bring their
+ * own markup, so a title can be a real `<h2>` rather than an emulated one.
+ *
+ * The host is the surface. A wrapper `<div part="container">` would be a second
+ * box doing nothing the host cannot: the element itself takes the border, the
+ * radius, and the grid, and a consumer styles `helix-card` rather than reaching
+ * through `::part`. One node instead of two, on every card on the page.
+ *
+ * Name the card with `aria-label` or `aria-labelledby`. That is the only
+ * naming that survives server rendering: reading a title out of the light DOM
+ * needs a DOM, and the server has none.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category layout
+ * @aliases Panel, Surface
+ * @documentation https://helix.fusion.dev/components/card
+ *
+ * @slot - The card's main content.
+ * @slot footer - Actions that conclude the card.
+ * @slot header - Title and any actions for the whole card.
+ * @slot media - Image, video, or chart that runs edge to edge, outside the inset.
+ */
+export declare class HelixHeadlessCard extends HelixElement {
+    /**
+     * Puts the media after the content instead of before it.
+     *
+     * **A figure that concludes a card is the same region as one that opens it**,
+     * and the only thing that differs is which edge it is flush against. Media is
+     * the one region that escapes the inset, so a chart wanting to span the card
+     * has nowhere else to be: slotted into the content it keeps the padding on
+     * both sides, and there is no second bleeding region to add without saying
+     * twice what this says once.
+     *
+     * Reflected and undefaulted, so a card that has not asked reads as a card
+     * with no attribute on it and the stylesheet only describes the departure.
+     */
+    mediaPlacement?: 'end';
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-card': HelixHeadlessCard;
+    }
+}

package/dist/card/root/card-root.js

@@ -0,0 +1,71 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary Groups related content and actions into a single surface.
+ *
+ * @description
+ * Regions are slots rather than separate elements, because a header, body, and
+ * footer carry no state, no behavior, and no API of their own. Slotting them
+ * costs one custom element instead of five and lets the consumer bring their
+ * own markup, so a title can be a real `<h2>` rather than an emulated one.
+ *
+ * The host is the surface. A wrapper `<div part="container">` would be a second
+ * box doing nothing the host cannot: the element itself takes the border, the
+ * radius, and the grid, and a consumer styles `helix-card` rather than reaching
+ * through `::part`. One node instead of two, on every card on the page.
+ *
+ * Name the card with `aria-label` or `aria-labelledby`. That is the only
+ * naming that survives server rendering: reading a title out of the light DOM
+ * needs a DOM, and the server has none.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category layout
+ * @aliases Panel, Surface
+ * @documentation https://helix.fusion.dev/components/card
+ *
+ * @slot - The card's main content.
+ * @slot footer - Actions that conclude the card.
+ * @slot header - Title and any actions for the whole card.
+ * @slot media - Image, video, or chart that runs edge to edge, outside the inset.
+ */
+let HelixHeadlessCard = class HelixHeadlessCard extends HelixElement {
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        // On the host, since the host is the box. Set here rather than in
+        // `connectedCallback`, which the server never calls.
+        hostAria(this.internals, { role: 'group' });
+    }
+    render() {
+        // Bare slots, with no wrapper element around any of them. A `<slot>` is
+        // `display: contents` in the UA stylesheet, so an unassigned one generates
+        // no box at all: no grid row, no gap, nothing. A wrapper generates one
+        // whether or not anything is slotted into it, so an omitted region would
+        // paint an empty inset band.
+        //
+        // It has to be layout rather than detection, because the detection does not
+        // exist. `:host(:has([slot='header']))` is invalid CSS, so the whole rule is
+        // dropped and the region stays hidden even when filled, and the component
+        // cannot inspect its children on the server to do it in JavaScript.
+        return html `
+      <slot name="media"></slot>
+      <slot name="header"></slot>
+      <slot></slot>
+      <slot name="footer"></slot>
+    `;
+    }
+};
+__decorate([
+    property({ attribute: 'media-placement', reflect: true })
+], HelixHeadlessCard.prototype, "mediaPlacement", void 0);
+HelixHeadlessCard = __decorate([
+    customElement('helix-headless-card')
+], HelixHeadlessCard);
+export { HelixHeadlessCard };

package/dist/carousel/index.d.ts

@@ -0,0 +1 @@
+export * from './root/carousel-root.js';

package/dist/carousel/index.js

@@ -0,0 +1 @@
+export * from './root/carousel-root.js';