snice 4.28.0 → 4.30.0

package/docs/components/pdf-viewer.md

@@ -1,62 +1,47 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/pdf-viewer.md instead -->
-
-# PDF Viewer Component
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/pdf-viewer.md -->
 
+# PDF Viewer
 `<snice-pdf-viewer>`
 
-A PDF document viewer with a built-in toolbar for page navigation, zoom control, fit modes, printing, and downloading. Uses a vendored PDF.js bundle included with the component.
+A PDF document viewer with a toolbar for page navigation, zoom controls, fit modes, download, and print. Uses a vendored PDF.js library.
 
 ## Table of Contents
-- [Importing](#importing)
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [Keyboard Shortcuts](#keyboard-shortcuts)
+- [Keyboard Navigation](#keyboard-navigation)
 - [Accessibility](#accessibility)
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/pdf-viewer/snice-pdf-viewer';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-pdf-viewer.min.js"></script>
-```
-
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `src` | `string` | `''` | URL of the PDF file to display |
+| `src` | `string` | `''` | PDF file URL |
 | `page` | `number` | `1` | Current page number |
 | `zoom` | `number` | `1` | Zoom level (range: 0.25 to 5) |
-| `fit` | `'width' \| 'height' \| 'page'` | `'width'` | How the PDF page fits within the viewer |
-| `totalPages` | `number` (readonly) | `0` | Total number of pages in the loaded document |
+| `fit` | `'width' \| 'height' \| 'page'` | `'width'` | Fit mode for page display |
+| `totalPages` (read-only) | `number` | `0` | Total number of pages in the document |
 
 ## Methods
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
-| `goToPage()` | `page: number` | Navigate to a specific page number |
-| `nextPage()` | -- | Navigate to the next page |
-| `prevPage()` | -- | Navigate to the previous page |
+| `goToPage()` | `page: number` | Navigate to a specific page |
+| `nextPage()` | -- | Go to the next page |
+| `prevPage()` | -- | Go to the previous page |
 | `print()` | -- | Open the PDF in a new window for printing |
-| `download()` | -- | Trigger a file download of the PDF |
+| `download()` | -- | Trigger a download of the PDF file |
 
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `page-change` | `{ page: number; totalPages: number }` | Fired when the current page changes |
-| `pdf-loaded` | `{ totalPages: number }` | Fired when the PDF document has been loaded successfully |
-| `pdf-error` | `{ error: string }` | Fired when an error occurs during loading or rendering |
+| `page-change` | `{ page: number, totalPages: number }` | Fired when the page changes |
+| `pdf-loaded` | `{ totalPages: number }` | Fired when the PDF document loads successfully |
+| `pdf-error` | `{ error: string }` | Fired on loading or rendering errors |
 
 ## CSS Parts
 
@@ -68,17 +53,6 @@ Style internal elements from outside the shadow DOM using `::part()`.
 | `toolbar` | `<div>` | The navigation and zoom toolbar |
 | `viewport` | `<div>` | The PDF page display area |
 
-```css
-snice-pdf-viewer::part(toolbar) {
-  background: #f9fafb;
-  border-bottom: 1px solid #e5e7eb;
-}
-
-snice-pdf-viewer::part(viewport) {
-  background: #e5e7eb;
-}
-```
-
 ## Basic Usage
 
 ```typescript
@@ -86,142 +60,63 @@ import 'snice/components/pdf-viewer/snice-pdf-viewer';
 ```
 
 ```html
-<snice-pdf-viewer src="/documents/report.pdf"></snice-pdf-viewer>
+<snice-pdf-viewer src="/documents/report.pdf" fit="width" style="height: 600px;"></snice-pdf-viewer>
 ```
 
 ## Examples
 
-### Basic Document Viewer
+### Fit Modes
 
-Display a PDF with the default fit-to-width mode.
+Use the `fit` attribute to control how the page fills the viewport.
 
 ```html
-<snice-pdf-viewer
-  src="/documents/report.pdf"
-  style="width: 100%; height: 600px;"
-></snice-pdf-viewer>
-```
-
-### Zoom and Fit Modes
-
-Control how the document is displayed using `zoom` and `fit` attributes.
-
-```html
-<!-- Fit to page width -->
-<snice-pdf-viewer src="/docs/manual.pdf" fit="width"></snice-pdf-viewer>
-
-<!-- Fit entire page -->
-<snice-pdf-viewer src="/docs/manual.pdf" fit="page"></snice-pdf-viewer>
-
-<!-- Custom zoom level -->
-<snice-pdf-viewer src="/docs/manual.pdf" zoom="1.5"></snice-pdf-viewer>
+<snice-pdf-viewer src="/doc.pdf" fit="width"></snice-pdf-viewer>
+<snice-pdf-viewer src="/doc.pdf" fit="height"></snice-pdf-viewer>
+<snice-pdf-viewer src="/doc.pdf" fit="page"></snice-pdf-viewer>
 ```
 
-### Handling Load and Error Events
+### Event Handling
 
-Listen for document lifecycle events to show loading states or handle errors.
+Listen for document and navigation events.
 
-```html
-<snice-pdf-viewer id="viewer" style="width: 100%; height: 600px;"></snice-pdf-viewer>
-<div id="status"></div>
-
-<script type="module">
-  import 'snice/components/pdf-viewer/snice-pdf-viewer';
-
-  const viewer = document.getElementById('viewer');
-  const status = document.getElementById('status');
-
-  viewer.addEventListener('pdf-loaded', (e) => {
-    status.textContent = `Document loaded: ${e.detail.totalPages} pages`;
-  });
-
-  viewer.addEventListener('pdf-error', (e) => {
-    status.textContent = `Error: ${e.detail.error}`;
-  });
+```typescript
+viewer.addEventListener('pdf-loaded', (e) => {
+  console.log('Loaded:', e.detail.totalPages, 'pages');
+});
 
-  viewer.addEventListener('page-change', (e) => {
-    status.textContent = `Page ${e.detail.page} of ${e.detail.totalPages}`;
-  });
+viewer.addEventListener('page-change', (e) => {
+  console.log(`Page ${e.detail.page} of ${e.detail.totalPages}`);
+});
 
-  viewer.src = '/documents/report.pdf';
-</script>
+viewer.addEventListener('pdf-error', (e) => {
+  console.error('PDF error:', e.detail.error);
+});
 ```
 
 ### Programmatic Navigation
 
-Use methods to control page navigation from external buttons or logic.
-
-```html
-<snice-pdf-viewer id="viewer" src="/documents/slides.pdf" style="width: 100%; height: 500px;"></snice-pdf-viewer>
-
-<div style="margin-top: 1rem;">
-  <button id="prev">Previous</button>
-  <span id="page-info">Page 1</span>
-  <button id="next">Next</button>
-  <button id="download">Download</button>
-  <button id="print">Print</button>
-</div>
-
-<script type="module">
-  import 'snice/components/pdf-viewer/snice-pdf-viewer';
-
-  const viewer = document.getElementById('viewer');
-
-  document.getElementById('prev').addEventListener('click', () => viewer.prevPage());
-  document.getElementById('next').addEventListener('click', () => viewer.nextPage());
-  document.getElementById('download').addEventListener('click', () => viewer.download());
-  document.getElementById('print').addEventListener('click', () => viewer.print());
-
-  viewer.addEventListener('page-change', (e) => {
-    document.getElementById('page-info').textContent =
-      `Page ${e.detail.page} of ${e.detail.totalPages}`;
-  });
-</script>
-```
-
-### Jump to a Specific Page
-
-Use `goToPage()` to navigate directly to any page.
-
-```html
-<snice-pdf-viewer id="viewer" src="/documents/handbook.pdf" style="width: 100%; height: 600px;"></snice-pdf-viewer>
-
-<label>
-  Go to page:
-  <input id="page-input" type="number" min="1" value="1" style="width: 60px;">
-</label>
-<button id="go-btn">Go</button>
+Use methods to control the viewer from JavaScript.
 
-<script type="module">
-  import 'snice/components/pdf-viewer/snice-pdf-viewer';
-
-  const viewer = document.getElementById('viewer');
-
-  viewer.addEventListener('pdf-loaded', (e) => {
-    document.getElementById('page-input').max = e.detail.totalPages;
-  });
-
-  document.getElementById('go-btn').addEventListener('click', () => {
-    const page = parseInt(document.getElementById('page-input').value, 10);
-    viewer.goToPage(page);
-  });
-</script>
+```typescript
+viewer.goToPage(5);
+viewer.nextPage();
+viewer.prevPage();
+viewer.print();
+viewer.download();
 ```
 
-## Keyboard Shortcuts
+## Keyboard Navigation
 
 | Key | Action |
 |-----|--------|
 | `ArrowRight` / `PageDown` | Next page |
 | `ArrowLeft` / `PageUp` | Previous page |
-| `Ctrl/Cmd + =` | Zoom in |
-| `Ctrl/Cmd + -` | Zoom out |
+| `Ctrl/Cmd` + `+` | Zoom in |
+| `Ctrl/Cmd` + `-` | Zoom out |
 
 ## Accessibility
 
-- The built-in toolbar provides page navigation, zoom controls, and fit mode selection
-- Keyboard shortcuts allow page navigation and zoom without a mouse
-- Arrow keys (Left/Right) and PageUp/PageDown navigate between pages
-- Ctrl/Cmd with +/- controls zoom level
-- Print and download functions are available via toolbar buttons
-- The viewer displays the current page number and total pages for orientation
+- The viewer container is keyboard-focusable with `tabindex="0"`
+- All toolbar buttons have descriptive `title` attributes
+- The page input field allows direct page number entry
+- Navigation buttons are disabled at page boundaries

package/docs/components/permission-matrix.md

@@ -1,53 +1,51 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/permission-matrix.md instead -->
-
-# Permission Matrix Component
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/permission-matrix.md -->
 
+# Permission Matrix
 `<snice-permission-matrix>`
 
-A grid that maps roles to permissions using checkbox toggles. Useful for managing access control, displaying role-based permissions, and configuring authorization settings.
-
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/permission-matrix/snice-permission-matrix';
-```
+A role/permission grid with checkbox toggles for managing access control. Rows represent roles, columns represent permissions.
 
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-permission-matrix.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+- [Data Types](#data-types)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `roles` | `PermissionRole[]` | `[]` | Array of role objects: `{ id, name, description? }`. Set via JS. |
-| `permissions` | `Permission[]` | `[]` | Array of permission objects: `{ id, name, group?, description? }`. Set via JS. |
-| `matrix` | `PermissionMatrix` | `{}` | Object mapping role IDs to arrays of permission IDs: `{ [roleId]: string[] }`. Set via JS. |
-| `readonly` | `boolean` | `false` | When true, shows check/dash indicators instead of checkboxes |
+| `roles` | `PermissionRole[]` | `[]` | Array of roles to display as rows (set via JS) |
+| `permissions` | `Permission[]` | `[]` | Array of permissions to display as columns (set via JS) |
+| `matrix` | `PermissionMatrix` | `{}` | Permission assignments: `{ [roleId]: string[] }` (set via JS) |
+| `readonly` | `boolean` | `false` | Display check/dash indicators instead of checkboxes |
 
 ## Methods
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
-| `getMatrix()` | -- | Returns a deep copy of the current permission matrix |
-| `setMatrix()` | `matrix: PermissionMatrix` | Replaces the entire permission matrix |
-| `hasPermission()` | `roleId: string, permId: string` | Returns `true` if the role has the specified permission |
+| `getMatrix()` | -- | Returns a deep copy of the current matrix |
+| `setMatrix()` | `matrix: PermissionMatrix` | Replace the entire matrix |
+| `hasPermission()` | `roleId: string, permId: string` | Check if a role has a specific permission |
 
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `permission-toggle` | `{ roleId: string, permissionId: string, granted: boolean }` | Fired when a single permission is toggled |
-| `matrix-change` | `{ matrix: PermissionMatrix }` | Fired after any permission change, with the full updated matrix |
+| `permission-toggle` | `{ roleId: string, permissionId: string, granted: boolean }` | Fired when a checkbox is toggled |
+| `matrix-change` | `{ matrix: PermissionMatrix }` | Fired when the matrix is updated |
 
 ## CSS Parts
 
-| Part | Description |
-|------|-------------|
-| `base` | Outer container element |
+Style internal elements from outside the shadow DOM using `::part()`.
+
+| Part | Element | Description |
+|------|---------|-------------|
+| `base` | `<div>` | The outer container |
 
 ## Basic Usage
 
@@ -58,10 +56,10 @@ import 'snice/components/permission-matrix/snice-permission-matrix';
 ```html
 <snice-permission-matrix id="pm"></snice-permission-matrix>
 
-<script>
+<script type="module">
   const pm = document.getElementById('pm');
   pm.roles = [
-    { id: 'admin', name: 'Admin' },
+    { id: 'admin', name: 'Admin', description: 'Full access' },
     { id: 'editor', name: 'Editor' },
     { id: 'viewer', name: 'Viewer' }
   ];
@@ -81,102 +79,61 @@ import 'snice/components/permission-matrix/snice-permission-matrix';
 
 ## Examples
 
-### Editable Matrix
+### Readonly Mode
 
-By default, the matrix is editable. Users can toggle checkboxes to grant or revoke permissions.
+Use the `readonly` attribute to display a non-editable view with check and dash indicators.
 
 ```html
-<snice-permission-matrix id="pm"></snice-permission-matrix>
-
-<script>
-  const pm = document.getElementById('pm');
-  pm.roles = [
-    { id: 'admin', name: 'Administrator', description: 'Full system access' },
-    { id: 'editor', name: 'Editor', description: 'Content management' },
-    { id: 'viewer', name: 'Viewer', description: 'Read-only access' }
-  ];
-  pm.permissions = [
-    { id: 'create', name: 'Create' },
-    { id: 'read', name: 'Read' },
-    { id: 'update', name: 'Update' },
-    { id: 'delete', name: 'Delete' }
-  ];
-  pm.matrix = {
-    admin: ['create', 'read', 'update', 'delete'],
-    editor: ['create', 'read', 'update'],
-    viewer: ['read']
-  };
-</script>
+<snice-permission-matrix readonly></snice-permission-matrix>
 ```
 
-### Read-Only Mode
+### Event Handling
 
-Use the `readonly` attribute to display the matrix without editable checkboxes. Granted permissions show a checkmark, denied permissions show a dash.
+Listen for permission changes.
 
-```html
-<snice-permission-matrix id="pm-readonly" readonly></snice-permission-matrix>
+```typescript
+pm.addEventListener('permission-toggle', (e) => {
+  console.log(e.detail.roleId, e.detail.permissionId, e.detail.granted);
+});
+
+pm.addEventListener('matrix-change', (e) => {
+  console.log('Updated matrix:', e.detail.matrix);
+});
 ```
 
-### With Permission Descriptions
+### Querying Permissions
 
-Add `description` to permission objects to show additional context in the column headers.
+Use methods to inspect the matrix programmatically.
 
-```javascript
-pm.permissions = [
-  { id: 'create', name: 'Create', description: 'Add new items' },
-  { id: 'read', name: 'Read', description: 'View existing items' },
-  { id: 'update', name: 'Update', description: 'Modify existing items' },
-  { id: 'delete', name: 'Delete', description: 'Remove items permanently' }
-];
+```typescript
+pm.hasPermission('admin', 'delete'); // true
+pm.hasPermission('viewer', 'delete'); // false
+
+const matrixCopy = pm.getMatrix(); // deep copy
 ```
 
 ### Grouped Permissions
 
-Set the `group` property on permissions to organize them by category. Group names appear as headers.
+Use the `group` property on permissions to organize columns.
 
-```javascript
+```typescript
 pm.permissions = [
-  { id: 'view-docs', name: 'View', group: 'Documents' },
-  { id: 'edit-docs', name: 'Edit', group: 'Documents' },
-  { id: 'delete-docs', name: 'Delete', group: 'Documents' },
-  { id: 'view-reports', name: 'View', group: 'Reports' },
-  { id: 'export-reports', name: 'Export', group: 'Reports' },
-  { id: 'manage-team', name: 'Manage', group: 'Team' },
-  { id: 'view-team', name: 'View', group: 'Team' }
+  { id: 'create', name: 'Create', group: 'Content' },
+  { id: 'read', name: 'Read', group: 'Content' },
+  { id: 'manage-users', name: 'Manage Users', group: 'Admin' },
+  { id: 'billing', name: 'Billing', group: 'Admin' }
 ];
 ```
 
-### Listening for Changes
-
-```javascript
-pm.addEventListener('permission-toggle', (e) => {
-  console.log(`${e.detail.roleId}: ${e.detail.permissionId} = ${e.detail.granted}`);
-});
-
-pm.addEventListener('matrix-change', (e) => {
-  console.log('Full matrix:', e.detail.matrix);
-  // Save to backend, etc.
-});
-```
-
-### Programmatic Access
-
-```javascript
-// Check if a role has a specific permission
-pm.hasPermission('admin', 'delete'); // true
-
-// Get a deep copy of the matrix
-const currentMatrix = pm.getMatrix();
+## Accessibility
 
-// Replace the entire matrix
-pm.setMatrix({
-  admin: ['create', 'read', 'update', 'delete'],
-  editor: ['read'],
-  viewer: []
-});
-```
+- The table uses `role="grid"` with `aria-label="Permission matrix"`
+- Each checkbox has an accessible label (e.g., "Grant Create for Admin")
+- Readonly mode displays check/dash SVG indicators instead of interactive checkboxes
+- Role descriptions and permission descriptions are displayed when provided
+- Column headers use `scope="col"` for screen readers
 
-## Type Definitions
+## Data Types
 
 ```typescript
 interface PermissionRole {
@@ -194,11 +151,3 @@ interface Permission {
 
 type PermissionMatrix = { [roleId: string]: string[] };
 ```
-
-## Accessibility
-
-- Table uses `role="grid"` with `aria-label`
-- Each checkbox has a descriptive `aria-label` (e.g., "Grant Delete for Admin")
-- Keyboard navigation works with standard tab/enter/space
-- Focus indicators are visible on checkboxes
-- Column headers use `scope="col"` for screen readers