@grafloria/element 0.3.20 → 0.3.22

package/src/libs/renderer/src/comments/comment-overlay.d.ts

@@ -1,56 +0,0 @@
-import type { CommentStore, CommentThreadView } from '@grafloria/engine';
-import type { CommentPinsOptions } from './comment-pins';
-/**
- * What the renderer needs from a comment source. Deliberately tiny — the renderer must not
- * know what a thread IS, only where the pins go and what they are called.
- */
-export interface CommentSource {
-    /** The threads to draw. Called once per BUILT frame (never on a skipped one). */
-    getThreads(): readonly CommentThreadView[];
-    /**
-     * Local view state — selection and the resolved filter.
-     *
-     * NOT keyboard focus. That is the RENDERER's `a11yFocus`, which already owns the roving
-     * tabindex for nodes and edges, and a comment pin is just a third kind of thing in the
-     * same one-tab-stop widget. Two authorities for "what is focused" is how you get two
-     * elements with `tabindex=0`, which is the exact bug the roving tabindex exists to
-     * prevent — so there is one, and it is the one that already existed.
-     */
-    getPinOptions(): Pick<CommentPinsOptions, 'selectedThreadId' | 'showResolved' | 'radius'>;
-}
-/** The slice of the renderer this controller drives. Structural, so it is trivial to fake. */
-export interface CommentRendererHost {
-    setCommentSource(source: CommentSource | null): void;
-    invalidateFrame(): void;
-}
-export interface CommentOverlayOptions {
-    showResolved?: boolean;
-    /** Notified when the open thread changes (a host pans to it, opens the panel, …). */
-    onSelectionChange?: (threadId: string | null) => void;
-}
-export declare class CommentOverlayController implements CommentSource {
-    private readonly store;
-    private readonly renderer;
-    private readonly options;
-    private selectedThreadId;
-    private showResolved;
-    private unsubscribe;
-    private invalidations;
-    constructor(store: CommentStore, renderer: CommentRendererHost, options?: CommentOverlayOptions);
-    getThreads(): readonly CommentThreadView[];
-    getPinOptions(): Pick<CommentPinsOptions, 'selectedThreadId' | 'showResolved' | 'radius'>;
-    /** Open a thread. Opening it is READING it, which is what "unread" means. */
-    select(threadId: string | null): void;
-    getSelected(): string | null;
-    setShowResolved(show: boolean): void;
-    /** Mark a thread read WITHOUT opening it (the "mark all read" affordance). */
-    markRead(threadId: string): void;
-    /** How many times the picture has been declared stale. A test asserts this moves. */
-    getInvalidationCount(): number;
-    dispose(): void;
-    /**
-     * THE ONE FUNNEL. Everything that can change what a pin looks like — and that the model
-     * cannot see — passes through here. See the header.
-     */
-    private invalidate;
-}

package/src/libs/renderer/src/comments/comment-overlay.js

@@ -1,127 +0,0 @@
-"use strict";
-// Wave 9 — Card 6: the overlay controller, and KEEPING THE FRAME GATE HONEST.
-//
-// ===========================================================================
-// THE PERF TRAP, WRITTEN OUT IN FULL
-// ===========================================================================
-// Wave 8 gave the renderer a FRAME GATE: `render()` skips a frame entirely — handing the
-// patcher back the SAME VNode object — when the model's mutation epoch and the viewport
-// signature are both unchanged. That is what makes an idle 10k-node frame cost 0.0ms, and
-// it is the single most valuable thing in the renderer.
-//
-// It is also a loaded gun pointed at every feature that draws something the model does not
-// know about. Three branches have already been shot by it. The rule it enforces is simple
-// and merciless:
-//
-//     IF IT CAN CHANGE THE PICTURE, IT MUST MOVE ONE OF THE GATE'S INPUTS.
-//
-// Comment state splits cleanly into two halves, and they are handled in two different ways
-// ON PURPOSE:
-//
-//   1. COMMENT DATA (a new thread, a reply, a resolve — local or arriving from a peer).
-//      This lives IN THE MODEL, in the `comments` register namespace, so it moves the
-//      mutation epoch through the model's own change funnel. Nothing here has to do
-//      anything, and — importantly — nothing here CAN FORGET to. (That is why
-//      `DiagramModel.comments` is an accessor pair rather than a plain field: applyOp's
-//      remote write is a raw assignment, and a raw assignment to a plain field would have
-//      been invisible to the epoch. A colleague's comment would have landed in the model
-//      and never been drawn. There is a mutation test that bypasses the accessor and
-//      watches exactly that happen.)
-//
-//   2. VIEW STATE (which thread is open, which pin has keyboard focus, whether resolved
-//      threads are shown, and WHAT THIS VIEWER HAS READ). None of it is in the model —
-//      correctly so: "Ada has read this thread" is a fact about Ada, not about the
-//      document, and syncing it would clear everyone else's unread badge. So none of it
-//      moves the epoch, and the gate would happily skip the frame in which the unread dot
-//      is supposed to disappear.
-//
-//      Every one of those transitions goes through `invalidate()` below, which calls
-//      `renderer.invalidateFrame()` — the escape hatch that exists for precisely this. It
-//      is cheap (one rebuilt frame) and idempotent, so the cost of calling it when you did
-//      not need to is nothing, and the cost of NOT calling it when you did is a stale
-//      picture. There is exactly one funnel, so there is exactly one thing to get right.
-//
-// And when there is no comment source at all, the renderer builds no layer and asks no
-// questions — an idle 10k-node frame is untouched, at 0.0ms.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CommentOverlayController = void 0;
-class CommentOverlayController {
-    constructor(store, renderer, options = {}) {
-        var _a;
-        this.store = store;
-        this.renderer = renderer;
-        this.options = options;
-        this.selectedThreadId = null;
-        this.unsubscribe = null;
-        this.invalidations = 0;
-        this.showResolved = (_a = options.showResolved) !== null && _a !== void 0 ? _a : false;
-        // The store fires for comment DATA (which already moved the epoch — belt) and for
-        // READ STATE (which did not — braces). Routing both through one invalidate() means the
-        // read-state case cannot be the one somebody forgets.
-        this.unsubscribe = this.store.onChange(() => this.invalidate());
-        this.renderer.setCommentSource(this);
-        // Installing a source CHANGES THE PICTURE and moves nothing the gate watches. If the
-        // renderer has already drawn a frame, that frame has no pins in it and the gate would
-        // serve it back forever.
-        this.invalidate();
-    }
-    // --- CommentSource --------------------------------------------------------
-    getThreads() {
-        return this.store.threads({ includeResolved: this.showResolved });
-    }
-    getPinOptions() {
-        return {
-            selectedThreadId: this.selectedThreadId,
-            showResolved: this.showResolved,
-        };
-    }
-    // --- view state: every setter goes through invalidate() --------------------
-    /** Open a thread. Opening it is READING it, which is what "unread" means. */
-    select(threadId) {
-        var _a, _b;
-        if (this.selectedThreadId === threadId)
-            return;
-        this.selectedThreadId = threadId;
-        if (threadId)
-            this.store.markRead(threadId); // fires onChange → invalidate
-        else
-            this.invalidate();
-        (_b = (_a = this.options).onSelectionChange) === null || _b === void 0 ? void 0 : _b.call(_a, threadId);
-    }
-    getSelected() {
-        return this.selectedThreadId;
-    }
-    setShowResolved(show) {
-        if (this.showResolved === show)
-            return;
-        this.showResolved = show;
-        this.invalidate();
-    }
-    /** Mark a thread read WITHOUT opening it (the "mark all read" affordance). */
-    markRead(threadId) {
-        this.store.markRead(threadId); // fires onChange → invalidate
-    }
-    /** How many times the picture has been declared stale. A test asserts this moves. */
-    getInvalidationCount() {
-        return this.invalidations;
-    }
-    dispose() {
-        var _a;
-        (_a = this.unsubscribe) === null || _a === void 0 ? void 0 : _a.call(this);
-        this.unsubscribe = null;
-        this.renderer.setCommentSource(null);
-        // Removing the pins is as much a change to the picture as adding them was.
-        this.renderer.invalidateFrame();
-    }
-    // -------------------------------------------------------------------------
-    /**
-     * THE ONE FUNNEL. Everything that can change what a pin looks like — and that the model
-     * cannot see — passes through here. See the header.
-     */
-    invalidate() {
-        this.invalidations++;
-        this.renderer.invalidateFrame();
-    }
-}
-exports.CommentOverlayController = CommentOverlayController;
-//# sourceMappingURL=comment-overlay.js.map

package/src/libs/renderer/src/comments/comment-panel.d.ts

@@ -1,45 +0,0 @@
-import type { CommentStore } from '@grafloria/engine';
-export interface CommentPanelOptions {
-    /** Accessible name of the region. */
-    label?: string;
-    /** Show resolved threads too. Default false — a resolved thread is an answered one. */
-    showResolved?: boolean;
-    /** Called when the user picks a thread (the host selects it and pans to it). */
-    onSelect?: (threadId: string | null) => void;
-    /** Called on Escape. The host MUST return focus to the canvas. */
-    onDismiss?: () => void;
-    /** Render a wall-clock timestamp. Injectable so tests are not clock-dependent. */
-    formatTime?: (ms: number) => string;
-}
-export declare class CommentPanelView {
-    private readonly store;
-    private readonly root;
-    private readonly listEl;
-    private readonly emptyEl;
-    private readonly options;
-    private signature;
-    private rebuilds;
-    private selected;
-    private pendingFocus;
-    constructor(container: HTMLElement, store: CommentStore, options?: CommentPanelOptions);
-    getElement(): HTMLElement;
-    getRebuildCount(): number;
-    /** Which thread is open. Setting it re-renders and moves focus onto the conversation. */
-    select(threadId: string | null, opts?: {
-        focus?: boolean;
-    }): void;
-    getSelected(): string | null;
-    /**
-     * Rebuild if — and only if — something the panel SHOWS has changed.
-     *
-     * Safe on every frame. A drag, a pan and a zoom all change the diagram and change
-     * nothing here, and must therefore cost zero DOM operations.
-     */
-    update(): boolean;
-    dispose(): void;
-    private renderThread;
-    private threadTitle;
-    private renderMessages;
-    private renderReplyForm;
-    private renderActions;
-}

package/src/libs/renderer/src/comments/comment-panel.js

@@ -1,287 +0,0 @@
-"use strict";
-// Wave 9 — Card 6: the comment side PANEL.
-//
-// ===========================================================================
-// WHY THIS IS HTML AND NOT SVG
-// ===========================================================================
-// The pin in the canvas is a POINTER. The conversation is TEXT — paragraphs, authors,
-// timestamps, a reply box — and text is what HTML is for. Rendering a threaded discussion
-// inside SVG would mean hand-rolling line wrapping, and it would hand a screen-reader user
-// a pile of `<text>` elements with no headings, no list semantics, no form controls and no
-// focus order. The panel is therefore ordinary DOM: `<article>`s with headings, an
-// ordinary `<ul>` of messages, and a real `<form>` with a labelled `<textarea>`.
-//
-// That is not a concession. It is the thing that makes the feature reachable at all: an
-// AT user browses the panel with the same list/heading keys they use on every other page
-// in the world, and the canvas keeps its ONE tab stop.
-//
-// ===========================================================================
-// NOT A KEYBOARD TRAP — the failure this kind of panel ships with
-// ===========================================================================
-// Everything focusable is in natural DOM order; nothing is trapped, nothing is aria-hidden
-// while focused, and ESCAPE always leaves (onDismiss → the host returns focus to the
-// canvas). Focus is MOVED, never stolen: opening a thread focuses its heading (which is
-// `tabindex=-1`, i.e. programmatically focusable but not in the Tab sequence), so a
-// keyboard user lands on the conversation they just opened instead of at the top of a list
-// they have to walk again.
-//
-// THRASH CONTROL, same discipline as the outline mirror: `update()` is safe to call every
-// frame. It compares a SIGNATURE and returns immediately when nothing that appears in the
-// panel has changed. `getRebuildCount()` exists so a test can prove that rather than
-// believe it.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CommentPanelView = void 0;
-/** The panel's own signature: everything it DISPLAYS, and nothing it does not. */
-function panelSignature(threads, selected) {
-    return (selected +
-        '|' +
-        threads
-            .map((t) => `${t.id}:${t.resolved ? 'r' : 'o'}:${t.unread}:${t.resolvedAnchor.attached ? 'a' : 'd'}:` +
-            `${t.resolvedAnchor.targetLabel}:` +
-            t.messages.map((m) => { var _a; return `${m.id}${m.deleted ? 'x' : ''}${(_a = m.editedAt) !== null && _a !== void 0 ? _a : ''}`; }).join(','))
-            .join(';'));
-}
-class CommentPanelView {
-    constructor(container, store, options = {}) {
-        var _a, _b, _c;
-        this.store = store;
-        this.signature = null;
-        this.rebuilds = 0;
-        this.selected = null;
-        this.pendingFocus = null;
-        this.options = {
-            label: (_a = options.label) !== null && _a !== void 0 ? _a : 'Comments',
-            showResolved: (_b = options.showResolved) !== null && _b !== void 0 ? _b : false,
-            formatTime: (_c = options.formatTime) !== null && _c !== void 0 ? _c : ((ms) => new Date(ms).toISOString()),
-            onSelect: options.onSelect,
-            onDismiss: options.onDismiss,
-        };
-        const doc = container.ownerDocument;
-        this.root = doc.createElement('section');
-        // `complementary` (not `region`): a comments sidebar is exactly what the landmark is
-        // for, and it means the AT's landmark rotor can jump straight here.
-        this.root.setAttribute('role', 'complementary');
-        this.root.setAttribute('aria-label', this.options.label);
-        this.root.className = 'grafloria-comment-panel';
-        this.root.setAttribute('data-grafloria-comment-panel', '');
-        const heading = doc.createElement('h3');
-        heading.className = 'grafloria-comment-panel__title';
-        heading.textContent = this.options.label;
-        this.root.appendChild(heading);
-        this.emptyEl = doc.createElement('p');
-        this.emptyEl.textContent = 'No comments yet.';
-        this.root.appendChild(this.emptyEl);
-        this.listEl = doc.createElement('ul');
-        // A `<ul>` may contain ONLY `<li>` — axe checks this, and a list that lies about its
-        // structure is worse than a div.
-        this.listEl.className = 'grafloria-comment-panel__threads';
-        this.listEl.setAttribute('aria-label', 'Comment threads');
-        this.root.appendChild(this.listEl);
-        // ESCAPE ALWAYS LEAVES. A panel you can tab into and not out of is a trap, and a trap
-        // is a WCAG failure (2.1.2) whatever else it does well.
-        this.root.addEventListener('keydown', (e) => {
-            var _a, _b;
-            const ev = e;
-            if (ev.key === 'Escape') {
-                ev.stopPropagation();
-                (_b = (_a = this.options).onDismiss) === null || _b === void 0 ? void 0 : _b.call(_a);
-            }
-        });
-        container.appendChild(this.root);
-    }
-    getElement() {
-        return this.root;
-    }
-    getRebuildCount() {
-        return this.rebuilds;
-    }
-    /** Which thread is open. Setting it re-renders and moves focus onto the conversation. */
-    select(threadId, opts) {
-        var _a, _b;
-        if (this.selected === threadId)
-            return;
-        this.selected = threadId;
-        if (threadId && (opts === null || opts === void 0 ? void 0 : opts.focus) !== false)
-            this.pendingFocus = threadId;
-        // Opening a thread is READING it — that is what "unread" means.
-        if (threadId)
-            this.store.markRead(threadId);
-        this.update();
-        (_b = (_a = this.options).onSelect) === null || _b === void 0 ? void 0 : _b.call(_a, threadId);
-    }
-    getSelected() {
-        return this.selected;
-    }
-    /**
-     * Rebuild if — and only if — something the panel SHOWS has changed.
-     *
-     * Safe on every frame. A drag, a pan and a zoom all change the diagram and change
-     * nothing here, and must therefore cost zero DOM operations.
-     */
-    update() {
-        const threads = this.store
-            .threads({ includeResolved: this.options.showResolved })
-            .sort(orderForReading);
-        const sig = panelSignature(threads, this.selected);
-        if (sig === this.signature && !this.pendingFocus)
-            return false;
-        this.signature = sig;
-        this.rebuilds++;
-        this.emptyEl.hidden = threads.length > 0;
-        this.listEl.replaceChildren(...threads.map((t) => this.renderThread(t)));
-        if (this.pendingFocus) {
-            const h = this.listEl.querySelector(`[data-thread-heading="${cssEscape(this.pendingFocus)}"]`);
-            // Focus is MOVED to the thing the user just opened, never STOLEN from elsewhere.
-            h === null || h === void 0 ? void 0 : h.focus();
-            this.pendingFocus = null;
-        }
-        return true;
-    }
-    dispose() {
-        this.root.remove();
-    }
-    // -------------------------------------------------------------------------
-    renderThread(t) {
-        const doc = this.root.ownerDocument;
-        const li = doc.createElement('li');
-        li.className = 'grafloria-comment-thread';
-        li.setAttribute('data-thread-id', t.id);
-        if (t.unread > 0)
-            li.setAttribute('data-unread', String(t.unread));
-        const article = doc.createElement('article');
-        const open = this.selected === t.id;
-        // --- the heading: a button, so it is operable by keyboard AND mouse ------
-        const h = doc.createElement('h4');
-        const btn = doc.createElement('button');
-        btn.type = 'button';
-        btn.setAttribute('data-thread-heading', t.id);
-        btn.setAttribute('aria-expanded', open ? 'true' : 'false');
-        btn.className = 'grafloria-comment-thread__heading';
-        btn.textContent = this.threadTitle(t);
-        btn.addEventListener('click', () => this.select(open ? null : t.id));
-        h.appendChild(btn);
-        article.appendChild(h);
-        // A DETACHED thread says so IN TEXT — not only in an amber colour. WCAG 1.4.1.
-        if (!t.resolvedAnchor.attached) {
-            const warn = doc.createElement('p');
-            warn.className = 'grafloria-comment-thread__detached';
-            warn.textContent = `Detached — the ${t.resolvedAnchor.targetKind === 'link' ? 'edge' : 'node'} this thread was about ("${t.resolvedAnchor.targetLabel}") has been deleted. The conversation is kept.`;
-            article.appendChild(warn);
-        }
-        if (open) {
-            article.appendChild(this.renderMessages(t));
-            article.appendChild(this.renderReplyForm(t));
-            article.appendChild(this.renderActions(t));
-        }
-        li.appendChild(article);
-        return li;
-    }
-    threadTitle(t) {
-        var _a, _b;
-        const live = t.messages.filter((m) => !m.deleted);
-        const first = (_b = (_a = live[0]) === null || _a === void 0 ? void 0 : _a.body) !== null && _b !== void 0 ? _b : '(no messages)';
-        const bits = [];
-        if (t.resolved)
-            bits.push('resolved');
-        if (!t.resolvedAnchor.attached)
-            bits.push('detached');
-        if (t.unread > 0)
-            bits.push(`${t.unread} unread`);
-        const suffix = bits.length ? ` — ${bits.join(', ')}` : '';
-        return `${truncate(first, 60)}${suffix}`;
-    }
-    renderMessages(t) {
-        const doc = this.root.ownerDocument;
-        const ul = doc.createElement('ul');
-        ul.className = 'grafloria-comment-thread__messages';
-        ul.setAttribute('aria-label', 'Messages');
-        for (const m of t.messages) {
-            const li = doc.createElement('li');
-            li.className = 'grafloria-comment-message';
-            li.setAttribute('data-message-id', m.id);
-            if (m.deleted) {
-                li.classList.add('grafloria-comment-message--deleted');
-                const p = doc.createElement('p');
-                p.textContent = `${m.author} deleted a message`;
-                li.appendChild(p);
-            }
-            else {
-                const meta = doc.createElement('p');
-                meta.className = 'grafloria-comment-message__meta';
-                meta.textContent = `${m.author} · ${this.options.formatTime(m.createdAt)}${m.editedAt ? ' · edited' : ''}`;
-                const body = doc.createElement('p');
-                body.className = 'grafloria-comment-message__body';
-                body.textContent = m.body;
-                li.appendChild(meta);
-                li.appendChild(body);
-            }
-            ul.appendChild(li);
-        }
-        return ul;
-    }
-    renderReplyForm(t) {
-        const doc = this.root.ownerDocument;
-        const form = doc.createElement('form');
-        form.className = 'grafloria-comment-reply';
-        const id = `grafloria-reply-${t.id}`;
-        // A real <label>, really associated. axe's `label` rule is WCAG 2 A, and a textarea
-        // that an AT announces as "edit, blank" is a textarea nobody can use.
-        const label = doc.createElement('label');
-        label.setAttribute('for', id);
-        label.textContent = 'Reply to this thread';
-        const ta = doc.createElement('textarea');
-        ta.id = id;
-        ta.rows = 2;
-        ta.setAttribute('data-reply-input', t.id);
-        const submit = doc.createElement('button');
-        submit.type = 'submit';
-        submit.textContent = 'Reply';
-        form.addEventListener('submit', (e) => {
-            e.preventDefault();
-            const body = ta.value.trim();
-            if (!body)
-                return;
-            this.store.reply(t.id, body);
-            ta.value = '';
-            this.store.markRead(t.id);
-            this.update();
-        });
-        form.appendChild(label);
-        form.appendChild(ta);
-        form.appendChild(submit);
-        return form;
-    }
-    renderActions(t) {
-        const doc = this.root.ownerDocument;
-        const p = doc.createElement('p');
-        p.className = 'grafloria-comment-thread__actions';
-        const toggle = doc.createElement('button');
-        toggle.type = 'button';
-        toggle.setAttribute('data-thread-resolve', t.id);
-        toggle.textContent = t.resolved ? 'Reopen thread' : 'Resolve thread';
-        toggle.addEventListener('click', () => {
-            if (t.resolved)
-                this.store.reopen(t.id);
-            else
-                this.store.resolve(t.id);
-            this.update();
-        });
-        p.appendChild(toggle);
-        return p;
-    }
-}
-exports.CommentPanelView = CommentPanelView;
-/** Unread first (that is why you opened the panel), then oldest first within each group. */
-function orderForReading(a, b) {
-    if (a.unread !== b.unread && (a.unread === 0 || b.unread === 0))
-        return a.unread ? -1 : 1;
-    return a.createdAt - b.createdAt;
-}
-function truncate(s, n) {
-    return s.length <= n ? s : `${s.slice(0, n - 1)}…`;
-}
-/** Ids are minted by us and contain no CSS metacharacters, but a selector must not trust that. */
-function cssEscape(v) {
-    return v.replace(/["\\]/g, '\\$&');
-}
-//# sourceMappingURL=comment-panel.js.map

package/src/libs/renderer/src/comments/comment-pins.d.ts

@@ -1,34 +0,0 @@
-import type { CommentThreadView } from '@grafloria/engine';
-import type { VNode } from '../types';
-export interface CommentPinsOptions {
-    /** World rect currently on screen. Pins outside it are not built. */
-    visibleRect?: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    };
-    /** Current zoom, so the pin can be counter-scaled to a constant screen size. */
-    zoom?: number;
-    /** The thread whose panel is open — drawn selected, and `aria-expanded=true`. */
-    selectedThreadId?: string | null;
-    /** The comment the roving tabindex has focused, if any. */
-    focusedThreadId?: string | null;
-    /** Hide resolved threads (the default view — a resolved thread is answered). */
-    showResolved?: boolean;
-    /** Radius in SCREEN pixels. */
-    radius?: number;
-}
-/**
- * The accessible name of a pin. This is the ONLY thing an AT user hears about a comment
- * before they decide whether to open it, so it has to answer the question they are
- * actually asking: what is this about, is it live, and is any of it new to me?
- */
-export declare function commentPinAccessibleName(thread: CommentThreadView): string;
-/**
- * Build the pin layer.
- *
- * Returns a `<g>` even when empty: a stable element keeps the patcher's keyed diff
- * simple, and an empty `<g>` costs nothing to reconcile.
- */
-export declare function renderCommentPins(threads: readonly CommentThreadView[], options?: CommentPinsOptions): VNode;