humn 1.7.0 → 1.7.1

package/docs/guides/api-reference.md

@@ -0,0 +1,91 @@
+# API Reference
+
+## `mount(target, Component)`
+
+Mounts a component to a target DOM element.
+
+- `target`: The DOM element to mount the component to.
+- `Component`: The root component to render.
+
+## `Cortex<Memory, Synapses>({ memory, synapses })`
+
+Creates a strongly-typed `Cortex` instance for state management.
+
+- **Generics**:
+  - `Memory`: The shape of your state object.
+  - `Synapses`: The shape of your actions object.
+- **Arguments**:
+  - `memory`: The initial state. Values can be raw or wrapped in `persist()`.
+  - `synapses`: A builder function `(set, get) => Synapses`.
+
+### The `set` function
+
+When typing is applied, `set` supports two modes:
+
+1. **Partial Update**: `set({ count: 1 })` — validated against `Memory`.
+2. **Functional Update**: `set(state => { state.count++ })` — `state` is inferred as `Memory`.
+
+### `persist(initial, config)`
+
+Marks a section of the state for persistence in localStorage.
+
+- `initial`: The initial value of the state.
+- `config`: (Optional) The configuration for persistence.
+  - `key`: A custom key to use in `localStorage`.
+
+## `onMount(callback)`
+
+Registers a callback to be called after a component is mounted.
+
+- `callback`: The function to be called.
+
+## `onCleanup(callback)`
+
+Registers a callback to be called when a component is unmounted.
+
+- `callback`: The function to be called.
+
+## Interaction Helper Props
+
+Interaction helpers are optional props for common DOM interaction boilerplate. Existing event behavior is unchanged when these props are not used. See the [Interaction Helpers guide](./interaction-helpers.md) for examples and edge-case details.
+
+### Keyboard Helpers
+
+- `onenter(event)`: runs when `Enter` is pressed.
+- `onescape(event)`: runs when `Escape` is pressed.
+- `onkeys`: object map of key combinations to handlers, such as `{ 'Mod+Enter': save, Escape: close }`.
+
+Keyboard helpers are composition-aware and ignore key handling while IME composition is active. `Mod` maps to `Meta` on macOS and `Ctrl` elsewhere.
+
+### Debounced Input
+
+- `debounce={number}`: debounce delay in milliseconds. Defaults to `250` when omitted or invalid.
+- `oninputdebounced(event)`: runs once input settles for the configured delay.
+
+Each input event clears the previous pending timer. The callback receives an event-like object with `target` and `currentTarget` set to the element, so `event.target.value` reflects the latest value when the timer fires.
+
+### Commit Semantics
+
+- `oncommit(event)`: runs when a field is committed by `Enter` or blur.
+
+If pressing `Enter` causes blur, `oncommit` fires once for that user intent instead of firing for both events. The Enter path is IME-safe.
+
+### Async Click Helpers
+
+- `onclickasync(event)`: async click handler.
+- `disabledwhilepending`: when true, disables the element and blocks repeated clicks while `onclickasync` is pending.
+
+The element is re-enabled after the async handler settles, including rejection. Without `disabledwhilepending`, repeated async clicks are allowed.
+
+### Event Modifiers
+
+Use pipe syntax on event prop keys for explicit modifiers:
+
+- `'onclick|prevent'`
+- `'onclick|stop'`
+- `'onsubmit|prevent|stop'`
+- `'onclick|once'`
+- `'onclick|capture'`
+- `'onscroll|passive'`
+
+`prevent` and `stop` run before the handler. `once`, `capture`, and `passive` are passed as listener options. Modifiers are opt-in and local to the specific handler prop.

package/docs/guides/getting-started.md

@@ -0,0 +1,83 @@
+# Getting Started
+
+This guide will walk you through the process of creating a simple "Hello, World!" application with Humn.
+
+## Installation
+
+### Humn Core
+
+You can install Humn using npm or yarn:
+
+```bash
+npm install humn
+# or
+yarn add humn
+```
+
+### The Vite Plugin
+
+To use `.humn` files, you need to use the `vite-plugin-humn` in your Vite configuration.
+
+```bash
+npm install --save-dev vite-plugin-humn
+# or
+yarn add vite-plugin-humn -D
+```
+
+```javascript
+// vite.config.js
+import { defineConfig } from 'vite'
+import humn from 'vite-plugin-humn'
+
+export default defineConfig({
+  plugins: [humn()],
+})
+```
+
+### Prettier
+
+We also have, and recommend, a Prettier Plugin which can be installed like any other
+
+```bash
+npm install --save-dev prettier-plugin-humn
+# or
+yarn add prettier-plugin-humn -D
+```
+
+```javascript
+// prettier.config.js
+import humn from 'prettier-plugin-humn'
+
+const config = {
+  plugins: [humn],
+}
+
+export default config
+```
+
+## Hello, World
+
+Here's a simple "Hello, World!" example to get you started:
+
+```humn
+<script>
+  // App.humn
+  const message = 'Hello, World!'
+</script>
+
+<h1>{message}</h1>
+```
+
+In this example, we're creating a simple component that renders an `h1` element with the text "Hello, World!".
+
+To mount this application, you would typically have an entry point like `main.js`:
+
+```javascript
+// main.js
+import { mount } from 'humn'
+import App from './App.humn'
+
+mount(document.getElementById('root'), App)
+```
+
+In this example, we're creating a simple component called `App` that renders an `h1` element with the text "Hello, World!". We then mount the `App` component to the `div` with the id `root`.

package/docs/guides/humn-files.md

@@ -0,0 +1,87 @@
+# .humn Files
+
+Humn introduces a dedicated file format `.humn` to make writing components even more intuitive. It feels a lot like Svelte, but with Humn's unique flavour.
+
+A `.humn` file consists of three optional sections: `<script>`, `<template>` (implicit), and `<style>`.
+
+## Structure
+
+```humn
+<script>
+  // Your JavaScript logic here
+  import { cortex } from './cortex.js'
+
+  // Props are available via the `props` variable
+  const { name } = props
+
+  // Access cortex state
+  const { count } = cortex.memory
+  const { increment } = cortex.synapses
+</script>
+
+<!-- The template is the main content of the file -->
+<div>
+  <h1>Hello, {name}!</h1>
+  <p>Count: {count}</p>
+  <button onclick={increment}>Increment</button>
+</div>
+
+<style>
+  /* Scoped CSS */
+  div {
+    padding: 20px;
+    border: 1px solid #ccc;
+  }
+
+  h1 {
+    color: blue;
+  }
+</style>
+```
+
+## The Script Section
+
+The `<script>` block is where you define your component's logic.
+
+- **Imports**: Import other components, cortexes, or utilities.
+- **Props**: `props` is a magic variable available in the script scope containing the properties passed to the component.
+- **Reactivity**: Destructuring from `Cortex` memory creates reactive subscriptions.
+
+## The Template
+
+Anything outside of `<script>` and `<style>` tags is considered the template.
+
+- **JSX-like Syntax**: Use `{expression}` to embed JavaScript values.
+- **Directives**: Use standard HTML attributes. Event listeners match the HTML format, such as `onclick`, and runtime interaction helpers such as `onenter`, `oncommit`, and `oninputdebounced` are available on base elements.
+- **Control Flow**: Use JavaScript logic within curly braces for conditionals and loops.
+
+```humn
+{isLoading && <div class="loader">Loading...</div>}
+
+<ul>
+  {items.map((item) => (
+    <li>{item.name}</li>
+  ))}
+</ul>
+```
+
+Interaction helpers can remove common event boilerplate from templates:
+
+```humn
+<script>
+  const save = (event) => {
+    const value = event.target.value
+  }
+</script>
+
+<input debounce={300} oninputdebounced={save} oncommit={save} />
+```
+
+See the [Interaction Helpers guide](./interaction-helpers.md) for keyboard helpers, debounce behavior, commit semantics, async click handling, and event modifiers.
+
+## The Style Section
+
+The `<style>` block contains CSS that is **scoped** to the component.
+
+- **Isolation**: Styles defined here will not leak out to other components.
+- **No Config**: It works out of the box with the Humn compiler.

package/docs/guides/interaction-helpers.md

@@ -0,0 +1,117 @@
+# Interaction Helpers
+
+Humn includes small runtime helper props for common UI interactions. They are regular props on base DOM elements, so existing event handling behavior is unchanged unless you opt into one of these helpers.
+
+## Keyboard Helpers
+
+Use keyboard helpers when you want common key handling without writing the same `keydown` branching code in every component.
+
+```humn
+<script>
+  const save = () => {
+    // Save the current field value.
+  }
+
+  const close = () => {
+    // Close a dialog or clear focus.
+  }
+</script>
+
+<input
+  onenter={save}
+  onescape={close}
+  onkeys={{ 'Mod+Enter': save, 'Shift+Escape': close }}
+/>
+```
+
+- `onenter`: runs when `Enter` is pressed.
+- `onescape`: runs when `Escape` is pressed.
+- `onkeys`: maps key combinations to handlers.
+
+Key combinations use `event.key` names plus optional `Ctrl`, `Meta`, `Alt`, and `Shift` modifiers. `Mod` maps to `Meta` on macOS and `Ctrl` elsewhere.
+
+Keyboard helpers are IME-safe. They ignore keyboard events while composition is active, including native `event.isComposing` events and the period between `compositionstart` and `compositionend`.
+
+## Debounced Input
+
+Use `oninputdebounced` when input should wait until typing settles before running work such as filtering, validation, or search.
+
+```humn
+<script>
+  const search = (event) => {
+    const query = event.target.value
+    // Run the search with the latest value.
+  }
+</script>
+
+<input debounce={300} oninputdebounced={search} />
+```
+
+- `debounce`: delay in milliseconds.
+- `oninputdebounced`: runs after the delay has passed without another input event.
+
+If `debounce` is omitted or cannot be converted to a finite number, Humn uses `250` milliseconds. Each input event clears the previous pending timer, and the callback receives an event-like object whose `target` and `currentTarget` point at the input element so the latest value is available when the timer fires.
+
+## Commit Semantics
+
+Use `oncommit` when a field should commit on either `Enter` or blur.
+
+```humn
+<script>
+  const commitName = (event) => {
+    const name = event.target.value
+    // Persist the committed value.
+  }
+</script>
+
+<input oncommit={commitName} />
+```
+
+`oncommit` runs when the element receives `Enter` or loses focus. If pressing `Enter` also causes blur, Humn treats that as one user intent and fires `oncommit` once instead of double-firing. The Enter path uses the same IME safety as the keyboard helpers.
+
+## Async Click Helpers
+
+Use `onclickasync` for async submit-style actions, and add `disabledwhilepending` when repeated clicks should be blocked while the promise is pending.
+
+```humn
+<script>
+  const save = async () => {
+    await api.save()
+  }
+</script>
+
+<button onclickasync={save} disabledwhilepending={true}>
+  Save
+</button>
+```
+
+- `onclickasync`: async click handler.
+- `disabledwhilepending`: when true, disables the element and blocks repeated clicks until the async handler settles.
+
+The disabled state is restored in a `finally` step, so the element is re-enabled whether the promise resolves or rejects. Without `disabledwhilepending`, `onclickasync` behaves like an async click listener and repeated clicks are allowed.
+
+## Event Modifiers
+
+Event modifiers are explicit, local opt-ins on handler prop names. They use pipe syntax on the prop key.
+
+```javascript
+import { h } from 'humn'
+
+export function Link() {
+  return h(
+    'a',
+    { href: '#', 'onclick|prevent|stop': (event) => navigate(event) },
+    'Open',
+  )
+}
+```
+
+- `prevent`: calls `event.preventDefault()` before the handler.
+- `stop`: calls `event.stopPropagation()` before the handler.
+- `once`: installs the listener with `{ once: true }`.
+- `capture`: installs the listener with `{ capture: true }`.
+- `passive`: installs the listener with `{ passive: true }`.
+
+Modifiers apply only to the specific handler prop where they are declared. Unknown modifier names are ignored.
+
+Pipe-named modifiers are runtime prop keys. When using `h()`, quote the key as shown above. Current `.humn` templates support the helper props in this guide, but do not parse `|` inside attribute names; use standard event handlers in templates or generate a quoted prop key through `h()` for modifier behavior.

package/docs/guides/lifecycle-hooks.md

@@ -0,0 +1,51 @@
+# Lifecycle Hooks
+
+Humn provides two lifecycle hooks: `onMount` and `onCleanup`.
+
+## Side Effects & Data Fetching (Important)
+
+**Do not start fetches, timers, subscriptions or DOM listeners directly in a `.humn` script block.** The `<script>` block is part of the component's render logic, which means it may run multiple times (on every re-render).
+
+Always use `onMount` for component-owned side effects to ensure they run only once when the component appears in the DOM.
+
+```humn
+<script>
+  import { onMount } from 'humn'
+  import { api } from '../api.js'
+
+  // ❌ BAD: This will trigger an infinite loop of fetches and re-renders!
+  // api.fetchData()
+
+  // ✅ GOOD: Runs only once when the component mounts
+  onMount(() => {
+    api.fetchData()
+  })
+</script>
+```
+
+_(Note: For robust data fetching, we recommend using Cortex's built-in `resource` primitives instead of manual API calls. See the [Data Fetching guide](./state-management.md#data-fetching) for the best practices.)_
+
+## Overview
+
+The `onMount` hook is called after a component is mounted to the DOM. You can use it to perform any setup that you need to do.
+
+The `onCleanup` hook is called when a component is unmounted from the DOM. You can use it to perform any cleanup that you need to do, such as removing event listeners.
+
+Here's an example of how to use the lifecycle hooks:
+
+```humn
+<script>
+  // MyComponent.humn
+  import { onMount, onCleanup } from 'humn'
+
+  onMount(() => {
+    console.log('Component mounted!')
+  })
+
+  onCleanup(() => {
+    console.log('Component unmounted!')
+  })
+</script>
+
+<p>My component</p>
+```

package/docs/guides/scoped-css.md

@@ -0,0 +1,22 @@
+# Scoped CSS
+
+In `.humn` files, you can simply use the `<style>` tag. Humn automatically scopes these styles to your component.
+
+```humn
+<script>
+  // MyComponent.humn
+  // ... logic
+</script>
+
+<p>This component has scoped styles, no need for classes!</p>
+<div>Both elements are styled by top level, unwrapped, CSS</div>
+
+<style>
+  background: red; /* This applies to both the <p> and the <div> */
+
+  p {
+    color: blue;
+    font-size: 20px;
+  }
+</style>
+```

package/docs/guides/state-management.md

@@ -0,0 +1,172 @@
+# State Management
+
+Humn's state management system is called `Cortex`. It is a simple yet powerful way to manage the state of your application.
+
+To create a `Cortex` instance, you need to provide an initial `memory` (state) and a `synapses` function. The `synapses` function receives `set` and `get` functions that you can use to interact with the state.
+
+Here's an example of a simple counter:
+
+```javascript
+// cortex.js
+import { Cortex } from 'humn'
+
+export const counterCortex = new Cortex({
+  memory: {
+    count: 0,
+  },
+  synapses: (set) => ({
+    increment: () => set((state) => ({ count: state.count + 1 })),
+    decrement: () => set((state) => ({ count: state.count - 1 })),
+  }),
+})
+```
+
+```humn
+<script>
+  // App.humn
+  import { counterCortex } from './cortex.js'
+
+  const { count } = counterCortex.memory
+  const { increment, decrement } = counterCortex.synapses
+</script>
+
+<div>
+  <h1>{count}</h1>
+  <button onclick={increment}>Increment</button>
+  <button onclick={decrement}>Decrement</button>
+</div>
+```
+
+To mount the app:
+
+```javascript
+// main.js
+import { mount } from 'humn'
+import App from './App.humn'
+
+mount(document.getElementById('app'), App)
+```
+
+In this example, we're creating a `Cortex` instance called `counterCortex` with an initial count of 0. We're also defining two synapses, `increment` and `decrement`, that update the count.
+
+The `App` component gets the `count` from the `counterCortex.memory` and the `increment` and `decrement` functions from the `counterCortex.synapses`. It then renders the count and two buttons to increment and decrement the count.
+
+## State Persistence
+
+You can persist the state of your application to `localStorage` using the `persist` utility. This is useful for keeping the state of your application across page reloads.
+
+To use it, wrap the value you want to persist with the `persist` function.
+
+```javascript
+import { Cortex, persist } from 'humn'
+
+const todoCortex = new Cortex({
+  memory: {
+    items: persist([
+      { id: 1, text: 'Create Humn Library', done: true },
+      { id: 2, text: 'Write first app', done: false },
+    ]),
+    inputValue: '',
+    errorMessage: '',
+    isLoading: false,
+  },
+  // ...
+})
+```
+
+By default, the key used in `localStorage` will be the same as the key in the `memory` object. In the example above, the key will be `items`.
+
+You can also provide a custom key by passing a configuration object to the `persist` function:
+
+```javascript
+const todoCortex = new Cortex({
+  memory: {
+    items: persist(
+      [
+        { id: 1, text: 'Create Humn Library', done: true },
+        { id: 2, text: 'Write first app', done: false },
+      ],
+      { key: 'my-custom-key' },
+    ),
+    // ...
+  },
+  // ...
+})
+```
+
+## Type Safety (TS & JSDoc)
+
+Cortex supports strong typing out of the box. By defining your Memory and Synapse types, you ensure that your `set` updates are valid and your components receive the correct data types.
+
+Cortex automatically handles the complexity of unwrapping `persist()` values in your types, so your API remains clean.
+
+> For a detailed guide on how to type your cortex using TypeScript or JSDoc, see the **[TypeScript Support](./typescript.md)** guide.
+
+## Data Fetching
+
+Do not start fetches directly in a `.humn` script block. The script block runs during render and may run many times.
+
+Use `onMount` to trigger component-owned loading, and use a Cortex resource synapse to own the async workflow.
+
+Components should read resource state and render the right UI. They should not manage request lifecycle manually.
+
+### The `resource` primitive
+
+Humn comes with built-in primitives to handle server state, similar to React Query or Solid's resources: `resource` and `resourceSynapse`.
+
+```javascript
+// cortexes/crmCortex.js
+import { Cortex, resource, resourceSynapse } from 'humn'
+import { api } from '../api/api.js'
+
+export const crmCortex = new Cortex({
+  memory: {
+    // Automatically creates { data: [], status: 'idle', loading: false, error: null }
+    accounts: resource([]),
+  },
+
+  synapses: (set, get) => ({
+    // Automatically manages loading/error states, race conditions, and deduplication
+    loadAccounts: resourceSynapse(set, get, 'accounts', async (params) => {
+      return api.accounts.list(params)
+    }),
+  }),
+})
+```
+
+Usage in a component:
+
+```humn
+<script>
+  import { onMount } from 'humn'
+  import { crmCortex } from '../cortexes/crmCortex.js'
+
+  const { accounts } = crmCortex.memory
+  const { loadAccounts } = crmCortex.synapses
+
+  // Trigger the fetch safely on mount
+  onMount(() => loadAccounts())
+</script>
+
+<div>
+  {#if accounts.loading}
+    <p>Loading accounts...</p>
+  {/if}
+  
+  {#if accounts.error}
+    <p>Could not load accounts: {accounts.error.message}</p>
+  {/if}
+
+  {#if accounts.status === 'success'}
+    <ul>
+      {accounts.data.map(acc => <li>{acc.name}</li>)}
+    </ul>
+  {/if}
+</div>
+```
+
+`resourceSynapse` supports fetching options like `force`:
+
+```javascript
+crmCortex.synapses.loadAccounts(null, { force: true })
+```