@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/DataMatrixIcon.svelte

@@ -3,26 +3,83 @@
 <script lang="ts">
 	import { passthrough } from '../Helpers/Helpers.svelte.js';
 	import type { DataMatrixIconProps } from './DataMatrixIconProps.js';
+	import Icon from './Icon.svelte';
 
-	const { icon, interactive = false, title, oncontextmenu }: DataMatrixIconProps = $props();
+	const {
+		icon,
+		interactive = false,
+		title,
+		oncontextmenu,
+		ariaLabel = 'Edit Barcode Value',
+	}: DataMatrixIconProps = $props();
 
 	let svgContainer = $state<HTMLDivElement | null>(null);
 
+	// Track the last SVG we mounted so the effect only re-runs when the
+	// underlying SVG identity changes. Repeated parent renders that hand
+	// back the same node should NOT force a DOM replacement; each replace
+	// forces layout, which becomes expensive with many barcodes on a screen.
+	let lastSvg: SVGSVGElement | undefined = undefined;
+
+	/**
+	 * Defensively sanitise the SVG before mounting it.
+	 *
+	 * SECURITY: although the prop is branded `DataMatrixSvg` to discourage
+	 * arbitrary callers, the brand is type-only. As defence in depth we
+	 * strip `<script>` nodes plus any `on*` / `href` / `xlink:href`
+	 * attributes from the cloned tree before it enters the document. This
+	 * neutralises stored-XSS sinks (`<script>`, `<image href="javascript:...">`,
+	 * inline event handlers) without depending on caller discipline.
+	 */
+	function sanitiseSvg(node: SVGSVGElement): void {
+		node.querySelectorAll('script').forEach((s) => {
+			s.remove();
+		});
+		node.querySelectorAll('*').forEach((el) => {
+			for (const attr of [...el.attributes]) {
+				const lower = attr.name.toLowerCase();
+				if (lower.startsWith('on') || lower === 'href' || lower === 'xlink:href') {
+					el.removeAttribute(attr.name);
+				}
+			}
+		});
+	}
+
 	$effect(() => {
-		if (svgContainer != null) {
-			// eslint-disable-next-line svelte/no-dom-manipulating
-			svgContainer.innerHTML = '';
-			icon.setAttribute('width', '64');
-			icon.setAttribute('height', '64');
+		if (icon.kind !== 'svg') {
+			// icon-props branch renders an <Icon> below; nothing for the
+			// SVG mount effect to do, and we clear the stale mount so a
+			// later toggle back to kind: 'svg' re-mounts correctly.
+			if (svgContainer != null && lastSvg !== undefined) {
+				// Mirror of the mount path below; `replaceChildren()` is the
+				// cheapest way to detach the previously cloned SVG.
+				// eslint-disable-next-line svelte/no-dom-manipulating
+				svgContainer.replaceChildren();
+				lastSvg = undefined;
+			}
+			return;
+		}
+		const source = icon.svg;
+		if (svgContainer != null && source !== lastSvg) {
+			// Clone so we never mutate the consumer-supplied node. If the
+			// same SVG is rendered into multiple DataMatrixIcon instances or
+			// reused elsewhere the original keeps its original attributes.
+			const local = source.cloneNode(true) as SVGSVGElement;
+			sanitiseSvg(local);
+			local.setAttribute('width', '64');
+			local.setAttribute('height', '64');
+			// `replaceChildren` is cheaper than `innerHTML = ''` + `appendChild`:
+			// it skips the HTML parse step and only touches the child list.
 			// eslint-disable-next-line svelte/no-dom-manipulating
-			svgContainer.appendChild(icon);
+			svgContainer.replaceChildren(local);
+			lastSvg = source;
 		}
 	});
 </script>
 
 {#if interactive}
 	<button
-		aria-label="Edit Barcode Value"
+		aria-label={ariaLabel}
 		onkeydown={passthrough}
 		title="Right click to edit barcode value for the {title} command"
 		oncontextmenu={(e) => {
@@ -32,10 +89,24 @@
 			}
 		}}
 	>
-		<div class="fit" bind:this={svgContainer}></div>
+		<div
+			class="fit"
+			bind:this={svgContainer}
+		>
+			{#if icon.kind === 'icon-props'}
+				<Icon {...icon.iconProps} />
+			{/if}
+		</div>
 	</button>
 {:else}
-	<div class="fit" bind:this={svgContainer}></div>
+	<div
+		class="fit"
+		bind:this={svgContainer}
+	>
+		{#if icon.kind === 'icon-props'}
+			<Icon {...icon.iconProps} />
+		{/if}
+	</div>
 {/if}
 
 <style>button {
@@ -46,5 +117,5 @@
 div.fit {
   background-color: #ffffff;
   display: flex;
-  padding: 8px;
+  padding: 0.5rem;
 }</style>

package/dist/Components/DataMatrixIconProps.d.ts

@@ -1,6 +1,78 @@
+import type { PartialIconProps } from './PartialIconProps.js';
+/**
+ * Branded SVG type indicating that the element was produced by the
+ * built-in `DATAMatrix` encoder and is therefore considered trusted
+ * for direct DOM insertion by `DataMatrixIcon`.
+ *
+ * Callers should not construct this manually; the `DATAMatrix()`
+ * factory in `$lib/Helpers/Datamatrix.js` is the only sanctioned
+ * source. If you need to pass a non-encoder-built SVG, that path
+ * must go through an explicit sanitiser first.
+ */
+export type DataMatrixSvg = SVGSVGElement & {
+    readonly __brand: 'DataMatrix';
+};
+/**
+ * Discriminated input for {@link DataMatrixIcon}.
+ *
+ * - `{ kind: 'svg', svg }` mounts a pre-generated, trusted SVG element
+ *   produced by `DATAMatrix()`. This is the primary path and the only
+ *   one currently exercised by in-tree consumers (`AlertModal`, `Modal`,
+ *   `TouchModal`, `UtilityButton`).
+ * - `{ kind: 'icon-props', iconProps }` renders an ordinary {@link Icon}
+ *   in place of the matrix barcode. This is a forward-compatible escape
+ *   hatch for environments where a barcode would be inappropriate (for
+ *   example, mobile clients that cannot present a scanner-friendly
+ *   barcode, or test fixtures that just want a placeholder glyph). The
+ *   icon path bypasses the SVG sanitiser; only use it with statically
+ *   declared `PartialIconProps` values, never with user-derived input.
+ *
+ * Phase 7.7 (BREAKING): introduced as a defensive widening. The previous
+ * single-shape `icon: DataMatrixSvg` prop was deferred in Phase 5; the
+ * discriminator lands now so future consumers can opt into the
+ * icon-props path without another breaking change. Existing call sites
+ * migrate from `icon={svg}` to `icon={{ kind: 'svg', svg }}`.
+ */
+export type DataMatrixIconInput = {
+    kind: 'svg';
+    svg: DataMatrixSvg;
+} | {
+    kind: 'icon-props';
+    iconProps: PartialIconProps;
+};
+/**
+ * Props for the {@link DataMatrixIcon} component.
+ *
+ * SECURITY: when `icon.kind === 'svg'` the SVG is mounted into the DOM
+ * via `replaceChildren`. The branded `DataMatrixSvg` type narrows the
+ * public surface so only encoder output reaches this component. The
+ * component additionally defensively strips `<script>` nodes and
+ * event-handler / `href` attributes before mounting. The
+ * `kind: 'icon-props'` branch delegates to {@link Icon} and does not
+ * touch the SVG sanitiser.
+ */
 export interface DataMatrixIconProps {
-    icon: SVGSVGElement;
+    /**
+     * Discriminated icon input. Pass `{ kind: 'svg', svg }` for the
+     * traditional barcode path (output of `DATAMatrix()`), or
+     * `{ kind: 'icon-props', iconProps }` to render a placeholder
+     * {@link Icon} instead.
+     *
+     * BREAKING (Phase 7.7): was `DataMatrixSvg`; now the discriminated
+     * `DataMatrixIconInput`. Migrate by wrapping existing SVG values:
+     * `icon={svg}` -> `icon={{ kind: 'svg', svg }}`.
+     */
+    icon: DataMatrixIconInput;
+    /** When true, render inside a `<button>` and forward right-click via `oncontextmenu`. */
     interactive?: boolean;
+    /** Short human-readable name of the command this barcode represents. Interpolated into the tooltip. */
     title: string;
+    /** Right-click handler. Only fires when `interactive` is true. */
     oncontextmenu?: (e: MouseEvent) => void;
+    /**
+     * Accessible label for the interactive variant. Defaults to
+     * `"Edit Barcode Value"`. Provide a localised string when running
+     * outside an English-language context.
+     */
+    ariaLabel?: string;
 }

package/dist/Components/DateInput.svelte

@@ -1,16 +1,33 @@
 <svelte:options runes />
 
-<script lang="ts" module>
+<script
+	lang="ts"
+	module
+>
+	import { cssLength, passthrough } from '../Helpers/Helpers.svelte.js';
 	import { InputVariant } from '../Types/Internal/InputVariant.js';
-	import type { InputDate } from '../Types/Internal/Misc.js';
 	import { Size } from '../Types/Internal/Size.js';
 	import type { DateInputProps } from './DateInputProps.js';
 	import Icon from './Icon.svelte';
+
+	function openPicker(ref: HTMLInputElement | undefined): void {
+		ref?.showPicker();
+	}
+
+	function submitAncestorForm(e: KeyboardEvent): void {
+		if (e.key !== 'Enter') {
+			return;
+		}
+		e.preventDefault();
+		const target = e.target as HTMLElement | undefined;
+		const form = target?.closest('form') as HTMLFormElement | undefined;
+		form?.requestSubmit();
+	}
 </script>
 
 <script lang="ts">
 	let {
-		value = $bindable('' as InputDate),
+		value = $bindable(''),
 		label,
 		placeholder,
 		required = false,
@@ -18,17 +35,40 @@
 		variant = InputVariant.Default,
 		min,
 		max,
-		type = 'date',
+		type,
 		disabled,
 		leftIcon,
 		rightIcon,
-		inputRef,
+		inputRef = $bindable(),
 		invalid,
 		onblur,
-		onfocus
+		onfocus,
+		onchange,
 	}: DateInputProps = $props();
 
-	let isInvalid = $derived((required && !value?.trim()) || invalid);
+	const isInvalid = $derived((required && !value.trim()) || invalid);
+
+	function onkeydown(e: KeyboardEvent): void {
+		if (e.key === 'Enter') {
+			submitAncestorForm(e);
+			return;
+		}
+		passthrough(e);
+	}
+
+	function ondblclick(): void {
+		openPicker(inputRef);
+	}
+
+	function onauxclick(e: MouseEvent): void {
+		e.preventDefault();
+		openPicker(inputRef);
+	}
+
+	function handleChange(e: Event): void {
+		const next = (e.target as HTMLInputElement).value;
+		void onchange?.(next === '' ? null : (next as never));
+	}
 </script>
 
 <div
@@ -45,7 +85,10 @@
 				>{label}{#if optional}<i>&nbsp;- optional</i>{/if}</span
 			>
 			{#if variant === InputVariant.Default}
-				<span class="border" class:invalid={isInvalid}
+				<span
+					aria-hidden="true"
+					class="border"
+					class:invalid={isInvalid}
 					>{label}{#if optional}<i>&nbsp;- optional</i>{/if}</span
 				>
 			{/if}
@@ -56,10 +99,10 @@
 					name={leftIcon.name}
 					size={leftIcon.size ?? Size.Medium}
 					float
-					left="0.75rem"
-					top="50%"
-					anchorX="0"
-					anchorY="-50%"
+					left={cssLength('0.75rem')}
+					top={cssLength('50%')}
+					anchorX={cssLength('0')}
+					anchorY={cssLength('-50%')}
 				/>
 			{/if}
 			<input
@@ -67,39 +110,31 @@
 				class:invalid={isInvalid}
 				class:left-pad={leftIcon != undefined}
 				class:right-pad={rightIcon != undefined}
+				aria-invalid={isInvalid || undefined}
 				{type}
 				bind:value
 				{onblur}
 				{onfocus}
-				ondblclick={() => inputRef?.showPicker()}
-				onauxclick={(e) => {
-					e.preventDefault();
-					inputRef?.showPicker();
-				}}
+				{ondblclick}
+				{onauxclick}
 				bind:this={inputRef}
 				{min}
 				{max}
 				{placeholder}
 				{required}
 				{disabled}
-				onkeydown={(e) => {
-					if (e.key === 'Enter') {
-						e.preventDefault();
-						(
-							(e.target as HTMLElement | undefined)?.closest('form') as HTMLFormElement | undefined
-						)?.requestSubmit();
-					}
-				}}
+				{onkeydown}
+				onchange={handleChange}
 			/>
 			{#if rightIcon}
 				<Icon
 					name={rightIcon.name}
 					size={rightIcon.size ?? Size.Medium}
 					float
-					right="0.5rem"
-					top="50%"
-					anchorX="0"
-					anchorY="-50%"
+					right={cssLength('0.5rem')}
+					top={cssLength('50%')}
+					anchorX={cssLength('0')}
+					anchorY={cssLength('-50%')}
 				/>
 			{/if}
 		</div>

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

@@ -1,4 +1,4 @@
 import type { DateInputProps } from './DateInputProps.js';
-declare const DateInput: import("svelte").Component<DateInputProps, {}, "value">;
+declare const DateInput: import("svelte").Component<DateInputProps, {}, "value" | "inputRef">;
 type DateInput = ReturnType<typeof DateInput>;
 export default DateInput;

package/dist/Components/DateOnlyInputProps.d.ts

@@ -1,21 +1,47 @@
 import type { InputVariant } from '../Types/Internal/InputVariant.js';
 import type { InputDate } from '../Types/Internal/Misc.js';
 import type { PartialIconProps } from './PartialIconProps.js';
+/**
+ * Props for the `date` variant of {@link DateInput}.
+ *
+ * The `type` discriminator is required to keep the union with
+ * {@link DateTimeInputProps} fully discriminable. `value` is branded
+ * with {@link InputDate}; the empty string is a known sentinel that
+ * the consumer is expected to handle when binding.
+ */
 export interface DateOnlyInputProps {
-    value?: InputDate | null;
+    /** Discriminator. Must be the literal `'date'`. */
+    type: 'date';
+    /** Bindable date value. `''` represents "no date selected". */
+    value?: InputDate | '';
+    /** Label rendered above the input. */
     label?: string;
+    /** Native `placeholder` attribute. */
     placeholder?: string;
+    /** Native `required` attribute. */
     required?: boolean;
-    variant?: InputVariant;
-    min?: string;
-    max?: string;
+    /** Render the "- optional" suffix next to `label`. */
     optional?: boolean;
-    type?: 'date';
+    /** Render variant. See {@link InputVariant}. */
+    variant?: InputVariant;
+    /** Native `min` constraint. */
+    min?: InputDate;
+    /** Native `max` constraint. */
+    max?: InputDate;
+    /** Native `disabled` attribute. */
     disabled?: boolean;
+    /** Icon rendered on the left of the input. */
     leftIcon?: PartialIconProps;
+    /** Icon rendered on the right of the input. */
     rightIcon?: PartialIconProps;
+    /** Bindable reference to the underlying `<input>` element. */
     inputRef?: HTMLInputElement;
+    /** Force the invalid visual state. */
     invalid?: boolean;
+    /** Blur handler. */
     onblur?: (e: FocusEvent) => void;
+    /** Focus handler. */
     onfocus?: (e: FocusEvent) => void;
+    /** Change handler. May return `void` or `Promise<void>`. */
+    onchange?: (value: InputDate | null) => void | Promise<void>;
 }