@marianmeres/stuic 2.66.0 → 3.0.1

package/README.md

@@ -1,8 +1,296 @@
 # @marianmeres/stuic
 
-*S*velte *T*ailwind _UI_ *C*omponents.
+**S**velte **T**ailwind **UI** **C**omponents
 
-OPINIONATED, UNSTABLE AND IN PROGRESS...
+An opinionated Svelte 5 component library built with Tailwind CSS v4. Featuring a centralized design token system for consistent theming across all components.
 
-Ongoing effort to build reusable Svelte UI primitives as I need them, inspired by many
-other libs -- cherry-picked, combined, adjusted and tweaked to my personal preference and needs.
+## Installation
+
+```bash
+npm install @marianmeres/stuic
+```
+
+## Quick Start
+
+```svelte
+<script>
+  import { Button, Modal } from "@marianmeres/stuic";
+
+  let modal;
+</script>
+
+<Button onclick={() => modal.open()}>Open Modal</Button>
+
+<Modal bind:this={modal}>
+  <p>Hello from Modal!</p>
+</Modal>
+```
+
+## Theming System
+
+STUIC uses a 3-layer CSS variable token system that enables both global theming and per-component customization.
+
+### Architecture
+
+```
+Layer 1: Global Semantic Tokens (--stuic-accent, --stuic-surface, etc.)
+    ↓ (used as fallback defaults)
+Layer 2: Component Tokens (--stuic-button-bg, --stuic-input-accent, etc.)
+    ↓ (Tailwind utility class references)
+Layer 3: Instance Overrides (inline styles, class props)
+```
+
+### Global Theming
+
+Override global tokens in your app's CSS to change the entire library's appearance:
+
+```css
+/* app.css */
+:root {
+  /* Change the accent color globally */
+  --stuic-accent: #6366f1; /* Indigo brand color */
+  --stuic-accent-hover: #4f46e5;
+  --stuic-accent-active: #4338ca;
+}
+
+.dark {
+  --stuic-accent: #818cf8;
+  --stuic-accent-hover: #a5b4fc;
+}
+```
+
+### Per-Component Customization
+
+Override specific component tokens:
+
+```css
+:root {
+  /* Only change switches to green */
+  --stuic-switch-accent: #10b981;
+
+  /* Custom button colors */
+  --stuic-button-bg: #f3f4f6;
+  --stuic-button-bg-hover: #e5e7eb;
+}
+```
+
+### Instance Overrides
+
+Use class props or inline styles for one-off customizations:
+
+```svelte
+<Button class="bg-purple-500 hover:bg-purple-600 text-white">
+  Custom Button
+</Button>
+
+<div style="--stuic-list-item-button-bg-hover: var(--color-blue-500);">
+  <ListItemButton>Blue hover</ListItemButton>
+</div>
+```
+
+## Global Design Tokens
+
+All tokens are defined in `src/lib/theme.css`. See the full reference below.
+
+### Accent Colors
+
+| Token | Light Mode | Dark Mode | Description |
+|-------|------------|-----------|-------------|
+| `--stuic-accent` | `sky-600` | `sky-400` | Primary accent for interactive elements |
+| `--stuic-accent-hover` | `sky-700` | `sky-300` | Accent hover state |
+| `--stuic-accent-active` | `sky-800` | `sky-200` | Accent active/pressed state |
+| `--stuic-accent-destructive` | `red-600` | `red-400` | Destructive/error accent |
+| `--stuic-accent-destructive-hover` | `red-700` | `red-300` | Destructive hover state |
+
+### Surface Colors
+
+| Token | Light Mode | Dark Mode | Description |
+|-------|------------|-----------|-------------|
+| `--stuic-surface` | `white` | `neutral-900` | Base page background |
+| `--stuic-surface-elevated` | `white` | `neutral-800` | Cards, modals, popovers |
+| `--stuic-surface-sunken` | `neutral-100` | `neutral-700` | Input backgrounds, wells |
+| `--stuic-surface-overlay` | `neutral-800` | `neutral-950` | Backdrops, tooltips |
+| `--stuic-surface-interactive` | `neutral-200` | `neutral-600` | Buttons, list items |
+| `--stuic-surface-interactive-hover` | `neutral-500` | `neutral-200` | Interactive hover |
+| `--stuic-surface-interactive-active` | `neutral-600` | `neutral-100` | Interactive active |
+
+### Text Colors
+
+| Token | Light Mode | Dark Mode | Description |
+|-------|------------|-----------|-------------|
+| `--stuic-text` | `black` | `neutral-100` | Primary text |
+| `--stuic-text-muted` | `neutral-600` | `neutral-400` | Secondary/muted text |
+| `--stuic-text-inverse` | `white` | `neutral-900` | Text on dark backgrounds |
+| `--stuic-text-placeholder` | `neutral-400` | `neutral-500` | Placeholder text |
+| `--stuic-text-on-accent` | `white` | `neutral-950` | Text on accent backgrounds |
+| `--stuic-text-destructive` | `red-600` | `red-400` | Error/destructive text |
+
+### Border Colors
+
+| Token | Light Mode | Dark Mode | Description |
+|-------|------------|-----------|-------------|
+| `--stuic-border` | `neutral-300` | `neutral-600` | Default border |
+| `--stuic-border-strong` | `neutral-400` | `neutral-500` | Emphasized border |
+| `--stuic-border-subtle` | `neutral-200` | `neutral-700` | Subtle/light border |
+| `--stuic-border-focus` | `sky-500` | `sky-400` | Focus ring border |
+| `--stuic-border-error` | `red-500` | `red-400` | Error state border |
+
+### Other Tokens
+
+| Token | Default | Description |
+|-------|---------|-------------|
+| `--stuic-ring` | `sky-500` / `sky-400` | Focus ring color |
+| `--stuic-ring-offset` | `2px` | Focus ring offset |
+| `--stuic-ring-width` | `2px` | Focus ring width |
+| `--stuic-radius-sm` | `--radius-sm` | Small border radius |
+| `--stuic-radius` | `--radius-md` | Default border radius |
+| `--stuic-radius-lg` | `--radius-lg` | Large border radius |
+| `--stuic-radius-full` | `9999px` | Fully rounded |
+| `--stuic-transition-fast` | `100ms` | Fast transitions |
+| `--stuic-transition-normal` | `150ms` | Normal transitions |
+| `--stuic-transition-slow` | `300ms` | Slow transitions |
+
+## Component Tokens
+
+Each component defines its own tokens that reference global tokens as defaults:
+
+| Component | Token Prefix | Key Tokens |
+|-----------|--------------|------------|
+| Button | `--stuic-button-*` | `bg`, `text`, `border`, `border-focus` |
+| Switch | `--stuic-switch-*` | `accent` |
+| Input | `--stuic-input-*` | `accent`, `accent-error` |
+| Progress | `--stuic-progress-*` | `bg`, `accent` |
+| ListItemButton | `--stuic-list-item-button-*` | `bg`, `text`, `border`, `bg-hover`, `text-hover`, etc. |
+| ButtonGroupRadio | `--stuic-button-group-*` | `bg`, `text`, `border`, `accent`, `bg-active`, `text-active` |
+| TabbedMenu | `--stuic-tabbed-menu-*` | `tab-bg`, `tab-text`, `tab-bg-active`, `tab-text-active`, `border` |
+| DismissibleMessage | `--stuic-dismissible-message-*` | `bg`, `text`, `border` |
+| Notifications | `--stuic-notification-*` | `bg`, `text`, `border` |
+| Tooltip | `--stuic-tooltip-*` | `bg`, `text` |
+| Popover | `--stuic-popover-*` | `bg`, `text`, `border` |
+| Skeleton | `--stuic-skeleton-*` | `bg`, `bg-highlight`, `duration` |
+
+## CSS Variable Naming Convention
+
+**STRICT REQUIREMENT**: All CSS variables follow this pattern:
+
+```
+--stuic-{component}-{element?}-{property}-{state?}
+```
+
+- **Full component names** (no abbreviations): `list-item-button` not `lib`
+- **State at end**: `--stuic-button-bg-hover` not `--stuic-button-hover-bg`
+- **No `-dark` suffix**: Dark mode defined in `.dark {}` selector
+- **Properties**: `bg`, `text`, `border`, `ring`, `shadow`, `accent`
+- **States**: `hover`, `active`, `focus`, `disabled`, `error`
+
+### Examples
+
+```css
+/* Correct */
+--stuic-button-bg
+--stuic-button-bg-hover
+--stuic-list-item-button-text-active
+--stuic-input-accent-error
+
+/* Incorrect */
+--stuic-btn-bg                    /* abbreviated component name */
+--stuic-button-hover-bg           /* state not at end */
+--stuic-button-bg-dark           /* -dark suffix */
+--color-lib-hover-bg              /* old naming convention */
+```
+
+## Customization Approaches
+
+### 1. CSS Variables (Recommended)
+
+Set variables in your CSS for theming:
+
+```css
+:root {
+  --stuic-accent: #6366f1;
+}
+```
+
+### 2. Class Props
+
+Pass Tailwind classes directly to components:
+
+```svelte
+<Button class="bg-linear-to-r from-purple-500 to-pink-500">
+  Gradient Button
+</Button>
+```
+
+### 3. Unstyled Mode
+
+Use `unstyled` prop to remove all default styling:
+
+```svelte
+<Button unstyled class="my-custom-button-class">
+  Fully Custom
+</Button>
+```
+
+## Components
+
+See `src/lib/README.md` for the full component list and API documentation.
+
+### Layout & Overlays
+- AppShell, Backdrop, Modal, ModalDialog, Drawer
+
+### Forms & Inputs
+- FieldInput, FieldTextarea, FieldSelect, FieldCheckbox, FieldRadios, FieldFile, FieldAssets, FieldOptions, FieldKeyValues, FieldSwitch, Fieldset
+
+### Buttons & Controls
+- Button, ButtonGroupRadio, Switch, ListItemButton, X
+
+### Feedback & Notifications
+- Notifications, AlertConfirmPrompt, DismissibleMessage, Progress, Spinner, Skeleton
+
+### Navigation & Menus
+- CommandMenu, DropdownMenu, TabbedMenu, TypeaheadInput, KbdShortcut
+
+### Utilities
+- ColorScheme, Thc, SlidingPanels, HoverExpandableWidth, AnimatedElipsis
+
+## Actions
+
+```svelte
+<input use:autogrow use:validate={{ required: true }} />
+<button use:tooltip aria-label="Tooltip text">Hover me</button>
+<div use:popover={{ content: 'Popover content' }}>Anchor</div>
+```
+
+- `autogrow` - Auto-expand textarea height
+- `validate` - Form validation with custom validators
+- `focusTrap` - Trap focus within element
+- `tooltip` - Tooltip from aria-label
+- `popover` - Anchored popover
+- `fileDropzone` - Drag-and-drop file upload
+- `highlightDragover` - Visual feedback for drag operations
+
+## TypeScript
+
+All components export their Props types:
+
+```ts
+import type { ButtonProps, ModalProps, ListItemButtonProps } from "@marianmeres/stuic";
+```
+
+## Requirements
+
+- Svelte 5 (runes mode)
+- Tailwind CSS v4
+- Modern browser with CSS custom properties support
+
+## Breaking Changes in v2
+
+- All CSS variables renamed from `--color-*` to `--stuic-*` prefix
+- ListItemButton variables renamed from `--color-lib-*` to `--stuic-list-item-button-*`
+- State naming changed from `--*-hover-bg` to `--*-bg-hover` (state at end)
+- Removed `-dark` suffix from variables (use `.dark {}` selector instead)
+- Legacy variable names preserved as aliases for backwards compatibility
+
+## License
+
+MIT

package/dist/README.md

@@ -53,6 +53,7 @@ npm install @marianmeres/stuic
 - **Button** - Styled button with variants (primary, secondary, ghost)
 - **ButtonGroupRadio** - Radio-style button group
 - **Switch** - Toggle switch component
+- **ListItemButton** - Versatile button for list contexts (dropdowns, menus)
 - **X** - Close/dismiss button icon
 
 ### Feedback & Notifications
@@ -62,10 +63,13 @@ npm install @marianmeres/stuic
 - **DismissibleMessage** - Closable message banner
 - **Progress** - Progress bar indicator
 - **Spinner** - Loading spinner animation
+- **Skeleton** - Loading placeholder with shimmer animation
 
-### Navigation & Interaction
+### Navigation & Menus
 
 - **CommandMenu** - Keyboard-driven command palette
+- **DropdownMenu** - Anchored dropdown menu with keyboard navigation
+- **TabbedMenu** - Tab-based navigation component
 - **TypeaheadInput** - Autocomplete text input
 - **KbdShortcut** - Keyboard shortcut display
 
@@ -76,17 +80,22 @@ npm install @marianmeres/stuic
 - **SlidingPanels** - Animated panel transitions
 - **HoverExpandableWidth** - Expand content on hover
 - **AnimatedElipsis** - Animated loading dots
+- **Collapsible** - Expandable/collapsible content sections
+- **AssetsPreview** - Preview uploaded files/images
+- **Circle** - Circular container/badge component
 
 ## Actions (use:action)
 
 ```svelte
 <input use:autogrow use:validate={{ required: true }} />
+<button use:tooltip aria-label="Tooltip text">Hover me</button>
 ```
 
 - **autogrow** - Auto-expand textarea height
 - **validate** - Form validation with custom validators
 - **focusTrap** - Trap focus within element
-- **tooltip** - Tooltip from aria-label
+- **tooltip** - Tooltip from aria-label (CSS anchor positioning)
+- **popover** - Anchored popover (CSS anchor positioning)
 - **fileDropzone** - Drag-and-drop file upload
 - **highlightDragover** - Visual feedback for drag operations
 
@@ -104,30 +113,44 @@ import { debounce, throttle, twMerge, localStorageState } from "@marianmeres/stu
 - **getId** - Generate unique IDs
 - **EventEmitter** - Typed event emitter
 
-## Theming
-
-Components use CSS custom properties for theming. Override in your CSS:
-
-```css
-:root {
-	--color-button-bg: theme("colors.blue.500");
-	--color-button-text: white;
-	--color-input-accent: theme("colors.blue.500");
-	/* ... */
-}
-```
-
-See `src/lib/theme.css` for all available custom properties.
-
 ## TypeScript
 
 All components export their Props types:
 
 ```ts
-import type { ButtonProps, ModalProps } from "@marianmeres/stuic";
+import type { ButtonProps, ModalProps, ListItemButtonProps } from "@marianmeres/stuic";
 
 const buttonConfig: Partial<ButtonProps> = {
 	variant: "primary",
 	size: "lg",
 };
 ```
+
+## Component Token Reference
+
+Each component with customizable styling defines CSS custom properties:
+
+| Component | Prefix | Key Properties |
+|-----------|--------|----------------|
+| Button | `--stuic-button-*` | `bg`, `text`, `border`, `border-focus` |
+| Switch | `--stuic-switch-*` | `accent` |
+| Input | `--stuic-input-*` | `accent`, `accent-error` |
+| Progress | `--stuic-progress-*` | `bg`, `accent` |
+| Skeleton | `--stuic-skeleton-*` | `bg`, `bg-highlight`, `duration` |
+| ListItemButton | `--stuic-list-item-button-*` | `bg`, `text`, `border`, plus `-hover`, `-active`, `-focus` states |
+| ButtonGroupRadio | `--stuic-button-group-*` | `bg`, `text`, `border`, `accent`, `bg-active`, `text-active` |
+| TabbedMenu | `--stuic-tabbed-menu-*` | `tab-bg`, `tab-text`, `tab-bg-active`, `tab-text-active`, `border` |
+| DismissibleMessage | `--stuic-dismissible-message-*` | `bg`, `text`, `border` |
+| Notifications | `--stuic-notification-*` | `bg`, `text`, `border` |
+| Tooltip | `--stuic-tooltip-*` | `bg`, `text` |
+| Popover | `--stuic-popover-*` | `bg`, `text`, `border` |
+
+### CSS Variable Naming Convention
+
+**Pattern:** `--stuic-{component}-{element?}-{property}-{state?}`
+
+- Full component names (no abbreviations)
+- State at end: `--stuic-button-bg-hover`
+- No `-dark` suffix (use `.dark {}` selector)
+
+See `AGENTS.md` for complete development guidelines.

package/dist/actions/index.d.ts

@@ -8,4 +8,5 @@ export * from "./popover/popover.svelte.js";
 export * from "./resizable-width.svelte.js";
 export * from "./tooltip/tooltip.svelte.js";
 export * from "./trim.svelte.js";
+export * from "./typeahead.svelte.js";
 export * from "./validate.svelte.js";

package/dist/actions/index.js

@@ -8,4 +8,5 @@ export * from "./popover/popover.svelte.js";
 export * from "./resizable-width.svelte.js";
 export * from "./tooltip/tooltip.svelte.js";
 export * from "./trim.svelte.js";
+export * from "./typeahead.svelte.js";
 export * from "./validate.svelte.js";

package/dist/actions/popover/README.md

@@ -137,6 +137,25 @@ if (isPopoverSupported()) {
 }
 ```
 
+## CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--stuic-popover-bg` | `--stuic-surface-elevated` | Popover background |
+| `--stuic-popover-text` | `--stuic-text` | Popover text color |
+| `--stuic-popover-border` | `--stuic-border-subtle` | Popover border color |
+
+### Example Override
+
+```css
+:root {
+  --stuic-popover-bg: var(--color-slate-50);
+  --stuic-popover-border: var(--color-slate-300);
+}
+```
+
+**Note:** Popover CSS variables may not work with inline style props because popovers are created outside the anchor's DOM tree. Set them in your global CSS.
+
 ## Notes
 
 - Uses CSS Anchor Positioning API when available

package/dist/actions/popover/index.css

@@ -1,12 +1,9 @@
-/* prettier-ignore */
-@theme inline {
-	/* style props will not work as with regular components, because popovers are created outside of the anchor dom tree */
-	--color-popover-bg: var(--color-popover-bg, var(--color-white));
-	--color-popover-bg-dark: var(--color-popover-bg-dark, var(--color-neutral-800));
-	--color-popover-text: var(--color-popover-text, var(--color-neutral-900));
-	--color-popover-text-dark: var(--color-popover-text-dark, var(--color-neutral-100));
-	--color-popover-border: var(--color-popover-border, var(--color-neutral-200));
-	--color-popover-border-dark: var(--color-popover-border-dark, var(--color-neutral-700));
+/* Popover component tokens */
+/* Note: style props will not work as with regular components, because popovers are created outside of the anchor DOM tree */
+:root {
+	--stuic-popover-bg: var(--stuic-color-surface);
+	--stuic-popover-text: var(--stuic-color-foreground);
+	--stuic-popover-border: var(--stuic-color-border);
 }
 
 /* Base popover styles */

package/dist/actions/popover/popover.svelte.js

@@ -107,9 +107,9 @@ const POSITION_MAP = {
     right: "right",
 };
 const _classPopover = `
-	bg-popover-bg dark:bg-popover-bg-dark text-popover-text dark:text-popover-text-dark
+	bg-(--stuic-popover-bg) text-(--stuic-popover-text)
 	shadow-lg rounded-md
-	border border-popover-border dark:border-popover-border-dark
+	border border-(--stuic-popover-border)
 	z-50
 `;
 const _classBackdrop = `

package/dist/actions/tooltip/README.md

@@ -127,6 +127,24 @@ if (isTooltipSupported()) {
 - ARIA attributes are automatically managed (`aria-describedby`, `aria-expanded`)
 - Maximum width is 16rem (256px) by default
 
+## CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--stuic-tooltip-bg` | `--stuic-surface-overlay` | Tooltip background |
+| `--stuic-tooltip-text` | `--stuic-text-inverse` | Tooltip text color |
+
+### Example Override
+
+```css
+:root {
+  --stuic-tooltip-bg: var(--color-indigo-900);
+  --stuic-tooltip-text: var(--color-indigo-100);
+}
+```
+
+**Note:** Tooltip CSS variables may not work with inline style props because tooltips are created outside the anchor's DOM tree. Set them in your global CSS.
+
 ## 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/actions/tooltip/index.css

@@ -1,11 +1,8 @@
-/* prettier-ignore */
-@theme inline {
-    /* style props will not work as with regular components, because tooltips are created outside of the anchor dom tree */
-    --color-tooltip-bg: var(--color-tooltip-bg, var(--color-neutral-800));
-    --color-tooltip-bg-dark: var(--color-tooltip-bg-dark, var(--color-neutral-300));
-    --color-tooltip-text: var(--color-tooltip-text, var(--color-white));
-    --color-tooltip-text-dark: var(--color-tooltip-text-dark, var(--color-black));
-
+/* Tooltip component tokens */
+/* Note: style props will not work as with regular components, because tooltips are created outside of the anchor DOM tree */
+:root {
+	--stuic-tooltip-bg: var(--color-black);
+	--stuic-tooltip-text: var(--color-white);
 }
 
 .stuic-tooltip {

package/dist/actions/tooltip/tooltip.svelte.js

@@ -28,7 +28,7 @@ export function isTooltipSupported() {
         CSS.supports("position-try-fallbacks", "top"));
 }
 const _classTooltip = `
-    bg-tooltip-bg dark:bg-tooltip-bg-dark text-tooltip-text dark:text-tooltip-text-dark
+    bg-(--stuic-tooltip-bg) text-(--stuic-tooltip-text)
     text-sm tracking-tight rounded my-1
     px-2.5 py-1.5
     max-w-64

package/dist/actions/typeahead.svelte.d.ts

@@ -0,0 +1,53 @@
+import type { Item } from "@marianmeres/item-collection";
+/**
+ * Configuration options for the typeahead action.
+ */
+export interface TypeaheadOptions<T extends Item = Item> {
+    /** Whether the typeahead functionality is enabled (default: true) */
+    enabled?: boolean;
+    /** Async function to fetch options based on the current query (required when enabled) */
+    getOptions?: (query: string, current: T[]) => Promise<T[]>;
+    /** Custom function to render the label for an item */
+    renderOptionLabel?: (item: T) => string;
+    /** Property name to use as item ID (default: "id") */
+    itemIdPropName?: string;
+    /** Debounce delay in milliseconds (default: 150) */
+    debounceMs?: number;
+    /** Callback when value is submitted (Enter, Tab, blur) */
+    onSubmit?: (value: string) => void;
+    /** Callback when Backspace is pressed at cursor position 0 */
+    onDeleteRequest?: () => void;
+    /** Callback when fetching state changes */
+    onFetchingChange?: (isFetching: boolean) => void;
+    /** Disable showing all options when arrow keys pressed on empty input */
+    noListAllOnEmptyQ?: boolean;
+    /** Hint text appended to the visible suggestion (default: " [tab]") */
+    appendHint?: string;
+    /** CSS class for the ghost input element */
+    classGhost?: string;
+    /** Callback that provides a reset function to clear ghost text programmatically */
+    onResetGhost?: (resetFn: () => void) => void;
+}
+/**
+ * A Svelte action that adds typeahead/autocomplete functionality to an input element.
+ *
+ * Creates a "ghost input" behind the main input to show suggestions. Supports keyboard
+ * navigation with ArrowUp/Down, accepts suggestions with Tab/Enter/ArrowRight, and
+ * handles accent-insensitive matching.
+ *
+ * @param el - The input element to add typeahead to
+ * @param fn - Function returning configuration options
+ *
+ * @example
+ * ```svelte
+ * <input
+ *   bind:value
+ *   use:typeahead={() => ({
+ *     getOptions: async (q) => fetchSuggestions(q),
+ *     renderOptionLabel: (item) => item.name,
+ *     onSubmit: (v) => console.log('Selected:', v),
+ *   })}
+ * />
+ * ```
+ */
+export declare function typeahead<T extends Item = Item>(el: HTMLInputElement, fn?: () => TypeaheadOptions<T>): void;