entasis 0.13.4 → 0.13.6

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

@@ -0,0 +1,77 @@
+/**
+ * Strokes of a signature and the images they export to. Pure geometry: no DOM except the
+ * canvas context a caller passes in, so it runs the same in a test, on the pad and on export.
+ */
+/** One sampled pointer position, in CSS pixels of the pad. */
+export type SignaturePoint = {
+    x: number;
+    y: number;
+    /** Pen pressure from 0 to 1. Mouse and touch report 0.5. */
+    pressure: number;
+};
+/** One continuous line, from a pointer down to its pointer up. */
+export type SignatureStroke = readonly SignaturePoint[];
+export type SignatureBounds = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Exported image format: a PNG or an SVG, each as a data URL. */
+export type SignatureFormat = 'png' | 'svg';
+export type SignatureRenderOptions = {
+    /** CSS color of the ink. */
+    color: string;
+    /** Base line width in CSS pixels, at a pressure of 0.5. */
+    width: number;
+};
+/** Width of a segment drawn at `pressure`: half the base at no pressure, 1.5 times at full. */
+export declare const strokeWidthAt: (pressure: number, width: number) => number;
+/**
+ * The segments a stroke is drawn as: quadratic curves through the midpoints of its samples, so
+ * the line is smooth however coarse the pointer events were. Each segment carries the pressure it
+ * is drawn at, so a pen's line thickens and thins along the way.
+ */
+export declare function strokeSegments(stroke: SignatureStroke): {
+    from: SignaturePoint;
+    control: SignaturePoint;
+    to: SignaturePoint;
+    pressure: number;
+}[];
+/** Draws `strokes` on a 2D context already scaled to CSS pixels. A tap draws a dot. */
+export declare function drawStrokes(context: CanvasRenderingContext2D, strokes: readonly SignatureStroke[], { color, width }: SignatureRenderOptions): void;
+/** The box the ink covers, line width included, or null when there is no ink. */
+export declare function strokesBounds(strokes: readonly SignatureStroke[], width: number): SignatureBounds | null;
+/** One drawable piece of a stroke: a dot for a tap, or a path at one line width. */
+export type SignatureShape = {
+    kind: 'dot';
+    x: number;
+    y: number;
+    r: number;
+} | {
+    kind: 'path';
+    d: string;
+    width: number;
+};
+/**
+ * The shapes a stroke draws as, in SVG path syntax, shifted by `offset`. Consecutive segments
+ * at the same width share one path, so a mouse or finger stroke is a single path and only a
+ * pen's changing pressure splits it.
+ */
+export declare function strokeShapes(stroke: SignatureStroke, width: number, offset?: {
+    x: number;
+    y: number;
+}): SignatureShape[];
+/** A standalone SVG of the strokes, cropped to the ink plus `padding`. */
+export declare function strokesToSvg(strokes: readonly SignatureStroke[], { color, width, padding }: SignatureRenderOptions & {
+    padding: number;
+}): string | null;
+/**
+ * Exports the strokes as a data URL cropped to the ink plus `padding`: an SVG, or a PNG drawn at
+ * `scale` device pixels per CSS pixel so it stays sharp in a document. Null when there is no ink.
+ */
+export declare function exportStrokes(strokes: readonly SignatureStroke[], { format, color, width, padding, scale }: SignatureRenderOptions & {
+    format: SignatureFormat;
+    padding: number;
+    scale: number;
+}): string | null;

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

@@ -0,0 +1,149 @@
+/**
+ * Strokes of a signature and the images they export to. Pure geometry: no DOM except the
+ * canvas context a caller passes in, so it runs the same in a test, on the pad and on export.
+ */
+/** Width of a segment drawn at `pressure`: half the base at no pressure, 1.5 times at full. */
+export const strokeWidthAt = (pressure, width) => width * (0.5 + Math.min(Math.max(pressure, 0), 1));
+const midpoint = (a, b) => ({
+    x: (a.x + b.x) / 2,
+    y: (a.y + b.y) / 2,
+    pressure: (a.pressure + b.pressure) / 2
+});
+/**
+ * The segments a stroke is drawn as: quadratic curves through the midpoints of its samples, so
+ * the line is smooth however coarse the pointer events were. Each segment carries the pressure it
+ * is drawn at, so a pen's line thickens and thins along the way.
+ */
+export function strokeSegments(stroke) {
+    const segments = [];
+    if (stroke.length < 2)
+        return segments;
+    let from = stroke[0];
+    for (let index = 1; index < stroke.length - 1; index++) {
+        const control = stroke[index];
+        const to = midpoint(control, stroke[index + 1]);
+        segments.push({ from, control, to, pressure: control.pressure });
+        from = to;
+    }
+    const last = stroke[stroke.length - 1];
+    segments.push({ from, control: last, to: last, pressure: last.pressure });
+    return segments;
+}
+/** Draws `strokes` on a 2D context already scaled to CSS pixels. A tap draws a dot. */
+export function drawStrokes(context, strokes, { color, width }) {
+    context.save();
+    context.strokeStyle = color;
+    context.fillStyle = color;
+    context.lineCap = 'round';
+    context.lineJoin = 'round';
+    for (const stroke of strokes) {
+        if (stroke.length === 1) {
+            const [dot] = stroke;
+            context.beginPath();
+            context.arc(dot.x, dot.y, strokeWidthAt(dot.pressure, width) / 2, 0, Math.PI * 2);
+            context.fill();
+            continue;
+        }
+        for (const segment of strokeSegments(stroke)) {
+            context.beginPath();
+            context.lineWidth = strokeWidthAt(segment.pressure, width);
+            context.moveTo(segment.from.x, segment.from.y);
+            context.quadraticCurveTo(segment.control.x, segment.control.y, segment.to.x, segment.to.y);
+            context.stroke();
+        }
+    }
+    context.restore();
+}
+/** The box the ink covers, line width included, or null when there is no ink. */
+export function strokesBounds(strokes, width) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const stroke of strokes) {
+        for (const point of stroke) {
+            const half = strokeWidthAt(point.pressure, width) / 2;
+            minX = Math.min(minX, point.x - half);
+            minY = Math.min(minY, point.y - half);
+            maxX = Math.max(maxX, point.x + half);
+            maxY = Math.max(maxY, point.y + half);
+        }
+    }
+    if (minX === Infinity)
+        return null;
+    return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+const round = (value) => Math.round(value * 100) / 100;
+/**
+ * The shapes a stroke draws as, in SVG path syntax, shifted by `offset`. Consecutive segments
+ * at the same width share one path, so a mouse or finger stroke is a single path and only a
+ * pen's changing pressure splits it.
+ */
+export function strokeShapes(stroke, width, offset = { x: 0, y: 0 }) {
+    const x = (value) => round(value - offset.x);
+    const y = (value) => round(value - offset.y);
+    if (stroke.length === 1) {
+        const [dot] = stroke;
+        return [
+            { kind: 'dot', x: x(dot.x), y: y(dot.y), r: round(strokeWidthAt(dot.pressure, width) / 2) }
+        ];
+    }
+    const shapes = [];
+    for (const segment of strokeSegments(stroke)) {
+        const segmentWidth = round(strokeWidthAt(segment.pressure, width));
+        const curve = `Q${x(segment.control.x)} ${y(segment.control.y)} ${x(segment.to.x)} ${y(segment.to.y)}`;
+        const last = shapes.at(-1);
+        if (last?.kind === 'path' && last.width === segmentWidth)
+            last.d += curve;
+        else
+            shapes.push({
+                kind: 'path',
+                d: `M${x(segment.from.x)} ${y(segment.from.y)}${curve}`,
+                width: segmentWidth
+            });
+    }
+    return shapes;
+}
+/** A standalone SVG of the strokes, cropped to the ink plus `padding`. */
+export function strokesToSvg(strokes, { color, width, padding }) {
+    const bounds = strokesBounds(strokes, width);
+    if (!bounds)
+        return null;
+    const offset = { x: bounds.x - padding, y: bounds.y - padding };
+    const boxWidth = round(bounds.width + padding * 2);
+    const boxHeight = round(bounds.height + padding * 2);
+    const shapes = strokes
+        .flatMap((stroke) => strokeShapes(stroke, width, offset))
+        .map((shape) => shape.kind === 'dot'
+        ? `<circle cx="${shape.x}" cy="${shape.y}" r="${shape.r}" fill="${color}"/>`
+        : `<path d="${shape.d}" stroke-width="${shape.width}"/>`);
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${boxWidth}" height="${boxHeight}" viewBox="0 0 ${boxWidth} ${boxHeight}">`,
+        `<g fill="none" stroke="${color}" stroke-linecap="round" stroke-linejoin="round">`,
+        shapes.join(''),
+        '</g></svg>'
+    ].join('');
+}
+/**
+ * Exports the strokes as a data URL cropped to the ink plus `padding`: an SVG, or a PNG drawn at
+ * `scale` device pixels per CSS pixel so it stays sharp in a document. Null when there is no ink.
+ */
+export function exportStrokes(strokes, { format, color, width, padding, scale }) {
+    if (format === 'svg') {
+        const svg = strokesToSvg(strokes, { color, width, padding });
+        return svg ? `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}` : null;
+    }
+    const bounds = strokesBounds(strokes, width);
+    if (!bounds || typeof document === 'undefined')
+        return null;
+    const canvas = document.createElement('canvas');
+    canvas.width = Math.ceil((bounds.width + padding * 2) * scale);
+    canvas.height = Math.ceil((bounds.height + padding * 2) * scale);
+    const context = canvas.getContext('2d');
+    if (!context)
+        return null;
+    context.scale(scale, scale);
+    context.translate(padding - bounds.x, padding - bounds.y);
+    drawStrokes(context, strokes, { color, width });
+    return canvas.toDataURL('image/png');
+}

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

@@ -0,0 +1,99 @@
+import { type InferComponentTheme } from '../../../utils/cva/index.js';
+export declare const signatureInputTheme: {
+    frame: (props?: import("../../../utils/cva/types.ts").CVAClassProp | undefined) => string;
+    pad: (props?: (import("../../../utils/cva/types.ts").CVAVariantSchema<{
+        size: {
+            small: string;
+            normal: string;
+            large: string;
+        };
+        interactive: {
+            true: string;
+            false: string;
+        };
+        disabled: {
+            true: string;
+            false: string;
+        };
+        hasError: {
+            true: string;
+            false: string;
+        };
+    }> & 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;
+    placeholder: (props?: (import("../../../utils/cva/types.ts").CVAVariantSchema<{
+        size: {
+            small: string;
+            normal: string;
+            large: string;
+        };
+    }> & import("../../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
+    actions: (props?: import("../../../utils/cva/types.ts").CVAClassProp | undefined) => string;
+};
+export type SignatureInputTheme = typeof signatureInputTheme;
+export type SignatureInputThemeProps = InferComponentTheme<SignatureInputTheme>;
+export declare const setSignatureInputTheme: (theme: InferComponentTheme<{
+    frame: (props?: import("../../../utils/cva/types.ts").CVAClassProp | undefined) => string;
+    pad: (props?: (import("../../../utils/cva/types.ts").CVAVariantSchema<{
+        size: {
+            small: string;
+            normal: string;
+            large: string;
+        };
+        interactive: {
+            true: string;
+            false: string;
+        };
+        disabled: {
+            true: string;
+            false: string;
+        };
+        hasError: {
+            true: string;
+            false: string;
+        };
+    }> & 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;
+    placeholder: (props?: (import("../../../utils/cva/types.ts").CVAVariantSchema<{
+        size: {
+            small: string;
+            normal: string;
+            large: string;
+        };
+    }> & import("../../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
+    actions: (props?: import("../../../utils/cva/types.ts").CVAClassProp | undefined) => string;
+}>) => void;
+export declare const useSignatureInputTheme: import("../../../utils/cva/theme.ts").UseComponentTheme<{
+    frame: (props?: import("../../../utils/cva/types.ts").CVAClassProp | undefined) => string;
+    pad: (props?: (import("../../../utils/cva/types.ts").CVAVariantSchema<{
+        size: {
+            small: string;
+            normal: string;
+            large: string;
+        };
+        interactive: {
+            true: string;
+            false: string;
+        };
+        disabled: {
+            true: string;
+            false: string;
+        };
+        hasError: {
+            true: string;
+            false: string;
+        };
+    }> & 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;
+    placeholder: (props?: (import("../../../utils/cva/types.ts").CVAVariantSchema<{
+        size: {
+            small: string;
+            normal: string;
+            large: string;
+        };
+    }> & import("../../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
+    actions: (props?: import("../../../utils/cva/types.ts").CVAClassProp | undefined) => string;
+}>;

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

@@ -0,0 +1,70 @@
+import { cva, setComponentTheme, useComponentTheme } from '../../../utils/cva/index.js';
+// Holds the pad and, over its corner, the buttons: they cannot sit inside the pad, whose image
+// role would hide them from assistive technology.
+const defaultFrame = cva({
+    base: 'relative w-full min-w-0'
+});
+// The pad is the control: it takes focus, so its own ring shows keyboard focus, and the strokes
+// are drawn in its text color (an SVG in `currentColor`), so they follow the theme.
+const defaultPad = cva({
+    base: 'relative w-full min-w-0 touch-none overflow-hidden rounded-md border border-neutral-muted bg-surface-raised text-neutral outline-none select-none focus-visible:ring-2 focus-visible:ring-focus/50',
+    variants: {
+        size: {
+            small: 'h-28',
+            normal: 'h-36',
+            large: 'h-44'
+        },
+        interactive: {
+            true: 'cursor-crosshair',
+            false: ''
+        },
+        disabled: {
+            true: 'cursor-not-allowed opacity-50',
+            false: ''
+        },
+        hasError: {
+            true: 'border-danger focus-visible:ring-danger/50',
+            false: ''
+        }
+    },
+    defaultVariants: {
+        size: 'normal',
+        interactive: true,
+        disabled: false,
+        hasError: false
+    }
+});
+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.
+const defaultImage = cva({
+    base: 'pointer-events-none absolute inset-0 size-full object-contain p-md'
+});
+// The line to sign on and its hint: decorative, gone as soon as there is ink.
+const defaultPlaceholder = cva({
+    base: 'pointer-events-none absolute inset-x-[var(--space-xl)] bottom-1/4 flex items-end gap-sm border-b border-dashed border-neutral-muted pb-xs text-neutral/45',
+    variants: {
+        size: {
+            small: 'text-xs',
+            normal: 'text-sm',
+            large: 'text-base'
+        }
+    },
+    defaultVariants: {
+        size: 'normal'
+    }
+});
+const defaultActions = cva({
+    base: 'absolute end-[var(--space-xs)] top-[var(--space-xs)] flex items-center gap-xs'
+});
+export const signatureInputTheme = {
+    frame: defaultFrame,
+    pad: defaultPad,
+    ink: defaultInk,
+    image: defaultImage,
+    placeholder: defaultPlaceholder,
+    actions: defaultActions
+};
+export const setSignatureInputTheme = setComponentTheme('signature-input');
+export const useSignatureInputTheme = useComponentTheme('signature-input', signatureInputTheme);

package/dist/components/Sidebar/sidebar-layout.js

@@ -59,6 +59,8 @@ export function getSidebarPanelPeekClass(variant) {
  * ones for floating and split (the panel's own gutter spaces the pair).
  */
 export function getSidebarActivityBarContainerClass(side, frame, variant) {
-    return cx('inset-y-0 z-30 hidden w-[var(--sidebar-activity-offset,3rem)] md:flex', frame === 'viewport' ? 'fixed h-window' : 'absolute h-full', side === 'left' ? 'left-0' : 'right-0', variant === 'inset' && 'py-md', (variant === 'floating' || variant === 'split') &&
+    // Above the panel in every state, a peek (`z-40`) included: an edge-revealed panel slides in
+    // from past the screen edge and must come out from under the rail, never across it.
+    return cx('inset-y-0 z-[45] hidden w-[var(--sidebar-activity-offset,3rem)] md:flex', frame === 'viewport' ? 'fixed h-window' : 'absolute h-full', side === 'left' ? 'left-0' : 'right-0', variant === 'inset' && 'py-md', (variant === 'floating' || variant === 'split') &&
         (side === 'left' ? 'py-md pl-md' : 'py-md pr-md'));
 }

package/dist/components/Timeline/Timeline.svelte

@@ -15,7 +15,7 @@
 		size = 'normal',
 		density = 'normal',
 		color = 'neutral',
-		connectorColor = 'neutral',
+		connectorColor,
 		showConnectors = true,
 		scrollFade = true,
 		i18n,

package/dist/components/Timeline/TimelineEntry.svelte

@@ -1,4 +1,5 @@
 <script lang="ts" generics="Item extends TimelineItem = TimelineItem">
+	import { checkIcon } from '../Icons/check.js';
 	import Slot from '../Slot/Slot.svelte';
 	import Spinner from '../Spinner/Spinner.svelte';
 	import type { Density, Sizes } from '../../types/theme.js';
@@ -64,6 +65,8 @@
 	data-density={density}
 	data-first={entry.isFirst ? 'true' : undefined}
 	data-last={entry.isLast ? 'true' : undefined}
+	data-progress={entry.item.progress}
+	aria-current={entry.item.progress === 'current' ? 'step' : undefined}
 	class={classes.item({
 		orientation: entry.orientation,
 		placement,
@@ -107,9 +110,11 @@
 			<span
 				data-slot="timeline-connector"
 				data-color={entry.connectorColor}
+				data-progress={entry.item.progress}
 				class={classes.connector({
 					orientation: entry.orientation,
-					color: entry.connectorColor
+					color: entry.connectorColor,
+					progress: entry.item.progress ?? 'none'
 				})}
 			></span>
 		{/if}
@@ -182,7 +187,12 @@
 	<span
 		data-slot="timeline-marker"
 		data-color={entry.color}
-		class={classes.marker({ size, color: entry.color })}
+		data-progress={entry.item.loading ? undefined : entry.item.progress}
+		class={classes.marker({
+			size,
+			color: entry.color,
+			progress: entry.item.loading ? 'none' : (entry.item.progress ?? 'none')
+		})}
 	>
 		{#if entry.item.loading}
 			<span data-slot="timeline-loading" class={classes.loading({ size })}>
@@ -190,6 +200,10 @@
 			</span>
 		{:else if entry.item.icon}
 			<Slot render={entry.item.icon} />
+		{:else if entry.item.progress === 'done'}
+			{@render checkIcon()}
+		{:else if entry.item.progress === 'upcoming'}
+			<span data-slot="timeline-step-number">{entry.index + 1}</span>
 		{:else}
 			<span data-slot="timeline-dot"></span>
 		{/if}

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

@@ -1,3 +1,3 @@
 export { default as Timeline } from './Timeline.svelte';
-export type { TimelineItem, TimelineItemPayload, TimelineOrientation, TimelinePlacement, TimelineProps, TimelineSide, TimelineVariant } from './timeline.props.js';
+export type { TimelineItem, TimelineItemPayload, TimelineOrientation, TimelinePlacement, TimelineProgress, TimelineProps, TimelineSide, TimelineVariant } from './timeline.props.js';
 export { timelineTheme, setTimelineTheme, useTimelineTheme, type TimelineTheme, type TimelineThemeProps } from './timeline.theme.js';

package/dist/components/Timeline/timeline.items.d.ts

@@ -11,4 +11,4 @@ export type ResolvedTimelineItem<Item extends TimelineItem> = Readonly<{
     isFirst: boolean;
     isLast: boolean;
 }>;
-export declare function resolveTimelineItems<Item extends TimelineItem>(items: readonly Item[], orientation: TimelineOrientation, placement: TimelinePlacement, color: Colors, connectorColor: Colors): readonly ResolvedTimelineItem<Item>[];
+export declare function resolveTimelineItems<Item extends TimelineItem>(items: readonly Item[], orientation: TimelineOrientation, placement: TimelinePlacement, color: Colors, connectorColor: Colors | undefined): readonly ResolvedTimelineItem<Item>[];

package/dist/components/Timeline/timeline.items.js

@@ -17,6 +17,7 @@ export function resolveTimelineItems(items, orientation, placement, color, conne
         const side = placement === 'alternate'
             ? (timelineItem.side ?? (index % 2 === 0 ? 'end' : 'start'))
             : placement;
+        const itemColor = timelineItem.color ?? color;
         let key = `index:${index}`;
         if (explicitId !== undefined) {
             key = `id:${typeof explicitId}:${explicitId}`;
@@ -27,8 +28,12 @@ export function resolveTimelineItems(items, orientation, placement, color, conne
             index,
             side,
             orientation,
-            color: timelineItem.color ?? color,
-            connectorColor: timelineItem.connectorColor ?? connectorColor,
+            color: itemColor,
+            // A progress band reads as one stroke: its connectors follow the step's own color
+            // unless a connector color is set on the item or the root.
+            connectorColor: timelineItem.connectorColor ??
+                connectorColor ??
+                (timelineItem.progress ? itemColor : 'neutral'),
             isFirst: index === 0,
             isLast: index === items.length - 1
         };

package/dist/components/Timeline/timeline.mcp.d.ts

@@ -1 +1 @@
-export declare const timelineDescription = "\n# Timeline\n\nRender an ordered sequence of dated or descriptive events on a vertical or horizontal axis. Timeline owns the semantic list, item surfaces, axis anchors, markers, connectors, responsive alternate collapse, and horizontal overflow behavior. Input order is always render order.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n  import { Timeline, type TimelineItem } from './index.ts';\n\n  const items: TimelineItem[] = [\n    {\n      id: 'placed',\n      date: 'Mar 15, 2024',\n      datetime: '2024-03-15',\n      title: 'Order placed',\n      description: 'Your order has been received.'\n    },\n    {\n      id: 'payment',\n      date: 'Mar 16, 2024',\n      datetime: '2024-03-16',\n      title: 'Payment confirmed',\n      color: 'success'\n    }\n  ];\n</script>\n\n<Timeline {items} />\n```\n\nThe default configuration is a vertical timeline with all content on the logical end side of the axis.\n\n## Props\n\n### Data and layout\n\n- **items**: `readonly Item[]` (required) \u2014 entries in display order. `Item` must extend `TimelineItem`.\n- **orientation**: `'vertical' | 'horizontal'` (default: `'vertical'`) \u2014 direction of the sequence axis.\n- **placement**: `'start' | 'end' | 'alternate'` (default: `'end'`) \u2014 logical side used for item surfaces. Alternate placement starts on `end`, then alternates by array index.\n- **variant**: `'ghost' | 'card' | 'outline' | 'soft'` (default: `'ghost'`) \u2014 global surface treatment for all entries.\n- **size**: `'small' | 'normal' | 'large'` (default: `'normal'`) \u2014 title and description typography, marker and icon scale, and loading Spinner scale.\n- **density**: `'compact' | 'normal' | 'comfortable'` (default: `'normal'`) \u2014 item gaps, surface padding, connector spacing, and horizontal item minimum width.\n- **color**: Entasis semantic color (default: `'neutral'`) \u2014 default marker and outline or soft surface accent.\n- **connectorColor**: Entasis semantic color (default: `'neutral'`) \u2014 default outgoing connector color.\n- **showConnectors**: `boolean` (default: `true`) \u2014 shows connector segments between markers.\n- **scrollFade**: `boolean` (default: `true`) \u2014 applies the shared logical horizontal scroll fade only while a horizontal timeline actually overflows.\n- **i18n**: `Partial<Messages>` \u2014 per-instance translations merged over the global i18n catalog.\n\n### Custom rendering\n\n- **item**: `Snippet<[TimelineItemPayload<Item>]>` \u2014 replaces the content inside each Timeline-owned variant surface.\n- **marker**: `Snippet<[TimelineItemPayload<Item>]>` \u2014 replaces the marker visual inside the Timeline-owned axis anchor.\n- **opposite**: `Snippet<[TimelineItemPayload<Item>]>` \u2014 replaces the opposite track in alternate placement. Its default renderer is the item date. TypeScript rejects this prop with fixed `start` or `end` placement.\n\n### Root element\n\n- **ref**: `HTMLOListElement | null` (bindable) \u2014 reference to the root `<ol>`.\n- **class**: `string` \u2014 additional root classes.\n- **theme**: `TimelineThemeProps` \u2014 per-instance overrides for Timeline theme parts.\n- Native ordered-list attributes and Svelte attachments are forwarded to the root.\n\n## Item shape\n\n```ts\ntype TimelineItem = {\n  id?: string | number;\n  title: Slot;\n  date?: Slot;\n  datetime?: string;\n  description?: Slot;\n  icon?: Slot;\n  loading?: boolean;\n  color?: Colors;\n  connectorColor?: Colors;\n  side?: 'start' | 'end';\n};\n```\n\n- `title` is required. `title`, `date`, `description`, and `icon` accept a string or snippet.\n- `id` is optional. Use a stable explicit ID when entries can reorder; otherwise Timeline uses the array index as identity.\n- `datetime` adds the machine-readable value to a default `<time>` element when `date` is present.\n- `icon` replaces the default dot inside the default marker.\n- `loading` replaces the default marker visual with a color- and size-aware Spinner.\n- `color` overrides the root color for this marker and its outline or soft surface.\n- `connectorColor` overrides the root color for this item's outgoing connector. It has no effect on the final item.\n- `side` overrides alternate parity for one item. It is not valid with fixed placement.\n\n## Placement and dates\n\nFixed `start` and `end` placement keeps every surface on one logical side. The default content renders the date before the title inside each surface.\n\n`placement=\"alternate\"` creates an opposite track and starts the first item on `end`. Its default opposite renderer displays the date. Set `item.side` to place a specific alternate item on `start` or `end` without changing the array order.\n\n```svelte\n<Timeline items={milestones} placement=\"alternate\" variant=\"card\" />\n```\n\nTimeline treats dates as display content. It does not parse, format, compare, or sort them. It also has no completed, current, or pending status model. Put status meaning in the title or description and use semantic color or a custom marker only as supporting presentation.\n\n## Generic snippets and defaults\n\nApplication item types can extend `TimelineItem`. The extended type remains available as `payload.item` in all three renderer snippets.\n\n```svelte\n<script lang=\"ts\">\n  import { Timeline, type TimelineItem } from './index.ts';\n\n  type Release = TimelineItem & {\n    version: string;\n    href: string;\n  };\n\n  const releases: Release[] = [\n    { id: 'v2', title: 'Version 2 released', version: '2.0.0', href: '/releases/v2' }\n  ];\n</script>\n\n<Timeline items={releases}>\n  {#snippet item({ item, defaultContent })}\n    <a href={item.href} class=\"block\">\n      {@render defaultContent()}\n      <span class=\"text-neutral/70 text-xs\">{item.version}</span>\n    </a>\n  {/snippet}\n</Timeline>\n```\n\nEvery snippet receives:\n\n```ts\ntype TimelineItemPayload<Item extends TimelineItem> = Readonly<{\n  item: Item;\n  index: number;\n  side: 'start' | 'end';\n  orientation: 'vertical' | 'horizontal';\n  color: Colors;\n  connectorColor: Colors;\n  isFirst: boolean;\n  isLast: boolean;\n  defaultContent: Snippet;\n  defaultMarker: Snippet;\n  defaultOpposite: Snippet;\n}>;\n```\n\nCall `defaultContent()`, `defaultMarker()`, or `defaultOpposite()` to wrap or extend the matching default renderer. A custom `marker` snippet that does not call `defaultMarker()` owns its complete marker visual, including loading presentation. Timeline still owns the `<ol>`, each `<li>`, axis and connector geometry, marker anchor, opposite track, and variant surface.\n\n## Responsive alternate layout\n\nA vertical alternate timeline uses its own inline-size container. Below `40rem`, it moves the axis to the logical start edge, places every main surface on the end side, and places opposite content before the main surface. DOM and input order do not change. Per-item `side` values remain in the payload, but their visual side effect is suspended while the layout is collapsed.\n\n## Horizontal overflow\n\nHorizontal entries stay on one axis and use density-controlled minimum widths. They do not wrap or compress; the root uses native horizontal scrolling. Timeline measures real overflow with `ResizeObserver`, applies `scroll-fade-x` only when needed, and makes the ordered list keyboard-focusable only while it overflows. The fade and native scrolling use logical inline direction and work in LTR and RTL layouts.\n\n## Variants\n\n- `ghost`: no surface chrome.\n- `card`: neutral raised surface with a quiet ring and shadow.\n- `outline`: transparent surface with a ring in the resolved item color.\n- `soft`: muted surface in the resolved item color.\n\nThe variant is global. Timeline does not support per-item variant overrides.\n\n## Runtime validation\n\nTimeline throws a descriptive `TypeError` when:\n\n- two items have the same explicit `id`;\n- an item supplies `side` while placement is fixed to `start` or `end`.\n\nThe ID check preserves number and string identity, so `1` and `'1'` are different IDs. TypeScript separately rejects `opposite` with fixed placement.\n\n## Accessibility\n\n- The root is an ordered list and every event is a list item.\n- Axis anchors, markers, and connectors are decorative and hidden from assistive technology. Do not use marker color or shape as the only status signal.\n- A default loading marker has a localized polite status announcement outside the decorative axis.\n- A default date with `datetime` renders as a semantic `<time>` element.\n- An overflowing horizontal timeline becomes a native keyboard scroll region; a non-overflowing timeline adds no tab stop.\n\n## Theme parts\n\n`root`, `item`, `opposite`, `axis`, `connector`, `marker`, `content`, `date`, `titleRow`, `title`, `description`, and `loading`.\n\nTimeline is display-only. It has no selection, navigation, event callbacks, animation state, bindable controller, date processing, or built-in progress status.\n";
+export declare const timelineDescription = "\n# Timeline\n\nRender an ordered sequence of dated or descriptive events on a vertical or horizontal axis. Timeline owns the semantic list, item surfaces, axis anchors, markers, connectors, responsive alternate collapse, and horizontal overflow behavior. Input order is always render order.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n  import { Timeline, type TimelineItem } from './index.ts';\n\n  const items: TimelineItem[] = [\n    {\n      id: 'placed',\n      date: 'Mar 15, 2024',\n      datetime: '2024-03-15',\n      title: 'Order placed',\n      description: 'Your order has been received.'\n    },\n    {\n      id: 'payment',\n      date: 'Mar 16, 2024',\n      datetime: '2024-03-16',\n      title: 'Payment confirmed',\n      color: 'success'\n    }\n  ];\n</script>\n\n<Timeline {items} />\n```\n\nThe default configuration is a vertical timeline with all content on the logical end side of the axis.\n\n## Props\n\n### Data and layout\n\n- **items**: `readonly Item[]` (required) \u2014 entries in display order. `Item` must extend `TimelineItem`.\n- **orientation**: `'vertical' | 'horizontal'` (default: `'vertical'`) \u2014 direction of the sequence axis.\n- **placement**: `'start' | 'end' | 'alternate'` (default: `'end'`) \u2014 logical side used for item surfaces. Alternate placement starts on `end`, then alternates by array index.\n- **variant**: `'ghost' | 'card' | 'outline' | 'soft'` (default: `'ghost'`) \u2014 global surface treatment for all entries.\n- **size**: `'small' | 'normal' | 'large'` (default: `'normal'`) \u2014 title and description typography, marker and icon scale, and loading Spinner scale.\n- **density**: `'compact' | 'normal' | 'comfortable'` (default: `'normal'`) \u2014 item gaps, surface padding, connector spacing, and horizontal item minimum width.\n- **color**: Entasis semantic color (default: `'neutral'`) \u2014 default marker and outline or soft surface accent.\n- **connectorColor**: Entasis semantic color \u2014 default outgoing connector color. When omitted, an item with `progress` uses its own resolved color for its connector, and every other item uses `'neutral'`.\n- **showConnectors**: `boolean` (default: `true`) \u2014 shows connector segments between markers.\n- **scrollFade**: `boolean` (default: `true`) \u2014 applies the shared logical horizontal scroll fade only while a horizontal timeline actually overflows.\n- **i18n**: `Partial<Messages>` \u2014 per-instance translations merged over the global i18n catalog.\n\n### Custom rendering\n\n- **item**: `Snippet<[TimelineItemPayload<Item>]>` \u2014 replaces the content inside each Timeline-owned variant surface.\n- **marker**: `Snippet<[TimelineItemPayload<Item>]>` \u2014 replaces the marker visual inside the Timeline-owned axis anchor.\n- **opposite**: `Snippet<[TimelineItemPayload<Item>]>` \u2014 replaces the opposite track in alternate placement. Its default renderer is the item date. TypeScript rejects this prop with fixed `start` or `end` placement.\n\n### Root element\n\n- **ref**: `HTMLOListElement | null` (bindable) \u2014 reference to the root `<ol>`.\n- **class**: `string` \u2014 additional root classes.\n- **theme**: `TimelineThemeProps` \u2014 per-instance overrides for Timeline theme parts.\n- Native ordered-list attributes and Svelte attachments are forwarded to the root.\n\n## Item shape\n\n```ts\ntype TimelineItem = {\n  id?: string | number;\n  title: Slot;\n  date?: Slot;\n  datetime?: string;\n  description?: Slot;\n  icon?: Slot;\n  loading?: boolean;\n  color?: Colors;\n  connectorColor?: Colors;\n  progress?: 'done' | 'current' | 'upcoming';\n  side?: 'start' | 'end';\n};\n```\n\n- `title` is required. `title`, `date`, `description`, and `icon` accept a string or snippet.\n- `id` is optional. Use a stable explicit ID when entries can reorder; otherwise Timeline uses the array index as identity.\n- `datetime` adds the machine-readable value to a default `<time>` element when `date` is present.\n- `icon` replaces the default dot inside the default marker.\n- `loading` replaces the default marker visual with a color- and size-aware Spinner.\n- `color` overrides the root color for this marker and its outline or soft surface.\n- `connectorColor` overrides the root color for this item's outgoing connector. It has no effect on the final item.\n- `side` overrides alternate parity for one item. It is not valid with fixed placement.\n- `progress` marks a step of a process (`TimelineProgress`). See Step progress below.\n\n## Placement and dates\n\nFixed `start` and `end` placement keeps every surface on one logical side. The default content renders the date before the title inside each surface.\n\n`placement=\"alternate\"` creates an opposite track and starts the first item on `end`. Its default opposite renderer displays the date. Set `item.side` to place a specific alternate item on `start` or `end` without changing the array order.\n\n```svelte\n<Timeline items={milestones} placement=\"alternate\" variant=\"card\" />\n```\n\nTimeline treats dates as display content. It does not parse, format, compare, or sort them.\n\n## Step progress\n\nGive each item a `progress` to draw a process's progress band, such as a file's six stages, so a reader sees at a glance what is done, what is under way, and what is to come:\n\n```svelte\n<script lang=\"ts\">\n  import { Timeline, type TimelineItem } from './index.ts';\n\n  const steps: TimelineItem[] = [\n    { id: 'opened', title: 'Opened', progress: 'done' },\n    { id: 'documents', title: 'Documents', progress: 'done' },\n    { id: 'appraisal', title: 'Appraisal', progress: 'current' },\n    { id: 'report', title: 'Report', progress: 'upcoming' }\n  ];\n</script>\n\n<Timeline items={steps} orientation=\"horizontal\" color=\"primary\" />\n```\n\n- `done`: the marker is filled with the item color and carries a check. Its outgoing connector is solid.\n- `current`: the marker is a ring in the item color around a point. The `<li>` gets `aria-current=\"step\"`. Its outgoing connector is faint.\n- `upcoming`: the marker is a quiet neutral ring carrying the step number (the item's position, from 1). Its outgoing connector is faint.\n- Markers keep the size's marker scale. Progress connectors are 2px thick instead of the hairline, so the done part of the band stands out.\n- An item `icon` replaces the check, the point, or the number, and keeps the progress ring and fill. `loading` replaces the whole marker with the Spinner.\n- `progress` is per item: Timeline does not derive it from an index, so a host may mark any combination.\n- The step's state is not announced by the markers, which stay decorative. Put it in the item's own text (for example \"Step 3 of 6, done\") or an `item` snippet. `aria-current=\"step\"` on the current item is the only state Timeline adds.\n- The `marker` snippet still replaces every marker: read `payload.item.progress` and call `defaultMarker()` for the steps it leaves alone. Theme overrides reach the `progress` variant of the `marker` and `connector` parts, for example `theme={{ connector: { progress: { done: 'bg-success' } } }}`.\n- Styling hooks: `data-progress` on the item, its marker and its outgoing connector.\n\n## Generic snippets and defaults\n\nApplication item types can extend `TimelineItem`. The extended type remains available as `payload.item` in all three renderer snippets.\n\n```svelte\n<script lang=\"ts\">\n  import { Timeline, type TimelineItem } from './index.ts';\n\n  type Release = TimelineItem & {\n    version: string;\n    href: string;\n  };\n\n  const releases: Release[] = [\n    { id: 'v2', title: 'Version 2 released', version: '2.0.0', href: '/releases/v2' }\n  ];\n</script>\n\n<Timeline items={releases}>\n  {#snippet item({ item, defaultContent })}\n    <a href={item.href} class=\"block\">\n      {@render defaultContent()}\n      <span class=\"text-neutral/70 text-xs\">{item.version}</span>\n    </a>\n  {/snippet}\n</Timeline>\n```\n\nEvery snippet receives:\n\n```ts\ntype TimelineItemPayload<Item extends TimelineItem> = Readonly<{\n  item: Item;\n  index: number;\n  side: 'start' | 'end';\n  orientation: 'vertical' | 'horizontal';\n  color: Colors;\n  connectorColor: Colors;\n  isFirst: boolean;\n  isLast: boolean;\n  defaultContent: Snippet;\n  defaultMarker: Snippet;\n  defaultOpposite: Snippet;\n}>;\n```\n\nCall `defaultContent()`, `defaultMarker()`, or `defaultOpposite()` to wrap or extend the matching default renderer. A custom `marker` snippet that does not call `defaultMarker()` owns its complete marker visual, including loading presentation. Timeline still owns the `<ol>`, each `<li>`, axis and connector geometry, marker anchor, opposite track, and variant surface.\n\n## Responsive alternate layout\n\nA vertical alternate timeline uses its own inline-size container. Below `40rem`, it moves the axis to the logical start edge, places every main surface on the end side, and places opposite content before the main surface. DOM and input order do not change. Per-item `side` values remain in the payload, but their visual side effect is suspended while the layout is collapsed.\n\n## Horizontal overflow\n\nHorizontal entries stay on one axis and use density-controlled minimum widths. They do not wrap or compress; the root uses native horizontal scrolling. Timeline measures real overflow with `ResizeObserver`, applies `scroll-fade-x` only when needed, and makes the ordered list keyboard-focusable only while it overflows. The fade and native scrolling use logical inline direction and work in LTR and RTL layouts.\n\n## Variants\n\n- `ghost`: no surface chrome.\n- `card`: neutral raised surface with a quiet ring and shadow.\n- `outline`: transparent surface with a ring in the resolved item color.\n- `soft`: muted surface in the resolved item color.\n\nThe variant is global. Timeline does not support per-item variant overrides.\n\n## Runtime validation\n\nTimeline throws a descriptive `TypeError` when:\n\n- two items have the same explicit `id`;\n- an item supplies `side` while placement is fixed to `start` or `end`.\n\nThe ID check preserves number and string identity, so `1` and `'1'` are different IDs. TypeScript separately rejects `opposite` with fixed placement.\n\n## Accessibility\n\n- The root is an ordered list and every event is a list item.\n- Axis anchors, markers, and connectors are decorative and hidden from assistive technology. Do not use marker color or shape as the only status signal.\n- An item with `progress: 'current'` carries `aria-current=\"step\"`.\n- A default loading marker has a localized polite status announcement outside the decorative axis.\n- A default date with `datetime` renders as a semantic `<time>` element.\n- An overflowing horizontal timeline becomes a native keyboard scroll region; a non-overflowing timeline adds no tab stop.\n\n## Theme parts\n\n`root`, `item`, `opposite`, `axis`, `connector`, `marker`, `content`, `date`, `titleRow`, `title`, `description`, and `loading`.\n\nTimeline is display-only. It has no selection, navigation, event callbacks, animation state, bindable controller, or date processing. Step `progress` is presentation the host sets per item, not a state Timeline advances.\n";

package/dist/components/Timeline/timeline.mcp.js

@@ -43,7 +43,7 @@ The default configuration is a vertical timeline with all content on the logical
 - **size**: \`'small' | 'normal' | 'large'\` (default: \`'normal'\`) — title and description typography, marker and icon scale, and loading Spinner scale.
 - **density**: \`'compact' | 'normal' | 'comfortable'\` (default: \`'normal'\`) — item gaps, surface padding, connector spacing, and horizontal item minimum width.
 - **color**: Entasis semantic color (default: \`'neutral'\`) — default marker and outline or soft surface accent.
-- **connectorColor**: Entasis semantic color (default: \`'neutral'\`) — default outgoing connector color.
+- **connectorColor**: Entasis semantic color — default outgoing connector color. When omitted, an item with \`progress\` uses its own resolved color for its connector, and every other item uses \`'neutral'\`.
 - **showConnectors**: \`boolean\` (default: \`true\`) — shows connector segments between markers.
 - **scrollFade**: \`boolean\` (default: \`true\`) — applies the shared logical horizontal scroll fade only while a horizontal timeline actually overflows.
 - **i18n**: \`Partial<Messages>\` — per-instance translations merged over the global i18n catalog.
@@ -74,6 +74,7 @@ type TimelineItem = {
   loading?: boolean;
   color?: Colors;
   connectorColor?: Colors;
+  progress?: 'done' | 'current' | 'upcoming';
   side?: 'start' | 'end';
 };
 \`\`\`
@@ -86,6 +87,7 @@ type TimelineItem = {
 - \`color\` overrides the root color for this marker and its outline or soft surface.
 - \`connectorColor\` overrides the root color for this item's outgoing connector. It has no effect on the final item.
 - \`side\` overrides alternate parity for one item. It is not valid with fixed placement.
+- \`progress\` marks a step of a process (\`TimelineProgress\`). See Step progress below.
 
 ## Placement and dates
 
@@ -97,7 +99,36 @@ Fixed \`start\` and \`end\` placement keeps every surface on one logical side. T
 <Timeline items={milestones} placement="alternate" variant="card" />
 \`\`\`
 
-Timeline treats dates as display content. It does not parse, format, compare, or sort them. It also has no completed, current, or pending status model. Put status meaning in the title or description and use semantic color or a custom marker only as supporting presentation.
+Timeline treats dates as display content. It does not parse, format, compare, or sort them.
+
+## Step progress
+
+Give each item a \`progress\` to draw a process's progress band, such as a file's six stages, so a reader sees at a glance what is done, what is under way, and what is to come:
+
+\`\`\`svelte
+<script lang="ts">
+  import { Timeline, type TimelineItem } from './index.ts';
+
+  const steps: TimelineItem[] = [
+    { id: 'opened', title: 'Opened', progress: 'done' },
+    { id: 'documents', title: 'Documents', progress: 'done' },
+    { id: 'appraisal', title: 'Appraisal', progress: 'current' },
+    { id: 'report', title: 'Report', progress: 'upcoming' }
+  ];
+</script>
+
+<Timeline items={steps} orientation="horizontal" color="primary" />
+\`\`\`
+
+- \`done\`: the marker is filled with the item color and carries a check. Its outgoing connector is solid.
+- \`current\`: the marker is a ring in the item color around a point. The \`<li>\` gets \`aria-current="step"\`. Its outgoing connector is faint.
+- \`upcoming\`: the marker is a quiet neutral ring carrying the step number (the item's position, from 1). Its outgoing connector is faint.
+- Markers keep the size's marker scale. Progress connectors are 2px thick instead of the hairline, so the done part of the band stands out.
+- An item \`icon\` replaces the check, the point, or the number, and keeps the progress ring and fill. \`loading\` replaces the whole marker with the Spinner.
+- \`progress\` is per item: Timeline does not derive it from an index, so a host may mark any combination.
+- The step's state is not announced by the markers, which stay decorative. Put it in the item's own text (for example "Step 3 of 6, done") or an \`item\` snippet. \`aria-current="step"\` on the current item is the only state Timeline adds.
+- The \`marker\` snippet still replaces every marker: read \`payload.item.progress\` and call \`defaultMarker()\` for the steps it leaves alone. Theme overrides reach the \`progress\` variant of the \`marker\` and \`connector\` parts, for example \`theme={{ connector: { progress: { done: 'bg-success' } } }}\`.
+- Styling hooks: \`data-progress\` on the item, its marker and its outgoing connector.
 
 ## Generic snippets and defaults
 
@@ -177,6 +208,7 @@ The ID check preserves number and string identity, so \`1\` and \`'1'\` are diff
 
 - The root is an ordered list and every event is a list item.
 - Axis anchors, markers, and connectors are decorative and hidden from assistive technology. Do not use marker color or shape as the only status signal.
+- An item with \`progress: 'current'\` carries \`aria-current="step"\`.
 - A default loading marker has a localized polite status announcement outside the decorative axis.
 - A default date with \`datetime\` renders as a semantic \`<time>\` element.
 - An overflowing horizontal timeline becomes a native keyboard scroll region; a non-overflowing timeline adds no tab stop.
@@ -185,5 +217,5 @@ The ID check preserves number and string identity, so \`1\` and \`'1'\` are diff
 
 \`root\`, \`item\`, \`opposite\`, \`axis\`, \`connector\`, \`marker\`, \`content\`, \`date\`, \`titleRow\`, \`title\`, \`description\`, and \`loading\`.
 
-Timeline is display-only. It has no selection, navigation, event callbacks, animation state, bindable controller, date processing, or built-in progress status.
+Timeline is display-only. It has no selection, navigation, event callbacks, animation state, bindable controller, or date processing. Step \`progress\` is presentation the host sets per item, not a state Timeline advances.
 `;