@cube-dev/ui-kit 0.175.1 → 0.176.0

package/docs/tasty/ssr.md

@@ -86,6 +86,92 @@ export default function RootLayout({
 
 That's it. All `tasty()` components inside the tree automatically get SSR support. No per-component changes needed.
 
+### Optional shared globals stylesheet
+
+By default, configured global CSS is included in the streamed Tasty style tag
+for every route. `withTastyNext()` can move that stable CSS into one
+content-hashed stylesheet shared by all routes while leaving component and hook
+styles in the normal streaming path.
+
+Keep the Tasty config in a side-effect-free module:
+
+```ts
+// app/tasty.config.ts
+import type { TastyConfig } from '@tenphi/tasty';
+
+const config: TastyConfig = {
+  tokens: { $gap: '8px', '#brand': 'rebeccapurple' },
+  globalStyles: { body: { margin: '0', color: '#brand' } },
+  fontFaces: {
+    Brand: { src: 'url("/fonts/brand.woff2") format("woff2")' },
+  },
+};
+
+export default config;
+```
+
+Use it from the Next config:
+
+```ts
+// next.config.ts
+import { withTastyNext } from '@tenphi/tasty/ssr/next-config';
+import config from './app/tasty.config';
+
+export default withTastyNext({
+  config,
+})({
+  // your Next.js config
+});
+```
+
+The runtime must receive the same config. Import and configure it before the
+registry renders:
+
+```tsx
+// app/tasty-registry.tsx
+'use client';
+
+import { configure } from '@tenphi/tasty';
+import { TastyRegistry } from '@tenphi/tasty/ssr/next';
+import config from './tasty.config';
+
+configure(config);
+
+export default function TastyStyleRegistry({ children }) {
+  return <TastyRegistry>{children}</TastyRegistry>;
+}
+```
+
+The generated file contains eager configuration artifacts: built-in and custom
+`@property` rules, tokens and presets, `@font-face`, `@counter-style`, native
+CSS `@function` definitions, and `globalStyles`. Route-dependent component
+rules and calls to `useGlobalStyles`, `useRawCSS`, `useKeyframes`,
+`useProperty`, `useFontFace`, `useCounterStyle`, and `useFunction` remain
+route-specific. Configured keyframes also remain lazy and are streamed only
+when a route references them.
+
+The default output directory is `public/_tasty`. The wrapper adds the generated
+URL to `TastyRegistry`, respects `basePath`, preserves existing `env` and
+`headers` config, and serves the content-hashed file with an immutable one-year
+cache header on Next server deployments. Static exports keep the content-hashed
+URL and leave cache headers to the hosting provider. Older hashes are not
+deleted automatically, so rolling deployments cannot break pages from the
+previous build; clean the generated directory as part of a clean deployment if
+needed. Page-relative CSS resources such as
+`url(../fonts/brand.woff2)` are rejected because moving them would change their
+meaning; use root-relative, absolute, or data URLs.
+
+`withTastyNext()` options:
+
+| Option       | Type          | Default                   | Description                                                            |
+| ------------ | ------------- | ------------------------- | ---------------------------------------------------------------------- |
+| `config`     | `TastyConfig` | —                         | Config object; takes precedence over `configFile`                      |
+| `configFile` | `string`      | —                         | Project-relative config module path; requires the optional `jiti` peer |
+| `rootDir`    | `string`      | current directory         | Next app root when the build runs from a monorepo root                 |
+| `outputDir`  | `string`      | `public/_tasty`           | Filesystem output directory                                            |
+| `publicPath` | `string`      | inferred from `outputDir` | Root-relative URL; required when output is outside `public`            |
+| `enabled`    | `boolean`     | `true`                    | Disable generation without changing wrapper composition                |
+
 ### How it works
 
 - `TastyRegistry` is a `'use client'` component, but Next.js still server-renders it on initial page load. The `'use client'` boundary is required solely to access `useServerInsertedHTML` — **not** because `tasty()` components need the client.
@@ -130,13 +216,13 @@ The nonce is automatically applied to all `<style>` and `<script>` tags injected
 
 Tasty offers several levels of Astro integration. Choose the one that matches your needs:
 
-| Setup                                                     | Config needed | Deduplication                 | Hooks work             | Client JS      |
-| --------------------------------------------------------- | ------------- | ----------------------------- | ---------------------- | -------------- |
-| Zero setup                                                | None          | Per render tree               | Yes (within each tree) | None           |
-| `tastyIntegration({ islands: false })`                    | One line      | Cross-tree                    | Yes                    | None           |
-| `tastyIntegration()`                                      | One line      | Cross-tree                    | Yes                    | Auto-hydration |
-| `tastyIntegration({ css: { mode: 'extract' } })`          | One line      | Cross-tree and cross-page     | Yes                    | Auto-hydration |
-| `tastyIntegration({ islands: false, css: { mode: 'extract' } })` | One line | Cross-tree and cross-page | Yes                    | None           |
+| Setup                                                            | Config needed | Deduplication             | Hooks work             | Client JS      |
+| ---------------------------------------------------------------- | ------------- | ------------------------- | ---------------------- | -------------- |
+| Zero setup                                                       | None          | Per render tree           | Yes (within each tree) | None           |
+| `tastyIntegration({ islands: false })`                           | One line      | Cross-tree                | Yes                    | None           |
+| `tastyIntegration()`                                             | One line      | Cross-tree                | Yes                    | Auto-hydration |
+| `tastyIntegration({ css: { mode: 'extract' } })`                 | One line      | Cross-tree and cross-page | Yes                    | Auto-hydration |
+| `tastyIntegration({ islands: false, css: { mode: 'extract' } })` | One line      | Cross-tree and cross-page | Yes                    | None           |
 
 ### Zero setup (static pages)
 
@@ -235,8 +321,8 @@ This gives the same middleware deduplication and hook support, but ships zero cl
 
 #### Build-wide CSS extraction
 
-Static Astro builds can move repeated Tasty CSS into a content-hashed,
-browser-cacheable asset:
+Static Astro builds can move Tasty CSS into content-hashed, browser-cacheable
+shared and page assets:
 
 ```ts
 export default defineConfig({
@@ -257,14 +343,38 @@ output. Extraction requires Astro 5 or newer and only applies to prerendered
 production pages. Development, preview-time SSR, and on-demand routes continue
 to receive the normal inline `<style data-tasty-ssr>` output.
 
-Extraction moves the largest common block whose position can be preserved on
-every generated page into one stylesheet. Page-only component, global, and raw
-CSS stays inline, so unvisited routes do not receive unrelated styles.
-
-The asset is written under Astro's configured `build.assets` directory (for
-example, `/_astro/tasty.a1b2c3.css`). Links include the configured Astro
-`base`, so nested routes do not need relative-path handling. The content hash
-and output are deterministic for identical builds.
+Extraction writes every artifact emitted by all styled pages to a shared
+stylesheet. Each page's strict set difference is written to a separate page
+stylesheet. The shared link comes first and the page link follows, so shared
+styles form the base cascade and page-only styles can override them. A fully
+shared page omits the empty page stylesheet. If generated pages have no common
+artifacts, each page receives only its page stylesheet.
+
+The shared-base/page-override order is the extraction-mode cascade contract.
+It does not preserve an inline artifact order where a page-only rule originally
+appeared before a shared rule. Use shared styles for defaults and page-only
+styles for overrides.
+
+Extracted CSS preserves resource URLs verbatim. Relative URLs in an inline
+style resolve from the page, but in an extracted stylesheet they resolve from
+the asset directory. Use absolute URLs or data URLs when extraction is enabled.
+Root-relative URLs such as `url(/fonts/brand.woff2)` are also safe while the
+stylesheet stays on the page's origin. The build fails with a clear error if an
+artifact contains a page-relative or fragment-only URL, including URL strings
+in `image-set()`, `image()`, `src()`, and `@import`.
+
+Assets are written under Astro's configured `build.assets` directory (for
+example, `/_astro/tasty.shared.a1b2c3.css` and
+`/_astro/tasty.page.d4e5f6.css`). Links include the configured Astro `base`, so
+nested routes do not need relative-path handling. Content hashes and output are
+deterministic for identical builds. If `build.assetsPrefix` is configured,
+Tasty uses its CSS-specific prefix (or `fallback`) just like Astro-generated
+stylesheets. When that prefix points to a different origin, root-relative
+resources would resolve against the asset origin rather than the page's origin,
+so the build rejects them as well. Tasty compares the prefix with Astro's `site`
+when it is configured; without `site`, an absolute or protocol-relative prefix
+is treated conservatively as cross-origin. Use a fully absolute resource URL in
+that configuration.
 
 ### Manual middleware (advanced)
 
@@ -300,12 +410,13 @@ Astro's `@astrojs/react` renderer calls `renderToString()` for each React compon
 - The middleware reads the full response body, then injects the collected CSS into `</head>` before sending the final HTML.
 - In extraction mode, prerendered responses also carry temporary structured
   artifact metadata. `astro:build:done` uses those collector-provided
-  boundaries to write the shared asset and rewrite generated HTML, then removes
-  the metadata. CSS is never split on newlines or parsed heuristically.
+  boundaries to write shared and page assets and rewrite generated HTML, then
+  removes the metadata. Artifact boundaries are never inferred by splitting or
+  reparsing the generated CSS.
 
 ### CSP nonce
 
-Call `configure({ nonce: '...' })` before any rendering happens. The middleware reads the nonce and applies it to injected `<style>` and `<script>` tags. In extraction mode, page-local inline style tags and the external stylesheet link retain the nonce.
+Call `configure({ nonce: '...' })` before any rendering happens. The middleware reads the nonce and applies it to injected `<style>` and `<script>` tags. In extraction mode, the external stylesheet links retain the nonce.
 
 ---
 
@@ -388,12 +499,13 @@ const stream = await runWithCollector(collector, () =>
 
 ### Entry points
 
-| Import path                                                                         | Description                                                                                                                                                                                                     |
-| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@tenphi/tasty/ssr`                                                                 | Core SSR API: `ServerStyleCollector`, `createServerStyleCollector`, `runWithCollector`, `hydrateTastyClasses`                                                                                                   |
-| `@tenphi/tasty/ssr/next`                                                            | Next.js App Router: `TastyRegistry` component                                                                                                                                                                   |
-| `@tenphi/tasty/ssr/astro`                                                           | Astro: `tastyIntegration`, `tastyMiddleware`                                                                                                                                                                    |
-| `@tenphi/tasty/ssr/astro-client`                                                    | Astro: client-side cache hydration (auto-injected by integration, or import manually)                                                                                                                           |
+| Import path                                                                                                                                                                                | Description                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@tenphi/tasty/ssr`                                                                                                                                                                        | Core SSR API: `ServerStyleCollector`, `createServerStyleCollector`, `runWithCollector`, `hydrateTastyClasses`                                                                                                   |
+| `@tenphi/tasty/ssr/next`                                                                                                                                                                   | Next.js App Router: `TastyRegistry` component                                                                                                                                                                   |
+| `@tenphi/tasty/ssr/next-config`                                                                                                                                                            | Next.js config wrapper: shared, content-hashed global stylesheet                                                                                                                                                |
+| `@tenphi/tasty/ssr/astro`                                                                                                                                                                  | Astro: `tastyIntegration`, `tastyMiddleware`                                                                                                                                                                    |
+| `@tenphi/tasty/ssr/astro-client`                                                                                                                                                           | Astro: client-side cache hydration (auto-injected by integration, or import manually)                                                                                                                           |
 | `@tenphi/tasty/ssr/astro-middleware`<br>`@tenphi/tasty/ssr/astro-middleware-static`<br>`@tenphi/tasty/ssr/astro-middleware-extract`<br>`@tenphi/tasty/ssr/astro-middleware-extract-static` | Astro: the middleware entrypoints `tastyIntegration()` registers via `addMiddleware()`. Exported so Astro can resolve them by specifier; you should not import them. For manual setups use `tastyMiddleware()`. |
 
 ### `ServerStyleCollector`
@@ -414,7 +526,7 @@ Constructor: `new ServerStyleCollector(namePrefix?)`, or use the `createServerSt
 | `allocateCounterStyleName(providedName?)`  | Allocate a counter-style name. Returns `providedName` if given, otherwise generates one using `${namePrefix}c${counter}` (e.g. `tc0`, `tc1`, ...).                                                                                                                         |
 | `collectGlobalStyles(key, css)`            | Record global styles (from `useGlobalStyles`). Deduplicated by key.                                                                                                                                                                                                        |
 | `collectRawCSS(key, css)`                  | Record raw CSS text (from `useRawCSS`). Deduplicated by key.                                                                                                                                                                                                               |
-| `collectInternals()`                       | Collect internal `@property` rules, `:root` token defaults, `@font-face`, and `@counter-style` rules from the global config. Called automatically on first chunk collection; idempotent.                                                                                   |
+| `collectInternals()`                       | Collect eager configured globals: `@property`, `:root` tokens and presets, `@font-face`, `@counter-style`, `@function`, and `globalStyles`. Called automatically on first chunk collection; idempotent.                                                                    |
 | `getCSS()`                                 | Get all collected CSS as a single string. For non-streaming SSR.                                                                                                                                                                                                           |
 | `flushCSS()`                               | Get only CSS collected since the last flush. For streaming SSR.                                                                                                                                                                                                            |
 | `getRenderedClassNames()`                  | Get the list of class names rendered so far. Serialized to `window.__TASTY__` for client hydration via `hydrateTastyClasses()`.                                                                                                                                            |
@@ -423,10 +535,18 @@ Constructor: `new ServerStyleCollector(namePrefix?)`, or use the `createServerSt
 
 Next.js App Router component. Props:
 
-| Prop            | Type        | Default  | Description                                      |
-| --------------- | ----------- | -------- | ------------------------------------------------ |
-| `children`      | `ReactNode` | required | Application tree                                 |
-| `transferCache` | `boolean`   | `true`   | Embed cache state script for zero-cost hydration |
+| Prop               | Type              | Default   | Description                                                               |
+| ------------------ | ----------------- | --------- | ------------------------------------------------------------------------- |
+| `children`         | `ReactNode`       | required  | Application tree                                                          |
+| `transferCache`    | `boolean`         | `true`    | Embed cache state script for zero-cost hydration                          |
+| `sharedStylesheet` | `string \| false` | generated | Override the shared URL, or disable generated shared CSS for the registry |
+
+### `withTastyNext(options)`
+
+Next.js configuration wrapper exported from
+`@tenphi/tasty/ssr/next-config`. It generates a shared stylesheet from eager
+Tasty configuration artifacts and wires its URL and immutable cache header
+into the Next config. Route-specific CSS continues through `TastyRegistry`.
 
 ### `tastyIntegration(options?)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.175.1",
+  "version": "0.176.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -59,7 +59,7 @@
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
     "@tenphi/glaze": "2.0.0",
-    "@tenphi/tasty": "^3.5.0",
+    "@tenphi/tasty": "^3.7.0",
     "clipboard-copy": "^4.0.1",
     "clsx": "^1.1.1",
     "diff": "^8.0.3",