@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Popover/Popover.module.scss

@@ -0,0 +1,177 @@
+@use './Popover.tokens';
+
+// `.content` carries chrome + the open-only scale-fade entrance. The animation
+// (transition + @starting-style + per-side transform-origin) relies on
+// Floating UI being in `transform: false` mode (see Content.tsx) so the CSS
+// `transform` property is free for the entrance.
+.content {
+  position: relative;
+  min-width: var(--popover-min-width);
+  max-width: var(--popover-max-width);
+  padding: var(--popover-padding);
+  background: var(--popover-bg);
+  color: var(--popover-fg);
+  border: var(--border-width) solid var(--popover-border-color);
+  border-radius: var(--popover-radius);
+  box-shadow: var(--popover-shadow);
+  z-index: var(--popover-z);
+  outline: none;
+
+  // Explicit so each per-side @starting-style transform has a defined
+  // resting target to interpolate to.
+  transform: none;
+  transition:
+    opacity var(--popover-transition),
+    transform var(--popover-transition);
+
+  @starting-style {
+    opacity: var(--popover-opacity-hidden);
+  }
+}
+
+.content[data-in-overlay] {
+  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.
+.content[data-in-overlay]:has([data-tour-current-target]) {
+  z-index: calc(var(--z-tour) - 1);
+}
+
+// #598: a popover holding a <ScrollArea> caps itself at the viewport
+// (`--popover-available-height`, written by Content.tsx's size middleware)
+// and becomes a flex column in which the ScrollArea is the ONLY child that
+// shrinks, so a header above it stays whole while the feed scrolls.
+// Supported shapes: the ScrollArea is a direct child, or inside ONE wrapper
+// element that is a direct child (Content > Stack > [header, ScrollArea]).
+// That one wrapper must lay its children out as a column: a `<Stack>`, or a
+// plain element (div/form/Card), which the `:where` rule below lays out as a
+// column. A row wrapper such as `<Cluster>` is not supported (the popover
+// caps but the feed overflows it) — put the ScrollArea in a Stack instead.
+// A `hidden` wrapper doesn't count, so a ScrollArea only in a hidden view of
+// a two-view popover doesn't cap the visible view. The selectors are
+// `>`-anchored on purpose: deeper nesting can't pass the shrink down, so it
+// would cap the chrome while the rows paint outside it. Such popovers stay
+// uncapped (pre-#598).
+// Compound-internal layout like Card's `.scroll`: the popover lays out its
+// own content box, not a consumer-positioned component. No `overflow` here,
+// since it would clip the arrow.
+.content:has(> [data-scroll-area], > :not([hidden]) > [data-scroll-area]) {
+  display: flex;
+  flex-direction: column;
+  max-height: var(--popover-available-height, none);
+
+  > * {
+    flex-shrink: 0;
+  }
+
+  > [data-scroll-area] {
+    flex-shrink: 1;
+    min-height: 0;
+  }
+
+  > :has(> [data-scroll-area]) {
+    flex-shrink: 1;
+    min-height: 0;
+  }
+}
+
+// The one wrapper's LAYOUT, at zero specificity: a wrapper with its own
+// display (a Stack) keeps it; a plain div/form becomes a column so it passes
+// the shrink down. `:not([hidden])`: an author `display` would
+// otherwise override the UA `[hidden] { display: none }` (cf. Rail's
+// `.subitems[hidden]`), showing a hidden view of a two-view popover.
+:where(
+  .content:has(> [data-scroll-area], > :not([hidden]) > [data-scroll-area])
+    > :has(> [data-scroll-area]):not([hidden])
+) {
+  display: flex;
+  flex-direction: column;
+}
+
+// The wrapper's other children (a header, a `<Text truncate>`) don't shrink
+// with the ScrollArea. Zero specificity so a consumer class setting
+// `flex-shrink` still wins.
+:where(
+  .content:has(> [data-scroll-area], > :not([hidden]) > [data-scroll-area])
+    > :has(> [data-scroll-area])
+    > :not([data-scroll-area])
+) {
+  flex-shrink: 0;
+}
+
+.arrow {
+  position: absolute;
+  width: var(--popover-arrow-size);
+  height: var(--popover-arrow-size);
+  background: var(--popover-arrow-bg);
+  border-right: var(--border-width) solid var(--popover-arrow-border-color);
+  border-bottom: var(--border-width) solid var(--popover-arrow-border-color);
+  transform: rotate(45deg);
+  pointer-events: none;
+}
+
+// Each data-side rotates the arrow so the "visible" two borders face outward
+// (i.e. away from the panel chrome). The default rule above uses bottom +
+// right borders (panel above trigger → arrow pokes downward), which matches
+// data-side='top'. Override for the other three sides:
+.content[data-side='bottom'] .arrow {
+  border-top: var(--border-width) solid var(--popover-arrow-border-color);
+  border-left: var(--border-width) solid var(--popover-arrow-border-color);
+  border-right: 0;
+  border-bottom: 0;
+}
+
+.content[data-side='left'] .arrow {
+  border-top: var(--border-width) solid var(--popover-arrow-border-color);
+  border-right: var(--border-width) solid var(--popover-arrow-border-color);
+  border-bottom: 0;
+  border-left: 0;
+}
+
+.content[data-side='right'] .arrow {
+  border-bottom: var(--border-width) solid var(--popover-arrow-border-color);
+  border-left: var(--border-width) solid var(--popover-arrow-border-color);
+  border-top: 0;
+  border-right: 0;
+}
+
+// --- Open-only entrance: per-side origin + starting transform -----------
+.content[data-side='top'] {
+  transform-origin: bottom center;
+
+  @starting-style {
+    transform: scale(0.95) translateY(4px);
+  }
+}
+
+.content[data-side='bottom'] {
+  transform-origin: top center;
+
+  @starting-style {
+    transform: scale(0.95) translateY(-4px);
+  }
+}
+
+.content[data-side='left'] {
+  transform-origin: right center;
+
+  @starting-style {
+    transform: scale(0.95) translateX(4px);
+  }
+}
+
+.content[data-side='right'] {
+  transform-origin: left center;
+
+  @starting-style {
+    transform: scale(0.95) translateX(-4px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .content {
+    transition: none;
+  }
+}

package/src/components/Popover/Popover.tokens.scss

@@ -0,0 +1,22 @@
+// Popover.tokens.scss — Component-scoped tokens for <Popover>. Each token defaults to the primitive the SCSS used before this migration. Floating-positioned panel base used by ConfirmationPopover; Tooltip and DropdownMenu maintain their own surfaces.
+:root {
+  // Panel surface
+  --popover-bg: var(--color-bg);
+  --popover-fg: var(--color-fg);
+  --popover-border-color: var(--color-border);
+  --popover-radius: var(--radius-md);
+  --popover-shadow: var(--shadow-lg);
+  --popover-padding: var(--space-3);
+  --popover-min-width: var(--size-popover-min-width);
+  --popover-max-width: var(--size-popover-max-width);
+  --popover-z: var(--z-popover);
+
+  // Entrance transition
+  --popover-transition: var(--transition-base);
+  --popover-opacity-hidden: var(--opacity-hidden);
+
+  // Arrow
+  --popover-arrow-size: var(--space-3);
+  --popover-arrow-bg: var(--color-bg);
+  --popover-arrow-border-color: var(--color-border);
+}

package/src/components/Popover/Popover.tsx

@@ -0,0 +1,23 @@
+import { PopoverRoot } from './PopoverRoot';
+import { Trigger } from './Trigger';
+import { Anchor } from './Anchor';
+import { Content } from './Content';
+import { Heading } from './Heading';
+import { Close } from './Close';
+
+type PopoverNamespace = typeof PopoverRoot & {
+  Trigger: typeof Trigger;
+  Anchor: typeof Anchor;
+  Content: typeof Content;
+  Heading: typeof Heading;
+  Close: typeof Close;
+};
+
+const Popover = PopoverRoot as PopoverNamespace;
+Popover.Trigger = Trigger;
+Popover.Anchor = Anchor;
+Popover.Content = Content;
+Popover.Heading = Heading;
+Popover.Close = Close;
+
+export { Popover };

package/src/components/Popover/PopoverRoot.tsx

@@ -0,0 +1,75 @@
+import { useCallback, useId, useRef, useState, type ReactNode } from 'react';
+import { PopoverContext, type PopoverContextValue } from './context';
+import { sanitizeId } from '../_internal/refs';
+
+export interface PopoverProps {
+  /**
+   * Must contain exactly one `<Popover.Trigger>` (or `<Popover.Anchor>` for a
+   * controlled popover whose anchor owns its own toggle + ARIA) and one
+   * `<Popover.Content>`. `<Popover.Heading>` and `<Popover.Close>` are optional
+   * and may appear anywhere inside `<Popover.Content>`.
+   */
+  children: ReactNode;
+  /**
+   * Controlled open state. Provide alongside `onOpenChange` to drive open
+   * externally. Omit both to let Popover own its state (the common case).
+   */
+  open?: boolean;
+  /** Fired whenever Popover wants to change open state. Required when `open` is provided. */
+  onOpenChange?: (open: boolean) => void;
+  /** Default open state for uncontrolled usage. Defaults to `false`. */
+  defaultOpen?: boolean;
+  /**
+   * Reserved future hint. v1 ignores the value and always renders non-modal.
+   * Will gate focus-trap + inert-background once `<Modal>` lands.
+   */
+  modal?: boolean;
+}
+
+/**
+ * Non-modal floating panel opened from a trigger, holding arbitrary interactive content (WAI-ARIA non-modal dialog); compound `Popover.Trigger`, `Content`, `Heading`, `Close`, `Anchor`.
+ * @see docs/components/Popover.md
+ */
+export function PopoverRoot({
+  children,
+  open: controlledOpen,
+  onOpenChange,
+  defaultOpen = false,
+  modal: _modal = false,
+}: PopoverProps) {
+  const isControlled = controlledOpen !== undefined;
+  const [uncontrolled, setUncontrolled] = useState(defaultOpen);
+  const open = isControlled ? (controlledOpen as boolean) : uncontrolled;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      onOpenChange?.(next);
+      if (!isControlled) setUncontrolled(next);
+    },
+    [isControlled, onOpenChange],
+  );
+
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const contentRef = useRef<HTMLDivElement | null>(null);
+  const reactId = useId();
+  const contentId = `popover-${sanitizeId(reactId)}`;
+  const [headingId, setHeadingId] = useState<string | null>(null);
+
+  const closeAll = useCallback(() => {
+    setOpen(false);
+    triggerRef.current?.focus({ preventScroll: true });
+  }, [setOpen]);
+
+  const value: PopoverContextValue = {
+    open,
+    setOpen,
+    triggerRef,
+    contentRef,
+    contentId,
+    headingId,
+    setHeadingId,
+    closeAll,
+  };
+
+  return <PopoverContext.Provider value={value}>{children}</PopoverContext.Provider>;
+}

package/src/components/Popover/Trigger.tsx

@@ -0,0 +1,86 @@
+import {
+  cloneElement,
+  isValidElement,
+  useCallback,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type MouseEvent as ReactMouseEvent,
+  type ReactElement,
+  type Ref,
+} from 'react';
+import { usePopoverContext } from './context';
+import { chain, mergeRefs } from '../_internal/refs';
+
+export interface PopoverTriggerProps {
+  /**
+   * Exactly one React element that accepts a ref. The Trigger clones this
+   * element to inject `aria-haspopup`, `aria-expanded`, `aria-controls`, a
+   * click handler that toggles the popover, and a keydown handler that opens
+   * on Enter/Space. `<Button>` and raw `<button>` both qualify; a custom
+   * component without `forwardRef` does not.
+   */
+  children: ReactElement;
+  /**
+   * Override the `aria-haspopup` value injected onto the trigger child.
+   * Defaults to `'dialog'` (matching the role of `Popover.Content`). Pass
+   * `'listbox'` for picker-style compound usages where the popover surfaces
+   * a listbox rather than a generic dialog.
+   *
+   * @default 'dialog'
+   */
+  'aria-haspopup'?: 'dialog' | 'listbox' | 'menu' | 'tree' | 'grid' | 'true' | 'false';
+}
+
+/**
+ * Clones its single ref-accepting child to inject the ref, ARIA and the click toggle (`Popover.Trigger`).
+ * @see docs/components/Popover.md
+ */
+export function Trigger({
+  children,
+  'aria-haspopup': ariaHaspopup = 'dialog',
+}: PopoverTriggerProps) {
+  const ctx = usePopoverContext('Trigger');
+
+  if (!isValidElement(children)) {
+    throw new Error('<Popover.Trigger> requires exactly one React element child.');
+  }
+
+  const childProps = children.props as {
+    ref?: Ref<HTMLElement>;
+    onClick?: (e: ReactMouseEvent<HTMLElement>) => void;
+    onKeyDown?: (e: ReactKeyboardEvent<HTMLElement>) => void;
+  };
+
+  // stopPropagation: prevents the click from bubbling to an ancestor that
+  // might also act on it (e.g., a <DropdownMenu.Item> whose onClick fires
+  // onSelect and closes the menu, which would unmount this Popover before
+  // it gets a chance to open). The trigger's job is to consume the click;
+  // nothing meaningful should run on parents.
+  const handleClick = useCallback(
+    (e: ReactMouseEvent<HTMLElement>) => {
+      e.stopPropagation();
+      ctx.setOpen(!ctx.open);
+    },
+    [ctx],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: ReactKeyboardEvent<HTMLElement>) => {
+      if (ctx.open) return;
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        e.stopPropagation();
+        ctx.setOpen(true);
+      }
+    },
+    [ctx],
+  );
+
+  return cloneElement(children, {
+    ref: mergeRefs(ctx.triggerRef, childProps.ref),
+    'aria-haspopup': ariaHaspopup,
+    'aria-expanded': ctx.open,
+    'aria-controls': ctx.open ? ctx.contentId : undefined,
+    onClick: chain(childProps.onClick, handleClick),
+    onKeyDown: chain(childProps.onKeyDown, handleKeyDown),
+  } as object);
+}

package/src/components/Popover/context.ts

@@ -0,0 +1,22 @@
+import { createContext, useContext, type RefObject } from 'react';
+
+export interface PopoverContextValue {
+  open: boolean;
+  setOpen: (next: boolean) => void;
+  triggerRef: RefObject<HTMLElement | null>;
+  contentRef: RefObject<HTMLDivElement | null>;
+  contentId: string;
+  headingId: string | null;
+  setHeadingId: (id: string | null) => void;
+  closeAll: () => void;
+}
+
+export const PopoverContext = createContext<PopoverContextValue | null>(null);
+
+export function usePopoverContext(componentName: string): PopoverContextValue {
+  const ctx = useContext(PopoverContext);
+  if (!ctx) {
+    throw new Error(`<Popover.${componentName}> must be used inside <Popover>.`);
+  }
+  return ctx;
+}

package/src/components/Popover/index.ts

@@ -0,0 +1,7 @@
+export { Popover } from './Popover';
+export type { PopoverProps } from './PopoverRoot';
+export type { PopoverTriggerProps } from './Trigger';
+export type { PopoverAnchorProps } from './Anchor';
+export type { PopoverContentProps, PopoverSide, PopoverAlign } from './Content';
+export type { PopoverHeadingProps } from './Heading';
+export type { PopoverCloseProps } from './Close';

package/src/components/Progress/Progress.module.scss

@@ -0,0 +1,110 @@
+@use './Progress.tokens';
+
+.progress {
+  display: flex;
+  align-items: center;
+  gap: var(--progress-gap);
+  width: 100%;
+}
+
+.track {
+  flex: 1;
+  background: var(--progress-track-bg);
+  border-radius: var(--progress-track-radius);
+  overflow: hidden;
+}
+
+.fill {
+  height: 100%;
+  background: var(--progress-fill-bg);
+  border-radius: var(--progress-fill-radius);
+  transition: width var(--transition-base);
+}
+
+.sizeSm .track,
+.sizeSm .fill {
+  height: 4px;
+}
+
+.sizeMd .track,
+.sizeMd .fill {
+  height: 8px;
+}
+
+.sizeLg .track,
+.sizeLg .fill {
+  height: 12px;
+}
+
+.toneDefault .fill {
+  background: var(--progress-fill-bg);
+}
+
+.toneSuccess .fill {
+  background: var(--progress-fill-bg-success);
+}
+
+.toneWarning .fill {
+  background: var(--progress-fill-bg-warning);
+}
+
+.toneDanger .fill {
+  background: var(--progress-fill-bg-danger);
+}
+
+.indeterminate {
+  // !important ensures the 30% fill width wins against any specificity
+  // collision with the size-* rules that set `.fill { height: ... }` for
+  // each track height (the `.fill` selector specificity matches `.indeterminate`).
+  width: 30% !important;
+  animation: progress-slide 1.2s linear infinite;
+
+  // Indeterminate always uses the accent color — tone semantics don't apply
+  // to an unknown total. Override any .tone-* rule that would otherwise
+  // win via specificity.
+  background: var(--progress-fill-bg-indeterminate) !important;
+
+  // Disable the width transition so determinate→indeterminate switches don't
+  // animate from the determinate width down to 30% before the loop fires.
+  transition: none;
+}
+
+@keyframes progress-slide {
+  0% {
+    transform: translateX(-100%);
+  }
+
+  100% {
+    transform: translateX(400%);
+  }
+}
+
+.label {
+  font-size: var(--progress-label-font-size);
+  color: var(--progress-label-fg);
+  font-weight: var(--progress-label-font-weight);
+  font-variant-numeric: tabular-nums;
+  flex-shrink: 0;
+
+  // Cap the label so a long string can't collapse the track. The bar should
+  // win the layout argument; long labels should ellipsis or the consumer
+  // should pre-truncate.
+  max-width: 50%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .indeterminate {
+    animation: none;
+
+    // Replace the sliding animation with a static accent fill so the user
+    // still gets a visible "in progress" cue.
+    width: 100% !important;
+  }
+
+  .fill {
+    transition: none;
+  }
+}

package/src/components/Progress/Progress.tokens.scss

@@ -0,0 +1,44 @@
+// Progress.tokens.scss — Component-scoped tokens for <Progress>. Cluster
+// gap, track bg + radius, fill bg per tone, fill radius, per-size track
+// heights (literal px), and the label typography. The width transition
+// stays primitive since --motion-* is not tokenized.
+:root {
+  // Cluster
+  --progress-gap: var(--space-2);
+
+  // Track
+  --progress-track-bg: var(--color-border);
+  --progress-track-radius: var(--radius-full);
+
+  // Fill — default tone is accent.
+  --progress-fill-bg: var(--color-accent);
+  --progress-fill-radius: var(--radius-full);
+  --progress-fill-bg-success: var(--color-success);
+
+  // @contrast --color-warning on --color-border = 1.63:1 light
+  // @contrast --color-warning-strong on --color-border = 4.55:1 light
+  // @contrast --color-success on --color-border = 3.90:1 light
+  // @contrast --color-danger on --color-border = 4.13:1 light
+  // @contrast --color-accent on --color-border = 5.21:1 light
+  // @contrast --color-warning on --color-border = 6.77:1 dark
+  // @contrast --color-success on --color-border = 5.23:1 dark
+  // @contrast --color-danger on --color-border = 3.73:1 dark
+  // @contrast --color-accent on --color-border = 4.23:1 dark
+  // The track is --color-border, not --color-bg-muted (#647): a bg-muted track
+  // vanished on every bg-muted surface (StatTile, table headers, muted panels).
+  // warning uses --color-warning-strong: the bare amber measures 1.63:1 against
+  // the track, below 1.4.11's 3:1 — the ONLY tone that fails there (light success
+  // 3.90:1, danger 4.13:1, accent 5.21:1), so the fill is wrong, not the track.
+  // In dark nothing fails (amber 6.77:1, success 5.23:1, danger 3.73:1, accent
+  // 4.23:1). See #481.
+  --progress-fill-bg-warning: var(--color-warning-strong);
+  --progress-fill-bg-danger: var(--color-danger);
+
+  // Indeterminate always uses accent (tone semantics don't apply to unknown total).
+  --progress-fill-bg-indeterminate: var(--color-accent);
+
+  // Label
+  --progress-label-font-size: var(--font-size-sm);
+  --progress-label-fg: var(--color-fg-muted);
+  --progress-label-font-weight: var(--font-weight-medium);
+}