@aglyn/besigner-ui 1.0.0-beta.143

package/src/lib/hooks/use-component-propagation-notice.js

@@ -0,0 +1,177 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ 'use client';
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { collectReferencedComponentIds } from "@aglyn/aglyn";
+import { useEffect, useRef } from "react";
+/**
+ * Deterministic JSON: object keys sorted, so two snapshots of the same
+ * document cannot differ only by field order.
+ *
+ * `JSON.stringify` alone would be a false-positive generator — it preserves
+ * insertion order, and nothing promises a Firestore snapshot rebuilds a map
+ * in the order the last one did. A notice that fires when nothing changed
+ * teaches authors to ignore it, which costs more than the notice is worth.
+ */ function stableStringify(value) {
+    var _JSON_stringify;
+    if (value === null || typeof value !== 'object') return (_JSON_stringify = JSON.stringify(value)) != null ? _JSON_stringify : 'null';
+    if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((key)=>`${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+}
+/**
+ * What a definition contributes to what is DRAWN.
+ *
+ * `icon` is deliberately excluded: it is editor chrome on the hierarchy row,
+ * and republishing a component only to change its glyph must not tell a
+ * screen author their page just changed. `rootId`, `nodes` and declared
+ * `props` are the three the graft consumes.
+ */ function renderSignature(definition) {
+    var _definition_props;
+    if (!definition) return undefined;
+    return stableStringify({
+        rootId: definition.rootId,
+        nodes: definition.nodes,
+        props: (_definition_props = definition.props) != null ? _definition_props : null
+    });
+}
+/**
+ * The changes one snapshot made to definitions THIS document renders
+ * (AGL-1898 phase 2), given the previous snapshot.
+ *
+ * Pulled out of the hook because the interesting rules are all here and all
+ * testable without a renderer:
+ *
+ * - **Only what this document renders.** The definitions map is per HOST, so
+ *   it changes whenever any component in the site is published — most of
+ *   them not on this page. The referenced set is transitive
+ *   ({@link Aglyn.collectReferencedComponentIds}), because the shared
+ *   component an author edits is usually reached through a nav or a card
+ *   rather than placed on the screen itself. Filtering on direct instances
+ *   would stay silent for exactly the case the feature exists for.
+ * - **Only what changed what is drawn.** Compared by render signature, not
+ *   object identity: `useHostComponentDefinitions` rebuilds every definition
+ *   object on every snapshot, so identity always differs and would report
+ *   the whole page as changed each time a colleague published anything.
+ * - **A newly PLACED instance is not a change.** The baseline covers the
+ *   whole map rather than the referenced subset, so dragging in a component
+ *   that was already published reports nothing — its definition's signature
+ *   never moved.
+ *
+ * The reference walk runs over previous ∪ current definitions so a component
+ * nested inside one that was just deleted is still reachable, rather than
+ * dropping out of the referenced set at the moment it most needs reporting.
+ */ export function diffRenderedComponentDefinitions(options) {
+    const { documents, previous, next, names } = options;
+    const merged = _extends({}, previous, next);
+    const referenced = new Set();
+    for (const document of documents){
+        if (!document) continue;
+        for (const id of collectReferencedComponentIds(document, merged)){
+            referenced.add(id);
+        }
+    }
+    const changes = [];
+    for (const id of referenced){
+        const before = renderSignature(previous[id]);
+        const after = renderSignature(next[id]);
+        if (before === after) continue;
+        changes.push({
+            id,
+            name: (names == null ? void 0 : names[id]) || id,
+            kind: before === undefined ? 'appeared' : after === undefined ? 'removed' : 'updated'
+        });
+    }
+    return changes;
+}
+/** Oxford-comma list: `a`, `a and b`, `a, b and c`. */ function joinNames(names) {
+    var _names_;
+    if (names.length <= 1) return (_names_ = names[0]) != null ? _names_ : '';
+    return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+}
+/**
+ * The line an author reads when a component they are using changed under
+ * them (AGL-1898 phase 2).
+ *
+ * It says the canvas ALREADY updated, in the past tense, because it has —
+ * the graft re-ran before this message could be composed. The loop's real
+ * weakness was never the transport but the silence: an author publishes in
+ * the component tab, switches back, and cannot tell a working propagation
+ * from a broken one, because a component edit is usually too small to spot.
+ *
+ * Named, not counted. "A component updated" sends the author hunting; the
+ * name tells them where to look, and is the only part of this message that
+ * does any work.
+ */ export function describeComponentPropagation(changes) {
+    if (!changes.length) return '';
+    const names = joinNames(changes.map((change)=>change.name));
+    const plural = changes.length > 1;
+    if (changes.every((change)=>change.kind === 'removed')) {
+        // Not an update, and must not read like one: the instance is drawing a
+        // placeholder now, and saying "updated" would send the author looking
+        // for a change they cannot see.
+        return plural ? `${names} are no longer published, so this page shows placeholders where they were.` : `${names} is no longer published, so this page shows a placeholder where it was.`;
+    }
+    return plural ? `${names} were updated by their components — this page already shows the new versions.` : `${names} was updated by its component — this page already shows the new version.`;
+}
+/**
+ * Tells an author when a component this document renders changed under them
+ * (AGL-1898 phase 2).
+ *
+ * Phase 2's transport already works: `useHostComponentDefinitions` is a live
+ * listener, so publishing a component re-grafts every open canvas rendering
+ * it. What was missing is any sign that it happened. This adds NO reads —
+ * it is derived entirely from the snapshot stream the canvas already
+ * consumes — and deliberately reports only PUBLISHED changes, because that
+ * is what the parent doc carries and what the live site serves.
+ *
+ * The first settle is silent. Recording a baseline rather than reporting
+ * against an empty map is what stops a page announcing its own components on
+ * load, and is the reason `definitions === undefined` is not treated as
+ * `{}`.
+ */ export function useComponentPropagationNotice(options) {
+    const { documents, definitions, names, onPropagated } = options;
+    // Read through refs: this must fire on a SNAPSHOT, never on the author's
+    // own typing. `documents` is a fresh array on every render and the node
+    // map changes on every keystroke, so either in the dependency list would
+    // re-run the effect constantly — and with a stale-but-equal baseline, a
+    // change would then be reported once per keystroke instead of once.
+    const documentsRef = useRef(documents);
+    documentsRef.current = documents;
+    const namesRef = useRef(names);
+    namesRef.current = names;
+    const onPropagatedRef = useRef(onPropagated);
+    onPropagatedRef.current = onPropagated;
+    const previousRef = useRef(null);
+    useEffect(()=>{
+        if (!definitions) return;
+        const previous = previousRef.current;
+        previousRef.current = definitions;
+        if (!previous) return;
+        const changes = diffRenderedComponentDefinitions({
+            documents: documentsRef.current,
+            previous,
+            next: definitions,
+            names: namesRef.current
+        });
+        if (changes.length) onPropagatedRef.current(changes);
+    }, [
+        definitions
+    ]);
+}
+export default useComponentPropagationNotice;
+
+//# sourceMappingURL=use-component-propagation-notice.js.map

package/src/lib/hooks/use-component-propagation-notice.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/hooks/use-component-propagation-notice.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n'use client'\n\nimport type * as Aglyn from '@aglyn/aglyn'\nimport { collectReferencedComponentIds } from '@aglyn/aglyn'\nimport { useEffect, useRef } from 'react'\n\n/** What happened to one definition this document renders. */\nexport type ComponentPropagationKind = 'updated' | 'appeared' | 'removed'\n\nexport interface ComponentPropagationChange {\n  /** Definition (host component) id. */\n  id: string\n  /** Its display name when known, else the id — never blank. */\n  name: string\n  kind: ComponentPropagationKind\n}\n\nexport interface ComponentPropagationNoticeOptions {\n  /**\n   * Node maps this canvas draws. More than one because the component an\n   * author edits is usually in the LAYOUT — a site nav reached from a\n   * screen — so a screen besigner passes its own nodes AND its bound\n   * layout's, and a surface with only one passes one.\n   */\n  documents: (Record<string, unknown> | undefined | null)[]\n  /**\n   * The live host definitions map, `undefined` until the first snapshot\n   * settles. Loading and \"this host has none\" must not look the same here:\n   * treating loading as an empty map would report every component on the\n   * page as removed and then re-appeared.\n   */\n  definitions: Record<string, Aglyn.ReusableComponentTree> | undefined\n  /** Display names by definition id, for the copy. */\n  names?: Record<string, string | undefined> | undefined\n  /** Called once per snapshot that actually changed something rendered here. */\n  onPropagated: (changes: ComponentPropagationChange[]) => void\n}\n\n/**\n * Deterministic JSON: object keys sorted, so two snapshots of the same\n * document cannot differ only by field order.\n *\n * `JSON.stringify` alone would be a false-positive generator — it preserves\n * insertion order, and nothing promises a Firestore snapshot rebuilds a map\n * in the order the last one did. A notice that fires when nothing changed\n * teaches authors to ignore it, which costs more than the notice is worth.\n */\nfunction stableStringify(value: unknown): string {\n  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'\n  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`\n  const keys = Object.keys(value as Record<string, unknown>).sort()\n  return `{${keys\n    .map(\n      (key) =>\n        `${JSON.stringify(key)}:${stableStringify(\n          (value as Record<string, unknown>)[key],\n        )}`,\n    )\n    .join(',')}}`\n}\n\n/**\n * What a definition contributes to what is DRAWN.\n *\n * `icon` is deliberately excluded: it is editor chrome on the hierarchy row,\n * and republishing a component only to change its glyph must not tell a\n * screen author their page just changed. `rootId`, `nodes` and declared\n * `props` are the three the graft consumes.\n */\nfunction renderSignature(\n  definition: Aglyn.ReusableComponentTree | undefined,\n): string | undefined {\n  if (!definition) return undefined\n  return stableStringify({\n    rootId: definition.rootId,\n    nodes: definition.nodes,\n    props: definition.props ?? null,\n  })\n}\n\n/**\n * The changes one snapshot made to definitions THIS document renders\n * (AGL-1898 phase 2), given the previous snapshot.\n *\n * Pulled out of the hook because the interesting rules are all here and all\n * testable without a renderer:\n *\n * - **Only what this document renders.** The definitions map is per HOST, so\n *   it changes whenever any component in the site is published — most of\n *   them not on this page. The referenced set is transitive\n *   ({@link Aglyn.collectReferencedComponentIds}), because the shared\n *   component an author edits is usually reached through a nav or a card\n *   rather than placed on the screen itself. Filtering on direct instances\n *   would stay silent for exactly the case the feature exists for.\n * - **Only what changed what is drawn.** Compared by render signature, not\n *   object identity: `useHostComponentDefinitions` rebuilds every definition\n *   object on every snapshot, so identity always differs and would report\n *   the whole page as changed each time a colleague published anything.\n * - **A newly PLACED instance is not a change.** The baseline covers the\n *   whole map rather than the referenced subset, so dragging in a component\n *   that was already published reports nothing — its definition's signature\n *   never moved.\n *\n * The reference walk runs over previous ∪ current definitions so a component\n * nested inside one that was just deleted is still reachable, rather than\n * dropping out of the referenced set at the moment it most needs reporting.\n */\nexport function diffRenderedComponentDefinitions(options: {\n  documents: (Record<string, unknown> | undefined | null)[]\n  previous: Record<string, Aglyn.ReusableComponentTree>\n  next: Record<string, Aglyn.ReusableComponentTree>\n  names?: Record<string, string | undefined> | undefined\n}): ComponentPropagationChange[] {\n  const { documents, previous, next, names } = options\n  const merged = { ...previous, ...next }\n  const referenced = new Set<string>()\n  for (const document of documents) {\n    if (!document) continue\n    for (const id of collectReferencedComponentIds(\n      document as Record<string, Aglyn.AglynNodeSchema | undefined>,\n      merged,\n    )) {\n      referenced.add(id)\n    }\n  }\n\n  const changes: ComponentPropagationChange[] = []\n  for (const id of referenced) {\n    const before = renderSignature(previous[id])\n    const after = renderSignature(next[id])\n    if (before === after) continue\n    changes.push({\n      id,\n      name: names?.[id] || id,\n      kind:\n        before === undefined\n          ? 'appeared'\n          : after === undefined\n            ? 'removed'\n            : 'updated',\n    })\n  }\n  return changes\n}\n\n/** Oxford-comma list: `a`, `a and b`, `a, b and c`. */\nfunction joinNames(names: string[]): string {\n  if (names.length <= 1) return names[0] ?? ''\n  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`\n}\n\n/**\n * The line an author reads when a component they are using changed under\n * them (AGL-1898 phase 2).\n *\n * It says the canvas ALREADY updated, in the past tense, because it has —\n * the graft re-ran before this message could be composed. The loop's real\n * weakness was never the transport but the silence: an author publishes in\n * the component tab, switches back, and cannot tell a working propagation\n * from a broken one, because a component edit is usually too small to spot.\n *\n * Named, not counted. \"A component updated\" sends the author hunting; the\n * name tells them where to look, and is the only part of this message that\n * does any work.\n */\nexport function describeComponentPropagation(\n  changes: ComponentPropagationChange[],\n): string {\n  if (!changes.length) return ''\n  const names = joinNames(changes.map((change) => change.name))\n  const plural = changes.length > 1\n  if (changes.every((change) => change.kind === 'removed')) {\n    // Not an update, and must not read like one: the instance is drawing a\n    // placeholder now, and saying \"updated\" would send the author looking\n    // for a change they cannot see.\n    return plural\n      ? `${names} are no longer published, so this page shows placeholders where they were.`\n      : `${names} is no longer published, so this page shows a placeholder where it was.`\n  }\n  return plural\n    ? `${names} were updated by their components — this page already shows the new versions.`\n    : `${names} was updated by its component — this page already shows the new version.`\n}\n\n/**\n * Tells an author when a component this document renders changed under them\n * (AGL-1898 phase 2).\n *\n * Phase 2's transport already works: `useHostComponentDefinitions` is a live\n * listener, so publishing a component re-grafts every open canvas rendering\n * it. What was missing is any sign that it happened. This adds NO reads —\n * it is derived entirely from the snapshot stream the canvas already\n * consumes — and deliberately reports only PUBLISHED changes, because that\n * is what the parent doc carries and what the live site serves.\n *\n * The first settle is silent. Recording a baseline rather than reporting\n * against an empty map is what stops a page announcing its own components on\n * load, and is the reason `definitions === undefined` is not treated as\n * `{}`.\n */\nexport function useComponentPropagationNotice(\n  options: ComponentPropagationNoticeOptions,\n): void {\n  const { documents, definitions, names, onPropagated } = options\n  // Read through refs: this must fire on a SNAPSHOT, never on the author's\n  // own typing. `documents` is a fresh array on every render and the node\n  // map changes on every keystroke, so either in the dependency list would\n  // re-run the effect constantly — and with a stale-but-equal baseline, a\n  // change would then be reported once per keystroke instead of once.\n  const documentsRef = useRef(documents)\n  documentsRef.current = documents\n  const namesRef = useRef(names)\n  namesRef.current = names\n  const onPropagatedRef = useRef(onPropagated)\n  onPropagatedRef.current = onPropagated\n  const previousRef = useRef<Record<string, Aglyn.ReusableComponentTree> | null>(\n    null,\n  )\n\n  useEffect(() => {\n    if (!definitions) return\n    const previous = previousRef.current\n    previousRef.current = definitions\n    if (!previous) return\n    const changes = diffRenderedComponentDefinitions({\n      documents: documentsRef.current,\n      previous,\n      next: definitions,\n      names: namesRef.current,\n    })\n    if (changes.length) onPropagatedRef.current(changes)\n  }, [definitions])\n}\n\nexport default useComponentPropagationNotice\n"],"names":["collectReferencedComponentIds","useEffect","useRef","stableStringify","value","JSON","stringify","Array","isArray","map","join","keys","Object","sort","key","renderSignature","definition","undefined","rootId","nodes","props","diffRenderedComponentDefinitions","options","documents","previous","next","names","merged","referenced","Set","document","id","add","changes","before","after","push","name","kind","joinNames","length","slice","describeComponentPropagation","change","plural","every","useComponentPropagationNotice","definitions","onPropagated","documentsRef","current","namesRef","onPropagatedRef","previousRef"],"mappings":"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"}

package/src/lib/hooks/use-debounced-commit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export declare const ATTRIBUTE_COMMIT_DEBOUNCE_MS = 250;
+export interface DebouncedCommitOptions {
+    /**
+     * Upper bound on how long a continuously-rescheduled commit may be
+     * deferred. Without one, a trailing debounce starves under sustained
+     * activity: a long drag or an unbroken burst of typing keeps pushing the
+     * timer back and the commit never runs at all. Attribute edits do not need
+     * this (a keystroke burst ends in milliseconds); a draft snapshot does,
+     * because the whole point is that the work is on disk *before* the crash
+     * (AGL-1256). Omit for a pure trailing debounce.
+     */
+    maxWait?: number;
+}
+/**
+ * Debounces a commit callback and exposes an imperative `flush`. Rapid
+ * `schedule()` calls (keystrokes) coalesce into a single commit; `flush()`
+ * forces a pending commit out immediately (focus leaving a field, an explicit
+ * Save), and a pending commit is also flushed on unmount (panel close) so an
+ * in-flight edit is never dropped. `commit` may change identity between
+ * renders (react-final-form's `handleSubmit` does) — the latest is always used
+ * without resubscribing the timer.
+ */
+export declare function useDebouncedCommit(commit: () => void, delay?: number, options?: DebouncedCommitOptions): {
+    schedule: () => void;
+    flush: () => void;
+};
+export default useDebouncedCommit;

package/src/lib/hooks/use-debounced-commit.js

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { useCallback, useEffect, useRef } from "react";
+// Attribute edits commit to the node model on a short debounce, never once
+// per keystroke (AGL-567). A commit runs `canvas.updateNodeProps`, which calls
+// `saveHistory` — deep-cloning the ENTIRE node map onto the undo stack — and
+// mutates the observable props the canvas tree renders from. Firing that on
+// every character of a long value (a 30-plus-character External URL is the
+// reproducer) floods the main thread with full-tree clones and full-tree
+// re-renders faster than it can drain them, until the renderer process is
+// killed ("Aw, Snap"). Short labels never typed enough characters to reach the
+// tipping point, which is why only long URLs crashed. The data-driven-forms
+// field keeps the typed value in its own local state, so typing stays
+// responsive while the (expensive) model commit is deferred.
+export const ATTRIBUTE_COMMIT_DEBOUNCE_MS = 250;
+/**
+ * Debounces a commit callback and exposes an imperative `flush`. Rapid
+ * `schedule()` calls (keystrokes) coalesce into a single commit; `flush()`
+ * forces a pending commit out immediately (focus leaving a field, an explicit
+ * Save), and a pending commit is also flushed on unmount (panel close) so an
+ * in-flight edit is never dropped. `commit` may change identity between
+ * renders (react-final-form's `handleSubmit` does) — the latest is always used
+ * without resubscribing the timer.
+ */ export function useDebouncedCommit(commit, delay = ATTRIBUTE_COMMIT_DEBOUNCE_MS, options = {}) {
+    const { maxWait } = options;
+    const commitRef = useRef(commit);
+    commitRef.current = commit;
+    const timerRef = useRef(null);
+    const pendingRef = useRef(false);
+    /** When the currently-pending run was first scheduled, for `maxWait`. */ const pendingSinceRef = useRef(null);
+    const run = useCallback(()=>{
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        pendingRef.current = false;
+        pendingSinceRef.current = null;
+        commitRef.current();
+    }, []);
+    const flush = useCallback(()=>{
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        if (pendingRef.current) run();
+    }, [
+        run
+    ]);
+    const schedule = useCallback(()=>{
+        if (!pendingRef.current) pendingSinceRef.current = Date.now();
+        pendingRef.current = true;
+        if (maxWait !== undefined && pendingSinceRef.current !== null && Date.now() - pendingSinceRef.current >= maxWait) {
+            return run();
+        }
+        if (timerRef.current) clearTimeout(timerRef.current);
+        timerRef.current = setTimeout(run, delay);
+        return undefined;
+    }, [
+        delay,
+        maxWait,
+        run
+    ]);
+    // Flush any pending edit when the form tears down (panel close) so the last
+    // keystrokes are never lost.
+    useEffect(()=>flush, [
+        flush
+    ]);
+    return {
+        schedule,
+        flush
+    };
+}
+export default useDebouncedCommit;
+
+//# sourceMappingURL=use-debounced-commit.js.map

package/src/lib/hooks/use-debounced-commit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/hooks/use-debounced-commit.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { useCallback, useEffect, useRef } from 'react'\n\n// Attribute edits commit to the node model on a short debounce, never once\n// per keystroke (AGL-567). A commit runs `canvas.updateNodeProps`, which calls\n// `saveHistory` — deep-cloning the ENTIRE node map onto the undo stack — and\n// mutates the observable props the canvas tree renders from. Firing that on\n// every character of a long value (a 30-plus-character External URL is the\n// reproducer) floods the main thread with full-tree clones and full-tree\n// re-renders faster than it can drain them, until the renderer process is\n// killed (\"Aw, Snap\"). Short labels never typed enough characters to reach the\n// tipping point, which is why only long URLs crashed. The data-driven-forms\n// field keeps the typed value in its own local state, so typing stays\n// responsive while the (expensive) model commit is deferred.\nexport const ATTRIBUTE_COMMIT_DEBOUNCE_MS = 250\n\nexport interface DebouncedCommitOptions {\n  /**\n   * Upper bound on how long a continuously-rescheduled commit may be\n   * deferred. Without one, a trailing debounce starves under sustained\n   * activity: a long drag or an unbroken burst of typing keeps pushing the\n   * timer back and the commit never runs at all. Attribute edits do not need\n   * this (a keystroke burst ends in milliseconds); a draft snapshot does,\n   * because the whole point is that the work is on disk *before* the crash\n   * (AGL-1256). Omit for a pure trailing debounce.\n   */\n  maxWait?: number\n}\n\n/**\n * Debounces a commit callback and exposes an imperative `flush`. Rapid\n * `schedule()` calls (keystrokes) coalesce into a single commit; `flush()`\n * forces a pending commit out immediately (focus leaving a field, an explicit\n * Save), and a pending commit is also flushed on unmount (panel close) so an\n * in-flight edit is never dropped. `commit` may change identity between\n * renders (react-final-form's `handleSubmit` does) — the latest is always used\n * without resubscribing the timer.\n */\nexport function useDebouncedCommit(\n  commit: () => void,\n  delay: number = ATTRIBUTE_COMMIT_DEBOUNCE_MS,\n  options: DebouncedCommitOptions = {},\n) {\n  const { maxWait } = options\n  const commitRef = useRef(commit)\n  commitRef.current = commit\n  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)\n  const pendingRef = useRef(false)\n  /** When the currently-pending run was first scheduled, for `maxWait`. */\n  const pendingSinceRef = useRef<number | null>(null)\n\n  const run = useCallback(() => {\n    if (timerRef.current) {\n      clearTimeout(timerRef.current)\n      timerRef.current = null\n    }\n    pendingRef.current = false\n    pendingSinceRef.current = null\n    commitRef.current()\n  }, [])\n\n  const flush = useCallback(() => {\n    if (timerRef.current) {\n      clearTimeout(timerRef.current)\n      timerRef.current = null\n    }\n    if (pendingRef.current) run()\n  }, [run])\n\n  const schedule = useCallback(() => {\n    if (!pendingRef.current) pendingSinceRef.current = Date.now()\n    pendingRef.current = true\n    if (\n      maxWait !== undefined &&\n      pendingSinceRef.current !== null &&\n      Date.now() - pendingSinceRef.current >= maxWait\n    ) {\n      return run()\n    }\n    if (timerRef.current) clearTimeout(timerRef.current)\n    timerRef.current = setTimeout(run, delay)\n    return undefined\n  }, [delay, maxWait, run])\n\n  // Flush any pending edit when the form tears down (panel close) so the last\n  // keystrokes are never lost.\n  useEffect(() => flush, [flush])\n\n  return { schedule, flush }\n}\n\nexport default useDebouncedCommit\n"],"names":["useCallback","useEffect","useRef","ATTRIBUTE_COMMIT_DEBOUNCE_MS","useDebouncedCommit","commit","delay","options","maxWait","commitRef","current","timerRef","pendingRef","pendingSinceRef","run","clearTimeout","flush","schedule","Date","now","undefined","setTimeout"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,WAAW,EAAEC,SAAS,EAAEC,MAAM,QAAQ,QAAO;AAEtD,2EAA2E;AAC3E,+EAA+E;AAC/E,6EAA6E;AAC7E,4EAA4E;AAC5E,2EAA2E;AAC3E,yEAAyE;AACzE,0EAA0E;AAC1E,+EAA+E;AAC/E,4EAA4E;AAC5E,sEAAsE;AACtE,6DAA6D;AAC7D,OAAO,MAAMC,+BAA+B,IAAG;AAe/C;;;;;;;;CAQC,GACD,OAAO,SAASC,mBACdC,MAAkB,EAClBC,QAAgBH,4BAA4B,EAC5CI,UAAkC,CAAC,CAAC;IAEpC,MAAM,EAAEC,OAAO,EAAE,GAAGD;IACpB,MAAME,YAAYP,OAAOG;IACzBI,UAAUC,OAAO,GAAGL;IACpB,MAAMM,WAAWT,OAA6C;IAC9D,MAAMU,aAAaV,OAAO;IAC1B,uEAAuE,GACvE,MAAMW,kBAAkBX,OAAsB;IAE9C,MAAMY,MAAMd,YAAY;QACtB,IAAIW,SAASD,OAAO,EAAE;YACpBK,aAAaJ,SAASD,OAAO;YAC7BC,SAASD,OAAO,GAAG;QACrB;QACAE,WAAWF,OAAO,GAAG;QACrBG,gBAAgBH,OAAO,GAAG;QAC1BD,UAAUC,OAAO;IACnB,GAAG,EAAE;IAEL,MAAMM,QAAQhB,YAAY;QACxB,IAAIW,SAASD,OAAO,EAAE;YACpBK,aAAaJ,SAASD,OAAO;YAC7BC,SAASD,OAAO,GAAG;QACrB;QACA,IAAIE,WAAWF,OAAO,EAAEI;IAC1B,GAAG;QAACA;KAAI;IAER,MAAMG,WAAWjB,YAAY;QAC3B,IAAI,CAACY,WAAWF,OAAO,EAAEG,gBAAgBH,OAAO,GAAGQ,KAAKC,GAAG;QAC3DP,WAAWF,OAAO,GAAG;QACrB,IACEF,YAAYY,aACZP,gBAAgBH,OAAO,KAAK,QAC5BQ,KAAKC,GAAG,KAAKN,gBAAgBH,OAAO,IAAIF,SACxC;YACA,OAAOM;QACT;QACA,IAAIH,SAASD,OAAO,EAAEK,aAAaJ,SAASD,OAAO;QACnDC,SAASD,OAAO,GAAGW,WAAWP,KAAKR;QACnC,OAAOc;IACT,GAAG;QAACd;QAAOE;QAASM;KAAI;IAExB,4EAA4E;IAC5E,6BAA6B;IAC7Bb,UAAU,IAAMe,OAAO;QAACA;KAAM;IAE9B,OAAO;QAAEC;QAAUD;IAAM;AAC3B;AAEA,eAAeZ,mBAAkB"}

package/src/lib/hooks/use-delete-element-callback.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2024 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type * as Aglyn from '@aglyn/aglyn';
+export declare function useDeleteElementCallback(): (node: Aglyn.NodeSchema) => Promise<void>;
+/**
+ * Bulk variant for multi-selection (AGL-10/11): one confirm dialog, then
+ * deletes every given node (the root node is skipped defensively).
+ */
+export declare function useDeleteElementsCallback(): (nodes: Aglyn.NodeSchema[]) => Promise<void>;
+export default useDeleteElementCallback;

package/src/lib/hooks/use-delete-element-callback.js

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2024 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { canvas } from "@aglyn/aglyn";
+import * as Besigner from "@aglyn/besigner";
+import { useConfirmationContext } from "@aglyn/shared-ui-jsx";
+import { useCallback } from "react";
+export function useDeleteElementCallback() {
+    const { confirm } = useConfirmationContext();
+    return useCallback((node)=>{
+        function handleDelete() {
+            // Resolved BEFORE the delete and applied after: sibling indices shift
+            // once it runs, and the successor has to be a node that survived it
+            // (AGL-2553). Hover still goes — the pointer was over what just left.
+            const candidates = Besigner.focus.resolveSelectionAfterDeletion([
+                node
+            ]);
+            Besigner.focus.clearHover();
+            canvas.deleteNode(node);
+            Besigner.focus.selectFirstSurviving(candidates);
+        }
+        return confirm({
+            title: 'Are you sure?',
+            description: "You are about to delete an element and all of its child elements from the canvas, please confirm the desired option. Press 'Delete' to confirm and delete the item(s). Press 'Cancel' to void the operation and close this dialog.",
+            confirmationText: 'Delete',
+            confirmationButtonProps: {
+                color: 'error'
+            }
+        }).then(handleDelete).catch(()=>{});
+    }, [
+        confirm
+    ]);
+}
+/**
+ * Bulk variant for multi-selection (AGL-10/11): one confirm dialog, then
+ * deletes every given node (the root node is skipped defensively).
+ */ export function useDeleteElementsCallback() {
+    const { confirm } = useConfirmationContext();
+    return useCallback((nodes)=>{
+        const deletable = nodes.filter((node)=>node && !canvas.isRootNode(node));
+        if (!deletable.length) return Promise.resolve();
+        function handleDelete() {
+            // Same two-phase resolve as the single delete (AGL-2553). The whole
+            // doomed set is handed over so the anchor is the first node that has
+            // a parent; candidates that were themselves deleted — or hung off
+            // something that was — are gone from the map by the time the
+            // selection is applied, and the next one wins.
+            const candidates = Besigner.focus.resolveSelectionAfterDeletion(deletable);
+            Besigner.focus.clearHover();
+            for (const node of deletable){
+                // A node may have been removed already as part of an ancestor.
+                if (canvas.getNode(node.$id)) canvas.deleteNode(node);
+            }
+            Besigner.focus.selectFirstSurviving(candidates);
+        }
+        return confirm({
+            title: 'Are you sure?',
+            description: `You are about to delete ${deletable.length} elements and all of ` + "their child elements from the canvas. Press 'Delete' to confirm " + "or 'Cancel' to void the operation.",
+            confirmationText: 'Delete',
+            confirmationButtonProps: {
+                color: 'error'
+            }
+        }).then(handleDelete).catch(()=>{});
+    }, [
+        confirm
+    ]);
+}
+export default useDeleteElementCallback;
+
+//# sourceMappingURL=use-delete-element-callback.js.map

package/src/lib/hooks/use-delete-element-callback.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/hooks/use-delete-element-callback.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2024 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type * as Aglyn from '@aglyn/aglyn'\nimport { canvas } from '@aglyn/aglyn'\nimport * as Besigner from '@aglyn/besigner'\nimport { useConfirmationContext } from '@aglyn/shared-ui-jsx'\nimport { useCallback } from 'react'\n\nexport function useDeleteElementCallback(): (\n  node: Aglyn.NodeSchema,\n) => Promise<void> {\n  const { confirm } = useConfirmationContext()\n\n  return useCallback(\n    (node: Aglyn.NodeSchema) => {\n      function handleDelete() {\n        // Resolved BEFORE the delete and applied after: sibling indices shift\n        // once it runs, and the successor has to be a node that survived it\n        // (AGL-2553). Hover still goes — the pointer was over what just left.\n        const candidates = Besigner.focus.resolveSelectionAfterDeletion([node])\n        Besigner.focus.clearHover()\n        canvas.deleteNode(node)\n        Besigner.focus.selectFirstSurviving(candidates)\n      }\n\n      return confirm({\n        title: 'Are you sure?',\n        description:\n          \"You are about to delete an element and all of its child elements from the canvas, please confirm the desired option. Press 'Delete' to confirm and delete the item(s). Press 'Cancel' to void the operation and close this dialog.\",\n        confirmationText: 'Delete',\n        confirmationButtonProps: {\n          color: 'error',\n        },\n      })\n        .then(handleDelete)\n        .catch(() => {})\n    },\n    [confirm],\n  )\n}\n\n/**\n * Bulk variant for multi-selection (AGL-10/11): one confirm dialog, then\n * deletes every given node (the root node is skipped defensively).\n */\nexport function useDeleteElementsCallback(): (\n  nodes: Aglyn.NodeSchema[],\n) => Promise<void> {\n  const { confirm } = useConfirmationContext()\n\n  return useCallback(\n    (nodes: Aglyn.NodeSchema[]) => {\n      const deletable = nodes.filter((node) => node && !canvas.isRootNode(node))\n      if (!deletable.length) return Promise.resolve()\n\n      function handleDelete() {\n        // Same two-phase resolve as the single delete (AGL-2553). The whole\n        // doomed set is handed over so the anchor is the first node that has\n        // a parent; candidates that were themselves deleted — or hung off\n        // something that was — are gone from the map by the time the\n        // selection is applied, and the next one wins.\n        const candidates =\n          Besigner.focus.resolveSelectionAfterDeletion(deletable)\n        Besigner.focus.clearHover()\n        for (const node of deletable) {\n          // A node may have been removed already as part of an ancestor.\n          if (canvas.getNode(node.$id)) canvas.deleteNode(node)\n        }\n        Besigner.focus.selectFirstSurviving(candidates)\n      }\n\n      return confirm({\n        title: 'Are you sure?',\n        description:\n          `You are about to delete ${deletable.length} elements and all of ` +\n          \"their child elements from the canvas. Press 'Delete' to confirm \" +\n          \"or 'Cancel' to void the operation.\",\n        confirmationText: 'Delete',\n        confirmationButtonProps: {\n          color: 'error',\n        },\n      })\n        .then(handleDelete)\n        .catch(() => {})\n    },\n    [confirm],\n  )\n}\n\nexport default useDeleteElementCallback\n"],"names":["canvas","Besigner","useConfirmationContext","useCallback","useDeleteElementCallback","confirm","node","handleDelete","candidates","focus","resolveSelectionAfterDeletion","clearHover","deleteNode","selectFirstSurviving","title","description","confirmationText","confirmationButtonProps","color","then","catch","useDeleteElementsCallback","nodes","deletable","filter","isRootNode","length","Promise","resolve","getNode","$id"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,MAAM,QAAQ,eAAc;AACrC,YAAYC,cAAc,kBAAiB;AAC3C,SAASC,sBAAsB,QAAQ,uBAAsB;AAC7D,SAASC,WAAW,QAAQ,QAAO;AAEnC,OAAO,SAASC;IAGd,MAAM,EAAEC,OAAO,EAAE,GAAGH;IAEpB,OAAOC,YACL,CAACG;QACC,SAASC;YACP,sEAAsE;YACtE,oEAAoE;YACpE,sEAAsE;YACtE,MAAMC,aAAaP,SAASQ,KAAK,CAACC,6BAA6B,CAAC;gBAACJ;aAAK;YACtEL,SAASQ,KAAK,CAACE,UAAU;YACzBX,OAAOY,UAAU,CAACN;YAClBL,SAASQ,KAAK,CAACI,oBAAoB,CAACL;QACtC;QAEA,OAAOH,QAAQ;YACbS,OAAO;YACPC,aACE;YACFC,kBAAkB;YAClBC,yBAAyB;gBACvBC,OAAO;YACT;QACF,GACGC,IAAI,CAACZ,cACLa,KAAK,CAAC,KAAO;IAClB,GACA;QAACf;KAAQ;AAEb;AAEA;;;CAGC,GACD,OAAO,SAASgB;IAGd,MAAM,EAAEhB,OAAO,EAAE,GAAGH;IAEpB,OAAOC,YACL,CAACmB;QACC,MAAMC,YAAYD,MAAME,MAAM,CAAC,CAAClB,OAASA,QAAQ,CAACN,OAAOyB,UAAU,CAACnB;QACpE,IAAI,CAACiB,UAAUG,MAAM,EAAE,OAAOC,QAAQC,OAAO;QAE7C,SAASrB;YACP,oEAAoE;YACpE,qEAAqE;YACrE,kEAAkE;YAClE,6DAA6D;YAC7D,+CAA+C;YAC/C,MAAMC,aACJP,SAASQ,KAAK,CAACC,6BAA6B,CAACa;YAC/CtB,SAASQ,KAAK,CAACE,UAAU;YACzB,KAAK,MAAML,QAAQiB,UAAW;gBAC5B,+DAA+D;gBAC/D,IAAIvB,OAAO6B,OAAO,CAACvB,KAAKwB,GAAG,GAAG9B,OAAOY,UAAU,CAACN;YAClD;YACAL,SAASQ,KAAK,CAACI,oBAAoB,CAACL;QACtC;QAEA,OAAOH,QAAQ;YACbS,OAAO;YACPC,aACE,CAAC,wBAAwB,EAAEQ,UAAUG,MAAM,CAAC,qBAAqB,CAAC,GAClE,qEACA;YACFV,kBAAkB;YAClBC,yBAAyB;gBACvBC,OAAO;YACT;QACF,GACGC,IAAI,CAACZ,cACLa,KAAK,CAAC,KAAO;IAClB,GACA;QAACf;KAAQ;AAEb;AAEA,eAAeD,yBAAwB"}

package/src/lib/hooks/use-detail-hover-intent.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * How long the panel survives the pointer leaving, in ms.
+ *
+ * This is the forgiving path from the card to the panel: the two are
+ * separated by a gap, so travelling to a link inside the panel means
+ * leaving the card first. Dismissing on `mouseleave` is what makes a
+ * floating detail impossible to click — the content moves or vanishes on the
+ * way to it. Long enough to cross a gap diagonally, short enough that it
+ * does not linger once you have moved on.
+ */
+export declare const DETAIL_CLOSE_DELAY_MS = 260;
+export interface DetailTarget<T> {
+    item: T;
+    anchor: HTMLElement;
+}
+export interface HoverIntent<T> {
+    /** What the surface should describe: the pin wins over the pointer. */
+    active: DetailTarget<T> | null;
+    /** True while held open by a click rather than by the pointer. */
+    isPinned: boolean;
+    /** Pointer entered a card. */
+    open: (item: T, anchor: HTMLElement) => void;
+    /** Pointer left a card, or left the floating panel. */
+    scheduleClose: () => void;
+    /** Pointer entered the floating panel — cancels a pending close. */
+    keepOpen: () => void;
+    /** Click a card: holds it open, or releases it if it was already held. */
+    togglePin: (item: T, anchor: HTMLElement) => void;
+    /** Dismiss explicitly (close button, Escape, outside click). */
+    dismiss: () => void;
+    /**
+     * Dismiss AND stop responding to the pointer until {@link resume}.
+     *
+     * For a drag: the panel floats over the canvas, which is where the element
+     * is being dropped, so it has to leave the drop path the moment the drag
+     * starts — not on drop. Suspending rather than just dismissing is the
+     * other half: a drag crosses other cards on its way out, and each of those
+     * would otherwise re-open it mid-flight.
+     */
+    suspend: () => void;
+    resume: () => void;
+}
+/**
+ * Hover-with-intent for a floating detail panel (AGL-2486).
+ *
+ * Three behaviours, and every one of them exists because the naive version
+ * is unusable:
+ *
+ * - **A pin beats the pointer.** Once clicked, moving across other cards
+ *   does not swap the content out from under you. Without this, everything
+ *   inside the panel — Learn more, the attribute list — is unreachable,
+ *   because reaching for it changes what it says.
+ * - **Closing is delayed.** See {@link DETAIL_CLOSE_DELAY_MS}.
+ * - **Only one is ever open**, because there is one piece of state, not one
+ *   per card.
+ */
+export declare function useDetailHoverIntent<T extends {
+    $id?: string;
+}>(): HoverIntent<T>;
+export default useDetailHoverIntent;