@cube-dev/ui-kit 0.163.0 → 0.165.0

package/dist/tokens/palette-config.d.ts

@@ -1,94 +1,255 @@
 
 //#region src/tokens/palette-config.d.ts
-/** Hue / saturation seed override for one colored theme. */
-interface PaletteThemeSeed {
+/**
+ * Ceiling on a base saturation derived from a {@link PaletteConfig.base} color.
+ *
+ * A named base color lands the chrome near itself rather than at the 12% share the
+ * accent lends it, which is the whole reason to name one — but a fully saturated
+ * chrome stops being chrome. `50` is well past where the base colors begin to
+ * converge (`surface-inverse` tops out around `25`), so the clip costs nothing that
+ * was still moving and stops a vivid brand hex from being read as an instruction to
+ * paint the page with it.
+ *
+ * The manual slider in the tuner shares the number, so the two agree on what the top
+ * of the range means.
+ */
+declare const MAX_BASE_SATURATION = 50;
+/** The numeric arm of a {@link PaletteSeed}. */
+interface PaletteNumericSeed {
   /** Hue in degrees (0–360). */
   hue?: number;
-  /** Saturation (0–100). Defaults to the palette-level `saturation`. */
+  /** Saturation (0–100). */
   saturation?: number;
 }
+/**
+ * One zone's seed: a **color**, or the **numbers**.
+ *
+ * A string is a color — anything Glaze parses: hex, `rgb()`, `hsl()`, `okhsl()`,
+ * `okhst()`, `oklch()`. CSS color keywords (`rebeccapurple`) are not supported, and an
+ * unparseable value warns once and falls back to the numeric path with nothing pinned.
+ *
+ * The union **is** the exclusivity. A zone is seeded one way or the other — never both,
+ * never layered — so there is no precedence rule to learn and no contradiction to warn
+ * about. It also means a patch that switches form *replaces* rather than merges; layering
+ * happens within a path. See {@link resolvePaletteConfig}.
+ *
+ * What a color supplies differs by zone, and each zone's own field says so:
+ * {@link PaletteConfig.accent} keeps the tone but lends the palette none of its chroma,
+ * {@link PaletteConfig.base} discards the tone, and a status theme keeps the tone *and*
+ * takes the chroma as its seed.
+ */
+type PaletteSeed = string | PaletteNumericSeed;
 /**
  * The `code-*` syntax family takes a saturation and nothing else — and answers to
  * nothing else either. This is the one knob that moves it.
  *
  * Its hues are absolute literals by design, so syntax colors never rotate with the
- * brand — strings would collide with numbers the moment the brand went green. Unlike
- * every other theme, its saturation does **not** inherit the palette-level one: the
- * code palette is calibrated once and stays there, so re-seeding the app cannot
- * quietly wash out a code block. {@link PaletteConfig.pastel} skips it for the same
- * reason.
+ * brand — strings would collide with numbers the moment the brand went green, which is
+ * also why it is not a {@link PaletteSeed} and cannot take a color. Unlike every other
+ * theme, its saturation does **not** inherit the palette-level one: the code palette is
+ * calibrated once and stays there, so re-seeding the app cannot quietly wash out a code
+ * block. {@link PaletteConfig.pastel} skips it for the same reason.
  */
 interface PaletteCodeSeed {
-  /** Saturation (0–100). Defaults to {@link DEFAULT_CODE_SATURATION}, not to `saturation`. */
+  /** Saturation (0–100). Defaults to {@link DEFAULT_CODE_SATURATION}, not to the accent's. */
   saturation?: number;
 }
+/**
+ * Where the neutral surface ramp sits on the tone scale — see
+ * {@link PaletteConfig.surfaceMode}.
+ */
+type SurfaceMode = 'neutral' | 'tinted';
 /** Names of the themes whose seeds can be overridden individually. */
 type PaletteThemeName = 'success' | 'danger' | 'warning' | 'note' | 'code';
 /**
- * Palette tuning. Every field is optional; omitted fields keep their default,
- * and per-theme fields left unset inherit the palette-level value.
+ * Palette tuning. Every field is optional; omitted fields keep their default, and
+ * per-theme fields left unset inherit the palette-level value.
+ *
+ * Every zone takes the same {@link PaletteSeed} — a color or the numbers — so the whole
+ * config is one idea spelled once, and a settings UI can drive all six zones with one
+ * control.
  */
 interface PaletteConfig {
   /**
-   * Accent hue in degrees (0–360) — the brand.
+   * The **accent** zone — the brand. Drives the `accent-*` family on every theme,
+   * `primary` / `purple` / `special`, and the brand-tinted odds and ends (`focus`, the
+   * loading faces, the disabled chip). Its hue is also the default for
+   * {@link PaletteConfig.base}, and its saturation the default every status theme
+   * inherits.
+   *
+   * **As numbers** — `{ hue, saturation }`. One saturation scale for the whole theme, by
+   * design: every color's own `saturation` is a 0–1 factor of this seed — `surface` at
+   * 0.12, `border` at 0.175, the text ramp at 0.2, the accent family at ~1.0 — so moving
+   * it rescales the palette while keeping those proportions. Unlike hue, which is
+   * configured separately for the brand and for each status theme, saturation is
+   * deliberately not split: the ratio between a subtle surface tint and a saturated
+   * accent is part of the design.
+   *
+   * A `saturation` **belongs to the non-pastel path**, and writing one says so: with no
+   * {@link PaletteConfig.pastel} beside it, it turns pastel off, because tuning a
+   * saturation is the non-pastel path by definition. Pastel is one flat chroma ceiling,
+   * so under it there is exactly one seed and it is the top of the scale. A
+   * `pastel: true` written next to a saturation wins and the saturation is ignored (with
+   * a dev warning) — but it is kept rather than dropped, so turning pastel back off
+   * restores your number.
+   *
+   * **As a color** — the brand, as you have it. Unlike a
+   * {@link PaletteConfig.base} color, which keeps only hue and saturation, this keeps
+   * the **tone** as well — which is the whole point. Without it the brand fill is
+   * authored as a fixed tone step off white, so every accent hue lands at roughly the
+   * same lightness and the color you asked for never actually appears.
    *
-   * Drives the `accent-*` family on every theme, `primary` / `purple` / `special`,
-   * and the brand-tinted odds and ends (`focus`, the loading faces, the disabled
-   * chip). Also the default for {@link PaletteConfig.baseHue}.
+   * The **light, normal-contrast** variant reproduces the color; dark and high contrast
+   * adapt, as every other color in the palette does. Two things cost exactness even
+   * there: {@link PaletteConfig.pastel} caps chroma (so `#FFD400` softens), and the fill
+   * answers to two APCA floors of deliberately different sizes — **Lc 45 against the
+   * white label** it carries, because a label is text, and only **Lc 25 against
+   * `surface`**, because a fill is a shape. It moves as far as the nearer one requires
+   * and no further.
+   *
+   * Those floors are APCA, not WCAG, and the difference is deliberate: one WCAG ratio
+   * means two very different things by scheme (3:1 measures Lc 56 in light but only
+   * Lc 23 in dark), which crushed light brands while letting dark ones through. A
+   * consequence worth stating plainly — **the emitted fill can sit below WCAG 3:1**.
+   * `#0EA5E9` renders at 2.77:1 against a white page and is correct at that value; the
+   * Lc is the guarantee, not the ratio.
+   *
+   * A color's own chroma is **not** adopted as the zone's seed saturation, which stays at
+   * its default. The accent family gets the chroma through Glaze's `from`, where it is
+   * absolute and seed-independent, and leaving the seed alone is what keeps a saturated
+   * brand out of every status theme that inherits it. A status theme's color behaves the
+   * other way round for the same reason inverted — nothing inherits from a status theme.
    */
-  hue?: number;
+  accent?: PaletteSeed;
   /**
-   * Hue of the **base** zone in degrees (0–360): the neutral chrome — `surface`
-   * and its ladder, the `surface-text*` ramp, `border`, `placeholder`. Defaults to
-   * `hue`, so the chrome carries a faint tint of the brand unless you say otherwise.
-   *
-   * Splitting it lets the chrome sit on a different hue from the accent — a warm
-   * grey UI with a cool blue brand, say. Only the `default` theme is affected: a
-   * colored theme's tinted `surface` deliberately follows *its own* hue, because a
-   * danger banner should read as red.
+   * The **base** zone: the neutral chrome — `surface` and its ladder, the
+   * `surface-text*` ramp, `border`, `placeholder`.
+   *
+   * **Omit it and the zone follows the accent** — the chrome carries a faint tint of the
+   * brand, at {@link SURFACE_SATURATION_SHARE} of its chroma, unless you say otherwise.
+   * That is the third state, and the reason this field is worth reading back from
+   * {@link getPaletteConfigInput}: absent, an object, or a string are three different
+   * answers to "does the chrome have a seed of its own".
+   *
+   * **As numbers** — `{ hue, saturation }`, each independently optional. Splitting the
+   * hue off lets the chrome sit on a different one from the accent — a warm grey UI with
+   * a cool blue brand, say. Only the `default` theme is affected: a colored theme's
+   * tinted `surface` deliberately follows *its own* hue, because a danger banner should
+   * read as red.
+   *
+   * The saturation is on the same 0–100 scale as the accent's, and read the same way.
+   * **The shipped chrome is `12`** — a faint tint is what a neutral surface is — so the
+   * useful range is mostly below a third, and the numbers above it are a deliberately
+   * tinted theme rather than a neutral one. Set it and the base zone stops following the
+   * brand: a vivid accent over near-grey chrome, or a muted accent over visibly warm
+   * chrome, are both one number away and neither is reachable from a single scale.
+   *
+   * The base colors keep their proportions to one another — `border` more than `surface`,
+   * the text ramp more than `border` — until the highest of them hits the top of the
+   * scale, which happens around `25`. Past that they converge.
+   *
+   * Under {@link PaletteConfig.surfaceMode} `'neutral'` it reaches `surface-2`…
+   * `surface-4`, `border`, `placeholder` and the text ramp, but not the page surface: at
+   * the end of the tone scale there is no room for chroma, whatever the seed says.
+   * `'tinted'` is what gives it somewhere to land.
+   *
+   * **As a color** — its **hue and saturation** are read; its **tone is discarded**,
+   * because the chrome's lightness ladder is the design. A base color says which way the
+   * greys lean and how far, not how dark they are.
+   *
+   * The saturation is clipped to {@link MAX_BASE_SATURATION}. Naming a base color says
+   * "the chrome is this color", so it lands near it rather than at the share it would
+   * inherit from the accent — but a fully saturated chrome is no longer chrome, so there
+   * is a ceiling on how far "near" goes.
+   *
+   * Unlike the accent's, writing a base saturation does *not* turn pastel off: how much
+   * hue the chrome carries says nothing about which chroma space the palette is in.
    */
-  baseHue?: number;
+  base?: PaletteSeed;
   /**
-   * Seed saturation (0–100), and the fallback for every theme that does not set
-   * its own.
-   *
-   * One scale for the whole theme, by design. Every color's own `saturation` is a
-   * 0–1 factor of this seed — `surface` at 0.12, `border` at 0.175, the text ramp
-   * at 0.2, the accent family at ~1.0 — so moving it rescales the palette while
-   * keeping those proportions. Unlike hue, which is configured separately for the
-   * brand and for each status theme, saturation is deliberately not split: the
-   * ratio between a subtle surface tint and a saturated accent is part of the
-   * design.
+   * Global. Where the neutral surface ramp sits on the tone scale.
+   *
+   * - `'neutral'` — `surface` is the extreme: pure white in light, the darkest
+   *   step the dark tone window allows in dark. No room for chroma, so the page
+   *   carries no hue however saturated the base zone is.
+   * - `'tinted'` — the whole ramp moves two tones inward, off the extreme.
+   *
+   * Two tones is not a visible lightness change; what it buys is *room*. Chroma
+   * needs distance from white to exist at all, so at the extreme a light page is
+   * white no matter what the base saturation says. Tinted trades two tones of
+   * headroom for a page that actually carries its base hue.
+   *
+   * Everything below `surface` is positioned relative to it, so the ladder, the
+   * borders and the text ramp all follow — and the contrast floors on the text
+   * re-solve against the new background rather than drifting.
    */
-  saturation?: number;
+  surfaceMode?: SurfaceMode;
   /**
    * Global. Widens the usable chroma range by relaxing the sRGB-safe limit,
    * producing a softer, more even palette across hues. Glaze treats `pastel` as
    * instance-level, so it is threaded into every theme.
    *
-   * Every theme except `code`. The syntax family is calibrated on its own
-   * saturation and is deliberately left out — softening it collapses the chroma
-   * spread the syntax hues rely on to stay apart. To soften a code block, lower
+   * It also **pins the accent's saturation to 100**: the even, hue-independent ceiling
+   * is what pastel is for, and a second saturation scale on top of it would only undo
+   * that. Two paths, then — pastel with no saturation knob, or `pastel: false` with a
+   * free 0–100 one.
+   *
+   * Which is why a lone `accent: { saturation }` picks the second path for you. State
+   * this field only to override that: it is the coarser of the two choices, so it wins
+   * wherever both are set, and a saturation it shadows is ignored with a dev warning.
+   *
+   * The same ceiling is why a color seed cannot render exactly under pastel — `#FFD400`
+   * softens to `#e4d8ad`. Under pastel a color contributes its hue and its tone; turn
+   * pastel off to get its chroma too.
+   *
+   * Every theme except `code`. The syntax family is calibrated on its own saturation and
+   * is deliberately left out — softening it collapses the chroma spread the syntax hues
+   * rely on to stay apart. To soften a code block, lower
    * {@link PaletteCodeSeed.saturation} instead.
    */
   pastel?: boolean;
   /**
-   * Global. `'auto'` (the default) keeps the two-tier model: normal colors plus
-   * a separate high-contrast tier driven by `<html data-contrast="high">` /
-   * `prefers-contrast: more`.
-   *
-   * A number (0–100) replaces that switch with a slider — and, because a manual
-   * level already carries the contrast preference, **drops the high-contrast
-   * tier entirely**. `0` reproduces the normal output and `100` the
-   * high-contrast output, bit for bit.
+   * Global. `'auto'` (the default) leaves contrast entirely to the two-tier model:
+   * normal colors plus a high-contrast tier driven by `<html data-contrast="high">`
+   * / `prefers-contrast: more`.
+   *
+   * A number (0–100) additionally positions the **normal** colors on a slider, so
+   * a product can offer its own contrast control. `0` is the shipped palette and
+   * `100` is the high-contrast one, bit for bit.
+   *
+   * The two **compose** rather than replace each other: the high-contrast tier
+   * stays the true high-contrast resolution at every level — identical to what
+   * `'auto'` emits — so a slider raises the baseline while
+   * `prefers-contrast: more` still escalates on top of it. The one exception is
+   * `100`, where the normal colors already *are* the high-contrast ones and a
+   * second tier would only duplicate them.
    */
   contrastLevel?: number | 'auto';
-  /** Per-theme seed overrides. */
+  /**
+   * Per-theme seed overrides. Each status theme takes the same {@link PaletteSeed} the
+   * accent zone does, and inherits the accent's saturation until it sets its own.
+   *
+   * **As numbers** — `{ hue, saturation }`. Status hues have to stay semantically
+   * legible (danger red, warning amber, success green) and far enough apart from each
+   * other and from the brand to read as different things.
+   *
+   * **As a color** — the theme's accent family becomes that color, on the same terms
+   * {@link PaletteConfig.accent} sets: the light/normal-contrast variant reproduces it,
+   * the softened APCA floors apply instead of the white-anchored ladder's WCAG ones, and
+   * the tone is capped so the `#white` label every `type="primary"` item paints on the
+   * fill survives.
+   *
+   * Here the color's chroma **does** become the theme's seed saturation, unlike the
+   * accent's. Nothing inherits from a status theme, so there is nothing to
+   * re-chromatize — and it is what keeps the theme's tinted banner surface, border and
+   * text ramp at their shipped proportions to the fill instead of drifting relative to
+   * it.
+   */
   themes?: {
-    success?: PaletteThemeSeed;
-    danger?: PaletteThemeSeed;
-    warning?: PaletteThemeSeed;
-    note?: PaletteThemeSeed;
+    success?: PaletteSeed;
+    danger?: PaletteSeed;
+    warning?: PaletteSeed;
+    note?: PaletteSeed;
     code?: PaletteCodeSeed;
   };
 }
@@ -97,30 +258,95 @@ interface ResolvedPaletteConfig {
   hue: number;
   baseHue: number;
   saturation: number;
+  baseSaturation: number;
+  surfaceMode: SurfaceMode;
+  /**
+   * The accent color as given, handed to Glaze's `from` so the brand family renders
+   * as that literal value rather than as a shade re-derived from the seed.
+   *
+   * `null` — the common case — means no accent color was supplied and the family keeps
+   * its white-anchored derivation, which is the only arrangement that reproduces the
+   * shipped palette bit for bit.
+   */
+  accentColor: string | null;
+  /**
+   * The base color as given, or `null`.
+   *
+   * Nothing renders from it — the hue and the saturation it derives are what reach the
+   * palette. It is resolved anyway so {@link isSameConfig} can compare it, which is the
+   * only way a write that changes the *string* without changing either derived number
+   * still counts as a change. `MAX_BASE_SATURATION` makes that a live case rather than
+   * a theoretical one: every color above the clip on a given hue derives the same pair,
+   * so without this a color picker's whole upper range — and its entire tone axis, which
+   * a base color discards — would drop writes silently and leave the field stale.
+   */
+  baseColor: string | null;
+  /**
+   * The tone of {@link ResolvedPaletteConfig.accentColor}, or `null` alongside it.
+   *
+   * `from` carries the tone itself, so this exists for the one thing that needs the
+   * *number*: the hover brand text sits a fixed tone step past the rest one, and a
+   * step has to be computed.
+   */
+  accentTone: number | null;
+  /**
+   * The saturation of {@link ResolvedPaletteConfig.accentColor}, or `null` beside it.
+   *
+   * On the palette's 0–100 scale, like every other saturation here — and deliberately
+   * *not* the same number as {@link ResolvedPaletteConfig.saturation}, which a color
+   * never raises. The accent family gets this chroma through Glaze's `from`, where it is
+   * absolute; the seed stays where it was so the status themes that inherit it are left
+   * alone.
+   *
+   * Kept as a number because the accent seed is rebuilt from its three components rather
+   * than handed over as the literal: the tone is capped so a white label survives on the
+   * fill, and a capped tone means reconstructing the color anyway.
+   */
+  accentSaturation: number | null;
   pastel: boolean;
   contrastLevel: number | 'auto';
   themes: {
-    success: {
-      hue: number;
-      saturation: number;
-    };
-    danger: {
-      hue: number;
-      saturation: number;
-    };
-    warning: {
-      hue: number;
-      saturation: number;
-    };
-    note: {
-      hue: number;
-      saturation: number;
-    };
+    success: ResolvedThemeSeed;
+    danger: ResolvedThemeSeed;
+    warning: ResolvedThemeSeed;
+    note: ResolvedThemeSeed;
     code: {
       saturation: number;
     };
   };
 }
+/** One status theme's seed, resolved. */
+interface ResolvedThemeSeed {
+  hue: number;
+  /**
+   * The theme's Glaze seed, and a ceiling on every color in it.
+   *
+   * On the numeric path this inherits the accent's saturation until the theme pins its
+   * own. On the color path it **is** the color's chroma, which is what keeps the theme's
+   * tinted surface, border and text ramp at their shipped proportions to a fill whose
+   * chroma arrives absolute through `from`. See {@link PaletteConfig.themes} for why the
+   * accent zone does the opposite.
+   */
+  saturation: number;
+  /**
+   * The color as given, handed to Glaze's `from` so this theme's accent family renders
+   * as that literal value rather than as a shade re-derived from the seed.
+   *
+   * `null` — the common case — means the theme is on the numeric path and its accent
+   * family keeps the white-anchored derivation, which is the only arrangement that
+   * reproduces the shipped palette bit for bit.
+   */
+  color: string | null;
+  /**
+   * The tone of {@link ResolvedThemeSeed.color}, or `null` alongside it.
+   *
+   * `from` carries the tone itself, so this exists for the two things that need the
+   * *number*: the hover brand text sits a fixed tone step past the rest one, and the
+   * tone is capped so the `#white` label a `type="primary"` item paints on the fill
+   * survives. Both are arithmetic, and neither can be done to a string.
+   */
+  colorTone: number | null;
+}
 /**
  * The palette as it ships, with no tuning applied. Frozen — it is the baseline
  * every resolution falls back to, so a stray write to it would move the defaults
@@ -136,8 +362,8 @@ declare const DEFAULT_PALETTE_CONFIG: ResolvedPaletteConfig;
  * object, and re-applying the same object twice is the same as applying it once.
  *
  * ```ts
- * setPaletteConfig({ hue: 200, baseHue: 60 });
- * setPaletteConfig({ hue: 200 }); // baseHue is gone — back to inheriting `hue`
+ * setPaletteConfig({ accent: { hue: 200 }, base: { hue: 60 } });
+ * setPaletteConfig({ accent: { hue: 200 } }); // `base` is gone — follows accent again
  * ```
  *
  * To adjust one field of the config already in place — a slider in a settings UI —
@@ -145,7 +371,7 @@ declare const DEFAULT_PALETTE_CONFIG: ResolvedPaletteConfig;
  * preserves which fields are pinned and which still inherit:
  *
  * ```ts
- * setPaletteConfig((config) => ({ ...config, hue: 200 }));
+ * setPaletteConfig((config) => ({ ...config, accent: { hue: 200 } }));
  * ```
  *
  * The palette is rebuilt lazily on the next token read, and any mounted `<Root>`
@@ -178,10 +404,10 @@ declare function getPaletteConfig(): ResolvedPaletteConfig;
  * to offer a way back:
  *
  * ```ts
- * const pinned = getPaletteConfigInput().baseHue !== undefined;
+ * const own = getPaletteConfigInput().base !== undefined;
  *
  * // Re-link it to the brand by dropping the field.
- * setPaletteConfig(({ baseHue, ...config }) => config);
+ * setPaletteConfig(({ base, ...config }) => config);
  * ```
  *
  * It is also the value handed to a {@link setPaletteConfig} updater.
@@ -213,17 +439,18 @@ declare function usePaletteVersion(): number;
  *
  * <HueSlider
  *   value={palette.hue}
- *   onChange={(hue) => setPalette((config) => ({ ...config, hue }))}
+ *   onChange={(hue) => setPalette((config) => ({ ...config, accent: { hue } }))}
  * />
  * ```
  *
- * The first element is the *resolved* config, so `palette.hue` is always a number.
- * The updater's argument is the sparse one — see {@link getPaletteConfigInput}.
+ * The first element is the *resolved* config, so `palette.hue` is always a number — it
+ * keeps the flat shape the recipe reads, whichever way the zones were seeded. The
+ * updater's argument is the sparse one — see {@link getPaletteConfigInput}.
  *
  * The config is global process state, so every consumer of this hook — and every
  * mounted `<Root>` — sees the same palette.
  */
 declare function usePaletteConfig(): readonly [ResolvedPaletteConfig, typeof setPaletteConfig];
 //#endregion
-export { DEFAULT_PALETTE_CONFIG, PaletteCodeSeed, PaletteConfig, PaletteThemeName, PaletteThemeSeed, ResolvedPaletteConfig, getPaletteConfig, getPaletteConfigInput, invalidatePaletteTokens, resetPaletteConfig, resolvePaletteConfig, setPaletteConfig, subscribePaletteConfig, usePaletteConfig, usePaletteVersion };
+export { DEFAULT_PALETTE_CONFIG, MAX_BASE_SATURATION, PaletteCodeSeed, PaletteConfig, PaletteNumericSeed, PaletteSeed, PaletteThemeName, ResolvedPaletteConfig, ResolvedThemeSeed, SurfaceMode, getPaletteConfig, getPaletteConfigInput, invalidatePaletteTokens, resetPaletteConfig, resolvePaletteConfig, setPaletteConfig, subscribePaletteConfig, usePaletteConfig, usePaletteVersion };
 //# sourceMappingURL=palette-config.d.ts.map