@dashforge/tw 0.11.0-beta → 1.1.0

package/src/components/Chip/Chip.test.tsx

@@ -0,0 +1,316 @@
+// @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 { Chip } from './Chip.js';
+
+void React;
+afterEach(() => cleanup());
+
+/**
+ * `<Chip>` unit tests. Covers:
+ *   - static vs clickable rendering (span vs button)
+ *   - sample variant × color cells (token-driven, no hardcoded hex)
+ *   - icon / avatar leading slots (avatar wins when both set)
+ *   - onClick (clickable) and onDelete (delete button) — separate
+ *     event paths, delete button stops propagation
+ *   - selected → aria-pressed
+ *   - disabled state (explicit + access.disabled)
+ *   - access RBAC: hide / disable
+ *   - className / sx overrides
+ */
+
+const FULL_ACCESS_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('<Chip>', () => {
+  describe('rendering — root element', () => {
+    it('renders as <span> by default (static)', () => {
+      const { container } = render(<Chip label="Active" />);
+      expect(container.querySelector('span')).toBeTruthy();
+      expect(container.querySelector('button')).toBeNull();
+    });
+
+    it('renders as <button> when clickable=true', () => {
+      render(<Chip label="Filter" clickable />);
+      expect(screen.getByRole('button', { name: /filter/i })).toBeTruthy();
+    });
+
+    it('renders as <button> when onClick is provided (implicit clickable)', () => {
+      render(<Chip label="Click me" onClick={() => {}} />);
+      expect(screen.getByRole('button', { name: /click me/i })).toBeTruthy();
+    });
+
+    it('renders the label content', () => {
+      render(<Chip label="Active" />);
+      expect(screen.getByText('Active')).toBeTruthy();
+    });
+  });
+
+  describe('variant × color matrix (sample, token-driven)', () => {
+    it('renders soft + primary with token classes (no hardcoded hex)', () => {
+      const { container } = render(
+        <Chip label="x" variant="soft" color="primary" />
+      );
+      const root = container.firstChild as HTMLElement;
+      expect(root.className).toContain('bg-primary-100');
+      expect(root.className).toContain('text-primary-700');
+      expect(root.className).not.toMatch(/#[0-9a-fA-F]{3,8}/);
+    });
+
+    it('renders solid + danger with full bg', () => {
+      const { container } = render(
+        <Chip label="x" variant="solid" color="danger" />
+      );
+      const root = container.firstChild as HTMLElement;
+      expect(root.className).toContain('bg-danger-500');
+      expect(root.className).toContain('text-white');
+    });
+
+    it('renders outline + info with border', () => {
+      const { container } = render(
+        <Chip label="x" variant="outline" color="info" />
+      );
+      const root = container.firstChild as HTMLElement;
+      expect(root.className).toContain('border-info-500');
+      expect(root.className).toContain('text-info-700');
+    });
+
+    it('defaults to soft + neutral when omitted', () => {
+      const { container } = render(<Chip label="x" />);
+      const root = container.firstChild as HTMLElement;
+      expect(root.className).toContain('bg-neutral-100');
+      expect(root.className).toContain('text-neutral-700');
+    });
+  });
+
+  describe('size axis', () => {
+    it('applies h-5 + text-xs for size="sm" (default)', () => {
+      const { container } = render(<Chip label="x" />);
+      const root = container.firstChild as HTMLElement;
+      expect(root.className).toContain('h-5');
+      expect(root.className).toContain('text-xs');
+    });
+
+    it('applies h-6 for size="md"', () => {
+      const { container } = render(<Chip label="x" size="md" />);
+      const root = container.firstChild as HTMLElement;
+      expect(root.className).toContain('h-6');
+    });
+  });
+
+  describe('leading slots — icon / avatar', () => {
+    it('renders icon when provided', () => {
+      render(
+        <Chip label="x" icon={<span data-testid="icon">i</span>} />
+      );
+      expect(screen.getByTestId('icon')).toBeTruthy();
+    });
+
+    it('renders avatar when provided', () => {
+      render(
+        <Chip label="x" avatar={<span data-testid="avatar">A</span>} />
+      );
+      expect(screen.getByTestId('avatar')).toBeTruthy();
+    });
+
+    it('avatar wins over icon when both set (MUI parity)', () => {
+      render(
+        <Chip
+          label="x"
+          icon={<span data-testid="icon">i</span>}
+          avatar={<span data-testid="avatar">A</span>}
+        />
+      );
+      expect(screen.getByTestId('avatar')).toBeTruthy();
+      expect(screen.queryByTestId('icon')).toBeNull();
+    });
+  });
+
+  describe('onClick (clickable chip)', () => {
+    it('fires onClick when clicked', () => {
+      const onClick = vi.fn();
+      render(<Chip label="x" onClick={onClick} />);
+      fireEvent.click(screen.getByRole('button'));
+      expect(onClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('does NOT fire onClick when disabled', () => {
+      const onClick = vi.fn();
+      render(<Chip label="x" onClick={onClick} disabled />);
+      fireEvent.click(screen.getByRole('button'));
+      expect(onClick).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('onDelete (delete button)', () => {
+    it('renders a delete button when onDelete is provided', () => {
+      render(<Chip label="tag" onDelete={() => {}} />);
+      expect(screen.getByRole('button', { name: /^remove$/i })).toBeTruthy();
+    });
+
+    it('does NOT render a delete button when onDelete is omitted', () => {
+      render(<Chip label="tag" />);
+      expect(screen.queryByRole('button', { name: /^remove$/i })).toBeNull();
+    });
+
+    it('respects custom deleteLabel for aria-label', () => {
+      render(<Chip label="tag" onDelete={() => {}} deleteLabel="Detach tag" />);
+      expect(screen.getByRole('button', { name: /detach tag/i })).toBeTruthy();
+    });
+
+    it('fires onDelete when delete button clicked', () => {
+      const onDelete = vi.fn();
+      render(<Chip label="tag" onDelete={onDelete} />);
+      fireEvent.click(screen.getByRole('button', { name: /remove/i }));
+      expect(onDelete).toHaveBeenCalledTimes(1);
+    });
+
+    it('delete button does NOT trigger chip onClick (stopPropagation)', () => {
+      const onClick = vi.fn();
+      const onDelete = vi.fn();
+      render(
+        <Chip label="tag" onClick={onClick} onDelete={onDelete} />
+      );
+      // Click on the delete button
+      fireEvent.click(screen.getByRole('button', { name: /remove/i }));
+      expect(onDelete).toHaveBeenCalledTimes(1);
+      expect(onClick).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('selected state', () => {
+    it('applies aria-pressed=true when selected on a clickable chip', () => {
+      render(<Chip label="x" clickable selected />);
+      const btn = screen.getByRole('button');
+      expect(btn.getAttribute('aria-pressed')).toBe('true');
+    });
+
+    it('applies the selected ring class', () => {
+      const { container } = render(<Chip label="x" clickable selected />);
+      const root = container.firstChild as HTMLElement;
+      expect(root.className).toContain('ring-2');
+    });
+
+    it('does NOT set aria-pressed when not selected', () => {
+      render(<Chip label="x" clickable />);
+      const btn = screen.getByRole('button');
+      expect(btn.getAttribute('aria-pressed')).toBeNull();
+    });
+  });
+
+  describe('disabled state', () => {
+    it('respects the explicit disabled prop on clickable chip', () => {
+      render(<Chip label="x" clickable disabled />);
+      const btn = screen.getByRole('button') as HTMLButtonElement;
+      expect(btn.disabled).toBe(true);
+    });
+
+    it('applies opacity-50 + cursor-not-allowed to root when disabled', () => {
+      const { container } = render(<Chip label="x" disabled />);
+      const root = container.firstChild as HTMLElement;
+      expect(root.className).toContain('opacity-50');
+    });
+  });
+
+  describe('access RBAC integration', () => {
+    it('hides the chip when access.onUnauthorized=hide and subject lacks permission', () => {
+      const { container } = render(
+        <RbacProvider policy={NO_ACCESS_POLICY} subject={guestSubject}>
+          <Chip
+            label="x"
+            access={{
+              resource: 'admin-panel',
+              action: 'read',
+              onUnauthorized: 'hide',
+            }}
+          />
+        </RbacProvider>
+      );
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('disables a clickable chip when access.onUnauthorized=disable', () => {
+      render(
+        <RbacProvider policy={NO_ACCESS_POLICY} subject={guestSubject}>
+          <Chip
+            label="x"
+            clickable
+            access={{
+              resource: 'admin-panel',
+              action: 'read',
+              onUnauthorized: 'disable',
+            }}
+          />
+        </RbacProvider>
+      );
+      const btn = screen.getByRole('button') as HTMLButtonElement;
+      expect(btn.disabled).toBe(true);
+    });
+
+    it('renders normally for admin subject', () => {
+      render(
+        <RbacProvider policy={FULL_ACCESS_POLICY} subject={adminSubject}>
+          <Chip
+            label="visible"
+            access={{
+              resource: 'admin-panel',
+              action: 'read',
+              onUnauthorized: 'hide',
+            }}
+          />
+        </RbacProvider>
+      );
+      expect(screen.getByText('visible')).toBeTruthy();
+    });
+  });
+
+  describe('bridge integration — visibleWhen', () => {
+    it('renders when visibleWhen returns true (no DashForm context)', () => {
+      const { container } = render(
+        <Chip label="shown" visibleWhen={() => true} />
+      );
+      expect(container.firstChild).toBeTruthy();
+      expect(screen.getByText('shown')).toBeTruthy();
+    });
+
+    it('returns null when visibleWhen returns false', () => {
+      const { container } = render(
+        <Chip label="hidden" visibleWhen={() => false} />
+      );
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('renders normally when visibleWhen is omitted', () => {
+      const { container } = render(<Chip label="always" />);
+      expect(container.firstChild).toBeTruthy();
+    });
+  });
+
+  describe('overrides — sx + className', () => {
+    it('appends sx to the root className', () => {
+      const { container } = render(<Chip label="x" sx="ring-2 ring-purple-500" />);
+      const root = container.firstChild as HTMLElement;
+      expect(root.className).toContain('ring-purple-500');
+    });
+
+    it('appends className to the root', () => {
+      const { container } = render(<Chip label="x" className="my-custom-chip" />);
+      const root = container.firstChild as HTMLElement;
+      expect(root.className).toContain('my-custom-chip');
+    });
+  });
+});

package/src/components/Chip/Chip.tsx

@@ -0,0 +1,224 @@
+import { forwardRef, useContext, type KeyboardEvent, type MouseEvent } from 'react';
+import { DashFormContext, useEngineVisibility } from '@dashforge/ui-core';
+import { cn } from '../../utils/cn.js';
+import { useAccessState } from '../../hooks/useAccessState.js';
+import { chipVariants } from './chip.variants.js';
+import type { ChipProps } from './chip.types.js';
+
+/**
+ * Default delete-button glyph — inline stroke SVG. Inherits the
+ * chip's text colour via `currentColor`. No icon-library dep.
+ *
+ * @internal
+ */
+function DefaultDeleteIcon() {
+  return (
+    <svg
+      width="0.875em"
+      height="0.875em"
+      viewBox="0 0 14 14"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.75}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="m4 4 6 6M10 4l-6 6" />
+    </svg>
+  );
+}
+
+/**
+ * Dashforge TW Chip — status / filter / tag pill.
+ *
+ * Promoted from the internal `Table/cells/RenderChip` (Sprint 4.4):
+ * preserves the 3 × 7 variant × color matrix byte-identical and adds
+ * the public API (label, icon, avatar, clickable, onClick, onDelete,
+ * selected, access).
+ *
+ * **Rendering modes** (chosen at runtime from props):
+ *   - **Static** (default) → `<span>`. Pure display.
+ *   - **Clickable** (`clickable` true OR `onClick` provided) →
+ *     `<button type="button">` with focus ring + hover state.
+ *   - **Deletable** (`onDelete` provided) → root + trailing `<button>`
+ *     for the delete glyph. Static or clickable root depending on
+ *     whether `onClick` is also set.
+ *
+ * **Variant axis** is `soft | solid | outline` (Dashforge chip
+ * vocabulary, default `'soft'`). Distinct from Button's
+ * (`solid | outline | ghost | link`) and Alert's
+ * (`standard | filled | outlined`) by design — see CHANGELOG.
+ *
+ * **A11y**:
+ *   - Static chip → no role (it's a `<span>`).
+ *   - Clickable chip → native `<button>` semantics.
+ *   - `selected` → `aria-pressed="true"` (so it announces as a toggle
+ *     button in pressed state).
+ *   - Delete button → its own `<button>` with `aria-label`
+ *     (defaults to `'Remove'`).
+ *
+ * @example
+ * ```tsx
+ * // Static status chip
+ * <Chip label="Active" color="success" />
+ *
+ * // With icon
+ * import { CheckIcon } from 'lucide-react';
+ * <Chip label="Verified" color="success" icon={<CheckIcon size={14} />} />
+ *
+ * // Filter chip (clickable + toggle via selected)
+ * <Chip
+ *   label="Last 7 days"
+ *   color="primary"
+ *   clickable
+ *   selected={range === '7d'}
+ *   onClick={() => setRange('7d')}
+ * />
+ *
+ * // Removable tag
+ * <Chip
+ *   label="design-system"
+ *   color="info"
+ *   variant="outline"
+ *   onDelete={() => removeTag('design-system')}
+ * />
+ *
+ * // RBAC-gated admin chip
+ * <Chip
+ *   label="Admin"
+ *   color="danger"
+ *   variant="solid"
+ *   access={{ resource: 'role', action: 'read', onUnauthorized: 'hide' }}
+ * />
+ * ```
+ */
+export const Chip = forwardRef<HTMLElement, ChipProps>(function Chip(
+  props,
+  ref
+) {
+  const {
+    label,
+    icon,
+    avatar,
+    variant,
+    color,
+    size,
+    clickable: clickableProp,
+    onClick,
+    onDelete,
+    deleteIcon,
+    deleteLabel = 'Remove',
+    selected,
+    disabled: disabledProp,
+    visibleWhen,
+    access,
+    sx,
+    className,
+  } = props;
+
+  // 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);
+
+  if (!isVisible || !accessState.visible) return null;
+
+  // Effective interactivity / disabled — mirrors Button semantics.
+  const isClickable = Boolean(clickableProp ?? onClick);
+  const isDisabled =
+    Boolean(disabledProp) || accessState.disabled || accessState.readonly;
+
+  const classes = cn(
+    chipVariants({
+      color,
+      variant,
+      size,
+      clickable: isClickable || undefined,
+      selected: selected || undefined,
+      disabled: isDisabled || undefined,
+    }),
+    sx,
+    className
+  );
+
+  // ─── Inner content — leading slot + label + delete ────────────
+  // Avatar wins over icon when both provided (MUI parity).
+  // Label is rendered as a direct text node (no wrapping span) so
+  // the chip DOM stays minimal and consumers that target the root
+  // via `getByText(label)` continue working. The root's
+  // `inline-flex items-center` provides vertical alignment with
+  // any leading / trailing slots.
+  const leading = avatar ?? icon;
+  const innerContent = (
+    <>
+      {leading != null && (
+        <span className="-ml-0.5 inline-flex items-center shrink-0">
+          {leading}
+        </span>
+      )}
+      {label}
+      {onDelete != null && (
+        <button
+          type="button"
+          aria-label={deleteLabel}
+          onClick={(e: MouseEvent<HTMLButtonElement>) => {
+            // Stop propagation so the chip's own onClick doesn't fire
+            // when the user clicks the × — MUI matches this behaviour.
+            e.stopPropagation();
+            if (!isDisabled) onDelete(e);
+          }}
+          disabled={isDisabled}
+          className={cn(
+            'ml-0.5 -mr-1 inline-flex items-center justify-center',
+            'h-4 w-4 rounded-full opacity-70 hover:opacity-100',
+            'outline-none focus-visible:ring-2 focus-visible:ring-current',
+            'transition-opacity'
+          )}
+        >
+          {deleteIcon ?? <DefaultDeleteIcon />}
+        </button>
+      )}
+    </>
+  );
+
+  // ─── Interactive root (clickable) ─────────────────────────────
+  if (isClickable) {
+    return (
+      <button
+        ref={ref as React.Ref<HTMLButtonElement>}
+        type="button"
+        className={classes}
+        disabled={isDisabled}
+        aria-pressed={selected ? true : undefined}
+        onClick={(e: MouseEvent<HTMLButtonElement>) => {
+          if (isDisabled) return;
+          onClick?.(e);
+        }}
+        onKeyDown={(e: KeyboardEvent<HTMLButtonElement>) => {
+          // Native <button> handles Enter + Space already; the keydown
+          // is here for future extension (e.g. Delete key to fire
+          // onDelete when focused) — currently no-op.
+          void e;
+        }}
+      >
+        {innerContent}
+      </button>
+    );
+  }
+
+  // ─── Static root (display only) ───────────────────────────────
+  return (
+    <span
+      ref={ref as React.Ref<HTMLSpanElement>}
+      className={classes}
+      aria-disabled={isDisabled || undefined}
+    >
+      {innerContent}
+    </span>
+  );
+});

package/src/components/Chip/chip.types.ts

@@ -0,0 +1,128 @@
+import type { ReactNode } from 'react';
+import type { ClassValue } from 'tailwind-variants';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { ChipVariants } from './chip.variants.js';
+
+/**
+ * Props for `<Chip>` — status / filter / tag pill.
+ *
+ * Mirrors MUI Chip's API surface where it makes sense (label, icon,
+ * avatar, clickable, onDelete) and extends with Dashforge-specific
+ * affordances (`selected` for filter chips, `access` for RBAC).
+ *
+ * Variant axis (`soft | solid | outline`) is the **Dashforge chip
+ * vocabulary** — distinct from Button's (`solid | outline | ghost |
+ * link`) and Alert's (`standard | filled | outlined`). The asymmetry
+ * is intentional and category-scoped: each component family uses the
+ * vocabulary that maps to its design needs (see CHANGELOG +
+ * MIGRATION.md for the design note).
+ *
+ * @see https://mui.com/material-ui/api/chip/
+ */
+export interface ChipProps
+  extends Pick<
+    ChipVariants,
+    'color' | 'variant' | 'size' | 'selected' | 'disabled'
+  > {
+  /**
+   * The chip's textual content. Named `label` for MUI parity — most
+   * design systems (MUI, Radix Themes, Mantine, Tremor) use `label`
+   * as the canonical content prop on Chip / Badge / Pill primitives.
+   */
+  label: ReactNode;
+
+  /**
+   * Leading icon — typically a small SVG (16px). Consumer brings
+   * their iconography. Rendered inside the chip BEFORE the label.
+   * Falls back to `avatar` if not provided.
+   */
+  icon?: ReactNode;
+
+  /**
+   * Leading avatar — alternative to `icon`, typically a small
+   * circular image (Avatar component or `<img>`). When BOTH `icon`
+   * and `avatar` are set, `avatar` wins (matches MUI behaviour).
+   */
+  avatar?: ReactNode;
+
+  /**
+   * Makes the chip interactive — renders as `<button>` (instead of
+   * `<span>`), adds focus ring + hover state. Set automatically to
+   * `true` when `onClick` is provided.
+   */
+  clickable?: boolean;
+
+  /**
+   * Click handler. Implies `clickable=true`. Fires on chip-body
+   * click (NOT on the delete button — `onDelete` is the dedicated
+   * path for that).
+   */
+  onClick?: (event: React.MouseEvent<HTMLElement>) => void;
+
+  /**
+   * When set, renders a trailing × delete button. The handler fires
+   * on delete-button click and stops propagation so the chip's
+   * `onClick` doesn't also fire.
+   */
+  onDelete?: (event: React.MouseEvent<HTMLElement>) => void;
+
+  /**
+   * Custom delete icon. Defaults to an inline stroke-style × SVG.
+   * `currentColor` flows through, so the icon inherits the chip's
+   * text colour.
+   */
+  deleteIcon?: ReactNode;
+
+  /**
+   * `aria-label` for the delete button. Required for screen readers
+   * since the × glyph alone is not semantic.
+   * @default 'Remove'
+   */
+  deleteLabel?: string;
+
+  /**
+   * Reactive visibility predicate. Re-evaluated on every engine state
+   * change when the chip 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`
+   * — same contract as `<Alert>` / `<TextField>` / other bridge-aware
+   * components. Useful for status chips that should appear / disappear
+   * based on form values without forcing JSX guards on the consumer.
+   *
+   * @example
+   * ```tsx
+   * // Inside a DashForm — engine-reactive
+   * <Chip
+   *   label="Premium"
+   *   color="primary"
+   *   visibleWhen={(engine) => engine.getNode('plan')?.value === 'premium'}
+   * />
+   *
+   * // Outside a form — closure over external state
+   * <Chip
+   *   label={`${count} results`}
+   *   visibleWhen={() => count > 0}
+   * />
+   * ```
+   */
+  visibleWhen?: (engine: Engine) => boolean;
+
+  /**
+   * RBAC requirement. Same contract as `<Button>` / `<IconButton>` —
+   * `onUnauthorized: 'hide' | 'disable' | 'readonly'`.
+   * (`readonly` maps to `disabled` for chips, matching Button.)
+   */
+  access?: AccessRequirement;
+
+  /**
+   * Root-element class shortcut (string or clsx-compatible value).
+   * Last-wins via `tailwind-merge` inside `cn()`.
+   */
+  sx?: ClassValue;
+
+  /** Standard React `className` — appended to the root via `cn()`. */
+  className?: string;
+}