@dashforge/tw 1.1.0 → 1.2.0

package/src/components/LeftNav/leftNav.types.ts

@@ -1,120 +0,0 @@
-import type {
-  ReactNode,
-  ComponentType,
-  AnchorHTMLAttributes,
-  Ref,
-} from 'react';
-import type { AccessRequirement } from '@dashforge/rbac';
-import type { LeftNavVariants } from './leftNav.variants.js';
-
-/**
- * One row in the LeftNav. May be either a clickable item OR a group
- * (a header that owns nested children, optionally collapsible).
- */
-export type LeftNavNode = LeftNavItem | LeftNavGroup;
-
-export interface LeftNavItem {
-  kind?: 'item';
-  /** Stable id used for `activeId` matching + React keys. */
-  id: string;
-  label: ReactNode;
-  icon?: ReactNode;
-  /**
-   * Destination for navigation. Omit for a pure-callback item (use
-   * `onSelect`).
-   */
-  href?: string;
-  /** Fired when the row is clicked (in addition to navigation). */
-  onSelect?: () => void;
-  /** Optional pill / counter rendered to the right of the label. */
-  badge?: ReactNode;
-  /** Per-item disabled flag. */
-  disabled?: boolean;
-  /** RBAC access requirement — hides / disables the row. */
-  access?: AccessRequirement;
-}
-
-export interface LeftNavGroup {
-  kind: 'group';
-  id: string;
-  label: ReactNode;
-  icon?: ReactNode;
-  children: LeftNavItem[];
-  /**
-   * Initial expanded state when used in uncontrolled mode. Default
-   * `true` (groups open by default — most app navs want immediate
-   * visibility).
-   */
-  defaultExpanded?: boolean;
-  /** Controlled expanded state. Provide `onExpandedChange` to update. */
-  expanded?: boolean;
-  /** RBAC access requirement — hides / disables the whole group. */
-  access?: AccessRequirement;
-}
-
-/**
- * Polymorphic link component prop. Defaults to `<a>`. Pass a
- * router-aware component (react-router `Link`, Next `Link`) for SPA
- * navigation.
- */
-export type LeftNavLinkComponent = ComponentType<
-  AnchorHTMLAttributes<HTMLAnchorElement> & {
-    ref?: Ref<HTMLAnchorElement>;
-  }
->;
-
-export interface LeftNavSlotProps {
-  root?: { className?: string };
-  brand?: { className?: string };
-  list?: { className?: string };
-  item?: { className?: string };
-  itemLink?: { className?: string };
-  itemActive?: { className?: string };
-  itemIcon?: { className?: string };
-  itemLabel?: { className?: string };
-  itemBadge?: { className?: string };
-  group?: { className?: string };
-  groupHeader?: { className?: string };
-  groupChildren?: { className?: string };
-  footer?: { className?: string };
-  collapseToggle?: { className?: string };
-}
-
-/**
- * Props for `<LeftNav>`.
- *
- * Router-agnostic sidebar navigation. The consumer drives the active
- * item via `activeId` (typically derived from the current route).
- *
- * Rail / drawer responsive behaviour is handled by `<AppShell>`; this
- * component renders the actual nav content and exposes a `collapsed`
- * prop for the icon-only "rail" rendering.
- */
-export interface LeftNavProps extends LeftNavVariants {
-  items: LeftNavNode[];
-  /** Currently-active item id (highlight + `aria-current="page"`). */
-  activeId?: string;
-  /**
-   * Icon-only rail mode. When `true`, labels and group children are
-   * visually hidden (kept for screen readers via `sr-only`).
-   */
-  collapsed?: boolean;
-  /** Fired when the user clicks the collapse-toggle button. */
-  onCollapseChange?: (collapsed: boolean) => void;
-  /** Fired when a group's expanded state changes (controlled or not). */
-  onGroupExpandedChange?: (groupId: string, expanded: boolean) => void;
-  /** Brand / logo node rendered at the top. */
-  brand?: ReactNode;
-  /** Footer node (e.g., user badge). */
-  footer?: ReactNode;
-  /** Override the link component. @default 'a' */
-  linkComponent?: LeftNavLinkComponent;
-  /** Visible label of the nav landmark. @default 'Main navigation' */
-  ariaLabel?: string;
-  /** Root className shortcut. */
-  sx?: string;
-  /** Per-slot className overrides. */
-  slotProps?: LeftNavSlotProps;
-  /** Show / hide the collapse toggle button. @default true */
-  showCollapseToggle?: boolean;
-}

package/src/components/LeftNav/leftNav.variants.ts

@@ -1,107 +0,0 @@
-import { tv, type VariantProps } from 'tailwind-variants';
-
-/**
- * Tailwind-variants recipe for `<LeftNav>`.
- *
- * Slots:
- *   - `root`           — `<nav>` landmark
- *   - `brand`          — top brand/logo wrapper
- *   - `list`           — `<ul>` containing items & groups
- *   - `item`           — `<li>` wrapper
- *   - `itemLink`       — clickable row (`<a>` or `<button>`)
- *   - `itemActive`     — active state on the row
- *   - `itemIcon`       — icon slot inside a row
- *   - `itemLabel`      — text label slot
- *   - `itemBadge`      — right-aligned pill
- *   - `group`          — wrapper around a group header + children
- *   - `groupHeader`    — clickable header row (`<button>`)
- *   - `groupChildren`  — `<ul>` containing the group's items
- *   - `footer`         — bottom slot (user badge, etc.)
- *   - `collapseToggle` — rail-mode toggle button
- */
-export const leftNavVariants = tv({
-  slots: {
-    root: [
-      'flex flex-col h-full',
-      'bg-neutral-50 border-r border-neutral-200',
-      // Width transition (rail-mode toggle) — gated on
-      // prefers-reduced-motion (WCAG 2.3.3). The new width still
-      // applies, just without the animated tween.
-      'transition-[width] duration-200 motion-reduce:transition-none motion-reduce:duration-0',
-    ],
-    brand: [
-      'flex items-center gap-2 px-3 h-14 shrink-0',
-      'border-b border-neutral-200 text-neutral-900 font-semibold',
-    ],
-    list: 'flex flex-col gap-0.5 p-2 flex-1 overflow-y-auto list-none m-0',
-    item: 'list-none',
-    itemLink: [
-      'flex items-center gap-2 px-2 py-2 rounded-md',
-      'text-sm text-neutral-700 hover:bg-neutral-100',
-      'outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50',
-      'transition-colors w-full',
-      'aria-disabled:opacity-50 aria-disabled:cursor-not-allowed',
-      'aria-disabled:hover:bg-transparent',
-      // Defensive `no-underline` — Tailwind's preflight removes the
-      // default browser anchor underline globally, but environments
-      // that DISABLE preflight (e.g. our docs-lab, where the tw
-      // section coexists with MUI's chrome) get raw browser defaults
-      // back. Without this, `<a>` items in the nav render underlined
-      // in those contexts. Explicit `no-underline` + `hover:no-underline`
-      // keeps the appearance consistent regardless of preflight state.
-      'no-underline hover:no-underline',
-    ],
-    itemActive: 'bg-primary-100 text-primary-900 font-medium',
-    itemIcon: 'shrink-0 w-5 h-5 flex items-center justify-center',
-    itemLabel: 'truncate flex-1 min-w-0 text-left',
-    itemBadge: [
-      'shrink-0 inline-flex items-center justify-center',
-      'px-1.5 h-5 rounded-full text-[10px] font-medium',
-      'bg-neutral-200 text-neutral-800',
-    ],
-    group: 'flex flex-col gap-0.5',
-    groupHeader: [
-      'flex items-center gap-2 px-2 py-2 rounded-md',
-      'text-sm font-medium text-neutral-900 hover:bg-neutral-100',
-      'outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50',
-      'transition-colors w-full',
-    ],
-    groupChildren: 'flex flex-col gap-0.5 pl-6 list-none m-0',
-    footer: [
-      'border-t border-neutral-200 p-3 shrink-0',
-      'flex items-center gap-2',
-    ],
-    collapseToggle: [
-      'inline-flex items-center justify-center w-8 h-8 shrink-0',
-      'rounded-md text-neutral-600 hover:bg-neutral-100',
-      'outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50',
-      'transition-colors',
-    ],
-  },
-  variants: {
-    width: {
-      sm: { root: 'w-48' },
-      md: { root: 'w-60' },
-      lg: { root: 'w-72' },
-    },
-    collapsed: {
-      true: {
-        root: 'w-14',
-        brand: 'justify-center px-0',
-        list: 'p-1 items-center',
-        itemLink: 'justify-center px-0 py-2.5',
-        itemLabel: 'sr-only',
-        itemBadge: 'hidden',
-        groupHeader: 'justify-center px-0',
-        groupChildren: 'hidden',
-        footer: 'justify-center px-0',
-      },
-    },
-  },
-  defaultVariants: {
-    width: 'md',
-    collapsed: false,
-  },
-});
-
-export type LeftNavVariants = VariantProps<typeof leftNavVariants>;

package/src/components/Menu/Menu.test.tsx

@@ -1,408 +0,0 @@
-// @vitest-environment jsdom
-import * as React from 'react';
-import { describe, it, expect, vi, afterEach } from 'vitest';
-import { render, screen, fireEvent, cleanup } from '@testing-library/react';
-import { RbacProvider } from '@dashforge/rbac';
-import type { RbacPolicy, Subject } from '@dashforge/rbac';
-import {
-  Menu,
-  MenuContent,
-  MenuItem,
-  MenuLabel,
-  MenuSeparator,
-  MenuSkeleton,
-  MenuTrigger,
-} from './Menu.js';
-
-void React;
-afterEach(() => cleanup());
-
-/**
- * Unit tests for the Menu family.
- *
- * Testing strategy: open the menu via `defaultOpen={true}` instead
- * of clicking the trigger. Radix DropdownMenu's open/close flow
- * uses pointer events that don't translate cleanly to jsdom's
- * `fireEvent.click` — and that logic is Radix's responsibility
- * anyway (already covered by their tests). Our tests focus on:
- *   - Our `<MenuItem>` props (onClick / disabled / selected / color /
- *     icon / endIcon)
- *   - Bridge integration on `<MenuItem>` (access / visibleWhen)
- *   - Our wrapper components (`<MenuLabel>`, `<MenuSeparator>`,
- *     `<MenuSkeleton>`)
- *   - `closeOnItemClick` propagation
- *
- * NB: Radix DropdownMenu uses Portal — when `defaultOpen={true}`,
- * the content renders to `document.body`. We assert via
- * `screen.getByText` / `screen.getByRole` which scan the whole
- * document.
- */
-
-const NO_ACCESS_POLICY: RbacPolicy = {
-  roles: [{ name: 'guest', permissions: [] }],
-};
-const ADMIN_POLICY: RbacPolicy = {
-  roles: [
-    {
-      name: 'admin',
-      permissions: [{ resource: '*', action: '*', effect: 'allow' }],
-    },
-  ],
-};
-const guestSubject: Subject = { id: 'g', roles: ['guest'] };
-const adminSubject: Subject = { id: 'a', roles: ['admin'] };
-
-describe('<Menu>', () => {
-  describe('rendering', () => {
-    it('renders the trigger', () => {
-      render(
-        <Menu>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem>Item</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      expect(screen.getByRole('button', { name: /open/i })).toBeTruthy();
-    });
-
-    it('does NOT render content when closed (lazy mount)', () => {
-      render(
-        <Menu>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem>Hidden item</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      // Without defaultOpen, Radix Portal isn't mounted.
-      expect(screen.queryByText('Hidden item')).toBeNull();
-    });
-
-    it('renders content when defaultOpen=true', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem>Visible item</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      expect(screen.getByText('Visible item')).toBeTruthy();
-    });
-  });
-
-  describe('MenuItem rendering', () => {
-    it('renders icon prop', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem icon={<span data-testid="icon">i</span>}>
-              With icon
-            </MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      expect(screen.getByTestId('icon')).toBeTruthy();
-    });
-
-    it('renders endIcon prop', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem endIcon={<span data-testid="end">⌘K</span>}>
-              Command
-            </MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      expect(screen.getByTestId('end')).toBeTruthy();
-    });
-
-    it('renders the children as label', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem>My label</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      expect(screen.getByText('My label')).toBeTruthy();
-    });
-  });
-
-  describe('MenuItem disabled', () => {
-    it('marks the item as disabled', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem disabled>Save</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      const item = screen.getByText('Save').closest('[role="menuitem"]');
-      expect(item?.getAttribute('data-disabled')).not.toBeNull();
-    });
-  });
-
-  describe('MenuItem selected visual', () => {
-    it('applies primary bg classes when selected', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem selected>Theme: light</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      const item = screen.getByText('Theme: light').closest('[role="menuitem"]');
-      expect(item?.className).toContain('bg-primary-50');
-    });
-
-    it('does NOT apply primary bg when not selected', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem>Theme: light</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      const item = screen.getByText('Theme: light').closest('[role="menuitem"]');
-      expect(item?.className).not.toContain('bg-primary-50');
-    });
-  });
-
-  describe('MenuItem color="danger"', () => {
-    it('applies danger text class', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem color="danger">Delete</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      const item = screen.getByText('Delete').closest('[role="menuitem"]');
-      expect(item?.className).toContain('text-danger-700');
-    });
-
-    it('default color does NOT apply danger class', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem>Default</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      const item = screen.getByText('Default').closest('[role="menuitem"]');
-      expect(item?.className).not.toContain('text-danger-700');
-    });
-  });
-
-  describe('MenuItem access RBAC', () => {
-    it('hides the item for unauthorized subjects (onUnauthorized="hide")', () => {
-      render(
-        <RbacProvider policy={NO_ACCESS_POLICY} subject={guestSubject}>
-          <Menu defaultOpen>
-            <MenuTrigger>
-              <button>Open</button>
-            </MenuTrigger>
-            <MenuContent>
-              <MenuItem>Public</MenuItem>
-              <MenuItem
-                access={{
-                  resource: 'admin',
-                  action: 'manage',
-                  onUnauthorized: 'hide',
-                }}
-              >
-                Admin-only
-              </MenuItem>
-            </MenuContent>
-          </Menu>
-        </RbacProvider>
-      );
-      expect(screen.getByText('Public')).toBeTruthy();
-      expect(screen.queryByText('Admin-only')).toBeNull();
-    });
-
-    it('renders for authorized subjects', () => {
-      render(
-        <RbacProvider policy={ADMIN_POLICY} subject={adminSubject}>
-          <Menu defaultOpen>
-            <MenuTrigger>
-              <button>Open</button>
-            </MenuTrigger>
-            <MenuContent>
-              <MenuItem
-                access={{
-                  resource: 'admin',
-                  action: 'manage',
-                  onUnauthorized: 'hide',
-                }}
-              >
-                Admin-only
-              </MenuItem>
-            </MenuContent>
-          </Menu>
-        </RbacProvider>
-      );
-      expect(screen.getByText('Admin-only')).toBeTruthy();
-    });
-  });
-
-  describe('MenuItem visibleWhen', () => {
-    it('renders when predicate returns true', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem visibleWhen={() => true}>Shown</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      expect(screen.getByText('Shown')).toBeTruthy();
-    });
-
-    it('returns null when predicate returns false', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem>Always shown</MenuItem>
-            <MenuItem visibleWhen={() => false}>Hidden</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      expect(screen.getByText('Always shown')).toBeTruthy();
-      expect(screen.queryByText('Hidden')).toBeNull();
-    });
-  });
-
-  describe('MenuLabel + MenuSeparator', () => {
-    it('renders MenuLabel content', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuLabel>Section heading</MenuLabel>
-            <MenuItem>Item</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      expect(screen.getByText('Section heading')).toBeTruthy();
-    });
-
-    it('renders MenuSeparator with role="separator"', () => {
-      const { baseElement } = render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem>Above</MenuItem>
-            <MenuSeparator />
-            <MenuItem>Below</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      const sep = baseElement.querySelector('[role="separator"]');
-      expect(sep).toBeTruthy();
-    });
-  });
-
-  describe('overrides — sx + className', () => {
-    it('applies sx to a MenuItem', () => {
-      render(
-        <Menu defaultOpen>
-          <MenuTrigger>
-            <button>Open</button>
-          </MenuTrigger>
-          <MenuContent>
-            <MenuItem sx="ring-2 ring-purple-500">x</MenuItem>
-          </MenuContent>
-        </Menu>
-      );
-      const item = screen.getByText('x').closest('[role="menuitem"]');
-      expect(item?.className).toContain('ring-purple-500');
-    });
-  });
-});
-
-// ─── MenuSkeleton — standalone tests (no Menu wrapper) ───────────
-
-describe('<MenuSkeleton>', () => {
-  it('renders the default 3 placeholder rows', () => {
-    const { container } = render(<MenuSkeleton />);
-    // Each row is a div with the inline pulse classes; we match on
-    // the unique "h-3 flex-1 rounded-sm bg-neutral-200" inline bone.
-    const rows = container.querySelectorAll('.h-3.flex-1.rounded-sm');
-    expect(rows.length).toBe(3);
-  });
-
-  it('renders custom count', () => {
-    const { container } = render(<MenuSkeleton count={7} />);
-    const rows = container.querySelectorAll('.h-3.flex-1.rounded-sm');
-    expect(rows.length).toBe(7);
-  });
-
-  it('renders a skeleton heading when withHeading=true', () => {
-    const { container } = render(<MenuSkeleton withHeading />);
-    // Heading is the .uppercase wrapper (matches the MenuLabel style).
-    expect(container.querySelector('.uppercase')).toBeTruthy();
-  });
-
-  it('omits the heading by default', () => {
-    const { container } = render(<MenuSkeleton />);
-    expect(container.querySelector('.uppercase')).toBeNull();
-  });
-
-  it('has aria-hidden="true" (decorative)', () => {
-    const { container } = render(<MenuSkeleton />);
-    expect(container.firstElementChild?.getAttribute('aria-hidden')).toBe(
-      'true'
-    );
-  });
-
-  it('uses animate-pulse class (motion-reduce-safe)', () => {
-    const { container } = render(<MenuSkeleton />);
-    expect(container.firstElementChild?.className).toContain('animate-pulse');
-    expect(container.firstElementChild?.className).toContain(
-      'motion-reduce:animate-none'
-    );
-  });
-});