@dashforge/tw 0.4.0-beta → 0.5.0-beta

package/src/components/Pagination/pagination.types.ts

@@ -0,0 +1,117 @@
+import type { PaginationVariants } from './pagination.variants.js';
+
+export interface PaginationSlotProps {
+  root?: { className?: string };
+  summary?: { className?: string };
+  list?: { className?: string };
+  pageButton?: { className?: string };
+  activeButton?: { className?: string };
+  navButton?: { className?: string };
+  ellipsis?: { className?: string };
+  pageSizeSelector?: { className?: string };
+  jumpInput?: { className?: string };
+}
+
+/**
+ * I18n strings for `<Pagination>`. Default = English. Override the
+ * subset you need to translate; the rest fall back to defaults.
+ */
+export interface PaginationLabels {
+  first?: string;
+  prev?: string;
+  next?: string;
+  last?: string;
+  page?: string;
+  of?: string;
+  showing?: string;
+  perPage?: string;
+  goToPage?: string;
+}
+
+/**
+ * Props for `<Pagination>`.
+ *
+ * Controlled component: the consumer owns `page` + `pageSize`. The
+ * component emits `onPageChange` / `onPageSizeChange` and recomputes
+ * the visible page range from `totalCount`.
+ *
+ * @example
+ * ```tsx
+ * const [page, setPage] = useState(1);
+ * const [pageSize, setPageSize] = useState(20);
+ *
+ * <Pagination
+ *   page={page}
+ *   pageSize={pageSize}
+ *   totalCount={1437}
+ *   onPageChange={setPage}
+ *   onPageSizeChange={setPageSize}
+ *   pageSizeOptions={[10, 20, 50, 100]}
+ * />
+ * ```
+ */
+export interface PaginationProps extends Pick<PaginationVariants, 'variant' | 'size'> {
+  /** Current page, **1-indexed**. */
+  page: number;
+
+  /** Items per page. */
+  pageSize: number;
+
+  /** Total items in the underlying data set (NOT total pages — we compute that). */
+  totalCount: number;
+
+  /** Fired when the user picks a different page. */
+  onPageChange: (page: number) => void;
+
+  /**
+   * Fired when the user picks a different page size. Omit (or pass
+   * undefined) to hide the page-size selector.
+   */
+  onPageSizeChange?: (pageSize: number) => void;
+
+  /**
+   * Options shown in the page-size selector.
+   * @default [10, 20, 50, 100]
+   */
+  pageSizeOptions?: number[];
+
+  /**
+   * How many page buttons to show on each side of the current page.
+   * @default 1
+   */
+  siblingCount?: number;
+
+  /**
+   * How many page buttons to always show at the start/end of the
+   * sequence (acts as "boundary"). @default 1
+   */
+  boundaryCount?: number;
+
+  /**
+   * Show first/last buttons (`«` / `»`). @default true
+   */
+  showFirstLast?: boolean;
+
+  /**
+   * Show the direct page-jump input (variant=`default` only).
+   * @default true
+   */
+  showJumpInput?: boolean;
+
+  /**
+   * Disable all interactive elements (kept rendered but inert).
+   */
+  disabled?: boolean;
+
+  /**
+   * I18n strings. Defaults are English; pass the subset you need
+   * to translate.
+   */
+  labels?: PaginationLabels;
+
+  /** Root-level Tailwind override. */
+  sx?: string;
+
+  /** Per-slot overrides. */
+  slotProps?: PaginationSlotProps;
+}

package/src/components/Pagination/pagination.variants.ts

@@ -0,0 +1,111 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `<Pagination>` variant recipe.
+ *
+ * Slots:
+ *  - `root`             — outer `<nav>` container
+ *  - `summary`          — "Showing X-Y of Z" text
+ *  - `list`             — `<ul>` of page buttons
+ *  - `pageButton`       — individual page number button
+ *  - `activeButton`     — modifier applied to the current page
+ *  - `navButton`        — first/prev/next/last buttons
+ *  - `ellipsis`         — `…` rendered when range gap
+ *  - `pageSizeSelector` — native `<select>` for page size
+ *  - `jumpInput`        — direct page jump `<input>`
+ *
+ * Variant axes:
+ *  - `variant` — `default` (full kit) | `compact` (number buttons +
+ *    prev/next only) | `minimal` ("X / Y pages" + prev/next only).
+ *  - `size` — `sm` | `md` (default) | `lg`. Drives padding + text
+ *    size on the buttons.
+ */
+export const paginationVariants = tv({
+  slots: {
+    root: 'flex flex-wrap items-center gap-3',
+    summary: 'text-neutral-600 dark:text-neutral-400',
+    list: 'inline-flex items-center gap-1',
+    pageButton: [
+      'inline-flex items-center justify-center rounded-md',
+      'border border-neutral-300 dark:border-neutral-700',
+      'bg-white dark:bg-neutral-900',
+      'text-neutral-700 dark:text-neutral-300',
+      'hover:bg-neutral-50 dark:hover:bg-neutral-800',
+      'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
+      'transition-colors motion-reduce:transition-none',
+      'disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none',
+    ],
+    activeButton: [
+      'bg-primary-500 text-white border-primary-500',
+      'hover:bg-primary-600 dark:hover:bg-primary-400',
+    ],
+    navButton: [
+      'inline-flex items-center justify-center rounded-md',
+      'border border-neutral-300 dark:border-neutral-700',
+      'bg-white dark:bg-neutral-900',
+      'text-neutral-700 dark:text-neutral-300',
+      'hover:bg-neutral-50 dark:hover:bg-neutral-800',
+      'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
+      'transition-colors motion-reduce:transition-none',
+      'disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none',
+    ],
+    ellipsis: 'inline-flex items-center justify-center text-neutral-500 px-1',
+    pageSizeSelector: [
+      'inline-flex items-center gap-2',
+      'text-neutral-700 dark:text-neutral-300',
+    ],
+    jumpInput: [
+      'rounded-md border border-neutral-300 dark:border-neutral-700',
+      'bg-white dark:bg-neutral-900',
+      'text-neutral-900 dark:text-neutral-50',
+      'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
+      'transition-colors motion-reduce:transition-none',
+    ],
+  },
+  variants: {
+    // Note: variant-driven visibility is enforced via conditional JSX
+    // rendering (in `Pagination.tsx`), NOT via `hidden` Tailwind class.
+    // Reason: `display: none` keeps the elements in the DOM (and in the
+    // a11y tree depending on how it's applied), which leaks into
+    // testing-library `queryByText` and feels semantically wrong for
+    // "this UI piece doesn't exist in this variant". So compact and
+    // minimal slots stay empty here.
+    variant: {
+      default: {},
+      compact: {},
+      minimal: {},
+    },
+    size: {
+      sm: {
+        summary: 'text-xs',
+        pageButton: 'h-7 min-w-7 px-2 text-xs',
+        navButton: 'h-7 min-w-7 px-2 text-xs',
+        ellipsis: 'h-7 min-w-5 text-xs',
+        pageSizeSelector: 'text-xs',
+        jumpInput: 'h-7 px-2 text-xs w-14',
+      },
+      md: {
+        summary: 'text-sm',
+        pageButton: 'h-9 min-w-9 px-3 text-sm',
+        navButton: 'h-9 min-w-9 px-3 text-sm',
+        ellipsis: 'h-9 min-w-6 text-sm',
+        pageSizeSelector: 'text-sm',
+        jumpInput: 'h-9 px-2 text-sm w-16',
+      },
+      lg: {
+        summary: 'text-base',
+        pageButton: 'h-10 min-w-10 px-4 text-base',
+        navButton: 'h-10 min-w-10 px-4 text-base',
+        ellipsis: 'h-10 min-w-7 text-base',
+        pageSizeSelector: 'text-base',
+        jumpInput: 'h-10 px-3 text-base w-20',
+      },
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+    size: 'md',
+  },
+});
+
+export type PaginationVariants = VariantProps<typeof paginationVariants>;

package/src/components/Skeleton/Skeleton.test.tsx

@@ -0,0 +1,127 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, cleanup } from '@testing-library/react';
+import { Skeleton } from './Skeleton.js';
+
+void React;
+afterEach(() => cleanup());
+
+describe('Skeleton — rendering', () => {
+  it('renders a span with aria-hidden', () => {
+    const { container } = render(<Skeleton />);
+    const el = container.querySelector('span');
+    expect(el).not.toBeNull();
+    expect(el?.getAttribute('aria-hidden')).toBe('true');
+    expect(el?.getAttribute('role')).toBe('presentation');
+  });
+
+  it('defaults to variant=text + animation=pulse', () => {
+    const { container } = render(<Skeleton />);
+    const cls = container.querySelector('span')!.className;
+    expect(cls).toContain('animate-pulse');
+    // text variant has a height of 1em
+    expect(cls).toContain('h-[1em]');
+  });
+});
+
+describe('Skeleton — variants', () => {
+  it.each(['text', 'rectangle', 'circle'] as const)(
+    'renders variant=%s without crashing',
+    (variant) => {
+      const { container } = render(<Skeleton variant={variant} />);
+      expect(container.querySelector('span')).not.toBeNull();
+    },
+  );
+
+  it('rectangle has rounded-md class', () => {
+    const { container } = render(<Skeleton variant="rectangle" />);
+    expect(container.querySelector('span')!.className).toContain('rounded-md');
+  });
+
+  it('circle has rounded-full class', () => {
+    const { container } = render(<Skeleton variant="circle" />);
+    expect(container.querySelector('span')!.className).toContain('rounded-full');
+  });
+});
+
+describe('Skeleton — animations', () => {
+  it('animation=pulse adds animate-pulse', () => {
+    const { container } = render(<Skeleton animation="pulse" />);
+    expect(container.querySelector('span')!.className).toContain('animate-pulse');
+  });
+
+  it('animation=none does NOT add animate-pulse', () => {
+    const { container } = render(<Skeleton animation="none" />);
+    expect(container.querySelector('span')!.className).not.toContain('animate-pulse');
+  });
+
+  it('animation=wave adds overflow-hidden + after gradient', () => {
+    const { container } = render(<Skeleton animation="wave" />);
+    const cls = container.querySelector('span')!.className;
+    expect(cls).toContain('overflow-hidden');
+    expect(cls).toContain('relative');
+  });
+
+  it('always carries motion-reduce safety regardless of animation', () => {
+    const { container } = render(<Skeleton animation="pulse" />);
+    expect(container.querySelector('span')!.className).toContain('motion-reduce:animate-none');
+  });
+});
+
+describe('Skeleton — dimensions', () => {
+  it('passes width as inline style', () => {
+    const { container } = render(<Skeleton width="200px" />);
+    expect((container.querySelector('span') as HTMLElement).style.width).toBe('200px');
+  });
+
+  it('passes height as inline style', () => {
+    const { container } = render(<Skeleton variant="rectangle" height="120px" />);
+    expect((container.querySelector('span') as HTMLElement).style.height).toBe('120px');
+  });
+
+  it('for circle, height defaults to width', () => {
+    const { container } = render(<Skeleton variant="circle" width="48px" />);
+    const el = container.querySelector('span') as HTMLElement;
+    expect(el.style.width).toBe('48px');
+    expect(el.style.height).toBe('48px');
+  });
+
+  it('for circle, explicit height wins over width-default', () => {
+    const { container } = render(<Skeleton variant="circle" width="48px" height="64px" />);
+    const el = container.querySelector('span') as HTMLElement;
+    expect(el.style.width).toBe('48px');
+    expect(el.style.height).toBe('64px');
+  });
+});
+
+describe('Skeleton — sx + slotProps', () => {
+  it('appends sx to root className', () => {
+    const { container } = render(<Skeleton sx="my-custom-sx" />);
+    expect(container.querySelector('span')!.className).toContain('my-custom-sx');
+  });
+
+  it('applies slotProps.root.className', () => {
+    const { container } = render(
+      <Skeleton slotProps={{ root: { className: 'slot-class' } }} />,
+    );
+    expect(container.querySelector('span')!.className).toContain('slot-class');
+  });
+
+  it('sx wins over variant default on conflict via tailwind-merge', () => {
+    // variant=text emits `bg-neutral-200`; sx forces `bg-red-500`.
+    const { container } = render(<Skeleton sx="bg-red-500" />);
+    const cls = container.querySelector('span')!.className;
+    expect(cls).toContain('bg-red-500');
+    expect(cls).not.toContain('bg-neutral-200');
+  });
+});
+
+describe('Skeleton — accessibility', () => {
+  it('does not appear in role-based queries (aria-hidden + role=presentation)', () => {
+    const { container } = render(<Skeleton />);
+    const el = container.querySelector('span')!;
+    expect(el.getAttribute('aria-hidden')).toBe('true');
+    expect(el.getAttribute('role')).toBe('presentation');
+  });
+});

package/src/components/Skeleton/Skeleton.tsx

@@ -0,0 +1,49 @@
+import type { CSSProperties } from 'react';
+import { cn } from '../../utils/cn.js';
+import { skeletonVariants } from './skeleton.variants.js';
+import type { SkeletonProps } from './skeleton.types.js';
+
+/**
+ * Dashforge TW `<Skeleton>` — loading placeholder primitive.
+ *
+ * Renders as a non-interactive `<span aria-hidden="true">` so screen
+ * readers skip it. The surrounding component is responsible for
+ * announcing loading state via `aria-busy` or `aria-live` if needed.
+ *
+ * Variants:
+ *   - `variant` — `text` (default, line shape) / `rectangle` / `circle`
+ *   - `animation` — `pulse` (default) / `wave` / `none`
+ *
+ * Both animations are gated by `prefers-reduced-motion` (WCAG 2.3.3).
+ *
+ * @example
+ * ```tsx
+ * <Skeleton variant="text" width="200px" />
+ * <Skeleton variant="rectangle" width="100%" height="120px" />
+ * <Skeleton variant="circle" width="40px" />
+ * ```
+ */
+export function Skeleton(props: SkeletonProps) {
+  const { variant = 'text', animation = 'pulse', width, height, sx, slotProps } = props;
+  const v = skeletonVariants({ variant, animation });
+
+  // Width / height come through as inline style — Tailwind doesn't
+  // know about arbitrary user-supplied lengths. We default `circle`'s
+  // height to `width` so consumers don't have to repeat themselves.
+  const style: CSSProperties = {};
+  if (width != null) style.width = width;
+  if (height != null) {
+    style.height = height;
+  } else if (variant === 'circle' && width != null) {
+    style.height = width;
+  }
+
+  return (
+    <span
+      aria-hidden="true"
+      role="presentation"
+      className={cn(v.root(), sx, slotProps?.root?.className)}
+      style={style}
+    />
+  );
+}

package/src/components/Skeleton/skeleton.types.ts

@@ -0,0 +1,59 @@
+import type { SkeletonVariants } from './skeleton.variants.js';
+
+export interface SkeletonSlotProps {
+  /** Root element override. */
+  root?: { className?: string };
+}
+
+/**
+ * Props for `<Skeleton>`.
+ *
+ * Visual loading placeholder shown while data / images / components
+ * are being prepared. Three shapes (`variant`), three animations
+ * (`animation`), and free-form `width` / `height` for arbitrary
+ * dimensions.
+ *
+ * Rendered as a non-interactive `<span aria-hidden="true">` so screen
+ * readers skip it entirely.
+ *
+ * Compose by nesting: e.g. avatar + two text lines for a card
+ * placeholder.
+ *
+ * @example
+ * ```tsx
+ * <Skeleton variant="text"      width="200px" />
+ * <Skeleton variant="rectangle" width="100%" height="120px" />
+ * <Skeleton variant="circle"    width="40px" />
+ *
+ * // Compose to mimic a card shape
+ * <div className="flex gap-3">
+ *   <Skeleton variant="circle" width="48px" />
+ *   <div className="flex flex-col gap-2 flex-1">
+ *     <Skeleton variant="text" width="60%" />
+ *     <Skeleton variant="text" width="40%" />
+ *   </div>
+ * </div>
+ * ```
+ */
+export interface SkeletonProps
+  extends Pick<SkeletonVariants, 'variant' | 'animation'> {
+  /**
+   * CSS width (e.g. `"200px"`, `"100%"`, `"60%"`).
+   *
+   * Defaults: `text` → `100%`, `rectangle` → `100%`, `circle` → `40px`.
+   */
+  width?: string;
+
+  /**
+   * CSS height (e.g. `"1em"`, `"120px"`).
+   *
+   * Defaults: `text` → `1em`, `rectangle` → `100px`, `circle` → matches `width`.
+   */
+  height?: string;
+
+  /** Root-level Tailwind override (wins via `tailwind-merge`). */
+  sx?: string;
+
+  /** Per-slot overrides. */
+  slotProps?: SkeletonSlotProps;
+}

package/src/components/Skeleton/skeleton.variants.ts

@@ -0,0 +1,86 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `<Skeleton>` variant recipe.
+ *
+ * Slots:
+ *  - `root` — single element (atomic component)
+ *
+ * Variant axes:
+ *  - `variant` (`text` | `rectangle` | `circle`) — shape / radius
+ *  - `animation` (`pulse` | `wave` | `none`) — how the placeholder
+ *    "breathes" while data loads. Always gated on
+ *    `prefers-reduced-motion` (no exception — animations are
+ *    purely cosmetic).
+ *
+ * Implementation notes:
+ *
+ *  - `pulse` uses Tailwind's built-in `animate-pulse` (opacity
+ *    1.0 ↔ 0.5 over 2s, ease-in-out infinite).
+ *  - `wave` overlays a moving gradient. Implemented with a
+ *    `relative` container + an `::after` pseudo-element via a
+ *    Tailwind arbitrary-value class. The gradient slides
+ *    horizontally over the surface, mimicking the MUI Skeleton
+ *    "wave" look.
+ *  - Color uses neutral-200 (light) and neutral-800 (dark) for
+ *    the base, picked up automatically by the dashforge preset's
+ *    CSS-variable layer.
+ *
+ * Accessibility: the root has `aria-hidden="true"` (set on the JSX
+ * side, not here). Screen readers skip the skeleton entirely;
+ * the surrounding component is responsible for announcing
+ * loading state via `aria-busy` or `aria-live` if needed.
+ */
+export const skeletonVariants = tv({
+  slots: {
+    root: [
+      'block',
+      'bg-neutral-200 dark:bg-neutral-800',
+      'motion-reduce:animate-none',
+    ],
+  },
+  variants: {
+    variant: {
+      text: {
+        root: 'rounded h-[1em] w-full',
+      },
+      rectangle: {
+        root: 'rounded-md w-full h-[100px]',
+      },
+      circle: {
+        root: 'rounded-full w-10 h-10',
+      },
+    },
+    animation: {
+      pulse: {
+        root: 'animate-pulse',
+      },
+      wave: {
+        root: [
+          'relative overflow-hidden',
+          // The wave is rendered via an arbitrary-value ::after
+          // pseudo-element with a moving linear gradient. Tailwind
+          // doesn't ship a `wave` keyframe; we use the built-in
+          // `animate-pulse` as a fallback if a consumer needs to
+          // override. The gradient stop direction works in both
+          // light and dark mode (white shimmer in light, lighter
+          // overlay in dark).
+          'after:absolute after:inset-0',
+          'after:bg-gradient-to-r after:from-transparent after:via-white/40 after:to-transparent',
+          'dark:after:via-white/10',
+          'after:animate-pulse',
+          'after:motion-reduce:animate-none',
+        ],
+      },
+      none: {
+        root: '',
+      },
+    },
+  },
+  defaultVariants: {
+    variant: 'text',
+    animation: 'pulse',
+  },
+});
+
+export type SkeletonVariants = VariantProps<typeof skeletonVariants>;

package/src/index.ts

@@ -262,6 +262,23 @@ export type {
 } from './components/Accordion/accordion.types.js';
 export { accordionVariants } from './components/Accordion/accordion.variants.js';
 
+// F12 utilities: loading placeholder + pagination control.
+
+export { Skeleton } from './components/Skeleton/Skeleton.js';
+export type {
+  SkeletonProps,
+  SkeletonSlotProps,
+} from './components/Skeleton/skeleton.types.js';
+export { skeletonVariants } from './components/Skeleton/skeleton.variants.js';
+
+export { Pagination } from './components/Pagination/Pagination.js';
+export type {
+  PaginationProps,
+  PaginationSlotProps,
+  PaginationLabels,
+} from './components/Pagination/pagination.types.js';
+export { paginationVariants } from './components/Pagination/pagination.variants.js';
+
 // ───── Hooks ─────
 export { useAccessState } from './hooks/useAccessState.js';
 
@@ -276,4 +293,4 @@ export type { VariantProps } from 'tailwind-variants';
 /**
  * Package version (synced with `package.json` at publish time).
  */
-export const VERSION = '0.4.0-beta';
+export const VERSION = '0.5.0-beta';