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

package/dist/Meter.d.ts

@@ -1,68 +1,43 @@
+/**
+ * A non-interactive native measurement within a known range.
+ * Threshold options communicate preferred regions; they do not execute alert policies.
+ *
+ * Read the [Meter guide](/explore/ui-meter) for a complete example.
+ *
+ * [APG interaction reference](https://www.w3.org/WAI/ARIA/apg/patterns/meter/).
+ * @since 1.0.0
+ * @category Overview
+ * @packageDocumentation
+ */
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { RefSubject } from "@typed/fx";
 import { type Renderable } from "@typed/template";
 import * as Dom from "./Dom.js";
 import type { HostResult } from "./Dom/Types.js";
-/** Current value displayed by the meter.
- * @remarks
- * ## Why
- * Renderer-independent state can be updated and tested before a meter mounts.
- * ## Ownership and lifetime
- * Plain state acquires no resources; the hydrated RefSubject owns observation.
- * @since 1.0.0
- * @category state
+/**
  */
 export interface State {
-    /** Finite scalar reflected to the native meter value.
-     * @remarks
-     * ## Why
-     * One value drives DOM output and state consumers consistently.
-     * ## Ownership and lifetime
-     * Plain data retains no resources.
-     * @since 1.0.0
-     * @category state
+    /**
      */
     readonly value: number;
 }
-/** Initial finite meter value.
- * @remarks
- * ## Why
- * Explicit input makes the hydration snapshot deterministic.
- * ## Ownership and lifetime
- * Configuration is inert and copied into state.
- * @since 1.0.0
- * @category state
+/**
  */
 export interface InitialState {
-    /** Value used for the initial snapshot.
-     * @remarks
-     * ## Why
-     * The native meter needs a concrete value independent of its range metadata.
-     * ## Ownership and lifetime
-     * Plain data acquires no resources.
-     * @since 1.0.0
-     * @category state
+    /**
      */
     readonly value: number;
 }
-/** Schema for serializing finite meter state.
- * @remarks
- * ## Why
- * Rejecting non-finite values keeps SSR and native DOM output valid.
- * ## Ownership and lifetime
- * The immutable schema acquires no resources.
- * @since 1.0.0
- * @category schemas
+/**
  */
 export declare const StateSchema: Schema.Struct<{
     readonly value: Schema.Finite;
 }>;
-/** Creates hydrated meter state.
+/**
+ * Creates hydrated meter state.
  * @remarks
- * ## Why
  * The state remains testable and reusable without rendering a UI component.
- * ## Ownership and lifetime
  * The caller's Effect Scope owns the hydrated RefSubject.
  * @example
  * ```ts
@@ -74,110 +49,64 @@ export declare const StateSchema: Schema.Struct<{
  * })
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category State construction
  */
 export declare function makeState(initial: InitialState): Effect.Effect<RefSubject.HydratedRefSubject<{
     readonly value: number;
 }, Schema.SchemaError, never, never>, never, import("effect/Scope").Scope>;
-/** Updates the displayed meter value.
- * @remarks
- * ## Why
- * State transitions stay outside rendering and preserve typed error/services.
- * ## Ownership and lifetime
- * The Effect uses the existing RefSubject lifetime and acquires no resource.
- * @example
- * ```ts
- * import { Effect } from "effect"
- * import * as Meter from "@typed/ui/Meter"
+/**
+ * Assigns the displayed measurement without clamping it to the meter range.
  *
- * const program = Effect.gen(function* () {
- *   const state = yield* Meter.makeState({ value: 0 })
- *   yield* Meter.setValue(state, 0.75)
- * })
- * ```
+ * @remarks
+ * Keep measurement units consistent with min/max and threshold options. This operation does not
+ * execute threshold actions or validate the preferred range.
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export declare function setValue<E, R>(state: RefSubject.RefSubject<State, E, R>, value: number): Effect.Effect<State, E, R>;
-/** Native meter range, threshold, content, and state options.
- * @remarks
- * ## Why
- * These mirror the platform meter element rather than reimplementing its
- * accessibility and range interpretation.
- * ## Ownership and lifetime
- * Options are inert; rendering owns reactive subscriptions by Scope.
- * @since 1.0.0
- * @category models
+/**
  */
 export interface MeterOptions extends Dom.HostOptions<HTMLMeterElement> {
-    /** Hydrated value state borrowed by the element.
-     * @remarks
-     * ## Why
-     * One source keeps the native value and application state aligned.
-     * ## Ownership and lifetime
-     * Its original Scope owns it; the component only subscribes while mounted.
+    /**
+     * Hydrated value state borrowed by the element.
      * @since 1.0.0
-     * @category state
+     * @category State connection
      */
     readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
-    /** Lower bound of the measured range.
-     * @remarks
-     * ## Why
-     * Native meter semantics use the bound to interpret `value`.
-     * ## Ownership and lifetime
-     * Dynamic attributes follow the component Scope.
+    /**
+     * Lower bound of the measured range.
      * @since 1.0.0
-     * @category attributes
+     * @category Numeric bounds
      */
     readonly min?: Renderable.Any<number | null | undefined>;
-    /** Upper bound of the measured range.
-     * @remarks
-     * ## Why
-     * Native meter semantics use the bound to interpret `value`.
-     * ## Ownership and lifetime
-     * Dynamic attributes follow the component Scope.
+    /**
+     * Upper bound of the measured range.
      * @since 1.0.0
-     * @category attributes
+     * @category Numeric bounds
      */
     readonly max?: Renderable.Any<number | null | undefined>;
-    /** Boundary below which values are considered low.
-     * @remarks
-     * ## Why
-     * The browser uses this native threshold with `high` and `optimum`.
-     * ## Ownership and lifetime
-     * Dynamic attributes follow the component Scope.
+    /**
+     * Boundary below which values are considered low.
      * @since 1.0.0
-     * @category attributes
+     * @category Measurement thresholds
      */
     readonly low?: Renderable.Any<number | null | undefined>;
-    /** Boundary above which values are considered high.
-     * @remarks
-     * ## Why
-     * It preserves native threshold semantics and accessibility exposure.
-     * ## Ownership and lifetime
-     * Dynamic attributes follow the component Scope.
+    /**
+     * Boundary above which values are considered high.
      * @since 1.0.0
-     * @category attributes
+     * @category Measurement thresholds
      */
     readonly high?: Renderable.Any<number | null | undefined>;
-    /** Preferred value within the meter range.
-     * @remarks
-     * ## Why
-     * Native rendering interprets threshold quality relative to this value.
-     * ## Ownership and lifetime
-     * Dynamic attributes follow the component Scope.
+    /**
+     * Preferred value within the meter range.
      * @since 1.0.0
-     * @category attributes
+     * @category Measurement thresholds
      */
     readonly optimum?: Renderable.Any<number | null | undefined>;
-    /** Fallback content rendered inside the meter.
-     * @remarks
-     * ## Why
-     * Text content provides useful output where meter rendering is unavailable.
-     * ## Ownership and lifetime
-     * Dynamic content follows the component Scope.
+    /**
+     * Fallback content rendered inside the meter.
      * @since 1.0.0
-     * @category content
+     * @category Rendered content
      */
     readonly content?: Renderable.Any;
 }
@@ -191,26 +120,37 @@ declare function internalProps<const Options extends MeterOptions>(options: Opti
     readonly ref: RefSubject.HydratedRefSubject<State, Schema.SchemaError, never, never>;
 };
 type MeterInternalProps<Options extends MeterOptions> = ReturnType<ReturnType<typeof internalProps<Options>>>;
-/** Renders a native `<meter>` synchronized with hydrated state.
+/**
+ * Renders a native meter for a measurement within a known range.
+ *
  * @remarks
- * ## Why
- * The platform owns range semantics and accessibility while Typed composes
- * reactive state and custom hosts around the real element.
- * ## Ownership and lifetime
- * Running the Fx owns attribute/state subscriptions until its Scope closes. A
- * custom host must preserve native meter attributes and the hydration ref.
+ * Supply a label and coherent min/max/low/high/optimum values. The browser presents thresholds;
+ * the component does not trigger alerts when they are crossed. Use a slider for editing or a
+ * progress element for operation completion. The meter has no keyboard action.
+ *
  * @example
  * ```ts
- * import { Effect } from "effect"
- * import * as Meter from "@typed/ui/Meter"
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { component } from "@typed/ui/Component";
+ * import * as Meter from "@typed/ui/Meter";
  *
- * const program = Effect.gen(function* () {
- *   const state = yield* Meter.makeState({ value: 64 })
- *   return Meter.Meter({ state, min: 0, max: 100 })
- * })
+ * export const StorageUsage = component(function* () {
+ *   const state = yield* Meter.makeState({ value: 64 });
+ *   const description = RefSubject.map(state, ({ value }) => `${value} GB of 100 GB used`);
+ *   return html`<section>
+ *     <label for="storage-meter">Storage used</label>
+ *     ${Meter.Meter({
+ *       state, min: 0, max: 100, low: 60, high: 85, optimum: 0,
+ *       content: description,
+ *       props: { id: "storage-meter", "aria-valuetext": description },
+ *     })}
+ *     <p>${description}</p>
+ *   </section>`;
+ * });
  * ```
  * @since 1.0.0
- * @category components
+ * @category Controls
  */
 export declare function Meter<const Options extends MeterOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, MeterInternalProps<Options>>, Options["content"], Host>): import("./Dom/Types.js").HostComponent<Host | Options>;
 export {};

package/dist/Meter.d.ts.map

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

package/dist/Meter.js

@@ -2,21 +2,13 @@ import * as Schema from "effect/Schema";
 import { RefSubject } from "@typed/fx";
 import { html } from "@typed/template";
 import * as Dom from "./Dom.js";
-/** Schema for serializing finite meter state.
- * @remarks
- * ## Why
- * Rejecting non-finite values keeps SSR and native DOM output valid.
- * ## Ownership and lifetime
- * The immutable schema acquires no resources.
- * @since 1.0.0
- * @category schemas
+/**
  */
 export const StateSchema = Schema.Struct({ value: Schema.Finite });
-/** Creates hydrated meter state.
+/**
+ * Creates hydrated meter state.
  * @remarks
- * ## Why
  * The state remains testable and reusable without rendering a UI component.
- * ## Ownership and lifetime
  * The caller's Effect Scope owns the hydrated RefSubject.
  * @example
  * ```ts
@@ -28,29 +20,19 @@ export const StateSchema = Schema.Struct({ value: Schema.Finite });
  * })
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category State construction
  */
 export function makeState(initial) {
     return RefSubject.hydrate(StateSchema, initial);
 }
-/** Updates the displayed meter value.
- * @remarks
- * ## Why
- * State transitions stay outside rendering and preserve typed error/services.
- * ## Ownership and lifetime
- * The Effect uses the existing RefSubject lifetime and acquires no resource.
- * @example
- * ```ts
- * import { Effect } from "effect"
- * import * as Meter from "@typed/ui/Meter"
+/**
+ * Assigns the displayed measurement without clamping it to the meter range.
  *
- * const program = Effect.gen(function* () {
- *   const state = yield* Meter.makeState({ value: 0 })
- *   yield* Meter.setValue(state, 0.75)
- * })
- * ```
+ * @remarks
+ * Keep measurement units consistent with min/max and threshold options. This operation does not
+ * execute threshold actions or validate the preferred range.
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export function setValue(state, value) {
     return RefSubject.update(state, (current) => ({ ...current, value }));
@@ -66,26 +48,37 @@ function internalProps(options) {
         ref: options.state,
     });
 }
-/** Renders a native `<meter>` synchronized with hydrated state.
+/**
+ * Renders a native meter for a measurement within a known range.
+ *
  * @remarks
- * ## Why
- * The platform owns range semantics and accessibility while Typed composes
- * reactive state and custom hosts around the real element.
- * ## Ownership and lifetime
- * Running the Fx owns attribute/state subscriptions until its Scope closes. A
- * custom host must preserve native meter attributes and the hydration ref.
+ * Supply a label and coherent min/max/low/high/optimum values. The browser presents thresholds;
+ * the component does not trigger alerts when they are crossed. Use a slider for editing or a
+ * progress element for operation completion. The meter has no keyboard action.
+ *
  * @example
  * ```ts
- * import { Effect } from "effect"
- * import * as Meter from "@typed/ui/Meter"
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { component } from "@typed/ui/Component";
+ * import * as Meter from "@typed/ui/Meter";
  *
- * const program = Effect.gen(function* () {
- *   const state = yield* Meter.makeState({ value: 64 })
- *   return Meter.Meter({ state, min: 0, max: 100 })
- * })
+ * export const StorageUsage = component(function* () {
+ *   const state = yield* Meter.makeState({ value: 64 });
+ *   const description = RefSubject.map(state, ({ value }) => `${value} GB of 100 GB used`);
+ *   return html`<section>
+ *     <label for="storage-meter">Storage used</label>
+ *     ${Meter.Meter({
+ *       state, min: 0, max: 100, low: 60, high: 85, optimum: 0,
+ *       content: description,
+ *       props: { id: "storage-meter", "aria-valuetext": description },
+ *     })}
+ *     <p>${description}</p>
+ *   </section>`;
+ * });
  * ```
  * @since 1.0.0
- * @category components
+ * @category Controls
  */
 export function Meter(options, host) {
     return Dom.renderHost()(options, host, internalProps(options), options.content ?? "", (props, content) => {

package/dist/NativeDetails.d.ts

@@ -34,7 +34,7 @@ interface State {
  * ```
  *
  * @since 1.0.0
- * @category refs
+ * @category Native synchronization
  */
 export declare function ref<S extends State, E, R>(state: RefSubject.RefSubject<S, E, R>): (element: HTMLDetailsElement) => Effect.Effect<void, E, R | Scope.Scope>;
 export {};

package/dist/NativeDetails.js

@@ -30,7 +30,7 @@ import { Fx } from "@typed/fx";
  * ```
  *
  * @since 1.0.0
- * @category refs
+ * @category Native synchronization
  */
 export function ref(state) {
     return Effect.fn((element) => Effect.asVoid(Effect.forkScoped(Fx.observe(state, Effect.fn((value) => Effect.sync(() => {

package/dist/NativeDialog.d.ts

@@ -12,7 +12,7 @@ interface State {
  * ## Ownership and lifetime
  * Options are inert and retain no resources.
  * @since 1.0.0
- * @category models
+ * @category Native display options
  */
 export interface Options {
     /** Whether opening uses the modal top layer; defaults to true.
@@ -23,7 +23,7 @@ export interface Options {
      * ## Ownership and lifetime
      * The flag is read during synchronization and retains no resources.
      * @since 1.0.0
-     * @category behavior
+     * @category Native display options
      */
     readonly modal?: boolean;
 }
@@ -39,8 +39,10 @@ export interface Options {
  *
  * ## Ownership and lifetime
  *
- * Applying the ref forks an observer in the current Effect Scope. Finalization
- * interrupts that observer but does not close state owned elsewhere or remove
+ * Applying the ref forks an observer in the current Effect Scope. Modal opening
+ * waits for a detached host to connect; a newer state or Scope finalization cancels
+ * that pending connection check. Hidden documents may defer the check until animation
+ * frames resume. Finalization does not close state owned elsewhere or remove
  * the element. `Dialog.Content` handles native `cancel`, `close`, and `toggle`
  * events and composes exactly one hydration owner.
  *
@@ -57,7 +59,7 @@ export interface Options {
  * ```
  *
  * @since 1.0.0
- * @category refs
+ * @category Native synchronization
  */
 export declare function ref<S extends State, E, R>(state: RefSubject.RefSubject<S, E, R>, options?: Options): (element: HTMLDialogElement) => Effect.Effect<void, E, R | Scope.Scope>;
 export {};

package/dist/NativeDialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NativeDialog.d.ts","sourceRoot":"","sources":["../src/NativeDialog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAM,UAAU,EAAE,MAAM,WAAW,CAAC;AAE3C,UAAU,KAAK;IACb,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACtB;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,EAAE,CAAC,EACvC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACrC,OAAO,GAAE,OAAY,GACpB,CAAC,OAAO,EAAE,iBAAiB,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAWzE"}
+{"version":3,"file":"NativeDialog.d.ts","sourceRoot":"","sources":["../src/NativeDialog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAM,UAAU,EAAE,MAAM,WAAW,CAAC;AAE3C,UAAU,KAAK;IACb,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACtB;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,EAAE,CAAC,EACvC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACrC,OAAO,GAAE,OAAY,GACpB,CAAC,OAAO,EAAE,iBAAiB,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAqBzE"}

package/dist/NativeDialog.js

@@ -1,4 +1,5 @@
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import { Fx } from "@typed/fx";
 /**
  * Creates a scoped ref that drives a real `HTMLDialogElement` from state.
@@ -12,8 +13,10 @@ import { Fx } from "@typed/fx";
  *
  * ## Ownership and lifetime
  *
- * Applying the ref forks an observer in the current Effect Scope. Finalization
- * interrupts that observer but does not close state owned elsewhere or remove
+ * Applying the ref forks an observer in the current Effect Scope. Modal opening
+ * waits for a detached host to connect; a newer state or Scope finalization cancels
+ * that pending connection check. Hidden documents may defer the check until animation
+ * frames resume. Finalization does not close state owned elsewhere or remove
  * the element. `Dialog.Content` handles native `cancel`, `close`, and `toggle`
  * events and composes exactly one hydration owner.
  *
@@ -30,10 +33,45 @@ import { Fx } from "@typed/fx";
  * ```
  *
  * @since 1.0.0
- * @category refs
+ * @category Native synchronization
  */
 export function ref(state, options = {}) {
-    return Effect.fn((element) => Effect.asVoid(Effect.forkScoped(Fx.observe(state, Effect.fn((value) => Effect.sync(() => synchronize(element, value.open, options)))))));
+    return Effect.fn(function* (element) {
+        let pending;
+        yield* Effect.forkScoped(Fx.observe(state, Effect.fn(function* (value) {
+            if (pending !== undefined) {
+                const previous = pending;
+                pending = undefined;
+                yield* Fiber.interrupt(previous);
+            }
+            const update = Effect.sync(() => synchronize(element, value.open, options));
+            if (value.open && options.modal !== false && !element.isConnected) {
+                pending = yield* Effect.forkScoped(Effect.andThen(whenConnected(element), update));
+            }
+            else {
+                // Complete connected transitions before queued native lifecycle events
+                // can reflect an older open state back into the application.
+                yield* update;
+            }
+        })));
+    });
+}
+// Template refs run before their host is inserted. Native showModal requires a connected element.
+function whenConnected(element) {
+    return Effect.callback((resume) => {
+        if (element.isConnected) {
+            resume(Effect.void);
+            return;
+        }
+        const check = () => {
+            if (element.isConnected)
+                resume(Effect.void);
+            else
+                frame = requestAnimationFrame(check);
+        };
+        let frame = requestAnimationFrame(check);
+        return Effect.sync(() => cancelAnimationFrame(frame));
+    });
 }
 function synchronize(element, open, options) {
     if (open) {

package/dist/NativePopover.d.ts

@@ -16,9 +16,11 @@ interface State {
  *
  * ## Ownership and lifetime
  *
- * Applying the ref forks one observer in the current Effect Scope. Closing the
- * Scope interrupts it; it does not remove the host or close the caller-owned
- * state. The host must support the Popover API and retain its `popover`
+ * Applying the ref forks one observer in the current Effect Scope. Opening
+ * waits for a detached host to connect. A newer state or Scope finalization
+ * cancels that pending connection check; hidden documents may defer it until
+ * animation frames resume. Closing the Scope interrupts observation without
+ * removing the host or closing caller-owned state. The host must support the Popover API and retain its `popover`
  * attribute. Only one hydration owner may be composed for the element.
  *
  * @example
@@ -34,7 +36,7 @@ interface State {
  * ```
  *
  * @since 1.0.0
- * @category refs
+ * @category Native synchronization
  */
 export declare function ref<S extends State, E, R>(state: RefSubject.RefSubject<S, E, R>): (element: HTMLElement) => Effect.Effect<void, E, R | Scope.Scope>;
 export {};

package/dist/NativePopover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NativePopover.d.ts","sourceRoot":"","sources":["../src/NativePopover.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAM,UAAU,EAAE,MAAM,WAAW,CAAC;AAE3C,UAAU,KAAK;IACb,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,EAAE,CAAC,EACvC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACpC,CAAC,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAWnE"}
+{"version":3,"file":"NativePopover.d.ts","sourceRoot":"","sources":["../src/NativePopover.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAM,UAAU,EAAE,MAAM,WAAW,CAAC;AAE3C,UAAU,KAAK;IACb,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,EAAE,CAAC,EACvC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACpC,CAAC,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAqBnE"}

package/dist/NativePopover.js

@@ -1,4 +1,5 @@
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import { Fx } from "@typed/fx";
 /**
  * Creates a scoped ref that synchronizes state with the native Popover API.
@@ -12,9 +13,11 @@ import { Fx } from "@typed/fx";
  *
  * ## Ownership and lifetime
  *
- * Applying the ref forks one observer in the current Effect Scope. Closing the
- * Scope interrupts it; it does not remove the host or close the caller-owned
- * state. The host must support the Popover API and retain its `popover`
+ * Applying the ref forks one observer in the current Effect Scope. Opening
+ * waits for a detached host to connect. A newer state or Scope finalization
+ * cancels that pending connection check; hidden documents may defer it until
+ * animation frames resume. Closing the Scope interrupts observation without
+ * removing the host or closing caller-owned state. The host must support the Popover API and retain its `popover`
  * attribute. Only one hydration owner may be composed for the element.
  *
  * @example
@@ -30,10 +33,45 @@ import { Fx } from "@typed/fx";
  * ```
  *
  * @since 1.0.0
- * @category refs
+ * @category Native synchronization
  */
 export function ref(state) {
-    return Effect.fn((element) => Effect.asVoid(Effect.forkScoped(Fx.observe(state, Effect.fn((value) => Effect.sync(() => synchronize(element, value.open)))))));
+    return Effect.fn(function* (element) {
+        let pending;
+        yield* Effect.forkScoped(Fx.observe(state, Effect.fn(function* (value) {
+            if (pending !== undefined) {
+                const previous = pending;
+                pending = undefined;
+                yield* Fiber.interrupt(previous);
+            }
+            const update = Effect.sync(() => synchronize(element, value.open));
+            if (value.open && !element.isConnected) {
+                pending = yield* Effect.forkScoped(Effect.andThen(whenConnected(element), update));
+            }
+            else {
+                // Connected transitions stay in the observer: Menu/Select can focus
+                // their now-visible items immediately after updating open state.
+                yield* update;
+            }
+        })));
+    });
+}
+// Template refs run before insertion; native showPopover requires a connected host.
+function whenConnected(element) {
+    return Effect.callback((resume) => {
+        if (element.isConnected) {
+            resume(Effect.void);
+            return;
+        }
+        const check = () => {
+            if (element.isConnected)
+                resume(Effect.void);
+            else
+                frame = requestAnimationFrame(check);
+        };
+        let frame = requestAnimationFrame(check);
+        return Effect.sync(() => cancelAnimationFrame(frame));
+    });
 }
 function synchronize(element, open) {
     if (open) {