@typed/ui 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/Toolbar.js

@@ -0,0 +1,187 @@
+/**
+ * Toolbar is a roving-focus composite with toolbar and button roles. Orientation and RTL control
+ * Arrow-key order; Home and End select the document-order endpoints.
+ *
+ * @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.
+ *
+ * Learn the interaction in the [Toolbar guide](/explore/ui-toolbar).
+ *
+ * @since 1.0.0
+ * @category modules
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import { RefSubject } from "@typed/fx";
+import { EventHandler, html, } from "@typed/template";
+import * as Collection from "./Collection.js";
+import * as Composite from "./Composite.js";
+import * as Dom from "./Dom.js";
+/**
+ * Effect Schema used by makeState to encode, decode, and hydrate Toolbar state.
+ *
+ * @remarks
+ * @example
+ * ```ts
+ * import * as Schema from "effect/Schema";
+ * import * as Toolbar from "@typed/ui/Toolbar";
+ *
+ * const decodeState = Schema.decodeUnknownEffect(Toolbar.StateSchema);
+ * ```
+ * @since 1.0.0
+ * @category Command focus
+ */
+export const StateSchema = Composite.StateSchema;
+/**
+ * Creates hydrated Toolbar state. Uses Composite defaults unless overridden.
+ *
+ * @remarks
+ * 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 Toolbar from "@typed/ui/Toolbar";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const state = yield* Toolbar.makeState({});
+ *     const collection = yield* Toolbar.makeCollection();
+ *     return { state: yield* state, collection: yield* collection };
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category Command focus
+ */
+export function makeState(initial = {}) {
+    return Composite.makeState(initial);
+}
+/**
+ * Creates a scoped Collection for Toolbar items.
+ *
+ * @remarks
+ * The returned Effect allocates the RefSubject in the caller's Scope. Each later registration is
+ * owned by the Scope that runs register, independently of this construction Effect.
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect";
+ * import * as Toolbar from "@typed/ui/Toolbar";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const collection = yield* Toolbar.makeCollection();
+ *     return yield* collection;
+ *   }),
+ * );
+ * ```
+ * @since 1.0.0
+ * @category Command registration
+ */
+export const makeCollection = Collection.makeState;
+function rootProps(options) {
+    const onfocus = options.collection === undefined
+        ? undefined
+        : Effect.gen(function* () {
+            if ((yield* options.state).activeId !== null)
+                return;
+            yield* Composite.moveAndFocus({ state: options.state, collection: options.collection }, "first");
+        });
+    const onkeydown = options.collection === undefined
+        ? undefined
+        : EventHandler.make(Effect.fn(function* (event) {
+            if (event.key === "Enter" || event.key === " ") {
+                const activeId = (yield* options.state).activeId;
+                const item = activeId === null
+                    ? undefined
+                    : (yield* options.collection).find((candidate) => candidate.id === activeId);
+                const click = item?.disabled === true ? undefined : Reflect.get(item?.element ?? {}, "click");
+                if (typeof click === "function") {
+                    event.preventDefault();
+                    yield* Effect.sync(() => click.call(item.element));
+                }
+                return;
+            }
+            const direction = Composite.keyMove(event, yield* options.state);
+            if (direction === undefined)
+                return;
+            event.preventDefault();
+            yield* Composite.moveAndFocus({ state: options.state, collection: options.collection }, direction);
+        }));
+    return ({ property }) => ({
+        role: "toolbar",
+        "aria-label": property("label", undefined),
+        "aria-orientation": RefSubject.map(options.state, (state) => state.orientation),
+        tabindex: Composite.rootTabIndex(options.state),
+        onfocus,
+        onkeydown,
+        ref: options.state,
+    });
+}
+/**
+ * Renders the toolbar root and moves roving focus through registered items in DOM order.
+ *
+ * @remarks
+ * The returned Fx installs DOM refs, native listeners, state subscriptions, and optional
+ * collection registrations only when rendered. The rendering Scope removes those resources;
+ * unrelated nodes and attributes remain caller-owned.
+ *
+ * @since 1.0.0
+ * @category Toolbar surface
+ */
+export function Root(options, host) {
+    return Dom.renderHost()(options, host, rootProps(options), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}
+/**
+ * Consumer-facing alias of the canonical Toolbar component with identical behavior and lifetime.
+ *
+ * @remarks
+ * The alias acquires nothing. Rendering it has exactly the canonical component's Scope and DOM
+ * ownership contract.
+ *
+ * @since 1.0.0
+ * @category Toolbar surface
+ */
+export const Toolbar = Root;
+function itemProps(options) {
+    const activate = options.disabled === true
+        ? Effect.void
+        : RefSubject.update(options.state, (state) => ({ ...state, activeId: options.id }));
+    const register = options.collection === undefined
+        ? undefined
+        : Collection.ref(options.collection, {
+            id: options.id,
+            value: options.id,
+            textValue: options.textValue ?? options.id,
+            disabled: options.disabled,
+        });
+    return () => ({
+        id: options.id,
+        role: "button",
+        "aria-disabled": options.disabled ?? false,
+        tabindex: Composite.tabIndex(options.state, options.id),
+        onfocus: activate,
+        ref: Dom.composeRefs(register, options.ref),
+    });
+}
+/**
+ * Renders and optionally registers a toolbar button; focus activates it unless disabled.
+ *
+ * @remarks
+ * The returned Fx installs DOM refs, native listeners, state subscriptions, and optional
+ * collection registrations only when rendered. The rendering Scope removes those resources;
+ * unrelated nodes and attributes remain caller-owned.
+ *
+ * @since 1.0.0
+ * @category Toolbar commands
+ */
+export function Item(options, host) {
+    return Dom.renderHost()(options, host, itemProps(options), options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}

package/dist/Tooltip.d.ts

@@ -0,0 +1,296 @@
+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 tooltip identity and visibility.
+ * @remarks
+ * ## Why
+ * A stable id connects the anchor's description relationship to native popover
+ * content while open state stays renderer-independent.
+ * ## Ownership and lifetime
+ * Plain state retains no resources; RefSubject observation is Scope-owned.
+ * @since 1.0.0
+ * @category Open state
+ */
+export interface State {
+    /** Stable id used by `aria-describedby` and tooltip content.
+     * @remarks
+     * ## Why
+     * Server and client must agree on the relationship target during hydration.
+     * ## Ownership and lifetime
+     * Plain data acquires no resources.
+     * @since 1.0.0
+     * @category Identity and relationships
+     */
+    readonly id: string;
+    /** Whether tooltip content is open.
+     * @remarks
+     * ## Why
+     * The value coordinates delayed anchor interactions and native popover state.
+     * ## Ownership and lifetime
+     * Plain data acquires no resources.
+     * @since 1.0.0
+     * @category Open state
+     */
+    readonly open: boolean;
+}
+/** Initial tooltip identity and visibility.
+ * @remarks
+ * ## Why
+ * Requiring an id makes the accessibility relationship explicit.
+ * ## Ownership and lifetime
+ * Configuration is inert.
+ * @since 1.0.0
+ * @category Open state
+ */
+export interface InitialState {
+    /** Stable tooltip id.
+     * @remarks
+     * ## Why
+     * Deterministic ids prevent SSR/client relationship drift.
+     * ## Ownership and lifetime
+     * Plain data retains no resources.
+     * @since 1.0.0
+     * @category Identity and relationships
+     */
+    readonly id: string;
+    /** Initial visibility, defaulting to false.
+     * @remarks
+     * ## Why
+     * Closed is the deterministic default before user focus or hover.
+     * ## Ownership and lifetime
+     * Plain data retains no resources.
+     * @since 1.0.0
+     * @category Open state
+     */
+    readonly open?: boolean;
+}
+/** Schema for tooltip hydration state.
+ * @remarks
+ * ## Why
+ * Shared identity/open encoding keeps SSR and browser relationships compatible.
+ * ## Ownership and lifetime
+ * The immutable schema acquires no resources.
+ * @since 1.0.0
+ * @category Open state
+ */
+export declare const StateSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly open: Schema.Boolean;
+}>;
+/** Creates hydrated tooltip state.
+ * @remarks
+ * ## Why
+ * Visibility logic can be tested without mounting an anchor or popover.
+ * ## Ownership and lifetime
+ * The calling Effect Scope owns the returned RefSubject.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Tooltip from "@typed/ui/Tooltip"
+ *
+ * const program = Effect.gen(function* () {
+ *   return yield* Tooltip.makeState({ id: "save-help" })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category Open state
+ */
+export declare function makeState(initial: InitialState): Effect.Effect<RefSubject.HydratedRefSubject<{
+    readonly id: string;
+    readonly open: boolean;
+}, Schema.SchemaError, never, never>, never, Scope.Scope>;
+/** Sets tooltip visibility.
+ * @remarks
+ * ## Why
+ * Delayed focus/hover logic converges on one explicit state transition.
+ * ## Ownership and lifetime
+ * The Effect uses the existing state Scope and acquires no resource.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Tooltip from "@typed/ui/Tooltip"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Tooltip.makeState({ id: "save-help" })
+ *   yield* Tooltip.setOpen(state, true)
+ * })
+ * ```
+ * @since 1.0.0
+ * @category Open state
+ */
+export declare function setOpen<E, R>(state: RefSubject.RefSubject<State, E, R>, open: boolean): Effect.Effect<State, E, R>;
+/** Options for a tooltip anchor host.
+ * @remarks
+ * ## Why
+ * Pointer entry works with the default span. Keyboard focus behavior requires
+ * the host itself to be focusable, for example `props: { tabindex: 0 }` or a
+ * focusable custom host; focus and blur on descendants do not bubble to it.
+ * ## Ownership and lifetime
+ * Options are inert; rendering owns listeners/timers by Scope.
+ * @since 1.0.0
+ * @category Pointer and focus anchors
+ */
+export interface AnchorOptions extends Dom.HostOptions<HTMLSpanElement> {
+    /** Hydrated state shared with tooltip content.
+     * @remarks
+     * ## Why
+     * Its id drives `aria-describedby` and its open value drives the popover.
+     * ## Ownership and lifetime
+     * The anchor borrows state; its original Scope owns it.
+     * @since 1.0.0
+     * @category State connection
+     */
+    readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
+    /** Anchor content.
+     * @remarks
+     * ## Why
+     * The anchor wraps descriptive content. A focusable descendant does not make
+     * the default span receive its non-bubbling focus and blur handlers.
+     * ## Ownership and lifetime
+     * Dynamic content follows the anchor Scope.
+     * @since 1.0.0
+     * @category Rendered content
+     */
+    readonly content: Renderable.Any;
+    /** Delay in milliseconds before opening.
+     * @remarks
+     * ## Why
+     * A delay avoids accidental tooltip activation during pointer transit.
+     * ## Ownership and lifetime
+     * Delayed Effects run inside the component interaction lifetime; newer
+     * schedules invalidate older versions.
+     * @since 1.0.0
+     * @category Interaction delays
+     */
+    readonly showDelay?: number;
+    /** Delay in milliseconds before closing.
+     * @remarks
+     * ## Why
+     * A delay prevents flicker during brief pointer movement.
+     * ## Ownership and lifetime
+     * Newer schedules invalidate older delayed updates.
+     * @since 1.0.0
+     * @category Interaction delays
+     */
+    readonly hideDelay?: number;
+}
+declare function anchorInternalProps<const Options extends AnchorOptions>(options: Options): () => {
+    readonly "aria-describedby": RefSubject.Computed<string, Schema.SchemaError, never>;
+    readonly onfocus: Effect.Effect<void, Schema.SchemaError, never>;
+    readonly onblur: Effect.Effect<void, Schema.SchemaError, never>;
+    readonly onkeydown: EventHandler.EventHandler<KeyboardEvent, Schema.SchemaError, never>;
+    readonly onmouseenter: Effect.Effect<void, Schema.SchemaError, never>;
+    readonly onmouseleave: Effect.Effect<void, Schema.SchemaError, never>;
+};
+type AnchorInternalProps<Options extends AnchorOptions> = ReturnType<ReturnType<typeof anchorInternalProps<Options>>>;
+/** Renders a tooltip anchor with pointer and optional host-focus behavior.
+ * @remarks
+ * ## Why
+ * The default host is a non-focusable `<span>`, so it provides pointer behavior
+ * only. Give that host `tabindex`, or supply a natively focusable custom host,
+ * to activate its direct focus, blur, and keydown handlers. Those events are
+ * attached to the host itself and do not observe focus on nested content.
+ * Tooltip content remains descriptive rather than an interactive dialog.
+ * ## Ownership and lifetime
+ * Running the Fx owns event listeners and dynamic relationship state in its
+ * Scope. Custom hosts must preserve `aria-describedby` and all handlers.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Tooltip from "@typed/ui/Tooltip"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Tooltip.makeState({ id: "save-help" })
+ *   return Tooltip.Anchor({
+ *     state,
+ *     content: "Save",
+ *     props: { tabindex: 0 }
+ *   })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category Pointer and focus anchors
+ */
+export declare function Anchor<const Options extends AnchorOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, AnchorInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+/** Options for native tooltip popover content.
+ * @remarks
+ * ## Why
+ * The role and native top-layer lifecycle remain explicit.
+ * ## Ownership and lifetime
+ * Options are inert; rendering owns listeners/ref observation by Scope.
+ * @since 1.0.0
+ * @category Native content host
+ */
+export interface ContentOptions extends Dom.HostOptions<HTMLDivElement> {
+    /** Hydrated state supplying content id and visibility.
+     * @remarks
+     * ## Why
+     * One source keeps ARIA relationship and native popover state aligned.
+     * ## Ownership and lifetime
+     * Content borrows state; its original Scope owns it.
+     * @since 1.0.0
+     * @category State connection
+     */
+    readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
+    /** Non-interactive explanatory tooltip content.
+     * @remarks
+     * ## Why
+     * Tooltip content describes its anchor and must not contain required controls.
+     * ## Ownership and lifetime
+     * Dynamic content follows the content Scope.
+     * @since 1.0.0
+     * @category Rendered content
+     */
+    readonly content: Renderable.Any;
+}
+declare function contentInternalProps<const Options extends ContentOptions>(options: Options): () => {
+    readonly id: RefSubject.Computed<string, Schema.SchemaError, never>;
+    readonly role: "tooltip";
+    readonly popover: "manual";
+    readonly onmouseenter: Effect.Effect<void, Schema.SchemaError, never>;
+    readonly onmouseleave: EventHandler.EventHandler<MouseEvent, Schema.SchemaError, never>;
+    readonly onkeydown: EventHandler.EventHandler<KeyboardEvent, 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 `role="tooltip"` content through the native Popover API.
+ * @remarks
+ * ## Why
+ * Native top-layer output avoids reparenting into a private portal while real
+ * toggle/mouse/keyboard events synchronize renderer-independent state.
+ * ## Ownership and lifetime
+ * Running the Fx owns listeners and NativePopover observation in its Scope. A
+ * custom host must preserve id, role, manual popover, handlers, and one
+ * hydration ref owner.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Tooltip from "@typed/ui/Tooltip"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Tooltip.makeState({ id: "save-help" })
+ *   return Tooltip.Content({ state, content: "Stores changes" })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category Native content host
+ */
+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>;
+/** Canonical widget alias for `Content`.
+ * @remarks
+ * ## Why
+ * The alias provides the widget name while `Content` names compound use.
+ * ## Ownership and lifetime
+ * It has exactly the same Scope and popover ownership as `Content`.
+ * @since 1.0.0
+ * @category Native content host
+ */
+export declare const Tooltip: typeof Content;
+export {};
+//# sourceMappingURL=Tooltip.d.ts.map

package/dist/Tooltip.d.ts.map

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

package/dist/Tooltip.js

@@ -0,0 +1,172 @@
+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 tooltip hydration state.
+ * @remarks
+ * ## Why
+ * Shared identity/open encoding keeps SSR and browser relationships compatible.
+ * ## Ownership and lifetime
+ * The immutable schema acquires no resources.
+ * @since 1.0.0
+ * @category Open state
+ */
+export const StateSchema = Schema.Struct({ id: Schema.String, open: Schema.Boolean });
+/** Creates hydrated tooltip state.
+ * @remarks
+ * ## Why
+ * Visibility logic can be tested without mounting an anchor or popover.
+ * ## Ownership and lifetime
+ * The calling Effect Scope owns the returned RefSubject.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Tooltip from "@typed/ui/Tooltip"
+ *
+ * const program = Effect.gen(function* () {
+ *   return yield* Tooltip.makeState({ id: "save-help" })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category Open state
+ */
+export function makeState(initial) {
+    return RefSubject.hydrate(StateSchema, { id: initial.id, open: initial.open ?? false });
+}
+/** Sets tooltip visibility.
+ * @remarks
+ * ## Why
+ * Delayed focus/hover logic converges on one explicit state transition.
+ * ## Ownership and lifetime
+ * The Effect uses the existing state Scope and acquires no resource.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Tooltip from "@typed/ui/Tooltip"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Tooltip.makeState({ id: "save-help" })
+ *   yield* Tooltip.setOpen(state, true)
+ * })
+ * ```
+ * @since 1.0.0
+ * @category Open state
+ */
+export function setOpen(state, open) {
+    return RefSubject.update(state, (current) => ({ ...current, open }));
+}
+const scheduleVersions = new WeakMap();
+const scheduleOpen = Effect.fn(function* (state, open, delay) {
+    const version = (scheduleVersions.get(state) ?? 0) + 1;
+    scheduleVersions.set(state, version);
+    if (delay > 0)
+        yield* Effect.sleep(delay);
+    if (scheduleVersions.get(state) === version)
+        yield* setOpen(state, open);
+});
+function anchorInternalProps(options) {
+    const id = RefSubject.map(options.state, (state) => state.id);
+    return () => ({
+        "aria-describedby": id,
+        onfocus: scheduleOpen(options.state, true, options.showDelay ?? 0),
+        onblur: scheduleOpen(options.state, false, options.hideDelay ?? 0),
+        onkeydown: EventHandler.make(Effect.fn(function* (event) {
+            if (event.key === "Escape")
+                yield* scheduleOpen(options.state, false, 0);
+        })),
+        onmouseenter: scheduleOpen(options.state, true, options.showDelay ?? 0),
+        onmouseleave: scheduleOpen(options.state, false, options.hideDelay ?? 0),
+    });
+}
+/** Renders a tooltip anchor with pointer and optional host-focus behavior.
+ * @remarks
+ * ## Why
+ * The default host is a non-focusable `<span>`, so it provides pointer behavior
+ * only. Give that host `tabindex`, or supply a natively focusable custom host,
+ * to activate its direct focus, blur, and keydown handlers. Those events are
+ * attached to the host itself and do not observe focus on nested content.
+ * Tooltip content remains descriptive rather than an interactive dialog.
+ * ## Ownership and lifetime
+ * Running the Fx owns event listeners and dynamic relationship state in its
+ * Scope. Custom hosts must preserve `aria-describedby` and all handlers.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Tooltip from "@typed/ui/Tooltip"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Tooltip.makeState({ id: "save-help" })
+ *   return Tooltip.Anchor({
+ *     state,
+ *     content: "Save",
+ *     props: { tabindex: 0 }
+ *   })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category Pointer and focus anchors
+ */
+export function Anchor(options, host) {
+    return Dom.renderHost()(options, host, anchorInternalProps(options), options.content, (props, content) => html `<span ...${props}>${content}</span>`);
+}
+function contentInternalProps(options) {
+    const id = RefSubject.map(options.state, (state) => state.id);
+    return () => ({
+        id,
+        role: "tooltip",
+        popover: "manual",
+        onmouseenter: scheduleOpen(options.state, true, 0),
+        onmouseleave: EventHandler.make(Effect.fn(function* (event) {
+            const contentId = (yield* options.state).id;
+            if (event.relatedTarget instanceof Element &&
+                event.relatedTarget.getAttribute("aria-describedby") === contentId)
+                return;
+            yield* scheduleOpen(options.state, false, 0);
+        })),
+        onkeydown: EventHandler.make(Effect.fn(function* (event) {
+            if (event.key === "Escape")
+                yield* scheduleOpen(options.state, false, 0);
+        })),
+        ontoggle: EventHandler.make(Effect.fn((event) => setOpen(options.state, Dom.toggleState(event) === "open"))),
+        ref: Dom.composeRefs(options.state, NativePopover.ref(options.state)),
+    });
+}
+/** Renders `role="tooltip"` content through the native Popover API.
+ * @remarks
+ * ## Why
+ * Native top-layer output avoids reparenting into a private portal while real
+ * toggle/mouse/keyboard events synchronize renderer-independent state.
+ * ## Ownership and lifetime
+ * Running the Fx owns listeners and NativePopover observation in its Scope. A
+ * custom host must preserve id, role, manual popover, handlers, and one
+ * hydration ref owner.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Tooltip from "@typed/ui/Tooltip"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Tooltip.makeState({ id: "save-help" })
+ *   return Tooltip.Content({ state, content: "Stores changes" })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category Native content host
+ */
+export function Content(options, host) {
+    return Dom.renderHost()(options, host, contentInternalProps(options), options.content, (props, content) => {
+        return html `<div ...${props}>${content}</div>`;
+    });
+}
+/** Canonical widget alias for `Content`.
+ * @remarks
+ * ## Why
+ * The alias provides the widget name while `Content` names compound use.
+ * ## Ownership and lifetime
+ * It has exactly the same Scope and popover ownership as `Content`.
+ * @since 1.0.0
+ * @category Native content host
+ */
+export const Tooltip = Content;