@lavalogic/scoria 0.35.0 → 0.37.0

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

@@ -0,0 +1,4 @@
+import type { AppointmentCalendarProps } from './AppointmentCalendarProps.js';
+declare const AppointmentCalendar: import("svelte").Component<AppointmentCalendarProps, {}, "">;
+type AppointmentCalendar = ReturnType<typeof AppointmentCalendar>;
+export default AppointmentCalendar;

package/dist/Components/AppointmentCalendar/AppointmentCalendarProps.d.ts

@@ -0,0 +1,92 @@
+import type { InputDateWithTime } from '../../Types/Internal/Misc.js';
+import type { SvelteDate } from 'svelte/reactivity';
+import type { Snippet } from 'svelte';
+/**
+ * Available calendar view modes.
+ *
+ * Frozen const + derived type, following the scoria
+ * enum-as-const convention.
+ */
+export declare const CalendarViewMode: {
+    readonly Day: "day";
+    readonly Week: "week";
+    readonly Month: "month";
+};
+export type CalendarViewMode = (typeof CalendarViewMode)[keyof typeof CalendarViewMode];
+/**
+ * A single appointment on the calendar.
+ *
+ * `dateFrom` and `dateTo` are branded with {@link InputDateWithTime} so
+ * callers cannot accidentally pass a raw `string` that does not parse
+ * as an ISO date-time. The branded values remain plain strings at
+ * runtime; the component parses them into `Date` internally.
+ */
+export interface CalendarAppointment {
+    readonly id: number;
+    readonly segmentId: number;
+    readonly dateFrom: InputDateWithTime;
+    readonly dateTo: InputDateWithTime;
+    readonly typeCode: string;
+    readonly label: string;
+    readonly sublabel?: string;
+}
+export interface CalendarDoor {
+    readonly id: number;
+    readonly name: string;
+}
+export interface DragSelection {
+    readonly doorId: number;
+    readonly doorName: string;
+    readonly dateFrom: Date;
+    readonly dateTo: Date;
+}
+/**
+ * Arguments passed to {@link AppointmentCalendarProps.onappointmentmove}.
+ *
+ * The previous five-positional-argument signature was easy to mix up
+ * at the call site; this object form makes each field self-describing.
+ */
+export interface AppointmentMoveArgs {
+    readonly appointment: CalendarAppointment;
+    readonly newDoorId: number;
+    readonly newDoorName: string;
+    readonly newDateFrom: Date;
+    readonly newDateTo: Date;
+}
+export interface AppointmentCalendarProps {
+    /** The doors (segments) to display as columns. */
+    doors: ReadonlyArray<CalendarDoor>;
+    /** The appointments to render on the calendar. */
+    appointments: ReadonlyArray<CalendarAppointment>;
+    /**
+     * The currently selected date.
+     *
+     * Accepts either a `Date` (which the component reads but does not
+     * mutate) or a `SvelteDate` for callers that want reactive
+     * day-rollover semantics. The component never writes to the value;
+     * use `ondatechange` to update it.
+     */
+    selectedDate: Date | SvelteDate;
+    /** The current view mode. */
+    viewMode: CalendarViewMode;
+    /** Called when the user changes the selected date. */
+    ondatechange: (date: Date) => void;
+    /** Called when the user changes the view mode. */
+    onviewmodechange: (mode: CalendarViewMode) => void;
+    /** Called when the user clicks and drags to create a new appointment. */
+    ondragcreate?: (selection: DragSelection) => void;
+    /** Called when the user clicks on an existing appointment. */
+    onappointmentclick?: (appointment: CalendarAppointment) => void;
+    /** Called when the user drags an existing appointment to a new door or time slot. */
+    onappointmentmove?: (args: AppointmentMoveArgs) => void;
+    /** The start hour for the day view grid (default: 0). */
+    startHour?: number;
+    /** The end hour for the day view grid (default: 24). */
+    endHour?: number;
+    /** The slot interval in minutes (default: 15). */
+    slotIntervalMinutes?: number;
+    /** Whether the calendar is loading data. */
+    isLoading?: boolean;
+    /** Optional snippet for extra header content (e.g. buttons). */
+    headerExtra?: Snippet;
+}

package/dist/Components/AppointmentCalendar/AppointmentCalendarProps.js

@@ -0,0 +1,12 @@
+/**
+ * Available calendar view modes.
+ *
+ * Frozen const + derived type, following the scoria
+ * enum-as-const convention.
+ */
+export const CalendarViewMode = {
+    Day: 'day',
+    Week: 'week',
+    Month: 'month',
+};
+Object.freeze(CalendarViewMode);

package/dist/Components/Base/BaseModal.svelte

@@ -0,0 +1,172 @@
+<svelte:options runes />
+
+<!--
+	BaseModal.svelte - internal primitive that owns the `<dialog>`
+	open/close + Escape/backdrop dismissal + autofocus plumbing
+	shared between `Modal`, `DesktopModal`, and `TouchModal`. See
+	`BaseModalProps.ts` for the contract.
+
+	Cosmetic-free for inner content by design: each consumer renders
+	its own header / main / footer / button-row markup as
+	`{@render children()}`. The consumer also keeps its own
+	footer-text rules, scanner shortcut wiring, colourSet button
+	styling, etc. - those concerns intentionally do not live in
+	BaseModal.
+
+	The shared dialog SHELL styling (border, backdrop, zoom-in
+	animation, the `--dialog-*` size variables and the static-height
+	/ static-width / noscroll modifier classes) is included here via
+	the `@mixin dialog` SCSS so it is shared across all three
+	consumer modals.
+-->
+
+<script lang="ts">
+	import { devCatch } from '../../Helpers/Helpers.svelte.js';
+	import { onMount, tick } from 'svelte';
+	import type { BaseModalProps } from './BaseModalProps.js';
+
+	let {
+		value = $bindable(true),
+		children,
+		onclose,
+		mandatory = false,
+		autofocusSelector,
+		ariaLabelledby,
+		ariaDescribedby,
+		closeOnEscape = true,
+		closeOnBackdropClick = true,
+		dialogClass,
+		dialogStyle,
+	}: BaseModalProps = $props();
+
+	let dialog: HTMLDialogElement | undefined = $state();
+
+	function tryFocusSelector() {
+		if (dialog && autofocusSelector != null && autofocusSelector.length > 0) {
+			const target = dialog.querySelector<HTMLElement>(autofocusSelector);
+			target?.focus();
+		}
+	}
+
+	onMount(() => {
+		// HACK tick() helps with Portal shenanigans. Matches the legacy
+		// Modal.svelte open-on-mount sequence.
+		tick()
+			.then(() => {
+				if (dialog && value && !dialog.open) {
+					dialog.showModal();
+					tryFocusSelector();
+				}
+			})
+			.catch(devCatch);
+	});
+
+	// React to parent flipping `value` after mount. We do not call
+	// showModal/close from inside a $derived because both have
+	// side-effects on the DOM; an $effect is the documented home
+	// for such bridges.
+	$effect(() => {
+		if (!dialog) {
+			return;
+		}
+		if (value && !dialog.open) {
+			dialog.showModal();
+			tryFocusSelector();
+		} else if (!value && dialog.open) {
+			dialog.close();
+		}
+	});
+
+	function handleNativeClose() {
+		// The dialog closed (native dismiss, our own close(), or Escape).
+		// Sync `value` back to false and fire the consumer callback.
+		if (value) {
+			value = false;
+		}
+		onclose?.();
+	}
+
+	function handleKeydown(e: KeyboardEvent) {
+		if (e.key === 'Escape') {
+			// stopPropagation matches the legacy Modal.svelte behaviour
+			// (prevents Escape bubbling out of a nested modal stack).
+			e.stopPropagation();
+			if (mandatory || !closeOnEscape) {
+				e.preventDefault();
+			}
+			// otherwise let the browser-native Escape close the dialog,
+			// which fires the `close` event and `handleNativeClose`.
+		}
+	}
+
+	function handleBackdropClick(e: MouseEvent) {
+		if (e.target === dialog) {
+			if (!mandatory && closeOnBackdropClick) {
+				dialog.close();
+			}
+		}
+	}
+</script>
+
+<dialog
+	bind:this={dialog}
+	class={dialogClass}
+	style={dialogStyle}
+	aria-modal="true"
+	aria-labelledby={ariaLabelledby}
+	aria-describedby={ariaDescribedby}
+	onclose={handleNativeClose}
+	onkeydown={handleKeydown}
+	onclick={handleBackdropClick}
+>
+	{@render children()}
+</dialog>
+
+<style>dialog {
+  overflow: clip;
+  background-color: #e9ecf1;
+  max-height: 95%;
+  min-height: var(--dialog-min-height);
+  min-width: var(--dialog-min-width);
+  width: var(--dialog-width, max-content);
+  height: var(--dialog-height, max-content);
+  border-radius: 0.1875rem;
+  border: none;
+  padding: 0;
+}
+dialog::backdrop {
+  background: rgba(0, 0, 0, 0.3);
+  backdrop-filter: blur(1px);
+}
+dialog.static-height {
+  height: 95%;
+}
+dialog.static-width {
+  width: min(95%, 1728px);
+}
+dialog[open] {
+  animation: zoom 0.2s cubic-bezier(0.34, 1.56, 0.64, 1);
+  display: flex;
+}
+@keyframes zoom {
+  from {
+    transform: scale(0.98);
+  }
+  to {
+    transform: scale(1);
+  }
+}
+dialog .modal-header {
+  flex-shrink: 0;
+}
+dialog .modal-main {
+  align-content: center;
+  flex-shrink: 1;
+  overflow: auto;
+}
+dialog .modal-main.noscroll {
+  overflow: visible;
+}
+dialog .footer {
+  flex-shrink: 0;
+}</style>

package/dist/Components/Base/BaseModal.svelte.d.ts

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

package/dist/Components/Base/BaseModalProps.d.ts

@@ -0,0 +1,73 @@
+import type { Snippet } from 'svelte';
+/**
+ * Props for the internal `BaseModal` primitive.
+ *
+ * `BaseModal` owns the `<dialog>` open/close lifecycle, Escape and
+ * backdrop-click dismissal (subject to {@link mandatory},
+ * {@link closeOnEscape}, {@link closeOnBackdropClick}), an optional
+ * autofocus selector, ARIA passthroughs, and the dialog shell
+ * styling (border, backdrop, zoom-in animation, size variables).
+ *
+ * BaseModal is deliberately cosmetic-free for the dialog's
+ * inner content: the {@link children} snippet is rendered directly
+ * inside the dialog, so each consumer owns its own wrapper markup
+ * (header / body / footer composition, button rows, barcode shortcut
+ * wiring, footer-text rules, focus-trap concerns beyond the native
+ * `showModal()` trap).
+ *
+ * The dialog opens via `dialog.showModal()` when {@link value} flips
+ * to `true`, and closes via `dialog.close()` when it flips to
+ * `false`. The flag defaults to `true` so the dialog opens
+ * immediately on mount, matching the legacy `Modal` / `TouchModal`
+ * behaviour.
+ *
+ * `BaseModal` is an internal primitive. Public consumers should use
+ * `Modal`, `DesktopModal`, or `TouchModal`.
+ */
+export interface BaseModalProps {
+    /**
+     * Bindable open flag. Defaults to `true`. When the parent flips
+     * this to `false`, BaseModal calls `dialog.close()`. When the
+     * dialog is dismissed natively (Escape / backdrop / its own
+     * `close()`), BaseModal flips this back to `false` and fires
+     * {@link onclose}.
+     */
+    value?: boolean;
+    /** Body content. Consumers render their own header / main / footer here. */
+    children: Snippet;
+    /** Fired after the native `<dialog>` element closes. */
+    onclose?: () => void;
+    /**
+     * When `true`, Escape and backdrop click do not dismiss the
+     * modal. Programmatic close (via `value = false`) is still
+     * allowed.
+     */
+    mandatory?: boolean;
+    /**
+     * Optional CSS selector identifying the element to focus when
+     * the modal opens. When omitted the browser focuses the first
+     * focusable element inside the dialog.
+     */
+    autofocusSelector?: string;
+    /** Pass-through `aria-labelledby` for the `<dialog>`. */
+    ariaLabelledby?: string;
+    /** Pass-through `aria-describedby` for the `<dialog>`. */
+    ariaDescribedby?: string;
+    /** Set to `false` to ignore Escape entirely (defaults to `true`). */
+    closeOnEscape?: boolean;
+    /** Set to `false` to ignore backdrop clicks entirely (defaults to `true`). */
+    closeOnBackdropClick?: boolean;
+    /**
+     * Extra class names appended to the `<dialog>` element. Consumers
+     * use this to add `static-height`, `static-width`, `noscroll`
+     * flags that the shared `@mixin dialog` already styles.
+     */
+    dialogClass?: string;
+    /**
+     * Inline `style` string applied to the `<dialog>` element.
+     * Consumers use this to set the `--dialog-min-width`,
+     * `--dialog-min-height`, `--dialog-width`, `--dialog-height`,
+     * and `--timer` CSS variables.
+     */
+    dialogStyle?: string;
+}

package/dist/Components/Base/BaseModalProps.js

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

package/dist/Components/Base/ContextWrapper.svelte

@@ -1,50 +1,72 @@
-<!-- 
-	@component
- 	Sets Contexts expected to exist for internal functionalities:
-	Context Menu, Tooltip, Toast, Untyped Input.
-
-	It is meant to be used in a +page.svelte or a +layout.svelte as early as required.
-
-	### Usage
-	```svelte
-	<ContextWrapper>
-		{@render children()}
-	</ChontextWrapper>
-	```
--->
-<script lang="ts">
-	import { AlertContext } from '../../Contexts/AlertContext.svelte.js';
-	import { ContextMenuContext } from '../../Contexts/ContextMenuContext.svelte.js';
-	import { ToastContext } from '../../Contexts/ToastContext.svelte.js';
-	import { TooltipContext } from '../../Contexts/TooltipContext.svelte.js';
-	import { UntypedInputContext } from '../../Contexts/UntypedInputContext.svelte.js';
-	import { setContext } from 'svelte';
-	import AlertModal from '../AlertModal.svelte';
-	import ContextMenu from '../Contexts/ContextMenu.svelte';
-	import ToastContainer from '../Contexts/ToastContainer.svelte';
-	import Tooltip from '../Contexts/Tooltip.svelte';
-	import type { ContextWrapperProps } from './ContextWrapperProps.js';
-
-	const { children, debug = false }: ContextWrapperProps = $props();
-
-	setContext(ContextMenuContext.identifier, new ContextMenuContext());
-	setContext(TooltipContext.identifier, new TooltipContext());
-	setContext(ToastContext.identifier, new ToastContext());
-	const alertContext = new AlertContext();
-	setContext(AlertContext.identifier, alertContext);
-
-	// NOTE known limitation. Not expected to mutate after instantiation
-	// svelte-ignore state_referenced_locally
-	const untypedListenerContext = new UntypedInputContext(debug);
-	setContext(UntypedInputContext.identifier, untypedListenerContext);
-</script>
-
-<ContextMenu />
-<Tooltip />
-<ToastContainer />
-{#if alertContext.showModal}
-	<AlertModal />
-{/if}
-<svelte:window onkeydown={untypedListenerContext.handleGlobalKeydown} />
-{@render children()}
-<!-- -->
+<svelte:options runes />
+
+<!--
+@component
+Application-level wrapper that mounts the global context hosts and
+instantiates the contexts they depend on. Mount it once near the root
+of a SvelteKit app, in `+layout.svelte` or `+page.svelte`, so that
+every descendant can read the contexts via `getContext`.
+
+### Hosts mounted
+
+| Host             | Driving context        | Notes                                              |
+| ---------------- | ---------------------- | -------------------------------------------------- |
+| `ContextMenu`    | `ContextMenuContext`   | Right-click / programmatic menus.                  |
+| `Tooltip`        | `TooltipContext`       | Hover tooltips driven by Button / Action.          |
+| `ToastContainer` | `ToastContext`         | Queue of toast notifications.                      |
+| `AlertModal`     | `AlertContext`         | Mounts only when `alertContext.showModal` is true. |
+
+`UntypedInputContext` is registered alongside the visual hosts. The
+wrapper installs a `svelte:window onkeydown` listener that forwards
+key events to `untypedListenerContext.handleGlobalKeydown` so barcode
+scanners and similar untyped input sources reach the context queue.
+
+### Usage
+
+```svelte
+<script lang="ts">
+	import { ContextWrapper } from '@lavalogic/scoria';
+</script>
+
+<ContextWrapper>
+	{@render children()}
+</ContextWrapper>
+```
+-->
+<script lang="ts">
+	import { AlertContext } from '../../Contexts/AlertContext.svelte.js';
+	import { ContextMenuContext } from '../../Contexts/ContextMenuContext.svelte.js';
+	import { ToastContext } from '../../Contexts/ToastContext.svelte.js';
+	import { TooltipContext } from '../../Contexts/TooltipContext.svelte.js';
+	import { UntypedInputContext } from '../../Contexts/UntypedInputContext.svelte.js';
+	import { setContext } from 'svelte';
+	import AlertModal from '../AlertModal.svelte';
+	import ContextMenu from '../Contexts/ContextMenu.svelte';
+	import ToastContainer from '../Contexts/ToastContainer.svelte';
+	import Tooltip from '../Contexts/Tooltip.svelte';
+	import type { ContextWrapperProps } from './ContextWrapperProps.js';
+
+	const { children, debug = false }: ContextWrapperProps = $props();
+
+	setContext(ContextMenuContext.identifier, new ContextMenuContext());
+	setContext(TooltipContext.identifier, new TooltipContext());
+	setContext(ToastContext.identifier, new ToastContext());
+	const alertContext = new AlertContext();
+	setContext(AlertContext.identifier, alertContext);
+
+	// NOTE known limitation. `debug` is captured at construction time;
+	// later prop changes are not propagated to the listener because the
+	// keydown handler closes over the constructed context instance.
+	// svelte-ignore state_referenced_locally
+	const untypedListenerContext = new UntypedInputContext(debug);
+	setContext(UntypedInputContext.identifier, untypedListenerContext);
+</script>
+
+<ContextMenu />
+<Tooltip />
+<ToastContainer />
+{#if alertContext.showModal}
+	<AlertModal />
+{/if}
+<svelte:window onkeydown={untypedListenerContext.handleGlobalKeydown} />
+{@render children()}

package/dist/Components/Base/ContextWrapper.svelte.d.ts

@@ -1,15 +1,34 @@
 import type { ContextWrapperProps } from './ContextWrapperProps.js';
 /**
- * Sets Contexts expected to exist for internal functionalities:
- * Context Menu, Tooltip, Toast, Untyped Input.
+ * Application-level wrapper that mounts the global context hosts and
+ * instantiates the contexts they depend on. Mount it once near the root
+ * of a SvelteKit app, in `+layout.svelte` or `+page.svelte`, so that
+ * every descendant can read the contexts via `getContext`.
  *
- * It is meant to be used in a +page.svelte or a +layout.svelte as early as required.
+ * ### Hosts mounted
+ *
+ * | Host             | Driving context        | Notes                                              |
+ * | ---------------- | ---------------------- | -------------------------------------------------- |
+ * | `ContextMenu`    | `ContextMenuContext`   | Right-click / programmatic menus.                  |
+ * | `Tooltip`        | `TooltipContext`       | Hover tooltips driven by Button / Action.          |
+ * | `ToastContainer` | `ToastContext`         | Queue of toast notifications.                      |
+ * | `AlertModal`     | `AlertContext`         | Mounts only when `alertContext.showModal` is true. |
+ *
+ * `UntypedInputContext` is registered alongside the visual hosts. The
+ * wrapper installs a `svelte:window onkeydown` listener that forwards
+ * key events to `untypedListenerContext.handleGlobalKeydown` so barcode
+ * scanners and similar untyped input sources reach the context queue.
  *
  * ### Usage
+ *
  * ```svelte
+ * <script lang="ts">
+ * import { ContextWrapper } from '@lavalogic/scoria';
+ * </script>
+ *
  * <ContextWrapper>
- * 	{@render children()}
- * </ChontextWrapper>
+ * {@render children()}
+ * </ContextWrapper>
  * ```
  */
 declare const ContextWrapper: import("svelte").Component<ContextWrapperProps, {}, "">;

package/dist/Components/Base/ContextWrapperProps.d.ts

@@ -1,5 +1,27 @@
 import type { Snippet } from 'svelte';
+/**
+ * Props for {@link ContextWrapper}.
+ *
+ * `ContextWrapper` mounts the global context hosts (`ContextMenu`,
+ * `Tooltip`, `ToastContainer`, `AlertModal`) and instantiates the
+ * application-level context classes (`ContextMenuContext`,
+ * `TooltipContext`, `ToastContext`, `AlertContext`, and
+ * `UntypedInputContext`).
+ */
 export interface ContextWrapperProps {
+    /**
+     * Application content. Rendered after all context hosts are
+     * mounted so descendants can `getContext(...)` the contexts and
+     * the hosts are guaranteed to be present.
+     */
     children: Snippet;
+    /**
+     * When `true` the constructed `UntypedInputContext` logs every
+     * captured key event to `console.debug`. Useful for verifying
+     * barcode scanner integrations during development; should be
+     * left `false` in production.
+     *
+     * @default false
+     */
     debug?: boolean;
 }