eidos-ui 2.1.0 → 3.1.0

package/README.md

@@ -19,14 +19,14 @@
 
 ## Features
 
-|                     |                                                                                                                        |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **Themeable**       | Every design token is a CSS custom property, so palette, spacing, and radii can be overridden without touching source. |
-| **Type-safe**       | Written in TypeScript with full prop typings exported for every component.                                             |
-| **Tree-shakeable**  | Per-component entry points (`eidos-ui/button`, `eidos-ui/table`, ...) keep bundles lean.                               |
-| **Icon-agnostic**   | Works with any icon library - Lucide, MUI Icons, Font Awesome, Remix Icons, or your own.                               |
-| **Accessible**      | Built with keyboard navigation and ARIA semantics in mind.                                                             |
-| **Optimized build** | Bundled with tsup, shipping both ESM and CJS with source maps and `.d.ts` files.                                       |
+|                     |                                                                                                                                                        |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Themeable**       | Every design token is a CSS custom property. Override them statically, or let users change the palette and typography at runtime with `ThemeProvider`. |
+| **Type-safe**       | Written in TypeScript with full prop typings exported for every component.                                                                             |
+| **Tree-shakeable**  | Per-component entry points (`eidos-ui/button`, `eidos-ui/table`, ...) keep bundles lean.                                                               |
+| **Icon-agnostic**   | Works with any icon library - Lucide, MUI Icons, Font Awesome, Remix Icons, or your own.                                                               |
+| **Accessible**      | Built with keyboard navigation and ARIA semantics in mind.                                                                                             |
+| **Optimized build** | Bundled with tsup, shipping both ESM and CJS with source maps and `.d.ts` files.                                                                       |
 
 ## Installation
 
@@ -45,6 +45,7 @@ npm install lucide-react
 ```tsx
 import { Button, Tooltip } from 'eidos-ui';
 import 'eidos-ui/styles';
+import 'eidos-ui/fonts'; // optional - bundled Plus Jakarta Sans + JetBrains Mono
 
 function App() {
   return (
@@ -91,6 +92,11 @@ These are the same groups used in Storybook, so the README and the docs sidebar
 - Toolbar
 - Breadcrumb
 
+**Theming**
+
+- ThemeProvider
+- ThemeEditor
+
 **Elements**
 
 - Button
@@ -120,7 +126,6 @@ These are the same groups used in Storybook, so the README and the docs sidebar
 - Switch
 - Slider
 - ColorPicker
-- DatePicker
 - OTPInput
 - TagInput
 - FileUpload
@@ -139,7 +144,9 @@ These are the same groups used in Storybook, so the README and the docs sidebar
 **Data**
 
 - Table
+- TableFiltersDropdown
 - DataGrid
+- DatePicker
 - Timeline
 - VirtualList
 
@@ -180,15 +187,19 @@ npm run storybook
 
 ## Theming
 
-All design tokens are exposed as CSS custom properties, so themes can be overridden globally without touching component source.
+Every design token is a CSS custom property. There are two ways to change them, depending on whether the theme is fixed at build time or chosen by the user.
+
+### Static overrides
+
+Redeclare any token in your own stylesheet:
 
 ```css
 :root {
-  /* Colors */
-  --primary-color: #6366f1;
-  --secondary-color: #ec4899;
+  /* Colours - each family also has -dark, -light, -rgb and -contrast */
+  --primary-color: #5c5de8;
+  --secondary-color: #617087;
 
-  /* Spacing */
+  /* Spacing (em-based, so it scales with font size) */
   --spacing-md: 1em;
   --spacing-lg: 1.5em;
 
@@ -197,15 +208,54 @@ All design tokens are exposed as CSS custom properties, so themes can be overrid
 }
 ```
 
-Individual component styles can also be targeted directly, following each component's `eidos-<name>` BEM-style class names:
+Individual components can also be targeted directly, following each component's `eidos-<name>` BEM-style class names:
 
 ```css
 .eidos-button--filled.eidos-button--primary {
   border-radius: 20px;
-  background: linear-gradient(to right, #6366f1, #8b5cf6);
+  background: linear-gradient(to right, #5c5de8, #8b5cf6);
 }
 ```
 
+### Runtime theming
+
+`ThemeProvider` applies a theme at runtime — for a settings screen, a per-tenant palette, or a colour a user picks. Supply one base colour per family and the shades, tints, ramp steps and accessible foregrounds are derived from it:
+
+```tsx
+import { ThemeProvider, ThemeEditor } from 'eidos-ui';
+
+<ThemeProvider defaultTheme={{ colors: { primary: '#0ea5e9' } }}>
+  <App />
+</ThemeProvider>;
+```
+
+`ThemeEditor` is a ready-made panel for editing the active theme, with live WCAG contrast readouts per colour:
+
+```tsx
+<ThemeProvider theme={theme} onThemeChange={saveThemeForUser}>
+  <ThemeEditor />
+  <App />
+</ThemeProvider>
+```
+
+Ten things are editable — seven colour bases, two font stacks, and a font scale. Tokens are written through the CSSOM to `document.documentElement`, which needs **no Content Security Policy allowance** and covers portaled overlays too. A theme equal to the preset writes nothing at all.
+
+Use `useTheme()` to read or change it from your own UI, and `toCss()` to export the resolved tokens as a `:root` block you can paste into a stylesheet — useful for baking a theme in at build time.
+
+### Fonts
+
+The theme names Plus Jakarta Sans and JetBrains Mono, but a font stack only _names_ families — it cannot install them. Import the bundled copies to actually use them:
+
+```ts
+import 'eidos-ui/fonts';
+```
+
+This is a separate entry point because these are the only rules in the library that fetch a subresource; importing it means allowing `font-src 'self'` (already covered by `default-src 'self'`). Skip it and the stylesheet fetches nothing, falling back to system fonts.
+
+For a font of your own, `registerFontFace(family, arrayBuffer)` registers one at runtime with no CSP allowance at all.
+
+See the **Theming** and **Content Security Policy** pages in Storybook for the full reference.
+
 ## TypeScript
 
 Every component ships with exported prop types:

package/dist/ThemeProvider.types-DgXN0gEH.d.cts

@@ -0,0 +1,88 @@
+import React__default from 'react';
+
+/** The seven themeable colour families. */
+type ThemeColorKey = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'hyperlink';
+/**
+ * A themeable colour: either a bare hex string, or an object that also pins the
+ * foreground to place on it.
+ *
+ * `contrast` exists because the provider writes tokens inline on
+ * `document.documentElement`, and inline styles beat author stylesheets - a
+ * consumer who must have a specific foreground could otherwise only override it
+ * with `!important`. Leave it unset to have it computed (see `pickContrast`).
+ */
+type ThemeColorValue = string | {
+    base: string;
+    contrast?: string;
+};
+type ThemeColors = Partial<Record<ThemeColorKey, ThemeColorValue>>;
+/** A selectable font stack, as offered by `ThemeEditor`. */
+interface ThemeFontOption {
+    /** Display name, e.g. "Plus Jakarta Sans". */
+    label: string;
+    /** The full CSS font stack written to the token. */
+    value: string;
+}
+interface ThemeTypography {
+    /** Replaces `--font-family-primary`. A full CSS font stack. */
+    fontFamily?: string;
+    /** Replaces `--font-family-mono`. A full CSS font stack. */
+    monoFamily?: string;
+    /**
+     * Multiplier applied to all eight `--font-size-*` tokens. 1 is the preset.
+     *
+     * Note that `--spacing-*` is declared in `em`, so this scales most padding
+     * and gaps along with the text rather than only the glyphs.
+     */
+    fontScale?: number;
+}
+/**
+ * A theme. Every field is optional and anything omitted falls back to
+ * `defaultTheme`, so a theme may be as small as one colour.
+ *
+ * Named `ThemeConfig` rather than `Theme` to avoid colliding with the `Theme`
+ * exported by MUI, styled-components and others in a consumer's namespace.
+ */
+interface ThemeConfig {
+    colors?: ThemeColors;
+    typography?: ThemeTypography;
+}
+/** A theme with every field populated - what the provider actually applies. */
+interface ResolvedTheme {
+    colors: Record<ThemeColorKey, {
+        base: string;
+        contrast?: string;
+    }>;
+    typography: Required<ThemeTypography>;
+}
+interface ThemeContextValue {
+    /** The theme as supplied, with omitted fields left absent. */
+    theme: ThemeConfig;
+    /** The same theme with every field filled in from the preset. */
+    resolvedTheme: ResolvedTheme;
+    /** Replaces the whole theme. */
+    setTheme: (theme: ThemeConfig) => void;
+    /** Deep-merges a partial theme into the current one. */
+    updateTheme: (patch: ThemeConfig) => void;
+    /** Returns to the preset. */
+    resetTheme: () => void;
+    /** True when nothing differs from the preset, so no tokens are being written. */
+    isDefault: boolean;
+    /** The resolved theme as a `:root { … }` CSS block. */
+    toCss: () => string;
+}
+interface ThemeProviderProps {
+    children: React__default.ReactNode;
+    /**
+     * Controlled theme. Pair with `onThemeChange` and own persistence yourself -
+     * this is the mode to use when the theme comes from a user record on your
+     * server.
+     */
+    theme?: ThemeConfig;
+    /** Initial theme for uncontrolled usage. Ignored when `theme` is supplied. */
+    defaultTheme?: ThemeConfig;
+    /** Fires whenever the theme changes, in both controlled and uncontrolled mode. */
+    onThemeChange?: (theme: ThemeConfig) => void;
+}
+
+export type { ResolvedTheme as R, ThemeColorKey as T, ThemeColorValue as a, ThemeColors as b, ThemeConfig as c, ThemeContextValue as d, ThemeFontOption as e, ThemeProviderProps as f, ThemeTypography as g };

package/dist/ThemeProvider.types-DgXN0gEH.d.ts

@@ -0,0 +1,88 @@
+import React__default from 'react';
+
+/** The seven themeable colour families. */
+type ThemeColorKey = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'hyperlink';
+/**
+ * A themeable colour: either a bare hex string, or an object that also pins the
+ * foreground to place on it.
+ *
+ * `contrast` exists because the provider writes tokens inline on
+ * `document.documentElement`, and inline styles beat author stylesheets - a
+ * consumer who must have a specific foreground could otherwise only override it
+ * with `!important`. Leave it unset to have it computed (see `pickContrast`).
+ */
+type ThemeColorValue = string | {
+    base: string;
+    contrast?: string;
+};
+type ThemeColors = Partial<Record<ThemeColorKey, ThemeColorValue>>;
+/** A selectable font stack, as offered by `ThemeEditor`. */
+interface ThemeFontOption {
+    /** Display name, e.g. "Plus Jakarta Sans". */
+    label: string;
+    /** The full CSS font stack written to the token. */
+    value: string;
+}
+interface ThemeTypography {
+    /** Replaces `--font-family-primary`. A full CSS font stack. */
+    fontFamily?: string;
+    /** Replaces `--font-family-mono`. A full CSS font stack. */
+    monoFamily?: string;
+    /**
+     * Multiplier applied to all eight `--font-size-*` tokens. 1 is the preset.
+     *
+     * Note that `--spacing-*` is declared in `em`, so this scales most padding
+     * and gaps along with the text rather than only the glyphs.
+     */
+    fontScale?: number;
+}
+/**
+ * A theme. Every field is optional and anything omitted falls back to
+ * `defaultTheme`, so a theme may be as small as one colour.
+ *
+ * Named `ThemeConfig` rather than `Theme` to avoid colliding with the `Theme`
+ * exported by MUI, styled-components and others in a consumer's namespace.
+ */
+interface ThemeConfig {
+    colors?: ThemeColors;
+    typography?: ThemeTypography;
+}
+/** A theme with every field populated - what the provider actually applies. */
+interface ResolvedTheme {
+    colors: Record<ThemeColorKey, {
+        base: string;
+        contrast?: string;
+    }>;
+    typography: Required<ThemeTypography>;
+}
+interface ThemeContextValue {
+    /** The theme as supplied, with omitted fields left absent. */
+    theme: ThemeConfig;
+    /** The same theme with every field filled in from the preset. */
+    resolvedTheme: ResolvedTheme;
+    /** Replaces the whole theme. */
+    setTheme: (theme: ThemeConfig) => void;
+    /** Deep-merges a partial theme into the current one. */
+    updateTheme: (patch: ThemeConfig) => void;
+    /** Returns to the preset. */
+    resetTheme: () => void;
+    /** True when nothing differs from the preset, so no tokens are being written. */
+    isDefault: boolean;
+    /** The resolved theme as a `:root { … }` CSS block. */
+    toCss: () => string;
+}
+interface ThemeProviderProps {
+    children: React__default.ReactNode;
+    /**
+     * Controlled theme. Pair with `onThemeChange` and own persistence yourself -
+     * this is the mode to use when the theme comes from a user record on your
+     * server.
+     */
+    theme?: ThemeConfig;
+    /** Initial theme for uncontrolled usage. Ignored when `theme` is supplied. */
+    defaultTheme?: ThemeConfig;
+    /** Fires whenever the theme changes, in both controlled and uncontrolled mode. */
+    onThemeChange?: (theme: ThemeConfig) => void;
+}
+
+export type { ResolvedTheme as R, ThemeColorKey as T, ThemeColorValue as a, ThemeColors as b, ThemeConfig as c, ThemeContextValue as d, ThemeFontOption as e, ThemeProviderProps as f, ThemeTypography as g };