@marianmeres/stuic 3.131.0 → 3.133.0

package/dist/components/CommentInput/README.md

@@ -0,0 +1,117 @@
+# CommentInput
+
+A GitHub-style comment box: a **raw markdown** `<textarea>` with **Write / Preview**
+tabs and a submit footer. It composes the same `InputWrap` scaffold as the
+`Field*` components, so its label / description / validation / sizing / `class*`
+props and look-and-feel match the rest of the form family.
+
+Unlike `MarkdownEditor` (a WYSIWYG Milkdown/CodeMirror surface), `CommentInput` keeps
+the lightweight "type raw markdown, flip to a rendered preview" model — ideal for
+comments, replies and short discussion input.
+
+```svelte
+<script>
+	import { CommentInput } from "@marianmeres/stuic";
+
+	let value = $state("");
+
+	async function post(text) {
+		await api.addComment(text); // your handler
+	}
+</script>
+
+<CommentInput
+	bind:value
+	label="Add a comment"
+	placeholder="Leave a comment…"
+	onSubmit={post}
+/>
+```
+
+## Preview rendering & dependencies
+
+The Preview tab renders markdown to **sanitized** HTML. The bundled default
+renderer uses `marked` + `dompurify`, declared as **optional peer dependencies**
+and lazy-loaded the first time a Preview is opened:
+
+```sh
+npm i marked dompurify
+```
+
+If you don't install them, install your own renderer via `renderMarkdown` instead
+(the bundled one is then never imported):
+
+```svelte
+<CommentInput bind:value renderMarkdown={(md) => mySanitizedHtml(md)} />
+```
+
+> Comment text is untrusted user content and `marked` emits embedded raw HTML
+> verbatim. If you pass your own `renderMarkdown`, **you** are responsible for
+> sanitizing its output.
+
+## Props
+
+| Prop                      | Type                                        | Default                  | Description                                                 |
+| ------------------------- | ------------------------------------------- | ------------------------ | ----------------------------------------------------------- |
+| `value`                   | `string` (bindable)                         | `""`                     | Comment text (raw markdown).                                |
+| `mode`                    | `"write" \| "preview"` (bindable)           | `"write"`                | Active tab.                                                 |
+| `input`                   | `HTMLTextAreaElement` (bindable)            | —                        | The underlying textarea element.                            |
+| `name`                    | `string`                                    | —                        | Textarea `name`, for native form submission.                |
+| `label`                   | `THC \| Snippet`                            | `""`                     | Field label (via InputWrap).                                |
+| `description`             | `THC \| Snippet`                            | —                        | Collapsible hint below the box.                             |
+| `placeholder`             | `string`                                    | —                        | Textarea placeholder.                                       |
+| `renderSize`              | `"sm" \| "md" \| "lg" \| string`            | `"md"`                   | Size variant.                                               |
+| `required`                | `boolean`                                   | `false`                  | Mark required + enforce on validation.                      |
+| `disabled`                | `boolean`                                   | `false`                  | Disable the whole box.                                      |
+| `validate`                | `boolean \| ValidateOptions`                | —                        | Enable validation (same contract as `FieldTextarea`).       |
+| `useTrim`                 | `boolean`                                   | `true`                   | Trim surrounding whitespace on blur.                        |
+| `useAutogrow`             | `boolean \| { enabled?, max? }`             | `true`                   | Grow the textarea with content (default max 250px).         |
+| `showTabs`                | `boolean`                                   | `true`                   | Show Write/Preview tabs. `false` → plain markdown textarea. |
+| `writeLabel`              | `string`                                    | `"Write"`                | Write tab label.                                            |
+| `previewLabel`            | `string`                                    | `"Preview"`              | Preview tab label.                                          |
+| `showMarkdownHint`        | `boolean`                                   | `true`                   | Show the subtle "Markdown supported" hint.                  |
+| `markdownHintLabel`       | `string`                                    | `"Markdown supported"`   | Hint text.                                                  |
+| `previewEmptyLabel`       | `string`                                    | `"Nothing to preview"`   | Shown in Preview when empty.                                |
+| `previewLoadingLabel`     | `string`                                    | `"Loading preview…"`     | Shown while the Preview renderer is loading.                |
+| `renderMarkdown`          | `(md: string) => string \| Promise<string>` | bundled marked+DOMPurify | Override the Preview renderer. Output is rendered as-is.    |
+| `onSubmit`                | `(value: string) => void \| Promise<void>`  | —                        | Submit handler. Async → spinner + disabled while pending.   |
+| `onCancel`                | `() => void`                                | —                        | Cancel handler.                                             |
+| `onChange`                | `(value: string) => void`                   | —                        | Fired on every edit.                                        |
+| `submitLabel`             | `string`                                    | `"Comment"`              | Submit button label.                                        |
+| `cancelLabel`             | `string`                                    | `"Cancel"`               | Cancel button label.                                        |
+| `showSubmit`              | `boolean`                                   | `!!onSubmit`             | Show the submit button.                                     |
+| `showCancel`              | `boolean`                                   | `!!onCancel`             | Show the cancel button.                                     |
+| `submitOnModEnter`        | `boolean`                                   | `true`                   | Submit on ⌘/Ctrl+Enter.                                     |
+| `clearOnSubmit`           | `boolean`                                   | `true`                   | Clear value after a successful submit.                      |
+| `submitDisabledWhenEmpty` | `boolean`                                   | `true`                   | Disable submit when empty/whitespace.                       |
+| `busy`                    | `boolean`                                   | `false`                  | External busy state (disables box + submit).                |
+| `avatar`                  | `THC \| Snippet`                            | —                        | Optional gutter to the left of the box.                     |
+| `footer`                  | `Snippet`                                   | —                        | Extra footer content, left of the buttons.                  |
+
+Plus the standard `InputWrap` layout props (`labelAfter`, `below`, `labelLeft`,
+`labelLeftWidth`, `labelLeftBreakpoint`) and `class*` props (`classInput`,
+`classBar`, `classPreview`, `classFooter`, and the shared `InputWrapClassProps`).
+
+## Imperative API
+
+Bind the component (`bind:this`) to call: `validate()`, `clearValidation()`,
+`getValidation()`, `focus()`, `scrollIntoView()`, `submit()`.
+
+## CSS variables
+
+All optional; each falls back to the shared `--stuic-input-*` token, then a global
+default.
+
+| Variable                              | Falls back to                  |
+| ------------------------------------- | ------------------------------ |
+| `--stuic-comment-input-radius`        | `--stuic-input-radius`         |
+| `--stuic-comment-input-border`        | `--stuic-input-border`         |
+| `--stuic-comment-input-border-focus`  | `--stuic-input-border-focus`   |
+| `--stuic-comment-input-bg`            | `--stuic-input-bg`             |
+| `--stuic-comment-input-padding-x`     | `--stuic-input-padding-x-*`    |
+| `--stuic-comment-input-padding-y`     | `--stuic-input-padding-y-*`    |
+| `--stuic-comment-input-font-size`     | `--stuic-input-font-size-*`    |
+| `--stuic-comment-input-min-height`    | `5rem` (`4rem` sm / `7rem` lg) |
+| `--stuic-comment-input-gap`           | `0.625rem`                     |
+| `--stuic-comment-input-tab-active-bg` | subtle overlay                 |
+| `--stuic-comment-input-code-bg`       | subtle overlay                 |

package/dist/components/CommentInput/_internal/render.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Default Preview renderer for {@link CommentInput}: turns a markdown string into
+ * **sanitized** HTML.
+ *
+ * `marked` and `dompurify` are declared as *optional* peer dependencies and are
+ * imported dynamically the first time a Preview tab is opened — consumers who
+ * never preview (or who pass their own `renderMarkdown`) don't pay for them, and
+ * a consumer who hasn't installed them gets a caught error (handled by the
+ * component) rather than a hard build failure. Mirrors the lazy-load convention
+ * used by `MarkdownEditor` for its Milkdown/CodeMirror backends.
+ *
+ * Sanitization is non-negotiable here: comment text is untrusted user content and
+ * `marked` emits raw HTML embedded in markdown verbatim (an XSS vector). Every
+ * code path that returns HTML runs it through DOMPurify first.
+ */
+/** A markdown-to-HTML renderer. Return value may be sync or async. */
+export type MarkdownRenderer = (markdown: string) => string | Promise<string>;
+/**
+ * Render markdown to sanitized HTML using the bundled (lazy) marked + DOMPurify
+ * pipeline. Throws if the optional peers aren't installed (the caller catches
+ * this and shows a fallback). SSR-safe: returns an empty string off the DOM,
+ * since DOMPurify needs a `window` to sanitize against.
+ */
+export declare function renderMarkdownSafe(markdown: string): Promise<string>;

package/dist/components/CommentInput/_internal/render.js

@@ -0,0 +1,47 @@
+/**
+ * Default Preview renderer for {@link CommentInput}: turns a markdown string into
+ * **sanitized** HTML.
+ *
+ * `marked` and `dompurify` are declared as *optional* peer dependencies and are
+ * imported dynamically the first time a Preview tab is opened — consumers who
+ * never preview (or who pass their own `renderMarkdown`) don't pay for them, and
+ * a consumer who hasn't installed them gets a caught error (handled by the
+ * component) rather than a hard build failure. Mirrors the lazy-load convention
+ * used by `MarkdownEditor` for its Milkdown/CodeMirror backends.
+ *
+ * Sanitization is non-negotiable here: comment text is untrusted user content and
+ * `marked` emits raw HTML embedded in markdown verbatim (an XSS vector). Every
+ * code path that returns HTML runs it through DOMPurify first.
+ */
+// Cache the resolved (marked + DOMPurify) pipeline so the dynamic imports and
+// DOMPurify instance creation happen at most once per page.
+let cached = null;
+async function load() {
+    if (cached)
+        return cached;
+    const [{ marked }, dompurify] = await Promise.all([
+        import("marked"),
+        import("dompurify"),
+    ]);
+    // DOMPurify's default export is the instance in a browser/DOM context.
+    const DOMPurify = dompurify.default ?? dompurify;
+    cached = async (markdown) => {
+        // GitHub-flavored markdown + soft line breaks → <br>, matching how comment
+        // boxes (incl. GitHub's) treat single newlines.
+        const html = await marked.parse(markdown ?? "", { gfm: true, breaks: true });
+        return DOMPurify.sanitize(html);
+    };
+    return cached;
+}
+/**
+ * Render markdown to sanitized HTML using the bundled (lazy) marked + DOMPurify
+ * pipeline. Throws if the optional peers aren't installed (the caller catches
+ * this and shows a fallback). SSR-safe: returns an empty string off the DOM,
+ * since DOMPurify needs a `window` to sanitize against.
+ */
+export async function renderMarkdownSafe(markdown) {
+    if (typeof window === "undefined")
+        return "";
+    const render = await load();
+    return render(markdown);
+}

package/dist/components/CommentInput/index.css

@@ -0,0 +1,310 @@
+/******************************************************************************
+  CommentInput
+
+  A GitHub-style comment box: a raw-markdown textarea with Write/Preview tabs and
+  a submit footer. Field chrome (label/description/validation/sizing) comes from
+  the shared InputWrap, so it matches the `Field*` family; everything specific to
+  the box lives here.
+
+  Tokens follow the library convention: a component token that falls back to the
+  shared `--stuic-input-*` token, then to a global default — so the box inherits
+  input theming for free but can be retargeted on its own.
+******************************************************************************/
+
+.stuic-comment-input {
+	--_radius: var(
+		--stuic-comment-input-radius,
+		var(--stuic-input-radius, var(--stuic-radius))
+	);
+	--_border-color: var(
+		--stuic-comment-input-border,
+		var(--stuic-input-border, currentColor)
+	);
+	--_bg: var(--stuic-comment-input-bg, var(--stuic-input-bg, transparent));
+	--_pad-x: var(
+		--stuic-comment-input-padding-x,
+		var(--stuic-input-padding-x-md, 0.75rem)
+	);
+	--_pad-y: var(--stuic-comment-input-padding-y, var(--stuic-input-padding-y-md, 0.5rem));
+	--_min-height: var(--stuic-comment-input-min-height, 5rem);
+	--_font-size: var(
+		--stuic-comment-input-font-size,
+		var(--stuic-input-font-size-md, 0.9375rem)
+	);
+
+	display: flex;
+	align-items: flex-start;
+	gap: var(--stuic-comment-input-gap, 0.625rem);
+	width: 100%;
+	min-width: 0;
+}
+
+.stuic-comment-input-avatar {
+	flex: 0 0 auto;
+	padding-top: 0.125rem;
+}
+
+/* The bordered card — focus ring lives here, not on the avatar row. */
+.stuic-comment-input-editor {
+	display: flex;
+	flex-direction: column;
+	flex: 1 1 auto;
+	min-width: 0;
+	max-width: 100%;
+	background: var(--_bg);
+	border: var(--stuic-border-width, 1px) solid var(--_border-color);
+	border-radius: var(--_radius);
+	color: var(--stuic-input-text, inherit);
+	overflow: hidden;
+	transition: border-color var(--stuic-transition, 150ms);
+}
+
+.stuic-comment-input-editor:focus-within {
+	border-color: var(
+		--stuic-comment-input-border-focus,
+		var(--stuic-input-border-focus, currentColor)
+	);
+}
+
+.stuic-comment-input.disabled {
+	opacity: 0.6;
+	pointer-events: none;
+}
+
+/* --- Tab bar -------------------------------------------------------------- */
+.stuic-comment-input-bar {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: 0.5rem;
+	padding: 0.25rem 0.375rem;
+	background: var(--stuic-comment-input-bar-bg, transparent);
+}
+
+.stuic-comment-input-tabs {
+	display: flex;
+	align-items: center;
+	gap: 0.125rem;
+}
+
+.stuic-comment-input-tabs button {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	height: 2rem;
+	padding: 0 0.625rem;
+	font-size: 0.8125rem;
+	line-height: 1;
+	color: inherit;
+	opacity: 0.7;
+	background: transparent;
+	border: none;
+	border-radius: var(--stuic-radius, 0.375rem);
+	transition:
+		background-color var(--stuic-transition, 150ms),
+		opacity var(--stuic-transition, 150ms);
+}
+
+.stuic-comment-input-tabs button:hover:not(:disabled) {
+	background: var(--stuic-comment-input-tab-hover-bg, rgb(0 0 0 / 0.06));
+}
+
+.stuic-comment-input-tabs button[data-active="true"] {
+	opacity: 1;
+	font-weight: 600;
+	background: var(--stuic-comment-input-tab-active-bg, rgb(0 0 0 / 0.06));
+}
+
+.stuic-comment-input-tabs button:disabled {
+	opacity: 0.4;
+}
+
+.stuic-comment-input-hint {
+	font-size: 0.75rem;
+	opacity: 0.5;
+	padding-right: 0.25rem;
+}
+
+:root.dark .stuic-comment-input-tabs button:hover:not(:disabled),
+:root.dark .stuic-comment-input-tabs button[data-active="true"] {
+	background: var(--stuic-comment-input-tab-active-bg, rgb(255 255 255 / 0.08));
+}
+
+@media (pointer: coarse) {
+	.stuic-comment-input-tabs button {
+		height: 2.5rem;
+	}
+}
+
+/* --- Surface (textarea + preview share the same box) ---------------------- */
+.stuic-comment-input-surface {
+	min-width: 0;
+}
+
+/* The inactive tab panel is removed via the `hidden` attribute; the explicit
+   rule guarantees it collapses regardless of any utility-layer display. The
+   write panel stays in the DOM while hidden so its textarea still submits and
+   validates. */
+.stuic-comment-input-panel[hidden] {
+	display: none;
+}
+
+.stuic-comment-input-textarea {
+	display: block;
+	width: 100%;
+	min-height: var(--_min-height);
+	max-width: 100%;
+	margin: 0;
+	padding: var(--_pad-y) var(--_pad-x);
+	font-size: var(--_font-size);
+	line-height: 1.6;
+	color: inherit;
+	background: transparent;
+	border: none;
+	outline: none;
+	box-shadow: none;
+	resize: none;
+}
+
+/* --- Preview -------------------------------------------------------------- */
+.stuic-comment-input-preview {
+	min-height: var(--_min-height);
+	padding: var(--_pad-y) var(--_pad-x);
+	font-size: var(--_font-size);
+	line-height: 1.6;
+	overflow-wrap: break-word;
+}
+
+.stuic-comment-input-preview-empty {
+	opacity: 0.5;
+	font-style: italic;
+}
+
+.stuic-comment-input-preview > * + * {
+	margin-top: 0.75em;
+}
+.stuic-comment-input-preview h1 {
+	font-size: 1.5em;
+	font-weight: 700;
+	line-height: 1.2;
+}
+.stuic-comment-input-preview h2 {
+	font-size: 1.3em;
+	font-weight: 700;
+	line-height: 1.25;
+}
+.stuic-comment-input-preview h3 {
+	font-size: 1.15em;
+	font-weight: 600;
+}
+.stuic-comment-input-preview ul,
+.stuic-comment-input-preview ol {
+	padding-left: 1.5em;
+}
+.stuic-comment-input-preview ul {
+	list-style: disc;
+}
+.stuic-comment-input-preview ol {
+	list-style: decimal;
+}
+.stuic-comment-input-preview a {
+	text-decoration: underline;
+}
+.stuic-comment-input-preview blockquote {
+	padding-left: 1em;
+	border-left: 3px solid var(--_border-color);
+	opacity: 0.85;
+}
+.stuic-comment-input-preview code {
+	font-family: var(
+		--stuic-comment-input-font-mono,
+		ui-monospace,
+		SFMono-Regular,
+		Menlo,
+		monospace
+	);
+	font-size: 0.9em;
+	padding: 0.1em 0.3em;
+	border-radius: 0.25rem;
+	background: var(--stuic-comment-input-code-bg, rgb(0 0 0 / 0.06));
+}
+.stuic-comment-input-preview pre {
+	font-family: var(
+		--stuic-comment-input-font-mono,
+		ui-monospace,
+		SFMono-Regular,
+		Menlo,
+		monospace
+	);
+	padding: 0.75em 1em;
+	border-radius: var(--stuic-radius, 0.375rem);
+	background: var(--stuic-comment-input-code-bg, rgb(0 0 0 / 0.06));
+	overflow-x: auto;
+}
+.stuic-comment-input-preview pre code {
+	padding: 0;
+	background: transparent;
+}
+.stuic-comment-input-preview hr {
+	border: none;
+	border-top: var(--stuic-border-width, 1px) solid var(--_border-color);
+}
+.stuic-comment-input-preview table {
+	border-collapse: collapse;
+}
+.stuic-comment-input-preview th,
+.stuic-comment-input-preview td {
+	border: var(--stuic-border-width, 1px) solid var(--_border-color);
+	padding: 0.25em 0.5em;
+}
+
+:root.dark .stuic-comment-input-preview code,
+:root.dark .stuic-comment-input-preview pre {
+	background: var(--stuic-comment-input-code-bg, rgb(255 255 255 / 0.08));
+}
+
+/* --- Footer (button row) -------------------------------------------------- */
+.stuic-comment-input-footer {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: 0.5rem;
+	padding: 0.5rem;
+}
+
+.stuic-comment-input-footer-start,
+.stuic-comment-input-footer-end {
+	display: flex;
+	align-items: center;
+	gap: 0.5rem;
+}
+
+.stuic-comment-input-footer-end {
+	margin-left: auto;
+}
+
+/* --- Size variants -------------------------------------------------------- */
+.stuic-comment-input[data-size="sm"] {
+	--_pad-x: var(--stuic-comment-input-padding-x, var(--stuic-input-padding-x-sm, 0.5rem));
+	--_pad-y: var(
+		--stuic-comment-input-padding-y,
+		var(--stuic-input-padding-y-sm, 0.375rem)
+	);
+	--_font-size: var(
+		--stuic-comment-input-font-size,
+		var(--stuic-input-font-size-sm, 0.8125rem)
+	);
+	--_min-height: var(--stuic-comment-input-min-height, 4rem);
+}
+.stuic-comment-input[data-size="lg"] {
+	--_pad-x: var(--stuic-comment-input-padding-x, var(--stuic-input-padding-x-lg, 1rem));
+	--_pad-y: var(
+		--stuic-comment-input-padding-y,
+		var(--stuic-input-padding-y-lg, 0.75rem)
+	);
+	--_font-size: var(
+		--stuic-comment-input-font-size,
+		var(--stuic-input-font-size-lg, 1.0625rem)
+	);
+	--_min-height: var(--stuic-comment-input-min-height, 7rem);
+}

package/dist/components/CommentInput/index.d.ts

@@ -0,0 +1,2 @@
+export { default as CommentInput, type Props as CommentInputProps, type CommentInputMode, } from "./CommentInput.svelte";
+export type { MarkdownRenderer } from "./_internal/render.js";

package/dist/components/CommentInput/index.js

@@ -0,0 +1 @@
+export { default as CommentInput, } from "./CommentInput.svelte";

package/dist/components/Input/FieldAssets.svelte

@@ -14,8 +14,10 @@
 		iconFileWord,
 		iconFileZip,
 		iconPlus as iconAdd,
+		iconChevronLeft,
+		iconChevronRight,
 	} from "../../icons/index.js";
-	import { onDestroy, type Snippet } from "svelte";
+	import { onDestroy, tick, type Snippet } from "svelte";
 	import { fileDropzone } from "../../actions/file-dropzone.svelte.js";
 	import { highlightDragover } from "../../actions/highlight-dragover.svelte.js";
 	import { tooltip } from "../../actions/index.js";
@@ -58,6 +60,10 @@
 			close: "Close preview window",
 			download: "Download original",
 			invalid_type: 'Some of the files are not supported. Allowed are only "{{accept}}".',
+			move_prev: "Move earlier",
+			move_next: "Move later",
+			moved_prev: "Moved {{name}} earlier",
+			moved_next: "Moved {{name}} later",
 		};
 		let out = m[k] ?? fallback ?? k;
 
@@ -167,6 +173,13 @@
 		withOnProgress?: boolean;
 		classControls?: string;
 		isLoading?: boolean;
+		/**
+		 * Opt-in: when true, each asset tile in the grid gets "Move earlier" / "Move later"
+		 * controls (shown on hover/focus) so the user can manually reorder the assets. The
+		 * chosen order is serialized to `value`. Buttons only, no drag (the field's drag is
+		 * reserved for file drops); full keyboard + aria-live announcements. Default `false`.
+		 */
+		ordered?: boolean;
 		//
 		classWrap?: string;
 	}
@@ -231,6 +244,7 @@
 		withOnProgress,
 		classControls = "",
 		isLoading = false,
+		ordered = false,
 		parseValue = (strigifiedModels: string) => {
 			const val = strigifiedModels ?? "[]";
 			try {
@@ -249,6 +263,10 @@
 	let isUploading = $state(false);
 	let cardinality = $derived(_cardinality === -1 ? Infinity : _cardinality);
 	let isMultiple = $derived(cardinality > 1);
+	// reordering ("ordered") is opt-in and only meaningful with more than one asset
+	let canArrange = $derived(ordered && isMultiple);
+	// aria-live announcement text for reorder actions
+	let liveAnnouncement = $state("");
 	let parentHiddenInputEl: HTMLInputElement | undefined = $state();
 	let hasLabel = $derived(isTHCNotEmpty(label) || typeof label === "function");
 	let inputEl = $state<HTMLInputElement>()!;
@@ -348,6 +366,44 @@
 		notifications?.info(t("deleted", { name }));
 	}
 
+	// re-focus the same logical move button on the tile that moved, so repeated presses keep
+	// walking the item; if that button is now disabled (a boundary), fall back to the enabled one.
+	// We target by the NEW index (querySelectorAll DOM order == array order) to avoid escaping
+	// blob/url ids into a CSS attribute selector.
+	function focusMovedButton(to: number, which: "prev" | "next") {
+		tick().then(() => {
+			const tile = wrapEl?.querySelectorAll<HTMLElement>("[data-asset-tile]")[to];
+			if (!tile) return;
+			let btn = tile.querySelector<HTMLButtonElement>(`[data-arrange-btn="${which}"]`);
+			if (!btn || btn.disabled) {
+				btn =
+					tile.querySelector<HTMLButtonElement>(
+						`[data-arrange-btn="prev"]:not([disabled])`
+					) ||
+					tile.querySelector<HTMLButtonElement>(
+						`[data-arrange-btn="next"]:not([disabled])`
+					);
+			}
+			btn?.focus();
+		});
+	}
+
+	// Reorder by moving the asset at `from` to `to`. Splices a copy and re-serializes (same
+	// value-driven pattern as remove_by_idx). Safe mid-upload: processAssets reconciles the
+	// resolved asset by blob-url id (findIndex), never by array position.
+	function move(from: number, to: number) {
+		if (to < 0 || to >= assets.length || from === to) return;
+		const next = [...assets];
+		const [item] = next.splice(from, 1);
+		if (!item) return;
+		next.splice(to, 0, item);
+		value = serializeValue(next);
+		liveAnnouncement = t(to < from ? "moved_prev" : "moved_next", {
+			name: item.name,
+		}) as string;
+		focusMovedButton(to, to < from ? "prev" : "next");
+	}
+
 	onDestroy(() => {
 		try {
 			assets.forEach((a) => {
@@ -369,11 +425,15 @@
 			<SpinnerCircleOscillate />
 		</div>
 	{:else}
+		{#if canArrange}
+			<!-- screen-reader announcements for reorder actions -->
+			<div class="sr-only" aria-live="polite" aria-atomic="true">{liveAnnouncement}</div>
+		{/if}
 		<div class={["p-2 flex items-center gap-0.5 flex-wrap"]}>
-			{#each assets as asset, idx}
+			{#each assets as asset, idx (asset.id)}
 				{@const { thumb, full, original } = asset_urls(asset)}
 				{@const _is_img = isImage(asset.type ?? thumb)}
-				<div class="relative group">
+				<div class="relative group" data-asset-tile>
 					<button
 						class={[objectSize, "bg-black/10 grid place-content-center", classControls]}
 						onclick={(e) => {
@@ -420,6 +480,59 @@
 							</span>
 						{/if}
 					</button>
+
+					{#if canArrange && assets.length > 1}
+						<!-- Reorder controls (sibling of the thumbnail <button>, never nested — that
+						would be invalid HTML). Hidden until the tile is hovered/focused; pointer
+						events are gated to hover/focus so an invisible control can't intercept a
+						click meant for the thumbnail, while keyboard users can still Tab to them. -->
+						<div
+							class={[
+								"absolute inset-x-0 top-0 flex items-start justify-between p-0.5",
+								"opacity-0 transition-opacity pointer-events-none",
+								"group-hover:opacity-100 focus-within:opacity-100",
+							]}
+						>
+							<button
+								type="button"
+								data-arrange-btn="prev"
+								disabled={idx === 0}
+								aria-label={t("move_prev")}
+								use:tooltip={() => ({ content: t("move_prev") })}
+								class={[
+									"grid place-content-center rounded p-0.5 bg-black/60 text-white hover:bg-black/80",
+									"pointer-events-none group-hover:pointer-events-auto focus:pointer-events-auto",
+									"disabled:opacity-30 disabled:cursor-not-allowed disabled:hover:bg-black/60",
+								]}
+								onclick={(e) => {
+									e.stopPropagation();
+									e.preventDefault();
+									move(idx, idx - 1);
+								}}
+							>
+								{@html iconChevronLeft({ size: 16 })}
+							</button>
+							<button
+								type="button"
+								data-arrange-btn="next"
+								disabled={idx === assets.length - 1}
+								aria-label={t("move_next")}
+								use:tooltip={() => ({ content: t("move_next") })}
+								class={[
+									"grid place-content-center rounded p-0.5 bg-black/60 text-white hover:bg-black/80",
+									"pointer-events-none group-hover:pointer-events-auto focus:pointer-events-auto",
+									"disabled:opacity-30 disabled:cursor-not-allowed disabled:hover:bg-black/60",
+								]}
+								onclick={(e) => {
+									e.stopPropagation();
+									e.preventDefault();
+									move(idx, idx + 1);
+								}}
+							>
+								{@html iconChevronRight({ size: 16 })}
+							</button>
+						</div>
+					{/if}
 				</div>
 			{/each}
 			<Button