@sky.ui/reactivity 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+/** Internal effect runner returned by `effect()`. */
+type EffectRunner = (() => void) & {
+    stopped: boolean;
+    paused: boolean;
+    stop: () => void;
+    pause: () => void;
+    resume: () => void;
+    scheduler: (run: () => void) => void;
+};
+type EffectOptions = {
+    lazy?: boolean;
+    scheduler?: (run: () => void) => void;
+    onCleanup?: () => void;
+};
+type CustomRefFactory<T> = (track: () => void, trigger: () => void) => {
+    get: () => T;
+    set: (value: T) => void;
+};
+type EffectScopeHandle = {
+    readonly active: boolean;
+    run<T>(fn: () => T): T;
+    stop(): void;
+};
+type Ref<T> = {
+    value: T;
+    readonly __isRef?: true;
+};
+type ComputedOptions<T> = {
+    get: () => T;
+    set?: (v: T) => void;
+};
+type WatchCallback = (newVal: unknown, oldVal: unknown, onCleanup: (fn: () => void) => void) => void;
+type WatchOptions = {
+    immediate?: boolean;
+    deep?: boolean;
+    flush?: 'pre' | 'post' | 'sync';
+};
+type WatchSource = unknown | (() => unknown) | (unknown | (() => unknown))[];
+type SetupFn = (() => Record<string, unknown>) | Record<string, unknown>;
+type ReactivityApp = {
+    mount(target: Element | string, initial?: Record<string, unknown>): {
+        ctx: Record<string, unknown>;
+        unmount: () => void;
+    };
+};
+/** Reactive proxy marker set on proxied objects. */
+interface ReactiveProxy {
+    __isReactive?: boolean;
+    __isReadonly?: boolean;
+    __isRef?: boolean;
+    [key: string | symbol]: unknown;
+}
+declare const SHALLOW_REF_TARGET: unique symbol;
+interface ShallowRefObject<T = unknown> {
+    value: T;
+    readonly __isRef?: true;
+    [SHALLOW_REF_TARGET]?: {
+        value: T;
+    };
+}
+
+declare function effect<T>(fn: () => T, opts?: EffectOptions): EffectRunner & (() => T);
+/** Alias for `effect()` (Vue `watchEffect` style). */
+declare const watchEffect: typeof effect;
+
+declare function reactive<T extends object>(obj: T): T;
+
+declare function readonly<T extends object>(obj: T): T;
+
+declare function shallowReactive<T extends object>(obj: T): T;
+
+declare function shallowReadonly<T extends object>(obj: T): T;
+
+declare function toRaw<T>(proxy: T): T;
+declare function markRaw<T extends object>(obj: T): T;
+declare function isReactive(obj: unknown): obj is ReactiveProxy;
+declare function isReadonly(obj: unknown): boolean;
+
+/** Mutable ref wrapper `{ value }` with deep reactivity on **`.value`** when assigned plain objects/arrays. */
+declare function ref<T>(v: T): Ref<T>;
+/** Ref whose **`.value`** is not deeply made reactive. */
+declare function shallowRef<T>(v: T): ShallowRefObject<T>;
+/** Forces subscribers to re-run for a **shallow** ref when inner object is mutated without replacing `.value`. */
+declare function triggerRef(r: ShallowRefObject | Ref<unknown> | null | undefined): void;
+declare function customRef<T>(factory: CustomRefFactory<T>): Ref<T>;
+
+declare function isRef(v: unknown): v is Ref<unknown> | ShallowRefObject;
+declare function unref<T>(v: T | Ref<T> | ShallowRefObject<T>): T;
+
+declare function toRef<T extends object, K extends keyof T>(object: T, key: K): Ref<T[K]>;
+declare function toRefs<T extends object>(object: T): {
+    [K in keyof T]: Ref<T[K]>;
+};
+
+declare function computed<T>(getterOrOptions: (() => T) | ComputedOptions<T>): Ref<T>;
+
+declare function watch(src: WatchSource, cb: WatchCallback, opts?: WatchOptions): () => void;
+
+declare const nextTick: (fn?: () => void) => Promise<void>;
+
+declare class EffectScope {
+    readonly detached: boolean;
+    active: boolean;
+    private readonly effects;
+    private readonly disposers;
+    constructor(detached?: boolean);
+    run<T>(fn: () => T): T;
+    register(runner: EffectRunner): void;
+    registerDispose(fn: () => void): void;
+    stop(): void;
+}
+declare function effectScope(detached?: boolean): EffectScope;
+declare function getCurrentScope(): EffectScope | null;
+declare function onScopeDispose(fn: () => void): void;
+
+declare function flushSync(fn: () => void): void;
+
+declare function mount(root: ParentNode | Element, ctx: Record<string, unknown>): Record<string, unknown>;
+
+declare function createReactivity(setup: SetupFn): ReactivityApp;
+
+type RenderToStringOptions = {
+    /** CSS selector for the mount root (default: `body`). */
+    root?: string;
+    /** Extra properties merged into context before setup exports. */
+    initial?: Record<string, unknown>;
+    /** When true, return full `<html>...</html>` instead of root outerHTML only. */
+    fullDocument?: boolean;
+    /** Remove `<!--sky-for-->` / `<!--if-chain-->` anchors from output (default: `true`). */
+    stripAnchors?: boolean;
+};
+/**
+ * One-shot SSR: compiles directives and `{{ }}` without reactive effects.
+ * Requires browser DOM or optional peer `linkedom` in Node.
+ */
+declare function renderToString(markup: string, ctx: Record<string, unknown>, options?: RenderToStringOptions): Promise<string>;
+
+type SSRDocument = Document & {
+    toString(): string;
+};
+/** Parse markup into a Document (browser `DOMParser` or optional `linkedom`). */
+declare function parseSSRDocument(markup: string): Promise<SSRDocument>;
+
+/** Run a template event-handler statement string against a context (for tests and tooling). */
+declare function runHandlerCode(code: string, ctx: Record<string, unknown>, $event?: unknown, $el?: Node | null): Promise<unknown>;
+
+declare global {
+    var __SKY_DEV__: boolean | undefined;
+}
+/** When `false`, dev warnings and verbose errors are suppressed (Vue-style). */
+declare function getSkyDev(): boolean;
+declare function setSkyDev(enabled: boolean): void;
+/** Snapshot at module load; prefer `getSkyDev()` for runtime checks. */
+declare const skyDevSnapshot: boolean;
+
+/** Stable warning codes (search docs / source by code). */
+declare const WarnCodes: {
+    readonly MODEL_ARG_ON_NATIVE: "MODEL_ARG_ON_NATIVE";
+    readonly MODEL_INVALID_KEY: "MODEL_INVALID_KEY";
+    readonly MODEL_UNKNOWN_MODIFIER: "MODEL_UNKNOWN_MODIFIER";
+    readonly MODEL_DUPLICATE: "MODEL_DUPLICATE";
+    readonly FOR_KEY_RECOMMENDED: "FOR_KEY_RECOMMENDED";
+    readonly FOR_INVALID_SYNTAX: "FOR_INVALID_SYNTAX";
+    readonly EVENT_UNKNOWN_MODIFIER: "EVENT_UNKNOWN_MODIFIER";
+    readonly HANDLER_RUNTIME: "HANDLER_RUNTIME";
+    readonly AST_EVAL: "AST_EVAL";
+    readonly AST_STMT: "AST_STMT";
+    readonly AST_BLOCKED: "AST_BLOCKED";
+    readonly MOUNT_TARGET_NOT_FOUND: "MOUNT_TARGET_NOT_FOUND";
+    readonly SSR_ROOT_NOT_FOUND: "SSR_ROOT_NOT_FOUND";
+    readonly SKY_HTML_UNSAFE: "SKY_HTML_UNSAFE";
+};
+type WarnCode = (typeof WarnCodes)[keyof typeof WarnCodes];
+
+type WarnContext = {
+    /** Element the warning relates to (shown as `<tag#id>`). */
+    element?: Element | null;
+    /** Short location hint, e.g. `@click` or `sky-for`. */
+    label?: string;
+};
+type SkyWarnHandler = (code: WarnCode, message: string, context?: WarnContext) => void;
+declare function setWarnHandler(handler: SkyWarnHandler | null): void;
+/**
+ * Log a development warning (no-op when `__SKY_DEV__` is false).
+ */
+declare function warn(code: WarnCode, args?: Record<string, string | number>, context?: WarnContext): void;
+/**
+ * Log each distinct warning once per element/label (Vue `warnOnce` style).
+ */
+declare function warnOnce(code: WarnCode, args?: Record<string, string | number>, context?: WarnContext): void;
+/**
+ * Log a runtime error with Sky formatting (handlers, AST, etc.).
+ */
+declare function logError(code: WarnCode, err: unknown, context?: WarnContext): void;
+/** Clear dedupe cache (tests). */
+declare function resetWarned(): void;
+
+export { type ComputedOptions, type CustomRefFactory, type EffectOptions, type EffectRunner, EffectScope, type EffectScopeHandle, type ReactivityApp, type Ref, type RenderToStringOptions, type SSRDocument, type SetupFn, type SkyWarnHandler, type WarnCode, WarnCodes, type WarnContext, type WatchCallback, type WatchOptions, type WatchSource, skyDevSnapshot as __SKY_DEV__, computed, createReactivity, customRef, effect, effectScope, flushSync, getCurrentScope, getSkyDev, isReactive, isReadonly, isRef, logError, markRaw, mount, nextTick, onScopeDispose, parseSSRDocument, reactive, readonly, ref, renderToString, resetWarned, runHandlerCode, setSkyDev, setWarnHandler, shallowReactive, shallowReadonly, shallowRef, toRaw, toRef, toRefs, triggerRef, unref, warn, warnOnce, watch, watchEffect };