@tenphi/cookbook 0.28.0 → 0.30.0

package/docs/upstream/tasty/docs/tasty-static.md

@@ -8,30 +8,38 @@ Choose `tastyStatic` specifically when styles must be generated during the build
 
 ## When to Use
 
-- **Static site generation (SSG)** — Pre-render all styles at build time
-- **No-JavaScript websites** — CSS works without any JS runtime
-- **Performance-critical pages** — CSS extracted before the application renders
-- **Landing pages** — Minimal bundle size with pre-generated CSS
+- **CSS that must exist before anything renders** — static sites, landing pages, and HTML served from a CDN get one stylesheet generated at build time
+- **No React at runtime** — `tastyStatic` returns class names, so plain DOM code or any templating that sets `class` can use them; the [Programmatic API](#programmatic-api) covers frameworks Babel does not process
+- **Class-name objects instead of components** — extend them with `tastyStatic(base, styles)` and pass them wherever a `className` goes
+- **Self-contained packages** — [inject mode](#inject-mode) embeds the CSS in the JavaScript, so consumers have no stylesheet to wire up
+
+If the styles depend on props, keep `tasty()`: rendered only on the server, it also ships no styling runtime (see [Server-Side Rendering](ssr.md)).
 
 ## Requirements
 
 Build-time extraction is part of the main `@tenphi/tasty` package but requires additional peer dependencies depending on your setup:
 
-| Dependency                   | Version | Required for                                                               |
-| ---------------------------- | ------- | -------------------------------------------------------------------------- |
-| `@babel/core`                | >= 7.24 | Babel plugin (`@tenphi/tasty/babel-plugin`)                                |
-| `@babel/helper-plugin-utils` | >= 7.24 | Babel plugin                                                               |
-| `@babel/types`               | >= 7.24 | Babel plugin                                                               |
-| `jiti`                       | >= 2.6  | Next.js wrapper (`@tenphi/tasty/zero/next`) when using `configFile` option |
+| Dependency                   | Version                | Required for                                         |
+| ---------------------------- | ---------------------- | ---------------------------------------------------- |
+| `@babel/core`                | 7.24+ or 8             | Babel plugin (`@tenphi/tasty/babel-plugin`)          |
+| `@babel/helper-plugin-utils` | 7.24+ or 8             | Babel plugin                                         |
+| `@babel/types`               | 7.24+ or 8             | Babel plugin                                         |
+| `jiti`                       | >= 2.6                 | `configFile` only (Babel plugin and Next.js wrapper) |
+| `babel-loader`               | any (10+ with Babel 8) | Next.js wrapper (`@tenphi/tasty/zero/next`)          |
+
+Install the three Babel packages from the same major. Babel 8 itself needs Node 22.18+ or 24.11+, and `babel-loader` accepts it from version 10.
 
-All of these are declared as optional peer dependencies of `@tenphi/tasty`. Install only what your setup requires:
+The Babel packages and `jiti` are optional peer dependencies of `@tenphi/tasty`; `babel-loader` is resolved from your project. `jiti` is loaded only to read a `configFile`, so a setup that passes `config` directly does not need it; without it, `configFile` fails with an error that says to install it. Install what your setup requires:
 
 ```bash
-# For any Babel-based setup (Vite, custom Babel config, etc.)
+# Any Babel-based setup (Vite, custom Babel config, etc.)
 pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types
 
-# For Next.js with TypeScript config file
-pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types jiti
+# Next.js
+pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types babel-loader
+
+# Either, with configFile
+pnpm add -D jiti
 ```
 
 ---
@@ -52,13 +60,15 @@ const button = tastyStatic({
   radius: '1r',
 });
 
-// Use in JSX - works via toString() coercion
-<button className={button}>Click me</button>
+// Use in JSX
+<button className={button.className}>Click me</button>;
 
-// Or access className explicitly
-<button className={button.className}>Click me</button>
+// toString() returns the class name, for template strings and plain JS
+element.className = `${button} is-active`;
 ```
 
+In TSX, pass `button.className`: React types `className` as `string`, so passing the `StaticStyle` object fails type-checking even though it works at runtime.
+
 ---
 
 ## API Reference
@@ -105,6 +115,8 @@ tastyStatic('body', {
 });
 ```
 
+The selector can be a list (`'.uni-checkbox, uni-checkbox'`): every item gets the states and sub-elements. Local `@keyframes` and `@starting` states work as in `tastyStatic(styles)`.
+
 ---
 
 ## StaticStyle Object
@@ -166,7 +178,7 @@ module.exports = {
 | -------------------------- | ------------------------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `output`                   | `string`                                         | `'tasty.css'` | Path for generated CSS file                                                                                                                                                                      |
 | `mode`                     | `'file' \| 'inject'`                             | `'file'`      | `'file'` writes CSS to disk; `'inject'` embeds CSS inline in JS (see [Inject Mode](#inject-mode))                                                                                                |
-| `configFile`               | `string`                                         | —             | Absolute path to a TS/JS module that default-exports a `TastyZeroConfig` object. JSON-serializable alternative to `config` — required for Turbopack.                                             |
+| `configFile`               | `string`                                         | —             | Absolute path to a TS/JS module that default-exports a `TastyZeroConfig` object. JSON-serializable alternative to `config` — required for Turbopack. Loaded with the optional `jiti` peer.       |
 | `config`                   | `TastyZeroConfig \| () => TastyZeroConfig`       | `{}`          | Inline config object or factory function. Takes precedence over `configFile`.                                                                                                                    |
 | `configDeps`               | `string[]`                                       | `[]`          | Absolute file paths that affect config (for cache invalidation)                                                                                                                                  |
 | `injectImport`             | `boolean`                                        | `true`        | Replace `@tenphi/tasty/static` imports with an import of the generated CSS file. Set to `false` to manage CSS imports manually.                                                                  |
@@ -178,7 +190,8 @@ module.exports = {
 | `config.keyframes`         | `Record<string, KeyframesSteps>`                 | —             | Global `@keyframes` definitions available to all `tastyStatic` calls                                                                                                                             |
 | `config.fontFaces`         | `Record<string, FontFaceInput>`                  | —             | Global `@font-face` definitions                                                                                                                                                                  |
 | `config.counterStyles`     | `Record<string, CounterStyleDescriptors>`        | —             | Global `@counter-style` definitions                                                                                                                                                              |
-| `config.units`             | `Record<string, string \| UnitHandler>`          | —             | Custom units for the style parser (merged with built-ins). E.g. `{ em: 'em', vw: 'vw' }`                                                                                                         |
+| `config.properties`        | `Record<string, PropertyDefinition>`             | —             | Global `@property` definitions, written with Tasty's [default properties](dsl.md#default-properties)                                                                                             |
+| `config.units`             | `Record<string, string \| UnitHandler>`          | —             | Custom units for the style parser (merged with built-ins). E.g. `{ u: 'var(--u)' }` makes `2u` compile to `calc(2 * var(--u))`. Native CSS units need no entry                                   |
 | `config.functions`         | `Record<string, FunctionDefinition \| Function>` | —             | Custom functions (merged). Bare keys → parse functions; `$$name` keys → declarative CSS `@function` definitions                                                                                  |
 | `config.polyfills`         | `{ functions?: boolean }`                        | `{}`          | Opt-in polyfills. `functions: true` inlines `@function` calls into plain CSS at build time                                                                                                       |
 | `config.plugins`           | `TastyPlugin[]`                                  | —             | Plugins that extend tasty with custom functions, units, states, and handlers                                                                                                                     |
@@ -242,7 +255,7 @@ const card = tastyStatic({
   color: '#text',
 });
 
-<div className={card}>Styled card</div>;
+<div className={card.className}>Styled card</div>;
 ```
 
 ---
@@ -279,12 +292,12 @@ export default withTastyZero({
 
 Starting with Next.js 16, Turbopack is the default bundler. `withTastyZero` supports it out of the box by injecting `turbopack.rules` with `babel-loader` and JSON-serializable options.
 
-The `configFile` option is key for Turbopack — it passes a file path (JSON-serializable) instead of a function, and the Babel plugin loads the config internally via jiti.
+The `configFile` option is key for Turbopack — it passes a file path (JSON-serializable) instead of a function, and the Babel plugin loads the config internally via `jiti`, which must be installed.
 
-**Requirements**: `babel-loader` must be installed in your project:
+**Requirements**: `babel-loader` must be installed in your project (see [Requirements](#requirements)):
 
 ```bash
-pnpm add babel-loader
+pnpm add -D babel-loader
 ```
 
 ### CSS Injection
@@ -299,34 +312,107 @@ public/tasty.css
 
 ---
 
+## Programmatic API
+
+`@tenphi/tasty/zero` turns styles into CSS in Node without Babel or React — for build scripts, or CSS shipped to other frameworks:
+
+```ts
+import {
+  configure,
+  extractStylesForSelector,
+  extractStylesWithChunks,
+} from '@tenphi/tasty/zero';
+
+configure({
+  units: { u: 'var(--unit)' },
+  states: { '@dark': '@root(schema=dark)' },
+});
+
+extractStylesForSelector('.card', { padding: '2u', fill: '#surface' }).css;
+// → '.card { padding: calc(2 * var(--unit)); background-color: … }'
+
+extractStylesWithChunks({ display: 'flex', gap: '1u' });
+// → [{ className: 'ts…', css: '.ts….ts… { … }' }]
+```
+
+`configure()` takes the same options as the Babel plugin's `config` (see [Plugin Options](#plugin-options)) and replaces the previous configuration on each call; `resetConfig()` returns to the defaults. Options that shape the extracted rules apply — `states`, `units`, parse `functions`, `handlers`, `replaceTokens`, `recipes`, `plugins`, `namePrefix`. Definitions that become at-rules or global CSS of their own are not emitted with the rules: `tokens`, `globalStyles`, `fontFaces`, `counterStyles`, `properties` and `$$` `@function` definitions. Render tokens and global styles with `extractStylesForSelector(':root', tokens)` and `extractStylesForSelector(selector, styles)`.
+
+`extractConfigProperties()` returns the `@property` rules the Babel plugin writes at the top of its output: Tasty's [default set](dsl.md#default-properties) (`#border`, `#outline`, `$gap`, `$radius`, `$transition`, …) overlaid with the configured `properties`, or with the `properties` map you pass it. Emit them once per stylesheet. Style handlers read several of these tokens with no fallback of their own (`border: true` reads `#border`, `transition` reads `$transition`), so without them those declarations resolve to nothing.
+
+The configuration is process-wide and shared with the Babel plugin and the runtime `configure()` from `@tenphi/tasty`. The extractors re-apply their own configuration when the Babel plugin replaced it, but not after a runtime `configure()` — don't mix the runtime and build-time configuration in one process.
+
+`extractStylesForSelector()` output starts with the `@keyframes` its rules animate — local `@keyframes` and configured `keyframes` — under hashed names the `animation` declarations are rewritten to. `extractStylesWithChunks()` returns class rules only.
+
+`mergeStyles()` merges style objects with the rules `tasty(Base, { styles })` extends by — state maps with and without a `''` key, `null`, `false`, `'@inherit'` and sub-elements (see [Extending vs. Replacing State Maps](dsl.md#extending-vs-replacing-state-maps)) — so a build script can layer overrides onto source styles before extracting them, without React:
+
+```ts
+import { extractStylesForSelector, mergeStyles } from '@tenphi/tasty/zero';
+
+const styles = mergeStyles(checkboxStyles, {
+  Indicator: { radius: '0.5r' },
+});
+
+extractStylesForSelector('.checkbox', styles).css;
+```
+
+To write the results to a file the way the Babel plugin does, use `createCSSWriter()`. It deduplicates blocks by key and prepends the generated-file header:
+
+```ts
+import {
+  createCSSWriter,
+  extractConfigProperties,
+  extractStylesWithChunks,
+} from '@tenphi/tasty/zero';
+
+const writer = createCSSWriter('dist/tasty.css', { devMode: true });
+
+for (const prop of extractConfigProperties()) {
+  writer.add(`@property:${prop.name}`, prop.css);
+}
+
+for (const chunk of extractStylesWithChunks({ display: 'flex', gap: '1u' })) {
+  writer.add(chunk.className, chunk.css, 'src/card.ts'); // source is a devMode comment
+}
+
+writer.write(); // also: has(key), getCSS(), clear(), getOutputPath()
+```
+
+---
+
 ## Vite Integration
 
+`@vitejs/plugin-react` 6 no longer runs Babel; add it with `@rolldown/plugin-babel` (`pnpm add -D @rolldown/plugin-babel`):
+
 ```typescript
 // vite.config.ts
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
+import babel from '@rolldown/plugin-babel';
 
 export default defineConfig({
   plugins: [
-    react({
-      babel: {
-        plugins: [
-          [
-            '@tenphi/tasty/babel-plugin',
-            {
-              output: 'public/tasty.css',
-              config: {
-                states: { '@mobile': '@media(w < 768px)' },
-              },
+    react(),
+    babel({
+      plugins: [
+        [
+          '@tenphi/tasty/babel-plugin',
+          {
+            output: 'src/tasty.css',
+            config: {
+              states: { '@mobile': '@media(w < 768px)' },
             },
-          ],
+          },
         ],
-      },
+      ],
     }),
   ],
 });
 ```
 
+With `@vitejs/plugin-react` 5 or older, pass the same `plugins` array to `react({ babel: { plugins } })` instead.
+
+Keep `output` outside `public/`: the plugin replaces each `@tenphi/tasty/static` import with an import of the generated file, and Vite does not let JavaScript import files from `public/`. Vite then bundles the CSS like any other stylesheet.
+
 ---
 
 ## Build Transformation
@@ -344,44 +430,67 @@ const button = tastyStatic({
 
 tastyStatic('.heading', { preset: 'h1' });
 
-export const Button = () => <button className={button}>Click</button>;
+export const Button = () => <button className={button.className}>Click</button>;
 ```
 
 ### After (Production Build)
 
 ```tsx
+import './tasty.css';
+
 const button = {
-  className: 'ts3f2a1b ts8c4d2e',
+  className: 'ts3f783b ts070801',
   styles: { padding: '2x 4x', fill: '#purple', color: '#white' },
   toString() {
     return this.className;
   },
 };
 
-export const Button = () => <button className={button}>Click</button>;
+export const Button = () => <button className={button.className}>Click</button>;
 ```
 
+The `@tenphi/tasty/static` import becomes an import of the generated file (relative to the source file), and the selector-mode call is removed.
+
 ### Generated CSS (tasty.css)
 
 ```css
 /* Generated by @tenphi/tasty/zero - DO NOT EDIT */
 
-.ts3f2a1b.ts3f2a1b {
-  padding: 16px 32px;
+@property --tasty-second-fill-color {
+  syntax: '<color>';
+  inherits: false;
+  initial-value: transparent;
 }
 
-.ts8c4d2e.ts8c4d2e {
-  background: #9370db;
-  color: #fff;
+@property --current-color {
+  syntax: '<color>';
+  inherits: true;
+  initial-value: currentcolor;
 }
 
-.heading.heading {
-  font-size: 2.5rem;
-  font-weight: 700;
-  line-height: 1.2;
+/* …the rest of Tasty's default @property rules (--white-color, --border-color, --gap, --transition, …), then config.properties */
+
+.ts3f783b.ts3f783b {
+  color: var(--white-color);
+  --current-color: var(--white-color);
+}
+
+.ts3f783b.ts3f783b {
+  background-color: var(--purple-color);
+}
+
+.ts070801.ts070801 {
+  padding: 16px 32px;
+}
+
+.heading {
+  font-size: var(--h1-font-size, var(--default-font-size));
+  /* …line-height, letter-spacing, font-weight, and the rest of the h1 preset */
 }
 ```
 
+The file starts with Tasty's [default `@property` rules](dsl.md#default-properties) and your `config.properties`, written once. Styles are split into chunks (here appearance and spacing), each with its own class. Color tokens compile to custom properties: `#purple` becomes `var(--purple-color)`. Define it in `config.tokens` and the plugin writes it to `:root` at the top of the same file. Units are literal (`2x` is `16px`). Selector-mode rules use the selector as written, without the doubled specificity of class rules.
+
 ---
 
 ## Inject Mode
@@ -452,22 +561,29 @@ tastyStatic('.heading', { preset: 'h1' });
 ```tsx
 import { injectCSS as _$i } from '@tenphi/tasty/static/inject';
 
+_$i(
+  '@property',
+  '@property --tasty-second-fill-color { … }\n@property --current-color { … }\n…',
+);
+
 const button =
   (_$i(
-    'ts3f2a1b ts8c4d2e',
-    '.ts3f2a1b.ts3f2a1b{padding:16px 32px}\n.ts8c4d2e.ts8c4d2e{background:#9370db}',
+    'tsa903d6 ts070801',
+    '.tsa903d6.tsa903d6 { background-color: var(--purple-color); }\n.ts070801.ts070801 { padding: 16px 32px; }',
   ),
   {
-    className: 'ts3f2a1b ts8c4d2e',
+    className: 'tsa903d6 ts070801',
     styles: { padding: '2x 4x', fill: '#purple' },
     toString() {
       return this.className;
     },
   });
 
-_$i('.heading', '.heading{font-size:2.5rem;font-weight:700;line-height:1.2}');
+_$i('.heading', '.heading { font-size: var(--h1-font-size, …); … }');
 ```
 
+Each file that calls `tastyStatic()` starts by injecting Tasty's default `@property` rules and your `config.properties` under the `@property` id. `injectCSS()` skips an id it has already injected, so the page gets them once.
+
 ### Dev Mode / HMR
 
 Class names are content-hashed (`ts` + MD5). When styles change, a new hash produces a new `_$i` call that injects fresh CSS. The injector deduplicates by id, so unchanged styles are skipped. Old CSS stays in the DOM but is harmless since no elements reference those class names.
@@ -525,7 +641,7 @@ const card = tastyStatic({
 
 ## Extending Style Types (TypeScript)
 
-If you add custom style properties, use module augmentation so `tastyStatic` recognizes them too. See [Extending Style Types](configuration.md#extending-style-types-typescript) in the configuration docs.
+If you add custom style properties, use module augmentation so `tastyStatic` recognizes them too. See [TypeScript](configuration.md#typescript) in the configuration docs.
 
 ---
 
@@ -547,10 +663,12 @@ const card = tastyStatic({
 });
 
 <div
-  className={card}
-  style={{
-    '--card-bg': isActive ? 'var(--purple-color)' : 'var(--white-color)',
-  }}
+  className={card.className}
+  style={
+    {
+      '--card-bg': isActive ? 'var(--purple-color)' : 'var(--white-color)',
+    } as React.CSSProperties
+  }
 />;
 ```
 

package/docs/zh/getting-started.md

@@ -63,8 +63,6 @@ Cookbook 自带 Astro 渲染器，并会自动查找 `docs.config.ts`。如果
 
 ## 配置站点
 
-可以先查看完整的[品牌、标志和字体示例](../recipes.md)。若要深入调整样式或添加组件，请阅读[自定义规则](../customization-rules.md)。这些规则和上游参考资料也包含在安装后的 Cookbook 包中。
-
 在 `astro.config.ts` 旁创建 `docs.config.ts`：
 
 ```ts
@@ -83,9 +81,11 @@ export default defineDocsConfig({
 });
 ```
 
-修改 `theme.fonts` 可使用[按名称指定的 Google Fonts 或你自己的字体文件](../fonts-and-typography.md)。使用 `theme.presets` 调整排版细节，使用 `theme.styles` 调整内置元素，并结合 `defineComponent()` 与 `theme.customStyles` 添加新元素。[主题指南](../theme-and-components.md)介绍了起点；[组件样式参考](../component-styles.md)列出了全部可自定义部分。
+修改 `theme.fonts` 可使用[按名称指定的 Google Fonts 或你自己的字体文件](../fonts-and-typography.md#change-font-families)。使用 `theme.presets` 调整排版细节，使用 `theme.styles` 调整内置元素，并结合 `defineComponent()` 与 `theme.customStyles` 添加新元素。[主题指南](../theme-and-components.md)介绍了起点；[组件样式参考](../component-styles.md)列出了全部可自定义部分。
+
+完整的起点可参考[品牌、标志和字体示例](../recipes.md)。若要深入调整样式或添加组件，请阅读[自定义规则](../customization-rules.md)。这些规则和上游参考资料也包含在安装后的 Cookbook 包中。
 
-集成和 CLI 读取同一份配置。支持的文件名依优先顺序为 `docs.config.ts`、`.mts`、`.js` 和 `.mjs`。在集成中显式传入的 `config` 对象优先；`configFile: false` 会关闭自动查找。若配置文件位于其他位置，可使用 `cookbook({ configFile: "./config/manual.ts" })` 和 `cookbook doctor --config ./config/manual.ts`。
+集成和 CLI 读取同一份配置。支持的文件名依优先顺序为 `docs.config.ts`、`.mts`、`.js` 和 `.mjs`。在集成中显式传入的 `config` 对象优先；`configFile: false` 会关闭自动查找。若配置文件位于其他位置，可使用 `cookbook({ configFile: "./config/manual.ts" })` 和 `cookbook doctor --config ./config/manual.ts`。由于 `root` 相对于配置文件所在目录解析，该文件需要设置 `root: ".."`，才能继续从应用目录读取 `README.md` 和 `docs/`。
 
 ## 单体仓库的根目录
 
@@ -106,4 +106,6 @@ npm run validate
 npm run preview
 ```
 
-其他指南目前仍以英文提供，包括[示例](../examples.md)、[内容编写组件](../authoring.mdx)、[AI 智能体工作流程](../ai-agents.md)、[部署](../deployment.md)和[按版本升级指南](../migration.md)。如需可修改的完整配置，可从[示例配置](../recipes.md)开始。如果验证失败，请查看[故障排查](../troubleshooting.md)。
+`validate` 会对项目进行类型检查、运行 Cookbook 预检、构建站点并检查输出。对于自行配置的项目，请添加 [CLI 命令](../cli.md)中列出的脚本，或运行 `npx @tenphi/cookbook doctor`。
+
+其他指南目前仍以英文提供，包括[示例](../examples.md)、[内容编写组件](../authoring.mdx)、[AI 智能体工作流程](../ai-agents.md)、[部署](../deployment.md)和[按版本升级指南](../migration.md)。如果验证失败，请查看[故障排查](../troubleshooting.md)。

package/docs/zh/index.md

@@ -42,7 +42,7 @@ cd docs-site
 npm run dev
 ```
 
-Cookbook 会直接读取原位置的文件。你也可以[创建新站点](./getting-started.md)、[为实际发布到 npm 的文件编写文档](./getting-started.md)，或[将 Cookbook 加入现有 Astro 项目](./getting-started.md)。
+Cookbook 会直接读取原位置的文件。你也可以[创建新站点](./getting-started.md#创建第一个站点)、[为实际发布到 npm 的文件编写文档](./getting-started.md#为已发布的-npm-包编写文档)，或[将 Cookbook 加入现有 Astro 项目](./getting-started.md#加入现有-astro-项目)。
 
 ## 本站就是一个示例
 

package/package.json

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