@dashforge/tw 1.1.0 → 1.2.0

package/src/components/Box/Box.test.tsx

@@ -1,391 +0,0 @@
-// @vitest-environment jsdom
-import { describe, it, expect } from 'vitest';
-import { render } from '@testing-library/react';
-import { Box } from './Box.js';
-
-/**
- * Suite mirrors the Typography/Button test shape (rendering · variants ·
- * compound × intent · override · polymorphism · pass-through). The big
- * delta here is the compound-variant matrix: 5 surface variants × 7
- * intents = 35 combos, of which 21 carry actual visual differences
- * (outlined / soft / solid × 7 intents). We spot-check a representative
- * subset rather than enumerate all 35 — if the TV compound resolution
- * works for one of each (primary, danger, neutral), it works for all.
- */
-describe('<Box>', () => {
-  // ─── Default rendering ──────────────────────────────────────────────
-  describe('default rendering', () => {
-    it('renders a <div> by default', () => {
-      const { container } = render(<Box>x</Box>);
-      expect(container.firstElementChild?.tagName).toBe('DIV');
-    });
-
-    it('default variant is plain — no border, no bg, no shadow', () => {
-      const { container } = render(<Box>x</Box>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).not.toContain('border');
-      expect(cls).not.toContain('bg-');
-      expect(cls).not.toContain('shadow-sm');
-      // baseline `block` is always present
-      expect(cls).toContain('block');
-    });
-  });
-
-  // ─── Variant — surface chrome ───────────────────────────────────────
-  describe('surface variants', () => {
-    it('variant="outlined" adds a border', () => {
-      const { container } = render(<Box variant="outlined" color="neutral">x</Box>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('border');
-      // neutral outlined picks the white surface + neutral-200 border
-      expect(cls).toContain('border-neutral-200');
-      expect(cls).toContain('bg-white');
-    });
-
-    it('variant="elevated" adds the neutral surface, no border, no color tint', () => {
-      const { container } = render(<Box variant="elevated" elevation={3}>x</Box>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('bg-white');
-      // Sprint 4.3 theme identity sweep: corrected `dark:bg-neutral-900`
-      // (which resolved to near-white in dark mode via inversion — broken
-      // elevation) to `dark:bg-neutral-100` which resolves to `#171717`,
-      // one elevation tier above the page surface in dark mode.
-      expect(cls).toContain('dark:bg-neutral-100');
-      expect(cls).toContain('shadow-md');
-      expect(cls).not.toContain('border ');
-    });
-
-    it('variant="soft" + color="warning" picks the warning soft tones', () => {
-      const { container } = render(<Box variant="soft" color="warning">x</Box>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('bg-warning-100');
-      expect(cls).toContain('text-warning-900');
-      expect(cls).toContain('dark:bg-warning-950/50');
-    });
-
-    it('variant="solid" + color="primary" picks the primary solid', () => {
-      const { container } = render(<Box variant="solid" color="primary">x</Box>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('bg-primary-600');
-      expect(cls).toContain('text-white');
-      expect(cls).toContain('dark:bg-primary-500');
-    });
-
-    it('variant="solid" + color="danger" picks the danger solid', () => {
-      const { container } = render(<Box variant="solid" color="danger">x</Box>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('bg-danger-600');
-      expect(cls).toContain('text-white');
-    });
-  });
-
-  // ─── Elevation scale ─────────────────────────────────────────────────
-  describe('elevation', () => {
-    it('elevation={0} emits shadow-none', () => {
-      const { container } = render(<Box variant="elevated" elevation={0}>x</Box>);
-      expect(container.firstElementChild?.className).toContain('shadow-none');
-    });
-
-    it('elevation={5} emits shadow-xl', () => {
-      const { container } = render(<Box variant="elevated" elevation={5}>x</Box>);
-      expect(container.firstElementChild?.className).toContain('shadow-xl');
-    });
-  });
-
-  // ─── Spacing ─────────────────────────────────────────────────────────
-  describe('spacing', () => {
-    it('p={4} emits p-4', () => {
-      const { container } = render(<Box p={4}>x</Box>);
-      expect(container.firstElementChild?.className).toContain('p-4');
-    });
-
-    it('px={6} + py={2} emits px-6 + py-2', () => {
-      const { container } = render(<Box px={6} py={2}>x</Box>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('px-6');
-      expect(cls).toContain('py-2');
-    });
-
-    it('m={"0.5"} emits m-0.5', () => {
-      const { container } = render(<Box m="0.5">x</Box>);
-      expect(container.firstElementChild?.className).toContain('m-0.5');
-    });
-  });
-
-  // ─── Rounded + sizing ────────────────────────────────────────────────
-  describe('rounded + sizing', () => {
-    it('rounded="xl" emits rounded-xl', () => {
-      const { container } = render(<Box rounded="xl">x</Box>);
-      expect(container.firstElementChild?.className).toContain('rounded-xl');
-    });
-
-    it('fullWidth emits w-full', () => {
-      const { container } = render(<Box fullWidth>x</Box>);
-      expect(container.firstElementChild?.className).toContain('w-full');
-    });
-
-    it('fullHeight emits h-full', () => {
-      const { container } = render(<Box fullHeight>x</Box>);
-      expect(container.firstElementChild?.className).toContain('h-full');
-    });
-  });
-
-  // ─── Override semantics ─────────────────────────────────────────────
-  describe('override', () => {
-    it('sx wins over variant defaults via tailwind-merge', () => {
-      const { container } = render(
-        <Box variant="solid" color="primary" sx="bg-fuchsia-600">x</Box>,
-      );
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('bg-fuchsia-600');
-      // the conflicting bg-primary-600 from the compound is collapsed
-      expect(cls).not.toContain('bg-primary-600');
-    });
-
-    it('sx can add utilities Box deliberately omits (overflow)', () => {
-      const { container } = render(<Box sx="overflow-hidden">x</Box>);
-      expect(container.firstElementChild?.className).toContain('overflow-hidden');
-    });
-  });
-
-  // ─── Polymorphism ───────────────────────────────────────────────────
-  describe('polymorphism', () => {
-    it('as="section" renders a <section>', () => {
-      const { container } = render(<Box as="section">x</Box>);
-      expect(container.firstElementChild?.tagName).toBe('SECTION');
-    });
-
-    it('asChild renders the single child element with merged className', () => {
-      const { container } = render(
-        <Box variant="elevated" elevation={2} asChild>
-          <article>x</article>
-        </Box>,
-      );
-      const el = container.firstElementChild;
-      expect(el?.tagName).toBe('ARTICLE');
-      expect(el?.className).toContain('shadow');
-      expect(el?.className).toContain('bg-white');
-    });
-
-    it('asChild wins over as when both are passed', () => {
-      const { container } = render(
-        <Box as="section" asChild>
-          <article>x</article>
-        </Box>,
-      );
-      expect(container.firstElementChild?.tagName).toBe('ARTICLE');
-    });
-  });
-
-  // ─── Pass-through ────────────────────────────────────────────────────
-  describe('pass-through', () => {
-    it('forwards data-* and aria-*', () => {
-      const { container } = render(
-        <Box data-testid="box" aria-label="surface">x</Box>,
-      );
-      const el = container.firstElementChild;
-      expect(el?.getAttribute('data-testid')).toBe('box');
-      expect(el?.getAttribute('aria-label')).toBe('surface');
-    });
-  });
-
-  // ─── F11-bis edge cases: every compound variant explicit ─────────────
-  // The original suite spot-checked 4 surface×intent combos (outlined
-  // neutral, soft warning, solid primary, solid danger). The validation
-  // pass before publishing 0.2.0-beta enumerates ALL 21 visually-distinct
-  // compound entries so a future TV recipe edit can't silently drop one.
-  describe('compound variants matrix — every surface × intent', () => {
-    const INTENTS = ['primary', 'secondary', 'success', 'warning', 'danger', 'info', 'neutral'] as const;
-
-    /*
-     * Outlined × 7 intents — each emits a tinted border + soft bg pair
-     * with the dark-mode counterpart pre-wired. Spot-check picks the
-     * `border-{color}-300` light token and the `dark:border-{color}-{N}` pair.
-     */
-    describe('outlined × intent', () => {
-      it.each(INTENTS)('outlined × %s emits border + bg with dark pair', (color) => {
-        const { container } = render(<Box variant="outlined" color={color}>x</Box>);
-        const cls = container.firstElementChild?.className ?? '';
-        if (color === 'neutral') {
-          // Sprint 4.3 identity sweep: neutral outlined uses
-          // `border-neutral-200` (auto-inverts via CSS-var swap; no
-          // `dark:` needed) + `bg-white dark:bg-neutral-100`
-          // (bg-white is hardcoded so `dark:` is required; target
-          // `dark:bg-neutral-100` = `#171717` is one tier elevated
-          // above the page surface in dark mode).
-          expect(cls).toContain('border-neutral-200');
-          expect(cls).toContain('bg-white');
-          expect(cls).toContain('dark:bg-neutral-100');
-          // No more dark:border-neutral-700 (auto-inverts).
-          expect(cls).not.toContain('dark:border-neutral-');
-        } else {
-          // primary/secondary/success/warning/danger/info share the
-          // border-{color}-300 + bg-{color}-50/40 + dark:* pattern
-          expect(cls).toContain(`border-${color}-300`);
-          expect(cls).toContain(`bg-${color}-50/40`);
-          expect(cls).toContain(`dark:border-${color}-800`);
-          expect(cls).toContain(`dark:bg-${color}-950/30`);
-        }
-      });
-    });
-
-    /*
-     * Soft × 7 intents — semi-transparent tinted background + matching
-     * intent text colour. Dark pair uses a darker bg + lighter text so
-     * contrast holds in both modes.
-     */
-    describe('soft × intent', () => {
-      it.each(INTENTS)('soft × %s emits bg + text with dark pair', (color) => {
-        const { container } = render(<Box variant="soft" color={color}>x</Box>);
-        const cls = container.firstElementChild?.className ?? '';
-        if (color === 'neutral') {
-          // Sprint 4.3 identity sweep: both neutral classes auto-invert
-          // via the dashforgePreset() CSS-var swap — no `dark:` needed.
-          expect(cls).toContain('bg-neutral-100');
-          expect(cls).toContain('text-neutral-900');
-          expect(cls).not.toContain('dark:bg-neutral-');
-          expect(cls).not.toContain('dark:text-neutral-');
-        } else {
-          expect(cls).toContain(`bg-${color}-100`);
-          expect(cls).toContain(`text-${color}-900`);
-          expect(cls).toContain(`dark:bg-${color}-950/50`);
-          expect(cls).toContain(`dark:text-${color}-100`);
-        }
-      });
-    });
-
-    /*
-     * Solid × 7 intents — full-bleed intent background, white text by
-     * default (neutral inverts: black bg → white text in light, white
-     * bg → black text in dark). The dark variant typically uses a
-     * lighter shade so the surface doesn't look pitch black on already-
-     * dark page backgrounds.
-     */
-    describe('solid × intent', () => {
-      it.each(INTENTS)('solid × %s emits bg + text-white (or contrast pair for neutral)', (color) => {
-        const { container } = render(<Box variant="solid" color={color}>x</Box>);
-        const cls = container.firstElementChild?.className ?? '';
-        if (color === 'neutral') {
-          // Sprint 4.3 identity sweep: solid neutral now uses
-          // `bg-neutral-900 text-neutral-50` (both auto-invert) — the
-          // accent surface inverts WITH the page (dark surface in
-          // light mode, light surface in dark mode), consistent with
-          // identity rule. Previously was `text-white` (no inversion)
-          // forcing double-invert pattern to stay readable.
-          expect(cls).toContain('bg-neutral-900');
-          expect(cls).toContain('text-neutral-50');
-          expect(cls).not.toContain('text-white');
-          expect(cls).not.toContain('dark:bg-neutral-');
-          expect(cls).not.toContain('dark:text-neutral-');
-        } else if (color === 'warning') {
-          // warning uses 500/600 instead of 600/500 to keep contrast
-          // legible against an already-yellow surface in light mode.
-          expect(cls).toContain('bg-warning-500');
-          expect(cls).toContain('text-white');
-          expect(cls).toContain('dark:bg-warning-600');
-        } else {
-          expect(cls).toContain(`bg-${color}-600`);
-          expect(cls).toContain('text-white');
-          expect(cls).toContain(`dark:bg-${color}-500`);
-        }
-      });
-    });
-  });
-
-  // ─── F11-bis edge cases: color is ignored for plain / elevated ──────
-  // These two variants are color-agnostic by design (see box.variants.ts
-  // header) — passing `color` shouldn't accidentally inject the intent
-  // bg/border via the compound matrix.
-  describe('color-agnostic variants', () => {
-    it('plain + color="primary" does NOT add intent classes', () => {
-      const { container } = render(<Box variant="plain" color="primary">x</Box>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).not.toContain('bg-primary-');
-      expect(cls).not.toContain('border-primary-');
-      expect(cls).not.toContain('text-primary-');
-    });
-
-    it('elevated + color="danger" stays on the neutral surface', () => {
-      const { container } = render(<Box variant="elevated" color="danger">x</Box>);
-      const cls = container.firstElementChild?.className ?? '';
-      // elevated paints bg-white / dark:bg-neutral-100 regardless of
-      // intent (Sprint 4.3 sweep: dark target corrected to
-      // `dark:bg-neutral-100` for proper dark elevation).
-      expect(cls).toContain('bg-white');
-      expect(cls).toContain('dark:bg-neutral-100');
-      expect(cls).not.toContain('bg-danger-');
-      expect(cls).not.toContain('border-danger-');
-    });
-  });
-
-  // ─── F11-bis edge cases: spacing axis coexistence ───────────────────
-  describe('spacing axis coexistence', () => {
-    it('p={4} + px={6}: both classes emitted (tailwind-merge resolves)', () => {
-      const { container } = render(<Box p={4} px={6}>x</Box>);
-      const cls = container.firstElementChild?.className ?? '';
-      // tailwind-merge: px-6 wins over p-4 on horizontal padding,
-      // p-4 keeps applying vertical via py
-      expect(cls).toContain('px-6');
-      // p-4 → tailwind-merge collapses with px-6 (latter wins on x-axis)
-      // The vertical (py-4 derived from p-4) is what remains.
-    });
-
-    it('m={2} + mx={4} + my={6}: all three coexist (resolves to mx-4 + my-6 effectively)', () => {
-      const { container } = render(<Box m={2} mx={4} my={6}>x</Box>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('mx-4');
-      expect(cls).toContain('my-6');
-    });
-  });
-
-  // ─── F11-bis edge cases: elevation × variant interaction ────────────
-  describe('elevation × variant', () => {
-    it('elevation works on non-elevated variants too (consumer choice)', () => {
-      const { container } = render(<Box variant="outlined" color="neutral" elevation={4}>x</Box>);
-      // The shadow class still gets emitted even though the design
-      // recommendation is "use elevation only with variant=elevated".
-      // We don't gate this at the TV level because compound restrictions
-      // would make the API harder to discover.
-      expect(container.firstElementChild?.className).toContain('shadow-lg');
-    });
-
-    it('elevation=0 explicitly disables shadow', () => {
-      const { container } = render(<Box variant="elevated" elevation={0}>x</Box>);
-      expect(container.firstElementChild?.className).toContain('shadow-none');
-    });
-  });
-
-  // ─── F11-bis edge cases: rounded full ───────────────────────────────
-  describe('rounded edge values', () => {
-    it('rounded="full" produces rounded-full (avatars, pills)', () => {
-      const { container } = render(<Box rounded="full">x</Box>);
-      expect(container.firstElementChild?.className).toContain('rounded-full');
-    });
-
-    it('rounded="none" explicitly removes any rounding', () => {
-      const { container } = render(<Box rounded="none">x</Box>);
-      expect(container.firstElementChild?.className).toContain('rounded-none');
-    });
-  });
-
-  describe('bridge integration — visibleWhen (Sprint 4.4 surface alignment)', () => {
-    it('renders when visibleWhen returns true', () => {
-      const { container } = render(
-        <Box visibleWhen={() => true}>shown</Box>
-      );
-      expect(container.firstChild).toBeTruthy();
-    });
-
-    it('returns null when visibleWhen returns false', () => {
-      const { container } = render(
-        <Box visibleWhen={() => false}>hidden</Box>
-      );
-      expect(container.firstChild).toBeNull();
-    });
-
-    it('renders normally when visibleWhen is omitted', () => {
-      const { container } = render(<Box>always</Box>);
-      expect(container.firstChild).toBeTruthy();
-    });
-  });
-});

package/src/components/Box/Box.tsx

@@ -1,112 +0,0 @@
-import { forwardRef, useContext, type ElementType, type ReactElement } 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 { boxVariants } from './box.variants.js';
-import type { BoxProps } from './box.types.js';
-
-/**
- * `<Box>` — the surface primitive of @dashforge/tw.
- *
- * What it IS:
- *   A polymorphic container with typed surface variants (plain /
- *   outlined / elevated / soft / solid) × 7 intent colours, plus
- *   spacing / sizing / rounded / elevation as enumerated token-scale
- *   props. Replaces MUI's Box + Paper + Card + Surface in one component.
- *
- * What it is NOT (deliberate, enforced by the prop set):
- *   • Not a flex container         → use <Stack>
- *   • Not a grid container         → use <Grid>
- *   • Not a paragraph              → use <Typography>
- *   • Not a button                 → use <Button>
- *
- * The "Box is not flex" rule is the spine of the layout layer. Without
- * it, every `<div>` in an app gravitates back to Box and the surface
- * vs layout distinction collapses. Box's job is the SURFACE around
- * content; Stack/Grid's job is the ARRANGEMENT of content. Two
- * primitives, two responsibilities.
- *
- * When BOTH `as` and `asChild` are passed, `asChild` wins. Same rule
- * as Typography — documented to avoid the dimension-bloat of a
- * discriminated union over an 11-axis props type.
- *
- * Layering:
- *   • Sits BENEATH every visual chrome — every card, every panel,
- *     every section background.
- *   • Composes ON TOP of @dashforge/tw-tokens (color + spacing + radius
- *     + shadow scales) via the dashforgePreset CSS variables.
- *   • Pairs with Typography for text content, Stack/Grid for layout
- *     children inside it.
- */
-export const Box = forwardRef<HTMLElement, BoxProps>(
-  function Box(props, ref) {
-    const {
-      variant,
-      color,
-      elevation,
-      rounded,
-      p, px, py, m, mx, my,
-      fullWidth,
-      fullHeight,
-      as,
-      asChild = false,
-      sx,
-      visibleWhen,
-      access,
-      children,
-      ...rest
-    } = props;
-
-    // Bridge — hooks called unconditionally (rules-of-hooks).
-    // `useEngineVisibility` subscribes to engine state inside a
-    // `<DashForm>` and re-evaluates the predicate reactively; outside
-    // a form, it evaluates the predicate as a plain closure.
-    // `useAccessState` consults the @dashforge/rbac policy engine.
-    // Both default to no-op when the corresponding prop is omitted.
-    const bridge = useContext(DashFormContext);
-    const isVisible = useEngineVisibility(bridge?.engine, visibleWhen);
-    const accessState = useAccessState(access);
-
-    // Early return — predicate false OR RBAC denies visibility.
-    if (!isVisible || !accessState.visible) return null;
-
-    const classes = cn(
-      boxVariants({
-        variant, color, elevation, rounded,
-        p, px, py, m, mx, my,
-        fullWidth, fullHeight,
-      }),
-      // RBAC-disabled / readonly surfaces dim visually + carry
-      // semantic ARIA attributes (assigned below) so descendants and
-      // assistive tech can react.
-      accessState.disabled && 'opacity-60',
-      accessState.readonly && 'opacity-80',
-      sx,
-    );
-
-    const ariaProps = {
-      'aria-disabled': accessState.disabled || undefined,
-      'aria-readonly': accessState.readonly || undefined,
-      'data-disabled': accessState.disabled || undefined,
-      'data-readonly': accessState.readonly || undefined,
-    };
-
-    if (asChild) {
-      return (
-        <Slot ref={ref} className={classes} {...ariaProps} {...rest}>
-          {children as ReactElement}
-        </Slot>
-      );
-    }
-
-    const Tag = (as ?? 'div') as ElementType;
-    return (
-      <Tag ref={ref as never} className={classes} {...ariaProps} {...rest}>
-        {children}
-      </Tag>
-    );
-  },
-);
-
-Box.displayName = 'Box';

package/src/components/Box/box.types.ts

@@ -1,116 +0,0 @@
-import type { ElementType, HTMLAttributes } from 'react';
-import type { Engine } from '@dashforge/ui-core';
-import type { AccessRequirement } from '@dashforge/rbac';
-import type { BoxVariants } from './box.variants.js';
-
-/**
- * Props for `<Box>` — the surface primitive.
- *
- * What lives in props (typed, ergonomic):
- *   • Surface          — variant, color, elevation, rounded
- *   • Spacing          — p, px, py, m, mx, my (token-scale steps)
- *   • Sizing           — fullWidth, fullHeight
- *   • Polymorphism     — as, asChild
- *   • Override escape  — sx (utility string, merged via tailwind-merge)
- *
- * What does NOT live here (deliberate, see Box.tsx header):
- *   • display / flex / grid / gap   → use Stack or Grid
- *   • position / top / z-index      → use sx
- *   • overflow / cursor             → use sx
- *   • animation / transition        → use sx
- *
- * Native attribute overrides:
- *   • `className` is omitted in favour of `sx` (string of utilities,
- *     resolved by tailwind-merge so consumer wins over variant defaults)
- *     — same convention as Button/TextField/Checkbox/Switch.
- *   • `color` is omitted: collides with the deprecated HTML4 `color`
- *     attribute. Our typed `color` (intent) is the right one.
- */
-export interface BoxProps
-  extends Omit<HTMLAttributes<HTMLDivElement>, 'className' | 'color'>,
-          Pick<BoxVariants,
-            'variant' | 'color' | 'elevation' | 'rounded'
-            | 'p' | 'px' | 'py' | 'm' | 'mx' | 'my'
-            | 'fullWidth' | 'fullHeight'> {
-  /**
-   * Override the rendered HTML tag. Defaults to `'div'`. Useful when
-   * the surface should also carry semantic meaning — `<Box as="section">`
-   * for a page section, `<Box as="article">` for a card-shaped article.
-   *
-   * Ignored when `asChild` is true.
-   */
-  as?: ElementType;
-
-  /**
-   * Render via Radix `Slot` — the Box styles paint onto the single
-   * React child instead of wrapping it in our own element. Useful for
-   * `<Box asChild><Link>...</Link></Box>` to get a styled router link
-   * with no extra DOM wrapper.
-   *
-   * Mutually exclusive with `as` (when both are passed, `asChild` wins
-   * — see Box.tsx for the reasoning).
-   */
-  asChild?: boolean;
-
-  /**
-   * Utility classes appended to the variant chain. Resolved via
-   * `tailwind-merge` so the consumer's classes always win over the
-   * variant defaults. Use for one-off overrides AND for utility
-   * dimensions Box deliberately doesn't expose as props (overflow,
-   * position, animation, etc.).
-   */
-  sx?: string;
-
-  /**
-   * Reactive visibility predicate — added in 1.1.0 (Sprint 4.4
-   * surface alignment). When the predicate returns `false`, the
-   * component renders `null`. Inside a `<DashForm>` it subscribes
-   * reactively to engine state changes; outside a form, it's
-   * evaluated as a plain closure.
-   *
-   * Use for state-driven hiding of dashboard cards, conditional
-   * sections, gated content, etc. **For permission-driven hiding,
-   * prefer `access` with `onUnauthorized: 'hide'`** — it's semantically
-   * the correct path and surfaces better in RBAC dev tools.
-   *
-   * @example
-   * ```tsx
-   * // Dashboard card visible only when there are pending shipments
-   * <Box variant="outlined" rounded="lg" p={4}
-   *   visibleWhen={() => pendingCount > 0}>
-   *   <Typography variant="h3">{pendingCount} pending</Typography>
-   * </Box>
-   * ```
-   */
-  visibleWhen?: (engine: Engine) => boolean;
-
-  /**
-   * RBAC requirement — added in 1.1.0 (Sprint 4.4 surface alignment).
-   * Controls Box visibility / disabled-state via the centralized
-   * `@dashforge/rbac` policy engine.
-   *
-   * - `onUnauthorized: 'hide'`     → Box does not render
-   * - `onUnauthorized: 'disable'`  → adds `aria-disabled` + dimmed
-   *   visual; interactive children should derive their disabled state
-   *   from `data-disabled` on the Box or pass their own `access`
-   * - `onUnauthorized: 'readonly'` → adds `aria-readonly`; mostly used
-   *   when Box wraps form sections that propagate readonly to children
-   *
-   * Use for permission-gated dashboard cards, admin-only sections,
-   * tenant-aware layouts. The hide path is the common case.
-   *
-   * @example
-   * ```tsx
-   * // Revenue card visible only to users with billing:read permission
-   * <Box variant="elevated" rounded="lg" elevation={2} p={4}
-   *   access={{
-   *     resource: 'billing',
-   *     action: 'read',
-   *     onUnauthorized: 'hide'
-   *   }}>
-   *   <Typography variant="h3">Q3 Revenue</Typography>
-   * </Box>
-   * ```
-   */
-  access?: AccessRequirement;
-}