ivue 2.4.0 → 2.6.0

package/lib/nestedProps.ts

@@ -0,0 +1,126 @@
+/**
+ * `nestedProps(props, defaults)` — fill a nested object prop from its
+ * defaults, in place, so the class reads complete props at every depth.
+ *
+ * Vue resolves a prop's default only when the prop is ABSENT: pass
+ * `{ wheel: { gain: 2 } }` for a prop whose default is
+ * `{ wheel: { gain: 1, follow: 0.1 }, touch: { … } }` and the component
+ * receives exactly the object it was passed — `follow` and `touch` are
+ * gone. `propsWithDefaults` decides what the default IS and clones it per
+ * instance; it cannot reach inside a supplied object. The fill is possible
+ * at all because the defaults are a value the class owns — a compiler-only
+ * default has nothing to fill from.
+ *
+ * The semantics are lodash's `defaultsDeep` with arrays taken whole: for
+ * every prop whose value and default are both plain objects, each leaf the
+ * supplied object lacks is written into it from the default, recursively;
+ * a leaf it has is kept. Missing plain-object and array defaults are copied
+ * recursively so instances never share those mutable containers. Arrays
+ * are never merged; class instances and functions retain their identity. Vue's
+ * props proxy is shallow, so the nested objects are the parent's own and
+ * are written directly; the props object itself is untouched and returned.
+ *
+ * Call it once, at the seam where props enter the class:
+ *
+ *   constructor(props: Scroller.Props, public emit: Scroller.Emits) {
+ *     this.props = nestedProps(props, this.self.propsDefaults);
+ *   }
+ *
+ * The parent passes a stable object: a constant inline literal (Vue hoists
+ * it), a `ref`'s value, a store field. An object built anew on every
+ * parent render is a new, unfilled object each time.
+ *
+ * `customCloner` is the same policy knob `propsWithDefaults` has: it copies
+ * each default branch written into the props. The default, `clone`, copies
+ * plain containers and keeps callbacks, constructors and opaque objects by
+ * reference, so no two instances share a mutable default. Pass
+ * `structuredClone` when `Date`, `Map` or `Set` defaults need their own
+ * copies; pass the identity, `value => value`, only when the caller owns
+ * every default it passes — a fresh tree per instance, never a shared one.
+ *
+ * `NestedPartial<T>` is the matching declaration for the prop's type — the
+ * shape an author may pass — and `NestedProps<P, D>` the type of the
+ * filled props, where every key both sides carry as an object is complete.
+ *
+ * Ships from `ivue/extras` (not the reactive core) so the primary `ivue`
+ * entry stays minimal.
+ */
+
+import { clone } from './clone';
+
+/** Every key optional at every plain-object depth; arrays stay whole. */
+export type NestedPartial<T> = T extends readonly unknown[]
+  ? T
+  : T extends object
+    ? { [K in keyof T]?: NestedPartial<T[K]> }
+    : T;
+
+/** The filled props' type: a key both sides carry as a plain object is complete. */
+export type NestedProps<P, D> = {
+  [K in keyof P as K extends keyof D ? K : never]-?: NestedLeaf<
+    NonNullable<P[K]>,
+    D[K & keyof D]
+  >;
+} & {
+  [K in keyof P as K extends keyof D ? never : K]: P[K];
+};
+
+/** A value the fill takes whole: not a plain container. */
+type Opaque = Date | RegExp | Map<unknown, unknown> | Set<unknown> | ((...args: never[]) => unknown);
+
+type NestedLeaf<V, D> = V extends readonly unknown[]
+  ? V
+  : V extends Opaque
+    ? V
+    : V extends object
+    ? D extends readonly unknown[]
+      ? V
+      : D extends object
+        ? NestedProps<V, D>
+        : V
+    : V;
+
+type PlainObject = Record<PropertyKey, unknown>;
+
+/** A plain object — an object literal, `Object.create(null)`, or a reactive
+ *  proxy over either; not an array, a class instance or a function. A
+ *  `constructor` check, no prototype walk. */
+function isPlain(value: unknown): value is PlainObject {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    ((value as PlainObject).constructor === Object ||
+      (value as PlainObject).constructor === undefined)
+  );
+}
+
+/** Write every leaf `target` lacks from `defaults`, recursively; keep what
+ *  it has. `for…in` over the defaults: plain objects have no enumerable
+ *  prototype keys. */
+function fill(target: PlainObject, defaults: PlainObject, copy: (value: unknown) => unknown) {
+  for (const key in defaults) {
+    const value = target[key];
+    const fallback = defaults[key];
+    if (value === undefined) target[key] = copy(fallback);
+    else if (isPlain(value) && isPlain(fallback)) fill(value, fallback, copy);
+  }
+}
+
+/**
+ * Fill every nested object prop from its default, in place, and return
+ * the props typed as complete. Top-level props are Vue's to default and
+ * are never written.
+ */
+export function nestedProps<P extends object, D extends object>(
+  props: P,
+  defaults: D,
+  // Optional: the copy policy for default branches written into the props.
+  customCloner: (value: unknown) => unknown = clone
+): NestedProps<P, D> {
+  for (const key in defaults) {
+    const value = (props as PlainObject)[key];
+    const fallback = (defaults as PlainObject)[key];
+    if (isPlain(value) && isPlain(fallback)) fill(value, fallback, customCloner);
+  }
+  return props as unknown as NestedProps<P, D>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ivue",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Infinite Vue – Class Based Architecture for Vue 3",
   "type": "module",
   "exports": {
@@ -14,12 +14,18 @@
       "import": "./dist/extras.es.js",
       "require": "./dist/extras.cjs"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./skills/*": "./skills/*"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.es.js",
   "types": "./dist/index.d.ts",
   "scripts": {
+    "gate": "vite-node skills/ivue/ivue-standards-check.ts --",
+    "gate:docs": "node scripts/gate-docs.mjs",
+    "sweep:components": "NODE_PATH=$PWD/node_modules node docs_v2/scripts/component-sweep.cjs",
+    "gate:house": "vite-node skills/ivue/ivue-house-gate.ts --",
+    "gate:newsletter": "vite-node skills/ivue/ivue-generator-standard.ts -- --source-root newsletter --skip-list skills/ivue/ivue-standards-skip.json --test-glob 'newsletter/src/**/*.test.ts'",
     "dev": "vite demo --host",
     "dev:demo": "vite demo --host",
     "dev:flyweight": "vite examples/playground --port 5181 --host",
@@ -37,9 +43,9 @@
     "bench:node-namespace": "vite-node experiments/node-namespace/benchmark.ts",
     "cypress": "cypress run --component",
     "cypress:headed": "cypress run --component --browser chrome --headed --no-exit",
-    "build": "tsc --version;tsc --p ./tsconfig.json && vite build",
+    "build": "tsc --version;tsc --p ./tsconfig.json && node scripts/build-lib.mjs",
     "build:demo": "tsc --p ./tsconfig.json && vite build demo",
-    "build:docs": "npm run sync:examples && npm run sync:releases && npm run sync:blog-index && npm --prefix docs_v2 run build && npm run check:links && node docs_v2/scripts/check-related-posts.mjs",
+    "build:docs": "npm run gate:docs && npm run sync:examples && npm run sync:releases && npm run sync:blog-index && node docs_v2/scripts/rss-generator.mjs && npm --prefix docs_v2 run build && npm run check:links && node docs_v2/scripts/check-related-posts.mjs && node docs_v2/scripts/check-private-ban.mjs",
     "sync:releases": "node docs_v2/scripts/releases-page-generator.mjs",
     "sync:blog-index": "node docs_v2/scripts/blog-index-generator.mjs",
     "check:links": "node docs_v2/scripts/check-links.mjs",
@@ -56,7 +62,7 @@
     "release": "npm run build && npm publish",
     "sync:skill": "node -e \"const fs=require('fs');fs.mkdirSync('skills/ivue',{recursive:true});fs.copyFileSync('.claude/skills/ivue/SKILL.md','skills/ivue/SKILL.md')\"",
     "prepack": "npm run sync:skill",
-    "sync:examples": "node -e \"require('fs').copyFileSync('lib/Reactive.ts','examples/playground/src/ivue.ts')\"",
+    "sync:examples": "node scripts/sync-examples.mjs",
     "dev:playground": "vite examples/playground --host",
     "build:playground": "vite build examples/playground",
     "preview:playground": "vite preview examples/playground --host",
@@ -102,7 +108,9 @@
     "rollup-plugin-terser": "^7.0.2",
     "typescript": "^5.9.3",
     "vite": "^4.0.4",
+    "vite-node": "^2.0.5",
     "vite-plugin-dts": "^1.7.1",
+    "@microsoft/api-extractor": "7.33.8",
     "vite-plugin-dynamic-import": "^1.5.0",
     "vite-tsconfig-paths": "^4.3.2",
     "vitest": "^2.0.5",