@faber1999/axon.js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faber Grajales Hincapié
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,292 @@
+# axon.js
+
+A fine-grained reactive frontend framework built from scratch.
+JSX syntax · Signals reactivity · Router · Store · No Virtual DOM · Zero dependencies.
+
+```tsx
+import { signal, createApp } from 'axon.js'
+
+function Counter() {
+  const [count, setCount] = signal(0)
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={() => setCount((c) => c + 1)}>+1</button>
+    </div>
+  )
+}
+
+createApp(Counter).mount('#app')
+```
+
+Components run **once**. Only the exact DOM nodes that depend on a signal update — no diffing, no re-renders.
+
+---
+
+## Installation
+
+```bash
+npm install axon.js
+```
+
+### Vite setup
+
+**`vite.config.ts`**
+
+```ts
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  esbuild: {
+    jsxFactory: 'h',
+    jsxFragment: 'Fragment',
+    jsxInject: `import { h, Fragment } from 'axon.js/jsx'`
+  }
+})
+```
+
+**`tsconfig.json`**
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "preserve",
+    "jsxFactory": "h",
+    "jsxFragmentFactory": "Fragment",
+    "strict": true
+  }
+}
+```
+
+That's it. No plugins, no Babel, no extra config.
+
+---
+
+## Core API
+
+### Reactivity
+
+```ts
+import { signal, effect, computed, batch, untrack } from 'axon.js'
+
+// signal — reactive value
+const [count, setCount] = signal(0)
+count() // read
+setCount(1) // write
+setCount((c) => c + 1) // update with function
+
+// effect — runs immediately and re-runs when dependencies change
+effect(() => {
+  console.log('count is', count())
+})
+
+// computed — derived reactive value
+const double = computed(() => count() * 2)
+double() // 0, 2, 4...
+
+// batch — group multiple updates into one notification
+batch(() => {
+  setFirstName('John')
+  setLastName('Doe')
+})
+
+// untrack — read a signal without subscribing
+effect(() => {
+  const a = count() // subscribes
+  const b = untrack(() => x()) // does NOT subscribe
+})
+```
+
+### JSX & Components
+
+```tsx
+import { onMount, onCleanup, createApp } from 'axon.js'
+
+function Timer() {
+  const [seconds, setSeconds] = signal(0)
+
+  onMount(() => {
+    const id = setInterval(() => setSeconds((s) => s + 1), 1000)
+    onCleanup(() => clearInterval(id))
+  })
+
+  return <p>Elapsed: {seconds}s</p>
+}
+
+createApp(Timer).mount('#app')
+```
+
+### Control flow
+
+```tsx
+import { Show, For, Dynamic, Portal } from 'axon.js'
+
+// Conditional rendering
+<Show when={isLoggedIn} fallback={<Login />}>
+  <Dashboard />
+</Show>
+
+// List rendering
+<For each={todos}>
+  {(todo, index) => <li>{todo.text}</li>}
+</For>
+
+// Dynamic component
+<Dynamic component={currentView} />
+
+// Render outside the tree (e.g. modals)
+<Portal mount={document.body}>
+  <Modal />
+</Portal>
+```
+
+### Router
+
+```tsx
+import { createRouter, RouterView, Link, useRouter, useParams } from 'axon.js'
+
+createRouter(
+  [
+    { path: '/', component: Home },
+    { path: '/about', component: About },
+
+    // Route groups — shared layout and/or guard
+    {
+      layout: DashboardLayout,
+      guard: () => isLoggedIn() || '/login',
+      fallbackPath: '/login',
+      children: [
+        { path: '/dashboard', component: Dashboard },
+        { path: '/settings', component: Settings }
+      ]
+    },
+
+    // Catch-all 404
+    { path: '*', component: NotFound }
+  ],
+  { viewTransitions: true }
+) // optional animated transitions
+
+function App() {
+  return (
+    <div>
+      <nav>
+        <Link href="/">Home</Link>
+        <Link href="/about" activeClass="active">
+          About
+        </Link>
+      </nav>
+      <main>
+        <RouterView />
+      </main>
+    </div>
+  )
+}
+```
+
+**Guard return values:**
+
+| Returns   | Behavior                                                  |
+| --------- | --------------------------------------------------------- |
+| `true`    | Allow access, render the component                        |
+| `false`   | Navigate back to the previous route, or to `fallbackPath` |
+| `"/path"` | Redirect to that path                                     |
+
+**Router hooks:**
+
+```ts
+const router = useRouter() // full router instance
+const params = useParams() // { id: '42' }
+const navigate = useNavigate() // navigate('/path')
+```
+
+### Store
+
+```ts
+import { createStore, select } from 'axon.js'
+
+interface AppState {
+  theme: 'dark' | 'light'
+  count: number
+}
+
+const [store, setStore] = createStore<AppState>({
+  theme: 'dark',
+  count: 0
+})
+
+store.theme // read (reactive)
+setStore('theme', 'light') // set one property
+setStore('count', (c) => c + 1) // update with function
+setStore({ theme: 'light', count: 5 }) // merge update
+
+// Derived value from store
+const label = select(store, (s) => `Theme: ${s.theme}`)
+label() // reactive getter
+```
+
+Multiple independent stores are supported — just call `createStore` multiple times.
+
+### Context
+
+```tsx
+import { createContext } from 'axon.js'
+
+const ThemeContext = createContext<'dark' | 'light'>('dark')
+
+function App() {
+  return (
+    <ThemeContext.Provider value="light">
+      <Page />
+    </ThemeContext.Provider>
+  )
+}
+
+function Page() {
+  const theme = ThemeContext.use()
+  return <div class={theme}>...</div>
+}
+```
+
+### View Transitions
+
+Pass `{ viewTransitions: true }` to `createRouter` and name your content area:
+
+```css
+main {
+  view-transition-name: page;
+}
+::view-transition-old(page) {
+  animation: 120ms ease-out fade-out both;
+}
+::view-transition-new(page) {
+  animation: 180ms ease-in fade-in both;
+}
+```
+
+The framework handles the rest automatically. Falls back gracefully in unsupported browsers.
+
+---
+
+## How it works
+
+axon.js uses **fine-grained reactivity**: a global effect stack tracks which signals are read during execution, creating subscriptions automatically. No compiler magic — pure runtime JavaScript.
+
+- Components execute **once** to build their initial DOM.
+- Only `effect()` callbacks re-execute when signals change.
+- DOM updates are surgical — only the exact node that depends on a signal is touched.
+
+For a deep dive into the internals, see [INTERNALS.md](INTERNALS.md).
+
+---
+
+## License
+
+MIT
+
+---
+
+<div align="center">
+  <sub>Built with ❤️ by <a href="https://github.com/faber1999">faber1999</a></sub>
+</div>

package/dist/chunk-HYNBHCGU.js

@@ -0,0 +1,227 @@
+// src/reactivity/effect.ts
+var effectStack = [];
+function getCurrentEffect() {
+  return effectStack[effectStack.length - 1] ?? null;
+}
+function effect(fn) {
+  let cleanup = null;
+  const run = (() => {
+    if (typeof cleanup === "function") {
+      cleanup();
+      cleanup = null;
+    }
+    effectStack.push(run);
+    try {
+      cleanup = fn() ?? null;
+    } finally {
+      effectStack.pop();
+    }
+  });
+  run._subscriptions = /* @__PURE__ */ new Set();
+  run._disposed = false;
+  run();
+  const dispose = () => {
+    run._disposed = true;
+    run._subscriptions.forEach((unsub) => unsub());
+    run._subscriptions.clear();
+    if (typeof cleanup === "function") {
+      cleanup();
+      cleanup = null;
+    }
+  };
+  return dispose;
+}
+function untrack(fn) {
+  const saved = effectStack.splice(0);
+  try {
+    return fn();
+  } finally {
+    effectStack.push(...saved);
+  }
+}
+
+// src/component/lifecycle.ts
+var ownerStack = [];
+function getCurrentOwner() {
+  return ownerStack[ownerStack.length - 1] ?? null;
+}
+function runOwned(fn) {
+  const owner = {
+    _onMount: [],
+    _onCleanup: [],
+    _children: [],
+    _mounted: false
+  };
+  const parent = getCurrentOwner();
+  if (parent) parent._children.push(owner);
+  ownerStack.push(owner);
+  let result;
+  try {
+    result = fn();
+  } finally {
+    ownerStack.pop();
+  }
+  queueMicrotask(() => {
+    if (!owner._mounted) {
+      owner._mounted = true;
+      owner._onMount.forEach((cb) => cb());
+    }
+  });
+  return [result, owner];
+}
+function runWithOwner(fn, props) {
+  const [result] = runOwned(() => fn(props));
+  return result;
+}
+function onMount(fn) {
+  const owner = getCurrentOwner();
+  if (owner) owner._onMount.push(fn);
+  else console.warn("[axon] onMount called outside of a component");
+}
+function onCleanup(fn) {
+  const owner = getCurrentOwner();
+  if (owner) owner._onCleanup.push(fn);
+  else console.warn("[axon] onCleanup called outside of a component");
+}
+function disposeOwner(owner) {
+  owner._children.forEach(disposeOwner);
+  owner._onCleanup.forEach((cb) => cb());
+  owner._onMount = [];
+  owner._onCleanup = [];
+  owner._children = [];
+}
+
+// src/dom/h.ts
+var Fragment = /* @__PURE__ */ Symbol("Fragment");
+var BOOLEAN_ATTRS = /* @__PURE__ */ new Set([
+  "checked",
+  "disabled",
+  "readonly",
+  "multiple",
+  "selected",
+  "autofocus",
+  "autoplay",
+  "controls",
+  "default",
+  "defer",
+  "formnovalidate",
+  "hidden",
+  "ismap",
+  "loop",
+  "novalidate",
+  "open",
+  "required",
+  "reversed",
+  "scoped",
+  "seamless"
+]);
+function applyProp(el, key, value) {
+  if (key === "class" || key === "className") {
+    el.className = value ?? "";
+  } else if (key === "style") {
+    if (typeof value === "string") {
+      el.style.cssText = value;
+    } else if (value && typeof value === "object") {
+      Object.assign(el.style, value);
+    }
+  } else if (key === "ref") {
+    if (typeof value === "function") {
+      value(el);
+    } else if (value && typeof value === "object") {
+      value.current = el;
+    }
+  } else if (key.startsWith("on") && key.length > 2) {
+    const event = key.slice(2).toLowerCase();
+    el.addEventListener(event, value);
+  } else if (BOOLEAN_ATTRS.has(key)) {
+    if (value) el.setAttribute(key, "");
+    else el.removeAttribute(key);
+  } else if (key === "innerHTML") {
+    el.innerHTML = value;
+  } else {
+    if (value == null || value === false) {
+      el.removeAttribute(key);
+    } else {
+      el.setAttribute(key, value === true ? "" : String(value));
+    }
+  }
+}
+function toNode(value) {
+  if (value == null || value === false) return document.createTextNode("");
+  if (value instanceof Node) return value;
+  if (typeof value === "function") return document.createTextNode("");
+  return document.createTextNode(String(value));
+}
+function appendChild(parent, child) {
+  if (child == null || child === false) return;
+  if (Array.isArray(child)) {
+    child.forEach((c) => appendChild(parent, c));
+    return;
+  }
+  if (child instanceof Node) {
+    parent.appendChild(child);
+    return;
+  }
+  if (typeof child === "function") {
+    const startMarker = document.createComment("");
+    const endMarker = document.createComment("");
+    parent.appendChild(startMarker);
+    parent.appendChild(endMarker);
+    effect(() => {
+      const result = child();
+      let node = startMarker.nextSibling;
+      while (node && node !== endMarker) {
+        const next = node.nextSibling;
+        parent.removeChild(node);
+        node = next;
+      }
+      const nodes = Array.isArray(result) ? result : [result];
+      nodes.forEach((n) => {
+        if (n != null && n !== false) {
+          parent.insertBefore(toNode(n), endMarker);
+        }
+      });
+    });
+    return;
+  }
+  parent.appendChild(document.createTextNode(String(child)));
+}
+function h(type, props, ...children) {
+  if (type === Fragment) {
+    return children.flat();
+  }
+  if (typeof type === "function") {
+    const componentProps = { ...props ?? {} };
+    if (children.length === 1) componentProps.children = children[0];
+    else if (children.length > 1) componentProps.children = children.flat();
+    return runWithOwner(type, componentProps);
+  }
+  const el = document.createElement(type);
+  if (props) {
+    for (const key of Object.keys(props)) {
+      const value = props[key];
+      if (key === "children") continue;
+      if (typeof value === "function" && !key.startsWith("on")) {
+        effect(() => applyProp(el, key, value()));
+      } else {
+        applyProp(el, key, value);
+      }
+    }
+  }
+  const flatChildren = children.flat();
+  flatChildren.forEach((child) => appendChild(el, child));
+  return el;
+}
+
+export {
+  getCurrentEffect,
+  effect,
+  untrack,
+  runOwned,
+  runWithOwner,
+  onMount,
+  onCleanup,
+  disposeOwner,
+  Fragment,
+  h
+};