regor 1.7.0 → 1.7.2

package/README.md

@@ -24,7 +24,7 @@ Its template syntax is familiar to Vue users (`r-if`, `r-model`, `r-for`, `r-bin
 />
 ```
 
-- **Flexible Reactivity:** Combine `ref`, `sref`, `batch`, `pause`, `resume`, and `entangle` for explicit state orchestration.
+- **Flexible Reactivity:** Combine `ref`, `cref`, `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.
@@ -340,7 +340,7 @@ Regor is openly inspired by Vue’s concepts (even adopting a similar directive
 ### 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.
+- **Regor:** Provides fine-tuned, manual control. It offers `ref` (deep in-place reactivity), `cref` (copy-first 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
@@ -428,6 +428,7 @@ These directives empower you to create dynamic and interactive user interfaces,
 **Reactivity Functions**
 
 - **`ref`** Creates a deep ref object recursively, modifying the source object in place.
+- **`cref`** Creates a deep ref object recursively from a flattened copy of the source object.
 - **`sref`** Creates a simple ref object from a given value, without nested ref creation.
 - **`isDeepRef`** Returns true if a given ref is created with `ref()` function.
 - **`isRef`** Returns true for any ref, false for non-refs.

package/dist/regor.d.ts

@@ -333,6 +333,7 @@ export type BivariantAnyRefCall = {
 	bivarianceHack(newValue?: unknown, eventSource?: unknown): unknown;
 }["bivarianceHack"];
 export type AnyRef = BivariantAnyRefCall;
+export type CompProp<TValueType> = Ref<TValueType> | SRef<TValueType>;
 export type RefOrValue<TValueType> = Ref<TValueType> | SRef<TValueType> | TValueType;
 export type RefSetterValue<TValueType> = RefContent<TValueType> | Ref<RefParam<TValueType>> | SRef<RefContent<TValueType>>;
 export type RefValueSetterValue<TValueType> = TValueType extends readonly unknown[] ? Ref<RefParam<TValueType>> | SRef<RefContent<TValueType>> : RefSetterValue<TValueType>;
@@ -777,11 +778,21 @@ export declare const observerCount: <TValueType extends AnyRef>(source: TValueTy
 export declare const batch: (updater: () => void) => void;
 export declare const startBatch: () => void;
 export declare const endBatch: () => void;
+/**
+ * Creates a deep ref from a flattened copy of the given value.
+ *
+ * Unlike `ref`, this does not mutate the original object graph during initial
+ * conversion. cref is slower than ref. Use it when you need to preserve original object.
+ */
+export declare function cref<TValueType>(value?: TValueType | RefContent<TValueType> | (TValueType extends Ref<infer V1> ? Ref<RefParam<V1>> : never) | (TValueType extends SRef<infer V2> ? SRef<UnwrapRef<V2>> : never) | RefParam<TValueType> | (TValueType extends Array<infer V1> ? V1[] : never) | null): IsNull<TValueType> extends true ? Ref<unknown> : Ref<RefParam<TValueType>>;
 export declare const entangle: (r1: AnyRef, r2: AnyRef) => StopObserving;
 export declare const isDeepRef: (value: unknown) => value is AnyRef;
 export declare const isRef: (value: unknown) => value is AnyRef;
 export declare const pause: <TValueType extends AnyRef>(source: TValueType) => void;
 /**
+ * The ref function mutates given value in place. Use it with caution.
+ * If you need to create ref without mutating use cref (which is slower).
+ *
  * Converts the given value and its nested properties into ref objects recursively and returns the ref.
  * The returned object's type reflects its nested properties as well.
  *
@@ -839,3 +850,16 @@ export declare function ref<TValueType>(
     object,
 ): IsNull<TValueType> extends true ? Ref<unknown> : Ref<RefParam<TValueType>>
 export declare function ref(value: string, eventSource?: unknown): Ref<string>
+
+export declare function cref(value: string): Ref<string>
+export declare function cref(value: number): Ref<number>
+export declare function cref(value: boolean): Ref<boolean>
+export declare function cref(value: bigint): Ref<bigint>
+export declare function cref(value: symbol): Ref<symbol>
+export declare function cref<TValueType>(
+  value: (TValueType extends RawTypes | readonly unknown[]
+    ? never
+    : RefInit<TValueType>) &
+    object,
+): IsNull<TValueType> extends true ? Ref<unknown> : Ref<RefParam<TValueType>>
+export declare function cref(value: string, eventSource?: unknown): Ref<string>

package/dist/regor.es2015.cjs.js

@@ -69,6 +69,7 @@ __export(index_exports, {
   computeRef: () => computeRef,
   computed: () => computed,
   createApp: () => createApp,
+  cref: () => cref,
   defineComponent: () => defineComponent,
   drainUnbind: () => drainUnbind,
   endBatch: () => endBatch,
@@ -1230,6 +1231,132 @@ var isScope = (value) => {
   return scopeSymbol2 in value;
 };
 
+// src/reactivity/unref.ts
+var unref = (value) => {
+  const anyValue = value;
+  return anyValue != null && anyValue[srefSymbol] > 0 ? anyValue() : anyValue;
+};
+
+// src/directives/attr.ts
+var xlinkNS = "http://www.w3.org/1999/xlink";
+var booleanAttributes = {
+  itemscope: 2,
+  allowfullscreen: 2,
+  formnovalidate: 2,
+  ismap: 2,
+  nomodule: 2,
+  novalidate: 2,
+  readonly: 2,
+  async: 1,
+  autofocus: 1,
+  autoplay: 1,
+  controls: 1,
+  default: 1,
+  defer: 1,
+  disabled: 1,
+  hidden: 1,
+  inert: 1,
+  loop: 1,
+  open: 1,
+  required: 1,
+  reversed: 1,
+  scoped: 1,
+  seamless: 1,
+  checked: 1,
+  muted: 1,
+  multiple: 1,
+  selected: 1
+};
+var updateAttr = (el, values, previousValues, option, previousOption, flags) => {
+  var _a;
+  if (option) {
+    option = unref(option);
+    if (flags && flags.includes("camel")) option = camelize(option);
+    patchAttr(
+      el,
+      option,
+      unref(values[0]),
+      unref(previousOption)
+    );
+    return;
+  }
+  const len = values.length;
+  for (let i = 0; i < len; ++i) {
+    const next = values[i];
+    if (isArray(next)) {
+      const previousKey = unref((_a = previousValues == null ? void 0 : previousValues[i]) == null ? void 0 : _a[0]);
+      const key = unref(next[0]);
+      const value = unref(next[1]);
+      patchAttr(el, key, value, previousKey);
+    } else if (isObject(next)) {
+      for (const item of Object.entries(next)) {
+        const key = item[0];
+        const value = unref(item[1]);
+        const p = unref(previousValues == null ? void 0 : previousValues[i]);
+        const previousKey = p && key in p ? key : void 0;
+        patchAttr(el, key, value, previousKey);
+      }
+    } else {
+      const previousKey = unref(previousValues == null ? void 0 : previousValues[i]);
+      const key = unref(values[i++]);
+      const value = unref(values[i]);
+      patchAttr(el, key, value, previousKey);
+    }
+  }
+};
+var attrDirective = {
+  mount: () => ({
+    update: ({ el, values, previousValues, option, previousOption, flags }) => {
+      updateAttr(
+        el,
+        values,
+        previousValues,
+        option,
+        previousOption,
+        flags
+      );
+    }
+  })
+};
+var patchAttr = (el, key, value, previousKey) => {
+  if (previousKey && previousKey !== key) {
+    el.removeAttribute(previousKey);
+  }
+  if (isNullOrUndefined(key)) {
+    warning(3 /* KeyIsEmpty */, "r-bind", el);
+    return;
+  }
+  if (!isString(key)) {
+    warning(
+      6 /* ErrorLog */,
+      `Attribute key is not string at ${el.outerHTML}`,
+      key
+    );
+    return;
+  }
+  if (key.startsWith("xlink:")) {
+    if (isNullOrUndefined(value)) {
+      el.removeAttributeNS(xlinkNS, key.slice(6, key.length));
+    } else {
+      el.setAttributeNS(xlinkNS, key, value);
+    }
+    return;
+  }
+  if (isNullOrUndefined(value)) {
+    el.removeAttribute(key);
+    return;
+  }
+  if (key in booleanAttributes) {
+    if (toBoolean(value)) {
+      el.setAttribute(key, "");
+    } else {
+      el.removeAttribute(key);
+    }
+    return;
+  }
+  el.setAttribute(key, value);
+};
+
 // src/directives/context.ts
 var contextDirective = {
   collectRefObj: true,
@@ -1968,10 +2095,11 @@ var ComponentBinder = class {
           } else if (attrName === ":style" || attrName === bindStyleName) {
             mergeBinding(":style", bindStyleName, value);
           } else {
-            inheritor.setAttribute(
-              normalizeAttributeName(attrName, binder.__config),
-              value
+            const normalizedName = normalizeAttributeName(
+              attrName,
+              binder.__config
             );
+            patchAttr(inheritor, normalizedName, value);
           }
         };
         for (const { name, value } of inheritedPropAttrs) {
@@ -2313,12 +2441,6 @@ var DynamicBinder = class {
   }
 };
 
-// src/reactivity/unref.ts
-var unref = (value) => {
-  const anyValue = value;
-  return anyValue != null && anyValue[srefSymbol] > 0 ? anyValue() : anyValue;
-};
-
 // src/directives/html.ts
 var updateHtml = (el, values) => {
   const [value, replacer] = values;
@@ -3268,116 +3390,6 @@ var Binder = class {
   }
 };
 
-// src/directives/attr.ts
-var xlinkNS = "http://www.w3.org/1999/xlink";
-var booleanAttributes = {
-  itemscope: 2,
-  allowfullscreen: 2,
-  formnovalidate: 2,
-  ismap: 2,
-  nomodule: 2,
-  novalidate: 2,
-  readonly: 2,
-  async: 1,
-  autofocus: 1,
-  autoplay: 1,
-  controls: 1,
-  default: 1,
-  defer: 1,
-  disabled: 1,
-  hidden: 1,
-  inert: 1,
-  loop: 1,
-  open: 1,
-  required: 1,
-  reversed: 1,
-  scoped: 1,
-  seamless: 1,
-  checked: 1,
-  muted: 1,
-  multiple: 1,
-  selected: 1
-};
-function includeBooleanAttr(value) {
-  return !!value || value === "";
-}
-var updateAttr = (el, values, previousValues, option, previousOption, flags) => {
-  var _a;
-  if (option) {
-    if (flags && flags.includes("camel")) option = camelize(option);
-    patchAttribute(el, option, values[0], previousOption);
-    return;
-  }
-  const len = values.length;
-  for (let i = 0; i < len; ++i) {
-    const next = values[i];
-    if (isArray(next)) {
-      const previousKey = (_a = previousValues == null ? void 0 : previousValues[i]) == null ? void 0 : _a[0];
-      const key = next[0];
-      const value = next[1];
-      patchAttribute(el, key, value, previousKey);
-    } else if (isObject(next)) {
-      for (const item of Object.entries(next)) {
-        const key = item[0];
-        const value = item[1];
-        const p = previousValues == null ? void 0 : previousValues[i];
-        const previousKey = p && key in p ? key : void 0;
-        patchAttribute(el, key, value, previousKey);
-      }
-    } else {
-      const previousKey = previousValues == null ? void 0 : previousValues[i];
-      const key = values[i++];
-      const value = values[i];
-      patchAttribute(el, key, value, previousKey);
-    }
-  }
-};
-var attrDirective = {
-  mount: () => ({
-    update: ({ el, values, previousValues, option, previousOption, flags }) => {
-      updateAttr(
-        el,
-        values,
-        previousValues,
-        option,
-        previousOption,
-        flags
-      );
-    }
-  })
-};
-var patchAttribute = (el, key, value, previousKey) => {
-  if (previousKey && previousKey !== key) {
-    el.removeAttribute(previousKey);
-  }
-  if (isNullOrUndefined(key)) {
-    warning(3 /* KeyIsEmpty */, "r-bind", el);
-    return;
-  }
-  if (!isString(key)) {
-    warning(
-      6 /* ErrorLog */,
-      `Attribute key is not string at ${el.outerHTML}`,
-      key
-    );
-    return;
-  }
-  if (key.startsWith("xlink:")) {
-    if (isNullOrUndefined(value)) {
-      el.removeAttributeNS(xlinkNS, key.slice(6, key.length));
-    } else {
-      el.setAttributeNS(xlinkNS, key, value);
-    }
-    return;
-  }
-  const isBoolean2 = key in booleanAttributes;
-  if (isNullOrUndefined(value) || isBoolean2 && !includeBooleanAttr(value)) {
-    el.removeAttribute(key);
-  } else {
-    el.setAttribute(key, isBoolean2 ? "" : value);
-  }
-};
-
 // src/directives/class.ts
 var updateClass = (el, values, previousValues) => {
   const len = values.length;
@@ -4024,7 +4036,7 @@ var propDirective = {
     }
   })
 };
-function includeBooleanAttr2(value) {
+function includeBooleanAttr(value) {
   return !!value || value === "";
 }
 var patchProp = (el, key, value) => {
@@ -4056,7 +4068,7 @@ var patchProp = (el, key, value) => {
   if (value === "" || value == null) {
     const type = typeof el[key];
     if (type === "boolean") {
-      value = includeBooleanAttr2(value);
+      value = includeBooleanAttr(value);
     } else if (value == null && type === "string") {
       value = "";
       needRemove = true;
@@ -4222,6 +4234,8 @@ var flatten = (reference) => {
 var flattenContent = (value, weakMap = /* @__PURE__ */ new WeakMap()) => {
   if (!value) return value;
   if (!isObject(value)) return value;
+  if (value instanceof Node || value instanceof Date || value instanceof RegExp || value instanceof Promise || value instanceof Error)
+    return value;
   if (isArray(value)) {
     return value.map(flatten);
   }
@@ -4310,6 +4324,11 @@ function ref(value) {
   return result;
 }
 
+// src/reactivity/cref.ts
+function cref(value) {
+  return ref(flatten(value));
+}
+
 // src/app/RegorConfig.ts
 var _RegorConfig = class _RegorConfig {
   constructor(globalContext) {
@@ -4370,6 +4389,7 @@ var _RegorConfig = class _RegorConfig {
       obj[key] = global[key];
     }
     obj.ref = ref;
+    obj.cref = cref;
     obj.sref = sref;
     obj.flatten = flatten;
     return obj;