@tristan2828/ui-foundation 3.12.0 → 3.14.0

package/dist/lib/markdown-merge.d.ts

@@ -0,0 +1,19 @@
+export declare class MarkdownMergeError extends Error {
+    constructor();
+}
+/**
+ * The Markdown to save: `original` with the edits that turned `baseline`
+ * (the editor's serialization as loaded) into `current` (its serialization
+ * now), every unchanged top-level block kept as `original` wrote it.
+ * Throws `MarkdownMergeError` rather than save something that means other
+ * than `current`.
+ */
+export declare function mergeMarkdown(original: string, baseline: string, current: string): string;
+/**
+ * The document's own marks, for writing a block the person edited the way
+ * the rest is written: its bullet (`-`, `*`, `+`) and its thematic break.
+ */
+export declare function markdownStyle(markdown: string): {
+    bullet: '-' | '*' | '+';
+    rule: '-' | '*' | '_';
+};

package/dist/lib/markdown-merge.js

@@ -0,0 +1,196 @@
+// Saving rich-text edits back to Markdown without rewriting what the
+// person didn't touch.
+//
+// The rich-text editor (RichTextEditor) loads Markdown into a document and
+// serializes it back. Its serializer is faithful to meaning but has its own
+// style: bullets, table padding, rules and hard breaks come back written
+// its way, and a reference-style link comes back inline. Saving that
+// whole would quietly rewrite every note anyone opened. So a save is
+// assembled block by block:
+//
+// - `baseline` is the editor's serialization of the document as loaded,
+//   `current` its serialization now. Equal means nothing was edited: the
+//   original comes back as it was, byte for byte.
+// - Otherwise each top-level block (a paragraph, a heading, a whole list or
+//   table) is matched by meaning: original ↔ baseline, then baseline ↔
+//   current. A block the person didn't change is written from the
+//   original's own source; only a changed or new block is written by the
+//   editor (in the document's own bullet and rule marks, `markdownStyle`).
+// - Blocks the editor can't show (a link reference's definition) are kept
+//   where they were.
+// - Guard: the result must mean exactly what the editor shows. If it
+//   wouldn't (two blocks fusing, say), the merge throws instead of saving
+//   something else; the draft stays on screen.
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+const processor = unified().use(remarkParse).use(remarkGfm);
+function parse(markdown) {
+    return processor.runSync(processor.parse(markdown));
+}
+// Fields that are about how a node was written, not what it means.
+const STYLE_ONLY = new Set(['position', 'data', 'spread', 'label', 'referenceType']);
+// A block's meaning as a comparable string: positions and source style
+// dropped, and a reference link resolved to the link it stands for.
+function meaning(node, definitions) {
+    if (Array.isArray(node))
+        return node.map((child) => meaning(child, definitions));
+    if (!node || typeof node !== 'object')
+        return node;
+    const md = node;
+    if (md.type === 'linkReference' || md.type === 'imageReference') {
+        const definition = definitions.get(String(md.identifier));
+        if (definition) {
+            return meaning({
+                type: md.type === 'linkReference' ? 'link' : 'image',
+                url: definition.url,
+                title: definition.title ?? null,
+                alt: md.alt,
+                children: md.children,
+            }, definitions);
+        }
+    }
+    const out = {};
+    for (const key of Object.keys(md).sort()) {
+        if (STYLE_ONLY.has(key))
+            continue;
+        out[key] = meaning(md[key], definitions);
+    }
+    if ((md.type === 'link' || md.type === 'image') && out.title === undefined)
+        out.title = null;
+    return out;
+}
+function blocks(markdown) {
+    const tree = parse(markdown);
+    const children = tree.children ?? [];
+    const definitions = new Map();
+    for (const child of children)
+        if (child.type === 'definition')
+            definitions.set(String(child.identifier), child);
+    return children.map((child) => {
+        const start = child.position?.start.offset ?? 0;
+        const end = child.position?.end.offset ?? 0;
+        return {
+            type: child.type,
+            start,
+            end,
+            source: markdown.slice(start, end),
+            key: JSON.stringify(meaning(child, definitions)),
+        };
+    });
+}
+// Longest common subsequence by meaning: which `to` block is which `from`
+// block, as a map from `to` index to `from` index.
+function match(from, to) {
+    const table = Array.from({ length: from.length + 1 }, () => new Array(to.length + 1).fill(0));
+    for (let i = from.length - 1; i >= 0; i--) {
+        for (let j = to.length - 1; j >= 0; j--) {
+            table[i][j] = from[i].key === to[j].key ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    }
+    const pairs = new Map();
+    let i = 0;
+    let j = 0;
+    while (i < from.length && j < to.length) {
+        if (from[i].key === to[j].key) {
+            pairs.set(j, i);
+            i++;
+            j++;
+        }
+        else if (table[i + 1][j] >= table[i][j + 1])
+            i++;
+        else
+            j++;
+    }
+    return pairs;
+}
+export class MarkdownMergeError extends Error {
+    constructor() {
+        super("This text can't be saved without changing parts you didn't edit. Undo the last change, or edit it in the form.");
+        this.name = 'MarkdownMergeError';
+    }
+}
+/**
+ * The Markdown to save: `original` with the edits that turned `baseline`
+ * (the editor's serialization as loaded) into `current` (its serialization
+ * now), every unchanged top-level block kept as `original` wrote it.
+ * Throws `MarkdownMergeError` rather than save something that means other
+ * than `current`.
+ */
+export function mergeMarkdown(original, baseline, current) {
+    if (current === baseline)
+        return original;
+    const originals = blocks(original);
+    const loaded = blocks(baseline);
+    const edited = blocks(current);
+    const loadedToOriginal = match(originals, loaded);
+    const editedToLoaded = match(loaded, edited);
+    // Each edited block's original, if it is one unchanged.
+    const sources = edited.map((_block, index) => {
+        const loadedIndex = editedToLoaded.get(index);
+        return loadedIndex === undefined ? undefined : loadedToOriginal.get(loadedIndex);
+    });
+    // A written block sits between the originals around it.
+    const items = edited.map((block, index) => {
+        const source = sources[index];
+        if (source !== undefined)
+            return { original: source, at: source };
+        const before = sources.slice(0, index).reverse().find((value) => value !== undefined) ?? -1;
+        const after = sources.slice(index + 1).find((value) => value !== undefined) ?? originals.length;
+        return { written: block, at: (before + after) / 2 };
+    });
+    // Blocks the editor never showed (definitions): after whatever came
+    // before them in the original.
+    const shown = new Set(loadedToOriginal.values());
+    originals.forEach((_block, index) => {
+        if (shown.has(index))
+            return;
+        let position = 0;
+        for (let k = items.length - 1; k >= 0; k--) {
+            if (items[k].at < index) {
+                position = k + 1;
+                break;
+            }
+        }
+        items.splice(position, 0, { original: index, at: index });
+    });
+    let out = '';
+    items.forEach((item, k) => {
+        const previous = items[k - 1];
+        if (!previous) {
+            if ('original' in item && item.original === 0)
+                out += original.slice(0, originals[0].start);
+        }
+        else if ('original' in previous && 'original' in item && item.original === previous.original + 1) {
+            out += original.slice(originals[previous.original].end, originals[item.original].start);
+        }
+        else {
+            out += '\n\n';
+        }
+        out += 'original' in item ? originals[item.original].source : item.written.source;
+    });
+    // The document ends the way the original ended, whichever block is last
+    // now: an edit to the last block adds no newline the person didn't type.
+    // Text written from nothing ends the way the editor ends it.
+    const ending = originals.length > 0
+        ? original.slice(originals[originals.length - 1].end)
+        : current.slice(edited.at(-1)?.end ?? current.length);
+    if (items.length > 0)
+        out += ending;
+    const saved = blocks(out)
+        .filter((block) => block.type !== 'definition')
+        .map((block) => block.key);
+    const shownNow = edited.filter((block) => block.type !== 'definition').map((block) => block.key);
+    if (JSON.stringify(saved) !== JSON.stringify(shownNow))
+        throw new MarkdownMergeError();
+    return out;
+}
+/**
+ * The document's own marks, for writing a block the person edited the way
+ * the rest is written: its bullet (`-`, `*`, `+`) and its thematic break.
+ */
+export function markdownStyle(markdown) {
+    const bullet = /^\s*([-*+])\s/m.exec(markdown)?.[1];
+    const rule = /^ {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*$/m.exec(markdown)?.[1];
+    return { bullet: bullet ?? '-', rule: rule ?? '-' };
+}

package/dist/testing/index.d.ts

@@ -11,7 +11,24 @@ export declare function forceMswOverride(page: Page, override: MswOverride): Pro
 export declare function waitForMswReady(page: Page): Promise<void>;
 /** Starts the page logged out: GET /auth/me answers 401 on first load. */
 export declare function forceLoggedOut(page: Page): Promise<void>;
-export declare function expectNoAxeViolations(page: Page): Promise<void>;
+/**
+ * Leaves an open popup's own scaffolding out of an axe run: Base UI's
+ * focus guards, invisible `aria-hidden` sentinels that hand focus back
+ * when you tab past a non-modal list. Hidden yet focusable is their job;
+ * they're never read out.
+ */
+export declare const POPUP_FOCUS_GUARDS = "[data-base-ui-focus-guard]";
+/**
+ * axe on the page as it is now. The options are for a state whose
+ * structure a rule doesn't fit, said where they're used: a list open in a
+ * portal sits outside the page's landmarks by design (`disableRules:
+ * ['region']`) and brings focus guards (`exclude: [POPUP_FOCUS_GUARDS]`),
+ * while every other rule, contrast included, still checks the list.
+ */
+export declare function expectNoAxeViolations(page: Page, options?: {
+    disableRules?: string[];
+    exclude?: string[];
+}): Promise<void>;
 export type A11ySuiteOptions = {
     /**
      * Form screens, which aren't in the sidebar: each entity's create route,

package/dist/testing/index.js

@@ -36,8 +36,27 @@ export function forceLoggedOut(page) {
         body: { detail: 'Not authenticated' },
     });
 }
-export async function expectNoAxeViolations(page) {
-    const results = await new AxeBuilder({ page }).analyze();
+/**
+ * Leaves an open popup's own scaffolding out of an axe run: Base UI's
+ * focus guards, invisible `aria-hidden` sentinels that hand focus back
+ * when you tab past a non-modal list. Hidden yet focusable is their job;
+ * they're never read out.
+ */
+export const POPUP_FOCUS_GUARDS = '[data-base-ui-focus-guard]';
+/**
+ * axe on the page as it is now. The options are for a state whose
+ * structure a rule doesn't fit, said where they're used: a list open in a
+ * portal sits outside the page's landmarks by design (`disableRules:
+ * ['region']`) and brings focus guards (`exclude: [POPUP_FOCUS_GUARDS]`),
+ * while every other rule, contrast included, still checks the list.
+ */
+export async function expectNoAxeViolations(page, options = {}) {
+    const builder = new AxeBuilder({ page });
+    if (options.disableRules?.length)
+        builder.disableRules(options.disableRules);
+    for (const selector of options.exclude ?? [])
+        builder.exclude(selector);
+    const results = await builder.analyze();
     expect(results.violations).toEqual([]);
 }
 // The app's own pages, read from the Primary nav. Below the sidebar's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.12.0",
+  "version": "3.14.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {
@@ -128,6 +128,7 @@
   "dependencies": {
     "@fontsource-variable/geist": "^5.3.0",
     "@hookform/resolvers": "^5.9.1",
+    "@milkdown/kit": "^7.22.2",
     "class-variance-authority": "^0.7.1",
     "cn": "^0.3.0",
     "date-fns": "^4.4.0",
@@ -136,8 +137,10 @@
     "react-day-picker": "^10.0.1",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
     "shadcn": "^4.21.0",
-    "tw-animate-css": "^1.4.0"
+    "tw-animate-css": "^1.4.0",
+    "unified": "^11.0.5"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.13.0",