@marianmeres/stuic 2.5.0 → 2.6.0

package/dist/components/Button/README.md

@@ -0,0 +1,83 @@
+# Button
+
+A flexible button component with style variants, sizes, and optional toggle/switch behavior. Can render as a button or anchor tag.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"primary" \| "secondary" \| string` | - | Style variant |
+| `size` | `"sm" \| "md" \| "lg" \| string` | - | Button size |
+| `muted` | `boolean` | `false` | Reduce text contrast for less emphasis |
+| `noshadow` | `boolean` | `false` | Remove shadow effect |
+| `noborder` | `boolean` | `false` | Remove border |
+| `unstyled` | `boolean` | `false` | Skip all default styling |
+| `inverse` | `boolean` | `false` | Transparent bg, styled on hover |
+| `href` | `string` | - | Render as anchor tag with this URL |
+| `roleSwitch` | `boolean` | `false` | Enable toggle/switch behavior |
+| `checked` | `boolean` | `false` | Toggle state when `roleSwitch` is true (bindable) |
+| `el` | `Element` | - | Element reference (bindable) |
+| `class` | `string` | - | Additional CSS classes |
+
+## Snippet Props
+
+The `children` snippet receives `{ checked }` when `roleSwitch` is enabled.
+
+## Usage
+
+### Basic Variants
+
+```svelte
+<script lang="ts">
+  import { Button } from 'stuic';
+</script>
+
+<Button>Default</Button>
+<Button variant="primary">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button size="sm">Small</Button>
+<Button size="lg">Large</Button>
+```
+
+### Inverse Style (Ghost Button)
+
+```svelte
+<Button inverse>
+  Hover to see background
+</Button>
+```
+
+### As Link
+
+```svelte
+<Button href="/dashboard">
+  Go to Dashboard
+</Button>
+```
+
+### Toggle Button
+
+```svelte
+<script lang="ts">
+  import { Button } from 'stuic';
+
+  let isActive = $state(false);
+</script>
+
+<Button roleSwitch bind:checked={isActive}>
+  {#snippet children({ checked })}
+    {checked ? 'ON' : 'OFF'}
+  {/snippet}
+</Button>
+```
+
+### Custom Styling
+
+```svelte
+<Button
+  unstyled
+  class="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600"
+>
+  Fully Custom
+</Button>
+```

package/dist/components/ButtonGroupRadio/README.md

@@ -0,0 +1,94 @@
+# ButtonGroupRadio
+
+A radio button group styled as a segmented button toggle. Supports keyboard navigation and async validation.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `(string \| FieldRadiosOption)[]` | - | Array of options |
+| `value` | `string` | - | Selected value (bindable) |
+| `activeIndex` | `number` | - | Selected index (bindable) |
+| `size` | `"sm" \| "md" \| "lg" \| string` | `"md"` | Button size |
+| `disabled` | `boolean` | `false` | Disable all buttons |
+| `tabindex` | `number` | `0` | Tab index for active button |
+| `class` | `string` | - | CSS for container |
+| `classButton` | `string` | - | CSS for all buttons |
+| `classButtonActive` | `string` | - | CSS for active button |
+| `style` | `string` | - | Inline styles for container |
+| `onButtonClick` | `(index, coll) => Promise<boolean> \| boolean` | - | Async validation hook (return `false` to prevent) |
+| `buttonProps` | `(index, coll) => Record<string, any>` | - | Dynamic props per button |
+
+## Option Format
+
+```ts
+// Simple string
+'Option A'
+
+// Or object
+{
+  label: 'Option A',
+  value: 'a'  // optional, defaults to label
+}
+```
+
+## Usage
+
+### Basic
+
+```svelte
+<script lang="ts">
+  import { ButtonGroupRadio } from 'stuic';
+
+  let selected = $state('monthly');
+</script>
+
+<ButtonGroupRadio
+  options={['daily', 'weekly', 'monthly']}
+  bind:value={selected}
+/>
+
+<p>Selected: {selected}</p>
+```
+
+### With Object Options
+
+```svelte
+<script lang="ts">
+  let plan = $state('pro');
+</script>
+
+<ButtonGroupRadio
+  options={[
+    { label: 'Free', value: 'free' },
+    { label: 'Pro', value: 'pro' },
+    { label: 'Enterprise', value: 'enterprise' }
+  ]}
+  bind:value={plan}
+/>
+```
+
+### With Async Validation
+
+```svelte
+<script lang="ts">
+  let value = $state('a');
+</script>
+
+<ButtonGroupRadio
+  options={['a', 'b', 'c']}
+  bind:value
+  onButtonClick={async (index, coll) => {
+    // Return false to prevent selection
+    if (index === 2) {
+      alert('Option C is disabled');
+      return false;
+    }
+  }}
+/>
+```
+
+## Keyboard Navigation
+
+- **Arrow Left/Up**: Select previous option
+- **Arrow Right/Down**: Select next option

package/dist/components/Circle/README.md

@@ -0,0 +1,70 @@
+# Circle
+
+An SVG circle progress indicator with configurable stroke, rotation, and animated transitions.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `completeness` | `number` | `1` | Progress value from 0 to 1 |
+| `strokeWidth` | `number` | `10` | Stroke width in SVG units |
+| `bgStrokeColor` | `string` | - | Background circle stroke color |
+| `roundedEdges` | `boolean` | `true` | Use rounded stroke line caps |
+| `rotate` | `number` | `0` | Rotation in degrees |
+| `strokeWidthRatio` | `number` | `0` | Ratio for background stroke width |
+| `animateCompletenessMs` | `number` | `0` | Transition duration for progress changes (ms) |
+| `class` | `string` | - | CSS for container div |
+| `style` | `string` | - | Inline styles for container |
+| `circleClass` | `string` | - | CSS for SVG circle element |
+| `circleStyle` | `string` | - | Inline styles for circle |
+
+## Usage
+
+### Basic Progress Circle
+
+```svelte
+<script lang="ts">
+  import { Circle } from 'stuic';
+</script>
+
+<Circle completeness={0.75} class="size-16" />
+```
+
+### Animated Progress
+
+```svelte
+<script lang="ts">
+  import { Circle } from 'stuic';
+
+  let progress = $state(0);
+
+  function startProgress() {
+    progress = 0;
+    const interval = setInterval(() => {
+      progress += 0.1;
+      if (progress >= 1) clearInterval(interval);
+    }, 200);
+  }
+</script>
+
+<Circle
+  completeness={progress}
+  animateCompletenessMs={200}
+  class="size-20"
+/>
+
+<button onclick={startProgress}>Start</button>
+```
+
+### Custom Styling
+
+```svelte
+<Circle
+  completeness={0.5}
+  strokeWidth={8}
+  rotate={-90}
+  bgStrokeColor="rgba(0,0,0,0.1)"
+  class="size-24"
+  circleClass="stroke-blue-500"
+/>
+```

package/dist/components/ColorScheme/README.md

@@ -0,0 +1,64 @@
+# ColorScheme
+
+Hydration components for dark mode support. Add/remove the `dark` class on the document root based on localStorage and optionally system preference.
+
+## Components
+
+### ColorSchemeLocal
+
+Uses only the localStorage setting to determine dark mode. Does not check system preference.
+
+### ColorSchemeSystemAware
+
+Checks localStorage first, then falls back to system preference (`prefers-color-scheme: dark`).
+
+## Props
+
+Both components have **no props** - they are pure hydration components.
+
+## Storage Key
+
+Both components use the localStorage key: `stuic-color-scheme`
+
+- Value `"dark"` → adds `dark` class to `<html>`
+- Any other value → removes `dark` class
+
+## Usage
+
+### System-Aware (Recommended)
+
+```svelte
+<script lang="ts">
+  import { ColorSchemeSystemAware } from 'stuic';
+</script>
+
+<ColorSchemeSystemAware />
+```
+
+### Local Only
+
+```svelte
+<script lang="ts">
+  import { ColorSchemeLocal } from 'stuic';
+</script>
+
+<ColorSchemeLocal />
+```
+
+### Toggle Dark Mode
+
+```svelte
+<script lang="ts">
+  import { ColorSchemeSystemAware } from 'stuic';
+
+  function toggleDarkMode() {
+    const root = document.documentElement;
+    const isDark = root.classList.toggle('dark');
+    localStorage.setItem('stuic-color-scheme', isDark ? 'dark' : 'light');
+  }
+</script>
+
+<ColorSchemeSystemAware />
+
+<button onclick={toggleDarkMode}>Toggle Dark Mode</button>
+```

package/dist/components/CommandMenu/README.md

@@ -0,0 +1,97 @@
+# CommandMenu
+
+A searchable command palette/menu modal for quick navigation and selection. Supports keyboard navigation, option grouping, and async search.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `any` | - | Selected item (bindable) |
+| `q` | `string` | `""` | Search query (bindable) |
+| `getOptions` | `(q: string, current: Item[]) => Promise<Item[]>` | - | Async function to fetch options |
+| `renderOptionLabel` | `(item: Item) => string` | - | Custom label renderer |
+| `renderOptionGroup` | `(s: string) => string` | - | Custom group label renderer |
+| `itemIdPropName` | `string` | `"id"` | Property name for item ID |
+| `t` | `TranslateFn` | - | Translation function for i18n |
+| `notifications` | `NotificationsStack` | - | Notifications stack for errors |
+| `searchPlaceholder` | `string` | `"Type to search..."` | Input placeholder |
+| `noScrollLock` | `boolean` | `false` | Disable body scroll lock |
+| `showAllOnEmptyQ` | `boolean` | `false` | Show all options when query is empty |
+| `classOption` | `string` | - | CSS for option buttons |
+| `classOptionActive` | `string` | - | CSS for active option |
+| `input` | `HTMLInputElement` | - | Input element reference (bindable) |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `open(opener?)` | Open the command menu |
+| `close()` | Close the command menu |
+
+## Usage
+
+### Basic
+
+```svelte
+<script lang="ts">
+  import { CommandMenu } from 'stuic';
+
+  let menu: CommandMenu;
+  let selected = $state(null);
+
+  async function getOptions(q: string) {
+    const items = [
+      { id: 'dashboard', label: 'Dashboard' },
+      { id: 'settings', label: 'Settings' },
+      { id: 'profile', label: 'Profile' },
+    ];
+    return items.filter(i =>
+      i.label.toLowerCase().includes(q.toLowerCase())
+    );
+  }
+</script>
+
+<button onclick={() => menu.open()}>Open Menu (Cmd+K)</button>
+
+<CommandMenu
+  bind:this={menu}
+  bind:value={selected}
+  {getOptions}
+  renderOptionLabel={(item) => item.label}
+/>
+
+{#if selected}
+  <p>Selected: {selected.label}</p>
+{/if}
+```
+
+### With Option Groups
+
+```svelte
+<script lang="ts">
+  async function getOptions(q: string) {
+    return [
+      { id: 'new-file', label: 'New File', optgroup: 'file' },
+      { id: 'open-file', label: 'Open File', optgroup: 'file' },
+      { id: 'copy', label: 'Copy', optgroup: 'edit' },
+      { id: 'paste', label: 'Paste', optgroup: 'edit' },
+    ];
+  }
+</script>
+
+<CommandMenu
+  bind:this={menu}
+  {getOptions}
+  renderOptionLabel={(item) => item.label}
+  renderOptionGroup={(group) => group.toUpperCase()}
+/>
+```
+
+## Keyboard Navigation
+
+- **Arrow Up/Down**: Navigate options
+- **Cmd/Ctrl + Arrow Up**: Jump to first option
+- **Cmd/Ctrl + Arrow Down**: Jump to last option
+- **Enter**: Select active option
+- **Escape**: Close menu (or clear input first)
+- **Tab**: Focus back to search input

package/dist/components/DismissibleMessage/README.md

@@ -0,0 +1,91 @@
+# DismissibleMessage
+
+A dismissible alert/message component with color themes and slide transition.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `message` | `THC \| Error` | - | Message content (string, HTML, or Error object) |
+| `theme` | `TW_COLORS` | - | Tailwind color theme (e.g., `"red"`, `"green"`, `"blue"`) |
+| `forceAsHtml` | `boolean` | `true` | Render message as HTML |
+| `duration` | `number` | `150` | Slide transition duration (ms) |
+| `onDismiss` | `(() => void) \| null \| false` | - | Dismiss callback (set to `false` to hide X button) |
+| `class` | `string` | - | CSS for container |
+| `classContent` | `string` | - | CSS for content area |
+| `classDismiss` | `string` | - | CSS for dismiss button |
+| `classX` | `string` | - | CSS for X icon |
+
+## Usage
+
+### Basic Message
+
+```svelte
+<script lang="ts">
+  import { DismissibleMessage } from 'stuic';
+
+  let message = $state('This is an important notice.');
+</script>
+
+<DismissibleMessage
+  {message}
+  onDismiss={() => message = ''}
+/>
+```
+
+### With Theme Colors
+
+```svelte
+<script lang="ts">
+  import { DismissibleMessage } from 'stuic';
+
+  let error = $state('Something went wrong!');
+  let success = $state('Operation completed successfully.');
+</script>
+
+<DismissibleMessage
+  message={error}
+  theme="red"
+  onDismiss={() => error = ''}
+/>
+
+<DismissibleMessage
+  message={success}
+  theme="green"
+  onDismiss={() => success = ''}
+/>
+```
+
+### Non-Dismissible
+
+```svelte
+<DismissibleMessage
+  message="This message cannot be dismissed."
+  theme="blue"
+  onDismiss={false}
+/>
+```
+
+### With Error Object
+
+```svelte
+<script lang="ts">
+  let error = $state<Error | null>(null);
+
+  function doSomething() {
+    try {
+      throw new Error('Network request failed');
+    } catch (e) {
+      error = e as Error;
+    }
+  }
+</script>
+
+{#if error}
+  <DismissibleMessage
+    message={error}
+    theme="red"
+    onDismiss={() => error = null}
+  />
+{/if}
+```

package/dist/components/Drawer/README.md

@@ -0,0 +1,110 @@
+# Drawer
+
+A slide-out panel component with configurable position, fly animation, and backdrop support.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `visible` | `boolean` | `false` | Controls visibility (bindable) |
+| `position` | `"left" \| "top" \| "right" \| "bottom"` | `"left"` | Slide direction |
+| `transitionDuration` | `number` | `200` | Animation duration (ms) |
+| `animOffset` | `string \| number` | `"75vw"` | Fly animation distance |
+| `focusTrap` | `boolean \| FocusTrapOptions` | - | Enable focus trapping |
+| `onEscape` | `() => void` | - | Callback on Escape key |
+| `onOutside` | `() => void` | - | Callback on backdrop click |
+| `noBackdropScrollLock` | `boolean` | `false` | Disable body scroll lock |
+| `class` | `string` | - | CSS for drawer panel |
+| `classBackdrop` | `string` | - | CSS for backdrop |
+| `labelledby` | `string` | - | ARIA labelledby ID |
+| `describedby` | `string` | - | ARIA describedby ID |
+| `el` | `HTMLDivElement` | - | Panel element reference (bindable) |
+| `elBackdrop` | `HTMLDivElement` | - | Backdrop element reference (bindable) |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `open(opener?)` | Open drawer, optionally track opener for focus return |
+| `close()` | Close drawer |
+| `setOpener(el)` | Set element to refocus when closed |
+
+## Usage
+
+### Basic Side Drawer
+
+```svelte
+<script lang="ts">
+  import { Drawer } from 'stuic';
+
+  let drawer: Drawer;
+</script>
+
+<button onclick={(e) => drawer.open(e)}>Open Drawer</button>
+
+<Drawer
+  bind:this={drawer}
+  onEscape={() => drawer.close()}
+  onOutside={() => drawer.close()}
+  class="bg-white dark:bg-neutral-900 max-w-md"
+>
+  <div class="p-6">
+    <h2>Drawer Content</h2>
+    <p>This is a side drawer.</p>
+    <button onclick={() => drawer.close()}>Close</button>
+  </div>
+</Drawer>
+```
+
+### Right-Side Drawer
+
+```svelte
+<Drawer
+  bind:this={drawer}
+  position="right"
+  onEscape={() => drawer.close()}
+  onOutside={() => drawer.close()}
+  class="bg-white dark:bg-neutral-900 max-w-sm"
+>
+  <nav class="p-4">
+    <ul>
+      <li>Menu Item 1</li>
+      <li>Menu Item 2</li>
+    </ul>
+  </nav>
+</Drawer>
+```
+
+### Bottom Sheet
+
+```svelte
+<Drawer
+  bind:this={drawer}
+  position="bottom"
+  animOffset="50vh"
+  onEscape={() => drawer.close()}
+  class="bg-white dark:bg-neutral-900 max-h-[50vh]"
+>
+  <div class="p-6">
+    Bottom sheet content
+  </div>
+</Drawer>
+```
+
+### With Visible Binding
+
+```svelte
+<script lang="ts">
+  let visible = $state(false);
+</script>
+
+<button onclick={() => visible = true}>Open</button>
+
+<Drawer
+  bind:visible
+  onEscape={() => visible = false}
+  onOutside={() => visible = false}
+>
+  <div class="p-4">Content</div>
+</Drawer>
+```

package/dist/components/HoverExpandableWidth/README.md

@@ -0,0 +1,81 @@
+# HoverExpandableWidth
+
+A container that expands its width on hover, transitioning from a fixed width to a target width. Useful for sidebars or navigation that expand to show more content.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enabled` | `boolean` | `true` (if fine pointer) | Enable hover expansion |
+| `targetWidth` | `number` | `256` | Expanded width in pixels |
+| `duration` | `number` | `150` | Transition duration (ms) |
+| `delayIn` | `number` | `500` | Delay before expanding (ms) |
+| `delayOut` | `number` | `300` | Delay before shrinking (ms) |
+| `shadowOpacity` | `number` | `0.5` | Box shadow opacity when expanded |
+| `class` | `string` | - | CSS classes for container |
+
+## Snippet Props
+
+The `children` snippet receives state information:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isExpanded` | `boolean` | Currently expanded |
+| `isExpanding` | `boolean` | Transition to expanded |
+| `isShrinking` | `boolean` | Transition to collapsed |
+| `inTransition` | `boolean` | Any transition active |
+
+## Usage
+
+### Basic Expandable Sidebar
+
+```svelte
+<script lang="ts">
+  import { HoverExpandableWidth } from 'stuic';
+</script>
+
+<div class="w-16 h-screen">
+  <HoverExpandableWidth targetWidth={256}>
+    {#snippet children({ isExpanded })}
+      <nav class="h-full bg-gray-100 p-2">
+        {#if isExpanded}
+          <ul>
+            <li>Dashboard</li>
+            <li>Settings</li>
+            <li>Profile</li>
+          </ul>
+        {:else}
+          <ul>
+            <li>D</li>
+            <li>S</li>
+            <li>P</li>
+          </ul>
+        {/if}
+      </nav>
+    {/snippet}
+  </HoverExpandableWidth>
+</div>
+```
+
+### With Custom Delays
+
+```svelte
+<HoverExpandableWidth
+  targetWidth={320}
+  delayIn={300}
+  delayOut={200}
+  duration={200}
+>
+  {#snippet children({ isExpanded, inTransition })}
+    <div class={inTransition ? 'opacity-50' : ''}>
+      {isExpanded ? 'Expanded content...' : 'Icon'}
+    </div>
+  {/snippet}
+</HoverExpandableWidth>
+```
+
+## Notes
+
+- Respects `prefers-reduced-motion` - animations disabled when user prefers reduced motion
+- Automatically disabled on touch devices (coarse pointer)
+- Uses `position: fixed` during expansion for overlay effect