regor 1.3.4 → 1.3.5

package/dist/regor.d.ts

@@ -1,28 +1,133 @@
 // Generated by dts-bundle-generator v9.5.1
 
+/**
+ * Runtime metadata passed to a component's `context(head)` factory.
+ *
+ * `ComponentHead` gives component authors controlled access to:
+ * - incoming values from parent (`head.props`)
+ * - component mount boundaries (`head.start`, `head.end`)
+ * - parent-context event bridge (`head.emit(...)`)
+ * - optional behavior toggles (`head.autoProps`, `head.entangle`, `head.enableSwitch`)
+ *
+ * Typical usage:
+ * ```ts
+ * const Card = createComponent({
+ *   template: `<article><h3 r-text="title"></h3></article>`,
+ *   props: ['title'],
+ *   context(head) {
+ *     // read parent values
+ *     const initialTitle = head.props.title
+ *
+ *     // optional event to parent/listener
+ *     const close = () => head.emit('close', { reason: 'user' })
+ *
+ *     return { title: initialTitle, close }
+ *   },
+ * })
+ * ```
+ */
 export declare class ComponentHead<TContext extends IRegorContext | object = IRegorContext> {
+	/**
+	 * Values provided by parent for this component instance.
+	 *
+	 * Sources:
+	 * - declared props via `props: ['foo']` + attribute binding (`:foo="..."`)
+	 * - object binding via `:context="{ ... }"`
+	 */
 	props: TContext;
+	/**
+	 * Comment node that marks the beginning of this mounted component block.
+	 * Advanced use only.
+	 */
 	start: Comment;
+	/**
+	 * Comment node that marks the end of this mounted component block.
+	 * Advanced use only.
+	 */
 	end: Comment;
+	/**
+	 * Captured context chain used by this component instance.
+	 * Used internally for lifecycle/unmount behavior.
+	 */
 	ctx: IRegorContext[];
-	/** Automatically assigns properties defined in the :props binding to the component context when enabled. If disabled, props should be manually assigned using head.props.
-	 * Default: true */
+	/**
+	 * Controls whether Regor should automatically apply incoming `head.props`
+	 * values to the component context after `context(head)` returns.
+	 *
+	 * Think of it as "auto wire parent inputs into my component fields".
+	 *
+	 * - `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)`.
+	 *
+	 * Use `false` when you need strict custom mapping/validation/transforms
+	 * before any value touches component state.
+	 *
+	 * "Missing key" is always checked against the returned component context object.
+	 *
+	 * Example (auto add):
+	 * ```ts
+	 * // Parent passes: :context="{ badge: 'pro' }"
+	 * context(head) {
+	 *   // Returned context has no "badge" key:
+	 *   return { name: ref('Ada') }
+	 * }
+	 * // Resulting component context becomes:
+	 * // { name: ref('Ada'), badge: 'pro' }
+	 * ```
+	 *
+	 * Example:
+	 * ```ts
+	 * context(head) {
+	 *   head.autoProps = false
+	 *   const title = ref((head.props.title as string) ?? 'Untitled')
+	 *   return { title }
+	 * }
+	 * ```
+	 */
 	autoProps: boolean;
-	/** When both autoProps and entangle are enabled,
-	 * the refs defined in the component context (without using head.props)
-	 * become entangled with the head.props refs. (parent[ref] `<==>` component[ref])
-	 * This means that changes to parent[ref] reflect in component[ref], and vice versa.
-	 * Disable this flag to isolate refs created within the component context.
-	 * Default: true */
+	/**
+	 * Enables two-way ref linking between incoming props and component context
+	 * when `autoProps` is also enabled.
+	 *
+	 * - `true` (default): parent and component refs stay synchronized.
+	 * - `false`: component keeps local ref isolation.
+	 */
 	entangle: boolean;
-	/** enables slot context switch to the parent
-	 * Default: false */
+	/**
+	 * Enables slot context switch behavior for advanced slot scenarios.
+	 * Default: `false`.
+	 */
 	enableSwitch: boolean;
-	/** A callback invoked after auto props get assigned to the component context. */
+	/**
+	 * Optional hook called after automatic prop assignment completes.
+	 * Useful when post-assignment normalization is needed.
+	 */
 	onAutoPropsAssigned?: () => void;
 	constructor(props: TContext, element: Element, ctx: IRegorContext[], start: Comment, end: Comment);
-	/** use arrow syntax to be called without using head.emit.bind(head) in Binder.ts. */
+	/**
+	 * Emits a custom DOM event from the component host element.
+	 *
+	 * Example:
+	 * ```ts
+	 * head.emit('saved', { id: 42 })
+	 * ```
+	 *
+	 * Parent markup can listen via regular event binding:
+	 * ```html
+	 * <MyComp @saved="onSaved"></MyComp>
+	 * ```
+	 */
 	emit: (event: string, args: Record<string, unknown>) => void;
+	/**
+	 * Unmounts this component instance by removing nodes between `start` and `end`
+	 * and calling unmount lifecycle handlers for captured contexts.
+	 */
 	unmount(): void;
 }
 export declare class RegorConfig {
@@ -198,24 +303,77 @@ export interface Component<TContext extends IRegorContext | object = IRegorConte
 export type OnMounted = () => void;
 export type OnUnmounted = () => void;
 export interface CreateComponentOptions<TContext extends IRegorContext | object = IRegorContext> {
+	/**
+	 * Enables interpolation transform inside the component template.
+	 *
+	 * When `true` (default), text like `{{ expr }}` / `[[ expr ]]` is converted
+	 * to directive bindings during component template preparation.
+	 *
+	 * Set to `false` when the template should keep interpolation markers as plain text.
+	 */
 	useInterpolation?: boolean;
+	/**
+	 * Regor configuration used while creating this component.
+	 *
+	 * Useful when the component must use a specific config instance
+	 * (custom directives, global context, registered components).
+	 */
 	config?: RegorConfig;
 	/**
-	 * A function that defines the Regor context for the component.
+	 * Factory that creates the component context.
+	 *
+	 * `head` contains incoming parent-bound values (`head.props`) and mount controls.
+	 *
+	 * Example:
+	 * ```ts
+	 * context(head) {
+	 *   return {
+	 *     title: head.props.title ?? 'Untitled',
+	 *     close: () => head.emit('close', { reason: 'user' }),
+	 *   }
+	 * }
+	 * ```
 	 */
 	context?(head: ComponentHead<TContext>): TContext;
+	/**
+	 * Controls attribute fallthrough from component host to component root.
+	 *
+	 * - `true` (default): non-prop attributes like `class`, `style`, `id` are inherited.
+	 * - `false`: host attributes are not forwarded automatically.
+	 */
 	inheritAttrs?: boolean;
 	/**
-	 * Notes on component props:
-	 * The props defined in the props list can be used with :foo or r-bind:foo syntax.
-	 * `<MyComponent :prop-kebab-1="1" r-bind:prop-kebab-2="x ? 1 : 0" :props="{ propFoo3: true, propFoo4: x ? 'a' : 'b' }></MyComponent>`
-	 * It is required to define prop-kebab-1 and prop-kebab-2 in the props list camelized.
-	 * It is not required to define propFoo3 and propFoo4 in the props list because it uses :props binding. :props binding enables binding to arbitrary component properties regardless they are explicitly defined in props list.
+	 * Declares prop names accepted via single-prop binding (`:foo`, `r-bind:foo`, `.foo`).
+	 *
+	 * Use camelCase names in this list.
+	 * Kebab-case template attributes are matched to camelCase automatically.
+	 *
+	 * Example:
+	 * ```ts
+	 * props: ['userName', 'isActive']
+	 * ```
+	 * ```html
+	 * <UserCard :user-name="name" r-bind:is-active="enabled"></UserCard>
+	 * ```
+	 *
+	 * Note:
+	 * `:context="{ ... }"` can assign arbitrary component fields even when
+	 * they are not declared in `props`.
 	 */
 	props?: string[];
-	/** The default name of the component.
-	 * It is required if the component is registered using the Regor config.addComponent method.
-	 * It is not required if the component being registered in app or component scope. */
+	/**
+	 * Default component name used by global registration (`config.addComponent(...)`).
+	 *
+	 * Required for global registration.
+	 * Optional when component is provided via app/component local `components` context.
+	 *
+	 * Example:
+	 * ```ts
+	 * const Card = createComponent('<div>...</div>', { defaultName: 'CardView' })
+	 * cfg.addComponent(Card)
+	 * // usable as <CardView></CardView>
+	 * ```
+	 */
 	defaultName?: string;
 }
 export interface Scope<TRegorContext> {
@@ -224,7 +382,81 @@ export interface Scope<TRegorContext> {
 	[ScopeSymbol]: true;
 	[key: string]: unknown;
 }
+/**
+ * Creates and mounts a Regor application on an existing DOM root.
+ *
+ * The app can bind directly to existing markup or replace root content with
+ * a provided `template`/`json` before binding.
+ *
+ * @typeParam TRegorContext - Root app context type.
+ * @param context - App context object (or `useScope(... )` result).
+ * @param template - Mount target + optional template source.
+ * @param config  -Optional Regor config. Uses `RegorConfig.getDefault()` when omitted.
+ *
+ * @returns App handle with:
+ * - `context`: the same context instance used for binding
+ * - `unbind()`: removes Regor observers/listeners from the root
+ * - `unmount()`: removes the root element from DOM
+ *
+ * @example
+ * ```ts
+ * const root = document.getElementById('app')!
+ * const app = createApp(
+ *   { count: ref(0) },
+ *   {
+ *     element: root,
+ *     template: `<button @click="count(count()+1)" r-text="count"></button>`,
+ *   },
+ * )
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Bind against existing markup without replacing it.
+ * const app = createApp(
+ *   { user: ref('Ada') },
+ *   { selector: '#header-island' },
+ * )
+ * ```
+ */
 export declare const createApp: <TRegorContext extends IRegorContext | object = IRegorContext>(context: TRegorContext | Scope<TRegorContext>, template?: Template | string, config?: RegorConfig) => App<TRegorContext>;
+/**
+ * Creates a reusable Regor component definition.
+ *
+ * `createComponent` prepares a template once, then Regor clones/binds it for each
+ * component instance in the app.
+ *
+ * @typeParam TContext - Component context type.
+ * @param template Component template source:
+ * - inline HTML string
+ * - `Template` object (`template`, `element`, `selector`, or `json`)
+ * @param options Component options (`context`, `props`, `inheritAttrs`, etc.).
+ * You can also pass `string[]` as shorthand for `props`.
+ *
+ * @returns Component definition usable in app/component `components`.
+ *
+ * @example
+ * ```ts
+ * const UserCard = createComponent(
+ *   `<article><h3 r-text="name"></h3></article>`,
+ *   {
+ *     props: ['name'],
+ *     context: (head) => ({
+ *       name: head.props.name ?? 'Anonymous',
+ *     }),
+ *   },
+ * )
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Props shorthand:
+ * const CounterLabel = createComponent(
+ *   `<span r-text="value"></span>`,
+ *   ['value'],
+ * )
+ * ```
+ */
 export declare const createComponent: <TContext extends IRegorContext | object = IRegorContext>(template: Template | string, options?: CreateComponentOptions<TContext> | string[]) => Component<TContext>;
 export declare const toFragment: (json: JSONTemplate | JSONTemplate[], isSVG?: boolean, config?: RegorConfig) => DocumentFragment;
 export declare const toJsonTemplate: (node: Element | Element[]) => JSONTemplate | JSONTemplate[];

package/dist/regor.es2015.cjs.js

@@ -247,30 +247,105 @@ var callUnmounted = (context) => {
 // src/app/ComponentHead.ts
 var ComponentHead = class {
   constructor(props, element, ctx, start, end) {
+    /**
+     * Values provided by parent for this component instance.
+     *
+     * Sources:
+     * - declared props via `props: ['foo']` + attribute binding (`:foo="..."`)
+     * - object binding via `:context="{ ... }"`
+     */
     __publicField(this, "props");
+    /**
+     * Comment node that marks the beginning of this mounted component block.
+     * Advanced use only.
+     */
     __publicField(this, "start");
+    /**
+     * Comment node that marks the end of this mounted component block.
+     * Advanced use only.
+     */
     __publicField(this, "end");
+    /**
+     * Captured context chain used by this component instance.
+     * Used internally for lifecycle/unmount behavior.
+     */
     __publicField(this, "ctx");
-    /** Automatically assigns properties defined in the :props binding to the component context when enabled. If disabled, props should be manually assigned using head.props.
-     * Default: true */
+    /**
+     * Controls whether Regor should automatically apply incoming `head.props`
+     * values to the component context after `context(head)` returns.
+     *
+     * Think of it as "auto wire parent inputs into my component fields".
+     *
+     * - `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)`.
+     *
+     * Use `false` when you need strict custom mapping/validation/transforms
+     * before any value touches component state.
+     *
+     * "Missing key" is always checked against the returned component context object.
+     *
+     * Example (auto add):
+     * ```ts
+     * // Parent passes: :context="{ badge: 'pro' }"
+     * context(head) {
+     *   // Returned context has no "badge" key:
+     *   return { name: ref('Ada') }
+     * }
+     * // Resulting component context becomes:
+     * // { name: ref('Ada'), badge: 'pro' }
+     * ```
+     *
+     * Example:
+     * ```ts
+     * context(head) {
+     *   head.autoProps = false
+     *   const title = ref((head.props.title as string) ?? 'Untitled')
+     *   return { title }
+     * }
+     * ```
+     */
     __publicField(this, "autoProps", true);
-    /** When both autoProps and entangle are enabled,
-     * the refs defined in the component context (without using head.props)
-     * become entangled with the head.props refs. (parent[ref] `<==>` component[ref])
-     * This means that changes to parent[ref] reflect in component[ref], and vice versa.
-     * Disable this flag to isolate refs created within the component context.
-     * Default: true */
+    /**
+     * Enables two-way ref linking between incoming props and component context
+     * when `autoProps` is also enabled.
+     *
+     * - `true` (default): parent and component refs stay synchronized.
+     * - `false`: component keeps local ref isolation.
+     */
     __publicField(this, "entangle", true);
-    /** enables slot context switch to the parent
-     * Default: false */
+    /**
+     * Enables slot context switch behavior for advanced slot scenarios.
+     * Default: `false`.
+     */
     __publicField(this, "enableSwitch", false);
-    /** A callback invoked after auto props get assigned to the component context. */
+    /**
+     * Optional hook called after automatic prop assignment completes.
+     * Useful when post-assignment normalization is needed.
+     */
     __publicField(this, "onAutoPropsAssigned");
     /**
      * @internal
      */
     __publicField(this, "__element");
-    /** use arrow syntax to be called without using head.emit.bind(head) in Binder.ts. */
+    /**
+     * Emits a custom DOM event from the component host element.
+     *
+     * Example:
+     * ```ts
+     * head.emit('saved', { id: 42 })
+     * ```
+     *
+     * Parent markup can listen via regular event binding:
+     * ```html
+     * <MyComp @saved="onSaved"></MyComp>
+     * ```
+     */
     __publicField(this, "emit", (event, args) => {
       this.__element.dispatchEvent(
         new CustomEvent(event, { detail: args })
@@ -282,6 +357,10 @@ var ComponentHead = class {
     this.start = start;
     this.end = end;
   }
+  /**
+   * Unmounts this component instance by removing nodes between `start` and `end`
+   * and calling unmount lifecycle handlers for captured contexts.
+   */
   unmount() {
     let next = this.start.nextSibling;
     const end = this.end;
@@ -763,8 +842,8 @@ var observe = (source, observer, init, trackUnmount = true) => {
   return stop;
 };
 
-// src/directives/props.ts
-var propsDirective = {
+// src/directives/context.ts
+var contextDirective = {
   collectRefObj: true,
   onBind: (_, parseResult) => {
     const stopObserving = observe(
@@ -794,34 +873,6 @@ var propsDirective = {
   }
 };
 
-// src/directives/props-once.ts
-var propsOnceDirective = {
-  collectRefObj: true,
-  once: true,
-  onBind: (_, parseResult) => {
-    const value = parseResult.value();
-    const ctx = parseResult.context;
-    const obj = value[0];
-    if (!isObject(obj)) {
-      return () => {
-      };
-    }
-    for (const item of Object.entries(obj)) {
-      const key = item[0];
-      const value2 = item[1];
-      const ctxKey = ctx[key];
-      if (ctxKey === value2) continue;
-      if (isRef(ctxKey)) {
-        ctxKey(value2);
-      } else {
-        ctx[key] = value2;
-      }
-    }
-    return () => {
-    };
-  }
-};
-
 // src/reactivity/entangle.ts
 var entangle = (r1, r2) => {
   if (r1 === r2) return () => {
@@ -1284,18 +1335,19 @@ var ComponentBinder = class {
       const endOfComponent = new Comment(" end component: " + component.tagName);
       componentParent.insertBefore(startOfComponent, component);
       component.remove();
-      const propsName = binder.__config.__builtInNames.props;
-      const propsOnceName = binder.__config.__builtInNames.propsOnce;
+      const contextName = binder.__config.__builtInNames.context;
+      const contextAliasName = binder.__config.__builtInNames.contextAlias;
       const bindName = binder.__config.__builtInNames.bind;
       const getProps = (component2, capturedContext2) => {
         const props = {};
-        const hasProps = component2.hasAttribute(propsName);
-        const hasPropsOnce = component2.hasAttribute(propsOnceName);
+        const hasContext = component2.hasAttribute(contextName);
         parser.__scoped(capturedContext2, () => {
           parser.__push(props);
-          if (hasProps) binder.__bind(propsDirective, component2, propsName);
-          if (hasPropsOnce)
-            binder.__bind(propsOnceDirective, component2, propsOnceName);
+          if (hasContext) {
+            binder.__bind(contextDirective, component2, contextName);
+          } else if (component2.hasAttribute(contextAliasName)) {
+            binder.__bind(contextDirective, component2, contextAliasName);
+          }
           let definedProps = registeredComponent.props;
           if (!definedProps || definedProps.length === 0) return;
           definedProps = definedProps.map(camelize);
@@ -1352,8 +1404,20 @@ var ComponentBinder = class {
             if (key in componentCtx2) {
               const compValue = componentCtx2[key];
               if (compValue === propsValue) continue;
-              if (head2.entangle && isRef(compValue) && isRef(propsValue)) {
-                addUnbinder(startOfComponent, entangle(propsValue, compValue));
+              if (isRef(compValue)) {
+                if (isRef(propsValue)) {
+                  if (head2.entangle) {
+                    addUnbinder(
+                      startOfComponent,
+                      entangle(propsValue, compValue)
+                    );
+                  } else {
+                    compValue(propsValue());
+                  }
+                } else {
+                  compValue(propsValue);
+                }
+                continue;
               }
             } else componentCtx2[key] = propsValue;
           }
@@ -1464,7 +1528,8 @@ var ComponentBinder = class {
         const inheritor = inheritorChildNodes[0];
         if (!inheritor) return;
         for (const attrName of component.getAttributeNames()) {
-          if (attrName === propsName || attrName === propsOnceName) continue;
+          if (attrName === contextName || attrName === contextAliasName)
+            continue;
           const value = component.getAttribute(attrName);
           if (attrName === "class") {
             inheritor.classList.add(...value.split(" "));
@@ -3347,6 +3412,7 @@ var _RegorConfig = class _RegorConfig {
       [`${prefix}show`]: showDirective,
       [`${prefix}model`]: modelDirective,
       ":style": styleDirective,
+      [`${prefix}style`]: styleDirective,
       [`${prefix}bind:style`]: styleDirective,
       ":class": classDirective,
       [`${prefix}bind:class`]: classDirective,
@@ -3362,8 +3428,8 @@ var _RegorConfig = class _RegorConfig {
       pre: `${prefix}pre`,
       inherit: `${prefix}inherit`,
       text: `${prefix}text`,
-      props: ":props",
-      propsOnce: ":props-once",
+      context: ":context",
+      contextAlias: `${prefix}context`,
       bind: `${prefix}bind`,
       on: `${prefix}on`,
       keyBind: ":key",