elements-kit 0.21.0 → 0.22.1

package/README.md

@@ -5,9 +5,9 @@
 ```tsx
 import { signal, computed } from "elements-kit/signals";
 import { render } from "elements-kit/render";
-import type { ReactiveProps } from "elements-kit/jsx-runtime";
+import type { Props } from "elements-kit/jsx-runtime";
 
-function Counter(props: ReactiveProps<{ initial?: number }>) {
+function Counter(props: Props<{ initial?: number }>) {
   const count = signal(props.initial() ?? 0);
   const doubled = computed(() => count() * 2);
 
@@ -52,7 +52,7 @@ ElementsKit is a library of reactive primitives, not a framework. Each piece is
 
 - **Designed for the AI age.** Code is cheap; maintenance still isn't. Primitives compose into higher-level blocks. Swap one block at a time instead of maintaining long lines of code.
 
-- **Bundler-friendly.** Every primitive is its own subpath — `elements-kit/signals`, `elements-kit/utilities/*`, `elements-kit/integrations/*`. Import only what you need.
+- **Bundler-friendly.** Every primitive is its own subpath — `elements-kit/signals`, `elements-kit/utilities/*`, `elements-kit/ui/*`, `elements-kit/integrations/*`. Import only what you need.
 
 ## Packages
 
@@ -63,16 +63,17 @@ Every feature is a separate subpath export — import only what you use.
 | `elements-kit/signals` | `signal`, `computed`, `effect`, `effectScope`, `batch`, `untracked`, `trigger`, `onCleanup`, `MaybeReactive`, `resolve`, `resolveProps`, `@reactive` |
 | `elements-kit/render` | `render(target, setup)` — mount a node with a scoped lifetime; returns `unmount` |
 | `elements-kit/attributes` | `@attributes` decorator + `ATTRIBUTES` symbol |
-| `elements-kit/slot` | `Slot`, `Slots`, `SLOTS` symbol — comment-marker DOM regions |
-| `elements-kit/custom-elements` | `defineElement`, `CustomElementRegistry` |
+| `elements-kit/slot` | `Slot` class + `@slot()` decorator + `SlotContent` type — comment-marker DOM regions as plain properties |
+| `elements-kit/custom-elements` | `defineElement`, `CustomElementRegistry`, `PropertiesOf`, `AttributesOf`, `EventsOf`, `PublicPropKeys` — raw framework-agnostic extractors for a custom element's properties/attributes/events |
 | `elements-kit/for` | `For` keyed-list component |
-| `elements-kit/jsx-runtime` | JSX factory + type helpers (`ElementProps`, `Props`, `ComponentProps`, `MaybeReactiveProps`, `ReactiveProps`, `Require`) — configure via `jsxImportSource` |
+| `elements-kit/jsx-runtime` | JSX factory + type helpers (`PropsOf`, `MaybeReactiveProps`, `RawProps`, `Props`, `Require`) — configure via `jsxImportSource` |
 | `elements-kit/server` | `renderToStream`, `renderToString` — streaming HTML rendering in any JS runtime (Node, edge/Workers), no DOM required *(experimental)* |
 | `elements-kit/hydrate` | `hydrate(container, () => <App/>)` — adopt server-rendered DOM and make it interactive *(experimental)* |
 | `elements-kit/await` | `Await` — loading boundary (Suspense equivalent); code splitting = `async` + dynamic import *(experimental)* |
 | `elements-kit/integrations/react` | `useSignal`, `useScope` React bridge hooks |
 | `elements-kit/integrations/astro` | `elementsKit()` Astro integration — elements-kit components as server-rendered, hydrated islands *(experimental)* |
 | `elements-kit/utilities/*` | Reactive browser-API utilities — see [src/utilities/README.md](src/utilities/README.md) |
+| `elements-kit/ui/*` | Accessible UI component styles (CSS) + an optional base theme (`elements-kit/ui/styles.css`); plus the `otp-input` custom element and `overlay` positioning/interaction behaviors. Catalog in [src/ui/README.md](src/ui/README.md) |
 
 ## Signals
 
@@ -340,7 +341,7 @@ await op;     // awaitable (delegates to .then/.catch/.finally via .raw)
 op.stop();    // halt reruns + fire registered cleanup
 ```
 
-Reactive state getters: `.state`, `.value`, `.reason`, `.result`, `.pending`, `.raw` (the underlying `ComputedPromise`).
+Reactive state getters: `.state` (`"idle" | "pending" | "fulfilled" | "rejected"` — `idle` before the first run, so `.pending` is `false` until you trigger one), `.value`, `.reason`, `.result`, `.pending`, `.raw` (the underlying `ComputedPromise`).
 
 One-shot mutation (no tracking):
 
@@ -412,24 +413,25 @@ import { For } from "elements-kit/for";
 
 ## Prop types
 
-Six type helpers derive JSX prop shapes from your components — no parallel `declare global` block to maintain. Full guide at [docs/src/content/docs/elements/types.mdx](docs/src/content/docs/elements/types.mdx).
+A small set of type helpers derives JSX prop shapes from your components — no parallel `declare global` block to maintain. Full guide at [docs/src/content/docs/elements/types.mdx](docs/src/content/docs/elements/types.mdx).
 
 | Helper | For |
 | ------ | --- |
-| `ElementProps<typeof Cls>` | `HTMLElement` subclass — full surface (attrs, events, slots, children) |
-| `Props<C>` | Class instance, constructor, or function component — unified |
-| `ComponentProps<typeof Cls>` | Class components with `constructor(props: P)` |
-| `MaybeReactiveProps<P>` | Caller-facing — wrap every prop in `MaybeReactive` (what parents pass) |
-| `ReactiveProps<P>` | Component-facing — every prop becomes a `Computed<T>` getter (what function components receive) |
+| `PropsOf<C>` | Unified — fn/class components give raw prop shapes; custom-element ctors give the full JSX surface (attrs, events, slots, children) |
+| `Props<P>` | Component-facing — every prop becomes a `Computed<T>` getter (what function components receive) |
+| `MaybeReactiveProps<P>` | Caller-facing — wrap every prop in `MaybeReactive` (e.g. a class component's constructor param) |
+| `RawProps<R>` | Recover the raw `P` from a branded `Props<P>` |
 | `MaybeReactive<T>` | Scalar value-or-getter (from `elements-kit/signals`) |
 | `Require<P, K>` | Promote optional keys to required |
 
-The JSX runtime auto-wraps function-component props — each key arrives as a callable getter that subscribes on read. Pair the signature with `ReactiveProps<P>` and read `props.x()`:
+Callers never wrap anything by hand — at every JSX call site the runtime's `LibraryManagedAttributes` automatically lets parents pass each prop as a static value *or* a signal/computed.
+
+The JSX runtime auto-wraps function-component props — each key arrives as a callable getter that subscribes on read. Pair the signature with `Props<P>` and read `props.x()`:
 
 ```tsx
-import type { ReactiveProps } from "elements-kit/jsx-runtime";
+import type { Props } from "elements-kit/jsx-runtime";
 
-function Greeting(props: ReactiveProps<{ name: string }>) {
+function Greeting(props: Props<{ name: string }>) {
   return <p>Hello, {props.name}</p>;
 }
 ```
@@ -472,15 +474,15 @@ class MyElement extends HTMLElement {
 }
 ```
 
-For typed slots, attach a `[SLOTS]` instance field — pass the key list with `as const` so TS can narrow:
+For named slots, declare `@slot()` properties — reading places the region in your template, assigning fills it (from any framework, or none):
 
 ```ts
-import { SLOTS, Slots } from "elements-kit/slot";
+import { slot } from "elements-kit/slot";
 
 class Card extends HTMLElement {
-  [SLOTS] = Slots.new(["header", "footer"] as const);
+  @slot() header!: Node
+  @slot() footer!: Node
 }
-// ElementProps<typeof Card> now includes `slot:header` / `slot:footer`
 ```
 
 For typed events, declare a `static events` map:
@@ -489,7 +491,7 @@ For typed events, declare a `static events` map:
 class XPicker extends HTMLElement {
   declare static events: { commit: CustomEvent<number> };
 }
-// ElementProps<typeof XPicker> now includes `on:commit`
+// PropsOf<typeof XPicker> now includes `on:commit`
 ```
 
 ## Roadmap

package/dist/attributes.d.mts

@@ -1,2 +1,2 @@
-import { a as Attributes, c as observedAttributes, i as AttributeTarget, n as AttrChangeHandler, o as attributes, r as AttributeDecorated, s as dispatchAttrChange, t as ATTRIBUTES } from "./attributes-3r7Diua4.mjs";
+import { a as Attributes, c as observedAttributes, i as AttributeTarget, n as AttrChangeHandler, o as attributes, r as AttributeDecorated, s as dispatchAttrChange, t as ATTRIBUTES } from "./attributes-DILeh3-s.mjs";
 export { ATTRIBUTES, AttrChangeHandler, AttributeDecorated, AttributeTarget, Attributes, attributes, dispatchAttrChange, observedAttributes };

package/dist/await.d.mts

@@ -1,4 +1,4 @@
-import { t as Child } from "./types-CUvFIgPa.mjs";
+import { c as Props, t as Children } from "./children-s3nFjpLA.mjs";
 
 //#region src/await.d.ts
 /** @internal Metadata stamped on an Await region getter (see claim walk). */
@@ -44,10 +44,11 @@ interface AsyncRegionMeta {
  * </Await>
  * ```
  */
-declare function Await(props: {
-  fallback?: Child | (() => Child);
+type AwaitChildren = Children | PromiseLike<Children> | (Children | PromiseLike<Children>)[];
+declare function Await(props: Props<{
+  fallback?: Children;
   when?: unknown;
-  children?: Child;
-}): Element;
+  children?: AwaitChildren;
+}>): Element;
 //#endregion
 export { AsyncRegionMeta, Await };

package/dist/await.mjs

@@ -13,42 +13,6 @@ function toAwaitables(value) {
 	else if (isThenable(item)) out.push(promise(item));
 	return out;
 }
-/**
-* Loading boundary for async children — elements-kit's `Suspense` equivalent.
-*
-* Direct async children (`promise`/`async` values — including the
-* code-splitting pattern `async(() => import("./chart"))`) are detected
-* automatically; pass `when` to gate on arbitrary awaitables instead. While
-* anything is pending the client renders `fallback`; once everything settles
-* the children show. The server never renders the fallback — the stream
-* awaits and emits the real content. During hydration the server content
-* stays visible while the region is pending (no fallback flash).
-*
-* Prefer a thunk fallback (`fallback={() => <Spinner/>}`) so it renders
-* fresh each time the boundary re-enters a pending state.
-*
-* @example Code splitting with `async` + dynamic import:
-* ```tsx
-* const chart = async(() => import("./chart").then((m) => m.default));
-*
-* function Panel() {
-*   chart.run(); // server: awaited · hydration: deferred · client: import
-*   return (
-*     <Await fallback={() => <em>loading…</em>}>{chart}</Await>
-*   );
-* }
-* ```
-*
-* @example Passing props to a code-split component:
-* ```tsx
-* const chart = async(() => import("./chart").then((m) => m.default));
-* chart.run();
-*
-* <Await fallback={() => <em>loading…</em>}>
-*   {promise(chart.then((C) => () => <C data={data} />))}
-* </Await>
-* ```
-*/
 function Await(props) {
 	const read = (value) => typeof value === "function" && !isReactive(value) ? value() : value;
 	const children = read(props.children);
@@ -58,7 +22,7 @@ function Await(props) {
 	if (awaitables.length === 0) return children;
 	if (effectsInert()) return promise(Promise.all(awaitables).then(() => () => children));
 	const fallback = props.fallback;
-	const pending = () => awaitables.some((a) => a.state === "pending");
+	const pending = () => awaitables.some((a) => a.state !== "fulfilled" && a.state !== "rejected");
 	const region = () => pending() ? read(fallback) : children;
 	region[ASYNC_REGION] = {
 		ids: 1 + fromChildren.length,