@supersoniks/concorde 5.1.2 → 5.1.3-immutable.1

package/src/core/utils/immutableValue.ts

@@ -0,0 +1,102 @@
+/**
+ * Ownership helpers for the immutable DataProvider store (REDMINE-79567).
+ * External values are cloned then deep-frozen; internal updates rebuild via spread.
+ */
+
+const warnedUnclonable = new WeakSet<object>();
+
+export function isFrozenValue(value: unknown): boolean {
+  return value != null && typeof value === "object" && Object.isFrozen(value);
+}
+
+/** Deep freeze (in place). Safe to call on already-frozen graphs. */
+export function deepFreeze<T>(value: T): T {
+  if (value == null || typeof value !== "object" || Object.isFrozen(value)) {
+    return value;
+  }
+  Object.freeze(value);
+  if (Array.isArray(value)) {
+    for (const item of value) deepFreeze(item);
+  } else {
+    for (const key of Reflect.ownKeys(value as object)) {
+      deepFreeze((value as Record<string | symbol, unknown>)[key]);
+    }
+  }
+  return value;
+}
+
+/**
+ * Clone so the publisher owns the data, then freeze.
+ * Non-cloneable values (EventSource, etc.): kept as-is, not frozen (warned once).
+ */
+export function takeOwnership<T>(value: T): T {
+  if (value == null || typeof value !== "object") return value;
+  if (isFrozenValue(value)) return value;
+  try {
+    return deepFreeze(structuredClone(value));
+  } catch {
+    if (!warnedUnclonable.has(value as object)) {
+      warnedUnclonable.add(value as object);
+      console.warn(
+        "[Concorde] takeOwnership: value is not structuredClone-able; stored without freeze.",
+      );
+    }
+    return value;
+  }
+}
+
+/** Drop `undefined` own keys on plain objects (before freeze). Arrays unchanged. */
+export function stripUndefinedKeys<T>(value: T): T {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return value;
+  }
+  if (Object.prototype.hasOwnProperty.call(value, "__value")) return value;
+  // Keep frozen / already-owned graphs intact (set(get()) identity).
+  if (Object.isFrozen(value)) return value;
+  let needsStrip = false;
+  for (const key of Object.keys(value as object)) {
+    if ((value as Record<string, unknown>)[key] === undefined) {
+      needsStrip = true;
+      break;
+    }
+  }
+  if (!needsStrip) return value;
+  const out: Record<string, unknown> = { ...(value as object) };
+  for (const key of Object.keys(out)) {
+    if (out[key] === undefined) delete out[key];
+  }
+  return out as T;
+}
+
+/** Shallow rebuild with one key set — result is deep-frozen. Nested `value` should already be owned. */
+export function setAtKey<T extends object>(
+  root: T | null | undefined,
+  key: string | number,
+  value: unknown,
+): T {
+  let next: any;
+  if (root == null) {
+    next = typeof key === "number" || !isNaN(Number(key)) ? [] : {};
+  } else if (Array.isArray(root)) {
+    next = [...root];
+  } else {
+    next = { ...(root as object) };
+  }
+  next[key as any] = value;
+  return deepFreeze(next) as T;
+}
+
+/** Shallow rebuild without one key — result is deep-frozen. */
+export function deleteAtKey<T extends object>(
+  root: T,
+  key: string | number,
+): T {
+  if (Array.isArray(root)) {
+    const next = [...root];
+    delete next[key as any];
+    return deepFreeze(next) as T;
+  }
+  const next = { ...(root as object) } as Record<string, unknown>;
+  delete next[String(key)];
+  return deepFreeze(next) as T;
+}

package/src/core/utils/nestedDotForm.spec.ts

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { PublisherManager, get, set } from "./PublisherProxy";
+import { traverseDotNotation } from "./Objects";
+
+afterEach(() => {
+  PublisherManager.getInstance().delete("nested-dot-form");
+});
+
+describe("nested dot form publishers (immutable)", () => {
+  it("set via traverseDotNotation builds nested object", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    form.set({});
+    traverseDotNotation(form as any, "passenger.seat").set("window");
+    expect(get("nested-dot-form")).toEqual({ passenger: { seat: "window" } });
+  });
+
+  it("successive nested sets keep siblings", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    form.set({});
+    traverseDotNotation(form as any, "passenger.name").set("Ada");
+    traverseDotNotation(form as any, "passenger.seat").set("aisle");
+    expect(get("nested-dot-form")).toEqual({
+      passenger: { name: "Ada", seat: "aisle" },
+    });
+  });
+
+  it("nested get after set is readable", () => {
+    set("nested-dot-form", { passenger: { seat: "window" } });
+    const form = PublisherManager.get("nested-dot-form");
+    expect(traverseDotNotation(form as any, "passenger.seat").get()).toBe(
+      "window",
+    );
+  });
+
+  it("deep leaf set from empty root creates intermediates (frozen)", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    traverseDotNotation(form as any, "passenger.seat").set("window");
+    const data = get("nested-dot-form") as { passenger: { seat: string } };
+    expect(data).toEqual({ passenger: { seat: "window" } });
+    expect(Object.isFrozen(data)).toBe(true);
+    expect(Object.isFrozen(data.passenger)).toBe(true);
+  });
+
+  it("switching nested radio leaf replaces value", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    traverseDotNotation(form as any, "passenger.seat").set("window");
+    traverseDotNotation(form as any, "passenger.seat").set("aisle");
+    expect(get("nested-dot-form")).toEqual({ passenger: { seat: "aisle" } });
+  });
+
+  it("onAssign on nested path receives scalar", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    const seen: unknown[] = [];
+    traverseDotNotation(form as any, "passenger.seat").onAssign((v: unknown) => {
+      seen.push(v);
+    });
+    traverseDotNotation(form as any, "passenger.seat").set("window");
+    expect(seen).toContain("window");
+  });
+
+  it("reading nested before set returns null", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    expect(traverseDotNotation(form as any, "passenger.seat").get()).toBeNull();
+  });
+
+  it("updating leaf after frozen parent set keeps siblings", () => {
+    set("nested-dot-form", { passenger: { name: "Ada", seat: "window" } });
+    const form = PublisherManager.get("nested-dot-form");
+    traverseDotNotation(form as any, "passenger.seat").set("aisle");
+    expect(get("nested-dot-form")).toEqual({
+      passenger: { name: "Ada", seat: "aisle" },
+    });
+  });
+
+  it("checkbox-like array replace via slice keeps frozen parent", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    traverseDotNotation(form as any, "passenger.tags").set(["a"]);
+    const current = traverseDotNotation(form as any, "passenger.tags").get() as
+      | string[]
+      | null;
+    const next = (current ?? []).slice(0);
+    next.push("b");
+    traverseDotNotation(form as any, "passenger.tags").set(next);
+    expect(get("nested-dot-form")).toEqual({
+      passenger: { tags: ["a", "b"] },
+    });
+  });
+});

package/src/core/utils/publisherImmutable.spec.ts

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { DataProviderKey } from "./dataProviderKey";
+import { dp, get, PublisherManager, set } from "./PublisherProxy";
+
+type Cart = { items: { id: number }[]; total: number };
+type Row = { id: number; _metadata_?: { key: string; even: boolean } };
+
+describe("immutable DataProvider store (79567)", () => {
+  const cartKey = new DataProviderKey<Cart>("publisherImmutableCart");
+
+  afterEach(() => {
+    PublisherManager.getInstance().delete(cartKey.path);
+    PublisherManager.getInstance().delete("publisherImmutableListLoop");
+  });
+
+  it("set takes ownership — mutating the input does not change the store", () => {
+    const input: Cart = { items: [{ id: 1 }], total: 1 };
+    set(cartKey, input);
+    input.total = 99;
+    input.items.push({ id: 2 });
+    expect(get(cartKey).total).toBe(1);
+    expect(get(cartKey).items).toHaveLength(1);
+  });
+
+  it("get returns a frozen value (same ref until next set)", () => {
+    set(cartKey, { items: [], total: 0 });
+    const a = get(cartKey);
+    const b = get(cartKey);
+    expect(a).toBe(b);
+    expect(Object.isFrozen(a)).toBe(true);
+    expect(() => {
+      (a as Cart).total = 5;
+    }).toThrow();
+    expect(get(cartKey).total).toBe(0);
+  });
+
+  it("nested dp().set updates parent immutably", () => {
+    set(cartKey, { items: [{ id: 1 }], total: 0 });
+    dp(cartKey.total).set(10);
+    expect(get(cartKey).total).toBe(10);
+    expect(Object.isFrozen(get(cartKey))).toBe(true);
+  });
+
+  it("publisher property assign goes through immutable set", () => {
+    set(cartKey, { items: [], total: 0 });
+    const pub = dp(cartKey);
+    (pub as any).total = 4;
+    expect(get(cartKey).total).toBe(4);
+  });
+
+  it("set(get()) is a no-op identity keep", () => {
+    set(cartKey, { items: [{ id: 1 }], total: 1 });
+    const snap = get(cartKey);
+    set(cartKey, snap);
+    expect(get(cartKey)).toBe(snap);
+  });
+
+  it("re-assigning the same nested value does not re-publish the parent", () => {
+    const listKey = new DataProviderKey<Row[]>("publisherImmutableListLoop");
+    set(listKey, [{ id: 1 }]);
+    const row = dp(listKey)[0];
+    const meta = { key: "0", even: true };
+    row._metadata_ = meta as any;
+
+    const parentAssign = vi.fn();
+    dp(listKey).onAssign(parentAssign, false);
+    parentAssign.mockClear();
+
+    // Same logical metadata again (new object) would rebuild without the list guard;
+    // engine must still skip parent sync when the child commits a value already at parent[key].
+    expect(row._metadata_).toBeDefined();
+    const ownedMeta = row._metadata_!.get();
+    row._metadata_!.set(ownedMeta as any);
+    expect(parentAssign).not.toHaveBeenCalled();
+  });
+});

package/src/core/utils/strictGet.spec.ts

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { DataProviderKey } from "./dataProviderKey";
+import {
+  clearStrictGetWarnings,
+  PublisherManager,
+  dp,
+  get,
+  set,
+} from "./PublisherProxy";
+
+type Cart = { items: { id: number }[]; total: number };
+
+describe("strictGet runtime guard (79567)", () => {
+  const cartKey = new DataProviderKey<Cart>("strictGetSpecCart");
+
+  afterEach(() => {
+    PublisherManager.strictGet = "off";
+    clearStrictGetWarnings();
+    vi.restoreAllMocks();
+  });
+
+  it("off: store is frozen — assignment via get() throws", () => {
+    PublisherManager.strictGet = "off";
+    set(cartKey, { items: [{ id: 1 }], total: 1 });
+    const cart = get(cartKey) as Cart;
+    expect(() => {
+      cart.total = 7;
+    }).toThrow();
+    expect(get(cartKey).total).toBe(1);
+  });
+
+  it("warn: logs once per path; mutation still blocked by freeze", () => {
+    PublisherManager.strictGet = "warn";
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    set(cartKey, { items: [{ id: 1 }], total: 1 });
+    const cart = get(cartKey) as Cart;
+    expect(() => {
+      cart.total = 2;
+    }).toThrow();
+    expect(warn).toHaveBeenCalled();
+    expect(String(warn.mock.calls[0]?.[0])).toContain("strictGet=warn");
+    expect(get(cartKey).total).toBe(1);
+  });
+
+  it("throw: TypeError from strictGet before freeze", () => {
+    PublisherManager.strictGet = "throw";
+    set(cartKey, { items: [{ id: 1 }], total: 1 });
+    const cart = get(cartKey) as Cart;
+    expect(() => {
+      cart.total = 9;
+    }).toThrow(/strictGet=throw/);
+    expect(dp(cartKey).get().total).toBe(1);
+  });
+
+  it("set() still works while strictGet=throw", () => {
+    PublisherManager.strictGet = "throw";
+    set(cartKey, { items: [], total: 0 });
+    set(cartKey, { items: [{ id: 1 }], total: 1 });
+    expect(get(cartKey).total).toBe(1);
+  });
+});

package/src/core/utils/strictGet.ts

@@ -0,0 +1,102 @@
+/**
+ * Runtime guard for values returned by publisher `get()` (REDMINE-79567).
+ * Wraps objects/arrays in a Proxy — does **not** freeze live `_value_`.
+ * Engine writes that touch the target directly still work.
+ *
+ * - `off`   — no wrap (same ref as today)
+ * - `warn`  — log once per path, mutation still applied (discovery)
+ * - `throw` — TypeError, mutation blocked (CI / hardening)
+ */
+
+export type StrictGetMode = "off" | "warn" | "throw";
+
+let strictGetMode: StrictGetMode = "off";
+const warnedKeys = new Set<string>();
+const proxyCache = new WeakMap<object, object>();
+
+export function getStrictGetMode(): StrictGetMode {
+  return strictGetMode;
+}
+
+export function setStrictGetMode(mode: StrictGetMode): void {
+  strictGetMode = mode;
+}
+
+/** Test helper — clears once-only warn dedupe. */
+export function clearStrictGetWarnings(): void {
+  warnedKeys.clear();
+}
+
+function report(mode: "warn" | "throw", path: string): void {
+  const message = `[Concorde strictGet=${mode}] Mutation via get() at "${path || "(root)"}". Use set() / dp(…).set(…) instead.`;
+  if (mode === "throw") {
+    throw new TypeError(message);
+  }
+  if (warnedKeys.has(path)) return;
+  warnedKeys.add(path);
+  console.warn(message);
+}
+
+function wrapDeep<T extends object>(target: T, path: string): T {
+  const cached = proxyCache.get(target);
+  if (cached) return cached as T;
+
+  const proxy = new Proxy(target, {
+    get(obj, prop, receiver) {
+      if (prop === "__strictGetTarget__") return target;
+      const value = Reflect.get(obj, prop, receiver);
+      if (value == null || typeof value !== "object") return value;
+      if (getStrictGetMode() === "off") return value;
+      const childPath =
+        path === "" ? String(prop) : `${path}.${String(prop)}`;
+      return wrapDeep(value as object, childPath);
+    },
+    set(obj, prop, value, receiver) {
+      const mode = getStrictGetMode();
+      if (mode === "off") {
+        return Reflect.set(obj, prop, value, receiver);
+      }
+      const childPath =
+        path === "" ? String(prop) : `${path}.${String(prop)}`;
+      report(mode, childPath);
+      if (mode === "throw") return false;
+      return Reflect.set(obj, prop, value, receiver);
+    },
+    deleteProperty(obj, prop) {
+      const mode = getStrictGetMode();
+      if (mode === "off") {
+        return Reflect.deleteProperty(obj, prop);
+      }
+      const childPath =
+        path === "" ? String(prop) : `${path}.${String(prop)}`;
+      report(mode, childPath);
+      if (mode === "throw") return false;
+      return Reflect.deleteProperty(obj, prop);
+    },
+    defineProperty(obj, prop, desc) {
+      const mode = getStrictGetMode();
+      if (mode === "off") {
+        return Reflect.defineProperty(obj, prop, desc);
+      }
+      const childPath =
+        path === "" ? String(prop) : `${path}.${String(prop)}`;
+      report(mode, childPath);
+      if (mode === "throw") return false;
+      return Reflect.defineProperty(obj, prop, desc);
+    },
+  });
+
+  proxyCache.set(target, proxy);
+  return proxy;
+}
+
+/**
+ * When mode is off or value is not an object, returns value as-is (same ref).
+ * Otherwise returns a deep Proxy over the **same** target (no clone).
+ */
+export function wrapStrictGet<T>(value: T): T {
+  if (getStrictGetMode() === "off" || value == null || typeof value !== "object") {
+    return value;
+  }
+  return wrapDeep(value as object, "") as T;
+}

package/src/css.d.ts

@@ -0,0 +1,19 @@
+declare module "*.css" {
+  const css: import("lit").CSSResult;
+  export default css;
+}
+
+declare module "*.css?inline" {
+  const css: string;
+  export default css;
+}
+
+declare module "*.scss" {
+  const css: import("lit").CSSResult;
+  export default css;
+}
+
+declare module "*.scss?inline" {
+  const css: string;
+  export default css;
+}

package/src/docs/components/docs-demo-sources.ts

@@ -342,12 +342,12 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
     },
   ],
   "demo-bind": [
-    { path: "src/docs/example/decorators-demo-bind-demos.ts", line: 32, label: "demo-bind" },
+    { path: "src/docs/example/decorators-demo-bind-demos.ts", line: 36, label: "demo-bind" },
   ],
   "demo-bind-reflect": [
     {
       path: "src/docs/example/decorators-demo-bind-demos.ts",
-      line: 70,
+      line: 74,
       label: "demo-bind-reflect",
     },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
@@ -355,7 +355,7 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-bind-dynamic": [
     {
       path: "src/docs/example/decorators-demo-bind-demos.ts",
-      line: 130,
+      line: 113,
       label: "demo-bind-dynamic",
     },
   ],

package/src/docs/decorators/bind.md

@@ -1,22 +1,26 @@
 # @bind
 
-Keeps a class property in sync with a path of the DataProvider store, in both directions when needed. Pass a dot-notation string or a [DataProviderKey](/docs/misc/dataProviderKey); add `{ reflect: true }` to push local writes back to the store. For read-only sync prefer [@subscribe](/docs/decorators/subscribe), and see [Data flow](/docs/getting-started/dataFlow) for the overall model.
+`@bind(key)` keeps a class property and one path of the DataProvider store in sync. With `{ reflect: true }` the sync goes both ways: the property follows the store, and each assignment is written back to it. For one direction only, use the complementary decorators: [@subscribe](/docs/decorators/subscribe) to read, [@publish](/docs/decorators/publish) to write. See [Data flow](/docs/getting-started/dataFlow) for the overall model.
 
 ## Import
 
 <sonic-code language="typescript">
   <template>
 import { bind } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+type Flight = { flight: string; gate: string; boarded: number };
+const flightKey = new DataProviderKey&lt;Flight&gt;("flight");
 
-@bind("flight.gate")
+@bind(flightKey.boarded, { reflect: true })
 @state()
-gate = "";
+boarded = 0;
   </template>
 </sonic-code>
 
 ## Basic usage
 
-The first path segment is the data provider id, the rest is dot notation (array items use a numeric index: `passengers.0`). The property updates each time the store value changes. Add `@state()` so Lit re-renders.
+The key is a [DataProviderKey](/docs/misc/dataProviderKey): TypeScript checks that the property type matches `T` at that path. The property updates each time the store value changes. Add `@state()` so Lit re-renders.
 
 <sonic-code>
   <template>
@@ -25,26 +29,9 @@ The first path segment is the data provider id, the rest is dot notation (array
   </template>
 </sonic-code>
 
-## Typed key
-
-With a `DataProviderKey<T>`, TypeScript checks that the property type matches `T` at that path.
-
-<sonic-code language="typescript">
-  <template>
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-
-type Flight = { flight: string; gate: string; boarded: number };
-const flightKey = new DataProviderKey&lt;Flight&gt;("flight");
-
-@bind(flightKey.boarded, { reflect: true })
-@state()
-boarded = 0;
-  </template>
-</sonic-code>
-
 ## Reflect
 
-By default (`reflect: false`) the binding is one-way: assigning the property does not touch the store. With `reflect: true`, each assignment calls `set()` on the publisher, so every other subscriber sees the new value. An internal guard prevents update loops.
+With `reflect: true`, each assignment to the property calls `set()` at the key path, so every other subscriber sees the new value. An internal guard prevents update loops. Without `reflect` (the default), assigning the property does not touch the store, and `@bind` behaves like `@subscribe`.
 
 <sonic-code>
   <template>
@@ -55,7 +42,19 @@ By default (`reflect: false`) the binding is one-way: assigning the property doe
 
 ## Dynamic path
 
-Placeholders such as `${index}` are resolved from properties of the same component, and `@bind` re-subscribes when they change. Write them in a plain string, not a backtick template literal. While a placeholder is `null` or `undefined` the binding is inactive; `{ skipEmptyPlaceholder: true }` also waits on `""`. Full rules: [Dynamic paths](/docs/misc/dynamic-path).
+Placeholders such as `${index}` are resolved from properties of the same component, and `@bind` re-subscribes when they change. Declare them in the key's second generic and write them in a plain string, not a backtick template literal. While a placeholder is `null` or `undefined` the binding is inactive; `{ skipEmptyPlaceholder: true }` also waits on `""`. Full rules: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+const personKey = new DataProviderKey&lt;Person, { dataProvider: string; index: number }&gt;(
+  "${dataProvider}.${index}",
+);
+
+@bind(personKey)
+@state()
+person: Person | null = null;
+  </template>
+</sonic-code>
 
 <sonic-code>
   <template>
@@ -72,6 +71,6 @@ The decorator subscribes in `connectedCallback` and unsubscribes in `disconnecte
 
 | Argument | Type | Description |
 |----------|------|-------------|
-| `path` | `string` or `DataProviderKey<T>` | Store path to bind. Supports `${prop}` placeholders |
+| `key` | `DataProviderKey<T>` | Store path to bind. Supports `${prop}` placeholders |
 | `options.reflect` | `boolean` (default `false`) | Write local assignments back to the store |
 | `options.skipEmptyPlaceholder` | `boolean` (default `false`) | Treat a placeholder resolved to `""` as not ready |

package/src/docs/docs-location.spec.ts

@@ -19,6 +19,16 @@ describe("docsPagePath / docsPageHref", () => {
 });
 
 describe("parseDocsLocation", () => {
+  it("maps root site pages to their markdown", () => {
+    const r = parseDocsLocation("/about");
+    expect(r.url).toBe("about.md");
+    expect(r.pagePath).toBe("/about");
+    expect(parseDocsLocation("/privacy#your-rights").anchor).toBe("your-rights");
+    expect(parseDocsLocation("/about/").url).toBe("about.md");
+    expect(parseDocsLocation("/developers").url).toBe("");
+    expect(parseDocsLocation("/unknown").url).toBe("");
+  });
+
   it("parses pretty pathname doc URLs", () => {
     const r = parseDocsLocation("/docs/getting-started/start");
     expect(r.url).toBe("docs/getting-started/start.md");

package/src/docs/docs-location.ts

@@ -9,6 +9,7 @@
  */
 
 import {
+  SITE_PAGE_SLUGS,
   toPublicMdRel,
   toPublicPath,
   toSourceId,
@@ -107,6 +108,15 @@ export function parseDocsLocation(location: string): {
   }
 
   const rel = pathname.replace(/^\//, "");
+  if (SITE_PAGE_SLUGS.includes(rel)) {
+    return {
+      url: `${rel}.md`,
+      anchor: hash,
+      demoSubHash: hash,
+      pagePath: pathname,
+      pageHash: pathname,
+    };
+  }
   if (!rel || !isDocsContentPath(rel)) {
     return empty;
   }