@dashforge/tw 0.4.0-beta → 0.6.0-beta

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>;