regor 1.3.4 → 1.3.6

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
@@ -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 = createComponent<MyComponent>(template, {
+  context: (head) => ({
+    message: head.props.message,
+    count: ref(0),
+  }),
+  props,
+})
 
 createApp({
   components: { myComponent },
@@ -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
 

package/dist/regor.d.ts

@@ -1,28 +1,134 @@
 // 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(
+ *  `<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 {
@@ -83,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[];
@@ -101,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>;
 }
@@ -198,24 +321,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 +400,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[];