@dashforge/tw 1.0.0 → 1.1.0

package/src/components/Card/Card.test.tsx

@@ -0,0 +1,291 @@
+// @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 { Card, CardContent, CardActionArea } from './Card.js';
+
+void React;
+afterEach(() => cleanup());
+
+/**
+ * Unit tests for the Card family. Covers:
+ *   - <Card>: thin Box wrapper with restricted variant axis, inherits
+ *     access + visibleWhen from Box (verified at integration level)
+ *   - <CardContent>: padded inner box with default p=4 and override
+ *   - <CardActionArea>: clickable wrapper (button or asChild), focus
+ *     ring, selected aria-pressed, disabled state, access RBAC,
+ *     visibleWhen predicate
+ */
+
+const ADMIN_POLICY: RbacPolicy = {
+  roles: [
+    {
+      name: 'admin',
+      permissions: [{ resource: '*', action: '*', effect: 'allow' }],
+    },
+  ],
+};
+const NO_ACCESS_POLICY: RbacPolicy = {
+  roles: [{ name: 'guest', permissions: [] }],
+};
+const adminSubject: Subject = { id: 'a', roles: ['admin'] };
+const guestSubject: Subject = { id: 'g', roles: ['guest'] };
+
+describe('<Card>', () => {
+  describe('rendering', () => {
+    it('renders children', () => {
+      render(<Card data-testid="card">hello</Card>);
+      expect(screen.getByTestId('card')).toBeTruthy();
+      expect(screen.getByText('hello')).toBeTruthy();
+    });
+
+    it('applies default outlined variant (border class from Box)', () => {
+      const { container } = render(<Card>x</Card>);
+      const root = container.firstElementChild!;
+      expect(root.className).toContain('border');
+    });
+
+    it('applies default rounded="lg"', () => {
+      const { container } = render(<Card>x</Card>);
+      const root = container.firstElementChild!;
+      expect(root.className).toContain('rounded-lg');
+    });
+
+    it('overrides default variant to elevated', () => {
+      const { container } = render(<Card variant="elevated">x</Card>);
+      const root = container.firstElementChild!;
+      // Elevated variant uses bg-white in light mode
+      expect(root.className).toContain('bg-white');
+    });
+
+    it('respects elevation override', () => {
+      const { container } = render(<Card elevation={3}>x</Card>);
+      const root = container.firstElementChild!;
+      expect(root.className).toContain('shadow-md');
+    });
+
+    it('inherits visibleWhen from Box', () => {
+      const { container } = render(
+        <Card visibleWhen={() => false}>hidden</Card>
+      );
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('inherits access from Box (hide mode)', () => {
+      const { container } = render(
+        <RbacProvider policy={NO_ACCESS_POLICY} subject={guestSubject}>
+          <Card
+            access={{
+              resource: 'admin',
+              action: 'read',
+              onUnauthorized: 'hide',
+            }}
+          >
+            admin-only
+          </Card>
+        </RbacProvider>
+      );
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('inherits access from Box (visible for authorized subject)', () => {
+      const { container } = render(
+        <RbacProvider policy={ADMIN_POLICY} subject={adminSubject}>
+          <Card
+            access={{
+              resource: 'admin',
+              action: 'read',
+              onUnauthorized: 'hide',
+            }}
+          >
+            shown
+          </Card>
+        </RbacProvider>
+      );
+      expect(container.firstChild).toBeTruthy();
+      expect(screen.getByText('shown')).toBeTruthy();
+    });
+  });
+});
+
+describe('<CardContent>', () => {
+  it('renders children inside a Box with default p=4', () => {
+    const { container } = render(
+      <CardContent>content</CardContent>
+    );
+    const root = container.firstElementChild!;
+    expect(root.className).toContain('p-4');
+    expect(screen.getByText('content')).toBeTruthy();
+  });
+
+  it('respects custom p value', () => {
+    const { container } = render(
+      <CardContent p={6}>spacious</CardContent>
+    );
+    const root = container.firstElementChild!;
+    expect(root.className).toContain('p-6');
+  });
+
+  it('respects p={0} for zero padding', () => {
+    const { container } = render(
+      <CardContent p={0}>flush</CardContent>
+    );
+    const root = container.firstElementChild!;
+    expect(root.className).toContain('p-0');
+  });
+
+  it('appends className', () => {
+    const { container } = render(
+      <CardContent className="my-custom-content">x</CardContent>
+    );
+    const root = container.firstElementChild!;
+    expect(root.className).toContain('my-custom-content');
+  });
+});
+
+describe('<CardActionArea>', () => {
+  describe('rendering', () => {
+    it('renders as <button> by default', () => {
+      render(<CardActionArea>click me</CardActionArea>);
+      expect(screen.getByRole('button', { name: /click me/i })).toBeTruthy();
+    });
+
+    it('renders as the immediate child when asChild=true', () => {
+      const { container } = render(
+        <CardActionArea asChild>
+          <a href="/x" data-testid="anchor-child">link content</a>
+        </CardActionArea>
+      );
+      const anchor = container.querySelector('a[data-testid="anchor-child"]');
+      expect(anchor).toBeTruthy();
+      expect(container.querySelector('button')).toBeNull();
+    });
+
+    it('applies base layout (block w-full)', () => {
+      const { container } = render(<CardActionArea>x</CardActionArea>);
+      const root = container.firstElementChild!;
+      expect(root.className).toContain('block');
+      expect(root.className).toContain('w-full');
+    });
+  });
+
+  describe('selected state', () => {
+    it('applies aria-pressed=true when selected', () => {
+      render(<CardActionArea selected>x</CardActionArea>);
+      expect(screen.getByRole('button').getAttribute('aria-pressed')).toBe('true');
+    });
+
+    it('does NOT set aria-pressed when not selected', () => {
+      render(<CardActionArea>x</CardActionArea>);
+      expect(screen.getByRole('button').getAttribute('aria-pressed')).toBeNull();
+    });
+
+    it('applies primary ring class when selected', () => {
+      const { container } = render(<CardActionArea selected>x</CardActionArea>);
+      const btn = container.firstElementChild!;
+      expect(btn.className).toContain('ring-primary-500');
+    });
+  });
+
+  describe('disabled state', () => {
+    it('respects explicit disabled prop', () => {
+      render(<CardActionArea disabled>x</CardActionArea>);
+      const btn = screen.getByRole('button') as HTMLButtonElement;
+      expect(btn.disabled).toBe(true);
+    });
+
+    it('does NOT fire onClick when disabled', () => {
+      const onClick = vi.fn();
+      render(<CardActionArea disabled onClick={onClick}>x</CardActionArea>);
+      fireEvent.click(screen.getByRole('button'));
+      expect(onClick).not.toHaveBeenCalled();
+    });
+
+    it('applies opacity-50 + cursor-not-allowed when disabled', () => {
+      const { container } = render(<CardActionArea disabled>x</CardActionArea>);
+      const btn = container.firstElementChild!;
+      expect(btn.className).toContain('opacity-50');
+    });
+  });
+
+  describe('click handler', () => {
+    it('fires onClick when clicked', () => {
+      const onClick = vi.fn();
+      render(<CardActionArea onClick={onClick}>x</CardActionArea>);
+      fireEvent.click(screen.getByRole('button'));
+      expect(onClick).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('access RBAC', () => {
+    it('hides when access.onUnauthorized=hide and subject lacks permission', () => {
+      const { container } = render(
+        <RbacProvider policy={NO_ACCESS_POLICY} subject={guestSubject}>
+          <CardActionArea
+            access={{
+              resource: 'admin',
+              action: 'read',
+              onUnauthorized: 'hide',
+            }}
+          >
+            admin-cta
+          </CardActionArea>
+        </RbacProvider>
+      );
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('disables when access.onUnauthorized=disable', () => {
+      render(
+        <RbacProvider policy={NO_ACCESS_POLICY} subject={guestSubject}>
+          <CardActionArea
+            access={{
+              resource: 'admin',
+              action: 'read',
+              onUnauthorized: 'disable',
+            }}
+          >
+            disable-cta
+          </CardActionArea>
+        </RbacProvider>
+      );
+      const btn = screen.getByRole('button') as HTMLButtonElement;
+      expect(btn.disabled).toBe(true);
+    });
+
+    it('renders normally for authorized subject', () => {
+      render(
+        <RbacProvider policy={ADMIN_POLICY} subject={adminSubject}>
+          <CardActionArea
+            access={{
+              resource: 'admin',
+              action: 'read',
+              onUnauthorized: 'hide',
+            }}
+          >
+            admin-cta
+          </CardActionArea>
+        </RbacProvider>
+      );
+      expect(screen.getByText('admin-cta')).toBeTruthy();
+    });
+  });
+
+  describe('visibleWhen', () => {
+    it('renders when predicate returns true', () => {
+      render(
+        <CardActionArea visibleWhen={() => true}>shown</CardActionArea>
+      );
+      expect(screen.getByText('shown')).toBeTruthy();
+    });
+
+    it('returns null when predicate returns false', () => {
+      const { container } = render(
+        <CardActionArea visibleWhen={() => false}>hidden</CardActionArea>
+      );
+      expect(container.firstChild).toBeNull();
+    });
+  });
+});

package/src/components/Card/Card.tsx

@@ -0,0 +1,241 @@
+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 { Box } from '../Box/Box.js';
+import type {
+  CardActionAreaProps,
+  CardContentProps,
+  CardProps,
+} from './card.types.js';
+
+/**
+ * `<Card>` — opinionated surface preset over `<Box>`.
+ *
+ * Thin alias that pre-fills card-shaped Box defaults (`outlined`,
+ * `rounded='lg'`, `elevation=1`, no padding). Reads as `<Card>` in
+ * consumer code while reusing every Box affordance: surface variants,
+ * 7 intent colors, spacing scale, polymorphism, and the bridge
+ * integration (`access` + `visibleWhen`) retrofitted to Box in 1.1.0.
+ *
+ * Restricted variant axis: only `'outlined' | 'elevated' | 'plain'`.
+ * `'soft'` and `'solid'` are deliberately excluded — they belong to
+ * Box (as `<Alert>`-shaped callouts) and to banners, not to cards.
+ *
+ * @example
+ * ```tsx
+ * // Most common — outlined card with content padding via CardContent
+ * <Card>
+ *   <CardContent>
+ *     <Typography variant="h3">Title</Typography>
+ *     <Typography variant="body">Body</Typography>
+ *   </CardContent>
+ * </Card>
+ *
+ * // Elevated, clickable, gated by RBAC (inherits access from Box)
+ * <Card
+ *   variant="elevated"
+ *   elevation={2}
+ *   access={{ resource: 'billing', action: 'read', onUnauthorized: 'hide' }}
+ * >
+ *   <CardActionArea onClick={openBilling}>
+ *     <CardContent>
+ *       <Typography variant="h3">Revenue</Typography>
+ *     </CardContent>
+ *   </CardActionArea>
+ * </Card>
+ * ```
+ */
+export const Card = forwardRef<HTMLElement, CardProps>(function Card(
+  props,
+  ref
+) {
+  const {
+    variant = 'outlined',
+    rounded = 'lg',
+    elevation = 1,
+    p = 0,
+    children,
+    ...rest
+  } = props;
+
+  return (
+    <Box
+      ref={ref}
+      variant={variant}
+      rounded={rounded}
+      elevation={elevation}
+      p={p}
+      {...rest}
+    >
+      {children}
+    </Box>
+  );
+});
+
+Card.displayName = 'Card';
+
+/**
+ * `<CardContent>` — padded inner section of a Card.
+ *
+ * Semantic alias for an inner `<Box p={4}>`. The default padding step
+ * (4) maps to `--df-tw-spacing-4` (1rem) via the dashforgePreset,
+ * matching common card-content paddings across MUI / shadcn / Chakra.
+ * Override `p` to dial up/down per the spacing token scale.
+ *
+ * @example
+ * ```tsx
+ * <Card>
+ *   <CardContent p={6}>  {/* bigger inner padding *}/}
+ *     <Typography variant="h3">Spacious card</Typography>
+ *   </CardContent>
+ * </Card>
+ * ```
+ */
+export function CardContent({
+  p = 4,
+  children,
+  className,
+  sx,
+}: CardContentProps) {
+  return (
+    <Box p={p} sx={cn(className, sx as string | undefined)}>
+      {children}
+    </Box>
+  );
+}
+
+CardContent.displayName = 'CardContent';
+
+/**
+ * `<CardActionArea>` — clickable wrapper for Card content.
+ *
+ * Adds focus ring + hover tint + Radix Slot polymorphism. Renders as
+ * `<button type="button">` by default, or as the immediate child via
+ * `asChild` (typical pattern: wrap a router `<Link>`).
+ *
+ * Bridge integration is local — CardActionArea is an action trigger
+ * (not a surface), so it carries `access` + `visibleWhen` directly
+ * (rather than relying on the wrapping Card's props). This lets the
+ * consumer differentiate "the card is visible but not clickable" from
+ * "the card is not visible at all".
+ *
+ * @example
+ * ```tsx
+ * // Card-as-CTA
+ * <Card>
+ *   <CardActionArea onClick={navigate}>
+ *     <CardContent>
+ *       <Typography variant="h3">Open dashboard</Typography>
+ *       <Typography variant="body">Hover to see the focus ring.</Typography>
+ *     </CardContent>
+ *   </CardActionArea>
+ * </Card>
+ *
+ * // Polymorphic — wrap a router Link
+ * <Card>
+ *   <CardActionArea asChild>
+ *     <Link to="/billing">
+ *       <CardContent>
+ *         <Typography variant="h3">Billing</Typography>
+ *       </CardContent>
+ *     </Link>
+ *   </CardActionArea>
+ * </Card>
+ *
+ * // Selectable card (filter / option pattern)
+ * <CardActionArea
+ *   selected={selected === 'monthly'}
+ *   onClick={() => setSelected('monthly')}
+ * >
+ *   <CardContent>Monthly plan</CardContent>
+ * </CardActionArea>
+ * ```
+ */
+export const CardActionArea = forwardRef<HTMLButtonElement, CardActionAreaProps>(
+  function CardActionArea(props, ref) {
+    const {
+      children,
+      asChild,
+      selected,
+      access,
+      visibleWhen,
+      disabled,
+      sx,
+      className,
+      onClick,
+      ...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;
+
+    const isDisabled =
+      Boolean(disabled) || accessState.disabled || accessState.readonly;
+
+    // The action area must SPAN the parent Card so the entire surface
+    // is clickable. Includes focus ring, hover, and a subtle pressed
+    // tint via `data-pressed`. Token-driven via dashforgePreset.
+    const classes = cn(
+      'block w-full text-left',
+      'outline-none rounded-[inherit]',
+      'transition-colors',
+      // Hover — gentle bg tint on top of the card surface. Uses
+      // currentColor with 5% alpha so it composes with any Card
+      // variant/color without hardcoding.
+      'hover:bg-current/5',
+      // Focus ring — keyboard-navigable, primary tone, inset slightly
+      // so it traces the card's inherited radius.
+      'focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:ring-offset-1',
+      // Selected — adds a primary tone ring + soft tint so the card
+      // visually reads as "active option" without changing the parent
+      // Card's variant.
+      selected && 'ring-2 ring-primary-500 ring-offset-1 bg-primary-50/60 dark:bg-primary-950/40',
+      // Disabled — dims content and suppresses clicks.
+      isDisabled && 'opacity-50 cursor-not-allowed pointer-events-none',
+      sx,
+      className
+    );
+
+    const handleClick: React.MouseEventHandler<HTMLButtonElement> = (e) => {
+      if (isDisabled) return;
+      onClick?.(e);
+    };
+
+    if (asChild) {
+      return (
+        <Slot
+          ref={ref}
+          className={classes}
+          data-disabled={isDisabled || undefined}
+          aria-disabled={isDisabled || undefined}
+          aria-pressed={selected ? true : undefined}
+          onClick={handleClick}
+        >
+          {children}
+        </Slot>
+      );
+    }
+
+    return (
+      <button
+        ref={ref}
+        type="button"
+        className={classes}
+        disabled={isDisabled}
+        aria-pressed={selected ? true : undefined}
+        onClick={handleClick}
+        {...rest}
+      >
+        {children}
+      </button>
+    );
+  }
+);
+
+CardActionArea.displayName = 'CardActionArea';

package/src/components/Card/card.types.ts

@@ -0,0 +1,132 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { ClassValue } from 'tailwind-variants';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { BoxProps } from '../Box/box.types.js';
+
+/**
+ * `<Card>` — opinionated surface preset over `<Box>`.
+ *
+ * Architectural note: `<Box>` already implements the full surface
+ * vocabulary (variant × color, elevation, rounded, spacing). `<Card>`
+ * exists for **two reasons** on top of Box:
+ *
+ *   1. **MUI mental model** — devs migrating from `@mui/material/Card`
+ *      reach for `<Card>` reflexively. Having the component (as a
+ *      thin Box alias with card-shaped defaults) removes adoption
+ *      friction without duplicating the surface system.
+ *   2. **Restricted variant axis** — Card excludes `'soft'` and
+ *      `'solid'` from Box's 5 variants. A "solid card" is semantically
+ *      a banner; a "soft card" is a callout (use `<Alert>`). Restricting
+ *      to `'outlined' | 'elevated' | 'plain'` is opinionated typing
+ *      that catches misuse at compile time.
+ *
+ * Card inherits `access` + `visibleWhen` from Box (Sprint 4.4 surface
+ * alignment) automatically — no per-component wiring needed.
+ *
+ * Defaults set by Card (override at the call site):
+ *   - `variant='outlined'`  → soft border + bg tint (most card-like)
+ *   - `rounded='lg'`        → 8px radius
+ *   - `elevation={1}`       → faint shadow for visual weight
+ *   - `p={0}`               → no inner padding (use `<CardContent>`)
+ */
+export interface CardProps
+  extends Omit<BoxProps, 'variant'> {
+  /**
+   * Restricted variant — only the three card-appropriate Box variants.
+   * - `'outlined'` (default) — bordered surface with subtle tint.
+   * - `'elevated'` — surface with shadow, no border.
+   * - `'plain'` — bare surface (background + radius), no border, no
+   *   shadow. Use when wrapping content that already provides chrome.
+   *
+   * @default 'outlined'
+   */
+  variant?: 'outlined' | 'elevated' | 'plain';
+}
+
+/**
+ * `<CardContent>` — padded inner section of a Card.
+ *
+ * A semantic alias for `<Box p={4}>` (or the equivalent spacing
+ * step). Reads better in starter-kit code than the equivalent Box
+ * call — the consumer expresses "this is the content area of the
+ * card" rather than "this is a box with padding-4 inside a card".
+ *
+ * No surface props — CardContent inherits its background from the
+ * parent Card. The only configurable axis is the padding step.
+ */
+export interface CardContentProps {
+  /**
+   * Inner padding token step (same scale as `<Box p>`).
+   * @default 4
+   */
+  p?: BoxProps['p'];
+
+  /** Content of the section. */
+  children: ReactNode;
+
+  /** Standard React `className` — appended to the root via `cn()`. */
+  className?: string;
+
+  /** Root-element class shortcut (string or clsx-compatible value). */
+  sx?: ClassValue;
+}
+
+/**
+ * `<CardActionArea>` — clickable wrapper inside (or around) a Card.
+ *
+ * The single value-add over a raw `<Box>` wrapper: focus ring +
+ * hover state + Radix Slot polymorphism so the wrapper can become a
+ * router `<Link>` without nesting `<a>` inside `<button>` (a11y
+ * violation).
+ *
+ * Use cases:
+ *   - "Card-as-CTA" patterns where the whole card surface should be
+ *     clickable (e.g. "Open dashboard" tile)
+ *   - Card-shaped router links in dashboards / navigation grids
+ *   - Selectable cards in galleries (with `selected` + `onClick`)
+ *
+ * Always renders as `<button>` (or the asChild element) — focusable,
+ * keyboard-accessible by default. `aria-pressed` when `selected=true`
+ * for the toggle pattern (filter card / option card).
+ */
+export interface CardActionAreaProps
+  extends Omit<ComponentPropsWithoutRef<'button'>, 'className' | 'color'> {
+  /** The card body / content to wrap. */
+  children: ReactNode;
+
+  /**
+   * Render-as-child via Radix Slot. The CardActionArea styles paint
+   * onto the immediate child element (typically a router `<Link>`).
+   * No `<button>` DOM emitted.
+   */
+  asChild?: boolean;
+
+  /**
+   * Selected state — for toggle / option-card patterns. Adds
+   * `aria-pressed="true"` and a primary-toned focus ring even when
+   * not focused.
+   */
+  selected?: boolean;
+
+  /**
+   * RBAC requirement — controls clickability via the centralized
+   * `@dashforge/rbac` policy engine.
+   *   - `onUnauthorized: 'hide'`     → action area does not render
+   *   - `onUnauthorized: 'disable'`  → clicks suppressed + dimmed
+   *   - `onUnauthorized: 'readonly'` → mapped to disabled
+   */
+  access?: AccessRequirement;
+
+  /**
+   * Engine-reactive visibility predicate — Sprint 4.4 alignment.
+   * When the predicate returns `false`, the action area renders `null`.
+   */
+  visibleWhen?: (engine: Engine) => boolean;
+
+  /** Root-element class shortcut. */
+  sx?: ClassValue;
+
+  /** Standard React className — appended via `cn()`. */
+  className?: string;
+}