@scattered-light/loomiere 0.0.0-stage → 0.1.1

package/exporters/README.md

@@ -0,0 +1,45 @@
+# Exporters
+
+One theme, many frameworks. The universal outputs come first; everything else is a small
+adapter in this folder, and each one only renames. No adapter does color math.
+
+| Id | Output | For |
+|---|---|---|
+| (built in) | `tokens.css` | Any framework, or none. Every token as a `--sl-` variable, with dark, contrast, color vision and roles. |
+| `dtcg` | `tokens.dtcg.json` | Any tool that reads the W3C design tokens format: Figma importers, Tokens Studio, Style Dictionary, Terrazzo, Penpot. |
+| `tailwind` | `tailwind.css` | Tailwind CSS v4. Points at the `--sl-` variables instead of copying values. |
+| `mui` | `mui.js`, `.d.ts` | MUI 6, 7 and 9. `createTheme(options)`: the palette in light and dark, plus component overrides that match loomiere-base-ui. Needs `tokens.css`. |
+| `chakra` | `chakra.js`, `.d.ts` | Chakra UI 3. `<ChakraProvider value={system}>`: every palette as a color palette, plus recipes that match loomiere-base-ui. Needs `tokens.css`. |
+| `ag-grid-v36` | `ag-grid-v36.js`, `.d.ts`, `.css` | AG Grid 36 and later (Theming API). |
+| `ag-grid-v33` | `ag-grid-v33.js`, `.d.ts`, `.css` | AG Grid 33 to 35 (Theming API). |
+| `ag-grid-v32` | `ag-grid-v32.css` | AG Grid 31 and 32 (CSS themes). All three come from `ag-grid-settings.mjs`. |
+| `figma` | `figma.json` | Figma variables in three collections: Brand, Pairs, Theme (Light and Dark modes). Aliases point back to Brand, so a palette change flows through. Fluid sizes use their large-screen value. |
+
+`loomiere build` writes them all to the theme's `exports/` folder, with `catalog.json` listing what's there.
+`"exports": ["ag-grid", "tailwind"]` in `loomiere.config.json` writes only those (an id prefix picks a
+family, so `ag-grid` writes all three AG Grid themes). The Mojave demo package exposes them as
+`@scattered-light/loomiere-mojave/exports/<file>`.
+
+## How it works
+
+1. The build writes the token catalog (`tokens.json`).
+2. `theme.mjs` reads it back into a framework-neutral theme: every palette, every scope's slots
+   in light and dark, the semantic surfaces, text and borders in light and dark, fonts, sizes,
+   radii, space and shadows, plus the brand's roles.
+3. Each adapter maps that theme onto one framework's shape.
+
+MUI and Chakra style their own components, so their adapters also restyle those to match
+loomiere-base-ui. `component-styles.mjs` turns the shared patterns (field, popup surface, item
+row, check box, focus ring, emphasis levels and so on) into style objects that read the same
+concept variables the Base UI CSS reads; `mui.mjs` and `chakra.mjs` place them on each
+library's own parts. A change to a semantic concept reaches all three.
+
+## Add a framework
+
+Write `<id>.mjs` exporting `{ id, name, file, for, build(theme) }`, where `build` returns the
+file's text (or `{ fileName: text }` when it writes several, as the AG Grid themes do), and add it to `EXPORTERS` in `index.mjs`. Prefer pointing at `--sl-` variables
+when the framework allows it (as Tailwind does), so modes and roles keep working at runtime;
+otherwise give light and dark values the way the framework expects (as MUI's palette does,
+since MUI does color math on it).
+Good next candidates: Panda CSS, Radix Themes, shadcn/ui (Tailwind plus its own variable
+names), Vuetify and Mantine.

package/exporters/ag-grid-settings.mjs

@@ -0,0 +1,177 @@
+/**
+ * AG Grid settings table: one row per grid setting, pointing at the theme's semantic tokens.
+ * The three AG Grid themes (v32 CSS, v33 and v36 Theming API) are all written from this table,
+ * so a grid looks like the rest of the theme in every version, and light, dark and data-color
+ * follow the same tokens as the Base UI components.
+ *
+ * Each row is [setting, value, legacy variable]:
+ *   setting  the Theming API parameter name (AG Grid 33 and later).
+ *   value    "{token.path}" becomes var(--sl-token-path); text around the braces is kept, so
+ *            "{stroke.default} solid {table.border-color}" is a CSS border. No braces = literal.
+ *   legacy   the --ag-* CSS variable that does the same job in v31-32 themes, or null when
+ *            the old themes have no such variable. [variable, value] when the old variable
+ *            takes a different value (a color where the new setting takes a whole border).
+ * npm run check:ag-grid confirms every setting and variable exists in the AG Grid version it
+ * is written for.
+ */
+
+/** Settings added after 33; the v33 theme leaves them out. */
+export const SINCE = {
+  fontWeight: 36,
+  borderWidth: 36,
+  cellFontWeight: 36,
+  focusErrorShadow: 36,
+};
+
+export const SETTINGS = [
+  // Color scheme: native scrollbars and pickers follow the theme in effect.
+  ['browserColorScheme', '{color-scheme}', null],
+
+  // Cells
+  ['backgroundColor', '{table.background}', '--ag-background-color'],
+  ['foregroundColor', '{table.color}', '--ag-foreground-color'],
+  ['textColor', '{table.color}', null],
+  ['cellTextColor', '{table.color}', '--ag-data-color'],
+  ['subtleTextColor', '{table.subtle-color}', '--ag-secondary-foreground-color'],
+  ['accentColor', '{interactive.default}', '--ag-active-color'],
+  ['invalidColor', '{field.border-color-error}', '--ag-invalid-color'],
+  ['oddRowBackgroundColor', '{table.background}', '--ag-odd-row-background-color'],
+  ['rowHoverColor', '{table.row-hover}', '--ag-row-hover-color'],
+  ['selectedRowBackgroundColor', '{table.row-selected}', '--ag-selected-row-background-color'],
+  ['columnHoverColor', '{table.column-hover}', '--ag-column-hover-color'],
+  ['rangeSelectionBackgroundColor', '{table.range-background}', '--ag-range-selection-background-color'],
+  ['rangeSelectionBorderColor', '{table.range-border}', '--ag-range-selection-border-color'],
+  ['cellEditingBorder', '{field.border-width} solid {field.border-color-focus}', null],
+  ['cellEditingShadow', '{field.shadow-focus}', null],
+
+  // Type: cells use the condense text style, the header uses condense-subtitle, whole.
+  ['fontFamily', '{font.condense.font-family}', '--ag-font-family'],
+  ['fontSize', '{font.condense.font-size}', '--ag-font-size'],
+  ['fontWeight', '{font.condense.font-weight}', null],
+  ['headerFontFamily', '{font.condense-subtitle.font-family}', null],
+  ['headerFontSize', '{font.condense-subtitle.font-size}', null],
+  ['headerFontWeight', '{font.condense-subtitle.font-weight}', null],
+
+  // Sizes
+  ['spacing', '{space.2}', '--ag-grid-size'],
+  ['rowHeight', '{table.row-height}', '--ag-row-height'],
+  ['headerHeight', '{table.header-height}', '--ag-header-height'],
+  ['listItemHeight', '{control.height-sm}', '--ag-list-item-height'],
+  ['cellHorizontalPadding', '{table.cell-padding-inline}', '--ag-cell-horizontal-padding'],
+  ['iconSize', '{icon-size.condense}', '--ag-icon-size'],
+
+  // Edges
+  ['borderColor', '{table.border-color}', '--ag-border-color'],
+  ['wrapperBorder', '{stroke.default} solid {table.border-color}', null],
+  ['wrapperBorderRadius', '{table.radius}', '--ag-wrapper-border-radius'],
+  ['borderRadius', '{radius.item}', '--ag-border-radius'],
+  ['borderWidth', '{stroke.default}', null],
+  ['rowBorder', '{stroke.default} solid {table.row-border-color}', ['--ag-row-border-color', '{table.row-border-color}']],
+  ['headerRowBorder', '{stroke.default} solid {table.border-color}', null],
+  ['columnBorder', 'none', null],
+  ['headerColumnResizeHandleColor', '{table.border-color}', '--ag-header-column-resize-handle-color'],
+
+  // Header, side bar and other chrome
+  ['chromeBackgroundColor', '{table.header-background}', '--ag-control-panel-background-color'],
+  ['headerBackgroundColor', '{table.header-background}', '--ag-header-background-color'],
+  ['headerTextColor', '{table.header-color}', '--ag-header-foreground-color'],
+  ['headerCellHoverBackgroundColor', '{table.header-background-hover}', null],
+  ['sideBarBackgroundColor', '{table.header-background}', null],
+  ['sideButtonSelectedBackgroundColor', '{table.background}', '--ag-side-button-selected-background-color'],
+  ['iconColor', '{table.subtle-color}', '--ag-icon-font-color'],
+
+  // Focus: the same ring and halo as every other control.
+  ['focusShadow', '0 0 0 {a11y.focus-outline-width} {focus.ring}, 0 0 0 {focus.halo-spread} {focus.halo-color}', null],
+  ['focusErrorShadow', '{field.shadow-focus-error}', null],
+
+  // Inputs (filters, cell editors, the quick filter): the field concept.
+  ['inputBackgroundColor', '{field.background}', null],
+  ['inputTextColor', '{field.color}', null],
+  ['inputPlaceholderTextColor', '{field.placeholder-color}', null],
+  ['inputBorder', '{field.border-width} solid {field.border-color}', ['--ag-input-border-color', '{field.border-color}']],
+  ['inputBorderRadius', '{field.radius}', null],
+  ['inputFocusBorder', '{field.border-width} solid {field.border-color-focus}', ['--ag-input-focus-border-color', '{field.border-color-focus}']],
+  ['inputFocusShadow', '{field.shadow-focus}', '--ag-input-focus-box-shadow'],
+  ['inputInvalidBorder', '{field.border-width} solid {field.border-color-error}', ['--ag-input-border-color-invalid', '{field.border-color-error}']],
+  ['inputDisabledBackgroundColor', '{field.background-disabled}', '--ag-input-disabled-background-color'],
+  ['inputDisabledTextColor', '{field.color-disabled}', null],
+  ['inputIconColor', '{table.subtle-color}', null],
+  ['inputHeight', '{control.height-sm}', null],
+  ['inputPaddingStart', '{control.padding-inline-sm}', null],
+
+  // Checkboxes and toggles: the check concept.
+  ['checkboxBorderRadius', '{check.radius}', null],
+  ['checkboxBorderWidth', '{check.border-width}', null],
+  ['checkboxUncheckedBackgroundColor', '{check.background}', '--ag-checkbox-background-color'],
+  ['checkboxUncheckedBorderColor', '{check.border-color}', '--ag-checkbox-unchecked-color'],
+  ['checkboxCheckedBackgroundColor', '{check.background-checked}', '--ag-checkbox-checked-color'],
+  ['checkboxCheckedBorderColor', '{check.border-color-checked}', null],
+  ['checkboxCheckedShapeColor', '{check.mark-color}', null],
+  ['checkboxIndeterminateBackgroundColor', '{check.background-checked}', '--ag-checkbox-indeterminate-color'],
+  ['checkboxIndeterminateBorderColor', '{check.border-color-checked}', null],
+  ['checkboxIndeterminateShapeColor', '{check.mark-color}', null],
+  ['toggleButtonOnBackgroundColor', '{check.background-checked}', null],
+  ['toggleButtonOffBackgroundColor', '{check.border-color}', null],
+  ['toggleButtonSwitchBackgroundColor', '{check.background}', null],
+
+  // Menus, pickers and panels: the popup and item concepts.
+  ['menuBackgroundColor', '{popup.background}', '--ag-menu-background-color'],
+  ['menuTextColor', '{item.color}', null],
+  ['menuBorder', '{popup.border-width} solid {popup.border-color}', ['--ag-menu-border-color', '{popup.border-color}']],
+  ['menuShadow', '{popup.shadow}', null],
+  ['menuSeparatorColor', '{popup.separator-color}', null],
+  ['popupShadow', '{popup.shadow}', '--ag-popup-shadow'],
+  ['dropdownShadow', '{popup.shadow}', null],
+  ['pickerListBackgroundColor', '{popup.background}', null],
+  ['pickerListBorder', '{popup.border-width} solid {popup.border-color}', null],
+  ['panelBackgroundColor', '{popup.background}', '--ag-panel-background-color'],
+  ['panelTitleBarBackgroundColor', '{table.header-background}', null],
+  ['cardShadow', '{elevation.sm}', '--ag-card-shadow'],
+  ['dialogBorder', '{modal.border-width} solid {modal.border-color}', null],
+  ['dialogShadow', '{modal.shadow}', null],
+  ['modalOverlayBackgroundColor', '{modal.backdrop}', '--ag-modal-overlay-background-color'],
+  ['tooltipBackgroundColor', '{surface.inverse}', '--ag-tooltip-background-color'],
+  ['tooltipTextColor', '{text.on-inverse-surface}', null],
+  ['tooltipBorder', 'none', null],
+
+  // Buttons (filter Apply/Reset, panels): the standard emphasis level, like an outline Button.
+  ['buttonBackgroundColor', '{emphasis.standard.bg}', null],
+  ['buttonTextColor', '{emphasis.standard.fg}', null],
+  ['buttonBorder', '{stroke.default} solid {emphasis.standard.border}', null],
+  ['buttonHoverBackgroundColor', '{emphasis.standard.bg-hover}', null],
+  ['buttonHoverBorder', '{stroke.default} solid {emphasis.standard.border-hover}', null],
+  ['buttonActiveBackgroundColor', '{emphasis.standard.bg-active}', null],
+  ['buttonBorderRadius', '{radius.control}', null],
+  ['buttonFontWeight', '{font.condense-trigger.font-weight}', null],
+  ['iconButtonColor', '{icon-button.color}', null],
+  ['iconButtonHoverColor', '{icon-button.color-hover}', null],
+  ['iconButtonHoverBackgroundColor', '{icon-button.background-hover}', null],
+  ['iconButtonBorderRadius', '{icon-button.radius}', null],
+
+  // Tabs (column menu, tool panels): the disclosure concept, like Base UI Tabs.
+  ['tabTextColor', '{table.subtle-color}', null],
+  ['tabHoverTextColor', '{table.color}', null],
+  ['tabSelectedTextColor', '{disclosure.selected-color}', null],
+  ['tabSelectedUnderlineColor', '{disclosure.indicator-color}', null],
+  ['tabSelectedUnderlineWidth', '{disclosure.indicator-width}', null],
+
+  // Value change flashes: the success and error palettes.
+  ['valueChangeDeltaUpColor', '{scope.success.fg}', null],
+  ['valueChangeDeltaDownColor', '{scope.error.fg}', null],
+];
+
+/** Old-theme variables with no single Theming API setting of their own. */
+export const LEGACY_ONLY = [
+  ['--ag-secondary-border-color', '{table.row-border-color}'],
+  ['--ag-subheader-background-color', '{table.header-background}'],
+  ['--ag-disabled-foreground-color', '{text.disabled}'],
+  ['--ag-input-disabled-border-color', '{field.border-color}'],
+  ['--ag-header-cell-hover-background-color', '{table.header-background-hover}'],
+  ['--ag-header-column-separator-display', 'none'],
+  ['--ag-borders', 'solid {stroke.default}'],
+  ['--ag-borders-critical', 'solid {stroke.default}'],
+  ['--ag-row-border-style', 'solid'],
+  ['--ag-row-border-width', '{stroke.default}'],
+  ['--ag-checkbox-border-radius', '{check.radius}'],
+  ['--ag-card-radius', '{radius.item}'],
+];

package/exporters/ag-grid.mjs

@@ -0,0 +1,112 @@
+/**
+ * AG Grid themes, one per family of AG Grid versions, all written from ag-grid-settings.mjs.
+ *   v36 (36 and later)  Theming API, with the settings 36 added.
+ *   v33 (33 to 35)      Theming API.
+ *   v32 (31 and 32)     The old CSS themes: --ag-* variables on .ag-theme-quartz.
+ * Every value points at a --sl- variable, so light, dark, contrast and data-color keep working.
+ */
+import { LEGACY_ONLY, SETTINGS, SINCE } from './ag-grid-settings.mjs';
+
+/** Turns "{a.b} solid {c}" into "var(--sl-a-b) solid var(--sl-c)", failing on unknown tokens. */
+function resolver(theme) {
+  const name = new Map(theme.tokens.map((t) => [t.path, t.name]));
+  return (value) =>
+    value.replace(/\{([^}]+)\}/g, (_, path) => {
+      if (!name.has(path)) throw new Error(`AG Grid settings: no token "${path}"`);
+      return `var(${name.get(path)})`;
+    });
+}
+
+/** Text-style details AG Grid has no settings for (letter spacing), plus per-version fixes. */
+const extraCss = (fixes = '') => `/* Letter spacing comes from the condense and condense-subtitle text styles. */
+.ag-root-wrapper,
+.ag-popup {
+  letter-spacing: var(--sl-font-condense-letter-spacing);
+}
+.ag-header-cell-text {
+  letter-spacing: var(--sl-font-condense-subtitle-letter-spacing);
+  line-height: var(--sl-font-condense-subtitle-line-height);
+}
+${fixes}`;
+
+function themingApi(major, fixes) {
+  const file = `ag-grid-v${major}`;
+  return {
+    id: `ag-grid-v${major}`,
+    name: `AG Grid ${major === 33 ? '33 to 35' : `${major}+`}`,
+    files: [`${file}.js`, `${file}.d.ts`, `${file}.css`],
+    file: `${file}.js`,
+    for: `AG Grid ${major === 33 ? '33, 34 and 35' : '36 and later'} (Theming API): themeQuartz.withParams(brandParams), plus ${file}.css.`,
+    build(theme) {
+      const resolve = resolver(theme);
+      const rows = SETTINGS.filter(([param]) => !(SINCE[param] > major));
+      const body = rows.map(([param, value]) => `  ${param}: ${JSON.stringify(resolve(value))},`).join('\n');
+      const usage = ` *   import { themeQuartz } from 'ag-grid-community';\n *   import { withBrand } from './theme/exports/ag-grid-v${major}.js';\n *   import './theme/tokens.css';\n *   import './theme/exports/ag-grid-v${major}.css';\n *   <AgGridReact theme={withBrand(themeQuartz)} ... />`;
+      return {
+        [`${file}.js`]: `/**\n * AG Grid ${major === 33 ? '33 to 35' : '36 and later'} theme for "${theme.brand}". Generated by loomiere build from exporters/ag-grid-settings.mjs; do not edit.\n${usage}\n * Every value is a --${theme.prefix}- variable, so light and dark follow data-theme or the system.\n */\nexport const brandParams = {\n${body}\n};\n\n/** Applies the brand's settings to an AG Grid theme, usually themeQuartz. */\nexport const withBrand = (base) => base.withParams(brandParams);\n`,
+        [`${file}.d.ts`]: `/** AG Grid ${major === 33 ? '33 to 35' : '36 and later'} theme settings for "${theme.brand}". */\nexport declare const brandParams: Readonly<Record<string, string>>;\n/** Applies the brand's settings to an AG Grid theme, usually themeQuartz. */\nexport declare function withBrand<T extends { withParams(params: object): T }>(base: T): T;\n`,
+        [`${file}.css`]: `/* AG Grid ${major === 33 ? '33 to 35' : '36 and later'} additions for "${theme.brand}". Generated by loomiere build; do not edit. Load after tokens.css. */\n${extraCss(fixes)}`,
+      };
+    },
+  };
+}
+
+export const agGridV36 = themingApi(36);
+
+export const agGridV33 = themingApi(
+  33,
+  `/* 33 to 35 hard-code a 5px radius on picker fields (36 uses borderRadius). */
+.ag-picker-field-wrapper {
+  border-radius: var(--sl-field-radius);
+}
+
+/* 33 to 35 give focused text inputs the keyboard focus ring; 36 uses inputFocusShadow, like Input. */
+.ag-root-wrapper .ag-input-field-input:focus,
+.ag-popup .ag-input-field-input:focus {
+  box-shadow: var(--sl-field-shadow-focus);
+}
+`,
+);
+
+export const agGridV32 = {
+  id: 'ag-grid-v32',
+  name: 'AG Grid 31 and 32',
+  files: ['ag-grid-v32.css'],
+  file: 'ag-grid-v32.css',
+  for: 'AG Grid 31 and 32 (CSS themes): load after ag-theme-quartz.css and put class="ag-theme-quartz ag-theme-loomiere" on the grid.',
+  build(theme) {
+    const resolve = resolver(theme);
+    const lines = [];
+    for (const [, value, legacy] of SETTINGS) {
+      if (!legacy) continue;
+      const [variable, legacyValue] = Array.isArray(legacy) ? legacy : [legacy, value];
+      lines.push(`  ${variable}: ${resolve(legacyValue)};`);
+    }
+    for (const [variable, value] of LEGACY_ONLY) lines.push(`  ${variable}: ${resolve(value)};`);
+    return {
+      'ag-grid-v32.css': `/* AG Grid 31 and 32 theme for "${theme.brand}". Generated by loomiere build from exporters/ag-grid-settings.mjs; do not edit.
+   import 'ag-grid-community/styles/ag-grid.css';
+   import 'ag-grid-community/styles/ag-theme-quartz.css';
+   import './theme/tokens.css';
+   import './theme/exports/ag-grid-v32.css';
+   <div class="ag-theme-quartz ag-theme-loomiere">…grid…</div>
+   Every value is a --${theme.prefix}- variable, so light and dark follow data-theme or the system;
+   no -dark theme class is needed. */
+.ag-theme-quartz.ag-theme-loomiere {
+${lines.join('\n')}
+  color-scheme: var(--${theme.prefix}-color-scheme);
+}
+
+/* The old themes have no header type settings: the header uses the condense-subtitle text style. */
+.ag-theme-loomiere .ag-header-cell-text {
+  font-family: var(--${theme.prefix}-font-condense-subtitle-font-family);
+  font-size: var(--${theme.prefix}-font-condense-subtitle-font-size);
+  font-weight: var(--${theme.prefix}-font-condense-subtitle-font-weight);
+}
+.ag-theme-loomiere .ag-header-cell:hover {
+  background-color: var(--${theme.prefix}-table-header-background-hover);
+}
+${extraCss().replace(/^\.ag-root-wrapper,\n\.ag-popup \{/m, '.ag-theme-loomiere {').replace(/^\.ag-header-cell-text \{/m, '.ag-theme-loomiere .ag-header-cell-text {')}`,
+    };
+  },
+};