@elastic/distillate 0.0.0 → 0.1.0

package/src/local_vars.ts

@@ -0,0 +1,220 @@
+/*
+ * 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 { assertCssIdentSegment } from './idents';
+import { cssVarName } from './names';
+import type { ContextualVarPath, CssValue } from './styles/types';
+
+const RESERVED_DEFAULT_KEYS = new Set(['set', 'toString', 'valueOf', 'toJSON']);
+
+const isReservedKey = (key: string): boolean =>
+  RESERVED_DEFAULT_KEYS.has(key) || key.startsWith('__');
+
+/** Reference to a local CSS variable. Stringifies to `var(--...)`. */
+export interface LocalVarRef {
+  /** Brand distinguishing a local-var ref from other interpolations. */
+  readonly __kind: 'local-var-ref';
+  /** Canonical group/key path. */
+  readonly path: ContextualVarPath;
+  /** Actual emitted CSS custom property name. */
+  readonly propName: `--${string}`;
+  /** Usable CSS `var(...)` reference string. */
+  readonly ref: `var(--${string})`;
+  /** Stringifies to {@link LocalVarRef.ref}. */
+  toString(): string;
+  /** Template interpolation; same as {@link LocalVarRef.toString}. */
+  [Symbol.toPrimitive](hint: string): string;
+}
+
+/** Interpolation marker representing `.set(...)` overrides. */
+export interface LocalVarOverrideMarker {
+  /** Brand distinguishing a `.set(...)` override marker. */
+  readonly __kind: 'local-var-override-marker';
+  /** Unique ID for the group. */
+  readonly groupId: string;
+  /** Ordered list of variable overrides. */
+  readonly overrides: ReadonlyArray<{
+    /** Variable key within the group. */
+    readonly key: string;
+    /** Canonical group/key path. */
+    readonly path: ContextualVarPath;
+    /** Actual emitted CSS custom property name. */
+    readonly propName: `--${string}`;
+    /** Override value written at this interpolation site. */
+    readonly value: CssValue;
+  }>;
+}
+
+/** Interpolation marker representing `${group}` defaults. */
+export interface LocalVarDefaultMarker {
+  /** Brand distinguishing a `${group}` default marker. */
+  readonly __kind: 'local-var-default-marker';
+  /** Unique ID for the group. */
+  readonly groupId: string;
+  /** Group prefix path. */
+  readonly groupPath: `vars/${string}`;
+  /** Ordered list of variable defaults. */
+  readonly defaults: ReadonlyArray<{
+    /** Variable key within the group. */
+    readonly key: string;
+    /** Canonical group/key path. */
+    readonly path: ContextualVarPath;
+    /** Actual emitted CSS custom property name. */
+    readonly propName: `--${string}`;
+    /** Default value emitted when this key is reachable. */
+    readonly value: CssValue;
+  }>;
+}
+
+/** Interpolation marker: `${group}` defaults or `${group.set(...)}` overrides. */
+export type LocalVarMarker = LocalVarOverrideMarker | LocalVarDefaultMarker;
+
+/**
+ * Value returned by `t.vars(...)`. Interpolate `${group}`, `${group.key}`, or `${group.set({...})}`.
+ */
+export type LocalVarGroup<TKey extends string> = {
+  readonly [P in TKey]: LocalVarRef;
+} & {
+  /** Builds a marker that writes the given keys at the interpolation site. */
+  set(overrides: Partial<Record<TKey, CssValue>>): LocalVarOverrideMarker;
+};
+
+/** `true` when `value` is a {@link LocalVarRef}. */
+export const isLocalVarRef = (value: unknown): value is LocalVarRef =>
+  Boolean(
+    value &&
+    typeof value === 'object' &&
+    (value as { __kind?: string }).__kind === 'local-var-ref'
+  );
+
+/** `true` when `value` is a {@link LocalVarDefaultMarker}. */
+export const isLocalVarDefaultMarker = (
+  value: unknown
+): value is LocalVarDefaultMarker =>
+  Boolean(
+    value &&
+    typeof value === 'object' &&
+    (value as { __kind?: string }).__kind === 'local-var-default-marker'
+  );
+
+/** `true` when `value` is a {@link LocalVarOverrideMarker}. */
+export const isLocalVarOverrideMarker = (
+  value: unknown
+): value is LocalVarOverrideMarker =>
+  Boolean(
+    value &&
+    typeof value === 'object' &&
+    (value as { __kind?: string }).__kind === 'local-var-override-marker'
+  );
+
+/** `true` when `value` is a {@link LocalVarDefaultMarker} or {@link LocalVarOverrideMarker}. */
+export const isLocalVarMarker = (value: unknown): value is LocalVarMarker =>
+  isLocalVarDefaultMarker(value) || isLocalVarOverrideMarker(value);
+
+const cssVarPath = (
+  moduleName: string,
+  group: string,
+  key: string
+): ContextualVarPath => `vars/${moduleName}/${group}/${key}`;
+
+const buildLocalVarRef = (
+  path: ContextualVarPath,
+  propName: `--${string}`
+): LocalVarRef => {
+  const ref: `var(--${string})` = `var(${propName})`;
+  const refToString = (): string => ref;
+  return {
+    __kind: 'local-var-ref',
+    path,
+    propName,
+    ref,
+    toString: refToString,
+    [Symbol.toPrimitive]: refToString,
+  };
+};
+
+const reservedKeyError = (key: string): Error =>
+  new Error(
+    `t.vars(...) defaults key "${key}" is reserved. Reserved: ${[...RESERVED_DEFAULT_KEYS].join(', ')} plus any "__"-prefixed key.`
+  );
+
+export const createLocalVarGroup = <TKey extends string>(
+  prefix: string,
+  moduleName: string,
+  group: string,
+  defaults: Record<TKey, CssValue>
+): LocalVarGroup<TKey> => {
+  assertCssIdentSegment(group, 't.vars(...) group');
+  const groupId = `${moduleName}/${group}`;
+  const groupPath = `vars/${groupId}`;
+  const refs = new Map<TKey, LocalVarRef>();
+  const defaultsList: Array<{
+    readonly key: string;
+    readonly path: ContextualVarPath;
+    readonly propName: `--${string}`;
+    readonly value: CssValue;
+  }> = [];
+
+  for (const [key, value] of Object.entries(defaults) as Array<
+    [TKey, CssValue]
+  >) {
+    if (isReservedKey(key)) {
+      throw reservedKeyError(key);
+    }
+    assertCssIdentSegment(key, `t.vars("${group}") key`);
+    const path = cssVarPath(moduleName, group, key);
+    const propName = cssVarName(prefix, path);
+    refs.set(key, buildLocalVarRef(path, propName));
+    defaultsList.push({ key, path, propName, value });
+  }
+
+  const setOverrides = (
+    overrides: Partial<Record<TKey, CssValue>>
+  ): LocalVarOverrideMarker => {
+    const list: Array<LocalVarOverrideMarker['overrides'][number]> = [];
+    for (const [key, value] of Object.entries(overrides) as Array<
+      [TKey, CssValue | undefined]
+    >) {
+      if (value === undefined) {
+        continue;
+      }
+      const ref = refs.get(key);
+      if (!ref) {
+        throw new Error(
+          `t.vars("${group}").set: unknown key "${key}". Declared keys: ${defaultsList
+            .map((entry) => entry.key)
+            .join(', ')}.`
+        );
+      }
+      list.push({ key, path: ref.path, propName: ref.propName, value });
+    }
+    return {
+      __kind: 'local-var-override-marker',
+      groupId,
+      overrides: list,
+    };
+  };
+
+  const group_ = {
+    __kind: 'local-var-default-marker',
+    groupId,
+    groupPath,
+    defaults: defaultsList,
+    set: setOverrides,
+  } as unknown as LocalVarGroup<TKey>;
+
+  for (const [key, ref] of refs) {
+    Object.defineProperty(group_, key, {
+      value: ref,
+      enumerable: true,
+      writable: false,
+      configurable: false,
+    });
+  }
+
+  return group_;
+};

package/src/minify.ts

@@ -0,0 +1,87 @@
+/*
+ * 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 CssSpan, scanCss } from './css_scan';
+
+/**
+ * A space between two non-structural spans is significant wherever it sits: a
+ * descendant combinator in a selector (`.a .b`), a token separator in a value
+ * (`margin:0 auto`). Beside a structural character it is noise, except before
+ * a pseudo-class colon in a rules block — `.menu :hover` is not `.menu:hover`,
+ * while `color : red` is `color:red`.
+ */
+const spaceIsSignificant = (
+  before: CssSpan | undefined,
+  after: CssSpan | undefined
+): boolean => {
+  if (!before || !after) {
+    return false;
+  }
+  if (before.kind === 'structural') {
+    return false;
+  }
+  if (after.kind === 'structural') {
+    // Only a pseudo-class colon in a selector keeps the space in front of it.
+    // Space before `{`, `}`, `;`, `,`, or `>` is never significant.
+    return after.text === ':' && after.block === 'rules';
+  }
+  return true;
+};
+
+/**
+ * Strips comments and insignificant whitespace from CSS.
+ *
+ * Strings, unquoted `url(…)` tokens, and backslash escapes pass through
+ * untouched: their contents are literal, so a `/*` or a `;` inside one is data
+ * rather than syntax.
+ *
+ * @param value Raw CSS text.
+ */
+export const minifyCss = (value: string): string => {
+  // Dropping comments can leave two whitespace spans adjacent — `.a /*c*/ .b`
+  // — and emitting one space per span would keep both. Coalescing after the
+  // filter makes the run a single decision.
+  const spans = scanCss(value)
+    .filter((span) => span.kind !== 'comment')
+    .filter(
+      (span, index, all) =>
+        span.kind !== 'whitespace' || all[index - 1]?.kind !== 'whitespace'
+    );
+  const out: string[] = [];
+  // Indices into `spans` of what has been emitted, so lookaround skips the
+  // whitespace being decided about.
+  const significant = spans.filter((span) => span.kind !== 'whitespace');
+  let significantIndex = 0;
+
+  spans.forEach((span) => {
+    if (span.kind === 'whitespace') {
+      const before = significant[significantIndex - 1];
+      const after = significant[significantIndex];
+      if (spaceIsSignificant(before, after)) {
+        out.push(' ');
+      }
+      return;
+    }
+
+    // A declaration's terminator is redundant against the block's own close.
+    // Only a bare `;` qualifies: an escaped one is part of a value, and it
+    // arrives as an `escape` span rather than a structural `;`.
+    if (
+      span.kind === 'structural' &&
+      span.text === '}' &&
+      significant[significantIndex - 1]?.kind === 'structural' &&
+      significant[significantIndex - 1]?.text === ';'
+    ) {
+      out.pop();
+    }
+
+    out.push(span.text);
+    significantIndex += 1;
+  });
+
+  return out.join('').trim();
+};

package/src/names.ts

@@ -0,0 +1,129 @@
+/*
+ * 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.
+ */
+
+/** Naming scheme: `compact` assigns sequential identifiers by sorted key index, `readable` emits descriptive ones. */
+export type StyleNameMode = 'compact' | 'readable';
+/** Destination format for the CSS collection. */
+export type StyleTarget = 'artifact' | 'stylesheet';
+
+/** Context for resolving keys into final class or custom-property names. */
+export interface StyleNameResolver {
+  /** The naming mode used by this resolver. */
+  readonly names: StyleNameMode;
+  /** Resolves a handle key into a CSS class name. */
+  className(key: string, readableName?: string): string;
+  /** Resolves a variable key into a custom property name. */
+  cssVar(key: string): `--${string}`;
+  /** Resolves a variable key into a `var(...)` reference. */
+  cssVarRef(key: string): `var(--${string})`;
+}
+
+/** Inputs for {@link createStyleNameResolver}. */
+export interface StyleNameResolverOptions {
+  /** Naming strategy (`compact` or `readable`). */
+  names: StyleNameMode;
+  /** Brand prefix for readable names (`<prefix>-<key>` / `--<prefix>-<key>`), e.g. `'aui'`. */
+  prefix: string;
+  /** Keys defining the compact class-name domain. */
+  classKeys?: Iterable<string>;
+  /** Keys defining the compact custom-property domain. */
+  cssVarKeys?: Iterable<string>;
+}
+
+const compactAlphabet = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+export const compactNameForIndex = (index: number): string => {
+  if (!Number.isInteger(index) || index < 0) {
+    throw new Error(`Compact name index must be a non-negative integer.`);
+  }
+
+  const base = compactAlphabet.length;
+  let remaining = index;
+  let length = 1;
+
+  while (remaining >= base ** length) {
+    remaining -= base ** length;
+    length += 1;
+  }
+
+  let name = '';
+  for (let position = length - 1; position >= 0; position -= 1) {
+    const divisor = base ** position;
+    const digit = Math.floor(remaining / divisor);
+    name += compactAlphabet[digit] ?? '';
+    remaining %= divisor;
+  }
+
+  return name;
+};
+
+/** Compact names are assigned from sorted keys so emission is deterministic. */
+export const createCompactNameMap = (
+  keys: Iterable<string>
+): ReadonlyMap<string, string> => {
+  const uniqueKeys = [...new Set(keys)].sort();
+  return new Map(
+    uniqueKeys.map((key, index) => [key, compactNameForIndex(index)])
+  );
+};
+
+const readableClassName = (
+  prefix: string,
+  key: string,
+  fallback?: string
+): string => fallback ?? `${prefix}-${key.replaceAll('/', '-')}`;
+
+/**
+ * Readable custom-property name: `--${prefix}-${path}` with `/` joined on `-` and a leading `vars/` stripped.
+ *
+ * @param prefix Brand prefix (e.g. `'eui'`).
+ * @param path Theme or contextual-var path (e.g. `'colors/ink'`, `'vars/chip/look/bg'`).
+ */
+export const cssVarName = (prefix: string, path: string): `--${string}` =>
+  `--${prefix}-${path.replace(/^vars\//, '').replaceAll('/', '-')}`;
+
+const compactLookup = (
+  map: ReadonlyMap<string, string>,
+  key: string,
+  kind: 'class' | 'CSS variable'
+): string => {
+  const name = map.get(key);
+  if (!name) {
+    throw new Error(`No compact ${kind} name registered for "${key}".`);
+  }
+  return name;
+};
+
+/** Maps semantic keys to readable (`<prefix>-<key>`) or compact (`a`, `b`, …) names. */
+export const createStyleNameResolver = ({
+  names,
+  prefix,
+  classKeys = [],
+  cssVarKeys = [],
+}: StyleNameResolverOptions): StyleNameResolver => {
+  const classMap = createCompactNameMap(classKeys);
+  const cssVarMap = createCompactNameMap(cssVarKeys);
+
+  const cssVar = (key: string): `--${string}` => {
+    if (names === 'readable') {
+      return cssVarName(prefix, key);
+    }
+    return `--${compactLookup(cssVarMap, key, 'CSS variable')}`;
+  };
+
+  return {
+    names,
+    className: (key, fallback) => {
+      if (names === 'readable') {
+        return readableClassName(prefix, key, fallback);
+      }
+      return compactLookup(classMap, key, 'class');
+    },
+    cssVar,
+    cssVarRef: (key) => `var(${cssVar(key)})`,
+  };
+};