@tenphi/cookbook 0.22.1 → 0.24.0

package/docs/authoring.mdx

@@ -153,7 +153,7 @@ markers remain visible independently of their theme-aware backgrounds:
 | --------- | --------------------------------------------------------------------------------------------------- |
 | `Card`    | Optional `title` and `href`; renders an article or link with slot content                           |
 | `Steps`   | Ordered list container; supply `li` elements                                                        |
-| `Logo`    | Optional `label`, `decorative`, and `class`; renders the Cookbook mark                              |
+| `Logo`    | Optional `label`, `decorative`, and root `class`; renders the Cookbook mark                         |
 | `Preview` | Required `title`; optional `html`, `css`, and `javascript`; isolates examples in a sandboxed iframe |
 
 The public package exports each component's props type, such as `TabProps`,

package/docs/component-styles.md

@@ -13,7 +13,7 @@ its dimensions under `SiteLogo`.
 
 Heading levels are states of the same element. Customize them through a root
 property map such as `Heading: { textWrap: { "": "balance", ":is(h1)": "pretty" } }`.
-Markdown heading wrappers use `.level-h1` through `.level-h6` as root states.
+Markdown heading wrappers use `level=h1` through `level=h6` as root states.
 
 Block spacing uses `$margin-block-start` and `$margin-block-end` tokens. The
 owning `blockMargin` consumes both tokens, and a surrounding prose/layout rule
@@ -65,14 +65,14 @@ theme: {
     Sidebar: {
       LinkLabel: {
         preset: "body",
-        whiteSpace: { "": "nowrap", "@mobile": "normal" }
+        whiteSpace: { "": "nowrap", "!@md": "normal" }
       }
     }
   }
 }
 ```
 
-The `@mobile` value sits with the default value in one Tasty state map. Shared
+The `!@md` value sits with the default value in one Tasty state map. Shared
 tokens and presets keep the component aligned with the rest of the site, while
 Glaze resolves semantic colors across the configured schemes and contrast
 modes.
@@ -83,29 +83,36 @@ Cookbook registers these Tasty state aliases for `theme.styles`, custom
 components, and recipes. Widths use CSS `rem` units; their pixel values depend
 on the browser's font-size settings.
 
-| State             | Condition                                                  | Typical use                                        |
-| ----------------- | ---------------------------------------------------------- | -------------------------------------------------- |
-| `@compact`        | width ≤ 23rem                                              | Hide optional header controls in very narrow space |
-| `@small`          | width ≤ 40rem                                              | Stack compact grids                                |
-| `@shell-mobile`   | width ≤ 48rem                                              | Switch the page shell to its narrow arrangement    |
-| `@shell-desktop`  | width > 48rem                                              | Restore the wider shell arrangement                |
-| `@mobile`         | width < 50rem                                              | Mobile navigation and component layouts            |
-| `@desktop`        | width ≥ 50rem                                              | Desktop navigation and component layouts           |
-| `@medium-layout`  | 50rem ≤ width < 72rem                                      | Intermediate two-column layouts                    |
-| `@narrow-layout`  | width < 72rem                                              | Hide or reposition the desktop table of contents   |
-| `@popover-open`   | selected element is an open native popover                 | Use inside `@own(...)` for a descendant panel      |
-| `@reduced-motion` | `prefers-reduced-motion: reduce`                           | Remove optional motion                             |
-| `@light`          | explicit light theme, or system light when no theme is set | Match the site's effective light appearance        |
-| `@dark`           | explicit dark theme, or system dark when no theme is set   | Match the site's effective dark appearance         |
-| `@system-light`   | `prefers-color-scheme: light`                              | Read the operating system preference directly      |
-| `@system-dark`    | `prefers-color-scheme: dark`                               | Read the operating system preference directly      |
-
-The 48rem shell boundary, 50rem navigation boundary, and 72rem contents
-boundary serve different parts of the layout; their ranges intentionally
-overlap. Use the default state key `""` for the value outside the listed
-condition. Add your own aliases with `theme.states`; redefining a built-in
-alias also changes the renderer's responsive layout, so check the whole site
-when doing so.
+| State | Condition     | Typical use                                    |
+| ----- | ------------- | ---------------------------------------------- |
+| `@sm` | width > 40rem | Pagination links share one row                 |
+| `@md` | width ≥ 50rem | Desktop navigation and component layouts       |
+| `@lg` | width ≥ 72rem | Desktop table of contents fits beside the page |
+
+The conditions select wider viewports. Use `!@sm` for stacked
+pagination, `!@md` for mobile, and `!@lg` when the contents panel does not fit
+beside the page. Combine states when needed, for example `@md & !@lg` for the
+intermediate layout. Component-specific
+thresholds use direct media conditions, such as `@media(w <= 23rem)` for
+PackageVersion. Use the default state key `""` for the value outside a condition.
+Add your own aliases with `theme.states`; redefining a built-in alias also
+changes the renderer's responsive layout, so check the whole site when doing so.
+
+Native pseudo-classes need no alias. Use `:is(:popover-open)` on a root or
+`@own(:is(:popover-open))` for a selected descendant; the `:is()` wrapper is
+needed because the pinned linter's simple pseudo-class list omits `:popover-open`.
+
+### Appearance and motion states
+
+Use these shared aliases to match the site's appearance or respect motion preferences.
+
+| State             | Condition                                                  | Typical use                                 |
+| ----------------- | ---------------------------------------------------------- | ------------------------------------------- |
+| `@reduced-motion` | `prefers-reduced-motion: reduce`                           | Suppress optional motion                    |
+| `@light`          | Explicit light theme, or system light when no theme is set | Match the site's effective light appearance |
+| `@dark`           | Explicit dark theme, or system dark when no theme is set   | Match the site's effective dark appearance  |
+| `@system-light`   | `prefers-color-scheme: light`                              | Read the system preference directly         |
+| `@system-dark`    | `prefers-color-scheme: dark`                               | Read the system preference directly         |
 
 Use `@light` and `@dark` in component styles. They check the page root's
 `data-theme` attribute and use the system preference only when that attribute
@@ -113,6 +120,8 @@ is absent. Document rules that style the root itself use `@system-light` and
 `@system-dark` within their automatic-theme branch. Keep scheme media queries
 in the shared state definitions instead of repeating them in style objects.
 
+### State maps and validation
+
 In a generated site, run `npm run validate` (or the matching package manager's
 command) after editing `docs.config.ts`. It checks TypeScript theme properties,
 then runs Cookbook's preflight and production output checks. A misspelled
@@ -130,6 +139,17 @@ state keys for the component root. A sub-element cannot target its containing
 element: use root state maps for callout kinds, hover/active buttons, compact
 selectors, and syntax wrapping. Use Tasty element names such as `Primary > Search`
 instead of spelling out `[data-element="Primary"] > [data-element="Search"]`.
+For a state on the owning root, use a plain key: `DiffCode: { display: { "diff": "block" } }`.
+Use `@own(:first-child)` when a structurally selected link needs its own condition,
+instead of repeating its `Panel a` selector. `@prose` uses
+`@own(!:is([data-not-content] *))` to exclude selected elements inside isolated
+sections while preserving surrounding prose in the same Markdown root.
+
+Markdown also shares `@prose-block` for a block following block content
+(including linked Cards marked `data-block`), and `@prose-heading` for a heading
+following non-heading content. Both preserve the same isolated-content condition
+as `@prose`.
+
 A scalar override replaces the property's
 whole state map; use the matching state key without a default entry to change
 only that branch. `"": null` omits a declaration outside a condition. For
@@ -139,9 +159,9 @@ conditional `display`, `"": null` is also supported, including styles with
 For a compact language selector, customize the root with
 `LanguageSelect: { border: { "[data-compact]": "4px solid #border" } }`.
 The former `Compact` hook is now a root state. Likewise, customize code wrapping
-with `SyntaxHighlight: { whiteSpace: { ".td-syntax-wrap": "pre-wrap" } }`.
+with `SyntaxHighlight: { whiteSpace: { "[data-syntax-wrap]": "pre-wrap" } }`.
 Syntax category sub-elements such as `Keyword` target descendant spans; use
-`SyntaxHighlight.color[".td-syntax-keyword"]` when customizing the containing
+`SyntaxHighlight.color["[data-syntax-keyword]"]` when customizing the containing
 code element itself.
 
 Cookbook temporarily retains selectors for pseudo-element states that Tasty
@@ -194,7 +214,7 @@ it stays complete when a surface changes.
 
 #### Page shell
 
-* `Document`: `All`, `BlockSpacing`, `Body`, `Control`, `Pointer`, `ResponsiveWidth`, `ResponsiveHeight`, `Hidden`, `PrintHidden`, `DesktopBlock`, `DesktopFlex`, `ScreenReaderOnly`, `Strong`, `Link`, `NarrowBlock`, `MobileBlock`, `Code`, `FocusRing`, `CurrentLink`, `SearchOpen`
+* `Document`: `All`, `BlockSpacing`, `Body`, `Control`, `Pointer`, `ResponsiveWidth`, `ResponsiveHeight`, `Hidden`, `PrintHidden`, `DesktopBlock`, `DesktopFlex`, `ScreenReaderOnly`, `RouteAnnouncer`, `Strong`, `Link`, `NarrowBlock`, `MobileBlock`, `Code`, `FocusRing`, `CurrentLink`, `SearchOpen`
 * `Layout`: `Islands`
 * `PageFrame`: `MainFrame`, `SidebarFrame`, `Columns`
 * `MainPane`: None
@@ -442,8 +462,11 @@ colors with `theme.palette` (for example `syntax-keyword`). The default
 to the page background's saturation, in dark mode. Set
 `theme.palette["syntax-bg"]` to give code its own color seed;
 syntax text and token contrast resolve against that surface. Code fences, including
-MDX and diff blocks, use classes without inline style attributes. Custom Shiki
-transformers should emit classes; unsupported inline declarations fail with a
+MDX and diff blocks, use the `.tasty-code` root class, `data-syntax-*` modifiers, and
+`data-diff` on the owning code-block wrapper. Diff lines carry
+`data-inserted`/`data-deleted` with `data-element="Line"`. Custom Shiki
+transformers may add root classes; token anatomy and state use identities or
+modifiers. Unsupported token classes or inline declarations fail with a
 configuration hint.
 
 The production build rejects style attributes, style blocks (including inside
@@ -465,3 +488,9 @@ The fullscreen mobile dialog has no dimmed or blurred backdrop; the backdrop
 transition applies only to wider layouts.
 The Pagefind sizing adapter prevents inline layout declarations and is checked
 against the pinned UI version during builds.
+
+Root selectors may use stable classes (for example `.cookbook-markdown-content`,
+`.td-code-block`, and `.tasty-code`) or `data-component`. `data-element` identifies
+structural anatomy and must not serve as a variant or modifier. Use data modifiers
+for states; authored sub-element classes remain only in the Pagefind bridge because
+the library owns and updates its UI markup.

package/docs/custom-components.md

@@ -163,14 +163,14 @@ export const SiteTitleRoot = defineComponent("ProjectSiteTitle", {
     gap: "1x",
     inlineSize: "min 0",
     color: "#text",
-    preset: { "": "h4 / strong", "@mobile": "h5 / strong" },
+    preset: { "": "h4 / strong", "!@md": "h5 / strong" },
     textDecoration: "none",
     Logo: {
       $: "> svg",
       display: "block",
       flexShrink: "0",
-      inlineSize: { "": "2rem", "@mobile": "1.75rem" },
-      blockSize: { "": "2rem", "@mobile": "1.75rem" },
+      inlineSize: { "": "2rem", "!@md": "1.75rem" },
+      blockSize: { "": "2rem", "!@md": "1.75rem" },
       color: "#accent-text",
     },
     Label: {
@@ -233,8 +233,10 @@ at render time follow Tasty's usual precedence.
 Use `defineComponent` when authoring a component that should support
 `theme.customStyles`. Use `tasty` directly for ordinary Tasty creation or composition
 that does not need a configuration name. To define a named component around
-an existing React component that forwards `className`, pass it as `as` in the options. Use `className`
-when passing a class to a Tasty component from Astro.
+an existing React component that forwards `className`, pass it as `as` in the options. Tasty attaches its generated classes for extracted CSS. Use `data-element` identities
+and named sub-elements for owned anatomy, and modifiers/state maps for variants.
+Root selectors may keep stable classes, such as `.project-note`, or use
+`data-component`; avoid classes for sub-elements and modifiers.
 
 ### Extending a component
 

package/docs/migration.md

@@ -57,7 +57,7 @@ still use `--name`.
 Built-in markup now uses Tasty’s `data-element` identities instead of
 `data-tasty-anatomy`. Custom styles resolve through each owning definition.
 Heading levels move from `Heading.Level1`–`Level6` to root property state maps
-(`:is(h1)`–`:is(h6)`); Markdown wrappers use `.level-h1`–`.level-h6`.
+(`:is(h1)`–`:is(h6)`); Markdown wrappers use `[data-level=h1]`–`[data-level=h6]`.
 Panel first/second-child padding moves into `MainContent.Panel` token state maps.
 Header’s shared title/search defaults live on `Title` and `Search`; Footer’s
 only-child and hover states live on `MetaLink`, `MetaUpdated`, and `CreditLink`.
@@ -200,3 +200,65 @@ Apply these steps if your project still uses the earlier contracts:
 
 See [authoring](./authoring.mdx) for component usage and
 [working examples](./examples.md) for repository configuration patterns.
+
+## Root hooks, anatomy, and button variants
+
+Existing component root classes and Logo’s root `class` prop remain supported.
+Stable generated-content root classes remain available for global ownership, including
+`.cookbook-markdown-content`, `.cookbook-heading-wrapper`, `.td-code-block`,
+`.tasty-code`, `.cookbook-alert`, and `.td-mermaid`. Custom roots may also use classes
+or `data-component`.
+
+Owned sub-elements use `data-element` identities, and state uses data modifiers.
+Keep identity matching in structural `$` selectors. For example, hero actions use
+`data-element="Action"` with `data-primary`, `data-secondary`, or `data-minimal`.
+When customizing `Hero.PrimaryAction`, keep its variant condition in a property
+map, such as `color: { "@own(primary)": "#accent-text" }`.
+
+The code-block wrapper owns `data-diff` and `data-copy-state`; code and line rules
+use plain `diff` or `copy-state=copied` state keys. Line insertion/deletion flags
+belong to the line itself and use `@own(inserted)` / `@own(deleted)`.
+
+Heading wrappers carry `data-heading` and `level=h1` through `level=h6` states.
+Linked Cards carry `data-block` for prose spacing. Shared `@prose`, `@prose-block`,
+and `@prose-heading` conditions keep repeated Markdown declarations readable while
+preserving isolated `data-not-content` descendants and conditional omissions.
+
+Syntax transformers may emit root classes. Token/category hooks use modifiers,
+for example `SyntaxHighlight: { Keyword: { color: { "@own(syntax-keyword)": "#accent-text" } } }`.
+Tasty-generated style hashes and library-owned Pagefind sub-element classes remain.
+
+Hero buttons stay stationary on hover. Minimal actions share secondary outline
+padding, background, and border width, with a transparent border (`border: "#clear"`).
+Pagination links also reserve a transparent border before hover; hover changes
+only its color, preserving `theme.styles.Pagination.Link` border width and style.
+
+## Smaller shared state set
+
+Responsive aliases now use one width scale: `@sm` (>40rem), `@md` (≥50rem), and
+`@lg` (≥72rem). The conditions select wider viewports;
+the exclusive 40rem boundary preserves the former `@small` behavior. The renderer
+keeps its existing responsive thresholds.
+Use these replacements for the removed shortcuts in custom style maps:
+
+| Removed alias    | Replacement          |
+| ---------------- | -------------------- |
+| `@small`         | `!@sm`               |
+| `@mobile`        | `!@md`               |
+| `@narrow-layout` | `!@lg`               |
+| `@desktop`       | `@md`                |
+| `@compact`       | `@media(w <= 23rem)` |
+| `@shell-mobile`  | `@media(w <= 48rem)` |
+| `@shell-desktop` | `@media(w > 48rem)`  |
+| `@medium-layout` | `@md & !@lg`         |
+| `@popover-open`  | `:is(:popover-open)` |
+
+Inside a selected descendant's condition, use `@own(:is(:popover-open))`.
+The `:is()` wrapper accommodates the pinned linter's pseudo-class list.
+The shell and medium-layout aliases were unused by built-in components;
+PackageVersion's 23rem rule is now a direct media condition. Define a project
+alias in `theme.states` if you need a named threshold across your own components.
+
+If you customized `theme.states`, rename your breakpoint definitions and invert
+the old upper-bound conditions. For example, `"@mobile": "@media(w < 43rem)"`
+becomes `"@md": "@media(w >= 43rem)"`.

package/docs/site-navigation.md

@@ -21,6 +21,29 @@ navigation: {
 }
 ```
 
+## Client navigation
+
+Internal page links use client navigation over the generated static HTML. The
+router loads when an internal page link is hovered, focused, or clicked, so it
+does not add to the initial page download for readers who stay on one page. The
+current page stays visible while the next page and its styles load, then swaps
+without a full-page fade. Appearance preferences, sidebar expansion choices, and
+desktop sidebar scroll within the same navigation section are preserved. Article
+scroll resets to the top on page changes, including Back and Forward; links with
+fragments still navigate to their heading. The current page and its ancestors
+update from the destination markup. Mobile navigation and other open panels close.
+
+Search keeps its query and loaded engine between pages in the same language,
+and closes when a result is followed. Language changes initialize the translated
+search interface. External links, downloads, modified clicks, and links marked
+`data-astro-reload` keep normal browser behavior. Without JavaScript, page links
+use normal document navigation.
+
+Custom browser scripts should attach behavior through custom-element lifecycle
+callbacks or initialize on `astro:page-load`; bundled scripts are not rerun on
+every client navigation. The router and appearance initialization belong to the common page shell
+and remain available with replacement Header, Head, and PageFrame components.
+
 ## Search
 
 The production build creates a local Pagefind index. Readers can select Search

package/docs/upstream/manifest.json

@@ -1,10 +1,10 @@
 [
   {
     "name": "@tenphi/tasty",
-    "version": "3.9.9",
+    "version": "3.9.10",
     "license": "MIT",
     "repository": "https://github.com/tenphi/tasty",
-    "ref": "v3.9.9",
+    "ref": "v3.9.10",
     "directory": "upstream/tasty"
   },
   {

package/docs/upstream/tasty/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/tenphi/tasty/v3.9.9/assets/tasty.svg" width="128" height="128" alt="Tasty logo" />
+  <img src="https://raw.githubusercontent.com/tenphi/tasty/v3.9.10/assets/tasty.svg" width="128" height="128" alt="Tasty logo" />
 </p>
 
 <h1 align="center">Tasty</h1>
@@ -615,7 +615,7 @@ const tokens = theme.tasty(); // Ready-to-use Tasty tokens
 Syntax highlighting for Tasty styles in TypeScript, TSX, JavaScript, and JSX. Highlights color tokens, custom units, state keys, presets, and style properties inside `tasty()`, `tastyStatic()`, and related APIs.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/tenphi/tasty/v3.9.9/assets/tasty-vscode-highlight.png" width="512" alt="Tasty VS Code syntax highlighting example" />
+  <img src="https://raw.githubusercontent.com/tenphi/tasty/v3.9.10/assets/tasty-vscode-highlight.png" width="512" alt="Tasty VS Code syntax highlighting example" />
 </p>
 
 ## Built with Tasty

package/docs/upstream/tasty/docs/pipeline.md

@@ -2,7 +2,7 @@
 
 This document describes the style rendering pipeline that transforms style objects into CSS rules. The pipeline ensures that each style value is applied to exactly one condition through exclusive condition building, boolean simplification, and intelligent CSS generation.
 
-**Implementation:** [`src/pipeline/`](https://github.com/tenphi/tasty/blob/v3.9.9/src/pipeline) — TypeScript file names below are relative to that directory.
+**Implementation:** [`src/pipeline/`](https://github.com/tenphi/tasty/blob/v3.9.10/src/pipeline) — TypeScript file names below are relative to that directory.
 
 ## Overview
 

package/docs/upstream/tasty/docs/runtime-benchmarks.md

@@ -80,9 +80,9 @@ cold cases. These benchmarks do not include React, DOM work, stylesheet
 injection, style resolution, layout, or paint.
 
 The benchmark sources are colocated with the code they exercise:
-[`pipeline.bench.ts`](https://github.com/tenphi/tasty/blob/v3.9.9/src/pipeline/pipeline.bench.ts),
-[`parseStateKey.bench.ts`](https://github.com/tenphi/tasty/blob/v3.9.9/src/pipeline/parseStateKey.bench.ts), and the
-parser benchmark files under [`src/parser`](https://github.com/tenphi/tasty/blob/v3.9.9/src/parser).
+[`pipeline.bench.ts`](https://github.com/tenphi/tasty/blob/v3.9.10/src/pipeline/pipeline.bench.ts),
+[`parseStateKey.bench.ts`](https://github.com/tenphi/tasty/blob/v3.9.10/src/pipeline/parseStateKey.bench.ts), and the
+parser benchmark files under [`src/parser`](https://github.com/tenphi/tasty/blob/v3.9.10/src/parser).
 
 ## Empty Wrapper Overhead
 
@@ -91,7 +91,7 @@ Skipping the style pipeline does not make a `tasty()` component free. Even
 tracks another fiber, and Tasty still processes and forwards the element's
 props.
 
-[`tasty-overhead.bench.tsx`](https://github.com/tenphi/tasty/blob/v3.9.9/src/tasty-overhead.bench.tsx) compares 10,000
+[`tasty-overhead.bench.tsx`](https://github.com/tenphi/tasty/blob/v3.9.10/src/tasty-overhead.bench.tsx) compares 10,000
 raw `<div className>` siblings with 10,000 instances of one module-scoped
 `tasty({})` component. Both receive the same props, and the benchmark fails if
 they do not produce equivalent DOM.
@@ -125,7 +125,7 @@ snapshot experiment with controlled garbage collection.
 
 ## Cold Generation and Injection
 
-[`tasty-injection.bench.ts`](https://github.com/tenphi/tasty/blob/v3.9.9/src/tasty-injection.bench.ts) measures the extra
+[`tasty-injection.bench.ts`](https://github.com/tenphi/tasty/blob/v3.9.10/src/tasty-injection.bench.ts) measures the extra
 work when Tasty must generate and inject CSS that an otherwise equivalent page
 already has. It does not compare different stylesheet insertion techniques.
 
@@ -201,7 +201,7 @@ and dialogs open. Both paths go through the state-map and ref-counting
 machinery rather than the parser, so a regression in them is invisible to every
 other benchmark here.
 
-[`tasty-interaction.bench.tsx`](https://github.com/tenphi/tasty/blob/v3.9.9/src/tasty-interaction.bench.tsx) pairs each
+[`tasty-interaction.bench.tsx`](https://github.com/tenphi/tasty/blob/v3.9.10/src/tasty-interaction.bench.tsx) pairs each
 case with a raw-DOM equivalent driven by a hand-written stylesheet that
 produces the same computed color and background in both states. The benchmark
 fails if either arm resolves to anything else, so an arm that quietly rendered
@@ -255,7 +255,7 @@ reopening a menu re-pays the React wrapper, not the style pipeline.
 ## Page-Load Cold Start
 
 Every benchmark above deliberately excludes the network, module compilation and
-the first render. [`scripts/cold-start`](https://github.com/tenphi/tasty/blob/v3.9.9/scripts/cold-start) measures exactly
+the first render. [`scripts/cold-start`](https://github.com/tenphi/tasty/blob/v3.9.10/scripts/cold-start) measures exactly
 those: what a visitor waits for between requesting a page and seeing styled
 content, in a real Chromium under CDP network and CPU throttling.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/cookbook",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "Repository-native static documentation for Astro",
   "type": "module",
   "keywords": [
@@ -68,8 +68,8 @@
   "author": "Andrey Yamanov",
   "license": "MIT",
   "dependencies": {
-    "@tenphi/docs": "0.22.1",
-    "@tenphi/renderer": "0.22.1"
+    "@tenphi/docs": "0.24.0",
+    "@tenphi/renderer": "0.24.0"
   },
   "peerDependencies": {
     "astro": "^7.3.2"