@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/ErrorState/ErrorState.module.scss

@@ -0,0 +1,105 @@
+@use './ErrorState.tokens';
+
+.errorState {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+.align-center {
+  align-items: center;
+  text-align: center;
+}
+
+.align-start {
+  align-items: flex-start;
+  text-align: start;
+}
+
+// Size modifiers — gap between stacked children + outer padding.
+.size-sm {
+  gap: var(--error-state-gap-sm);
+  padding: var(--error-state-padding-sm);
+}
+
+.size-md {
+  gap: var(--error-state-gap-md);
+  padding: var(--error-state-padding-md);
+}
+
+.size-lg {
+  gap: var(--error-state-gap-lg);
+  padding: var(--error-state-padding-lg);
+}
+
+// Icon — color comes from the tone modifier below. Consumer-supplied SVG
+// inherits via currentColor (lucide convention).
+.icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  line-height: var(--error-state-icon-line-height);
+}
+
+.tone-neutral .icon {
+  color: var(--error-state-icon-fg-neutral);
+}
+
+.tone-danger .icon {
+  color: var(--error-state-icon-fg-danger);
+}
+
+// stylelint-disable property-disallowed-list -- defensive reset of user-agent <h*> margins; not a layout property on the component box.
+.title {
+  margin: 0;
+  color: var(--error-state-title-fg);
+  font-weight: var(--error-state-title-font-weight);
+  line-height: var(--error-state-title-line-height);
+}
+// stylelint-enable property-disallowed-list
+
+.size-sm .title {
+  font-size: var(--error-state-title-font-size-sm);
+}
+
+.size-md .title {
+  font-size: var(--error-state-title-font-size-md);
+}
+
+.size-lg .title {
+  font-size: var(--error-state-title-font-size-lg);
+}
+
+// stylelint-disable property-disallowed-list -- `margin: 0` resets the user-agent
+// <p> margin (the only property flagged by property-disallowed-list here).
+// `max-width: 48ch` is an internal readable-width cap, not a layout property on
+// the component box, and is not the reason for this disable.
+.description {
+  margin: 0;
+  color: var(--error-state-description-fg);
+  line-height: var(--error-state-description-line-height);
+  max-width: 48ch;
+}
+// stylelint-enable property-disallowed-list
+
+.size-sm .description {
+  font-size: var(--error-state-description-font-size-sm);
+}
+
+.size-md .description,
+.size-lg .description {
+  font-size: var(--error-state-description-font-size-md);
+}
+
+// Shrink-to-fit wrappers around the consumer's slots. inline-flex keeps a lone
+// child from stretching the column when align="start". Spacing above comes from
+// .errorState's gap, not padding here.
+.actions {
+  display: inline-flex;
+  align-items: center;
+}
+
+.extra {
+  display: inline-flex;
+  align-items: center;
+}

package/src/components/ErrorState/ErrorState.tokens.scss

@@ -0,0 +1,32 @@
+// ErrorState.tokens.scss — Component-scoped tokens for <ErrorState>. Mirrors the
+// EmptyState scale (gap + padding + type) and adds per-tone icon colors. The
+// internal 48ch description max-width literal lives in the .module.scss and
+// stays a raw value (readable-width cap, not a token).
+:root {
+  // Size — outer gap + padding
+  --error-state-gap-sm: var(--space-2);
+  --error-state-gap-md: var(--space-3);
+  --error-state-gap-lg: var(--space-4);
+  --error-state-padding-sm: var(--space-3);
+  --error-state-padding-md: var(--space-6);
+  --error-state-padding-lg: var(--space-10);
+
+  // Icon — tinted per tone
+  --error-state-icon-fg-neutral: var(--color-fg-muted);
+  --error-state-icon-fg-danger: var(--color-danger);
+  --error-state-icon-line-height: var(--line-height-none);
+
+  // Title
+  --error-state-title-fg: var(--color-fg);
+  --error-state-title-font-weight: var(--font-weight-semibold);
+  --error-state-title-line-height: var(--line-height-tight);
+  --error-state-title-font-size-sm: var(--font-size-sm);
+  --error-state-title-font-size-md: var(--font-size-md);
+  --error-state-title-font-size-lg: var(--font-size-xl);
+
+  // Description
+  --error-state-description-fg: var(--color-fg-subtle);
+  --error-state-description-line-height: var(--line-height-normal);
+  --error-state-description-font-size-sm: var(--font-size-sm);
+  --error-state-description-font-size-md: var(--font-size-md);
+}

package/src/components/ErrorState/ErrorState.tsx

@@ -0,0 +1,125 @@
+import { createElement, forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './ErrorState.module.scss';
+
+/** Visual size. Tracks the typography + spacing scale (mirrors EmptyState). */
+export type ErrorStateSize = 'sm' | 'md' | 'lg';
+
+/** Horizontal alignment of the stacked content. */
+export type ErrorStateAlign = 'center' | 'start';
+
+/** Status tone — drives the icon tint and the danger live-region. */
+export type ErrorStateTone = 'neutral' | 'danger';
+
+/** Valid `<h*>` heading levels. */
+export type ErrorStateHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export interface ErrorStateProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+  /**
+   * Icon rendered above the title. Pass a lucide icon (sized by the consumer —
+   * lg=48, md=32, sm=24), custom SVG, or any ReactNode. The icon's color is set
+   * by `tone`; pass `aria-hidden="true"` on it when purely decorative.
+   */
+  icon?: ReactNode;
+
+  /**
+   * Required title, rendered as a semantic heading (default `<h1>` — it's
+   * usually the page heading). Accepts ReactNode for inline emphasis.
+   */
+  title: ReactNode;
+
+  /** Optional description rendered below the title. */
+  description?: ReactNode;
+
+  /**
+   * Optional action(s) below the description — a `<Button>` or a
+   * `<Cluster gap="sm">` of buttons. Keep to ONE primary action.
+   */
+  actions?: ReactNode;
+
+  /**
+   * Optional supplemental content rendered below the actions — e.g. an
+   * `Error ID: …` line or a "view status" link. Reads as metadata, not primary
+   * copy. Distinct from `description`, which sits above the actions.
+   */
+  extra?: ReactNode;
+
+  /**
+   * Status tone. Defaults to `'neutral'`.
+   * - `'neutral'` — informational (404 / not-found). Icon uses `--color-fg-muted`.
+   * - `'danger'` — an error (500 / crash). Icon uses `--color-danger`, and the
+   *   wrapper gets `role="alert"` so an error-boundary fallback announces on
+   *   mount. Override the role by passing your own `role`.
+   */
+  tone?: ErrorStateTone;
+
+  /**
+   * Visual size. Defaults to `'lg'` (full-page hero). Use `'sm'` / `'md'` when
+   * the state is embedded in a smaller surface.
+   */
+  size?: ErrorStateSize;
+
+  /**
+   * Horizontal alignment of the stacked content. Defaults to `'center'`.
+   * Use `'start'` in a tight column where centering looks stranded.
+   */
+  align?: ErrorStateAlign;
+
+  /**
+   * Heading level for `title`. Defaults to `1` (page-level). Lower it when the
+   * screen is nested under an existing heading. Values outside `1–6` clamp to `1`.
+   */
+  headingLevel?: ErrorStateHeadingLevel;
+}
+
+function clampHeading(level: ErrorStateHeadingLevel | undefined): ErrorStateHeadingLevel {
+  if (level === undefined) return 1;
+  if (level < 1 || level > 6) return 1;
+  return level;
+}
+
+/**
+ * Page-level status / result screen: icon, title heading, description, actions and an `extra` slot.
+ * @see docs/components/ErrorState.md
+ */
+export const ErrorState = forwardRef<HTMLElement, ErrorStateProps>(function ErrorState(
+  {
+    icon,
+    title,
+    description,
+    actions,
+    extra,
+    tone = 'neutral',
+    size = 'lg',
+    align = 'center',
+    headingLevel,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const headingTag = `h${clampHeading(headingLevel)}` as const;
+
+  // role="alert" on danger so an error-boundary fallback announces on mount.
+  // Set before {...props} (Pattern A) so a consumer can override role/aria-*.
+  return (
+    <section
+      ref={ref}
+      role={tone === 'danger' ? 'alert' : undefined}
+      className={clsx(
+        styles.errorState,
+        styles[`size-${size}`],
+        styles[`align-${align}`],
+        styles[`tone-${tone}`],
+        className,
+      )}
+      {...props}
+    >
+      {icon != null && <span className={styles.icon}>{icon}</span>}
+      {createElement(headingTag, { className: styles.title }, title)}
+      {description != null && <p className={styles.description}>{description}</p>}
+      {actions != null && <div className={styles.actions}>{actions}</div>}
+      {extra != null && <div className={styles.extra}>{extra}</div>}
+    </section>
+  );
+});

package/src/components/ErrorState/index.ts

@@ -0,0 +1,8 @@
+export { ErrorState } from './ErrorState';
+export type {
+  ErrorStateProps,
+  ErrorStateSize,
+  ErrorStateAlign,
+  ErrorStateTone,
+  ErrorStateHeadingLevel,
+} from './ErrorState';

package/src/components/Field/Field.module.scss

@@ -0,0 +1,46 @@
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+// Label-beside-control. `--field-label-width` is overridable per consumer.
+// grid-template-columns is not token-linted (only color/border-width/opacity are);
+// the literal fallback mirrors DefinitionList's `--dl-term-width` pattern.
+.horizontal {
+  display: grid;
+  grid-template-columns: var(--field-label-width, 12rem) 1fr;
+  gap: var(--space-2) var(--space-4);
+  align-items: start;
+}
+
+.label {
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--line-height-tight);
+  color: var(--color-fg);
+}
+
+.sizeSm {
+  font-size: var(--font-size-xs);
+}
+
+.sizeLg {
+  font-size: var(--font-size-md);
+}
+
+.required {
+  color: var(--color-danger);
+}
+
+.optional {
+  font-weight: var(--font-weight-regular);
+  color: var(--color-fg-muted);
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+  min-width: 0;
+}

package/src/components/Field/Field.tsx

@@ -0,0 +1,185 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { Text, type TextSize } from '../Text';
+import { useTranslation } from '../../i18n/useTranslation';
+import { hasContent, useFieldWiring, type FieldRenderProps } from '../_internal/fieldWiring';
+import styles from './Field.module.scss';
+
+export type { FieldRenderProps };
+
+/** Label placement relative to the control. */
+export type FieldOrientation = 'vertical' | 'horizontal';
+
+/** Label/message type scale; pairs with the control's own `size`. */
+export type FieldSize = 'sm' | 'md' | 'lg';
+
+type FieldChild = ReactNode | ((field: FieldRenderProps) => ReactNode);
+
+export interface FieldProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** Label text. Renders a `<label htmlFor>` (or, in `asGroup`, a `role="group"` caption). An empty or falsy value (e.g. `0`, `''`, `[]`, `<></>`) renders no label at all; see the anti-pattern below. */
+  label?: ReactNode;
+  /** Helper text below the control. Hidden while `error` is present. */
+  description?: ReactNode;
+  /**
+   * Error message. Replaces `description`, flips the control to `invalid`, and
+   * links it with `aria-describedby`.
+   *
+   * **Not announced, deliberately.** `aria-describedby` is read on FOCUS, so an
+   * error that appears after a submit reaches nobody unless focus moves into
+   * the field. Hard rule 10 permits chosen silence provided it is written down;
+   * this is that note.
+   *
+   * The alternative — a live region per Field — is worse in the common case: a
+   * validate-on-change form would announce on every keystroke, and a submit
+   * failing N fields would fire N announcements over each other. The right
+   * owner of that announcement is the FORM, which knows how many fields failed
+   * and when the user asked for the answer.
+   *
+   * So: announce a summary yourself on submit, and leave the per-field message
+   * to `aria-describedby` for when focus arrives.
+   *
+   * ```tsx
+   * <div role="status" aria-live="polite">
+   *   {submitted && errorCount > 0 ? `${errorCount} fields need attention` : ''}
+   * </div>
+   * ```
+   */
+  error?: ReactNode;
+  /** Marks the field required: shows `*` and injects `required` onto the control. */
+  required?: boolean;
+  /** Marks the field optional: shows `(optional)`. Mutually exclusive with `required`. */
+  optional?: boolean;
+  /** Label placement. Default `'vertical'`. `'horizontal'` puts the label beside the control. */
+  orientation?: FieldOrientation;
+  /** Label/message type scale. Default `'md'`. Size primarily scales the label; the help/error message uses a compact fixed scale (`md` and `lg` both render the message at `sm`). */
+  size?: FieldSize;
+  /** Explicit control id. Field owns the id by default (auto-generated) so the label always matches. */
+  id?: string;
+  /** Group mode for radio/checkbox sets: label becomes a `role="group"` caption (no `htmlFor`). */
+  asGroup?: boolean;
+  /** A single control element (auto-wired) or a render-prop `(field) => ReactNode`. */
+  children: FieldChild;
+}
+
+const MSG_SIZE: Record<FieldSize, TextSize> = { sm: 'xs', md: 'sm', lg: 'sm' };
+
+/**
+ * Labeled-control unit, the editable sibling of `<DefinitionList>`: wires label, helper/error text and ARIA by construction.
+ * @see docs/components/Field.md
+ */
+export const Field = forwardRef<HTMLDivElement, FieldProps>(function Field(
+  {
+    label,
+    description,
+    error,
+    required,
+    optional,
+    orientation = 'vertical',
+    size = 'md',
+    id,
+    asGroup = false,
+    className,
+    children,
+    ...rest
+  },
+  ref,
+) {
+  const t = useTranslation();
+  // Single source of truth for each "is there an X" predicate — round 5
+  // hoisted only `hasLabel` (it had THREE consumers and had already
+  // diverged); round 6 did the same for `hasDescription`/`hasError`/
+  // `hasRequired`, which were 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`/`hasOptional` stay
+  // `Boolean` since `required`/`optional` are plain booleans, 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 hasOptional = Boolean(optional);
+  const { controlId, labelId, descriptionId, errorId, describedBy, labelledBy, invalid, wire } =
+    useFieldWiring({
+      id,
+      hasLabel,
+      hasDescription,
+      hasError,
+      required: hasRequired,
+      asGroup,
+    });
+
+  const control = wire(children);
+
+  const labelClassName = clsx(
+    styles.label,
+    size === 'sm' && styles.sizeSm,
+    size === 'lg' && styles.sizeLg,
+  );
+
+  const markers = (
+    <>
+      {hasRequired && (
+        <span aria-hidden="true" className={styles.required}>
+          {' '}
+          *
+        </span>
+      )}
+      {hasOptional && <span className={styles.optional}> {t('field.optional')}</span>}
+    </>
+  );
+
+  let labelNode: ReactNode = null;
+  if (hasLabel) {
+    labelNode = asGroup ? (
+      <span id={labelId} className={labelClassName}>
+        {label}
+        {markers}
+      </span>
+    ) : (
+      <label htmlFor={controlId} id={labelId} className={labelClassName}>
+        {label}
+        {markers}
+      </label>
+    );
+  }
+
+  let messageNode: ReactNode = null;
+  if (hasError) {
+    messageNode = (
+      <Text as="div" id={errorId} size={MSG_SIZE[size]} tone="danger">
+        {error}
+      </Text>
+    );
+  } else if (hasDescription) {
+    messageNode = (
+      <Text as="div" id={descriptionId} size={MSG_SIZE[size]} tone="muted">
+        {description}
+      </Text>
+    );
+  }
+
+  const groupAria = asGroup
+    ? {
+        role: 'group' as const,
+        'aria-labelledby': labelledBy,
+        'aria-describedby': describedBy,
+        'aria-invalid': invalid || undefined,
+      }
+    : {};
+
+  return (
+    <div
+      ref={ref}
+      className={clsx(styles.field, orientation === 'horizontal' && styles.horizontal, className)}
+      {...groupAria}
+      {...rest}
+    >
+      {labelNode}
+      <div className={styles.body}>
+        {control}
+        {messageNode}
+      </div>
+    </div>
+  );
+});

package/src/components/Field/index.ts

@@ -0,0 +1,2 @@
+export { Field } from './Field';
+export type { FieldProps, FieldOrientation, FieldSize, FieldRenderProps } from './Field';

package/src/components/FileUpload/FileUpload.module.scss

@@ -0,0 +1,187 @@
+@use '../../styles/mixins' as *;
+@use './FileUpload.tokens';
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--file-upload-gap);
+  width: 100%;
+}
+
+.dropzone {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--file-upload-dropzone-gap);
+  padding: var(--file-upload-dropzone-padding);
+  border: var(--border-width-emphasis) dashed var(--file-upload-dropzone-border-color);
+  border-radius: var(--file-upload-dropzone-radius);
+  background: var(--file-upload-dropzone-bg);
+  color: var(--file-upload-dropzone-fg);
+  cursor: pointer;
+  transition:
+    border-color var(--transition-base),
+    background var(--transition-base);
+
+  &:hover {
+    border-color: var(--file-upload-dropzone-border-color-hover);
+    color: var(--file-upload-dropzone-fg-hover);
+  }
+
+  // Split from `:hover` above, which set `outline: none` for both. Focus DID
+  // change the border and text colour pre-fix — a real visible change, so
+  // 2.4.7 Focus Visible was technically satisfied — but it was the SAME
+  // change `:hover` made, so a keyboard user could not tell focused from
+  // hovered, and the ring mechanism was suppressed entirely.
+  // The tint is deliberately not repeated here on focus, unlike Slider's:
+  // splitting the rule means this block no longer sets `border-color`, which
+  // lets `.dragOver` (specificity 0,1,0) win the border while the dropzone is
+  // focused. Before the split, `:focus-visible` (0,2,0) always beat it, so
+  // dragging a file over a focused dropzone showed no drag state. Restoring
+  // the tint here would reintroduce that.
+  // Clipping check (mixin's own requirement for a new call site): neither
+  // `.root` nor `.dropzone` sets `overflow`, so nothing in this component
+  // clips the outset ring. A consumer that scrolls this in a padding-less
+  // container (a `Card` with `overflow: hidden`, a Modal body) could still
+  // clip it — that's #512's territory, not a reason to go inset here.
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+.dragOver {
+  border-color: var(--file-upload-dragover-border-color);
+  border-style: solid;
+  background: var(--file-upload-dragover-bg);
+  color: var(--file-upload-dragover-fg);
+}
+
+.dropzoneIcon {
+  color: var(--file-upload-icon-fg);
+}
+
+.dropzoneLabel {
+  font-size: var(--file-upload-label-font-size);
+  text-align: center;
+}
+
+.dropzoneHint {
+  font-size: var(--file-upload-hint-font-size);
+  color: var(--file-upload-hint-fg);
+  text-align: center;
+}
+
+.hiddenInput {
+  // Visually-hidden pattern — kept in the DOM so the dropzone click can
+  // trigger the picker. Standard 1x1 absolute + clip-rect technique.
+
+  // stylelint-disable-next-line property-disallowed-list -- visually-hidden pattern (component-internal)
+  position: absolute;
+  width: 1px;
+  height: 1px;
+
+  // stylelint-disable-next-line property-disallowed-list -- visually-hidden pattern (component-internal)
+  padding: 0;
+
+  // stylelint-disable-next-line property-disallowed-list -- visually-hidden pattern (component-internal)
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--file-upload-list-gap);
+
+  // stylelint-disable-next-line property-disallowed-list -- native <ul> margin reset (component-internal)
+  margin: 0;
+
+  // stylelint-disable-next-line property-disallowed-list -- native <ul> padding reset (component-internal)
+  padding: 0;
+  list-style: none;
+}
+
+.row {
+  display: grid;
+  grid-template-columns: auto 1fr auto auto auto;
+  align-items: center;
+  gap: var(--file-upload-row-gap);
+  padding: var(--file-upload-row-padding-y) var(--file-upload-row-padding-x);
+  border: var(--border-width) solid var(--file-upload-row-border-color);
+  border-radius: var(--file-upload-row-radius);
+  background: var(--file-upload-row-bg);
+}
+
+// stylelint-disable-next-line block-no-empty -- intentional no-op placeholder for status row variants
+.rowPending,
+.rowUploading,
+.rowDone {
+  // No additional border styling — base .row's border-color is correct.
+}
+
+.rowError {
+  border-color: var(--file-upload-row-border-color-error);
+}
+
+.rowIcon {
+  display: flex;
+  color: var(--file-upload-row-icon-fg);
+}
+
+.rowName {
+  font-size: var(--file-upload-row-name-font-size);
+  color: var(--file-upload-row-name-fg);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  min-width: 0;
+}
+
+.rowMeta {
+  font-size: var(--file-upload-row-meta-font-size);
+  color: var(--file-upload-row-meta-fg);
+  font-variant-numeric: tabular-nums;
+}
+
+.rowStatus {
+  // Status slot — always rendered (empty for pending). Holds <Progress> when
+  // uploading, the error message when error, or the Check icon when done.
+  // Sized via the parent grid's 4th column (auto width).
+  display: flex;
+  align-items: center;
+  min-width: 0;
+}
+
+// #588 — `<Progress>` is `width: 100%` with no intrinsic size of its own, so
+// in the row's `auto` 4th column it measures to 0 and the bar is invisible.
+// Scoped to `.rowUploading` (the row's own per-status class, from
+// STATUS_CLASS) so only the row actually showing a bar gets a wider column;
+// pending/done/error status cells are untouched. `min-inline-size` on a
+// grid item is the item's own sizing, not a layout property the parent owns
+// (CLAUDE.md Rule 4) — it's the same category as the `min-width: 0` above.
+.rowUploading .rowStatus {
+  min-inline-size: var(--file-upload-progress-min-width);
+}
+
+.rowErrorMsg {
+  font-size: var(--file-upload-row-error-font-size);
+  color: var(--file-upload-row-error-fg);
+}
+
+.rowDoneIcon {
+  color: var(--file-upload-row-done-fg);
+}
+
+.disabled .dropzone {
+  cursor: not-allowed;
+  opacity: var(--file-upload-opacity-disabled);
+  pointer-events: none;
+}
+
+.srOnly {
+  @include visually-hidden;
+}