@softure-ai/marketing-kit 0.38.0 → 0.39.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.
@@ -71,6 +71,17 @@ export const LIST_CHIP_GAP_EM = 0.3;
71
71
  export const LIST_CHIP_BADGE_EM = { size: 1.1, gap: 0.35 };
72
72
  /** How opaque a chip's point stays once the next point is in: it steps back, the newest point leads. */
73
73
  export const LIST_CHIP_COVERED_OPACITY = 0.55;
74
+ /**
75
+ * The smallest type a row of chips shrinks to, in px of a 1080 px wide frame: past a title's three shrinks a row keeps
76
+ * shrinking down to it, so the step badges never turn a row that fitted without them into a refusal.
77
+ */
78
+ export const LIST_CHIP_MIN_FONT_SIZE = 36;
79
+ /**
80
+ * The smallest type a row of chips shrinks to so it can sit on the frame's axis (RV-185 of an adopting app), in px of a
81
+ * 1080 px wide frame: in the centred span only, where a row that fits the whole zone at `LIST_CHIP_MIN_FONT_SIZE` would
82
+ * otherwise stand off the axis.
83
+ */
84
+ export const LIST_CHIP_CENTRED_MIN_FONT_SIZE = 32;
74
85
  /** A place card title's line height, tighter for its big type. */
75
86
  export const OVERLAY_TITLE_LINE_HEIGHT = 1.05;
76
87
  export const OVERLAY_PADDING_EM = { x: 0.6, y: 0.35 };
@@ -255,13 +266,23 @@ function getBoxesUnion(boxes) {
255
266
  * A list's drawn boxes after each point has come in (RV-144 of an adopting app): `cards[i]` is what shows once points
256
267
  * 0 to i are in. A stack's card grows with each point, fitted to the points in so far (one line taller, as wide as the
257
268
  * widest), so it never stands sized for the whole list nor empty: its first point comes in with it. Chips add one
258
- * card at a time, each in its final place (`overlay.chips`), so the row is centred once complete and nothing already
259
- * shown moves. Every entry holds one box per drawn card.
269
+ * card at a time, and the chips shown so far are always a row of their own on the frame's axis (`chipAxis`, RV-185 of
270
+ * an adopting app), as close to it as the box allows, their sizes and gaps kept; the last step is the full row
271
+ * (`overlay.chips`) exactly. Every entry holds one box per drawn card.
260
272
  */
261
273
  export function getListCardsByItem(overlay) {
262
274
  if (overlay.chips !== undefined) {
263
275
  const chips = overlay.chips;
264
- return chips.map((_chip, index) => chips.slice(0, index + 1));
276
+ const first = chips[0].left;
277
+ const axis = overlay.chipAxis ?? (first + getChipRight(chips[chips.length - 1])) / 2;
278
+ const { box } = overlay;
279
+ return chips.map((chip, index) => {
280
+ if (index === chips.length - 1)
281
+ return chips;
282
+ const width = getChipRight(chip) - first;
283
+ const left = Math.round(Math.max(box.left, Math.min(box.left + box.width - width, axis - width / 2)));
284
+ return chips.slice(0, index + 1).map((shown) => ({ ...shown, left: shown.left - first + left }));
285
+ });
265
286
  }
266
287
  const lines = getSideTextLines(overlay);
267
288
  const padY = getOverlayPadding(overlay).y;
@@ -270,6 +291,19 @@ export function getListCardsByItem(overlay) {
270
291
  return [getSideTextCard(overlay, lines.slice(0, index + 1), height)];
271
292
  });
272
293
  }
294
+ /** A chip's right edge, in px of the frame. */
295
+ function getChipRight(chip) {
296
+ return chip.left + chip.width;
297
+ }
298
+ /**
299
+ * Which step of `getListCardsByItem` shows from each distinct second a list's points come in at (RV-185 of an adopting
300
+ * app): points on the same second come in together, so the step is the last of them. In time order, the first at the
301
+ * list's start.
302
+ */
303
+ export function getListStops(overlay) {
304
+ const times = getListItemTimes(overlay);
305
+ return times.flatMap((at, step) => (times[step + 1] === at ? [] : [{ at, step }]));
306
+ }
273
307
  /** The film seconds each point of a list comes in at: its own (`itemStarts`), the first with the card; else all with the card. */
274
308
  export function getListItemTimes(overlay) {
275
309
  return overlay.items.map((_item, index) => (index === 0 ? overlay.start : (overlay.itemStarts?.[index] ?? overlay.start)));
@@ -485,10 +519,12 @@ function getCentredSpan(place, margin) {
485
519
  * there either in the whole zone, as close to the axis as the zone allows. What fitted before still fits.
486
520
  */
487
521
  function measureCentred(input) {
488
- const wide = input.measure(input.whole);
489
- if (!wide.ok || input.getWidth(wide) <= input.centred)
522
+ const wide = input.measure(input.whole, false);
523
+ if (!wide.ok && input.isRetriedWhenRefused !== true)
524
+ return wide;
525
+ if (wide.ok && input.getWidth(wide) <= input.centred)
490
526
  return wide;
491
- const narrow = input.measure(input.centred);
527
+ const narrow = input.measure(input.centred, true);
492
528
  return narrow.ok ? narrow : wide;
493
529
  }
494
530
  /** The top of a box `height` tall at a named position of the text region. */
@@ -724,8 +760,10 @@ function placeSideText(overlay, drawn, place) {
724
760
  const chips = overlay.kind === "list" ? measureCentred({
725
761
  whole: room,
726
762
  centred: getCentredSpan(place, margin).width,
727
- measure: (width) => getListChipLayout({ items: overlay.items ?? [], layout: overlay.style?.list_layout ?? "stack", fontSize, padScale: place.padScale, room: width }),
763
+ measure: (width, isCentred) => getListChipLayout({ items: overlay.items ?? [], layout: overlay.style?.list_layout ?? "stack", fontSize, minFontSize: Math.round((isCentred ? LIST_CHIP_CENTRED_MIN_FONT_SIZE : LIST_CHIP_MIN_FONT_SIZE) * scale), padScale: place.padScale, room: width }),
728
764
  getWidth: (result) => result.row?.width ?? 0,
765
+ // A row refused in the whole zone may still fit the centred span a little smaller.
766
+ isRetriedWhenRefused: true,
729
767
  }) : null;
730
768
  if (chips !== null && !chips.ok)
731
769
  return chips;
@@ -745,7 +783,7 @@ function placeSideText(overlay, drawn, place) {
745
783
  const centred = { ...box, ...getCentredSpan(place, margin) };
746
784
  if (overlay.kind === "list") {
747
785
  const isCentred = row === null && overlay.style?.side === undefined;
748
- const layout = row !== null ? { chips: placeChipRow(row, { ...box, left: getCentredLeft(place, row.width, margin), width: row.width }) } : isCentred ? { isCentred: true } : {};
786
+ const layout = row !== null ? { chips: placeChipRow(row, { ...box, left: getCentredLeft(place, row.width, margin), width: row.width }), chipAxis: place.frame.width / 2 } : isCentred ? { isCentred: true } : {};
749
787
  // A row of chips may be drawn smaller than the list's size, to fit one row.
750
788
  return { ok: true, overlay: { ...drawn, kind: "list", items: overlay.items ?? [], fontSize: row?.fontSize ?? fontSize, side, box: isCentred ? centred : box, ...layout } };
751
789
  }
@@ -776,17 +814,23 @@ function measureChipRow(items, fontSize, padScale) {
776
814
  }
777
815
  /**
778
816
  * Whether a list draws as chips and their row (null: the stack), or why it cannot. A row wider than `room` is tried
779
- * smaller, as a title is (by `OVERLAY_TITLE_SHRINK`, at most `MAX_TITLE_SHRINKS` times); one that never fits is refused
780
- * on `chips`, and `auto` falls back to the stack at the list's own size. `stack` never draws chips.
817
+ * smaller, as a title is (by `OVERLAY_TITLE_SHRINK`, `MAX_TITLE_SHRINKS` times; an asked row of chips then on while its type
818
+ * stays at or above `minFontSize`); one that never fits is refused on `chips`, and `auto` falls back to the stack at the list's
819
+ * own size. `stack` never draws chips.
781
820
  */
782
821
  function getListChipLayout(input) {
783
822
  const { items, layout, room } = input;
784
823
  if (layout === "stack")
785
824
  return { ok: true, row: null };
786
825
  const own = measureChipRow(items, input.fontSize, input.padScale);
787
- for (let shrink = 0, row = own; shrink <= MAX_TITLE_SHRINKS; shrink++, row = measureChipRow(items, Math.round(row.fontSize * OVERLAY_TITLE_SHRINK), input.padScale)) {
826
+ for (let shrink = 0, row = own;; shrink++) {
788
827
  if (row.width <= room)
789
828
  return { ok: true, row };
829
+ const smaller = Math.round(row.fontSize * OVERLAY_TITLE_SHRINK);
830
+ // `auto` has the stack to fall back to, so only an asked row of chips shrinks past a title's three steps.
831
+ if (shrink >= MAX_TITLE_SHRINKS && (layout === "auto" || smaller < input.minFontSize))
832
+ break;
833
+ row = measureChipRow(items, smaller, input.padScale);
790
834
  }
791
835
  if (layout === "auto")
792
836
  return { ok: true, row: null };
@@ -859,9 +903,12 @@ export function wrapOverlayTitle(text, fontSize, width) {
859
903
  }
860
904
  return best;
861
905
  }
862
- /** A title's lines and font size: its own size, else smaller by `OVERLAY_TITLE_SHRINK` until it fits two lines; null when it never does. */
863
- function fitTitle(text, fontSize, room) {
864
- for (let shrink = 0, size = fontSize; shrink <= MAX_TITLE_SHRINKS; shrink++, size = Math.round(size * OVERLAY_TITLE_SHRINK)) {
906
+ /**
907
+ * A title's lines and font size: its own size, else smaller by `OVERLAY_TITLE_SHRINK` until it fits two lines, at most
908
+ * `maxShrinks` times; null when it never does.
909
+ */
910
+ function fitTitle(text, fontSize, room, maxShrinks = MAX_TITLE_SHRINKS) {
911
+ for (let shrink = 0, size = fontSize; shrink <= maxShrinks; shrink++, size = Math.round(size * OVERLAY_TITLE_SHRINK)) {
865
912
  const lines = wrapOverlayTitle(text, size, room);
866
913
  if (lines.length <= MAX_OVERLAY_TITLE_LINES && lines.every((line) => estimateTextWidth(line, size) <= room))
867
914
  return { lines, fontSize: size };
@@ -874,10 +921,44 @@ function fitTitle(text, fontSize, room) {
874
921
  * fitted then is refused now).
875
922
  */
876
923
  function getSubtitleSize(input) {
877
- const wanted = Math.max(Math.round(MIN_OVERLAY_SUBTITLE_PX * input.scale), Math.round(input.titleSize * OVERLAY_SUBTITLE_SCALES[input.step]));
924
+ const smallest = Math.round(MIN_OVERLAY_SUBTITLE_PX * input.scale);
925
+ const wanted = Math.max(smallest, Math.round(input.titleSize * OVERLAY_SUBTITLE_SCALES[input.step]));
878
926
  const fitting = Math.floor(input.room / ([...input.subtitle].length * OVERLAY_CHAR_EM));
879
- return Math.min(wanted, Math.max(fitting, Math.round(input.titleSize * OVERLAY_SUBTITLE_SCALES.s)));
927
+ // In the centred span a subtitle may go down to `MIN_OVERLAY_SUBTITLE_PX` too when the `s` step is above it.
928
+ const floor = Math.round(input.titleSize * OVERLAY_SUBTITLE_SCALES.s);
929
+ return Math.min(wanted, Math.max(fitting, input.isCentred === true ? Math.min(floor, smallest) : floor));
930
+ }
931
+ /**
932
+ * A place card's subtitle: one line at `getSubtitleSize` when it fits `room` (what fitted before keeps its size), else
933
+ * two balanced lines, each sized as one line would be; null when even two lines are too wide (RV-184 of an adopting
934
+ * app: a card whose subtitle cannot fit the centred span is placed off the frame's axis).
935
+ */
936
+ function fitPlaceSubtitle(input) {
937
+ const size = getSubtitleSize(input);
938
+ if (estimateTextWidth(input.subtitle, size) <= input.room)
939
+ return { lines: [input.subtitle], size };
940
+ const lines = splitInTwoLines(input.subtitle);
941
+ if (lines === null)
942
+ return null;
943
+ const longest = lines.reduce((widest, line) => ([...line].length > [...widest].length ? line : widest));
944
+ const lineSize = getSubtitleSize({ ...input, subtitle: longest });
945
+ return lines.every((line) => estimateTextWidth(line, lineSize) <= input.room) ? { lines, size: lineSize } : null;
880
946
  }
947
+ /** A text's two lines of words as even as they can be (the longer line as short as it can be); null for one word. */
948
+ function splitInTwoLines(text) {
949
+ const words = text.split(/\s+/).filter((part) => part.length > 0);
950
+ if (words.length < 2)
951
+ return null;
952
+ let best = [words[0], words.slice(1).join(" ")];
953
+ for (let split = 2; split < words.length; split++) {
954
+ const pair = [words.slice(0, split).join(" "), words.slice(split).join(" ")];
955
+ if (Math.max(...pair.map((line) => [...line].length)) < Math.max(...best.map((line) => [...line].length)))
956
+ best = pair;
957
+ }
958
+ return best;
959
+ }
960
+ /** A place card's title may shrink this many steps more in the centred span than in the whole zone (0.9² ≈ 0.81). */
961
+ const CENTRED_TITLE_EXTRA_SHRINKS = 2;
881
962
  /**
882
963
  * The text block of a hook title or a place card without its padding, in px: its widest line (the place label with
883
964
  * its pin, the subtitle, each title line) and its height. Its card is this plus the padding, so the draft and the
@@ -886,11 +967,14 @@ function getSubtitleSize(input) {
886
967
  export function getTitleContentSize(input) {
887
968
  const { kind, lines, fontSize, second, secondSize } = input;
888
969
  const isHook = kind === "hook_title";
889
- const secondWidth = second === null ? 0 : estimateTextWidth(second, secondSize) + (isHook ? Math.round(secondSize * 1.1) : 0);
970
+ const seconds = second === null ? [] : (input.secondLines ?? [second]);
971
+ const secondWidth = Math.max(0, ...seconds.map((line) => estimateTextWidth(line, secondSize) + (isHook ? Math.round(secondSize * 1.1) : 0)));
890
972
  const lineHeight = isHook ? OVERLAY_LINE_HEIGHT : OVERLAY_TITLE_LINE_HEIGHT;
973
+ // A wrapped subtitle's further lines each add a card line (`OVERLAY_LINE_HEIGHT`), as the render's `<br>` does.
974
+ const secondHeight = seconds.length === 0 ? 0 : secondSize * 1.3 + fontSize * 0.12 + (seconds.length - 1) * secondSize * OVERLAY_LINE_HEIGHT;
891
975
  return {
892
976
  width: Math.max(secondWidth, input.pin === true ? getPlaceCardPinSize(fontSize) : 0, ...lines.map((line) => estimateTextWidth(line, fontSize))),
893
- height: lines.length * fontSize * lineHeight + (second === null ? 0 : secondSize * 1.3 + fontSize * 0.12) + (input.pin === true ? getPlaceCardPinRow(fontSize) : 0),
977
+ height: lines.length * fontSize * lineHeight + secondHeight + (input.pin === true ? getPlaceCardPinRow(fontSize) : 0),
894
978
  };
895
979
  }
896
980
  /** A place card's pin height (and width), in px: half its title's size. */
@@ -905,26 +989,38 @@ export function getPlaceCardPinRow(fontSize) {
905
989
  export function getTitleContentBox(overlay) {
906
990
  const second = overlay.kind === "hook_title" ? overlay.place : overlay.subtitle;
907
991
  const secondSize = overlay.kind === "hook_title" ? overlay.placeFontSize : overlay.subtitleFontSize;
908
- const size = getTitleContentSize({ kind: overlay.kind, lines: overlay.lines, fontSize: overlay.fontSize, second, secondSize, pin: overlay.kind === "place_card" && overlay.pin !== undefined });
992
+ const isPlace = overlay.kind === "place_card";
993
+ const size = getTitleContentSize({
994
+ kind: overlay.kind,
995
+ lines: overlay.lines,
996
+ fontSize: overlay.fontSize,
997
+ second,
998
+ secondSize,
999
+ pin: isPlace && overlay.pin !== undefined,
1000
+ ...(isPlace && overlay.subtitleLines !== undefined ? { secondLines: overlay.subtitleLines } : {}),
1001
+ });
909
1002
  const { box } = overlay;
910
1003
  return { left: box.left + (box.width - size.width) / 2, top: box.top + (box.height - size.height) / 2, width: size.width, height: size.height };
911
1004
  }
912
1005
  /** A hook title's or a place card's lines and second line, aligned as its style says. */
913
- function measureTitle(overlay, metrics) {
1006
+ function measureTitle(overlay, metrics, isCentred = false) {
914
1007
  const { room, label } = metrics;
915
- const fitted = fitTitle(overlay.text ?? "", metrics.fontSize, room);
1008
+ const isHook = overlay.kind === "hook_title";
1009
+ // In the centred span a place card's title may shrink further, so a card that fitted the whole zone stays on the axis.
1010
+ const fitted = fitTitle(overlay.text ?? "", metrics.fontSize, room, MAX_TITLE_SHRINKS + (isCentred && !isHook ? CENTRED_TITLE_EXTRA_SHRINKS : 0));
916
1011
  if (fitted === null)
917
1012
  return { ok: false, error: `the ${label} takes more than ${MAX_OVERLAY_TITLE_LINES} lines even at a smaller size; shorten it or use a smaller size` };
918
1013
  const { lines, fontSize } = fitted;
919
- const isHook = overlay.kind === "hook_title";
920
1014
  const second = (isHook ? overlay.place : overlay.subtitle) ?? null;
921
- const secondSize = !isHook && second !== null
922
- ? getSubtitleSize({ subtitle: second, titleSize: metrics.fontSize, step: overlay.style?.subtitle_size ?? "m", room, scale: metrics.scale })
923
- : Math.round(metrics.fontSize * OVERLAY_SECONDARY_SCALE[overlay.kind]);
1015
+ const subtitle = !isHook && second !== null ? fitPlaceSubtitle({ subtitle: second, titleSize: metrics.fontSize, step: overlay.style?.subtitle_size ?? "m", room, scale: metrics.scale, isCentred }) : null;
1016
+ if (!isHook && second !== null && subtitle === null)
1017
+ return tooWide(metrics, "subtitle");
1018
+ const secondSize = subtitle?.size ?? Math.round(metrics.fontSize * OVERLAY_SECONDARY_SCALE[overlay.kind]);
1019
+ const subtitleLines = subtitle !== null && subtitle.lines.length > 1 ? subtitle.lines : undefined;
924
1020
  // The hook title's place label carries a pin about one label line wide before it.
925
- const secondWidth = second === null ? 0 : estimateTextWidth(second, secondSize) + (isHook ? Math.round(secondSize * 1.1) : 0);
1021
+ const secondWidth = second === null || !isHook ? 0 : estimateTextWidth(second, secondSize) + Math.round(secondSize * 1.1);
926
1022
  if (secondWidth > room)
927
- return tooWide(metrics, isHook ? "place label" : "subtitle");
1023
+ return tooWide(metrics, "place label");
928
1024
  // A title's align is center or left (the schema refuses right on it).
929
1025
  const align = overlay.style?.align === "left" ? "left" : "center";
930
1026
  const pin = !isHook && overlay.style?.pin !== undefined && overlay.style.pin !== "none" ? overlay.style.pin : undefined;
@@ -932,10 +1028,20 @@ function measureTitle(overlay, metrics) {
932
1028
  return {
933
1029
  ok: true,
934
1030
  content: {
935
- ...getTitleContentSize({ kind: overlay.kind, lines, fontSize, second, secondSize, pin: pin !== undefined }),
1031
+ ...getTitleContentSize({ kind: overlay.kind, lines, fontSize, second, secondSize, pin: pin !== undefined, ...(subtitleLines === undefined ? {} : { secondLines: subtitleLines }) }),
936
1032
  fields: isHook
937
1033
  ? { kind: "hook_title", lines, place: second, fontSize, placeFontSize: secondSize, align, ...(overlay.style?.backdrop === "highlight" ? { backdrop: "highlight" } : {}) }
938
- : { kind: "place_card", lines, subtitle: second, fontSize, subtitleFontSize: secondSize, align, ...(pin === undefined ? {} : { pin }), ...(delay === undefined ? {} : { subtitleDelay: delay }) },
1034
+ : {
1035
+ kind: "place_card",
1036
+ lines,
1037
+ subtitle: second,
1038
+ fontSize,
1039
+ subtitleFontSize: secondSize,
1040
+ align,
1041
+ ...(pin === undefined ? {} : { pin }),
1042
+ ...(delay === undefined ? {} : { subtitleDelay: delay }),
1043
+ ...(subtitleLines === undefined ? {} : { subtitleLines }),
1044
+ },
939
1045
  },
940
1046
  };
941
1047
  }
@@ -993,10 +1099,10 @@ function placeCard(overlay, drawn, place) {
993
1099
  const outer = frame.width - zone.left - zone.right - 2 * margin;
994
1100
  const fontSize = Math.round(OVERLAY_FONT_SIZES[overlay.kind][overlay.style?.size ?? "m"] * scale);
995
1101
  const pad = getOverlayPadding({ fontSize, padScale: place.padScale });
996
- const measure = (room) => {
1102
+ const measure = (room, isCentred = false) => {
997
1103
  const metrics = { fontSize, pad, room: room - 2 * pad.x, label: overlay.kind.replace("_", " "), scale };
998
1104
  return overlay.kind === "hook_title" || overlay.kind === "place_card"
999
- ? measureTitle({ ...overlay, kind: overlay.kind }, metrics)
1105
+ ? measureTitle({ ...overlay, kind: overlay.kind }, metrics, isCentred)
1000
1106
  : overlay.kind === "search_bar"
1001
1107
  ? measureSearchBar(overlay, metrics)
1002
1108
  : overlay.kind === "counter"
@@ -1006,7 +1112,13 @@ function placeCard(overlay, drawn, place) {
1006
1112
  // A date stamp sits on its side of the whole zone; every other card on the frame's axis.
1007
1113
  const measured = overlay.kind === "date_stamp"
1008
1114
  ? measure(outer)
1009
- : measureCentred({ whole: outer, centred: getCentredSpan(place, margin).width, measure, getWidth: (result) => Math.ceil(result.content.width + 2 * pad.x) });
1115
+ : measureCentred({
1116
+ whole: outer,
1117
+ centred: getCentredSpan(place, margin).width,
1118
+ measure,
1119
+ getWidth: (result) => Math.ceil(result.content.width + 2 * pad.x),
1120
+ isRetriedWhenRefused: overlay.kind === "place_card",
1121
+ });
1010
1122
  if (!measured.ok)
1011
1123
  return measured;
1012
1124
  const { content } = measured;