@tristan2828/ui-foundation 3.13.0 → 3.15.0

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

@@ -168,7 +168,10 @@ is a filled-in example while the Widgets demo is still here).
      `src/routes/<entity>/<entity>-schema.ts` (zod schema mirroring
      `<Entity>Create`/`<Entity>Update`, plus the form ↔ wire conversion
      functions — see `widgetToFormValues`/`formValuesToWidgetCreate` for
-     the shape)
+     the shape. A Markdown long text is checked with `refine`, never
+     trimmed, like Widget's `description`: a trim rewrites text nobody
+     touched, a leading indent that makes a code block or the text's
+     own ending)
    - `src/routes/widgets/widget-format.ts` →
      `src/routes/<entity>/<entity>-format.ts` (the lookups and formatters
      both the columns and the view render values with: badge variant maps,
@@ -194,7 +197,9 @@ is a filled-in example while the Widgets demo is still here).
      the plan edits in place** (`Edit in place`), shared by the form
      (through a `Controller`) and the view (through `editInPlace`), and
      the Markdown long text's `RichTextEditor` (on the form whether or
-     not it edits in place). Every other field's control stays inline in
+     not it edits in place), given a `placeholder` and `maxLength` (the
+     schema's limit, one constant both read, like Widget's
+     `DESCRIPTION_MAX_LENGTH`). Every other field's control stays inline in
      the form, as `widget-form.tsx`'s Category, Tags and Available From
      do. No `Edit in place` line and no Markdown long text: no fields
      file.

package/conventions/docs/cell-patterns.md

@@ -10,7 +10,12 @@ alternatives ([`column-options.md`](column-options.md)), not designed in the abs
 Patterns 12 (boolean), 15 (yes/no flipped in the row), 16 (title linking
 to its view), 17 (quick action on the view) and 18 (editable value) are
 the template's own references: Widget's In Stock and Name columns and its
-view render them, and their specs pin them. The other patterns from 11 on are
+view render them, and their specs pin them. Pattern 19 (stage circle)
+and the multi-value variant of 4, the dependency list in 10 and the
+pressed icon in 15 were each built for a real app's screen first; the
+package's Storybook renders them (`app/StageCircle`,
+`patterns/CellPatterns`), and its checks pin their accessibility and
+contrast in both themes. The other patterns from 11 on are
 marked **Unproven**: written ahead of a real
 column, so no app has tested them on real data yet. Prefer a proven
 pattern when one fits. When you use an unproven one, say so in the
@@ -109,6 +114,63 @@ narrow.
   cell, absent in an isolated Storybook story.
 - Encode the value in the glyph's **shape** (solid / half / slashed /
   dashed), not its colour.
+- **Give the trigger a focus ring**
+  (`rounded-sm outline-none focus-visible:ring-3 focus-visible:ring-ring/50`):
+  it's focusable, and a span has none of its own.
+
+### Several values: the icons side by side, every name in one tooltip
+
+A multi value (several categories on one record) where each value has
+its own icon and colour slot, and the column is narrow. The package's
+Storybook renders it (`patterns/CellPatterns`, "Icons with one tooltip").
+
+```tsx
+// values: the row's categories, `undefined` for one still loading.
+const names = values.map((value) => value?.name ?? '…').join(', ')
+if (values.length === 0) return emptyCell
+
+<Tooltip>
+  <TooltipTrigger
+    render={
+      <span role="img" aria-label={names} tabIndex={0}
+        className="inline-flex items-center gap-1 rounded-sm outline-none focus-visible:ring-3 focus-visible:ring-ring/50" />
+    }
+  >
+    {values.map((value, index) => {
+      if (!value) return <span key={index} className="text-muted-foreground">…</span>
+      const Icon = CATEGORY_ICON[value.icon]
+      return <Icon key={value.id} className={`size-4 shrink-0 ${CATEGORY_COLOR[value.color]}`} />
+    })}
+  </TooltipTrigger>
+  <TooltipContent>{names}</TooltipContent>
+</Tooltip>
+```
+
+- **One tooltip on the whole group**, listing every name in the record's
+  order ("Home, Finance"), not one per icon: one tab stop per cell, and
+  the names read as one value.
+- **The trigger is the `role="img"` span**, named by that same list. The
+  icons inside are presentational (children of an `img`), so they need no
+  `aria-hidden` of their own. Read-only: never a button.
+- **Each icon tinted with its value's colour slot**
+  ([`design-language.md`](design-language.md) "Categorical colour"), the
+  icon's shape telling values apart in greyscale.
+- **A value still loading shows "…"**, in the cell and in the names,
+  never a bare id.
+- **Where there's room** (the record's view), each icon sits beside its
+  name instead (pattern 2 per value, in a `flex flex-wrap gap-x-3 gap-y-1`
+  list), with no tooltip.
+
+**Testing note.** With several tooltips on a page, one that's closing
+stays in the DOM for a moment beside the one opening. A spec that reads
+the open tooltip must select `[data-slot=tooltip-content][data-open]`;
+the bare `[data-slot=tooltip-content]` can match the closing one, and
+reads the wrong text:
+
+```ts
+await page.getByRole('img', { name: 'Home, Finance', exact: true }).focus()
+await expect(page.locator('[data-slot=tooltip-content][data-open]')).toHaveText('Home, Finance')
+```
 
 ## 5. Enum → tone-mapped badge
 
@@ -116,6 +178,11 @@ A many-valued enum that collapses to good / neutral / bad. **The grouping
 is the decision, not the style** — see
 [`design-language.md`](design-language.md#mapping-an-enum-to-tones).
 
+An **ordered** status (a lifecycle every record moves through toward
+*done*) reads better as a stage circle beside the word (pattern 19);
+the tone badge stays right for a status with no order, or one whose end
+isn't *done*.
+
 Keep a separate short-label map when the API strings are full sentences
 (`"Yes – Full Crossplay"` → `Full`): read once in a dropdown they're right,
 read down 25 rows under a column header they're noise.
@@ -232,6 +299,40 @@ A one-to-many value (`★ 4.7 (3)` opening a per-person breakdown).
   can't be sorted server-side without a backend change
   (`enableSorting: false`).
 
+### A second example: what a row depends on
+
+The records a row waits on (parts it needs, a date that has to pass,
+other records that have to finish), summarised in the cell, listed in
+the popover. The package's Storybook renders it
+(`patterns/CellPatterns`, "Dependency list").
+
+- **The cell: a computed summary.** "Ready" when nothing holds the row,
+  else the count of what does ("1 hold", "2 holds"). Compute it where the
+  data is: the backend, when the column sorts or filters on it.
+- **The popover: every related record, grouped by kind**, each kind
+  under a small heading (`type-caption text-muted-foreground`) in its own
+  labelled group, in a fixed order. Each record keeps its kind's glyph
+  (`aria-hidden`, beside the name), so the kinds stay apart in
+  greyscale.
+- **Held reads dark, with its reason; clear reads muted.** A held record
+  is `text-foreground` with why after its name ("Bulb: unavailable",
+  "Delivery day: hasn't happened", or the blocking record's status);
+  a clear one is `text-muted-foreground` with a visually hidden ": clear",
+  so a screen reader hears the state the colour shows. No tone: a hold
+  is the normal state of waiting, not an error, and the count already
+  says how many.
+- **Name the popup**: `<PopoverContent aria-label={`What ${name} depends on`}>`.
+  It's a `dialog`, and axe fails one with no name.
+- **A row that links nothing has nothing to open**: render the summary as
+  plain text (`<span>Ready</span>`), not a button. A button that opens an
+  empty popover is a dead end.
+- **The trigger reads as the value**, with a dotted underline
+  (`underline decoration-dotted underline-offset-4`) and a focus ring,
+  so it looks openable without becoming a column of buttons.
+- The trigger's name starts with the summary it shows
+  (`aria-label={`${summary}: what ${name} depends on`}`), so it's still
+  found by its visible text, and says which row.
+
 ## 11. Number or currency — *Unproven*
 
 A count, a quantity, a price.
@@ -358,6 +459,91 @@ now", "happened"). Widget's In Stock column is the reference
 - **Cost:** one click changes data, with no confirmation. Only for values
   that are cheap to flip back; never for anything destructive.
 
+### A variant: a pressed icon inside another value's cell
+
+A yes/no that belongs to another value rather than having a column of
+its own: a "focus" flag that only exists while the status is "doing", a
+"pinned" mark on an open item. It's a small icon button inside the owning
+value's cell, beside its word. The package's Storybook renders it
+(`patterns/CellPatterns`, "Pressed icon in a cell").
+
+**Pick it over the Switch** when the yes/no only means something while
+another value allows it, or when a Switch and its words would crowd that
+value's cell. A yes/no that stands on its own keeps its own column and
+the Switch.
+
+```tsx
+// Off: faint. On: the destructive text tone, filled. The primitive's
+// pressed background is dropped: the icon carries the value.
+const FLAG_TOGGLE_CLASS =
+  'text-muted-foreground/80 hover:text-muted-foreground aria-pressed:bg-transparent ' +
+  'aria-pressed:text-destructive-text'
+
+// <entity>-focus-toggle.tsx, rendered inside the status cell
+export function FocusToggle({ item }: { item: Item }) {
+  const save = useSaveItemField(item.id) // useRecordUpdate, like Widget's useSaveWidgetField
+  return (
+    <>
+      <Toggle size="icon-xs" pressed={item.focus} aria-label={`Focus: ${item.name}`}
+        className={FLAG_TOGGLE_CLASS} onPressedChange={(focus) => save.mutate({ focus })}>
+        <FlagIcon className="group-aria-pressed/toggle:fill-current" />
+      </Toggle>
+      <span className="inline-flex size-3.5 shrink-0">
+        {save.isPending && <Spinner aria-label="Saving" className="size-3.5 text-muted-foreground" />}
+      </span>
+    </>
+  )
+}
+
+// The status cell: the word stays, the toggle only while the status allows it.
+<span className="inline-flex items-center gap-1.5">
+  <StageCircle {...STATUS_STAGE[item.status]} />
+  {STATUS_LABEL[item.status]}
+  {item.status === 'doing' && <FocusToggle item={item} />}
+</span>
+```
+
+- **`Toggle` from the package** (`/ui/toggle`, shadcn's, on Base UI), at
+  `size="icon-xs"`: a 24px target, the smallest WCAG 2.2 allows, which
+  keeps the row's height. It's `aria-pressed` by itself.
+- **Named for the row, not the state**: `Focus: <record name>`. The
+  pressed state is announced on its own; a name that changes with it
+  ("Unfocus") reads twice.
+- **The icon carries the value.** Filled when on
+  (`group-aria-pressed/toggle:fill-current`), outline when off, so it
+  reads in greyscale. Pick a glyph with an area to fill (`FlagIcon`,
+  `StarIcon`, `PinIcon`), not a line.
+- **Faint, but never below 3:1.** Off is `text-muted-foreground/80`, the
+  faintest step that still clears WCAG's 3:1 non-text minimum in light
+  mode (3.2:1; dark is 5.2:1). `/70` measures 2.7:1, and a control a
+  reader can't see fails them. Hover lifts it to full
+  `muted-foreground`. axe doesn't measure icons, so the package's
+  Storybook glyph check does.
+- **Tone: `destructive-text`, read as "flagged", not "error".** A flag
+  claims attention ahead of the rest of the row, and the destructive
+  tone is the one with that pull. The other tones are taken where it
+  sits: `info` is the in-progress status it belongs to (an info flag
+  beside an info stage disappears), `success` reads as done, and
+  `warning` says something may be wrong. It stays honest because it's
+  rare (a flag nearly every row carries is the "about a third" limit
+  broken) and because no word beside it says error. If a flag is common,
+  or does mean "something's wrong", it's an enum with a verdict
+  (pattern 5) instead.
+- **It saves on its own, through `useRecordUpdate`**, like the Switch: the
+  new value shows at once, and a refusal (a cap the server enforces)
+  puts it back with the toast giving the server's reason. The hook does
+  both; add nothing.
+- **The "Saving" slot is always there**, after the toggle, so nothing
+  moves while it saves, and nothing is disabled.
+- **Only rendered while the owning value allows it.** When the status
+  moves on, the toggle goes; what the server does with the flag then (it
+  clears it, or keeps it for next time) is the plan's rule, and shows
+  through the record it returns.
+- **On the record's view** it's the same component beside the owning
+  value in the header, as a quick action (pattern 17): the plan names it
+  under `Quick actions`. There its name is the field's label alone
+  (`Focus`), like the view's other controls.
+
 ## 16. Title linking to the record's view
 
 The column that names a record (its name or title), when the entity has a
@@ -415,6 +601,7 @@ type or pick from a list (text, a status) edits in place instead
 | The plan's field | The control | Accessible name |
 |---|---|---|
 | `yes/no`, in the header or a field row | A `Switch` (`size="sm"`) with the value in words beside it, `aria-hidden` (pattern 15) | The field's label: `In stock` |
+| A `yes/no` that belongs to another value (pattern 15's variant), beside that value in the header | The same pressed icon `Toggle` as in the table's cell | The field's label: `Focus` |
 | A sub-record list's `yes/no` item field | Each item a `Checkbox` inside a `<label>` with the item's text, so the text ticks it too; the list in one `role="group"` named for the list, described by the done-count | `Done: <item text>` (a visually hidden `Done: ` inside the label) |
 
 ```tsx
@@ -549,7 +736,12 @@ const price = editInPlace({
 - **Long text written as Markdown edits as rich text** (`RichTextEditor`):
   formatted where it's read, saved as Markdown with every block the person
   didn't touch kept exactly as written. On the form too, so it's one
-  control.
+  control. Give it a `placeholder` and the schema's limit as `maxLength`
+  (a count shows from 80% of it, in the destructive text tone once over).
+  Its keys: Ctrl/Cmd+K adds or edits a link (web and email addresses
+  only), Ctrl/Cmd+Shift+Enter ticks the task item the caret is in, and
+  Markdown pasted as plain text arrives formatted. Ctrl/Cmd+Enter stays
+  the save.
 - **The save is the single-field save** (`useRecordUpdate` with
   `optimistic: false, toastOnError: false`, the entity's
   `useEdit<Entity>Field`), `mutateAsync` of one field's PATCH.
@@ -558,3 +750,71 @@ const price = editInPlace({
 - **Cost:** a value that looks like text but edits on click can surprise.
   Keep it to the fields the plan names, and leave the form for everything
   else.
+
+## 19. Stage circle for an ordered status
+
+A status that's an ordered lifecycle (each record moves through the same
+stages, in the same order, toward one that means *done*), with one or
+more exit states off the side. A small circle beside the word fills as
+the record moves on. The package ships it: `StageCircle`, rendered with
+every stage and tone in its Storybook (`app/StageCircle`).
+
+| Stage (`stage`) | Drawn as | Say it for |
+|---|---|---|
+| `0` | a dashed outline | the first stage: not started |
+| `1`, `2`, `3` | the outline with a quarter, a half, three quarters filled | a stage under way, in order |
+| `'complete'` | a solid circle with a tick | the final stage: done |
+| `'exit'` | the outline, struck through | off the lifecycle: dropped, cancelled |
+
+```tsx
+import { StageCircle, type StageCircleStage, type StageCircleTone } from '@tristan2828/ui-foundation'
+
+// <entity>-format.ts: typed by the enum, so a new value can't go unmapped.
+const STATUS_STAGE: Record<ItemStatus, { stage: StageCircleStage; tone?: StageCircleTone }> = {
+  idea: { stage: 0 },
+  considering: { stage: 1 },
+  doing: { stage: 2, tone: 'info' },
+  done: { stage: 'complete', tone: 'success' },
+  dropped: { stage: 'exit' },
+}
+
+cell: ({ getValue }) => {
+  const status = getValue() as ItemStatus
+  return (
+    <span className="inline-flex items-center gap-1.5">
+      <StageCircle {...STATUS_STAGE[status]} />
+      {STATUS_LABEL[status]}
+    </span>
+  )
+}
+```
+
+- **The word stays**, in plain `text-foreground`. The circle is
+  `aria-hidden`; the word is what's read, and what a reader who doesn't
+  know the shapes yet goes by.
+- **The shape carries the stage, in greyscale.** Dashed, filling, solid,
+  struck through: the stage reads from the shape alone, and the tone only
+  reinforces it.
+- **Tone it like pattern 5:** the stage in progress is `info` ("notice
+  this"), complete is `success`, and the rest stay `muted` (the default).
+  The tones are the `*-text` shades, so the circle clears 3:1 on the page
+  in both themes, measured by the package's glyph check. An exit is
+  muted: dropped is an end, not a failure. Give it `destructive` only if
+  the exit really is bad news (failed, rejected).
+- **Map the stages in order**, the first `0`, the final `'complete'`, the
+  ones between `1`–`3` in order. Two middle stages fill a quarter and a
+  half; three, up to three quarters. More than three stages between
+  first and done is more than a fill can tell apart: use the tone badge.
+- **Stage circle or tone badge (pattern 5)?** The circle is for an
+  *ordered* status: every record goes the same way, and "how far along
+  toward done" is the question. A status with no order (`active` /
+  `paused` / `blocked`), or one whose end isn't *done*, keeps pattern 5.
+  Widget's Status is the second kind: `draft` → `active` → `archived` is
+  an order in time, but `archived` is retirement, not completion, and its
+  good state is the middle one. A tick on `archived` would say "done"
+  where nothing was finished, so it stays a tone badge.
+- **On the record's view** it's the same markup in the header, beside the
+  title; editing the status in place (pattern 18) wraps it in
+  `<EditableValue>` like a badge.
+- **Cost:** a reader learns the shapes once. Until then the word does the
+  work, which is why it stays.

package/conventions/docs/design-language.md

@@ -82,6 +82,24 @@ Two rules that keep this honest:
   greyscale screenshot and a printed page all lose it. The label text
   usually carries the meaning already; where a cell is a glyph rather than
   a word, vary the *shape* (filled / half / slashed) too, not just the hue.
+  The package's `StageCircle` does this for an ordered status: dashed,
+  filling, solid with a tick, struck through
+  ([`cell-patterns.md`](cell-patterns.md) pattern 19).
+
+## Glyphs and icons: 3:1
+
+An icon that carries meaning on its own (a stage circle, a category's
+icon, a pressed flag) must clear WCAG's **3:1 non-text minimum** against
+the background behind it, in both themes. axe measures text only, so the
+package's Storybook has a glyph check of its own: every `<svg>` in its
+design-language stories, its ink (with any opacity modifier painted over
+its background) against what's behind it. Every `*-text` tone, every
+category slot and `muted-foreground` clear it as they are. An opacity
+modifier is where it goes wrong: `text-muted-foreground/80` is the
+faintest step that still clears it in light mode (3.2:1), and `/70`
+doesn't (2.7:1). A deliberately faint icon that carries nothing on its
+own (an "empty" star beside a rating's filled ones, pattern 9) may go
+lower; say so in a comment.
 
 ## Categorical colour
 
@@ -119,10 +137,11 @@ Four things about them:
   `text-foreground`, so readability never depends on the hue. A slot used
   as a background needs its own contrast check, which nothing here does
   for you.
-- **Nothing re-measures them automatically.** All eight clear the 3:1
-  non-text minimum in both themes (measured, recorded in `theme.css`), but
-  axe checks text contrast, not icon contrast — so a change to these
-  values is not caught by any gate.
+- **The glyph check re-measures them.** All eight clear the 3:1
+  non-text minimum in both themes (recorded in `theme.css`). axe checks
+  text contrast, not icon contrast, so the package's Storybook glyph check
+  draws an icon in each slot (`patterns/CellPatterns`, "Icons with one
+  tooltip") and fails a change that takes one below 3:1.
 
 If you find yourself wanting a ninth, that is usually a sign the column
 should be showing a shape or a label rather than more colours.

package/dist/components/app/milkdown-editor.d.ts

@@ -1,2 +1,2 @@
 import type { RichTextEditorProps } from './rich-text-editor.js';
-export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly, autoFocus, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }: RichTextEditorProps): import("react").JSX.Element;
+export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly, autoFocus, placeholder, maxLength, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }: RichTextEditorProps): import("react").JSX.Element;

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

@@ -1,4 +1,4 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 // The rich-text editor behind RichTextEditor, loaded only when one opens
 // (rich-text-editor.tsx imports this lazily): Milkdown, a ProseMirror
 // editor whose Markdown goes in and out through remark, the same parser
@@ -15,15 +15,28 @@ import { jsx as _jsx } from "react/jsx-runtime";
 // - Headings render from <h3>, like <Markdown>: the page owns <h1> and
 //   <h2>. A task-list item renders a real checkbox that toggles it.
 // - Edited blocks are written in the document's own bullet and rule marks.
-import { useEffect, useRef } from 'react';
-import { defaultValueCtx, Editor, editorViewCtx, editorViewOptionsCtx, remarkStringifyOptionsCtx, rootCtx, } from '@milkdown/kit/core';
+// - Markdown pasted as plain text arrives formatted (still no HTML), and a
+//   copy out of the editor is Markdown.
+// - Ctrl/Cmd+K adds or edits a link (a box at the caret: web and email
+//   addresses only); Ctrl/Cmd+Shift+Enter ticks the task item the caret is
+//   in. Ctrl/Cmd+Enter stays the field's save.
+// - A placeholder in an empty document, and a count of the Markdown's
+//   length as it nears `maxLength`.
+import { useEffect, useId, useRef, useState } from 'react';
+import { defaultValueCtx, Editor, editorViewCtx, editorViewOptionsCtx, parserCtx, remarkStringifyOptionsCtx, rootCtx, schemaCtx, serializerCtx, } from '@milkdown/kit/core';
 import { history } from '@milkdown/kit/plugin/history';
 import { commands, inputRules, keymap, markInputRules, plugins, remarkPreserveEmptyLinePlugin, schema, } from '@milkdown/kit/preset/commonmark';
 import { gfm } from '@milkdown/kit/preset/gfm';
 import { Fragment, Slice } from '@milkdown/kit/prose/model';
 import { Plugin } from '@milkdown/kit/prose/state';
+import { Decoration, DecorationSet } from '@milkdown/kit/prose/view';
 import { $prose, getMarkdown } from '@milkdown/kit/utils';
 import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Field, FieldError, FieldLabel } from '../ui/field.js';
+import { Input } from '../ui/input.js';
+import { Popover, PopoverContent } from '../ui/popover.js';
+import { linkHref } from '../../lib/link-href.js';
 import { MarkdownMergeError, markdownStyle, mergeMarkdown } from '../../lib/markdown-merge.js';
 // The commonmark preset, minus the plugin that writes `<br />`. A $remark
 // plugin is a pair (its options and the plugin), spread into `plugins`.
@@ -102,14 +115,84 @@ function taskItemView(node, view, getPos) {
         ignoreMutation: (mutation) => mutation.target === box,
     };
 }
-export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly = false, autoFocus = false, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }) {
+// The task-list item the caret is in, ticked or unticked. False when the
+// caret isn't in one.
+function toggleTaskItem(view) {
+    const { $from } = view.state.selection;
+    for (let depth = $from.depth; depth > 0; depth--) {
+        const node = $from.node(depth);
+        if (node.type.name === 'list_item' && node.attrs.checked != null) {
+            view.dispatch(view.state.tr.setNodeMarkup($from.before(depth), undefined, { ...node.attrs, checked: !node.attrs.checked }));
+            return true;
+        }
+    }
+    return false;
+}
+function linkTarget(state) {
+    const link = state.schema.marks.link;
+    const { from, to, empty, $from } = state.selection;
+    if (!empty) {
+        let href = '';
+        state.doc.nodesBetween(from, to, (node) => {
+            const mark = link.isInSet(node.marks);
+            if (mark && !href)
+                href = String(mark.attrs.href);
+        });
+        return { from, to, href };
+    }
+    const mark = link.isInSet($from.marks());
+    if (!mark)
+        return { from, to, href: '' };
+    const start = $from.start();
+    let target = { from, to, href: String(mark.attrs.href) };
+    let runFrom = -1;
+    $from.parent.forEach((child, offset) => {
+        const childFrom = start + offset;
+        const childTo = childFrom + child.nodeSize;
+        if (!mark.isInSet(child.marks)) {
+            runFrom = -1;
+            return;
+        }
+        if (runFrom < 0)
+            runFrom = childFrom;
+        if (runFrom <= from && from <= childTo)
+            target = { from: runFrom, to: childTo, href: target.href };
+    });
+    return target;
+}
+// Sets (or, with `href` empty, removes) the link on the target. With
+// nothing selected and no link there, the address goes in as the link's
+// own text.
+function applyLink(view, target, href) {
+    const link = view.state.schema.marks.link;
+    const tr = view.state.tr;
+    if (target.from === target.to) {
+        if (!href)
+            return;
+        tr.insertText(href, target.from).addMark(target.from, target.from + href.length, link.create({ href }));
+    }
+    else {
+        tr.removeMark(target.from, target.to, link);
+        if (href)
+            tr.addMark(target.from, target.to, link.create({ href }));
+    }
+    view.dispatch(tr.scrollIntoView());
+}
+export default function MilkdownEditor({ id, defaultValue, onChange, onProblem, readOnly = false, autoFocus = false, placeholder, maxLength, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }) {
     const rootRef = useRef(null);
     const editorRef = useRef(null);
+    const [linkBox, setLinkBox] = useState(null);
+    const [length, setLength] = useState(defaultValue.length);
     // The latest props, for the editor's callbacks, which are set up once.
-    const latest = useRef({ onChange, onProblem, readOnly });
+    const latest = useRef({ onChange, onProblem, readOnly, placeholder });
     useEffect(() => {
-        latest.current = { onChange, onProblem, readOnly };
+        latest.current = { onChange, onProblem, readOnly, placeholder };
     });
+    const ids = useId();
+    const counterId = `${ids}-count`;
+    // The count shows from 80% of the limit: below that it's noise.
+    const showCount = maxLength !== undefined && length >= maxLength * 0.8;
+    const describedBy = [ariaDescribedBy, showCount ? counterId : undefined].filter(Boolean).join(' ');
     const attributes = {
         'aria-multiline': 'true',
         'aria-readonly': String(readOnly),
@@ -121,10 +204,12 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
         attributes['aria-label'] = ariaLabel;
     if (ariaLabelledBy)
         attributes['aria-labelledby'] = ariaLabelledBy;
-    if (ariaDescribedBy)
-        attributes['aria-describedby'] = ariaDescribedBy;
+    if (describedBy)
+        attributes['aria-describedby'] = describedBy;
     if (ariaInvalid)
         attributes['aria-invalid'] = 'true';
+    if (placeholder)
+        attributes['aria-placeholder'] = placeholder;
     const attributesKey = JSON.stringify(attributes);
     // The editor is made once, from the Markdown it opened with.
     useEffect(() => {
@@ -143,6 +228,7 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                 const merged = mergeMarkdown(original, baseline, current);
                 latest.current.onProblem?.(null);
                 latest.current.onChange(merged);
+                setLength(merged.length);
             }
             catch (error) {
                 if (!(error instanceof MarkdownMergeError))
@@ -161,6 +247,80 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
                 transformPasted: (slice) => new Slice(htmlToText(slice.content), slice.openStart, slice.openEnd),
             },
         }));
+        // Opens the link box at the start of what the link applies to.
+        const openLink = (view) => {
+            if (!view.editable)
+                return;
+            const target = linkTarget(view.state);
+            const point = view.coordsAtPos(target.from);
+            setLinkBox({
+                ...target,
+                anchor: {
+                    getBoundingClientRect: () => new DOMRect(point.left, point.top, 0, point.bottom - point.top),
+                    contextElement: view.dom,
+                },
+            });
+        };
+        // Paste, copy, the editor's own keys and the placeholder.
+        const input = $prose((ctx) => new Plugin({
+            props: {
+                // Plain text is read as Markdown, so `## Notes` or `**bold**`
+                // copied from another app arrives formatted; raw HTML in it
+                // still arrives as text. A paste with HTML of its own (from a
+                // web page) is ProseMirror's, through transformPasted above.
+                handlePaste: (view, event) => {
+                    const data = event.clipboardData;
+                    if (!data || !view.editable || data.getData('text/html'))
+                        return false;
+                    const text = data.getData('text/plain');
+                    if (!text || view.state.selection.$from.parent.type.spec.code)
+                        return false;
+                    const parsed = ctx.get(parserCtx)(text);
+                    if (!parsed || typeof parsed === 'string')
+                        return false;
+                    // Text with no Markdown in it (one plain paragraph) goes in
+                    // exactly as typed, spaces at its ends kept.
+                    const only = parsed.childCount === 1 ? parsed.firstChild : null;
+                    if (only?.type.name === 'paragraph' && only.childCount === 1 && only.textContent === text.trim()) {
+                        view.dispatch(view.state.tr.insertText(text).scrollIntoView());
+                        return true;
+                    }
+                    view.dispatch(view.state.tr.replaceSelection(Slice.maxOpen(htmlToText(parsed.content))).scrollIntoView());
+                    return true;
+                },
+                // A copy is Markdown, so it pastes into a plain text field
+                // (or another Markdown editor) as written.
+                clipboardTextSerializer: (slice) => {
+                    const doc = slice.content.firstChild?.isBlock
+                        ? ctx.get(schemaCtx).topNodeType.createAndFill(undefined, slice.content)
+                        : null;
+                    return doc ? ctx.get(serializerCtx)(doc) : slice.content.textBetween(0, slice.content.size, '\n\n');
+                },
+                handleKeyDown: (view, event) => {
+                    const mod = event.metaKey || event.ctrlKey;
+                    if (mod && !event.shiftKey && !event.altKey && event.key.toLowerCase() === 'k') {
+                        event.preventDefault();
+                        openLink(view);
+                        return true;
+                    }
+                    // Ctrl/Cmd+Shift+Enter in a task item ticks it, and goes no
+                    // further. Anywhere else it reaches the field, which saves.
+                    if (mod && event.shiftKey && event.key === 'Enter' && view.editable && toggleTaskItem(view)) {
+                        event.preventDefault();
+                        event.stopPropagation();
+                        return true;
+                    }
+                    return false;
+                },
+                decorations: (state) => {
+                    const text = latest.current.placeholder;
+                    const only = state.doc.childCount === 1 ? state.doc.firstChild : null;
+                    if (!text || !only || only.type.name !== 'paragraph' || only.content.size > 0)
+                        return null;
+                    return DecorationSet.create(state.doc, [Decoration.node(0, only.nodeSize, { 'data-placeholder': text })]);
+                },
+            },
+        }));
         const make = Editor.make()
             .config((ctx) => {
             ctx.set(rootCtx, root);
@@ -179,7 +339,8 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             .use(COMMONMARK)
             .use(gfm)
             .use(history)
-            .use(changes);
+            .use(changes)
+            .use(input);
         void make.create().then((editor) => {
             if (cancelled) {
                 void editor.destroy();
@@ -212,10 +373,52 @@ export default function MilkdownEditor({ id, defaultValue, onChange, onProblem,
             view.setProps({ editable: () => !readOnly, attributes: JSON.parse(attributesKey) });
         });
     }, [readOnly, attributesKey]);
-    return (_jsx("div", { ref: rootRef, "data-slot": "rich-text-editor", className: cn('min-h-24 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-2 type-body text-foreground break-words transition-colors', 'focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50 dark:bg-input/30', 'has-[[aria-invalid=true]]:border-destructive has-[[aria-invalid=true]]:ring-destructive/20', '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]:min-h-20 [&_.ProseMirror]:flex-col [&_.ProseMirror]:gap-3', '[&_h3]:type-section-title [&_h4]:type-section-title [&_h5]:type-label [&_h6]:type-label', '[&_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', '[&_a]:text-primary [&_a]:underline [&_a]:underline-offset-4', '[&_blockquote]:border-l-2 [&_blockquote]:border-border [&_blockquote]:pl-4 [&_blockquote]:text-muted-foreground', '[&_pre]:overflow-x-auto [&_pre]:rounded-lg [&_pre]:bg-muted [&_pre]:p-3 [&_pre]:font-mono', '[&_:not(pre)>code]:rounded [&_:not(pre)>code]:bg-muted [&_:not(pre)>code]:px-1 [&_:not(pre)>code]:font-mono', '[&_hr]:border-border', '[&_table]:w-full [&_table]:border-collapse [&_td]:border [&_td]:border-border [&_td]:px-2 [&_td]:py-1 [&_th]:border [&_th]:border-border [&_th]:px-2 [&_th]:py-1 [&_th]:text-left [&_th]:type-label', 
-        // Raw HTML from the text: shown as its characters, never as markup.
-        '[&_span[data-type=html]]:rounded [&_span[data-type=html]]:bg-muted [&_span[data-type=html]]:px-1 [&_span[data-type=html]]:font-mono [&_span[data-type=html]]:text-foreground', className) }));
+    const closeLink = () => {
+        setLinkBox(null);
+        editorRef.current?.action((ctx) => ctx.get(editorViewCtx).focus());
+    };
+    return (_jsxs(_Fragment, { children: [_jsx("div", { ref: rootRef, "data-slot": "rich-text-editor", className: cn('min-h-24 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-2 type-body text-foreground break-words transition-colors', 'focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50 dark:bg-input/30', 'has-[[aria-invalid=true]]:border-destructive has-[[aria-invalid=true]]:ring-destructive/20', '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]:min-h-20 [&_.ProseMirror]:flex-col [&_.ProseMirror]:gap-3', '[&_h3]:type-section-title [&_h4]:type-section-title [&_h5]:type-label [&_h6]:type-label', '[&_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', '[&_a]:text-primary [&_a]:underline [&_a]:underline-offset-4', '[&_blockquote]:border-l-2 [&_blockquote]:border-border [&_blockquote]:pl-4 [&_blockquote]:text-muted-foreground', '[&_pre]:overflow-x-auto [&_pre]:rounded-lg [&_pre]:bg-muted [&_pre]:p-3 [&_pre]:font-mono', '[&_:not(pre)>code]:rounded [&_:not(pre)>code]:bg-muted [&_:not(pre)>code]:px-1 [&_:not(pre)>code]:font-mono', '[&_hr]:border-border', '[&_table]:w-full [&_table]:border-collapse [&_td]:border [&_td]:border-border [&_td]:px-2 [&_td]:py-1 [&_th]:border [&_th]:border-border [&_th]:px-2 [&_th]:py-1 [&_th]:text-left [&_th]:type-label', 
+                // Raw HTML from the text: shown as its characters, never as markup.
+                '[&_span[data-type=html]]:rounded [&_span[data-type=html]]:bg-muted [&_span[data-type=html]]:px-1 [&_span[data-type=html]]:font-mono [&_span[data-type=html]]:text-foreground', 
+                // The placeholder, in an empty document only (a decoration).
+                '[&_p[data-placeholder]]:before:pointer-events-none [&_p[data-placeholder]]:before:float-left [&_p[data-placeholder]]:before:h-0 [&_p[data-placeholder]]:before:text-muted-foreground [&_p[data-placeholder]]:before:content-[attr(data-placeholder)]', className) }), showCount && (_jsx("p", { id: counterId, "data-slot": "rich-text-editor-count", className: cn('text-right type-caption tabular-nums', length > maxLength ? 'text-destructive-text' : 'text-muted-foreground'), children: length > maxLength
+                    ? `${(length - maxLength).toLocaleString()} characters over the limit of ${maxLength.toLocaleString()}`
+                    : `${length.toLocaleString()} of ${maxLength.toLocaleString()} characters` })), _jsx(Popover, { open: linkBox !== null, onOpenChange: (open) => !open && closeLink(), children: linkBox && (_jsx(LinkForm, { box: linkBox, onApply: (href) => {
+                        const editor = editorRef.current;
+                        editor?.action((ctx) => applyLink(ctx.get(editorViewCtx), linkBox, href));
+                        closeLink();
+                    } })) })] }));
+}
+// The link box: the address, Apply, and Remove link for an existing one.
+// Enter (Ctrl/Cmd+Enter too) applies the link and stays its own: editing
+// in place listens for Ctrl/Cmd+Enter through the portal, and would save
+// the field without it. Esc is the popover's: it closes the box only.
+function LinkForm({ box, onApply }) {
+    const [typed, setTyped] = useState(box.href);
+    const [error, setError] = useState(null);
+    const inputRef = useRef(null);
+    const inputId = useId();
+    const errorId = `${inputId}-error`;
+    const apply = () => {
+        const href = linkHref(typed);
+        if (href === null) {
+            setError('Enter a web or email address, like https://example.com.');
+            return;
+        }
+        onApply(href);
+    };
+    const onKeyDown = (event) => {
+        if (event.key === 'Enter' && event.target === inputRef.current) {
+            event.preventDefault();
+            event.stopPropagation();
+            apply();
+        }
+    };
+    return (_jsxs(PopoverContent, { anchor: box.anchor, align: "start", "aria-label": box.href ? 'Edit link' : 'Add link', initialFocus: inputRef, finalFocus: false, className: "w-80", onKeyDown: onKeyDown, children: [_jsxs(Field, { "data-invalid": error ? true : undefined, children: [_jsx(FieldLabel, { htmlFor: inputId, children: "Link address" }), _jsx(Input, { ref: inputRef, id: inputId, value: typed, placeholder: "https://", autoComplete: "off", "aria-invalid": error ? true : undefined, "aria-describedby": error ? errorId : undefined, onChange: (event) => {
+                            setTyped(event.target.value);
+                            setError(null);
+                        } }), error && _jsx(FieldError, { id: errorId, children: error })] }), _jsxs("div", { className: "flex gap-2", children: [_jsx(Button, { size: "sm", onClick: apply, children: "Apply" }), box.href && (_jsx(Button, { size: "sm", variant: "outline", onClick: () => onApply(''), children: "Remove link" }))] })] }));
 }

package/dist/components/app/rich-text-editor.d.ts

@@ -10,6 +10,14 @@ export type RichTextEditorProps = {
     /** Shown but not editable (while a save is in flight). */
     readOnly?: boolean;
     autoFocus?: boolean;
+    /** Shown while the document is empty (and given to screen readers as `aria-placeholder`). */
+    placeholder?: string;
+    /**
+     * The field's limit on the saved Markdown's length. From 80% of it, a
+     * count shows under the editor, in the destructive text tone once over.
+     * Typing isn't stopped: the form's schema still refuses a save over it.
+     */
+    maxLength?: number;
     className?: string;
     /** The field's label. A rich-text area must have one: this, or `aria-labelledby`. */
     'aria-label'?: string;

package/dist/components/app/stage-circle.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Where the record is: `0` the first stage (a dashed outline), `1`–`3` a
+ * stage under way (a quarter, a half, three quarters filled), `'complete'`
+ * the final stage (solid, with a tick), `'exit'` off the lifecycle (struck
+ * through: dropped, cancelled).
+ */
+export type StageCircleStage = 0 | 1 | 2 | 3 | 'complete' | 'exit';
+/**
+ * The tone, as text on the page (`*-text` tokens). `muted` is the default:
+ * colour only the stages that mean something (in progress `info`,
+ * complete `success`), like a tone-mapped badge (cell pattern 5).
+ */
+export type StageCircleTone = 'muted' | 'info' | 'success' | 'warning' | 'destructive';
+export interface StageCircleProps {
+    stage: StageCircleStage;
+    tone?: StageCircleTone;
+    className?: string;
+}
+/** The glyph only: put the status word beside it. Hidden from screen readers, which read the word. */
+export declare function StageCircle({ stage, tone, className }: StageCircleProps): import("react").JSX.Element;

package/dist/components/app/stage-circle.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// A stage circle (cell pattern 19): where a record is in an ordered
+// lifecycle, as a small circle that fills as it moves on. It sits beside
+// the status word, which stays: the shape carries the stage in greyscale
+// and the tone only reinforces it.
+//
+// Lucide has no part-filled circle, so it's drawn here, in currentColor
+// (16×16 viewBox, the ring and fill in the tone, the tick cut out of the
+// solid circle in the page's background).
+import { cn } from 'cn';
+const TONE_CLASS = {
+    muted: 'text-muted-foreground',
+    info: 'text-info-text',
+    success: 'text-success-text',
+    warning: 'text-warning-text',
+    destructive: 'text-destructive-text',
+};
+// The filled part of a stage under way: a pie from twelve o'clock,
+// clockwise, inside the ring with a gap so it reads as filling, not as a
+// thicker ring.
+const PIE = {
+    1: 'M8 8V4.5A3.5 3.5 0 0 1 11.5 8Z',
+    2: 'M8 8V4.5A3.5 3.5 0 0 1 8 11.5Z',
+    3: 'M8 8V4.5A3.5 3.5 0 1 1 4.5 8Z',
+};
+const RING = { cx: 8, cy: 8, r: 6, strokeWidth: 1.5, className: 'fill-none stroke-current' };
+/** The glyph only: put the status word beside it. Hidden from screen readers, which read the word. */
+export function StageCircle({ stage, tone = 'muted', className }) {
+    return (_jsxs("svg", { viewBox: "0 0 16 16", "aria-hidden": "true", "data-slot": "stage-circle", "data-stage": stage, className: cn('size-4 shrink-0', TONE_CLASS[tone], className), children: [stage === 0 && _jsx("circle", { ...RING, strokeDasharray: "2.4 2.3" }), (stage === 1 || stage === 2 || stage === 3) && (_jsxs(_Fragment, { children: [_jsx("circle", { ...RING }), _jsx("path", { d: PIE[stage], className: "fill-current" })] })), stage === 'complete' && (_jsxs(_Fragment, { children: [_jsx("circle", { cx: "8", cy: "8", r: "7", className: "fill-current" }), _jsx("path", { d: "M5 8.2 7.1 10.2 11 6", className: "fill-none stroke-background", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round" })] })), stage === 'exit' && (_jsxs(_Fragment, { children: [_jsx("circle", { ...RING }), _jsx("path", { d: "M4 12 12 4", className: "fill-none stroke-current", strokeWidth: "1.5", strokeLinecap: "round" })] }))] }));
+}

package/dist/components/ui/badge.d.ts

@@ -1,7 +1,7 @@
 import { useRender } from "@base-ui/react/use-render";
 import { type VariantProps } from "class-variance-authority";
 declare const badgeVariants: (props?: ({
-    variant?: "link" | "success" | "default" | "outline" | "secondary" | "ghost" | "destructive" | "warning" | "info" | "outline-success" | "outline-warning" | "outline-info" | "outline-destructive" | "tinted-success" | "tinted-warning" | "tinted-info" | "tinted-destructive" | null | undefined;
+    variant?: "link" | "success" | "default" | "outline" | "secondary" | "ghost" | "destructive" | "info" | "warning" | "outline-success" | "outline-warning" | "outline-info" | "outline-destructive" | "tinted-success" | "tinted-warning" | "tinted-info" | "tinted-destructive" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Badge({ className, variant, render, ...props }: useRender.ComponentProps<"span"> & VariantProps<typeof badgeVariants>): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export { Badge, badgeVariants };

package/dist/components/ui/popover.d.ts

@@ -2,7 +2,7 @@ import * as React from "react";
 import { Popover as PopoverPrimitive } from "@base-ui/react/popover";
 declare function Popover({ ...props }: PopoverPrimitive.Root.Props): React.JSX.Element;
 declare function PopoverTrigger({ ...props }: PopoverPrimitive.Trigger.Props): React.JSX.Element;
-declare function PopoverContent({ className, align, alignOffset, side, sideOffset, ...props }: PopoverPrimitive.Popup.Props & Pick<PopoverPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset">): React.JSX.Element;
+declare function PopoverContent({ className, align, alignOffset, side, sideOffset, anchor, ...props }: PopoverPrimitive.Popup.Props & Pick<PopoverPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset" | "anchor">): React.JSX.Element;
 declare function PopoverHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 declare function PopoverTitle({ className, ...props }: PopoverPrimitive.Title.Props): React.JSX.Element;
 declare function PopoverDescription({ className, ...props }: PopoverPrimitive.Description.Props): React.JSX.Element;

package/dist/components/ui/popover.js

@@ -8,8 +8,12 @@ function Popover({ ...props }) {
 function PopoverTrigger({ ...props }) {
     return _jsx(PopoverPrimitive.Trigger, { "data-slot": "popover-trigger", ...props });
 }
-function PopoverContent({ className, align = "center", alignOffset = 0, side = "bottom", sideOffset = 4, ...props }) {
-    return (_jsx(PopoverPrimitive.Portal, { children: _jsx(PopoverPrimitive.Positioner, { align: align, alignOffset: alignOffset, side: side, sideOffset: sideOffset, className: "isolate z-50", children: _jsx(PopoverPrimitive.Popup, { "data-slot": "popover-content", className: cn("z-50 flex w-72 origin-(--transform-origin) flex-col gap-2.5 rounded-lg bg-popover p-2.5 text-sm text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className), ...props }) }) }));
+// `anchor` is this repo's patch to the upstream primitive: a popover with
+// no trigger of its own, placed at a point (the rich-text editor's link
+// box, at the caret). A local patch: re-running `shadcn add popover` here
+// would overwrite it. Diff against upstream before taking a new version.
+function PopoverContent({ className, align = "center", alignOffset = 0, side = "bottom", sideOffset = 4, anchor, ...props }) {
+    return (_jsx(PopoverPrimitive.Portal, { children: _jsx(PopoverPrimitive.Positioner, { anchor: anchor, align: align, alignOffset: alignOffset, side: side, sideOffset: sideOffset, className: "isolate z-50", children: _jsx(PopoverPrimitive.Popup, { "data-slot": "popover-content", className: cn("z-50 flex w-72 origin-(--transform-origin) flex-col gap-2.5 rounded-lg bg-popover p-2.5 text-sm text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className), ...props }) }) }));
 }
 function PopoverHeader({ className, ...props }) {
     return (_jsx("div", { "data-slot": "popover-header", className: cn("flex flex-col gap-0.5 text-sm", className), ...props }));

package/dist/components/ui/toggle.d.ts

@@ -0,0 +1,8 @@
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import { type VariantProps } from "class-variance-authority";
+declare const toggleVariants: (props?: ({
+    variant?: "default" | "outline" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon-xs" | "icon-sm" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare function Toggle({ className, variant, size, ...props }: TogglePrimitive.Props & VariantProps<typeof toggleVariants>): import("react").JSX.Element;
+export { Toggle, toggleVariants };

package/dist/components/ui/toggle.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import { cva } from "class-variance-authority";
+import { cn } from "cn";
+// The `icon-xs`/`icon-sm` sizes are this repo's patch to the upstream
+// primitive, matching Button's: a square toggle holding one icon, like the
+// pressed flag inside a table cell (cell pattern 15). A local patch:
+// re-running `shadcn add toggle` here would overwrite it. Diff against
+// upstream before taking a new version.
+const toggleVariants = cva("group/toggle inline-flex items-center justify-center gap-1 rounded-lg text-sm font-medium whitespace-nowrap transition-all outline-none hover:bg-muted hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-pressed:bg-muted data-[state=on]:bg-muted dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", {
+    variants: {
+        variant: {
+            default: "bg-transparent",
+            outline: "border border-input bg-transparent hover:bg-muted",
+        },
+        size: {
+            default: "h-8 min-w-8 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+            sm: "h-7 min-w-7 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+            lg: "h-9 min-w-9 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+            // 24px: the smallest target WCAG 2.2 allows (2.5.8).
+            "icon-xs": "size-6 min-w-6 rounded-[min(var(--radius-md),10px)] [&_svg:not([class*='size-'])]:size-3.5",
+            "icon-sm": "size-7 min-w-7 rounded-[min(var(--radius-md),12px)]",
+        },
+    },
+    defaultVariants: {
+        variant: "default",
+        size: "default",
+    },
+});
+function Toggle({ className, variant = "default", size = "default", ...props }) {
+    return (_jsx(TogglePrimitive, { "data-slot": "toggle", className: cn(toggleVariants({ variant, size, className })), ...props }));
+}
+export { Toggle, toggleVariants };

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { ListEditor } from './components/app/list-editor.js';
 export { PasswordInput } from './components/app/password-input.js';
 export { RichTextEditor, type RichTextEditorProps } from './components/app/rich-text-editor.js';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
+export { StageCircle, type StageCircleProps, type StageCircleStage, type StageCircleTone, } from './components/app/stage-circle.js';
 export { ThemeProvider } from './components/theme-provider.js';
 export { LoginRoute, type LoginRouteProps } from './routes/login.js';
 export { RegisterRoute } from './routes/register.js';

package/dist/index.js

@@ -19,6 +19,7 @@ export { ListEditor } from './components/app/list-editor.js';
 export { PasswordInput } from './components/app/password-input.js';
 export { RichTextEditor } from './components/app/rich-text-editor.js';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
+export { StageCircle, } from './components/app/stage-circle.js';
 export { ThemeProvider } from './components/theme-provider.js';
 // Screens outside the app shell
 export { LoginRoute } from './routes/login.js';

package/dist/lib/link-href.d.ts

@@ -0,0 +1,2 @@
+/** The `href` to save, `''` to remove the link, or `null` when it's refused. */
+export declare function linkHref(typed: string): string | null;

package/dist/lib/link-href.js

@@ -0,0 +1,22 @@
+// The address a link in the rich-text editor points at, from what the
+// person typed. Web and email addresses only: a bare `example.com` becomes
+// `https://example.com` and a bare `name@example.com` a `mailto:`; a path
+// on this site (`/x`) or a heading (`#x`) is kept. Any other scheme
+// (`javascript:`, `data:`, `file:`) is refused, so a link can't run code
+// or reach a local file.
+/** The `href` to save, `''` to remove the link, or `null` when it's refused. */
+export function linkHref(typed) {
+    const value = typed.trim();
+    if (value === '')
+        return '';
+    if (/^(https?:\/\/|mailto:|tel:)/i.test(value))
+        return value;
+    // A scheme of its own (`javascript:`), not a port (`example.com:8080`).
+    if (/^[a-z][a-z0-9+.-]*:(?!\d)/i.test(value))
+        return null;
+    if (value.startsWith('/') || value.startsWith('#'))
+        return value;
+    if (/^[^\s@/]+@[^\s@/]+\.[^\s@/]+$/.test(value))
+        return `mailto:${value}`;
+    return `https://${value}`;
+}

package/dist/lib/markdown-merge.js

@@ -169,13 +169,14 @@ export function mergeMarkdown(original, baseline, current) {
         }
         out += 'original' in item ? originals[item.original].source : item.written.source;
     });
-    const last = items[items.length - 1];
-    if (last && 'original' in last && last.original === originals.length - 1) {
-        out += original.slice(originals[originals.length - 1].end);
-    }
-    else if (items.length > 0) {
-        out += '\n';
-    }
+    // 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);

package/package.json

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