@tristan2828/ui-foundation 4.22.0 → 4.24.0

package/conventions/docs/add-an-entity.md

@@ -642,3 +642,26 @@ soft one; copy it.
 - **Hard-deleted:** `DELETE` removes the row. Give the entity no `delete`
   in `mcp_entities.py`: a chat that read planted instructions would
   destroy data that only a backup returns.
+
+## Fields only a script writes
+
+Some fields the API takes on create and update are for a script, not for
+the people or chats using the app: an importer that runs again and again
+stores each record's id in the source it came from, so a re-run finds the
+record even after it's renamed. The API has to accept that id, for the
+importer. A chat that changed or cleared it would break the matching, and
+the next run would create the record a second time.
+
+- *MCP:* list the field's wire name in the entity's `McpEntity`
+  `script_only` (`script_only=("sourceId",)`). Chats still read it
+  (`fetch` shows it), but `create` and `update` refuse a call that names
+  it, by its wire name or its snake_case one, before the entity's own
+  function runs: `Nothing was saved.` and `- sourceId: set by a script,
+  not through MCP`, with no audit row. It's left out of the two tools'
+  descriptions, so a chat isn't invited to send it. The backend refuses
+  to start if a name isn't a field of the create or update schema, or if
+  create requires it (a chat could then never create one).
+- *Screens:* the form leaves the field out, for the same reason.
+- Don't use it for a field the server works out itself (`computed`) or
+  one that's never on the request: those aren't in the create or update
+  schema to begin with.

package/conventions/docs/design-language.md

@@ -208,18 +208,23 @@ outline (that stays `type-page-title` and `type-section-title`):
 
 | Class | For | Size / weight |
 |---|---|---|
-| `type-heading-1` | `#` in a note, with a 5px bar in `--heading-bar` | 26px / 700 |
-| `type-heading-2` | `##`, with a 3px bar in `--heading-bar` | 20px / 600 |
-| `type-heading-3` | `###`, with a 2px bar in `--rule` | 17px / 600 |
+| `type-heading-1` | `#` in a note, on a band in `--heading-band` with a 2px `--rule` along its foot | 28px / 700 |
+| `type-heading-2` | `##`, on a band in `--muted` | 20px / 600 |
+| `type-heading-3` | `###`, a small uppercase label in `--muted-foreground` | 12px / 600 |
 
-The bar runs down the heading's left edge and thins as the level drops,
-so the level reads at a glance as well as from the size.
+The bands run the text's full width, with 12px of padding either side.
+In text with a band, the rest (paragraphs, lists, tables, callouts,
+`###` and deeper) is inset by the same 12px, so it lines up with the
+words in the band rather than its edge; text with no band stays flush. The level reads at a glance: two bands of
+different strength, then a label.
 
-The same text has three colour tokens of its own: `--link` (`text-link`), a
+The same text has four colour tokens of its own: `--link` (`text-link`), a
 link's colour, blue as well as underlined (5.59:1 on white, 8.90:1 on the
-dark page); `--heading-bar` (`border-heading-bar`), the same blue for the
-bar beside `#` and `##`; and `--rule` (`bg-rule`), the 2px line a `---`
-divider draws, stronger than `--border`'s hairline. A callout (`> [!NOTE]`) is a 10% wash
+dark page); `--heading-band` (`bg-heading-band`), the `#` band, one step
+stronger than `--muted`; `--rule` (`bg-rule`), the 2px line a `---`
+divider draws, stronger than `--border`'s hairline, and the foot of the
+`#` band; and `--heading-bar`, which the headings' old left bars drew in,
+kept for apps but unused by the package. A callout (`> [!NOTE]`) is a 10% wash
 of its kind's tone behind ordinary text, with the icon in the tone's text
 shade: note `info`, tip `success`, important category slot 2, warning
 `warning`, caution `destructive`. The package draws all of it; an app

package/dist/components/app/markdown.js

@@ -5,7 +5,7 @@ import { cn } from 'cn';
 import { ExternalLinkIcon, SquareCheckIcon, SquareIcon } from 'lucide-react';
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../ui/table.js';
 import { CALLOUT_KINDS, remarkCallouts } from '../../lib/markdown-callout.js';
-import { CALLOUT_BOX, CALLOUT_LOOK, headingClass, PROSE } from './prose-look.js';
+import { CALLOUT_BOX, CALLOUT_LOOK, headingClass, PROSE, PROSE_INSET } from './prose-look.js';
 const REMARK_PLUGINS = [remarkGfm, remarkCallouts];
 function isCalloutKind(value) {
     return CALLOUT_KINDS.includes(value);
@@ -17,13 +17,14 @@ function omitNode(props) {
     delete rest.node;
     return rest;
 }
+// The text's colour first, so a level's own (`###`'s muted label) wins.
 const COMPONENTS = {
-    h1: (props) => _jsx("h3", { ...omitNode(props), className: cn(headingClass(1), 'text-foreground') }),
-    h2: (props) => _jsx("h4", { ...omitNode(props), className: cn(headingClass(2), 'text-foreground') }),
-    h3: (props) => _jsx("h5", { ...omitNode(props), className: cn(headingClass(3), 'text-foreground') }),
-    h4: (props) => _jsx("h6", { ...omitNode(props), className: cn(headingClass(4), 'text-foreground') }),
-    h5: (props) => _jsx("h6", { ...omitNode(props), className: cn(headingClass(5), 'text-foreground') }),
-    h6: (props) => _jsx("h6", { ...omitNode(props), className: cn(headingClass(6), 'text-foreground') }),
+    h1: (props) => _jsx("h3", { ...omitNode(props), className: cn('text-foreground', headingClass(1)) }),
+    h2: (props) => _jsx("h4", { ...omitNode(props), className: cn('text-foreground', headingClass(2)) }),
+    h3: (props) => _jsx("h5", { ...omitNode(props), className: cn('text-foreground', headingClass(3)) }),
+    h4: (props) => _jsx("h6", { ...omitNode(props), className: cn('text-foreground', headingClass(4)) }),
+    h5: (props) => _jsx("h6", { ...omitNode(props), className: cn('text-foreground', headingClass(5)) }),
+    h6: (props) => _jsx("h6", { ...omitNode(props), className: cn('text-foreground', headingClass(6)) }),
     a: (props) => {
         const { href, children, ...rest } = omitNode(props);
         if (!href)
@@ -74,5 +75,5 @@ const COMPONENTS = {
     td: (props) => _jsx(TableCell, { ...omitNode(props), className: "border-r border-border whitespace-normal last:border-r-0" }),
 };
 export function Markdown({ children, className, ...rest }) {
-    return (_jsx("div", { "data-slot": "markdown", ...rest, className: cn('flex min-w-0 flex-col gap-3 type-body text-foreground break-words', className), children: _jsx(ReactMarkdown, { remarkPlugins: REMARK_PLUGINS, components: COMPONENTS, children: children }) }));
+    return (_jsx("div", { "data-slot": "markdown", ...rest, className: cn('flex min-w-0 flex-col gap-3 type-body text-foreground break-words', PROSE_INSET, className), children: _jsx(ReactMarkdown, { remarkPlugins: REMARK_PLUGINS, components: COMPONENTS, children: children }) }));
 }

package/dist/components/app/milkdown-editor.js

@@ -714,7 +714,10 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                         'has-[[aria-readonly=true]]:text-muted-foreground', 
                         // The same type roles <Markdown> uses, so text reads the same
                         // being edited as being read.
-                        '[&_.ProseMirror]:flex [&_.ProseMirror]:flex-col [&_.ProseMirror]:gap-3', !inline && '[&_.ProseMirror]:min-h-20', 
+                        '[&_.ProseMirror]:flex [&_.ProseMirror]:flex-col [&_.ProseMirror]:gap-3', 
+                        // PROSE_INSET, on the editable element: with a heading's band
+                        // in the text, the rest lines up with the words in it.
+                        '[&_.ProseMirror:has(>:is(h3,h4))>:not(h3,h4)]:mx-3', !inline && '[&_.ProseMirror]:min-h-20', 
                         // ProseMirror's own required style (prosemirror-view's CSS): spaces
                         // as typed, so one at the end of a line isn't kept as &nbsp;.
                         '[&_.ProseMirror]:whitespace-pre-wrap [&_.ProseMirror]:break-words', '[&_ul]:flex [&_ul]:list-disc [&_ul]:flex-col [&_ul]:gap-1 [&_ul]:pl-6', '[&_ol]:flex [&_ol]:list-decimal [&_ol]:flex-col [&_ol]:gap-1 [&_ol]:pl-6', '[&_li[data-item-type=task]]:-ml-6 [&_li[data-item-type=task]]:flex [&_li[data-item-type=task]]:list-none [&_li[data-item-type=task]]:items-start [&_li[data-item-type=task]]:gap-2', '[&_li[data-item-type=task]>input]:mt-1 [&_li[data-item-type=task]>input]:size-4 [&_li[data-item-type=task]>input]:accent-primary', 

package/dist/components/app/prose-look.d.ts

@@ -1,20 +1,24 @@
 import { type LucideIcon } from 'lucide-react';
 import type { CalloutKind } from '../../lib/markdown-callout.js';
 /**
- * Classes for written text's own elements. No colours on the heading text:
- * <Markdown> adds the text colour, and the editor's read-only text is
- * muted as a whole.
+ * Classes for written text's own elements.
  *
- * Each of the first three heading levels has a bar down its left edge that
- * thins as the level drops: 5px in the heading-bar tone for `#`, 3px for
- * `##`, 2px in the rule tone for `###`. A level reads from the bar
- * as well as from the size.
+ * `#` and `##` sit on a full-width tinted band, stronger for `#`, which
+ * also has a 2px rule along its foot, so the top of the outline is marked
+ * twice. `###` is a small uppercase label. The band's text is always the
+ * foreground: the editor's read-only text is muted as a whole, and muted
+ * text on the `##` band measures 4.34:1.
+ *
+ * Where there's a band, the rest of the text (paragraphs, lists, tables,
+ * callouts, `###` and deeper) is inset by its padding, PROSE_INSET, so it
+ * lines up with the words inside the band rather than its edge.
  */
 export declare const PROSE: {
-    /** `#`: the largest, with the widest bar, so it reads as the top of the outline. */
-    readonly heading1: "type-heading-1 mt-4 border-l-[5px] border-heading-bar pl-3 first:mt-0";
-    readonly heading2: "type-heading-2 mt-3 border-l-[3px] border-heading-bar pl-3 first:mt-0";
-    readonly heading3: "type-heading-3 mt-1 border-l-2 border-rule pl-3 first:mt-0";
+    /** `#`: the largest, on the stronger band with a rule along its foot. */
+    readonly heading1: "type-heading-1 mt-4 rounded-t-sm border-b-2 border-rule bg-heading-band px-3 py-2 text-foreground first:mt-0";
+    readonly heading2: "type-heading-2 mt-5 rounded-sm bg-muted px-3 py-1.25 text-foreground first:mt-0";
+    /** `###`: a small uppercase label in the muted tone, no band. */
+    readonly heading3: "type-heading-3 mt-0.5 uppercase tracking-[0.08em] text-muted-foreground first:mt-0";
     /** `####` and deeper: a label, as before. */
     readonly heading4: "type-label mt-1 first:mt-0";
     /** Coloured as well as underlined. */
@@ -22,6 +26,14 @@ export declare const PROSE: {
     /** `---`: a 2px line in the rule tone, with room around it. */
     readonly rule: "my-2 h-0.5 rounded-full border-0 bg-rule";
 };
+/**
+ * On the text's container: when it has a band (the `<h3>` or `<h4>` a `#`
+ * or `##` renders as), everything else is inset by the band's 12px
+ * padding, so the text lines up with the words in the band. Text with no
+ * band stays flush, where the section's own text starts. A margin, so a
+ * list's own indent and a table's or callout's box keep theirs.
+ */
+export declare const PROSE_INSET = "[&:has(>:is(h3,h4))>:not(h3,h4)]:mx-3";
 /** A heading's classes by its Markdown level (1 for `#`). */
 export declare function headingClass(level: number): string;
 export type CalloutLook = {

package/dist/components/app/prose-look.js

@@ -7,20 +7,24 @@
 // (what "Callout" inserts).
 import { InfoIcon, LightbulbIcon, MessageSquareWarningIcon, OctagonAlertIcon, TriangleAlertIcon, } from 'lucide-react';
 /**
- * Classes for written text's own elements. No colours on the heading text:
- * <Markdown> adds the text colour, and the editor's read-only text is
- * muted as a whole.
+ * Classes for written text's own elements.
  *
- * Each of the first three heading levels has a bar down its left edge that
- * thins as the level drops: 5px in the heading-bar tone for `#`, 3px for
- * `##`, 2px in the rule tone for `###`. A level reads from the bar
- * as well as from the size.
+ * `#` and `##` sit on a full-width tinted band, stronger for `#`, which
+ * also has a 2px rule along its foot, so the top of the outline is marked
+ * twice. `###` is a small uppercase label. The band's text is always the
+ * foreground: the editor's read-only text is muted as a whole, and muted
+ * text on the `##` band measures 4.34:1.
+ *
+ * Where there's a band, the rest of the text (paragraphs, lists, tables,
+ * callouts, `###` and deeper) is inset by its padding, PROSE_INSET, so it
+ * lines up with the words inside the band rather than its edge.
  */
 export const PROSE = {
-    /** `#`: the largest, with the widest bar, so it reads as the top of the outline. */
-    heading1: 'type-heading-1 mt-4 border-l-[5px] border-heading-bar pl-3 first:mt-0',
-    heading2: 'type-heading-2 mt-3 border-l-[3px] border-heading-bar pl-3 first:mt-0',
-    heading3: 'type-heading-3 mt-1 border-l-2 border-rule pl-3 first:mt-0',
+    /** `#`: the largest, on the stronger band with a rule along its foot. */
+    heading1: 'type-heading-1 mt-4 rounded-t-sm border-b-2 border-rule bg-heading-band px-3 py-2 text-foreground first:mt-0',
+    heading2: 'type-heading-2 mt-5 rounded-sm bg-muted px-3 py-1.25 text-foreground first:mt-0',
+    /** `###`: a small uppercase label in the muted tone, no band. */
+    heading3: 'type-heading-3 mt-0.5 uppercase tracking-[0.08em] text-muted-foreground first:mt-0',
     /** `####` and deeper: a label, as before. */
     heading4: 'type-label mt-1 first:mt-0',
     /** Coloured as well as underlined. */
@@ -28,6 +32,14 @@ export const PROSE = {
     /** `---`: a 2px line in the rule tone, with room around it. */
     rule: 'my-2 h-0.5 rounded-full border-0 bg-rule',
 };
+/**
+ * On the text's container: when it has a band (the `<h3>` or `<h4>` a `#`
+ * or `##` renders as), everything else is inset by the band's 12px
+ * padding, so the text lines up with the words in the band. Text with no
+ * band stays flush, where the section's own text starts. A margin, so a
+ * list's own indent and a table's or callout's box keep theirs.
+ */
+export const PROSE_INSET = '[&:has(>:is(h3,h4))>:not(h3,h4)]:mx-3';
 /** A heading's classes by its Markdown level (1 for `#`). */
 export function headingClass(level) {
     return level === 1 ? PROSE.heading1 : level === 2 ? PROSE.heading2 : level === 3 ? PROSE.heading3 : PROSE.heading4;

package/package.json

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

@@ -49,6 +49,7 @@
     --color-info-text: var(--info-text);
     --color-link: var(--link);
     --color-rule: var(--rule);
+    --color-heading-band: var(--heading-band);
     --color-heading-bar: var(--heading-bar);
     --color-category-1: var(--category-1);
     --color-category-2: var(--category-2);

package/styles/theme.css

@@ -142,17 +142,18 @@
    * 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. Where the roles are used, each also gets a
-   * bar down its left edge that thins by level (--heading-bar).
+   * `###` never look alike. Where the roles are used, `#` and `##` also
+   * sit on a tinted band (--heading-band, --muted) and `###` is a small
+   * uppercase label (prose-look.ts).
    */
-  --type-heading-1-size: 1.625rem;
-  --type-heading-1-leading: 2rem;
+  --type-heading-1-size: 1.75rem;
+  --type-heading-1-leading: 2.25rem;
   --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-size: 0.75rem;
+  --type-heading-3-leading: 1.25rem;
   --type-heading-3-weight: 600;
 
   /*
@@ -208,8 +209,11 @@
   /* 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);
-  /* The bar down the left of a `#` or `##` heading in written text, so
-     the level shows at a glance (on white: 5.59). `###` takes --rule. */
+  /* The band behind a `#` heading in written text: one step stronger than
+     --muted, which `##`'s band takes. Its foot is a 2px --rule. */
+  --heading-band: var(--gray-200);
+  /* Written text's headings drew a bar in this until 4.24.0; nothing in
+     the package uses it now. Kept for an app that does (on white: 5.59). */
   --heading-bar: var(--blue-700);
   /* Categorical slots — a glyph tint, never a fill behind text. */
   --category-1: var(--category-1-700);
@@ -305,12 +309,12 @@
   --type-label-leading: 1.625rem;
   --type-caption-size: 0.9375rem;
   --type-caption-leading: 1.25rem;
-  --type-heading-1-size: 2rem;
-  --type-heading-1-leading: 2.5rem;
+  --type-heading-1-size: 2.1875rem;
+  --type-heading-1-leading: 2.8125rem;
   --type-heading-2-size: 1.5625rem;
   --type-heading-2-leading: 2.125rem;
-  --type-heading-3-size: 1.3125rem;
-  --type-heading-3-leading: 1.875rem;
+  --type-heading-3-size: 0.9375rem;
+  --type-heading-3-leading: 1.5625rem;
 
   --table-cell-px: 0.75rem;
   --table-cell-py: 0.75rem;
@@ -350,6 +354,8 @@
   --info-text: var(--blue-400);
   --link: var(--blue-400); /* on near-black: 8.90 */
   --rule: var(--gray-600); /* on near-black: 2.54 */
+  /* Stronger is lighter on the dark page: halfway from --muted to gray-700. */
+  --heading-band: color-mix(in oklab, var(--gray-900), var(--gray-700));
   --heading-bar: var(--blue-400); /* on near-black: 8.90 */
   /* Categorical slots — lighter shades to read against the dark page. */
   --category-1: var(--category-1-400);