@tristan2828/ui-foundation 3.20.1 → 3.22.0

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

@@ -0,0 +1,38 @@
+export declare const CALLOUT_KINDS: readonly ["note", "tip", "important", "warning", "caution"];
+export type CalloutKind = (typeof CALLOUT_KINDS)[number];
+type MdNode = {
+    type: string;
+    children?: MdNode[];
+    value?: string;
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+/**
+ * For react-markdown: a callout quote becomes a `<div data-callout="note">`
+ * (its marker gone), which <Markdown>'s `div` component draws as one.
+ */
+export declare function remarkCallouts(): (tree: unknown) => void;
+/**
+ * For the rich-text editor: a callout quote becomes a `callout` node
+ * (`kind`, `marker`), which its schema reads and `calloutHandler` writes.
+ */
+export declare function remarkCalloutNodes(): (tree: unknown) => void;
+/** The marker to write for a callout: as it was written, unless its kind changed. */
+export declare function calloutMarker(kind: CalloutKind, written: string | null | undefined): string;
+type ToMarkdownState = {
+    enter: (name: string) => () => void;
+    createTracker: (info: unknown) => {
+        move: (value: string) => void;
+        shift: (value: number) => void;
+        current: () => unknown;
+    };
+    containerFlow: (node: MdNode, info: unknown) => string;
+    indentLines: (value: string, map: (line: string, index: number, blank: boolean) => string) => string;
+};
+/**
+ * Writes a `callout` node the way remark writes a quote, with the marker
+ * as its first line. A first block that isn't a paragraph gets a blank
+ * line after the marker, so it can't run into it.
+ */
+export declare function calloutHandler(node: MdNode, _parent: unknown, state: ToMarkdownState, info: unknown): string;
+export {};

package/dist/lib/markdown-callout.js

@@ -0,0 +1,103 @@
+// Callouts (Notion's coloured boxes) in Markdown: GitHub's alert syntax, a
+// quote whose first line is its kind in brackets.
+//
+//   > [!NOTE]
+//   > Measure twice, cut once.
+//
+// It's plain Markdown, so a note stays readable anywhere (GitHub and
+// Obsidian render it as a callout too, anything else as a quote), and
+// remark parses it as a blockquote whose first text is the marker. These
+// plugins read that marker: `remarkCallouts` for <Markdown> (an element
+// react-markdown hands to its `div` component) and `remarkCalloutNodes`
+// for the rich-text editor (a `callout` node it has a schema for, written
+// back with `calloutHandler`). The merge (markdown-merge.ts) needs
+// neither: to it a callout is the quote it's written as.
+//
+// Five kinds, GitHub's: note, tip, important, warning, caution. The marker
+// is kept as it was written (`[!note]` stays lower case) unless the kind
+// changes, so an untouched callout never reads as edited.
+export const CALLOUT_KINDS = ['note', 'tip', 'important', 'warning', 'caution'];
+// The marker alone on the quote's first line: `[!NOTE]`, any case, spaces
+// after it allowed.
+const MARKER = /^\[!(note|tip|important|warning|caution)\][ \t]*(?:\n|$)/i;
+/**
+ * A quote that's a callout: its kind and marker as written, with the
+ * marker taken out of its first paragraph (and that paragraph too, when
+ * the marker was all of it). Null for any other node, untouched.
+ */
+function takeCallout(node) {
+    if (node.type !== 'blockquote')
+        return null;
+    const paragraph = node.children?.[0];
+    const text = paragraph?.type === 'paragraph' ? paragraph.children?.[0] : undefined;
+    if (!paragraph || text?.type !== 'text' || typeof text.value !== 'string')
+        return null;
+    const found = MARKER.exec(text.value);
+    if (!found)
+        return null;
+    const rest = text.value.slice(found[0].length);
+    if (rest)
+        text.value = rest;
+    else
+        paragraph.children.shift();
+    if (paragraph.children.length === 0)
+        node.children.shift();
+    return { kind: found[1].toLowerCase(), marker: found[0].trim() };
+}
+function visit(node, each) {
+    for (const child of node.children ?? [])
+        visit(child, each);
+    each(node);
+}
+/**
+ * For react-markdown: a callout quote becomes a `<div data-callout="note">`
+ * (its marker gone), which <Markdown>'s `div` component draws as one.
+ */
+export function remarkCallouts() {
+    return (tree) => {
+        visit(tree, (node) => {
+            const callout = takeCallout(node);
+            if (callout)
+                node.data = { ...node.data, hName: 'div', hProperties: { dataCallout: callout.kind } };
+        });
+    };
+}
+/**
+ * For the rich-text editor: a callout quote becomes a `callout` node
+ * (`kind`, `marker`), which its schema reads and `calloutHandler` writes.
+ */
+export function remarkCalloutNodes() {
+    return (tree) => {
+        visit(tree, (node) => {
+            const callout = takeCallout(node);
+            if (!callout)
+                return;
+            node.type = 'callout';
+            node.kind = callout.kind;
+            node.marker = callout.marker;
+        });
+    };
+}
+/** The marker to write for a callout: as it was written, unless its kind changed. */
+export function calloutMarker(kind, written) {
+    return written && written.slice(2, -1).toLowerCase() === kind ? written : `[!${kind.toUpperCase()}]`;
+}
+/**
+ * Writes a `callout` node the way remark writes a quote, with the marker
+ * as its first line. A first block that isn't a paragraph gets a blank
+ * line after the marker, so it can't run into it.
+ */
+export function calloutHandler(node, _parent, state, info) {
+    const exit = state.enter('blockquote');
+    const tracker = state.createTracker(info);
+    tracker.move('> ');
+    tracker.shift(2);
+    const marker = calloutMarker(node.kind, node.marker);
+    // Milkdown's serializer starts a container's flow on a new line; the
+    // marker's line is that line.
+    const body = state.containerFlow(node, tracker.current()).replace(/^\n+/, '');
+    const joined = !body ? marker : node.children?.[0]?.type === 'paragraph' ? `${marker}\n${body}` : `${marker}\n\n${body}`;
+    const value = state.indentLines(joined, (line, _index, blank) => '>' + (blank ? '' : ' ') + line);
+    exit();
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.20.1",
+  "version": "3.22.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": {

package/styles/index.css

@@ -47,6 +47,8 @@
     --color-info: var(--info);
     --color-info-foreground: var(--info-foreground);
     --color-info-text: var(--info-text);
+    --color-link: var(--link);
+    --color-rule: var(--rule);
     --color-category-1: var(--category-1);
     --color-category-2: var(--category-2);
     --color-category-3: var(--category-3);
@@ -105,6 +107,21 @@
   line-height: var(--type-caption-leading);
   font-weight: var(--type-caption-weight);
 }
+@utility type-heading-1 {
+  font-size: var(--type-heading-1-size);
+  line-height: var(--type-heading-1-leading);
+  font-weight: var(--type-heading-1-weight);
+}
+@utility type-heading-2 {
+  font-size: var(--type-heading-2-size);
+  line-height: var(--type-heading-2-leading);
+  font-weight: var(--type-heading-2-weight);
+}
+@utility type-heading-3 {
+  font-size: var(--type-heading-3-size);
+  line-height: var(--type-heading-3-leading);
+  font-weight: var(--type-heading-3-weight);
+}
 
 @layer base {
   * {

package/styles/theme.css

@@ -123,6 +123,22 @@
   --type-caption-size: 0.75rem; /* counts, metadata, helper text */
   --type-caption-leading: 1rem;
   --type-caption-weight: 400;
+  /*
+   * Headings inside written text (a record's notes: <Markdown> and the
+   * rich-text editor), not the screen's own outline. Three clear steps
+   * over the 14px body, roughly Notion's proportions, so `#`, `##` and
+   * `###` never look alike. Heading 1 also gets a rule under it (where
+   * the roles are used), so it reads as the top of the outline.
+   */
+  --type-heading-1-size: 1.625rem;
+  --type-heading-1-leading: 2rem;
+  --type-heading-1-weight: 700;
+  --type-heading-2-size: 1.25rem;
+  --type-heading-2-leading: 1.75rem;
+  --type-heading-2-weight: 600;
+  --type-heading-3-size: 1.0625rem;
+  --type-heading-3-leading: 1.5rem;
+  --type-heading-3-weight: 600;
 
   /*
    * Table density (design-language.md "Density"). The table primitive's
@@ -167,6 +183,12 @@
   --success-text: var(--green-800);
   --warning-text: var(--amber-800);
   --info-text: var(--blue-800);
+  /* A link in written text: coloured as well as underlined, so it reads
+     as a link at a glance (on white: 5.59). */
+  --link: var(--blue-700);
+  /* A thematic break (`---`) in written text: a 2px line meant to be
+     seen, stronger than --border's hairline (on white: 2.59). */
+  --rule: var(--gray-400);
   /* Categorical slots — a glyph tint, never a fill behind text. */
   --category-1: var(--category-1-700);
   --category-2: var(--category-2-700);
@@ -176,6 +198,11 @@
   --category-6: var(--category-6-700);
   --category-7: var(--category-7-700);
   --category-8: var(--category-8-700);
+  /* The zebra stripe (table.tsx: bg-muted/40 on even rows) mixed onto the
+     page, opaque: what a pinned table cell paints on an even row, so it
+     matches the row without letting scrolled columns show through. Mixed
+     in sRGB, as the browser composites the translucent stripe. */
+  --table-stripe: color-mix(in srgb, var(--muted) 40%, var(--background));
   --border: var(--gray-200);
   --input: var(--gray-200);
   --ring: var(--gray-400);
@@ -236,6 +263,8 @@
   --success-text: var(--green-400);
   --warning-text: var(--amber-400);
   --info-text: var(--blue-400);
+  --link: var(--blue-400); /* on near-black: 8.90 */
+  --rule: var(--gray-600); /* on near-black: 2.54 */
   /* Categorical slots — lighter shades to read against the dark page. */
   --category-1: var(--category-1-400);
   --category-2: var(--category-2-400);
@@ -245,6 +274,7 @@
   --category-6: var(--category-6-400);
   --category-7: var(--category-7-400);
   --category-8: var(--category-8-400);
+  --table-stripe: color-mix(in srgb, var(--muted) 40%, var(--background));
   --border: var(--white-a10);
   --input: var(--white-a15);
   --ring: var(--gray-500);