@harborclient/sdk 0.6.2 → 0.6.4

package/dist/components/VariableInput/index.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "@harborclient/sdk/jsx-runtime";
-import { useEffect, useMemo, useRef, useState } from '@harborclient/sdk/react';
-import { getDynamicVariableDescription, resolveVariable, tokenizeVariables } from '../../variables/index.js';
+import { useEffect, useId, useMemo, useRef, useState } from '@harborclient/sdk/react';
+import { getDynamicVariableDescription, getVariableTokenAtOffset, getVariableTooltipContent, resolveVariable, tokenizeVariables } from '../../variables/index.js';
 import { Input } from '../forms/index.js';
 /**
  * Text input that highlights {{variable}} tokens and shows resolved values on hover.
@@ -14,6 +14,7 @@ export function VariableInput({ value, onChange, variables, placeholder, onKeyDo
     const spanRefs = useRef(new Map());
     const hideTimer = useRef(null);
     const [tooltip, setTooltip] = useState(null);
+    const tooltipId = useId();
     /**
      * Splits the input value into plain text and {{variable}} token spans for highlighting.
      */
@@ -48,6 +49,53 @@ export function VariableInput({ value, onChange, variables, placeholder, onKeyDo
             backdrop.scrollLeft = input.scrollLeft;
         }
     };
+    /**
+     * Shows a tooltip for a variable token at the given screen position.
+     *
+     * @param key - Variable name from the token.
+     * @param top - Top coordinate for tooltip placement.
+     * @param left - Horizontal center coordinate for tooltip placement.
+     */
+    const showTooltipForKey = (key, top, left) => {
+        setTooltip({
+            key,
+            value: resolveVariable(key, variables),
+            dynamicDescription: getDynamicVariableDescription(key),
+            top,
+            left
+        });
+    };
+    /**
+     * Updates the tooltip based on the current text caret position.
+     */
+    const updateTooltipFromCaret = () => {
+        const input = inputRef.current;
+        if (!input)
+            return;
+        const offset = input.selectionStart ?? 0;
+        const match = getVariableTokenAtOffset(value, offset);
+        if (!match) {
+            setTooltip(null);
+            return;
+        }
+        let tokenIndex = -1;
+        let position = 0;
+        for (const [index, token] of tokens.entries()) {
+            if (token.key && position === match.start) {
+                tokenIndex = index;
+                break;
+            }
+            position += token.text.length;
+        }
+        const span = tokenIndex >= 0 ? spanRefs.current.get(tokenIndex) : undefined;
+        if (span) {
+            const rect = span.getBoundingClientRect();
+            showTooltipForKey(match.key, rect.top, rect.left + rect.width / 2);
+            return;
+        }
+        const rect = input.getBoundingClientRect();
+        showTooltipForKey(match.key, rect.top, rect.left + rect.width / 2);
+    };
     /**
      * Shows a tooltip when the pointer is over a variable token span.
      *
@@ -66,24 +114,50 @@ export function VariableInput({ value, onChange, variables, placeholder, onKeyDo
                 e.clientX <= rect.right &&
                 e.clientY >= rect.top &&
                 e.clientY <= rect.bottom) {
-                setTooltip({
-                    key: token.key,
-                    value: resolveVariable(token.key, variables),
-                    dynamicDescription: getDynamicVariableDescription(token.key),
-                    top: rect.top,
-                    left: rect.left + rect.width / 2
-                });
+                showTooltipForKey(token.key, rect.top, rect.left + rect.width / 2);
                 return;
             }
         }
         setTooltip(null);
     };
+    /**
+     * Handles keyboard events on the input, including tooltip dismissal.
+     *
+     * @param event - Keyboard event from the input.
+     */
+    const handleKeyDown = (event) => {
+        if (event.key === 'Escape' && tooltip) {
+            event.preventDefault();
+            setTooltip(null);
+            return;
+        }
+        onKeyDown?.(event);
+    };
+    /**
+     * Updates the tooltip after keyboard navigation moves the caret.
+     *
+     * @param event - Keyboard event from the input.
+     */
+    const handleKeyUp = (event) => {
+        if (event.key === 'ArrowLeft' ||
+            event.key === 'ArrowRight' ||
+            event.key === 'ArrowUp' ||
+            event.key === 'ArrowDown' ||
+            event.key === 'Home' ||
+            event.key === 'End') {
+            updateTooltipFromCaret();
+        }
+    };
+    const tooltipContent = tooltip ? getVariableTooltipContent(tooltip.key, variables) : null;
     return (_jsxs("div", { className: wrapperClassName ? `relative min-w-0 ${wrapperClassName}` : 'relative min-w-0 flex-1', children: [_jsx("div", { ref: backdropRef, "aria-hidden": true, className: "pointer-events-none absolute inset-0 overflow-hidden whitespace-nowrap px-2 py-1.5 text-[14px] text-inherit", children: value ? (tokens.map((token, index) => token.key ? (_jsx("span", { ref: (el) => {
                         if (el)
                             spanRefs.current.set(index, el);
                         else
                             spanRefs.current.delete(index);
-                    }, className: "text-[#32D2E2]", children: token.text }, index)) : (_jsx("span", { children: token.text }, index)))) : (_jsx("span", { className: "text-muted", children: placeholder })) }), _jsx(Input, { ref: inputRef, id: id, variant: "plain", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className: `relative w-full min-w-0 border-none bg-transparent px-2 py-1.5 text-[14px] text-transparent caret-text focus-visible:shadow-none ${className}`, type: "text", placeholder: placeholder, value: value, onChange: (e) => onChange(e.target.value), onKeyDown: onKeyDown, onScroll: syncScroll, onMouseMove: handleMouseMove, onMouseLeave: scheduleHide }), tooltip && (_jsxs("div", { className: "pointer-events-auto fixed z-50 flex max-w-sm -translate-x-1/2 -translate-y-full flex-col gap-1.5 rounded-md border border-separator bg-surface px-3 py-2 text-[14px] text-text shadow-md", style: { top: tooltip.top - 4, left: tooltip.left }, onMouseEnter: cancelHide, onMouseLeave: () => setTooltip(null), children: [tooltip.value !== undefined ? (tooltip.value) : tooltip.dynamicDescription ? (_jsxs("span", { className: "text-muted", children: ["Dynamic: ", tooltip.dynamicDescription] })) : (_jsx("span", { className: "text-muted", children: "Not defined" })), onEditVariable && (_jsx("button", { type: "button", className: "self-start text-[14px] text-accent hover:underline app-no-drag", onClick: () => {
+                    }, className: "text-[#32D2E2]", children: token.text }, index)) : (_jsx("span", { children: token.text }, index)))) : (_jsx("span", { className: "text-muted", children: placeholder })) }), _jsx(Input, { ref: inputRef, id: id, variant: "plain", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": tooltip ? tooltipId : undefined, className: `relative w-full min-w-0 border-none bg-transparent px-2 py-1.5 text-[14px] text-transparent caret-text focus-visible:shadow-none ${className}`, type: "text", placeholder: placeholder, value: value, onChange: (e) => {
+                    onChange(e.target.value);
+                    queueMicrotask(updateTooltipFromCaret);
+                }, onFocus: updateTooltipFromCaret, onKeyDown: handleKeyDown, onKeyUp: handleKeyUp, onSelect: updateTooltipFromCaret, onClick: updateTooltipFromCaret, onScroll: syncScroll, onMouseMove: handleMouseMove, onMouseLeave: scheduleHide }), tooltip && tooltipContent && (_jsxs("div", { id: tooltipId, role: "tooltip", className: "pointer-events-auto fixed z-50 flex max-w-sm -translate-x-1/2 -translate-y-full flex-col gap-1.5 rounded-md border border-separator bg-surface px-3 py-2 text-[14px] text-text shadow-md", style: { top: tooltip.top - 4, left: tooltip.left }, onMouseEnter: cancelHide, onMouseLeave: () => setTooltip(null), children: [_jsx("span", { className: tooltipContent.muted ? 'text-muted' : undefined, children: tooltipContent.text }), onEditVariable && (_jsx("button", { type: "button", className: "self-start text-[14px] text-accent hover:underline app-no-drag", "aria-label": `Edit value for ${tooltip.key}`, onClick: () => {
                             onEditVariable();
                             setTooltip(null);
                         }, children: "Edit value" }))] }))] }));

package/dist/components/VariableTable/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/VariableTable/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAa/C,UAAU,KAAK;IACb;;OAEG;IACH,SAAS,EAAE,QAAQ,EAAE,CAAC;IAEtB;;OAEG;IACH,QAAQ,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,IAAI,CAAC;IAE1C;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,GAAG,GAAG,CAAC,OAAO,CAkHtF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/VariableTable/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAa/C,UAAU,KAAK;IACb;;OAEG;IACH,SAAS,EAAE,QAAQ,EAAE,CAAC;IAEtB;;OAEG;IACH,QAAQ,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,IAAI,CAAC;IAE1C;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,GAAG,GAAG,CAAC,OAAO,CAmHtF"}

package/dist/components/VariableTable/index.js

@@ -39,5 +39,5 @@ export function VariableTable({ variables, onChange, description }) {
         }
         onChange(variables.filter((_, i) => i !== index));
     };
-    return (_jsxs("div", { children: [description && _jsx("p", { className: "mb-3 text-[14px] text-muted", children: description }), _jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsxs("table", { className: "w-full border-separate border-spacing-x-1.5 border-spacing-y-1.5", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { className: thClass, children: "Key" }), _jsx("th", { className: thClass, children: "Value" }), _jsx("th", { className: thClass, children: "Default" }), _jsx("th", { className: `${thClass} w-14 text-center`, children: "Share" }), _jsx("th", { className: `${thClass} w-7 p-0 text-center` })] }) }), _jsx("tbody", { children: variables.map((variable, index) => (_jsxs("tr", { className: "group", children: [_jsx("td", { children: _jsx(Input, { type: "text", className: "w-full", value: variable.key, placeholder: "variable", "aria-label": `Key, row ${index + 1}`, onChange: (e) => updateVariable(index, { key: e.target.value }) }) }), _jsx("td", { children: _jsx(Input, { type: "text", className: "w-full", value: variable.value, placeholder: "value", "aria-label": `Value, row ${index + 1}`, onChange: (e) => updateVariable(index, { value: e.target.value }) }) }), _jsx("td", { children: _jsx(Input, { type: "text", className: "w-full", value: variable.defaultValue, placeholder: "default", "aria-label": `Default, row ${index + 1}`, onChange: (e) => updateVariable(index, { defaultValue: e.target.value }) }) }), _jsx("td", { className: "w-14 text-center", children: _jsx(Input, { type: "checkbox", checked: variable.share, onChange: (e) => updateVariable(index, { share: e.target.checked }), "aria-label": `Include value in export, row ${index + 1}`, title: "Include value in export" }) }), _jsx("td", { className: "w-7 p-0 text-center", children: _jsx(Button, { type: "button", variant: "iconDanger", onClick: () => removeVariable(index), title: "Remove", children: _jsx(FaIcon, { icon: faXmark, className: "h-3.5 w-3.5" }) }) })] }, index))) })] }), _jsxs(Button, { type: "button", variant: "toolbar", className: "inline-flex items-center gap-1 self-start", onClick: addVariable, children: [_jsx(FaIcon, { icon: faPlus, className: "h-3 w-3" }), "Add variable"] })] })] }));
+    return (_jsxs("div", { children: [description && _jsx("p", { className: "mb-3 text-[14px] text-muted", children: description }), _jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsxs("table", { className: "w-full border-separate border-spacing-x-1.5 border-spacing-y-1.5", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { className: thClass, children: "Key" }), _jsx("th", { className: thClass, children: "Value" }), _jsx("th", { className: thClass, children: "Default" }), _jsx("th", { className: `${thClass} w-14 text-center`, children: "Share" }), _jsx("th", { className: `${thClass} w-7 p-0 text-center` })] }) }), _jsx("tbody", { children: variables.map((variable, index) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(Input, { type: "text", className: "w-full", value: variable.key, placeholder: "variable", "aria-label": `Key, row ${index + 1}`, onChange: (e) => updateVariable(index, { key: e.target.value }) }) }), _jsx("td", { children: _jsx(Input, { type: "text", className: "w-full", value: variable.value, placeholder: "value", "aria-label": `Value, row ${index + 1}`, onChange: (e) => updateVariable(index, { value: e.target.value }) }) }), _jsx("td", { children: _jsx(Input, { type: "text", className: "w-full", value: variable.defaultValue, placeholder: "default", "aria-label": `Default, row ${index + 1}`, onChange: (e) => updateVariable(index, { defaultValue: e.target.value }) }) }), _jsx("td", { className: "w-14 text-center", children: _jsx(Input, { type: "checkbox", checked: variable.share, onChange: (e) => updateVariable(index, { share: e.target.checked }), "aria-label": `Include value in export, row ${index + 1}`, title: "Include value in export" }) }), _jsx("td", { className: "w-7 p-0 text-center", children: _jsx(Button, { type: "button", variant: "iconDanger", onClick: () => removeVariable(index), title: "Remove", "aria-label": `Remove row ${index + 1}`, children: _jsx(FaIcon, { icon: faXmark, className: "h-3.5 w-3.5" }) }) })] }, index))) })] }), _jsxs(Button, { type: "button", variant: "toolbar", className: "inline-flex items-center gap-1 self-start", onClick: addVariable, children: [_jsx(FaIcon, { icon: faPlus, className: "h-3 w-3" }), "Add variable"] })] })] }));
 }

package/dist/components/classes.d.ts

@@ -1,7 +1,7 @@
 /**
  * Shared macOS-style Tailwind class strings for SDK UI components.
  */
-export declare const segmentGroup = "inline-flex rounded-md p-0.5 shadow-[inset_0_0.5px_1px_rgba(0,0,0,0.06)] app-no-drag";
+export declare const segmentGroup = "inline-flex p-3 border-b border-separator w-full shadow-[inset_0_0.5px_1px_rgba(0,0,0,0.06)] app-no-drag";
 /**
  * Tailwind classes for a segmented control button.
  *

package/dist/components/classes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"classes.d.ts","sourceRoot":"","sources":["../../src/components/classes.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,yFAC+D,CAAC;AAEzF;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAI/C"}
+{"version":3,"file":"classes.d.ts","sourceRoot":"","sources":["../../src/components/classes.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,6GACmF,CAAC;AAE7G;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAI/C"}

package/dist/components/classes.js

@@ -1,7 +1,7 @@
 /**
  * Shared macOS-style Tailwind class strings for SDK UI components.
  */
-export const segmentGroup = 'inline-flex rounded-md p-0.5 shadow-[inset_0_0.5px_1px_rgba(0,0,0,0.06)] app-no-drag';
+export const segmentGroup = 'inline-flex p-3 border-b border-separator w-full shadow-[inset_0_0.5px_1px_rgba(0,0,0,0.06)] app-no-drag';
 /**
  * Tailwind classes for a segmented control button.
  *
@@ -9,6 +9,6 @@ export const segmentGroup = 'inline-flex rounded-md p-0.5 shadow-[inset_0_0.5px_
  */
 export function segment(active) {
     return active
-        ? 'cursor-pointer rounded-[5px] border-none bg-control px-3 py-1 text-[15px] text-text shadow-sm app-no-drag'
-        : 'cursor-pointer rounded-[5px] border-none bg-transparent px-3 py-1 text-[15px] text-muted hover:text-text app-no-drag';
+        ? 'cursor-pointer rounded-[2.5px] border-none bg-control px-3 py-1 text-[15px] text-text shadow-sm app-no-drag'
+        : 'cursor-pointer rounded-[2.5px] border-none bg-transparent px-3 py-1 text-[15px] text-muted hover:text-text app-no-drag';
 }

package/dist/components/enhanceControl.d.ts

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react';
+/**
+ * Options for merging validation accessibility attributes onto a form control.
+ */
+export interface EnhanceControlOptions {
+    /**
+     * Space-separated ids merged into `aria-describedby` on the control.
+     */
+    describedBy?: string;
+    /**
+     * When true, sets `aria-invalid="true"` on the control.
+     */
+    invalid?: boolean;
+    /**
+     * Sets `id` on the leaf control when it does not already have one.
+     */
+    id?: string;
+}
+/**
+ * Merges accessibility attributes onto a form control, unwrapping single-child
+ * fragments and DOM wrappers to reach the underlying input component.
+ *
+ * @param child - Form control element or wrapper to enhance.
+ * @param options - `aria-describedby` ids, invalid state, and optional `id` to apply.
+ * @returns The original node or a cloned tree with ARIA props on the leaf control.
+ */
+export declare function enhanceControl(child: ReactNode, options: EnhanceControlOptions): ReactNode;
+//# sourceMappingURL=enhanceControl.d.ts.map

package/dist/components/enhanceControl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhanceControl.d.ts","sourceRoot":"","sources":["../../src/components/enhanceControl.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAgB,SAAS,EAAE,MAAM,OAAO,CAAC;AAMrD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AA0DD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB,GAAG,SAAS,CAmC1F"}

package/dist/components/enhanceControl.js

@@ -0,0 +1,84 @@
+import { cloneElement, isValidElement } from '@harborclient/sdk/react';
+const REACT_FRAGMENT_TYPE = Symbol.for('react.fragment');
+const FORM_CONTROL_TAGS = new Set(['button', 'input', 'select', 'textarea']);
+/**
+ * Returns the sole child when `node` is a one-element array; otherwise `node`.
+ *
+ * @param node - React child node to normalize.
+ * @returns The single child, or undefined when zero or multiple children exist.
+ */
+function getSingleChild(node) {
+    if (node == null || typeof node === 'boolean')
+        return undefined;
+    if (Array.isArray(node)) {
+        const filtered = node.filter((n) => n != null && n !== false);
+        return filtered.length === 1 ? filtered[0] : undefined;
+    }
+    return node;
+}
+/**
+ * Clones a control element with merged accessibility attributes.
+ *
+ * @param child - Leaf form control element.
+ * @param options - Accessibility attributes to apply.
+ * @returns Cloned element with merged ARIA props.
+ */
+function applyAriaProps(child, options) {
+    const { describedBy, invalid, id } = options;
+    const props = {};
+    if (id && child.props.id == null) {
+        props.id = id;
+    }
+    if (describedBy) {
+        const existing = typeof child.props['aria-describedby'] === 'string'
+            ? child.props['aria-describedby']
+            : undefined;
+        props['aria-describedby'] = existing ? `${existing} ${describedBy}` : describedBy;
+    }
+    if (invalid) {
+        props['aria-invalid'] = true;
+    }
+    if (Object.keys(props).length === 0)
+        return child;
+    return cloneElement(child, props);
+}
+/**
+ * Merges accessibility attributes onto a form control, unwrapping single-child
+ * fragments and DOM wrappers to reach the underlying input component.
+ *
+ * @param child - Form control element or wrapper to enhance.
+ * @param options - `aria-describedby` ids, invalid state, and optional `id` to apply.
+ * @returns The original node or a cloned tree with ARIA props on the leaf control.
+ */
+export function enhanceControl(child, options) {
+    const { describedBy, invalid, id } = options;
+    if (!describedBy && !invalid && !id)
+        return child;
+    const single = getSingleChild(child);
+    if (single !== undefined && single !== child) {
+        return enhanceControl(single, options);
+    }
+    if (!isValidElement(child))
+        return child;
+    if (child.type === REACT_FRAGMENT_TYPE) {
+        const inner = getSingleChild(child.props.children);
+        if (inner && isValidElement(inner)) {
+            return cloneElement(child, {}, enhanceControl(inner, options));
+        }
+        return child;
+    }
+    if (typeof child.type === 'string') {
+        if (FORM_CONTROL_TAGS.has(child.type)) {
+            return applyAriaProps(child, options);
+        }
+        const inner = getSingleChild(child.props.children);
+        if (inner && isValidElement(inner)) {
+            const enhanced = enhanceControl(inner, options);
+            if (enhanced !== inner) {
+                return cloneElement(child, {}, enhanced);
+            }
+        }
+        return child;
+    }
+    return applyAriaProps(child, options);
+}

package/dist/components/enhanceControl.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=enhanceControl.test.d.ts.map

package/dist/components/enhanceControl.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhanceControl.test.d.ts","sourceRoot":"","sources":["../../src/components/enhanceControl.test.ts"],"names":[],"mappings":""}

package/dist/components/enhanceControl.test.js

@@ -0,0 +1,83 @@
+import { describe, expect, it } from '@jest/globals';
+import { createElement, Fragment, isValidElement } from 'react';
+import { enhanceControl } from './enhanceControl.js';
+/** Stand-in for {@link Input} — function component that forwards props to a native input. */
+function TextInput(props) {
+    return createElement('input', { type: 'text', ...props });
+}
+function propsOf(node) {
+    if (!isValidElement(node)) {
+        throw new Error('Expected a valid React element');
+    }
+    return node.props;
+}
+describe('enhanceControl', () => {
+    it('merges aria-describedby and aria-invalid on a form component', () => {
+        const result = enhanceControl(createElement(TextInput), {
+            describedBy: 'field-error',
+            invalid: true
+        });
+        expect(propsOf(result)['aria-describedby']).toBe('field-error');
+        expect(propsOf(result)['aria-invalid']).toBe(true);
+    });
+    it('includes description id in aria-describedby without setting aria-invalid', () => {
+        const result = enhanceControl(createElement(TextInput), {
+            describedBy: 'api-key-description'
+        });
+        expect(propsOf(result)['aria-describedby']).toBe('api-key-description');
+        expect(propsOf(result)['aria-invalid']).toBeUndefined();
+    });
+    it('merges description and error ids in aria-describedby', () => {
+        const result = enhanceControl(createElement(TextInput), {
+            describedBy: 'api-key-description api-key-error',
+            invalid: true
+        });
+        expect(propsOf(result)['aria-describedby']).toBe('api-key-description api-key-error');
+        expect(propsOf(result)['aria-invalid']).toBe(true);
+    });
+    it('merges with an existing aria-describedby value', () => {
+        const result = enhanceControl(createElement(TextInput, { 'aria-describedby': 'existing' }), {
+            describedBy: 'field-error'
+        });
+        expect(propsOf(result)['aria-describedby']).toBe('existing field-error');
+    });
+    it('enhances a control wrapped in a div', () => {
+        const wrapped = createElement('div', null, createElement(TextInput));
+        const result = enhanceControl(wrapped, { describedBy: 'field-error' });
+        const inner = propsOf(result).children;
+        expect(propsOf(inner)['aria-describedby']).toBe('field-error');
+    });
+    it('enhances a native input wrapped in a div', () => {
+        const wrapped = createElement('div', null, createElement('input', { type: 'text' }));
+        const result = enhanceControl(wrapped, { describedBy: 'field-error' });
+        const inner = propsOf(result).children;
+        expect(propsOf(inner)['aria-describedby']).toBe('field-error');
+    });
+    it('unwraps a single-element array', () => {
+        const result = enhanceControl([createElement(TextInput)], { describedBy: 'field-error' });
+        expect(propsOf(result)['aria-describedby']).toBe('field-error');
+    });
+    it('enhances a control wrapped in a fragment', () => {
+        const wrapped = createElement(Fragment, null, createElement(TextInput));
+        const result = enhanceControl(wrapped, { describedBy: 'field-error' });
+        const inner = propsOf(result).children;
+        expect(propsOf(inner)['aria-describedby']).toBe('field-error');
+    });
+    it('leaves multiple siblings unchanged', () => {
+        const child = [createElement(TextInput), createElement('span')];
+        const result = enhanceControl(child, { describedBy: 'field-error' });
+        expect(result).toBe(child);
+    });
+    it('sets id when the control has none', () => {
+        const result = enhanceControl(createElement('input', { type: 'checkbox' }), {
+            id: 'auto-id'
+        });
+        expect(propsOf(result).id).toBe('auto-id');
+    });
+    it('preserves an existing id', () => {
+        const result = enhanceControl(createElement('input', { id: 'existing-id', type: 'checkbox' }), {
+            id: 'auto-id'
+        });
+        expect(propsOf(result).id).toBe('existing-id');
+    });
+});

package/dist/components/useDialogFocus.d.ts

@@ -8,9 +8,10 @@ import type { RefObject } from 'react';
  */
 export declare function getFocusableElements(container: HTMLElement): HTMLElement[];
 /**
- * Traps keyboard focus within a dialog panel and restores focus on unmount.
+ * Traps keyboard focus within a dialog panel, inerts background siblings,
+ * and restores focus on unmount.
  *
- * @param panelRef - Ref attached to the dialog panel element.
+ * @param panelRef - Ref attached to the dialog overlay element.
  */
 export declare function useDialogFocus(panelRef: RefObject<HTMLElement | null>): void;
 //# sourceMappingURL=useDialogFocus.d.ts.map

package/dist/components/useDialogFocus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDialogFocus.d.ts","sourceRoot":"","sources":["../../src/components/useDialogFocus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKvC;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,EAAE,CAU1E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CA2D5E"}
+{"version":3,"file":"useDialogFocus.d.ts","sourceRoot":"","sources":["../../src/components/useDialogFocus.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AA8DvC;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,EAAE,CAU1E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CA8D5E"}

package/dist/components/useDialogFocus.js

@@ -1,5 +1,58 @@
 import { useEffect } from '@harborclient/sdk/react';
 const FOCUSABLE_SELECTOR = 'button:not([disabled]), a[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+const inertLockCounts = new WeakMap();
+/**
+ * Increments or decrements an inert lock on an element so nested dialogs
+ * do not prematurely restore interactivity on shared siblings.
+ *
+ * @param element - Element to lock or unlock.
+ * @param locked - Whether to apply or release an inert lock.
+ */
+function setInertLocked(element, locked) {
+    const count = inertLockCounts.get(element) ?? 0;
+    if (locked) {
+        inertLockCounts.set(element, count + 1);
+        element.inert = true;
+        return;
+    }
+    const next = count - 1;
+    if (next <= 0) {
+        inertLockCounts.delete(element);
+        element.inert = false;
+    }
+    else {
+        inertLockCounts.set(element, next);
+    }
+}
+/**
+ * Marks sibling elements of the overlay container as inert while the dialog is open.
+ *
+ * @param overlay - Modal overlay root element.
+ * @returns Siblings that received an inert lock from this call.
+ */
+function lockOverlaySiblings(overlay) {
+    const parent = overlay.parentElement;
+    if (!parent)
+        return [];
+    const locked = [];
+    for (const child of parent.children) {
+        if (child === overlay)
+            continue;
+        setInertLocked(child, true);
+        locked.push(child);
+    }
+    return locked;
+}
+/**
+ * Releases inert locks previously applied to overlay siblings.
+ *
+ * @param siblings - Sibling elements to unlock.
+ */
+function unlockOverlaySiblings(siblings) {
+    for (const sibling of siblings) {
+        setInertLocked(sibling, false);
+    }
+}
 /**
  * Returns visible, enabled focusable descendants of a container, excluding
  * elements inside `aria-hidden` subtrees.
@@ -19,19 +72,22 @@ export function getFocusableElements(container) {
     });
 }
 /**
- * Traps keyboard focus within a dialog panel and restores focus on unmount.
+ * Traps keyboard focus within a dialog panel, inerts background siblings,
+ * and restores focus on unmount.
  *
- * @param panelRef - Ref attached to the dialog panel element.
+ * @param panelRef - Ref attached to the dialog overlay element.
  */
 export function useDialogFocus(panelRef) {
     /**
-     * Moves initial focus into the panel, traps Tab/Shift+Tab, and restores
-     * focus to the element that opened the dialog when the panel unmounts.
+     * Moves initial focus into the panel, traps Tab/Shift+Tab, inerts sibling
+     * content, and restores focus to the element that opened the dialog when
+     * the panel unmounts.
      */
     useEffect(() => {
         const panel = panelRef.current;
         if (!panel)
             return;
+        const inertedSiblings = lockOverlaySiblings(panel);
         const previousFocus = document.activeElement;
         if (!panel.contains(document.activeElement)) {
             const focusables = getFocusableElements(panel);
@@ -73,6 +129,7 @@ export function useDialogFocus(panelRef) {
         document.addEventListener('keydown', handleKeyDown);
         return () => {
             document.removeEventListener('keydown', handleKeyDown);
+            unlockOverlaySiblings(inertedSiblings);
             if (previousFocus instanceof HTMLElement && document.contains(previousFocus)) {
                 previousFocus.focus();
             }

package/dist/components/utils.d.ts

@@ -26,4 +26,29 @@ export interface TabListKeyOptions {
  * @returns Target index when the key is handled, or null otherwise.
  */
 export declare function resolveTabListKeyAction(key: string, currentIndex: number, itemCount: number, options?: TabListKeyOptions): number | null;
+/**
+ * Result of a menu typeahead key press.
+ */
+export interface MenuTypeaheadResult {
+    /**
+     * Index of the menu item to focus.
+     */
+    index: number;
+    /**
+     * Updated typeahead buffer after appending the typed character.
+     */
+    buffer: string;
+}
+/**
+ * Resolves a printable key to the next menu item whose label matches the
+ * accumulated typeahead prefix. Search starts at the item after the current
+ * index and wraps circularly.
+ *
+ * @param labels - Visible menu item labels.
+ * @param currentIndex - Index of the currently focused item.
+ * @param key - Keyboard event key value.
+ * @param buffer - Accumulated typeahead characters from recent key presses.
+ * @returns Target index and updated buffer when matched, or null when unhandled.
+ */
+export declare function resolveMenuTypeahead(labels: string[], currentIndex: number, key: string, buffer: string): MenuTypeaheadResult | null;
 //# sourceMappingURL=utils.d.ts.map

package/dist/components/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/components/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,WAAW,QAAQ,EAAE,KAAG,QAAQ,EACmB,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAgED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,MAAM,GAAG,IAAI,CAcf"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/components/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,WAAW,QAAQ,EAAE,KAAG,QAAQ,EACmB,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAgED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,MAAM,GAAG,IAAI,CAcf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EAAE,EAChB,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,mBAAmB,GAAG,IAAI,CAc5B"}

package/dist/components/utils.js

@@ -87,3 +87,27 @@ export function resolveTabListKeyAction(key, currentIndex, itemCount, options) {
     }
     return null;
 }
+/**
+ * Resolves a printable key to the next menu item whose label matches the
+ * accumulated typeahead prefix. Search starts at the item after the current
+ * index and wraps circularly.
+ *
+ * @param labels - Visible menu item labels.
+ * @param currentIndex - Index of the currently focused item.
+ * @param key - Keyboard event key value.
+ * @param buffer - Accumulated typeahead characters from recent key presses.
+ * @returns Target index and updated buffer when matched, or null when unhandled.
+ */
+export function resolveMenuTypeahead(labels, currentIndex, key, buffer) {
+    if (labels.length === 0 || key.length !== 1 || key === ' ')
+        return null;
+    const newBuffer = buffer + key;
+    const prefix = newBuffer.toLowerCase();
+    for (let offset = 1; offset <= labels.length; offset++) {
+        const index = (currentIndex + offset) % labels.length;
+        if (labels[index].toLowerCase().startsWith(prefix)) {
+            return { index, buffer: newBuffer };
+        }
+    }
+    return null;
+}

package/dist/components/utils.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from '@jest/globals';
-import { resolveTabListKeyAction } from './utils.js';
+import { resolveMenuTypeahead, resolveTabListKeyAction } from './utils.js';
 describe('resolveTabListKeyAction', () => {
     it('returns null for unhandled keys', () => {
         expect(resolveTabListKeyAction('Enter', 0, 3)).toBeNull();
@@ -25,3 +25,20 @@ describe('resolveTabListKeyAction', () => {
         expect(resolveTabListKeyAction('End', 0, 3, { disabledIndices: [2] })).toBe(1);
     });
 });
+describe('resolveMenuTypeahead', () => {
+    const labels = ['Rename', 'Duplicate', 'Delete'];
+    it('returns null for non-printable keys', () => {
+        expect(resolveMenuTypeahead(labels, 0, 'Enter', '')).toBeNull();
+        expect(resolveMenuTypeahead(labels, 0, ' ', 'd')).toBeNull();
+    });
+    it('matches the next item whose label starts with the typed prefix', () => {
+        expect(resolveMenuTypeahead(labels, 0, 'd', '')).toEqual({ index: 1, buffer: 'd' });
+        expect(resolveMenuTypeahead(labels, 1, 'e', 'd')).toEqual({ index: 2, buffer: 'de' });
+    });
+    it('wraps the search from the current index', () => {
+        expect(resolveMenuTypeahead(labels, 2, 'r', '')).toEqual({ index: 0, buffer: 'r' });
+    });
+    it('returns null when no label matches the prefix', () => {
+        expect(resolveMenuTypeahead(labels, 0, 'z', '')).toBeNull();
+    });
+});