entasis 0.13.6 → 0.13.8

package/dist/components/Form/Form/form.state.svelte.d.ts

@@ -527,6 +527,7 @@ export declare class FormState<I extends FormInputs = FormInputs> {
     } & Omit<import("../Field/field.js").InputProps<"signature">, "theme"> & {
         format?: import("../SignatureInput/signatureInput.strokes.ts").SignatureFormat;
         inkColor?: string;
+        imageInk?: import("../SignatureInput/signatureInput.props.ts").SignatureImageInk;
         strokeWidth?: number;
         placeholder?: string;
         clearLabel?: string;
@@ -1412,6 +1413,7 @@ export declare class FormState<I extends FormInputs = FormInputs> {
     } & Omit<import("../Field/field.js").InputProps<"signature">, "theme"> & {
         format?: import("../SignatureInput/signatureInput.strokes.ts").SignatureFormat;
         inkColor?: string;
+        imageInk?: import("../SignatureInput/signatureInput.props.ts").SignatureImageInk;
         strokeWidth?: number;
         placeholder?: string;
         clearLabel?: string;
@@ -2493,6 +2495,7 @@ export declare class FormState<I extends FormInputs = FormInputs> {
     } & Omit<import("../Field/field.js").InputProps<"signature">, "theme"> & {
         format?: import("../SignatureInput/signatureInput.strokes.ts").SignatureFormat;
         inkColor?: string;
+        imageInk?: import("../SignatureInput/signatureInput.props.ts").SignatureImageInk;
         strokeWidth?: number;
         placeholder?: string;
         clearLabel?: string;
@@ -3378,6 +3381,7 @@ export declare class FormState<I extends FormInputs = FormInputs> {
     } & Omit<import("../Field/field.js").InputProps<"signature">, "theme"> & {
         format?: import("../SignatureInput/signatureInput.strokes.ts").SignatureFormat;
         inkColor?: string;
+        imageInk?: import("../SignatureInput/signatureInput.props.ts").SignatureImageInk;
         strokeWidth?: number;
         placeholder?: string;
         clearLabel?: string;

package/dist/components/Form/Form/visibility.d.ts

@@ -1400,6 +1400,7 @@ export declare function prepareInputProps(input: FormFieldInput, size: Sizes, la
     format?: import("../SignatureInput/signatureInput.strokes.ts").SignatureFormat | undefined;
     clearLabel?: string | undefined;
     inkColor?: string | undefined;
+    imageInk?: import("../SignatureInput/signatureInput.props.ts").SignatureImageInk | undefined;
     strokeWidth?: number | undefined;
     undoLabel?: string | undefined;
     display?: string;
@@ -7755,6 +7756,7 @@ export declare function prepareInputProps(input: FormFieldInput, size: Sizes, la
     format?: import("../SignatureInput/signatureInput.strokes.ts").SignatureFormat | undefined;
     clearLabel?: string | undefined;
     inkColor?: string | undefined;
+    imageInk?: import("../SignatureInput/signatureInput.props.ts").SignatureImageInk | undefined;
     strokeWidth?: number | undefined;
     undoLabel?: string | undefined;
     display?: string;

package/dist/components/Form/MultiStepForm/multiStepForm.state.svelte.d.ts

@@ -442,6 +442,7 @@ export declare class MultiStepFormState<I extends MultiStepFormItems = FormStep[
     } & Omit<import("../Field/field.ts").InputProps<"signature">, "theme"> & {
         format?: import("../SignatureInput/signatureInput.strokes.ts").SignatureFormat;
         inkColor?: string;
+        imageInk?: import("../SignatureInput/signatureInput.props.ts").SignatureImageInk;
         strokeWidth?: number;
         placeholder?: string;
         clearLabel?: string;
@@ -1327,6 +1328,7 @@ export declare class MultiStepFormState<I extends MultiStepFormItems = FormStep[
     } & Omit<import("../Field/field.ts").InputProps<"signature">, "theme"> & {
         format?: import("../SignatureInput/signatureInput.strokes.ts").SignatureFormat;
         inkColor?: string;
+        imageInk?: import("../SignatureInput/signatureInput.props.ts").SignatureImageInk;
         strokeWidth?: number;
         placeholder?: string;
         clearLabel?: string;
@@ -2408,6 +2410,7 @@ export declare class MultiStepFormState<I extends MultiStepFormItems = FormStep[
     } & Omit<import("../Field/field.ts").InputProps<"signature">, "theme"> & {
         format?: import("../SignatureInput/signatureInput.strokes.ts").SignatureFormat;
         inkColor?: string;
+        imageInk?: import("../SignatureInput/signatureInput.props.ts").SignatureImageInk;
         strokeWidth?: number;
         placeholder?: string;
         clearLabel?: string;
@@ -3293,6 +3296,7 @@ export declare class MultiStepFormState<I extends MultiStepFormItems = FormStep[
     } & Omit<import("../Field/field.ts").InputProps<"signature">, "theme"> & {
         format?: import("../SignatureInput/signatureInput.strokes.ts").SignatureFormat;
         inkColor?: string;
+        imageInk?: import("../SignatureInput/signatureInput.props.ts").SignatureImageInk;
         strokeWidth?: number;
         placeholder?: string;
         clearLabel?: string;

package/dist/components/Form/SignatureInput/SignatureInput.svelte

@@ -33,6 +33,7 @@
 		size = 'normal',
 		format = 'png',
 		inkColor = '#000000',
+		imageInk = 'theme',
 		strokeWidth = 2.5,
 		placeholder,
 		clearLabel,
@@ -125,6 +126,27 @@
 
 	const hasInk = $derived(strokes.length > 0 || current !== null);
 	const image = $derived(hasInk ? null : (field.value ?? null));
+
+	// A mask image is fetched in CORS mode: a URL from another origin that does not allow it would
+	// paint nothing. Such a URL is probed once and, when refused, shown as the image itself.
+	let refusedMask = $state<string | null>(null);
+	const ownsImage = (url: string) =>
+		/^(data|blob):/.test(url) || new URL(url, location.href).origin === location.origin;
+	$effect(() => {
+		if (imageInk !== 'theme' || !image || ownsImage(image)) return;
+		const probe = new Image();
+		probe.crossOrigin = 'anonymous';
+		probe.onerror = () => (refusedMask = image);
+		probe.src = image;
+		return () => {
+			probe.onerror = null;
+		};
+	});
+	const imageMode = $derived(imageInk === 'theme' && refusedMask !== image ? 'theme' : 'as-is');
+	// Quoted for `url()`: a data URL may hold characters CSS would end the string on.
+	const maskImage = $derived(
+		image ? `url("${image.replace(/["\\\n]/g, (char) => encodeURIComponent(char))}")` : undefined
+	);
 	const shapes = $derived(
 		[...strokes, ...(current ? [current] : [])].flatMap((stroke) =>
 			strokeShapes(stroke, strokeWidth)
@@ -277,7 +299,23 @@
 				</div>
 			{/if}
 			{#if image}
-				<img data-slot="signature-image" src={image} alt="" class={classes.image()} />
+				{#if imageMode === 'theme'}
+					<span
+						data-slot="signature-image"
+						data-ink="theme"
+						class={classes.image({ ink: 'theme' })}
+						style:mask-image={maskImage}
+						style:-webkit-mask-image={maskImage}
+					></span>
+				{:else}
+					<img
+						data-slot="signature-image"
+						data-ink="as-is"
+						src={image}
+						alt=""
+						class={classes.image({ ink: 'as-is' })}
+					/>
+				{/if}
 			{/if}
 			<svg data-slot="signature-ink" class={classes.ink()} aria-hidden="true" focusable="false">
 				<g fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round">

package/dist/components/Form/SignatureInput/index.d.ts

@@ -1,4 +1,4 @@
 export { default as SignatureInput } from './SignatureInput.svelte';
-export type { SignatureInputProps } from './signatureInput.props.js';
+export type { SignatureImageInk, SignatureInputProps } from './signatureInput.props.js';
 export type { SignatureFormat, SignaturePoint, SignatureStroke } from './signatureInput.strokes.js';
 export { signatureInputTheme, setSignatureInputTheme, useSignatureInputTheme, type SignatureInputTheme, type SignatureInputThemeProps } from './signatureInput.theme.js';

package/dist/components/Form/SignatureInput/signatureInput.mcp.d.ts

@@ -1 +1 @@
-export declare const signatureInputDescription = "\n# SignatureInput Component\n\nSignatureInput is a form field where a person signs with a mouse, a finger or a pen. Its value is the signature as an image: a data URL cropped to the ink (PNG by default, or SVG), ready to store, submit or place in a document.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n  import { SignatureInput } from './index.ts';\n\n  let signature = $state<string | null>(null);\n</script>\n\n<SignatureInput label=\"Signature\" required bind:value={signature} />\n```\n\nIn a Form or `ask()`, use `type: 'signature'`:\n\n```ts\nimport { ask } from 'entasis/ask';\n\nconst result = await ask({\n  title: 'Sign the mandate',\n  inputs: { signature: { type: 'signature', label: 'Signature', required: true } },\n  confirm: 'Sign',\n  cancel: 'Cancel'\n});\n```\n\n## Props\n\nExtends the shared Field props (`label`, `description`, `helper`, `required`, `disabled`, `readOnly`, `name`, `size`, `density`, `labelPosition`, `messages`, `onValidate`, `errors`, `focused`, `visible`) plus:\n\n- **value**: `string | null` (bindable) \u2014 the signature as a data URL, or `null` while the pad is empty.\n- **defaultValue**: `string | null` \u2014 initial value when `value` is omitted. Any image data URL works: a saved signature shows in the pad, scaled to fit.\n- **onValueChange**: `(value: string | null) => void` \u2014 called once per finished stroke, undo and clear.\n- **format**: `'png' | 'svg'` (default `'png'`) \u2014 the image the value holds. A PNG is drawn at twice the pad's resolution; an SVG keeps every stroke as a vector path.\n- **inkColor**: `string` (default `'#000000'`) \u2014 CSS color of the ink in the exported image, so a signature reads on a white document whatever the app's theme. The pad itself draws in the theme's text color.\n- **strokeWidth**: `number` (default `2.5`) \u2014 line width in CSS pixels at a medium pen pressure. A pen's pressure makes the line thinner or thicker (half to one and a half times); a mouse or a finger draws at this width.\n- **placeholder**: `string` \u2014 hint on the signing line while the pad is empty. Defaults to the i18n `signatureInputPlaceholder` (\"Sign here\").\n- **clearLabel**, **undoLabel**: `string` \u2014 accessible labels and tooltips of the two buttons.\n- **i18n**: `Partial<Messages>` \u2014 per-instance translations.\n- **size**: `'small' | 'normal' | 'large'` \u2014 pad height (112, 144 or 176 px) and placeholder text size. Override the height with the `pad` theme part.\n- **theme**: `SignatureInputThemeProps` and Field theme parts.\n\n## Behaviour\n\n- Each stroke runs from pointer down to pointer up and is smoothed through its samples. The value updates when a stroke ends, not while it is drawn.\n- The undo button (or Ctrl/Cmd+Z on the pad) removes the last stroke; the clear button (or Delete/Backspace on the pad) empties the pad and sets the value to `null`. Both show only while the pad is editable and has a signature.\n- A value set from outside (a saved signature, a Form reset) replaces the strokes and shows as an image. Drawing over it starts a new signature: the image is replaced, not added to. Undo only steps back through strokes drawn since.\n- `disabled` and `readOnly` stop drawing and hide the buttons; a read-only pad still shows, focuses, validates and submits its value. A stroke in progress is dropped when the pad becomes disabled or read-only.\n- Required: an empty pad (`null` or `''`) fails `required`.\n- Native forms: a hidden input (`FieldHiddenInputs`) submits the data URL under `name`.\n\n## Accessibility\n\n- The pad is the field's control: it is focusable, labelled by the field label (or \"Signature\" without one), and has `role=\"img\"` with a description of its state (\"No signature yet\u2026\" or \"Signed.\"). Errors and descriptions are linked by Field.\n- Drawing is a path-based gesture with no keyboard equivalent: signing by hand is the purpose of the field. Keyboard users can clear and undo with the buttons and keys above. When a keyboard-only path to consent is needed, pair the pad with another field (a typed full name, a consent checkbox).\n- The ink, placeholder and image are decorative (`aria-hidden`, empty `alt`).\n\n## Styling hooks\n\n- `data-slot`: `signature-frame`, `signature-pad`, `signature-ink`, `signature-image`, `signature-placeholder`, `signature-actions`.\n- On the pad: `data-filled=\"true\"` while it holds a signature, `data-drawing=\"true\"` during a stroke.\n\n## Theme parts\n\n`frame` (the pad and its buttons), `pad` (variants `size`, `interactive`, `disabled`, `hasError`), `ink` (the SVG of strokes), `image` (a value set from outside), `placeholder` (the signing line and hint), `actions` (the undo and clear buttons).\n\n## Exports\n\n`SignatureInput`, `SignatureInputProps`, `SignatureFormat`, `SignaturePoint`, `SignatureStroke`, `signatureInputTheme`, `setSignatureInputTheme`, `useSignatureInputTheme`, `SignatureInputTheme`, `SignatureInputThemeProps`.\n";
+export declare const signatureInputDescription = "\n# SignatureInput Component\n\nSignatureInput is a form field where a person signs with a mouse, a finger or a pen. Its value is the signature as an image: a data URL cropped to the ink (PNG by default, or SVG), ready to store, submit or place in a document.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n  import { SignatureInput } from './index.ts';\n\n  let signature = $state<string | null>(null);\n</script>\n\n<SignatureInput label=\"Signature\" required bind:value={signature} />\n```\n\nIn a Form or `ask()`, use `type: 'signature'`:\n\n```ts\nimport { ask } from 'entasis/ask';\n\nconst result = await ask({\n  title: 'Sign the mandate',\n  inputs: { signature: { type: 'signature', label: 'Signature', required: true } },\n  confirm: 'Sign',\n  cancel: 'Cancel'\n});\n```\n\n## Props\n\nExtends the shared Field props (`label`, `description`, `helper`, `required`, `disabled`, `readOnly`, `name`, `size`, `density`, `labelPosition`, `messages`, `onValidate`, `errors`, `focused`, `visible`) plus:\n\n- **value**: `string | null` (bindable) \u2014 the signature as a data URL, or `null` while the pad is empty.\n- **defaultValue**: `string | null` \u2014 initial value when `value` is omitted. Any image data URL works: a saved signature shows in the pad, scaled to fit.\n- **onValueChange**: `(value: string | null) => void` \u2014 called once per finished stroke, undo and clear.\n- **format**: `'png' | 'svg'` (default `'png'`) \u2014 the image the value holds. A PNG is drawn at twice the pad's resolution; an SVG keeps every stroke as a vector path.\n- **inkColor**: `string` (default `'#000000'`) \u2014 CSS color of the ink in the exported image, so a signature reads on a white document whatever the app's theme. The pad itself draws in the theme's text color.\n- **imageInk**: `'theme' | 'as-is'` (default `'theme'`) \u2014 how a value set from outside (a saved signature) shows in the pad. `'theme'` paints its shape in the pad's ink color, like live strokes (the image becomes a CSS mask over `bg-current`; only its transparency counts), so a black signature saved for paper reads on a dark theme without the app knowing which mode is on. `'as-is'` shows the image unchanged: for a signature with several colors or an opaque background. The value is never changed. A URL from another origin is fetched in CORS mode for the mask; when that origin refuses CORS, the pad falls back to the image as it is.\n- **strokeWidth**: `number` (default `2.5`) \u2014 line width in CSS pixels at a medium pen pressure. A pen's pressure makes the line thinner or thicker (half to one and a half times); a mouse or a finger draws at this width.\n- **placeholder**: `string` \u2014 hint on the signing line while the pad is empty. Defaults to the i18n `signatureInputPlaceholder` (\"Sign here\").\n- **clearLabel**, **undoLabel**: `string` \u2014 accessible labels and tooltips of the two buttons.\n- **i18n**: `Partial<Messages>` \u2014 per-instance translations.\n- **size**: `'small' | 'normal' | 'large'` \u2014 pad height (112, 144 or 176 px) and placeholder text size. Override the height with the `pad` theme part.\n- **theme**: `SignatureInputThemeProps` and Field theme parts.\n\n## Behaviour\n\n- Each stroke runs from pointer down to pointer up and is smoothed through its samples. The value updates when a stroke ends, not while it is drawn.\n- The undo button (or Ctrl/Cmd+Z on the pad) removes the last stroke; the clear button (or Delete/Backspace on the pad) empties the pad and sets the value to `null`. Both show only while the pad is editable and has a signature.\n- A value set from outside (a saved signature, a Form reset) replaces the strokes and shows as an image. Drawing over it starts a new signature: the image is replaced, not added to. Undo only steps back through strokes drawn since.\n- `disabled` and `readOnly` stop drawing and hide the buttons; a read-only pad still shows, focuses, validates and submits its value. A stroke in progress is dropped when the pad becomes disabled or read-only.\n- Required: an empty pad (`null` or `''`) fails `required`.\n- Native forms: a hidden input (`FieldHiddenInputs`) submits the data URL under `name`.\n\n## Accessibility\n\n- The pad is the field's control: it is focusable, labelled by the field label (or \"Signature\" without one), and has `role=\"img\"` with a description of its state (\"No signature yet\u2026\" or \"Signed.\"). Errors and descriptions are linked by Field.\n- Drawing is a path-based gesture with no keyboard equivalent: signing by hand is the purpose of the field. Keyboard users can clear and undo with the buttons and keys above. When a keyboard-only path to consent is needed, pair the pad with another field (a typed full name, a consent checkbox).\n- The ink, placeholder and image are decorative (`aria-hidden`, empty `alt`).\n\n## Styling hooks\n\n- `data-slot`: `signature-frame`, `signature-pad`, `signature-ink`, `signature-image`, `signature-placeholder`, `signature-actions`.\n- On the pad: `data-filled=\"true\"` while it holds a signature, `data-drawing=\"true\"` during a stroke.\n\n## Theme parts\n\n`frame` (the pad and its buttons), `pad` (variants `size`, `interactive`, `disabled`, `hasError`), `ink` (the SVG of strokes), `image` (a value set from outside), `placeholder` (the signing line and hint), `actions` (the undo and clear buttons).\n\n## Exports\n\n`SignatureInput`, `SignatureInputProps`, `SignatureFormat`, `SignaturePoint`, `SignatureStroke`, `signatureInputTheme`, `setSignatureInputTheme`, `useSignatureInputTheme`, `SignatureInputTheme`, `SignatureInputThemeProps`.\n";

package/dist/components/Form/SignatureInput/signatureInput.mcp.js

@@ -37,6 +37,7 @@ Extends the shared Field props (\`label\`, \`description\`, \`helper\`, \`requir
 - **onValueChange**: \`(value: string | null) => void\` — called once per finished stroke, undo and clear.
 - **format**: \`'png' | 'svg'\` (default \`'png'\`) — the image the value holds. A PNG is drawn at twice the pad's resolution; an SVG keeps every stroke as a vector path.
 - **inkColor**: \`string\` (default \`'#000000'\`) — CSS color of the ink in the exported image, so a signature reads on a white document whatever the app's theme. The pad itself draws in the theme's text color.
+- **imageInk**: \`'theme' | 'as-is'\` (default \`'theme'\`) — how a value set from outside (a saved signature) shows in the pad. \`'theme'\` paints its shape in the pad's ink color, like live strokes (the image becomes a CSS mask over \`bg-current\`; only its transparency counts), so a black signature saved for paper reads on a dark theme without the app knowing which mode is on. \`'as-is'\` shows the image unchanged: for a signature with several colors or an opaque background. The value is never changed. A URL from another origin is fetched in CORS mode for the mask; when that origin refuses CORS, the pad falls back to the image as it is.
 - **strokeWidth**: \`number\` (default \`2.5\`) — line width in CSS pixels at a medium pen pressure. A pen's pressure makes the line thinner or thicker (half to one and a half times); a mouse or a finger draws at this width.
 - **placeholder**: \`string\` — hint on the signing line while the pad is empty. Defaults to the i18n \`signatureInputPlaceholder\` ("Sign here").
 - **clearLabel**, **undoLabel**: \`string\` — accessible labels and tooltips of the two buttons.

package/dist/components/Form/SignatureInput/signatureInput.props.d.ts

@@ -3,6 +3,7 @@ import type { WithAttachments } from '../../../types/props.js';
 import type { InputProps } from '../Field/field.js';
 import type { SignatureFormat } from './signatureInput.strokes.js';
 import type { SignatureInputThemeProps } from './signatureInput.theme.js';
+export type SignatureImageInk = 'theme' | 'as-is';
 export type SignatureInputProps = WithAttachments<Omit<InputProps<'signature'>, 'theme'> & {
     /**
      * Image the value holds, as a data URL cropped to the ink: `'png'` (default, drawn at twice
@@ -14,6 +15,14 @@ export type SignatureInputProps = WithAttachments<Omit<InputProps<'signature'>,
      * white document whatever the app's theme; the pad itself draws in the theme's text color.
      */
     inkColor?: string;
+    /**
+     * How a value set from outside (a saved signature) shows in the pad. `'theme'` (default)
+     * paints its shape in the pad's ink color, as live strokes are, so a black signature saved
+     * for paper still reads on a dark theme; only its transparency counts. `'as-is'` shows the
+     * image unchanged: for a signature with several colors or an opaque background. The value
+     * itself is never changed.
+     */
+    imageInk?: SignatureImageInk;
     /** Line width in CSS pixels at a medium pen pressure. Defaults to 2.5. */
     strokeWidth?: number;
     /** Hint on the signing line while the pad is empty. Defaults to the i18n `signatureInputPlaceholder`. */

package/dist/components/Form/SignatureInput/signatureInput.theme.d.ts

@@ -21,7 +21,12 @@ export declare const signatureInputTheme: {
         };
     }> & import("../../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
     ink: (props?: import("../../../utils/cva/types.ts").CVAClassProp | undefined) => string;
-    image: (props?: import("../../../utils/cva/types.ts").CVAClassProp | undefined) => string;
+    image: (props?: (import("../../../utils/cva/types.ts").CVAVariantSchema<{
+        ink: {
+            theme: string;
+            'as-is': string;
+        };
+    }> & import("../../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
     placeholder: (props?: (import("../../../utils/cva/types.ts").CVAVariantSchema<{
         size: {
             small: string;
@@ -55,7 +60,12 @@ export declare const setSignatureInputTheme: (theme: InferComponentTheme<{
         };
     }> & import("../../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
     ink: (props?: import("../../../utils/cva/types.ts").CVAClassProp | undefined) => string;
-    image: (props?: import("../../../utils/cva/types.ts").CVAClassProp | undefined) => string;
+    image: (props?: (import("../../../utils/cva/types.ts").CVAVariantSchema<{
+        ink: {
+            theme: string;
+            'as-is': string;
+        };
+    }> & import("../../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
     placeholder: (props?: (import("../../../utils/cva/types.ts").CVAVariantSchema<{
         size: {
             small: string;
@@ -87,7 +97,12 @@ export declare const useSignatureInputTheme: import("../../../utils/cva/theme.ts
         };
     }> & import("../../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
     ink: (props?: import("../../../utils/cva/types.ts").CVAClassProp | undefined) => string;
-    image: (props?: import("../../../utils/cva/types.ts").CVAClassProp | undefined) => string;
+    image: (props?: (import("../../../utils/cva/types.ts").CVAVariantSchema<{
+        ink: {
+            theme: string;
+            'as-is': string;
+        };
+    }> & import("../../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
     placeholder: (props?: (import("../../../utils/cva/types.ts").CVAVariantSchema<{
         size: {
             small: string;

package/dist/components/Form/SignatureInput/signatureInput.theme.js

@@ -37,9 +37,20 @@ const defaultPad = cva({
 const defaultInk = cva({
     base: 'pointer-events-none absolute inset-0 size-full overflow-visible'
 });
-// A value set from outside (a saved signature) shows as an image, scaled to fit the pad.
+// A value set from outside (a saved signature) shows scaled to fit the pad. With `imageInk`
+// 'theme' it is a mask over the pad's ink color (`bg-current`), so a black signature saved for
+// paper reads on a dark surface; 'as-is' is the image itself.
 const defaultImage = cva({
-    base: 'pointer-events-none absolute inset-0 size-full object-contain p-md'
+    base: 'pointer-events-none absolute inset-0 size-full p-md',
+    variants: {
+        ink: {
+            theme: 'bg-current [mask-clip:content-box] [mask-origin:content-box] [mask-position:center] [mask-repeat:no-repeat] [mask-size:contain]',
+            'as-is': 'object-contain'
+        }
+    },
+    defaultVariants: {
+        ink: 'theme'
+    }
 });
 // The line to sign on and its hint: decorative, gone as soon as there is ink.
 const defaultPlaceholder = cva({

package/dist/components/Sidebar/Sidebar.svelte

@@ -266,7 +266,7 @@
 	});
 
 	function hasIcon(entry: SidebarMenuEntry) {
-		return entry.icon != null;
+		return entry.icon != null || entry.media != null;
 	}
 
 	function hasCollapsibleMedia(button: SidebarMenuButtonItem | undefined) {

package/dist/components/Sidebar/SidebarMenuItem.svelte

@@ -28,6 +28,7 @@
 	import SidebarFlyout from './SidebarFlyout.svelte';
 	import SidebarIcon from './SidebarIcon.svelte';
 	import SidebarMenuSubItem from './SidebarMenuSubItem.svelte';
+	import SidebarMenuText from './SidebarMenuText.svelte';
 	import { useSidebarSuffixWidth } from './sidebar.suffix.svelte.js';
 	import { useSidebarMotion, useSidebarTheme, type SidebarThemeProps } from './sidebar.theme.js';
 
@@ -82,6 +83,13 @@
 	);
 	const hasSubmenu = $derived(!!item.items?.length);
 	const showBadge = $derived(item.badge != null && !isIconCollapsed);
+	// A description stacks a second line under the label, so the row takes the large height
+	// unless the entry sets its own size.
+	const rowSize = $derived(item.size ?? (item.description != null ? 'large' : undefined));
+	const lead = $derived(item.media ? 'media' : 'icon');
+	// On a two-line row the suffix and the badge sit on the description's line, so the label's
+	// line, and its meta, run to the same end on every row.
+	const twoLine = $derived(item.description != null);
 	// An in-flow chevron or dots after the badge: the row then keeps its action's room at every
 	// width, since the action would otherwise cover that glyph when it shows.
 	const hasTrailingGlyph = $derived(
@@ -94,8 +102,12 @@
 	const endReserve = $derived(
 		item.suffix
 			? item.action
-				? 'suffixAction'
-				: 'suffix'
+				? twoLine
+					? 'suffixLineAction'
+					: 'suffixAction'
+				: twoLine
+					? 'suffixLine'
+					: 'suffix'
 			: !item.action
 				? 'none'
 				: showBadge && !hasTrailingGlyph
@@ -176,7 +188,11 @@
 </script>
 
 {#snippet entryContent()}
-	{#if hasIconSurface}
+	{#if item.media}
+		<span data-slot="sidebar-menu-media" data-sidebar="menu-media" class={classes.menuMedia()}>
+			{@render item.media(api, item)}
+		</span>
+	{:else if hasIconSurface}
 		<span
 			data-slot="sidebar-menu-icon"
 			data-color={item.iconColor}
@@ -187,7 +203,25 @@
 	{:else}
 		<SidebarIcon icon={item.icon} class={back ? 'rtl:-scale-x-100' : undefined} />
 	{/if}
-	<span class={classes.menuLabel()}>{item.label}</span>
+	{#if item.description != null || item.meta != null}
+		<SidebarMenuText
+			label={item.label}
+			description={item.description}
+			meta={isIconCollapsed ? undefined : item.meta}
+			suffix={!!item.suffix}
+			trailing={twoLine ? badge : undefined}
+			{size}
+			{theme}
+		/>
+	{:else}
+		<span class={classes.menuLabel()}>{item.label}</span>
+	{/if}
+	{#if !twoLine}
+		{@render badge()}
+	{/if}
+{/snippet}
+
+{#snippet badge()}
 	{#if showBadge}
 		<span
 			data-slot="sidebar-menu-badge"
@@ -224,7 +258,7 @@
 			role={item.disabled ? 'link' : undefined}
 			data-slot="sidebar-menu-button"
 			data-sidebar="menu-button"
-			data-size={item.size ?? 'normal'}
+			data-size={rowSize ?? 'normal'}
 			data-active={item.isActive ? 'true' : undefined}
 			data-active-variant={activeVariant}
 			aria-current={item.isActive ? 'page' : undefined}
@@ -236,7 +270,8 @@
 				activeVariant,
 				size,
 				density,
-				itemSize: item.size,
+				itemSize: rowSize,
+				lead,
 				endReserve,
 				className: item.class
 			})}
@@ -254,7 +289,7 @@
 			type="button"
 			data-slot="sidebar-menu-button"
 			data-sidebar="menu-button"
-			data-size={item.size ?? 'normal'}
+			data-size={rowSize ?? 'normal'}
 			data-active={item.isActive ? 'true' : undefined}
 			data-active-variant={activeVariant}
 			aria-current={item.isActive ? 'page' : undefined}
@@ -267,7 +302,8 @@
 				activeVariant,
 				size,
 				density,
-				itemSize: item.size,
+				itemSize: rowSize,
+				lead,
 				endReserve,
 				className: item.class
 			})}
@@ -302,7 +338,7 @@
 				type="button"
 				data-slot="sidebar-menu-button"
 				data-sidebar="menu-button"
-				data-size={item.size ?? 'normal'}
+				data-size={rowSize ?? 'normal'}
 				data-active-variant={activeVariant}
 				disabled={item.disabled || undefined}
 				class={classes.menuButton({
@@ -310,7 +346,8 @@
 					activeVariant,
 					size,
 					density,
-					itemSize: item.size,
+					itemSize: rowSize,
+					lead,
 					endReserve,
 					className: ['aria-expanded:bg-neutral-muted', item.class]
 				})}
@@ -339,7 +376,7 @@
 				type="button"
 				data-slot="sidebar-menu-button"
 				data-sidebar="menu-button"
-				data-size={item.size ?? 'normal'}
+				data-size={rowSize ?? 'normal'}
 				data-active={item.isActive ? 'true' : undefined}
 				data-active-variant={activeVariant}
 				class={classes.menuButton({
@@ -347,7 +384,8 @@
 					activeVariant,
 					size,
 					density,
-					itemSize: item.size,
+					itemSize: rowSize,
+					lead,
 					endReserve,
 					className: item.class
 				})}
@@ -434,7 +472,7 @@
 					type="button"
 					data-slot="sidebar-menu-button"
 					data-sidebar="menu-button"
-					data-size={item.size ?? 'normal'}
+					data-size={rowSize ?? 'normal'}
 					data-active={item.isActive ? 'true' : undefined}
 					data-active-variant={activeVariant}
 					disabled={item.disabled || undefined}
@@ -443,7 +481,8 @@
 						activeVariant,
 						size,
 						density,
-						itemSize: item.size,
+						itemSize: rowSize,
+						lead,
 						endReserve,
 						className: item.class
 					})}
@@ -473,7 +512,12 @@
 				data-sidebar="menu-suffix"
 				inert={isIconCollapsed ? true : undefined}
 				aria-hidden={isIconCollapsed ? 'true' : undefined}
-				class={classes.suffix({ size, density, action: item.action ? 'action' : 'none' })}
+				class={classes.suffix({
+					size,
+					density,
+					action: item.action ? 'action' : 'none',
+					line: twoLine ? 'two' : 'one'
+				})}
 				{@attach suffixWidth.measure}
 			>
 				{@render item.suffix(api, item)}

package/dist/components/Sidebar/SidebarMenuSubItem.svelte

@@ -11,6 +11,7 @@
 	import { sidebarInwardPhysicalSide, sidebarTooltip } from './sidebar-position.js';
 	import SidebarAction from './SidebarAction.svelte';
 	import SidebarIcon from './SidebarIcon.svelte';
+	import SidebarMenuText from './SidebarMenuText.svelte';
 	import { useSidebarSuffixWidth } from './sidebar.suffix.svelte.js';
 	import { useSidebarTheme, type SidebarThemeProps } from './sidebar.theme.js';
 
@@ -39,6 +40,9 @@
 	// tile, so an untinted row never inherits the ambient `data-color`.
 	const hasIconSurface = $derived(!!sub.icon && (sub.iconVariant === 'tile' || !!sub.iconColor));
 	const hasBadge = $derived(sub.badge != null);
+	// On a two-line row the suffix and the badge sit on the description's line, so the label's
+	// line, and its meta, run to the same end on every row.
+	const twoLine = $derived(sub.description != null);
 	const suffixWidth = useSidebarSuffixWidth();
 	const uid = $props.id();
 	const suffixId = `${uid}-suffix`;
@@ -63,13 +67,18 @@
 			// stays visible before the action, so a row with one reserves both at every width.
 			endReserve: sub.suffix
 				? sub.action
-					? 'suffixAction'
-					: 'suffix'
+					? twoLine
+						? 'suffixLineAction'
+						: 'suffixAction'
+					: twoLine
+						? 'suffixLine'
+						: 'suffix'
 				: !sub.action
 					? 'none'
 					: hasBadge
 						? 'actionBelowMd'
 						: 'action',
+			tall: sub.description != null || sub.media != null,
 			className: sub.class
 		})
 	);
@@ -85,7 +94,11 @@
 </script>
 
 {#snippet entryContent()}
-	{#if hasIconSurface}
+	{#if sub.media}
+		<span data-slot="sidebar-menu-media" data-sidebar="menu-media" class={classes.menuMedia()}>
+			{@render sub.media(api, sub)}
+		</span>
+	{:else if hasIconSurface}
 		<span
 			data-slot="sidebar-menu-icon"
 			data-color={sub.iconColor}
@@ -100,20 +113,37 @@
 	{:else}
 		<SidebarIcon icon={sub.icon} />
 	{/if}
-	{#if hasBadge}
+	{#if sub.description != null || sub.meta != null}
+		<SidebarMenuText
+			label={sub.label}
+			description={sub.description}
+			meta={sub.meta}
+			suffix={!!sub.suffix}
+			trailing={twoLine && hasBadge ? badge : undefined}
+			size={subSize}
+			{theme}
+		/>
+		{#if !twoLine && hasBadge}
+			{@render badge()}
+		{/if}
+	{:else if hasBadge}
 		<span data-slot="sidebar-menu-sub-label">{sub.label}</span>
-		<span
-			data-slot="sidebar-menu-sub-badge"
-			data-sidebar="menu-sub-badge"
-			class={classes.badge({ size: subSize, action: sub.action && !sub.suffix ? 'sub' : 'none' })}
-		>
-			{sub.badge}
-		</span>
+		{@render badge()}
 	{:else}
 		<span>{sub.label}</span>
 	{/if}
 {/snippet}
 
+{#snippet badge()}
+	<span
+		data-slot="sidebar-menu-sub-badge"
+		data-sidebar="menu-sub-badge"
+		class={classes.badge({ size: subSize, action: sub.action && !sub.suffix ? 'sub' : 'none' })}
+	>
+		{sub.badge}
+	</span>
+{/snippet}
+
 <li
 	bind:this={itemRef}
 	data-slot="sidebar-menu-sub-item"
@@ -175,7 +205,8 @@
 			class={classes.suffix({
 				size: subSize,
 				density,
-				action: sub.action ? 'action' : 'none'
+				action: sub.action ? 'action' : 'none',
+				line: twoLine ? 'two' : 'one'
 			})}
 			{@attach suffixWidth.measure}
 		>

package/dist/components/Sidebar/SidebarMenuText.svelte

@@ -0,0 +1,60 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { SidebarSize } from './sidebar.props.js';
+	import { useSidebarTheme, type SidebarThemeProps } from './sidebar.theme.js';
+
+	let {
+		label,
+		description,
+		meta,
+		size,
+		suffix = false,
+		trailing,
+		theme
+	}: {
+		label: string;
+		description?: string | Snippet;
+		/** Left out while the Sidebar is collapsed to icons. */
+		meta?: string | Snippet;
+		size: SidebarSize;
+		/** The row has a suffix, centred on the description's line. */
+		suffix?: boolean;
+		/** End of the description's line: the row's badge. */
+		trailing?: Snippet;
+		theme?: SidebarThemeProps;
+	} = $props();
+
+	const classes = $derived(useSidebarTheme(theme));
+</script>
+
+{#snippet text(content: string | Snippet)}
+	{#if typeof content === 'string'}{content}{:else}{@render content()}{/if}
+{/snippet}
+
+<!-- The label's line (the label, then the meta at its end) over the description's line. -->
+<span data-slot="sidebar-menu-text" class={classes.menuText()}>
+	<span class={classes.menuTitleRow()}>
+		<span data-slot="sidebar-menu-label" class={classes.menuTitle()}>{label}</span>
+		{#if meta != null}
+			<span
+				data-slot="sidebar-menu-meta"
+				data-sidebar="menu-meta"
+				class={classes.menuMeta({ size })}
+			>
+				{@render text(meta)}
+			</span>
+		{/if}
+	</span>
+	{#if description != null}
+		<span class={classes.menuDescriptionRow({ suffix })}>
+			<span
+				data-slot="sidebar-menu-description"
+				data-sidebar="menu-description"
+				class={classes.menuSecondary({ size })}
+			>
+				{@render text(description)}
+			</span>
+			{@render trailing?.()}
+		</span>
+	{/if}
+</span>

package/dist/components/Sidebar/SidebarMenuText.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { Snippet } from 'svelte';
+import type { SidebarSize } from './sidebar.props.js';
+import { type SidebarThemeProps } from './sidebar.theme.js';
+type $$ComponentProps = {
+    label: string;
+    description?: string | Snippet;
+    /** Left out while the Sidebar is collapsed to icons. */
+    meta?: string | Snippet;
+    size: SidebarSize;
+    /** The row has a suffix, centred on the description's line. */
+    suffix?: boolean;
+    /** End of the description's line: the row's badge. */
+    trailing?: Snippet;
+    theme?: SidebarThemeProps;
+};
+declare const SidebarMenuText: import("svelte").Component<$$ComponentProps, {}, "">;
+type SidebarMenuText = ReturnType<typeof SidebarMenuText>;
+export default SidebarMenuText;