@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/Select/context.ts

@@ -0,0 +1,101 @@
+import { createContext, useContext, type ReactNode, type RefObject } from 'react';
+import type { SelectOption, FlatRow } from './utils-types';
+
+/**
+ * Internal context published by `<Select>` to its subcomponents (Trigger,
+ * Listbox, future ChipsInputTrigger, etc.). Not part of the public API —
+ * all consumer-facing customization happens through `SelectProps`.
+ *
+ * The shape includes fields that some phases don't yet populate (e.g.
+ * `loading`, `error`, render escape hatches, `onCreate`). Those are wired
+ * in later phases; right now they're declared so subcomponents written
+ * against the full interface don't need to grow new optional reads later.
+ */
+export interface SelectContextValue<T = unknown> {
+  // ─── mode flags ───────────────────────────────────────────────────────────
+  multiple: boolean;
+  searchable: boolean;
+  creatable: boolean;
+  triggerDisplay: 'chips' | 'summary';
+
+  // ─── data ─────────────────────────────────────────────────────────────────
+  /**
+   * Currently-rendered rows. When `searchable`, this is the filtered set;
+   * otherwise identical to `allRows`. Phase 2 has no filter yet, so the
+   * two are the same.
+   */
+  rows: FlatRow<T>[];
+  /**
+   * The full flattened option list, independent of any active query. Used
+   * by chip-mode renderers to resolve labels for selected values that have
+   * been filtered out of the visible list.
+   */
+  allRows: FlatRow<T>[];
+  loading: boolean;
+  error: Error | null;
+  /**
+   * For an async Select, the query its current rows belong to; `null` before
+   * the first settle. `undefined` when there is no `loadOptions` at all.
+   *
+   * The empty-state announcement needs this: `loading` is FALSE for the whole
+   * debounce window, during which the rows are still the previous query's — so
+   * announcing on `!loading && rows.length === 0` said "No options." before the
+   * first fetch started, and "No results for X" about a search never run.
+   */
+  loadedQuery?: string | null;
+
+  // ─── value ────────────────────────────────────────────────────────────────
+  value: string | string[];
+  setValue: (next: string | string[]) => void;
+  toggleValue: (v: string) => void;
+
+  // ─── open ─────────────────────────────────────────────────────────────────
+  open: boolean;
+  setOpen: (next: boolean) => void;
+
+  // ─── active (keyboard cursor) ─────────────────────────────────────────────
+  activeIndex: number;
+  setActiveIndex: (i: number) => void;
+
+  // ─── search (only meaningful when `searchable`) ───────────────────────────
+  query: string;
+  setQuery: (q: string) => void;
+
+  // ─── ids ──────────────────────────────────────────────────────────────────
+  listboxId: string;
+  triggerId: string;
+  getOptionId: (value: string) => string;
+  getGroupHeaderId: (label: string) => string;
+
+  // ─── refs ─────────────────────────────────────────────────────────────────
+  triggerRef: RefObject<HTMLElement | null>;
+  triggerRootRef: RefObject<HTMLElement | null>;
+  listboxRef: RefObject<HTMLDivElement | null>;
+
+  // ─── imperative ───────────────────────────────────────────────────────────
+  closeAndFocusTrigger: () => void;
+  retry: () => void;
+
+  // ─── render overrides + onCreate (populated in later phases) ──────────────
+  onCreate?: (label: string) => void;
+  renderOption?: (opt: SelectOption<T>, state: { active: boolean; selected: boolean }) => ReactNode;
+  renderValue?: (opt: SelectOption<T>) => ReactNode;
+  renderTag?: (opt: SelectOption<T>, remove: () => void) => ReactNode;
+  renderEmpty?: (query: string) => ReactNode;
+  renderLoading?: () => ReactNode;
+  renderError?: (err: Error, retry: () => void) => ReactNode;
+}
+
+export const SelectContext = createContext<SelectContextValue | null>(null);
+
+/**
+ * Read the SelectContext. Throws when called outside a `<Select>` so a
+ * misuse (e.g. rendering `<Trigger>` directly) fails loudly during dev.
+ */
+export function useSelectContext<T = unknown>(componentName: string): SelectContextValue<T> {
+  const ctx = useContext(SelectContext);
+  if (!ctx) {
+    throw new Error(`<Select> internals (${componentName}) must be rendered inside <Select>.`);
+  }
+  return ctx as SelectContextValue<T>;
+}

package/src/components/Select/emptyStateText.ts

@@ -0,0 +1,19 @@
+import type { useTranslation } from '../../i18n/useTranslation';
+
+/**
+ * The empty-state sentence, built in ONE place.
+ *
+ * The visible row renders it and the Listbox's status region announces it, and
+ * the row's copy is `aria-hidden` so a reader meets it once. That means
+ * nothing compares the two: the reachable-count assertion is satisfied by the
+ * region alone, so if the two constructions drifted, what is shown and what is
+ * spoken would differ with every test still green.
+ */
+export function emptyStateText(
+  t: ReturnType<typeof useTranslation>,
+  query: string | undefined,
+): string {
+  return query && query.trim() !== ''
+    ? t('select.noResultsFor', { query })
+    : `${t('select.noOptions')}.`;
+}

package/src/components/Select/index.ts

@@ -0,0 +1,9 @@
+export { Select } from './Select';
+export type {
+  SelectProps,
+  SelectOption,
+  SelectGroup,
+  SelectOptions,
+  SelectSize,
+  SelectTriggerDisplay,
+} from './Select';

package/src/components/Select/useSelectState.ts

@@ -0,0 +1,157 @@
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+
+export interface UseSelectStateArgs {
+  /** When `true`, value is a `string[]`; when `false`, a `string`. */
+  multiple: boolean;
+  /** Controlled value. When defined, internal state is bypassed. */
+  value?: string | string[];
+  /** Initial value when uncontrolled. Falls back to `''` (single) / `[]` (multi). */
+  defaultValue?: string | string[];
+  /** Fires on every commit, including in controlled mode (where state stays put). */
+  onChange?: (value: string | string[]) => void;
+  /** Controlled open. When defined, internal open state is bypassed. */
+  open?: boolean;
+  /** Initial open when uncontrolled. Defaults to `false`. */
+  defaultOpen?: boolean;
+  /** Fires on every commit to open state, including in controlled mode. */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * Return shape of `useSelectState`, parameterized by the value type so
+ * overloads can narrow `value` / `setValue` based on `multiple`.
+ */
+export interface UseSelectStateReturn<V extends string | string[] = string | string[]> {
+  /** Current value — `string` in single mode, `string[]` in multi. */
+  value: V;
+  /** Replace the entire selection. */
+  setValue: (next: V) => void;
+  /**
+   * Multi: toggle membership of `v` (add when missing, remove when present).
+   * Single: equivalent to `setValue(v)`.
+   */
+  toggleValue: (v: string) => void;
+  /** Current open state. */
+  open: boolean;
+  /** Set open state. */
+  setOpen: (next: boolean) => void;
+}
+
+interface StateRefShape {
+  multiple: boolean;
+  isControlledValue: boolean;
+  isControlledOpen: boolean;
+  currentValue: string | string[];
+  onChange?: (value: string | string[]) => void;
+  onOpenChange?: (open: boolean) => void;
+}
+
+const emptyValue = (multiple: boolean): string | string[] => (multiple ? [] : '');
+
+/**
+ * Combined reducer-like state for Select: controlled/uncontrolled value
+ * and open state, plus a multi-aware `toggleValue` helper.
+ *
+ * Controlled vs. uncontrolled is decided per-axis (value, open):
+ *  - `value !== undefined` → controlled. `setValue` / `toggleValue` fire
+ *    `onChange` but do NOT update internal state.
+ *  - `open !== undefined` → controlled. `setOpen` fires `onOpenChange`
+ *    but does NOT update internal state.
+ *
+ * @example
+ *   const { value, setValue } = useSelectState({ multiple: false });
+ *   // value is typed as `string`
+ *
+ * @example
+ *   const { value, setValue } = useSelectState({ multiple: true });
+ *   // value is typed as `string[]`
+ */
+export function useSelectState(
+  args: UseSelectStateArgs & { multiple: false },
+): UseSelectStateReturn<string>;
+export function useSelectState(
+  args: UseSelectStateArgs & { multiple: true },
+): UseSelectStateReturn<string[]>;
+export function useSelectState(args: UseSelectStateArgs): UseSelectStateReturn;
+// Implementation signature: intentionally permissive — public callers see one
+// of the three overloads above. `UseSelectStateReturn<string | string[]>`
+// would not be a valid supertype of `UseSelectStateReturn<string>` because
+// `setValue` is contravariant in V.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useSelectState(args: UseSelectStateArgs): UseSelectStateReturn<any> {
+  const { multiple, value, defaultValue, onChange, open, defaultOpen, onOpenChange } = args;
+
+  const [internalValue, setInternalValue] = useState<string | string[]>(
+    () => defaultValue ?? emptyValue(multiple),
+  );
+  const [internalOpen, setInternalOpen] = useState<boolean>(defaultOpen ?? false);
+
+  const isControlledValue = value !== undefined;
+  const isControlledOpen = open !== undefined;
+
+  // Stable refs so the returned callbacks have stable identity even though
+  // they read fresh values on every invocation. The ref is seeded with the
+  // initial values and refreshed in a layout effect — assigning during render
+  // would violate React's render-purity rule under StrictMode / concurrent
+  // rendering (a discarded render could mutate state observed by a
+  // not-yet-committed update).
+  const stateRef = useRef<StateRefShape>({
+    multiple,
+    isControlledValue,
+    isControlledOpen,
+    currentValue: isControlledValue ? (value as string | string[]) : internalValue,
+    onChange,
+    onOpenChange,
+  });
+  useLayoutEffect(() => {
+    stateRef.current = {
+      multiple,
+      isControlledValue,
+      isControlledOpen,
+      currentValue: isControlledValue ? (value as string | string[]) : internalValue,
+      onChange,
+      onOpenChange,
+    };
+  });
+
+  const setValue = useCallback((next: string | string[]) => {
+    const s = stateRef.current;
+    if (!s.isControlledValue) {
+      setInternalValue(next);
+    }
+    s.onChange?.(next);
+  }, []);
+
+  const toggleValue = useCallback((v: string) => {
+    const s = stateRef.current;
+    if (!s.multiple) {
+      if (!s.isControlledValue) {
+        setInternalValue(v);
+      }
+      s.onChange?.(v);
+      return;
+    }
+    const current = (s.currentValue as string[]) ?? [];
+    const next = current.includes(v) ? current.filter((x) => x !== v) : [...current, v];
+    if (!s.isControlledValue) {
+      setInternalValue(next);
+    }
+    s.onChange?.(next);
+  }, []);
+
+  const setOpen = useCallback((next: boolean) => {
+    const s = stateRef.current;
+    if (!s.isControlledOpen) {
+      setInternalOpen(next);
+    }
+    s.onOpenChange?.(next);
+  }, []);
+
+  return {
+    value: isControlledValue ? (value as string | string[]) : internalValue,
+    setValue,
+    toggleValue,
+    open: isControlledOpen ? (open as boolean) : internalOpen,
+    setOpen,
+  };
+}

package/src/components/Select/utils-types.ts

@@ -0,0 +1,7 @@
+// Tiny re-export module that breaks the circular import that would
+// otherwise exist between `Select.tsx` (which imports the SelectContext
+// from `./context`) and `context.ts` (which needs `SelectOption` etc.
+// declared in `Select.tsx`). Subcomponents and `context.ts` import these
+// types from here rather than from `./Select` directly.
+export type { SelectOption, SelectGroup, SelectOptions } from './Select';
+export type { FlatRow } from './utils';

package/src/components/Select/utils.ts

@@ -0,0 +1,122 @@
+import type { SelectGroup, SelectOption, SelectOptions } from './Select';
+
+/**
+ * Discriminator for `SelectOptions`: returns `true` when the input is a
+ * `SelectGroup[]` (i.e. the first element exposes an `options` array),
+ * `false` for a flat `SelectOption[]` and for an empty list.
+ *
+ * Mixing groups and flat options at the same level is not supported;
+ * only the first element is inspected.
+ */
+export function isGrouped<T>(opts: SelectOptions<T>): opts is SelectGroup<T>[] {
+  if (opts.length === 0) return false;
+  const first = opts[0] as SelectOption<T> | SelectGroup<T>;
+  return Array.isArray((first as SelectGroup<T>).options);
+}
+
+/**
+ * One row in the flattened render list — either a non-selectable group
+ * header or a selectable option. `groupLabel` is set on option rows when
+ * they belong to a group, so the renderer can group them visually or in
+ * `aria-` attributes without re-walking the original tree.
+ */
+export type FlatRow<T = unknown> =
+  | { kind: 'header'; label: string }
+  | { kind: 'option'; option: SelectOption<T>; groupLabel?: string };
+
+/**
+ * Walk `SelectOptions` into a flat array of render rows.
+ *
+ * - Flat input → one `'option'` row per option (no `groupLabel`).
+ * - Grouped input → for each group: one `'header'` row then one
+ *   `'option'` row per member (each tagged with its `groupLabel`).
+ */
+export function flattenOptions<T>(opts: SelectOptions<T>): FlatRow<T>[] {
+  if (!isGrouped(opts)) {
+    return (opts as SelectOption<T>[]).map((option) => ({ kind: 'option', option }));
+  }
+  const rows: FlatRow<T>[] = [];
+  for (const group of opts) {
+    rows.push({ kind: 'header', label: group.label });
+    for (const option of group.options) {
+      rows.push({ kind: 'option', option, groupLabel: group.label });
+    }
+  }
+  return rows;
+}
+
+/**
+ * Find a single option by `value`. Walks groups when the input is
+ * grouped. Returns `null` when no match exists.
+ */
+export function findOption<T>(opts: SelectOptions<T>, value: string): SelectOption<T> | null {
+  if (isGrouped(opts)) {
+    for (const group of opts) {
+      const hit = group.options.find((o) => o.value === value);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  return (opts as SelectOption<T>[]).find((o) => o.value === value) ?? null;
+}
+
+/**
+ * Find every option whose `value` appears in `values`. The returned
+ * array preserves the order of options in `opts` (NOT the order of the
+ * `values` argument), and values with no match are skipped silently —
+ * the result contains no nulls and no duplicates beyond what's in `opts`.
+ */
+export function findOptions<T>(opts: SelectOptions<T>, values: string[]): SelectOption<T>[] {
+  if (values.length === 0) return [];
+  const wanted = new Set(values);
+  const out: SelectOption<T>[] = [];
+  if (isGrouped(opts)) {
+    for (const group of opts) {
+      for (const option of group.options) {
+        if (wanted.has(option.value)) out.push(option);
+      }
+    }
+    return out;
+  }
+  for (const option of opts as SelectOption<T>[]) {
+    if (wanted.has(option.value)) out.push(option);
+  }
+  return out;
+}
+
+/**
+ * Returns true if any option in `opts` has a label case-insensitively
+ * matching `query` (after trim). Used by the creatable Select to decide
+ * whether to render a "+ Create" row — when the typed query already
+ * matches an existing label, the create row would be a no-op duplicate.
+ *
+ * The empty / whitespace-only query case returns `false` so the create
+ * row never appears for blank input.
+ */
+export function hasExactLabelMatch<T>(opts: SelectOptions<T>, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (q === '') return false;
+  if (!isGrouped(opts)) {
+    return opts.some((o) => o.label.toLowerCase() === q);
+  }
+  for (const g of opts) {
+    if (g.options.some((o) => o.label.toLowerCase() === q)) return true;
+  }
+  return false;
+}
+
+/**
+ * Returns true if an option carries the internal `__create` sentinel on
+ * its `data` payload. The sentinel is injected by `<Select>` when it
+ * synthesises the "+ Create" row, and the listbox + Trigger keyboard
+ * handlers branch on it to fire `onCreate` instead of the normal
+ * select/toggle flow.
+ */
+export function isCreateRow<T>(opt: { data?: T }): boolean {
+  return (
+    typeof opt.data === 'object' &&
+    opt.data !== null &&
+    Object.prototype.hasOwnProperty.call(opt.data, '__create') &&
+    (opt.data as { __create?: boolean }).__create === true
+  );
+}

package/src/components/SettingRow/SettingRow.module.scss

@@ -0,0 +1,166 @@
+@use './SettingRow.tokens';
+@use '../_internal/collapse' as bp;
+
+// Two columns: label | control. The label column is a length resolved from
+// --setting-row-label-width, so sibling rows align without a subgrid.
+// minmax(0, …) on both tracks so a long description or a wide control
+// shrinks instead of overflowing the List.
+.row {
+  display: grid;
+  grid-template-columns:
+    minmax(0, var(--setting-row-label-width))
+    minmax(0, 1fr);
+  column-gap: var(--setting-row-column-gap);
+  align-items: start;
+}
+
+.term,
+.control {
+  display: flex;
+  flex-direction: column;
+  gap: var(--setting-row-stack-gap);
+  min-width: 0;
+}
+
+// Label line — the <label> plus any adornment, which sits OUTSIDE the <label>
+// so it never joins the control's accessible name.
+.labelLine {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--setting-row-trailing-gap);
+}
+
+.label {
+  font-size: var(--setting-row-label-font-size);
+  font-weight: var(--setting-row-label-font-weight);
+  line-height: var(--line-height-tight);
+  color: var(--setting-row-label-fg);
+}
+
+.required {
+  color: var(--color-danger);
+}
+
+// Control + its trailing adornments on one line. wrap so a narrow row drops
+// the adornments below instead of overflowing.
+.controlLine {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--setting-row-trailing-gap);
+}
+
+// The control's own wrapper — sized by controlWidth, `trailing` sits
+// outside it on .controlLine so controlWidth never sizes the adornments.
+// They share the line only while both fit: in a narrow column a wide step
+// (md) plus `trailing` wraps `trailing` onto a second line. This wrapper
+// is created AFTER wire() has already cloned the child and injected id /
+// aria-labelledby / aria-describedby / invalid / required, so it is never
+// the cloneElement target — that's also why a consumer-side <Constrain>
+// was ruled out in favor of controlWidth.
+// controlWidth is a WIDTH, not only a cap (#549): the slot is a
+// shrink-to-fit flex item, so a max-width alone let each `width: 100%`
+// control resolve to its own intrinsic size — a number input's depends on
+// its `max` attribute in Chromium — and rows in one List came out ragged.
+// max-width: 100% still lets a narrow column shrink it.
+.controlSlot {
+  min-width: 0;
+}
+
+.controlSlot[data-control-width='xs'] {
+  width: var(--setting-row-control-width-xs);
+  max-width: 100%;
+}
+
+.controlSlot[data-control-width='sm'] {
+  width: var(--setting-row-control-width-sm);
+  max-width: 100%;
+}
+
+.controlSlot[data-control-width='md'] {
+  width: var(--setting-row-control-width-md);
+  max-width: 100%;
+}
+
+// trailing's own flex item, sized to its content rather than the shared
+// line. Most DS controls (Select included) are `width: 100%`, which would
+// otherwise resolve against .controlLine's full content box — the entire
+// control column — and force a wrap no matter how much room there is.
+// `width: max-content` makes a 100%-wide child measure against ITS OWN box
+// instead; `max-width: 100%` still lets it shrink rather than overflow.
+.trailing {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--setting-row-trailing-gap);
+  width: max-content;
+  max-width: 100%;
+  min-width: 0;
+}
+
+// --- SettingRow.List ---------------------------------------------------
+// The List owns vertical rhythm and dividers — hard rule 4 keeps them off
+// the row, which is the child.
+.list {
+  display: flex;
+  flex-direction: column;
+}
+
+.list[data-spacing='sm'] > [data-setting-row] {
+  padding-block: var(--setting-row-padding-y-sm);
+}
+
+.list[data-spacing='md'] > [data-setting-row] {
+  padding-block: var(--setting-row-padding-y-md);
+}
+
+.list[data-spacing='lg'] > [data-setting-row] {
+  padding-block: var(--setting-row-padding-y-lg);
+}
+
+.list[data-dividers='true'] > [data-setting-row] + [data-setting-row] {
+  border-top: var(--border-width) solid var(--setting-row-divider-color);
+}
+
+// --- collapseBelow -----------------------------------------------------
+// Unlike Grid/Split, where collapse is opt-in, `collapseBelow` defaults to
+// 'sm' — so every List is a size container BY DEFAULT. The label track IS
+// `minmax(0, …)` like the control track (see the .row comment above) — it
+// shrinks rather than overflows — but below the collapseBelow threshold
+// (480/640/768px, see collapse.ts) that shrinking crushes the control
+// column instead of giving it room, which is a worse failure than the
+// column simply overflowing would be. Collapsing to one stacked column below
+// the threshold is the fix, and it is the right default rather than a
+// nice-to-have. `collapseBelow={false}` opts a List out of containment
+// entirely (below, .collapsible is then never applied) — the escape hatch
+// for a shrink-to-fit parent, matching Grid/Split's opt-in-by-omission
+// shape from the other direction. The cost when containment IS on (mirrors
+// Split.module.scss:86-87): container-type: inline-size zeroes the
+// element's intrinsic-width contribution. The queries target the ROWS,
+// which are descendants — an element is never matched by a query against
+// its own container (same constraint Grid and Split document).
+.collapsible {
+  container-type: inline-size;
+}
+
+@container (max-width: #{bp.$collapse-sm}) {
+  .collapsible.collapseSm > [data-setting-row] {
+    grid-template-columns: minmax(0, 1fr);
+    row-gap: var(--setting-row-stack-gap);
+  }
+}
+
+@container (max-width: #{bp.$collapse-md}) {
+  .collapsible.collapseMd > [data-setting-row] {
+    grid-template-columns: minmax(0, 1fr);
+    row-gap: var(--setting-row-stack-gap);
+  }
+}
+
+@container (max-width: #{bp.$collapse-lg}) {
+  .collapsible.collapseLg > [data-setting-row] {
+    grid-template-columns: minmax(0, 1fr);
+    row-gap: var(--setting-row-stack-gap);
+  }
+}

package/src/components/SettingRow/SettingRow.tokens.scss

@@ -0,0 +1,37 @@
+// SettingRow.tokens.scss — Component-scoped tokens for <SettingRow> and
+// <SettingRow.List>. Covers the label column width, the two-column gap,
+// label typography, per-spacing row padding, and the divider color.
+// No hex literals here — a component token that duplicates a semantic value
+// is a structure.test.ts failure.
+:root {
+  // Label column — a LENGTH, not max-content, so every row in a List resolves
+  // the same column without a subgrid.
+  --setting-row-label-width: 16rem;
+
+  // Gap between the label column and the control column
+  --setting-row-column-gap: var(--space-4);
+
+  // Gap between stacked pieces inside each column
+  --setting-row-stack-gap: var(--space-1);
+
+  // Gap between the control and its trailing adornments
+  --setting-row-trailing-gap: var(--space-2);
+
+  // Label typography
+  --setting-row-label-font-size: var(--font-size-sm);
+  --setting-row-label-font-weight: var(--font-weight-medium);
+  --setting-row-label-fg: var(--color-fg);
+
+  // Spacing variants — padding-block per row, set by the List
+  --setting-row-padding-y-sm: var(--space-2);
+  --setting-row-padding-y-md: var(--space-3);
+  --setting-row-padding-y-lg: var(--space-4);
+
+  // Divider between rows when the List sets dividers
+  --setting-row-divider-color: var(--color-border);
+
+  // Control cell caps — mirror Constrain's measure scale
+  --setting-row-control-width-xs: var(--measure-xs);
+  --setting-row-control-width-sm: var(--measure-sm);
+  --setting-row-control-width-md: var(--measure-md);
+}