@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Link/Link.tsx

@@ -0,0 +1,114 @@
+import {
+  forwardRef,
+  type ComponentPropsWithoutRef,
+  type ComponentPropsWithRef,
+  type ElementType,
+  type ForwardedRef,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import styles from './Link.module.scss';
+
+/**
+ * Visual variant. Defaults to `'default'`.
+ * - `'default'` — link color (`--color-link-fg`, the accent unless the accent set
+ *   overrides it), no underline at rest, underline + hover color on hover. Under
+ *   `data-accent="tealpine"` it is also medium weight, except inside headings,
+ *   `<strong>`/`<b>` and `<th>`.
+ *   Use for inline CTA links ("View all →", "Read more").
+ * - `'muted'` — muted color, no underline, accent-hover on hover.
+ *   Use inside breadcrumbs or any low-emphasis nav.
+ * - `'subtle'` — full foreground color, no underline at rest, underline + accent-hover on hover.
+ *   Use for primary clickable text in dense surfaces (table name cells, card titles).
+ */
+export type LinkVariant = 'default' | 'muted' | 'subtle';
+
+/**
+ * Underline behavior, independent of `variant`. Defaults to `'hover'`, which
+ * preserves each variant's existing look exactly — this prop only needs to
+ * be passed to opt into one of the other two behaviors.
+ * - `'hover'` — (default, same as omitting the prop) each variant's own
+ *   at-rest/hover behavior: `default`/`subtle` underline on hover only,
+ *   `muted` never underlines.
+ * - `'always'` — underlined at rest (and stays underlined on hover). Use for
+ *   any Link inside running text/body copy: color alone is not a sufficient
+ *   visual cue (WCAG 1.4.1 — the default accent-on-body contrast is 2.06:1,
+ *   below the 3:1 non-text threshold), so an inline link needs an underline
+ *   to be told apart from surrounding words without relying on color.
+ * - `'none'` — never underlined, not even on hover. Use for brand/nav/logo
+ *   links that want a variant's subtle color without a hover underline.
+ */
+export type LinkUnderline = 'hover' | 'always' | 'none';
+
+interface LinkOwnProps {
+  /** Visual variant. See `LinkVariant` for descriptions. */
+  variant?: LinkVariant;
+  /** Underline behavior. See `LinkUnderline` for descriptions. Default: `'hover'`. */
+  underline?: LinkUnderline;
+  children?: ReactNode;
+}
+
+/**
+ * Polymorphic props helper. Intersects the component's own props with the
+ * underlying element's props (minus what we own), plus the `as` selector.
+ */
+type PolymorphicProps<C extends ElementType, P> = P & { as?: C } & Omit<
+    ComponentPropsWithoutRef<C>,
+    keyof P | 'as'
+  >;
+
+/**
+ * Public Link prop type. Generic `C` defaults to `'a'`. When the consumer
+ * passes `as={SomeComponent}`, all of SomeComponent's props become available
+ * with full TypeScript inference (including `to`, `replace`, `state`, etc. for
+ * `react-router-dom`'s `<Link>`).
+ */
+export type LinkProps<C extends ElementType = 'a'> = PolymorphicProps<C, LinkOwnProps>;
+
+/**
+ * Internal ref type for the polymorphic generic. React's `forwardRef` strips
+ * the generic from the returned component, so we re-attach it via the
+ * `LinkComponent` cast on the export below.
+ */
+type LinkComponent = <C extends ElementType = 'a'>(
+  props: LinkProps<C> & { ref?: ComponentPropsWithRef<C>['ref'] },
+) => ReactElement | null;
+
+const VARIANT_CLASS: Record<LinkVariant, string> = {
+  default: styles.default,
+  muted: styles.muted,
+  subtle: styles.subtle,
+};
+
+// `'hover'` (the default) adds no class — each variant's own rules already
+// implement it. Only the two overrides need a class.
+const UNDERLINE_CLASS: Partial<Record<LinkUnderline, string>> = {
+  always: styles.underlineAlways,
+  none: styles.underlineNone,
+};
+
+/**
+ * Polymorphic styled anchor (`as` for router links) with `default` / `muted` / `subtle` variants; for navigation only.
+ * @see docs/components/Link.md
+ */
+export const Link = forwardRef(function Link<C extends ElementType = 'a'>(
+  { as, variant = 'default', underline, className, children, ...props }: LinkProps<C>,
+  ref: ForwardedRef<Element>,
+) {
+  const Component = (as || 'a') as ElementType;
+  return (
+    <Component
+      ref={ref}
+      {...props}
+      className={clsx(
+        styles.link,
+        VARIANT_CLASS[variant],
+        underline && UNDERLINE_CLASS[underline],
+        className,
+      )}
+    >
+      {children}
+    </Component>
+  );
+}) as LinkComponent;

package/src/components/Link/index.ts

@@ -0,0 +1,2 @@
+export { Link } from './Link';
+export type { LinkProps, LinkVariant, LinkUnderline } from './Link';

package/src/components/LinkCard/LinkCard.module.scss

@@ -0,0 +1,92 @@
+@use '../../styles/mixins' as *;
+@use './LinkCard.tokens';
+@use '../Card/Card.tokens';
+
+.linkCard {
+  --link-card-elevation: var(--link-card-shadow);
+
+  display: block;
+  background: var(--card-bg);
+  border: var(--border-width) solid var(--card-border-color);
+  border-radius: var(--card-radius);
+  box-shadow: var(--link-card-elevation);
+  overflow: hidden;
+  color: inherit;
+  text-decoration: none;
+  cursor: pointer;
+  transition: var(--link-card-transition);
+}
+
+.linkCard:hover {
+  --link-card-elevation: var(--link-card-hover-shadow);
+
+  border-color: var(--link-card-hover-border-color);
+
+  // Re-assert no underline on hover. The library's own global hover rule
+  // (typography.scss's `a:where(:hover)`, specificity 0,0,1) is deliberately
+  // kept below `.linkCard` (0,1,0) so it can't win here — this is defensive
+  // against a CONSUMER's global link rule (e.g. a plain `a:hover { text-
+  // decoration: underline }` in the CRM shell), which has no such restraint
+  // and would otherwise out-specify `.linkCard`'s rest rule. A LinkCard is a
+  // surface, never text.
+  text-decoration: none;
+}
+
+// --link-card-focus-offset used to override this to 2px, identical to the
+// mixin's own --ring-offset default — a no-op token, deleted along with the
+// override.
+.linkCard:focus-visible {
+  @include focus-ring;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .linkCard {
+    transition: none;
+  }
+}
+
+.linkCard[data-tone='accent'] {
+  box-shadow:
+    inset var(--card-stripe-width) 0 0 var(--card-stripe-color-accent),
+    var(--link-card-elevation);
+}
+
+.linkCard[data-tone='info'] {
+  box-shadow:
+    inset var(--card-stripe-width) 0 0 var(--card-stripe-color-info),
+    var(--link-card-elevation);
+}
+
+.linkCard[data-tone='success'] {
+  box-shadow:
+    inset var(--card-stripe-width) 0 0 var(--card-stripe-color-success),
+    var(--link-card-elevation);
+}
+
+.linkCard[data-tone='warning'] {
+  box-shadow:
+    inset var(--card-stripe-width) 0 0 var(--card-stripe-color-warning),
+    var(--link-card-elevation);
+}
+
+.linkCard[data-tone='danger'] {
+  box-shadow:
+    inset var(--card-stripe-width) 0 0 var(--card-stripe-color-danger),
+    var(--link-card-elevation);
+}
+
+.paddingNone {
+  padding: 0;
+}
+
+.paddingSm {
+  padding: var(--card-padding-sm);
+}
+
+.paddingMd {
+  padding: var(--card-padding-md);
+}
+
+.paddingLg {
+  padding: var(--card-padding-lg);
+}

package/src/components/LinkCard/LinkCard.tokens.scss

@@ -0,0 +1,9 @@
+// LinkCard.tokens.scss — interactive-state tokens over Card's reused surface tokens.
+@use '../Card/Card.tokens';
+
+:root {
+  --link-card-shadow: var(--card-shadow); // rest = Card's shadow (--shadow-sm)
+  --link-card-hover-shadow: var(--shadow-md);
+  --link-card-hover-border-color: var(--color-border-strong);
+  --link-card-transition: border-color 120ms ease, box-shadow 120ms ease;
+}

package/src/components/LinkCard/LinkCard.tsx

@@ -0,0 +1,72 @@
+import {
+  forwardRef,
+  type ComponentPropsWithoutRef,
+  type ComponentPropsWithRef,
+  type ElementType,
+  type ForwardedRef,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import { type CardPadding, type CardTone } from '../Card';
+import styles from './LinkCard.module.scss';
+
+interface LinkCardOwnProps {
+  /** Inner padding — same scale as `Card`. Defaults to `'md'`. */
+  padding?: CardPadding;
+  /** Optional left-edge tone stripe — same vocabulary as `Card`. */
+  tone?: CardTone;
+  children?: ReactNode;
+}
+
+/** Polymorphic props helper (identical to Link's). */
+type PolymorphicProps<C extends ElementType, P> = P & { as?: C } & Omit<
+    ComponentPropsWithoutRef<C>,
+    keyof P | 'as'
+  >;
+
+/**
+ * Public LinkCard prop type. Generic `C` defaults to `'a'`. Passing
+ * `as={SomeComponent}` makes all of its props available with full inference
+ * (including `to` / `replace` for `react-router-dom`'s `<Link>`).
+ */
+export type LinkCardProps<C extends ElementType = 'a'> = PolymorphicProps<C, LinkCardOwnProps>;
+
+type LinkCardComponent = <C extends ElementType = 'a'>(
+  props: LinkCardProps<C> & { ref?: ComponentPropsWithRef<C>['ref'] },
+) => ReactElement | null;
+
+const paddingClass: Record<CardPadding, string> = {
+  none: styles.paddingNone,
+  sm: styles.paddingSm,
+  md: styles.paddingMd,
+  lg: styles.paddingLg,
+};
+
+/**
+ * A clickable Card whose entire surface is one navigation or action target; polymorphic like `<Link>`.
+ * @see docs/components/LinkCard.md
+ */
+export const LinkCard = forwardRef(function LinkCard<C extends ElementType = 'a'>(
+  { as, padding = 'md', tone, className, children, ...props }: LinkCardProps<C>,
+  ref: ForwardedRef<Element>,
+) {
+  const Component = (as || 'a') as ElementType;
+  // Default native <button> to type="button" so it doesn't submit forms (Rule 6).
+  // Spread before {...props} so a consumer can still pass type="submit".
+  const typeDefault = Component === 'button' ? { type: 'button' as const } : {};
+
+  // typeDefault first, then {...props} (consumer wins), then component-owned
+  // className (merged via clsx) + data-tone — same spread order as Link.
+  return (
+    <Component
+      ref={ref}
+      {...typeDefault}
+      {...props}
+      className={clsx(styles.linkCard, paddingClass[padding], className)}
+      data-tone={tone}
+    >
+      {children}
+    </Component>
+  );
+}) as LinkCardComponent;

package/src/components/LinkCard/index.ts

@@ -0,0 +1,2 @@
+export { LinkCard } from './LinkCard';
+export type { LinkCardProps } from './LinkCard';

package/src/components/LiquidEditor/AutocompleteMenu.tsx

@@ -0,0 +1,133 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { useFloatingSurface } from '../_internal/overlay';
+import { createPortal } from 'react-dom';
+import { useFloating, autoUpdate, flip, shift, offset } from '@floating-ui/react-dom';
+import clsx from 'clsx';
+import type { AutocompleteItem } from './useLiquidAutocomplete';
+import { useTranslation } from '../../i18n';
+import styles from './LiquidEditor.module.scss';
+
+export interface AutocompleteMenuProps {
+  /** Suggestions to render. */
+  items: AutocompleteItem[];
+  /** Index of the highlighted suggestion (driven by the textarea's keyboard handling). */
+  activeIndex: number;
+  /** Caret rect (viewport coords) the menu anchors to. */
+  anchorRect: { top: number; left: number; height: number; width: number };
+  /** Id shared with the textarea's `aria-controls` / `aria-activedescendant`. */
+  listboxId: string;
+  /** Called when a suggestion is picked with the mouse. */
+  onSelect: (item: AutocompleteItem, index: number) => void;
+}
+
+/**
+ * The floating combobox listbox. Anchored to a virtual element built from the
+ * caret rect. Mouse interactions select; keyboard is handled by the textarea
+ * (which owns focus) via `aria-activedescendant`.
+ */
+export function AutocompleteMenu({
+  items,
+  activeIndex,
+  anchorRect,
+  listboxId,
+  onSelect,
+}: AutocompleteMenuProps) {
+  // #274: mounted only while open — register as a floating surface so
+  // Modal/Drawer/Lightbox yield Escape to us (our own Escape handling closes
+  // us; without registration one press would close the host too).
+  useFloatingSurface(true);
+  const t = useTranslation();
+
+  // A Floating UI virtual element: only `getBoundingClientRect` is required.
+  const virtualRef = useMemo(
+    () => ({
+      getBoundingClientRect: () => ({
+        x: anchorRect.left,
+        y: anchorRect.top,
+        top: anchorRect.top,
+        left: anchorRect.left,
+        right: anchorRect.left + anchorRect.width,
+        bottom: anchorRect.top + anchorRect.height,
+        width: anchorRect.width,
+        height: anchorRect.height,
+      }),
+    }),
+    [anchorRect],
+  );
+
+  const { refs, floatingStyles } = useFloating({
+    placement: 'bottom-start',
+    // `fixed` + viewport-coord anchor + portal to <body> so the menu escapes the
+    // editor's `overflow: hidden` and any positioned/scrolled ancestor (Drawer,
+    // Modal). Mirrors how DropdownMenu / Popover / Tooltip position themselves.
+    strategy: 'fixed',
+    whileElementsMounted: autoUpdate,
+    middleware: [offset(4), flip(), shift({ padding: 4 })],
+    elements: { reference: virtualRef },
+  });
+
+  // Keep the keyboard-active option scrolled into view inside the menu's
+  // (max-height, overflow-y:auto) box — arrow-key nav must not move the
+  // highlight off-screen. Focus stays on the textarea, so we scroll manually.
+  const activeRef = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    activeRef.current?.scrollIntoView?.({ block: 'nearest' });
+  }, [activeIndex]);
+
+  // Precompute group-header flags before render (no mutation during the map —
+  // keeps the render pure under StrictMode double-invocation). A header shows
+  // when an item's group differs from the previous item's.
+  const showGroupAt = items.map(
+    (item, idx) => item.group !== undefined && item.group !== items[idx - 1]?.group,
+  );
+
+  return createPortal(
+    <ul
+      ref={refs.setFloating}
+      id={listboxId}
+      role="listbox"
+      aria-label={t('liquidEditor.suggestions')}
+      className={styles.menu}
+      style={floatingStyles}
+    >
+      {items.map((item, idx) => {
+        const showGroup = showGroupAt[idx];
+        return (
+          <li key={`${item.value}-${idx}`} role="presentation">
+            {showGroup ? (
+              <div className={styles.menuGroupLabel} role="presentation">
+                {item.group}
+              </div>
+            ) : null}
+            <div
+              id={`${listboxId}-opt-${idx}`}
+              ref={idx === activeIndex ? activeRef : undefined}
+              role="option"
+              aria-selected={idx === activeIndex}
+              className={clsx(styles.menuItem, idx === activeIndex && styles.menuItemActive)}
+              // Use onMouseDown (not onClick) so the textarea doesn't blur first.
+              onMouseDown={(e) => {
+                e.preventDefault();
+                onSelect(item, idx);
+              }}
+            >
+              <span className={styles.menuItemMain}>
+                <span>{item.label}</span>
+                {item.description ? (
+                  <span className={styles.menuItemDesc}>{item.description}</span>
+                ) : null}
+              </span>
+              <span className={styles.menuItemTags}>
+                {item.collection ? (
+                  <span className={styles.menuItemType}>{t('liquidEditor.collectionTag')}</span>
+                ) : null}
+                {item.type ? <span className={styles.menuItemType}>{item.type}</span> : null}
+              </span>
+            </div>
+          </li>
+        );
+      })}
+    </ul>,
+    document.body,
+  );
+}

package/src/components/LiquidEditor/HighlightLayer.tsx

@@ -0,0 +1,53 @@
+import { memo } from 'react';
+import clsx from 'clsx';
+import type { LiquidToken, LiquidTokenType } from './liquidTokenizer';
+import styles from './LiquidEditor.module.scss';
+
+const TOKEN_CLASS: Partial<Record<LiquidTokenType, string>> = {
+  delimiter: styles.delimiter,
+  variable: styles.variable,
+  filter: styles.filter,
+  string: styles.string,
+  number: styles.number,
+  keyword: styles.keyword,
+  operator: styles.operator,
+  unknown: styles.unknown,
+  // `text` has no class — inherits the base color.
+};
+
+export interface HighlightLayerProps {
+  /** Contiguous tokens whose `value`s concatenate back to the editor source. */
+  tokens: LiquidToken[];
+  /** Extra class merged onto the `<pre>` (e.g. to forward a scroll-sync ref's styling). */
+  className?: string;
+}
+
+/**
+ * The colored layer painted beneath the textarea. `aria-hidden` — the textarea
+ * carries the real, screen-reader-visible text. A trailing newline gets a
+ * zero-width space so the last empty line keeps its height (matching the
+ * textarea's own trailing-line behavior).
+ */
+export const HighlightLayer = memo(function HighlightLayer({
+  tokens,
+  className,
+}: HighlightLayerProps) {
+  const last = tokens[tokens.length - 1];
+  const trailingNewline = last !== undefined && last.value.endsWith('\n');
+  return (
+    <pre className={clsx(styles.highlight, className)} aria-hidden="true">
+      {tokens.map((t, idx) => {
+        const cls = TOKEN_CLASS[t.type];
+        return cls ? (
+          <span key={idx} className={cls}>
+            {t.value}
+          </span>
+        ) : (
+          // Plain text — no token class, just inherits the base color.
+          <span key={idx}>{t.value}</span>
+        );
+      })}
+      {trailingNewline ? '​' : null}
+    </pre>
+  );
+});

package/src/components/LiquidEditor/InsertVariableMenu.tsx

@@ -0,0 +1,81 @@
+import { DropdownMenu } from '../DropdownMenu';
+import { Button } from '../Button';
+import { useTranslation } from '../../i18n';
+import type { LiquidVariable } from './types';
+import styles from './LiquidEditor.module.scss';
+
+export interface InsertVariableMenuProps {
+  /** Variables offered in the menu, grouped by `group` in first-seen order. */
+  variables: LiquidVariable[];
+  /** Disable the trigger (read-only / disabled editor). */
+  disabled?: boolean;
+  /** Called with the chosen variable when an item is selected. */
+  onInsert: (variable: LiquidVariable) => void;
+}
+
+/**
+ * Toolbar menu that inserts `{{ code }}` at the caret — or, for a collection
+ * variable (`collection: true`), a `{% for item in code %}{{ item }}{% endfor %}`
+ * snippet with the caret left after `{{ item }}`. Groups variables by their
+ * `group` field (first-seen order) under section labels; ungrouped variables
+ * render without a label. Shows an empty-state label when there are none.
+ */
+export function InsertVariableMenu({ variables, disabled, onInsert }: InsertVariableMenuProps) {
+  const t = useTranslation();
+
+  // Preserve first-seen group order.
+  const groups: { name: string | undefined; items: LiquidVariable[] }[] = [];
+  for (const v of variables) {
+    let g = groups.find((x) => x.name === v.group);
+    if (!g) {
+      g = { name: v.group, items: [] };
+      groups.push(g);
+    }
+    g.items.push(v);
+  }
+
+  return (
+    <DropdownMenu>
+      {/* Trigger clones its single child to inject ref + ARIA — no `asChild`. */}
+      <DropdownMenu.Trigger>
+        <Button variant="secondary" size="sm" disabled={disabled || variables.length === 0}>
+          {t('liquidEditor.insertVariable')}
+        </Button>
+      </DropdownMenu.Trigger>
+      <DropdownMenu.Content>
+        {variables.length === 0 ? (
+          <DropdownMenu.Label>{t('liquidEditor.noVariables')}</DropdownMenu.Label>
+        ) : (
+          groups.map((group, gi) => (
+            <DropdownMenu.Group key={group.name ?? `g${gi}`}>
+              {group.name ? <DropdownMenu.Label>{group.name}</DropdownMenu.Label> : null}
+              {group.items.map((v) => {
+                const tags = [v.collection ? t('liquidEditor.collectionTag') : null, v.type]
+                  .filter(Boolean)
+                  .join(' · ');
+                return (
+                  <DropdownMenu.Item
+                    key={v.code}
+                    onSelect={() => onInsert(v)}
+                    shortcut={tags || undefined}
+                  >
+                    <span className={styles.menuItemMain}>
+                      {/* `||`, not `??`: `code` is here so a menu item always
+                          has SOMETHING readable, and this span is the item's
+                          only name source — `label: ''` would defeat it and
+                          render a blank menuitem (#535). */}
+                      <span>{v.label || v.code}</span>
+                      {v.description ? (
+                        <span className={styles.menuItemDesc}>{v.description}</span>
+                      ) : null}
+                    </span>
+                  </DropdownMenu.Item>
+                );
+              })}
+            </DropdownMenu.Group>
+          ))
+        )}
+      </DropdownMenu.Content>
+    </DropdownMenu>
+  );
+}