@typed/ui 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/Checkbox.js

@@ -0,0 +1,140 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { RefSubject } from "@typed/fx";
+import { EventHandler, html } from "@typed/template";
+import * as Dom from "./Dom.js";
+/** Schema used to encode and hydrate checkbox state.
+ * @remarks
+ * ## Why
+ * A shared schema keeps server and client state shape identical.
+ * ## Ownership and lifetime
+ * The schema is immutable and acquires no resources.
+ * @since 1.0.0
+ * @category schemas
+ */
+export const StateSchema = Schema.Struct({
+    checked: Schema.Literals([true, false, "mixed"]),
+});
+/** Creates hydrated, renderer-independent checkbox state.
+ * @remarks
+ * ## Why
+ * State transitions remain testable without rendering and can be consumed by
+ * any UI producer.
+ * ## Ownership and lifetime
+ * The caller's Effect Scope owns the hydrated RefSubject and its subscriptions.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Checkbox from "@typed/ui/Checkbox"
+ *
+ * const program = Effect.gen(function* () {
+ *   return yield* Checkbox.makeState({ checked: "mixed" })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export function makeState(initial = {}) {
+    return RefSubject.hydrate(StateSchema, { checked: initial.checked ?? false });
+}
+/** Sets the checkbox state to a boolean or mixed value.
+ * @remarks
+ * ## Why
+ * A single atomic RefSubject update keeps DOM properties and ARIA state aligned.
+ * ## Ownership and lifetime
+ * The Effect uses the existing subject lifetime and acquires no new resource.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Checkbox from "@typed/ui/Checkbox"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Checkbox.makeState()
+ *   yield* Checkbox.setChecked(state, true)
+ * })
+ * ```
+ * @since 1.0.0
+ * @category state
+ */
+export function setChecked(state, checked) {
+    return RefSubject.update(state, (current) => ({ ...current, checked }));
+}
+/** Toggles checked to false and false or mixed to true.
+ * @remarks
+ * ## Why
+ * User activation of an indeterminate checkbox resolves to a concrete checked
+ * state, matching native input behavior.
+ * ## Ownership and lifetime
+ * The Effect updates the existing RefSubject and acquires no resource.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Checkbox from "@typed/ui/Checkbox"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Checkbox.makeState({ checked: "mixed" })
+ *   yield* Checkbox.toggle(state)
+ * })
+ * ```
+ * @since 1.0.0
+ * @category state
+ */
+export function toggle(state) {
+    return RefSubject.update(state, (current) => ({
+        ...current,
+        checked: current.checked === true ? false : true,
+    }));
+}
+function internalProps(options) {
+    const checked = RefSubject.map(options.state, (state) => state.checked === true);
+    const indeterminate = RefSubject.map(options.state, (state) => state.checked === "mixed");
+    const onChange = EventHandler.make(Effect.fn((event) => setChecked(options.state, Dom.currentTarget(event).checked)));
+    return ({ property }) => ({
+        type: "checkbox",
+        "aria-checked": RefSubject.map(options.state, (state) => state.checked),
+        "?checked": checked,
+        ".checked": checked,
+        "?disabled": property("disabled", false),
+        "?required": property("required", false),
+        ".indeterminate": indeterminate,
+        onchange: onChange,
+        ref: options.state,
+    });
+}
+/** Renders a native checkbox input synchronized with hydrated state.
+ * @remarks
+ * ## Why
+ * Native keyboard, form, disabled, required, and accessibility behavior remain
+ * available while state is exposed through RefSubject.
+ * ## Ownership and lifetime
+ * Running the Fx installs native listeners and state subscriptions in its
+ * Scope. A custom host must apply `type`, checked, indeterminate, ARIA, and ref
+ * props; only one hydration owner may be composed for the element.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Checkbox from "@typed/ui/Checkbox"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Checkbox.makeState()
+ *   return Checkbox.Input({ state })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export function Input(options, host) {
+    return Dom.renderHost()(options, host, internalProps(options), "", (i) => {
+        return html `<input ...${i} />`;
+    });
+}
+/** Canonical component alias for `Input`.
+ * @remarks
+ * ## Why
+ * The alias provides the widget name while retaining the explicit input API.
+ * ## Ownership and lifetime
+ * It has exactly the same Scope and native-element ownership as `Input`.
+ * @since 1.0.0
+ * @category aliases
+ */
+export const Checkbox = Input;

package/dist/Collection.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Collection is the scoped registry shared by composite widgets. Registration order is not
+ * navigation order: byDomOrder reads the mounted nodes with compareDocumentPosition, and each
+ * register Effect removes its own item when that Effect's Scope closes.
+ *
+ * @remarks
+ * The module keeps policy, state transitions, and DOM rendering separable so applications can use
+ * the state and pure operations without mounting UI, or supply custom hosts without replacing native
+ * events and browser-owned focus.
+ *
+ * @since 1.0.0
+ * @category modules
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Scope from "effect/Scope";
+import { RefSubject } from "@typed/fx";
+/**
+ * Public Collection.Item behavioral model.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The public model lets custom composites reuse Collection's deterministic policy without copying
+ * an internal shape.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration is data or schema metadata and acquires no resources.
+ *
+ * ## Example
+ *
+ * Import with `import type { Item } from "@typed/ui/Collection";` Extend the [Collection.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FCollection%23makeState). A registered value can retain
+ * its real DOM identity:
+ * `const item: Item<string> = { id: "save", value: "save", element: document.createElement("button") }`.
+ * @since 1.0.0
+ * @category models
+ */
+export interface Item<Value = unknown, Element extends object = globalThis.Element> {
+    /**
+     * Stable id used for collection identity and ARIA relationships.
+     * @since 1.0.0
+     * @category models
+     */
+    readonly id: string;
+    /**
+     * Mounted element handle used for DOM ordering, focus, and scrolling.
+     * @since 1.0.0
+     * @category models
+     */
+    readonly element?: Element;
+    /**
+     * Flag used by collection movement and widget handlers to skip activation by default.
+     * @since 1.0.0
+     * @category models
+     */
+    readonly disabled?: boolean;
+    /**
+     * Whether the item participates as a submenu entry.
+     * @since 1.0.0
+     * @category models
+     */
+    readonly submenu?: boolean;
+    /**
+     * Search text used by typeahead independently of rendered markup.
+     * @since 1.0.0
+     * @category models
+     */
+    readonly textValue?: string;
+    /**
+     * Current semantic value selected or edited by the widget.
+     * @since 1.0.0
+     * @category models
+     */
+    readonly value?: Value;
+}
+/**
+ * Complete renderer-independent state for Collection.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Applications can inspect, update, and test Collection behavior without mounting or coupling the
+ * state to a renderer.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration is data or schema metadata and acquires no resources.
+ *
+ * ## Example
+ *
+ * Import with `import type { State } from "@typed/ui/Collection";` Extend the [Collection.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FCollection%23makeState). Collection state is an
+ * immutable sequence: `const snapshot: State<string> = [{ id: "save", value: "save" }]`.
+ * @since 1.0.0
+ * @category models
+ */
+export type State<Value = unknown, Element extends object = globalThis.Element> = readonly Item<Value, Element>[];
+/**
+ * Creates hydrated Collection state. The collection starts with the supplied immutable item array,
+ * or empty.
+ *
+ * @remarks
+ * ## Why
+ *
+ * State and collection ownership can be composed and tested independently from any renderer.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Effect creates the RefSubject when run. That state is renderer-independent;
+ * collection registrations belong to the separate Scope that runs register or ref, not to state
+ * creation.
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect";
+ * import * as Collection from "@typed/ui/Collection";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* Collection.makeState<string>();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare function makeState<Value = unknown, Element extends object = globalThis.Element>(initial?: State<Value, Element>): Effect.Effect<RefSubject.RefSubject<State<Value, Element>>, never, Scope.Scope>;
+/**
+ * Upserts an item immediately and installs a finalizer in the Scope that runs this Effect; the
+ * finalizer removes only that exact registration.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Collection's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * Registration is owned by the Scope in which the registration Effect runs. Closing that Scope
+ * removes the exact registered item; creating the collection or state does not own this cleanup.
+ *
+ * ## Example
+ *
+ * Import with `import { register } from "@typed/ui/Collection";` Extend the [Collection.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FCollection%23makeState). Inside the linked Effect
+ * program invoke `yield* register(collection, { id: "save", value: "save" })`, then read the
+ * collection to observe the inserted item.
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare function register<Value, Element extends object, E, R>(collection: RefSubject.RefSubject<State<Value, Element>, E, R>, item: Item<Value, Element>): Effect.Effect<void, E, R | Scope.Scope>;
+/**
+ * Registers a mounted element and removes it automatically with the Scope in which the returned
+ * Effect is run.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Collection's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * Registration is owned by the Scope in which the registration Effect runs. Closing that Scope
+ * removes the exact registered item; creating the collection or state does not own this cleanup.
+ *
+ * ## Example
+ *
+ * Import with `import { ref } from "@typed/ui/Collection";` Extend the [Collection.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FCollection%23makeState). Inside the linked Effect
+ * program create `const attach = ref(collection, { id: "save", value: "save" })`, then run `yield*
+ * attach(document.createElement("button"))` and read the collection before Scope close.
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare function ref<Value, Element extends object, E, R>(collection: RefSubject.RefSubject<State<Value, Element>, E, R>, item: Omit<Item<Value, Element>, "element">): (element: Element) => Effect.Effect<void, E, R | Scope.Scope>;
+/**
+ * Removes every registered item with the supplied id and retains the remaining order.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Collection's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Effect performs the update or DOM side effect only when run, preserves the declared
+ * error and service channels, and retains no resources after completion.
+ *
+ * ## Example
+ *
+ * Import with `import { unregister } from "@typed/ui/Collection";` Extend the [Collection.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FCollection%23makeState). Inside the linked Effect
+ * program first register `"save"`, run `yield* unregister(collection, "save")`, then read the
+ * collection to observe that only the matching id was removed.
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare function unregister<Value, Element extends object, E, R>(collection: RefSubject.RefSubject<State<Value, Element>, E, R>, id: string): Effect.Effect<void, E, R>;
+/**
+ * Returns a new array excluding only items whose disabled flag is exactly true.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Collection from "@typed/ui/Collection";
+ *
+ * const enabled = Collection.enabledItems([{ id: "a" }, { id: "b", disabled: true }]);
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare function enabledItems<ItemType extends Item<unknown, object>>(items: readonly ItemType[]): readonly ItemType[];
+/**
+ * Returns a sorted copy using compareDocumentPosition; items without comparable mounted elements
+ * retain an equivalent ordering position.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Collection from "@typed/ui/Collection";
+ *
+ * const ordered = Collection.byDomOrder([{ id: "body", element: document.body }]);
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare function byDomOrder<ItemType extends Item<unknown, object>>(items: readonly ItemType[]): readonly ItemType[];
+//# sourceMappingURL=Collection.d.ts.map

package/dist/Collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Collection.d.ts","sourceRoot":"","sources":["../src/Collection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,OAAO,SAAS,MAAM,GAAG,UAAU,CAAC,OAAO;IAChF;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,KAAK,CAAC,KAAK,GAAG,OAAO,EAAE,OAAO,SAAS,MAAM,GAAG,UAAU,CAAC,OAAO,IAAI,SAAS,IAAI,CAC7F,KAAK,EACL,OAAO,CACR,EAAE,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,SAAS,CAAC,KAAK,GAAG,OAAO,EAAE,OAAO,SAAS,MAAM,GAAG,UAAU,CAAC,OAAO,EACpF,OAAO,GAAE,KAAK,CAAC,KAAK,EAAE,OAAO,CAAM,GAClC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAGjF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,EAC1D,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9D,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,GACzB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAczC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,wBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,EACrD,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9D,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,GAC1C,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAE/D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,EAC5D,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9D,EAAE,EAAE,MAAM,GACT,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAI3B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,SAAS,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,EACjE,KAAK,EAAE,SAAS,QAAQ,EAAE,GACzB,SAAS,QAAQ,EAAE,CAErB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,QAAQ,SAAS,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,EAC/D,KAAK,EAAE,SAAS,QAAQ,EAAE,GACzB,SAAS,QAAQ,EAAE,CAWrB"}

package/dist/Collection.js

@@ -0,0 +1,218 @@
+/**
+ * Collection is the scoped registry shared by composite widgets. Registration order is not
+ * navigation order: byDomOrder reads the mounted nodes with compareDocumentPosition, and each
+ * register Effect removes its own item when that Effect's Scope closes.
+ *
+ * @remarks
+ * The module keeps policy, state transitions, and DOM rendering separable so applications can use
+ * the state and pure operations without mounting UI, or supply custom hosts without replacing native
+ * events and browser-owned focus.
+ *
+ * @since 1.0.0
+ * @category modules
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import * as Scope from "effect/Scope";
+import { RefSubject } from "@typed/fx";
+import * as Equivalence from "effect/Equivalence";
+/**
+ * Creates hydrated Collection state. The collection starts with the supplied immutable item array,
+ * or empty.
+ *
+ * @remarks
+ * ## Why
+ *
+ * State and collection ownership can be composed and tested independently from any renderer.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Effect creates the RefSubject when run. That state is renderer-independent;
+ * collection registrations belong to the separate Scope that runs register or ref, not to state
+ * creation.
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect";
+ * import * as Collection from "@typed/ui/Collection";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* Collection.makeState<string>();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export function makeState(initial = []) {
+    // DOM elements are runtime handles; structural equality would traverse browser internals.
+    return RefSubject.make(initial, { eq: Equivalence.Array(itemEquivalence()) });
+}
+/**
+ * Upserts an item immediately and installs a finalizer in the Scope that runs this Effect; the
+ * finalizer removes only that exact registration.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Collection's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * Registration is owned by the Scope in which the registration Effect runs. Closing that Scope
+ * removes the exact registered item; creating the collection or state does not own this cleanup.
+ *
+ * ## Example
+ *
+ * Import with `import { register } from "@typed/ui/Collection";` Extend the [Collection.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FCollection%23makeState). Inside the linked Effect
+ * program invoke `yield* register(collection, { id: "save", value: "save" })`, then read the
+ * collection to observe the inserted item.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function register(collection, item) {
+    return Effect.gen(function* () {
+        yield* RefSubject.update(collection, (items) => upsert(items, item)).pipe(Effect.asVoid);
+        const services = yield* Effect.context();
+        const scope = yield* Effect.scope;
+        yield* Scope.addFinalizer(scope, unregisterRegistered(collection, item).pipe(Effect.provide(services), Effect.ignore({ log: true })));
+    });
+}
+/**
+ * Registers a mounted element and removes it automatically with the Scope in which the returned
+ * Effect is run.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Collection's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * Registration is owned by the Scope in which the registration Effect runs. Closing that Scope
+ * removes the exact registered item; creating the collection or state does not own this cleanup.
+ *
+ * ## Example
+ *
+ * Import with `import { ref } from "@typed/ui/Collection";` Extend the [Collection.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FCollection%23makeState). Inside the linked Effect
+ * program create `const attach = ref(collection, { id: "save", value: "save" })`, then run `yield*
+ * attach(document.createElement("button"))` and read the collection before Scope close.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function ref(collection, item) {
+    return Effect.fn((element) => register(collection, { ...item, element }));
+}
+/**
+ * Removes every registered item with the supplied id and retains the remaining order.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The operation exposes Collection's transition directly so callers can compose it in Effect
+ * programs and native event handlers.
+ *
+ * ## Ownership and lifetime
+ *
+ * The returned Effect performs the update or DOM side effect only when run, preserves the declared
+ * error and service channels, and retains no resources after completion.
+ *
+ * ## Example
+ *
+ * Import with `import { unregister } from "@typed/ui/Collection";` Extend the [Collection.makeState
+ * runnable setup](/reference/%40typed%2Fui%2FCollection%23makeState). Inside the linked Effect
+ * program first register `"save"`, run `yield* unregister(collection, "save")`, then read the
+ * collection to observe that only the matching id was removed.
+ * @since 1.0.0
+ * @category combinators
+ */
+export function unregister(collection, id) {
+    return RefSubject.update(collection, (items) => items.filter((item) => item.id !== id)).pipe(Effect.asVoid);
+}
+/**
+ * Returns a new array excluding only items whose disabled flag is exactly true.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Collection from "@typed/ui/Collection";
+ *
+ * const enabled = Collection.enabledItems([{ id: "a" }, { id: "b", disabled: true }]);
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function enabledItems(items) {
+    return items.filter((item) => item.disabled !== true);
+}
+/**
+ * Returns a sorted copy using compareDocumentPosition; items without comparable mounted elements
+ * retain an equivalent ordering position.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Separating this deterministic policy from event wiring lets applications test it directly and
+ * reuse it in custom composites.
+ *
+ * ## Ownership and lifetime
+ *
+ * This is a synchronous calculation. It acquires no resources and does not mutate the input array,
+ * state, event, or DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Collection from "@typed/ui/Collection";
+ *
+ * const ordered = Collection.byDomOrder([{ id: "body", element: document.body }]);
+ * ```
+ * @since 1.0.0
+ * @category combinators
+ */
+export function byDomOrder(items) {
+    return items.toSorted((left, right) => {
+        if (left.element === undefined || right.element === undefined)
+            return 0;
+        const compareDocumentPosition = Reflect.get(left.element, "compareDocumentPosition");
+        if (typeof compareDocumentPosition !== "function")
+            return 0;
+        const position = compareDocumentPosition.call(left.element, right.element);
+        if (position & 2)
+            return 1;
+        if (position & 4)
+            return -1;
+        return 0;
+    });
+}
+function unregisterRegistered(collection, item) {
+    return RefSubject.update(collection, (items) => items.filter((current) => current.id !== item.id || current !== item)).pipe(Effect.asVoid);
+}
+function upsert(items, item) {
+    const index = items.findIndex((current) => current.id === item.id);
+    return index === -1 ? [...items, item] : items.toSpliced(index, 1, item);
+}
+function itemEquivalence() {
+    return Equivalence.make((left, right) => left.id === right.id &&
+        left.element === right.element &&
+        left.disabled === right.disabled &&
+        left.submenu === right.submenu &&
+        left.textValue === right.textValue &&
+        Equal.equals(left.value, right.value));
+}