entasis 0.11.0 → 0.12.0

package/dist/components/ProgressCircle/ProgressCircle.svelte

@@ -3,6 +3,8 @@
 	import { useProgressCircleTheme } from './progressCircle.theme.js';
 	import { useDefaultColor } from '../Theme/theme.state.svelte.js';
 	import { useI18n } from '../../i18n/context.svelte.js';
+	import { clampRange, rangeAriaAttributes, resolveRangeValue } from '../../utils/range.js';
+	import { presence } from '../../utils/stateAttributes.js';
 
 	let {
 		ref = $bindable(),
@@ -11,6 +13,11 @@
 		size = 'normal',
 		diameter,
 		value = 0,
+		min = 0,
+		max = 100,
+		format,
+		getAriaValueText,
+		locale: localeProp,
 		label,
 		decorative = false,
 		theme,
@@ -25,8 +32,32 @@
 			? `${Number.isFinite(diameter) ? Math.max(diameter, 1) : 28}px`
 			: undefined
 	);
-	const progressValue = $derived(Number.isFinite(value) ? Math.min(100, Math.max(0, value)) : 0);
-	const indicatorOffset = $derived(100 - progressValue);
+	const locale = $derived(localeProp ?? t.locale);
+
+	// `null` (or a non-finite number) is indeterminate. Otherwise the value is clamped into
+	// [min, max] and the arc, the ARIA values and the text all follow that one clamped value.
+	const rangeOptions = $derived({
+		value,
+		min,
+		max,
+		format,
+		locale,
+		indeterminateText: t.progressIndeterminate,
+		getAriaValueText:
+			getAriaValueText &&
+			((formattedValue: string, rawValue: number | null) =>
+				getAriaValueText({
+					value: rawValue === null ? null : clampRange(rawValue, min, max),
+					formattedValue,
+					min,
+					max
+				}))
+	});
+	const range = $derived(resolveRangeValue(rangeOptions));
+	const aria = $derived(rangeAriaAttributes(rangeOptions));
+	const indeterminate = $derived(range.status === 'indeterminate');
+	// An indeterminate arc is a quarter turn that spins.
+	const indicatorOffset = $derived(100 - (range.percent ?? 25));
 </script>
 
 <span
@@ -37,14 +68,28 @@
 	role={decorative ? undefined : 'progressbar'}
 	aria-hidden={decorative ? 'true' : undefined}
 	aria-label={decorative ? undefined : (label ?? t.progress)}
-	aria-valuemin={decorative ? undefined : 0}
-	aria-valuemax={decorative ? undefined : 100}
-	aria-valuenow={decorative ? undefined : progressValue}
+	aria-valuemin={decorative ? undefined : aria['aria-valuemin']}
+	aria-valuemax={decorative ? undefined : aria['aria-valuemax']}
+	aria-valuenow={decorative ? undefined : aria['aria-valuenow']}
+	aria-valuetext={decorative ? undefined : aria['aria-valuetext']}
+	data-indeterminate={presence(indeterminate)}
+	data-progressing={presence(range.status === 'progressing')}
+	data-complete={presence(range.status === 'complete')}
 	class={classes.root({ size, color: resolvedColor, className })}
 	style:--progress-circle-size={pixelDiameter}
 	{...attachments}
 >
-	<svg data-slot="progress-circle-svg" viewBox="0 0 32 32" aria-hidden="true" class={classes.svg()}>
+	{#if !decorative}
+		<!-- NVDA ignores the name of a progressbar with no text content (nvaccess/nvda#13904), so
+		     the value text sits inside it. role="presentation" keeps it out of the tree. -->
+		<span role="presentation" class="sr-only">{aria['aria-valuetext'] ?? range.formatted}</span>
+	{/if}
+	<svg
+		data-slot="progress-circle-svg"
+		viewBox="0 0 32 32"
+		aria-hidden="true"
+		class={classes.svg({ indeterminate })}
+	>
 		<circle
 			data-slot="progress-circle-track"
 			cx="16"

package/dist/components/ProgressCircle/progressCircle.mcp.d.ts

@@ -1 +1 @@
-export declare const progressCircleDescription = "\n# ProgressCircle Component\n\nProgressCircle is a compact determinate circular progress indicator with a visible track and an arc that animates when the value changes.\n\n## Basic Usage\n\n```svelte\n<ProgressCircle />\n```\n\n## Props\n\n- **value**: number (default: 0)\n  - Progress value from 0 to 100. Values outside the range are clamped.\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n  - Selects semantic component geometry.\n- **diameter**: number\n  - Optional explicit circle diameter in pixels.\n- **color**: 'primary' | 'secondary' | 'danger' | 'success' | 'warning' | 'info' | 'neutral' (default: 'primary')\n  - Applies a theme color token to the animated arc.\n- **label**: string (default: 'Progress')\n  - Accessible label used when the component is not decorative.\n- **decorative**: boolean (default: false)\n  - Removes progress semantics and hides the element from assistive technology.\n- **class**: string\n  - Additional classes for the root element.\n- **theme**: ProgressCircleThemeProps\n  - Per-instance theme overrides.\n\n## Examples\n\n```svelte\n<ProgressCircle size=\"small\" />\n<ProgressCircle value={45} color=\"danger\" />\n<ProgressCircle value={72} diameter={56} color=\"success\" />\n```\n\n## Accessibility\n\n- The component renders `role=\"progressbar\"` with `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` by default.\n- Use `label` to provide a specific accessible name.\n- Use `decorative` when nearby UI already announces the loading state.\n\n## Theme Parts\n\n- **root**: inline wrapper and color/size token host\n- **svg**: animated SVG element\n- **track**: background circle\n- **indicator**: active arc\n";
+export declare const progressCircleDescription = "\n# ProgressCircle Component\n\nProgressCircle is a compact circular progress indicator with a visible track and an arc that animates when the value changes. A null value makes it indeterminate: the arc spins.\n\n## Basic Usage\n\n```svelte\n<ProgressCircle />\n```\n\n## Props\n\n- **value**: number | null (default: 0)\n  - Progress between min and max. Values outside the range are clamped. null is indeterminate: aria-valuenow is dropped, data-indeterminate is set and the arc spins.\n- **min**: number (default: 0)\n  - Value at which the arc is empty (aria-valuemin).\n- **max**: number (default: 100)\n  - Value at which the arc is full (aria-valuemax). data-complete is set once the clamped value reaches it.\n- **format**: Intl.NumberFormatOptions\n  - Formats the clamped value for the value text (for example { style: 'unit', unit: 'megabyte' }). Without it the text is the percentage of the range.\n- **getAriaValueText**: (payload: { value, formattedValue, min, max }) => string\n  - Overrides aria-valuetext. value is null while indeterminate.\n- **locale**: Intl.LocalesArgument\n  - Locale of the value text (default: the I18n locale).\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n  - Selects semantic component geometry.\n- **diameter**: number\n  - Optional explicit circle diameter in pixels.\n- **color**: 'primary' | 'secondary' | 'danger' | 'success' | 'warning' | 'info' | 'neutral' (default: 'primary')\n  - Applies a theme color token to the animated arc.\n- **label**: string (default: 'Progress')\n  - Accessible label used when the component is not decorative.\n- **decorative**: boolean (default: false)\n  - Removes progress semantics and hides the element from assistive technology.\n- **class**: string\n  - Additional classes for the root element.\n- **theme**: ProgressCircleThemeProps\n  - Per-instance theme overrides.\n\n## Examples\n\n```svelte\n<ProgressCircle size=\"small\" />\n<ProgressCircle value={45} color=\"danger\" />\n<ProgressCircle value={72} diameter={56} color=\"success\" />\n<ProgressCircle value={null} label=\"Loading\" />\n<ProgressCircle value={30} min={20} max={40} label=\"Temperature\" />\n```\n\n## Accessibility\n\n- The component renders `role=\"progressbar\"` with `aria-valuenow` (the clamped value), `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` (the formatted value, for example \"45%\") by default. While indeterminate, aria-valuenow is omitted and the value text is \"Indeterminate progress\" (i18n progressIndeterminate).\n- A visually hidden presentational text node inside the root carries the value text, because NVDA ignores the name of a progressbar with no text content.\n- Styling hooks: data-indeterminate, data-progressing and data-complete on the root.\n- Use `label` to provide a specific accessible name.\n- Use `decorative` when nearby UI already announces the loading state.\n\n## Theme Parts\n\n- **root**: inline wrapper and color/size token host\n- **svg**: animated SVG element\n- **track**: background circle\n- **indicator**: active arc\n";

package/dist/components/ProgressCircle/progressCircle.mcp.js

@@ -1,7 +1,7 @@
 export const progressCircleDescription = `
 # ProgressCircle Component
 
-ProgressCircle is a compact determinate circular progress indicator with a visible track and an arc that animates when the value changes.
+ProgressCircle is a compact circular progress indicator with a visible track and an arc that animates when the value changes. A null value makes it indeterminate: the arc spins.
 
 ## Basic Usage
 
@@ -11,8 +11,18 @@ ProgressCircle is a compact determinate circular progress indicator with a visib
 
 ## Props
 
-- **value**: number (default: 0)
-  - Progress value from 0 to 100. Values outside the range are clamped.
+- **value**: number | null (default: 0)
+  - Progress between min and max. Values outside the range are clamped. null is indeterminate: aria-valuenow is dropped, data-indeterminate is set and the arc spins.
+- **min**: number (default: 0)
+  - Value at which the arc is empty (aria-valuemin).
+- **max**: number (default: 100)
+  - Value at which the arc is full (aria-valuemax). data-complete is set once the clamped value reaches it.
+- **format**: Intl.NumberFormatOptions
+  - Formats the clamped value for the value text (for example { style: 'unit', unit: 'megabyte' }). Without it the text is the percentage of the range.
+- **getAriaValueText**: (payload: { value, formattedValue, min, max }) => string
+  - Overrides aria-valuetext. value is null while indeterminate.
+- **locale**: Intl.LocalesArgument
+  - Locale of the value text (default: the I18n locale).
 - **size**: 'small' | 'normal' | 'large' (default: 'normal')
   - Selects semantic component geometry.
 - **diameter**: number
@@ -34,11 +44,15 @@ ProgressCircle is a compact determinate circular progress indicator with a visib
 <ProgressCircle size="small" />
 <ProgressCircle value={45} color="danger" />
 <ProgressCircle value={72} diameter={56} color="success" />
+<ProgressCircle value={null} label="Loading" />
+<ProgressCircle value={30} min={20} max={40} label="Temperature" />
 \`\`\`
 
 ## Accessibility
 
-- The component renders \`role="progressbar"\` with \`aria-valuenow\`, \`aria-valuemin\`, and \`aria-valuemax\` by default.
+- The component renders \`role="progressbar"\` with \`aria-valuenow\` (the clamped value), \`aria-valuemin\`, \`aria-valuemax\`, and \`aria-valuetext\` (the formatted value, for example "45%") by default. While indeterminate, aria-valuenow is omitted and the value text is "Indeterminate progress" (i18n progressIndeterminate).
+- A visually hidden presentational text node inside the root carries the value text, because NVDA ignores the name of a progressbar with no text content.
+- Styling hooks: data-indeterminate, data-progressing and data-complete on the root.
 - Use \`label\` to provide a specific accessible name.
 - Use \`decorative\` when nearby UI already announces the loading state.
 

package/dist/components/ProgressCircle/progressCircle.props.d.ts

@@ -14,11 +14,41 @@ type ProgressCircleBaseProps = {
     /** Explicit circle diameter in pixels, overriding the semantic size. */
     diameter?: number;
     /**
-     * Progress value from 0 to 100.
+     * Progress between `min` and `max`; it is clamped into that range. `null` is indeterminate:
+     * `aria-valuenow` is dropped, `data-indeterminate` is set and the arc spins. `data-complete`
+     * is set once the clamped value reaches `max`.
      *
      * @readonly-value ProgressCircle draws reported progress it never edits.
+     * @default 0
      */
-    value?: number;
+    value?: number | null;
+    /**
+     * Value at which the arc is empty, reported as `aria-valuemin`.
+     * @default 0
+     */
+    min?: number;
+    /**
+     * Value at which the arc is full, reported as `aria-valuemax`.
+     * @default 100
+     */
+    max?: number;
+    /**
+     * `Intl.NumberFormat` options for the value text (`{ style: 'unit', unit: 'megabyte' }`),
+     * applied to the clamped value. Without it, the text is the percentage of the range.
+     */
+    format?: Intl.NumberFormatOptions;
+    /**
+     * Overrides `aria-valuetext`. Receives the clamped value (`null` while indeterminate), its
+     * formatted text and the range bounds.
+     */
+    getAriaValueText?: (payload: {
+        value: number | null;
+        formattedValue: string;
+        min: number;
+        max: number;
+    }) => string;
+    /** Locale of the value text. Defaults to the I18n locale. */
+    locale?: Intl.LocalesArgument;
     /** Accessible label used when the progress circle is not decorative. */
     label?: string;
     /** Removes progress semantics when the circle is purely decorative. */

package/dist/components/ProgressCircle/progressCircle.theme.d.ts

@@ -16,7 +16,11 @@ export declare const progressCircleTheme: {
             neutral: string;
         };
     }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
-    svg: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
+    svg: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
+        indeterminate: {
+            true: string;
+        };
+    }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
     track: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
     indicator: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
 };
@@ -39,7 +43,11 @@ export declare const setProgressCircleTheme: (theme: InferComponentTheme<{
             neutral: string;
         };
     }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
-    svg: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
+    svg: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
+        indeterminate: {
+            true: string;
+        };
+    }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
     track: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
     indicator: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
 }>) => void;
@@ -60,7 +68,11 @@ export declare const useProgressCircleTheme: import("../../utils/cva/theme.js").
             neutral: string;
         };
     }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
-    svg: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
+    svg: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
+        indeterminate: {
+            true: string;
+        };
+    }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
     track: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
     indicator: (props?: import("../../utils/cva/types.js").CVAClassProp | undefined) => string;
 }>;

package/dist/components/ProgressCircle/progressCircle.theme.js

@@ -2,7 +2,7 @@ import { cva, setComponentTheme, useComponentTheme } from '../../utils/cva/index
 // `--progress-circle-size` is INTERNAL: the root publishes the resolved diameter for the svg
 // and label parts. It follows the `size` prop, which is the public way to change it.
 const defaultProgressCircleRoot = cva({
-    base: 'inline-flex shrink-0 items-center justify-center align-middle [--progress-circle-size:1.75rem]',
+    base: 'relative inline-flex shrink-0 items-center justify-center align-middle [--progress-circle-size:1.75rem]',
     variants: {
         size: {
             small: '[--progress-circle-size:1.25rem]',
@@ -25,7 +25,12 @@ const defaultProgressCircleRoot = cva({
     }
 });
 const defaultProgressCircleSvg = cva({
-    base: 'size-[var(--progress-circle-size)] shrink-0 overflow-visible'
+    base: 'size-[var(--progress-circle-size)] shrink-0 overflow-visible',
+    variants: {
+        indeterminate: {
+            true: 'animate-spin motion-reduce:animate-none [html[data-entasis-reduce-motion]_&]:animate-none'
+        }
+    }
 });
 const defaultProgressCircleTrack = cva({
     base: 'stroke-neutral/20'

package/dist/components/RichTextInput/RichTextInput.svelte

@@ -24,6 +24,8 @@
 		required = false,
 		name,
 		onValidate,
+		validationMode,
+		validationDebounce,
 		visible,
 		triggers = {},
 		onSuggestionOpen,
@@ -38,6 +40,8 @@
 		maxHeight = false,
 		formats = AI_COMPOSER_DEFAULT_RICH_TEXT_FORMATS,
 		disabled = false,
+		readOnly,
+		messages,
 		placeholder,
 		size = 'normal',
 		toolbarClass,
@@ -92,9 +96,21 @@
 		set disabled(nextDisabled: boolean | undefined) {
 			disabled = nextDisabled ?? false;
 		},
+		get readOnly() {
+			return readOnly;
+		},
+		get messages() {
+			return messages;
+		},
 		get required() {
 			return required;
 		},
+		get validationMode() {
+			return validationMode;
+		},
+		get validationDebounce() {
+			return validationDebounce;
+		},
 		get name() {
 			return name;
 		},
@@ -147,8 +163,9 @@
 		get formats() {
 			return formats;
 		},
+		// A read-only editor stops editing and suggestions too; only its chrome stays enabled.
 		get disabled() {
-			return field.disabled ?? false;
+			return field.disabled || field.readOnly;
 		}
 	});
 
@@ -197,6 +214,7 @@
 		{formats}
 		{toolbarClass}
 		disabled={field.disabled ?? false}
+		readOnly={field.readOnly}
 		placeholder={placeholder ?? t.aiComposerPlaceholder}
 		{standalone}
 		{maxHeight}

package/dist/components/RichTextInput/RichTextInputChrome.svelte

@@ -31,6 +31,8 @@
 		formats: RichTextInputFormat[];
 		toolbarClass?: string;
 		disabled: boolean;
+		/** Focusable and selectable, but not editable; the formatting toolbar is hidden. */
+		readOnly?: boolean;
 		placeholder: string;
 		standalone?: boolean;
 		maxHeight?: RichTextInputMaxHeight;
@@ -66,6 +68,7 @@
 		formats,
 		toolbarClass,
 		disabled,
+		readOnly = false,
 		placeholder,
 		standalone = false,
 		maxHeight = false,
@@ -95,7 +98,7 @@
 	class={classes.root({ size, disabled, className })}
 	{...attachments}
 >
-	{#if showFixedToolbar}
+	{#if showFixedToolbar && !readOnly}
 		<div
 			data-slot="rich-text-input-toolbar"
 			class={classes.fixedToolbar({ size, standalone, class: toolbarClass })}
@@ -124,6 +127,7 @@
 		{size}
 		{theme}
 		{disabled}
+		{readOnly}
 		{placeholder}
 		{standalone}
 		{maxHeight}

package/dist/components/RichTextInput/RichTextInputChrome.svelte.d.ts

@@ -27,6 +27,8 @@ type Props = WithAttachments<{
     formats: RichTextInputFormat[];
     toolbarClass?: string;
     disabled: boolean;
+    /** Focusable and selectable, but not editable; the formatting toolbar is hidden. */
+    readOnly?: boolean;
     placeholder: string;
     standalone?: boolean;
     maxHeight?: RichTextInputMaxHeight;

package/dist/components/RichTextInput/RichTextInputViewport.svelte

@@ -14,6 +14,7 @@
 		size: Sizes;
 		theme?: RichTextInputThemeProps;
 		disabled?: boolean;
+		readOnly?: boolean;
 		placeholder: string;
 		standalone?: boolean;
 		maxHeight?: RichTextInputMaxHeight;
@@ -30,6 +31,7 @@
 		size,
 		theme,
 		disabled = false,
+		readOnly = false,
 		placeholder,
 		standalone = false,
 		maxHeight = false,
@@ -185,7 +187,7 @@
 				{@attach editorAttachment}
 				data-slot="ai-composer-editor"
 				data-rich-text-input-editor="true"
-				contenteditable={disabled ? 'false' : 'true'}
+				contenteditable={disabled || readOnly ? 'false' : 'true'}
 				role="textbox"
 				aria-label={placeholder}
 				aria-multiline="true"

package/dist/components/RichTextInput/RichTextInputViewport.svelte.d.ts

@@ -9,6 +9,7 @@ type Props = {
     size: Sizes;
     theme?: RichTextInputThemeProps;
     disabled?: boolean;
+    readOnly?: boolean;
     placeholder: string;
     standalone?: boolean;
     maxHeight?: RichTextInputMaxHeight;

package/dist/components/RichTextInput/richTextInput.mcp.d.ts

@@ -1 +1 @@
-export declare const richTextInputDescription = "\n# RichTextInput Component\n\nRichTextInput is a markdown rich text editor for AI-style composition. It supports inline and block formatting, trigger-based suggestions, token insertion, and a bindable markdown value.\n\n## Requires\n\nRichTextInput is built on Lexical. Those packages are optional peer dependencies of entasis, so install them alongside it:\n\n`pnpm add lexical @lexical/history @lexical/link @lexical/list @lexical/markdown @lexical/rich-text @lexical/selection @lexical/utils`\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\timport { RichTextInput, type RichTextInputTriggers } from 'entasis/rich-text-input';\n\n\tlet value = $state('');\n\n\tconst triggers: RichTextInputTriggers = {\n\t\t'/': {\n\t\t\ttitle: 'Commands',\n\t\t\ttokenKind: 'command',\n\t\t\titems: [{ id: 'summarize', label: '/summarize', kind: 'command' }]\n\t\t}\n\t};\n</script>\n\n<RichTextInput bind:value {triggers} toolbar=\"both\" />\n```\n\n## Standalone Usage\n\n```svelte\n<RichTextInput standalone toolbar=\"hover\" placeholder=\"Prompt...\" />\n```\n\n## Height\n\n```svelte\n<RichTextInput placeholder=\"Grows with content by default...\" />\n<RichTextInput maxHeight={320} placeholder=\"Capped at 320px...\" />\n```\n\n## Form Usage\n\n```svelte\n<Form\n\tinputs={{\n\t\tprompt: {\n\t\t\ttype: 'rich-text',\n\t\t\tlabel: 'Prompt',\n\t\t\tplaceholder: 'Write a prompt...',\n\t\t\ttoolbar: 'fixed'\n\t\t}\n\t}}\n/>\n```\n\n## Props\n\n### Value\n- **value**: string - Bindable markdown value.\n- **name**: string - Hidden input name for native form submission; Form supplies this from the field key.\n- **id**: string - Applied to the editable root.\n- **ref**: HTMLDivElement | null - Bindable editable root reference.\n- **label**, **description**, **helper**, **errors**, **required**, **onValidate** - Standard Field props.\n- **placeholder**: string (default: \"Ask anything...\") - Placeholder and textbox aria-label.\n- **disabled**: boolean (default: false) - Disables editing and suggestions.\n- **standalone**: boolean (default: false) - Renders only the rich text editor chrome without the Field wrapper or input surface.\n- **maxHeight**: number | string | false (default: false) - False lets the editor grow with content; a number/string caps the editor height.\n\n### Suggestions\n- **triggers**: RichTextInputTriggers - Trigger configuration keyed by characters such as '/', '@', or '$'.\n- **onSuggestionOpen**: (payload) => void - Called when a suggestion menu opens.\n- **onSuggestionClose**: (payload) => void - Called when a suggestion menu closes.\n- **onSuggestionQueryChange**: (payload) => void - Called when the active query changes.\n- **onSuggestionHighlightChange**: (payload) => void - Called when highlighted suggestion changes.\n\n### Formatting\n- **toolbar**: 'hover' | 'fixed' | 'both' | 'none' (default: 'hover') - 'hover' shows controls for selected text, 'fixed' pins controls above the editor, 'both' enables both, and 'none' hides formatting controls.\n- **formats**: RichTextInputFormat[] - Allowed formatting controls.\n- **toolbarClass**: string - Extra classes on the fixed toolbar wrapper.\n\n### Events and Methods\n- **onValueChange**: (payload: RichTextInputChange) => void - Receives markdown, tokens, and empty state.\n- **submitShortcut**: 'enter' | 'shift-enter' | 'command-enter' | 'none' - Shortcut that calls onSubmitShortcut.\n- **onSubmitShortcut**: (event: KeyboardEvent) => void - Submit shortcut callback.\n- **focus()**, **clear()**, **insertText(text)**, **insertItem(trigger, item)**, **insertToken(token)** are exported component methods.\n\n## Accessibility\n\n- The editable root uses role=\"textbox\" and aria-multiline.\n- Fixed and selected-text formatting controls use ToggleMenu toolbar semantics and roving focus.\n- Block styles use radio semantics, list controls toggle on and off, and command buttons do not expose pressed state.\n- The hover toolbar uses SelectionMenu's direct ToggleMenu pass-through for range containment, selection preservation, and Popover positioning.\n- Suggestion menus use the existing Command and Popover primitives.\n";
+export declare const richTextInputDescription = "\n# RichTextInput Component\n\nRichTextInput is a markdown rich text editor for AI-style composition. It supports inline and block formatting, trigger-based suggestions, token insertion, and a bindable markdown value.\n\n## Requires\n\nRichTextInput is built on Lexical. Those packages are optional peer dependencies of entasis, so install them alongside it:\n\n`pnpm add lexical @lexical/history @lexical/link @lexical/list @lexical/markdown @lexical/rich-text @lexical/selection @lexical/utils`\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\timport { RichTextInput, type RichTextInputTriggers } from 'entasis/rich-text-input';\n\n\tlet value = $state('');\n\n\tconst triggers: RichTextInputTriggers = {\n\t\t'/': {\n\t\t\ttitle: 'Commands',\n\t\t\ttokenKind: 'command',\n\t\t\titems: [{ id: 'summarize', label: '/summarize', kind: 'command' }]\n\t\t}\n\t};\n</script>\n\n<RichTextInput bind:value {triggers} toolbar=\"both\" />\n```\n\n## Standalone Usage\n\n```svelte\n<RichTextInput standalone toolbar=\"hover\" placeholder=\"Prompt...\" />\n```\n\n## Height\n\n```svelte\n<RichTextInput placeholder=\"Grows with content by default...\" />\n<RichTextInput maxHeight={320} placeholder=\"Capped at 320px...\" />\n```\n\n## Form Usage\n\n```svelte\n<Form\n\tinputs={{\n\t\tprompt: {\n\t\t\ttype: 'rich-text',\n\t\t\tlabel: 'Prompt',\n\t\t\tplaceholder: 'Write a prompt...',\n\t\t\ttoolbar: 'fixed'\n\t\t}\n\t}}\n/>\n```\n\n## Props\n\n### Value\n- **value**: string - Bindable markdown value.\n- **name**: string - Hidden input name for native form submission; Form supplies this from the field key.\n- **id**: string - Applied to the editable root.\n- **ref**: HTMLDivElement | null - Bindable editable root reference.\n- **label**, **description**, **helper**, **errors**, **required**, **onValidate** - Standard Field props.\n- **placeholder**: string (default: \"Ask anything...\") - Placeholder and textbox aria-label.\n- **disabled**: boolean (default: false) - Disables editing and suggestions.\n- **readOnly**: boolean (default: false) - The editor stays focusable and selectable but is not editable; the fixed toolbar is hidden and the value still submits.\n- **standalone**: boolean (default: false) - Renders only the rich text editor chrome without the Field wrapper or input surface.\n- **maxHeight**: number | string | false (default: false) - False lets the editor grow with content; a number/string caps the editor height.\n\n### Suggestions\n- **triggers**: RichTextInputTriggers - Trigger configuration keyed by characters such as '/', '@', or '$'.\n- **onSuggestionOpen**: (payload) => void - Called when a suggestion menu opens.\n- **onSuggestionClose**: (payload) => void - Called when a suggestion menu closes.\n- **onSuggestionQueryChange**: (payload) => void - Called when the active query changes.\n- **onSuggestionHighlightChange**: (payload) => void - Called when highlighted suggestion changes.\n\n### Formatting\n- **toolbar**: 'hover' | 'fixed' | 'both' | 'none' (default: 'hover') - 'hover' shows controls for selected text, 'fixed' pins controls above the editor, 'both' enables both, and 'none' hides formatting controls.\n- **formats**: RichTextInputFormat[] - Allowed formatting controls.\n- **toolbarClass**: string - Extra classes on the fixed toolbar wrapper.\n\n### Events and Methods\n- **onValueChange**: (payload: RichTextInputChange) => void - Receives markdown, tokens, and empty state.\n- **submitShortcut**: 'enter' | 'shift-enter' | 'command-enter' | 'none' - Shortcut that calls onSubmitShortcut.\n- **onSubmitShortcut**: (event: KeyboardEvent) => void - Submit shortcut callback.\n- **focus()**, **clear()**, **insertText(text)**, **insertItem(trigger, item)**, **insertToken(token)** are exported component methods.\n\n## Accessibility\n\n- The editable root uses role=\"textbox\" and aria-multiline.\n- Fixed and selected-text formatting controls use ToggleMenu toolbar semantics and roving focus.\n- Block styles use radio semantics, list controls toggle on and off, and command buttons do not expose pressed state.\n- The hover toolbar uses SelectionMenu's direct ToggleMenu pass-through for range containment, selection preservation, and Popover positioning.\n- Suggestion menus use the existing Command and Popover primitives.\n";

package/dist/components/RichTextInput/richTextInput.mcp.js

@@ -67,6 +67,7 @@ RichTextInput is built on Lexical. Those packages are optional peer dependencies
 - **label**, **description**, **helper**, **errors**, **required**, **onValidate** - Standard Field props.
 - **placeholder**: string (default: "Ask anything...") - Placeholder and textbox aria-label.
 - **disabled**: boolean (default: false) - Disables editing and suggestions.
+- **readOnly**: boolean (default: false) - The editor stays focusable and selectable but is not editable; the fixed toolbar is hidden and the value still submits.
 - **standalone**: boolean (default: false) - Renders only the rich text editor chrome without the Field wrapper or input surface.
 - **maxHeight**: number | string | false (default: false) - False lets the editor grow with content; a number/string caps the editor height.
 

package/dist/components/RichTextInput/suggestions.js

@@ -18,6 +18,8 @@ export function buildRichTextInputGroups(trigger, config, items, query, shouldFi
         groupItems.push({
             value: getSuggestionValue(trigger, item),
             label: item.label,
+            // A file or reference shows its path, the clearest way to tell two same-named files apart.
+            description: item.path ?? item.description,
             icon: item.icon,
             keywords: item.keywords
         });