cajoa 0.7.0 → 0.9.0

package/README.md

@@ -3,22 +3,34 @@
 A small, beginner-friendly frontend framework built on **signals** and **JSX**.
 No virtual DOM, no hooks rules, no re-rendering components.
 
-> ⚠️ **v0.6 (early stage).** The API may still change. Not production-ready yet.
+> ⚠️ **Early stage.** The API may still change before 1.0.
 
 ## Why Cajoa?
 
 - **Components run once.** A component is just a function that builds DOM. Only the parts that depend on a signal update.
 - **Plain JSX.** Write `<button onClick={...}>`, no special syntax to learn.
-- **Tiny and readable.** The whole core is small enough to read in one sitting.
+- **Tiny and readable.** The core is small enough to read in one sitting.
+- **Renderer-agnostic core.** `@cajoa/core` has no DOM dependency, so other targets (native, SSR) can plug in their own renderer.
 - **TypeScript-first**, ESM + CommonJS, zero runtime dependencies.
 
-## Install
+## Get started
+
+The fastest way is the starter:
 
 ```bash
 npm create cajoa@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Or add Cajoa to an existing project:
+
+```bash
+npm install cajoa
 ```
 
-## Setup (JSX)
+### Manual JSX setup
 
 In your `tsconfig.json`:
 
@@ -31,7 +43,7 @@ In your `tsconfig.json`:
 }
 ```
 
-If you use Vite and your JSX is not transformed, also set it in `vite.config.ts`
+With Vite, also set it in `vite.config.ts`
 (`oxc: { jsx: { runtime: "automatic", importSource: "cajoa" } }` on newer Vite,
 or `esbuild: { jsx: "automatic", jsxImportSource: "cajoa" }` on older ones).
 
@@ -55,7 +67,7 @@ render(Counter, document.getElementById("app")!);
 
 ## Two rules to remember
 
-Cajoa has no compiler, so JSX expressions run exactly once. That gives two rules:
+Cajoa has no compiler yet, so JSX expressions run exactly once. That gives two rules:
 
 1. **Pass the signal, don't call it.**
    `{count}` is reactive. `{count()}` is read once and never updates.
@@ -82,6 +94,54 @@ const [todos, setTodos] = createSignal([{ id: 1, text: "Learn Cajoa" }]);
 
 ## Routing
 
+## Forms, styles and events
+
+````tsx
+const [name, setName] = createSignal("");
+const [agree, setAgree] = createSignal(false);
+
+<form>
+  <input
+    placeholder="Name"
+    value={name}
+    onInput={(e) => setName(e.target.value)}
+  />
+  <label>
+    <input
+      type="checkbox"
+      checked={agree}
+      onChange={(e) => setAgree(e.target.checked)}
+    />
+    I agree
+  </label>
+  <p style={() => ({ color: agree() ? "green" : "gray", fontSize: "18px" })}>
+    Hello, {() => name() || "stranger"}!
+  </p>
+</form>;
+
+## Refs and SVG
+
+```tsx
+function SearchBox() {
+  let input: HTMLInputElement | undefined;
+
+  return (
+    <div>
+      <input ref={(el: HTMLInputElement) => (input = el)} />
+      <button onClick={() => input?.focus()}>Focus</button>
+    </div>
+  );
+}
+
+````
+
+- `value`, `checked` and `selected` are set as DOM properties, so they stay in sync even after the user typed. Write `value` after `type`, `min` and `max`.
+- `style` takes a string or an object (camelCase keys, kebab-case keys, or custom properties like `--accent`). Numbers are not converted to `px`, so write `"12px"`. For a reactive style, pass a function: `style={() => ({ color: color() })}`. An object with signals inside, like `style={{ color: color() }}`, is read once.
+- Events are native DOM events. `onChange` fires when a field loses focus, so use `onInput` for every keystroke. `onDoubleClick` listens to `dblclick`.
+- `className` and `htmlFor` work. Inline string handlers like `onclick="..."` are ignored.
+- `ref` is a function that receives the element once it is created. Its props and children are ready, but it is not in the page yet, so use `onMount` if you need to measure it right away. Signals read inside `ref` are not tracked.
+- SVG works: `<svg>`, `<path>`, `<circle>`, gradients, filters and the other SVG tags are created in the SVG namespace. Write attributes as `stroke-width="2"` or `strokeWidth="2"`.
+
 ```tsx
 import { render, Router, Route, Link, useParams } from "cajoa";
 
@@ -106,6 +166,15 @@ render(
 
 Routes are matched in order, so put `path="*"` last.
 
+## Packages
+
+| Package        | What it is                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------ |
+| `cajoa`        | The package most apps install (core + DOM)                                                 |
+| `@cajoa/core`  | Renderer-agnostic core: signals, JSX runtime, `Show`, `For`, context, `Renderer` interface |
+| `@cajoa/dom`   | DOM renderer and router                                                                    |
+| `create-cajoa` | Project starter (`npm create cajoa@latest`)                                                |
+
 ## API
 
 ### Reactivity
@@ -116,13 +185,15 @@ Routes are matched in order, so put `path="*"` last.
 | `createEffect(fn)`    | Runs `fn` now and again whenever a signal it read changes.                                                             |
 | `createMemo(fn)`      | Cached computed value. Only notifies when the result changes.                                                          |
 | `batch(fn)`           | Groups several `set` calls into one update.                                                                            |
+| `untrack(fn)`         | Runs `fn` without subscribing to signals.                                                                              |
 
 ### Components
 
-| Component              | What it does                                                                                         |
-| ---------------------- | ---------------------------------------------------------------------------------------------------- |
-| `<Show when fallback>` | Conditional rendering. `children` and `fallback` are functions.                                      |
-| `<For each key?>`      | List rendering. Reuses DOM nodes for unchanged items. The child is a function that returns a `Node`. |
+| Component              | What it does                                                                                              |
+| ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| `<Show when fallback>` | Conditional rendering. `children` and `fallback` are functions.                                           |
+| `<For each key?>`      | List rendering. Reuses DOM nodes for unchanged items. The child is a function that returns a single node. |
+| `<>...</>` (Fragment)  | Groups siblings without a wrapper element.                                                                |
 
 ### Rendering
 
@@ -157,7 +228,6 @@ Routes are matched in order, so put `path="*"` last.
 | `navigate(to, { replace? })` | Navigates programmatically.                                |
 | `useParams()`                | Reads the route params (`{ id: "7" }`).                    |
 | `usePath()`                  | Returns a signal getter for the current pathname.          |
-| `untrack(fn)`                | Runs `fn` without subscribing to signals.                  |
 
 ### Renderer
 
@@ -167,20 +237,12 @@ Routes are matched in order, so put `path="*"` last.
 | `getRenderer()`         | Returns the current renderer.                                      |
 | `domRenderer`           | The built-in DOM renderer.                                         |
 
-## Packages
-
-| Package       | What it is                                                           |
-| ------------- | -------------------------------------------------------------------- |
-| `cajoa`       | The package most apps install (core + DOM)                           |
-| `@cajoa/core` | Renderer-agnostic core: signals, JSX runtime, `Show`, `For`, context |
-| `@cajoa/dom`  | DOM renderer and router                                              |
-
 ## Good to know
 
 - `For` uses the item itself as the key by default. If you pass `key`, items with the same key are **not** re-rendered when their data changes, so keys must be unique and the item should hold its own signals if it needs to update.
-- `useContext` only works while a component is being created (or inside `onMount` / effects). Read it at the top of your component and use the value later in handlers.
+- Inside `<For>`, return a single element (not a fragment), because `For` reuses that node.
+- `useContext` and `useParams` only work while a component is being created (or inside `onMount` / effects). Read them at the top of your component and use the value later in handlers.
 - Updating an object in place will not trigger effects. Set a new object instead.
-- Fragments (`<>...</>`) work anywhere, but inside `<For>` the child must be a single element, because `For` reuses that node.
 
 ## Known limitations
 
@@ -188,26 +250,28 @@ Routes are matched in order, so put `path="*"` last.
 - Router: pathname only (no query/hash handling), no nested routes, no `base` path.
 - `<Show>` and `<Router>` return a function, so they must sit inside an element, not be the root returned by `render`.
 - Single-page apps need a server fallback to `index.html` for unknown paths.
+- `<select value>` works only when the `<option>` elements are direct children of the `<select>`.
 - `createMemo` can show a brief inconsistent state when memos depend on each other.
 - `set` calls are not batched automatically inside event handlers. Wrap them in `batch()`.
-- The Router and event names (`onClick`) are still web-specific for now.
+- Types in the core use a loose `HostNode` type for now.
+- Inside `<svg>`, the tags `<a>`, `<title>`, `<style>` and `<script>` are created as HTML elements (they share their names with HTML tags).
 
 ## Roadmap
 
-- [x] Signals and effects
-- [x] DOM bindings and `render`
-- [x] `Show`, `For` (keyed)
-- [x] Lifecycle and disposal
-- [x] `createMemo`, `batch`
-- [x] Context
+- [x] Signals, effects, memo, batch
+- [x] DOM bindings, `Show`, keyed `For`, Fragments
+- [x] Lifecycle, context
 - [x] JSX support
-- [x] Fragments
 - [x] Router
-- [x] Renderer abstraction (core no longer depends on DOM)
-- [ ] Split into packages ('@cajoa/core', '@cajoa/dom')
+- [x] Renderer abstraction, split into packages
+- [x] Automated releases
+- [x] Form, style and event handling in the DOM renderer
+- [ ] SVG and `ref` support
 - [ ] Vite plugin (removes the two rules above)
-- [ ] Native renderer (mobile, desktop)
+- [ ] Better form and style handling in the DOM renderer
+- [ ] Native renderers (mobile, desktop)
 - [ ] SSR
+- [ ] Docs site
 
 ## Development
 
@@ -215,9 +279,11 @@ Routes are matched in order, so put `path="*"` last.
 npm install
 npm test          # run tests
 npm run dev       # open the playground
-npm run build     # build to dist/
+npm run verify    # typecheck, tests, build, sync and package checks
 ```
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the release flow.
+
 ## License
 
 [Apache-2.0](./LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cajoa",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "A small, beginner-friendly frontend framework built on signals and JSX.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -56,8 +56,8 @@
   ],
   "sideEffects": true,
   "dependencies": {
-    "@cajoa/core": "^0.7.0",
-    "@cajoa/dom": "^0.7.0"
+    "@cajoa/core": "^0.9.0",
+    "@cajoa/dom": "^0.9.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",