@adea-ai/ui 0.28.0 → 0.29.0

package/dist/components/appearance.d.ts

@@ -0,0 +1,245 @@
+/**
+ * The versioned client appearance preference (Dev Runtime spec,
+ * "Appearance and App Library"). Stored as one JSON document; the legacy
+ * single `theme` key migrates into it without deleting the old value.
+ */
+export type AppearancePreferencesV2 = Readonly<{
+    version: 2;
+    mode: AppearanceMode;
+    lightThemeId: string;
+    darkThemeId: string;
+    /** `'theme'`, a built-in preset id, or a validated `#rrggbb` color. */
+    accent: 'theme' | string;
+    surface: 'opaque' | 'frosted' | 'translucent';
+    reduceTransparency: boolean;
+}>;
+export type AppearanceMode = 'system' | 'light' | 'dark';
+export type ResolvedAppearance = 'light' | 'dark';
+export type SurfacePreference = 'opaque' | 'frosted' | 'translucent';
+export declare const APPEARANCE_STORAGE_KEY = "appearance";
+/** The pre-#425 key. Migration reads it and never deletes it. */
+export declare const LEGACY_THEME_STORAGE_KEY = "theme";
+export declare const DARK_QUERY = "(prefers-color-scheme: dark)";
+export declare const REDUCED_TRANSPARENCY_QUERY = "(prefers-reduced-transparency: reduce)";
+export declare const defaultAppearancePreferences: AppearancePreferencesV2;
+/**
+ * Combine the user's choice with the OS state. A pinned mode ignores the OS;
+ * `system` follows it. (Zeron `resolve`.)
+ */
+export declare function resolveAppearanceMode(mode: AppearanceMode, system: ResolvedAppearance): ResolvedAppearance;
+export type RgbColor = Readonly<{
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}>;
+export declare class ColorParseError extends Error {
+    constructor();
+}
+/** Parse a hex color. Returns `undefined` for anything unsupported. */
+export declare function parseColor(value: string): RgbColor | undefined;
+export declare function colorToHex(color: RgbColor): string;
+/** WCAG contrast ratio between two colors. Alpha composites over the background first. */
+export declare function contrastRatio(foreground: RgbColor | string, background: RgbColor | string): number;
+export type AccentPreset = Readonly<{
+    id: string;
+    label: string;
+    dark: string;
+    light: string;
+}>;
+export declare const accentPresets: readonly AccentPreset[];
+/**
+ * Normalize a custom accent color against a variant background: unparseable
+ * input is rejected (`undefined`), and any accepted color is raised to the
+ * 3:1 interaction minimum so an accent can never ship unreadable.
+ */
+export declare function normalizeAccentValue(value: string, background: string): string | undefined;
+export declare function accentPresetById(id: string): AccentPreset | undefined;
+export type AccentRoles = Readonly<{
+    /** Interactive primary. */
+    primary: string;
+    /** Text drawn on `primary`-filled controls; ≥ 4.5:1 against it. */
+    onPrimary: string;
+    /** Hover/press emphasis derived from the primary. */
+    strong: string;
+    /** Focus ring color. */
+    ring: string;
+    /** False when the selection is the variant's own accent and no role should be overridden. */
+    overrides: boolean;
+}>;
+/**
+ * Derive the accent roles for a selection against a variant. `'theme'` keeps
+ * the variant's own accent; presets and custom colors are normalized to the
+ * 3:1 interaction minimum (Zeron `AccentRoles::derive`, thresholds preserved).
+ */
+export declare function deriveAccentRoles(selection: string, variant: ThemeVariant): AccentRoles;
+export type EffectiveSurface = 'opaque' | 'frosted' | 'translucent';
+export declare function resolveSurface(preference: SurfacePreference, environment: Readonly<{
+    osReducedTransparency: boolean;
+    userReducedTransparency: boolean;
+    nativeTranslucency: boolean;
+}>): EffectiveSurface;
+export type ThemeTerminalPalette = Readonly<{
+    background: string;
+    foreground: string;
+    cursor: string;
+    selection: string;
+    /** The 16 xterm ANSI slots, in protocol order. */
+    ansi: readonly string[];
+}>;
+export type ThemeEditorRoles = Readonly<{
+    keyword: string;
+    string: string;
+    number: string;
+    comment: string;
+    function: string;
+    variable: string;
+    type: string;
+    tag: string;
+    attribute: string;
+    operator: string;
+    heading: string;
+    link: string;
+    diffAdd: string;
+    diffDelete: string;
+    diffHunk: string;
+    searchMatch: string;
+}>;
+export type ThemeChartRoles = Readonly<{
+    chart1: string;
+    chart2: string;
+    chart3: string;
+    chart4: string;
+    chart5: string;
+    chart6: string;
+}>;
+export type ThemeColors = Readonly<{
+    background: string;
+    foreground: string;
+    card: string;
+    cardForeground: string;
+    popover: string;
+    popoverForeground: string;
+    primary: string;
+    primaryForeground: string;
+    secondary: string;
+    secondaryForeground: string;
+    muted: string;
+    mutedForeground: string;
+    accent: string;
+    accentForeground: string;
+    destructive: string;
+    success: string;
+    border: string;
+    input: string;
+    ring: string;
+}>;
+export type ThemeVariant = Readonly<{
+    id: string;
+    familyId: string;
+    familyName: string;
+    name: string;
+    appearance: ResolvedAppearance;
+    colors: ThemeColors;
+    terminal: ThemeTerminalPalette;
+    editor: ThemeEditorRoles;
+    charts: ThemeChartRoles;
+}>;
+/**
+ * The independent per-appearance theme selection (Zeron `ThemeSelection`,
+ * carrying the V2 preference's field names).
+ */
+export type ThemeSelection = Readonly<{
+    lightThemeId: string;
+    darkThemeId: string;
+}>;
+export declare function themeSelectionVariantId(selection: ThemeSelection, appearance: ResolvedAppearance): string;
+export type ValidationIssue = Readonly<{
+    variantId: string;
+    severity: 'error' | 'warning';
+    message: string;
+}>;
+/**
+ * Registry validation, ported from Zeron `ThemeRegistry::validate`: core text
+ * and muted text must reach 4.5:1, the accent 3:1, on-accent 4.5:1, the
+ * terminal foreground 4.5:1, and every chromatic ANSI slot 3:1 (slots 0 and 8
+ * are structural black/dim colors). Provenance completeness is a Zeron
+ * library concept; M12 ships only built-ins, so the structural check here is
+ * id/non-empty-color integrity.
+ */
+export declare function validateThemeRegistry(registry: readonly ThemeVariant[]): ValidationIssue[];
+/**
+ * Resolve the variant for a selection, falling back deterministically to the
+ * default variant of the same appearance when the stored id is missing or
+ * broken — a corrupt preference degrades the palette, never the UI.
+ * (Zeron `ThemeRegistry::resolve`.)
+ */
+export declare function resolveThemeVariant(registry: readonly ThemeVariant[], selection: ThemeSelection, appearance: ResolvedAppearance): ThemeVariant;
+/** The `adea-light`/`adea-dark` entries mirror `styles/theme.css`. */
+export declare const builtinThemeRegistry: readonly ThemeVariant[];
+export type NormalizedPreferences = Readonly<{
+    /** The strict v2 document, with every unknown field corrected to defaults. */
+    value: AppearancePreferencesV2;
+    /**
+     * The raw stored document when it was not a valid v2 record. Retained so a
+     * future version (or a repaired write) never loses the user's data.
+     */
+    retainedRaw?: unknown;
+}>;
+/**
+ * Parse a stored appearance document. Anything that is not a strict version-2
+ * record falls back to the defaults and keeps the raw value for retention;
+ * individual unknown values inside a v2 record are corrected field by field.
+ */
+export declare function normalizeAppearancePreferences(raw: unknown): NormalizedPreferences;
+/** The legacy single-key preference, mapped into v2 during migration. */
+export declare function migrateLegacyThemeValue(stored: string | null): AppearancePreferencesV2 | undefined;
+type AppearanceStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+/**
+ * Read the appearance preferences: the v2 key first, then the legacy `theme`
+ * key, then defaults. Storage failures degrade to defaults like every other
+ * blocked-storage consumer.
+ */
+export declare function readAppearancePreferences(storage: AppearanceStorage | undefined): AppearancePreferencesV2;
+export declare function writeAppearancePreferences(storage: AppearanceStorage | undefined, preferences: AppearancePreferencesV2): void;
+export type ResolvedAppearanceState = Readonly<{
+    resolvedMode: ResolvedAppearance;
+    variant: ThemeVariant;
+    accent: AccentRoles;
+    effectiveSurface: EffectiveSurface;
+    reduceTransparencyActive: boolean;
+}>;
+/** Resolve preferences against the environment into the applied document state. */
+export declare function resolveAppearanceState(preferences: AppearancePreferencesV2, environment: Readonly<{
+    systemAppearance: ResolvedAppearance;
+    osReducedTransparency: boolean;
+    nativeTranslucency: boolean;
+}>, registry?: readonly ThemeVariant[]): ResolvedAppearanceState;
+/**
+ * The custom properties a non-default variant owns, as a flat map. This one
+ * mapping feeds both the live provider and the pre-paint no-flash script, so
+ * a restored first paint and a later live switch cannot disagree. Default
+ * variants return an empty map: `styles/theme.css` declares those tokens.
+ */
+export declare function flatVariantTokens(variant: ThemeVariant): Record<string, string>;
+/**
+ * Apply a resolved state to a document: the `dark` class and color scheme for
+ * the palette, the diagnostic data attributes, the accent role overrides, and
+ * the resolved variant's semantic tokens (including terminal ANSI and editor
+ * roles). CSS custom properties cascade, so terminals and editors update live
+ * without remounting.
+ *
+ * The default `adea-light`/`adea-dark` variants skip the palette override —
+ * `styles/theme.css` declares those tokens already, and leaving them CSS-owned
+ * keeps first paint byte-identical to the pre-#425 app.
+ */
+export declare function applyAppearanceToDocument(document: Document, state: ResolvedAppearanceState): void;
+/**
+ * The no-flash preload script rendered in the document head. It re-resolves
+ * the stored (or legacy) preference against the OS before first paint and
+ * applies the same palette state the provider would, so hydration never shows
+ * the wrong palette. Accent overrides land with the provider: they decorate
+ * the resolved palette and cannot produce a wrong-palette flash.
+ */
+export declare function appearanceThemeScript(): string;
+export {};