@north-light/crouter 0.3.192 → 0.3.193

package/dist/pages/elements/pages.js

@@ -0,0 +1,355 @@
+/**
+ * `<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.
+ */
+import { registerElement } from '../register.js';
+function hostBridge() {
+    return window.crtr;
+}
+const NO_HOST_REASON = 'Submit is unavailable — this page is not connected to a host.';
+const PAGE_STYLE = `
+  :host {
+    display: block;
+  }
+
+  :host([hidden]) {
+    display: none;
+  }
+
+  [part="page"] {
+    display: grid;
+    gap: var(--crtr-space-3);
+  }
+
+  [part="page"]:focus {
+    outline: none;
+  }
+`;
+const PAGES_STYLE = `
+  :host {
+    display: block;
+  }
+
+  [part="container"] {
+    display: grid;
+    gap: var(--crtr-space-4);
+  }
+
+  [part="chrome"] {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--crtr-space-3);
+    padding-top: var(--crtr-space-3);
+    border-top: 1px solid var(--crtr-color-border);
+  }
+
+  [part="container"][data-steps="1"] [part="chrome"] {
+    justify-content: flex-end;
+  }
+
+  [part="progress"] {
+    display: flex;
+    align-items: center;
+    gap: var(--crtr-space-2);
+    color: var(--crtr-color-text-muted);
+  }
+
+  [part="progress-track"] {
+    display: flex;
+    align-items: center;
+    gap: var(--crtr-space-1);
+  }
+
+  [part="progress-step"] {
+    width: var(--crtr-space-2);
+    height: var(--crtr-space-1);
+    border-radius: var(--crtr-radius-small);
+    background: var(--crtr-color-border);
+  }
+
+  [part="progress-step"][data-state="complete"] {
+    background: var(--crtr-color-text-muted);
+  }
+
+  [part="progress-step"][data-state="current"] {
+    width: var(--crtr-space-4);
+    background: var(--crtr-color-accent);
+  }
+
+  [part="actions"] {
+    display: flex;
+    align-items: center;
+    gap: var(--crtr-space-2);
+  }
+
+  button {
+    font: inherit;
+    color: var(--crtr-color-text);
+    background: var(--crtr-color-surface);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-small);
+    padding: var(--crtr-space-2) var(--crtr-space-3);
+    cursor: pointer;
+  }
+
+  button:hover:not(:disabled) {
+    background: var(--crtr-color-surface-hover);
+  }
+
+  button:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: 2px;
+  }
+
+  button:disabled {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+
+  [part="submit"] {
+    color: var(--crtr-color-accent-contrast);
+    background: var(--crtr-color-accent);
+    border-color: transparent;
+  }
+
+  [part="submit"]:hover:not(:disabled) {
+    background: var(--crtr-color-accent);
+    filter: brightness(1.08);
+  }
+
+  [part="notice"] {
+    color: var(--crtr-color-text-muted);
+  }
+
+  [part="notice"][data-state="error"] {
+    color: var(--crtr-color-danger);
+  }
+
+  [hidden] {
+    display: none !important;
+  }
+`;
+/** One step of a page. Bare on its own; the pager shows and hides it. */
+class CrtrPageElement extends HTMLElement {
+    constructor() {
+        super();
+        const root = this.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        style.textContent = PAGE_STYLE;
+        const page = document.createElement('div');
+        page.part.add('page');
+        page.append(document.createElement('slot'));
+        root.append(style, page);
+    }
+}
+class CrtrPagesElement extends HTMLElement {
+    static observedAttributes = ['disabled', 'submit-label'];
+    #steps = [];
+    #index = 0;
+    #state = 'idle';
+    #error = null;
+    #container = document.createElement('div');
+    #chrome = document.createElement('div');
+    #progress = document.createElement('div');
+    #progressLabel = document.createElement('span');
+    #progressTrack = document.createElement('span');
+    #actions = document.createElement('div');
+    #notice = document.createElement('span');
+    #prev = document.createElement('button');
+    #next = document.createElement('button');
+    #submit = document.createElement('button');
+    #children = new MutationObserver(() => {
+        this.#collectSteps();
+        this.#render();
+    });
+    constructor() {
+        super();
+        const root = this.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        style.textContent = PAGES_STYLE;
+        const steps = document.createElement('div');
+        steps.part.add('steps');
+        steps.append(document.createElement('slot'));
+        this.#container.part.add('container');
+        this.#chrome.part.add('chrome');
+        this.#progress.part.add('progress');
+        this.#progress.setAttribute('role', 'status');
+        this.#progress.setAttribute('aria-live', 'polite');
+        this.#progressLabel.part.add('progress-label');
+        this.#progressTrack.part.add('progress-track');
+        this.#progressTrack.setAttribute('aria-hidden', 'true');
+        this.#progress.append(this.#progressLabel, this.#progressTrack);
+        this.#prev.part.add('prev');
+        this.#prev.type = 'button';
+        this.#prev.textContent = 'Back';
+        this.#prev.addEventListener('click', () => this.#go(-1));
+        this.#next.part.add('next');
+        this.#next.type = 'button';
+        this.#next.textContent = 'Next';
+        this.#next.addEventListener('click', () => this.#go(1));
+        this.#submit.part.add('submit');
+        this.#submit.type = 'button';
+        this.#submit.addEventListener('click', () => void this.#runSubmit());
+        this.#notice.part.add('notice');
+        this.#actions.part.add('actions');
+        this.#actions.append(this.#notice, this.#prev, this.#next, this.#submit);
+        this.#chrome.append(this.#progress, this.#actions);
+        this.#container.append(steps, this.#chrome);
+        root.append(style, this.#container);
+    }
+    connectedCallback() {
+        this.#collectSteps();
+        this.#children.observe(this, { childList: true });
+        this.ownerDocument.addEventListener('keydown', this.#onKeydown);
+        this.#render();
+    }
+    disconnectedCallback() {
+        this.#children.disconnect();
+        this.ownerDocument.removeEventListener('keydown', this.#onKeydown);
+    }
+    attributeChangedCallback() {
+        if (this.isConnected)
+            this.#render();
+    }
+    #collectSteps() {
+        this.#steps = [...this.children].filter((child) => child instanceof HTMLElement && child.tagName === 'CRTR-PAGE');
+        for (const step of this.#steps) {
+            if (!step.hasAttribute('tabindex'))
+                step.setAttribute('tabindex', '-1');
+        }
+        this.#index = Math.min(this.#index, Math.max(0, this.#steps.length - 1));
+    }
+    get #isFinalStep() {
+        return this.#index >= this.#steps.length - 1;
+    }
+    #go(delta, focus = true) {
+        const next = this.#index + delta;
+        if (next < 0 || next >= this.#steps.length || next === this.#index)
+            return;
+        this.#index = next;
+        this.#error = null;
+        this.#render();
+        if (focus)
+            this.#steps[this.#index]?.focus();
+    }
+    async #runSubmit() {
+        if (this.#state !== 'idle' || this.hasAttribute('disabled') || !this.#isFinalStep)
+            return;
+        const bridge = hostBridge();
+        if (typeof bridge?.submit !== 'function') {
+            this.#error = NO_HOST_REASON;
+            this.#render();
+            return;
+        }
+        this.#state = 'submitting';
+        this.#error = null;
+        this.#render();
+        try {
+            await bridge.submit();
+            this.#state = 'submitted';
+        }
+        catch (error) {
+            this.#state = 'idle';
+            this.#error = error instanceof Error ? error.message : 'Submit failed.';
+        }
+        this.#render();
+    }
+    #onKeydown = (event) => {
+        if (event.defaultPrevented)
+            return;
+        const path = event.composedPath();
+        // One `<crtr-pages>` per document, so the pager listens document-wide — but never steals
+        // a key that belongs to another pager's subtree (a page rendering a page).
+        if (path.some((node) => node instanceof HTMLElement && node.tagName === 'CRTR-PAGES' && node !== this))
+            return;
+        // The submit chord is modified, so it cannot type a character and fires even from a
+        // textarea — exactly the rule the inbox's own ⌘↵ follows.
+        if ((event.metaKey || event.ctrlKey) && event.key === 'Enter') {
+            if (!this.#isFinalStep)
+                return;
+            event.preventDefault();
+            void this.#runSubmit();
+            return;
+        }
+        if (event.metaKey || event.ctrlKey || event.altKey || isTextEntry(path))
+            return;
+        const key = event.key.toLowerCase();
+        if (key !== 'n' && key !== 'p')
+            return;
+        event.preventDefault();
+        this.#go(key === 'n' ? 1 : -1);
+    };
+    #render() {
+        const total = this.#steps.length;
+        const multiStep = total > 1;
+        const current = Math.min(this.#index, Math.max(0, total - 1));
+        for (const [position, step] of this.#steps.entries()) {
+            step.toggleAttribute('hidden', position !== current);
+        }
+        this.#container.dataset['steps'] = String(Math.max(1, total));
+        this.#container.dataset['step'] = String(current + 1);
+        this.#progress.hidden = !multiStep;
+        if (multiStep) {
+            const label = this.#steps[current]?.getAttribute('label')?.trim();
+            this.#progressLabel.textContent = label
+                ? `Step ${current + 1} of ${total} · ${label}`
+                : `Step ${current + 1} of ${total}`;
+            this.#progressTrack.replaceChildren(...this.#steps.map((_step, position) => {
+                const dot = document.createElement('span');
+                dot.part.add('progress-step');
+                dot.dataset['state'] = position === current ? 'current' : position < current ? 'complete' : 'upcoming';
+                return dot;
+            }));
+        }
+        this.#prev.hidden = !multiStep;
+        this.#prev.disabled = current === 0;
+        this.#next.hidden = !multiStep || this.#isFinalStep;
+        this.#next.disabled = false;
+        this.#submit.hidden = !this.#isFinalStep;
+        const bridgeReady = typeof hostBridge()?.submit === 'function';
+        this.#submit.disabled = !bridgeReady || this.#state !== 'idle' || this.hasAttribute('disabled');
+        this.#submit.textContent =
+            this.#state === 'submitting'
+                ? 'Submitting…'
+                : this.#state === 'submitted'
+                    ? 'Submitted'
+                    : this.getAttribute('submit-label')?.trim() || 'Submit';
+        const notice = this.#error ??
+            (this.#state === 'submitted'
+                ? 'Your response was submitted.'
+                : !bridgeReady && this.#isFinalStep
+                    ? NO_HOST_REASON
+                    : null);
+        this.#notice.hidden = notice === null;
+        this.#notice.textContent = notice ?? '';
+        this.#notice.dataset['state'] = this.#error === null ? 'info' : 'error';
+    }
+}
+/** A key typed into writing is writing, never navigation. */
+function isTextEntry(path) {
+    return path.some((node) => node instanceof HTMLElement &&
+        (node instanceof HTMLInputElement || node instanceof HTMLTextAreaElement || node.isContentEditable));
+}
+registerElement('crtr-page', CrtrPageElement);
+registerElement('crtr-pages', CrtrPagesElement);

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

@@ -0,0 +1,21 @@
+/**
+ * `<crtr-slot>` — the one escape element, for kinds crtr does not own.
+ *
+ * A page may carry a slot whose `kind` belongs to the product hosting the page (a Northlight
+ * workspace component, say) rather than to this kit. crtr validated only that such a slot has
+ * an id, a kind, and an object config; it never invents an element for a kind it cannot
+ * render. So every one of them arrives as
+ * `<crtr-slot kind="product-kind" slot-id="…"><script type="application/json">…</script></crtr-slot>`,
+ * and this element does exactly two things: ask the host to render the kind into a mount
+ * point, and — when the host has no renderer for it, or there is no host at all — say so by
+ * name instead of leaving a hole in the page.
+ *
+ * The mount point is a light-DOM child, surfaced through the shadow root's `<slot>`. Host
+ * content styles itself from the document it is mounted into, and putting it behind this
+ * element's shadow boundary would cut it off from that; the JSON config child stays where it
+ * is, untouched, so a re-mount reads the same config.
+ *
+ * A mounted component owns its own answer: it talks to `window.crtr` itself, and this element
+ * never invents a response shape for a kind whose shape only the product knows.
+ */
+export {};

package/dist/pages/elements/slot.js

@@ -0,0 +1,105 @@
+/**
+ * `<crtr-slot>` — the one escape element, for kinds crtr does not own.
+ *
+ * A page may carry a slot whose `kind` belongs to the product hosting the page (a Northlight
+ * workspace component, say) rather than to this kit. crtr validated only that such a slot has
+ * an id, a kind, and an object config; it never invents an element for a kind it cannot
+ * render. So every one of them arrives as
+ * `<crtr-slot kind="product-kind" slot-id="…"><script type="application/json">…</script></crtr-slot>`,
+ * and this element does exactly two things: ask the host to render the kind into a mount
+ * point, and — when the host has no renderer for it, or there is no host at all — say so by
+ * name instead of leaving a hole in the page.
+ *
+ * The mount point is a light-DOM child, surfaced through the shadow root's `<slot>`. Host
+ * content styles itself from the document it is mounted into, and putting it behind this
+ * element's shadow boundary would cut it off from that; the JSON config child stays where it
+ * is, untouched, so a re-mount reads the same config.
+ *
+ * A mounted component owns its own answer: it talks to `window.crtr` itself, and this element
+ * never invents a response shape for a kind whose shape only the product knows.
+ */
+import { mountWorkspaceComponent } from '../host.js';
+import { registerElement } from '../register.js';
+import { readSlotConfig } from '../slot-config.js';
+const STYLE = `
+  :host {
+    display: block;
+  }
+
+  [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);
+    box-shadow: var(--crtr-shadow);
+  }
+
+  [part="unavailable"][hidden] {
+    display: none;
+  }
+
+  [part="kind"] {
+    color: var(--crtr-color-text);
+    font-family: var(--crtr-font-mono);
+  }
+
+  [part="reason"] {
+    display: block;
+    margin-top: var(--crtr-space-1);
+    font-size: 0.9em;
+  }
+`;
+class CrtrSlotElement extends HTMLElement {
+    #unavailable = document.createElement('div');
+    #kind = document.createElement('span');
+    #reason = document.createElement('span');
+    #mount = document.createElement('div');
+    #started = false;
+    constructor() {
+        super();
+        const root = this.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        style.textContent = STYLE;
+        this.#unavailable.part.add('unavailable');
+        this.#unavailable.setAttribute('role', 'status');
+        this.#kind.part.add('kind');
+        this.#reason.part.add('reason');
+        this.#unavailable.append('Component unavailable: ', this.#kind, this.#reason);
+        // Hidden until the mount attempt resolves, so a host that does render this kind never
+        // flashes an unavailable state on the way in.
+        this.#unavailable.hidden = true;
+        this.#mount.part.add('mount');
+        root.append(style, document.createElement('slot'), this.#unavailable);
+    }
+    connectedCallback() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        const kind = this.getAttribute('kind')?.trim() ?? '';
+        this.#kind.textContent = kind === '' ? 'unknown' : kind;
+        if (kind === '') {
+            this.#showUnavailable('This slot names no component kind.');
+            return;
+        }
+        const read = readSlotConfig(this);
+        if (read.status !== 'ok') {
+            this.#showUnavailable(read.reason);
+            return;
+        }
+        this.append(this.#mount);
+        void this.#attemptMount(kind, read.config);
+    }
+    async #attemptMount(kind, config) {
+        const outcome = await mountWorkspaceComponent(this.#mount, kind, config);
+        if (outcome === 'mounted')
+            return;
+        this.#mount.remove();
+        this.#showUnavailable('This page is open somewhere that cannot render it.');
+    }
+    #showUnavailable(reason) {
+        this.#reason.textContent = reason;
+        this.#unavailable.hidden = false;
+    }
+}
+registerElement('crtr-slot', CrtrSlotElement);

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

@@ -0,0 +1,19 @@
+/**
+ * `<crtr-table>` — a dataset the agent wants the user to pick from.
+ *
+ * Rows and columns are independently selectable, single or multi, because the two questions
+ * an agent asks of a table are "which of these records" and "which of these fields", and they
+ * are not the same question. Row selection wears a real checkbox or radio in a leading cell;
+ * column selection turns the header into a pressed toggle, since a column has no natural row
+ * to hang a checkbox on and the header IS the column.
+ *
+ * Anchored comments use the same one-per-anchor algebra as every other element: a row anchor
+ * in each row's trailing cell, a column anchor beside each header label, and a `whole` anchor
+ * in the trailing header cell for the table itself. Triggers stay invisible until the row is
+ * hovered or focused, or until a comment is actually there.
+ *
+ * Ported from the agent interaction kit's `agent-table.tsx` (northlight `3705fe9e2`), with the
+ * kit's `classic-list-keys` grammar — j/k move, x selects, c comments — reimplemented here
+ * over the shadow root.
+ */
+export {};