regor 1.5.2 → 1.5.4

package/README.md

@@ -369,8 +369,8 @@ Regor provides a set of directives that allow you to enhance the behavior and ap
 - **`:key`** Provides a unique identifier for each item in a list, aiding efficient updates and rendering.
 - **`:is`** Specifies the component to dynamically render based on a value or expression.
 - **`r-teleport`** Teleports the element to anywhere in the DOM. Unlike Vue, teleport is a directive to avoid component overhead.
-- **`: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`** Similar to :props but it doesn't observe entire reactive tree of the template expression. Tail reactivity still works.
+- **`:context`** Assigns an object into a component instance context, reactively. Use it for object-style component input, including fields that are not declared in the component `props` list.
+- **`r-context`** Alias of `:context` with the same behavior.
 - **`@`** Shorthand for `r-on` to bind event listeners.
 - **`:`** Shorthand for `r-bind` to bind element attributes.
 - **`.`** Shorthand for `r-bind.prop` to set properties.

package/dist/regor.d.ts

@@ -147,24 +147,36 @@ export declare class ComponentHead<TContext extends IRegorContext | object = IRe
 	 */
 	ctx: IRegorContext[];
 	/**
-	 * Controls whether Regor should automatically apply incoming `head.props`
-	 * values to the component context after `context(head)` returns.
+	 * Controls whether Regor automatically merges parent-provided component inputs
+	 * into the object returned by `context(head)`.
 	 *
-	 * Think of it as "auto wire parent inputs into my component fields".
+	 * There are two runtime data sources for a component:
+	 *
+	 * 1. Parent inputs:
+	 *    values passed from the component host, such as `:title="abc"` or
+	 *    `:context="{ ... }"`. These are exposed on `head.props`.
+	 *
+	 * 2. Component context:
+	 *    the object returned by `context(head)`. This is the component's own local
+	 *    state.
+	 *
+	 * `autoProps` controls the third step: how those two sources are merged.
 	 *
 	 * - `true` (default):
-	 *   - If a key exists in `head.props` but does not exist on the object
-	 *     returned by `context(head)`, Regor adds that key to component context.
-	 *   - Existing ref fields can receive incoming values automatically.
-	 *   - Ref-to-ref inputs can be entangled when `head.entangle` is enabled.
-	 * - `false`:
-	 *   - Regor does not auto-apply props.
-	 *   - You fully control mapping manually inside `context(head)`.
+	 *   Regor automatically applies `head.props` to the component context.
+	 *   If a parent input name is missing from the component context, Regor adds it.
+	 *   Isolates the declared component properties,
+	 *   so a component does not accidentally inherit unwanted values from its ancestors.
 	 *
-	 * Use `false` when you need strict custom mapping/validation/transforms
-	 * before any value touches component state.
+	 * - `false`:
+	 *   Regor does not merge `head.props` into the returned context.
+	 *   The component author must map values manually from `head.props`.
+	 *   Disables isolation for declared props.
 	 *
-	 * "Missing key" is always checked against the returned component context object.
+	 * In short:
+	 * - `head.props` = what the parent passed
+	 * - `context(head)` return value = what the component defines
+	 * - `autoProps` = whether Regor should merge the first into the second
 	 *
 	 * Example (auto add):
 	 * ```ts
@@ -321,6 +333,7 @@ export type BivariantAnyRefCall = {
 	bivarianceHack(newValue?: unknown, eventSource?: unknown): unknown;
 }["bivarianceHack"];
 export type AnyRef = BivariantAnyRefCall;
+export type RefOrValue<TValueType> = Ref<TValueType> | SRef<TValueType> | TValueType;
 export type Ref<TValueType> = ((newValue?: RefContent<TValueType> | Ref<RefParam<TValueType>> | SRef<RefContent<TValueType>>, eventSource?: unknown) => RefContent<TValueType>) & {
 	value: RefContent<TValueType>;
 };

package/dist/regor.es2015.cjs.js

@@ -555,24 +555,36 @@ var ComponentHead = class {
      */
     __publicField(this, "ctx");
     /**
-     * Controls whether Regor should automatically apply incoming `head.props`
-     * values to the component context after `context(head)` returns.
+     * Controls whether Regor automatically merges parent-provided component inputs
+     * into the object returned by `context(head)`.
      *
-     * Think of it as "auto wire parent inputs into my component fields".
+     * There are two runtime data sources for a component:
+     *
+     * 1. Parent inputs:
+     *    values passed from the component host, such as `:title="abc"` or
+     *    `:context="{ ... }"`. These are exposed on `head.props`.
+     *
+     * 2. Component context:
+     *    the object returned by `context(head)`. This is the component's own local
+     *    state.
+     *
+     * `autoProps` controls the third step: how those two sources are merged.
      *
      * - `true` (default):
-     *   - If a key exists in `head.props` but does not exist on the object
-     *     returned by `context(head)`, Regor adds that key to component context.
-     *   - Existing ref fields can receive incoming values automatically.
-     *   - Ref-to-ref inputs can be entangled when `head.entangle` is enabled.
-     * - `false`:
-     *   - Regor does not auto-apply props.
-     *   - You fully control mapping manually inside `context(head)`.
+     *   Regor automatically applies `head.props` to the component context.
+     *   If a parent input name is missing from the component context, Regor adds it.
+     *   Isolates the declared component properties,
+     *   so a component does not accidentally inherit unwanted values from its ancestors.
      *
-     * Use `false` when you need strict custom mapping/validation/transforms
-     * before any value touches component state.
+     * - `false`:
+     *   Regor does not merge `head.props` into the returned context.
+     *   The component author must map values manually from `head.props`.
+     *   Disables isolation for declared props.
      *
-     * "Missing key" is always checked against the returned component context object.
+     * In short:
+     * - `head.props` = what the parent passed
+     * - `context(head)` return value = what the component defines
+     * - `autoProps` = whether Regor should merge the first into the second
      *
      * Example (auto add):
      * ```ts
@@ -1681,6 +1693,7 @@ var ComponentBinder = class {
     return isTemplate(node) && node.getAttributeNames().length === 0;
   }
   __unwrapComponents(element) {
+    var _a, _b;
     const binder = this.__binder;
     const parser = binder.__parser;
     const registeredComponents = binder.__config.__components;
@@ -1714,6 +1727,7 @@ var ComponentBinder = class {
       const contextName = binder.__config.__builtInNames.context;
       const contextAliasName = binder.__config.__builtInNames.contextAlias;
       const bindName = binder.__config.__builtInNames.bind;
+      const definedProps = (_b = (_a = registeredComponent.props) == null ? void 0 : _a.map(camelize)) != null ? _b : [];
       const getProps = (component2, capturedContext2) => {
         const props = {};
         const hasContext = component2.hasAttribute(contextName);
@@ -1724,9 +1738,7 @@ var ComponentBinder = class {
           } else if (component2.hasAttribute(contextAliasName)) {
             binder.__bind(contextDirective, component2, contextAliasName);
           }
-          let definedProps = registeredComponent.props;
-          if (!definedProps || definedProps.length === 0) return;
-          definedProps = definedProps.map(camelize);
+          if (definedProps.length === 0) return;
           const definedPropsByLowerCase = new Map(
             definedProps.map((definedProp) => [
               definedProp.toLowerCase(),
@@ -1765,7 +1777,7 @@ var ComponentBinder = class {
       };
       const capturedContext = [...parser.__capture()];
       const createComponentCtx = () => {
-        var _a;
+        var _a2;
         const props = getProps(component, capturedContext);
         const head2 = new ComponentHead(
           props,
@@ -1776,8 +1788,8 @@ var ComponentBinder = class {
           binder.__config.propValidationMode
         );
         const componentCtx2 = useScope(() => {
-          var _a2;
-          return (_a2 = registeredComponent.context(head2)) != null ? _a2 : {};
+          var _a3;
+          return (_a3 = registeredComponent.context(head2)) != null ? _a3 : {};
         }).context;
         if (head2.autoProps) {
           for (const [key, propsValue] of Object.entries(props)) {
@@ -1801,7 +1813,11 @@ var ComponentBinder = class {
               }
             } else componentCtx2[key] = propsValue;
           }
-          (_a = head2.onAutoPropsAssigned) == null ? void 0 : _a.call(head2);
+          for (const key of definedProps) {
+            if (key in componentCtx2) continue;
+            componentCtx2[key] = void 0;
+          }
+          (_a2 = head2.onAutoPropsAssigned) == null ? void 0 : _a2.call(head2);
         }
         return { componentCtx: componentCtx2, head: head2 };
       };
@@ -1810,7 +1826,7 @@ var ComponentBinder = class {
       const len = childNodes.length;
       const isEmptyComponent = component.childNodes.length === 0;
       const expandSlot = (slot) => {
-        var _a;
+        var _a2;
         const parent2 = slot.parentElement;
         let name = slot.name;
         if (isNullOrWhitespace(name)) {
@@ -1843,9 +1859,9 @@ var ComponentBinder = class {
           const unnamedTemplates = component.querySelectorAll(
             "template:not([name])"
           );
-          compTemplate = (_a = [...unnamedTemplates].find(
+          compTemplate = (_a2 = [...unnamedTemplates].find(
             (x) => this.__isDefaultSlotTemplateShortcut(x)
-          )) != null ? _a : null;
+          )) != null ? _a2 : null;
         }
         const createSwitchContext = (childNodes2) => {
           if (!head.enableSwitch) return;