@hyvnt/hyvui 0.3.0 → 0.4.0

package/dist/components/feedback/StatusDot.svelte

@@ -1,6 +1,12 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * @example
+	 * <StatusDot status="ok" />
+	 * <StatusDot status="pend" pulse={false} />
+	 * <StatusDot status="fail" size={8} />
+	 */
 	interface Props {
 		/** Status state determining the dot color. */
 		status?: 'ok' | 'pend' | 'warn' | 'fail';
@@ -38,7 +44,7 @@
 	}
 
 	.hyvui-status-dot-pulse {
-		animation: pulse-dot 2s ease-in-out infinite;
+		animation: pulse-dot 2s cubic-bezier(0.37, 0, 0.63, 1) infinite;
 	}
 
 	@media (prefers-reduced-motion: reduce) {
@@ -46,4 +52,33 @@
 			animation: none;
 		}
 	}
+
+	/* ── hextech: cyan ring pulse instead of scale ────────────────────── */
+	:global([data-register='hextech']) .hyvui-status-dot-pulse {
+		animation: sd-hextech-pulse 2.4s cubic-bezier(0.16, 1, 0.3, 1) infinite;
+	}
+
+	@keyframes sd-hextech-pulse {
+		0%, 100% { box-shadow: 0 0 0 0 rgba(93, 217, 240, 0.0); }
+		50%       { box-shadow: 0 0 0 4px rgba(93, 217, 240, 0.0); opacity: 1; }
+		30%       { box-shadow: 0 0 0 3px rgba(93, 217, 240, 0.35); opacity: 1; }
+	}
+
+	/* ── arcane: shimmer ripple ───────────────────────────────────────── */
+	:global([data-register='arcane']) .hyvui-status-dot-pulse {
+		animation: sd-arcane-pulse 2s cubic-bezier(0.6, 0, 0.4, 1) infinite;
+	}
+
+	@keyframes sd-arcane-pulse {
+		0%        { box-shadow: 0 0 0 0 rgba(184, 69, 201, 0.6); opacity: 1; }
+		70%       { box-shadow: 0 0 0 5px rgba(184, 69, 201, 0); opacity: 0.85; }
+		100%      { box-shadow: 0 0 0 0 rgba(184, 69, 201, 0); opacity: 1; }
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		:global([data-register='hextech']) .hyvui-status-dot-pulse,
+		:global([data-register='arcane']) .hyvui-status-dot-pulse {
+			animation: none;
+		}
+	}
 </style>

package/dist/components/feedback/StatusDot.svelte.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @example
+ * <StatusDot status="ok" />
+ * <StatusDot status="pend" pulse={false} />
+ * <StatusDot status="fail" size={8} />
+ */
 interface Props {
     /** Status state determining the dot color. */
     status?: 'ok' | 'pend' | 'warn' | 'fail';

package/dist/components/feedback/StatusLine.svelte

@@ -1,6 +1,12 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * @example
+	 * <StatusLine status="ok" message="database connected" visible={true} />
+	 * <StatusLine status="pend" message="waiting for signal" visible={show} cursor />
+	 * <StatusLine status="fail" message="stream interrupted" visible={true} tone="line" />
+	 */
 	interface Props {
 		/** Status determining the glyph and color. */
 		status?: 'ok' | 'pend' | 'warn' | 'fail';
@@ -69,8 +75,8 @@
 		opacity: 0;
 		transform: translateY(6px);
 		transition:
-			opacity 0.5s cubic-bezier(0.22, 1, 0.36, 1),
-			transform 0.5s cubic-bezier(0.22, 1, 0.36, 1);
+			opacity var(--transition-smooth),
+			transform var(--transition-smooth);
 	}
 
 	.hyvui-status-line-visible {

package/dist/components/feedback/StatusLine.svelte.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @example
+ * <StatusLine status="ok" message="database connected" visible={true} />
+ * <StatusLine status="pend" message="waiting for signal" visible={show} cursor />
+ * <StatusLine status="fail" message="stream interrupted" visible={true} tone="line" />
+ */
 interface Props {
     /** Status determining the glyph and color. */
     status?: 'ok' | 'pend' | 'warn' | 'fail';

package/dist/components/feedback/Toast.svelte

@@ -29,6 +29,16 @@
 	import { cn } from '../../utils/cn.js';
 	import { flip } from 'svelte/animate';
 
+	/**
+	 * Place once in your root layout. Trigger toasts anywhere via `toastStore.push(message, variant)`.
+	 * Variants: 'ok' | 'pend' | 'warn' | 'fail'
+	 * @example
+	 * <Toast position="bottom-right" />
+	 * @example
+	 * toastStore.push('file saved', 'ok');
+	 * toastStore.push('connection lost', 'fail');
+	 * toastStore.push('uploading...', 'pend', 8000);
+	 */
 	interface Props {
 		/** Position of the toast stack. */
 		position?: 'bottom-right' | 'bottom-center';
@@ -40,8 +50,11 @@
 
 	let items: ToastItem[] = $state([]);
 
-	toastStore.subscribe((v) => {
-		items = v;
+	$effect(() => {
+		const unsub = toastStore.subscribe((v) => {
+			items = v;
+		});
+		return unsub;
 	});
 
 	const statusColorMap: Record<string, string> = {
@@ -95,6 +108,7 @@
 		align-items: center;
 		gap: 0.625rem;
 		pointer-events: auto;
+		backface-visibility: hidden;
 		animation: toast-in 0.35s cubic-bezier(0.22, 1, 0.36, 1);
 	}
 

package/dist/components/feedback/Toast.svelte.d.ts

@@ -10,6 +10,16 @@ export declare const toastStore: {
     /** Push a new toast notification. */
     push(message: string, variant?: "ok" | "pend" | "warn" | "fail", duration?: number): void;
 };
+/**
+ * Place once in your root layout. Trigger toasts anywhere via `toastStore.push(message, variant)`.
+ * Variants: 'ok' | 'pend' | 'warn' | 'fail'
+ * @example
+ * <Toast position="bottom-right" />
+ * @example
+ * toastStore.push('file saved', 'ok');
+ * toastStore.push('connection lost', 'fail');
+ * toastStore.push('uploading...', 'pend', 8000);
+ */
 interface Props {
     /** Position of the toast stack. */
     position?: 'bottom-right' | 'bottom-center';

package/dist/components/inputs/Button.svelte

@@ -3,6 +3,14 @@
 	import type { Snippet } from 'svelte';
 	import { echo as echoAction } from '../../system/actions/echo.js';
 
+	/**
+	 * @see echo — add `echo` prop (or `use:echo` directly) for a gold click-pulse ripple.
+	 * @example
+	 * <Button variant="primary" onclick={handleSubmit}>submit</Button>
+	 * <Button variant="ghost" href="/back">go back</Button>
+	 * <Button variant="destructive" loading>deleting...</Button>
+	 * <Button variant="primary" echo onclick={confirm}>confirm</Button>
+	 */
 	interface Props {
 		/** Button visual style. */
 		variant?: 'primary' | 'secondary' | 'ghost' | 'destructive';
@@ -123,9 +131,10 @@
 		justify-content: center;
 		gap: var(--control-gap);
 		transition:
-			color var(--transition-smooth),
-			border-color var(--transition-smooth),
-			background var(--transition-smooth),
+			color var(--transition-fast),
+			border-color var(--transition-fast),
+			background var(--transition-fast),
+			filter var(--transition-fast),
 			transform var(--transition-smooth),
 			box-shadow var(--transition-smooth);
 		white-space: nowrap;
@@ -221,7 +230,7 @@
 		height: 6px;
 		border-radius: 50%;
 		background-color: var(--status-pend);
-		animation: pulse-dot 2s ease-in-out infinite;
+		animation: pulse-dot 2s cubic-bezier(0.37, 0, 0.63, 1) infinite;
 	}
 
 	@media (prefers-reduced-motion: reduce) {
@@ -237,4 +246,65 @@
 			animation: none;
 		}
 	}
+
+	/* ── hextech ornament ─────────────────────────────────────────────── */
+	:global([data-register='hextech']) .hyvui-btn {
+		border-radius: var(--radius-sm);
+	}
+
+	/* brass corner pip — top-left notch */
+	:global([data-register='hextech']) .hyvui-btn::before {
+		content: '';
+		position: absolute;
+		top: 0;
+		left: 0;
+		width: 7px;
+		height: 7px;
+		border-top: 1.5px solid rgba(212, 165, 116, 0.55);
+		border-left: 1.5px solid rgba(212, 165, 116, 0.55);
+		pointer-events: none;
+	}
+
+	:global([data-register='hextech']) .hyvui-btn-primary:hover:not(:disabled):not(.hyvui-btn-disabled),
+	:global([data-register='hextech']) .hyvui-btn-primary:focus-visible {
+		box-shadow:
+			inset 0 1px 0 rgba(255, 255, 255, 0.2),
+			0 0 18px rgba(93, 217, 240, 0.3),
+			0 14px 26px rgba(184, 115, 51, 0.18);
+	}
+
+	:global([data-register='hextech']) .hyvui-btn-secondary:hover:not(:disabled):not(.hyvui-btn-disabled),
+	:global([data-register='hextech']) .hyvui-btn-secondary:focus-visible {
+		box-shadow: 0 0 12px rgba(93, 217, 240, 0.2);
+		border-color: rgba(93, 217, 240, 0.4);
+	}
+
+	/* ── arcane ornament ──────────────────────────────────────────────── */
+
+	/* crystal accent — top-right shard corner */
+	:global([data-register='arcane']) .hyvui-btn::after {
+		content: '';
+		position: absolute;
+		top: -1px;
+		right: -1px;
+		width: 8px;
+		height: 8px;
+		background: rgba(233, 76, 188, 0.55);
+		clip-path: polygon(100% 0, 100% 100%, 0 0);
+		pointer-events: none;
+	}
+
+	:global([data-register='arcane']) .hyvui-btn-primary:hover:not(:disabled):not(.hyvui-btn-disabled),
+	:global([data-register='arcane']) .hyvui-btn-primary:focus-visible {
+		box-shadow:
+			inset 0 1px 0 rgba(255, 255, 255, 0.14),
+			0 0 22px rgba(184, 69, 201, 0.38),
+			0 14px 26px rgba(184, 69, 201, 0.14);
+	}
+
+	:global([data-register='arcane']) .hyvui-btn-secondary:hover:not(:disabled):not(.hyvui-btn-disabled),
+	:global([data-register='arcane']) .hyvui-btn-secondary:focus-visible {
+		box-shadow: 0 0 14px rgba(184, 69, 201, 0.28);
+		border-color: rgba(184, 69, 201, 0.5);
+	}
 </style>

package/dist/components/inputs/Button.svelte.d.ts

@@ -1,4 +1,12 @@
 import type { Snippet } from 'svelte';
+/**
+ * @see echo — add `echo` prop (or `use:echo` directly) for a gold click-pulse ripple.
+ * @example
+ * <Button variant="primary" onclick={handleSubmit}>submit</Button>
+ * <Button variant="ghost" href="/back">go back</Button>
+ * <Button variant="destructive" loading>deleting...</Button>
+ * <Button variant="primary" echo onclick={confirm}>confirm</Button>
+ */
 interface Props {
     /** Button visual style. */
     variant?: 'primary' | 'secondary' | 'ghost' | 'destructive';

package/dist/components/inputs/Checkbox.svelte

@@ -1,6 +1,11 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * @example
+	 * <Checkbox label="accept terms" bind:checked={accepted} />
+	 * <Checkbox label="notify me" bind:checked={notify} onchange={handleChange} />
+	 */
 	interface Props {
 		/** Whether the checkbox is checked (bindable). */
 		checked?: boolean;

package/dist/components/inputs/Checkbox.svelte.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @example
+ * <Checkbox label="accept terms" bind:checked={accepted} />
+ * <Checkbox label="notify me" bind:checked={notify} onchange={handleChange} />
+ */
 interface Props {
     /** Whether the checkbox is checked (bindable). */
     checked?: boolean;

package/dist/components/inputs/FileUpload.svelte

@@ -1,6 +1,11 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * @example
+	 * <FileUpload accept="image/*" onfiles={handleImages} />
+	 * <FileUpload multiple accept=".csv,.json" onfiles={handleData} label="drop data files here" />
+	 */
 	interface Props {
 		/** Accepted file types (e.g. "image/*"). */
 		accept?: string;

package/dist/components/inputs/FileUpload.svelte.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @example
+ * <FileUpload accept="image/*" onfiles={handleImages} />
+ * <FileUpload multiple accept=".csv,.json" onfiles={handleData} label="drop data files here" />
+ */
 interface Props {
     /** Accepted file types (e.g. "image/*"). */
     accept?: string;

package/dist/components/inputs/Input.svelte

@@ -1,6 +1,13 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * @see resolve — wrap parent `<form>` with `use:resolve` to flash status on submit.
+	 * @example
+	 * <Input label="api key" bind:value={key} placeholder="sk-..." />
+	 * <Input label="email" type="email" bind:value={email} error={emailError} />
+	 * <Input label="search" type="search" bind:value={query} hint="press enter to search" />
+	 */
 	interface Props {
 		/** Input type. */
 		type?: 'text' | 'number' | 'password' | 'email' | 'search';
@@ -50,14 +57,15 @@
 		bind:value
 		{placeholder}
 		{disabled}
+		aria-describedby={(error || hint) ? `${inputId}-desc` : undefined}
 		class={cn('hyvui-input', error && 'hyvui-input-error')}
 		{oninput}
 		{onchange}
 	/>
 	{#if error}
-		<span class="hyvui-input-message hyvui-input-message-error">{error}</span>
+		<span id="{inputId}-desc" class="hyvui-input-message hyvui-input-message-error">{error}</span>
 	{:else if hint}
-		<span class="hyvui-input-message">{hint}</span>
+		<span id="{inputId}-desc" class="hyvui-input-message">{hint}</span>
 	{/if}
 </div>
 

package/dist/components/inputs/Input.svelte.d.ts

@@ -1,3 +1,10 @@
+/**
+ * @see resolve — wrap parent `<form>` with `use:resolve` to flash status on submit.
+ * @example
+ * <Input label="api key" bind:value={key} placeholder="sk-..." />
+ * <Input label="email" type="email" bind:value={email} error={emailError} />
+ * <Input label="search" type="search" bind:value={query} hint="press enter to search" />
+ */
 interface Props {
     /** Input type. */
     type?: 'text' | 'number' | 'password' | 'email' | 'search';

package/dist/components/inputs/Select.svelte

@@ -6,6 +6,14 @@
 		label: string;
 	}
 
+	/**
+	 * @example
+	 * <Select label="region" bind:value={region} options={[
+	 *   { value: 'us', label: 'united states' },
+	 *   { value: 'eu', label: 'europe' }
+	 * ]} />
+	 * <Select label="status" bind:value={status} options={statusOptions} error={statusError} />
+	 */
 	interface Props {
 		/** Available options. */
 		options?: SelectOption[];

package/dist/components/inputs/Select.svelte.d.ts

@@ -2,6 +2,14 @@ interface SelectOption {
     value: string;
     label: string;
 }
+/**
+ * @example
+ * <Select label="region" bind:value={region} options={[
+ *   { value: 'us', label: 'united states' },
+ *   { value: 'eu', label: 'europe' }
+ * ]} />
+ * <Select label="status" bind:value={status} options={statusOptions} error={statusError} />
+ */
 interface Props {
     /** Available options. */
     options?: SelectOption[];

package/dist/components/inputs/Textarea.svelte

@@ -1,6 +1,12 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * @see resolve — wrap parent `<form>` with `use:resolve` to flash status on submit.
+	 * @example
+	 * <Textarea label="notes" bind:value={notes} placeholder="enter notes..." />
+	 * <Textarea label="message" rows={6} bind:value={msg} autoresize error={msgError} />
+	 */
 	interface Props {
 		/** Current value (bindable). */
 		value?: string;
@@ -61,13 +67,14 @@
 		{rows}
 		{placeholder}
 		{disabled}
+		aria-describedby={(error || hint) ? `${textareaId}-desc` : undefined}
 		class={cn('hyvui-textarea', error && 'hyvui-textarea-error')}
 		oninput={handleInput}
 	></textarea>
 	{#if error}
-		<span class="hyvui-textarea-message hyvui-textarea-message-error">{error}</span>
+		<span id="{textareaId}-desc" class="hyvui-textarea-message hyvui-textarea-message-error">{error}</span>
 	{:else if hint}
-		<span class="hyvui-textarea-message">{hint}</span>
+		<span id="{textareaId}-desc" class="hyvui-textarea-message">{hint}</span>
 	{/if}
 </div>
 

package/dist/components/inputs/Textarea.svelte.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @see resolve — wrap parent `<form>` with `use:resolve` to flash status on submit.
+ * @example
+ * <Textarea label="notes" bind:value={notes} placeholder="enter notes..." />
+ * <Textarea label="message" rows={6} bind:value={msg} autoresize error={msgError} />
+ */
 interface Props {
     /** Current value (bindable). */
     value?: string;

package/dist/components/inputs/Toggle.svelte

@@ -1,6 +1,11 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * @example
+	 * <Toggle label="enable notifications" bind:checked={enabled} />
+	 * <Toggle label="dark mode" bind:checked={dark} onchange={applyTheme} />
+	 */
 	interface Props {
 		/** Whether the toggle is on (bindable). */
 		checked?: boolean;
@@ -95,7 +100,7 @@
 		border-radius: 50%;
 		background-color: var(--muted);
 		transition:
-			transform var(--transition-fast),
+			transform var(--transition-smooth),
 			background-color var(--transition-fast);
 	}
 

package/dist/components/inputs/Toggle.svelte.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @example
+ * <Toggle label="enable notifications" bind:checked={enabled} />
+ * <Toggle label="dark mode" bind:checked={dark} onchange={applyTheme} />
+ */
 interface Props {
     /** Whether the toggle is on (bindable). */
     checked?: boolean;

package/dist/components/layout/Card.svelte

@@ -3,6 +3,17 @@
 	import Surface from '../primitives/Surface.svelte';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * @see surface — add `use:surface` on Card for an entrance animation on mount.
+	 * @see reveal — add `use:reveal={{ target: '.meta' }}` on the Card for hover-reveal of child elements.
+	 * @example
+	 * <Card>
+	 *   {#snippet header()}<Label>project alpha</Label>{/snippet}
+	 *   <Text>card body content here.</Text>
+	 *   {#snippet footer()}<Button variant="ghost" size="sm">view details</Button>{/snippet}
+	 * </Card>
+	 * <Card staggerOffset="1.2rem">offset card in a grid</Card>
+	 */
 	interface Props {
 		/** TranslateY offset for staggered card grids. */
 		staggerOffset?: string;

package/dist/components/layout/Card.svelte.d.ts

@@ -1,4 +1,15 @@
 import type { Snippet } from 'svelte';
+/**
+ * @see surface — add `use:surface` on Card for an entrance animation on mount.
+ * @see reveal — add `use:reveal={{ target: '.meta' }}` on the Card for hover-reveal of child elements.
+ * @example
+ * <Card>
+ *   {#snippet header()}<Label>project alpha</Label>{/snippet}
+ *   <Text>card body content here.</Text>
+ *   {#snippet footer()}<Button variant="ghost" size="sm">view details</Button>{/snippet}
+ * </Card>
+ * <Card staggerOffset="1.2rem">offset card in a grid</Card>
+ */
 interface Props {
     /** TranslateY offset for staggered card grids. */
     staggerOffset?: string;

package/dist/components/layout/Drawer.svelte

@@ -4,6 +4,12 @@
 	import Surface from '../primitives/Surface.svelte';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * @example
+	 * <Drawer open={showDrawer} side="right" onclose={() => showDrawer = false}>
+	 *   <SidebarNav items={navItems} />
+	 * </Drawer>
+	 */
 	interface Props {
 		/** Controls drawer visibility. */
 		open?: boolean;
@@ -86,6 +92,7 @@
 		z-index: var(--z-modal);
 		inline-size: min(var(--hyvui-drawer-w, 320px), 100dvw);
 		max-inline-size: 100dvw;
+		backface-visibility: hidden;
 	}
 
 	.hyvui-drawer-left {

package/dist/components/layout/Drawer.svelte.d.ts

@@ -1,4 +1,10 @@
 import type { Snippet } from 'svelte';
+/**
+ * @example
+ * <Drawer open={showDrawer} side="right" onclose={() => showDrawer = false}>
+ *   <SidebarNav items={navItems} />
+ * </Drawer>
+ */
 interface Props {
     /** Controls drawer visibility. */
     open?: boolean;

package/dist/components/layout/Grid.svelte

@@ -2,6 +2,16 @@
 	import { cn } from '../../utils/cn.js';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * @example
+	 * <Grid minColWidth="18rem" maxCols={3}>
+	 *   {#each items as item}<Card>{item.name}</Card>{/each}
+	 * </Grid>
+	 * <Grid mode="template" cols="1fr 2fr">
+	 *   <aside>sidebar</aside>
+	 *   <main>content</main>
+	 * </Grid>
+	 */
 	interface Props {
 		/** Grid mode. `auto` computes columns from container width. */
 		mode?: 'auto' | 'template';

package/dist/components/layout/Grid.svelte.d.ts

@@ -1,4 +1,14 @@
 import type { Snippet } from 'svelte';
+/**
+ * @example
+ * <Grid minColWidth="18rem" maxCols={3}>
+ *   {#each items as item}<Card>{item.name}</Card>{/each}
+ * </Grid>
+ * <Grid mode="template" cols="1fr 2fr">
+ *   <aside>sidebar</aside>
+ *   <main>content</main>
+ * </Grid>
+ */
 interface Props {
     /** Grid mode. `auto` computes columns from container width. */
     mode?: 'auto' | 'template';

package/dist/components/layout/Modal.svelte

@@ -4,6 +4,16 @@
 	import Surface from '../primitives/Surface.svelte';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * @example
+	 * <Modal open={showModal} title="confirm action" onclose={() => showModal = false}>
+	 *   <Text>are you sure you want to proceed?</Text>
+	 *   {#snippet footer()}
+	 *     <Button variant="primary" onclick={confirm}>proceed</Button>
+	 *     <Button variant="ghost" onclick={() => showModal = false}>cancel</Button>
+	 *   {/snippet}
+	 * </Modal>
+	 */
 	interface Props {
 		/** Controls modal visibility. */
 		open?: boolean;
@@ -32,13 +42,17 @@
 	}: Props = $props();
 
 	let dialogEl: HTMLDialogElement | undefined = $state();
+	let previousFocus: Element | null = null;
 
 	$effect(() => {
 		if (!dialogEl) return;
 		if (open) {
+			previousFocus = document.activeElement;
 			if (!dialogEl.open) dialogEl.showModal();
 		} else {
 			if (dialogEl.open) dialogEl.close();
+			if (previousFocus instanceof HTMLElement) previousFocus.focus();
+			previousFocus = null;
 		}
 	});
 
@@ -121,6 +135,7 @@
 		display: flex;
 		flex-direction: column;
 		min-height: 0;
+		backface-visibility: hidden;
 		animation: modal-in 0.35s cubic-bezier(0.22, 1, 0.36, 1);
 	}
 

package/dist/components/layout/Modal.svelte.d.ts

@@ -1,4 +1,14 @@
 import type { Snippet } from 'svelte';
+/**
+ * @example
+ * <Modal open={showModal} title="confirm action" onclose={() => showModal = false}>
+ *   <Text>are you sure you want to proceed?</Text>
+ *   {#snippet footer()}
+ *     <Button variant="primary" onclick={confirm}>proceed</Button>
+ *     <Button variant="ghost" onclick={() => showModal = false}>cancel</Button>
+ *   {/snippet}
+ * </Modal>
+ */
 interface Props {
     /** Controls modal visibility. */
     open?: boolean;

package/dist/components/layout/Panel.svelte

@@ -3,6 +3,15 @@
 	import Surface from '../primitives/Surface.svelte';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * @see surface — add `use:surface` on Panel for an entrance animation on mount.
+	 * @example
+	 * <Panel>
+	 *   {#snippet header()}<Label color="accent">system status</Label>{/snippet}
+	 *   <StatusDot status="ok" />
+	 * </Panel>
+	 * <Panel withInset>panel with teal inset border</Panel>
+	 */
 	interface Props {
 		/** Adds a pseudoelement teal inset border. */
 		withInset?: boolean;

package/dist/components/layout/Panel.svelte.d.ts

@@ -1,4 +1,13 @@
 import type { Snippet } from 'svelte';
+/**
+ * @see surface — add `use:surface` on Panel for an entrance animation on mount.
+ * @example
+ * <Panel>
+ *   {#snippet header()}<Label color="accent">system status</Label>{/snippet}
+ *   <StatusDot status="ok" />
+ * </Panel>
+ * <Panel withInset>panel with teal inset border</Panel>
+ */
 interface Props {
     /** Adds a pseudoelement teal inset border. */
     withInset?: boolean;