@foldkit/ui 0.127.0 → 0.128.0

package/dist/combobox/shared.js

@@ -1,4 +1,4 @@
-import { Array, Effect, Match as M, Option, Predicate, Result, Schema as S, pipe, } from 'effect';
+import { Array, Effect, Match as M, Option, Predicate, Schema as S, pipe, } from 'effect';
 import * as Command from 'foldkit/command';
 import * as Dom from 'foldkit/dom';
 import { html } from 'foldkit/html';
@@ -55,22 +55,25 @@ export const baseInit = (config) => ({
 export const Opened = m('Opened', {
     maybeActiveItemIndex: S.Option(S.Number),
 });
-/** Sent when the combobox closes via Escape key or backdrop click. */
-export const Closed = m('Closed');
-/** Sent when the combobox input loses focus. */
-export const BlurredInput = m('BlurredInput');
+/** Sent when the combobox closes via Escape key or backdrop click. `restingInputValue` is what the input returns to on close (the parent-owned selection's display text, or empty), computed by the view from `ViewInputs.restingInputValue`. */
+export const Closed = m('Closed', { restingInputValue: S.String });
+/** Sent when the combobox input loses focus. `restingInputValue` is what the input returns to on close (the parent-owned selection's display text, or empty), computed by the view from `ViewInputs.restingInputValue`. */
+export const BlurredInput = m('BlurredInput', {
+    restingInputValue: S.String,
+});
 /** Sent when an item is highlighted via arrow keys or mouse hover. Includes activation trigger and optional immediate selection info. */
 export const ActivatedItem = m('ActivatedItem', {
     index: S.Number,
     activationTrigger: ActivationTrigger,
-    maybeImmediateSelection: S.Option(S.Struct({ item: S.String, displayText: S.String })),
+    maybeImmediateSelection: S.Option(S.Struct({ item: S.String })),
 });
 /** Sent when the mouse leaves an enabled item. */
 export const DeactivatedItem = m('DeactivatedItem');
-/** Sent when an item is selected via Enter or click. Includes display text for restoring input value on close. */
+/** Sent when an item is selected via Enter or click. `displayText` is the item's resting input text, and `wasSelected` reports whether the item was already in the parent-owned selection when activated, so nullable deselect logic works without the Model knowing the selection. */
 export const SelectedItem = m('SelectedItem', {
     item: S.String,
     displayText: S.String,
+    wasSelected: S.Boolean,
 });
 /** Sent when the pointer moves over a combobox item. */
 export const MovedPointerOverItem = m('MovedPointerOverItem', {
@@ -112,8 +115,10 @@ export const GotAnimationMessage = m('GotAnimationMessage', {
 export const UpdatedInputValue = m('UpdatedInputValue', {
     value: S.String,
 });
-/** Sent when the optional toggle button is clicked. */
-export const PressedToggleButton = m('PressedToggleButton');
+/** Sent when the optional toggle button is clicked. `restingInputValue` is what the input returns to when the press closes the combobox (the parent-owned selection's display text, or empty), computed by the view from `ViewInputs.restingInputValue`. */
+export const PressedToggleButton = m('PressedToggleButton', {
+    restingInputValue: S.String,
+});
 /** Union of all messages the combobox component can produce. */
 export const Message = S.Union([
     Opened,
@@ -140,13 +145,14 @@ export const Message = S.Union([
     PressedToggleButton,
 ]);
 // OUT MESSAGE
-/** Sent when a single-select combobox commits a selection, or when a multi-select combobox toggles an item on. The `value` is the string key; consumers that need a richer domain type should look it up from their own state or, in the multi case, branch on `wasAdded` to distinguish add vs remove. */
+/** Sent when the user activates an item. Carries the neutral fact that the item was activated; the parent owns the selection and decides what it means (single-select stores the value, nullable single-select toggles it, multi-select toggles the value's membership). Generic over `Value extends string`: the runtime schema stores `value: string`, but the type-level OutMessage exposes `value: Value` so consumers who supply `items: ReadonlyArray<MyUnion>` receive `value: MyUnion` from the factory's `update` without casting. */
 export const Selected = m('Selected', {
     value: S.String,
-    wasAdded: S.Boolean,
 });
-/** Union of out-messages the combobox component can produce. Single-select comboboxes always emit `wasAdded: true`. Multi-select comboboxes emit `wasAdded: true` when adding to the selection and `wasAdded: false` when toggling off. */
-export const OutMessage = S.Union([Selected]);
+/** Sent when a nullable combobox closes with an empty input, meaning the user cleared it. The parent clears the selection it owns. */
+export const ClearedSelection = m('ClearedSelection');
+/** Union of out-messages the combobox component can produce. The parent folds `Selected` into the selection it owns and clears that selection on `ClearedSelection`. */
+export const OutMessage = S.Union([Selected, ClearedSelection]);
 // SELECTORS
 /** Returns the bare DOM id of the combobox input, derived from the
  *  combobox's base id. Use this to associate an external label with the
@@ -161,7 +167,7 @@ export const itemSelector = (id, index) => idSelector(`${id}-item-${index}`);
 export const itemId = (id, index) => `${id}-item-${index}`;
 // HELPERS
 const constrainedEvo = makeConstrainedEvo();
-/** Resets only shared base fields to their closed state. Does not touch inputValue or selection. Those are variant-specific. */
+/** Resets only shared base fields to their closed state. Does not touch inputValue. That is variant-specific. */
 export const closedBaseModel = (model) => constrainedEvo(model, {
     isOpen: () => false,
     maybeActiveItemIndex: () => Option.none(),
@@ -229,13 +235,17 @@ export const makeUpdate = (handlers) => {
                 Option.none(),
             ];
         };
-        const closeCombobox = (baseModel, commands, maybeOutMessage = Option.none()) => {
-            const closed = handlers.handleClose(baseModel);
+        const closeCombobox = (baseModel, commands, restingInputValue) => {
+            const [closed, maybeCloseOutMessage] = handlers.handleClose(baseModel, restingInputValue);
             if (model.isAnimated) {
                 const [nextModel, animationCommands] = delegateToAnimation(closed, AnimationHid());
-                return [nextModel, [...commands, ...animationCommands], maybeOutMessage];
+                return [
+                    nextModel,
+                    [...commands, ...animationCommands],
+                    maybeCloseOutMessage,
+                ];
             }
-            return [closed, commands, maybeOutMessage];
+            return [closed, commands, maybeCloseOutMessage];
         };
         return M.value(message).pipe(withUpdateReturn, M.tag('CompletedLockScroll', 'CompletedUnlockScroll', 'CompletedInertOthers', 'CompletedRestoreInert', 'CompletedFocusInput', 'CompletedScrollIntoView', 'CompletedClickItem', 'CompletedAnchorCombobox', 'CompletedAttachComboboxPreventBlur', 'CompletedAttachComboboxSelectOnFocus', 'CompletedPortalComboboxBackdrop', () => [model, [], Option.none()]), M.tagsExhaustive({
             Opened: ({ maybeActiveItemIndex }) => openCombobox(constrainedEvo(model, {
@@ -246,23 +256,32 @@ export const makeUpdate = (handlers) => {
                 }),
                 maybeLastPointerPosition: () => Option.none(),
             })),
-            Closed: () => closeCombobox(model, [focusInput]),
-            BlurredInput: () => closeCombobox(model, []),
+            // NOTE: guard on isOpen so a close-path message baked from a stale
+            // render (a sub-frame blur after a selection already closed the
+            // combobox) cannot rewrite inputValue with an outdated
+            // restingInputValue or re-emit ClearedSelection while closed.
+            Closed: ({ restingInputValue }) => model.isOpen
+                ? closeCombobox(model, [focusInput], restingInputValue)
+                : [model, [], Option.none()],
+            BlurredInput: ({ restingInputValue }) => model.isOpen
+                ? closeCombobox(model, [], restingInputValue)
+                : [model, [], Option.none()],
             ActivatedItem: ({ index, activationTrigger, maybeImmediateSelection, }) => {
                 const highlightedModel = constrainedEvo(model, {
                     maybeActiveItemIndex: () => Option.some(index),
                     activationTrigger: () => activationTrigger,
                 });
-                const nextModel = Option.match(maybeImmediateSelection, {
-                    onNone: () => highlightedModel,
-                    onSome: ({ item, displayText }) => handlers.handleImmediateActivation(highlightedModel, item, displayText),
+                const skippedActivation = [highlightedModel, Option.none()];
+                const [nextModel, maybeOutMessage] = Option.match(maybeImmediateSelection, {
+                    onNone: () => skippedActivation,
+                    onSome: ({ item }) => handlers.handleImmediateActivation(highlightedModel, item),
                 });
                 return [
                     nextModel,
                     activationTrigger === 'Keyboard'
                         ? [ScrollIntoView({ id: model.id, index })]
                         : [],
-                    Option.none(),
+                    maybeOutMessage,
                 ];
             },
             MovedPointerOverItem: ({ index, screenX, screenY }) => {
@@ -289,8 +308,8 @@ export const makeUpdate = (handlers) => {
                     Option.none(),
                 ]
                 : [model, [], Option.none()],
-            SelectedItem: ({ item, displayText }) => {
-                const [nextModel, commands, maybeOutMessage] = handlers.handleSelectedItem(model, item, displayText, {
+            SelectedItem: ({ item, displayText, wasSelected }) => {
+                const [nextModel, commands, maybeOutMessage] = handlers.handleSelectedItem(model, item, displayText, wasSelected, {
                     focusInput,
                     maybeUnlockScroll,
                     maybeRestoreInert,
@@ -329,9 +348,9 @@ export const makeUpdate = (handlers) => {
                     maybeLastPointerPosition: () => Option.none(),
                 }));
             },
-            PressedToggleButton: () => {
+            PressedToggleButton: ({ restingInputValue }) => {
                 if (model.isOpen) {
-                    return closeCombobox(model, [focusInput]);
+                    return closeCombobox(model, [focusInput], restingInputValue);
                 }
                 const [nextModel, commands] = openCombobox(constrainedEvo(model, {
                     maybeActiveItemIndex: () => Option.none(),
@@ -413,12 +432,12 @@ export const PortalComboboxBackdrop = Mount.define('PortalComboboxBackdrop', Com
     yield* Effect.acquireRelease(Effect.sync(() => portalToContainingRoot(element)), cleanup => Effect.sync(cleanup));
     return CompletedPortalComboboxBackdrop();
 }));
-/** Creates a combobox view function from variant-specific behavior. Shared rendering logic (input, items, transitions, keyboard navigation) is handled internally; only selection display varies by variant. */
+/** Creates a combobox view function from variant-specific behavior. Shared rendering logic (input, items, transitions, keyboard navigation) is handled internally; only listbox multi-select semantics vary by variant. */
 export const makeView = (behavior) => {
     const impl = defineView((model, viewInputs) => {
         const h = html();
         const { id, isOpen, immediate, animation: { transitionState }, maybeActiveItemIndex, } = model;
-        const { items, itemToConfig, itemToValue, itemToDisplayText, isItemDisabled, inputClassName, inputAttributes = [], inputPlaceholder, inputWrapperClassName, inputWrapperAttributes = [], itemsClassName, itemsAttributes = [], itemsScrollClassName, itemsScrollAttributes = [], backdropClassName, backdropAttributes = [], className, attributes = [], buttonContent, buttonClassName, buttonAttributes = [], formName, isDisabled, isInvalid, openOnFocus, itemGroupKey, groupToHeading, groupClassName, groupAttributes = [], separatorClassName, separatorAttributes = [], anchor = {}, ariaLabel, ariaLabelledBy, } = viewInputs;
+        const { items, selectedValues, restingInputValue, itemToConfig, itemToValue, itemToDisplayText, isItemDisabled, inputClassName, inputAttributes = [], inputPlaceholder, inputWrapperClassName, inputWrapperAttributes = [], itemsClassName, itemsAttributes = [], itemsScrollClassName, itemsScrollAttributes = [], backdropClassName, backdropAttributes = [], className, attributes = [], buttonContent, buttonClassName, buttonAttributes = [], formName, isDisabled, isInvalid, openOnFocus, itemGroupKey, groupToHeading, groupClassName, groupAttributes = [], separatorClassName, separatorAttributes = [], anchor = {}, ariaLabel, ariaLabelledBy, } = viewInputs;
         const resolveInputLabel = () => {
             if (Predicate.isNotUndefined(ariaLabel)) {
                 return [h.AriaLabel(ariaLabel)];
@@ -431,6 +450,7 @@ export const makeView = (behavior) => {
             }
         };
         const inputLabelAttributes = resolveInputLabel();
+        const isValueSelected = (itemValue) => Array.contains(selectedValues, itemValue);
         const isLeaving = transitionState === 'LeaveStart' || transitionState === 'LeaveAnimating';
         const isVisible = isOpen || isLeaving;
         const animationAttributes = M.value(transitionState).pipe(M.when('EnterStart', () => [
@@ -453,12 +473,8 @@ export const makeView = (behavior) => {
         const firstEnabledIndex = findFirstEnabledIndex(items.length, 0, isDisabledAtIndex)(0, 1);
         const lastEnabledIndex = findFirstEnabledIndex(items.length, 0, isDisabledAtIndex)(items.length - 1, -1);
         const resolveActiveIndex = keyToIndex('ArrowDown', 'ArrowUp', items.length, Option.getOrElse(maybeActiveItemIndex, () => -1), isDisabledAtIndex);
-        const resolveImmediateSelection = (targetIndex) => OptionExt.when(immediate, pipe(items, Array.get(targetIndex), Option.match({
-            onNone: () => ({ item: '', displayText: '' }),
-            onSome: targetItem => ({
-                item: itemToValue(targetItem, targetIndex),
-                displayText: itemToDisplayText(targetItem, targetIndex),
-            }),
+        const resolveImmediateSelection = (targetIndex) => pipe(OptionExt.when(immediate, targetIndex), Option.flatMap(index => Array.get(items, index)), Option.map(targetItem => ({
+            item: itemToValue(targetItem, targetIndex),
         })));
         const handleInputKeyDown = (key) => M.value(key).pipe(M.when('ArrowDown', () => {
             if (!isOpen) {
@@ -493,7 +509,7 @@ export const makeView = (behavior) => {
             if (!isOpen) {
                 return Option.none();
             }
-            return Option.some(Closed());
+            return Option.some(Closed({ restingInputValue }));
         }), M.whenOr('Home', 'End', () => {
             if (!isOpen) {
                 return Option.none();
@@ -526,7 +542,7 @@ export const makeView = (behavior) => {
                 : [
                     h.OnInput(value => UpdatedInputValue({ value })),
                     h.OnKeyDownPreventDefault(handleInputKeyDown),
-                    h.OnBlur(BlurredInput()),
+                    h.OnBlur(BlurredInput({ restingInputValue })),
                     ...(openOnFocus
                         ? [h.OnFocus(Opened({ maybeActiveItemIndex: Option.none() }))]
                         : []),
@@ -566,7 +582,7 @@ export const makeView = (behavior) => {
         const comboboxItems = Array.map(items, (item, index) => {
             const isActiveItem = Option.exists(maybeActiveItemIndex, activeIndex => activeIndex === index);
             const isDisabledItem = isDisabledAtIndex(index);
-            const isSelectedItem = behavior.isItemSelected(model, itemToValue(item, index));
+            const isSelectedItem = isValueSelected(itemToValue(item, index));
             const itemConfig = itemToConfig(item, {
                 isActive: isActiveItem,
                 isDisabled: isDisabledItem,
@@ -587,6 +603,7 @@ export const makeView = (behavior) => {
                         h.OnClick(SelectedItem({
                             item: itemToValue(item, index),
                             displayText: itemToDisplayText(item, index),
+                            wasSelected: isValueSelected(itemToValue(item, index)),
                         })),
                         ...(isActiveItem
                             ? []
@@ -647,7 +664,7 @@ export const makeView = (behavior) => {
         };
         const backdrop = h.keyed('div')(`${id}-backdrop`, [
             h.OnMount(PortalComboboxBackdrop()),
-            ...(isLeaving ? [] : [h.OnClick(Closed())]),
+            ...(isLeaving ? [] : [h.OnClick(Closed({ restingInputValue }))]),
             ...(backdropClassName ? [h.Class(backdropClassName)] : []),
             ...backdropAttributes,
         ], []);
@@ -683,17 +700,13 @@ export const makeView = (behavior) => {
                     h.Attribute('aria-haspopup', 'listbox'),
                     ...(isDisabled
                         ? [h.AriaDisabled(true), h.DataAttribute('disabled', '')]
-                        : [h.OnClick(PressedToggleButton())]),
+                        : [h.OnClick(PressedToggleButton({ restingInputValue }))]),
                     h.OnMount(AttachComboboxPreventBlur()),
                     ...(buttonClassName ? [h.Class(buttonClassName)] : []),
                     ...buttonAttributes,
                 ], [buttonContent]),
             ]
             : [];
-        const selectedValues = pipe(items, Array.filterMap((item, index) => {
-            const value = itemToValue(item, index);
-            return Result.fromOption(OptionExt.when(behavior.isItemSelected(model, value), value), () => undefined);
-        }));
         const hiddenInputs = formName
             ? Array.match(selectedValues, {
                 onEmpty: () => [h.input([h.Type('hidden'), h.Name(formName)])],

package/dist/combobox/single.d.ts

@@ -1,11 +1,9 @@
 import { Option, Schema as S } from 'effect';
 import type * as Command from 'foldkit/command';
-import type { Reflect, View as SubmodelView } from 'foldkit/submodel';
-import { type BaseInitConfig, type BaseViewInputs, type Message, type OutMessage } from './shared.js';
-/** Schema for the single-select combobox component's state, tracking open/closed status, active item, input value, selected item, and display text. */
+import { type View as SubmodelView } from 'foldkit/submodel';
+import { type BaseInitConfig, type BaseViewInputsCommon, type Message, type OutMessage } from './shared.js';
+/** Schema for the single-select combobox's private interaction state (open/closed status, active item, activation trigger, typed input value). The selection is owned by the parent and passed in via `ViewInputs.maybeSelectedValue`. */
 export declare const Model: S.Struct<{
-    readonly maybeSelectedItem: S.Option<S.String>;
-    readonly maybeSelectedDisplayText: S.Option<S.String>;
     readonly id: S.String;
     readonly isOpen: S.Boolean;
     readonly isAnimated: S.Boolean;
@@ -27,17 +25,12 @@ export declare const Model: S.Struct<{
     }>>;
 }>;
 export type Model = typeof Model.Type;
-/** Configuration for creating a single-select combobox model with `init`. `isAnimated` enables CSS transition coordination (default `false`). `isModal` locks page scroll and inerts other elements when open (default `false`). `selectedItem` sets the initial selection (default none). */
-export type InitConfig = BaseInitConfig & Readonly<{
-    selectedItem?: string;
-    selectedDisplayText?: string;
-}>;
-/** Creates an initial single-select combobox model from a config. Defaults to closed with no active item, empty input, and no selection. */
+/** Configuration for creating a single-select combobox model with `init`. `isAnimated` enables CSS transition coordination (default `false`). `isModal` locks page scroll and inerts other elements when open (default `false`). */
+export type InitConfig = BaseInitConfig;
+/** Creates an initial single-select combobox model from a config. Defaults to closed with no active item and an empty input. */
 export declare const init: (config: InitConfig) => Model;
-/** Processes a combobox message and returns the next model and commands. Closes the combobox on selection (single-select behavior). */
+/** Processes a combobox message and returns the next model, commands, and optional OutMessage. Closes the combobox on selection (single-select behavior); emits `Selected({ value })` for the parent to store, and `ClearedSelection` when a nullable combobox closes with an empty input. */
 export declare const update: (model: S.Struct.ReadonlySide<{
-    readonly maybeSelectedItem: S.Option<S.String>;
-    readonly maybeSelectedDisplayText: S.Option<S.String>;
     readonly id: S.String;
     readonly isOpen: S.Boolean;
     readonly isAnimated: S.Boolean;
@@ -58,8 +51,6 @@ export declare const update: (model: S.Struct.ReadonlySide<{
         readonly screenY: S.Number;
     }>>;
 }, "Type">, message: Message) => readonly [S.Struct.ReadonlySide<{
-    readonly maybeSelectedItem: S.Option<S.String>;
-    readonly maybeSelectedDisplayText: S.Option<S.String>;
     readonly id: S.String;
     readonly isOpen: S.Boolean;
     readonly isAnimated: S.Boolean;
@@ -90,20 +81,21 @@ export declare const update: (model: S.Struct.ReadonlySide<{
         readonly _tag: S.tag<"CompletedInertOthers">;
     }, "Type"> | S.Struct.ReadonlySide<{
         readonly _tag: S.tag<"CompletedRestoreInert">;
-    }, "Type"> | S.Struct.ReadonlySide<{
-        readonly _tag: S.tag<"Closed">;
     }, "Type"> | S.Struct.ReadonlySide<{
         readonly _tag: S.tag<"Opened">;
         maybeActiveItemIndex: S.Option<S.Number>;
+    }, "Type"> | S.Struct.ReadonlySide<{
+        readonly _tag: S.tag<"Closed">;
+        restingInputValue: S.String;
     }, "Type"> | S.Struct.ReadonlySide<{
         readonly _tag: S.tag<"BlurredInput">;
+        restingInputValue: S.String;
     }, "Type"> | S.Struct.ReadonlySide<{
         readonly _tag: S.tag<"ActivatedItem">;
         index: S.Number;
         activationTrigger: S.Literals<readonly ["Pointer", "Keyboard"]>;
         maybeImmediateSelection: S.Option<S.Struct<{
             readonly item: S.String;
-            readonly displayText: S.String;
         }>>;
     }, "Type"> | S.Struct.ReadonlySide<{
         readonly _tag: S.tag<"DeactivatedItem">;
@@ -111,6 +103,7 @@ export declare const update: (model: S.Struct.ReadonlySide<{
         readonly _tag: S.tag<"SelectedItem">;
         item: S.String;
         displayText: S.String;
+        wasSelected: S.Boolean;
     }, "Type"> | S.Struct.ReadonlySide<{
         readonly _tag: S.tag<"MovedPointerOverItem">;
         index: S.Number;
@@ -130,6 +123,7 @@ export declare const update: (model: S.Struct.ReadonlySide<{
         value: S.String;
     }, "Type"> | S.Struct.ReadonlySide<{
         readonly _tag: S.tag<"PressedToggleButton">;
+        restingInputValue: S.String;
     }, "Type"> | S.Struct.ReadonlySide<{
         readonly _tag: S.tag<"CompletedAnchorCombobox">;
     }, "Type"> | S.Struct.ReadonlySide<{
@@ -142,49 +136,43 @@ export declare const update: (model: S.Struct.ReadonlySide<{
         readonly _tag: S.tag<"GotAnimationMessage">;
         message: S.Union<[import("foldkit/schema").CallableTaggedStruct<"Showed", {}>, import("foldkit/schema").CallableTaggedStruct<"Hid", {}>, import("foldkit/schema").CallableTaggedStruct<"AdvancedAnimationFrame", {}>, import("foldkit/schema").CallableTaggedStruct<"EndedAnimation", {}>]>;
     }, "Type">, never, never>;
-}>[], Option.Option<Readonly<{
-    readonly _tag: "Selected";
-    readonly value: string;
-    readonly wasAdded: boolean;
-}>>];
+}>[], Option.Option<OutMessage<string>>];
 type UpdateReturn = ReturnType<typeof update>;
 /** Programmatically opens the combobox, updating the model and returning
  *  focus and modal commands. Use this in domain-event handlers to open the combobox. */
 export declare const open: (model: Model) => UpdateReturn;
 /** Programmatically closes the combobox, updating the model and returning
- *  focus and modal commands. Use this in domain-event handlers to close the combobox. */
-export declare const close: (model: Model) => UpdateReturn;
-/** Programmatically selects an item in the single-select combobox. Emits `Selected({ value, wasAdded })`. */
+ *  focus and modal commands. `restingInputValue` is the text the input
+ *  returns to (the parent-owned selection's display text, or empty). Use
+ *  this in domain-event handlers to close the combobox. */
+export declare const close: (model: Model, restingInputValue: string) => UpdateReturn;
+/** Programmatically selects an item in the single-select combobox, closing
+ *  the combobox and emitting `Selected({ value })`. The Submodel treats the
+ *  select as fresh (`wasSelected: false`), so the input rests on
+ *  `displayText`; what the selection becomes is the parent's fold to decide,
+ *  and a parent that toggles on its own state will still deselect an
+ *  already-selected value. */
 export declare const selectItem: (model: Model, item: string, displayText: string) => UpdateReturn;
-/** Reflects an externally-sourced selection onto the model without
- *  emitting an OutMessage or running selection side effects (no close, no
- *  focus). Sets the selected item, its display text, and the input text
- *  together, so the input shows the reflected selection. Pass
- *  `Option.none()` to clear. Use this to mirror external truth (a URL
- *  parameter, restored storage, a server push) onto the combobox.
- *  Contrast with `selectItem`, a user/programmatic *choice* that emits
- *  `Selected`. Returns the model directly because it produces no commands
- *  and no OutMessage. */
-export declare const reflectSelectedItem: Reflect<Model, Option.Option<{
-    readonly item: string;
-    readonly displayText: string;
-}>>;
 /** Per-render view inputs passed to the view via `h.submodel`'s `viewInputs` field. */
-export type ViewInputs<Item extends string> = BaseViewInputs<Item>;
+export type ViewInputs<Item extends string> = BaseViewInputsCommon<Item> & Readonly<{
+    /** The selection the parent owns, passed in fresh on every render.
+     *  `Option` because a single-select combobox may have no selection
+     *  yet. Marks the selected item and drives the hidden form input
+     *  submitted under `formName`. */
+    maybeSelectedValue: Option.Option<Item>;
+}>;
 /** Pairs the single-select combobox's `view` and `update` (and programmatic
  *  helpers) behind a single Item-typed entry point. See `Listbox.create`
  *  for the rationale; the combobox factory follows the same shape with
- *  `selectItem` taking both `item` and `displayText`. */
+ *  `selectItem` taking both `item` and `displayText`. `selectItem` emits
+ *  `Selected({ value })` with the input resting on `displayText`; what the
+ *  selection becomes is the parent's fold to decide. */
 export declare const create: <Item extends string = string>() => Readonly<{
-    view: SubmodelView<Model, Message, BaseViewInputs<Item>>;
+    view: SubmodelView<Model, Message, ViewInputs<Item>>;
     update: (model: Model, message: Message) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Item>>];
     selectItem: (model: Model, item: Item, displayText: string) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Item>>];
     open: (model: Model) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Item>>];
-    close: (model: Model) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Item>>];
-    reflectSelectedItem: Reflect<Model, Option.Option<{
-        readonly item: Item;
-        readonly displayText: string;
-    }>>;
+    close: (model: Model, restingInputValue: string) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Item>>];
 }>;
 export {};
 //# sourceMappingURL=single.d.ts.map

package/dist/combobox/single.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"single.d.ts","sourceRoot":"","sources":["../../src/combobox/single.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"single.d.ts","sourceRoot":"","sources":["../../src/combobox/single.ts"],"names":[],"mappings":"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"}

package/dist/combobox/single.js

@@ -1,106 +1,79 @@
-import { Array, Function, Option, Schema as S, pipe } from 'effect';
+import { Array, Option, Schema as S, pipe } from 'effect';
 import { evo } from 'foldkit/struct';
-import { BaseModel, Closed, Opened, SelectedItem, Selected as SharedSelected, baseInit, closedBaseModel, makeUpdate, makeView, } from './shared.js';
+import { defineView } from 'foldkit/submodel';
+import { BaseModel, ClearedSelection, Closed, Opened, SelectedItem, Selected as SharedSelected, baseInit, closedBaseModel, makeUpdate, makeView, } from './shared.js';
 // MODEL
-/** Schema for the single-select combobox component's state, tracking open/closed status, active item, input value, selected item, and display text. */
+/** Schema for the single-select combobox's private interaction state (open/closed status, active item, activation trigger, typed input value). The selection is owned by the parent and passed in via `ViewInputs.maybeSelectedValue`. */
 export const Model = S.Struct({
     ...BaseModel.fields,
-    maybeSelectedItem: S.Option(S.String),
-    maybeSelectedDisplayText: S.Option(S.String),
-});
-/** Creates an initial single-select combobox model from a config. Defaults to closed with no active item, empty input, and no selection. */
-export const init = (config) => ({
-    ...baseInit(config),
-    maybeSelectedItem: Option.fromNullishOr(config.selectedItem),
-    maybeSelectedDisplayText: Option.fromNullishOr(config.selectedDisplayText ?? config.selectedItem),
 });
+/** Creates an initial single-select combobox model from a config. Defaults to closed with no active item and an empty input. */
+export const init = (config) => baseInit(config);
 // UPDATE
-/** Processes a combobox message and returns the next model and commands. Closes the combobox on selection (single-select behavior). */
+/** Processes a combobox message and returns the next model, commands, and optional OutMessage. Closes the combobox on selection (single-select behavior); emits `Selected({ value })` for the parent to store, and `ClearedSelection` when a nullable combobox closes with an empty input. */
 export const update = makeUpdate({
-    handleClose: model => {
+    handleClose: (model, restingInputValue) => {
         if (model.nullable && model.inputValue === '') {
-            return evo(closedBaseModel(model), {
-                maybeSelectedItem: () => Option.none(),
-                maybeSelectedDisplayText: () => Option.none(),
-                inputValue: () => '',
-            });
+            return [
+                evo(closedBaseModel(model), { inputValue: () => '' }),
+                Option.some(ClearedSelection()),
+            ];
         }
-        return evo(closedBaseModel(model), {
-            inputValue: () => Option.getOrElse(model.maybeSelectedDisplayText, () => ''),
-        });
+        return [
+            evo(closedBaseModel(model), { inputValue: () => restingInputValue }),
+            Option.none(),
+        ];
     },
-    handleSelectedItem: (model, item, displayText, context) => {
-        const isAlreadySelected = Option.exists(model.maybeSelectedItem, selectedItem => selectedItem === item);
-        const nullableDeselect = model.nullable && isAlreadySelected;
-        const nextModel = nullableDeselect
-            ? evo(closedBaseModel(model), {
-                inputValue: () => '',
-                maybeSelectedItem: () => Option.none(),
-                maybeSelectedDisplayText: () => Option.none(),
-            })
-            : evo(closedBaseModel(model), {
-                inputValue: () => displayText,
-                maybeSelectedItem: () => Option.some(item),
-                maybeSelectedDisplayText: () => Option.some(displayText),
-            });
+    handleSelectedItem: (model, item, displayText, wasSelected, context) => {
+        const nullableDeselect = model.nullable && wasSelected;
         return [
-            nextModel,
+            evo(closedBaseModel(model), {
+                inputValue: () => (nullableDeselect ? '' : displayText),
+            }),
             pipe(Array.getSomes([context.maybeUnlockScroll, context.maybeRestoreInert]), Array.prepend(context.focusInput)),
-            Option.some(SharedSelected({ value: item, wasAdded: !nullableDeselect })),
+            Option.some(SharedSelected({ value: item })),
         ];
     },
-    handleImmediateActivation: (model, item, displayText) => evo(model, {
-        maybeSelectedItem: () => Option.some(item),
-        maybeSelectedDisplayText: () => Option.some(displayText),
-    }),
+    handleImmediateActivation: (model, item) => [
+        model,
+        Option.some(SharedSelected({ value: item })),
+    ],
 });
 /** Programmatically opens the combobox, updating the model and returning
  *  focus and modal commands. Use this in domain-event handlers to open the combobox. */
 export const open = (model) => update(model, Opened({ maybeActiveItemIndex: Option.none() }));
 /** Programmatically closes the combobox, updating the model and returning
- *  focus and modal commands. Use this in domain-event handlers to close the combobox. */
-export const close = (model) => update(model, Closed());
-/** Programmatically selects an item in the single-select combobox. Emits `Selected({ value, wasAdded })`. */
-export const selectItem = (model, item, displayText) => update(model, SelectedItem({ item, displayText }));
-/** Reflects an externally-sourced selection onto the model without
- *  emitting an OutMessage or running selection side effects (no close, no
- *  focus). Sets the selected item, its display text, and the input text
- *  together, so the input shows the reflected selection. Pass
- *  `Option.none()` to clear. Use this to mirror external truth (a URL
- *  parameter, restored storage, a server push) onto the combobox.
- *  Contrast with `selectItem`, a user/programmatic *choice* that emits
- *  `Selected`. Returns the model directly because it produces no commands
- *  and no OutMessage. */
-export const reflectSelectedItem = Function.dual(2, (model, maybeSelection) => Option.match(maybeSelection, {
-    onNone: () => evo(model, {
-        maybeSelectedItem: () => Option.none(),
-        maybeSelectedDisplayText: () => Option.none(),
-        inputValue: () => '',
-    }),
-    onSome: ({ item, displayText }) => evo(model, {
-        maybeSelectedItem: () => Option.some(item),
-        maybeSelectedDisplayText: () => Option.some(displayText),
-        inputValue: () => displayText,
-    }),
-}));
-const internalView = makeView({
-    isItemSelected: (model, itemValue) => Option.exists(model.maybeSelectedItem, selectedItem => selectedItem === itemValue),
-    ariaMultiSelectable: false,
-});
+ *  focus and modal commands. `restingInputValue` is the text the input
+ *  returns to (the parent-owned selection's display text, or empty). Use
+ *  this in domain-event handlers to close the combobox. */
+export const close = (model, restingInputValue) => update(model, Closed({ restingInputValue }));
+/** Programmatically selects an item in the single-select combobox, closing
+ *  the combobox and emitting `Selected({ value })`. The Submodel treats the
+ *  select as fresh (`wasSelected: false`), so the input rests on
+ *  `displayText`; what the selection becomes is the parent's fold to decide,
+ *  and a parent that toggles on its own state will still deselect an
+ *  already-selected value. */
+export const selectItem = (model, item, displayText) => update(model, SelectedItem({ item, displayText, wasSelected: false }));
+const internalView = makeView({ ariaMultiSelectable: false });
 /** Pairs the single-select combobox's `view` and `update` (and programmatic
  *  helpers) behind a single Item-typed entry point. See `Listbox.create`
  *  for the rationale; the combobox factory follows the same shape with
- *  `selectItem` taking both `item` and `displayText`. */
+ *  `selectItem` taking both `item` and `displayText`. `selectItem` emits
+ *  `Selected({ value })` with the input resting on `displayText`; what the
+ *  selection becomes is the parent's fold to decide. */
 export const create = () => {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
     const typedUpdate = update;
+    const arrayBasedView = internalView();
+    const view = defineView((model, { maybeSelectedValue, ...baseInputs }) => arrayBasedView(model, {
+        ...baseInputs,
+        selectedValues: Option.toArray(maybeSelectedValue),
+    }));
     return {
-        view: internalView(),
+        view,
         update: typedUpdate,
-        selectItem: (model, item, displayText) => typedUpdate(model, SelectedItem({ item, displayText })),
+        selectItem: (model, item, displayText) => typedUpdate(model, SelectedItem({ item, displayText, wasSelected: false })),
         open: model => typedUpdate(model, Opened({ maybeActiveItemIndex: Option.none() })),
-        close: model => typedUpdate(model, Closed()),
-        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
-        reflectSelectedItem: reflectSelectedItem,
+        close: (model, restingInputValue) => typedUpdate(model, Closed({ restingInputValue })),
     };
 };