@humanspeak/svelte-json-view-lite 0.1.4 → 0.2.0

package/README.md

@@ -259,6 +259,7 @@ pnpm build        # vite build + svelte-package + publint
 
 Part of the [Humanspeak](https://humanspeak.com) family of runes-native Svelte 5 packages:
 
+<!-- prettier-ignore-start -->
 | Package | Description |
 | --- | --- |
 | [@humanspeak/svelte-markdown](https://markdown.svelte.page) | Runtime markdown renderer for Svelte |
@@ -271,6 +272,7 @@ Part of the [Humanspeak](https://humanspeak.com) family of runes-native Svelte 5
 | [@humanspeak/memory-cache](https://memory.svelte.page) | In-memory cache for TypeScript |
 | **[@humanspeak/svelte-json-view-lite](https://jsonview.svelte.page)** — _this package_ | JSON tree viewer for Svelte 5 |
 | [@humanspeak/svelte-scoped-props](https://scoped.svelte.page) | Scoped class props for Svelte |
+<!-- prettier-ignore-end -->
 
 ## License
 

package/dist/EmptyObject.svelte

@@ -15,7 +15,9 @@
     live in a single punctuation span so the `.punctuation-base + .punctuation-base`
     adjacent-sibling margin rule isn't needed here.
 -->
-<div class={style.basicChildStyle} role="treeitem" aria-selected={false}>
+<!-- Upstream parity: unselected treeitems omit aria-selected entirely. -->
+<!-- svelte-ignore a11y_role_has_required_aria_props -->
+<div class={style.basicChildStyle} role="treeitem">
     <!-- prettier-ignore -->
     {#if hasField}<span class={style.label}>{labelText}:</span>{/if}<span class={style.punctuation}
         >{openBracket}{closeBracket}{lastElement ? '' : ','}</span

package/dist/ExpandableObject.svelte

@@ -60,6 +60,13 @@
 
     let expanderButton = $state<HTMLSpanElement | null>(null)
 
+    // Register from the node action, not a component effect: actions follow
+    // DOM creation order, so parent/top-level expanders append before children.
+    function registerExpander(node: HTMLSpanElement) {
+        const unregister = outerRef.navigation.register(node)
+        return { destroy: unregister }
+    }
+
     const activeAriaLabels = $derived<AriaLabels>(
         style.ariaLabels ??
             style.ariaLables ?? {
@@ -112,29 +119,13 @@
         if (e.key !== 'ArrowUp' && e.key !== 'ArrowDown') return
         e.preventDefault()
         const direction = e.key === 'ArrowUp' ? -1 : 1
-        const outer = outerRef.current
-        if (!outer) return
-        const buttons = outer.querySelectorAll<HTMLElement>('[role=button]')
-        let currentIndex = -1
-        for (let i = 0; i < buttons.length; i++) {
-            if (buttons[i].tabIndex === 0) {
-                currentIndex = i
-                break
-            }
-        }
-        if (currentIndex < 0) return
-        const nextIndex = (currentIndex + direction + buttons.length) % buttons.length
-        buttons[currentIndex].tabIndex = -1
-        buttons[nextIndex].tabIndex = 0
-        buttons[nextIndex].focus()
+        if (expanderButton) outerRef.navigation.move(expanderButton, direction)
     }
 
     function onClick() {
         setExpandWithCallback(!expanded)
         if (!expanderButton) return
-        const prev = outerRef.current?.querySelector<HTMLElement>('[role=button][tabindex="0"]')
-        if (prev) prev.tabIndex = -1
-        expanderButton.tabIndex = 0
+        outerRef.navigation.activate(expanderButton)
         expanderButton.focus()
     }
 </script>
@@ -142,12 +133,9 @@
 {#if count === 0}
     <EmptyObject {field} {openBracket} {closeBracket} {lastElement} {style} />
 {:else}
-    <div
-        class={style.basicChildStyle}
-        role="treeitem"
-        aria-expanded={expanded}
-        aria-selected={false}
-    >
+    <!-- Upstream parity: unselected treeitems omit aria-selected entirely. -->
+    <!-- svelte-ignore a11y_role_has_required_aria_props -->
+    <div class={style.basicChildStyle} role="treeitem" aria-expanded={expanded}>
         <!--
             The entire inline sequence inside a row lives on a single
             prettier-ignored line because Svelte preserves template whitespace
@@ -159,7 +147,7 @@
             it tight anyway for a consistent rule.
         -->
         <!-- prettier-ignore -->
-        <span bind:this={expanderButton} class={expanderIconStyle} role="button" aria-label={ariaLabel} aria-expanded={expanded} aria-controls={expanded ? contentsId : undefined} tabindex={level === 0 ? 0 : -1} onclick={onClick} onkeydown={onKeyDown}></span>{#if hasField}{#if snippets.label}{@render snippets.label(
+        <span bind:this={expanderButton} use:registerExpander class={expanderIconStyle} role="button" aria-label={ariaLabel} aria-expanded={expanded} aria-controls={expanded ? contentsId : undefined} tabindex={level === 0 ? 0 : -1} onclick={onClick} onkeydown={onKeyDown}></span>{#if hasField}{#if snippets.label}{@render snippets.label(
                     { field: field ?? '', level }
                 )}{:else if clickToExpandNode}<!-- svelte-ignore a11y_no_static_element_interactions --><span
                     class={style.clickableLabel}

package/dist/JsonPrimitiveValue.svelte

@@ -112,7 +112,9 @@
     whitespace natively; we hand-collapse it. Per-type snippet branches key
     off `kind` rather than re-running predicates.
 -->
-<div class={style.basicChildStyle} role="treeitem" aria-selected={false}>
+<!-- Upstream parity: unselected treeitems omit aria-selected entirely. -->
+<!-- svelte-ignore a11y_role_has_required_aria_props -->
+<div class={style.basicChildStyle} role="treeitem">
     <!-- prettier-ignore -->
     {#if hasField}{#if snippets.label}{@render snippets.label({ field: field ?? '', level })}{:else}<span class={style.label}>{labelText}:</span>{/if}{/if}{#if activeSnippet && kind === 'null'}{@render snippets.null?.(
             { value: null, field, level }

package/dist/JsonView.svelte

@@ -3,6 +3,7 @@
     import { defaultStyles } from './index.js'
     import type { OuterRef, Props, StyleProps } from './types.js'
     import { isObject } from './utils/dataTypeDetection.js'
+    import { createExpanderNavigation } from './utils/expanderNavigation.js'
     import { allExpanded } from './utils/expandStrategies.js'
 
     const {
@@ -26,6 +27,7 @@
     }: Props = $props()
 
     let outerElement = $state<HTMLDivElement | null>(null)
+    const navigation = createExpanderNavigation()
 
     // Merge user theme onto defaults. Also emit a deprecation warning when the
     // legacy `ariaLables` key (typo in react-json-view-lite) is supplied
@@ -52,7 +54,8 @@
     const outerRef: OuterRef = {
         get current() {
             return outerElement
-        }
+        },
+        navigation
     }
 
     const snippets = $derived({

package/dist/types.d.ts

@@ -106,13 +106,62 @@ export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'data' | 'st
     label?: Snippet<[LabelSnippetProps]>;
 }
 /**
- * Reference wrapper passed from the root down to every expandable node so
- * that cross-sibling keyboard navigation can query `[role=button]` elements
- * scoped to the tree. Using a getter ensures the child always reads the
- * current `bind:this` target rather than a frozen snapshot.
+ * Tree-local controller for roving tabindex across expandable nodes.
+ *
+ * The controller is intentionally passed through internal render props instead
+ * of discovered from the DOM on every keypress. Each expander registers its
+ * button while mounted, unregisters on `$effect` cleanup, and asks this helper
+ * to activate or move focus when the user clicks or presses ArrowUp/ArrowDown.
+ */
+export interface ExpanderNavigation {
+    /**
+     * Add a mounted expander button to the navigation order.
+     *
+     * @param _button - Expander button element rendered by an expandable node.
+     * @returns Cleanup callback that removes the button on component unmount.
+     *
+     * @example
+     * ```ts
+     * const cleanup = navigation.register(button)
+     * cleanup()
+     * ```
+     */
+    register(_button: HTMLElement): () => void;
+    /**
+     * Make a registered button the only expander with `tabIndex=0`.
+     *
+     * @param _button - Registered expander button to activate.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * navigation.activate(button)
+     * ```
+     */
+    activate(_button: HTMLElement): void;
+    /**
+     * Move focus to the next or previous registered expander.
+     *
+     * @param _button - Current registered expander button.
+     * @param _direction - `1` for ArrowDown, `-1` for ArrowUp.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * navigation.move(button, 1)
+     * ```
+     */
+    move(_button: HTMLElement, _direction: -1 | 1): void;
+}
+/**
+ * Reference wrapper passed from the root down to every expandable node. Using
+ * a getter ensures the child always reads the current `bind:this` target rather
+ * than a frozen snapshot; the navigation helper keeps roving tabindex state
+ * tree-local without doing live DOM sweeps on every keypress.
  */
 export interface OuterRef {
     readonly current: HTMLDivElement | null;
+    readonly navigation: ExpanderNavigation;
 }
 /** Internal shared props threaded through every renderer. Not exported. */
 export interface CommonRenderProps {

package/dist/utils/expanderNavigation.d.ts

@@ -0,0 +1,23 @@
+import type { ExpanderNavigation } from '../types.js';
+/**
+ * Create the tree-local roving tabindex controller for expandable JSON nodes.
+ *
+ * Each expander registers its own button on mount and receives a cleanup
+ * callback for unmount. The controller stores buttons in document order as a
+ * linked list, so ArrowUp/ArrowDown can move from the current button to its
+ * neighbor without querying `[role=button]` or scanning `tabIndex` across the
+ * whole tree on every keypress. Normal document-order mounts append in O(1);
+ * the insertion scan is reserved for out-of-order registrations.
+ *
+ * @returns A navigation controller shared by every expandable node in one
+ * `JsonView` tree.
+ *
+ * @example
+ * ```ts
+ * const navigation = createExpanderNavigation()
+ * const cleanup = navigation.register(button)
+ * navigation.move(button, 1)
+ * cleanup()
+ * ```
+ */
+export declare const createExpanderNavigation: () => ExpanderNavigation;

package/dist/utils/expanderNavigation.js

@@ -0,0 +1,224 @@
+/**
+ * Create the tree-local roving tabindex controller for expandable JSON nodes.
+ *
+ * Each expander registers its own button on mount and receives a cleanup
+ * callback for unmount. The controller stores buttons in document order as a
+ * linked list, so ArrowUp/ArrowDown can move from the current button to its
+ * neighbor without querying `[role=button]` or scanning `tabIndex` across the
+ * whole tree on every keypress. Normal document-order mounts append in O(1);
+ * the insertion scan is reserved for out-of-order registrations.
+ *
+ * @returns A navigation controller shared by every expandable node in one
+ * `JsonView` tree.
+ *
+ * @example
+ * ```ts
+ * const navigation = createExpanderNavigation()
+ * const cleanup = navigation.register(button)
+ * navigation.move(button, 1)
+ * cleanup()
+ * ```
+ */
+export const createExpanderNavigation = () => {
+    const nodes = new WeakMap();
+    let first = null;
+    let last = null;
+    let active = null;
+    let activeIsSeed = false;
+    /**
+     * Detach a node from the linked list while preserving the surrounding
+     * neighbors. The caller owns deleting it from the lookup table.
+     *
+     * @param node - Registered expander node to remove from document order.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * unlink(node)
+     * ```
+     */
+    const unlink = (node) => {
+        if (node.previous)
+            node.previous.next = node.next;
+        else
+            first = node.next;
+        if (node.next)
+            node.next.previous = node.previous;
+        else
+            last = node.previous;
+        node.previous = null;
+        node.next = null;
+    };
+    /**
+     * Insert a registered node before another registered node in document
+     * order.
+     *
+     * @param node - Expander node being inserted.
+     * @param before - Existing expander node that currently follows `node`.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * insertBefore(node, before)
+     * ```
+     */
+    const insertBefore = (node, before) => {
+        node.previous = before.previous;
+        node.next = before;
+        if (before.previous)
+            before.previous.next = node;
+        else
+            first = node;
+        before.previous = node;
+    };
+    /**
+     * Append a registered node to the end of the document-order list.
+     *
+     * @param node - Expander node being appended.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * append(node)
+     * ```
+     */
+    const append = (node) => {
+        node.previous = last;
+        if (last)
+            last.next = node;
+        else
+            first = node;
+        last = node;
+    };
+    /**
+     * Make one registered button the active roving tabindex target.
+     *
+     * @param node - Expander node that should receive `tabIndex=0`.
+     * @param seed - Whether this is the implicit initial target, which may
+     * move to the document-order head if earlier nodes register later.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * setActive(node, false)
+     * ```
+     */
+    const setActive = (node, seed) => {
+        if (active && active !== node)
+            active.element.tabIndex = -1;
+        active = node;
+        activeIsSeed = seed;
+        node.element.tabIndex = 0;
+    };
+    /**
+     * Make one registered button the explicit active roving tabindex target.
+     *
+     * @param button - Expander button that should receive `tabIndex=0`.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * navigation.activate(button)
+     * ```
+     */
+    const activate = (button) => {
+        const node = nodes.get(button);
+        if (!node)
+            return;
+        setActive(node, false);
+    };
+    /**
+     * Remove a button from the controller and keep a usable roving target when
+     * the active button unmounts.
+     *
+     * @param button - Expander button previously returned by `register`.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * unregister(button)
+     * ```
+     */
+    const unregister = (button) => {
+        const node = nodes.get(button);
+        if (!node)
+            return;
+        const fallback = node.next ?? node.previous;
+        const wasActive = active === node;
+        const wasSeed = activeIsSeed;
+        nodes.delete(button);
+        unlink(node);
+        if (wasActive) {
+            active = null;
+            activeIsSeed = false;
+            if (fallback)
+                setActive(fallback, wasSeed);
+        }
+    };
+    /**
+     * Register a mounted expander button in document order.
+     *
+     * @param button - Expander button rendered by an `ExpandableObject`.
+     * @returns Cleanup callback that unregisters `button` on component unmount.
+     *
+     * @example
+     * ```ts
+     * const cleanup = navigation.register(button)
+     * cleanup()
+     * ```
+     */
+    const register = (button) => {
+        const existing = nodes.get(button);
+        if (existing)
+            return () => unregister(button);
+        const node = { element: button, previous: null, next: null };
+        nodes.set(button, node);
+        if (!last ||
+            (last.element.compareDocumentPosition(button) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0) {
+            append(node);
+        }
+        else {
+            let before = null;
+            for (let cursor = first; cursor; cursor = cursor.next) {
+                if ((button.compareDocumentPosition(cursor.element) &
+                    Node.DOCUMENT_POSITION_FOLLOWING) !==
+                    0) {
+                    before = cursor;
+                    break;
+                }
+            }
+            if (before)
+                insertBefore(node, before);
+            else
+                append(node);
+        }
+        if (button.tabIndex === 0)
+            setActive(node, false);
+        else if ((!active || activeIsSeed) && first)
+            setActive(first, true);
+        return () => unregister(button);
+    };
+    /**
+     * Move focus to the adjacent registered expander, wrapping at list edges.
+     *
+     * @param button - Current expander button handling the keypress.
+     * @param direction - `1` for ArrowDown, `-1` for ArrowUp.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * navigation.move(button, 1)
+     * ```
+     */
+    const move = (button, direction) => {
+        const current = nodes.get(button);
+        if (!current)
+            return;
+        const next = direction === 1 ? (current.next ?? first) : (current.previous ?? last);
+        if (!next)
+            return;
+        setActive(next, false);
+        next.element.focus();
+    };
+    return { register, activate, move };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-json-view-lite",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Fast, tiny JSON tree viewer for Svelte 5 — port of react-json-view-lite with runes, SSR, snippet overrides, and zero runtime dependencies",
   "keywords": [
     "svelte",