@fusion.dev/helix-headless 0.1.0 → 0.3.0

package/dist/command/root/command-root.js

@@ -7,19 +7,8 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, HelixSelectEvent, MixinControllerOpen, } from '@fusion.dev/helix-core';
 import { property, state } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
-/* Side-effect imports, because this renders both in its own shadow root and a
-   custom element registers on import. The paths are relative, so this registers
-   the base pair and the styled file's identical imports register the styled
-   pair; `tier` picks which names the template asks for. */
 import '../../dialog/index.js';
 import '../../listbox/index.js';
-/**
- * A hotkey, as the pieces a `keydown` can be compared against.
- *
- * `mod` is the platform's own: Command on a Mac and Control everywhere else,
- * which is what every application means by it and what a consumer would
- * otherwise have to detect and write twice.
- */
 const parse = (hotkey) => {
     const parts = hotkey.toLowerCase().split('+');
     return {
@@ -29,105 +18,14 @@ const parse = (hotkey) => {
         shift: parts.includes('shift'),
     };
 };
-/**
- * @summary A list of commands, opened from anywhere and filtered by typing.
- *
- * @description
- * **The list is `helix-listbox`, filtering and all.** Listbox already owns
- * narrowing, the empty state, the highlight over what matched,
- * `aria-activedescendant`, scrolling an option into view and the keyboard that
- * moves between them. Its own note says a command palette is that list again
- * with something different opening it, and this is that something: a dialog,
- * and a key that summons it.
- *
- * **The value is not kept.** A palette runs a command and forgets it: nothing
- * here is a form control and nothing is submitted, so what it reports is that
- * an option was chosen, once, with `helix-select`. A consumer that wants the
- * last command remembered is a consumer with somewhere better to keep it.
- *
- * **The hotkey is global and the element does not have to be open to hear it.**
- * The listener is on the document, because the point of a palette is that it
- * answers from wherever the reader is, including from inside another control's
- * text field. `mod` is Command on a Mac and Control elsewhere, resolved here so
- * a consumer writes one thing.
- *
- * The filter is emptied as the palette closes, for the reason Combobox and
- * Select both record: a control reopened still narrowed by the last visit's
- * search is one whose second use starts from the first one's leftovers, and a
- * palette is used far more often than either.
- *
- * @since 0.1.0
- * @status stable
- * @category navigation
- * @aliases Command palette, Quick open, Spotlight
- * @documentation https://helix.fusion.dev/components/command
- *
- * @slot - The commands, which are `helix-option` elements and their groups.
- * @slot footer - Under the list, for the keys a reader can press.
- *
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the palette opens. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixSelectEvent} helix-select - Fired when a command is chosen. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
- *
- * @csspart dialog - The overlay's own box, forwarded from the dialog.
- * @csspart footer - The row under the list.
- * @csspart listbox - The list inside it.
- * @csspart listbox-empty - Shown when a filter has hidden everything.
- * @csspart listbox-feedback - What is wrong with it.
- * @csspart listbox-filter-icon - The mark beside that field.
- * @csspart listbox-filter-mark - The glyph beside the filter field, where none is slotted.
- * @csspart listbox-hint - Help under the list.
- * @csspart listbox-items - The list itself.
- * @csspart listbox-label - The question, over the list.
- * @csspart listbox-loading - Shown while the options are still on their way.
- * @csspart listbox-search - The region holding the field that narrows the list.
- * @csspart listbox-search-field - The field itself.
- */
 let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Words shown where the filter has matched nothing.
-         */
         this.emptyText = 'No commands';
-        /**
-         * The key that opens it, as `mod+k` or `shift+p` or plain `k`.
-         *
-         * Empty turns it off, for a consumer who opens the palette from a button or
-         * from their own shortcut handler. There is no list of defaults to fight
-         * with: one key, said once.
-         */
         this.hotkey = 'mod+k';
-        /**
-         * Accessible name for the overlay, which has no visible heading.
-         */
         this.label = 'Commands';
-        /**
-         * Shown in the field before anything is typed.
-         */
         this.placeholder = 'Search commands';
-        /**
-         * Whether the consumer put anything under the list.
-         *
-         * Asked of the slot rather than of CSS. A wrapper holding a slot always has a
-         * child element, which is the slot, so `:not(:has(*))` on it is never true
-         * and an empty footer would draw its rule and its padding over nothing. Steps
-         * was caught by the same thing.
-         */
         this.footed = false;
-        /**
-         * Answers the hotkey from wherever the reader is.
-         *
-         * On the document rather than on this element, which is never the thing with
-         * focus: a palette that only answered when it already had focus would be a
-         * palette nobody could open.
-         *
-         * `preventDefault` because every key worth using is already the browser's.
-         * Command-K focuses the address bar in some browsers and opens a search in
-         * others, and a palette that opened underneath one of those would be a
-         * palette the reader never sees.
-         */
         this.handleHotkey = (event) => {
             if (this.hotkey === '') {
                 return;
@@ -143,14 +41,6 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
             event.preventDefault();
             this.requestOpen(!this.open);
         };
-        /**
-         * Takes what the list announced and says it under this element's name.
-         *
-         * The listbox says `helix-before-change`, which is the right word for a control that
-         * holds a value and the wrong one for a palette: nothing here changed, a
-         * command ran. It is stopped and re-announced rather than relayed, so a
-         * consumer hears one event naming the element they put on the page.
-         */
         this.handleChange = (event) => {
             event.stopPropagation();
             const { value } = event.detail;
@@ -159,26 +49,6 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
             }
             this.requestOpen(false);
         };
-        /**
-         * Takes the row's second destination, where the reader asked for it.
-         *
-         * **Command intercepts rather than Listbox reporting, and that is the whole
-         * design.** Enter belongs to the listbox: it owns the active row, it decides
-         * what choosing means, and it announces `helix-before-change`. Teaching it about a
-         * modifier would put a palette's idea of a second destination inside a
-         * control that is also a select and a combobox, neither of which has one.
-         *
-         * So this listens in the capture phase, before the listbox sees the key, and
-         * only for the one combination that means something here. Anything else falls
-         * straight through and the listbox behaves exactly as it always did.
-         *
-         * `mod` is Command on a Mac and Control elsewhere, which is what `hotkey`
-         * already means by it two methods up.
-         *
-         * The pointer takes the same path for the same reason: a modifier-click on a
-         * row is the same intent as a modifier-Enter on it, and both have to be
-         * stopped before the row announces its ordinary selection.
-         */
         this.handleAlternate = (event) => {
             if (!(event.metaKey || event.ctrlKey) || !this.open) {
                 return;
@@ -199,21 +69,6 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
                 this.requestOpen(false);
             }
         };
-        /*
-         * Keeps an option's own announcement inside the palette.
-         *
-         * Every option says `helix-select` when it is chosen, which is how the list
-         * hears it, and the options are light DOM children of this element, so it
-         * carries straight on out to the consumer: two selections for one command
-         * under one event name, told apart only by the target. The one this element
-         * dispatches has itself as the target and is let past.
-         *
-         * `stopImmediatePropagation`, not `stopPropagation`. The consumer's listener
-         * is on this same element, and stopping propagation only keeps an event off
-         * the *next* node, so every other listener already bound here still runs. The
-         * listbox hears it well before this, from inside the shadow root, so nothing
-         * this element needs is lost by ending it here.
-         */
         this.swallowOptionSelect = (event) => {
             if (event.target !== this) {
                 event.stopImmediatePropagation();
@@ -223,21 +78,12 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
     get listbox() {
         return this.renderRoot?.querySelector('[part="listbox"]') ?? null;
     }
-    /**
-     * The row under the keyboard, read from the attribute the listbox writes.
-     *
-     * `data-active` rather than a reference the listbox hands over, because the
-     * options are this element's own light DOM children and the attribute is
-     * already published: asking the listbox would mean a second channel saying
-     * what the markup says.
-     */
     get activeOption() {
         return this.querySelector('[data-active]');
     }
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('helix-select', this.swallowOptionSelect);
-        /* Capture, so both reach this before the listbox and the row do. */
         this.addEventListener('keydown', this.handleAlternate, { capture: true });
         this.addEventListener('click', this.handleAlternate, { capture: true });
         document.addEventListener('keydown', this.handleHotkey);
@@ -251,18 +97,10 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
     }
     updated(changed) {
         super.updated?.(changed);
-        /* On the change rather than on every update. Both of these reach into the
-           listbox, and asking it to filter on a render it did not cause is how a
-           render becomes a loop: the list updates, something it owns comes back
-           through this element, and the next update asks again. Only the moment the
-           palette opens or shuts is either of them true. */
         if (!changed.has('open')) {
             return;
         }
         if (this.open) {
-            /* The field takes focus as the palette arrives. A reader who pressed a
-               key to summon a search expects to be typing in it, and the dialog would
-               otherwise put focus on itself. */
             this.renderRoot
                 .querySelector('[part="listbox"]')
                 ?.renderRoot?.querySelector('[part="search-field"]')
@@ -272,16 +110,6 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
             this.listbox?.requestFilter('');
         }
     }
-    /**
-     * The surface the palette opens in, behind a seam the styled tier can move.
-     *
-     * A method rather than a fragment inline, so a tier above can render its own,
-     * wrap this one, pass it a property the base does not know about, or leave it
-     * out, without reimplementing the whole template to do any of them. The tag is
-     * interpolated rather than written, so `tier` resolves it: this renders the
-     * headless element, and a styled subclass that sets `tier` renders the styled one
-     * from the same template.
-     */
     renderDialog() {
         return html `<${this.tag('dialog')}
     exportparts="dialog"
@@ -320,11 +148,6 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
     </${this.tag('dialog')}>`;
     }
     render() {
-        /* No part of its own on the host, and the dialog's own box forwarded under
-           its own name: `::part(dialog)` then reaches the thing with the shadow and
-           the padding, rather than a host that is only a wrapper. `align` is not set
-           here either, being a styled-tier property: where the panel sits is
-           presentation, and this tier renders no CSS. */
         return html `${this.renderDialog()}`;
     }
 };

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

@@ -13,97 +13,13 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { html } from 'lit/static-html.js';
 import { HelixHeadlessIconButton } from '../../icon-button/root/icon-button-root.js';
 import '../../tooltip/index.js';
-/** How long the confirmation stands before the button goes back to itself. */
 const CONFIRM = 1600;
-/**
- * @summary A button that puts a string on the clipboard and says it did.
- *
- * @description
- * **The confirmation is the component.** Writing to the clipboard is three
- * lines; what makes this worth an element is that the platform gives a reader
- * no feedback at all. A press that copies and looks identical to a press that
- * failed is a control nobody trusts, so they press it again, and the second
- * press is indistinguishable from the first.
- *
- * **Announced after the write, never before.** A clipboard write is a
- * permission the browser may refuse, and it is refused for real reasons: an
- * insecure origin, a document that is not focused, a user agent that requires a
- * gesture this press did not qualify as. So the confirmation and the event both
- * wait for the promise, and a refusal leaves the button exactly as it was.
- * `HelixCopyEvent` is not cancelable for the same reason: by the time there is
- * anything to say, it has already happened.
- *
- * **An icon button, extending IconButton.** Both of this button's faces are
- * icons and it never carries a word, so it is the square control rather than a
- * text button that happens to hold a glyph: it inherits the square box, and
- * with it the rule that an icon-only control must be named. `label` is not
- * optional here for the same reason it is not optional there, and the two
- * faces make it sharper: the accessible name has to describe the press, not
- * whichever picture is showing when a reader arrives.
- *
- * `data-copied`, not a reflected `copied`. State never reflects here: a
- * serialized `copied` attribute would come back from a paste as a button
- * claiming to have copied something it never held.
- *
- * @since 0.1.0
- * @status experimental
- * @category actions
- * @aliases Copy, Copy to clipboard
- * @documentation https://helix.fusion.dev/components/copy-button
- *
- * @slot - The resting icon. Falls back to a clipboard.
- * @slot copied - What replaces it once the write succeeds. Falls back to a check.
- *
- * @event {HelixCopyEvent} helix-copy - Fired after the clipboard write succeeds.
- *
- * @csspart button - The inner button.
- * @csspart mark - The clipboard glyph, and the confirmation that replaces it.
- * @csspart tooltip - The bubble, forwarded from the tooltip inside.
- * @csspart tooltip-arrow - The point, resting against the trigger.
- */
 let HelixHeadlessCopyButton = HelixHeadlessCopyButton_1 = class HelixHeadlessCopyButton extends HelixHeadlessIconButton {
     constructor() {
         super(...arguments);
-        /**
-         * What it is called, and says, after one.
-         *
-         * `attribute` written out, because Lit lowercases a property name rather than
-         * dash-casing it, and `copiedlabel` is not what anyone would type.
-         */
         this.copiedLabel = 'Copied';
-        /**
-         * What it is called, and says, before a press.
-         *
-         * Defaulted rather than left empty. An icon-only control must be named, and
-         * the name of this one is not a judgment call: every copy button in the
-         * world is called Copy. A consumer with a better word still sets it.
-         */
         this.label = 'Copy';
-        /**
-         * What goes on the clipboard.
-         *
-         * **Narrows `Button.value`, which is the submit value, and the two agree.**
-         * A copy button is `type="button"` and never submits, so the inherited
-         * meaning has nothing to act on; where a consumer changes the type, what it
-         * submits is what it copies, which is the reading anybody would expect of one
-         * property called `value`. Declared here rather than inherited because the
-         * clipboard is what this component is about and its own page should say so.
-         */
         this.value = '';
-        /**
-         * The write, the confirmation, the timer and the event, all of them shared.
-         *
-         * **Never reach for `navigator.clipboard.writeText` directly.** It is inert in
-         * a sandboxed iframe without `allow-same-origin`, which is the sandbox every
-         * example on the docs site runs in, and guarding on the API existing does not
-         * help there: the object exists and the write rejects. A copy button that does
-         * nothing is indistinguishable from a broken one.
-         *
-         * The controller carries the `execCommand` fallback, checks the host is still
-         * connected after the await (writing is asynchronous, so `hostDisconnected`
-         * can run before there is a timer to clear), and registers itself so the timer
-         * is released without an override here.
-         */
         this.clipboard = new CopyController(this, { after: CONFIRM });
         this.handleCopy = async () => {
             if (this.isDisabled) {
@@ -112,32 +28,12 @@ let HelixHeadlessCopyButton = HelixHeadlessCopyButton_1 = class HelixHeadlessCop
             await this.clipboard.copy(this.value);
         };
     }
-    /**
-     * The words for the state it is in, used twice on purpose.
-     *
-     * The tooltip is the visible confirmation and the accessible name is the
-     * spoken one, and they have to be the same words. A tooltip that changes to
-     * Copied while the accessible name stays Copy tells a sighted reader it
-     * worked and leaves a screen reader user pressing a button that never
-     * acknowledges anything. Changing the name of the focused element is what
-     * makes the announcement happen at all.
-     */
     get says() {
         return this.copied ? this.copiedLabel : this.label;
     }
     get copied() {
         return this.clipboard.copied;
     }
-    /**
-     * Both faces, drawn rather than demanded.
-     *
-     * Slot fallback, which is this library's answer for content a component has a
-     * sensible default for: a copy button with no icons is not a copy button, and
-     * making every consumer slot the same clipboard is asking them to supply the
-     * one thing the component is sure about. Slotting anything replaces it, at
-     * assignment time, with no property to set and nothing for the server and the
-     * client to disagree about.
-     */
     static icon(glyph) {
         return html `<svg part="mark" fill="currentColor" viewBox=${glyph.viewBox} aria-hidden="true">
       ${unsafeSVG(glyph.content)}
@@ -155,45 +51,15 @@ let HelixHeadlessCopyButton = HelixHeadlessCopyButton_1 = class HelixHeadlessCop
       ${this.renderCopiedIcon()} ${this.renderCopyIcon()}
       </button>`);
     }
-    /**
-     * The mark for the resting state, behind a seam a tier can move.
-     *
-     * Two seams and not one taking the state, because the two marks are two
-     * decisions: a tier changing the clipboard for a house glyph has no reason to
-     * touch the confirmation, and the stylesheet already treats them separately,
-     * the check holding its green through a hover where this one does not.
-     */
     renderCopyIcon() {
         return html `<slot ?hidden=${this.copied}>${HelixHeadlessCopyButton_1.icon(copy)}</slot>`;
     }
-    /**
-     * The mark for the moment after a press, behind a seam of its own.
-     *
-     * Both slots render and CSS shows one, which is why this is a slot rather
-     * than a branch: swapping which slot exists would unassign the consumer's
-     * content on every press, and an element that leaves and re-enters the tree
-     * loses focus with it, so the button a reader just pressed would stop being
-     * the focused element mid-press.
-     */
     renderCopiedIcon() {
         return html `<slot name="copied" ?hidden=${!this.copied}
       >${HelixHeadlessCopyButton_1.icon(check)}</slot
     >`;
     }
-    /**
-     * The bubble the control sits inside, behind a seam.
-     *
-     * It takes the control rather than rendering it, because this one wraps: a
-     * tier above overriding it can drop the tooltip entirely and return the
-     * button, put something else around it, or keep the tooltip and change only
-     * how it is anchored, and every one of those is a normal thing to want.
-     * Rendering the button here as well would make all three a rewrite.
-     */
     renderTooltip(control) {
-        /* `persist`, because this bubble is the confirmation rather than a hint
-           about it. Without it the tooltip hid on the same click that swapped its
-           content to Copied, so the words this component takes such care over were
-           written and then taken off screen in the same frame. */
         return html `<${this.tag('tooltip')} content=${this.says} persist
     exportparts="arrow: tooltip-arrow, tooltip">
       ${control}