@marianmeres/stuic 3.132.0 → 3.133.0

package/dist/components/CommentInput/CommentInput.svelte

@@ -0,0 +1,547 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { HTMLTextareaAttributes } from "svelte/elements";
+	import type { ValidateOptions } from "../../actions/validate.svelte.js";
+	import type { THC } from "../Thc/Thc.svelte";
+	import type { InputWrapClassProps } from "../Input/types.js";
+	import type { MarkdownRenderer } from "./_internal/render.js";
+
+	type SnippetWithId = Snippet<[{ id: string }]>;
+
+	/** Active tab of the comment box. */
+	export type CommentInputMode = "write" | "preview";
+
+	export interface Props
+		extends
+			Omit<HTMLTextareaAttributes, "value" | "class" | "style">,
+			InputWrapClassProps {
+		/** Comment text (raw markdown). Bindable. */
+		value?: string;
+		/** Active tab. Bindable. Default `"write"`. */
+		mode?: CommentInputMode;
+		/** The underlying `<textarea>` element. Bindable. */
+		input?: HTMLTextAreaElement;
+		/** Name attribute of the textarea, for native form submission. */
+		name?: string;
+		//
+		label?: SnippetWithId | THC;
+		description?: SnippetWithId | THC;
+		class?: string;
+		id?: string;
+		tabindex?: number;
+		renderSize?: "sm" | "md" | "lg" | string;
+		required?: boolean;
+		disabled?: boolean;
+		placeholder?: string;
+		validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+		/** Trim surrounding whitespace on blur. Default `true`. */
+		useTrim?: boolean;
+		/** Grow the textarea with its content (up to `max`). Default `true`. */
+		useAutogrow?: boolean | { enabled?: boolean; max?: number };
+		//
+		/** Show the Write/Preview tabs. Default `true`. Set `false` for a plain markdown textarea. */
+		showTabs?: boolean;
+		/** Label for the "write" tab. Default `"Write"`. */
+		writeLabel?: string;
+		/** Label for the "preview" tab. Default `"Preview"`. */
+		previewLabel?: string;
+		/** Show the subtle "Markdown supported" hint in the tab bar. Default `true`. */
+		showMarkdownHint?: boolean;
+		/** Text of the markdown hint. Default `"Markdown supported"`. */
+		markdownHintLabel?: string;
+		/** Placeholder shown in the Preview tab when there is nothing to render. */
+		previewEmptyLabel?: string;
+		/** Text shown in the Preview tab while the renderer is (lazy-)loading. */
+		previewLoadingLabel?: string;
+		/**
+		 * Override the Preview renderer. Receives the raw markdown, returns (or
+		 * resolves to) an HTML string that is rendered as-is — **you are responsible
+		 * for sanitizing it**. When omitted, the bundled marked + DOMPurify pipeline
+		 * is used (lazy-loaded; requires the optional `marked` / `dompurify` peers).
+		 */
+		renderMarkdown?: MarkdownRenderer;
+		//
+		/**
+		 * Submit handler. Receives the current value. May be async — the submit
+		 * button shows a spinner and the box is disabled while it resolves.
+		 */
+		onSubmit?: (value: string) => void | Promise<void>;
+		/** Cancel handler. When set, a Cancel button is shown by default. */
+		onCancel?: () => void;
+		/** Fired on every edit with the new value. */
+		onChange?: (value: string) => void;
+		/** Submit button label. Default `"Comment"`. */
+		submitLabel?: string;
+		/** Cancel button label. Default `"Cancel"`. */
+		cancelLabel?: string;
+		/** Show the submit button. Defaults to `true` when `onSubmit` is set. */
+		showSubmit?: boolean;
+		/** Show the cancel button. Defaults to `true` when `onCancel` is set. */
+		showCancel?: boolean;
+		/** Submit on ⌘/Ctrl+Enter while the textarea is focused. Default `true`. */
+		submitOnModEnter?: boolean;
+		/** Clear the value after a successful submit. Default `true`. */
+		clearOnSubmit?: boolean;
+		/** Disable the submit button when the value is empty/whitespace. Default `true`. */
+		submitDisabledWhenEmpty?: boolean;
+		/** Externally-controlled busy state (disables the box + submit). */
+		busy?: boolean;
+		//
+		labelAfter?: SnippetWithId | THC;
+		below?: SnippetWithId | THC;
+		labelLeft?: boolean;
+		labelLeftWidth?: "normal" | "wide";
+		labelLeftBreakpoint?: number;
+		//
+		/** Optional avatar/gutter rendered to the left of the box. */
+		avatar?: SnippetWithId | THC;
+		/** Extra content rendered in the footer, left of the buttons (e.g. attach). */
+		footer?: Snippet;
+		//
+		/** Classes for the `<textarea>` element. */
+		classInput?: string;
+		/** Classes for the tab bar. */
+		classBar?: string;
+		/** Classes for the preview panel. */
+		classPreview?: string;
+		/** Classes for the footer (button row). */
+		classFooter?: string;
+		style?: string;
+	}
+</script>
+
+<script lang="ts">
+	import { autogrow } from "../../actions/autogrow.svelte.js";
+	import { trim } from "../../actions/trim.svelte.js";
+	import {
+		validate as validateAction,
+		type ValidationResult,
+	} from "../../actions/validate.svelte.js";
+	import { getId } from "../../utils/get-id.js";
+	import { twMerge } from "../../utils/tw-merge.js";
+	import { Button } from "../Button/index.js";
+	import Thc from "../Thc/Thc.svelte";
+	import InputWrap from "../Input/_internal/InputWrap.svelte";
+	import { renderMarkdownSafe } from "./_internal/render.js";
+
+	let {
+		value = $bindable(""),
+		mode = $bindable("write"),
+		input = $bindable(),
+		name,
+		//
+		label = "",
+		description,
+		class: classProp,
+		id = getId(),
+		tabindex = 0,
+		renderSize = "md",
+		required = false,
+		disabled = false,
+		placeholder,
+		// Renamed to avoid collision with the exported `validate()` below.
+		validate: validateProp,
+		useTrim = true,
+		useAutogrow = true,
+		//
+		showTabs = true,
+		writeLabel = "Write",
+		previewLabel = "Preview",
+		showMarkdownHint = true,
+		markdownHintLabel = "Markdown supported",
+		previewEmptyLabel = "Nothing to preview",
+		previewLoadingLabel = "Loading preview…",
+		renderMarkdown,
+		//
+		onSubmit,
+		onCancel,
+		onChange,
+		submitLabel = "Comment",
+		cancelLabel = "Cancel",
+		showSubmit,
+		showCancel,
+		submitOnModEnter = true,
+		clearOnSubmit = true,
+		submitDisabledWhenEmpty = true,
+		busy = false,
+		//
+		labelAfter,
+		below,
+		labelLeft = false,
+		labelLeftWidth = "normal",
+		labelLeftBreakpoint = 480,
+		//
+		avatar,
+		footer,
+		//
+		classInput,
+		classBar,
+		classPreview,
+		classFooter,
+		classLabel,
+		classLabelBox,
+		classInputBox,
+		classInputBoxWrap,
+		classInputBoxWrapInvalid,
+		classDescBox,
+		classDescBoxToggle,
+		classBelowBox,
+		classValidationBox,
+		style,
+		//
+		...rest
+	}: Props = $props();
+
+	// --- Validation (mirrors FieldTextarea: action lives on the real textarea) ---
+	let validation: ValidationResult | undefined = $state();
+	const setValidationResult = (res: ValidationResult) => (validation = res);
+	let _doValidate: (() => void) | undefined = $state();
+
+	// --- Submit state ---------------------------------------------------------
+	let submitting = $state(false);
+	const isEmpty = $derived(!(value ?? "").trim());
+	// Resolve the show* defaults from the presence of their handlers.
+	const _showSubmit = $derived(showSubmit ?? !!onSubmit);
+	const _showCancel = $derived(showCancel ?? !!onCancel);
+	const _busy = $derived(disabled || busy || submitting);
+	const canSubmit = $derived(!_busy && !(submitDisabledWhenEmpty && isEmpty));
+
+	// --- Preview rendering ----------------------------------------------------
+	let previewHtml = $state("");
+	let previewError = $state(false);
+	let previewLoading = $state(false);
+
+	$effect(() => {
+		if (mode !== "preview" || !showTabs) return;
+		const md = value ?? "";
+		if (!md.trim()) {
+			previewHtml = "";
+			previewError = false;
+			previewLoading = false;
+			return;
+		}
+		const render = renderMarkdown ?? renderMarkdownSafe;
+		let cancelled = false;
+		previewLoading = true;
+		// Drop the previous value's HTML so the loading placeholder shows instead of
+		// briefly rendering content that no longer matches `value`.
+		previewHtml = "";
+		previewError = false;
+		(async () => {
+			try {
+				const html = await render(md);
+				if (cancelled) return;
+				previewHtml = html;
+				previewError = false;
+			} catch (err) {
+				if (cancelled) return;
+				previewHtml = "";
+				previewError = true;
+				// eslint-disable-next-line no-console
+				console.warn(
+					"[CommentInput] preview renderer failed. When using the default " +
+						"renderer, make sure the optional peers `marked` and `dompurify` " +
+						"are installed, or pass a `renderMarkdown` function.",
+					err
+				);
+			} finally {
+				if (!cancelled) previewLoading = false;
+			}
+		})();
+		return () => {
+			cancelled = true;
+		};
+	});
+
+	// Returning to the Write tab: re-measure the textarea. autogrow can't size a
+	// `display:none` element, so an external value change made while previewing
+	// would otherwise leave the textarea at a stale height.
+	$effect(() => {
+		if (mode !== "write" || !input || !useAutogrow) return;
+		const el = input;
+		const max =
+			typeof useAutogrow === "object" && useAutogrow.max ? useAutogrow.max : 250;
+		requestAnimationFrame(() => {
+			el.style.height = "auto";
+			const cs = getComputedStyle(el);
+			const borderY =
+				cs.boxSizing === "border-box"
+					? parseFloat(cs.borderTopWidth) + parseFloat(cs.borderBottomWidth)
+					: 0;
+			el.style.height = Math.min(el.scrollHeight + borderY, max) + "px";
+		});
+	});
+
+	// --- Handlers -------------------------------------------------------------
+	async function handleSubmit() {
+		if (!canSubmit) return;
+		// Validate before invoking the handler — the submit button bypasses any
+		// form-level submit check, so enforce it here (surfaces the inline message).
+		const res = validate();
+		if (res && !res.valid) {
+			mode = "write";
+			return;
+		}
+		try {
+			submitting = true;
+			await onSubmit?.(value ?? "");
+			if (clearOnSubmit) {
+				value = "";
+				// Back to Write so the (now empty) box is editable again.
+				if (mode === "preview") mode = "write";
+				validation = undefined;
+				input?.setCustomValidity?.("");
+			}
+		} finally {
+			submitting = false;
+		}
+	}
+
+	function handleCancel() {
+		onCancel?.();
+	}
+
+	function handleKeydown(e: KeyboardEvent) {
+		if (submitOnModEnter && (e.metaKey || e.ctrlKey) && e.key === "Enter") {
+			e.preventDefault();
+			handleSubmit();
+		}
+	}
+
+	function setMode(next: CommentInputMode) {
+		if (disabled) return;
+		mode = next;
+	}
+
+	// Roving-tabindex keyboard nav for the Write/Preview tablist (automatic
+	// activation — Arrow/Home/End move selection and focus together).
+	function handleTabKeydown(e: KeyboardEvent) {
+		const keys = ["ArrowRight", "ArrowLeft", "ArrowDown", "ArrowUp", "Home", "End"];
+		if (!keys.includes(e.key)) return;
+		e.preventDefault();
+		const next: CommentInputMode =
+			e.key === "Home"
+				? "write"
+				: e.key === "End"
+					? "preview"
+					: mode === "write"
+						? "preview"
+						: "write";
+		setMode(next);
+		if (disabled) return;
+		document.getElementById(`${id}-tab-${next}`)?.focus();
+	}
+
+	// --- Imperative API (mirrors FieldTextarea) -------------------------------
+	/** Trigger validation now. Renders the inline message if invalid. */
+	export function validate(): ValidationResult | undefined {
+		_doValidate?.();
+		return validation;
+	}
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		validation = undefined;
+		input?.setCustomValidity?.("");
+	}
+	/** Current validation state, or undefined if the validator has never run. */
+	export function getValidation(): ValidationResult | undefined {
+		return validation;
+	}
+	/** Focus the underlying `<textarea>` (switches to the Write tab first). */
+	export function focus(): void {
+		mode = "write";
+		input?.focus?.();
+	}
+	/** Scroll the field into view. Defaults to smooth + center. */
+	export function scrollIntoView(opts?: ScrollIntoViewOptions): void {
+		input?.scrollIntoView?.({ behavior: "smooth", block: "center", ...opts });
+	}
+	/** Programmatically run the submit flow (respects the empty/busy guards). */
+	export function submit(): void {
+		handleSubmit();
+	}
+</script>
+
+{#snippet thcOrSnippet(value?: SnippetWithId | THC)}
+	{#if typeof value === "function"}
+		{@render value({ id })}
+	{:else if value}
+		<Thc thc={value} forceAsHtml />
+	{/if}
+{/snippet}
+
+<InputWrap
+	{description}
+	class={classProp}
+	size={renderSize}
+	{id}
+	{label}
+	{labelAfter}
+	{below}
+	{required}
+	{disabled}
+	{labelLeft}
+	{labelLeftWidth}
+	{labelLeftBreakpoint}
+	{classLabel}
+	{classLabelBox}
+	{classInputBox}
+	{classInputBoxWrap}
+	{classInputBoxWrapInvalid}
+	{classDescBox}
+	{classDescBoxToggle}
+	{classBelowBox}
+	{classValidationBox}
+	{validation}
+	{style}
+>
+	<div class="stuic-comment-input" data-size={renderSize} class:disabled>
+		{#if avatar}
+			<div class="stuic-comment-input-avatar">
+				{@render thcOrSnippet(avatar)}
+			</div>
+		{/if}
+
+		<div class="stuic-comment-input-editor" data-mode={mode}>
+			{#if showTabs || showMarkdownHint}
+				<div class={twMerge("stuic-comment-input-bar", classBar)}>
+					{#if showTabs}
+						<div
+							class="stuic-comment-input-tabs"
+							role="tablist"
+							aria-label="Comment editor"
+						>
+							<button
+								id={`${id}-tab-write`}
+								type="button"
+								role="tab"
+								aria-selected={mode === "write"}
+								aria-controls={`${id}-panel-write`}
+								tabindex={mode === "write" ? 0 : -1}
+								data-active={mode === "write" ? "true" : undefined}
+								{disabled}
+								onclick={() => setMode("write")}
+								onkeydown={handleTabKeydown}
+							>
+								{writeLabel}
+							</button>
+							<button
+								id={`${id}-tab-preview`}
+								type="button"
+								role="tab"
+								aria-selected={mode === "preview"}
+								aria-controls={`${id}-panel-preview`}
+								tabindex={mode === "preview" ? 0 : -1}
+								data-active={mode === "preview" ? "true" : undefined}
+								{disabled}
+								onclick={() => setMode("preview")}
+								onkeydown={handleTabKeydown}
+							>
+								{previewLabel}
+							</button>
+						</div>
+					{/if}
+					{#if showMarkdownHint && mode === "write"}
+						<span class="stuic-comment-input-hint">{markdownHintLabel}</span>
+					{/if}
+				</div>
+			{/if}
+
+			<div class="stuic-comment-input-surface">
+				<div
+					class="stuic-comment-input-panel"
+					id={`${id}-panel-write`}
+					role={showTabs ? "tabpanel" : undefined}
+					aria-labelledby={showTabs ? `${id}-tab-write` : undefined}
+					hidden={showTabs && mode === "preview"}
+				>
+					<textarea
+						bind:value
+						bind:this={input}
+						{...rest}
+						{id}
+						{name}
+						{placeholder}
+						{tabindex}
+						{required}
+						disabled={_busy}
+						class={twMerge("stuic-comment-input-textarea", classInput)}
+						oninput={(e) => onChange?.(e.currentTarget.value)}
+						onkeydown={handleKeydown}
+						use:trim={() => ({
+							enabled: useTrim,
+							setValue: (v: string) => (value = v),
+						})}
+						use:validateAction={() => ({
+							enabled: validateProp !== false,
+							...(typeof validateProp === "boolean" ? {} : validateProp),
+							setValidationResult,
+							setDoValidate: (fn) => (_doValidate = fn),
+						})}
+						use:autogrow={() => ({
+							enabled: !!useAutogrow,
+							...(typeof useAutogrow === "boolean" ? {} : useAutogrow),
+							value,
+						})}
+					></textarea>
+				</div>
+
+				{#if showTabs && mode === "preview"}
+					<div
+						class={twMerge(
+							"stuic-comment-input-panel stuic-comment-input-preview",
+							classPreview
+						)}
+						id={`${id}-panel-preview`}
+						role="tabpanel"
+						aria-labelledby={`${id}-tab-preview`}
+					>
+						{#if previewError}
+							<p class="stuic-comment-input-preview-empty">Preview unavailable.</p>
+						{:else if !(value ?? "").trim()}
+							<p class="stuic-comment-input-preview-empty">{previewEmptyLabel}</p>
+						{:else if previewLoading && !previewHtml}
+							<p class="stuic-comment-input-preview-empty">{previewLoadingLabel}</p>
+						{:else}
+							<!-- eslint-disable-next-line svelte/no-at-html-tags -->
+							{@html previewHtml}
+						{/if}
+					</div>
+				{/if}
+			</div>
+
+			{#if _showSubmit || _showCancel || footer}
+				<div class={twMerge("stuic-comment-input-footer", classFooter)}>
+					<div class="stuic-comment-input-footer-start">
+						{@render footer?.()}
+					</div>
+					<div class="stuic-comment-input-footer-end">
+						{#if _showCancel}
+							<Button
+								type="button"
+								variant="ghost"
+								size={renderSize}
+								disabled={submitting}
+								onclick={handleCancel}
+							>
+								{cancelLabel}
+							</Button>
+						{/if}
+						{#if _showSubmit}
+							<Button
+								type="button"
+								intent="primary"
+								size={renderSize}
+								disabled={!canSubmit}
+								spinner={submitting}
+								onclick={handleSubmit}
+							>
+								{submitLabel}
+							</Button>
+						{/if}
+					</div>
+				</div>
+			{/if}
+		</div>
+	</div>
+</InputWrap>

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

@@ -0,0 +1,113 @@
+import type { Snippet } from "svelte";
+import type { HTMLTextareaAttributes } from "svelte/elements";
+import type { ValidateOptions } from "../../actions/validate.svelte.js";
+import type { THC } from "../Thc/Thc.svelte";
+import type { InputWrapClassProps } from "../Input/types.js";
+import type { MarkdownRenderer } from "./_internal/render.js";
+type SnippetWithId = Snippet<[{
+    id: string;
+}]>;
+/** Active tab of the comment box. */
+export type CommentInputMode = "write" | "preview";
+export interface Props extends Omit<HTMLTextareaAttributes, "value" | "class" | "style">, InputWrapClassProps {
+    /** Comment text (raw markdown). Bindable. */
+    value?: string;
+    /** Active tab. Bindable. Default `"write"`. */
+    mode?: CommentInputMode;
+    /** The underlying `<textarea>` element. Bindable. */
+    input?: HTMLTextAreaElement;
+    /** Name attribute of the textarea, for native form submission. */
+    name?: string;
+    label?: SnippetWithId | THC;
+    description?: SnippetWithId | THC;
+    class?: string;
+    id?: string;
+    tabindex?: number;
+    renderSize?: "sm" | "md" | "lg" | string;
+    required?: boolean;
+    disabled?: boolean;
+    placeholder?: string;
+    validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+    /** Trim surrounding whitespace on blur. Default `true`. */
+    useTrim?: boolean;
+    /** Grow the textarea with its content (up to `max`). Default `true`. */
+    useAutogrow?: boolean | {
+        enabled?: boolean;
+        max?: number;
+    };
+    /** Show the Write/Preview tabs. Default `true`. Set `false` for a plain markdown textarea. */
+    showTabs?: boolean;
+    /** Label for the "write" tab. Default `"Write"`. */
+    writeLabel?: string;
+    /** Label for the "preview" tab. Default `"Preview"`. */
+    previewLabel?: string;
+    /** Show the subtle "Markdown supported" hint in the tab bar. Default `true`. */
+    showMarkdownHint?: boolean;
+    /** Text of the markdown hint. Default `"Markdown supported"`. */
+    markdownHintLabel?: string;
+    /** Placeholder shown in the Preview tab when there is nothing to render. */
+    previewEmptyLabel?: string;
+    /** Text shown in the Preview tab while the renderer is (lazy-)loading. */
+    previewLoadingLabel?: string;
+    /**
+     * Override the Preview renderer. Receives the raw markdown, returns (or
+     * resolves to) an HTML string that is rendered as-is — **you are responsible
+     * for sanitizing it**. When omitted, the bundled marked + DOMPurify pipeline
+     * is used (lazy-loaded; requires the optional `marked` / `dompurify` peers).
+     */
+    renderMarkdown?: MarkdownRenderer;
+    /**
+     * Submit handler. Receives the current value. May be async — the submit
+     * button shows a spinner and the box is disabled while it resolves.
+     */
+    onSubmit?: (value: string) => void | Promise<void>;
+    /** Cancel handler. When set, a Cancel button is shown by default. */
+    onCancel?: () => void;
+    /** Fired on every edit with the new value. */
+    onChange?: (value: string) => void;
+    /** Submit button label. Default `"Comment"`. */
+    submitLabel?: string;
+    /** Cancel button label. Default `"Cancel"`. */
+    cancelLabel?: string;
+    /** Show the submit button. Defaults to `true` when `onSubmit` is set. */
+    showSubmit?: boolean;
+    /** Show the cancel button. Defaults to `true` when `onCancel` is set. */
+    showCancel?: boolean;
+    /** Submit on ⌘/Ctrl+Enter while the textarea is focused. Default `true`. */
+    submitOnModEnter?: boolean;
+    /** Clear the value after a successful submit. Default `true`. */
+    clearOnSubmit?: boolean;
+    /** Disable the submit button when the value is empty/whitespace. Default `true`. */
+    submitDisabledWhenEmpty?: boolean;
+    /** Externally-controlled busy state (disables the box + submit). */
+    busy?: boolean;
+    labelAfter?: SnippetWithId | THC;
+    below?: SnippetWithId | THC;
+    labelLeft?: boolean;
+    labelLeftWidth?: "normal" | "wide";
+    labelLeftBreakpoint?: number;
+    /** Optional avatar/gutter rendered to the left of the box. */
+    avatar?: SnippetWithId | THC;
+    /** Extra content rendered in the footer, left of the buttons (e.g. attach). */
+    footer?: Snippet;
+    /** Classes for the `<textarea>` element. */
+    classInput?: string;
+    /** Classes for the tab bar. */
+    classBar?: string;
+    /** Classes for the preview panel. */
+    classPreview?: string;
+    /** Classes for the footer (button row). */
+    classFooter?: string;
+    style?: string;
+}
+import { type ValidationResult } from "../../actions/validate.svelte.js";
+declare const CommentInput: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+    submit: () => void;
+}, "value" | "input" | "mode">;
+type CommentInput = ReturnType<typeof CommentInput>;
+export default CommentInput;

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/index.css

@@ -71,6 +71,7 @@ In practice:
 @import "./components/LoginOrRegisterForm/index.css";
 @import "./components/Checkout/index.css";
 @import "./components/CommandMenu/index.css";
+@import "./components/CommentInput/index.css";
 @import "./components/ContactUsForm/index.css";
 @import "./components/CronInput/index.css";
 @import "./components/DataTable/index.css";

package/dist/index.d.ts

@@ -38,6 +38,7 @@ export * from "./components/Checkout/index.js";
 export * from "./components/Collapsible/index.js";
 export * from "./components/ColorScheme/index.js";
 export * from "./components/CommandMenu/index.js";
+export * from "./components/CommentInput/index.js";
 export * from "./components/ContactUsForm/index.js";
 export * from "./components/CronInput/index.js";
 export * from "./components/DataTable/index.js";

package/dist/index.js

@@ -39,6 +39,7 @@ export * from "./components/Checkout/index.js";
 export * from "./components/Collapsible/index.js";
 export * from "./components/ColorScheme/index.js";
 export * from "./components/CommandMenu/index.js";
+export * from "./components/CommentInput/index.js";
 export * from "./components/ContactUsForm/index.js";
 export * from "./components/CronInput/index.js";
 export * from "./components/DataTable/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.132.0",
+	"version": "3.133.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",
@@ -72,6 +72,8 @@
 		"@milkdown/prose": "^7.0.0",
 		"@milkdown/transformer": "^7.0.0",
 		"@milkdown/utils": "^7.0.0",
+		"dompurify": "^3.0.0",
+		"marked": "^18.0.0",
 		"svelte": "^5.0.0"
 	},
 	"peerDependenciesMeta": {
@@ -119,15 +121,21 @@
 		},
 		"@milkdown/utils": {
 			"optional": true
+		},
+		"dompurify": {
+			"optional": true
+		},
+		"marked": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
 		"@codemirror/commands": "^6.10.4",
 		"@codemirror/lang-markdown": "^6.5.0",
-		"@codemirror/language": "^6.12.3",
+		"@codemirror/language": "^6.12.4",
 		"@codemirror/language-data": "^6.5.2",
 		"@codemirror/state": "^6.7.0",
-		"@codemirror/view": "^6.43.2",
+		"@codemirror/view": "^6.43.4",
 		"@eslint/js": "^9.39.4",
 		"@marianmeres/random-human-readable": "^1.10.2",
 		"@milkdown/core": "^7.21.2",
@@ -149,11 +157,13 @@
 		"@tailwindcss/vite": "^4.3.1",
 		"@types/node": "^25.9.4",
 		"@vitest/browser-playwright": "^4.1.9",
+		"dompurify": "^3.4.11",
 		"dotenv": "^16.6.1",
 		"eslint": "^9.39.4",
 		"globals": "^16.5.0",
+		"marked": "^18.0.5",
 		"playwright": "^1.61.1",
-		"prettier": "^3.8.4",
+		"prettier": "^3.9.0",
 		"prettier-plugin-svelte": "^3.5.2",
 		"publint": "^0.3.21",
 		"svelte": "^5.56.4",
@@ -170,7 +180,7 @@
 		"@marianmeres/clog": "^3.21.0",
 		"@marianmeres/countries": "^1.0.1",
 		"@marianmeres/cron": "^2.0.1",
-		"@marianmeres/design-tokens": "^1.9.0",
+		"@marianmeres/design-tokens": "^1.12.0",
 		"@marianmeres/icons-fns": "^5.0.0",
 		"@marianmeres/item-collection": "^1.4.2",
 		"@marianmeres/paging-store": "^2.1.1",