feat(pagination): add molecule component

[ludevdot]

Summary

Closes #25

• Adds the new Pagination molecule with compound named exports for root, content, item, link, previous, next, ellipsis, and summary.
• Supports anchor and button navigation modes, current-page semantics, disabled controls, root-driven sizes, and accessible ellipsis text.
• Includes tests, Storybook examples, dark-mode accessibility fixes, and a small Select prop-doc hygiene fix required by the existing pre-commit gate.

Review scope

• Primary files/areas:
  • src/components/molecules/pagination/*
  • src/index.ts
  • src/components/atoms/select/types.ts default-doc hygiene only
• Out of scope:
  • Data-driven page calculation, automatic page ranges, compact/select/flyout pagination, first/last buttons, rows-per-page selector.
• Review workload: large; size:exception explicitly approved by maintainer in implementation thread because this is one cohesive new component and tests/stories belong with the component.

Type of change

• New component
• Existing component update/refactor
• Bug fix
• Accessibility
• Design tokens
• Storybook/docs
• Infrastructure/tooling
• NPM/dependencies

Workflow gates

• Linked issue is present with Closes #NNN or maintainer approved an exception.
• Linked issue has label status:approved before implementation starts.
• Work was started through the Project flow: assignee set, Project status In progress, branch/worktree recorded.
• PR title follows Conventional Commit format: <type>(<optional scope>): <description>.
• Commits follow the same commitlint-enforced format.
• Diff is focused; unrelated work is called out in Review scope.
• MCP/runtime artifacts are absent: .playwright-mcp, page-*.png, page-*.jpeg, *.md.playwright-output.

Component evidence (required for component changes)

• Validated component spec is linked or quoted in the issue.
• Accessibility contract from the spec was implemented or deviations are explained below.
• Follows the 6-file pattern: types.ts, use*.ts, Component.tsx, Component.test.tsx, Component.stories.tsx, index.ts.
• CVA variants live in types.ts; JSX component has no state, CVA calls, or business logic.
• Public props with runtime defaults have matching @default JSDoc in types.ts (node scripts/verify-prop-default-docs.mjs).
• Uses design tokens from theme.css; no hardcoded colors or arbitrary color utilities.
• Storybook covers default, variants, documented states, edge cases, and dark mode when visually different.
• Component audit result is PASS or accepted PASS WITH WARNINGS.
• Visual review result is included when visuals changed.

Accessibility evidence

• Role/name semantics verified with Testing Library queries or equivalent.
• Keyboard-only behavior verified: Tab / Shift+Tab, Enter / Space, Arrow keys, Escape, Home / End / typeahead where applicable.
• Focus lifecycle verified: native browser focus order; no roving tabindex, focus trap, or portal.
• Disabled, required, invalid/error, loading, and empty states expose the expected semantics where applicable.
• Reduced motion behavior is respected where motion changed.
• Screen reader or axe/manual evidence is included below when applicable.

Validation evidence

• TypeScript: pnpm exec tsc --noEmit passed.
• Unit tests: pnpm test passed, 30 files / 536 tests.
• Build/package: pnpm run build passed.
• Storybook or visual check: Storybook examples cover Default, WithEllipsis, WithSummary, PreviousNextOnly, DisabledBoundary, Sizes, ButtonMode, and AnchorMode. Sizes uses explicit titled sections.
• Accessibility check: Playwright + Storybook axe in dark mode for all Pagination stories reported 0 violations / 0 incomplete. Ellipsis uses SR-only text without invalid aria-label on a plain span; current-page contrast uses darker brand token in both themes.
• Security/dependency check: no new runtime dependency added.

Additional review evidence:

• Judgment Day Round 1 found two real warnings; both fixed.
• Judgment Day Round 2: Judge A clean, Judge B clean.

Screenshots or recordings

Notes for reviewer

• PaginationLink intentionally remains interactive when current; isCurrent only adds aria-current="page" and selected styling, per approved spec.
• Page range calculation is intentionally owned by consumers for MVP.
• src/components/atoms/select/types.ts only adds missing @default docs for existing runtime defaults so the repository prop-doc gate passes.

[Copilot]

Pull request overview

This PR adds a new Pagination molecule (compound component API) to the design system and wires it into the package exports, along with a small Select prop-doc default hygiene update needed to satisfy the repo’s prop-default docs gate.

Changes:

• Added a new Pagination molecule with compound exports (PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis, PaginationSummary) supporting anchor and button modes, disabled semantics, sizing via root context, and current-page semantics.
• Added unit tests and Storybook stories covering the supported states and modes.
• Added missing @default JSDoc for existing Select props with runtime defaults (clearAriaLabel, loadingLabel).

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/index.ts	Exports the new Pagination molecule from the package entrypoint.
src/components/molecules/pagination/usePagination.ts	Implements sizing context + container-layer logic for Pagination subcomponents.
src/components/molecules/pagination/types.ts	Defines public props, CVA variants, and JSDoc controls/defaults for Pagination.
src/components/molecules/pagination/Pagination.tsx	Presentational compound components for the Pagination molecule.
src/components/molecules/pagination/Pagination.test.tsx	Adds hook + component behavior tests for accessibility and interaction semantics.
src/components/molecules/pagination/Pagination.stories.tsx	Adds Storybook docs/examples for variants, modes, and states.
src/components/molecules/pagination/index.ts	Barrel re-exports for the Pagination molecule and types.
src/components/atoms/select/types.ts	Adds missing @default JSDoc for existing runtime defaults (prop-doc gate hygiene).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[egdev6]

Está muy bien encaminado. Dejo un pedido chico antes de aprobar: sumemos cobertura explícita de activación por teclado para PaginationLink.

El PR declara keyboard-only verification, y el componente soporta modo button y modo anchor, así que estaría bueno dejar evidencia local de:

• Enter/Space activando el modo button.
• Enter activando el modo anchor.

El resto lo veo bien: scope claro, CI verde, stories completas y la excepción de tamaño está justificada.

aplicado