@plannotator/ui 0.41.1 → 0.42.0

package/types.ts

@@ -1,6 +1,16 @@
 import type { DiagramAnchor } from '@plannotator/core/diagram-anchor';
+import type { DiagramRenderKind } from '@plannotator/core/annotatable';
 
 export type { DiagramAnchor } from '@plannotator/core/diagram-anchor';
+export type { DiagramRenderKind } from '@plannotator/core/annotatable';
+
+/**
+ * How a document's body is rendered. `markdown` and `html` are the original
+ * pair; the two diagram kinds are whole-file diagram sources (.mmd/.mermaid,
+ * .dot/.gv) that render as ONE diagram through the same engine a ```mermaid
+ * fence uses — see diagramDocumentBlocks in utils/parser.
+ */
+export type DocumentRenderAs = 'markdown' | 'html' | DiagramRenderKind;
 
 export enum AnnotationType {
   DELETION = 'DELETION',
@@ -192,6 +202,16 @@ export interface Block {
   order: number; // Sorting order
   startLine: number; // 1-based line number in source
   sourceLineCount?: number; // Number of source lines consumed when it differs from content lines
+  /**
+   * Line offset a diagram comment's `sourceLine` is measured from, when it
+   * differs from `startLine`. A ```mermaid fence in a document has its opening
+   * line ABOVE the diagram's first line, so `startLine` is the right offset
+   * there and this stays unset. A whole-file diagram source (.mmd/.dot) has no
+   * fence: its first line IS document line 1, so it sets 0 here while
+   * `startLine` keeps naming the block's own first line for the export's
+   * `(lines a–b)` label.
+   */
+  diagramSourceLineOffset?: number;
 }
 
 export interface DiffResult {

package/utils/diagram-render.ts

@@ -48,14 +48,21 @@ type Mermaid = Awaited<ReturnType<typeof loadMermaidRuntime>>;
 
 /**
  * The (palette, mode) a render is for: the same pair `useTheme()` resolves
- * for code fences. The mermaid entry passes it to `applyMermaidTheme`, which
- * runs the global `initialize` once per key; the graphviz entry recolors its
- * defaults onto CSS tokens and needs neither. A host without ThemeProvider
- * passes any palette id with the mode it renders in.
+ * for code fences, plus the node shadow amount the user chose. The mermaid
+ * entry passes them to `applyMermaidTheme`, which runs the global `initialize`
+ * once per key; the graphviz entry recolors its defaults onto CSS tokens and
+ * needs neither. A host without ThemeProvider passes any palette id with the
+ * mode it renders in.
  */
 export interface DiagramTheme {
   readonly colorTheme: string;
   readonly mode: MermaidThemeMode;
+  /**
+   * Node drop shadow strength, 0..1 (see `mermaidTheme.buildMermaidShadow`).
+   * Absent means the shipped default, so a host that builds its own
+   * `DiagramTheme` renders exactly what Plannotator renders.
+   */
+  readonly shadowAmount?: number;
 }
 
 export type DiagramRenderError = {
@@ -514,11 +521,11 @@ const mermaidRenderer: DiagramRenderer = {
     }
     // Derive every Mermaid theme variable from the page's tokens before each
     // render, so the diagram follows the palette and mode. Keyed on the
-    // runtime plus (palette, mode), so the lazy runtime is themed on its
-    // first render and re-initialized only when one of the three changes.
+    // runtime plus (palette, mode, shadow amount), so the lazy runtime is
+    // themed on its first render and re-initialized only when one changes.
     // With no tokens on the page it is a no-op and the static
     // MERMAID_CONFIG (securityLevel strict) applies.
-    applyMermaidTheme(runtime, mermaidThemeKey(theme.colorTheme, theme.mode));
+    applyMermaidTheme(runtime, mermaidThemeKey(theme.colorTheme, theme.mode, theme.shadowAmount));
     return renderMermaid(runtime, renderId, source);
   },
 };

package/utils/diagramShadow.ts

@@ -0,0 +1,27 @@
+/**
+ * The user-facing scale for the Mermaid node drop shadow: whole percent, 0..100,
+ * where 100 is Mermaid 12's own default shadow and 0 is none.
+ *
+ * Deliberately free of imports so the settings registry can read it on every
+ * surface (the guides.show viewer included) without pulling the diagram theme
+ * mapping — and the runtime into which it feeds — into that module graph.
+ * `mermaidTheme.DEFAULT_MERMAID_SHADOW_AMOUNT` is the same value in the 0..1
+ * unit the mapping takes; `mermaidTheme.test.ts` pins the two together.
+ */
+
+/** The steps Settings offers. A slider would imply a precision nobody can see. */
+export const DIAGRAM_SHADOW_OPTIONS = [0, 40, 70, 100] as const;
+
+/** Shipped default: the neo look with its grey halo toned down. */
+export const DEFAULT_DIAGRAM_SHADOW = 70;
+
+/** Any whole percent in range is valid, not only the offered steps. */
+export function isDiagramShadow(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 100;
+}
+
+/** The 0..1 amount `buildMermaidThemeVariables` takes. */
+export function diagramShadowAmount(percent: number): number {
+  if (!Number.isFinite(percent)) return DEFAULT_DIAGRAM_SHADOW / 100;
+  return Math.min(100, Math.max(0, percent)) / 100;
+}

package/utils/mermaid.ts

@@ -45,6 +45,18 @@ export const MERMAID_CONFIG: MermaidConfig = {
     clusterBorder: '#475569',
     titleColor: '#f8fafc',
     edgeLabelBackground: '#1e293b',
+    /**
+     * Mermaid 12's neo look shadows every node from a fixed
+     * `drop-shadow(1px 2px 2px rgba(185,185,185,1))` grey, which reads as a
+     * halo. The token-driven mapping replaces it per palette
+     * (`buildMermaidShadow` in `./mermaidTheme`); this static config is what a
+     * host with no theme tokens renders with, so it carries the same
+     * toned-down 0.7 geometry with a fixed colour. The value is what
+     * `buildMermaidShadow(#1e293b, 0.7)` returns for THIS config's own slate
+     * ground, which is dark — hence a light shadow, exactly as Mermaid's own
+     * `insertLookDefs` uses a white flood colour on dark themes.
+     */
+    dropShadow: 'drop-shadow(0.79px 1.58px 1.58px rgba(210, 212, 217, 0.684))',
   },
   flowchart: {
     htmlLabels: true,

package/utils/mermaidTheme.ts

@@ -24,7 +24,18 @@
  *    Mermaid's colour library does not parse `oklch()`.
  * 3. `applyMermaidTheme(mermaid, key)` is the runtime step `MermaidBlock`
  *    calls before every render: `mermaid.initialize` is global state, so it
- *    runs only when the `(palette, mode)` key changed since the last apply.
+ *    runs only when the `(palette, mode, shadow amount)` key changed since the
+ *    last apply.
+ *
+ * Node shadow: Mermaid 12's neo look paints a drop shadow on every node,
+ * cluster and actor, from its own fixed `rgba(185,185,185,1)` grey at
+ * `1px 2px 2px`. The mapping keeps the look and replaces that one filter:
+ * `themeVariables.dropShadow` is built from the palette's own ground at
+ * `DEFAULT_MERMAID_SHADOW_AMOUNT` (0.7 of Mermaid's geometry), in the polarity
+ * the page reads in — see `buildMermaidShadow`. A host that wants Mermaid's
+ * grey back sets its own `themeVariables.dropShadow` after ours; a host that
+ * wants none passes `{ shadowAmount: 0 }`, which publishes `dropShadow: false`
+ * and the neo rules render `filter: none`.
  *
  * Fallback contract (hosts): when no tokens resolve, the runtime keeps the
  * static `MERMAID_CONFIG` it was initialized with, and nothing is
@@ -106,6 +117,35 @@ export type MermaidThemeTokens = Partial<Record<MermaidThemeTokenName, string>>;
 export interface MermaidThemeSpec {
   theme: 'dark' | 'default';
   themeVariables: Record<string, unknown>;
+  /** The node shadow amount baked into `themeVariables.dropShadow` (0..1). */
+  shadowAmount: number;
+}
+
+/** Options `buildMermaidThemeVariables` accepts beyond the tokens and mode. */
+export interface MermaidThemeOptions {
+  /**
+   * How much node drop shadow to paint, 0..1, where 1 reproduces Mermaid's
+   * own default geometry (`1px 2px 2px`) and 0 means no shadow at all.
+   * Default: `DEFAULT_MERMAID_SHADOW_AMOUNT`.
+   */
+  readonly shadowAmount?: number;
+}
+
+/**
+ * The shipped shadow amount: Mermaid 12's neo look at 70% of its own shadow.
+ * The full-strength default reads as a grey halo around every node on a
+ * Plannotator page; 70 keeps the lift and drops the halo.
+ */
+export const DEFAULT_MERMAID_SHADOW_AMOUNT = 0.7;
+
+/** Mermaid 12's own node shadow, the colour included. Amount 1 reproduces
+ *  this geometry; the colour is ours unless the palette yields nothing. */
+export const MERMAID_DEFAULT_SHADOW_COLOR = 'rgba(185, 185, 185, 1)';
+
+/** Clamp an amount to 0..1 and round it, so it is stable in a cache key. */
+export function clampShadowAmount(amount: number | undefined): number {
+  if (typeof amount !== 'number' || !Number.isFinite(amount)) return DEFAULT_MERMAID_SHADOW_AMOUNT;
+  return Math.round(Math.min(1, Math.max(0, amount)) * 1000) / 1000;
 }
 
 /** WCAG minimums the guard enforces. */
@@ -317,6 +357,62 @@ export function isDarkBackground(background: RgbColor): boolean {
   return relativeLuminance(background) < 0.179;
 }
 
+/** `rgba()` from an RgbColor plus an explicit alpha. */
+function rgba(c: RgbColor, alpha: number): string {
+  const ch = (v: number) => Math.round(Math.max(0, Math.min(1, v)) * 255);
+  return `rgba(${ch(c.r)}, ${ch(c.g)}, ${ch(c.b)}, ${Math.round(alpha * 1000) / 1000})`;
+}
+
+/**
+ * The node drop shadow, as the `drop-shadow(x y blur colour)` string Mermaid's
+ * `dropShadow` theme variable takes, or `false` — its falsy value, which every
+ * `[data-look="neo"] … { filter: … }` rule turns into `filter: none`.
+ *
+ * Geometry scales with the amount over a small floor, so a toned-down shadow
+ * still reads as a lift rather than vanishing: at 1 it is exactly Mermaid's own
+ * `1px 2px 2px`, at 0 there is no shadow at all.
+ *
+ * The COLOUR comes from the palette rather than Mermaid's fixed
+ * `rgba(185,185,185,1)` grey — that grey is the halo that reads as wrong on a
+ * themed page — and its POLARITY follows the page, exactly as Mermaid's own
+ * `insertLookDefs` does (`floodColor = theme.includes('dark') ? '#FFFFFF' :
+ * '#000000'`): on a dark page a shadow's job is to LIFT the node off the
+ * ground, and a black shadow on a near-black ground paints nothing the eye can
+ * see. What is kept from the palette is the tint and the strength, not the
+ * direction:
+ *   - dark page: the ground lifted 82% toward white, alpha 0.18 -> 0.90;
+ *   - light page: the ground darkened 40% toward black, alpha 0.25 -> 0.55.
+ * Each is then asserted to differ from the ground in the READABLE direction,
+ * falling back to plain white or black, so no palette can produce an invisible
+ * shadow; a ground that is not a usable colour at all falls back to Mermaid's
+ * own grey.
+ *
+ * Pure. `ground` is the page's opaque background.
+ */
+export function buildMermaidShadow(ground: RgbColor | undefined, amount: number): string | false {
+  const a = clampShadowAmount(amount);
+  if (a <= 0) return false;
+  const round = (v: number) => Math.round(v * 100) / 100;
+  const geometry = `${round(0.3 + 0.7 * a)}px ${round(0.6 + 1.4 * a)}px ${round(0.6 + 1.4 * a)}px`;
+  const usable =
+    ground !== undefined &&
+    Number.isFinite(ground.r) &&
+    Number.isFinite(ground.g) &&
+    Number.isFinite(ground.b);
+  // Nothing usable from the palette: Mermaid's own colour at our geometry.
+  if (!usable) return `drop-shadow(${geometry} ${MERMAID_DEFAULT_SHADOW_COLOR})`;
+  const dark = isDarkBackground(ground);
+  let colour = dark ? mixOklab(ground, WHITE, 0.82) : mixOklab(ground, BLACK, 0.4);
+  // The dark-page top end is calibrated so amount 1 reads as strongly as
+  // Mermaid's own `rgba(185,185,185,1)` over the same ground — 1 is defined as
+  // "Mermaid's default", so it has to actually look like it.
+  const alpha = dark ? 0.18 + 0.72 * a : 0.25 + 0.3 * a;
+  const groundL = relativeLuminance(ground);
+  if (dark && relativeLuminance(colour) <= groundL) colour = WHITE;
+  if (!dark && relativeLuminance(colour) >= groundL) colour = BLACK;
+  return `drop-shadow(${geometry} ${rgba(colour, alpha)})`;
+}
+
 /**
  * Push a fill's lightness away from `ink` until `ink` reads on it at 4.5:1.
  * Used for the categorical scale, whose single ink is fixed per mode.
@@ -376,10 +472,15 @@ export function buildCategoricalScale(p: Palette, polarity: MermaidThemeMode): R
  * the tokens. Returns `null` when the required tokens are missing or
  * unparsable, which callers treat as "use the static config".
  */
-export function buildMermaidThemeVariables(tokens: MermaidThemeTokens | undefined, mode: MermaidThemeMode): MermaidThemeSpec | null {
+export function buildMermaidThemeVariables(
+  tokens: MermaidThemeTokens | undefined,
+  mode: MermaidThemeMode,
+  options?: MermaidThemeOptions,
+): MermaidThemeSpec | null {
   if (!tokens) return null;
   const p = resolvePalette(tokens);
   if (!p) return null;
+  const shadowAmount = clampShadowAmount(options?.shadowAmount);
 
   // Base theme follows the mode; fill lightness and ink follow the measured page.
   const polarity: MermaidThemeMode = isDarkBackground(p.background) ? 'dark' : 'light';
@@ -428,6 +529,9 @@ export function buildMermaidThemeVariables(tokens: MermaidThemeTokens | undefine
   const scaleLabel = scale.map((c) => toHex(text(scaleInk, c)));
 
   const h = toHex;
+  // The shadow nodes, clusters and actors are painted with. Derived from the
+  // page's own ground, never Mermaid's fixed grey (see buildMermaidShadow).
+  const shadow = buildMermaidShadow(p.background, shadowAmount);
   const vars: Record<string, unknown> = {
     darkMode: mode === 'dark',
     ...(p.fontFamily ? { fontFamily: p.fontFamily } : {}),
@@ -459,6 +563,13 @@ export function buildMermaidThemeVariables(tokens: MermaidThemeTokens | undefine
     errorBkgColor: h(errorBg),
     errorTextColor: h(errorText),
     useGradient: false,
+    // Paint-time only: a filter on the shape, never a fill or a label colour.
+    dropShadow: shadow,
+    // `nodeShadow` gates ONE thing in Mermaid 12: the inline
+    // `filter:url(#…-drop-shadow-small)` a state diagram's small start / end
+    // dots carry, which no theme variable string reaches. Off at amount 0 so
+    // "no shadow" is true of every element.
+    ...(shadow === false ? { nodeShadow: false } : {}),
 
     // Flowchart
     nodeBkg: h(p.card),
@@ -669,7 +780,7 @@ export function buildMermaidThemeVariables(tokens: MermaidThemeTokens | undefine
     vars[`fillType${i}`] = scaleHex[i];
     vars[`venn${i + 1}`] = scaleHex[i];
   }
-  return { theme: mode === 'dark' ? 'dark' : 'default', themeVariables: vars };
+  return { theme: mode === 'dark' ? 'dark' : 'default', themeVariables: vars, shadowAmount };
 }
 
 /** The full Mermaid config for a spec: `MERMAID_CONFIG` with the theme swapped. */
@@ -682,15 +793,33 @@ export function buildMermaidConfig(spec: MermaidThemeSpec | null): MermaidConfig
 // Runtime application (cached by key)
 // ---------------------------------------------------------------------------
 
-/** `mode:palette`, the cache key `applyMermaidTheme` compares. */
-export function mermaidThemeKey(colorTheme: string, mode: MermaidThemeMode): string {
-  return `${mode}:${colorTheme}`;
+/**
+ * `mode:palette`, the cache key `applyMermaidTheme` compares — plus a
+ * `#s<amount>` suffix when the shadow amount is not the shipped default, so a
+ * changed amount re-initializes the runtime. The default amount keeps the key
+ * byte-identical to the `(palette, mode)` pair it always was, which is also
+ * what keeps a host that never names an amount on the same key it had.
+ */
+export function mermaidThemeKey(
+  colorTheme: string,
+  mode: MermaidThemeMode,
+  shadowAmount: number = DEFAULT_MERMAID_SHADOW_AMOUNT,
+): string {
+  const amount = clampShadowAmount(shadowAmount);
+  const base = `${mode}:${colorTheme}`;
+  return amount === DEFAULT_MERMAID_SHADOW_AMOUNT ? base : `${base}#s${amount}`;
 }
 
 function modeFromKey(key: string): MermaidThemeMode {
   return key.startsWith('light:') ? 'light' : 'dark';
 }
 
+/** The amount a key carries, the default when it carries none. */
+export function shadowAmountFromKey(key: string): number {
+  const match = /#s(\d*\.?\d+)$/u.exec(key);
+  return match ? clampShadowAmount(Number(match[1])) : DEFAULT_MERMAID_SHADOW_AMOUNT;
+}
+
 export type MermaidThemeApplyResult = 'unchanged' | 'dynamic' | 'static';
 
 let appliedRuntime: Pick<Mermaid, 'initialize'> | null = null;
@@ -710,7 +839,9 @@ export function applyMermaidTheme(
   root?: Element | null,
 ): MermaidThemeApplyResult {
   if (appliedRuntime === mermaid && appliedKey === key) return 'unchanged';
-  const spec = buildMermaidThemeVariables(readThemeTokens(root), modeFromKey(key));
+  const spec = buildMermaidThemeVariables(readThemeTokens(root), modeFromKey(key), {
+    shadowAmount: shadowAmountFromKey(key),
+  });
   const sameRuntime = appliedRuntime === mermaid;
   appliedRuntime = mermaid;
   appliedKey = key;

package/utils/parser.ts

@@ -541,6 +541,39 @@ export const resolveReferenceLinks = (markdown: string): string => {
     .join('\n');
 };
 
+/**
+ * The block list for a whole-file diagram source (`plannotator annotate
+ * flow.mmd`): ONE code block carrying the file's raw text, which `Viewer`
+ * hands to the same `DiagramBlock` a ```mermaid fence in a plan produces.
+ * Everything downstream — diagram comments, the annotations rail, the export's
+ * `Diagram node <label> (<id>), line <n>` location line, drafts, restore — is
+ * the fence path unchanged.
+ *
+ * `diagramSourceLineOffset: 0` is the load-bearing part. `DiagramBlock` passes
+ * it as the viewer's `sourceLineOffset` and the codec adds it to the 1-based
+ * line WITHIN the diagram source; for a fence that offset is the fence's own
+ * opening line, which sits one line above the diagram's first line. A diagram
+ * FILE has no fence, so its first line is document line 1 and the offset is 0
+ * — the 1 a synthesized ```mermaid wrapper would produce puts every exported
+ * diagram line one too high. `startLine`/`sourceLineCount` still describe the
+ * block itself, so the export's `(lines a–b)` label names the file's real
+ * span.
+ */
+export const diagramDocumentBlocks = (text: string, kind: 'mermaid' | 'graphviz'): Block[] => [
+  {
+    id: 'block-0',
+    type: 'code',
+    content: text,
+    // `dot` is what isGraphvizLanguage reads for the Graphviz engine.
+    language: kind === 'graphviz' ? 'dot' : 'mermaid',
+    order: 1,
+    startLine: 1,
+    // A trailing newline ends the last line, it does not start another.
+    sourceLineCount: text === '' ? 0 : text.replace(/\n$/, '').split('\n').length,
+    diagramSourceLineOffset: 0,
+  },
+];
+
 /**
  * A simplified markdown parser that splits content into linear blocks.
  * For a production app, we would use a robust AST walker (remark),

package/utils/sharing.ts

@@ -8,7 +8,8 @@
  * Inspired by textarea.my's approach.
  */
 
-import { AnnotationType, type Annotation, type ImageAttachment } from '../types';
+import { AnnotationType, type Annotation, type DocumentRenderAs, type ImageAttachment } from '../types';
+import { isDiagramRenderKind } from '@plannotator/core/annotatable';
 import { compress, decompress } from '@plannotator/core/compress';
 import { encrypt, decrypt } from '@plannotator/core/crypto';
 
@@ -31,6 +32,32 @@ export interface SharePayload {
   r?: 'html';  // render mode flag (omitted = markdown)
 }
 
+/**
+ * The markdown a document ships as in a share payload's `p`.
+ *
+ * A whole-file diagram source (.mmd/.dot) has no fence of its own — the
+ * annotate session renders it as one diagram because the SERVER said so in
+ * `renderAs`, and a share link carries no server. So it travels as the fenced
+ * form, which the portal's ordinary markdown parse turns back into the same
+ * diagram block. This is deliberately smaller than adding a render-mode flag
+ * (`r: 'html'`'s sibling): the portal needs no change at all.
+ *
+ * Diagram comments themselves still degrade to text comments in a share link,
+ * exactly as they do today — `diagramAnchor` is dropped like `htmlAnchor`
+ * (see sharing.multiTarget.test.ts).
+ */
+export function shareableDocumentMarkdown(
+  markdown: string,
+  renderAs: DocumentRenderAs | undefined,
+): string {
+  if (!isDiagramRenderKind(renderAs) || markdown === '') return markdown;
+  const language = renderAs === 'graphviz' ? 'dot' : 'mermaid';
+  // A diagram source can itself contain a ``` run only in a comment/label;
+  // a four-backtick fence keeps such a body intact.
+  const fence = markdown.includes('```') ? '````' : '```';
+  return `${fence}${language}\n${markdown.replace(/\n+$/, '')}\n${fence}`;
+}
+
 /**
  * Convert ShareableImage[] to ImageAttachment[] (handles old plain-string format)
  */