@elastic/distillate 0.0.0 → 0.1.0

package/src/styles/registry.ts

@@ -0,0 +1,261 @@
+/*
+ * 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 { DistilleryEnvironment } from '../environment';
+import { cssVarName } from '../names';
+
+import type {
+  ContextualVarPath,
+  CssVarPath,
+  Declarations,
+  StyleRegistrySnapshot,
+  StylesModule,
+} from './types';
+
+/**
+ * Registered style modules for one distillery. Throws on duplicate module names or colliding readable class/var names.
+ */
+export class StyleRegistry {
+  private readonly modulesByName = new Map<string, StylesModule>();
+  private targetedKeys: Set<string> | undefined;
+
+  constructor(
+    private readonly prefix: string,
+    private readonly reservedVarOwners: ReadonlyMap<string, string> = new Map(),
+    private readonly sharedVarPaths: ReadonlySet<string> = new Set()
+  ) {}
+
+  /**
+   * Adds `module` to this registry.
+   *
+   * @throws If another module already uses this name, or if a readable class or CSS-variable name collides (including `themeVars` and `sharedVars`).
+   */
+  registerModule(module: StylesModule): void {
+    const existing = this.modulesByName.get(module.name);
+    if (existing === module) {
+      return;
+    }
+    if (existing) {
+      throw new Error(`Style module "${module.name}" is already registered.`);
+    }
+    assertReadableNameCollisions(
+      this.prefix,
+      this.reservedVarOwners,
+      this.sharedVarPaths,
+      this.modulesByName.values(),
+      module
+    );
+    this.modulesByName.set(module.name, module);
+    this.targetedKeys = undefined;
+  }
+
+  /**
+   * True when some rule, or some inner rule of an `@media` / `@container` block, reads `key` in its selector.
+   *
+   * A nested `&` rule records its owning handle through `recordRuleDeps`, so a handle with an empty self block but real nested rules is targeted. A rule-less nested block targets nothing.
+   */
+  targetsHandle(key: string): boolean {
+    return this.targetedHandleKeys().has(key);
+  }
+
+  private targetedHandleKeys(): Set<string> {
+    if (this.targetedKeys) {
+      return this.targetedKeys;
+    }
+    const keys = new Set<string>();
+    for (const module of this.modulesByName.values()) {
+      for (const entry of module.entries) {
+        if (entry.kind === 'rule') {
+          entry.dependsOn.forEach((dep) => keys.add(dep));
+        } else if (entry.kind === 'media') {
+          for (const inner of entry.rules) {
+            inner.dependsOn.forEach((dep) => keys.add(dep));
+          }
+        }
+      }
+    }
+    this.targetedKeys = keys;
+    return keys;
+  }
+
+  /** Registered modules, sorted by name. */
+  get modules(): readonly StylesModule[] {
+    return [...this.modulesByName.values()].sort((a, b) =>
+      a.name.localeCompare(b.name)
+    );
+  }
+
+  /** Looks up a module by the name passed to `createStyleModule`. */
+  module(name: string): StylesModule | undefined {
+    return this.modulesByName.get(name);
+  }
+
+  /** Handle keys across all modules. Compact-name domain for a full stylesheet. */
+  get classKeys(): readonly string[] {
+    return this.modules.flatMap((module) =>
+      module.handleList.map((handle) => handle.key)
+    );
+  }
+
+  /** Theme and contextual-var keys across all modules. */
+  get cssVarKeys(): readonly CssVarPath[] {
+    const keys = new Set<CssVarPath>();
+    for (const module of this.modules) {
+      module.themeDeps.forEach((path) => keys.add(path));
+      module.varDeps.forEach((path) => keys.add(path));
+    }
+    return [...keys].sort();
+  }
+
+  /**
+   * Frozen class and CSS-var keys for a {@link StyleNameResolver}.
+   *
+   * @param options Overrides the registry-wide key sets when compact-naming a subset.
+   */
+  freeze(
+    options: {
+      /** Compact class-name domain override. */
+      classKeys?: Iterable<string>;
+      /** Compact CSS-var domain override. */
+      cssVarKeys?: Iterable<CssVarPath>;
+    } = {}
+  ): StyleRegistrySnapshot {
+    return Object.freeze({
+      classKeys: Object.freeze(
+        sortedUnique(options.classKeys ?? this.classKeys)
+      ),
+      cssVarKeys: Object.freeze(
+        sortedUnique(options.cssVarKeys ?? this.cssVarKeys)
+      ),
+    });
+  }
+}
+
+const sortedUnique = <TValue extends string>(
+  values: Iterable<TValue>
+): readonly TValue[] => [...new Set(values)].sort();
+
+const claimReadableVar = (
+  owners: Map<string, string>,
+  name: string,
+  owner: string
+): void => {
+  const prior = owners.get(name);
+  if (prior) {
+    throw new Error(
+      `Readable CSS variable "${name}" collides between ${prior} and ${owner}.`
+    );
+  }
+  owners.set(name, owner);
+};
+
+/** Claimed readable custom-property name and the owner that registered it. */
+interface ReadableLocalVarOwner {
+  /** Canonical variable path. */
+  readonly path: ContextualVarPath;
+  /** Human-readable owner used in collision errors. */
+  readonly owner: string;
+}
+
+/** Readable custom-property names already claimed by `themeVars` / `sharedVars`. */
+export const readableVarOwnersFromEnvironment = (
+  environment: Pick<
+    DistilleryEnvironment,
+    'prefix' | 'themeVars' | 'sharedVars'
+  >
+): ReadonlyMap<string, string> => {
+  const owners = new Map<string, string>();
+  const { prefix } = environment;
+  for (const path of Object.keys(environment.themeVars)) {
+    claimReadableVar(owners, cssVarName(prefix, path), `theme var "${path}"`);
+  }
+  for (const path of environment.sharedVars ?? []) {
+    claimReadableVar(owners, cssVarName(prefix, path), `shared var "${path}"`);
+  }
+  return owners;
+};
+
+const assertReadableNameCollisions = (
+  prefix: string,
+  reservedVarOwners: ReadonlyMap<string, string>,
+  sharedVarPaths: ReadonlySet<string>,
+  existing: Iterable<StylesModule>,
+  incoming: StylesModule
+): void => {
+  const classOwners = new Map<string, string>();
+  const reservedOwners = new Map(reservedVarOwners);
+  const localVarOwners = new Map<string, ReadableLocalVarOwner>();
+  const index = (module: StylesModule): void => {
+    for (const handle of module.handleList) {
+      const prior = classOwners.get(handle.readableName);
+      if (prior) {
+        throw new Error(
+          `Readable class name "${handle.readableName}" collides between ${prior} and module "${module.name}" handle "${handle.localName}".`
+        );
+      }
+      classOwners.set(
+        handle.readableName,
+        `module "${module.name}" handle "${handle.localName}"`
+      );
+    }
+    for (const path of localVarPathsOf(module, sharedVarPaths)) {
+      const name = cssVarName(prefix, path);
+      const owner = `module "${module.name}" var "${path}"`;
+      const reserved = reservedOwners.get(name);
+      if (reserved) {
+        throw new Error(
+          `Readable CSS variable "${name}" collides between ${reserved} and ${owner}.`
+        );
+      }
+      const prior = localVarOwners.get(name);
+      if (prior && prior.path !== path) {
+        throw new Error(
+          `Readable CSS variable "${name}" collides between ${prior.owner} and ${owner}.`
+        );
+      }
+      localVarOwners.set(name, { path, owner });
+    }
+  };
+  for (const module of existing) {
+    index(module);
+  }
+  index(incoming);
+};
+
+// `deps.vars` records every contextual var a module *references*, which includes
+// shared ones the module does not own. A shared path synthesizes the same
+// readable name as a local var would, so leaving them in makes two modules that
+// merely reference one shared var collide on it. The same exclusion is applied
+// when compaction maps readable names to compact ones.
+const localVarPathsOf = (
+  module: StylesModule,
+  sharedVarPaths: ReadonlySet<string>
+): readonly ContextualVarPath[] => {
+  const paths = new Set<ContextualVarPath>();
+  const addFrom = (declarations: Declarations): void => {
+    declarations.deps.vars.forEach((path) => {
+      if (!sharedVarPaths.has(path)) {
+        paths.add(path);
+      }
+    });
+    for (const group of declarations.deps.defaults) {
+      for (const item of group.keys) {
+        paths.add(item.path);
+      }
+    }
+  };
+  for (const entry of module.entries) {
+    if (entry.kind === 'handle' || entry.kind === 'rule') {
+      addFrom(entry.declarations);
+    } else {
+      for (const nested of entry.rules) {
+        addFrom(nested.declarations);
+      }
+    }
+  }
+  return [...paths];
+};

package/src/styles/types.ts

@@ -0,0 +1,283 @@
+/*
+ * 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 {
+  LocalVarDefaultMarker,
+  LocalVarGroup,
+  LocalVarMarker,
+  LocalVarOverrideMarker,
+  LocalVarRef,
+} from '../local_vars';
+import type { SelectorAlternative } from '../nesting';
+import type {
+  ContextualCssVar,
+  ContextualCssVarName,
+  CssToken,
+  ScaleToken,
+} from '../tokens';
+
+export type {
+  LocalVarDefaultMarker,
+  LocalVarGroup,
+  LocalVarMarker,
+  LocalVarOverrideMarker,
+  LocalVarRef,
+};
+
+/** Canonical `vars/<group>/<key>` path for a contextual or module-local CSS variable. */
+export type ContextualVarPath = `vars/${string}`;
+/** Theme-token path or any other CSS-var key the resolver knows. */
+export type CssVarPath = string;
+
+/** Values accepted by `t.vars(...)` defaults and `.set(...)`. */
+export type CssValue =
+  | string
+  | number
+  | CssToken
+  | ContextualCssVar
+  | ContextualCssVarName
+  | ScaleToken
+  | LocalVarRef;
+
+/** Reachability sets captured while authoring a declaration block. */
+export interface StyleDeps {
+  /** Theme-token paths interpolated into this block. */
+  readonly theme: ReadonlySet<string>;
+  /** Unconditional writes and reads. Default-marker keys land here only when reachable. */
+  readonly vars: ReadonlySet<ContextualVarPath>;
+  /** Read-side `var(...)` paths. Drives default-emission reachability. */
+  readonly refs: ReadonlySet<ContextualVarPath>;
+  /** `t.vars(...)` default-emission sites, resolved after collection. */
+  readonly defaults: ReadonlyArray<DefaultGroupDeps>;
+}
+
+/** One `t.vars(...)` group's default-emission metadata. */
+export interface DefaultGroupDeps {
+  /** Target variable namespace group. */
+  readonly groupPath: `vars/${string}`;
+  /** Defaults registered within this group. */
+  readonly keys: ReadonlyArray<DefaultKeyDeps>;
+}
+
+/** One key inside a {@link DefaultGroupDeps} group. */
+export interface DefaultKeyDeps {
+  /** The specific variable key within the group. */
+  readonly key: string;
+  /** Full CSS variable path (e.g. `vars/group/key`). */
+  readonly path: ContextualVarPath;
+  /** Theme/var paths referenced by the default value. Kept if the key is reachable. */
+  readonly valueDeps: {
+    /** Theme-token paths the default value interpolates. */
+    readonly theme: ReadonlySet<string>;
+    /** Contextual-var paths the default value interpolates. */
+    readonly vars: ReadonlySet<ContextualVarPath>;
+  };
+}
+
+/** Mutable twin of {@link StyleDeps} used while scanning interpolations. */
+export interface MutableStyleDeps {
+  /** Theme-token paths interpolated into this block. */
+  theme: Set<string>;
+  /** Unconditional writes and reads. */
+  vars: Set<ContextualVarPath>;
+  /** Read-side `var(...)` paths. */
+  refs: Set<ContextualVarPath>;
+  /** `t.vars(...)` default-emission sites. */
+  defaults: DefaultGroupDeps[];
+}
+
+/** Literal CSS text or a local-var interpolation marker. */
+export type DeclarationSegment = string | LocalVarMarker;
+
+/** Authored CSS plus the deps the collector uses for reachability. */
+export interface Declarations {
+  /** Interleaved literal CSS and local variable markers. */
+  readonly css: readonly DeclarationSegment[];
+  /** Reachability tracking dependencies. */
+  readonly deps: StyleDeps;
+}
+
+/** A named class: readable name, declarations, and collection identity. */
+export interface StyleHandle {
+  /** Discriminant for {@link StyleEntry}. */
+  readonly kind: 'handle';
+  /** The registered module name this handle belongs to. */
+  readonly moduleName: string;
+  /** Leaf key if at root, or composed path for nested handles. */
+  readonly localName: string;
+  /** Full path joined by dots. */
+  readonly key: string;
+  /** Predictable name used for output CSS classes. */
+  readonly readableName: string;
+  /** CSS properties for this handle. */
+  readonly declarations: Declarations;
+  /** `true` when produced inside `variants(...)`. Skipped by {@link index.StylesCollector#use | StylesCollector.use}. */
+  readonly variant: boolean;
+  /** Produces the final class name via the provided resolver context. */
+  resolveClassName(context: {
+    /** Joins one or more handles into a class-name string. */
+    resolveClassName: (...handles: StyleHandle[]) => string;
+  }): string;
+}
+
+/** A selector plus declarations, optionally auto-collected from handle deps. */
+export interface StyleRule {
+  /** Discriminant for {@link StyleEntry}. */
+  readonly kind: 'rule';
+  /** The registered module name this rule belongs to. */
+  readonly moduleName: string;
+  /** Unique key for this rule within the module. */
+  readonly key: string;
+  /** Selector string factory receiving a resolver for `&` and other handles. */
+  readonly selector: (h: StyleSelectorResolver) => string;
+  /** CSS properties for this rule. */
+  readonly declarations: Declarations;
+  /** `true` when produced inside `variants(...)`. */
+  readonly variant: boolean;
+  /** Handle keys this selector reads. Empty until `assignEntries` fills it. */
+  readonly dependsOn: ReadonlySet<string>;
+  /** When `false`, skip auto-collection; the caller must `use` the rule. */
+  readonly auto: boolean;
+}
+
+/** Options for {@link rule}. */
+export interface RuleOptions {
+  /** When `false`, the collector must `use` this rule explicitly. Defaults to `true`. */
+  auto?: boolean;
+}
+
+/** `@media` or `@container` block wrapping inner {@link StyleRule}s. */
+export interface StyleMedia {
+  /** Discriminant for {@link StyleEntry}. */
+  readonly kind: 'media';
+  /**
+   * At-rule this entry emits. `kind` stays `'media'` so collector rank and deps apply uniformly; see finding `media-block-ordering`.
+   */
+  readonly atRule?: 'media' | 'container';
+  /** Stable identity for deduplication across multiple renders. */
+  readonly key: string;
+  /** The registered module name this media block belongs to. */
+  readonly moduleName: string;
+  /** The conditional query (e.g. `(min-width: 600px)`). */
+  readonly query: string;
+  /** Inner rules collected inside this block. */
+  readonly rules: readonly StyleRule[];
+  /** `true` when produced inside `variants(...)`. */
+  readonly variant: boolean;
+}
+
+/** One registered handle, selector rule, or at-rule block. */
+export type StyleEntry = StyleHandle | StyleRule | StyleMedia;
+/** Selector factory: call with a handle, or read sibling local names as `.class` strings. */
+export type StyleSelectorResolver = ((handle: StyleHandle) => string) &
+  Record<string, string>;
+
+/** Named handle tree plus flat entries after `createStyleModule`. */
+export interface StylesModule<TStyles = StylesObject> {
+  /** The unique registered name of the module. */
+  readonly name: string;
+  /** Authored tree of handles, rules, and media; variants nest as records. */
+  readonly handles: TStyles;
+  /** Flat list of style entries (handles, rules, media) defined in this module. */
+  readonly entries: readonly StyleEntry[];
+  /** Flat list of just the style handles defined in this module. */
+  readonly handleList: readonly StyleHandle[];
+  /** Aggregated theme dependencies across all entries. */
+  readonly themeDeps: ReadonlySet<string>;
+  /** Aggregated variable dependencies across all entries. */
+  readonly varDeps: ReadonlySet<ContextualVarPath>;
+}
+
+/** Authored module tree before {@link ResolvedStyles} substitution. */
+export type StylesObject = Record<string, unknown>;
+/** Class and CSS-var key snapshot used to build a {@link StyleNameResolver}. */
+export interface StyleRegistrySnapshot {
+  /** Collected readable class names from registered modules. */
+  readonly classKeys: readonly string[];
+  /** Collected custom property (CSS variable) keys. */
+  readonly cssVarKeys: readonly CssVarPath[];
+}
+
+/** Resolves nested pending handles, rules, and medias into their runtime types. */
+export type ResolvedStyles<TValue> = TValue extends PendingStyleHandle
+  ? StyleHandle
+  : TValue extends StyleRule
+    ? StyleRule
+    : TValue extends StyleMedia
+      ? StyleMedia
+      : TValue extends readonly (infer TItem)[]
+        ? readonly ResolvedStyles<TItem>[]
+        : TValue extends Record<string, unknown>
+          ? { [TKey in keyof TValue]: ResolvedStyles<TValue[TKey]> }
+          : TValue;
+
+/** Authoring API passed to `createStyleModule` factories. */
+export interface StyleAuthoringApi<TTokens = unknown> {
+  /** Creates a handle template where nested `&` and `@media` flatten into sibling rules. */
+  css: (
+    strings: TemplateStringsArray,
+    ...values: readonly unknown[]
+  ) => PendingStyleHandle;
+  /** Creates a declaration block template for direct CSS properties. */
+  decls: (
+    strings: TemplateStringsArray,
+    ...values: readonly unknown[]
+  ) => Declarations;
+  /** Module-local CSS variable group. Interpolate `${group}`, `${group.key}`, or `${group.set({...})}`. */
+  vars: <TKey extends string>(
+    group: string,
+    defaults: Record<TKey, CssValue>
+  ) => LocalVarGroup<TKey>;
+  /** Environment token tree. */
+  tokens: TTokens;
+}
+
+/** Authoring-time handle before module registration rewrites it to a {@link StyleHandle}. */
+export interface PendingStyleHandle {
+  /** Discriminant for pending templates. */
+  readonly kind: 'pending-handle';
+  /** Declaration properties authored on this pending handle. */
+  readonly declarations: Declarations;
+  /** Nested `&` / `@media` rules expanded into sibling entries at registration. */
+  readonly nested?: readonly PendingNested[];
+}
+
+/** Nested `&` rule captured on a pending handle. */
+export interface PendingNestedRule {
+  /** Discriminant for pending nested entries. */
+  readonly kind: 'nested-rule';
+  /** Comma alternatives relative to the parent handle. */
+  readonly alternatives: readonly SelectorAlternative[];
+  /** CSS properties for this nested rule. */
+  readonly declarations: Declarations;
+}
+
+/** Nested `@media` captured on a pending handle. */
+export interface PendingNestedMedia {
+  /** Discriminant for pending nested entries. */
+  readonly kind: 'nested-media';
+  /** Media query text. */
+  readonly query: string;
+  /** Bare declarations inside the block, applied to the parent handle. */
+  readonly self?: Declarations;
+  /** Nested `&` rules inside this media block. */
+  readonly rules: readonly PendingNestedRule[];
+}
+
+/** Nested `&` rule or `@media` on a pending handle. */
+export type PendingNested = PendingNestedRule | PendingNestedMedia;
+
+/** Pending handle or already-resolved rule/media during registration. */
+export type PendingEntry = PendingStyleHandle | StyleRule | StyleMedia;
+
+/** Narrow `t` for `primitiveStyles`: handles and tokens only. */
+export interface PrimitiveStyleAuthoringApi<TTokens = unknown> {
+  /** Creates named style handles using the same template tag as `css`. */
+  style: StyleAuthoringApi<TTokens>['css'];
+  /** Environment token tree. */
+  tokens: TTokens;
+}

package/src/testing.ts

@@ -0,0 +1,48 @@
+/*
+ * 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 { isCssToken, isScaleToken } from './tokens';
+
+export {
+  assertVarRefsHaveDeclarations,
+  findVarRefViolations,
+  type VarInvariantViolation,
+} from './var_invariant';
+
+/**
+ * Emits a TypeScript `interface` for a derived token tree, for Monaco extraLib text.
+ *
+ * @param typeName Interface identifier.
+ * @param tree Derived {@link CssToken} / {@link ScaleToken} tree.
+ * @param leafType Identifier used for every leaf. Defaults to `CssInterpolable`.
+ */
+export const tokenTreeDts = (
+  typeName: string,
+  tree: object,
+  leafType = 'CssInterpolable'
+): string => `interface ${typeName} ${emitTokenObject(tree, 0, leafType)}`;
+
+const emitTokenObject = (
+  value: object,
+  indent: number,
+  leafType: string
+): string => {
+  const pad = '  '.repeat(indent);
+  const inner = '  '.repeat(indent + 1);
+  const lines = Object.entries(value as Record<string, unknown>).map(
+    ([key, child]) => {
+      if (isCssToken(child) || isScaleToken(child)) {
+        return `${inner}readonly ${key}: ${leafType};`;
+      }
+      if (child && typeof child === 'object') {
+        return `${inner}readonly ${key}: ${emitTokenObject(child, indent + 1, leafType)};`;
+      }
+      throw new Error(`tokenTreeDts: unexpected leaf at "${key}"`);
+    }
+  );
+  return `{\n${lines.join('\n')}\n${pad}}`;
+};