@arbor-education/design-system.components 0.14.0 → 0.16.0

package/src/components/table/pagination/PaginationPanel.stories.tsx

@@ -0,0 +1,327 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { fn } from 'storybook/test';
+import { PaginationPanel } from './PaginationPanel';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`PaginationPanel` is the pre-composed footer slot for the Arbor data table.',
+  'It renders a three-part `<nav>`: a **row count** (how many rows are visible),',
+  '**page controls** (first / prev / page-number input / next / last), and a **page-size selector** dropdown.',
+  '',
+  'Every part is opt-in — only pass the props for the sections you need.',
+  'Pass the entire `<PaginationPanel />` element as the `footerContent` prop of `<Table />`.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- As the `footerContent` of a `<Table />` to give it standard pagination controls',
+  '- When you need a page-size selector alongside page navigation in a single composable component',
+  '- When implementing server-side pagination (pass `totalPages` + `onPageChange` + `onPageSizeChange`)',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Alternative |',
+  '|---|---|',
+  '| You only need page navigation | Use `PaginationControls` directly |',
+  '| You only need a page-size selector | Use `PageSizeSelector` directly |',
+  '| The table has no pagination | Omit `footerContent` entirely |',
+  '',
+  '---',
+  '',
+  '### Sub-component summary',
+  '',
+  '| Sub-component | Key props | Notes |',
+  '|---|---|---|',
+  '| `RowCountInfo` | `totalRows` | Returns `null` when used outside a `<Table />` — it reads row count from `GridApiContext` |',
+  '| `PaginationControls` | `totalPages`, `onPageChange` | Works standalone; falls back to `GridApiContext` when no props are passed |',
+  '| `PageSizeSelector` | `availableSizes`, `initialPageSize`, `onPageSizeChange` | Works standalone; falls back to `GridApiContext` when no props are passed |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Wiring into `<Table />`',
+  '',
+  '```tsx',
+  "import { Table, PaginationPanel } from '@arbor-education/design-system.components';",
+  '',
+  'function MyTable() {',
+  '  return (',
+  '    <Table',
+  '      rowData={rows}',
+  '      columnDefs={colDefs}',
+  '      footerContent={(',
+  '        <PaginationPanel',
+  '          availableSizes={[10, 25, 50, 100]}',
+  '          initialPageSize={25}',
+  '          onPageSizeChange={setPageSize}',
+  '        />',
+  '      )}',
+  '    />',
+  '  );',
+  '}',
+  '```',
+  '',
+  '---',
+  '',
+  '### Server-side pagination',
+  '',
+  'When your data is fetched page-by-page from an API, pass `totalPages` and `onPageChange`:',
+  '',
+  '```tsx',
+  'function ServerTable() {',
+  '  const [page, setPage] = useState(0);',
+  '  const [pageSize, setPageSize] = useState(25);',
+  '  const { data, totalPages } = useMyApiQuery({ page, pageSize });',
+  '',
+  '  return (',
+  '    <Table',
+  '      rowData={data}',
+  '      columnDefs={colDefs}',
+  '      footerContent={(',
+  '        <PaginationPanel',
+  '          totalPages={totalPages}',
+  '          onPageChange={setPage}',
+  '          availableSizes={[10, 25, 50]}',
+  '          initialPageSize={pageSize}',
+  '          onPageSizeChange={setPageSize}',
+  '        />',
+  '      )}',
+  '    />',
+  '  );',
+  '}',
+  '```',
+  '',
+  '---',
+  '',
+  '### `RowCountInfo` and `GridApiContext`',
+  '',
+  '`RowCountInfo` reads the displayed row count from `GridApiContext` — this context is provided',
+  'automatically by `<Table />`. When `PaginationPanel` is rendered outside a `<Table />`',
+  '(as in these Storybook stories), `RowCountInfo` returns `null` and the row-count text is not shown.',
+  'Pass `totalRows` to supply a value manually in server-side scenarios.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { PaginationPanel } from '@arbor-education/design-system.components';",
+  "import type { PaginationControlsProps, PageSizeSelectorProps, RowCountInfoProps } from '@arbor-education/design-system.components';",
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [TableControls](?path=/docs/components-table-tablecontrols--docs) · [Button](?path=/docs/components-button--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — toggle props to see the panel update in real time. Note that `RowCountInfo` (the row-count text on the left) only displays inside a `<Table />`; it returns `null` in this standalone preview.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function PaginationPanelDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
+  title: 'Components/Table/PaginationPanel',
+  component: PaginationPanel,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: PaginationPanelDocsPage },
+  },
+  argTypes: {
+    totalRows: {
+      description: 'Total number of rows in the dataset. Passed to `RowCountInfo` for the "Showing X of Y results" label. Only relevant when used outside a `<Table />` (which provides this automatically via `GridApiContext`).',
+      control: 'number',
+      table: { type: { summary: 'number' }, defaultValue: { summary: 'undefined' } },
+    },
+    totalPages: {
+      description: 'Total number of pages. Passed to `PaginationControls`. Required for server-side pagination; when omitted the control reads from `GridApiContext`.',
+      control: 'number',
+      table: { type: { summary: 'number' }, defaultValue: { summary: 'undefined' } },
+    },
+    onPageChange: {
+      description: 'Called with the zero-indexed new page number when the user navigates. Required for server-side pagination; when omitted the control drives the AG Grid API directly.',
+      control: false,
+      table: { type: { summary: '(newPage: number) => void' }, defaultValue: { summary: 'undefined' } },
+    },
+    availableSizes: {
+      description: 'Array of page sizes shown in the `PageSizeSelector` dropdown. Defaults to `[10, 20, 30, 50, 100, 200, 300, 500, 1000, "All"]`.',
+      control: false,
+      table: { type: { summary: '(number | "All")[]' }, defaultValue: { summary: 'undefined' } },
+    },
+    initialPageSize: {
+      description: 'The initially selected page size in the `PageSizeSelector`.',
+      control: 'number',
+      table: { type: { summary: 'number | "All"' }, defaultValue: { summary: 'undefined' } },
+    },
+    onPageSizeChange: {
+      description: 'Called with the newly selected page size when the user changes it. Required for server-side pagination; when omitted the control drives the AG Grid API directly.',
+      control: false,
+      table: { type: { summary: '(newPageSize: number | "All") => void' }, defaultValue: { summary: 'undefined' } },
+    },
+    className: {
+      description: 'Additional CSS class name(s) to apply to the root `<nav>` element.',
+      control: 'text',
+      table: { type: { summary: 'string' }, defaultValue: { summary: 'undefined' } },
+    },
+  },
+  args: {
+    onPageChange: fn(),
+    onPageSizeChange: fn(),
+  },
+} satisfies Meta<typeof PaginationPanel>;
+
+export default meta;
+type Story = StoryObj<typeof PaginationPanel>;
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      totalPages: 10,
+      onPageChange: fn(),
+      availableSizes: [10, 25, 50, 100],
+      initialPageSize: 25,
+      onPageSizeChange: fn(),
+    },
+  },
+  'The interactive canvas — all three sections visible: row count (hidden outside a `<Table />`), '
+  + 'page navigation controls, and a page-size selector. '
+  + 'Use the Controls panel to adjust `totalPages` and `initialPageSize`.',
+);
+
+export const PageNavigationOnly: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    args: {
+      totalPages: 5,
+      onPageChange: fn(),
+    },
+  },
+  'Only `PaginationControls` — first, previous, page input, next, and last buttons. '
+  + '`totalPages` drives the upper bound; `onPageChange` receives the zero-indexed new page number. '
+  + 'No `PageSizeSelector` props are passed so that section is omitted.',
+);
+
+export const PageSizeSelectorOnly: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    args: {
+      availableSizes: [10, 25, 50, 100, 'All'],
+      initialPageSize: 25,
+      onPageSizeChange: fn(),
+    },
+  },
+  'Only `PageSizeSelector` — a dropdown listing the available page sizes. '
+  + 'No `totalPages` / `onPageChange` props are passed so the page-navigation section is omitted. '
+  + 'When used inside a `<Table />` without `onPageSizeChange`, selecting a size updates the AG Grid pagination automatically.',
+);
+
+export const ServerSidePagination: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { Table, PaginationPanel } from '@arbor-education/design-system.components';
+
+function ServerTable() {
+  const [page, setPage] = useState(0);
+  const [pageSize, setPageSize] = useState(25);
+  const { data, totalPages, totalRows } = useMyApiQuery({ page, pageSize });
+
+  return (
+    <Table
+      rowData={data}
+      columnDefs={colDefs}
+      footerContent={(
+        <PaginationPanel
+          totalRows={totalRows}
+          totalPages={totalPages}
+          onPageChange={setPage}
+          availableSizes={[10, 25, 50, 100]}
+          initialPageSize={pageSize}
+          onPageSizeChange={setPageSize}
+        />
+      )}
+    />
+  );
+}
+export default ServerTable;
+`.trim(),
+        },
+      },
+    },
+    args: {
+      totalRows: 347,
+      totalPages: 14,
+      onPageChange: fn(),
+      availableSizes: [10, 25, 50, 100],
+      initialPageSize: 25,
+      onPageSizeChange: fn(),
+    },
+  },
+  'Server-side pagination pattern — `totalPages` and `onPageChange` are controlled externally by your data-fetching layer. '
+  + '`totalRows` is provided manually (not derived from the grid). '
+  + 'In this standalone preview `RowCountInfo` still returns `null` (no `GridApiContext`), '
+  + 'but the code example shows the full wiring pattern.',
+);

package/src/components/table/table.scss

@@ -1,4 +1,15 @@
 .ds-table {
+  &--vertical-header-text {
+    .ag-header-cell-label .ag-header-cell-text {
+      writing-mode: vertical-rl; 
+      transform: rotate(180deg);
+      text-wrap: balance;
+      text-align: center;
+      flex-shrink: 0;
+      min-width: fit-content;
+    }
+  }
+
   &__select-dropdown-cell {
     width: 100%;
   }