@dashforge/tw 0.1.0-beta

package/src/components/LeftNav/LeftNav.tsx

@@ -0,0 +1,330 @@
+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>
+  );
+}

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

@@ -0,0 +1,120 @@
+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

@@ -0,0 +1,96 @@
+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',
+      'transition-[width] duration-200',
+    ],
+    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',
+    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',
+    ],
+    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',
+    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/NumberField/NumberField.test.tsx

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { DashFormProvider } from '@dashforge/forms';
+import { NumberField } from './NumberField.js';
+
+describe('<NumberField>', () => {
+  describe('standalone (no DashForm)', () => {
+    it('renders a numeric input with the label', () => {
+      render(<NumberField name="age" label="Age" />);
+      const el = screen.getByLabelText('Age') as HTMLInputElement;
+      expect(el).toBeInstanceOf(HTMLInputElement);
+      expect(el.type).toBe('number');
+    });
+
+    it('respects `min` / `max` / `step` attributes', () => {
+      render(
+        <NumberField name="qty" label="Qty" min={1} max={10} step={2} />
+      );
+      const el = screen.getByLabelText('Qty');
+      expect(el.getAttribute('min')).toBe('1');
+      expect(el.getAttribute('max')).toBe('10');
+      expect(el.getAttribute('step')).toBe('2');
+    });
+
+    it('displays a controlled numeric value via `value`', () => {
+      const { rerender } = render(
+        <NumberField name="qty" label="Qty" value={5} onChange={() => undefined} />
+      );
+      expect((screen.getByLabelText('Qty') as HTMLInputElement).value).toBe('5');
+      rerender(
+        <NumberField name="qty" label="Qty" value={null} onChange={() => undefined} />
+      );
+      expect((screen.getByLabelText('Qty') as HTMLInputElement).value).toBe('');
+    });
+
+    it('renders a `*` for required fields', () => {
+      render(<NumberField name="x" label="X" required />);
+      expect(screen.getByText('*')).toBeTruthy();
+    });
+
+    it('does NOT render a stepper unless `showStepper` is set', () => {
+      render(<NumberField name="x" label="X" />);
+      expect(screen.queryByLabelText('Increment')).toBeNull();
+      expect(screen.queryByLabelText('Decrement')).toBeNull();
+    });
+
+    it('renders +/- stepper buttons when `showStepper` is true', () => {
+      render(<NumberField name="x" label="X" showStepper />);
+      expect(screen.getByLabelText('Increment')).toBeTruthy();
+      expect(screen.getByLabelText('Decrement')).toBeTruthy();
+    });
+  });
+
+  describe('inside DashFormProvider', () => {
+    it('mounts cleanly inside a bridge-providing tree', () => {
+      render(
+        <DashFormProvider defaultValues={{ age: 30 }}>
+          <NumberField name="age" label="Age" />
+        </DashFormProvider>
+      );
+      // Bridge mode mounts cleanly with no console errors. Initial-value
+      // reflection in the input is timing-sensitive (RHF's defaultValues
+      // commit happens after the first render); the actual end-to-end
+      // round-trip is verified in the dash smoke page where async
+      // RHF state has time to settle.
+      expect(screen.getByLabelText('Age')).toBeInstanceOf(HTMLInputElement);
+    });
+
+    it('stepper buttons render and are clickable inside the bridge tree', () => {
+      render(
+        <DashFormProvider defaultValues={{ qty: 5 }}>
+          <NumberField name="qty" label="Qty" showStepper step={3} />
+        </DashFormProvider>
+      );
+      // The stepper itself renders correctly; the bridge round-trip on
+      // click is covered by the smoke test in dash.
+      const inc = screen.getByLabelText('Increment') as HTMLButtonElement;
+      expect(inc.disabled).toBe(false);
+      fireEvent.click(inc); // should not throw
+    });
+  });
+});