@marianmeres/stuic 3.182.0 → 3.184.0

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

@@ -0,0 +1,152 @@
+import { type Snippet } from "svelte";
+import { type ValidateOptions, type ValidationResult } from "../../actions/validate.svelte.js";
+import type { TranslateFn } from "../../types.js";
+import { NotificationsStack } from "../Notifications/notifications-stack.svelte.js";
+import { type THC } from "../Thc/Thc.svelte";
+import type { FieldAsset } from "./FieldAssets.svelte";
+import type { InputWrapClassProps } from "./types.js";
+type SnippetWithId = Snippet<[{
+    id: string;
+}]>;
+/** What `processAsset` receives besides the optimistic (blob) asset. */
+export interface FieldSingleAssetUploadContext {
+    /** The file to upload — already run through `transformFile`, if any. */
+    file: File;
+    /** Report upload progress (0–100). Rendered when `withOnProgress` is set. */
+    onProgress: (progress: number) => void;
+}
+export type FieldSingleAssetShape = "square" | "circle" | "wide";
+export type FieldSingleAssetFit = "cover" | "contain";
+export type FieldSingleAssetSize = "sm" | "md" | "lg";
+/** `validateFile` verdict: a non-empty string rejects the file with that message. */
+export type FieldSingleAssetFileCheck = string | void | null | undefined | false;
+export interface Props extends InputWrapClassProps, Record<string, any> {
+    /**
+     * The serialized asset: by default the JSON of ONE `FieldAsset` object, or the
+     * empty string when the field is empty (see `parseValue` / `serializeValue`).
+     * Only ever rewritten when a user action SETTLES — an upload that resolves, a
+     * remove, an undo. An in-flight or failed upload never touches it.
+     */
+    value: string;
+    /** The hidden input's name (what the form submits). */
+    name: string;
+    label?: SnippetWithId | THC;
+    description?: SnippetWithId | THC;
+    labelAfter?: SnippetWithId | THC;
+    below?: SnippetWithId | THC;
+    class?: string;
+    id?: string;
+    tabindex?: number;
+    renderSize?: "sm" | "md" | "lg" | string;
+    required?: boolean;
+    disabled?: boolean;
+    validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+    labelLeft?: boolean;
+    labelLeftWidth?: "normal" | "wide";
+    labelLeftBreakpoint?: number;
+    /** Classes for the hidden `<input type="file">` */
+    classInput?: string;
+    /** Classes for the outermost wrapper (the drop zone) */
+    classWrap?: string;
+    /** Classes for the tile (the preview button) */
+    classPreview?: string;
+    /** Classes for the tile's action buttons (remove, preview, retry) */
+    classControls?: string;
+    style?: string;
+    t?: TranslateFn;
+    notifications?: NotificationsStack;
+    /** Initial-fetch state: renders a skeleton in the tile's shape; takes no input. */
+    isLoading?: boolean;
+    /** `value` -> asset. Default: `JSON.parse`, `null` for an empty/invalid string. */
+    parseValue?: (serialized: string) => FieldAsset | null;
+    /** asset -> `value`. Default: `JSON.stringify`, `""` for `null`. */
+    serializeValue?: (asset: FieldAsset | null) => string;
+    /**
+     * The upload. Receives the optimistic asset (its `id` and every `url` are one
+     * blob URL of the file) and the file itself; resolves with the stored asset,
+     * which becomes the new `value`. A rejection keeps the previous `value`, shows
+     * an error state on the tile with Retry / Discard, and reports `notifications`
+     * (see `onUploadError` to take over that report).
+     * Without it the field is display-only (no picker, no drop, no paste).
+     */
+    processAsset?: (asset: FieldAsset, ctx: FieldSingleAssetUploadContext) => Promise<FieldAsset>;
+    /** Render a progress ring driven by `ctx.onProgress` instead of a spinner. */
+    withOnProgress?: boolean;
+    /**
+     * Called when `processAsset` rejects (with the raw rejection, so a status code or
+     * a custom error class is still inspectable), after the tile has entered its
+     * error state and before the default `notifications.error(...)` toast. Return
+     * `false` to skip that toast — for a rejection the page already renders its own
+     * way (a quota / plan-limit panel). The tile keeps Retry / Discard regardless.
+     */
+    onUploadError?: (error: unknown, ctx: {
+        asset: FieldAsset;
+        file: File;
+    }) => void | boolean;
+    /** Same tokens as the HTML `accept` attribute; also applied to drops and pastes. */
+    accept?: string;
+    /** Passed to the file input: on phones opens the camera directly. */
+    capture?: "user" | "environment";
+    /** Reject files larger than this many bytes (checked after `transformFile`). */
+    maxSize?: number;
+    /**
+     * Custom check, run after `transformFile` and `maxSize`. Return a non-empty
+     * string to reject the file with that message (may be async — e.g. read image
+     * dimensions first).
+     */
+    validateFile?: (file: File) => FieldSingleAssetFileCheck | Promise<FieldSingleAssetFileCheck>;
+    /**
+     * Pre-upload hook, run after the `accept` check: downscale a photo, or open a
+     * cropper and resolve with the cropped file. Resolving with `null`/`undefined`
+     * cancels silently (the user closed the cropper).
+     */
+    transformFile?: (file: File) => File | null | undefined | Promise<File | null | undefined>;
+    /**
+     * Return `false` (may be async) to keep the asset. While a returned promise is
+     * pending the tile is busy: the Remove control shows a spinner, the tile and
+     * its controls are inert, and a second Remove is a no-op — so the hook may do
+     * the actual server-side delete and resolve with whether it succeeded.
+     */
+    onBeforeRemove?: (asset: FieldAsset) => boolean | Promise<boolean>;
+    /** Return `false` (may be async) to keep the current asset instead of uploading `file`. */
+    onBeforeReplace?: (current: FieldAsset, file: File) => boolean | Promise<boolean>;
+    /**
+     * After a remove, an inline "Undo" stays available this many ms (the removed
+     * asset is only unlinked from `value`, never deleted anywhere, so undo is
+     * lossless). `0` disables it. Default `6000`.
+     */
+    undoTtl?: number;
+    /**
+     * Opt-in: accept a clipboard paste (Ctrl/Cmd-V). Same routing as `FieldAssets`
+     * (one shared document listener: focused field wins; a bare paste with no focus
+     * goes to the only pasteable field on the page). A paste replaces. No-op without
+     * `processAsset`.
+     */
+    pasteable?: boolean;
+    /** Tile shape. `circle` for avatars, `wide` (16:9) for banners / logos. Default `square`. */
+    shape?: FieldSingleAssetShape;
+    /** `cover` crops to fill, `contain` letterboxes on a neutral background (logos). Default `cover`. */
+    fit?: FieldSingleAssetFit;
+    /** Tile height: a preset (`5rem` / `8rem` / `12rem`) or any CSS length. Default `md`. */
+    size?: FieldSingleAssetSize | string;
+    /** What the empty tile shows instead of the default icon (e.g. an `Avatar` with initials). */
+    placeholder?: THC;
+    /** Hide the "Preview" action (the `AssetsPreview` lightbox). */
+    noPreview?: boolean;
+    /** Hide the lightbox's Download button. */
+    noDownload?: boolean;
+    /** See `AssetsPreview.onDownload`: replaces the default download of `url.original`. */
+    onDownload?: (asset: FieldAsset) => void | Promise<void>;
+    /** After every user-driven change of `value` (upload settled, remove, undo). */
+    onChange?: (asset: FieldAsset | null) => void;
+}
+declare const FieldSingleAsset: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+    openFilePicker: () => void;
+}, "value">;
+type FieldSingleAsset = ReturnType<typeof FieldSingleAsset>;
+export default FieldSingleAsset;

package/dist/components/Input/README.md

@@ -4,25 +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                 |
-| `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)                 |
+| 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)
 
@@ -677,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
@@ -756,6 +758,252 @@ 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. An
+  async `onBeforeRemove` gets a busy state for its round trip (spinner on the Remove
+  control, tile inert, second click ignored) — so it may be the real server-side delete.
+- **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` — unless `onUploadError` returns `false`
+  because the page shows that failure its own way. 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`
+
+### When the failure is yours to show (`onUploadError`)
+
+Some rejections are not failures but product states — a 402 "plan limit reached" that the
+page already renders as an upgrade panel. Without a hook the field would stack its generic
+toast on top of that panel. `onUploadError(error, { asset, file })` gets the raw rejection
+first; return `false` to skip the toast. The tile still shows the error with Retry / Discard
+(the user may come back to it after upgrading), so the override is deliberately that narrow:
+
+```svelte
+<script lang="ts">
+	let gated = $state<string | null>(null);
+</script>
+
+{#if gated}
+	<UpgradeNotice message={gated} />
+{/if}
+
+<FieldSingleAsset
+	...
+	onUploadError={(e) => {
+		if ((e as any)?.status === 402) {
+			gated = (e as Error).message;
+			return false; // handled above — no toast
+		}
+	}}
+/>
+```
+
+### Removing the server copy too (`onBeforeRemove`)
+
+By default a remove only unlinks the asset from `value` (hence the lossless Undo). When the
+field owns a file that must go away on the server as well, do the `DELETE` inside
+`onBeforeRemove` and resolve with whether it succeeded — the field clears `value` only then.
+The round trip gets a busy state (spinner on the Remove control, `data-state="removing"`,
+tile and controls inert, a second Remove ignored). Pair it with `undoTtl={0}`: restoring the
+local value would lie about a file that is already gone.
+
+```svelte
+<FieldSingleAsset
+	...
+	undoTtl={0}
+	onBeforeRemove={async (asset) => {
+		const res = await fetch(`/api/logo/${asset.id}`, { method: "DELETE" });
+		return res.ok;
+	}}
+/>
+```
+
+### 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                                      |
+| `onUploadError`                                            | `(error, { asset, file }) => void \| boolean`          | -                  | On a rejected upload, before the toast; `false` skips the toast         |
+| `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; busy state while a promise settles             |
+| `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.

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;

package/dist/components/Input/_internal/asset-helpers.js

@@ -0,0 +1,46 @@
+/**
+ * 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 function isAcceptedType(allowedAccept, type, name) {
+    if (!allowedAccept)
+        return true;
+    const tokens = (allowedAccept ?? "")
+        .split(",")
+        .map((v) => `${v || ""}`.trim().toLowerCase())
+        .filter(Boolean);
+    if (!tokens.length)
+        return true;
+    const _type = `${type ?? ""}`.toLowerCase();
+    const _name = `${name ?? ""}`.toLowerCase();
+    return tokens.some((tok) => {
+        if (tok.startsWith("."))
+            return !!_name && _name.endsWith(tok);
+        // unknown type: cannot decide, let it through (legacy behavior)
+        if (!_type)
+            return true;
+        const prefix = tok.includes("*") ? tok.slice(0, tok.indexOf("*")) : tok;
+        return _type.startsWith(prefix);
+    });
+}
+/** `1234567` -> `"1.2 MB"` (1024-based, at most one decimal below 10). */
+export function formatBytes(bytes) {
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let v = Math.max(0, Number(bytes) || 0);
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    const rounded = i === 0 ? Math.round(v) : parseFloat(v.toFixed(v < 10 ? 1 : 0));
+    return `${rounded} ${units[i]}`;
+}

package/dist/components/Input/_internal/paste-target.d.ts

@@ -0,0 +1,15 @@
+export type PasteTarget = {
+    el: HTMLElement;
+    handle: (e: ClipboardEvent) => void;
+};
+/**
+ * Registers a pasteable field. Returns the unregister function. The document
+ * listener is installed with the first registration and removed with the last.
+ */
+export declare function registerPasteTarget(t: PasteTarget): () => void;
+/**
+ * The file entries of a paste. Prefers `items` (lets us keep only file-kind
+ * entries, e.g. a pasted screenshot); falls back to `.files` for browsers that
+ * only populate that. Empty for a plain-text paste.
+ */
+export declare function extractClipboardFiles(e: ClipboardEvent): File[];