@elastic/distillate 0.0.0 → 0.1.0

package/docs/playground/src/lib/compile.ts

@@ -0,0 +1,242 @@
+/*
+ * 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 {
+  container,
+  media,
+  rule,
+  type StyleHandle,
+  type StylesCollector,
+  variants,
+} from '@elastic/distillate';
+import { type ClassNameArg, createEmotion } from '@elastic/distillate/emotion';
+import { transform } from 'sucrase';
+
+import {
+  createDemoDistillery,
+  type DemoTokens,
+  demoTokens,
+} from './demo_environment';
+
+export type PlaygroundMode = 'emotion' | 'native';
+
+export type CompileStage = 'transform' | 'evaluate' | 'render';
+
+export interface CompileError {
+  readonly stage: CompileStage;
+  readonly message: string;
+}
+
+export interface CompileSuccess {
+  readonly ok: true;
+  readonly previewHtml: string;
+  readonly readableCss: string;
+  readonly compactCss: string;
+  readonly artifactCss: string;
+  readonly stylesheetBytes: number;
+  readonly artifactBytes: number;
+}
+
+export interface CompileFailure {
+  readonly ok: false;
+  readonly error: CompileError;
+}
+
+export type PlaygroundResult = CompileSuccess | CompileFailure;
+
+type Distillery = ReturnType<typeof createDemoDistillery>;
+
+const utf8Bytes = (css: string): number =>
+  new TextEncoder().encode(css).byteLength;
+
+const stripImports = (source: string): string =>
+  source.replace(/^\s*import\b.*(?:\n|$)/gm, '');
+
+const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const isStyleHandle = (value: unknown): value is StyleHandle =>
+  Boolean(
+    value &&
+    typeof value === 'object' &&
+    (value as { kind?: string }).kind === 'handle'
+  );
+
+const collectStyleHandles = (
+  collector: StylesCollector,
+  values: readonly unknown[]
+): void => {
+  const handles: StyleHandle[] = [];
+  const walk = (value: unknown): void => {
+    if (Array.isArray(value)) {
+      value.forEach(walk);
+      return;
+    }
+    if (isStyleHandle(value)) {
+      handles.push(value);
+    }
+  };
+  for (const value of values) {
+    walk(value);
+  }
+  if (handles.length > 0) {
+    collector.useHandles(handles);
+  }
+};
+
+const readableClassName = (...args: readonly unknown[]): string =>
+  args
+    .filter((arg): arg is NonNullable<typeof arg> => Boolean(arg))
+    .map((arg) => {
+      if (typeof arg === 'string') {
+        return arg;
+      }
+      if (typeof arg === 'number') {
+        return String(arg);
+      }
+      const readable = (arg as Partial<StyleHandle>).readableName;
+      return typeof readable === 'string' ? readable : '';
+    })
+    .filter(Boolean)
+    .join(' ');
+
+const cnFor =
+  (collector: StylesCollector) =>
+  (...args: readonly unknown[]): string => {
+    collectStyleHandles(collector, args);
+    return readableClassName(...args);
+  };
+
+const bindEmotionCollection = (
+  distillery: Distillery,
+  collector: StylesCollector
+): Record<string, unknown> => {
+  const emotion = createEmotion<DemoTokens>(distillery);
+  const css = (
+    strings: TemplateStringsArray,
+    ...values: readonly unknown[]
+  ): ReturnType<typeof emotion.css> => {
+    const handle = emotion.css(strings, ...values);
+    const asString = (): string => {
+      collector.useHandles([handle]);
+      return handle.readableName;
+    };
+    handle.toString = asString;
+    handle[Symbol.toPrimitive] = asString;
+    return handle;
+  };
+  const cx = (...args: readonly ClassNameArg[]): string => {
+    collectStyleHandles(collector, args);
+    return emotion.cx(...args);
+  };
+  return {
+    css,
+    cx,
+    injectGlobal: (
+      strings: TemplateStringsArray,
+      ...values: readonly unknown[]
+    ): void => emotion.injectGlobal(strings, ...values),
+  };
+};
+
+const buildScope = (
+  mode: PlaygroundMode,
+  distillery: Distillery,
+  collector: StylesCollector
+): Record<string, unknown> => {
+  const shared: Record<string, unknown> = {
+    cn: cnFor(collector),
+    tokens: demoTokens,
+  };
+  if (mode === 'emotion') {
+    return { ...shared, ...bindEmotionCollection(distillery, collector) };
+  }
+  const { createStyleModule, primitiveStyles } = distillery;
+  return {
+    ...shared,
+    createStyleModule,
+    primitiveStyles,
+    rule,
+    media,
+    container,
+    variants,
+  };
+};
+
+const evaluate = (
+  transformed: string,
+  scope: Record<string, unknown>
+): unknown => {
+  // Playground compiler: eval is the point.
+  // eslint-disable-next-line @typescript-eslint/no-implied-eval
+  const factory = new Function(
+    'scope',
+    `with (scope) {\n${transformed}\n}`
+  ) as (scope: Record<string, unknown>) => unknown;
+  return factory(scope);
+};
+
+export const compilePlayground = (
+  source: string,
+  mode: PlaygroundMode
+): PlaygroundResult => {
+  const normalized = stripImports(source);
+
+  let transformed: string;
+  try {
+    transformed = transform(normalized, {
+      transforms: ['typescript'],
+      production: true,
+    }).code;
+  } catch (error) {
+    return {
+      ok: false,
+      error: { stage: 'transform', message: messageOf(error) },
+    };
+  }
+
+  const distillery = createDemoDistillery();
+  const artifactCollector = distillery.artifactCollector('compact');
+  let returned: unknown;
+  try {
+    returned = evaluate(
+      transformed,
+      buildScope(mode, distillery, artifactCollector)
+    );
+  } catch (error) {
+    return {
+      ok: false,
+      error: { stage: 'evaluate', message: messageOf(error) },
+    };
+  }
+
+  try {
+    const previewHtml = typeof returned === 'string' ? returned : '';
+    const readableCss = distillery.renderStyles(
+      distillery.stylesheetCollector('readable')
+    );
+    const compactCss = distillery.renderStyles(
+      distillery.stylesheetCollector('compact')
+    );
+    const artifactResolver = artifactCollector.createResolver();
+    const artifactCss = distillery.renderStyles(
+      artifactCollector,
+      artifactResolver
+    );
+    return {
+      ok: true,
+      previewHtml,
+      readableCss,
+      compactCss,
+      artifactCss,
+      stylesheetBytes: utf8Bytes(readableCss),
+      artifactBytes: utf8Bytes(artifactCss),
+    };
+  } catch (error) {
+    return { ok: false, error: { stage: 'render', message: messageOf(error) } };
+  }
+};

package/docs/playground/src/lib/demo_environment.test.ts

@@ -0,0 +1,123 @@
+/*
+ * 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 { describe, expect, it } from 'vitest';
+
+import {
+  createDemoDistillery,
+  demoTokenCatalog,
+  demoTokens,
+} from './demo_environment';
+
+describe('demoTokenCatalog', () => {
+  it('lists every playground token with its resolved values', () => {
+    const byAccess = new Map(
+      demoTokenCatalog.map((entry) => [entry.access, entry])
+    );
+    expect(byAccess.size).toBe(demoTokenCatalog.length);
+
+    const accent = byAccess.get('tokens.color.accent');
+    expect(accent).toMatchObject({
+      kind: 'theme',
+      cssVar: demoTokens.color.accent.cssVar,
+      light: '#BC1E70',
+      dark: '#EE72A6',
+    });
+    expect(byAccess.get('tokens.color.primary')).toMatchObject({
+      kind: 'theme',
+      light: '#0B64DD',
+      dark: '#61A2FF',
+    });
+    expect(byAccess.get('tokens.color.accentSecondary')).toMatchObject({
+      kind: 'theme',
+      light: '#008B87',
+      dark: '#16C5C0',
+    });
+    expect(byAccess.get('tokens.color.success')).toMatchObject({
+      kind: 'theme',
+      light: '#008A5E',
+      dark: '#24C292',
+    });
+    expect(byAccess.get('tokens.color.warning')).toMatchObject({
+      kind: 'theme',
+      light: '#FACB3D',
+      dark: '#FACB3D',
+    });
+    expect(byAccess.get('tokens.color.danger')).toMatchObject({
+      kind: 'theme',
+      light: '#C61E25',
+      dark: '#F6726A',
+    });
+
+    const space = byAccess.get('tokens.space.s');
+    expect(space).toMatchObject({
+      kind: 'scale',
+      value: demoTokens.space.s.value,
+      cq: demoTokens.space.s.cq,
+    });
+
+    expect(demoTokenCatalog.map((entry) => entry.access)).toEqual([
+      ...Object.keys(demoTokens.color).map((key) => `tokens.color.${key}`),
+      ...Object.keys(demoTokens.space).map((key) => `tokens.space.${key}`),
+      ...Object.keys(demoTokens.radius).map((key) => `tokens.radius.${key}`),
+      ...Object.keys(demoTokens.font).map((key) => `tokens.font.${key}`),
+    ]);
+  });
+});
+
+describe('demo theme variations', () => {
+  const renderDemo = (options?: {
+    flatten?: string;
+    alternates?: readonly { variation: string; selector?: string }[];
+  }): string => {
+    const distillery = createDemoDistillery();
+    distillery.createStyleModule('swatch', (t) => ({
+      root: t.css`
+        color: ${t.tokens.color.accent};
+        background: ${t.tokens.color.surface};
+      `,
+    }));
+    return distillery.renderStyles(
+      distillery.stylesheetCollector(),
+      undefined,
+      options
+    );
+  };
+
+  it('keeps base-only output free of declared variations', () => {
+    const css = renderDemo();
+    expect(css).toContain('--dstl-color-accent:light-dark(#BC1E70,#EE72A6)');
+    expect(css).not.toContain('#0077cc');
+    expect(css).not.toContain('prefers-contrast');
+  });
+
+  it('flattens muted into :host', () => {
+    const css = renderDemo({ flatten: 'muted' });
+    expect(css).toContain(':host{');
+    expect(css).toContain('--dstl-color-accent:#0077cc');
+    expect(css).not.toContain('data-eui-theme');
+  });
+
+  it('emits muted as a :host() alternate', () => {
+    const css = renderDemo({
+      alternates: [
+        { variation: 'muted', selector: '[data-eui-theme="muted"]' },
+      ],
+    });
+    expect(css).toContain(
+      ':host([data-eui-theme="muted"]){--dstl-color-accent:#0077cc}'
+    );
+  });
+
+  it('wraps highContrast in its media query under :host', () => {
+    const css = renderDemo({ flatten: 'highContrast' });
+    expect(css).toContain(
+      '@media (prefers-contrast:more){:host{--dstl-color-surface:light-dark(#fff,#000)}}'
+    );
+    expect(css).not.toContain('--dstl-color-text:light-dark(#000,#fff)');
+  });
+});

package/docs/playground/src/lib/demo_environment.ts

@@ -0,0 +1,140 @@
+/*
+ * 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 {
+  cq,
+  createDistillery,
+  type Distillery,
+  type DistilleryEnvironment,
+  isCssToken,
+  isScaleToken,
+  lightDark,
+  type TokensOf,
+} from '@elastic/distillate';
+
+const sansStack = 'system-ui, -apple-system, "Segoe UI", sans-serif';
+const monoStack = 'ui-monospace, SFMono-Regular, Menlo, Monaco, monospace';
+
+const demoTheme = {
+  color: {
+    text: lightDark('#1B1E28', '#E6E8F0'),
+    surface: lightDark('#FFFFFF', '#141A27'),
+    subtle: lightDark('#5A6472', '#9AA4B6'),
+    border: lightDark('#DCE2EA', '#2B3242'),
+    primary: lightDark('#0B64DD', '#61A2FF'),
+    accent: lightDark('#BC1E70', '#EE72A6'),
+    accentSecondary: lightDark('#008B87', '#16C5C0'),
+    success: lightDark('#008A5E', '#24C292'),
+    warning: '#FACB3D',
+    danger: lightDark('#C61E25', '#F6726A'),
+  },
+  space: {
+    xs: cq('4px', '1cqi'),
+    s: cq('8px', '2cqi'),
+    m: cq('16px', '4cqi'),
+    l: cq('24px', '6cqi'),
+  },
+  radius: {
+    s: cq('6px', '6px'),
+    m: cq('12px', '12px'),
+  },
+  font: {
+    sans: sansStack,
+    mono: monoStack,
+  },
+};
+
+export type DemoTokens = TokensOf<typeof demoTheme>;
+
+const demoBind = {
+  prefix: 'dstl',
+  themeScope: ':host',
+  theme: demoTheme,
+  dev: true,
+  variations: {
+    muted: {
+      color: {
+        accent: '#0077cc',
+      },
+    },
+    highContrast: {
+      media: '(prefers-contrast: more)',
+      variation: {
+        color: {
+          text: lightDark('#000', '#fff'),
+          surface: lightDark('#fff', '#000'),
+        },
+      },
+    },
+  },
+};
+
+const catalogDistillery = createDistillery(demoBind);
+
+export const demoTokens: DemoTokens = catalogDistillery.tokens;
+export const demoEnvironment: DistilleryEnvironment<DemoTokens> =
+  catalogDistillery.environment;
+
+export const createDemoDistillery = (): Distillery<DemoTokens> =>
+  createDistillery(demoBind);
+
+/** A single entry in the token catalog table. */
+export type DemoTokenCatalogEntry =
+  | {
+      readonly kind: 'theme';
+      readonly access: string;
+      readonly cssVar: string;
+      readonly light: string;
+      readonly dark: string;
+    }
+  | {
+      readonly kind: 'scale';
+      readonly access: string;
+      readonly value: string;
+      readonly cq: string;
+    };
+
+const catalogFromTokens = (
+  tokens: object,
+  prefix = 'tokens'
+): DemoTokenCatalogEntry[] => {
+  const out: DemoTokenCatalogEntry[] = [];
+  const walk = (node: object, access: string): void => {
+    for (const [key, child] of Object.entries(
+      node as Record<string, unknown>
+    )) {
+      const next = `${access}.${key}`;
+      if (isCssToken(child)) {
+        const def = demoEnvironment.themeVars[child.path];
+        out.push({
+          kind: 'theme',
+          access: next,
+          cssVar: child.cssVar,
+          light: def?.light ?? '',
+          dark: def?.dark ?? '',
+        });
+      } else if (isScaleToken(child)) {
+        out.push({
+          kind: 'scale',
+          access: next,
+          value: child.value,
+          cq: child.cq,
+        });
+      } else if (child && typeof child === 'object') {
+        walk(child, next);
+      } else {
+        throw new Error(`Unknown token type at ${next}`);
+      }
+    }
+  };
+  walk(tokens, prefix);
+  return out;
+};
+
+/** Flat catalog of all demo tokens, in group/key insertion order. */
+export const demoTokenCatalog: readonly DemoTokenCatalogEntry[] =
+  catalogFromTokens(demoTokens);

package/docs/playground/src/lib/editor_lib.test.ts

@@ -0,0 +1,39 @@
+/*
+ * 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 { describe, expect, it } from 'vitest';
+
+import { extraLibSource, playgroundScopeNames } from './editor_lib';
+
+const isDeclared = (source: string, name: string): boolean =>
+  source.includes(`declare function ${name}`) ||
+  source.includes(`declare const ${name}`);
+
+describe('extraLibSource', () => {
+  it('declares every emotion eval binding and omits native-only names', () => {
+    const source = extraLibSource('emotion');
+    for (const name of playgroundScopeNames('emotion')) {
+      expect(isDeclared(source, name), name).toBe(true);
+    }
+    expect(source).toContain('readonly primary');
+    expect(source).toContain('readonly accent');
+    expect(source).toContain('readonly accentSecondary');
+    expect(source).toContain('readonly success');
+    expect(source).toContain('readonly warning');
+    expect(source).toContain('readonly danger');
+    expect(source).not.toContain('createStyleModule');
+  });
+
+  it('declares every native eval binding and omits emotion-only names', () => {
+    const source = extraLibSource('native');
+    for (const name of playgroundScopeNames('native')) {
+      expect(isDeclared(source, name), name).toBe(true);
+    }
+    expect(source).toContain('LocalVarGroup');
+    expect(source).not.toContain('injectGlobal');
+  });
+});

package/docs/playground/src/lib/editor_lib.ts

@@ -0,0 +1,142 @@
+/*
+ * 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 { tokenTreeDts } from '@elastic/distillate/testing';
+
+import type { PlaygroundMode } from './compile';
+import { demoTokens } from './demo_environment';
+
+/** Virtual path for the playground ambient extraLib. */
+export const PLAYGROUND_EXTRA_LIB_PATH = 'file:///playground-globals.d.ts';
+
+const demoTokensInterface = tokenTreeDts('DemoTokens', demoTokens);
+
+const sharedTypes = `
+interface CssInterpolable {
+  readonly [Symbol.toPrimitive]: (hint: string) => string;
+  toString(): string;
+}
+
+type CssValue = CssInterpolable | string | number;
+
+${demoTokensInterface}
+
+interface StyleHandle extends CssInterpolable {
+  readonly readableName: string;
+  readonly localName: string;
+  readonly key: string;
+}
+
+type LocalVarGroup<K extends string> = { readonly [P in K]: CssInterpolable } & {
+  set(overrides: Partial<Record<K, CssValue>>): CssInterpolable;
+};
+
+interface StyleAuthoringApi {
+  css(strings: TemplateStringsArray, ...values: unknown[]): StyleHandle;
+  decls(strings: TemplateStringsArray, ...values: unknown[]): unknown;
+  vars<K extends string>(
+    group: string,
+    defaults: Record<K, CssValue>
+  ): LocalVarGroup<K>;
+  readonly tokens: DemoTokens;
+}
+
+interface PrimitiveStyleAuthoringApi {
+  style(strings: TemplateStringsArray, ...values: unknown[]): StyleHandle;
+  readonly tokens: DemoTokens;
+}
+
+interface StylesModule<T> {
+  readonly name: string;
+  readonly handles: T;
+}
+
+/** Demo theme and scale tokens. Interpolate into \`css\` templates. */
+declare const tokens: DemoTokens;
+
+/** Joins class names and handle \`readableName\`s. Collects handles for the artifact. */
+declare function cn(
+  ...args: Array<StyleHandle | string | number | false | null | undefined>
+): string;
+`;
+
+const emotionGlobals = `
+/** Emotion-compat tagged template. Nested \`&\` and \`@media\` flatten. */
+declare function css(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): StyleHandle;
+
+/** Joins class names, handles, arrays, and truthy maps. */
+declare function cx(
+  ...args: Array<
+    | StyleHandle
+    | string
+    | number
+    | false
+    | null
+    | undefined
+    | ReadonlyArray<unknown>
+    | { readonly [className: string]: boolean }
+  >
+): string;
+
+/** Registers global rules (\`body\`, \`html\`, …). */
+declare function injectGlobal(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): void;
+`;
+
+const nativeGlobals = `
+/** Named module. Destructure \`css\` / \`vars\` / \`tokens\` from the factory argument. */
+declare function createStyleModule<T extends Record<string, unknown>>(
+  name: string,
+  factory: (api: StyleAuthoringApi) => T
+): StylesModule<T>;
+
+/** Named handles plus tokens only. */
+declare function primitiveStyles<T extends Record<string, unknown>>(
+  name: string,
+  factory: (api: PrimitiveStyleAuthoringApi) => T
+): StylesModule<T>;
+
+declare function rule(
+  selector: (h: (handle: StyleHandle) => string) => string,
+  declarations: unknown
+): unknown;
+
+declare function media(query: string, rules: readonly unknown[]): unknown;
+
+declare function container(query: string, rules: readonly unknown[]): unknown;
+
+declare function variants<K extends string, V>(
+  domain: readonly K[],
+  factory: (value: K) => V
+): Record<K, V>;
+`;
+
+/** Ambient `.d.ts` matching the playground eval scope for `mode`. */
+export const extraLibSource = (mode: PlaygroundMode): string =>
+  `${sharedTypes}${mode === 'emotion' ? emotionGlobals : nativeGlobals}`;
+
+/** Binding names injected at eval time for `mode`. */
+export const playgroundScopeNames = (
+  mode: PlaygroundMode
+): readonly string[] =>
+  mode === 'emotion'
+    ? ['tokens', 'cn', 'css', 'cx', 'injectGlobal']
+    : [
+        'tokens',
+        'cn',
+        'createStyleModule',
+        'primitiveStyles',
+        'rule',
+        'media',
+        'container',
+        'variants',
+      ];