@eocrm/design-system 0.6.24 → 0.8.0

package/dist/components/LiquidEditor/caretCoordinates.d.ts

@@ -0,0 +1,9 @@
+export interface CaretCoordinates {
+    /** Offset from the textarea's top padding edge, in px. */
+    top: number;
+    /** Offset from the textarea's left padding edge, in px. */
+    left: number;
+    /** Line height at the caret, in px (menu offsets below by this). */
+    height: number;
+}
+export declare function getCaretCoordinates(textarea: HTMLTextAreaElement, position: number): CaretCoordinates;

package/dist/components/LiquidEditor/caretCoordinates.js

@@ -0,0 +1,68 @@
+// src/components/LiquidEditor/caretCoordinates.ts
+var MIRRORED_PROPS = [
+	"boxSizing",
+	"width",
+	"paddingTop",
+	"paddingRight",
+	"paddingBottom",
+	"paddingLeft",
+	"borderTopWidth",
+	"borderRightWidth",
+	"borderBottomWidth",
+	"borderLeftWidth",
+	"fontStyle",
+	"fontVariant",
+	"fontWeight",
+	"fontStretch",
+	"fontSize",
+	"fontSizeAdjust",
+	"lineHeight",
+	"fontFamily",
+	"textAlign",
+	"textTransform",
+	"textIndent",
+	"textDecoration",
+	"letterSpacing",
+	"wordSpacing",
+	"tabSize",
+	"whiteSpace",
+	"wordWrap"
+];
+function getCaretCoordinates(textarea, position) {
+	const doc = textarea.ownerDocument;
+	const style = (doc.defaultView ?? window).getComputedStyle(textarea);
+	const mirror = doc.createElement("div");
+	mirror.setAttribute("aria-hidden", "true");
+	const s = mirror.style;
+	s.position = "absolute";
+	s.visibility = "hidden";
+	s.whiteSpace = "pre-wrap";
+	s.wordWrap = "break-word";
+	s.top = "0";
+	s.left = "-9999px";
+	s.overflow = "hidden";
+	for (const prop of MIRRORED_PROPS) {
+		const value = style[prop];
+		if (value) s.setProperty(toKebab(prop), value);
+	}
+	s.width = `${textarea.clientWidth}px`;
+	mirror.textContent = textarea.value.slice(0, position);
+	const marker = doc.createElement("span");
+	marker.textContent = textarea.value.slice(position) || ".";
+	mirror.appendChild(marker);
+	doc.body.appendChild(mirror);
+	const lineHeight = parseFloat(style.lineHeight) || parseFloat(style.fontSize) || 0;
+	const coords = {
+		top: marker.offsetTop - textarea.scrollTop,
+		left: marker.offsetLeft - textarea.scrollLeft,
+		height: Number.isFinite(lineHeight) ? lineHeight : 0
+	};
+	mirror.remove();
+	if (!Number.isFinite(coords.top)) coords.top = 0;
+	if (!Number.isFinite(coords.left)) coords.left = 0;
+	return coords;
+}
+function toKebab(prop) {
+	return prop.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
+export { getCaretCoordinates };

package/dist/components/LiquidEditor/index.d.ts

@@ -0,0 +1,2 @@
+export { LiquidEditor } from './LiquidEditor.js';
+export type { LiquidEditorProps, LiquidVariable, LiquidPreviewStatus, LiquidPreviewPlacement, } from './types.js';

package/dist/components/LiquidEditor/liquidFilters.d.ts

@@ -0,0 +1,2 @@
+/** Common Liquid output filters, offered in autocomplete after a `|`. */
+export declare const DEFAULT_LIQUID_FILTERS: readonly string[];

package/dist/components/LiquidEditor/liquidFilters.js

@@ -0,0 +1,21 @@
+// src/components/LiquidEditor/liquidFilters.ts
+/** Common Liquid output filters, offered in autocomplete after a `|`. */
+var DEFAULT_LIQUID_FILTERS = [
+	"upcase",
+	"downcase",
+	"capitalize",
+	"strip",
+	"truncate",
+	"truncatewords",
+	"default",
+	"date",
+	"replace",
+	"append",
+	"prepend",
+	"size",
+	"first",
+	"last",
+	"join",
+	"escape"
+];
+export { DEFAULT_LIQUID_FILTERS };

package/dist/components/LiquidEditor/liquidTokenizer.d.ts

@@ -0,0 +1,27 @@
+export type LiquidTokenType = 'text' | 'delimiter' | 'variable' | 'unknown' | 'filter' | 'string' | 'number' | 'keyword' | '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;
+}
+/**
+ * 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 declare function tokenize(source: string, knownCodes?: ReadonlySet<string>): LiquidToken[];
+/**
+ * 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 declare function unknownVariables(source: string, knownCodes: ReadonlySet<string>): string[];

package/dist/components/LiquidEditor/liquidTokenizer.js

@@ -0,0 +1,163 @@
+// src/components/LiquidEditor/liquidTokenizer.ts
+var KEYWORDS = /* @__PURE__ */ 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"
+]);
+var IDENT_START = /[A-Za-z_]/;
+var IDENT_CHAR = /[A-Za-z0-9_]/;
+var 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.
+*/
+function tokenize(source, knownCodes) {
+	const tokens = [];
+	const n = source.length;
+	let i = 0;
+	const hasKnown = knownCodes !== void 0 && knownCodes.size > 0;
+	const knownRoots = hasKnown ? new Set([...knownCodes].map((c) => c.split(".")[0])) : void 0;
+	const declaredVars = /* @__PURE__ */ new Set();
+	const push = (type, start, end) => {
+		if (end > start) tokens.push({
+			type,
+			value: source.slice(start, end),
+			start,
+			end
+		});
+	};
+	while (i < n) {
+		if (!(source[i] === "{" && (source[i + 1] === "{" || source[i + 1] === "%"))) {
+			const start = i;
+			while (i < n && !(source[i] === "{" && (source[i + 1] === "{" || source[i + 1] === "%"))) i += 1;
+			push("text", start, i);
+			continue;
+		}
+		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;
+		})();
+		let expectFilter = false;
+		let seenValue = false;
+		let expectDeclaration = false;
+		while (i < interiorEnd) {
+			const c = source[i];
+			if (c === " " || c === "	" || 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;
+				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);
+				else {
+					if (expectDeclaration) declaredVars.add(word);
+					push(hasKnown && !seenValue && !expectDeclaration && !knownRoots.has(word) && !declaredVars.has(word) ? "unknown" : "variable", start, i);
+					seenValue = true;
+					expectDeclaration = false;
+				}
+				continue;
+			}
+			if (c === "|") {
+				push("operator", i, i + 1);
+				expectFilter = true;
+				i += 1;
+				continue;
+			}
+			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;
+			}
+			push("text", i, i + 1);
+			i += 1;
+		}
+		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.
+*/
+function unknownVariables(source, knownCodes) {
+	if (knownCodes.size === 0) return [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const t of tokenize(source, knownCodes)) if (t.type === "unknown") seen.add(t.value);
+	return [...seen];
+}
+export { tokenize, unknownVariables };

package/dist/components/LiquidEditor/types.d.ts

@@ -0,0 +1,97 @@
+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/dist/components/LiquidEditor/useLiquidAutocomplete.d.ts

@@ -0,0 +1,78 @@
+import type { LiquidVariable } from './types.js';
+/** 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;
+}
+export declare const QUERY_CHAR: RegExp;
+/**
+ * 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 declare function getAutocompleteContext(value: string, caret: number): AutocompleteContext | null;
+/**
+ * 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 declare function applyCompletion(value: string, caret: number, ctx: {
+    wordStart: number;
+    query: string;
+}, completion: string): {
+    value: string;
+    caret: number;
+};
+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 declare function useLiquidAutocomplete({ variables, filters, enabled }: UseLiquidAutocompleteArgs): {
+    state: AutocompleteState;
+    recompute: (value: string, caret: number) => void;
+    move: (delta: number) => void;
+    close: () => void;
+};

package/dist/components/LiquidEditor/useLiquidAutocomplete.js

@@ -0,0 +1,117 @@
+'use client';
+import { useCallback, useMemo, useState } from "react";
+// src/components/LiquidEditor/useLiquidAutocomplete.ts
+var 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`).
+*/
+function getAutocompleteContext(value, caret) {
+	const open = Math.max(value.lastIndexOf("{{", caret - 1), value.lastIndexOf("{%", caret - 1));
+	if (open === -1) return null;
+	if (Math.max(value.lastIndexOf("}}", caret - 1), value.lastIndexOf("%}", caret - 1)) > open) return null;
+	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;
+	let j = wordStart - 1;
+	while (j > open && value[j] === " ") j -= 1;
+	return {
+		kind: value[j] === "|" ? "filter" : "variable",
+		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.
+*/
+function applyCompletion(value, caret, ctx, completion) {
+	const before = value.slice(0, ctx.wordStart);
+	const after = value.slice(caret);
+	return {
+		value: before + completion + after,
+		caret: before.length + completion.length
+	};
+}
+/**
+* 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.
+*/
+function useLiquidAutocomplete({ variables, filters, enabled }) {
+	const [state, setState] = useState({
+		open: false,
+		items: [],
+		activeIndex: 0,
+		context: null
+	});
+	const variableItems = useMemo(() => variables.map((v) => ({
+		value: v.code,
+		label: v.label || v.code,
+		type: v.type,
+		group: v.group,
+		description: v.description,
+		collection: v.collection
+	})), [variables]);
+	return {
+		state,
+		recompute: useCallback((value, caret) => {
+			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
+		]),
+		move: useCallback((delta) => {
+			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
+				};
+			});
+		}, []),
+		close: useCallback(() => {
+			setState((s) => s.open ? {
+				...s,
+				open: false
+			} : s);
+		}, [])
+	};
+}
+export { QUERY_CHAR, applyCompletion, getAutocompleteContext, useLiquidAutocomplete };