regor 1.3.6 → 1.3.8

package/README.md

@@ -62,7 +62,7 @@ HTML:
 Defining component:
 
 ```ts
-import { createApp, createComponent, ref, html, type Ref } from 'regor'
+import { createApp, defineComponent, ref, html, type Ref } from 'regor'
 
 interface MyComponent {
   message: Ref<string>
@@ -74,7 +74,7 @@ const template = html`<button @click="count++">
 
 const props = ['message']
 
-const myComponent = createComponent<MyComponent>(template, {
+const myComponent = defineComponent<MyComponent>(template, {
   context: (head) => ({
     message: head.props.message,
     count: ref(0),
@@ -120,7 +120,7 @@ Example:
 ```
 
 ```ts
-const tableRow = createComponent(
+const tableRow = defineComponent(
   html`<tr>
     <TableCell :value="row.name" />
     <TableCell :value="row.age" />
@@ -222,7 +222,7 @@ These directives empower you to create dynamic and interactive user interfaces,
 **App / Component Template Functions**
 
 - **`createApp`** Similar to Vue's `createApp`, it initializes a Regor application instance.
-- **`createComponent`** Creates a Regor component instance.
+- **`defineComponent`** Creates a Regor component instance.
 - **`toFragment`** Converts a JSON template to a document fragment.
 - **`toJsonTemplate`** Converts a DOM element to a JSON template.
 

package/dist/regor.d.ts

@@ -1,5 +1,6 @@
 // Generated by dts-bundle-generator v9.5.1
 
+export type ContextClass<TValue> = abstract new (...args: never[]) => TValue;
 /**
  * Runtime metadata passed to a component's `context(head)` factory.
  *
@@ -11,7 +12,7 @@
  *
  * Typical usage:
  * ```ts
- * const Card = createComponent(
+ * const Card = defineComponent(
  *  `<article><h3 r-text="title"></h3></article>`,
  *  {
  *   props: ['title'],
@@ -125,6 +126,50 @@ export declare class ComponentHead<TContext extends IRegorContext | object = IRe
 	 * ```
 	 */
 	emit: (event: string, args: Record<string, unknown>) => void;
+	/**
+	 * Finds a parent context instance by constructor type from the captured
+	 * context stack.
+	 *
+	 * Matching uses `instanceof` and respects stack order.
+	 *
+	 * `occurrence` selects which matching instance to return:
+	 * - `0` (default): first match
+	 * - `1`: second match
+	 * - `2`: third match
+	 * - negative values: always `undefined`
+	 *
+	 * Example:
+	 * ```ts
+	 * // stack: [RootCtx, ParentCtx, ParentCtx]
+	 * head.findContext(ParentCtx)    // first ParentCtx
+	 * head.findContext(ParentCtx, 1) // second ParentCtx
+	 * ```
+	 *
+	 * @param constructor - Class constructor used for `instanceof` matching.
+	 * @param occurrence - Zero-based index of the matching instance to return.
+	 * @returns The matching parent context instance, or `undefined` when not found.
+	 */
+	findContext<TValue>(constructor: ContextClass<TValue>, occurrence?: number): TValue | undefined;
+	/**
+	 * Returns a parent context instance by constructor type from the captured
+	 * context stack.
+	 *
+	 * The stack is scanned in order and each entry is checked with `instanceof`.
+	 * `occurrence` is zero-based (`0` = first match, `1` = second match, ...).
+	 * If no instance exists at the requested occurrence, this method throws.
+	 *
+	 * Example:
+	 * ```ts
+	 * const auth = head.requireContext(AuthContext)     // first AuthContext
+	 * const outer = head.requireContext(LayoutCtx, 1)   // second LayoutCtx
+	 * ```
+	 *
+	 * @param constructor - Class constructor used for `instanceof` matching.
+	 * @param occurrence - Zero-based index of the instance to return.
+	 * @returns The parent context instance at the requested occurrence.
+	 * @throws Error when no matching instance exists at the requested occurrence.
+	 */
+	requireContext<TValue>(constructor: ContextClass<TValue>, occurrence?: number): TValue;
 	/**
 	 * Unmounts this component instance by removing nodes between `start` and `end`
 	 * and calling unmount lifecycle handlers for captured contexts.
@@ -249,36 +294,36 @@ export interface JSONTemplate {
  * - Define either 'selector' or 'element' to specify the mounting point.
  * - Optionally, 'html' or 'json' can be defined to override the inner HTML of the mounting point.
  * - If neither 'html' nor 'json' template is defined, the mounting point's inner HTML remains unchanged.
- * If used with 'createComponent':
+ * If used with 'defineComponent':
  * - Define only one option: 'selector', 'element', 'html', or 'json'. The single option defines the component's HTML template.
  */
 export interface Template {
 	/**
 	 * If used with 'createApp', specifies the target root element for mounting the application.
-	 * If used with 'createComponent', identifies the component template using a selector.
+	 * If used with 'defineComponent', identifies the component template using a selector.
 	 */
 	selector?: string;
 	/**
 	 * If used with 'createApp', represents the actual DOM element where the app will be mounted.
-	 * If used with 'createComponent', specifies the component template using an element.
+	 * If used with 'defineComponent', specifies the component template using an element.
 	 * Use this property if you already have a reference to the target element.
 	 */
 	element?: Node;
 	/**
 	 *  If used with 'createApp', HTML template string that will replace the content of the root element defined by 'selector' or 'element'.
-	 * If used with 'createComponent', this template populates the content of the component.
+	 * If used with 'defineComponent', this template populates the content of the component.
 	 */
 	template?: string;
 	/**
 	 * JSON-based template representation, enabling rendering within secure contexts.
 	 * Can be a single JSONTemplate object or an array of JSONTemplate objects.
-	 * This property is applicable to both 'createApp' and 'createComponent'.
+	 * This property is applicable to both 'createApp' and 'defineComponent'.
 	 */
 	json?: JSONTemplate | JSONTemplate[];
 	/**
 	 * Indicates whether the component template contains SVG elements.
 	 * Enable this flag if SVG content is present to ensure proper rendering.
-	 * This property is applicable to both 'createApp' and 'createComponent'.
+	 * This property is applicable to both 'createApp' and 'defineComponent'.
 	 */
 	isSVG?: boolean;
 }
@@ -320,7 +365,7 @@ export interface Component<TContext extends IRegorContext | object = IRegorConte
 }
 export type OnMounted = () => void;
 export type OnUnmounted = () => void;
-export interface CreateComponentOptions<TContext extends IRegorContext | object = IRegorContext> {
+export interface DefineComponentOptions<TContext extends IRegorContext | object = IRegorContext> {
 	/**
 	 * Enables interpolation transform inside the component template.
 	 *
@@ -387,7 +432,7 @@ export interface CreateComponentOptions<TContext extends IRegorContext | object
 	 *
 	 * Example:
 	 * ```ts
-	 * const Card = createComponent('<div>...</div>', { defaultName: 'CardView' })
+	 * const Card = defineComponent('<div>...</div>', { defaultName: 'CardView' })
 	 * cfg.addComponent(Card)
 	 * // usable as <CardView></CardView>
 	 * ```
@@ -441,7 +486,7 @@ export declare const createApp: <TRegorContext extends IRegorContext | object =
 /**
  * Creates a reusable Regor component definition.
  *
- * `createComponent` prepares a template once, then Regor clones/binds it for each
+ * `defineComponent` prepares a template once, then Regor clones/binds it for each
  * component instance in the app.
  *
  * @typeParam TContext - Component context type.
@@ -455,7 +500,7 @@ export declare const createApp: <TRegorContext extends IRegorContext | object =
  *
  * @example
  * ```ts
- * const UserCard = createComponent(
+ * const UserCard = defineComponent(
  *   `<article><h3 r-text="name"></h3></article>`,
  *   {
  *     props: ['name'],
@@ -469,13 +514,13 @@ export declare const createApp: <TRegorContext extends IRegorContext | object =
  * @example
  * ```ts
  * // Props shorthand:
- * const CounterLabel = createComponent(
+ * const CounterLabel = defineComponent(
  *   `<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 defineComponent: <TContext extends IRegorContext | object = IRegorContext>(template: Template | string, options?: DefineComponentOptions<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[];
 export declare const addUnbinder: (node: Node, unbinder: Unbinder) => void;

package/dist/regor.es2015.cjs.js

@@ -68,7 +68,7 @@ __export(index_exports, {
   computeRef: () => computeRef,
   computed: () => computed,
   createApp: () => createApp,
-  createComponent: () => createComponent,
+  defineComponent: () => defineComponent,
   drainUnbind: () => drainUnbind,
   endBatch: () => endBatch,
   entangle: () => entangle,
@@ -357,6 +357,66 @@ var ComponentHead = class {
     this.start = start;
     this.end = end;
   }
+  /**
+   * Finds a parent context instance by constructor type from the captured
+   * context stack.
+   *
+   * Matching uses `instanceof` and respects stack order.
+   *
+   * `occurrence` selects which matching instance to return:
+   * - `0` (default): first match
+   * - `1`: second match
+   * - `2`: third match
+   * - negative values: always `undefined`
+   *
+   * Example:
+   * ```ts
+   * // stack: [RootCtx, ParentCtx, ParentCtx]
+   * head.findContext(ParentCtx)    // first ParentCtx
+   * head.findContext(ParentCtx, 1) // second ParentCtx
+   * ```
+   *
+   * @param constructor - Class constructor used for `instanceof` matching.
+   * @param occurrence - Zero-based index of the matching instance to return.
+   * @returns The matching parent context instance, or `undefined` when not found.
+   */
+  findContext(constructor, occurrence = 0) {
+    var _a;
+    if (occurrence < 0) return void 0;
+    let current = 0;
+    for (const value of (_a = this.ctx) != null ? _a : []) {
+      if (!(value instanceof constructor)) continue;
+      if (current === occurrence) return value;
+      ++current;
+    }
+    return void 0;
+  }
+  /**
+   * Returns a parent context instance by constructor type from the captured
+   * context stack.
+   *
+   * The stack is scanned in order and each entry is checked with `instanceof`.
+   * `occurrence` is zero-based (`0` = first match, `1` = second match, ...).
+   * If no instance exists at the requested occurrence, this method throws.
+   *
+   * Example:
+   * ```ts
+   * const auth = head.requireContext(AuthContext)     // first AuthContext
+   * const outer = head.requireContext(LayoutCtx, 1)   // second LayoutCtx
+   * ```
+   *
+   * @param constructor - Class constructor used for `instanceof` matching.
+   * @param occurrence - Zero-based index of the instance to return.
+   * @returns The parent context instance at the requested occurrence.
+   * @throws Error when no matching instance exists at the requested occurrence.
+   */
+  requireContext(constructor, occurrence = 0) {
+    const value = this.findContext(constructor, occurrence);
+    if (value !== void 0) return value;
+    throw new Error(
+      `${constructor} was not found in the context stack at occurrence ${occurrence}.`
+    );
+  }
   /**
    * Unmounts this component instance by removing nodes between `start` and `end`
    * and calling unmount lifecycle handlers for captured contexts.
@@ -5923,8 +5983,8 @@ var toJsonTemplate = (node) => {
   return json;
 };
 
-// src/app/createComponent.ts
-var createComponent = (template, options = {}) => {
+// src/app/defineComponent.ts
+var defineComponent = (template, options = {}) => {
   var _a, _b, _c, _d, _e, _f;
   if (isArray(options)) options = { props: options };
   if (isString(template)) template = { template };