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

package/dist/Dom/Props.js

@@ -0,0 +1,110 @@
+import { chainEvent, isEventKey } from "./Events.js";
+import { composeRefs } from "./Refs.js";
+/**
+ * Merges user host props with component-required internal props.
+ *
+ * @remarks
+ * ## Why
+ * Internal accessibility/state props must remain authoritative, but user
+ * events still run first and may cancel component behavior. Disabled hosts
+ * suppress user activation handlers. Refs compose instead of overwriting one
+ * another.
+ *
+ * ## Ownership and lifetime
+ * The function allocates only a merged object. Listener and ref effects are
+ * run by the eventual template Scope. `composeRefs` rejects two hydration
+ * owners because one element can restore only one hydration protocol.
+ *
+ * @example
+ * ```ts
+ * import { mergeProps } from "@typed/ui/Dom/Props"
+ * import { EventHandler } from "@typed/template"
+ * import { Effect } from "effect"
+ *
+ * const props = mergeProps(
+ *   {
+ *     class: "external",
+ *     onclick: EventHandler.make(() => Effect.log("user activation"))
+ *   },
+ *   { role: "button", "aria-disabled": false }
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Prop composition
+ */
+export function mergeProps(user, internal) {
+    if (!user)
+        return internal;
+    const merged = { ...user, ...internal };
+    const internalRecord = internal;
+    const mergedRecord = merged;
+    const activationDisabled = internalRecord["aria-disabled"] === true || internalRecord["?disabled"] === true;
+    for (const [key, value] of Object.entries(user)) {
+        if (isEventKey(key)) {
+            mergedRecord[key] = chainEvent(activationDisabled && (key === "onclick" || key === "@click")
+                ? undefined
+                : value, internalRecord[key]);
+        }
+    }
+    mergedRecord["ref"] = composeRefs(internalRecord["ref"], user["ref"]);
+    return merged;
+}
+/**
+ * Reads a property from an unknown generic value without throwing on nullish input.
+ *
+ * @remarks
+ * ## Why
+ * Generic option construction needs runtime behavior matching the public `Property` type.
+ *
+ * ## Ownership and lifetime
+ * Pure read; no value is retained.
+ *
+ * @since 1.0.0
+ * @category Property inspection
+ */
+export function getProperty(value, key) {
+    return (value === null || value === undefined ? undefined : Reflect.get(Object(value), key));
+}
+/**
+ * Builds typed fallback helpers for component-owned host props.
+ *
+ * @remarks
+ * ## Why
+ * Components can distinguish an absent option from valid falsy values.
+ *
+ * ## Ownership and lifetime
+ * The helper closes over `options` only during synchronous prop construction.
+ *
+ * @since 1.0.0
+ * @category Internal prop defaults
+ */
+export function makeInternalPropsHelpers(options) {
+    return {
+        property: (key, fallback) => {
+            const value = getProperty(options, key);
+            return (value === null || value === undefined ? fallback : value);
+        },
+    };
+}
+/**
+ * Extracts top-level refs and event handlers from component options.
+ *
+ * @remarks
+ * ## Why
+ * Convenience event/ref options can enter the same deterministic host merge as `props`.
+ *
+ * ## Ownership and lifetime
+ * Returns a shallow object. The rendering Scope owns any contained listener/ref work.
+ *
+ * @since 1.0.0
+ * @category Prop forwarding
+ */
+export function forwardHostProps(options) {
+    const props = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (key === "ref" || isEventKey(key))
+            props[key] = value;
+    }
+    return props;
+}

package/dist/Dom/Refs.d.ts

@@ -0,0 +1,58 @@
+import * as Effect from "effect/Effect";
+import { RefSubject } from "@typed/fx";
+import type { Renderable } from "@typed/template";
+type RefInput = (element: never) => unknown;
+type RefTarget<Ref> = NonNullable<Ref> extends (element: infer Target) => unknown ? Target : unknown;
+type RefResult<Ref> = NonNullable<Ref> extends (...args: Array<never>) => infer Result ? Result : never;
+type RefError<Ref> = Renderable.Error<NonNullable<Ref> | RefResult<Ref>>;
+type RefServices<Ref> = Renderable.Services<NonNullable<Ref> | RefResult<Ref>>;
+type HydrationProtocol<Ref> = NonNullable<Ref> extends RefSubject.HydrationRef<infer E, infer R> ? RefSubject.HydrationRef<E, R> : unknown;
+/**
+ * Ref callback produced by combining two compatible element refs.
+ *
+ * @remarks
+ * ## Why
+ * User and component refs can observe the exact same DOM element without one
+ * overwriting the other, while their error/service channels remain visible.
+ *
+ * ## Ownership and lifetime
+ * The callback sequences both refs inside the element's rendering Scope. At
+ * most one input may carry `HydrationRef` ownership; that protocol is retained
+ * on the composed callback.
+ *
+ * @since 1.0.0
+ * @category Ref composition
+ */
+export type ComposedRef<First, Second> = ((element: RefTarget<First> & RefTarget<Second>) => Effect.Effect<void, RefError<First> | RefError<Second>, RefServices<First> | RefServices<Second>>) & HydrationProtocol<First> & HydrationProtocol<Second>;
+/**
+ * Composes two element refs in order.
+ *
+ * @remarks
+ * ## Why
+ * A component's internal ref and a caller's ref both need the real mounted
+ * node. Each return value may be void, Effect, Stream, or Fx, and composition
+ * normalizes those forms without hiding failures or services.
+ *
+ * ## Ownership and lifetime
+ * The first ref runs before the second. Streams and Fx values are drained in
+ * the caller's Scope and interrupted on unmount. The function throws
+ * synchronously when both refs claim hydration ownership because applying two
+ * serialized states to one element is ambiguous.
+ *
+ * @example
+ * ```ts
+ * import { composeRefs } from "@typed/ui/Dom/Refs"
+ * import { Effect } from "effect"
+ *
+ * const ref = composeRefs(
+ *   (element: HTMLButtonElement) => Effect.sync(() => element.focus()),
+ *   (element: HTMLButtonElement) => console.log(element)
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Ref composition
+ */
+export declare function composeRefs<const First extends RefInput | null | undefined, const Second extends RefInput | null | undefined = undefined>(first: First, second?: Second): ComposedRef<First, Second> | undefined;
+export {};
+//# sourceMappingURL=Refs.d.ts.map

package/dist/Dom/Refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Refs.d.ts","sourceRoot":"","sources":["../../src/Dom/Refs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,KAAK,QAAQ,GAAG,CAAC,OAAO,EAAE,KAAK,KAAK,OAAO,CAAC;AAC5C,KAAK,SAAS,CAAC,GAAG,IAChB,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,MAAM,KAAK,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AACjF,KAAK,SAAS,CAAC,GAAG,IAChB,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,MAAM,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AACpF,KAAK,QAAQ,CAAC,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;AACzE,KAAK,WAAW,CAAC,GAAG,IAAI,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/E,KAAK,iBAAiB,CAAC,GAAG,IACxB,WAAW,CAAC,GAAG,CAAC,SAAS,UAAU,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAC9D,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7B,OAAO,CAAC;AAEd;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,CACxC,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,KAC1C,MAAM,CAAC,MAAM,CAChB,IAAI,EACJ,QAAQ,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,EAClC,WAAW,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,CACzC,CAAC,GACA,iBAAiB,CAAC,KAAK,CAAC,GACxB,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CACzB,KAAK,CAAC,KAAK,SAAS,QAAQ,GAAG,IAAI,GAAG,SAAS,EAC/C,KAAK,CAAC,MAAM,SAAS,QAAQ,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,EAC5D,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,SAAS,CAoBvE"}

package/dist/Dom/Refs.js

@@ -0,0 +1,61 @@
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import { RefSubject } from "@typed/fx";
+import { drain, isFx } from "@typed/fx/Fx";
+/**
+ * Composes two element refs in order.
+ *
+ * @remarks
+ * ## Why
+ * A component's internal ref and a caller's ref both need the real mounted
+ * node. Each return value may be void, Effect, Stream, or Fx, and composition
+ * normalizes those forms without hiding failures or services.
+ *
+ * ## Ownership and lifetime
+ * The first ref runs before the second. Streams and Fx values are drained in
+ * the caller's Scope and interrupted on unmount. The function throws
+ * synchronously when both refs claim hydration ownership because applying two
+ * serialized states to one element is ambiguous.
+ *
+ * @example
+ * ```ts
+ * import { composeRefs } from "@typed/ui/Dom/Refs"
+ * import { Effect } from "effect"
+ *
+ * const ref = composeRefs(
+ *   (element: HTMLButtonElement) => Effect.sync(() => element.focus()),
+ *   (element: HTMLButtonElement) => console.log(element)
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Ref composition
+ */
+export function composeRefs(first, second) {
+    if (!first && !second)
+        return undefined;
+    const hydrationOwners = [first, second].filter(RefSubject.isHydrationRef);
+    if (hydrationOwners.length > 1) {
+        throw new TypeError("Only one hydration ref can own an element");
+    }
+    const composed = Effect.fn((element) => Effect.andThen(runRef(first, element), runRef(second, element)));
+    const hydrationOwner = hydrationOwners[0];
+    const ref = hydrationOwner === undefined
+        ? composed
+        : Object.assign(composed, {
+            [RefSubject.HydrationRefTypeId]: hydrationOwner[RefSubject.HydrationRefTypeId],
+        });
+    return ref;
+}
+function runRef(ref, element) {
+    if (!ref)
+        return Effect.void;
+    const result = ref(element);
+    if (Effect.isEffect(result))
+        return Effect.asVoid(result);
+    if (Stream.isStream(result))
+        return Stream.runDrain(result);
+    if (isFx(result))
+        return drain(result);
+    return Effect.void;
+}

package/dist/Dom/Render.d.ts

@@ -0,0 +1,59 @@
+import { type RenderHostProps } from "./Props.js";
+import type { HostComponent, HostOptions, HostOverride, HostProps, HostResult, InternalPropsHelpers, RenderableInput } from "./Types.js";
+/**
+ * Creates the host-rendering boundary for a particular DOM element type.
+ *
+ * @remarks
+ * ## Why
+ * Components can compute required props once, merge them with caller props,
+ * then delegate either to a custom host or to a native-template fallback. This
+ * exposes the boundary needed for external renderers without a framework adapter.
+ *
+ * ## Ownership and lifetime
+ * The returned component is lazy. Its Scope owns the chosen Effect/Fx result,
+ * merged listener/ref work, and only the render-event range that result emits.
+ * A custom host owns output it creates and must honor the supplied props.
+ *
+ * @example
+ * ```ts
+ * import { renderHost } from "@typed/ui/Dom/Render"
+ * import { html } from "@typed/template"
+ *
+ * const renderButton = renderHost<HTMLButtonElement>()
+ * const button = renderButton(
+ *   { props: { class: "action" } },
+ *   undefined,
+ *   () => ({ type: "button" }),
+ *   "Save",
+ *   (props, content) => html`<button ...${props}>${content}</button>`
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Host rendering
+ */
+export declare function renderHost<Element extends globalThis.Element>(): <const Options extends HostOptions<Element>, const Internal extends HostProps<Element>, const Content extends RenderableInput, const Fallback extends HostResult, const Host extends HostResult = never>(options: Options, host: HostOverride<RenderHostProps<Options, Internal>, Content, Host> | undefined, buildInternal: (helpers: InternalPropsHelpers<Options>) => Internal, content: Content, fallback: (props: RenderHostProps<Options, Internal>, content: Content) => Fallback) => HostComponent<Options | Host>;
+/**
+ * Renders a native `div` host from supplied props and content.
+ *
+ * @remarks
+ * ## Why
+ * Many behavior-only components need a standards-based neutral fallback while
+ * still allowing callers to replace the host through `renderHost`.
+ *
+ * ## Ownership and lifetime
+ * The returned template is lazy. Its Scope owns reactive parts and the created
+ * div; it does not claim surrounding or externally supplied DOM.
+ *
+ * @example
+ * ```ts
+ * import { renderDivHost } from "@typed/ui/Dom/Render"
+ *
+ * const host = renderDivHost({ role: "group", class: "cluster" }, "Actions")
+ * ```
+ *
+ * @since 1.0.0
+ * @category Host rendering
+ */
+export declare function renderDivHost<const Props extends HostProps<HTMLDivElement>, const Content extends RenderableInput>(props: Props, content: Content): HostComponent<Props | Content>;
+//# sourceMappingURL=Render.d.ts.map

package/dist/Dom/Render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Render.d.ts","sourceRoot":"","sources":["../../src/Dom/Render.ts"],"names":[],"mappings":"AAGA,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAEV,aAAa,EACb,WAAW,EACX,YAAY,EACZ,SAAS,EACT,UAAU,EACV,oBAAoB,EACpB,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,UAAU,CAAC,OAAO,SAAS,UAAU,CAAC,OAAO,MAEzD,KAAK,CAAC,OAAO,SAAS,WAAW,CAAC,OAAO,CAAC,EAC1C,KAAK,CAAC,QAAQ,SAAS,SAAS,CAAC,OAAO,CAAC,EACzC,KAAK,CAAC,OAAO,SAAS,eAAe,EACrC,KAAK,CAAC,QAAQ,SAAS,UAAU,EACjC,KAAK,CAAC,IAAI,SAAS,UAAU,GAAG,KAAK,WAE5B,OAAO,QACV,YAAY,CAAC,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,SAAS,iBAClE,CAAC,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,KAAK,QAAQ,WAC1D,OAAO,YACN,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,OAAO,KAAK,QAAQ,KAClF,aAAa,CAAC,OAAO,GAAG,IAAI,CAAC,CASjC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,CAAC,KAAK,SAAS,SAAS,CAAC,cAAc,CAAC,EAC7C,KAAK,CAAC,OAAO,SAAS,eAAe,EACrC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,aAAa,CAAC,KAAK,GAAG,OAAO,CAAC,CAEhE"}

package/dist/Dom/Render.js

@@ -0,0 +1,71 @@
+import * as Effect from "effect/Effect";
+import { fromEffect } from "@typed/fx/Fx";
+import { html } from "@typed/template";
+import { forwardHostProps, getProperty, makeInternalPropsHelpers, mergeProps, } from "./Props.js";
+/**
+ * Creates the host-rendering boundary for a particular DOM element type.
+ *
+ * @remarks
+ * ## Why
+ * Components can compute required props once, merge them with caller props,
+ * then delegate either to a custom host or to a native-template fallback. This
+ * exposes the boundary needed for external renderers without a framework adapter.
+ *
+ * ## Ownership and lifetime
+ * The returned component is lazy. Its Scope owns the chosen Effect/Fx result,
+ * merged listener/ref work, and only the render-event range that result emits.
+ * A custom host owns output it creates and must honor the supplied props.
+ *
+ * @example
+ * ```ts
+ * import { renderHost } from "@typed/ui/Dom/Render"
+ * import { html } from "@typed/template"
+ *
+ * const renderButton = renderHost<HTMLButtonElement>()
+ * const button = renderButton(
+ *   { props: { class: "action" } },
+ *   undefined,
+ *   () => ({ type: "button" }),
+ *   "Save",
+ *   (props, content) => html`<button ...${props}>${content}</button>`
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Host rendering
+ */
+export function renderHost() {
+    return function (options, host, buildInternal, content, fallback) {
+        const props = mergeProps(mergeProps(getProperty(options, "props"), forwardHostProps(options)), buildInternal(makeInternalPropsHelpers(options)));
+        const rendered = host ? host(props, content) : fallback(props, content);
+        return componentBoundary(rendered);
+    };
+}
+/**
+ * Renders a native `div` host from supplied props and content.
+ *
+ * @remarks
+ * ## Why
+ * Many behavior-only components need a standards-based neutral fallback while
+ * still allowing callers to replace the host through `renderHost`.
+ *
+ * ## Ownership and lifetime
+ * The returned template is lazy. Its Scope owns reactive parts and the created
+ * div; it does not claim surrounding or externally supplied DOM.
+ *
+ * @example
+ * ```ts
+ * import { renderDivHost } from "@typed/ui/Dom/Render"
+ *
+ * const host = renderDivHost({ role: "group", class: "cluster" }, "Actions")
+ * ```
+ *
+ * @since 1.0.0
+ * @category Host rendering
+ */
+export function renderDivHost(props, content) {
+    return html `<div ...${props}>${content}</div>`;
+}
+function componentBoundary(value) {
+    return (Effect.isEffect(value) ? fromEffect(value) : value);
+}