aural-ui 4.0.1 → 4.1.0

package/dist/components/pagination/Pagination.stories.tsx

@@ -1,4 +1,4 @@
-import React from "react"
+import React, { useState } from "react"
 import {
   ChevronDoubleLeftIcon,
   ChevronDoubleRightIcon,
@@ -7,6 +7,8 @@ import {
 } from "@icons/index"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import {
   Pagination,
   PaginationButton,
@@ -22,18 +24,29 @@ const meta: Meta<typeof Pagination> = {
   component: Pagination,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
         component:
-          "A pagination component for navigating through paginated data with customizable options.",
+          "A compound pagination component for navigating through large datasets. Provides a fully-managed high-level Pagination component plus low-level primitives (PaginationButton, PaginationEllipsis, PaginationSizeSelector, PaginationRoot, PaginationContent) for custom compositions. State is supplied via PaginationProvider.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Provider State",
+              description: "Centralized page context",
+            },
+            {
+              title: "Low-level Primitives",
+              description: "Fully custom layouts",
+            },
+            {
+              title: "Size Selector",
+              description: "Page size dropdown",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -55,10 +68,6 @@ const meta: Meta<typeof Pagination> = {
       control: "object",
       description: "Available page sizes",
     },
-    className: {
-      control: "text",
-      description: "Additional CSS class name",
-    },
   },
   decorators: [
     (Story, context) => (
@@ -72,130 +81,128 @@ const meta: Meta<typeof Pagination> = {
 export default meta
 type Story = StoryObj<typeof Pagination>
 
-// Main Pagination Stories
-export const Default: Story = {
+// ─── 1. Playground ────────────────────────────────────────────────────────────
+
+export const Playground: Story = {
   args: {
     size: "md",
     showFirstLast: true,
     showPageSize: false,
     pageSizeOptions: [10, 20, 50, 100],
   },
-}
-
-export const Small: Story = {
-  args: {
-    size: "sm",
-    showFirstLast: true,
-    showPageSize: false,
+  render: (args) => <Pagination {...args} />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Use the controls panel in the sidebar to toggle size, first/last buttons, and page size selector. The pagination is live — click through pages to see state changes.",
+      },
+    },
   },
 }
 
-export const Large: Story = {
-  args: {
-    size: "lg",
-    showFirstLast: true,
-    showPageSize: false,
-  },
-}
+// ─── 2. Sizes ─────────────────────────────────────────────────────────────────
 
-export const WithPageSize: Story = {
-  args: {
-    size: "md",
-    showFirstLast: true,
-    showPageSize: true,
-    pageSizeOptions: [10, 20, 50, 100],
-  },
-}
+export const Sizes: Story = {
+  render: () => (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Small (sm)
+        </h4>
+        <div className="flex flex-wrap items-end justify-center gap-6">
+          <div className="space-y-2 text-center">
+            <Pagination size="sm" showFirstLast showPageSize={false} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Small — 32px buttons
+            </p>
+          </div>
+        </div>
+      </div>
 
-export const WithoutFirstLast: Story = {
-  args: {
-    size: "md",
-    showFirstLast: false,
-    showPageSize: false,
-  },
-}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Medium (md)
+        </h4>
+        <div className="flex flex-wrap items-end justify-center gap-6">
+          <div className="space-y-2 text-center">
+            <Pagination size="md" showFirstLast showPageSize={false} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Medium — 40px buttons (default)
+            </p>
+          </div>
+        </div>
+      </div>
 
-export const FirstPage: Story = {
-  decorators: [
-    (Story) => (
-      <PaginationProvider totalItems={100} initialPage={1} initialPageSize={10}>
-        <Story />
-      </PaginationProvider>
-    ),
-  ],
-  args: {
-    size: "md",
-    showFirstLast: true,
-    showPageSize: true,
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Large (lg)
+        </h4>
+        <div className="flex flex-wrap items-end justify-center gap-6">
+          <div className="space-y-2 text-center">
+            <Pagination size="lg" showFirstLast showPageSize={false} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Large — 48px buttons
+            </p>
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Side-by-side scale comparison across all three sizes: small (32px), medium (40px), and large (48px).",
+      },
+    },
   },
 }
 
-export const LastPage: Story = {
-  decorators: [
-    (Story) => (
-      <PaginationProvider
-        totalItems={100}
-        initialPage={10}
-        initialPageSize={10}
-      >
-        <Story />
-      </PaginationProvider>
-    ),
-  ],
-  args: {
-    size: "md",
-    showFirstLast: true,
-    showPageSize: true,
-  },
-}
+// ─── 3. Configurations ────────────────────────────────────────────────────────
 
-// Primitives Stories
-export const PrimitiveButtons: Story = {
+export const Configurations: Story = {
   render: () => (
-    <div className="text-fm-primary space-y-4">
-      <div className="space-x-2">
-        <h3 className="mb-2 text-sm font-medium">Button Variants</h3>
-        <PaginationButton variant="navigation" size="md">
-          <ChevronLeftIcon />
-        </PaginationButton>
-        <PaginationButton variant="number" size="md">
-          1
-        </PaginationButton>
-        <PaginationButton variant="active" size="md">
-          2
-        </PaginationButton>
-        <PaginationButton variant="number" size="md">
-          3
-        </PaginationButton>
-        <PaginationButton variant="navigation" size="md">
-          <ChevronRightIcon />
-        </PaginationButton>
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          With First / Last Buttons
+        </h4>
+        <div className="space-y-2 text-center">
+          <Pagination size="md" showFirstLast showPageSize={false} />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            showFirstLast=true
+          </p>
+        </div>
       </div>
 
-      <div className="space-x-2">
-        <h3 className="mb-2 text-sm font-medium">Button Sizes</h3>
-        <PaginationButton variant="number" size="sm">
-          1
-        </PaginationButton>
-        <PaginationButton variant="number" size="md">
-          2
-        </PaginationButton>
-        <PaginationButton variant="number" size="lg">
-          3
-        </PaginationButton>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Without First / Last Buttons
+        </h4>
+        <div className="space-y-2 text-center">
+          <Pagination size="md" showFirstLast={false} showPageSize={false} />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            showFirstLast=false
+          </p>
+        </div>
       </div>
 
-      <div className="space-x-2">
-        <h3 className="mb-2 text-sm font-medium">Disabled States</h3>
-        <PaginationButton variant="navigation" size="md" disabled>
-          <ChevronLeftIcon />
-        </PaginationButton>
-        <PaginationButton variant="number" size="md" disabled>
-          1
-        </PaginationButton>
-        <PaginationButton variant="navigation" size="md" disabled>
-          <ChevronRightIcon />
-        </PaginationButton>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          With Page Size Selector
+        </h4>
+        <div className="space-y-2 text-center">
+          <Pagination
+            size="md"
+            showFirstLast
+            showPageSize
+            pageSizeOptions={[10, 20, 50, 100]}
+          />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            showPageSize=true — page size control shown on the left
+          </p>
+        </div>
       </div>
     </div>
   ),
@@ -203,158 +210,662 @@ export const PrimitiveButtons: Story = {
     docs: {
       description: {
         story:
-          "Individual pagination button primitives with different variants, sizes, and states.",
+          "Configuration axes: with and without first/last navigation buttons, and with the page size selector visible.",
       },
     },
   },
 }
 
-export const PrimitiveEllipsis: Story = {
+// ─── 4. States ────────────────────────────────────────────────────────────────
+
+export const States: Story = {
   render: () => (
-    <div className="text-fm-primary space-y-4">
-      <div className="flex items-center space-x-2">
-        <h3 className="text-sm font-medium">Ellipsis Sizes</h3>
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          First Page (prev / first disabled)
+        </h4>
+        <PaginationProvider
+          totalItems={100}
+          initialPage={1}
+          initialPageSize={10}
+        >
+          <div className="space-y-2 text-center">
+            <Pagination size="md" showFirstLast showPageSize={false} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Page 1 of 10 — back navigation disabled
+            </p>
+          </div>
+        </PaginationProvider>
       </div>
-      <div className="flex items-center space-x-2">
-        <PaginationButton variant="number" size="sm">
-          1
-        </PaginationButton>
-        <PaginationEllipsis size="sm" />
-        <PaginationButton variant="number" size="sm">
-          5
-        </PaginationButton>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Last Page (next / last disabled)
+        </h4>
+        <PaginationProvider
+          totalItems={100}
+          initialPage={10}
+          initialPageSize={10}
+        >
+          <div className="space-y-2 text-center">
+            <Pagination size="md" showFirstLast showPageSize={false} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Page 10 of 10 — forward navigation disabled
+            </p>
+          </div>
+        </PaginationProvider>
       </div>
-      <div className="flex items-center space-x-2">
-        <PaginationButton variant="number" size="md">
-          1
-        </PaginationButton>
-        <PaginationEllipsis size="md" />
-        <PaginationButton variant="number" size="md">
-          5
-        </PaginationButton>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Mid-Range (with ellipsis)
+        </h4>
+        <PaginationProvider
+          totalItems={250}
+          initialPage={5}
+          initialPageSize={10}
+        >
+          <div className="space-y-2 text-center">
+            <Pagination size="md" showFirstLast showPageSize={false} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Page 5 of 25 — ellipsis visible on both sides
+            </p>
+          </div>
+        </PaginationProvider>
       </div>
-      <div className="flex items-center space-x-2">
-        <PaginationButton variant="number" size="lg">
-          1
-        </PaginationButton>
-        <PaginationEllipsis size="lg" />
-        <PaginationButton variant="number" size="lg">
-          5
-        </PaginationButton>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Button States
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          <div className="space-y-2 text-center">
+            <PaginationButton variant="number" size="md">
+              5
+            </PaginationButton>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Number — default
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <PaginationButton variant="active" size="md">
+              6
+            </PaginationButton>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Number — active
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <PaginationButton variant="number" size="md" disabled>
+              7
+            </PaginationButton>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Number — disabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <PaginationButton variant="navigation" size="md">
+              <ChevronLeftIcon />
+            </PaginationButton>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Navigation — enabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <PaginationButton variant="navigation" size="md" disabled>
+              <ChevronRightIcon />
+            </PaginationButton>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Navigation — disabled
+            </p>
+          </div>
+        </div>
       </div>
     </div>
   ),
   parameters: {
     docs: {
       description: {
-        story: "Pagination ellipsis primitive in different sizes.",
+        story:
+          "First page (back disabled), last page (forward disabled), mid-range with ellipsis, and individual button state variants (default, active, disabled).",
       },
     },
   },
 }
 
-export const PrimitiveSizeSelector: Story = {
-  render: () => (
-    <PaginationProvider totalItems={100} initialPage={1} initialPageSize={10}>
-      <div className="text-fm-primary space-y-4">
-        <div>
-          <h3 className="mb-2 text-sm font-medium">Size Selector Sizes</h3>
-        </div>
-        <div className="space-y-2">
-          <PaginationSizeSelector
-            size="sm"
-            pageSizeOptions={[5, 10, 20]}
-            pageSize={10}
-            setPageSize={(size) => console.log("Set page size:", size)}
-          />
-          <PaginationSizeSelector
-            size="md"
-            pageSizeOptions={[10, 20, 50]}
-            pageSize={20}
-            setPageSize={(size) => console.log("Set page size:", size)}
-          />
-          <PaginationSizeSelector
-            size="lg"
-            pageSizeOptions={[20, 50, 100]}
-            pageSize={50}
-            setPageSize={(size) => console.log("Set page size:", size)}
-          />
+// ─── 5. Interactive ───────────────────────────────────────────────────────────
+
+export const Interactive: Story = {
+  render: () => {
+    const [totalItems] = useState(250)
+    const [initialPage] = useState(1)
+
+    return (
+      <div className="w-full p-8">
+        <div className="mx-auto max-w-3xl space-y-6">
+          <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+            {/* Controls Panel */}
+            <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-5 rounded-xl border p-5">
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Dataset
+              </p>
+              <div className="space-y-2">
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Total items:{" "}
+                  <span className="text-fm-primary font-medium">
+                    {totalItems}
+                  </span>
+                </p>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Starting page:{" "}
+                  <span className="text-fm-primary font-medium">
+                    {initialPage}
+                  </span>
+                </p>
+              </div>
+              <div className="border-fm-divider-secondary border-t pt-4" />
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Info
+              </p>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                Click page numbers or navigation arrows to move through pages.
+                The active page highlights and ellipsis collapses distant pages
+                automatically.
+              </p>
+            </div>
+
+            {/* Preview Stage */}
+            <div className="flex flex-col gap-6 lg:col-span-2">
+              <PaginationProvider
+                totalItems={totalItems}
+                initialPage={initialPage}
+                initialPageSize={10}
+              >
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary flex flex-col gap-6 rounded-xl border p-6">
+                  <div className="space-y-1">
+                    <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold">
+                      With page size selector
+                    </p>
+                    <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                      size="md" · showFirstLast · showPageSize
+                    </p>
+                  </div>
+                  <Pagination
+                    size="md"
+                    showFirstLast
+                    showPageSize
+                    pageSizeOptions={[10, 20, 50]}
+                  />
+                </div>
+              </PaginationProvider>
+
+              <PaginationProvider
+                totalItems={totalItems}
+                initialPage={initialPage}
+                initialPageSize={10}
+              >
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary flex flex-col gap-6 rounded-xl border p-6">
+                  <div className="space-y-1">
+                    <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold">
+                      Compact — no first/last
+                    </p>
+                    <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                      size="sm" · showFirstLast=false
+                    </p>
+                  </div>
+                  <Pagination
+                    size="sm"
+                    showFirstLast={false}
+                    showPageSize={false}
+                  />
+                </div>
+              </PaginationProvider>
+
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+                <code className="text-fm-secondary text-fm-md leading-fm-md font-[var(--font-fm-mono)]">
+                  {
+                    '<PaginationProvider totalItems={250}>\n  <Pagination size="md" showFirstLast showPageSize />\n</PaginationProvider>'
+                  }
+                </code>
+              </div>
+            </div>
+          </div>
         </div>
       </div>
-    </PaginationProvider>
-  ),
+    )
+  },
   parameters: {
+    layout: "fullscreen",
     docs: {
       description: {
-        story: "Pagination size selector primitive in different sizes.",
+        story:
+          "Live interactive demo of two Pagination variants side by side. Click through pages to observe ellipsis collapsing, active page highlighting, and disabled navigation edges.",
       },
     },
   },
 }
 
-export const PrimitiveComposition: Story = {
+// ─── 6. Parts ─────────────────────────────────────────────────────────────────
+
+export const Parts: Story = {
   render: () => (
-    <div className="text-fm-primary space-y-6">
-      <div>
-        <h3 className="mb-2 text-sm font-medium">
-          Custom Composition with Primitives
-        </h3>
-        <PaginationRoot>
-          <PaginationContent>
+    <div className="space-y-10">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          PaginationButton
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          <div className="space-y-2 text-center">
             <PaginationButton variant="navigation" size="md">
               <ChevronDoubleLeftIcon />
             </PaginationButton>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              navigation
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
             <PaginationButton variant="navigation" size="md">
               <ChevronLeftIcon />
             </PaginationButton>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              navigation
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
             <PaginationButton variant="number" size="md">
-              1
-            </PaginationButton>
-            <PaginationButton variant="number" size="md">
-              2
-            </PaginationButton>
-            <PaginationButton variant="active" size="md">
               3
             </PaginationButton>
-            <PaginationButton variant="number" size="md">
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              number
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <PaginationButton variant="active" size="md">
               4
             </PaginationButton>
-            <PaginationEllipsis size="md" />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              active
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
             <PaginationButton variant="number" size="md">
-              10
+              5
             </PaginationButton>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              number
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
             <PaginationButton variant="navigation" size="md">
               <ChevronRightIcon />
             </PaginationButton>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              navigation
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
             <PaginationButton variant="navigation" size="md">
               <ChevronDoubleRightIcon />
             </PaginationButton>
-          </PaginationContent>
-        </PaginationRoot>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              navigation
+            </p>
+          </div>
+        </div>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            A standalone button primitive. Accepts{" "}
+            <code className="text-fm-primary">variant</code> (number, active,
+            navigation) and <code className="text-fm-primary">size</code> (sm,
+            md, lg). Used inside PaginationContent for custom compositions.
+          </p>
+        </div>
       </div>
 
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Minimal Composition</h3>
-        <PaginationRoot>
-          <PaginationContent>
-            <PaginationButton variant="navigation" size="sm">
-              <ChevronLeftIcon />
-            </PaginationButton>
-            <PaginationButton variant="active" size="sm">
-              5
-            </PaginationButton>
-            <PaginationButton variant="navigation" size="sm">
-              <ChevronRightIcon />
-            </PaginationButton>
-          </PaginationContent>
-        </PaginationRoot>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          PaginationEllipsis
+        </h4>
+        <div className="flex flex-wrap items-end gap-6">
+          <div className="space-y-2 text-center">
+            <div className="flex items-center gap-1">
+              <PaginationButton variant="number" size="sm">
+                1
+              </PaginationButton>
+              <PaginationEllipsis size="sm" />
+              <PaginationButton variant="number" size="sm">
+                9
+              </PaginationButton>
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              sm
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <div className="flex items-center gap-1">
+              <PaginationButton variant="number" size="md">
+                1
+              </PaginationButton>
+              <PaginationEllipsis size="md" />
+              <PaginationButton variant="number" size="md">
+                9
+              </PaginationButton>
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              md
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <div className="flex items-center gap-1">
+              <PaginationButton variant="number" size="lg">
+                1
+              </PaginationButton>
+              <PaginationEllipsis size="lg" />
+              <PaginationButton variant="number" size="lg">
+                9
+              </PaginationButton>
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              lg
+            </p>
+          </div>
+        </div>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            A decorative span that renders "…" to indicate skipped pages. Uses{" "}
+            <code className="text-fm-primary">aria-hidden="true"</code> — screen
+            readers skip it. Sized via the same{" "}
+            <code className="text-fm-primary">size</code> prop as
+            PaginationButton.
+          </p>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          PaginationSizeSelector
+        </h4>
+        <PaginationProvider
+          totalItems={100}
+          initialPage={1}
+          initialPageSize={10}
+        >
+          <div className="flex flex-wrap items-end gap-6">
+            <div className="space-y-2 text-center">
+              <PaginationSizeSelector
+                size="sm"
+                pageSizeOptions={[5, 10, 20]}
+                pageSize={10}
+                setPageSize={(s) => console.log("page size:", s)}
+              />
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                sm
+              </p>
+            </div>
+            <div className="space-y-2 text-center">
+              <PaginationSizeSelector
+                size="md"
+                pageSizeOptions={[10, 20, 50]}
+                pageSize={20}
+                setPageSize={(s) => console.log("page size:", s)}
+              />
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                md
+              </p>
+            </div>
+            <div className="space-y-2 text-center">
+              <PaginationSizeSelector
+                size="lg"
+                pageSizeOptions={[20, 50, 100]}
+                pageSize={50}
+                setPageSize={(s) => console.log("page size:", s)}
+              />
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                lg
+              </p>
+            </div>
+          </div>
+        </PaginationProvider>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            A select control for choosing how many items to show per page.
+            Requires <code className="text-fm-primary">pageSize</code> (current
+            value) and <code className="text-fm-primary">setPageSize</code>{" "}
+            (change handler). When used inside Pagination, these are wired
+            automatically via PaginationProvider.
+          </p>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Custom Composition (PaginationRoot + PaginationContent)
+        </h4>
+        <div className="space-y-4">
+          <PaginationRoot>
+            <PaginationContent>
+              <PaginationButton variant="navigation" size="md">
+                <ChevronDoubleLeftIcon />
+              </PaginationButton>
+              <PaginationButton variant="navigation" size="md">
+                <ChevronLeftIcon />
+              </PaginationButton>
+              <PaginationButton variant="number" size="md">
+                1
+              </PaginationButton>
+              <PaginationButton variant="number" size="md">
+                2
+              </PaginationButton>
+              <PaginationButton variant="active" size="md">
+                3
+              </PaginationButton>
+              <PaginationButton variant="number" size="md">
+                4
+              </PaginationButton>
+              <PaginationEllipsis size="md" />
+              <PaginationButton variant="number" size="md">
+                10
+              </PaginationButton>
+              <PaginationButton variant="navigation" size="md">
+                <ChevronRightIcon />
+              </PaginationButton>
+              <PaginationButton variant="navigation" size="md">
+                <ChevronDoubleRightIcon />
+              </PaginationButton>
+            </PaginationContent>
+          </PaginationRoot>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm text-center">
+            Fully custom layout — no PaginationProvider required
+          </p>
+        </div>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            PaginationRoot is a flex container with{" "}
+            <code className="text-fm-primary">justify-between</code>.
+            PaginationContent is a <code className="text-fm-primary">nav</code>{" "}
+            element with{" "}
+            <code className="text-fm-primary">
+              aria-label="Pagination navigation"
+            </code>
+            . Compose these with any button primitives for fully custom
+            pagination UI without the managed Pagination component.
+          </p>
+        </div>
       </div>
     </div>
   ),
   parameters: {
     docs: {
       description: {
-        story: "Examples of custom compositions using pagination primitives.",
+        story:
+          "Individual compound-component parts: PaginationButton (all variants and sizes), PaginationEllipsis (all sizes), PaginationSizeSelector, and a fully custom PaginationRoot + PaginationContent composition without the managed Pagination component.",
+      },
+    },
+  },
+}
+
+// ─── 7. Use Cases ─────────────────────────────────────────────────────────────
+
+export const UseCases: Story = {
+  render: () => (
+    <div className="mx-auto max-w-3xl space-y-8 p-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Track Library Browser
+        </h4>
+        <PaginationProvider
+          totalItems={347}
+          initialPage={3}
+          initialPageSize={20}
+        >
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md rounded-xl border">
+            <div className="border-fm-divider-secondary border-b p-4">
+              <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+                All Tracks
+              </p>
+              <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                347 tracks
+              </p>
+            </div>
+            {[
+              "Midnight Dreams",
+              "Electric Sunrise",
+              "Neon Horizon",
+              "Echoes in Rain",
+              "Solar Wind",
+            ].map((title, i) => (
+              <div
+                key={title}
+                className="border-fm-divider-secondary flex items-center justify-between border-b p-4 last:border-b-0"
+              >
+                <div className="flex items-center gap-3">
+                  <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm w-5 text-right">
+                    {i + 41}
+                  </p>
+                  <div>
+                    <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                      {title}
+                    </p>
+                    <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                      3:2{i + 1}
+                    </p>
+                  </div>
+                </div>
+              </div>
+            ))}
+            <div className="p-4">
+              <Pagination
+                size="sm"
+                showFirstLast={false}
+                showPageSize={false}
+              />
+            </div>
+          </div>
+        </PaginationProvider>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Album Search Results
+        </h4>
+        <PaginationProvider
+          totalItems={120}
+          initialPage={2}
+          initialPageSize={10}
+        >
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md space-y-4 rounded-xl border p-5">
+            <div className="flex items-center justify-between">
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                Showing 11–20 of 120 results
+              </p>
+            </div>
+            <div className="grid grid-cols-2 gap-3">
+              {[
+                "Midnight Sessions",
+                "Neon Frequencies",
+                "Echoes Vol. 2",
+                "Solar Drift",
+              ].map((album) => (
+                <div
+                  key={album}
+                  className="border-fm-divider-secondary rounded-lg border p-3"
+                >
+                  <div className="bg-fm-surface-secondary mb-2 aspect-square w-full rounded-md" />
+                  <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                    {album}
+                  </p>
+                  <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                    Various Artists
+                  </p>
+                </div>
+              ))}
+            </div>
+            <Pagination
+              size="md"
+              showFirstLast
+              showPageSize
+              pageSizeOptions={[10, 20, 50]}
+            />
+          </div>
+        </PaginationProvider>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Admin Data Table
+        </h4>
+        <PaginationProvider
+          totalItems={1500}
+          initialPage={1}
+          initialPageSize={50}
+        >
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md space-y-3 rounded-xl border p-5">
+            <div className="flex items-center justify-between">
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold">
+                Upload Log
+              </p>
+              <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                1,500 entries
+              </p>
+            </div>
+            <div className="border-fm-divider-secondary rounded-lg border">
+              {[
+                "track_001.flac",
+                "track_002.mp3",
+                "cover_art.png",
+                "metadata.json",
+              ].map((file, i) => (
+                <div
+                  key={file}
+                  className="border-fm-divider-secondary flex items-center justify-between border-b p-3 last:border-b-0"
+                >
+                  <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                    {file}
+                  </p>
+                  <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                    {(i + 1) * 2}.{i}MB
+                  </p>
+                </div>
+              ))}
+            </div>
+            <Pagination
+              size="md"
+              showFirstLast
+              showPageSize
+              pageSizeOptions={[25, 50, 100]}
+            />
+          </div>
+        </PaginationProvider>
+      </div>
+    </div>
+  ),
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "Real product scenarios: a track library browser with compact pagination, an album search results grid, and an admin data table with page size control.",
       },
     },
   },