@adea-ai/ui 0.127.0 → 0.128.0

package/dist/r/theme.json

@@ -2,7 +2,7 @@
   "name": "theme",
   "type": "registry:style",
   "title": "Adea theme",
-  "description": "The design tokens: the semantic palette in OKLCH, the type and control scales, shells geometry, shadows, motion and the z-index stack.",
+  "description": "The design tokens: the semantic palette in OKLCH, the type and control scales, shells geometry, shadows, motion and the z-index stack, plus the pre-paint stylesheet that carries every catalogue theme.",
   "dependencies": [
     "@fontsource-variable/geist@^5.3.0",
     "@fontsource-variable/geist-mono@^5.3.0",
@@ -22,6 +22,11 @@
       "type": "registry:style",
       "target": "styles/theme.css"
     },
+    {
+      "path": "src/styles/theme-variants.css",
+      "type": "registry:style",
+      "target": "styles/theme-variants.css"
+    },
     {
       "path": "src/styles/base.css",
       "type": "registry:style",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/ui",
-  "version": "0.127.0",
+  "version": "0.128.0",
   "description": "The Adea design system: Kobalte-backed Solid components, semantic OKLCH tokens, and the app-shell layout primitives shared by Adea and Cortana.",
   "keywords": [
     "adea",
@@ -68,6 +68,7 @@
     },
     "./globals.css": "./src/styles/globals.css",
     "./theme.css": "./src/styles/theme.css",
+    "./theme-variants.css": "./src/styles/theme-variants.css",
     "./base.css": "./src/styles/base.css",
     "./appearance-font-settings.css": "./src/styles/appearance-font-settings.css",
     "./fonts.css": "./src/styles/fonts.css",

package/registry.json

@@ -2600,7 +2600,7 @@
       "name": "theme",
       "type": "registry:style",
       "title": "Adea theme",
-      "description": "The design tokens: the semantic palette in OKLCH, the type and control scales, shells geometry, shadows, motion and the z-index stack.",
+      "description": "The design tokens: the semantic palette in OKLCH, the type and control scales, shells geometry, shadows, motion and the z-index stack, plus the pre-paint stylesheet that carries every catalogue theme.",
       "dependencies": [
         "@fontsource-variable/geist@^5.3.0",
         "@fontsource-variable/geist-mono@^5.3.0",
@@ -2620,6 +2620,11 @@
           "type": "registry:style",
           "target": "styles/theme.css"
         },
+        {
+          "path": "src/styles/theme-variants.css",
+          "type": "registry:style",
+          "target": "styles/theme-variants.css"
+        },
         {
           "path": "src/styles/base.css",
           "type": "registry:style",

package/src/components/theme/index.ts

@@ -17,6 +17,7 @@ export {
   themeScript,
   useOptionalTheme,
   useTheme,
+  type EditorRolesMode,
   type ThemeContextValue,
   type ThemeDensity,
   type ThemePersistence,

package/src/components/theme/theme-document.ts

@@ -4,9 +4,10 @@ import {
 } from '#lib/appearance-font-settings'
 import {
   accentVariables,
+  isCatalogueVariant,
   terminalCssVariables,
-  themeById,
   themeCssVariables,
+  type EditorRolesMode,
   type ThemeAppearance,
   type ThemeVariant,
 } from '#lib/themes'
@@ -67,11 +68,34 @@ export type ThemeDocumentOptions = {
    * imported one wrote, so nothing inline outlives it to beat the stylesheet.
    */
   palette?: 'inline' | 'stylesheet'
+  /**
+   * The `--editor-*` projection. `syntax` (the default) is the catalogue's quiet
+   * syntax roles, which is what `theme-variants.css` carries; `floor` holds every
+   * editor role to 4.5:1 on the canvas, as hex.
+   *
+   * With `palette: 'stylesheet'`, `floor` is the one palette write a catalogue
+   * variant still gets: the stylesheet is generated for the default projection, so
+   * the sixteen `--editor-*` properties are written inline over it. The rest of the
+   * palette stays in the stylesheet.
+   */
+  editorRoles?: EditorRolesMode
 }
 
-/** True for the catalogue's own variant, not a host's copy that merely shares its id. */
-function isCatalogueVariant(variant: ThemeVariant): boolean {
-  return themeById(variant.id) === variant
+/**
+ * What a catalogue variant still writes inline when its palette is the stylesheet's:
+ * nothing, unless the editor projection is not the one the stylesheet was generated
+ * for.
+ */
+function stylesheetOverrides(
+  variant: ThemeVariant,
+  editorRoles: EditorRolesMode | undefined
+): Record<string, string> {
+  if (editorRoles !== 'floor') return {}
+  return Object.fromEntries(
+    Object.entries(themeCssVariables(variant, { editor: 'floor' })).filter(([name]) =>
+      name.startsWith('--editor-')
+    )
+  )
 }
 
 /**
@@ -91,7 +115,9 @@ export function themeDocumentTokens(
   options: ThemeDocumentOptions = {}
 ): { tokens: Record<string, string>; accented: boolean } {
   const fromStylesheet = options.palette === 'stylesheet' && isCatalogueVariant(state.variant)
-  const properties = fromStylesheet ? {} : { ...themeCssVariables(state.variant) }
+  const properties = fromStylesheet
+    ? stylesheetOverrides(state.variant, options.editorRoles)
+    : { ...themeCssVariables(state.variant, { editor: options.editorRoles }) }
   const accent = accentVariables(state.selection.accent, state.appearance, state.selection, {
     background: state.variant.colors.background,
     floor: options.accentContrastFloor,

package/src/components/theme/theme-provider.tsx

@@ -5,6 +5,7 @@ import { REDUCED_TRANSPARENCY_QUERY, resolveSurfaceState } from '#lib/theme-surf
 import {
   builtinThemes,
   themeAccentsFor,
+  type EditorRolesMode,
   type ThemeAppearance,
   type ThemeVariant,
 } from '#lib/themes'
@@ -38,6 +39,7 @@ export {
   type VersionedPersistenceOptions,
 } from './theme-persistence'
 export type { ThemeSurface } from '#lib/theme-surface'
+export type { EditorRolesMode } from '#lib/themes'
 export { inlineScriptLiteral, themeScript, type ThemeScriptOptions } from './theme-script'
 export {
   defaultThemeSelection,
@@ -159,6 +161,19 @@ export type ThemeProviderProps = {
    * properties the host variant wrote.
    */
   palette?: 'inline' | 'stylesheet'
+  /**
+   * The projection behind the `--editor-*` ramp. `syntax` (the default) is the
+   * catalogue's quiet syntax roles, a comment among them deliberately below
+   * body-text contrast. `floor` holds all sixteen roles to 4.5:1 on the canvas, as
+   * hex, for a host that renders code as content (a diff, a file view) rather than
+   * as decoration.
+   *
+   * Applies to catalogue variants; a host's own `themes` keep their `editor` and
+   * their `tokens`. With `palette="stylesheet"` it is the one palette property a
+   * catalogue variant still writes inline, because `theme-variants.css` is generated
+   * for `syntax`. Absent, nothing changes.
+   */
+  editorRoles?: EditorRolesMode
   /**
    * Bind the platform zoom chords (Cmd or Ctrl with `=`, `+`, `-`, `0`) to the three
    * text sizes instead of the browser's page zoom: stepping them together is zoom
@@ -189,6 +204,7 @@ export function ThemeProvider(props: ThemeProviderProps) {
     'accentContrastFloor',
     'surface',
     'palette',
+    'editorRoles',
     'fontZoom',
   ])
   const storageKey = () => local.storageKey ?? 'adea-appearance'
@@ -288,6 +304,7 @@ export function ThemeProvider(props: ThemeProviderProps) {
       transformTokens: local.transformTokens,
       accentContrastFloor: local.accentContrastFloor,
       palette: local.palette,
+      editorRoles: local.editorRoles,
     }
     const apply = () => {
       written = applyThemeToRoot(document.documentElement, state, options, written)

package/src/index.ts

@@ -141,6 +141,7 @@ export {
   contrastRatio,
   defaultDarkThemeId,
   defaultLightThemeId,
+  editorPaletteFor,
   isThemeAccentId,
   resolveAccentPreset,
   resolveVariant,
@@ -157,8 +158,10 @@ export {
   validateThemeRegistry,
   variantFromRecord,
   withAccent,
+  type EditorRolesMode,
   type ThemeAppearance,
   type ThemeColors,
+  type ThemeCssVariableOptions,
   type ThemeEditorPalette,
   type ThemeFinding,
   type ThemeProvenance,

package/src/lib/themes.ts

@@ -37,6 +37,7 @@ import {
   ACCENTS,
   accentForeground,
   chartSeries,
+  editorRolesHex,
   getAccent,
   getTheme,
   hasTheme,
@@ -613,6 +614,97 @@ export function accentRolesForSelection(
   })
 }
 
+/**
+ * Which projection fills the `--editor-*` ramp.
+ *
+ *   - `syntax` (the default) is the catalogue's quiet syntax roles, as `ThemeVariant.editor`
+ *     holds them: a comment may sit below body-text contrast, because in a code view
+ *     it is meant to recede.
+ *   - `floor` holds every editor role to 4.5:1 on the canvas (`editorRolesHex`), for a
+ *     host that renders code as content rather than as decoration. It is hex, where
+ *     `syntax` is `oklch()`.
+ */
+export type EditorRolesMode = 'syntax' | 'floor'
+
+/** Options for {@link themeCssVariables}. */
+export type ThemeCssVariableOptions = {
+  /** The `--editor-*` projection. Default `syntax`: absent, the output is unchanged. */
+  editor?: EditorRolesMode
+}
+
+/**
+ * True for the catalogue's own variant, not a host's copy that merely shares its id.
+ *
+ * Identity rather than id, because a host's imported theme may reuse a catalogue id
+ * with different colours, and projecting the catalogue's record for it would paint
+ * the wrong palette.
+ */
+export function isCatalogueVariant(variant: ThemeVariant): boolean {
+  return themeById(variant.id) === variant
+}
+
+/**
+ * The editor palette held to 4.5:1, or `fallback` for a record that cannot reach it.
+ *
+ * Some palettes (an imported one, most often) cannot be repaired to the floor from
+ * their own ramp within the catalogue's lightness budget, and `editorRolesHex` says
+ * so by throwing. A palette that paints nothing is worse than one that paints its
+ * quiet roles, so the throw is the cue to fall back rather than to fail. `project` is
+ * a parameter so that path can be exercised: no catalogue theme takes it.
+ */
+export function floorEditorPalette(
+  record: AdeaTheme,
+  fallback: ThemeEditorPalette,
+  project: (theme: AdeaTheme) => Record<keyof ThemeEditorPalette, string> = editorRolesHex
+): ThemeEditorPalette {
+  try {
+    const roles = project(record)
+    return {
+      keyword: roles.keyword,
+      string: roles.string,
+      number: roles.number,
+      comment: roles.comment,
+      function: roles.function,
+      variable: roles.variable,
+      type: roles.type,
+      tag: roles.tag,
+      attribute: roles.attribute,
+      operator: roles.operator,
+      heading: roles.heading,
+      link: roles.link,
+      diffAdd: roles.diffAdd,
+      diffDelete: roles.diffDelete,
+      diffHunk: roles.diffHunk,
+      searchMatch: roles.searchMatch,
+    }
+  } catch {
+    return fallback
+  }
+}
+
+const floorEditorCache = new Map<string, ThemeEditorPalette>()
+
+/**
+ * The editor palette a variant paints under a projection.
+ *
+ * `floor` applies to the catalogue's own variants, whose record the catalogue holds.
+ * A variant it does not hold (a host's imported theme) has no record to project and
+ * keeps its own `editor`; such a theme normally carries its roles in `tokens`, which
+ * win over either projection anyway. Computed once per theme: the repair is a search.
+ */
+export function editorPaletteFor(
+  theme: ThemeVariant,
+  mode: EditorRolesMode = 'syntax'
+): ThemeEditorPalette {
+  if (mode !== 'floor' || !isCatalogueVariant(theme)) return theme.editor
+  const cached = floorEditorCache.get(theme.id)
+  if (cached) return cached
+  const record = getTheme(theme.id)
+  const palette = record ? floorEditorPalette(record, theme.editor) : theme.editor
+  floorEditorCache.set(theme.id, palette)
+  return palette
+}
+
 /**
  * The roles a variant sets, as CSS custom properties.
  *
@@ -620,11 +712,18 @@ export function accentRolesForSelection(
  * names. A provider applies this; nothing else repeats it. The `--terminal-*` and
  * `--editor-*` ramps are presentations of the catalogue's ANSI and syntax data rather
  * than separate roles, which is why they are built here and not in the catalogue.
+ *
+ * `options.editor` picks the `--editor-*` projection ({@link EditorRolesMode}).
+ * Absent it, the result is what it has always been; the generated `theme-variants.css`
+ * and the design-system artifact are built without it.
  */
-export function themeCssVariables(theme: ThemeVariant): Record<string, string> {
+export function themeCssVariables(
+  theme: ThemeVariant,
+  options: ThemeCssVariableOptions = {}
+): Record<string, string> {
   const c = theme.colors
   const t = theme.terminal
-  const e = theme.editor
+  const e = editorPaletteFor(theme, options.editor)
   const derived = {
     '--background': c.background,
     '--foreground': c.foreground,