snice 4.9.0 → 4.10.0

package/docs/ai/components/notification-center.md

@@ -0,0 +1,79 @@
+# snice-notification-center
+
+Bell icon with dropdown notification panel. Shows unread badge, supports dismiss and mark-as-read.
+
+## Properties
+
+```ts
+notifications: NotificationItem[]       // Array of notification objects
+```
+
+### NotificationItem
+
+```ts
+interface NotificationItem {
+  id: string;
+  title: string;
+  message: string;
+  timestamp: string;
+  read?: boolean;
+  icon?: string;                         // Emoji/text icon (auto-set by type if omitted)
+  type?: 'info' | 'success' | 'warning' | 'error';
+}
+```
+
+## Methods
+
+- `markAsRead(id: string)` -- Mark single notification as read
+- `markAllAsRead()` -- Mark all notifications as read
+- `dismiss(id: string)` -- Remove notification from list
+
+## Events
+
+- `notification-click` -> `{ notification: NotificationItem }` -- Notification item clicked
+- `notification-dismiss` -> `{ id: string }` -- Notification dismissed
+- `notification-read-all` -> `void` -- All marked as read
+
+## CSS Custom Properties
+
+```css
+--snice-font-family
+--snice-color-text
+--snice-color-primary              /* Mark all read link, unread highlight */
+--snice-color-primary-subtle       /* Unread item background */
+--snice-color-danger               /* Badge background, dismiss hover */
+--snice-color-text-inverse         /* Badge text */
+--snice-color-text-secondary       /* Message text */
+--snice-color-text-tertiary        /* Timestamp, empty state, dismiss icon */
+--snice-color-border               /* Panel, item borders */
+--snice-color-background           /* Panel background */
+--snice-color-background-element   /* Item hover, bell hover */
+--snice-shadow-lg                  /* Panel shadow */
+--snice-spacing-*
+--snice-font-size-sm
+--snice-font-size-md
+--snice-font-weight-medium
+--snice-font-weight-semibold
+--snice-font-weight-bold
+--snice-border-radius-md
+--snice-border-radius-lg
+--snice-transition-fast
+```
+
+## Usage
+
+```html
+<snice-notification-center></snice-notification-center>
+```
+
+```js
+const nc = document.querySelector('snice-notification-center');
+nc.notifications = [
+  { id: '1', title: 'New message', message: 'You have a new message', timestamp: '2 min ago', type: 'info' },
+  { id: '2', title: 'Deployed', message: 'Build succeeded', timestamp: '5 min ago', type: 'success', read: true }
+];
+
+nc.addEventListener('notification-click', (e) => {
+  console.log('Clicked:', e.detail.notification);
+});
+```

package/docs/ai/components/org-chart.md

@@ -0,0 +1,62 @@
+# snice-org-chart
+
+Hierarchical organizational chart with expand/collapse, avatars, and two layout directions.
+
+## Properties
+
+```ts
+data: OrgChartNode | null                // Root node of the tree
+direction: 'top-down' | 'left-right'     // Layout direction (default: 'top-down')
+compact: boolean                         // Compact node display (default: false)
+```
+
+### OrgChartNode
+
+```ts
+interface OrgChartNode {
+  id: string;
+  name: string;
+  title?: string;                        // Job title / role
+  avatar?: string;                       // Avatar image URL
+  children?: OrgChartNode[];
+}
+```
+
+## Methods
+
+- `collapseNode(id: string)` -- Collapse a specific node
+- `expandNode(id: string)` -- Expand a specific node
+- `expandAll()` -- Expand all nodes
+- `collapseAll()` -- Collapse all nodes
+
+## Events
+
+- `node-click` -> `{ node: OrgChartNode }` -- Node clicked
+- `node-expand` -> `{ node: OrgChartNode }` -- Node expanded
+- `node-collapse` -> `{ node: OrgChartNode }` -- Node collapsed
+
+## Usage
+
+```html
+<snice-org-chart direction="top-down"></snice-org-chart>
+```
+
+```js
+const chart = document.querySelector('snice-org-chart');
+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', title: 'Engineer' }
+    ]},
+    { id: 'cfo', name: 'Carol White', title: 'CFO' }
+  ]
+};
+
+chart.addEventListener('node-click', (e) => {
+  console.log('Selected:', e.detail.node.name);
+});
+```

package/docs/ai/components/pagination.md

@@ -5,46 +5,44 @@ Pagination navigation component.
 ## Properties
 
 ```typescript
-current: number = 1;         // Active page
-total: number = 1;           // Total pages
-siblings: number = 1;        // Pages shown each side of current
-showFirst: boolean = true;   // Show first button
-showLast: boolean = true;    // Show last button
-showPrev: boolean = true;    // Show previous button
-showNext: boolean = true;    // Show next button
+current: number = 1;
+total: number = 1;
+siblings: number = 1;               // Pages shown each side of current
+showFirst: boolean = true;          // attr: show-first
+showLast: boolean = true;           // attr: show-last
+showPrev: boolean = true;           // attr: show-prev
+showNext: boolean = true;           // attr: show-next
 size: 'small'|'medium'|'large' = 'medium';
 variant: 'default'|'rounded'|'text' = 'default';
 ```
 
 ## Methods
 
-```typescript
-goToPage(page: number)   // Navigate to page
-nextPage()               // Next page
-previousPage()           // Previous page
-firstPage()              // First page
-lastPage()               // Last page
-```
+- `goToPage(page: number)` - Navigate to page
+- `nextPage()` - Next page
+- `previousPage()` - Previous page
+- `firstPage()` - First page
+- `lastPage()` - Last page
 
 ## Events
 
-```typescript
-'pagination-change' // { page, previousPage }
-```
+- `pagination-change` → `{ page, previousPage }`
 
 ## Usage
 
 ```html
 <snice-pagination current="1" total="10"></snice-pagination>
+<snice-pagination total="20" siblings="3" variant="rounded" size="large"></snice-pagination>
 ```
 
 ```typescript
 pagination.addEventListener('pagination-change', (e) => {
   console.log(e.detail.page);
 });
+pagination.goToPage(5);
 ```
 
-## CSS Variables
+## CSS Custom Properties
 
 ```css
 --pagination-gap: 4px;

package/docs/ai/components/pdf-viewer.md

@@ -0,0 +1,57 @@
+# snice-pdf-viewer
+
+PDF document viewer with toolbar (page navigation, zoom, fit modes, download, print). Uses PDF.js loaded from CDN.
+
+## Properties
+
+```ts
+src: string                              // PDF file URL
+page: number                             // Current page (default: 1)
+zoom: number                             // Zoom level (default: 1, range: 0.25-5)
+fit: 'width' | 'height' | 'page'        // Fit mode (default: 'width')
+readonly totalPages: number              // Total pages in document
+```
+
+## Methods
+
+- `goToPage(page: number)` -- Navigate to specific page
+- `nextPage()` -- Go to next page
+- `prevPage()` -- Go to previous page
+- `print()` -- Open PDF in new window for printing
+- `download()` -- Trigger PDF file download
+
+## Events
+
+- `page-change` -> `{ page: number; totalPages: number }` -- Page navigation
+- `pdf-loaded` -> `{ totalPages: number }` -- Document loaded successfully
+- `pdf-error` -> `{ error: string }` -- Loading or rendering error
+
+## Keyboard Shortcuts
+
+- `ArrowRight` / `PageDown` -- Next page
+- `ArrowLeft` / `PageUp` -- Previous page
+- `Ctrl/Cmd +` -- Zoom in
+- `Ctrl/Cmd -` -- Zoom out
+
+## Usage
+
+```html
+<snice-pdf-viewer
+  src="/documents/report.pdf"
+  fit="width"
+  zoom="1"
+></snice-pdf-viewer>
+```
+
+```js
+const viewer = document.querySelector('snice-pdf-viewer');
+viewer.src = '/documents/report.pdf';
+
+viewer.addEventListener('pdf-loaded', (e) => {
+  console.log('Pages:', e.detail.totalPages);
+});
+
+viewer.addEventListener('page-change', (e) => {
+  console.log(`Page ${e.detail.page} of ${e.detail.totalPages}`);
+});
+```

package/docs/ai/components/podcast-player.md

@@ -0,0 +1,94 @@
+# snice-podcast-player
+
+Full-featured podcast player with playback controls, episode list, chapters, RSS feed support, sleep timer, and position memory via localStorage.
+
+## Properties
+
+```ts
+src: string                              // Audio source URL
+fromRss: string                          // RSS feed URL (attr: from-rss)
+title: string                            // Episode title
+show: string                             // Show/podcast name
+artwork: string                          // Artwork image URL
+description: string                      // Episode description
+playbackRate: number                     // Speed 0.5-2 (default: 1, attr: playback-rate)
+skipForward: number                      // Skip forward seconds (default: 30, attr: skip-forward)
+skipBack: number                         // Skip back seconds (default: 15, attr: skip-back)
+currentTime: number                      // Current playback position (attr: current-time)
+duration: number                         // Episode duration in seconds
+volume: number                           // Volume 0-1 (default: 1)
+muted: boolean                           // Muted state
+state: PodcastPlayerState                // 'playing'|'paused'|'stopped'|'loading'|'error'
+episodes: PodcastEpisode[]               // Episode list
+currentEpisodeIndex: number              // Active episode index (attr: current-episode-index)
+sleepTimer: number                       // Sleep timer minutes (attr: sleep-timer)
+```
+
+### Types
+
+```ts
+interface PodcastEpisode {
+  title: string;
+  src: string;
+  artwork?: string;
+  description?: string;
+  pubDate?: string;
+  duration?: number;
+  chapters?: PodcastChapter[];
+}
+
+interface PodcastChapter {
+  title: string;
+  startTime: number;
+  endTime?: number;
+  artwork?: string;
+}
+```
+
+## Methods
+
+- `play()` -- Start playback (async)
+- `pause()` -- Pause playback
+- `toggle()` -- Toggle play/pause
+- `seekTo(time: number)` -- Seek to time in seconds
+- `setPlaybackRate(rate: number)` -- Set speed (0.5-2)
+- `loadEpisode(index: number)` -- Load and switch to episode by index
+
+## Events
+
+- `podcast-play` -> `{ player, episode }` -- Playback started
+- `podcast-pause` -> `{ player, episode }` -- Playback paused
+- `podcast-ended` -> `{ player, episode }` -- Episode ended
+- `podcast-time-update` -> `{ player, currentTime, duration }` -- Time update
+- `podcast-rate-change` -> `{ player, rate }` -- Playback rate changed
+- `podcast-episode-change` -> `{ player, episode, index }` -- Episode switched
+- `podcast-feed-loaded` -> `{ player, feed: RSSFeedData }` -- RSS feed parsed
+
+## Usage
+
+```html
+<!-- Direct source -->
+<snice-podcast-player
+  src="/audio/episode.mp3"
+  title="Episode 1"
+  show="My Podcast"
+  artwork="/images/cover.jpg"
+></snice-podcast-player>
+
+<!-- From RSS feed -->
+<snice-podcast-player from-rss="https://example.com/feed.xml"></snice-podcast-player>
+```
+
+```js
+const player = document.querySelector('snice-podcast-player');
+player.episodes = [
+  { title: 'Ep 1', src: '/audio/ep1.mp3', duration: 1800 },
+  { title: 'Ep 2', src: '/audio/ep2.mp3', duration: 2400,
+    chapters: [
+      { title: 'Intro', startTime: 0 },
+      { title: 'Main Topic', startTime: 120 }
+    ]
+  }
+];
+player.loadEpisode(0);
+```

package/docs/ai/components/pricing-table.md

@@ -0,0 +1,87 @@
+# snice-pricing-table
+
+Pricing comparison with cards or table layout, monthly/annual toggle, and declarative child elements.
+
+## Properties
+
+```ts
+plans: PricingPlan[]                     // Plan data array
+variant: 'cards' | 'table'              // Layout variant (default: 'cards')
+annual: boolean                          // Show annual pricing (default: false)
+```
+
+### Types
+
+```ts
+interface PricingPlan {
+  name: string;
+  price: number;
+  annualPrice?: number;                  // Annual price (enables billing toggle)
+  period?: string;                       // e.g. '/mo' (default: '/mo')
+  currency?: string;                     // e.g. '$' (default: '$')
+  description?: string;
+  features: PricingFeature[];
+  cta: string;                           // Button text
+  ctaVariant?: 'primary' | 'secondary' | 'outline';
+  highlighted?: boolean;                 // Emphasize this plan
+  badge?: string;                        // e.g. 'Popular'
+}
+
+interface PricingFeature {
+  name: string;
+  included: boolean | string;            // true/false for check/x, string for custom value
+}
+```
+
+## Child Elements
+
+Supports declarative usage via `<snice-plan>` and `<snice-feature>`:
+
+**`<snice-plan>`** attributes: `name`, `price`, `annual-price`, `period`, `currency`, `description`, `cta`, `cta-variant`, `highlighted` (boolean), `badge`
+
+**`<snice-feature>`** attributes: `excluded` (boolean), `value` (string for custom display)
+
+## Events
+
+- `plan-select` -> `{ plan: PricingPlan; index: number; billing: 'monthly' | 'annual' }` -- CTA button clicked
+
+## CSS Parts
+
+`base`, `cards`, `card`, `cta`, `toggle`, `table-wrapper`, `table`
+
+## Usage
+
+```html
+<!-- Declarative -->
+<snice-pricing-table>
+  <snice-plan name="Free" price="0" cta="Get Started">
+    <snice-feature>5 projects</snice-feature>
+    <snice-feature excluded>API access</snice-feature>
+    <snice-feature value="1GB">Storage</snice-feature>
+  </snice-plan>
+  <snice-plan name="Pro" price="29" annual-price="24" highlighted badge="Popular" cta="Start Trial">
+    <snice-feature>Unlimited projects</snice-feature>
+    <snice-feature>API access</snice-feature>
+    <snice-feature value="100GB">Storage</snice-feature>
+  </snice-plan>
+</snice-pricing-table>
+```
+
+```js
+// Programmatic
+const table = document.querySelector('snice-pricing-table');
+table.plans = [
+  { name: 'Free', price: 0, cta: 'Get Started', features: [
+    { name: '5 projects', included: true },
+    { name: 'API access', included: false }
+  ]},
+  { name: 'Pro', price: 29, annualPrice: 24, cta: 'Start Trial', highlighted: true, badge: 'Popular', features: [
+    { name: 'Unlimited projects', included: true },
+    { name: 'API access', included: true }
+  ]}
+];
+
+table.addEventListener('plan-select', (e) => {
+  console.log(`Selected ${e.detail.plan.name} (${e.detail.billing})`);
+});
+```

package/docs/ai/components/progress.md

@@ -10,78 +10,62 @@ max: number = 100;
 variant: 'linear'|'circular' = 'linear';
 indeterminate: boolean = false;
 size: 'small'|'medium'|'large'|'xl'|'xxl'|'xxxl' = 'medium';
-color: 'primary'|'success'|'warning'|'error'|'info'|string = 'primary';  // semantic or any CSS color
-showLabel: boolean = false;
+color: 'primary'|'success'|'warning'|'error'|'info'|string = 'primary';
+showLabel: boolean = false;       // attr: show-label
 label: string = '';
 striped: boolean = false;
 animated: boolean = false;
-thickness: number = 4;  // Stroke width for circular variant
+thickness: number = 4;            // Stroke width for circular variant
 ```
 
 ## Methods
 
 - `setProgress(value, max?)` - Set progress value
-- `getPercentage()` - Get calculated percentage
+- `getPercentage()` - Get calculated percentage (0-100)
 
 ## Events
 
-- `progress-change` - {value, max, percentage, indeterminate}
+- `progress-change` → `{ value, max, percentage, indeterminate }`
 
 ## Usage
 
 ```html
-<!-- Basic linear -->
+<!-- Linear -->
 <snice-progress value="50"></snice-progress>
 
 <!-- Circular -->
-<snice-progress variant="circular" value="75"></snice-progress>
+<snice-progress variant="circular" value="75" size="xl"></snice-progress>
 
-<!-- Indeterminate (loading) -->
+<!-- Indeterminate -->
 <snice-progress indeterminate></snice-progress>
-<snice-progress variant="circular" indeterminate></snice-progress>
 
 <!-- With label -->
 <snice-progress value="60" show-label></snice-progress>
 <snice-progress value="60" label="Uploading..."></snice-progress>
 
-<!-- Custom max -->
-<snice-progress value="3" max="10"></snice-progress>
-
 <!-- Striped and animated -->
-<snice-progress value="70" striped></snice-progress>
 <snice-progress value="70" striped animated></snice-progress>
 
-<!-- Color variants -->
-<snice-progress value="80" color="primary"></snice-progress>
+<!-- Colors -->
 <snice-progress value="80" color="success"></snice-progress>
-
-<!-- Custom colors -->
 <snice-progress value="80" color="#3b82f6"></snice-progress>
-<snice-progress value="80" color="rgb(59, 130, 246)"></snice-progress>
-
-<!-- Sizes -->
-<snice-progress value="50" size="small"></snice-progress>
-<snice-progress value="50" size="medium"></snice-progress>
-<snice-progress value="50" size="large"></snice-progress>
-
-<!-- Dynamic updates -->
-<snice-progress id="prog" value="0"></snice-progress>
-<script>
-const prog = document.querySelector('#prog');
-let val = 0;
-setInterval(() => {
-  val = (val + 10) % 100;
-  prog.value = val;
-}, 500);
-</script>
+
+<!-- Custom max -->
+<snice-progress value="3" max="10"></snice-progress>
+```
+
+```typescript
+const prog = document.querySelector('snice-progress');
+prog.setProgress(75);
+prog.setProgress(3, 10);
+console.log(prog.getPercentage());
 ```
 
 ## Features
 
-- Linear or circular variant
+- Linear and circular variants
 - Indeterminate mode for unknown progress
-- Optional percentage label or custom text
+- Optional percentage or custom label
 - Striped and animated styles
-- 5 color variants
-- 6 sizes
-- Reactive value updates
+- 5 semantic + custom CSS colors
+- 6 sizes (small through xxxl)