@dashforge/tw 1.1.0 → 1.2.0

package/src/components/IconButton/IconButton.tsx

@@ -1,159 +0,0 @@
-import { forwardRef, useContext } from 'react';
-import { Slot } from '@radix-ui/react-slot';
-import { DashFormContext, useEngineVisibility } from '@dashforge/ui-core';
-import { cn } from '../../utils/cn.js';
-import { useAccessState } from '../../hooks/useAccessState.js';
-import { buttonVariants } from '../Button/button.variants.js';
-import { Spinner } from '../Spinner/Spinner.js';
-import type { SpinnerSize } from '../Spinner/spinner.types.js';
-import {
-  ICON_BUTTON_BASE,
-  ICON_BUTTON_SIZE_OVERRIDES,
-} from './iconButton.variants.js';
-import type { IconButtonProps } from './iconButton.types.js';
-
-/**
- * Map IconButton size to Spinner size. Same mapping as Button —
- * Spinner has 5 steps, the parent has 3.
- *
- * @internal
- */
-function iconButtonSizeToSpinnerSize(size: 'sm' | 'md' | 'lg'): SpinnerSize {
-  return size === 'sm' ? 'xs' : size === 'lg' ? 'md' : 'sm';
-}
-
-/**
- * Dashforge TW IconButton — square, icon-only action button.
- *
- * Reuses `buttonVariants` 1:1 (same `variant` / `color` / `size` /
- * `loading` axes) so every `<Button>` style maps to the equivalent
- * `<IconButton>` with zero code duplication. The ONLY additions are:
- *
- *   - `ICON_BUTTON_SIZE_OVERRIDES` — forces `w-N + px-0` so the button
- *     is square at every size token
- *   - `ICON_BUTTON_BASE` — `aspect-square inline-flex items-center
- *     justify-center` for layout
- *
- * Both additions are token-driven (spacing) or layout-primitive
- * (geometry) — no hardcoded hex, no `dark:` variants.
- *
- * **`aria-label` is REQUIRED** at the type level — icon-only buttons
- * are invisible to assistive tech without an explicit accessible
- * name. The TypeScript compiler enforces this rather than relying on
- * runtime warnings.
- *
- * RBAC integration mirrors `<Button>`: `access` with
- * `onUnauthorized: 'hide' | 'disable' | 'readonly'`. No `visibleWhen`
- * (mirror Button — buttons should disable, not hide, on
- * state-driven unavailability; permission-driven hiding is `access`).
- *
- * @example
- * ```tsx
- * import { Trash2 } from 'lucide-react';
- *
- * <IconButton aria-label="Delete row" color="danger" onClick={onDelete}>
- *   <Trash2 size={20} />
- * </IconButton>
- *
- * // Polymorphism via Radix Slot
- * <IconButton asChild aria-label="Open settings" variant="ghost">
- *   <Link to="/settings"><SettingsIcon size={20} /></Link>
- * </IconButton>
- *
- * // RBAC-gated
- * <IconButton
- *   aria-label="Publish article"
- *   variant="solid"
- *   color="primary"
- *   access={{ resource: 'article', action: 'publish', onUnauthorized: 'disable' }}
- * >
- *   <PublishIcon size={20} />
- * </IconButton>
- *
- * // Loading swap
- * <IconButton aria-label="Save" loading={isSaving}>
- *   <SaveIcon size={20} />
- * </IconButton>
- * ```
- */
-export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(
-  function IconButton(props, ref) {
-    const {
-      access,
-      visibleWhen,
-      disabled,
-      variant,
-      color,
-      size = 'md',
-      loading,
-      asChild,
-      sx,
-      className,
-      children,
-      ...rest
-    } = props;
-
-    // Bridge — both hooks called unconditionally (rules-of-hooks).
-    const bridge = useContext(DashFormContext);
-    const isVisible = useEngineVisibility(bridge?.engine, visibleWhen);
-    const accessState = useAccessState(access);
-    if (!isVisible || !accessState.visible) return null;
-
-    // Effective disabled = explicit OR RBAC.disabled OR RBAC.readonly OR loading.
-    // Mirrors `<Button>` exactly — IconButton has no true read-only
-    // state, so RBAC readonly maps to disabled (same as MUI side).
-    const effectiveDisabled =
-      Boolean(disabled) ||
-      accessState.disabled ||
-      accessState.readonly ||
-      Boolean(loading);
-
-    const classes = cn(
-      buttonVariants({ variant, color, size, loading }),
-      ICON_BUTTON_SIZE_OVERRIDES[size],
-      ICON_BUTTON_BASE,
-      sx,
-      className
-    );
-
-    // `aria-busy` while loading — distinguishes "wait for action to
-    // finish" from "you can't do this" in screen-reader announcements.
-    const ariaBusy = loading ? true : undefined;
-
-    if (asChild) {
-      return (
-        <Slot
-          ref={ref}
-          className={classes}
-          data-disabled={effectiveDisabled || undefined}
-          aria-disabled={effectiveDisabled || undefined}
-          aria-busy={ariaBusy}
-        >
-          {children}
-        </Slot>
-      );
-    }
-
-    return (
-      <button
-        ref={ref}
-        type={rest.type ?? 'button'}
-        disabled={effectiveDisabled}
-        aria-busy={ariaBusy}
-        className={classes}
-        {...rest}
-      >
-        {loading ? (
-          <Spinner
-            size={iconButtonSizeToSpinnerSize(size)}
-            thickness="thick"
-            withTrack
-            label=""
-          />
-        ) : (
-          children
-        )}
-      </button>
-    );
-  }
-);

package/src/components/IconButton/iconButton.types.ts

@@ -1,106 +0,0 @@
-import type { ButtonHTMLAttributes, ReactNode } from 'react';
-import type { ClassValue } from 'tailwind-variants';
-import type { Engine } from '@dashforge/ui-core';
-import type { AccessRequirement } from '@dashforge/rbac';
-import type { ButtonVariants } from '../Button/button.variants.js';
-
-/**
- * Props for `<IconButton>`.
- *
- * IconButton is the **icon-only variant of `<Button>`** — it reuses
- * `buttonVariants` 1:1 (same `variant` × `color` × `size` × `loading`
- * compound matrix) and adds:
- *
- *   - Square geometry (width = height = size token, `aspect-square`)
- *   - Zero horizontal padding (no text to pad around)
- *   - **`aria-label` REQUIRED** at the type level — icon-only buttons
- *     are invisible to screen readers without an explicit label, so we
- *     enforce it via TypeScript rather than runtime warning.
- *
- * Notes on excluded props (deliberate parity with `<Button>`):
- *   - **No `slotProps`** — IconButton renders a single DOM element
- *     (`<button>` plus a transient loading swap); `className` + `sx`
- *     cover the override surface fully, matching Button.
- *   - **No `fullWidth`** — meaningless on an icon-sized button.
- *
- * As of 1.1.0 (Sprint 4.4 alignment), IconButton + Button both
- * support `visibleWhen` — see prop docs below.
- *
- * @example
- * ```tsx
- * import { TrashIcon } from 'lucide-react';
- *
- * <IconButton aria-label="Delete row" color="danger" onClick={onDelete}>
- *   <TrashIcon size={20} />
- * </IconButton>
- *
- * // Polymorphism via Radix Slot — wrap a router Link without nesting
- * // a button inside an anchor.
- * <IconButton asChild aria-label="Open settings" variant="ghost">
- *   <Link to="/settings"><SettingsIcon size={20} /></Link>
- * </IconButton>
- *
- * // RBAC-gated
- * <IconButton
- *   aria-label="Publish article"
- *   variant="solid"
- *   color="primary"
- *   access={{ resource: 'article', action: 'publish', onUnauthorized: 'disable' }}
- * >
- *   <PublishIcon size={20} />
- * </IconButton>
- * ```
- */
-export interface IconButtonProps
-  extends Omit<
-      ButtonHTMLAttributes<HTMLButtonElement>,
-      'color' | 'children'
-    >,
-    Pick<ButtonVariants, 'variant' | 'color' | 'size' | 'loading'> {
-  /**
-   * The icon — typically an SVG element from the consumer's icon
-   * library (Lucide / Phosphor / Tabler / inline SVG). A single
-   * `ReactNode` is expected.
-   */
-  children: ReactNode;
-
-  /**
-   * Required at the type level — icon-only buttons MUST have an
-   * accessible name. Pass a short verb phrase describing the action
-   * (e.g. `"Delete row"`, `"Open settings"`, NOT `"Trash icon"`).
-   */
-  'aria-label': string;
-
-  /**
-   * Render-as-child via Radix Slot — the resolved IconButton
-   * className is forwarded to the immediate child element, no
-   * `<button>` DOM is emitted. Useful for router `<Link>`s.
-   * Same contract as `<Button asChild>`.
-   */
-  asChild?: boolean;
-
-  /**
-   * RBAC requirement. When the current subject doesn't satisfy the
-   * requirement, the button is hidden / disabled / read-only per
-   * `onUnauthorized`. Same contract as `<Button access>`.
-   */
-  access?: AccessRequirement;
-
-  /**
-   * Reactive visibility predicate — same contract as `<Button>` and
-   * `<Chip>`. When the predicate returns `false`, the component
-   * renders `null`. Inside a `<DashForm>` it subscribes to engine
-   * state and re-evaluates on every change; outside a form, it's
-   * called with `null` engine (capture external state in closure).
-   *
-   * Added in 1.1.0 (Sprint 4.4 alignment) to keep IconButton in
-   * lockstep with Button.
-   */
-  visibleWhen?: (engine: Engine) => boolean;
-
-  /**
-   * Root-element class shortcut (string or `clsx`-compatible value).
-   * Last-wins via `tailwind-merge` inside `cn()`.
-   */
-  sx?: ClassValue;
-}

package/src/components/IconButton/iconButton.variants.ts

@@ -1,31 +0,0 @@
-import type { ButtonVariants } from '../Button/button.variants.js';
-
-/**
- * IconButton size overrides — applied ON TOP of `buttonVariants(...)`.
- *
- * Button's `size` axis sets `h-X` + `px-Y` (rectangular). For
- * IconButton we need a SQUARE shape, so we:
- *   - zero out the horizontal padding (`px-0`)
- *   - set an explicit width that matches the height (`w-N` mirrors the
- *     `h-N` from Button's size variant)
- *
- * The `aspect-square` utility provides belt-and-braces in the edge
- * case where Tailwind purges the explicit `w-N` (e.g., when the user
- * passes `size` dynamically and the JIT can't statically see all
- * combinations).
- *
- * Token propagation: `w-N` resolves to `var(--df-tw-spacing-N)`
- * through `dashforgePreset()`, identical to how `h-N` works for
- * Button. `patchTheme({ spacing: { 10: '2.75rem' } })` patches both
- * Button height and IconButton size in lockstep.
- */
-type IconButtonSize = NonNullable<ButtonVariants['size']>;
-
-export const ICON_BUTTON_SIZE_OVERRIDES: Record<IconButtonSize, string> = {
-  sm: 'w-8 px-0',
-  md: 'w-10 px-0',
-  lg: 'w-12 px-0',
-};
-
-/** Always-applied layout primitives — not token-driven (geometric CSS). */
-export const ICON_BUTTON_BASE = 'aspect-square inline-flex items-center justify-center';

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

@@ -1,172 +0,0 @@
-// @vitest-environment jsdom
-/**
- * Performance + re-render budget tests for `<LeftNav>`.
- *
- * Layout sidebar is the most expensive layout primitive — it can
- * easily host 50+ rows, each with RBAC checks. Guardrails:
- *
- *  1. Mount cost bounded for realistic + worst-case row counts.
- *  2. `activeId` change only re-renders the rows that need re-styling
- *     (today: all rows re-render because we don't `React.memo` them,
- *     but the total time is still bounded).
- *  3. Group expand/collapse only re-renders THAT group.
- *  4. Toggling `collapsed` does not allocate per-item maps.
- */
-import * as React from 'react';
-import { describe, it, expect, 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());
-
-function makeFlatNav(n: number): LeftNavNode[] {
-  return Array.from({ length: n }, (_, i) => ({
-    id: `r${i}`,
-    label: `Row ${i}`,
-    href: `/r${i}`,
-  }));
-}
-
-function makeNestedNav(groups: number, perGroup: number): LeftNavNode[] {
-  return Array.from({ length: groups }, (_, g) => ({
-    kind: 'group' as const,
-    id: `g${g}`,
-    label: `Group ${g}`,
-    children: Array.from({ length: perGroup }, (_, i) => ({
-      id: `g${g}-r${i}`,
-      label: `Row ${i}`,
-      href: `/g${g}/r${i}`,
-    })),
-  }));
-}
-
-function withRenderCounter<P>(
-  Component: React.ComponentType<P>,
-  counterRef: { count: number }
-): React.FC<P> {
-  return function Counted(props: P) {
-    counterRef.count++;
-    return <Component {...(props as P & object)} />;
-  };
-}
-
-describe('<LeftNav> performance', () => {
-  it('mounts a realistic 30-row flat nav in under 50ms', () => {
-    const items = makeFlatNav(30);
-    const t0 = performance.now();
-    render(<LeftNav items={items} />);
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(50);
-  });
-
-  it('mounts a 300-row flat nav in under 250ms', () => {
-    const items = makeFlatNav(300);
-    const t0 = performance.now();
-    render(<LeftNav items={items} />);
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(250);
-  });
-
-  it('mounts a 10×10 nested nav (100 leaf rows) in under 150ms', () => {
-    const items = makeNestedNav(10, 10);
-    const t0 = performance.now();
-    render(<LeftNav items={items} />);
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(150);
-  });
-
-  it('toggles `collapsed` in under 100ms (30 rows)', () => {
-    const items = makeFlatNav(30);
-    const { rerender } = render(<LeftNav items={items} />);
-    const t0 = performance.now();
-    rerender(<LeftNav items={items} collapsed />);
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(100);
-  });
-});
-
-describe('<LeftNav> re-render budget', () => {
-  it('renders at most 2 times on mount (top-level wrapper)', () => {
-    const counter = { count: 0 };
-    const Counted = withRenderCounter(LeftNav, counter);
-    render(<Counted items={makeFlatNav(10)} />);
-    expect(counter.count).toBeLessThanOrEqual(2);
-  });
-
-  it('does NOT re-render the wrapper when a group expands locally', () => {
-    // Group state is local — flipping it must not bubble a re-render
-    // up to the LeftNav wrapper.
-    const counter = { count: 0 };
-    const Counted = withRenderCounter(LeftNav, counter);
-    render(<Counted items={makeNestedNav(2, 3)} />);
-    const baseline = counter.count;
-    const header = screen.getByRole('button', { name: /Group 0/ });
-    fireEvent.click(header);
-    fireEvent.click(header);
-    fireEvent.click(header);
-    expect(counter.count).toBe(baseline);
-  });
-
-  it('does NOT re-render an unrelated sibling when collapsing the nav', () => {
-    const sibCount = { count: 0 };
-    const Sibling = () => {
-      sibCount.count++;
-      return <div data-testid="sib" />;
-    };
-    const Shell = ({ collapsed }: { collapsed: boolean }) => (
-      <div>
-        <LeftNav items={makeFlatNav(20)} collapsed={collapsed} />
-        <Sibling />
-      </div>
-    );
-    const { rerender } = render(<Shell collapsed={false} />);
-    const baseline = sibCount.count;
-    rerender(<Shell collapsed={true} />);
-    // 1 parent re-render → 1 sibling re-render. Allow 1 extra for
-    // React strict-mode or commit-phase double-invocation in dev.
-    expect(sibCount.count - baseline).toBeLessThanOrEqual(2);
-  });
-
-  it('activeId change updates aria-current without throwing', () => {
-    const items = makeFlatNav(5);
-    const { rerender } = render(
-      <LeftNav items={items} activeId="r0" />
-    );
-    expect(
-      screen.getByRole('link', { name: 'Row 0' }).getAttribute('aria-current')
-    ).toBe('page');
-    rerender(<LeftNav items={items} activeId="r3" />);
-    expect(
-      screen.getByRole('link', { name: 'Row 0' }).getAttribute('aria-current')
-    ).toBeNull();
-    expect(
-      screen.getByRole('link', { name: 'Row 3' }).getAttribute('aria-current')
-    ).toBe('page');
-  });
-
-  it('group expanded state is preserved across parent re-renders', () => {
-    // Local state inside `<NavGroupRow>` must survive a parent
-    // re-render. Without this, every `activeId` change would reset
-    // every group to its `defaultExpanded`, which would be terrible UX.
-    const items = makeNestedNav(2, 3);
-    const { container, rerender } = render(
-      <LeftNav items={items} activeId="g0-r0" />
-    );
-    // Collapse Group 0 — Group 0's first child href becomes invisible.
-    fireEvent.click(screen.getByRole('button', { name: /Group 0/ }));
-    const g0Child = () =>
-      container.querySelector('a[href="/g0/r0"]');
-    expect(g0Child()).toBeNull();
-    // Now change activeId to a row in Group 1.
-    rerender(<LeftNav items={items} activeId="g1-r0" />);
-    // Group 0 must STAY collapsed (local state survived parent re-render).
-    expect(g0Child()).toBeNull();
-  });
-});