@lyeve-labs/ui-kit 0.17.0 → 0.18.0

package/dist/styles/theme.css

@@ -79,6 +79,61 @@
   --radius-xl: 16px;
   --radius-2xl: 24px;
 
+  /* -- Elevation - the stacking order of everything that floats --- *
+   *  Every floating surface in the kit carried a bare z-50, so which
+   *  one won was decided by document order: a Dropdown opened after a
+   *  Modal painted over it, and the same two in the other order did
+   *  not. The layer a surface belongs to is a property of the surface,
+   *  so it is named here once and each component asks for its layer by
+   *  name.
+   *
+   *  The ramp starts at 100 and leaves everything below it to the
+   *  consuming app. The admin's own chrome sits at z-10 and z-20
+   *  today, and a kit layer landing on either number would tie with
+   *  it and resolve, again, by document order.
+   *
+   *  The steps are 100 apart because one of these layers holds a
+   *  stack rather than a surface: the dialog manager offsets each
+   *  dialog above the one it opened over, and a ramp in steps of ten
+   *  would put the eleventh dialog through the ceiling of its own
+   *  layer and under the tooltip above it.
+   *
+   *  tooltip sits above modal because a tooltip on a control inside a
+   *  dialog is drawn while that dialog is the topmost surface. toast
+   *  sits above tooltip because it reports the outcome of the action
+   *  the tooltip described. skip-link is above everything: it is the
+   *  first focusable thing in the document and nothing may cover it.
+   *
+   *  No sticky rung is declared. Nothing in the kit is sticky or
+   *  fixed below the dropdown layer, and a token no rule reads is the
+   *  defect this scale was written to end.                           */
+  --z-index-dropdown: 100; /* a panel anchored to its trigger    */
+  --z-index-overlay: 200; /* the scrim behind a drawer or modal */
+  --z-index-drawer: 300; /* a panel docked to a viewport edge  */
+  --z-index-modal: 400; /* a centred dialog, and the stack    */
+  --z-index-tooltip: 500; /* a label attached to a control      */
+  --z-index-toast: 600; /* transient status                   */
+  --z-index-skip-link: 700; /* the first tab stop in the document */
+
+  /* -- Motion - how long a transition or an entrance runs -------- *
+   *  Four durations shipped as literals inside the animate-[...]
+   *  utility of the component that used them, so the only way to
+   *  read the kit's motion was to grep four components. They are
+   *  stated here at the values they already ran at.
+   *
+   *  Tailwind builds no utility from a --duration-* token: there is
+   *  no such theme namespace, and `duration-collapse` compiles to
+   *  nothing at all. Each one is read through var() from an
+   *  arbitrary utility instead, which is why they are listed in
+   *  VAR_ONLY in theme-tokens.test.ts.
+   *
+   *  The reduced-motion block at the foot of this file overrides
+   *  every one of them and stays the authority on whether they run. */
+  --duration-modal-in: 120ms; /* Modal, the centred entrance   */
+  --duration-toast-in: 140ms; /* Toaster, one toast arriving   */
+  --duration-drawer-in: 150ms; /* Drawer, either edge           */
+  --duration-collapse: 200ms; /* Accordion and Collapsible     */
+
   /* ── Typography · families ───────────────────────────────────── */
   --font-sans:
     'Inter', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial,
@@ -181,6 +236,65 @@ html[data-theme='light'] {
   --color-danger: #ab1a1a;
 }
 
+/*
+ * The entrance keyframes, declared here and not in the components that play
+ * them.
+ *
+ * Modal, Drawer and Toaster each held their own `@keyframes` in a scoped
+ * `<style>` block and started it from a Tailwind `animate-[...]` class. Svelte
+ * renames a scoped keyframe to `svelte-<hash>-<name>` and rewrites only the
+ * references inside that same style block, so the class asked the browser for
+ * `modal-in` while the only rule declared was `svelte-ta60gp-modal-in`. An
+ * animation-name that resolves to nothing is not an error: the element simply
+ * appears, and all four entrances had been dead in every consumer.
+ *
+ * A keyframe named from a class has to be global, and the file every consumer
+ * already imports is the one place it can be global from.
+ */
+@keyframes modal-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px) scale(0.98);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+@keyframes drawer-in-right {
+  from {
+    opacity: 0;
+    transform: translateX(16px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+@keyframes drawer-in-left {
+  from {
+    opacity: 0;
+    transform: translateX(-16px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+@keyframes toast-in {
+  from {
+    opacity: 0;
+    transform: translateX(12px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
 @layer base {
   html {
     background-color: var(--color-ink);
@@ -238,3 +352,124 @@ html[data-theme='light'] {
     }
   }
 }
+
+/*
+ * Print.
+ *
+ * The estate had no `@media print` rule anywhere, and three surfaces print:
+ * the portal prints an invoice, the ops console prints an audit log, the admin
+ * prints a subject-access export. All three printed the sidebar, the theme
+ * toggle and the nav, in a dark palette, and all three printed one screenful
+ * and stopped, because the shell is `h-screen` with the content column set to
+ * `overflow-auto` and paper has neither a viewport nor a scrollbar.
+ *
+ * These rules are deliberately outside `@layer base`. An unlayered declaration
+ * beats every layered one whatever its specificity, so a `bg-surface` utility
+ * on a card cannot put the dark surface back.
+ *
+ * Three markers, each stating what paper needs rather than what an element is:
+ *
+ *   data-print="hide"    chrome that exists to navigate. Paper cannot be
+ *                        navigated, so it is noise on every page.
+ *   data-print="unclip"  a box that clips on screen because the screen is a
+ *                        fixed height. On paper it must give up its height and
+ *                        its overflow or the content past the first page is
+ *                        never printed.
+ *   data-print="keep"    a block that reads as one thing and must not be split
+ *                        across a page break.
+ */
+@media print {
+  /*
+   * The palette, not the components.
+   *
+   * Every kit component paints from these tokens, so redefining them here
+   * turns the whole library monochrome without a single component knowing
+   * about paper. Browsers drop backgrounds when printing by default, which
+   * left light text on the white the printer supplies; naming white here means
+   * the two agree either way.
+   *
+   * The status hues collapse to black rather than to a print-safe tint. A
+   * colour that carries meaning on screen carries none through a mono printer,
+   * and a legible black label beats an unreadable coloured one.
+   */
+  html,
+  html[data-theme='light'] {
+    --color-ink: #ffffff;
+    --color-surface: #ffffff;
+    --color-surface-2: #ffffff;
+    --color-line: #999999;
+    --color-line-strong: #666666;
+    --color-fg: #000000;
+    --color-muted: #000000;
+    --color-faint: #000000;
+    --color-brand: #000000;
+    --color-brand-light: #000000;
+    --color-brand-deep: #000000;
+    --color-violet: #000000;
+    --color-success: #000000;
+    --color-warn: #000000;
+    --color-danger: #000000;
+    color-scheme: light;
+  }
+
+  html,
+  body {
+    background: #ffffff;
+    color: #000000;
+  }
+
+  [data-print='hide'] {
+    display: none !important;
+  }
+
+  /*
+   * height as well as overflow. The shell is `h-screen`, so releasing the
+   * overflow alone still caps the printed document at one viewport.
+   */
+  [data-print='unclip'] {
+    overflow: visible !important;
+    height: auto !important;
+    max-height: none !important;
+  }
+
+  [data-print='keep'],
+  tr,
+  li {
+    break-inside: avoid;
+  }
+
+  /* A table running past one page repeats its own column headings. */
+  thead {
+    display: table-header-group;
+  }
+
+  tfoot {
+    display: table-footer-group;
+  }
+
+  /*
+   * A heading orphaned at the foot of a page belongs to the section on the
+   * next one.
+   */
+  h1,
+  h2,
+  h3 {
+    break-after: avoid;
+  }
+
+  /*
+   * The target of a link, for the links a reader cannot follow from paper and
+   * could not guess.
+   *
+   * Absolute links only. An invoice full of "(/portal/invoices/8841)" after
+   * every internal link is noise, and the reader holding the paper is already
+   * inside that application. A caller whose absolute link is decorative, or
+   * whose text is the URL already, opts out per link.
+   */
+  a[href^='http']:not([data-print='bare'])::after {
+    content: ' <' attr(href) '>';
+    font-size: 0.85em;
+    font-weight: normal;
+    word-break: break-all;
+  }
+}

package/dist/utils/theme.d.ts

@@ -5,22 +5,87 @@
  * The `<ThemeToggle />` component uses these under the hood; you can also
  * call them directly when you need to set the theme from a layout, route
  * loader, or an inline `<script>` that runs before paint.
+ *
+ * Two vocabularies, and the distinction is the whole point:
+ *
+ *   Theme            what is painted. `dark` or `light`, and it is what
+ *                    `data-theme` holds and what every palette rule keys off.
+ *   ThemePreference  what the reader asked for. `dark`, `light`, or `system`,
+ *                    which is a standing instruction to follow the operating
+ *                    system rather than a colour.
+ *
+ * The kit resolved a preference in exactly one place, the pre-paint script,
+ * and nothing else could read it back. A control could therefore offer two
+ * states and no third, so a reader who wanted the operating system's choice
+ * had to keep re-picking it by hand, and one console forked ThemeToggle rather
+ * than ship that. `system` is now a value the storage key holds and every
+ * helper here understands.
  */
+/** What is painted. */
 export type Theme = 'dark' | 'light';
+/** What the reader asked for. `system` resolves against the OS at read time. */
+export type ThemePreference = Theme | 'system';
+/** The order a control cycles through, and the order a picker lists. */
+export declare const THEME_PREFERENCES: readonly ThemePreference[];
 /**
  * Inline-script payload that should run *before* the first paint to avoid
  * the flash-of-wrong-theme. Drop the returned string into a `<script>` tag
  * in the `<head>` of your app shell.
  *
  * Picks the theme in this order:
- *   1. `localStorage["lyeve-theme"]` if set
- *   2. The user's OS preference (`prefers-color-scheme`)
- *   3. Dark (the default brand palette)
+ *   1. `localStorage["lyeve-theme"]` when it holds `'light'` or `'dark'`
+ *   2. The user's OS preference (`prefers-color-scheme`), which is also what
+ *      the stored value `'system'` asks for
+ *   3. Dark (the default brand palette), including when storage throws
  */
 export declare function themeBootScript(): string;
+/**
+ * What the operating system is asking for.
+ *
+ * Dark unless the OS says light, which is the same fallback the pre-paint
+ * script uses and the same one a browser without `matchMedia` gets.
+ */
+export declare function systemTheme(): Theme;
+/** The theme a preference resolves to right now. */
+export declare function resolveTheme(preference: ThemePreference): Theme;
+/**
+ * What the reader asked for, from storage.
+ *
+ * `system` when nothing is stored, which is the default this kit resolves by
+ * and not a guess: an unanswered question is answered by the operating system,
+ * because the reader already answered it there.
+ */
+export declare function getThemePreference(): ThemePreference;
 /** Read the current theme. SSR-safe; returns `'dark'` on the server. */
 export declare function getTheme(): Theme;
+/**
+ * Record a preference, apply what it resolves to, and return the applied theme.
+ *
+ * `system` is stored under its own name rather than by clearing the key. The
+ * two are indistinguishable on the next read otherwise, and they are not the
+ * same thing: one reader chose to follow the OS and the other has not chosen
+ * anything yet. Both resolve identically today; only one of them is a decision
+ * a later default may not override.
+ */
+export declare function setThemePreference(preference: ThemePreference): Theme;
 /** Apply a theme and persist the choice to `localStorage`. */
 export declare function setTheme(theme: Theme): void;
+/**
+ * The next preference in `order`, wrapping at the end.
+ *
+ * Takes the list so a surface that offers only two states cycles through only
+ * those two. A preference that is not in the list starts the cycle at its
+ * first entry rather than falling out of it.
+ */
+export declare function nextThemePreference(current: ThemePreference, order?: readonly ThemePreference[]): ThemePreference;
 /** Flip between dark and light. Returns the new theme. */
 export declare function toggleTheme(): Theme;
+/**
+ * Call `onChange` whenever the operating system's choice changes. Returns the
+ * unsubscribe function, and a no-op one where there is no `matchMedia`.
+ *
+ * A page resolving `system` has to repaint when the OS flips at dusk. Without
+ * this the preference is honoured once, at load, and reads as ignored for the
+ * rest of the session.
+ */
+export declare function watchSystemTheme(onChange: (theme: Theme) => void): () => void;

package/dist/utils/theme.js

@@ -5,17 +5,46 @@
  * The `<ThemeToggle />` component uses these under the hood; you can also
  * call them directly when you need to set the theme from a layout, route
  * loader, or an inline `<script>` that runs before paint.
+ *
+ * Two vocabularies, and the distinction is the whole point:
+ *
+ *   Theme            what is painted. `dark` or `light`, and it is what
+ *                    `data-theme` holds and what every palette rule keys off.
+ *   ThemePreference  what the reader asked for. `dark`, `light`, or `system`,
+ *                    which is a standing instruction to follow the operating
+ *                    system rather than a colour.
+ *
+ * The kit resolved a preference in exactly one place, the pre-paint script,
+ * and nothing else could read it back. A control could therefore offer two
+ * states and no third, so a reader who wanted the operating system's choice
+ * had to keep re-picking it by hand, and one console forked ThemeToggle rather
+ * than ship that. `system` is now a value the storage key holds and every
+ * helper here understands.
+ */
+/**
+ * The one key every surface in the estate reads and writes.
+ *
+ * Not exported. A surface that needs the name has `getThemePreference` and
+ * `setThemePreference`; a surface that spells the key itself is how two of
+ * them ended up on different keys, with the control writing one and the
+ * pre-paint script reading the other.
  */
 const STORAGE_KEY = 'lyeve-theme';
+/** The order a control cycles through, and the order a picker lists. */
+export const THEME_PREFERENCES = ['light', 'dark', 'system'];
+function isPreference(value) {
+    return value === 'light' || value === 'dark' || value === 'system';
+}
 /**
  * Inline-script payload that should run *before* the first paint to avoid
  * the flash-of-wrong-theme. Drop the returned string into a `<script>` tag
  * in the `<head>` of your app shell.
  *
  * Picks the theme in this order:
- *   1. `localStorage["lyeve-theme"]` if set
- *   2. The user's OS preference (`prefers-color-scheme`)
- *   3. Dark (the default brand palette)
+ *   1. `localStorage["lyeve-theme"]` when it holds `'light'` or `'dark'`
+ *   2. The user's OS preference (`prefers-color-scheme`), which is also what
+ *      the stored value `'system'` asks for
+ *   3. Dark (the default brand palette), including when storage throws
  */
 export function themeBootScript() {
     return `(function () {
@@ -29,12 +58,69 @@ export function themeBootScript() {
     }
   })();`;
 }
+/**
+ * What the operating system is asking for.
+ *
+ * Dark unless the OS says light, which is the same fallback the pre-paint
+ * script uses and the same one a browser without `matchMedia` gets.
+ */
+export function systemTheme() {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+        return 'dark';
+    return window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
+}
+/** The theme a preference resolves to right now. */
+export function resolveTheme(preference) {
+    return preference === 'system' ? systemTheme() : preference;
+}
+/**
+ * What the reader asked for, from storage.
+ *
+ * `system` when nothing is stored, which is the default this kit resolves by
+ * and not a guess: an unanswered question is answered by the operating system,
+ * because the reader already answered it there.
+ */
+export function getThemePreference() {
+    if (typeof localStorage === 'undefined')
+        return 'system';
+    try {
+        const stored = localStorage.getItem(STORAGE_KEY);
+        return isPreference(stored) ? stored : 'system';
+    }
+    catch {
+        // Storage may be disabled (private mode, quota). Follow the OS.
+        return 'system';
+    }
+}
 /** Read the current theme. SSR-safe; returns `'dark'` on the server. */
 export function getTheme() {
     if (typeof document === 'undefined')
         return 'dark';
     return document.documentElement.getAttribute('data-theme') === 'light' ? 'light' : 'dark';
 }
+/**
+ * Record a preference, apply what it resolves to, and return the applied theme.
+ *
+ * `system` is stored under its own name rather than by clearing the key. The
+ * two are indistinguishable on the next read otherwise, and they are not the
+ * same thing: one reader chose to follow the OS and the other has not chosen
+ * anything yet. Both resolve identically today; only one of them is a decision
+ * a later default may not override.
+ */
+export function setThemePreference(preference) {
+    const theme = resolveTheme(preference);
+    if (typeof document !== 'undefined') {
+        document.documentElement.setAttribute('data-theme', theme);
+    }
+    try {
+        localStorage.setItem(STORAGE_KEY, preference);
+    }
+    catch {
+        // Storage may be disabled (private mode, quota); the attribute is applied
+        // either way, so the session the reader is in still honours the choice.
+    }
+    return theme;
+}
 /** Apply a theme and persist the choice to `localStorage`. */
 export function setTheme(theme) {
     if (typeof document === 'undefined')
@@ -47,9 +133,38 @@ export function setTheme(theme) {
         // Storage may be disabled (private mode, quota); fall through silently.
     }
 }
+/**
+ * The next preference in `order`, wrapping at the end.
+ *
+ * Takes the list so a surface that offers only two states cycles through only
+ * those two. A preference that is not in the list starts the cycle at its
+ * first entry rather than falling out of it.
+ */
+export function nextThemePreference(current, order = THEME_PREFERENCES) {
+    if (order.length === 0)
+        return current;
+    const at = order.indexOf(current);
+    return at === -1 ? order[0] : order[(at + 1) % order.length];
+}
 /** Flip between dark and light. Returns the new theme. */
 export function toggleTheme() {
     const next = getTheme() === 'dark' ? 'light' : 'dark';
     setTheme(next);
     return next;
 }
+/**
+ * Call `onChange` whenever the operating system's choice changes. Returns the
+ * unsubscribe function, and a no-op one where there is no `matchMedia`.
+ *
+ * A page resolving `system` has to repaint when the OS flips at dusk. Without
+ * this the preference is honoured once, at load, and reads as ignored for the
+ * rest of the session.
+ */
+export function watchSystemTheme(onChange) {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+        return () => { };
+    const query = window.matchMedia('(prefers-color-scheme: light)');
+    const handler = () => onChange(query.matches ? 'light' : 'dark');
+    query.addEventListener('change', handler);
+    return () => query.removeEventListener('change', handler);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyeve-labs/ui-kit",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "A clean, accessible, palette-aware Svelte 5 component library. The design system behind LyEve.",
   "license": "MIT",
   "author": "LyEve Labs <hello@lyeve.com>",
@@ -23,25 +23,9 @@
   ],
   "type": "module",
   "sideEffects": false,
-  "packageManager": "pnpm@11.25.0",
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "build": "pnpm version:check && svelte-package && publint && node scripts/check-dist.mjs",
-    "version:sync": "node scripts/sync-version.mjs",
-    "version:check": "node scripts/sync-version.mjs --check",
-    "package": "pnpm version:check && svelte-package && publint",
-    "prepublishOnly": "pnpm package",
-    "check": "svelte-check --tsconfig ./tsconfig.json",
-    "check:watch": "svelte-check --tsconfig ./tsconfig.json --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:ct": "playwright test --config playwright-ct.config.ts",
-    "format": "prettier --write .",
-    "format:check": "prettier --check ."
-  },
   "files": [
     "dist",
     "src/lib/styles",
@@ -60,7 +44,8 @@
     "./package.json": "./package.json"
   },
   "peerDependencies": {
-    "svelte": "^5.0.0"
+    "svelte": "^5.0.0",
+    "tailwindcss": "^4"
   },
   "publishConfig": {
     "access": "public"
@@ -82,5 +67,19 @@
     "svelte-check": "^4.4.8",
     "typescript": "^5.9.3",
     "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "pnpm version:check && svelte-package && publint && node scripts/check-dist.mjs",
+    "version:sync": "node scripts/sync-version.mjs",
+    "version:check": "node scripts/sync-version.mjs --check",
+    "package": "pnpm version:check && svelte-package && publint",
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-check --tsconfig ./tsconfig.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ct": "playwright test --config playwright-ct.config.ts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   }
-}
+}