aktion-runtime 0.5.0

package/dist/types/theme/index.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Theme tokens applied as CSS custom properties on the host element.
+ *
+ * Built-in themes:
+ *   - "light"      (default)
+ *   - "dark"
+ *   - "neon"       (cyberpunk-inspired, dark with glowing accents)
+ *   - "pastel"     (soft, friendly, light & rounded)
+ *   - "glass"      (frosted glass, translucent surfaces, vivid gradient bg)
+ *   - "brutalist"  (neo-brutalism, hard edges, thick borders, bold colors)
+ *   - "skyline"    (deep navy + cyan, crisp & calm)
+ *
+ * Consumers can also pass a JSON object via the `theme` attribute, call
+ * `element.setTheme({...})`, or declare `theme = Theme({...})` inside a
+ * Aktion program. All three paths flow through `mergeTheme`
+ * so partial token maps are layered on top of the `light` defaults.
+ *
+ * Token taxonomy:
+ *   - **Color** — surface, semantic, brand accents, focus ring.
+ *   - **Typography** — body and heading families, sizes, weights, line
+ *     heights, letter spacing, and heading text-transform. Enough surface
+ *     to mirror brand systems (GitHub, Stripe, Apple, IONOS, Notion, …).
+ *   - **Shape & spacing** — radii (xs/sm/md/lg/pill/button/input), border
+ *     width, shadows, spacing scale.
+ *   - **Buttons** — font-weight, text-transform, letter-spacing, padding.
+ *   - **Charts** — six rotating series colors.
+ *   - **Motion** — transition duration shared by hover / focus animations.
+ */
+export interface ThemeTokens {
+    colorBg: string;
+    colorBgSubtle: string;
+    colorSurface: string;
+    colorSurfaceMuted: string;
+    colorBorder: string;
+    colorBorderSubtle: string;
+    colorText: string;
+    colorTextMuted: string;
+    colorPrimary: string;
+    colorPrimaryHover: string;
+    colorPrimaryText: string;
+    /** Secondary brand accent (links, chips, callouts). Defaults to primary. */
+    colorAccent: string;
+    colorAccentHover: string;
+    colorAccentText: string;
+    /** Focus ring color (CSS color). Defaults to primary. */
+    colorFocusRing: string;
+    colorSuccess: string;
+    colorWarning: string;
+    colorDanger: string;
+    colorInfo: string;
+    fontFamily: string;
+    /** Font stack used for headings (Card title, Page header, SectionHeader…). */
+    fontFamilyHeading: string;
+    fontFamilyMono: string;
+    /** Root font size — body text defaults to this value. */
+    fontSizeBase: string;
+    fontSizeSm: string;
+    fontSizeLg: string;
+    /** Font size for Card/Section headings. */
+    fontSizeHeading: string;
+    /** Font size for page-level titles (PageHeader, Cover, Hero). */
+    fontSizeTitle: string;
+    fontWeightBody: string;
+    fontWeightHeading: string;
+    lineHeightBody: string;
+    lineHeightHeading: string;
+    /** Letter spacing applied to titles & headings (e.g. "-0.01em"). */
+    letterSpacingHeading: string;
+    /** `text-transform` applied to titles & headings (e.g. "uppercase"). */
+    headingTextTransform: string;
+    /** Micro radius (pills, dots, status chips). */
+    radiusXs: string;
+    radiusSm: string;
+    radiusMd: string;
+    radiusLg: string;
+    /** Fully-rounded radius — `999px` by default. */
+    radiusPill: string;
+    /** Button-specific radius. Falls back to `radiusSm`. */
+    radiusButton: string;
+    /** Input-specific radius. Falls back to `radiusSm`. */
+    radiusInput: string;
+    /** Width of every solid border (default 1px; brutalist uses 2px). */
+    borderWidth: string;
+    shadowSm: string;
+    shadowMd: string;
+    shadowLg: string;
+    spacingXs: string;
+    spacingS: string;
+    spacingM: string;
+    spacingL: string;
+    spacingXl: string;
+    buttonFontWeight: string;
+    buttonTextTransform: string;
+    buttonLetterSpacing: string;
+    buttonPaddingY: string;
+    buttonPaddingX: string;
+    transitionDuration: string;
+    chart1: string;
+    chart2: string;
+    chart3: string;
+    chart4: string;
+    chart5: string;
+    chart6: string;
+}
+export declare const lightTheme: ThemeTokens;
+export declare const darkTheme: ThemeTokens;
+/**
+ * Neon — cyberpunk-flavoured dark mode. Magenta/cyan glow, sharper corners,
+ * monospace headings, and high-contrast surfaces.
+ */
+export declare const neonTheme: ThemeTokens;
+/**
+ * Pastel — soft, friendly, light and rounded. Larger paddings, big radii,
+ * lavender + mint palette, gentle shadows.
+ */
+export declare const pastelTheme: ThemeTokens;
+/**
+ * Glass — modern glassmorphism. Vivid gradient backdrop, frosted translucent
+ * surfaces (real backdrop-filter blur applied via the stylesheet), generous
+ * radii, and a cool indigo→cyan accent. Designed for hero sections and
+ * marketing-style UIs.
+ */
+export declare const glassTheme: ThemeTokens;
+/**
+ * Brutalist — neo-brutalism. Hard 2px black borders, chunky offset shadows,
+ * loud primary colors, all-caps display type, and zero gradients. Designed
+ * to look hand-built and unapologetically bold.
+ */
+export declare const brutalistTheme: ThemeTokens;
+/**
+ * Skyline — enterprise cloud-console aesthetic. Deep navy primary, calm
+ * cyan accents, very pale blue page background, white surfaces with crisp
+ * 1px borders, small radii, and a clean Inter type stack. The look should
+ * feel at home in an admin panel: dense, scannable, minimal chrome.
+ */
+export declare const skylineTheme: ThemeTokens;
+export declare const builtInThemes: Record<string, ThemeTokens>;
+export type ThemeInput = string | Partial<ThemeTokens>;
+export interface ResolvedTheme {
+    /** Built-in theme name when known, otherwise "custom". Drives `data-rui-theme`. */
+    name: string;
+    tokens: ThemeTokens;
+}
+export declare function resolveTheme(input: ThemeInput | null | undefined): ResolvedTheme;
+/**
+ * Apply theme tokens to the host element. Also sets `data-rui-theme` so the
+ * shadow-DOM stylesheet can hook into theme-specific overrides (fonts,
+ * gradients, animations, etc.) that go beyond raw token values.
+ */
+export declare function applyTheme(host: HTMLElement, theme: ResolvedTheme | ThemeTokens): void;
+/**
+ * Apply *only* the tokens explicitly listed in `partial`. Leaves every other
+ * CSS variable untouched, so this composes cleanly on top of whatever base
+ * theme `applyTheme(...)` last wrote. Used by the in-script `Theme(...)`
+ * construct so authors can override just a handful of tokens without
+ * wiping the rest of the active theme.
+ *
+ * Unknown keys are ignored — both for forward compatibility and to keep
+ * malformed LLM output from polluting the host's inline styles.
+ */
+export declare function applyPartialTheme(host: HTMLElement, partial: Partial<ThemeTokens>): ReadonlyArray<keyof ThemeTokens>;
+/**
+ * Remove an array of token CSS variables from the host's inline style. Used
+ * to "undo" a previous `applyPartialTheme(...)` call so the next render
+ * inherits whatever the base theme provides rather than the stale override.
+ */
+export declare function clearTokenOverrides(host: HTMLElement, keys: ReadonlyArray<keyof ThemeTokens>): void;
+/**
+ * Filter an arbitrary object down to the keys recognised by `ThemeTokens`,
+ * stringifying primitive values along the way. Used when an Aktion program
+ * declares `theme = Theme({...})` — the evaluator hands us
+ * a plain JS object, and we want to ignore anything that isn't a real token
+ * (LLM typo guard) before applying it.
+ */
+export declare function sanitiseThemeTokens(input: unknown): Partial<ThemeTokens>;