npm - @cube-dev/ui-kit - Versions diffs - 0.169.1 → 0.170.0 - Mend

@cube-dev/ui-kit 0.169.1 → 0.170.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (588) hide show

package/dist/utils/react/useSchema.js ADDED Viewed

@@ -0,0 +1,182 @@
+/** @license MIT | @cube-dev/ui-kit v0.170.0 | Cube Dev Team */
+import { useSyncExternalStore } from "react";
+//#region src/utils/react/useSchema.ts
+/**
+* The ambient viewing conditions — the color schema and the contrast tier the
+* document is showing right now.
+*
+* This module is the single owner of the definition: it builds the `@dark` /
+* `@hc` predefined states that `src/components/Root.tsx` registers with tasty,
+* *and* it answers the same question in JS. One definition, two readers, so the
+* CSS and the JS answers cannot drift apart.
+*
+* **For styling, do not use this.** `{ '': light, '@dark': dark, '@hc': hc }` is
+* the answer, and branching styles in JS gives up the conditionality that lets a
+* schema flip repaint without a re-render. Two cases the state map cannot serve:
+*
+* 1. **Surfaces the stylesheet does not reach** — a Vega spec, a CodeMirror or
+*    Monaco theme, a third-party iframe. They take values, not CSS, so `@dark`
+*    never applies and the branch has to happen in JS.
+* 2. **Control state that is not styling** — seeding or labelling a control from
+*    the ambient condition, e.g. a Light/Dark or Normal/High-contrast preview
+*    selector that starts on whatever the page is already showing.
+*
+* Root-level only, and deliberately not a generic state reader: tasty's state
+* vocabulary mixes element-local states (`hovered`, `pressed`, `disabled`) with
+* ambient ones (`@media(…)`, `@root(…)`), and only the ambient half is
+* answerable without an element. Evaluating the state language in JS would mean
+* a second implementation of the state algebra to keep in agreement with the CSS
+* one, for a question almost every caller asks about the root anyway.
+*/
+/**
+* The `data-*` attribute names the opt-in uses, and the media queries it falls
+* back to. `@root(schema=dark)` compiles to `:root[data-schema="dark"]`, hence
+* the `data-` prefix on the DOM side and the bare key on the tasty side.
+*/
+const SCHEMA_KEY = "schema";
+const CONTRAST_KEY = "contrast";
+const SCHEMA_ATTR = `data-${SCHEMA_KEY}`;
+const CONTRAST_ATTR = `data-${CONTRAST_KEY}`;
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+const HIGH_CONTRAST_QUERY = "(prefers-contrast: more)";
+/**
+* The `@dark` / `@hc` state aliases, in tasty's DSL — registered globally by
+* `<Root>` via `setGlobalPredefinedStates()`.
+*
+* The attribute opt-in wins over the system preference, and the fallback is
+* gated on the attribute being *absent* (`!@root(schema)`) rather than on it
+* being some other value — so `<html data-schema="light">` stays light inside a
+* dark OS, which is the whole point of an opt-in. {@link resolveSchema} and
+* {@link resolveHighContrast} read the same way.
+*/
+const AMBIENT_PREDEFINED_STATES = {
+	"@dark": `@root(${SCHEMA_KEY}=dark) | (!@root(${SCHEMA_KEY}) & @media${DARK_QUERY})`,
+	"@hc": `@root(${CONTRAST_KEY}=high) | (!@root(${CONTRAST_KEY}) & @media${HIGH_CONTRAST_QUERY})`
+};
+/**
+* `matchMedia` is called per read rather than cached, so a test that stubs it
+* takes effect immediately. Missing (older jsdom, non-DOM runtimes) reads as
+* "no preference", which lands on the light / normal-contrast defaults.
+*/
+function mediaMatches(query) {
+	return typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia(query).matches : false;
+}
+function rootAttribute(name) {
+	return typeof document === "undefined" ? null : document.documentElement.getAttribute(name);
+}
+/**
+* The document's current color schema, read once — the JS answer to `@dark`.
+*
+* Outside React (a chart spec built in a module, an editor theme registered at
+* import time). In React use {@link useSchema}, which also re-renders on change.
+* Returns `'light'` with no DOM.
+*/
+function resolveSchema() {
+	const attribute = rootAttribute(SCHEMA_ATTR);
+	if (attribute !== null) return attribute === "dark" ? "dark" : "light";
+	return mediaMatches(DARK_QUERY) ? "dark" : "light";
+}
+/**
+* Whether the document is showing the high-contrast tier, read once — the JS
+* answer to `@hc`.
+*
+* Note this is an *ambient* condition, not the theme's `contrastLevel`: the
+* level is a `PaletteConfig` seed the app supplies (read it with
+* `getPaletteConfig()`), while this is the tier the viewer asked for.
+* Returns `false` with no DOM.
+*/
+function resolveHighContrast() {
+	const attribute = rootAttribute(CONTRAST_ATTR);
+	if (attribute !== null) return attribute === "high";
+	return mediaMatches(HIGH_CONTRAST_QUERY);
+}
+const listeners = /* @__PURE__ */ new Set();
+let stopWatching = null;
+function notify() {
+	listeners.forEach((listener) => listener());
+}
+/**
+* Both inputs have to be watched, because either can decide the answer: the
+* attribute when the opt-in is set, the media query otherwise — an attribute flip
+* is invisible to `matchMedia` and a system flip is invisible to a
+* `MutationObserver`. One observer and one pair of query listeners are shared by
+* every subscriber, and torn down when the last one leaves.
+*/
+function startWatching() {
+	if (typeof document === "undefined") return () => {};
+	const teardowns = [];
+	if (typeof window !== "undefined" && typeof window.matchMedia === "function") for (const query of [DARK_QUERY, HIGH_CONTRAST_QUERY]) {
+		const list = window.matchMedia(query);
+		if (typeof list?.addEventListener !== "function") continue;
+		list.addEventListener("change", notify);
+		teardowns.push(() => list.removeEventListener("change", notify));
+	}
+	if (typeof MutationObserver === "function" && document.documentElement) {
+		const observer = new MutationObserver(notify);
+		observer.observe(document.documentElement, {
+			attributes: true,
+			attributeFilter: [SCHEMA_ATTR, CONTRAST_ATTR]
+		});
+		teardowns.push(() => observer.disconnect());
+	}
+	return () => teardowns.forEach((teardown) => teardown());
+}
+/**
+* Subscribe to ambient condition changes — either the schema or the contrast
+* tier. Returns an unsubscribe function.
+*
+* The listener takes no argument: re-read with {@link resolveSchema} /
+* {@link resolveHighContrast}, which is what the hooks below do. For non-React
+* consumers that own a surface the stylesheet cannot reach — re-theming a Monaco
+* instance, re-rendering a chart.
+*/
+function subscribeSchema(listener) {
+	listeners.add(listener);
+	if (!stopWatching) stopWatching = startWatching();
+	return () => {
+		listeners.delete(listener);
+		if (!listeners.size && stopWatching) {
+			stopWatching();
+			stopWatching = null;
+		}
+	};
+}
+/**
+* Snapshots are primitives, so React bails out on an unchanged value and no
+* memoization is needed — a contrast change re-runs a `useSchema()` reader's
+* `getSnapshot` and stops there.
+*/
+const getServerSchema = () => "light";
+const getServerHighContrast = () => false;
+/**
+* The document's color schema, kept live — `'light'` or `'dark'`.
+*
+* ```tsx
+* const schema = useSchema();
+*
+* <VegaChart spec={useMemo(() => buildSpec(schema), [schema])} />;
+* ```
+*
+* Follows both the `<html data-schema>` opt-in and `prefers-color-scheme`,
+* exactly as the `@dark` state does. Under SSR it renders `'light'` and
+* re-renders with the real value after hydration.
+*/
+function useSchema() {
+	return useSyncExternalStore(subscribeSchema, resolveSchema, getServerSchema);
+}
+/**
+* Whether the document is showing the high-contrast tier, kept live — the hook
+* form of {@link resolveHighContrast}, following `<html data-contrast>` and
+* `prefers-contrast` exactly as the `@hc` state does.
+*
+* Under SSR it renders `false` and re-renders with the real value after
+* hydration.
+*/
+function useHighContrast() {
+	return useSyncExternalStore(subscribeSchema, resolveHighContrast, getServerHighContrast);
+}
+//#endregion
+export { AMBIENT_PREDEFINED_STATES, resolveHighContrast, resolveSchema, subscribeSchema, useHighContrast, useSchema };
+//# sourceMappingURL=useSchema.js.map

package/dist/utils/react/useSchema.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"useSchema.js","names":[],"sources":["../../../src/utils/react/useSchema.ts"],"sourcesContent":["import { useSyncExternalStore } from 'react';\n\n/**\n * The ambient viewing conditions — the color schema and the contrast tier the\n * document is showing right now.\n *\n * This module is the single owner of the definition: it builds the `@dark` /\n * `@hc` predefined states that `src/components/Root.tsx` registers with tasty,\n * *and* it answers the same question in JS. One definition, two readers, so the\n * CSS and the JS answers cannot drift apart.\n *\n * **For styling, do not use this.** `{ '': light, '@dark': dark, '@hc': hc }` is\n * the answer, and branching styles in JS gives up the conditionality that lets a\n * schema flip repaint without a re-render. Two cases the state map cannot serve:\n *\n * 1. **Surfaces the stylesheet does not reach** — a Vega spec, a CodeMirror or\n * Monaco theme, a third-party iframe. They take values, not CSS, so `@dark`\n * never applies and the branch has to happen in JS.\n * 2. **Control state that is not styling** — seeding or labelling a control from\n * the ambient condition, e.g. a Light/Dark or Normal/High-contrast preview\n * selector that starts on whatever the page is already showing.\n *\n * Root-level only, and deliberately not a generic state reader: tasty's state\n * vocabulary mixes element-local states (`hovered`, `pressed`, `disabled`) with\n * ambient ones (`@media(…)`, `@root(…)`), and only the ambient half is\n * answerable without an element. Evaluating the state language in JS would mean\n * a second implementation of the state algebra to keep in agreement with the CSS\n * one, for a question almost every caller asks about the root anyway.\n */\n\n// ============================================================================\n// The definition\n// ============================================================================\n\n/**\n * The `data-*` attribute names the opt-in uses, and the media queries it falls\n * back to. `@root(schema=dark)` compiles to `:root[data-schema=\"dark\"]`, hence\n * the `data-` prefix on the DOM side and the bare key on the tasty side.\n */\nconst SCHEMA_KEY = 'schema';\nconst CONTRAST_KEY = 'contrast';\nconst SCHEMA_ATTR = `data-${SCHEMA_KEY}`;\nconst CONTRAST_ATTR = `data-${CONTRAST_KEY}`;\nconst DARK_QUERY = '(prefers-color-scheme: dark)';\nconst HIGH_CONTRAST_QUERY = '(prefers-contrast: more)';\n\n/**\n * The `@dark` / `@hc` state aliases, in tasty's DSL — registered globally by\n * `<Root>` via `setGlobalPredefinedStates()`.\n *\n * The attribute opt-in wins over the system preference, and the fallback is\n * gated on the attribute being *absent* (`!@root(schema)`) rather than on it\n * being some other value — so `<html data-schema=\"light\">` stays light inside a\n * dark OS, which is the whole point of an opt-in. {@link resolveSchema} and\n * {@link resolveHighContrast} read the same way.\n */\nexport const AMBIENT_PREDEFINED_STATES = {\n '@dark': `@root(${SCHEMA_KEY}=dark) | (!@root(${SCHEMA_KEY}) & @media${DARK_QUERY})`,\n '@hc': `@root(${CONTRAST_KEY}=high) | (!@root(${CONTRAST_KEY}) & @media${HIGH_CONTRAST_QUERY})`,\n} as const;\n\n/** The color schema the document resolves to — the two arms of the `@dark` state. */\nexport type ColorSchema = 'light' | 'dark';\n\n// ============================================================================\n// Reading\n// ============================================================================\n\n/**\n * `matchMedia` is called per read rather than cached, so a test that stubs it\n * takes effect immediately. Missing (older jsdom, non-DOM runtimes) reads as\n * \"no preference\", which lands on the light / normal-contrast defaults.\n */\nfunction mediaMatches(query: string): boolean {\n return typeof window !== 'undefined' &&\n typeof window.matchMedia === 'function'\n ? window.matchMedia(query).matches\n : false;\n}\n\nfunction rootAttribute(name: string): string | null {\n return typeof document === 'undefined'\n ? null\n : document.documentElement.getAttribute(name);\n}\n\n/**\n * The document's current color schema, read once — the JS answer to `@dark`.\n *\n * Outside React (a chart spec built in a module, an editor theme registered at\n * import time). In React use {@link useSchema}, which also re-renders on change.\n * Returns `'light'` with no DOM.\n */\nexport function resolveSchema(): ColorSchema {\n const attribute = rootAttribute(SCHEMA_ATTR);\n\n if (attribute !== null) {\n return attribute === 'dark' ? 'dark' : 'light';\n }\n\n return mediaMatches(DARK_QUERY) ? 'dark' : 'light';\n}\n\n/**\n * Whether the document is showing the high-contrast tier, read once — the JS\n * answer to `@hc`.\n *\n * Note this is an *ambient* condition, not the theme's `contrastLevel`: the\n * level is a `PaletteConfig` seed the app supplies (read it with\n * `getPaletteConfig()`), while this is the tier the viewer asked for.\n * Returns `false` with no DOM.\n */\nexport function resolveHighContrast(): boolean {\n const attribute = rootAttribute(CONTRAST_ATTR);\n\n if (attribute !== null) {\n return attribute === 'high';\n }\n\n return mediaMatches(HIGH_CONTRAST_QUERY);\n}\n\n// ============================================================================\n// Watching\n// ============================================================================\n\nconst listeners = new Set<() => void>();\n\nlet stopWatching: (() => void) | null = null;\n\nfunction notify() {\n listeners.forEach((listener) => listener());\n}\n\n/**\n * Both inputs have to be watched, because either can decide the answer: the\n * attribute when the opt-in is set, the media query otherwise — an attribute flip\n * is invisible to `matchMedia` and a system flip is invisible to a\n * `MutationObserver`. One observer and one pair of query listeners are shared by\n * every subscriber, and torn down when the last one leaves.\n */\nfunction startWatching(): () => void {\n if (typeof document === 'undefined') {\n return () => {};\n }\n\n const teardowns: (() => void)[] = [];\n\n // Guarded rather than assumed: jsdom ships neither `matchMedia` nor a\n // `MediaQueryList` in every version, and a consumer's unit tests are exactly\n // where a hook like this gets mounted. Losing one source of change is a stale\n // value; throwing is a broken render.\n if (\n typeof window !== 'undefined' &&\n typeof window.matchMedia === 'function'\n ) {\n for (const query of [DARK_QUERY, HIGH_CONTRAST_QUERY]) {\n const list = window.matchMedia(query);\n\n if (typeof list?.addEventListener !== 'function') continue;\n\n list.addEventListener('change', notify);\n teardowns.push(() => list.removeEventListener('change', notify));\n }\n }\n\n if (typeof MutationObserver === 'function' && document.documentElement) {\n const observer = new MutationObserver(notify);\n\n observer.observe(document.documentElement, {\n attributes: true,\n attributeFilter: [SCHEMA_ATTR, CONTRAST_ATTR],\n });\n\n teardowns.push(() => observer.disconnect());\n }\n\n return () => teardowns.forEach((teardown) => teardown());\n}\n\n/**\n * Subscribe to ambient condition changes — either the schema or the contrast\n * tier. Returns an unsubscribe function.\n *\n * The listener takes no argument: re-read with {@link resolveSchema} /\n * {@link resolveHighContrast}, which is what the hooks below do. For non-React\n * consumers that own a surface the stylesheet cannot reach — re-theming a Monaco\n * instance, re-rendering a chart.\n */\nexport function subscribeSchema(listener: () => void): () => void {\n listeners.add(listener);\n\n if (!stopWatching) {\n stopWatching = startWatching();\n }\n\n return () => {\n listeners.delete(listener);\n\n if (!listeners.size && stopWatching) {\n stopWatching();\n stopWatching = null;\n }\n };\n}\n\n// ============================================================================\n// React bindings\n// ============================================================================\n\n/**\n * Snapshots are primitives, so React bails out on an unchanged value and no\n * memoization is needed — a contrast change re-runs a `useSchema()` reader's\n * `getSnapshot` and stops there.\n */\nconst getServerSchema = (): ColorSchema => 'light';\nconst getServerHighContrast = () => false;\n\n/**\n * The document's color schema, kept live — `'light'` or `'dark'`.\n *\n * ```tsx\n * const schema = useSchema();\n *\n * <VegaChart spec={useMemo(() => buildSpec(schema), [schema])} />;\n * ```\n *\n * Follows both the `<html data-schema>` opt-in and `prefers-color-scheme`,\n * exactly as the `@dark` state does. Under SSR it renders `'light'` and\n * re-renders with the real value after hydration.\n */\nexport function useSchema(): ColorSchema {\n return useSyncExternalStore(subscribeSchema, resolveSchema, getServerSchema);\n}\n\n/**\n * Whether the document is showing the high-contrast tier, kept live — the hook\n * form of {@link resolveHighContrast}, following `<html data-contrast>` and\n * `prefers-contrast` exactly as the `@hc` state does.\n *\n * Under SSR it renders `false` and re-renders with the real value after\n * hydration.\n */\nexport function useHighContrast(): boolean {\n return useSyncExternalStore(\n subscribeSchema,\n resolveHighContrast,\n getServerHighContrast,\n );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,MAAM,aAAa;AACnB,MAAM,eAAe;AACrB,MAAM,cAAc,QAAQ;AAC5B,MAAM,gBAAgB,QAAQ;AAC9B,MAAM,aAAa;AACnB,MAAM,sBAAsB;;;;;;;;;;;AAY5B,MAAa,4BAA4B;CACvC,SAAS,SAAS,WAAW,mBAAmB,WAAW,YAAY,WAAW;CAClF,OAAO,SAAS,aAAa,mBAAmB,aAAa,YAAY,oBAAoB;CAC9F;;;;;;AAcD,SAAS,aAAa,OAAwB;AAC5C,QAAO,OAAO,WAAW,eACvB,OAAO,OAAO,eAAe,aAC3B,OAAO,WAAW,MAAM,CAAC,UACzB;;AAGN,SAAS,cAAc,MAA6B;AAClD,QAAO,OAAO,aAAa,cACvB,OACA,SAAS,gBAAgB,aAAa,KAAK;;;;;;;;;AAUjD,SAAgB,gBAA6B;CAC3C,MAAM,YAAY,cAAc,YAAY;AAE5C,KAAI,cAAc,KAChB,QAAO,cAAc,SAAS,SAAS;AAGzC,QAAO,aAAa,WAAW,GAAG,SAAS;;;;;;;;;;;AAY7C,SAAgB,sBAA+B;CAC7C,MAAM,YAAY,cAAc,cAAc;AAE9C,KAAI,cAAc,KAChB,QAAO,cAAc;AAGvB,QAAO,aAAa,oBAAoB;;AAO1C,MAAM,4BAAY,IAAI,KAAiB;AAEvC,IAAI,eAAoC;AAExC,SAAS,SAAS;AAChB,WAAU,SAAS,aAAa,UAAU,CAAC;;;;;;;;;AAU7C,SAAS,gBAA4B;AACnC,KAAI,OAAO,aAAa,YACtB,cAAa;CAGf,MAAM,YAA4B,EAAE;AAMpC,KACE,OAAO,WAAW,eAClB,OAAO,OAAO,eAAe,WAE7B,MAAK,MAAM,SAAS,CAAC,YAAY,oBAAoB,EAAE;EACrD,MAAM,OAAO,OAAO,WAAW,MAAM;AAErC,MAAI,OAAO,MAAM,qBAAqB,WAAY;AAElD,OAAK,iBAAiB,UAAU,OAAO;AACvC,YAAU,WAAW,KAAK,oBAAoB,UAAU,OAAO,CAAC;;AAIpE,KAAI,OAAO,qBAAqB,cAAc,SAAS,iBAAiB;EACtE,MAAM,WAAW,IAAI,iBAAiB,OAAO;AAE7C,WAAS,QAAQ,SAAS,iBAAiB;GACzC,YAAY;GACZ,iBAAiB,CAAC,aAAa,cAAc;GAC9C,CAAC;AAEF,YAAU,WAAW,SAAS,YAAY,CAAC;;AAG7C,cAAa,UAAU,SAAS,aAAa,UAAU,CAAC;;;;;;;;;;;AAY1D,SAAgB,gBAAgB,UAAkC;AAChE,WAAU,IAAI,SAAS;AAEvB,KAAI,CAAC,aACH,gBAAe,eAAe;AAGhC,cAAa;AACX,YAAU,OAAO,SAAS;AAE1B,MAAI,CAAC,UAAU,QAAQ,cAAc;AACnC,iBAAc;AACd,kBAAe;;;;;;;;;AAcrB,MAAM,wBAAqC;AAC3C,MAAM,8BAA8B;;;;;;;;;;;;;;AAepC,SAAgB,YAAyB;AACvC,QAAO,qBAAqB,iBAAiB,eAAe,gBAAgB;;;;;;;;;;AAW9E,SAAgB,kBAA2B;AACzC,QAAO,qBACL,iBACA,qBACA,sBACD"}

package/dist/utils/react/useViewportSize.js CHANGED Viewed

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.169.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.170.0 | Cube Dev Team */
 import { useEffect, useState } from "react";
 //#region src/utils/react/useViewportSize.ts

package/dist/utils/react/wrapNodeIfPlain.js CHANGED Viewed

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.169.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.170.0 | Cube Dev Team */
 import { isValidElement } from "react";
 import { isFragment } from "react-is";

package/dist/utils/selection.js CHANGED Viewed

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.169.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.170.0 | Cube Dev Team */
 //#region src/utils/selection.ts
 /**
 * Deduplicate/toggle keys in a selection: if a key appears twice it is

package/dist/utils/styles.js CHANGED Viewed

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.169.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.170.0 | Cube Dev Team */
 //#region src/utils/styles.ts
 /**
 * Split properties into style and non-style properties.

package/dist/utils/tree.js CHANGED Viewed

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.169.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.170.0 | Cube Dev Team */
 //#region src/utils/tree.ts
 function toFlatTree(tree, includingFolders) {
 	return tree.reduce((result, node) => {

package/dist/utils/warnings.js CHANGED Viewed

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.169.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.170.0 | Cube Dev Team */
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {
 	disabled: "isDisabled",

package/dist/version.js CHANGED Viewed

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.169.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.170.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.169.1";
+const VERSION = "0.170.0";
 const TASTY_VERSION = "3.3.1";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/Colors.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Colors
-Cube UI Kit color tokens are generated by Glaze from a shared OKHST palette. Every adaptive token includes light, dark, and high-contrast variants. Change the active scheme in the Storybook toolbar to review each example.
+Cube UI Kit color tokens are generated by Glaze from a shared OKHST palette. Every adaptive token includes light, dark, and high-contrast variants. Change the active schema in the Storybook toolbar to review each example.
 The colors shown here come from the default seeds. Those seeds — brand hue, saturation, per-status hues — are tunable at runtime; see [Theming](./Theming.md) for a live playground.
@@ -50,7 +50,7 @@ Syntax tokens are calibrated as a group against `#surface`. Use the semantic tok
 ## Borders and shadows
-Borders use the `1bw` design-system width. Shadow geometry comes from `src/tokens/shadows.ts`; the `#shadow-sm`, `#shadow-md`, and `#shadow-lg` colors adapt with the active scheme.
+Borders use the `1bw` design-system width. Shadow geometry comes from `src/tokens/shadows.ts`; the `#shadow-sm`, `#shadow-md`, and `#shadow-lg` colors adapt with the active schema.
 ## Scope

package/docs/Introduction.md CHANGED Viewed

@@ -17,7 +17,7 @@ Cube UI Kit is built on two independent open-source projects:
 - [Tasty](https://tasty.style) is the declarative styling engine. It turns token-aware style objects, responsive values, and component states into conflict-free CSS.
 - [Glaze](https://github.com/tenphi/glaze) generates the semantic color palette. A small set of brand and status seeds resolves into light, dark, and high-contrast token sets.
-Use the [Theme Builder](/story/getting-started-theming--theme-builder) to tune a palette and preview the result across schemes and contrast levels.
+Use the [Theme Builder](/story/getting-started-theming--theme-builder) to tune a palette and preview the result across schemas and contrast levels.
 ## Get started

package/docs/Theming.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Theming
-The whole palette is generated by [Glaze](https://github.com/tenphi/glaze) from a handful of seeds, one per **zone**: the accent, the base, and each of the four status themes. Those seeds are tunable at runtime — change one and every token re-resolves, in light, dark, and high-contrast schemes at once.
+The whole palette is generated by [Glaze](https://github.com/tenphi/glaze) from a handful of seeds, one per **zone**: the accent, the base, and each of the four status themes. Those seeds are tunable at runtime — change one and every token re-resolves, in light, dark, and high-contrast schemas at once.
 Every zone takes the same seed, and it comes in two forms: a **color**, which is usually what you actually have, or the **numbers** behind one. Never both — a zone is seeded one way or the other. See [One seed, two ways to spell it](#one-seed-two-ways-to-spell-it).
@@ -133,7 +133,7 @@ First, **exactness is scoped to the light, normal-contrast variant.** That is th
 Sizing those two the same is a mistake worth naming, because this palette made it. In light `surface` **is** white, so one measurement is both constraints at once and Lc 45 looks right for the pair. In dark the page is near-black and the same number becomes a demand that a filled shape reach text contrast against it — which nothing in the palette meets, the shipped fill included. Since a floor can only lighten, the surplus flattened the dark half of the tone axis onto a single value: every brand darker than the floor came out the same colour. The page floor is now sized for a shape and the label is guaranteed separately, by a cap on the seed's tone.
-They are APCA rather than WCAG on purpose. A single WCAG ratio means two different things depending on the scheme: measured across twelve hues, a fill sitting exactly at 3:1 comes out at Lc 56 in light but only Lc 23 in dark. That is why light brands kept getting crushed while dark ones sailed through the same rule. **A consequence to state plainly: the emitted fill can sit below WCAG 3:1.** `#0EA5E9` renders at 2.77:1 against a white page and is correct there — the Lc is the guarantee, not the ratio.
+They are APCA rather than WCAG on purpose. A single WCAG ratio means two different things depending on the schema: measured across twelve hues, a fill sitting exactly at 3:1 comes out at Lc 56 in light but only Lc 23 in dark. That is why light brands kept getting crushed while dark ones sailed through the same rule. **A consequence to state plainly: the emitted fill can sit below WCAG 3:1.** `#0EA5E9` renders at 2.77:1 against a white page and is correct there — the Lc is the guarantee, not the ratio.
 High contrast does **not** escalate the page floor. It is a request for separation over brand, but not for separation from the page: the same fill carries the label, and driving it off the page drives the label off it. The shipped ladder makes the same trade and lands the other side of it, ending up with _less_ page separation in high contrast than in normal, because it darkens the fill toward its label. What does escalate is the label cap, which searches the high-contrast variants too.
@@ -173,7 +173,7 @@ setPaletteConfig({ surfaceMode: 'tinted', base: { saturation: 25 } });
 Two tones is not a lightness change you would name — it is _room_. Everything below `surface` is positioned relative to it, so the ladder, the borders and the text ramp all follow, and the text's `['AA','AAA']` floors re-solve against the new background rather than drifting. The `code-*` family follows too: its mirrored `surface` exists to be the page, so it tracks both the tone and the base seed.
-**The tinted surfaces move with it.** A status theme's `surface` — and a runtime tint's, from `getColorTheme()` — is authored as an offset from the page's rather than as an absolute tone, and that offset is exactly the two tones `tinted` shifts by. Anchored absolutely they would land on the page's own new tone and a `note` banner would stop reading as a banner at all; anchored to the page they keep the separation the offset was chosen for, in both schemes. They also pick up a little more chroma there, being further from the extreme — so `tinted` makes a status surface easier to see, not harder.
+**The tinted surfaces move with it.** A status theme's `surface` — and a runtime tint's, from `getColorTheme()` — is authored as an offset from the page's rather than as an absolute tone, and that offset is exactly the two tones `tinted` shifts by. Anchored absolutely they would land on the page's own new tone and a `note` banner would stop reading as a banner at all; anchored to the page they keep the separation the offset was chosen for, in both schemas. They also pick up a little more chroma there, being further from the extreme — so `tinted` makes a status surface easier to see, not harder.
 The tint stays subtle by construction. Near white the sRGB gamut has very little chroma to give, so `tinted` buys a surface that reads as warm or cool rather than one that reads as colored — which is the whole ask. For a genuinely colored panel, reach for a status theme's `surface` instead.
@@ -331,7 +331,7 @@ The preview deliberately shows all three surface levels with their own text ramp
 ## Previewing a theme in a region
-`setPaletteConfig()` re-themes the whole document, which is no use for a theme picker — you want several themes visible at once, or a dark preview inside a light page. `renderColorTokens()` does that: it resolves the palette for **one** config and **one** scheme and returns flat literal values, ready to apply to a subtree through a tasty `tokens` prop.
+`setPaletteConfig()` re-themes the whole document, which is no use for a theme picker — you want several themes visible at once, or a dark preview inside a light page. `renderColorTokens()` does that: it resolves the palette for **one** config and **one** schema and returns flat literal values, ready to apply to a subtree through a tasty `tokens` prop.
 ```tsx
 import { renderColorTokens, tasty } from '@cube-dev/ui-kit';
@@ -339,20 +339,20 @@ import { renderColorTokens, tasty } from '@cube-dev/ui-kit';
 const Region = tasty({ styles: { fill: '#surface', color: '#surface-text' } });
 const preview = useMemo(
-  () => renderColorTokens({ accent: { hue: 210 }, scheme: 'dark' }),
+  () => renderColorTokens({ accent: { hue: 210 }, schema: 'dark' }),
   [],
 );
 <Region tokens={preview}>…everything in here renders in that theme…</Region>;
 ```
-The reason this needs its own API: the document palette emits **state maps** (`{ '': …, '@dark': …, '@hc': … }`), so a page can only ever show one scheme at a time — that is what `@dark` means. Collapsing the palette to a chosen scheme removes the conditionality, so several themes can coexist.
+The reason this needs its own API: the document palette emits **state maps** (`{ '': …, '@dark': …, '@hc': … }`), so a page can only ever show one schema at a time — that is what `@dark` means. Collapsing the palette to a chosen schema removes the conditionality, so several themes can coexist.
 | Option | Meaning |
 | --- | --- |
-| every `PaletteConfig` field | merged over the **current** config, so `{ scheme: 'dark' }` previews the active theme in dark |
-| `scheme` | `'light'` (default) or `'dark'` |
-| `highContrast` | resolve that scheme's high-contrast variant. Default `false` |
+| every `PaletteConfig` field | merged over the **current** config, so `{ schema: 'dark' }` previews the active theme in dark |
+| `schema` | `'light'` (default) or `'dark'` |
+| `highContrast` | resolve that schema's high-contrast variant. Default `false` |
 Nothing is applied globally — the live palette and the stored config are untouched, so previews are safe to render anywhere.
@@ -360,10 +360,10 @@ Note the one place the merge/replace split matters: this call **layers** over th
 Notes:
-- Real components work inside a region. Every color in the kit compiles to a CSS custom property, so overriding those properties on one element re-colors its whole subtree with no scheme attribute and no second `<Root>`.
+- Real components work inside a region. Every color in the kit compiles to a CSS custom property, so overriding those properties on one element re-colors its whole subtree with no schema attribute and no second `<Root>`.
 - The legacy aliases come along **by reference** (`'#dark': '#surface-text'`), and so do the shadow tokens and scrollbar colors, whose values embed a palette color. Tasty re-declares them on the region so each `var()` resolves against the region's own values; resolving them up front would freeze them to the outer theme instead.
 - Typography, spacing, sizes and layout are **not** included — nothing in their values references a color, so the region inherits them from `<Root>`.
-- `contrastLevel` works per region, so the whole 0–100 ramp can be shown at once — something a document cannot do, since it is only ever at one level. Level `0` reproduces the normal tier and `100` the high-contrast tier exactly, in both schemes. `highContrast: true` still returns the genuine high-contrast resolution at any level below `100`, because the level moves the baseline and the tier escalates from where `'auto'` would put it; at `100` the two coincide and it returns the same colors as the normal variant. Note that tokens carrying a contrast _floor_ (most text) can sit still over part of the ramp — the floor is solved, not approximated, so the value only moves once the interpolated target does. Tokens positioned by a plain tone pair, like `#border`, step at every level.
+- `contrastLevel` works per region, so the whole 0–100 ramp can be shown at once — something a document cannot do, since it is only ever at one level. Level `0` reproduces the normal tier and `100` the high-contrast tier exactly, in both schemas. `highContrast: true` still returns the genuine high-contrast resolution at any level below `100`, because the level moves the baseline and the tier escalates from where `'auto'` would put it; at `100` the two coincide and it returns the same colors as the normal variant. Note that tokens carrying a contrast _floor_ (most text) can sit still over part of the ramp — the floor is solved, not approximated, so the value only moves once the interpolated target does. Tokens positioned by a plain tone pair, like `#border`, step at every level.
 - Resolving a palette costs a few milliseconds. The last config is memoized, but `useMemo` on the caller side if you drive it from state.
 `renderPaletteTokens()` is the same thing without the aliases and companion tokens, if you want only the Glaze palette.
@@ -395,6 +395,23 @@ subscribePaletteConfig(() => {
 `getPaletteConfig()` always returns the fully resolved form, so `getPaletteConfig().themes.danger.saturation` is a number even if nobody ever set it. `DEFAULT_PALETTE_CONFIG` is the shipped baseline in the same shape.
+## Reading the ambient schema
+The palette config is what the app _asked for_; the schema and contrast tier are what the viewer is _seeing_ — `<html data-schema>` / `prefers-color-scheme`, and `<html data-contrast>` / `prefers-contrast`. They are not part of the config, so `getPaletteConfig()` says nothing about them:
+```tsx
+import { useHighContrast, useSchema } from '@cube-dev/ui-kit';
+const schema = useSchema(); // 'light' | 'dark'
+const isHighContrast = useHighContrast(); // boolean
+```
+Both resolve exactly as the `@dark` / `@hc` states do — attribute opt-in first, media query only when the attribute is absent — and re-render when either input changes. Outside React: `resolveSchema()`, `resolveHighContrast()` and `subscribeSchema(listener)`, which fires on a change to either condition.
+Reach for these only where CSS cannot go. Styling belongs in a state map (`{ '': …, '@dark': …, '@hc': … }`), which repaints on a schema flip with no re-render at all. What the states cannot reach is a surface that takes values rather than CSS — a Vega spec, a CodeMirror or Monaco theme, an iframe — or a control whose value _is_ the condition, like the Light/Dark and Normal/High-contrast selectors over the [theme builder](#theme-builder).
+Note the distinction from `contrastLevel`: the level is a config seed the app supplies and can read back, while high contrast is a viewing condition the document is in. They also pair up — `renderColorTokens({ schema, highContrast })` takes both, so a region can be previewed in the conditions the page is actually showing.
 ## `<Root palette>`
 `<Root>` accepts the same config as a prop, applied during render so the first paint is already correct:
@@ -420,7 +437,7 @@ This is a convenience wrapper over `setPaletteConfig()`, not a separate scope. *
 It also owns the accent's `saturation` outright — pinned to `100`, so a number passed _explicitly alongside_ it is inert and warned about (a number passed on its own turns pastel off instead). And it caps a color seed short of itself: the ceiling sits below where a saturated color lands, so `#EF4444` resolves to `#c47069`. Both are visible in the [Theme builder](#theme-builder), the first as a disabled slider and the second as the requested/resolved chips.
-**Re-seeding costs about 10 ms.** Rebuilding the eight themes and re-solving ~156 tokens across four scheme variants is not free, though it is inside a frame. A manual `contrastLevel` costs the same — it runs the same four passes — except at level `100`, which skips the two high-contrast ones because the normal pass already produced those values. Setting the config to a value it already holds is free — it does not even bump the version. If you are driving it from a slider, let the input coalesce to frames (a pointer-driven `onChange` already does) rather than writing on every event.
+**Re-seeding costs about 10 ms.** Rebuilding the eight themes and re-solving ~156 tokens across four schema variants is not free, though it is inside a frame. A manual `contrastLevel` costs the same — it runs the same four passes — except at level `100`, which skips the two high-contrast ones because the normal pass already produced those values. Setting the config to a value it already holds is free — it does not even bump the version. If you are driving it from a slider, let the input coalesce to frames (a pointer-driven `onChange` already does) rather than writing on every event.
 **If you call Glaze directly, tell the kit.** `glaze.configure({ darkTone })` and friends invalidate Glaze's own caches, but the kit's token maps are memoized against the palette config version:

package/docs/Usage.md CHANGED Viewed

@@ -69,7 +69,7 @@ Defined in `src/tokens/sizes.ts`. Used for component heights and icon sizes.
 ## Shadow Tokens
-Defined in `src/tokens/shadows.ts`. Shadow colors (`#shadow-sm`, `#shadow-md`, `#shadow-lg`) are generated by Glaze and adapt automatically to dark / high-contrast schemes.
+Defined in `src/tokens/shadows.ts`. Shadow colors (`#shadow-sm`, `#shadow-md`, `#shadow-lg`) are generated by Glaze and adapt automatically to dark / high-contrast schemas.
 | Token            | Value                     |
 | ---------------- | ------------------------- |
@@ -92,26 +92,41 @@ Defined in `src/tokens/layout.ts`.
 All color tokens use `#name` syntax in styles. Opacity variants use `#name.NN` (e.g. `#surface-text.06` for 6% opacity).
-The palette is generated by [`@tenphi/glaze`](https://github.com/tenphi/glaze) (see `src/tokens/palette.ts`). Every color token is emitted as a state map with `light`, `@dark`, and `@hc` (high-contrast) variants, so the entire UI Kit adapts to dark / high-contrast schemes automatically.
+The palette is generated by [`@tenphi/glaze`](https://github.com/tenphi/glaze) (see `src/tokens/palette.ts`). Every color token is emitted as a state map with `light`, `@dark`, and `@hc` (high-contrast) variants, so the entire UI Kit adapts to dark / high-contrast schemas automatically.
 The seeds it is generated from — brand hue, saturation, per-status hues, `pastel`, `contrastLevel` — are tunable at runtime. See [Theming](./Theming.md).
-### Color Schemes
+### Color Schemas
 The `@dark` and `@hc` predefined states are wired up in `src/components/Root.tsx` to support both an attribute opt-in and the user's system preference:
 ```html
-<!-- Force dark scheme -->
+<!-- Force dark schema -->
 <html data-schema="dark">
-<!-- Force high-contrast scheme -->
+<!-- Force high-contrast schema -->
 <html data-contrast="high">
 <!-- Both can be combined -->
 <html data-schema="dark" data-contrast="high">
 ```
-When the attribute is absent, the scheme falls back to `@media (prefers-color-scheme: dark)` and `@media (prefers-contrast: more)`.
+When the attribute is absent, the schema falls back to `@media (prefers-color-scheme: dark)` and `@media (prefers-contrast: more)`.
+#### Reading the schema from JS
+For styling, use the state map — `{ '': light, '@dark': dark, '@hc': hc }`. Two cases it cannot serve: a surface the stylesheet never reaches (a Vega spec, a CodeMirror / Monaco theme, an iframe), and a control whose value _is_ the ambient condition (a Light/Dark preview selector). For those, read the same two conditions from JS:
+```tsx
+import { useHighContrast, useSchema } from '@cube-dev/ui-kit';
+const schema = useSchema(); // 'light' | 'dark' — the JS answer to `@dark`
+const isHighContrast = useHighContrast(); // boolean — the JS answer to `@hc`
+```
+Both follow the attribute opt-in first and the media query second, exactly as the states do, and re-render when either changes. Outside React: `resolveSchema()`, `resolveHighContrast()` and `subscribeSchema(listener)` (fires on either condition; re-read in the listener). This is the conditions half of the gap [`resolveTokenValue()`](#resolving-tokens-outside-css) closes for token _values_.
+Root-level only — there is no element-scoped or generic state reader, on purpose. Tasty's state vocabulary mixes element-local states (`hovered`, `pressed`, `disabled`) with ambient ones (`@media(…)`, `@root(…)`), and only the ambient half is answerable without an element.
 ### Surface & Text Vocabulary
@@ -154,7 +169,7 @@ Tokens a **container** sets to steer a component that cannot resolve the color o
 ```jsx
 <Block fill="#fixed-dark" color="#white" styles={{ '#current-fill': '#fixed-dark' }}>
-  <Button theme="current" type="primary">Legible in both schemes</Button>
+  <Button theme="current" type="primary">Legible in both schemas</Button>
 </Block>
 ```
@@ -162,7 +177,7 @@ Setting it moves the label, the icon slots and the chip's rim together. It also
 ### Accent System
-Each themed color (default, primary, success, danger, warning, note) provides an `accent-*` family anchored to a fixed white "accent surface text". These tokens stay recognizable across schemes (used for branded buttons, CTAs, etc.):
+Each themed color (default, primary, success, danger, warning, note) provides an `accent-*` family anchored to a fixed white "accent surface text". These tokens stay recognizable across schemas (used for branded buttons, CTAs, etc.):
 | Token (default theme; prefixed in others) | Role |
 | --- | --- |
@@ -203,10 +218,10 @@ resetPaletteConfig();
 Also available: `getPaletteConfig()`, `subscribePaletteConfig()`, the `usePaletteConfig()` hook, a `<Root palette={…}>` prop, `DEFAULT_PALETTE_CONFIG`, and `invalidatePaletteTokens()` for when you drive `glaze.configure(...)` yourself after mount. The palette is process-global — one palette per process, not per tree or per request.
-To theme a _region_ instead of the document — a theme preview, or a dark panel inside a light page — use `renderColorTokens()`. It resolves one config and one scheme to flat values you apply via a `tokens` prop, without touching the live palette:
+To theme a _region_ instead of the document — a theme preview, or a dark panel inside a light page — use `renderColorTokens()`. It resolves one config and one schema to flat values you apply via a `tokens` prop, without touching the live palette:
 ```tsx
-<Block tokens={renderColorTokens({ accent: { hue: 210 }, scheme: 'dark' })} fill="#surface">
+<Block tokens={renderColorTokens({ accent: { hue: 210 }, schema: 'dark' })} fill="#surface">
   …
 </Block>
 ```
@@ -325,7 +340,9 @@ resolveTokenValues(['#surface', '#surface-text', '#border']); // keyed by the to
 resolvePresetValues('s3'); // { fontFamily: 'ui-monospace, …', fontSize: '14px', lineHeight: '20px', … }
 ```
-`useTokenValue()`, `useTokenValues()` and `usePresetValues()` are the same three readers as hooks, re-resolved whenever the palette is re-seeded or the scheme / contrast tier flips. The object `useTokenValues()` returns keeps its identity while the values do, so it is safe as a dependency of the theme object built from it.
+`useTokenValue()`, `useTokenValues()` and `usePresetValues()` are the same three readers as hooks, re-resolved whenever the palette is re-seeded or the schema / contrast tier flips. The object `useTokenValues()` returns keeps its identity while the values do, so it is safe as a dependency of the theme object built from it.
+These resolve token _values_. For the ambient _conditions_ themselves — which schema and contrast tier the document is in — see [Reading the schema from JS](#reading-the-schema-from-js).
 So these helpers do not inspect the value. They read `$tokens-applied`, a marker the token block declares alongside the tokens, which answers the question that matters — _are the kit's tokens in effect on this element?_ Off that surface every read returns `null` (or `fallback`) and warns once in development; on it, the computed value is taken as the truth.

package/docs/components/content/ItemCard.md CHANGED Viewed

@@ -55,7 +55,7 @@ Inherits all styling from `Item`. See [Item documentation](./Item.md) for sub-el
 ### Themes
-Use the `theme` prop to apply a semantic color scheme:
+Use the `theme` prop to apply a semantic color schema:
 - `default` — Standard card appearance
 - `success` — Green theme for positive outcomes

package/docs/components/content/PrismCode.md CHANGED Viewed

@@ -28,7 +28,7 @@ Supports [Base properties](../../BaseProperties.md).
 ## Theme
-Syntax colors are driven by a dedicated, scheme-aware palette of `code-*` tokens. Each token uses a different hue so token classes stay visually separable, and every token meets at least **WCAG AA (4.5:1)** contrast against `#surface` in light, dark, and high-contrast schemes (AAA in HC).
+Syntax colors are driven by a dedicated, schema-aware palette of `code-*` tokens. Each token uses a different hue so token classes stay visually separable, and every token meets at least **WCAG AA (4.5:1)** contrast against `#surface` in light, dark, and high-contrast schemas (AAA in HC).
 | Token | Hue | Used for |
 | --- | --- | --- |
@@ -40,7 +40,7 @@ Syntax colors are driven by a dedicated, scheme-aware palette of `code-*` tokens
 | `#code-function` | pink | functions, class names, regex, variables |
 | `#code-attribute` | cyan | attribute names, properties, selectors, built-ins, keys |
-Diff insertion (`+`) and deletion (`-`) intentionally re-use the existing `#success-*` / `#danger-*` ramps — both the line background tint and the foreground color adapt to the active scheme.
+Diff insertion (`+`) and deletion (`-`) intentionally re-use the existing `#success-*` / `#danger-*` ramps — both the line background tint and the foreground color adapt to the active schema.
 ## Examples

package/docs/components/data/DataTable.md CHANGED Viewed

@@ -371,7 +371,7 @@ A stale order is safe: keys for columns that no longer exist are ignored, and a
 `column.color` tints a whole column — header, cells and pinned totals. It takes a palette theme name, any CSS color, a `{ hue, saturation }` seed, or a `{ fill, text }` pair for full manual control.
-Every form but the last is _derived_: only the hue and saturation are kept, and the tone ramp plus an AA/AAA text floor are re-solved for light, dark and high-contrast. A column cannot end up unreadable in a scheme nobody checked.
+Every form but the last is _derived_: only the hue and saturation are kept, and the tone ramp plus an AA/AAA text floor are re-solved for light, dark and high-contrast. A column cannot end up unreadable in a schema nobody checked.
 ```tsx
 const columns = [

package/docs/components/fields/Picker.md CHANGED Viewed

@@ -310,7 +310,7 @@ The trigger button supports various visual styles via the `type` prop:
 ### Trigger Button Themes
-Control the color scheme with the `theme` prop:
+Control the color schema with the `theme` prop:
 - **`default`** — Standard theme (default)
 - **`danger`** — Red/destructive color (also applied automatically when `isInvalid` is set)