@marianmeres/stuic 3.181.0 → 3.183.0

package/dist/components/Input/FieldTable.svelte.d.ts

@@ -0,0 +1,98 @@
+import type { Snippet } from "svelte";
+import type { ValidateOptions, ValidationResult } from "../../actions/validate.svelte.js";
+import type { TranslateFn } from "../../types.js";
+import type { MaybeLocalized } from "../../utils/tr.js";
+import type { THC } from "../Thc/Thc.svelte";
+import type { InputWrapClassProps } from "./types.js";
+type SnippetWithId = Snippet<[{
+    id: string;
+}]>;
+/** The cell types `FieldTable` renders itself. */
+export type FieldTableCellType = "text" | "number" | "select" | "checkbox" | "date" | "url";
+export interface FieldTableColumn {
+    /** The row-object key this cell reads and writes. */
+    key: string;
+    /** A built-in cell type, or anything else for the `cell` snippet. */
+    type: FieldTableCellType | (string & {});
+    label: MaybeLocalized;
+    /** `select` cells: the choices. */
+    options?: {
+        value: string;
+        label: MaybeLocalized;
+    }[];
+    /** `number` cells: a display unit — in the header ("Qty (pcs)") and after the input. */
+    unit?: string;
+    placeholder?: MaybeLocalized;
+    /** `text` / `url` cells: the input's `maxlength`, re-checked by validation. */
+    maxLength?: number;
+    /** Extra per-cell rule, run after the built-in one. Return a message to fail. */
+    validate?: (value: unknown, row: Record<string, unknown>) => string | undefined | void;
+}
+/** What the `cell` snippet receives for a column whose `type` is not built in. */
+export interface FieldTableCellContext {
+    column: FieldTableColumn;
+    row: Record<string, unknown>;
+    rowIndex: number;
+    value: unknown;
+    setValue: (next: unknown) => void;
+    /** The id the cell's `<label for>` points at. Put it on your control. */
+    id: string;
+    disabled: boolean;
+    invalid: boolean;
+    describedby: string | undefined;
+}
+export type FieldTableRow = Record<string, unknown>;
+export interface Props extends InputWrapClassProps, Record<string, any> {
+    /** Bindable. The rows — a live array, no string round trip. */
+    value: FieldTableRow[];
+    /** The hidden input carrying `JSON.stringify(value)`. */
+    name: string;
+    /** One entry per cell, in order. */
+    columns: FieldTableColumn[];
+    /** "Add row" is disabled at the cap; a seeded list above it is a validation error. */
+    maxRows?: number;
+    /** At least one row. */
+    required?: boolean;
+    /** The `tr()` fallback chain used to resolve column and option labels. */
+    displayLanguage?: string | string[];
+    /** Decimal separator of number cells (input and display). Default: the browser's. */
+    locale?: string;
+    /** `auto` switches on the component's OWN width (container query). */
+    layout?: "auto" | "table" | "stacked";
+    /** `sm` 32rem, `md` 40rem, `lg` 48rem, `xl` 56rem; ignored unless `layout="auto"`. */
+    tableFrom?: "sm" | "md" | "lg" | "xl";
+    /** Move up / move down buttons per row. Default `true`. */
+    reorderable?: boolean;
+    /** What "Add row" inserts. Default: one empty value per column. */
+    newRow?: () => FieldTableRow;
+    /** Renders any column whose `type` is not built in. */
+    cell?: Snippet<[FieldTableCellContext]>;
+    addLabel?: string;
+    emptyMessage?: string;
+    /** Fired after every change. */
+    onChange?: (value: FieldTableRow[]) => void;
+    label?: SnippetWithId | THC;
+    description?: SnippetWithId | THC;
+    class?: string;
+    id?: string;
+    tabindex?: number;
+    renderSize?: "sm" | "md" | "lg" | string;
+    disabled?: boolean;
+    validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+    labelAfter?: SnippetWithId | THC;
+    below?: SnippetWithId | THC;
+    labelLeft?: boolean;
+    labelLeftWidth?: "normal" | "wide";
+    labelLeftBreakpoint?: number;
+    style?: string;
+    t?: TranslateFn;
+}
+declare const FieldTable: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+}, "value">;
+type FieldTable = ReturnType<typeof FieldTable>;
+export default FieldTable;

package/dist/components/Input/README.md

@@ -4,24 +4,26 @@ A comprehensive form input system with multiple field components, validation sup
 
 ## Components
 
-| Component         | Description                                                    |
-| ----------------- | -------------------------------------------------------------- |
-| `FieldInput`      | Text, email, password, number, and other input types           |
-| `FieldMoney`      | Money amount stored as integer minor units (cents)             |
-| `FieldDate`       | Single calendar date — trigger + dialog, or embedded calendar  |
-| `FieldDateRange`  | Inclusive date range (`start` … `end`), same two presentations |
-| `FieldTextarea`   | Multi-line text input with auto-grow                           |
-| `FieldSelect`     | Dropdown select with option groups                             |
-| `FieldCheckbox`   | Single checkbox with label                                     |
-| `FieldRadios`     | Radio button group                                             |
-| `FieldSwitch`     | Toggle switch field                                            |
-| `FieldFile`       | File upload input                                              |
-| `FieldAssets`     | Asset/image upload with preview                                |
-| `FieldKeyValues`  | Key-value pairs editor with JSON serialization                 |
-| `FieldLikeButton` | Like/favorite toggle button                                    |
-| `Fieldset`        | Fieldset with legend                                           |
-| `Honeypot`        | Hidden anti-bot trap field (server-less)                       |
-| `TimeTrap`        | Anti-bot submit-timing primitive (server-less)                 |
+| Component          | Description                                                    |
+| ------------------ | -------------------------------------------------------------- |
+| `FieldInput`       | Text, email, password, number, and other input types           |
+| `FieldMoney`       | Money amount stored as integer minor units (cents)             |
+| `FieldDate`        | Single calendar date — trigger + dialog, or embedded calendar  |
+| `FieldDateRange`   | Inclusive date range (`start` … `end`), same two presentations |
+| `FieldTextarea`    | Multi-line text input with auto-grow                           |
+| `FieldSelect`      | Dropdown select with option groups                             |
+| `FieldCheckbox`    | Single checkbox with label                                     |
+| `FieldRadios`      | Radio button group                                             |
+| `FieldSwitch`      | Toggle switch field                                            |
+| `FieldFile`        | File upload input                                              |
+| `FieldAssets`      | Asset/image upload with preview                                |
+| `FieldSingleAsset` | One asset (avatar, logo, cover, one document) — see below      |
+| `FieldKeyValues`   | Key-value pairs editor with JSON serialization                 |
+| `FieldTable`       | Rows × typed columns editor (a list of records) — see below    |
+| `FieldLikeButton`  | Like/favorite toggle button                                    |
+| `Fieldset`         | Fieldset with legend                                           |
+| `Honeypot`         | Hidden anti-bot trap field (server-less)                       |
+| `TimeTrap`         | Anti-bot submit-timing primitive (server-less)                 |
 
 ## Common Props (FieldInput, FieldTextarea, FieldSelect)
 
@@ -676,8 +678,9 @@ all mounted pasteable fields):
   anywhere in the field focuses it, and a `:focus-within` ring on the input box signals the
   paste-ready state;
 - a paste with **no focus anywhere** (fresh page — focus parked on `<body>`) is routed to
-  the field as long as it is the _only_ pasteable (and visible) FieldAssets on the page, so
-  a bare Ctrl/Cmd-V works with no prior click;
+  the field as long as it is the _only_ pasteable (and visible) field on the page —
+  `FieldAssets` and `FieldSingleAsset` share one registry — so a bare Ctrl/Cmd-V works
+  with no prior click;
 - focus elsewhere is respected: pasting while a text input, textarea, select,
   contenteditable (even one nested _inside_ the field via the `label`/`description`/`below`
   snippets) or any other widget holds focus is never hijacked. With several pasteable fields
@@ -755,6 +758,200 @@ until it settles, and a rejection is caught so a failed download never breaks th
 
 ---
 
+## FieldSingleAsset
+
+One asset — a profile picture, a logo, a cover image, a single contract PDF. `FieldAssets`
+with `cardinality={1}` keeps the "many" interaction model (an add button that errors once
+the limit is hit, delete only inside the lightbox, a grid of small tiles). This field is
+built around a single tile instead:
+
+- **The tile is the picker and the drop target.** Click it, drop onto the field, or (opt-in)
+  paste — every source _replaces_ what is there. Two files at once are refused.
+- **Remove inline**, with an **Undo** offered for `undoTtl` ms (the asset is only unlinked
+  from `value`, never deleted anywhere, so undo is lossless). Focus returns to the tile.
+- **Shape / fit / size presets**: `shape="circle"` for avatars, `shape="wide"` (16:9) for
+  banners, `fit="contain"` for logos that must never be cropped; `size` is `sm` / `md` / `lg`
+  (5 / 8 / 12rem tall) or any CSS length.
+- **Optimistic preview + progress** — a spinner, or a ring driven by `onProgress` with
+  `withOnProgress`.
+- **Rollback on failure.** `value` is only rewritten when the upload _resolves_. A rejection
+  keeps the previous asset, shows the error on the tile with **Retry** (same file) and
+  **Discard**, and reports through `notifications`. X during an upload cancels it (a late
+  resolution is ignored).
+- **Client-side checks** before any bytes move: `accept` (also for drops and pastes),
+  `maxSize`, a custom async `validateFile`, and a `transformFile` seam for downscaling a
+  photo — or plugging in a cropper later.
+- **Preview** (the `AssetsPreview` lightbox: zoom, download, delete) as a secondary action.
+- `disabled` really disables (no drop, no paste, no remove — preview stays); without
+  `processAsset` the field is display-only; `isLoading` renders a skeleton in the tile's
+  shape.
+
+```svelte
+<script lang="ts">
+	import { FieldSingleAsset, type FieldAsset } from "@marianmeres/stuic";
+
+	let value = $state("");
+
+	async function processAsset(
+		asset: FieldAsset,
+		{ file, onProgress }: { file: File; onProgress: (p: number) => void }
+	): Promise<FieldAsset> {
+		const body = new FormData();
+		body.append("file", file);
+		const res = await fetch("/api/avatar", { method: "POST", body });
+		if (!res.ok) throw new Error(`Upload failed (${res.status})`);
+		const stored = await res.json();
+		return { id: stored.id, url: stored.url, name: file.name, type: file.type };
+	}
+</script>
+
+<FieldSingleAsset
+	bind:value
+	name="avatar"
+	label="Profile picture"
+	shape="circle"
+	accept="image/*"
+	capture="user"
+	maxSize={2 * 1024 * 1024}
+	{processAsset}
+	withOnProgress
+	pasteable
+	required
+/>
+```
+
+### Value
+
+`value` is the JSON of **one** `FieldAsset` object, or `""` when empty — not an array. It
+changes only when a user action settles: an upload that resolved, a remove, an undo. The
+form never sees a blob asset, and `onChange` fires exactly on those changes.
+
+For another shape — e.g. a backend that stores every relation as a list — pass
+`parseValue` / `serializeValue`:
+
+```svelte
+<FieldSingleAsset
+	bind:value
+	name="logo"
+	parseValue={(s) => JSON.parse(s || "[]")[0] ?? null}
+	serializeValue={(a) => JSON.stringify(a ? [a] : [])}
+/>
+```
+
+### Upload
+
+`processAsset(asset, { file, onProgress })` receives the optimistic asset (its `id` and
+every `url` are one blob URL of the file; `meta.size` is the byte size) plus the `file`
+itself — already run through `transformFile` — and `onProgress(0–100)`. Resolve with the
+stored asset: it becomes `value` as is (keep the blob URL as `url.thumb` if you like — it is
+revoked only when the field unmounts).
+
+Checks run in this order and the first failure stops with a message (via `notifications`,
+or `alert` without one):
+
+one file only → `accept` → `onBeforeReplace` → `transformFile` → `maxSize` → `validateFile`
+→ `processAsset`
+
+### Downscale or crop before upload (`transformFile`)
+
+```svelte
+<FieldSingleAsset ... transformFile={(file) => downscale(file, 512)} />
+```
+
+Return the file to upload, or `null` / `undefined` to cancel silently (the user closed your
+cropper). `maxSize` and `validateFile` see the transformed file, so a 12 MP phone photo
+downscaled on the client passes a 2 MB cap. A cropper is just a `transformFile` that opens
+a dialog and resolves with the cropped file.
+
+### Props
+
+| Prop                                                       | Type                                                   | Default            | Description                                                             |
+| ---------------------------------------------------------- | ------------------------------------------------------ | ------------------ | ----------------------------------------------------------------------- |
+| `value`                                                    | `string`                                               | required, bindable | JSON of one `FieldAsset`, or `""`                                       |
+| `name`                                                     | `string`                                               | required           | The hidden input's name                                                 |
+| `processAsset`                                             | `(asset, { file, onProgress }) => Promise<FieldAsset>` | -                  | The upload. Without it the field is display-only                        |
+| `withOnProgress`                                           | `boolean`                                              | `false`            | Progress ring instead of a spinner                                      |
+| `accept`                                                   | `string`                                               | -                  | HTML `accept` tokens (MIME, `image/*`, `.pdf`); applied to drops/pastes |
+| `capture`                                                  | `"user" \| "environment"`                              | -                  | Passed to the file input: phones open the camera directly               |
+| `maxSize`                                                  | `number`                                               | -                  | Max bytes, checked after `transformFile`                                |
+| `validateFile`                                             | `(file) => string \| void \| Promise<...>`             | -                  | Non-empty string rejects with that message                              |
+| `transformFile`                                            | `(file) => File \| null \| Promise<...>`               | -                  | Pre-upload hook; `null` cancels                                         |
+| `onBeforeRemove`                                           | `(asset) => boolean \| Promise<boolean>`               | -                  | `false` keeps the asset                                                 |
+| `onBeforeReplace`                                          | `(current, file) => boolean \| Promise<boolean>`       | -                  | `false` keeps the current asset                                         |
+| `undoTtl`                                                  | `number`                                               | `6000`             | ms the inline Undo stays after a remove; `0` disables                   |
+| `pasteable`                                                | `boolean`                                              | `false`            | Accept Ctrl/Cmd-V (same routing as `FieldAssets`)                       |
+| `shape`                                                    | `"square" \| "circle" \| "wide"`                       | `"square"`         | Tile shape                                                              |
+| `fit`                                                      | `"cover" \| "contain"`                                 | `"cover"`          | How an image fills the tile                                             |
+| `size`                                                     | `"sm" \| "md" \| "lg" \| string`                       | `"md"`             | Tile height: preset or CSS length                                       |
+| `placeholder`                                              | `THC`                                                  | -                  | Empty-tile content (e.g. an `Avatar` with initials)                     |
+| `noPreview`, `noDownload`                                  | `boolean`                                              | `false`            | Hide the Preview action / the lightbox's Download                       |
+| `onDownload`                                               | `(asset) => void \| Promise<void>`                     | -                  | Replaces the lightbox's default download (auth-gated bytes)             |
+| `onChange`                                                 | `(asset \| null) => void`                              | -                  | After every user-driven change of `value`                               |
+| `parseValue`, `serializeValue`                             | see Value                                              | JSON               | Custom `value` shape                                                    |
+| `isLoading`                                                | `boolean`                                              | `false`            | Skeleton while the initial value is fetched                             |
+| `notifications`                                            | `NotificationsStack`                                   | -                  | Where rejections and upload failures are reported (else `alert`)        |
+| `t`                                                        | `TranslateFn`                                          | English            | See i18n                                                                |
+| `classWrap`, `classPreview`, `classControls`, `classInput` | `string`                                               | -                  | Drop zone / tile / action buttons / hidden file input                   |
+
+Plus the usual field props: `label`, `description`, `labelAfter`, `below`, `id`, `tabindex`,
+`renderSize`, `required`, `disabled`, `validate`, `labelLeft*`, `style`, `class`, and the
+shared `InputWrapClassProps`. The imperative API is the standard one — `validate()`,
+`clearValidation()`, `getValidation()`, `focus()` (the tile), `scrollIntoView()` — plus
+`openFilePicker()`.
+
+### i18n
+
+All UI texts go through `t`. English is built in; Slovak ships bundled and opt-in:
+
+```svelte
+<script>
+	import {
+		FieldSingleAsset,
+		createFieldSingleAssetT,
+		FIELD_SINGLE_ASSET_MESSAGES_SK,
+	} from "@marianmeres/stuic";
+	const t = createFieldSingleAssetT(FIELD_SINGLE_ASSET_MESSAGES_SK);
+</script>
+
+<FieldSingleAsset bind:value name="avatar" {processAsset} {t} />
+```
+
+`createFieldSingleAssetT(messages, fallbackMessages?)` falls back to
+`FIELD_SINGLE_ASSET_MESSAGES_EN` for any key the catalog does not define. The catalog also
+carries the keys of the embedded `AssetsPreview`, so one `t` serves both.
+
+### Accessibility
+
+- The field's `<label>` targets the tile button; the tile's accessible description says what
+  pressing it does ("Choose a file" / "Replace x.jpg").
+- Remove / Preview / Retry / Discard are real named buttons, revealed on hover or focus,
+  always visible on touch, and on a failed upload.
+- Uploading, uploaded, failed, removed and restored are announced through a polite live
+  region; a remove or undo moves focus back to the tile.
+
+### CSS Variables
+
+| Variable                                              | Default                          | Description                                         |
+| ----------------------------------------------------- | -------------------------------- | --------------------------------------------------- |
+| `--stuic-field-single-asset-size-{sm,md,lg}`          | `5rem` / `8rem` / `12rem`        | Tile height per `size` preset                       |
+| `--stuic-field-single-asset-size`                     | (unset)                          | Explicit tile height, wins over the preset          |
+| `--stuic-field-single-asset-wide-ratio`               | `16 / 9`                         | Aspect ratio of `shape="wide"`                      |
+| `--stuic-field-single-asset-preview-bg`               | `--stuic-color-muted`            | Tile background (visible behind `fit="contain"`)    |
+| `--stuic-field-single-asset-preview-border`           | `--stuic-color-border`           | Tile border (dashed while empty)                    |
+| `--stuic-field-single-asset-preview-border-hover`     | `--stuic-color-ring`             | Tile border on hover                                |
+| `--stuic-field-single-asset-placeholder-text`         | `--stuic-color-muted-foreground` | Empty-tile icon color                               |
+| `--stuic-field-single-asset-meta-text`                | `--stuic-color-muted-foreground` | The meta line / hint / undo line                    |
+| `--stuic-field-single-asset-control-bg` / `-bg-hover` | `rgb(0 0 0 / 0.6)` / `0.8`       | Action buttons                                      |
+| `--stuic-field-single-asset-control-text`             | `#fff`                           | Action button icon color                            |
+| `--stuic-field-single-asset-overlay-bg`               | `rgb(0 0 0 / 0.4)`               | Progress overlay                                    |
+| `--stuic-field-single-asset-error-color`              | `--stuic-input-accent-error`     | Failed-upload border + overlay tint                 |
+| `--stuic-field-single-asset-radius`                   | `--stuic-radius`                 | Tile radius (usage-site fallback; `circle` ignores) |
+| `--stuic-field-single-asset-control-radius`           | `--stuic-radius-button`          | Action button radius (usage-site fallback)          |
+| `--stuic-field-single-asset-border-width`             | `--stuic-border-width`           | Tile border width (usage-site fallback)             |
+| `--stuic-field-single-asset-transition`               | `--stuic-transition`             | Hover / reveal transitions (usage-site fallback)    |
+
+---
+
 ## Date and date range fields
 
 `FieldDate` picks one calendar date, `FieldDateRange` an inclusive `start` … `end` pair.
@@ -886,6 +1083,256 @@ field shell adds:
 The trigger follows the `--stuic-input-*` size tokens (`renderSize`), the dialog card the
 `--stuic-modal-dialog-bg` / `-text` tokens.
 
+## FieldTable
+
+A form control whose value is **a list of records with a fixed, typed set of columns** —
+a bill of materials, a price list, opening hours, contacts. Each row is a line of typed
+inputs; the bound `value` is a live array of plain row objects, no string round trip:
+
+```ts
+[
+	{ part: "M6 bolt", qty: 12, material: "steel", rohs: true, since: "2026-01-15" },
+	{ part: "Washer", qty: 24, material: "brass", rohs: false, since: "" },
+];
+```
+
+It follows the hidden-input `Field*` contract (like `FieldKeyValues` and `FieldsBuilder`):
+one `<input type="hidden" name>` carries `JSON.stringify(value)`, every inner control is
+nameless, and `required` plus the per-cell rules are enforced by the component's own
+validator. Columns are declared by data:
+
+```svelte
+<script lang="ts">
+	import {
+		FieldTable,
+		type FieldTableColumn,
+		type FieldTableRow,
+	} from "@marianmeres/stuic";
+
+	const columns: FieldTableColumn[] = [
+		{ key: "part", type: "text", label: "Part", maxLength: 60 },
+		{ key: "qty", type: "number", label: "Qty", unit: "pcs" },
+		{
+			key: "material",
+			type: "select",
+			label: "Material",
+			options: [
+				{ value: "steel", label: "Steel" },
+				{ value: "brass", label: "Brass" },
+			],
+		},
+		{ key: "rohs", type: "checkbox", label: "RoHS" },
+		{ key: "since", type: "date", label: "Since" },
+		{ key: "sheet", type: "url", label: "Datasheet" },
+	];
+
+	let bom = $state<FieldTableRow[]>([]);
+</script>
+
+<FieldTable
+	bind:value={bom}
+	name="bom"
+	label="Bill of materials"
+	{columns}
+	maxRows={100}
+/>
+```
+
+### Column shape
+
+```ts
+type FieldTableCellType = "text" | "number" | "select" | "checkbox" | "date" | "url";
+
+interface FieldTableColumn {
+	key: string; // the row-object key this cell reads and writes
+	type: FieldTableCellType | (string & {}); // a built-in type, or anything for `cell`
+	label: MaybeLocalized; // resolved through `tr()` with `displayLanguage`
+	options?: { value: string; label: MaybeLocalized }[]; // `select`
+	unit?: string; // `number`: shown in the header ("Qty (pcs)") and after the input
+	placeholder?: MaybeLocalized;
+	maxLength?: number; // `text` / `url`: the input's maxlength, re-checked by validation
+	validate?: (value: unknown, row: Record<string, unknown>) => string | undefined | void;
+}
+```
+
+### The built-in cells
+
+| type       | Control                                          | Writes                                                 | Blank   | A stored value that does not fit                                              |
+| ---------- | ------------------------------------------------ | ------------------------------------------------------ | ------- | ----------------------------------------------------------------------------- |
+| `text`     | `<input type="text">` (+ `maxlength`)            | string; trimmed on commit (`change`), not while typing | `""`    | over `maxLength` → `err_maxlength`                                            |
+| `number`   | `<input type="text" inputmode="decimal">` + unit | `number`                                               | `null`  | unparseable text is **kept as typed** and flagged `err_number`                |
+| `select`   | `<select>` with a blank first entry              | the option value                                       | `""`    | shown as its own entry, round-trips, flagged `err_select_unknown`             |
+| `checkbox` | `<input type="checkbox">`                        | boolean                                                | `false` | checked iff `=== true`; rewritten only when toggled                           |
+| `date`     | `<input type="date">`                            | `YYYY-MM-DD`                                           | `""`    | input shows empty, value untouched until a date is picked, flagged `err_date` |
+| `url`      | `<input type="text" inputmode="url">`            | string; trimmed on commit                              | `""`    | not an absolute `http:` / `https:` URL → `err_url`                            |
+
+Why no `type="number"` / `type="url"`: a number input defaults to `step=1`, so a decimal
+fails **native** constraint validation and the browser refuses the whole form's submit —
+silently, when the bubble belongs to a control the user cannot see. A url input accepts
+`mailto:` while refusing a bare domain, which matches nobody's rule. Both stay text
+inputs (with the numeric / url keypad) and are validated by the component.
+
+**Number parsing is locale-aware and never guesses.** Whitespace (incl. NBSP) is
+stripped, so `1 000` gives `1000`; `.` is always the decimal separator; `,` is one only
+when `locale` uses it (`Intl.NumberFormat(locale)`), so `4,2` under `sk` is `4.2` and
+under `en` an error — never silently read as grouping. Display uses the locale's decimal
+separator without grouping, so a Slovak user sees `4,2`. While a cell is being typed in,
+the input shows exactly the typed text; blur re-formats it. The two helpers,
+`parseCellNumber(raw, locale)` and `formatCellNumber(n, locale)`, are exported.
+
+**Unknown types** render through the `cell` snippet, which receives
+`{ column, row, rowIndex, value, setValue, id, disabled, invalid, describedby }` — put
+`id` on your control so the row's `<label for>` reaches it. Without the snippet the cell
+shows the raw value read-only and round-trips it.
+
+```svelte
+{#snippet cell(ctx)}
+	{#if ctx.column.type === "color"}
+		<input
+			type="color"
+			id={ctx.id}
+			value={ctx.value}
+			oninput={(e) => ctx.setValue(e.currentTarget.value)}
+		/>
+	{/if}
+{/snippet}
+
+<FieldTable bind:value name="items" {columns} {cell} />
+```
+
+### Value semantics
+
+- **Row objects never gain a key the component invented.** Row identity lives in an
+  internal index-aligned list, so a backend with `additionalProperties: false` on the row
+  never sees a stray id.
+- **Keys not in `columns` are preserved, untouched and unrendered.** The library never
+  silently drops data; a consumer whose backend is closed prunes at its save boundary.
+- **"Add row"** inserts `newRow?.()`, or else one empty value per column (`""` / `null` /
+  `false` as in the table), and focuses the new row's first cell.
+- **A loaded row missing a cell** renders that control empty and writes nothing until the
+  cell is edited.
+- **Change → emit.** `value` is replaced by a JSON copy of the rows, then `onChange`
+  fires, then a bubbling `change` on the hidden input. **External reassignment** is
+  detected by a JSON comparison and rebuilds the rows.
+- **A non-array `value`** (`""`, `null`, `undefined`) renders as zero rows and is not
+  rewritten on mount — a mount never dirties the host form. The first edit emits an array.
+- **A non-object entry** renders as a degraded read-only row (`unknown_row_warning`). It
+  can be moved and removed, is never edited, and round-trips.
+- **Duplicate column keys**: the first occurrence wins, later ones are skipped with a
+  `console.warn`. **An empty column label** falls back to the key.
+
+### Layout
+
+One DOM for both modes — a real `<table>` — restyled by CSS. `layout="auto"` (default)
+switches on the **component's own width** through a container query, not the viewport's:
+a 480px table inside a side panel of a 1440px window stacks. `tableFrom` picks the
+threshold on a fixed scale (`sm` 32rem, `md` 40rem (default), `lg` 48rem, `xl` 56rem);
+`layout="table"` / `"stacked"` are static.
+
+- **table**: `<th scope="col">` headings (with the unit), one row per record, an actions
+  cell (move up / down, remove). Each cell type has a `min-width` token; the table
+  scrolls horizontally inside its own wrapper instead of squashing inputs.
+- **stacked**: each row is a card titled "Row N" with the actions on top, each cell a
+  label + control line.
+
+Every cell carries a real `<label for>` in both modes — "Qty (pcs), row 3" — visually
+hidden in table mode (the heading is visible there), visible and clickable in stacked
+mode. Crossing the breakpoint keeps focus and caret, because nothing remounts.
+
+### Validation and the host `validate()` rule
+
+The validator runs, in order: `required` with zero rows (`err_rows_required`), `maxRows`
+exceeded (`err_max_rows` — a seeded list above the cap is an error, never truncated),
+the first invalid cell in row-major order (`err_cell`: "Row 3, Qty: not a number" —
+built-in rule, then `column.maxLength`, then `column.validate`), then your
+`validate.customValidator`. Each invalid cell is `aria-invalid` with its message inline
+once `validate()` has run or once that cell was blurred; `validate()` scrolls to and
+focuses the first offender.
+
+No cell control carries `required`, `pattern`, `min` / `max` or a validating `type`, so
+a cell scrolled out of view can never make the browser refuse a submit without a
+message. The flip side — the rule for every hidden-input `Field*` — is that **a host that
+submits natively must call `validate()`** (or use `use:onSubmitValidityCheck`) before
+saving.
+
+### Props
+
+| Prop                       | Type                               | Default            | Description                                                       |
+| -------------------------- | ---------------------------------- | ------------------ | ----------------------------------------------------------------- |
+| `value`                    | `FieldTableRow[]`                  | required, bindable | The rows                                                          |
+| `name`                     | `string`                           | required           | The hidden input's name                                           |
+| `columns`                  | `FieldTableColumn[]`               | required           | One entry per cell, in order                                      |
+| `maxRows`                  | `number`                           | -                  | Cap; shows an `n / max` counter                                   |
+| `required`                 | `boolean`                          | `false`            | At least one row                                                  |
+| `displayLanguage`          | `string \| string[]`               | -                  | `tr()` fallback chain for column / option labels                  |
+| `locale`                   | `string`                           | browser            | Decimal separator of number cells                                 |
+| `layout`                   | `"auto" \| "table" \| "stacked"`   | `"auto"`           | See Layout                                                        |
+| `tableFrom`                | `"sm" \| "md" \| "lg" \| "xl"`     | `"md"`             | Container width at which `auto` renders the table                 |
+| `reorderable`              | `boolean`                          | `true`             | Move up / down buttons                                            |
+| `newRow`                   | `() => FieldTableRow`              | per-column empties | What "Add row" inserts                                            |
+| `cell`                     | `Snippet<[FieldTableCellContext]>` | -                  | Renders columns whose `type` is not built in                      |
+| `addLabel`, `emptyMessage` | `string`                           | `t(...)`           | Text overrides                                                    |
+| `onChange`                 | `(value: FieldTableRow[]) => void` | -                  | After every change                                                |
+| `t`                        | `TranslateFn`                      | English            | See i18n                                                          |
+| `renderSize`               | `"sm" \| "md" \| "lg"`             | `"sm"`             | Control size (the cells follow the `--stuic-input-*` size tokens) |
+
+Plus the usual field props: `label`, `description`, `labelAfter`, `below`, `id`,
+`tabindex`, `disabled`, `validate`, `labelLeft*`, `style`, `class`, and the shared
+`InputWrapClassProps`. The imperative API is the standard one: `validate()`,
+`clearValidation()`, `getValidation()`, `focus()` (first cell, or "Add row"),
+`scrollIntoView()`.
+
+### i18n
+
+All UI texts go through `t`. English is built in; Slovak ships bundled and opt-in
+(importing it is what pulls it into your bundle):
+
+```svelte
+<script>
+	import {
+		FieldTable,
+		createFieldTableT,
+		FIELD_TABLE_MESSAGES_SK,
+	} from "@marianmeres/stuic";
+	const t = createFieldTableT(FIELD_TABLE_MESSAGES_SK);
+</script>
+
+<FieldTable bind:value name="items" {columns} displayLanguage="sk" locale="sk" {t} />
+```
+
+`createFieldTableT(messages, fallbackMessages?)` falls back to `FIELD_TABLE_MESSAGES_EN`
+for any key the catalog does not define, so a partial catalog is fine and a raw key is
+never rendered. Column and option labels are consumer data: pass them as
+`{ en: "...", sk: "..." }` records and set `displayLanguage`.
+
+### Accessibility
+
+- Every cell has an accessible name of the form "Column, row N", in both layouts.
+- The actions are real buttons ("Move row 3 up", "Remove row 3"); a move keeps focus on
+  the moved row's button, a remove focuses the row now at that index (else the previous
+  one, else "Add row"); add, move and remove are announced through a polite live region.
+- "Enter" in a cell submits the host form, like any `FieldInput` in it — there is no
+  "Enter adds a row".
+
+### CSS Variables
+
+Cell controls reuse the `--stuic-input-*` colour and size tokens, so a themed `FieldInput`
+and a themed cell look alike. The table adds:
+
+| Variable                                                             | Default                          | Description                               |
+| -------------------------------------------------------------------- | -------------------------------- | ----------------------------------------- |
+| `--stuic-field-table-border-color`                                   | `--stuic-color-border`           | Stacked card border                       |
+| `--stuic-field-table-header-bg`                                      | `--stuic-color-muted`            | `<th>` background                         |
+| `--stuic-field-table-header-text`                                    | `--stuic-color-muted-foreground` | `<th>` and stacked cell-label color       |
+| `--stuic-field-table-row-divider-color`                              | `--stuic-color-border`           | Line between rows / under a card's title  |
+| `--stuic-field-table-cell-padding-x` / `-y`                          | `0.375rem` / `0.25rem`           | Cell padding in table mode                |
+| `--stuic-field-table-card-bg`                                        | `transparent`                    | Stacked card background                   |
+| `--stuic-field-table-card-gap`                                       | `0.5rem`                         | Gap between stacked cards                 |
+| `--stuic-field-table-card-radius`                                    | `--stuic-radius`                 | Stacked card radius (usage-site fallback) |
+| `--stuic-field-table-invalid-color`                                  | `--stuic-input-accent-error`     | Invalid cell border + inline message      |
+| `--stuic-field-table-unit-text`                                      | `--stuic-color-muted-foreground` | The unit suffix                           |
+| `--stuic-field-table-col-min-{text,number,select,checkbox,date,url}` | `10 / 6 / 8 / 3 / 9.5 / 12rem`   | Minimum cell width per type in table mode |
+
 ## Honeypot & TimeTrap (anti-bot primitives)
 
 Two small, **client-side, server-less** primitives for cheap spam mitigation. They produce **signals** — they do not block anything. Read the signal, then enforce on your server (the only place enforcement is trustworthy). Both are reusable on any form; [`ContactUsForm`](../ContactUsForm/README.md) composes them by default.

package/dist/components/Input/_internal/asset-helpers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Does a file pass an `accept` attribute value? Shared by `FieldAssets` and
+ * `FieldSingleAsset`.
+ *
+ * Tokens are the HTML `accept` ones, comma separated: a MIME type
+ * (`image/png`), a wildcard MIME (`image/*`, `*`), or an extension (`.pdf`).
+ * MIME tokens are matched as prefixes of the file's `type`; extension tokens
+ * are matched against the end of the file's `name` (the browser's own picker
+ * filters by the same rule, so a drop and a pick agree). An empty `accept`
+ * accepts everything; so does a file with an unknown (empty) `type` when the
+ * token is a MIME one — we cannot tell, and the picker would have let it
+ * through too.
+ */
+export declare function isAcceptedType(allowedAccept?: string, type?: string, name?: string): boolean;
+/** `1234567` -> `"1.2 MB"` (1024-based, at most one decimal below 10). */
+export declare function formatBytes(bytes: number): string;