@open-artifact/whiteboard-core 0.9.2 → 0.11.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.
Files changed (43) hide show
  1. package/package.json +4 -4
  2. package/src/backdrop.d.ts +4 -2
  3. package/src/backdrop.js +10 -3
  4. package/src/check.d.ts +9 -1
  5. package/src/check.js +91 -11
  6. package/src/drawn-svg/looks.d.ts +166 -0
  7. package/src/drawn-svg/looks.js +594 -0
  8. package/src/drawn-svg/svg-geometry.d.ts +7 -0
  9. package/src/drawn-svg/svg-geometry.js +37 -0
  10. package/src/drawn-svg/vetting.d.ts +4 -2
  11. package/src/drawn-svg/vetting.js +11 -5
  12. package/src/edits.d.ts +2 -2
  13. package/src/edits.js +2 -2
  14. package/src/geometry.js +2 -1
  15. package/src/history/board-diff.d.ts +7 -2
  16. package/src/history/board-diff.js +31 -6
  17. package/src/history/table-steps.d.ts +8 -3
  18. package/src/history/table-steps.js +38 -7
  19. package/src/hit-test.d.ts +2 -1
  20. package/src/hit-test.js +26 -5
  21. package/src/ideas.d.ts +2 -2
  22. package/src/ideas.js +3 -1
  23. package/src/index.d.ts +5 -0
  24. package/src/index.js +5 -0
  25. package/src/links.d.ts +2 -0
  26. package/src/links.js +9 -5
  27. package/src/next-item.d.ts +16 -1
  28. package/src/next-item.js +65 -15
  29. package/src/normalize.d.ts +2 -0
  30. package/src/normalize.js +14 -4
  31. package/src/schema.d.ts +20 -0
  32. package/src/schema.js +6 -0
  33. package/src/selection.js +8 -8
  34. package/src/table-tints.d.ts +84 -0
  35. package/src/table-tints.js +217 -0
  36. package/src/table.d.ts +17 -4
  37. package/src/table.js +59 -6
  38. package/src/text/placeholder.d.ts +17 -0
  39. package/src/text/placeholder.js +16 -0
  40. package/src/text/push-down.d.ts +29 -0
  41. package/src/text/push-down.js +72 -0
  42. package/src/text/turned-anchor.d.ts +19 -0
  43. package/src/text/turned-anchor.js +32 -0
package/src/table.js CHANGED
@@ -11,6 +11,7 @@
11
11
  * built-in glyph-width table, so sizing is the same in every browser and in
12
12
  * Node (the agent's checks).
13
13
  */
14
+ import { HEX_COLOR_PATTERN, NOTE_COLORS } from "./schema.js";
14
15
  /** Most cells one table holds, and most bytes of its JSON. */
15
16
  export const TABLE_LIMITS = { cells: 3000, bytes: 194_560 };
16
17
  /** Most row or column keys read from one table. */
@@ -101,6 +102,14 @@ export function tableCellGrid(table) {
101
102
  const columns = tableColumnIds(table);
102
103
  return tableRowIds(table).map((rowId) => columns.map((columnId) => tableCellValue(table, rowId, columnId)));
103
104
  }
105
+ /** A cell fill or heat-map color: a block color name or `#rrggbb` (lower-cased); `undefined` for anything else, `""` included. */
106
+ export function tableTintColor(value) {
107
+ if (typeof value !== 'string')
108
+ return undefined;
109
+ if (NOTE_COLORS.includes(value))
110
+ return value;
111
+ return HEX_COLOR_PATTERN.test(value) ? value.toLowerCase() : undefined;
112
+ }
104
113
  /** True when a grid of this size would exceed {@link TABLE_LIMITS}. */
105
114
  export function exceedsTableCellLimit(rows, columns) {
106
115
  return rows * columns > TABLE_LIMITS.cells;
@@ -295,11 +304,23 @@ function rowCellEntries(row) {
295
304
  function mapObjectValues(record, map) {
296
305
  return Object.fromEntries(Object.entries(record).map(([key, value]) => [key, map(value, key)]));
297
306
  }
307
+ /** The colors of `raw` (key → color) whose key `keep` accepts, sorted by key; `undefined` when none is left. */
308
+ function tintColorMap(raw, keep) {
309
+ const entries = (isRecord(raw) ? Object.entries(raw) : []).flatMap(([key, value]) => {
310
+ const color = tableTintColor(value);
311
+ return color !== undefined && keep(key) ? [[key, color]] : [];
312
+ });
313
+ return entries.length > 0 ? sortedEntriesObject(entries) : undefined;
314
+ }
298
315
  /**
299
316
  * Cleans up a table's `cols` and `rows`: valid keys only (sorted, capped),
300
317
  * columns derived from the cells when missing, cells as strings, and at
301
318
  * least one row and one column. Empty cells of unknown columns are kept as
302
319
  * `""` (they are tombstones a concurrent column delete left).
320
+ *
321
+ * `fills` and `heat` keep valid colors of rows and columns that exist. A
322
+ * cell written as `{text, color}` reads as its text, with its color as the
323
+ * cell's fill unless `fills` names that cell.
303
324
  */
304
325
  export function normalizeTable(raw, cellText) {
305
326
  const entriesOf = (record, limit) => {
@@ -320,7 +341,8 @@ export function normalizeTable(raw, cellText) {
320
341
  });
321
342
  if (normalizedCols.length === 0)
322
343
  normalizedCols.push(['c1', {}]);
323
- const cellValue = (value) => typeof value === 'string' ? cellText(value) : typeof value === 'number' || typeof value === 'boolean' ? String(value) : undefined;
344
+ const plainCellValue = (value) => typeof value === 'string' ? cellText(value) : typeof value === 'number' || typeof value === 'boolean' ? String(value) : undefined;
345
+ const cellValue = (value) => plainCellValue(isRecord(value) ? value.text : value);
324
346
  const columnIds = new Set(normalizedCols.map(([key]) => key));
325
347
  const emptyCells = (row) => Object.keys(row).flatMap((key) => (row[key] === '' && !columnIds.has(key) && isTableKey(key) ? [[key, '']] : []));
326
348
  const normalizedRows = keptRows.map(([key, row]) => [
@@ -335,7 +357,34 @@ export function normalizeTable(raw, cellText) {
335
357
  ]);
336
358
  if (normalizedRows.length === 0)
337
359
  normalizedRows.push(['r1', {}]);
338
- return { cols: sortedEntriesObject(normalizedCols), rows: sortedEntriesObject(normalizedRows) };
360
+ const rowIds = new Set(normalizedRows.map(([key]) => key));
361
+ const rawRows = new Map(keptRows);
362
+ const rawFills = isRecord(raw.fills) ? raw.fills : {};
363
+ const fills = normalizedRows.flatMap(([rowId]) => {
364
+ const legacy = Object.fromEntries(Object.entries(rawRows.get(rowId) ?? {}).flatMap(([key, cell]) => (isRecord(cell) ? [[key, cell.color]] : [])));
365
+ const ownFills = rawFills[rowId];
366
+ const cells = tintColorMap({ ...legacy, ...(isRecord(ownFills) ? ownFills : {}) }, (key) => columnIds.has(key));
367
+ return cells !== undefined ? [[rowId, cells]] : [];
368
+ });
369
+ const rawHeat = isRecord(raw.heat) ? raw.heat : {};
370
+ const heatCols = tintColorMap(rawHeat.cols, (key) => columnIds.has(key));
371
+ const headRowId = raw.head !== false ? sortedTableKeys(Object.fromEntries(normalizedRows))[0] : undefined;
372
+ const heatRows = tintColorMap(rawHeat.rows, (key) => rowIds.has(key) && key !== headRowId);
373
+ const heat = { ...(heatCols !== undefined ? { cols: heatCols } : {}), ...(heatRows !== undefined ? { rows: heatRows } : {}) };
374
+ return {
375
+ cols: sortedEntriesObject(normalizedCols),
376
+ rows: sortedEntriesObject(normalizedRows),
377
+ ...(fills.length > 0 ? { fills: sortedEntriesObject(fills) } : {}),
378
+ ...(heatCols !== undefined || heatRows !== undefined ? { heat } : {}),
379
+ };
380
+ }
381
+ /** True when a fill or a heat map tints the row. */
382
+ export function tableRowIsTinted(table, rowId) {
383
+ return table.heat?.rows?.[rowId] !== undefined || Object.keys(table.fills?.[rowId] ?? {}).length > 0;
384
+ }
385
+ /** True when a fill or a heat map tints the column. */
386
+ export function tableColumnIsTinted(table, columnId) {
387
+ return table.heat?.cols?.[columnId] !== undefined || Object.values(table.fills ?? {}).some((cells) => cells[columnId] !== undefined);
339
388
  }
340
389
  /** A table from a grid of texts (rows of cells). */
341
390
  export function tableFromGrid(grid) {
@@ -505,8 +554,8 @@ export function scaleTableWidth(table, width, reference = table) {
505
554
  }
506
555
  /**
507
556
  * Undo/redo of a table edit applied over current content: takes the
508
- * incoming rows and columns but keeps column widths that changed locally
509
- * since `base`.
557
+ * incoming rows, columns, fills and heat maps but keeps column widths that
558
+ * changed locally since `base`.
510
559
  */
511
560
  export function mergeTableEdit(current, incoming, base) {
512
561
  if (current.type !== 'table' || incoming.type !== 'table')
@@ -514,13 +563,17 @@ export function mergeTableEdit(current, incoming, base) {
514
563
  const local = current;
515
564
  const remote = incoming;
516
565
  const baseTable = base?.type === 'table' ? base : undefined;
517
- if (local.cols === remote.cols && local.rows === remote.rows)
566
+ if (local.cols === remote.cols && local.rows === remote.rows && local.fills === remote.fills && local.heat === remote.heat)
518
567
  return current;
519
568
  const cols = mapObjectValues(remote.cols, (column, key) => {
520
569
  const width = baseTable !== undefined && local.cols[key] !== undefined && baseTable.cols[key]?.w !== local.cols[key]?.w ? local.cols[key]?.w : column.w;
521
570
  return { ...atField(column.at), ...(width !== undefined ? { w: width } : {}) };
522
571
  });
523
- return { ...current, cols, rows: remote.rows };
572
+ const merged = { ...current, cols, rows: remote.rows, fills: remote.fills, heat: remote.heat };
573
+ for (const field of ['fills', 'heat'])
574
+ if (merged[field] === undefined)
575
+ Reflect.deleteProperty(merged, field);
576
+ return merged;
524
577
  }
525
578
  /* -------------------------------------------------------------------------- */
526
579
  /* TSV */
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Text placeholders: a hint a free text shows while it holds nothing but
3
+ * whitespace. The hint is laid out, measured and hit like text, but it is
4
+ * not content: it is not exported and an empty text keeping one is not
5
+ * removed when its edit ends.
6
+ */
7
+ import type { BoardElement, TextElement } from '../schema.ts';
8
+ /** A free text whose placeholder is showing. */
9
+ export type PlaceholderText = TextElement & {
10
+ placeholder: string;
11
+ };
12
+ /** Smallest on-screen height, px, a text showing its placeholder is hit over. */
13
+ export declare const PLACEHOLDER_HIT_MIN_PX = 40;
14
+ /** True when the element is a text showing its placeholder (its text is blank after trimming). */
15
+ export declare function showsTextPlaceholder(element: BoardElement): element is PlaceholderText;
16
+ /** What a text lays out as: its placeholder while that shows, else its text. */
17
+ export declare function textOrPlaceholder(element: TextElement): string;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Text placeholders: a hint a free text shows while it holds nothing but
3
+ * whitespace. The hint is laid out, measured and hit like text, but it is
4
+ * not content: it is not exported and an empty text keeping one is not
5
+ * removed when its edit ends.
6
+ */
7
+ /** Smallest on-screen height, px, a text showing its placeholder is hit over. */
8
+ export const PLACEHOLDER_HIT_MIN_PX = 40;
9
+ /** True when the element is a text showing its placeholder (its text is blank after trimming). */
10
+ export function showsTextPlaceholder(element) {
11
+ return element.type === 'text' && element.placeholder !== undefined && element.placeholder !== '' && element.text.trim() === '';
12
+ }
13
+ /** What a text lays out as: its placeholder while that shows, else its text. */
14
+ export function textOrPlaceholder(element) {
15
+ return showsTextPlaceholder(element) ? element.placeholder : element.text;
16
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Push-down while typing: as an edit makes a free text taller, the items
3
+ * right below it move down by the growth, so the text never runs over them.
4
+ *
5
+ * The plan is taken once, when the edit starts: unlocked items whose top is
6
+ * at or below the text's bottom and that overlap it horizontally, in the
7
+ * same section and the same group as the text (a section moves with its
8
+ * content, a host with its stickers). A turned text pushes nothing.
9
+ */
10
+ import { type Box, type ElementMeasures } from '../geometry.ts';
11
+ import { type BoardElement, type ElementId } from '../schema.ts';
12
+ /** Who a growing text pushes down. */
13
+ export interface TextPushPlan {
14
+ /** The growing text. */
15
+ id: ElementId;
16
+ /** The text's bottom when the edit started. */
17
+ bottom: number;
18
+ /** Everything that moves (contents of pushed sections and stickers on pushed hosts included). */
19
+ ids: ReadonlySet<ElementId>;
20
+ /** Boxes of the pushed sections (free arrow ends inside them move along). */
21
+ frames: readonly Box[];
22
+ }
23
+ /**
24
+ * The push plan for the text `id` (see the module comment); `undefined`
25
+ * when it is not an unturned text or nothing sits below it.
26
+ */
27
+ export declare function planTextPush(elements: readonly BoardElement[], id: ElementId, measures?: ElementMeasures): TextPushPlan | undefined;
28
+ /** How far a plan's items are pushed while the text's box is `box`: its growth below the starting bottom, never negative. */
29
+ export declare function textPushGrowth(plan: Pick<TextPushPlan, 'bottom'>, box: Box | undefined): number;
@@ -0,0 +1,72 @@
1
+ /**
2
+ * Push-down while typing: as an edit makes a free text taller, the items
3
+ * right below it move down by the growth, so the text never runs over them.
4
+ *
5
+ * The plan is taken once, when the edit starts: unlocked items whose top is
6
+ * at or below the text's bottom and that overlap it horizontally, in the
7
+ * same section and the same group as the text (a section moves with its
8
+ * content, a host with its stickers). A turned text pushes nothing.
9
+ */
10
+ import { findStickerHost, stickersOnHosts } from "../attachments.js";
11
+ import { elementBounds, elementLayoutBox } from "../geometry.js";
12
+ import { outermostGroupOf } from "../groups.js";
13
+ import { elementSitsInBox, sectionsSmallestFirst } from "../layout.js";
14
+ import { elementTurn, isElementLocked } from "../schema.js";
15
+ import { collectMoveIds } from "../selection.js";
16
+ /** The smallest section an element sits in (not itself); `undefined` on the open board. */
17
+ function sectionHolding(element, sections, measures) {
18
+ const box = elementLayoutBox(element, measures);
19
+ if (box === undefined)
20
+ return undefined;
21
+ for (const section of sections) {
22
+ if (section.id === element.id)
23
+ continue;
24
+ const frame = elementLayoutBox(section, measures);
25
+ if (frame !== undefined && elementSitsInBox(frame, element, box))
26
+ return section.id;
27
+ }
28
+ return undefined;
29
+ }
30
+ /**
31
+ * The push plan for the text `id` (see the module comment); `undefined`
32
+ * when it is not an unturned text or nothing sits below it.
33
+ */
34
+ export function planTextPush(elements, id, measures) {
35
+ const text = elements.find((element) => element.id === id);
36
+ if (text?.type !== 'text' || elementTurn(text) !== 0)
37
+ return undefined;
38
+ const box = elementLayoutBox(text, measures);
39
+ if (box === undefined)
40
+ return undefined;
41
+ const bottom = box.y + box.h;
42
+ const sections = sectionsSmallestFirst(elements);
43
+ const section = sectionHolding(text, sections, measures);
44
+ const group = outermostGroupOf(elements, text.id);
45
+ const pushed = new Set();
46
+ for (const element of elements) {
47
+ if (element.id === text.id || element.type === 'arrow' || isElementLocked(element))
48
+ continue;
49
+ if (element.type === 'sticker' && findStickerHost(element, elements, measures) !== undefined)
50
+ continue;
51
+ const bounds = elementBounds(element, measures);
52
+ if (bounds === undefined || bounds.y < bottom - 0.5)
53
+ continue;
54
+ if (bounds.x >= box.x + box.w || bounds.x + bounds.w <= box.x)
55
+ continue;
56
+ if (sectionHolding(element, sections, measures) !== section || outermostGroupOf(elements, element.id) !== group)
57
+ continue;
58
+ pushed.add(element.id);
59
+ }
60
+ if (pushed.size === 0)
61
+ return undefined;
62
+ const moving = collectMoveIds(elements, pushed, measures);
63
+ for (const sticker of stickersOnHosts(moving, elements, measures))
64
+ moving.add(sticker);
65
+ moving.delete(text.id);
66
+ const frames = elements.flatMap((element) => (element.type === 'container' && pushed.has(element.id) ? (elementLayoutBox(element, measures) ?? []) : []));
67
+ return { id: text.id, bottom, ids: moving, frames };
68
+ }
69
+ /** How far a plan's items are pushed while the text's box is `box`: its growth below the starting bottom, never negative. */
70
+ export function textPushGrowth(plan, box) {
71
+ return box === undefined ? 0 : Math.max(0, Math.round(box.y + box.h - plan.bottom));
72
+ }
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Keeping a turned item's anchor corner in place while its size changes.
3
+ *
4
+ * Items turn about their center, so a turned note or text that grows (more
5
+ * text, a bigger size) would otherwise drift on screen. The corner the
6
+ * person reads from stays put instead: the top edge at the side the text is
7
+ * aligned to (top-left for left-aligned text, top-right for right-aligned,
8
+ * the middle of the top edge for centered).
9
+ */
10
+ import type { Box } from '../geometry.ts';
11
+ import type { TextAlign } from '../schema.ts';
12
+ /**
13
+ * The top-left that keeps the anchor corner of `box` (turned `degrees`,
14
+ * aligned `align`) on the same board point once the box is `w` × `h`.
15
+ */
16
+ export declare function keepTurnedAnchor(box: Box, degrees: number, w: number, h: number, align: TextAlign): {
17
+ x: number;
18
+ y: number;
19
+ };
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Keeping a turned item's anchor corner in place while its size changes.
3
+ *
4
+ * Items turn about their center, so a turned note or text that grows (more
5
+ * text, a bigger size) would otherwise drift on screen. The corner the
6
+ * person reads from stays put instead: the top edge at the side the text is
7
+ * aligned to (top-left for left-aligned text, top-right for right-aligned,
8
+ * the middle of the top edge for centered).
9
+ */
10
+ /** Where along the top edge the anchor sits, as a share of the width. */
11
+ const ANCHOR_SHARE = { left: 0, center: 0.5, right: 1 };
12
+ /** A point of a box turned `degrees` clockwise about its center, given relative to its unturned top-left. */
13
+ function turnedPoint(box, degrees, dx, dy) {
14
+ const radians = (degrees * Math.PI) / 180;
15
+ const cos = Math.cos(radians);
16
+ const sin = Math.sin(radians);
17
+ const rx = dx - box.w / 2;
18
+ const ry = dy - box.h / 2;
19
+ return { x: box.x + box.w / 2 + rx * cos - ry * sin, y: box.y + box.h / 2 + rx * sin + ry * cos };
20
+ }
21
+ /**
22
+ * The top-left that keeps the anchor corner of `box` (turned `degrees`,
23
+ * aligned `align`) on the same board point once the box is `w` × `h`.
24
+ */
25
+ export function keepTurnedAnchor(box, degrees, w, h, align) {
26
+ if (degrees % 360 === 0 && align === 'left')
27
+ return { x: box.x, y: box.y };
28
+ const share = ANCHOR_SHARE[align];
29
+ const anchor = turnedPoint(box, degrees, share * box.w, 0);
30
+ const moved = turnedPoint({ x: 0, y: 0, w, h }, degrees, share * w, 0);
31
+ return { x: anchor.x - moved.x, y: anchor.y - moved.y };
32
+ }