@semantic-components/ui-lab 0.62.0 → 0.63.0

package/src/lib/components/pagination/KEYBOARD-NAVIGATION.md

@@ -0,0 +1,356 @@
+# Keyboard Navigation
+
+This document describes the keyboard navigation patterns for pagination components, ensuring full keyboard accessibility.
+
+## Overview
+
+All pagination components support full keyboard navigation following WAI-ARIA best practices. Users can navigate through pagination controls using standard keyboard interactions without requiring a mouse.
+
+## Supported Keys
+
+### Tab Navigation
+
+- **Tab** - Move focus to the next interactive element in the pagination
+- **Shift + Tab** - Move focus to the previous interactive element
+
+### Activation
+
+- **Enter** - Activate focused pagination control (links or buttons)
+- **Space** - Activate focused pagination control (buttons only)
+
+### Page Size Selector
+
+- **Arrow Up/Down** - Navigate through page size options (when select is focused)
+- **Enter/Space** - Open the dropdown (when select is focused)
+- **Escape** - Close the dropdown without changing selection
+
+## Component Keyboard Behavior
+
+### ScPaginationLink
+
+**Element**: Button or anchor
+
+**Keys**:
+
+- **Tab** - Focus the page link
+- **Enter** - Navigate to the page
+- **Space** - Navigate to the page (button only)
+
+**Focus indicator**: Visible focus ring using `focus-visible:ring-2`
+
+```html
+<button sc-pagination-link [page]="2">2</button>
+```
+
+### ScPaginationPrevious / ScPaginationNext
+
+**Element**: Button or anchor
+
+**Keys**:
+
+- **Tab** - Focus the navigation control
+- **Enter** - Navigate to previous/next page
+- **Space** - Navigate to previous/next page (button only)
+
+**Disabled state**: When disabled, element is focusable but activation does nothing
+
+```html
+<button sc-pagination-previous [disabled]="currentPage() === 1">Previous</button>
+```
+
+### ScPaginationFirst / ScPaginationLast
+
+**Element**: Button or anchor
+
+**Keys**:
+
+- **Tab** - Focus the navigation control
+- **Enter** - Navigate to first/last page
+- **Space** - Navigate to first/last page (button only)
+
+**Disabled state**: When disabled, element is focusable but activation does nothing
+
+```html
+<button sc-pagination-first [disabled]="currentPage() === 1">First</button>
+```
+
+### ScPaginationPageSizeSelect
+
+**Element**: Select element
+
+**Keys**:
+
+- **Tab** - Focus the select
+- **Enter/Space** - Open dropdown
+- **Arrow Up** - Select previous option
+- **Arrow Down** - Select next option
+- **Home** - Jump to first option
+- **End** - Jump to last option
+- **Escape** - Close dropdown without change
+
+**Focus indicator**: Visible focus ring using `focus-visible:ring-2`
+
+```html
+<select sc-pagination-page-size-select></select>
+```
+
+## Focus Management
+
+### Focus Order
+
+The natural tab order follows the visual layout:
+
+1. Page size selector (if present)
+2. First page button (if present)
+3. Previous page button
+4. Page number links/buttons
+5. Next page button
+6. Last page button (if present)
+
+### Focus Indicators
+
+All interactive elements have visible focus indicators:
+
+```css
+focus-visible:outline-none
+focus-visible:ring-2
+focus-visible:ring-ring
+focus-visible:ring-offset-2
+```
+
+### Disabled State Focus
+
+Disabled controls remain in the tab order with `aria-disabled="true"` but do not perform actions when activated. This maintains consistent focus order regardless of pagination state.
+
+## ARIA Attributes
+
+### Navigation Container
+
+```html
+<nav sc-pagination role="navigation" aria-label="pagination"></nav>
+```
+
+- **role="navigation"** - Identifies the pagination region
+- **aria-label="pagination"** - Provides accessible name
+
+### Active Page
+
+```html
+<button sc-pagination-link [isActive]="true" aria-current="page">2</button>
+```
+
+- **aria-current="page"** - Indicates the current page
+
+### Navigation Buttons
+
+```html
+<button sc-pagination-previous aria-label="Go to previous page">Previous</button>
+
+<button sc-pagination-next aria-label="Go to next page">Next</button>
+
+<button sc-pagination-first aria-label="Go to first page">First</button>
+
+<button sc-pagination-last aria-label="Go to last page">Last</button>
+```
+
+- **aria-label** - Provides clear button purpose for screen readers
+
+### Disabled Controls
+
+```html
+<button sc-pagination-previous [disabled]="true" aria-disabled="true">Previous</button>
+```
+
+- **aria-disabled="true"** - Announces disabled state to screen readers
+- Element remains focusable but activation is prevented
+
+### Ellipsis (Non-interactive)
+
+```html
+<span sc-pagination-ellipsis aria-hidden="true">
+  <svg><!-- dots icon --></svg>
+  <span class="sr-only">More pages</span>
+</span>
+```
+
+- **aria-hidden="true"** - Hides decorative ellipsis from screen readers
+- **.sr-only** - Provides screen reader text without visual display
+
+## Best Practices
+
+### Use Semantic HTML
+
+Prefer `<button>` over `<a>` for client-side navigation:
+
+```html
+<!-- Good: Button for client-side navigation -->
+<button sc-pagination-link [page]="2">2</button>
+
+<!-- Also good: Anchor for server-side navigation -->
+<a sc-pagination-link href="/page/2">2</a>
+```
+
+### Provide Clear Labels
+
+Always provide text labels for navigation controls:
+
+```html
+<!-- Good: Text label provided -->
+<button sc-pagination-previous>
+  <svg><!-- icon --></svg>
+  <span>Previous</span>
+</button>
+
+<!-- Avoid: Icon only -->
+<button sc-pagination-previous>
+  <svg><!-- icon --></svg>
+</button>
+```
+
+If you must use icon-only, add `aria-label`:
+
+```html
+<button sc-pagination-previous aria-label="Go to previous page">
+  <svg><!-- icon --></svg>
+</button>
+```
+
+### Maintain Focus Context
+
+When page changes, consider where to move focus:
+
+```typescript
+export class MyComponent {
+  readonly currentPage = signal(1);
+
+  onPageChange(newPage: number): void {
+    this.currentPage.set(newPage);
+
+    // Option 1: Announce page change
+    // Screen readers will announce the new active page
+
+    // Option 2: Move focus to main content
+    // document.querySelector('[role="main"]')?.focus();
+
+    // Option 3: Keep focus on pagination
+    // Natural behavior - focus stays on clicked control
+  }
+}
+```
+
+### Page Size Selector Accessibility
+
+Wrap the select with a visible label:
+
+```html
+<!-- Good: Visible label associated -->
+<div class="flex items-center gap-2">
+  <span class="text-sm text-muted-foreground">Items per page:</span>
+  <sc-pagination-page-size-select />
+</div>
+
+<!-- Better: Using label element -->
+<label class="flex items-center gap-2">
+  <span class="text-sm text-muted-foreground">Items per page:</span>
+  <sc-pagination-page-size-select />
+</label>
+```
+
+### Loading States
+
+When loading new page data, provide feedback:
+
+```typescript
+export class MyComponent {
+  readonly loading = signal(false);
+  readonly currentPage = signal(1);
+
+  async onPageChange(newPage: number): Promise<void> {
+    this.loading.set(true);
+    try {
+      await this.loadData(newPage);
+      this.currentPage.set(newPage);
+    } finally {
+      this.loading.set(false);
+    }
+  }
+}
+```
+
+```html
+<nav sc-pagination [attr.aria-busy]="loading()" [currentPage]="currentPage()" (pageChange)="onPageChange($event)">
+  <!-- pagination content -->
+</nav>
+```
+
+## Testing Keyboard Navigation
+
+### Manual Testing Checklist
+
+1. ✅ All controls are reachable via Tab key
+2. ✅ Focus indicators are clearly visible
+3. ✅ Enter/Space keys activate controls
+4. ✅ Disabled controls don't perform actions
+5. ✅ Page size select works with arrow keys
+6. ✅ Active page is announced by screen readers
+7. ✅ Tab order matches visual layout
+8. ✅ No keyboard traps
+
+### Automated Testing
+
+Use Playwright or similar tools to test keyboard interactions:
+
+```typescript
+test('pagination keyboard navigation', async ({ page }) => {
+  await page.goto('/demos/pagination/page-size-pagination-demo');
+
+  // Test Tab navigation
+  await page.keyboard.press('Tab');
+  await expect(page.locator('[sc-pagination-previous]')).toBeFocused();
+
+  // Test Enter activation
+  await page.keyboard.press('Enter');
+
+  // Test focus indicators
+  const focused = page.locator(':focus');
+  await expect(focused).toHaveCSS('outline', expect.stringContaining('ring'));
+});
+```
+
+## Common Issues and Solutions
+
+### Issue: Focus Ring Not Visible
+
+**Problem**: Custom styles override focus indicators
+
+**Solution**: Use `focus-visible` instead of `focus`:
+
+```css
+/* Avoid */
+.button:focus {
+  outline: none;
+}
+
+/* Prefer */
+.button:focus-visible {
+  outline: 2px solid blue;
+}
+```
+
+### Issue: Disabled Controls Skip in Tab Order
+
+**Problem**: Using `disabled` attribute removes controls from tab order
+
+**Solution**: The component handles this correctly with `aria-disabled` while keeping controls focusable.
+
+### Issue: Select Opens on Space
+
+**Problem**: Native select behavior may vary across browsers
+
+**Solution**: This is standard behavior and should be maintained. Don't override native select interactions.
+
+## Resources
+
+- [WAI-ARIA Authoring Practices - Pagination](https://www.w3.org/WAI/ARIA/apg/patterns/)
+- [WebAIM - Keyboard Accessibility](https://webaim.org/techniques/keyboard/)
+- [WCAG 2.1 - Keyboard Accessible](https://www.w3.org/WAI/WCAG21/quickref/#keyboard-accessible)

package/src/lib/components/pagination/README.md

@@ -0,0 +1,359 @@
+# Pagination
+
+Pagination with page navigation, next and previous links. Supports both manual and smart automatic page generation.
+
+## Components
+
+- `ScPagination` - Navigation container with optional smart pagination logic
+- `ScPaginationList` - List container (ul)
+- `ScPaginationItem` - List item (li)
+- `ScPaginationLink` - Page number link/button
+- `ScPaginationPrevious` - Previous page link/button
+- `ScPaginationNext` - Next page link/button
+- `ScPaginationFirst` - First page link/button
+- `ScPaginationLast` - Last page link/button
+- `ScPaginationEllipsis` - Ellipsis indicator
+- `ScPaginationPageSizeSelect` - Page size selector (select dropdown)
+
+## Features
+
+- **Manual Mode**: Full control over pagination items (basic usage)
+- **Smart Mode**: Automatic page number and ellipsis generation (always returns 7 items when totalPages > 7)
+- Automatic calculation of total pages
+- Disabled state support for navigation buttons
+- **Internal state management**: Components handle state internally with automatic input syncing
+- **Unified change event**: Single event for both page and page size changes
+- **Auto-sized icons**: SVG icons automatically sized via `[&_svg]:size-4`
+
+## Usage
+
+### Basic Example
+
+```html
+<nav sc-pagination>
+  <ul sc-pagination-list>
+    <li sc-pagination-item>
+      <button sc-pagination-previous>
+        <svg si-chevron-left-icon></svg>
+        <span>Previous</span>
+      </button>
+    </li>
+    <li sc-pagination-item>
+      <button sc-pagination-link [page]="1">1</button>
+    </li>
+    <li sc-pagination-item>
+      <button sc-pagination-link [page]="2">2</button>
+    </li>
+    <li sc-pagination-item>
+      <button sc-pagination-link [page]="3">3</button>
+    </li>
+    <li sc-pagination-item>
+      <button sc-pagination-next>
+        <span>Next</span>
+        <svg si-chevron-right-icon></svg>
+      </button>
+    </li>
+  </ul>
+</nav>
+```
+
+### With Icons (Lucide)
+
+```typescript
+import {
+  SiChevronLeftIcon,
+  SiChevronRightIcon,
+  SiEllipsisIcon,
+} from '@semantic-icons/lucide-icons';
+
+@Component({
+  imports: [
+    ScPagination,
+    ScPaginationList,
+    ScPaginationItem,
+    ScPaginationLink,
+    ScPaginationPrevious,
+    ScPaginationNext,
+    ScPaginationEllipsis,
+    SiChevronLeftIcon,
+    SiChevronRightIcon,
+    SiEllipsisIcon,
+  ],
+  template: `
+    <nav sc-pagination>
+      <ul sc-pagination-list>
+        <li sc-pagination-item>
+          <button sc-pagination-previous>
+            <svg si-chevron-left-icon></svg>
+            <span>Previous</span>
+          </button>
+        </li>
+        <!-- Page items here -->
+        <li sc-pagination-item>
+          <button sc-pagination-next>
+            <span>Next</span>
+            <svg si-chevron-right-icon></svg>
+          </button>
+        </li>
+      </ul>
+    </nav>
+  `,
+})
+```
+
+**Note**: Icons are automatically sized via `[&_svg]:size-4`. No need to add `class="size-4"` manually.
+
+## Smart Pagination (Automatic Page Generation)
+
+The pagination component can automatically calculate and generate page numbers with ellipses:
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { ScPaginationChange } from '@semantic-components/ui-lab';
+
+@Component({
+  template: `
+    <nav sc-pagination #pagination="scPagination" [currentPage]="currentPage()" [pageSize]="10" [totalItems]="100" (change)="onPaginationChange($event)">
+      <ul sc-pagination-list>
+        <li sc-pagination-item>
+          <button sc-pagination-previous>
+            <svg si-chevron-left-icon></svg>
+            <span>Previous</span>
+          </button>
+        </li>
+
+        @for (page of pagination.pages(); track page.value) {
+          <li sc-pagination-item>
+            @if (page.type === 'ellipsis') {
+              <span sc-pagination-ellipsis>
+                <svg si-ellipsis-icon></svg>
+                <span class="sr-only">More pages</span>
+              </span>
+            } @else {
+              <button sc-pagination-link [page]="page.value">
+                {{ page.value }}
+              </button>
+            }
+          </li>
+        }
+
+        <li sc-pagination-item>
+          <button sc-pagination-next>
+            <span>Next</span>
+            <svg si-chevron-right-icon></svg>
+          </button>
+        </li>
+      </ul>
+    </nav>
+  `,
+})
+export class MyComponent {
+  readonly currentPage = signal(1);
+
+  onPaginationChange(event: ScPaginationChange): void {
+    this.currentPage.set(event.page);
+  }
+}
+```
+
+### Smart Pagination Features
+
+- Automatically generates page numbers based on `currentPage`, `pageSize`, and `totalItems`
+- **Always returns exactly 7 items** when `totalPages > 7`
+- Intelligently places ellipses when there are many pages
+- Exposes `pagination.pages()` array for iteration
+- Exposes `pagination.totalPages()` for total page count
+- Each item in `pages()` has type `ScPaginationPage`: `{ type: 'page' | 'ellipsis', value: number | string }`
+- Active state is automatically computed for pagination links
+
+## Disabled State
+
+Navigation buttons (Previous, Next, First, Last) automatically disable themselves based on the current page:
+
+- **Previous** and **First**: Auto-disabled when on page 1
+- **Next** and **Last**: Auto-disabled when on the last page
+
+You can also manually disable any button:
+
+```html
+<!-- Manually disabled -->
+<button sc-pagination-previous [disabled]="true">
+  <!-- content -->
+</button>
+
+<!-- Disabled link -->
+<button sc-pagination-link [disabled]="true">1</button>
+```
+
+## First and Last Page Navigation
+
+Use `ScPaginationFirst` and `ScPaginationLast` for quick navigation to the first and last pages:
+
+```html
+<nav sc-pagination #pagination="scPagination" [currentPage]="currentPage()" [pageSize]="10" [totalItems]="100" (change)="onPaginationChange($event)">
+  <ul sc-pagination-list>
+    <li sc-pagination-item>
+      <button sc-pagination-first>
+        <svg si-chevrons-left-icon></svg>
+        <span>First</span>
+      </button>
+    </li>
+    <li sc-pagination-item>
+      <button sc-pagination-previous>
+        <svg si-chevron-left-icon></svg>
+        <span>Previous</span>
+      </button>
+    </li>
+
+    <!-- Page numbers here -->
+
+    <li sc-pagination-item>
+      <button sc-pagination-next>
+        <span>Next</span>
+        <svg si-chevron-right-icon></svg>
+      </button>
+    </li>
+    <li sc-pagination-item>
+      <button sc-pagination-last>
+        <span>Last</span>
+        <svg si-chevrons-right-icon></svg>
+      </button>
+    </li>
+  </ul>
+</nav>
+```
+
+## Page Size Selector
+
+Use `ScPaginationPageSizeSelect` to allow users to change the number of items displayed per page:
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { ScPaginationChange } from '@semantic-components/ui-lab';
+
+@Component({
+  template: `
+    <nav sc-pagination #pagination="scPagination" [currentPage]="currentPage()" [pageSize]="pageSize()" [totalItems]="totalItems()" [pageSizes]="[10, 25, 50, 100]" (change)="onPaginationChange($event)">
+      <div class="flex items-center gap-2">
+        <span class="text-sm text-muted-foreground">Items per page:</span>
+        <sc-pagination-page-size-select />
+      </div>
+
+      <ul sc-pagination-list>
+        <!-- Pagination items here -->
+      </ul>
+    </nav>
+  `,
+})
+export class MyComponent {
+  readonly currentPage = signal(1);
+  readonly pageSize = signal(10);
+  readonly totalItems = signal(250);
+
+  onPaginationChange(event: ScPaginationChange): void {
+    this.currentPage.set(event.page);
+    this.pageSize.set(event.pageSize);
+  }
+}
+```
+
+Key points:
+
+- `ScPaginationPageSizeSelect` renders only the select element
+- Wrap it with a label or other elements as needed in your template
+- Must be a child of `<nav sc-pagination>` to access pagination context
+- Configure available options via `[pageSizes]` on the parent `ScPagination`
+- Listen to `(change)` to receive both page and pageSize updates
+- The component automatically resets to page 1 when page size changes
+
+## Inputs & Outputs
+
+### ScPagination
+
+| Input         | Type       | Default             | Description                            |
+| ------------- | ---------- | ------------------- | -------------------------------------- |
+| `currentPage` | `number`   | `1`                 | Current active page (1-based)          |
+| `pageSize`    | `number`   | `10`                | Number of items per page               |
+| `totalItems`  | `number`   | `0`                 | Total number of items across all pages |
+| `pageSizes`   | `number[]` | `[10, 25, 50, 100]` | Available page size options            |
+| `class`       | `string`   | `''`                | Additional CSS classes                 |
+
+| Output   | Type                 | Description                           |
+| -------- | -------------------- | ------------------------------------- |
+| `change` | `ScPaginationChange` | Emitted when page or pageSize changes |
+
+**ScPaginationChange interface:**
+
+```typescript
+interface ScPaginationChange {
+  page: number;
+  pageSize: number;
+}
+```
+
+### ScPaginationLink
+
+| Input      | Type                                  | Default  | Description                      |
+| ---------- | ------------------------------------- | -------- | -------------------------------- |
+| `page`     | `number`                              | -        | Page number this link represents |
+| `size`     | `'default' \| 'sm' \| 'lg' \| 'icon'` | `'icon'` | Button size                      |
+| `disabled` | `boolean`                             | `false`  | Disabled state                   |
+| `class`    | `string`                              | `''`     | Additional CSS classes           |
+
+**Note**: The active state is automatically computed by comparing the `page` input with the parent pagination's `currentPage`.
+
+### ScPaginationPrevious
+
+| Input      | Type      | Default | Description            |
+| ---------- | --------- | ------- | ---------------------- |
+| `disabled` | `boolean` | `false` | Disabled state         |
+| `class`    | `string`  | `''`    | Additional CSS classes |
+
+### ScPaginationNext
+
+| Input      | Type      | Default | Description            |
+| ---------- | --------- | ------- | ---------------------- |
+| `disabled` | `boolean` | `false` | Disabled state         |
+| `class`    | `string`  | `''`    | Additional CSS classes |
+
+### ScPaginationFirst
+
+| Input      | Type      | Default | Description            |
+| ---------- | --------- | ------- | ---------------------- |
+| `disabled` | `boolean` | `false` | Disabled state         |
+| `class`    | `string`  | `''`    | Additional CSS classes |
+
+### ScPaginationLast
+
+| Input      | Type      | Default | Description            |
+| ---------- | --------- | ------- | ---------------------- |
+| `disabled` | `boolean` | `false` | Disabled state         |
+| `class`    | `string`  | `''`    | Additional CSS classes |
+
+### ScPaginationPageSizeSelect
+
+| Input   | Type     | Default | Description            |
+| ------- | -------- | ------- | ---------------------- |
+| `class` | `string` | `''`    | Additional CSS classes |
+
+**Note**: This component renders only the select element. The page size options are configured via the `pageSizes` input on the parent `ScPagination` component.
+
+## Accessibility
+
+- Uses `role="navigation"` with `aria-label="pagination"`
+- Active page has `aria-current="page"`
+- Previous/Next/First/Last have `aria-label` for screen readers
+- Disabled state uses `aria-disabled` attribute with automatic styling
+- Ellipsis is `aria-hidden` with `.sr-only` text
+- Focus ring for keyboard navigation
+
+## Internal State Management
+
+The pagination component uses internal signals with effects to manage state:
+
+- Accepts `currentPage` and `pageSize` as inputs
+- Maintains internal state that syncs with inputs
+- Updates internal state when user interacts (clicks links, changes page size)
+- Emits `change` event with both page and pageSize
+- Parent can optionally update inputs in response to the event
+- Works in both controlled and semi-controlled modes