snice 4.28.0 → 4.30.0

package/docs/components/scheduler.md

@@ -1,160 +1,94 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/scheduler.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/scheduler.md -->
 
-# Scheduler Component
-`<snice-scheduler>`
+# Scheduler
 
-A multi-resource week/day/month scheduler for managing events across people, rooms, or equipment.
+A multi-resource week/day/month scheduler for managing events across people, rooms, or equipment. Supports drag-to-create, move, and resize events.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/scheduler/snice-scheduler';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-scheduler.min.js"></script>
-```
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
-| Property | Attribute | Type | Default | Description |
-|----------|-----------|------|---------|-------------|
-| `resources` | — | `SchedulerResource[]` | `[]` | Array of resources (rows) |
-| `events` | — | `SchedulerEvent[]` | `[]` | Array of events on the grid |
-| `view` | `view` | `'day' \| 'week' \| 'month'` | `'week'` | Current view mode |
-| `date` | `date` | `Date \| string` | `new Date()` | Current view date |
-| `granularity` | `granularity` | `number` | `60` | Slot size in minutes (15, 30, 60) |
-| `startHour` | `start-hour` | `number` | `0` | First hour displayed |
-| `endHour` | `end-hour` | `number` | `24` | Last hour displayed |
-
-## Methods
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `resources` | `SchedulerResource[]` | `[]` | Array of resources/rows (JS only) |
+| `events` | `SchedulerEvent[]` | `[]` | Array of events on the grid (JS only) |
+| `view` | `'day' \| 'week' \| 'month'` | `'week'` | Current view mode |
+| `date` | `Date \| string` | `new Date()` | Current view date |
+| `granularity` | `number` | `60` | Slot size in minutes (15, 30, 60) |
+| `startHour` (attr: `start-hour`) | `number` | `0` | First hour displayed |
+| `endHour` (attr: `end-hour`) | `number` | `24` | Last hour displayed |
 
-### `addEvent(event: SchedulerEvent): void`
-Add a new event to the scheduler.
+### Type Interfaces
 
 ```typescript
-scheduler.addEvent({
-  id: 'new-1',
-  resourceId: '1',
-  start: new Date(2025, 5, 15, 14, 0),
-  end: new Date(2025, 5, 15, 15, 0),
-  title: 'New Appointment'
-});
-```
-
-### `removeEvent(id: string | number): void`
-Remove an event by its ID.
-
-```typescript
-scheduler.removeEvent('1');
-```
-
-### `scrollToDate(date: Date | string): void`
-Navigate the scheduler to a specific date.
+interface SchedulerResource {
+  id: string | number;
+  name: string;
+  avatar?: string;  // Avatar image URL
+  color?: string;   // Accent color
+}
 
-```typescript
-scheduler.scrollToDate(new Date(2025, 5, 20));
+interface SchedulerEvent {
+  id: string | number;
+  resourceId: string | number;
+  start: Date | string;
+  end: Date | string;
+  title: string;
+  color?: string;
+  data?: any;
+}
 ```
 
-### `scrollToResource(id: string | number): void`
-Scroll a resource row into view.
+## Methods
 
-```typescript
-scheduler.scrollToResource('3');
-```
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `addEvent()` | `event: SchedulerEvent` | Add a new event to the scheduler |
+| `removeEvent()` | `id: string \| number` | Remove an event by its ID |
+| `scrollToDate()` | `date: Date \| string` | Navigate to a specific date |
+| `scrollToResource()` | `id: string \| number` | Scroll a resource row into view |
 
 ## Events
 
-### `event-create`
-Dispatched when a new event is created by dragging on an empty slot.
-
-```typescript
-scheduler.addEventListener('event-create', (e) => {
-  console.log('New event:', e.detail.event);
-});
-```
-
-**Detail:** `{ event: SchedulerEvent }`
-
-### `event-move`
-Dispatched when an event is dragged to a new position or resource.
-
-```typescript
-scheduler.addEventListener('event-move', (e) => {
-  console.log('Moved:', e.detail.event.title);
-  console.log('From resource:', e.detail.oldResourceId);
-  console.log('Old time:', e.detail.oldStart, '-', e.detail.oldEnd);
-});
-```
-
-**Detail:** `{ event: SchedulerEvent, oldResourceId: string | number, oldStart: Date | string, oldEnd: Date | string }`
-
-### `event-resize`
-Dispatched when an event is resized via edge handles.
-
-```typescript
-scheduler.addEventListener('event-resize', (e) => {
-  console.log('Resized:', e.detail.event.title);
-});
-```
-
-**Detail:** `{ event: SchedulerEvent, oldStart: Date | string, oldEnd: Date | string }`
-
-### `event-click`
-Dispatched when an event is clicked.
-
-```typescript
-scheduler.addEventListener('event-click', (e) => {
-  showEventDetails(e.detail.event);
-});
-```
-
-**Detail:** `{ event: SchedulerEvent }`
-
-### `slot-click`
-Dispatched when an empty time slot is clicked.
-
-```typescript
-scheduler.addEventListener('slot-click', (e) => {
-  console.log('Resource:', e.detail.resourceId);
-  console.log('Time:', e.detail.start, '-', e.detail.end);
-});
-```
-
-**Detail:** `{ resourceId: string | number, start: Date, end: Date }`
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `event-create` | `{ event: SchedulerEvent }` | New event created by dragging on empty slot |
+| `event-move` | `{ event, oldResourceId, oldStart, oldEnd }` | Event dragged to new position/resource |
+| `event-resize` | `{ event, oldStart, oldEnd }` | Event resized via edge handles |
+| `event-click` | `{ event: SchedulerEvent }` | Event clicked |
+| `slot-click` | `{ resourceId, start: Date, end: Date }` | Empty time slot clicked |
 
 ## CSS Parts
 
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Main scheduler container |
-| `header` | `<div>` | Navigation header with view toggle |
-| `resources` | `<div>` | Resource sidebar |
-| `grid` | `<div>` | Time grid area |
+| Part | Description |
+|------|-------------|
+| `base` | Main scheduler container |
+| `header` | Navigation header with view toggle |
+| `resources` | Resource sidebar |
+| `grid` | Time grid area |
 
-```css
-snice-scheduler::part(base) {
-  border-radius: 12px;
-}
+## Basic Usage
 
-snice-scheduler::part(header) {
-  background: #f5f5f5;
-}
+```typescript
+import 'snice/components/scheduler/snice-scheduler';
 ```
 
-## Basic Usage
-
 ```html
-<snice-scheduler></snice-scheduler>
+<snice-scheduler start-hour="8" end-hour="18" granularity="30"></snice-scheduler>
 ```
 
 ```typescript
 scheduler.resources = [
   { id: '1', name: 'Dr. Smith', color: '#2196f3' },
-  { id: '2', name: 'Room A', color: '#ff9800' },
+  { id: '2', name: 'Room A', color: '#ff9800' }
 ];
 
 scheduler.events = [
@@ -164,98 +98,66 @@ scheduler.events = [
     start: new Date(2025, 5, 15, 9, 0),
     end: new Date(2025, 5, 15, 10, 30),
     title: 'Patient Consultation'
-  },
+  }
 ];
 ```
 
 ## Examples
 
-### Week View with Resources
-
-```typescript
-scheduler.resources = [
-  { id: '1', name: 'Dr. Smith', avatar: '/avatars/smith.jpg', color: '#2196f3' },
-  { id: '2', name: 'Dr. Johnson', color: '#4caf50' },
-  { id: '3', name: 'Conference Room', color: '#ff9800' },
-];
-```
-
 ### Business Hours Only
 
+Use `start-hour` and `end-hour` to limit the displayed time range.
+
 ```html
 <snice-scheduler start-hour="9" end-hour="17" granularity="30"></snice-scheduler>
 ```
 
 ### Day View with 15-Minute Slots
 
+Use `view="day"` and `granularity="15"` for fine-grained scheduling.
+
 ```html
 <snice-scheduler view="day" granularity="15" start-hour="8" end-hour="20"></snice-scheduler>
 ```
 
-### Handling Event Interactions
+### Creating Events from Slot Clicks
+
+Listen for `slot-click` to create new events when empty slots are clicked.
 
 ```typescript
-// Create new events from empty slots
 scheduler.addEventListener('slot-click', (e) => {
-  const newEvent = {
+  scheduler.addEvent({
     id: `evt-${Date.now()}`,
     resourceId: e.detail.resourceId,
     start: e.detail.start,
     end: e.detail.end,
     title: 'New Appointment',
     color: '#2196f3'
-  };
-  scheduler.addEvent(newEvent);
+  });
 });
+```
+
+### Handling Moves and Resizes
+
+Listen for `event-move` and `event-resize` to persist changes.
 
-// Handle event moves
+```typescript
 scheduler.addEventListener('event-move', (e) => {
   saveEventToBackend(e.detail.event);
 });
 
-// Handle event resizes
 scheduler.addEventListener('event-resize', (e) => {
   saveEventToBackend(e.detail.event);
 });
 ```
 
-### Navigate Programmatically
+### Programmatic Navigation
+
+Change the view date and mode programmatically.
 
 ```typescript
-// Go to today
 scheduler.date = new Date();
-
-// Switch views
 scheduler.view = 'day';
-scheduler.view = 'week';
-scheduler.view = 'month';
-```
-
-## Interfaces
-
-### SchedulerResource
-
-```typescript
-interface SchedulerResource {
-  id: string | number;
-  name: string;
-  avatar?: string;  // URL for avatar image
-  color?: string;   // Color for avatar fallback
-}
-```
-
-### SchedulerEvent
-
-```typescript
-interface SchedulerEvent {
-  id: string | number;
-  resourceId: string | number;
-  start: Date | string;
-  end: Date | string;
-  title: string;
-  color?: string;
-  data?: any;
-}
 ```
 
 ## Accessibility
@@ -263,9 +165,4 @@ interface SchedulerEvent {
 - Keyboard navigation with arrow keys
 - ARIA labels for resources and time slots
 - Focus management for events
-- Screen reader support
-
-## Browser Support
-
-- Modern browsers with Custom Elements v1 support
-- Mouse and touch interaction for drag operations
+- Current time indicator in the grid

package/docs/components/segmented-control.md

@@ -1,44 +1,50 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/segmented-control.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/segmented-control.md -->
 
 # Segmented Control
-`<snice-segmented-control>`
 
-A multi-option switcher with a sliding indicator. One option is selected at a time. Unlike a switch (binary) or tabs (with content panes), this is purely a value selector for multiple options.
+A multi-option switcher with a sliding indicator. One option is selected at a time. Unlike tabs, this is purely a value selector without content panes.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/segmented-control/snice-segmented-control';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-segmented-control.min.js"></script>
-```
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `value` | `string` | `''` | Selected option value |
-| `options` | `SegmentedControlOption[]` | `[]` | Array of `{ value, label, icon?, disabled? }` |
+| `options` | `SegmentedControlOption[]` | `[]` | Array of `{ value, label, icon?, disabled? }` (JS only) |
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Control size |
 | `disabled` | `boolean` | `false` | Disables the entire control |
 
+### Type Interface
+
+```typescript
+interface SegmentedControlOption {
+  value: string;
+  label: string;
+  icon?: string;
+  disabled?: boolean;
+}
+```
+
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `value-change` | `{ value, previousValue, option, control }` | Selection changed |
+| `value-change` | `{ value: string, previousValue: string, option: SegmentedControlOption, control }` | Selection changed |
 
 ## CSS Parts
 
 | Part | Description |
 |------|-------------|
 | `base` | The control container |
-| `indicator` | The sliding indicator |
+| `indicator` | The sliding selection indicator |
 | `segment` | Each segment button |
 
 ## Basic Usage
@@ -55,12 +61,20 @@ import 'snice/components/segmented-control/snice-segmented-control';
 control.options = [
   { value: 'day', label: 'Day' },
   { value: 'week', label: 'Week' },
-  { value: 'month', label: 'Month' },
+  { value: 'month', label: 'Month' }
 ];
 ```
 
 ## Examples
 
+### Pre-selected Value
+
+Set the `value` attribute to pre-select an option.
+
+```html
+<snice-segmented-control value="week"></snice-segmented-control>
+```
+
 ### Sizes
 
 Use the `size` attribute to change the control size.
@@ -71,12 +85,15 @@ Use the `size` attribute to change the control size.
 <snice-segmented-control size="large"></snice-segmented-control>
 ```
 
-### Pre-selected Value
+### With Icons
 
-Set the `value` attribute to pre-select an option.
+Pass an `icon` URL in option objects to display icons alongside labels.
 
-```html
-<snice-segmented-control value="week"></snice-segmented-control>
+```typescript
+control.options = [
+  { value: 'grid', label: 'Grid', icon: '/icons/grid.svg' },
+  { value: 'list', label: 'List', icon: '/icons/list.svg' }
+];
 ```
 
 ### Disabled Options
@@ -87,7 +104,7 @@ Options with `disabled: true` cannot be selected.
 control.options = [
   { value: 'free', label: 'Free' },
   { value: 'pro', label: 'Pro' },
-  { value: 'enterprise', label: 'Enterprise', disabled: true },
+  { value: 'enterprise', label: 'Enterprise', disabled: true }
 ];
 ```
 
@@ -99,29 +116,20 @@ Disable the entire control with the `disabled` attribute.
 <snice-segmented-control disabled></snice-segmented-control>
 ```
 
-### With Icons
-
-Pass an `icon` URL in option objects to display icons alongside labels.
-
-```typescript
-control.options = [
-  { value: 'grid', label: 'Grid', icon: '/icons/grid.svg' },
-  { value: 'list', label: 'List', icon: '/icons/list.svg' },
-];
-```
-
 ### Event Handling
 
+Listen to `value-change` to respond to selection changes.
+
 ```typescript
 control.addEventListener('value-change', (e) => {
   console.log('New value:', e.detail.value);
-  console.log('Previous value:', e.detail.previousValue);
-  console.log('Selected option:', e.detail.option);
+  console.log('Previous:', e.detail.previousValue);
 });
 ```
 
-### Programmatic Control
+## Accessibility
 
-```typescript
-control.value = 'month';
-```
+- Uses `role="radiogroup"` with `role="radio"` per segment
+- Sliding indicator animates between selections
+- If no value set, first non-disabled option is selected
+- Disabled segments are not focusable