@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/Button.svelte

@@ -1,14 +1,15 @@
 <svelte:options runes />
 
-<script module lang="ts">
-	import { TooltipContext } from '../Contexts/TooltipContext.svelte.js';
-	import { Delay } from '../Delay/Delay.js';
+<script
+	module
+	lang="ts"
+>
 	import { passthrough } from '../Helpers/Helpers.svelte.js';
+	import { useTooltip } from '../Helpers/useTooltip.svelte.js';
 	import { Colour, ColourSet } from '../scss/colours.js';
 	import { Side } from '../Types/Internal/Side.js';
 	import { Size } from '../Types/Internal/Size.js';
 	import { Variant } from '../Types/Internal/Variant.js';
-	import { getContext } from 'svelte';
 	import type { ButtonProps } from './ButtonProps.js';
 	import Icon from './Icon.svelte';
 
@@ -24,7 +25,7 @@
 		[Size.DoubleXLarge]: '1.1rem',
 		[Size.TripleXLarge]: '1.2975rem',
 		[Size.FillWidth]: '0.75rem', // TODO decide
-		[Size.FillHeight]: '0' // TODO decide
+		[Size.FillHeight]: '0', // TODO decide
 	};
 
 	// TODO alter the values for these if required
@@ -39,7 +40,7 @@
 		[Size.DoubleXLarge]: '1.1rem',
 		[Size.TripleXLarge]: '1.2975rem',
 		[Size.FillWidth]: '0.75rem', // TODO decide
-		[Size.FillHeight]: '0.75rem' // TODO decide
+		[Size.FillHeight]: '0.75rem', // TODO decide
 	};
 
 	// const fontSizes: Record<Size, string> = {
@@ -68,17 +69,17 @@
 		[Size.DoubleXLarge]: '0.1875rem',
 		[Size.TripleXLarge]: '0.1875rem',
 		[Size.FillWidth]: '0.1875rem', // TODO decide
-		[Size.FillHeight]: '0.1875rem' // TODO decide
+		[Size.FillHeight]: '0.1875rem', // TODO decide
 	};
 
 	const iconColours: Record<ColourSet, Colour | undefined> = {
 		[ColourSet.Primary]: Colour['$ui-white'],
 		[ColourSet.CallToAction]: Colour['$ui-white'],
-		[ColourSet.Secondary]: undefined,
-		[ColourSet.Auxiliary]: undefined,
+		[ColourSet.Secondary]: Colour['$ui-blue-14'],
+		[ColourSet.Auxiliary]: Colour['$font-primary'],
 		[ColourSet.Warning]: Colour['$error-border'],
 		[ColourSet.Error]: Colour['$error-border'],
-		[ColourSet.Info]: Colour['$error-border']
+		[ColourSet.Info]: Colour['$primary-blue-13'],
 	};
 </script>
 
@@ -102,11 +103,34 @@
 		onclick,
 		onfocus,
 		onblur,
+		onkeydown: onkeydownProp,
 		children,
 		relative,
-		noninteractive
+		noninteractive,
 	}: ButtonProps = $props();
-	const tooltipContext = getContext<TooltipContext>(TooltipContext.identifier);
+	function onkeydown(e: KeyboardEvent): void {
+		passthrough(e);
+		if (document.activeElement === e.target) {
+			onkeydownProp?.(e);
+		}
+	}
+
+	// Shared tooltip lifecycle: hover handlers plus unmount-time teardown so
+	// a rapidly-churning host (toolbar, table row) does not leave the global
+	// tooltip host painting against a node that no longer exists. The helper
+	// also exposes an `onclick` hook that we compose with the consumer's
+	// `onclick`. The extra `$effect` dismisses the tooltip when `disabled`
+	// flips to true mid-hover - the disabled element will not fire its own
+	// `mouseleave`.
+	const tt = useTooltip({
+		text: () => label,
+		arrow: () => side ?? Side.Left,
+	});
+	$effect(() => {
+		if (disabled) {
+			tt.onmouseleave();
+		}
+	});
 </script>
 
 <!-- title={label} -->
@@ -114,22 +138,8 @@
 		size
 	]};" -->
 <button
-	onmouseenter={(e) => {
-		if (label) {
-			const rect = (e.target as HTMLButtonElement).getBoundingClientRect();
-			tooltipContext.showTooltip({
-				text: label,
-				arrow: side ?? Side.Left,
-				delay: Delay.Default,
-				rect
-			});
-		}
-	}}
-	onmouseleave={() => {
-		if (label) {
-			tooltipContext.hideTooltip(label);
-		}
-	}}
+	onmouseenter={tt.onmouseenter}
+	onmouseleave={tt.onmouseleave}
 	class:noninteractive
 	class:relative
 	class:default={variant === Variant.Default}
@@ -162,22 +172,20 @@
 	aria-label={label}
 	{disabled}
 	onclick={(e) => {
-		// e.stopImmediatePropagation();
-		// if (dev) {
-		// 	// console.trace();
-		// }
-		if (label) {
-			tooltipContext.hideTooltip(label);
-		}
+		tt.onclick();
 		onclick?.(e);
 	}}
 	{onfocus}
 	{onblur}
-	onkeydown={passthrough}
+	{onkeydown}
 >
 	<div class="icon-container">
 		{#if iconLeft}
-			<Icon {...iconLeft} colour={iconColours[colourSet]} size={iconLeft.size ?? size} />
+			<Icon
+				{...iconLeft}
+				colour={iconColours[colourSet]}
+				size={iconLeft.size ?? size}
+			/>
 		{/if}
 		{#if iconTop}
 			<Icon {...iconTop} />
@@ -189,7 +197,11 @@
 			<Icon {...iconBottom} />
 		{/if}
 		{#if iconRight}
-			<Icon {...iconRight} colour={iconColours[colourSet]} size={iconRight.size ?? size} />
+			<Icon
+				{...iconRight}
+				colour={iconColours[colourSet]}
+				size={iconRight.size ?? size}
+			/>
 		{/if}
 	</div>
 </button>

package/dist/Components/ButtonProps.d.ts

@@ -4,26 +4,91 @@ import type { Size } from '../Types/Internal/Size.js';
 import type { Variant } from '../Types/Internal/Variant.js';
 import type { Snippet } from 'svelte';
 import type { PartialIconProps } from './PartialIconProps.js';
+/**
+ * Props for the foundational {@link Button} component. Every option is optional
+ * because Button is designed to be drop-in-friendly: a bare `<Button>Save</Button>`
+ * renders a secondary, medium-sized push button with no icon or tooltip.
+ */
 export interface ButtonProps {
+    /** Native `<button type>` attribute. Defaults to `'button'` so the button never
+     *  accidentally submits an enclosing form. */
     type?: 'button' | 'submit' | 'reset' | undefined;
+    /** Visual variant: default push button, card surface, inner card, toolbar, or secondary. */
     variant?: Variant | undefined;
+    /** Whether the button renders in its toggled (selected) visual state. */
     toggled?: boolean | undefined;
+    /**
+     * Icon rendered to the left of the label.
+     *
+     * NOTE: The four side props (`iconLeft`, `iconRight`, `iconTop`,
+     * `iconBottom`) are deliberately **not** mutually exclusive at the
+     * type level. Buttons that need icons on more than one side (for
+     * example, a "next" button with a directional chevron on the right
+     * and a status dot on the left) are well established in the design
+     * system. The discriminated-union alternative was evaluated and
+     * deferred (see `Concepts/ButtonIconSides` for the migration plan)
+     * because the type-safety gain is negligible compared with the
+     * breaking-change cost across every existing call site.
+     *
+     * If a single button passes more than one side prop, all of them
+     * render simultaneously. If you need an at-most-one constraint at a
+     * particular call site, enforce it locally with a discriminated
+     * helper before composing `<Button>`.
+     */
     iconLeft?: PartialIconProps | undefined;
+    /**
+     * Icon rendered above the label. See `iconLeft` for the rationale on
+     * why this is independently optional rather than part of a
+     * discriminated union.
+     */
     iconTop?: PartialIconProps | undefined;
+    /**
+     * Icon rendered to the right of the label. See `iconLeft` for the
+     * rationale on why this is independently optional rather than part
+     * of a discriminated union.
+     */
     iconRight?: PartialIconProps | undefined;
+    /**
+     * Icon rendered below the label. See `iconLeft` for the rationale on
+     * why this is independently optional rather than part of a
+     * discriminated union.
+     */
     iconBottom?: PartialIconProps | undefined;
+    /** Prevent the label from wrapping when the button is narrower than its content. */
     nowrap?: boolean | undefined;
+    /** Side of the trigger the tooltip arrow points from. Defaults to Side.Left. */
     side?: Side | undefined;
+    /** Sizing token controlling padding, font size, and border width. Defaults to Size.Medium. */
     size?: Size | undefined;
+    /** Render the border as a dashed outline. */
     dashed?: boolean | undefined;
+    /** Disable interaction. Sets the native `disabled` attribute and hides the tooltip. */
     disabled?: boolean | undefined;
+    /** Stretch the button to fill its container's inline axis. */
     fullWidth?: boolean | undefined;
-    label?: string | null | undefined;
+    /**
+     * Accessible name. Doubles as the tooltip text shown on hover. An
+     * empty string or `undefined` suppresses the tooltip and aria-label.
+     *
+     * BREAKING (vNext): the `null` variant has been removed. Pass
+     * `undefined` (or omit the prop) instead of `null` to indicate the
+     * absence of a label.
+     */
+    label?: string | undefined;
+    /** Semantic colour set used for foreground/background. Defaults to ColourSet.Secondary. */
     colourSet?: ColourSet | undefined;
+    /** Click handler. Tooltip is hidden synchronously before the handler fires. */
     onclick?: ((e: MouseEvent) => void) | undefined;
+    /** Native focus event handler. */
     onfocus?: ((e: FocusEvent) => void) | undefined;
+    /** Native blur event handler. */
     onblur?: ((e: FocusEvent) => void) | undefined;
+    /** Keydown handler. Composed with `passthrough` so scanner workflows continue to fire. */
+    onkeydown?: ((e: KeyboardEvent) => void) | undefined;
+    /** Snippet rendered between the optional icons. Typically the visible label. */
     children?: Snippet;
+    /** Apply `position: relative` so absolutely-positioned overlays anchor to the button. */
     relative?: boolean;
+    /** Visually present the button without interactive affordances (cursor stays at not-allowed). */
     noninteractive?: boolean;
 }

package/dist/Components/Checkbox.svelte

@@ -1,44 +1,37 @@
 <svelte:options runes />
 
-<script lang="ts" module>
-	import { generateShortUUID } from '../Helpers/Helpers.svelte.js';
+<script
+	lang="ts"
+	module
+>
+	import { generateWeakId } from '../Helpers/Helpers.svelte.js';
 	import { Size } from '../Types/Internal/Size.js';
-	import type { ChangeEventHandler } from 'svelte/elements';
+	import type { CheckboxProps } from './CheckboxProps.js';
 	import Icon from './Icon.svelte';
-	import type { IconProps } from './IconProps.js';
-
-	export interface CheckboxProps {
-		value: boolean;
-		id?: string;
-		icon?: IconProps;
-		size?: Size;
-		label?: string;
-		disabled?: boolean;
-		onchange?: ChangeEventHandler<HTMLInputElement>;
-	}
 </script>
 
 <script lang="ts">
 	let {
 		value = false,
-		id = generateShortUUID(),
+		id = generateWeakId(),
 		icon,
 		size,
 		label,
 		disabled,
-		onchange
+		onchange,
 	}: CheckboxProps = $props();
 </script>
 
 {#if icon}
-	<!-- style="--inner-checkbox-container-width: {(size != undefined ? widths[size] : undefined) ??
-			'2.75rem'};" -->
 	<div
 		class="outer-checkbox-container"
 		class:fill-width={size === Size.FillWidth}
 		class:fill-height={size === Size.FillHeight}
 	>
-		<div class="inner-checkbox-container with-icon" class:disabled>
+		<div
+			class="inner-checkbox-container with-icon"
+			class:disabled
+		>
 			<input
 				{id}
 				name={id}
@@ -48,24 +41,50 @@
 				{disabled}
 				checked={value}
 			/>
-			<label class="icon-label" for={id} class:disabled>
-				<Icon {...icon} size={icon.size ?? size ?? Size.DoubleXLarge} />
+			<label
+				class="icon-label"
+				for={id}
+				class:disabled
+			>
+				<Icon
+					{...icon}
+					size={icon.size ?? size ?? Size.DoubleXLarge}
+				/>
 			</label>
 		</div>
 		{#if label}
-			<label class="text-label" for={id}>{label}</label>
+			<label
+				class="text-label"
+				for={id}>{label}</label
+			>
 		{/if}
 	</div>
 {:else}
-	<div class="checkbox-container">
-		<input {id} {onchange} type="checkbox" checked={value} {disabled} />
+	<div
+		class="checkbox-container"
+		class:compact={size === Size.Tiny ||
+			size === Size.Small ||
+			size === Size.MediumSmall ||
+			size === Size.Medium}
+	>
+		<input
+			{id}
+			{onchange}
+			type="checkbox"
+			checked={value}
+			{disabled}
+		/>
 		{#if label}
-			<label class="text-label" for={id}>{label}</label>
+			<label
+				class="text-label"
+				for={id}>{label}</label
+			>
 		{/if}
 	</div>
 {/if}
 
 <style>.outer-checkbox-container {
+  box-sizing: border-box;
   display: flex;
   flex-flow: row nowrap;
   align-items: stretch;
@@ -79,7 +98,7 @@
   height: 100%;
 }
 .outer-checkbox-container:hover div.inner-checkbox-container:not(.disabled) {
-  border: solid 2px #676774;
+  border: solid 2px #5a707f;
 }
 .outer-checkbox-container .icon-label {
   width: 100%;
@@ -99,11 +118,19 @@
   width: 3rem;
   height: 3rem;
 }
+.checkbox-container.compact input {
+  width: 1.25rem;
+  height: 1.25rem;
+}
 
 label.text-label {
   padding-left: 1rem;
 }
 
+.checkbox-container.compact label.text-label {
+  padding-left: 0.5rem;
+}
+
 input {
   cursor: pointer;
   accent-color: var(--colour, #259fc7);
@@ -122,24 +149,25 @@ input.with-icon {
 }
 
 div.inner-checkbox-container {
+  box-sizing: border-box;
   width: 100%;
   height: 100%;
   background-color: #ffffff;
   color: #ffffff;
   fill: #ffffff;
-  border: solid 2px #8f8f9d;
+  border: solid 2px #adbbc5;
   border-radius: 4px;
 }
 div.inner-checkbox-container label:not(.disabled):hover {
   color: #8096a5;
   fill: #8096a5;
 }
-div.inner-checkbox-container input:checked:not([disabled=true]) + label {
+div.inner-checkbox-container input:checked:not([disabled]) + label {
   background-color: #259fc7;
   color: #ffffff;
   fill: #ffffff;
 }
-div.inner-checkbox-container input:checked:not([disabled=true]) + label:hover {
+div.inner-checkbox-container input:checked:not([disabled]) + label:hover {
   color: #1f81a0;
   fill: #1f81a0;
 }

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

@@ -1,15 +1,4 @@
-import { Size } from '../Types/Internal/Size.js';
-import type { ChangeEventHandler } from 'svelte/elements';
-import type { IconProps } from './IconProps.js';
-export interface CheckboxProps {
-    value: boolean;
-    id?: string;
-    icon?: IconProps;
-    size?: Size;
-    label?: string;
-    disabled?: boolean;
-    onchange?: ChangeEventHandler<HTMLInputElement>;
-}
+import type { CheckboxProps } from './CheckboxProps.js';
 declare const Checkbox: import("svelte").Component<CheckboxProps, {}, "">;
 type Checkbox = ReturnType<typeof Checkbox>;
 export default Checkbox;

package/dist/Components/CheckboxProps.d.ts

@@ -0,0 +1,27 @@
+import type { Size } from '../Types/Internal/Size.js';
+import type { ChangeEventHandler } from 'svelte/elements';
+import type { IconProps } from './IconProps.js';
+/**
+ * Props for the {@link Checkbox} component.
+ *
+ * Supports a label-only variant and an icon variant. When `icon` is
+ * provided the native checkbox is visually replaced by the icon, with
+ * the underlying `<input>` kept in the DOM (visually hidden) to retain
+ * keyboard and screen-reader semantics.
+ */
+export interface CheckboxProps {
+    /** Current checked state. */
+    value: boolean;
+    /** `id` on the `<input>`. Defaults to a generated short UUID. */
+    id?: string;
+    /** Optional icon rendered in place of the native checkbox UI. */
+    icon?: IconProps;
+    /** Render size token (drives the visual scale). */
+    size?: Size;
+    /** Visible label next to the checkbox. */
+    label?: string;
+    /** Native `disabled` attribute. */
+    disabled?: boolean;
+    /** Native `change` event handler. */
+    onchange?: ChangeEventHandler<HTMLInputElement>;
+}

package/dist/Components/CheckboxProps.js

@@ -0,0 +1 @@
+export {};

package/dist/Components/CollapsibleCard.svelte

@@ -1,5 +1,12 @@
 <svelte:options runes />
 
+<script
+	lang="ts"
+	module
+>
+	import { generateWeakId } from '../Helpers/Helpers.svelte.js';
+</script>
+
 <script lang="ts">
 	import { loadingText } from '../Helpers/Helpers.svelte.js';
 	import { Size } from '../Types/Internal/Size.js';
@@ -10,23 +17,20 @@
 	let {
 		title,
 		subtitle,
-		maxHeight: maxHeight,
+		maxHeight,
 		children,
 		grow,
 		isCollapsed = $bindable(false),
 	}: CollapsibleCardProps = $props();
 
-	let cardRef: HTMLDivElement | undefined = $state();
+	const contentId = `collapsible-card-${generateWeakId()}`;
 
-	let cardMaxHeight = $derived(
-		cardRef && maxHeight != undefined && maxHeight > 0 && `${maxHeight}px`
-	);
+	const cardMaxHeight = $derived(maxHeight != null && maxHeight > 0 ? `${maxHeight}px` : undefined);
 </script>
 
 <div
 	class="collapsible-card"
-	bind:this={cardRef}
-	style={cardMaxHeight ? `--card-max-height: ${cardMaxHeight};` : ''}
+	style={cardMaxHeight != null ? `--card-max-height: ${cardMaxHeight};` : undefined}
 	class:is-collapsed={isCollapsed}
 	class:grow
 >
@@ -36,14 +40,16 @@
 			{#if subtitle}
 				{#await subtitle}
 					<span>{loadingText}</span>
-				{:then subtitle}
-					<span>{subtitle}</span>
+				{:then resolvedSubtitle}
+					<span>{resolvedSubtitle}</span>
 				{/await}
 			{/if}
 		</div>
 		<div class="right">
 			<Action
 				label={isCollapsed ? 'Expand' : 'Collapse'}
+				aria-expanded={!isCollapsed}
+				aria-controls={contentId}
 				onclick={() => {
 					isCollapsed = !isCollapsed;
 				}}
@@ -58,8 +64,10 @@
 	</div>
 
 	<div
+		id={contentId}
 		class="content"
 		class:is-collapsed={isCollapsed}
+		aria-hidden={isCollapsed}
 	>
 		{#if children}
 			{@render children()}
@@ -68,7 +76,7 @@
 </div>
 
 <style>.collapsible-card {
-  background-color: white;
+  background-color: #ffffff;
   display: flex;
   flex-flow: column nowrap;
   flex-shrink: 1;
@@ -111,32 +119,55 @@
 }
 .collapsible-card:not(.is-collapsed) .heading {
   margin-bottom: 1rem;
-  border-bottom: solid 1px #e8e8e8;
+  border-bottom: solid 1px #dae0e5;
 }
 
 div.content {
   display: flex;
   flex-flow: column nowrap;
-  transition: max-height ease-out 0.15s 0s, opacity ease-out 0.15s 0.1s;
+}
+@media (prefers-reduced-motion: no-preference) {
+  div.content {
+    transition: max-height ease-out 0.15s 0s, opacity ease-out 0.15s 0.1s;
+  }
+}
+div.content {
   max-height: var(--card-max-height, 100%);
   overflow: auto;
   height: var(--card-max-height);
   opacity: 1;
   width: 100%;
 }
+@media (prefers-reduced-motion: no-preference) {
+  div.content.is-collapsed {
+    animation: accordion ease-out 0.15s 0s forwards;
+  }
+}
 div.content.is-collapsed {
-  animation: accordion ease-out 0.15s 0s forwards;
   max-height: 0px;
+  opacity: 0;
+  overflow: hidden;
 }
-@keyframes accordion {
-  0% {
-    opacity: 1;
-    max-height: var(--card-max-height, 90vh);
-    overflow: auto;
+@media (prefers-reduced-motion: no-preference) {
+  @keyframes accordion {
+    0% {
+      opacity: 1;
+      max-height: var(--card-max-height, 90vh);
+      overflow: auto;
+    }
+    100% {
+      opacity: 0;
+      max-height: 0px;
+      overflow: hidden;
+    }
   }
-  100% {
-    opacity: 0;
-    max-height: 0px;
-    overflow: hidden;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .heading,
+  div.content,
+  div.content.is-collapsed {
+    animation-duration: 0.001ms !important;
+    transition-duration: 0.001ms !important;
   }
 }</style>

package/dist/Components/CollapsibleCardProps.d.ts

@@ -1,9 +1,30 @@
 import type { Snippet } from 'svelte';
+import type { Pixels } from '../Types/Internal/Misc.js';
+/**
+ * Props for the {@link CollapsibleCard} container.
+ */
 export interface CollapsibleCardProps {
+    /** Heading text displayed in the card header. */
     title?: string;
+    /**
+     * Optional subtitle rendered beneath the heading. May be a string or
+     * a `Promise<string>` that resolves asynchronously. When passing a
+     * Promise, callers should memoise the reference so that re-renders
+     * do not re-suspend with a fresh Promise on every update.
+     */
     subtitle?: string | Promise<string>;
+    /** Snippet rendered inside the collapsible body. */
     children?: Snippet;
-    maxHeight?: number;
+    /**
+     * Maximum height of the content area in pixels. When omitted the
+     * card grows to fit its content. Branded as `Pixels` for clarity.
+     */
+    maxHeight?: Pixels;
+    /** Whether the card should flex-grow to fill its container. */
     grow?: boolean;
+    /**
+     * Whether the card is currently collapsed. Bindable so the
+     * collapsed state can be hoisted to the parent and persisted.
+     */
     isCollapsed?: boolean;
 }