@aiworker/sdk 1.24.0

package/dist/ui/navigation.d.ts

@@ -0,0 +1,18 @@
+/** Pure keyboard navigation shared by list, select, menu, and tabs. No DOM here. */
+export type NavigableItem = {
+    id: string;
+    disabled?: boolean;
+};
+export type NavigationKey = 'next' | 'previous' | 'first' | 'last';
+type KeyLike = {
+    key: string;
+    ctrlKey: boolean;
+};
+/** Maps a keyboard event to a navigation step. Ctrl+N / Ctrl+P mirror the arrow keys, as in the host. */
+export declare const navigationKey: (event: KeyLike, axis?: "vertical" | "horizontal") => NavigationKey | null;
+/**
+ * Returns the id that `key` lands on from `currentId`, skipping disabled items and
+ * stopping at the edges. Returns `null` when nothing is enabled.
+ */
+export declare const moveListSelection: (items: readonly NavigableItem[], currentId: string | null, key: NavigationKey) => string | null;
+export {};

package/dist/ui/navigation.js

@@ -0,0 +1,38 @@
+/** Pure keyboard navigation shared by list, select, menu, and tabs. No DOM here. */
+/** Maps a keyboard event to a navigation step. Ctrl+N / Ctrl+P mirror the arrow keys, as in the host. */
+export const navigationKey = (event, axis = 'vertical') => {
+    const [next, previous] = axis === 'vertical' ? ['ArrowDown', 'ArrowUp'] : ['ArrowRight', 'ArrowLeft'];
+    if (event.key === next || (event.ctrlKey && event.key.toLowerCase() === 'n'))
+        return 'next';
+    if (event.key === previous || (event.ctrlKey && event.key.toLowerCase() === 'p'))
+        return 'previous';
+    if (event.key === 'Home')
+        return 'first';
+    if (event.key === 'End')
+        return 'last';
+    return null;
+};
+/**
+ * Returns the id that `key` lands on from `currentId`, skipping disabled items and
+ * stopping at the edges. Returns `null` when nothing is enabled.
+ */
+export const moveListSelection = (items, currentId, key) => {
+    const enabled = items.filter((item) => !item.disabled);
+    if (enabled.length === 0) {
+        return null;
+    }
+    const first = enabled[0];
+    const last = enabled[enabled.length - 1];
+    if (key === 'first' || !first || !last) {
+        return first?.id ?? null;
+    }
+    if (key === 'last') {
+        return last.id;
+    }
+    const index = enabled.findIndex((item) => item.id === currentId);
+    if (index === -1) {
+        return key === 'next' ? first.id : last.id;
+    }
+    const target = enabled[Math.min(enabled.length - 1, Math.max(0, index + (key === 'next' ? 1 : -1)))];
+    return target?.id ?? null;
+};

package/dist/ui/option.d.ts

@@ -0,0 +1,16 @@
+/** One popup row shared by select (`role="option"`) and menu (`role="menuitem"`). */
+type OptionSpec = {
+    id: string;
+    label: string;
+    hint?: string;
+    selected?: boolean;
+    destructive?: boolean;
+    disabled?: boolean;
+};
+export declare const createOption: (uid: string, role: "option" | "menuitem", spec: OptionSpec, on: {
+    hover: () => void;
+    pick: () => void;
+}) => HTMLButtonElement;
+/** Moves the `data-active` highlight and `aria-activedescendant`; scrolls the row into view. */
+export declare const highlightOption: (container: HTMLElement, focusOwner: HTMLElement, uid: string, id: string | null) => void;
+export {};

package/dist/ui/option.js

@@ -0,0 +1,35 @@
+import { button, el, setAttr } from "./dom.js";
+const optionId = (uid, id) => `${uid}-${id ?? ''}`;
+export const createOption = (uid, role, spec, on) => {
+    const node = button('oc-sdk-option');
+    node.id = optionId(uid, spec.id);
+    node.setAttribute('role', role);
+    node.tabIndex = -1;
+    node.disabled = Boolean(spec.disabled);
+    if (role === 'option') {
+        node.setAttribute('aria-selected', spec.selected ? 'true' : 'false');
+    }
+    node.dataset.destructive = spec.destructive ? 'true' : 'false';
+    const label = el('span', 'oc-sdk-option-label');
+    label.textContent = spec.label;
+    node.append(label);
+    if (spec.hint) {
+        const hint = el('span', 'oc-sdk-option-hint');
+        hint.textContent = spec.hint;
+        node.append(hint);
+    }
+    node.addEventListener('pointerenter', on.hover);
+    node.addEventListener('click', on.pick);
+    return node;
+};
+/** Moves the `data-active` highlight and `aria-activedescendant`; scrolls the row into view. */
+export const highlightOption = (container, focusOwner, uid, id) => {
+    const target = optionId(uid, id);
+    for (const child of Array.from(container.children)) {
+        if (child instanceof HTMLElement && child.classList.contains('oc-sdk-option')) {
+            child.dataset.active = child.id === target ? 'true' : 'false';
+        }
+    }
+    setAttr(focusOwner, 'aria-activedescendant', id ? target : null);
+    container.querySelector('[data-active="true"]')?.scrollIntoView({ block: 'nearest' });
+};

package/dist/ui/popup.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Attaches `popup` next to `trigger` and wires the ways it closes: outside press,
+ * viewport resize, or scroll. Returns the disposer; the caller decides what `close` does.
+ */
+export declare const openPopup: (host: Element, trigger: HTMLElement, popup: HTMLElement, close: () => void) => (() => void);

package/dist/ui/popup.js

@@ -0,0 +1,43 @@
+import { onOutsideClick } from "./dom.js";
+/** Places a fixed popup under `trigger`; flips above when the room below is too small. */
+const placePopup = (popup, trigger) => {
+    const rect = trigger.getBoundingClientRect();
+    popup.style.minWidth = `${Math.round(rect.width)}px`;
+    popup.style.left = `${Math.round(rect.left)}px`;
+    popup.style.top = `${Math.round(rect.bottom + 4)}px`;
+    const height = popup.offsetHeight;
+    const roomBelow = window.innerHeight - rect.bottom - 8;
+    if (height > roomBelow && rect.top - 8 > roomBelow) {
+        popup.style.top = `${Math.max(8, Math.round(rect.top - 4 - height))}px`;
+    }
+    const overflow = rect.left + popup.offsetWidth - window.innerWidth + 8;
+    if (overflow > 0) {
+        popup.style.left = `${Math.max(8, Math.round(rect.left - overflow))}px`;
+    }
+};
+/**
+ * Attaches `popup` next to `trigger` and wires the ways it closes: outside press,
+ * viewport resize, or scroll. Returns the disposer; the caller decides what `close` does.
+ */
+export const openPopup = (host, trigger, popup, close) => {
+    host.append(popup);
+    placePopup(popup, trigger);
+    const stopOutside = onOutsideClick(host, close);
+    const onResize = () => {
+        close();
+    };
+    const onScroll = (event) => {
+        if (event.target instanceof Node && popup.contains(event.target)) {
+            return;
+        }
+        close();
+    };
+    window.addEventListener('resize', onResize);
+    window.addEventListener('scroll', onScroll, true);
+    return () => {
+        stopOutside();
+        window.removeEventListener('resize', onResize);
+        window.removeEventListener('scroll', onScroll, true);
+        popup.remove();
+    };
+};

package/dist/ui/progress.d.ts

@@ -0,0 +1,11 @@
+import { type Tone } from './badge.ts';
+import { type Handle } from './dom.ts';
+export type ProgressProps = {
+    /** 0 to 100. Values outside that range are clamped. */
+    value: number;
+    tone?: Tone;
+    label?: string;
+};
+export type ProgressHandle = Handle<ProgressProps>;
+export declare const clampProgress: (value: number) => number;
+export declare const mountProgress: (root: Element, initial: ProgressProps) => ProgressHandle;

package/dist/ui/progress.js

@@ -0,0 +1,44 @@
+import { applyTone } from "./badge.js";
+import { el, ensureStyle, setText } from "./dom.js";
+import { UI_CSS } from "./style.js";
+export const clampProgress = (value) => (Number.isFinite(value) ? Math.min(100, Math.max(0, Math.round(value))) : 0);
+export const mountProgress = (root, initial) => {
+    ensureStyle(UI_CSS);
+    let props = initial;
+    const node = el('div', 'oc-sdk oc-sdk-progress');
+    const caption = el('div', 'oc-sdk-progress-label');
+    const label = el('span');
+    const percent = el('span');
+    caption.append(label, percent);
+    const track = el('div', 'oc-sdk-progress-track');
+    track.setAttribute('role', 'progressbar');
+    track.setAttribute('aria-valuemin', '0');
+    track.setAttribute('aria-valuemax', '100');
+    const fill = el('div', 'oc-sdk-progress-fill');
+    track.append(fill);
+    node.append(caption, track);
+    root.append(node);
+    const paint = () => {
+        const value = clampProgress(props.value);
+        applyTone(fill, props.tone);
+        fill.style.transform = `scaleX(${value / 100})`;
+        track.setAttribute('aria-valuenow', String(value));
+        if (props.label)
+            track.setAttribute('aria-label', props.label);
+        else
+            track.removeAttribute('aria-label');
+        setText(label, props.label);
+        setText(percent, `${value}%`);
+        caption.hidden = !props.label;
+    };
+    paint();
+    return {
+        update: (next) => {
+            props = { ...props, ...next };
+            paint();
+        },
+        dispose: () => {
+            node.remove();
+        },
+    };
+};

package/dist/ui/search.d.ts

@@ -0,0 +1,11 @@
+import { type Handle } from './dom.ts';
+export type SearchFieldProps = {
+    value: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+    /** Accessible name. Falls back to the placeholder. */
+    label?: string;
+    autofocus?: boolean;
+};
+export type SearchFieldHandle = Handle<SearchFieldProps>;
+export declare const mountSearchField: (root: Element, initial: SearchFieldProps) => SearchFieldHandle;

package/dist/ui/search.js

@@ -0,0 +1,62 @@
+import { button, el, ensureStyle, setAttr } from "./dom.js";
+import { icon } from "./icons.js";
+import { UI_CSS } from "./style.js";
+export const mountSearchField = (root, initial) => {
+    ensureStyle(UI_CSS);
+    let props = initial;
+    const wrap = el('div', 'oc-sdk oc-sdk-search');
+    const input = el('input', 'oc-sdk-input');
+    input.type = 'text';
+    input.spellcheck = false;
+    input.autocomplete = 'off';
+    input.setAttribute('role', 'searchbox');
+    const clear = button('oc-sdk-search-clear');
+    clear.append(icon('close', 14));
+    clear.tabIndex = -1;
+    wrap.append(icon('search', 16, 'oc-sdk-search-icon'), input, clear);
+    root.append(wrap);
+    const paint = () => {
+        const placeholder = props.placeholder ?? 'Search';
+        setAttr(input, 'placeholder', placeholder);
+        input.setAttribute('aria-label', props.label ?? placeholder);
+        clear.setAttribute('aria-label', 'Clear search');
+        if (input.value !== props.value) {
+            input.value = props.value;
+        }
+        wrap.dataset.active = props.value.trim() === '' ? 'false' : 'true';
+    };
+    const clearValue = () => {
+        if (props.value !== '') {
+            props.onChange('');
+        }
+        input.focus();
+    };
+    const onInput = () => {
+        props.onChange(input.value);
+    };
+    const onKeyDown = (event) => {
+        if (event.key === 'Escape' && input.value !== '') {
+            event.preventDefault();
+            clearValue();
+        }
+    };
+    input.addEventListener('input', onInput);
+    input.addEventListener('keydown', onKeyDown);
+    clear.addEventListener('click', clearValue);
+    paint();
+    if (props.autofocus) {
+        input.focus();
+    }
+    return {
+        update: (next) => {
+            props = { ...props, ...next };
+            paint();
+        },
+        dispose: () => {
+            input.removeEventListener('input', onInput);
+            input.removeEventListener('keydown', onKeyDown);
+            clear.removeEventListener('click', clearValue);
+            wrap.remove();
+        },
+    };
+};

package/dist/ui/select.d.ts

@@ -0,0 +1,22 @@
+import { type Handle } from './dom.ts';
+export type SelectOption = {
+    id: string;
+    label: string;
+    /** Small muted text at the right of the option. */
+    hint?: string;
+};
+export type SelectProps = {
+    label?: string;
+    value: string | null;
+    options: SelectOption[];
+    onChange: (id: string) => void;
+    placeholder?: string;
+    /** Adds a search box at the top of the popup. */
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    disabled?: boolean;
+};
+export type SelectHandle = Handle<SelectProps>;
+/** Case-insensitive substring match on label and id. Empty query keeps every option. */
+export declare const filterSelectOptions: (options: readonly SelectOption[], query: string) => SelectOption[];
+export declare const mountSelect: (root: Element, initial: SelectProps) => SelectHandle;

package/dist/ui/select.js

@@ -0,0 +1,168 @@
+import { button, clearNode, el, ensureStyle, setText } from "./dom.js";
+import { icon } from "./icons.js";
+import { moveListSelection, navigationKey } from "./navigation.js";
+import { createOption, highlightOption } from "./option.js";
+import { openPopup } from "./popup.js";
+import { UI_CSS } from "./style.js";
+/** Case-insensitive substring match on label and id. Empty query keeps every option. */
+export const filterSelectOptions = (options, query) => {
+    const needle = query.trim().toLowerCase();
+    if (!needle) {
+        return [...options];
+    }
+    return options.filter((option) => (option.label.toLowerCase().includes(needle) || option.id.toLowerCase().includes(needle)));
+};
+let selectCount = 0;
+export const mountSelect = (root, initial) => {
+    ensureStyle(UI_CSS);
+    let props = initial;
+    const uid = `oc-sdk-select-${selectCount += 1}`;
+    const wrap = el('div', 'oc-sdk oc-sdk-select');
+    const caption = el('span', 'oc-sdk-field-label');
+    caption.id = `${uid}-label`;
+    const trigger = button('oc-sdk-trigger');
+    trigger.setAttribute('aria-haspopup', 'listbox');
+    trigger.setAttribute('aria-labelledby', caption.id);
+    const value = el('span', 'oc-sdk-trigger-value');
+    trigger.append(value, icon('chevron', 14, 'oc-sdk-trigger-chevron'));
+    wrap.append(caption, trigger);
+    root.append(wrap);
+    let query = '';
+    let activeId = null;
+    let closePopup = null;
+    const popup = el('div', 'oc-sdk oc-sdk-popup');
+    const searchSlot = el('div', 'oc-sdk-popup-search');
+    const search = el('input', 'oc-sdk-input');
+    search.type = 'text';
+    search.autocomplete = 'off';
+    searchSlot.append(search);
+    const listbox = el('div');
+    listbox.setAttribute('role', 'listbox');
+    listbox.tabIndex = -1;
+    popup.append(listbox);
+    const visible = () => filterSelectOptions(props.options, props.searchable ? query : '');
+    const focusOwner = () => (props.searchable ? search : listbox);
+    const setActive = (id) => {
+        activeId = id;
+        highlightOption(listbox, focusOwner(), uid, id);
+    };
+    const paintOptions = () => {
+        clearNode(listbox);
+        const options = visible();
+        if (options.length === 0) {
+            const empty = el('div', 'oc-sdk-popup-empty');
+            empty.textContent = 'No matches';
+            listbox.append(empty);
+        }
+        for (const option of options) {
+            listbox.append(createOption(uid, 'option', { ...option, selected: option.id === props.value }, {
+                hover: () => setActive(option.id),
+                pick: () => pick(option.id),
+            }));
+        }
+        setActive(options.some((option) => option.id === activeId) ? activeId : options[0]?.id ?? null);
+    };
+    const close = () => {
+        // Removing a focused row fires `focusout` synchronously from inside the disposer, and
+        // that handler calls `close` again. Clearing the slot first makes the re-entry a no-op
+        // instead of a second `popup.remove()` that throws before the pick reaches `onChange`.
+        const dispose = closePopup;
+        closePopup = null;
+        dispose?.();
+        query = '';
+        search.value = '';
+        trigger.setAttribute('aria-expanded', 'false');
+    };
+    const open = () => {
+        if (closePopup || props.disabled) {
+            return;
+        }
+        activeId = props.value;
+        search.placeholder = props.searchPlaceholder ?? 'Search';
+        if (props.searchable)
+            popup.prepend(searchSlot);
+        else
+            searchSlot.remove();
+        paintOptions();
+        closePopup = openPopup(wrap, trigger, popup, close);
+        trigger.setAttribute('aria-expanded', 'true');
+        focusOwner().focus();
+    };
+    const pick = (id) => {
+        close();
+        trigger.focus();
+        if (id !== props.value)
+            props.onChange(id);
+    };
+    const onTriggerClick = () => {
+        if (closePopup)
+            close();
+        else
+            open();
+    };
+    const onTriggerKey = (event) => {
+        if (!closePopup && navigationKey(event)) {
+            event.preventDefault();
+            open();
+        }
+    };
+    const onPopupKey = (event) => {
+        const step = navigationKey(event);
+        if (step) {
+            event.preventDefault();
+            setActive(moveListSelection(visible(), activeId, step));
+        }
+        else if (event.key === 'Enter') {
+            event.preventDefault();
+            if (activeId)
+                pick(activeId);
+        }
+        else if (event.key === 'Escape') {
+            event.preventDefault();
+            close();
+            trigger.focus();
+        }
+        else if (props.searchable && event.target !== search && event.key.length === 1 && !event.ctrlKey && !event.metaKey) {
+            search.focus();
+        }
+    };
+    const onSearchInput = () => {
+        query = search.value;
+        paintOptions();
+    };
+    const onFocusOut = (event) => {
+        if (closePopup && !(event.relatedTarget instanceof Node && wrap.contains(event.relatedTarget)))
+            close();
+    };
+    const paint = () => {
+        setText(caption, props.label);
+        caption.hidden = !props.label;
+        const current = props.options.find((option) => option.id === props.value);
+        setText(value, current?.label ?? props.placeholder ?? 'Select');
+        value.dataset.empty = current ? 'false' : 'true';
+        trigger.disabled = Boolean(props.disabled);
+        if (closePopup)
+            paintOptions();
+    };
+    trigger.addEventListener('click', onTriggerClick);
+    trigger.addEventListener('keydown', onTriggerKey);
+    popup.addEventListener('keydown', onPopupKey);
+    search.addEventListener('input', onSearchInput);
+    wrap.addEventListener('focusout', onFocusOut);
+    paint();
+    return {
+        update: (next) => {
+            props = { ...props, ...next };
+            paint();
+        },
+        dispose: () => {
+            close();
+            trigger.removeEventListener('click', onTriggerClick);
+            trigger.removeEventListener('keydown', onTriggerKey);
+            popup.removeEventListener('keydown', onPopupKey);
+            search.removeEventListener('input', onSearchInput);
+            wrap.removeEventListener('focusout', onFocusOut);
+            wrap.remove();
+        },
+    };
+};

package/dist/ui/separator.d.ts

@@ -0,0 +1,6 @@
+import { type Handle } from './dom.ts';
+export type SeparatorProps = {
+    label?: string;
+};
+export type SeparatorHandle = Handle<SeparatorProps>;
+export declare const mountSeparator: (root: Element, initial?: SeparatorProps) => SeparatorHandle;

package/dist/ui/separator.js

@@ -0,0 +1,26 @@
+import { el, ensureStyle, setText } from "./dom.js";
+import { UI_CSS } from "./style.js";
+export const mountSeparator = (root, initial = {}) => {
+    ensureStyle(UI_CSS);
+    let props = initial;
+    const node = el('div', 'oc-sdk oc-sdk-separator');
+    node.setAttribute('role', 'separator');
+    const label = el('span');
+    node.append(label);
+    root.append(node);
+    const paint = () => {
+        setText(label, props.label);
+        label.hidden = !props.label;
+        node.dataset.labeled = props.label ? 'true' : 'false';
+    };
+    paint();
+    return {
+        update: (next) => {
+            props = { ...props, ...next };
+            paint();
+        },
+        dispose: () => {
+            node.remove();
+        },
+    };
+};

package/dist/ui/spinner.d.ts

@@ -0,0 +1,8 @@
+import { type Handle } from './dom.ts';
+export type SpinnerProps = {
+    size?: 'sm' | 'default';
+    /** Text next to the ring. Also the accessible name. */
+    label?: string;
+};
+export type SpinnerHandle = Handle<SpinnerProps>;
+export declare const mountSpinner: (root: Element, initial?: SpinnerProps) => SpinnerHandle;

package/dist/ui/spinner.js

@@ -0,0 +1,29 @@
+import { el, ensureStyle, setText } from "./dom.js";
+import { UI_CSS } from "./style.js";
+export const mountSpinner = (root, initial = {}) => {
+    ensureStyle(UI_CSS);
+    let props = initial;
+    const node = el('span', 'oc-sdk oc-sdk-spinner');
+    node.setAttribute('role', 'status');
+    const ring = el('span', 'oc-sdk-spinner-ring');
+    ring.setAttribute('aria-hidden', 'true');
+    const label = el('span');
+    node.append(ring, label);
+    root.append(node);
+    const paint = () => {
+        node.dataset.size = props.size ?? 'default';
+        setText(label, props.label);
+        label.hidden = !props.label;
+        node.setAttribute('aria-label', props.label ?? 'Loading');
+    };
+    paint();
+    return {
+        update: (next) => {
+            props = { ...props, ...next };
+            paint();
+        },
+        dispose: () => {
+            node.remove();
+        },
+    };
+};

package/dist/ui/style.d.ts

@@ -0,0 +1 @@
+export declare const UI_CSS: string;