@tenphi/cookbook 0.25.3 → 0.26.0

package/docs/authoring.mdx

@@ -130,6 +130,30 @@ import { Preview } from "@tenphi/cookbook/components";
   css={"button { padding: 0.75rem; }"}
 />
 
+To demonstrate your own library, build it into the site's public directory
+(`public/` by default) and list the files in `scripts` by their public path,
+without the Astro `base`. Cookbook inlines each file, in order, before
+`javascript`, so the authored code can use what they define. Each file runs as
+a classic script, so use a self-contained IIFE or UMD build without `import` or
+`export`:
+
+```mdx
+<Preview
+  title="Library button"
+  html={"<acme-button>Save</acme-button>"}
+  scripts={["/demo/button.js"]}
+  javascript={"document.querySelector('acme-button').loading = true;"}
+/>
+```
+
+Inlining keeps the preview isolated and needs no request, so the demo works in
+`astro dev`, `astro preview`, and offline as well as on the deployed site. A
+`<script src>` in `html` is a cross-site request from the sandboxed frame:
+`astro dev` rejects it, and Chrome blocks it from local servers. View source
+shows each inlined file as a `<script src>` tag. Every preview embeds its own
+copy, so keep demo bundles small. A missing file or a path outside the public
+directory fails the build.
+
 ## Cookbook logo
 
 `Logo` renders the Cookbook mark. Use `label` when it carries meaning or
@@ -149,12 +173,12 @@ markers remain visible independently of their theme-aware backgrounds:
 
 ## Component props
 
-| Component | Props and behavior                                                                                  |
-| --------- | --------------------------------------------------------------------------------------------------- |
-| `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 root `class`; renders the Cookbook mark                         |
-| `Preview` | Required `title`; optional `html`, `css`, and `javascript`; isolates examples in a sandboxed iframe |
+| Component | Props and behavior                                                                                                         |
+| --------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `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 root `class`; renders the Cookbook mark                                                |
+| `Preview` | Required `title`; optional `html`, `css`, `javascript`, and public-file `scripts`; isolates examples in a sandboxed iframe |
 
 The public package exports each component's props type, such as `TabProps`,
 `CalloutProps`, and `CodeGroupProps`. Styles and all named sub-elements are

package/docs/migration.md

@@ -230,8 +230,8 @@ Tasty-generated style hashes and library-owned Pagefind sub-element classes rema
 
 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.
+Pagination links keep their border at rest; hover changes only colors,
+preserving `theme.styles.Pagination.Link` border width and style.
 
 ## Smaller shared state set
 

package/docs/theme-and-components.md

@@ -382,6 +382,38 @@ Adopt Cookbook's Tasty validation preset and register your additional names.
 See [Linting custom styles](./custom-components.md#linting-custom-styles) for
 ESLint and oxlint examples.
 
+## Reader appearance
+
+The Appearance menu stores each reader's color scheme and contrast in one
+`localStorage` entry. Its key and format are a stable contract, so another app
+on the same origin can share the preference with the documentation. A typical
+example is a product site that serves Cookbook under `/docs/`.
+
+```ts
+// localStorage["cookbook-appearance"], stored as JSON
+type CookbookAppearance = {
+  theme?: "light" | "dark" | "system";
+  contrast?: "normal" | "more" | "system";
+};
+```
+
+A missing or unrecognized field means `"system"`, which follows the reader's
+operating system. Keep any other fields when you write the object:
+
+```ts
+const key = "cookbook-appearance";
+const appearance = JSON.parse(localStorage.getItem(key) ?? "{}") ?? {};
+
+localStorage.setItem(key, JSON.stringify({ ...appearance, theme: "dark" }));
+```
+
+Cookbook applies the stored choice before the first paint, as `data-theme` and
+`data-contrast` on `<html>`. Open pages follow changes made in other tabs through
+the `storage` event. Your app can map the same values onto its own attributes.
+
+Browsers keep `localStorage` per origin: the scheme, host, and port must all
+match, so a docs subdomain does not share the preference.
+
 ## Static behavior
 
 The page content remains readable without client JavaScript. Search, menus,

package/package.json

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