@fusion.dev/helix-headless 0.215.3 → 0.216.0

package/dist/markdown/stream.d.ts

@@ -0,0 +1,47 @@
+import { type MarkdownBlock } from './blocks.js';
+/**
+ * The part of a reply that can be drawn now, and the part held back until the
+ * next characters decide what it is.
+ *
+ * Only the end of the text is held, and only for as long as it is ambiguous:
+ *
+ * - a last line that is only a marker so far (`#`, `-`, `1.`, three backticks,
+ *   `>` or `> [!NO`), until it is clear what block it starts. A fence's opening line
+ *   is held whole, since its language arrives with it;
+ * - a line starting with a pipe after a line that did not, with whatever has
+ *   arrived of the next line, until that next line shows whether the first was
+ *   a table's header.
+ *
+ * Holding costs a few characters of latency and nothing else, so it is safe
+ * anywhere, a code block included: what is held is drawn, unchanged, a moment
+ * later.
+ */
+export declare const visibleText: (text: string) => string;
+/** What one read of a stream gives: its blocks, and how many of them are final. */
+export interface MarkdownRead {
+    blocks: MarkdownBlock[];
+    /** The leading blocks no later text can change. */
+    closed: number;
+}
+/**
+ * Reads a growing text into blocks, reparsing only from the block that is
+ * still open.
+ *
+ * A top-level block is final once another has started after it, since the line
+ * that started the next one cannot be read differently by anything after it.
+ * So each read keeps those, and parses again from the first line of the last
+ * one. A text that does not extend the last one starts over.
+ */
+export declare class MarkdownStream {
+    private text;
+    private blocks;
+    private starts;
+    private lines;
+    /**
+     * Reads the text so far. With `final`, the whole text is read, the held end
+     * included, as the finished reply.
+     */
+    read(text: string, final: boolean): MarkdownRead;
+    /** Forgets everything read, as a new reply does. */
+    reset(): void;
+}

package/dist/markdown/stream.js

@@ -0,0 +1,62 @@
+import { parseBlocks } from './blocks.js';
+export const visibleText = (text) => {
+    const breakAt = text.lastIndexOf('\n');
+    const partial = text.slice(breakAt + 1);
+    const complete = breakAt < 0 ? '' : text.slice(0, breakAt);
+    const bare = partial.replace(/^[ \t>]*/, '');
+    if (/^(?:#{1,6}|[-*_+](?:[ \t]*[-*_])*|\d{1,9}[.)]?|`+|~+)$/.test(bare) ||
+        /^(?:`{3,}|~{3,})/.test(bare) ||
+        (/^[ \t]*>/.test(partial) && /^(?:\[(?:!(?:[A-Za-z]{0,9}\]?)?)?)?$/.test(bare))) {
+        return breakAt < 0 ? '' : `${complete}\n`;
+    }
+    const lines = breakAt < 0 ? [] : complete.split('\n');
+    const last = lines.at(-1);
+    const piped = (line) => line !== undefined && /^[ \t>]*\|/.test(line);
+    if (piped(partial) && !piped(last)) {
+        return breakAt < 0 ? '' : `${complete}\n`;
+    }
+    if (piped(last) && !piped(lines.at(-2)) && /^[ \t>]*[|:\- \t]*$/.test(partial)) {
+        return lines.length > 1 ? `${lines.slice(0, -1).join('\n')}\n` : '';
+    }
+    return text;
+};
+export class MarkdownStream {
+    constructor() {
+        this.text = '';
+        this.blocks = [];
+        this.starts = [];
+        this.lines = [];
+    }
+    read(text, final) {
+        const drawn = final ? text : visibleText(text);
+        if (!drawn.startsWith(this.text)) {
+            this.blocks = [];
+            this.starts = [];
+            this.lines = [];
+        }
+        this.text = drawn;
+        const lines = drawn === '' ? [] : drawn.replace(/\r\n?/g, '\n').split('\n');
+        if (lines.at(-1) === '') {
+            lines.pop();
+        }
+        const keep = Math.max(0, this.blocks.length - 1);
+        const from = this.starts[keep] ?? 0;
+        const same = this.lines.length >= from && lines.length >= from;
+        const restart = same ? from : 0;
+        const kept = same ? keep : 0;
+        const read = parseBlocks(lines.slice(restart));
+        this.blocks = [...this.blocks.slice(0, kept), ...read.blocks];
+        this.starts = [...this.starts.slice(0, kept), ...read.starts.map((start) => start + restart)];
+        this.lines = lines;
+        return {
+            blocks: this.blocks,
+            closed: final ? this.blocks.length : Math.max(0, this.blocks.length - 1),
+        };
+    }
+    reset() {
+        this.text = '';
+        this.blocks = [];
+        this.starts = [];
+        this.lines = [];
+    }
+}

package/dist/markdown/tree.d.ts

@@ -0,0 +1,57 @@
+import type { MarkdownAlertKind, MarkdownBlock } from './blocks.js';
+/** A node of what a document draws: an element, or the text of a text node. */
+export type MarkdownNode = string | MarkdownElement;
+/** An element of what a document draws. */
+export interface MarkdownElement {
+    attributes: Record<string, string>;
+    children: MarkdownNode[];
+    tag: string;
+}
+/** How a document is drawn. */
+export interface MarkdownOptions {
+    /** Each alert's heading by its kind. English by default. */
+    headings?: Partial<Record<MarkdownAlertKind, string>> | undefined;
+    /**
+     * The tags for a fence and an alert, which name the tier they are drawn in.
+     * `helix-code-block` and `helix-callout` by default.
+     */
+    tags?: Partial<MarkdownTags> | undefined;
+}
+/** The options with every default filled in. */
+export interface MarkdownFilled {
+    headings: Record<MarkdownAlertKind, string>;
+    tags: MarkdownTags;
+}
+/** The elements a document draws from another family. */
+export interface MarkdownTags {
+    callout: string;
+    codeBlock: string;
+}
+/**
+ * The address, where it is one a link may follow: a relative address, or one
+ * on `http`, `https`, `mailto` or `tel`. Anything else, `javascript:` and
+ * `data:` among them, is dropped, and the link is drawn as its text.
+ */
+export declare const safeUrl: (url: string) => string | undefined;
+/**
+ * Each column's share of a table's width, from its heading's length, between
+ * 4 and 24 characters. Set once, from the rows that arrive first, so the
+ * columns never move as the rest arrives.
+ */
+export declare const columnShares: (head: string[]) => number[];
+/** A block as the node it draws. `open` reads its end as still arriving. */
+export declare const blockNode: (block: MarkdownBlock, open: boolean, options: MarkdownFilled) => MarkdownElement;
+/** The options with every default filled in. */
+export declare const withDefaults: (options?: MarkdownOptions) => MarkdownFilled;
+/** A finished document's nodes. */
+export declare const markdownNodes: (text: string, options?: MarkdownOptions) => MarkdownElement[];
+/** A node as HTML, the way a browser serializes the element it draws. */
+export declare const nodeHtml: (node: MarkdownNode) => string;
+/**
+ * A finished document as HTML, for a server to send inside `helix-markdown`.
+ *
+ * The element takes over what it is sent where the markup is exactly what it
+ * would draw for its `text`, so a page served this way draws the reply before
+ * any script runs and does not draw it again.
+ */
+export declare const markdownToHtml: (text: string, options?: MarkdownOptions) => string;

package/dist/markdown/tree.js

@@ -0,0 +1,144 @@
+import { parseInline } from './inline.js';
+import { MarkdownStream } from './stream.js';
+const HEADINGS = {
+    caution: 'Caution',
+    important: 'Important',
+    note: 'Note',
+    tip: 'Tip',
+    warning: 'Warning',
+};
+const TONES = {
+    caution: 'danger',
+    important: undefined,
+    note: 'info',
+    tip: 'success',
+    warning: 'warning',
+};
+const element = (tag, children = [], attributes = {}) => ({ attributes, children, tag });
+export const safeUrl = (url) => {
+    const trimmed = url.trim();
+    const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):/.exec(trimmed)?.[1]?.toLowerCase();
+    return scheme === undefined || ['http', 'https', 'mailto', 'tel'].includes(scheme)
+        ? trimmed
+        : undefined;
+};
+const inlineNodes = (nodes) => nodes.flatMap((node) => {
+    switch (node.kind) {
+        case 'break':
+            return [element('br')];
+        case 'code':
+            return [element('code', [node.text])];
+        case 'del':
+        case 'em':
+        case 'strong':
+            return [element(node.kind, inlineNodes(node.children))];
+        case 'image': {
+            const href = safeUrl(node.src);
+            const words = node.alt || node.src;
+            return href === undefined
+                ? [words]
+                : [
+                    element('a', [words], node.title === undefined ? { href } : { href, title: node.title }),
+                ];
+        }
+        case 'link': {
+            const children = inlineNodes(node.children);
+            if (node.href === undefined) {
+                return [element('a', children)];
+            }
+            const href = safeUrl(node.href);
+            if (href === undefined) {
+                return children;
+            }
+            return [
+                element('a', children, node.title === undefined ? { href } : { href, title: node.title }),
+            ];
+        }
+        default:
+            return node.text === '' ? [] : [node.text];
+    }
+});
+const inline = (text, open) => inlineNodes(parseInline(text, { open }));
+const aligned = (align) => align === undefined ? {} : { 'data-align': align };
+export const columnShares = (head) => {
+    const weights = head.map((cell) => Math.min(24, Math.max(4, cell.length)));
+    const total = weights.reduce((sum, weight) => sum + weight, 0);
+    return weights.map((weight) => Math.round((weight / total) * 10000) / 100);
+};
+const itemNode = (item, open, options) => {
+    const [first, ...rest] = item.children;
+    const lead = first?.kind === 'paragraph'
+        ? inline(first.text, open && rest.length === 0)
+        : first
+            ? [blockNode(first, open && rest.length === 0, options)]
+            : [];
+    const tail = rest.map((block, index) => blockNode(block, open && index === rest.length - 1, options));
+    if (item.checked === undefined) {
+        return element('li', [...lead, ...tail]);
+    }
+    const box = element('input', [], item.checked
+        ? { checked: '', disabled: '', type: 'checkbox' }
+        : { disabled: '', type: 'checkbox' });
+    return element('li', [box, ' ', ...lead, ...tail], { 'data-task': '' });
+};
+export const blockNode = (block, open, options) => {
+    switch (block.kind) {
+        case 'code': {
+            const language = block.info.split(/\s+/)[0] ?? '';
+            return element(options.tags.codeBlock, [block.text], language === '' ? {} : { label: language, language });
+        }
+        case 'heading':
+            return element(`h${block.level}`, inline(block.text, open));
+        case 'list':
+            return element(block.ordered ? 'ol' : 'ul', block.items.map((item, index) => itemNode(item, open && index === block.items.length - 1, options)), block.ordered && block.start !== 1 ? { start: String(block.start) } : {});
+        case 'paragraph':
+            return element('p', inline(block.text, open));
+        case 'quote': {
+            const children = block.children.map((child, index) => blockNode(child, open && index === block.children.length - 1, options));
+            if (block.alert === undefined) {
+                return element('blockquote', children);
+            }
+            const tone = TONES[block.alert];
+            return element(options.tags.callout, [element('span', [options.headings[block.alert]], { slot: 'heading' }), ...children], tone === undefined ? {} : { tone });
+        }
+        case 'rule':
+            return element('hr');
+        case 'table': {
+            const shares = columnShares(block.head);
+            const table = element('table', [
+                element('colgroup', shares.map((share) => element('col', [], { width: `${share}%` }))),
+                element('thead', [
+                    element('tr', block.head.map((cell, column) => element('th', inline(cell, false), aligned(block.align[column])))),
+                ]),
+                element('tbody', block.rows.map((row, at) => element('tr', row.map((cell, column) => element('td', inline(cell, open && at === block.rows.length - 1 && column === row.length - 1), aligned(block.align[column])))))),
+            ], { 'data-columns': String(block.head.length) });
+            return element('div', [table], { 'data-table': '' });
+        }
+    }
+};
+export const withDefaults = (options = {}) => ({
+    headings: { ...HEADINGS, ...options.headings },
+    tags: { callout: 'helix-callout', codeBlock: 'helix-code-block', ...options.tags },
+});
+export const markdownNodes = (text, options = {}) => {
+    const filled = withDefaults(options);
+    return new MarkdownStream()
+        .read(text, true)
+        .blocks.map((block) => blockNode(block, false, filled));
+};
+const VOID = new Set(['br', 'col', 'hr', 'input']);
+const escapeText = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const escapeAttribute = (text) => escapeText(text).replace(/"/g, '&quot;');
+export const nodeHtml = (node) => {
+    if (typeof node === 'string') {
+        return escapeText(node);
+    }
+    const attributes = Object.entries(node.attributes)
+        .map(([name, value]) => (value === '' ? ` ${name}=""` : ` ${name}="${escapeAttribute(value)}"`))
+        .join('');
+    if (VOID.has(node.tag)) {
+        return `<${node.tag}${attributes}>`;
+    }
+    return `<${node.tag}${attributes}>${node.children.map(nodeHtml).join('')}</${node.tag}>`;
+};
+export const markdownToHtml = (text, options = {}) => markdownNodes(text, options).map(nodeHtml).join('');

package/dist/markdown/writer.d.ts

@@ -0,0 +1,33 @@
+import { type MarkdownOptions } from './tree.js';
+/**
+ * Draws a Markdown document into an element as its text grows.
+ *
+ * Each top-level block is its own subtree. A block that has closed is drawn
+ * once and never touched again, and the open one is changed only where it
+ * differs from what is drawn: a word arriving appends to the text node that
+ * holds the line, a row arriving adds a row, and nothing above it is
+ * rebuilt.
+ */
+export declare class MarkdownWriter {
+    private readonly host;
+    private readonly stream;
+    private drawn;
+    private closed;
+    private text;
+    private options;
+    constructor(host: Element, options?: MarkdownOptions);
+    /** Changes how the document is drawn, and draws it again. */
+    configure(options: MarkdownOptions): void;
+    /**
+     * Draws the text so far. With `final`, the text is the whole document and
+     * every block is closed.
+     */
+    write(text: string, final: boolean): void;
+    /** Forgets the document, and empties the element. */
+    clear(): void;
+    /**
+     * Takes over what a server drew, where it is exactly these nodes, and
+     * otherwise clears it to draw it again.
+     */
+    private take;
+}

package/dist/markdown/writer.js

@@ -0,0 +1,139 @@
+import { MarkdownStream } from './stream.js';
+import { blockNode, nodeHtml, withDefaults, } from './tree.js';
+const create = (node, document) => {
+    if (typeof node === 'string') {
+        return { children: [], dom: document.createTextNode(node), node };
+    }
+    const dom = document.createElement(node.tag);
+    for (const [name, value] of Object.entries(node.attributes)) {
+        dom.setAttribute(name, value);
+    }
+    const children = node.children.map((child) => create(child, document));
+    for (const child of children) {
+        dom.appendChild(child.dom);
+    }
+    return { children, dom, node };
+};
+const patch = (parent, drawn, next) => {
+    const previous = drawn.node;
+    if (previous === next) {
+        return drawn;
+    }
+    if (typeof next === 'string') {
+        if (typeof previous === 'string') {
+            const text = drawn.dom;
+            if (next.startsWith(previous)) {
+                text.appendData(next.slice(previous.length));
+            }
+            else {
+                text.data = next;
+            }
+            return { children: [], dom: text, node: next };
+        }
+    }
+    else if (typeof previous !== 'string' && previous.tag === next.tag) {
+        const dom = drawn.dom;
+        for (const name of Object.keys(previous.attributes)) {
+            if (!(name in next.attributes)) {
+                dom.removeAttribute(name);
+            }
+        }
+        for (const [name, value] of Object.entries(next.attributes)) {
+            if (previous.attributes[name] !== value) {
+                dom.setAttribute(name, value);
+            }
+        }
+        return { children: patchChildren(dom, drawn.children, next.children), dom, node: next };
+    }
+    const replacement = create(next, parent.ownerDocument ?? parent);
+    parent.replaceChild(replacement.dom, drawn.dom);
+    return replacement;
+};
+const patchChildren = (parent, drawn, next) => {
+    const kept = next.map((node, index) => {
+        const before = drawn[index];
+        if (before) {
+            return patch(parent, before, node);
+        }
+        const made = create(node, parent.ownerDocument ?? parent);
+        parent.appendChild(made.dom);
+        return made;
+    });
+    for (const extra of drawn.slice(next.length)) {
+        extra.dom.parentNode?.removeChild(extra.dom);
+    }
+    return kept;
+};
+const adopt = (dom, node) => ({
+    children: typeof node === 'string'
+        ? []
+        : node.children.map((child, index) => adopt(dom.childNodes[index], child)),
+    dom,
+    node,
+});
+export class MarkdownWriter {
+    constructor(host, options = {}) {
+        this.host = host;
+        this.stream = new MarkdownStream();
+        this.drawn = [];
+        this.closed = 0;
+        this.text = '';
+        this.options = withDefaults(options);
+    }
+    configure(options) {
+        this.options = withDefaults(options);
+        this.closed = 0;
+        this.write(this.text, true);
+    }
+    write(text, final) {
+        if (!text.startsWith(this.text)) {
+            this.closed = 0;
+        }
+        this.text = text;
+        const read = this.stream.read(text, final);
+        if (this.drawn.length === 0 && this.host.childNodes.length > 0) {
+            this.take(read.blocks.map((block) => blockNode(block, false, this.options)));
+        }
+        const blocks = read.blocks;
+        const next = [];
+        for (const [index, block] of blocks.entries()) {
+            const before = this.drawn[index];
+            if (before && index < this.closed) {
+                next.push(before);
+                continue;
+            }
+            const node = blockNode(block, !final && index === blocks.length - 1, this.options);
+            if (before) {
+                next.push(patch(this.host, before, node));
+            }
+            else {
+                const made = create(node, this.host.ownerDocument);
+                this.host.appendChild(made.dom);
+                next.push(made);
+            }
+        }
+        for (const extra of this.drawn.slice(blocks.length)) {
+            extra.dom.parentNode?.removeChild(extra.dom);
+        }
+        this.drawn = next;
+        this.closed = read.closed;
+    }
+    clear() {
+        this.stream.reset();
+        this.drawn = [];
+        this.closed = 0;
+        this.text = '';
+        this.host.replaceChildren();
+    }
+    take(nodes) {
+        const children = [...this.host.childNodes];
+        const served = children
+            .map((child) => child.outerHTML ?? child.textContent)
+            .join('');
+        if (children.length === nodes.length && served === nodes.map(nodeHtml).join('')) {
+            this.drawn = nodes.map((node, index) => adopt(children[index], node));
+            return;
+        }
+        this.host.replaceChildren();
+    }
+}

package/dist/menu/root/menu-root.d.ts

@@ -66,6 +66,15 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * to where it was. A touch or a pen held still on the area opens it too, on
  * every browser, since iOS sends no `contextmenu` for one.
  *
+ * **One menu for many things.** `for` names an area outside the menu, such as
+ * a table, and `targets` says which things in it the menu is about, such as
+ * `tr`. A request over one of them opens the menu with it as
+ * `contextTarget`, which a `helix-before-open` listener reads to change the
+ * rows for it; a request over none of them is left to the page. `showAt()`
+ * opens the menu at a point, for an area that finds what was pressed itself,
+ * such as a canvas. Shift with a right-click leaves the browser's own menu to
+ * the reader.
+ *
  * **A trigger with its own action.** With `open-on="long-press"`, a press on
  * the trigger is the trigger's own, and a press held for half a second opens
  * the menu, as React Aria's `trigger="longPress"` does. Alt+Down or Alt+Up
@@ -193,6 +202,14 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * property only, there being no way to write a function in markup.
      */
     filterMatch?: ((text: string, filter: string) => boolean) | undefined;
+    /**
+     * With `context`, the id of an area outside the menu whose context menu
+     * this is, for one menu that serves a region the page draws elsewhere, such
+     * as a table. A right-click, a long press, Shift+F10 or the menu key there
+     * opens it, as on the `trigger` slot's area. Names an element in the same
+     * tree, the way `Tooltip.for` does.
+     */
+    for: string;
     /**
      * Accessible name for the surface.
      *
@@ -263,6 +280,12 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * a way back. `flyout` opens it in a panel of its own beside its row.
      */
     submenus: 'drill' | 'flyout';
+    /**
+     * With `context`, a selector for the things in the area a menu is about,
+     * such as `tr` for a table's rows. A request over one opens the menu with it
+     * as `contextTarget`, and a request over none of them is left to the page.
+     */
+    targets: string;
     /**
      * Which page is showing, and what is on it.
      *
@@ -357,6 +380,29 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     private openAt;
     /** Closes the menu and returns it to its first page. */
     hide(): void;
+    /**
+     * The thing the open context menu is about: the element of `targets` the
+     * reader asked over, the area where there are no `targets`, or what
+     * `showAt` was given. Set before `helix-before-open`, so a listener can
+     * change the rows for it, and kept until the menu next opens.
+     */
+    contextTarget: Element | undefined;
+    /**
+     * Opens the menu at a point in the viewport, as a context menu opens, for
+     * an area that finds what was pressed itself, such as a canvas or a map.
+     * `target` becomes `contextTarget`. An open menu moves there.
+     */
+    showAt(point: {
+        x: number;
+        y: number;
+    }, target?: Element): void;
+    /** The areas a context menu answers in: the `trigger` slot's, and the one `for` names. */
+    private get contextAreas();
+    /**
+     * The element of `targets` a request came from, the area where there are
+     * no `targets`, or nothing where a request over the area missed every one.
+     */
+    private targetOf;
     /**
      * Opens a context menu where the reader asked for it: at the pointer, or at
      * the area's corner where the keyboard asked and the event has no position.
@@ -459,6 +505,13 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     private inGrace;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** The area `for` named, which carries this menu's listeners while it is the context area. */
+    private watched;
+    /** The keys an area outside the menu passes on: only Shift+F10 and the menu key, while it is closed. */
+    private readonly handleAreaKeydown;
+    /** Moves the menu's listeners onto the area `for` names, and off the one it named before. */
+    private watchArea;
+    private unwatchArea;
     protected updated(changed: PropertyValues): void;
     /** Whether the surface is named by a submenu's page, which `nameSurface` undoes at the top. */
     private namedByPage;