@dashforge/tw 0.1.0-beta

package/src/components/Breadcrumbs/Breadcrumbs.tsx

@@ -0,0 +1,203 @@
+import { Fragment, useMemo } from 'react';
+import { cn } from '../../utils/cn.js';
+import { breadcrumbsVariants } from './breadcrumbs.variants.js';
+import type {
+  BreadcrumbItem,
+  BreadcrumbsProps,
+} from './breadcrumbs.types.js';
+
+/**
+ * Dashforge TW Breadcrumbs — router-agnostic navigation trail.
+ *
+ * Pure presentational. The consumer derives `items` from their routing
+ * layer (no automatic location read) — that keeps the component usable
+ * with React Router, Next.js App Router, TanStack Router, Wouter, etc.
+ *
+ * Truncation policy: when `items.length > maxItems > 0`, the middle is
+ * collapsed into a non-interactive `…` placeholder. `itemsBeforeCollapse`
+ * (default 1) and `itemsAfterCollapse` (default 1) control how many
+ * crumbs survive at each end — set both to 0 to keep only first+last,
+ * or higher to preserve more context.
+ *
+ * **A11y**:
+ *   - `<nav aria-label="Breadcrumb">` landmark
+ *   - `<ol>` semantic list (screen readers announce position-in-list)
+ *   - `aria-current="page"` on the last (or `current: true`) crumb
+ *   - Separator nodes carry `aria-hidden="true"` (decorative)
+ *   - The truncation ellipsis is a `<span aria-label="More breadcrumbs">`
+ */
+export function Breadcrumbs(props: BreadcrumbsProps) {
+  const {
+    items,
+    separator = '/',
+    maxItems = 0,
+    itemsBeforeCollapse = 1,
+    itemsAfterCollapse = 1,
+    size,
+    slotProps,
+    sx,
+    linkComponent: Link = 'a' as unknown as React.ComponentType<
+      React.AnchorHTMLAttributes<HTMLAnchorElement>
+    >,
+    ariaLabel = 'Breadcrumb',
+  } = props;
+
+  const v = breadcrumbsVariants({ size });
+
+  /**
+   * Decide which items survive after truncation. Returns the rendered
+   * list interleaved with a sentinel for the collapsed gap (when
+   * truncation kicks in).
+   *
+   * Sentinel marker: `'__ELLIPSIS__'` — chosen instead of `null` so the
+   * map/render loop can distinguish a "gap" from a regular crumb
+   * without an instance-of dance.
+   */
+  type RenderEntry =
+    | { kind: 'item'; item: BreadcrumbItem; idx: number; isLast: boolean }
+    | { kind: 'ellipsis' };
+
+  const entries = useMemo<RenderEntry[]>(() => {
+    const lastIdx = items.length - 1;
+    const shouldCollapse = maxItems > 0 && items.length > maxItems;
+
+    const toEntry = (item: BreadcrumbItem, idx: number): RenderEntry => ({
+      kind: 'item',
+      item,
+      idx,
+      isLast: idx === lastIdx,
+    });
+
+    if (!shouldCollapse) {
+      return items.map(toEntry);
+    }
+
+    const before = Math.max(0, itemsBeforeCollapse);
+    const after = Math.max(0, itemsAfterCollapse);
+    // Edge case: if before+after >= items.length, no point collapsing.
+    if (before + after >= items.length) {
+      return items.map(toEntry);
+    }
+    const head = items.slice(0, before).map(toEntry);
+    const tail = items
+      .slice(items.length - after)
+      .map((item, j) => toEntry(item, items.length - after + j));
+    return [...head, { kind: 'ellipsis' as const }, ...tail];
+  }, [items, maxItems, itemsBeforeCollapse, itemsAfterCollapse]);
+
+  if (items.length === 0) return null;
+
+  return (
+    <nav
+      aria-label={ariaLabel}
+      className={cn(v.root(), sx, slotProps?.root?.className)}
+    >
+      <ol className={cn(v.list(), slotProps?.list?.className)}>
+        {entries.map((entry, i) => {
+          // Trailing-separator policy: every entry EXCEPT the last one
+          // is followed by a separator. We render both inside the same
+          // <li> for visual cohesion; aria-hidden on the separator keeps
+          // the SR announcement clean.
+          const isLastEntry = i === entries.length - 1;
+
+          if (entry.kind === 'ellipsis') {
+            return (
+              <li
+                key="__ellipsis__"
+                className={cn(v.item(), slotProps?.item?.className)}
+              >
+                <span
+                  aria-label="More breadcrumbs"
+                  className={cn(
+                    v.ellipsis(),
+                    slotProps?.ellipsis?.className
+                  )}
+                >
+                  …
+                </span>
+                {!isLastEntry && (
+                  <span
+                    aria-hidden="true"
+                    className={cn(
+                      v.separator(),
+                      slotProps?.separator?.className
+                    )}
+                  >
+                    {separator}
+                  </span>
+                )}
+              </li>
+            );
+          }
+
+          const { item, isLast } = entry;
+          // A crumb is "current" if explicitly flagged OR it's the last
+          // crumb (sensible default — matches the WAI-ARIA pattern).
+          const isCurrent = Boolean(item.current) || isLast;
+          // Interactive only when there's a way to navigate AND the
+          // crumb is not the current page AND not disabled.
+          const isInteractive =
+            !isCurrent &&
+            !item.disabled &&
+            (item.href !== undefined || item.onClick !== undefined);
+
+          return (
+            <li
+              key={item.id}
+              className={cn(v.item(), slotProps?.item?.className)}
+            >
+              {isInteractive ? (
+                <Link
+                  href={item.href}
+                  onClick={item.onClick}
+                  className={cn(v.link(), slotProps?.link?.className)}
+                >
+                  {item.icon ? (
+                    <Fragment>
+                      <span aria-hidden="true">{item.icon}</span>
+                      {item.label}
+                    </Fragment>
+                  ) : (
+                    item.label
+                  )}
+                </Link>
+              ) : (
+                <span
+                  aria-current={isCurrent ? 'page' : undefined}
+                  aria-disabled={item.disabled || undefined}
+                  className={cn(
+                    isCurrent ? v.current() : v.link(),
+                    isCurrent
+                      ? slotProps?.current?.className
+                      : slotProps?.link?.className
+                  )}
+                >
+                  {item.icon ? (
+                    <Fragment>
+                      <span aria-hidden="true">{item.icon}</span>
+                      {item.label}
+                    </Fragment>
+                  ) : (
+                    item.label
+                  )}
+                </span>
+              )}
+
+              {!isLastEntry && (
+                <span
+                  aria-hidden="true"
+                  className={cn(
+                    v.separator(),
+                    slotProps?.separator?.className
+                  )}
+                >
+                  {separator}
+                </span>
+              )}
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}

package/src/components/Breadcrumbs/breadcrumbs.types.ts

@@ -0,0 +1,87 @@
+import type { ReactNode, ComponentType, AnchorHTMLAttributes } from 'react';
+import type { BreadcrumbsVariants } from './breadcrumbs.variants.js';
+
+/**
+ * A single crumb in the trail.
+ *
+ * - `label` is the visible text (or any React node).
+ * - `href` makes it a navigation link. Omit for a non-link crumb (e.g.,
+ *   the current page).
+ * - `onClick` is fired in addition to (or instead of) `href`; useful
+ *   when the consumer wants to intercept SPA navigation.
+ * - `current: true` flags the LAST crumb as the active page; gets
+ *   `aria-current="page"` and is rendered as plain text (no link).
+ */
+export interface BreadcrumbItem {
+  /** Stable key for React reconciliation + accessibility id. */
+  id: string;
+  label: ReactNode;
+  href?: string;
+  onClick?: (event: React.MouseEvent) => void;
+  current?: boolean;
+  /** Per-item disabled flag — renders as plain text, no interaction. */
+  disabled?: boolean;
+  /** Optional icon prepended to the label. */
+  icon?: ReactNode;
+}
+
+export interface BreadcrumbsSlotProps {
+  root?: { className?: string };
+  list?: { className?: string };
+  item?: { className?: string };
+  link?: { className?: string };
+  current?: { className?: string };
+  separator?: { className?: string };
+  ellipsis?: { className?: string };
+}
+
+/**
+ * Polymorphic link component prop. Defaults to the native `<a>`.
+ *
+ * Pass a router-aware component (e.g., `react-router-dom`'s `Link`,
+ * Next's `Link`) for SPA navigation. The component must accept
+ * `href` (or its router-equivalent — bring your own adapter) plus
+ * standard anchor props (className, onClick, children, ref).
+ */
+export type BreadcrumbLinkComponent = ComponentType<
+  AnchorHTMLAttributes<HTMLAnchorElement> & { ref?: React.Ref<HTMLAnchorElement> }
+>;
+
+/**
+ * Props for `<Breadcrumbs>`.
+ *
+ * Renders a router-agnostic navigation trail. Bridge-free — pure
+ * presentational, accepts a fully-resolved item list from the consumer
+ * (typically derived from route metadata).
+ *
+ * **Truncation**: when `items.length > maxItems`, the middle crumbs
+ * collapse into an ellipsis (`…`). Always preserved: first + last
+ * crumb. Tunable via `itemsBeforeCollapse` / `itemsAfterCollapse` for
+ * asymmetric trails (defaults: 1 + 1).
+ */
+export interface BreadcrumbsProps extends BreadcrumbsVariants {
+  items: BreadcrumbItem[];
+  /** Separator node between crumbs. @default '/' */
+  separator?: ReactNode;
+  /**
+   * Max crumbs to show before collapsing the middle. `0` / negative ⇒
+   * never collapse. @default 0
+   */
+  maxItems?: number;
+  /**
+   * Crumbs preserved at the START when collapsed. @default 1
+   */
+  itemsBeforeCollapse?: number;
+  /**
+   * Crumbs preserved at the END when collapsed. @default 1
+   */
+  itemsAfterCollapse?: number;
+  /** Per-slot className overrides. */
+  slotProps?: BreadcrumbsSlotProps;
+  /** Root className shortcut. */
+  sx?: string;
+  /** Override the link component (router integration). @default 'a' */
+  linkComponent?: BreadcrumbLinkComponent;
+  /** Visible label of the nav landmark. @default 'Breadcrumb' */
+  ariaLabel?: string;
+}

package/src/components/Breadcrumbs/breadcrumbs.variants.ts

@@ -0,0 +1,49 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * Tailwind-variants recipe for `<Breadcrumbs>`.
+ *
+ * Slots:
+ *   - `root`       — `<nav>` landmark
+ *   - `list`       — flex `<ol>`
+ *   - `item`       — `<li>` wrapper
+ *   - `link`       — non-current crumb (clickable / focusable)
+ *   - `current`    — last crumb (no link, aria-current="page")
+ *   - `separator`  — between-crumbs marker
+ *   - `ellipsis`   — collapsed-middle placeholder (`…`)
+ */
+export const breadcrumbsVariants = tv({
+  slots: {
+    root: 'text-sm text-neutral-600',
+    list: 'flex items-center flex-wrap gap-1',
+    item: 'inline-flex items-center gap-1 min-w-0',
+    link: [
+      'inline-flex items-center gap-1 truncate',
+      'text-neutral-600 hover:text-primary-700',
+      'rounded-sm outline-none',
+      'focus-visible:ring-2 focus-visible:ring-primary-500/50',
+      'transition-colors',
+    ],
+    current: [
+      'inline-flex items-center gap-1 truncate',
+      'text-neutral-900 font-medium',
+    ],
+    separator: 'text-neutral-400 select-none mx-0.5',
+    ellipsis: [
+      'inline-flex items-center justify-center px-1',
+      'text-neutral-500 cursor-default select-none',
+    ],
+  },
+  variants: {
+    size: {
+      sm: { root: 'text-xs', list: 'gap-0.5', separator: 'mx-0' },
+      md: { root: 'text-sm' },
+      lg: { root: 'text-base', list: 'gap-1.5' },
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+});
+
+export type BreadcrumbsVariants = VariantProps<typeof breadcrumbsVariants>;

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

@@ -0,0 +1,183 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/react';
+import { RbacProvider } from '@dashforge/rbac';
+import type { RbacPolicy, Subject } from '@dashforge/rbac';
+import { Button } from './Button.js';
+
+const READ_ONLY_POLICY: RbacPolicy = {
+  roles: [
+    {
+      name: 'viewer',
+      permissions: [
+        { resource: 'doc', action: 'read', effect: 'allow' },
+        { resource: 'doc', action: 'delete', effect: 'deny' },
+      ],
+    },
+  ],
+};
+const viewer: Subject = { id: 'v', roles: ['viewer'] };
+
+describe('Button — basic rendering', () => {
+  it('renders children inside a <button>', () => {
+    const { getByText } = render(<Button>Save</Button>);
+    const node = getByText('Save');
+    expect(node.tagName).toBe('BUTTON');
+  });
+
+  it('defaults type="button" (not "submit")', () => {
+    const { getByText } = render(<Button>Save</Button>);
+    expect((getByText('Save') as HTMLButtonElement).type).toBe('button');
+  });
+
+  it('forwards type="submit" when supplied', () => {
+    const { getByText } = render(<Button type="submit">Send</Button>);
+    expect((getByText('Send') as HTMLButtonElement).type).toBe('submit');
+  });
+
+  it('fires onClick when clicked', () => {
+    const onClick = vi.fn();
+    const { getByText } = render(<Button onClick={onClick}>Hit</Button>);
+    fireEvent.click(getByText('Hit'));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('Button — variant classes', () => {
+  it('applies the solid + primary default classes', () => {
+    const { getByText } = render(<Button>X</Button>);
+    const cls = getByText('X').className;
+    expect(cls).toContain('bg-primary-500');
+    expect(cls).toContain('inline-flex'); // base
+    expect(cls).toContain('h-10'); // size=md default
+  });
+
+  it('switches color palette on `color="danger"`', () => {
+    const { getByText } = render(<Button color="danger">X</Button>);
+    const cls = getByText('X').className;
+    expect(cls).toContain('bg-danger-500');
+    expect(cls).not.toContain('bg-primary-500');
+  });
+
+  it('outline variant uses border + text-{color}-700', () => {
+    const { getByText } = render(<Button variant="outline" color="success">X</Button>);
+    const cls = getByText('X').className;
+    expect(cls).toContain('border-success-500');
+    expect(cls).toContain('text-success-700');
+  });
+
+  it('size sm/lg map to h-8/h-12', () => {
+    const { getByText: small } = render(<Button size="sm">S</Button>);
+    expect(small('S').className).toContain('h-8');
+    const { getByText: large } = render(<Button size="lg">L</Button>);
+    expect(large('L').className).toContain('h-12');
+  });
+
+  it('fullWidth adds w-full', () => {
+    const { getByText } = render(<Button fullWidth>X</Button>);
+    expect(getByText('X').className).toContain('w-full');
+  });
+});
+
+describe('Button — override (sx wins via tailwind-merge)', () => {
+  it('sx is appended after variant classes', () => {
+    const { getByText } = render(<Button sx="ml-4">X</Button>);
+    expect(getByText('X').className).toContain('ml-4');
+  });
+
+  it('sx overrides a conflicting variant class via tailwind-merge', () => {
+    // variant produces `bg-primary-500`; sx forces `bg-red-500` — must win.
+    const { getByText } = render(<Button sx="bg-red-500">X</Button>);
+    const cls = getByText('X').className;
+    expect(cls).toContain('bg-red-500');
+    expect(cls).not.toContain('bg-primary-500');
+  });
+});
+
+describe('Button — loading state', () => {
+  it('disables the button and shows the spinner', () => {
+    const { getByText, container } = render(<Button loading>Save</Button>);
+    expect((getByText('Save').parentElement as HTMLButtonElement)?.disabled || (getByText('Save') as HTMLButtonElement).disabled).toBe(true);
+    expect(container.querySelector('svg')).not.toBeNull();
+  });
+
+  it('does not fire onClick when loading (disabled native attr)', () => {
+    const onClick = vi.fn();
+    const { getByText } = render(<Button loading onClick={onClick}>Save</Button>);
+    fireEvent.click(getByText('Save'));
+    expect(onClick).not.toHaveBeenCalled();
+  });
+});
+
+describe('Button — RBAC', () => {
+  function withRbac(children: React.ReactNode) {
+    return (
+      <RbacProvider policy={READ_ONLY_POLICY} subject={viewer}>
+        {children}
+      </RbacProvider>
+    );
+  }
+
+  it('renders normally when no access prop is supplied', () => {
+    const { getByText } = render(withRbac(<Button>X</Button>));
+    expect(getByText('X')).toBeTruthy();
+  });
+
+  it('hides when access denies with onUnauthorized=hide', () => {
+    const { queryByText } = render(
+      withRbac(
+        <Button access={{ resource: 'doc', action: 'delete', onUnauthorized: 'hide' }}>
+          Delete
+        </Button>
+      )
+    );
+    expect(queryByText('Delete')).toBeNull();
+  });
+
+  it('disables when access denies with onUnauthorized=disable', () => {
+    const { getByText } = render(
+      withRbac(
+        <Button access={{ resource: 'doc', action: 'delete', onUnauthorized: 'disable' }}>
+          Delete
+        </Button>
+      )
+    );
+    expect((getByText('Delete') as HTMLButtonElement).disabled).toBe(true);
+  });
+
+  it('disables (fallback) when access denies with onUnauthorized=readonly', () => {
+    const { getByText } = render(
+      withRbac(
+        <Button access={{ resource: 'doc', action: 'delete', onUnauthorized: 'readonly' }}>
+          Delete
+        </Button>
+      )
+    );
+    expect((getByText('Delete') as HTMLButtonElement).disabled).toBe(true);
+  });
+});
+
+describe('Button — asChild polymorphism', () => {
+  it('renders the child element with the Button class merged in', () => {
+    const { getByText } = render(
+      <Button asChild variant="solid" color="primary">
+        <a href="/dashboard">Open</a>
+      </Button>
+    );
+    const node = getByText('Open');
+    expect(node.tagName).toBe('A');
+    expect((node as HTMLAnchorElement).getAttribute('href')).toBe('/dashboard');
+    expect(node.className).toContain('bg-primary-500');
+  });
+
+  it('sets data-disabled + aria-disabled when effectiveDisabled', () => {
+    const { getByText } = render(
+      <Button asChild disabled>
+        <a href="/x">X</a>
+      </Button>
+    );
+    const node = getByText('X');
+    expect(node.getAttribute('data-disabled')).toBe('true');
+    expect(node.getAttribute('aria-disabled')).toBe('true');
+  });
+});

package/src/components/Button/Button.tsx

@@ -0,0 +1,139 @@
+import { forwardRef } from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cn } from '../../utils/cn.js';
+import { useAccessState } from '../../hooks/useAccessState.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.
+ *
+ * @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>
+  );
+}
+
+/**
+ * Dashforge TW Button — action component with RBAC support.
+ *
+ * Mirrors the public contract of the MUI-side
+ * `@dashforge/ui/Button` (RBAC behaviour identical) while rendering
+ * through Tailwind classes + the `dashforgePreset` color scales. Like
+ * the MUI version, this is NOT a form field — there is no bridge
+ * integration and no `DashFormContext` consumption.
+ *
+ * **`asChild`** mirrors the shadcn/Radix pattern: when set, the
+ * immediate child element receives the Button's resolved className
+ * and the Button DOM is not emitted. Useful for router Links, anchor
+ * tags, or any element that should look like a button without
+ * nesting one inside it.
+ *
+ * **Override precedence**: `sx` wins over variant classes via
+ * `tailwind-merge` inside `cn()`. Variants win over the `base` class
+ * group (TV's `compoundVariants` handle color×variant combos
+ * explicitly).
+ *
+ * @example
+ * ```tsx
+ * <Button onClick={onSave}>Save</Button>
+ *
+ * <Button variant="outline" color="danger" size="lg" sx="ml-4">
+ *   Delete
+ * </Button>
+ *
+ * <Button asChild variant="solid" color="primary">
+ *   <Link to="/dashboard">Open Dashboard</Link>
+ * </Button>
+ *
+ * <Button
+ *   loading
+ *   access={{ resource: 'article', action: 'publish', onUnauthorized: 'disable' }}
+ *   onClick={onPublish}
+ * >
+ *   Publish
+ * </Button>
+ * ```
+ */
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  props,
+  ref
+) {
+  const {
+    access,
+    disabled,
+    variant,
+    color,
+    size,
+    fullWidth,
+    loading,
+    asChild,
+    sx,
+    children,
+    ...rest
+  } = props;
+
+  // RBAC always called unconditionally (rules-of-hooks compliance).
+  const accessState = useAccessState(access);
+
+  // Early return for hidden state.
+  if (!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
+  // to disabled (matches the MUI-side semantics in @dashforge/ui).
+  const effectiveDisabled =
+    Boolean(disabled) || accessState.disabled || accessState.readonly || Boolean(loading);
+
+  const classes = cn(
+    buttonVariants({ variant, color, size, fullWidth, loading }),
+    sx
+  );
+
+  // `asChild` renders through Radix Slot: the immediate child element
+  // gets the resolved className, no extra Button DOM is emitted.
+  if (asChild) {
+    return (
+      <Slot
+        ref={ref}
+        className={classes}
+        data-disabled={effectiveDisabled || undefined}
+        aria-disabled={effectiveDisabled || undefined}
+      >
+        {children}
+      </Slot>
+    );
+  }
+
+  return (
+    <button
+      ref={ref}
+      type={rest.type ?? 'button'}
+      disabled={effectiveDisabled}
+      className={classes}
+      {...rest}
+    >
+      {loading && <LoadingSpinner size={size ?? 'md'} />}
+      {children}
+    </button>
+  );
+});