regor 1.3.5 → 1.3.7

package/README.md

@@ -2,7 +2,9 @@
 
 # Regor
 
-Regor is a powerful UI framework designed to streamline the development of HTML5-based applications for both web and desktop environments. With a template syntax that closely follows Vue.js, transitioning from VueJS to Regor is seamless for developers familiar with Vue.
+Regor is a runtime-first UI framework for teams that want direct DOM control, strong TypeScript ergonomics, and precise reactivity behavior without being forced into a Virtual DOM architecture.
+
+Its template syntax is familiar to Vue users (`r-if`, `r-model`, `r-for`, `r-bind`), but its runtime model is intentionally different: Regor is built for progressive enhancement, mixed-rendering environments, and incremental adoption.
 
 ### [![Published on npm](https://img.shields.io/npm/v/regor.svg)](https://www.npmjs.com/package/regor)
 
@@ -10,9 +12,9 @@ Regor is a powerful UI framework designed to streamline the development of HTML5
 
 ## Key Features
 
-- **Simplicity:** Develop UIs without a Virtual DOM for a more straightforward implementation and easier debugging.
-- **TypeScript:** Enjoy native TypeScript support without workarounds.
-- **No Build Step Required:** Define components in TypeScript using tagged string templates, no build step needed.
+- **No VDOM Layer:** Bind directly to real DOM for transparent runtime behavior and straightforward debugging.
+- **TypeScript-Native:** Use standard TypeScript interfaces, classes, and generics without framework-specific file formats.
+- **No Build Step Required:** Define components in TypeScript using tagged string templates with npm, CDN ESM, or global build workflows.
 - **Secure Evaluation:** Regor's secure JavaScript VM ensures safe runtime compilation. You can enable security policy in your page without removing runtime compilation support.
 
 ```html
@@ -22,9 +24,9 @@ Regor is a powerful UI framework designed to streamline the development of HTML5
 />
 ```
 
-- **Flexible Reactivity:** Empowering developers with a highly flexible reactivity system.
-- **Non-JS SSR:** Bind to the existing DOM without removing already mounted HTML elements, suitable for non-JavaScript server-side rendering.
-- **Reentrance:** Regor supports multiple mountings in the previously mounted area using the same or different app contexts. This enables creating and mounting new directives dynamically.
+- **Flexible Reactivity:** Combine `ref`, `sref`, `batch`, `pause`, `resume`, and `entangle` for explicit state orchestration.
+- **Static-First + Islands:** Bind to existing DOM without removing server-rendered HTML, ideal for progressive enhancement.
+- **Reentrance:** Mount multiple times in already-mounted regions with same or different app contexts.
 - **Compatibility:** Rendered pages are designed for seamless integration with other libraries manipulating the DOM.
 
 ## Documentation
@@ -60,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>
@@ -72,16 +74,13 @@ const template = html`<button @click="count++">
 
 const props = ['message']
 
-const myComponent = createComponent<MyComponent>(
-  template,
-  {
-    context: (head) => ({
-      message: head.props.message,
-      count: ref(0),
-    }),
-    props,
-  },
-)
+const myComponent = defineComponent<MyComponent>(template, {
+  context: (head) => ({
+    message: head.props.message,
+    count: ref(0),
+  }),
+  props,
+})
 
 createApp({
   components: { myComponent },
@@ -121,7 +120,7 @@ Example:
 ```
 
 ```ts
-const tableRow = createComponent(
+const tableRow = defineComponent(
   html`<tr>
     <TableCell :value="row.name" />
     <TableCell :value="row.age" />
@@ -161,7 +160,31 @@ or
 
 ## Comparison with VueJs
 
-Regor shares core functionality with VueJs but differs in implementation, TypeScript support, template evaluation, reactivity, server-side rendering support, compatibility.
+Regor is openly inspired by Vue’s concepts (even adopting a similar directive syntax like r-if / r-model instead of v-if / v-model), but it fundamentally diverges in its implementation. It prioritizes runtime flexibility, build-less environments, and strict TypeScript integration over the Virtual DOM (VDOM) paradigm.
+
+### Architecture and rendering model
+
+- **Vue:** Uses a Virtual DOM. This provides excellent performance for highly dynamic Single Page Applications (SPAs) because Vue calculates diffs in memory before updating the browser. However, it usually requires a compilation step to optimize templates, and hydrating existing server-rendered HTML can be notoriously strict (hydration mismatches).
+- **Regor:** Ditches the VDOM entirely. It binds directly to the actual DOM. Regor explicitly supports Static-first + dynamic islands and "Reentrance." You can mount an application multiple times over already-mounted regions or existing server-rendered HTML without destroying the elements.
+- **Verdict:** Regor is significantly more flexible for integrating into existing applications, multi-page applications (MPAs), or legacy backends.
+
+### Runtime and deployment model
+
+- **Vue:** Commonly paired with a build pipeline for SFCs and tooling depth.
+- **Regor:** Designed to require no build step. You can write standard TypeScript using tagged string templates (e.g., `html` tags for templates) and it will evaluate at runtime. Crucially, Regor features a Secure JavaScript VM for runtime compilation that adheres to strict Content Security Policies (CSP)—a common pain point when using Vue's runtime compiler in enterprise environments.
+- **Verdict:** Regor wins in deployment flexibility and zero-config setups. It respects modern security policies out of the box without demanding a bundler.
+
+### Reactivity control model
+
+- **Vue:** Uses ES6 Proxies for a highly automated, "magical" reactivity system. You update an object, and Vue figures out what to re-render. However, this magic can sometimes abstract away performance bottlenecks, leading to over-rendering if you aren't careful with deep reactivity.
+- **Regor:** Provides fine-tuned, manual control. It offers `ref` (deep reactivity) and `sref` (simple/shallow reactivity without nested observation). Furthermore, Regor provides advanced control APIs like `pause()` and `resume()` to stop a ref's auto-triggers, `entangle()` to sync two refs effortlessly, and `batch()` for precise state grouping.
+- **Verdict:** Vue's reactivity is easier for beginners.. Regor’s reactivity is more flexible and transparent, giving engineers exact tools to orchestrate update semantics and prevent unwanted DOM paints.
+
+### TypeScript ergonomics
+
+- **Vue:** TypeScript support in Vue has improved massively, but it still relies on heavy IDE plugins (Volar) and specialized compilers (vue-tsc) to understand .vue files. The separation between the `<template>` and `<script>` requires tooling to bridge the gap.
+- **Regor:** Offers native TypeScript support without workarounds. Because components and templates are defined using standard TypeScript functions, class-based contexts, and `ComponentHead<T>`, standard TypeScript compilers and IDEs understand 100% of the code immediately.
+- **Verdict:** Regor offers a purer, higher-quality TypeScript experience. It leverages the language itself rather than relying on framework-specific compiler magic to provide type safety.
 
 ## Supported Directives
 
@@ -199,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

@@ -11,8 +11,9 @@
  *
  * Typical usage:
  * ```ts
- * const Card = createComponent({
- *   template: `<article><h3 r-text="title"></h3></article>`,
+ * const Card = defineComponent(
+ *  `<article><h3 r-text="title"></h3></article>`,
+ *  {
  *   props: ['title'],
  *   context(head) {
  *     // read parent values
@@ -188,17 +189,34 @@ export declare interface IRegorContext extends Record<string, unknown> {
 }
 export type IsLazy = (i: number, d: number) => boolean;
 export type IsLazyKey = (key: string, d: number) => boolean;
+export interface DirectiveUpdatePayload {
+	el: HTMLElement;
+	expr: string;
+	values: unknown[];
+	previousValues?: unknown[];
+	option?: unknown;
+	previousOption?: unknown;
+	flags?: string[];
+	parseResult: ParseResult;
+	dynamicOption?: ParseResult;
+}
+export interface MountedDirective {
+	update?: (payload: DirectiveUpdatePayload) => void;
+	unmount?: Unbinder;
+}
 export interface Directive {
 	isLazy?: IsLazy;
 	isLazyKey?: IsLazyKey;
 	collectRefObj?: boolean;
-	/** if once is enabled, the onChange is never triggered.
-	 * The refs in parseResult are still reactive. */
+	/** If once is enabled, updates are not re-triggered after initial mount. */
 	once?: boolean;
-	/** Called on every value change. */
-	onChange?: (el: HTMLElement, values: unknown[], previousValues?: unknown[], option?: unknown, previousOption?: unknown, flags?: string[]) => void;
-	/** Called on binding. Returns unbinder.  */
-	onBind?: (el: HTMLElement, parseResult: ParseResult, expr: string, option?: string, dynamicOption?: ParseResult, flags?: string[]) => Unbinder;
+	/**
+	 * Called once at bind time.
+	 * Returns either:
+	 * - unmount function
+	 * - mounted object with `update` and/or `unmount`
+	 */
+	mount: (payload: DirectiveUpdatePayload) => Unbinder | MountedDirective | void;
 }
 export interface BindData {
 	unbinders: Unbinder[];
@@ -206,9 +224,9 @@ export interface BindData {
 }
 export type Unbinder = () => void;
 export interface ParseResult {
-	value: SRef<unknown[]>;
+	value: () => unknown[];
 	stop: StopObserving;
-	subscribe?: (observer: ObserveCallback<unknown[]>, init?: boolean) => StopObserving;
+	subscribe: (observer: ObserveCallback<unknown[]>, init?: boolean) => StopObserving;
 	refs: Array<AnyRef | undefined>;
 	context: Record<string, unknown>;
 }
@@ -231,36 +249,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;
 }
@@ -302,7 +320,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.
 	 *
@@ -369,7 +387,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>
 	 * ```
@@ -423,21 +441,21 @@ 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.
- * @param template Component template source:
+ * @param template - Component template source:
  * - inline HTML string
  * - `Template` object (`template`, `element`, `selector`, or `json`)
- * @param options Component options (`context`, `props`, `inheritAttrs`, etc.).
+ * @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(
+ * const UserCard = defineComponent(
  *   `<article><h3 r-text="name"></h3></article>`,
  *   {
  *     props: ['name'],
@@ -451,13 +469,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;