@marianmeres/stuic 3.167.0 → 3.169.0

package/dist/components/Input/_internal/FieldLikeChips.svelte

@@ -0,0 +1,286 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { ValidateOptions } from "../../../actions/validate.svelte.js";
+	import type { IntentColorKey } from "../../../utils/design-tokens.js";
+	import type { THC } from "../../Thc/Thc.svelte";
+	import type { InputWrapClassProps } from "../types.js";
+
+	type SnippetWithId = Snippet<[{ id: string }]>;
+
+	/** One rendered chip. `key` must be unique within the row. */
+	export interface FieldLikeChip {
+		key: string | number;
+		label: string;
+		/** Accessible name of the chip's remove (×) button, e.g. "Remove Foo" */
+		removeLabel: string;
+	}
+
+	/**
+	 * Internal: the `chips` trigger of `FieldOptions`. The FieldLikeButton counterpart for a
+	 * selection shown as inline, individually removable Pills — same InputWrap shell, same
+	 * hidden input + validate wiring, same imperative API.
+	 */
+	export interface Props extends InputWrapClassProps {
+		/** The hidden input carrying `value` + `name` (bindable) */
+		input?: HTMLInputElement;
+		value: string;
+		/** The chips to render (the parent derives them from `value`) */
+		chips: FieldLikeChip[];
+		label?: SnippetWithId | THC;
+		description?: SnippetWithId | THC;
+		class?: string;
+		id?: string;
+		tabindex?: number;
+		renderSize?: "sm" | "md" | "lg" | string;
+		name?: string;
+		required?: boolean;
+		disabled?: boolean;
+		validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+		labelAfter?: SnippetWithId | THC;
+		below?: SnippetWithId | THC;
+		labelLeft?: boolean;
+		labelLeftWidth?: "normal" | "wide";
+		labelLeftBreakpoint?: number;
+		style?: string;
+		/** Shown in the row while there are no chips */
+		placeholder?: string;
+		/** Accessible name (and tooltip) of the trailing "open" button */
+		openLabel: string;
+		/** Classes for each chip (Pill) */
+		classChip?: string;
+		/** Pill intent of the chips */
+		chipIntent?: IntentColorKey;
+		/** Open the picker (trailing button, or a click on the empty part of the row) */
+		onOpen: () => void;
+		/** A chip's × was pressed */
+		onRemove: (chip: FieldLikeChip, index: number) => void;
+	}
+</script>
+
+<script lang="ts">
+	import { tick } from "svelte";
+	import { iconSearch } from "../../../icons/index.js";
+	import {
+		validate as validateAction,
+		type ValidationResult,
+	} from "../../../actions/validate.svelte.js";
+	import { getId } from "../../../utils/get-id.js";
+	import Button from "../../Button/Button.svelte";
+	import Pill from "../../Pill/Pill.svelte";
+	import InputWrap from "./InputWrap.svelte";
+
+	let {
+		input = $bindable(),
+		value = $bindable(),
+		chips,
+		label = "",
+		id = getId(),
+		tabindex = 0,
+		description,
+		class: classProp,
+		renderSize = "md",
+		name,
+		//
+		required = false,
+		disabled = false,
+		//
+		// Renamed local binding to avoid collision with `export function validate()` below.
+		validate: validateProp,
+		//
+		labelAfter,
+		below,
+		//
+		labelLeft = false,
+		labelLeftWidth = "normal",
+		labelLeftBreakpoint = 480,
+		//
+		classLabel,
+		classLabelBox,
+		classInputBox,
+		classInputBoxWrap,
+		classInputBoxWrapInvalid,
+		classDescBox,
+		classDescBoxToggle,
+		classBelowBox,
+		classValidationBox,
+		style = "",
+		//
+		placeholder,
+		openLabel,
+		classChip,
+		chipIntent,
+		onOpen,
+		onRemove,
+	}: Props = $props();
+
+	// chips sit one step smaller than the field they live in
+	const PILL_SIZE: Record<string, string> = { sm: "sm", md: "sm", lg: "md" };
+	let pillSize = $derived(PILL_SIZE[renderSize] ?? "sm");
+
+	let validation: ValidationResult | undefined = $state();
+	const setValidationResult = (res: ValidationResult) => (validation = res);
+
+	let _doValidate: (() => void) | undefined = $state();
+	let rowEl: HTMLDivElement | undefined = $state();
+	let openBtnEl: HTMLElement | undefined = $state();
+
+	/** Trigger validation now. Renders the inline message if invalid. */
+	export function validate(): ValidationResult | undefined {
+		_doValidate?.();
+		return validation;
+	}
+
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		validation = undefined;
+		input?.setCustomValidity?.("");
+	}
+
+	/** Current validation state, or undefined if validator has never run. */
+	export function getValidation(): ValidationResult | undefined {
+		return validation;
+	}
+
+	/** Focus the trailing "open" button (the hidden input cannot be focused). */
+	export function focus(): void {
+		openBtnEl?.focus?.();
+	}
+
+	/** Scroll the field into view. Defaults to smooth + center. */
+	export function scrollIntoView(opts?: ScrollIntoViewOptions): void {
+		rowEl?.scrollIntoView?.({
+			behavior: "smooth",
+			block: "center",
+			...opts,
+		});
+	}
+
+	// the empty part of the row is a pointer convenience: chips own their own clicks and
+	// the trailing button is the keyboard-reachable opener
+	function onRowClick(e: MouseEvent) {
+		if (disabled) return;
+		if ((e.target as Element | null)?.closest?.(".stuic-pill")) return;
+		onOpen();
+	}
+
+	// keep keyboard focus inside the field after a removal: the × now sitting at the same
+	// index, else the trailing button
+	function remove(chip: FieldLikeChip, index: number) {
+		onRemove(chip, index);
+		tick().then(() => {
+			const btns =
+				rowEl?.querySelectorAll<HTMLButtonElement>(".stuic-pill-dismiss") ?? [];
+			const next = btns[Math.min(index, btns.length - 1)];
+			(next ?? openBtnEl)?.focus?.();
+		});
+	}
+</script>
+
+<InputWrap
+	{description}
+	class={classProp}
+	size={renderSize}
+	{id}
+	{label}
+	{labelAfter}
+	{below}
+	{required}
+	{disabled}
+	{labelLeft}
+	{labelLeftWidth}
+	{labelLeftBreakpoint}
+	{classLabel}
+	{classLabelBox}
+	{classInputBox}
+	{classInputBoxWrap}
+	{classInputBoxWrapInvalid}
+	{classDescBox}
+	{classDescBoxToggle}
+	{classBelowBox}
+	{classValidationBox}
+	{validation}
+	{style}
+>
+	<!-- svelte-ignore a11y_no_static_element_interactions -->
+	<!-- svelte-ignore a11y_click_events_have_key_events -->
+	<div
+		bind:this={rowEl}
+		class="stuic-field-options-chips"
+		data-size={renderSize}
+		data-empty={chips.length ? undefined : "true"}
+		onclick={onRowClick}
+	>
+		{#each chips as chip, i (chip.key)}
+			<Pill
+				dismissible
+				size={pillSize}
+				intent={chipIntent}
+				class={classChip}
+				dismissLabel={chip.removeLabel}
+				ondismiss={() => remove(chip, i)}
+				{disabled}
+				title={chip.label}
+			>
+				<!-- own span so an over-long label truncates (the Pill body is a flex row) -->
+				<span class="stuic-field-options-chip-label">{chip.label}</span>
+			</Pill>
+		{/each}
+		{#if !chips.length && placeholder}
+			<span class="stuic-field-options-chips-placeholder">{placeholder}</span>
+		{/if}
+	</div>
+
+	{#snippet inputAfter()}
+		<div class="flex items-center pr-1">
+			<Button
+				bind:el={openBtnEl}
+				iconButton
+				variant="ghost"
+				roundedFull
+				type="button"
+				size={renderSize === "lg" ? "md" : "sm"}
+				aria-label={openLabel}
+				tooltip={openLabel}
+				{disabled}
+				{tabindex}
+				onclick={() => onOpen()}
+			>
+				{@html iconSearch({ size: 18 })}
+			</Button>
+		</div>
+	{/snippet}
+
+	<input
+		bind:value
+		bind:this={input}
+		type="hidden"
+		{id}
+		{name}
+		use:validateAction={() => ({
+			enabled: validateProp !== false,
+			...(typeof validateProp === "boolean"
+				? {
+						// Return actual messages (not reason names) because hidden inputs
+						// don't support el.validationMessage - the validate action preserves
+						// our return value and uses it directly as the error message.
+						customValidator(val, ctx, el) {
+							if (required && !val)
+								return "This field requires attention. Please review and try again.";
+
+							// also, by default, JSON validation is built in
+							try {
+								JSON.parse(val as string);
+								return "";
+							} catch (e) {
+								return "This field is invalid. Please review and try again.";
+							}
+						},
+					}
+				: validateProp),
+			setValidationResult,
+			setDoValidate: (fn) => (_doValidate = fn),
+		})}
+		{required}
+		{disabled}
+	/>
+</InputWrap>

package/dist/components/Input/_internal/FieldLikeChips.svelte.d.ts

@@ -0,0 +1,65 @@
+import type { Snippet } from "svelte";
+import type { ValidateOptions } from "../../../actions/validate.svelte.js";
+import type { IntentColorKey } from "../../../utils/design-tokens.js";
+import type { THC } from "../../Thc/Thc.svelte";
+import type { InputWrapClassProps } from "../types.js";
+type SnippetWithId = Snippet<[{
+    id: string;
+}]>;
+/** One rendered chip. `key` must be unique within the row. */
+export interface FieldLikeChip {
+    key: string | number;
+    label: string;
+    /** Accessible name of the chip's remove (×) button, e.g. "Remove Foo" */
+    removeLabel: string;
+}
+/**
+ * Internal: the `chips` trigger of `FieldOptions`. The FieldLikeButton counterpart for a
+ * selection shown as inline, individually removable Pills — same InputWrap shell, same
+ * hidden input + validate wiring, same imperative API.
+ */
+export interface Props extends InputWrapClassProps {
+    /** The hidden input carrying `value` + `name` (bindable) */
+    input?: HTMLInputElement;
+    value: string;
+    /** The chips to render (the parent derives them from `value`) */
+    chips: FieldLikeChip[];
+    label?: SnippetWithId | THC;
+    description?: SnippetWithId | THC;
+    class?: string;
+    id?: string;
+    tabindex?: number;
+    renderSize?: "sm" | "md" | "lg" | string;
+    name?: string;
+    required?: boolean;
+    disabled?: boolean;
+    validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+    labelAfter?: SnippetWithId | THC;
+    below?: SnippetWithId | THC;
+    labelLeft?: boolean;
+    labelLeftWidth?: "normal" | "wide";
+    labelLeftBreakpoint?: number;
+    style?: string;
+    /** Shown in the row while there are no chips */
+    placeholder?: string;
+    /** Accessible name (and tooltip) of the trailing "open" button */
+    openLabel: string;
+    /** Classes for each chip (Pill) */
+    classChip?: string;
+    /** Pill intent of the chips */
+    chipIntent?: IntentColorKey;
+    /** Open the picker (trailing button, or a click on the empty part of the row) */
+    onOpen: () => void;
+    /** A chip's × was pressed */
+    onRemove: (chip: FieldLikeChip, index: number) => void;
+}
+import { type ValidationResult } from "../../../actions/validate.svelte.js";
+declare const FieldLikeChips: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+}, "value" | "input">;
+type FieldLikeChips = ReturnType<typeof FieldLikeChips>;
+export default FieldLikeChips;

package/dist/components/Input/index.css

@@ -81,6 +81,8 @@
 	--stuic-field-options-control-ring: var(--stuic-color-ring);
 	--stuic-field-options-muted-text: var(--stuic-color-muted-foreground);
 	--stuic-field-options-optgroup-text: var(--stuic-color-muted-foreground);
+	/* FieldOptions `chips` display mode */
+	--stuic-field-options-chips-gap: 0.25rem;
 }
 
 @layer components {
@@ -561,6 +563,62 @@
 		opacity: 1;
 	}
 
+	/* `chips` display mode: the selection as inline, removable Pills (FieldLikeChips) */
+	.stuic-field-options-chips {
+		display: flex;
+		flex: 1 1 0%;
+		min-width: 0;
+		flex-wrap: wrap;
+		align-items: center;
+		gap: var(--stuic-field-options-chips-gap);
+		cursor: pointer;
+	}
+
+	.stuic-input.disabled .stuic-field-options-chips {
+		cursor: not-allowed;
+	}
+
+	/* An over-long label must not push the chip out of the field: cap the chip at the row
+	   width and let the label span truncate (the × keeps its size) */
+	.stuic-field-options-chips .stuic-pill {
+		max-width: 100%;
+	}
+
+	.stuic-field-options-chip-label {
+		min-width: 0;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	/* Row metrics follow the input size tokens so the field lines up with its siblings */
+	.stuic-field-options-chips[data-size="sm"] {
+		padding: calc(var(--stuic-input-padding-y-sm) / 2) var(--stuic-input-padding-x-sm);
+		font-size: var(--stuic-input-font-size-sm);
+		min-height: var(--stuic-input-min-height-sm);
+	}
+
+	.stuic-field-options-chips[data-size="md"],
+	.stuic-field-options-chips:not([data-size]) {
+		padding: calc(var(--stuic-input-padding-y-md) / 2) var(--stuic-input-padding-x-md);
+		font-size: var(--stuic-input-font-size-md);
+		min-height: var(--stuic-input-min-height-md);
+	}
+
+	.stuic-field-options-chips[data-size="lg"] {
+		padding: calc(var(--stuic-input-padding-y-lg) / 2) var(--stuic-input-padding-x-lg);
+		font-size: var(--stuic-input-font-size-lg);
+		min-height: var(--stuic-input-min-height-lg);
+	}
+
+	.stuic-field-options-chips-placeholder {
+		color: var(
+			--stuic-field-options-chips-placeholder-text,
+			var(--stuic-input-placeholder)
+		);
+		user-select: none;
+	}
+
 	/* ============================================================================
 	   FIELD INPUT LOCALIZED
 	   ============================================================================ */

package/dist/components/Pagination/Pagination.svelte

@@ -0,0 +1,250 @@
+<script lang="ts" module>
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { Snippet } from "svelte";
+	import type { PagingCalcResult } from "@marianmeres/paging-store";
+	import type { TranslateFn } from "../../types.js";
+	import type { ButtonSize } from "../Button/Button.svelte";
+
+	export type PaginationVariant = "compact" | "numbers";
+
+	export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+		/**
+		 * Paging calculation result from `@marianmeres/paging-store` — the exact shape
+		 * `DataTable` consumes, so both can be fed from the same store or `calculatePaging`
+		 * call. Takes precedence over the `total`/`limit`/`offset` convenience props.
+		 */
+		paging?: PagingCalcResult;
+		/** Convenience alternative to `paging`: total number of items in the dataset. */
+		total?: number;
+		/** Convenience alternative to `paging`: items per page (default 10). */
+		limit?: number;
+		/** Convenience alternative to `paging`: current offset (default 0). */
+		offset?: number;
+		/**
+		 * Callback when the user navigates to a different page. First argument is the new
+		 * offset (`DataTable`'s `onPageChange` signature), second is the 1-based target page.
+		 */
+		onPageChange?: (offset: number, page: number) => void;
+		/**
+		 * `"compact"` (default): prev / "Page X of Y" / next — the `DataTable` pager.
+		 * `"numbers"`: windowed page-number buttons with ellipsis gaps.
+		 */
+		variant?: PaginationVariant;
+		/** Numbers variant: pages always shown around the current page (default 1). */
+		siblingCount?: number;
+		/** Numbers variant: pages always shown at the start and at the end (default 1). */
+		boundaryCount?: number;
+		/** Render first/last jump buttons (default false). */
+		showFirstLast?: boolean;
+		/**
+		 * Render the "Page X of Y" info. Defaults per variant: `true` for compact (between
+		 * prev/next), `false` for numbers (after the buttons when enabled).
+		 */
+		showInfo?: boolean;
+		/**
+		 * Render nothing when there is at most one page (default true — the `DataTable`
+		 * rule: one page of results needs no pager). Set `false` to keep it visible.
+		 */
+		hideSinglePage?: boolean;
+		/** Disable all controls (e.g. while a page of data is loading). */
+		disabled?: boolean;
+		/** Size preset passed to the inner Buttons (default "sm", as in `DataTable`). */
+		size?: ButtonSize;
+		/** i18n translate function (see `createPaginationT`). */
+		t?: TranslateFn;
+		/** Override the "Page X of Y" info content. */
+		renderInfo?: Snippet<[PagingCalcResult]>;
+		/** Skip all default styling (inner Buttons keep their own Button styling) */
+		unstyled?: boolean;
+		/** Additional CSS classes */
+		class?: string;
+		/** Class for every inner button */
+		classButton?: string;
+		/** Extra class for the current-page button (numbers variant) */
+		classButtonCurrent?: string;
+		/** Class for the "Page X of Y" info */
+		classInfo?: string;
+		/** Bindable element reference */
+		el?: HTMLElement;
+	}
+</script>
+
+<script lang="ts">
+	import { calculatePaging } from "@marianmeres/paging-store";
+	import { twMerge } from "../../utils/tw-merge.js";
+	import Button from "../Button/Button.svelte";
+	import { t_default } from "./i18n.js";
+	import { paginationRange } from "./pagination-range.js";
+
+	let {
+		paging,
+		total,
+		limit,
+		offset,
+		onPageChange,
+		variant = "compact",
+		siblingCount = 1,
+		boundaryCount = 1,
+		showFirstLast = false,
+		showInfo,
+		hideSinglePage = true,
+		disabled = false,
+		size = "sm",
+		t = t_default,
+		renderInfo,
+		unstyled = false,
+		class: classProp,
+		classButton: classButtonProp,
+		classButtonCurrent: classButtonCurrentProp,
+		classInfo: classInfoProp,
+		el = $bindable(),
+		...rest
+	}: Props = $props();
+
+	let _paging: PagingCalcResult | undefined = $derived(
+		paging ??
+			(total != null || limit != null || offset != null
+				? calculatePaging({ total, limit, offset })
+				: undefined)
+	);
+
+	let _render = $derived(!!_paging && (_paging.pageCount > 1 || !hideSinglePage));
+	let _showInfo = $derived(showInfo ?? variant === "compact");
+
+	let _pages = $derived(
+		variant === "numbers" && _paging
+			? paginationRange(_paging.currentPage, _paging.pageCount, {
+					siblingCount,
+					boundaryCount,
+				})
+			: []
+	);
+
+	let _class = $derived(unstyled ? classProp : twMerge("stuic-pagination", classProp));
+	let _classButton = $derived(
+		unstyled ? classButtonProp : twMerge("stuic-pagination-button", classButtonProp)
+	);
+	let _classInfo = $derived(
+		unstyled ? classInfoProp : twMerge("stuic-pagination-info", classInfoProp)
+	);
+
+	function goToPage(page: number) {
+		if (!_paging || disabled) return;
+		if (page < 1 || page > _paging.pageCount || page === _paging.currentPage) return;
+		onPageChange?.((page - 1) * _paging.limit, page);
+	}
+</script>
+
+{#if _paging && _render}
+	<nav
+		bind:this={el}
+		class={_class}
+		data-variant={!unstyled ? variant : undefined}
+		aria-label={t("pagination", null, "Pagination")}
+		{...rest}
+	>
+		{#if showFirstLast}
+			<Button
+				variant="ghost"
+				{size}
+				class={_classButton}
+				disabled={disabled || !_paging.hasPrevious}
+				onclick={() => goToPage(1)}
+				aria-label={t("first_page")}
+			>
+				&laquo;
+			</Button>
+		{/if}
+
+		<Button
+			variant="ghost"
+			{size}
+			class={_classButton}
+			disabled={disabled || !_paging.hasPrevious}
+			onclick={() => goToPage(_paging!.currentPage - 1)}
+			aria-label={t("previous_page")}
+		>
+			{#if variant === "compact"}
+				&lsaquo; {t("previous_page")}
+			{:else}
+				&lsaquo;
+			{/if}
+		</Button>
+
+		{#if variant === "numbers"}
+			{#each _pages as item, i (item === "ellipsis" ? `ellipsis-${i}` : item)}
+				{#if item === "ellipsis"}
+					<span
+						class={!unstyled ? "stuic-pagination-ellipsis" : undefined}
+						aria-hidden="true"
+					>
+						&hellip;
+					</span>
+				{:else}
+					{@const isCurrent = item === _paging.currentPage}
+					<Button
+						variant={isCurrent ? "solid" : "ghost"}
+						intent={isCurrent ? "primary" : undefined}
+						{size}
+						class={isCurrent
+							? twMerge(_classButton, classButtonCurrentProp)
+							: _classButton}
+						{disabled}
+						aria-label={t("go_to_page_x", { page: item })}
+						aria-current={isCurrent ? "page" : undefined}
+						data-current={isCurrent ? "true" : undefined}
+						onclick={() => goToPage(item)}
+					>
+						{item}
+					</Button>
+				{/if}
+			{/each}
+		{:else if _showInfo}
+			<span class={_classInfo}>
+				{#if renderInfo}
+					{@render renderInfo(_paging)}
+				{:else}
+					{t("page_x_of_y", { page: _paging.currentPage, pageCount: _paging.pageCount })}
+				{/if}
+			</span>
+		{/if}
+
+		<Button
+			variant="ghost"
+			{size}
+			class={_classButton}
+			disabled={disabled || !_paging.hasNext}
+			onclick={() => goToPage(_paging!.currentPage + 1)}
+			aria-label={t("next_page")}
+		>
+			{#if variant === "compact"}
+				{t("next_page")} &rsaquo;
+			{:else}
+				&rsaquo;
+			{/if}
+		</Button>
+
+		{#if showFirstLast}
+			<Button
+				variant="ghost"
+				{size}
+				class={_classButton}
+				disabled={disabled || !_paging.hasNext}
+				onclick={() => goToPage(_paging!.pageCount)}
+				aria-label={t("last_page")}
+			>
+				&raquo;
+			</Button>
+		{/if}
+
+		{#if variant === "numbers" && _showInfo}
+			<span class={_classInfo}>
+				{#if renderInfo}
+					{@render renderInfo(_paging)}
+				{:else}
+					{t("page_x_of_y", { page: _paging.currentPage, pageCount: _paging.pageCount })}
+				{/if}
+			</span>
+		{/if}
+	</nav>
+{/if}