@mihcm/ui 0.14.1

package/src/TopBar.tsx

@@ -0,0 +1,436 @@
+'use client';
+
+/**
+ * TopBar (web variant — React DOM) + compound sub-components.
+ *
+ * Segmented app header from the MiHCM Figma prototype.
+ * 60 px height on desktop, compact on mobile. Overflow is clipped so the
+ * parallelogram shapes stay within bounds without leaving visual gaps.
+ *
+ * Sub-components:
+ *   TopBarLogo         — brand mark using the Logo primitive
+ *   TopBarHomeButton   — parallelogram home nav button
+ *   TopBarBackLink     — parallelogram back link with ‹ arrow + text
+ *   TopBarNotification — icon with badge count
+ *   TopBarProfile      — user greeting + avatar + status
+ *   TopBarDivider      — thin vertical separator
+ *   TopBarAction       — generic action button (icon + optional label)
+ *
+ * Wiki: docs/components/TopBar.md
+ */
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import { cn } from './internal/cn.js';
+import { Logo, type LogoProps } from './Logo.js';
+import { NotificationBadge } from './NotificationBadge.js';
+
+/* ── TopBar (container) ──────────────────────────────────────────── */
+
+export interface TopBarProps extends HTMLAttributes<HTMLElement> {
+  /** Leading slot — logo, home button, back link, notification. */
+  start?: ReactNode;
+  /** Optional middle slot — global search, page-level controls. */
+  center?: ReactNode;
+  /** Trailing slot — profile, actions, logout. */
+  end?: ReactNode;
+  /** Force a surface treatment, or follow the app `.dark` class. */
+  appearance?: 'system' | 'light' | 'dark';
+}
+
+export const TopBar = forwardRef<HTMLElement, TopBarProps>(function TopBar(
+  { className, start, center, end, children, appearance = 'system', ...props },
+  ref,
+) {
+  const surfaceClass =
+    appearance === 'dark'
+      ? 'bg-topbar-dark-surface text-topbar-dark-foreground'
+      : appearance === 'light'
+        ? 'bg-topbar-light-surface text-topbar-light-foreground'
+        : 'bg-topbar-light-surface text-topbar-light-foreground dark:!bg-topbar-dark-surface dark:!text-topbar-dark-foreground';
+
+  return (
+    <header
+      ref={ref}
+      data-appearance={appearance}
+      className={cn(
+        'group/topbar z-30 flex h-15 flex-shrink-0 items-center justify-between overflow-hidden px-6 py-2 shadow-mi-soft',
+        surfaceClass,
+        className,
+      )}
+      {...props}
+    >
+      {children ?? (
+        <>
+          {start ? (
+            <div className="flex min-w-0 shrink-0 items-center gap-0.5">{start}</div>
+          ) : (
+            <span />
+          )}
+          {center ? (
+            <div className="hidden md:flex flex-1 justify-center px-6">{center}</div>
+          ) : null}
+          {end ? <div className="flex h-10 shrink-0 items-center gap-6">{end}</div> : <span />}
+        </>
+      )}
+    </header>
+  );
+});
+
+/* ── TopBarLogo ───────────────────────────────────────────────────── */
+
+export interface TopBarLogoProps extends HTMLAttributes<HTMLDivElement> {
+  /** Built-in Logo color treatment. */
+  variant?: LogoProps['variant'];
+  /** Built-in Logo size. */
+  size?: LogoProps['size'];
+  /** Approved brand asset family to swap the mark. */
+  brand?: LogoProps['brand'];
+  /** Approved asset variant when `brand` is set. */
+  assetVariant?: LogoProps['assetVariant'];
+  /** Base public path for approved logo assets. */
+  assetBasePath?: LogoProps['assetBasePath'];
+  /** Logo image source. Overrides `brand`. */
+  src?: string;
+  /** Alt text for the logo image or built-in mark. */
+  alt?: string;
+  /** Classes for the inner Logo primitive. */
+  logoClassName?: string;
+}
+
+export const TopBarLogo = forwardRef<HTMLDivElement, TopBarLogoProps>(function TopBarLogo(
+  {
+    className,
+    src,
+    alt = 'MiHCM',
+    variant = 'primary',
+    size = 'md',
+    brand,
+    assetVariant,
+    assetBasePath,
+    logoClassName,
+    children,
+    ...props
+  },
+  ref,
+) {
+  const logoProps = {
+    ...(src ? { src } : {}),
+    ...(brand ? { brand } : {}),
+    ...(assetVariant ? { assetVariant } : {}),
+    ...(assetBasePath ? { assetBasePath } : {}),
+  };
+  const shouldAutoSwapBuiltIn = !children && !src && !brand && variant === 'primary';
+  const shouldAutoSwapAsset =
+    !children && !src && Boolean(brand) && (assetVariant === undefined || assetVariant === 'primary');
+
+  return (
+    <div
+      ref={ref}
+      className={cn('flex flex-shrink-0 items-center justify-center', className)}
+      {...props}
+    >
+      {children ?? (shouldAutoSwapBuiltIn ? (
+        <>
+          <Logo
+            alt={alt}
+            variant="primary"
+            size={size}
+            className={cn(
+              'dark:!hidden group-data-[appearance=dark]/topbar:!hidden group-data-[appearance=light]/topbar:!inline-flex',
+              logoClassName,
+            )}
+          />
+          <Logo
+            alt={alt}
+            variant="white"
+            size={size}
+            className={cn(
+              'hidden dark:!inline-flex group-data-[appearance=dark]/topbar:!inline-flex group-data-[appearance=light]/topbar:!hidden',
+              logoClassName,
+            )}
+          />
+        </>
+      ) : shouldAutoSwapAsset ? (
+        <>
+          <Logo
+            {...logoProps}
+            alt={alt}
+            assetVariant="primary"
+            size={size}
+            className={cn(
+              'dark:!hidden group-data-[appearance=dark]/topbar:!hidden group-data-[appearance=light]/topbar:!inline-flex',
+              logoClassName,
+            )}
+          />
+          <Logo
+            {...logoProps}
+            alt={alt}
+            assetVariant="white"
+            size={size}
+            className={cn(
+              'hidden dark:!inline-flex group-data-[appearance=dark]/topbar:!inline-flex group-data-[appearance=light]/topbar:!hidden',
+              logoClassName,
+            )}
+          />
+        </>
+      ) : (
+        <Logo
+          {...logoProps}
+          alt={alt}
+          variant={variant}
+          size={size}
+          className={logoClassName}
+        />
+      ))}
+    </div>
+  );
+});
+
+/* ── TopBarHomeButton ─────────────────────────────────────────────── */
+
+export interface TopBarHomeButtonProps extends Omit<HTMLAttributes<HTMLButtonElement>, 'children'> {
+  /** The icon rendered inside the parallelogram. */
+  icon: ReactNode;
+}
+
+/**
+ * Parallelogram-shaped home navigation button.
+ * Hidden on mobile (`hidden md:block`) by default.
+ */
+export const TopBarHomeButton = forwardRef<HTMLButtonElement, TopBarHomeButtonProps>(
+  function TopBarHomeButton({ className, icon, ...props }, ref) {
+    return (
+      <button
+        ref={ref}
+        type="button"
+        aria-label="Home"
+        className={cn(
+          'relative -mr-12 hidden h-[65px] w-[102px] shrink-0 md:block',
+          'cursor-pointer focus:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          className,
+        )}
+        {...props}
+      >
+        <span
+          className="absolute inset-0 bg-topbar-light-home dark:!bg-topbar-dark-home group-data-[appearance=dark]/topbar:!bg-topbar-dark-home group-data-[appearance=light]/topbar:!bg-topbar-light-home"
+          style={{ clipPath: 'polygon(48px 0, 100% 0, calc(100% - 48px) 100%, 0 100%)' }}
+          aria-hidden
+        />
+        <span className="absolute inset-0 flex items-center justify-center text-topbar-light-muted dark:!text-topbar-dark-muted group-data-[appearance=dark]/topbar:!text-topbar-dark-muted group-data-[appearance=light]/topbar:!text-topbar-light-muted [&_svg]:size-4">
+          {icon}
+        </span>
+      </button>
+    );
+  },
+);
+
+/* ── TopBarBackLink ───────────────────────────────────────────────── */
+
+export interface TopBarBackLinkProps extends HTMLAttributes<HTMLElement> {
+  /** Navigates as an anchor when provided. Renders a button otherwise. */
+  href?: string;
+  /** Override the default chevron icon. */
+  icon?: ReactNode;
+}
+
+/**
+ * Back navigation — parallelogram with chevron + text.
+ * Hidden on mobile (`hidden md:flex`). The text is hidden below `sm`.
+ */
+export const TopBarBackLink = forwardRef<HTMLElement, TopBarBackLinkProps>(function TopBarBackLink(
+  { className, href, icon, children, ...props },
+  ref,
+) {
+  const chevron = icon ?? (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <path d="M15 18L9 12L15 6" />
+    </svg>
+  );
+
+  const inner = (
+    <>
+      {/* Parallelogram background */}
+      <span
+        className="absolute inset-0 bg-topbar-light-segment dark:!bg-topbar-dark-segment group-data-[appearance=dark]/topbar:!bg-topbar-dark-segment group-data-[appearance=light]/topbar:!bg-topbar-light-segment"
+        style={{ clipPath: 'polygon(48px 0, 100% 0, calc(100% - 48px) 100%, 0 100%)' }}
+        aria-hidden
+      />
+      {/* Content — relative so it drives the element's auto width */}
+      <span className="relative flex h-full items-center gap-2 pl-[39.77px] pr-12">
+        <span className="w-4 h-4 flex items-center justify-center shrink-0">{chevron}</span>
+        {children ? (
+          <span className="hidden whitespace-nowrap text-xs font-medium text-topbar-light-foreground dark:!text-topbar-dark-foreground group-data-[appearance=dark]/topbar:!text-topbar-dark-foreground group-data-[appearance=light]/topbar:!text-topbar-light-foreground sm:inline">
+            {children}
+          </span>
+        ) : null}
+      </span>
+    </>
+  );
+
+  const shared = {
+    className: cn(
+      'relative hidden h-[65px] w-[193.773px] shrink-0 md:block',
+      'cursor-pointer focus:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+      className,
+    ),
+    ...props,
+  };
+
+  if (href) {
+    return (
+      <a ref={ref as React.Ref<HTMLAnchorElement>} href={href} {...shared}>
+        {inner}
+      </a>
+    );
+  }
+  return (
+    <button ref={ref as React.Ref<HTMLButtonElement>} type="button" {...shared}>
+      {inner}
+    </button>
+  );
+});
+
+/* ── TopBarNotification ───────────────────────────────────────────── */
+
+export interface TopBarNotificationProps extends Omit<
+  HTMLAttributes<HTMLButtonElement>,
+  'children'
+> {
+  /** The notification icon (e.g. Bell from lucide). */
+  icon: ReactNode;
+  /** Badge count. Hidden when 0 or undefined. */
+  count?: number;
+}
+
+export const TopBarNotification = forwardRef<HTMLButtonElement, TopBarNotificationProps>(
+  function TopBarNotification({ className, icon, count, ...props }, ref) {
+    return (
+      <button
+        ref={ref}
+        type="button"
+        aria-label={count ? `Notifications (${count})` : 'Notifications'}
+        className={cn(
+          'relative ml-0 cursor-pointer',
+          'focus:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded',
+          className,
+        )}
+        {...props}
+      >
+        <span className="flex size-4 items-center justify-center text-topbar-light-muted dark:!text-topbar-dark-muted group-data-[appearance=dark]/topbar:!text-topbar-dark-muted group-data-[appearance=light]/topbar:!text-topbar-light-muted [&_svg]:size-4">
+          {icon}
+        </span>
+        <NotificationBadge count={count ?? 0} className="-top-[9px] -right-2.5" />
+      </button>
+    );
+  },
+);
+
+/* ── TopBarProfile ────────────────────────────────────────────────── */
+
+export interface TopBarProfileProps extends HTMLAttributes<HTMLDivElement> {
+  /** Primary line, e.g. "Good Morning Yashi". */
+  name?: string;
+  /** Secondary line, e.g. "Edit Profile". */
+  subtitle?: string;
+  /** Avatar element (use the Avatar component). */
+  avatar: ReactNode;
+  /** Optional status indicator overlaid on the avatar. */
+  status?: ReactNode;
+}
+
+export const TopBarProfile = forwardRef<HTMLDivElement, TopBarProfileProps>(function TopBarProfile(
+  { className, name, subtitle, avatar, status, ...props },
+  ref,
+) {
+  return (
+    <div ref={ref} className={cn('relative flex items-center gap-4', className)} {...props}>
+      {(name || subtitle) && (
+        <div className="text-right leading-4 hidden md:flex md:flex-col md:items-end gap-0.5">
+          {name && (
+            <span className="whitespace-nowrap text-xs font-medium text-topbar-light-foreground dark:!text-topbar-dark-foreground group-data-[appearance=dark]/topbar:!text-topbar-dark-foreground group-data-[appearance=light]/topbar:!text-topbar-light-foreground">
+              {name}
+            </span>
+          )}
+          {subtitle && (
+            <span className="whitespace-nowrap text-xs leading-4 text-topbar-light-muted dark:!text-topbar-dark-muted group-data-[appearance=dark]/topbar:!text-topbar-dark-muted group-data-[appearance=light]/topbar:!text-topbar-light-muted">
+              {subtitle}
+            </span>
+          )}
+        </div>
+      )}
+      <div className="relative">
+        {avatar}
+        {status && <span className="absolute -bottom-0.5 -right-0.5">{status}</span>}
+      </div>
+    </div>
+  );
+});
+
+/* ── TopBarDivider ────────────────────────────────────────────────── */
+
+/**
+ * Thin vertical separator between TopBar items.
+ * Hidden below `lg` by default; override with `className`.
+ */
+export const TopBarDivider = forwardRef<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>>(
+  function TopBarDivider({ className, ...props }, ref) {
+    return (
+      <span
+        ref={ref}
+        aria-hidden
+        className={cn(
+          'hidden h-[15px] w-px bg-topbar-light-divider dark:!bg-topbar-dark-divider lg:block',
+          'group-data-[appearance=dark]/topbar:!bg-topbar-dark-divider group-data-[appearance=light]/topbar:!bg-topbar-light-divider',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+/* ── TopBarAction ─────────────────────────────────────────────────── */
+
+export interface TopBarActionProps extends HTMLAttributes<HTMLButtonElement> {
+  /** Leading icon (e.g. Sparkles, Headphones from lucide). */
+  icon?: ReactNode;
+}
+
+/**
+ * Generic action button for the TopBar end slot.
+ * Pass `icon` for an icon-only or icon+label button.
+ * Pass `children` (string or node) for the visible label.
+ * Control responsive visibility via `className` (e.g. `hidden lg:flex`).
+ */
+export const TopBarAction = forwardRef<HTMLButtonElement, TopBarActionProps>(function TopBarAction(
+  { className, icon, children, ...props },
+  ref,
+) {
+  return (
+    <button
+      ref={ref}
+      type="button"
+      className={cn(
+        'flex items-center gap-2 cursor-pointer',
+        'text-topbar-light-muted transition-colors duration-150 hover:text-topbar-light-foreground dark:!text-topbar-dark-muted dark:hover:!text-topbar-dark-foreground',
+        'group-data-[appearance=dark]/topbar:!text-topbar-dark-muted group-data-[appearance=dark]/topbar:hover:!text-topbar-dark-foreground',
+        'group-data-[appearance=light]/topbar:!text-topbar-light-muted group-data-[appearance=light]/topbar:hover:!text-topbar-light-foreground',
+        'focus:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded',
+        className,
+      )}
+      {...props}
+    >
+      {icon && <span className="[&_svg]:size-4">{icon}</span>}
+      {children && <span className="text-xs leading-4">{children}</span>}
+    </button>
+  );
+});

package/src/Tracker.tsx

@@ -0,0 +1,244 @@
+'use client';
+
+/**
+ * Tracker (web variant).
+ *
+ * Dense sequence of status segments for uptime, workflows, and timeline
+ * coverage. Inspired by Tremor's Tracker but tokenized for MiHCM.
+ *
+ * Wiki: docs/components/Tracker.md
+ */
+import { forwardRef, type CSSProperties, type HTMLAttributes, type ReactNode } from 'react';
+import { cn } from './internal/cn.js';
+
+const TONE_CLASS = {
+  neutral: 'bg-muted',
+  primary: 'bg-primary',
+  accent: 'bg-accent',
+  success: 'bg-success',
+  warning: 'bg-warning',
+  danger: 'bg-destructive',
+} as const;
+
+export interface TrackerItem {
+  key?: string;
+  label?: string;
+  tone?: keyof typeof TONE_CLASS;
+  value?: number;
+  tooltip?: ReactNode;
+  className?: string;
+  labelClassName?: string;
+}
+
+export interface TrackerProps extends HTMLAttributes<HTMLDivElement> {
+  data: TrackerItem[];
+  variant?: 'bar' | 'blocks' | 'dots' | 'timeline';
+  size?: 'xs' | 'sm' | 'md' | 'lg';
+  radius?: 'none' | 'sm' | 'md' | 'lg' | 'full';
+  gap?: 'none' | 'xs' | 'sm' | 'md';
+  distribution?: 'equal' | 'weighted';
+  ariaLabel?: string;
+  showLabels?: boolean;
+  labelPosition?: 'top' | 'bottom';
+  selectedKey?: string;
+  onItemSelect?: (item: TrackerItem, index: number) => void;
+  itemClassName?: string;
+  labelClassName?: string;
+}
+
+const SIZE_CLASS = {
+  xs: 'h-3',
+  sm: 'h-6',
+  md: 'h-8',
+  lg: 'h-10',
+} as const;
+
+const DOT_SIZE_CLASS = {
+  xs: 'size-2.5',
+  sm: 'size-3.5',
+  md: 'size-[1.125rem]',
+  lg: 'size-6',
+} as const;
+
+const RADIUS_CLASS = {
+  none: 'rounded-none',
+  sm: 'rounded-sm',
+  md: 'rounded-md',
+  lg: 'rounded-lg',
+  full: 'rounded-full',
+} as const;
+
+const GAP_CLASS = {
+  none: 'gap-0',
+  xs: 'gap-0.5',
+  sm: 'gap-1',
+  md: 'gap-2',
+} as const;
+
+const VARIANT_CLASS = {
+  bar: 'min-w-1 flex-1',
+  blocks: 'min-w-3 flex-1 border border-background/70 shadow-mi-card',
+  dots: 'shrink-0 rounded-full',
+  timeline: 'min-w-4 flex-1 border-y border-background/70',
+} as const;
+
+function getItemKey(item: TrackerItem, index: number) {
+  return item.key ?? `${item.label ?? 'tracker-item'}-${index}`;
+}
+
+function getItemStyle(
+  item: TrackerItem,
+  variant: NonNullable<TrackerProps['variant']>,
+  distribution: NonNullable<TrackerProps['distribution']>,
+): CSSProperties | undefined {
+  if (variant === 'dots') {
+    return undefined;
+  }
+
+  if (distribution === 'weighted') {
+    return { flexGrow: Math.max(item.value ?? 1, 0), flexBasis: 0 };
+  }
+
+  return undefined;
+}
+
+function getItemLayoutClass(
+  variant: NonNullable<TrackerProps['variant']>,
+  showLabels: boolean,
+  labelPosition: NonNullable<TrackerProps['labelPosition']>,
+) {
+  return cn(
+    'min-w-0',
+    variant === 'dots' ? 'shrink-0' : 'flex-1',
+    showLabels && 'flex flex-col gap-1',
+    showLabels && labelPosition === 'top' && 'flex-col-reverse',
+  );
+}
+
+function getTimelineRadiusClass(
+  variant: NonNullable<TrackerProps['variant']>,
+  index: number,
+  length: number,
+) {
+  if (variant !== 'timeline') {
+    return undefined;
+  }
+
+  if (length === 1) {
+    return 'rounded-full';
+  }
+
+  return cn(index === 0 && 'rounded-l-full', index === length - 1 && 'rounded-r-full');
+}
+
+export const Tracker = forwardRef<HTMLDivElement, TrackerProps>(function Tracker(
+  {
+    data,
+    variant = 'bar',
+    size = 'md',
+    radius = 'md',
+    gap = 'xs',
+    distribution = 'equal',
+    ariaLabel = 'Status tracker',
+    showLabels = false,
+    labelPosition = 'bottom',
+    selectedKey,
+    onItemSelect,
+    itemClassName,
+    labelClassName,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const renderSegment = (item: TrackerItem, index: number) => {
+    const key = getItemKey(item, index);
+    const selected = selectedKey === key;
+    const interactive = Boolean(onItemSelect);
+    const title = typeof item.tooltip === 'string' ? item.tooltip : item.label;
+    const segmentClassName = cn(
+      'block border-0 p-0 transition-all duration-300',
+      interactive && 'appearance-none',
+      variant !== 'dots' && 'w-full',
+      variant === 'dots' ? DOT_SIZE_CLASS[size] : SIZE_CLASS[size],
+      variant !== 'timeline' && RADIUS_CLASS[radius],
+      getTimelineRadiusClass(variant, index, data.length),
+      VARIANT_CLASS[variant],
+      TONE_CLASS[item.tone ?? 'neutral'],
+      selected && 'ring-2 ring-ring ring-offset-2 ring-offset-background',
+      interactive &&
+        'cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+      itemClassName,
+      item.className,
+    );
+    const segment = interactive ? (
+      <button
+        type="button"
+        aria-pressed={selected}
+        aria-label={item.label}
+        title={title}
+        className={segmentClassName}
+        onClick={() => onItemSelect?.(item, index)}
+      />
+    ) : (
+      <span
+        aria-label={item.label}
+        title={title}
+        className={segmentClassName}
+      />
+    );
+
+    if (!showLabels) {
+      return (
+        <span
+          key={key}
+          role="listitem"
+          className={getItemLayoutClass(variant, false, labelPosition)}
+          style={getItemStyle(item, variant, distribution)}
+        >
+          {segment}
+        </span>
+      );
+    }
+
+    return (
+      <span
+        key={key}
+        role="listitem"
+        className={getItemLayoutClass(variant, true, labelPosition)}
+        style={getItemStyle(item, variant, distribution)}
+      >
+        {segment}
+        {item.label ? (
+          <span
+            className={cn(
+              'truncate text-xs text-muted-foreground',
+              labelPosition === 'top' ? 'mb-1' : 'mt-1',
+              labelClassName,
+              item.labelClassName,
+            )}
+          >
+            {item.label}
+          </span>
+        ) : null}
+      </span>
+    );
+  };
+
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        'flex w-full items-center',
+        variant === 'dots' ? 'justify-start' : 'items-stretch',
+        GAP_CLASS[gap],
+        className,
+      )}
+      role="list"
+      aria-label={ariaLabel}
+      {...props}
+    >
+      {data.map(renderSegment)}
+    </div>
+  );
+});