entasis 0.8.0 → 0.9.1

package/README.md

@@ -320,7 +320,13 @@ Snippet props: `size` (px number or CSS length, default `1lh`), `color` (a role
 
 - `pnpm dev` runs the documentation site with a page per component under `/components/<name>`.
 - `.claude/skills/entasis/` (mirrored in `.agents/skills/entasis/`) holds the coding-agent skill: import conventions, per-component references, theming notes.
-- Each component folder ships a `*.mcp.ts` description used by the MCP integration.
+- Each component folder ships a `*.mcp.ts` description, served by the MCP server the docs site runs at
+  `https://entasis.beynar.workers.dev/mcp` (one `components` tool that returns a component's documentation).
+  Add it to a project for Claude Code with:
+
+  ```bash
+  claude mcp add --transport http --scope project entasis https://entasis.beynar.workers.dev/mcp
+  ```
 
 ## Releasing
 

package/dist/components/AppShell/appShell.theme.js

@@ -42,8 +42,8 @@ const defaultPage = cva({
         variant: {
             admin: 'bg-surface [--page-shell-chrome:var(--color-surface-canvas)] [--page-shell-surface:var(--color-surface)]',
             floating: 'bg-surface-canvas [--page-shell-chrome:var(--color-surface)] [--page-shell-surface:var(--color-surface-canvas)] [--page-shell-chrome-inline-gap:0.5rem] [--page-shell-chrome-block-gap:0.5rem] [--page-shell-header-top-radius:var(--radius-lg)] [--page-shell-header-bottom-radius:var(--radius-lg)] [--page-shell-footer-top-radius:var(--radius-lg)] [--page-shell-footer-bottom-radius:var(--radius-lg)] [--page-shell-chrome-border:var(--color-neutral-muted)] [--page-shell-chrome-shadow:var(--elevation-1)]',
-            inset: 'bg-surface [--page-shell-chrome:var(--color-surface)] [--page-shell-surface:var(--color-surface)] transition-[border-color,box-shadow] md:raised-1 md:group-data-[display-state=hidden]/sidebar-wrapper:border-transparent md:group-data-[display-state=hidden]/sidebar-wrapper:shadow-none',
-            split: 'bg-surface [--page-shell-chrome:var(--color-surface)] [--page-shell-surface:var(--color-surface)] transition-[border-color,box-shadow] md:raised-1 md:group-data-[display-state=hidden]/sidebar-wrapper:border-transparent md:group-data-[display-state=hidden]/sidebar-wrapper:shadow-none',
+            inset: 'bg-surface [--page-shell-chrome:var(--color-surface)] [--page-shell-surface:var(--color-surface)] transition-[border-color,box-shadow] md:raised-1 md:group-data-[page-flush=true]/sidebar-wrapper:border-transparent md:group-data-[page-flush=true]/sidebar-wrapper:shadow-none',
+            split: 'bg-surface [--page-shell-chrome:var(--color-surface)] [--page-shell-surface:var(--color-surface)] transition-[border-color,box-shadow] md:raised-1 md:group-data-[page-flush=true]/sidebar-wrapper:border-transparent md:group-data-[page-flush=true]/sidebar-wrapper:shadow-none',
             // The frame already owns the radius, border and elevation, so the page inside it is flat,
             // and its header chrome is the same surface as the content: the white column is one
             // piece whose only corners are the frame's own.
@@ -54,6 +54,21 @@ const defaultPage = cva({
             right: ''
         }
     },
+    compoundVariants: [
+        // A floating panel column pads its page side, which already spaces the panel card from the
+        // page's header and footer cards: their own inset on that side would double the gap. A
+        // hidden panel leaves the rail (or the screen edge) beside the page, so the inset returns.
+        {
+            variant: 'floating',
+            side: 'left',
+            class: 'md:[--page-shell-chrome-left-gap:0px] md:group-data-[display-state=hidden]/sidebar-wrapper:[--page-shell-chrome-left-gap:0.5rem]'
+        },
+        {
+            variant: 'floating',
+            side: 'right',
+            class: 'md:[--page-shell-chrome-right-gap:0px] md:group-data-[display-state=hidden]/sidebar-wrapper:[--page-shell-chrome-right-gap:0.5rem]'
+        }
+    ],
     defaultVariants: {
         variant: 'admin',
         side: 'left'

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

@@ -634,6 +634,7 @@ export declare class FormState<I extends FormInputs = FormInputs> {
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {
@@ -1405,6 +1406,7 @@ export declare class FormState<I extends FormInputs = FormInputs> {
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {
@@ -2210,6 +2212,7 @@ export declare class FormState<I extends FormInputs = FormInputs> {
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {
@@ -2981,6 +2984,7 @@ export declare class FormState<I extends FormInputs = FormInputs> {
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {

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

@@ -3349,6 +3349,7 @@ export declare function prepareInputProps(input: FormFieldInput, size: Sizes, la
     focused?: boolean | undefined;
     i18n?: Partial<import("../../../i18n/en.js").Messages> | undefined;
     separators?: boolean | undefined;
+    alignItemWithTrigger?: boolean | undefined;
     triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes | undefined;
     display?: string;
 } | {
@@ -8972,6 +8973,7 @@ export declare function prepareInputProps(input: FormFieldInput, size: Sizes, la
     focused?: boolean | undefined;
     i18n?: Partial<import("../../../i18n/en.js").Messages> | undefined;
     separators?: boolean | undefined;
+    alignItemWithTrigger?: boolean | undefined;
     triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes | undefined;
     display?: string;
 } | {

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

@@ -614,6 +614,7 @@ export declare class MultiStepFormState<I extends MultiStepFormItems = FormStep[
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {
@@ -1385,6 +1386,7 @@ export declare class MultiStepFormState<I extends MultiStepFormItems = FormStep[
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {
@@ -2190,6 +2192,7 @@ export declare class MultiStepFormState<I extends MultiStepFormItems = FormStep[
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {
@@ -2961,6 +2964,7 @@ export declare class MultiStepFormState<I extends MultiStepFormItems = FormStep[
         items?: import("../Select/select.props.js").SelectItems;
         density?: import("../../../types/theme.js").Density;
         separators?: boolean;
+        alignItemWithTrigger?: boolean;
         triggerAttrs?: import("../Select/select.props.js").SelectTriggerAttributes;
         i18n?: Partial<import("../../../i18n/en.js").Messages>;
     }, "visible"> & {

package/dist/components/Form/Select/Select.svelte

@@ -30,6 +30,7 @@
 		visible,
 		items,
 		separators = true,
+		alignItemWithTrigger = true,
 		triggerAttrs,
 		label,
 		...rest
@@ -37,6 +38,9 @@
 	if (value === undefined) value = untrack(() => defaultValue);
 
 	const id = $props.id();
+	let valueEl = $state<HTMLElement | null>(null);
+	let listEl = $state<HTMLDivElement | null>(null);
+	let viewportEl = $state<HTMLDivElement | null>(null);
 	const t = $derived(useI18n(i18n));
 
 	const field = createFieldState({
@@ -105,6 +109,18 @@
 		},
 		set triggerEl(_) {
 			// field.node is owned by the bind:this below.
+		},
+		get alignItemWithTrigger() {
+			return alignItemWithTrigger;
+		},
+		get valueEl() {
+			return valueEl;
+		},
+		get listEl() {
+			return listEl;
+		},
+		get viewportEl() {
+			return viewportEl;
 		}
 	});
 
@@ -121,6 +137,7 @@
 	fitTrigger
 	position="bottom"
 	ref={field.node?.parentElement}
+	positionPanel={select.positionPanel}
 	size="small"
 	transition={{
 		in: { scale: 1, opacity: 0 },
@@ -143,7 +160,13 @@
 			event.preventDefault();
 		}}
 	>
-		<ScrollArea scrollOnEdges type="auto" class="flex max-h-[240px] flex-col">
+		<ScrollArea
+			bind:ref={listEl}
+			bind:viewportRef={viewportEl}
+			scrollOnEdges
+			type="auto"
+			class="flex max-h-[240px] flex-col"
+		>
 			{#each select.renderGroups as group, groupIndex (groupIndex)}
 				{#if separators && groupIndex > 0}
 					<div role="separator" class={classes.separator({ size })}></div>
@@ -230,7 +253,10 @@
 					triggerAttrs?.onblur?.(event);
 				}}
 			>
-				<span class={classes.value({ size, placeholder: !select.selectedOption })}>
+				<span
+					bind:this={valueEl}
+					class={classes.value({ size, placeholder: !select.selectedOption })}
+				>
 					{select.selectedOption?.label ?? placeholder ?? t.selectOption}
 				</span>
 				{@render caretDownIcon({ class: classes.triggerIcon({ size }) })}

package/dist/components/Form/Select/select.align.d.ts

@@ -0,0 +1,55 @@
+/** Distance kept between an item-aligned panel and the viewport edges, in px. */
+export declare const SELECT_ALIGN_MARGIN = 8;
+/**
+ * Viewport measurements of an open Select, taken with the option list at its natural height and
+ * scrolled to the top. `textStart` values are the inline-start edge of the text (left in LTR,
+ * right in RTL).
+ */
+export type SelectAlignMetrics = {
+    viewport: {
+        width: number;
+        height: number;
+    };
+    trigger: {
+        top: number;
+        height: number;
+    };
+    /** The trigger's value (or placeholder) text. */
+    valueTextStart: number;
+    panel: {
+        left: number;
+        right: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    /** The scrolling option list inside the panel. */
+    list: {
+        top: number;
+        height: number;
+    };
+    /** The option to put on the trigger: the selected one, else the first. */
+    item: {
+        top: number;
+        height: number;
+        textStart: number;
+    };
+    rtl: boolean;
+};
+export type SelectAlignment = {
+    /** Panel position, viewport coordinates. */
+    x: number;
+    y: number;
+    /** Height to cap the option list at. */
+    listHeight: number;
+    /** Scroll offset that keeps the option on the trigger. */
+    scrollTop: number;
+};
+/**
+ * Item-aligned placement, the native select's and Radix's: the panel covers the trigger with the
+ * option's middle on the trigger's middle and its text on the value text. A panel that would cross
+ * the top edge is pinned there and its list scrolled by the overflow, so the option stays on the
+ * trigger; one that would cross the bottom edge is cut short and scrolls. Only when the trigger
+ * sits so low that fewer than four rows would fit does the panel rise and give up the alignment.
+ */
+export declare function alignItemWithTrigger(m: SelectAlignMetrics): SelectAlignment;

package/dist/components/Form/Select/select.align.js

@@ -0,0 +1,41 @@
+/** Distance kept between an item-aligned panel and the viewport edges, in px. */
+export const SELECT_ALIGN_MARGIN = 8;
+const clamp = (value, min, max) => Math.min(Math.max(value, min), Math.max(min, max));
+/**
+ * Item-aligned placement, the native select's and Radix's: the panel covers the trigger with the
+ * option's middle on the trigger's middle and its text on the value text. A panel that would cross
+ * the top edge is pinned there and its list scrolled by the overflow, so the option stays on the
+ * trigger; one that would cross the bottom edge is cut short and scrolls. Only when the trigger
+ * sits so low that fewer than four rows would fit does the panel rise and give up the alignment.
+ */
+export function alignItemWithTrigger(m) {
+    const top = SELECT_ALIGN_MARGIN;
+    const bottom = m.viewport.height - SELECT_ALIGN_MARGIN;
+    const chromeAbove = m.list.top - m.panel.top;
+    const chromeBelow = m.panel.top + m.panel.height - (m.list.top + m.list.height);
+    const itemMiddle = m.item.top + m.item.height / 2 - m.panel.top;
+    const triggerMiddle = m.trigger.top + m.trigger.height / 2;
+    let y = triggerMiddle - itemMiddle;
+    let scrollTop = 0;
+    if (y < top) {
+        scrollTop = top - y;
+        y = top;
+    }
+    let height = Math.min(m.panel.height - scrollTop, bottom - y);
+    const minHeight = Math.min(m.panel.height, chromeAbove + chromeBelow + m.item.height * 4);
+    if (height < minHeight) {
+        height = minHeight;
+        y = Math.max(top, bottom - height);
+    }
+    const listHeight = Math.max(0, height - chromeAbove - chromeBelow);
+    scrollTop = clamp(scrollTop, 0, m.list.height - listHeight);
+    // Line the option's text up with the value's: the panel moves by the gap between them.
+    const textOffset = m.rtl ? m.panel.right - m.item.textStart : m.item.textStart - m.panel.left;
+    const x = m.rtl ? m.valueTextStart + textOffset - m.panel.width : m.valueTextStart - textOffset;
+    return {
+        x: clamp(x, SELECT_ALIGN_MARGIN, m.viewport.width - SELECT_ALIGN_MARGIN - m.panel.width),
+        y,
+        listHeight,
+        scrollTop
+    };
+}

package/dist/components/Form/Select/select.mcp.d.ts

@@ -1 +1 @@
-export declare const selectDescription = "\n# Select Component\n\nA custom (non-native) dropdown selection field: a combobox trigger opening a listbox popover,\nwith full keyboard navigation, grouped options, and Field/Form integration.\n\n## Basic Usage\n\n```svelte\n<Select\n\tlabel=\"Country\"\n\tbind:value={country}\n\titems={[\n\t\t{ value: 'us', label: 'United States' },\n\t\t{ value: 'uk', label: 'United Kingdom' },\n\t\t{ value: 'ca', label: 'Canada' }\n\t]}\n/>\n```\n\n## Grouped options\n\nFlat options and `{ label, items }` groups can be mixed freely; separators render between groups.\n\n```svelte\n<Select\n\tlabel=\"Timezone\"\n\tbind:value={tz}\n\titems={[\n\t\t{ label: 'Europe', items: [{ value: 'paris', label: 'Paris' }, { value: 'berlin', label: 'Berlin' }] },\n\t\t{ label: 'America', items: [{ value: 'nyc', label: 'New York' }, { value: 'la', label: 'Los Angeles' }] }\n\t]}\n/>\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: string (bindable) - Selected value\n- **items**: (SelectOption | SelectOptionGroup)[] - Flat `{ value, label, disabled? }` options and/or `{ label, items }` groups\n- **placeholder**: string (default: 'Select an option') - Trigger text when no selection\n- **separators**: boolean (default: true) - Render separators between consecutive groups\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label, and the trigger's accessible name; without it the trigger falls back to the placeholder\n- **description**: string | Snippet - Helper text\n- **required**: boolean - Mark as required\n- **disabled**: boolean - Disable the trigger\n- **size**: 'small' | 'normal' | 'large' - Trigger and dropdown size\n- **density**: 'compact' | 'normal' | 'comfortable' (default: 'normal') - Spacing density forwarded to the dropdown option rows (paddings, gaps, min-height)\n- **name**: string - Form field name; also renders a hidden input for native form posts\n\n### Bindable Props\n- **value**: string - Selected value\n- **errors**: string[] - Validation errors\n- **focused**: boolean - Trigger focus state\n\n### Callbacks\n- **onValueChange**: (value) => void - Fires when the selection changes\n- **onValidate**: (value) => string[] | boolean - Custom validation\n\n### Advanced Props\n- **theme**: SelectThemeProps - Theme overrides (input, inputContainer, value, triggerIcon, content, group, groupLabel, item, itemIndicator, separator)\n\n## Keyboard\n\n- Closed: ArrowDown / ArrowUp / Enter / Space open the dropdown, anchored on the selected option\n- Open: ArrowDown / ArrowUp move the highlight (wrap-around), Home / End jump, Enter / Space select, Escape closes, Tab closes and moves focus on\n- Type-ahead: typing letters while the trigger has focus moves the highlight to the next option whose label starts with the typed text\n- Disabled options are skipped by the highlight\n\n## Accessibility\n\nARIA 1.2 select-only combobox pattern: the trigger is a `role=\"combobox\"` button with\n`aria-haspopup=\"listbox\"`, `aria-expanded`, and `aria-controls`; DOM focus stays on the\ntrigger while `aria-activedescendant` tracks the highlighted `role=\"option\"` (virtual focus).\nThe selected option shows a check indicator and `aria-selected`.\n\nThe trigger always has an accessible name: `label` names it through the Field label (a string\nlabel as a `<label for>`, a snippet through `aria-labelledby`), and without one the trigger\nfalls back to `placeholder`, then to the catalog's \"Select an option\". Pass `label` whenever\nan unlabelled select sits in a toolbar or filter row, so the name says which control it is\nrather than repeating the placeholder.\n\n## Notes\n\n- Selection re-focuses the trigger (matches native select behavior)\n- Clicking outside closes via trigger blur; option rows prevent mousedown so the click can land\n- The dropdown scrolls beyond ~240px (ScrollArea); the highlight scrolls into view on keyboard nav\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";
+export declare const selectDescription = "\n# Select Component\n\nA custom (non-native) selection field: a combobox trigger opening a listbox popover, with full\nkeyboard navigation, grouped options, and Field/Form integration. Like a native select (and\nRadix's item-aligned or Base UI's `alignItemWithTrigger` position), the listbox opens over the\ntrigger with the selected option sitting on the value.\n\n## Basic Usage\n\n```svelte\n<Select\n\tlabel=\"Country\"\n\tbind:value={country}\n\titems={[\n\t\t{ value: 'us', label: 'United States' },\n\t\t{ value: 'uk', label: 'United Kingdom' },\n\t\t{ value: 'ca', label: 'Canada' }\n\t]}\n/>\n```\n\n## Grouped options\n\nFlat options and `{ label, items }` groups can be mixed freely; separators render between groups.\n\n```svelte\n<Select\n\tlabel=\"Timezone\"\n\tbind:value={tz}\n\titems={[\n\t\t{ label: 'Europe', items: [{ value: 'paris', label: 'Paris' }, { value: 'berlin', label: 'Berlin' }] },\n\t\t{ label: 'America', items: [{ value: 'nyc', label: 'New York' }, { value: 'la', label: 'Los Angeles' }] }\n\t]}\n/>\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: string (bindable) - Selected value\n- **items**: (SelectOption | SelectOptionGroup)[] - Flat `{ value, label, disabled? }` options and/or `{ label, items }` groups\n- **placeholder**: string (default: 'Select an option') - Trigger text when no selection\n- **separators**: boolean (default: true) - Render separators between consecutive groups\n- **alignItemWithTrigger**: boolean (default: true) - Open over the trigger with the selected option (the first enabled one when nothing is selected) on the trigger's middle and its text on the value text. A list taller than the viewport is capped 8px from the edges and pre-scrolled so the option stays on the trigger; a trigger too close to the bottom for four rows gives up the alignment and the panel rises into view. Wheel and touch scrolling outside the panel are blocked while it is open, so the trigger cannot move away from it. `false` opens a dropdown below the trigger instead, capped at ~240px\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label, and the trigger's accessible name; without it the trigger falls back to the placeholder\n- **description**: string | Snippet - Helper text\n- **required**: boolean - Mark as required\n- **disabled**: boolean - Disable the trigger\n- **size**: 'small' | 'normal' | 'large' - Trigger and dropdown size\n- **density**: 'compact' | 'normal' | 'comfortable' (default: 'normal') - Spacing density forwarded to the dropdown option rows (paddings, gaps, min-height)\n- **name**: string - Form field name; also renders a hidden input for native form posts\n\n### Bindable Props\n- **value**: string - Selected value\n- **errors**: string[] - Validation errors\n- **focused**: boolean - Trigger focus state\n\n### Callbacks\n- **onValueChange**: (value) => void - Fires when the selection changes\n- **onValidate**: (value) => string[] | boolean - Custom validation\n\n### Advanced Props\n- **theme**: SelectThemeProps - Theme overrides (input, inputContainer, value, triggerIcon, content, group, groupLabel, item, itemIndicator, separator)\n\n## Keyboard\n\n- Closed: ArrowDown / ArrowUp / Enter / Space open the dropdown, anchored on the selected option\n- Open: ArrowDown / ArrowUp move the highlight (wrap-around), Home / End jump, Enter / Space select, Escape closes, Tab closes and moves focus on\n- Type-ahead: typing letters while the trigger has focus moves the highlight to the next option whose label starts with the typed text\n- Disabled options are skipped by the highlight\n\n## Accessibility\n\nARIA 1.2 select-only combobox pattern: the trigger is a `role=\"combobox\"` button with\n`aria-haspopup=\"listbox\"`, `aria-expanded`, and `aria-controls`; DOM focus stays on the\ntrigger while `aria-activedescendant` tracks the highlighted `role=\"option\"` (virtual focus).\nThe selected option shows a check indicator and `aria-selected`.\n\nThe trigger always has an accessible name: `label` names it through the Field label (a string\nlabel as a `<label for>`, a snippet through `aria-labelledby`), and without one the trigger\nfalls back to `placeholder`, then to the catalog's \"Select an option\". Pass `label` whenever\nan unlabelled select sits in a toolbar or filter row, so the name says which control it is\nrather than repeating the placeholder.\n\n## Notes\n\n- Selection re-focuses the trigger (matches native select behavior)\n- Clicking outside closes via trigger blur; option rows prevent mousedown so the click can land\n- The list scrolls (ScrollArea) beyond the viewport when item-aligned, beyond ~240px as a dropdown; the highlight scrolls into view on keyboard nav\n- The panel covers the trigger while open, so clicking outside (not the trigger) closes it, as with a native select\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";

package/dist/components/Form/Select/select.mcp.js

@@ -1,8 +1,10 @@
 export const selectDescription = `
 # Select Component
 
-A custom (non-native) dropdown selection field: a combobox trigger opening a listbox popover,
-with full keyboard navigation, grouped options, and Field/Form integration.
+A custom (non-native) selection field: a combobox trigger opening a listbox popover, with full
+keyboard navigation, grouped options, and Field/Form integration. Like a native select (and
+Radix's item-aligned or Base UI's \`alignItemWithTrigger\` position), the listbox opens over the
+trigger with the selected option sitting on the value.
 
 ## Basic Usage
 
@@ -42,6 +44,7 @@ Extends all Field component props plus:
 - **items**: (SelectOption | SelectOptionGroup)[] - Flat \`{ value, label, disabled? }\` options and/or \`{ label, items }\` groups
 - **placeholder**: string (default: 'Select an option') - Trigger text when no selection
 - **separators**: boolean (default: true) - Render separators between consecutive groups
+- **alignItemWithTrigger**: boolean (default: true) - Open over the trigger with the selected option (the first enabled one when nothing is selected) on the trigger's middle and its text on the value text. A list taller than the viewport is capped 8px from the edges and pre-scrolled so the option stays on the trigger; a trigger too close to the bottom for four rows gives up the alignment and the panel rises into view. Wheel and touch scrolling outside the panel are blocked while it is open, so the trigger cannot move away from it. \`false\` opens a dropdown below the trigger instead, capped at ~240px
 
 ### Field Props (inherited)
 - **label**: string | Snippet - Field label, and the trigger's accessible name; without it the trigger falls back to the placeholder
@@ -88,7 +91,8 @@ rather than repeating the placeholder.
 
 - Selection re-focuses the trigger (matches native select behavior)
 - Clicking outside closes via trigger blur; option rows prevent mousedown so the click can land
-- The dropdown scrolls beyond ~240px (ScrollArea); the highlight scrolls into view on keyboard nav
+- The list scrolls (ScrollArea) beyond the viewport when item-aligned, beyond ~240px as a dropdown; the highlight scrolls into view on keyboard nav
+- The panel covers the trigger while open, so clicking outside (not the trigger) closes it, as with a native select
 
 ## State contract
 

package/dist/components/Form/Select/select.props.d.ts

@@ -34,6 +34,14 @@ export type SelectProps = InputProps<'select'> & {
     density?: Density;
     /** Render separators between consecutive groups. */
     separators?: boolean;
+    /**
+     * Open over the trigger with the selected option (or the first, when nothing is selected) on
+     * the value, its text lined up with the value's, like a native select. A list taller than the
+     * viewport is capped and pre-scrolled to keep the option there. `false` opens a dropdown below
+     * the trigger instead.
+     * @default true
+     */
+    alignItemWithTrigger?: boolean;
     /** Native attributes applied to the combobox trigger button. */
     triggerAttrs?: SelectTriggerAttributes;
     /** Per-instance i18n overrides merged over the global catalog. */

package/dist/components/Form/Select/select.state.svelte.d.ts

@@ -8,13 +8,24 @@ interface SelectStateOptions {
     disabled: boolean | undefined;
     /** The trigger button — reactive getter bridged to `field.node`, refocused after selection. */
     triggerEl: HTMLElement | null;
+    /** Open over the trigger with the selected option on the value, like a native select. */
+    alignItemWithTrigger: boolean;
+    /** The trigger's value text, the option list root, and its scrolling viewport. */
+    valueEl: HTMLElement | null;
+    listEl: HTMLElement | null;
+    viewportEl: HTMLElement | null;
 }
 export declare class SelectState {
+    #private;
     id: string;
     items: SelectItems | undefined;
     value: string | null | undefined;
     disabled: boolean | undefined;
     triggerEl: HTMLElement | null;
+    alignItemWithTrigger: boolean;
+    valueEl: HTMLElement | null;
+    listEl: HTMLElement | null;
+    viewportEl: HTMLElement | null;
     isOpen: boolean;
     listboxId: string;
     /** All options, flattened across groups — render order. */
@@ -38,6 +49,19 @@ export declare class SelectState {
     };
     constructor(options: SelectStateOptions);
     optionId: (value: string) => string;
+    /**
+     * Popover `positionPanel`: places the open panel over the trigger with the selected option (or
+     * the first one) on the value, and sizes and scrolls the list to keep it there. `null` falls
+     * back to the dropdown below the trigger.
+     */
+    positionPanel: ({ panel, reference }: {
+        panel: HTMLElement;
+        reference: unknown;
+    }) => {
+        x: number;
+        y: number;
+        minWidth: number;
+    } | null;
     open: () => void;
     close: () => void;
     toggle: () => void;

package/dist/components/Form/Select/select.state.svelte.js

@@ -1,8 +1,28 @@
 import { bind } from '../../../utils/state.svelte.js';
 import { useListNavigation } from '../../../utils/useListNavigation.svelte.js';
+import { alignItemWithTrigger, SELECT_ALIGN_MARGIN } from './select.align.js';
+/** Inline-start edge of an element's first text: what lines up between the value and an option. */
+const textStart = (element, rtl) => {
+    const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT, {
+        acceptNode: (node) => node.textContent?.trim() ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP
+    });
+    const text = walker.nextNode();
+    let rect = element.getBoundingClientRect();
+    const range = text ? document.createRange() : null;
+    // Ranges without layout (jsdom) fall back to the element's own box.
+    if (range?.getBoundingClientRect) {
+        range.selectNodeContents(text);
+        rect = range.getBoundingClientRect();
+    }
+    return rtl ? rect.right : rect.left;
+};
 const isGroup = (entry) => Array.isArray(entry.items);
 export class SelectState {
     isOpen = $state(false);
+    // Where this open session placed the panel. Measured once: later repositioning (the panel
+    // resizing, the list scrolling) must not re-scroll the list under the pointer. A new viewport
+    // size measures again.
+    #alignment = null;
     listboxId = $derived.by(() => `${this.id}-listbox`);
     /** All options, flattened across groups — render order. */
     flatOptions = $derived.by(() => (this.items ?? []).flatMap((entry) => (isGroup(entry) ? entry.items : [entry])));
@@ -35,12 +55,100 @@ export class SelectState {
     });
     constructor(options) {
         bind(this, options);
+        // An item-aligned panel sits on the trigger, so the page holds still while it is open, as
+        // it does for a native select. Popover's body lock does not reach an app's own scroll
+        // container (a scrolling <main>), so wheel and touch scrolling are blocked outside the
+        // panel. The panel is portaled under the locked body: its own scrolling cannot chain out.
+        $effect(() => {
+            if (!this.isOpen || !this.alignItemWithTrigger)
+                return;
+            const block = (event) => {
+                const panel = document.getElementById(this.listboxId)?.closest('dialog');
+                if (event.target instanceof Node && panel?.contains(event.target))
+                    return;
+                event.preventDefault();
+            };
+            const listen = { capture: true, passive: false };
+            window.addEventListener('wheel', block, listen);
+            window.addEventListener('touchmove', block, listen);
+            return () => {
+                window.removeEventListener('wheel', block, listen);
+                window.removeEventListener('touchmove', block, listen);
+            };
+        });
     }
     // Index-based ids — sanitizing values into ids can collide ('a.b' and 'a_b' both → 'a_b').
     optionId = (value) => `${this.id}-option-${this.flatOptions.findIndex((o) => o.value === value)}`;
+    /**
+     * Popover `positionPanel`: places the open panel over the trigger with the selected option (or
+     * the first one) on the value, and sizes and scrolls the list to keep it there. `null` falls
+     * back to the dropdown below the trigger.
+     */
+    positionPanel = ({ panel, reference }) => {
+        const { valueEl, listEl, viewportEl } = this;
+        if (!this.alignItemWithTrigger || !valueEl || !listEl || !viewportEl)
+            return null;
+        if (!(reference instanceof HTMLElement))
+            return null;
+        const anchor = this.selectedOption && !this.selectedOption.disabled
+            ? this.selectedOption
+            : this.flatOptions.find((option) => !option.disabled);
+        const item = anchor && document.getElementById(this.optionId(anchor.value));
+        if (!item)
+            return null;
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+        const kept = this.#alignment;
+        if (kept && kept.viewport.width === width && kept.viewport.height === height)
+            return kept.position;
+        // Measure the list at its natural height and scroll, the panel at least as wide as the
+        // trigger (what `fitTrigger` applies on the next render).
+        const trigger = reference.getBoundingClientRect();
+        const surface = panel.firstElementChild;
+        if (surface)
+            surface.style.minWidth = `${trigger.width}px`;
+        listEl.style.maxHeight = 'none';
+        viewportEl.scrollTop = 0;
+        const rtl = getComputedStyle(reference).direction === 'rtl';
+        const panelRect = panel.getBoundingClientRect();
+        const listRect = listEl.getBoundingClientRect();
+        const itemRect = item.getBoundingClientRect();
+        const placed = alignItemWithTrigger({
+            viewport: { width, height },
+            trigger: { top: trigger.top, height: trigger.height },
+            valueTextStart: textStart(valueEl, rtl),
+            panel: {
+                left: panelRect.left,
+                right: panelRect.right,
+                top: panelRect.top,
+                width: panelRect.width,
+                height: panelRect.height
+            },
+            list: { top: listRect.top, height: listRect.height },
+            item: { top: itemRect.top, height: itemRect.height, textStart: textStart(item, rtl) },
+            rtl
+        });
+        listEl.style.maxHeight = `${placed.listHeight}px`;
+        viewportEl.scrollTop = placed.scrollTop;
+        // Overhang the trigger on both sides. The text alignment fixes the start edge, so the panel
+        // widens at the end to match the start's overhang (at least 4px) and stays in the viewport.
+        const end = rtl ? placed.x + panelRect.width : placed.x;
+        const startOverhang = rtl ? end - trigger.right : trigger.left - placed.x;
+        const overhang = Math.max(4, startOverhang);
+        const minWidth = Math.max(panelRect.width, rtl ? end - (trigger.left - overhang) : trigger.right + overhang - placed.x);
+        const x = Math.min(Math.max(rtl ? end - minWidth : placed.x, SELECT_ALIGN_MARGIN), width - SELECT_ALIGN_MARGIN - minWidth);
+        // Popover applies `minWidth` through a style binding, which skips the write when the value
+        // matches the previous session's: put back what the measurement overwrote.
+        if (surface)
+            surface.style.minWidth = `${minWidth}px`;
+        const position = { x: Math.max(SELECT_ALIGN_MARGIN, x), y: placed.y, minWidth };
+        this.#alignment = { position, viewport: { width, height } };
+        return position;
+    };
     open = () => {
         if (this.disabled)
             return;
+        this.#alignment = null;
         this.isOpen = true;
         // Safari/Firefox-macOS don't focus buttons on click — grab focus explicitly so the
         // blur-to-close and trigger keydown paths work for mouse users everywhere.
@@ -51,8 +159,10 @@ export class SelectState {
         if (selected && !selected.disabled) {
             this.nav.setHighlighted(selected.value);
             // The dropdown mounts on the next flush — defer the scroll (setTimeout, not rAF:
-            // rAF stalls in hidden tabs).
+            // rAF stalls in hidden tabs). An item-aligned panel has already scrolled its list.
             setTimeout(() => {
+                if (this.#alignment)
+                    return;
                 document
                     .getElementById(this.optionId(selected.value))
                     ?.scrollIntoView({ block: 'nearest' });

package/dist/components/PageShell/pageShell.theme.js

@@ -4,7 +4,7 @@ const defaultShell = cva({
     base: 'flex min-h-full w-full flex-col overflow-clip rounded-[inherit] bg-surface !bg-[var(--page-shell-surface,var(--color-surface))] text-neutral'
 });
 const defaultHeader = cva({
-    base: 'sticky top-[calc(var(--page-shell-edge-inset,0px)_+_var(--page-shell-chrome-block-gap,0px))] z-20 mx-[var(--page-shell-chrome-inline-gap,0px)] mt-[var(--page-shell-chrome-block-gap,0px)] mb-[var(--page-shell-chrome-block-gap,0px)] shrink-0 rounded-tl-[var(--page-shell-header-top-radius,inherit)] rounded-tr-[var(--page-shell-header-top-radius,inherit)] rounded-br-[var(--page-shell-header-bottom-radius,0px)] rounded-bl-[var(--page-shell-header-bottom-radius,0px)] border-b [border-bottom-color:var(--page-shell-chrome-divider,var(--color-neutral-muted))] bg-[var(--page-shell-chrome,var(--color-surface))] shadow-[var(--page-shell-chrome-shadow,none)] ring-1 ring-inset ring-[var(--page-shell-chrome-border,transparent)] backdrop-blur'
+    base: 'sticky top-[calc(var(--page-shell-edge-inset,0px)_+_var(--page-shell-chrome-block-gap,0px))] z-20 ml-[var(--page-shell-chrome-left-gap,var(--page-shell-chrome-inline-gap,0px))] mr-[var(--page-shell-chrome-right-gap,var(--page-shell-chrome-inline-gap,0px))] mt-[var(--page-shell-chrome-block-gap,0px)] mb-[var(--page-shell-chrome-block-gap,0px)] shrink-0 rounded-tl-[var(--page-shell-header-top-radius,inherit)] rounded-tr-[var(--page-shell-header-top-radius,inherit)] rounded-br-[var(--page-shell-header-bottom-radius,0px)] rounded-bl-[var(--page-shell-header-bottom-radius,0px)] border-b [border-bottom-color:var(--page-shell-chrome-divider,var(--color-neutral-muted))] bg-[var(--page-shell-chrome,var(--color-surface))] shadow-[var(--page-shell-chrome-shadow,none)] ring-1 ring-inset ring-[var(--page-shell-chrome-border,transparent)] backdrop-blur'
 });
 // The row wraps: the title keeps its natural width and the actions drop under it when they do not
 // fit, instead of the title being squeezed to an ellipsis by a wide actions block.
@@ -63,7 +63,7 @@ const defaultContentInner = cva({
     }
 });
 const defaultFooter = cva({
-    base: 'sticky bottom-[calc(var(--page-shell-edge-inset,0px)_+_var(--page-shell-chrome-block-gap,0px))] z-20 mx-[var(--page-shell-chrome-inline-gap,0px)] mt-[var(--page-shell-chrome-block-gap,0px)] mb-[var(--page-shell-chrome-block-gap,0px)] shrink-0 rounded-tl-[var(--page-shell-footer-top-radius,0px)] rounded-tr-[var(--page-shell-footer-top-radius,0px)] rounded-br-[var(--page-shell-footer-bottom-radius,inherit)] rounded-bl-[var(--page-shell-footer-bottom-radius,inherit)] border-t [border-top-color:var(--page-shell-chrome-divider,var(--color-neutral-muted))] bg-[var(--page-shell-chrome,var(--color-surface))] shadow-[var(--page-shell-chrome-shadow,none)] ring-1 ring-inset ring-[var(--page-shell-chrome-border,transparent)] backdrop-blur'
+    base: 'sticky bottom-[calc(var(--page-shell-edge-inset,0px)_+_var(--page-shell-chrome-block-gap,0px))] z-20 ml-[var(--page-shell-chrome-left-gap,var(--page-shell-chrome-inline-gap,0px))] mr-[var(--page-shell-chrome-right-gap,var(--page-shell-chrome-inline-gap,0px))] mt-[var(--page-shell-chrome-block-gap,0px)] mb-[var(--page-shell-chrome-block-gap,0px)] shrink-0 rounded-tl-[var(--page-shell-footer-top-radius,0px)] rounded-tr-[var(--page-shell-footer-top-radius,0px)] rounded-br-[var(--page-shell-footer-bottom-radius,inherit)] rounded-bl-[var(--page-shell-footer-bottom-radius,inherit)] border-t [border-top-color:var(--page-shell-chrome-divider,var(--color-neutral-muted))] bg-[var(--page-shell-chrome,var(--color-surface))] shadow-[var(--page-shell-chrome-shadow,none)] ring-1 ring-inset ring-[var(--page-shell-chrome-border,transparent)] backdrop-blur'
 });
 const defaultFooterInner = cva({
     base: 'flex min-h-row-lg items-center justify-between gap-lg px-xl py-md text-sm text-neutral/70'

package/dist/components/Popover/Popover.svelte

@@ -34,6 +34,7 @@
 		directedTransition = true,
 		lockScroll = true,
 		fitTrigger = false,
+		positionPanel,
 		inline = false,
 		mobileSheet = false,
 		mobileSheetSizeTransition = true,
@@ -87,6 +88,9 @@
 		get fitTrigger() {
 			return fitTrigger;
 		},
+		get positionPanel() {
+			return positionPanel;
+		},
 		get mobileSheet() {
 			return mobileSheet;
 		},