@aspect-ops/exon-ui 0.0.3 → 0.2.0

package/README.md

@@ -46,17 +46,24 @@ npm install @aspect-ops/exon-ui
 
 ### Form Components
 
-| Component       | Description                              |
-| --------------- | ---------------------------------------- |
-| `TextInput`     | Text input with validation states        |
-| `Textarea`      | Multi-line input with auto-resize        |
-| `Select`        | Dropdown select with keyboard navigation |
-| `Checkbox`      | Single checkbox with indeterminate state |
-| `CheckboxGroup` | Group of checkboxes with shared state    |
-| `Radio`         | Single radio button                      |
-| `RadioGroup`    | Radio button group with orientation      |
-| `Switch`        | Toggle switch component                  |
-| `FormField`     | Label wrapper with helper/error text     |
+| Component       | Description                                |
+| --------------- | ------------------------------------------ |
+| `TextInput`     | Text input with validation states          |
+| `Textarea`      | Multi-line input with auto-resize          |
+| `Select`        | Dropdown select with keyboard navigation   |
+| `Checkbox`      | Single checkbox with indeterminate state   |
+| `CheckboxGroup` | Group of checkboxes with shared state      |
+| `Radio`         | Single radio button                        |
+| `RadioGroup`    | Radio button group with orientation        |
+| `Switch`        | Toggle switch component                    |
+| `FormField`     | Label wrapper with helper/error text       |
+| `SearchInput`   | Search with autocomplete suggestions       |
+| `DatePicker`    | Date selection with calendar popup         |
+| `TimePicker`    | Time selection with hour/minute picker     |
+| `FileUpload`    | Drag-drop file upload with previews        |
+| `OTPInput`      | One-time password input                    |
+| `NumberInput`   | Number input with +/- buttons and keyboard |
+| `ToggleGroup`   | Single/multi select button group           |
 
 ### Navigation Components
 
@@ -68,6 +75,31 @@ npm install @aspect-ops/exon-ui
 | `BottomNav`, `BottomNavItem`                     | Mobile bottom navigation           |
 | `Navbar`, `NavItem`                              | Responsive header with mobile menu |
 | `Sidebar`, `SidebarItem`, `SidebarGroup`         | Collapsible sidebar navigation     |
+| `Stepper`, `StepperStep`                         | Multi-step progress indicator      |
+| `Pagination`                                     | Page navigation with ellipsis      |
+
+### Data Display Components
+
+| Component                    | Description                                  |
+| ---------------------------- | -------------------------------------------- |
+| `Accordion`, `AccordionItem` | Collapsible content panels                   |
+| `Slider`                     | Range slider with drag/keyboard support      |
+| `Carousel`, `CarouselSlide`  | Image/content carousel with swipe            |
+| `Image`                      | Lazy loading image with placeholder/fallback |
+| `Rating`                     | Star rating display/input                    |
+| `Chip`, `ChipGroup`          | Tag/filter chips with selection              |
+
+### Mobile Components
+
+| Component                                             | Description                                 |
+| ----------------------------------------------------- | ------------------------------------------- |
+| `ActionSheet`, `ActionSheetItem`                      | iOS/Android-style bottom action menu        |
+| `BottomSheet`, `BottomSheetHeader`, `BottomSheetBody` | Draggable bottom sheet with snap points     |
+| `FAB`                                                 | Floating action button with positions       |
+| `FABGroup`                                            | Speed dial FAB with expandable actions      |
+| `PullToRefresh`                                       | Pull-to-refresh gesture for lists           |
+| `SwipeActions`                                        | Swipe-to-reveal actions on list items       |
+| `SafeArea`                                            | Safe area inset wrapper for notched devices |
 
 ## Usage Examples
 
@@ -320,73 +352,901 @@ npm install @aspect-ops/exon-ui
 </Sidebar>
 ```
 
-## Theming
+## Advanced Form Components
 
-### CSS Custom Properties
+### SearchInput
 
-Import the default styles and customize with CSS variables:
+Search input with autocomplete suggestions and keyboard navigation.
+
+**Props:**
+
+| Prop             | Type        | Default    | Description                       |
+| ---------------- | ----------- | ---------- | --------------------------------- |
+| `value`          | `string`    | `''`       | Bindable search value             |
+| `placeholder`    | `string`    | `'Search'` | Input placeholder text            |
+| `suggestions`    | `string[]`  | `[]`       | Array of autocomplete suggestions |
+| `size`           | `InputSize` | `'md'`     | Input size: sm, md, lg            |
+| `disabled`       | `boolean`   | `false`    | Disabled state                    |
+| `loading`        | `boolean`   | `false`    | Show loading spinner              |
+| `maxSuggestions` | `number`    | `5`        | Maximum suggestions to display    |
+| `onselect`       | `function`  | -          | Callback when suggestion selected |
+
+**Usage:**
 
 ```svelte
 <script>
-	import '@aspect-ops/exon-ui/styles';
+	import { SearchInput } from '@aspect-ops/exon-ui';
+
+	let query = $state('');
+	const suggestions = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];
 </script>
 
-<style>
-	:root {
-		/* Colors */
-		--color-primary: #3b82f6;
-		--color-primary-hover: #2563eb;
-		--color-bg: #ffffff;
-		--color-bg-muted: #f9fafb;
-		--color-text: #1f2937;
-		--color-border: #e5e7eb;
-
-		/* Spacing */
-		--space-xs: 0.25rem;
-		--space-sm: 0.5rem;
-		--space-md: 1rem;
-		--space-lg: 1.5rem;
-		--space-xl: 2rem;
-
-		/* Border Radius */
-		--radius-sm: 0.25rem;
-		--radius-md: 0.5rem;
-		--radius-lg: 0.75rem;
-
-		/* Transitions */
-		--transition-fast: 150ms ease;
-		--transition-base: 200ms ease;
+<SearchInput bind:value={query} {suggestions} onselect={(val) => console.log('Selected:', val)} />
+```
+
+### DatePicker
+
+Date selection with calendar popup and keyboard navigation.
+
+**Props:**
+
+| Prop          | Type        | Default         | Description             |
+| ------------- | ----------- | --------------- | ----------------------- |
+| `value`       | `Date`      | `null`          | Bindable selected date  |
+| `placeholder` | `string`    | `'Select date'` | Input placeholder       |
+| `min`         | `Date`      | `null`          | Minimum selectable date |
+| `max`         | `Date`      | `null`          | Maximum selectable date |
+| `disabled`    | `boolean`   | `false`         | Disabled state          |
+| `size`        | `InputSize` | `'md'`          | Input size: sm, md, lg  |
+| `format`      | `string`    | `'yyyy-MM-dd'`  | Date format string      |
+
+**Usage:**
+
+```svelte
+<script>
+	import { DatePicker } from '@aspect-ops/exon-ui';
+
+	let selectedDate = $state(null);
+</script>
+
+<DatePicker bind:value={selectedDate} placeholder="Choose a date" />
+```
+
+### TimePicker
+
+Time selection with scrollable hour/minute/period picker.
+
+**Props:**
+
+| Prop         | Type             | Default | Description                 |
+| ------------ | ---------------- | ------- | --------------------------- |
+| `value`      | `string`         | `''`    | Bindable time value (HH:mm) |
+| `format`     | `'12h' \| '24h'` | `'24h'` | Time format                 |
+| `minuteStep` | `number`         | `1`     | Minute increment step       |
+| `min`        | `string`         | -       | Minimum selectable time     |
+| `max`        | `string`         | -       | Maximum selectable time     |
+| `disabled`   | `boolean`        | `false` | Disabled state              |
+| `size`       | `InputSize`      | `'md'`  | Input size: sm, md, lg      |
+
+**Usage:**
+
+```svelte
+<script>
+	import { TimePicker } from '@aspect-ops/exon-ui';
+
+	let time = $state('');
+</script>
+
+<TimePicker bind:value={time} format="12h" minuteStep={15} />
+```
+
+### FileUpload
+
+Drag-and-drop file upload with image previews and validation.
+
+**Props:**
+
+| Prop          | Type      | Default | Description                      |
+| ------------- | --------- | ------- | -------------------------------- |
+| `files`       | `File[]`  | `[]`    | Bindable array of uploaded files |
+| `accept`      | `string`  | `''`    | Accepted file types              |
+| `multiple`    | `boolean` | `false` | Allow multiple file selection    |
+| `maxSize`     | `number`  | `10MB`  | Maximum file size in bytes       |
+| `maxFiles`    | `number`  | `10`    | Maximum number of files          |
+| `showPreview` | `boolean` | `true`  | Show image previews              |
+
+**Usage:**
+
+```svelte
+<script>
+	import { FileUpload } from '@aspect-ops/exon-ui';
+
+	let files = $state([]);
+</script>
+
+<FileUpload bind:files multiple accept="image/*" maxSize={5242880} />
+```
+
+### OTPInput
+
+One-time password input with auto-focus and paste support.
+
+**Props:**
+
+| Prop         | Type                          | Default     | Description                      |
+| ------------ | ----------------------------- | ----------- | -------------------------------- |
+| `value`      | `string`                      | `''`        | Bindable OTP value               |
+| `length`     | `number`                      | `6`         | Number of OTP digits             |
+| `type`       | `'numeric' \| 'alphanumeric'` | `'numeric'` | Input validation type            |
+| `masked`     | `boolean`                     | `false`     | Show dots instead of characters  |
+| `disabled`   | `boolean`                     | `false`     | Disabled state                   |
+| `size`       | `Size`                        | `'md'`      | Input size: sm, md, lg           |
+| `oncomplete` | `function`                    | -           | Callback when all digits entered |
+
+**Usage:**
+
+```svelte
+<script>
+	import { OTPInput } from '@aspect-ops/exon-ui';
+
+	let otp = $state('');
+</script>
+
+<OTPInput bind:value={otp} length={6} oncomplete={(code) => console.log('OTP:', code)} />
+```
+
+### NumberInput
+
+Number input with increment/decrement buttons and keyboard support.
+
+**Props:**
+
+| Prop            | Type                      | Default | Description                 |
+| --------------- | ------------------------- | ------- | --------------------------- |
+| `value`         | `number \| null`          | `null`  | Bindable number value       |
+| `min`           | `number`                  | -       | Minimum allowed value       |
+| `max`           | `number`                  | -       | Maximum allowed value       |
+| `step`          | `number`                  | `1`     | Increment/decrement step    |
+| `disabled`      | `boolean`                 | `false` | Disabled state              |
+| `placeholder`   | `string`                  | -       | Input placeholder           |
+| `error`         | `boolean`                 | `false` | Error state styling         |
+| `onValueChange` | `(value: number) => void` | -       | Callback when value changes |
+
+**Usage:**
+
+```svelte
+<script>
+	import { NumberInput } from '@aspect-ops/exon-ui';
+
+	let quantity = $state(1);
+</script>
+
+<NumberInput bind:value={quantity} min={1} max={99} step={1} />
+
+<!-- With error state -->
+<NumberInput bind:value={quantity} min={0} max={10} error={quantity > 10} />
+```
+
+### ToggleGroup
+
+Button group for single or multiple selection.
+
+**Props (ToggleGroup):**
+
+| Prop            | Type                         | Default        | Description                 |
+| --------------- | ---------------------------- | -------------- | --------------------------- |
+| `type`          | `'single' \| 'multiple'`     | `'single'`     | Selection mode              |
+| `value`         | `string \| string[]`         | `'' \| []`     | Bindable selected value(s)  |
+| `onValueChange` | `(value) => void`            | -              | Callback when value changes |
+| `disabled`      | `boolean`                    | `false`        | Disabled state              |
+| `orientation`   | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction            |
+
+**Props (ToggleGroupItem):**
+
+| Prop       | Type      | Default | Description           |
+| ---------- | --------- | ------- | --------------------- |
+| `value`    | `string`  | -       | Item value (required) |
+| `disabled` | `boolean` | `false` | Disabled state        |
+
+**Usage:**
+
+```svelte
+<script>
+	import { ToggleGroup, ToggleGroupItem } from '@aspect-ops/exon-ui';
+
+	let alignment = $state('left');
+	let formats = $state([]);
+</script>
+
+<!-- Single selection (radio-like) -->
+<ToggleGroup bind:value={alignment} type="single">
+	{#snippet children()}
+		<ToggleGroupItem value="left">Left</ToggleGroupItem>
+		<ToggleGroupItem value="center">Center</ToggleGroupItem>
+		<ToggleGroupItem value="right">Right</ToggleGroupItem>
+	{/snippet}
+</ToggleGroup>
+
+<!-- Multiple selection (checkbox-like) -->
+<ToggleGroup bind:value={formats} type="multiple">
+	{#snippet children()}
+		<ToggleGroupItem value="bold">B</ToggleGroupItem>
+		<ToggleGroupItem value="italic">I</ToggleGroupItem>
+		<ToggleGroupItem value="underline">U</ToggleGroupItem>
+	{/snippet}
+</ToggleGroup>
+```
+
+### Pagination
+
+Page navigation with ellipsis for large page ranges.
+
+**Props:**
+
+| Prop           | Type                     | Default | Description                       |
+| -------------- | ------------------------ | ------- | --------------------------------- |
+| `currentPage`  | `number`                 | -       | Current page number (required)    |
+| `totalPages`   | `number`                 | -       | Total number of pages (required)  |
+| `siblingCount` | `number`                 | `1`     | Pages to show around current page |
+| `onPageChange` | `(page: number) => void` | -       | Callback when page changes        |
+
+**Usage:**
+
+```svelte
+<script>
+	import { Pagination } from '@aspect-ops/exon-ui';
+
+	let currentPage = $state(1);
+	const totalPages = 20;
+</script>
+
+<Pagination {currentPage} {totalPages} onPageChange={(page) => (currentPage = page)} />
+
+<!-- With more visible siblings -->
+<Pagination
+	{currentPage}
+	{totalPages}
+	siblingCount={2}
+	onPageChange={(page) => (currentPage = page)}
+/>
+```
+
+**Keyboard Navigation:**
+
+- `←` / `→`: Previous / Next page
+- `Home`: First page
+- `End`: Last page
+
+## Data Display Components
+
+### Accordion
+
+Collapsible content panels with single or multiple expansion.
+
+**Props:**
+
+| Prop       | Type                 | Default | Description                     |
+| ---------- | -------------------- | ------- | ------------------------------- |
+| `value`    | `string \| string[]` | `[]`    | Bindable expanded item value(s) |
+| `multiple` | `boolean`            | `false` | Allow multiple panels open      |
+| `disabled` | `boolean`            | `false` | Disabled state                  |
+
+**Usage:**
+
+```svelte
+<script>
+	import { Accordion, AccordionItem } from '@aspect-ops/exon-ui';
+
+	let expanded = $state([]);
+</script>
+
+<Accordion bind:value={expanded} multiple>
+	{#snippet children()}
+		<AccordionItem value="item1" title="Section 1">Content for section 1</AccordionItem>
+		<AccordionItem value="item2" title="Section 2">Content for section 2</AccordionItem>
+	{/snippet}
+</Accordion>
+```
+
+### Slider
+
+Range slider with drag, keyboard support, and optional value display.
+
+**Props:**
+
+| Prop        | Type      | Default | Description           |
+| ----------- | --------- | ------- | --------------------- |
+| `value`     | `number`  | `0`     | Bindable slider value |
+| `min`       | `number`  | `0`     | Minimum value         |
+| `max`       | `number`  | `100`   | Maximum value         |
+| `step`      | `number`  | `1`     | Value increment step  |
+| `disabled`  | `boolean` | `false` | Disabled state        |
+| `showValue` | `boolean` | `false` | Show value tooltip    |
+| `showTicks` | `boolean` | `false` | Show tick marks       |
+
+**Usage:**
+
+```svelte
+<script>
+	import { Slider } from '@aspect-ops/exon-ui';
+
+	let volume = $state(50);
+</script>
+
+<Slider bind:value={volume} min={0} max={100} showValue />
+```
+
+### Carousel
+
+Image/content carousel with swipe gestures and autoplay.
+
+**Props:**
+
+| Prop               | Type      | Default | Description                 |
+| ------------------ | --------- | ------- | --------------------------- |
+| `activeIndex`      | `number`  | `0`     | Bindable active slide index |
+| `autoplay`         | `boolean` | `false` | Enable autoplay             |
+| `autoplayInterval` | `number`  | `5000`  | Autoplay interval (ms)      |
+| `loop`             | `boolean` | `true`  | Loop slides                 |
+| `showIndicators`   | `boolean` | `true`  | Show dot indicators         |
+| `showArrows`       | `boolean` | `true`  | Show navigation arrows      |
+
+**Usage:**
+
+```svelte
+<script>
+	import { Carousel, CarouselSlide } from '@aspect-ops/exon-ui';
+
+	let activeSlide = $state(0);
+</script>
+
+<Carousel bind:activeIndex={activeSlide} autoplay loop>
+	{#snippet children()}
+		<CarouselSlide><img src="slide1.jpg" alt="Slide 1" /></CarouselSlide>
+		<CarouselSlide><img src="slide2.jpg" alt="Slide 2" /></CarouselSlide>
+		<CarouselSlide><img src="slide3.jpg" alt="Slide 3" /></CarouselSlide>
+	{/snippet}
+</Carousel>
+```
+
+### Image
+
+Lazy-loading image with placeholder and fallback support.
+
+**Props:**
+
+| Prop          | Type                | Default   | Description                     |
+| ------------- | ------------------- | --------- | ------------------------------- |
+| `src`         | `string`            | -         | Image source URL (required)     |
+| `alt`         | `string`            | -         | Alt text (required)             |
+| `loading`     | `'lazy' \| 'eager'` | `'lazy'`  | Loading strategy                |
+| `objectFit`   | `string`            | `'cover'` | CSS object-fit value            |
+| `placeholder` | `string`            | -         | Placeholder image or color      |
+| `fallback`    | `string`            | -         | Fallback image on error         |
+| `rounded`     | `boolean \| string` | `false`   | Border radius: sm, md, lg, full |
+| `aspectRatio` | `string`            | -         | CSS aspect ratio                |
+
+**Usage:**
+
+```svelte
+<script>
+	import { Image } from '@aspect-ops/exon-ui';
+</script>
+
+<Image
+	src="profile.jpg"
+	alt="User profile"
+	rounded="full"
+	aspectRatio="1/1"
+	placeholder="#e5e7eb"
+	fallback="default-avatar.png"
+/>
+```
+
+### Rating
+
+Star rating display and input with half-star support.
+
+**Props:**
+
+| Prop        | Type      | Default | Description             |
+| ----------- | --------- | ------- | ----------------------- |
+| `value`     | `number`  | `0`     | Bindable rating value   |
+| `max`       | `number`  | `5`     | Maximum rating          |
+| `allowHalf` | `boolean` | `false` | Allow half-star ratings |
+| `readonly`  | `boolean` | `false` | Read-only display mode  |
+| `disabled`  | `boolean` | `false` | Disabled state          |
+| `size`      | `Size`    | `'md'`  | Star size: sm, md, lg   |
+| `showValue` | `boolean` | `false` | Show numeric value      |
+
+**Usage:**
+
+```svelte
+<script>
+	import { Rating } from '@aspect-ops/exon-ui';
+
+	let rating = $state(4.5);
+</script>
+
+<Rating bind:value={rating} allowHalf showValue />
+```
+
+## Navigation & Feedback Components
+
+### Stepper
+
+Multi-step progress indicator with linear or non-linear navigation.
+
+**Props:**
+
+| Prop          | Type                         | Default        | Description                   |
+| ------------- | ---------------------------- | -------------- | ----------------------------- |
+| `activeStep`  | `number`                     | `0`            | Bindable active step index    |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout orientation            |
+| `linear`      | `boolean`                    | `true`         | Enforce sequential navigation |
+
+**Usage:**
+
+```svelte
+<script>
+	import { Stepper, StepperStep } from '@aspect-ops/exon-ui';
+
+	let currentStep = $state(0);
+</script>
+
+<Stepper bind:activeStep={currentStep}>
+	{#snippet children()}
+		<StepperStep label="Personal Info" description="Enter your details" />
+		<StepperStep label="Address" description="Shipping information" />
+		<StepperStep label="Review" description="Confirm your order" />
+	{/snippet}
+</Stepper>
+```
+
+### Chip
+
+Compact tag/filter chips with selection and removal.
+
+**Props:**
+
+| Prop        | Type          | Default     | Description                                      |
+| ----------- | ------------- | ----------- | ------------------------------------------------ |
+| `variant`   | `ChipVariant` | `'filled'`  | Chip style: filled, outlined, soft               |
+| `color`     | `ChipColor`   | `'default'` | Color: default, primary, success, warning, error |
+| `size`      | `ChipSize`    | `'md'`      | Size: sm, md, lg                                 |
+| `removable` | `boolean`     | `false`     | Show remove button                               |
+| `selected`  | `boolean`     | `false`     | Selected state                                   |
+| `disabled`  | `boolean`     | `false`     | Disabled state                                   |
+
+**Usage:**
+
+```svelte
+<script>
+	import { Chip, ChipGroup } from '@aspect-ops/exon-ui';
+
+	let selected = $state(['tag1']);
+</script>
+
+<ChipGroup>
+	<Chip onclick={() => console.log('clicked')}>JavaScript</Chip>
+	<Chip color="primary" removable onremove={() => console.log('removed')}>Svelte</Chip>
+	<Chip variant="outlined" color="success">TypeScript</Chip>
+</ChipGroup>
+```
+
+## Mobile Components
+
+Components optimized for Capacitor mobile apps with gesture support, haptic feedback, and safe area handling.
+
+| Component       | Description                                 |
+| --------------- | ------------------------------------------- |
+| `ActionSheet`   | iOS/Android-style bottom action menu        |
+| `BottomSheet`   | Draggable bottom sheet with snap points     |
+| `FAB`           | Floating action button with positions       |
+| `FABGroup`      | Speed dial FAB with expandable actions      |
+| `PullToRefresh` | Pull-to-refresh gesture for lists           |
+| `SwipeActions`  | Swipe-to-reveal actions on list items       |
+| `SafeArea`      | Safe area inset wrapper for notched devices |
+
+### ActionSheet
+
+```svelte
+<script>
+	import { ActionSheet, ActionSheetItem, Button } from '@aspect-ops/exon-ui';
+
+	let open = $state(false);
+</script>
+
+<Button onclick={() => (open = true)}>Show Actions</Button>
+
+<ActionSheet bind:open title="Choose an action" description="Select what you want to do">
+	{#snippet actions()}
+		<ActionSheetItem onclick={() => console.log('Edit')}>Edit</ActionSheetItem>
+		<ActionSheetItem onclick={() => console.log('Share')}>Share</ActionSheetItem>
+		<ActionSheetItem destructive onclick={() => console.log('Delete')}>Delete</ActionSheetItem>
+	{/snippet}
+</ActionSheet>
+```
+
+**Props:**
+
+- `open` - Bindable open state
+- `title` - Optional header title
+- `description` - Optional header description
+- `cancelLabel` - Cancel button text (default: "Cancel")
+- `showCancel` - Show cancel button (default: true)
+- `closeOnSelect` - Close when action selected (default: true)
+
+### BottomSheet
+
+```svelte
+<script>
+	import { BottomSheet, BottomSheetHeader, BottomSheetBody, Button } from '@aspect-ops/exon-ui';
+
+	let open = $state(false);
+</script>
+
+<Button onclick={() => (open = true)}>Open Sheet</Button>
+
+<BottomSheet bind:open snapPoints={['half', 'full']} defaultSnapPoint="half">
+	<BottomSheetHeader>
+		<h3>Sheet Title</h3>
+	</BottomSheetHeader>
+	<BottomSheetBody>
+		<p>Drag the handle to resize or swipe down to close.</p>
+	</BottomSheetBody>
+</BottomSheet>
+```
+
+**Props:**
+
+- `open` - Bindable open state
+- `snapPoints` - Array of snap points: `'min'` | `'half'` | `'full'` | number (px)
+- `defaultSnapPoint` - Initial snap point (default: 'half')
+- `showHandle` - Show drag handle (default: true)
+- `closeOnBackdrop` - Close on backdrop click (default: true)
+- `closeOnEscape` - Close on Escape key (default: true)
+
+### FAB (Floating Action Button)
+
+```svelte
+<script>
+	import { FAB } from '@aspect-ops/exon-ui';
+</script>
+
+<!-- Basic FAB -->
+<FAB onclick={() => console.log('clicked')}>+</FAB>
+
+<!-- Positioned FAB -->
+<FAB position="bottom-left" size="lg">📝</FAB>
+
+<!-- Extended FAB with label -->
+<FAB extended position="bottom-right">
+	{#snippet children()}➕{/snippet}
+	{#snippet label()}Add Item{/snippet}
+</FAB>
+```
+
+**Props:**
+
+- `size` - `'sm'` | `'md'` | `'lg'` (44px, 56px, 72px)
+- `position` - `'bottom-right'` | `'bottom-left'` | `'bottom-center'` | `'top-right'` | `'top-left'`
+- `extended` - Extended FAB with label
+- `disabled` - Disable the button
+
+### FABGroup (Speed Dial)
+
+```svelte
+<script>
+	import { FABGroup } from '@aspect-ops/exon-ui';
+
+	const actions = [
+		{ icon: '📷', label: 'Camera', onAction: () => console.log('Camera') },
+		{ icon: '🖼️', label: 'Gallery', onAction: () => console.log('Gallery') },
+		{ icon: '📎', label: 'Attach', onAction: () => console.log('Attach') }
+	];
+</script>
+
+<FABGroup {actions} icon="+" closeIcon="×" position="bottom-right" direction="up" />
+```
+
+**Props:**
+
+- `actions` - Array of `{ icon, label, onAction }` objects
+- `icon` - Main FAB icon (default: '+')
+- `closeIcon` - Icon when open (default: '×')
+- `position` - Same as FAB positions
+- `direction` - `'up'` | `'down'` | `'left'` | `'right'`
+
+### PullToRefresh
+
+```svelte
+<script>
+	import { PullToRefresh } from '@aspect-ops/exon-ui';
+
+	let refreshing = $state(false);
+
+	async function handleRefresh() {
+		// Fetch new data
+		await new Promise((r) => setTimeout(r, 2000));
+		refreshing = false;
 	}
-</style>
+</script>
+
+<PullToRefresh bind:refreshing onrefresh={handleRefresh}>
+	<div class="content">
+		<p>Pull down to refresh...</p>
+		<!-- Your scrollable content -->
+	</div>
+</PullToRefresh>
+```
+
+**Props:**
+
+- `refreshing` - Bindable loading state
+- `threshold` - Pull distance to trigger (default: 80px)
+- `maxPull` - Maximum pull distance (default: 150px)
+- `disabled` - Disable pull-to-refresh
+- `onrefresh` - Callback when threshold reached
+
+### SwipeActions
+
+```svelte
+<script>
+	import { SwipeActions } from '@aspect-ops/exon-ui';
+
+	const leftActions = [
+		{ icon: '📌', label: 'Pin', color: '#3b82f6', onAction: () => console.log('Pin') }
+	];
+
+	const rightActions = [
+		{ icon: '🗑️', label: 'Delete', color: '#ef4444', onAction: () => console.log('Delete') }
+	];
+</script>
+
+<SwipeActions {leftActions} {rightActions}>
+	<div class="list-item">
+		<p>Swipe me left or right</p>
+	</div>
+</SwipeActions>
+```
+
+**Props:**
+
+- `leftActions` - Actions revealed on swipe right
+- `rightActions` - Actions revealed on swipe left
+- `threshold` - Swipe distance to reveal (default: 60px)
+- `disabled` - Disable swipe gestures
+
+**Action object:**
+
+- `icon` - Icon string or emoji
+- `label` - Action label text
+- `color` - Background color
+- `onAction` - Callback when tapped
+
+### SafeArea
+
+```svelte
+<script>
+	import { SafeArea } from '@aspect-ops/exon-ui';
+</script>
+
+<!-- All edges (default) -->
+<SafeArea>
+	<main>Content with safe area padding on all sides</main>
+</SafeArea>
+
+<!-- Specific edges -->
+<SafeArea edges={['top', 'bottom']}>
+	<main>Only top and bottom safe area</main>
+</SafeArea>
+```
+
+**Props:**
+
+- `edges` - Array of edges: `'top'` | `'right'` | `'bottom'` | `'left'` (default: all)
+
+## Theming & Customization
+
+### Quick Setup
+
+```svelte
+<script>
+	// In your root layout (+layout.svelte)
+	import '@aspect-ops/exon-ui/styles';
+</script>
+```
+
+### Custom Brand Colors
+
+Override CSS variables in your app's global styles:
+
+```css
+/* src/app.css or global styles */
+:root {
+	/* Primary brand color */
+	--color-primary: #8b5cf6; /* Purple */
+	--color-primary-hover: #7c3aed;
+	--color-primary-active: #6d28d9;
+	--color-primary-bg: #ede9fe;
+
+	/* Secondary */
+	--color-secondary: #64748b;
+	--color-secondary-hover: #475569;
+
+	/* Destructive/Error */
+	--color-destructive: #dc2626;
+	--color-error: #dc2626;
+
+	/* Success */
+	--color-success: #16a34a;
+
+	/* Warning */
+	--color-warning: #d97706;
+}
+```
+
+### Full Design Token Reference
+
+```css
+:root {
+	/* ===== COLORS ===== */
+
+	/* Backgrounds */
+	--color-bg: #fcfcfc; /* Main background */
+	--color-bg-muted: #f9f9f9; /* Subtle background */
+	--color-bg-subtle: #f0f0f0; /* More contrast */
+	--color-bg-hover: #e8e8e8; /* Hover state */
+	--color-bg-active: #e0e0e0; /* Active/pressed */
+	--color-bg-elevated: #ffffff; /* Cards, modals */
+	--color-bg-card: #ffffff; /* Card backgrounds */
+
+	/* Text */
+	--color-text: #202020; /* Primary text */
+	--color-text-muted: #646464; /* Secondary text */
+	--color-text-subtle: #838383; /* Tertiary text */
+	--color-text-inverse: #ffffff; /* Text on dark backgrounds */
+
+	/* Borders */
+	--color-border: #d9d9d9;
+	--color-border-hover: #cecece;
+	--color-border-active: #bbbbbb;
+
+	/* ===== TYPOGRAPHY ===== */
+
+	--font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+	--font-family-mono: ui-monospace, 'SF Mono', Menlo, Monaco, monospace;
+
+	/* Fluid type scale (responsive) */
+	--text-xs: clamp(0.69rem, 0.66rem + 0.14vw, 0.78rem); /* ~11-12px */
+	--text-sm: clamp(0.83rem, 0.79rem + 0.21vw, 0.97rem); /* ~13-16px */
+	--text-base: clamp(1rem, 0.93rem + 0.33vw, 1.125rem); /* 16-18px */
+	--text-lg: clamp(1.13rem, 1.03rem + 0.47vw, 1.41rem); /* ~18-23px */
+	--text-xl: clamp(1.27rem, 1.14rem + 0.65vw, 1.76rem); /* ~20-28px */
+	--text-2xl: clamp(1.42rem, 1.25rem + 0.89vw, 2.2rem); /* ~23-35px */
+	--text-3xl: clamp(1.6rem, 1.37rem + 1.19vw, 2.75rem); /* ~26-44px */
+	--text-4xl: clamp(1.8rem, 1.49rem + 1.57vw, 3.43rem); /* ~29-55px */
+
+	/* Font weights */
+	--font-normal: 400;
+	--font-medium: 500;
+	--font-semibold: 600;
+	--font-bold: 700;
+
+	/* ===== SPACING ===== */
+
+	--space-xs: clamp(0.25rem, 0.23rem + 0.11vw, 0.31rem); /* 4-5px */
+	--space-sm: clamp(0.5rem, 0.46rem + 0.22vw, 0.63rem); /* 8-10px */
+	--space-md: clamp(1rem, 0.93rem + 0.33vw, 1.125rem); /* 16-18px */
+	--space-lg: clamp(1.5rem, 1.39rem + 0.54vw, 1.75rem); /* 24-28px */
+	--space-xl: clamp(2rem, 1.85rem + 0.76vw, 2.5rem); /* 32-40px */
+	--space-2xl: clamp(3rem, 2.78rem + 1.09vw, 3.75rem); /* 48-60px */
+
+	/* ===== BORDER RADIUS ===== */
+
+	--radius-sm: 0.25rem; /* 4px */
+	--radius-md: 0.375rem; /* 6px */
+	--radius-lg: 0.5rem; /* 8px */
+	--radius-xl: 0.75rem; /* 12px */
+	--radius-2xl: 1rem; /* 16px */
+	--radius-full: 9999px; /* Pill/circle */
+
+	/* ===== SHADOWS ===== */
+
+	--shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.1);
+	--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+	--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+	--shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1);
+
+	/* ===== TRANSITIONS ===== */
+
+	--transition-fast: 150ms ease;
+	--transition-base: 200ms ease;
+	--transition-slow: 300ms ease;
+
+	/* ===== MOBILE ===== */
+
+	--touch-target-min: 44px;
+	--safe-area-top: env(safe-area-inset-top, 0px);
+	--safe-area-bottom: env(safe-area-inset-bottom, 0px);
+}
 ```
 
 ### Dark Mode
 
-Toggle dark mode by setting `data-theme="dark"` on the html element:
+The library supports dark mode via `data-theme` attribute or system preference:
 
 ```svelte
 <script>
+	let isDark = $state(false);
+
 	function toggleTheme() {
-		const isDark = document.documentElement.getAttribute('data-theme') === 'dark';
-		document.documentElement.setAttribute('data-theme', isDark ? 'light' : 'dark');
+		isDark = !isDark;
+		document.documentElement.setAttribute('data-theme', isDark ? 'dark' : 'light');
 	}
+
+	// Respect system preference on load
+	import { onMount } from 'svelte';
+	onMount(() => {
+		if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
+			isDark = true;
+			document.documentElement.setAttribute('data-theme', 'dark');
+		}
+	});
 </script>
 
-<button onclick={toggleTheme}>Toggle Theme</button>
+<Switch bind:checked={isDark} onchange={toggleTheme}>
+	{#snippet children()}Dark Mode{/snippet}
+</Switch>
 ```
 
-Dark theme variables are automatically applied:
+Dark theme automatically adjusts all colors:
 
 ```css
 [data-theme='dark'] {
-	--color-bg: #111827;
-	--color-bg-muted: #1f2937;
-	--color-bg-elevated: #1f2937;
-	--color-text: #f9fafb;
-	--color-border: #374151;
+	--color-bg: #111111;
+	--color-bg-muted: #191919;
+	--color-bg-elevated: #222222;
+	--color-text: #eeeeee;
+	--color-text-muted: #b4b4b4;
+	--color-border: #3a3a3a;
+	/* All other colors auto-adapt */
 }
 ```
 
+### Component-Level Customization
+
+Override styles for specific components using CSS classes:
+
+```svelte
+<Button class="my-custom-button" variant="primary">Custom Button</Button>
+
+<style>
+	:global(.my-custom-button) {
+		--color-primary: #10b981;
+		border-radius: var(--radius-full);
+		text-transform: uppercase;
+	}
+</style>
+```
+
+### Platform-Specific Styling
+
+Components adapt to iOS/Android automatically. Set platform manually:
+
+```svelte
+<script>
+	import { onMount } from 'svelte';
+
+	onMount(() => {
+		// Auto-detect or set manually
+		const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
+		document.documentElement.setAttribute('data-platform', isIOS ? 'ios' : 'android');
+	});
+</script>
+```
+
 ## Mobile / Capacitor Support
 
 Components are designed with mobile-first principles:
@@ -395,12 +1255,27 @@ Components are designed with mobile-first principles:
 - **Safe area inset handling** for notched devices (iPhone, Android gesture bar)
 - **Responsive breakpoints** for adaptive layouts
 - **Hardware-accelerated animations** for smooth 60fps performance
+- **Haptic feedback** integration (requires Capacitor Haptics plugin)
+- **Platform-adaptive styling** for iOS and Android
+
+### Capacitor Integration
 
-### Safe Area Example
+```bash
+# Install Capacitor plugins for full mobile support
+npm install @capacitor/haptics @capacitor/status-bar
+```
 
 ```svelte
-<BottomNav {items} />
-<!-- Automatically includes padding-bottom: env(safe-area-inset-bottom) -->
+<script>
+	import { SafeArea, BottomNav, PullToRefresh } from '@aspect-ops/exon-ui';
+</script>
+
+<SafeArea edges={['top', 'bottom']}>
+	<PullToRefresh onrefresh={handleRefresh}>
+		<main>Your content here</main>
+	</PullToRefresh>
+	<BottomNav {items} />
+</SafeArea>
 ```
 
 ## TypeScript