@tonycodes-ui/mortar 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -2,54 +2,31 @@
 
 Mortar follows [semantic versioning](https://semver.org/). Before 1.0, a minor release may contain breaking changes, and it says so. Each release is published from its `v<version>` tag to [npmjs.com](https://www.npmjs.com/package/@tonycodes-ui/mortar) with npm provenance. Its GitHub release carries the exact archive and a `provenance.json` with the commit and SHA-512 integrity.
 
-## 0.12.0 (2026-10-27)
+## 0.13.0 (2026-11-05)
 
 ### Added
 
-- **Surfaces in the brand contract.** A brand can set `paper`, `surface` and `sunken` for each appearance (`--m-brand-l-paper|surface|sunken`, `--m-brand-d-paper|surface|sunken`), for example a navy dark page. Omitted, they keep today's values, and inverse bands take them from the other appearance. Mortar's text and status colours stay fixed, so check them against tinted surfaces: the brand builder's contrast table now does ([#59](https://github.com/tonycodes/mortar/issues/59)).
-- **Accent gradients.** `accentGradient` per appearance (`--m-brand-{l,d}-accent-gradient`) takes a `linear-`, `radial-` or `conic-gradient()` (or a `repeating-` form) whose stops are colours. It is painted only where a component opts in: Button and ActionLink `variant="accent"`, and `tone="accent"` on CallToAction, Hero and Banner, all with `onAccent` text. Without a gradient these paint the flat accent. The appearance exposes the fill as `--m-accent-fill` (an image, painted over `background-color: var(--m-accent)`) and `--m-inv-accent-fill` for inverse bands. On hover and active the fill takes a white or black wash chosen from the on-accent text (`--m-accent-wash`), so contrast rises instead of falling; browsers without relative colours keep the plain fill. The brand builder checks on-accent text against every stop at rest, hover and active.
-- **Heading font.** Headings and component titles (page, section, hero, card, settings, sign-in, auth, post, calendar and stacked-list titles, and prose headings) read `--m-font-heading`. It is unset by default, so headings keep the font they inherit; nothing changes until you set it. A brand can set `fonts: { body, heading }` (`--m-brand-font`, `--m-brand-font-heading`), which apply wherever the brand does, including a container-scoped ThemeProvider. Tailwind gains a `font-heading` utility, and `font-sans` follows a brand's body font.
-- `isBrandColour`, `isBrandGradient` and `isBrandFont` in `@tonycodes-ui/mortar/brand` check a value before you save it. Fonts accept bare `var(--name)` entries, as framework font loaders such as `next/font` hand out.
-- The brand builder checks strong lines (`--m-line-strong`, control borders) at 3:1 on page, surface and sunken.
-- **NetworkIllustration** ([#68](https://github.com/tonycodes/mortar/issues/68)) draws nodes and straight connections supplied as data, in a viewBox that scales to its container. Signals travel along connections that carry one, with a duration per illustration or per connection and an even stagger by default. It is decorative by default (`aria-hidden`). Given a `label`, it is one named image with an optional `description`. Colours are tokens: surface nodes with a strong-line outline, accent nodes and signals, and secondary labels. While signals move, a visible "Pause animation" button controls them, and `paused` with `onPausedChange` makes that choice controlled or shared. Signals stop automatically under `prefers-reduced-motion`, which shows the static drawing with no control, even before scripts run. They also stop while the document is hidden or the drawing is off screen. Returning never overrides the user's pause. `motion="static"` draws the same thing without motion. The animation is illustrative and never announced as live activity. It adds no dependency.
-- **Landing-page composition** ([#68](https://github.com/tonycodes/mortar/issues/68)). All additions are optional, and default markup is unchanged.
-  - **MarketingPage** frames a public page: a header, a `<main>` that grows to fill the viewport, and a footer. `align="center"` centres a single hero between them. The page is at least the viewport's height, and longer content scrolls rather than clipping.
-  - **Hero** `emphasis` marks a phrase of the title as `<em class="m-emphasis">` inside the one heading, in the brand's link colour. The title stays a string, and a phrase that isn't in it is ignored. `note` adds supporting content below the actions, such as a note or a Notice. `wide="copy" | "preview"` gives one split column three fifths of the width.
-  - **MarketingHeader** `tagline` shows a short descriptor beside the wordmark, outside the home link. It is hidden at 560px and narrower.
-  - **Footer** `layout="inline"` is one compact row of brand, notes, links, copyright and legal links. It wraps without changing reading order. `description` and `columns` are now optional.
-- **Open agent tooling in the package: an MCP server and the `mortar` CLI.** They read the installed version's catalogue, contracts, examples and guides, run locally, work offline and need no account. They add no runtime dependencies. See [Mortar for coding agents](https://github.com/tonycodes/mortar/blob/main/docs/agents.md).
-  - `mortar mcp` is a stdio MCP server (`claude mcp add mortar -- npx -y @tonycodes-ui/mortar mcp`) with six tools: `search_components`, `get_component` (props with types and defaults, usage notes, dependencies, marker, tested states and a JSX example), `get_build_packet` (for component names or a free-text brief: the dependency closure, imports, CSS and ThemeProvider setup, design principles, API conventions and matching page templates), `get_guide`, `list_kits` and `audit_app`.
-  - `mortar search`, `component`, `packet`, `audit`, `guide` and `kits` give the same answers on the command line, with `--json`.
-  - `mortar audit [path]` is a read-only static audit of an application: version range, imports and props that the installed version does not have (with 0.6 rename suggestions), invalid prop values, CSS overriding `.m-*` classes or `[data-m-component]`, raw colours beside Mortar components, a missing `styles.css` import or ThemeProvider, deep imports and local copies of Mortar source. It exits 1 when it finds errors.
-  - An agent skill, `skills/mortar/SKILL.md` (`npx mortar skill`), with the workflow defaults: search, packet, compose, audit, and contribute by pull request.
-- The package now also ships `AGENTS.md`, `CONTRIBUTING.md`, `TESTING.md` and the guides in `docs/`, which the tools read.
-- **`ErrorSummary`** (Foundation › Form controls): the problems that stopped a form submitting, listed above the form with a link to each field. Props: `errors` (`{ message; href?; target? }[]`; renders nothing when empty), `title` (default "There is a problem"), `headingLevel` (default 2), `autoFocus` (default true), `submitCount`, `id` and `className`. It is a `role="alert"` region named by its heading with `tabIndex={-1}`: it takes focus when it appears and whenever `submitCount` changes, but not while a fixed field's error clears. A link focuses its field without changing the URL hash; for a group such as a RadioGroup the checked or first radio takes focus, and the label or legend scrolls into view.
-- **Checkbox `error`**: the message is announced when it appears (`role="alert"`), the box is `aria-invalid` and `aria-describedby` links the description and the error. `required` adds the decorative `*` after the label, as on Input and Select. Without these props the markup is unchanged.
-- **RadioGroup `error`, `hint`, `required` and `id`**: the hint or error sits under the legend and describes the fieldset; with an error each radio is `aria-invalid`, and `required` marks every radio and adds `*` to the legend. Without these props the markup is unchanged.
+- **DataTable column priority and pinning for narrow screens** ([#77](https://github.com/tonycodes/mortar/issues/77)). `priority: "medium"` hides a column when the table is narrower than 480px and `priority: "low"` below 768px. This is the table's own width (a container query), so a table in a narrow panel collapses as it would on a phone. The first column always shows. A table with priorities keeps its truncated columns shrinking on narrow screens (down to 5rem) so the remaining columns fit instead of scrolling. `pin: "end"` keeps a column, such as row actions, at the trailing edge while the table scrolls sideways; its background follows the row's stripe, hover and selection. Tables without these props are unchanged.
+- **`mortar audit` flags raw HTML elements that a Mortar component replaces** (`raw-element`, [#76](https://github.com/tonycodes/mortar/issues/76)). In an app that uses Mortar, a raw `<table>` (use DataTable or Table), `<select>`, `<textarea>`, `<dialog>`, `<progress>` or `<input>` is an error, and a raw `<button>` is a warning. Each finding names the component to use and gives its file and line. Inputs are matched by `type`, so `hidden`, `file`, `range`, `color` and `image` inputs are not reported. HTML inside strings and template literals is ignored, including concise arrow returns, `case` and `throw`, and nested templates inside `${…}`. A backtick quoted inside `${…}` does not hide a later element. The mapping is read from a new `replaces` field on each component's contract in the catalogue, so new components extend it.
+- **Top navigation for application screens.** All additions are optional, and default markup is unchanged.
+  - **Dropdown groups.** `Navbar` `items` and `StackedShell` `navigation` take a labelled group, `{ label, items }`, beside plain links. A group opens a panel of links (each with an optional description, icon and `current`), using the same flyout as MarketingHeader. A group holding the current page is marked current. On narrow screens it opens inside the folded menu, and choosing a link closes the menu.
+  - **Bar tone.** `tone` on Navbar and StackedShell can be `"inverse"` (the other appearance, through the inverse remap) or `"accent"` (the brand's accent fill, or its gradient when it defines one). An accent bar has on-accent links and focus, an inverted primary action and outlined secondary ones. Dropdown panels keep the page's colours.
+  - **Page tabs.** StackedShell `tabs` (`{ label, items }`) adds a second row of page tabs under the bar, rendered as a TabNav.
+  - **Template.** A new application template, "Dashboard, top navigation" (`?recipe=stacked-dashboard`), composes StackedShell with all three.
+- **Split landing template** (`?recipe=split-landing`, [#68](https://github.com/tonycodes/mortar/issues/68)). A one-screen landing page composed only from public components: MarketingPage, a MarketingHeader with a tagline and the consumer's logo in the logo slot, a split Hero with an emphasised title, a Notice as supporting feedback, a NetworkIllustration, and an inline Footer. The CLI and MCP list it with the components it composes. Its browser test checks 320px reflow, 200% zoom, long text, keyboard order and visible focus in both themes, and that the emphasised phrase uses the green brand's link colour in light and dark. It also has a visual baseline.
+- **Docs: marketing surfaces and illustrations** ([theming](docs/theming.md#marketing-surfaces-and-illustrations)). Shows which existing tokens a branded landing page and its SVG read (canvas, text, borders, emphasis, accent and focus), and lists the supported extension points and what is not supported. No new tokens: every role already had one. [Mortar for coding agents](docs/agents.md#the-audit) and the agent skill now say that a clean audit is not proof that a page uses only Mortar components.
 
 ### Fixed
 
-- **Brand values are checked as colour syntax.** `brandToStyle`, `brandToCss`, `registerBrand` and `brandTokens` accepted any value made of letters, digits and brackets, so `accent: "linear-gradient(…)"` or `url(…)` passed and then failed silently in the browser. A colour is now hex, a colour name (including `transparent` and `currentcolor`), or `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, `color()`, `color-mix()`, `light-dark()` or `var()`, with nested functions checked the same way. Anything else throws an error that names the key, such as `dark.accent`.
-- **The audit no longer flags brand colours as `raw-colour`.** Colours inside a `brandTokens={…}` value (and a `const` it references in the same file), the arguments of `brandToCss`, `brandToStyle` and `registerBrand`, objects typed as or satisfying `BrandDefinition`, and `--m-brand-*` values are where colours belong. Other colours in the same file are still reported.
+- **Pinned DataTable cells keep the forced-colours highlight.** A selected or hovered pinned cell was specific enough to paint its own background over `Highlight`, so the text stayed `HighlightText` on `--m-selected`. Those backgrounds now sit below the forced-colours rule, and still cover the stripe in ordinary colours.
+- **Switch and Checkbox keep keyboard focus when their description comes and goes** ([#78](https://github.com/tonycodes/mortar/issues/78)). A description set in only one state (for example "Showing all 4 keys" when on) swapped the layout and remounted the input, so Space stopped working. Once a choice has had a description or error it keeps the described layout, and focus follows if the layout changes.
+- **MetricGroup no longer clips long values on phones** ([#81](https://github.com/tonycodes/mortar/issues/81)). Below 560px metrics still sit two to a row, but a value too wide for half a row (such as "Operational" at 320px) takes a row of its own, and a value wider than the row wraps.
+- **SegmentedControl no longer pushes the page sideways** ([#80](https://github.com/tonycodes/mortar/issues/80)). It is never wider than its container: options scroll inside the control, the selected option is scrolled into view on mount and on change, and the focus ring isn't clipped. Apps can drop local overflow wrappers.
+- **Accent navbar sunken contrast.** `Navbar` `tone="accent"` sets `--m-sunken` from `--m-accent-wash`, the same direction as an accent button's hover, so current items, avatars and hovers on the bar stay at least 4.5:1. A wash towards the on-accent text dropped the built-in green light bar to 4.2:1.
 
 ### Changed
 
-- **`--m-line-strong` in light is `#8b8b90`** (was `#8e8e93`), and `--m-inv-line-strong` in dark with it. The old value was 2.99:1 on the default sunken surface, just under the 3:1 that control borders need.
-- **Packages are published to npmjs.com.** Install with a plain `npm install @tonycodes-ui/mortar`; no registry configuration, account or token is needed. Releases are published from GitHub Actions with npm trusted publishing (OIDC, no long-lived token) and `--provenance`, so each version on npmjs.com links to the workflow run and commit that built it.
-- **The playground moved to GitHub Pages**, at https://mortar.tony.codes/playground/. The site root links the playground, GitHub, npm and the docs. The package `homepage` points there.
-- **Everything is free and in this repository.** The hosted Mortar Cloud preview (agent identities, OAuth MCP connections, hosted audits and planned paid plans) is retired. The kit, docs, playground and agent tooling are MIT licensed here, with no accounts, licence checks, telemetry or hosted service. GitHub maintainer review is the only review gate.
-- The sign-up and other auth page templates use `ErrorSummary` and `Checkbox error` instead of a local summary and a hand-wired terms error. The terms checkbox is now `required`.
-
-### Migration
-
-Versions up to 0.11 of the private-registry package `@tony-ui/mortar` were published only to the previous owner-hosted registry, `https://git.tony.codes/api/packages/tony/npm/`, which will be retired. New versions are on npmjs.com only. To upgrade, remove the scope override and install from npmjs.com:
-
-```sh
-npm config delete @tony-ui:registry --location=project
-npm install @tonycodes-ui/mortar@latest
-```
-
-A project that must stay on 0.11 or earlier keeps its scope override (`@tony-ui:registry=https://git.tony.codes/api/packages/tony/npm/` in `.npmrc`) while that registry remains available, or installs the archive attached to the version's [GitHub release](https://github.com/tonycodes/mortar/releases).
+- **Brands under a strict Content Security Policy are documented** ([#82](https://github.com/tonycodes/mortar/issues/82)). `brandTokens` and `registerBrand` inject an inline `<style>`, which `style-src 'self'` blocks, silently dropping the brand. `docs/theming.md` now shows the CSP-safe path: generate the rule with `brandToCss` at build time, import it after Mortar's styles, and pass ThemeProvider the brand name only. It also covers the options for runtime tenant brands (`'unsafe-inline'`, a hash, or serving each tenant's rule as a stylesheet).
 
 ## 0.11.0 (2026-10-20)
 

package/DESIGN.md

@@ -27,7 +27,7 @@ Every component follows these rules. New props must fit them, and the code revie
   - Tables align columns with `start | end`, not `left | right`.
 - **Tone.**
   - Status uses `Tone` (`neutral | info | success | warning | danger`).
-  - Section surfaces use `tone: "default" | "muted" | "inverse"`. Promotional bands (CallToAction, Hero and Banner) also take `"accent"`: the brand's accent fill, which is its accent gradient when it defines one, with on-accent text. Button and ActionLink take the same fill as `variant="accent"`. Each component offers only the tones it styles.
+  - Section surfaces use `tone: "default" | "muted" | "inverse"`. Promotional bands (CallToAction, Hero and Banner) also take `"accent"`: the brand's accent fill, which is its accent gradient when it defines one, with on-accent text. Button and ActionLink take the same fill as `variant="accent"`. The application bar (Navbar, and StackedShell through it) takes `tone: "default" | "inverse" | "accent"`; it has no muted tone. Each component offers only the tones it styles.
   - A destructive action is `tone="danger"`, and a destructive item in a list is `danger: true`.
   - Tone renders as `data-tone`.
 - **State.** Busy work is `loading`. Empty content is `empty?: { title; description?; action? }`. Errors are `error` (string).