@bluepic/embed 0.4.0-next.110 → 0.4.0-next.111

package/dist/theme/bridge.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Legacy variable name (without leading `--`) → CSS value expression.
+ * May use `var(--bx-<semantic>)` and plain CSS (px, calc, shorthands).
+ */
+export declare const LEGACY_BRIDGE: Record<string, string>;
+/**
+ * Legacy keys whose CSS custom property IS a semantic token (`--<key>` === `--bx-<semantic>`),
+ * e.g. `bx-focus-ring-width` ↔ `--bx-focus-ring-width`. Their bridge value would reference itself.
+ * They are listed in `LEGACY_BRIDGE` for coverage only — emitters MUST skip them (the resolver
+ * already emits the semantic token with the same name).
+ */
+export declare const LEGACY_BRIDGE_IDENTITY_KEYS: ReadonlySet<string>;
+/** `LEGACY_BRIDGE` minus the identity keys — the entries an emitter should actually write out. */
+export declare const LEGACY_BRIDGE_ENTRIES: ReadonlyArray<readonly [legacyName: string, value: string]>;

package/dist/theme/color.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Bluepic theme system v2 — colour utilities.
+ *
+ * Pure, dependency-free, SSR-safe (no Vue, no DOM). Everything the theme engine needs to
+ * turn "any CSS colour string" into numbers, reason about it perceptually (OKLab / OKLCH,
+ * Björn Ottosson 2020) and for accessibility (WCAG 2.x relative luminance / contrast), and
+ * serialise it back into CSS.
+ *
+ * Conventions
+ *   RGB   — r,g,b in 0..255 (floats allowed internally, rounded on format), a in 0..1
+ *   OKLCH — l in 0..1, c ≥ 0, h in degrees 0..360
+ */
+export type RGB = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+export type OKLCH = {
+    l: number;
+    c: number;
+    h: number;
+    a: number;
+};
+export declare const WHITE: RGB;
+export declare const BLACK: RGB;
+/**
+ * Parse any CSS colour: `#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`, `rgb()` / `rgba()` (comma AND modern space
+ * syntax, `%`, `none`, alpha as 0..1 or `%`), `hsl()` / `hsla()` (`deg` / `turn` / `rad` / `grad`, `%`), all CSS
+ * named colours, `transparent`, and a bare legacy triplet `"r, g, b"` (→ a = 1).
+ * Case-insensitive, trims whitespace. Returns `null` for anything else (e.g. values containing `var()`).
+ */
+export declare function parseColor(input: string | null | undefined): RGB | null;
+/** sRGB → linear → OKLab → OKLCH. */
+export declare function toOklch(c: RGB): OKLCH;
+/** OKLCH → sRGB with gamut mapping (see `oklchToRgbMapped`). */
+export declare function fromOklch(c: OKLCH): RGB;
+/** `#rrggbb`, or `#rrggbbaa` when a < 1. */
+export declare function formatHex(c: RGB): string;
+/** Legacy comma syntax: `rgb(r, g, b)` when a ≥ 1, else `rgba(r, g, b, a)` (ints for rgb, alpha ≤ 3 decimals). */
+export declare function formatRgb(c: RGB): string;
+/** `r, g, b` (ints) — the legacy `*-rgb` triplet for `rgba(var(--x), α)` usage. Alpha is dropped. */
+export declare function formatTriplet(c: RGB): string;
+/** WCAG 2.x relative luminance (0..1). Alpha is ignored. */
+export declare function relativeLuminance(c: RGB): number;
+/**
+ * WCAG 2.x contrast ratio (1..21).
+ * If `fg.a < 1` the foreground is composited over `bg` first. `bg` is ALWAYS treated as opaque — its alpha is
+ * ignored (what it would actually sit on is unknown here; callers that know should composite it themselves).
+ */
+export declare function contrastRatio(fg: RGB, bg: RGB): number;
+/** Alpha-over (`fg` over `bg`). Result alpha = fg.a + bg.a·(1 − fg.a). Fully transparent result → {0,0,0,0}. */
+export declare function composite(fg: RGB, bg: RGB): RGB;
+/**
+ * Perceptual mix in OKLab (t 0..1; 0 → a, 1 → b). Alpha interpolates linearly; the colour channels are
+ * interpolated alpha-premultiplied (as CSS `color-mix()` does) so fading towards a transparent colour keeps
+ * the hue of the opaque one. The result is gamut-mapped back into sRGB.
+ */
+export declare function mix(a: RGB, b: RGB, t: number): RGB;
+export declare function withAlpha(c: RGB, a: number): RGB;
+/** OKLCH lightness (0..1). */
+export declare function lightness(c: RGB): number;
+/** Shift OKLCH lightness by `dl` (clamped to 0..1), hue/chroma kept, gamut-mapped. */
+export declare function adjustL(c: RGB, dl: number): RGB;
+/** Set OKLCH lightness to `l` (clamped to 0..1), hue/chroma kept, gamut-mapped. */
+export declare function setL(c: RGB, l: number): RGB;
+/**
+ * Move `fg`'s OKLCH lightness away from `bg` until `contrastRatio(fg, bg) >= min`, keeping hue/chroma as far as
+ * possible (chroma is reduced progressively only if the target can't be reached at the extremes).
+ * `direction: 'auto'` picks whichever side (lighter or darker than `bg`) can reach the higher contrast.
+ * If `fg` already satisfies `min` it is returned unchanged. If `min` is unreachable the best achievable colour is
+ * returned. `fg`'s alpha is preserved (and taken into account through `contrastRatio`'s compositing).
+ * The result satisfies `min` both as returned (floats) and after 8-bit rounding (`formatHex` / `formatRgb`).
+ * Bounded: ≤ 5 chroma levels × (1 + 24) lightness probes per direction.
+ */
+export declare function ensureContrast(fg: RGB, bg: RGB, min: number, direction?: 'auto' | 'lighter' | 'darker'): RGB;
+/** True when white contrasts at least as well against `c` as black does (i.e. `c` wants light ink). */
+export declare function isDarkSurface(c: RGB): boolean;
+/** The candidate with the highest contrast on `bg`. Default candidates: white and #111111. */
+export declare function bestOn(bg: RGB, candidates?: RGB[]): RGB;

package/dist/theme/css.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvedTheme } from './resolve';
+/** All custom properties (keys include the leading `--`). */
+export declare function themeToCssVars(theme: ResolvedTheme): Record<string, string>;
+/**
+ * CSS text for one or more selectors. Also sets `color-scheme` so UA-painted controls,
+ * scrollbars and form elements follow the theme.
+ */
+export declare function themeToCssText(theme: ResolvedTheme, selectors: string | string[]): string;

package/dist/theme/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @bluepic/embed — theme system v2 (pure, SSR-safe).
+ *
+ *   import { resolveTheme, themeToCssText, themeColor } from '@bluepic/embed';
+ *   const theme = resolveTheme({ version: 2, surface: '#000', primary: '#ffd400' });
+ *   theme.tokens['on-primary']   // → contrast-corrected foreground
+ *   theme.report.checks          // → WCAG pairs with pass/fail
+ *   themeToCssText(theme, '.my-root');
+ *   themeColor.contrastRatio(themeColor.parseColor('#fff')!, themeColor.parseColor('#000')!); // 21
+ *
+ * The DOM-binding (useThemeV2 / applyTheme / legacy useTheme) lives in ../util/useTheme.ts.
+ */
+export * from './tokens';
+export * from './resolve';
+export * from './css';
+export * from './legacy';
+export { LEGACY_BRIDGE } from './bridge';
+export * as themeColor from './color';
+export type { RGB as ThemeRGB, OKLCH as ThemeOKLCH } from './color';

package/dist/theme/legacy.d.ts

@@ -0,0 +1,3 @@
+import type { ThemeInput } from './tokens';
+export declare function looksLikeThemeInput(x: unknown): x is ThemeInput;
+export declare function themeInputFromLegacyCustomStyle(customStyle: Record<string, string> | undefined | null): ThemeInput;

package/dist/theme/resolve.d.ts

@@ -0,0 +1,8 @@
+import { type SemanticTokens, type ThemeInput, type ThemeReport } from './tokens';
+export type ResolvedTheme = {
+    input: ThemeInput;
+    mode: 'dark' | 'light';
+    tokens: SemanticTokens;
+    report: ThemeReport;
+};
+export declare function resolveTheme(rawInput: ThemeInput | undefined | null): ResolvedTheme;

package/dist/theme/tokens.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Bluepic theme system v2 — token vocabulary.
+ *
+ * Three tiers:
+ *   0. ThemeInput      — what a user/host actually chooses (a handful of values).
+ *   1. Semantic tokens — `--bx-*`, ~60 role tokens derived from the input by `resolveTheme()`.
+ *                        Dark and light differ ONLY here.
+ *   2. Component tokens — the historical `--button-*`, `--input-*`, … variables that the
+ *                        components read today. They are defined ONCE, mode-agnostic, as
+ *                        references to semantic tokens (see ./bridge.ts). No more
+ *                        darkmode.scss / lightmode.scss forks.
+ *
+ * Everything in this file is pure data/types: no Vue, no DOM, SSR-safe.
+ */
+export type ThemePresetName = 'light' | 'dark';
+export type ThemeContrast = 'normal' | 'high';
+export type ThemeRadius = 'none' | 'sm' | 'md' | 'lg' | 'full';
+/**
+ * What a campaign (or any host) persists. Small, human-readable, forward-compatible:
+ * the library derives everything else, so campaigns automatically pick up design fixes.
+ */
+export type ThemeInput = {
+    /** Schema marker so legacy `customStyle` records can never be mistaken for this. */
+    version: 2;
+    /**
+     * Base preset. Only decides the defaults of `surface` / `primary` when those are absent.
+     * Mode (dark vs light) is ALWAYS derived from the resolved `surface`, never from this.
+     */
+    preset?: ThemePresetName;
+    /** Page / editor background. Any CSS colour. */
+    surface?: string;
+    /** Brand colour used for primary actions, selection, focus, links. Any CSS colour. */
+    primary?: string;
+    /** High-contrast modifier (replaces the separate *-wcag presets). */
+    contrast?: ThemeContrast;
+    /** Corner radius scale. */
+    radius?: ThemeRadius;
+    /** Typography. */
+    font?: {
+        family?: string;
+        size?: number;
+    };
+    /** 0..1 — how strongly neutral surfaces/borders are tinted with the primary hue. Default 0. */
+    tint?: number;
+    /**
+     * Detailed tier: pin individual semantic tokens. Keys are semantic token names without the
+     * `--bx-` prefix (e.g. `"surface-1"`, `"on-primary"`). Anything not listed stays "auto".
+     */
+    overrides?: Partial<Record<SemanticTokenName, string>>;
+    /**
+     * Escape hatch for hosts/API users: raw component-tier variables (legacy names without `--`),
+     * applied LAST. Prefer `overrides`.
+     */
+    customStyle?: Record<string, string>;
+};
+/**
+ * Semantic token names (without the `--bx-` prefix). Grouped by role. Every one of these is
+ * emitted as a concrete CSS value by `resolveTheme()`; colour tokens are full CSS colours
+ * (`rgb()`/`rgba()`), `*-rgb` tokens are bare `r, g, b` triplets for `rgba(var(--x), a)` use.
+ */
+export declare const SEMANTIC_TOKEN_NAMES: readonly ["color-scheme", "surface", "surface-rgb", "surface-1", "surface-1-rgb", "surface-2", "surface-2-rgb", "surface-3", "surface-inverse", "scrim", "ink", "ink-rgb", "text", "text-muted", "text-faint", "text-inverse", "text-on-surface-rgb", "text-on-inverse-rgb", "border", "border-strong", "divider", "border-rgb", "fill", "fill-hover", "fill-active", "field", "field-hover", "field-focus", "hover", "pressed", "primary", "primary-rgb", "primary-hover", "primary-active", "on-primary", "primary-text", "primary-border", "primary-soft", "primary-soft-hover", "focus-ring", "focus-ring-width", "focus-ring-offset", "primary-dark", "primary-dark-rgb", "primary-light", "primary-light-rgb", "primary-bright", "primary-bright-rgb", "success", "success-rgb", "on-success", "success-text", "success-soft", "success-border", "success-dark-rgb", "success-light-rgb", "success-darker-rgb", "warning", "warning-rgb", "on-warning", "warning-text", "warning-soft", "warning-border", "warning-dark-rgb", "warning-light-rgb", "warning-darker-rgb", "error", "error-rgb", "on-error", "error-text", "error-soft", "error-border", "error-dark-rgb", "error-light-rgb", "error-darker-rgb", "info", "info-rgb", "on-info", "info-text", "info-soft", "info-border", "info-dark-rgb", "info-light-rgb", "info-bright-rgb", "shadow-1", "shadow-2", "shadow-3", "radius-sm", "radius-md", "radius-lg", "radius-full", "font-family", "font-size", "root-font-size", "canvas", "canvas-image", "canvas-control", "canvas-control-hover", "on-canvas-control", "disabled-opacity"];
+export type SemanticTokenName = (typeof SEMANTIC_TOKEN_NAMES)[number];
+export type SemanticTokens = Record<SemanticTokenName, string>;
+export declare const SEMANTIC_PREFIX = "--bx-";
+/** Human-facing groups — used by the Studio "Advanced" panel and the playground Theme Lab. */
+export declare const SEMANTIC_TOKEN_GROUPS: {
+    label: string;
+    tokens: SemanticTokenName[];
+}[];
+export declare const THEME_PRESETS: Record<ThemePresetName, Required<Pick<ThemeInput, 'surface' | 'primary'>>>;
+/** Default status hues (mode-independent bases; the resolver adapts them per surface). */
+export declare const STATUS_BASES: {
+    readonly success: "#28a552";
+    readonly warning: "#d9a400";
+    readonly error: "#dc2f2f";
+    readonly info: "#3b82f6";
+};
+export type ContrastCheck = {
+    /** Human label, e.g. "Text on surface". */
+    label: string;
+    fg: SemanticTokenName;
+    bg: SemanticTokenName;
+    ratio: number;
+    /** WCAG threshold applied (4.5 text, 3 non-text; 7 / 4.5 in high-contrast). */
+    min: number;
+    pass: boolean;
+};
+export type ThemeReport = {
+    mode: 'dark' | 'light';
+    checks: ContrastCheck[];
+    /** Tokens that the resolver had to nudge away from the user's literal choice to stay readable. */
+    adjustments: {
+        token: SemanticTokenName;
+        reason: string;
+    }[];
+};