@dashforge/tw 1.0.0 → 1.1.0

package/src/components/Badge/badge.types.ts

@@ -0,0 +1,154 @@
+import type { ReactNode } from 'react';
+import type { ClassValue } from 'tailwind-variants';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
+
+/**
+ * Intent color — drives the badge background. Default is `danger`
+ * because the most common notification UX expects a red dot/count
+ * for "needs attention" affordance.
+ */
+export type BadgeColor =
+  | 'neutral'
+  | 'primary'
+  | 'secondary'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'info';
+
+/** 4 corner positions for the floating badge. */
+export type BadgePlacement =
+  | 'top-right'
+  | 'top-left'
+  | 'bottom-right'
+  | 'bottom-left';
+
+/**
+ * Anchor shape:
+ *   - `'rectangular'` (default) — badge sits at the bounding-box
+ *     corner. Use for square-ish anchors like IconButton, Card.
+ *   - `'circular'` — badge offset to align with the circular edge.
+ *     Use for round anchors like Avatar.
+ */
+export type BadgeOverlap = 'rectangular' | 'circular';
+
+/**
+ * Per-slot className overrides for `<Badge>`.
+ */
+export interface BadgeSlotProps {
+  /** Outer wrapper (relative-positioned, contains the anchor + badge). */
+  root?: { className?: string };
+  /** The floating badge pill / dot itself. */
+  badge?: { className?: string };
+}
+
+/**
+ * Props for `<Badge>` — anchored indicator (count / dot / short text).
+ *
+ * Wrapper-only mode: `<Badge>` always wraps an anchor element passed
+ * as `children`. For standalone inline pills (status labels, tags),
+ * use `<Chip>` — Badge and Chip are complementary, not interchangeable.
+ *
+ * Relationship with Chip:
+ *   - `<Chip>` = inline pill (interactive — `onClick`, `onDelete`,
+ *     `selected`). Standalone, no anchor.
+ *   - `<Badge>` = anchored indicator (passive — small count / dot
+ *     overlaid on top of another element).
+ */
+export interface BadgeProps {
+  // ─── Required ──────────────────────────────────────────────────
+  /** The anchor element (Avatar / IconButton / button / Card / custom). */
+  children: ReactNode;
+
+  // ─── Content ───────────────────────────────────────────────────
+  /**
+   * Numeric or string content to display inside the badge.
+   *   - `number` → formatted via `max` (overflow renders as `"N+"`)
+   *   - `string` → rendered verbatim (e.g., `"NEW"`)
+   *   - omitted + `dot=false` → no badge rendered (or only at zero if
+   *     `showZero=true`)
+   */
+  content?: number | string;
+
+  /**
+   * Dot-only mode — small circle without content. When `true`,
+   * `content` and `max` are ignored.
+   */
+  dot?: boolean;
+
+  /**
+   * Overflow threshold for numeric `content`. Values above render
+   * as `{max}+`. Set to `-1` to disable overflow (always raw number).
+   * @default 99
+   */
+  max?: number;
+
+  /**
+   * Whether to render the badge when numeric `content` is `0`.
+   * Hidden by default — the typical notification UX is "no badge =
+   * nothing to see".
+   * @default false
+   */
+  showZero?: boolean;
+
+  /**
+   * Imperative hide — keeps the badge in the DOM but applies
+   * `display: none`. Use for opacity/scale fade animations without
+   * unmounting.
+   * @default false
+   */
+  invisible?: boolean;
+
+  // ─── Visual ────────────────────────────────────────────────────
+  /** @default 'danger' — typical "needs attention" notification color. */
+  color?: BadgeColor;
+
+  /** @default 'top-right' */
+  placement?: BadgePlacement;
+
+  /**
+   * Anchor shape — controls badge offset.
+   * - `'rectangular'` (default) sits at the bounding-box corner
+   * - `'circular'` offsets to align with the circular anchor edge
+   *   (use with `<Avatar shape="circle">`)
+   * @default 'rectangular'
+   */
+  overlap?: BadgeOverlap;
+
+  /**
+   * White/neutral ring around the badge — visually separates from
+   * the anchor surface. Token-driven via `ring-neutral-50` which
+   * auto-inverts via the dashforgePreset CSS-var swap (no `dark:`
+   * needed).
+   * @default true
+   */
+  withRing?: boolean;
+
+  // ─── Bridge integration (Sprint 4.4) ───────────────────────────
+  /**
+   * RBAC requirement — hides the badge for unauthorized subjects.
+   * The wrapped anchor element remains visible (use Box `access`
+   * to gate the anchor too).
+   *
+   * Use case: admin-only notification count, role-gated indicators.
+   */
+  access?: AccessRequirement;
+
+  /**
+   * Reactive visibility predicate. When `false`, the badge dot/count
+   * is not rendered (children always render). Use for state-driven
+   * indicators tied to engine values.
+   */
+  visibleWhen?: (engine: Engine) => boolean;
+
+  // ─── Override ──────────────────────────────────────────────────
+  /** Root-element class shortcut. */
+  sx?: ClassValue;
+
+  /** Standard className — appended to the root via `cn()`. */
+  className?: string;
+
+  /** Per-slot overrides — root + badge. */
+  slotProps?: BadgeSlotProps;
+}

package/src/components/Badge/badge.variants.ts

@@ -0,0 +1,161 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * Tailwind-variants recipe for `<Badge>`.
+ *
+ * Slot layout:
+ *   - `root`  — outer span (relative-positioned wrapper around the
+ *               anchor). `inline-flex` so the wrapper shrinks to fit
+ *               the anchor element.
+ *   - `badge` — the floating absolute-positioned pill / dot. Two
+ *               variants (`dot=true` → tiny circle, `dot=false` →
+ *               pill with min-width to fit content).
+ *
+ * Color axis emits the `badge` background + text classes. The 7
+ * intents map to:
+ *   - solid bg: `bg-{intent}-500` (vivid, attention-grabbing for
+ *     notifications — different from Chip which uses 600 for solid
+ *     because chip surface is larger; small badge needs the brighter
+ *     mid-tone)
+ *   - text: `text-white` for primary/secondary/success/warning/danger/
+ *     info; `text-neutral-50` for neutral (auto-inverts via CSS-var
+ *     swap, no `dark:` needed)
+ *
+ * Placement axis emits absolute-position + translate utilities:
+ *   - top-right (default): `top-0 right-0 -translate-y-1/2 translate-x-1/2`
+ *   - top-left:    `top-0 left-0 -translate-y-1/2 -translate-x-1/2`
+ *   - bottom-right: `bottom-0 right-0 translate-y-1/2 translate-x-1/2`
+ *   - bottom-left:  `bottom-0 left-0 translate-y-1/2 -translate-x-1/2`
+ *
+ * Overlap axis adds an extra inset for circular anchors so the
+ * badge sits along the round edge instead of the bounding box corner.
+ */
+export const badgeVariants = tv({
+  slots: {
+    root: 'relative inline-flex shrink-0',
+    badge: [
+      // Absolute positioning is owned by the placement compound rules.
+      'absolute z-10',
+      // Layout / typography — pill defaults; dot mode overrides
+      // dimensions below.
+      'inline-flex items-center justify-center',
+      'rounded-full',
+      'text-[10px] font-medium leading-none',
+      'pointer-events-none select-none',
+      // Smooth show/hide for `invisible` toggle (consumer-side
+      // animation hook). Gated on motion-reduce per WCAG 2.3.3.
+      'transition-transform duration-150 motion-reduce:transition-none motion-reduce:duration-0',
+    ],
+  },
+  variants: {
+    /**
+     * `dot=true` → tiny circle (8px), no content. The badge slot
+     * collapses to a fixed-size circle without the pill min-width.
+     */
+    dot: {
+      true: {
+        badge: 'w-2 h-2 p-0',
+      },
+      false: {
+        // Content pill — 16px tall, padded inline, min-width so
+        // single-digit counts still read centered.
+        badge: 'min-w-4 h-4 px-1',
+      },
+    },
+    /** Whether the floating badge is hidden via `display: none`. */
+    invisible: {
+      true: {
+        badge: 'hidden',
+      },
+    },
+    /** Halo ring for visual separation from the anchor surface. */
+    withRing: {
+      true: {
+        // ring-neutral-50 auto-inverts via dashforgePreset CSS var
+        // swap (no `dark:` needed for the neutral palette).
+        badge: 'ring-2 ring-neutral-50',
+      },
+    },
+    /** 7 intents — drives the badge background + text colour. */
+    color: {
+      neutral: {
+        // Both classes on the neutral palette — auto-invert via CSS
+        // var swap. No `dark:` variants needed.
+        badge: 'bg-neutral-700 text-neutral-50',
+      },
+      primary: { badge: 'bg-primary-500 text-white' },
+      secondary: { badge: 'bg-secondary-500 text-white' },
+      success: { badge: 'bg-success-500 text-white' },
+      warning: { badge: 'bg-warning-500 text-white' },
+      danger: { badge: 'bg-danger-500 text-white' },
+      info: { badge: 'bg-info-500 text-white' },
+    },
+    placement: {
+      'top-right': {
+        badge: 'top-0 right-0 -translate-y-1/2 translate-x-1/2',
+      },
+      'top-left': {
+        badge: 'top-0 left-0 -translate-y-1/2 -translate-x-1/2',
+      },
+      'bottom-right': {
+        badge: 'bottom-0 right-0 translate-y-1/2 translate-x-1/2',
+      },
+      'bottom-left': {
+        badge: 'bottom-0 left-0 translate-y-1/2 -translate-x-1/2',
+      },
+    },
+    /**
+     * `overlap='circular'` adds an inward inset so the badge sits
+     * along the circular anchor edge instead of the bounding-box
+     * corner. The 14% offset is empirically tuned to match the
+     * standard avatar / round-button geometry (matches MUI's value).
+     */
+    overlap: {
+      rectangular: {},
+      circular: {},
+    },
+  },
+  compoundVariants: [
+    // ─── overlap='circular' × placement — additional inset ─────────
+    // The inward shift is in addition to the placement translate,
+    // achieved via an extra `-{translate-corner}` adjustment.
+    {
+      overlap: 'circular',
+      placement: 'top-right',
+      class: {
+        badge: 'top-[14%] right-[14%] translate-x-1/2 -translate-y-1/2',
+      },
+    },
+    {
+      overlap: 'circular',
+      placement: 'top-left',
+      class: {
+        badge: 'top-[14%] left-[14%] -translate-x-1/2 -translate-y-1/2',
+      },
+    },
+    {
+      overlap: 'circular',
+      placement: 'bottom-right',
+      class: {
+        badge: 'bottom-[14%] right-[14%] translate-x-1/2 translate-y-1/2',
+      },
+    },
+    {
+      overlap: 'circular',
+      placement: 'bottom-left',
+      class: {
+        badge: 'bottom-[14%] left-[14%] -translate-x-1/2 translate-y-1/2',
+      },
+    },
+  ],
+  defaultVariants: {
+    dot: false,
+    invisible: false,
+    withRing: true,
+    color: 'danger',
+    placement: 'top-right',
+    overlap: 'rectangular',
+  },
+});
+
+export type BadgeVariants = VariantProps<typeof badgeVariants>;

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

@@ -367,4 +367,25 @@ describe('<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,6 +1,8 @@
-import { forwardRef, type ElementType, type ReactElement } from 'react';
+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';
 
@@ -50,22 +52,49 @@ export const Box = forwardRef<HTMLElement, BoxProps>(
       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} {...rest}>
+        <Slot ref={ref} className={classes} {...ariaProps} {...rest}>
           {children as ReactElement}
         </Slot>
       );
@@ -73,7 +102,7 @@ export const Box = forwardRef<HTMLElement, BoxProps>(
 
     const Tag = (as ?? 'div') as ElementType;
     return (
-      <Tag ref={ref as never} className={classes} {...rest}>
+      <Tag ref={ref as never} className={classes} {...ariaProps} {...rest}>
         {children}
       </Tag>
     );

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

@@ -1,4 +1,6 @@
 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';
 
 /**
@@ -58,4 +60,57 @@ export interface BoxProps
    * 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;
 }

package/src/components/Button/Button.test.tsx

@@ -181,3 +181,24 @@ describe('Button — asChild polymorphism', () => {
     expect(node.getAttribute('aria-disabled')).toBe('true');
   });
 });
+
+describe('Button — visibleWhen (engine-reactive visibility, Sprint 4.4)', () => {
+  it('renders when visibleWhen returns true (no DashForm context)', () => {
+    const { container } = render(
+      <Button visibleWhen={() => true}>shown</Button>
+    );
+    expect(container.firstChild).toBeTruthy();
+  });
+
+  it('returns null when visibleWhen returns false', () => {
+    const { container } = render(
+      <Button visibleWhen={() => false}>hidden</Button>
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders normally when visibleWhen is omitted', () => {
+    const { container } = render(<Button>always</Button>);
+    expect(container.firstChild).toBeTruthy();
+  });
+});

package/src/components/Button/Button.tsx

@@ -1,36 +1,22 @@
-import { forwardRef } from 'react';
+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 { Spinner } from '../Spinner/Spinner.js';
+import type { SpinnerSize } from '../Spinner/spinner.types.js';
 import { buttonVariants } from './button.variants.js';
 import type { ButtonProps } from './button.types.js';
 
 /**
- * Inline spinner shown when `loading` is true. Kept inline (≈10 lines
- * of SVG) so the package adds no icon-library dependency.
+ * Map Button size to Spinner size. Button has 3 sizes (sm/md/lg);
+ * Spinner has 5 (xs/sm/md/lg/xl). Picking the closest match keeps
+ * the spinner visually proportional to the button label.
  *
  * @internal
  */
-function LoadingSpinner({ size }: { size: 'sm' | 'md' | 'lg' }) {
-  const dim = size === 'sm' ? 14 : size === 'lg' ? 20 : 16;
-  return (
-    <svg
-      aria-hidden="true"
-      width={dim}
-      height={dim}
-      viewBox="0 0 24 24"
-      fill="none"
-      className="animate-spin"
-    >
-      <circle cx="12" cy="12" r="9" stroke="currentColor" strokeWidth="2.5" strokeOpacity="0.25" />
-      <path
-        d="M21 12a9 9 0 0 0-9-9"
-        stroke="currentColor"
-        strokeWidth="2.5"
-        strokeLinecap="round"
-      />
-    </svg>
-  );
+function buttonSizeToSpinnerSize(size: 'sm' | 'md' | 'lg'): SpinnerSize {
+  return size === 'sm' ? 'xs' : size === 'lg' ? 'md' : 'sm';
 }
 
 /**
@@ -80,6 +66,7 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button
 ) {
   const {
     access,
+    visibleWhen,
     disabled,
     variant,
     color,
@@ -92,11 +79,18 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button
     ...rest
   } = props;
 
-  // RBAC always called unconditionally (rules-of-hooks compliance).
+  // Bridge — both hooks called unconditionally (rules-of-hooks).
+  // Inside a `<DashForm>`, `useEngineVisibility` subscribes to engine
+  // state and re-evaluates the predicate on changes; outside a form,
+  // the predicate is called with `null` engine (consumer captures
+  // external state in the closure).
+  const bridge = useContext(DashFormContext);
+  const isVisible = useEngineVisibility(bridge?.engine, visibleWhen);
   const accessState = useAccessState(access);
 
-  // Early return for hidden state.
-  if (!accessState.visible) return null;
+  // Early return for hidden state — either RBAC denies visibility or
+  // the engine-reactive predicate returned false.
+  if (!isVisible || !accessState.visible) return null;
 
   // Effective disabled = explicit OR RBAC-disabled OR RBAC-readonly OR loading.
   // Buttons do not support a true readonly state — RBAC readonly is mapped
@@ -143,7 +137,14 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button
       className={classes}
       {...rest}
     >
-      {loading && <LoadingSpinner size={size ?? 'md'} />}
+      {loading && (
+        <Spinner
+          size={buttonSizeToSpinnerSize(size ?? 'md')}
+          thickness="thick"
+          withTrack
+          label=""
+        />
+      )}
       {children}
     </button>
   );

package/src/components/Button/button.types.ts

@@ -1,4 +1,5 @@
 import type { ButtonHTMLAttributes } from 'react';
+import type { Engine } from '@dashforge/ui-core';
 import type { AccessRequirement } from '@dashforge/rbac';
 import type { ButtonVariants } from './button.variants.js';
 
@@ -45,6 +46,41 @@ export interface ButtonProps
    */
   access?: AccessRequirement;
 
+  /**
+   * Reactive visibility predicate. Re-evaluated on every engine state
+   * change when the button is mounted inside a `<DashForm>`; outside
+   * a form, evaluated as a plain predicate (the consumer captures
+   * any external state in the closure).
+   *
+   * When the predicate returns `false`, the component renders `null`.
+   *
+   * **Added in 1.1.0 (Sprint 4.4 alignment)** — extends the
+   * engine-reactive visibility pattern previously available only on
+   * form fields + `<Alert>` to every interactive component in the
+   * Dashforge TW catalog (Button, IconButton, Chip, …).
+   *
+   * Note: `visibleWhen` is for **state-driven** hide. For
+   * **permission-driven** hide, use `access` with
+   * `onUnauthorized: 'hide'` — it's the semantically correct path
+   * and provides better error messages in RBAC dev tools.
+   *
+   * @example
+   * ```tsx
+   * // Inside a DashForm — reactive on engine state
+   * <Button
+   *   visibleWhen={(engine) =>
+   *     engine.getNode('plan')?.value === 'premium'
+   *   }
+   * >
+   *   Upgrade extras
+   * </Button>
+   *
+   * // Outside a form — closure over external React state
+   * <Button visibleWhen={() => itemCount > 0}>Bulk delete</Button>
+   * ```
+   */
+  visibleWhen?: (engine: Engine) => boolean;
+
   /**
    * When `true`, the immediate child element is rendered with the
    * Button's classes merged in (via `@radix-ui/react-slot`). The