@marianmeres/stuic 2.5.0 → 2.6.0

package/dist/components/Input/README.md

@@ -0,0 +1,192 @@
+# Input
+
+A comprehensive form input system with multiple field components, validation support, and flexible layouts.
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `FieldInput` | Text, email, password, number, and other input types |
+| `FieldTextarea` | Multi-line text input with auto-grow |
+| `FieldSelect` | Dropdown select with option groups |
+| `FieldCheckbox` | Single checkbox with label |
+| `FieldRadios` | Radio button group |
+| `FieldSwitch` | Toggle switch field |
+| `FieldFile` | File upload input |
+| `FieldAssets` | Asset/image upload with preview |
+| `FieldLikeButton` | Like/favorite toggle button |
+| `Fieldset` | Fieldset with legend |
+
+## Common Props (FieldInput, FieldTextarea, FieldSelect)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string \| number` | - | Field value (bindable) |
+| `input` | `HTMLInputElement` | - | Element reference (bindable) |
+| `label` | `Snippet \| THC` | - | Field label |
+| `description` | `Snippet \| THC` | - | Help text below field |
+| `id` | `string` | auto | Element ID |
+| `renderSize` | `"sm" \| "md" \| "lg"` | `"md"` | Visual size |
+| `required` | `boolean` | `false` | Mark as required |
+| `disabled` | `boolean` | `false` | Disable field |
+| `validate` | `boolean \| ValidateOptions` | - | Enable validation |
+| `labelLeft` | `boolean` | `false` | Position label on left |
+| `labelLeftWidth` | `"normal" \| "wide"` | `"normal"` | Left label width |
+| `useTrim` | `boolean` | `true` | Auto-trim whitespace |
+| `class` | `string` | - | Container CSS |
+| `classInput` | `string` | - | Input element CSS |
+| `classLabel` | `string` | - | Label CSS |
+
+## Slot Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `labelAfter` | `Snippet \| THC` | Content after label |
+| `inputBefore` | `Snippet \| THC` | Content before input (inside wrapper) |
+| `inputAfter` | `Snippet \| THC` | Content after input (inside wrapper) |
+| `inputBelow` | `Snippet \| THC` | Content below input |
+| `below` | `Snippet \| THC` | Content below entire field |
+
+## Usage
+
+### Basic Text Input
+
+```svelte
+<script lang="ts">
+  import { FieldInput } from 'stuic';
+
+  let name = $state('');
+</script>
+
+<FieldInput
+  label="Name"
+  bind:value={name}
+  placeholder="Enter your name"
+  required
+/>
+```
+
+### With Validation
+
+```svelte
+<FieldInput
+  label="Email"
+  type="email"
+  bind:value={email}
+  validate
+  required
+/>
+```
+
+### Select Field
+
+```svelte
+<script lang="ts">
+  import { FieldSelect } from 'stuic';
+
+  let country = $state('');
+</script>
+
+<FieldSelect
+  label="Country"
+  bind:value={country}
+  options={[
+    { label: 'United States', value: 'us' },
+    { label: 'Canada', value: 'ca' },
+    { label: 'Mexico', value: 'mx' }
+  ]}
+/>
+```
+
+### Grouped Select Options
+
+```svelte
+<FieldSelect
+  label="City"
+  options={[
+    { label: 'New York', value: 'ny', optgroup: 'USA' },
+    { label: 'Los Angeles', value: 'la', optgroup: 'USA' },
+    { label: 'Toronto', value: 'to', optgroup: 'Canada' }
+  ]}
+/>
+```
+
+### Textarea with Auto-grow
+
+```svelte
+<script lang="ts">
+  import { FieldTextarea } from 'stuic';
+
+  let message = $state('');
+</script>
+
+<FieldTextarea
+  label="Message"
+  bind:value={message}
+  useAutogrow
+  rows={3}
+/>
+```
+
+### Checkbox
+
+```svelte
+<script lang="ts">
+  import { FieldCheckbox } from 'stuic';
+
+  let agreed = $state(false);
+</script>
+
+<FieldCheckbox
+  label="I agree to the terms"
+  bind:checked={agreed}
+  required
+/>
+```
+
+### Input with Addons
+
+```svelte
+<FieldInput
+  label="Price"
+  type="number"
+  bind:value={price}
+>
+  {#snippet inputBefore()}
+    <span class="px-3 text-gray-500">$</span>
+  {/snippet}
+  {#snippet inputAfter()}
+    <span class="px-3 text-gray-500">.00</span>
+  {/snippet}
+</FieldInput>
+```
+
+### Left-aligned Label
+
+```svelte
+<FieldInput
+  label="Username"
+  bind:value={username}
+  labelLeft
+  labelLeftWidth="wide"
+/>
+```
+
+## Validation
+
+Validation is handled by the `validate` action. Pass `validate={true}` for default HTML5 validation, or pass options:
+
+```svelte
+<FieldInput
+  label="Custom"
+  bind:value={val}
+  validate={{
+    validatorFn: (el) => {
+      if (el.value.length < 3) {
+        return { valid: false, message: 'Min 3 characters' };
+      }
+      return { valid: true };
+    }
+  }}
+/>
+```

package/dist/components/KbdShortcut/README.md

@@ -0,0 +1,81 @@
+# KbdShortcut
+
+Display keyboard shortcuts with platform-aware modifier key symbols. Automatically shows the correct symbols for macOS (⌘, ⌥, ⇧) vs Windows/Linux (Win, Ctrl, Alt).
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `keys` | `string` | - | The key(s) to display (e.g., `"K"`, `"Enter"`) |
+| `metas` | `KnownMeta[]` | `[]` | Array of modifier keys |
+| `forcedOs` | `"mac" \| "win" \| "linux"` | - | Force specific OS symbols |
+| `class` | `string` | - | CSS classes |
+
+## Meta Keys
+
+| Meta | macOS | Windows/Linux |
+|------|-------|---------------|
+| `cmd` | ⌘ | ⊞ |
+| `meta` | ⌘ | ⊞ |
+| `win` | ⌘ | ⊞ |
+| `opt` | ⌥ | Alt |
+| `alt` | ⌥ | Alt |
+| `shift` | ⇧ | ⇧ |
+| `ctrl` | ⌃ | Ctrl |
+
+## Usage
+
+### Basic Shortcut
+
+```svelte
+<script lang="ts">
+  import { KbdShortcut } from 'stuic';
+</script>
+
+<KbdShortcut metas={['cmd']} keys="K" />
+<!-- macOS: ⌘K -->
+<!-- Windows: ⊞K -->
+```
+
+### Multiple Modifiers
+
+```svelte
+<KbdShortcut metas={['cmd', 'shift']} keys="P" />
+<!-- macOS: ⌘⇧P -->
+<!-- Windows: ⊞⇧P -->
+```
+
+### Key Only
+
+```svelte
+<KbdShortcut keys="Enter" />
+<!-- Displays: Enter -->
+```
+
+### Force Specific OS
+
+```svelte
+<KbdShortcut metas={['cmd']} keys="S" forcedOs="mac" />
+<!-- Always shows: ⌘S -->
+
+<KbdShortcut metas={['cmd']} keys="S" forcedOs="win" />
+<!-- Always shows: ⊞S -->
+```
+
+### In Context
+
+```svelte
+<p>
+  Press <KbdShortcut metas={['cmd']} keys="K" /> to open search
+</p>
+```
+
+### Custom Styling
+
+```svelte
+<KbdShortcut
+  metas={['cmd', 'shift']}
+  keys="Z"
+  class="bg-gray-100 px-2 py-1"
+/>
+```

package/dist/components/Modal/README.md

@@ -0,0 +1,117 @@
+# Modal
+
+A centered modal dialog with optional header and footer sections. Built on top of `Backdrop` with focus trap and scroll locking.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `visible` | `boolean` | `false` | Controls visibility (bindable) |
+| `focusTrap` | `boolean \| FocusTrapOptions` | `true` | Enable focus trapping |
+| `transitionDuration` | `number` | `100` | Fade transition duration (ms) |
+| `onEscape` | `() => void` | - | Callback on Escape key |
+| `noScrollLock` | `boolean` | `false` | Disable body scroll lock |
+| `classBackdrop` | `string` | - | CSS for backdrop overlay |
+| `classInner` | `string` | - | CSS for inner width container |
+| `class` | `string` | - | CSS for modal box |
+| `classHeader` | `string` | - | CSS for header section |
+| `classMain` | `string` | - | CSS for main content |
+| `classFooter` | `string` | - | CSS for footer section |
+| `labelledby` | `string` | - | ARIA labelledby ID |
+| `describedby` | `string` | - | ARIA describedby ID |
+| `el` | `HTMLDivElement` | - | Modal element reference (bindable) |
+| `elBackdrop` | `HTMLDivElement` | - | Backdrop element reference (bindable) |
+
+## Snippets
+
+| Snippet | Description |
+|---------|-------------|
+| `header` | Optional header section |
+| `children` | Main modal content |
+| `footer` | Optional footer section |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `open(opener?)` | Open modal, optionally track opener element |
+| `close()` | Close modal |
+| `setOpener(el)` | Set element to refocus when closed |
+| `visibility()` | Returns object with `visible` getter |
+
+## Usage
+
+### Basic Modal
+
+```svelte
+<script lang="ts">
+  import { Modal } from 'stuic';
+
+  let modal: Modal;
+</script>
+
+<button onclick={(e) => modal.open(e)}>Open Modal</button>
+
+<Modal
+  bind:this={modal}
+  onEscape={() => modal.close()}
+>
+  <div class="p-6">
+    <h2>Modal Title</h2>
+    <p>Modal content goes here.</p>
+    <button onclick={() => modal.close()}>Close</button>
+  </div>
+</Modal>
+```
+
+### With Header and Footer
+
+```svelte
+<Modal bind:this={modal} onEscape={() => modal.close()}>
+  {#snippet header()}
+    <div class="p-4 border-b">
+      <h2>Confirm Action</h2>
+    </div>
+  {/snippet}
+
+  <div class="p-6">
+    Are you sure you want to proceed?
+  </div>
+
+  {#snippet footer()}
+    <div class="p-4 border-t flex justify-end gap-2">
+      <button onclick={() => modal.close()}>Cancel</button>
+      <button onclick={handleConfirm}>Confirm</button>
+    </div>
+  {/snippet}
+</Modal>
+```
+
+### With Visibility Binding
+
+```svelte
+<script lang="ts">
+  let visible = $state(false);
+</script>
+
+<button onclick={() => visible = true}>Open</button>
+
+<Modal
+  bind:visible
+  onEscape={() => visible = false}
+>
+  <div class="p-6">Content</div>
+</Modal>
+```
+
+### Custom Sizing
+
+```svelte
+<Modal
+  bind:this={modal}
+  classInner="max-w-lg"
+  class="rounded-lg"
+>
+  <div class="p-6">Smaller modal</div>
+</Modal>
+```

package/dist/components/ModalDialog/README.md

@@ -0,0 +1,103 @@
+# ModalDialog
+
+A modal component using the native HTML `<dialog>` element with `showModal()`. Provides built-in backdrop, focus management, and accessibility.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `noClickOutsideClose` | `boolean` | `false` | Disable close on outside click |
+| `noEscapeClose` | `boolean` | `false` | Disable close on Escape key |
+| `preEscapeClose` | `() => any` | - | Hook before Escape close (return `false` to prevent) |
+| `preClose` | `() => any` | - | Hook before any close (return `false` to prevent) |
+| `type` | `string` | - | Optional UI hint (added as `data-type` attribute) |
+| `class` | `string` | - | CSS for content box |
+| `classDialog` | `string` | - | CSS for dialog element |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `open(opener?)` | Open modal with `showModal()`, optionally track opener |
+| `close()` | Close modal |
+| `setOpener(el)` | Set element to refocus when closed |
+
+## Usage
+
+### Basic Dialog
+
+```svelte
+<script lang="ts">
+  import { ModalDialog } from 'stuic';
+
+  let dialog: ModalDialog;
+</script>
+
+<button onclick={(e) => dialog.open(e)}>Open Dialog</button>
+
+<ModalDialog bind:this={dialog} class="p-6 rounded-lg max-w-md">
+  <h2>Dialog Title</h2>
+  <p>This uses the native dialog element.</p>
+  <button onclick={() => dialog.close()}>Close</button>
+</ModalDialog>
+```
+
+### With Pre-close Validation
+
+```svelte
+<script lang="ts">
+  let hasUnsavedChanges = $state(false);
+</script>
+
+<ModalDialog
+  bind:this={dialog}
+  preClose={() => {
+    if (hasUnsavedChanges) {
+      return confirm('Discard unsaved changes?');
+    }
+  }}
+  class="p-6 rounded-lg"
+>
+  <form>
+    <input oninput={() => hasUnsavedChanges = true} />
+    <button type="button" onclick={() => dialog.close()}>Close</button>
+  </form>
+</ModalDialog>
+```
+
+### Prevent Outside Click Close
+
+```svelte
+<ModalDialog
+  bind:this={dialog}
+  noClickOutsideClose
+  class="p-6 rounded-lg"
+>
+  <p>Click outside won't close this dialog.</p>
+  <button onclick={() => dialog.close()}>Close</button>
+</ModalDialog>
+```
+
+### Async Pre-close Hook
+
+```svelte
+<ModalDialog
+  bind:this={dialog}
+  preEscapeClose={async () => {
+    const shouldClose = await confirmAction();
+    return shouldClose;
+  }}
+>
+  Content
+</ModalDialog>
+```
+
+## Differences from Modal
+
+| Feature | Modal | ModalDialog |
+|---------|-------|-------------|
+| Implementation | Custom backdrop | Native `<dialog>` |
+| Backdrop | Via `Backdrop` component | Native `::backdrop` |
+| Browser support | All modern | Requires `<dialog>` support |
+| Stacking | Manual z-index | Top layer (always on top) |
+| Accessibility | Manual ARIA | Built-in |

package/dist/components/Notifications/README.md

@@ -0,0 +1,144 @@
+# Notifications
+
+A toast notification system with auto-disposal, deduplication, progress indicators, and flexible positioning.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `notifications` | `NotificationsStack` | - | Stack instance (required) |
+| `posX` | `"left" \| "center" \| "right"` | `"right"` | Horizontal position (desktop) |
+| `posY` | `"top" \| "center" \| "bottom"` | `"top"` | Vertical position (desktop) |
+| `posXMobile` | `"left" \| "center" \| "right"` | `"center"` | Horizontal position (mobile) |
+| `posYMobile` | `"top" \| "center" \| "bottom"` | `"top"` | Vertical position (mobile) |
+| `themeInfo` | `TW_COLORS` | `"neutral"` | Color theme for info notifications |
+| `themeError` | `TW_COLORS` | `"red"` | Color theme for error notifications |
+| `themeWarn` | `TW_COLORS` | `"yellow"` | Color theme for warning notifications |
+| `themeSuccess` | `TW_COLORS` | `"green"` | Color theme for success notifications |
+| `noTheme` | `boolean` | `false` | Disable color theming |
+| `noIcons` | `boolean` | `false` | Hide notification icons |
+| `noProgress` | `boolean` | `false` | Hide TTL progress bar |
+| `noXButton` | `boolean` | `false` | Hide close button |
+| `duration` | `number` | `200` | Fade transition duration (ms) |
+| `forceAsHtml` | `boolean` | - | Render content as HTML |
+| `iconFns` | `Record<type, () => string>` | - | Custom icon functions |
+
+## NotificationsStack API
+
+### Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxCapacity` | `number` | `5` | Maximum notifications in queue |
+| `defaultTtl` | `number` | `3000` | Default time-to-live (ms) |
+| `extraTtlPerChar` | `number` | `20` | Extra TTL per content character |
+| `sortOrder` | `"asc" \| "desc"` | `"asc"` | Stack sort order |
+| `disposeInterval` | `number` | `500` | Auto-dispose check interval (ms) |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `info(content, opts?)` | Add info notification |
+| `success(content, opts?)` | Add success notification |
+| `warn(content, opts?)` | Add warning notification |
+| `error(content, opts?)` | Add error notification |
+| `removeById(id)` | Remove notification by ID |
+| `reset()` | Clear all notifications |
+| `destroy()` | Cleanup and stop ticker |
+
+### Notification Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `id` | `string \| number` | Unique ID (auto-generated from content if omitted) |
+| `ttl` | `number` | Time-to-live in ms (0 = no auto-dismiss) |
+| `iconFn` | `(() => string) \| false` | Custom icon or `false` to hide |
+| `forceAsHtml` | `boolean` | Render content as HTML |
+
+## Usage
+
+### Basic Setup
+
+```svelte
+<script lang="ts">
+  import { Notifications, NotificationsStack } from 'stuic';
+
+  const notifications = new NotificationsStack();
+</script>
+
+<Notifications {notifications} />
+
+<button onclick={() => notifications.info('Hello!')}>
+  Show Info
+</button>
+```
+
+### Different Types
+
+```svelte
+<script lang="ts">
+  notifications.info('Information message');
+  notifications.success('Operation successful!');
+  notifications.warn('Warning: check this');
+  notifications.error('An error occurred');
+</script>
+```
+
+### Custom TTL
+
+```svelte
+<script lang="ts">
+  // Auto-dismiss after 10 seconds
+  notifications.info('Long message', { ttl: 10000 });
+
+  // Never auto-dismiss
+  notifications.error('Critical error', { ttl: 0 });
+</script>
+```
+
+### Deduplication
+
+```svelte
+<script lang="ts">
+  // Same content = same ID = increments count instead of duplicating
+  notifications.info('Save completed');
+  notifications.info('Save completed'); // Shows "2" badge
+</script>
+```
+
+### Custom Positioning
+
+```svelte
+<Notifications
+  {notifications}
+  posX="left"
+  posY="bottom"
+  posXMobile="center"
+  posYMobile="bottom"
+/>
+```
+
+### Custom Stack Options
+
+```svelte
+<script lang="ts">
+  const notifications = new NotificationsStack([], {
+    maxCapacity: 3,
+    defaultTtl: 5000,
+    sortOrder: 'desc'
+  });
+</script>
+```
+
+## Cleanup
+
+```svelte
+<script lang="ts">
+  import { onDestroy } from 'svelte';
+
+  const notifications = new NotificationsStack();
+
+  onDestroy(() => notifications.destroy());
+</script>
+```

package/dist/components/Progress/README.md

@@ -0,0 +1,71 @@
+# Progress
+
+A progress indicator available as either a horizontal bar or circular display.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `"bar" \| "circle"` | `"bar"` | Display type |
+| `progress` | `number` | `0` | Progress value (0-100) |
+| `class` | `string` | - | CSS for container |
+| `classBar` | `string` | - | CSS for progress bar fill (bar type only) |
+| `styleBar` | `string` | - | Inline styles for bar fill |
+
+## Usage
+
+### Basic Bar
+
+```svelte
+<script lang="ts">
+  import { Progress } from 'stuic';
+
+  let progress = $state(0);
+</script>
+
+<Progress {progress} />
+```
+
+### Circle Progress
+
+```svelte
+<Progress type="circle" progress={75} class="size-16" />
+```
+
+### Animated Progress
+
+```svelte
+<script lang="ts">
+  let progress = $state(0);
+
+  function start() {
+    progress = 0;
+    const interval = setInterval(() => {
+      progress += 10;
+      if (progress >= 100) clearInterval(interval);
+    }, 300);
+  }
+</script>
+
+<Progress {progress} />
+<button onclick={start}>Start</button>
+```
+
+### Custom Styling
+
+```svelte
+<Progress
+  progress={60}
+  class="h-2 bg-gray-200 rounded-full"
+  classBar="bg-blue-500 rounded-full"
+/>
+```
+
+### With Transition
+
+```svelte
+<Progress
+  progress={value}
+  classBar="transition-all duration-300"
+/>
+```