snice 2.5.4 → 3.2.0

package/docs/components/nav.md

@@ -0,0 +1,239 @@
+# Navigation Component
+
+The `<snice-nav>` component renders navigation menus from placard configurations. It integrates with Snice's routing system and supports multiple display variants.
+
+## Basic Usage
+
+```html
+<snice-nav id="mainNav" variant="flat" orientation="horizontal"></snice-nav>
+
+<script type="module">
+  import 'snice/components/nav/snice-nav';
+
+  const nav = document.querySelector('#mainNav');
+
+  const placards = [
+    { name: 'home', title: 'Home', icon: '🏠', order: 0 },
+    { name: 'products', title: 'Products', icon: '📦', order: 1 },
+    { name: 'about', title: 'About', icon: 'ℹ️', order: 2 },
+  ];
+
+  nav.update(placards, undefined, 'home');
+</script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `variant` | `'flat' \| 'hierarchical' \| 'grouped'` | `'flat'` | Display style for navigation |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction |
+| `isTopLevel` | `boolean` | `false` | Whether to receive context updates |
+
+## Methods
+
+### `update(placards, appContext?, currentRoute?, routeParams?): void`
+Update the navigation with new placard data and routing information.
+
+```typescript
+nav.update(
+  placards,           // Array of placard objects
+  appContext,         // Optional app context
+  'products',         // Current route
+  { id: '123' }       // Route parameters
+);
+```
+
+## Placard Structure
+
+```typescript
+interface Placard {
+  name: string;              // Unique identifier and route
+  title: string;             // Display text
+  icon?: string;             // Icon character/emoji
+  order?: number;            // Sort order
+  parent?: string;           // Parent placard name (for hierarchical)
+  group?: string;            // Group name (for grouped variant)
+  show?: boolean;            // Whether to show the item
+  description?: string;      // Accessible label and tooltip
+  tooltip?: string;          // Hover tooltip
+  hotkeys?: string[];        // Keyboard shortcuts
+  helpUrl?: string;          // Help documentation URL
+  searchTerms?: string[];    // Search keywords
+  attributes?: Record<string, any>; // Custom data attributes
+  visibleOn?: Function | Function[]; // Visibility guards
+}
+```
+
+## Variants
+
+### Flat (Default)
+Simple horizontal or vertical list of navigation items.
+
+```html
+<snice-nav variant="flat"></snice-nav>
+```
+
+### Hierarchical
+Nested navigation with parent-child relationships.
+
+```html
+<snice-nav variant="hierarchical"></snice-nav>
+```
+
+```javascript
+const placards = [
+  { name: 'products', title: 'Products', order: 0 },
+  { name: 'electronics', title: 'Electronics', parent: 'products', order: 0 },
+  { name: 'clothing', title: 'Clothing', parent: 'products', order: 1 },
+];
+```
+
+### Grouped
+Navigation items organized into labeled groups.
+
+```html
+<snice-nav variant="grouped"></snice-nav>
+```
+
+```javascript
+const placards = [
+  { name: 'home', title: 'Home', group: 'Main', order: 0 },
+  { name: 'about', title: 'About', group: 'Main', order: 1 },
+  { name: 'settings', title: 'Settings', group: 'Account', order: 2 },
+];
+```
+
+## Examples
+
+### Basic Navigation
+
+```html
+<snice-nav id="nav"></snice-nav>
+
+<script type="module">
+  import 'snice/components/nav/snice-nav';
+
+  const nav = document.querySelector('#nav');
+
+  const placards = [
+    { name: 'home', title: 'Home', order: 0 },
+    { name: 'products', title: 'Products', order: 1 },
+    { name: 'services', title: 'Services', order: 2 },
+    { name: 'contact', title: 'Contact', order: 3 },
+  ];
+
+  nav.update(placards, undefined, 'home');
+</script>
+```
+
+### With Icons
+
+```javascript
+const placards = [
+  { name: 'dashboard', title: 'Dashboard', icon: '📊', order: 0 },
+  { name: 'analytics', title: 'Analytics', icon: '📈', order: 1 },
+  { name: 'reports', title: 'Reports', icon: '📋', order: 2 },
+  { name: 'settings', title: 'Settings', icon: '⚙️', order: 3 },
+];
+
+nav.update(placards);
+```
+
+### Hierarchical Menu
+
+```javascript
+const placards = [
+  { name: 'products', title: 'Products', order: 0 },
+  { name: 'electronics', title: 'Electronics', parent: 'products', order: 0 },
+  { name: 'computers', title: 'Computers', parent: 'electronics', order: 0 },
+  { name: 'phones', title: 'Phones', parent: 'electronics', order: 1 },
+  { name: 'clothing', title: 'Clothing', parent: 'products', order: 1 },
+];
+
+const nav = document.querySelector('snice-nav');
+nav.variant = 'hierarchical';
+nav.update(placards);
+```
+
+### Grouped Navigation
+
+```javascript
+const placards = [
+  { name: 'home', title: 'Home', group: 'Main', order: 0 },
+  { name: 'dashboard', title: 'Dashboard', group: 'Main', order: 1 },
+  { name: 'profile', title: 'Profile', group: 'Account', order: 0 },
+  { name: 'settings', title: 'Settings', group: 'Account', order: 1 },
+  { name: 'help', title: 'Help', group: 'Support', order: 0 },
+];
+
+const nav = document.querySelector('snice-nav');
+nav.variant = 'grouped';
+nav.update(placards);
+```
+
+### With Keyboard Shortcuts
+
+```javascript
+const placards = [
+  { name: 'home', title: 'Home', hotkeys: ['h', 'Ctrl+H'], order: 0 },
+  { name: 'search', title: 'Search', hotkeys: ['/', 'Ctrl+K'], order: 1 },
+];
+
+nav.update(placards);
+
+// Access hotkeys via data attribute
+const links = nav.shadowRoot.querySelectorAll('[data-hotkeys]');
+```
+
+### Conditional Visibility
+
+```javascript
+const placards = [
+  { name: 'home', title: 'Home', order: 0 },
+  {
+    name: 'admin',
+    title: 'Admin',
+    order: 1,
+    visibleOn: (appContext) => appContext.user?.isAdmin
+  },
+];
+
+nav.update(placards, { user: { isAdmin: true } });
+```
+
+### Active Route Tracking
+
+```javascript
+// Update current route
+nav.update(placards, undefined, 'products');
+
+// The corresponding nav item will have 'nav__link--active' class
+// and aria-current="page" attribute
+```
+
+## Accessibility
+
+- `role="navigation"` on nav container
+- `aria-current="page"` on active links
+- `aria-label` from placard descriptions
+- Keyboard navigation support
+- Screen reader friendly
+
+## Integration with Snice Context
+
+When `isTopLevel` is true, the nav component automatically receives updates from the Snice context system:
+
+```html
+<snice-nav is-top-level></snice-nav>
+```
+
+The context provides:
+- Placards from routing configuration
+- Current route and parameters
+- Application context for visibility guards
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires Custom Elements v1 and Shadow DOM support

package/docs/components/pagination.md

@@ -0,0 +1,289 @@
+# Pagination Component
+
+The `<snice-pagination>` component provides a flexible pagination interface for navigating through large datasets or multi-page content.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Variants](#variants)
+- [Examples](#examples)
+
+## Basic Usage
+
+```html
+<snice-pagination current="1" total="10"></snice-pagination>
+```
+
+```typescript
+import 'snice/components/pagination/snice-pagination';
+
+const pagination = document.querySelector('snice-pagination');
+pagination.addEventListener('@snice/pagination-change', (e) => {
+  console.log('Page changed to:', e.detail.page);
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `current` | `number` | `1` | The currently active page number |
+| `total` | `number` | `1` | Total number of pages |
+| `siblings` | `number` | `1` | Number of page buttons to show on each side of current page |
+| `showFirst` | `boolean` | `true` | Whether to show the "First" button |
+| `showLast` | `boolean` | `true` | Whether to show the "Last" button |
+| `showPrev` | `boolean` | `true` | Whether to show the "Previous" button |
+| `showNext` | `boolean` | `true` | Whether to show the "Next" button |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant of the pagination |
+| `variant` | `'default' \| 'rounded' \| 'text'` | `'default'` | Visual style variant |
+
+## Methods
+
+### `goToPage(page: number): void`
+Navigate to a specific page number.
+
+```typescript
+pagination.goToPage(5);
+```
+
+### `nextPage(): void`
+Navigate to the next page (if not on last page).
+
+```typescript
+pagination.nextPage();
+```
+
+### `previousPage(): void`
+Navigate to the previous page (if not on first page).
+
+```typescript
+pagination.previousPage();
+```
+
+### `firstPage(): void`
+Navigate to the first page.
+
+```typescript
+pagination.firstPage();
+```
+
+### `lastPage(): void`
+Navigate to the last page.
+
+```typescript
+pagination.lastPage();
+```
+
+## Events
+
+### `@snice/pagination-change`
+Fired when the page changes.
+
+**Event Detail:**
+```typescript
+{
+  page: number;        // New page number
+  previousPage: number; // Previous page number
+}
+```
+
+**Usage:**
+```typescript
+pagination.addEventListener('@snice/pagination-change', (e) => {
+  const { page, previousPage } = e.detail;
+  console.log(`Changed from page ${previousPage} to ${page}`);
+});
+```
+
+## Variants
+
+### Size Variants
+
+```html
+<!-- Small -->
+<snice-pagination total="10" size="small"></snice-pagination>
+
+<!-- Medium (default) -->
+<snice-pagination total="10" size="medium"></snice-pagination>
+
+<!-- Large -->
+<snice-pagination total="10" size="large"></snice-pagination>
+```
+
+### Style Variants
+
+```html
+<!-- Default (squared corners) -->
+<snice-pagination total="10" variant="default"></snice-pagination>
+
+<!-- Rounded (circular buttons) -->
+<snice-pagination total="10" variant="rounded"></snice-pagination>
+
+<!-- Text (minimal styling) -->
+<snice-pagination total="10" variant="text"></snice-pagination>
+```
+
+## Examples
+
+### Basic Pagination
+
+```html
+<snice-pagination
+  current="1"
+  total="20">
+</snice-pagination>
+```
+
+### Controlling Siblings
+
+The `siblings` property controls how many page buttons appear on each side of the current page.
+
+```html
+<!-- Show 1 page on each side (default) -->
+<!-- Current: 5 → Shows: [1] ... [4] [5] [6] ... [20] -->
+<snice-pagination current="5" total="20" siblings="1"></snice-pagination>
+
+<!-- Show 3 pages on each side -->
+<!-- Current: 10 → Shows: [1] ... [7] [8] [9] [10] [11] [12] [13] ... [20] -->
+<snice-pagination current="10" total="20" siblings="3"></snice-pagination>
+```
+
+### Without Navigation Buttons
+
+```html
+<!-- No first/last buttons -->
+<snice-pagination
+  total="10"
+  show-first="false"
+  show-last="false">
+</snice-pagination>
+
+<!-- Only page numbers -->
+<snice-pagination
+  total="10"
+  show-first="false"
+  show-last="false"
+  show-prev="false"
+  show-next="false">
+</snice-pagination>
+```
+
+### Programmatic Navigation
+
+```typescript
+import type { SnicePaginationElement } from 'snice/components/pagination/snice-pagination.types';
+
+const pagination = document.querySelector<SnicePaginationElement>('snice-pagination');
+
+// Navigate to specific page
+pagination.goToPage(7);
+
+// Navigate step by step
+pagination.nextPage();
+pagination.previousPage();
+
+// Jump to extremes
+pagination.firstPage();
+pagination.lastPage();
+```
+
+### With Event Handling
+
+```typescript
+const pagination = document.querySelector('snice-pagination');
+
+pagination.addEventListener('@snice/pagination-change', (e) => {
+  const { page } = e.detail;
+
+  // Fetch data for the new page
+  fetchPageData(page);
+});
+
+async function fetchPageData(page: number) {
+  const response = await fetch(`/api/data?page=${page}`);
+  const data = await response.json();
+  renderData(data);
+}
+```
+
+### Custom Styling with CSS Variables
+
+```html
+<style>
+  snice-pagination {
+    --pagination-gap: 8px;
+    --pagination-button-size: 40px;
+    --pagination-button-padding: 12px;
+    --pagination-font-size: 16px;
+    --pagination-border-radius: 8px;
+  }
+</style>
+
+<snice-pagination total="10"></snice-pagination>
+```
+
+### Complete Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="module">
+    import 'snice/components/pagination/snice-pagination';
+
+    const pagination = document.querySelector('snice-pagination');
+    const dataContainer = document.querySelector('#data');
+    const itemsPerPage = 10;
+
+    // Sample data
+    const allData = Array.from({ length: 100 }, (_, i) => ({
+      id: i + 1,
+      name: `Item ${i + 1}`
+    }));
+
+    // Update total pages
+    pagination.total = Math.ceil(allData.length / itemsPerPage);
+
+    // Render data for current page
+    function renderPage(page) {
+      const start = (page - 1) * itemsPerPage;
+      const end = start + itemsPerPage;
+      const pageData = allData.slice(start, end);
+
+      dataContainer.innerHTML = pageData
+        .map(item => `<div>${item.id}. ${item.name}</div>`)
+        .join('');
+    }
+
+    // Listen for page changes
+    pagination.addEventListener('@snice/pagination-change', (e) => {
+      renderPage(e.detail.page);
+    });
+
+    // Render initial page
+    renderPage(1);
+  </script>
+</head>
+<body>
+  <div id="data"></div>
+  <snice-pagination current="1"></snice-pagination>
+</body>
+</html>
+```
+
+## Accessibility
+
+The pagination component includes proper ARIA attributes:
+
+- `role="navigation"` on the container
+- `aria-label="Pagination"` on the nav element
+- `aria-label` on each button describing its action
+- `aria-current="page"` on the active page button
+- `disabled` state for unavailable navigation buttons
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires Custom Elements v1 and Shadow DOM support