@marianmeres/stuic 2.3.2 → 2.5.0

package/README.md

@@ -6,4 +6,3 @@ OPINIONATED, UNSTABLE AND IN PROGRESS...
 
 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.
-

package/dist/README.md

@@ -12,21 +12,22 @@ npm install @marianmeres/stuic
 
 ```svelte
 <script>
-  import { Button, Modal } from '@marianmeres/stuic';
+	import { Button, Modal } from "@marianmeres/stuic";
 
-  let modal;
+	let modal;
 </script>
 
 <Button onclick={() => modal.open()}>Open Modal</Button>
 
 <Modal bind:this={modal}>
-  <p>Hello from Modal!</p>
+	<p>Hello from Modal!</p>
 </Modal>
 ```
 
 ## Components
 
 ### Layout & Overlays
+
 - **AppShell** - Application layout wrapper with header, sidebar, main content
 - **Backdrop** - Fullscreen overlay with transitions
 - **Modal** - Dialog overlay with focus trap and scroll lock
@@ -34,6 +35,7 @@ npm install @marianmeres/stuic
 - **Drawer** - Slide-in panel from screen edges
 
 ### Forms & Inputs
+
 - **FieldInput** - Text input with label, validation, description
 - **FieldTextarea** - Multiline text input with autogrow support
 - **FieldSelect** - Native select dropdown
@@ -46,12 +48,14 @@ npm install @marianmeres/stuic
 - **Fieldset** - Group of form fields with legend
 
 ### Buttons & Controls
+
 - **Button** - Styled button with variants (primary, secondary, ghost)
 - **ButtonGroupRadio** - Radio-style button group
 - **Switch** - Toggle switch component
 - **X** - Close/dismiss button icon
 
 ### Feedback & Notifications
+
 - **Notifications** - Toast notification system
 - **AlertConfirmPrompt** - Modal dialogs for alerts, confirms, and prompts
 - **DismissibleMessage** - Closable message banner
@@ -59,11 +63,13 @@ npm install @marianmeres/stuic
 - **Spinner** - Loading spinner animation
 
 ### Navigation & Interaction
+
 - **CommandMenu** - Keyboard-driven command palette
 - **TypeaheadInput** - Autocomplete text input
 - **KbdShortcut** - Keyboard shortcut display
 
 ### Utilities
+
 - **ColorScheme** - Dark/light mode management
 - **Thc** - Render text, HTML, or component dynamically
 - **SlidingPanels** - Animated panel transitions
@@ -86,7 +92,7 @@ npm install @marianmeres/stuic
 ## Utilities
 
 ```ts
-import { debounce, throttle, twMerge, localStorageState } from '@marianmeres/stuic';
+import { debounce, throttle, twMerge, localStorageState } from "@marianmeres/stuic";
 ```
 
 - **debounce/throttle** - Function rate limiting
@@ -103,10 +109,10 @@ 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');
-  /* ... */
+	--color-button-bg: theme("colors.blue.500");
+	--color-button-text: white;
+	--color-input-accent: theme("colors.blue.500");
+	/* ... */
 }
 ```
 
@@ -117,10 +123,10 @@ See `src/lib/theme.css` for all available custom properties.
 All components export their Props types:
 
 ```ts
-import type { ButtonProps, ModalProps } from '@marianmeres/stuic';
+import type { ButtonProps, ModalProps } from "@marianmeres/stuic";
 
 const buttonConfig: Partial<ButtonProps> = {
-  variant: 'primary',
-  size: 'lg',
+	variant: "primary",
+	size: "lg",
 };
 ```

package/dist/actions/autogrow.svelte.js

@@ -25,10 +25,10 @@
 export function autogrow(el, fn) {
     let lastValue = el.value;
     $effect(() => {
-        let { enabled = true, max = 250, immediate = true, value } = fn?.() || {};
+        const { enabled = true, max = 250, immediate = true, value } = fn?.() || {};
         if (!enabled)
             return;
-        function set_height(_e) {
+        function set_height() {
             // console.log(123, el.value);
             if (enabled) {
                 el.style.height = "auto"; // Reset height to auto to correctly calculate scrollHeight
@@ -38,14 +38,14 @@ export function autogrow(el, fn) {
         // eventlistener strategy (we're not passing value)
         if (value === undefined) {
             if (immediate)
-                set_height(null);
+                set_height();
             el.addEventListener("input", set_height);
             el.addEventListener("blur", set_height);
         }
         // strategy with provided value
         else {
             if (value !== lastValue) {
-                set_height(null);
+                set_height();
                 lastValue = value;
             }
         }

package/dist/actions/autoscroll.d.ts

@@ -12,8 +12,8 @@ interface StoreLike<T> extends StoreReadable<T> {
  * Options for the autoscroll action.
  */
 export type AutoscrollOptions = ScrollOptions & {
-    dependencies?: StoreReadable<any>[];
-    logger?: (...args: any[]) => void;
+    dependencies?: StoreReadable<unknown>[];
+    logger?: (...args: unknown[]) => void;
     newScrollableContentSignal?: StoreLike<boolean>;
     shouldScrollThresholdPx?: number;
     startScrollTimeout?: number;

package/dist/actions/autoscroll.js

@@ -43,16 +43,19 @@ export function autoscroll(node, options = {
     startScrollTimeout: DEFAULTS.startScrollTimeout,
 }) {
     // use "smooth" by default
-    options.behavior ??= 'smooth';
+    options.behavior ??= "smooth";
     options.shouldScrollThresholdPx ??= DEFAULTS.shouldScrollThresholdPx;
     options.startScrollTimeout ??= DEFAULTS.startScrollTimeout;
     const { behavior, shouldScrollThresholdPx, dependencies, logger, newScrollableContentSignal, startScrollTimeout, } = options || {};
     let origScrollHeight = 0;
-    const log = (...args) => typeof logger === 'function' && logger.apply(null, [...args]);
+    const log = (...args) => {
+        if (typeof logger === "function")
+            logger.apply(null, [...args]);
+    };
     const shouldScroll = () => {
         const { scrollTop, clientHeight } = node;
         const result = origScrollHeight - scrollTop - clientHeight < shouldScrollThresholdPx;
-        log('shouldScroll?', result, { scrollTop, origScrollHeight, clientHeight });
+        log("shouldScroll?", result, { scrollTop, origScrollHeight, clientHeight });
         return result;
     };
     const scroll = () => {
@@ -62,17 +65,23 @@ export function autoscroll(node, options = {
     };
     // for when children change sizes
     const resizeObserver = new ResizeObserver(() => {
-        log('observed resize...');
-        shouldScroll() && scroll();
+        log("observed resize...");
+        if (shouldScroll())
+            scroll();
     });
     // for when children
     const mutationObserver = new MutationObserver(() => {
-        log('observed mutation...');
-        shouldScroll() ? scroll() : newScrollableContentSignal?.set(true);
+        log("observed mutation...");
+        if (shouldScroll()) {
+            scroll();
+        }
+        else {
+            newScrollableContentSignal?.set(true);
+        }
         origScrollHeight = node.scrollHeight;
     });
     const unsubs = dependencies?.map((dep) => dep.subscribe((v) => {
-        log('dependency update...', v);
+        log("dependency update...", v);
         setTimeout(scroll, startScrollTimeout);
     })) ?? [];
     // observe size of all children

package/dist/actions/file-dropzone.svelte.d.ts

@@ -5,7 +5,7 @@ interface FileDropzoneOptions {
     enabled?: boolean;
     inputEl: HTMLInputElement;
     allowClick?: boolean;
-    processFiles?: (files: FileList | null, wasDrop?: boolean) => any | Promise<any>;
+    processFiles?: (files: FileList | null, wasDrop?: boolean) => void | Promise<void>;
 }
 /**
  * A Svelte action that turns any element into a file drop zone.

package/dist/actions/file-dropzone.svelte.js

@@ -40,7 +40,7 @@
  */
 export function fileDropzone(el, fn) {
     $effect(() => {
-        let { enabled = true, allowClick = true, inputEl, processFiles, } = fn?.() || {};
+        const { enabled = true, allowClick = true, inputEl, processFiles, } = fn?.() || {};
         if (!enabled)
             return;
         if (!inputEl) {

package/dist/actions/focus-trap.js

@@ -32,34 +32,36 @@ const defaults = { enabled: true, autoFocusFirst: true };
  * ```
  */
 export function focusTrap(node, options = {}) {
-    let { enabled, autoFocusFirst } = { ...defaults, ...(options || {}) };
+    let enabled;
+    const { enabled: _enabled, autoFocusFirst } = { ...defaults, ...(options || {}) };
+    enabled = _enabled ?? true;
     const focusableSelectors = [
-        '[contentEditable=true]',
+        "[contentEditable=true]",
         //
-        'button:not([disabled])',
-        'input:not([disabled])',
-        'select:not([disabled])',
-        'textarea:not([disabled])',
+        "button:not([disabled])",
+        "input:not([disabled])",
+        "select:not([disabled])",
+        "textarea:not([disabled])",
         //
-        'a[href]',
-        'area[href]',
-        'details',
-        'iframe',
+        "a[href]",
+        "area[href]",
+        "details",
+        "iframe",
         // see more below on tabindexes
         '[tabindex]:not([tabindex^="-"])',
-    ].join(',');
+    ].join(",");
     let first;
     let last;
     // When the first element is selected, shift+tab pressed, jump to the last selectable item.
     function onFirstElemKeydown(e) {
-        if (e.shiftKey && e.code === 'Tab') {
+        if (e.shiftKey && e.code === "Tab") {
             e.preventDefault();
             last.focus();
         }
     }
     // When the last item selected, tab pressed, jump to the first selectable item.
     function onLastElemKeydown(e) {
-        if (!e.shiftKey && e.code === 'Tab') {
+        if (!e.shiftKey && e.code === "Tab") {
             e.preventDefault();
             first.focus();
         }
@@ -68,15 +70,15 @@ export function focusTrap(node, options = {}) {
         if (enabled === false)
             return;
         let maxTabindex = 0;
-        let focusable = [...node.querySelectorAll(focusableSelectors)]
+        const focusable = [...node.querySelectorAll(focusableSelectors)]
             // filter negative tabindexes (afaik there is no :not([disabled] OR [tabindex^="-"]))
             .filter((e) => {
             // reusing loop for a side job here... see sort below
-            maxTabindex = Math.max(maxTabindex, parseInt(e.getAttribute('tabindex') || '0'));
+            maxTabindex = Math.max(maxTabindex, parseInt(e.getAttribute("tabindex") || "0"));
             //
-            if (e.getAttribute('disabled') === '')
+            if (e.getAttribute("disabled") === "")
                 return false;
-            if ((e.getAttribute('tabindex') || '').startsWith('-'))
+            if ((e.getAttribute("tabindex") || "").startsWith("-"))
                 return false;
             return true;
         })
@@ -84,8 +86,8 @@ export function focusTrap(node, options = {}) {
             // but must increase zero to max + 1 first, because browsers focus zeros as last...
             // https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex
             .sort((e1, e2) => {
-            const a = parseInt(e1.getAttribute('tabindex') || '0') || maxTabindex + 1;
-            const b = parseInt(e2.getAttribute('tabindex') || '0') || maxTabindex + 1;
+            const a = parseInt(e1.getAttribute("tabindex") || "0") || maxTabindex + 1;
+            const b = parseInt(e2.getAttribute("tabindex") || "0") || maxTabindex + 1;
             return a - b;
         });
         if (focusable.length) {
@@ -95,14 +97,16 @@ export function focusTrap(node, options = {}) {
             if (!fromObserver && autoFocusFirst)
                 first.focus();
             // Listen for keydown on first & last element
-            first.addEventListener('keydown', onFirstElemKeydown);
-            last.addEventListener('keydown', onLastElemKeydown);
+            first.addEventListener("keydown", onFirstElemKeydown);
+            last.addEventListener("keydown", onLastElemKeydown);
         }
     };
     queryElements(false);
     function cleanup() {
-        first && first.removeEventListener('keydown', onFirstElemKeydown);
-        last && last.removeEventListener('keydown', onLastElemKeydown);
+        if (first)
+            first.removeEventListener("keydown", onFirstElemKeydown);
+        if (last)
+            last.removeEventListener("keydown", onLastElemKeydown);
     }
     // When children of node are changed (added or removed)
     const observer = new MutationObserver((mutations, observer) => {
@@ -117,7 +121,12 @@ export function focusTrap(node, options = {}) {
     return {
         update(options = {}) {
             enabled = !!options?.enabled;
-            enabled ? queryElements(false) : cleanup();
+            if (enabled) {
+                queryElements(false);
+            }
+            else {
+                cleanup();
+            }
         },
         destroy() {
             cleanup();

package/dist/actions/highlight-dragover.svelte.js

@@ -32,15 +32,16 @@ export function highlightDragover(el, fn) {
     // 	// Trigger change event for any listeners
     // 	el.dispatchEvent(new Event("change"));
     // }
-    function prevent(e) {
-        e.preventDefault();
-        // e.stopPropagation();
-    }
+    // function prevent(e: DragEvent) {
+    // 	e.preventDefault();
+    // 	// e.stopPropagation();
+    // }
     const HIGH = ["dragenter", "dragover"];
     const UNHIGH = ["dragleave", "drop"];
     // const ALL = [...HIGH, ...UNHIGH];
     $effect(() => {
-        let { classes = ["dragover"], enabled = true } = fn?.() || {};
+        const { enabled = true } = fn?.() || {};
+        let { classes = ["dragover"] } = fn?.() || {};
         if (!enabled)
             return;
         if (!Array.isArray(classes))

package/dist/actions/index.d.ts

@@ -4,6 +4,7 @@ export * from "./file-dropzone.svelte.js";
 export * from "./focus-trap.js";
 export * from "./highlight-dragover.svelte.js";
 export * from "./on-submit-validity-check.svelte.js";
+export * from "./popover/popover.svelte.js";
 export * from "./resizable-width.svelte.js";
 export * from "./tooltip/tooltip.svelte.js";
 export * from "./trim.svelte.js";

package/dist/actions/index.js

@@ -4,6 +4,7 @@ export * from "./file-dropzone.svelte.js";
 export * from "./focus-trap.js";
 export * from "./highlight-dragover.svelte.js";
 export * from "./on-submit-validity-check.svelte.js";
+export * from "./popover/popover.svelte.js";
 export * from "./resizable-width.svelte.js";
 export * from "./tooltip/tooltip.svelte.js";
 export * from "./trim.svelte.js";

package/dist/actions/on-submit-validity-check.svelte.js

@@ -47,9 +47,9 @@ export function onSubmitValidityCheck(node) {
         e.preventDefault();
         // this will disable all other onsubmit listeners...
         e.stopImmediatePropagation();
-        let invalid = [];
+        const invalid = [];
         for (let i = 0; i < node.elements?.length; i++) {
-            let el = node.elements[i];
+            const el = node.elements[i];
             if (typeof el.checkValidity === "function") {
                 // hm... radios are tricky, as triggering change automatically checks the last
                 // input (last radio input), which is not desired

package/dist/actions/popover/PopoverContent.svelte

@@ -0,0 +1,15 @@
+<script lang="ts" module>
+	import type { THC } from "../../components/Thc/Thc.svelte";
+
+	export interface Props {
+		thc: THC;
+	}
+</script>
+
+<script lang="ts">
+	import Thc from "../../components/Thc/Thc.svelte";
+
+	let { thc }: Props = $props();
+</script>
+
+<Thc {thc} />

package/dist/actions/popover/PopoverContent.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { THC } from "../../components/Thc/Thc.svelte";
+export interface Props {
+    thc: THC;
+}
+declare const PopoverContent: import("svelte").Component<Props, {}, "">;
+type PopoverContent = ReturnType<typeof PopoverContent>;
+export default PopoverContent;

package/dist/actions/popover/index.css

@@ -0,0 +1,78 @@
+/* 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));
+}
+
+/* Base popover styles */
+.stuic-popover,
+.stuic-popover-fallback {
+	display: none;
+	opacity: 0;
+	transition-property: opacity;
+}
+
+/* Backdrop for fallback mode */
+.stuic-popover-backdrop {
+	opacity: 0;
+	transition-property: opacity;
+	&.pop-visible {
+		opacity: 1;
+	}
+}
+
+/* Define fallback positions for auto-repositioning when popover overflows viewport */
+/* span-right/span-left keep popover "above/below" but shift horizontally */
+@position-try --pop-top-span-right {
+	position-area: top span-right; /* above, aligned to anchor's left edge */
+}
+@position-try --pop-top-span-left {
+	position-area: top span-left; /* above, aligned to anchor's right edge */
+}
+@position-try --pop-bottom-span-right {
+	position-area: bottom span-right;
+}
+@position-try --pop-bottom-span-left {
+	position-area: bottom span-left;
+}
+@position-try --pop-left {
+	position-area: left;
+}
+@position-try --pop-right {
+	position-area: right;
+}
+
+/* CSS Anchor Positioning supported mode */
+@supports (anchor-name: --anchor) {
+	.stuic-popover {
+		/* position-area is set via inline style based on position param */
+		/* fallbacks ensure popover stays within viewport */
+		position-try-fallbacks:
+			--pop-top-span-right, --pop-top-span-left, flip-block, --pop-bottom-span-right,
+			--pop-bottom-span-left, --pop-left, --pop-right;
+
+		&.pop-block {
+			display: block;
+			opacity: 0;
+			&.pop-visible {
+				opacity: 1;
+			}
+		}
+	}
+}
+
+/* Fallback mode (centered modal) */
+.stuic-popover-fallback {
+	&.pop-block {
+		display: block;
+		opacity: 0;
+		&.pop-visible {
+			opacity: 1;
+		}
+	}
+}

package/dist/actions/popover/index.d.ts

@@ -0,0 +1 @@
+export * from "./popover.svelte.js";

package/dist/actions/popover/index.js

@@ -0,0 +1 @@
+export * from "./popover.svelte.js";

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

@@ -0,0 +1,112 @@
+import type { THC } from "../../components/Thc/Thc.svelte";
+import "./index.css";
+/**
+ * Checks if the browser supports CSS Anchor Positioning for popovers.
+ *
+ * Tests for support of `anchor-name`, `position-area`, `position-try`,
+ * and `position-try-fallbacks` CSS properties.
+ *
+ * @returns `true` if CSS Anchor Positioning is fully supported
+ *
+ * @example
+ * ```ts
+ * if (isPopoverSupported()) {
+ *   // Use native anchor positioning
+ * } else {
+ *   // Fall back to centered modal
+ * }
+ * ```
+ */
+export declare function isPopoverSupported(): boolean;
+/**
+ * Valid positions for popover placement relative to the anchor element.
+ */
+export type PopoverPosition = "top" | "top-left" | "top-right" | "top-span-left" | "top-span-right" | "bottom" | "bottom-left" | "bottom-right" | "bottom-span-left" | "bottom-span-right" | "left" | "right";
+/**
+ * Trigger mode for the popover.
+ */
+export type PopoverTrigger = "click" | "hover";
+/**
+ * Options for the popover action.
+ */
+export interface PopoverOptions {
+    /** Whether the popover is enabled */
+    enabled?: boolean;
+    /** Content to display (THC format: string, {text}, {html}, {component, props}, {snippet}, or Snippet) */
+    content?: THC | null;
+    /** Preferred position relative to anchor */
+    position?: PopoverPosition;
+    /** Trigger mode: "click" (default) or "hover" */
+    trigger?: PopoverTrigger;
+    /** Delay before showing (ms), mainly for hover mode */
+    showDelay?: number;
+    /** Delay before hiding (ms), mainly for hover mode */
+    hideDelay?: number;
+    /** Custom class for the popover container */
+    class?: string;
+    /** Offset/margin from the anchor element (CSS value, e.g., "0.5rem", "8px") */
+    offset?: string;
+    /** Close all other open popovers when this one opens */
+    closeOthers?: boolean;
+    /** Close on click outside (for click trigger) */
+    closeOnClickOutside?: boolean;
+    /** Close on Escape key */
+    closeOnEscape?: boolean;
+    /** Show backdrop in fallback mode */
+    showBackdrop?: boolean;
+    /** Force fallback mode (centered modal) even if CSS Anchor Positioning is supported */
+    forceFallback?: boolean;
+    /** Callback when popover opens */
+    onShow?: () => void;
+    /** Callback when popover hides */
+    onHide?: () => void;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * A Svelte action that displays a popover anchored to an element using CSS Anchor Positioning.
+ *
+ * The popover appears on click or hover (configurable) and supports multiple positions
+ * with automatic fallback. When CSS Anchor Positioning is not supported, falls back
+ * to a centered modal overlay.
+ *
+ * @param anchorEl - The element to attach the popover to
+ * @param fn - Function returning popover options (reactive)
+ *
+ * @example
+ * ```svelte
+ * <!-- Click trigger (default) -->
+ * <button use:popover={() => ({ content: "Hello World" })}>
+ *   Open Popover
+ * </button>
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Hover trigger -->
+ * <button use:popover={() => ({
+ *   content: "Hover content",
+ *   trigger: "hover",
+ *   position: "top"
+ * })}>
+ *   Hover Me
+ * </button>
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- With component content -->
+ * <button use:popover={() => ({
+ *   content: { component: MyComponent, props: { foo: "bar" } }
+ * })}>
+ *   With Component
+ * </button>
+ * ```
+ *
+ * @remarks
+ * - Falls back to centered modal when CSS Anchor Positioning is not supported
+ * - Closes on click outside (for click trigger) and Escape key by default
+ * - For hover trigger, popover persists when hovering over it
+ * - Automatically cleans up DOM elements on unmount
+ */
+export declare function popover(anchorEl: HTMLElement, fn?: () => PopoverOptions): void;