elements-kit 0.0.14 → 0.0.16

package/dist/infer-BfzRJoCn.d.mts

@@ -0,0 +1,203 @@
+import { n as AttrChangeHandler, t as ATTRIBUTES } from "./attributes-Dtn68R1u.mjs";
+import { a as PrimitiveNodeType, i as Slots, t as SLOTS } from "./slot-C7GQZe-r.mjs";
+import { n as MaybeReactive } from "./index-DydGTqZU.mjs";
+import { JSX } from "dom-expressions/src/jsx-h";
+
+//#region src/jsx-runtime/types.d.ts
+/** An instance created by a component class — must expose `render()`. */
+interface ComponentInstance {
+  render(): Element | DocumentFragment | null;
+}
+/** A class whose constructor returns a ComponentInstance. */
+type ComponentClass<P = any> = new (props: P) => ComponentInstance;
+type ComponentFn = (props: Record<string | symbol, unknown>) => null | Element | DocumentFragment;
+/** Anything that can appear as a JSX child. */
+type Child = PrimitiveNodeType | AnyFn | Child[];
+/** A function that renders props into an element or fragment. */
+type AnyFn = (...args: any[]) => any;
+//#endregion
+//#region src/jsx-runtime/infer.d.ts
+type AnyElementCtor = abstract new (...args: any[]) => HTMLElement;
+type Inst<C> = C extends (abstract new (...args: any[]) => infer I) ? I : never;
+/**
+ * When the instance extends `HTMLElement`, drop the DOM surface so only the
+ * user's own fields remain. Plain classes keep all their keys.
+ */
+type PublicPropKeys<I> = I extends HTMLElement ? Exclude<keyof I, keyof HTMLElement | symbol> : Exclude<keyof I, symbol>;
+/**
+ * Public instance fields of `I` — all optional. For `HTMLElement` subclasses
+ * the DOM surface is excluded; for plain classes, all own keys are kept.
+ */
+type PropsOfInstance<I> = { [K in PublicPropKeys<I> & string]?: I[K] };
+/**
+ * Promote keys `K` of `P` to required; leave the rest unchanged.
+ *
+ * @template P — the prop object type.
+ * @template K — the keys to make required.
+ *
+ * @example
+ * ```ts
+ * type Optional = { a?: number; b?: string; c?: boolean };
+ * type AB = Require<Optional, "a" | "b">;
+ * // { a: number; b: string; c?: boolean }
+ * ```
+ */
+type Require<P, K extends keyof P> = { [X in K]-?: P[X] } & Omit<P, K>;
+/**
+ * Wrap every prop in {@link MaybeReactive} so callers may pass either a
+ * plain value or a reactive getter. Function-typed props (event handlers,
+ * render callbacks) are wrapped too — the JSX runtime detects branded
+ * signals/computed and re-binds on change. Optionality is preserved at the
+ * key level — the `| undefined` stays at the prop, not inside the reactive.
+ *
+ * @template P — source prop object type.
+ *
+ * @example
+ * ```ts
+ * type Raw = { count: number; label?: string; onClick: (e: Event) => void };
+ * type Wrapped = MaybeReactiveProps<Raw>;
+ * // {
+ * //   count:    MaybeReactive<number>;
+ * //   label?:   MaybeReactive<string>;
+ * //   onClick:  MaybeReactive<(e: Event) => void>;   // computed handlers OK
+ * // }
+ * ```
+ *
+ * @see {@link MaybeReactive}
+ * @see {@link Props}
+ */
+type MaybeReactiveProps<P> = { [K in keyof P]: undefined extends P[K] ? MaybeReactive<Exclude<P[K], undefined>> | undefined : MaybeReactive<P[K]> };
+type InstancePropsOf<C> = Inst<C> extends infer I ? PropsOfInstance<I> : {};
+type PropKeysOf<C> = keyof InstancePropsOf<C> & string;
+type AttrMap<C> = C extends {
+  [ATTRIBUTES]: infer M;
+} ? M : never;
+type HandlerValue<H> = H extends AttrChangeHandler<any> ? string | null : H;
+type AttrsOf<C> = AttrMap<C> extends infer M ? M extends Record<string, unknown> ? { [K in Exclude<keyof M & string, PropKeysOf<C>>]?: MaybeReactive<HandlerValue<M[K]>> } : {} : {};
+type FlatPropsOf<C> = MaybeReactiveProps<InstancePropsOf<C>>;
+type PropNamespacedOf<C> = { [K in PropKeysOf<C> as `prop:${K}`]?: NonNullable<InstancePropsOf<C>[K]> };
+type EventMapOf<C> = C extends {
+  events: infer E;
+} ? E : {};
+type Capitalize1<S extends string> = S extends `${infer H}${infer R}` ? `${Uppercase<H>}${R}` : S;
+type EventsOf<C> = EventMapOf<C> extends infer E ? E extends Record<string, Event> ? { [K in keyof E & string as `on:${K}`]?: MaybeReactive<(ev: E[K]) => void> } & { [K in keyof E & string as `on${Capitalize1<K>}`]?: MaybeReactive<(ev: E[K]) => void> } : {} : {};
+type SlotKeys<I> = I extends {
+  [SLOTS]: Slots<infer K>;
+} ? K : never;
+type SlotsOf<C> = SlotKeys<Inst<C>> extends infer K ? [K] extends [string] ? { [P in K as `slot:${P}`]?: Child } : {} : {};
+type ChildrenOf<C> = C extends {
+  children: never;
+} ? {} : {
+  children?: Child;
+};
+type BaseDOMAttrs = JSX.DOMAttributes<HTMLElement>;
+type Namespaces = {
+  ref?: (el: Element) => void;
+  [cls: `class:${string}`]: MaybeReactive<boolean>;
+  [sty: `style:${string}`]: MaybeReactive<string | null>;
+  [prop: `prop:${string}`]: unknown;
+};
+/**
+ * Full JSX prop type for a custom-element class (extends `HTMLElement`).
+ *
+ * Composes every surface the element can receive from JSX:
+ * - **Attributes** — keys from `static [ATTRIBUTES]` (typed `MaybeReactive<string | null>`).
+ *   Keys also present on the instance are dropped here so the flat key carries the property type.
+ * - **Flat properties** — public instance fields, wrapped in `MaybeReactive`.
+ * - **`prop:*`** — explicit property assignment for every field.
+ * - **Events** — keys from `declare static events: { ... }` produce both
+ *   `on:${K}` and `on${Capitalize<K>}` typed handlers.
+ * - **Slots** — keys from `[SLOTS] = Slots.new([...] as const)` produce `slot:${K}`.
+ * - **Children** — `children?: Child` unless `static children: never`.
+ * - **DOM attrs** — the standard dom-expressions surface (`class`, `style`, `ref`, …).
+ *
+ * @template C — the custom-element class (constructor type).
+ *
+ * @example
+ * ```ts
+ * @attributes
+ * class XRange extends HTMLElement {
+ *   static [ATTRIBUTES]: Attributes<XRange> = { min(v) { this.min = +v! } };
+ *   declare static events: { commit: CustomEvent<number> };
+ *   [SLOTS] = Slots.new(["label"] as const);
+ *   @reactive() min = 0;
+ * }
+ *
+ * type Props = ElementProps<typeof XRange>;
+ * // {
+ * //   min?: MaybeReactive<number>;
+ * //   "prop:min"?: number;
+ * //   "on:commit"?: (e: CustomEvent<number>) => void;
+ * //   onCommit?:   (e: CustomEvent<number>) => void;
+ * //   "slot:label"?: Child;
+ * //   children?: Child;
+ * //   // …plus ref, class, class:*, style, style:*, standard DOM events
+ * // }
+ * ```
+ *
+ * @see {@link Props} for class-components / function components (no attr/event/slot synthesis).
+ */
+type ElementProps<C extends AnyElementCtor> = BaseDOMAttrs & AttrsOf<C> & FlatPropsOf<C> & PropNamespacedOf<C> & EventsOf<C> & SlotsOf<C> & ChildrenOf<C> & Namespaces;
+/**
+ * Props of a class component that receives them via its constructor:
+ * `class Comp { constructor(props: P) }`. Reads `ConstructorParameters[0]`.
+ *
+ * Use this when the component's props live on a constructor parameter rather
+ * than on public instance fields. For instance-field components, use {@link Props}.
+ *
+ * @template C — the class constructor type (e.g. `typeof Card`).
+ *
+ * @example
+ * ```ts
+ * class Card {
+ *   constructor(public props: { title: string; children?: Child }) {}
+ *   render() { return <div>{this.props.title}</div>; }
+ * }
+ *
+ * type P = ComponentProps<typeof Card>;
+ * // { title: string; children?: Child }
+ * ```
+ *
+ * @see {@link Props}
+ */
+type ComponentProps<C extends ComponentClass<any>> = C extends ComponentClass<infer P> ? (P extends object ? P : {}) : {};
+/**
+ * Props for any component — class or function. Wraps every non-function
+ * prop in {@link MaybeReactive} so callers may pass values or reactive getters.
+ *
+ * Branches by input shape:
+ * - **Class constructor** (`typeof Cls`) → uses `PropsOfInstance<InstanceType<Cls>>`.
+ * - **Function component** (`(props: P) => ...`) → uses the first parameter.
+ * - **Class instance** (`Cls<T>`) → uses `PropsOfInstance<Cls<T>>` (useful when
+ *   generics need to flow through — see the `For` example below).
+ *
+ * Does **not** synthesize `on:*`, `slot:*`, or attribute surface. For custom
+ * elements that need those, use {@link ElementProps}.
+ *
+ * @template C — constructor, function, or instance.
+ *
+ * @example
+ * ```ts
+ * // 1. Class instance (lets a generic flow)
+ * class For<T> { each: T[] = []; render() { return null } }
+ * type ForProps<T> = Props<For<T>>;
+ * //   ↑ { each?: MaybeReactive<T[]> }
+ *
+ * // 2. Function component
+ * const Greeting = (_p: { name: string; excited?: boolean }) => null;
+ * type GreetingProps = Props<typeof Greeting>;
+ * //   ↑ { name: MaybeReactive<string>; excited?: MaybeReactive<boolean> }
+ *
+ * // 3. Class constructor
+ * class Counter { count = 0; render() { return null } }
+ * type CounterProps = Props<typeof Counter>;
+ * //   ↑ { count?: MaybeReactive<number> }
+ * ```
+ *
+ * @see {@link ElementProps} — custom elements (`HTMLElement` subclasses).
+ * @see {@link ComponentProps} — constructor-param-based class components.
+ * @see {@link MaybeReactiveProps}
+ */
+type Props<C> = C extends (abstract new (...args: any[]) => infer I) ? MaybeReactiveProps<PropsOfInstance<I>> : C extends ((props: infer P, ...rest: any[]) => any) ? P extends object ? MaybeReactiveProps<P> : {} : MaybeReactiveProps<PropsOfInstance<C>>;
+//#endregion
+export { Props as a, ComponentClass as c, MaybeReactiveProps as i, ComponentFn as l, ComponentProps as n, Require as o, ElementProps as r, Child as s, AnyElementCtor as t };

package/dist/integrations/react.d.mts

@@ -1,4 +1,4 @@
-import { t as Computed } from "../index-DUshSQ_6.mjs";
+import { t as Computed } from "../index-DydGTqZU.mjs";
 
 //#region src/integrations/react.d.ts
 /**

package/dist/integrations/react.mjs

@@ -1,4 +1,4 @@
-import { _ as signal, d as effectScope, u as effect } from "../signals-BHmWX6ox.mjs";
+import { d as effect, f as effectScope, v as signal } from "../signals-J8dK_rA4.mjs";
 import { useEffect, useMemo, useRef, useSyncExternalStore } from "react";
 //#region src/integrations/react.ts
 /**

package/dist/jsx-runtime/index.d.mts

@@ -1,24 +1,15 @@
-import { t as PrimitiveNodeType } from "../lib-JA05lzCN.mjs";
+import { t as CustomElementRegistry } from "../define-CjbTZ3VG.mjs";
+import { a as Props, c as ComponentClass, i as MaybeReactiveProps, l as ComponentFn, n as ComponentProps, o as Require, r as ElementProps, s as Child, t as AnyElementCtor } from "../infer-BfzRJoCn.mjs";
+import { n as MaybeReactive } from "../index-DydGTqZU.mjs";
 import { JSX as JSX$1 } from "dom-expressions/src/jsx-h";
 
-//#region src/jsx-runtime/types.d.ts
-/** An instance created by a component class — must expose `render()`. */
-interface ComponentInstance {
-  render(): Element | DocumentFragment | null;
-}
-/** A class whose constructor returns a ComponentInstance. */
-type ComponentClass = new (...args: any[]) => ComponentInstance;
-type ComponentFn = (props: Record<string | symbol, unknown>) => null | Element | DocumentFragment;
-/** Anything that can appear as a JSX child. */
-type Child = PrimitiveNodeType | AnyFn | Child[];
-/** A function that renders props into an element or fragment. */
-type AnyFn = (...args: any[]) => any;
-//#endregion
 //#region src/jsx-runtime/element.d.ts
-declare function createElement(type: string | Element | DocumentFragment | ComponentClass | ComponentFn, rawProps?: Record<string | symbol, unknown>): Element | DocumentFragment | null;
-//#endregion
-//#region src/jsx-runtime/ref.d.ts
-declare const $ref: unique symbol;
+declare function createElement(type: string | Element | DocumentFragment | ComponentClass | ComponentFn, {
+  ref,
+  ...props
+}?: Record<string | symbol, unknown> & {
+  ref?: (el: Element) => void;
+}): Element | DocumentFragment | null;
 //#endregion
 //#region src/jsx-runtime/fragment.d.ts
 /**
@@ -59,7 +50,7 @@ type SlotProps<K extends string> = { [P in K as `slot:${P}`]?: Child };
 type Attrs<K extends keyof JSX.IntrinsicElements> = JSX.IntrinsicElements[K];
 /** Extra props injected into every intrinsic element beyond dom-expressions defaults. */
 type OurProps = {
-  [$ref]?: (el: Element) => void;
+  ref?: (el: Element) => void;
   [slot: `slot:${string}`]: Child;
   [cls: `class:${string}`]: FunctionMaybe<boolean>;
   [sty: `style:${string}`]: FunctionMaybe<string | null>;
@@ -67,14 +58,16 @@ type OurProps = {
 };
 type WithOurProps<T> = T & OurProps;
 declare namespace JSX {
-  type Element = globalThis.Element | globalThis.DocumentFragment | null;
-  type ElementType = Child | ComponentClass;
-  interface ElementChildrenAttribute {
+  export type Element = globalThis.Element | globalThis.DocumentFragment | null;
+  export type ElementType = Child | ComponentClass;
+  export interface ElementChildrenAttribute {
     children: {};
   }
-  type IntrinsicElements = { [K in keyof JSX$1.IntrinsicElements]: WithOurProps<JSX$1.IntrinsicElements[K]> } & {
-    /** Custom elements (`x-foo`, `my-component`, …) get a loose typed fallback. */[customElement: `${string}-${string}`]: WithOurProps<JSX$1.DOMAttributes<HTMLElement>> & Record<string, unknown>;
+  type RegisteredElements = { [K in keyof CustomElementRegistry]: CustomElementRegistry[K] extends AnyElementCtor ? ElementProps<CustomElementRegistry[K]> : never };
+  export type IntrinsicElements = { [K in keyof JSX$1.IntrinsicElements]: WithOurProps<JSX$1.IntrinsicElements[K]> } & RegisteredElements & {
+    /** Unregistered custom elements (`x-foo`, `my-component`, …) — loose fallback. */[customElement: `${string}-${string}`]: WithOurProps<JSX$1.DOMAttributes<HTMLElement>> & Record<string, unknown>;
   };
+  export {};
 }
 //#endregion
-export { Attrs, Fragment, FunctionMaybe, JSX, SlotProps, createElement as h, createElement as jsx, createElement as jsxDEV, createElement as jsxs };
+export { Attrs, type ComponentProps, type ElementProps, Fragment, FunctionMaybe, JSX, type MaybeReactive, type MaybeReactiveProps, type Props, type Require, SlotProps, createElement as h, createElement as jsx, createElement as jsxDEV, createElement as jsxs };

package/dist/jsx-runtime/index.mjs

@@ -1,5 +1,5 @@
-import { t as createElement } from "../element-C_4VbkvQ.mjs";
-import { g as onCleanup } from "../signals-BHmWX6ox.mjs";
+import { t as createElement } from "../element-CGVy_8TW.mjs";
+import { _ as onCleanup } from "../signals-J8dK_rA4.mjs";
 //#region src/jsx-runtime/fragment.ts
 /**
 * Used by the JSX transform for `<>...</>` fragments.

package/dist/signals/index.d.mts

@@ -1,2 +1,2 @@
-import { C as untracked, S as trigger, _ as isEffect, a as isReactive, b as onCleanup, c as $computed, d as $signal, f as batch, g as isComputed, h as effectScope, i as Updater, l as $effect, m as effect, n as MaybeReactive, o as reactive, p as computed, r as Signal, s as resolve, t as Computed, u as $effectScope, v as isEffectScope, x as signal, y as isSignal } from "../index-DUshSQ_6.mjs";
-export { $computed, $effect, $effectScope, $signal, Computed, MaybeReactive, Signal, Updater, batch, computed, effect, effectScope, isComputed, isEffect, isEffectScope, isReactive, isSignal, onCleanup, reactive, resolve, signal, trigger, untracked };
+import { C as trigger, S as signal, _ as isComputed, a as isReactive, b as isSignal, c as resolveProps, d as EFFECT_SCOPE, f as SIGNAL, g as effectScope, h as effect, i as Updater, l as COMPUTED, m as computed, n as MaybeReactive, o as reactive, p as batch, r as Signal, s as resolve, t as Computed, u as EFFECT, v as isEffect, w as untracked, x as onCleanup, y as isEffectScope } from "../index-DydGTqZU.mjs";
+export { COMPUTED, Computed, EFFECT, EFFECT_SCOPE, MaybeReactive, SIGNAL, Signal, Updater, batch, computed, effect, effectScope, isComputed, isEffect, isEffectScope, isReactive, isSignal, onCleanup, reactive, resolve, resolveProps, signal, trigger, untracked };

package/dist/signals/index.mjs

@@ -1,2 +1,2 @@
-import { _ as signal, a as $effect, c as batch, d as effectScope, f as isComputed, g as onCleanup, h as isSignal, i as $computed, l as computed, m as isEffectScope, n as reactive, o as $effectScope, p as isEffect, r as resolve, s as $signal, t as isReactive, u as effect, v as trigger, y as untracked } from "../signals-BHmWX6ox.mjs";
-export { $computed, $effect, $effectScope, $signal, batch, computed, effect, effectScope, isComputed, isEffect, isEffectScope, isReactive, isSignal, onCleanup, reactive, resolve, signal, trigger, untracked };
+import { _ as onCleanup, a as COMPUTED, b as untracked, c as SIGNAL, d as effect, f as effectScope, g as isSignal, h as isEffectScope, i as resolveProps, l as batch, m as isEffect, n as reactive, o as EFFECT, p as isComputed, r as resolve, s as EFFECT_SCOPE, t as isReactive, u as computed, v as signal, y as trigger } from "../signals-J8dK_rA4.mjs";
+export { COMPUTED, EFFECT, EFFECT_SCOPE, SIGNAL, batch, computed, effect, effectScope, isComputed, isEffect, isEffectScope, isReactive, isSignal, onCleanup, reactive, resolve, resolveProps, signal, trigger, untracked };

package/dist/{signals-BHmWX6ox.mjs → signals-J8dK_rA4.mjs}

@@ -275,10 +275,10 @@ let activeSub;
 let activeOwner;
 /** Ring-buffer of effects waiting to be flushed. */
 const queued = [];
-const $signal = Symbol("signal");
-const $computed = Symbol("computed");
-const $effect = Symbol("effect");
-const $effectScope = Symbol("effectScope");
+const SIGNAL = Symbol("signal");
+const COMPUTED = Symbol("computed");
+const EFFECT = Symbol("effect");
+const EFFECT_SCOPE = Symbol("effectScope");
 const { link, unlink, propagate, checkDirty, shallowPropagate } = createReactiveSystem({
 	update(node) {
 		if (node.depsTail !== void 0) return updateComputed(node);
@@ -353,26 +353,26 @@ function endBatch() {
 /**
 * Returns `true` if `fn` is a signal handle created by {@link signal}.
 *
-* Relies on `$signal` matching the internal `signalOper` function name.
+* Relies on the SIGNAL symbol.
 */
 function isSignal(fn) {
-	return fn != null && fn[$signal] === true;
+	return fn != null && fn[SIGNAL] === true;
 }
 /**
 * Returns `true` if `fn` is a computed handle created by {@link computed}.
 *
-* Relies on `$computed` matching the internal `computedOper` function name.
+* Relies on the COMPUTED symbol.
 */
 function isComputed(fn) {
-	return fn != null && fn[$computed] === true;
+	return fn != null && fn[COMPUTED] === true;
 }
 /**
 * Returns `true` if `fn` is an effect cleanup handle created by {@link effect}.
 *
-* Relies on the $effect symbol branding.
+* Relies on the EFFECT symbol.
 */
 function isEffect(fn) {
-	return fn != null && fn[$effect] === true;
+	return fn != null && fn[EFFECT] === true;
 }
 /**
 * Returns `true` if `fn` is an effectScope cleanup handle created by
@@ -391,7 +391,7 @@ function signal(initialValue) {
 		subsTail: void 0,
 		flags: 1
 	});
-	Object.defineProperty(handle, $signal, { value: true });
+	Object.defineProperty(handle, SIGNAL, { value: true });
 	return handle;
 }
 /**
@@ -427,7 +427,7 @@ function computed(getter) {
 		flags: 0,
 		getter
 	});
-	Object.defineProperty(handle, $computed, { value: true });
+	Object.defineProperty(handle, COMPUTED, { value: true });
 	return handle;
 }
 /**
@@ -481,7 +481,7 @@ function effect(fn) {
 		e.flags &= -5;
 	}
 	const handle = effectOper.bind(e);
-	Object.defineProperty(handle, $effect, { value: true });
+	Object.defineProperty(handle, EFFECT, { value: true });
 	return handle;
 }
 /**
@@ -527,7 +527,7 @@ function effectScope(fn) {
 		activeOwner = prevOwner;
 	}
 	const handle = effectScopeOper.bind(e);
-	Object.defineProperty(handle, $effectScope, { value: true });
+	Object.defineProperty(handle, EFFECT_SCOPE, { value: true });
 	return handle;
 }
 /**
@@ -964,11 +964,51 @@ function reactive(source) {
 	};
 }
 /**
-* Resolves a MaybeReactive<T> to its current value.
-* If the input is a function, calls it; otherwise returns as-is.
+* Resolve a {@link MaybeReactive} to its current value. Calls the getter
+* when reactive; returns the value as-is when static.
+*
+* @example
+* ```ts
+* resolve(5);              // 5
+* resolve(() => count());  // current count value
+* ```
 */
 function resolve(value) {
 	return isReactive(value) ? value() : value;
 }
+/**
+* Turn a reactive-props object into a bag of per-key getters. Callers may
+* pass values or reactive sources (`signal`, `computed`); reading
+* `props.name()` inside an effect or JSX getter subscribes to whatever
+* drives it. Static values become stable thunks, signals and computed pass
+* through unchanged — so identity is preserved (`props.name === props.name`).
+*
+* @example
+* ```tsx
+* import { resolveProps } from "elements-kit/signals";
+*
+* function Greeting(raw: MaybeReactiveProps<{ name: string; excited?: boolean }>) {
+*   const props = resolveProps(raw);
+*   return (
+*     <p>
+*       Hello, {props.name}
+*       {() => (props.excited() ? "!" : ".")}
+*     </p>
+*   );
+* }
+* ```
+*/
+function resolveProps(raw) {
+	const cache = /* @__PURE__ */ new Map();
+	return new Proxy(raw, { get(target, key) {
+		let getter = cache.get(key);
+		if (!getter) {
+			const v = target[key];
+			getter = isReactive(v) ? v : () => v;
+			cache.set(key, getter);
+		}
+		return getter;
+	} });
+}
 //#endregion
-export { signal as _, $effect as a, batch as c, effectScope as d, isComputed as f, onCleanup as g, isSignal as h, $computed as i, computed as l, isEffectScope as m, reactive as n, $effectScope as o, isEffect as p, resolve as r, $signal as s, isReactive as t, effect as u, trigger as v, untracked as y };
+export { onCleanup as _, COMPUTED as a, untracked as b, SIGNAL as c, effect as d, effectScope as f, isSignal as g, isEffectScope as h, resolveProps as i, batch as l, isEffect as m, reactive as n, EFFECT as o, isComputed as p, resolve as r, EFFECT_SCOPE as s, isReactive as t, computed as u, signal as v, trigger as y };

package/dist/slot-C7GQZe-r.d.mts

@@ -0,0 +1,104 @@
+//#region src/lib.d.ts
+type PrimitiveNodeType = Node | string | boolean | number | bigint | symbol | Date | RegExp | null | undefined;
+//#endregion
+//#region src/slot.d.ts
+/**
+ * A lightweight slot that reserves a region in the DOM using comment markers.
+ * Content between the markers can be replaced dynamically without wrapper elements.
+ */
+declare class Slot {
+  #private;
+  private readonly start;
+  private readonly end;
+  /**
+   * Render the slot as a DocumentFragment.
+   * If not yet mounted, inserts the comment markers and optional default content.
+   * If already mounted, extracts and returns the current content WITHOUT disposing
+   * it — the caller takes ownership of the returned nodes and is responsible for
+   * their disposal.
+   */
+  slot(defaultContent?: PrimitiveNodeType): DocumentFragment;
+  /** Dispose reactive children and remove all content between the markers. */
+  clear(): void;
+  /**
+   * Replace the slot's content with the given element.
+   * No-op if the slot is not mounted or the content is identical.
+   */
+  set(element: Node): void;
+  /**
+   * Extract and return the current slot content as a DocumentFragment.
+   * Returns `null` if the slot is not mounted.
+   * Content is NOT disposed — the caller takes ownership and is responsible
+   * for disposal.
+   */
+  get(): DocumentFragment | null;
+  /** Returns the parent node if the slot is mounted, otherwise `null`. */
+  parent(): ParentNode | null;
+  /** Whether the slot's comment markers are attached to the DOM. */
+  isMounted(): boolean;
+  private isSame;
+  /**
+   * Create a callable slot instance.
+   *
+   * The returned value is both a function and an object:
+   * - Call it to render the slot with optional default content.
+   * - Access `.set()`, `.parent()`, `.isMounted()` for slot management.
+   *
+   * @example
+   * ```ts
+   * const slot = createSlot();
+   * el.append(slot("default text"));  // mount with default
+   * slot.set(newElement);              // replace content
+   * ```
+   */
+  static new(): Slot & ((defaultContent?: PrimitiveNodeType) => DocumentFragment);
+}
+type SlotInstance = ReturnType<typeof Slot.new>;
+/** A callable slot — invoke to render, or access `.set()` / `.isMounted()` / `.parent()` for management. */
+/**
+ * Symbol key for attaching a `Slots` instance to a custom element instance.
+ * This prevent collisions with Element properties and are not meant to be treated as JSX children.
+ */
+declare const SLOTS: unique symbol;
+declare const $map: unique symbol;
+declare const $keys: unique symbol;
+declare const $has: unique symbol;
+/**
+ * A keyed collection of slot instances.
+ * Slots are pre-created from the provided keys and lazily created on first access for unknown keys.
+ */
+declare class Slots<K extends string> implements Iterable<[K, SlotInstance]> {
+  readonly [$map]: Map<K, Slot & ((defaultContent?: PrimitiveNodeType) => DocumentFragment)>;
+  private constructor();
+  [Symbol.iterator](): MapIterator<[K, Slot & ((defaultContent?: PrimitiveNodeType) => DocumentFragment)]>;
+  [Symbol.toStringTag](): string;
+  [Symbol.hasInstance](instance: unknown): instance is Slots<any>;
+  [$has](key: K): boolean;
+  /** Check whether a slot with the given key exists. */
+  static has<K extends string>(slots: Slots<K>, key: K): boolean;
+  [$keys](): MapIterator<K>;
+  /** Iterate over all registered slot keys. */
+  static keys<K extends string>(slots: Slots<K>): MapIterator<K>;
+  /**
+   * Create a typed `Slots` collection from a list of key names.
+   *
+   * Pass the keys with `as const` so TS narrows them to a literal union —
+   * this is what lets `ElementProps<typeof Cls>` synthesize `slot:${K}`
+   * entries. Without `as const`, the array type widens to `string[]` and
+   * the slot keys are lost.
+   *
+   * @example
+   * ```ts
+   * class Card extends HTMLElement {
+   *   // ✅ literal keys flow through — "header" | "footer"
+   *   [SLOTS] = Slots.new(["header", "footer"] as const);
+   * }
+   *
+   * // ❌ widens to string; no typed slot:* props
+   * // [SLOTS] = Slots.new(["header", "footer"]);
+   * ```
+   */
+  static new<K extends string>(keys: K[]): Slots<K> & { readonly [P in K]: SlotInstance };
+}
+//#endregion
+export { PrimitiveNodeType as a, Slots as i, Slot as n, SlotInstance as r, SLOTS as t };

package/dist/{slot-Cydy7-0L.mjs → slot-Kb61AcgW.mjs}

@@ -132,7 +132,7 @@ var Slot = class Slot {
 * Symbol key for attaching a `Slots` instance to a custom element instance.
 * This prevent collisions with Element properties and are not meant to be treated as JSX children.
 */
-const $slots = Symbol("slots");
+const SLOTS = Symbol("slots");
 const $map = Symbol("map");
 const $keys = Symbol("keys");
 const $has = Symbol("has");
@@ -168,6 +168,25 @@ var Slots = class Slots {
 	static keys(slots) {
 		return slots[$keys]();
 	}
+	/**
+	* Create a typed `Slots` collection from a list of key names.
+	*
+	* Pass the keys with `as const` so TS narrows them to a literal union —
+	* this is what lets `ElementProps<typeof Cls>` synthesize `slot:${K}`
+	* entries. Without `as const`, the array type widens to `string[]` and
+	* the slot keys are lost.
+	*
+	* @example
+	* ```ts
+	* class Card extends HTMLElement {
+	*   // ✅ literal keys flow through — "header" | "footer"
+	*   [SLOTS] = Slots.new(["header", "footer"] as const);
+	* }
+	*
+	* // ❌ widens to string; no typed slot:* props
+	* // [SLOTS] = Slots.new(["header", "footer"]);
+	* ```
+	*/
 	static new(keys) {
 		const instance = new Slots(keys);
 		return new Proxy(instance, { get(target, prop, receiver) {
@@ -177,4 +196,4 @@ var Slots = class Slots {
 	}
 };
 //#endregion
-export { resolveNode as i, Slot as n, Slots as r, $slots as t };
+export { resolveNode as i, Slot as n, Slots as r, SLOTS as t };