@widgetic/creator 0.4.48 → 0.4.50

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.
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Puts a row of `POST /widgets/batch` onto the row the creator already has for the same widget, and keeps what the batch row
3
+ * does not carry.
4
+ *
5
+ * The creator reads the widget list as raw JSON, so its rows hold every field the gateway sends (`hasLiveVersion`,
6
+ * `lastPublishCommitSha`, `thumbnailUrl`, `canvas_id`, ...). The batch is read through the generated `Widget` model, which
7
+ * carries fewer fields, and gives `undefined` for the ones it knows but the answer lacks. Writing a batch row over a list row
8
+ * drops the live commit of a published widget, and with it the "published, with unpublished changes" state of the bar
9
+ * above the sketch ("Saved" and "Publish changes"): the bar then read "Live" with no button, or "Publish changes" when the
10
+ * answer came in the other order.
11
+ *
12
+ * - A field the batch row has a value for (a `null` included) is the batch row's: it is the newer read.
13
+ * - A field the batch row lacks (absent or `undefined`) stays as the list row had it.
14
+ * - Neither input is changed; a widget with no earlier row is the batch row as it is.
15
+ */
16
+ export declare function mergeBatchWidgetOntoListRecord<WidgetRow extends object>(listRecord: object | null | undefined, batchRecord: WidgetRow): WidgetRow;
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Puts a row of `POST /widgets/batch` onto the row the creator already has for the same widget, and keeps what the batch row
3
+ * does not carry.
4
+ *
5
+ * The creator reads the widget list as raw JSON, so its rows hold every field the gateway sends (`hasLiveVersion`,
6
+ * `lastPublishCommitSha`, `thumbnailUrl`, `canvas_id`, ...). The batch is read through the generated `Widget` model, which
7
+ * carries fewer fields, and gives `undefined` for the ones it knows but the answer lacks. Writing a batch row over a list row
8
+ * drops the live commit of a published widget, and with it the "published, with unpublished changes" state of the bar
9
+ * above the sketch ("Saved" and "Publish changes"): the bar then read "Live" with no button, or "Publish changes" when the
10
+ * answer came in the other order.
11
+ *
12
+ * - A field the batch row has a value for (a `null` included) is the batch row's: it is the newer read.
13
+ * - A field the batch row lacks (absent or `undefined`) stays as the list row had it.
14
+ * - Neither input is changed; a widget with no earlier row is the batch row as it is.
15
+ */
16
+ export function mergeBatchWidgetOntoListRecord(listRecord, batchRecord) {
17
+ if (!listRecord)
18
+ return batchRecord;
19
+ try {
20
+ const mergedRecord = { ...listRecord };
21
+ for (const [fieldName, fieldValue] of Object.entries(batchRecord)) {
22
+ if (fieldValue !== undefined)
23
+ mergedRecord[fieldName] = fieldValue;
24
+ }
25
+ return mergedRecord;
26
+ }
27
+ catch (mergeError) {
28
+ // A row that cannot be copied is not a reason to lose the batch answer: the batch row stands, as before this helper.
29
+ console.warn('[mergeBatchWidgetOntoListRecord] could not merge the batch row onto the list row', mergeError);
30
+ return batchRecord;
31
+ }
32
+ }
@@ -8,9 +8,8 @@ export declare function isSketchGenerationFailed(panelState: PanelCodegenFlags,
8
8
  /** Figma ready frame: caption "Saved 2m ago" from widget `updatedAt`. */
9
9
  export declare function sketchSavedStatusLabel(savedWord: string, updatedAt: unknown, nowMs?: number): string;
10
10
  /**
11
- * The bar of the Figma frames carries Publish in every state except while the widget is being built (526:2466) and after a
12
- * failed build (526:2984). A canvas that has no widget yet (the Empty frame) shows it too, as the way of learning that
13
- * Send comes first: a bar with no Publish at all on a new canvas read as "Publish is missing".
11
+ * Figma Creator Bar (514:43): Publish is visible on Ready (526:2706) and Publish changes on History (1248:74452); hidden on
12
+ * Empty, Generating, Failed, and Published-without-changes (524:635, 526:2466, 526:2984, 526:3238).
14
13
  */
15
14
  export declare function sketchBarShowsPublish(input: {
16
15
  embedded: boolean;
@@ -19,7 +18,15 @@ export declare function sketchBarShowsPublish(input: {
19
18
  showsLive: boolean;
20
19
  generating: boolean;
21
20
  failed: boolean;
21
+ hasUnpublishedChanges?: boolean;
22
22
  }): boolean;
23
+ /**
24
+ * The widget row carries two commits: HEAD, the newest commit the server has for the widget (`lastCommitSha`), and live, the
25
+ * commit of the published version (`lastPublishCommitSha`). When both are there and they differ, the widget has changes that
26
+ * are not published, whatever this browser has seen: a build made on another device, or before this browser was opened, leaves
27
+ * nothing in its storage. `isSameCommit` is the creator's own comparison (it accepts a short SHA against a long one).
28
+ */
29
+ export declare function widgetRowHeadIsAheadOfLive(widget: Record<string, unknown> | null | undefined, isSameCommit: (headSha: string, liveSha: string) => boolean): boolean;
23
30
  export declare function sketchBarShowsCustomize(input: {
24
31
  embedded: boolean;
25
32
  widgetId: string | null;
@@ -29,15 +29,35 @@ export function sketchSavedStatusLabel(savedWord, updatedAt, nowMs = Date.now())
29
29
  return savedWord;
30
30
  }
31
31
  /**
32
- * The bar of the Figma frames carries Publish in every state except while the widget is being built (526:2466) and after a
33
- * failed build (526:2984). A canvas that has no widget yet (the Empty frame) shows it too, as the way of learning that
34
- * Send comes first: a bar with no Publish at all on a new canvas read as "Publish is missing".
32
+ * Figma Creator Bar (514:43): Publish is visible on Ready (526:2706) and Publish changes on History (1248:74452); hidden on
33
+ * Empty, Generating, Failed, and Published-without-changes (524:635, 526:2466, 526:2984, 526:3238).
35
34
  */
36
35
  export function sketchBarShowsPublish(input) {
37
36
  void input.widgetId;
38
- void input.hasGeneratedCode;
39
- void input.showsLive;
40
- return input.embedded && !input.generating && !input.failed;
37
+ if (!input.embedded || input.generating || input.failed)
38
+ return false;
39
+ if (!input.hasGeneratedCode)
40
+ return false;
41
+ if (!input.showsLive)
42
+ return true;
43
+ return !!input.hasUnpublishedChanges;
44
+ }
45
+ /**
46
+ * The widget row carries two commits: HEAD, the newest commit the server has for the widget (`lastCommitSha`), and live, the
47
+ * commit of the published version (`lastPublishCommitSha`). When both are there and they differ, the widget has changes that
48
+ * are not published, whatever this browser has seen: a build made on another device, or before this browser was opened, leaves
49
+ * nothing in its storage. `isSameCommit` is the creator's own comparison (it accepts a short SHA against a long one).
50
+ */
51
+ export function widgetRowHeadIsAheadOfLive(widget, isSameCommit) {
52
+ if (!widget)
53
+ return false;
54
+ const headSha = String(widget.lastCommitSha ?? widget.last_commit_sha ?? '').trim();
55
+ const liveSha = String(widget.lastPublishCommitSha
56
+ ?? widget.last_publish_commit_sha
57
+ ?? '').trim();
58
+ if (!headSha || !liveSha)
59
+ return false;
60
+ return !isSameCommit(headSha, liveSha);
41
61
  }
42
62
  export function sketchBarShowsCustomize(input) {
43
63
  return (input.embedded &&
@@ -0,0 +1,34 @@
1
+ /**
2
+ * What a one-widget sketch canvas shows after the card of its widget leaves the board (Delete widget, item 21) and when it comes back
3
+ * (Undo). Everything the canvas draws around the board — the name in the bar, the "ready" chip, the selector bar in place of the
4
+ * drawing tools, the widget's chat — follows the primary widget id, so the id has to follow the card.
5
+ */
6
+ export type SketchBoardAfterDeleteInput = {
7
+ /** The widget whose card the person took off the board with Delete widget; null when they have not. */
8
+ deletedWidgetId: string | null;
9
+ /** The widget the canvas speaks for right now. */
10
+ primaryWidgetId: string | null;
11
+ /** The widgets that have a card on the board right now. */
12
+ linkedWidgetIds: ReadonlySet<string>;
13
+ };
14
+ export type SketchBoardAfterDeleteStep =
15
+ /** Nothing to do. */
16
+ {
17
+ kind: 'keep';
18
+ }
19
+ /** The card is off the board but the canvas still speaks for its widget: the canvas is empty again (Redo of the delete). */
20
+ | {
21
+ kind: 'clear';
22
+ widgetId: string;
23
+ }
24
+ /** The card is back on the board and the canvas speaks for nobody: the widget is the canvas's widget again (Undo). */
25
+ | {
26
+ kind: 'restore';
27
+ widgetId: string;
28
+ }
29
+ /** Another widget has taken the canvas over (a new first message): the deleted one is no longer ours to give back. */
30
+ | {
31
+ kind: 'forget';
32
+ };
33
+ /** Decides, after the board changed, how the primary widget id has to move for the widget the person deleted. */
34
+ export declare function stepAfterBoardChange(input: SketchBoardAfterDeleteInput): SketchBoardAfterDeleteStep;
@@ -0,0 +1,20 @@
1
+ /**
2
+ * What a one-widget sketch canvas shows after the card of its widget leaves the board (Delete widget, item 21) and when it comes back
3
+ * (Undo). Everything the canvas draws around the board — the name in the bar, the "ready" chip, the selector bar in place of the
4
+ * drawing tools, the widget's chat — follows the primary widget id, so the id has to follow the card.
5
+ */
6
+ /** Decides, after the board changed, how the primary widget id has to move for the widget the person deleted. */
7
+ export function stepAfterBoardChange(input) {
8
+ const deletedWidgetId = (input.deletedWidgetId ?? '').trim();
9
+ if (!deletedWidgetId)
10
+ return { kind: 'keep' };
11
+ const primaryWidgetId = (input.primaryWidgetId ?? '').trim();
12
+ if (primaryWidgetId && primaryWidgetId !== deletedWidgetId)
13
+ return { kind: 'forget' };
14
+ const cardIsOnBoard = input.linkedWidgetIds.has(deletedWidgetId);
15
+ if (cardIsOnBoard && !primaryWidgetId)
16
+ return { kind: 'restore', widgetId: deletedWidgetId };
17
+ if (!cardIsOnBoard && primaryWidgetId === deletedWidgetId)
18
+ return { kind: 'clear', widgetId: deletedWidgetId };
19
+ return { kind: 'keep' };
20
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Figma Generation Chip on the sketch canvas (520:586): Generating / Ready / Failed while the widget builds.
3
+ */
4
+ export type SketchBoardStatusChipVariant = 'generating' | 'ready' | 'failed';
5
+ export type SketchBoardStatusChipState = {
6
+ variant: SketchBoardStatusChipVariant;
7
+ showAction: boolean;
8
+ } | null;
9
+ export declare function resolveSketchBoardStatusChip(input: {
10
+ embedded: boolean;
11
+ generating: boolean;
12
+ failed: boolean;
13
+ hasGeneratedCode: boolean;
14
+ showsLive: boolean;
15
+ }): SketchBoardStatusChipState;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Figma Generation Chip on the sketch canvas (520:586): Generating / Ready / Failed while the widget builds.
3
+ */
4
+ export function resolveSketchBoardStatusChip(input) {
5
+ if (!input.embedded)
6
+ return null;
7
+ if (input.generating) {
8
+ return { variant: 'generating', showAction: true };
9
+ }
10
+ if (input.failed) {
11
+ return { variant: 'failed', showAction: true };
12
+ }
13
+ if (input.hasGeneratedCode && !input.showsLive) {
14
+ return { variant: 'ready', showAction: false };
15
+ }
16
+ return null;
17
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * When the sketch embed swaps the drawing toolbar for the element selector bar (item 20).
3
+ */
4
+ export type SketchToolbarModeInput = {
5
+ /** Widget has a successful build artifact (commit, generated code, or published version). */
6
+ hasBuiltArtifact: boolean;
7
+ /** Code generation is in progress for the primary widget. */
8
+ generating: boolean;
9
+ /** Last generation failed (panel or widget flags). */
10
+ generationFailed: boolean;
11
+ };
12
+ /** True when the selector bar should replace the drawing tools (success only). */
13
+ export declare function shouldHideDrawingToolbarForSelector(input: SketchToolbarModeInput): boolean;
@@ -0,0 +1,13 @@
1
+ /**
2
+ * When the sketch embed swaps the drawing toolbar for the element selector bar (item 20).
3
+ */
4
+ /** True when the selector bar should replace the drawing tools (success only). */
5
+ export function shouldHideDrawingToolbarForSelector(input) {
6
+ if (!input.hasBuiltArtifact)
7
+ return false;
8
+ if (input.generating)
9
+ return false;
10
+ if (input.generationFailed)
11
+ return false;
12
+ return true;
13
+ }
@@ -0,0 +1,50 @@
1
+ /**
2
+ * Two decisions the creator makes when it saves the canvas, kept out of `CreatorApp.svelte` so that they can be tested.
3
+ *
4
+ * - **Is an empty canvas written over a canvas that had shapes?** A save that sends no shapes over a server copy that had
5
+ * some is how a canvas is wiped, by a snapshot that looks empty for the wrong reason (the board was not loaded, the page
6
+ * is being torn down). It is refused, unless the canvas itself reported a change since the last save got past this
7
+ * guard: a person who selected everything and pressed Delete emptied the board on purpose, and a server that kept the
8
+ * old shapes would show them again at the next visit.
9
+ * - **Does the request ask the browser to keep it alive?** A page that is going away (the tab closes, a reload) drops a
10
+ * request that is still on its way, and the last changes are lost. `keepalive` lets the browser finish it, for bodies of
11
+ * up to 64 KB.
12
+ */
13
+ /** What the guard against an empty canvas is told about the save. */
14
+ export interface EmptyCanvasGuardInput {
15
+ /** How many shapes the canvas to save has. */
16
+ shapesToSave: number;
17
+ /** How many shapes the last save that got past the guard had. */
18
+ shapesSavedBefore: number;
19
+ /** The save is the one made when the canvas component is torn down (a hot reload, a navigation): its snapshot is never trusted when it is empty. */
20
+ isUnmountSave: boolean;
21
+ /** The canvas reported a change since the last save got past the guard. */
22
+ changedSinceLastSave: boolean;
23
+ }
24
+ /**
25
+ * True when the save must be refused: it would put an empty canvas over one that had shapes, and nothing says the person did it.
26
+ * An empty canvas over an empty one, and over one that had a single shape (the last one was deleted), is always allowed.
27
+ */
28
+ export declare function refusesEmptyCanvas(input: EmptyCanvasGuardInput): boolean;
29
+ /** The most a request that outlives its page may carry, in bytes. The browser's limit is 64 KB for the body and the headers together. */
30
+ export declare const KEEPALIVE_BODY_LIMIT_BYTES = 60000;
31
+ /** Whether the text can go in a request that outlives its page. */
32
+ export declare function fitsKeepaliveRequest(text: string): boolean;
33
+ /** What the page tells about itself: whether it is being torn down, and what the document says about being seen. */
34
+ export interface PageState {
35
+ isUnmountSave: boolean;
36
+ /**
37
+ * The canvas says the page is going away (`pagehide`). It cannot be read from `visibilityState`: the browser sends `pagehide`
38
+ * while the document still says `visible` (`hidden` comes a moment later), so a save made in that moment would not be kept
39
+ * alive and would go with the page: that is how a text typed a second before a reload was lost.
40
+ */
41
+ pageIsLeaving?: boolean;
42
+ visibilityState: string | null | undefined;
43
+ }
44
+ /**
45
+ * The extra options of the save request: `{ keepalive: true }` when the page is going away or is hidden and the canvas fits,
46
+ * nothing otherwise (a request that is not kept alive can carry any size).
47
+ */
48
+ export declare function requestInitForSave(json: string, page: PageState): {
49
+ keepalive: true;
50
+ } | undefined;
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Two decisions the creator makes when it saves the canvas, kept out of `CreatorApp.svelte` so that they can be tested.
3
+ *
4
+ * - **Is an empty canvas written over a canvas that had shapes?** A save that sends no shapes over a server copy that had
5
+ * some is how a canvas is wiped, by a snapshot that looks empty for the wrong reason (the board was not loaded, the page
6
+ * is being torn down). It is refused, unless the canvas itself reported a change since the last save got past this
7
+ * guard: a person who selected everything and pressed Delete emptied the board on purpose, and a server that kept the
8
+ * old shapes would show them again at the next visit.
9
+ * - **Does the request ask the browser to keep it alive?** A page that is going away (the tab closes, a reload) drops a
10
+ * request that is still on its way, and the last changes are lost. `keepalive` lets the browser finish it, for bodies of
11
+ * up to 64 KB.
12
+ */
13
+ /**
14
+ * True when the save must be refused: it would put an empty canvas over one that had shapes, and nothing says the person did it.
15
+ * An empty canvas over an empty one, and over one that had a single shape (the last one was deleted), is always allowed.
16
+ */
17
+ export function refusesEmptyCanvas(input) {
18
+ if (input.shapesToSave !== 0 || input.shapesSavedBefore <= 0)
19
+ return false;
20
+ if (input.isUnmountSave)
21
+ return true;
22
+ return input.shapesSavedBefore > 1 && !input.changedSinceLastSave;
23
+ }
24
+ /** The most a request that outlives its page may carry, in bytes. The browser's limit is 64 KB for the body and the headers together. */
25
+ export const KEEPALIVE_BODY_LIMIT_BYTES = 60_000;
26
+ /** Whether the text can go in a request that outlives its page. */
27
+ export function fitsKeepaliveRequest(text) {
28
+ try {
29
+ return new TextEncoder().encode(text).length <= KEEPALIVE_BODY_LIMIT_BYTES;
30
+ }
31
+ catch {
32
+ return false;
33
+ }
34
+ }
35
+ /**
36
+ * The extra options of the save request: `{ keepalive: true }` when the page is going away or is hidden and the canvas fits,
37
+ * nothing otherwise (a request that is not kept alive can carry any size).
38
+ */
39
+ export function requestInitForSave(json, page) {
40
+ const leaving = page.isUnmountSave || page.pageIsLeaving === true || page.visibilityState === 'hidden';
41
+ return leaving && fitsKeepaliveRequest(json) ? { keepalive: true } : undefined;
42
+ }
package/package.json CHANGED
@@ -1,15 +1,15 @@
1
1
  {
2
2
  "name": "@widgetic/creator",
3
- "version": "0.4.48",
3
+ "version": "0.4.50",
4
4
  "license": "SEE LICENSE IN LICENSE",
5
5
  "type": "module",
6
6
  "peerDependencies": {
7
7
  "@sveltejs/kit": "^2.20.0",
8
8
  "@widgetic/api-sdk": "^2.0.0",
9
9
  "@widgetic/cache-layer": "^0.1.2",
10
- "@widgetic/canvas": "^0.5.36",
11
- "@widgetic/chat": "^0.1.36",
12
- "@widgetic/design-system": "^0.5.32",
10
+ "@widgetic/canvas": "^0.5.39",
11
+ "@widgetic/chat": "^0.1.38",
12
+ "@widgetic/design-system": "^0.5.39",
13
13
  "@widgetic/editor": "^4.1.3",
14
14
  "@widgetic/file-browser": "^0.5.25",
15
15
  "svelte": "^5.25.0"
@@ -74,9 +74,9 @@
74
74
  "@types/node": "26.4.0",
75
75
  "@widgetic/api-sdk": "^2.0.0",
76
76
  "@widgetic/cache-layer": "^0.1.2",
77
- "@widgetic/canvas": "^0.5.36",
78
- "@widgetic/chat": "^0.1.36",
79
- "@widgetic/design-system": "^0.5.32",
77
+ "@widgetic/canvas": "^0.5.39",
78
+ "@widgetic/chat": "^0.1.38",
79
+ "@widgetic/design-system": "^0.5.39",
80
80
  "@widgetic/dev-tools": "^0.3.0",
81
81
  "@widgetic/editor": "^4.1.3",
82
82
  "@widgetic/file-browser": "^0.5.25",