@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/EmptyState/EmptyState.module.scss

@@ -0,0 +1,102 @@
+@use './EmptyState.tokens';
+
+.emptyState {
+  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(--empty-state-gap-sm);
+  padding: var(--empty-state-padding-sm);
+}
+
+.size-md {
+  gap: var(--empty-state-gap-md);
+  padding: var(--empty-state-padding-md);
+}
+
+.size-lg {
+  gap: var(--empty-state-gap-lg);
+  padding: var(--empty-state-padding-lg);
+}
+
+// Icon — uses --color-fg-muted so it sits visually "behind" the title.
+// Consumer-supplied SVG inherits via currentColor when its `color` prop
+// is omitted (lucide convention).
+.icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--empty-state-icon-fg);
+  line-height: var(--empty-state-icon-line-height);
+}
+
+// Title — semantic heading. Reset user-agent margins (h1-h6 default to
+// nonzero margin in most browsers) so the gap above is controlled by
+// .emptyState's flex `gap`.
+// 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(--empty-state-title-fg);
+  font-weight: var(--empty-state-title-font-weight);
+  line-height: var(--empty-state-title-line-height);
+}
+// stylelint-enable property-disallowed-list
+
+.size-sm .title {
+  font-size: var(--empty-state-title-font-size-sm);
+}
+
+.size-md .title {
+  font-size: var(--empty-state-title-font-size-md);
+}
+
+.size-lg .title {
+  font-size: var(--empty-state-title-font-size-lg);
+}
+
+// stylelint-disable property-disallowed-list -- `margin: 0` is a defensive
+// reset of the user-agent <p> margin; `max-width: 48ch` is an internal
+// readable-width cap. Neither is a layout property on the component box.
+.description {
+  margin: 0;
+  color: var(--empty-state-description-fg);
+  line-height: var(--empty-state-description-line-height);
+
+  // Cap the readable line length. Most visible on `size-lg` (the only
+  // size that lives inside wide containers), but applied unconditionally
+  // so two-paragraph descriptions stay scannable at any size.
+  max-width: 48ch;
+}
+// stylelint-enable property-disallowed-list
+
+.size-sm .description {
+  font-size: var(--empty-state-description-font-size-sm);
+}
+
+.size-md .description,
+.size-lg .description {
+  font-size: var(--empty-state-description-font-size-md);
+}
+
+// Shrink-to-fit wrapper around the consumer's actions slot. `inline-flex`
+// keeps a lone `<Button>` from stretching to fill the column when
+// `align="start"` is set; vertical-align ensures consistent baseline
+// against any sibling text. The spacing above comes from `.emptyState`'s
+// `gap`, not from any padding here.
+.actions {
+  display: inline-flex;
+  align-items: center;
+}

package/src/components/EmptyState/EmptyState.tokens.scss

@@ -0,0 +1,28 @@
+// EmptyState.tokens.scss — Component-scoped tokens for <EmptyState>. Covers per-size gap + padding, icon/title/description colors + sizes, and title/description line-heights. The internal 48ch description max-width literal is intentional and stays a raw value.
+:root {
+  // Size — outer gap + padding
+  --empty-state-gap-sm: var(--space-2);
+  --empty-state-gap-md: var(--space-3);
+  --empty-state-gap-lg: var(--space-4);
+  --empty-state-padding-sm: var(--space-3);
+  --empty-state-padding-md: var(--space-6);
+  --empty-state-padding-lg: var(--space-10);
+
+  // Icon
+  --empty-state-icon-fg: var(--color-fg-muted);
+  --empty-state-icon-line-height: var(--line-height-none);
+
+  // Title
+  --empty-state-title-fg: var(--color-fg);
+  --empty-state-title-font-weight: var(--font-weight-semibold);
+  --empty-state-title-line-height: var(--line-height-tight);
+  --empty-state-title-font-size-sm: var(--font-size-sm);
+  --empty-state-title-font-size-md: var(--font-size-md);
+  --empty-state-title-font-size-lg: var(--font-size-xl);
+
+  // Description
+  --empty-state-description-fg: var(--color-fg-subtle);
+  --empty-state-description-line-height: var(--line-height-normal);
+  --empty-state-description-font-size-sm: var(--font-size-sm);
+  --empty-state-description-font-size-md: var(--font-size-md);
+}

package/src/components/EmptyState/EmptyState.tsx

@@ -0,0 +1,112 @@
+import { createElement, forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './EmptyState.module.scss';
+
+/** Visual size. Tracks typography + spacing scale. */
+export type EmptyStateSize = 'sm' | 'md' | 'lg';
+
+/** Horizontal alignment of the stacked content. */
+export type EmptyStateAlign = 'center' | 'start';
+
+/** Valid `<h*>` heading levels. */
+export type EmptyStateHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export interface EmptyStateProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+  /**
+   * Icon rendered above the title. Pass a lucide icon, custom SVG, or any
+   * ReactNode. Sized by the consumer — recommended: sm=24, md=32, lg=48.
+   * Omit for an icon-less empty state.
+   */
+  icon?: ReactNode;
+
+  /**
+   * Required title. Rendered as a semantic heading (default `<h3>`).
+   * Accepts ReactNode so inline emphasis works
+   * (e.g., `<>Found <strong>0</strong> results</>`). Keep it short and
+   * announceable — AT users hear it via heading navigation.
+   */
+  title: ReactNode;
+
+  /** Optional description rendered below the title. */
+  description?: ReactNode;
+
+  /**
+   * Optional action(s) rendered below the description. Typically a
+   * `<Button>` or a `<Cluster gap="sm">` of buttons.
+   */
+  actions?: ReactNode;
+
+  /**
+   * Visual size. Defaults to `'md'`.
+   * - `'sm'` — compact for inline / popover use (empty Select results,
+   *   empty filter chips). Icon target 24px, font-size-sm title.
+   * - `'md'` — default for cards / sections (DataTable empty row, inbox
+   *   empty). Icon target 32px, font-size-md title.
+   * - `'lg'` — hero / full-page empty states. Icon target 48px,
+   *   font-size-xl title.
+   */
+  size?: EmptyStateSize;
+
+  /**
+   * Horizontal alignment of the stacked content. Defaults to `'center'`.
+   * Use `'start'` when the empty state sits in a tight column where
+   * centering would look stranded.
+   */
+  align?: EmptyStateAlign;
+
+  /**
+   * Heading level for the `title`. Defaults to `3` (renders `<h3>`).
+   * Set higher (4–6) when the empty state lives deep inside the page's
+   * heading hierarchy. Set to `2` when the empty state IS the page's
+   * primary content. Values outside `1–6` clamp to `3`.
+   */
+  headingLevel?: EmptyStateHeadingLevel;
+}
+
+function clampHeading(level: EmptyStateHeadingLevel | undefined): EmptyStateHeadingLevel {
+  if (level === undefined) return 3;
+  if (level < 1 || level > 6) return 3;
+  return level;
+}
+
+/**
+ * Empty-state container: optional icon, required title heading, optional description and actions, stacked vertically.
+ * @see docs/components/EmptyState.md
+ */
+export const EmptyState = forwardRef<HTMLElement, EmptyStateProps>(function EmptyState(
+  {
+    icon,
+    title,
+    description,
+    actions,
+    size = 'md',
+    align = 'center',
+    headingLevel,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const headingTag = `h${clampHeading(headingLevel)}` as const;
+
+  // {...props} last so consumer overrides win (Pattern A). className is
+  // destructured above and re-injected into clsx() so consumer-supplied
+  // class names compose with the component's, rather than replacing them.
+  return (
+    <section
+      ref={ref}
+      className={clsx(
+        styles.emptyState,
+        styles[`size-${size}`],
+        styles[`align-${align}`],
+        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>}
+    </section>
+  );
+});

package/src/components/EmptyState/index.ts

@@ -0,0 +1,7 @@
+export { EmptyState } from './EmptyState';
+export type {
+  EmptyStateProps,
+  EmptyStateSize,
+  EmptyStateAlign,
+  EmptyStateHeadingLevel,
+} from './EmptyState';

package/src/components/EntityChip/EntityChip.module.scss

@@ -0,0 +1,275 @@
+@use '../../styles/mixins' as *;
+@use './EntityChip.tokens';
+
+.chip {
+  display: inline-flex;
+  align-items: baseline;
+  gap: var(--entity-chip-gap);
+
+  // Equal top/bottom values include the font-metric inset documented in
+  // EntityChip.tokens.scss.
+  padding: var(--entity-chip-padding-top) var(--entity-chip-padding-x)
+    var(--entity-chip-padding-bottom);
+  border: none;
+  border-radius: var(--entity-chip-radius);
+  background: var(--entity-chip-bg);
+  color: var(--entity-chip-fg);
+
+  // Font-size deliberately inherits (no override): the chip text runs at the
+  // surrounding text's size, which — with the tight line-height below — makes
+  // the padded box bracket the local glyph band symmetrically in any context.
+  // A fixed smaller size made the box hang ~4px below 14px body text even
+  // with perfect baseline alignment.
+  font: inherit;
+  line-height: var(--entity-chip-line-height);
+
+  // Consumer apps ship global link rules (`a:hover { text-decoration: … }`)
+  // that out-specify anything the chip can win by selectors alone — the chip
+  // must NEVER underline, so assert it unconditionally.
+  // stylelint-disable-next-line declaration-no-important -- global consumer link rules out-specify the chip; precedent: Sortable's reduced-motion !important
+  text-decoration: none !important;
+  vertical-align: baseline;
+
+  // <a>/<button> renders are the interactive variants and get hover/focus
+  // chrome even when loading/unavailable (those are purely visual states on a
+  // live link) — only a target-less <span> chip has none.
+  &:is(a, button) {
+    cursor: pointer;
+
+    // Hover affordance: bg deepens a step + a brightness dip. Never an
+    // underline, never a weight change (a fake-bold text-stroke used to live
+    // here — dropped, see #345).
+    &:hover {
+      background: var(--entity-chip-bg-hover);
+      filter: brightness(0.96);
+    }
+
+    &:focus-visible {
+      @include focus-ring;
+    }
+  }
+}
+
+.icon {
+  display: inline-flex;
+  align-items: center;
+  // stylelint-disable-next-line property-disallowed-list -- internal child of the chip's OWN flex row, opting the icon glyph back to vertical centering while the chip itself aligns on text baseline
+  align-self: center;
+}
+
+.prefix {
+  color: var(--entity-chip-prefix-fg);
+}
+
+.label {
+  font-weight: var(--entity-chip-label-font-weight);
+}
+
+// `labelWeight="semibold"` (#590): a modifier class on BOTH the prefix and
+// the label (the task-chip design wants key + title both heavier). Compound
+// selectors so the class only takes effect together with the part's own
+// class; the prefix keeps its muted color, only the weight changes.
+.prefix.semibold,
+.label.semibold {
+  font-weight: var(--entity-chip-label-font-weight-semibold);
+}
+
+// Text that belongs in the accessible name but not on screen. Three jobs now:
+// a loading chip's label (so it isn't announced as just "…"), its loading state
+// word, and an unavailable chip's state word. Both state words exist because
+// the ARIA attribute alone reaches nobody — `aria-disabled` carries no meaning
+// on a non-widget role, and `busy` is not conveyed on a non-live element.
+.hiddenLabel {
+  @include visually-hidden;
+}
+
+.ellipsis {
+  color: var(--entity-chip-prefix-fg);
+}
+
+.status {
+  color: var(--entity-chip-status-fg, currentColor);
+}
+
+// Trailing adornments (priority icon, badge): centered on the line like the
+// icon, never shrunk.
+.trailing {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  // stylelint-disable-next-line property-disallowed-list -- internal child of the chip's OWN flex row, centering adornments while the chip itself aligns on text baseline
+  align-self: center;
+}
+
+// Single-line list-row mode (#565): capped at the container, only the label
+// ellipsizes; every other part keeps its size.
+.truncate {
+  max-width: 100%;
+  min-width: 0;
+  white-space: nowrap;
+
+  // Single-line, so centring is safe and keeps the text centred when a
+  // trailing adornment is taller than the line. Non-truncate chips keep
+  // baseline because their label can wrap.
+  align-items: center;
+
+  > * {
+    flex-shrink: 0;
+  }
+
+  > .label {
+    flex-shrink: 1;
+    min-width: 0;
+
+    // Clip the inline axis only: the block axis would also be clipped by
+    // the hidden keyword, cutting descenders at line-height 1 (#678).
+    overflow-x: clip;
+    overflow-y: visible;
+    text-overflow: ellipsis;
+  }
+}
+
+// Colored via --entity-chip-status-fg (set on the chip root when `status` is
+// present, see EntityChip.tsx) so the dot reads as one unit with the status
+// label instead of a neutral separator.
+.dot {
+  flex-shrink: 0;
+  width: var(--entity-chip-dot-size);
+  height: var(--entity-chip-dot-size);
+  border-radius: var(--radius-full);
+  background: currentcolor;
+  color: var(--entity-chip-status-fg, currentColor);
+  // stylelint-disable-next-line property-disallowed-list -- internal child of the chip's OWN flex row, centering the circle on the line while the chip itself aligns on text baseline
+  align-self: center;
+}
+
+// Specificity 0,2,0 (.unavailable .status) beats the plain .status rule
+// (0,1,0) so the unavailable muted color wins over any resolved status color.
+.unavailable {
+  color: var(--entity-chip-unavailable-fg);
+
+  .status,
+  .dot {
+    color: var(--entity-chip-unavailable-fg);
+  }
+}
+
+// Segmented chip (#582): the root is only the rounded clip; the core carries
+// today's fill and padding, and palette segments butt against it. One line:
+// only the core's label gives way.
+.chip.segmented {
+  align-items: baseline;
+  gap: 0;
+  max-width: 100%;
+  min-width: 0;
+  padding: 0;
+  overflow: hidden;
+  background: none;
+  white-space: nowrap;
+
+  &:is(a, button):hover {
+    background: none;
+  }
+}
+
+.core {
+  display: inline-flex;
+  align-items: baseline;
+  gap: var(--entity-chip-gap);
+  padding: var(--entity-chip-padding-top) var(--entity-chip-padding-x)
+    var(--entity-chip-padding-bottom);
+  background: var(--entity-chip-bg);
+
+  > * {
+    flex-shrink: 0;
+  }
+
+  > .label {
+    flex-shrink: 1;
+    min-width: 0;
+    overflow-x: clip;
+    overflow-y: visible;
+    text-overflow: ellipsis;
+  }
+}
+
+// `.core`'s own shrink/min-width, scoped under `.segmented` so the selector
+// (0,2,0) out-specifies `.truncate > *` (0,1,0, the `*` contributes nothing)
+// regardless of which rule comes later in the stylesheet — `.core` is always
+// a direct child of the `.segmented` root, so this changes nothing visually.
+.segmented > .core {
+  flex-shrink: 1;
+  min-width: 0;
+}
+
+.segmented:is(a, button):hover .core {
+  background: var(--entity-chip-bg-hover);
+}
+
+.segment {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  // stylelint-disable-next-line property-disallowed-list -- internal child of the chip's OWN flex row: the root aligns on the core's text baseline, segments fill its height
+  align-self: stretch;
+  padding-top: var(--entity-chip-padding-top);
+  padding-bottom: var(--entity-chip-padding-bottom);
+  background: var(--entity-chip-segment-bg, transparent);
+  color: var(--entity-chip-segment-fg, currentColor);
+}
+
+.segmentIcon {
+  padding-inline: var(--entity-chip-segment-padding-x-icon);
+}
+
+// #591: the outer box keeps the chip's OWN font-size and line-height (and the
+// same vertical padding as `.core`, from `.segment` above) so its box and its
+// first-line baseline match the core exactly. `display: block` drops the
+// `.segment` base rule's centring flex layout in favor of a normal block
+// formatting context, so the line box's strut — not `align-items: center` —
+// sets the baseline; `align-self: stretch` (inherited from `.segment`) still
+// spans the row for the fill. The smaller text size lives on the inner
+// `.segmentTextValue` span instead (moved off this element), which then sits
+// on that baseline via ordinary inline layout.
+.segmentText {
+  display: block;
+  padding-inline: var(--entity-chip-segment-padding-x-text);
+  line-height: var(--entity-chip-line-height);
+}
+
+.segmentTextValue {
+  font-size: var(--entity-chip-segment-text-size);
+  font-weight: var(--entity-chip-label-font-weight);
+
+  // Contributes no height of its own: `line-height: 1` resolved against this
+  // smaller font sticks out of the chip's line box when baseline-aligned
+  // (measured: the chip grew 20.5px → 21.09px). At 0 the segment's strut
+  // alone sets the line — the same box as the core — and the glyphs still
+  // sit on its baseline (#591, measured equal in Chromium).
+  line-height: 0;
+}
+
+.segmentGlyph {
+  display: inline-flex;
+
+  > svg {
+    width: var(--entity-chip-segment-glyph-size);
+    height: var(--entity-chip-segment-glyph-size);
+  }
+}
+
+// `labelMaxWidth` (#582): the label alone is capped (max-width set inline in
+// `ch`) and ellipsizes on one line — also on a chip that otherwise wraps.
+.capped {
+  overflow-x: clip;
+  overflow-y: visible;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+// `labelEllipsis="start"` (#593): overflow — and the ellipsis — falls at the
+// label's start, so its tail stays visible. The inner `dir="ltr"` run in the
+// markup keeps the text order.
+.ellipsisStart {
+  direction: rtl;
+}

package/src/components/EntityChip/EntityChip.tokens.scss

@@ -0,0 +1,66 @@
+// EntityChip.tokens.scss — Component-scoped tokens for <EntityChip>. Chip
+// chrome matches the RichText @mention fill exactly (--color-accent-bg-subtle
+// / --color-accent, see _prose.scss) so a chip and a rendered mention read as
+// the same visual object in both themes — no per-theme tuning needed since
+// the accent tokens are already theme-aware.
+:root {
+  --entity-chip-bg: var(--color-accent-bg-subtle);
+  --entity-chip-bg-hover: var(--color-accent-bg-subtle);
+  --entity-chip-fg: var(--color-accent);
+
+  // Matches the RichText @mention's own font-weight (_prose.scss) — part of
+  // the same "read as one visual object" goal as the bg/fg tokens above.
+  --entity-chip-label-font-weight: var(--font-weight-medium);
+
+  // `labelWeight="semibold"` (#590) — an explicit heavier weight for designs
+  // that want it (e.g. the segmented task chip's key + title). Default stays
+  // `medium` above, matching a plain chip and the RichText @mention.
+  --entity-chip-label-font-weight-semibold: var(--font-weight-semibold);
+  --entity-chip-prefix-fg: var(--color-fg-muted);
+  --entity-chip-radius: var(--radius-sm);
+  --entity-chip-gap: var(--space-1);
+  --entity-chip-padding-y: var(--space-05);
+  --entity-chip-padding-x: var(--space-2);
+
+  // At line-height:1 the browser synthesizes the line box's ascent/descent
+  // split from the font's own metrics, not from the rendered glyphs — most
+  // sans-serif fonts reserve far more headroom above the baseline (room for
+  // tall accents) than the descent metric leaves below it (barely enough for
+  // 'y'/'p'/'g'). With equal padding-top/padding-bottom that metric skew
+  // reads as extra padding on top (see #357). em-relative because the skew
+  // scales with the inherited font-size, not a fixed px amount — measured ~3px
+  // top/1px bottom ink gap at 14px body size and ~5px/1px at 24px heading
+  // size before this correction. Use the corrected inset equally on both
+  // edges so the chip's computed top and bottom padding match exactly.
+  --entity-chip-padding-y-shift: 0.09em;
+  --entity-chip-padding-top: calc(
+    var(--entity-chip-padding-y) + var(--entity-chip-padding-y-shift)
+  );
+  --entity-chip-padding-bottom: calc(
+    var(--entity-chip-padding-y) + var(--entity-chip-padding-y-shift)
+  );
+
+  // No font-size token: the chip inherits the surrounding text's size by
+  // design (see EntityChip.module.scss) — a tight line-height keeps the
+  // padded box hugging the glyph band instead of hanging below the baseline.
+  --entity-chip-line-height: var(--line-height-none);
+
+  --entity-chip-unavailable-fg: var(--color-fg-muted);
+
+  // Status separator dot — DIAMETER of the solid circle rendered between the
+  // name and the status (its own flex item, so the chip's gap spaces it
+  // symmetrically). A fixed size on purpose: it must not scale with the
+  // inherited font and inflate the line box.
+  --entity-chip-dot-size: var(--space-1);
+
+  // Segments (#582): palette-coloured parts butted against the core. The
+  // fill/fg come from the segment's PaletteColor at runtime
+  // (--entity-chip-segment-bg/-fg), so they're not declared here.
+  --entity-chip-segment-padding-x-icon: var(--space-1);
+  --entity-chip-segment-padding-x-text: var(--space-2);
+
+  // Relative to the inherited text size, like the chip itself; a segment's
+  // `size` prop overrides them in em.
+  --entity-chip-segment-glyph-size: 0.85em;
+  --entity-chip-segment-text-size: 0.9em;
+}