waybetter 0.1.1 → 0.7.0

package/dist/runtime/themeComponents.d.ts

@@ -0,0 +1,435 @@
+import { type FontRoleName } from './themeApi.ts';
+/** Color roles a component may name. `onAccent` is the readable label on the accent. */
+export declare const COLOR_ROLES: readonly ["bg", "surface", "elevated", "page", "border", "text", "muted", "accent", "onAccent", "inverse", "onInverse"];
+export type ColorRole = typeof COLOR_ROLES[number];
+export type RoleColors = Record<ColorRole, string>;
+export declare const BORDER_STYLES: readonly ["none", "solid", "dashed", "dotted", "double", "bevel-out", "bevel-in"];
+export declare const SHADOWS: readonly ["none", "soft", "deep", "hard", "inset", "glow"];
+export declare const CASES: readonly ["none", "upper", "lower", "capitalize", "small-caps"];
+export declare const AVATAR_SHAPES: readonly ["circle", "rounded", "square", "squircle", "hexagon", "octagon", "diamond"];
+export declare const CORNERS: readonly ["round", "cut"];
+export type Gradient = {
+    from: ColorRole;
+    to: ColorRole;
+    angle: number;
+};
+export type Fill = ColorRole | 'transparent' | 'glass' | Gradient;
+export type StateTokens = {
+    fill?: Fill;
+    text?: ColorRole;
+    borderColor?: ColorRole;
+    shadow?: typeof SHADOWS[number];
+    lift?: number;
+    scale?: number;
+    underline?: boolean;
+};
+export type ComponentTokens = {
+    preset?: string;
+    radius?: number | 'pill';
+    borderWidth?: number;
+    borderStyle?: typeof BORDER_STYLES[number];
+    borderColor?: ColorRole;
+    fill?: Fill;
+    text?: ColorRole;
+    padX?: number;
+    padY?: number;
+    gap?: number;
+    height?: number;
+    width?: number;
+    size?: number;
+    maxHeight?: number;
+    font?: FontRoleName;
+    fontSize?: number;
+    weight?: number;
+    case?: typeof CASES[number];
+    tracking?: number;
+    leading?: number;
+    shadow?: typeof SHADOWS[number];
+    shape?: typeof AVATAR_SHAPES[number];
+    corner?: typeof CORNERS[number];
+    visible?: boolean;
+    hover?: StateTokens;
+    active?: StateTokens;
+    focus?: StateTokens;
+};
+/** Every component a theme can name. Sites map them to selectors; a component a site does not have is ignored. */
+export declare const COMPONENTS: {
+    readonly nav: {
+        readonly width: [56, 320];
+        readonly glass: true;
+        readonly gradient: true;
+    };
+    readonly navItem: {
+        readonly height: [36, 64];
+        readonly fontSize: [number, number];
+        readonly text: true;
+    };
+    readonly topBar: {
+        readonly height: [40, 64];
+        readonly glass: true;
+        readonly gradient: true;
+        readonly fontSize: [number, number];
+    };
+    readonly tabs: {
+        readonly presets: "tabs";
+        readonly gradient: true;
+    };
+    readonly tab: {
+        readonly height: [32, 56];
+        readonly fontSize: [number, number];
+        readonly text: true;
+        readonly presets: "tabs";
+    };
+    readonly post: {
+        readonly corner: true;
+        readonly presets: "post";
+        readonly contrast: 7;
+    };
+    readonly avatar: {
+        readonly size: [20, 64];
+        readonly shape: true;
+        readonly visible: true;
+    };
+    readonly displayName: {
+        readonly text: true;
+        readonly fontSize: [number, number];
+        readonly visible: true;
+    };
+    readonly handle: {
+        readonly text: true;
+        readonly fontSize: [number, number];
+        readonly visible: true;
+    };
+    readonly postText: {
+        readonly text: true;
+        readonly fontSize: [13, 24];
+        readonly contrast: 7;
+    };
+    readonly meta: {
+        readonly text: true;
+        readonly fontSize: [number, number];
+    };
+    readonly actionBar: {};
+    readonly action: {
+        readonly size: [28, 44];
+    };
+    readonly count: {
+        readonly text: true;
+        readonly fontSize: [number, number];
+        readonly visible: true;
+    };
+    readonly media: {
+        readonly corner: true;
+        readonly maxHeight: [200, 700];
+    };
+    readonly linkCard: {
+        readonly corner: true;
+    };
+    readonly quote: {};
+    readonly button: {
+        readonly height: [24, 56];
+        readonly fontSize: [number, number];
+        readonly text: true;
+        readonly gradient: true;
+        readonly presets: "button";
+    };
+    readonly buttonPrimary: {
+        readonly parent: "button";
+        readonly height: [24, 56];
+        readonly fontSize: [number, number];
+        readonly text: true;
+        readonly gradient: true;
+        readonly presets: "button";
+    };
+    readonly buttonSecondary: {
+        readonly parent: "button";
+        readonly height: [24, 56];
+        readonly fontSize: [number, number];
+        readonly text: true;
+        readonly gradient: true;
+        readonly presets: "button";
+    };
+    readonly buttonGhost: {
+        readonly parent: "button";
+        readonly height: [24, 56];
+        readonly fontSize: [number, number];
+        readonly text: true;
+        readonly gradient: true;
+        readonly presets: "button";
+    };
+    readonly input: {
+        readonly height: [32, 56];
+        readonly fontSize: [number, number];
+        readonly text: true;
+        readonly presets: "input";
+    };
+    readonly search: {
+        readonly height: [32, 56];
+        readonly fontSize: [number, number];
+        readonly text: true;
+        readonly presets: "input";
+    };
+    readonly composer: {
+        readonly fontSize: [13, 24];
+        readonly text: true;
+    };
+    /** The tool icons under a composer (media, poll, emoji); `text` is their color. */
+    readonly composerTool: {
+        readonly size: [28, 44];
+    };
+    readonly panel: {
+        readonly glass: true;
+        readonly presets: "panel";
+    };
+    readonly menu: {
+        readonly parent: "panel";
+        readonly glass: true;
+        readonly presets: "panel";
+    };
+    readonly dialog: {
+        readonly parent: "panel";
+        readonly glass: true;
+        readonly presets: "panel";
+    };
+    readonly toast: {
+        readonly parent: "panel";
+        readonly glass: true;
+        readonly presets: "panel";
+    };
+    readonly hoverCard: {
+        readonly parent: "panel";
+        readonly glass: true;
+        readonly presets: "panel";
+    };
+    readonly sidebarCard: {
+        readonly parent: "panel";
+        readonly glass: true;
+        readonly corner: true;
+        readonly presets: "panel";
+    };
+    readonly badge: {
+        readonly size: [14, 24];
+        readonly corner: true;
+        readonly fontSize: [number, number];
+        readonly text: true;
+    };
+    readonly pill: {
+        readonly fontSize: [number, number];
+        readonly text: true;
+    };
+    readonly divider: {};
+    readonly scrollbar: {};
+    readonly profileHeader: {};
+};
+export type ComponentId = keyof typeof COMPONENTS;
+export declare const COMPONENT_IDS: ComponentId[];
+export type ThemeComponents = Partial<Record<ComponentId, ComponentTokens>>;
+/** Clamp ranges of the tokens every component shares (the JSON Schema says the same; tested). */
+export declare const TOKEN_LIMITS: {
+    readonly radius: readonly [0, 32];
+    readonly borderWidth: readonly [0, 4];
+    readonly padX: readonly [0, 32];
+    readonly padY: readonly [0, 32];
+    readonly gap: readonly [0, 24];
+    readonly weight: readonly [100, 900];
+    readonly tracking: readonly [-0.05, 0.2];
+    readonly leading: readonly [1.1, 2];
+    readonly angle: readonly [0, 360];
+    readonly lift: readonly [0, 4];
+    readonly scale: readonly [0.96, 1.04];
+};
+/** Named token bundles per family; a theme's own tokens win over its preset's. Frozen once shipped. */
+export declare const PRESETS: {
+    readonly button: {
+        readonly pill: {
+            readonly radius: "pill";
+            readonly borderWidth: 0;
+        };
+        readonly soft: {
+            readonly radius: 8;
+            readonly borderWidth: 0;
+        };
+        readonly square: {
+            readonly radius: 0;
+            readonly borderWidth: 1;
+            readonly borderStyle: "solid";
+        };
+        readonly outline: {
+            readonly radius: 6;
+            readonly borderWidth: 1;
+            readonly borderStyle: "solid";
+            readonly fill: "transparent";
+            readonly text: "text";
+            readonly borderColor: "border";
+        };
+        readonly bevel: {
+            readonly radius: 0;
+            readonly borderStyle: "bevel-out";
+            readonly fill: "surface";
+            readonly text: "text";
+            readonly active: {
+                readonly shadow: "inset";
+            };
+        };
+        readonly gloss: {
+            readonly radius: "pill";
+            readonly borderWidth: 1;
+            readonly borderStyle: "solid";
+            readonly shadow: "soft";
+        };
+        readonly 'flat-link': {
+            readonly radius: 0;
+            readonly borderWidth: 0;
+            readonly fill: "transparent";
+            readonly text: "accent";
+            readonly hover: {
+                readonly underline: true;
+            };
+        };
+    };
+    readonly post: {
+        readonly flat: {
+            readonly radius: 0;
+            readonly borderWidth: 0;
+            readonly fill: "transparent";
+            readonly shadow: "none";
+        };
+        readonly card: {
+            readonly radius: 14;
+            readonly borderWidth: 1;
+            readonly borderStyle: "solid";
+            readonly borderColor: "border";
+            readonly fill: "surface";
+        };
+        readonly bubble: {
+            readonly radius: 20;
+            readonly borderWidth: 0;
+            readonly fill: "surface";
+        };
+        readonly window: {
+            readonly radius: 0;
+            readonly borderStyle: "bevel-out";
+            readonly fill: "surface";
+        };
+        readonly ruled: {
+            readonly radius: 0;
+            readonly borderWidth: 0;
+            readonly fill: "transparent";
+        };
+    };
+    readonly input: {
+        readonly pill: {
+            readonly radius: "pill";
+            readonly borderWidth: 1;
+            readonly borderStyle: "solid";
+            readonly borderColor: "border";
+        };
+        readonly underline: {
+            readonly radius: 0;
+            readonly borderWidth: 0;
+            readonly fill: "transparent";
+        };
+        readonly sunken: {
+            readonly radius: 0;
+            readonly borderStyle: "bevel-in";
+            readonly fill: "bg";
+            readonly text: "text";
+        };
+        readonly boxed: {
+            readonly radius: 4;
+            readonly borderWidth: 1;
+            readonly borderStyle: "solid";
+            readonly borderColor: "border";
+            readonly fill: "bg";
+        };
+    };
+    readonly panel: {
+        readonly sheet: {
+            readonly radius: 12;
+            readonly borderWidth: 1;
+            readonly borderStyle: "solid";
+            readonly borderColor: "border";
+            readonly fill: "surface";
+            readonly shadow: "soft";
+        };
+        readonly window: {
+            readonly radius: 0;
+            readonly borderStyle: "bevel-out";
+            readonly fill: "surface";
+            readonly shadow: "none";
+        };
+        readonly glass: {
+            readonly radius: 16;
+            readonly borderWidth: 1;
+            readonly borderStyle: "solid";
+            readonly borderColor: "border";
+            readonly fill: "glass";
+            readonly shadow: "soft";
+        };
+    };
+    readonly tabs: {
+        readonly underline: {
+            readonly radius: 0;
+        };
+        readonly pills: {
+            readonly radius: "pill";
+        };
+        readonly folder: {
+            readonly radius: 6;
+            readonly borderWidth: 1;
+            readonly borderStyle: "solid";
+            readonly borderColor: "border";
+        };
+        readonly blocks: {
+            readonly radius: 0;
+            readonly borderWidth: 1;
+            readonly borderStyle: "solid";
+            readonly borderColor: "border";
+        };
+    };
+};
+/** One component's tokens from JSON: clamped, unknown names and tokens the component does not take dropped. */
+export declare function sanitizeComponentTokens(id: ComponentId, value: unknown): ComponentTokens | undefined;
+/** The `components` group from JSON. Null when nothing valid is left (the theme sets no component). */
+export declare function sanitizeComponents(value: unknown): ThemeComponents | null;
+/** Every component with its preset and its parent's tokens folded in (own tokens win, then the preset, then the parent). */
+export declare function resolveComponents(components: ThemeComponents): ThemeComponents;
+/** A site's selectors for one component. */
+export type PartDef = {
+    /** The component's box. */
+    sel: string;
+    /** Its text leaves (sites often put type on leaf spans); defaults to the box. */
+    text?: string;
+    /** Where a fill is painted when it is not the box itself. */
+    fill?: string;
+    /** Tokens the site cannot honor on this part (left out of the CSS). */
+    skip?: ReadonlyArray<keyof ComponentTokens>;
+};
+export type PartMap = Partial<Record<ComponentId, PartDef>>;
+export type ComponentContext = {
+    /** Every role as `#rrggbb` (the theme's palette, legible). */
+    colors: RoleColors;
+    /** `font-family` per font role. */
+    fonts: Record<FontRoleName, string>;
+};
+/** The most readable of the theme's text-capable roles on `fill`. */
+export declare function readableRole(fill: string, colors: RoleColors, preferred?: ColorRole): ColorRole;
+/** A part rule's selector: two `:root`s lift it over the site's atomic classes and inline styles' non-important values. */
+export declare const partRule: (selector: string) => string;
+export type CompiledComponents = {
+    /** `--wb-part-*` declarations (for `:where(:root)`). */
+    values: string[];
+    /** Rules that read them. */
+    rules: string[];
+    /** What the contrast pass changed, for import notes and the builder's report. */
+    notes: string[];
+};
+/**
+ * CSS for a theme's components over a site's part map. A component without a part, and a token the
+ * part skips, emits nothing. Text on a fill the theme chose is held to the component's contrast
+ * (the text role is swapped for the most readable one); sizes stay at or above a 24px target.
+ */
+export declare function compileComponents(components: ThemeComponents, parts: PartMap, ctx: ComponentContext): CompiledComponents;
+/** The `colors.actions` group: the colors of an on state (liked, reposted, bookmarked) and of the reply hover. */
+export declare const ACTION_NAMES: readonly ["reply", "repost", "like", "bookmark"];
+export type ActionColors = Partial<Record<typeof ACTION_NAMES[number], string>>;