@evolve.ui/theme-system 1.0.1 → 1.2.0

package/src/effects/emit.ts

@@ -0,0 +1,314 @@
+/**
+ * Build-time effect sheet. Called from tsdown `onSuccess` for each registered brand.
+ * The build writes `*.effects.css` only for brands in the registry.
+ *
+ * Order: layer statement, token block, two identical fallback remaps, then `@layer hui-effects`
+ * (vocabulary rules, then the brand's rules). No palette block and no `:root`.
+ * Pseudo-element declarations are enforced: Tailwind preflight's unlayered `::before, ::after`
+ * reset would otherwise drop a layered-normal edge or dashed frame.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { brandsToCSS } from '../themes/brands';
+import { effectClasses } from './classes';
+import { effectHooks, freePseudoSlot, hookSelector, type EffectHookId, type PseudoSlot } from './hooks';
+import { effectLayers } from './layers';
+import { materials, type Decoration, type EffectLayer, type EffectRule, type PaintProperty } from './rules';
+import { effectTokens, type EffectTokenName, type EffectTokenSpec } from './tokens';
+import { validateEffectLayer, validateRules } from './validate';
+import { vocabularyRules } from './vocabulary';
+
+export const EFFECT_LAYER = 'hui-effects';
+
+export const BACKDROP_SUPPORT = '(-webkit-backdrop-filter: blur(1px)) or (backdrop-filter: blur(1px))';
+
+/** Reduced transparency, increased contrast, or a forced palette. Both fallbacks share one body. */
+export const TRANSPARENCY_OFF =
+    '(prefers-reduced-transparency: reduce), (prefers-contrast: more), (forced-colors: active)';
+
+/** Keeps Tailwind `ring-*` when an effect replaces `box-shadow`. */
+export const RING_PREFIX = 'var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000)';
+
+const EDGE_DECLARATIONS = [
+    ['content', "''"],
+    ['position', 'absolute'],
+    ['inset', '0'],
+    ['border-radius', 'inherit'],
+    ['padding', '1px'],
+    ['background', 'var(--effect-edge)'],
+    ['-webkit-mask', 'linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0)'],
+    ['mask', 'linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0)'],
+    ['-webkit-mask-composite', 'xor'],
+    ['mask-composite', 'exclude'],
+    ['pointer-events', 'none'],
+] as const;
+
+const PAINT_CSS: Record<PaintProperty, string> = {
+    backdropFilter: 'backdrop-filter',
+    background: 'background',
+    backgroundColor: 'background-color',
+    backgroundImage: 'background-image',
+    color: 'color',
+    fontFamily: 'font-family',
+};
+
+const PAINT_ORDER: readonly PaintProperty[] = [
+    'background',
+    'backgroundColor',
+    'backgroundImage',
+    'backdropFilter',
+    'color',
+    'fontFamily',
+];
+
+type Declaration = readonly [property: string, value: string, important: boolean];
+
+export type GenerateEffectSheetInput = {
+    readonly className: string;
+    readonly siblings: readonly string[];
+    readonly layer: EffectLayer;
+};
+
+export type EmitEffectSheetsInput = {
+    readonly outDir: string;
+    readonly layers?: Readonly<Record<string, EffectLayer>>;
+    readonly classNames?: Readonly<Record<string, string>>;
+};
+
+const isOptInClass = (value: string): boolean => (Object.values(effectClasses) as readonly string[]).includes(value);
+
+const hasOwnHook = (on: string): boolean => Object.prototype.hasOwnProperty.call(effectHooks, on);
+
+const onIsHook = (on: string): on is EffectHookId => hasOwnHook(on) && !isOptInClass(on);
+
+const ruleBlock = (selector: string, declarations: readonly Declaration[]): string => {
+    const body = declarations
+        .map(([property, value, important]) => `        ${property}: ${value}${important ? ' !important' : ''};`)
+        .join('\n');
+    return `    ${selector} {\n${body}\n    }`;
+};
+
+const tokenValue = (tokens: EffectLayer['tokens'], key: EffectTokenName, spec: EffectTokenSpec): string => {
+    if (Object.prototype.hasOwnProperty.call(tokens, key)) {
+        const value = Reflect.get(tokens, key) as unknown;
+        if (typeof value === 'string') {
+            return value;
+        }
+    }
+    if (spec.default !== undefined) {
+        return spec.default;
+    }
+    throw new Error(`Missing effect token ${key}`);
+};
+
+const tokenBlock = (className: string, tokens: EffectLayer['tokens']): string => {
+    const lines = (Object.entries(effectTokens) as [EffectTokenName, EffectTokenSpec][]).map(
+        ([key, spec]) => `    --effect-${key}: ${tokenValue(tokens, key, spec)};`
+    );
+    return `.${className} {\n${lines.join('\n')}\n}`;
+};
+
+const fallbackBody = (className: string): string => {
+    const lines = (Object.entries(effectTokens) as [EffectTokenName, EffectTokenSpec][]).flatMap(([key, spec]) => {
+        if (spec.opaque === undefined) {
+            return [];
+        }
+        const value = spec.opaque === 'none' ? 'none' : `var(--effect-${spec.opaque})`;
+        return [`        --effect-${key}: ${value};`];
+    });
+    return `    .${className} {\n${lines.join('\n')}\n    }`;
+};
+
+/** `Object.values(brandsToCSS)` minus `self`, sorted. */
+export const siblingBrandClasses = (self: string): string[] =>
+    Object.values(brandsToCSS)
+        .filter((className) => className !== self)
+        .sort();
+
+/**
+ * `:where(.brand-x <compound>:not(.hui-fx-none)[:not(.other)…:not(.brand-x :is(.other) *)])`.
+ * The island guard is omitted when there are no siblings. Pseudo-elements stay outside `:where`.
+ * A brand island is one level deep; an element under `.brand-x .brand-other .brand-x` gets no effect rules (it fails safe).
+ */
+export const scopeFor =
+    (className: string, siblings: readonly string[]) =>
+    (compound: string): string => {
+        // The island root is excluded as well as its subtree: a locked brand never defines `--effect-*`, so an element
+        // carrying another brand's class would otherwise inherit this brand's tokens. One `:not()` per class, because
+        // jsdom's selector engine misreads `:not(.x :is(...))` (Chromium agrees with this form).
+        const island =
+            siblings.length === 0
+                ? ''
+                : `${siblings.map((sibling) => `:not(.${sibling})`).join('')}:not(.${className} :is(${siblings
+                      .map((sibling) => `.${sibling}`)
+                      .join(', ')}) *)`;
+        return `:where(.${className} ${compound}:not(.${effectClasses.none})${island})`;
+    };
+
+export const composeShadow = (token: string): string => `${RING_PREFIX}, var(--effect-${token})`;
+
+/** First pseudo slot the target does not already paint. Opt-in classes start at `before`. */
+export const edgeSlotFor = (on: string): PseudoSlot => {
+    const taken = isOptInClass(on) || !hasOwnHook(on) ? [] : effectHooks[on as EffectHookId].taken;
+    const slot = freePseudoSlot(taken);
+    if (slot === undefined) {
+        throw new Error(`No free pseudo slot for ${on}`);
+    }
+    return slot;
+};
+
+const decorationDeclarations = (decoration: Decoration): Declaration[] => {
+    const declarations: Declaration[] = [
+        ['content', "''", true],
+        ['position', 'absolute', true],
+        ['pointer-events', 'none', true],
+    ];
+    if (decoration.inset !== undefined) {
+        declarations.push(['inset', decoration.inset, true]);
+    }
+    if (decoration.borderRadius !== undefined) {
+        declarations.push(['border-radius', decoration.borderRadius, true]);
+    }
+    if (decoration.borderWidth !== undefined) {
+        declarations.push(['border-width', decoration.borderWidth, true]);
+    }
+    if (decoration.borderStyle !== undefined) {
+        declarations.push(['border-style', decoration.borderStyle, true]);
+    }
+    if (decoration.borderColor !== undefined) {
+        declarations.push(['border-color', decoration.borderColor, true]);
+    }
+    if (decoration.background !== undefined) {
+        declarations.push(['background', decoration.background, true]);
+    }
+    if (decoration.boxShadow !== undefined) {
+        declarations.push(['box-shadow', decoration.boxShadow, true]);
+    }
+    return declarations;
+};
+
+/** One rule becomes an enforced block, a default block, an edge block, and decoration blocks. */
+export const emitRule = (rule: EffectRule, scope: (compound: string) => string): string => {
+    const optIn = isOptInClass(rule.on);
+    const compound = `${optIn ? `.${rule.on}` : hookSelector(rule.on as EffectHookId)}${
+        rule.unless !== undefined ? `:not(${rule.unless})` : ''
+    }${rule.when !== undefined ? `:${rule.when}` : ''}`;
+    const scoped = (pseudo: '' | '::before' | '::after'): string => `${scope(compound)}${pseudo}`;
+    const blocks: string[] = [];
+
+    const enforced: Declaration[] = [];
+    if (rule.material !== undefined) {
+        const material = materials[rule.material];
+        enforced.push(['background', `var(--effect-${material.fill})`, true]);
+        enforced.push(['-webkit-backdrop-filter', `var(--effect-${material.filter})`, true]);
+        enforced.push(['backdrop-filter', `var(--effect-${material.filter})`, true]);
+        if (material.shadow !== null) {
+            enforced.push(['box-shadow', composeShadow(material.shadow), true]);
+        }
+    }
+    if (rule.shadow !== undefined) {
+        enforced.push(['box-shadow', composeShadow(rule.shadow), true]);
+    }
+    if (rule.paint !== undefined) {
+        for (const property of PAINT_ORDER) {
+            const value = rule.paint[property];
+            if (value === undefined) {
+                continue;
+            }
+            if (property === 'backdropFilter') {
+                enforced.push(['-webkit-backdrop-filter', value, true]);
+            }
+            enforced.push([PAINT_CSS[property], value, true]);
+        }
+    }
+    if (enforced.length > 0) {
+        blocks.push(ruleBlock(scoped(''), enforced));
+    }
+
+    const defaults: Declaration[] = [];
+    if (rule.vars !== undefined) {
+        for (const [key, value] of Object.entries(rule.vars)) {
+            if (value !== undefined) {
+                defaults.push([key, value, false]);
+            }
+        }
+    }
+    if (rule.radius !== undefined) {
+        defaults.push(['border-radius', `var(--effect-${rule.radius})`, false]);
+    }
+    const paintsEdge = rule.material !== undefined && materials[rule.material].edge && rule.when === undefined;
+    const paintsDecoration = rule.before !== undefined || rule.after !== undefined;
+    const unpositionedHook = onIsHook(rule.on) && !effectHooks[rule.on].positioned;
+    if ((optIn || unpositionedHook) && (paintsEdge || paintsDecoration)) {
+        defaults.push(['position', 'relative', false]);
+    }
+    if (defaults.length > 0) {
+        blocks.push(ruleBlock(scoped(''), defaults));
+    }
+
+    if (paintsEdge) {
+        const slot = edgeSlotFor(rule.on);
+        blocks.push(
+            ruleBlock(
+                scoped(slot === 'before' ? '::before' : '::after'),
+                EDGE_DECLARATIONS.map(([property, value]) => [property, value, true])
+            )
+        );
+    }
+    if (rule.before !== undefined) {
+        blocks.push(ruleBlock(scoped('::before'), decorationDeclarations(rule.before)));
+    }
+    if (rule.after !== undefined) {
+        blocks.push(ruleBlock(scoped('::after'), decorationDeclarations(rule.after)));
+    }
+    return blocks.join('\n\n');
+};
+
+export const generateEffectSheet = ({ className, layer, siblings }: GenerateEffectSheetInput): string => {
+    validateEffectLayer(layer);
+    validateRules(vocabularyRules, 'vocabulary');
+    const body = fallbackBody(className);
+    const scope = scopeFor(className, siblings);
+    const layerBlock = `@layer ${EFFECT_LAYER} {\n${[...vocabularyRules, ...layer.rules]
+        .map((rule) => emitRule(rule, scope))
+        .filter((block) => block !== '')
+        .join('\n\n')}\n}`;
+    return `${[
+        `@layer ${EFFECT_LAYER};`,
+        tokenBlock(className, layer.tokens),
+        `@supports not (${BACKDROP_SUPPORT}) {\n${body}\n}`,
+        `@media ${TRANSPARENCY_OFF} {\n${body}\n}`,
+        layerBlock,
+    ].join('\n\n')}\n`;
+};
+
+/**
+ * Writes `<brand>.effects.css` for each registry entry. An empty registry writes nothing.
+ * `layers` and `classNames` are overrides for tests; the build calls this with `outDir` only.
+ */
+export const emitEffectSheets = ({
+    classNames,
+    layers = effectLayers as Readonly<Record<string, EffectLayer>>,
+    outDir,
+}: EmitEffectSheetsInput): string[] => {
+    const entries = Object.entries(layers).sort(([left], [right]) => left.localeCompare(right));
+    if (entries.length === 0) {
+        return [];
+    }
+    mkdirSync(outDir, { recursive: true });
+    const written: string[] = [];
+    for (const [brand, layer] of entries) {
+        const className = classNames?.[brand] ?? (brandsToCSS as Record<string, string>)[brand];
+        if (className === undefined) {
+            throw new Error(`No brand class for effect layer ${brand}`);
+        }
+        const fileName = `${brand}.effects.css`;
+        writeFileSync(
+            path.join(outDir, fileName),
+            generateEffectSheet({ className, layer, siblings: siblingBrandClasses(className) })
+        );
+        written.push(fileName);
+    }
+    return written;
+};