@luutuankiet/clipboard2markdown 0.4.0 → 0.5.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 CHANGED
@@ -58,7 +58,7 @@ cat diagram.json | c2m excalidraw - # same, from stdin
58
58
 
59
59
  The Mermaid is deliberately lossy: positions, colours, fonts and arrow curves are dropped; boxes, labels, connections, line style and grouping are kept. The canvas stays the master copy.
60
60
 
61
- **Diagrams as PNG** (`c2m excalidraw --png`, Node 20+, any OS): draws one or more diagrams locally, for pasting into a Google Doc. No browser is needed and the drawing makes no network request; the share link is uploaded as usual (skip it with `--no-upload`). Input is the JSON array above or a whole scene (`{"elements": [...]}`, such as a `.excalidraw` file).
61
+ **Diagrams as PNG** (`c2m excalidraw --png`, Node 20+, any OS): draws one or more diagrams locally, for pasting into a Google Doc. No browser is needed and the drawing makes no network request; the share link is uploaded as usual (skip it with `--no-upload`). Input is the JSON array above or a whole scene (`{"elements": [...]}`, such as a `.excalidraw` file); a scene's elements may use the same shorthand (`label`, `start`/`end`, arrows without `points`), and a scene without it is drawn as is.
62
62
 
63
63
  ```bash
64
64
  c2m excalidraw --png a.json b.json # PNGs in ~/.cache/c2m/renders/
package/bin/excalidraw.js CHANGED
@@ -39,7 +39,7 @@ LOOP
39
39
  INPUT: a JSON array of elements
40
40
  [
41
41
  {"id": "api", "type": "rectangle", "x": 0, "y": 0, "width": 160, "height": 70,
42
- "label": {"text": "API"}, "backgroundColor": "#a5d8ff"},
42
+ "label": {"text": "API"}},
43
43
  {"id": "db", "type": "ellipse", "x": 300, "y": 0, "width": 200, "height": 80,
44
44
  "label": {"text": "Postgres"}},
45
45
  {"id": "ok", "type": "diamond", "x": 280, "y": 180, "width": 240, "height": 120,
@@ -67,7 +67,11 @@ ELEMENTS
67
67
  FIELDS (all optional unless noted above)
68
68
  label {"text": "...", "fontSize": 20} or just "..." on shapes and
69
69
  arrows; rendered as text centred in the shape / on the arrow.
70
- Use "\\n" for line breaks; labels are not wrapped for you.
70
+ A group box (a shape fully containing another) puts its
71
+ label top-left instead. Override with "textAlign" (left,
72
+ center, right) and "verticalAlign" (top, middle, bottom)
73
+ inside label. Use "\\n" for line breaks; labels are not
74
+ wrapped for you.
71
75
  start, end {"id": "<shape id>"} on arrows and lines. The arrow stays
72
76
  attached when someone drags the shape in excalidraw.com.
73
77
  MCP style also works: "startBinding": {"elementId": "<id>"}.
@@ -88,9 +92,25 @@ SIZING AND SPACING (rules of thumb, font size 20)
88
92
  - Ellipse needs ~1.4x that, diamond ~2x, in both directions.
89
93
  - Leave >= 120 px between shapes that an arrow joins, more if it has a label.
90
94
  - A large rectangle drawn first and fully containing others works as a group
91
- box: full containment is fine, partial overlap is warned about.
95
+ box: full containment is fine, partial overlap is warned about. Give it a
96
+ "label" for its title (drawn top-left); do not fake one with a text
97
+ element, or the preview loses the group's name. Leave ~40 px above the
98
+ first row inside for the title.
92
99
  - Lay out on a grid: rows every ~150 px, columns every ~250 px.
93
100
 
101
+ STYLE (the default look; the user's own styling instructions win)
102
+ 1. Plan all white: every node #ffffff solid fill, #1e1e1e stroke, default
103
+ width, roughness and font. Group boxes: thin grey stroke (#868e96, width
104
+ 1) and a "label" title. Fix layout, text and arrows here; never deliver it.
105
+ 2. Deliver a highlight pass: same positions, text and arrows. Change only
106
+ fill colour, fillStyle, dashed strokes or shape, to mark the point.
107
+ Colour means emphasis only, no fixed palette, at most 3 colours. One
108
+ highlighted node is fine. Add a key (labelled boxes no arrow touches, at the
109
+ top or right) whenever a colour or dash carries meaning.
110
+ Arrow labels: optional, at most 2 words, no ids, brackets or line breaks.
111
+ Full guide with examples:
112
+ https://github.com/luutuankiet/clipboard2markdown/blob/master/docs/reference/diagram-style.md
113
+
94
114
  PREVIEW
95
115
  rectangle -> id[label] ellipse -> id((label)) diamond -> id{label}
96
116
  An arrow bound at both ends -> edge with its label. A shape fully inside a
@@ -111,7 +131,9 @@ PNG (for pasting into a Google Doc)
111
131
  Draws each diagram locally (no browser; the drawing itself makes no network
112
132
  request) and uploads it for its share link as above. Each input is either
113
133
  the element array described here or a whole scene ({"elements": [...]},
114
- e.g. a .excalidraw file). For each input <name>.json it writes:
134
+ e.g. a .excalidraw file). A scene's elements may use the same shorthand
135
+ (label, start/end, arrows without points); a scene without it is drawn and
136
+ uploaded as is. For each input <name>.json it writes:
115
137
  <name>.png for the document: scale 3, lowered until the image
116
138
  has at most 25,000,000 pixels (Google Docs' limit)
117
139
  <name>.review.png for a quick look: at most 1000 px on the long side
@@ -156,11 +178,24 @@ async function upload(scene, fetchImpl) {
156
178
  }
157
179
  }
158
180
 
159
- // A whole scene ({elements: [...]}, as in a .excalidraw file) is drawn as is;
160
- // anything else goes through the skeleton builder.
181
+ // The help's shorthand: `label`, `start`/`end`, or an arrow/line left without
182
+ // points for the builder to route. A real Excalidraw element has none of these.
183
+ function usesShorthand(el) {
184
+ if (!el || typeof el !== 'object') return false;
185
+ if ('label' in el || 'start' in el || 'end' in el) return true;
186
+ return (el.type === 'arrow' || el.type === 'line') && !Array.isArray(el.points);
187
+ }
188
+
189
+ // A whole scene ({elements: [...]}, as in a .excalidraw file) is drawn as is,
190
+ // unless it uses the shorthand: then it goes through the skeleton builder like
191
+ // an element array, keeping the scene's own appState and files.
161
192
  function toScene(input) {
162
193
  if (input && !Array.isArray(input) && Array.isArray(input.elements)) {
163
- return { scene: input, preview: null, warnings: [] };
194
+ if (!input.elements.some(usesShorthand)) return { scene: input, preview: null, warnings: [] };
195
+ var built = buildSkeleton(input.elements);
196
+ if (input.appState) built.scene.appState = input.appState;
197
+ if (input.files) built.scene.files = input.files;
198
+ return built;
164
199
  }
165
200
  return buildSkeleton(input);
166
201
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@luutuankiet/clipboard2markdown",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Convert rich clipboard HTML from Jira, Confluence, Slack and Google apps into clean Markdown, and back.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -7,7 +7,7 @@
7
7
 
8
8
  import { measureText, containerFactor, TEXT_METRICS } from './edit.js';
9
9
  import { sceneToMermaid } from './scene-to-mermaid.js';
10
- import { bounds } from './scene-model.js';
10
+ import { bounds, TUNING } from './scene-model.js';
11
11
 
12
12
  const SHAPES = new Set(['rectangle', 'ellipse', 'diamond']);
13
13
  const LINEAR = new Set(['arrow', 'line']);
@@ -16,15 +16,31 @@ const MCP_PSEUDO = new Set(['cameraUpdate', 'delete', 'restoreCheckpoint']);
16
16
  // Skeleton-only fields that must not leak into the scene.
17
17
  const SKELETON_FIELDS = ['label', 'start', 'end'];
18
18
  const BINDING_GAP = 4;
19
-
20
- function randomInt() { return Math.floor(Math.random() * 2 ** 31); }
19
+ // Excalidraw's own inset for bound text (BOUND_TEXT_PADDING); using the same
20
+ // value means the editor does not move a title when the scene is opened.
21
+ const BOUND_TEXT_PADDING = 5;
22
+ const TEXT_ALIGNS = new Set(['left', 'center', 'right']);
23
+ const VERTICAL_ALIGNS = new Set(['top', 'middle', 'bottom']);
24
+
25
+ // FNV-1a over the element id. `seed` drives the hand-drawn wobble, so deriving
26
+ // it from the id makes the same diagram draw the same way on every run; a
27
+ // random seed made two renders of one diagram not line up. Never 0: rough.js
28
+ // falls back to Math.random for a zero seed.
29
+ function seedFromId(id, salt) {
30
+ var s = salt + String(id), h = 0x811c9dc5;
31
+ for (var i = 0; i < s.length; i++) {
32
+ h ^= s.charCodeAt(i);
33
+ h = Math.imul(h, 0x01000193);
34
+ }
35
+ return ((h >>> 0) % 2147483646) + 1;
36
+ }
21
37
 
22
38
  function base(type, id) {
23
39
  return {
24
40
  id: id, type: type, x: 0, y: 0, width: 0, height: 0, angle: 0,
25
41
  strokeColor: '#1e1e1e', backgroundColor: 'transparent', fillStyle: 'solid', strokeWidth: 2,
26
42
  strokeStyle: 'solid', roughness: 1, opacity: 100, groupIds: [], frameId: null, roundness: null,
27
- seed: randomInt(), version: 1, versionNonce: randomInt(), isDeleted: false, boundElements: null,
43
+ seed: seedFromId(id, ''), version: 1, versionNonce: seedFromId(id, 'nonce:'), isDeleted: false, boundElements: null,
28
44
  updated: Date.now(), link: null, locked: false,
29
45
  };
30
46
  }
@@ -102,6 +118,42 @@ function fitLinear(el) {
102
118
  el.height = Math.max.apply(null, ys) - Math.min.apply(null, ys);
103
119
  }
104
120
 
121
+ function pickAlign(fromLabel, fromShape, allowed) {
122
+ if (allowed.has(fromLabel)) return fromLabel;
123
+ if (allowed.has(fromShape)) return fromShape;
124
+ return null;
125
+ }
126
+
127
+ // Same test the Mermaid reader uses for a subgraph: the shape fully encloses
128
+ // another shape and is bigger than it.
129
+ function encloses(shape, shapes) {
130
+ var outer = { x: shape.x, y: shape.y, w: shape.width, h: shape.height };
131
+ return shapes.some(function (o) {
132
+ if (o === shape) return false;
133
+ var inner = { x: o.x, y: o.y, w: o.width, h: o.height };
134
+ var k = TUNING.containmentSlack;
135
+ return contains({ x: outer.x - k, y: outer.y - k, w: outer.w + 2 * k, h: outer.h + 2 * k }, inner) &&
136
+ outer.w * outer.h > inner.w * inner.h;
137
+ });
138
+ }
139
+
140
+ // Excalidraw's computeBoundTextPosition, so the text sits where the editor
141
+ // itself would put it for this alignment.
142
+ function placeInShape(t, shape) {
143
+ var ox = BOUND_TEXT_PADDING, oy = BOUND_TEXT_PADDING;
144
+ if (shape.type === 'ellipse') {
145
+ ox += (shape.width / 2) * (1 - Math.SQRT1_2);
146
+ oy += (shape.height / 2) * (1 - Math.SQRT1_2);
147
+ } else if (shape.type === 'diamond') {
148
+ ox += shape.width / 4;
149
+ oy += shape.height / 4;
150
+ }
151
+ var availW = shape.width - 2 * ox, availH = shape.height - 2 * oy;
152
+ var x0 = shape.x + ox, y0 = shape.y + oy;
153
+ t.x = t.textAlign === 'left' ? x0 : t.textAlign === 'right' ? x0 + availW - t.width : x0 + (availW - t.width) / 2;
154
+ t.y = t.verticalAlign === 'top' ? y0 : t.verticalAlign === 'bottom' ? y0 + availH - t.height : y0 + (availH - t.height) / 2;
155
+ }
156
+
105
157
  // Throws on input that cannot become a scene at all; everything recoverable is
106
158
  // a warning instead, so the agent still gets a link.
107
159
  export function normalizeSkeleton(input) {
@@ -175,7 +227,11 @@ export function normalizeSkeleton(input) {
175
227
 
176
228
  var label = labelOf(raw);
177
229
  if (label && (SHAPES.has(raw.type) || LINEAR.has(raw.type))) {
178
- labels.push({ container: el, text: String(label.text), fontSize: label.fontSize || raw.fontSize || 20, strokeColor: label.strokeColor || raw.strokeColor });
230
+ labels.push({
231
+ container: el, text: String(label.text), fontSize: label.fontSize || raw.fontSize || 20, strokeColor: label.strokeColor || raw.strokeColor,
232
+ textAlign: pickAlign(label.textAlign, raw.textAlign, TEXT_ALIGNS),
233
+ verticalAlign: pickAlign(label.verticalAlign, raw.verticalAlign, VERTICAL_ALIGNS),
234
+ });
179
235
  }
180
236
  elements.push(el);
181
237
  if (!byId.has(id)) byId.set(id, el);
@@ -211,17 +267,31 @@ export function normalizeSkeleton(input) {
211
267
  a.to = to;
212
268
  });
213
269
 
214
- // Labels become bound text, centred in the shape or on the arrow's midpoint.
270
+ // Labels become bound text. A container (a shape that encloses another shape,
271
+ // which the Mermaid preview reads as a subgraph) gets its title in the top-left
272
+ // corner so it stays clear of the boxes inside; any other shape, and every
273
+ // arrow, gets its label centred. An explicit textAlign / verticalAlign wins.
274
+ var shapeEls = elements.filter(function (e) { return SHAPES.has(e.type); });
215
275
  var usedIds = new Set(elements.map(function (e) { return e.id; }));
216
276
  labels.forEach(function (l) {
217
277
  var id = l.container.id + '-label';
218
278
  for (var n = 2; usedIds.has(id); n++) id = l.container.id + '-label' + n;
219
279
  usedIds.add(id);
220
- var t = textElement(id, l.text, l.fontSize, { textAlign: 'center', verticalAlign: 'middle', containerId: l.container.id });
280
+ var linear = LINEAR.has(l.container.type);
281
+ var isContainer = !linear && encloses(l.container, shapeEls);
282
+ var t = textElement(id, l.text, l.fontSize, {
283
+ textAlign: linear ? 'center' : l.textAlign || (isContainer ? 'left' : 'center'),
284
+ verticalAlign: linear ? 'middle' : l.verticalAlign || (isContainer ? 'top' : 'middle'),
285
+ containerId: l.container.id,
286
+ });
221
287
  if (l.strokeColor) t.strokeColor = l.strokeColor;
222
- var c = LINEAR.has(l.container.type) ? arrowMidpoint(l.container) : centre(l.container);
223
- t.x = c[0] - t.width / 2;
224
- t.y = c[1] - t.height / 2;
288
+ if (linear) {
289
+ var c = arrowMidpoint(l.container);
290
+ t.x = c[0] - t.width / 2;
291
+ t.y = c[1] - t.height / 2;
292
+ } else {
293
+ placeInShape(t, l.container);
294
+ }
225
295
  addBound(l.container, { id: id, type: 'text' });
226
296
  elements.push(t);
227
297
  });