@dashforge/tw 1.0.0 → 1.1.1

package/src/components/LeftNav/LeftNav.test.tsx

@@ -1,302 +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 { LeftNav } from './LeftNav.js';
-import type { LeftNavNode } from './leftNav.types.js';
-
-void React;
-afterEach(() => cleanup());
-
-const flatNav: LeftNavNode[] = [
-  { id: 'home', label: 'Home', href: '/' },
-  { id: 'reports', label: 'Reports', href: '/reports' },
-  { id: 'settings', label: 'Settings', href: '/settings' },
-];
-
-const nestedNav: LeftNavNode[] = [
-  { id: 'home', label: 'Home', href: '/' },
-  {
-    kind: 'group',
-    id: 'sales',
-    label: 'Sales',
-    children: [
-      { id: 'invoices', label: 'Invoices', href: '/invoices' },
-      { id: 'customers', label: 'Customers', href: '/customers' },
-    ],
-  },
-];
-
-describe('<LeftNav>', () => {
-  describe('rendering', () => {
-    it('renders a nav landmark with the default aria-label', () => {
-      render(<LeftNav items={flatNav} />);
-      expect(
-        screen.getByRole('navigation', { name: 'Main navigation' })
-      ).toBeTruthy();
-    });
-
-    it('renders a custom aria-label', () => {
-      render(<LeftNav items={flatNav} ariaLabel="App nav" />);
-      expect(
-        screen.getByRole('navigation', { name: 'App nav' })
-      ).toBeTruthy();
-    });
-
-    it('renders one link per flat item', () => {
-      render(<LeftNav items={flatNav} />);
-      expect(screen.getAllByRole('link')).toHaveLength(3);
-    });
-
-    it('renders a brand slot', () => {
-      render(
-        <LeftNav
-          items={flatNav}
-          brand={<span data-testid="brand">Dashforge</span>}
-        />
-      );
-      expect(screen.getByTestId('brand')).toBeTruthy();
-    });
-
-    it('renders a footer slot', () => {
-      render(
-        <LeftNav
-          items={flatNav}
-          footer={<span data-testid="footer">user@x.io</span>}
-        />
-      );
-      expect(screen.getByTestId('footer')).toBeTruthy();
-    });
-  });
-
-  describe('active item', () => {
-    it('marks the active item with aria-current="page"', () => {
-      render(<LeftNav items={flatNav} activeId="reports" />);
-      const link = screen.getByRole('link', { name: 'Reports' });
-      expect(link.getAttribute('aria-current')).toBe('page');
-    });
-
-    it('marks NO item when activeId is missing or unknown', () => {
-      render(<LeftNav items={flatNav} activeId="unknown" />);
-      const links = screen.getAllByRole('link');
-      links.forEach((l) => {
-        expect(l.getAttribute('aria-current')).toBeNull();
-      });
-    });
-  });
-
-  describe('items without href render as button', () => {
-    it('renders a button when only onSelect is provided', () => {
-      const onSelect = vi.fn();
-      render(
-        <LeftNav
-          items={[{ id: 'logout', label: 'Logout', onSelect }]}
-        />
-      );
-      const btn = screen.getByRole('button', { name: 'Logout' });
-      expect(btn.tagName).toBe('BUTTON');
-      fireEvent.click(btn);
-      expect(onSelect).toHaveBeenCalled();
-    });
-  });
-
-  describe('disabled state', () => {
-    it('does not call onSelect on a disabled item', () => {
-      const onSelect = vi.fn();
-      render(
-        <LeftNav
-          items={[{ id: 'x', label: 'X', onSelect, disabled: true }]}
-        />
-      );
-      fireEvent.click(screen.getByRole('button', { name: 'X' }));
-      expect(onSelect).not.toHaveBeenCalled();
-    });
-
-    it('marks the disabled link with aria-disabled', () => {
-      render(
-        <LeftNav
-          items={[
-            { id: 'x', label: 'X', href: '/x', disabled: true },
-          ]}
-        />
-      );
-      const link = screen.getByRole('link', { name: 'X' });
-      expect(link.getAttribute('aria-disabled')).toBe('true');
-    });
-  });
-
-  describe('groups (nested)', () => {
-    it('renders a group header as a button with aria-expanded', () => {
-      render(<LeftNav items={nestedNav} />);
-      const header = screen.getByRole('button', { name: /Sales/ });
-      expect(header.getAttribute('aria-expanded')).toBe('true');
-    });
-
-    it('shows group children when expanded (default true)', () => {
-      render(<LeftNav items={nestedNav} />);
-      expect(screen.getByRole('link', { name: 'Invoices' })).toBeTruthy();
-      expect(screen.getByRole('link', { name: 'Customers' })).toBeTruthy();
-    });
-
-    it('hides group children after the user clicks the header', () => {
-      render(<LeftNav items={nestedNav} />);
-      const header = screen.getByRole('button', { name: /Sales/ });
-      fireEvent.click(header);
-      expect(screen.queryByRole('link', { name: 'Invoices' })).toBeNull();
-    });
-
-    it('starts collapsed when defaultExpanded=false', () => {
-      const items: LeftNavNode[] = [
-        {
-          kind: 'group',
-          id: 'g',
-          label: 'Group',
-          defaultExpanded: false,
-          children: [{ id: 'c', label: 'Child', href: '/c' }],
-        },
-      ];
-      render(<LeftNav items={items} />);
-      expect(screen.queryByRole('link', { name: 'Child' })).toBeNull();
-    });
-
-    it('honours controlled `expanded` prop', () => {
-      const items: LeftNavNode[] = [
-        {
-          kind: 'group',
-          id: 'g',
-          label: 'Group',
-          expanded: false,
-          children: [{ id: 'c', label: 'Child', href: '/c' }],
-        },
-      ];
-      const { rerender } = render(<LeftNav items={items} />);
-      expect(screen.queryByRole('link', { name: 'Child' })).toBeNull();
-      const expanded: LeftNavNode[] = [
-        { ...(items[0] as { expanded: boolean }), expanded: true } as LeftNavNode,
-      ];
-      rerender(<LeftNav items={expanded} />);
-      expect(screen.getByRole('link', { name: 'Child' })).toBeTruthy();
-    });
-
-    it('fires onGroupExpandedChange when toggled', () => {
-      const cb = vi.fn();
-      render(
-        <LeftNav items={nestedNav} onGroupExpandedChange={cb} />
-      );
-      fireEvent.click(screen.getByRole('button', { name: /Sales/ }));
-      expect(cb).toHaveBeenCalledWith('sales', false);
-    });
-  });
-
-  describe('collapsed (rail mode)', () => {
-    it('hides labels visually via sr-only when collapsed', () => {
-      const { container } = render(
-        <LeftNav items={flatNav} collapsed />
-      );
-      // Labels are still in the DOM, just hidden — accessible name
-      // resolution still works.
-      const link = screen.getByRole('link', { name: 'Home' });
-      expect(link).toBeTruthy();
-      // The label span carries the sr-only class.
-      const labelSpans = container.querySelectorAll('.sr-only');
-      expect(labelSpans.length).toBeGreaterThanOrEqual(3);
-    });
-
-    it('shows a tooltip via `title` for string labels in rail mode', () => {
-      render(<LeftNav items={flatNav} collapsed />);
-      const link = screen.getByRole('link', { name: 'Home' });
-      expect(link.getAttribute('title')).toBe('Home');
-    });
-
-    it('fires onCollapseChange when the toggle is clicked', () => {
-      const cb = vi.fn();
-      render(<LeftNav items={flatNav} onCollapseChange={cb} />);
-      fireEvent.click(
-        screen.getByRole('button', { name: /Collapse navigation/ })
-      );
-      expect(cb).toHaveBeenCalledWith(true);
-    });
-
-    it('renders the toggle as Expand-button when already collapsed', () => {
-      render(<LeftNav items={flatNav} collapsed onCollapseChange={vi.fn()} />);
-      expect(
-        screen.getByRole('button', { name: /Expand navigation/ })
-      ).toBeTruthy();
-    });
-
-    it('hides the toggle button when showCollapseToggle=false', () => {
-      render(
-        <LeftNav
-          items={flatNav}
-          onCollapseChange={vi.fn()}
-          showCollapseToggle={false}
-        />
-      );
-      expect(
-        screen.queryByRole('button', { name: /(Collapse|Expand) navigation/ })
-      ).toBeNull();
-    });
-  });
-
-  describe('polymorphic linkComponent', () => {
-    it('uses the supplied link component for every linked item', () => {
-      const MyLink = vi.fn(
-        ({
-          children,
-          ...rest
-        }: React.AnchorHTMLAttributes<HTMLAnchorElement>) => (
-          <a data-testid="my-link" {...rest}>
-            {children}
-          </a>
-        )
-      );
-      render(<LeftNav items={flatNav} linkComponent={MyLink} />);
-      expect(screen.getAllByTestId('my-link')).toHaveLength(3);
-    });
-  });
-
-  describe('badges', () => {
-    it('renders a badge node next to the label', () => {
-      const items: LeftNavNode[] = [
-        {
-          id: 'inbox',
-          label: 'Inbox',
-          href: '/inbox',
-          badge: <span data-testid="badge">42</span>,
-        },
-      ];
-      render(<LeftNav items={items} />);
-      expect(screen.getByTestId('badge')).toBeTruthy();
-    });
-
-    it('hides the badge in collapsed/rail mode', () => {
-      const items: LeftNavNode[] = [
-        {
-          id: 'inbox',
-          label: 'Inbox',
-          href: '/inbox',
-          badge: <span data-testid="badge">42</span>,
-        },
-      ];
-      render(<LeftNav items={items} collapsed />);
-      expect(screen.queryByTestId('badge')).toBeNull();
-    });
-  });
-
-  describe('width variants', () => {
-    it('renders sm / md / lg without throwing', () => {
-      (['sm', 'md', 'lg'] as const).forEach((w) => {
-        const { unmount } = render(<LeftNav items={flatNav} width={w} />);
-        expect(
-          screen.getByRole('navigation', { name: 'Main navigation' })
-        ).toBeTruthy();
-        unmount();
-      });
-    });
-  });
-});

package/src/components/LeftNav/LeftNav.tsx

@@ -1,330 +0,0 @@
-import { useCallback, useState } from 'react';
-import { cn } from '../../utils/cn.js';
-import { useAccessState } from '../../hooks/useAccessState.js';
-import { leftNavVariants } from './leftNav.variants.js';
-import type {
-  LeftNavGroup,
-  LeftNavItem,
-  LeftNavNode,
-  LeftNavProps,
-} from './leftNav.types.js';
-
-/** Type-narrowing guard for `LeftNavGroup`. */
-function isGroup(node: LeftNavNode): node is LeftNavGroup {
-  return node.kind === 'group';
-}
-
-/**
- * Internal `<NavItemRow>` — renders one clickable row.
- *
- * Extracted as a separate component so each row can call `useAccessState`
- * unconditionally (RBAC is per-row). Without this extraction we'd have
- * a rules-of-hooks violation iterating `items.map(useAccessState)`.
- */
-function NavItemRow({
-  item,
-  isActive,
-  collapsed,
-  linkComponent,
-  v,
-  slotProps,
-}: {
-  item: LeftNavItem;
-  isActive: boolean;
-  collapsed: boolean;
-  linkComponent: NonNullable<LeftNavProps['linkComponent']>;
-  v: ReturnType<typeof leftNavVariants>;
-  slotProps: LeftNavProps['slotProps'];
-}) {
-  const accessState = useAccessState(item.access);
-  if (!accessState.visible) return null;
-
-  const isDisabled = Boolean(item.disabled) || accessState.disabled;
-  const Link = linkComponent;
-
-  const linkClasses = cn(
-    v.itemLink(),
-    isActive && v.itemActive(),
-    slotProps?.itemLink?.className,
-    isActive && slotProps?.itemActive?.className
-  );
-
-  // Visual content — same in `<a>` / `<button>` branches below.
-  const content = (
-    <>
-      {item.icon && (
-        <span
-          aria-hidden="true"
-          className={cn(v.itemIcon(), slotProps?.itemIcon?.className)}
-        >
-          {item.icon}
-        </span>
-      )}
-      <span className={cn(v.itemLabel(), slotProps?.itemLabel?.className)}>
-        {item.label}
-      </span>
-      {!collapsed && item.badge != null && (
-        <span className={cn(v.itemBadge(), slotProps?.itemBadge?.className)}>
-          {item.badge}
-        </span>
-      )}
-    </>
-  );
-
-  return (
-    <li className={cn(v.item(), slotProps?.item?.className)}>
-      {item.href !== undefined ? (
-        <Link
-          href={item.href}
-          onClick={(event) => {
-            if (isDisabled) {
-              event.preventDefault();
-              return;
-            }
-            item.onSelect?.();
-          }}
-          aria-current={isActive ? 'page' : undefined}
-          aria-disabled={isDisabled || undefined}
-          title={collapsed && typeof item.label === 'string' ? item.label : undefined}
-          className={linkClasses}
-        >
-          {content}
-        </Link>
-      ) : (
-        <button
-          type="button"
-          onClick={() => {
-            if (isDisabled) return;
-            item.onSelect?.();
-          }}
-          aria-current={isActive ? 'page' : undefined}
-          aria-disabled={isDisabled || undefined}
-          disabled={isDisabled}
-          title={collapsed && typeof item.label === 'string' ? item.label : undefined}
-          className={linkClasses}
-        >
-          {content}
-        </button>
-      )}
-    </li>
-  );
-}
-
-/**
- * Internal `<NavGroupRow>` — renders a collapsible group of items.
- *
- * State strategy: each group owns its own `expanded` state (uncontrolled
- * by default, seeded from `defaultExpanded`). A controlled mode kicks
- * in when `group.expanded` is provided — then the parent owns the state
- * and we never call `setLocalExpanded`.
- */
-function NavGroupRow({
-  group,
-  activeId,
-  collapsed,
-  linkComponent,
-  onGroupExpandedChange,
-  v,
-  slotProps,
-}: {
-  group: LeftNavGroup;
-  activeId: string | undefined;
-  collapsed: boolean;
-  linkComponent: NonNullable<LeftNavProps['linkComponent']>;
-  onGroupExpandedChange?: (groupId: string, expanded: boolean) => void;
-  v: ReturnType<typeof leftNavVariants>;
-  slotProps: LeftNavProps['slotProps'];
-}) {
-  const accessState = useAccessState(group.access);
-  const isControlled = group.expanded !== undefined;
-  const [localExpanded, setLocalExpanded] = useState<boolean>(
-    group.defaultExpanded ?? true
-  );
-  const expanded = isControlled ? Boolean(group.expanded) : localExpanded;
-
-  if (!accessState.visible) return null;
-  const isDisabled = accessState.disabled;
-
-  const toggle = () => {
-    if (isDisabled) return;
-    const next = !expanded;
-    if (!isControlled) setLocalExpanded(next);
-    onGroupExpandedChange?.(group.id, next);
-  };
-
-  // Group header ids → wires aria-controls / aria-labelledby for the
-  // expandable region the screen-reader announces.
-  const headerId = `${group.id}-header`;
-  const regionId = `${group.id}-region`;
-
-  return (
-    <li className={cn(v.group(), slotProps?.group?.className)}>
-      <button
-        id={headerId}
-        type="button"
-        onClick={toggle}
-        aria-expanded={expanded}
-        aria-controls={regionId}
-        aria-disabled={isDisabled || undefined}
-        disabled={isDisabled}
-        title={collapsed && typeof group.label === 'string' ? group.label : undefined}
-        className={cn(v.groupHeader(), slotProps?.groupHeader?.className)}
-      >
-        {group.icon && (
-          <span
-            aria-hidden="true"
-            className={cn(v.itemIcon(), slotProps?.itemIcon?.className)}
-          >
-            {group.icon}
-          </span>
-        )}
-        <span className={cn(v.itemLabel(), slotProps?.itemLabel?.className)}>
-          {group.label}
-        </span>
-        {!collapsed && (
-          <span aria-hidden="true" className="shrink-0 text-neutral-500 text-xs">
-            {expanded ? '▾' : '▸'}
-          </span>
-        )}
-      </button>
-      {expanded && (
-        <ul
-          id={regionId}
-          role="region"
-          aria-labelledby={headerId}
-          className={cn(
-            v.groupChildren(),
-            slotProps?.groupChildren?.className
-          )}
-        >
-          {group.children.map((child) => (
-            <NavItemRow
-              key={child.id}
-              item={child}
-              isActive={activeId === child.id}
-              collapsed={collapsed}
-              linkComponent={linkComponent}
-              v={v}
-              slotProps={slotProps}
-            />
-          ))}
-        </ul>
-      )}
-    </li>
-  );
-}
-
-/**
- * Dashforge TW LeftNav — router-agnostic sidebar navigation.
- *
- * Pure presentational. The consumer wires `activeId` from the current
- * route. Each row renders as a real `<a>` (with `href`) or a `<button>`
- * (with `onSelect`); `linkComponent` swaps in a router-aware link
- * component for SPA navigation.
- *
- * Modes:
- *   - **Expanded** (`collapsed={false}`): full-width with labels +
- *     badges + group children visible.
- *   - **Rail** (`collapsed={true}`): 56px wide, icons only, labels
- *     hidden from sighted users (still announced to screen readers via
- *     `sr-only`). Group children are hidden — clicking the group
- *     header is a no-op visually in rail mode (consumer is expected
- *     to either expand the nav or surface a flyout in a follow-up).
- *
- * **A11y**:
- *   - `<nav aria-label="…">` landmark.
- *   - `aria-current="page"` on the active row.
- *   - Groups expose `aria-expanded` / `aria-controls` and the children
- *     wrapper is `role="region" aria-labelledby="…-header"`.
- *   - Rail-mode tooltips via the native `title` attribute (preserves
- *     hover discoverability when labels are visually hidden).
- *
- * **Re-render contract**:
- *   - Rows are extracted into stable sub-components so a single
- *     `activeId` change re-renders all rows but each does only its
- *     own `useAccessState` lookup; this is the price of per-row RBAC.
- *   - Group expand/collapse re-renders ONLY that group (local state).
- */
-export function LeftNav(props: LeftNavProps) {
-  const {
-    items,
-    activeId,
-    collapsed = false,
-    onCollapseChange,
-    onGroupExpandedChange,
-    brand,
-    footer,
-    width,
-    linkComponent = 'a' as unknown as NonNullable<LeftNavProps['linkComponent']>,
-    ariaLabel = 'Main navigation',
-    sx,
-    slotProps,
-    showCollapseToggle = true,
-  } = props;
-
-  const v = leftNavVariants({ width, collapsed });
-
-  const handleCollapseToggle = useCallback(() => {
-    onCollapseChange?.(!collapsed);
-  }, [collapsed, onCollapseChange]);
-
-  return (
-    <nav
-      aria-label={ariaLabel}
-      className={cn(v.root(), sx, slotProps?.root?.className)}
-    >
-      {(brand || (showCollapseToggle && onCollapseChange)) && (
-        <div className={cn(v.brand(), slotProps?.brand?.className)}>
-          {brand && <div className="flex-1 min-w-0 truncate">{brand}</div>}
-          {showCollapseToggle && onCollapseChange && (
-            <button
-              type="button"
-              onClick={handleCollapseToggle}
-              aria-label={collapsed ? 'Expand navigation' : 'Collapse navigation'}
-              aria-pressed={collapsed}
-              className={cn(
-                v.collapseToggle(),
-                slotProps?.collapseToggle?.className
-              )}
-            >
-              {collapsed ? '»' : '«'}
-            </button>
-          )}
-        </div>
-      )}
-
-      <ul className={cn(v.list(), slotProps?.list?.className)}>
-        {items.map((node) =>
-          isGroup(node) ? (
-            <NavGroupRow
-              key={node.id}
-              group={node}
-              activeId={activeId}
-              collapsed={collapsed}
-              linkComponent={linkComponent}
-              onGroupExpandedChange={onGroupExpandedChange}
-              v={v}
-              slotProps={slotProps}
-            />
-          ) : (
-            <NavItemRow
-              key={node.id}
-              item={node}
-              isActive={activeId === node.id}
-              collapsed={collapsed}
-              linkComponent={linkComponent}
-              v={v}
-              slotProps={slotProps}
-            />
-          )
-        )}
-      </ul>
-
-      {footer && (
-        <div className={cn(v.footer(), slotProps?.footer?.className)}>
-          {footer}
-        </div>
-      )}
-    </nav>
-  );
-}