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

package/dist/Popover.d.ts

@@ -0,0 +1,241 @@
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import * as Schema from "effect/Schema";
+import type { Fx } from "@typed/fx/Fx";
+import { RefSubject } from "@typed/fx";
+import { EventHandler, type Renderable, type RenderEvent, type RenderTemplate } from "@typed/template";
+import * as Dom from "./Dom.js";
+import type { HostResult } from "./Dom/Types.js";
+/** Current renderer-independent popover visibility.
+ * @remarks
+ * ## Why
+ * Open state can be controlled and tested without rendering the top layer.
+ * ## Ownership and lifetime
+ * Plain data retains no resources; RefSubject lifetime is Scope-owned.
+ * @since 1.0.0
+ * @category state
+ */
+export interface State {
+    /** Whether native popover content should be open.
+     * @remarks
+     * ## Why
+     * The value coordinates trigger ARIA state and native Popover API state.
+     * ## Ownership and lifetime
+     * Plain state acquires no resources.
+     * @since 1.0.0
+     * @category state
+     */
+    readonly open: boolean;
+}
+/** Optional initial popover visibility.
+ * @remarks
+ * ## Why
+ * A false default gives SSR and hydration a deterministic closed snapshot.
+ * ## Ownership and lifetime
+ * Configuration is inert.
+ * @since 1.0.0
+ * @category state
+ */
+export interface InitialState {
+    /** Initial open state, defaulting to false.
+     * @remarks
+     * ## Why
+     * The value seeds the serializable hydration contract.
+     * ## Ownership and lifetime
+     * Plain data retains no resources.
+     * @since 1.0.0
+     * @category state
+     */
+    readonly open?: boolean;
+}
+/** Schema for serialized popover state.
+ * @remarks
+ * ## Why
+ * A shared boolean shape keeps server and browser hydration compatible.
+ * ## Ownership and lifetime
+ * The immutable schema acquires no resources.
+ * @since 1.0.0
+ * @category schemas
+ */
+export declare const StateSchema: Schema.Struct<{
+    readonly open: Schema.Boolean;
+}>;
+/** Creates hydrated popover state.
+ * @remarks
+ * ## Why
+ * Applications can own and test visibility independently of a component.
+ * ## Ownership and lifetime
+ * The calling Effect Scope owns the returned RefSubject.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Popover from "@typed/ui/Popover"
+ *
+ * const program = Effect.gen(function* () {
+ *   return yield* Popover.makeState()
+ * })
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare function makeState(initial?: InitialState): Effect.Effect<RefSubject.HydratedRefSubject<{
+    readonly open: boolean;
+}, Schema.SchemaError, never, never>, never, Scope.Scope>;
+/** Sets popover visibility atomically.
+ * @remarks
+ * ## Why
+ * Explicit state transitions coordinate trigger and content without hidden
+ * component-local state.
+ * ## Ownership and lifetime
+ * The Effect uses the existing RefSubject lifetime and acquires no resource.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Popover from "@typed/ui/Popover"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Popover.makeState()
+ *   yield* Popover.setOpen(state, true)
+ * })
+ * ```
+ * @since 1.0.0
+ * @category state
+ */
+export declare function setOpen<E, R>(state: RefSubject.RefSubject<State, E, R>, open: boolean): Effect.Effect<State, E, R>;
+/** Options for the native popover trigger.
+ * @remarks
+ * ## Why
+ * The trigger exposes native target attributes when an id is supplied and a
+ * state-driven fallback otherwise.
+ * ## Ownership and lifetime
+ * Options are inert; rendering owns listeners/subscriptions by Scope.
+ * @since 1.0.0
+ * @category models
+ */
+export interface TriggerOptions extends Dom.HostOptions<HTMLButtonElement> {
+    /** Hydrated state shared with popover content.
+     * @remarks
+     * ## Why
+     * It drives `aria-expanded` and fallback activation from one source.
+     * ## Ownership and lifetime
+     * The trigger borrows state; its original Scope owns it.
+     * @since 1.0.0
+     * @category state
+     */
+    readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
+    /** Id of content targeted through native `popovertarget`.
+     * @remarks
+     * ## Why
+     * Native targeting lets the browser run the Popover API lifecycle directly.
+     * ## Ownership and lifetime
+     * The string is reflected and retains no resources.
+     * @since 1.0.0
+     * @category relationships
+     */
+    readonly controls?: string;
+    /** Visible trigger content and accessible name.
+     * @remarks
+     * ## Why
+     * A trigger needs a discoverable accessible name.
+     * ## Ownership and lifetime
+     * Dynamic content follows the trigger Scope.
+     * @since 1.0.0
+     * @category content
+     */
+    readonly content: Renderable.Any;
+}
+declare function triggerInternalProps<const Options extends TriggerOptions>(options: Options): ({ property }: Dom.InternalPropsHelpers<Options>) => {
+    readonly type: "button";
+    readonly "aria-expanded": RefSubject.Computed<boolean, Schema.SchemaError, never>;
+    readonly popovertarget: Exclude<Dom.Property<Options, "controls">, Dom.Nullish> | undefined;
+    readonly popovertargetaction: "show" | undefined;
+    readonly onclick: Effect.Effect<State, Schema.SchemaError, never> | undefined;
+    readonly onkeydown: EventHandler.EventHandler<KeyboardEvent, Schema.SchemaError, never>;
+};
+type TriggerInternalProps<Options extends TriggerOptions> = ReturnType<ReturnType<typeof triggerInternalProps<Options>>>;
+/** Renders a native button that opens popover content.
+ * @remarks
+ * ## Why
+ * It preserves button keyboard behavior, native target commands, real DOM
+ * events, and an explicit state fallback when no target id is supplied.
+ * ## Ownership and lifetime
+ * Running the Fx owns reactive ARIA state and listeners in its Scope. A custom
+ * host must preserve button type, target props, `aria-expanded`, and handlers.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Popover from "@typed/ui/Popover"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Popover.makeState()
+ *   return Popover.Trigger({ state, controls: "account", content: "Account" })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export declare function Trigger<const Options extends TriggerOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, TriggerInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+/** Options for manually controlled native popover content.
+ * @remarks
+ * ## Why
+ * Content and state remain explicit while the browser owns top-layer behavior.
+ * ## Ownership and lifetime
+ * Options are inert; rendering owns the native ref and subscriptions by Scope.
+ * @since 1.0.0
+ * @category models
+ */
+export interface ContentOptions extends Dom.HostOptions<HTMLDivElement> {
+    /** Hydrated state synchronized with native popover visibility.
+     * @remarks
+     * ## Why
+     * Native toggle events and application updates converge on one source.
+     * ## Ownership and lifetime
+     * The content borrows the state; its original Scope owns it.
+     * @since 1.0.0
+     * @category state
+     */
+    readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
+    /** Content rendered in the top layer.
+     * @remarks
+     * ## Why
+     * Renderable output retains Typed error and service channels.
+     * ## Ownership and lifetime
+     * Dynamic content follows the content Scope.
+     * @since 1.0.0
+     * @category content
+     */
+    readonly content: Renderable.Any;
+}
+declare function contentInternalProps<const Options extends ContentOptions>(options: Options): () => {
+    readonly popover: "manual";
+    readonly onkeydown: EventHandler.EventHandler<KeyboardEvent, Schema.SchemaError, never>;
+    readonly onbeforetoggle: EventHandler.EventHandler<Event, Schema.SchemaError, never>;
+    readonly ontoggle: EventHandler.EventHandler<Event, Schema.SchemaError, never>;
+    readonly ref: import("./Dom/Refs.js").ComposedRef<RefSubject.HydratedRefSubject<State, Schema.SchemaError, never, never>, (element: HTMLElement) => Effect.Effect<void, Schema.SchemaError, Scope.Scope>> | undefined;
+};
+type ContentInternalProps<Options extends ContentOptions> = ReturnType<ReturnType<typeof contentInternalProps<Options>>>;
+/** Renders manually controlled native popover content.
+ * @remarks
+ * ## Why
+ * The component delegates top-layer lifecycle to the Popover API, synchronizes
+ * real `beforetoggle`/`toggle` events, and handles Escape through native events.
+ * ## Ownership and lifetime
+ * Running the Fx owns listeners and the NativePopover observer in its Effect
+ * Scope. A custom host must preserve `popover="manual"`, toggle handlers, and
+ * the single composed hydration ref.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Popover from "@typed/ui/Popover"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Popover.makeState()
+ *   return Popover.Content({ state, content: "Preferences" })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export declare function Content<const Options extends ContentOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, ContentInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+export {};
+//# sourceMappingURL=Popover.d.ts.map

package/dist/Popover.d.ts.map

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

package/dist/Popover.js

@@ -0,0 +1,141 @@
+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";
+import * as NativePopover from "./NativePopover.js";
+/** Schema for serialized popover state.
+ * @remarks
+ * ## Why
+ * A shared boolean shape keeps server and browser hydration compatible.
+ * ## Ownership and lifetime
+ * The immutable schema acquires no resources.
+ * @since 1.0.0
+ * @category schemas
+ */
+export const StateSchema = Schema.Struct({ open: Schema.Boolean });
+/** Creates hydrated popover state.
+ * @remarks
+ * ## Why
+ * Applications can own and test visibility independently of a component.
+ * ## Ownership and lifetime
+ * The calling Effect Scope owns the returned RefSubject.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Popover from "@typed/ui/Popover"
+ *
+ * const program = Effect.gen(function* () {
+ *   return yield* Popover.makeState()
+ * })
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+export function makeState(initial = {}) {
+    return RefSubject.hydrate(StateSchema, { open: initial.open ?? false });
+}
+/** Sets popover visibility atomically.
+ * @remarks
+ * ## Why
+ * Explicit state transitions coordinate trigger and content without hidden
+ * component-local state.
+ * ## Ownership and lifetime
+ * The Effect uses the existing RefSubject lifetime and acquires no resource.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Popover from "@typed/ui/Popover"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Popover.makeState()
+ *   yield* Popover.setOpen(state, true)
+ * })
+ * ```
+ * @since 1.0.0
+ * @category state
+ */
+export function setOpen(state, open) {
+    return RefSubject.update(state, (current) => ({ ...current, open }));
+}
+function triggerInternalProps(options) {
+    const open = RefSubject.map(options.state, (state) => state.open);
+    return ({ property }) => ({
+        type: "button",
+        "aria-expanded": open,
+        popovertarget: property("controls", undefined),
+        popovertargetaction: options.controls === undefined ? undefined : "show",
+        onclick: options.controls === undefined ? setOpen(options.state, true) : undefined,
+        onkeydown: EventHandler.make(Effect.fn(function* (event) {
+            if (event.key !== "Escape")
+                return;
+            event.preventDefault();
+            yield* setOpen(options.state, false);
+        })),
+    });
+}
+/** Renders a native button that opens popover content.
+ * @remarks
+ * ## Why
+ * It preserves button keyboard behavior, native target commands, real DOM
+ * events, and an explicit state fallback when no target id is supplied.
+ * ## Ownership and lifetime
+ * Running the Fx owns reactive ARIA state and listeners in its Scope. A custom
+ * host must preserve button type, target props, `aria-expanded`, and handlers.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Popover from "@typed/ui/Popover"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Popover.makeState()
+ *   return Popover.Trigger({ state, controls: "account", content: "Account" })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export function Trigger(options, host) {
+    return Dom.renderHost()(options, host, triggerInternalProps(options), options.content, (props, content) => html `<button ...${props}>${content}</button>`);
+}
+function contentInternalProps(options) {
+    return () => ({
+        popover: "manual",
+        onkeydown: EventHandler.make(Effect.fn(function* (event) {
+            if (event.key !== "Escape")
+                return;
+            event.preventDefault();
+            yield* setOpen(options.state, false);
+        })),
+        onbeforetoggle: EventHandler.make(Effect.fn((event) => setOpen(options.state, Dom.toggleState(event) === "open"))),
+        ontoggle: EventHandler.make(Effect.fn((event) => setOpen(options.state, Dom.toggleState(event) === "open"))),
+        ref: Dom.composeRefs(options.state, NativePopover.ref(options.state)),
+    });
+}
+/** Renders manually controlled native popover content.
+ * @remarks
+ * ## Why
+ * The component delegates top-layer lifecycle to the Popover API, synchronizes
+ * real `beforetoggle`/`toggle` events, and handles Escape through native events.
+ * ## Ownership and lifetime
+ * Running the Fx owns listeners and the NativePopover observer in its Effect
+ * Scope. A custom host must preserve `popover="manual"`, toggle handlers, and
+ * the single composed hydration ref.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Popover from "@typed/ui/Popover"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Popover.makeState()
+ *   return Popover.Content({ state, content: "Preferences" })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category components
+ */
+export function Content(options, host) {
+    return Dom.renderHost()(options, host, contentInternalProps(options), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}