@liminis/editor 0.7.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -4
- package/dist/app/editor/CorrectionPanelPlugin.js +3 -4
- package/dist/app/editor/nodes/C4Component.js +129 -41
- package/dist/app/editor/nodes/DiagramContextMenu.d.ts +21 -1
- package/dist/app/editor/nodes/DiagramContextMenu.js +24 -3
- package/dist/app/editor/nodes/TransclusionComponent.js +1 -1
- package/dist/app/editor/nodes/c4-layout.d.ts +16 -0
- package/dist/app/editor/nodes/c4-layout.js +38 -0
- package/dist/app/editor/nodes/transclusion-render.d.ts +18 -2
- package/dist/app/editor/nodes/transclusion-render.js +46 -7
- package/dist/app/mapper/mdastToLexical.js +5 -31
- package/dist/styles.css +29 -0
- package/dist/utils/file-types.d.ts +16 -0
- package/dist/utils/file-types.js +31 -0
- package/docs/decisions/adr-119-block-transclusion.md +7 -0
- package/docs/decisions/adr-192-transclusion-source-affordance.md +103 -0
- package/docs/decisions/adr-194-c4-layout-merge-at-commit.md +101 -0
- package/docs/decisions/adr-203-c4-release-shift-compensation.md +188 -0
- package/package.json +46 -46
|
@@ -5,7 +5,7 @@ import { $isLinkNode } from '@lexical/link';
|
|
|
5
5
|
import { $createHorizontalRuleNode, $createImageNode, $isImageNode, $createCalloutNode, $createToggleContainerNode, $createToggleTitleNode, $createToggleContentNode, $createEquationNode, $isEquationNode, $createFootnoteNode, $isFootnoteNode, $createBlockAnchorNode, $isBlockAnchorNode, $createHtmlNode, $isHtmlNode, $createMermaidNode, $createC4Node, $createFrontmatterNode, $createCustomLinkNode, $createCustomListNode, $createDefinitionListNode, $createDefinitionTermNode, $createDefinitionDescriptionNode, $createCustomListItemNode, $createListItemParagraphBreakNode, $createTransclusionNode, } from '../editor/nodes/index.js';
|
|
6
6
|
import { parseFormattedAlias } from '../editor/MarkdownShortcutsPlugin.js';
|
|
7
7
|
import { $createTableNode, $createTableRowNode, $createTableCellNode, TableCellHeaderStates } from '@lexical/table';
|
|
8
|
-
import {
|
|
8
|
+
import { wikiTargetToUrl, wikiLinkTargetToUrl } from '../../utils/file-types.js';
|
|
9
9
|
// Set only while a *WithOffsets import is running, so convertText/convertInlineCode
|
|
10
10
|
// can record spans without threading a collector parameter through every one of
|
|
11
11
|
// this file's many recursive conversion functions. Lexical updates run their
|
|
@@ -271,7 +271,7 @@ function convertBlockNode(node) {
|
|
|
271
271
|
const wikiLink = node;
|
|
272
272
|
const target = wikiLink.value || '';
|
|
273
273
|
const rawDisplayText = wikiLink.data?.alias || target;
|
|
274
|
-
const url =
|
|
274
|
+
const url = wikiTargetToUrl(target);
|
|
275
275
|
const paragraph = $createParagraphNode();
|
|
276
276
|
const link = $createCustomLinkNode(url);
|
|
277
277
|
link.setWikiLinkOrigin(true);
|
|
@@ -861,35 +861,9 @@ function convertInlineNode(node) {
|
|
|
861
861
|
return [$createTextNode('[[]]')];
|
|
862
862
|
}
|
|
863
863
|
const displayText = wikiLink.data?.alias || target;
|
|
864
|
-
// Convert to URL, preserving semantic intent
|
|
865
|
-
//
|
|
866
|
-
|
|
867
|
-
let url;
|
|
868
|
-
if (target.startsWith('#')) {
|
|
869
|
-
// Anchor-only: #anchor → #anchor
|
|
870
|
-
url = target;
|
|
871
|
-
}
|
|
872
|
-
else if (target.endsWith('/')) {
|
|
873
|
-
// Directory link: preserve trailing slash for semantic clarity
|
|
874
|
-
// Navigation layer will resolve to index.md or README.md
|
|
875
|
-
url = target;
|
|
876
|
-
}
|
|
877
|
-
else if (target.includes('#')) {
|
|
878
|
-
// Path with anchor: page#anchor → page.md#anchor (or dir/#anchor preserved)
|
|
879
|
-
const [path, anchor] = target.split('#', 2);
|
|
880
|
-
if (path.endsWith('/')) {
|
|
881
|
-
// Directory with anchor - preserve for navigation layer
|
|
882
|
-
url = target;
|
|
883
|
-
}
|
|
884
|
-
else {
|
|
885
|
-
const pathWithExt = getFileType(path) !== 'unknown' ? path : `${path}.md`;
|
|
886
|
-
url = `${pathWithExt}#${anchor}`;
|
|
887
|
-
}
|
|
888
|
-
}
|
|
889
|
-
else {
|
|
890
|
-
// Simple path: page → page.md (unless it already has a recognized extension)
|
|
891
|
-
url = getFileType(target) !== 'unknown' ? target : `${target}.md`;
|
|
892
|
-
}
|
|
864
|
+
// Convert to URL, preserving semantic intent (anchor, directory and
|
|
865
|
+
// extension handling live in wikiLinkTargetToUrl)
|
|
866
|
+
const url = wikiLinkTargetToUrl(target);
|
|
893
867
|
const link = $createCustomLinkNode(url);
|
|
894
868
|
// Marks this link as genuine author-written wiki-link syntax, so export
|
|
895
869
|
// (convertLinkNode) always emits it back as a wiki-link even when a host
|
package/dist/styles.css
CHANGED
|
@@ -717,6 +717,30 @@ body {
|
|
|
717
717
|
font-weight: 600;
|
|
718
718
|
}
|
|
719
719
|
|
|
720
|
+
/* Source badge (#192): trailing "↗" that navigates to the transcluded block.
|
|
721
|
+
It reuses `.editor-link` so the `modifier-held` / `links-clickable` cursor
|
|
722
|
+
rules apply unchanged; the rules below only size it down and cancel the
|
|
723
|
+
shared link hover underline/opacity, which look wrong on a lone glyph. */
|
|
724
|
+
.editor-transclusion-wrap {
|
|
725
|
+
display: inline;
|
|
726
|
+
}
|
|
727
|
+
|
|
728
|
+
.editor-transclusion-source {
|
|
729
|
+
margin-inline-start: 0.25em;
|
|
730
|
+
font-size: 0.75em;
|
|
731
|
+
line-height: 1;
|
|
732
|
+
vertical-align: super;
|
|
733
|
+
user-select: none;
|
|
734
|
+
}
|
|
735
|
+
|
|
736
|
+
.editor-link.editor-transclusion-source,
|
|
737
|
+
.editor-link.editor-transclusion-source:hover,
|
|
738
|
+
.modifier-held .editor-link.editor-transclusion-source:hover,
|
|
739
|
+
.links-clickable .editor-link.editor-transclusion-source:hover {
|
|
740
|
+
text-decoration: none;
|
|
741
|
+
opacity: 1;
|
|
742
|
+
}
|
|
743
|
+
|
|
720
744
|
/* Tables */
|
|
721
745
|
.editor-table {
|
|
722
746
|
width: 100%;
|
|
@@ -2653,6 +2677,11 @@ body {
|
|
|
2653
2677
|
text-decoration: underline !important;
|
|
2654
2678
|
}
|
|
2655
2679
|
|
|
2680
|
+
/* The source badge is a lone glyph; an underline reads as noise in print */
|
|
2681
|
+
.editor-link.editor-transclusion-source {
|
|
2682
|
+
text-decoration: none !important;
|
|
2683
|
+
}
|
|
2684
|
+
|
|
2656
2685
|
/* Tables */
|
|
2657
2686
|
.editor-table {
|
|
2658
2687
|
page-break-inside: auto !important;
|
|
@@ -8,3 +8,19 @@ export type FileType = 'markdown' | 'image' | 'pdf' | 'mermaid' | 'code' | 'rema
|
|
|
8
8
|
* @returns The detected file type
|
|
9
9
|
*/
|
|
10
10
|
export declare function getFileType(path: string | null): FileType;
|
|
11
|
+
/**
|
|
12
|
+
* Normalise a wiki-link / transclusion target to the URL form carried on a
|
|
13
|
+
* link node: a target with a recognised extension is kept as-is, anything else
|
|
14
|
+
* gets `.md` appended (`[[page]]` -> `page.md`). Shared by the mapper and the
|
|
15
|
+
* transclusion renderer so `[[file#^id]]` and `![[file#^id]]` hand the host the
|
|
16
|
+
* same `url` shape.
|
|
17
|
+
*/
|
|
18
|
+
export declare function wikiTargetToUrl(target: string): string;
|
|
19
|
+
/**
|
|
20
|
+
* Full wiki-link target -> URL derivation, covering the anchor and directory
|
|
21
|
+
* forms the bare {@link wikiTargetToUrl} does not: `#anchor` and `dir/` are
|
|
22
|
+
* kept, `page#anchor` becomes `page.md#anchor`. Shared by the mapper's inline
|
|
23
|
+
* wiki-link conversion and the transclusion renderer's nested links, so a link
|
|
24
|
+
* inside transcluded content navigates to the same URL as a top-level one.
|
|
25
|
+
*/
|
|
26
|
+
export declare function wikiLinkTargetToUrl(target: string): string;
|
package/dist/utils/file-types.js
CHANGED
|
@@ -44,3 +44,34 @@ export function getFileType(path) {
|
|
|
44
44
|
return 'code';
|
|
45
45
|
return 'unknown';
|
|
46
46
|
}
|
|
47
|
+
/**
|
|
48
|
+
* Normalise a wiki-link / transclusion target to the URL form carried on a
|
|
49
|
+
* link node: a target with a recognised extension is kept as-is, anything else
|
|
50
|
+
* gets `.md` appended (`[[page]]` -> `page.md`). Shared by the mapper and the
|
|
51
|
+
* transclusion renderer so `[[file#^id]]` and `![[file#^id]]` hand the host the
|
|
52
|
+
* same `url` shape.
|
|
53
|
+
*/
|
|
54
|
+
export function wikiTargetToUrl(target) {
|
|
55
|
+
return getFileType(target) !== 'unknown' ? target : `${target}.md`;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Full wiki-link target -> URL derivation, covering the anchor and directory
|
|
59
|
+
* forms the bare {@link wikiTargetToUrl} does not: `#anchor` and `dir/` are
|
|
60
|
+
* kept, `page#anchor` becomes `page.md#anchor`. Shared by the mapper's inline
|
|
61
|
+
* wiki-link conversion and the transclusion renderer's nested links, so a link
|
|
62
|
+
* inside transcluded content navigates to the same URL as a top-level one.
|
|
63
|
+
*/
|
|
64
|
+
export function wikiLinkTargetToUrl(target) {
|
|
65
|
+
// Anchor-only (#anchor) and directory links (trailing slash) are preserved;
|
|
66
|
+
// the navigation layer resolves directories to index.md / README.md.
|
|
67
|
+
if (target.startsWith('#') || target.endsWith('/'))
|
|
68
|
+
return target;
|
|
69
|
+
if (target.includes('#')) {
|
|
70
|
+
const [path, anchor] = target.split('#', 2);
|
|
71
|
+
// Directory with anchor: preserve for the navigation layer
|
|
72
|
+
if (path.endsWith('/'))
|
|
73
|
+
return target;
|
|
74
|
+
return `${wikiTargetToUrl(path)}#${anchor}`;
|
|
75
|
+
}
|
|
76
|
+
return wikiTargetToUrl(target);
|
|
77
|
+
}
|
|
@@ -157,6 +157,13 @@ block content" (FR-015 — any `^id`-carrying block is a valid target, not
|
|
|
157
157
|
just checkboxes) without committing to full visual parity for every mdast
|
|
158
158
|
construct.
|
|
159
159
|
|
|
160
|
+
> **Amended 2026-11-13 — the "inert link text" part of this clause no longer
|
|
161
|
+
> holds.** A `wikiLink` inside transcluded content now renders as a live
|
|
162
|
+
> anchor, and every transclusion carries a trailing "↗" source badge that
|
|
163
|
+
> navigates to its own source block. See ADR-192
|
|
164
|
+
> (`adr-192-transclusion-source-affordance.md`). The renderer is still partial
|
|
165
|
+
> and still render-only; only link navigation changed.
|
|
166
|
+
|
|
160
167
|
### 9. `openLink` gets an additive optional `blockId` parameter
|
|
161
168
|
|
|
162
169
|
A host that has not implemented block-aware navigation still receives
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# ADR-192: Transclusions Navigate to Their Source Through a Trailing Badge
|
|
2
|
+
|
|
3
|
+
**Date:** 2026-11-13
|
|
4
|
+
**Status:** Accepted
|
|
5
|
+
**Supersedes:** none
|
|
6
|
+
**Amends:** ADR-119 (§8, nested link navigation)
|
|
7
|
+
**Issue:** #192 (verveguy/liminis-editor)
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
`![[file#^id]]` transclusion (ADR-119, #119) renders the referenced block
|
|
12
|
+
inline, but the rendered output was a dead end: only `<span>`s, no `<a>`, so
|
|
13
|
+
`LinkClickPlugin` — which reacts to `a[data-href]` — never saw anything to
|
|
14
|
+
follow. A `[[file#^id]]` link was navigable; the same block embedded was not.
|
|
15
|
+
|
|
16
|
+
The block-scoped `OPEN_LINK { url, blockId }` path already exists (ADR-119 §9),
|
|
17
|
+
so the only missing piece was a link-shaped element on the transclusion.
|
|
18
|
+
|
|
19
|
+
## Decision
|
|
20
|
+
|
|
21
|
+
### 1. A trailing "↗" badge, not a whole-container link
|
|
22
|
+
|
|
23
|
+
Every transclusion renders `<a class="editor-link editor-transclusion-source"
|
|
24
|
+
data-href data-block-id>↗</a>` after its state span, in all four states
|
|
25
|
+
(resolved, unresolved, circular, depth-exceeded). It is a *sibling* of the
|
|
26
|
+
content, never an ancestor of it, so:
|
|
27
|
+
|
|
28
|
+
- `target.closest('a')` in `LinkClickPlugin` always finds the innermost anchor:
|
|
29
|
+
a wiki link inside the transcluded content wins over the badge, with no
|
|
30
|
+
`stopPropagation` ordering to maintain;
|
|
31
|
+
- no `<a>`-in-`<a>`;
|
|
32
|
+
- caret placement and selection inside the transcluded text are untouched.
|
|
33
|
+
|
|
34
|
+
`LinkClickPlugin`, `TransclusionNode`, `exportDOM` and the mdast round-trip are
|
|
35
|
+
unchanged. The badge is presentation only.
|
|
36
|
+
|
|
37
|
+
### 2. The badge carries `editor-link` but not `data-wiki-link`
|
|
38
|
+
|
|
39
|
+
`editor-link` makes the existing `modifier-held` / `links-clickable` cursor
|
|
40
|
+
rules apply with no new cursor CSS. `data-wiki-link` is deliberately absent:
|
|
41
|
+
`WikiLinkExistencePlugin` queries `a[data-wiki-link="true"]` and would resolve
|
|
42
|
+
the badge and could style it as a broken link.
|
|
43
|
+
|
|
44
|
+
### 3. `data-href` is normalised exactly as a wiki link is
|
|
45
|
+
|
|
46
|
+
`wikiTargetToUrl(target)` (in `src/utils/file-types.ts`) appends `.md` to a
|
|
47
|
+
target without a recognised extension. The mapper's duplicated expressions now
|
|
48
|
+
call it too. A host that handles block-scoped links therefore receives the same
|
|
49
|
+
`url` shape from `![[x#^id]]` as from `[[x#^id]]`.
|
|
50
|
+
|
|
51
|
+
### 4. Nested wiki links in transcluded content are now live
|
|
52
|
+
|
|
53
|
+
ADR-119 §8 left `wikiLink` inside transcluded content as inert text. That had to
|
|
54
|
+
change: with a badge present but nested links inert, the requirement that a
|
|
55
|
+
nested link navigate to *its own* target would pass vacuously. They render as
|
|
56
|
+
`<a class="editor-link" data-href data-block-id?>`, again without
|
|
57
|
+
`data-wiki-link` (the existence plugin only walks the editor's own DOM, and
|
|
58
|
+
resolver calls per nested link are not wanted).
|
|
59
|
+
|
|
60
|
+
### 5. The badge renders from props, not from resolved state
|
|
61
|
+
|
|
62
|
+
`TransclusionComponent` passes `{ file, blockId }` from its props, so the badge
|
|
63
|
+
is present and stable across debounced re-resolves. It is absent only in the
|
|
64
|
+
loading state, which is not one of the four states in scope. A nested
|
|
65
|
+
`wikiEmbed` passes its own `{ file, blockId }`, so each level navigates to its
|
|
66
|
+
own source.
|
|
67
|
+
|
|
68
|
+
### 6. `contenteditable="false"` and accessible name
|
|
69
|
+
|
|
70
|
+
The badge is `contenteditable="false"` so the caret does not land inside it. It
|
|
71
|
+
has `title` and `aria-label` "Open source block". It has no `href` or
|
|
72
|
+
`tabindex`, matching every other editor link, so keyboard activation is
|
|
73
|
+
whatever existing links support (nothing new).
|
|
74
|
+
|
|
75
|
+
## Consequences — what this costs
|
|
76
|
+
|
|
77
|
+
- **An always-present "↗" glyph** in transclusions, including editable mode.
|
|
78
|
+
Existing transclusions grow by one small element; a host that screenshots or
|
|
79
|
+
styles transclusions will see it. It can be restyled or hidden via
|
|
80
|
+
`.editor-transclusion-source` without changing the emitted event.
|
|
81
|
+
- **A larger click target in read-only mode.** A plain click on the badge
|
|
82
|
+
navigates there, where previously nothing did. Nested wiki links in
|
|
83
|
+
transcluded content also now navigate on click, which they never did.
|
|
84
|
+
- **A small `contenteditable="false"` island** inside editable content, next to
|
|
85
|
+
an inline decorator. It was verified in jsdom (a plain click is not
|
|
86
|
+
default-prevented and does not navigate) but not in a real browser, where
|
|
87
|
+
caret behaviour around inline decorators is Lexical's and the browser's call.
|
|
88
|
+
- **Not keyboard-focusable.** Consistent with existing links, but it means the
|
|
89
|
+
affordance is pointer-only until links gain `tabindex`/`href` generally.
|
|
90
|
+
- **The whole transclusion is not a link target.** Clicking the transcluded text
|
|
91
|
+
still does nothing; only the badge navigates. That was a design choice, and a
|
|
92
|
+
whole-container target can be added later without changing the event.
|
|
93
|
+
- **Unresolved/circular/depth-exceeded states pass the block id along.** The
|
|
94
|
+
host may ignore it if the block no longer exists; the file still opens, which
|
|
95
|
+
is what a user repairing a broken reference needs.
|
|
96
|
+
- **Not done: making the transcluded checkbox writable** (#181) and host-side
|
|
97
|
+
scroll-to-block (shadoworg/liminis-notes#1318).
|
|
98
|
+
|
|
99
|
+
## References
|
|
100
|
+
|
|
101
|
+
- ADR-119 — transclusion node and renderer (§8 amended, §9 reused)
|
|
102
|
+
- ADR-122 — block-anchor badge (visual vocabulary)
|
|
103
|
+
- Issue #192 (this ADR), #119 (transclusion), #181 (one logical item)
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# ADR-194: C4 Manual Positions Are Merged at the Hand-Edit Commit, Not Cleared
|
|
2
|
+
|
|
3
|
+
**Date:** 2026-11-15
|
|
4
|
+
**Status:** Accepted
|
|
5
|
+
**Supersedes:** none
|
|
6
|
+
**Amends:** none
|
|
7
|
+
**Issue:** #194 (verveguy/liminis-editor)
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
`@liminis/diagrams` 0.2.0 lets a user add elements and relationships on the
|
|
12
|
+
rendered C4 diagram. The renderer reports `onEdit(edit, { positions })`; the
|
|
13
|
+
host turns the edit into source with `applyC4Edit` and stores the reported
|
|
14
|
+
`positions`, which is the complete, already-merged map.
|
|
15
|
+
|
|
16
|
+
The C4 node could not adopt this. `C4Component` had an effect ("TASK 7") that
|
|
17
|
+
cleared the whole manual layout whenever the set of element ids differed from
|
|
18
|
+
the layout's keys. Adding one box from the diagram changes that set, so every
|
|
19
|
+
position the user had arranged would have been discarded the moment they added
|
|
20
|
+
something.
|
|
21
|
+
|
|
22
|
+
## Decision
|
|
23
|
+
|
|
24
|
+
### 1. A diagram edit replaces code and layout in one `editor.update`
|
|
25
|
+
|
|
26
|
+
`handleEdit` reads the source from the **node** (never from component state,
|
|
27
|
+
which lags by a render), calls `applyC4Edit`, and on success calls
|
|
28
|
+
`setCode(result.source)` and `setManualLayout({ positions: context.positions })`
|
|
29
|
+
in the same update. One update is one history entry, so a single undo restores
|
|
30
|
+
both. `context.positions` is stored as received: not filtered, not merged with
|
|
31
|
+
the old layout. On `{ ok: false }` nothing is mutated, so there is no history
|
|
32
|
+
entry; `code` and `message` are logged with `console.warn`.
|
|
33
|
+
|
|
34
|
+
### 2. A hand edit merges at the commit, in the same update as `setCode`
|
|
35
|
+
|
|
36
|
+
The only point where a hand edit reaches the Lexical node is `onHide`
|
|
37
|
+
(`node.setCode(codeValue)`). The merge runs there: `mergeManualLayout` keeps the
|
|
38
|
+
positions of ids still present in the parsed source and any reserved `__` key
|
|
39
|
+
(such as `__legend__`), and drops the rest. It is a no-op (same object) when
|
|
40
|
+
nothing is dropped, and yields `undefined` when nothing is left. A source that
|
|
41
|
+
fails to parse, or parses with errors, never drops anything. An unchanged close
|
|
42
|
+
no longer dirties the node.
|
|
43
|
+
|
|
44
|
+
### 3. The display renders from a `{ code, manualLayout }` snapshot
|
|
45
|
+
|
|
46
|
+
`C4DiagramDisplay` reads both from the node together, in its initial state and in
|
|
47
|
+
`registerUpdateListener`, instead of taking `code` from a prop that is synced in
|
|
48
|
+
an effect. A diagram edit or undo/redo therefore never renders new positions
|
|
49
|
+
against old code (the "visible jump" the diagrams recipe warns about).
|
|
50
|
+
|
|
51
|
+
### Alternatives rejected
|
|
52
|
+
|
|
53
|
+
- **An effect that merges when ids change.** It can run with the new layout
|
|
54
|
+
(containing the just-placed id) before the new code reaches the display, see an
|
|
55
|
+
id absent from the parsed diagram, and drop the position it was meant to keep.
|
|
56
|
+
Undo and redo have the same ordering problem. Telling diagram-originated
|
|
57
|
+
changes from hand edits with a ref flag is order-dependent and fragile.
|
|
58
|
+
|
|
59
|
+
## Consequences — what this costs
|
|
60
|
+
|
|
61
|
+
- **The layout is no longer cleared on an id-set change.** A hand-added element
|
|
62
|
+
is auto-placed beside existing pinned ones, and the result may not look as
|
|
63
|
+
tidy as a full re-layout did. "Reset to auto layout" remains the way to start
|
|
64
|
+
over.
|
|
65
|
+
- **A renamed id loses its position.** The old id is dropped and the new id has
|
|
66
|
+
none; the merge cannot tell a rename from a remove plus an add.
|
|
67
|
+
- **Clearing the source drops every position.** An empty source parses cleanly
|
|
68
|
+
with zero elements, so all positions go. Only a parse that fails, or reports
|
|
69
|
+
errors, is protected.
|
|
70
|
+
- **`setCode` callers other than the editor commit are not covered.** The merge
|
|
71
|
+
lives in `onHide`, not in `C4Node.setCode`. Anything else that later changes a
|
|
72
|
+
C4 node's code (a host, an import, collaboration) must merge the layout itself
|
|
73
|
+
or leave stale positions for removed ids. Stale keys are harmless to rendering
|
|
74
|
+
(the layout ignores unknown ids) but are written to the `@layout` fence meta
|
|
75
|
+
until the next hand edit prunes them. `C4Node` was deliberately not given this
|
|
76
|
+
logic: it must not import `@liminis/diagrams` statically (ADR-075, ADR-079).
|
|
77
|
+
- **Structural editing is only available in layout-edit mode.** The
|
|
78
|
+
interactive renderer is only mounted while the user is editing layout, and the
|
|
79
|
+
renderer shows its add affordances only in edit mode.
|
|
80
|
+
- **Hand-edit merging is validated against `parseC4` element ids**, which include
|
|
81
|
+
boundaries and nested elements (covered by tests). Whether the renderer keys
|
|
82
|
+
boundary positions identically was checked against the 0.2.0 type
|
|
83
|
+
declarations, not against a rendered diagram.
|
|
84
|
+
|
|
85
|
+
> **Amended 2026-11-16 — structural editing now shows one context menu.** The
|
|
86
|
+
> clause "Structural editing is only available in layout-edit mode" still holds,
|
|
87
|
+
> but trying the first version by hand showed that layout mode opened two
|
|
88
|
+
> overlapping menus: the renderer's own add-element menu and the editor's
|
|
89
|
+
> `DiagramContextMenu` (the renderer called `preventDefault()` but not
|
|
90
|
+
> `stopPropagation()`, so the event also reached the container's
|
|
91
|
+
> `onContextMenu`). `@liminis/diagrams` 0.2.1 added an `onContextMenu` hook that
|
|
92
|
+
> hands the host the diagram's items instead of drawing a menu. The C4 node now
|
|
93
|
+
> passes it and renders **one** `DiagramContextMenu`, with the diagram's items
|
|
94
|
+
> (elements, then boundaries) as their own groups above the editor's items; over
|
|
95
|
+
> a node the diagram offers none, so only the editor's items show. A long-press
|
|
96
|
+
> opens the same menu. Choosing an item calls the item's `select()`, so
|
|
97
|
+
> placement, the label prompt, `onEdit` and the single undo step are the
|
|
98
|
+
> diagram's own. The cost: the menu's look is now the editor's, not the
|
|
99
|
+
> renderer's, and the editor depends on `@liminis/diagrams` >= 0.2.1 (the hook
|
|
100
|
+
> is opt-in; without it the renderer's behaviour is unchanged). Guarded by
|
|
101
|
+
> `C4Component.contextmenu.test.tsx`, which uses the real renderer.
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# ADR-203: The C4 Node Cancels the Release Shift by Measuring It, Not from `onFrameChange`
|
|
2
|
+
|
|
3
|
+
**Date:** 2026-11-15
|
|
4
|
+
**Status:** Accepted
|
|
5
|
+
**Supersedes:** none
|
|
6
|
+
**Amends:** none
|
|
7
|
+
**Issue:** #203 (verveguy/liminis-editor)
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
`@liminis/diagrams` 0.2.0 (its ADR-100) grows the C4 diagram's SVG frame live while
|
|
12
|
+
a node is dragged past an edge. During the drag the renderer holds the diagram's
|
|
13
|
+
origin steady with an imperative `svg.style.transform`; on release it clears that
|
|
14
|
+
transform and the origin jumps to the natural origin of the larger frame. The
|
|
15
|
+
library leaves cancelling that jump to the host.
|
|
16
|
+
|
|
17
|
+
The editor's C4 node wraps the renderer in a flex-centred, `overflow-x: auto`
|
|
18
|
+
container. So on release the diagram jumps by the full growth for top/left growth,
|
|
19
|
+
and by half the growth for growth on any horizontal side (centring). The user sees
|
|
20
|
+
the node they just dropped move away from the pointer.
|
|
21
|
+
|
|
22
|
+
## Decision
|
|
23
|
+
|
|
24
|
+
`C4DiagramDisplay` (`src/app/editor/nodes/C4Component.tsx`) measures the jump and
|
|
25
|
+
cancels it with a host-owned offset on the diagram's `<svg>`:
|
|
26
|
+
|
|
27
|
+
1. `onPositionChange` is called by the renderer synchronously at release, before the
|
|
28
|
+
transform is cleared, and not at all for a cancelled drag. The handler records the
|
|
29
|
+
svg's `getBoundingClientRect()` and bumps a render tick, so the component
|
|
30
|
+
re-renders in the same batch as the renderer's release render.
|
|
31
|
+
2. A no-dependency `useLayoutEffect` runs after the renderer's own (child) layout
|
|
32
|
+
effect. Once `style.transform` is empty it measures the svg again and adds
|
|
33
|
+
`before − after` to a per-instance offset.
|
|
34
|
+
3. The offset is written as the CSS `translate` property (`svg.style.translate`),
|
|
35
|
+
which composes with the renderer's `transform` and which the renderer never
|
|
36
|
+
writes. The write happens in the layout phase, so no frame is painted with the
|
|
37
|
+
jump in it.
|
|
38
|
+
4. The offset resets when layout mode exits. The container also gets
|
|
39
|
+
`overflow-anchor: none` so scroll anchoring cannot add a second adjustment.
|
|
40
|
+
|
|
41
|
+
Because the shift is measured rather than computed from the growth, one mechanism
|
|
42
|
+
covers left, top, right (the centring half-growth), corners, several sides in one
|
|
43
|
+
drag, net growth smaller than the peak, a container that was already scrolled, and
|
|
44
|
+
growth deferred to release by the renderer's 48px cap. A drag that does not grow
|
|
45
|
+
the frame measures zero and writes nothing.
|
|
46
|
+
|
|
47
|
+
### Why `onFrameChange` is not used (the FR-005 reason)
|
|
48
|
+
|
|
49
|
+
`onFrameChange` reports `{ width, height }` in unscaled diagram units. It carries no
|
|
50
|
+
origin and no per-side growth, so it cannot tell a left-edge growth (which moves the
|
|
51
|
+
origin) from a right-edge one; it carries no drag or release signal; and it is silent
|
|
52
|
+
while the growth cap holds the frame, which is exactly when growth is deferred to
|
|
53
|
+
release. It could at most say that the width changed. The quantity that moves the
|
|
54
|
+
dropped node on screen is the origin's screen position, so that is what is measured.
|
|
55
|
+
|
|
56
|
+
### The 48px growth cap
|
|
57
|
+
|
|
58
|
+
The cap applies only when the rendered scale differs from the drag-start scale
|
|
59
|
+
(zoom-to-fit) and the pointer is within 48px of the scroll container's edge. This
|
|
60
|
+
editor never passes `zoom`, so the cap cannot engage here today. If it ever does,
|
|
61
|
+
the deferred growth lands at release and goes through the same measure-and-cancel
|
|
62
|
+
path, which a unit test simulates. A test also asserts that `zoom` is not passed, so a
|
|
63
|
+
later zoom-to-fit change fails it and sends the next person back here.
|
|
64
|
+
|
|
65
|
+
## Alternatives rejected
|
|
66
|
+
|
|
67
|
+
- **Adjust `scrollLeft`.** It only has range when the content overflows. A diagram
|
|
68
|
+
narrower than its container (the common case) cannot be corrected by scrolling, and
|
|
69
|
+
`scrollTop` cannot go negative for top growth.
|
|
70
|
+
- **A wrapper `<div>` with `transform`.** It would become the flex item, so
|
|
71
|
+
`.c4-renderer svg { max-width: 100% }` would resolve against an auto-width wrapper
|
|
72
|
+
and change diagram sizing on entering layout mode.
|
|
73
|
+
- **Drop the centring.** Users rely on it, and it would not cancel the top/left shift.
|
|
74
|
+
- **Use `getScreenCTM()` for the measurement.** The renderer's own code notes that
|
|
75
|
+
engines have been inconsistent about whether it includes CSS transforms. The bounding
|
|
76
|
+
rect always does.
|
|
77
|
+
|
|
78
|
+
## Cost
|
|
79
|
+
|
|
80
|
+
- After a frame-growing drag the diagram stays off-centre by the cancelled shift until
|
|
81
|
+
layout mode is exited. That is deliberate: where the user dropped the node is what counts.
|
|
82
|
+
- Nothing is un-clipped. The offset reproduces the pre-release visual state, so
|
|
83
|
+
content pushed outside the container's scrollable area during the drag stays
|
|
84
|
+
clipped, as it was during the drag.
|
|
85
|
+
- The fix depends on library internals: the transform being cleared in a child layout
|
|
86
|
+
effect, `onPositionChange` firing synchronously at release and not on cancel, and
|
|
87
|
+
the renderer not writing `style.translate`. The unit tests lock the ordering with a
|
|
88
|
+
fake renderer that mirrors it. The Electron e2e (`examples/electron/e2e/c4-release-shift.spec.ts`)
|
|
89
|
+
measures real Chromium geometry to 1px and fails when the compensation is removed.
|
|
90
|
+
- `onFrameChange` stays unused.
|
|
91
|
+
|
|
92
|
+
> **Amended 2026-11-16 — the translate-only approach no longer holds for vertical
|
|
93
|
+
> growth (issue #206).** A translate is visual only, so the container's layout box
|
|
94
|
+
> does not grow with it. For top growth the cancelling translate moved the grown
|
|
95
|
+
> strip above the container's top edge, and the container clips there
|
|
96
|
+
> (`overflow-x: auto` makes its computed `overflow-y` clip too, and it has only `1rem`
|
|
97
|
+
> of padding). A node dropped partly above the top ended up mostly hidden, which is
|
|
98
|
+
> worse than the jump this ADR removed. What changed:
|
|
99
|
+
>
|
|
100
|
+
> - **Measurement is unchanged** (the svg's bounding rect before and after release).
|
|
101
|
+
> Only how the measured shift is applied changes.
|
|
102
|
+
> - **Vertical: no translate at all.** The container grows with the frame, and the
|
|
103
|
+
> shift is cancelled by scrolling the nearest vertically scrolling ancestor
|
|
104
|
+
> (`scrollContainerFor`, ADR-088, else the document) by the measured amount, with
|
|
105
|
+
> `behavior: 'instant'`. The browser clamps to the scroll range, so with no range (a
|
|
106
|
+
> short, non-scrolling document) or only a partial range the remainder is accepted as
|
|
107
|
+
> a visible shift. A visible jump is better than clipped content.
|
|
108
|
+
> - **Horizontal: scroll first, then a guarded translate.** If the container's content
|
|
109
|
+
> overflows, its `scrollLeft` absorbs the shift. Whatever remains (all of it when
|
|
110
|
+
> nothing overflows, the centred common case) is a translate, clamped so the svg
|
|
111
|
+
> stays inside the container's padding box. If the svg is wider than the box, or the
|
|
112
|
+
> translate would otherwise clip, the shift is accepted instead. The host offset is
|
|
113
|
+
> now x-only.
|
|
114
|
+
> - **`justify-content: safe center`** replaces `center` on the container. With plain
|
|
115
|
+
> centring an overflowing svg overflows equally both ways and the left half cannot be
|
|
116
|
+
> scrolled to, so left growth could not be recovered with `scrollLeft`.
|
|
117
|
+
> - `overflow-anchor: none` stays, so scroll anchoring adds no second adjustment.
|
|
118
|
+
>
|
|
119
|
+
> **The "Alternatives rejected" scroll option is revisited.** It was rejected because a
|
|
120
|
+
> narrow, centred diagram has no horizontal range and `scrollTop` cannot go negative.
|
|
121
|
+
> Neither holds for vertical growth once the container grows: the content is pushed
|
|
122
|
+
> down, so the *ancestor* has range to scroll down into. Horizontal scrolling is still
|
|
123
|
+
> only possible when the content overflows, which is why the translate remains there.
|
|
124
|
+
>
|
|
125
|
+
> **The "Cost" clause "Nothing is un-clipped" no longer holds.** The cost now is a
|
|
126
|
+
> visible shift wherever compensation cannot be done without clipping: a non-scrolling
|
|
127
|
+
> (or exhausted) vertical scroller, or a horizontal drop so close to the container edge
|
|
128
|
+
> that the grown frame cannot be translated back inside it. The e2e measured the
|
|
129
|
+
> latter: the svg frame carries about 40px of empty margin around the nodes, so a drop
|
|
130
|
+
> within that margin of the container's edge shifts a few pixels even though the node
|
|
131
|
+
> itself would still fit. The guard cannot tell frame from content, so it errs towards
|
|
132
|
+
> not clipping.
|
|
133
|
+
> The e2e now also asserts the dropped node's whole box lies inside the visible area
|
|
134
|
+
> (viewport and every clipping ancestor), and fails if the container clips it.
|
|
135
|
+
|
|
136
|
+
> **Amended 2026-11-17 — compensation is now live, through `@liminis/diagrams`
|
|
137
|
+
> 0.2.2 (issue #206, liminis-diagrams#110); the release-time translate is gone.**
|
|
138
|
+
> The 2026-11-16 amendment fixed the clipping at release, but hand testing in the
|
|
139
|
+
> demo with every frame of a drag recorded showed the four edges still differed
|
|
140
|
+
> *during* the drag. Down and right grow the box and nothing clips (past the right
|
|
141
|
+
> edge the svg shrinks to fit, `.c4-renderer svg { max-width: 100% }`). Up and left,
|
|
142
|
+
> the renderer held the origin with a CSS `transform` (liminis-diagrams ADR-100),
|
|
143
|
+
> which paints the grown strip outside the svg's layout box, so the container
|
|
144
|
+
> clipped it: the dragged node vanished above the top, and past the left edge the
|
|
145
|
+
> drawing spilled about 300px beyond the container. Correcting only at release
|
|
146
|
+
> cannot fix a frame that is already clipped. The release-time `translate` also left
|
|
147
|
+
> residual horizontal offsets (seen: -98px and +78px), so the diagram drifted off
|
|
148
|
+
> centre. What changed:
|
|
149
|
+
>
|
|
150
|
+
> - **`holdOrigin={false}`.** The host opts out of the hold transform, so the svg's
|
|
151
|
+
> layout box is always the whole drawing and all four edges behave alike. Bumps
|
|
152
|
+
> `@liminis/diagrams` to `^0.2.2`.
|
|
153
|
+
> - **Live, every frame, through `onOriginShift({ dx, dy })`.** The renderer reports
|
|
154
|
+
> the displacement since the previous commit from a layout effect (before paint,
|
|
155
|
+
> only during a drag, with the reverse shift on a cancel). The host scrolls the
|
|
156
|
+
> nearest vertical scroller (`scrollContainerFor`, else the document) by `dy`, and
|
|
157
|
+
> the container by `dx`. Top growth now opens upward the way bottom growth opens
|
|
158
|
+
> downward, and other nodes do not move on screen wherever the scroller has range.
|
|
159
|
+
> With no range the shift is accepted rather than clipped.
|
|
160
|
+
> - **Left and right need no compensation in practice.** The svg shrinks to fit, so
|
|
161
|
+
> the container has no horizontal range, the `dx` scroll is a no-op, and the diagram
|
|
162
|
+
> re-centres symmetrically.
|
|
163
|
+
> - **`unabsorbedShiftRef`.** Browsers snap a scroll position to whole pixels, and a
|
|
164
|
+
> range can clamp it. The unabsorbed part is carried into the next frame, so
|
|
165
|
+
> rounding cannot accumulate (the e2e measured a 2.5px drift of untouched nodes
|
|
166
|
+
> without it) and a reverse shift unwinds exactly what was scrolled. It is reset on
|
|
167
|
+
> release; whatever it holds then is the accepted shift.
|
|
168
|
+
> - **Removed:** the release snapshot, the layout effect, the host `translate` and its
|
|
169
|
+
> accumulated offset, and the clamp that guarded it. The svg now carries no
|
|
170
|
+
> `transform` or `translate` at any time, so an out-and-back drag leaves nothing
|
|
171
|
+
> behind. `justify-content: safe center` and `overflow-anchor: none` stay.
|
|
172
|
+
>
|
|
173
|
+
> **This supersedes the 2026-11-16 amendment's horizontal clauses** ("scroll first,
|
|
174
|
+
> then a guarded translate", the x-only host offset); its vertical clauses stand,
|
|
175
|
+
> with the scroll now applied live rather than at release. The measurement clause
|
|
176
|
+
> ("the compensation is measured from the svg's rect before and after release") also
|
|
177
|
+
> no longer holds: the renderer reports the shift, so nothing is measured. That
|
|
178
|
+
> removes the dependence on library internals listed under "Cost" (the transform
|
|
179
|
+
> cleared in a child layout effect, `onPositionChange` ordering): the contract is now
|
|
180
|
+
> the documented `onOriginShift` API.
|
|
181
|
+
>
|
|
182
|
+
> **Cost.** Where the vertical scroller has no range (a short, non-scrolling
|
|
183
|
+
> document) the diagram shifts as it grows at the top, instead of staying put; a
|
|
184
|
+
> jump beats clipped content. Dropping a layout-mode drag that is not covered by the
|
|
185
|
+
> renderer's own frame (`zoom` and the 48px growth cap, which this editor never
|
|
186
|
+
> engages) is unchanged. The e2e now checks every frame of a drag, at every edge and
|
|
187
|
+
> corner and out and back, that the dragged node lies inside the container's visible
|
|
188
|
+
> box, and it fails if the hold transform is switched back on.
|