@marianmeres/stuic 3.4.3 → 3.4.4

package/README.md

@@ -1,8 +1,9 @@
 # @marianmeres/stuic
 
-**S**velte **T**ailwind **UI** **C**omponents
+[![NPM](https://img.shields.io/npm/v/@marianmeres/stuic)](https://www.npmjs.com/package/@marianmeres/stuic)
+[![License](https://img.shields.io/npm/l/@marianmeres/stuic)](LICENSE)
 
-An opinionated Svelte 5 component library built with Tailwind CSS v4. Featuring a centralized design token system for consistent theming across all components.
+**S**velte **T**ailwind **UI** **C**omponents — an opinionated Svelte 5 component library built with Tailwind CSS v4. Featuring a centralized design token system for consistent theming across all components.
 
 ## Installation
 
@@ -10,30 +11,28 @@ An opinionated Svelte 5 component library built with Tailwind CSS v4. Featuring
 npm install @marianmeres/stuic
 ```
 
-## Quick Start
+## Usage
 
 ```svelte
 <script>
   import { Button, Modal } from "@marianmeres/stuic";
 
-  let modal;
+  let open = $state(false);
 </script>
 
-<Button onclick={() => modal.open()}>Open Modal</Button>
+<Button onclick={() => open = true}>Open Modal</Button>
 
-<Modal bind:this={modal}>
+<Modal bind:open>
   <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
+STUIC uses a 3-layer CSS variable token system:
 
 ```
-Layer 1: Global Semantic Tokens (--stuic-accent, --stuic-surface, etc.)
+Layer 1: Theme Tokens (--stuic-color-*)
     ↓ (used as fallback defaults)
 Layer 2: Component Tokens (--stuic-button-bg, --stuic-input-accent, etc.)
     ↓ (Tailwind utility class references)
@@ -42,20 +41,16 @@ 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:
+Override theme tokens in your app's CSS:
 
 ```css
-/* app.css */
 :root {
-  /* Change the accent color globally */
-  --stuic-accent: #6366f1; /* Indigo brand color */
-  --stuic-accent-hover: #4f46e5;
-  --stuic-accent-active: #4338ca;
+  --stuic-color-primary: #6366f1;
+  --stuic-color-primary-hover: #4f46e5;
 }
 
-.dark {
-  --stuic-accent: #818cf8;
-  --stuic-accent-hover: #a5b4fc;
+:root.dark {
+  --stuic-color-primary: #818cf8;
 }
 ```
 
@@ -65,232 +60,90 @@ 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;
+  --stuic-button-radius: 9999px;  /* Pill buttons */
+  --stuic-switch-accent: #10b981; /* Green switches */
 }
 ```
 
 ### Instance Overrides
 
-Use class props or inline styles for one-off customizations:
+Use `class` props or inline styles:
 
 ```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?}
+<!-- Or use unstyled mode for full control -->
+<Button unstyled class="my-custom-button">
+  Fully Custom
+</Button>
 ```
 
-- **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`
+### Dark Mode
 
-### Examples
+Add `class="dark"` to the `<html>` element. All tokens switch automatically — no `dark:` Tailwind prefix needed.
 
-```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)
+### Themes
 
-Set variables in your CSS for theming:
+26 pre-built themes available. Default: `stone`.
 
 ```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>
+/* Use a different theme */
+@import "@marianmeres/stuic/dist/themes/css/blue-orange.css";
 ```
 
 ## Components
 
-See `src/lib/README.md` for the full component list and API documentation.
-
 ### Layout & Overlays
-- AppShell, Backdrop, Modal, ModalDialog, Drawer
+AppShell, Backdrop, Modal, ModalDialog, Drawer, Collapsible, SlidingPanels, Nav
 
 ### Forms & Inputs
-- FieldInput, FieldTextarea, FieldSelect, FieldCheckbox, FieldRadios, FieldFile, FieldAssets, FieldOptions, FieldKeyValues, FieldSwitch, Fieldset
+FieldInput, FieldTextarea, FieldSelect, FieldCheckbox, FieldRadios, FieldFile, FieldAssets, FieldOptions, FieldKeyValues, FieldSwitch, FieldInputLocalized, FieldLikeButton, Fieldset
 
 ### Buttons & Controls
-- Button, ButtonGroupRadio, Switch, ListItemButton, X
+Button, ButtonGroupRadio, Switch, TwCheck, ListItemButton, X
 
 ### Feedback & Notifications
-- Notifications, AlertConfirmPrompt, DismissibleMessage, Progress, Spinner, Skeleton
+Notifications, AlertConfirmPrompt, DismissibleMessage, Progress, Spinner, Skeleton
 
 ### Navigation & Menus
-- CommandMenu, DropdownMenu, TabbedMenu, TypeaheadInput, KbdShortcut
+CommandMenu, DropdownMenu, TabbedMenu, TypeaheadInput, KbdShortcut
 
-### Utilities
-- ColorScheme, Thc, SlidingPanels, HoverExpandableWidth, AnimatedElipsis
+### Display & Utility
+Avatar, Carousel, AnimatedElipsis, ThemePreview, ColorScheme, Thc, HoverExpandableWidth, AssetsPreview
 
 ## 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>
+<textarea use:autogrow />
+<input use:validate={() => ({ customValidator: (v) => !v && "Required" })} />
+<input use:trim />
+<button use:tooltip aria-label="Save">Save</button>
+<div use:focusTrap>...</div>
+<div use:fileDropzone={() => ({ onDrop: handleFiles })}>Drop here</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
+`autogrow` · `validate` · `focusTrap` · `autoscroll` · `fileDropzone` · `highlightDragover` · `resizableWidth` · `trim` · `typeahead` · `onSubmitValidityCheck` · `popover` · `tooltip`
 
 ## TypeScript
 
 All components export their Props types:
 
 ```ts
-import type { ButtonProps, ModalProps, ListItemButtonProps } from "@marianmeres/stuic";
+import type { ButtonProps, ModalProps, FieldInputProps } from "@marianmeres/stuic";
 ```
 
+## API
+
+See [API.md](API.md) for complete API documentation including all component props, actions, utilities, icons, and design token reference.
+
 ## 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
+[MIT](LICENSE)

package/dist/components/Input/FieldLikeButton.svelte

@@ -163,13 +163,15 @@
 		{...rest as any}
 		{tabindex}
 	>
-		{#if typeof rendered === "function"}
-			{@render rendered(value)}
-		{:else if rendered}
-			{@html rendered}
-		{:else}
-			 
-		{/if}
+		<span class="block truncate">
+			{#if typeof rendered === "function"}
+				{@render rendered(value)}
+			{:else if rendered}
+				{@html rendered}
+			{:else}
+				&nbsp;
+			{/if}
+		</span>
 	</Button>
 
 	<input

package/dist/components/Input/FieldOptions.svelte

@@ -94,7 +94,7 @@
 			cardinality_of: "of max",
 			cardinality_selected: "selected",
 			submit: "Submit",
-			select_all: "Select results",
+			select_all: "Select all",
 			clear_all: "Clear selected",
 			clear: "Clear",
 			search_placeholder: "Type to search...",
@@ -561,7 +561,7 @@
 		bind:this={modalDialog}
 		preEscapeClose={escape}
 		classDialog="items-start"
-		class={twMerge("w-full max-w-2xl bg-transparent! shadow-none! pointer-events-none")}
+		class={twMerge("w-full max-w-2xl bg-transparent shadow-none pointer-events-none")}
 		ariaLabelledby={id}
 		{noScrollLock}
 	>
@@ -569,7 +569,7 @@
 			<div class="pointer-events-auto">
 				<InputWrap
 					size={renderSize}
-					class={twMerge("m-2 mb-12 shadow-xl", classModalField)}
+					class={twMerge("m-1 sm:m-2 mb-12 shadow-xl", classModalField)}
 					classInputBoxWrap={twMerge(
 						// always look like focused
 						`border border-(--stuic-input-accent)`,

package/dist/components/Input/_internal/InputWrap.svelte

@@ -88,7 +88,6 @@
 	});
 
 	let hasLabel = $derived(isTHCNotEmpty(label) || typeof label === "function");
-
 </script>
 
 {#snippet snippetOrThc({ id, value }: { id: string; value?: SnippetWithId | THC })}
@@ -140,7 +139,7 @@
 
 	<div
 		class={twMerge(
-			"input-box",
+			"input-box min-w-0",
 			hasLabel && labelLeft && labelLeftWidth === "normal" && "flex-3",
 			hasLabel && labelLeft && labelLeftWidth === "wide" && "flex-2",
 			classInputBox
@@ -164,24 +163,14 @@
 		{#if validation && !validation?.valid}
 			<div
 				transition:slide={{ duration: 150 }}
-				class={twMerge(
-					"validation-box",
-					"my-1 text-sm px-2",
-					classValidationBox
-				)}
+				class={twMerge("validation-box", "my-1 text-sm px-2", classValidationBox)}
 			>
 				{validation.message}
 			</div>
 		{/if}
 
 		{#if description}
-			<div
-				class={twMerge(
-					"desc-box",
-					"mx-2 mt-1 text-sm opacity-50",
-					classDescBox
-				)}
-			>
+			<div class={twMerge("desc-box", "mx-2 mt-1 text-sm opacity-50", classDescBox)}>
 				{#if descriptionCollapsible}
 					<Collapsible
 						expanded={descriptionDefaultExpanded}

package/dist/components/ModalDialog/ModalDialog.svelte

@@ -62,7 +62,7 @@
 		setOpener(
 			openerOrEvent instanceof MouseEvent
 				? (openerOrEvent.currentTarget as HTMLElement)
-				: openerOrEvent ?? (document.activeElement as HTMLElement)
+				: (openerOrEvent ?? (document.activeElement as HTMLElement))
 		);
 		// dialog must be rendered in the DOM before it can be opened...
 		waitForNextRepaint().then(() => {
@@ -134,7 +134,10 @@
 		aria-describedby={ariaDescribedby}
 		class={twMerge(
 			"stuic-modal-dialog",
-			"fixed inset-4 m-auto size-auto",
+			"fixed m-auto size-auto",
+			// Note that the default browser styling is (so we are not touching the edge):
+			// max-width/height: calc((100% - 6px) - 2em);
+			"p-0 inset-0",
 			"flex justify-center items-center",
 			"focus:outline-none focus-visible:outline-none",
 			"bg-transparent",

package/package.json

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