0.5.0-beta

Released 2026-05-19 · Sprint 4 release

Two utility primitives — <Skeleton> and <Pagination> — that were missing from the catalog and unlock the loading-state + paginated-list use cases ahead of Sprint 4.1 (Table + DataGrid).

Pure-UI, no bridge integration. Both ship in @dashforge/tw only — MUI consumers continue using @mui/material/Skeleton and @mui/material/Pagination directly. Per the Dashforge design rule (@dashforge/ui wraps MUI only when adding bridge / RBAC / validation / custom-behavior value), wrappers for these would add zero value and would only block evolution of the upstream components.

Zero new runtime deps. The "no external libraries" constraint is honored — Skeleton uses Tailwind's built-in animate-pulse, Pagination is hand-rolled with a standard "siblings + boundaries + ellipsis fill" range algorithm.

Strictly additive minor bump. Drop-in upgrade from 0.4.0-beta — zero breaking changes; existing usages keep working byte-identical.

Affected packages

Unchanged (independent versioning):

Added

Skeleton — loading placeholder primitive

import { Skeleton } from '@dashforge/tw';

<Skeleton variant="text"      width="200px" />
<Skeleton variant="rectangle" width="100%" height="120px" />
<Skeleton variant="circle"    width="48px" />

• Three shapes: text (default — h-[1em], full width), rectangle (rounded-md), circle (rounded-full — height defaults to width when omitted).
• Three animations: pulse (default — Tailwind's built-in animate-pulse), wave (gradient overlay), none.
• WCAG 2.3.3 reduced-motion safe: both animations are automatically suppressed when the user has set prefers-reduced-motion: reduce in their OS. No extra config.
• A11Y by design: rendered as a <span aria-hidden="true" role="presentation"> — screen readers skip the placeholder entirely. The surrounding container is responsible for aria-busy / aria-live announcements when relevant.
• Compose freely: nest multiple <Skeleton>s inside a flex or grid layout to mimic card / row / avatar shapes during fetch.
• sx + slotProps.root for the standard customization escape hatches.

Pagination — controlled pagination primitive

import { Pagination } from '@dashforge/tw';
import { useState } from 'react';

function MyList() {
  const [page, setPage] = useState(1);
  const [pageSize, setPageSize] = useState(20);

  return (
    <Pagination
      page={page}
      pageSize={pageSize}
      totalCount={1437}
      onPageChange={setPage}
      onPageSizeChange={setPageSize}
    />
  );
}

• Three variants:
  • default (full kit) — summary "Showing X-Y of Z" · page numbers with ellipsis · first/prev/next/last · page-size selector · direct page-jump input
  • compact — page numbers + first/prev/next/last only
  • minimal — "Page X of Y" + prev/next (mobile-friendly)
• Three sizes: sm · md (default) · lg — drives padding + text size on every interactive element.
• Smart ellipsis range: configurable siblingCount (default 1) + boundaryCount (default 1). Small totals (≤ 2·boundary + 2·sibling + 3 pages = 7 with defaults) short-circuit to the full range — no ellipsis when it's unnecessary.
• Full i18n via labels prop. Pass the subset you need; the rest fall back to English defaults (first · prev · next · last · page · of · showing · perPage · goToPage).
• A11Y: rendered as <nav aria-label="Pagination"> landmark. Active button marked with aria-current="page". Every interactive element carries an aria-label. Page-size selector is a real <select>; jump input is a real <input type="number"> with min / max matching the page range, commit on Enter or blur, out-of-range values silently clamped.
• Page-size selector hidden when onPageSizeChange is omitted. Jump input toggle via showJumpInput.
• sx + slotProps (root, summary, list, pageButton, activeButton, navButton, ellipsis, pageSizeSelector, jumpInput).

Internal — workflow + smoke test

This is the first release that exercised the new Dashforge workflow policy: every component is validated end-to-end in the dash consumer (/test-utilities) BEFORE its docs page is written. Catches integration / theme / animation / a11y issues that unit tests miss — and avoids docs that fossilize a not-yet-validated API.

TestUtilities.tsx in dash exercises:

• Skeleton: 3 variants × 3 animations matrix
• Skeleton: canonical card-placeholder compose pattern with a loading/loaded toggle
• Skeleton: 50-instance stress test wrapped in React.Profiler
• Pagination: all 3 variants
• Pagination: all 3 sizes side-by-side
• Pagination: Italian i18n labels
• Pagination: edge cases (totalCount=0, disabled)

Why no MUI wrapper for these?

A design decision worth documenting once for future reference:

Skeleton + Pagination fall entirely in the right column. A wrapper would only add a layer of indirection that blocks MUI's own evolution (peer-dep version pins, prop-passthrough churn, etc.) without giving consumers anything they can't get from @mui/material directly.

Bundle size delta

Above the 5% threshold defined in PERFORMANCE.md, but under 10% — falls in the "CHANGELOG justification only, no reviewer sign-off" category.

Per-component contribution (gzipped, estimated):

• Skeleton: ~1 KB
• Pagination: ~4 KB (3 variants × 3 sizes × i18n labels + range-computation helper + jump-input commit logic)

Within the projected envelope. The next bundle alarm to watch is Sprint 4.1 (DataGrid — virtualization homemade, no @tanstack), projected ~+10-15% gz.

Migration

pnpm up @dashforge/tw@^0.5.0-beta

No code changes required. Adopt the new components by importing them from @dashforge/tw:

import { Skeleton, Pagination } from '@dashforge/tw';

MUI consumers: continue using @mui/material/Skeleton and @mui/material/Pagination directly. @dashforge/ui will NOT ship wrappers for these (design rule above).

Compatibility

Looking ahead