docs

Author: koculu

docs-site/src/content/docs/api/createComponent.md

@@ -22,7 +22,7 @@ To create a Regor component, call the `createComponent` function with the follow
 
 - `options` (optional): An array of strings that defines component properties or an object that allows you to configure various options for the component, such as whether to use interpolation, props, the component's default name, or the component context.
   - `context` (optional): A function that defines the Regor context for the component. This function receives a `ComponentHead` object, which you can use to specify the component's behavior and props. It should return the Regor context.
-    - `head.autoProps`: Automatically assigns properties defined in the `:props` binding to the component context. Defaults to `true`.
+    - `head.autoProps`: Automatically assigns properties defined in the `:context` binding to the component context. Defaults to `true`.
     - `head.entangle`: Keeps refs defined in the component context entangled with `head.props` refs. Defaults to `true`.
     - `head.enableSwitch`: Enables slot context switching to the parent. Defaults to `false`.
     - `head.onAutoPropsAssigned`: Callback invoked after auto props get assigned to the component context.
@@ -94,3 +94,4 @@ The `createComponent` function returns a component object with the following pro
 - [`toJsonTemplate`](/api/toJsonTemplate)
 
 [Back to the API list](/api/)
+

docs-site/src/content/docs/api/index.md

@@ -1,75 +1,83 @@
 ---
 title: Regor API
 sidebar:
-  order: 5
+  order: 6
 ---
 
-In this section, you will find a list of Regor's API methods organized by categories. Click on each method to view its detailed documentation.
+This section contains the function-level reference for Regor.
 
-**App / Component Template Functions:**
+Use this page as an index, then open each API page for signature details and examples.
 
-- [`createApp`](/api/createApp)
-- [`createComponent`](/api/createComponent)
-- [`toFragment`](/api/toFragment)
-- [`toJsonTemplate`](/api/toJsonTemplate)
-- [`RegorConfig`](/api/regorConfig)
+## App and Components
 
-**Cleanup Functions:**
+1. [`createApp`](./createApp)
+2. [`createComponent`](./createComponent)
+3. [`toFragment`](./toFragment)
+4. [`toJsonTemplate`](./toJsonTemplate)
+5. [`RegorConfig`](./regorConfig)
 
-- [`addUnbinder`](/api/addUnbinder)
-- [`getBindData`](/api/getBindData)
-- [`removeNode`](/api/removeNode)
-- [`unbind`](/api/unbind)
+## Reactivity
 
-**Compute Functions:**
+1. [`ref`](./ref)
+2. [`sref`](./sref)
+3. [`isRef`](./isRef)
+4. [`isDeepRef`](./isDeepRef)
+5. [`unref`](./unref)
+6. [`pause`](./pause)
+7. [`resume`](./resume)
+8. [`trigger`](./trigger)
+9. [`entangle`](./entangle)
 
-- [`computed`](/api/computed)
-- [`computeRef`](/api/computeRef)
-- [`computeMany`](/api/computeMany)
-- [`watchEffect`](/api/watchEffect)
-- [`collectRefs`](/api/collectRefs)
-- [`silence`](/api/silence)
+## Computed and Effects
 
-**Misc Functions:**
+1. [`computed`](./computed)
+2. [`computeRef`](./computeRef)
+3. [`computeMany`](./computeMany)
+4. [`watchEffect`](./watchEffect)
+5. [`collectRefs`](./collectRefs)
+6. [`silence`](./silence)
 
-- [`flatten`](/api/flatten)
-- [`isRaw`](/api/isRaw)
-- [`markRaw`](/api/markRaw)
-- [`persist`](/api/persist)
-- [`html`](/api/html)
-- [`raw`](/api/raw)
+## Observation and Batch
 
-**Observe Functions:**
+1. [`observe`](./observe)
+2. [`observeMany`](./observeMany)
+3. [`observerCount`](./observerCount)
+4. [`batch`](./batch)
+5. [`startBatch`](./startBatch)
+6. [`endBatch`](./endBatch)
 
-- [`observe`](/api/observe)
-- [`observeMany`](/api/observeMany)
-- [`observerCount`](/api/observerCount)
-- [`batch`](/api/batch)
-- [`startBatch`](/api/startBatch)
-- [`endBatch`](/api/endBatch)
+## Lifecycle and Scope
 
-**Reactivity Functions:**
+1. [`useScope`](./useScope)
+2. [`onMounted`](./onMounted)
+3. [`onUnmounted`](./onUnmounted)
 
-- [`ref`](/api/ref)
-- [`sref`](/api/sref)
-- [`isDeepRef`](/api/isDeepRef)
-- [`isRef`](/api/isRef)
-- [`pause`](/api/pause)
-- [`resume`](/api/resume)
-- [`trigger`](/api/trigger)
-- [`unref`](/api/unref)
-- [`entangle`](/api/entangle)
+## Cleanup and Unbind
 
-**Composition Functions:**
+1. [`addUnbinder`](./addUnbinder)
+2. [`getBindData`](./getBindData)
+3. [`removeNode`](./removeNode)
+4. [`unbind`](./unbind)
 
-- [`useScope`](/api/useScope)
-- [`onMounted`](/api/onMounted)
-- [`onUnmounted`](/api/onUnmounted)
+## Utilities
 
-**Log Configuration:**
+1. [`flatten`](./flatten)
+2. [`markRaw`](./markRaw)
+3. [`isRaw`](./isRaw)
+4. [`persist`](./persist)
+5. [`html`](./html)
+6. [`raw`](./raw)
 
-- [`warningHandler`](/api/warningHandler)
+## Logging
 
-Each link will take you to a dedicated documentation page for the respective method, where you can find detailed information, examples, and usage guidelines.
+1. [`warningHandler`](./warningHandler)
 
-[Back to the main](/)
+## Recommendation
+
+Start with:
+
+1. [`createApp`](./createApp)
+2. [`ref`](./ref)
+3. [`sref`](./sref)
+4. [`computed`](./computed)
+5. [`watchEffect`](./watchEffect)

docs-site/src/content/docs/directives/context.md

@@ -0,0 +1,54 @@
+---
+title: :context Directive
+---
+
+`:context` assigns an object into a component instance context, reactively.
+`r-context` is an alias with the same behavior.
+
+Use it when you want to pass multiple values to a component in one place, including fields that are not declared in `props`.
+
+## What it does
+
+```html
+<MyComponent :context="{ title: pageTitle, theme: activeTheme }"></MyComponent>
+<MyComponent r-context="{ title: pageTitle, theme: activeTheme }"></MyComponent>
+```
+
+In the component, `title` and `theme` become available as component context fields (or update existing ref fields when applicable).  
+When `pageTitle` or `activeTheme` changes, the component values are updated.
+
+## When to use `:context`
+
+Use `:context` for object-style component input.
+`r-context` is equivalent and can be used interchangeably.
+
+Use `:prop-name="value"` or `r-bind:prop-name="value"` (same single-prop binding behavior) when the prop is declared in the component `props` list.
+
+Use object-form attribute binding (`r-bind="{...}"` or `:="{...}"`) for normal host attribute fallthrough, not for component context assignment.
+
+## Example
+
+```html
+<UserCard
+  :user-id="selectedUserId"
+  :context="{ badge: userBadge, canEdit: isAdmin }"
+></UserCard>
+```
+
+```ts
+const UserCard = createComponent('<section>...</section>', {
+  props: ['userId'],
+  context: (head) => ({
+    userId: head.props.userId,
+    badge: head.props.badge,
+    canEdit: head.props.canEdit,
+  }),
+})
+```
+
+In this example:
+
+- `userId` comes from declared prop binding (`:user-id`)
+- `badge` and `canEdit` come from `:context`
+
+[Back to the directives](/directives/)

docs-site/src/content/docs/directives/index.md

@@ -1,50 +1,56 @@
 ---
 title: Directives
 sidebar:
-  order: 4
+  order: 5
 ---
 
-In Regor, directives are special attributes that start with the "r-" prefix. They allow you to enhance the behavior and appearance of your applications. Below, you'll find a list of supported directives categorized by their functionality.
+Directives are Regor’s runtime template control surface.
 
-> **Note:** The directive prefix "r-" can be customized using `RegorConfig.getDefault().setDirectives('v-')` to align with a different naming convention, such as Vue's "v-" prefix.
+By default, directive names start with `r-`. You can customize the prefix with `RegorConfig`.
 
-**Binding Directives:**
+## Core Rules
 
-- [`r-bind`](/directives/r-bind) Binds an element's attribute to a component's data, allowing dynamic updates.
-- [`r-model`](/directives/r-model) Enables two-way data binding between form inputs.
-- [`r-text`](/directives/r-text) Sets the element's text content to the result of an expression.
-- [`r-html`](/directives/r-html) Renders the result of an expression as HTML content within the element.
-- [`r-on`](/directives/r-on) Attaches event listeners to the element and invokes specified component methods.
-- [`r-show`](/directives/r-show) Conditionally displays the element based on the truthiness of an expression.
+1. `r-` directives are explicit full-form syntax.
+2. `:` is shorthand for `r-bind`.
+3. `@` is shorthand for `r-on`.
+4. `.` shorthand binds DOM properties (equivalent to `r-bind.prop`).
 
-**Control Flow Directives:**
+## Binding
 
-- [`r-for`](/directives/r-for) Renders a set of elements based on an array and a template.
-- [`r-if`](/directives/r-if) Conditionally renders the element based on the truthiness of an expression.
-- [`r-else`](/directives/r-if) Provides an alternative rendering when used in conjunction with `r-if`.
-- [`r-else-if`](/directives/r-if) Conditionally renders the element as an alternative to `r-if`.
+1. [`r-text`](./r-text): text content binding.
+2. [`r-html`](./r-html): HTML content binding.
+3. [`r-bind`](./r-bind): attributes/properties/object binding.
+4. [`r-model`](./r-model): form two-way binding.
+5. [`r-on`](./r-on): event binding.
+6. [`r-show`](./r-show): conditional visibility.
+7. [`:class`](./class): dynamic class binding.
+8. [`:style`](./style): dynamic style binding.
 
-**Utility Directives:**
+## Control Flow
 
-- [`r-pre`](/directives/r-pre) Excludes HTML element from Regor bindings.
-- [`:class`](/directives/class) Binds one or more class names to an element based on expressions.
-- [`:style`](/directives/style) Binds one or more inline styles to an element based on expressions.
-- [`:ref`](/directives/ref) Provides a reference to an element in the template, allowing you to interact with it programmatically.
-- [`:key`](/directives/r-for) Provides a unique identifier for each item in a list, aiding efficient updates and rendering.
-- [`:is`](/directives/is) Specifies the component to dynamically render based on a value or expression.
-- [`r-teleport`](/directives/r-teleport): Teleports the element to anywhere in the DOM. Unlike Vue, teleport is a directive to avoid component overhead.
-- [`:props`](/directives/props) Vue uses `v-bind` for component property passing. However, this can conflict with `v-bind`'s attribute fall-through logic. Hence, Regor defines a dedicated directive to pass properties using object syntax. It enables passing properties without defining them in the component's props contract.
-- [`:props-once`](/directives/props-once) Similar to `:props` but it doesn't observe the entire reactive tree of the template expression. Tail reactivity still works.
+1. [`r-if`](./r-if), `r-else-if`, `r-else`: conditional branches.
+2. [`r-for`](./r-for): list/object iteration with keying support.
 
-**Event Handling Directives:**
+## Component and Utility
 
-- [`@`](/directives/r-on) Shorthand for `r-on` to bind event listeners.
+1. [`:is`](./is): dynamic component selection.
+2. [`:context`](./context): component prop object binding.
+3. [`:ref`](./ref): element/component references.
+4. [`r-pre`](./r-pre): skip compilation for subtree.
+5. [`r-teleport`](./r-teleport): move DOM subtree to another target.
 
-**Attribute Binding Directives:**
+## Important Keying Note
 
-- [`:`](/directives/r-bind) Shorthand for `r-bind` to bind element attributes.
-- [`.`](/directives/r-bind) Shorthand for `r-bind.prop` to set properties.
+In `r-for`, both `key="row.id"` and `:key="row.id"` are expression bindings in Regor templates. Both are supported. Nested paths like `a.b.c.d` are supported.
 
-These directives empower you to create dynamic and interactive user interfaces, enhancing the user experience of your Regor-powered applications. Click on each directive to view its detailed documentation, including examples and usage guidelines.
+Use stable keys whenever list identity matters.
 
-[Back to the main](/)
+## Recommendation
+
+Read in this order:
+
+1. [`r-bind`](./r-bind)
+2. [`r-text`](./r-text)
+3. [`r-if`](./r-if)
+4. [`r-for`](./r-for)
+5. [`r-model`](./r-model)