round-core 0.0.5 → 0.0.7

package/src/index.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Round Framework Type Definitions
+ */
+
+export interface RoundSignal<T> {
+    /**
+     * Get or set the current value.
+     */
+    (newValue?: T): T;
+
+    /**
+     * Get the current value (reactive).
+     */
+    value: T;
+
+    /**
+     * Get the current value without tracking dependencies.
+     */
+    peek(): T;
+
+    /**
+     * Creates a transformed view of this signal.
+     */
+    transform<U>(fromInput: (v: U) => T, toOutput: (v: T) => U): RoundSignal<U>;
+
+    /**
+     * Attaches validation logic to the signal.
+     */
+    validate(validator: (next: T, prev: T) => string | boolean | undefined | null, options?: {
+        /** Timing of validation: 'input' (default) or 'blur'. */
+        validateOn?: 'input' | 'blur';
+        /** Whether to run validation immediately on startup. */
+        validateInitial?: boolean;
+    }): RoundSignal<T> & {
+        /** Signal containing the current validation error message. */
+        error: RoundSignal<string | null>;
+        /** Manually trigger validation check. Returns true if valid. */
+        check(): boolean
+    };
+
+    /**
+     * Creates a read/write view of a specific property path.
+     */
+    $pick<K extends keyof T>(path: K): RoundSignal<T[K]>;
+    $pick(path: string | string[]): RoundSignal<any>;
+
+    /**
+     * Internal: marks the signal as bindable for two-way bindings.
+     */
+    bind?: boolean;
+}
+
+export interface Signal {
+    <T>(initialValue?: T): RoundSignal<T>;
+    object<T extends object>(initialState: T): { [K in keyof T]: RoundSignal<T[K]> };
+}
+
+/**
+ * Creates a reactive signal.
+ */
+export const signal: Signal;
+
+/**
+ * Creates a bindable signal intended for two-way DOM bindings.
+ */
+export interface Bindable {
+    <T>(initialValue?: T): RoundSignal<T>;
+    object<T extends object>(initialState: T): { [K in keyof T]: RoundSignal<T[K]> };
+}
+
+/**
+ * Creates a bindable signal intended for two-way DOM bindings.
+ */
+export const bindable: Bindable;
+
+/**
+ * Run a function without tracking any signals it reads.
+ * Any signals accessed inside the function will not become dependencies of the current effect.
+ */
+export function untrack<T>(fn: () => T): T;
+
+/**
+ * Create a reactive side-effect that runs whenever its signal dependencies change.
+ */
+export function effect(fn: () => void | (() => void), options?: {
+    /** If false, the effect won't run immediately on creation. Defaults to true. */
+    onLoad?: boolean
+}): () => void;
+
+/**
+ * Create a reactive side-effect with explicit dependencies.
+ */
+export function effect(deps: any[], fn: () => void | (() => void), options?: {
+    /** If false, the effect won't run immediately on creation. Defaults to true. */
+    onLoad?: boolean
+}): () => void;
+
+/**
+ * Create a read-only computed signal derived from other signals.
+ */
+export function derive<T>(fn: () => T): () => T;
+
+/**
+ * Create a read/write view of a specific path within a signal object.
+ */
+export function pick<T = any>(root: RoundSignal<any>, path: string | string[]): RoundSignal<T>;
+
+/**
+ * Store API
+ */
+export interface RoundStore<T> {
+    /**
+     * Access a specific key from the store as a bindable signal.
+     */
+    use<K extends keyof T>(key: K): RoundSignal<T[K]>;
+
+    /**
+     * Update a specific key in the store.
+     */
+    set<K extends keyof T>(key: K, value: T[K]): T[K];
+
+    /**
+     * Batch update multiple keys in the store.
+     */
+    patch(obj: Partial<T>): void;
+
+    /**
+     * Get a snapshot of the current state.
+     */
+    snapshot(options?: {
+        /** If true, the returned values will be reactive signals. */
+        reactive?: boolean
+    }): T;
+
+    /**
+     * Enable persistence for the store.
+     */
+    persist(storageKey: string, options?: {
+        /** The storage implementation (defaults to localStorage). */
+        storage?: Storage;
+        /** Debounce time in milliseconds for writes. */
+        debounce?: number;
+        /** Array of keys to exclude from persistence. */
+        exclude?: string[];
+    }): RoundStore<T>;
+
+    /**
+     * Action methods defined during store creation.
+     */
+    actions: Record<string, Function>;
+}
+
+/**
+ * Create a shared global state store with actions and optional persistence.
+ */
+export function createStore<T, A extends Record<string, (state: T, ...args: any[]) => Partial<T> | void>>(
+    initialState: T,
+    actions?: A
+): RoundStore<T> & { [K in keyof A]: (...args: Parameters<A[K]> extends [any, ...infer P] ? P : never) => any };
+
+/**
+ * Router API
+ */
+export interface RouteProps {
+    /** The path to match. Must start with a forward slash. */
+    route?: string;
+    /** If true, only matches if the path is exactly the same. */
+    exact?: boolean;
+    /** Page title to set in the document header when active. */
+    title?: string;
+    /** Meta description to set in the document header when active. */
+    description?: string;
+    /** Advanced head configuration including links and meta tags. */
+    head?: any;
+    /** Fragment or elements to render when matched. */
+    children?: any;
+}
+
+/**
+ * Define a route that renders its children when the path matches.
+ */
+export function Route(props: RouteProps): any;
+
+/**
+ * An alias for Route, typically used for top-level pages.
+ */
+export function Page(props: RouteProps): any;
+
+export interface LinkProps {
+    /** The destination path. */
+    href: string;
+    /** Alias for href. */
+    to?: string;
+    /** Use SPA navigation (prevents full page reloads). Defaults to true. */
+    spa?: boolean;
+    /** Force a full page reload on navigation. */
+    reload?: boolean;
+    /** Custom click event handler. */
+    onClick?: (e: MouseEvent) => void;
+    /** Link content (text or elements). */
+    children?: any;
+    [key: string]: any;
+}
+
+/**
+ * A standard link component that performs SPA navigation.
+ */
+export function Link(props: LinkProps): any;
+
+/**
+ * Define a fallback component or content for when no routes match.
+ */
+export function NotFound(props: {
+    /** Optional component to render for the 404 state. */
+    component?: any;
+    /** Fallback content. ignored if 'component' is provided. */
+    children?: any
+}): any;
+
+/**
+ * Navigate to a different path programmatically.
+ */
+export function navigate(to: string, options?: {
+    /** If true, replaces the current history entry instead of pushing. */
+    replace?: boolean
+}): void;
+
+/**
+ * Hook to get a reactive function returning the current normalized pathname.
+ */
+export function usePathname(): () => string;
+
+/**
+ * Get the current normalized pathname.
+ */
+export function getPathname(): string;
+
+/**
+ * Hook to get a reactive function returning the current location object.
+ */
+export function useLocation(): () => { pathname: string; search: string; hash: string };
+
+/**
+ * Get the current location object (pathname, search, hash).
+ */
+export function getLocation(): { pathname: string; search: string; hash: string };
+
+/**
+ * Hook to get a reactive function returning whether the current path has no matches.
+ */
+export function useIsNotFound(): () => boolean;
+
+/**
+ * Get whether the current path is NOT matched by any defined route.
+ */
+export function getIsNotFound(): boolean;
+
+/**
+ * DOM & Context API
+ */
+
+/**
+ * Create a DOM element or instance a component.
+ */
+export function createElement(tag: any, props?: any, ...children: any[]): any;
+
+/**
+ * A grouping component that returns its children without a wrapper element.
+ */
+export function Fragment(props: { children?: any }): any;
+
+export interface Context<T> {
+    /** Internal identifier for the context. */
+    id: number;
+    /** Default value used when no Provider is found in the tree. */
+    defaultValue: T;
+    /** Component that provides a value to all its descendants. */
+    Provider: (props: { value: T; children?: any }) => any;
+}
+
+/**
+ * Create a new Context object for sharing state between components.
+ */
+export function createContext<T>(defaultValue?: T): Context<T>;
+
+/**
+ * Read the current value of a context from the component tree.
+ */
+export function readContext<T>(ctx: Context<T>): T;
+
+/**
+ * Returns a reactive function that reads the current context value.
+ */
+export function bindContext<T>(ctx: Context<T>): () => T;
+
+/**
+ * Async & Code Splitting
+ */
+
+/**
+ * Mark a component for lazy loading (code-splitting).
+ * Expects a function returning a dynamic import promise.
+ */
+export function lazy<T>(fn: () => Promise<{ default: T } | T>): any;
+
+declare module "*.round";
+
+export interface SuspenseProps {
+    /** Content to show while children (e.g. lazy components) are loading. */
+    fallback: any;
+    /** Content that might trigger a loading state. */
+    children?: any;
+}
+
+/**
+ * Component that boundaries async operations and renders a fallback while loading.
+ */
+export function Suspense(props: SuspenseProps): any;
+
+/**
+ * Head Management
+ */
+
+/**
+ * Define static head metadata (titles, meta tags, favicons, etc.).
+ */
+export function startHead(head: any): any;
+
+/**
+ * Markdown
+ */
+
+/**
+ * Component that renders Markdown content into HTML.
+ */
+export function Markdown(props: {
+    /** The markdown string or a function returning it. */
+    content: string | (() => string);
+    /** Remark/Rehype configuration options. */
+    options?: any
+}): any;

package/src/runtime/context.js

@@ -11,6 +11,12 @@ function popContext() {
     contextStack.pop();
 }
 
+/**
+ * Read the current value of a context from the tree.
+ * @template T
+ * @param {Context<T>} ctx The context object.
+ * @returns {T} The current context value.
+ */
 export function readContext(ctx) {
     for (let i = contextStack.length - 1; i >= 0; i--) {
         const layer = contextStack[i];
@@ -21,6 +27,12 @@ export function readContext(ctx) {
     return ctx.defaultValue;
 }
 
+/**
+ * Create a new Context object for sharing state between components.
+ * @template T
+ * @param {T} [defaultValue] The value used when no provider is found.
+ * @returns {Context<T>} The context object with a `Provider` component.
+ */
 export function createContext(defaultValue) {
     const ctx = {
         id: nextContextId++,

package/src/runtime/dom.js

@@ -29,6 +29,13 @@ function warnSignalDirectUsage(fn, kind) {
     }
 }
 
+/**
+ * Create a DOM element or instance a component.
+ * @param {string | Function} tag HTML tag name or Component function.
+ * @param {object} [props] Element attributes or component props.
+ * @param {...any} children Child nodes.
+ * @returns {Node} The resulting DOM node.
+ */
 export function createElement(tag, props = {}, ...children) {
     if (typeof tag === 'function') {
         const componentInstance = createComponentInstance();
@@ -388,6 +395,9 @@ function appendChild(parent, child) {
     }
 }
 
+/**
+ * A grouping component that returns its children without a wrapper element.
+ */
 export function Fragment(props) {
     return props.children;
 }

package/src/runtime/router.js

@@ -127,6 +127,11 @@ function mountAutoNotFound() {
     root.appendChild(view);
 }
 
+/**
+ * Navigate to a different path programmatically.
+ * @param {string} to The destination URL or path.
+ * @param {object} [options] Navigation options (e.g., { replace: true }).
+ */
 export function navigate(to, options = {}) {
     if (!hasWindow) return;
     ensureListener();
@@ -264,6 +269,15 @@ export function setNotFound(Component) {
     defaultNotFoundComponent = Component;
 }
 
+/**
+ * Define a route that renders its children when the path matches.
+ * @param {object} props Route properties.
+ * @param {string} [props.route='/'] The path to match.
+ * @param {boolean} [props.exact] Whether to use exact matching.
+ * @param {string} [props.title] Page title to set when active.
+ * @param {string} [props.description] Meta description to set when active.
+ * @param {any} [props.children] Content to render.
+ */
 export function Route(props = {}) {
     ensureListener();
 
@@ -319,6 +333,10 @@ export function Route(props = {}) {
     });
 }
 
+/**
+ * An alias for Route, typically used for top-level pages.
+ * @param {object} props Page properties (same as Route).
+ */
 export function Page(props = {}) {
     ensureListener();
 
@@ -371,6 +389,9 @@ export function Page(props = {}) {
     });
 }
 
+/**
+ * Define a fallback component or content for when no routes match.
+ */
 export function NotFound(props = {}) {
     ensureListener();
 
@@ -402,6 +423,13 @@ export function NotFound(props = {}) {
     });
 }
 
+/**
+ * A standard link component that performs SPA navigation.
+ * @param {object} props Link properties.
+ * @param {string} [props.href] The destination path.
+ * @param {boolean} [props.spa=true] Use SPA navigation (prevents reload).
+ * @param {any} [props.children] Link content.
+ */
 export function Link(props = {}) {
     ensureListener();
 

package/src/runtime/signals.js

@@ -12,6 +12,13 @@ function subscribe(running, subscriptions) {
     running.dependencies.add(subscriptions);
 }
 
+/**
+ * Run a function without tracking any signals it reads.
+ * Any signals accessed inside `fn` will not become dependencies of the current effect.
+ * @template T
+ * @param {() => T} fn The function to execute.
+ * @returns {T} The return value of `fn`.
+ */
 export function untrack(fn) {
     context.push(null);
     try {
@@ -21,6 +28,13 @@ export function untrack(fn) {
     }
 }
 
+/**
+ * Create a reactive side-effect that runs whenever its signal dependencies change.
+ * @param {(() => any) | any[]} arg1 Either the callback function or an array of explicit dependencies.
+ * @param {(() => any)} [arg2] The callback function if the first argument was explicit dependencies.
+ * @param {object} [arg3] Optional configuration (e.g., { onLoad: false }).
+ * @returns {() => void} A function to stop and cleanup the effect.
+ */
 export function effect(arg1, arg2, arg3) {
     let callback;
     let explicitDeps = null;
@@ -241,6 +255,12 @@ function attachHelpers(s) {
     return s;
 }
 
+/**
+ * Create a reactive signal.
+ * @template T
+ * @param {T} [initialValue] The starting value.
+ * @returns {RoundSignal<T>} A signal function that reads/writes the value.
+ */
 export function signal(initialValue) {
     let value = initialValue;
     const subscriptions = new Set();
@@ -285,6 +305,12 @@ export function signal(initialValue) {
     return attachHelpers(signal);
 }
 
+/**
+ * Create a bindable signal intended for two-way DOM bindings.
+ * @template T
+ * @param {T} [initialValue] The starting value.
+ * @returns {RoundSignal<T>} A signal function marked as bindable.
+ */
 export function bindable(initialValue) {
     const s = signal(initialValue);
     try {
@@ -345,6 +371,12 @@ function parsePath(path) {
     return [String(path)];
 }
 
+/**
+ * Create a read/write view of a specific path within a signal object.
+ * @param {RoundSignal<any>} root The source signal.
+ * @param {string | string[]} path The property path (e.g., 'user.profile.name' or ['user', 'profile', 'name']).
+ * @returns {RoundSignal<any>} A signal-like view of the path.
+ */
 export function pick(root, path) {
     if (!isSignalLike(root)) {
         throw new Error('[round] pick(root, path) expects root to be a signal (use bindable.object(...) or signal({...})).');
@@ -499,6 +531,12 @@ bindable.object = function (initialObject = {}) {
     return createBindableObjectProxy(root, []);
 };
 
+/**
+ * Create a read-only computed signal derived from other signals.
+ * @template T
+ * @param {() => T} fn A function that computes the value.
+ * @returns {(() => T)} A function that returns the derived value.
+ */
 export function derive(fn) {
     const derived = signal();
 

package/src/runtime/store.js

@@ -5,6 +5,13 @@ function hasWindow() {
     return typeof window !== 'undefined' && typeof document !== 'undefined';
 }
 
+/**
+ * Create a shared global state store with actions and optional persistence.
+ * @template T
+ * @param {T} [initialState={}] Initial state object.
+ * @param {Record<string, (state: T, ...args: any[]) => any>} [actions] Action reducers.
+ * @returns {RoundStore<T>} The store object.
+ */
 export function createStore(initialState = {}, actions = null) {
     const state = (initialState && typeof initialState === 'object') ? initialState : {};
     const signals = Object.create(null);

package/vite.config.build.js

@@ -33,4 +33,16 @@ export default defineConfig({
             }
         },
     },
+    plugins: [
+        {
+            name: 'copy-dts',
+            closeBundle() {
+                const src = path.resolve(__dirname, 'src/index.d.ts');
+                const dest = path.resolve(__dirname, 'dist/index.d.ts');
+                if (fs.existsSync(src)) {
+                    fs.copyFileSync(src, dest);
+                }
+            }
+        }
+    ]
 });