@marianmeres/stuic 3.130.0 → 3.131.0

package/dist/components/Input/FieldOptions.svelte

@@ -1,6 +1,16 @@
 <script lang="ts" module>
 	import { createClog } from "@marianmeres/clog";
-	import { iconSearch, iconCheck, iconCircle, iconSquare } from "../../icons/index.js";
+	import {
+		iconSearch,
+		iconCheck,
+		iconCircle,
+		iconSquare,
+		iconChevronUp,
+		iconChevronDown,
+		iconArrowUpToLine,
+		iconArrowDownToLine,
+		iconTrash,
+	} from "../../icons/index.js";
 	import { ItemCollection, type Item } from "@marianmeres/item-collection";
 	import { Debounced, watch } from "runed";
 	import { onDestroy, tick, type Snippet } from "svelte";
@@ -73,6 +83,13 @@
 		renderOptionLabel?: (item: Item) => string;
 		renderOptionGroup?: (s: string) => string;
 		allowUnknown?: boolean;
+		/**
+		 * Opt-in: when true (and multi-select), exposes a dedicated "Arrange" screen in the
+		 * modal that lets the user manually reorder the current selection (buttons only, no
+		 * drag), plus "Sort A–Z" / "Reverse" shortcuts. The chosen order is what gets
+		 * serialized to `value` on submit. No-op for single-select. Default `false`.
+		 */
+		ordered?: boolean;
 		showIconsCheckbox?: boolean;
 		showIconsRadio?: boolean;
 		searchPlaceholder?: string;
@@ -101,11 +118,28 @@
 			cardinality_full: "Max selection reached",
 			select_from_list: "Please select from the list only",
 			x_close: "Clear input or close [esc]",
+			close: "Close [esc]",
 			unknown_allowed: "Select or type and submit",
 			unknown_not_allowed: "Select from the list",
 			no_results: "No results found.",
 			add_new: 'Add "{{value}}"...',
 			click_add_new: "You must add the value to continue",
+			//
+			pick_tab: "Pick",
+			arrange_tab: "Arrange ({{value}})",
+			arrange_help: "Reorder the selected items. Use the buttons to move them.",
+			sort_az: "Sort A–Z",
+			reverse: "Reverse",
+			move_up: "Move up",
+			move_down: "Move down",
+			move_to_top: "Move to top",
+			move_to_bottom: "Move to bottom",
+			remove_item: "Remove",
+			moved_up: "Moved {{value}} up",
+			moved_down: "Moved {{value}} down",
+			removed_item: "Removed {{value}}",
+			sorted_az: "Sorted A to Z",
+			reversed: "Order reversed",
 		};
 		let out = m[k] ?? fallback ?? k;
 
@@ -177,6 +211,7 @@
 		renderOptionLabel,
 		renderOptionGroup = (s: string) => `${s}`.replaceAll("_", " "),
 		allowUnknown = false,
+		ordered = false,
 		showIconsCheckbox = true,
 		showIconsRadio = false,
 		searchPlaceholder,
@@ -229,6 +264,21 @@
 	let isMultiple = $derived(cardinality > 1);
 	let showIcons = $derived(isMultiple ? showIconsCheckbox : showIconsRadio);
 
+	// the "Arrange" (manual ordering) feature is opt-in and only meaningful for multi-select
+	let canArrange = $derived(ordered && isMultiple);
+	// false = "Pick" screen (search + options), true = "Arrange" screen (reorder selection)
+	let arrangeMode = $state(false);
+	// aria-live announcement text for reorder/remove actions
+	let liveAnnouncement = $state("");
+	// the arrange list scroller (for focus management)
+	let arrangeListBox: HTMLDivElement | undefined = $state();
+	// hydrate-once tracker (ordered mode): the `value` we last loaded the selection from
+	let hydratedValue: string | undefined = undefined;
+	// keep arrange state clean if the feature gets disabled at runtime (e.g. cardinality -> 1)
+	$effect(() => {
+		if (!canArrange && arrangeMode) arrangeMode = false;
+	});
+
 	//
 	let wrappedValidate: Omit<ValidateOptions, "setValidationResult"> = $derived({
 		enabled: true,
@@ -294,7 +344,13 @@
 
 	// reconfigure if the prop ever changes during runtime (most likely will NOT)
 	$effect(() => {
-		_selectedColl.configure({ cardinality });
+		// In "arrange" mode we UNSET the sortFn (item-collection: `null` unsets, a function
+		// keeps it) so the selection keeps its manual/insertion order instead of being
+		// auto-sorted alphabetically. Default mode keeps the alpha sortFn => byte-identical.
+		_selectedColl.configure({
+			cardinality,
+			sortFn: canArrange ? (null as any) : sortFn,
+		});
 		// trim excess selections if cardinality was reduced
 		if (_selectedColl.size > cardinality) {
 			const trimmed = _selectedColl.items.slice(0, cardinality);
@@ -356,15 +412,35 @@
 		}
 	);
 
+	function _hydrateSelectedFromValue(v: string) {
+		_selectedColl.clear().addMany(maybeJsonParse(v) as Item[]);
+		// IMPORTANT: focus first selected so it scrolls into view on open
+		if (_selectedColl.size) {
+			waitForNextRepaint().then(() => {
+				if (!isUnmounted) _optionsColl.setActive(_selectedColl.items[0]);
+			});
+		}
+	}
+
 	$effect(() => {
-		if (modalDialog.visibility().visible && touch) {
-			_selectedColl.clear().addMany(maybeJsonParse(value) as Item[]);
-			// IMPORTANT: focus first selected so it scrolls into view on open
-			if (_selectedColl.size) {
-				waitForNextRepaint().then(() => {
-					if (!isUnmounted) _optionsColl.setActive(_selectedColl.items[0]);
-				});
+		const visible = modalDialog.visibility().visible;
+		if (canArrange) {
+			// ORDERED MODE: hydrate the selection from `value` ONLY on open / external value
+			// change — deliberately NOT on every fetch (`touch`), otherwise a manual reorder
+			// (or any not-yet-submitted pick) would be silently reset on the next keystroke.
+			const v = value;
+			if (!visible) {
+				hydratedValue = undefined;
+				return;
 			}
+			if (hydratedValue === v) return;
+			hydratedValue = v;
+			// ensure the sortFn is unset before addMany, so the saved order survives the load
+			_selectedColl.configure({ sortFn: null as any }, false);
+			_hydrateSelectedFromValue(v);
+		} else {
+			// DEFAULT MODE: unchanged behavior (re-sync to `value` whenever visible & touched)
+			if (visible && touch) _hydrateSelectedFromValue(value);
 		}
 	});
 
@@ -384,6 +460,87 @@
 		return prefix + strHash(`${id}`.repeat(3));
 	}
 
+	// --- Arrange (ordered) screen helpers ---
+
+	function arrange_row_id(id: string | number) {
+		return btn_id(id, "arr-");
+	}
+
+	function _announce(key: string, item: Item) {
+		liveAnnouncement = t(key, { value: _renderOptionLabel(item) }) as string;
+	}
+
+	// re-focus the same logical button on the row that moved, so repeated presses keep
+	// walking the item; if that button is now disabled (a boundary), fall back to an enabled one
+	function focusRowButton(itemId: string | number, which: "up" | "down") {
+		tick().then(() => {
+			const row = arrangeListBox?.querySelector(`#${arrange_row_id(itemId)}`);
+			if (!row) return;
+			let btn = row.querySelector<HTMLButtonElement>(`[data-arrange-btn="${which}"]`);
+			if (!btn || btn.disabled) {
+				btn =
+					row.querySelector<HTMLButtonElement>(
+						`[data-arrange-btn="up"]:not([disabled])`
+					) ||
+					row.querySelector<HTMLButtonElement>(
+						`[data-arrange-btn="down"]:not([disabled])`
+					);
+			}
+			btn?.focus();
+		});
+	}
+
+	function moveItem(from: number, to: number) {
+		if (to < 0 || to >= _selectedColl.size || from === to) return;
+		const item = _selectedColl.items[from];
+		if (!_selectedColl.move(from, to)) return;
+		if (item) {
+			_announce(to < from ? "moved_up" : "moved_down", item);
+			focusRowButton(item[itemIdPropName], to < from ? "up" : "down");
+		}
+	}
+
+	function removeItem(i: number) {
+		const item = _selectedColl.items[i];
+		_selectedColl.removeAt(i);
+		if (item) _announce("removed_item", item);
+		tick().then(() => {
+			if (!_selectedColl.size) return enterPick();
+			const next = _selectedColl.items[Math.min(i, _selectedColl.size - 1)];
+			if (next) focusRowButton(next[itemIdPropName], "down");
+		});
+	}
+
+	// one-shot sort by visible label (does NOT re-enable auto-sort; subsequent adds still append)
+	function sortAZ() {
+		_selectedColl.sort((a, b) =>
+			_renderOptionLabel(a).localeCompare(_renderOptionLabel(b), undefined, {
+				sensitivity: "base",
+			})
+		);
+		liveAnnouncement = t("sorted_az") as string;
+	}
+
+	// no reverse() on the collection; snapshot, clear (no publish), re-add in reversed order
+	function reverse() {
+		const reversed = [...selected.items].reverse();
+		_selectedColl.clear(false).addMany(reversed);
+		liveAnnouncement = t("reversed") as string;
+	}
+
+	function enterArrange() {
+		if (!selected.items.length) return;
+		arrangeMode = true;
+		input?.blur(); // dismiss the soft keyboard (no text input on this screen)
+		const first = selected.items[0];
+		if (first) focusRowButton(first[itemIdPropName], "down");
+	}
+
+	function enterPick() {
+		arrangeMode = false;
+		tick().then(() => input?.focus());
+	}
+
 	// "inner" submit
 	function try_submit(force = false) {
 		// clog("try_submit", innerValue, _selectedColl.dump());
@@ -440,6 +597,7 @@
 		// clog("modal submit", $state.snapshot(selected.items));
 		value = JSON.stringify(selected.items);
 		innerValue = "";
+		arrangeMode = false;
 		_optionsColl.clear();
 		modalDialog.close();
 		_dispatch_change_to_owner();
@@ -449,6 +607,7 @@
 	// clears state and dispatches change; close is handled by ModalDialog's preEscapeClose
 	function escape() {
 		innerValue = "";
+		arrangeMode = false;
 		_optionsColl.clear();
 		_dispatch_change_to_owner();
 	}
@@ -506,7 +665,9 @@
 <!-- this must be on window as we're catching any typing anywhere -->
 <svelte:window
 	onkeydown={(e) => {
-		if (modalDialog.visibility().visible) {
+		// on the Arrange screen the reorder buttons own the keyboard; the option-list
+		// navigation + "any key focuses search" behavior must NOT run there
+		if (modalDialog.visibility().visible && !arrangeMode) {
 			// arrow navigation
 			if (["ArrowDown", "ArrowUp"].includes(e.key)) {
 				e.preventDefault();
@@ -602,6 +763,11 @@
 	>
 		<div class="pt-0 md:pt-[20vh] w-full">
 			<div class="pointer-events-auto">
+				<!-- screen-reader announcements for reorder / remove actions -->
+				<div class="sr-only" aria-live="polite" aria-atomic="true">
+					{liveAnnouncement}
+				</div>
+
 				<InputWrap
 					size={renderSize}
 					class={twMerge("m-1 sm:m-2 mb-12 shadow-xl", classModalField)}
@@ -613,12 +779,75 @@
 					{id}
 					{required}
 				>
+					{#snippet inputAbove()}
+						{#if canArrange}
+							<!-- Pick | Arrange tab header — lives INSIDE the card (solid bg) -->
+							<div
+								class="relative flex items-stretch px-2 border-b"
+								style={`border-color: var(--stuic-field-options-divider); min-height: var(--stuic-input-min-height-${renderSize}, 3rem);`}
+							>
+								<!-- full-height tabs => titles are vertically centered in the row -->
+								<div role="tablist" class="flex items-stretch gap-1">
+									<button
+										type="button"
+										role="tab"
+										aria-selected={!arrangeMode}
+										onclick={enterPick}
+										class={twMerge(
+											// keep font-weight constant across states so the tab doesn't reflow
+											"flex items-center px-3 -mb-px text-sm font-semibold border-b-2",
+											!arrangeMode
+												? "border-(--stuic-input-accent) text-(--stuic-input-accent)"
+												: "border-transparent stuic-field-options-muted"
+										)}
+									>
+										{@html t("pick_tab")}
+									</button>
+									<button
+										type="button"
+										role="tab"
+										aria-selected={arrangeMode}
+										disabled={!selected.items.length}
+										onclick={enterArrange}
+										class={twMerge(
+											// keep font-weight constant across states so the tab doesn't reflow
+											"flex items-center px-3 -mb-px text-sm font-semibold border-b-2",
+											arrangeMode
+												? "border-(--stuic-input-accent) text-(--stuic-input-accent)"
+												: "border-transparent stuic-field-options-muted"
+										)}
+									>
+										{@html t("arrange_tab", { value: selected.items.length })}
+									</button>
+								</div>
+
+								<!-- modal close lives in the tab header whenever tabs exist (both screens).
+								Absolutely positioned + height-matched row, so it never causes a jump. -->
+								<div class="absolute inset-y-0 right-1 flex items-center">
+									<Button
+										x
+										size="sm"
+										variant="ghost"
+										roundedFull
+										type="button"
+										tooltip={t("close")}
+										onclick={(e) => {
+											e.preventDefault();
+											escape();
+											modalDialog.close();
+										}}
+									/>
+								</div>
+							</div>
+						{/if}
+					{/snippet}
+
 					<input
 						bind:value={innerValue}
 						bind:this={input}
 						{type}
 						{id}
-						class={twMerge(renderSize, classInput)}
+						class={twMerge(renderSize, classInput, arrangeMode && "hidden")}
 						tabindex={1}
 						{required}
 						{disabled}
@@ -638,203 +867,353 @@
 
 					{#snippet inputBelow()}
 						<div
-							class="h-full border-t p-2"
+							class={twMerge("h-full p-2", !arrangeMode && "border-t")}
 							style="border-color: var(--stuic-field-options-divider);"
 						>
-							<div class="text-sm -mt-1 flex items-center">
-								{#if isMultiple}
+							{#snippet footerSubmitBtn()}
+								<div>
+									<Button
+										class="control"
+										type="button"
+										intent="primary"
+										onclick={async (e) => {
+											e.preventDefault();
+											try_submit(true);
+										}}
+										tabindex={3}
+									>
+										{@html t("submit")}
+									</Button>
+								</div>
+							{/snippet}
+
+							{#if canArrange && arrangeMode}
+								<!-- ARRANGE screen: reorder the current selection (buttons only, no drag) -->
+								<div class="text-sm -mt-1 flex items-center">
 									<button
 										type="button"
-										onclick={() => _selectedColl.addMany(options.items)}
+										onclick={sortAZ}
+										disabled={selected.items.length < 2}
 										class="control flex items-center p-1 m-1 text-sm underline rounded stuic-field-options-control"
 										tabindex={4}
-										disabled={!options.size}
 									>
-										{@html t("select_all")}
+										{@html t("sort_az")}
 									</button>
-								{/if}
-								<button
-									type="button"
-									onclick={() => {
-										_selectedColl.clear();
-										input?.focus();
-									}}
-									class="control flex items-center p-1 m-1 text-sm underline rounded stuic-field-options-control"
-									data-disabled={!selected.items.length || undefined}
-									tabindex={5}
-									disabled={!selected.items.length}
-								>
-									{@html t(cardinality === 1 ? "clear" : "clear_all")}
-								</button>
+									<button
+										type="button"
+										onclick={reverse}
+										disabled={selected.items.length < 2}
+										class="control flex items-center p-1 m-1 text-sm underline rounded stuic-field-options-control"
+										tabindex={5}
+									>
+										{@html t("reverse")}
+									</button>
+									<span
+										class="flex-1 block justify-end text-right text-xs p-1 pr-2 stuic-field-options-muted"
+									>
+										{selected.items.length}
+										{#if cardinality > 0 && cardinality < Infinity}
+											{@html t("cardinality_of")} {cardinality}
+										{/if}
+										{@html t("cardinality_selected")}
+									</span>
+								</div>
 
-								<span class="p-1 m-1 text-sm">&nbsp;</span>
-								<span
-									class="flex-1 block justify-end text-right text-xs p-1 pr-2 stuic-field-options-muted"
+								<div
+									class={[
+										"options overflow-y-auto overflow-x-hidden space-y-1 scrollbar-thin",
+										"h-55 max-h-55",
+									]}
+									bind:this={arrangeListBox}
+									tabindex="-1"
 								>
-									{selected.items.length}
-									{#if cardinality > 0 && cardinality < Infinity}
-										{@html t("cardinality_of")} {cardinality}
-									{/if}
-									{@html t("cardinality_selected")}
-								</span>
-							</div>
+									{#each selected.items as item, i (item[itemIdPropName])}
+										{@const last = selected.items.length - 1}
+										<div
+											id={arrange_row_id(item[itemIdPropName])}
+											class="flex items-center gap-1 px-1 py-0.5"
+										>
+											<span class="flex-1 min-w-0 truncate text-sm"
+												>{_renderOptionLabel(item)}</span
+											>
+											<span class="hidden sm:inline-flex">
+												<Button
+													iconButton
+													variant="ghost"
+													type="button"
+													aria-label={t("move_to_top")}
+													tooltip={t("move_to_top")}
+													data-arrange-btn="top"
+													disabled={i === 0}
+													onclick={() => moveItem(i, 0)}
+												>
+													{@html iconArrowUpToLine({ size: 18 })}
+												</Button>
+											</span>
+											<Button
+												iconButton
+												variant="ghost"
+												type="button"
+												aria-label={t("move_up")}
+												tooltip={t("move_up")}
+												data-arrange-btn="up"
+												disabled={i === 0}
+												onclick={() => moveItem(i, i - 1)}
+											>
+												{@html iconChevronUp({ size: 18 })}
+											</Button>
+											<Button
+												iconButton
+												variant="ghost"
+												type="button"
+												aria-label={t("move_down")}
+												tooltip={t("move_down")}
+												data-arrange-btn="down"
+												disabled={i === last}
+												onclick={() => moveItem(i, i + 1)}
+											>
+												{@html iconChevronDown({ size: 18 })}
+											</Button>
+											<span class="hidden sm:inline-flex">
+												<Button
+													iconButton
+													variant="ghost"
+													type="button"
+													aria-label={t("move_to_bottom")}
+													tooltip={t("move_to_bottom")}
+													data-arrange-btn="bottom"
+													disabled={i === last}
+													onclick={() => moveItem(i, last)}
+												>
+													{@html iconArrowDownToLine({ size: 18 })}
+												</Button>
+											</span>
+											<Button
+												iconButton
+												variant="ghost"
+												type="button"
+												aria-label={t("remove_item")}
+												tooltip={t("remove_item")}
+												data-arrange-btn="remove"
+												onclick={() => removeItem(i)}
+											>
+												{@html iconTrash({ size: 18 })}
+											</Button>
+										</div>
+									{/each}
+								</div>
 
-							<!-- {#if options.items.length} -->
-							<div
-								id={`${id}-options`}
-								class={[
-									"options overflow-y-auto overflow-x-hidden space-y-1 scrollbar-thin",
-									"h-55 max-h-55",
-								]}
-								bind:this={optionsBox}
-								tabindex="-1"
-							>
-								{#if isFetching && !options.items.length}
-									<div
-										class="flex text-sm h-full items-center justify-center stuic-field-options-placeholder"
-									>
-										<Spinner class="w-4" />
+								<div class="pt-3 pl-1 flex items-end justify-between">
+									<div class="text-xs stuic-field-options-muted">
+										{@html t("arrange_help")}
 									</div>
-								{:else if !options.items.length && !allowUnknown}
-									<div
-										class="flex text-sm h-full items-center justify-center stuic-field-options-placeholder"
+									{@render footerSubmitBtn()}
+								</div>
+							{:else}
+								<div class="text-sm -mt-1 flex items-center">
+									{#if isMultiple}
+										<button
+											type="button"
+											onclick={() => _selectedColl.addMany(options.items)}
+											class="control flex items-center p-1 m-1 text-sm underline rounded stuic-field-options-control"
+											tabindex={4}
+											disabled={!options.size}
+										>
+											{@html t("select_all")}
+										</button>
+									{/if}
+									<button
+										type="button"
+										onclick={() => {
+											_selectedColl.clear();
+											input?.focus();
+										}}
+										class="control flex items-center p-1 m-1 text-sm underline rounded stuic-field-options-control"
+										data-disabled={!selected.items.length || undefined}
+										tabindex={5}
+										disabled={!selected.items.length}
 									>
-										{@html t("no_results")}
-									</div>
-								{/if}
+										{@html t(cardinality === 1 ? "clear" : "clear_all")}
+									</button>
 
-								{#if !isFetching && allowUnknown && innerValue && !have_option_label_like(options.items, innerValue)}
-									<div class="px-1">
-										<ListItemButton
-											bind:el={addNewBtn}
-											onclick={add_new}
-											focused={isAddNewBtnActive}
-											class={classOption}
-											classFocused={classOptionActive}
-										>
-											{t("add_new", { value: innerValue })}
-										</ListItemButton>
-									</div>
-								{/if}
+									<span class="p-1 m-1 text-sm">&nbsp;</span>
+									<span
+										class="flex-1 block justify-end text-right text-xs p-1 pr-2 stuic-field-options-muted"
+									>
+										{selected.items.length}
+										{#if cardinality > 0 && cardinality < Infinity}
+											{@html t("cardinality_of")} {cardinality}
+										{/if}
+										{@html t("cardinality_selected")}
+									</span>
+								</div>
 
-								{#each groupedOptions as [_optgroup, _opts]}
-									{#if _optgroup}
+								<!-- {#if options.items.length} -->
+								<div
+									id={`${id}-options`}
+									class={[
+										"options overflow-y-auto overflow-x-hidden space-y-1 scrollbar-thin",
+										"h-55 max-h-55",
+									]}
+									bind:this={optionsBox}
+									tabindex="-1"
+								>
+									{#if isFetching && !options.items.length}
 										<div
-											class={twMerge(
-												"mb-1 p-1 text-xs font-semibold uppercase tracking-wide stuic-field-options-optgroup",
-												classOptgroup
-											)}
+											class="flex text-sm h-full items-center justify-center stuic-field-options-placeholder"
 										>
-											{_optgroup}
+											<Spinner class="w-4" />
+										</div>
+									{:else if !options.items.length && !allowUnknown}
+										<div
+											class="flex text-sm h-full items-center justify-center stuic-field-options-placeholder"
+										>
+											{@html t("no_results")}
 										</div>
 									{/if}
-									<ul role="presentation" class="space-y-1">
-										<!-- {#each options.items as item} -->
-										{#each _opts as item (item[itemIdPropName])}
-											{@const active =
-												item[itemIdPropName] === options.active?.[itemIdPropName]}
-											{@const isSelected =
-												selected.items && _selectedColl.exists(item[itemIdPropName])}
-											<li class:active role="presentation" class="px-1">
-												<ListItemButton
-													id={btn_id(item[itemIdPropName])}
-													onclick={() => {
-														if (isMultiple) {
-															if (selected.isFull && !_selectedColl.exists(item)) {
-																return notifications?.error(t("cardinality_full"), {
-																	ttl: 1000,
-																});
-															}
-															_selectedColl.toggleAdd(item);
-														} else {
-															_selectedColl.clear();
-															_selectedColl.add(item);
-															submit();
-														}
-													}}
-													active={isSelected}
-													focused={active}
-													contentBefore={showIcons ? getIconThc(isSelected) : undefined}
-													classContentBefore={isSelected
-														? "stuic-field-options-icon stuic-field-options-icon--selected"
-														: "stuic-field-options-icon"}
-													class={classOption}
-													classActive={classOptionActive}
-													classFocused={classOptionActive}
-													tabindex={-1}
-													role={isMultiple ? "checkbox" : "radio"}
-													aria-checked={isSelected}
-												>
-													{_renderOptionLabel(item)}
-												</ListItemButton>
-											</li>
-										{/each}
-									</ul>
-								{/each}
-							</div>
-							<!-- {/if} -->
-							<div class="pt-3 pl-1 flex items-end justify-between">
-								<div class="text-xs stuic-field-options-muted">
-									<!-- Use arrows to navigate. Spacebar and Enter to select and/or submit. -->
-									{#if allowUnknown}
-										{@html t("unknown_allowed")}
-									{:else}
-										{@html t("unknown_not_allowed")}
+
+									{#if !isFetching && allowUnknown && innerValue && !have_option_label_like(options.items, innerValue)}
+										<div class="px-1">
+											<ListItemButton
+												bind:el={addNewBtn}
+												onclick={add_new}
+												focused={isAddNewBtnActive}
+												class={classOption}
+												classFocused={classOptionActive}
+											>
+												{t("add_new", { value: innerValue })}
+											</ListItemButton>
+										</div>
 									{/if}
+
+									{#each groupedOptions as [_optgroup, _opts]}
+										{#if _optgroup}
+											<div
+												class={twMerge(
+													"mb-1 p-1 text-xs font-semibold uppercase tracking-wide stuic-field-options-optgroup",
+													classOptgroup
+												)}
+											>
+												{_optgroup}
+											</div>
+										{/if}
+										<ul role="presentation" class="space-y-1">
+											<!-- {#each options.items as item} -->
+											{#each _opts as item (item[itemIdPropName])}
+												{@const active =
+													item[itemIdPropName] === options.active?.[itemIdPropName]}
+												{@const isSelected =
+													selected.items && _selectedColl.exists(item[itemIdPropName])}
+												<li class:active role="presentation" class="px-1">
+													<ListItemButton
+														id={btn_id(item[itemIdPropName])}
+														onclick={() => {
+															if (isMultiple) {
+																if (selected.isFull && !_selectedColl.exists(item)) {
+																	return notifications?.error(t("cardinality_full"), {
+																		ttl: 1000,
+																	});
+																}
+																_selectedColl.toggleAdd(item);
+															} else {
+																_selectedColl.clear();
+																_selectedColl.add(item);
+																submit();
+															}
+														}}
+														active={isSelected}
+														focused={active}
+														contentBefore={showIcons ? getIconThc(isSelected) : undefined}
+														classContentBefore={isSelected
+															? "stuic-field-options-icon stuic-field-options-icon--selected"
+															: "stuic-field-options-icon"}
+														class={classOption}
+														classActive={classOptionActive}
+														classFocused={classOptionActive}
+														tabindex={-1}
+														role={isMultiple ? "checkbox" : "radio"}
+														aria-checked={isSelected}
+													>
+														{_renderOptionLabel(item)}
+													</ListItemButton>
+												</li>
+											{/each}
+										</ul>
+									{/each}
 								</div>
-								<div>
-									<Button
-										class="control"
-										type="button"
-										intent="primary"
-										onclick={async (e) => {
-											e.preventDefault();
-											try_submit(true);
-										}}
-										tabindex={3}
-									>
-										{@html t("submit")}
-									</Button>
+								<!-- {/if} -->
+								<div class="pt-3 pl-1 flex items-end justify-between">
+									<div class="text-xs stuic-field-options-muted">
+										<!-- Use arrows to navigate. Spacebar and Enter to select and/or submit. -->
+										{#if allowUnknown}
+											{@html t("unknown_allowed")}
+										{:else}
+											{@html t("unknown_not_allowed")}
+										{/if}
+									</div>
+									<div>
+										<Button
+											class="control"
+											type="button"
+											intent="primary"
+											onclick={async (e) => {
+												e.preventDefault();
+												try_submit(true);
+											}}
+											tabindex={3}
+										>
+											{@html t("submit")}
+										</Button>
+									</div>
 								</div>
-							</div>
+							{/if}
 						</div>
 					{/snippet}
 
 					{#snippet inputAfter()}
-						<div
-							class="flex pl-2 items-center justify-center stuic-field-options-placeholder"
-						>
-							{#if isFetching}
-								<Spinner class="w-4" />
+						<!-- the whole search row is hidden on the Arrange screen (close moves to the tabs) -->
+						{#if !arrangeMode}
+							<div
+								class="flex pl-2 items-center justify-center stuic-field-options-placeholder"
+							>
+								{#if isFetching}
+									<Spinner class="w-4" />
+								{/if}
+							</div>
+							<!-- ordered fields have a single close ✕ in the tab header, so the
+							search row drops its own ✕ (avoids a confusing double-✕) -->
+							{#if !canArrange}
+								<div class="flex pl-2 pr-1 items-center justify-center">
+									<Button
+										x
+										variant="ghost"
+										roundedFull
+										type="button"
+										tooltip={t("x_close")}
+										onclick={(e) => {
+											e.preventDefault();
+											if (innerValue.trim() == "") {
+												escape();
+												return modalDialog.close();
+											}
+											innerValue = "";
+											input?.focus();
+										}}
+										tabindex={2}
+									/>
+								</div>
 							{/if}
-						</div>
-						<div class="flex pl-2 pr-1 items-center justify-center">
-							<Button
-								x
-								variant="ghost"
-								roundedFull
-								type="button"
-								tooltip={t("x_close")}
-								onclick={(e) => {
-									e.preventDefault();
-									if (innerValue.trim() == "") {
-										escape();
-										return modalDialog.close();
-									}
-									innerValue = "";
-									input?.focus();
-								}}
-								tabindex={2}
-							/>
-						</div>
+						{/if}
 					{/snippet}
 
 					{#snippet inputBefore()}
-						<div
-							class="flex flex-col items-center justify-center pl-3 stuic-field-options-muted"
-						>
-							{@html iconSearch({ size: 19 })}
-						</div>
+						{#if !arrangeMode}
+							<div
+								class="flex flex-col items-center justify-center pl-3 stuic-field-options-muted"
+							>
+								{@html iconSearch({ size: 19 })}
+							</div>
+						{/if}
 					{/snippet}
 				</InputWrap>
 			</div>

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

@@ -55,6 +55,13 @@ export interface Props extends InputWrapClassProps, Record<string, any> {
     renderOptionLabel?: (item: Item) => string;
     renderOptionGroup?: (s: string) => string;
     allowUnknown?: boolean;
+    /**
+     * Opt-in: when true (and multi-select), exposes a dedicated "Arrange" screen in the
+     * modal that lets the user manually reorder the current selection (buttons only, no
+     * drag), plus "Sort A–Z" / "Reverse" shortcuts. The chosen order is what gets
+     * serialized to `value` on submit. No-op for single-select. Default `false`.
+     */
+    ordered?: boolean;
     showIconsCheckbox?: boolean;
     showIconsRadio?: boolean;
     searchPlaceholder?: string;

package/dist/components/Input/README.md

@@ -359,21 +359,22 @@ A modal-based multi-select/single-select component with search functionality, ty
 
 ### Props
 
-| Prop                | Type                                                       | Default    | Description                             |
-| ------------------- | ---------------------------------------------------------- | ---------- | --------------------------------------- |
-| `value`             | `string`                                                   | `"[]"`     | JSON array of selected items (bindable) |
-| `name`              | `string`                                                   | -          | Form field name                         |
-| `getOptions`        | `(q: string, current: Item[]) => Promise<{found: Item[]}>` | -          | Async function to fetch options         |
-| `cardinality`       | `number`                                                   | `Infinity` | Max selections (-1 for unlimited)       |
-| `allowUnknown`      | `boolean`                                                  | `false`    | Allow typing custom values              |
-| `renderOptionLabel` | `(item: Item) => string`                                   | -          | Custom option label renderer            |
-| `renderOptionGroup` | `(s: string) => string`                                    | -          | Custom optgroup label renderer          |
-| `renderValue`       | `(stringifiedItems: string) => string`                     | -          | Custom value display renderer           |
-| `showIconsCheckbox` | `boolean`                                                  | `true`     | Show checkbox icons in multi-select     |
-| `showIconsRadio`    | `boolean`                                                  | `false`    | Show radio icons in single-select       |
-| `searchPlaceholder` | `string`                                                   | -          | Custom search placeholder               |
-| `itemIdPropName`    | `string`                                                   | `"id"`     | Property name for item ID               |
-| `notifications`     | `NotificationsStack`                                       | -          | Notification handler for errors         |
+| Prop                | Type                                                       | Default    | Description                                                                         |
+| ------------------- | ---------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------- |
+| `value`             | `string`                                                   | `"[]"`     | JSON array of selected items (bindable)                                             |
+| `name`              | `string`                                                   | -          | Form field name                                                                     |
+| `getOptions`        | `(q: string, current: Item[]) => Promise<{found: Item[]}>` | -          | Async function to fetch options                                                     |
+| `cardinality`       | `number`                                                   | `Infinity` | Max selections (-1 for unlimited)                                                   |
+| `allowUnknown`      | `boolean`                                                  | `false`    | Allow typing custom values                                                          |
+| `ordered`           | `boolean`                                                  | `false`    | Opt-in: add an "Arrange" screen to manually order the selection (multi-select only) |
+| `renderOptionLabel` | `(item: Item) => string`                                   | -          | Custom option label renderer                                                        |
+| `renderOptionGroup` | `(s: string) => string`                                    | -          | Custom optgroup label renderer                                                      |
+| `renderValue`       | `(stringifiedItems: string) => string`                     | -          | Custom value display renderer                                                       |
+| `showIconsCheckbox` | `boolean`                                                  | `true`     | Show checkbox icons in multi-select                                                 |
+| `showIconsRadio`    | `boolean`                                                  | `false`    | Show radio icons in single-select                                                   |
+| `searchPlaceholder` | `string`                                                   | -          | Custom search placeholder                                                           |
+| `itemIdPropName`    | `string`                                                   | `"id"`     | Property name for item ID                                                           |
+| `notifications`     | `NotificationsStack`                                       | -          | Notification handler for errors                                                     |
 
 ### Class Props
 
@@ -422,6 +423,33 @@ A modal-based multi-select/single-select component with search functionality, ty
 />
 ```
 
+### Ordering the selection (`ordered`)
+
+By default the selected items are serialized to `value` in alphabetical order. For
+relations where the order matters, opt in with `ordered` (multi-select only). This adds a
+`Pick | Arrange` tab header inside the modal. The **Arrange** screen shows the current
+selection as a flat list where each row has **Move up / down** (and, on wider screens,
+**Move to top / bottom**) plus **Remove** buttons — buttons only, no drag — and offers
+**Sort A–Z** / **Reverse** shortcuts. The order you set is what gets serialized to `value`
+on submit (and round-trips on reopen). Single-select fields ignore the prop.
+
+```svelte
+<FieldOptions
+	label="Steps (in order)"
+	name="steps"
+	bind:value
+	{getOptions}
+	cardinality={-1}
+	ordered
+/>
+```
+
+> Note: with `ordered`, **Select all** appends in the options' (alphabetical) order as a
+> starting point — use the per-row buttons or the Sort/Reverse shortcuts to arrange from
+> there. The `value` must hold full item objects (with their label), which is already the
+> default contract, so the Arrange list can render selected items even when they aren't in
+> the current search results.
+
 ### Customization Examples
 
 ```css

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

@@ -16,6 +16,8 @@
 		label?: SnippetWithId | THC;
 		labelAfter?: SnippetWithId | THC;
 		inputBefore?: SnippetWithId | THC;
+		/** Rendered inside the input card, above the input row (e.g. a tab header) */
+		inputAbove?: SnippetWithId | THC;
 		children: Snippet;
 		inputAfter?: SnippetWithId | THC;
 		inputBelow?: SnippetWithId | THC;
@@ -40,6 +42,7 @@
 		label,
 		labelAfter,
 		inputBefore,
+		inputAbove,
 		children,
 		inputAfter,
 		inputBelow,
@@ -144,6 +147,7 @@
 				invalid && classInputBoxWrapInvalid
 			)}
 		>
+			{@render snippetOrThc({ id, value: inputAbove })}
 			<div class="flex">
 				{@render snippetOrThc({ id, value: inputBefore })}
 				{@render children()}

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

@@ -12,6 +12,8 @@ interface Props extends InputWrapClassProps {
     label?: SnippetWithId | THC;
     labelAfter?: SnippetWithId | THC;
     inputBefore?: SnippetWithId | THC;
+    /** Rendered inside the input card, above the input row (e.g. a tab header) */
+    inputAbove?: SnippetWithId | THC;
     children: Snippet;
     inputAfter?: SnippetWithId | THC;
     inputBelow?: SnippetWithId | THC;

package/dist/icons/index.d.ts

@@ -17,9 +17,11 @@ export { iconLucideOctagonX as iconAlertError } from "@marianmeres/icons-fns/luc
 export { iconLucideRefreshCw as iconRefresh } from "@marianmeres/icons-fns/lucide/iconLucideRefreshCw.js";
 export { iconLucideTriangleAlert as iconAlertWarning } from "@marianmeres/icons-fns/lucide/iconLucideTriangleAlert.js";
 export { iconLucideArrowDown as iconArrowDown } from "@marianmeres/icons-fns/lucide/iconLucideArrowDown.js";
+export { iconLucideArrowDownToLine as iconArrowDownToLine } from "@marianmeres/icons-fns/lucide/iconLucideArrowDownToLine.js";
 export { iconLucideArrowLeft as iconArrowLeft } from "@marianmeres/icons-fns/lucide/iconLucideArrowLeft.js";
 export { iconLucideArrowRight as iconArrowRight } from "@marianmeres/icons-fns/lucide/iconLucideArrowRight.js";
 export { iconLucideArrowUp as iconArrowUp } from "@marianmeres/icons-fns/lucide/iconLucideArrowUp.js";
+export { iconLucideArrowUpToLine as iconArrowUpToLine } from "@marianmeres/icons-fns/lucide/iconLucideArrowUpToLine.js";
 export { iconLucideDownload as iconDownload } from "@marianmeres/icons-fns/lucide/iconLucideDownload.js";
 export { iconLucideMinus as iconMinus } from "@marianmeres/icons-fns/lucide/iconLucideMinus.js";
 export { iconLucidePlus as iconPlus } from "@marianmeres/icons-fns/lucide/iconLucidePlus.js";

package/dist/icons/index.js

@@ -21,9 +21,11 @@ export { iconLucideRefreshCw as iconRefresh } from "@marianmeres/icons-fns/lucid
 export { iconLucideTriangleAlert as iconAlertWarning } from "@marianmeres/icons-fns/lucide/iconLucideTriangleAlert.js";
 // Action Icons (Lucide)
 export { iconLucideArrowDown as iconArrowDown } from "@marianmeres/icons-fns/lucide/iconLucideArrowDown.js";
+export { iconLucideArrowDownToLine as iconArrowDownToLine } from "@marianmeres/icons-fns/lucide/iconLucideArrowDownToLine.js";
 export { iconLucideArrowLeft as iconArrowLeft } from "@marianmeres/icons-fns/lucide/iconLucideArrowLeft.js";
 export { iconLucideArrowRight as iconArrowRight } from "@marianmeres/icons-fns/lucide/iconLucideArrowRight.js";
 export { iconLucideArrowUp as iconArrowUp } from "@marianmeres/icons-fns/lucide/iconLucideArrowUp.js";
+export { iconLucideArrowUpToLine as iconArrowUpToLine } from "@marianmeres/icons-fns/lucide/iconLucideArrowUpToLine.js";
 export { iconLucideDownload as iconDownload } from "@marianmeres/icons-fns/lucide/iconLucideDownload.js";
 export { iconLucideMinus as iconMinus } from "@marianmeres/icons-fns/lucide/iconLucideMinus.js";
 export { iconLucidePlus as iconPlus } from "@marianmeres/icons-fns/lucide/iconLucidePlus.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.130.0",
+	"version": "3.131.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",
@@ -122,12 +122,12 @@
 		}
 	},
 	"devDependencies": {
-		"@codemirror/commands": "^6.10.3",
+		"@codemirror/commands": "^6.10.4",
 		"@codemirror/lang-markdown": "^6.5.0",
 		"@codemirror/language": "^6.12.3",
 		"@codemirror/language-data": "^6.5.2",
-		"@codemirror/state": "^6.6.0",
-		"@codemirror/view": "^6.43.1",
+		"@codemirror/state": "^6.7.0",
+		"@codemirror/view": "^6.43.2",
 		"@eslint/js": "^9.39.4",
 		"@marianmeres/random-human-readable": "^1.10.2",
 		"@milkdown/core": "^7.21.2",
@@ -140,29 +140,29 @@
 		"@milkdown/transformer": "^7.21.2",
 		"@milkdown/utils": "^7.21.2",
 		"@sveltejs/adapter-auto": "^4.0.0",
-		"@sveltejs/kit": "^2.65.1",
+		"@sveltejs/kit": "^2.68.0",
 		"@sveltejs/package": "^2.5.8",
 		"@sveltejs/vite-plugin-svelte": "^6.2.4",
 		"@tailwindcss/cli": "^4.3.1",
 		"@tailwindcss/forms": "^0.5.11",
 		"@tailwindcss/typography": "^0.5.20",
 		"@tailwindcss/vite": "^4.3.1",
-		"@types/node": "^25.9.3",
+		"@types/node": "^25.9.4",
 		"@vitest/browser-playwright": "^4.1.9",
 		"dotenv": "^16.6.1",
 		"eslint": "^9.39.4",
 		"globals": "^16.5.0",
-		"playwright": "^1.61.0",
+		"playwright": "^1.61.1",
 		"prettier": "^3.8.4",
 		"prettier-plugin-svelte": "^3.5.2",
 		"publint": "^0.3.21",
-		"svelte": "^5.56.3",
-		"svelte-check": "^4.6.0",
+		"svelte": "^5.56.4",
+		"svelte-check": "^4.7.1",
 		"tailwindcss": "^4.3.1",
 		"tsx": "^4.22.4",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.61.1",
-		"vite": "^7.3.5",
+		"typescript-eslint": "^8.62.0",
+		"vite": "^7.3.6",
 		"vitest": "^4.1.9",
 		"vitest-browser-svelte": "^2.1.1"
 	},
@@ -177,7 +177,7 @@
 		"@marianmeres/parse-boolean": "^2.1.0",
 		"@marianmeres/ticker": "^1.17.1",
 		"@marianmeres/tree": "^2.3.0",
-		"libphonenumber-js": "^1.13.6",
+		"libphonenumber-js": "^1.13.7",
 		"runed": "^0.23.4",
 		"tailwind-merge": "^3.6.0"
 	}