@tristan2828/ui-foundation 4.2.0 → 4.3.0

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

@@ -437,7 +437,8 @@ is a filled-in example while the Widgets demo is still here).
    each value as its cell shows it), plus the sparse record showing its
    "not set" labels and no blank value. Its flows: the table's title link
    opens it, saving and cancelling the form return to it, creating opens
-   the new record's view, and Delete confirms then lands on the list.
+   the new record's view, and Delete confirms then lands on the list
+   (a soft-deleted entity's toast also has an Undo that restores it).
    Each quick action gets its own tests (copy `quick action: …` in
    `e2e/widget-view.spec.ts`): the change shows and the PATCH carries it
    (a list item sends the whole list), a server-side effect shows once the
@@ -518,3 +519,34 @@ is a filled-in example while the Widgets demo is still here).
   capability they don't have (a new field-type widget, say), don't copy
   one into `src/` to change it: raise it for the foundation (AGENTS.md
   "Changing the Foundation") and build the screen once the release ships.
+
+## Deleting
+
+The plan's "Deleting" line says which of three. The Widget reference is the
+soft one; copy it.
+
+- **Retired by a status:** no delete endpoint, screen or action. The
+  status field and its filter do the job.
+- **Soft-deleted:**
+  - *Model and migration:* a nullable `deleted_at timestamptz`, commented
+    in the migration (null means live; set by DELETE, cleared by restore).
+    It is never on the wire. `backend/app/models.py`,
+    `migrations/versions/0012_widget_soft_delete.py`.
+  - *Router:* `DELETE /<entity>/{id}` sets `deleted_at`; `POST
+    /<entity>/{id}/restore` clears it and returns the record (404 unless
+    it is deleted); the list leaves deleted records out unless asked
+    (`deleted=true` lists only them); get and update of a deleted record
+    are a 404. `backend/app/routers/widgets.py` (`_get_or_404`'s
+    `deleted` flag).
+  - *Contract, gateway, mocks:* `restore<Entity>` in `openapi.yaml`, the
+    gateway's `restore<Entity>`, a `useRestore<Entity>Mutation`, and mocks
+    that move the record aside (`deletedWidgets` in `src/mocks/data.ts`).
+  - *Screens:* the delete dialog says it can be undone, and the success
+    toast carries an Undo that restores (`delete-widget-action.tsx`).
+  - *MCP:* give the entity's `McpEntity` `delete` and `restore` (and add
+    `deleted` to its filters). Chats then get `delete(url)`, marked
+    destructive so the chat asks before each call, and `restore(url)`.
+    Both are logged with the whole record.
+- **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.

package/conventions/docs/design-language.md

@@ -208,14 +208,18 @@ outline (that stays `type-page-title` and `type-section-title`):
 
 | Class | For | Size / weight |
 |---|---|---|
-| `type-heading-1` | `#` in a note, with a rule under it | 26px / 700 |
-| `type-heading-2` | `##` | 20px / 600 |
-| `type-heading-3` | `###` | 17px / 600 |
+| `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 |
 
-The same text has two colour tokens of its own: `--link` (`text-link`), a
+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 same text has three 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), 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-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
 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/conventions/docs/entity-plan-template.md

@@ -187,6 +187,16 @@ except the quick actions, if any.
   rows").
 - Ownership: **shared** (every signed-in user sees every record) or
   **per-user** (each user sees only their own).
+- Deleting: how a record goes away, one of
+  - **retired by a status**: no delete; a status (Archived, Finished)
+    takes it out of the way, and a filter brings it back;
+  - **soft-deleted** (the default for a record someone typed): delete
+    marks it (`deleted_at`, null means live) and it comes back with
+    restore. The view's delete offers Undo, lists leave deleted records
+    out, and AI chats (MCP) can delete and restore it;
+  - **hard-deleted**: gone for good, back only from a backup. AI chats get
+    no delete for it. Say why it must be.
+  (`docs/foundation/add-an-entity.md` "Deleting".)
 
 ## Open questions
 

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

@@ -1,15 +1,20 @@
 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 headings:
+ * 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.
+ *
+ * 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.
  */
 export declare const PROSE: {
-    /** `#`: the largest, with a rule under it, so it reads as the top of the outline. */
-    readonly heading1: "type-heading-1 mt-4 border-b border-border pb-1.5 first:mt-0";
-    readonly heading2: "type-heading-2 mt-3 first:mt-0";
-    readonly heading3: "type-heading-3 mt-1 first:mt-0";
+    /** `#`: 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";
     /** `####` and deeper: a label, as before. */
     readonly heading4: "type-label mt-1 first:mt-0";
     /** Coloured as well as underlined. */

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

@@ -7,15 +7,20 @@
 // (what "Callout" inserts).
 import { InfoIcon, LightbulbIcon, MessageSquareWarningIcon, OctagonAlertIcon, TriangleAlertIcon, } from 'lucide-react';
 /**
- * Classes for written text's own elements. No colours on the headings:
+ * 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.
+ *
+ * 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.
  */
 export const PROSE = {
-    /** `#`: the largest, with a rule under it, so it reads as the top of the outline. */
-    heading1: 'type-heading-1 mt-4 border-b border-border pb-1.5 first:mt-0',
-    heading2: 'type-heading-2 mt-3 first:mt-0',
-    heading3: 'type-heading-3 mt-1 first:mt-0',
+    /** `#`: 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',
     /** `####` and deeper: a label, as before. */
     heading4: 'type-label mt-1 first:mt-0',
     /** Coloured as well as underlined. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.2.0",
+  "version": "4.3.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-bar: var(--heading-bar);
     --color-category-1: var(--category-1);
     --color-category-2: var(--category-2);
     --color-category-3: var(--category-3);

package/styles/theme.css

@@ -142,8 +142,8 @@
    * 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.
+   * `###` never look alike. Where the roles are used, each also gets a
+   * bar down its left edge that thins by level (--heading-bar).
    */
   --type-heading-1-size: 1.625rem;
   --type-heading-1-leading: 2rem;
@@ -208,6 +208,9 @@
   /* 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. */
+  --heading-bar: var(--blue-700);
   /* Categorical slots — a glyph tint, never a fill behind text. */
   --category-1: var(--category-1-700);
   --category-2: var(--category-2-700);
@@ -340,6 +343,7 @@
   --info-text: var(--blue-400);
   --link: var(--blue-400); /* on near-black: 8.90 */
   --rule: var(--gray-600); /* on near-black: 2.54 */
+  --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);
   --category-2: var(--category-2-400);