@lavalogic/scoria 0.35.0 → 0.37.0

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,111 +1,146 @@
-<svelte:options runes />
-
-<script lang="ts" module>
-	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';
-</script>
-
-<script lang="ts">
-	let {
-		value = $bindable('' as InputDate),
-		label,
-		placeholder,
-		required = false,
-		optional,
-		variant = InputVariant.Default,
-		min,
-		max,
-		type = 'date',
-		disabled,
-		leftIcon,
-		rightIcon,
-		inputRef,
-		invalid,
-		onblur,
-		onfocus
-	}: DateInputProps = $props();
-
-	let isInvalid = $derived((required && !value?.trim()) || invalid);
-</script>
-
-<div
-	class="error-wrapper"
-	class:for-modal={variant == InputVariant.Modal}
-	class:for-table={variant == InputVariant.Table}
->
-	<label class:for-modal={variant == InputVariant.Modal}>
-		{#if label}
-			<span
-				class="top-label"
-				class:for-default={variant === InputVariant.Default}
-				class:invalid={isInvalid}
-				>{label}{#if optional}<i>&nbsp;- optional</i>{/if}</span
-			>
-			{#if variant === InputVariant.Default}
-				<span class="border" class:invalid={isInvalid}
-					>{label}{#if optional}<i>&nbsp;- optional</i>{/if}</span
-				>
-			{/if}
-		{/if}
-		<div class="icon-container">
-			{#if leftIcon}
-				<Icon
-					name={leftIcon.name}
-					size={leftIcon.size ?? Size.Medium}
-					float
-					left="0.75rem"
-					top="50%"
-					anchorX="0"
-					anchorY="-50%"
-				/>
-			{/if}
-			<input
-				step={type === 'datetime-local' ? 1 : 'any'}
-				class:invalid={isInvalid}
-				class:left-pad={leftIcon != undefined}
-				class:right-pad={rightIcon != undefined}
-				{type}
-				bind:value
-				{onblur}
-				{onfocus}
-				ondblclick={() => inputRef?.showPicker()}
-				onauxclick={(e) => {
-					e.preventDefault();
-					inputRef?.showPicker();
-				}}
-				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();
-					}
-				}}
-			/>
-			{#if rightIcon}
-				<Icon
-					name={rightIcon.name}
-					size={rightIcon.size ?? Size.Medium}
-					float
-					right="0.5rem"
-					top="50%"
-					anchorX="0"
-					anchorY="-50%"
-				/>
-			{/if}
-		</div>
-	</label>
-</div>
-
+<svelte:options runes />
+
+<script
+	lang="ts"
+	module
+>
+	import { cssLength, passthrough } from '../Helpers/Helpers.svelte.js';
+	import { InputVariant } from '../Types/Internal/InputVariant.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(''),
+		label,
+		placeholder,
+		required = false,
+		optional,
+		variant = InputVariant.Default,
+		min,
+		max,
+		type,
+		disabled,
+		leftIcon,
+		rightIcon,
+		inputRef = $bindable(),
+		invalid,
+		onblur,
+		onfocus,
+		onchange,
+	}: DateInputProps = $props();
+
+	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
+	class="error-wrapper"
+	class:for-modal={variant == InputVariant.Modal}
+	class:for-table={variant == InputVariant.Table}
+>
+	<label class:for-modal={variant == InputVariant.Modal}>
+		{#if label}
+			<span
+				class="top-label"
+				class:for-default={variant === InputVariant.Default}
+				class:invalid={isInvalid}
+				>{label}{#if optional}<i>&nbsp;- optional</i>{/if}</span
+			>
+			{#if variant === InputVariant.Default}
+				<span
+					aria-hidden="true"
+					class="border"
+					class:invalid={isInvalid}
+					>{label}{#if optional}<i>&nbsp;- optional</i>{/if}</span
+				>
+			{/if}
+		{/if}
+		<div class="icon-container">
+			{#if leftIcon}
+				<Icon
+					name={leftIcon.name}
+					size={leftIcon.size ?? Size.Medium}
+					float
+					left={cssLength('0.75rem')}
+					top={cssLength('50%')}
+					anchorX={cssLength('0')}
+					anchorY={cssLength('-50%')}
+				/>
+			{/if}
+			<input
+				step={type === 'datetime-local' ? 1 : 'any'}
+				class:invalid={isInvalid}
+				class:left-pad={leftIcon != undefined}
+				class:right-pad={rightIcon != undefined}
+				aria-invalid={isInvalid || undefined}
+				{type}
+				bind:value
+				{onblur}
+				{onfocus}
+				{ondblclick}
+				{onauxclick}
+				bind:this={inputRef}
+				{min}
+				{max}
+				{placeholder}
+				{required}
+				{disabled}
+				{onkeydown}
+				onchange={handleChange}
+			/>
+			{#if rightIcon}
+				<Icon
+					name={rightIcon.name}
+					size={rightIcon.size ?? Size.Medium}
+					float
+					right={cssLength('0.5rem')}
+					top={cssLength('50%')}
+					anchorX={cssLength('0')}
+					anchorY={cssLength('-50%')}
+				/>
+			{/if}
+		</div>
+	</label>
+</div>
+
 <style>input {
   box-sizing: border-box;
   height: 100%;
@@ -335,4 +370,4 @@ label.for-table {
 }
 label.for-table input {
   height: unset;
-}</style>
+}</style>

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>;
 }