@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/TimeField/index.ts

@@ -0,0 +1,2 @@
+export { TimeField } from './TimeField';
+export type { TimeFieldProps } from './TimeField';

package/src/components/Timeline/Timeline.module.scss

@@ -0,0 +1,58 @@
+@use './Timeline.tokens';
+
+.root {
+  // UA <ol> reset.
+  list-style: none;
+  // stylelint-disable-next-line property-disallowed-list -- UA reset for <ol> default margin
+  margin: 0;
+  // stylelint-disable-next-line property-disallowed-list -- UA reset for <ol> default padding
+  padding: 0;
+  display: block;
+}
+
+.item {
+  display: grid;
+  grid-template-columns: var(--timeline-gutter) 1fr;
+  column-gap: var(--timeline-content-gap);
+}
+
+.gutter {
+  position: relative;
+}
+
+.nodeBox {
+  height: var(--timeline-node-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.connector {
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  top: var(--timeline-node-size);
+  bottom: 0;
+  width: var(--timeline-line-width);
+  background: var(--timeline-line-color);
+}
+
+.item:last-child .connector {
+  display: none;
+}
+
+.content {
+  min-width: 0;
+  padding-block-end: var(--timeline-row-gap);
+}
+
+.item:last-child .content {
+  padding-block-end: 0;
+}
+
+.compact {
+  --timeline-gutter: var(--timeline-gutter-compact);
+  --timeline-node-size: var(--timeline-node-size-compact);
+  --timeline-row-gap: var(--timeline-row-gap-compact);
+  --timeline-content-gap: var(--timeline-content-gap-compact);
+}

package/src/components/Timeline/Timeline.tokens.scss

@@ -0,0 +1,13 @@
+:root {
+  --timeline-gutter: var(--size-md); // 32px node column
+  --timeline-node-size: var(--size-md); // 32px fixed node box
+  --timeline-row-gap: var(--space-4); // 16px between items
+  --timeline-content-gap: var(--space-3); // 12px node → content
+  --timeline-line-width: var(--border-width); // hairline connector
+  --timeline-line-color: var(--color-border);
+
+  --timeline-gutter-compact: var(--size-sm); // 24px
+  --timeline-node-size-compact: var(--size-sm); // 24px
+  --timeline-row-gap-compact: var(--space-2); // 8px
+  --timeline-content-gap-compact: var(--space-2); // 8px
+}

package/src/components/Timeline/Timeline.tsx

@@ -0,0 +1,53 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './Timeline.module.scss';
+
+export interface TimelineProps extends HTMLAttributes<HTMLOListElement> {
+  /** Tighter gutter, node box, and spacing for dense sidebar widgets. Default `false`. */
+  compact?: boolean;
+  /** `<Timeline.Item>`s. */
+  children: ReactNode;
+}
+
+export interface TimelineItemProps extends Omit<HTMLAttributes<HTMLLIElement>, 'children'> {
+  /**
+   * The gutter node — an `<Avatar>`, `<Dot>`, icon, etc. Centered in a fixed node box so
+   * the connector aligns regardless of node content.
+   */
+  node: ReactNode;
+  /** The item content (right of the node) — e.g. name·type·time, body, system text. */
+  children: ReactNode;
+}
+
+/**
+ * Vertical activity-feed primitive: a connector line between per-item `node` slots, with content to the right.
+ * @see docs/components/Timeline.md
+ */
+const TimelineRoot = forwardRef<HTMLOListElement, TimelineProps>(function Timeline(
+  { compact = false, className, children, ...rest },
+  ref,
+) {
+  return (
+    <ol ref={ref} className={clsx(styles.root, compact && styles.compact, className)} {...rest}>
+      {children}
+    </ol>
+  );
+});
+
+const TimelineItem = forwardRef<HTMLLIElement, TimelineItemProps>(function TimelineItem(
+  { node, className, children, ...rest },
+  ref,
+) {
+  return (
+    <li ref={ref} className={clsx(styles.item, className)} {...rest}>
+      <div className={styles.gutter}>
+        <div className={styles.nodeBox}>{node}</div>
+        <span className={styles.connector} aria-hidden="true" />
+      </div>
+      <div className={styles.content}>{children}</div>
+    </li>
+  );
+});
+TimelineItem.displayName = 'Timeline.Item';
+
+export const Timeline = Object.assign(TimelineRoot, { Item: TimelineItem });

package/src/components/Timeline/index.ts

@@ -0,0 +1,2 @@
+export { Timeline } from './Timeline';
+export type { TimelineProps, TimelineItemProps } from './Timeline';

package/src/components/Title/Title.module.scss

@@ -0,0 +1,84 @@
+@use './Title.tokens';
+
+.title {
+  // stylelint-disable-next-line property-disallowed-list -- native heading margin reset
+  margin: 0;
+  font-family: var(--font-family-sans);
+  font-weight: var(--title-font-weight);
+  line-height: var(--title-line-height);
+  color: var(--title-fg);
+}
+
+.sizeXs {
+  font-size: var(--title-font-size-xs);
+}
+
+.sizeSm {
+  font-size: var(--title-font-size-sm);
+}
+
+.sizeMd {
+  font-size: var(--title-font-size-md);
+}
+
+.sizeLg {
+  font-size: var(--title-font-size-lg);
+}
+
+.sizeXl {
+  font-size: var(--title-font-size-xl);
+}
+
+.size2xl {
+  font-size: var(--title-font-size-2xl);
+}
+
+.size3xl {
+  font-size: var(--title-font-size-3xl);
+}
+
+.weightRegular {
+  font-weight: var(--title-font-weight-regular);
+}
+
+.weightMedium {
+  font-weight: var(--title-font-weight-medium);
+}
+
+.weightSemibold {
+  font-weight: var(--title-font-weight-semibold);
+}
+
+.weightBold {
+  font-weight: var(--title-font-weight-bold);
+}
+
+.toneDefault {
+  color: var(--title-fg-default);
+}
+
+.toneMuted {
+  color: var(--title-fg-muted);
+}
+
+.toneSubtle {
+  color: var(--title-fg-subtle);
+}
+
+.toneAccent {
+  color: var(--title-fg-accent);
+}
+
+.toneDanger {
+  color: var(--title-fg-danger);
+}
+
+.truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+
+  // Allow shrinkage below intrinsic size inside flex/grid parents — without
+  // this, the truncate has no effect when the heading is a flex/grid child.
+  min-width: 0;
+}

package/src/components/Title/Title.tokens.scss

@@ -0,0 +1,37 @@
+// Title.tokens.scss — Component-scoped tokens for <Title>. Base block, the
+// per-size font-size scale (xs/sm/md/lg/xl/2xl/3xl), per-weight, and per-tone
+// foregrounds. Title's default weight is semibold (vs Text's regular) and its
+// default line-height is tight (vs Text's normal). --font-family-sans is not
+// tokenized per migration rules.
+:root {
+  // Base
+  --title-font-weight: var(--font-weight-semibold);
+  --title-line-height: var(--line-height-tight);
+  --title-fg: var(--color-fg);
+
+  // Size scale
+  --title-font-size-xs: var(--font-size-xs);
+  --title-font-size-sm: var(--font-size-sm);
+  --title-font-size-md: var(--font-size-md);
+  --title-font-size-lg: var(--font-size-lg);
+  --title-font-size-xl: var(--font-size-xl);
+  --title-font-size-2xl: var(--font-size-2xl);
+  --title-font-size-3xl: var(--font-size-3xl);
+
+  // Weight scale
+  --title-font-weight-regular: var(--font-weight-regular);
+  --title-font-weight-medium: var(--font-weight-medium);
+  --title-font-weight-semibold: var(--font-weight-semibold);
+  --title-font-weight-bold: var(--font-weight-bold);
+
+  // Tone foregrounds
+  --title-fg-default: var(--color-fg);
+  --title-fg-muted: var(--color-fg-muted);
+
+  // DEPRECATED (#521), same collapse as --text-fg-subtle: see Text.tokens.scss
+  // for the measurement, for why the token is kept rather than deleted, and
+  // for the dark-theme appearance change this carries.
+  --title-fg-subtle: var(--title-fg-muted);
+  --title-fg-accent: var(--color-accent);
+  --title-fg-danger: var(--color-danger);
+}

package/src/components/Title/Title.tsx

@@ -0,0 +1,150 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './Title.module.scss';
+
+/** Heading semantic level — what `<hN>` element to render and the default visual size. */
+export type TitleOrder = 1 | 2 | 3 | 4 | 5 | 6;
+
+/** Visual size override. When omitted, derived from `order` (1→3xl, 2→2xl, 3→xl, 4→lg, 5→md, 6→sm). */
+export type TitleSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+
+/**
+ * Color tone. Tone maps to a `--color-*` token. `'subtle'` is deprecated and
+ * resolves to `'muted'` — see {@link TitleProps.tone}.
+ */
+export type TitleTone =
+  | 'default'
+  | 'muted'
+  /** @deprecated Resolves to `muted` (#521) — changes dark-theme appearance. Use `muted`. */
+  | 'subtle'
+  | 'accent'
+  | 'danger';
+
+/** Font weight. */
+export type TitleWeight = 'regular' | 'medium' | 'semibold' | 'bold';
+
+export interface TitleProps extends HTMLAttributes<HTMLHeadingElement> {
+  /**
+   * Heading semantic level (1–6). REQUIRED — forces the consumer to think about
+   * heading hierarchy on the page. Drives both the rendered element (`<h1>`–`<h6>`)
+   * and the default visual size (1→3xl, 2→2xl, 3→xl, 4→lg, 5→md, 6→sm).
+   */
+  order: TitleOrder;
+  /**
+   * Visual size override. Defaults to the size for the given `order`. Use this
+   * when the semantic level and the visual size need to diverge — e.g. a small
+   * section title that's still an `<h2>` for screen readers.
+   */
+  size?: TitleSize;
+  /**
+   * Color tone. Defaults to `'default'` (full foreground).
+   * - `default` — `--color-fg`
+   * - `muted` — `--color-fg-muted`
+   * - `subtle` — **@deprecated (#521): resolves to `muted`. Use `muted`.**
+   *   In LIGHT theme the two neutrals were indistinguishable: OKLab ΔE 0.0261
+   *   when the deprecation was filed, 0.0365 after `--color-fg-muted` was retuned,
+   *   against the 0.065 floor this library's perceptual gates use. In DARK
+   *   they were 0.0707 apart — a real step — so **this deprecation changes
+   *   dark-theme appearance**: `subtle` text in dark gets lighter, moving from
+   *   `--color-fg-subtle` to `--color-fg-muted`. That is the accepted trade
+   *   (a tier that exists in one theme only is not a tier), but it is a
+   *   visual change, not the removal of a duplicate. `--title-fg-subtle` now
+   *   aliases `--title-fg-muted`, so nothing breaks at the type or build level;
+   *   if you need the old dark value back, override `--title-fg-subtle`.
+   * - `accent` — `--color-accent`
+   * - `danger` — `--color-danger`
+   */
+  tone?: TitleTone;
+  /**
+   * Font weight. Defaults to `'semibold'` (matches the most common heading
+   * weight across the existing mockups).
+   */
+  weight?: TitleWeight;
+  /**
+   * Truncate the title to a single line with ellipsis. Useful inside narrow
+   * cards or grid cells. Defaults to `false`. The full text remains in the
+   * accessibility tree — screen readers read the entire string. Don't
+   * additionally add `aria-label` to "compensate" for the visual clip.
+   */
+  truncate?: boolean;
+  /** Title text content. */
+  children: ReactNode;
+}
+
+/**
+ * Default size map keyed by `order`. Each heading level maps to one font-size
+ * token. Override via the `size` prop when the semantic level and visual size
+ * should diverge.
+ */
+const SIZE_BY_ORDER: Record<TitleOrder, TitleSize> = {
+  1: '3xl',
+  2: '2xl',
+  3: 'xl',
+  4: 'lg',
+  5: 'md',
+  6: 'sm',
+};
+
+const SIZE_CLASS: Record<TitleSize, string> = {
+  xs: styles.sizeXs,
+  sm: styles.sizeSm,
+  md: styles.sizeMd,
+  lg: styles.sizeLg,
+  xl: styles.sizeXl,
+  '2xl': styles.size2xl,
+  '3xl': styles.size3xl,
+};
+
+const TONE_CLASS: Record<TitleTone, string> = {
+  default: styles.toneDefault,
+  muted: styles.toneMuted,
+  subtle: styles.toneSubtle,
+  accent: styles.toneAccent,
+  danger: styles.toneDanger,
+};
+
+const WEIGHT_CLASS: Record<TitleWeight, string> = {
+  regular: styles.weightRegular,
+  medium: styles.weightMedium,
+  semibold: styles.weightSemibold,
+  bold: styles.weightBold,
+};
+
+/**
+ * Semantic heading primitive rendering `<h1>`-`<h6>` by `order`, with a default visual size per level.
+ * @see docs/components/Title.md
+ */
+export const Title = forwardRef<HTMLHeadingElement, TitleProps>(function Title(
+  {
+    order,
+    size,
+    tone = 'default',
+    weight = 'semibold',
+    truncate = false,
+    className,
+    children,
+    ...rest
+  },
+  ref,
+) {
+  const Heading = `h${order}` as 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+  const effectiveSize = size ?? SIZE_BY_ORDER[order];
+  // className merged above via clsx so consumer extensions stack with our classes;
+  // {...rest} last so any other consumer-passed attr can override ours (Pattern A).
+  return (
+    <Heading
+      ref={ref}
+      className={clsx(
+        styles.title,
+        SIZE_CLASS[effectiveSize],
+        TONE_CLASS[tone],
+        WEIGHT_CLASS[weight],
+        truncate && styles.truncate,
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </Heading>
+  );
+});

package/src/components/Title/index.ts

@@ -0,0 +1,2 @@
+export { Title } from './Title';
+export type { TitleProps, TitleOrder, TitleSize, TitleTone, TitleWeight } from './Title';