@eocrm/design-system 0.6.23 → 0.7.0

package/AI-PRIMER.md

@@ -24,7 +24,7 @@ Accent: blue by default; `<html data-accent="…">` switches to `tealpine`, `ind
 
 ## Localization (i18n)
 
-Every user-facing string the library renders flows through `I18nProvider` (`'en'` default, `'ru'`); pair it with `LocaleProvider` for `Intl` dates. There are NO `labels` / `cancelLabel` / `searchPlaceholder` props on any component. Overrides, adding a string, drag-and-drop announcements: see [docs/i18n.md](docs/i18n.md).
+Every user-facing string the library renders flows through `I18nProvider` (English built in; other locales via `messages`, e.g. `<I18nProvider locale="ru" messages={ru}>`); pair it with `LocaleProvider` for `Intl` dates. There are NO `labels` / `cancelLabel` / `searchPlaceholder` props on any component. Overrides, adding a string, drag-and-drop announcements: see [docs/i18n.md](docs/i18n.md).
 
 ---
 
@@ -89,6 +89,7 @@ Each `<Name>` below is documented in `docs/components/<Name>.md`.
 - `StatTile` — one KPI tile (label, value, trend, footnote, icon, sparkline, quota `progress`) inside a StatGroup (`filled` or `card` surface)
 - `Sparkline` — compact static line / area / bar trend for KPI cards (StatTile slot, kpi DashboardWidget child); no axes, summary in the accessible name
 - `Chart` — line / bar / stacked bar / area time-series chart for a chart DashboardWidget (smoothed lines, static markers, legend, tooltip, keyboard, data table, empty state)
+- `FunnelChart` — stage funnel for pipeline / campaign conversion: height = drop-off, pill = step conversion, one-hue ramp with a hero first stage; optional stage click drill-through, vertical slices plus a table when narrow
 - `TreeView` — lazily loaded hierarchy (WAI-ARIA tree) as a file-explorer list or a top-down org chart, with loading / error-retry / load-more rows
 - `LiquidEditor` — Liquid template editor
 - `RichTextEditor` — controlled rich-text editor (contentEditable)

package/README.md

@@ -1,10 +1,10 @@
 # @eocrm/design-system
 
-React 19 design system for the EOCRM. Source-distributed (consumers' bundlers process `.tsx` and `.module.scss` directly — no compile step in this package).
+React 19 design system for the EOCRM. Ships compiled ESM (`dist/`: JavaScript, `.d.ts` types and plain CSS) — no Sass, TypeScript or transpile configuration needed in the consumer.
 
-Its web tokens are generated and versioned by `@eocrm/design-tokens`. Existing
-consumer imports remain unchanged: the design-system Sass entry points forward
-to the token package.
+Its web tokens are generated and versioned by `@eocrm/design-tokens`; the
+compiled token CSS is bundled into this package, so consumers install only
+`@eocrm/design-system`.
 
 Component contracts live in **[`docs/components/<Name>.md`](./docs/components)** (props table, anti-patterns). AI agents consuming this package should read **[AI-PRIMER.md](./AI-PRIMER.md)** first, ideally through the MCP server (see [AI agents](#ai-agents)).
 
@@ -16,10 +16,8 @@ Component contracts live in **[`docs/components/<Name>.md`](./docs/components)**
 
 ### 1. Registry
 
-`@eocrm/design-system` and `@eocrm/design-tokens` are public on npmjs, so no
-`.npmrc` or token is needed. If your `.npmrc` still maps `@eocrm` to another
-registry, remove that line — the design system pins `@eocrm/design-tokens` to its
-exact version, and both resolve from npmjs.
+`@eocrm/design-system` is public on npmjs, so no `.npmrc` or token is needed.
+If your `.npmrc` still maps `@eocrm` to another registry, remove that line.
 
 ### 2. Install
 
@@ -31,7 +29,7 @@ npm install @eocrm/design-system
 
 ```ts
 // Once, at the app's root (e.g. main.tsx):
-import '@eocrm/design-system/styles/global.scss';
+import '@eocrm/design-system/styles/global.css';
 
 // Anywhere:
 import {
@@ -49,15 +47,15 @@ import {
 
 ---
 
-## What `global.scss` does
+## What `global.css` does
 
-Importing `@eocrm/design-system/styles/global.scss` once at your app root applies three things:
+Importing `@eocrm/design-system/styles/global.css` once at your app root applies three things:
 
 1. **Tokens** — defines every `--color-*`, `--space-*`, `--radius-*`, `--font-*`, `--shadow-*` etc. on `:root`. Required.
 2. **Modern reset** — including `* { margin: 0 }`. **All default browser margins on every element are zeroed.** Headings, paragraphs, lists have no intrinsic vertical rhythm; space them via `Stack`/`Cluster` or with the parent's own margin in CSS. The document background uses `--document-background` (default `var(--color-bg-subtle)`) so route transitions between full-screen surfaces do not flash a different base color; override that token after the global import for a different application canvas. The reset also applies `scrollbar-width: thin` + a token-colored `scrollbar-color` to every element, so **every** scroll container — library components and your own — gets a thin themed scrollbar instead of the OS default. (One deliberate exception: a collapsed `<Rail>` hides its bar entirely, since a gutter is about a quarter of the 56px rail's inner width.) It's declared at specificity 0-0-0; opt a scroller out with its own `scrollbar-width: auto` / `scrollbar-color: auto`. Note that Chromium ignores `::-webkit-scrollbar` rules on any scroller where these standard properties are set — if you already style scrollbars that way, they'll stop applying.
 3. **Base typography** — `body` font + size, `h1`–`h4` sizes, link color. Global rules, not scoped.
 
-If you need only the tokens (you're providing your own reset), import `@eocrm/design-system/styles/tokens.scss` directly. Other available subpath imports: `./styles/reset.scss`, `./styles/typography.scss`, `./styles/mixins.scss`.
+If you need only the tokens (you're providing your own reset), import `@eocrm/design-system/styles/tokens.css` directly. Sass variables: `@eocrm/design-tokens`. `mixins.scss` was removed with no replacement.
 
 ---
 
@@ -80,7 +78,7 @@ The accent family defaults to blue. To switch the whole app to another accent, s
 | `ocean`       | Cyan-blue        | `EocrmOceanLightTokens` / `EocrmOceanDarkTokens`       |
 | `moss`        | Olive green      | `EocrmMossLightTokens` / `EocrmMossDarkTokens`         |
 
-Each accent swaps `--color-accent`, `-hover`, `-pressed`, `-fg`, `-bg-subtle`, `-subtle-bg` and `--ring-accent`, plus the default `Link` colour (`--color-link-fg` / `-hover`), in light, forced dark (`data-theme="dark"`) and OS dark. They ship in the existing `tokens.scss` / `dark.scss`, so there is no new import. `AppProvider`'s `tokens` / `darkTokens` overrides win over `data-accent` in every theme (see [docs/setup.md](docs/setup.md)). Info colours stay blue under any accent; DropdownMenu checked items, the OptionsPicker selected row and StagePath done states follow the accent. In light theme, Teal pine's default `Link`s use a slightly brighter teal than the accent (`#007676`, AA on every grey surface) at medium weight (not inside headings, `<strong>` or `<th>`), because the accent alone sits too close to the navy body text to read as a link. Slate's default `Link`s are medium weight for the same reason. Indigo and Berry also set a slightly different link colour from their accent (`#4342c4`, `#a82c68`) to keep links at AA on every grey surface.
+Each accent swaps `--color-accent`, `-hover`, `-pressed`, `-fg`, `-bg-subtle`, `-subtle-bg` and `--ring-accent`, plus the default `Link` colour (`--color-link-fg` / `-hover`), in light, forced dark (`data-theme="dark"`) and OS dark. They ship in the existing `tokens.css` / `global.css`, so there is no new import. `AppProvider`'s `tokens` / `darkTokens` overrides win over `data-accent` in every theme (see [docs/setup.md](docs/setup.md)). Info colours stay blue under any accent; DropdownMenu checked items, the OptionsPicker selected row and StagePath done states follow the accent. In light theme, Teal pine's default `Link`s use a slightly brighter teal than the accent (`#007676`, AA on every grey surface) at medium weight (not inside headings, `<strong>` or `<th>`), because the accent alone sits too close to the navy body text to read as a link. Slate's default `Link`s are medium weight for the same reason. Indigo and Berry also set a slightly different link colour from their accent (`#4342c4`, `#a82c68`) to keep links at AA on every grey surface.
 
 Compose: each accent's Light / Dark objects sit beside `EocrmLightTokens` / `EocrmDarkTokens`; only accent colours differ. The link colour tokens are web-only (Compose has no `Link`), so Compose links keep the accent colour.
 
@@ -92,29 +90,61 @@ There is deliberately no red, orange or yellow accent: a primary button in those
 
 ## Bundler notes
 
-The package ships **source files** (`.tsx`, `.module.scss`). Your bundler compiles them.
+The package ships **compiled ESM** (`dist/`) with `.d.ts` types and plain CSS. No Sass, TypeScript or transpile configuration is needed.
+
+- **CSS imports**: every component's JS chunk imports its own `.css`, so the bundler must handle CSS imports. Next.js, Vite, Rsbuild and CRA do out of the box; plain webpack 5 needs `css-loader` plus `style-loader` or `mini-css-extract-plugin`; Rollup needs a CSS plugin. Import `@eocrm/design-system/styles/global.css` once at the app root.
+- **One way to load component CSS**: use either `styles.css` (a single `<link>`, for setups whose CSS pipeline can't take imports from JS) or the JS imports, not both — loading both duplicates every rule. The JS itself always needs a bundler (it imports CSS and reads `process.env.NODE_ENV`).
+- **Next.js (app router)**: works as-is, no `transpilePackages`. Client-bound modules carry `'use client'`, so plain components (`Button`, `Select`, `Badge`, `Input`, …) can be rendered directly from Server Components. Three limits of the Server/Client boundary:
+  - **Providers**: the `ru` catalog contains functions, and functions cannot be passed from a Server Component to a Client Component. Mount `AppProvider` / `I18nProvider` from your own `'use client'` providers file that imports `ru` (example below), not from `app/layout.tsx` directly.
+  - **Compound parts** (`Breadcrumb.Item`, `Modal.Header`, `Accordion.Item`, `List.Item`, …) cannot be reached from a Server Component — a client module can't be dotted into on the server, so `X.Item` is `undefined` there and rendering fails. Render compound components from a `'use client'` file.
+  - **Controlled overlays** (`Modal`, `Drawer`) need state and a function `onOpenChange`, so render them from a client component.
+- Set `moduleResolution: "bundler"` (or `"node16"`) in your `tsconfig.json` if TypeScript can't resolve types. If `tsc` rejects the side-effect `import '…/styles/global.css'` (TS2882) and your framework doesn't declare CSS modules for you (Vite's `vite/client` and Next's `next-env.d.ts` do), add `declare module '*.css';` to a `.d.ts` file.
+
+```tsx
+// app/providers.tsx
+'use client';
+import { AppProvider, ru } from '@eocrm/design-system';
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <AppProvider locale="ru" messages={ru}>
+      {children}
+    </AppProvider>
+  );
+}
+
+// app/layout.tsx (Server Component)
+import '@eocrm/design-system/styles/global.css';
+import { Providers } from './providers';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="ru">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
 
-- **Vite**: works out of the box.
-- **Next.js**: add `transpilePackages: ['@eocrm/design-system']` to `next.config.js`.
-- **Webpack 5**: ensure your TS/SCSS loaders don't `exclude: /node_modules/` for this package.
-- **Create React App (ejected)**: same as Webpack.
+**Tests.** Vitest externalizes `node_modules` and Node can't import the components' `.css` (`TypeError: Unknown file extension ".css"`), so inline this package (add `css: true` only if you assert on styles):
 
-If TypeScript can't resolve types, set `moduleResolution: "bundler"` (or `"node16"`) in your `tsconfig.json`.
+```ts
+// vitest.config.ts
+test: { server: { deps: { inline: [/@eocrm\/design-system/] } } },
+```
 
-**Tests.** Vitest works out of the box. Jest (CommonJS) must transform this package (TSX source) and its ESM-only dependencies (`d3-*`, `internmap`, used by `Chart`), and map `.module.scss` imports:
+Jest (CommonJS) needs to transform this ESM package and its ESM-only dependencies (`d3-*`, `internmap`, used by `Chart`), and stub `.css` imports:
 
 ```js
 // jest.config.js — the pattern covers npm/yarn and pnpm (node_modules/.pnpm/<name>@<version>/…) layouts
 transformIgnorePatterns: [
   '/node_modules/(?!(\\.pnpm/)?(@eocrm[/+]design-system|d3-[^/@]+|internmap)[/@])',
 ],
-moduleNameMapper: { '\\.module\\.scss$': 'identity-obj-proxy' },
+moduleNameMapper: { '\\.css$': '<rootDir>/emptyModule.js' },
 ```
 
-- Install `identity-obj-proxy` as a dev dependency.
-- The transformer must compile TSX and convert ESM to CommonJS inside `node_modules`:
-  - `babel-jest`: a root `babel.config.js` (a `.babelrc` does not apply to `node_modules`) with `@babel/preset-env` (`targets: { node: 'current' }`, which converts `import`/`export`), `@babel/preset-react` (`runtime: 'automatic'`) and `@babel/preset-typescript`.
-  - `ts-jest`: `preset: 'ts-jest/presets/js-with-ts'` (so `.js` files are transformed too), with `allowJs: true`, `jsx: 'react-jsx'` and `module: 'commonjs'` in the tsconfig it uses, and `isolatedModules: true` (transpile only). The package does not ship a `*.module.scss` type declaration, so a type-checking ts-jest reports TS2307 on its style imports unless you declare `*.module.scss` yourself.
+- `emptyModule.js` is an empty file (`module.exports = {};`).
+- The transformer must convert ESM to CommonJS inside `node_modules`: `babel-jest` with a root `babel.config.js` (a `.babelrc` does not apply to `node_modules`) using `@babel/preset-env` (`targets: { node: 'current' }`), or `ts-jest` with `preset: 'ts-jest/presets/js-with-ts'`, `allowJs: true` and `module: 'commonjs'`.
 
 ---
 
@@ -235,6 +265,13 @@ Grouped for navigation. Per-component contracts are in `docs/components/<Name>.m
 
 ---
 
+## Migrating to 0.7
+
+- **Stylesheet:** `@eocrm/design-system/styles/global.scss` is now `@eocrm/design-system/styles/global.css`. `styles.css` bundles every component's CSS; per-component CSS is also imported automatically by the JS chunks — use one or the other, not both.
+- **Removed subpaths:** `styles/tokens.scss`, `styles/reset.scss`, `styles/typography.scss` and `styles/mixins.scss` are gone. Use `styles/tokens.css` for tokens only. Sass variables: `@eocrm/design-tokens` (`@use` it directly). `mixins.scss` was removed with no replacement.
+- **Compiled output:** the package no longer ships `src/`; drop `transpilePackages` and any Sass/TSX loader rules for it.
+- **i18n:** `I18nProvider` / `AppProvider` no longer bundle Russian. Pass the catalog: `<I18nProvider locale="ru" messages={ru}>` with `import { ru } from '@eocrm/design-system'`. A non-`en` locale without `messages` logs a `console.error` and renders English. In a Next.js app router, pass `ru` from a `'use client'` providers file (see [Bundler notes](#bundler-notes)) — a Server Component cannot pass its function leaves.
+
 ## Releasing a new version
 
 Releases are **automatic**. Merging to `main` triggers the `Release` workflow (`.github/workflows/release.yml`), which:
@@ -248,6 +285,8 @@ Releases are **automatic**. Merging to `main` triggers the `Release` workflow (`
 
 There is no manual "Run workflow" button — merging to `main` is the only way to release. Playground-only changes skip the publish step (no version bump for a demo tweak) but still redeploy the playground.
 
+**Bundle-size budgets**: `size-budgets.json` caps gzip JS/CSS per consumer scenario (`npm run size`, run by Quality `test-ds`); raise a budget deliberately in the PR that grows the bundle.
+
 **Forcing a minor/major bump**: edit `BUMP` (`patch` → `minor` / `major`) in `release.yml` on a branch and merge. There is no other override by design.
 
 **One-time repo setup**: Settings → Actions → General → Workflow permissions → "Read and write permissions".
@@ -260,7 +299,7 @@ The package name `@eocrm/design-system` must match an organization (or user) you
 
 The playground (live component gallery) deploys to GitHub Pages automatically as the final step of the `Release` workflow, so the live site at <https://eocrm.github.io/design-system/> always reflects `main`. It redeploys whenever the quality gate passes — even on playground-only changes, and even if a publish hiccups.
 
-**This repo and its Pages site are public.** The playground bakes the library's source into its bundle via `?raw` imports, so the source is world-readable — that's intentional for a source-distributed library.
+**This repo and its Pages site are public.** The playground bakes the library's source into its bundle via `?raw` imports, so the source is world-readable — that's intentional for an open-source library.
 
 **One-time setup**: Settings → Pages → Source = "GitHub Actions" (not "Deploy from a branch").
 

package/dist/app/AppProvider.d.ts

@@ -0,0 +1,53 @@
+import { type ReactNode } from 'react';
+import { type DeepPartial, type Locale, type Messages } from '../i18n/index.js';
+import { type ToastViewportProps } from '../components/Toast/index.js';
+import { type TokenMap } from './themeTokens.js';
+export interface AppProviderProps {
+    /**
+     * UI-string locale. English is built in; every other locale needs its
+     * catalog passed via `messages`. Drives every component's copy via `useTranslation`.
+     */
+    locale: Locale;
+    /** Message catalog for `locale` (e.g. `ru`). Omitted ⇒ English. */
+    messages?: Messages;
+    /**
+     * BCP-47 locale for Intl-facing formatting (Calendar, dates, numbers), read
+     * by components via `useLocale`. Optional — defaults to `locale` verbatim
+     * (`'en'` / `'ru'` are valid language tags). Set it for a region, e.g.
+     * `'en-US'` / `'ru-RU'` / `'en-GB'`.
+     */
+    intlLocale?: string;
+    /**
+     * Deep-partial overrides deep-merged over `messages` (or English).
+     * Supply only the keys you rebrand/retext; the rest fall back to the shipped
+     * defaults. Memoize this object — passing a fresh literal every render
+     * rebuilds the merged messages each time.
+     */
+    translations?: DeepPartial<Messages>;
+    /**
+     * Toast viewport configuration (`position`, `duration`, …), or `false` to
+     * NOT mount a viewport (place `<ToastViewport>` yourself). Omitted ⇒ a
+     * viewport is mounted with the library defaults.
+     */
+    toast?: ToastViewportProps | false;
+    /**
+     * CSS design-token overrides applied in BOTH light and dark — a flat map of
+     * token name → value (`{ '--color-accent': '#7c3aed', '--radius-md': '6px' }`).
+     * Rebrands the design system globally (reaches portaled Modal/Tooltip/Toast).
+     * Emitted as a declarative `<style>`; layers over the dark theme correctly.
+     * **Memoize this object** — a fresh literal each render rebuilds the CSS.
+     */
+    tokens?: TokenMap;
+    /**
+     * Token overrides applied ONLY in dark (forced `data-theme="dark"` and system
+     * `prefers-color-scheme: dark`), merged over `tokens` — use it to tune a token
+     * for dark surfaces (e.g. a lighter accent). **Memoize this object.**
+     */
+    darkTokens?: TokenMap;
+    children: ReactNode;
+}
+/**
+ * App root: composes `LocaleProvider` + `I18nProvider` and mounts the toast viewport.
+ * @see docs/setup.md
+ */
+export declare function AppProvider({ locale, messages, intlLocale, translations, toast, tokens, darkTokens, children, }: AppProviderProps): import("react").JSX.Element;

package/dist/app/AppProvider.js

@@ -0,0 +1,32 @@
+'use client';
+import { LocaleProvider } from "../i18n/LocaleProvider.js";
+import { I18nProvider } from "../i18n/I18nProvider.js";
+import { ToastViewport } from "../components/Toast/ToastViewport.js";
+import { buildThemeTokenCss } from "./themeTokens.js";
+import { useMemo } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+// src/app/AppProvider.tsx
+/**
+* App root: composes `LocaleProvider` + `I18nProvider` and mounts the toast viewport.
+* @see docs/setup.md
+*/
+function AppProvider({ locale, messages, intlLocale, translations, toast, tokens, darkTokens, children }) {
+	const tokenCss = useMemo(() => buildThemeTokenCss(tokens, darkTokens), [tokens, darkTokens]);
+	return /* @__PURE__ */ jsx(LocaleProvider, {
+		locale: intlLocale ?? locale,
+		children: /* @__PURE__ */ jsxs(I18nProvider, {
+			locale,
+			messages,
+			overrides: translations,
+			children: [
+				tokenCss && /* @__PURE__ */ jsx("style", {
+					"data-eocrm-tokens": true,
+					children: tokenCss
+				}),
+				children,
+				toast !== false && /* @__PURE__ */ jsx(ToastViewport, { ...toast ?? {} })
+			]
+		})
+	});
+}
+export { AppProvider };

package/dist/app/index.d.ts

@@ -0,0 +1,3 @@
+export { AppProvider } from './AppProvider.js';
+export type { AppProviderProps } from './AppProvider.js';
+export type { TokenMap } from './themeTokens.js';

package/dist/app/themeTokens.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A flat map of CSS design-token overrides: custom-property name → value.
+ * Keys must start with `--` (e.g. `--color-accent`, `--radius-md`,
+ * `--font-family-sans`). Consumed by `<AppProvider tokens>` / `darkTokens`.
+ */
+export type TokenMap = Partial<Record<`--${string}`, string>>;
+/**
+ * Build the CSS for consumer token overrides, mirroring `dark.scss`'s scopes so
+ * the cascade resolves correctly:
+ * - `tokens` → `:root {}` plus accent-aware twins (`:root:root[data-accent]`) that
+ *   win over the generated `data-accent` blocks by specificity, AND re-emitted
+ *   into the dark scopes so a single map applies in both themes.
+ * - `darkTokens` → layered AFTER `tokens` inside the dark scopes only.
+ *
+ * Returns `null` when there is nothing to emit, so `<AppProvider>` renders no
+ * `<style>` for the no-override case (preserving its zero-side-effect default).
+ */
+export declare function buildThemeTokenCss(tokens?: TokenMap, darkTokens?: TokenMap): string | null;

package/dist/app/themeTokens.js

@@ -0,0 +1,61 @@
+// src/app/themeTokens.ts
+var IS_DEV = typeof process !== "undefined" && process.env.NODE_ENV !== "production";
+var KEY_RE = /^--[\w-]+$/;
+var UNSAFE_VALUE_RE = /[{}<>]/;
+function warn(message) {
+	if (IS_DEV) console.warn(`[AppProvider] ${message}`);
+}
+/**
+* Keep only entries whose key is a valid custom-property name and whose value
+* cannot break out of a CSS declaration / the <style> element. Rejected
+* entries are dropped with a dev warning (the consumer is trusted — this is
+* defensive, not a security boundary). Preserves the map's own key order.
+*/
+function sanitizeEntries(map) {
+	if (!map) return [];
+	const out = [];
+	for (const [key, value] of Object.entries(map)) {
+		if (value == null) continue;
+		if (!KEY_RE.test(key)) {
+			warn(`ignoring override with invalid key ${JSON.stringify(key)} (must match --name)`);
+			continue;
+		}
+		if (UNSAFE_VALUE_RE.test(value)) {
+			warn(`ignoring override ${key}: value contains an unsafe character ({ } < >)`);
+			continue;
+		}
+		out.push([key, value]);
+	}
+	return out;
+}
+function declarations(entries, indent) {
+	return entries.map(([key, value]) => `${indent}${key}: ${value};`).join("\n");
+}
+var LIGHT_SELECTOR = ":root, :root:root[data-accent]";
+var DARK_SELECTOR = ":root[data-theme='dark'], :root:root[data-accent][data-theme='dark']";
+var OS_DARK_SELECTOR = ":root:not([data-theme='light']), :root:root[data-accent]:not([data-theme='light'])";
+/**
+* Build the CSS for consumer token overrides, mirroring `dark.scss`'s scopes so
+* the cascade resolves correctly:
+* - `tokens` → `:root {}` plus accent-aware twins (`:root:root[data-accent]`) that
+*   win over the generated `data-accent` blocks by specificity, AND re-emitted
+*   into the dark scopes so a single map applies in both themes.
+* - `darkTokens` → layered AFTER `tokens` inside the dark scopes only.
+*
+* Returns `null` when there is nothing to emit, so `<AppProvider>` renders no
+* `<style>` for the no-override case (preserving its zero-side-effect default).
+*/
+function buildThemeTokenCss(tokens, darkTokens) {
+	const base = sanitizeEntries(tokens);
+	const dark = sanitizeEntries(darkTokens);
+	if (base.length === 0 && dark.length === 0) return null;
+	const blocks = [];
+	if (base.length > 0) blocks.push(`${LIGHT_SELECTOR} {\n${declarations(base, "  ")}\n}`);
+	const darkScope = [...base, ...dark];
+	if (darkScope.length > 0) {
+		blocks.push(`${DARK_SELECTOR} {\n${declarations(darkScope, "  ")}\n}`);
+		blocks.push(`@media (prefers-color-scheme: dark) {\n  ${OS_DARK_SELECTOR} {\n${declarations(darkScope, "    ")}\n  }\n}`);
+	}
+	return blocks.join("\n");
+}
+export { buildThemeTokenCss };

package/dist/calendar/dateMath.d.ts

@@ -0,0 +1,45 @@
+/** Return a new Date `n` days after `date`. Local-time anchored. Does not mutate `date`. */
+export declare function addDays(date: Date, n: number): Date;
+/**
+ * Return a new Date `n` months after `date`. Clamps day-of-month onto shorter
+ * target months (Jan 31 + 1 month → Feb 28/29). Does not mutate `date`.
+ */
+export declare function addMonths(date: Date, n: number): Date;
+/** Return a new Date `n` weeks after `date` (sugar for `addDays(date, n * 7)`). */
+export declare function addWeeks(date: Date, n: number): Date;
+/** Return a new Date with the same calendar day at local 00:00:00.000. */
+export declare function startOfDay(date: Date): Date;
+/**
+ * Return the local-midnight start of the week containing `date`. `weekStartsOn`
+ * is the column index of the locale's first-day-of-week (0 = Sunday, 1 = Monday).
+ */
+export declare function startOfWeek(date: Date, weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6): Date;
+/** Return the 1st of `date`'s month at local midnight. */
+export declare function startOfMonth(date: Date): Date;
+/** Return the last day of `date`'s month at local midnight (e.g., Jan 31, Feb 28/29). */
+export declare function endOfMonth(date: Date): Date;
+/** True when `a` and `b` fall on the same calendar day (ignores time component). */
+export declare function isSameDay(a: Date, b: Date): boolean;
+/** True when `a` and `b` fall in the same calendar month and year. */
+export declare function isSameMonth(a: Date, b: Date): boolean;
+/**
+ * True when `date` is today. Pass an explicit `now` for deterministic tests;
+ * defaults to `new Date()`.
+ */
+export declare function isToday(date: Date, now?: Date): boolean;
+/**
+ * True when `date.getDay()` is in `weekendDays` (e.g., `[0, 6]` for Sat/Sun
+ * in most locales; `[5, 6]` for Fri/Sat in ar-SA / he-IL). Use
+ * `getWeekendDays(locale)` to derive the array.
+ */
+export declare function isWeekend(date: Date, weekendDays: readonly number[]): boolean;
+/**
+ * Calendar-day difference between `a` and `b`. DST-safe — rounds to whole
+ * days so the ±1 hour offset across a DST boundary doesn't shift the count.
+ * Positive when `b` is after `a`.
+ */
+export declare function daysBetween(a: Date, b: Date): number;
+/** Return `'YYYY-MM-DD'` in local time. Zero-padded month and day. */
+export declare function toDateKey(date: Date): string;
+/** Parse a `'YYYY-MM-DD'` key (as produced by `toDateKey`) to a local-midnight Date. */
+export declare function fromDateKey(key: string): Date;

package/dist/calendar/dateMath.js

@@ -0,0 +1,92 @@
+// src/calendar/dateMath.ts
+var MS_PER_DAY = 864e5;
+/** Return a new Date `n` days after `date`. Local-time anchored. Does not mutate `date`. */
+function addDays(date, n) {
+	const result = new Date(date);
+	result.setDate(result.getDate() + n);
+	return result;
+}
+/**
+* Return a new Date `n` months after `date`. Clamps day-of-month onto shorter
+* target months (Jan 31 + 1 month → Feb 28/29). Does not mutate `date`.
+*/
+function addMonths(date, n) {
+	const result = new Date(date);
+	const originalDay = result.getDate();
+	result.setDate(1);
+	result.setMonth(result.getMonth() + n);
+	const lastDay = new Date(result.getFullYear(), result.getMonth() + 1, 0).getDate();
+	result.setDate(Math.min(originalDay, lastDay));
+	return result;
+}
+/** Return a new Date `n` weeks after `date` (sugar for `addDays(date, n * 7)`). */
+function addWeeks(date, n) {
+	return addDays(date, n * 7);
+}
+/** Return a new Date with the same calendar day at local 00:00:00.000. */
+function startOfDay(date) {
+	const result = new Date(date);
+	result.setHours(0, 0, 0, 0);
+	return result;
+}
+/**
+* Return the local-midnight start of the week containing `date`. `weekStartsOn`
+* is the column index of the locale's first-day-of-week (0 = Sunday, 1 = Monday).
+*/
+function startOfWeek(date, weekStartsOn) {
+	const result = startOfDay(date);
+	const delta = (result.getDay() - weekStartsOn + 7) % 7;
+	result.setDate(result.getDate() - delta);
+	return result;
+}
+/** Return the 1st of `date`'s month at local midnight. */
+function startOfMonth(date) {
+	return new Date(date.getFullYear(), date.getMonth(), 1);
+}
+/** Return the last day of `date`'s month at local midnight (e.g., Jan 31, Feb 28/29). */
+function endOfMonth(date) {
+	return new Date(date.getFullYear(), date.getMonth() + 1, 0);
+}
+/** True when `a` and `b` fall on the same calendar day (ignores time component). */
+function isSameDay(a, b) {
+	return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+}
+/** True when `a` and `b` fall in the same calendar month and year. */
+function isSameMonth(a, b) {
+	return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+}
+/**
+* True when `date` is today. Pass an explicit `now` for deterministic tests;
+* defaults to `new Date()`.
+*/
+function isToday(date, now = /* @__PURE__ */ new Date()) {
+	return isSameDay(date, now);
+}
+/**
+* True when `date.getDay()` is in `weekendDays` (e.g., `[0, 6]` for Sat/Sun
+* in most locales; `[5, 6]` for Fri/Sat in ar-SA / he-IL). Use
+* `getWeekendDays(locale)` to derive the array.
+*/
+function isWeekend(date, weekendDays) {
+	return weekendDays.includes(date.getDay());
+}
+/**
+* Calendar-day difference between `a` and `b`. DST-safe — rounds to whole
+* days so the ±1 hour offset across a DST boundary doesn't shift the count.
+* Positive when `b` is after `a`.
+*/
+function daysBetween(a, b) {
+	const startA = startOfDay(a).getTime();
+	const startB = startOfDay(b).getTime();
+	return Math.round((startB - startA) / MS_PER_DAY);
+}
+/** Return `'YYYY-MM-DD'` in local time. Zero-padded month and day. */
+function toDateKey(date) {
+	return `${String(date.getFullYear()).padStart(4, "0")}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+/** Parse a `'YYYY-MM-DD'` key (as produced by `toDateKey`) to a local-midnight Date. */
+function fromDateKey(key) {
+	const [yyyy, mm, dd] = key.split("-").map(Number);
+	return new Date(yyyy, mm - 1, dd);
+}
+export { addDays, addMonths, addWeeks, daysBetween, endOfMonth, fromDateKey, isSameDay, isSameMonth, isToday, isWeekend, startOfDay, startOfMonth, startOfWeek, toDateKey };

package/dist/calendar/formatters.d.ts

@@ -0,0 +1,30 @@
+/**
+ * "May 2026" / "Май 2026" — capitalized standalone month name + numeric year,
+ * without the locale's era suffix.
+ *
+ * `Intl.DateTimeFormat(locale, { year: 'numeric', month: 'long' })` in some
+ * locales (notably `ru-RU`) yields "май 2026 г." — lowercase genitive month
+ * with an era marker. For calendar headers we want a nominative-cased
+ * standalone month, so we format month and year separately and uppercase the
+ * first character of the month with locale-aware casing.
+ */
+export declare function formatMonth(date: Date, locale: string): string;
+/** "Mon" (Intl 'short' weekday). */
+export declare function formatWeekdayShort(date: Date, locale: string): string;
+/** "M" (Intl 'narrow' weekday — for tight column headers). */
+export declare function formatWeekdayNarrow(date: Date, locale: string): string;
+/** "Wed 20" */
+export declare function formatDayShort(date: Date, locale: string): string;
+/** "Wednesday, May 20" */
+export declare function formatDayLong(date: Date, locale: string): string;
+/** "May 18 – 24, 2026" via Intl.DateTimeFormat#formatRange. */
+export declare function formatRange(from: Date, to: Date, locale: string): string;
+/** "9 AM" / "09:00" — hour only, 12/24-hour determined by locale default. */
+export declare function formatHour(hour: number, locale: string): string;
+/**
+ * "9:00 AM" / "09:00" — hour + minute, suitable for event start times.
+ * 12/24-hour determined by locale default.
+ */
+export declare function formatTime(date: Date, locale: string): string;
+/** Test-only helper. Resets the formatter cache between tests. */
+export declare function _resetFormatterCacheForTests(): void;

package/dist/calendar/formatters.js

@@ -0,0 +1,73 @@
+// src/calendar/formatters.ts
+var cache = /* @__PURE__ */ new Map();
+function getFormatter(locale, options) {
+	const key = `${locale}|${JSON.stringify(options)}`;
+	let f = cache.get(key);
+	if (!f) {
+		f = new Intl.DateTimeFormat(locale, options);
+		cache.set(key, f);
+	}
+	return f;
+}
+/**
+* "May 2026" / "Май 2026" — capitalized standalone month name + numeric year,
+* without the locale's era suffix.
+*
+* `Intl.DateTimeFormat(locale, { year: 'numeric', month: 'long' })` in some
+* locales (notably `ru-RU`) yields "май 2026 г." — lowercase genitive month
+* with an era marker. For calendar headers we want a nominative-cased
+* standalone month, so we format month and year separately and uppercase the
+* first character of the month with locale-aware casing.
+*/
+function formatMonth(date, locale) {
+	const month = getFormatter(locale, { month: "long" }).format(date);
+	const year = date.getFullYear();
+	return `${month.charAt(0).toLocaleUpperCase(locale) + month.slice(1)} ${year}`;
+}
+/** "Mon" (Intl 'short' weekday). */
+function formatWeekdayShort(date, locale) {
+	return getFormatter(locale, { weekday: "short" }).format(date);
+}
+/** "M" (Intl 'narrow' weekday — for tight column headers). */
+function formatWeekdayNarrow(date, locale) {
+	return getFormatter(locale, { weekday: "narrow" }).format(date);
+}
+/** "Wed 20" */
+function formatDayShort(date, locale) {
+	return getFormatter(locale, {
+		weekday: "short",
+		day: "numeric"
+	}).format(date);
+}
+/** "Wednesday, May 20" */
+function formatDayLong(date, locale) {
+	return getFormatter(locale, {
+		weekday: "long",
+		month: "long",
+		day: "numeric"
+	}).format(date);
+}
+/** "May 18 – 24, 2026" via Intl.DateTimeFormat#formatRange. */
+function formatRange(from, to, locale) {
+	return getFormatter(locale, {
+		year: "numeric",
+		month: "long",
+		day: "numeric"
+	}).formatRange(from, to);
+}
+/** "9 AM" / "09:00" — hour only, 12/24-hour determined by locale default. */
+function formatHour(hour, locale) {
+	const date = new Date(2e3, 0, 1, hour);
+	return getFormatter(locale, { hour: "numeric" }).format(date);
+}
+/**
+* "9:00 AM" / "09:00" — hour + minute, suitable for event start times.
+* 12/24-hour determined by locale default.
+*/
+function formatTime(date, locale) {
+	return getFormatter(locale, {
+		hour: "numeric",
+		minute: "2-digit"
+	}).format(date);
+}
+export { formatDayLong, formatDayShort, formatHour, formatMonth, formatRange, formatTime, formatWeekdayNarrow, formatWeekdayShort };

package/dist/calendar/index.d.ts

@@ -0,0 +1,12 @@
+export { useMonth } from './useMonth.js';
+export type { UseMonthOptions } from './useMonth.js';
+export { useWeek } from './useWeek.js';
+export type { UseWeekOptions, WeekResult } from './useWeek.js';
+export { useDay } from './useDay.js';
+export type { UseDayOptions, DayResult } from './useDay.js';
+export { useAgenda } from './useAgenda.js';
+export type { UseAgendaOptions, AgendaResult } from './useAgenda.js';
+export type { Day, Week, MonthGrid } from './types.js';
+export { addDays, addMonths, addWeeks, startOfDay, startOfWeek, startOfMonth, endOfMonth, isSameDay, isSameMonth, isToday, isWeekend, daysBetween, toDateKey, fromDateKey, } from './dateMath.js';
+export { formatMonth, formatWeekdayShort, formatWeekdayNarrow, formatDayShort, formatDayLong, formatRange, formatHour, formatTime, } from './formatters.js';
+export { getFirstDayOfWeek, getWeekendDays } from './weekInfo.js';