@north-light/crouter 0.3.192 → 0.3.193

package/dist/pages/elements/options.js

@@ -0,0 +1,604 @@
+/**
+ * `<crtr-options>` — the agent asks a multiple-choice question.
+ *
+ * A port of the interaction kit's `agent-options` (Northlight
+ * `apps/gateway/components/agent-ui/agent-options.tsx` @ `3705fe9e2`) onto a dependency-free
+ * custom element, keeping its two load-bearing decisions:
+ *
+ *  - **The control's silhouette tells the truth about how many answers are wanted.**
+ *    Single-select is a radio group, multi-select is checkbox rows, so the element never has
+ *    to say "pick one" in prose.
+ *  - **"This one, but…" is a first-class answer.** Every option carries the comment
+ *    affordance in place, rather than making the user squeeze a caveat into the freetext box
+ *    at the bottom. The affordance is quiet until you reach for it — it reveals on hover, on
+ *    keyboard focus, and on the `j`/`k` cursor — and stays lit once a comment exists, which
+ *    is the whole "there is a note here" signal at a glance.
+ *
+ * Selection is kept in the agent's authored order, never click order, so the response reads
+ * the way the question did. `freetext` is absent rather than empty: the response says whether
+ * the user wrote something, not whether the box existed.
+ */
+import { setComment, findComment } from '../comments.js';
+import { respond } from '../host.js';
+import { registerElement } from '../register.js';
+import { readSlotConfig, readSlotId } from '../slot-config.js';
+const BUBBLE_PLUS = '<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M2.5 3.5h11v7h-6l-3 2.5v-2.5h-2z"/><path d="M8 5.5v3M6.5 7h3"/></svg>';
+const BUBBLE_TEXT = '<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M2.5 3.5h11v7h-6l-3 2.5v-2.5h-2z"/><path d="M5 6.25h6M5 8.25h4"/></svg>';
+const STYLE = `
+  :host {
+    display: block;
+  }
+
+  [part="container"] {
+    display: grid;
+    gap: var(--crtr-space-3);
+  }
+
+  [part="list"] {
+    display: grid;
+    gap: var(--crtr-space-2);
+  }
+
+  [part="option"] {
+    position: relative;
+    display: flex;
+    align-items: flex-start;
+    gap: var(--crtr-space-3);
+    padding: var(--crtr-space-2) var(--crtr-space-3);
+    background: var(--crtr-color-surface);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-medium);
+    transition: background-color 120ms ease, border-color 120ms ease;
+  }
+
+  [part="option"]:hover,
+  [part="option"][data-active="true"] {
+    background: var(--crtr-color-surface-hover);
+  }
+
+  [part="option"][data-selected="true"] {
+    border-color: var(--crtr-color-accent);
+    background: color-mix(in srgb, var(--crtr-color-accent) 10%, var(--crtr-color-surface));
+  }
+
+  [part="option-label"] {
+    display: flex;
+    flex: 1;
+    align-items: flex-start;
+    gap: var(--crtr-space-3);
+    cursor: pointer;
+  }
+
+  [part="option-control"] {
+    margin: 0;
+    margin-top: 0.15em;
+    accent-color: var(--crtr-color-accent);
+  }
+
+  [part="option-control"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: 2px;
+  }
+
+  [part="option-text"] {
+    display: grid;
+    gap: var(--crtr-space-1);
+  }
+
+  [part="option-title"] {
+    font-weight: 500;
+  }
+
+  [part="option-description"] {
+    color: var(--crtr-color-text-muted);
+    font-size: 0.9em;
+  }
+
+  [part="comment"] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex: none;
+    width: 1.5rem;
+    height: 1.5rem;
+    padding: 0;
+    color: var(--crtr-color-text-muted);
+    background: transparent;
+    border: 1px solid transparent;
+    border-radius: var(--crtr-radius-small);
+    opacity: 0;
+    cursor: pointer;
+    transition: opacity 120ms ease, color 120ms ease, background-color 120ms ease;
+  }
+
+  [part="option"]:hover [part="comment"],
+  [part="option"][data-active="true"] [part="comment"],
+  [part="option"]:focus-within [part="comment"],
+  [part="comment"][data-state="commented"],
+  [part="comment"][aria-expanded="true"] {
+    opacity: 1;
+  }
+
+  [part="comment"]:hover {
+    background: var(--crtr-color-surface-hover);
+    border-color: var(--crtr-color-border);
+  }
+
+  [part="comment"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: 1px;
+  }
+
+  [part="comment"][data-state="commented"] {
+    color: var(--crtr-color-accent);
+  }
+
+  [part="comment"] svg {
+    width: 0.9rem;
+    height: 0.9rem;
+    fill: none;
+    stroke: currentColor;
+    stroke-width: 1.25;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+  }
+
+  [part="comment-popover"] {
+    position: absolute;
+    top: calc(100% + var(--crtr-space-1));
+    right: 0;
+    z-index: 2;
+    display: grid;
+    gap: var(--crtr-space-2);
+    width: min(20rem, 100%);
+    padding: var(--crtr-space-3);
+    background: var(--crtr-color-background);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-medium);
+    box-shadow: var(--crtr-shadow);
+  }
+
+  [part="comment-popover"][hidden] {
+    display: none;
+  }
+
+  [part="comment-subject"] {
+    margin: 0;
+    color: var(--crtr-color-text-muted);
+    font-family: var(--crtr-font-mono);
+    font-size: 0.75em;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+  }
+
+  [part="comment-input"],
+  [part="freetext-input"] {
+    width: 100%;
+    box-sizing: border-box;
+    padding: var(--crtr-space-2);
+    color: var(--crtr-color-text);
+    font: inherit;
+    background: var(--crtr-color-surface);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-small);
+    resize: vertical;
+  }
+
+  [part="comment-input"] {
+    min-height: 4.5rem;
+  }
+
+  [part="freetext-input"] {
+    min-height: 4rem;
+  }
+
+  [part="comment-input"]:focus-visible,
+  [part="freetext-input"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: -1px;
+  }
+
+  [part="comment-actions"] {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--crtr-space-2);
+  }
+
+  [part="comment-hint"] {
+    color: var(--crtr-color-text-muted);
+    font-family: var(--crtr-font-mono);
+    font-size: 0.75em;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+  }
+
+  [part="comment-cancel"],
+  [part="comment-save"] {
+    padding: var(--crtr-space-1) var(--crtr-space-2);
+    font: inherit;
+    font-size: 0.9em;
+    border-radius: var(--crtr-radius-small);
+    cursor: pointer;
+  }
+
+  [part="comment-cancel"] {
+    color: var(--crtr-color-text-muted);
+    background: transparent;
+    border: 1px solid transparent;
+  }
+
+  [part="comment-cancel"]:hover {
+    color: var(--crtr-color-text);
+    background: var(--crtr-color-surface-hover);
+  }
+
+  [part="comment-save"] {
+    color: var(--crtr-color-accent-contrast);
+    background: var(--crtr-color-accent);
+    border: 1px solid var(--crtr-color-accent);
+  }
+
+  [part="comment-cancel"]:focus-visible,
+  [part="comment-save"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: 1px;
+  }
+
+  [part="freetext"] {
+    display: grid;
+    gap: var(--crtr-space-1);
+  }
+
+  [part="freetext-label"] {
+    color: var(--crtr-color-text-muted);
+    font-size: 0.85em;
+  }
+
+  [part="unavailable"] {
+    padding: var(--crtr-space-3);
+    color: var(--crtr-color-text-muted);
+    background: var(--crtr-color-surface);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-medium);
+  }
+
+  [part="reason"] {
+    color: var(--crtr-color-text);
+    font-family: var(--crtr-font-mono);
+  }
+`;
+let groupCounter = 0;
+/**
+ * Whether a key belongs to something being written in rather than to the list grammar.
+ * The option controls are real radios and checkboxes, so this deliberately admits them —
+ * only prose entry (the comment box, the freetext box) swallows `j`/`k`/`x`/`c`.
+ */
+function isTextEntry(target) {
+    if (target instanceof HTMLTextAreaElement)
+        return true;
+    if (target instanceof HTMLElement && target.isContentEditable)
+        return true;
+    if (!(target instanceof HTMLInputElement))
+        return false;
+    return target.type !== 'checkbox' && target.type !== 'radio';
+}
+class CrtrOptionsElement extends HTMLElement {
+    #shadow;
+    #config;
+    #slotId;
+    #rows = new Map();
+    #order = [];
+    #selected = [];
+    #comments = [];
+    #freetext;
+    #activeId;
+    #commentingId;
+    #built = false;
+    constructor() {
+        super();
+        this.#shadow = this.attachShadow({ mode: 'open' });
+    }
+    connectedCallback() {
+        if (this.#built)
+            return;
+        this.#built = true;
+        this.#slotId = readSlotId(this);
+        const read = readSlotConfig(this);
+        if (read.status !== 'ok') {
+            this.#renderUnavailable(read.reason);
+            return;
+        }
+        const config = read.config;
+        if (!Array.isArray(config.options) || config.options.length === 0) {
+            this.#renderUnavailable('options config lists no options');
+            return;
+        }
+        this.#config = config;
+        this.#order = config.options.map((option) => option.id);
+        this.#render(config);
+        this.#sync();
+    }
+    disconnectedCallback() {
+        document.removeEventListener('pointerdown', this.#onDocumentPointerDown, true);
+    }
+    /** The named state for a config this element cannot render — never a thrown error. */
+    #renderUnavailable(reason) {
+        const style = document.createElement('style');
+        style.textContent = STYLE;
+        const container = document.createElement('div');
+        container.part.add('unavailable');
+        container.setAttribute('role', 'status');
+        const detail = document.createElement('span');
+        detail.part.add('reason');
+        detail.textContent = reason;
+        container.append('Options unavailable: ', detail);
+        this.#shadow.replaceChildren(style, container);
+    }
+    #render(config) {
+        const style = document.createElement('style');
+        style.textContent = STYLE;
+        const container = document.createElement('div');
+        container.part.add('container');
+        const list = document.createElement('div');
+        list.part.add('list');
+        if (config.mode === 'single')
+            list.setAttribute('role', 'radiogroup');
+        groupCounter += 1;
+        const group = `crtr-options-${groupCounter}`;
+        for (const option of config.options)
+            list.append(this.#renderOption(config, option, group));
+        container.append(list);
+        if (config.allowFreetext === true)
+            container.append(this.#renderFreetext(config));
+        // The grammar lives on the container, so it reaches every row and never escapes the
+        // shadow root: `j`/`k` move the cursor, `x` toggles it, `c` comments on it.
+        container.addEventListener('keydown', (event) => this.#onKeydown(event));
+        this.#shadow.replaceChildren(style, container);
+    }
+    #renderOption(config, option, group) {
+        const root = document.createElement('div');
+        root.part.add('option');
+        root.dataset.optionId = option.id;
+        const label = document.createElement('label');
+        label.part.add('option-label');
+        const control = document.createElement('input');
+        control.part.add('option-control');
+        control.type = config.mode === 'single' ? 'radio' : 'checkbox';
+        control.name = group;
+        control.value = option.id;
+        control.addEventListener('change', () => this.#toggle(option.id, control.checked));
+        control.addEventListener('focus', () => this.#setActive(option.id));
+        const text = document.createElement('span');
+        text.part.add('option-text');
+        const title = document.createElement('span');
+        title.part.add('option-title');
+        title.textContent = option.label;
+        text.append(title);
+        if (option.description !== undefined && option.description !== '') {
+            const description = document.createElement('span');
+            description.part.add('option-description');
+            description.textContent = option.description;
+            text.append(description);
+        }
+        label.append(control, text);
+        const comment = document.createElement('button');
+        comment.part.add('comment');
+        comment.type = 'button';
+        comment.setAttribute('aria-haspopup', 'dialog');
+        comment.addEventListener('click', () => {
+            if (this.#commentingId === option.id)
+                this.#closeComment();
+            else
+                this.#openComment(option.id);
+        });
+        const popover = document.createElement('div');
+        popover.part.add('comment-popover');
+        popover.setAttribute('role', 'dialog');
+        popover.hidden = true;
+        const subject = document.createElement('p');
+        subject.part.add('comment-subject');
+        subject.textContent = `Comment on ${option.label}`;
+        popover.setAttribute('aria-label', subject.textContent);
+        const input = document.createElement('textarea');
+        input.part.add('comment-input');
+        input.placeholder = 'What should the agent know about this?';
+        input.addEventListener('keydown', (event) => {
+            if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+                event.preventDefault();
+                this.#commitComment(option.id);
+                return;
+            }
+            if (event.key === 'Escape') {
+                event.preventDefault();
+                this.#closeComment();
+            }
+        });
+        const actions = document.createElement('div');
+        actions.part.add('comment-actions');
+        const hint = document.createElement('span');
+        hint.part.add('comment-hint');
+        const buttons = document.createElement('span');
+        const cancel = document.createElement('button');
+        cancel.part.add('comment-cancel');
+        cancel.type = 'button';
+        cancel.textContent = 'Cancel';
+        cancel.addEventListener('click', () => this.#closeComment());
+        const save = document.createElement('button');
+        save.part.add('comment-save');
+        save.type = 'button';
+        save.textContent = 'Save';
+        save.addEventListener('click', () => this.#commitComment(option.id));
+        buttons.append(cancel, save);
+        actions.append(hint, buttons);
+        popover.append(subject, input, actions);
+        root.append(label, comment, popover);
+        root.addEventListener('mouseenter', () => this.#setActive(option.id));
+        root.addEventListener('mouseleave', () => this.#clearActive(option.id));
+        this.#rows.set(option.id, { id: option.id, label: option.label, root, control, comment, popover, input, hint });
+        return root;
+    }
+    #renderFreetext(config) {
+        const wrapper = document.createElement('label');
+        wrapper.part.add('freetext');
+        const label = document.createElement('span');
+        label.part.add('freetext-label');
+        label.textContent = config.freetextLabel ?? 'Something else';
+        const input = document.createElement('textarea');
+        input.part.add('freetext-input');
+        input.placeholder = config.freetextPlaceholder ?? 'Answer in your own words…';
+        input.addEventListener('input', () => {
+            // Absent rather than empty — see the note on `freetext` in the response type.
+            this.#freetext = input.value === '' ? undefined : input.value;
+            this.#emit();
+        });
+        wrapper.append(label, input);
+        return wrapper;
+    }
+    #onKeydown(event) {
+        if (event.metaKey || event.ctrlKey || event.altKey)
+            return;
+        if (isTextEntry(event.target))
+            return;
+        const key = event.key.toLowerCase();
+        const current = this.#activeId ?? this.#selected.at(-1) ?? this.#order[0];
+        if (current === undefined)
+            return;
+        if (key === 'j' || key === 'k') {
+            event.preventDefault();
+            const index = Math.max(0, this.#order.indexOf(current));
+            const step = key === 'j' ? 1 : -1;
+            const next = this.#order[(index + step + this.#order.length) % this.#order.length];
+            this.#setActive(next);
+            this.#rows.get(next)?.control.focus();
+            return;
+        }
+        if (key === 'x') {
+            event.preventDefault();
+            const selected = this.#selected.includes(current);
+            this.#toggle(current, this.#config?.mode === 'single' ? true : !selected);
+            return;
+        }
+        if (key === 'c') {
+            event.preventDefault();
+            this.#openComment(current);
+        }
+    }
+    #setActive(optionId) {
+        if (this.#activeId === optionId)
+            return;
+        this.#activeId = optionId;
+        this.#sync();
+    }
+    #clearActive(optionId) {
+        if (this.#activeId !== optionId)
+            return;
+        this.#activeId = undefined;
+        this.#sync();
+    }
+    #toggle(optionId, selected) {
+        if (this.#config === undefined)
+            return;
+        if (this.#config.mode === 'single') {
+            this.#selected = [optionId];
+        }
+        else {
+            const next = selected
+                ? [...this.#selected, optionId]
+                : this.#selected.filter((id) => id !== optionId);
+            // Kept in the agent's authored order, so the response reads the way the question did
+            // rather than in click order.
+            this.#selected = this.#order.filter((id) => next.includes(id));
+        }
+        this.#setActive(optionId);
+        this.#sync();
+        this.#emit();
+    }
+    /**
+     * A press anywhere but the open box and its trigger closes the box without committing,
+     * matching the kit's popover. It listens on the document rather than on this element,
+     * because "anywhere else" includes the rest of the page: `pointerdown` is composed, so the
+     * path still names the shadow nodes an inside press went through.
+     */
+    #onDocumentPointerDown = (event) => {
+        if (this.#commentingId === undefined)
+            return;
+        const row = this.#rows.get(this.#commentingId);
+        if (row === undefined)
+            return;
+        const path = event.composedPath();
+        if (path.includes(row.popover) || path.includes(row.comment))
+            return;
+        // No focus restore: the press is on its way somewhere else, and pulling focus back to
+        // the trigger would fight it.
+        this.#closeComment(false);
+    };
+    #openComment(optionId) {
+        const row = this.#rows.get(optionId);
+        if (row === undefined)
+            return;
+        if (this.#commentingId === undefined) {
+            document.addEventListener('pointerdown', this.#onDocumentPointerDown, true);
+        }
+        this.#commentingId = optionId;
+        this.#activeId = optionId;
+        // Seeded from the saved comment every time it opens.
+        row.input.value = findComment(this.#comments, anchorFor(optionId))?.text ?? '';
+        this.#sync();
+        row.input.focus();
+    }
+    #closeComment(restoreFocus = true) {
+        if (this.#commentingId === undefined)
+            return;
+        const row = this.#rows.get(this.#commentingId);
+        this.#commentingId = undefined;
+        document.removeEventListener('pointerdown', this.#onDocumentPointerDown, true);
+        this.#sync();
+        if (restoreFocus)
+            row?.comment.focus();
+    }
+    #commitComment(optionId) {
+        const row = this.#rows.get(optionId);
+        if (row === undefined)
+            return;
+        // Clearing the box deletes the comment — `setComment` treats empty text as removal, so
+        // there is no separate destructive control.
+        this.#comments = setComment(this.#comments, anchorFor(optionId), row.input.value);
+        this.#closeComment();
+        this.#emit();
+    }
+    /** Paint every row from local state; local state is authoritative for rendering. */
+    #sync() {
+        for (const row of this.#rows.values()) {
+            const selected = this.#selected.includes(row.id);
+            row.control.checked = selected;
+            row.root.dataset.selected = String(selected);
+            row.root.dataset.active = String(this.#activeId === row.id);
+            const comment = findComment(this.#comments, anchorFor(row.id));
+            row.comment.dataset.state = comment === undefined ? 'empty' : 'commented';
+            row.comment.innerHTML = comment === undefined ? BUBBLE_PLUS : BUBBLE_TEXT;
+            row.comment.setAttribute('aria-label', comment === undefined ? `Comment on ${row.label}` : `Edit comment on ${row.label}`);
+            const open = this.#commentingId === row.id;
+            row.comment.setAttribute('aria-expanded', String(open));
+            row.popover.hidden = !open;
+            row.hint.textContent = comment === undefined ? '\u2318\u21b5 to save' : 'empty to delete';
+        }
+    }
+    /** The complete current response, on every user change — never a delta. */
+    #emit() {
+        if (this.#slotId === undefined)
+            return;
+        const response = {
+            selectedOptionIds: [...this.#selected],
+            comments: this.#comments.map((comment) => ({ ...comment })),
+        };
+        if (this.#config?.allowFreetext === true && this.#freetext !== undefined) {
+            response.freetext = this.#freetext;
+        }
+        respond(this.#slotId, response);
+    }
+}
+function anchorFor(optionId) {
+    return { kind: 'option', optionId };
+}
+registerElement('crtr-options', CrtrOptionsElement);

package/dist/pages/elements/pages.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `<crtr-pages>` / `<crtr-page>` — the page's own pager, and the only thing that submits.
+ *
+ * A response-bearing page wraps its slots in exactly one `<crtr-pages>` containing one or
+ * more `<crtr-page>` steps. This element shows one step at a time, carries the step
+ * progress and the forward/back affordances, and renders the submit affordance on the
+ * final step — the in-document chrome, and nothing else. Dismiss and save are host chrome
+ * (a frame around the page, not markup inside it) and never appear here.
+ *
+ * **Flipping steps is the same motion as flipping tickets, one level down.** The inbox is
+ * a pager over pending pages; this is a pager over the steps of one page. So the grammar is
+ * deliberately the narrow one both levels share — go to the next unit of work, go back to
+ * the previous one, submit — with no third way to move. `n` / `p` are the keys, matching the
+ * terminal page panel's within-page motion (`src/clients/inbox/tui/input.ts`), because the
+ * kit's `j` / `k` / `x` / `c` belong to the items *inside* a slot and a pager that stole them
+ * would make one keystroke mean two levels at once. Submit is `⌘`/`Ctrl` + `Enter` — the
+ * inbox's own submit chord, unchanged, because submitting an answer is literally the same
+ * act at both levels. The step dots are an indicator, not a control: a page is answered by
+ * walking it, not by jumping around it.
+ *
+ * A single-step page renders no pager chrome at all — no progress, no forward/back — just
+ * the submit affordance, because there is nothing to flip.
+ */
+export {};