foldkit 0.101.0 → 0.102.0

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

@@ -1,7 +1,8 @@
 import { Option, Schema as S } from 'effect';
 import type * as Command from '../../command/index.js';
-import { type Html } from '../../html/index.js';
-import { type BaseInitConfig, type BaseViewConfig, Closed, type Message, Opened, SelectedItem } from './shared.js';
+import type { SubmodelView } from '../../html/index.js';
+import type { Reflect } from '../../submodel/submodel.js';
+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. */
 export declare const Model: S.Struct<{
     readonly maybeSelectedItem: S.Option<S.String>;
@@ -91,9 +92,9 @@ export declare const update: (model: {
     } | {
         readonly _tag: "CompletedUnlockScroll";
     } | {
-        readonly _tag: "CompletedSetupInert";
+        readonly _tag: "CompletedInertOthers";
     } | {
-        readonly _tag: "CompletedTeardownInert";
+        readonly _tag: "CompletedRestoreInert";
     } | {
         readonly _tag: "CompletedScrollIntoView";
     } | {
@@ -150,97 +151,49 @@ export declare const update: (model: {
     } | {
         readonly _tag: "PressedToggleButton";
     }, never, never>;
-}>[]];
+}>[], Option.Option<Readonly<{
+    readonly _tag: "Selected";
+    readonly value: string;
+    readonly wasAdded: boolean;
+}>>];
+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) => readonly [Model, ReadonlyArray<Command.Command<Message>>];
+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) => readonly [Model, ReadonlyArray<Command.Command<Message>>];
-/** Programmatically selects an item in the single-select combobox, closing the combobox and returning
- *  focus commands. Use this in domain-event handlers when the combobox uses `onSelectedItem`. */
-export declare const selectItem: (model: Model, item: string, displayText: string) => readonly [Model, ReadonlyArray<Command.Command<Message>>];
-/** Configuration for rendering a single-select combobox with `view`. */
-export type ViewConfig<ParentMessage, Item extends string> = BaseViewConfig<ParentMessage, Item, Model>;
-/** Renders a headless single-select combobox with keyboard navigation, selection tracking, and aria-activedescendant focus management. */
-export declare const view: <ParentMessage, Item extends string>(config: Readonly<{
-    model: {
-        readonly maybeSelectedItem: Option.Option<string>;
-        readonly maybeSelectedDisplayText: Option.Option<string>;
-        readonly id: string;
-        readonly isOpen: boolean;
-        readonly isAnimated: boolean;
-        readonly isModal: boolean;
-        readonly nullable: boolean;
-        readonly immediate: boolean;
-        readonly selectInputOnFocus: boolean;
-        readonly animation: {
-            readonly id: string;
-            readonly isShowing: boolean;
-            readonly transitionState: "Idle" | "EnterStart" | "EnterAnimating" | "LeaveStart" | "LeaveAnimating";
-        };
-        readonly maybeActiveItemIndex: Option.Option<number>;
-        readonly activationTrigger: "Pointer" | "Keyboard";
-        readonly inputValue: string;
-        readonly maybeLastPointerPosition: Option.Option<{
-            readonly screenX: number;
-            readonly screenY: number;
-        }>;
-    };
-    toParentMessage: (message: Opened | Closed | import("./shared.js").BlurredInput | import("./shared.js").ActivatedItem | import("./shared.js").DeactivatedItem | SelectedItem | import("./shared.js").MovedPointerOverItem | import("./shared.js").RequestedItemClick | import("./shared.js").UpdatedInputValue | import("./shared.js").PressedToggleButton | {
-        readonly _tag: "CompletedAnchorCombobox";
-    } | {
-        readonly _tag: "CompletedAttachComboboxPreventBlur";
-    } | {
-        readonly _tag: "CompletedAttachComboboxSelectOnFocus";
-    } | {
-        readonly _tag: "CompletedPortalComboboxBackdrop";
-    }) => ParentMessage;
-    onSelectedItem?: (value: string) => ParentMessage;
-    items: readonly Item[];
-    itemToConfig: (item: Item, context: Readonly<{
-        isActive: boolean;
-        isDisabled: boolean;
-        isSelected: boolean;
-    }>) => Readonly<{
-        className?: string;
-        content: Html;
-    }>;
-    itemToValue: (item: Item, index: number) => string;
-    itemToDisplayText: (item: Item, index: number) => string;
-    isItemDisabled?: (item: Item, index: number) => boolean;
-    inputClassName?: string;
-    inputAttributes?: readonly import("../../html/index.js").Attribute<ParentMessage>[];
-    inputPlaceholder?: string;
-    inputWrapperClassName?: string;
-    inputWrapperAttributes?: readonly import("../../html/index.js").Attribute<ParentMessage>[];
-    itemsClassName?: string;
-    itemsAttributes?: readonly import("../../html/index.js").Attribute<ParentMessage>[];
-    itemsScrollClassName?: string;
-    itemsScrollAttributes?: readonly import("../../html/index.js").Attribute<ParentMessage>[];
-    backdropClassName?: string;
-    backdropAttributes?: readonly import("../../html/index.js").Attribute<ParentMessage>[];
-    className?: string;
-    attributes?: readonly import("../../html/index.js").Attribute<ParentMessage>[];
-    buttonContent?: Html;
-    buttonClassName?: string;
-    buttonAttributes?: readonly import("../../html/index.js").Attribute<ParentMessage>[];
-    formName?: string;
-    isDisabled?: boolean;
-    isInvalid?: boolean;
-    openOnFocus?: boolean;
-    itemGroupKey?: (item: Item, index: number) => string;
-    groupToHeading?: (groupKey: string) => Readonly<{
-        content: Html;
-        className?: string;
-    }> | undefined;
-    groupClassName?: string;
-    groupAttributes?: readonly import("../../html/index.js").Attribute<ParentMessage>[];
-    separatorClassName?: string;
-    separatorAttributes?: readonly import("../../html/index.js").Attribute<ParentMessage>[];
-    anchor?: import("./public.js").AnchorConfig;
-}>) => Html;
-/** Creates a memoized single-select combobox view. Static config is captured in a closure;
- *  only `model` and `toParentMessage` are compared per render via `createLazy`. */
-export declare const lazy: <ParentMessage, Item extends string>(staticConfig: Omit<ViewConfig<ParentMessage, Item>, "model" | "toParentMessage" | "onSelectedItem">) => ((model: Model, toParentMessage: BaseViewConfig<ParentMessage, Item, Model>["toParentMessage"]) => Html);
+export declare const close: (model: Model) => UpdateReturn;
+/** Programmatically selects an item in the single-select combobox. Emits `Selected({ value, wasAdded })`. */
+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>;
+/** Pairs the single-select combobox's `view` and `update` (and programmatic
+ *  helpers) behind a single Item-typed entry point. See `Ui.Listbox.create`
+ *  for the rationale; the combobox factory follows the same shape with
+ *  `selectItem` taking both `item` and `displayText`. */
+export declare const create: <Item extends string = string>() => Readonly<{
+    view: SubmodelView<Model, Message, BaseViewInputs<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;
+    }>>;
+}>;
+export {};
 //# sourceMappingURL=single.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"single.d.ts","sourceRoot":"","sources":["../../../src/ui/combobox/single.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,MAAM,EAAE,MAAM,IAAI,CAAC,EAAQ,MAAM,QAAQ,CAAA;AAEzD,OAAO,KAAK,KAAK,OAAO,MAAM,wBAAwB,CAAA;AACtD,OAAO,EAAE,KAAK,IAAI,EAAc,MAAM,qBAAqB,CAAA;AAE3D,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,cAAc,EACnB,MAAM,EACN,KAAK,OAAO,EACZ,MAAM,EACN,YAAY,EAKb,MAAM,aAAa,CAAA;AAIpB,uJAAuJ;AACvJ,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;EAIhB,CAAA;AAEF,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAIrC,8RAA8R;AAC9R,MAAM,MAAM,UAAU,GAAG,cAAc,GACrC,QAAQ,CAAC;IACP,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAC,CAAA;AAEJ,4IAA4I;AAC5I,eAAO,MAAM,IAAI,GAAI,QAAQ,UAAU,KAAG,KAMxC,CAAA;AAIF,uIAAuI;AACvI,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAiDjB,CAAA;AAEF;wFACwF;AACxF,eAAO,MAAM,IAAI,GACf,OAAO,KAAK,KACX,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CACK,CAAA;AAEhE;yFACyF;AACzF,eAAO,MAAM,KAAK,GAChB,OAAO,KAAK,KACX,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAClC,CAAA;AAEzB;iGACiG;AACjG,eAAO,MAAM,UAAU,GACrB,OAAO,KAAK,EACZ,MAAM,MAAM,EACZ,aAAa,MAAM,KAClB,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CACP,CAAA;AAIpD,wEAAwE;AACxE,MAAM,MAAM,UAAU,CAAC,aAAa,EAAE,IAAI,SAAS,MAAM,IAAI,cAAc,CACzE,aAAa,EACb,IAAI,EACJ,KAAK,CACN,CAAA;AAED,0IAA0I;AAC1I,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAOf,CAAA;AAEF;mFACmF;AACnF,eAAO,MAAM,IAAI,GAAI,aAAa,EAAE,IAAI,SAAS,MAAM,EACrD,cAAc,IAAI,CAChB,UAAU,CAAC,aAAa,EAAE,IAAI,CAAC,EAC/B,OAAO,GAAG,iBAAiB,GAAG,gBAAgB,CAC/C,KACA,CAAC,CACF,KAAK,EAAE,KAAK,EACZ,eAAe,EAAE,cAAc,CAC7B,aAAa,EACb,IAAI,EACJ,KAAK,CACN,CAAC,iBAAiB,CAAC,KACjB,IAAI,CAoBR,CAAA"}
+{"version":3,"file":"single.d.ts","sourceRoot":"","sources":["../../../src/ui/combobox/single.ts"],"names":[],"mappings":"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"}

package/dist/ui/combobox/single.js

@@ -1,7 +1,6 @@
-import { Array, Option, Schema as S, pipe } from 'effect';
-import { createLazy } from '../../html/index.js';
+import { Array, Function, Option, Schema as S, pipe } from 'effect';
 import { evo } from '../../struct/index.js';
-import { BaseModel, Closed, Opened, SelectedItem, baseInit, closedBaseModel, makeUpdate, makeView, } from './shared.js';
+import { BaseModel, 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. */
 export const Model = S.Struct({
@@ -32,7 +31,8 @@ export const update = makeUpdate({
     },
     handleSelectedItem: (model, item, displayText, context) => {
         const isAlreadySelected = Option.exists(model.maybeSelectedItem, selectedItem => selectedItem === item);
-        const nextModel = model.nullable && isAlreadySelected
+        const nullableDeselect = model.nullable && isAlreadySelected;
+        const nextModel = nullableDeselect
             ? evo(closedBaseModel(model), {
                 inputValue: () => '',
                 maybeSelectedItem: () => Option.none(),
@@ -46,6 +46,7 @@ export const update = makeUpdate({
         return [
             nextModel,
             pipe(Array.getSomes([context.maybeUnlockScroll, context.maybeRestoreInert]), Array.prepend(context.focusInput)),
+            Option.some(SharedSelected({ value: item, wasAdded: !nullableDeselect })),
         ];
     },
     handleImmediateActivation: (model, item, displayText) => evo(model, {
@@ -59,21 +60,47 @@ export const open = (model) => update(model, Opened({ maybeActiveItemIndex: Opti
 /** 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, closing the combobox and returning
- *  focus commands. Use this in domain-event handlers when the combobox uses `onSelectedItem`. */
+/** Programmatically selects an item in the single-select combobox. Emits `Selected({ value, wasAdded })`. */
 export const selectItem = (model, item, displayText) => update(model, SelectedItem({ item, displayText }));
-/** Renders a headless single-select combobox with keyboard navigation, selection tracking, and aria-activedescendant focus management. */
-export const view = makeView({
+/** 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,
 });
-/** Creates a memoized single-select combobox view. Static config is captured in a closure;
- *  only `model` and `toParentMessage` are compared per render via `createLazy`. */
-export const lazy = (staticConfig) => {
-    const lazyView = createLazy();
-    return (model, toParentMessage) => lazyView((currentModel, currentToParentMessage) => view({
-        ...staticConfig,
-        model: currentModel,
-        toParentMessage: currentToParentMessage,
-    }), [model, toParentMessage]);
+/** Pairs the single-select combobox's `view` and `update` (and programmatic
+ *  helpers) behind a single Item-typed entry point. See `Ui.Listbox.create`
+ *  for the rationale; the combobox factory follows the same shape with
+ *  `selectItem` taking both `item` and `displayText`. */
+export const create = () => {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const typedUpdate = update;
+    return {
+        view: internalView(),
+        update: typedUpdate,
+        selectItem: (model, item, displayText) => typedUpdate(model, SelectedItem({ item, displayText })),
+        open: model => typedUpdate(model, Opened({ maybeActiveItemIndex: Option.none() })),
+        close: model => typedUpdate(model, Closed()),
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        reflectSelectedItem: reflectSelectedItem,
+    };
 };