@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/LiquidEditor/liquidTokenizer.ts

@@ -0,0 +1,235 @@
+// liquidTokenizer.ts — pure, dependency-free Liquid tokenizer.
+//
+// Emits CONTIGUOUS tokens: tokens.map(t => t.value).join('') === source. The
+// highlight overlay relies on this so its <pre> text matches the <textarea>
+// character-for-character. Classification is presentational, not a parser —
+// it never throws on malformed input.
+
+export type LiquidTokenType =
+  | 'text' // plain text outside {{ }} / {% %}, and neutral punctuation/space inside
+  | 'delimiter' // {{  }}  {%  %}
+  | 'variable' // a known (or unvalidated) identifier in value position
+  | 'unknown' // an identifier in value position not present in knownCodes
+  | 'filter' // an identifier immediately after `|`
+  | 'string' // "…" or '…'
+  | 'number' // 42, 3.14
+  | 'keyword' // if, for, in, and, or, …
+  | 'operator'; // | == != <= >= < > = . : , ( )
+
+export interface LiquidToken {
+  type: LiquidTokenType;
+  value: string;
+  /** Start index in the source string (inclusive). */
+  start: number;
+  /** End index in the source string (exclusive). */
+  end: number;
+}
+
+const KEYWORDS = new Set([
+  'if',
+  'elsif',
+  'else',
+  'endif',
+  'unless',
+  'endunless',
+  'case',
+  'when',
+  'endcase',
+  'for',
+  'endfor',
+  'in',
+  'break',
+  'continue',
+  'and',
+  'or',
+  'not',
+  'contains',
+  'assign',
+  'capture',
+  'endcapture',
+  'true',
+  'false',
+  'nil',
+  'empty',
+  'null',
+]);
+
+const IDENT_START = /[A-Za-z_]/;
+const IDENT_CHAR = /[A-Za-z0-9_]/;
+const DIGIT = /[0-9]/;
+
+/**
+ * Tokenize a Liquid template string for highlighting + unknown-variable
+ * detection.
+ *
+ * @param source The raw template string.
+ * @param knownCodes When provided and non-empty, a root identifier in value
+ *   position that is not in the set is typed `unknown`. Codes may be dotted
+ *   paths (e.g., "event.type"); the root identifier (first segment before the
+ *   first dot) is derived for membership testing. Omit (or pass an empty set)
+ *   to never flag — the caller cannot assert validity.
+ */
+export function tokenize(source: string, knownCodes?: ReadonlySet<string>): LiquidToken[] {
+  const tokens: LiquidToken[] = [];
+  const n = source.length;
+  let i = 0;
+  const hasKnown = knownCodes !== undefined && knownCodes.size > 0;
+  // #304: `code` is a PATH — "event.type" makes the ROOT `event` known. A
+  // reference is checked by its root identifier only, so membership is
+  // tested against the set of first dotted segments.
+  const knownRoots = hasKnown ? new Set([...knownCodes!].map((c) => c.split('.')[0])) : undefined;
+  // #304/#310: `{% for item in … %}` and `{% assign total = … %}` declare a
+  // name — collect declared names as the pass encounters them so later
+  // references (in tags and {{ }} bodies) aren't flagged unknown. Single
+  // forward pass: a use BEFORE its declaration stays flagged — acceptable
+  // ceiling, generated snippets always declare first. Names are not scoped
+  // to their loop/tag (lenient false negatives on out-of-scope use).
+  const declaredVars = new Set<string>();
+
+  const push = (type: LiquidTokenType, start: number, end: number) => {
+    if (end > start) tokens.push({ type, value: source.slice(start, end), start, end });
+  };
+
+  while (i < n) {
+    const isOpen = source[i] === '{' && (source[i + 1] === '{' || source[i + 1] === '%');
+    if (!isOpen) {
+      // Accumulate plain text up to the next tag open or EOF.
+      const start = i;
+      while (i < n && !(source[i] === '{' && (source[i + 1] === '{' || source[i + 1] === '%'))) {
+        i += 1;
+      }
+      push('text', start, i);
+      continue;
+    }
+
+    // Tag: emit the opening delimiter, then the interior, then the close.
+    const isOutput = source[i + 1] === '{';
+    const close = isOutput ? '}}' : '%}';
+    push('delimiter', i, i + 2);
+    i += 2;
+
+    const interiorEnd = (() => {
+      const idx = source.indexOf(close, i);
+      return idx === -1 ? n : idx;
+    })();
+
+    // `expectFilter` is set right after a `|` so the next identifier is a filter.
+    // `seenValue` tracks whether we've already consumed the leading value
+    // identifier in this tag (so only the ROOT identifier is unknown-checked).
+    let expectFilter = false;
+    let seenValue = false;
+    // Set right after the `for` / `assign` keyword in a `{% %}` tag — the
+    // next identifier is the declared name. Any other intervening keyword
+    // cancels the capture so a keyword-named declaration ({% for case in x %})
+    // can't mis-record the following identifier.
+    let expectDeclaration = false;
+    // For `{% if … %}` the first identifier is the tag-name keyword.
+
+    while (i < interiorEnd) {
+      const c = source[i];
+
+      if (c === ' ' || c === '\t' || c === '\n' || c === '\r') {
+        const start = i;
+        while (i < interiorEnd && /\s/.test(source[i])) i += 1;
+        push('text', start, i);
+        continue;
+      }
+
+      if (c === '"' || c === "'") {
+        const start = i;
+        i += 1;
+        while (i < interiorEnd && source[i] !== c) i += 1;
+        if (i < interiorEnd) i += 1; // closing quote
+        push('string', start, i);
+        continue;
+      }
+
+      if (DIGIT.test(c)) {
+        const start = i;
+        while (i < interiorEnd && (DIGIT.test(source[i]) || source[i] === '.')) i += 1;
+        push('number', start, i);
+        continue;
+      }
+
+      if (IDENT_START.test(c)) {
+        const start = i;
+        i += 1;
+        while (i < interiorEnd && IDENT_CHAR.test(source[i])) i += 1;
+        const word = source.slice(start, i);
+        const isDottedProperty = start > 0 && source[start - 1] === '.';
+
+        if (expectFilter) {
+          push('filter', start, i);
+          expectFilter = false;
+        } else if (KEYWORDS.has(word)) {
+          push('keyword', start, i);
+          expectDeclaration = !isOutput && (word === 'for' || word === 'assign');
+        } else if (isDottedProperty) {
+          push('variable', start, i); // neutral property access; not unknown-checked
+        } else {
+          if (expectDeclaration) declaredVars.add(word);
+          const unknown =
+            hasKnown &&
+            !seenValue &&
+            !expectDeclaration &&
+            !knownRoots!.has(word) &&
+            !declaredVars.has(word);
+          // Only the leading value identifier is the "root"; subsequent ones
+          // (rare) are treated as variables but not unknown-checked.
+          push(unknown ? 'unknown' : 'variable', start, i);
+          seenValue = true;
+          expectDeclaration = false;
+        }
+        continue;
+      }
+
+      if (c === '|') {
+        push('operator', i, i + 1);
+        expectFilter = true;
+        i += 1;
+        continue;
+      }
+
+      // Multi-char operators (==, !=, <=, >=) then single punctuation.
+      const two = source.slice(i, i + 2);
+      if (['==', '!=', '<=', '>='].includes(two)) {
+        push('operator', i, i + 2);
+        i += 2;
+        continue;
+      }
+      if ('<>=.,:()'.includes(c)) {
+        push('operator', i, i + 1);
+        i += 1;
+        continue;
+      }
+
+      // Anything else (neutral) — emit as text so the stream stays contiguous.
+      push('text', i, i + 1);
+      i += 1;
+    }
+
+    // Closing delimiter (if present).
+    if (interiorEnd < n) {
+      push('delimiter', interiorEnd, interiorEnd + 2);
+      i = interiorEnd + 2;
+    } else {
+      i = n;
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * The root variable codes referenced in `{{ }}` / `{% %}` that are NOT in
+ * `knownCodes` — i.e. the names the editor flags. Empty when `knownCodes` is
+ * omitted/empty. Drives the footer "unknown variable" warning.
+ */
+export function unknownVariables(source: string, knownCodes: ReadonlySet<string>): string[] {
+  if (knownCodes.size === 0) return [];
+  const seen = new Set<string>();
+  for (const t of tokenize(source, knownCodes)) {
+    if (t.type === 'unknown') seen.add(t.value);
+  }
+  return [...seen];
+}

package/src/components/LiquidEditor/types.ts

@@ -0,0 +1,101 @@
+import type { ReactNode } from 'react';
+
+/** A variable the editor knows about — drives the insert menu, autocomplete, and unknown flagging. */
+export interface LiquidVariable {
+  /** Token inserted and matched, e.g. `"first_name"` → referenced as `{{ first_name }}`. */
+  code: string;
+  /**
+   * Human label shown in the picker + autocomplete. Defaults to `code`.
+   *
+   * An EMPTY string counts as unset: the label is a menu item's only name
+   * source, and `code` is here precisely so every item has something readable.
+   */
+  label?: string;
+  /** Optional type hint rendered as a muted tag in suggestions, e.g. `"text"` | `"date"`. */
+  type?: string;
+  /** Optional group header that sections the picker + autocomplete. */
+  group?: string;
+  /**
+   * Optional human description. Surfaces as a second muted line in the insert
+   * menu and autocomplete suggestions, and in the footer when the caret sits
+   * on this variable's reference.
+   */
+  description?: string;
+  /**
+   * Marks an array/collection variable meant to be iterated, not interpolated.
+   * The insert menu drops a `{% for item in code %}{{ item }}{% endfor %}`
+   * snippet instead of `{{ code }}`, and menus show a muted "list" tag.
+   * Default `false`.
+   */
+  collection?: boolean;
+}
+
+/** Drives the preview pane chrome. */
+export type LiquidPreviewStatus = 'idle' | 'loading' | 'error';
+
+/** Where the preview pane sits relative to the editor. */
+export type LiquidPreviewPlacement = 'bottom' | 'right';
+
+export interface LiquidEditorProps {
+  /** Controlled template source. */
+  value: string;
+  /** Fires on every edit (typing, paste, variable insert, autocomplete accept). */
+  onChange: (value: string) => void;
+  /** Available variables → insert menu, autocomplete, unknown flagging. */
+  variables?: LiquidVariable[];
+  /** Underline `{{ vars }}` not present in `variables`. Default `true` (no-op when `variables` empty). */
+  flagUnknownVariables?: boolean;
+  /** External error visual (red border) — set from a backend Liquid syntax error. Default `false`. */
+  invalid?: boolean;
+  /** External error message shown in the footer. Pairs with `invalid`. */
+  error?: ReactNode;
+  /** Consumer-rendered preview output. When set (or `previewStatus` ≠ 'idle'), the pane shows. */
+  preview?: ReactNode;
+  /** Preview pane chrome. Default `'idle'`. */
+  previewStatus?: LiquidPreviewStatus;
+  /** Preview pane position. Default `'bottom'`. */
+  previewPlacement?: LiquidPreviewPlacement;
+  /** Show the line-number gutter. Default `true`. */
+  showLineNumbers?: boolean;
+  /** Show the toolbar (variable-insert menu). Default `true`. */
+  showToolbar?: boolean;
+  /**
+   * Custom action buttons rendered in the toolbar, right-aligned just before the
+   * "Insert variable" button (e.g. a Docs / Help link). Pass `<Button size="sm">`
+   * elements (or a fragment of them); a `ghost` variant pairs well next to the
+   * bordered "Insert variable" button. Only renders when `showToolbar` is true.
+   */
+  toolbarActions?: ReactNode;
+  /** Filter names offered in autocomplete after `|`. Defaults to a common Liquid set. */
+  filters?: string[];
+  /** Minimum visible rows. Default `4`. */
+  minRows?: number;
+  /** Maximum visible rows before the editor scrolls internally. Default unbounded. */
+  maxRows?: number;
+  /** Read-only: caret + selection allowed, no edits. Default `false`. */
+  readOnly?: boolean;
+  /** Disabled: non-interactive + dimmed. Default `false`. */
+  disabled?: boolean;
+  /** Optional id forwarded to the textarea (for `<Field>` / label association). */
+  id?: string;
+  /** Optional name forwarded to the textarea. */
+  name?: string;
+  /** Placeholder shown when empty. */
+  placeholder?: string;
+  /**
+   * Accessible label (defaults to the i18n `liquidEditor.editorLabel` when
+   * omitted OR empty — an empty string is not an explicit name).
+   */
+  'aria-label'?: string;
+  /** Id of an external label element. */
+  'aria-labelledby'?: string;
+  /**
+   * Id(s) of external description element(s). Merged with the component's own
+   * footer description (the `error` / unknown-variable message), so a screen
+   * reader announces both. You usually don't need this — the footer is wired
+   * automatically; pass it only to add an extra external description.
+   */
+  'aria-describedby'?: string;
+  /** Extra class on the root wrapper. */
+  className?: string;
+}

package/src/components/LiquidEditor/useLiquidAutocomplete.ts

@@ -0,0 +1,178 @@
+import { useCallback, useMemo, useState } from 'react';
+import type { LiquidVariable } from './types';
+
+/** Whether the caret context expects a variable name or a filter name. */
+export type AutocompleteKind = 'variable' | 'filter';
+
+export interface AutocompleteContext {
+  /** Variable position (value slot) vs filter position (right after a `|`). */
+  kind: AutocompleteKind;
+  /** The identifier prefix already typed (may be empty). */
+  query: string;
+  /** Index in the value where the current word starts. */
+  wordStart: number;
+}
+
+// #304: the QUERY walk includes dots so a dotted code ("event.type") matches
+// while the user types past the root. Only the walk-back + validity check
+// use it — tokenization/filter detection are unaffected. Exported so callers
+// that need to walk the same "variable reference" word (e.g. the footer's
+// caret-variable lookup) share one definition instead of a second literal.
+export const QUERY_CHAR = /[A-Za-z0-9_.]/;
+
+/**
+ * Inspect the value + caret and decide if/what to autocomplete. Returns null
+ * when the caret is not inside an open `{{ }}` / `{% %}` (no intervening close).
+ *
+ * @param value The full editor source.
+ * @param caret The caret index (`selectionStart`).
+ */
+export function getAutocompleteContext(value: string, caret: number): AutocompleteContext | null {
+  // Find the nearest opener before the caret.
+  const open = Math.max(value.lastIndexOf('{{', caret - 1), value.lastIndexOf('{%', caret - 1));
+  if (open === -1) return null;
+  // If a close occurs between the opener and the caret, we're outside.
+  const closeBetween = Math.max(
+    value.lastIndexOf('}}', caret - 1),
+    value.lastIndexOf('%}', caret - 1),
+  );
+  if (closeBetween > open) return null;
+
+  // Walk back from the caret over identifier chars to get the current word.
+  let wordStart = caret;
+  while (wordStart > open + 2 && QUERY_CHAR.test(value[wordStart - 1])) wordStart -= 1;
+  const query = value.slice(wordStart, caret);
+  if (/[^A-Za-z0-9_.]/.test(query)) return null;
+
+  // Look back (skipping spaces) for a `|` → filter context.
+  let j = wordStart - 1;
+  while (j > open && value[j] === ' ') j -= 1;
+  const kind: AutocompleteKind = value[j] === '|' ? 'filter' : 'variable';
+
+  return { kind, query, wordStart };
+}
+
+/**
+ * Replace the word at `ctx.wordStart` (up to the caret) with `completion`.
+ *
+ * @returns The next value and the caret position after the inserted completion.
+ */
+export function applyCompletion(
+  value: string,
+  caret: number,
+  ctx: { wordStart: number; query: string },
+  completion: string,
+): { value: string; caret: number } {
+  const before = value.slice(0, ctx.wordStart);
+  const after = value.slice(caret);
+  const next = before + completion + after;
+  return { value: next, caret: before.length + completion.length };
+}
+
+export interface AutocompleteItem {
+  /** The text inserted on accept. */
+  value: string;
+  /** Display label. */
+  label: string;
+  /** Optional type tag (variables only). */
+  type?: string;
+  /** Optional group header (variables only). */
+  group?: string;
+  /** Optional description shown as a muted second line (variables only). */
+  description?: string;
+  /** Collection flag → "list" tag (variables only). */
+  collection?: boolean;
+}
+
+export interface UseLiquidAutocompleteArgs {
+  /** Variables offered in value position. */
+  variables: LiquidVariable[];
+  /** Filter names offered after a `|`. */
+  filters: readonly string[];
+  /** Gate the menu off entirely (read-only / disabled editors). */
+  enabled: boolean;
+}
+
+export interface AutocompleteState {
+  /** Whether the listbox should be shown. */
+  open: boolean;
+  /** The filtered suggestions for the current context. */
+  items: AutocompleteItem[];
+  /** Index of the highlighted suggestion. */
+  activeIndex: number;
+  /** The caret context that produced `items` (null when closed). */
+  context: AutocompleteContext | null;
+}
+
+/**
+ * Stateful autocomplete controller. `recompute(value, caret)` is called after
+ * every edit / caret move; `move`, `close` drive keyboard handling. The
+ * orchestrator reads `state.context` to apply a completion via
+ * {@link applyCompletion}.
+ *
+ * @param args Variables, filter names, and an `enabled` gate.
+ */
+export function useLiquidAutocomplete({ variables, filters, enabled }: UseLiquidAutocompleteArgs) {
+  const [state, setState] = useState<AutocompleteState>({
+    open: false,
+    items: [],
+    activeIndex: 0,
+    context: null,
+  });
+
+  const variableItems = useMemo<AutocompleteItem[]>(
+    () =>
+      variables.map((v) => ({
+        value: v.code,
+        // `||`, not `??`. This is the SAME prop as InsertVariableMenu's, and it
+        // feeds `AutocompleteMenu`'s `<span>{item.label}</span>` — a
+        // `role="option"`'s only name source. `label: ''` rendered a blank
+        // option, and the docs in `types.ts` and AI-PRIMER.md promise it cannot.
+        label: v.label || v.code,
+        type: v.type,
+        group: v.group,
+        description: v.description,
+        collection: v.collection,
+      })),
+    [variables],
+  );
+
+  const recompute = useCallback(
+    (value: string, caret: number) => {
+      if (!enabled) {
+        setState((s) => (s.open ? { ...s, open: false } : s));
+        return;
+      }
+      const ctx = getAutocompleteContext(value, caret);
+      if (!ctx) {
+        setState((s) => (s.open ? { ...s, open: false, context: null } : s));
+        return;
+      }
+      const q = ctx.query.toLowerCase();
+      const items =
+        ctx.kind === 'filter'
+          ? filters
+              .filter((f) => f.toLowerCase().startsWith(q))
+              .map((f) => ({ value: f, label: f }))
+          : variableItems.filter(
+              (it) => it.value.toLowerCase().startsWith(q) || it.label.toLowerCase().startsWith(q),
+            );
+      setState({ open: items.length > 0, items, activeIndex: 0, context: ctx });
+    },
+    [enabled, filters, variableItems],
+  );
+
+  const move = useCallback((delta: number) => {
+    setState((s) => {
+      if (!s.open || s.items.length === 0) return s;
+      const next = (s.activeIndex + delta + s.items.length) % s.items.length;
+      return { ...s, activeIndex: next };
+    });
+  }, []);
+
+  const close = useCallback(() => {
+    setState((s) => (s.open ? { ...s, open: false } : s));
+  }, []);
+
+  return { state, recompute, move, close };
+}

package/src/components/List/List.module.scss

@@ -0,0 +1,105 @@
+@use './List.tokens';
+
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--list-gap-sm);
+
+  // UA reset — <ul>/<ol> ship with default margin and padding.
+  // stylelint-disable-next-line property-disallowed-list -- UA reset for list default margin
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  line-height: var(--list-line-height);
+}
+
+// Set on this list's own markers, not on the list, so a nested body-size List
+// (rendered inside .content) keeps the :root body values (#711).
+.list[data-size='heading'] > .item > .marker {
+  --list-marker-height: var(--list-heading-marker-height);
+  --list-marker-width: var(--list-heading-marker-width);
+  --list-bullet-size: var(--list-heading-bullet-size);
+  --list-number-font-size: var(--list-heading-number-font-size);
+  --list-badge-size: var(--list-heading-badge-size);
+  --list-badge-radius: var(--list-heading-badge-radius);
+  --list-badge-font-size: var(--list-heading-badge-font-size);
+}
+
+.list[data-variant='number'] {
+  // Nested <ol>s start a fresh counter instance, so numbering restarts per list.
+  counter-reset: list-item-number;
+}
+
+.list[data-variant='number'] > .item {
+  counter-increment: list-item-number;
+}
+
+.list[data-gap='xs'] {
+  gap: var(--list-gap-xs);
+}
+
+.list[data-gap='md'] {
+  gap: var(--list-gap-md);
+}
+
+.item {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--list-marker-gap);
+}
+
+// One line tall, so a marker centres on the FIRST text line of a multi-line item.
+.marker {
+  display: flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  min-width: var(--list-marker-width);
+  height: var(--list-marker-height);
+  color: var(--list-marker-fg);
+}
+
+.bullet {
+  width: var(--list-bullet-size);
+  height: var(--list-bullet-size);
+  border-radius: 50%;
+  background: currentcolor;
+}
+
+.number::before,
+.badge::before {
+  content: counter(list-item-number);
+}
+
+.number {
+  font-size: var(--list-number-font-size);
+  font-weight: var(--list-number-font-weight);
+  font-variant-numeric: tabular-nums;
+}
+
+.badge {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: var(--list-badge-size);
+  height: var(--list-badge-size);
+  border-radius: var(--list-badge-radius);
+  background: var(--list-badge-bg);
+  color: var(--list-badge-fg);
+  font-size: var(--list-badge-font-size);
+  font-weight: var(--list-badge-font-weight);
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+}
+
+// Block, not flex: inline children (text + <code>) must flow as one line of prose.
+// min-width: 0 lets long words wrap inside the flex row instead of overflowing.
+.content {
+  min-width: 0;
+}
+
+// A nested list sits under its parent's text; padding, not margin, keeps the layout rule.
+.list[data-nested='true'] {
+  padding-block-start: var(--list-gap-xs);
+}

package/src/components/List/List.tokens.scss

@@ -0,0 +1,42 @@
+// List.tokens.scss — Component-scoped tokens for <List>. Item gap per size, marker column, bullet dot, plain-number marker and the badge number.
+:root {
+  // Row gap per `gap` size
+  --list-gap-xs: var(--space-1);
+  --list-gap-sm: var(--space-2);
+  --list-gap-md: var(--space-3);
+
+  // Marker column — hanging indent; item text wraps under itself, not the marker
+  --list-marker-gap: var(--space-2);
+  --list-marker-width: var(--size-badge);
+  --list-line-height: var(--line-height-normal);
+  --list-marker-height: calc(var(--list-line-height) * 1em);
+
+  // Marker colour — muted, a graphic/text on the page surface
+  --list-marker-fg: var(--color-fg-muted);
+
+  // Bullet dot
+  --list-bullet-size: var(--size-badge-dot);
+
+  // Plain number
+  --list-number-font-weight: var(--font-weight-medium);
+  --list-number-font-size: 1em;
+
+  // Badge number
+  --list-badge-size: var(--size-badge);
+  --list-badge-radius: var(--radius-full);
+  --list-badge-bg: var(--color-accent-bg-subtle);
+  --list-badge-fg: var(--color-accent);
+  --list-badge-font-size: var(--font-size-xs);
+  --list-badge-font-weight: var(--font-weight-semibold);
+
+  // size="heading" — marker scaled to the first line of a Title size="xl" (20px x tight line height).
+  // Derived from the same globals Title.tokens.scss aliases, not from --title-* themselves: those are only
+  // emitted with Title's lazily loaded stylesheet, so they may be undefined when a List renders without a Title.
+  --list-heading-marker-height: calc(var(--line-height-tight) * var(--font-size-xl));
+  --list-heading-marker-width: var(--space-6);
+  --list-heading-bullet-size: var(--space-2);
+  --list-heading-number-font-size: var(--font-size-lg);
+  --list-heading-badge-size: var(--space-6);
+  --list-heading-badge-radius: var(--radius-sm);
+  --list-heading-badge-font-size: var(--font-size-md);
+}