@dashforge/tw 1.1.0 → 1.2.0

package/src/components/Menu/Menu.tsx

@@ -1,335 +0,0 @@
-import {
-  createContext,
-  forwardRef,
-  memo,
-  useContext,
-  type ReactNode,
-} from 'react';
-import * as RadixMenu from '@radix-ui/react-dropdown-menu';
-import { DashFormContext, useEngineVisibility } from '@dashforge/ui-core';
-import { cn } from '../../utils/cn.js';
-import { useAccessState } from '../../hooks/useAccessState.js';
-import { menuVariants, placementToRadix } from './menu.variants.js';
-import type {
-  MenuContentProps,
-  MenuItemProps,
-  MenuLabelProps,
-  MenuProps,
-  MenuSeparatorProps,
-  MenuSkeletonProps,
-  MenuTriggerProps,
-} from './menu.types.js';
-
-// ─── Context ─────────────────────────────────────────────────────
-
-/**
- * Internal Menu context — propagates the `closeOnItemClick` flag
- * down to `<MenuItem>` so each item knows whether to suppress the
- * default Radix close-on-select behaviour.
- *
- * @internal
- */
-interface MenuCtx {
-  closeOnItemClick: boolean;
-}
-
-const MenuContext = createContext<MenuCtx>({ closeOnItemClick: true });
-
-// ─── Menu (Root provider) ────────────────────────────────────────
-
-/**
- * `<Menu>` — top-level provider that wraps Radix `DropdownMenu.Root`.
- *
- * Compound API:
- * ```tsx
- * <Menu>
- *   <MenuTrigger>
- *     <IconButton aria-label="Actions"><MoreIcon /></IconButton>
- *   </MenuTrigger>
- *   <MenuContent>
- *     <MenuLabel>Actions</MenuLabel>
- *     <MenuItem onClick={onEdit}>Edit</MenuItem>
- *     <MenuSeparator />
- *     <MenuItem color="danger" onClick={onDelete}>Delete</MenuItem>
- *   </MenuContent>
- * </Menu>
- * ```
- *
- * Built on `@radix-ui/react-dropdown-menu` (purpose-built menu
- * primitive with full WAI-ARIA menu pattern + keyboard nav
- * + type-ahead + portal mount).
- *
- * Sub-menus and controlled selection mode are deliberately out of
- * scope for v1 (Sprint 4.4) — composable via Radix primitives if
- * needed via explicit sub-component opt-in (future).
- */
-export function Menu({
-  children,
-  open,
-  defaultOpen,
-  onOpenChange,
-  closeOnItemClick = true,
-  modal = false,
-}: MenuProps) {
-  return (
-    <MenuContext.Provider value={{ closeOnItemClick }}>
-      <RadixMenu.Root
-        open={open}
-        defaultOpen={defaultOpen}
-        onOpenChange={onOpenChange}
-        modal={modal}
-      >
-        {children}
-      </RadixMenu.Root>
-    </MenuContext.Provider>
-  );
-}
-
-// ─── MenuTrigger ─────────────────────────────────────────────────
-
-/**
- * `<MenuTrigger>` — the element that opens the menu.
- *
- * Always renders the immediate child via Radix Slot (`asChild`) — the
- * child receives the click handler + `aria-haspopup="menu"` +
- * `aria-expanded` reactive to open state. Pass any interactive
- * component as the child (`<IconButton>`, `<Button>`, `<Avatar>`,
- * custom).
- */
-export function MenuTrigger({ children }: MenuTriggerProps) {
-  return <RadixMenu.Trigger asChild>{children}</RadixMenu.Trigger>;
-}
-
-// ─── MenuContent ─────────────────────────────────────────────────
-
-/**
- * `<MenuContent>` — the floating panel.
- *
- * Lazy-mounted via Radix Portal — zero DOM cost when the menu is
- * closed (one of the perf properties we inherit from Radix +
- * Atlaskit-style menus).
- *
- * Placement / sideOffset are read from the parent `<Menu>` via
- * Radix context — we re-pull the `<Menu>` props via the
- * `MenuContext` here.
- *
- * NB: placement is read from PARENT MENU PROPS, not from
- * `<MenuContent>` directly — keeps the floating-positioning API on
- * the provider where it belongs.
- */
-export const MenuContent = forwardRef<HTMLDivElement, MenuContentProps>(
-  function MenuContent(props, ref) {
-    const { children, minWidth, className, sx } = props;
-    const v = menuVariants();
-
-    // NB: we don't read `placement` from MenuContext (Radix Root
-    // doesn't surface those props to descendants). Instead, the
-    // consumer passes them on `<Menu>` and they're forwarded into
-    // `<MenuContent>` via context-style props — to keep the API
-    // simple, we DON'T expose placement on MenuContent itself; the
-    // user sets it on Menu. We achieve this by reading the MenuProps
-    // off the Radix-internal context… actually, simpler: we just
-    // accept the default `bottom-start` from Radix and let the
-    // consumer pass `side`/`align` via MenuContent if they want fine
-    // control. For now, hardcode the most common defaults; Sprint
-    // 4.4-bis can lift this if real demand emerges.
-    const { side, align } = placementToRadix('bottom-start');
-
-    return (
-      <RadixMenu.Portal>
-        <RadixMenu.Content
-          ref={ref}
-          side={side}
-          align={align}
-          sideOffset={6}
-          style={
-            minWidth !== undefined
-              ? { minWidth: typeof minWidth === 'number' ? `${minWidth}px` : minWidth }
-              : undefined
-          }
-          className={cn(v.content(), sx, className)}
-        >
-          {children}
-        </RadixMenu.Content>
-      </RadixMenu.Portal>
-    );
-  }
-);
-
-MenuContent.displayName = 'MenuContent';
-
-// ─── MenuItem ────────────────────────────────────────────────────
-
-/**
- * `<MenuItem>` — clickable row inside the menu.
- *
- * Memoized via `React.memo` for performance — re-renders only when
- * its own props change, not when sibling items mutate. Pattern
- * inspired by Atlaskit's `ButtonItem` optimization (one of the
- * reasons Atlaskit menus stay responsive on large item lists).
- *
- * Bridge integration:
- *   - `access` — hides / disables the item per RBAC
- *   - `visibleWhen` — engine-reactive predicate
- *
- * Both gates fold into the visible/disabled state; when the
- * predicate returns `false` OR `access` denies visibility, the
- * item renders `null` (does NOT occupy a row in the menu, vs
- * disabled which renders dimmed-but-present).
- */
-function MenuItemImpl(props: MenuItemProps) {
-  const {
-    children,
-    onClick,
-    icon,
-    endIcon,
-    disabled: disabledProp,
-    selected,
-    color = 'default',
-    access,
-    visibleWhen,
-    className,
-    sx,
-  } = props;
-
-  const { closeOnItemClick } = useContext(MenuContext);
-
-  // Bridge hooks — always called (rules-of-hooks).
-  const bridge = useContext(DashFormContext);
-  const isBridgeVisible = useEngineVisibility(bridge?.engine, visibleWhen);
-  const accessState = useAccessState(access);
-
-  if (!isBridgeVisible || !accessState.visible) return null;
-
-  const isDisabled =
-    Boolean(disabledProp) || accessState.disabled || accessState.readonly;
-
-  const v = menuVariants({ color, selected });
-
-  return (
-    <RadixMenu.Item
-      disabled={isDisabled}
-      onSelect={(e) => {
-        if (isDisabled) return;
-        // Suppress default close behaviour when the parent <Menu>
-        // explicitly opted out (filter / multi-select pattern).
-        if (!closeOnItemClick) e.preventDefault();
-        onClick?.();
-      }}
-      className={cn(v.item(), sx, className)}
-    >
-      {icon != null && (
-        <span className={v.itemIcon()}>{icon}</span>
-      )}
-      <span className={v.itemLabel()}>{children}</span>
-      {endIcon != null && (
-        <span className={v.itemEnd()}>{endIcon}</span>
-      )}
-    </RadixMenu.Item>
-  );
-}
-
-export const MenuItem = memo(MenuItemImpl);
-MenuItem.displayName = 'MenuItem';
-
-// ─── MenuLabel ───────────────────────────────────────────────────
-
-/**
- * `<MenuLabel>` — non-interactive group heading.
- *
- * Renders via Radix `DropdownMenu.Label` which carries the right
- * ARIA semantics (`role="presentation"` — not announced as a
- * `menuitem` by screen readers).
- */
-export function MenuLabel({ children, className }: MenuLabelProps) {
-  const v = menuVariants();
-  return (
-    <RadixMenu.Label className={cn(v.label(), className)}>
-      {children}
-    </RadixMenu.Label>
-  );
-}
-
-// ─── MenuSeparator ───────────────────────────────────────────────
-
-/**
- * `<MenuSeparator>` — horizontal divider between items.
- *
- * Renders via Radix `DropdownMenu.Separator` — semantically correct
- * `role="separator"` for screen readers navigating the menu.
- */
-export function MenuSeparator({ className }: MenuSeparatorProps) {
-  const v = menuVariants();
-  return <RadixMenu.Separator className={cn(v.separator(), className)} />;
-}
-
-// ─── MenuSkeleton ────────────────────────────────────────────────
-
-/**
- * `<MenuSkeleton>` — Atlaskit-style loading state.
- *
- * Renders `count` placeholder rows (default 3) inside the menu while
- * real items are being fetched. Each row matches the geometry of a
- * real `<MenuItem>` (height, padding, icon slot) so the layout
- * doesn't jump when the real data arrives.
- *
- * `withHeading=true` adds a skeleton heading at the top, mimicking a
- * `<MenuLabel>` — useful when the real menu starts with a section
- * label.
- *
- * Pure visual — no animation overhead beyond Tailwind's
- * `animate-pulse` (motion-reduce-safe).
- *
- * @example
- * ```tsx
- * <MenuContent>
- *   {isLoading ? (
- *     <MenuSkeleton count={5} withHeading />
- *   ) : (
- *     items.map((it) => <MenuItem key={it.id}>{it.label}</MenuItem>)
- *   )}
- * </MenuContent>
- * ```
- */
-export function MenuSkeleton({
-  count = 3,
-  withHeading = false,
-  className,
-}: MenuSkeletonProps) {
-  const v = menuVariants();
-  return (
-    <div
-      role="presentation"
-      aria-hidden="true"
-      className={cn('animate-pulse motion-reduce:animate-none', className)}
-    >
-      {withHeading && (
-        <div className={cn(v.label(), 'pointer-events-none')}>
-          <span className="inline-block h-2.5 w-16 rounded-sm bg-neutral-200" />
-        </div>
-      )}
-      {Array.from({ length: count }).map((_, i) => (
-        <SkeletonRow key={i} />
-      ))}
-    </div>
-  );
-}
-
-/**
- * One skeleton row — matches the dimensions of a real `<MenuItem>`
- * (icon slot + label slot). Internal — not exported.
- *
- * @internal
- */
-function SkeletonRow() {
-  return (
-    <div className="flex items-center gap-2 px-3 py-1.5 mx-1 my-0.5">
-      <span className="inline-block h-4 w-4 shrink-0 rounded-sm bg-neutral-200" />
-      <span className="inline-block h-3 flex-1 rounded-sm bg-neutral-200" />
-    </div>
-  );
-}
-
-// Re-export ReactNode type for downstream consumers — keeps the
-// import surface for the Menu module self-contained.
-export type { ReactNode };

package/src/components/Menu/menu.types.ts

@@ -1,221 +0,0 @@
-import type { ReactNode } from 'react';
-import type { ClassValue } from 'tailwind-variants';
-import type { Engine } from '@dashforge/ui-core';
-import type { AccessRequirement } from '@dashforge/rbac';
-
-/**
- * Placement of the menu content relative to the trigger. Maps 1:1 to
- * Radix DropdownMenu's `side` + `align` pair via the internal
- * helpers in Menu.tsx.
- */
-export type MenuPlacement =
-  | 'top'
-  | 'top-start'
-  | 'top-end'
-  | 'bottom'
-  | 'bottom-start'
-  | 'bottom-end'
-  | 'left'
-  | 'left-start'
-  | 'left-end'
-  | 'right'
-  | 'right-start'
-  | 'right-end';
-
-/**
- * Props for the top-level `<Menu>` provider.
- *
- * Wraps Radix `DropdownMenu.Root`. Provides open-state coordination
- * + closeOnItemClick context for descendant `<MenuItem>`s.
- */
-export interface MenuProps {
-  /** Compound children: `<MenuTrigger>` + `<MenuContent>`. */
-  children: ReactNode;
-
-  /** Controlled open state. */
-  open?: boolean;
-
-  /** Default open state for uncontrolled mode. @default false */
-  defaultOpen?: boolean;
-
-  /** Open/close callback (controlled). */
-  onOpenChange?: (open: boolean) => void;
-
-  /**
-   * Close the menu when an item is clicked. Set to `false` for
-   * filter-style menus where item clicks should NOT dismiss (e.g.,
-   * multi-select checkbox menus, sticky filter pills).
-   * @default true
-   */
-  closeOnItemClick?: boolean;
-
-  /**
-   * Placement of the content relative to the trigger.
-   * @default 'bottom-start'
-   */
-  placement?: MenuPlacement;
-
-  /**
-   * Pixel offset between trigger and content along the perpendicular
-   * axis (e.g., for `placement='bottom-*'`, the vertical gap).
-   * @default 6
-   */
-  sideOffset?: number;
-
-  /**
-   * Modal mode (Radix). When `true`, the menu blocks interaction with
-   * the rest of the page (focus trap + outside scroll lock). When
-   * `false`, dismissal is automatic on outside-click but the page
-   * remains interactive. Default false matches the "lightweight
-   * action menu" pattern.
-   * @default false
-   */
-  modal?: boolean;
-}
-
-/**
- * Props for `<MenuTrigger>` — the element that opens the menu.
- *
- * Always renders via Radix Slot — the immediate child element
- * (typically `<IconButton>`, `<Button>`, or a custom interactive
- * component) receives the click handler, `aria-haspopup="menu"`,
- * and `aria-expanded` reactive to open state.
- */
-export interface MenuTriggerProps {
-  /** The trigger element. */
-  children: ReactNode;
-}
-
-/**
- * Props for `<MenuContent>` — the floating panel.
- *
- * Rendered through Radix `DropdownMenu.Portal`, lazily mounted only
- * when the menu is open (cost zero in DOM when closed).
- */
-export interface MenuContentProps {
-  /** Items + labels + separators + skeletons. */
-  children: ReactNode;
-
-  /** CSS min-width for the menu panel. */
-  minWidth?: number | string;
-
-  /** Standard className — appended to the root via `cn()`. */
-  className?: string;
-
-  /** Root-element class shortcut. */
-  sx?: ClassValue;
-}
-
-/**
- * Visual / semantic color of a `<MenuItem>`. `'danger'` highlights
- * destructive actions with a red hover state.
- */
-export type MenuItemColor = 'default' | 'danger';
-
-/**
- * Props for `<MenuItem>` — a clickable row inside the menu.
- *
- * Memoized (`React.memo`) for perf — re-renders only on prop change.
- * Pattern inspired by Atlaskit's ButtonItem optimization.
- */
-export interface MenuItemProps {
-  /** Item label / content. */
-  children: ReactNode;
-
-  /**
-   * Click handler. After firing, the menu closes (unless the parent
-   * `<Menu closeOnItemClick={false}>` opts out).
-   */
-  onClick?: () => void;
-
-  /** Leading icon slot. */
-  icon?: ReactNode;
-
-  /**
-   * Trailing slot — typically a keyboard shortcut (`"⌘K"`), a
-   * status hint, or a sub-menu chevron (when sub-menus arrive).
-   */
-  endIcon?: ReactNode;
-
-  /** Disabled state — suppresses click + dims the item. */
-  disabled?: boolean;
-
-  /**
-   * Visual hint of "active option" — for menus that show current
-   * selection (e.g., theme picker). No controlled selection state
-   * by design (v1) — purely visual.
-   */
-  selected?: boolean;
-
-  /**
-   * Color intent. `'danger'` highlights destructive actions
-   * (Delete, Remove, Sign out) with a red hover tint.
-   * @default 'default'
-   */
-  color?: MenuItemColor;
-
-  /**
-   * RBAC requirement. When the current subject doesn't satisfy it,
-   * the item is hidden (or disabled per `onUnauthorized`).
-   */
-  access?: AccessRequirement;
-
-  /**
-   * Reactive visibility predicate. When `false`, the item renders
-   * `null`. Use for state-driven menu items (e.g., "Restore" only
-   * when an item was just deleted).
-   */
-  visibleWhen?: (engine: Engine) => boolean;
-
-  /** Standard className. */
-  className?: string;
-
-  /** Root-element class shortcut. */
-  sx?: ClassValue;
-}
-
-/**
- * Props for `<MenuLabel>` — non-interactive group heading.
- *
- * Rendered as `role="presentation"` so screen readers don't
- * announce it as a menuitem. Typical use: section dividers inside
- * a menu ("Workspace", "Account", "Help").
- */
-export interface MenuLabelProps {
-  children: ReactNode;
-  className?: string;
-}
-
-/**
- * Props for `<MenuSeparator>` — horizontal divider between items.
- */
-export interface MenuSeparatorProps {
-  className?: string;
-}
-
-/**
- * Props for `<MenuSkeleton>` — Atlaskit-style loading state.
- *
- * Renders N placeholder rows that mimic the menu's item geometry,
- * giving the user immediate visual feedback while the real items
- * are being fetched (e.g., "Recent files" pulled from an API).
- * Strictly perceived-performance UX: no animation overhead beyond
- * Tailwind's `animate-pulse`.
- */
-export interface MenuSkeletonProps {
-  /**
-   * Number of skeleton item rows to render.
-   * @default 3
-   */
-  count?: number;
-
-  /**
-   * Show a skeleton heading at the top of the list (matches the
-   * height + indent of a real `<MenuLabel>`).
-   * @default false
-   */
-  withHeading?: boolean;
-
-  /** Standard className. */
-  className?: string;
-}

package/src/components/Menu/menu.variants.ts

@@ -1,132 +0,0 @@
-import { tv, type VariantProps } from 'tailwind-variants';
-import type { MenuPlacement } from './menu.types.js';
-
-/**
- * Tailwind-variants recipe for the Menu family.
- *
- * The whole menu family is styled here in one TV instance so the
- * compound rules (item color × selected × danger, etc.) live in
- * one source of truth.
- *
- * Slots:
- *   - `content`   — floating panel (DropdownMenu.Content)
- *   - `item`      — clickable row (DropdownMenu.Item)
- *   - `itemIcon`  — leading icon container
- *   - `itemLabel` — text content slot
- *   - `itemEnd`   — trailing slot (shortcut hint, chevron, …)
- *   - `label`     — non-interactive heading (DropdownMenu.Label)
- *   - `separator` — divider (DropdownMenu.Separator)
- *   - `skeleton`  — placeholder item (visual only, no Radix slot)
- */
-export const menuVariants = tv({
-  slots: {
-    content: [
-      'z-50 min-w-[180px] py-1.5',
-      // Surface elevation: `bg-white` is hardcoded (does NOT
-      // auto-invert via the dashforgePreset CSS-var swap), so we
-      // pair it with `dark:bg-neutral-100` (target #171717 — one
-      // elevation tier above page surface in dark mode). This is
-      // Category B of THEME-AUDIT.md — must stay on the same
-      // string literal so the whitelist regex matches.
-      'rounded-md border border-neutral-200 bg-white dark:bg-neutral-100 shadow-lg',
-      // Smooth fade-in via Radix's data-state attributes. Motion-
-      // reduce gated.
-      'data-[state=open]:animate-in data-[state=closed]:animate-out',
-      'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
-      'data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
-      'motion-reduce:animate-none motion-reduce:transition-none',
-      // List reset (defensive — same defensive pattern as
-      // Autocomplete listbox after the listbox-bullets fix in 1.0.1).
-      'list-none pl-0 m-0',
-    ],
-    item: [
-      'group relative flex cursor-pointer select-none items-center gap-2',
-      'px-3 py-1.5 mx-1 my-0.5',
-      'rounded-md text-sm text-neutral-900',
-      'outline-none',
-      // Radix sets data-highlighted when the item is keyboard-focused
-      // OR hovered. We anchor the active visual state to that single
-      // attribute so keyboard + mouse interactions look identical.
-      'data-[highlighted]:bg-neutral-100',
-      // Disabled (Radix sets data-disabled).
-      'data-[disabled]:opacity-50 data-[disabled]:cursor-not-allowed data-[disabled]:pointer-events-none',
-      'transition-colors duration-100',
-      'motion-reduce:transition-none',
-    ],
-    itemIcon: 'shrink-0 inline-flex items-center justify-center w-4 h-4',
-    itemLabel: 'flex-1 truncate',
-    itemEnd: 'shrink-0 ml-3 inline-flex items-center text-xs text-neutral-500',
-    label: [
-      'px-3 py-1 mx-1 mt-1 text-xs font-medium uppercase tracking-wide',
-      'text-neutral-500',
-    ],
-    separator: 'h-px my-1 mx-1 bg-neutral-200',
-    skeleton: [
-      'flex items-center gap-2 px-3 py-1.5 mx-1 my-0.5',
-      'animate-pulse motion-reduce:animate-none',
-    ],
-  },
-  variants: {
-    /**
-     * Item color intent. `'danger'` highlights destructive actions
-     * (Delete, Sign out) with red bg on hover. Both bg and text
-     * shift to the danger palette when the item is highlighted.
-     */
-    color: {
-      default: {},
-      danger: {
-        item: [
-          'text-danger-700',
-          // Hover + keyboard focus → red soft bg + saturated text.
-          'data-[highlighted]:bg-danger-50 data-[highlighted]:text-danger-800',
-          // Dark mode: bg-danger-50 doesn't auto-invert (color
-          // palettes don't), so we add the explicit dark variant.
-          // The `text-danger-700` base also gets a dark counterpart
-          // for readability on the dark surface.
-          'dark:text-danger-300',
-          'dark:data-[highlighted]:bg-danger-950 dark:data-[highlighted]:text-danger-200',
-        ],
-        itemIcon: 'text-danger-600 dark:text-danger-400',
-      },
-    },
-    /**
-     * Visual `selected` hint — adds a faint primary bg + the
-     * leading edge gets a primary accent. Pure visual; v1 has no
-     * controlled selection state machine.
-     */
-    selected: {
-      true: {
-        item: [
-          'bg-primary-50 text-primary-900',
-          'dark:bg-primary-950 dark:text-primary-100',
-        ],
-        itemIcon: 'text-primary-600 dark:text-primary-400',
-      },
-    },
-  },
-  defaultVariants: {
-    color: 'default',
-  },
-});
-
-export type MenuVariants = VariantProps<typeof menuVariants>;
-
-/**
- * Resolve a `MenuPlacement` enum to Radix `side` + `align` props.
- * Single source of truth so Menu.tsx doesn't need a switch statement.
- */
-export function placementToRadix(placement: MenuPlacement): {
-  side: 'top' | 'right' | 'bottom' | 'left';
-  align: 'start' | 'center' | 'end';
-} {
-  // The format is `<side>` or `<side>-<align>`. Center is the default
-  // when no `-start` / `-end` suffix is present.
-  const [side, alignSuffix] = placement.split('-') as [
-    'top' | 'right' | 'bottom' | 'left',
-    'start' | 'end' | undefined,
-  ];
-  return {
-    side,
-    align: alignSuffix ?? 'center',
-  };
-}