snice 4.27.0 → 4.29.0

package/docs/components/calendar.md

@@ -1,8 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/calendar.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/calendar.md -->
 
 # Calendar Component
 
-Display and select dates with event support.
+Display and select dates with event support, date restrictions, and locale-aware formatting.
+
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -11,89 +21,15 @@ Display and select dates with event support.
 | `value` | `Date \| string` | `new Date()` | Selected date |
 | `view` | `'month' \| 'week' \| 'day'` | `'month'` | Calendar view |
 | `events` | `CalendarEvent[]` | `[]` | Calendar events |
-| `minDate` | `Date \| string` | `''` | Minimum selectable date |
-| `maxDate` | `Date \| string` | `''` | Maximum selectable date |
-| `disabledDates` | `(Date \| string)[]` | `[]` | Disabled dates |
-| `highlightToday` | `boolean` | `true` | Highlight today's date |
-| `showWeekNumbers` | `boolean` | `false` | Show week numbers |
-| `firstDayOfWeek` | `number` | `0` | First day of week (0=Sun, 1=Mon) |
+| `minDate` (attr: `min-date`) | `Date \| string` | `''` | Minimum selectable date |
+| `maxDate` (attr: `max-date`) | `Date \| string` | `''` | Maximum selectable date |
+| `disabledDates` (attr: `disabled-dates`) | `(Date \| string)[]` | `[]` | Disabled dates |
+| `highlightToday` (attr: `highlight-today`) | `boolean` | `true` | Highlight today's date |
+| `showWeekNumbers` (attr: `show-week-numbers`) | `boolean` | `false` | Show week numbers |
+| `firstDayOfWeek` (attr: `first-day-of-week`) | `number` | `0` | First day of week (0=Sun, 1=Mon) |
 | `locale` | `string` | `'en-US'` | Locale for formatting |
 
-## Methods
-
-### `goToToday(): void`
-Navigate to today's date.
-
-```javascript
-calendar.goToToday();
-```
-
-### `goToDate(date: Date | string): void`
-Navigate to specific date.
-
-```javascript
-calendar.goToDate(new Date(2024, 5, 15));
-```
-
-### `previousMonth(): void`
-Navigate to previous month.
-
-```javascript
-calendar.previousMonth();
-```
-
-### `nextMonth(): void`
-Navigate to next month.
-
-```javascript
-calendar.nextMonth();
-```
-
-### `previousWeek(): void`
-Navigate to previous week.
-
-```javascript
-calendar.previousWeek();
-```
-
-### `nextWeek(): void`
-Navigate to next week.
-
-```javascript
-calendar.nextWeek();
-```
-
-### `previousDay(): void`
-Navigate to previous day.
-
-```javascript
-calendar.previousDay();
-```
-
-### `nextDay(): void`
-Navigate to next day.
-
-```javascript
-calendar.nextDay();
-```
-
-### `getDisplayedMonth(): { month: number; year: number }`
-Get currently displayed month.
-
-```javascript
-const { month, year } = calendar.getDisplayedMonth();
-console.log(`Showing ${month + 1}/${year}`);
-```
-
-### `getEventsForDate(date: Date | string): CalendarEvent[]`
-Get events for specific date.
-
-```javascript
-const events = calendar.getEventsForDate(new Date());
-console.log(`Today has ${events.length} events`);
-```
-
-## CalendarEvent Interface
+### CalendarEvent Interface
 
 ```typescript
 interface CalendarEvent {
@@ -106,39 +42,37 @@ interface CalendarEvent {
 }
 ```
 
-## Events
-
-### `calendar-change`
-Dispatched when selected date changes.
-
-```javascript
-calendar.addEventListener('calendar-change', (e) => {
-  console.log('Selected:', e.detail.value);
-});
-```
-
-**Detail:** `{ value: Date, calendar: SniceCalendarElement }`
+## Methods
 
-### `calendar-event-click`
-Dispatched when event is clicked.
+| Method | Arguments | Returns | Description |
+|--------|-----------|---------|-------------|
+| `goToToday()` | -- | `void` | Navigate to today's date |
+| `goToDate()` | `date: Date \| string` | `void` | Navigate to specific date |
+| `previousMonth()` | -- | `void` | Navigate to previous month |
+| `nextMonth()` | -- | `void` | Navigate to next month |
+| `previousWeek()` | -- | `void` | Navigate to previous week |
+| `nextWeek()` | -- | `void` | Navigate to next week |
+| `previousDay()` | -- | `void` | Navigate to previous day |
+| `nextDay()` | -- | `void` | Navigate to next day |
+| `getDisplayedMonth()` | -- | `{ month: number; year: number }` | Get currently displayed month |
+| `getEventsForDate()` | `date: Date \| string` | `CalendarEvent[]` | Get events for specific date |
 
-```javascript
-calendar.addEventListener('calendar-event-click', (e) => {
-  console.log('Event clicked:', e.detail.event);
-});
-```
+## Events
 
-**Detail:** `{ event: CalendarEvent, calendar: SniceCalendarElement }`
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `calendar-change` | `{ value: Date, calendar: SniceCalendarElement }` | Fired when selected date changes |
+| `calendar-event-click` | `{ event: CalendarEvent, calendar: SniceCalendarElement }` | Fired when an event is clicked |
 
 ## CSS Parts
 
 Style internal elements from outside the shadow DOM using `::part()`.
 
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | The main calendar container |
-| `header` | `<div>` | The header with month title and navigation buttons |
-| `grid` | `<div>` | The day cells grid |
+| Part | Description |
+|------|-------------|
+| `base` | The main calendar container |
+| `header` | The header with month title and navigation buttons |
+| `grid` | The day cells grid |
 
 ```css
 snice-calendar::part(base) {
@@ -150,10 +84,6 @@ snice-calendar::part(header) {
   padding: 1rem;
   font-weight: 600;
 }
-
-snice-calendar::part(grid) {
-  gap: 2px;
-}
 ```
 
 ## Basic Usage
@@ -163,6 +93,8 @@ snice-calendar::part(grid) {
 ```
 
 ```typescript
+import 'snice/components/calendar/snice-calendar';
+
 calendar.addEventListener('calendar-change', (e) => {
   console.log('Selected date:', e.detail.value);
 });
@@ -170,42 +102,29 @@ calendar.addEventListener('calendar-change', (e) => {
 
 ## Examples
 
-### Basic Calendar
-
-```html
-<snice-calendar></snice-calendar>
-```
-
 ### With Events
 
+Use the `events` property to display events on the calendar.
+
 ```typescript
 calendar.events = [
-  {
-    id: 1,
-    title: 'Team Meeting',
-    start: new Date(2024, 5, 15, 10, 0),
-    color: '#2196f3'
-  },
-  {
-    id: 2,
-    title: 'Project Deadline',
-    start: new Date(2024, 5, 20),
-    color: '#f44336'
-  }
+  { id: 1, title: 'Team Meeting', start: new Date(2024, 5, 15, 10, 0), color: '#2196f3' },
+  { id: 2, title: 'Project Deadline', start: new Date(2024, 5, 20), color: '#f44336' }
 ];
 ```
 
-### With Date Restrictions
+### Date Restrictions
+
+Use `min-date` and `max-date` to constrain the selectable date range.
 
 ```html
-<snice-calendar
-  min-date="2024-01-01"
-  max-date="2024-12-31">
-</snice-calendar>
+<snice-calendar min-date="2024-01-01" max-date="2024-12-31"></snice-calendar>
 ```
 
 ### Disabled Dates
 
+Use the `disabledDates` property to prevent selection of specific dates.
+
 ```javascript
 calendar.disabledDates = [
   new Date(2024, 5, 10),
@@ -216,11 +135,15 @@ calendar.disabledDates = [
 
 ### Week Starting Monday
 
+Use `first-day-of-week` to change the starting day.
+
 ```html
 <snice-calendar first-day-of-week="1"></snice-calendar>
 ```
 
-### French Locale
+### Locale
+
+Use the `locale` attribute for locale-aware date formatting.
 
 ```html
 <snice-calendar locale="fr-FR"></snice-calendar>
@@ -228,34 +151,32 @@ calendar.disabledDates = [
 
 ### With Week Numbers
 
+Set `show-week-numbers` to display ISO week numbers.
+
 ```html
 <snice-calendar show-week-numbers></snice-calendar>
 ```
 
 ### Programmatic Navigation
 
+Use methods to control navigation from JavaScript.
+
 ```javascript
-// Go to today
 calendar.goToToday();
-
-// Go to specific date
 calendar.goToDate(new Date(2024, 11, 25));
-
-// Navigate months
 calendar.previousMonth();
 calendar.nextMonth();
 ```
 
 ### Event Handling
 
+Listen for date selection and event clicks.
+
 ```javascript
-// Date selection
 calendar.addEventListener('calendar-change', (e) => {
   console.log('Date selected:', e.detail.value);
-  updateBookingForm(e.detail.value);
 });
 
-// Event clicks
 calendar.addEventListener('calendar-event-click', (e) => {
   showEventDetails(e.detail.event);
 });
@@ -263,8 +184,9 @@ calendar.addEventListener('calendar-event-click', (e) => {
 
 ### Booking System
 
+Combine events, disabled dates, and event handling for a booking workflow.
+
 ```typescript
-// Load bookings
 const bookings = await fetchBookings();
 calendar.events = bookings.map(b => ({
   id: b.id,
@@ -273,11 +195,8 @@ calendar.events = bookings.map(b => ({
   color: b.confirmed ? '#4caf50' : '#ff9800'
 }));
 
-// Disable fully booked dates
-const fullyBooked = await getFullyBookedDates();
-calendar.disabledDates = fullyBooked;
+calendar.disabledDates = await getFullyBookedDates();
 
-// Handle new booking
 calendar.addEventListener('calendar-change', (e) => {
   if (hasAvailability(e.detail.value)) {
     showBookingForm(e.detail.value);
@@ -285,133 +204,30 @@ calendar.addEventListener('calendar-change', (e) => {
 });
 ```
 
-### Holiday Calendar
-
-```javascript
-calendar.events = [
-  { id: 1, title: 'New Year', start: '2024-01-01', color: '#f44336' },
-  { id: 2, title: 'Independence Day', start: '2024-07-04', color: '#2196f3' },
-  { id: 3, title: 'Thanksgiving', start: '2024-11-28', color: '#ff9800' },
-  { id: 4, title: 'Christmas', start: '2024-12-25', color: '#4caf50' }
-];
-```
-
-### Meeting Scheduler
-
-```typescript
-// Show team meetings
-calendar.events = teamMeetings.map(m => ({
-  id: m.id,
-  title: m.title,
-  start: m.startTime,
-  end: m.endTime,
-  color: m.recurring ? '#9c27b0' : '#2196f3',
-  data: m
-}));
-
-// Click to see meeting details
-calendar.addEventListener('calendar-event-click', (e) => {
-  const meeting = e.detail.event;
-  showModal({
-    title: meeting.title,
-    attendees: meeting.data.attendees,
-    location: meeting.data.location
-  });
-});
-```
-
-### Availability Checker
-
-```javascript
-// Mark unavailable dates
-calendar.disabledDates = unavailableDates;
-
-// Set date range
-const today = new Date();
-calendar.minDate = today;
-calendar.maxDate = new Date(today.getFullYear(), today.getMonth() + 3, 0);
-
-// Handle selection
-calendar.addEventListener('calendar-change', (e) => {
-  checkAvailability(e.detail.value).then(slots => {
-    if (slots.length > 0) {
-      showTimeSlots(slots);
-    } else {
-      alert('No availability on this date');
-    }
-  });
-});
-```
-
 ### Multi-Event Days
 
+Use `getEventsForDate()` to query events for a specific date.
+
 ```javascript
-// Multiple events per day
 calendar.events = [
   { id: 1, title: 'Morning Standup', start: '2024-06-15 09:00', color: '#2196f3' },
   { id: 2, title: 'Client Meeting', start: '2024-06-15 14:00', color: '#4caf50' },
   { id: 3, title: 'Team Sync', start: '2024-06-15 16:00', color: '#ff9800' }
 ];
 
-// Get all events for a date
-const date = new Date(2024, 5, 15);
-const dayEvents = calendar.getEventsForDate(date);
-console.log(`${dayEvents.length} events on ${date.toLocaleDateString()}`);
-```
-
-### Vacation Planner
-
-```javascript
-// Show approved vacations
-calendar.events = vacations.map(v => ({
-  id: v.id,
-  title: `${v.employee} - Vacation`,
-  start: v.startDate,
-  end: v.endDate,
-  color: '#9c27b0'
-}));
-
-// Block company holidays
-calendar.disabledDates = companyHolidays;
-
-// Request new vacation
-calendar.addEventListener('calendar-change', (e) => {
-  if (canRequestVacation(e.detail.value)) {
-    showVacationRequestForm(e.detail.value);
-  }
-});
+const dayEvents = calendar.getEventsForDate(new Date(2024, 5, 15));
+console.log(`${dayEvents.length} events on this date`);
 ```
 
-### Dynamic Event Updates
+## Keyboard Navigation
 
-```javascript
-// Add event
-function addEvent(event) {
-  calendar.events = [...calendar.events, event];
-}
-
-// Remove event
-function removeEvent(id) {
-  calendar.events = calendar.events.filter(e => e.id !== id);
-}
-
-// Update event
-function updateEvent(id, updates) {
-  calendar.events = calendar.events.map(e =>
-    e.id === id ? { ...e, ...updates } : e
-  );
-}
-```
+- Arrow keys to navigate between dates
+- Enter to select a date
+- Tab to move between controls
 
 ## Accessibility
 
-- Keyboard navigation (arrow keys)
+- Keyboard navigation with arrow keys
 - ARIA labels for dates and events
 - Screen reader friendly
 - Focus management
-
-## Browser Support
-
-- Modern browsers with Custom Elements v1 support
-- Date formatting via Intl API
-- Touch and mouse support

package/docs/components/camera-annotate.md

@@ -1,8 +1,8 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/camera-annotate.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/camera-annotate.md -->
 
 # Camera Annotate Component
 
-The camera annotate component combines camera capture with freehand drawing and labeled annotations. It provides a workflow for taking pictures, drawing shapes on them, and adding descriptive labels to each annotation.
+Combines camera capture with freehand drawing and labeled annotations. Provides a workflow for taking pictures, drawing shapes on them, and adding descriptive labels to each annotation.
 
 ## Table of Contents
 - [Properties](#properties)
@@ -11,46 +11,42 @@ The camera annotate component combines camera capture with freehand drawing and
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [Annotation Workflow](#annotation-workflow)
 - [Accessibility](#accessibility)
-- [Browser Support](#browser-support)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `mode` | `'camera' \| 'annotate'` | `'camera'` | Current mode of the component |
-| `auto-rotate-colors` | `boolean` | `true` | Automatically cycle through preset colors for each new annotation |
-| `show-labels-panel` | `boolean` | `true` | Show the sidebar panel with annotation labels |
+| `autoRotateColors` (attr: `auto-rotate-colors`) | `boolean` | `true` | Automatically cycle through preset colors for each new annotation |
+| `showLabelsPanel` (attr: `show-labels-panel`) | `boolean` | `true` | Show the sidebar panel with annotation labels |
 
 ## Methods
 
-| Method | Return Type | Description |
-|--------|-------------|-------------|
-| `capture()` | `Promise<void>` | Capture current camera frame and switch to annotate mode |
-| `exportImage(options?)` | `string` | Export annotated image as data URL. Options: `{ includeLabels?: boolean }` |
-| `exportAnnotations()` | `AnnotationData` | Export all annotation data as a serializable object |
-| `importAnnotations(data)` | `void` | Load annotation data from a previously exported object |
-| `clearAnnotations()` | `void` | Remove all annotations and strokes |
+| Method | Arguments | Returns | Description |
+|--------|-----------|---------|-------------|
+| `capture()` | -- | `Promise<void>` | Capture current camera frame and switch to annotate mode |
+| `exportImage()` | `options?: { includeLabels?: boolean }` | `string` | Export annotated image as data URL |
+| `exportAnnotations()` | -- | `AnnotationData` | Export all annotation data as a serializable object |
+| `importAnnotations()` | `data: AnnotationData` | `void` | Load annotation data from a previously exported object |
+| `clearAnnotations()` | -- | `void` | Remove all annotations and strokes |
 
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `capture` | `{ dataURL, width, height }` | Fired when an image is captured from the camera |
-| `annotate` | `{ annotation }` | Fired when a new annotation (shape) is drawn |
-| `annotation-change` | `{ annotations }` | Fired when annotations are modified (add, remove, visibility, label) |
+| `capture` | `{ dataURL: string, width: number, height: number }` | Fired when an image is captured from the camera |
+| `annotate` | `{ annotation: Annotation }` | Fired when a new annotation (shape) is drawn |
+| `annotation-change` | `{ annotations: Annotation[] }` | Fired when annotations are modified (add, remove, visibility, label) |
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Outer layout container |
-| `canvas` | `<div>` | Canvas area containing the video feed and drawing surface |
-| `toolbar` | `<div>` | Toolbar with capture/retake, undo, clear, and export buttons |
-| `sidebar` | `<div>` | Sidebar panel with color palette and annotation labels |
+| Part | Description |
+|------|-------------|
+| `base` | Outer layout container |
+| `canvas` | Canvas area containing the video feed and drawing surface |
+| `toolbar` | Toolbar with capture/retake, undo, clear, and export buttons |
+| `sidebar` | Sidebar panel with color palette and annotation labels |
 
 ```css
 snice-camera-annotate::part(base) {
@@ -76,26 +72,26 @@ import 'snice/components/camera-annotate/snice-camera-annotate';
 
 ## Examples
 
-### Default Camera Annotator
-
-```html
-<snice-camera-annotate></snice-camera-annotate>
-```
-
 ### Without Labels Panel
 
+Hide the sidebar by setting `show-labels-panel` to false.
+
 ```html
 <snice-camera-annotate show-labels-panel="false"></snice-camera-annotate>
 ```
 
 ### Manual Color Selection
 
+Disable auto-rotation to choose colors manually from the palette.
+
 ```html
 <snice-camera-annotate auto-rotate-colors="false"></snice-camera-annotate>
 ```
 
 ### Listening to Events
 
+Use events to track capture and annotation changes.
+
 ```html
 <snice-camera-annotate id="annotator"></snice-camera-annotate>
 
@@ -118,85 +114,37 @@ import 'snice/components/camera-annotate/snice-camera-annotate';
 
 ### Save and Load Annotations
 
-```html
-<snice-camera-annotate id="annotator"></snice-camera-annotate>
+Use `exportAnnotations()` and `importAnnotations()` to persist annotation data.
 
-<script type="module">
-  const annotator = document.getElementById('annotator');
+```javascript
+// Save
+const data = annotator.exportAnnotations();
+localStorage.setItem('annotations', JSON.stringify(data));
 
-  // Save
-  function saveAnnotations() {
-    const data = annotator.exportAnnotations();
-    localStorage.setItem('annotations', JSON.stringify(data));
-  }
-
-  // Load
-  function loadAnnotations() {
-    const json = localStorage.getItem('annotations');
-    if (json) {
-      annotator.importAnnotations(JSON.parse(json));
-    }
-  }
-</script>
+// Load
+const json = localStorage.getItem('annotations');
+if (json) {
+  annotator.importAnnotations(JSON.parse(json));
+}
 ```
 
 ### Export Image
 
-```html
-<snice-camera-annotate id="annotator"></snice-camera-annotate>
-<button onclick="downloadImage()">Download</button>
-
-<script type="module">
-  function downloadImage() {
-    const annotator = document.getElementById('annotator');
+Use `exportImage()` to download the annotated image with or without labels.
 
-    // Without labels on the image
-    const imageOnly = annotator.exportImage();
+```javascript
+const imageOnly = annotator.exportImage();
+const withLabels = annotator.exportImage({ includeLabels: true });
 
-    // With labels rendered on the image
-    const withLabels = annotator.exportImage({ includeLabels: true });
-
-    // Download
-    const a = document.createElement('a');
-    a.href = withLabels;
-    a.download = 'annotated.png';
-    a.click();
-  }
-</script>
+const a = document.createElement('a');
+a.href = withLabels;
+a.download = 'annotated.png';
+a.click();
 ```
 
-## Annotation Workflow
-
-1. **Camera Mode**: The component starts showing a live camera feed
-2. **Capture**: Click the "Capture" button to take a photo
-3. **Annotate Mode**: Draw shapes on the captured image using freehand strokes
-4. **Label**: Type labels for each annotation in the sidebar
-5. **Manage**: Show/hide individual annotations, toggle all, or delete specific ones
-6. **Export**: Save annotation data as JSON or export the annotated image
-7. **Retake**: Click "Retake" to return to camera mode and start fresh
-
-### Color System
-
-- **Preset Palette**: 12 preset colors displayed as swatches in the sidebar
-- **Auto Rotate**: When enabled (default), each new annotation automatically gets the next color from the palette
-- **Manual Selection**: Click any color swatch to set the active drawing color
-
-### Visual Highlighting
-
-When you hover over an annotation label in the sidebar:
-- The corresponding shape is highlighted at full opacity
-- All other shapes dim to 20% opacity with a grayscale filter
-- This makes it easy to identify which shape belongs to which label
-
 ## Accessibility
 
 - Color swatches have title attributes showing the hex value
 - Annotation visibility toggles have descriptive title text
 - Delete buttons have clear title labels
 - The sidebar scrolls independently when annotations exceed available space
-
-## Browser Support
-
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires camera access via `getUserMedia`
-- Requires Custom Elements v1 and Shadow DOM support