@marianmeres/stuic 3.170.0 → 3.172.0

package/dist/components/ContextMenu/ContextMenu.svelte

@@ -47,7 +47,7 @@
 		search?: boolean | ContextMenuSearchConfig;
 		/** Show backdrop in fallback mode (default: true) */
 		showBackdrop?: boolean;
-		/** Reserve scrollbar space to prevent layout shift on open (see DropdownMenu) */
+		/** Reserve scrollbar space; auto-detected once the menu scrolls (see DropdownMenu) */
 		scrollbarGutter?: boolean;
 		/** Skip the body scroll lock in fallback mode */
 		noScrollLock?: boolean;

package/dist/components/ContextMenu/ContextMenu.svelte.d.ts

@@ -39,7 +39,7 @@ export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children">
     search?: boolean | ContextMenuSearchConfig;
     /** Show backdrop in fallback mode (default: true) */
     showBackdrop?: boolean;
-    /** Reserve scrollbar space to prevent layout shift on open (see DropdownMenu) */
+    /** Reserve scrollbar space; auto-detected once the menu scrolls (see DropdownMenu) */
     scrollbarGutter?: boolean;
     /** Skip the body scroll lock in fallback mode */
     noScrollLock?: boolean;

package/dist/components/ContextMenu/README.md

@@ -29,7 +29,7 @@ trigger semantics and the cursor anchoring.
 | `closeOnEscape`                                    | `boolean`                              | `true`                | Close on Escape                                                                                    |
 | `search`                                           | `boolean \| ContextMenuSearchConfig`   | -                     | Search/filter input inside the menu (see DropdownMenu)                                             |
 | `showBackdrop`                                     | `boolean`                              | `true`                | Backdrop in fallback (centered modal) mode                                                         |
-| `scrollbarGutter`                                  | `boolean`                              | auto                  | Reserve scrollbar space (auto-enables at ≥ 7 items)                                                |
+| `scrollbarGutter`                                  | `boolean`                              | auto                  | Reserve scrollbar space (auto: once the menu actually scrolls, kept until close)                   |
 | `noScrollLock`                                     | `boolean`                              | -                     | Skip the body scroll lock in fallback mode                                                         |
 | `forceFallback`                                    | `boolean`                              | `false`               | Force the centered-modal fallback (testing)                                                        |
 | `onOpen` / `onClose`                               | `() => void`                           | -                     | Open/close callbacks                                                                               |

package/dist/components/DropdownMenu/DropdownMenu.svelte

@@ -194,8 +194,10 @@
 		onClose?: () => void;
 		/** Called when any action item is selected (fallback if item has no onSelect) */
 		onSelect?: (item: DropdownMenuActionItem) => void | boolean | Promise<void | boolean>;
-		/** Reserve scrollbar space to prevent layout shift on open (useful for long lists).
-		 *  When undefined, auto-enables if items count >= 7. */
+		/** Reserve scrollbar space (`scrollbar-gutter: stable`) so the menu width does not
+		 *  jump when the scrollbar comes and goes while open (search filtering, expandable
+		 *  sections). `true`/`false` force it. When undefined, the gutter is reserved only
+		 *  once the content actually scrolls, and kept until the menu closes. */
 		scrollbarGutter?: boolean;
 		/** Reference to trigger element */
 		triggerEl?: HTMLButtonElement;
@@ -684,9 +686,58 @@
 	// Computed transition duration
 	let transitionDuration = $derived(reducedMotion.current ? 0 : 100);
 
+	// Scrollbar gutter.
+	// `scrollbar-gutter: stable` keeps the dropdown width from jumping when the vertical
+	// scrollbar comes and goes while the menu is open (search filtering, expanding or
+	// collapsing sections). Reserving it up front for a menu that never scrolls leaves a
+	// dead strip along the right edge (with classic, space-taking scrollbars), so unless
+	// the `scrollbarGutter` prop decides, the gutter is reserved only once a space-taking
+	// scrollbar is actually present — and then kept until the menu closes.
+	let hasScrollbar = $state(false);
+
+	/** Whether `el` currently renders a vertical scrollbar that takes up layout space.
+	 *  Overlay scrollbars take none (and `scrollbar-gutter` reserves nothing for them).
+	 *  Both halves are needed: an already reserved gutter takes the same space as a
+	 *  scrollbar (so width alone is fooled by a stale gutter from the previous session),
+	 *  and a mid-transition frame (`overflow: hidden`, reduced height) "overflows"
+	 *  without any scrollbar (so height alone is fooled by the slide animation). */
+	function hasVerticalScrollbar(el: HTMLElement): boolean {
+		const cs = getComputedStyle(el);
+		const borders =
+			(parseFloat(cs.borderLeftWidth) || 0) + (parseFloat(cs.borderRightWidth) || 0);
+		// offsetWidth - clientWidth = horizontal borders + vertical scrollbar (or gutter)
+		const takesSpace = el.offsetWidth - el.clientWidth - borders > 1;
+		return takesSpace && el.scrollHeight > el.clientHeight;
+	}
+
+	function measureScrollbar() {
+		if (hasScrollbar || !dropdownEl) return;
+		if (hasVerticalScrollbar(dropdownEl)) hasScrollbar = true;
+	}
+
+	// Each open session measures afresh. Reset on open rather than on close, so the
+	// gutter survives the closing slide-out (no width jump mid-outro).
+	$effect(() => {
+		if (isOpen) hasScrollbar = false;
+	});
+
+	// Measure on open and whenever the rendered content can grow (search results,
+	// expanded sections, items, positioning mode). Effects run before the slide intro
+	// applies its first zero-height frame, so this reads the settled layout; the
+	// `onintrostart` / `onintroend` handlers in the template re-check around transitions
+	// (a re-open that interrupts the closing slide-out is measured mid-animation here,
+	// and only settles by `introend`).
+	$effect(() => {
+		if (!isOpen || !dropdownEl) return;
+		void filteredItems;
+		void expandedSections;
+		void isSupported;
+		untrack(measureScrollbar);
+	});
+
 	// Position styles for CSS Anchor Positioning
 	let dropdownStyle = $derived.by(() => {
-		const useGutter = scrollbarGutter ?? items.length >= 7;
+		const useGutter = scrollbarGutter ?? hasScrollbar;
 		const gutterStyle = useGutter ? "scrollbar-gutter: stable;" : "";
 		if (isSupported) {
 			// Use fixed height when search is enabled AND position is a "top" variant
@@ -878,6 +929,8 @@
 					)}
 			style={dropdownStyle}
 			transition:slide={{ duration: transitionDuration }}
+			onintrostart={measureScrollbar}
+			onintroend={measureScrollbar}
 		>
 			<!-- Close button (fallback mode only) -->
 			{#if !isSupported}
@@ -1017,6 +1070,7 @@
 										classExpandableContent
 									)}
 									transition:slide={{ duration: transitionDuration }}
+									onintroend={measureScrollbar}
 								>
 									{#each item.items as childItem}
 										{#if childItem.type === "action"}

package/dist/components/DropdownMenu/DropdownMenu.svelte.d.ts

@@ -163,8 +163,10 @@ export interface Props extends Omit<HTMLButtonAttributes, "children"> {
     onClose?: () => void;
     /** Called when any action item is selected (fallback if item has no onSelect) */
     onSelect?: (item: DropdownMenuActionItem) => void | boolean | Promise<void | boolean>;
-    /** Reserve scrollbar space to prevent layout shift on open (useful for long lists).
-     *  When undefined, auto-enables if items count >= 7. */
+    /** Reserve scrollbar space (`scrollbar-gutter: stable`) so the menu width does not
+     *  jump when the scrollbar comes and goes while open (search filtering, expandable
+     *  sections). `true`/`false` force it. When undefined, the gutter is reserved only
+     *  once the content actually scrolls, and kept until the menu closes. */
     scrollbarGutter?: boolean;
     /** Reference to trigger element */
     triggerEl?: HTMLButtonElement;

package/dist/components/DropdownMenu/README.md

@@ -11,6 +11,7 @@ A feature-rich dropdown menu component with CSS Anchor Positioning (with fallbac
 | `position`               | `DropdownMenuPosition`                | `"bottom-span-right"` | Popover position relative to trigger               |
 | `offset`                 | `string`                              | `"0.25rem"`           | Offset from trigger element (CSS value)            |
 | `maxHeight`              | `string`                              | `"300px"`             | Max height of dropdown                             |
+| `scrollbarGutter`        | `boolean`                             | auto                  | Reserve scrollbar space (auto: once it scrolls)    |
 | `closeOnSelect`          | `boolean`                             | `true`                | Close menu when action item is selected            |
 | `closeOnClickOutside`    | `boolean`                             | `true`                | Close on click outside                             |
 | `closeOnEscape`          | `boolean`                             | `true`                | Close on Escape key                                |

package/dist/components/Input/FieldDate.svelte

@@ -0,0 +1,349 @@
+<!--
+	FieldDate — pick a single calendar date.
+
+	The bound `value` is an ISO `YYYY-MM-DD` string (or null). The user picks it in
+	a `Calendar`, either in a dialog opened from a trigger button that shows the
+	formatted date (default), or inline inside the field (`embedded`). The `name`
+	goes on a hidden input carrying the ISO value, so a <form> submits
+	`2026-09-02` regardless of how the date is displayed.
+
+	Loose input (`"2026-09-02T10:00:00Z"`, a `Date`) is normalized to its calendar
+	date for display and submission; garbage is submitted as-is so the validator
+	can flag it. `required` / `min` / `max` / `isDateDisabled` are enforced in the
+	validator because a hidden input never validates natively.
+-->
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { ValidateOptions } from "../../actions/validate.svelte.js";
+	import type { TranslateFn } from "../../types.js";
+	import type { THC } from "../Thc/Thc.svelte";
+	import type { Props as CalendarProps } from "../Calendar/Calendar.svelte";
+	import type { IsoDate } from "../Calendar/iso-date.js";
+	import type { InputWrapClassProps } from "./types.js";
+
+	type SnippetWithId = Snippet<[{ id: string }]>;
+
+	/** The `Calendar` props a date field lifts to its own top level. */
+	export type FieldDateCalendarProps = Pick<
+		CalendarProps,
+		| "min"
+		| "max"
+		| "isDateDisabled"
+		| "weekStartsOn"
+		| "weekendDays"
+		| "zone"
+		| "captionLayout"
+		| "yearRange"
+		| "showWeekNumbers"
+		| "showOutsideDays"
+		| "fixedWeeks"
+		| "showToday"
+		| "renderDay"
+	>;
+
+	export interface Props extends InputWrapClassProps, FieldDateCalendarProps {
+		/** The selected date as `YYYY-MM-DD` (bindable). `null` / `""` = empty. */
+		value?: IsoDate | null;
+		/** Form field name — applied to the hidden input carrying the ISO date. */
+		name?: string;
+		/** Render the calendar inline inside the field instead of a trigger + dialog. */
+		embedded?: boolean;
+		/** Close the dialog right after a date is picked. Default `true`. */
+		closeOnSelect?: boolean;
+		/** Trigger text while empty. Defaults to `t("placeholder_date")`. */
+		placeholder?: string;
+		/** Offer clearing (trailing × on the trigger / "Clear" in the embedded footer). Default `true`. */
+		clearable?: boolean;
+		/** BCP 47 locale of the display text and the calendar names. Browser default when omitted. */
+		locale?: string;
+		/** `Intl.DateTimeFormat` options of the display text. Default `{ dateStyle: "medium" }`. */
+		formatOptions?: Intl.DateTimeFormatOptions;
+		/** Custom display formatter (wins over `formatOptions`). */
+		format?: (iso: IsoDate) => string;
+		/** Months the calendar shows side by side. Default `1`. */
+		months?: number;
+		/** Anything else for the inner `Calendar` (class hooks, `view`, …). Applied last. */
+		calendarProps?: Partial<CalendarProps>;
+		/** The hidden input (bindable). */
+		input?: HTMLInputElement;
+		label?: SnippetWithId | THC;
+		description?: SnippetWithId | THC;
+		labelAfter?: SnippetWithId | THC;
+		below?: SnippetWithId | THC;
+		class?: string;
+		id?: string;
+		tabindex?: number;
+		renderSize?: "sm" | "md" | "lg" | string;
+		required?: boolean;
+		disabled?: boolean;
+		/**
+		 * Validation. `false` disables the built-in guard (required / valid ISO / min /
+		 * max / disabled dates); an options object is merged with it (your
+		 * `customValidator` runs after the built-in checks pass). Default: the guard.
+		 */
+		validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+		labelLeft?: boolean;
+		labelLeftWidth?: "normal" | "wide";
+		labelLeftBreakpoint?: number;
+		/** Classes for the trigger button */
+		classInput?: string;
+		/** Classes for the dialog box */
+		classDialog?: string;
+		style?: string;
+		noScrollLock?: boolean;
+		/** i18n — see `createCalendarT`. */
+		t?: TranslateFn;
+		/** Called after the value changed through the picker or the × (not on external writes). */
+		onChange?: (value: IsoDate | null) => void;
+	}
+</script>
+
+<script lang="ts">
+	import { tick } from "svelte";
+	import type { ValidationResult } from "../../actions/validate.svelte.js";
+	import { getId } from "../../utils/get-id.js";
+	import Button from "../Button/Button.svelte";
+	import Calendar from "../Calendar/Calendar.svelte";
+	import { t_default } from "../Calendar/calendar-i18n.js";
+	import {
+		compareIso,
+		dayCellOf,
+		DEFAULT_DATE_FORMAT,
+		formatIsoDate,
+		normalizeIsoDate,
+	} from "../Calendar/iso-date.js";
+	import FieldDateShell from "./_internal/FieldDateShell.svelte";
+
+	let {
+		value = $bindable(null),
+		name,
+		embedded = false,
+		closeOnSelect = true,
+		placeholder,
+		clearable = true,
+		locale,
+		formatOptions,
+		format,
+		months = 1,
+		calendarProps,
+		input = $bindable(),
+		label = "",
+		description,
+		labelAfter,
+		below,
+		class: classProp,
+		id = getId(),
+		tabindex = 0,
+		renderSize = "md",
+		required = false,
+		disabled = false,
+		// Renamed local binding to avoid collision with `export function validate()` below.
+		validate: validateProp,
+		labelLeft = false,
+		labelLeftWidth = "normal",
+		labelLeftBreakpoint = 480,
+		classInput,
+		classDialog,
+		style,
+		noScrollLock = false,
+		t = t_default,
+		onChange,
+		// calendar
+		min,
+		max,
+		isDateDisabled,
+		weekStartsOn,
+		weekendDays,
+		zone,
+		captionLayout,
+		yearRange,
+		showWeekNumbers,
+		showOutsideDays,
+		fixedWeeks,
+		showToday,
+		renderDay,
+		// wrapper class props
+		classLabel,
+		classLabelBox,
+		classInputBox,
+		classInputBoxWrap,
+		classInputBoxWrapInvalid,
+		classDescBox,
+		classDescBoxToggle,
+		classBelowBox,
+		classValidationBox,
+	}: Props = $props();
+
+	let shell: FieldDateShell | undefined = $state();
+
+	let normalized = $derived(normalizeIsoDate(value));
+	let _min = $derived(normalizeIsoDate(min));
+	let _max = $derived(normalizeIsoDate(max));
+
+	// What the form submits: the normalized date — or the raw (unparseable) value,
+	// so the validator can flag it instead of silently submitting "".
+	let submitValue = $derived(normalized ?? (value == null ? "" : `${value}`));
+
+	const fmt = (iso: IsoDate): string =>
+		format
+			? format(iso)
+			: formatIsoDate(iso, locale, formatOptions ?? DEFAULT_DATE_FORMAT);
+
+	let display = $derived(normalized ? fmt(normalized) : "");
+
+	function commit(next: IsoDate | null) {
+		value = next;
+		onChange?.(next);
+		// let the hidden input's value flush before the validate action reads it
+		tick().then(() => shell?.dispatchChange());
+	}
+
+	function onSelect(next: IsoDate | null) {
+		commit(next);
+		if (!embedded && closeOnSelect && next) shell?.close();
+	}
+
+	// Built-in guard (a hidden input never validates natively): required, a valid
+	// ISO date, min / max, disabled dates. Consumer opts are honored: `false`
+	// disables; an object is merged (its customValidator runs after the guard).
+	const validateOpts = $derived.by<
+		boolean | Omit<ValidateOptions, "setValidationResult">
+	>(() => {
+		if (validateProp === false) return false;
+		const custom = validateProp && typeof validateProp === "object" ? validateProp : {};
+		return {
+			...custom,
+			customValidator: (val, ctx, el) => {
+				const str = `${val ?? ""}`.trim();
+				if (!str) {
+					if (required) return t("field_req_att");
+					return custom.customValidator?.(val, ctx, el) || "";
+				}
+				const iso = normalizeIsoDate(str);
+				if (!iso) return t("date_invalid");
+				if (_min && compareIso(iso, _min) < 0) {
+					return t("date_before_min", { value: fmt(_min) });
+				}
+				if (_max && compareIso(iso, _max) > 0) {
+					return t("date_after_max", { value: fmt(_max) });
+				}
+				if (isDateDisabled?.(iso, dayCellOf(iso, { zone, weekendDays }))) {
+					return t("date_disabled");
+				}
+				return custom.customValidator?.(val, ctx, el) || "";
+			},
+		};
+	});
+
+	// ---- Imperative API (satisfies ValidatableField), forwarded to the shell ----
+
+	/** Trigger validation now. Renders the inline message if invalid. */
+	export function validate(): ValidationResult | undefined {
+		return shell?.validate();
+	}
+
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		shell?.clearValidation();
+	}
+
+	/** Current validation state, or undefined if the validator has never run. */
+	export function getValidation(): ValidationResult | undefined {
+		return shell?.getValidation();
+	}
+
+	/** Focus the trigger (or the embedded calendar's tabbable day). */
+	export function focus(): void {
+		shell?.focus();
+	}
+
+	/** Scroll the field into view. Defaults to smooth + center. */
+	export function scrollIntoView(opts?: ScrollIntoViewOptions): void {
+		shell?.scrollIntoView(opts);
+	}
+
+	/** Open the picker dialog (no-op when `embedded`). */
+	export function open(): void {
+		shell?.open();
+	}
+
+	/** Close the picker dialog. */
+	export function close(): void {
+		shell?.close();
+	}
+</script>
+
+{#snippet doneFooter()}
+	<Button type="button" size="sm" intent="primary" onclick={() => shell?.close()}>
+		{t("done")}
+	</Button>
+{/snippet}
+
+<FieldDateShell
+	bind:this={shell}
+	bind:input
+	{id}
+	{label}
+	{description}
+	{labelAfter}
+	{below}
+	class={classProp}
+	{style}
+	{renderSize}
+	{required}
+	{disabled}
+	{tabindex}
+	{labelLeft}
+	{labelLeftWidth}
+	{labelLeftBreakpoint}
+	{classLabel}
+	{classLabelBox}
+	{classInputBox}
+	{classInputBoxWrap}
+	{classInputBoxWrapInvalid}
+	{classDescBox}
+	{classDescBoxToggle}
+	{classBelowBox}
+	{classValidationBox}
+	{display}
+	placeholder={placeholder ?? t("placeholder_date")}
+	{clearable}
+	clearLabel={t("clear_value")}
+	{embedded}
+	inputs={[{ name, value: submitValue }]}
+	validate={validateOpts}
+	dialogTitle={t("dialog_title_date")}
+	closeLabel={t("close")}
+	{noScrollLock}
+	{classInput}
+	{classDialog}
+	onClear={() => commit(null)}
+>
+	<Calendar
+		mode="single"
+		value={normalized}
+		{months}
+		{min}
+		{max}
+		{isDateDisabled}
+		{weekStartsOn}
+		{weekendDays}
+		{zone}
+		{locale}
+		{captionLayout}
+		{yearRange}
+		{showWeekNumbers}
+		{showOutsideDays}
+		{fixedWeeks}
+		{showToday}
+		showClear={embedded && clearable}
+		{renderDay}
+		{disabled}
+		{t}
+		focusOnMount={!embedded}
+		aria-labelledby={embedded && label ? `${id}-label` : undefined}
+		footer={!embedded && !closeOnSelect ? doneFooter : undefined}
+		{onSelect}
+		{...calendarProps}
+	/>
+</FieldDateShell>

package/dist/components/Input/FieldDate.svelte.d.ts

@@ -0,0 +1,79 @@
+import type { Snippet } from "svelte";
+import type { ValidateOptions } from "../../actions/validate.svelte.js";
+import type { TranslateFn } from "../../types.js";
+import type { THC } from "../Thc/Thc.svelte";
+import type { Props as CalendarProps } from "../Calendar/Calendar.svelte";
+import type { IsoDate } from "../Calendar/iso-date.js";
+import type { InputWrapClassProps } from "./types.js";
+type SnippetWithId = Snippet<[{
+    id: string;
+}]>;
+/** The `Calendar` props a date field lifts to its own top level. */
+export type FieldDateCalendarProps = Pick<CalendarProps, "min" | "max" | "isDateDisabled" | "weekStartsOn" | "weekendDays" | "zone" | "captionLayout" | "yearRange" | "showWeekNumbers" | "showOutsideDays" | "fixedWeeks" | "showToday" | "renderDay">;
+export interface Props extends InputWrapClassProps, FieldDateCalendarProps {
+    /** The selected date as `YYYY-MM-DD` (bindable). `null` / `""` = empty. */
+    value?: IsoDate | null;
+    /** Form field name — applied to the hidden input carrying the ISO date. */
+    name?: string;
+    /** Render the calendar inline inside the field instead of a trigger + dialog. */
+    embedded?: boolean;
+    /** Close the dialog right after a date is picked. Default `true`. */
+    closeOnSelect?: boolean;
+    /** Trigger text while empty. Defaults to `t("placeholder_date")`. */
+    placeholder?: string;
+    /** Offer clearing (trailing × on the trigger / "Clear" in the embedded footer). Default `true`. */
+    clearable?: boolean;
+    /** BCP 47 locale of the display text and the calendar names. Browser default when omitted. */
+    locale?: string;
+    /** `Intl.DateTimeFormat` options of the display text. Default `{ dateStyle: "medium" }`. */
+    formatOptions?: Intl.DateTimeFormatOptions;
+    /** Custom display formatter (wins over `formatOptions`). */
+    format?: (iso: IsoDate) => string;
+    /** Months the calendar shows side by side. Default `1`. */
+    months?: number;
+    /** Anything else for the inner `Calendar` (class hooks, `view`, …). Applied last. */
+    calendarProps?: Partial<CalendarProps>;
+    /** The hidden input (bindable). */
+    input?: HTMLInputElement;
+    label?: SnippetWithId | THC;
+    description?: SnippetWithId | THC;
+    labelAfter?: SnippetWithId | THC;
+    below?: SnippetWithId | THC;
+    class?: string;
+    id?: string;
+    tabindex?: number;
+    renderSize?: "sm" | "md" | "lg" | string;
+    required?: boolean;
+    disabled?: boolean;
+    /**
+     * Validation. `false` disables the built-in guard (required / valid ISO / min /
+     * max / disabled dates); an options object is merged with it (your
+     * `customValidator` runs after the built-in checks pass). Default: the guard.
+     */
+    validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+    labelLeft?: boolean;
+    labelLeftWidth?: "normal" | "wide";
+    labelLeftBreakpoint?: number;
+    /** Classes for the trigger button */
+    classInput?: string;
+    /** Classes for the dialog box */
+    classDialog?: string;
+    style?: string;
+    noScrollLock?: boolean;
+    /** i18n — see `createCalendarT`. */
+    t?: TranslateFn;
+    /** Called after the value changed through the picker or the × (not on external writes). */
+    onChange?: (value: IsoDate | null) => void;
+}
+import type { ValidationResult } from "../../actions/validate.svelte.js";
+declare const FieldDate: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+    open: () => void;
+    close: () => void;
+}, "value" | "input">;
+type FieldDate = ReturnType<typeof FieldDate>;
+export default FieldDate;