@mhmo91/schmancy 0.8.6 → 0.9.3

package/ai/notification.md

@@ -1,194 +1,60 @@
-# Schmancy Notification - AI Reference
+# $notify
 
-## Core Notification Service
+> Notification service with type-colored luminous glow, progress bar countdown, and arc-path entry animation.
 
-```js
-import { $notify } from '@schmancy/index'
-// Or specific import: import { $notify } from '@schmancy/notification'
+## Usage
+```typescript
+import { $notify } from '@mhmo91/schmancy'
 
-// Display notification methods
-$notify.info(message?, options?) -> string    // Returns notification ID
-$notify.success(message?, options?) -> string
-$notify.warning(message?, options?) -> string
-$notify.error(message?, options?) -> string
-
-// Custom notification
-$notify.show({
-  message: string,
-  type?: 'info'|'success'|'warning'|'error',
-  title?: string,
-  duration?: number,      // milliseconds, default 1000
-  closable?: boolean,     // default true
-  playSound?: boolean,    // default true
-  showProgress?: boolean, // show progress bar
-  id?: string            // custom ID
-}) -> string
-
-// Dismiss notifications
-$notify.dismiss(id?)     // Dismisses specific notification or latest if no ID
-
-// Update notification content
-$notify.update(id, options)  // Update existing notification
-
-// Persistent notification
-$notify.persistent(message, options)  // Won't auto-dismiss (duration: 0)
-
-// Custom duration
-$notify.customDuration(message, duration, options)
-```
-
-## API Integration with notify()
-
-The `notify()` operator wraps observables with automatic notification lifecycle management.
-
-```js
-import { notify } from '@schmancy/index'
-// Or specific import: import { notify } from '@schmancy/notification'
-
-// Basic usage - minimal configuration
-someApiCall().pipe(
-  notify({
-    loadingMessage: 'Loading data...',
-    successMessage: 'Data loaded!',
-    errorMessage: 'Failed to load'
-  })
-).subscribe()
-
-// With custom durations
-saveData().pipe(
-  notify({
-    loadingMessage: 'Saving...',
-    successMessage: 'Saved!',
-    successDuration: 5000,  // Success stays 5 seconds
-    errorMessage: 'Save failed',
-    errorDuration: 0        // Error is persistent
-  })
-).subscribe()
-
-// Full configuration
-uploadFile().pipe(
-  notify({
-    // Loading state
-    loadingMessage: 'Uploading file...',
-    loadingType: 'info',
-    
-    // Success state
-    successMessage: 'Upload complete!',
-    successType: 'success',
-    successDuration: 3000,
-    
-    // Error state
-    errorMessage: (err) => `Upload failed: ${err.message}`,
-    errorType: 'error',
-    errorDuration: 10000,
-    
-    // Options
-    autoDismissLoading: true
-  })
-).subscribe()
-
-// With progress tracking
-// Automatically detects { progress: number } or { loaded, total } in emissions
-fileUpload().pipe(
-  notify({
-    loadingMessage: 'Uploading...',  // Updates to "Uploading... (50%)"
-    successMessage: 'Upload complete!',
-    errorMessage: 'Upload failed'
-  })
-).subscribe()
-```
-
-### notify() Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `loadingMessage` | string | Message during loading |
-| `loadingType` | NotificationType | Type for loading notification |
-| `successMessage` | string | Message on success |
-| `successType` | NotificationType | Type for success notification |
-| `successDuration` | number | Duration for success (ms, 0 = persistent) |
-| `errorMessage` | string \| (err) => string | Message on error |
-| `errorType` | NotificationType | Type for error notification |
-| `errorDuration` | number | Duration for error (ms, 0 = persistent) |
-| `autoDismissLoading` | boolean | Auto-dismiss loading on complete |
-
-## Components
-
-### Notification Container
-
-```html
-<schmancy-notification-container
-  position="top-right|top-left|bottom-right|bottom-left|top-center|bottom-center"
-  max-visible-notifications="2"
-  play-sound="true|false"
-  audio-volume="0.1">
-</schmancy-notification-container>
+$notify.success('Item saved')
+$notify.error('Failed to connect')
 ```
 
-### Individual Notification (used internally)
-
-```html
-<schmancy-notification
-  title="Title"
-  message="Message text"
-  type="info|success|warning|error"
-  duration="5000"
-  closable="true"
-  play-sound="true"
-  show-progress="false"
-  @close>
-</schmancy-notification>
-```
+## $notify API
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `success(message?, options?)` | `string` (id) | Green glow, 1.5s duration |
+| `error(message?, options?)` | `string` (id) | Red glow, 2.5s duration |
+| `warning(message?, options?)` | `string` (id) | Orange glow, 2.5s duration |
+| `info(message?, options?)` | `string` (id) | Blue glow, 2s duration |
+| `show(options)` | `string` (id) | Full options control |
+| `persistent(message, options?)` | `string` (id) | No auto-dismiss (duration: 0) |
+| `customDuration(msg, ms, options?)` | `string` (id) | Custom duration in ms |
+| `dismiss(id?)` | `void` | Dismiss by id or most recent |
+| `update(id, options)` | `void` | Update existing notification content |
+
+## Options
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `message` | `string` | required | Notification body text |
+| `title` | `string` | `undefined` | Optional title line |
+| `type` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | Notification type |
+| `duration` | `number` | Type-specific | Auto-dismiss ms (0 = persistent) |
+| `closable` | `boolean` | `true` | Show close button |
+| `playSound` | `boolean` | `true` | Play type-specific sound |
+| `showProgress` | `boolean` | `false` | Show indeterminate progress bar |
+
+## Physics
+- Type-colored luminous glow shadow (18% intensity, 28% on hover)
+- Arc-path entry animation from last click position to top-right corner
+- Hover: glow intensifies + `translateY(-2px)` lift
+- Progress bar shows countdown timer; pauses on hover
+- Only one notification visible at a time (replaces previous)
 
 ## Examples
+```typescript
+// Success with title
+$notify.success('Changes saved', { title: 'Success' })
 
-```js
-// Basic notifications
-$notify.success("Operation completed")
-$notify.error("Failed to save", { duration: 5000 })
-$notify.info() // Just icon, no message
+// Persistent loading indicator
+const id = $notify.persistent('Processing...', { showProgress: true })
+// Later: dismiss it
+$notify.dismiss(id)
 
-// Persistent notification
-const id = $notify.persistent("Processing...")
-// Later: $notify.dismiss(id)
+// Error with longer duration
+$notify.error('Connection lost', { duration: 5000 })
 
-// API with loading state
-fetchData().pipe(
-  notify({
-    loadingMessage: 'Fetching...',
-    successMessage: 'Data loaded!',
-    errorMessage: 'Failed'
-  })
-).subscribe()
-
-// File upload with progress
-upload(file).pipe(
-  notify({
-    loadingMessage: 'Uploading file...',
-    successMessage: 'Upload complete!',
-    successDuration: 3000,
-    errorMessage: (err) => `Upload failed: ${err.message}`,
-    errorDuration: 0  // Persistent error
-  })
-).subscribe()
+// Update existing notification
+const nid = $notify.info('Uploading...')
+$notify.update(nid, { message: 'Upload complete', type: 'success' })
 ```
-
-## Setup
-
-Add the notification container once in your app layout:
-
-```html
-<schmancy-notification-container
-  position="top-right"
-  max-visible-notifications="3"
-  play-sound="true">
-</schmancy-notification-container>
-```
-
-## Progress Indication
-
-- Notifications automatically show a progress bar when `duration > 0` (countdown)
-- When using `notify()` operator, shows indeterminate progress during loading
-- Detects progress in observable emissions:
-  - `{ progress: 50 }` - Shows "Loading... (50%)"
-  - `{ loaded: 500, total: 1000 }` - Shows "Loading... (50%)"

package/ai/option.md

@@ -1,173 +1,43 @@
-# Option Component
+# schmancy-option
 
-A versatile option element designed for use with select dropdowns and autocomplete components, providing accessible and interactive selection items.
-
-## Quick Start
+> Selectable item for `schmancy-select`, `schmancy-autocomplete`, and `schmancy-menu`. Lightweight and a11y-ready.
 
+## Usage
 ```html
-<!-- Basic option -->
-<schmancy-option value="1">Option One</schmancy-option>
-
-<!-- Option with custom label -->
-<schmancy-option value="us">United States</schmancy-option>
-
-<!-- Option with icon -->
-<schmancy-option value="email" icon="✉️">Email Notifications</schmancy-option>
+<schmancy-select label="Country">
+  <schmancy-option value="us">United States</schmancy-option>
+  <schmancy-option value="de">Germany</schmancy-option>
+  <schmancy-option value="jp" disabled>Japan</schmancy-option>
+</schmancy-select>
 ```
 
 ## Properties
-
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `value` | `string` | `''` | The value when selected |
-| `label` | `string` | `''` | Display label (defaults to text content) |
-| `selected` | `boolean` | `false` | Whether option is selected |
-| `disabled` | `boolean` | `false` | Whether option is disabled |
-| `group` | `string` | `''` | Optional group name |
-| `icon` | `string` | `''` | Optional icon/emoji |
+| `value` | string | `''` | Value reported when this option is selected |
+| `label` | string | auto | Display label (falls back to text content) |
+| `selected` | boolean | `false` | Reflects selected state |
+| `disabled` | boolean | `false` | Disables interaction |
+| `group` | string | `''` | Grouping identifier for grouped lists |
+| `icon` | string | `''` | Material icon name before the label |
 
 ## Events
-
-### option-select
-Fired when option is clicked or selected via keyboard.
-
-```typescript
-interface OptionSelectEvent {
-  detail: {
-    value: string;
-  }
-}
-```
-
-## Examples
-
-### In Select Component
+| Event | Payload | When |
+|-------|---------|------|
+| `click` | — | Standard click event |
+| `option-select` | `CustomEvent<{ value, label }>` | Dispatched on activation |
+
+## Behavior
+- Auto-generates `id` for ARIA wiring if not set.
+- Infers `label` from text content when omitted.
+- Keyboard focusable with a visible focus ring via `:focus-visible`.
+- Parent select/autocomplete coordinates selection state via slot query.
+
+## Example — grouped options
 ```html
-<schmancy-select placeholder="Choose country">
-  <schmancy-option value="us" icon="🇺🇸">United States</schmancy-option>
-  <schmancy-option value="uk" icon="🇬🇧">United Kingdom</schmancy-option>
-  <schmancy-option value="ca" icon="🇨🇦">Canada</schmancy-option>
-  <schmancy-option value="au" icon="🇦🇺">Australia</schmancy-option>
+<schmancy-select label="Framework">
+  <schmancy-option value="lit" group="web" icon="bolt">Lit</schmancy-option>
+  <schmancy-option value="react" group="web">React</schmancy-option>
+  <schmancy-option value="swift" group="mobile">Swift</schmancy-option>
 </schmancy-select>
 ```
-
-### Grouped Options
-```html
-<schmancy-select>
-  <!-- North America -->
-  <schmancy-option value="us" group="North America">United States</schmancy-option>
-  <schmancy-option value="ca" group="North America">Canada</schmancy-option>
-  <schmancy-option value="mx" group="North America">Mexico</schmancy-option>
-  
-  <!-- Europe -->
-  <schmancy-option value="uk" group="Europe">United Kingdom</schmancy-option>
-  <schmancy-option value="de" group="Europe">Germany</schmancy-option>
-  <schmancy-option value="fr" group="Europe">France</schmancy-option>
-</schmancy-select>
-```
-
-### With Status Indicators
-```html
-<schmancy-autocomplete>
-  <schmancy-option value="active" icon="🟢">Active</schmancy-option>
-  <schmancy-option value="pending" icon="🟡">Pending</schmancy-option>
-  <schmancy-option value="inactive" icon="🔴">Inactive</schmancy-option>
-  <schmancy-option value="archived" icon="📦" disabled>Archived</schmancy-option>
-</schmancy-autocomplete>
-```
-
-### Dynamic Options
-```html
-${users.map(user => html`
-  <schmancy-option 
-    value="${user.id}"
-    label="${user.name}"
-    ?disabled="${!user.active}"
-  >
-    <span class="flex items-center gap-2">
-      <schmancy-avatar size="xs" name="${user.name}"></schmancy-avatar>
-      <span>
-        <div>${user.name}</div>
-        <div class="text-xs opacity-70">${user.email}</div>
-      </span>
-    </span>
-  </schmancy-option>
-`)}
-```
-
-## Features
-
-### Automatic Value Assignment
-- If no value is provided, uses text content
-- If no label is provided, uses text content or value
-
-### Keyboard Navigation
-- `Space` or `Enter` to select
-- Full keyboard accessibility
-
-### Visual States
-- Hover highlighting
-- Selected state with checkmark
-- Disabled state with reduced opacity
-- Focus ring for keyboard navigation
-
-### Unique IDs
-Automatically generates unique IDs for accessibility if not provided.
-
-## Styling
-
-The component uses semantic design tokens:
-
-```css
-/* Default state */
-.hover:bg-surface-high
-
-/* Selected state */
-.bg-primary-container
-.text-primary-onContainer
-
-/* Custom styling */
-schmancy-option {
-  --option-padding-y: 0.5rem;
-  --option-padding-x: 0.75rem;
-  --option-border-radius: 0.25rem;
-}
-```
-
-## Accessibility
-
-- `role="option"` for semantic meaning
-- `aria-selected` state management
-- `aria-disabled` for disabled options
-- Keyboard event handling
-- Focus management
-
-## Integration
-
-Options are designed to work seamlessly with:
-- `schmancy-select` - Dropdown selection
-- `schmancy-autocomplete` - Filtered selection
-- Custom dropdown components
-
-## Best Practices
-
-1. **Clear Values**: Use meaningful, unique values
-2. **Icons**: Use icons to improve scannability
-3. **Groups**: Group related options together
-4. **Labels**: Provide clear, concise labels
-5. **Disabled State**: Clearly indicate why options are disabled
-
-## Related Components
-
-- [Select](./select.md) - Dropdown selector
-- [Autocomplete](./autocomplete.md) - Searchable selector
-- [List](./list.md) - Similar list item pattern
-- [Menu](./menu.md) - Menu items
-
-## Use Cases
-
-1. **Form Selects**: Country, state, category selection
-2. **Settings**: Preference options
-3. **Filters**: Data filtering options
-4. **Status Selection**: Workflow states
-5. **User Selection**: Team member pickers

package/ai/page.md

@@ -0,0 +1,42 @@
+# schmancy-page
+
+> Native mobile-like page container. Fills remaining viewport height, prevents rubber-banding, pull-to-refresh, and double-tap zoom.
+
+## Usage
+```html
+<schmancy-page rows="auto_1fr_auto">
+  <header>App bar</header>
+  <main>Scrollable content</main>
+  <footer>Bottom nav</footer>
+</schmancy-page>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `rows` | string | `'auto_1fr_auto'` | Grid template rows — underscores become spaces (e.g. `'1fr_2fr_auto'`) |
+| `show-scrollbar` | boolean | `false` | Display scrollbar on scrollable area |
+| `no-select` | boolean | `false` | Disable text selection |
+
+## Behavior
+- Listens to `visualViewport` resize/scroll + `orientationchange` + keyboard focus events to recompute height.
+- Accounts for theme bottom offset (iOS safe area, home indicator).
+- Auto-assigns semantic elements (`header`, `main`, `footer`) to slots.
+- Inner scroll area uses `schmancy-scroll` for momentum-preserving scroll.
+
+## When to Use
+- Root of a mobile view or panel that should feel like a native page.
+- Any container where viewport-aware height + scroll containment matters.
+
+## Example — 3-row app shell
+```html
+<schmancy-page rows="auto_1fr_auto">
+  <schmancy-surface type="solid" rounded="none">
+    <schmancy-typography type="title">My App</schmancy-typography>
+  </schmancy-surface>
+
+  <div class="p-4">…scrollable content…</div>
+
+  <schmancy-navigation-bar></schmancy-navigation-bar>
+</schmancy-page>
+```

package/ai/progress.md

@@ -1,69 +1,30 @@
-# Schmancy Progress - AI Reference
+# schmancy-progress
 
-Linear progress indicator showing task completion status.
+> Linear progress bar with determinate and indeterminate modes, color variants, and glass effect.
 
-```js
-// Component Tag
-<schmancy-progress
-  value="number"
-  max="number"
-  size="sm|md|lg"
-  color="primary|secondary|tertiary|error|success"
-  indeterminate?>
-</schmancy-progress>
-
-// Examples
-// 1. Basic progress
-<schmancy-progress value="30" max="100"></schmancy-progress>
-
-// 2. Different sizes
-<schmancy-progress value="50" max="100" size="sm"></schmancy-progress>
-<schmancy-progress value="50" max="100" size="md"></schmancy-progress>
-<schmancy-progress value="50" max="100" size="lg"></schmancy-progress>
-
-// 3. Color variants
-<schmancy-progress value="60" max="100" color="primary"></schmancy-progress>
-<schmancy-progress value="60" max="100" color="success"></schmancy-progress>
-<schmancy-progress value="60" max="100" color="error"></schmancy-progress>
-
-// 4. Indeterminate progress
-<schmancy-progress indeterminate></schmancy-progress>
-
-// 5. Custom max value
-<schmancy-progress value="750" max="1000"></schmancy-progress>
-
-// 6. With labels
-<div class="space-y-2">
-  <div class="flex justify-between mb-1">
-    <schmancy-typography type="label" token="sm">Upload Progress</schmancy-typography>
-    <schmancy-typography type="label" token="sm">75%</schmancy-typography>
-  </div>
-  <schmancy-progress value="75" max="100" color="success"></schmancy-progress>
-</div>
+## Usage
+```html
+<schmancy-progress value="60" max="100"></schmancy-progress>
 ```
 
-## Related Components
-- **[Circular Progress](./circular-progress.md)**: For circular progress indicators
-- **[Typography](./typography.md)**: For progress labels
-
-## Technical Details
-### Properties
-- `value`: Current progress value (0 to max)
-- `max`: Maximum value (default: 100)
-- `size`: Height variant - sm (2px), md (4px), lg (8px)
-- `color`: Theme color variant
-- `indeterminate`: Shows animated progress when value unknown
-
-### CSS Implementation
-Uses Tailwind classes:
-- Container: `bg-surface-container rounded-full`
-- Bar: `bg-[color] transition-all duration-300`
-- Sizes: `h-0.5` (sm), `h-1` (md), `h-2` (lg)
-- Indeterminate: Custom animation for continuous movement
-
-## Common Use Cases
-1. **File Upload**: Show upload progress with percentage
-2. **Form Completion**: Display multi-step form progress
-3. **Loading States**: Indeterminate mode for unknown duration
-4. **Data Processing**: Track batch operation progress
-5. **Download Progress**: Show download completion status
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | number | `0` | Current progress value |
+| max | number | `100` | Maximum value |
+| indeterminate | boolean | `false` | Show indeterminate animation |
+| size | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Track height (1px, 2px, 4px, 8px) |
+| color | `'primary'\|'secondary'\|'tertiary'\|'error'\|'success'` | `'primary'` | Bar color |
+| glass | boolean | `false` | Glass/frosted effect |
+
+## Examples
+```html
+<!-- Indeterminate loading -->
+<schmancy-progress indeterminate color="secondary"></schmancy-progress>
+
+<!-- Glass effect progress -->
+<schmancy-progress value="75" glass size="lg" color="success"></schmancy-progress>
+
+<!-- Thin track -->
+<schmancy-progress value="30" size="xs"></schmancy-progress>
+```

package/ai/qr-scanner.md

@@ -0,0 +1,51 @@
+# schmancy-qr-scanner
+
+> Camera-based QR code scanner using `jsQR`. Requests rear-camera access, decodes frames in real time, deduplicates reads.
+
+## Usage
+```html
+<schmancy-qr-scanner
+  continuous
+  @scan-result=${e => this.handleScan(e.detail.data)}
+></schmancy-qr-scanner>
+```
+
+```typescript
+handleScan(data: string) {
+  console.log('QR decoded:', data)
+}
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `continuous` | boolean | `true` | Keep scanning after a successful read (dedupe repeated reads) |
+
+## Events
+| Event | Detail | When |
+|-------|--------|------|
+| `scan-result` | `{ data: string, timestamp: number }` | QR code successfully decoded |
+
+## Behavior
+- Requests `getUserMedia` with `facingMode: 'environment'` (rear camera) at 1280×720.
+- Decodes via `jsQR` on `animationFrames` stream with `throttleTime` to avoid CPU thrashing.
+- `distinctUntilChanged` prevents duplicate emissions for the same code.
+- Brief success flash on each valid read.
+- Stops camera + tears down subscriptions on disconnect.
+- Displays an error state if camera permission is denied.
+
+## Requires
+- HTTPS (or `localhost`) for camera access.
+- User permission to the camera.
+
+## Example
+```html
+<schmancy-surface type="glass" rounded="all">
+  <schmancy-qr-scanner
+    @scan-result=${(e: CustomEvent<{ data: string }>) => {
+      $notify.success(`Scanned: ${e.detail.data}`)
+      this.scannedCode = e.detail.data
+    }}
+  ></schmancy-qr-scanner>
+</schmancy-surface>
+```