@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/SettingRow/SettingRow.tsx

@@ -0,0 +1,242 @@
+import { forwardRef, type CSSProperties, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { Text } from '../Text';
+import { hasContent, useFieldWiring, type FieldRenderProps } from '../_internal/fieldWiring';
+import { type CollapseBreakpoint } from '../_internal/collapse';
+import styles from './SettingRow.module.scss';
+
+/** Width of the control only (not its trailing adornments), capped at the column. A subset of `<Constrain>`'s measure scale. */
+export type SettingRowControlWidth = 'auto' | 'xs' | 'sm' | 'md';
+
+export interface SettingRowProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** Label text. Renders a `<label htmlFor>` that names the control. Required — an empty or falsy value (e.g. `0`, `''`, `[]`, `<></>`) renders no `<label>` at all; see the anti-pattern below. */
+  label: ReactNode;
+  /**
+   * Badges / chips on the label line, rendered as a SIBLING of the `<label>`.
+   * Deliberately outside it: label content becomes the control's accessible
+   * name, so a provenance badge placed inside makes the input announce
+   * "Seats From plan".
+   */
+  labelAdornment?: ReactNode;
+  /** Helper text under the label, in the label column. Linked via `aria-describedby`. */
+  description?: ReactNode;
+  /**
+   * Width of the control only — `trailing` is not sized by it. Default
+   * `'auto'` — the control's intrinsic width. Every row using the same step
+   * gets the same control width (capped at the column, so a narrow container
+   * still shrinks it), which is what keeps controls aligned down a
+   * `<SettingRow.List>`. Intended for controls that stretch to `width: 100%`
+   * (`Input`, `Select`); a fixed-size control (`Switch`) does not grow — the
+   * slot just reserves the width.
+   *
+   * `trailing` stays on the control's line only while both fit: in a narrow
+   * column a wide step (`'md'`) plus `trailing` can wrap `trailing` onto a
+   * second line. Use a smaller step if that matters.
+   */
+  controlWidth?: SettingRowControlWidth;
+  /**
+   * Content after the control on the same line — a mode select, a state
+   * badge, a reset button. `controlWidth` does NOT apply here — it only sizes
+   * the main control. A control that sizes itself to `width: 100%` (`Select`,
+   * `Input`, `Textarea`) fills the ENTIRE trailing group and pushes any other
+   * adornment onto a second line; wrap it in `<Constrain width="xs">` (or
+   * another named step) to size it instead. Plain truthiness check: an empty
+   * array or fragment still renders an empty wrapper (a stray gap) — pass
+   * `undefined` for "none".
+   */
+  trailing?: ReactNode;
+  /**
+   * Block under the control column — a usage meter, a caveat, a preview.
+   * Fills the control column's full width; cap a meter with `<Constrain>` —
+   * safe here, `footer` is not the wired child.
+   */
+  footer?: ReactNode;
+  /**
+   * Error message. Takes over `aria-describedby` and flips the control to
+   * `invalid`. Unlike `<Field>`, the `description` stays VISIBLE alongside it —
+   * the two sit in different columns, so an invalid value is no reason to
+   * remove the explanation of what the setting is.
+   *
+   * **Not announced, deliberately** — `aria-describedby` is read on focus, so
+   * the form owns the submit-time summary. Same reasoning as `<Field error>`.
+   */
+  error?: ReactNode;
+  /** Marks the row required: shows `*` and injects `required` onto the control. */
+  required?: boolean;
+  /** Explicit control id. The row owns the id by default so the label always matches. */
+  id?: string;
+  /** A single control element (auto-wired) or a render-prop `(field) => ReactNode`. */
+  children: ReactNode | ((field: FieldRenderProps) => ReactNode);
+}
+
+/**
+ * One row of a settings screen: label and description in a shared left column, control and footer on the right.
+ * @see docs/components/SettingRow.md
+ */
+const SettingRowRoot = forwardRef<HTMLDivElement, SettingRowProps>(function SettingRow(
+  {
+    label,
+    labelAdornment,
+    description,
+    controlWidth = 'auto',
+    trailing,
+    footer,
+    error,
+    required,
+    id,
+    className,
+    children,
+    ...rest
+  },
+  ref,
+) {
+  // Single source of truth for each "is there an X" predicate — round 5
+  // hoisted only `hasLabel` (it had two consumers and had already diverged);
+  // round 6 did the same for `hasDescription`/`hasError`/`hasRequired`,
+  // still each computed twice (once for the wiring call, once for the
+  // matching render gate). Round 7: `hasLabel`/`hasDescription`/`hasError`
+  // now use `hasContent`, not `Boolean` — see that function's doc in
+  // fieldWiring.ts. `hasRequired` stays `Boolean` since `required` is a
+  // plain boolean, not ReactNode content that can be an empty-but-truthy
+  // container.
+  const hasLabel = hasContent(label);
+  const hasDescription = hasContent(description);
+  const hasError = hasContent(error);
+  const hasRequired = Boolean(required);
+  const { controlId, labelId, descriptionId, errorId, wire } = useFieldWiring({
+    id,
+    hasLabel,
+    hasDescription,
+    hasError,
+    required: hasRequired,
+  });
+
+  return (
+    <div ref={ref} data-setting-row="" className={clsx(styles.row, className)} {...rest}>
+      <div className={styles.term}>
+        <div className={styles.labelLine}>
+          {hasLabel && (
+            <label htmlFor={controlId} id={labelId} className={styles.label}>
+              {label}
+              {hasRequired && (
+                <span aria-hidden="true" className={styles.required}>
+                  {' '}
+                  *
+                </span>
+              )}
+            </label>
+          )}
+          {Boolean(labelAdornment) && labelAdornment}
+        </div>
+        {hasDescription && (
+          <Text as="div" id={descriptionId} size="sm" tone="muted">
+            {description}
+          </Text>
+        )}
+      </div>
+      <div className={styles.control}>
+        <div className={styles.controlLine}>
+          <div className={styles.controlSlot} data-control-width={controlWidth}>
+            {wire(children)}
+          </div>
+          {Boolean(trailing) && <div className={styles.trailing}>{trailing}</div>}
+        </div>
+        {Boolean(footer) && footer}
+        {hasError && (
+          <Text as="div" id={errorId} size="sm" tone="danger">
+            {error}
+          </Text>
+        )}
+      </div>
+    </div>
+  );
+});
+SettingRowRoot.displayName = 'SettingRow';
+
+/** Vertical padding per row: `sm` = `--space-2`, `md` = `--space-3`, `lg` = `--space-4`. */
+export type SettingRowListSpacing = 'sm' | 'md' | 'lg';
+
+export interface SettingRowListProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * CSS length for the label column, shared by every row in the list
+   * (e.g. `'18rem'`, `'240px'`). Default `'16rem'` via the
+   * `--setting-row-label-width` token.
+   *
+   * A LENGTH, not `max-content` — rows align because they each resolve the
+   * same value, with no subgrid.
+   */
+  labelWidth?: string;
+  /** 1px border between rows. Default `false`, matching `<DefinitionList>`. */
+  dividers?: boolean;
+  /** Vertical padding per row. Default `'md'`. */
+  spacing?: SettingRowListSpacing;
+  /**
+   * Container width at or below which each row stacks its label column above
+   * its control column. `'sm'` 480px / `'md'` 640px / `'lg'` 768px, measured
+   * against the LIST's own box (a container query, like `<Grid>` and
+   * `<Split>`). Default `'sm'`.
+   *
+   * Pass `false` to opt out of containment entirely — e.g. inside a
+   * shrink-to-fit parent (a `width: max-content` flex item, an inline-block,
+   * a table cell), where `container-type: inline-size` would otherwise zero
+   * the List's intrinsic-width contribution. See the anti-pattern below.
+   */
+  collapseBelow?: CollapseBreakpoint | false;
+  /** The rows. */
+  children: ReactNode;
+}
+
+// Same shape as Grid's `collapseClass` (Grid.tsx:143) — no non-null
+// assertions: types/scss-modules.d.ts types a CSS-module member as `string`.
+const COLLAPSE_CLASS: Record<CollapseBreakpoint, string> = {
+  sm: styles.collapseSm,
+  md: styles.collapseMd,
+  lg: styles.collapseLg,
+};
+
+/**
+ * A list of `<SettingRow>`s that owns the shared label column, vertical rhythm, dividers and narrow-container collapse.
+ * @see docs/components/SettingRow.md
+ */
+const SettingRowList = forwardRef<HTMLDivElement, SettingRowListProps>(function SettingRowList(
+  {
+    labelWidth,
+    dividers = false,
+    spacing = 'md',
+    collapseBelow = 'sm',
+    className,
+    style,
+    children,
+    ...rest
+  },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      data-setting-row-list=""
+      data-spacing={spacing}
+      data-dividers={dividers ? 'true' : undefined}
+      className={clsx(
+        styles.list,
+        collapseBelow !== false && styles.collapsible,
+        collapseBelow !== false && COLLAPSE_CLASS[collapseBelow],
+        className,
+      )}
+      // Custom-property-in-style idiom copied from Grid.tsx:204.
+      style={
+        labelWidth != null
+          ? { ...(style as CSSProperties), ['--setting-row-label-width' as string]: labelWidth }
+          : style
+      }
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+});
+SettingRowList.displayName = 'SettingRowList';
+
+export const SettingRow = Object.assign(SettingRowRoot, {
+  List: SettingRowList,
+});

package/src/components/SettingRow/index.ts

@@ -0,0 +1,7 @@
+export { SettingRow } from './SettingRow';
+export type {
+  SettingRowProps,
+  SettingRowControlWidth,
+  SettingRowListProps,
+  SettingRowListSpacing,
+} from './SettingRow';

package/src/components/Skeleton/Skeleton.module.scss

@@ -0,0 +1,55 @@
+@use './Skeleton.tokens';
+
+.skeleton {
+  display: inline-block;
+  background: var(--skeleton-bg);
+
+  // Prevent text selection — skeletons are decorative.
+  user-select: none;
+
+  // Ensures the inline-block lays out cleanly inside text flow.
+  vertical-align: middle;
+}
+
+.variant-text {
+  border-radius: var(--skeleton-radius-text);
+}
+
+.variant-circular {
+  border-radius: var(--skeleton-radius-circular);
+}
+
+.variant-rectangular {
+  display: block;
+  border-radius: var(--skeleton-radius-rectangular);
+}
+
+// Pulse — opacity cycle. Hardware-accelerated (opacity is a compositor
+// property). 1.5s read as "alive" without being distracting.
+.pulse {
+  animation: skeleton-pulse 1.5s ease-in-out infinite;
+}
+
+@keyframes skeleton-pulse {
+  0% {
+    opacity: var(--skeleton-opacity-high);
+  }
+
+  50% {
+    opacity: var(--skeleton-opacity-low);
+  }
+
+  100% {
+    opacity: var(--skeleton-opacity-high);
+  }
+}
+
+// Respect reduced-motion. Wins over the .pulse rule above purely via
+// source order — both selectors are class-specificity (0,1,0), so the
+// later declaration takes precedence in the cascade. No !important
+// needed.
+@media (prefers-reduced-motion: reduce) {
+  .pulse {
+    animation: none;
+  }
+}

package/src/components/Skeleton/Skeleton.tokens.scss

@@ -0,0 +1,17 @@
+// Skeleton.tokens.scss — Component-scoped tokens for <Skeleton>. Background
+// (the muted block), the per-variant radii (text/circular/rectangular), and
+// the pulse animation's opacity extremes. The 1.5s pulse duration stays raw
+// since motion timings are not tokenized.
+:root {
+  // Block
+  --skeleton-bg: var(--color-bg-muted);
+
+  // Variant radii
+  --skeleton-radius-text: var(--radius-sm);
+  --skeleton-radius-circular: var(--radius-full);
+  --skeleton-radius-rectangular: var(--radius-md);
+
+  // Pulse opacity range
+  --skeleton-opacity-high: var(--opacity-visible);
+  --skeleton-opacity-low: var(--opacity-subtle);
+}

package/src/components/Skeleton/Skeleton.tsx

@@ -0,0 +1,131 @@
+import { forwardRef, type CSSProperties, type HTMLAttributes } from 'react';
+import clsx from 'clsx';
+import { useSkeletonVisibility } from './useSkeletonVisibility';
+import styles from './Skeleton.module.scss';
+
+/** Shape preset. */
+export type SkeletonVariant = 'text' | 'circular' | 'rectangular';
+
+/** Animation style. */
+export type SkeletonAnimation = 'pulse' | 'none';
+
+export interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
+  /**
+   * Shape preset. Defaults to `'text'`.
+   * - `'text'` — inline-block; `height` defaults to `1em` so it sits on text
+   *   baselines. Use inside paragraphs / labels for word-shaped placeholders.
+   * - `'circular'` — `border-radius: 50%`; when only one of `width`/`height`
+   *   is set, the other matches (square). Avatar / icon placeholder.
+   * - `'rectangular'` — block, small radius. Image / card / button placeholder.
+   */
+  variant?: SkeletonVariant;
+
+  /** Explicit width. Number → px, string → as-is (e.g., `'60%'`, `'12rem'`). */
+  width?: number | string;
+
+  /**
+   * Explicit height. Number → px, string → as-is.
+   * Defaults: `text` → `1em`, `circular` → matches `width` (square),
+   * `rectangular` → no default (consumer must size).
+   */
+  height?: number | string;
+
+  /**
+   * Animation. Defaults to `'pulse'`.
+   * - `'pulse'` — opacity 1 → 0.6 → 1, 1.5s ease-in-out infinite.
+   * - `'none'` — static. Use when stacking many skeletons to avoid motion
+   *   overload.
+   *
+   * Regardless of this prop, animation is suppressed when the user has
+   * `prefers-reduced-motion: reduce`.
+   */
+  animation?: SkeletonAnimation;
+
+  /**
+   * Whether the loading placeholder is needed. Defaults to `true`.
+   * Keep Skeleton mounted and drive this prop when using `minDuration`, so
+   * the component can finish its visibility window after loading completes.
+   */
+  loading?: boolean;
+
+  /**
+   * Milliseconds to wait before rendering the placeholder. Defaults to `0`.
+   * A load that finishes inside this window never displays the Skeleton.
+   */
+  delay?: number;
+
+  /**
+   * Minimum milliseconds to remain visible after the placeholder renders.
+   * Defaults to `0`. Prevents a Skeleton that appears just after `delay`
+   * from disappearing again within a frame or two.
+   */
+  minDuration?: number;
+}
+
+function toCssSize(value: number | string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  return typeof value === 'number' ? `${value}px` : value;
+}
+
+/**
+ * Placeholder rectangle for loading states, composed in any layout to mimic the eventual content shape.
+ * @see docs/components/Skeleton.md
+ */
+export const Skeleton = forwardRef<HTMLSpanElement, SkeletonProps>(function Skeleton(
+  {
+    variant = 'text',
+    width,
+    height,
+    animation = 'pulse',
+    loading = true,
+    delay = 0,
+    minDuration = 0,
+    className,
+    style,
+    ...props
+  },
+  ref,
+) {
+  const visible = useSkeletonVisibility(loading, { delay, minDuration });
+
+  // Default height: text → 1em (sits on baseline), circular → matches width
+  // (square), rectangular → undefined (consumer must size).
+  let resolvedHeight: string | undefined = toCssSize(height);
+  if (resolvedHeight === undefined) {
+    if (variant === 'text') resolvedHeight = '1em';
+    else if (variant === 'circular' && width !== undefined) resolvedHeight = toCssSize(width);
+  }
+
+  // Default width: circular with only height set → matches height (square).
+  let resolvedWidth: string | undefined = toCssSize(width);
+  if (resolvedWidth === undefined && variant === 'circular' && height !== undefined) {
+    resolvedWidth = toCssSize(height);
+  }
+
+  const mergedStyle: CSSProperties = {
+    width: resolvedWidth,
+    height: resolvedHeight,
+    ...style,
+  };
+
+  // Spread order: ref + aria-hidden BEFORE {...props} so a consumer can
+  // override aria-hidden (e.g., for a Skeleton that IS the loading
+  // announcement on a page with no parent live region). className and
+  // style live AFTER {...props} so the component's class composition +
+  // dimension style win over any consumer-supplied raw className / style
+  // (consumer composes via the prop, not by replacing).
+  return visible ? (
+    <span
+      ref={ref}
+      aria-hidden="true"
+      {...props}
+      className={clsx(
+        styles.skeleton,
+        styles[`variant-${variant}`],
+        animation === 'pulse' && styles.pulse,
+        className,
+      )}
+      style={mergedStyle}
+    />
+  ) : null;
+});

package/src/components/Skeleton/index.ts

@@ -0,0 +1,4 @@
+export { Skeleton } from './Skeleton';
+export type { SkeletonProps, SkeletonVariant, SkeletonAnimation } from './Skeleton';
+export { useSkeletonVisibility } from './useSkeletonVisibility';
+export type { SkeletonVisibilityOptions } from './useSkeletonVisibility';

package/src/components/Skeleton/useSkeletonVisibility.ts

@@ -0,0 +1,95 @@
+import { useLayoutEffect, useRef, useState } from 'react';
+
+/** Timing controls for {@link useSkeletonVisibility}. */
+export interface SkeletonVisibilityOptions {
+  /**
+   * Milliseconds to wait before showing the placeholder. Defaults to `0`.
+   * A loading cycle that finishes inside this window never becomes visible.
+   */
+  delay?: number;
+
+  /**
+   * Minimum milliseconds to remain visible after the placeholder appears.
+   * Defaults to `0`.
+   */
+  minDuration?: number;
+}
+
+function normalizeDuration(value: number | undefined): number {
+  const duration = value ?? 0;
+  return Number.isFinite(duration) ? Math.max(0, duration) : 0;
+}
+
+/**
+ * Coordinates delayed placeholder visibility and a minimum visible duration.
+ * Use the returned boolean to keep placeholder and content branches mutually
+ * exclusive while preserving the timing window after `loading` becomes false.
+ *
+ * @example
+ * // Immediate placeholder, then content.
+ * const showPlaceholder = useSkeletonVisibility(loading);
+ * return showPlaceholder ? <Skeleton width="60%" /> : <ContactList />;
+ *
+ * @example
+ * // Suppress quick-load flashes and avoid flashing content during the delay.
+ * const showPlaceholder = useSkeletonVisibility(loading, {
+ *   delay: 200,
+ *   minDuration: 300,
+ * });
+ * return showPlaceholder ? <Skeleton width="60%" /> : loading ? null : <ContactList />;
+ *
+ * @remarks Keep the hook's consumer mounted for the whole loading cycle. If it
+ * unmounts as soon as `loading` changes, the minimum-duration tail cannot finish.
+ */
+export function useSkeletonVisibility(
+  loading: boolean,
+  options: SkeletonVisibilityOptions = {},
+): boolean {
+  const normalizedDelay = normalizeDuration(options.delay);
+  const normalizedMinDuration = normalizeDuration(options.minDuration);
+  const [visible, setVisible] = useState(() => loading && normalizedDelay === 0);
+  const now = Date.now();
+  const shownAt = useRef<number | null>(visible ? now : null);
+  const loadingStartedAt = useRef<number | null>(loading ? now : null);
+  const wasLoading = useRef(loading);
+
+  useLayoutEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    if (loading) {
+      if (!wasLoading.current || loadingStartedAt.current === null) {
+        loadingStartedAt.current = Date.now();
+      }
+      if (!visible) {
+        const show = () => {
+          shownAt.current = Date.now();
+          setVisible(true);
+        };
+        const elapsed = Date.now() - loadingStartedAt.current;
+        const remaining = Math.max(0, normalizedDelay - elapsed);
+        if (remaining === 0) show();
+        else timer = setTimeout(show, remaining);
+      }
+    } else if (visible) {
+      const elapsed =
+        shownAt.current === null ? normalizedMinDuration : Date.now() - shownAt.current;
+      const remaining = Math.max(0, normalizedMinDuration - elapsed);
+      const hide = () => {
+        shownAt.current = null;
+        setVisible(false);
+      };
+      if (remaining === 0) hide();
+      else timer = setTimeout(hide, remaining);
+    } else {
+      loadingStartedAt.current = null;
+    }
+
+    wasLoading.current = loading;
+
+    return () => {
+      if (timer !== undefined) clearTimeout(timer);
+    };
+  }, [loading, normalizedDelay, normalizedMinDuration, visible]);
+
+  return visible;
+}