@marianmeres/stuic 2.5.0 → 2.6.0

package/dist/components/SlidingPanels/README.md

@@ -0,0 +1,123 @@
+# SlidingPanels
+
+A two-panel layout with smooth sliding transitions between panels. Useful for master-detail views, wizard flows, or progressive disclosure.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `initial` | `"A" \| "B"` | `"A"` | Initially active panel |
+| `duration` | `number` | `300` | Transition duration (ms) |
+| `destroyInactive` | `boolean` | `true` | Unmount inactive panel from DOM |
+| `class` | `string` | - | CSS for container |
+| `panelA` | `Snippet` | - | Content for Panel A (required) |
+| `panelB` | `Snippet` | - | Content for Panel B |
+
+## Snippet Props
+
+Both panel snippets receive:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `show` | `(panel: "A" \| "B") => Promise<boolean>` | Function to switch panels |
+| `active` | `"A" \| "B"` | Currently active panel |
+| `inTransition` | `boolean` | Whether transition is in progress |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `show(panel)` | Switch to specified panel, returns `false` if already active or transitioning |
+| `current()` | Returns object with `active` and `isTransitioning` getters |
+
+## Usage
+
+### Basic Two-Panel Layout
+
+```svelte
+<script lang="ts">
+  import { SlidingPanels } from 'stuic';
+</script>
+
+<div class="h-96">
+  <SlidingPanels>
+    {#snippet panelA({ show })}
+      <div class="p-4">
+        <h2>Panel A</h2>
+        <button onclick={() => show('B')}>Go to Panel B</button>
+      </div>
+    {/snippet}
+
+    {#snippet panelB({ show })}
+      <div class="p-4">
+        <h2>Panel B</h2>
+        <button onclick={() => show('A')}>Back to Panel A</button>
+      </div>
+    {/snippet}
+  </SlidingPanels>
+</div>
+```
+
+### Master-Detail Pattern
+
+```svelte
+<script lang="ts">
+  let selectedItem = $state(null);
+</script>
+
+<SlidingPanels duration={200}>
+  {#snippet panelA({ show })}
+    <ul>
+      {#each items as item}
+        <li>
+          <button onclick={() => {
+            selectedItem = item;
+            show('B');
+          }}>
+            {item.name}
+          </button>
+        </li>
+      {/each}
+    </ul>
+  {/snippet}
+
+  {#snippet panelB({ show })}
+    {#if selectedItem}
+      <article>
+        <button onclick={() => show('A')}>← Back</button>
+        <h1>{selectedItem.name}</h1>
+        <p>{selectedItem.description}</p>
+      </article>
+    {/if}
+  {/snippet}
+</SlidingPanels>
+```
+
+### Keep Inactive Panel in DOM
+
+```svelte
+<SlidingPanels destroyInactive={false}>
+  {#snippet panelA({ show })}
+    <!-- Panel A content persists when switching -->
+  {/snippet}
+  {#snippet panelB({ show })}
+    <!-- Panel B content persists when switching -->
+  {/snippet}
+</SlidingPanels>
+```
+
+### With Component Reference
+
+```svelte
+<script lang="ts">
+  let panels: SlidingPanels;
+</script>
+
+<SlidingPanels bind:this={panels}>
+  <!-- panels -->
+</SlidingPanels>
+
+<button onclick={() => panels.show('B')}>
+  Go to B
+</button>
+```

package/dist/components/Spinner/README.md

@@ -0,0 +1,80 @@
+# Spinner
+
+A customizable loading spinner with rotating segments. Pure CSS animation with configurable appearance.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `duration` | `number` | `750` | One full rotation duration (ms) |
+| `count` | `number` | `8` | Number of segments/hands (3-12) |
+| `thickness` | `"thin" \| "normal" \| "thick"` | `"thick"` | Segment width |
+| `height` | `"short" \| "normal" \| "tall"` | `"normal"` | Segment length |
+| `direction` | `"cw" \| "ccw"` | `"cw"` | Rotation direction (clockwise/counter-clockwise) |
+| `class` | `string` | - | CSS classes for sizing |
+
+## Usage
+
+### Basic Spinner
+
+```svelte
+<script lang="ts">
+  import { Spinner } from 'stuic';
+</script>
+
+<Spinner />
+```
+
+### Different Sizes
+
+```svelte
+<Spinner class="w-4" />
+<Spinner class="w-6" />
+<Spinner class="w-8" />
+<Spinner class="w-12" />
+```
+
+### Customized Appearance
+
+```svelte
+<!-- More segments, thinner -->
+<Spinner count={12} thickness="thin" />
+
+<!-- Fewer segments, thicker, taller -->
+<Spinner count={4} thickness="thick" height="tall" />
+```
+
+### Slower/Faster Animation
+
+```svelte
+<Spinner duration={500} />  <!-- Faster -->
+<Spinner duration={1500} /> <!-- Slower -->
+```
+
+### Counter-Clockwise
+
+```svelte
+<Spinner direction="ccw" />
+```
+
+### With Custom Color
+
+```svelte
+<Spinner class="w-8 text-blue-500" />
+<Spinner class="w-8 text-green-500" />
+```
+
+### Loading Button
+
+```svelte
+<script lang="ts">
+  let loading = $state(false);
+</script>
+
+<button disabled={loading}>
+  {#if loading}
+    <Spinner class="w-4 mr-2" />
+  {/if}
+  Submit
+</button>
+```

package/dist/components/Switch/README.md

@@ -0,0 +1,113 @@
+# Switch
+
+A toggle switch component with size variants, keyboard support, and optional async validation.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `checked` | `boolean` | - | Toggle state (bindable) |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| string` | `"md"` | Switch size |
+| `name` | `string` | - | Form field name for hidden checkbox |
+| `label` | `string` | - | Screen reader label (visually hidden) |
+| `required` | `boolean` | `false` | Mark as required |
+| `disabled` | `boolean` | `false` | Disable toggle |
+| `tabindex` | `number` | `0` | Tab index |
+| `preHook` | `(current: boolean) => Promise<false \| any>` | - | Async validation (return `false` to prevent) |
+| `validate` | `boolean \| ValidateOptions` | - | Enable validation |
+| `class` | `string` | - | CSS for switch container |
+| `dotClass` | `string` | - | CSS for toggle knob |
+| `button` | `HTMLButtonElement` | - | Button element reference (bindable) |
+
+## Snippets
+
+| Snippet | Description |
+|---------|-------------|
+| `on` | Content inside knob when checked |
+| `off` | Content inside knob when unchecked |
+
+## Usage
+
+### Basic Toggle
+
+```svelte
+<script lang="ts">
+  import { Switch } from 'stuic';
+
+  let enabled = $state(false);
+</script>
+
+<Switch bind:checked={enabled} />
+<span>{enabled ? 'On' : 'Off'}</span>
+```
+
+### Different Sizes
+
+```svelte
+<Switch size="xs" />
+<Switch size="sm" />
+<Switch size="md" />
+<Switch size="lg" />
+<Switch size="xl" />
+```
+
+### With Icons Inside
+
+```svelte
+<Switch bind:checked={darkMode}>
+  {#snippet on()}
+    <span class="text-xs">🌙</span>
+  {/snippet}
+  {#snippet off()}
+    <span class="text-xs">☀️</span>
+  {/snippet}
+</Switch>
+```
+
+### With Async Validation
+
+```svelte
+<script lang="ts">
+  let premium = $state(false);
+
+  async function checkPremium(current: boolean) {
+    if (!current) {
+      // Turning on - check if user can enable premium
+      const canEnable = await checkSubscription();
+      if (!canEnable) {
+        alert('Premium subscription required');
+        return false; // Prevent toggle
+      }
+    }
+    return true;
+  }
+</script>
+
+<Switch
+  bind:checked={premium}
+  preHook={checkPremium}
+/>
+```
+
+### In a Form
+
+```svelte
+<form>
+  <label class="flex items-center gap-2">
+    <Switch name="notifications" bind:checked={notifications} />
+    <span>Enable notifications</span>
+  </label>
+</form>
+```
+
+### Disabled State
+
+```svelte
+<Switch checked={true} disabled />
+<Switch checked={false} disabled />
+```
+
+## Keyboard Support
+
+- **Space**: Toggle switch
+- **Enter**: Toggle switch

package/dist/components/Thc/README.md

@@ -0,0 +1,113 @@
+# Thc
+
+A flexible content renderer supporting multiple content formats: Text, Html, or Component (THC). Used throughout stuic for flexible content rendering in labels, messages, and other dynamic content areas.
+
+## THC Type
+
+```ts
+type THC =
+  | string                              // Plain string
+  | { text: string }                    // Explicit text
+  | { html: string }                    // HTML (rendered with @html)
+  | { component: Component, props?: {} } // Svelte component
+  | { snippet: Snippet }                // Svelte snippet
+  | Snippet                             // Direct snippet function
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `thc` | `THC` | - | Content to render |
+| `forceAsHtml` | `boolean` | `false` | Render strings as HTML |
+| `allowCastToStringFallback` | `boolean` | `true` | Cast unknown types to string |
+
+## Utility Functions
+
+### `isTHCNotEmpty(value)`
+
+Checks if a THC value has renderable content.
+
+```ts
+isTHCNotEmpty("Hello");           // true
+isTHCNotEmpty({ text: "Hi" });    // true
+isTHCNotEmpty("");                // false
+isTHCNotEmpty(null);              // false
+```
+
+### `getTHCStringContent(value)`
+
+Extracts string content from a THC value.
+
+```ts
+getTHCStringContent("Hello");           // "Hello"
+getTHCStringContent({ text: "Hi" });    // "Hi"
+getTHCStringContent({ html: "<b>X</b>" }); // "<b>X</b>"
+getTHCStringContent(null);              // ""
+```
+
+## Usage
+
+### Plain String
+
+```svelte
+<script lang="ts">
+  import { Thc } from 'stuic';
+</script>
+
+<Thc thc="Hello World" />
+```
+
+### HTML Content
+
+```svelte
+<Thc thc={{ html: "<strong>Bold</strong> and <em>italic</em>" }} />
+```
+
+### Force String as HTML
+
+```svelte
+<Thc thc="<strong>Bold</strong>" forceAsHtml />
+```
+
+### Component Content
+
+```svelte
+<script lang="ts">
+  import MyIcon from './MyIcon.svelte';
+</script>
+
+<Thc thc={{
+  component: MyIcon,
+  props: { size: 24, color: 'blue' }
+}} />
+```
+
+### Snippet Content
+
+```svelte
+{#snippet myContent()}
+  <span class="custom">Custom snippet content</span>
+{/snippet}
+
+<Thc thc={{ snippet: myContent }} />
+
+<!-- Or directly -->
+<Thc thc={myContent} />
+```
+
+### In Other Components
+
+Many stuic components accept THC for labels and content:
+
+```svelte
+<FieldInput
+  label="Username"
+  description={{ html: "Enter your <strong>unique</strong> username" }}
+/>
+
+<DismissibleMessage
+  message={{ text: "Operation completed" }}
+  theme="green"
+/>
+```

package/dist/components/TwCheck/README.md

@@ -0,0 +1,54 @@
+# TwCheck
+
+A development utility component to verify that Tailwind CSS is properly loaded and working. Displays differently styled content at different breakpoints.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `theme` | `string` | - | Tailwind color theme for background |
+| `class` | `string` | - | Additional CSS classes |
+
+## Usage
+
+### Basic Check
+
+```svelte
+<script lang="ts">
+  import { TwCheck } from 'stuic';
+</script>
+
+<TwCheck>
+  TW Check
+</TwCheck>
+```
+
+### With Theme
+
+```svelte
+<TwCheck theme="blue">
+  Tailwind is working!
+</TwCheck>
+```
+
+## Visual Indicators
+
+When Tailwind CSS is properly loaded:
+- **Mobile**: Yellow text, no border
+- **Desktop (sm+)**: White text, teal border, larger font
+
+If the component appears unstyled (plain text), Tailwind CSS is not loading correctly.
+
+## Development Use
+
+Add temporarily during development to verify Tailwind setup:
+
+```svelte
+<script lang="ts">
+  import { dev } from '$app/environment';
+</script>
+
+{#if dev}
+  <TwCheck>CSS OK</TwCheck>
+{/if}
+```

package/dist/components/TypeaheadInput/README.md

@@ -0,0 +1,116 @@
+# TypeaheadInput
+
+An input with typeahead/autocomplete suggestions. Shows inline suggestions that can be accepted with Tab, with support for async data fetching and keyboard navigation.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `any` | - | Current input value (bindable) |
+| `input` | `HTMLInputElement` | - | Input element reference (bindable) |
+| `placeholder` | `string` | - | Input placeholder |
+| `getOptions` | `(q: string, current: T[]) => Promise<T[]>` | - | Async function to fetch suggestions |
+| `renderOptionLabel` | `(item: T) => string` | - | Render label for an option |
+| `itemIdPropName` | `string` | `"id"` | Property name for item ID |
+| `name` | `string` | `"text_input"` | Input name attribute |
+| `onSubmit` | `(value: string) => void` | - | Called on Enter or blur |
+| `onDeleteRequest` | `() => void` | - | Called on Backspace at position 0 |
+| `noSpinner` | `boolean` | `false` | Hide loading spinner |
+| `noListAllOnEmptyQ` | `boolean` | `false` | Don't show all options on empty query |
+| `appendHint` | `string` | `" [tab]"` | Hint text appended to suggestion |
+| `class` | `string` | - | CSS for container |
+| `classInput` | `string` | - | CSS for input element |
+
+## Usage
+
+### Basic Typeahead
+
+```svelte
+<script lang="ts">
+  import { TypeaheadInput } from 'stuic';
+
+  let city = $state('');
+
+  const cities = ['New York', 'Los Angeles', 'Chicago', 'Houston', 'Phoenix'];
+
+  async function getOptions(q: string) {
+    return cities
+      .filter(c => c.toLowerCase().startsWith(q.toLowerCase()))
+      .map((label, id) => ({ id, label }));
+  }
+</script>
+
+<TypeaheadInput
+  bind:value={city}
+  {getOptions}
+  renderOptionLabel={(item) => item.label}
+  placeholder="Enter city name"
+  onSubmit={(value) => console.log('Selected:', value)}
+/>
+```
+
+### With API Fetch
+
+```svelte
+<script lang="ts">
+  async function getOptions(q: string) {
+    if (!q) return [];
+    const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`);
+    return res.json();
+  }
+</script>
+
+<TypeaheadInput
+  bind:value
+  {getOptions}
+  renderOptionLabel={(item) => item.name}
+/>
+```
+
+### Tag Input Pattern
+
+```svelte
+<script lang="ts">
+  let tags = $state<string[]>([]);
+  let currentTag = $state('');
+</script>
+
+<div class="flex gap-2 flex-wrap">
+  {#each tags as tag}
+    <span class="bg-gray-200 px-2 py-1 rounded">{tag}</span>
+  {/each}
+
+  <TypeaheadInput
+    bind:value={currentTag}
+    {getOptions}
+    renderOptionLabel={(item) => item.label}
+    onSubmit={(value) => {
+      if (value && !tags.includes(value)) {
+        tags = [...tags, value];
+        currentTag = '';
+      }
+    }}
+    onDeleteRequest={() => {
+      if (tags.length) {
+        tags = tags.slice(0, -1);
+      }
+    }}
+  />
+</div>
+```
+
+## Keyboard Navigation
+
+- **Arrow Down/Up**: Cycle through suggestions
+- **Tab**: Accept current suggestion
+- **Enter**: Submit current value
+- **Arrow Right**: Accept suggestion (when cursor at end)
+- **Backspace** (at position 0): Triggers `onDeleteRequest`
+
+## Features
+
+- Case-insensitive and accent-insensitive matching
+- Debounced search (150ms)
+- Ghost text shows suggestion inline
+- Optional spinner during fetch
+- Supports listing all options on empty query with arrow keys

package/dist/components/X/README.md

@@ -0,0 +1,69 @@
+# X
+
+A simple SVG close/dismiss icon (X shape) with configurable stroke width.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `strokeWidth` | `0.5 \| 1 \| 1.5 \| 2 \| 2.5 \| 3 \| 3.5 \| 4` | `2` | Stroke width of the X lines |
+| `class` | `string` | - | CSS classes (default size is `size-6` / 1.5rem) |
+
+## Usage
+
+### Basic Close Icon
+
+```svelte
+<script lang="ts">
+  import { X } from 'stuic';
+</script>
+
+<button>
+  <X />
+</button>
+```
+
+### Different Sizes
+
+```svelte
+<X class="size-4" />
+<X class="size-6" />
+<X class="size-8" />
+```
+
+### Different Stroke Widths
+
+```svelte
+<X strokeWidth={1} />
+<X strokeWidth={2} />
+<X strokeWidth={3} />
+```
+
+### With Custom Color
+
+```svelte
+<X class="text-red-500" />
+<X class="text-gray-400" />
+```
+
+### In a Close Button
+
+```svelte
+<button
+  onclick={handleClose}
+  class="p-2 hover:bg-gray-100 rounded-full"
+>
+  <X strokeWidth={1.5} class="size-5" />
+</button>
+```
+
+### In a Dismissible Element
+
+```svelte
+<div class="flex items-center justify-between p-4 bg-blue-100 rounded">
+  <span>Notification message</span>
+  <button onclick={() => visible = false}>
+    <X class="size-4 text-blue-600 hover:text-blue-800" />
+  </button>
+</div>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marianmeres/stuic",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "files": [
     "dist",
     "!dist/**/*.test.*",