@elastic/distillate 0.0.0 → 0.1.0

package/src/engine.ts

@@ -0,0 +1,191 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { StylesCollector, type StylesCollectorOptions } from './collector';
+import type {
+  DistilleryEnvironment,
+  DistilleryOptions,
+  ThemeVarDefinition,
+} from './environment';
+import { assertCssIdentSegment } from './idents';
+import {
+  createStyleNameResolver,
+  type StyleNameMode,
+  type StyleNameResolver,
+  type StyleNameResolverOptions,
+} from './names';
+import { renderStyles, type RenderStylesOptions } from './runtime';
+import {
+  createStyleModuleWithEnvironment,
+  type PrimitiveStyleAuthoringApi,
+  readableVarOwnersFromEnvironment,
+  type ResolvedStyles,
+  type StyleAuthoringApi,
+  StyleRegistry,
+  type StylesModule,
+  type StylesObject,
+} from './styles';
+import {
+  deriveTheme,
+  requireThemeVariation,
+  resolveThemeValues,
+  resolveThemeVariations,
+  type ThemeTree,
+  type TokensOf,
+  type ValuesOf,
+} from './theme';
+
+/** One component library's binding: environment, registry, and pre-bound operations. Destructure-safe (no `this`). */
+export interface Distillery<
+  TTokens = unknown,
+  TTheme extends ThemeTree = ThemeTree,
+> {
+  /** Resolved environment (tokens, prefix, derived theme vars). */
+  readonly environment: DistilleryEnvironment<TTokens>;
+  /** Derived token tree, same object as `environment.tokens`. */
+  readonly tokens: TTokens;
+  /** Derived theme-var registry, same object as `environment.themeVars`. */
+  readonly themeVars: Readonly<Record<string, ThemeVarDefinition>>;
+  /** Nested literal values for one scheme. Optional `variation` is a name from `variations`. */
+  readonly resolveValues: (
+    scheme: 'light' | 'dark',
+    variation?: string
+  ) => ValuesOf<TTheme>;
+  /** The module registry accumulating collected handles and rules. */
+  readonly registry: StyleRegistry;
+  /** When `true`, collectors warn about no-op handles. */
+  readonly dev: boolean;
+  /** Named handle tree plus tokens. */
+  readonly createStyleModule: <TStyles extends StylesObject>(
+    name: string,
+    factory: (api: StyleAuthoringApi<TTokens>) => TStyles
+  ) => StylesModule<ResolvedStyles<TStyles>>;
+  /** Named handles plus tokens only. */
+  readonly primitiveStyles: <TStyles extends StylesObject>(
+    name: string,
+    factory: (api: PrimitiveStyleAuthoringApi<TTokens>) => TStyles
+  ) => StylesModule<ResolvedStyles<TStyles>>;
+  /** Collector for one render. Class-name resolution collects as a side effect. No-op warnings require `dev: true`; pass `{ warn }` to capture them. */
+  readonly artifactCollector: (
+    names: StyleNameMode,
+    options?: Pick<StylesCollectorOptions, 'warn'>
+  ) => StylesCollector;
+  /** Collector preloaded with every registered module. No-op warnings require `dev: true`; pass `{ warn }` to capture them. */
+  readonly stylesheetCollector: (
+    names?: StyleNameMode,
+    options?: Pick<StylesCollectorOptions, 'warn'>
+  ) => StylesCollector;
+  /** Emits collected CSS for this environment. */
+  readonly renderStyles: (
+    collector: StylesCollector,
+    resolver?: StyleNameResolver,
+    options?: RenderStylesOptions
+  ) => string;
+  /** Creates a standalone name resolver using this distillery's prefix. */
+  readonly createNameResolver: (
+    options: Omit<StyleNameResolverOptions, 'prefix'>
+  ) => StyleNameResolver;
+}
+
+/**
+ * Binds the engine to one library's prefix and theme tree.
+ *
+ * @param options Brand prefix, theme scope, and authoring theme tree.
+ * @throws If `prefix` is not a CSS identifier segment, if a theme key contains a hyphen, if a `lightDark` value is not a CSS `<color>`, if a named variation disagrees with the base, or if `themeVars` / `sharedVars` claim the same readable custom-property name.
+ */
+export const createDistillery = <const TTheme extends ThemeTree>(
+  options: DistilleryOptions<TTheme>
+): Distillery<TokensOf<TTheme>, TTheme> => {
+  const {
+    prefix,
+    themeScope,
+    theme,
+    sharedVars: sharedVarList,
+    variations,
+    dev = false,
+  } = options;
+  assertCssIdentSegment(prefix, 'Distillery prefix');
+  const { tokens, themeVars } = deriveTheme(prefix, theme);
+  const sharedVars = sharedVarList
+    ? Object.freeze(new Set(sharedVarList))
+    : undefined;
+  const resolvedVariations = resolveThemeVariations(
+    prefix,
+    theme,
+    themeVars,
+    variations
+  );
+  const environment: DistilleryEnvironment<TokensOf<TTheme>> = {
+    prefix,
+    themeScope,
+    themeVars: Object.freeze(themeVars),
+    tokens,
+    ...(sharedVars ? { sharedVars } : {}),
+    ...(Object.keys(resolvedVariations).length > 0
+      ? { variations: resolvedVariations }
+      : {}),
+  };
+  const registry = new StyleRegistry(
+    prefix,
+    readableVarOwnersFromEnvironment(environment),
+    sharedVars ?? new Set()
+  );
+
+  return {
+    environment,
+    tokens,
+    themeVars: environment.themeVars,
+    resolveValues: (scheme, variation) =>
+      resolveThemeValues(
+        theme,
+        themeVars,
+        scheme,
+        variation === undefined
+          ? undefined
+          : requireThemeVariation(environment.variations, variation)
+      ),
+    registry,
+    dev,
+    createStyleModule: (name, factory) =>
+      createStyleModuleWithEnvironment(environment, registry, name, factory),
+    primitiveStyles: (name, factory) =>
+      createStyleModuleWithEnvironment(
+        environment,
+        registry,
+        name,
+        ({ css: style, tokens: moduleTokens }) =>
+          factory({ style, tokens: moduleTokens })
+      ),
+    artifactCollector: (names, options) =>
+      new StylesCollector({
+        target: 'artifact',
+        names,
+        registry,
+        prefix,
+        dev,
+        ...(options?.warn ? { warn: options.warn } : {}),
+      }),
+    stylesheetCollector: (names = 'readable', options) => {
+      const collector = new StylesCollector({
+        target: 'stylesheet',
+        names,
+        registry,
+        prefix,
+        dev,
+        ...(options?.warn ? { warn: options.warn } : {}),
+      });
+      for (const module of registry.modules) {
+        collector.useAllEntries(module);
+      }
+      return collector;
+    },
+    renderStyles: (collector, resolver, renderOptions) =>
+      renderStyles(environment, collector, resolver, renderOptions),
+    createNameResolver: (resolverOptions) =>
+      createStyleNameResolver({ ...resolverOptions, prefix }),
+  };
+};

package/src/environment.ts

@@ -0,0 +1,56 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import type {
+  ResolvedThemeVariation,
+  ThemeTree,
+  ThemeVariation,
+} from './theme';
+
+/** One theme CSS variable. Differing `light`/`dark` fold into `light-dark(...)`. */
+export interface ThemeVarDefinition {
+  /** Theme-tree path this definition was derived from. */
+  readonly path: string;
+  /** Emitted CSS custom property name. Equal to `cssVarName(prefix, path)`. */
+  readonly cssVar: `--${string}`;
+  /** Value for light color scheme. */
+  readonly light: string;
+  /** Value for dark color scheme. Equal to `light` for scheme-invariant tokens. */
+  readonly dark: string;
+}
+
+/** Authoring input to `createDistillery`. */
+export interface DistilleryOptions<TTheme extends ThemeTree = ThemeTree> {
+  /** Brand identifier used in readable class and CSS-variable names. Must be a CSS identifier segment. */
+  readonly prefix: string;
+  /** Selector wrapping emitted theme-var declarations. */
+  readonly themeScope: string;
+  /** Nested value tree. Strings and `lightDark` leaves become theme vars; `ScaleToken` leaves inline. */
+  readonly theme: TTheme;
+  /** Named partial variations of `theme`. Declaring a variation does not emit it; name it at `renderStyles`. */
+  readonly variations?: Readonly<Record<string, ThemeVariation<TTheme>>>;
+  /** Cross-module contextual-var paths. Names are `cssVarName(prefix, path)`. Module-local `vars(...)` groups are not listed here. */
+  readonly sharedVars?: readonly `vars/${string}`[];
+  /** When `true`, collectors warn about no-op handles. Default `false`. Does not affect the single-copy guard. */
+  readonly dev?: boolean;
+}
+
+/** Resolved environment: derived `themeVars` / `tokens` plus the bind-time prefix and scope. */
+export interface DistilleryEnvironment<TTokens = unknown> {
+  /** Brand identifier used in readable class and CSS-variable names. Must be a CSS identifier segment. */
+  readonly prefix: string;
+  /** Selector wrapping emitted theme-var declarations. */
+  readonly themeScope: string;
+  /** Theme token path → definition. Emission sorts paths. */
+  readonly themeVars: Readonly<Record<string, ThemeVarDefinition>>;
+  /** Cross-module contextual-var paths. Module-local `vars(...)` groups are not listed here. */
+  readonly sharedVars?: ReadonlySet<`vars/${string}`>;
+  /** Typed token tree, surfaced as `tokens` on the authoring API. */
+  readonly tokens: TTokens;
+  /** Named variations resolved against `themeVars`. Absent when no `variations` were declared. */
+  readonly variations?: Readonly<Record<string, ResolvedThemeVariation>>;
+}

package/src/hash.ts

@@ -0,0 +1,111 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+// Content hashing for anonymous emotion `css`/`injectGlobal` modules.
+//
+// Deterministic 64-bit FNV-1a (two 32-bit passes with distinct offset bases)
+// over a canonical serialization of the authored template. Determinism lets
+// server-rendered and client-rendered class names agree without coordination.
+
+import type { LocalVarMarker } from './local_vars';
+import { isLocalVarMarker } from './local_vars';
+import { isLocalVarRef } from './local_vars';
+import { isHandleLike } from './nesting';
+import {
+  isContextualCssVar,
+  isContextualCssVarName,
+  isCssToken,
+  isScaleToken,
+} from './tokens';
+
+const FNV_PRIME = 0x01000193;
+const FNV_OFFSET_A = 0x811c9dc5;
+// A second basis derived from the golden-ratio constant so the two passes
+// disagree, widening the effective hash to 64 bits.
+const FNV_OFFSET_B = (0x811c9dc5 ^ 0x9e3779b9) >>> 0;
+
+const fnv1a = (input: string, offset: number): number => {
+  let hash = offset;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, FNV_PRIME);
+  }
+  return hash >>> 0;
+};
+
+const base36 = (value: number): string => value.toString(36).padStart(7, '0');
+
+export const contentHash64 = (
+  strings: readonly string[],
+  values: readonly unknown[]
+): string => {
+  const canonical = canonicalize(strings, values);
+  return (
+    base36(fnv1a(canonical, FNV_OFFSET_A)) +
+    base36(fnv1a(canonical, FNV_OFFSET_B))
+  );
+};
+
+// Canonical, injective-enough serialization. Template strings and tagged
+// values are interleaved and joined with a NUL sentinel that cannot appear in
+// authored CSS, so distinct templates cannot collide by concatenation.
+const canonicalize = (
+  strings: readonly string[],
+  values: readonly unknown[]
+): string => {
+  const segments: string[] = [];
+  strings.forEach((part, index) => {
+    segments.push(part);
+    if (index < values.length) {
+      segments.push(tagValue(values[index]));
+    }
+  });
+  return segments.join('\u0000');
+};
+
+const tagValue = (value: unknown): string => {
+  if (typeof value === 'string' || typeof value === 'number') {
+    return `r:${value}`;
+  }
+  if (isCssToken(value)) {
+    return `t:${value.path}`;
+  }
+  if (isContextualCssVar(value)) {
+    return `v:${value.path}`;
+  }
+  if (isContextualCssVarName(value)) {
+    return `n:${value.path}`;
+  }
+  if (isLocalVarRef(value)) {
+    return `l:${value.path}`;
+  }
+  if (isScaleToken(value)) {
+    return `s:${value.value}`;
+  }
+  if (isLocalVarMarker(value)) {
+    return tagMarker(value);
+  }
+  if (isHandleLike(value)) {
+    return `h:${value.key}`;
+  }
+  throw new Error(
+    `Unsupported interpolation in css template. Interpolate a theme token, scale token, contextual var, local var (ref/marker), string, number, or a style handle.`
+  );
+};
+
+const tagMarker = (marker: LocalVarMarker): string => {
+  if (marker.__kind === 'local-var-default-marker') {
+    const entries = marker.defaults
+      .map((item) => `${item.key}=${tagValue(item.value)}`)
+      .sort();
+    return `m:default:${marker.groupId}:${entries.join(',')}`;
+  }
+  const entries = marker.overrides
+    .map((item) => `${item.key}=${tagValue(item.value)}`)
+    .sort();
+  return `m:override:${marker.groupId}:${entries.join(',')}`;
+};

package/src/idents.ts

@@ -0,0 +1,21 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+/**
+ * Throws if `segment` is not a valid CSS identifier segment.
+ *
+ * @param segment Value to validate.
+ * @param role Human-readable label for the error message (e.g. `'Distillery prefix'`).
+ * @throws If `segment` contains characters outside `[A-Za-z_][A-Za-z0-9_-]*`.
+ */
+export const assertCssIdentSegment = (segment: string, role: string): void => {
+  if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(segment)) {
+    throw new Error(
+      `${role} "${segment}" is not a CSS identifier segment. Use a letter or underscore, then letters, digits, hyphens, or underscores.`
+    );
+  }
+};

package/src/index.ts

@@ -0,0 +1,93 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+export { createDistillery, type Distillery } from './engine';
+export {
+  type DistilleryEnvironment,
+  type DistilleryOptions,
+  type ThemeVarDefinition,
+} from './environment';
+export {
+  resolveThemeValues,
+  zipSchemes,
+  type DeepPartialTheme,
+  type MediaThemeVariation,
+  type PathsOf,
+  type ResolvedThemeVariation,
+  type SchemeValueTree,
+  type ThemeTree,
+  type ThemeVariation,
+  type TokensOf,
+  type ValuesOf,
+  type Zipped,
+} from './theme';
+export {
+  contextualVar,
+  cq,
+  isContextualCssVar,
+  isContextualCssVarName,
+  isCssToken,
+  isScaleToken,
+  lightDark,
+  scaleToken,
+  themeToken,
+  type ContextualCssVar,
+  type ContextualCssVarName,
+  type CssToken,
+  type ScaleToken,
+  type SchemePair,
+} from './tokens';
+export {
+  createStyleNameResolver,
+  cssVarName,
+  type StyleNameMode,
+  type StyleNameResolver,
+  type StyleNameResolverOptions,
+  type StyleTarget,
+} from './names';
+export { StylesCollector, type StylesCollectorOptions } from './collector';
+export {
+  renderStyles,
+  type RenderStylesOptions,
+  type ThemeAlternate,
+} from './runtime';
+export {
+  combineClassNames,
+  container,
+  css,
+  decls,
+  mapDomain,
+  media,
+  rule,
+  StyleRegistry,
+  variants,
+  type ContextualVarPath,
+  type CssValue,
+  type CssVarPath,
+  type Declarations,
+  type DeclarationSegment,
+  type DefaultGroupDeps,
+  type DefaultKeyDeps,
+  type LocalVarDefaultMarker,
+  type LocalVarGroup,
+  type LocalVarMarker,
+  type LocalVarOverrideMarker,
+  type LocalVarRef,
+  type PrimitiveStyleAuthoringApi,
+  type ResolvedStyles,
+  type RuleOptions,
+  type StyleAuthoringApi,
+  type StyleDeps,
+  type StyleEntry,
+  type StyleHandle,
+  type StyleMedia,
+  type StyleRegistrySnapshot,
+  type StyleRule,
+  type StylesModule,
+  type StylesObject,
+  type StyleSelectorResolver,
+} from './styles';

package/src/instance.ts

@@ -0,0 +1,49 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+/** `globalThis` key for the loaded copy's identity. See the README. */
+export const INSTANCE_KEY: unique symbol = Symbol.for(
+  'elastic.distillate.instance'
+);
+
+/** Object that may hold the Distillate instance identity, normally `globalThis`. */
+export interface InstanceHost {
+  /** Identity token of the first Distillate copy that registered. */
+  [INSTANCE_KEY]?: string;
+}
+
+/**
+ * Records this copy's identity and warns if a different token is already registered.
+ *
+ * @param host Object carrying the marker, normally `globalThis`.
+ * @param instanceId This copy's identity token.
+ * @param warn Injected so tests need not intercept the console.
+ */
+export const registerDistillateInstance = (
+  host: InstanceHost,
+  instanceId: string,
+  warn: (message: string) => void = (message) => console.warn(message)
+): void => {
+  const registered = host[INSTANCE_KEY];
+  if (registered === undefined) {
+    host[INSTANCE_KEY] = instanceId;
+    return;
+  }
+  if (registered === instanceId) {
+    return;
+  }
+  warn(
+    `@elastic/distillate: a second copy loaded (${instanceId}; already registered ${registered}). ` +
+      'The engine keeps module-scope state, so two copies silently break `variants(...)` tree-shaking ' +
+      'and inflate emitted CSS. Externalize @elastic/distillate in your bundler so exactly one copy loads.'
+  );
+};
+
+registerDistillateInstance(
+  globalThis as InstanceHost,
+  `@elastic/distillate/instance#${Math.random().toString(36).slice(2)}`
+);