@elastic/distillate 0.0.0 → 0.1.0

package/src/styles/declarations.ts

@@ -0,0 +1,172 @@
+/*
+ * 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 { isBlankCss } from '../css_scan';
+import { isLocalVarMarker, isLocalVarRef } from '../local_vars';
+import { isHandleLike } from '../nesting';
+import {
+  isContextualCssVar,
+  isContextualCssVarName,
+  isCssToken,
+  isScaleToken,
+} from '../tokens';
+
+import type {
+  Declarations,
+  DeclarationSegment,
+  DefaultKeyDeps,
+  LocalVarMarker,
+  MutableStyleDeps,
+} from './types';
+
+/** Builds a declaration block: interpolations stringify; local-var markers stay until render. */
+export const buildDeclarations = (
+  strings: readonly string[],
+  values: readonly unknown[]
+): Declarations => {
+  const deps: MutableStyleDeps = {
+    theme: new Set(),
+    vars: new Set(),
+    refs: new Set(),
+    defaults: [],
+  };
+  const segments: DeclarationSegment[] = [];
+  let pending = '';
+
+  const flushPending = (): void => {
+    if (pending.length > 0) {
+      segments.push(pending);
+      pending = '';
+    }
+  };
+
+  strings.forEach((part, index) => {
+    pending += part;
+    if (index < values.length) {
+      const value = values[index];
+      if (isLocalVarMarker(value)) {
+        flushPending();
+        // Both default-emission and override-emission markers may carry
+        // theme tokens or shared contextual var refs as values. Walk those
+        // values and record any nested deps onto the host declaration so
+        // tree-shaking and registry registration include them.
+        recordMarkerDeps(value, deps);
+        segments.push(value);
+      } else {
+        pending += stringifyCssValue(value, deps);
+      }
+    }
+  });
+  flushPending();
+
+  assertDeclarationBlock(segments);
+
+  return {
+    css: segments,
+    deps,
+  };
+};
+
+const recordMarkerDeps = (
+  marker: LocalVarMarker,
+  deps: MutableStyleDeps
+): void => {
+  if (marker.__kind === 'local-var-default-marker') {
+    // Default markers contribute their var paths and per-value deps only
+    // through the collector's reachability pass at resolver creation. We
+    // capture per-key value deps here so the collector can fold them in
+    // verbatim when the key survives reachability — and skip them entirely
+    // when it doesn't.
+    deps.defaults.push({
+      groupPath: marker.groupPath,
+      keys: marker.defaults.map((item) => ({
+        key: item.key,
+        path: item.path,
+        valueDeps: computeValueDeps(item.value),
+      })),
+    });
+    return;
+  }
+  for (const item of marker.overrides) {
+    deps.vars.add(item.path);
+    // Stringify each value once to capture nested theme/var deps. The
+    // string return is discarded — the runtime re-stringifies at render
+    // time so compaction sees the same readable refs we record here.
+    stringifyCssValue(item.value, deps);
+  }
+};
+
+/** Theme/var deps recorded while stringifying one declaration value. */
+export const computeValueDeps = (
+  value: unknown
+): DefaultKeyDeps['valueDeps'] => {
+  const local: MutableStyleDeps = {
+    theme: new Set(),
+    vars: new Set(),
+    refs: new Set(),
+    defaults: [],
+  };
+  stringifyCssValue(value, local);
+  return { theme: local.theme, vars: local.vars };
+};
+
+/** Stringifies one interpolable CSS value and records theme/var deps onto `deps`. */
+export const stringifyCssValue = (
+  value: unknown,
+  deps: MutableStyleDeps
+): string => {
+  if (isHandleLike(value)) {
+    throw new Error(
+      'A style handle cannot be interpolated into a declaration value; compose with the emotion compat css instead.'
+    );
+  }
+  if (isCssToken(value)) {
+    deps.theme.add(value.path);
+    return value.ref;
+  }
+  if (isContextualCssVar(value)) {
+    deps.vars.add(value.path);
+    deps.refs.add(value.path);
+    return value.ref;
+  }
+  if (isContextualCssVarName(value)) {
+    // `.name` interpolations are left-hand-side custom-property
+    // identifiers, not `var(...)` references — they belong in `vars` for
+    // registry coverage but not in `refs` (which feeds reachability).
+    deps.vars.add(value.path);
+    return value.name;
+  }
+  if (isLocalVarRef(value)) {
+    deps.vars.add(value.path);
+    deps.refs.add(value.path);
+    return value.ref;
+  }
+  if (isScaleToken(value)) {
+    return value.value;
+  }
+  return String(value);
+};
+
+/** True when every segment is comments, whitespace, or bare `;`. A local-var marker counts as content. */
+export const isEmptyDeclarations = ({ css }: Declarations): boolean =>
+  css.every((segment) => typeof segment === 'string' && isBlankCss(segment));
+
+const assertDeclarationBlock = (
+  segments: readonly DeclarationSegment[]
+): void => {
+  for (const segment of segments) {
+    if (typeof segment !== 'string') {
+      continue;
+    }
+    if (
+      /[{}]/.test(segment) ||
+      /(^|[\s;])@(?:media|supports|container)\b/i.test(segment)
+    ) {
+      throw new Error('css and decls accept declaration blocks only.');
+    }
+  }
+};

package/src/styles/index.ts

@@ -0,0 +1,58 @@
+/*
+ * 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 '../instance';
+
+export {
+  combineClassNames,
+  container,
+  css,
+  decls,
+  globalStylesFromFlattened,
+  isVariantMarked,
+  mapDomain,
+  media,
+  pendingHandleFromFlattened,
+  rule,
+  variants,
+} from './authoring';
+export {
+  computeValueDeps,
+  isEmptyDeclarations,
+  stringifyCssValue,
+} from './declarations';
+export { createStyleModuleWithEnvironment } from './module';
+export { readableVarOwnersFromEnvironment, StyleRegistry } from './registry';
+export type {
+  ContextualVarPath,
+  CssValue,
+  CssVarPath,
+  DeclarationSegment,
+  Declarations,
+  DefaultGroupDeps,
+  DefaultKeyDeps,
+  LocalVarDefaultMarker,
+  LocalVarGroup,
+  LocalVarMarker,
+  LocalVarOverrideMarker,
+  LocalVarRef,
+  MutableStyleDeps,
+  PendingStyleHandle,
+  PrimitiveStyleAuthoringApi,
+  ResolvedStyles,
+  RuleOptions,
+  StyleAuthoringApi,
+  StyleDeps,
+  StyleEntry,
+  StyleHandle,
+  StyleMedia,
+  StyleRegistrySnapshot,
+  StyleRule,
+  StylesModule,
+  StylesObject,
+  StyleSelectorResolver,
+} from './types';

package/src/styles/module.ts

@@ -0,0 +1,396 @@
+/*
+ * 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 { assertCssIdentSegment } from '../idents';
+import { createLocalVarGroup, type LocalVarGroup } from '../local_vars';
+import type { SelectorAlternative } from '../nesting';
+
+import { css, decls, EMPTY_DEPS, isVariantMarked } from './authoring';
+import type { StyleRegistry } from './registry';
+import type {
+  ContextualVarPath,
+  CssValue,
+  PendingEntry,
+  PendingNested,
+  PendingNestedRule,
+  PendingStyleHandle,
+  ResolvedStyles,
+  StyleAuthoringApi,
+  StyleDeps,
+  StyleEntry,
+  StyleHandle,
+  StyleMedia,
+  StyleRule,
+  StyleSelectorResolver,
+  StylesModule,
+  StylesObject,
+} from './types';
+
+export const createStyleModuleWithEnvironment = <
+  TTokens,
+  TStyles extends StylesObject,
+>(
+  environment: DistilleryEnvironment<TTokens>,
+  registry: StyleRegistry,
+  name: string,
+  factory: (t: StyleAuthoringApi<TTokens>) => TStyles
+): StylesModule<ResolvedStyles<TStyles>> => {
+  assertCssIdentSegment(name, 'Style module name');
+  const t = createAuthoringApi(environment, name);
+  const authored = factory(t);
+  const entries: StyleEntry[] = [];
+  const handleList: StyleHandle[] = [];
+  const themeDeps = new Set<string>();
+  const varDeps = new Set<ContextualVarPath>();
+
+  assignEntries(name, authored, [], entries, handleList, themeDeps, varDeps);
+  recordRuleDeps(entries, handleList);
+
+  const module: StylesModule<ResolvedStyles<TStyles>> = {
+    name,
+    handles: authored as ResolvedStyles<TStyles>,
+    entries,
+    handleList,
+    themeDeps,
+    varDeps,
+  };
+  registry.registerModule(module);
+  return module;
+};
+
+const createAuthoringApi = <TTokens>(
+  environment: DistilleryEnvironment<TTokens>,
+  moduleName: string
+): StyleAuthoringApi<TTokens> => ({
+  css,
+  decls,
+  vars: <TKey extends string>(
+    group: string,
+    defaults: Record<TKey, CssValue>
+  ): LocalVarGroup<TKey> =>
+    createLocalVarGroup(environment.prefix, moduleName, group, defaults),
+  tokens: environment.tokens,
+});
+
+const assignEntries = (
+  moduleName: string,
+  value: unknown,
+  path: readonly string[],
+  entries: StyleEntry[],
+  handles: StyleHandle[],
+  themeDeps: Set<string>,
+  varDeps: Set<ContextualVarPath>,
+  inheritedVariant = false
+): unknown => {
+  // A value is considered "variant" when either the immediate node was
+  // produced inside a `variants(...)` factory, or it sits beneath a parent
+  // `variants(...)` record (covers nested handles inside a per-variant
+  // object literal). The flag is sticky once set during the walk.
+  const variantHere = inheritedVariant || isVariantMarked(value);
+
+  if (isPendingHandle(value)) {
+    const localName = path.join('/');
+    const handle: StyleHandle = {
+      kind: 'handle',
+      moduleName,
+      localName,
+      key: `${moduleName}/${localName}`,
+      readableName: `${moduleName}-${path.join('-')}`,
+      declarations: value.declarations,
+      variant: variantHere,
+      resolveClassName: (context) => context.resolveClassName(handle),
+    };
+    entries.push(handle);
+    handles.push(handle);
+    copyDeps(value.declarations.deps, themeDeps, varDeps);
+    if (value.nested && value.nested.length > 0) {
+      expandNestedEntries(
+        moduleName,
+        handle,
+        value.nested,
+        variantHere,
+        entries,
+        themeDeps,
+        varDeps
+      );
+    }
+    return handle;
+  }
+
+  if (isRule(value)) {
+    const keyedRule: StyleRule = {
+      ...value,
+      moduleName,
+      key: `${moduleName}/${path.join('/')}`,
+      variant: variantHere,
+    };
+    entries.push(keyedRule);
+    copyDeps(value.declarations.deps, themeDeps, varDeps);
+    return keyedRule;
+  }
+
+  if (isMedia(value)) {
+    const mediaKey = `${moduleName}/${path.join('/')}`;
+    const keyedMedia: StyleMedia = {
+      ...value,
+      key: mediaKey,
+      moduleName,
+      variant: variantHere,
+      rules: value.rules.map((child, index) => ({
+        ...child,
+        moduleName,
+        key: `${mediaKey}/${index}`,
+        variant: variantHere,
+      })),
+    };
+    entries.push(keyedMedia);
+    for (const child of keyedMedia.rules) {
+      copyDeps(child.declarations.deps, themeDeps, varDeps);
+    }
+    return keyedMedia;
+  }
+
+  if (value && typeof value === 'object') {
+    for (const [key, child] of Object.entries(value)) {
+      assertCssIdentSegment(key, `Style module "${moduleName}" key`);
+      const assigned = assignEntries(
+        moduleName,
+        child,
+        [...path, key],
+        entries,
+        handles,
+        themeDeps,
+        varDeps,
+        variantHere
+      );
+      if (assigned) {
+        (value as Record<string, unknown>)[key] = assigned;
+      }
+    }
+  }
+
+  return value;
+};
+
+const MAX_NESTED_SIBLINGS = 1000;
+
+// Zero-padded so `collectedEntries` (lexicographic sort) preserves source order past 9 siblings.
+const paddedIndex = (index: number): string => {
+  if (index >= MAX_NESTED_SIBLINGS) {
+    throw new Error(
+      `A single css template cannot have more than ${MAX_NESTED_SIBLINGS} nested blocks.`
+    );
+  }
+  return String(index).padStart(3, '0');
+};
+
+const composeNestedSelector =
+  (self: StyleHandle, alternatives: readonly SelectorAlternative[]) =>
+  (h: StyleSelectorResolver): string =>
+    alternatives
+      .map((parts) =>
+        parts
+          .map((part) =>
+            typeof part === 'string'
+              ? part.replaceAll('&', `.${h(self)}`)
+              : `.${h(part)}`
+          )
+          .join('')
+      )
+      .join(',');
+
+const expandNestedEntries = (
+  moduleName: string,
+  self: StyleHandle,
+  nested: readonly PendingNested[],
+  variant: boolean,
+  entries: StyleEntry[],
+  themeDeps: Set<string>,
+  varDeps: Set<ContextualVarPath>
+): void => {
+  nested.forEach((entry, index) => {
+    const key = `${self.key}/&/${paddedIndex(index)}`;
+    if (entry.kind === 'nested-rule') {
+      entries.push(
+        makeNestedRule(
+          moduleName,
+          key,
+          self,
+          entry,
+          variant,
+          themeDeps,
+          varDeps
+        )
+      );
+      return;
+    }
+    const rules: StyleRule[] = [];
+    if (entry.self) {
+      rules.push(
+        makeNestedRule(
+          moduleName,
+          `${key}/${paddedIndex(0)}`,
+          self,
+          {
+            kind: 'nested-rule',
+            alternatives: [['&']],
+            declarations: entry.self,
+          },
+          variant,
+          themeDeps,
+          varDeps
+        )
+      );
+    }
+    entry.rules.forEach((rule, ruleIndex) => {
+      rules.push(
+        makeNestedRule(
+          moduleName,
+          `${key}/${paddedIndex(ruleIndex + (entry.self ? 1 : 0))}`,
+          self,
+          rule,
+          variant,
+          themeDeps,
+          varDeps
+        )
+      );
+    });
+    entries.push({
+      kind: 'media',
+      key,
+      moduleName,
+      query: entry.query,
+      rules,
+      variant,
+    });
+  });
+};
+
+const makeNestedRule = (
+  moduleName: string,
+  key: string,
+  self: StyleHandle,
+  rule: PendingNestedRule,
+  variant: boolean,
+  themeDeps: Set<string>,
+  varDeps: Set<ContextualVarPath>
+): StyleRule => {
+  copyDeps(rule.declarations.deps, themeDeps, varDeps);
+  return {
+    kind: 'rule',
+    moduleName,
+    key,
+    selector: composeNestedSelector(self, rule.alternatives),
+    declarations: rule.declarations,
+    dependsOn: EMPTY_DEPS,
+    auto: true,
+    variant,
+  };
+};
+
+const recordRuleDeps = (
+  entries: readonly StyleEntry[],
+  handles: readonly StyleHandle[]
+): void => {
+  if (entries.length === 0) {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.kind === 'rule') {
+      assignDependsOn(entry, computeRuleDeps(entry, handles));
+      continue;
+    }
+    if (entry.kind === 'media') {
+      for (const nested of entry.rules) {
+        assignDependsOn(nested, computeRuleDeps(nested, handles));
+      }
+    }
+  }
+};
+
+const assignDependsOn = (
+  rule: StyleRule,
+  dependsOn: ReadonlySet<string>
+): void => {
+  (rule as { dependsOn: ReadonlySet<string> }).dependsOn = dependsOn;
+};
+
+const computeRuleDeps = (
+  rule: StyleRule,
+  handles: readonly StyleHandle[]
+): ReadonlySet<string> => {
+  const accessed = new Set<string>();
+  const trackingResolver = ((handle: StyleHandle) => {
+    accessed.add(handle.key);
+    return `.${handle.readableName}`;
+  }) as StyleSelectorResolver;
+  for (const handle of handles) {
+    defineTrackingAlias(trackingResolver, handle.localName, handle, accessed);
+    const leafName = handle.localName.split('/').at(-1);
+    if (leafName && leafName !== handle.localName) {
+      defineTrackingAlias(trackingResolver, leafName, handle, accessed);
+    }
+  }
+  try {
+    rule.selector(trackingResolver);
+  } catch {
+    // Selector factories are expected to be pure string-builders, but a
+    // factory that throws on dummy input shouldn't break module construction.
+    // The dep set stays whatever was recorded before the throw.
+  }
+  return accessed;
+};
+
+const defineTrackingAlias = (
+  resolver: StyleSelectorResolver,
+  name: string,
+  handle: StyleHandle,
+  accessed: Set<string>
+): void => {
+  if (!/^[A-Za-z_$][\w$]*$/.test(name) || name in resolver) {
+    return;
+  }
+  Object.defineProperty(resolver, name, {
+    configurable: true,
+    enumerable: true,
+    get: () => {
+      accessed.add(handle.key);
+      return `.${handle.readableName}`;
+    },
+  });
+};
+
+const copyDeps = (
+  deps: StyleDeps,
+  themeDeps: Set<string>,
+  varDeps: Set<ContextualVarPath>
+): void => {
+  deps.theme.forEach((path) => themeDeps.add(path));
+  deps.vars.forEach((path) => varDeps.add(path));
+};
+
+const isPendingHandle = (value: unknown): value is PendingStyleHandle =>
+  Boolean(
+    value &&
+    typeof value === 'object' &&
+    (value as PendingEntry).kind === 'pending-handle'
+  );
+
+const isRule = (value: unknown): value is StyleRule =>
+  Boolean(
+    value &&
+    typeof value === 'object' &&
+    (value as PendingEntry).kind === 'rule'
+  );
+
+const isMedia = (value: unknown): value is StyleMedia =>
+  Boolean(
+    value &&
+    typeof value === 'object' &&
+    (value as PendingEntry).kind === 'media'
+  );