@fusion.dev/helix-headless 0.23.0 → 0.24.1

package/dist/notifications/root/notifications-root.js

@@ -32,7 +32,33 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
         return this.items.filter((item) => !item.read).length;
     }
     get items() {
-        return [...(this.children ?? [])].filter((child) => 'isNotification' in child && child.isNotification === true);
+        const isItem = (child) => 'isNotification' in child && child.isNotification === true;
+        return this.knownChildren.flatMap((child) => {
+            if (isItem(child)) {
+                return [child];
+            }
+            const grouped = 'isNotificationGroup' in child ? [...(child.children ?? [])] : [];
+            return grouped.filter(isItem);
+        });
+    }
+    get rows() {
+        return this.knownChildren.filter((child) => ('isNotification' in child && child.isNotification === true) ||
+            'isNotificationGroup' in child);
+    }
+    get groups() {
+        return this.knownChildren.filter((child) => 'isNotificationGroup' in child);
+    }
+    foldEveryGroup(folded = true) {
+        let moved = 0;
+        for (const group of this.groups) {
+            if (!group.collapsible || group.open !== folded) {
+                continue;
+            }
+            if (group.requestOpen(!folded)) {
+                moved += 1;
+            }
+        }
+        return moved;
     }
     markEveryoneRead() {
         if (!this.dispatchEvent(new HelixReadEvent({ read: true }))) {
@@ -53,8 +79,13 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
         if (!list?.assign) {
             return;
         }
-        const items = this.items;
-        list.assign(...items);
+        if (this.assignsByName) {
+            for (const row of this.rows) {
+                this.route(row, 'items');
+            }
+            return;
+        }
+        list.assign(...this.rows);
         for (const name of ['header', 'footer']) {
             const slot = root?.querySelector?.(`slot[name="${name}"]`);
             slot?.assign?.(...[...this.children].filter((child) => child.getAttribute('slot') === name));
@@ -101,7 +132,7 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
         }
     }
     render() {
-        const hasItems = this.items.length > 0;
+        const hasItems = this.items.length > 0 || !this.childrenKnown;
         return html `<div part="header">
         <slot name="header"></slot>
         ${this.markAll && this.unread > 0

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

@@ -142,6 +142,18 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
      * stepping to 0 would be out of range before the reader had typed anything.
      */
     private nudge;
+    /**
+     * A value the reader moved to in one gesture, applied and committed.
+     *
+     * **A step is finished when it lands, so it commits.** The field sends
+     * `change` on blur for what the reader typed, and a step is written by
+     * script, so the browser never sends one for it: three presses of the plus
+     * and a move elsewhere reached a form listening on `change` as nothing at
+     * all. A native number field commits on every step, and so does this, for
+     * the arrows, the buttons, and `Home` and `End`. Only when the value moved: a
+     * refused step, or one pinned at a bound, finished nothing.
+     */
+    private land;
     /** One step up, or `PageUp`'s larger one. */
     stepUp(large?: boolean): void;
     /**
@@ -173,6 +185,8 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
     /** Where the pointer went down, and what the value was there. */
     private scrubFrom;
     private scrubValue;
+    /** The value when the press began, which is what a release is compared to. */
+    private scrubStart;
     /**
      * Press, and the value follows the pointer.
      *
@@ -193,7 +207,13 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
      * the value can only be where the pointer says it is.
      */
     private readonly handleScrubMove;
-    /** Let go, and the capture goes with it. */
+    /**
+     * Let go, and the capture goes with it, and the drag commits.
+     *
+     * The same reason a step does: every frame of the drag was written by script,
+     * so the browser sends no `change` for any of it, and a drag that moved the
+     * value is finished when the pointer lets go.
+     */
     private readonly handleScrubEnd;
     /**
      * Every keystroke, cancelable, and put back where it is refused.

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

@@ -27,6 +27,7 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         this.step = 1;
         this.scrubFrom = 0;
         this.scrubValue = 0;
+        this.scrubStart = '';
         this.handleScrubDown = (event) => {
             if (this.isDisabled || this.readOnly) {
                 return;
@@ -35,6 +36,7 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
             event.currentTarget.setPointerCapture(event.pointerId);
             this.scrubFrom = event.clientX;
             this.scrubValue = this.numeric ?? this.min ?? 0;
+            this.scrubStart = this.value;
             event.preventDefault();
         };
         this.handleScrubMove = (event) => {
@@ -58,8 +60,12 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         };
         this.handleScrubEnd = (event) => {
             const grip = event.currentTarget;
-            if (grip.hasPointerCapture(event.pointerId)) {
-                grip.releasePointerCapture(event.pointerId);
+            if (!grip.hasPointerCapture(event.pointerId)) {
+                return;
+            }
+            grip.releasePointerCapture(event.pointerId);
+            if (this.value !== this.scrubStart) {
+                this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
             }
         };
         this.handleInput = (event) => {
@@ -98,13 +104,13 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
                 this.min !== undefined &&
                 !this.isDisabled &&
                 !this.readOnly) {
-                this.requestValue(String(this.min));
+                this.land(String(this.min));
             }
             else if (event.key === 'End' &&
                 this.max !== undefined &&
                 !this.isDisabled &&
                 !this.readOnly) {
-                this.requestValue(String(this.max));
+                this.land(String(this.max));
             }
             else {
                 return;
@@ -142,11 +148,18 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         const step = Math.abs(this.step) || 1;
         const from = this.numeric ?? this.min ?? 0;
         const next = this.clamp(this.numeric === null ? from : from + steps * step);
-        this.requestValue(String(next));
+        this.land(String(next));
+    }
+    land(next) {
+        const before = this.value;
+        const applied = this.requestValue(next);
         const control = this.control;
         if (control) {
             restoreValue(control, this.value);
         }
+        if (applied && this.value !== before) {
+            this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
+        }
     }
     stepUp(large = false) {
         this.nudge(large ? (this.largeStep ?? 10) : 1);

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

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

package/dist/object-inspector/index.js

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

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

@@ -0,0 +1,183 @@
+import { 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;
+}
+/**
+ * @summary A value read as a tree: collapse what you do not need, count what
+ * you collapsed, copy the part you do.
+ *
+ * @description
+ * What a developer-facing product shows constantly is a structured value: an
+ * API response, a config, a row's raw record. As text in a code block, a reader
+ * scrolls a wall of JSON and cannot put away the branch they do not care about;
+ * as a Tree, every node is a label and a string reads the same as a number. This
+ * reads the value and draws each entry with its type visible.
+ *
+ * **It reads and never edits.** An inspector that edits is a different
+ * component, with validation, undo and a model of what changed, and the reading
+ * one is what is wanted.
+ *
+ * **The data is text in the page or a property.** `for` names a
+ * `<script type="application/json">` by id, the channel `VirtualList` and the
+ * charts already read: it survives a server, which has attributes and no
+ * children, and React's hydration, which skips object properties. `value` is
+ * there for a page that already holds the object, and wins when both are set.
+ *
+ * **One tab stop, and the rows are reached with the arrow keys**, the tree
+ * pattern: Up and Down move, Right opens a branch or enters it, Left closes it or
+ * goes to its parent, Home and End go to the ends. The tree keeps focus and
+ * points at the active row with `aria-activedescendant`, which is what lets a
+ * windowed tree drop rows from the page without dropping focus with them. Each
+ * row carries its real level, position and set size, so a reader on a windowed
+ * row hears where it is in the value rather than in the slice drawn.
+ *
+ * **Copying takes the active row**, as JSON for a branch and as itself for a
+ * string, from the copy button or from Command or Control with C while the tree
+ * has focus and nothing is selected. The button sits beside the tree rather than in each row, where a
+ * button would be an interactive control inside a tree item, which assistive
+ * technology cannot reach reliably.
+ *
+ * **`windowed` draws only the rows in view**, for a value of thousands of
+ * entries, through the same controller `VirtualList` and `DataTable` use. The
+ * box has to have a height for that to mean anything, which the styled tier
+ * gives it and a headless consumer has to.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category data
+ * @aliases JSON viewer, Object viewer, Inspector, Data explorer
+ * @documentation https://helix.fusion.dev/components/object-inspector
+ *
+ * @event {HelixCopyEvent} helix-copy - A value was put on the clipboard, from the copy button or the keyboard.
+ *
+ * @csspart after - The room the rows after the window would take, when windowed.
+ * @csspart before - The room the rows before the window would take, when windowed.
+ * @csspart boolean - A `true` or `false`.
+ * @csspart copy - The copy button, which copies the active row.
+ * @csspart copy-button - The inner button.
+ * @csspart copy-mark - The clipboard glyph, and the confirmation that replaces it.
+ * @csspart copy-tooltip - The bubble, forwarded from the tooltip inside.
+ * @csspart copy-tooltip-arrow - The point, resting against the trigger.
+ * @csspart count - How many entries a branch holds.
+ * @csspart frame - The tree and the copy button beside it.
+ * @csspart header - The bar carrying the label, where there is one.
+ * @csspart key - A property name or an array index.
+ * @csspart label - The label.
+ * @csspart null - A `null`.
+ * @csspart number - A number.
+ * @csspart row - One entry, a tree item.
+ * @csspart string - A string, in quotes.
+ * @csspart summary - The brackets standing for a branch's contents.
+ * @csspart toggle - The caret on a branch: down when open, across when closed.
+ * @csspart tree - The tree, the one thing focus lands on.
+ *
+ * @cssproperty --object-inspector-level - How deep a row is, from 0 at the root, for indenting it.
+ */
+export declare class HelixHeadlessObjectInspector extends HelixElement {
+    /**
+     * How many levels start open.
+     *
+     * One by default: the root is open and everything under it closed, so a
+     * reader sees the shape of the value before its contents. `0` starts with the
+     * root closed; a large number opens everything, which on a big value is the
+     * wall of text this exists to avoid.
+     */
+    defaultDepth: number;
+    /**
+     * The id of a `<script type="application/json">` holding the value.
+     *
+     * Read once the document exists, and again whenever this changes. Text that
+     * does not parse leaves the inspector empty rather than throwing, since a
+     * page's markup should not take the page down over a comma.
+     */
+    for: string;
+    /**
+     * Accessible name for the tree, and the text of the header where there is one.
+     */
+    label: string;
+    /**
+     * Whether to leave the copy button off.
+     *
+     * Negative for the reason Code Block's is: a boolean attribute defaulting to
+     * true could never be turned off from markup.
+     */
+    noCopy: boolean;
+    /**
+     * The value itself, for a page that already holds it.
+     *
+     * Takes precedence over `for`. Anything JSON can say is drawn; anything else
+     * is shown as its string.
+     */
+    value: unknown;
+    /**
+     * Whether to draw only the rows in view.
+     *
+     * For a value of thousands of entries. Reflected, because the box it scrolls
+     * needs a height, which is a stylesheet rule reading this attribute.
+     */
+    windowed: boolean;
+    /** The value read from `for`, when there is no `value`. */
+    private read;
+    /** The `for` that `read` came from, so it is read again only when that changes. */
+    private loadedFor;
+    /** Which branches are open, by path. */
+    private opened;
+    /** The row the arrow keys are on, by its place among the visible rows. */
+    private active;
+    /** Set by a keyboard move, so the next render brings the active row into view. */
+    private revealing;
+    private readonly virtualize;
+    private get root();
+    /** 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`. */
+    private seed;
+    protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    private load;
+    /**
+     * Brings the active row into the box.
+     *
+     * **A windowed tree may not have drawn it, and a jump straight to where it
+     * should be does not land.** The controller places rows it has not measured at
+     * its estimate, so an offset computed from a real row's height points at a
+     * different row, and asking again from there asks the same wrong question: the
+     * first version of this looped until the page stopped. So each attempt steps
+     * from the rows that *are* drawn toward the one wanted, by how many rows lie
+     * between, which closes the gap every time whatever the estimate is, and gives
+     * up after a few rather than trusting that it always will.
+     */
+    private reveal;
+    /** What copying takes: a branch as indented JSON, a string as itself. */
+    private copyable;
+    private toggle;
+    private move;
+    private readonly handleKeydown;
+    private handleRowClick;
+    private renderValue;
+    private renderRow;
+    /** 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;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-object-inspector': HelixHeadlessObjectInspector;
+    }
+}
+export {};