snice 4.8.0 → 4.10.0

package/docs/components/notification-center.md

@@ -0,0 +1,256 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/notification-center.md instead)
+
+# Notification Center Component
+
+`<snice-notification-center>`
+
+A bell icon with a dropdown notification panel. Displays an unread count badge, supports marking notifications as read, and allows dismissing individual items.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Types](#types)
+- [CSS Custom Properties](#css-custom-properties)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```typescript
+import 'snice/components/notification-center/snice-notification-center';
+```
+
+```html
+<snice-notification-center></snice-notification-center>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/notification-center/snice-notification-center';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-notification-center.min.js"></script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `notifications` | `NotificationItem[]` | `[]` | Array of notification objects to display |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `markAsRead()` | `id: string` | Mark a single notification as read by its ID |
+| `markAllAsRead()` | -- | Mark all notifications as read |
+| `dismiss()` | `id: string` | Remove a notification from the list by its ID |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `notification-click` | `{ notification: NotificationItem }` | Fired when a notification item is clicked |
+| `notification-dismiss` | `{ id: string }` | Fired when a notification is dismissed |
+| `notification-read-all` | `void` | Fired when all notifications are marked as read |
+
+## Types
+
+### NotificationItem
+
+```typescript
+interface NotificationItem {
+  id: string;                                        // Unique identifier
+  title: string;                                     // Notification title
+  message: string;                                   // Notification body text
+  timestamp: string;                                 // Display timestamp (e.g., "2 min ago")
+  read?: boolean;                                    // Whether the notification has been read
+  icon?: string;                                     // Emoji or text icon (auto-set by type if omitted)
+  type?: 'info' | 'success' | 'warning' | 'error';  // Notification type (determines default icon)
+}
+```
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--snice-font-family` | Font family |
+| `--snice-color-text` | Primary text color |
+| `--snice-color-primary` | Mark-all-read link color and unread highlight |
+| `--snice-color-primary-subtle` | Unread item background |
+| `--snice-color-danger` | Badge background and dismiss hover color |
+| `--snice-color-text-inverse` | Badge text color |
+| `--snice-color-text-secondary` | Message text color |
+| `--snice-color-text-tertiary` | Timestamp, empty state text, and dismiss icon color |
+| `--snice-color-border` | Panel and item border color |
+| `--snice-color-background` | Panel background color |
+| `--snice-color-background-element` | Item hover and bell hover background |
+| `--snice-shadow-lg` | Panel drop shadow |
+| `--snice-spacing-*` | Various spacing tokens |
+| `--snice-font-size-sm` | Small text size |
+| `--snice-font-size-md` | Base text size |
+| `--snice-font-weight-medium` | Medium font weight |
+| `--snice-font-weight-semibold` | Semibold font weight |
+| `--snice-font-weight-bold` | Bold font weight |
+| `--snice-border-radius-md` | Item border radius |
+| `--snice-border-radius-lg` | Panel border radius |
+| `--snice-transition-fast` | Hover transition speed |
+
+## Examples
+
+### Basic Notifications
+
+Populate the `notifications` property to display items in the dropdown panel.
+
+```html
+<snice-notification-center id="nc"></snice-notification-center>
+
+<script type="module">
+  import 'snice/components/notification-center/snice-notification-center';
+
+  const nc = document.getElementById('nc');
+  nc.notifications = [
+    {
+      id: '1',
+      title: 'New message',
+      message: 'You have a new message from Sarah',
+      timestamp: '2 min ago',
+      type: 'info'
+    },
+    {
+      id: '2',
+      title: 'Build complete',
+      message: 'Production deployment succeeded',
+      timestamp: '10 min ago',
+      type: 'success',
+      read: true
+    },
+    {
+      id: '3',
+      title: 'Disk space low',
+      message: 'Server storage is at 90% capacity',
+      timestamp: '1 hour ago',
+      type: 'warning'
+    }
+  ];
+</script>
+```
+
+### Handling Notification Clicks
+
+Listen for the `notification-click` event to navigate or take action when a notification is clicked.
+
+```html
+<snice-notification-center id="nc"></snice-notification-center>
+
+<script type="module">
+  import 'snice/components/notification-center/snice-notification-center';
+
+  const nc = document.getElementById('nc');
+  nc.notifications = [
+    { id: '1', title: 'New order', message: 'Order #4521 placed', timestamp: 'Just now', type: 'info' },
+    { id: '2', title: 'Payment received', message: '$249.99 from Acme Corp', timestamp: '5 min ago', type: 'success' }
+  ];
+
+  nc.addEventListener('notification-click', (e) => {
+    const notification = e.detail.notification;
+    console.log('Clicked:', notification.title);
+
+    // Mark as read when clicked
+    nc.markAsRead(notification.id);
+
+    // Navigate to relevant page
+    window.location.href = `/notifications/${notification.id}`;
+  });
+</script>
+```
+
+### Notification Types
+
+Each `type` automatically applies a default icon if no custom `icon` is provided.
+
+```html
+<snice-notification-center id="nc"></snice-notification-center>
+
+<script type="module">
+  import 'snice/components/notification-center/snice-notification-center';
+
+  const nc = document.getElementById('nc');
+  nc.notifications = [
+    { id: '1', title: 'Info', message: 'System update available', timestamp: '1 min ago', type: 'info' },
+    { id: '2', title: 'Success', message: 'File uploaded successfully', timestamp: '3 min ago', type: 'success' },
+    { id: '3', title: 'Warning', message: 'API rate limit approaching', timestamp: '5 min ago', type: 'warning' },
+    { id: '4', title: 'Error', message: 'Database connection failed', timestamp: '8 min ago', type: 'error' }
+  ];
+</script>
+```
+
+### Dismiss and Mark All Read
+
+Use methods to manage notification state programmatically.
+
+```html
+<snice-notification-center id="nc"></snice-notification-center>
+<button id="clear-all">Clear All</button>
+
+<script type="module">
+  import 'snice/components/notification-center/snice-notification-center';
+
+  const nc = document.getElementById('nc');
+  nc.notifications = [
+    { id: '1', title: 'Alert 1', message: 'First notification', timestamp: '1 min ago', type: 'info' },
+    { id: '2', title: 'Alert 2', message: 'Second notification', timestamp: '2 min ago', type: 'warning' },
+    { id: '3', title: 'Alert 3', message: 'Third notification', timestamp: '3 min ago', type: 'error' }
+  ];
+
+  // Listen for individual dismissals
+  nc.addEventListener('notification-dismiss', (e) => {
+    console.log('Dismissed notification:', e.detail.id);
+  });
+
+  // Listen for mark-all-read
+  nc.addEventListener('notification-read-all', () => {
+    console.log('All notifications marked as read');
+  });
+
+  // Programmatically clear all
+  document.getElementById('clear-all').addEventListener('click', () => {
+    nc.markAllAsRead();
+  });
+</script>
+```
+
+### Custom Icons
+
+Override the default type-based icon with a custom emoji or text using the `icon` property.
+
+```html
+<snice-notification-center id="nc"></snice-notification-center>
+
+<script type="module">
+  import 'snice/components/notification-center/snice-notification-center';
+
+  const nc = document.getElementById('nc');
+  nc.notifications = [
+    { id: '1', title: 'New follower', message: 'Alex started following you', timestamp: 'Just now', icon: '👤' },
+    { id: '2', title: 'Achievement unlocked', message: 'You completed 100 tasks', timestamp: '5 min ago', icon: '🏆' },
+    { id: '3', title: 'Reminder', message: 'Team standup in 15 minutes', timestamp: '10 min ago', icon: '⏰' }
+  ];
+</script>
+```
+
+## Accessibility
+
+- The bell icon is keyboard-focusable and opens the dropdown panel on click or Enter/Space
+- The unread count badge is visible for sighted users; the count is communicated via the badge element
+- Notification items in the dropdown are interactive and clickable
+- The dismiss button is accessible for keyboard navigation
+- The "Mark all as read" action is available as a link at the top of the panel
+- Unread notifications are visually distinguished with a highlighted background

package/docs/components/org-chart.md

@@ -0,0 +1,275 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/org-chart.md instead)
+
+# Org Chart Component
+
+`<snice-org-chart>`
+
+A hierarchical organizational chart that renders tree-structured data with node cards, connecting lines, avatars, and expand/collapse functionality. Supports both top-down and left-right layout directions.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Types](#types)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```typescript
+import 'snice/components/org-chart/snice-org-chart';
+```
+
+```html
+<snice-org-chart direction="top-down"></snice-org-chart>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/org-chart/snice-org-chart';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-org-chart.min.js"></script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `OrgChartNode \| null` | `null` | Root node of the organizational tree (set via JavaScript) |
+| `direction` | `'top-down' \| 'left-right'` | `'top-down'` | Layout direction for the chart |
+| `compact` | `boolean` | `false` | Use compact node display with smaller cards |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `collapseNode()` | `id: string` | Collapse a specific node, hiding its children |
+| `expandNode()` | `id: string` | Expand a specific node, showing its children |
+| `expandAll()` | -- | Expand all nodes in the chart |
+| `collapseAll()` | -- | Collapse all nodes in the chart |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `node-click` | `{ node: OrgChartNode }` | Fired when a node card is clicked |
+| `node-expand` | `{ node: OrgChartNode }` | Fired when a node is expanded |
+| `node-collapse` | `{ node: OrgChartNode }` | Fired when a node is collapsed |
+
+## Types
+
+### OrgChartNode
+
+```typescript
+interface OrgChartNode {
+  id: string;                    // Unique identifier for the node
+  name: string;                  // Person's name displayed on the card
+  title?: string;                // Job title or role
+  avatar?: string;               // Avatar image URL
+  children?: OrgChartNode[];     // Child nodes in the hierarchy
+}
+```
+
+## Examples
+
+### Basic Org Chart
+
+Provide a tree data structure to render a top-down organizational chart.
+
+```html
+<snice-org-chart id="org" direction="top-down"></snice-org-chart>
+
+<script type="module">
+  import 'snice/components/org-chart/snice-org-chart';
+
+  const chart = document.getElementById('org');
+  chart.data = {
+    id: 'ceo',
+    name: 'Jane Smith',
+    title: 'CEO',
+    avatar: '/avatars/jane.jpg',
+    children: [
+      {
+        id: 'cto',
+        name: 'Bob Jones',
+        title: 'CTO',
+        children: [
+          { id: 'dev1', name: 'Alice Chen', title: 'Senior Engineer' },
+          { id: 'dev2', name: 'David Park', title: 'Engineer' }
+        ]
+      },
+      {
+        id: 'cfo',
+        name: 'Carol White',
+        title: 'CFO',
+        children: [
+          { id: 'acc1', name: 'Eve Brown', title: 'Accountant' }
+        ]
+      }
+    ]
+  };
+</script>
+```
+
+### Left-to-Right Layout
+
+Use `direction="left-right"` for a horizontal chart layout.
+
+```html
+<snice-org-chart id="horizontal-org" direction="left-right"></snice-org-chart>
+
+<script type="module">
+  import 'snice/components/org-chart/snice-org-chart';
+
+  const chart = document.getElementById('horizontal-org');
+  chart.data = {
+    id: 'root',
+    name: 'Engineering',
+    title: 'Department',
+    children: [
+      {
+        id: 'frontend',
+        name: 'Frontend Team',
+        title: 'Team Lead: Maria',
+        children: [
+          { id: 'fe1', name: 'Tom', title: 'React Developer' },
+          { id: 'fe2', name: 'Lisa', title: 'UI Engineer' }
+        ]
+      },
+      {
+        id: 'backend',
+        name: 'Backend Team',
+        title: 'Team Lead: James',
+        children: [
+          { id: 'be1', name: 'Sam', title: 'API Engineer' },
+          { id: 'be2', name: 'Nina', title: 'Database Admin' }
+        ]
+      }
+    ]
+  };
+</script>
+```
+
+### Compact Mode
+
+Set the `compact` attribute for smaller node cards, useful for large organizations.
+
+```html
+<snice-org-chart id="compact-org" compact></snice-org-chart>
+
+<script type="module">
+  import 'snice/components/org-chart/snice-org-chart';
+
+  const chart = document.getElementById('compact-org');
+  chart.data = {
+    id: 'ceo',
+    name: 'Jane Smith',
+    title: 'CEO',
+    children: [
+      { id: 'vp1', name: 'VP Engineering', title: 'VP' },
+      { id: 'vp2', name: 'VP Sales', title: 'VP' },
+      { id: 'vp3', name: 'VP Marketing', title: 'VP' },
+      { id: 'vp4', name: 'VP Operations', title: 'VP' }
+    ]
+  };
+</script>
+```
+
+### Interactive Node Selection
+
+Listen for `node-click` events to display details or navigate when a node is selected.
+
+```html
+<snice-org-chart id="interactive-org"></snice-org-chart>
+<div id="selected-info" style="margin-top: 1rem;"></div>
+
+<script type="module">
+  import 'snice/components/org-chart/snice-org-chart';
+
+  const chart = document.getElementById('interactive-org');
+  const info = document.getElementById('selected-info');
+
+  chart.data = {
+    id: 'ceo',
+    name: 'Jane Smith',
+    title: 'CEO',
+    avatar: '/avatars/jane.jpg',
+    children: [
+      { id: 'cto', name: 'Bob Jones', title: 'CTO', avatar: '/avatars/bob.jpg' },
+      { id: 'cfo', name: 'Carol White', title: 'CFO', avatar: '/avatars/carol.jpg' }
+    ]
+  };
+
+  chart.addEventListener('node-click', (e) => {
+    const node = e.detail.node;
+    info.textContent = `Selected: ${node.name} (${node.title || 'No title'})`;
+  });
+</script>
+```
+
+### Programmatic Expand/Collapse
+
+Use methods to control which branches of the tree are visible.
+
+```html
+<snice-org-chart id="controlled-org"></snice-org-chart>
+<button id="expand-all">Expand All</button>
+<button id="collapse-all">Collapse All</button>
+
+<script type="module">
+  import 'snice/components/org-chart/snice-org-chart';
+
+  const chart = document.getElementById('controlled-org');
+  chart.data = {
+    id: 'root',
+    name: 'Company',
+    title: 'Organization',
+    children: [
+      {
+        id: 'dept1',
+        name: 'Engineering',
+        title: 'Department',
+        children: [
+          { id: 'team1', name: 'Frontend', title: 'Team' },
+          { id: 'team2', name: 'Backend', title: 'Team' }
+        ]
+      },
+      {
+        id: 'dept2',
+        name: 'Marketing',
+        title: 'Department',
+        children: [
+          { id: 'team3', name: 'Content', title: 'Team' },
+          { id: 'team4', name: 'Growth', title: 'Team' }
+        ]
+      }
+    ]
+  };
+
+  document.getElementById('expand-all').addEventListener('click', () => chart.expandAll());
+  document.getElementById('collapse-all').addEventListener('click', () => chart.collapseAll());
+
+  chart.addEventListener('node-expand', (e) => {
+    console.log('Expanded:', e.detail.node.name);
+  });
+
+  chart.addEventListener('node-collapse', (e) => {
+    console.log('Collapsed:', e.detail.node.name);
+  });
+</script>
+```
+
+## Accessibility
+
+- Node cards are interactive and clickable
+- Expand/collapse controls are accessible for toggling subtree visibility
+- The chart uses connecting lines to visually represent the hierarchy
+- Nodes display name, title, and optional avatar for clear identification
+- Keyboard users can interact with node cards to trigger click events