@elastic/distillate 0.0.0 → 0.1.0

package/src/css_scan.ts

@@ -0,0 +1,263 @@
+/*
+ * 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.
+ */
+
+// One scanner for the three passes that need to read CSS text: minification,
+// the `@media` canonicalization in `nesting.ts`, and the var invariant in
+// `./testing`. Each of those grew its own character loop, and each learned the
+// same lessons separately and late — comments inside `url(...)`, backslash
+// escapes, at-rules inside `url(...)`, selector-versus-declaration position.
+// A span is the unit all three actually need: a stretch of text with a kind
+// that says whether its contents are code or opaque, plus where it sits.
+//
+// This is deliberately not a CSS Syntax Level 3 tokenizer. It models the six
+// things those passes get wrong and nothing else, because a promise of full
+// conformance is one this module would not keep.
+
+/** What a span's text is, which decides whether a pass may look inside it. */
+export type CssSpanKind =
+  /** `/* … *\/`, including the delimiters. Opaque. */
+  | 'comment'
+  /** A quoted string, including the quotes and any escapes. Opaque. */
+  | 'string'
+  /** An unquoted `url(…)` function token, including the parentheses. Opaque. */
+  | 'url'
+  /** A backslash and the character it escapes, outside a string. Opaque. */
+  | 'escape'
+  /** A run of whitespace. */
+  | 'whitespace'
+  /** One of `{ } : ; , >`. */
+  | 'structural'
+  /** Anything else, run together: identifiers, values, selectors, `var(`. */
+  | 'text';
+
+/** Whether the enclosing block holds declarations or further rules. */
+export type CssBlockKind = 'rules' | 'declarations';
+
+/** One scanner span: kind, source slice, and block context. */
+export interface CssSpan {
+  /** What this span's text is; opaque kinds are skipped by later passes. */
+  readonly kind: CssSpanKind;
+  /** Source slice for this span, including delimiters. */
+  readonly text: string;
+  /** Index of the first character in the source. */
+  readonly start: number;
+  /** Index one past the last character in the source. */
+  readonly end: number;
+  /**
+   * What the enclosing block holds. An at-rule prelude (`@media …`) opens a
+   * block of rules; anything else opens declarations; top level is rules.
+   *
+   * This is what separates `color : red` — where the space before `:` is
+   * noise — from `.menu :hover`, where it is a descendant combinator.
+   */
+  readonly block: CssBlockKind;
+  /** Block nesting depth; `0` at top level. */
+  readonly depth: number;
+}
+
+const STRUCTURAL = new Set(['{', '}', ':', ';', ',', '>']);
+const URL_PREFIX = 'url(';
+
+/** `true` when an unquoted `url(` function token starts at `index`. */
+const isUnquotedUrlStart = (value: string, index: number): boolean => {
+  // Cheap rejection first: this runs at every index of every text span, and
+  // all but one character in a few hundred fails here rather than in a
+  // `slice().toLowerCase()`.
+  const head = value[index];
+  if (head !== 'u' && head !== 'U') {
+    return false;
+  }
+  // `url(` has to open a function token rather than end a longer identifier.
+  // `myurl(/a/*b*/c)` is some other function, and reading it as a url would
+  // make its contents opaque — hiding a real comment from every pass.
+  const before = value[index - 1];
+  if (before !== undefined && /[\w\\-]/.test(before)) {
+    return false;
+  }
+  if (
+    value.slice(index, index + URL_PREFIX.length).toLowerCase() !== URL_PREFIX
+  ) {
+    return false;
+  }
+  let cursor = index + URL_PREFIX.length;
+  while (cursor < value.length && /\s/.test(value[cursor] ?? '')) {
+    cursor += 1;
+  }
+  const first = value[cursor];
+  return first !== '"' && first !== "'";
+};
+
+/** Index one past an unquoted `url(…)` token that starts at `start`. */
+const endOfUrl = (value: string, start: number): number => {
+  for (
+    let index = start + URL_PREFIX.length;
+    index < value.length;
+    index += 1
+  ) {
+    const char = value[index];
+    if (char === '\\' && index + 1 < value.length) {
+      index += 1;
+      continue;
+    }
+    if (char === ')') {
+      return index + 1;
+    }
+  }
+  return value.length;
+};
+
+/** Index one past a quoted string that starts at `start`. Unterminated runs to the end. */
+const endOfString = (value: string, start: number): number => {
+  const quote = value[start];
+  for (let index = start + 1; index < value.length; index += 1) {
+    const char = value[index];
+    if (char === '\\' && index + 1 < value.length) {
+      index += 1;
+      continue;
+    }
+    if (char === quote) {
+      return index + 1;
+    }
+  }
+  return value.length;
+};
+
+/** Index one past a `/* … *\/` comment that starts at `start`. Unterminated runs to the end. */
+const endOfComment = (value: string, start: number): number => {
+  const closing = value.indexOf('*/', start + 2);
+  return closing === -1 ? value.length : closing + 2;
+};
+
+/**
+ * Splits `value` into spans.
+ *
+ * Concatenating every span's `text` reproduces `value` exactly, which is what
+ * lets a pass rewrite the spans it understands and copy the rest through.
+ *
+ * @param value CSS text.
+ */
+export const scanCss = (value: string): readonly CssSpan[] => {
+  const spans: CssSpan[] = [];
+  const blocks: CssBlockKind[] = ['rules'];
+  // Null until the first significant character of a prelude is seen, so that
+  // `@media …{` opens rules and `.a …{` opens declarations.
+  let preludeIsAtRule: boolean | null = null;
+  let index = 0;
+
+  const push = (kind: CssSpanKind, start: number, end: number): void => {
+    spans.push({
+      kind,
+      text: value.slice(start, end),
+      start,
+      end,
+      block: blocks.at(-1) ?? 'rules',
+      depth: blocks.length - 1,
+    });
+  };
+
+  while (index < value.length) {
+    const char = value[index] ?? '';
+    const next = value[index + 1];
+
+    if (char === '/' && next === '*') {
+      const end = endOfComment(value, index);
+      push('comment', index, end);
+      index = end;
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      const end = endOfString(value, index);
+      push('string', index, end);
+      index = end;
+      continue;
+    }
+
+    if (char === '\\' && next !== undefined) {
+      push('escape', index, index + 2);
+      index += 2;
+      continue;
+    }
+
+    if (isUnquotedUrlStart(value, index)) {
+      const end = endOfUrl(value, index);
+      push('url', index, end);
+      index = end;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      let end = index + 1;
+      while (end < value.length && /\s/.test(value[end] ?? '')) {
+        end += 1;
+      }
+      push('whitespace', index, end);
+      index = end;
+      continue;
+    }
+
+    if (STRUCTURAL.has(char)) {
+      // Depth changes after the span is recorded, so `{` reads as belonging to
+      // the block it closes over rather than the one it opens.
+      push('structural', index, index + 1);
+      if (char === '{') {
+        blocks.push(preludeIsAtRule ? 'rules' : 'declarations');
+      } else if (char === '}' && blocks.length > 1) {
+        blocks.pop();
+      }
+      if (char === '{' || char === '}' || char === ';') {
+        preludeIsAtRule = null;
+      }
+      index += 1;
+      continue;
+    }
+
+    if (preludeIsAtRule === null) {
+      preludeIsAtRule = char === '@';
+    }
+    let end = index + 1;
+    while (end < value.length) {
+      const ahead = value[end] ?? '';
+      if (
+        STRUCTURAL.has(ahead) ||
+        /\s/.test(ahead) ||
+        ahead === '"' ||
+        ahead === "'" ||
+        ahead === '\\' ||
+        (ahead === '/' && value[end + 1] === '*') ||
+        isUnquotedUrlStart(value, end)
+      ) {
+        break;
+      }
+      end += 1;
+    }
+    push('text', index, end);
+    index = end;
+  }
+
+  return spans;
+};
+
+/**
+ * `true` for spans whose text is a literal rather than code — a comment, a
+ * quoted string, an unquoted `url(...)`, or an escape pair. A pass may rewrite
+ * what is inside a code span and must copy an opaque one through untouched.
+ */
+export const isOpaque = (span: CssSpan): boolean =>
+  span.kind === 'comment' ||
+  span.kind === 'string' ||
+  span.kind === 'url' ||
+  span.kind === 'escape';
+
+/** True when `value` has no declarations left after comments, whitespace, and bare `;` are ignored. */
+export const isBlankCss = (value: string): boolean =>
+  scanCss(value).every(
+    (span) =>
+      span.kind === 'comment' ||
+      span.kind === 'whitespace' ||
+      (span.kind === 'structural' && span.text === ';')
+  );

package/src/dom_sink.ts

@@ -0,0 +1,65 @@
+/*
+ * 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 { StyleSink } from './emotion';
+
+/** Minimal interface for a DOM `<style>` element. */
+export interface StyleElementLike {
+  /** Current stylesheet text, or `null` before the first flush. */
+  textContent: string | null;
+}
+
+/** Minimal interface for a DOM `Document` able to create and append style tags. */
+export interface DocumentLike {
+  /** Creates a `<style>` element. */
+  createElement(tagName: 'style'): StyleElementLike;
+  /** Node that receives the created style element. */
+  readonly head: { appendChild(node: StyleElementLike): void };
+}
+
+/** Host document and optional flush scheduler for a `<style>` sink. */
+export interface CreateDomSinkOptions {
+  /** The host document where the style element will be appended. */
+  document: DocumentLike;
+  /** Defers the flush. Defaults to `queueMicrotask`. */
+  schedule?: (flush: () => void) => void;
+}
+
+/**
+ * One managed `<style>` element, rewritten on each flush.
+ */
+export const createDomSink = ({
+  document,
+  schedule = queueMicrotask,
+}: CreateDomSinkOptions): StyleSink => {
+  let element: StyleElementLike | null = null;
+  let dirty = false;
+  let latestRender: (() => string) | null = null;
+
+  const flush = (): void => {
+    dirty = false;
+    if (!latestRender) {
+      return;
+    }
+    if (!element) {
+      element = document.createElement('style');
+      document.head.appendChild(element);
+    }
+    element.textContent = latestRender();
+  };
+
+  return {
+    invalidate(render) {
+      latestRender = render;
+      if (dirty) {
+        return;
+      }
+      dirty = true;
+      schedule(flush);
+    },
+  };
+};

package/src/emotion.ts

@@ -0,0 +1,311 @@
+/*
+ * 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 { Distillery } from './engine';
+import { contentHash64 } from './hash';
+import { flattenTemplate, isHandleLike, type TemplateSlice } from './nesting';
+import {
+  globalStylesFromFlattened,
+  pendingHandleFromFlattened,
+  type StyleHandle,
+  type StyleRegistry,
+  type StylesModule,
+} from './styles';
+
+export {
+  createDomSink,
+  type CreateDomSinkOptions,
+  type DocumentLike,
+  type StyleElementLike,
+} from './dom_sink';
+
+/** Receives stylesheet invalidation from Emotion compat modules. */
+export interface StyleSink {
+  /** Marks the sink dirty. `render` produces the current stylesheet when it flushes. */
+  invalidate(render: () => string): void;
+}
+
+/** Shared sink for Emotion compat modules on one registry. */
+export interface CreateEmotionOptions {
+  /** Notified when a compat module registers. Shared across `createEmotion` calls on the same registry. */
+  sink?: StyleSink;
+}
+
+/** Style handle that stringifies to its readable class name. */
+export interface EmotionCss extends StyleHandle {
+  /** Stringifies to the readable class name. */
+  toString(): string;
+  /** Template interpolation; same as {@link EmotionCss.toString}. */
+  [Symbol.toPrimitive](hint: string): string;
+}
+
+/** One `cx(...)` argument: a class, handle, list, or truthy map. */
+export type ClassNameArg =
+  | string
+  | number
+  | false
+  | null
+  | undefined
+  | EmotionCss
+  | StyleHandle
+  | ClassNameArg[]
+  | { readonly [className: string]: boolean };
+
+/** Emotion-shaped authoring API bound to one Distillery registry. */
+export interface Emotion {
+  /** Authors styles and returns a handle that can be used directly or passed to `cx`. */
+  css(strings: TemplateStringsArray, ...values: readonly unknown[]): EmotionCss;
+  /** Combines handles, conditional classes, and plain strings into a space-separated string. */
+  cx(...args: readonly ClassNameArg[]): string;
+  /** Defines styles that apply globally (e.g. `body`, `html`). */
+  injectGlobal(
+    strings: TemplateStringsArray,
+    ...values: readonly unknown[]
+  ): void;
+  /** Emits the full CSS for all generated emotion styles. */
+  stylesheet(): string;
+  /** Returns the underlying modules backing `injectGlobal` calls. */
+  globalModules(): readonly StylesModule[];
+}
+
+/** Per-registry Emotion compat cache. */
+interface EmotionState {
+  /** `css` handles keyed by source hash. */
+  readonly wrappers: Map<string, EmotionCss>;
+  /** Original templates for inlining nested compat handles. */
+  readonly rawSources: Map<string, TemplateSlice>;
+  /** Module name → canonical source hash. */
+  readonly canonicalByModule: Map<string, string>;
+  /** Modules produced by `injectGlobal`. */
+  readonly globals: StylesModule[];
+  /** Handles created by this registry's Emotion instance. */
+  readonly brand: WeakSet<object>;
+  /** Sinks notified when a compat module registers. */
+  readonly sinks: Set<StyleSink>;
+}
+
+const stateByRegistry = new WeakMap<StyleRegistry, EmotionState>();
+
+const stateFor = (registry: StyleRegistry): EmotionState => {
+  let state = stateByRegistry.get(registry);
+  if (!state) {
+    state = {
+      wrappers: new Map(),
+      rawSources: new Map(),
+      canonicalByModule: new Map(),
+      globals: [],
+      brand: new WeakSet(),
+      sinks: new Set(),
+    };
+    stateByRegistry.set(registry, state);
+  }
+  return state;
+};
+
+/**
+ * `@emotion/css`-shaped API over a distillery.
+ *
+ * `String(css\`...\`)` is the readable class name and does not collect. Passing the wrapper through `resolveClassName` collects and compacts like a native handle.
+ *
+ * @param distillery Bound distillery that owns the underlying registry.
+ * @param options Optional sink for DOM injection.
+ */
+export const createEmotion = <TTokens>(
+  distillery: Distillery<TTokens>,
+  options: CreateEmotionOptions = {}
+): Emotion => {
+  const { registry } = distillery;
+  const state = stateFor(registry);
+
+  const stylesheet = (): string =>
+    distillery.renderStyles(distillery.stylesheetCollector('readable'));
+
+  const invalidateSinks = (): void => {
+    for (const sink of state.sinks) {
+      sink.invalidate(stylesheet);
+    }
+  };
+
+  if (options.sink) {
+    state.sinks.add(options.sink);
+    // Catch a late-attached sink up to styles already registered on this
+    // registry: cached `css`/`injectGlobal` calls return early without
+    // invalidating, so without this the managed `<style>` would miss every
+    // style registered before the sink was attached.
+    options.sink.invalidate(stylesheet);
+  }
+
+  const inlineValue = (
+    value: unknown,
+    position: 'selector' | 'statement'
+  ): TemplateSlice | null => {
+    if (position !== 'statement' || !isBranded(state, value)) {
+      return null;
+    }
+    return state.rawSources.get((value as StyleHandle).key) ?? null;
+  };
+
+  const css = (
+    strings: TemplateStringsArray,
+    ...values: readonly unknown[]
+  ): EmotionCss => {
+    assertTemplate(strings, 'css');
+    const hash = contentHash64(strings, values);
+    const cached = state.wrappers.get(hash);
+    if (cached) {
+      return cached;
+    }
+    const moduleName = `css-${hash}`;
+    const canonical = canonicalKey(strings, values);
+    detectCollision(state, moduleName, canonical);
+
+    const flat = flattenTemplate(strings, values, {
+      mode: 'self',
+      inlineValue,
+    });
+    const pending = pendingHandleFromFlattened(flat);
+    const module = distillery.createStyleModule(moduleName, () => ({
+      root: pending,
+    }));
+    const handle = module.handles.root;
+
+    state.rawSources.set(handle.key, {
+      strings: [...strings],
+      values: [...values],
+    });
+    const wrapper = makeWrapper(handle);
+    state.brand.add(wrapper);
+    state.wrappers.set(hash, wrapper);
+    state.canonicalByModule.set(moduleName, canonical);
+    invalidateSinks();
+    return wrapper;
+  };
+
+  const injectGlobal = (
+    strings: TemplateStringsArray,
+    ...values: readonly unknown[]
+  ): void => {
+    assertTemplate(strings, 'injectGlobal');
+    const hash = contentHash64(strings, values);
+    const moduleName = `global-${hash}`;
+    if (registry.module(moduleName)) {
+      return;
+    }
+    const canonical = canonicalKey(strings, values);
+    detectCollision(state, moduleName, canonical);
+
+    const flat = flattenTemplate(strings, values, {
+      mode: 'global',
+      inlineValue,
+    });
+    const module = distillery.createStyleModule(moduleName, () =>
+      globalStylesFromFlattened(flat)
+    );
+    state.canonicalByModule.set(moduleName, canonical);
+    state.globals.push(module);
+    invalidateSinks();
+  };
+
+  const cx = (...args: readonly ClassNameArg[]): string => {
+    const classes: string[] = [];
+    const walk = (arg: ClassNameArg): void => {
+      if (!arg) {
+        return;
+      }
+      if (typeof arg === 'string') {
+        classes.push(arg);
+        return;
+      }
+      if (typeof arg === 'number') {
+        classes.push(String(arg));
+        return;
+      }
+      if (Array.isArray(arg)) {
+        arg.forEach(walk);
+        return;
+      }
+      if (isBranded(state, arg)) {
+        classes.push(String(arg));
+        return;
+      }
+      if (isHandleLike(arg)) {
+        classes.push(arg.readableName);
+        return;
+      }
+      for (const [className, enabled] of Object.entries(arg)) {
+        if (enabled) {
+          classes.push(className);
+        }
+      }
+    };
+    args.forEach(walk);
+    return classes.join(' ');
+  };
+
+  return {
+    css,
+    cx,
+    injectGlobal,
+    stylesheet,
+    globalModules: () => [...state.globals],
+  };
+};
+
+const makeWrapper = (handle: StyleHandle): EmotionCss => {
+  const readable = handle.readableName;
+  const asString = (): string => readable;
+  // Spread copy keeps `resolveClassName` (closed over the original handle) and
+  // `key` intact so collector dedupe and compaction work unchanged.
+  const wrapper = { ...handle } as EmotionCss & {
+    toString: () => string;
+    [Symbol.toPrimitive]: () => string;
+  };
+  wrapper.toString = asString;
+  wrapper[Symbol.toPrimitive] = asString;
+  return wrapper;
+};
+
+const isBranded = (state: EmotionState, value: unknown): value is EmotionCss =>
+  Boolean(value && typeof value === 'object' && state.brand.has(value));
+
+const assertTemplate = (strings: unknown, fn: string): void => {
+  if (!Array.isArray(strings) || !('raw' in (strings as object))) {
+    throw new Error(
+      `${fn} is a template tag; object styles (${fn}({...})) are not supported.`
+    );
+  }
+};
+
+const detectCollision = (
+  state: EmotionState,
+  moduleName: string,
+  canonical: string
+): void => {
+  const prior = state.canonicalByModule.get(moduleName);
+  if (prior !== undefined && prior !== canonical) {
+    throw new Error(
+      `Content-hash collision for "${moduleName}"; two distinct templates hashed to the same name.`
+    );
+  }
+};
+
+// A cheap, exact collision tripwire independent of the (lossy) hash. NUL-joins
+// strings and String()s values — good enough because it is only ever compared
+// against another canonical string for the same module name.
+const canonicalKey = (
+  strings: readonly string[],
+  values: readonly unknown[]
+): string => {
+  const segments: string[] = [];
+  strings.forEach((part, index) => {
+    segments.push(part);
+    if (index < values.length) {
+      segments.push(String(values[index]));
+    }
+  });
+  return segments.join('\u0000');
+};