@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/MultiSelect.svelte

@@ -1,20 +1,25 @@
 <svelte:options runes />
 
-<script lang="ts" generics="V extends object, VP extends ValueProp<V>">
-	import { autoPluralise, generateShortUUID, vowels } from '../Helpers/Helpers.svelte.js';
+<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';
 
-	// HACK selectedValues is mutated by svelecte without asking, so we sometimes have to reverse it without a callback (side effects)
-	let {
+	// NOTE selectedValues is mutated by svelecte without asking, so we sometimes have to reverse it without a callback (side effects)
+	const {
 		label,
-		inputId = generateShortUUID(),
+		inputId = generateWeakId(),
 		options,
 		labelProp,
 		valueProp,
@@ -27,24 +32,37 @@
 		name = 'Item',
 		disabled,
 		required,
-		invalid
+		invalid,
 	}: MultiSelectProps<V, VP> = $props();
 
 	const an = $derived(name && vowels.has(name.at(0)?.toLocaleLowerCase() ?? '') ? 'an' : 'a');
 
-	const hidden = $state(false);
+	// 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);
-		// input?.addEventListener('focus', () => {
-		// 	hidden = true;
-		// });
-		// input?.addEventListener('blur', () => {
-		// 	hidden = false;
-		// });
+		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
-		const dropdownRef = input?.closest('div.svelecte')?.querySelector('.sv_dropdown') ?? 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];
@@ -58,22 +76,24 @@
 			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();
 		};
 	});
 
-	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
@@ -99,7 +119,16 @@
 		searchable
 		value={selectedValues}
 		onChange={(e: Array<V>) => {
-			onchange(e);
+			// 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
@@ -117,21 +146,19 @@
 			<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}
+					class:yes={selectedKeys.has(option[valueProp])}
 				>
-					<Icon name="tick" size={Size.MediumSmall} />
+					<Icon
+						name="tick"
+						size={Size.MediumSmall}
+					/>
 				</div>
 				{option[labelProp]}</span
 			>
 		{/snippet}
 
 		{#snippet collapsedSelection(selectedOptions: Array<object> /*_i18n*/)}
-			<span class="selection" class:hidden
+			<span class="selection"
 				>{#if selectedOptions.length}{selectedOptions.length}
 					{#if name}{autoPluralise(name, selectedOptions.length)}{/if} Selected
 				{:else}Please Select {#if name}
@@ -153,14 +180,18 @@
 						}
 
 						if (selectedValues.length) {
-							onchange([]);
+							// 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 {
-							onchange(options.concat());
+							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']
+						colour: Colour['$ui-blue-10'],
 					}}
 				/>
 
@@ -171,26 +202,18 @@
 					colourSet={ColourSet.Auxiliary}
 					icon={{
 						name: isExpanded ? 'chevron-up' : 'chevron-down',
-						colour: Colour['$ui-blue-10']
+						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} -->
+		<!-- collapsed selection rendered above -->
 	{/snippet}
 </div>
 
@@ -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>

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;

package/dist/Components/Nav/Nav.svelte

@@ -1,12 +1,23 @@
 <svelte:options runes />
 
-<script lang="ts">
+<script
+	lang="ts"
+	generics="T"
+>
 	import { Size } from '../../Types/Internal/Size.js';
 	import Icon from '../Icon.svelte';
 	import type { NavProps } from './NavProps.js';
 	import ServicesNav from './ServicesNav.svelte';
 
-	const { userName, extras, userDialog, serviceTabs, selectedServiceTab }: NavProps = $props();
+	const {
+		userName,
+		extras,
+		userDialog,
+		serviceTabs,
+		selectedServiceTab,
+		brand,
+		// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
+	}: NavProps<T> = $props();
 
 	const userIcon = $derived.by(() => {
 		const names = userName.split(' ');
@@ -23,14 +34,11 @@
 </script>
 
 <nav class="main-navigation">
-	<span class="nav-link hoverable"> FloWMS </span>
-	<!-- HACK swap above for below when a decent landing page has been added -->
-	<!-- <a
-		href={resolve(Locations.Home)}
-		class="nav-link hoverable"
-	>
-		FloWMS
-	</a> -->
+	{#if typeof brand === 'string'}
+		<span class="nav-link brand">{brand}</span>
+	{:else if brand}
+		<span class="nav-link brand">{@render brand()}</span>
+	{/if}
 
 	<div class="nav-link">
 		<button
@@ -58,13 +66,7 @@
 		{/if}
 	</div>
 
-	<div class="nav-search-container">
-		<!-- <TextInput
-			bind:value={searchParam}
-			placeholder="Search for anything"
-			leftIcon={{ name: 'search-1' }}
-		/> -->
-	</div>
+	<div class="nav-search-container"></div>
 	{#if extras}
 		<div class="nav-link spaced selects">
 			{@render extras()}
@@ -104,8 +106,8 @@
   background-color: rgba(0, 0, 0, 0.2);
 }
 
-a.nav-link {
-  color: unset;
+span.brand {
+  font-weight: 600;
 }
 
 div.user {
@@ -142,18 +144,22 @@ nav button {
   width: 100%;
 }
 nav button:hover {
-  background-color: rgba(47, 151, 186, 0.1);
+  background-color: #f4f7f9;
   cursor: pointer;
 }
 
+.nav-search-container {
+  flex: 1;
+}
+
 .spaced {
-  gap: 1rem;
+  gap: 1.5rem;
 }
 
 .user-icon {
   background-color: #dae0e5;
   padding: 0.5rem;
-  border-radius: 17px;
+  border-radius: 4px;
   opacity: 0;
   font-weight: 600;
 }
@@ -161,8 +167,8 @@ nav button:hover {
   opacity: 1;
 }
 .user-icon.single-letter {
-  padding: 0.3rem 0.6rem;
-  border-radius: 14px;
+  padding: 0.375rem 0.75rem;
+  border-radius: 4px;
 }
 
 .main-navigation > *:nth-child(even) {
@@ -171,16 +177,16 @@ nav button:hover {
 .main-navigation > *:nth-child(even)::before {
   content: "";
   height: 1.5rem;
-  border-left: solid 1px #e8e8e8;
-  border-radius: 10px;
+  border-left: solid 1px #e9ecf1;
+  border-radius: 5px;
   left: 0;
   position: absolute;
 }
 .main-navigation > *:nth-child(even)::after {
   content: "";
   height: 1.5rem;
-  border-right: solid 1px #e8e8e8;
-  border-radius: 10px;
+  border-right: solid 1px #e9ecf1;
+  border-radius: 5px;
   position: absolute;
   right: 0;
 }
@@ -197,14 +203,13 @@ nav button:hover {
   justify-content: center;
   flex-flow: row;
   align-items: center;
-  /* flex-grow: 1; */
   min-width: 7.5rem;
   transition: background-color 200ms ease 0s;
 }
 .nav-link.padded {
   padding-left: 1rem;
   padding-right: 1rem;
-  gap: 1rem;
+  gap: 1.5rem;
 }
 
 div.delimited {

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

@@ -1,4 +1,25 @@
 import type { NavProps } from './NavProps.js';
-declare const Nav: import("svelte").Component<NavProps, {}, "">;
-type Nav = ReturnType<typeof Nav>;
+declare function $$render<T>(): {
+    props: NavProps<T>;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Nav: $$IsomorphicComponent;
+type Nav<T> = InstanceType<typeof Nav<T>>;
 export default Nav;

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

@@ -1,9 +1,56 @@
 import type { TabOption } from '../../Types/Internal/TabOption.js';
 import type { Snippet } from 'svelte';
-export interface NavProps {
+/**
+ * Generic `T` parameterises the `TabOption<T>.args` payload type carried by
+ * each entry in {@link serviceTabs} / {@link selectedServiceTab}. Defaults
+ * to `unknown` so existing untyped consumers continue to compile unchanged;
+ * consumers that want a typed `args` payload (e.g. a discriminated union of
+ * service identifiers) can pass it explicitly: `Nav<MyServiceArgs>`.
+ */
+export interface NavProps<T = unknown> {
+    /**
+     * The name of the currently signed-in user. The component derives an
+     * initials badge from this value (first letter of the first one or two
+     * space-separated tokens) and renders the full name beside it.
+     */
     userName: string;
+    /**
+     * Snippet rendered when the user clicks the user badge. Receives a
+     * `closeUserDialog` callback that the snippet must invoke to dismiss
+     * the dialog (the component does not auto-dismiss on outside click).
+     */
     userDialog: Snippet<[closeUserDialog: () => void]>;
-    serviceTabs: Array<TabOption<unknown>>;
-    selectedServiceTab: TabOption<unknown> | undefined;
+    /**
+     * The set of service tabs presented in the services dialog. Each tab
+     * is a `TabOption` whose `args` payload is opaque to scoria; consumers
+     * may carry whatever shape they need through `unknown`.
+     */
+    serviceTabs: ReadonlyArray<TabOption<T>>;
+    /**
+     * The currently selected service tab, or `undefined` if no tab is
+     * selected. Must reference one of `serviceTabs` by identity for the
+     * selection styling to apply.
+     */
+    selectedServiceTab: TabOption<T> | undefined;
+    /**
+     * Optional brand label rendered as the first item in the navigation
+     * bar.
+     *
+     * Accepts either a plain string (rendered as text inside the brand
+     * container) or a `Snippet` for rich brand rendering such as a logo
+     * image, a link, or a custom layout. When omitted the brand slot
+     * renders nothing, which keeps the component free of consumer
+     * specific branding by default.
+     *
+     * Consumer apps that previously relied on the historic hard-coded
+     * "FloWMS" string must now pass `brand="FloWMS"` (or a Snippet) to
+     * preserve the previous visual.
+     */
+    brand?: string | Snippet;
+    /**
+     * Optional snippet rendered between the services button and the user
+     * badge. Typically used to host context-dependent selects such as
+     * warehouse and depot pickers.
+     */
     extras?: Snippet;
 }