@dashforge/tw 1.1.0 → 1.1.1

package/src/components/Badge/Badge.test.tsx

@@ -1,385 +0,0 @@
-// @vitest-environment jsdom
-import * as React from 'react';
-import { describe, it, expect, afterEach } from 'vitest';
-import { render, screen, cleanup } from '@testing-library/react';
-import { RbacProvider } from '@dashforge/rbac';
-import type { RbacPolicy, Subject } from '@dashforge/rbac';
-import { Badge } from './Badge.js';
-
-void React;
-afterEach(() => cleanup());
-
-/**
- * Unit tests for `<Badge>`. Covers:
- *   - Content resolution (number, string, max overflow, showZero)
- *   - Dot mode
- *   - Placement (4 corners — sample 2)
- *   - Overlap (rectangular vs circular)
- *   - Color (7 intents — sample 3)
- *   - withRing toggle
- *   - invisible toggle (in DOM but hidden)
- *   - Access RBAC (hide vs always-show anchor)
- *   - visibleWhen predicate
- *   - Anchor children always render
- *   - Aria-hidden on badge slot
- */
-
-const NO_ACCESS_POLICY: RbacPolicy = {
-  roles: [{ name: 'guest', permissions: [] }],
-};
-const ADMIN_POLICY: RbacPolicy = {
-  roles: [
-    {
-      name: 'admin',
-      permissions: [{ resource: '*', action: '*', effect: 'allow' }],
-    },
-  ],
-};
-const guestSubject: Subject = { id: 'g', roles: ['guest'] };
-const adminSubject: Subject = { id: 'a', roles: ['admin'] };
-
-describe('<Badge>', () => {
-  describe('content resolution', () => {
-    it('renders numeric content', () => {
-      render(
-        <Badge content={3}>
-          <button>anchor</button>
-        </Badge>
-      );
-      expect(screen.getByText('3')).toBeTruthy();
-    });
-
-    it('renders string content verbatim', () => {
-      render(
-        <Badge content="NEW">
-          <button>anchor</button>
-        </Badge>
-      );
-      expect(screen.getByText('NEW')).toBeTruthy();
-    });
-
-    it('renders nothing when content omitted + no dot', () => {
-      const { container } = render(
-        <Badge>
-          <button>anchor</button>
-        </Badge>
-      );
-      // Anchor present, no badge element
-      expect(screen.getByText('anchor')).toBeTruthy();
-      expect(container.querySelector('[aria-hidden="true"]')).toBeNull();
-    });
-
-    it('hides badge when content=0 and showZero=false (default)', () => {
-      const { container } = render(
-        <Badge content={0}>
-          <button>anchor</button>
-        </Badge>
-      );
-      expect(container.querySelector('[aria-hidden="true"]')).toBeNull();
-    });
-
-    it('shows badge when content=0 and showZero=true', () => {
-      render(
-        <Badge content={0} showZero>
-          <button>anchor</button>
-        </Badge>
-      );
-      expect(screen.getByText('0')).toBeTruthy();
-    });
-  });
-
-  describe('max overflow', () => {
-    it('renders raw number when below max', () => {
-      render(
-        <Badge content={50} max={99}>
-          <button>anchor</button>
-        </Badge>
-      );
-      expect(screen.getByText('50')).toBeTruthy();
-    });
-
-    it('renders "99+" when above default max=99', () => {
-      render(
-        <Badge content={1284}>
-          <button>anchor</button>
-        </Badge>
-      );
-      expect(screen.getByText('99+')).toBeTruthy();
-    });
-
-    it('respects custom max', () => {
-      render(
-        <Badge content={1284} max={999}>
-          <button>anchor</button>
-        </Badge>
-      );
-      expect(screen.getByText('999+')).toBeTruthy();
-    });
-
-    it('disables overflow when max=-1', () => {
-      render(
-        <Badge content={1284} max={-1}>
-          <button>anchor</button>
-        </Badge>
-      );
-      expect(screen.getByText('1284')).toBeTruthy();
-    });
-  });
-
-  describe('dot mode', () => {
-    it('renders a dot (w-2 h-2) when dot=true', () => {
-      const { container } = render(
-        <Badge dot>
-          <button>anchor</button>
-        </Badge>
-      );
-      const badge = container.querySelector('[aria-hidden="true"]')!;
-      expect(badge).toBeTruthy();
-      expect(badge.className).toContain('w-2');
-      expect(badge.className).toContain('h-2');
-    });
-
-    it('ignores content when dot=true', () => {
-      render(
-        <Badge dot content={5}>
-          <button>anchor</button>
-        </Badge>
-      );
-      // Badge present but no "5" text
-      expect(screen.queryByText('5')).toBeNull();
-    });
-  });
-
-  describe('color axis', () => {
-    it('default color=danger → bg-danger-500', () => {
-      const { container } = render(
-        <Badge content={1}>
-          <button>x</button>
-        </Badge>
-      );
-      const badge = container.querySelector('[aria-hidden="true"]')!;
-      expect(badge.className).toContain('bg-danger-500');
-    });
-
-    it('color=success → bg-success-500', () => {
-      const { container } = render(
-        <Badge content={1} color="success">
-          <button>x</button>
-        </Badge>
-      );
-      const badge = container.querySelector('[aria-hidden="true"]')!;
-      expect(badge.className).toContain('bg-success-500');
-    });
-
-    it('color=neutral uses auto-inverting neutral tokens (no dark:)', () => {
-      const { container } = render(
-        <Badge content={1} color="neutral">
-          <button>x</button>
-        </Badge>
-      );
-      const badge = container.querySelector('[aria-hidden="true"]')!;
-      expect(badge.className).toContain('bg-neutral-700');
-      expect(badge.className).toContain('text-neutral-50');
-      expect(badge.className).not.toMatch(/\bdark:/);
-    });
-  });
-
-  describe('placement axis', () => {
-    it('default placement=top-right → top-0 right-0', () => {
-      const { container } = render(
-        <Badge content={1}>
-          <button>x</button>
-        </Badge>
-      );
-      const badge = container.querySelector('[aria-hidden="true"]')!;
-      expect(badge.className).toContain('top-0');
-      expect(badge.className).toContain('right-0');
-    });
-
-    it('placement=bottom-left → bottom-0 left-0', () => {
-      const { container } = render(
-        <Badge content={1} placement="bottom-left">
-          <button>x</button>
-        </Badge>
-      );
-      const badge = container.querySelector('[aria-hidden="true"]')!;
-      expect(badge.className).toContain('bottom-0');
-      expect(badge.className).toContain('left-0');
-    });
-  });
-
-  describe('overlap axis', () => {
-    it('default overlap=rectangular → no circular inset class', () => {
-      const { container } = render(
-        <Badge content={1}>
-          <button>x</button>
-        </Badge>
-      );
-      const badge = container.querySelector('[aria-hidden="true"]')!;
-      // No `top-[14%]` / `right-[14%]` inset for rectangular
-      expect(badge.className).not.toContain('top-[14%]');
-    });
-
-    it('overlap=circular adds the 14% inset', () => {
-      const { container } = render(
-        <Badge content={1} overlap="circular">
-          <button>x</button>
-        </Badge>
-      );
-      const badge = container.querySelector('[aria-hidden="true"]')!;
-      expect(badge.className).toContain('top-[14%]');
-      expect(badge.className).toContain('right-[14%]');
-    });
-  });
-
-  describe('withRing', () => {
-    it('default withRing=true → ring-2 ring-neutral-50', () => {
-      const { container } = render(
-        <Badge content={1}>
-          <button>x</button>
-        </Badge>
-      );
-      const badge = container.querySelector('[aria-hidden="true"]')!;
-      expect(badge.className).toContain('ring-2');
-      expect(badge.className).toContain('ring-neutral-50');
-    });
-
-    it('withRing=false → no ring class', () => {
-      const { container } = render(
-        <Badge content={1} withRing={false}>
-          <button>x</button>
-        </Badge>
-      );
-      const badge = container.querySelector('[aria-hidden="true"]')!;
-      expect(badge.className).not.toContain('ring-2');
-    });
-  });
-
-  describe('invisible', () => {
-    it('keeps badge in DOM but hidden when invisible=true', () => {
-      const { container } = render(
-        <Badge content={5} invisible>
-          <button>x</button>
-        </Badge>
-      );
-      const badge = container.querySelector('[aria-hidden="true"]')!;
-      expect(badge).toBeTruthy();
-      expect(badge.className).toContain('hidden');
-    });
-  });
-
-  describe('access RBAC', () => {
-    it('hides the badge for unauthorized subjects (anchor still visible)', () => {
-      const { container } = render(
-        <RbacProvider policy={NO_ACCESS_POLICY} subject={guestSubject}>
-          <Badge
-            content={5}
-            access={{
-              resource: 'admin',
-              action: 'read',
-              onUnauthorized: 'hide',
-            }}
-          >
-            <button>anchor</button>
-          </Badge>
-        </RbacProvider>
-      );
-      // Anchor renders
-      expect(screen.getByText('anchor')).toBeTruthy();
-      // Badge does not
-      expect(container.querySelector('[aria-hidden="true"]')).toBeNull();
-    });
-
-    it('shows the badge for authorized subjects', () => {
-      render(
-        <RbacProvider policy={ADMIN_POLICY} subject={adminSubject}>
-          <Badge
-            content={5}
-            access={{
-              resource: 'admin',
-              action: 'read',
-              onUnauthorized: 'hide',
-            }}
-          >
-            <button>anchor</button>
-          </Badge>
-        </RbacProvider>
-      );
-      expect(screen.getByText('5')).toBeTruthy();
-    });
-  });
-
-  describe('visibleWhen', () => {
-    it('renders when predicate returns true', () => {
-      render(
-        <Badge content={5} visibleWhen={() => true}>
-          <button>x</button>
-        </Badge>
-      );
-      expect(screen.getByText('5')).toBeTruthy();
-    });
-
-    it('hides badge (not anchor) when predicate returns false', () => {
-      const { container } = render(
-        <Badge content={5} visibleWhen={() => false}>
-          <button>anchor</button>
-        </Badge>
-      );
-      // Anchor still rendered
-      expect(screen.getByText('anchor')).toBeTruthy();
-      // Badge not
-      expect(container.querySelector('[aria-hidden="true"]')).toBeNull();
-    });
-  });
-
-  describe('anchor always renders', () => {
-    it('renders children even when badge is hidden via showZero', () => {
-      render(
-        <Badge content={0}>
-          <button data-testid="anchor">anchor</button>
-        </Badge>
-      );
-      expect(screen.getByTestId('anchor')).toBeTruthy();
-    });
-
-    it('renders children even when access denies badge', () => {
-      render(
-        <RbacProvider policy={NO_ACCESS_POLICY} subject={guestSubject}>
-          <Badge
-            content={5}
-            access={{
-              resource: 'admin',
-              action: 'read',
-              onUnauthorized: 'hide',
-            }}
-          >
-            <button data-testid="anchor">anchor</button>
-          </Badge>
-        </RbacProvider>
-      );
-      expect(screen.getByTestId('anchor')).toBeTruthy();
-    });
-  });
-
-  describe('overrides — sx + className + slotProps', () => {
-    it('appends sx to the root', () => {
-      const { container } = render(
-        <Badge content={1} sx="ring-4 ring-purple-500">
-          <button>x</button>
-        </Badge>
-      );
-      const root = container.firstElementChild!;
-      expect(root.className).toContain('ring-purple-500');
-    });
-
-    it('appends slotProps.badge.className to the badge', () => {
-      const { container } = render(
-        <Badge content={1} slotProps={{ badge: { className: 'custom-badge-cls' } }}>
-          <button>x</button>
-        </Badge>
-      );
-      const badge = container.querySelector('[aria-hidden="true"]')!;
-      expect(badge.className).toContain('custom-badge-cls');
-    });
-  });
-});

package/src/components/Badge/Badge.tsx

@@ -1,174 +0,0 @@
-import { forwardRef, useContext } from 'react';
-import { DashFormContext, useEngineVisibility } from '@dashforge/ui-core';
-import { cn } from '../../utils/cn.js';
-import { useAccessState } from '../../hooks/useAccessState.js';
-import { badgeVariants } from './badge.variants.js';
-import type { BadgeProps } from './badge.types.js';
-
-/**
- * Resolve the displayed badge content based on `content`, `max`, and
- * `showZero` props.
- *
- * Returns `null` when nothing should render (omitted content + no dot,
- * or `content=0` without `showZero`). Otherwise returns the string
- * to display (formatted overflow for numbers above `max`).
- *
- * @internal
- */
-function resolveDisplayContent(
-  content: number | string | undefined,
-  max: number,
-  showZero: boolean,
-  dot: boolean
-): string | null {
-  // Dot mode — content is irrelevant, badge always shows (unless
-  // gated by visibleWhen / access / invisible higher up).
-  if (dot) return '';
-
-  // No content + no dot → nothing to render.
-  if (content === undefined || content === null) return null;
-
-  // Numeric content — apply max overflow + showZero gate.
-  if (typeof content === 'number') {
-    if (content === 0 && !showZero) return null;
-    if (max >= 0 && content > max) return `${max}+`;
-    return String(content);
-  }
-
-  // String content — render verbatim. Empty string → hide
-  // (counts as "no content" — consumer should pass `dot` for plain dot).
-  return content === '' ? null : content;
-}
-
-/**
- * `<Badge>` — anchored indicator overlaying an anchor element.
- *
- * Common patterns:
- *   - Notification count on a bell IconButton
- *   - Presence dot on an Avatar
- *   - "NEW" label on a Card or feature tile
- *   - Unsaved-changes indicator on a save button
- *
- * For inline standalone pills (status labels, tags, removable
- * chips), use `<Chip>` instead — Chip and Badge are complementary
- * primitives. Chip is interactive (`onClick`, `onDelete`,
- * `selected`); Badge is passive overlay.
- *
- * Bridge integration (Sprint 4.4):
- *   - `access` — hide the badge for unauthorized subjects (anchor
- *     stays visible; wrap anchor in a separate Box `access` to gate
- *     it too)
- *   - `visibleWhen` — engine-reactive predicate
- *
- * The wrapped anchor element ALWAYS renders; only the floating
- * badge dot/count is gated by `access`, `visibleWhen`, `invisible`,
- * and content-resolution logic.
- *
- * @example
- * ```tsx
- * // Notification count on bell
- * <Badge content={unreadCount}>
- *   <IconButton aria-label="Notifications" variant="ghost">
- *     <BellIcon />
- *   </IconButton>
- * </Badge>
- *
- * // Presence dot on avatar
- * <Badge dot color="success" overlap="circular">
- *   <Avatar name="Maya Rodriguez" />
- * </Badge>
- *
- * // Overflow
- * <Badge content={1284} max={999}>
- *   <IconButton aria-label="Messages"><MailIcon /></IconButton>
- * </Badge>
- *
- * // RBAC-gated
- * <Badge
- *   content={adminQueueCount}
- *   access={{ resource: 'admin', action: 'read', onUnauthorized: 'hide' }}
- * >
- *   <IconButton aria-label="Admin queue"><SettingsIcon /></IconButton>
- * </Badge>
- *
- * // Engine-reactive
- * <Badge
- *   dot color="warning"
- *   visibleWhen={(engine) => !!engine.getNode('unsavedChanges')?.value}
- * >
- *   <IconButton aria-label="Save"><SaveIcon /></IconButton>
- * </Badge>
- * ```
- */
-export const Badge = forwardRef<HTMLSpanElement, BadgeProps>(function Badge(
-  props,
-  ref
-) {
-  const {
-    children,
-    content,
-    dot = false,
-    max = 99,
-    showZero = false,
-    invisible = false,
-    color = 'danger',
-    placement = 'top-right',
-    overlap = 'rectangular',
-    withRing = true,
-    access,
-    visibleWhen,
-    sx,
-    className,
-    slotProps,
-  } = props;
-
-  // Bridge — both hooks called unconditionally (rules-of-hooks).
-  const bridge = useContext(DashFormContext);
-  const isBridgeVisible = useEngineVisibility(bridge?.engine, visibleWhen);
-  const accessState = useAccessState(access);
-
-  // Resolve the actual content to render (string or null = hide).
-  // Computed regardless of access/visibleWhen so we can keep the
-  // hook order stable; the final "render or not" check folds them in.
-  const displayContent = resolveDisplayContent(content, max, showZero, dot);
-
-  // The wrapped anchor ALWAYS renders. Only the floating badge is
-  // gated. This is the right contract — gating the anchor too would
-  // belong to a Box `access` wrapper one level up.
-  const shouldRenderBadge =
-    isBridgeVisible &&
-    accessState.visible &&
-    displayContent !== null;
-
-  const v = badgeVariants({
-    dot,
-    invisible,
-    withRing,
-    color,
-    placement,
-    overlap,
-  });
-
-  return (
-    <span
-      ref={ref}
-      className={cn(v.root(), sx, className, slotProps?.root?.className)}
-    >
-      {children}
-      {shouldRenderBadge && (
-        <span
-          className={cn(v.badge(), slotProps?.badge?.className)}
-          // Use `aria-hidden` because the count itself is decorative
-          // — consumers should pair Badge with the anchor's
-          // `aria-label` to convey the count semantically
-          // (e.g., `aria-label="Notifications, 3 unread"`).
-          aria-hidden="true"
-        >
-          {displayContent}
-        </span>
-      )}
-    </span>
-  );
-});
-
-Badge.displayName = 'Badge';