@fusion.dev/helix-headless 0.144.0 → 0.146.0

package/dist/number-input/root/number-input-root.d.ts

@@ -25,9 +25,10 @@ declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@f
  * The locale's group separators are read in every field, so `1,234` is a
  * number in `en-US`.
  *
- * On iOS and iPadOS the field is a text field described as a number field,
- * with no `role="spinbutton"`, which VoiceOver reads as a slider you cannot
- * type in. React Aria's NumberField does the same.
+ * On iOS and iPadOS the field is a plain text field, with no
+ * `role="spinbutton"`, which VoiceOver reads as a slider you cannot type in,
+ * and no role description, so VoiceOver says the field is required. React
+ * Aria's NumberField does the same.
  *
  * Validity follows the platform's rules: `min`, `max`, and `step` are checked
  * and reported through the host's own `setValidity`, under the platform's flag
@@ -36,6 +37,19 @@ declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@f
  * Stepping is separate from typing, so a number is not corrected while you type
  * it.
  *
+ * **Keyboard.** The field is one tab stop, and the stepper buttons are not in
+ * the tab order.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Up, Down | Steps the value up or down by `step`. |
+ * | Page Up, Page Down | Steps by `large-step` steps, ten by default. |
+ * | Home, End | Goes to `min` or `max`, where there is one. Without one, moves the caret. |
+ * | Enter | Commits the typed number and submits the form, as a native field does. |
+ *
+ * The field has `role="spinbutton"` with `aria-valuenow`, `aria-valuemin`,
+ * `aria-valuemax`, and the formatted text in `aria-valuetext`.
+ *
  * @since 0.1.0
  * @status stable
  * @category forms
@@ -154,11 +168,6 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
      * Prevents editing. The value is still submitted with the form.
      */
     readOnly: boolean;
-    /**
-     * What the field is described as on iOS and iPadOS, where it carries no
-     * spinbutton role. See the class description.
-     */
-    roleDescription: string;
     /**
      * Makes the label a grip that changes the value when it is dragged.
      *

package/dist/number-input/root/number-input-root.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 { AriaForwardController, appleTouch, valueAsNumber as asNumber, customElement, fillTemplate, formatNumber, numberAsValue as fromNumber, HelixFormElement, holdCaret, MixinControllerValue, MixinField, parseNumber, restoreValue, } from '@fusion.dev/helix-core';
+import { AriaForwardController, appleTouch, valueAsNumber as asNumber, customElement, fillTemplate, formatNumber, numberAsValue as fromNumber, HelixFormElement, holdCaret, MixinControllerValue, MixinField, parseNumber, restoreValue, submitImplicitly, } from '@fusion.dev/helix-core';
 import { minus, plus } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -24,7 +24,6 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         this.locale = '';
         this.placeholder = '';
         this.readOnly = false;
-        this.roleDescription = 'number field';
         this.scrub = false;
         this.step = 1;
         this.valueText = '';
@@ -138,7 +137,7 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         };
         this.handleKeypress = (event) => {
             if (event.key === 'Enter' && !event.defaultPrevented) {
-                this.submitImplicitly();
+                submitImplicitly(this.form);
             }
         };
     }
@@ -317,7 +316,6 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
           .value=${this.shown}
           type="text"
           role=${this.touchApple ? nothing : 'spinbutton'}
-          aria-roledescription=${this.touchApple ? this.roleDescription : nothing}
           inputmode="decimal"
           autocomplete=${this.autocomplete || nothing}
           name=${this.name || nothing}
@@ -411,9 +409,6 @@ __decorate([
 __decorate([
     property({ attribute: 'readonly', reflect: true, type: Boolean })
 ], HelixHeadlessNumberInput.prototype, "readOnly", void 0);
-__decorate([
-    property({ attribute: 'role-description' })
-], HelixHeadlessNumberInput.prototype, "roleDescription", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessNumberInput.prototype, "scrub", void 0);

package/dist/object-inspector/root/object-inspector-root.d.ts

@@ -1,18 +1,7 @@
 import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../copy-button/index.js';
-/** One visible line of the tree: a value, where it sits, and whether it is open. */
-interface Row {
-    branch: boolean;
-    depth: number;
-    /** The property name or array index this value is under; absent for the root. */
-    key?: string;
-    open: boolean;
-    path: string;
-    position: number;
-    siblings: number;
-    value: unknown;
-}
+import { type Row } from '../rows.js';
 /**
  * @summary A structured value shown as a tree, where you can close branches,
  * see how many entries each holds, and copy any part.
@@ -26,13 +15,45 @@ interface Row {
  * works with server rendering and with React hydration, which skips object
  * properties. `value` wins when both are set.
  *
- * The tree is one tab stop. Up and Down move between rows, Right opens a branch
- * or moves into it, Left closes it or moves to its parent, and Home and End
- * move to the first and last rows. Typing moves to the next row whose key
- * starts with what was typed, and `*` opens every branch beside the active
- * row. Focus stays on the tree, and `aria-activedescendant` marks the active
- * row. Each row carries its real level, position, and set size, including in
- * a windowed tree.
+ * **Keyboard.** The tree is one tab stop, and focus moves from row to row.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Down, Up | Moves to the next or the previous row. |
+ * | Right | Opens a closed branch, or moves into an open one. Left on a right-to-left page. |
+ * | Left | Closes an open branch, or moves to the parent. Right on a right-to-left page. |
+ * | Home, End | Moves to the first or the last row. |
+ * | Enter, Space | Opens or closes a branch. |
+ * | `*` | Opens every branch beside the active row. |
+ * | A letter or a word | Moves to the next row whose key starts with what you typed. |
+ * | Command+C, Control+C | Copies the active row, where no text is selected. |
+ *
+ * The tree is a `treegrid`, as React Aria's Tree is: each entry is a `row` with
+ * one cell, and carries its real level, position, and set size, including in a
+ * windowed tree. Nothing in it is chosen, so no row carries `aria-selected`,
+ * and a focused row is not announced as selected.
+ *
+ * A reader opening or closing a branch sends `helix-before-open` or
+ * `helix-before-close`, which you can cancel, and then `toggle` with
+ * `newState` and `oldState`, as `<details>` does. The branch is the active
+ * row, and `expanded` holds every open branch. `*` asks once for all the
+ * branches it opens. A script writing `expanded` or `active` sends nothing.
+ *
+ * `active` is the active row's path, written the way a JSON Pointer writes it:
+ * the empty string for the root and `/meta/tags/0` for an entry under it.
+ * Moving to another row sends `helix-before-activate`, which you can cancel,
+ * and then `helix-activate`, both with the path. Writing `active` moves there
+ * and opens the branches around it, and sends nothing. `expanded` holds the
+ * open branches by path, and writing it opens those and closes the rest. A row
+ * that closes around the active one hands it to the nearest open branch.
+ *
+ * `filter` narrows the tree to the entries whose key or value holds the text,
+ * ignoring case, and the branches that lead to them, which it opens. A matched
+ * branch keeps everything under it. Each matched row carries `row-match`, and
+ * a screen reader hears how many entries matched from `result-label` and
+ * `results-label`. `filterable` adds a field that sets it: typing sends
+ * `helix-filter`, which you can cancel, and then `helix-filtered`, and Down
+ * moves from the field to the tree.
  *
  * A new `value` keeps the branches a reader opened or closed, and the active
  * row, where the new value still has them. A branch the old value did not have
@@ -53,7 +74,14 @@ interface Row {
  * @aliases JSON viewer, Object viewer, Inspector, Data explorer
  * @documentation https://fusion.dev/helix/components/object-inspector
  *
+ * @event {HelixActivateEvent} helix-activate - The active row moved, by a key or a click. The detail's `value` is its path.
+ * @event {HelixBeforeActivateEvent} helix-before-activate - The active row is about to move, with its new path. Cancelable: cancel it to keep the row where it is.
+ * @event {HelixBeforeCloseEvent} helix-before-close - A reader is about to close the active branch. Cancelable: cancel it to keep the branch open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - A reader is about to open the active branch, or `*` the branches beside it. Cancelable: cancel it to keep them closed.
  * @event {HelixCopyEvent} helix-copy - A value was put on the clipboard, from the copy button or the keyboard.
+ * @event {HelixFilterEvent} helix-filter - Text was typed in the filter field, with what it now holds. Cancelable: cancel it to keep the filter as it was.
+ * @event {HelixFilteredEvent} helix-filtered - The filter field changed `filter`, which now holds the text.
+ * @event {ToggleEvent} toggle - A reader opened or closed a branch, with `newState` and `oldState`. `expanded` holds every open branch.
  *
  * @csspart after - The space the rows below the drawn rows would take, when `windowed` is set.
  * @csspart before - The space the rows above the drawn rows would take, when `windowed` is set.
@@ -78,18 +106,32 @@ interface Row {
  * @csspart header - The bar that holds the label, when there is one.
  * @csspart key - A property name or an array index.
  * @csspart label - The label.
+ * @csspart live - How many entries a filter matched, in a region that screen readers announce when it changes. Drawn from the first filter on. Visually hidden in the styled tier.
  * @csspart null - A `null`.
  * @csspart number - A number.
- * @csspart row - One entry, as a tree item.
- * @csspart row-active - The entry the keyboard is on. Set alongside `row`.
+ * @csspart row - One entry, as a row of the tree grid, which takes focus.
+ * @csspart row-active - The entry the keyboard is on, which holds the tab stop. Set alongside `row`.
+ * @csspart row-match - An entry whose key or value holds the filter. Set alongside `row`.
+ * @csspart search-field - The field that sets `filter`, with `filterable`.
  * @csspart string - A string, in quotes.
  * @csspart summary - The brackets that stand for a branch's contents.
  * @csspart toggle - The caret on a branch. It points down when the branch is open and sideways when it is closed.
- * @csspart tree - The tree, which is the element that receives focus.
+ * @csspart tree - The tree grid that holds the rows.
  *
  * @cssproperty --object-inspector-level - How deep a row is, from 0 at the root, for indenting it.
  */
 export declare class HelixHeadlessObjectInspector extends HelixElement {
+    /**
+     * The active row's path, such as `/meta/tags/0`, and the empty string for the
+     * root.
+     *
+     * Reading gives the row the keys are on. Writing moves there, opening the
+     * branches around it, and sends no event, the way a script's write to any
+     * current value sends none. A path the value does not hold moves to the
+     * nearest branch above it that it does.
+     */
+    get active(): string;
+    set active(path: string);
     /**
      * The copy button's accessible name on a row with a key, with the key filled
      * in as `{name}`.
@@ -109,6 +151,23 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      * wall of text this exists to avoid.
      */
     defaultDepth: number;
+    /**
+     * The open branches, by path, in no set order.
+     *
+     * Writing opens exactly these and closes every other, keeping the active row
+     * where it stays visible. A property, never an attribute.
+     */
+    get expanded(): string[];
+    set expanded(paths: string[]);
+    /**
+     * Text the tree is narrowed to: the entries whose key or value holds it,
+     * ignoring case, and the branches that lead to them. Empty shows everything.
+     */
+    filter: string;
+    /** Whether to show a field that sets `filter`. */
+    filterable: boolean;
+    /** The filter field's placeholder and accessible name. */
+    filterLabel: string;
     /**
      * The id of a `<script type="application/json">` holding the value.
      *
@@ -143,6 +202,13 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      * reach a value.
      */
     noCopy: boolean;
+    /** What a screen reader hears when a filter matches one entry. `{count}` is the count. */
+    resultLabel: string;
+    /**
+     * What a screen reader hears when a filter matches any other number of
+     * entries. `{count}` is the count. The two are chosen by `Intl.PluralRules`.
+     */
+    resultsLabel: string;
     /**
      * The tree's accessible name when `label` is empty and the host names it
      * with neither `aria-label` nor `aria-labelledby`.
@@ -169,15 +235,32 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     /** Which branches are open, by path. */
     private opened;
     /** The row the arrow keys are on, by its place among the visible rows. */
-    private active;
+    private cursor;
+    /** A path written to `active` and not yet found among the rows. */
+    private wanted;
+    /**
+     * The branches written to `expanded`, until the next update applies them.
+     *
+     * Its own field, because a property declared with an accessor is in the
+     * first update's changes whether or not anybody wrote it.
+     */
+    private declared;
+    /** The paths the filter matched, or nothing while there is no filter. */
+    private found;
     /** Set by a keyboard move, so the next render brings the active row into view. */
     private revealing;
+    /** Set by a reader's move, so the next render moves focus to the active row. */
+    private focusing;
+    /** Whether a row held focus as this update began, so a row the render moved gets it back. */
+    private hadFocus;
     /** What has been typed toward a key, and when the last letter came. */
     private typed;
     /** The branches of the last value seen, by path, so a new value can tell old ones from new. */
     private branches;
     /** Carries a host `aria-label` and `aria-labelledby` to the tree, which is what takes focus. */
     protected readonly aria: AriaForwardController;
+    /** Says how many entries a filter matched. */
+    private readonly status;
     /**
      * How tall a row is taken to be before it has been drawn, in pixels.
      *
@@ -193,8 +276,6 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     /** Every visible row, in order, worked out once per change rather than per read. */
     private rows;
     private readonly copier;
-    /** Every visible row, in order, for the tree as it stands. */
-    private flatten;
     /**
      * Opens every branch shallower than `defaultDepth`.
      *
@@ -205,9 +286,20 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      * place on every update.
      */
     private seed;
+    /** Opens the branches around each path, where the value has them. */
+    private openAround;
     protected willUpdate(changed: PropertyValues): void;
+    /** Says how many entries the filter matched, and nothing for an empty one. */
+    private tell;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /**
+     * Moves focus to the active row, once it is drawn.
+     *
+     * After a reader's move only, so a script writing `active` does not take
+     * focus from wherever the reader is.
+     */
+    private focusActive;
     private load;
     /**
      * Brings the active row into the box.
@@ -224,11 +316,27 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     private reveal;
     /** What copying takes: a branch as indented JSON, a string as itself. */
     private copyable;
+    /**
+     * Asks to open or close branches, and then does and says so:
+     * `helix-before-open` or `helix-before-close`, which a listener can cancel,
+     * then `toggle`. A reader's act only. Returns whether they moved.
+     */
+    private requestOpen;
+    /**
+     * Says a branch opened or closed under the platform's own name and in its
+     * shape: `toggle` with `newState` and `oldState`, not bubbling, as
+     * `<details>` sends it and as the open mixin does for the families whose
+     * open state it owns. A real `ToggleEvent` where the platform has one, and a
+     * plain event carrying the same two fields where it does not.
+     */
+    private announceToggle;
     private toggle;
+    /**
+     * Moves the active row, asking first: `helix-before-activate` with the path,
+     * then `helix-activate` once it has moved. Returns whether it is there.
+     */
     private move;
     private readonly handleKeydown;
-    /** Opens every branch at the active row's level under the same parent, as `*` asks. */
-    private openSiblings;
     /**
      * Moves to the next row whose key starts with what was typed.
      *
@@ -237,19 +345,41 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      * keys that start with it.
      */
     private typeahead;
+    /** A press opens or closes the row it lands on, once that row is the active one. */
     private handleRowClick;
+    /** Text typed in the filter field, asked for before the tree narrows to it. */
+    private readonly handleFilterInput;
+    /** Down from the filter field goes to the active row, where the matches are. */
+    private readonly handleFilterKeydown;
     private renderValue;
     /**
      * One entry, named for its state where it holds one.
      *
      * **`row-active` and no attribute beside it.** Which row the keys are on is
      * drawn by a sheet and by nothing else: the accessibility tree hears it from
-     * `aria-activedescendant` on the tree, which points at this row's id, so an
-     * attribute would be a second spelling with no reader. The name is the one a
-     * consumer can reach, nothing being able to follow `::part()` with an
-     * attribute selector.
+     * focus, which the row holds, so an attribute would be a second spelling with
+     * no reader. The name is the one a consumer can reach, nothing being able to
+     * follow `::part()` with an attribute selector.
+     *
+     * **A `row` of a `treegrid` with one cell, focused itself, and no
+     * `aria-selected`**, because nothing here is chosen. Chromium takes the
+     * focused item of a single-selection `tree` as selected, by focus or by
+     * `aria-activedescendant` (measured), so every arrow press was also announced
+     * as a selection, and `aria-selected="false"` on every row was the one way to
+     * turn it off. A row of a tree grid is not selected by focus, which is why
+     * React Aria's Tree is one. The cell is `display: contents`, so the row lays
+     * out its text as it did.
      */
     private renderRow;
+    /** Whether a row of the tree holds focus. */
+    private hasFocusedRow;
+    /**
+     * A row that takes focus some other way than the keys, from a script or a
+     * screen reader, becomes the active row, so focus and the keys agree.
+     */
+    private readonly handleFocusIn;
+    /** A row kept drawn for focus is let go once focus leaves it. */
+    private readonly handleFocusOut;
     /** The copy button, behind the seam Code Block's uses, so each tier renders its own. */
     protected renderCopyButton(row: Row | undefined): TemplateResult;
     protected render(): TemplateResult;
@@ -259,4 +389,3 @@ declare global {
         'helix-headless-object-inspector': HelixHeadlessObjectInspector;
     }
 }
-export {};