@aglyn/besigner-ui 1.0.0-beta.143

package/src/lib/hooks/use-detail-hover-intent.js

@@ -0,0 +1,123 @@
+/**
+ * @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, useState } from "react";
+/**
+ * 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 const DETAIL_CLOSE_DELAY_MS = 260;
+/**
+ * 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 function useDetailHoverIntent() {
+    const [hovered, setHovered] = useState(null);
+    const [pinned, setPinned] = useState(null);
+    const [suspended, setSuspended] = useState(false);
+    const timer = useRef(null);
+    const cancel = useCallback(()=>{
+        if (timer.current) {
+            clearTimeout(timer.current);
+            timer.current = null;
+        }
+    }, []);
+    // A pending close must not fire into an unmounted tree.
+    useEffect(()=>cancel, [
+        cancel
+    ]);
+    const open = useCallback((item, anchor)=>{
+        if (suspended) return;
+        cancel();
+        setHovered({
+            item,
+            anchor
+        });
+    }, [
+        cancel,
+        suspended
+    ]);
+    const scheduleClose = useCallback(()=>{
+        cancel();
+        timer.current = setTimeout(()=>setHovered(null), DETAIL_CLOSE_DELAY_MS);
+    }, [
+        cancel
+    ]);
+    const keepOpen = useCallback(()=>cancel(), [
+        cancel
+    ]);
+    const togglePin = useCallback((item, anchor)=>{
+        if (suspended) return;
+        cancel();
+        setPinned((prev)=>{
+            var _prev_item;
+            return prev && ((_prev_item = prev.item) == null ? void 0 : _prev_item.$id) === (item == null ? void 0 : item.$id) ? null : {
+                item,
+                anchor
+            };
+        });
+        setHovered({
+            item,
+            anchor
+        });
+    }, [
+        cancel,
+        suspended
+    ]);
+    const dismiss = useCallback(()=>{
+        cancel();
+        setPinned(null);
+        setHovered(null);
+    }, [
+        cancel
+    ]);
+    const suspend = useCallback(()=>{
+        cancel();
+        setSuspended(true);
+        setPinned(null);
+        setHovered(null);
+    }, [
+        cancel
+    ]);
+    const resume = useCallback(()=>setSuspended(false), []);
+    return {
+        active: suspended ? null : pinned != null ? pinned : hovered,
+        isPinned: Boolean(pinned),
+        open,
+        scheduleClose,
+        keepOpen,
+        togglePin,
+        dismiss,
+        suspend,
+        resume
+    };
+}
+export default useDetailHoverIntent;
+
+//# sourceMappingURL=use-detail-hover-intent.js.map

package/src/lib/hooks/use-detail-hover-intent.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/hooks/use-detail-hover-intent.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, useState } from 'react'\n\n/**\n * How long the panel survives the pointer leaving, in ms.\n *\n * This is the forgiving path from the card to the panel: the two are\n * separated by a gap, so travelling to a link inside the panel means\n * leaving the card first. Dismissing on `mouseleave` is what makes a\n * floating detail impossible to click — the content moves or vanishes on the\n * way to it. Long enough to cross a gap diagonally, short enough that it\n * does not linger once you have moved on.\n */\nexport const DETAIL_CLOSE_DELAY_MS = 260\n\nexport interface DetailTarget<T> {\n  item: T\n  anchor: HTMLElement\n}\n\nexport interface HoverIntent<T> {\n  /** What the surface should describe: the pin wins over the pointer. */\n  active: DetailTarget<T> | null\n  /** True while held open by a click rather than by the pointer. */\n  isPinned: boolean\n  /** Pointer entered a card. */\n  open: (item: T, anchor: HTMLElement) => void\n  /** Pointer left a card, or left the floating panel. */\n  scheduleClose: () => void\n  /** Pointer entered the floating panel — cancels a pending close. */\n  keepOpen: () => void\n  /** Click a card: holds it open, or releases it if it was already held. */\n  togglePin: (item: T, anchor: HTMLElement) => void\n  /** Dismiss explicitly (close button, Escape, outside click). */\n  dismiss: () => void\n  /**\n   * Dismiss AND stop responding to the pointer until {@link resume}.\n   *\n   * For a drag: the panel floats over the canvas, which is where the element\n   * is being dropped, so it has to leave the drop path the moment the drag\n   * starts — not on drop. Suspending rather than just dismissing is the\n   * other half: a drag crosses other cards on its way out, and each of those\n   * would otherwise re-open it mid-flight.\n   */\n  suspend: () => void\n  resume: () => void\n}\n\n/**\n * Hover-with-intent for a floating detail panel (AGL-2486).\n *\n * Three behaviours, and every one of them exists because the naive version\n * is unusable:\n *\n * - **A pin beats the pointer.** Once clicked, moving across other cards\n *   does not swap the content out from under you. Without this, everything\n *   inside the panel — Learn more, the attribute list — is unreachable,\n *   because reaching for it changes what it says.\n * - **Closing is delayed.** See {@link DETAIL_CLOSE_DELAY_MS}.\n * - **Only one is ever open**, because there is one piece of state, not one\n *   per card.\n */\nexport function useDetailHoverIntent<T extends { $id?: string }>(): HoverIntent<T> {\n  const [hovered, setHovered] = useState<DetailTarget<T> | null>(null)\n  const [pinned, setPinned] = useState<DetailTarget<T> | null>(null)\n  const [suspended, setSuspended] = useState(false)\n  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)\n\n  const cancel = useCallback(() => {\n    if (timer.current) {\n      clearTimeout(timer.current)\n      timer.current = null\n    }\n  }, [])\n\n  // A pending close must not fire into an unmounted tree.\n  useEffect(() => cancel, [cancel])\n\n  const open = useCallback(\n    (item: T, anchor: HTMLElement) => {\n      if (suspended) return\n      cancel()\n      setHovered({ item, anchor })\n    },\n    [cancel, suspended],\n  )\n\n  const scheduleClose = useCallback(() => {\n    cancel()\n    timer.current = setTimeout(() => setHovered(null), DETAIL_CLOSE_DELAY_MS)\n  }, [cancel])\n\n  const keepOpen = useCallback(() => cancel(), [cancel])\n\n  const togglePin = useCallback((item: T, anchor: HTMLElement) => {\n    if (suspended) return\n    cancel()\n    setPinned((prev) => (prev && prev.item?.$id === item?.$id ? null : { item, anchor }))\n    setHovered({ item, anchor })\n  }, [cancel, suspended])\n\n  const dismiss = useCallback(() => {\n    cancel()\n    setPinned(null)\n    setHovered(null)\n  }, [cancel])\n\n  const suspend = useCallback(() => {\n    cancel()\n    setSuspended(true)\n    setPinned(null)\n    setHovered(null)\n  }, [cancel])\n\n  const resume = useCallback(() => setSuspended(false), [])\n\n  return {\n    active: suspended ? null : pinned ?? hovered,\n    isPinned: Boolean(pinned),\n    open,\n    scheduleClose,\n    keepOpen,\n    togglePin,\n    dismiss,\n    suspend,\n    resume,\n  }\n}\n\nexport default useDetailHoverIntent\n"],"names":["useCallback","useEffect","useRef","useState","DETAIL_CLOSE_DELAY_MS","useDetailHoverIntent","hovered","setHovered","pinned","setPinned","suspended","setSuspended","timer","cancel","current","clearTimeout","open","item","anchor","scheduleClose","setTimeout","keepOpen","togglePin","prev","$id","dismiss","suspend","resume","active","isPinned","Boolean"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,WAAW,EAAEC,SAAS,EAAEC,MAAM,EAAEC,QAAQ,QAAQ,QAAO;AAEhE;;;;;;;;;CASC,GACD,OAAO,MAAMC,wBAAwB,IAAG;AAmCxC;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC;IACd,MAAM,CAACC,SAASC,WAAW,GAAGJ,SAAiC;IAC/D,MAAM,CAACK,QAAQC,UAAU,GAAGN,SAAiC;IAC7D,MAAM,CAACO,WAAWC,aAAa,GAAGR,SAAS;IAC3C,MAAMS,QAAQV,OAA6C;IAE3D,MAAMW,SAASb,YAAY;QACzB,IAAIY,MAAME,OAAO,EAAE;YACjBC,aAAaH,MAAME,OAAO;YAC1BF,MAAME,OAAO,GAAG;QAClB;IACF,GAAG,EAAE;IAEL,wDAAwD;IACxDb,UAAU,IAAMY,QAAQ;QAACA;KAAO;IAEhC,MAAMG,OAAOhB,YACX,CAACiB,MAASC;QACR,IAAIR,WAAW;QACfG;QACAN,WAAW;YAAEU;YAAMC;QAAO;IAC5B,GACA;QAACL;QAAQH;KAAU;IAGrB,MAAMS,gBAAgBnB,YAAY;QAChCa;QACAD,MAAME,OAAO,GAAGM,WAAW,IAAMb,WAAW,OAAOH;IACrD,GAAG;QAACS;KAAO;IAEX,MAAMQ,WAAWrB,YAAY,IAAMa,UAAU;QAACA;KAAO;IAErD,MAAMS,YAAYtB,YAAY,CAACiB,MAASC;QACtC,IAAIR,WAAW;QACfG;QACAJ,UAAU,CAACc;gBAAkBA;mBAARA,QAAQA,EAAAA,aAAAA,KAAKN,IAAI,qBAATM,WAAWC,GAAG,OAAKP,wBAAAA,KAAMO,GAAG,IAAG,OAAO;gBAAEP;gBAAMC;YAAO;;QAClFX,WAAW;YAAEU;YAAMC;QAAO;IAC5B,GAAG;QAACL;QAAQH;KAAU;IAEtB,MAAMe,UAAUzB,YAAY;QAC1Ba;QACAJ,UAAU;QACVF,WAAW;IACb,GAAG;QAACM;KAAO;IAEX,MAAMa,UAAU1B,YAAY;QAC1Ba;QACAF,aAAa;QACbF,UAAU;QACVF,WAAW;IACb,GAAG;QAACM;KAAO;IAEX,MAAMc,SAAS3B,YAAY,IAAMW,aAAa,QAAQ,EAAE;IAExD,OAAO;QACLiB,QAAQlB,YAAY,OAAOF,iBAAAA,SAAUF;QACrCuB,UAAUC,QAAQtB;QAClBQ;QACAG;QACAE;QACAC;QACAG;QACAC;QACAC;IACF;AACF;AAEA,eAAetB,qBAAoB"}

package/src/lib/hooks/use-document-repair-callbacks.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @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.
+ */
+/**
+ * `Edit ▸ Repair page` — strip what the canvas cannot render and keep
+ * everything that still works (AGL-2555).
+ *
+ * ⚠️ Never silent. The repair is computed first and shown to the author as a
+ * list of what it would remove, move and relink; nothing is written until
+ * they accept it. A quiet repair that deletes content is worse than the
+ * corruption it is treating, because the author never learns which of their
+ * work is gone.
+ *
+ * A sound document says so and writes nothing at all — an author who runs
+ * this on a hunch should get an answer, not an undo entry.
+ */
+export declare function useRepairDocumentCallback(
+/** What this editor edits — 'page' on a screen, 'document' elsewhere. */
+noun?: string): () => Promise<void>;
+/**
+ * `Edit ▸ Clear canvas` — empty the document without touching the screen
+ * (AGL-2554).
+ *
+ * The screen record, its SEO fields, the layout binding, the parent and
+ * slug, the id and the version history all stay. Deleting the screen and
+ * recreating it is what an author had to do instead, and that throws every
+ * one of those away — and pushes a fresh screen back through the window
+ * where a blank page is briefly live.
+ *
+ * Works on a document the hierarchy cannot render, which is the case that
+ * needs it most: `'Invalid node'` rows are not selectable, so Delete Element
+ * cannot reach them, and Add Element only appends.
+ */
+export declare function useClearCanvasCallback(
+/** What this editor edits — 'page' on a screen, 'document' elsewhere. */
+noun?: string): () => Promise<void>;
+export default useRepairDocumentCallback;

package/src/lib/hooks/use-document-repair-callbacks.js

@@ -0,0 +1,237 @@
+/**
+ * @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 { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { canvas, clearCanvasNodes, components, repairCanvasNodes } from "@aglyn/aglyn";
+import * as Besigner from "@aglyn/besigner";
+import { useConfirmationContext } from "@aglyn/shared-ui-jsx";
+import Alert from "@mui/material/Alert";
+import Box from "@mui/material/Box";
+import Typography from "@mui/material/Typography";
+import { useCallback } from "react";
+/**
+ * Replaces the whole node map as ONE undoable step, without the foreign-node
+ * overlay `applyNodes` carries.
+ *
+ * That overlay is the interesting part. `applyNodes` re-applies every node a
+ * peer has touched (`withForeignNodes(map, 0)`) because the maps IT serves —
+ * a raw-JSON paste, a per-browser draft the crash net offers back — were
+ * composed without any knowledge of the peer's later work, and publishing
+ * them would roll that work back under this session's id (AGL-2486).
+ *
+ * Neither caller here is composed elsewhere. Both read the LIVE map at click
+ * time and hand back a transformation of it, so there is no staleness for
+ * the overlay to protect against — and applying it would be actively wrong:
+ * a repair would have the peer's copy of the very nodes it just removed put
+ * straight back, and a clear would be left holding whatever the peer had
+ * touched, parented to elements that no longer exist. Which is the orphan
+ * shape AGL-1363 is about.
+ *
+ * A clear DOES discard a co-editor's work, and nothing here pretends
+ * otherwise — {@link useClearCanvasCallback} says so in the dialog when
+ * there is a peer to lose.
+ */ function replaceDocument(nodes) {
+    canvas.saveHistory();
+    canvas.setNodes(nodes);
+    Besigner.focus.clearFocusStatus();
+}
+/**
+ * Whether the component registry is populated enough to be trusted about
+ * what an element type IS.
+ *
+ * An empty registry answers "unknown" for every component in the document,
+ * and a repair that believed it would delete all of it — the same shape as a
+ * stubbed resolver making every capacity ceiling read zero. So the check is
+ * simply not offered until there is something to check against.
+ */ function componentResolver() {
+    var _components_factories;
+    if (!Object.keys((_components_factories = components.factories) != null ? _components_factories : {}).length) return undefined;
+    return (componentId)=>Boolean(components.getFactory(componentId));
+}
+/** Groups findings for the preview, most consequential first. */ function summarize(result) {
+    const removed = result.findings.filter((f)=>f.action === 'removed');
+    const moved = result.findings.filter((f)=>f.action === 'reparented');
+    const linked = result.findings.filter((f)=>f.action === 'unlinked' || f.action === 'relisted');
+    return {
+        removed,
+        moved,
+        linked
+    };
+}
+function FindingList({ title, findings }) {
+    if (!findings.length) return null;
+    return /*#__PURE__*/ _jsxs(Box, {
+        sx: {
+            mt: 2
+        },
+        children: [
+            /*#__PURE__*/ _jsx(Typography, {
+                variant: "subtitle2",
+                children: title
+            }),
+            /*#__PURE__*/ _jsxs(Box, {
+                component: "ul",
+                sx: {
+                    m: 0,
+                    pl: 3
+                },
+                children: [
+                    findings.slice(0, 12).map((finding, index)=>{
+                        var _finding_label;
+                        return /*#__PURE__*/ _jsxs(Typography, {
+                            component: "li",
+                            variant: "body2",
+                            children: [
+                                /*#__PURE__*/ _jsx("strong", {
+                                    children: (_finding_label = finding.label) != null ? _finding_label : finding.nodeId
+                                }),
+                                ' — ',
+                                finding.detail
+                            ]
+                        }, `${finding.nodeId}-${index}`);
+                    }),
+                    findings.length > 12 ? /*#__PURE__*/ _jsx(Typography, {
+                        component: "li",
+                        variant: "body2",
+                        color: "text.secondary",
+                        children: `and ${findings.length - 12} more`
+                    }) : null
+                ]
+            })
+        ]
+    });
+}
+/**
+ * `Edit ▸ Repair page` — strip what the canvas cannot render and keep
+ * everything that still works (AGL-2555).
+ *
+ * ⚠️ Never silent. The repair is computed first and shown to the author as a
+ * list of what it would remove, move and relink; nothing is written until
+ * they accept it. A quiet repair that deletes content is worse than the
+ * corruption it is treating, because the author never learns which of their
+ * work is gone.
+ *
+ * A sound document says so and writes nothing at all — an author who runs
+ * this on a hunch should get an answer, not an undo entry.
+ */ export function useRepairDocumentCallback(/** What this editor edits — 'page' on a screen, 'document' elsewhere. */ noun = 'document') {
+    const { confirm } = useConfirmationContext();
+    return useCallback(async ()=>{
+        const current = canvas.toJSON().nodes;
+        const result = repairCanvasNodes(current, {
+            isKnownComponent: componentResolver()
+        });
+        if (result.healthy) {
+            await confirm({
+                title: 'Nothing to repair',
+                description: `Every element is intact and connected to the ${noun}. Nothing was changed.`,
+                confirmationText: 'Close',
+                cancellationButtonProps: {
+                    sx: {
+                        display: 'none'
+                    }
+                }
+            }).catch(()=>{});
+            return;
+        }
+        const { removed, moved, linked } = summarize(result);
+        return confirm({
+            title: `Repair ${noun}`,
+            description: /*#__PURE__*/ _jsxs(Box, {
+                children: [
+                    /*#__PURE__*/ _jsx(Typography, {
+                        variant: "body2",
+                        children: `This ${noun} has ${result.findings.length} problem${result.findings.length === 1 ? '' : 's'}. ${result.kept} element${result.kept === 1 ? '' : 's'} will be kept.`
+                    }),
+                    removed.length ? /*#__PURE__*/ _jsx(Alert, {
+                        severity: "warning",
+                        sx: {
+                            mt: 2
+                        },
+                        children: `${removed.length} element${removed.length === 1 ? ' will be' : 's will be'} removed. This cannot be recovered after you save, though Undo will step back before it.`
+                    }) : null,
+                    /*#__PURE__*/ _jsx(FindingList, {
+                        title: "Removed",
+                        findings: removed
+                    }),
+                    /*#__PURE__*/ _jsx(FindingList, {
+                        title: "Moved to the top level",
+                        findings: moved
+                    }),
+                    /*#__PURE__*/ _jsx(FindingList, {
+                        title: "Reconnected",
+                        findings: linked
+                    })
+                ]
+            }),
+            confirmationText: 'Repair',
+            confirmationButtonProps: {
+                color: removed.length ? 'error' : 'primary'
+            }
+        }).then(()=>replaceDocument(result.nodes)).catch(()=>{});
+    }, [
+        confirm,
+        noun
+    ]);
+}
+/**
+ * `Edit ▸ Clear canvas` — empty the document without touching the screen
+ * (AGL-2554).
+ *
+ * The screen record, its SEO fields, the layout binding, the parent and
+ * slug, the id and the version history all stay. Deleting the screen and
+ * recreating it is what an author had to do instead, and that throws every
+ * one of those away — and pushes a fresh screen back through the window
+ * where a blank page is briefly live.
+ *
+ * Works on a document the hierarchy cannot render, which is the case that
+ * needs it most: `'Invalid node'` rows are not selectable, so Delete Element
+ * cannot reach them, and Add Element only appends.
+ */ export function useClearCanvasCallback(/** What this editor edits — 'page' on a screen, 'document' elsewhere. */ noun = 'document') {
+    const { confirm } = useConfirmationContext();
+    return useCallback(()=>{
+        const remote = canvas.hasRemoteEdits;
+        return confirm({
+            title: 'Clear canvas?',
+            description: /*#__PURE__*/ _jsxs(Box, {
+                children: [
+                    /*#__PURE__*/ _jsx(Typography, {
+                        variant: "body2",
+                        children: `Every element will be removed. The ${noun} itself — its settings, its address and its version history — is not affected, and Undo steps back.`
+                    }),
+                    remote ? /*#__PURE__*/ _jsx(Alert, {
+                        severity: "warning",
+                        sx: {
+                            mt: 2
+                        },
+                        children: `Someone else has edited this ${noun} since you opened it. Clearing removes their work too.`
+                    }) : null
+                ]
+            }),
+            confirmationText: 'Clear canvas',
+            confirmationButtonProps: {
+                color: 'error'
+            }
+        }).then(()=>{
+            const current = canvas.toJSON().nodes;
+            replaceDocument(clearCanvasNodes(current));
+        }).catch(()=>{});
+    }, [
+        confirm,
+        noun
+    ]);
+}
+export default useRepairDocumentCallback;
+
+//# sourceMappingURL=use-document-repair-callbacks.js.map

package/src/lib/hooks/use-document-repair-callbacks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/hooks/use-document-repair-callbacks.tsx"],"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 type * as Aglyn from '@aglyn/aglyn'\nimport {\n  canvas,\n  clearCanvasNodes,\n  components,\n  repairCanvasNodes,\n} from '@aglyn/aglyn'\nimport * as Besigner from '@aglyn/besigner'\nimport { useConfirmationContext } from '@aglyn/shared-ui-jsx'\nimport Alert from '@mui/material/Alert'\nimport Box from '@mui/material/Box'\nimport Typography from '@mui/material/Typography'\nimport { useCallback } from 'react'\n\n/**\n * Replaces the whole node map as ONE undoable step, without the foreign-node\n * overlay `applyNodes` carries.\n *\n * That overlay is the interesting part. `applyNodes` re-applies every node a\n * peer has touched (`withForeignNodes(map, 0)`) because the maps IT serves —\n * a raw-JSON paste, a per-browser draft the crash net offers back — were\n * composed without any knowledge of the peer's later work, and publishing\n * them would roll that work back under this session's id (AGL-2486).\n *\n * Neither caller here is composed elsewhere. Both read the LIVE map at click\n * time and hand back a transformation of it, so there is no staleness for\n * the overlay to protect against — and applying it would be actively wrong:\n * a repair would have the peer's copy of the very nodes it just removed put\n * straight back, and a clear would be left holding whatever the peer had\n * touched, parented to elements that no longer exist. Which is the orphan\n * shape AGL-1363 is about.\n *\n * A clear DOES discard a co-editor's work, and nothing here pretends\n * otherwise — {@link useClearCanvasCallback} says so in the dialog when\n * there is a peer to lose.\n */\nfunction replaceDocument(nodes: Record<string, any>): void {\n  canvas.saveHistory()\n  canvas.setNodes(nodes as never)\n  Besigner.focus.clearFocusStatus()\n}\n\n/**\n * Whether the component registry is populated enough to be trusted about\n * what an element type IS.\n *\n * An empty registry answers \"unknown\" for every component in the document,\n * and a repair that believed it would delete all of it — the same shape as a\n * stubbed resolver making every capacity ceiling read zero. So the check is\n * simply not offered until there is something to check against.\n */\nfunction componentResolver():\n  | ((componentId: string) => boolean)\n  | undefined {\n  if (!Object.keys(components.factories ?? {}).length) return undefined\n  return (componentId: string) =>\n    Boolean(components.getFactory(componentId as never))\n}\n\n/** Groups findings for the preview, most consequential first. */\nfunction summarize(result: Aglyn.CanvasRepairResult) {\n  const removed = result.findings.filter((f) => f.action === 'removed')\n  const moved = result.findings.filter((f) => f.action === 'reparented')\n  const linked = result.findings.filter(\n    (f) => f.action === 'unlinked' || f.action === 'relisted',\n  )\n  return { removed, moved, linked }\n}\n\nfunction FindingList({\n  title,\n  findings,\n}: {\n  title: string\n  findings: Aglyn.CanvasRepairFinding[]\n}) {\n  if (!findings.length) return null\n  return (\n    <Box sx={{ mt: 2 }}>\n      <Typography variant=\"subtitle2\">{title}</Typography>\n      <Box component=\"ul\" sx={{ m: 0, pl: 3 }}>\n        {/* Capped: a badly damaged document can carry dozens, and a dialog\n            the author has to scroll to reach its own buttons is one they\n            will dismiss without reading. */}\n        {findings.slice(0, 12).map((finding, index) => (\n          <Typography\n            component=\"li\"\n            variant=\"body2\"\n            key={`${finding.nodeId}-${index}`}\n          >\n            <strong>{finding.label ?? finding.nodeId}</strong>\n            {' — '}\n            {finding.detail}\n          </Typography>\n        ))}\n        {findings.length > 12 ? (\n          <Typography component=\"li\" variant=\"body2\" color=\"text.secondary\">\n            {`and ${findings.length - 12} more`}\n          </Typography>\n        ) : null}\n      </Box>\n    </Box>\n  )\n}\n\n/**\n * `Edit ▸ Repair page` — strip what the canvas cannot render and keep\n * everything that still works (AGL-2555).\n *\n * ⚠️ Never silent. The repair is computed first and shown to the author as a\n * list of what it would remove, move and relink; nothing is written until\n * they accept it. A quiet repair that deletes content is worse than the\n * corruption it is treating, because the author never learns which of their\n * work is gone.\n *\n * A sound document says so and writes nothing at all — an author who runs\n * this on a hunch should get an answer, not an undo entry.\n */\nexport function useRepairDocumentCallback(\n  /** What this editor edits — 'page' on a screen, 'document' elsewhere. */\n  noun = 'document',\n): () => Promise<void> {\n  const { confirm } = useConfirmationContext()\n\n  return useCallback(async () => {\n    const current = canvas.toJSON().nodes as Record<string, any>\n    const result = repairCanvasNodes(current, {\n      isKnownComponent: componentResolver(),\n    })\n\n    if (result.healthy) {\n      await confirm({\n        title: 'Nothing to repair',\n        description: `Every element is intact and connected to the ${noun}. Nothing was changed.`,\n        confirmationText: 'Close',\n        cancellationButtonProps: { sx: { display: 'none' } },\n      }).catch(() => {})\n      return\n    }\n\n    const { removed, moved, linked } = summarize(result)\n    return confirm({\n      title: `Repair ${noun}`,\n      description: (\n        <Box>\n          <Typography variant=\"body2\">\n            {`This ${noun} has ${result.findings.length} problem${\n              result.findings.length === 1 ? '' : 's'\n            }. ${result.kept} element${\n              result.kept === 1 ? '' : 's'\n            } will be kept.`}\n          </Typography>\n          {removed.length ? (\n            <Alert severity=\"warning\" sx={{ mt: 2 }}>\n              {`${removed.length} element${\n                removed.length === 1 ? ' will be' : 's will be'\n              } removed. This cannot be recovered after you save, though Undo will step back before it.`}\n            </Alert>\n          ) : null}\n          <FindingList title=\"Removed\" findings={removed} />\n          <FindingList title=\"Moved to the top level\" findings={moved} />\n          <FindingList title=\"Reconnected\" findings={linked} />\n        </Box>\n      ),\n      confirmationText: 'Repair',\n      confirmationButtonProps: { color: removed.length ? 'error' : 'primary' },\n    })\n      .then(() => replaceDocument(result.nodes))\n      .catch(() => {})\n  }, [confirm, noun])\n}\n\n/**\n * `Edit ▸ Clear canvas` — empty the document without touching the screen\n * (AGL-2554).\n *\n * The screen record, its SEO fields, the layout binding, the parent and\n * slug, the id and the version history all stay. Deleting the screen and\n * recreating it is what an author had to do instead, and that throws every\n * one of those away — and pushes a fresh screen back through the window\n * where a blank page is briefly live.\n *\n * Works on a document the hierarchy cannot render, which is the case that\n * needs it most: `'Invalid node'` rows are not selectable, so Delete Element\n * cannot reach them, and Add Element only appends.\n */\nexport function useClearCanvasCallback(\n  /** What this editor edits — 'page' on a screen, 'document' elsewhere. */\n  noun = 'document',\n): () => Promise<void> {\n  const { confirm } = useConfirmationContext()\n\n  return useCallback(() => {\n    const remote = canvas.hasRemoteEdits\n    return confirm({\n      title: 'Clear canvas?',\n      description: (\n        <Box>\n          <Typography variant=\"body2\">\n            {`Every element will be removed. The ${noun} itself — its settings, its address and its version history — is not affected, and Undo steps back.`}\n          </Typography>\n          {remote ? (\n            <Alert severity=\"warning\" sx={{ mt: 2 }}>\n              {`Someone else has edited this ${noun} since you opened it. Clearing removes their work too.`}\n            </Alert>\n          ) : null}\n        </Box>\n      ),\n      confirmationText: 'Clear canvas',\n      confirmationButtonProps: { color: 'error' },\n    })\n      .then(() => {\n        const current = canvas.toJSON().nodes as Record<string, any>\n        replaceDocument(clearCanvasNodes(current))\n      })\n      .catch(() => {})\n  }, [confirm, noun])\n}\n\nexport default useRepairDocumentCallback\n"],"names":["canvas","clearCanvasNodes","components","repairCanvasNodes","Besigner","useConfirmationContext","Alert","Box","Typography","useCallback","replaceDocument","nodes","saveHistory","setNodes","focus","clearFocusStatus","componentResolver","Object","keys","factories","length","undefined","componentId","Boolean","getFactory","summarize","result","removed","findings","filter","f","action","moved","linked","FindingList","title","sx","mt","variant","component","m","pl","slice","map","finding","index","strong","label","nodeId","detail","color","useRepairDocumentCallback","noun","confirm","current","toJSON","isKnownComponent","healthy","description","confirmationText","cancellationButtonProps","display","catch","kept","severity","confirmationButtonProps","then","useClearCanvasCallback","remote","hasRemoteEdits"],"mappings":"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"}

package/src/lib/hooks/use-insert-token-options.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @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 type * as Aglyn from '@aglyn/aglyn';
+import { type BindingOption } from '../contexts/binding-picker-context';
+import type { TokenLabelContext } from '../utils/token-segments';
+export interface InsertTokenOptionsResult {
+    /**
+     * The full grouped picker list (AGL-583): host bindings first (AGL-100),
+     * then the data-placeholder catalogs. Entry/Collection stay browsable
+     * even out of context — with a hint saying where they resolve — while
+     * the Dataset item group only appears inside a resolvable repeatable.
+     */
+    options: BindingOption[];
+    /** Display-name resolution inputs for pill rendering (AGL-586). */
+    labelContext: TokenLabelContext;
+}
+/**
+ * A component's or layout's own declared props as picker options (AGL-1335).
+ * A free-text field offers every one; a field with no text box is handed only
+ * the properties it can be bound to (see `withPropertyBinding`).
+ *
+ * Names are filtered by the SAME pattern the graft requires, so a picker can
+ * never offer a token that would not substitute.
+ */
+export declare function componentPropBindingOptions(componentProps: readonly Aglyn.ReusableComponentProp[] | undefined | null, owner?: 'component' | 'layout'): BindingOption[];
+/** The picker's second line for a property: what a page that sets nothing gets. */
+export declare function componentPropDefaultPreview(prop: Aglyn.ReusableComponentProp): string;
+/**
+ * Assembles the insert-picker options for a canvas node from ITS context
+ * (AGL-583, extracted for AGL-586 so the attributes panel and the inline
+ * text editor share one walk): the ancestor chain is scanned for a
+ * repeatable container (dataset-item tokens need its model fields) and for
+ * a Collection entries block (entry tokens resolve right there, not only
+ * on entry pages). `repeatDataset` persists a dataset id OR a legacy
+ * display name — either resolves against the entity picker options.
+ */
+export declare function useInsertTokenOptions(node?: Aglyn.NodeSchema<any> | null): InsertTokenOptionsResult;
+export default useInsertTokenOptions;