@lavalogic/scoria 0.35.0 → 0.37.0

package/dist/Components/MultiSelect.svelte

@@ -1,199 +1,222 @@
-<svelte:options runes />
-
-<script lang="ts" generics="V extends object, VP extends ValueProp<V>">
-	import { autoPluralise, generateShortUUID, vowels } from '../Helpers/Helpers.svelte.js';
-	import { Colour, ColourSet } from '../scss/colours.js';
-	import type { ValueProp } from '../Types/Internal/Misc.js';
-	import { Size } from '../Types/Internal/Size.js';
-	import Svelecte from 'svelecte';
-	import { onMount } from 'svelte';
-	import Action from './Action.svelte';
-	import Icon from './Icon.svelte';
-	import type { MultiSelectProps } from './MultiSelectProps.js';
-
-	// HACK selectedValues is mutated by svelecte without asking, so we sometimes have to reverse it without a callback (side effects)
-	let {
-		label,
-		inputId = generateShortUUID(),
-		options,
-		labelProp,
-		valueProp,
-		width,
-		valueAsObject = true,
-		height,
-		selectedValues,
-		onchange,
-		collapseSelection = false,
-		name = 'Item',
-		disabled,
-		required,
-		invalid
-	}: MultiSelectProps<V, VP> = $props();
-
-	const an = $derived(name && vowels.has(name.at(0)?.toLocaleLowerCase() ?? '') ? 'an' : 'a');
-
-	const hidden = $state(false);
-
-	onMount(() => {
-		const input = document.getElementById(inputId);
-		// input?.addEventListener('focus', () => {
-		// 	hidden = true;
-		// });
-		// input?.addEventListener('blur', () => {
-		// 	hidden = false;
-		// });
-
-		// HACK callback for is-open on/off
-		const dropdownRef = input?.closest('div.svelecte')?.querySelector('.sv_dropdown') ?? undefined;
-		const observer = new MutationObserver((mutations: Array<MutationRecord>) => {
-			for (let i = mutations.length - 1; i > -1; i--) {
-				const mutation = mutations[i];
-				if (mutation.attributeName === 'class') {
-					isExpanded = dropdownRef?.classList.contains('is-open') ?? false;
-				}
-			}
-		});
-
-		if (dropdownRef) {
-			observer.observe(dropdownRef, { attributes: true });
-		}
-
-		return () => {
-			observer.disconnect();
-		};
-	});
-
-	let isExpanded = $state(false);
-
-	const isInvalid = $derived((required && !selectedValues.length) || invalid);
-
-	function usesValuesAsObjects(_values: Array<V> | Array<V[VP]>): _values is Array<V> {
-		return valueAsObject;
-	}
-
-	function usesValuesAsPrimitives(_values: Array<V> | Array<V[VP]>): _values is Array<V[VP]> {
-		return !valueAsObject;
-	}
-</script>
-
-<div
-	class:invalid={isInvalid}
-	class="select-wrapper"
-	style={`${width ? `--input-width: ${width};` : ''}${height ? `--input-height: ${height};` : ''}`}
->
-	{#if label}
-		<label for={inputId}>
-			<span>{label}</span>
-			<span class="border">{label}</span>
-		</label>
-	{/if}
-
-	<Svelecte
-		multiple
-		{valueAsObject}
-		{disabled}
-		{inputId}
-		valueField={valueProp}
-		labelField={labelProp}
-		{options}
-		searchable
-		value={selectedValues}
-		onChange={(e: Array<V>) => {
-			onchange(e);
-		}}
-		{name}
-		selectOnTab
-		keepSelectionInList
-		searchProps={{ keepSelectionInList: true }}
-		creatable={false}
-		collapseSelection={collapseSelection ? 'always' : null}
-		deselectMode="toggle"
-		highlightFirstItem={false}
-		placeholder="Please Select {name ? `${an} ${name}` : ''}"
-		selection={collapseSelection ? selection : undefined}
-	>
-		{#snippet option(opt)}
-			{@const option = opt as V}
-			<span class="dropdown-item">
-				<div
-					class="toggle-icon"
-					class:yes={usesValuesAsObjects(selectedValues)
-						? selectedValues.findIndex((v) => v[valueProp] === option[valueProp]) > -1
-						: usesValuesAsPrimitives(selectedValues)
-							? (selectedValues as Array<V[VP]>).findIndex((v: V[VP]) => v === option[valueProp]) >
-								-1
-							: false}
-				>
-					<Icon name="tick" size={Size.MediumSmall} />
-				</div>
-				{option[labelProp]}</span
-			>
-		{/snippet}
-
-		{#snippet collapsedSelection(selectedOptions: Array<object> /*_i18n*/)}
-			<span class="selection" class:hidden
-				>{#if selectedOptions.length}{selectedOptions.length}
-					{#if name}{autoPluralise(name, selectedOptions.length)}{/if} Selected
-				{:else}Please Select {#if name}
-						{an} {name}{/if}
-				{/if}</span
-			>
-		{/snippet}
-
-		{#snippet append()}
-			<div class="icons">
-				<Action
-					{disabled}
-					size={Size.Small}
-					noTabIndex
-					colourSet={ColourSet.Auxiliary}
-					onclick={(e: MouseEvent) => {
-						if (isExpanded) {
-							e.stopPropagation();
-						}
-
-						if (selectedValues.length) {
-							onchange([]);
-						} else {
-							onchange(options.concat());
-						}
-					}}
-					icon={{
-						name: selectedValues.length ? 'close-menu-cross' : 'manage-product-group',
-						colour: Colour['$ui-blue-10']
-					}}
-				/>
-
-				<Action
-					{disabled}
-					size={Size.Small}
-					noTabIndex
-					colourSet={ColourSet.Auxiliary}
-					icon={{
-						name: isExpanded ? 'chevron-up' : 'chevron-down',
-						colour: Colour['$ui-blue-10']
-					}}
-				/>
-			</div>
-		{/snippet}
-		{#snippet toggleIcon()}
-			<div class="nothing"></div>
-			<!-- <div class="icon-bg">
-				<Icon name="chevron-down" size={Size.MediumSmall} />
-			</div> -->
-		{/snippet}
-	</Svelecte>
-
-	{#snippet selection(/*_selectedOptions: Array<unknown>*/)}
-		<!-- {#if selectedOptions.length === 0}
-			<span class="selection" class:hidden
-				>Please Select {#if objectName}
-					{an} {objectName}{/if}</span
-			>
-		{/if} -->
-	{/snippet}
-</div>
-
+<svelte:options runes />
+
+<script
+	lang="ts"
+	generics="V extends object, VP extends ValueProp<V>"
+>
+	import { autoPluralise, generateWeakId, vowels } from '../Helpers/Helpers.svelte.js';
+	import { attachDropdownPortal } from '../Helpers/dropdownPortal.js';
+	import { Colour, ColourSet } from '../scss/colours.js';
+	import type { ValueProp } from '../Types/Internal/Misc.js';
+	import { Size } from '../Types/Internal/Size.js';
+	import Svelecte from 'svelecte';
+	import { SvelteSet } from 'svelte/reactivity';
+	import { onMount } from 'svelte';
+	import Action from './Action.svelte';
+	import Icon from './Icon.svelte';
+	import type { MultiSelectProps } from './MultiSelectProps.js';
+
+	// NOTE selectedValues is mutated by svelecte without asking, so we sometimes have to reverse it without a callback (side effects)
+	const {
+		label,
+		inputId = generateWeakId(),
+		options,
+		labelProp,
+		valueProp,
+		width,
+		valueAsObject = true,
+		height,
+		selectedValues,
+		onchange,
+		collapseSelection = false,
+		name = 'Item',
+		disabled,
+		required,
+		invalid,
+	}: MultiSelectProps<V, VP> = $props();
+
+	const an = $derived(name && vowels.has(name.at(0)?.toLocaleLowerCase() ?? '') ? 'an' : 'a');
+
+	// Pre-computed set of selected primitive keys. Used in the option snippet
+	// to avoid an O(n*m) findIndex sweep per render.
+	const selectedKeys = $derived.by(() => {
+		const s = new SvelteSet<V[VP]>();
+		if (valueAsObject) {
+			for (const v of selectedValues as Array<V>) {
+				s.add(v[valueProp]);
+			}
+		} else {
+			for (const v of selectedValues as Array<V[VP]>) {
+				s.add(v);
+			}
+		}
+		return s;
+	});
+
+	let isExpanded = $state(false);
+
+	onMount(() => {
+		const input = document.getElementById(inputId);
+		const svelecteRoot = input?.closest('div.svelecte') as HTMLElement | null;
+		const dropdownRef =
+			(svelecteRoot?.querySelector('.sv_dropdown') as HTMLElement | null) ?? undefined;
+
+		// HACK callback for is-open on/off; drives the chevron rotation
+		// in the action snippet further down.
+		const observer = new MutationObserver((mutations: Array<MutationRecord>) => {
+			for (let i = mutations.length - 1; i > -1; i--) {
+				const mutation = mutations[i];
+				if (mutation.attributeName === 'class') {
+					isExpanded = dropdownRef?.classList.contains('is-open') ?? false;
+				}
+			}
+		});
+
+		if (dropdownRef) {
+			observer.observe(dropdownRef, { attributes: true });
+		}
+
+		// Teleport the Svelecte dropdown to `document.body` while open
+		// so it escapes every ancestor `overflow` / `transform` /
+		// `z-index` stacking context. See `Helpers/dropdownPortal.ts`
+		// for the rationale and behaviour (auto-flip upwards on tight
+		// viewports, scroll-aware repositioning, viewport-bounded
+		// max-height).
+		const detachPortal = attachDropdownPortal({
+			getTrigger: () => svelecteRoot,
+			getDropdown: () => dropdownRef,
+		});
+
+		return () => {
+			observer.disconnect();
+			detachPortal();
+		};
+	});
+
+	const isInvalid = $derived((required && !selectedValues.length) || invalid);
+</script>
+
+<div
+	class:invalid={isInvalid}
+	class="select-wrapper"
+	style={`${width ? `--input-width: ${width};` : ''}${height ? `--input-height: ${height};` : ''}`}
+>
+	{#if label}
+		<label for={inputId}>
+			<span>{label}</span>
+			<span class="border">{label}</span>
+		</label>
+	{/if}
+
+	<Svelecte
+		multiple
+		{valueAsObject}
+		{disabled}
+		{inputId}
+		valueField={valueProp}
+		labelField={labelProp}
+		{options}
+		searchable
+		value={selectedValues}
+		onChange={(e: Array<V>) => {
+			// svelecte always emits the full option objects; normalise to the
+			// shape the variant promised: primitives for AsPrimitive,
+			// objects for AsObject. This is what the discriminated
+			// `onchange` typing now guarantees to consumers.
+			if (valueAsObject) {
+				void (onchange as (v: Array<V>) => void | Promise<void>)(e);
+			} else {
+				const primitives = e.map((it) => it[valueProp]);
+				void (onchange as (v: Array<V[VP]>) => void | Promise<void>)(primitives);
+			}
+		}}
+		{name}
+		selectOnTab
+		keepSelectionInList
+		searchProps={{ keepSelectionInList: true }}
+		creatable={false}
+		collapseSelection={collapseSelection ? 'always' : null}
+		deselectMode="toggle"
+		highlightFirstItem={false}
+		placeholder="Please Select {name ? `${an} ${name}` : ''}"
+		selection={collapseSelection ? selection : undefined}
+	>
+		{#snippet option(opt)}
+			{@const option = opt as V}
+			<span class="dropdown-item">
+				<div
+					class="toggle-icon"
+					class:yes={selectedKeys.has(option[valueProp])}
+				>
+					<Icon
+						name="tick"
+						size={Size.MediumSmall}
+					/>
+				</div>
+				{option[labelProp]}</span
+			>
+		{/snippet}
+
+		{#snippet collapsedSelection(selectedOptions: Array<object> /*_i18n*/)}
+			<span class="selection"
+				>{#if selectedOptions.length}{selectedOptions.length}
+					{#if name}{autoPluralise(name, selectedOptions.length)}{/if} Selected
+				{:else}Please Select {#if name}
+						{an} {name}{/if}
+				{/if}</span
+			>
+		{/snippet}
+
+		{#snippet append()}
+			<div class="icons">
+				<Action
+					{disabled}
+					size={Size.Small}
+					noTabIndex
+					colourSet={ColourSet.Auxiliary}
+					onclick={(e: MouseEvent) => {
+						if (isExpanded) {
+							e.stopPropagation();
+						}
+
+						if (selectedValues.length) {
+							// Empty array satisfies both Array<V> and Array<V[VP]>.
+							void (onchange as (v: Array<V> | Array<V[VP]>) => void | Promise<void>)([]);
+						} else if (valueAsObject) {
+							void (onchange as (v: Array<V>) => void | Promise<void>)(options.concat());
+						} else {
+							const primitives = options.map((it) => it[valueProp]);
+							void (onchange as (v: Array<V[VP]>) => void | Promise<void>)(primitives);
+						}
+					}}
+					icon={{
+						name: selectedValues.length ? 'close-menu-cross' : 'manage-product-group',
+						colour: Colour['$ui-blue-10'],
+					}}
+				/>
+
+				<Action
+					{disabled}
+					size={Size.Small}
+					noTabIndex
+					colourSet={ColourSet.Auxiliary}
+					icon={{
+						name: isExpanded ? 'chevron-up' : 'chevron-down',
+						colour: Colour['$ui-blue-10'],
+					}}
+				/>
+			</div>
+		{/snippet}
+		{#snippet toggleIcon()}
+			<div class="nothing"></div>
+		{/snippet}
+	</Svelecte>
+
+	{#snippet selection(/*_selectedOptions: Array<unknown>*/)}
+		<!-- collapsed selection rendered above -->
+	{/snippet}
+</div>
+
 <style>.select-wrapper {
   min-width: var(--input-min-width, 12rem);
   width: var(--input-width, 100%);
@@ -262,24 +285,13 @@
   max-height: 100%;
   box-sizing: border-box;
 }
-.select-wrapper :global(.sv-item--content) {
-  font-size: 0.875rem;
-}
-.select-wrapper :global(.sv-item--wrap.in-dropdown) {
-  cursor: pointer;
-  min-height: 40px;
-  align-items: center;
-}
-.select-wrapper :global(.sv-item--content) {
-  min-height: 1.2rem;
-}
 .select-wrapper :global(.sv-btn-indicator) {
   cursor: pointer;
 }
 .select-wrapper.no-border {
   --sv-border: none;
 }
-.select-wrapper .select-wrapper.force-upwards :global .sv_dropdown.is-open {
+.select-wrapper.force-upwards :global .sv_dropdown.is-open {
   bottom: var(--dropdown-bottom);
 }
 .select-wrapper :global .sv-control {
@@ -300,32 +312,18 @@
 .select-wrapper :global .svelecte.svelecte-control {
   cursor: pointer;
 }
-.select-wrapper :global .sv-item--wrap.in-dropdown {
-  cursor: pointer;
-  min-height: 40px;
-  align-items: center;
-}
-.select-wrapper :global .sv-item--content {
-  min-height: 1.2rem;
-}
 .select-wrapper :global span {
   transition: border-color ease-out 0.15s 0s, background-color ease-out 0.15s 0s, color ease-out 0.15s 0s, fill ease-out 0.15s 0s;
 }
 .select-wrapper :global .sv-control {
   transition: border-color ease-out 0.15s 0s, background-color ease-out 0.15s 0s, color ease-out 0.15s 0s, fill ease-out 0.15s 0s;
 }
-.select-wrapper :global div.sv_dropdown.is-open {
-  z-index: 99;
-}
 .select-wrapper div.nothing {
   height: 0;
   width: 0;
 }
-.select-wrapper .dropdown-item,
 .select-wrapper .selection {
   font-size: 0.875rem;
-}
-.select-wrapper .selection {
   padding-left: 0.5rem;
   white-space: nowrap;
   display: flex;
@@ -349,22 +347,36 @@ div.icons {
   box-sizing: border-box;
 }
 
-.dropdown-item {
+:global .sv-item--wrap.in-dropdown {
+  cursor: pointer;
+  min-height: 40px;
+  align-items: center;
+}
+:global .sv-item--content {
+  font-size: 0.875rem;
+  min-height: 1.2rem;
+}
+:global div.sv_dropdown.is-open {
+  z-index: 99;
+}
+
+:global(.dropdown-item) {
   display: flex;
   flex-flow: row nowrap;
   width: 100%;
   overflow: hidden;
   text-overflow: ellipsis;
   gap: 1rem;
+  font-size: 0.875rem;
   fill: #259fc7;
 }
-.dropdown-item .toggle-icon {
+:global(.dropdown-item) .toggle-icon {
   display: flex;
   align-items: center;
   justify-content: center;
   flex-flow: column nowrap;
   opacity: 0;
 }
-.dropdown-item .toggle-icon.yes {
+:global(.dropdown-item) .toggle-icon.yes {
   opacity: 1;
-}</style>
+}</style>

package/dist/Components/MultiSelectCommonProps.d.ts

@@ -1,16 +1,45 @@
-import type { NonNullableKey, ValueProp } from '../Types/Internal/Misc.js';
+import type { CssLength, NonNullableKey, ValueProp } from '../Types/Internal/Misc.js';
+/**
+ * Keys of `V` whose value is a string. Re-exported for callers that want
+ * a tighter constraint than `NonNullableKey<V>`. Currently aliased to
+ * `NonNullableKey<V>` to avoid cascading into Table subtree consumers
+ * (see workorder MultiSelect P1).
+ */
+export type StringValuedKey<V> = NonNullableKey<V>;
 export interface MultiSelectCommonProps<V extends object, VP extends ValueProp<V>> {
+    /** Available options to choose from. */
     options: Array<V>;
+    /** Singular display name of the entity. */
     name?: string;
+    /** Key of `V` whose value is the human-readable label. */
     labelProp: NonNullableKey<V>;
+    /** Key of `V` whose value is the unique identifier. */
     valueProp: VP;
+    /** Disable the input. */
     disabled?: boolean;
+    /** Whether at least one selection is required. */
     required?: boolean;
+    /** Force the invalid visual state. */
     invalid?: boolean;
+    /** Top label. */
     label?: string;
+    /** DOM id of the underlying svelecte input. */
     inputId?: string;
-    width?: string;
-    height?: string;
-    onchange: (e: Array<V>) => void;
+    /**
+     * CSS width override. Interpolated into a CSS custom property.
+     *
+     * BREAKING (Phase 7.7): was `string`; now requires the `CssLength`
+     * brand. Use the `cssLength('...')` helper to mark intentional CSS
+     * length strings.
+     */
+    width?: CssLength;
+    /**
+     * CSS height override. Interpolated into a CSS custom property.
+     *
+     * BREAKING (Phase 7.7): was `string`; now requires the `CssLength`
+     * brand. Use the `cssLength('...')` helper.
+     */
+    height?: CssLength;
+    /** When true, render a summary instead of chips. */
     collapseSelection?: boolean;
 }

package/dist/Components/MultiSelectPropsAsObject.d.ts

@@ -3,4 +3,9 @@ import type { MultiSelectCommonProps } from './MultiSelectCommonProps.js';
 export interface MultiSelectPropsAsObject<V extends object, VP extends ValueProp<V>> extends MultiSelectCommonProps<V, VP> {
     valueAsObject: true;
     selectedValues: Array<V>;
+    /**
+     * Called when the selection changes. Receives an array of the full
+     * option objects because `valueAsObject` is `true`.
+     */
+    onchange: (newValues: Array<V>) => void | Promise<void>;
 }

package/dist/Components/MultiSelectPropsAsPrimitive.d.ts

@@ -3,4 +3,10 @@ import type { MultiSelectCommonProps } from './MultiSelectCommonProps.js';
 export interface MultiSelectPropsAsPrimitive<V extends object, VP extends ValueProp<V>> extends MultiSelectCommonProps<V, VP> {
     valueAsObject: false;
     selectedValues: Array<V[VP]>;
+    /**
+     * Called when the selection changes. Receives an array of the
+     * primitive key values (`V[VP]`) because `valueAsObject` is `false`.
+     * Do NOT read `.value` off the items -- they are already primitives.
+     */
+    onchange: (newValues: Array<V[VP]>) => void | Promise<void>;
 }

package/dist/Components/Nav/CallbackButtonWithIcon.d.ts

@@ -1,22 +1,43 @@
 import type { Pathname } from '$app/types';
 import type { IconProps } from '../IconProps.js';
+import type { AsyncFlag } from '../../Types/Internal/AsyncFlag.js';
+/**
+ * Either a path-bearing nav button or a callback-bearing nav button.
+ *
+ * Modelled as a proper discriminated union so that providing both
+ * `path` and `callback` is a compile error. Each member uses
+ * `?: never` on the absent discriminant; this is the recommended
+ * template across scoria for "either A or B" prop shapes.
+ */
 export type CallbackButtonWithIcon = CallbackButtonWithPath | CallbackButtonWithCallback;
+/** Fields common to every nav button variant. */
 export interface NavButtonPartial {
+    /** Name of the icon to render to the left of the label. */
     iconName?: IconProps['name'];
+    /** Visible label shown next to the icon. */
     label: string;
+    /** Tooltip text displayed on hover. */
     hoverLabel?: string;
+    /** Optional second line shown below the label. */
     subtitle?: string;
-    visible?: boolean | Promise<boolean>;
+    /**
+     * AsyncFlag of a boolean. Nav button is hidden when this resolves
+     * to false. Defaults to true.
+     */
+    visible?: AsyncFlag<boolean>;
 }
+/** Convenience alias used by some consumers that build `NavButton` directly. */
 export type NavButton = NavButtonPartial & ({
     path: Pathname;
 } | {
     callback: () => void;
 });
+/** Nav button that navigates to a SvelteKit route. */
 export interface CallbackButtonWithPath extends NavButtonPartial {
     path: Pathname;
     callback?: never;
 }
+/** Nav button that fires a callback when clicked. */
 export interface CallbackButtonWithCallback extends NavButtonPartial {
     path?: never;
     callback: () => void;