@dashforge/tw 1.0.0 → 1.1.1

package/src/components/Breadcrumbs/Breadcrumbs.tsx

@@ -1,203 +0,0 @@
-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

@@ -1,87 +0,0 @@
-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

@@ -1,54 +0,0 @@
-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',
-      // Defensive `no-underline` — see the matching comment in
-      // LeftNav itemLink slot. The Breadcrumbs root cause covers
-      // TopBar too because Breadcrumbs is typically rendered in
-      // TopBar's center slot.
-      'no-underline hover:no-underline',
-    ],
-    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

@@ -1,183 +0,0 @@
-// @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

@@ -1,150 +0,0 @@
-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
-  );
-
-  /*
-   * `aria-busy` announces the loading state to assistive tech.
-   * `disabled` alone hides the reason (perm-denied vs loading vs
-   * intrinsic), so SR users only hear "dimmed/inactive" without
-   * knowing why. Adding `aria-busy={true}` while loading distinguishes
-   * "wait for the action to finish" from "you can't do this".
-   */
-  const ariaBusy = loading ? true : undefined;
-
-  // `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}
-        aria-busy={ariaBusy}
-      >
-        {children}
-      </Slot>
-    );
-  }
-
-  return (
-    <button
-      ref={ref}
-      type={rest.type ?? 'button'}
-      disabled={effectiveDisabled}
-      aria-busy={ariaBusy}
-      className={classes}
-      {...rest}
-    >
-      {loading && <LoadingSpinner size={size ?? 'md'} />}
-      {children}
-    </button>
-  );
-});