@marianmeres/stuic 2.5.0 → 2.6.0

package/dist/actions/popover/README.md

@@ -0,0 +1,145 @@
+# Popover Action
+
+A Svelte action that displays an anchored popover using CSS Anchor Positioning, with fallback to a centered modal when not supported.
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Enable/disable popover |
+| `content` | `THC \| null` | - | Popover content (string, HTML, component, or snippet) |
+| `position` | `PopoverPosition` | `"bottom"` | Placement relative to anchor |
+| `trigger` | `"click" \| "hover"` | `"click"` | Trigger mode |
+| `showDelay` | `number` | `100` | Delay before showing (ms) |
+| `hideDelay` | `number` | `200` | Delay before hiding (ms) |
+| `class` | `string` | - | Custom CSS for popover container |
+| `offset` | `string` | `"0.25rem"` | Margin from anchor (CSS value) |
+| `closeOthers` | `boolean` | `false` | Close other open popovers |
+| `closeOnClickOutside` | `boolean` | `true` | Close on outside click (click trigger) |
+| `closeOnEscape` | `boolean` | `true` | Close on Escape key |
+| `showBackdrop` | `boolean` | `true` | Show backdrop in fallback mode |
+| `forceFallback` | `boolean` | `false` | Force centered modal mode |
+| `onShow` | `() => void` | - | Callback when popover opens |
+| `onHide` | `() => void` | - | Callback when popover closes |
+
+## Positions
+
+```
+top-left       top        top-right
+top-span-left           top-span-right
+
+         left  [anchor]  right
+
+bottom-span-left        bottom-span-right
+bottom-left   bottom    bottom-right
+```
+
+## Usage
+
+### Click Trigger (Default)
+
+```svelte
+<script lang="ts">
+  import { popover } from 'stuic';
+</script>
+
+<button use:popover={() => ({
+  content: "Hello! This is a popover."
+})}>
+  Click Me
+</button>
+```
+
+### Hover Trigger
+
+```svelte
+<button use:popover={() => ({
+  content: "Hover content here",
+  trigger: "hover",
+  position: "top"
+})}>
+  Hover Me
+</button>
+```
+
+### HTML Content
+
+```svelte
+<button use:popover={() => ({
+  content: { html: "<strong>Bold</strong> and <em>italic</em>" },
+  position: "right"
+})}>
+  With HTML
+</button>
+```
+
+### Component Content
+
+```svelte
+<script lang="ts">
+  import MyPopoverContent from './MyPopoverContent.svelte';
+</script>
+
+<button use:popover={() => ({
+  content: { component: MyPopoverContent, props: { data: someData } }
+})}>
+  With Component
+</button>
+```
+
+### Dynamic Content
+
+```svelte
+<script lang="ts">
+  let count = $state(0);
+</script>
+
+<button use:popover={() => ({
+  content: `Count: ${count}`,
+  position: "top"
+})}>
+  Count: {count}
+</button>
+```
+
+### With Callbacks
+
+```svelte
+<button use:popover={() => ({
+  content: "Tracked popover",
+  onShow: () => console.log('Opened'),
+  onHide: () => console.log('Closed')
+})}>
+  Tracked
+</button>
+```
+
+### Close Others
+
+```svelte
+<button use:popover={() => ({
+  content: "Only one at a time",
+  closeOthers: true
+})}>
+  Exclusive
+</button>
+```
+
+## Helper Function
+
+```ts
+import { isPopoverSupported } from 'stuic';
+
+if (isPopoverSupported()) {
+  // CSS Anchor Positioning is available
+} else {
+  // Will use fallback centered modal
+}
+```
+
+## Notes
+
+- Uses CSS Anchor Positioning API when available
+- Falls back to centered modal overlay when not supported
+- For hover mode, popover persists when cursor moves to the popover itself
+- ARIA attributes are automatically managed (`aria-haspopup`, `aria-expanded`, `aria-controls`)

package/dist/actions/tooltip/README.md

@@ -0,0 +1,132 @@
+# Tooltip Action
+
+A Svelte action that displays a tooltip anchored to an element using CSS Anchor Positioning. Only works in browsers that support CSS Anchor Positioning.
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Enable/disable tooltip |
+| `content` | `string \| null` | - | Tooltip text (falls back to `aria-label`) |
+| `position` | `TooltipPosition` | `"top"` | Placement relative to anchor |
+| `class` | `string` | - | Custom CSS for tooltip |
+| `onShow` | `() => void` | - | Callback when tooltip shows |
+| `onHide` | `() => void` | - | Callback when tooltip hides |
+
+## Positions
+
+```
+top-left    top    top-right
+
+   left  [anchor]  right
+
+bottom-left bottom bottom-right
+```
+
+## Usage
+
+### Basic Tooltip
+
+```svelte
+<script lang="ts">
+  import { tooltip } from 'stuic';
+</script>
+
+<button use:tooltip={() => ({ content: "Save your changes" })}>
+  Save
+</button>
+```
+
+### Using aria-label
+
+```svelte
+<!-- Content is taken from aria-label when not specified -->
+<button
+  aria-label="Delete item"
+  use:tooltip
+>
+  Delete
+</button>
+```
+
+### Different Positions
+
+```svelte
+<button use:tooltip={() => ({ content: "Top", position: "top" })}>
+  Top
+</button>
+
+<button use:tooltip={() => ({ content: "Bottom", position: "bottom" })}>
+  Bottom
+</button>
+
+<button use:tooltip={() => ({ content: "Left", position: "left" })}>
+  Left
+</button>
+
+<button use:tooltip={() => ({ content: "Right", position: "right" })}>
+  Right
+</button>
+```
+
+### Custom Styling
+
+```svelte
+<button use:tooltip={() => ({
+  content: "Custom styled tooltip",
+  class: "bg-blue-600 text-white"
+})}>
+  Styled
+</button>
+```
+
+### Conditional Tooltip
+
+```svelte
+<script lang="ts">
+  let showTooltip = $state(true);
+</script>
+
+<button use:tooltip={() => ({
+  content: "Conditional tooltip",
+  enabled: showTooltip
+})}>
+  Conditional
+</button>
+```
+
+### With Callbacks
+
+```svelte
+<button use:tooltip={() => ({
+  content: "Tracked tooltip",
+  onShow: () => console.log('Tooltip shown'),
+  onHide: () => console.log('Tooltip hidden')
+})}>
+  Tracked
+</button>
+```
+
+## Helper Function
+
+```ts
+import { isTooltipSupported } from 'stuic';
+
+if (isTooltipSupported()) {
+  // CSS Anchor Positioning is available
+} else {
+  // Tooltip will not work
+}
+```
+
+## Notes
+
+- Requires CSS Anchor Positioning support (no fallback)
+- Shows on hover or focus with 200ms delay
+- Tooltip persists when hovering over it
+- ARIA attributes are automatically managed (`aria-describedby`, `aria-expanded`)
+- Maximum width is 16rem (256px) by default
+
+## Browser Support
+
+Check [Can I Use - CSS Anchor Positioning](https://caniuse.com/css-anchor-positioning) for current browser support. As of 2025, supported in Chrome 125+ and Edge 125+.

package/dist/components/AlertConfirmPrompt/README.md

@@ -0,0 +1,139 @@
+# AlertConfirmPrompt
+
+A modern, customizable replacement for native browser `alert()`, `confirm()`, and `prompt()` dialogs. Manages a FIFO queue of dialogs with visual variants and flexible content rendering.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `acp` | `AlertConfirmPromptStack` | - | Stack instance managing the dialog queue |
+| `forceAsHtml` | `boolean` | `false` | Render all content as HTML |
+| `class` | `string` | - | CSS classes for the modal dialog |
+| `classWrap` | `string` | - | CSS for outer wrapper |
+| `classIconBox` | `string` | - | CSS for icon container |
+| `classTitle` | `string` | - | CSS for title text |
+| `classContent` | `string` | - | CSS for content area |
+| `classInput` | `string` | - | CSS for prompt input field |
+| `classButton` | `string` | - | CSS for all buttons |
+| `classButtonPrimary` | `string` | - | CSS for OK button |
+| `classButtonCancel` | `string` | - | CSS for Cancel button |
+| `defaultIcons` | `Record<variant, () => string>` | - | Custom icon functions per variant |
+
+## AlertConfirmPromptStack API
+
+### Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `labelOk` | `THC` | `"OK"` | Default OK button label |
+| `labelCancel` | `THC` | `"Cancel"` | Default Cancel button label |
+| `iconFn` | `(() => string) \| boolean` | `true` | Icon function or `true` for default icons |
+
+### Methods
+
+- `alert(options)` - Show an alert dialog
+- `confirm(onOk, options)` - Show a confirm dialog with callback
+- `prompt(onOk, options)` - Show a prompt dialog with input field
+- `shift()` - Remove current dialog from queue
+- `reset()` - Clear all dialogs
+
+### Dialog Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `title` | `THC` | Dialog title |
+| `content` | `THC` | Dialog message/content |
+| `variant` | `"info" \| "success" \| "warn" \| "error"` | Visual style |
+| `value` | `any` | Initial value for prompt |
+| `labelOk` | `THC` | Custom OK button label |
+| `labelCancel` | `THC` | Custom Cancel button label |
+| `labelCustom` | `THC` | Optional third button label |
+| `onCustom` | `(value) => void` | Custom button callback |
+
+## Usage
+
+### Basic Setup
+
+```svelte
+<script lang="ts">
+  import { AlertConfirmPrompt, AlertConfirmPromptStack } from 'stuic';
+
+  const acp = new AlertConfirmPromptStack();
+</script>
+
+<AlertConfirmPrompt {acp} />
+```
+
+### Alert
+
+```svelte
+<script lang="ts">
+  // Simple alert
+  acp.alert({ title: 'Notice', content: 'Operation completed!' });
+
+  // Alert with variant
+  acp.alert({
+    title: 'Error',
+    content: 'Something went wrong',
+    variant: 'error'
+  });
+</script>
+```
+
+### Confirm
+
+```svelte
+<script lang="ts">
+  acp.confirm(
+    () => {
+      console.log('User confirmed!');
+      acp.shift();
+    },
+    {
+      title: 'Delete Item?',
+      content: 'This action cannot be undone.',
+      variant: 'warn'
+    }
+  );
+</script>
+```
+
+### Prompt
+
+```svelte
+<script lang="ts">
+  acp.prompt(
+    (value) => {
+      console.log('User entered:', value);
+      acp.shift();
+    },
+    {
+      title: 'Enter Name',
+      content: 'Please provide your username',
+      value: 'default_user'
+    }
+  );
+</script>
+```
+
+### Promise-based API
+
+```svelte
+<script lang="ts">
+  import { createAlert, createConfirm, createPrompt } from 'stuic';
+
+  const alert = createAlert(acp);
+  const confirm = createConfirm(acp);
+  const prompt = createPrompt(acp);
+
+  // Use like native dialogs
+  await alert('Hello!');
+
+  if (await confirm('Are you sure?')) {
+    const name = await prompt('Enter name:', 'Anonymous');
+    if (name !== null) {
+      console.log('Name:', name);
+    }
+  }
+</script>
+```

package/dist/components/AnimatedElipsis/README.md

@@ -0,0 +1,42 @@
+# AnimatedEllipsis
+
+An animated loading indicator displaying three dots that fade in sequentially to create a pulsing ellipsis effect.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `class` | `string` | - | CSS classes for the wrapper span |
+| `enabled` | `boolean` | `true` | When `false`, all dots are visible (no animation) |
+
+## Usage
+
+### Basic
+
+```svelte
+<script lang="ts">
+  import { AnimatedEllipsis } from 'stuic';
+</script>
+
+<span>Loading<AnimatedEllipsis /></span>
+```
+
+### Controlled Animation
+
+```svelte
+<script lang="ts">
+  import { AnimatedEllipsis } from 'stuic';
+
+  let isLoading = $state(true);
+</script>
+
+<span>
+  Processing<AnimatedEllipsis enabled={isLoading} />
+</span>
+```
+
+### With Custom Styling
+
+```svelte
+<AnimatedEllipsis class="text-blue-500 font-bold" />
+```

package/dist/components/AppShell/README.md

@@ -0,0 +1,99 @@
+# AppShell
+
+A complete application layout shell with flexible regions: rail, header, sidebars, main content area with page header/footer, and footer.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | `"shell"` | Shell element ID |
+| `scrollbarGutter` | `"auto" \| "stable" \| "both-edges"` | `"auto"` | Scrollbar gutter behavior |
+| `pageFlexGrow` | `0-5` | `3` | Flex grow ratio for main page area |
+| `class` | `string` | - | CSS for shell container |
+| `railClass` | `string` | - | CSS for rail (vertical sidebar) |
+| `headerClass` | `string` | - | CSS for top header |
+| `sidebarLeftClass` | `string` | - | CSS for left sidebar |
+| `pageClass` | `string` | - | CSS for page container |
+| `pageHeaderClass` | `string` | - | CSS for page header |
+| `pageMainClass` | `string` | - | CSS for main content |
+| `pageFooterClass` | `string` | - | CSS for page footer |
+| `sidebarRightClass` | `string` | - | CSS for right sidebar |
+| `footerClass` | `string` | - | CSS for bottom footer |
+
+## Snippets
+
+| Snippet | Description |
+|---------|-------------|
+| `rail` | Narrow vertical sidebar (icon navigation) |
+| `header` | Top header bar |
+| `sidebarLeft` | Left sidebar content |
+| `pageHeader` | Header within main page area |
+| `children` | Main page content |
+| `pageFooter` | Footer within main page area |
+| `sidebarRight` | Right sidebar content |
+| `footer` | Bottom footer bar |
+
+## Bindable Elements
+
+All regions expose bindable element refs: `elShell`, `elRail`, `elHeader`, `elSidebarLeft`, `elPage`, `elPageHeader`, `elPageMain`, `elPageFooter`, `elSidebarRight`, `elFooter`.
+
+## Usage
+
+### Basic Layout
+
+```svelte
+<script lang="ts">
+  import { AppShell, appShellSetHtmlBodyHeight } from 'stuic';
+  import { onMount } from 'svelte';
+
+  onMount(appShellSetHtmlBodyHeight);
+</script>
+
+<AppShell>
+  {#snippet header()}
+    <nav class="p-4 border-b">My App</nav>
+  {/snippet}
+
+  {#snippet sidebarLeft()}
+    <aside class="w-64 p-4 border-r">Navigation</aside>
+  {/snippet}
+
+  <main class="p-4">
+    Main content goes here
+  </main>
+
+  {#snippet footer()}
+    <footer class="p-4 border-t">Footer</footer>
+  {/snippet}
+</AppShell>
+```
+
+### With Rail Navigation
+
+```svelte
+<AppShell pageFlexGrow={3}>
+  {#snippet rail()}
+    <div class="w-16 h-full bg-gray-900 flex flex-col items-center py-4">
+      <button>Icon 1</button>
+      <button>Icon 2</button>
+    </div>
+  {/snippet}
+
+  {#snippet sidebarLeft()}
+    <nav class="w-64">Expanded menu</nav>
+  {/snippet}
+
+  Content area
+</AppShell>
+```
+
+## Helper Function
+
+```ts
+import { appShellSetHtmlBodyHeight } from 'stuic';
+import { onMount } from 'svelte';
+
+// Sets body height to 100vh with overflow hidden
+// Returns cleanup function automatically
+onMount(appShellSetHtmlBodyHeight);
+```

package/dist/components/Backdrop/README.md

@@ -0,0 +1,81 @@
+# Backdrop
+
+A semi-transparent overlay with focus trap and body scroll locking. Commonly used as the background layer for modals and drawers.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `visible` | `boolean` | `false` | Controls backdrop visibility (bindable) |
+| `focusTrap` | `boolean \| FocusTrapOptions` | `true` | Enable focus trapping within backdrop |
+| `fadeInDuration` | `number` | `50` | Fade in transition duration (ms) |
+| `fadeOutDuration` | `number` | `150` | Fade out transition duration (ms) |
+| `transitionEnabled` | `boolean` | `true` | Enable/disable transitions |
+| `onEscape` | `() => void` | - | Callback when Escape key is pressed |
+| `noScrollLock` | `boolean` | `false` | Disable body scroll locking |
+| `el` | `HTMLDivElement` | - | Element reference (bindable) |
+| `class` | `string` | - | CSS classes for backdrop |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `open(opener?)` | Show backdrop, optionally track opener element |
+| `close()` | Hide backdrop |
+| `setOpener(el)` | Set element to refocus when closed |
+| `visibility()` | Returns object with `visible` getter |
+
+## Usage
+
+### Basic Backdrop
+
+```svelte
+<script lang="ts">
+  import { Backdrop } from 'stuic';
+
+  let visible = $state(false);
+</script>
+
+<button onclick={() => visible = true}>Open</button>
+
+<Backdrop
+  bind:visible
+  onEscape={() => visible = false}
+  class="bg-black/50"
+>
+  <div class="m-auto p-8 bg-white rounded">
+    Modal content
+    <button onclick={() => visible = false}>Close</button>
+  </div>
+</Backdrop>
+```
+
+### With Component Methods
+
+```svelte
+<script lang="ts">
+  import { Backdrop } from 'stuic';
+
+  let backdrop: Backdrop;
+</script>
+
+<button onclick={(e) => backdrop.open(e)}>Open</button>
+
+<Backdrop
+  bind:this={backdrop}
+  onEscape={() => backdrop.close()}
+  class="bg-black/50"
+>
+  <div class="m-auto p-8 bg-white rounded">
+    Content here
+  </div>
+</Backdrop>
+```
+
+### Without Scroll Lock
+
+```svelte
+<Backdrop bind:visible noScrollLock class="bg-black/25">
+  <div>Overlay content - page still scrollable</div>
+</Backdrop>
+```