Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(open-knowledge): flash linked mermaid labels on edit (#2532)

Andrew Mikofalvy7d1efdce72d5
diff --git a/.changeset/mermaid-linked-label-flash.md b/.changeset/mermaid-linked-label-flash.md
new file mode 100644
index 000000000..19cac7a56
--- /dev/null
+++ b/.changeset/mermaid-linked-label-flash.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+When you edit a label in a Mermaid diagram and the change propagates to other places the same text appears — for example, renaming a sequence-diagram participant updates both its top and bottom boxes — those other occurrences now briefly flash, so it's clear they changed too. Same visual cue as the flash the editor already uses when it absorbs an agent's edits. A one-off label edit with no linked occurrences stays quiet.
diff --git a/packages/app/src/editor/components/Mermaid.dom.test.tsx b/packages/app/src/editor/components/Mermaid.dom.test.tsx
index 514288ba2..e54dc4623 100644
--- a/packages/app/src/editor/components/Mermaid.dom.test.tsx
+++ b/packages/app/src/editor/components/Mermaid.dom.test.tsx
@@ -79,7 +79,7 @@ mock.module('@panzoom/panzoom', () => ({
default: createPanzoom,
}));
-const { MermaidView } = await import('./Mermaid');
+const { MermaidView, flashLinkedLabels } = await import('./Mermaid');
const { TooltipProvider } = await import('@/components/ui/tooltip');
function renderMermaidView(chart: string) {
@@ -309,3 +309,33 @@ describe('MermaidView editBinding (standalone .mmd path)', () => {
expect(committed).toBeNull();
});
});
+
+describe('flashLinkedLabels', () => {
+ test('flashes every occurrence when a label appears 2+ times (linked)', () => {
+ const c = document.createElement('div');
+ c.innerHTML =
+ '<svg><text class="actor">Test123</text></svg>' +
+ '<svg><text class="actor">Test123</text></svg>' +
+ '<span class="nodeLabel">Untouched</span>';
+ expect(flashLinkedLabels(c, 'Test123')).toBe(2);
+ expect(c.querySelectorAll('.mermaid-label-flash').length).toBe(2);
+ // Non-matching label is left alone.
+ expect(c.querySelector('.nodeLabel')?.classList.contains('mermaid-label-flash')).toBe(false);
+ });
+
+ test('stays quiet for a lone occurrence (no related text to signal)', () => {
+ const c = document.createElement('div');
+ c.innerHTML = '<span class="nodeLabel">Solo</span><span class="nodeLabel">Other</span>';
+ expect(flashLinkedLabels(c, 'Solo')).toBe(0);
+ expect(c.querySelector('.mermaid-label-flash')).toBeNull();
+ });
+
+ test('matches trimmed text and ignores blank values', () => {
+ const c = document.createElement('div');
+ c.innerHTML = '<text class="messageText"> Ping </text><text class="messageText">Ping</text>';
+ expect(flashLinkedLabels(c, 'Ping')).toBe(2);
+ const blank = document.createElement('div');
+ blank.innerHTML = '<text class="actor"> </text><text class="actor"> </text>';
+ expect(flashLinkedLabels(blank, ' ')).toBe(0);
+ });
+});
diff --git a/packages/app/src/editor/components/Mermaid.tsx b/packages/app/src/editor/components/Mermaid.tsx
index 92bf4d9d1..baeb11912 100644
--- a/packages/app/src/editor/components/Mermaid.tsx
+++ b/packages/app/src/editor/components/Mermaid.tsx
@@ -749,6 +749,83 @@ export function findSequenceBlockConditionInSource(
return null;
}
+// Label selectors that carry visible text across the diagram types inline
+// editing supports (flowchart node/edge labels are HTML spans; sequence
+// actors/messages/notes/loops are SVG `<text>`).
+const FLASHABLE_LABEL_SELECTOR =
+ '.nodeLabel, .edgeLabel, text.actor, text.messageText, text.noteText, text.loopText';
+
+/**
+ * Flash the rendered label occurrences whose text matches `value` — the "this
+ * text changed too" cue used after a WYSIWYG label edit propagates to LINKED
+ * occurrences (a renamed sequence participant renders in BOTH its top and
+ * bottom actor boxes, so renaming once changes both). Adds the
+ * `mermaid-label-flash` class (globals.css) to each match.
+ *
+ * Flashes only when 2+ occurrences match: a lone label edit has no "related"
+ * text to signal, so it stays quiet. Mermaid re-renders the whole SVG on every
+ * edit, so the class lands on fresh nodes and the one-shot animation plays
+ * without a restart dance. Returns the count flashed.
+ */
+/**
+ * Pulse one label's glyph paint to the agent accent and back, twice, by
+ * toggling INLINE `!important` fill/color. Why inline `!important` and not a CSS
+ * class animation: mermaid injects a `<style>` into every rendered SVG whose
+ * `.actor` / `tspan` fill rules can out-specify (or `!important`-beat) a
+ * class-based `fill` animation, silently cancelling it. An inline `!important`
+ * declaration beats those, so the pulse always shows. `fill` colors SVG
+ * `<tspan>` glyphs; `color` colors HTML (`.nodeLabel`/`.edgeLabel`) labels —
+ * setting both covers either carrier. Honors reduce-motion with one softer
+ * pulse. Self-cleans via `removeProperty`; safe if a later re-render detaches
+ * the node (the timers just no-op on a detached element).
+ */
+function pulseGlyphPaint(el: Element): void {
+ const style = (el as SVGElement | HTMLElement).style as CSSStyleDeclaration | undefined;
+ if (!style) return;
+ const on = () => {
+ style.setProperty('fill', 'var(--color-agent)', 'important');
+ style.setProperty('color', 'var(--color-agent)', 'important');
+ };
+ const off = () => {
+ style.removeProperty('fill');
+ style.removeProperty('color');
+ };
+ const reduce =
+ typeof window !== 'undefined' &&
+ window.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true;
+ if (reduce) {
+ on();
+ setTimeout(off, 600);
+ return;
+ }
+ const beat = 170;
+ on();
+ setTimeout(off, beat);
+ setTimeout(on, beat * 2);
+ setTimeout(off, beat * 3);
+}
+
+export function flashLinkedLabels(container: HTMLElement, value: string): number {
+ const needle = value.trim();
+ if (!needle) return 0;
+ const matches = Array.from(container.querySelectorAll<Element>(FLASHABLE_LABEL_SELECTOR)).filter(
+ (el) => (el.textContent ?? '').trim() === needle,
+ );
+ if (matches.length < 2) return 0;
+ for (const el of matches) {
+ // Flash the innermost paint carrier, not the outer element. Mermaid paints
+ // the glyph color on an inner `<tspan>` (SVG text) / `<p>` (foreignObject
+ // label). The carrier collapses to the element itself when there's no
+ // inner tspan/p. The `mermaid-label-flash` class is kept as a semantic
+ // marker (and a bonus CSS glow for HTML labels, where `filter` isn't
+ // clipped); `pulseGlyphPaint` drives the guaranteed-visible color pulse.
+ const carrier = el.querySelector('tspan') ?? el.querySelector('p') ?? el;
+ carrier.classList.add('mermaid-label-flash');
+ pulseGlyphPaint(carrier);
+ }
+ return matches.length;
+}
+
export function MermaidView({ chart = '', className, editBinding }: MermaidProps) {
const reactId = useId();
const renderId = `mermaid-${reactId.replaceAll(':', '_')}`;
@@ -802,6 +879,11 @@ export function MermaidView({ chart = '', className, editBinding }: MermaidProps
// Tracks the currently-editing label so we can tear it down cleanly
// when the SVG re-renders (or component unmounts) mid-edit.
const editSessionRef = useRef<{ cleanup: () => void } | null>(null);
+ // Set to the just-committed label value when a WYSIWYG edit changed the
+ // chart; consumed by the post-render effect below to flash the LINKED
+ // occurrences (e.g. a renamed participant's other actor box) once the SVG
+ // re-renders. Null when no flash is pending.
+ const flashValueRef = useRef<string | null>(null);
useEffect(() => {
if (!chart.trim()) {
@@ -836,6 +918,25 @@ export function MermaidView({ chart = '', className, editBinding }: MermaidProps
};
}, [chart, renderId, colorMode]);
+ // After a WYSIWYG edit re-renders the SVG, flash the linked occurrences of
+ // the just-committed value (armed by `commitLabelChangeGeneric`). Keyed on
+ // `state.svg`, NOT `state.status`: a warm re-render can batch the
+ // `rendering`→`ready` transition so `status` collapses `ready`→`ready` and a
+ // `[state.status]` effect never re-runs. The svg string changes on every
+ // successful render, so keying on it fires reliably once the new SVG is in
+ // the DOM. Consume-and-clear so an unrelated re-render (theme flip, remote
+ // edit) never replays a stale flash.
+ useEffect(() => {
+ const value = flashValueRef.current;
+ if (value === null) return;
+ // A successful render always produces a non-empty svg; skip the idle/error
+ // renders (svg === '') where there are no nodes to flash.
+ if (!state.svg) return;
+ flashValueRef.current = null;
+ const container = containerRef.current;
+ if (container) flashLinkedLabels(container, value);
+ }, [state.svg]);
+
useEffect(() => {
if (state.status !== 'ready') return;
if (!canEdit) return;
@@ -915,6 +1016,11 @@ export function MermaidView({ chart = '', className, editBinding }: MermaidProps
if (match) newChart = spliceNewLabel(chartNow, match, newLabel);
}
if (newChart === null) return;
+ // Arm the linked-occurrence flash only when the edit actually changed the
+ // source — so the post-render effect fires once on the resulting re-render
+ // (a no-op edit produces no re-render, which would otherwise leave a stale
+ // value to flash on the next unrelated render).
+ if (newChart !== chartNow) flashValueRef.current = newLabel.trim();
commitChartSource(newChart);
}
diff --git a/packages/app/src/globals.css b/packages/app/src/globals.css
index 326b567ed..b17e161c2 100644
--- a/packages/app/src/globals.css
+++ b/packages/app/src/globals.css
@@ -828,6 +828,46 @@
padding-bottom: var(--ask-composer-height, 0px);
}
+/* Mermaid label flash — the "this text just changed too" cue when a WYSIWYG
+ label edit propagates to linked occurrences (e.g. a renamed sequence
+ participant appears in its top AND bottom actor boxes). Same accent family
+ as the agent flash (`--color-agent`), but a `filter` glow rather than the
+ box-shadow/background agent-flash keyframes use — filter renders on SVG
+ `<text>` (sequence actors/messages) as well as HTML label spans (flowchart
+ nodes), where box-shadow/background do not. */
+@keyframes mermaid-label-flash {
+ 0%,
+ 100% {
+ /* Unset paint at the ends so the element returns to its own base
+ fill/color when the animation finishes. */
+ filter: none;
+ }
+ 25% {
+ /* Pulse the glyph paint itself to the agent accent — `fill` colors SVG
+ `<tspan>` glyphs, `color` colors HTML labels (`.nodeLabel`/`.edgeLabel`).
+ This is the loud, UNCLIPPED cue: an SVG `filter` drop-shadow on small
+ `<text>` gets clipped by the default filter region and reads as nothing.
+ The small glow is a bonus for HTML labels, where `filter` isn't clipped. */
+ fill: var(--color-agent);
+ color: var(--color-agent);
+ filter: drop-shadow(0 0 4px var(--color-agent));
+ }
+}
+.mermaid-label-flash {
+ /* Two quick pulses (~1s total) read unmistakably as "this changed too",
+ where a single slow fade went unnoticed. No `forwards` — the animation
+ ends on its natural 100% (base paint), restoring the label. */
+ animation: mermaid-label-flash 0.5s var(--ease-out-strong) 2;
+}
+@media (prefers-reduced-motion: reduce) {
+ .mermaid-label-flash {
+ /* Reduced cue: one slower color pulse — no repeated flashing, but
+ reduce-motion users still get the "this changed too" signal (a color
+ fade, not vestibular motion). */
+ animation: mermaid-label-flash 0.9s var(--ease-out-strong) 1;
+ }
+}
+
/* Conflict-mode DiffView scroller: same composer inset so the last hunks (and
their inline Accept/Reject controls) can scroll clear of the floating
composer. The content-side padding rule lives next to the