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

package/dist/Group.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Explicitly named collections of related content.
+ * Group.Label is a span; connect its ID through labelledBy rather than assuming implicit wiring.
+ *
+ * Read the [Group guide](/explore/ui-group) for a complete example.
+ *
+ * [Platform reference](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role).
+ * @since 1.0.0
+ * @category Overview
+ * @packageDocumentation
+ */
+import type * as Scope from "effect/Scope";
+import type { Fx } from "@typed/fx/Fx";
+import { type Renderable, type RenderEvent, type RenderTemplate } from "@typed/template";
+import * as Dom from "./Dom.js";
+import type { HostResult } from "./Dom/Types.js";
+/**
+ * Related content with either a direct accessible label or an external label ID.
+ *
+ * @remarks
+ * Use labelledBy when visible text already names the group; use label when that text is absent.
+ * Native fieldset/legend and composite keyboard behavior are not created by these options.
+ * @since 1.0.0
+ * @category Component options
+ */
+export interface GroupOptions extends Dom.HostOptions<HTMLDivElement> {
+    /**
+     * Renderable child content for the component host.
+     * @since 1.0.0
+     * @category Rendered content
+     */
+    readonly content: Renderable.Any;
+    /**
+     * Accessible label rendered through aria-label.
+     * @since 1.0.0
+     * @category Accessible naming
+     */
+    readonly label?: Renderable.Any<string | null | undefined>;
+    /**
+     * Id of the external element used through aria-labelledby.
+     * @since 1.0.0
+     * @category Accessible naming
+     */
+    readonly labelledBy?: Renderable.Any<string | null | undefined>;
+}
+declare function internalProps<const Options extends GroupOptions>({ property }: Dom.InternalPropsHelpers<Options>): {
+    role: string;
+    "aria-label": Exclude<Dom.Property<Options, "label">, Dom.Nullish> | undefined;
+    "aria-labelledby": Exclude<Dom.Property<Options, "labelledBy">, Dom.Nullish> | undefined;
+};
+type GroupInternalProps<Options extends GroupOptions> = ReturnType<typeof internalProps<Options>>;
+/**
+ * Renders a semantic group with an explicit accessible name.
+ *
+ * @remarks
+ * label becomes aria-label; labelledBy references existing visible text through aria-labelledby.
+ * The div does not implement fieldset disabling, toolbar navigation, or child selection. Name
+ * each interactive child independently.
+ *
+ * @example
+ * ```ts
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { Button } from "@typed/ui/Button";
+ * import { component } from "@typed/template";
+ * import * as Group from "@typed/ui/Group";
+ *
+ * export const PreviewActions = component(function* () {
+ *   const rotation = yield* RefSubject.make(45);
+ *   const scale = yield* RefSubject.make(150);
+ *   return html`<section>
+ *     <p>Rotation: ${rotation} degrees. Scale: ${scale}%.</p>
+ *     ${Group.Label({
+ *       content: "Preview controls",
+ *       props: { id: "preview-control-label", class: "control-group-label" },
+ *     })}
+ *     ${Group.Group({
+ *       labelledBy: "preview-control-label",
+ *       props: { class: "preview-actions" },
+ *       content: [
+ *         Button({ content: "Reset rotation", onclick: RefSubject.set(rotation, 0) }),
+ *         Button({ content: "Reset scale", onclick: RefSubject.set(scale, 100) }),
+ *       ],
+ *     })}
+ *   </section>`;
+ * });
+ * ```
+ * @since 1.0.0
+ * @category Structure and naming
+ */
+export declare function Group<const Options extends GroupOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, GroupInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+/**
+ * Visible span content and host props for an explicitly linked group label.
+ *
+ * @remarks
+ * Set props.id and reference it through Group.labelledBy. There is no generated ID or implicit
+ * relationship.
+ * @since 1.0.0
+ * @category Component options
+ */
+export interface LabelOptions extends Dom.HostOptions<HTMLSpanElement> {
+    /**
+     * Renderable child content for the component host.
+     * @since 1.0.0
+     * @category Rendered content
+     */
+    readonly content: Renderable.Any;
+}
+/**
+ * Renders visible group-label text in a span.
+ *
+ * @remarks
+ * Pass an ID through props and reference it from Group.labelledBy to create a relationship.
+ * Rendering this span beside a group does not connect them automatically, and it does not create
+ * heading semantics.
+ *
+ * @example
+ * ```ts
+ * import * as Group from "@typed/ui/Group";
+ *
+ * const view = Group.Label({ content: "Formatting" });
+ * ```
+ * @since 1.0.0
+ * @category Controls
+ */
+export declare function Label<const Options extends LabelOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, Record<never, never>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+export {};
+//# sourceMappingURL=Group.d.ts.map

package/dist/Group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Group.d.ts","sourceRoot":"","sources":["../src/Group.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAQ,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAa,SAAQ,GAAG,CAAC,WAAW,CAAC,cAAc,CAAC;IACnE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACjE;AAED,iBAAS,aAAa,CAAC,KAAK,CAAC,OAAO,SAAS,YAAY,EAAE,EAAE,QAAQ,EAAE,EAAE,GAAG,CAAC,oBAAoB,CAAC,OAAO,CAAC;IAEtG,IAAI;IACJ,YAAY;IACZ,iBAAiB;EAEpB;AAED,KAAK,kBAAkB,CAAC,OAAO,SAAS,YAAY,IAAI,UAAU,CAAC,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;AAElG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,OAAO,SAAS,YAAY,EAAE,KAAK,CAAC,IAAI,SAAS,UAAU,GAAG,KAAK,EAC7F,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,GAC3G,EAAE,CACH,WAAW,EACX,UAAU,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,EAChC,UAAU,CAAC,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,GAAG,cAAc,CACnE,CAQA;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAa,SAAQ,GAAG,CAAC,WAAW,CAAC,eAAe,CAAC;IACpE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,OAAO,SAAS,YAAY,EAAE,KAAK,CAAC,IAAI,SAAS,UAAU,GAAG,KAAK,EAC7F,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,GACpG,EAAE,CACH,WAAW,EACX,UAAU,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,EAChC,UAAU,CAAC,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,GAAG,cAAc,CACnE,CAQA"}

package/dist/Group.js

@@ -0,0 +1,71 @@
+import { html } from "@typed/template";
+import * as Dom from "./Dom.js";
+function internalProps({ property }) {
+    return {
+        role: "group",
+        "aria-label": property("label", undefined),
+        "aria-labelledby": property("labelledBy", undefined),
+    };
+}
+/**
+ * Renders a semantic group with an explicit accessible name.
+ *
+ * @remarks
+ * label becomes aria-label; labelledBy references existing visible text through aria-labelledby.
+ * The div does not implement fieldset disabling, toolbar navigation, or child selection. Name
+ * each interactive child independently.
+ *
+ * @example
+ * ```ts
+ * import { RefSubject } from "@typed/fx";
+ * import { html } from "@typed/template";
+ * import { Button } from "@typed/ui/Button";
+ * import { component } from "@typed/template";
+ * import * as Group from "@typed/ui/Group";
+ *
+ * export const PreviewActions = component(function* () {
+ *   const rotation = yield* RefSubject.make(45);
+ *   const scale = yield* RefSubject.make(150);
+ *   return html`<section>
+ *     <p>Rotation: ${rotation} degrees. Scale: ${scale}%.</p>
+ *     ${Group.Label({
+ *       content: "Preview controls",
+ *       props: { id: "preview-control-label", class: "control-group-label" },
+ *     })}
+ *     ${Group.Group({
+ *       labelledBy: "preview-control-label",
+ *       props: { class: "preview-actions" },
+ *       content: [
+ *         Button({ content: "Reset rotation", onclick: RefSubject.set(rotation, 0) }),
+ *         Button({ content: "Reset scale", onclick: RefSubject.set(scale, 100) }),
+ *       ],
+ *     })}
+ *   </section>`;
+ * });
+ * ```
+ * @since 1.0.0
+ * @category Structure and naming
+ */
+export function Group(options, host) {
+    return Dom.renderHost()(options, host, internalProps, options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}
+/**
+ * Renders visible group-label text in a span.
+ *
+ * @remarks
+ * Pass an ID through props and reference it from Group.labelledBy to create a relationship.
+ * Rendering this span beside a group does not connect them automatically, and it does not create
+ * heading semantics.
+ *
+ * @example
+ * ```ts
+ * import * as Group from "@typed/ui/Group";
+ *
+ * const view = Group.Label({ content: "Formatting" });
+ * ```
+ * @since 1.0.0
+ * @category Controls
+ */
+export function Label(options, host) {
+    return Dom.renderHost()(options, host, () => ({}), options.content, (props, content) => html `<span ...${props}>${content}</span>`);
+}

package/dist/Heading.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Contextual heading semantics independent of typography.
+ * The default div uses role=heading and aria-level; fixed native headings remain useful.
+ *
+ * Read the [Heading guide](/explore/ui-heading) for a complete example.
+ *
+ * [Platform reference](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role).
+ * @since 1.0.0
+ * @category Overview
+ * @packageDocumentation
+ */
+import type * as Scope from "effect/Scope";
+import type { Fx } from "@typed/fx/Fx";
+import { type Renderable, type RenderEvent, type RenderTemplate } from "@typed/template";
+import * as Dom from "./Dom.js";
+import type { HostResult } from "./Dom/Types.js";
+/**
+ */
+export interface HeadingOptions extends Dom.HostOptions<HTMLDivElement> {
+    /**
+     * Heading content and accessible name.
+     * @since 1.0.0
+     * @category Rendered content
+     */
+    readonly content: Renderable.Any;
+    /**
+     */
+    readonly level?: Renderable.Any<number | null | undefined>;
+}
+declare function internalProps<const Options extends HeadingOptions>({ property, }: Dom.InternalPropsHelpers<Options>): {
+    role: string;
+    "aria-level": 1 | Exclude<Dom.Property<Options, "level">, Dom.Nullish>;
+};
+type HeadingInternalProps<Options extends HeadingOptions> = ReturnType<typeof internalProps<Options>>;
+/**
+ * Renders a div with heading semantics and an explicit level.
+ *
+ * @remarks
+ * level defaults to one and may be reactive; it does not choose font size, infer nesting, or
+ * validate the document outline. Use native h1–h6 markup when the level is fixed. A custom host
+ * must keep its native level and aria-level consistent.
+ *
+ * @example
+ * ```ts
+ * import { html } from "@typed/template";
+ * import { Heading } from "@typed/ui/Heading";
+ *
+ * export function AccountSection(level: 2 | 3) {
+ *   return html`<section aria-labelledby="account-section-title">
+ *     ${Heading({
+ *       level,
+ *       content: "Account security",
+ *       props: { id: "account-section-title", class: "section-title" },
+ *     })}
+ *     <p>Review the devices and credentials that can access this account.</p>
+ *   </section>`;
+ * }
+ *
+ * export const AccountPage = html`<main>
+ *     <h1>Account settings</h1>
+ *     ${AccountSection(2)}
+ *   </main>`;
+ * ```
+ * @since 1.0.0
+ * @category Structure and naming
+ */
+export declare function Heading<const Options extends HeadingOptions, const Host extends HostResult = never>(options: Options, host?: Dom.HostOverride<Dom.RenderHostProps<Options, HeadingInternalProps<Options>>, Options["content"], Host>): Fx<RenderEvent, Renderable.Error<Options | Host>, Renderable.Services<Options | Host> | Scope.Scope | RenderTemplate>;
+/**
+ * Alias for `Heading` retained for level-oriented imports.
+ * @remarks
+ * The alias names the role the component plays in a contextual heading system.
+ * It has exactly the same Scope and host ownership as `Heading`.
+ * @since 1.0.0
+ * @category Aliases
+ */
+export declare const Level: typeof Heading;
+/**
+ * Descriptive alias for `Heading`.
+ * @remarks
+ * The name remains available without duplicating an implementation contract.
+ * It has exactly the same Scope and host ownership as `Heading`.
+ * @since 1.0.0
+ * @category Aliases
+ */
+export declare const HeadingLevel: typeof Heading;
+export {};
+//# sourceMappingURL=Heading.d.ts.map

package/dist/Heading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Heading.d.ts","sourceRoot":"","sources":["../src/Heading.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAQ,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;GACG;AACH,MAAM,WAAW,cAAe,SAAQ,GAAG,CAAC,WAAW,CAAC,cAAc,CAAC;IACrE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC;IACjC;OACG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CAC5D;AAED,iBAAS,aAAa,CAAC,KAAK,CAAC,OAAO,SAAS,cAAc,EAAE,EAC3D,QAAQ,GACT,EAAE,GAAG,CAAC,oBAAoB,CAAC,OAAO,CAAC;IACzB,IAAI;IAAa,YAAY;EACvC;AAED,KAAK,oBAAoB,CAAC,OAAO,SAAS,cAAc,IAAI,UAAU,CACpE,OAAO,aAAa,CAAC,OAAO,CAAC,CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,OAAO,CACrB,KAAK,CAAC,OAAO,SAAS,cAAc,EACpC,KAAK,CAAC,IAAI,SAAS,UAAU,GAAG,KAAK,EAErC,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,GAAG,CAAC,YAAY,CACrB,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC,EAC3D,OAAO,CAAC,SAAS,CAAC,EAClB,IAAI,CACL,GACA,EAAE,CACH,WAAW,EACX,UAAU,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,EAChC,UAAU,CAAC,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,GAAG,cAAc,CACnE,CAQA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,gBAAU,CAAC;AAC7B;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,gBAAU,CAAC"}

package/dist/Heading.js

@@ -0,0 +1,58 @@
+import { html } from "@typed/template";
+import * as Dom from "./Dom.js";
+function internalProps({ property, }) {
+    return { role: "heading", "aria-level": property("level", 1) };
+}
+/**
+ * Renders a div with heading semantics and an explicit level.
+ *
+ * @remarks
+ * level defaults to one and may be reactive; it does not choose font size, infer nesting, or
+ * validate the document outline. Use native h1–h6 markup when the level is fixed. A custom host
+ * must keep its native level and aria-level consistent.
+ *
+ * @example
+ * ```ts
+ * import { html } from "@typed/template";
+ * import { Heading } from "@typed/ui/Heading";
+ *
+ * export function AccountSection(level: 2 | 3) {
+ *   return html`<section aria-labelledby="account-section-title">
+ *     ${Heading({
+ *       level,
+ *       content: "Account security",
+ *       props: { id: "account-section-title", class: "section-title" },
+ *     })}
+ *     <p>Review the devices and credentials that can access this account.</p>
+ *   </section>`;
+ * }
+ *
+ * export const AccountPage = html`<main>
+ *     <h1>Account settings</h1>
+ *     ${AccountSection(2)}
+ *   </main>`;
+ * ```
+ * @since 1.0.0
+ * @category Structure and naming
+ */
+export function Heading(options, host) {
+    return Dom.renderHost()(options, host, internalProps, options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}
+/**
+ * Alias for `Heading` retained for level-oriented imports.
+ * @remarks
+ * The alias names the role the component plays in a contextual heading system.
+ * It has exactly the same Scope and host ownership as `Heading`.
+ * @since 1.0.0
+ * @category Aliases
+ */
+export const Level = Heading;
+/**
+ * Descriptive alias for `Heading`.
+ * @remarks
+ * The name remains available without duplicating an implementation contract.
+ * It has exactly the same Scope and host ownership as `Heading`.
+ * @since 1.0.0
+ * @category Aliases
+ */
+export const HeadingLevel = Heading;

package/dist/Hovercard.d.ts

@@ -0,0 +1,297 @@
+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 hovercard identity and visibility.
+ * @remarks
+ * ## Why
+ * A stable id links the anchor to focusable native popover content while state
+ * remains renderer-independent.
+ * ## Ownership and lifetime
+ * Plain data retains no resources; RefSubject observation is Scope-owned.
+ * @since 1.0.0
+ * @category Open state
+ */
+export interface State {
+    /** Stable id used by `aria-controls` and content.
+     * @remarks
+     * ## Why
+     * Deterministic identity preserves server/client DOM relationships.
+     * ## Ownership and lifetime
+     * Plain data acquires no resources.
+     * @since 1.0.0
+     * @category Identity and relationships
+     */
+    readonly id: string;
+    /** Whether the hovercard is open.
+     * @remarks
+     * ## Why
+     * One value coordinates delayed interactions and native popover state.
+     * ## Ownership and lifetime
+     * Plain data acquires no resources.
+     * @since 1.0.0
+     * @category Open state
+     */
+    readonly open: boolean;
+}
+/** Initial hovercard identity and visibility.
+ * @remarks
+ * ## Why
+ * Requiring an id makes the anchor/content relationship explicit.
+ * ## Ownership and lifetime
+ * Configuration is inert.
+ * @since 1.0.0
+ * @category Open state
+ */
+export interface InitialState {
+    /** Stable content id.
+     * @remarks
+     * ## Why
+     * Explicit ids prevent hydration 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 deterministic before focus or hover interaction.
+     * ## Ownership and lifetime
+     * Plain data retains no resources.
+     * @since 1.0.0
+     * @category Open state
+     */
+    readonly open?: boolean;
+}
+/** Schema for hovercard hydration state.
+ * @remarks
+ * ## Why
+ * Shared identity/open encoding keeps SSR and browser state 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 hovercard state.
+ * @remarks
+ * ## Why
+ * Visibility and identity can be tested without mounting UI.
+ * ## Ownership and lifetime
+ * The calling Effect Scope owns the returned RefSubject.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Hovercard from "@typed/ui/Hovercard"
+ *
+ * const program = Effect.gen(function* () {
+ *   return yield* Hovercard.makeState({ id: "author-card" })
+ * })
+ * ```
+ * @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 hovercard visibility.
+ * @remarks
+ * ## Why
+ * Delayed focus/hover flows converge on one atomic state update.
+ * ## Ownership and lifetime
+ * The Effect uses the existing RefSubject lifetime and acquires no resource.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Hovercard from "@typed/ui/Hovercard"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Hovercard.makeState({ id: "author-card" })
+ *   yield* Hovercard.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 hovercard 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 handlers/delayed effects by Scope.
+ * @since 1.0.0
+ * @category Pointer and focus anchors
+ */
+export interface AnchorOptions extends Dom.HostOptions<HTMLSpanElement> {
+    /** Hydrated state shared with hovercard content.
+     * @remarks
+     * ## Why
+     * Its id and open state coordinate the whole compound widget.
+     * ## 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 wrapper retains nested content, but focusable descendants do not
+     * activate the default span's 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;
+    /** Milliseconds before opening.
+     * @remarks
+     * ## Why
+     * Delay filters incidental pointer transit.
+     * ## Ownership and lifetime
+     * New schedules invalidate older delayed updates.
+     * @since 1.0.0
+     * @category Interaction delays
+     */
+    readonly showDelay?: number;
+    /** Milliseconds before closing.
+     * @remarks
+     * ## Why
+     * Delay gives users time to move focus or pointer toward content.
+     * ## Ownership and lifetime
+     * New 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-controls": RefSubject.Computed<string, Schema.SchemaError, never>;
+    readonly onfocus: Effect.Effect<void, Schema.SchemaError, never>;
+    readonly onblur: EventHandler.EventHandler<FocusEvent, 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 an anchor coordinating pointer and optional host-focus behavior.
+ * @remarks
+ * ## Why
+ * The default host is a non-focusable `<span>`, so it provides pointer behavior
+ * only. Give the span `tabindex`, or supply a natively focusable custom host,
+ * for direct focus, blur, and keydown handling. Unlike a tooltip, hovercard
+ * content may receive focus; host blur checks `relatedTarget` and stays open
+ * while focus moves inside the card. Nested-anchor focus does not bubble.
+ * ## Ownership and lifetime
+ * Running the Fx owns real DOM handlers and dynamic relationships in its Scope.
+ * Custom hosts must preserve `aria-controls` and all supplied handlers.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Hovercard from "@typed/ui/Hovercard"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Hovercard.makeState({ id: "author-card" })
+ *   return Hovercard.Anchor({
+ *     state,
+ *     content: "Ada Lovelace",
+ *     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>;
+interface ContentOptionsBase extends Dom.HostOptions<HTMLDivElement> {
+    readonly state: RefSubject.HydratedRefSubject<State, Schema.SchemaError>;
+    readonly content: Renderable.Any;
+}
+type AccessibleName = {
+    readonly label: Renderable.Any<string | null | undefined>;
+    readonly labelledBy?: never;
+} | {
+    readonly label?: never;
+    readonly labelledBy: Renderable.Any<string | null | undefined>;
+};
+/** Hovercard content options requiring one accessible naming strategy.
+ * @remarks
+ * ## Why
+ * Focusable dialog-like content needs an explicit name; the type makes label
+ * and labelled-by mutually exclusive.
+ *
+ * ## Options
+ *
+ * `state` provides the stable content id and open state, while `content` may
+ * contain focusable output. `label` names the card directly; `labelledBy`
+ * references visible naming content. Supplying both is rejected by the type.
+ * ## Ownership and lifetime
+ * Options are inert; rendering owns content/listeners/native ref by Scope.
+ * @since 1.0.0
+ * @category Native content host
+ */
+export type ContentOptions = ContentOptionsBase & AccessibleName;
+declare function contentInternalProps<const Options extends ContentOptions>(options: Options): ({ property }: Dom.InternalPropsHelpers<Options>) => {
+    readonly id: RefSubject.Computed<string, Schema.SchemaError, never>;
+    readonly role: "dialog";
+    readonly "aria-label": Exclude<Dom.Property<Options, "label">, Dom.Nullish> | undefined;
+    readonly "aria-labelledby": Exclude<Dom.Property<Options, "labelledBy">, Dom.Nullish> | undefined;
+    readonly popover: "manual";
+    readonly onfocusin: Effect.Effect<void, Schema.SchemaError, never>;
+    readonly onfocusout: EventHandler.EventHandler<FocusEvent, Schema.SchemaError, never>;
+    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 named, focusable hovercard content in the native top layer.
+ * @remarks
+ * ## Why
+ * `role="dialog"` distinguishes interactive content from a tooltip. Native
+ * popover placement is retained, and focus/pointer transitions prevent closing
+ * while interaction remains inside the card.
+ * ## Ownership and lifetime
+ * Running the Fx owns handlers and NativePopover observation in its Scope. A
+ * custom host must preserve id, role, accessible name, manual popover,
+ * lifecycle handlers, and one hydration ref owner.
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Hovercard from "@typed/ui/Hovercard"
+ *
+ * const program = Effect.gen(function* () {
+ *   const state = yield* Hovercard.makeState({ id: "author-card" })
+ *   return Hovercard.Content({ state, label: "Author", content: "Mathematician" })
+ * })
+ * ```
+ * @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 native popover ownership as `Content`.
+ * @since 1.0.0
+ * @category Native content host
+ */
+export declare const Hovercard: typeof Content;
+export {};
+//# sourceMappingURL=Hovercard.d.ts.map

package/dist/Hovercard.d.ts.map

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