@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/TopBar/TopBar.tsx

@@ -0,0 +1,87 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from '../../i18n';
+import { TopBarStart } from './TopBarStart';
+import { TopBarEnd } from './TopBarEnd';
+import { TopBarSearch } from './TopBarSearch';
+import { TopBarIconButton } from './TopBarIconButton';
+import styles from './TopBar.module.scss';
+
+/**
+ * Element type the root renders as. `'header'` (default) is the right choice
+ * for the application's primary top bar — it carries the implicit `banner`
+ * landmark when placed as a direct child of `<body>`. Use `'div'` for the
+ * rare case of a nested toolbar inside a main content area where another
+ * `<header>` element would be semantically wrong.
+ */
+export type TopBarElement = 'header' | 'div';
+
+/**
+ * Props for `<TopBar>` — the application top-bar primitive.
+ *
+ * Composes via `<TopBar.Start>` + `<TopBar.End>` for the two horizontal
+ * clusters, plus `<TopBar.Search>` and `<TopBar.IconButton>` for the most
+ * common children. Any other children are accepted — the root is just a
+ * flex row that owns its own height, padding, sticky positioning, and
+ * bottom border.
+ */
+export interface TopBarProps extends Omit<HTMLAttributes<HTMLElement>, 'aria-label'> {
+  /**
+   * Element to render. Defaults to `'header'`. Pick `'div'` when the bar is
+   * nested inside another content area where a second `<header>` landmark
+   * would conflict with page semantics.
+   */
+  as?: TopBarElement;
+  /**
+   * Accessible label for the bar's landmark. Defaults to `t('topBar.label')`
+   * when omitted OR empty — an empty string is not an explicit name — so screen
+   * readers always announce a name for the region. Override when a page has
+   * multiple bars to disambiguate them.
+   */
+  'aria-label'?: string;
+  /**
+   * Children of the bar — typically `<TopBar.Start>` + `<TopBar.End>`. The
+   * children area is open so consumers can render a single cluster, a
+   * single trailing element, or any other arrangement they need.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Sticky application top-bar primitive; a layout-owning compound (`TopBar.Start`, `.End`, `.Search`, `.IconButton`).
+ * @see docs/components/TopBar.md
+ */
+const TopBarRoot = forwardRef<HTMLElement, TopBarProps>(function TopBar(
+  { as = 'header', 'aria-label': ariaLabel, className, children, ...props },
+  ref,
+) {
+  const t = useTranslation();
+  // The `as` union is narrow (`'header' | 'div'`), so a single cast is
+  // enough — both elements accept the same HTMLAttributes<HTMLElement>
+  // surface used by the props interface. The forwarded ref is typed to
+  // HTMLElement (the common supertype) so the same ref works for either
+  // rendered element without leaking a generic into the public type.
+  const Comp = as as 'header';
+  return (
+    <Comp
+      ref={ref as never}
+      aria-label={ariaLabel || t('topBar.label')}
+      className={clsx(styles.topBar, className)}
+      // {...props} last so consumer overrides win (Pattern A).
+      {...props}
+    >
+      {children}
+    </Comp>
+  );
+});
+
+/**
+ * Compound `<TopBar>`; subcomponents are attached via `Object.assign`.
+ * @see docs/components/TopBar.md
+ */
+export const TopBar = Object.assign(TopBarRoot, {
+  Start: TopBarStart,
+  End: TopBarEnd,
+  Search: TopBarSearch,
+  IconButton: TopBarIconButton,
+});

package/src/components/TopBar/TopBarEnd.tsx

@@ -0,0 +1,20 @@
+import { forwardRef, type HTMLAttributes } from 'react';
+import clsx from 'clsx';
+import styles from './TopBar.module.scss';
+
+/**
+ * Props for `<TopBar.End>`. Inherits the full `<div>` HTML attribute set;
+ * use the standard `className` / `style` / event-handler props as usual.
+ */
+export type TopBarEndProps = HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Right-side cluster of a `<TopBar>` that shrinks to its content.
+ * @see docs/components/TopBar.md
+ */
+export const TopBarEnd = forwardRef<HTMLDivElement, TopBarEndProps>(function TopBarEnd(
+  { className, ...props },
+  ref,
+) {
+  return <div ref={ref} className={clsx(styles.end, className)} {...props} />;
+});

package/src/components/TopBar/TopBarIconButton.tsx

@@ -0,0 +1,86 @@
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { Button } from '../Button';
+import styles from './TopBar.module.scss';
+
+/**
+ * Tone of the optional notification-indicator dot. Selects the dot color.
+ * - `'danger'` (default) — red, for unread / urgent notifications.
+ * - `'warning'` — dark amber, for soft-warning cues (maintenance banner, etc.).
+ * - `'info'` — blue, for informational badges.
+ * - `'accent'` — accent color, for "new content" cues.
+ */
+export type TopBarIndicatorTone = 'danger' | 'warning' | 'info' | 'accent';
+
+/**
+ * Props for `<TopBar.IconButton>` — a thin wrapper over `<Button iconOnly
+ * variant="ghost" size="sm">` sized for the bar with one addition: an
+ * optional notification-indicator dot positioned in the upper-right corner.
+ */
+export interface TopBarIconButtonProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  'children' | 'color'
+> {
+  /**
+   * Icon to render inside the button. Typically a single lucide icon
+   * (e.g. `<Bell size={16} />`). The wrapping button supplies the
+   * accessible name via `aria-label` — the icon itself is decorative.
+   */
+  children: ReactNode;
+  /**
+   * Show a small dot in the upper-right corner of the button. Useful for
+   * "unread notifications", "pending updates", etc. The dot is purely
+   * visual (`aria-hidden`); the consumer is responsible for surfacing
+   * count / status text to assistive tech, typically via the button's
+   * `aria-label` or a hidden span.
+   */
+  indicator?: boolean;
+  /**
+   * Dot color. Defaults to `'danger'` (red). See `TopBarIndicatorTone` for
+   * the full option set.
+   */
+  indicatorTone?: TopBarIndicatorTone;
+  /**
+   * **Required.** Accessible name for the icon-only button — without it,
+   * screen readers announce nothing. Phrase as an action (`'Notifications'`,
+   * `'Create new'`). Include count info here when the indicator is on
+   * (e.g. `'Notifications, 3 unread'`).
+   */
+  'aria-label': string;
+}
+
+/** Per-tone CSS class lookup. Kept as a record so adding a tone is one edit. */
+const TONE_CLASS: Record<TopBarIndicatorTone, string> = {
+  danger: styles.indicatorDanger,
+  warning: styles.indicatorWarning,
+  info: styles.indicatorInfo,
+  accent: styles.indicatorAccent,
+};
+
+/**
+ * Icon-only ghost button for `<TopBar>` with an optional notification-indicator dot.
+ * @see docs/components/TopBar.md
+ */
+export const TopBarIconButton = forwardRef<HTMLButtonElement, TopBarIconButtonProps>(
+  function TopBarIconButton(
+    { children, indicator = false, indicatorTone = 'danger', className, ...props },
+    ref,
+  ) {
+    return (
+      <Button
+        ref={ref}
+        variant="ghost"
+        size="sm"
+        iconOnly
+        className={clsx(styles.iconButton, className)}
+        // {...props} last so consumer overrides win (Pattern A).
+        {...props}
+      >
+        {children}
+        {indicator && (
+          <span aria-hidden className={clsx(styles.indicator, TONE_CLASS[indicatorTone])} />
+        )}
+      </Button>
+    );
+  },
+);

package/src/components/TopBar/TopBarSearch.tsx

@@ -0,0 +1,319 @@
+import {
+  forwardRef,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type FocusEvent,
+  type InputHTMLAttributes,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactNode,
+} from 'react';
+import { Search } from 'lucide-react';
+import clsx from 'clsx';
+import { useTranslation } from '../../i18n';
+import { Kbd } from '../Kbd';
+import { isTourHeld, useInOverlay } from '../_internal/overlay';
+import {
+  TopBarSearchPanel,
+  optionId,
+  type PanelGroup,
+  type SearchOption,
+} from './TopBarSearchPanel';
+import styles from './TopBar.module.scss';
+
+/** One result row in `<TopBar.Search>` combobox mode. */
+export interface TopBarSearchItem {
+  /** Unique across ALL groups. Identifies the result set: the highlight resets to the first row when the set of ids changes. */
+  id: string;
+  /** Primary text. Truncates to one line. */
+  label: ReactNode;
+  /** Trailing muted text, e.g. the entity type or an email. */
+  meta?: ReactNode;
+  /** Leading decorative icon (e.g. `<User size={16} />`); hidden from assistive tech. */
+  icon?: ReactNode;
+  /**
+   * Renders the row as a link so Cmd/Ctrl/Shift/middle-click and "copy link"
+   * work natively. A plain click or Enter still calls `onSelect` (the library
+   * never navigates) — route there.
+   */
+  href?: string;
+}
+
+/** A labelled block of results. Groups with no items are not rendered. */
+export interface TopBarSearchGroup {
+  /** Visible heading; also the group's accessible name. */
+  label: string;
+  /** Result rows in this group. */
+  items: TopBarSearchItem[];
+}
+
+/** Trailing row in the ↑/↓ cycle, e.g. "View all results". */
+export interface TopBarSearchFooterAction {
+  /** Row content. */
+  label: ReactNode;
+  /** Called on Enter or click. */
+  onSelect: () => void;
+  /** Optional link target, same semantics as `TopBarSearchItem.href`. */
+  href?: string;
+}
+
+/**
+ * Props for `<TopBar.Search>` — a styled `<input type="search">` with a
+ * leading magnifying-glass icon and an optional trailing `<Kbd>` hotkey
+ * hint. Passing `results` turns it into a combobox with a results panel.
+ *
+ * Inherits the standard `<input>` HTML attribute surface (minus `type`,
+ * fixed to `'search'`, the legacy `results` attribute, and the native
+ * `onSelect` text-selection event, replaced by the combobox `onSelect`). Spread `value` / `defaultValue` /
+ * `onChange` / `name` / `id` through normally — they reach the input.
+ */
+export interface TopBarSearchProps extends Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'type' | 'onSelect' | 'results'
+> {
+  /**
+   * Optional hotkey hint shown after the input. Rendered internally via
+   * `<Kbd size="sm">`. Pass an **array** of key labels for a multi-key
+   * combo (`['⌘', 'K']` → two chips joined with `+`) or a single string
+   * for a one-chip hint (`'Esc'` → one chip). Note: `'⌘K'` is treated as
+   * a single chip — use the array form for multi-key combos.
+   *
+   * The hint is **visual only**; the library does not bind any keyboard
+   * shortcut to it. Omit for no hint.
+   */
+  hotkey?: string | string[];
+  /**
+   * `className` for the wrapping `<div>` (the search surface itself).
+   * The input's own className lives on the underlying `<input>` via the
+   * spread input-props (use the standard `inputClassName` pattern if you
+   * need to target the inner element specifically — not exposed in v1).
+   */
+  className?: string;
+  /**
+   * Turns on combobox mode: the input gets `role="combobox"` and a results
+   * panel opens under it. Presence switches the mode — pass `[]` (not
+   * `undefined`) while there are no results yet. You filter or fetch; the
+   * library owns keyboard, focus, dismissal, positioning and announcements.
+   * The first row is highlighted whenever the set of ids changes, so Enter
+   * opens the top hit.
+   */
+  results?: TopBarSearchGroup[];
+  /** Controlled panel visibility. Omit for uncontrolled. */
+  open?: boolean;
+  /** Uncontrolled initial visibility. Default `false`. */
+  defaultOpen?: boolean;
+  /** Called when the panel wants to open (focus, typing, ↓) or close (Esc, blur, selection). */
+  onOpenChange?: (open: boolean) => void;
+  /** Called on Enter or click on a result. The input text is left as is — clear it here if wanted. */
+  onSelect?: (item: TopBarSearchItem, groupIndex: number) => void;
+  /** Shows a loading row and sets `aria-busy`; existing results stay visible and the live region keeps announcing their count. */
+  loading?: boolean;
+  /**
+   * Row shown for a non-empty query with no results. Default `t('topBar.searchEmpty')`
+   * (also used when this is an empty string). A non-string node is rendered but the
+   * live region still announces the default text — pass a string to have it announced.
+   */
+  emptyMessage?: ReactNode;
+  /** Trailing row in the ↑/↓ cycle (e.g. "View all results"). Rendered whenever the panel is shown (results, loading row, or empty row), as the last row. */
+  footerAction?: TopBarSearchFooterAction;
+}
+
+/**
+ * Search input for `<TopBar>`: a pill with a leading icon, a native search input, an optional hotkey hint and an optional results combobox.
+ * @see docs/components/TopBar.md
+ */
+export const TopBarSearch = forwardRef<HTMLInputElement, TopBarSearchProps>(function TopBarSearch(
+  {
+    hotkey,
+    placeholder,
+    className,
+    'aria-label': ariaLabel,
+    results,
+    open,
+    defaultOpen = false,
+    onOpenChange,
+    onSelect,
+    loading = false,
+    emptyMessage,
+    footerAction,
+    onChange,
+    onFocus,
+    onBlur,
+    onClick,
+    onKeyDown,
+    ...inputProps
+  },
+  ref,
+) {
+  const t = useTranslation();
+  const listboxId = useId();
+  const wrapperRef = useRef<HTMLDivElement>(null);
+  const combobox = results !== undefined;
+  // `||` on BOTH links, not `??`: an empty string is never a meaningful
+  // explicit name, so it must fall through to placeholder, then translation.
+  const name = ariaLabel || placeholder || t('topBar.search');
+
+  const [openState, setOpenState] = useState(defaultOpen);
+  const isOpen = open ?? openState;
+  const setOpen = (next: boolean) => {
+    if (next === isOpen) return;
+    if (open === undefined) setOpenState(next);
+    onOpenChange?.(next);
+  };
+
+  // Value is needed to decide whether an empty result set shows "No results".
+  const [uncontrolledValue, setUncontrolledValue] = useState(String(inputProps.defaultValue ?? ''));
+  const value = inputProps.value !== undefined ? String(inputProps.value) : uncontrolledValue;
+
+  const { groups, options } = useMemo(() => {
+    const groups: PanelGroup[] = [];
+    const options: SearchOption[] = [];
+    (results ?? []).forEach((g, groupIndex) => {
+      if (g.items.length === 0) return;
+      groups.push({ label: g.label, groupIndex, start: options.length, items: g.items });
+      for (const item of g.items) options.push({ kind: 'item', item, groupIndex });
+    });
+    if (footerAction) options.push({ kind: 'footer', action: footerAction });
+    return { groups, options };
+  }, [results, footerAction]);
+
+  const hasItems = groups.length > 0;
+  const shown = combobox && isOpen && (loading || hasItems || value.trim() !== '');
+  // Probed here, not in the panel: a child's layout effect runs before this wrapper's ref attaches.
+  const inOverlay = useInOverlay(wrapperRef, shown);
+  const empty = !loading && !hasItems ? emptyMessage || t('topBar.searchEmpty') : null;
+  const announcement = !shown
+    ? ''
+    : hasItems
+      ? t('topBar.searchResults', { count: options.filter((o) => o.kind === 'item').length })
+      : loading
+        ? t('topBar.searchLoading')
+        : typeof empty === 'string'
+          ? empty
+          : t('topBar.searchEmpty');
+
+  // Reset to the first row when the SET of ids changes — not on every new
+  // array identity, so a consumer rebuilding `results` inline keeps the highlight.
+  // Item ids only: the footer is always last, so toggling it must not reset the highlight or re-announce.
+  const signature = options.flatMap((o) => (o.kind === 'item' ? [o.item.id] : [])).join('\u0000');
+  const [active, setActive] = useState(0);
+  const [prevSignature, setPrevSignature] = useState(signature);
+  // Adjust state while rendering (not in an effect): no painted frame with a stale highlight.
+  if (signature !== prevSignature) {
+    setPrevSignature(signature);
+    setActive(0);
+  }
+  const activeIndex = options.length === 0 ? -1 : Math.min(active, options.length - 1);
+
+  const choose = (option: SearchOption) => {
+    if (option.kind === 'footer') option.action.onSelect();
+    else onSelect?.(option.item, option.groupIndex);
+    setOpen(false);
+  };
+
+  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
+    onChange?.(e);
+    if (inputProps.value === undefined) setUncontrolledValue(e.target.value);
+    if (combobox) setOpen(true);
+  };
+  const handleFocus = (e: FocusEvent<HTMLInputElement>) => {
+    onFocus?.(e);
+    if (combobox && !e.defaultPrevented) setOpen(true);
+  };
+  const handleBlur = (e: FocusEvent<HTMLInputElement>) => {
+    onBlur?.(e);
+    // Panel presses are mousedown-prevented, so a blur always means focus left.
+    // #684: unless a tour pointing into the panel took focus to its card.
+    const panel = document.getElementById(listboxId);
+    if (isTourHeld(e.relatedTarget, panel, wrapperRef.current)) return;
+    if (combobox) setOpen(false);
+  };
+  const handleClick = (e: MouseEvent<HTMLInputElement>) => {
+    onClick?.(e);
+    if (combobox && !e.defaultPrevented) setOpen(true);
+  };
+  const handleKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
+    onKeyDown?.(e);
+    if (!combobox || e.defaultPrevented) return;
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+      if (!shown) {
+        if (e.key === 'ArrowDown') {
+          e.preventDefault();
+          setOpen(true);
+        }
+        return;
+      }
+      if (options.length === 0) return;
+      e.preventDefault();
+      const step = e.key === 'ArrowDown' ? 1 : -1;
+      setActive((activeIndex + step + options.length) % options.length);
+    } else if (
+      e.key === 'Enter' &&
+      !e.nativeEvent.isComposing &&
+      e.keyCode !== 229 &&
+      shown &&
+      activeIndex >= 0
+    ) {
+      e.preventDefault();
+      choose(options[activeIndex]!);
+    }
+    // Escape: TopBarSearchPanel's document listener (overlay registry).
+  };
+
+  return (
+    <div ref={wrapperRef} className={clsx(styles.search, className)}>
+      <Search aria-hidden className={styles.searchIcon} />
+      <input
+        ref={ref}
+        type="search"
+        placeholder={placeholder}
+        aria-label={name}
+        className={styles.searchInput}
+        // Password managers and browser autofill must skip a free-text search box.
+        autoComplete="off"
+        data-1p-ignore
+        data-lpignore="true"
+        data-form-type="other"
+        // {...inputProps} after the defaults so consumer overrides win (Pattern A) ...
+        {...inputProps}
+        // ... but the combobox ARIA contract is applied after them (Pattern B).
+        {...(combobox && {
+          role: 'combobox',
+          'aria-expanded': shown,
+          'aria-controls': shown ? listboxId : undefined,
+          'aria-activedescendant':
+            shown && activeIndex >= 0 ? optionId(listboxId, activeIndex) : undefined,
+          'aria-autocomplete': 'list' as const,
+        })}
+        onChange={handleChange}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+      />
+      {hotkey != null && <Kbd keys={Array.isArray(hotkey) ? hotkey : [hotkey]} size="sm" />}
+      {combobox && (
+        <TopBarSearchPanel
+          id={listboxId}
+          shown={shown}
+          label={name}
+          groups={groups}
+          options={options}
+          activeIndex={activeIndex}
+          onActivate={setActive}
+          onChoose={choose}
+          anchorRef={wrapperRef}
+          inOverlay={inOverlay}
+          onClose={() => setOpen(false)}
+          loading={loading}
+          emptyMessage={shown ? empty : null}
+          announcement={announcement}
+          announceKey={signature}
+        />
+      )}
+    </div>
+  );
+});