@foldkit/ui 0.112.0

package/dist/combobox/single.d.ts

@@ -0,0 +1,198 @@
+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. */
+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;
+    readonly isModal: S.Boolean;
+    readonly nullable: S.Boolean;
+    readonly immediate: S.Boolean;
+    readonly selectInputOnFocus: S.Boolean;
+    readonly animation: S.Struct<{
+        readonly id: S.String;
+        readonly isShowing: S.Boolean;
+        readonly transitionState: S.Literals<readonly ["Idle", "EnterStart", "EnterAnimating", "LeaveStart", "LeaveAnimating"]>;
+    }>;
+    readonly maybeActiveItemIndex: S.Option<S.Number>;
+    readonly activationTrigger: S.Literals<readonly ["Pointer", "Keyboard"]>;
+    readonly inputValue: S.String;
+    readonly maybeLastPointerPosition: S.Option<S.Struct<{
+        readonly screenX: S.Number;
+        readonly screenY: S.Number;
+    }>>;
+}>;
+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. */
+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). */
+export declare const update: (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;
+    }>;
+}, message: Message) => readonly [{
+    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;
+    }>;
+}, readonly Readonly<{
+    name: string;
+    args?: Record<string, unknown>;
+    effect: import("effect/Effect").Effect<{
+        readonly _tag: "CompletedLockScroll";
+    } | {
+        readonly _tag: "CompletedUnlockScroll";
+    } | {
+        readonly _tag: "CompletedInertOthers";
+    } | {
+        readonly _tag: "CompletedRestoreInert";
+    } | {
+        readonly _tag: "Closed";
+    } | {
+        readonly _tag: "Opened";
+        readonly maybeActiveItemIndex: Option.Option<number>;
+    } | {
+        readonly _tag: "BlurredInput";
+    } | {
+        readonly _tag: "ActivatedItem";
+        readonly index: number;
+        readonly activationTrigger: "Pointer" | "Keyboard";
+        readonly maybeImmediateSelection: Option.Option<{
+            readonly item: string;
+            readonly displayText: string;
+        }>;
+    } | {
+        readonly _tag: "DeactivatedItem";
+    } | {
+        readonly _tag: "SelectedItem";
+        readonly item: string;
+        readonly displayText: string;
+    } | {
+        readonly _tag: "MovedPointerOverItem";
+        readonly index: number;
+        readonly screenX: number;
+        readonly screenY: number;
+    } | {
+        readonly _tag: "RequestedItemClick";
+        readonly index: number;
+    } | {
+        readonly _tag: "CompletedFocusInput";
+    } | {
+        readonly _tag: "CompletedScrollIntoView";
+    } | {
+        readonly _tag: "CompletedClickItem";
+    } | {
+        readonly _tag: "CompletedAnchorCombobox";
+    } | {
+        readonly _tag: "CompletedAttachComboboxPreventBlur";
+    } | {
+        readonly _tag: "CompletedAttachComboboxSelectOnFocus";
+    } | {
+        readonly _tag: "CompletedPortalComboboxBackdrop";
+    } | {
+        readonly _tag: "GotAnimationMessage";
+        readonly message: {
+            readonly _tag: "Showed";
+        } | {
+            readonly _tag: "Hid";
+        } | {
+            readonly _tag: "AdvancedAnimationFrame";
+        } | {
+            readonly _tag: "EndedAnimation";
+        };
+    } | {
+        readonly _tag: "UpdatedInputValue";
+        readonly value: string;
+    } | {
+        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) => 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 })`. */
+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 `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/combobox/single.d.ts.map

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

package/dist/combobox/single.js

@@ -0,0 +1,106 @@
+import { Array, Function, 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';
+// 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({
+    ...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),
+});
+// UPDATE
+/** Processes a combobox message and returns the next model and commands. Closes the combobox on selection (single-select behavior). */
+export const update = makeUpdate({
+    handleClose: model => {
+        if (model.nullable && model.inputValue === '') {
+            return evo(closedBaseModel(model), {
+                maybeSelectedItem: () => Option.none(),
+                maybeSelectedDisplayText: () => Option.none(),
+                inputValue: () => '',
+            });
+        }
+        return evo(closedBaseModel(model), {
+            inputValue: () => Option.getOrElse(model.maybeSelectedDisplayText, () => ''),
+        });
+    },
+    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),
+            });
+        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, {
+        maybeSelectedItem: () => Option.some(item),
+        maybeSelectedDisplayText: () => Option.some(displayText),
+    }),
+});
+/** 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,
+});
+/** 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`. */
+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,
+    };
+};