@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/Card/CardListRow.tsx

@@ -0,0 +1,24 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './Card.module.scss';
+
+export interface CardListRowProps extends HTMLAttributes<HTMLLIElement> {
+  /** Row content — typically a `<Stack>` or `<Cluster>` of text and metadata. */
+  children: ReactNode;
+}
+
+/**
+ * A single row inside a `<Card.List>`, rendered as `<li>`.
+ * @see docs/components/Card.md
+ */
+export const CardListRow = forwardRef<HTMLLIElement, CardListRowProps>(function CardListRow(
+  { children, className, ...rest },
+  ref,
+) {
+  // {...rest} last so consumer overrides win (Pattern A).
+  return (
+    <li ref={ref} className={clsx(styles.listRow, className)} {...rest}>
+      {children}
+    </li>
+  );
+});

package/src/components/Card/index.ts

@@ -0,0 +1,7 @@
+export { Card } from './Card';
+export { CardBody } from './CardBody';
+export type { CardProps, CardPadding, CardTone, CardOverflow } from './Card';
+export type { CardBodyProps } from './CardBody';
+export type { CardHeaderProps, CardHeaderLevel } from './CardHeader';
+export type { CardListProps } from './CardList';
+export type { CardListRowProps } from './CardListRow';

package/src/components/CatalogPicker/CatalogPicker.module.scss

@@ -0,0 +1,193 @@
+@use '../../styles/mixins' as *;
+@use './CatalogPicker.tokens';
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--catalog-picker-gap);
+  min-width: 0;
+
+  // Containing block for the out-of-flow stuck sentinel.
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- internal sentinel anchor
+  position: relative;
+}
+
+// Out-of-flow 1px probe at the root's top edge: adds no layout space or flex gap.
+.sentinel {
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- internal sentinel
+  position: absolute;
+  // stylelint-disable-next-line property-disallowed-list -- internal sentinel
+  inset-block-start: 0;
+  // stylelint-disable-next-line property-disallowed-list -- internal sentinel
+  inset-inline-start: 0;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- internal sentinel
+  width: 1px;
+  height: 1px;
+  pointer-events: none;
+  visibility: hidden;
+}
+
+// Internal sticky header: keeps search + pills reachable while the parent
+// (Drawer.Body / Modal.Body) scrolls. Not consumer layout.
+.toolbar {
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- internal sticky header
+  position: sticky;
+  // stylelint-disable-next-line property-disallowed-list -- internal sticky header
+  top: 0;
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+  gap: var(--catalog-picker-item-gap);
+  padding-block: var(--catalog-picker-toolbar-padding-block);
+  background: var(--catalog-picker-toolbar-bg);
+
+  // Covers the scrolling parent's top padding strip so cards never show above the
+  // pinned toolbar. Generic: sized by a token, not by Drawer/Modal's padding. It is only painted while the toolbar is actually stuck (data-stuck, set by an
+  // IntersectionObserver), so nothing above the picker is overpainted at rest.
+  &[data-stuck]::before {
+    content: '';
+    // stylelint-disable-next-line declaration-property-value-disallowed-list -- bleed pseudo, internal
+    position: absolute;
+    // stylelint-disable-next-line property-disallowed-list -- bleed pseudo, internal
+    inset-block-end: 100%;
+    // stylelint-disable-next-line property-disallowed-list -- bleed pseudo, internal
+    inset-inline: 0;
+    height: var(--catalog-picker-toolbar-bleed);
+    background: var(--catalog-picker-toolbar-bg);
+    pointer-events: none;
+  }
+}
+
+.pills {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--catalog-picker-pill-gap);
+}
+
+.pill {
+  position: relative;
+  display: inline-flex;
+  cursor: pointer;
+}
+
+// Native radio kept for semantics + arrow keys; visually replaced by the pill.
+.pillInput {
+  @include visually-hidden;
+}
+
+.pillLabel {
+  padding: var(--catalog-picker-pill-padding);
+  color: var(--catalog-picker-pill-fg);
+  font-size: var(--catalog-picker-title-size);
+  border: var(--border-width) solid var(--catalog-picker-pill-border);
+  border-radius: var(--radius-full);
+}
+
+.pillInput:checked + .pillLabel {
+  color: var(--catalog-picker-pill-fg-checked);
+  background: var(--catalog-picker-pill-bg-checked);
+  border-color: var(--catalog-picker-pill-bg-checked);
+}
+
+.pillInput:focus-visible + .pillLabel {
+  @include focus-ring(var(--catalog-picker-ring));
+}
+
+.search {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+}
+
+.searchIcon {
+  flex-shrink: 0;
+  color: var(--catalog-picker-search-icon-fg);
+}
+
+// Internal row arrangement (mirrors EmojiPicker's `.searchInput`).
+.searchInput {
+  flex: 1;
+}
+
+.count {
+  color: var(--catalog-picker-meta-fg);
+  font-size: var(--catalog-picker-meta-size);
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(var(--catalog-picker-item-min), 1fr));
+  gap: var(--catalog-picker-item-gap);
+}
+
+.option {
+  display: flex;
+  flex-direction: column;
+  gap: var(--catalog-picker-item-gap);
+  min-width: 0;
+  padding: var(--catalog-picker-item-padding);
+  background: var(--catalog-picker-item-bg);
+  border: var(--border-width) solid var(--catalog-picker-item-border);
+  border-radius: var(--catalog-picker-item-radius);
+  cursor: pointer;
+}
+
+.option:hover {
+  background: var(--catalog-picker-item-bg-hover);
+}
+
+.option:focus-visible {
+  @include focus-ring(var(--catalog-picker-ring));
+}
+
+.option[aria-disabled='true'] {
+  cursor: default;
+}
+
+// Dim the visuals, not the reason text (it must stay readable).
+.option[aria-disabled='true'] :is(.preview, .titleRow, .description) {
+  opacity: var(--catalog-picker-item-disabled-opacity);
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-05);
+  min-width: 0;
+}
+
+.titleRow {
+  display: flex;
+  align-items: center;
+  gap: var(--catalog-picker-item-gap);
+  min-width: 0;
+}
+
+.title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  font-size: var(--catalog-picker-title-size);
+  font-weight: var(--catalog-picker-title-weight);
+}
+
+.badge {
+  flex: none;
+}
+
+.description {
+  display: -webkit-box;
+  overflow: hidden;
+  color: var(--catalog-picker-meta-fg);
+  font-size: var(--catalog-picker-meta-size);
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+}
+
+.reason {
+  color: var(--catalog-picker-meta-fg);
+  font-size: var(--catalog-picker-meta-size);
+  font-style: italic;
+}

package/src/components/CatalogPicker/CatalogPicker.tokens.scss

@@ -0,0 +1,26 @@
+:root {
+  --catalog-picker-gap: var(--space-3);
+  --catalog-picker-toolbar-bg: var(--color-bg);
+  --catalog-picker-toolbar-bleed: var(--space-6);
+  --catalog-picker-toolbar-padding-block: var(--space-2);
+  --catalog-picker-item-min: 11rem;
+  --catalog-picker-item-gap: var(--space-2);
+  --catalog-picker-item-padding: var(--space-2);
+  --catalog-picker-item-radius: var(--radius-md);
+  --catalog-picker-item-bg: var(--color-bg);
+  --catalog-picker-item-bg-hover: var(--color-bg-hover);
+  --catalog-picker-item-border: var(--color-border);
+  --catalog-picker-item-disabled-opacity: var(--opacity-disabled);
+  --catalog-picker-title-size: var(--font-size-sm);
+  --catalog-picker-title-weight: var(--font-weight-semibold);
+  --catalog-picker-meta-size: var(--font-size-xs);
+  --catalog-picker-meta-fg: var(--color-fg-muted);
+  --catalog-picker-search-icon-fg: var(--color-fg-subtle);
+  --catalog-picker-pill-gap: var(--space-1);
+  --catalog-picker-pill-padding: var(--space-1) var(--space-3);
+  --catalog-picker-pill-border: var(--color-border);
+  --catalog-picker-pill-fg: var(--color-fg);
+  --catalog-picker-pill-bg-checked: var(--color-accent);
+  --catalog-picker-pill-fg-checked: var(--color-accent-fg);
+  --catalog-picker-ring: var(--ring-accent);
+}

package/src/components/CatalogPicker/CatalogPicker.tsx

@@ -0,0 +1,339 @@
+import {
+  forwardRef,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import { Search } from 'lucide-react';
+import { Input } from '../Input';
+import { overlayStack } from '../_internal/overlay';
+import { EmptyState } from '../EmptyState';
+import { useTranslation } from '../../i18n/useTranslation';
+import styles from './CatalogPicker.module.scss';
+
+/** One selectable entry in a CatalogPicker. */
+export interface CatalogPickerItem {
+  /** Stable id passed to `onSelect`. Unique within `items`. */
+  id: string;
+  /** Visible title and the option's accessible name. Searched. */
+  title: string;
+  /** Optional muted description (clamped to 2 lines). Searched; also the option's description. */
+  description?: string;
+  /** Category id (matches a `CatalogPickerCategory.id`) used by the pill filter. */
+  category?: string;
+  /** Extra search terms (not rendered). */
+  tags?: string[];
+  /** Optional badge node (e.g. `<Badge>New</Badge>`) shown on the card. */
+  badge?: ReactNode;
+  /** Optional preview node shown at the top of the card — typically `<WidgetPreview variant>`. */
+  preview?: ReactNode;
+  /**
+   * Marks the item unavailable (e.g. "Already on dashboard", "No permission"). It stays
+   * visible and focusable but dimmed, `aria-disabled`, and `onSelect` is not called; the
+   * reason is shown as text and added to the option's description.
+   */
+  disabledReason?: string;
+}
+
+/** A category pill. */
+export interface CatalogPickerCategory {
+  /** Matches `CatalogPickerItem.category`. */
+  id: string;
+  /** Visible pill label. */
+  label: string;
+}
+
+export interface CatalogPickerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+  /** The catalog. Rendered in the given order. */
+  items: CatalogPickerItem[];
+  /** Category pills (after a leading localized "All"). Omit or pass `[]` for no pills. */
+  categories?: CatalogPickerCategory[];
+  /** Called with the item id when an AVAILABLE item is clicked or activated with Enter/Space. */
+  onSelect: (id: string) => void;
+  /** Accessible name of the results listbox, e.g. "Widget catalog". Required. */
+  label: string;
+}
+
+const ALL = '';
+
+function matches(item: CatalogPickerItem, q: string) {
+  if (!q) return true;
+  return [item.title, item.description ?? '', ...(item.tags ?? [])].some((s) =>
+    s.toLocaleLowerCase().includes(q),
+  );
+}
+
+/**
+ * Searchable, category-filterable card grid for picking one item from a catalog (e.g. an "Add widget" drawer).
+ * @see docs/components/CatalogPicker.md
+ */
+// {...rest} last (Pattern A) so the consumer can add data-* / style to the root.
+export const CatalogPicker = forwardRef<HTMLDivElement, CatalogPickerProps>(function CatalogPicker(
+  { items, categories, onSelect, label, className, ...rest },
+  ref,
+) {
+  const t = useTranslation();
+  const id = useId();
+  const listboxId = `${id}-listbox`;
+  const [query, setQuery] = useState('');
+  const [category, setCategory] = useState(ALL);
+  const [active, setActive] = useState(0);
+  const searchRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+  const sentinelRef = useRef<HTMLSpanElement>(null);
+  const toolbarRef = useRef<HTMLDivElement>(null);
+  const optionRefs = useRef<Array<HTMLDivElement | null>>([]);
+
+  // Sticky "stuck" detection: a 0-flow sentinel at the root's top edge leaves the nearest
+  // scrollable ancestor's viewport exactly when the toolbar pins. Drives the top-bleed
+  // pseudo only while pinned. No IntersectionObserver (jsdom/old browsers) = no bleed.
+  useEffect(() => {
+    const sentinel = sentinelRef.current;
+    const toolbar = toolbarRef.current;
+    if (!sentinel || !toolbar || typeof IntersectionObserver === 'undefined') return;
+    let scroller: HTMLElement | null = sentinel.parentElement;
+    while (scroller && !/(auto|scroll)/.test(getComputedStyle(scroller).overflowY)) {
+      scroller = scroller.parentElement;
+    }
+    // sticky pins at the scroller's content-box top; the IO root is its padding box.
+    const padTop = scroller ? parseFloat(getComputedStyle(scroller).paddingTop) || 0 : 0;
+    const io = new IntersectionObserver(
+      ([entry]) => {
+        const stuck =
+          !entry.isIntersecting && entry.boundingClientRect.top < (entry.rootBounds?.top ?? 0);
+        if (stuck) toolbar.setAttribute('data-stuck', '');
+        else toolbar.removeAttribute('data-stuck');
+      },
+      { root: scroller, rootMargin: `-${padTop}px 0px 0px 0px` },
+    );
+    io.observe(sentinel);
+    return () => io.disconnect();
+  }, []);
+
+  // Escape in a non-empty search clears it instead of closing the enclosing Drawer/Modal.
+  // Their Escape listener is document-capture, which runs before any element/React handler,
+  // so intercept at window-capture and mark the press consumed (#274).
+  const hasQuery = query !== '';
+  useEffect(() => {
+    if (!hasQuery) return;
+    const onKey = (e: globalThis.KeyboardEvent) => {
+      if (e.key !== 'Escape' || e.target !== searchRef.current) return;
+      overlayStack.consumeEscape(e);
+      e.preventDefault();
+      setQuery('');
+    };
+    window.addEventListener('keydown', onKey, true);
+    return () => window.removeEventListener('keydown', onKey, true);
+  }, [hasQuery]);
+
+  const q = query.trim().toLocaleLowerCase();
+  const visible = useMemo(
+    () => items.filter((it) => (category === ALL || it.category === category) && matches(it, q)),
+    [items, category, q],
+  );
+  // Roving target resets to the first result whenever the filter changes.
+  const filterKey = `${category}\u0000${q}`;
+  const [prevFilterKey, setPrevFilterKey] = useState(filterKey);
+  if (filterKey !== prevFilterKey) {
+    setPrevFilterKey(filterKey);
+    setActive(0);
+  }
+  const current = Math.min(active, Math.max(visible.length - 1, 0));
+
+  // If the focused option vanishes (items prop shrank to nothing) focus would drop to <body>.
+  const focusInList = useRef(false);
+  const noneVisible = visible.length === 0;
+  useLayoutEffect(() => {
+    if (noneVisible && focusInList.current) {
+      focusInList.current = false;
+      searchRef.current?.focus();
+    }
+  }, [noneVisible]);
+
+  const focusOption = (i: number) => {
+    setActive(i);
+    optionRefs.current[i]?.focus();
+  };
+
+  const columns = () => {
+    const el = listRef.current;
+    if (!el) return 1;
+    const tracks = getComputedStyle(el).gridTemplateColumns.split(' ').filter(Boolean).length;
+    return Math.max(tracks, 1);
+  };
+
+  const select = (item: CatalogPickerItem) => {
+    if (!item.disabledReason) onSelect(item.id);
+  };
+
+  const onOptionKeyDown = (e: KeyboardEvent<HTMLDivElement>, i: number) => {
+    const last = visible.length - 1;
+    const rtl = listRef.current ? getComputedStyle(listRef.current).direction === 'rtl' : false;
+    const cols = columns();
+    let next: number | null = null;
+    switch (e.key) {
+      case 'ArrowRight':
+        next = Math.min(i + (rtl ? -1 : 1), last);
+        break;
+      case 'ArrowLeft':
+        next = Math.max(i + (rtl ? 1 : -1), 0);
+        break;
+      case 'ArrowDown':
+        next = Math.min(i + cols, last);
+        break;
+      case 'ArrowUp':
+        if (i - cols < 0) {
+          e.preventDefault();
+          searchRef.current?.focus();
+          return;
+        }
+        next = i - cols;
+        break;
+      case 'Home':
+        next = 0;
+        break;
+      case 'End':
+        next = last;
+        break;
+      case 'Enter':
+      case ' ':
+        e.preventDefault();
+        select(visible[i]);
+        return;
+      default:
+        return;
+    }
+    e.preventDefault();
+    focusOption(Math.max(next, 0));
+  };
+
+  return (
+    <div ref={ref} className={clsx(styles.root, className)} {...rest}>
+      <span ref={sentinelRef} aria-hidden="true" className={styles.sentinel} />
+      <div ref={toolbarRef} className={styles.toolbar}>
+        <div className={styles.search}>
+          <Search size={16} aria-hidden className={styles.searchIcon} />
+          <Input
+            ref={searchRef}
+            type="search"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            onFocus={() => {
+              focusInList.current = false;
+            }}
+            placeholder={t('catalogPicker.search')}
+            aria-label={t('catalogPicker.search')}
+            aria-controls={visible.length > 0 ? listboxId : undefined}
+            className={styles.searchInput}
+            onKeyDown={(e) => {
+              if (e.key === 'ArrowDown' && visible.length > 0) {
+                e.preventDefault();
+                focusOption(0);
+              }
+            }}
+          />
+        </div>
+
+        {categories && categories.length > 0 && (
+          <div
+            role="radiogroup"
+            aria-label={t('catalogPicker.categories')}
+            className={styles.pills}
+          >
+            {[{ id: ALL, label: t('catalogPicker.all') }, ...categories].map((c) => (
+              <label key={c.id || '__all'} className={styles.pill}>
+                <input
+                  type="radio"
+                  name={`${id}-category`}
+                  className={styles.pillInput}
+                  checked={category === c.id}
+                  onChange={() => setCategory(c.id)}
+                />
+                <span className={styles.pillLabel}>{c.label}</span>
+              </label>
+            ))}
+          </div>
+        )}
+
+        <div role="status" className={styles.count}>
+          {t('catalogPicker.resultCount', { count: visible.length })}
+        </div>
+      </div>
+
+      {visible.length === 0 ? (
+        <EmptyState size="sm" title={t('catalogPicker.noMatches')} />
+      ) : (
+        <div ref={listRef} id={listboxId} role="listbox" aria-label={label} className={styles.grid}>
+          {visible.map((item, i) => {
+            const descId = `${id}-d-${i}`;
+            const reasonId = `${id}-r-${i}`;
+            const badgeId = `${id}-b-${i}`;
+            const describedBy =
+              [
+                item.description && descId,
+                item.badge != null && badgeId,
+                item.disabledReason && reasonId,
+              ]
+                .filter(Boolean)
+                .join(' ') || undefined;
+            return (
+              <div
+                key={item.id}
+                ref={(el) => {
+                  optionRefs.current[i] = el;
+                }}
+                role="option"
+                aria-selected={false}
+                aria-disabled={item.disabledReason ? true : undefined}
+                aria-labelledby={`${id}-t-${i}`}
+                aria-describedby={describedBy}
+                tabIndex={i === current ? 0 : -1}
+                className={styles.option}
+                onClick={() => select(item)}
+                onKeyDown={(e) => onOptionKeyDown(e, i)}
+                onFocus={() => {
+                  focusInList.current = true;
+                  setActive(i);
+                }}
+                onBlur={(e) => {
+                  if (e.relatedTarget) focusInList.current = false;
+                }}
+              >
+                {item.preview != null && <div className={styles.preview}>{item.preview}</div>}
+                <div className={styles.body}>
+                  <div className={styles.titleRow}>
+                    <span id={`${id}-t-${i}`} className={styles.title}>
+                      {item.title}
+                    </span>
+                    {item.badge != null && (
+                      <span id={badgeId} className={styles.badge}>
+                        {item.badge}
+                      </span>
+                    )}
+                  </div>
+                  {item.description && (
+                    <span id={descId} className={styles.description}>
+                      {item.description}
+                    </span>
+                  )}
+                  {item.disabledReason && (
+                    <span id={reasonId} className={styles.reason}>
+                      {item.disabledReason}
+                    </span>
+                  )}
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+});

package/src/components/CatalogPicker/index.ts

@@ -0,0 +1,2 @@
+export { CatalogPicker } from './CatalogPicker';
+export type { CatalogPickerProps, CatalogPickerItem, CatalogPickerCategory } from './CatalogPicker';