@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Thread/Thread.module.scss

@@ -0,0 +1,161 @@
+@use './Thread.tokens';
+
+.root {
+  list-style: none;
+  // stylelint-disable-next-line property-disallowed-list -- UA reset for <ul> default margin
+  margin: 0;
+  // stylelint-disable-next-line property-disallowed-list -- UA reset for <ul> default padding
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--thread-row-gap);
+}
+
+.item {
+  display: grid;
+  grid-template-columns: var(--thread-node-size) 1fr;
+  column-gap: var(--thread-content-gap);
+
+  // Row gap separates the body row from the flat-replies row (past the depth cap),
+  // so the first flat reply isn't flush against the parent body. No-op for the
+  // indented branch (single grid row — its replies nest inside `.content`).
+  row-gap: var(--thread-row-gap);
+}
+
+// Node box: its height is the alignment target. Default (`nodeAlign="header"`) it's the
+// header line-box, so a node taller than one line centers ON the first body line
+// (overflowing the box symmetrically). `.alignTop` makes it the full node height → the
+// node top-aligns with the body. Either way the node is centered within the box.
+.nodeBox {
+  height: var(--thread-nodebox-height);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+// nodeAlign="top": full-height node box, top-aligned with the body (the pre-header-
+// centering behavior). Overrides the header-centering defaults from the tokens.
+.alignTop {
+  --thread-node-center: calc(var(--thread-node-size) / 2);
+  --thread-nodebox-height: var(--thread-node-size);
+}
+
+.content {
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--thread-row-gap);
+}
+
+// `position: relative` so the parent rail (rendered as a child) anchors to the body box:
+// its bottom edge is the rail's natural terminus, independent of the surface colour or
+// the replies' height.
+.body {
+  position: relative;
+  min-width: 0;
+}
+
+// The parent rail's trunk above the replies — from just below the node down to the
+// bottom of the body, extended one row-gap further so it meets the first reply's trunk
+// segment across the body→replies gap. Anchored to `.body` (not a full-height gutter),
+// so there is no overshoot to mask: the per-reply `::after` segments carry the trunk the
+// rest of the way and terminate it exactly at the last elbow. Decorative.
+.rail {
+  position: absolute;
+  inset-inline-start: calc(-1 * (var(--thread-node-size) / 2 + var(--thread-content-gap)));
+  transform: translateX(-50%);
+
+  // Start a hairline below the node (node centre + half the node), so the rail doesn't
+  // touch the avatar.
+  inset-block-start: calc(
+    var(--thread-node-center) + var(--thread-node-size) / 2 + var(--thread-node-gap)
+  );
+  inset-block-end: calc(-1 * var(--thread-row-gap));
+  width: var(--thread-rail-width);
+  background: var(--thread-rail-color);
+}
+
+// Indented replies — nested inside content (so the gutter column stretches and the
+// parent rail spans alongside them). Its own flex-column gap stacks the replies.
+.replies {
+  list-style: none;
+  // stylelint-disable-next-line property-disallowed-list -- UA reset for <ul> default margin
+  margin: 0;
+  // stylelint-disable-next-line property-disallowed-list -- UA reset for <ul> default padding
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--thread-row-gap);
+}
+
+// Each indented reply branches off the parent rail with a horizontal elbow that meets
+// the reply's node — so the thread reads as a ├─ / └─ tree, not just a bare vertical
+// line. The parent rail sits at the parent gutter's centre, one indent level (gutter
+// half + content-gap) to the LEFT of this reply, so the elbow starts there and runs
+// toward the reply's node (stopping a hairline short of the avatar). Logical props →
+// RTL-safe. Only indented replies (not the root items or flat past-cap replies) carry
+// an elbow, since only they sit under a rail.
+.replies > .item {
+  position: relative;
+}
+
+.replies > .item::before {
+  content: '';
+  position: absolute;
+  inset-block-start: var(--thread-node-center);
+  inset-inline-start: calc(-1 * (var(--thread-node-size) / 2 + var(--thread-content-gap)));
+
+  // Run from the parent rail to a hairline short of the node, so it doesn't touch the
+  // avatar (full reach would be node/2 + content-gap; stop `node-gap` before it).
+  width: calc(var(--thread-node-size) / 2 + var(--thread-content-gap) - var(--thread-node-gap));
+  height: var(--thread-rail-width);
+  background: var(--thread-rail-color);
+  transform: translateY(-50%);
+}
+
+// The trunk through the reply group, drawn per reply as a vertical segment so it ends
+// exactly at the last elbow — no full-height rail + surface-coloured mask, so it's
+// independent of the surface the thread sits on. Each segment starts one row-gap above
+// its item (bridging the gap to the previous segment / the body rail), giving a
+// continuous line at the parent gutter's centre.
+.replies > .item::after {
+  content: '';
+  position: absolute;
+  inset-block-start: calc(-1 * var(--thread-row-gap));
+  inset-inline-start: calc(-1 * (var(--thread-node-size) / 2 + var(--thread-content-gap)));
+  transform: translateX(-50%);
+  width: var(--thread-rail-width);
+  background: var(--thread-rail-color);
+}
+
+// Non-last replies: run the segment to the item's bottom so it joins the next one.
+.replies > .item:not(:last-child)::after {
+  inset-block-end: 0;
+}
+
+// Last reply: stop the trunk at this elbow (└─) — node centre + the bridged gap — so it
+// terminates at the final branch with nothing dangling below it.
+.replies > .item:last-child::after {
+  height: calc(var(--thread-row-gap) + var(--thread-node-center));
+}
+
+// Flat replies past the cap — a direct grid child spanning both columns so they are
+// NOT indented further (the gutter stops compounding). No parent rail / elbow here.
+.repliesFlat {
+  // stylelint-disable-next-line property-disallowed-list -- internal grid placement: flat replies span both columns to stop indent compounding
+  grid-column: 1 / -1;
+  list-style: none;
+  // stylelint-disable-next-line property-disallowed-list -- UA reset for <ul> default margin
+  margin: 0;
+  // stylelint-disable-next-line property-disallowed-list -- UA reset for <ul> default padding
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--thread-row-gap);
+}
+
+.compact {
+  --thread-node-size: var(--thread-node-size-compact);
+  --thread-content-gap: var(--thread-content-gap-compact);
+  --thread-row-gap: var(--thread-row-gap-compact);
+}

package/src/components/Thread/Thread.tokens.scss

@@ -0,0 +1,32 @@
+:root {
+  // Node column / box — match it to the avatar size you pass as `node`. Default `sm`
+  // (24px): comment-thread avatars are small, and it keeps the per-level reply indent
+  // (node + content-gap) tight. Override `--thread-node-size` for larger nodes.
+  --thread-node-size: var(--size-sm); // 24px node column / box
+  --thread-content-gap: var(
+    --space-2
+  ); // 8px node → content (also the per-level reply indent: node + gap)
+  --thread-row-gap: var(--space-4); // 16px between items
+  --thread-rail-width: var(--border-width); // hairline rail
+  --thread-rail-color: var(--color-border);
+  --thread-node-gap: 1px; // hairline gap between the connector lines and the node/avatar
+
+  // Height of the first body line (the "header" — author + timestamp). With the
+  // default `nodeAlign="header"`, the node is vertically centered against THIS line, so
+  // it should match your header text's line-box. Defaults to the line-box of
+  // `<Text size="sm">` (the canonical header) via the global primitives — if you rebrand
+  // Text's own tokens (`--text-font-size-sm`/`--text-line-height`) so they diverge, or
+  // your header line differs, override this token to match.
+  --thread-header-line-height: calc(var(--font-size-sm) * var(--line-height-normal));
+
+  // Node vertical centre (from the item top) and node-box height. Defaults center the
+  // node on the header line; the `.alignTop` class (`nodeAlign="top"`) overrides both to
+  // top-align the node with the body instead. The rail/elbow connectors derive their
+  // Y from `--thread-node-center`, so they track whichever alignment is active.
+  --thread-node-center: calc(var(--thread-header-line-height) / 2);
+  --thread-nodebox-height: var(--thread-header-line-height);
+
+  --thread-node-size-compact: var(--size-sm); // 24px
+  --thread-content-gap-compact: var(--space-1); // 4px
+  --thread-row-gap-compact: var(--space-2); // 8px
+}

package/src/components/Thread/Thread.tsx

@@ -0,0 +1,176 @@
+import {
+  forwardRef,
+  createContext,
+  useContext,
+  Children,
+  isValidElement,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import styles from './Thread.module.scss';
+
+const DEFAULT_MAX_DEPTH = 4;
+
+interface ThreadContextValue {
+  /** Current nesting depth — 0 at the root, +1 per indented reply level. */
+  depth: number;
+  /** Max depth before replies stop indenting and render flat. */
+  maxDepth: number;
+}
+
+const ThreadContext = createContext<ThreadContextValue | null>(null);
+
+/** Where the leading `node` sits relative to the comment body. See `ThreadProps#nodeAlign`. */
+export type ThreadNodeAlign = 'header' | 'top';
+
+/**
+ * Reads the surrounding thread depth/cap. Falls back to a depth-0 default so a
+ * `<Thread.Item>` can render standalone (e.g. in a test) without a provider.
+ */
+const useThread = (): ThreadContextValue =>
+  useContext(ThreadContext) ?? { depth: 0, maxDepth: DEFAULT_MAX_DEPTH };
+
+export interface ThreadProps extends HTMLAttributes<HTMLUListElement> {
+  /**
+   * Max visual nesting depth before replies render flat (no further indent). Once the
+   * cap is reached, deeper replies keep the same indent level so the thread stops
+   * marching right. Default `4`.
+   */
+  maxDepth?: number;
+  /**
+   * Tighter gaps for dense surfaces (sidebars, panels). The remapped tokens cascade to
+   * every nested item via CSS custom properties. Default `false`.
+   */
+  compact?: boolean;
+  /**
+   * Where the leading `node` sits relative to the comment body.
+   * - `header` (default) — vertically centered on the **first body line** (the author /
+   *   timestamp header), Jira/GitHub style, so a node taller than one line (e.g. a 24px
+   *   `<Avatar>`) reads as centered against the name rather than top-aligned. Assumes the
+   *   header line-box matches `--thread-header-line-height` (defaults to `<Text size="sm">`);
+   *   override that token if your header line differs. Remove any old header
+   *   `lineHeight` override (e.g. `var(--size-sm)`) — it now double-compensates.
+   * - `top` — top-aligned with the body (the node's top meets the body's top). Use when the
+   *   node is about one line tall, or when you deliberately want top alignment.
+   */
+  nodeAlign?: ThreadNodeAlign;
+  /** The `<Thread.Item>`s. */
+  children: ReactNode;
+}
+
+export interface ThreadItemProps extends HTMLAttributes<HTMLLIElement> {
+  /**
+   * The leading marker the rail connects to — an `<Avatar>`, icon, or `<Dot>`. Centered
+   * in its node box so the rail/elbow connectors meet it cleanly regardless of node
+   * content; by default the box centers on the first body line so a taller node aligns to
+   * the header (see `Thread`'s `nodeAlign`). It's a slot: there is no built-in avatar.
+   * Size the node to `--thread-node-size` (default `sm` / 24px) — e.g. `<Avatar size="sm">`;
+   * for a larger node, override `--thread-node-size` to match.
+   */
+  node: ReactNode;
+  /**
+   * The comment body/actions, plus optional nested `<Thread.Item>` replies. Plain children
+   * render as the comment body; any direct `<Thread.Item>` child renders as a reply under
+   * the rail.
+   */
+  children: ReactNode;
+}
+
+// Named `ThreadItemImpl` (not `ThreadItem`) so the inner named-function-expression
+// scope does NOT shadow the outer `const ThreadItem` — the recursive child sort below
+// compares `child.type === ThreadItem` (the forwardRef object), and a same-named inner
+// function would shadow it with the bare render function, breaking reply detection.
+const ThreadItem = forwardRef<HTMLLIElement, ThreadItemProps>(function ThreadItemImpl(
+  { node, className, children, ...rest },
+  ref,
+) {
+  const { depth, maxDepth } = useThread();
+
+  // Sort children: nested <Thread.Item>s are replies; everything else is the
+  // comment body. Consumers write them in natural source order — the split is
+  // internal (mirrors PersonDisplay's child sorting).
+  const replies: ReactNode[] = [];
+  const body: ReactNode[] = [];
+  Children.forEach(children, (child) => {
+    if (isValidElement(child) && child.type === ThreadItem) {
+      replies.push(child);
+    } else {
+      body.push(child);
+    }
+  });
+
+  const hasReplies = replies.length > 0;
+  // Indent while under the cap; at/over it, replies render flat so the gutter
+  // stops compounding right.
+  const indented = depth < maxDepth;
+
+  return (
+    <li className={clsx(styles.item, className)} {...rest} ref={ref}>
+      <div className={styles.nodeBox}>{node}</div>
+      {hasReplies && indented ? (
+        // Indented: replies live inside content; the parent rail (anchored to the body
+        // box) bridges down to the first reply, and the per-reply trunk segments carry
+        // it the rest of the way, ending at the last elbow. Depth +1.
+        <div className={styles.content}>
+          <div className={styles.body}>
+            {body}
+            {/* Parent rail trunk above the replies — anchored to the body box. */}
+            <div className={styles.rail} aria-hidden="true" />
+          </div>
+          <ThreadContext.Provider value={{ depth: depth + 1, maxDepth }}>
+            <ul className={styles.replies}>{replies}</ul>
+          </ThreadContext.Provider>
+        </div>
+      ) : (
+        // Flat: either no replies, or at/over the cap. Replies (if any) become a
+        // direct grid child spanning both columns and keep the SAME depth so they
+        // also render flat — the indent stops compounding.
+        <>
+          <div className={styles.content}>
+            <div className={styles.body}>{body}</div>
+          </div>
+          {hasReplies && (
+            <ThreadContext.Provider value={{ depth, maxDepth }}>
+              <ul className={styles.repliesFlat}>{replies}</ul>
+            </ThreadContext.Provider>
+          )}
+        </>
+      )}
+    </li>
+  );
+});
+ThreadItem.displayName = 'Thread.Item';
+
+/**
+ * Nested-reply threading primitive: a left rail per nesting level connecting a parent comment to its replies.
+ * @see docs/components/Thread.md
+ */
+const ThreadRoot = forwardRef<HTMLUListElement, ThreadProps>(function Thread(
+  {
+    maxDepth = DEFAULT_MAX_DEPTH,
+    compact = false,
+    nodeAlign = 'header',
+    className,
+    children,
+    ...rest
+  },
+  ref,
+) {
+  return (
+    <ul
+      ref={ref}
+      className={clsx(
+        styles.root,
+        compact && styles.compact,
+        nodeAlign === 'top' && styles.alignTop,
+        className,
+      )}
+      {...rest}
+    >
+      <ThreadContext.Provider value={{ depth: 0, maxDepth }}>{children}</ThreadContext.Provider>
+    </ul>
+  );
+});
+
+export const Thread = Object.assign(ThreadRoot, { Item: ThreadItem });

package/src/components/Thread/index.ts

@@ -0,0 +1,2 @@
+export { Thread } from './Thread';
+export type { ThreadProps, ThreadItemProps, ThreadNodeAlign } from './Thread';

package/src/components/TimeField/TimeField.module.scss

@@ -0,0 +1,232 @@
+@use '../../styles/mixins' as *;
+@use '../DatePicker/DatePicker.tokens';
+
+// TimeField wrapper — text input + chevron toggle laid out in a row, with
+// the same chrome (border, radius) as the library's <Input>. The wrapper
+// IS the public element, so `inline-flex` + intrinsic width here is the
+// component's own surface (not a Rule-4 violation: setting the box-model
+// for an input-shaped field is the component's job, just like <Input>).
+.timeField {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--date-picker-time-field-gap);
+  width: var(--date-picker-time-field-width);
+  height: var(--date-picker-input-height-sm);
+  padding: 0 var(--date-picker-time-field-padding-x);
+  background: var(--date-picker-time-field-bg);
+  border: var(--border-width) solid var(--date-picker-time-field-border-color);
+  border-radius: var(--date-picker-time-field-radius);
+  transition: border-color var(--transition-fast);
+
+  &:focus-within {
+    @include focus-ring;
+
+    border-color: var(--date-picker-time-field-border-color-focus);
+  }
+}
+
+.disabled {
+  opacity: var(--opacity-disabled);
+  cursor: not-allowed;
+}
+
+// Bare input — relies on the wrapper for chrome. `flex: 1` is the same
+// Rule-4 escape hatch used by `<Input>` and `<DatePicker>`: the wrapper
+// IS the public component, and the input must fill the remaining inline
+// space alongside the chevron.
+.timeInputCore {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 0;
+  background: transparent;
+  border: none;
+  outline: none;
+  font: inherit;
+  font-size: var(--date-picker-input-font-size-sm);
+  color: var(--color-fg);
+
+  &::placeholder {
+    color: var(--date-picker-input-placeholder-fg);
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+  }
+}
+
+// Chevron toggle — small ghost button matching the picker's clear/open buttons.
+.timeToggle {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--date-picker-time-toggle-size);
+  height: var(--date-picker-time-toggle-size);
+  padding: 0;
+  background: transparent;
+  border: none;
+  border-radius: var(--date-picker-time-toggle-radius);
+  color: var(--date-picker-time-toggle-fg);
+  cursor: pointer;
+
+  &:hover:not(:disabled) {
+    background: var(--date-picker-time-toggle-bg-hover);
+    color: var(--date-picker-time-toggle-fg-hover);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+  }
+}
+
+// Portaled popover — same z + shadow as the calendar popover, slightly
+// tighter padding because the rows are small.
+.timePopover {
+  z-index: var(--date-picker-time-popover-z);
+  background: var(--date-picker-time-popover-bg);
+  border: var(--border-width) solid var(--date-picker-time-popover-border-color);
+  border-radius: var(--date-picker-time-popover-radius);
+  box-shadow: var(--date-picker-time-popover-shadow);
+  padding: var(--date-picker-time-popover-padding);
+}
+
+.timePopover[data-in-overlay] {
+  // #272: inside a Modal/Drawer (or another elevated surface) the base
+  // z-index sits below --z-modal — elevate above the host, below toasts.
+  z-index: var(--z-overlay-floating);
+}
+
+// #685: the tour's current target is INSIDE this surface — drop just under the
+// scrim (--z-tour) so only the target is lit, not the whole panel.
+.timePopover[data-in-overlay]:has([data-tour-current-target]) {
+  z-index: calc(var(--z-tour) - 1);
+}
+
+// Two-column layout for the hour + minute lists, with a thin divider.
+.timeColumns {
+  display: flex;
+  align-items: stretch;
+  gap: var(--date-picker-time-popover-gap);
+}
+
+// Reset list defaults. The global reset (`* { margin: 0 }`) zeroes the UA
+// `<ul>` margin so we don't need an explicit `margin` rule here — which is
+// also forbidden by Hard Rule 4.
+.timeColumn {
+  list-style: none;
+  padding: 0;
+  width: var(--date-picker-time-popover-column-width);
+  max-height: var(--date-picker-time-popover-max-height);
+  overflow-y: auto;
+
+  // Y scrolls, X clips. Declaring only `overflow-y` leaves X at `visible`,
+  // which the spec computes to `auto` — making a 4rem listbox column
+  // horizontally scrollable. Same fix `Rail.body` and `DropdownMenu.content`
+  // carry. Nothing overflows today; this keeps it that way if the column token
+  // shrinks or rows grow (#375).
+  overflow-x: hidden;
+}
+
+.timeColumnDivider {
+  width: var(--border-width);
+  background: var(--date-picker-time-popover-divider-color);
+}
+
+// Each list item IS the option (WAI-ARIA APG listbox pattern: no nested
+// button). The `<li>` carries the hover / current-state styling, the
+// click handler, and the keyboard handler — same chrome that used to
+// live on the inner `<button>`.
+.timeRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-1);
+  width: 100%;
+  height: var(--date-picker-time-popover-row-height);
+  padding: 0 var(--date-picker-time-popover-row-padding-x);
+  border-radius: var(--date-picker-time-popover-row-radius);
+  color: var(--date-picker-time-popover-row-fg);
+  font-size: var(--date-picker-time-popover-row-font-size);
+  cursor: pointer;
+  user-select: none;
+  text-align: left;
+
+  &:hover {
+    background: var(--date-picker-time-popover-row-hover-bg);
+  }
+
+  // INSET. `.timeColumn` above is `overflow-x: hidden`, and this row is
+  // `width: 100%`, so an outset ring puts both vertical bands outside the
+  // scrollport on every option — always, not at some size. Same signature as
+  // Tabs (#505); found by a browser sweep, not by any gate.
+  &:focus-visible {
+    @include focus-ring($offset: calc(-1 * var(--ring-offset)));
+  }
+}
+
+.timeRowCurrent {
+  background: var(--date-picker-time-popover-row-current-bg);
+  color: var(--date-picker-time-popover-row-current-fg);
+
+  &:hover {
+    background: var(--date-picker-time-popover-row-current-bg);
+  }
+}
+
+.timeRowLabel {
+  font-variant-numeric: tabular-nums;
+}
+
+.timeRowCheck {
+  flex-shrink: 0;
+}
+
+// Narrow column for the AM/PM listbox (12-hour cycle only) — two rows,
+// no scrolling, slimmer than the hours/minutes columns to keep the
+// popover compact.
+.timeColumnPeriod {
+  width: var(--date-picker-time-period-column-width);
+}
+
+// Footer row below the listbox columns — hosts the "Now" quick-pick
+// button. Border-top to visually separate from the rows above.
+.timeFooter {
+  display: flex;
+  justify-content: flex-end;
+  padding: var(--date-picker-time-popover-footer-padding);
+  border-top: var(--border-width) solid var(--date-picker-time-popover-footer-border-color);
+}
+
+// Text button with accent color — sits in the popover footer. Outside
+// the roving-tabindex listbox set; reachable via natural Tab order.
+.timeNowButton {
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- button reset
+  background: transparent;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- button reset
+  border: 0;
+  color: var(--date-picker-time-now-button-fg);
+  cursor: pointer;
+  padding: var(--space-1) var(--space-2);
+  border-radius: var(--radius-sm);
+  font: inherit;
+  font-weight: var(--font-weight-medium);
+}
+
+.timeNowButton:hover,
+.timeNowButton:focus-visible {
+  background: var(--date-picker-time-now-button-bg-hover);
+}
+
+.timeNowButton:focus-visible {
+  @include focus-ring($offset: 1px);
+}
+
+// Mirrors Input's invalid treatment so a TimeField inside a Field with an
+// error reads the same as every other control (#494).
+.timeField:has(input[aria-invalid='true']) {
+  border-color: var(--date-picker-time-field-border-color-invalid);
+}