@granularjs/core 1.0.0

package/src/core/runtime.js

@@ -0,0 +1,28 @@
+export { bootstrap } from './bootstrap.js';
+export { component } from './component/function-component.js';
+export { signal, isSignal, setSignal, readSignal } from './reactivity/signal.js';
+export { state, isState, isStatePath, isComputed } from './reactivity/state.js';
+export { after, before, set, subscribe } from './reactivity/observe.js';
+export { resolve } from './reactivity/resolve.js';
+export { computed } from './reactivity/computed.js';
+export { concat } from './reactivity/concat.js';
+export { persist } from './reactivity/persist.js';
+export { form } from './forms/form.js';
+export { list } from './dom/list.js';
+export { when } from './dom/when.js';
+export { ErrorBoundary } from './dom/error-boundary.js';
+export { virtualList } from './dom/virtual-list.js';
+export { portal } from './dom/portal.js';
+export { WebSocketClient, createWebSocket } from './network/websocket.js';
+export { observableArray } from './collections/observable-array.js';
+export { Renderable } from './renderable/renderable.js';
+export { Renderer } from './renderable/renderer.js';
+export { renderToString, hydrate } from './renderable/render-string.js';
+export { QueryClient } from './query/query-client.js';
+export { EventHub } from './events/event-hub.js';
+export { Router, createRouter, router } from './router/router.js';
+export { context } from './context.js';
+export { Elements } from './dom/tags.js';
+export * from './dom/tags.js';
+
+

package/src/index.js

@@ -0,0 +1,42 @@
+export {
+  bootstrap,
+  component,
+  signal,
+  isSignal,
+  setSignal,
+  readSignal,
+  state,
+  isState,
+  isStatePath,
+  isComputed,
+  after,
+  before,
+  set,
+  resolve,
+  computed,
+  concat,
+  subscribe,
+  persist,
+  form,
+  list,
+  when,
+  ErrorBoundary,
+  virtualList,
+  portal,
+  WebSocketClient,
+  createWebSocket,
+  observableArray,
+  Renderable,
+  Renderer,
+  renderToString,
+  hydrate,
+  QueryClient,
+  EventHub,
+  Router,
+  createRouter,
+  router,
+  Elements,
+  context,
+} from './core/runtime.js';
+
+export * from './core/dom/tags.js';

package/types/core/bootstrap.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Creates and attaches a component instance or render function to a target element.
+ *
+ * @template T
+ * @param {new (...args: any[]) => T | (() => any)} ComponentClass
+ * @param {string|Element} target
+ * @returns {Promise<T|{ unmount(): void }>}
+ */
+export function bootstrap<T>(ComponentClass: new (...args: any[]) => T | (() => any), target: string | Element): Promise<T | {
+    unmount(): void;
+}>;

package/types/core/collections/observable-array.d.ts

@@ -0,0 +1,25 @@
+export function isObservableArray(value: any): boolean;
+export function observableArray(initial?: any[]): any[];
+export type ObservableArrayPatchInsert = {
+    type: "insert";
+    index: number;
+    items: any[];
+};
+export type ObservableArrayPatchRemove = {
+    type: "remove";
+    index: number;
+    count: number;
+    items: any[];
+};
+export type ObservableArrayPatchSet = {
+    type: "set";
+    index: number;
+    value: any;
+    prev: any;
+};
+export type ObservableArrayPatchReset = {
+    type: "reset";
+    items: any[];
+    prevItems: any[];
+};
+export type ObservableArrayPatch = ObservableArrayPatchInsert | ObservableArrayPatchRemove | ObservableArrayPatchSet | ObservableArrayPatchReset;

package/types/core/component/function-component.d.ts

@@ -0,0 +1,14 @@
+export function component(renderFn: any): {
+    (props: any): FunctionComponentInstance;
+    __zbFactory: boolean;
+};
+declare class FunctionComponentInstance extends DirtyHost {
+    constructor(renderFn: any, props: any);
+    props: any;
+    mountInto(parent: any, beforeNode: any): void;
+    renderToString(render: any): any;
+    onCleanup(fn: any): void;
+    #private;
+}
+import { DirtyHost } from '../reactivity/dirty-host.js';
+export {};

package/types/core/context.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Creates a context for sharing reactive state across a component tree
+ * without prop drilling.
+ *
+ * Returns { scope, state }:
+ * - scope(value?) — creates a new provider level. Returns a state with
+ *     .get(), .set(), path access, and .serve(renderable) to wrap children.
+ * - state() — returns a reactive state bound to the nearest ancestor provider.
+ *
+ * Usage:
+ *   const sizeCtx = context([1, 2, 3]);
+ *
+ *   const Parent = (...children) => {
+ *     const sizes = sizeCtx.scope();
+ *     sizes.set([10, 20, 30]);
+ *     return sizes.serve(Div(...children));
+ *   };
+ *
+ *   const Child = () => {
+ *     const sizes = sizeCtx.state();
+ *     return Div(sizes[0]);
+ *   };
+ *
+ *   Parent(Child());
+ */
+export function context(defaultValue: any): {
+    scope: (value: any) => {};
+    state: () => {};
+};

package/types/core/dom/dom.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Creates a comment node used as a stable DOM anchor.
+ * @param {string} label
+ * @param {string} name
+ */
+export function createComment(label: string, name: string): Comment;
+/**
+ * Removes all sibling nodes between two anchors.
+ * @param {Comment} start
+ * @param {Comment} end
+ * @param {(node: Node) => void} [disposer]
+ */
+export function clearBetween(start: Comment, end: Comment, disposer?: (node: Node) => void): void;

package/types/core/dom/element.d.ts

@@ -0,0 +1,10 @@
+export class ElementNode extends Renderable {
+    constructor(tagName: any, props?: {}, children?: any[]);
+    tagName: any;
+    props: {};
+    children: any[];
+    mountInto(parent: any, beforeNode: any): void;
+    renderToString(render: any): string;
+    #private;
+}
+import { Renderable } from '../renderable/renderable.js';

package/types/core/dom/error-boundary.d.ts

@@ -0,0 +1,8 @@
+export function ErrorBoundary(options: any, child: any): ErrorBoundaryNode;
+export class ErrorBoundaryNode extends Renderable {
+    constructor(options: any, child: any);
+    mountInto(parent: any, beforeNode: any): void;
+    renderToString(render: any): any;
+    #private;
+}
+import { Renderable } from '../renderable/renderable.js';

package/types/core/dom/input-format.d.ts

@@ -0,0 +1,6 @@
+export function normalizeInputFormat(format: any): any;
+export function applyInputFormat(inputValue: any, format: any): {
+    value: string;
+    visual: string;
+    raw: string;
+};

package/types/core/dom/list.d.ts

@@ -0,0 +1,8 @@
+export function list(items: any, renderItem: any): ListNode;
+export class ListNode extends Renderable {
+    constructor(items: any, renderItem: any);
+    mountInto(parent: any, beforeNode: any): void;
+    renderToString(render: any): any;
+    #private;
+}
+import { Renderable } from '../renderable/renderable.js';

package/types/core/dom/portal.d.ts

@@ -0,0 +1,8 @@
+export function portal(target: any, content: any): PortalNode;
+export class PortalNode extends Renderable {
+    constructor(target: any, content: any);
+    mountInto(_parent: any, _beforeNode: any): void;
+    renderToString(render: any): any;
+    #private;
+}
+import { Renderable } from '../renderable/renderable.js';

package/types/core/dom/tags.d.ts

@@ -0,0 +1,114 @@
+export const Elements: Readonly<{}>;
+export const Html: any;
+export const Head: any;
+export const Title: any;
+export const Base: any;
+export const Link: any;
+export const Meta: any;
+export const Style: any;
+export const Body: any;
+export const Article: any;
+export const Section: any;
+export const Nav: any;
+export const Aside: any;
+export const H1: any;
+export const H2: any;
+export const H3: any;
+export const H4: any;
+export const H5: any;
+export const H6: any;
+export const Hgroup: any;
+export const Header: any;
+export const Footer: any;
+export const Address: any;
+export const Main: any;
+export const Search: any;
+export const P: any;
+export const Hr: any;
+export const Pre: any;
+export const Blockquote: any;
+export const Ol: any;
+export const Ul: any;
+export const Li: any;
+export const Dl: any;
+export const Dt: any;
+export const Dd: any;
+export const Figure: any;
+export const Figcaption: any;
+export const Div: any;
+export const Menu: any;
+export const A: any;
+export const Em: any;
+export const Strong: any;
+export const Small: any;
+export const S: any;
+export const Cite: any;
+export const Q: any;
+export const Dfn: any;
+export const Abbr: any;
+export const Ruby: any;
+export const Rt: any;
+export const Rp: any;
+export const Data: any;
+export const Time: any;
+export const Code: any;
+export const Var: any;
+export const Samp: any;
+export const Kbd: any;
+export const Sub: any;
+export const Sup: any;
+export const I: any;
+export const B: any;
+export const U: any;
+export const Mark: any;
+export const Bdi: any;
+export const Bdo: any;
+export const Span: any;
+export const Br: any;
+export const Wbr: any;
+export const Ins: any;
+export const Del: any;
+export const Picture: any;
+export const Source: any;
+export const Img: any;
+export const Iframe: any;
+export const Embed: any;
+export const HtmlObject: any;
+export const Param: any;
+export const Video: any;
+export const Audio: any;
+export const Track: any;
+export const Map: any;
+export const Area: any;
+export const Table: any;
+export const Caption: any;
+export const Colgroup: any;
+export const Col: any;
+export const Tbody: any;
+export const Thead: any;
+export const Tfoot: any;
+export const Tr: any;
+export const Td: any;
+export const Th: any;
+export const Form: any;
+export const Label: any;
+export const Input: any;
+export const Button: any;
+export const Select: any;
+export const Datalist: any;
+export const Optgroup: any;
+export const Option: any;
+export const Textarea: any;
+export const Output: any;
+export const Progress: any;
+export const Meter: any;
+export const Fieldset: any;
+export const Legend: any;
+export const Details: any;
+export const Summary: any;
+export const Dialog: any;
+export const Script: any;
+export const Noscript: any;
+export const Template: any;
+export const Slot: any;
+export const Canvas: any;

package/types/core/dom/virtual-list.d.ts

@@ -0,0 +1,8 @@
+export function virtualList(items: any, options: any): VirtualListNode;
+export class VirtualListNode extends Renderable {
+    constructor(items: any, options?: {});
+    mountInto(parent: any, beforeNode: any): void;
+    renderToString(render: any): any;
+    #private;
+}
+import { Renderable } from '../renderable/renderable.js';

package/types/core/dom/when.d.ts

@@ -0,0 +1,13 @@
+export function when(source: any, renderTrue: any, renderFalse: any): WhenNode;
+export function isWhen(value: any): boolean;
+export function readWhenValue(value: any): any;
+export function subscribeWhenValue(value: any, fn: any): any;
+export class WhenNode extends Renderable {
+    constructor(source: any, renderTrue: any, renderFalse: any);
+    mountInto(parent: any, beforeNode: any): void;
+    readValue(): any;
+    subscribeValue(fn: any): any;
+    renderToString(render: any): any;
+    #private;
+}
+import { Renderable } from '../renderable/renderable.js';

package/types/core/events/event-hub.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Minimal before/after event hub.
+ *
+ * - `before` handlers may return `false` to cancel the operation.
+ * - `after` handlers are fire-and-forget.
+ */
+export class EventHub {
+    /**
+     * @param {'before'|'after'} phase
+     * @param {string} type
+     * @param {(payload: any, ctx: any) => (void|boolean)} fn
+     * @returns {() => void}
+     */
+    on(phase: "before" | "after", type: string, fn: (payload: any, ctx: any) => (void | boolean)): () => void;
+    /**
+     * Emits a before event. Returns false when cancelled.
+     * @param {string} type
+     * @param {any} payload
+     * @param {any} ctx
+     * @returns {boolean}
+     */
+    emitBefore(type: string, payload: any, ctx: any): boolean;
+    /**
+     * Emits an after event.
+     * @param {string} type
+     * @param {any} payload
+     * @param {any} ctx
+     */
+    emitAfter(type: string, payload: any, ctx: any): void;
+    /**
+     * Returns a fluent API for registering hooks.
+     * @param {'before'|'after'} phase
+     */
+    phase(phase: "before" | "after"): {
+        /**
+         * Registers a handler for a given type.
+         * @param {string} type
+         * @param {(payload: any, ctx: any) => (void|boolean)} fn
+         */
+        on(type: string, fn: (payload: any, ctx: any) => (void | boolean)): () => void;
+        /**
+         * Registers a handler for any type.
+         * @param {(payload: any, ctx: any) => (void|boolean)} fn
+         */
+        any(fn: (payload: any, ctx: any) => (void | boolean)): () => void;
+    };
+    #private;
+}

package/types/core/forms/form.d.ts

@@ -0,0 +1,9 @@
+export function form(initial: any): {
+    values: {};
+    meta: {};
+    errors: {};
+    touched: {};
+    dirty: {};
+    validators: Set<any>;
+    reset: () => void;
+};

package/types/core/internal/symbols.d.ts

@@ -0,0 +1,4 @@
+export const INTERNAL: Readonly<{
+    instrumentBoundProp: symbol;
+    subscribeProp: symbol;
+}>;

package/types/core/network/websocket.d.ts

@@ -0,0 +1,18 @@
+export function createWebSocket(options: any): WebSocketClient;
+export class WebSocketClient {
+    constructor(options?: {});
+    state(): {};
+    before(): {
+        on(type: string, fn: (payload: any, ctx: any) => (void | boolean)): () => void;
+        any(fn: (payload: any, ctx: any) => (void | boolean)): () => void;
+    };
+    after(): {
+        on(type: string, fn: (payload: any, ctx: any) => (void | boolean)): () => void;
+        any(fn: (payload: any, ctx: any) => (void | boolean)): () => void;
+    };
+    setUrl(next: any): void;
+    connect(): void;
+    send(value: any): void;
+    close(code: any, reason: any): void;
+    #private;
+}

package/types/core/query/query-client.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Query manager with caching and refetch orchestration.
+ */
+export class QueryClient {
+    /**
+     * Gets (or creates) a query instance for the given key.
+     *
+     * @param {QueryOptions} options
+     * @returns {Store & QueryState & { refetch(): Promise<any>, invalidate(): void, cancel(): void, ensure(): (Promise<any>|null), isStale: boolean }}
+     */
+    query(options: QueryOptions): Store & QueryState & {
+        refetch(): Promise<any>;
+        invalidate(): void;
+        cancel(): void;
+        ensure(): (Promise<any> | null);
+        isStale: boolean;
+    };
+    use(middleware: any): () => void;
+    service(config?: {}): {
+        request: (endpoint: any, input?: {}) => Promise<any>;
+    };
+    /**
+     * Marks a query as invalidated.
+     * @param {QueryKey} key
+     */
+    invalidate(key: QueryKey): void;
+    /**
+     * Refetches a query immediately.
+     * @param {QueryKey} key
+     * @returns {Promise<any>|null}
+     */
+    refetch(key: QueryKey): Promise<any> | null;
+    /**
+     * Removes a query from cache (cancels in-flight).
+     * @param {QueryKey} key
+     */
+    remove(key: QueryKey): void;
+    #private;
+}
+export type QueryKeyAtom = string | number | boolean | null;
+export type QueryKey = QueryKeyAtom | QueryKeyAtom[];
+export type QueryStatus = "idle" | "loading" | "success" | "error";
+export type QueryState = {
+    data: any;
+    error: any;
+    status: QueryStatus;
+    fetching: boolean;
+    updatedAt: number | null;
+    errorAt: number | null;
+    invalidated: boolean;
+};
+export type QueryContext = {
+    key: QueryKey;
+    signal: AbortSignal;
+};
+export type QueryOptions = {
+    key: QueryKey;
+    fetcher: (ctx: QueryContext) => Promise<any>;
+    /**
+     * ms
+     */
+    staleTime?: number;
+    /**
+     * ms
+     */
+    cacheTime?: number;
+    refetchOnFocus?: boolean;
+    refetchOnReconnect?: boolean;
+    retry?: number;
+    retryDelay?: (attempt: number) => number;
+    dedupe?: boolean;
+    refetchOnInvalidate?: boolean;
+};

package/types/core/reactivity/after-flush.d.ts

@@ -0,0 +1,4 @@
+export namespace AfterFlush {
+    function schedule(): void;
+    function add(run: any): () => boolean;
+}

package/types/core/reactivity/computed.d.ts

@@ -0,0 +1 @@
+export function computed(input: any): any;

package/types/core/reactivity/concat.d.ts

@@ -0,0 +1 @@
+export function concat(...input: any[]): any;

package/types/core/reactivity/dirty-host.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Base class that provides:
+ * - property instrumentation (dirty tracking)
+ * - microtask-batched flushing
+ * - subscription mechanism for template bindings
+ *
+ * This is part of the core runtime and is inherited by `Component`.
+ */
+export class DirtyHost extends Renderable {
+    [x: symbol]: ((prop: string, fn: () => void) => () => void) | ((prop: string) => void);
+    /**
+     * Registers BEFORE hooks. Handlers may return false to cancel.
+     * Example: `store.before().set(({ prop, next }) => next !== null)`
+     */
+    before(): {
+        on(type: string, fn: (payload: any, ctx: any) => (void | boolean)): () => void;
+        any(fn: (payload: any, ctx: any) => (void | boolean)): () => void;
+    };
+    /**
+     * Registers AFTER hooks.
+     * Example: `store.after().flush(({ props }) => console.log(props))`
+     */
+    after(): {
+        on(type: string, fn: (payload: any, ctx: any) => (void | boolean)): () => void;
+        any(fn: (payload: any, ctx: any) => (void | boolean)): () => void;
+    };
+    emitBefore(type: any, payload: any, ctx: any): boolean;
+    emitAfter(type: any, payload: any, ctx: any): void;
+    /**
+     * Batches multiple assignments into a single flush.
+     *
+     * @param {() => void} cb
+     */
+    set(cb: () => void): void;
+    /**
+     * Flushes all dirty properties, notifying any subscribers registered by bindings.
+     * Usually you don't need to call this manually, because assignments trigger a microtask flush.
+     */
+    update(): void;
+    #private;
+}
+import { Renderable } from '../renderable/renderable.js';

package/types/core/reactivity/observe.d.ts

@@ -0,0 +1,10 @@
+export function after(...targets: any[]): {
+    change(fn: any): () => void;
+    compute(fn: any, options?: {}): {};
+};
+export function before(...targets: any[]): {
+    change(fn: any): () => void;
+    compute(fn: any, options?: {}): {};
+};
+export function set(target: any, value: any): void;
+export function subscribe(target: any, selector: any, listener: any, equalityFn: any): {};

package/types/core/reactivity/persist.d.ts

@@ -0,0 +1 @@
+export function persist(target: any, options?: {}): any;

package/types/core/reactivity/resolve.d.ts

@@ -0,0 +1 @@
+export function resolve(value: any): any;

package/types/core/reactivity/signal.d.ts

@@ -0,0 +1,11 @@
+export function signal(initial: any): {
+    get(): any;
+    set(next: any, force?: boolean): boolean;
+    subscribe(fn: any): () => boolean;
+    before(fn: any): () => boolean;
+};
+export function isSignal(value: any): boolean;
+export function subscribeSignal(sig: any, fn: any): any;
+export function readSignal(sig: any): any;
+export function setSignal(sig: any, next: any, force?: boolean): any;
+export function getMappedArrayMeta(value: any): any;

package/types/core/reactivity/state.d.ts

@@ -0,0 +1,14 @@
+export function state(initial: any): {};
+export function createStateFromAdapter(adapter: any): {};
+export function mutateAdapter(adapter: any, optimistic: any, mutation: any, options?: {}): Promise<any>;
+export function isState(value: any): boolean;
+export function isComputed(value: any): boolean;
+export function isStatePath(value: any): any;
+export function readState(value: any): any;
+export function readStateFromRoot(value: any, root: any): any;
+export function subscribeState(value: any, fn: any): any;
+export function readStateMeta(meta: any): any;
+export function subscribeStateMeta(meta: any, fn: any): any;
+export function setStateValue(value: any, next: any): any;
+export function getMappedMeta(value: any): any;
+export function withDefaults(target: any, defaults: any, options?: {}): any;

package/types/core/renderable/render-string.d.ts

@@ -0,0 +1,2 @@
+export function renderToString(value: any): any;
+export function hydrate(target: any, value: any): void;

package/types/core/renderable/renderable.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Base contract for objects that can be mounted/unmounted by the core renderer.
+ */
+export class Renderable {
+    /**
+     * Mounts the instance into the DOM.
+     * @param {Node} parent
+     * @param {Node|null} beforeNode
+     */
+    mountInto(): void;
+    /**
+     * Unmounts and releases DOM/resources owned by the instance.
+     */
+    unmount(): void;
+}