@fanfare-io/fanfare-sdk-react 0.21.0 → 0.22.0

package/dist/styles/theme.css

@@ -55,6 +55,23 @@
 
 [data-fanfare-variant="retro"] {
   --ff-variant: "retro";
+  /* Inconsolata's advance is 0.5; 0.58 also covers the fallback monospace stack a host that
+   * does not load the face renders with. */
+  --ff-numeral-advance: 0.58;
+  --ff-countdown-cell-padding: 0.5rem 0.75rem;
+  --ff-countdown-cell-border-width: 2px;
+  --ff-countdown-reserve-cell: 1.75rem;
+  --ff-countdown-reserve-gap: 1rem;
+  --ff-countdown-cell-bg: var(--ff-color-background);
+  --ff-countdown-cell-shadow: 3px 3px 0 var(--ff-color-foreground);
+  --ff-progress-bar-shadow: inset 0 -3px 0 rgba(0, 0, 0, 0.2);
+  --ff-card-shadow: 6px 6px 0 var(--ff-color-foreground);
+  --ff-card-shadow-elevated: var(--ff-card-shadow);
+  --ff-countdown-separator-display: none;
+  --ff-countdown-inline-weight: 800;
+  --ff-countdown-tone-critical-bg: #ff3a00;
+  --ff-countdown-tone-critical-fg: #ffffff;
+  --ff-countdown-numeral-font: var(--ff-font-mono);
   --ff-color-background: #f4f1ea;
   --ff-color-foreground: #000000;
   --ff-color-muted: #444444;
@@ -63,7 +80,7 @@
   /*
    * Note: retro intentionally does NOT override --ff-color-danger. The
    * brutalist `#ff3a00` orange is a Countdown-critical-urgency accent only
-   * (applied directly in the countdown cva compound), not a global semantic
+   * (scoped to the countdown unit rule below), not a global semantic
    * destructive color. Destructive buttons / error views keep the customer's
    * (or @theme default) danger token under retro.
    */
@@ -74,15 +91,51 @@
 
 [data-fanfare-variant="rounded"] {
   --ff-variant: "rounded";
+  --ff-countdown-cell-radius: 14px;
+  --ff-countdown-cell-padding: 0.75rem 1rem;
+  --ff-countdown-cell-border-width: 1px;
+  --ff-countdown-cell-bg: var(--ff-color-background);
+  --ff-countdown-cell-shadow: 0 2px 12px -3px rgba(0, 0, 0, 0.08);
+  --ff-countdown-cell-shadow-hover: 0 4px 16px -4px rgba(0, 0, 0, 0.12);
+  --ff-countdown-separator-display: none;
+  --ff-countdown-inline-weight: 600;
+  --ff-countdown-reserve-cell: 2.125rem;
+  --ff-countdown-reserve-gap: 1rem;
+  --ff-card-shadow: 0 2px 12px -3px rgba(0, 0, 0, 0.08);
+  --ff-card-shadow-hover: 0 4px 16px -4px rgba(0, 0, 0, 0.12);
+  --ff-card-shadow-elevated: var(--ff-card-shadow);
+  --ff-card-shadow-elevated-hover: var(--ff-card-shadow-hover);
+  --ff-progress-shadow: inset 0 1px 4px -1px rgba(0, 0, 0, 0.06);
+  --ff-progress-bar-shadow: 0 0 10px -2px var(--ff-color-primary);
+  --ff-loading-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.08);
+  --ff-button-shadow: 0 2px 12px -3px rgba(0, 0, 0, 0.08);
+  --ff-button-shadow-hover: 0 4px 16px -4px rgba(0, 0, 0, 0.12);
+  --ff-button-shadow-active: inset 0 2px 4px rgba(0, 0, 0, 0.1);
+  --ff-button-shadow-primary: 0 2px 12px -3px rgba(0, 0, 0, 0.08), 0 0 12px -6px var(--ff-color-primary);
+  --ff-input-shadow: inset 0 1px 4px -1px rgba(0, 0, 0, 0.06);
+  --ff-input-shadow-focus: inset 0 1px 4px -1px rgba(0, 0, 0, 0.06), 0 0 0 3px rgba(var(--ff-color-primary-rgb), 0.12);
+  --ff-otp-shadow: inset 0 1px 4px -1px rgba(0, 0, 0, 0.06);
+  --ff-otp-shadow-focus: inset 0 1px 4px -1px rgba(0, 0, 0, 0.06), 0 0 0 3px rgba(var(--ff-color-primary-rgb), 0.12);
+  --ff-otp-shadow-focus-error:
+    inset 0 1px 4px -1px rgba(0, 0, 0, 0.06), 0 0 0 3px rgba(var(--ff-color-danger-rgb), 0.12);
 }
 
 [data-fanfare-variant="clean"] {
   --ff-variant: "clean";
+  --ff-numeral-advance: 0.58;
+  --ff-countdown-cell-gap: 0.125rem;
+  --ff-countdown-inline-weight: 500;
+  --ff-countdown-inline-tracking: 0.02em;
+  --ff-countdown-reserve-gap: 2rem;
+  --ff-countdown-numeral-font: var(--ff-font-mono);
   --ff-color-background: #ffffff;
   --ff-color-foreground: #0a0a0a;
   --ff-color-muted: #737373;
   --ff-color-muted-foreground: #737373;
   --ff-color-border: #e8e8e8;
+  --ff-card-shadow: 0 1px 3px rgba(0, 0, 0, 0.04), 0 8px 24px rgba(0, 0, 0, 0.06);
+  --ff-card-shadow-elevated: var(--ff-card-shadow);
+  --ff-progress-bar-shadow: 0 0 #0000;
   --ff-font-sans: "Figtree", system-ui, sans-serif;
   --ff-font-heading: "Figtree", system-ui, sans-serif;
   --ff-font-mono: "Inconsolata", "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
@@ -98,6 +151,154 @@
     font-family: var(--ff-font-sans);
     color: var(--ff-color-foreground);
     background-color: var(--ff-color-surface);
+    --ff-widget-max-width: 24rem;
+
+    /* The advance width of one digit as a fraction of the font size, for the
+     * variant's numeral typeface. Fitting a fixed-width glyph run to a
+     * container needs it; over-stating it only shrinks the numerals. */
+    --ff-numeral-advance: 0.65;
+
+    /* Display text that fits its container: a `cqi`-driven scale between a
+     * legible floor and a ceiling the design allows. */
+    --ff-stat-min: 1.5rem;
+    --ff-stat-scale: 9cqi;
+    --ff-stat-max: 2.25rem;
+    --ff-stat-weight: 700;
+    --ff-title-min: 1rem;
+    --ff-title-scale: 6cqi;
+    --ff-title-max: 1.25rem;
+    --ff-title-weight: 600;
+
+    /* Countdown: geometry, colour, label placement, separator and inline type,
+     * overridden per variant in the blocks above. */
+    --ff-countdown-cell-gap: 0.75rem;
+    --ff-countdown-cell-padding: 0;
+    --ff-countdown-cell-radius: 0;
+    --ff-countdown-cell-border-width: 0px;
+    --ff-countdown-cell-bg: transparent;
+    --ff-countdown-cell-shadow: none;
+    --ff-countdown-cell-shadow-hover: var(--ff-countdown-cell-shadow);
+    --ff-countdown-numeral-color: var(--ff-color-foreground);
+    --ff-countdown-numeral-font: var(--ff-font-heading);
+    --ff-countdown-label-color: var(--ff-color-muted-foreground);
+    --ff-countdown-label-size: 0.625rem;
+    --ff-countdown-label-order: 1;
+    --ff-countdown-separator-glyph: "/";
+    --ff-countdown-separator-display: inline;
+    --ff-countdown-separator-color: var(--ff-color-muted-foreground);
+    --ff-countdown-inline-size: inherit;
+    --ff-countdown-inline-weight: 600;
+    --ff-countdown-inline-tracking: 0;
+
+    /* Numeral fitting: the bounds the fitted numeral size is clamped to, and
+     * the horizontal space the numerals cannot have — the panel's own padding
+     * plus, per variant, each cell's padding and border and each gap's width
+     * and separator glyph. Rounded up: over-reserving shrinks the numerals,
+     * under-reserving overflows the widget. */
+    --ff-countdown-numeral-min: 1.25rem;
+    --ff-countdown-numeral-max: 2.5rem;
+    --ff-countdown-reserve-outer: 2.5rem;
+    --ff-countdown-reserve-cell: 0rem;
+    --ff-countdown-reserve-gap: 3rem;
+
+    /* Countdown urgency: the colours a warning or critical cell takes. */
+    --ff-countdown-tone-warning-color: var(--ff-color-warning);
+    --ff-countdown-tone-critical-color: var(--ff-color-danger);
+    --ff-countdown-tone-critical-bg: transparent;
+    --ff-countdown-tone-critical-fg: inherit;
+
+    /* Panel geometry: the padding around a panel's stack and the gap between
+     * the rows of that stack and of a panel body. */
+    --ff-panel-gap: 1.25rem;
+    --ff-panel-padding: 1.25rem;
+
+    /* Surface elevation, one token per surface and per interactive state it
+     * distinguishes. A variant that raises a surface overrides these. */
+    --ff-card-shadow: none;
+    --ff-card-shadow-hover: var(--ff-card-shadow);
+
+    /* The `elevated` card is raised above its aesthetic's resting surface, so it
+     * carries its own pair rather than reading the resting one. The default is
+     * the elevation the variant-less card has always drawn. */
+    --ff-card-shadow-elevated: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
+    --ff-card-shadow-elevated-hover: var(--ff-card-shadow-elevated);
+    --ff-progress-shadow: none;
+    --ff-progress-bar-shadow: none;
+    --ff-loading-shadow: none;
+
+    /* Surfaces that also carry a focus ring compose their shadow with it
+     * through Tailwind's own shadow utility, so the empty value here is the
+     * transparent shadow that composes rather than the `none` that would
+     * invalidate the whole list — and the ring with it. */
+    --ff-button-shadow: 0 0 #0000;
+    --ff-button-shadow-hover: var(--ff-button-shadow);
+    --ff-button-shadow-active: var(--ff-button-shadow);
+    --ff-button-shadow-primary: var(--ff-button-shadow);
+    --ff-input-shadow: 0 0 #0000;
+    --ff-input-shadow-focus: var(--ff-input-shadow);
+    --ff-otp-shadow: 0 0 #0000;
+    --ff-otp-shadow-focus: var(--ff-otp-shadow);
+    --ff-otp-shadow-focus-error: var(--ff-otp-shadow-focus);
+
+    /* Product selector row: the box a row draws and the square its thumbnail
+     * occupies inside it. */
+    --ff-row-gap: 0.75rem;
+    --ff-row-padding: 0.75rem;
+    --ff-row-radius: 0.375rem;
+    --ff-row-thumb-size: 2.75rem;
+    --ff-row-thumb-size-narrow: 2.5rem;
+
+    /* Ledger rows: the rule drawn between them, and the colour each tone
+     * carries on the marker glyph and the value. */
+    --ff-ledger-row-padding: 0.375rem;
+    --ff-ledger-border-color: color-mix(in oklab, var(--ff-color-border) 40%, transparent);
+    --ff-ledger-tone-default: var(--ff-color-foreground);
+    --ff-ledger-tone-muted: var(--ff-color-muted);
+    --ff-ledger-tone-live: var(--ff-color-primary);
+    --ff-ledger-tone-danger: var(--ff-color-danger);
+    --ff-ledger-tone-success: var(--ff-color-success);
+  }
+
+  /**
+   * Hero is the same countdown at a larger scale: a taller numeral ceiling, a
+   * wider cell gap, and a gap reserve that counts that gap either side of the
+   * larger separator glyph. The variants that draw no separator reserve the
+   * gap alone.
+   */
+  .fanfare-themed [data-slot="countdown"][data-size="hero"] {
+    --ff-countdown-numeral-max: 3.75rem;
+    --ff-countdown-cell-gap: 1rem;
+    --ff-countdown-reserve-gap: 3.75rem;
+  }
+
+  .fanfare-themed[data-fanfare-variant="retro"] [data-slot="countdown"][data-size="hero"],
+  .fanfare-themed[data-fanfare-variant="rounded"] [data-slot="countdown"][data-size="hero"] {
+    --ff-countdown-reserve-gap: 1rem;
+  }
+
+  /**
+   * Four unit labels plus three separators need more width than the widget
+   * has, so a countdown showing four cells drops its separators at every size
+   * and reserves the cell gap alone between cells.
+   */
+  .fanfare-themed [data-slot="countdown"][data-units="4"] {
+    --ff-countdown-separator-display: none;
+    --ff-countdown-reserve-gap: var(--ff-countdown-cell-gap);
+  }
+
+  /**
+   * The boxed variants' cell padding alone would leave four cells no room for
+   * numerals at the narrowest widget width the cells layout renders at, so a
+   * four-cell row narrows each cell's side padding; the cell reserve follows.
+   */
+  .fanfare-themed[data-fanfare-variant="rounded"] [data-slot="countdown"][data-units="4"] {
+    --ff-countdown-cell-padding: 0.75rem 0.5rem;
+    --ff-countdown-reserve-cell: 1.125rem;
+  }
+
+  .fanfare-themed[data-fanfare-variant="retro"] [data-slot="countdown"][data-units="4"] {
+    --ff-countdown-cell-padding: 0.5rem 0.5rem;
+    --ff-countdown-reserve-cell: 1.5rem;
   }
 
   /**
@@ -141,3 +342,250 @@
     }
   }
 }
+
+@layer components {
+  /**
+   * Countdown token consumers. The layer keeps a one-off Tailwind utility
+   * winning over these rules, and the `.fanfare-themed` prefix keeps them from
+   * reaching a host page's own markup once the stylesheet is imported.
+   */
+  /**
+   * Cells are a two-row grid: every unit spans both rows through a subgrid, so
+   * the numerals share the first row and each separator centres on that row
+   * whatever size the numerals fit to.
+   */
+  .fanfare-themed [data-slot="countdown-cells"] {
+    column-gap: var(--ff-countdown-cell-gap);
+  }
+
+  .fanfare-themed [data-slot="countdown-unit"] {
+    padding: var(--ff-countdown-cell-padding);
+    border-radius: var(--ff-countdown-cell-radius);
+    border-width: var(--ff-countdown-cell-border-width);
+    border-style: solid;
+    background-color: var(--ff-countdown-cell-bg);
+    box-shadow: var(--ff-countdown-cell-shadow);
+  }
+
+  /* Hover elevation is gated on a real pointer, so a tap does not leave a
+   * cell raised. */
+  @media (hover: hover) {
+    .fanfare-themed [data-slot="countdown-unit"]:hover {
+      box-shadow: var(--ff-countdown-cell-shadow-hover);
+    }
+  }
+
+  /* Per-digit boxes inherit the numeral face from their unit. */
+  .fanfare-themed [data-slot="countdown-unit-digits"] {
+    color: var(--ff-countdown-numeral-color);
+    font-family: var(--ff-countdown-numeral-font);
+  }
+
+  /**
+   * Per-unit numerals size themselves to the widget: the container's inline
+   * size less the reserved chrome, divided across every digit on screen
+   * (`--ff-countdown-digits`, across `--ff-countdown-cells` cells, at the
+   * variant's advance ratio). The per-digit granularity is excluded — its cells are fixed boxes
+   * whose numerals are sized by utility to match.
+   *
+   * `cqi` cannot name a container, so it binds to the nearest one. Every
+   * countdown the SDK renders sits under the widget root and outside
+   * `ProductSelector`'s own container, so this reads the widget's width.
+   */
+  .fanfare-themed [data-cells="unit"] [data-slot="countdown-unit-digits"] {
+    font-size: clamp(
+      var(--ff-countdown-numeral-min),
+      calc(
+        (
+            100cqi - var(--ff-countdown-reserve-outer) - var(--ff-countdown-cells) * var(--ff-countdown-reserve-cell) -
+              (var(--ff-countdown-cells) - 1) * var(--ff-countdown-reserve-gap)
+          ) /
+          (var(--ff-countdown-digits) * var(--ff-numeral-advance))
+      ),
+      var(--ff-countdown-numeral-max)
+    );
+  }
+
+  .fanfare-themed [data-slot="countdown-unit-label"] {
+    order: var(--ff-countdown-label-order);
+    font-size: var(--ff-countdown-label-size);
+    color: var(--ff-countdown-label-color);
+  }
+
+  .fanfare-themed [data-slot="countdown-separator"] {
+    display: var(--ff-countdown-separator-display);
+    color: var(--ff-countdown-separator-color);
+  }
+
+  .fanfare-themed [data-slot="countdown-separator"]::before {
+    content: var(--ff-countdown-separator-glyph);
+  }
+
+  .fanfare-themed [data-layout="inline"][data-slot="countdown"],
+  .fanfare-themed [data-slot="countdown-inline"] {
+    font-size: var(--ff-countdown-inline-size);
+    font-weight: var(--ff-countdown-inline-weight);
+    letter-spacing: var(--ff-countdown-inline-tracking);
+  }
+
+  /**
+   * Both layouts publish the resolved tone on their root: the cells layout
+   * colours each unit's numerals, the inline layout colours the single line,
+   * and the cells layout's narrow-container inline fallback picks up the same
+   * rule.
+   */
+  .fanfare-themed [data-slot="countdown-unit"][data-tone="warning"] [data-slot="countdown-unit-digits"],
+  .fanfare-themed [data-slot="countdown"][data-tone="warning"] [data-slot="countdown-inline"] {
+    color: var(--ff-countdown-tone-warning-color);
+  }
+
+  .fanfare-themed [data-slot="countdown-unit"][data-tone="critical"] [data-slot="countdown-unit-digits"],
+  .fanfare-themed [data-slot="countdown"][data-tone="critical"] [data-slot="countdown-inline"] {
+    color: var(--ff-countdown-tone-critical-color);
+  }
+
+  /**
+   * Retro's urgency accent is part of that variant's aesthetic rather than the
+   * global danger semantic, so the filled cell is scoped to the retro variant
+   * instead of moving `--ff-color-danger`. Other variants keep the cell surface
+   * their geometry tokens give them and carry urgency in the numeral colour
+   * alone.
+   */
+  .fanfare-themed[data-fanfare-variant="retro"] [data-slot="countdown-unit"][data-tone="critical"] {
+    background-color: var(--ff-countdown-tone-critical-bg);
+    color: var(--ff-countdown-tone-critical-fg);
+  }
+
+  /**
+   * The global critical rule sets the numeral colour directly, so the filled
+   * cell's foreground has to be restated on the numerals and label rather than
+   * relied on through inheritance.
+   */
+  .fanfare-themed[data-fanfare-variant="retro"]
+    [data-slot="countdown-unit"][data-tone="critical"]
+    [data-slot="countdown-unit-digits"],
+  .fanfare-themed[data-fanfare-variant="retro"]
+    [data-slot="countdown-unit"][data-tone="critical"]
+    [data-slot="countdown-unit-label"] {
+    color: var(--ff-countdown-tone-critical-fg);
+  }
+
+  /**
+   * Display text that is prose rather than a fixed glyph run: it scales with
+   * the widget between a legible floor and the design's ceiling, so a narrow
+   * embed shrinks the words instead of wrapping or clipping them.
+   */
+  .fanfare-themed [data-slot="stat-value"] {
+    font-size: clamp(var(--ff-stat-min), var(--ff-stat-scale), var(--ff-stat-max));
+    font-weight: var(--ff-stat-weight);
+    line-height: 1.2;
+  }
+
+  .fanfare-themed [data-slot="panel-title"] {
+    font-size: clamp(var(--ff-title-min), var(--ff-title-scale), var(--ff-title-max));
+    font-weight: var(--ff-title-weight);
+    line-height: 1.4;
+  }
+
+  .fanfare-themed [data-slot="panel-body"],
+  .fanfare-themed [data-slot="panel-stack"] {
+    gap: var(--ff-panel-gap);
+  }
+
+  .fanfare-themed [data-slot="panel-stack"] {
+    padding: var(--ff-panel-padding);
+  }
+
+  /**
+   * Every Card carries `data-fanfare-card` whatever `data-slot` its consumer
+   * publishes on it, so the surface rules key on that marker rather than on a
+   * slot name a panel is free to replace.
+   */
+  .fanfare-themed [data-fanfare-card] {
+    box-shadow: var(--ff-card-shadow);
+  }
+
+  /**
+   * A raised card publishes `data-elevated`, so its elevation is a token the
+   * variant reaches rather than a utility that outranks every variant's
+   * aesthetic.
+   */
+  .fanfare-themed [data-fanfare-card][data-elevated] {
+    box-shadow: var(--ff-card-shadow-elevated);
+  }
+
+  @media (hover: hover) {
+    .fanfare-themed [data-fanfare-card]:hover {
+      box-shadow: var(--ff-card-shadow-hover);
+    }
+
+    .fanfare-themed [data-fanfare-card][data-elevated]:hover {
+      box-shadow: var(--ff-card-shadow-elevated-hover);
+    }
+  }
+
+  .fanfare-themed [data-slot="progress-track"] {
+    box-shadow: var(--ff-progress-shadow);
+  }
+
+  .fanfare-themed [data-slot="progress-bar"] {
+    box-shadow: var(--ff-progress-bar-shadow);
+  }
+
+  .fanfare-themed [data-slot="loading-spinner"] {
+    box-shadow: var(--ff-loading-shadow);
+  }
+
+  .fanfare-themed [data-slot="product-selector-row"] {
+    gap: var(--ff-row-gap);
+    padding: var(--ff-row-padding);
+    border-radius: var(--ff-row-radius);
+  }
+
+  .fanfare-themed [data-slot="product-thumb"] {
+    width: var(--ff-row-thumb-size);
+    height: var(--ff-row-thumb-size);
+  }
+
+  /**
+   * The thumbnail takes its narrow side length once the picker's own container
+   * is too tight for the wide one. The query is unnamed so it binds to that
+   * container — the nearest one — rather than to the widget, which a picker
+   * rendered on its own need not sit inside.
+   */
+  @container not (min-width: 400px) {
+    .fanfare-themed [data-slot="product-thumb"] {
+      width: var(--ff-row-thumb-size-narrow);
+      height: var(--ff-row-thumb-size-narrow);
+    }
+  }
+
+  .fanfare-themed [data-slot="ledger-row"] {
+    padding-block: var(--ff-ledger-row-padding);
+    border-bottom-color: var(--ff-ledger-border-color);
+  }
+
+  /**
+   * Tone is published on the row and inherited by the marker glyph and the
+   * value; the label states its own muted colour and is unaffected.
+   */
+  .fanfare-themed [data-slot="ledger-row"][data-tone="default"] {
+    color: var(--ff-ledger-tone-default);
+  }
+
+  .fanfare-themed [data-slot="ledger-row"][data-tone="muted"] {
+    color: var(--ff-ledger-tone-muted);
+  }
+
+  .fanfare-themed [data-slot="ledger-row"][data-tone="live"] {
+    color: var(--ff-ledger-tone-live);
+  }
+
+  .fanfare-themed [data-slot="ledger-row"][data-tone="danger"] {
+    color: var(--ff-ledger-tone-danger);
+  }
+
+  .fanfare-themed [data-slot="ledger-row"][data-tone="success"] {
+    color: var(--ff-ledger-tone-success);
+  }
+}

package/dist/theme/font-loader.d.ts

@@ -0,0 +1,58 @@
+import { WidgetVariant } from '@fanfare-io/fanfare-sdk-core/theme';
+/** The catalogue categories, each with its own fallback stack. */
+export type FontCategory = "Display" | "Handwriting" | "Monospace" | "Sans Serif" | "Serif";
+export interface FontCatalogueEntry {
+    category: FontCategory;
+    /** The weights the family publishes; requesting one it lacks fails the whole font request. */
+    weights: number[];
+}
+/**
+ * Generic stacks a browser can render without a network request, so a family that fails to load
+ * degrades to a face of the same flavour rather than to the default serif.
+ */
+export declare const CATEGORY_FALLBACKS: Record<FontCategory, string>;
+/**
+ * CSS generic families and CSS-wide keywords. A font value that is one of these names no family at
+ * all, so it is neither fetchable nor quotable: quoting it would make the browser look for a family
+ * literally called `serif`. Kept lowercase because family names are case-insensitive in CSS.
+ */
+export declare const GENERIC_FONT_KEYWORDS: ReadonlySet<string>;
+/** The families the admin font picker offers, in the picker's own order. */
+export declare const FONT_CATALOGUE: Record<string, FontCatalogueEntry>;
+/** Whether a family resolves without a network request. Family names are case-insensitive in CSS. */
+export declare const isSystemFont: (family: string) => boolean;
+/**
+ * The catalogue's own spelling of a family. CSS matches family names case-insensitively, but the
+ * Google Fonts css2 endpoint does not — it rejects `figtree` outright — so a host's casing is
+ * resolved to the catalogue's before anything is requested.
+ */
+export declare const catalogueFamilyName: (family: string) => string | undefined;
+/**
+ * The Google Fonts stylesheet for a family, asking for exactly the weights it publishes — the
+ * css2 endpoint rejects the whole request when it names a weight the family lacks, and several
+ * curated families publish fewer than the usual 400/500/600/700. A family outside the catalogue
+ * has no known weight list, so it is requested without a weight axis at all.
+ */
+export declare const googleFontStylesheetHref: (family: string) => string;
+/** The faces a variant's own token block names: its text face, and its mono face where it has one. */
+export interface VariantFamilies {
+    body: string;
+    mono?: string;
+}
+/** The families each variant's own token block names, used when a theme names none of its own. */
+export declare const VARIANT_DEFAULT_FAMILIES: Record<WidgetVariant, VariantFamilies>;
+/**
+ * The faces to fetch for a variant. A variant name the build does not know still reaches here — a
+ * theme served by a newer admin, or a hand-written element attribute — and takes the default
+ * variant's faces, which are the ones its token block falls back to as well.
+ */
+export declare const variantFamilies: (variant: string | undefined) => VariantFamilies;
+/**
+ * Requests a family's stylesheet at most once per page. The link is inserted for print only and
+ * promoted to every medium once it has loaded, so a slow or unreachable font origin never holds
+ * first paint. A request that fails leaves nothing behind and is never retried — the theme's
+ * fallback stack carries the text, and a second attempt would spend the same latency again.
+ */
+export declare function ensureFontStylesheet(family: string): void;
+/** Test-only seam: forgets which families were requested. Never exported from the package entry. */
+export declare function resetFontLoaderCache(): void;

package/dist/theme/theme-context.d.ts

@@ -2,8 +2,16 @@ import { BrandTheme } from '@fanfare-io/fanfare-sdk-core/theme';
 import { ResolvedTheme, WidgetVariant } from './theme.types';
 /**
  * Context value for theme state.
+ *
+ * `theme` is the merged value a component renders with, every field filled from the SDK defaults.
+ * `overrides` answers the different question of what the host actually asked for: the raw fields
+ * the providers above this point set, accumulated but never merged with defaults, and `{}` where no
+ * provider set anything. A merged value cannot answer that — a host naming the default family is
+ * indistinguishable there from a host naming nothing.
  */
 export interface ThemeContextValue extends ResolvedTheme {
+    /** The raw fields providers up the tree explicitly set, without defaults */
+    overrides: BrandTheme;
     /** Whether this is the root theme provider */
     isRoot: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanfare-io/fanfare-sdk-react",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "React adapter for Fanfare SDK",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -43,8 +43,8 @@
     "nanostores": "^1.1.0",
     "tailwind-merge": "^2.6.0",
     "valibot": "^1.1.0",
-    "@fanfare-io/fanfare-sdk-core": "0.21.0",
-    "@fanfare-io/fanfare-sdk-i18n": "0.21.0"
+    "@fanfare-io/fanfare-sdk-core": "0.22.0",
+    "@fanfare-io/fanfare-sdk-i18n": "0.22.0"
   },
   "devDependencies": {
     "@iconify-json/heroicons": "^1.2.3",
@@ -55,7 +55,6 @@
     "@size-limit/preset-small-lib": "^11.1.8",
     "@storybook/addon-a11y": "^10.4.0",
     "@storybook/addon-docs": "^10.4.0",
-    "@storybook/addon-themes": "^10.4.0",
     "@storybook/addon-vitest": "~10.2.16",
     "@storybook/react-vite": "^10.4.0",
     "@stripe/stripe-js": "^7.3.1",
@@ -91,8 +90,8 @@
     "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^5.0.0",
-    "@fanfare-io/fanfare-sdk-core": "0.21.0",
-    "@fanfare-io/fanfare-sdk-solid": "0.21.0"
+    "@fanfare-io/fanfare-sdk-core": "0.22.0",
+    "@fanfare-io/fanfare-sdk-solid": "0.22.0"
   },
   "sideEffects": [
     "**/*.css"
@@ -110,7 +109,7 @@
     {
       "name": "React adapter",
       "path": "dist/index.js",
-      "limit": "67 KB",
+      "limit": "70 KB",
       "ignore": [
         "react",
         "react-dom",