aural-ui 3.0.7 → 4.1.0

package/dist/hooks/use-standalone-pagination/UseStandalonePagination.stories.tsx

@@ -1,12 +1,93 @@
-import React from "react"
+import React, { useMemo, useState } from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
-import { useStandalonePagination, UseStandalonePaginationProps } from "."
+import {
+  FeatureShineIcon,
+  FileTextIcon,
+  LayoutColumnIcon,
+  NotepadIcon,
+  PageTextIcon,
+  SearchIcon,
+  SettingIcon,
+} from "src/ui/icons"
+import {
+  HookCodeBlock,
+  HookControlButton,
+  HookPanel,
+  HookPlaygroundCanvas,
+  HookStateCard,
+  HookStateGrid,
+  HookUsageCanvas,
+  HookUsageSection,
+} from "src/ui/story-spec/hooks/hook-story-canvas"
+import { AuralHookDocsPage } from "src/ui/story-spec/hooks/hook-story-docs-page"
+
+import { useStandalonePagination, type UseStandalonePaginationProps } from "."
+
+type PlaygroundDemoProps = UseStandalonePaginationProps & {
+  label?: string
+}
+
+const PAGE_SIZE_OPTIONS = [5, 10, 20, 50]
+
+const formatVisiblePages = (visiblePages: number[]) =>
+  visiblePages.map((page) => (page > 0 ? String(page) : "...")).join(" ")
+
+const getRangeLabel = (
+  currentPage: number,
+  pageSize: number,
+  totalItems: number
+) => {
+  const start = totalItems === 0 ? 0 : (currentPage - 1) * pageSize + 1
+  const end = Math.min(currentPage * pageSize, totalItems)
+  return `${start}-${end} of ${totalItems}`
+}
+
+const PaginationPlaygroundDemo: React.FC<PlaygroundDemoProps> = ({
+  label = "Dataset",
+  ...props
+}) => {
+  const {
+    currentPage,
+    totalPages,
+    pageSize,
+    totalItems,
+    isFirstPage,
+    isLastPage,
+    visiblePages,
+  } = useStandalonePagination(props)
+
+  return (
+    <HookPlaygroundCanvas>
+      <div className="mx-auto w-full max-w-3xl space-y-6 p-8">
+        <HookStateGrid>
+          <HookStateCard label="Current page" value={String(currentPage)} />
+          <HookStateCard label="Total pages" value={String(totalPages)} />
+          <HookStateCard label="Page size" value={String(pageSize)} />
+          <HookStateCard
+            label={label}
+            value={getRangeLabel(currentPage, pageSize, totalItems)}
+          />
+        </HookStateGrid>
+
+        <HookPanel title="Derived state">
+          <div className="grid gap-3 md:grid-cols-2">
+            <HookCodeBlock
+              code={`visiblePages = [${formatVisiblePages(visiblePages)}]`}
+            />
+            <HookCodeBlock
+              code={`isFirstPage = ${String(isFirstPage)}
+isLastPage = ${String(isLastPage)}`}
+            />
+          </div>
+        </HookPanel>
+      </div>
+    </HookPlaygroundCanvas>
+  )
+}
 
-// Example component that uses the hook
-const PaginationDemo: React.FC<
-  UseStandalonePaginationProps & { title?: string }
-> = ({ title = "Pagination Demo", ...props }) => {
+const PaginationInteractiveDemo: React.FC = () => {
+  const [goToPageValue, setGoToPageValue] = useState("1")
   const {
     currentPage,
     totalPages,
@@ -21,963 +102,654 @@ const PaginationDemo: React.FC<
     isFirstPage,
     isLastPage,
     visiblePages,
-  } = useStandalonePagination(props)
+  } = useStandalonePagination({
+    totalItems: 126,
+    initialPage: 4,
+    initialPageSize: 10,
+    siblingCount: 1,
+  })
+
+  const pageRows = useMemo(
+    () =>
+      Array.from({ length: pageSize }, (_, index) => {
+        const itemNumber = (currentPage - 1) * pageSize + index + 1
+        if (itemNumber > totalItems) return null
+        return `Item ${itemNumber}`
+      }).filter(Boolean) as string[],
+    [currentPage, pageSize, totalItems]
+  )
+
+  const commitPageInput = () => {
+    const parsedPage = Number.parseInt(goToPageValue, 10)
+    if (Number.isNaN(parsedPage)) return
+    setPage(parsedPage)
+    setGoToPageValue(String(parsedPage))
+  }
 
   return (
-    <div className="!space-y-6 rounded-lg border border-white/10 bg-white/5 !p-6">
-      <div className="!space-y-4">
-        <h3 className="!text-xl font-semibold !text-white">{title}</h3>
-
-        {/* Current State Display */}
-        <div className="grid grid-cols-2 gap-4 md:grid-cols-4">
-          <div className="rounded-lg border border-blue-500/20 bg-blue-500/10 !p-3">
-            <div className="!text-sm !text-blue-300">Current Page</div>
-            <div className="!text-2xl font-bold !text-blue-100">
-              {currentPage}
-            </div>
-          </div>
-          <div className="rounded-lg border border-purple-500/20 bg-purple-500/10 !p-3">
-            <div className="!text-sm !text-purple-300">Total Pages</div>
-            <div className="!text-2xl font-bold !text-purple-100">
-              {totalPages}
-            </div>
-          </div>
-          <div className="rounded-lg border border-green-500/20 bg-green-500/10 !p-3">
-            <div className="!text-sm !text-green-300">Page Size</div>
-            <div className="!text-2xl font-bold !text-green-100">
-              {pageSize}
-            </div>
-          </div>
-          <div className="rounded-lg border border-orange-500/20 bg-orange-500/10 !p-3">
-            <div className="!text-sm !text-orange-300">Total Items</div>
-            <div className="!text-2xl font-bold !text-orange-100">
-              {totalItems}
-            </div>
-          </div>
-        </div>
-
-        {/* Page Size Controls */}
-        <div className="!space-y-2">
-          <label className="!text-sm font-medium !text-white">Page Size</label>
-          <div className="flex gap-2">
-            {[5, 10, 20, 50].map((size) => (
-              <button
-                key={size}
-                onClick={() => setPageSize(size)}
-                className={`rounded-lg !px-3 !py-1 !text-sm transition-colors ${
-                  pageSize === size
-                    ? "bg-blue-500 !text-white"
-                    : "border border-white/20 bg-white/5 !text-white/70 hover:bg-white/10"
-                }`}
-              >
-                {size}
-              </button>
-            ))}
-          </div>
-        </div>
-
-        {/* Navigation Controls */}
-        <div className="!space-y-2">
-          <label className="!text-sm font-medium !text-white">
-            Navigation Controls
-          </label>
-          <div className="flex gap-2">
-            <button
+    <HookPlaygroundCanvas>
+      <div className="mx-auto w-full max-w-4xl space-y-6 p-8">
+        <HookStateGrid>
+          <HookStateCard label="Current page" value={String(currentPage)} />
+          <HookStateCard label="Total pages" value={String(totalPages)} />
+          <HookStateCard label="Page size" value={String(pageSize)} />
+          <HookStateCard
+            label="Showing"
+            value={getRangeLabel(currentPage, pageSize, totalItems)}
+          />
+          <HookStateCard label="First page" value={String(isFirstPage)} />
+          <HookStateCard label="Last page" value={String(isLastPage)} />
+          <HookStateCard
+            label="Visible slots"
+            value={String(visiblePages.length)}
+          />
+          <HookStateCard label="Sibling count" value="1" />
+        </HookStateGrid>
+
+        <HookPanel title="Navigation controls">
+          <div className="flex flex-wrap gap-3">
+            <HookControlButton
               onClick={firstPage}
               disabled={isFirstPage}
-              className="rounded-lg border border-white/20 bg-white/5 !px-3 !py-2 !text-sm !text-white transition-colors hover:bg-white/10 disabled:cursor-not-allowed disabled:opacity-50"
+              className="flex-1"
             >
               First
-            </button>
-            <button
+            </HookControlButton>
+            <HookControlButton
               onClick={prevPage}
               disabled={isFirstPage}
-              className="rounded-lg border border-white/20 bg-white/5 !px-3 !py-2 !text-sm !text-white transition-colors hover:bg-white/10 disabled:cursor-not-allowed disabled:opacity-50"
+              variant="negative"
+              className="flex-1"
             >
               Previous
-            </button>
-            <button
+            </HookControlButton>
+            <HookControlButton
               onClick={nextPage}
               disabled={isLastPage}
-              className="rounded-lg border border-white/20 bg-white/5 !px-3 !py-2 !text-sm !text-white transition-colors hover:bg-white/10 disabled:cursor-not-allowed disabled:opacity-50"
+              variant="positive"
+              className="flex-1"
             >
               Next
-            </button>
-            <button
+            </HookControlButton>
+            <HookControlButton
               onClick={lastPage}
               disabled={isLastPage}
-              className="rounded-lg border border-white/20 bg-white/5 !px-3 !py-2 !text-sm !text-white transition-colors hover:bg-white/10 disabled:cursor-not-allowed disabled:opacity-50"
+              className="flex-1"
             >
               Last
-            </button>
+            </HookControlButton>
           </div>
-        </div>
-
-        {/* Visible Pages */}
-        <div className="!space-y-2">
-          <label className="!text-sm font-medium !text-white">
-            Visible Pages
-          </label>
-          <div className="flex flex-wrap gap-1">
-            {visiblePages.map((page, index) => (
-              <button
-                key={index}
-                onClick={() => page > 0 && setPage(page)}
-                disabled={page < 0}
-                className={`!h-10 !w-10 rounded-lg !text-sm transition-colors ${
-                  page === currentPage
-                    ? "bg-blue-500 !text-white"
-                    : page > 0
-                      ? "border border-white/20 bg-white/5 !text-white/70 hover:bg-white/10"
-                      : "cursor-default !text-white/40"
-                }`}
+        </HookPanel>
+
+        <HookPanel title="Page size">
+          <div className="flex flex-wrap gap-3">
+            {PAGE_SIZE_OPTIONS.map((size) => (
+              <HookControlButton
+                key={size}
+                onClick={() => setPageSize(size)}
+                variant={pageSize === size ? "info" : "default"}
               >
-                {page > 0 ? page : "..."}
-              </button>
+                {size} per page
+              </HookControlButton>
             ))}
           </div>
-        </div>
+        </HookPanel>
+
+        <HookPanel title="Visible pages">
+          <div className="flex flex-wrap gap-3">
+            {visiblePages.map((page, index) =>
+              page > 0 ? (
+                <HookControlButton
+                  key={`${page}-${index}`}
+                  onClick={() => {
+                    setPage(page)
+                    setGoToPageValue(String(page))
+                  }}
+                  variant={page === currentPage ? "info" : "default"}
+                >
+                  {page}
+                </HookControlButton>
+              ) : (
+                <div
+                  key={`ellipsis-${index}`}
+                  className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-tertiary flex min-w-11 items-center justify-center rounded-lg border px-4 py-2 text-sm"
+                >
+                  ...
+                </div>
+              )
+            )}
+          </div>
+        </HookPanel>
 
-        {/* Direct Page Input */}
-        <div className="!space-y-2">
-          <label className="!text-sm font-medium !text-white">Go to Page</label>
-          <div className="flex gap-2">
+        <HookPanel title="Jump to page">
+          <div className="flex flex-wrap gap-3">
             <input
               type="number"
               min="1"
               max={totalPages}
-              value={currentPage}
-              onChange={(e) => {
-                const page = parseInt(e.target.value)
-                if (!isNaN(page)) setPage(page)
-              }}
-              className="w-20 rounded-lg border border-white/20 bg-white/5 !px-3 !py-2 !text-sm !text-white placeholder-white/50"
+              value={goToPageValue}
+              onChange={(event) => setGoToPageValue(event.target.value)}
+              className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder:text-fm-tertiary w-28 rounded-lg border px-4 py-2 text-sm"
             />
-            <span className="flex items-center !text-sm !text-white/60">
-              of {totalPages}
-            </span>
+            <HookControlButton onClick={commitPageInput} variant="warning">
+              Apply page
+            </HookControlButton>
+            <p className="text-fm-secondary font-fm-text text-fm-sm self-center">
+              Enter any number from 1 to {totalPages}.
+            </p>
           </div>
-        </div>
-
-        {/* Status Information */}
-        <div className="rounded-lg border border-white/10 bg-black/20 !p-4">
-          <div className="!space-y-1 !text-sm">
-            <div className="!text-white/70">
-              <span className="font-medium !text-white">State:</span>{" "}
-              isFirstPage: {String(isFirstPage)}, isLastPage:{" "}
-              {String(isLastPage)}
-            </div>
-            <div className="!text-white/70">
-              <span className="font-medium !text-white">Items:</span> Showing{" "}
-              {(currentPage - 1) * pageSize + 1}-
-              {Math.min(currentPage * pageSize, totalItems)} of {totalItems}
-            </div>
-            <div className="!text-white/70">
-              <span className="font-medium !text-white">Pages:</span>{" "}
-              {currentPage} of {totalPages}
-            </div>
-          </div>
-        </div>
+        </HookPanel>
+
+        <HookPanel title="Current slice">
+          <HookCodeBlock code={pageRows.join("\n")} />
+        </HookPanel>
+
+        <HookCodeBlock
+          code={`const pagination = useStandalonePagination({
+  totalItems: 126,
+  initialPage: 4,
+  initialPageSize: 10,
+  siblingCount: 1,
+})`}
+        />
       </div>
-    </div>
+    </HookPlaygroundCanvas>
   )
 }
 
-const meta: Meta<typeof PaginationDemo> = {
+const meta: Meta<typeof PaginationPlaygroundDemo> = {
   title: "Hooks/useStandalonePagination",
-  component: PaginationDemo,
+  component: PaginationPlaygroundDemo,
   parameters: {
     layout: "fullscreen",
     backgrounds: {
       default: "dark",
       values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "darker", value: "#000000" },
-        { name: "light", value: "#ffffff" },
+        { name: "dark", value: "var(--color-fm-surface-primary)" },
+        { name: "darker", value: "var(--color-fm-neutral-0)" },
+        { name: "light", value: "var(--color-fm-neutral-1100)" },
       ],
     },
     docs: {
       page: () => (
-        <>
-          {/* Override default docs styling */}
-          <style>
-            {`
-              .sbdocs-wrapper {
-                padding: 0 !important;
-                max-width: none !important;
-                background: transparent !important;
-              }
-              .sbdocs-content {
-                max-width: none !important;
-                padding: 0 !important;
-                margin: 0 !important;
-                background: transparent !important;
-              }
-              .docs-story {
-                background: transparent !important;
-              }
-              .sbdocs {
-                background: transparent !important;
-              }
-              body {
-                background: #0a0a0a !important;
-              }
-              #storybook-docs {
-                background: #0a0a0a !important;
-              }
-              .sbdocs-preview {
-                background: transparent !important;
-                border: none !important;
-              }
-              .sbdocs-h1, .sbdocs-h2, .sbdocs-h3, .sbdocs-h4, .sbdocs-h5, .sbdocs-h6 {
-                color: white !important;
-              }
-              .sbdocs-p, .sbdocs-li {
-                color: rgba(255, 255, 255, 0.7) !important;
-              }
-              .sbdocs-code {
-                background: rgba(255, 255, 255, 0.1) !important;
-                color: rgba(168, 85, 247, 1) !important;
-                border: 1px solid rgba(255, 255, 255, 0.1) !important;
-              }
-              .sbdocs-pre {
-                background: rgba(0, 0, 0, 0.4) !important;
-                border: 1px solid rgba(255, 255, 255, 0.1) !important;
-              }
-              .sbdocs-table {
-                background: rgba(255, 255, 255, 0.05) !important;
-                border: 1px solid rgba(255, 255, 255, 0.1) !important;
-              }
-              .sbdocs-table th {
-                background: rgba(255, 255, 255, 0.05) !important;
-                color: white !important;
-                border-bottom: 1px solid rgba(255, 255, 255, 0.1) !important;
-              }
-              .sbdocs-table td {
-                color: rgba(255, 255, 255, 0.7) !important;
-                border-bottom: 1px solid rgba(255, 255, 255, 0.05) !important;
-              }
-            `}
-          </style>
-
-          <div className="min-h-screen bg-gradient-to-br from-gray-900 via-indigo-900/20 to-gray-900">
-            {/* Header */}
-            <div className="relative overflow-hidden border-b border-white/10 bg-black/20 backdrop-blur-xl">
-              <div className="absolute inset-0 bg-gradient-to-r from-indigo-500/10 via-transparent to-purple-500/10" />
-              <div className="relative !mx-auto max-w-7xl !px-6 !py-16">
-                <div className="!space-y-6 text-center">
-                  <div className="!mx-auto flex !h-24 !w-24 items-center justify-center rounded-2xl border border-indigo-500/30 bg-gradient-to-br from-indigo-500/20 to-purple-500/20">
-                    <span className="!text-4xl">📄</span>
-                  </div>
-                  <h1 className="!text-fm-primary !text-5xl font-bold">
-                    useStandalonePagination
-                  </h1>
-                  <p className="!mx-auto max-w-3xl !text-xl leading-relaxed !text-white/70">
-                    A comprehensive React hook for managing pagination state
-                    without external data dependencies. Perfect for client-side
-                    pagination, API integration, and complex data navigation
-                    scenarios.
-                  </p>
-
-                  {/* Stats */}
-                  <div className="flex items-center justify-center gap-8 !pt-8">
-                    <div className="text-center">
-                      <div className="!text-3xl font-bold !text-indigo-300">
-                        Stateful
-                      </div>
-                      <div className="!text-sm !text-white/60">
-                        Complete state management
-                      </div>
-                    </div>
-                    <div className="!h-8 !w-px bg-white/20" />
-                    <div className="text-center">
-                      <div className="!text-3xl font-bold !text-purple-300">
-                        Flexible
-                      </div>
-                      <div className="!text-sm !text-white/60">
-                        Configurable page sizes
-                      </div>
-                    </div>
-                    <div className="!h-8 !w-px bg-white/20" />
-                    <div className="text-center">
-                      <div className="!text-3xl font-bold !text-cyan-300">
-                        Smart
-                      </div>
-                      <div className="!text-sm !text-white/60">
-                        Intelligent page calculation
-                      </div>
-                    </div>
-                  </div>
-                </div>
-              </div>
-            </div>
-
-            {/* Content */}
-            <div className="!mx-auto max-w-7xl !space-y-16 !px-6 !py-12">
-              {/* Quick Usage */}
-              <div className="!space-y-8">
-                <h2 className="text-center !text-3xl font-bold !text-white">
-                  Quick Start
-                </h2>
-                <div className="grid grid-cols-1 gap-8 lg:grid-cols-2">
-                  <div className="!space-y-4">
-                    <h3 className="!text-xl font-semibold !text-indigo-300">
-                      Basic Usage
-                    </h3>
-                    <div className="rounded-lg bg-black/40 !p-4">
-                      <pre className="overflow-x-auto !text-sm !text-green-300">
-                        {`import { useStandalonePagination } from "@hooks/use-standalone-pagination"
-
-function MyComponent() {
+        <AuralHookDocsPage
+          icon={LayoutColumnIcon}
+          features={[
+            { title: "Stateful", description: "Complete pagination state" },
+            { title: "Adaptive", description: "Keeps visible items stable" },
+            { title: "Smart", description: "Builds ellipsis ranges" },
+          ]}
+          quickStart={{
+            codeExample: `import { useStandalonePagination } from "src/ui/hooks/use-standalone-pagination"
+
+function ResultsList({ totalItems }: { totalItems: number }) {
   const {
     currentPage,
     totalPages,
-    setPage,
     nextPage,
     prevPage,
     visiblePages,
-    isFirstPage,
-    isLastPage
   } = useStandalonePagination({
-    totalItems: 1000,
+    totalItems,
     initialPageSize: 10,
-    siblingCount: 1
+    siblingCount: 1,
   })
 
   return (
-    <div>
-      <div>Page {currentPage} of {totalPages}</div>
-      <div>
-        {visiblePages.map(page => (
-          <button 
-            key={page}
-            onClick={() => page > 0 && setPage(page)}
-            disabled={page < 0}
-          >
-            {page > 0 ? page : "..."}
-          </button>
-        ))}
-      </div>
-    </div>
+    <section>
+      <p>{currentPage} / {totalPages}</p>
+      <button onClick={prevPage}>Prev</button>
+      <button onClick={nextPage}>Next</button>
+      <div>{visiblePages.join(", ")}</div>
+    </section>
   )
-}`}
-                      </pre>
-                    </div>
-                  </div>
-
-                  <div className="!space-y-4">
-                    <h3 className="!text-xl font-semibold !text-indigo-300">
-                      Hook Properties
-                    </h3>
-                    <div className="!space-y-3 rounded-lg border border-white/10 bg-white/5 !p-4">
-                      <div className="flex justify-between">
-                        <span className="!text-sm !text-white/70">
-                          Total Items:
-                        </span>
-                        <span className="!text-sm font-medium !text-white">
-                          Configurable
-                        </span>
-                      </div>
-                      <div className="flex justify-between">
-                        <span className="!text-sm !text-white/70">
-                          Page Size:
-                        </span>
-                        <span className="!text-sm font-medium !text-white">
-                          Dynamic
-                        </span>
-                      </div>
-                      <div className="flex justify-between">
-                        <span className="!text-sm !text-white/70">
-                          Sibling Count:
-                        </span>
-                        <span className="!text-sm font-medium !text-white">
-                          Customizable
-                        </span>
-                      </div>
-                      <div className="flex justify-between">
-                        <span className="!text-sm !text-white/70">
-                          Navigation:
-                        </span>
-                        <span className="!text-sm font-medium !text-white">
-                          Built-in
-                        </span>
-                      </div>
-                    </div>
-                  </div>
-                </div>
-              </div>
-
-              {/* Props Documentation */}
-              <div className="!space-y-8">
-                <h2 className="text-center !text-3xl font-bold !text-white">
-                  Props & Configuration
-                </h2>
-
-                <div className="overflow-hidden rounded-lg border border-white/10 bg-white/5">
-                  <div className="bg-white/5 !p-4">
-                    <h3 className="!text-xl font-semibold !text-white">
-                      Input Props
-                    </h3>
-                  </div>
-                  <table className="!my-0 w-full">
-                    <thead className="bg-white/5">
-                      <tr className="border-b border-white/10">
-                        <th className="!px-6 !py-4 text-left !text-sm font-semibold !text-white">
-                          Prop
-                        </th>
-                        <th className="!px-6 !py-4 text-left !text-sm font-semibold !text-white">
-                          Type
-                        </th>
-                        <th className="!px-6 !py-4 text-left !text-sm font-semibold !text-white">
-                          Default
-                        </th>
-                        <th className="!px-6 !py-4 text-left !text-sm font-semibold !text-white">
-                          Description
-                        </th>
-                      </tr>
-                    </thead>
-                    <tbody>
-                      <tr className="border-b border-white/5">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-indigo-300">
-                          totalItems
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          number
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/50">
-                          required
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Total number of items to paginate
-                        </td>
-                      </tr>
-                      <tr className="border-b border-white/5 !bg-black/10">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-indigo-300">
-                          initialPage
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          number
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/50">
-                          1
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Starting page number
-                        </td>
-                      </tr>
-                      <tr className="border-b border-white/5">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-indigo-300">
-                          initialPageSize
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          number
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/50">
-                          10
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Number of items per page
-                        </td>
-                      </tr>
-                      <tr className="!bg-black/10">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-indigo-300">
-                          siblingCount
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          number
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/50">
-                          1
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Number of sibling pages to show around current page
-                        </td>
-                      </tr>
-                    </tbody>
-                  </table>
-                </div>
-
-                <div className="overflow-hidden rounded-lg border border-white/10 bg-white/5">
-                  <div className="bg-white/5 !p-4">
-                    <h3 className="!text-xl font-semibold !text-white">
-                      Return Values
-                    </h3>
-                  </div>
-                  <table className="!my-0 w-full">
-                    <thead className="bg-white/5">
-                      <tr className="border-b border-white/10">
-                        <th className="!px-6 !py-4 text-left !text-sm font-semibold !text-white">
-                          Property
-                        </th>
-                        <th className="!px-6 !py-4 text-left !text-sm font-semibold !text-white">
-                          Type
-                        </th>
-                        <th className="!px-6 !py-4 text-left !text-sm font-semibold !text-white">
-                          Description
-                        </th>
-                      </tr>
-                    </thead>
-                    <tbody>
-                      <tr className="border-b border-white/5">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-indigo-300">
-                          currentPage
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          number
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Current active page number
-                        </td>
-                      </tr>
-                      <tr className="border-b border-white/5 !bg-black/10">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-indigo-300">
-                          totalPages
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          number
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Total number of pages
-                        </td>
-                      </tr>
-                      <tr className="border-b border-white/5">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-indigo-300">
-                          setPage
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">{`(page: number) => void`}</td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Navigate to specific page
-                        </td>
-                      </tr>
-                      <tr className="border-b border-white/5 !bg-black/10">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-indigo-300">
-                          nextPage
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">{`() => void`}</td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Navigate to next page
-                        </td>
-                      </tr>
-                      <tr className="border-b border-white/5">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-indigo-300">
-                          prevPage
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">{`() => void`}</td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Navigate to previous page
-                        </td>
-                      </tr>
-                      <tr className="border-b border-white/5 !bg-black/10">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-indigo-300">
-                          visiblePages
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          number[]
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Array of page numbers to display (negative values
-                          represent dots)
-                        </td>
-                      </tr>
-                      <tr className="border-b border-white/5">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-indigo-300">
-                          isFirstPage
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          boolean
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Whether currently on first page
-                        </td>
-                      </tr>
-                      <tr className="!bg-black/10">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-indigo-300">
-                          isLastPage
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          boolean
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Whether currently on last page
-                        </td>
-                      </tr>
-                    </tbody>
-                  </table>
-                </div>
-              </div>
-
-              {/* Features */}
-              <div className="!space-y-8">
-                <h2 className="text-center !text-3xl font-bold !text-white">
-                  Key Features
-                </h2>
-                <div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
-                  <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                    <div className="!mb-4 flex !h-12 !w-12 items-center justify-center rounded-lg bg-blue-500/20">
-                      <span className="!text-2xl">🔄</span>
-                    </div>
-                    <h3 className="!mb-2 !text-lg font-semibold !text-white">
-                      State Management
-                    </h3>
-                    <p className="!text-sm !text-white/70">
-                      Complete pagination state with automatic page validation
-                      and boundary checks.
-                    </p>
-                  </div>
-
-                  <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                    <div className="!mb-4 flex !h-12 !w-12 items-center justify-center rounded-lg bg-green-500/20">
-                      <span className="!text-2xl">📊</span>
-                    </div>
-                    <h3 className="!mb-2 !text-lg font-semibold !text-white">
-                      Smart Pagination
-                    </h3>
-                    <p className="!text-sm !text-white/70">
-                      Intelligent page number calculation with customizable
-                      sibling count and ellipsis.
-                    </p>
-                  </div>
-
-                  <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                    <div className="!mb-4 flex !h-12 !w-12 items-center justify-center rounded-lg bg-purple-500/20">
-                      <span className="!text-2xl">⚙️</span>
-                    </div>
-                    <h3 className="!mb-2 !text-lg font-semibold !text-white">
-                      Dynamic Page Size
-                    </h3>
-                    <p className="!text-sm !text-white/70">
-                      Change page size on the fly with automatic page adjustment
-                      to maintain context.
-                    </p>
-                  </div>
-
-                  <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                    <div className="!mb-4 flex !h-12 !w-12 items-center justify-center rounded-lg bg-orange-500/20">
-                      <span className="!text-2xl">🎯</span>
-                    </div>
-                    <h3 className="!mb-2 !text-lg font-semibold !text-white">
-                      Navigation Methods
-                    </h3>
-                    <p className="!text-sm !text-white/70">
-                      Multiple navigation options: next, previous, first, last,
-                      and direct page selection.
-                    </p>
-                  </div>
-
-                  <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                    <div className="!mb-4 flex !h-12 !w-12 items-center justify-center rounded-lg bg-cyan-500/20">
-                      <span className="!text-2xl">🔍</span>
-                    </div>
-                    <h3 className="!mb-2 !text-lg font-semibold !text-white">
-                      State Indicators
-                    </h3>
-                    <p className="!text-sm !text-white/70">
-                      Built-in boolean flags for first/last page states and
-                      comprehensive pagination info.
-                    </p>
-                  </div>
-
-                  <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                    <div className="!mb-4 flex !h-12 !w-12 items-center justify-center rounded-lg bg-pink-500/20">
-                      <span className="!text-2xl">⚡</span>
-                    </div>
-                    <h3 className="!mb-2 !text-lg font-semibold !text-white">
-                      Performance Optimized
-                    </h3>
-                    <p className="!text-sm !text-white/70">
-                      Memoized calculations and optimized re-renders for smooth
-                      user experience.
-                    </p>
-                  </div>
-                </div>
-              </div>
-
-              {/* Usage Patterns */}
-              <div className="!space-y-8">
-                <h2 className="text-center !text-3xl font-bold !text-white">
-                  Usage Patterns
-                </h2>
-                <div className="grid grid-cols-1 gap-8 lg:grid-cols-2">
-                  <div className="!space-y-4">
-                    <h3 className="!text-xl font-semibold !text-indigo-300">
-                      Table Pagination
-                    </h3>
-                    <div className="rounded-lg bg-black/40 !p-4">
-                      <pre className="overflow-x-auto !text-sm !text-green-300">
-                        {`// Table with pagination
-function DataTable({ data }) {
-  const {
-    currentPage,
-    pageSize,
-    setPage,
-    setPageSize,
-    visiblePages
-  } = useStandalonePagination({
-    totalItems: data.length,
-    initialPageSize: 10
+}`,
+            hookProperties: [
+              { label: "Returns", value: "Full pagination controller" },
+              { label: "Range model", value: "Ellipsis aware pages" },
+              { label: "Page sizing", value: "Keeps item position stable" },
+              { label: "Best for", value: "Client side pagination UIs" },
+            ],
+          }}
+          hookSignature={`function useStandalonePagination({
+  initialPage,
+  initialPageSize,
+  totalItems,
+  siblingCount,
+}: UseStandalonePaginationProps): UseStandalonePaginationReturn`}
+          parameters={[
+            {
+              name: "initialPage",
+              type: "number",
+              description: "Starting page for the pagination state.",
+            },
+            {
+              name: "initialPageSize",
+              type: "number",
+              description: "Initial number of items shown per page.",
+            },
+            {
+              name: "totalItems",
+              type: "number",
+              required: true,
+              description: "Total item count used to derive total pages.",
+            },
+            {
+              name: "siblingCount",
+              type: "number",
+              description:
+                "How many pages to show on each side of the current page.",
+            },
+          ]}
+          returns={[
+            {
+              name: "currentPage",
+              type: "number",
+              description: "Active page currently selected.",
+            },
+            {
+              name: "totalPages",
+              type: "number",
+              description: "Derived page count from totalItems and pageSize.",
+            },
+            {
+              name: "pageSize",
+              type: "number",
+              description: "Current items-per-page value.",
+            },
+            {
+              name: "totalItems",
+              type: "number",
+              description: "Echo of the provided total item count.",
+            },
+            {
+              name: "setPage",
+              type: "(page: number) => void",
+              description: "Moves to a clamped page within valid bounds.",
+            },
+            {
+              name: "nextPage",
+              type: "() => void",
+              description: "Advances one page unless already at the end.",
+            },
+            {
+              name: "prevPage",
+              type: "() => void",
+              description: "Moves back one page unless already at the start.",
+            },
+            {
+              name: "firstPage",
+              type: "() => void",
+              description: "Jumps directly to page one.",
+            },
+            {
+              name: "lastPage",
+              type: "() => void",
+              description: "Jumps directly to the final page.",
+            },
+            {
+              name: "setPageSize",
+              type: "(size: number) => void",
+              description:
+                "Updates page size and recalculates the best matching page.",
+            },
+            {
+              name: "isFirstPage",
+              type: "boolean",
+              description: "True when the current page is page one.",
+            },
+            {
+              name: "isLastPage",
+              type: "boolean",
+              description: "True when the current page is the last page.",
+            },
+            {
+              name: "visiblePages",
+              type: "number[]",
+              description:
+                "Page model used to render pagination controls, including negative sentinel values for ellipsis slots.",
+            },
+          ]}
+          useCases={[
+            {
+              icon: SearchIcon,
+              title: "Search Results",
+              description:
+                "Power a client-side results grid with next, previous, and jump controls.",
+            },
+            {
+              icon: FileTextIcon,
+              title: "Article Lists",
+              description:
+                "Paginate long editorial archives while keeping visible ranges readable.",
+            },
+            {
+              icon: NotepadIcon,
+              title: "Admin Tables",
+              description:
+                "Handle back-office lists where users often change page size and jump far ahead.",
+            },
+            {
+              icon: PageTextIcon,
+              title: "Document Browsing",
+              description:
+                "Show page context for readers moving across long sets of content or records.",
+            },
+            {
+              icon: SettingIcon,
+              title: "Configurable Views",
+              description:
+                "Expose page-size controls when operators need dense or compact list views.",
+            },
+            {
+              icon: FeatureShineIcon,
+              title: "Hybrid APIs",
+              description:
+                "Reuse the same state machine to drive local slicing or remote fetch parameters.",
+            },
+          ]}
+          usagePatterns={[
+            {
+              title: "Paginating a Local Array",
+              code: `function TracksTable({ tracks }: { tracks: Track[] }) {
+  const pagination = useStandalonePagination({
+    totalItems: tracks.length,
+    initialPageSize: 20,
   })
 
-  const startIndex = (currentPage - 1) * pageSize
-  const paginatedData = data.slice(
-    startIndex, 
-    startIndex + pageSize
-  )
+  const start = (pagination.currentPage - 1) * pagination.pageSize
+  const end = start + pagination.pageSize
+  const rows = tracks.slice(start, end)
 
-  return (
-    <div>
-      <table>
-        {paginatedData.map(item => (
-          <tr key={item.id}>
-            <td>{item.name}</td>
-          </tr>
-        ))}
-      </table>
-      
-      <PaginationControls 
-        visiblePages={visiblePages}
-        onPageChange={setPage}
-      />
-    </div>
-  )
-}`}
-                      </pre>
-                    </div>
-                  </div>
-
-                  <div className="!space-y-4">
-                    <h3 className="!text-xl font-semibold !text-indigo-300">
-                      API Integration
-                    </h3>
-                    <div className="rounded-lg bg-black/40 !p-4">
-                      <pre className="overflow-x-auto !text-sm !text-green-300">
-                        {`// API with pagination
-function ApiDataList() {
-  const [data, setData] = useState([])
-  const [totalItems, setTotalItems] = useState(0)
-  
+  return <Table rows={rows} />
+}`,
+            },
+            {
+              title: "Driving a Remote Query",
+              code: `function AuditLog() {
   const pagination = useStandalonePagination({
-    totalItems,
-    initialPageSize: 20
+    totalItems: 500,
+    initialPageSize: 25,
+    siblingCount: 2,
   })
 
   useEffect(() => {
-    fetchData({
+    fetchLogs({
       page: pagination.currentPage,
-      limit: pagination.pageSize
-    }).then(response => {
-      setData(response.data)
-      setTotalItems(response.total)
+      limit: pagination.pageSize,
     })
   }, [pagination.currentPage, pagination.pageSize])
 
-  return (
-    <div>
-      <DataList items={data} />
-      <Pagination {...pagination} />
-    </div>
+  return <LogView pagination={pagination} />
+}`,
+            },
+            {
+              title: "Persisting Page Size",
+              code: `function SavedPreferenceList({ totalItems }: Props) {
+  const initialPageSize = Number(localStorage.getItem("pageSize") ?? 10)
+  const { pageSize, setPageSize, ...pagination } = useStandalonePagination({
+    totalItems,
+    initialPageSize,
+  })
+
+  useEffect(() => {
+    localStorage.setItem("pageSize", String(pageSize))
+  }, [pageSize])
+
+  return <ListControls pageSize={pageSize} setPageSize={setPageSize} />
+}`,
+            },
+          ]}
+          implementation={{
+            code: `import { useCallback, useEffect, useMemo, useState } from "react"
+
+export interface UseStandalonePaginationProps {
+  initialPage?: number
+  initialPageSize?: number
+  totalItems: number
+  siblingCount?: number
+}
+
+export interface UseStandalonePaginationReturn {
+  currentPage: number
+  totalPages: number
+  pageSize: number
+  totalItems: number
+  setPage: (page: number) => void
+  nextPage: () => void
+  prevPage: () => void
+  firstPage: () => void
+  lastPage: () => void
+  setPageSize: (size: number) => void
+  isFirstPage: boolean
+  isLastPage: boolean
+  visiblePages: number[]
+}
+
+export const useStandalonePagination = ({
+  initialPage = 1,
+  initialPageSize = 10,
+  totalItems,
+  siblingCount = 1,
+}: UseStandalonePaginationProps): UseStandalonePaginationReturn => {
+  const [currentPage, setCurrentPage] = useState<number>(initialPage)
+  const [pageSize, setPageSize] = useState<number>(initialPageSize)
+
+  const totalPages = useMemo(
+    () => Math.max(1, Math.ceil(totalItems / pageSize)),
+    [totalItems, pageSize]
   )
-}`}
-                      </pre>
-                    </div>
-                  </div>
-                </div>
-              </div>
-            </div>
-
-            {/* Footer */}
-            <div className="border-t border-white/10 bg-black/20 backdrop-blur-xl">
-              <div className="!mx-auto max-w-7xl !px-6 !py-8">
-                <div className="!space-y-4 text-center">
-                  <p className="!text-white/60">
-                    useStandalonePagination provides complete pagination logic
-                    without external dependencies, making it perfect for any
-                    data display scenario.
-                  </p>
-                  <p className="!text-sm !text-white/40">
-                    Built with performance and developer experience in mind,
-                    featuring TypeScript support and comprehensive state
-                    management.
-                  </p>
-                </div>
-              </div>
-            </div>
-          </div>
-        </>
+
+  useEffect(() => {
+    if (currentPage > totalPages) {
+      setCurrentPage(totalPages)
+    }
+  }, [totalPages, currentPage])
+
+  const isFirstPage = currentPage === 1
+  const isLastPage = currentPage === totalPages
+
+  const setPage = useCallback(
+    (page: number) => {
+      const validPage = Math.min(Math.max(1, page), totalPages)
+      setCurrentPage(validPage)
+    },
+    [totalPages]
+  )
+
+  const nextPage = useCallback(() => {
+    if (!isLastPage) {
+      setCurrentPage((prev) => prev + 1)
+    }
+  }, [isLastPage])
+
+  const prevPage = useCallback(() => {
+    if (!isFirstPage) {
+      setCurrentPage((prev) => prev - 1)
+    }
+  }, [isFirstPage])
+
+  const firstPage = useCallback(() => {
+    setCurrentPage(1)
+  }, [])
+
+  const lastPage = useCallback(() => {
+    setCurrentPage(totalPages)
+  }, [totalPages])
+
+  const updatePageSize = useCallback(
+    (size: number) => {
+      setPageSize(size)
+      const firstItemIndex = (currentPage - 1) * pageSize
+      const newPage = Math.floor(firstItemIndex / size) + 1
+      setCurrentPage(Math.min(newPage, Math.ceil(totalItems / size)))
+    },
+    [currentPage, pageSize, totalItems]
+  )
+
+  const visiblePages = useMemo(() => {
+    const range = (start: number, end: number): number[] => {
+      return Array.from({ length: end - start + 1 }, (_, i) => start + i)
+    }
+
+    const totalPageNumbers = siblingCount * 2 + 3
+
+    if (totalPages <= totalPageNumbers) {
+      return range(1, totalPages)
+    }
+
+    const leftSiblingIndex = Math.max(currentPage - siblingCount, 1)
+    const rightSiblingIndex = Math.min(currentPage + siblingCount, totalPages)
+
+    const shouldShowLeftDots = leftSiblingIndex > 2
+    const shouldShowRightDots = rightSiblingIndex < totalPages - 1
+
+    if (!shouldShowLeftDots && shouldShowRightDots) {
+      const leftItemCount = 3 + 2 * siblingCount
+      return [...range(1, leftItemCount), -1, totalPages]
+    }
+
+    if (shouldShowLeftDots && !shouldShowRightDots) {
+      const rightItemCount = 3 + 2 * siblingCount
+      return [1, -1, ...range(totalPages - rightItemCount + 1, totalPages)]
+    }
+
+    return [
+      1,
+      -1,
+      ...range(leftSiblingIndex, rightSiblingIndex),
+      -2,
+      totalPages,
+    ]
+  }, [currentPage, totalPages, siblingCount])
+
+  return {
+    currentPage,
+    totalPages,
+    pageSize,
+    totalItems,
+    setPage,
+    nextPage,
+    prevPage,
+    firstPage,
+    lastPage,
+    setPageSize: updatePageSize,
+    isFirstPage,
+    isLastPage,
+    visiblePages,
+  }
+}`,
+            notes: [
+              "The hook centralizes all pagination transitions so consuming components can stay focused on rendering.",
+              "Changing page size preserves the currently visible item range as closely as possible instead of blindly resetting to page one.",
+              "The visiblePages array uses sentinel values for ellipsis slots, which keeps pagination UIs compact without hiding the first or last page.",
+            ],
+          }}
+        />
       ),
     },
   },
   tags: ["autodocs"],
   argTypes: {
+    label: {
+      control: "text",
+      description: "Label shown for the currently visible item range.",
+    },
     totalItems: {
-      control: { type: "number", min: 1, max: 10000, step: 1 },
-      description: "Total number of items to paginate",
+      control: { type: "number" },
+      description: "Total number of items in the dataset.",
     },
     initialPage: {
-      control: { type: "number", min: 1, max: 100, step: 1 },
-      description: "Starting page number",
+      control: { type: "number" },
+      description: "Initial current page.",
     },
     initialPageSize: {
-      control: { type: "select", options: [5, 10, 20, 50, 100] },
-      description: "Number of items per page",
+      control: { type: "number" },
+      description: "Initial number of items per page.",
     },
     siblingCount: {
-      control: { type: "number", min: 0, max: 5, step: 1 },
-      description: "Number of sibling pages to show around current page",
-    },
-    title: {
-      control: "text",
-      description: "Title for the demo component",
+      control: { type: "number" },
+      description: "How many neighboring page numbers stay visible.",
     },
   },
 }
 
 export default meta
-type Story = StoryObj<typeof PaginationDemo>
-
-// Story parameters for consistent dark theme
-const storyParameters = {
-  backgrounds: {
-    default: "dark",
-    values: [
-      { name: "dark", value: "#0a0a0a" },
-      { name: "darker", value: "#000000" },
-    ],
-  },
-}
+type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
+export const Playground: Story = {
   args: {
-    totalItems: 100,
-    initialPage: 1,
+    label: "Dataset",
+    totalItems: 126,
+    initialPage: 4,
     initialPageSize: 10,
     siblingCount: 1,
-    title: "Basic Pagination",
   },
-  parameters: storyParameters,
-  render: (args) => (
-    <div className="min-h-dvh bg-gradient-to-br from-gray-900 to-gray-800 !p-8">
-      <PaginationDemo {...args} />
-    </div>
-  ),
+  render: (args) => <PaginationPlaygroundDemo {...args} />,
 }
 
-export const LargeDataset: Story = {
-  args: {
-    totalItems: 10000,
-    initialPage: 50,
-    initialPageSize: 20,
-    siblingCount: 2,
-    title: "Large Dataset Pagination",
-  },
-  parameters: {
-    ...storyParameters,
-    docs: {
-      description: {
-        story:
-          "Pagination with a large dataset showing intelligent page number calculation.",
-      },
-    },
-  },
-  render: (args) => (
-    <div className="min-h-dvh bg-gradient-to-br from-gray-900 to-gray-800 !p-8">
-      <PaginationDemo {...args} />
-    </div>
-  ),
+export const Interactive: Story = {
+  render: () => <PaginationInteractiveDemo />,
 }
 
-export const SmallDataset: Story = {
-  args: {
-    totalItems: 25,
-    initialPage: 1,
-    initialPageSize: 5,
-    siblingCount: 1,
-    title: "Small Dataset Pagination",
-  },
-  parameters: {
-    ...storyParameters,
-    docs: {
-      description: {
-        story: "Pagination with a small dataset where all pages are visible.",
-      },
-    },
-  },
-  render: (args) => (
-    <div className="min-h-dvh bg-gradient-to-br from-gray-900 to-gray-800 !p-8">
-      <PaginationDemo {...args} />
-    </div>
-  ),
-}
+export const UseCases: Story = {
+  render: () => (
+    <HookUsageCanvas>
+      <HookUsageSection title="Client-side search results">
+        <HookCodeBlock
+          code={`function SearchResults({ results }: { results: Result[] }) {
+  const pagination = useStandalonePagination({
+    totalItems: results.length,
+    initialPageSize: 20,
+  })
 
-export const CustomSiblingCount: Story = {
-  args: {
-    totalItems: 1000,
-    initialPage: 25,
-    initialPageSize: 10,
-    siblingCount: 3,
-    title: "Custom Sibling Count",
-  },
-  parameters: {
-    ...storyParameters,
-    docs: {
-      description: {
-        story:
-          "Pagination with increased sibling count showing more page numbers around current page.",
-      },
-    },
-  },
-  render: (args) => (
-    <div className="min-h-dvh bg-gradient-to-br from-gray-900 to-gray-800 !p-8">
-      <PaginationDemo {...args} />
-    </div>
-  ),
-}
+  const start = (pagination.currentPage - 1) * pagination.pageSize
+  const pageResults = results.slice(start, start + pagination.pageSize)
 
-export const InteractiveDemo: Story = {
-  args: {
-    totalItems: 500,
-    initialPage: 1,
-    initialPageSize: 10,
-    siblingCount: 1,
-    title: "Interactive Pagination Demo",
-  },
-  parameters: {
-    ...storyParameters,
-    docs: {
-      description: {
-        story:
-          "Full interactive demo showing all features of the pagination hook with real-time state updates.",
-      },
-    },
-  },
-  render: (args) => (
-    <div className="min-h-dvh bg-gradient-to-br from-gray-900 to-gray-800 !p-8">
-      <div className="!space-y-8">
-        <PaginationDemo {...args} />
-      </div>
-    </div>
-  ),
-}
+  return <ResultsGrid results={pageResults} pagination={pagination} />
+}`}
+        />
+      </HookUsageSection>
 
-export const Playground: Story = {
-  parameters: {
-    ...storyParameters,
-    docs: {
-      description: {
-        story:
-          "Interactive playground to experiment with different pagination configurations.",
-      },
-    },
-  },
-  args: {
-    totalItems: 300,
-    initialPage: 5,
-    initialPageSize: 15,
+      <HookUsageSection title="Server-driven admin table">
+        <HookCodeBlock
+          code={`function OrdersTable() {
+  const pagination = useStandalonePagination({
+    totalItems: 240,
+    initialPageSize: 25,
     siblingCount: 2,
-    title: "Pagination Playground",
-  },
-  render: (args) => (
-    <div className="min-h-dvh bg-gradient-to-br from-gray-900 to-gray-800 !p-8">
-      <PaginationDemo {...args} />
-    </div>
+  })
+
+  useEffect(() => {
+    loadOrders({
+      page: pagination.currentPage,
+      pageSize: pagination.pageSize,
+    })
+  }, [pagination.currentPage, pagination.pageSize])
+
+  return <Table pagination={pagination} />
+}`}
+        />
+      </HookUsageSection>
+
+      <HookUsageSection title="Reader-friendly archive navigation">
+        <HookCodeBlock
+          code={`function Archive({ totalItems }: { totalItems: number }) {
+  const pagination = useStandalonePagination({
+    totalItems,
+    initialPageSize: 12,
+  })
+
+  return (
+    <footer>
+      <button onClick={pagination.prevPage}>Prev</button>
+      {pagination.visiblePages.map(renderPageButton)}
+      <button onClick={pagination.nextPage}>Next</button>
+    </footer>
+  )
+}`}
+        />
+      </HookUsageSection>
+    </HookUsageCanvas>
   ),
 }