@marianmeres/stuic 3.167.0 → 3.168.0

package/dist/components/Stepper/Stepper.svelte

@@ -0,0 +1,240 @@
+<script lang="ts" module>
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { Snippet } from "svelte";
+	import type { THC } from "../Thc/Thc.svelte";
+	import type { TranslateFn } from "../../types.js";
+
+	export type StepperOrientation = "horizontal" | "vertical";
+
+	export type StepperLabelPosition = "end" | "below";
+
+	export type StepperStepState = "completed" | "current" | "upcoming";
+
+	export type StepperClickable = "none" | "completed" | "all";
+
+	export interface StepperStep {
+		/** Step label */
+		label: THC;
+		/** Optional secondary line under the label */
+		description?: THC;
+		/**
+		 * Raw svg/html string rendered inside the indicator instead of the step number
+		 * (e.g. an `@marianmeres/icons-fns` render result). Completed/error markers
+		 * still take precedence.
+		 */
+		icon?: string;
+		/** Marks the step as failed — destructive coloring + "×" indicator */
+		error?: boolean;
+		/** Never clickable, regardless of the `clickable` policy */
+		disabled?: boolean;
+	}
+
+	export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+		/** The steps to render. Plain strings are shorthand for `{ label }`. */
+		steps: (StepperStep | string)[];
+		/**
+		 * Zero-based index of the current step (default 0) — aligns with
+		 * `@marianmeres/wizard`'s `step.index`. Steps before it render as completed,
+		 * steps after it as upcoming. Pass `steps.length` to mark every step
+		 * completed (wizard done). Out-of-range values are clamped.
+		 */
+		current?: number;
+		/**
+		 * Navigation callback. When provided (and `clickable` is not "none"), steps
+		 * render as buttons and eligible ones fire this on click. The current step
+		 * never fires.
+		 */
+		onSelect?: (index: number, step: StepperStep) => void;
+		/**
+		 * Which steps may be clicked when `onSelect` is present. `"completed"`
+		 * (default): only completed steps — the "go back and revisit" wizard rule.
+		 * `"all"`: any non-disabled step. `"none"`: display-only.
+		 */
+		clickable?: StepperClickable;
+		/** Layout direction (default "horizontal") */
+		orientation?: StepperOrientation;
+		/**
+		 * Horizontal orientation only: labels to the right of the indicator
+		 * (`"end"`, default) or centered below it (`"below"` — the classic
+		 * checkout header).
+		 */
+		labelPosition?: StepperLabelPosition;
+		/** Disable all interaction (e.g. while a step is submitting) */
+		disabled?: boolean;
+		/** i18n translate function (see `createStepperT`) */
+		t?: TranslateFn;
+		/** Override the indicator bubble content */
+		renderIndicator?: Snippet<
+			[{ index: number; step: StepperStep; state: StepperStepState }]
+		>;
+		/** Skip all default styling */
+		unstyled?: boolean;
+		/** Additional CSS classes */
+		class?: string;
+		/** Class for every step item (`li`) */
+		classStep?: string;
+		/** Class for the indicator bubble */
+		classIndicator?: string;
+		/** Class for the label */
+		classLabel?: string;
+		/** Class for the description */
+		classDescription?: string;
+		/** Class for the connector line between steps */
+		classConnector?: string;
+		/** Bindable element reference */
+		el?: HTMLElement;
+	}
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import Thc from "../Thc/Thc.svelte";
+	import { iconCheck, iconX } from "../../icons/index.js";
+	import { t_default } from "./i18n.js";
+
+	let {
+		steps,
+		current = 0,
+		onSelect,
+		clickable = "completed",
+		orientation = "horizontal",
+		labelPosition = "end",
+		disabled = false,
+		t = t_default,
+		renderIndicator,
+		unstyled = false,
+		class: classProp,
+		classStep: classStepProp,
+		classIndicator: classIndicatorProp,
+		classLabel: classLabelProp,
+		classDescription: classDescriptionProp,
+		classConnector: classConnectorProp,
+		el = $bindable(),
+		...rest
+	}: Props = $props();
+
+	let _steps: StepperStep[] = $derived(
+		steps.map((s) => (typeof s === "string" ? { label: s } : s))
+	);
+
+	// clamped to [0, steps.length] — the extra slot means "all completed"
+	let _current = $derived(Math.min(Math.max(0, Math.floor(current)), _steps.length));
+
+	let _interactive = $derived(!!onSelect && clickable !== "none");
+
+	let _class = $derived(unstyled ? classProp : twMerge("stuic-stepper", classProp));
+	let _classStep = $derived(
+		unstyled ? classStepProp : twMerge("stuic-stepper-item", classStepProp)
+	);
+	let _classIndicator = $derived(
+		unstyled ? classIndicatorProp : twMerge("stuic-stepper-indicator", classIndicatorProp)
+	);
+	let _classLabel = $derived(
+		unstyled ? classLabelProp : twMerge("stuic-stepper-label", classLabelProp)
+	);
+	let _classDescription = $derived(
+		unstyled
+			? classDescriptionProp
+			: twMerge("stuic-stepper-description", classDescriptionProp)
+	);
+	let _classConnector = $derived(
+		unstyled ? classConnectorProp : twMerge("stuic-stepper-connector", classConnectorProp)
+	);
+
+	function stateOf(i: number): StepperStepState {
+		if (i < _current) return "completed";
+		if (i === _current) return "current";
+		return "upcoming";
+	}
+
+	function isEligible(step: StepperStep, state: StepperStepState): boolean {
+		if (disabled || step.disabled || state === "current") return false;
+		return clickable === "all" || state === "completed";
+	}
+
+	function select(i: number) {
+		const step = _steps[i];
+		if (!_interactive || !isEligible(step, stateOf(i))) return;
+		onSelect?.(i, step);
+	}
+
+	// icon-only state info for screen readers ("Step 2 of 4, Completed")
+	function srText(i: number, step: StepperStep, state: StepperStepState): string {
+		const parts = [t("step_x_of_y", { step: i + 1, stepCount: _steps.length })];
+		if (step.error) parts.push(t("failed"));
+		else if (state === "completed") parts.push(t("completed"));
+		return parts.join(", ");
+	}
+</script>
+
+{#snippet stepInner(i: number, step: StepperStep, state: StepperStepState)}
+	<span class={_classIndicator} aria-hidden="true">
+		{#if renderIndicator}
+			{@render renderIndicator({ index: i, step, state })}
+		{:else if step.error}
+			{@html iconX()}
+		{:else if state === "completed"}
+			{@html iconCheck()}
+		{:else if step.icon}
+			{@html step.icon}
+		{:else}
+			{i + 1}
+		{/if}
+	</span>
+	<span class="sr-only">{srText(i, step, state)}</span>
+	<span class={unstyled ? undefined : "stuic-stepper-text"}>
+		<span class={_classLabel}><Thc thc={step.label} /></span>
+		{#if step.description}
+			<span class={_classDescription}><Thc thc={step.description} /></span>
+		{/if}
+	</span>
+{/snippet}
+
+{#if _steps.length}
+	<nav
+		bind:this={el}
+		class={_class}
+		data-orientation={!unstyled ? orientation : undefined}
+		data-label-position={!unstyled && orientation === "horizontal"
+			? labelPosition
+			: undefined}
+		data-disabled={!unstyled && disabled ? "" : undefined}
+		aria-label={t("stepper", null, "Progress")}
+		{...rest}
+	>
+		<ol class={unstyled ? undefined : "stuic-stepper-list"}>
+			{#each _steps as step, i (i)}
+				{@const state = stateOf(i)}
+				<li
+					class={_classStep}
+					data-state={!unstyled ? state : undefined}
+					data-error={!unstyled && step.error ? "" : undefined}
+					data-disabled={!unstyled && step.disabled ? "" : undefined}
+					aria-current={state === "current" ? "step" : undefined}
+				>
+					{#if _interactive}
+						<button
+							type="button"
+							class={unstyled ? undefined : "stuic-stepper-trigger"}
+							disabled={!isEligible(step, state)}
+							onclick={() => select(i)}
+						>
+							{@render stepInner(i, step, state)}
+						</button>
+					{:else}
+						<div class={unstyled ? undefined : "stuic-stepper-trigger"}>
+							{@render stepInner(i, step, state)}
+						</div>
+					{/if}
+					{#if i < _steps.length - 1}
+						<span
+							class={_classConnector}
+							data-state={!unstyled && state === "completed" ? "completed" : undefined}
+							aria-hidden="true"
+						></span>
+					{/if}
+				</li>
+			{/each}
+		</ol>
+	</nav>
+{/if}

package/dist/components/Stepper/Stepper.svelte.d.ts

@@ -0,0 +1,86 @@
+import type { HTMLAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+import type { THC } from "../Thc/Thc.svelte";
+import type { TranslateFn } from "../../types.js";
+export type StepperOrientation = "horizontal" | "vertical";
+export type StepperLabelPosition = "end" | "below";
+export type StepperStepState = "completed" | "current" | "upcoming";
+export type StepperClickable = "none" | "completed" | "all";
+export interface StepperStep {
+    /** Step label */
+    label: THC;
+    /** Optional secondary line under the label */
+    description?: THC;
+    /**
+     * Raw svg/html string rendered inside the indicator instead of the step number
+     * (e.g. an `@marianmeres/icons-fns` render result). Completed/error markers
+     * still take precedence.
+     */
+    icon?: string;
+    /** Marks the step as failed — destructive coloring + "×" indicator */
+    error?: boolean;
+    /** Never clickable, regardless of the `clickable` policy */
+    disabled?: boolean;
+}
+export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** The steps to render. Plain strings are shorthand for `{ label }`. */
+    steps: (StepperStep | string)[];
+    /**
+     * Zero-based index of the current step (default 0) — aligns with
+     * `@marianmeres/wizard`'s `step.index`. Steps before it render as completed,
+     * steps after it as upcoming. Pass `steps.length` to mark every step
+     * completed (wizard done). Out-of-range values are clamped.
+     */
+    current?: number;
+    /**
+     * Navigation callback. When provided (and `clickable` is not "none"), steps
+     * render as buttons and eligible ones fire this on click. The current step
+     * never fires.
+     */
+    onSelect?: (index: number, step: StepperStep) => void;
+    /**
+     * Which steps may be clicked when `onSelect` is present. `"completed"`
+     * (default): only completed steps — the "go back and revisit" wizard rule.
+     * `"all"`: any non-disabled step. `"none"`: display-only.
+     */
+    clickable?: StepperClickable;
+    /** Layout direction (default "horizontal") */
+    orientation?: StepperOrientation;
+    /**
+     * Horizontal orientation only: labels to the right of the indicator
+     * (`"end"`, default) or centered below it (`"below"` — the classic
+     * checkout header).
+     */
+    labelPosition?: StepperLabelPosition;
+    /** Disable all interaction (e.g. while a step is submitting) */
+    disabled?: boolean;
+    /** i18n translate function (see `createStepperT`) */
+    t?: TranslateFn;
+    /** Override the indicator bubble content */
+    renderIndicator?: Snippet<[
+        {
+            index: number;
+            step: StepperStep;
+            state: StepperStepState;
+        }
+    ]>;
+    /** Skip all default styling */
+    unstyled?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+    /** Class for every step item (`li`) */
+    classStep?: string;
+    /** Class for the indicator bubble */
+    classIndicator?: string;
+    /** Class for the label */
+    classLabel?: string;
+    /** Class for the description */
+    classDescription?: string;
+    /** Class for the connector line between steps */
+    classConnector?: string;
+    /** Bindable element reference */
+    el?: HTMLElement;
+}
+declare const Stepper: import("svelte").Component<Props, {}, "el">;
+type Stepper = ReturnType<typeof Stepper>;
+export default Stepper;

package/dist/components/Stepper/i18n-sk.d.ts

@@ -0,0 +1,17 @@
+import type { StepperMessages } from "./i18n.js";
+/**
+ * Slovak message catalog for `Stepper`. Opt-in — English stays the built-in default,
+ * and this module is only pulled into a bundle when it is actually imported (the
+ * component itself never references it).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Stepper, createStepperT, STEPPER_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createStepperT(STEPPER_MESSAGES_SK);
+ * </script>
+ *
+ * <Stepper {steps} {current} {t} />
+ * ```
+ */
+export declare const STEPPER_MESSAGES_SK: StepperMessages;

package/dist/components/Stepper/i18n-sk.js

@@ -0,0 +1,21 @@
+/**
+ * Slovak message catalog for `Stepper`. Opt-in — English stays the built-in default,
+ * and this module is only pulled into a bundle when it is actually imported (the
+ * component itself never references it).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Stepper, createStepperT, STEPPER_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createStepperT(STEPPER_MESSAGES_SK);
+ * </script>
+ *
+ * <Stepper {steps} {current} {t} />
+ * ```
+ */
+export const STEPPER_MESSAGES_SK = {
+    stepper: "Priebeh",
+    step_x_of_y: "Krok {step} z {stepCount}",
+    completed: "Dokončený",
+    failed: "Zlyhal",
+};

package/dist/components/Stepper/i18n.d.ts

@@ -0,0 +1,35 @@
+import type { TranslateFn } from "../../types.js";
+/**
+ * The built-in (English) message catalog of `Stepper`. Also the fallback of every
+ * other bundled locale, so a locale missing a key still renders text.
+ *
+ * Placeholders are single-brace (`{step}`, `{stepCount}`).
+ */
+export declare const STEPPER_MESSAGES_EN: {
+    stepper: string;
+    step_x_of_y: string;
+    completed: string;
+    failed: string;
+};
+/** Every message key `Stepper` may look up. */
+export type StepperMessageKey = keyof typeof STEPPER_MESSAGES_EN;
+/** A (possibly partial) catalog for one locale. */
+export type StepperMessages = Record<StepperMessageKey, string>;
+/**
+ * Builds the `t` prop of `Stepper` from a message catalog. Unknown or untranslated
+ * keys fall back to `fallbackMessages` (English by default), so a catalog may safely be
+ * partial and never renders a raw key.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Stepper, createStepperT, STEPPER_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createStepperT(STEPPER_MESSAGES_SK);
+ * </script>
+ *
+ * <Stepper {steps} {current} {t} />
+ * ```
+ */
+export declare function createStepperT(messages: Partial<StepperMessages> | Record<string, string>, fallbackMessages?: Partial<StepperMessages> | Record<string, string>): TranslateFn;
+/** The component's built-in English `t`. */
+export declare const t_default: TranslateFn;

package/dist/components/Stepper/i18n.js

@@ -0,0 +1,43 @@
+import { isPlainObject } from "../../utils/is-plain-object.js";
+import { replaceMap } from "../../utils/replace-map.js";
+/**
+ * The built-in (English) message catalog of `Stepper`. Also the fallback of every
+ * other bundled locale, so a locale missing a key still renders text.
+ *
+ * Placeholders are single-brace (`{step}`, `{stepCount}`).
+ */
+export const STEPPER_MESSAGES_EN = {
+    stepper: "Progress",
+    step_x_of_y: "Step {step} of {stepCount}",
+    completed: "Completed",
+    failed: "Failed",
+};
+/**
+ * Builds the `t` prop of `Stepper` from a message catalog. Unknown or untranslated
+ * keys fall back to `fallbackMessages` (English by default), so a catalog may safely be
+ * partial and never renders a raw key.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Stepper, createStepperT, STEPPER_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createStepperT(STEPPER_MESSAGES_SK);
+ * </script>
+ *
+ * <Stepper {steps} {current} {t} />
+ * ```
+ */
+export function createStepperT(messages, fallbackMessages = STEPPER_MESSAGES_EN) {
+    return (k, values = null, fallback = "") => {
+        const out = messages[k] ??
+            fallbackMessages[k] ??
+            (typeof fallback === "string" ? fallback : k);
+        return isPlainObject(values)
+            ? replaceMap(out, values, {
+                preSearchKeyTransform: (k) => `{${k}}`,
+            })
+            : out;
+    };
+}
+/** The component's built-in English `t`. */
+export const t_default = createStepperT(STEPPER_MESSAGES_EN);