@dxos/ui-theme 0.8.4-staging.ac66bdf99f → 0.9.1-main.c7dcc2e112

package/src/main.css

@@ -11,7 +11,17 @@
  */
 @layer properties, theme, dx-tokens, user-tokens, base, tw-base, dx-base, components, tw-components, dx-components, utilities;
 
-@import 'tailwindcss';
+/**
+ * `source(none)` disables Tailwind 4's automatic content discovery (which
+ * scans the project root, including `publicDir`). With auto-detection on,
+ * every write to `public/icons.svg` from `vite-plugin-icons` triggers a
+ * Tailwind CSS regeneration, which invalidates `main.css` through its
+ * import graph and produces a 3–5-ping HMR storm per icon-sprite write
+ * during cold-start (icons land in tight bursts as plugin chunks stream
+ * in). Explicit `@source` directives below replace the auto-scan with a
+ * stable, source-only set.
+ */
+@import 'tailwindcss' source(none);
 
 /* @theme extensions */
 @import './css/theme/animation.css';
@@ -28,6 +38,7 @@
 
 /* @layer dx-components (components) */
 @import './css/components/button.css';
+@import './css/components/card.css';
 @import './css/components/checkbox.css';
 @import './css/components/dialog.css';
 @import './css/components/focus.css';
@@ -35,7 +46,7 @@
 @import './css/components/panel.css';
 @import './css/components/link.css';
 @import './css/components/scrollbar.css';
-@import './css/components/selected.css';
+@import './css/components/state.css';
 @import './css/components/surface.css';
 @import './css/components/tag.css';
 @import './css/components/text.css';
@@ -54,15 +65,63 @@
 @import './css/integrations/tldraw.css';
 
 /**
- * Force-emit CSS variables for the full color palette for all: 
+ * With `source(none)` on the Tailwind import above, these are the *only*
+ * paths Tailwind scans for utility classes. Cover every workspace source
+ * directory so lazy-loaded plugin / UI / SDK chunks don't surface new
+ * utilities mid-session, and root-level HTML entrypoints (index.html,
+ * internal.html, …) are visible too.
+ *
+ * Paths are relative to this file (`packages/ui/ui-theme/src/main.css`):
+ *   ../../../          → `packages/`
+ *   ../../../../tools/ → `tools/`
+ *
+ * Tailwind ignores `node_modules` and common build/output dirs by default,
+ * so a broad workspace glob is safe *for scanning*.
+ *
+ * NOTE: Tailwind's scanner respects `.gitignore` (so `dist/` is never
+ * scanned), but it hands Vite a coarse `dir-dependency` glob and Vite
+ * re-expands that itself, ignoring only `node_modules`. That re-expansion
+ * sweeps `dist/**` `.d.ts` files into the watch set and causes a `main.css`
+ * HMR storm on every package rebuild. Build outputs are excluded from the
+ * dev watcher in `plugins/ThemePlugin.ts` (`server.watch.ignored`) rather
+ * than here, because `@source not` does NOT propagate to the glob Vite
+ * re-expands.
+ */
+@source '../../../**/*.{ts,tsx,html}';
+@source '../../../../tools/**/*.{ts,tsx,html}';
+
+/**
+ * Exclude generated/static data files that have no Tailwind classes but are
+ * large enough to dominate scan time. The oxide scanner tokenizes every byte;
+ * a single 5MB geo-data file can pin Vite at 100% CPU for tens of seconds on
+ * a cold start.
+ */
+@source not '../../../ui/react-ui-geo/data/**';
+@source not '../../../ui/solid-ui-geo/data/**';
+@source not '../../../apps/composer-app/src/plugins/welcome/components/Welcome/hero-image.ts';
+
+/**
+ * Force-emit CSS variables for the full color palette for all:
  * --color-{hue}-{shade}
  * --color-{hue}-{style}
  */
-@source inline("bg-{neutral,red,orange,amber,yellow,lime,green,emerald,teal,cyan,sky,blue,indigo,violet,purple,fuchsia,pink,rose}-{50,100,200,300,400,500,600,700,800,900,950}");
-@source inline("bg-{neutral,red,orange,amber,yellow,lime,green,emerald,teal,cyan,sky,blue,indigo,violet,purple,fuchsia,pink,rose}-{fill,surface,surface-text,text,border}");
-@source inline("border-{neutral,red,orange,amber,yellow,lime,green,emerald,teal,cyan,sky,blue,indigo,violet,purple,fuchsia,pink,rose}-border");
-@source inline("bg-{info,success,warning,error}-{fill,surface,surface-text,text,border}");
-@source inline("border-{info,success,warning,error}-border");
+@source inline('bg-{neutral,red,orange,amber,yellow,lime,green,emerald,teal,cyan,sky,blue,indigo,violet,purple,fuchsia,pink,rose}-{50,100,200,300,400,500,600,700,800,900,950}');
+@source inline('bg-{neutral,red,orange,amber,yellow,lime,green,emerald,teal,cyan,sky,blue,indigo,violet,purple,fuchsia,pink,rose}-{bg,bg-hover,fg,surface,text,border}');
+@source inline('bg-{primary,secondary}-{50,100,200,300,400,500,600,700,800,900,950}');
+@source inline('border-{neutral,red,orange,amber,yellow,lime,green,emerald,teal,cyan,sky,blue,indigo,violet,purple,fuchsia,pink,rose}-border');
+@source inline('bg-{info,success,warning,error}-{bg,surface,fg,text,border}');
+@source inline('border-{info,success,warning,error}-border');
+
+/**
+ * Force-emit tokens consumed by web components / .pcss files outside the
+ * Tailwind source-scan graph (e.g. lit-grid's dx-grid.pcss uses var(--color-grid-line)).
+ */
+@source inline('bg-grid-{surface,fg,line,highlight,comment,comment-active,selection-surface,selection-fg}');
+/* 
+ * Sidebar surfaces alias each other (e.g. header-surface -> l0-surface); force-emit so the vars
+ * exist in apps that use the alias but not the underlying utility (e.g. devtools). 
+ */
+@source inline('bg-{l0,r0,l1,r1}-surface');
 
 /**
  * Plugins must come after all imports.
@@ -84,4 +143,4 @@
 /** Supports mouse/trackpad (Web) */
 @custom-variant hover-hover (@media (hover: hover));
 /** Active navigation */
-@custom-variant is-current (&[aria-current]:not([aria-current="false"]));
+@custom-variant is-current (&[aria-current]:not([aria-current='false']));

package/src/plugins/ThemePlugin.ts

@@ -4,10 +4,11 @@
 
 /* eslint-disable no-console */
 
-import tailwindcss from '@tailwindcss/postcss';
+import tailwindcssPostcss from '@tailwindcss/postcss';
+import tailwindcssVite from '@tailwindcss/vite';
 import autoprefixer from 'autoprefixer';
 import { existsSync, readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import postcssImport from 'postcss-import';
 import postcssNesting from 'postcss-nesting';
 import { type HtmlTagDescriptor, type Plugin, type UserConfig } from 'vite';
@@ -40,8 +41,9 @@ export type ThemePluginOptions = {
 
 /**
  * Vite plugin to configure theme.
+ * Returns the official Tailwind Vite plugin (persistent incremental scanner) alongside the theme plugin.
  */
-export const ThemePlugin = (options: ThemePluginOptions): Plugin => {
+export const ThemePlugin = (options: ThemePluginOptions): Plugin[] => {
   // Prefer source CSS if available (monorepo dev), fall back to dist for installed package.
   const srcThemePath = resolve(import.meta.dirname, ROOT, 'src/main.css');
   const distThemePath = resolve(import.meta.dirname, '../main.css');
@@ -53,23 +55,65 @@ export const ThemePlugin = (options: ThemePluginOptions): Plugin => {
   const darkModeScriptPath = resolve(pluginsDir, 'dark-mode.ts');
   const mainCssPath = resolve(pluginsDir, 'main.css');
 
-  const config: ThemePluginOptions = {
-    srcCssPath: isMonorepo ? srcThemePath : distThemePath,
-    virtualFileId: '@dxos-theme',
-    ...options,
+  const config = {
+    srcCssPath: options.srcCssPath ?? (isMonorepo ? srcThemePath : distThemePath),
+    virtualFileId: options.virtualFileId ?? '@dxos-theme',
+    verbose: options.verbose,
   };
 
-  // Derive project root from the source location so Tailwind scans all packages.
-  const base = isMonorepo ? resolve(dirname(srcThemePath), ROOT) : undefined;
-
   if (process.env.DEBUG || options.verbose) {
     console.log('ThemePlugin:\n', JSON.stringify(config, null, 2));
   }
 
-  return {
+  // Trailing-edge debounce handle for theme CSS reloads (see `handleHotUpdate`).
+  let themeReloadTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const themePlugin: Plugin = {
     name: 'vite-plugin-dxos-ui-theme',
     config: (): UserConfig => {
       return {
+        server: {
+          watch: {
+            // Stop build outputs from driving HMR — they are the root of the
+            // `main.css` HMR storm.
+            //
+            // Tailwind's `@source` scanning (see `src/main.css`) registers its
+            // scanned source files as Vite watch dependencies of the compiled
+            // theme CSS. Tailwind's own scanner respects `.gitignore` (and the
+            // `@source not` directives), so it never *scans* `dist/`. BUT the
+            // scanner hands Vite a coarse `dir-dependency` glob — e.g.
+            // `{**/*.html,**/*.ts,**/*.tsx}` — and Vite re-expands that glob
+            // itself, ignoring only `node_modules` (not `.gitignore`, not the
+            // `@source not` negations). The re-expansion therefore sweeps in
+            // every `packages/*/dist/**/*.d.ts` (`.d.ts` matches `**/*.ts`),
+            // making each emitted declaration file a watch-dependency of
+            // `main.css`. A single package rebuild emits dozens of `.d.ts` in a
+            // tight burst, and each write re-invalidates the theme — 40+ HMR
+            // pings for `main.css` in one second, repeating on every rebuild.
+            //
+            // Ignoring build outputs in the watcher is also semantically
+            // correct: in dev the workspace resolves `@dxos/*` via the `source`
+            // export condition (see `vite-plugin-import-source`), so `dist/`
+            // is never consumed at runtime and its churn should never trigger
+            // HMR. Vite concatenates these patterns with its built-in ignores
+            // (`**/node_modules/**`, `**/.git/**`, …), so this is purely
+            // additive.
+            //
+            // `<root>/.claude/**` covers agent worktrees checked out under the
+            // repo root (`.claude/worktrees/<name>/packages/**`): they are full
+            // source copies, so the glob re-expansion above sweeps them in and
+            // every agent-side edit burst or checkout invalidates the theme in
+            // the user's dev server. The pattern is anchored at the resolved
+            // repo root (not `**/.claude/**`) because chokidar matches against
+            // absolute paths — a bare pattern would match *everything* when the
+            // dev server itself runs from inside a worktree whose path contains
+            // a `.claude` segment. `*.log` covers runtime log sinks (e.g.
+            // vite-plugin-log's `app.log` in the app root), which are appended
+            // continuously at runtime and must never feed back into the
+            // watcher.
+            ignored: ['**/dist/**', '**/out/**', '**/*.log', `${resolve(import.meta.dirname, ROOT, '.claude')}/**`],
+          },
+        },
         css: {
           postcss: {
             plugins: [
@@ -77,9 +121,11 @@ export const ThemePlugin = (options: ThemePluginOptions): Plugin => {
               postcssImport(),
               // Processes CSS nesting syntax.
               postcssNesting(),
-              // Processes Tailwind directives and generates utilities from scanned content.
-              // base points to project root so all packages are scanned (not just ui-theme).
-              tailwindcss(base !== undefined ? { base } : {}),
+              // Resolves @reference/@apply in `.pcss` files (e.g. lit-grid, lit-ui), which the
+              // @tailwindcss/vite plugin skips — its transform filter only matches `.css`.
+              // Theme `.css` files are compiled by @tailwindcss/vite first (enforce: 'pre'),
+              // so this plugin's quick-bail check passes them through untouched.
+              tailwindcssPostcss(),
               // Adds vendor prefixes.
               autoprefixer,
             ],
@@ -92,6 +138,42 @@ export const ThemePlugin = (options: ThemePluginOptions): Plugin => {
         return config.srcCssPath;
       }
     },
+    hotUpdate({ type, file, modules }) {
+      // Direct edits to CSS (the theme source or its imports) keep Vite's
+      // default immediate update for instant feedback while authoring styles.
+      if (this.environment.name !== 'client' || type !== 'update' || file.endsWith('.css')) {
+        return;
+      }
+
+      // Every content file Tailwind scans is registered as a dependency of the
+      // theme CSS — Vite models it as a file-only entry node whose importer is
+      // `main.css` — so each source-file save invalidates `main.css` and
+      // re-runs the monorepo-wide Tailwind scan. During an edit wave that
+      // serializes one full scan per save. Drop the theme-dep entries from the
+      // update (the changed module itself still hot-updates immediately) and
+      // reload the theme CSS once on the trailing edge of a quiet window, so a
+      // wave costs at most one scan.
+      const isThemeDep = (mod: (typeof modules)[number]): boolean =>
+        mod.file === config.srcCssPath ||
+        (mod.id === null &&
+          mod.importers.size > 0 &&
+          [...mod.importers].every((importer) => importer.file === config.srcCssPath));
+      if (!modules.some(isThemeDep)) {
+        return;
+      }
+
+      const environment = this.environment;
+      clearTimeout(themeReloadTimer);
+      themeReloadTimer = setTimeout(() => {
+        for (const mod of environment.moduleGraph.getModulesByFile(config.srcCssPath) ?? []) {
+          environment.reloadModule(mod).catch(() => {
+            // Server may be mid-restart; the next edit reschedules the reload.
+          });
+        }
+      }, 300);
+
+      return modules.filter((mod) => !isThemeDep(mod));
+    },
     transformIndexHtml: () => {
       // Apply .dark class to <html> synchronously before any scripts run, so that
       // the critical CSS html.dark rules apply on the very first paint.
@@ -122,4 +204,10 @@ export const ThemePlugin = (options: ThemePluginOptions): Plugin => {
       return [darkModeTag, layersTag, criticalTag];
     },
   };
+
+  // The Tailwind Vite plugins are `enforce: 'pre'`, so they compile theme CSS (resolving
+  // `@import 'tailwindcss'`, @source, @plugin, @theme) before the postcss chain runs —
+  // postcss-import never sees the raw Tailwind directives. Scan roots come from the @source
+  // directives in main.css (relative to that file); no project-root base is needed.
+  return [...tailwindcssVite(), themePlugin];
 };

package/src/plugins/main.css

@@ -24,22 +24,25 @@ body {
 }
 
 /* Pre-CSS color fallbacks so text is readable before and during Vite HMR. */
-/* Values are intentionally kept in sync with @theme tokens in semantic.css. */
+/* Values are intentionally kept in sync with @theme tokens in semantic.css:
+ *   color            ← --color-base-fg      = light-dark(neutral-950, neutral-150)
+ *   background-color ← --color-base-surface = elevation-3 = light-dark(neutral-125, neutral-850)
+ * The literals carry the ramp tint (chroma 0.001, hue 190) so first paint matches the loaded theme. */
 :root {
   color-scheme: light;
 }
 html {
-  color: oklch(0.145 0 0);
-  background-color: oklch(0.985 0 0);
+  color: oklch(0.145 0.001 190);
+  background-color: oklch(0.92 0.001 190);
 }
 html.dark {
   color-scheme: dark;
-  color: oklch(0.985 0 0);
-  background-color: oklch(0.145 0 0);
+  color: oklch(0.905 0.001 190);
+  background-color: oklch(0.237 0.001 190);
 }
 @media (prefers-color-scheme: dark) {
   html:not(.dark) {
-    color: oklch(0.985 0 0);
-    background-color: oklch(0.145 0 0);
+    color: oklch(0.905 0.001 190);
+    background-color: oklch(0.237 0.001 190);
   }
 }

package/src/util/hash-styles.ts

@@ -6,21 +6,23 @@ import { type ChromaticPalette } from '@dxos/ui-types';
 
 export type Hue = ChromaticPalette | 'neutral';
 
-// TODO(burdon): Reconcile with ui-theme/theme/roles.css
+/**
+ * See theme.css
+ */
 export type ColorStyles = {
   hue: Hue;
-  fill: string; // -fill
-  surface: string; // -surface
-  surfaceText: string; // -surface-text
-  text: string; // -text
-  border: string; // -border
+  bg: string;
+  surface: string;
+  fg: string;
+  text: string;
+  border: string;
 };
 
 const neutral: ColorStyles = {
   hue: 'neutral',
-  fill: 'bg-neutral-fill',
+  bg: 'bg-neutral-bg',
   surface: 'bg-neutral-surface',
-  surfaceText: 'text-neutral-surface-text',
+  fg: 'text-neutral-fg',
   text: 'text-neutral-text',
   border: 'border-neutral-border',
 };
@@ -30,137 +32,137 @@ const neutral: ColorStyles = {
 const styles: ColorStyles[] = [
   {
     hue: 'red',
-    fill: 'bg-red-fill',
+    bg: 'bg-red-bg',
     surface: 'bg-red-surface',
-    surfaceText: 'text-red-surface-text',
+    fg: 'text-red-fg',
     text: 'text-red-text',
     border: 'border-red-border',
   },
   {
     hue: 'orange',
-    fill: 'bg-orange-fill',
+    bg: 'bg-orange-bg',
     surface: 'bg-orange-surface',
-    surfaceText: 'text-orange-surface-text',
+    fg: 'text-orange-fg',
     text: 'text-orange-text',
     border: 'border-orange-border',
   },
   {
     hue: 'amber',
-    fill: 'bg-amber-fill',
+    bg: 'bg-amber-bg',
     surface: 'bg-amber-surface',
-    surfaceText: 'text-amber-surface-text',
+    fg: 'text-amber-fg',
     text: 'text-amber-text',
     border: 'border-amber-border',
   },
   {
     hue: 'yellow',
-    fill: 'bg-yellow-fill',
+    bg: 'bg-yellow-bg',
     surface: 'bg-yellow-surface',
-    surfaceText: 'text-yellow-surface-text',
+    fg: 'text-yellow-fg',
     text: 'text-yellow-text',
     border: 'border-yellow-border',
   },
   {
     hue: 'lime',
-    fill: 'bg-lime-fill',
+    bg: 'bg-lime-bg',
     surface: 'bg-lime-surface',
-    surfaceText: 'text-lime-surface-text',
+    fg: 'text-lime-fg',
     text: 'text-lime-text',
     border: 'border-lime-border',
   },
   {
     hue: 'green',
-    fill: 'bg-green-fill',
+    bg: 'bg-green-bg',
     surface: 'bg-green-surface',
-    surfaceText: 'text-green-surface-text',
+    fg: 'text-green-fg',
     text: 'text-green-text',
     border: 'border-green-border',
   },
   {
     hue: 'emerald',
-    fill: 'bg-emerald-fill',
+    bg: 'bg-emerald-bg',
     surface: 'bg-emerald-surface',
-    surfaceText: 'text-emerald-surface-text',
+    fg: 'text-emerald-fg',
     text: 'text-emerald-text',
     border: 'border-emerald-border',
   },
   {
     hue: 'teal',
-    fill: 'bg-teal-fill',
+    bg: 'bg-teal-bg',
     surface: 'bg-teal-surface',
-    surfaceText: 'text-teal-surface-text',
+    fg: 'text-teal-fg',
     text: 'text-teal-text',
     border: 'border-teal-border',
   },
   {
     hue: 'cyan',
-    fill: 'bg-cyan-fill',
+    bg: 'bg-cyan-bg',
     surface: 'bg-cyan-surface',
-    surfaceText: 'text-cyan-surface-text',
+    fg: 'text-cyan-fg',
     text: 'text-cyan-text',
     border: 'border-cyan-border',
   },
   {
     hue: 'sky',
-    fill: 'bg-sky-fill',
+    bg: 'bg-sky-bg',
     surface: 'bg-sky-surface',
-    surfaceText: 'text-sky-surface-text',
+    fg: 'text-sky-fg',
     text: 'text-sky-text',
     border: 'border-sky-border',
   },
   {
     hue: 'blue',
-    fill: 'bg-blue-fill',
+    bg: 'bg-blue-bg',
     surface: 'bg-blue-surface',
-    surfaceText: 'text-blue-surface-text',
+    fg: 'text-blue-fg',
     text: 'text-blue-text',
     border: 'border-blue-border',
   },
   {
     hue: 'indigo',
-    fill: 'bg-indigo-fill',
+    bg: 'bg-indigo-bg',
     surface: 'bg-indigo-surface',
-    surfaceText: 'text-indigo-surface-text',
+    fg: 'text-indigo-fg',
     text: 'text-indigo-text',
     border: 'border-indigo-border',
   },
   {
     hue: 'violet',
-    fill: 'bg-violet-fill',
+    bg: 'bg-violet-bg',
     surface: 'bg-violet-surface',
-    surfaceText: 'text-violet-surface-text',
+    fg: 'text-violet-fg',
     text: 'text-violet-text',
     border: 'border-violet-border',
   },
   {
     hue: 'purple',
-    fill: 'bg-purple-fill',
+    bg: 'bg-purple-bg',
     surface: 'bg-purple-surface',
-    surfaceText: 'text-purple-surface-text',
+    fg: 'text-purple-fg',
     text: 'text-purple-text',
     border: 'border-purple-border',
   },
   {
     hue: 'fuchsia',
-    fill: 'bg-fuchsia-fill',
+    bg: 'bg-fuchsia-bg',
     surface: 'bg-fuchsia-surface',
-    surfaceText: 'text-fuchsia-surface-text',
+    fg: 'text-fuchsia-fg',
     text: 'text-fuchsia-text',
     border: 'border-fuchsia-border',
   },
   {
     hue: 'pink',
-    fill: 'bg-pink-fill',
+    bg: 'bg-pink-bg',
     surface: 'bg-pink-surface',
-    surfaceText: 'text-pink-surface-text',
+    fg: 'text-pink-fg',
     text: 'text-pink-text',
     border: 'border-pink-border',
   },
   {
     hue: 'rose',
-    fill: 'bg-rose-fill',
+    bg: 'bg-rose-bg',
     surface: 'bg-rose-surface',
-    surfaceText: 'text-rose-surface-text',
+    fg: 'text-rose-fg',
     text: 'text-rose-text',
     border: 'border-rose-border',
   },
@@ -171,6 +173,16 @@ export const palette = {
   hues: styles,
 };
 
+const validHues: ReadonlySet<Hue> = new Set<Hue>([neutral.hue, ...styles.map((s) => s.hue)]);
+
+/**
+ * Normalise an arbitrary string into a known `Hue`, falling back to `'neutral'` when the
+ * input doesn't match one of the catalogued palette entries. Useful when accepting hue
+ * values from user-authored data (e.g. ECHO objects, plugin settings) that need to be
+ * forwarded to a hue-keyed prop like `Tag`'s `palette`.
+ */
+export const toHue = (hue: string | undefined): Hue => (hue && validHues.has(hue as Hue) ? (hue as Hue) : 'neutral');
+
 // TODO(burdon): Rename getClassNames.
 export const getStyles = (hue: string): ColorStyles => {
   return styles.find((color) => color.hue === hue) || neutral;