what-core 0.12.3 → 0.13.0

package/index.d.ts

@@ -28,7 +28,13 @@ export function signal<T>(initial: T, debugName?: string): Signal<T>;
 export function computed<T>(fn: () => T): Computed<T>;
 export function effect(fn: () => void | (() => void), opts?: { stable?: boolean }): () => void;
 export function signalMemo<T>(fn: () => T): Computed<T>;
-export function batch<T>(fn: () => T): T;
+/**
+ * Group signal writes so effects run once at the end. The callback's return
+ * value is DISCARDED: batch() returns undefined. It was declared as `<T>(fn: ()
+ * => T) => T`, so `const rows = batch(() => compute())` typechecked and handed
+ * back undefined at runtime.
+ */
+export function batch(fn: () => unknown): void;
 export function untrack<T>(fn: () => T): T;
 export function flushSync(): void;
 export function createRoot<T>(fn: (dispose: () => void) => T): T;
@@ -46,10 +52,17 @@ export function onRootCleanup(fn: () => void): void;
 // --- Virtual DOM ---
 
 export type PrimitiveChild = string | number | boolean | null | undefined;
-export type VNodeChild = PrimitiveChild | VNode | (() => VNodeChild) | VNodeChild[];
+
+// `VNode<any>`, not `VNode`. VNode is invariant in P (its `tag` holds a
+// `Component<P>`, whose parameter position is contravariant under
+// strictFunctionTypes), so `VNode` — which means `VNode<Record<string, any>>` —
+// rejects every specifically-typed node. `h('div', {}, h('h1', { style: '' }))`
+// did not compile for any TypeScript user before 0.12.5, and neither did
+// passing that tree to mount().
+export type VNodeChild = PrimitiveChild | VNode<any> | (() => VNodeChild) | VNodeChild[];
 
 /** A component may legitimately render nothing, so `null` is part of the contract. */
-export type Component<P = {}> = ((props: P & { children?: VNodeChild }) => VNode | null) & {
+export type Component<P = {}> = ((props: P & { children?: VNodeChild }) => VNode<any> | null) & {
   /**
    * Opt out of realizing compiled children before the component runs.
    *
@@ -83,7 +96,7 @@ export function html(strings: TemplateStringsArray, ...values: any[]): VNode | V
 
 // --- DOM ---
 
-export function mount(vnode: VNodeChild, container: string | Element): () => void;
+export function mount(vnode: VNodeChild, container: string | Element | DocumentFragment): () => void;
 
 /** Attach reactive bindings to server-rendered DOM instead of creating it. */
 export function hydrate(vnode: VNodeChild, container: Element): Node | null;
@@ -106,11 +119,33 @@ export function classList(el: Element, classes: Record<string, boolean | (() =>
 
 // --- Hooks ---
 
-export function useState<T>(initial: T | (() => T)): [T, (value: Updater<T>) => void];
+/**
+ * Returns [signal, setter]. The first element is the SIGNAL ITSELF, not a
+ * snapshot value: components run once, so there is no re-render to hand a new
+ * `T` to. Read it by calling it (`count()`), or pass it straight into JSX where
+ * insert() binds it reactively.
+ *
+ * It was declared as `[T, setter]`, which made the correct code (`count()`) a
+ * type error and the wrong code (`count + 1`) type-check.
+ */
+export function useState<T>(initial: T | (() => T)): [Signal<T>, (value: Updater<T>) => void];
 export function useSignal<T>(initial: T | (() => T)): Signal<T>;
 export function useComputed<T>(fn: () => T): Computed<T>;
 export function useEffect(fn: () => void | (() => void), deps?: unknown[]): void;
-export function useMemo<T>(fn: () => T, deps?: unknown[]): T;
+/**
+ * Returns a COMPUTED ACCESSOR, not the value. Same reason as useState: the
+ * component body runs once, so nothing would ever hand back a refreshed `T`.
+ * Read it by calling it (`total()`), or pass the accessor straight into JSX
+ * where insert() tracks it.
+ *
+ * `deps` is accepted for React familiarity and ignored at runtime: computed()
+ * tracks whatever signals the callback actually reads.
+ *
+ * It was declared as `T`, which inverted both halves: `useMemo(...) * 2`
+ * type-checked and produced NaN, while the correct `useMemo(...)()` was the
+ * type error.
+ */
+export function useMemo<T>(fn: () => T, deps?: unknown[]): Computed<T>;
 export function useCallback<T extends (...args: any[]) => any>(fn: T, deps?: unknown[]): T;
 export function useRef<T>(initial: T): { current: T };
 
@@ -121,11 +156,19 @@ export interface Context<T> {
 
 export function createContext<T>(defaultValue: T): Context<T>;
 export function useContext<T>(context: Context<T>): T;
+/**
+ * Returns [signal, dispatch]. The first element is the SIGNAL ITSELF, exactly
+ * as useState returns it and for the same run-once reason. Read it with
+ * `state()`.
+ *
+ * It was declared as `[S, dispatch]`, so `state.items` type-checked (and read
+ * `undefined` off a function object) while `state()` did not.
+ */
 export function useReducer<S, A>(
   reducer: (state: S, action: A) => S,
   initialState: S,
   init?: (initial: S) => S,
-): [S, (action: A) => void];
+): [Signal<S>, (action: A) => void];
 export function onMount(fn: () => void): void;
 export function onCleanup(fn: () => void): void;
 
@@ -190,11 +233,22 @@ export function Island(props: IslandProps): VNode;
 
 // --- State ---
 
-export type DerivedFn<T> = ((state: any) => T) & { _isDerived: true };
+/** `_storeComputed` is the marker createStore() actually reads to tell a derived value from an action. */
+export type DerivedFn<T> = ((state: any) => T) & { _storeComputed: true };
 export function derived<T>(fn: (state: any) => T): DerivedFn<T>;
+/** @deprecated Use derived(). Warns once at runtime. */
 export function storeComputed<T>(fn: (state: any) => T): DerivedFn<T>;
 export type StoreDefinition = Record<string, any>;
-export type Store<T extends StoreDefinition> = T;
+/**
+ * The store hook resolves every derived key to its VALUE. State and derived
+ * keys are both getters on the returned object, only actions stay callable.
+ * `Store<T> = T` left a derived key typed as the DerivedFn you wrote in the
+ * definition, so `store.total` looked callable and `store.total * 2` was the
+ * type error, which is backwards from the runtime.
+ */
+export type Store<T extends StoreDefinition> = {
+  [K in keyof T]: T[K] extends DerivedFn<infer U> ? U : T[K];
+};
 export function createStore<T extends StoreDefinition>(definition: T): () => Store<T>;
 export function atom<T>(initial: T): Signal<T>;
 
@@ -280,31 +334,153 @@ export function smoothScrollTo(
 ): Promise<void>;
 
 // --- Animation ---
+//
+// Every accessor below is a plain getter function, NOT a Signal: the objects
+// these factories return expose reads through closures and offer writes as
+// named methods (set/snap/setValue), so nothing here carries .set/.peek. The
+// declarations used to promise Signal<number> and a single shared SpringValue
+// shape for both spring() and tween(), which are two different objects.
+
+export interface SpringConfig {
+  stiffness?: number;
+  damping?: number;
+  mass?: number;
+  precision?: number;
+}
 
+/** Physics-based value. `set()` retargets and animates; `snap()` jumps without animating. */
 export interface SpringValue {
   current(): number;
-  set(value: number): void;
+  target(): number;
+  velocity(): number;
+  isAnimating(): boolean;
+  set(target: number): void;
   stop(): void;
-  reset(): void;
+  snap(value: number): void;
+  subscribe(fn: (value: number) => void): () => void;
+}
+
+export interface TweenConfig {
+  duration?: number;
+  easing?: (t: number) => number;
+  onUpdate?: (value: number, progress: number) => void;
+  onComplete?: () => void;
+}
+
+/**
+ * Easing-based interpolation from `from` to `to`. Starts immediately on
+ * creation and runs to completion, so it exposes `cancel()` rather than the
+ * spring's retargeting `set()`/`stop()`.
+ */
+export interface TweenValue {
+  progress(): number;
+  value(): number;
+  isAnimating(): boolean;
+  cancel(): void;
+  subscribe(fn: (value: number) => void): () => void;
 }
 
-export function spring(initialValue?: number, config?: Record<string, any>): SpringValue;
-export function tween(initialValue?: number, config?: Record<string, any>): SpringValue;
+export function spring(initialValue: number, config?: SpringConfig): SpringValue;
+/**
+ * Both endpoints are required and positional. This was declared as
+ * `tween(initialValue?, config?)` returning a SpringValue, so the documented
+ * call `tween(0, 100, { duration: 300 })` was a type error, while
+ * `tween(0).current()` type-checked and threw (`current` does not exist, and a
+ * missing `to` interpolates toward undefined).
+ */
+export function tween(from: number, to: number, config?: TweenConfig): TweenValue;
 export const easings: Record<string, (t: number) => number>;
-export function useTransition(options?: Record<string, any>): {
-  mounted: Signal<boolean>;
-  styles: Computed<Record<string, any>>;
-  show: () => void;
-  hide: () => void;
+/**
+ * Drives a 0..1 progress value over `duration`. This is NOT React's
+ * useTransition, and it never had the mounted/styles/show/hide members that
+ * were declared here, and all four were undefined at runtime.
+ */
+export function useTransition(options?: { duration?: number; easing?: (t: number) => number }): {
+  isTransitioning: () => boolean;
+  progress: () => number;
+  start: (callback?: () => void) => Promise<void>;
 };
-export function useGesture(ref: { current?: Element | null } | Element, handlers?: Record<string, (payload: any) => void>): void;
-export function useAnimatedValue(initialValue?: number): {
-  value: Signal<number>;
-  animateTo: (target: number, config?: Record<string, any>) => Promise<void>;
+
+/** Live gesture state. `startX`/`startY` are plain numbers rewritten in place at gesture start. */
+export interface GestureState {
+  isDragging: Signal<boolean>;
+  startX: number;
+  startY: number;
+  currentX: Signal<number>;
+  currentY: Signal<number>;
+  deltaX: Signal<number>;
+  deltaY: Signal<number>;
+  velocity: Signal<GestureVelocity>;
+}
+
+export interface GestureVelocity {
+  x: number;
+  y: number;
+}
+
+/**
+ * `preventDefault` is why this cannot be a `Record<string, (payload) => void>`:
+ * it sits in the same object as the callbacks and is a boolean.
+ */
+export interface GestureHandlers {
+  onDragStart?: (payload: { x: number; y: number }) => void;
+  onDrag?: (payload: {
+    x: number; y: number; deltaX: number; deltaY: number; velocity: GestureVelocity;
+  }) => void;
+  onDragEnd?: (payload: { deltaX: number; deltaY: number; velocity: GestureVelocity }) => void;
+  onPinch?: (payload: { scale: number; centerX: number; centerY: number }) => void;
+  onSwipe?: (payload: { direction: 'up' | 'down' | 'left' | 'right'; velocity: GestureVelocity }) => void;
+  onTap?: (payload: { x: number; y: number }) => void;
+  onLongPress?: (payload: { x: number; y: number }) => void;
+  /** Opt in to e.preventDefault() in the touch handlers (listeners become non-passive). */
+  preventDefault?: boolean;
+}
+
+/** Returns the gesture state. It was declared `void`, so the state was unreachable from TypeScript. */
+export function useGesture(
+  ref: { current?: Element | null } | Element | (() => Element | null),
+  handlers?: GestureHandlers,
+): GestureState;
+
+/** Handle for one running animation started by useAnimatedValue. */
+export interface AnimationHandle {
   stop: () => void;
+}
+
+/**
+ * `animateTo` and `stop` were declared here and have never existed. Animations
+ * are started with spring()/timing(), each returning its own handle to stop.
+ */
+export function useAnimatedValue(initialValue: number): {
+  value: () => number;
+  setValue: (value: number) => void;
+  spring: (toValue: number, config?: SpringConfig) => AnimationHandle;
+  timing: (toValue: number, config?: TweenConfig) => AnimationHandle;
+  interpolate: (inputRange: number[], outputRange: number[]) => () => number;
+  subscribe: (fn: (value: number) => void) => () => void;
 };
-export function createTransitionClasses(name: string): string;
-export function cssTransition(config: Record<string, any>): Record<string, any>;
+
+export interface TransitionClasses {
+  enter: string;
+  enterActive: string;
+  enterDone: string;
+  exit: string;
+  exitActive: string;
+  exitDone: string;
+}
+
+/** Returns the six class NAMES for `name`, not a single string. */
+export function createTransitionClasses(name: string): TransitionClasses;
+/**
+ * Applies the enter/exit class sequence to an element and resolves when the
+ * transition is done. It was declared as a synchronous `(config) => object`.
+ */
+export function cssTransition(
+  element: Element,
+  name: string,
+  type?: 'enter' | 'exit',
+  duration?: number,
+): Promise<void>;
 
 // --- Accessibility ---
 
@@ -353,11 +529,51 @@ export function useAriaChecked(initialChecked?: boolean): {
   checkboxProps: () => Record<string, any>;
 };
 
-export function useRovingTabIndex(itemCountOrSignal: number | (() => number)): {
+export interface RovingTabIndexOptions {
+  /**
+   * Container role, emitted by containerProps(). The hook emits NO role by
+   * default: roving tabindex is the shared keyboard mechanic of toolbars,
+   * menus, trees, grids, tablists, radiogroups and listboxes, and a default
+   * spread last would silently overwrite the role the caller wrote beside it.
+   */
+  role?: string;
+}
+
+/**
+ * Props for one roving item. `ref` is the item's REGISTRATION (the hook holds
+ * the node through it and cannot move focus without it), so a `ref` passed via
+ * `overrides` is chained rather than replaced. `tabIndex` is an accessor, not a
+ * number: exactly one item is tabbable at a time and which one changes as focus
+ * roves, so a resolved value could not survive the spread.
+ */
+export interface RovingItemProps {
+  ref: { current: Element | null };
+  tabIndex: () => number;
+  onKeyDown: (e: KeyboardEvent) => void;
+  onFocus: (e: Event) => void;
+  [prop: string]: any;
+}
+
+export function useRovingTabIndex(
+  itemCountOrSignal: number | (() => number),
+  options?: RovingTabIndexOptions,
+): {
+  /** Active index, clamped to the current count so the group is never untabbable. */
   focusIndex: () => number;
+  /**
+   * Set the active index. Out-of-range indexes are REFUSED, not clamped. Moves
+   * real focus only when the group already owns it, so syncing from application
+   * state cannot steal focus from elsewhere on the page.
+   */
   setFocusIndex: (index: number) => void;
-  getItemProps: (index: number) => Record<string, any>;
-  containerProps: () => Record<string, any>;
+  /**
+   * Explicitly move focus to an item (a menu focusing its first item on open).
+   * Returns the element it focused, or null when the index is out of range or
+   * the item is not in the DOM.
+   */
+  focusItem: (index: number) => Element | null;
+  getItemProps: (index: number, overrides?: Record<string, any>) => RovingItemProps;
+  containerProps: (overrides?: Record<string, any>) => Record<string, any>;
 };
 
 export function VisuallyHidden(props: { children?: VNodeChild; as?: string }): VNode;
@@ -413,7 +629,8 @@ export function Spinner(props?: Record<string, any>): VNode;
 // --- Data Fetching ---
 
 export function useFetch<T = any>(url: string, options?: Record<string, any>): {
-  data: () => T;
+  /** null until the first response lands. It was declared as bare `T`, so strict-mode callers skipped the check they need. */
+  data: () => T | null;
   error: () => any;
   isLoading: () => boolean;
   refetch: () => Promise<void>;
@@ -429,36 +646,88 @@ export function useSWR<T = any>(key: string | null | false, fetcher: (key: strin
   revalidate: () => Promise<T | void>;
 };
 
+/**
+ * 'idle' is a real state, not a placeholder: a query with `enabled: false` and
+ * nothing cached is idle, and reporting it as loading is what renders a spinner
+ * that never comes down.
+ */
+export type QueryStatus = 'idle' | 'loading' | 'success' | 'error';
+/** Whether a request is on the wire, independent of whether data exists. */
+export type FetchStatus = 'idle' | 'fetching';
+
+/**
+ * Any array key is joined into a single normalized string, so an array and its
+ * normalization address the same cache entry everywhere a key is accepted.
+ */
+export type QueryKey = string | readonly unknown[];
+
 export function useQuery<T = any>(options: Record<string, any>): {
   data: () => T | null;
   error: () => any;
-  status: () => string;
+  status: () => QueryStatus;
+  fetchStatus: () => FetchStatus;
   isLoading: () => boolean;
   isFetching: () => boolean;
   isError: () => boolean;
   isSuccess: () => boolean;
+  isIdle: () => boolean;
+  /** Whether the `enabled` gate is currently open. */
+  isEnabled: () => boolean;
   refetch: () => Promise<T | void>;
 };
 
+/**
+ * Pages, plus the param each was fetched with. `pageParams[i]` names `pages[i]`.
+ */
+export interface InfiniteData<T> {
+  pages: T[];
+  pageParams: unknown[];
+}
+
+/**
+ * `data()` hands back the page CONTAINER, not a flat array. It was declared as
+ * `T[]`, so `data().map(...)` type-checked and threw. The rows are in
+ * `data().pages`. A `select` option replaces the container wholesale, and that
+ * transformation is not expressible here.
+ */
 export function useInfiniteQuery<T = any>(options: Record<string, any>): {
-  data: () => T[];
+  data: () => InfiniteData<T>;
   error: () => any;
-  status: () => string;
+  status: () => QueryStatus;
   isLoading: () => boolean;
-  isFetchingNextPage: () => boolean;
+  isError: () => boolean;
+  isSuccess: () => boolean;
+  isIdle: () => boolean;
+  isFetching: () => boolean;
+  isEnabled: () => boolean;
   hasNextPage: () => boolean;
+  hasPreviousPage: () => boolean;
+  isFetchingNextPage: () => boolean;
+  isFetchingPreviousPage: () => boolean;
   fetchNextPage: () => Promise<void>;
+  fetchPreviousPage: () => Promise<void>;
   refetch: () => Promise<void>;
 };
 
+/**
+ * Synchronous. It was declared as returning Promise<void>, so `await
+ * invalidateQueries(...)` awaited undefined and read as "the refetches are
+ * done" when they had only been kicked off. The subscribers it wakes fetch on
+ * their own.
+ *
+ * An array key is a PREFIX unless `exact` is set: invalidateQueries(['todos'])
+ * also invalidates ['todos', 1]. `hard` clears the cached value immediately
+ * (loading state); the default keeps stale data on screen while it refetches.
+ */
 export function invalidateQueries(
-  keyOrPredicate: string | ((key: string) => boolean),
-  options?: { exact?: boolean },
-): Promise<void>;
-
-export function prefetchQuery<T = any>(key: string, fetcher: (key: string) => Promise<T>): Promise<T>;
-export function setQueryData<T = any>(key: string, updater: T | ((prev: T | null) => T)): void;
-export function getQueryData<T = any>(key: string): T | null;
+  keyOrPredicate: QueryKey | ((key: string) => boolean),
+  options?: { exact?: boolean; hard?: boolean },
+): void;
+
+export function prefetchQuery<T = any>(key: QueryKey, fetcher: (key: string) => Promise<T>): Promise<T>;
+export function setQueryData<T = any>(key: QueryKey, updater: T | ((prev: T | null) => T)): void;
+/** `undefined` for a key the cache has never held; `null` for one that was emptied. */
+export function getQueryData<T = any>(key: QueryKey): T | null | undefined;
 export function clearCache(): void;
 
 // --- Forms ---
@@ -469,14 +738,39 @@ export interface FieldError {
   [key: string]: any;
 }
 
-export interface RegisterProps {
+/**
+ * What register() actually hands back, which varies by control type. The event
+ * handlers are LOWERCASE (`oninput`, `onchange`), because that is the key the
+ * DOM binding and the merge in <Input>/<Radio> look for; `onInput` was declared
+ * here and register() has never defined it, so `register('email').onInput(e)`
+ * type-checked and threw at the first keystroke.
+ *
+ * `value` and `checked` are reactive rather than snapshots: `value` and the
+ * checkbox `checked` are getters, and the radio `checked` is a thunk, so that a
+ * spread (`{...register('email')}`) binds instead of freezing the value at
+ * mount.
+ *
+ * A closed type alias rather than an interface: the key set really is closed
+ * (this is the whole object register() builds), and closing it is what makes
+ * the phantom `onInput` an error again instead of an `any` off an index
+ * signature. It must stay a `type`, not an `interface`, because only a type
+ * alias gets the implicit index signature that `h('input', register(name))`
+ * needs to be assignable to Record<string, any>.
+ */
+export type RegisterProps = {
   name: string;
-  value: any;
-  onInput: (e: any) => void;
   onBlur: () => void;
   onFocus: () => void;
   ref?: any;
-}
+  /** text/select/textarea, and the option's own value on a radio. */
+  value?: any;
+  /** checkbox/radio only. */
+  checked?: boolean | (() => boolean);
+  /** text/select/textarea only. */
+  oninput?: (e: any) => void;
+  /** checkbox/radio only. */
+  onchange?: (e: any) => void;
+};
 
 export interface FormState {
   readonly values: Record<string, any>;
@@ -485,6 +779,8 @@ export interface FormState {
   readonly touched: Record<string, boolean>;
   isDirty: () => boolean;
   isValid: Computed<boolean>;
+  /** True while the resolver is running. Present since resolvers went async; never declared. */
+  isValidating: () => boolean;
   isSubmitting: () => boolean;
   isSubmitted: () => boolean;
   submitCount: () => number;
@@ -578,6 +874,15 @@ export interface ErrorCodeDefinition {
 
 export const ERROR_CODES: Record<string, ErrorCodeDefinition>;
 
+/**
+ * Look up a catalogue entry by its `ERR_*` code.
+ *
+ * Errors thrown outside what-core carry only their code — the suggestion and
+ * the worked example live once, in the catalogue, so that the client bundle
+ * does not have to ship the prose. This is how they are recovered.
+ */
+export function getErrorDefinition(code: string): ErrorCodeDefinition | undefined;
+
 export interface WhatErrorJSON {
   code: string;
   message: string;
@@ -676,3 +981,24 @@ export function getMountedComponents(): unknown[];
 export function registerSignal(sig: unknown): void;
 export function unregisterSignal(sig: unknown): void;
 export function getActiveSignals(): unknown[];
+
+// --- Internal cross-package exports ---
+// Underscore-prefixed names are not public API and carry no compatibility
+// promise. They are declared here because sibling packages in this repo import
+// them across the package boundary (what-server, what-text), and an
+// undeclared cross-package import is exactly the rename that ships broken:
+// `hygiene:types` skips `_`-prefixed names in its reverse direction, so
+// nothing else would have caught it. Application code should not use these.
+
+/** @internal Used by what-server. True for `aria-*` and `data-*` attribute names. */
+export function _isAriaAttr(name: string): boolean;
+/** @internal Used by what-server. Opens an SSR component scope. */
+export function _beginComponentSSR(...args: unknown[]): unknown;
+/** @internal Used by what-server. Closes the scope opened by `_beginComponentSSR`. */
+export function _endComponentSSR(...args: unknown[]): unknown;
+/** @internal Used by what-server. The keyed-array mapping `<For>` compiles down to. */
+export function _mapArrayToArray(...args: unknown[]): unknown;
+/** @internal Used by what-server/node. Installs the Node AsyncLocalStorage backend. */
+export function __installServerContextStorage(storage: unknown): void;
+/** @internal Used by what-text. Lets the text engine intercept text-node insertion. */
+export function _setTextInsertHook(hook: unknown): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-core",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "What Framework - Signal-based UI framework built for AI agents",
   "type": "module",
   "main": "src/index.js",

package/render.d.ts

@@ -42,3 +42,10 @@ export function isHydrating(): boolean;
 // SVG counterpart to template(): elements are created in the SVG namespace, which
 // a plain innerHTML template cannot do.
 export function svgTemplate(html: string): () => Element;
+
+/**
+ * @internal The component-call helper the compiler emits for `<Component />`.
+ * Re-exported by what-framework/render so compiled output can import it from
+ * the package a scaffolded app actually depends on.
+ */
+export function _$createComponent(component: unknown, props?: unknown, ...args: unknown[]): unknown;