@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/PageHeader/PageHeader.module.scss

@@ -0,0 +1,197 @@
+@use '../../styles/mixins' as *;
+@use './PageHeader.tokens';
+
+// Default layout — no Aside. Two columns: title block, actions.
+// Used by list pages (Dashboard, Contacts, Deals, Members, Audit, …).
+.root {
+  display: grid;
+  grid-template-areas:
+    'breadcrumb breadcrumb'
+    'title actions'
+    'subtitle actions'
+    'meta actions';
+
+  // minmax(0, 1fr) title, and an actions track capped at everything but
+  // --page-header-title-min (+ the gap). A wide header sizes the actions to
+  // max-content on one line; once they'd leave the title less than the
+  // title-min, the cap makes them wrap. The cap is a fit-content() LIMIT,
+  // not a floor on the title, so a single action item wider than the
+  // remaining space still gets its min-content — the title shrinks instead
+  // of the header overflowing (as long as that item itself fits). (An
+  // `auto` track here crushed the title in a narrow container on a desktop
+  // viewport, where the 640px media query never fires; a hard title floor
+  // overflowed the header, #550.)
+  grid-template-columns:
+    minmax(0, 1fr)
+    fit-content(calc(100% - var(--page-header-title-min) - var(--page-header-col-gap)));
+
+  // Column gap only. Row gap is 0 because Title/Subtitle/Meta have their
+  // own line-height which naturally separates them — adding an explicit
+  // row gap puts a visible empty band between the title and the count
+  // beneath it (e.g., "Audit log" + "284+ events"). Consumers wanting more
+  // breathing room between rows can compose with Stack outside.
+  gap: 0 var(--page-header-col-gap);
+
+  // No top padding — the page container (AppShell content, modal body,
+  // card padding, etc.) provides the top spacing above the header. Adding
+  // top padding here doubled with the container's own padding and pushed
+  // the title 40px from the topbar on every consumer page. Bottom padding
+  // stays because it spaces the header content above the border-bottom
+  // divider (when borderBottom is enabled).
+  padding-block: 0 var(--page-header-padding-block-end);
+}
+
+// Layout with Aside — three columns: aside (hero avatar etc.), title
+// block, actions. Used by detail pages (ContactDetail). The modifier is
+// applied by the Root component only when an <Aside> child is present;
+// without this switch, the empty aside column-gap would still apply and
+// push the title 12px right on every consumer that omits Aside.
+.rootWithAside {
+  grid-template-areas:
+    'breadcrumb breadcrumb breadcrumb'
+    'aside title actions'
+    'aside subtitle actions'
+    'aside meta actions';
+  grid-template-columns:
+    auto
+    minmax(0, 1fr)
+    fit-content(calc(100% - var(--page-header-title-min) - var(--page-header-col-gap)));
+}
+
+.rootWithBorder {
+  border-bottom: var(--border-width) solid var(--page-header-border-color);
+}
+
+.breadcrumb {
+  grid-area: breadcrumb;
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  min-width: 0;
+  gap: var(--page-header-breadcrumb-gap);
+
+  // Separate the breadcrumb from the title row (grid row-gap is 0).
+  padding-block-end: var(--page-header-breadcrumb-gap-block);
+}
+
+.breadcrumbInner {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  min-width: 0;
+}
+
+.backButton {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--page-header-back-button-size);
+  height: var(--page-header-back-button-size);
+  background: transparent;
+  border: none;
+  border-radius: var(--page-header-back-button-radius);
+  color: var(--page-header-back-button-fg);
+
+  // CSS keyword — interactive trigger.
+  // stylelint-disable-next-line scale-unlimited/declaration-strict-value -- CSS keyword
+  cursor: pointer;
+
+  // CSS keyword — kill the default underline when rendered as <a>.
+  // stylelint-disable-next-line scale-unlimited/declaration-strict-value -- CSS keyword
+  text-decoration: none;
+}
+
+.backButton:hover:not(:disabled) {
+  background: var(--page-header-back-button-bg-hover);
+  color: var(--page-header-back-button-fg-hover);
+}
+
+.backButton:focus-visible {
+  @include focus-ring;
+}
+
+.backButton:disabled {
+  // CSS keyword — disabled affordance.
+  // stylelint-disable-next-line scale-unlimited/declaration-strict-value -- CSS keyword
+  cursor: not-allowed;
+  opacity: var(--page-header-back-button-opacity-disabled);
+}
+
+.aside {
+  grid-area: aside;
+
+  // stylelint-disable-next-line property-disallowed-list -- grid slot needs vertical centering within its cell
+  align-self: center;
+}
+
+.title {
+  grid-area: title;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+.subtitle {
+  grid-area: subtitle;
+  font-size: var(--page-header-subtitle-font-size);
+  color: var(--page-header-subtitle-fg);
+  line-height: var(--page-header-subtitle-line-height);
+  overflow-wrap: anywhere;
+}
+
+.meta {
+  grid-area: meta;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--page-header-meta-gap);
+
+  // Separate the meta row from whatever sits above it (Title or Subtitle) —
+  // grid row-gap is 0, so without this badges touch the title's descenders (#657).
+  padding-block-start: var(--page-header-meta-gap-block);
+}
+
+// #550: the actions wrap so the (capped) actions track can shrink below
+// their one-line width. No min-width: 0 — the track must keep the widest
+// single item's min-content, or it would overflow the header.
+.actions {
+  grid-area: actions;
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+
+  // Wrapped rows end at the right edge like the first one — on narrow
+  // viewports too, so the primary action stays at the thumb-side edge (#564).
+  justify-content: flex-end;
+  gap: var(--page-header-actions-gap);
+
+  // stylelint-disable-next-line property-disallowed-list -- grid slot needs vertical centering within its cell
+  align-self: center;
+}
+
+// ─── Responsive: actions wrap below the title on narrow viewports ────────
+@media (max-width: 640px) {
+  .root {
+    grid-template-areas:
+      'breadcrumb'
+      'title'
+      'subtitle'
+      'meta'
+      'actions';
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .rootWithAside {
+    grid-template-areas:
+      'breadcrumb breadcrumb'
+      'aside title'
+      'aside subtitle'
+      'aside meta'
+      'actions actions';
+    grid-template-columns: auto minmax(0, 1fr);
+  }
+
+  .actions {
+    // stylelint-disable-next-line property-disallowed-list -- internal responsive spacing in this layout primitive
+    margin-top: var(--page-header-actions-margin-top-narrow);
+  }
+}

package/src/components/PageHeader/PageHeader.tokens.scss

@@ -0,0 +1,41 @@
+// PageHeader.tokens.scss — Component-scoped tokens for <PageHeader>. Each
+// token defaults to the primitive the SCSS used before this migration.
+:root {
+  // Grid + spacing
+  // Room the actions track leaves for the title column (it is capped at
+  // 100% minus this and the gap): past it the actions wrap instead of
+  // crushing the title (#550).
+  --page-header-title-min: var(--measure-2xs);
+  --page-header-col-gap: var(--space-3);
+  --page-header-padding-block-end: var(--space-3);
+  --page-header-border-color: var(--color-border);
+
+  // Breadcrumb + slot gaps
+  --page-header-breadcrumb-gap: var(--space-2);
+  --page-header-meta-gap: var(--space-2);
+  --page-header-actions-gap: var(--space-2);
+
+  // Vertical separation between header rows. The grid runs row-gap:0 (so the
+  // title/subtitle stay tight), so these rows contribute their own block
+  // padding: space below the breadcrumb (before the title), and above the meta
+  // (after the title or subtitle, always).
+  --page-header-breadcrumb-gap-block: var(--space-2);
+  --page-header-meta-gap-block: var(--space-2);
+
+  // Back button
+  --page-header-back-button-size: 32px;
+  --page-header-back-button-radius: var(--radius-sm);
+  --page-header-back-button-fg: var(--color-fg-muted);
+  --page-header-back-button-bg-hover: var(--color-bg-muted);
+  --page-header-back-button-fg-hover: var(--color-fg);
+  --page-header-back-button-opacity-disabled: var(--opacity-disabled);
+
+  // Subtitle
+  --page-header-subtitle-font-size: var(--font-size-md);
+  --page-header-subtitle-fg: var(--color-fg-muted);
+  --page-header-subtitle-line-height: var(--line-height-tight);
+
+  // Responsive (narrow viewports) — actions wrap below; this margin-top
+  // pushes them away from the meta row above.
+  --page-header-actions-margin-top-narrow: var(--space-3);
+}

package/src/components/PageHeader/PageHeader.tsx

@@ -0,0 +1,310 @@
+import {
+  Children,
+  forwardRef,
+  Fragment,
+  isValidElement,
+  useEffect,
+  type AnchorHTMLAttributes,
+  type ButtonHTMLAttributes,
+  type ComponentType,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { ChevronLeft } from 'lucide-react';
+import clsx from 'clsx';
+import { useTranslation } from '../../i18n/useTranslation';
+import { Title, type TitleSize } from '../Title';
+import styles from './PageHeader.module.scss';
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface PageHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Render a 1px bottom border under the header. Default `true`. Set
+   * `false` when placing a `<Tabs>` component as a sibling below — Tabs
+   * has its own `border-bottom`, and you don't want the double line.
+   */
+  borderBottom?: boolean;
+}
+
+export interface PageHeaderBreadcrumbProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+}
+
+export interface PageHeaderBackButtonProps {
+  /**
+   * If set, renders as `<a href={href}>`. Mutually exclusive with
+   * `onClick` — passing both renders as `<button>` (the onClick wins)
+   * and emits a dev-only warning.
+   */
+  href?: string;
+  /**
+   * If set, renders as `<button type="button" onClick={onClick}>`.
+   * Mutually exclusive with `href`.
+   */
+  onClick?: () => void;
+  /**
+   * Accessible label. Defaults to the i18n value at `pageHeader.back`
+   * (`'Go back'` in English) when omitted OR empty — an empty string is not an
+   * explicit name, so it takes the default too.
+   */
+  'aria-label'?: string;
+  /** Icon to render. Default `<ChevronLeft size={16}>` from lucide-react. */
+  icon?: ReactNode;
+}
+
+export interface PageHeaderAsideProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+}
+
+export interface PageHeaderTitleProps {
+  /**
+   * Heading semantic level (1–6). Default `1`. Passes through to
+   * `<Title order={order}>` so the rendered element is `<h1>`–`<h6>`.
+   */
+  order?: 1 | 2 | 3 | 4 | 5 | 6;
+  /**
+   * Visual size override (decouples from semantic level). Pass-through to
+   * `<Title size>` — useful for "section-level page headers" where the
+   * h-level is 2 but you want it to LOOK like an h1.
+   */
+  size?: TitleSize;
+  /**
+   * Keep the title on one line, ending in an ellipsis where the title column
+   * ends (at the actions on wide layouts) instead of wrapping. Pass-through to
+   * `<Title truncate>`. Defaults to `false`. Anything inline AFTER the text
+   * (e.g. a status badge) is clipped with it — put badges in `PageHeader.Meta`.
+   * Screen readers still get the full text (don't add `aria-label`); sighted
+   * users don't, so show the full title somewhere else too if it matters.
+   */
+  truncate?: boolean;
+  children: ReactNode;
+}
+
+export interface PageHeaderSubtitleProps extends HTMLAttributes<HTMLParagraphElement> {
+  children: ReactNode;
+}
+
+export interface PageHeaderMetaProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+}
+
+export interface PageHeaderActionsProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────────
+
+/**
+ * Flatten one level of React Fragments out of children. `React.Children.toArray`
+ * does NOT recursively unwrap fragments — this helper handles the common case
+ * of wrapping a single sub-component in `<>...</>`. Deeper nesting (HOCs, etc.)
+ * is intentionally NOT supported; documented as an anti-pattern.
+ */
+function flattenChildren(children: ReactNode): ReactNode[] {
+  const flat: ReactNode[] = [];
+  Children.toArray(children).forEach((child) => {
+    if (isValidElement(child) && child.type === Fragment) {
+      flat.push(
+        ...Children.toArray((child as ReactElement<{ children: ReactNode }>).props.children),
+      );
+    } else {
+      flat.push(child);
+    }
+  });
+  return flat;
+}
+
+/** Find the first child whose `type` equals the given component. */
+function findSlot<P>(children: ReactNode, type: ComponentType<P>): ReactElement<P> | undefined {
+  return flattenChildren(children).find(
+    (c): c is ReactElement<P> => isValidElement(c) && c.type === type,
+  );
+}
+
+// ─── Sub-components ──────────────────────────────────────────────────────
+
+/**
+ * Top-row slot for a `<Breadcrumb>`; shares the row with `PageHeader.BackButton`.
+ * @see docs/components/PageHeader.md
+ */
+export function PageHeaderBreadcrumb({ children, className, ...rest }: PageHeaderBreadcrumbProps) {
+  return (
+    <div className={clsx(styles.breadcrumbInner, className)} {...rest}>
+      {children}
+    </div>
+  );
+}
+PageHeaderBreadcrumb.displayName = 'PageHeaderBreadcrumb';
+
+/**
+ * Compact back-navigation icon button: an `<a href>` or a `<button onClick>` (`PageHeader.BackButton`).
+ * @see docs/components/PageHeader.md
+ */
+export function PageHeaderBackButton({
+  href,
+  onClick,
+  'aria-label': ariaLabelProp,
+  icon = <ChevronLeft size={16} />,
+}: PageHeaderBackButtonProps) {
+  const t = useTranslation();
+  const ariaLabel = ariaLabelProp || t('pageHeader.back');
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'production' && href && onClick) {
+      console.warn(
+        '<PageHeader.BackButton> received both `href` and `onClick`. Rendering as <button>; `href` is ignored.',
+      );
+    }
+    if (process.env.NODE_ENV !== 'production' && !href && !onClick) {
+      console.warn(
+        '<PageHeader.BackButton> rendered without `href` or `onClick`. Rendering as a disabled <button>.',
+      );
+    }
+  }, [href, onClick]);
+
+  if (onClick) {
+    const buttonProps: ButtonHTMLAttributes<HTMLButtonElement> = {
+      type: 'button',
+      onClick,
+      'aria-label': ariaLabel,
+      className: styles.backButton,
+    };
+    return <button {...buttonProps}>{icon}</button>;
+  }
+  if (href) {
+    const anchorProps: AnchorHTMLAttributes<HTMLAnchorElement> = {
+      href,
+      'aria-label': ariaLabel,
+      className: styles.backButton,
+    };
+    return <a {...anchorProps}>{icon}</a>;
+  }
+  return (
+    <button type="button" disabled aria-label={ariaLabel} className={styles.backButton}>
+      {icon}
+    </button>
+  );
+}
+PageHeaderBackButton.displayName = 'PageHeaderBackButton';
+
+/**
+ * Leading slot left of the title row (avatar, icon or image) (`PageHeader.Aside`).
+ * @see docs/components/PageHeader.md
+ */
+export function PageHeaderAside({ children, className, ...rest }: PageHeaderAsideProps) {
+  return (
+    <div className={clsx(styles.aside, className)} {...rest}>
+      {children}
+    </div>
+  );
+}
+PageHeaderAside.displayName = 'PageHeaderAside';
+
+/**
+ * The page heading: `order` sets the semantic level, `size` the visual size, `truncate` keeps it on one line (`PageHeader.Title`).
+ * @see docs/components/PageHeader.md
+ */
+export function PageHeaderTitle({ order = 1, size, truncate, children }: PageHeaderTitleProps) {
+  return (
+    <Title order={order} size={size} truncate={truncate} className={styles.title}>
+      {children}
+    </Title>
+  );
+}
+PageHeaderTitle.displayName = 'PageHeaderTitle';
+
+/**
+ * One-line muted description below the title (`PageHeader.Subtitle`).
+ * @see docs/components/PageHeader.md
+ */
+export function PageHeaderSubtitle({ children, className, ...rest }: PageHeaderSubtitleProps) {
+  return (
+    <p className={clsx(styles.subtitle, className)} {...rest}>
+      {children}
+    </p>
+  );
+}
+PageHeaderSubtitle.displayName = 'PageHeaderSubtitle';
+
+/**
+ * Wrapping flex row for badges, timestamps and status chips below the subtitle (`PageHeader.Meta`).
+ * @see docs/components/PageHeader.md
+ */
+export function PageHeaderMeta({ children, className, ...rest }: PageHeaderMetaProps) {
+  return (
+    <div className={clsx(styles.meta, className)} {...rest}>
+      {children}
+    </div>
+  );
+}
+PageHeaderMeta.displayName = 'PageHeaderMeta';
+
+/**
+ * Right-aligned, wrapping action row that drops below the title under 640px (`PageHeader.Actions`).
+ * @see docs/components/PageHeader.md
+ */
+export function PageHeaderActions({ children, className, ...rest }: PageHeaderActionsProps) {
+  return (
+    <div className={clsx(styles.actions, className)} {...rest}>
+      {children}
+    </div>
+  );
+}
+PageHeaderActions.displayName = 'PageHeaderActions';
+
+// ─── Root ────────────────────────────────────────────────────────────────
+
+/**
+ * Top-of-page heading area bundling seven optional slots (Breadcrumb, BackButton, Aside, Title, Subtitle, Meta, Actions) in one grid.
+ * @see docs/components/PageHeader.md
+ */
+const PageHeaderRoot = forwardRef<HTMLDivElement, PageHeaderProps>(function PageHeaderRoot(
+  { borderBottom = true, className, children, ...rest },
+  ref,
+) {
+  const breadcrumb = findSlot(children, PageHeaderBreadcrumb);
+  const backButton = findSlot(children, PageHeaderBackButton);
+  const aside = findSlot(children, PageHeaderAside);
+  const title = findSlot(children, PageHeaderTitle);
+  const subtitle = findSlot(children, PageHeaderSubtitle);
+  const meta = findSlot(children, PageHeaderMeta);
+  const actions = findSlot(children, PageHeaderActions);
+
+  return (
+    <div
+      ref={ref}
+      className={clsx(
+        styles.root,
+        aside && styles.rootWithAside,
+        borderBottom && styles.rootWithBorder,
+        className,
+      )}
+      {...rest}
+    >
+      {(breadcrumb || backButton) && (
+        <div className={styles.breadcrumb}>
+          {backButton}
+          {breadcrumb}
+        </div>
+      )}
+      {aside}
+      {title}
+      {subtitle}
+      {meta}
+      {actions}
+    </div>
+  );
+});
+PageHeaderRoot.displayName = 'PageHeader';
+
+/** Compound API: `<PageHeader>` + 7 sub-components. */
+export const PageHeader = Object.assign(PageHeaderRoot, {
+  Breadcrumb: PageHeaderBreadcrumb,
+  BackButton: PageHeaderBackButton,
+  Aside: PageHeaderAside,
+  Title: PageHeaderTitle,
+  Subtitle: PageHeaderSubtitle,
+  Meta: PageHeaderMeta,
+  Actions: PageHeaderActions,
+});

package/src/components/PageHeader/index.ts

@@ -0,0 +1,20 @@
+export {
+  PageHeader,
+  PageHeaderBreadcrumb,
+  PageHeaderBackButton,
+  PageHeaderAside,
+  PageHeaderTitle,
+  PageHeaderSubtitle,
+  PageHeaderMeta,
+  PageHeaderActions,
+} from './PageHeader';
+export type {
+  PageHeaderProps,
+  PageHeaderBreadcrumbProps,
+  PageHeaderBackButtonProps,
+  PageHeaderAsideProps,
+  PageHeaderTitleProps,
+  PageHeaderSubtitleProps,
+  PageHeaderMetaProps,
+  PageHeaderActionsProps,
+} from './PageHeader';

package/src/components/Pagination/Pagination.module.scss

@@ -0,0 +1,117 @@
+@use '../../styles/mixins' as *;
+@use './Pagination.tokens';
+
+.pagination {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--pagination-gap);
+}
+
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--pagination-button-gap);
+  border: var(--border-width) solid var(--pagination-button-border-color);
+  border-radius: var(--pagination-button-radius);
+  background: var(--pagination-button-bg);
+  color: var(--pagination-button-fg);
+  font-family: inherit;
+  font-weight: var(--pagination-button-font-weight);
+  cursor: pointer;
+  user-select: none;
+
+  // No background / color transitions. Windowing shifts move DOM elements
+  // (page-number-keyed buttons reposition) and a fade on the .current
+  // class-swap during that move reads as "blinky" — the eye tracks the
+  // fade-in/out across the slide. Snapping keeps clicks feeling decisive.
+  // Same precedent as Stripe / Linear / GitHub pagination.
+
+  &:hover:not(:disabled) {
+    background: var(--pagination-button-bg-hover);
+  }
+
+  &:active:not(:disabled) {
+    background: var(--pagination-button-bg-active);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    color: var(--pagination-button-fg-disabled);
+  }
+}
+
+.pageButton {
+  min-width: var(--pagination-page-button-min-width-md);
+  height: var(--pagination-page-button-height-md);
+  padding: 0;
+}
+
+.navButton {
+  height: var(--pagination-nav-button-height-md);
+  padding: 0 var(--pagination-nav-button-padding-x-md);
+}
+
+// Current-page button — accent palette. Override the `.button` defaults.
+// The `:disabled` override preserves the selected treatment when the whole
+// Pagination is disabled, rather than making the current page look unavailable.
+.current {
+  background: var(--pagination-current-bg);
+  border-color: var(--pagination-current-border-color);
+  color: var(--pagination-current-fg);
+
+  &:disabled {
+    background: var(--pagination-current-bg);
+    border-color: var(--pagination-current-border-color);
+    color: var(--pagination-current-fg);
+    cursor: default;
+  }
+}
+
+.ellipsis {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: var(--pagination-ellipsis-min-width-md);
+  height: var(--pagination-ellipsis-height-md);
+  color: var(--pagination-ellipsis-fg);
+  user-select: none;
+}
+
+// Size modifiers — scale height + min-width + horizontal padding.
+.size-sm {
+  font-size: var(--pagination-font-size-sm);
+
+  .pageButton,
+  .ellipsis {
+    min-width: var(--pagination-page-button-min-width-sm);
+    height: var(--pagination-page-button-height-sm);
+  }
+
+  .navButton {
+    height: var(--pagination-nav-button-height-sm);
+  }
+}
+
+.size-md {
+  font-size: var(--pagination-font-size-md);
+}
+
+.size-lg {
+  font-size: var(--pagination-font-size-lg);
+
+  .pageButton,
+  .ellipsis {
+    min-width: var(--pagination-page-button-min-width-lg);
+    height: var(--pagination-page-button-height-lg);
+  }
+
+  .navButton {
+    height: var(--pagination-nav-button-height-lg);
+    padding: 0 var(--pagination-nav-button-padding-x-lg);
+  }
+}