@epilot/spark-ui 0.11.1 → 0.12.1

package/dist/lib/accent-theme.d.cts

@@ -1,7 +1,7 @@
 "use client";
 
-import { o as SparkNeutral } from "../theme-types-1yB0d8mp.cjs";
-import { t as generateRadixColors } from "../generate-radix-colors-Bw-RYaV4.cjs";
+import { c as SparkNeutralFamily, s as SparkNeutral } from "../theme-types-Bn5E15-P.cjs";
+import { t as generateRadixColors } from "../generate-radix-colors-BY4Wjsm7.cjs";
 
 //#region src/lib/accent-theme.d.ts
 /** Shape returned by the vendored Radix generator (it doesn't export a named type). */
@@ -29,8 +29,13 @@ interface GenerateScaleOptions {
    * must match what's actually painted or the alpha ramp renders wrong.
    */
   background?: string;
-  /** Neutral family to regenerate against `background`. Pass a resolved family, not `'auto'`. */
-  neutral?: Exclude<SparkNeutral, 'auto'>;
+  /**
+   * Neutral family, or an arbitrary color to seed the neutral scale (regenerated against
+   * `background`, same as a named family). Pass a resolved value, not `'auto'` — this
+   * option isn't itself typed to exclude it (an open string union can't forbid one
+   * literal), but nothing in `<Theme>` ever forwards `'auto'` this far.
+   */
+  neutral?: SparkNeutral;
 }
 /** Which appearance a canvas belongs to, by OKLCH lightness. */
 declare function appearanceForBackground(background: string): Appearance;
@@ -41,7 +46,71 @@ declare function accentSparkVars(scale: SparkAccentScale): string[];
 /** Wide-gamut (P3) `--spark-*` declarations — for a `color-gamut: p3` `@supports` block. */
 declare function accentSparkVarsP3(scale: SparkAccentScale): string[];
 /** Radix's "auto" gray: curated names use Radix's table; a custom hex is classified by OKLCH hue. */
-declare function getMatchingNeutral(accent: string): Exclude<SparkNeutral, 'auto'>;
+declare function getMatchingNeutral(accent: string): SparkNeutralFamily;
+/**
+ * Re-cast a scale for use ON its own solid (step-9) fill — the `inverted` knob.
+ *
+ * A solid accent control on a solid accent surface is invisible: both paint `--spark-9`.
+ * Inverting swaps that pair — step 9 and its contrast ink trade places — so the solid fill
+ * and its text are contrast-safe **by construction, for any accent**: `accentContrast` is
+ * already the WCAG-checked readable ink for step 9 (`readableContrast`).
+ *
+ * The non-solid styles need a second idea, because the ink is also the text colour. A fill
+ * blended surface→ink moves the background *toward* the foreground, so ink-on-fill contrast
+ * falls monotonically with `t` — and measured across the curated set, the highest `t` that
+ * still clears 4.5:1 (0.174) sits below the lowest `t` that is 3:1 distinguishable from the
+ * surface (0.543). On that line no fill can be both legible and visible, on any accent.
+ *
+ * So fills blend the other way, toward the **scrim** — the lightness pole opposite the ink,
+ * carrying the surface's own hue. Contrast against the ink now *rises* with `t`, which puts
+ * every non-solid style at or above the solid pair's ratio for free. Borders keep stepping
+ * toward the ink (a scrim-side border caps at ~2:1 on light accents like orange, so it can
+ * never clear 1.4.11), starting at the solved 3:1 floor.
+ *
+ * Appearance-stable on purpose. The generator pins step 9 to the accent itself, so the
+ * surface is identical in light and dark — which makes the whole inverted scale identical
+ * too, and `[data-inverted]` needs no `.dark` twin.
+ *
+ * Two things this is deliberately NOT:
+ * - **A positional mirror** (`1↔12`). It leaves the solid fill only 2.04:1 from the card in
+ *   dark and 2.23:1 on a light accent like orange — under the 3:1 graphical floor, i.e. still
+ *   invisible, which is the bug this exists to fix.
+ * - **A regenerated on-surface ramp.** Feeding the surface back in as `background` produces
+ *   off-hue overlays (a warm wash on a blue card) and ink at 3.35:1.
+ *
+ * Values are literals, not `var(--spark-N)` aliases: a scale can't re-point to itself
+ * (`--spark-1: var(--spark-12)` next to `--spark-12: var(--spark-1)` is a cycle, and CSS
+ * discards both).
+ */
+declare function invertAccentScale(scale: SparkAccentScale): SparkAccentScale;
+/**
+ * `neutralColor="auto"` resolution: prefer the canvas's own tint when it has one — a
+ * chromatic `background` seeds a visibly warmer/cooler ramp than bucketing it into one
+ * of the 6 named families would (see gap #12). Falls back to accent-matched bucketing
+ * when there's no tinted canvas to pull from.
+ */
+declare function resolveAutoNeutral(accent: string, background?: string): string;
+/**
+ * Whether a string parses as a color at all — for validating a custom `neutralColor`
+ * before it reaches the generator. An unparseable seed (e.g. a typo'd family name like
+ * `"slat"`) would otherwise throw deep inside `generateRadixColors`, taking the whole
+ * accent scale down with it via the caller's shared try/catch.
+ */
+declare function isParsableColor(value: string): boolean;
+/**
+ * The same `--neutral-*` tokens `neutralSparkVars` emits, pointed back at a static Radix
+ * family instead of a generated scale — the counterpart for an appearance that has *no*
+ * custom canvas of its own.
+ *
+ * Ambient (no explicit `appearance`) mode emits both appearances' scales into one unlayered
+ * `<style>`, but a custom canvas only regenerates neutrals for the appearance it belongs to.
+ * Left undeclared, the other block doesn't fall back — nothing resets a custom property, so
+ * its sibling's canvas-tinted values simply stay in effect there, and being unlayered they
+ * outrank `[data-neutral-color]`'s own `@layer base` mapping too. Declaring the same token
+ * set closes that. `var(--<family>-*)` is itself appearance-aware (Radix ships the dark
+ * scales under `.dark`), so one declaration resolves correctly wherever the block applies.
+ */
+declare function neutralFamilyVars(family: Exclude<SparkNeutral, 'auto'>): string[];
 /**
  * `--neutral-*` declarations from the gray scale the generator produces alongside the
  * accent — normally discarded, because `[data-neutral-color]` points `--neutral-*` at a
@@ -56,5 +125,5 @@ declare function neutralSparkVars(scale: SparkAccentScale): string[];
 /** Wide-gamut (P3) twin of `neutralSparkVars`. */
 declare function neutralSparkVarsP3(scale: SparkAccentScale): string[];
 //#endregion
-export { Appearance, CURATED_ACCENTS, GenerateScaleOptions, GeneratedColors, SparkAccentScale, accentSparkVars, accentSparkVarsP3, appearanceForBackground, generateAccentScale, getMatchingNeutral, neutralSparkVars, neutralSparkVarsP3 };
+export { Appearance, CURATED_ACCENTS, GenerateScaleOptions, GeneratedColors, SparkAccentScale, accentSparkVars, accentSparkVarsP3, appearanceForBackground, generateAccentScale, getMatchingNeutral, invertAccentScale, isParsableColor, neutralFamilyVars, neutralSparkVars, neutralSparkVarsP3, resolveAutoNeutral };
 //# sourceMappingURL=accent-theme.d.cts.map

package/dist/lib/accent-theme.d.ts

@@ -1,7 +1,7 @@
 "use client";
 
-import { o as SparkNeutral } from "../theme-types-1yB0d8mp.js";
-import { t as generateRadixColors } from "../generate-radix-colors-Bw-RYaV4.js";
+import { c as SparkNeutralFamily, s as SparkNeutral } from "../theme-types-Bn5E15-P.js";
+import { t as generateRadixColors } from "../generate-radix-colors-BY4Wjsm7.js";
 
 //#region src/lib/accent-theme.d.ts
 /** Shape returned by the vendored Radix generator (it doesn't export a named type). */
@@ -29,8 +29,13 @@ interface GenerateScaleOptions {
    * must match what's actually painted or the alpha ramp renders wrong.
    */
   background?: string;
-  /** Neutral family to regenerate against `background`. Pass a resolved family, not `'auto'`. */
-  neutral?: Exclude<SparkNeutral, 'auto'>;
+  /**
+   * Neutral family, or an arbitrary color to seed the neutral scale (regenerated against
+   * `background`, same as a named family). Pass a resolved value, not `'auto'` — this
+   * option isn't itself typed to exclude it (an open string union can't forbid one
+   * literal), but nothing in `<Theme>` ever forwards `'auto'` this far.
+   */
+  neutral?: SparkNeutral;
 }
 /** Which appearance a canvas belongs to, by OKLCH lightness. */
 declare function appearanceForBackground(background: string): Appearance;
@@ -41,7 +46,71 @@ declare function accentSparkVars(scale: SparkAccentScale): string[];
 /** Wide-gamut (P3) `--spark-*` declarations — for a `color-gamut: p3` `@supports` block. */
 declare function accentSparkVarsP3(scale: SparkAccentScale): string[];
 /** Radix's "auto" gray: curated names use Radix's table; a custom hex is classified by OKLCH hue. */
-declare function getMatchingNeutral(accent: string): Exclude<SparkNeutral, 'auto'>;
+declare function getMatchingNeutral(accent: string): SparkNeutralFamily;
+/**
+ * Re-cast a scale for use ON its own solid (step-9) fill — the `inverted` knob.
+ *
+ * A solid accent control on a solid accent surface is invisible: both paint `--spark-9`.
+ * Inverting swaps that pair — step 9 and its contrast ink trade places — so the solid fill
+ * and its text are contrast-safe **by construction, for any accent**: `accentContrast` is
+ * already the WCAG-checked readable ink for step 9 (`readableContrast`).
+ *
+ * The non-solid styles need a second idea, because the ink is also the text colour. A fill
+ * blended surface→ink moves the background *toward* the foreground, so ink-on-fill contrast
+ * falls monotonically with `t` — and measured across the curated set, the highest `t` that
+ * still clears 4.5:1 (0.174) sits below the lowest `t` that is 3:1 distinguishable from the
+ * surface (0.543). On that line no fill can be both legible and visible, on any accent.
+ *
+ * So fills blend the other way, toward the **scrim** — the lightness pole opposite the ink,
+ * carrying the surface's own hue. Contrast against the ink now *rises* with `t`, which puts
+ * every non-solid style at or above the solid pair's ratio for free. Borders keep stepping
+ * toward the ink (a scrim-side border caps at ~2:1 on light accents like orange, so it can
+ * never clear 1.4.11), starting at the solved 3:1 floor.
+ *
+ * Appearance-stable on purpose. The generator pins step 9 to the accent itself, so the
+ * surface is identical in light and dark — which makes the whole inverted scale identical
+ * too, and `[data-inverted]` needs no `.dark` twin.
+ *
+ * Two things this is deliberately NOT:
+ * - **A positional mirror** (`1↔12`). It leaves the solid fill only 2.04:1 from the card in
+ *   dark and 2.23:1 on a light accent like orange — under the 3:1 graphical floor, i.e. still
+ *   invisible, which is the bug this exists to fix.
+ * - **A regenerated on-surface ramp.** Feeding the surface back in as `background` produces
+ *   off-hue overlays (a warm wash on a blue card) and ink at 3.35:1.
+ *
+ * Values are literals, not `var(--spark-N)` aliases: a scale can't re-point to itself
+ * (`--spark-1: var(--spark-12)` next to `--spark-12: var(--spark-1)` is a cycle, and CSS
+ * discards both).
+ */
+declare function invertAccentScale(scale: SparkAccentScale): SparkAccentScale;
+/**
+ * `neutralColor="auto"` resolution: prefer the canvas's own tint when it has one — a
+ * chromatic `background` seeds a visibly warmer/cooler ramp than bucketing it into one
+ * of the 6 named families would (see gap #12). Falls back to accent-matched bucketing
+ * when there's no tinted canvas to pull from.
+ */
+declare function resolveAutoNeutral(accent: string, background?: string): string;
+/**
+ * Whether a string parses as a color at all — for validating a custom `neutralColor`
+ * before it reaches the generator. An unparseable seed (e.g. a typo'd family name like
+ * `"slat"`) would otherwise throw deep inside `generateRadixColors`, taking the whole
+ * accent scale down with it via the caller's shared try/catch.
+ */
+declare function isParsableColor(value: string): boolean;
+/**
+ * The same `--neutral-*` tokens `neutralSparkVars` emits, pointed back at a static Radix
+ * family instead of a generated scale — the counterpart for an appearance that has *no*
+ * custom canvas of its own.
+ *
+ * Ambient (no explicit `appearance`) mode emits both appearances' scales into one unlayered
+ * `<style>`, but a custom canvas only regenerates neutrals for the appearance it belongs to.
+ * Left undeclared, the other block doesn't fall back — nothing resets a custom property, so
+ * its sibling's canvas-tinted values simply stay in effect there, and being unlayered they
+ * outrank `[data-neutral-color]`'s own `@layer base` mapping too. Declaring the same token
+ * set closes that. `var(--<family>-*)` is itself appearance-aware (Radix ships the dark
+ * scales under `.dark`), so one declaration resolves correctly wherever the block applies.
+ */
+declare function neutralFamilyVars(family: Exclude<SparkNeutral, 'auto'>): string[];
 /**
  * `--neutral-*` declarations from the gray scale the generator produces alongside the
  * accent — normally discarded, because `[data-neutral-color]` points `--neutral-*` at a
@@ -56,5 +125,5 @@ declare function neutralSparkVars(scale: SparkAccentScale): string[];
 /** Wide-gamut (P3) twin of `neutralSparkVars`. */
 declare function neutralSparkVarsP3(scale: SparkAccentScale): string[];
 //#endregion
-export { Appearance, CURATED_ACCENTS, GenerateScaleOptions, GeneratedColors, SparkAccentScale, accentSparkVars, accentSparkVarsP3, appearanceForBackground, generateAccentScale, getMatchingNeutral, neutralSparkVars, neutralSparkVarsP3 };
+export { Appearance, CURATED_ACCENTS, GenerateScaleOptions, GeneratedColors, SparkAccentScale, accentSparkVars, accentSparkVarsP3, appearanceForBackground, generateAccentScale, getMatchingNeutral, invertAccentScale, isParsableColor, neutralFamilyVars, neutralSparkVars, neutralSparkVarsP3, resolveAutoNeutral };
 //# sourceMappingURL=accent-theme.d.ts.map