round-core 0.0.4 → 0.0.6

package/src/index.d.ts

@@ -0,0 +1,326 @@
+/**
+ * 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;
+}
+
+/**
+ * Creates a reactive signal.
+ */
+export function signal<T>(initialValue?: T): RoundSignal<T>;
+
+/**
+ * Creates a bindable signal intended for two-way DOM bindings.
+ */
+export function bindable<T>(initialValue?: T): RoundSignal<T>;
+
+/**
+ * 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;
+
+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++,
@@ -29,18 +41,29 @@ export function createContext(defaultValue) {
     };
 
     function Provider(props = {}) {
-        const value = props.value;
-        const child = Array.isArray(props.children) ? props.children[0] : props.children;
-        const childFn = typeof child === 'function' ? child : () => child;
+        const children = props.children;
 
-        return createElement('span', { style: { display: 'contents' } }, () => {
-            pushContext({ [ctx.id]: value });
-            try {
-                return childFn();
-            } finally {
-                popContext();
-            }
-        });
+        // Push context now so that any createElement/appendChild called 
+        // during the instantiation of this Provider branch picks it up immediately.
+        pushContext({ [ctx.id]: props.value });
+        try {
+            // We use a span to handle reactive value updates and dynamic children.
+            return createElement('span', { style: { display: 'contents' } }, () => {
+                // Read current value (reactive if it's a signal)
+                const val = (typeof props.value === 'function' && props.value.peek) ? props.value() : props.value;
+
+                // Push it during the effect run too! This ensures that anything returned 
+                // from this callback (which might trigger more appendChild calls) sees the context.
+                pushContext({ [ctx.id]: val });
+                try {
+                    return children;
+                } finally {
+                    popContext();
+                }
+            });
+        } finally {
+            popContext();
+        }
     }
 
     ctx.Provider = Provider;

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

@@ -1,5 +1,6 @@
 import { signal, effect } from './signals.js';
 import { createElement } from './dom.js';
+import { createContext, readContext } from './context.js';
 
 const hasWindow = typeof window !== 'undefined' && typeof document !== 'undefined';
 
@@ -20,6 +21,8 @@ let defaultNotFoundComponent = null;
 let autoNotFoundMounted = false;
 let userProvidedNotFound = false;
 
+const RoutingContext = createContext('');
+
 function ensureListener() {
     if (!hasWindow || listenerInitialized) return;
     listenerInitialized = true;
@@ -72,6 +75,7 @@ export function useRouteReady() {
 
 export function getIsNotFound() {
     const pathname = normalizePathname(currentPath());
+    if (pathname === '/') return false;
     if (!(Boolean(pathEvalReady()) && lastPathEvaluated === pathname)) return false;
     return !Boolean(pathHasMatch());
 }
@@ -79,6 +83,7 @@ export function getIsNotFound() {
 export function useIsNotFound() {
     return () => {
         const pathname = normalizePathname(currentPath());
+        if (pathname === '/') return false;
         if (!(Boolean(pathEvalReady()) && lastPathEvaluated === pathname)) return false;
         return !Boolean(pathHasMatch());
     };
@@ -104,6 +109,10 @@ function mountAutoNotFound() {
         if (lastPathEvaluated !== pathname) return null;
         if (hasMatch) return null;
 
+        // Skip absolute 404 overlay for the root path if no match found,
+        // allowing the base app to render its non-routed content.
+        if (pathname === '/') return null;
+
         const Comp = defaultNotFoundComponent;
         if (typeof Comp === 'function') {
             return createElement(Comp, { pathname });
@@ -118,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();
@@ -229,10 +243,12 @@ function normalizeTo(to) {
     return normalizePathname(path) + suffix;
 }
 
-function matchRoute(route, pathname) {
+function matchRoute(route, pathname, exact = true) {
     const r = normalizePathname(route);
     const p = normalizePathname(pathname);
-    return r === p;
+    if (exact) return r === p;
+    // Prefix match: either exactly the same, or p starts with r plus a slash
+    return p === r || p.startsWith(r.endsWith('/') ? r : r + '/');
 }
 
 function beginPathEvaluation(pathname) {
@@ -253,17 +269,54 @@ 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();
 
     return createElement('span', { style: { display: 'contents' } }, () => {
+        const parentPath = readContext(RoutingContext) || '';
         const pathname = normalizePathname(currentPath());
         beginPathEvaluation(pathname);
-        const route = props.route ?? '/';
-        if (!matchRoute(route, pathname)) return null;
 
-        hasMatchForPath = true;
-        pathHasMatch(true);
+        const routeProp = props.route ?? '/';
+        if (typeof routeProp === 'string' && !routeProp.startsWith('/')) {
+            throw new Error(`Invalid route: "${routeProp}". All routes must start with a forward slash "/". (Nested under: "${parentPath || 'root'}")`);
+        }
+
+        let fullRoute = '';
+        if (parentPath && parentPath !== '/') {
+            const cleanParent = parentPath.endsWith('/') ? parentPath.slice(0, -1) : parentPath;
+            const cleanChild = routeProp.startsWith('/') ? routeProp : '/' + routeProp;
+
+            if (cleanChild.startsWith(cleanParent + '/') || cleanChild === cleanParent) {
+                fullRoute = normalizePathname(cleanChild);
+            } else {
+                fullRoute = normalizePathname(cleanParent + cleanChild);
+            }
+        } else {
+            fullRoute = normalizePathname(routeProp);
+        }
+
+        const isRoot = fullRoute === '/';
+        const exact = props.exact !== undefined ? Boolean(props.exact) : isRoot;
+
+        // For nested routing, we match as a prefix so parents stay rendered while children are active
+        if (!matchRoute(fullRoute, pathname, exact)) return null;
+
+        // If it's an exact match of the FULL segments, mark as matched for 404 purposes
+        if (matchRoute(fullRoute, pathname, true)) {
+            hasMatchForPath = true;
+            pathHasMatch(true);
+        }
+
         const mergedHead = (props.head && typeof props.head === 'object') ? props.head : {};
         const meta = props.description
             ? ([{ name: 'description', content: String(props.description) }].concat(mergedHead.meta ?? props.meta ?? []))
@@ -274,21 +327,53 @@ export function Route(props = {}) {
         const favicon = mergedHead.favicon ?? props.favicon;
 
         applyHead({ title, meta, links, icon, favicon });
-        return props.children;
+
+        // Provide the current full path to nested routes
+        return createElement(RoutingContext.Provider, { value: fullRoute }, props.children);
     });
 }
 
+/**
+ * An alias for Route, typically used for top-level pages.
+ * @param {object} props Page properties (same as Route).
+ */
 export function Page(props = {}) {
     ensureListener();
 
     return createElement('span', { style: { display: 'contents' } }, () => {
+        const parentPath = readContext(RoutingContext) || '';
         const pathname = normalizePathname(currentPath());
         beginPathEvaluation(pathname);
-        const route = props.route ?? '/';
-        if (!matchRoute(route, pathname)) return null;
 
-        hasMatchForPath = true;
-        pathHasMatch(true);
+        const routeProp = props.route ?? '/';
+        if (typeof routeProp === 'string' && !routeProp.startsWith('/')) {
+            throw new Error(`Invalid route: "${routeProp}". All routes must start with a forward slash "/". (Nested under: "${parentPath || 'root'}")`);
+        }
+
+        let fullRoute = '';
+        if (parentPath && parentPath !== '/') {
+            const cleanParent = parentPath.endsWith('/') ? parentPath.slice(0, -1) : parentPath;
+            const cleanChild = routeProp.startsWith('/') ? routeProp : '/' + routeProp;
+
+            if (cleanChild.startsWith(cleanParent + '/') || cleanChild === cleanParent) {
+                fullRoute = normalizePathname(cleanChild);
+            } else {
+                fullRoute = normalizePathname(cleanParent + cleanChild);
+            }
+        } else {
+            fullRoute = normalizePathname(routeProp);
+        }
+
+        const isRoot = fullRoute === '/';
+        const exact = props.exact !== undefined ? Boolean(props.exact) : isRoot;
+
+        if (!matchRoute(fullRoute, pathname, exact)) return null;
+
+        if (matchRoute(fullRoute, pathname, true)) {
+            hasMatchForPath = true;
+            pathHasMatch(true);
+        }
+
         const mergedHead = (props.head && typeof props.head === 'object') ? props.head : {};
         const meta = props.description
             ? ([{ name: 'description', content: String(props.description) }].concat(mergedHead.meta ?? props.meta ?? []))
@@ -299,10 +384,14 @@ export function Page(props = {}) {
         const favicon = mergedHead.favicon ?? props.favicon;
 
         applyHead({ title, meta, links, icon, favicon });
-        return props.children;
+
+        return createElement(RoutingContext.Provider, { value: fullRoute }, props.children);
     });
 }
 
+/**
+ * Define a fallback component or content for when no routes match.
+ */
 export function NotFound(props = {}) {
     ensureListener();
 
@@ -318,6 +407,7 @@ export function NotFound(props = {}) {
         if (lastPathEvaluated !== pathname) return null;
 
         if (hasMatch) return null;
+        if (pathname === '/') return null;
 
         const Comp = props.component ?? defaultNotFoundComponent;
         if (typeof Comp === 'function') {
@@ -333,14 +423,21 @@ 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();
 
     const rawHref = props.href ?? props.to ?? '#';
     const href = spaNormalizeHref(rawHref);
 
-     const spa = props.spa !== undefined ? Boolean(props.spa) : true;
-     const reload = Boolean(props.reload);
+    const spa = props.spa !== undefined ? Boolean(props.spa) : true;
+    const reload = Boolean(props.reload);
 
     const onClick = (e) => {
         if (typeof props.onClick === 'function') props.onClick(e);