round-core 0.1.0 → 0.1.2

package/README.md

@@ -20,7 +20,7 @@ Extension for [VSCode](https://marketplace.visualstudio.com/items?itemName=ZtaMD
 
 --- 
 
-Instead of a Virtual DOM diff, Round updates the UI by subscribing DOM updates directly to reactive primitives (**signals**) and **bindables**. This keeps rendering predictable, small, and fast for interactive apps.
+Instead of a Virtual DOM diff, Round updates the UI by subscribing DOM updates directly to reactive primitives **signals** and **bindables**. This keeps rendering predictable, small, and fast for interactive apps.
 
 The `round-core` package is the **foundation of RoundJS**.
 
@@ -163,6 +163,23 @@ effect(() => {
 name('Grace');
 ```
 
+### `untrack(fn)`
+
+Run a function without tracking any signals it reads.
+
+```javascript
+import { signal, untrack, effect } from 'round-core';
+
+const count = signal(0);
+effect(() => {
+    console.log('Count is:', count());
+    untrack(() => {
+        // This read won't trigger the effect if it changes elsewhere
+        console.log('Static value:', count());
+    });
+});
+```
+
 ### `bindable(initialValue)`
 
 `bindable()` creates a signal intended for **two-way DOM bindings**.
@@ -206,14 +223,24 @@ export function TodoList() {
     
     return (
         <div>
-            {todos().map(todo => <div>{todo.text}</div>)}
+            {for(todo in todos()){
+                <div>{todo.text}</div>
+            }}
             <button onClick={() => store.addTodo('Buy Milk')}>Add</button>
         </div>
     );
 }
 
 // 3. Persistence (Optional)
-store.persist('my-app-store'); 
+store.persist('my-app-store', { 
+    debounce: 100, // ms
+    exclude: ['someSecretKey'] 
+}); 
+
+// 4. Advanced Methods
+store.patch({ filter: 'completed' }); // Update multiple keys at once
+const data = store.snapshot({ reactive: false }); // Get static JSON of state
+store.set('todos', []); // Direct set
 ```
 
 ### `bindable.object(initialObject)` and deep binding
@@ -241,6 +268,38 @@ export function Profile() {
 }
 ```
 
+## Lifecycle Hooks
+
+Round provides hooks to tap into the lifecycle of components. These must be called during the synchronous execution of your component function.
+
+### `onMount(fn)`
+Runs after the component is first created and its elements are added to the DOM. If `fn` returns a function, it's used as a cleanup (equivalent to `onUnmount`).
+
+### `onUnmount(fn)`
+Runs when the component's elements are removed from the DOM.
+
+### `onUpdate(fn)`
+Runs whenever any signal read during the component's *initial* render is updated.
+
+### `onCleanup(fn)`
+Alias for `onUnmount`.
+
+```jsx
+import { onMount, onUnmount } from 'round-core';
+
+export function MyComponent() {
+    onMount(() => {
+        console.log('Mounted!');
+        const timer = setInterval(() => {}, 1000);
+        return () => clearInterval(timer); // Cleanup
+    });
+
+    onUnmount(() => console.log('Goodbye!'));
+
+    return <div>Hello</div>;
+}
+```
+
 ### `.validate(validator, options)`
 
 Attach validation to a signal/bindable.
@@ -398,6 +457,22 @@ Round aims to provide strong developer feedback:
 - Runtime error reporting with safe boundaries.
 - `ErrorBoundary` to catch render-time errors and show a fallback.
 
+### `ErrorBoundary`
+
+Wrap components to prevent the whole app from crashing if a child fails to render.
+
+```jsx
+import { ErrorBoundary } from 'round-core';
+
+function DangerousComponent() {
+    throw new Error('Boom!');
+}
+
+<ErrorBoundary fallback={(err) => <div className="error">Something went wrong: {err.message}</div>}>
+    <DangerousComponent />
+</ErrorBoundary>
+```
+
 ## CLI
 
 The CLI is intended for day-to-day development:

package/dist/cli.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 import path from "node:path";
 import fs from "node:fs";
 import process from "node:process";
@@ -8,6 +10,7 @@ import RoundPlugin from "./vite-plugin.js";
 function onSignal() {
   process.exit(0);
 }
+__name(onSignal, "onSignal");
 process.on("SIGINT", onSignal);
 process.on("SIGTERM", onSignal);
 process.on("exit", () => {
@@ -23,9 +26,11 @@ function cleanupTemporaryFiles() {
   }
   temporaryFiles.clear();
 }
+__name(cleanupTemporaryFiles, "cleanupTemporaryFiles");
 function normalizePath(p) {
   return p.replaceAll("\\", "/");
 }
+__name(normalizePath, "normalizePath");
 const colors = {
   reset: "\x1B[0m",
   dim: "\x1B[2m",
@@ -41,7 +46,11 @@ const colors = {
 function c(text, color) {
   return `${colors[color] ?? ""}${text}${colors.reset}`;
 }
+__name(c, "c");
 class CliError extends Error {
+  static {
+    __name(this, "CliError");
+  }
   constructor(message, options = {}) {
     super(message);
     this.name = "CliError";
@@ -55,6 +64,7 @@ function printError(message) {
   process.stderr.write(`${c("Error:", "red")} ${msg}
 `);
 }
+__name(printError, "printError");
 function getRoundVersion() {
   try {
     const here = path.dirname(fileURLToPath(import.meta.url));
@@ -66,6 +76,7 @@ function getRoundVersion() {
     return null;
   }
 }
+__name(getRoundVersion, "getRoundVersion");
 function banner(title) {
   const v = getRoundVersion();
   const name = c("ROUND", "cyan");
@@ -76,12 +87,13 @@ function banner(title) {
   process.stdout.write(`
 `);
 }
+__name(banner, "banner");
 function createViteLogger() {
   let hasError = false;
-  const noop = () => {
-  };
+  const noop = /* @__PURE__ */ __name(() => {
+  }, "noop");
   return {
-    hasErrorLogged: () => hasError,
+    hasErrorLogged: /* @__PURE__ */ __name(() => hasError, "hasErrorLogged"),
     info(msg) {
       const s = String(msg ?? "");
       if (!s) return;
@@ -114,6 +126,7 @@ function createViteLogger() {
     }
   };
 }
+__name(createViteLogger, "createViteLogger");
 function printUrls(resolvedUrls, base = "/", ms = null) {
   const local = resolvedUrls?.local?.[0];
   const network = resolvedUrls?.network?.[0];
@@ -130,11 +143,13 @@ function printUrls(resolvedUrls, base = "/", ms = null) {
   process.stdout.write(`
 `);
 }
+__name(printUrls, "printUrls");
 function resolveFrom(baseDir, p) {
   if (!p) return null;
   if (path.isAbsolute(p)) return p;
   return path.resolve(baseDir, p);
 }
+__name(resolveFrom, "resolveFrom");
 function parseArgs(argv) {
   const args = { _: [] };
   for (let i = 0; i < argv.length; i++) {
@@ -166,6 +181,7 @@ function parseArgs(argv) {
   }
   return args;
 }
+__name(parseArgs, "parseArgs");
 function printHelp() {
   const header = `${c("round", "cyan")} ${c("(CLI)", "gray")}`;
   process.stdout.write(
@@ -186,15 +202,18 @@ function printHelp() {
     ].join("\n")
   );
 }
+__name(printHelp, "printHelp");
 function ensureDir(dir) {
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 }
+__name(ensureDir, "ensureDir");
 function writeFileIfMissing(filePath, content) {
   if (fs.existsSync(filePath)) {
     throw new Error(`File already exists: ${filePath}`);
   }
   fs.writeFileSync(filePath, content, "utf8");
 }
+__name(writeFileIfMissing, "writeFileIfMissing");
 async function runInit({ name }) {
   if (!name || typeof name !== "string") {
     throw new CliError(
@@ -327,15 +346,18 @@ ${c("Project created:", "green")} ${projectDir}
 
 `);
 }
+__name(runInit, "runInit");
 function loadRoundConfig(configPathAbs) {
   const raw = fs.readFileSync(configPathAbs, "utf8");
   const json = JSON.parse(raw);
   return json && typeof json === "object" ? json : {};
 }
+__name(loadRoundConfig, "loadRoundConfig");
 function coerceNumber(v, fallback) {
   const n = Number(v);
   return Number.isFinite(n) ? n : fallback;
 }
+__name(coerceNumber, "coerceNumber");
 function generateIndexHtml(config) {
   const name = config?.name ?? "Round";
   const rawEntry = config?.entry ?? "./src/app.round";
@@ -362,6 +384,7 @@ function generateIndexHtml(config) {
     "</html>"
   ].join("\n");
 }
+__name(generateIndexHtml, "generateIndexHtml");
 function writeTemporaryIndex(rootDir, config) {
   const indexPath = path.resolve(rootDir, "index.html");
   if (fs.existsSync(indexPath)) return false;
@@ -370,6 +393,7 @@ function writeTemporaryIndex(rootDir, config) {
   temporaryFiles.add(indexPath);
   return true;
 }
+__name(writeTemporaryIndex, "writeTemporaryIndex");
 async function runDev({ rootDir, configPathAbs, config }) {
   const startedAt = Date.now();
   const configDir = path.dirname(configPathAbs);
@@ -381,7 +405,7 @@ async function runDev({ rootDir, configPathAbs, config }) {
   let viteServer = null;
   let restarting = false;
   let restartTimer = null;
-  const startServer = async (nextConfig, { showBanner, showReady } = { showBanner: true, showReady: true }) => {
+  const startServer = /* @__PURE__ */ __name(async (nextConfig, { showBanner, showReady } = { showBanner: true, showReady: true }) => {
     const cfgDir = path.dirname(configPathAbs);
     const entryAbs2 = nextConfig?.entry ? resolveFrom(cfgDir, nextConfig.entry) : null;
     if (!entryAbs2 || !fs.existsSync(entryAbs2)) {
@@ -424,7 +448,7 @@ async function runDev({ rootDir, configPathAbs, config }) {
       printUrls(server.resolvedUrls, base2, ms);
     }
     return server;
-  };
+  }, "startServer");
   viteServer = await startServer(config, { showBanner: true, showReady: true });
   if (typeof fs.watch === "function") {
     try {
@@ -451,6 +475,7 @@ ${c("[round]", "cyan")} ${c("config changed", "gray")} ${c("restarting dev serve
     }
   }
 }
+__name(runDev, "runDev");
 async function runBuild({ rootDir, configPathAbs, config }) {
   const startedAt = Date.now();
   const configDir = path.dirname(configPathAbs);
@@ -491,6 +516,7 @@ async function runBuild({ rootDir, configPathAbs, config }) {
 
 `);
 }
+__name(runBuild, "runBuild");
 async function runPreview({ rootDir, configPathAbs, config }) {
   const configDir = path.dirname(configPathAbs);
   const outDir = config?.output ? resolveFrom(configDir, config.output) : resolveFrom(rootDir, "./dist");
@@ -530,6 +556,7 @@ async function runPreview({ rootDir, configPathAbs, config }) {
   });
   printUrls(server.resolvedUrls, base);
 }
+__name(runPreview, "runPreview");
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   const cmd = args._[0];
@@ -567,6 +594,7 @@ ${String(e?.message ?? e)}`, { code: 1 });
     await runPreview({ rootDir, configPathAbs, config });
   }
 }
+__name(main, "main");
 main().catch((e) => {
   if (e && e.name === "CliError") {
     printError(e.message);

package/dist/index.d.ts

@@ -80,7 +80,8 @@ export const bindable: Bindable;
 export function untrack<T>(fn: () => T): T;
 
 /**
- * Create a reactive side-effect that runs whenever its signal dependencies change.
+ * Creates a reactive side-effect that runs whenever its signal dependencies change.
+ * Returns a function to manually stop the effect.
  */
 export function effect(fn: () => void | (() => void), options?: {
     /** If false, the effect won't run immediately on creation. Defaults to true. */
@@ -88,7 +89,7 @@ export function effect(fn: () => void | (() => void), options?: {
 }): () => void;
 
 /**
- * Create a reactive side-effect with explicit dependencies.
+ * Creates 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. */
@@ -96,15 +97,40 @@ export function effect(deps: any[], fn: () => void | (() => void), options?: {
 }): () => void;
 
 /**
- * Create a read-only computed signal derived from other signals.
+ * Creates 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.
+ * Creates 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>;
 
+/**
+ * Lifecycle Hooks
+ */
+
+/**
+ * Runs a function when the component is mounted to the DOM.
+ * If the function returns another function, it will be used as an unmount cleanup.
+ */
+export function onMount(fn: () => void | (() => void)): void;
+
+/**
+ * Runs a function when the component is removed from the DOM.
+ */
+export function onUnmount(fn: () => void): void;
+
+/**
+ * Alias for onUnmount. Runs cleanup logic when the component is destroyed.
+ */
+export function onCleanup(fn: () => void): void;
+
+/**
+ * Runs a function after the component updates its DOM nodes.
+ */
+export function onUpdate(fn: () => void): void;
+
 /**
  * Store API
  */
@@ -136,7 +162,7 @@ export interface RoundStore<T> {
      * Enable persistence for the store.
      */
     persist(storageKey: string, options?: {
-        /** The storage implementation (defaults to localStorage). */
+        /** The storage provider (defaults to localStorage). */
         storage?: Storage;
         /** Debounce time in milliseconds for writes. */
         debounce?: number;
@@ -172,12 +198,12 @@ export interface RouteProps {
     description?: string;
     /** Advanced head configuration including links and meta tags. */
     head?: any;
-    /** Fragment or elements to render when matched. */
+    /** Component or elements to render when matched. */
     children?: any;
 }
 
 /**
- * Define a route that renders its children when the path matches.
+ * Defines a route that renders its children when the path matches.
  */
 export function Route(props: RouteProps): any;
 
@@ -203,55 +229,55 @@ export interface LinkProps {
 }
 
 /**
- * A standard link component that performs SPA navigation.
+ * A link component that performs SPA navigation.
  */
 export function Link(props: LinkProps): any;
 
 /**
- * Define a fallback component or content for when no routes match.
+ * Defines a fallback component for when no routes match.
  */
 export function NotFound(props: {
-    /** Optional component to render for the 404 state. */
+    /** Component to render for the 404 state. */
     component?: any;
-    /** Fallback content. ignored if 'component' is provided. */
+    /** Fallback content. Ignored if 'component' is provided. */
     children?: any
 }): any;
 
 /**
- * Navigate to a different path programmatically.
+ * Navigates to a different path programmatically.
  */
 export function navigate(to: string, options?: {
-    /** If true, replaces the current history entry instead of pushing. */
+    /** If true, replaces the current history entry. */
     replace?: boolean
 }): void;
 
 /**
- * Hook to get a reactive function returning the current normalized pathname.
+ * Returns a reactive function that returns the current normalized pathname.
  */
 export function usePathname(): () => string;
 
 /**
- * Get the current normalized pathname.
+ * Gets the current normalized pathname.
  */
 export function getPathname(): string;
 
 /**
- * Hook to get a reactive function returning the current location object.
+ * Returns a reactive function that returns the current location object.
  */
 export function useLocation(): () => { pathname: string; search: string; hash: string };
 
 /**
- * Get the current location object (pathname, search, hash).
+ * Gets 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.
+ * Returns a reactive function that returns whether the current path has no matches.
  */
 export function useIsNotFound(): () => boolean;
 
 /**
- * Get whether the current path is NOT matched by any defined route.
+ * Gets whether the current path is NOT matched by any defined route.
  */
 export function getIsNotFound(): boolean;
 
@@ -260,7 +286,7 @@ export function getIsNotFound(): boolean;
  */
 
 /**
- * Create a DOM element or instance a component.
+ * Creates a DOM element or instances a component.
  */
 export function createElement(tag: any, props?: any, ...children: any[]): any;
 
@@ -272,19 +298,19 @@ 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. */
+    /** Default value if no Provider is found. */
     defaultValue: T;
-    /** Component that provides a value to all its descendants. */
+    /** Component that provides a value to descendants. */
     Provider: (props: { value: T; children?: any }) => any;
 }
 
 /**
- * Create a new Context object for sharing state between components.
+ * Creates a new Context for sharing state between components.
  */
 export function createContext<T>(defaultValue?: T): Context<T>;
 
 /**
- * Read the current value of a context from the component tree.
+ * Reads the current context value from the component tree.
  */
 export function readContext<T>(ctx: Context<T>): T;
 
@@ -293,27 +319,46 @@ export function readContext<T>(ctx: Context<T>): T;
  */
 export function bindContext<T>(ctx: Context<T>): () => T;
 
+/**
+ * Error Handling
+ */
+
+export interface ErrorBoundaryProps {
+    /** Content to render if an error occurs. Can be a signal or function. */
+    fallback?: any | ((props: { error: any }) => any);
+    /** Optional identifier for the boundary. */
+    name?: string;
+    /** Optional key that, when changed, resets the boundary error state. */
+    resetKey?: any;
+    /** Content that might throw an error. */
+    children?: any;
+}
+
+/**
+ * Component that catches runtime errors in its child tree and displays a fallback UI.
+ */
+export function ErrorBoundary(props: ErrorBoundaryProps): any;
+
 /**
  * Async & Code Splitting
  */
 
 /**
- * Mark a component for lazy loading (code-splitting).
- * Expects a function returning a dynamic import promise.
+ * Marks a component for lazy loading (code-splitting).
  */
 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. */
+    /** Content to show while children are loading. */
     fallback: any;
     /** Content that might trigger a loading state. */
     children?: any;
 }
 
 /**
- * Component that boundaries async operations and renders a fallback while loading.
+ * Component that renders a fallback UI while its children are loading.
  */
 export function Suspense(props: SuspenseProps): any;
 
@@ -322,20 +367,6 @@ export function Suspense(props: SuspenseProps): any;
  */
 
 /**
- * Define static head metadata (titles, meta tags, favicons, etc.).
- */
-export function startHead(head: any): any;
-
-/**
- * Markdown
- */
-
-/**
- * Component that renders Markdown content into HTML.
+ * Defines static head metadata (titles, meta tags, etc.).
  */
-export function Markdown(props: {
-    /** The markdown string or a function returning it. */
-    content: string | (() => string);
-    /** Remark/Rehype configuration options. */
-    options?: any
-}): any;
+export function startHead(head: any): any;