@softure-ai/marketing-kit 0.37.0 → 0.38.1

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.
@@ -89,6 +89,15 @@ export const OVERLAY_LINE_HEIGHT = 1.15;
89
89
  export const OVERLAY_LIST_LINE_HEIGHT = 1.4;
90
90
  /** The room between two chips of a list's row, in font sizes. */
91
91
  export const LIST_CHIP_GAP_EM = 0.3;
92
+ /** A chip's step badge before its point (a round accent mark with its number, a tick once the next point is in), in font sizes. */
93
+ export const LIST_CHIP_BADGE_EM = { size: 1.1, gap: 0.35 } as const;
94
+ /** How opaque a chip's point stays once the next point is in: it steps back, the newest point leads. */
95
+ export const LIST_CHIP_COVERED_OPACITY = 0.55;
96
+ /**
97
+ * 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
98
+ * shrinking down to it, so the step badges never turn a row that fitted without them into a refusal.
99
+ */
100
+ export const LIST_CHIP_MIN_FONT_SIZE = 36;
92
101
  /** A place card title's line height, tighter for its big type. */
93
102
  export const OVERLAY_TITLE_LINE_HEIGHT = 1.05;
94
103
  export const OVERLAY_PADDING_EM = { x: 0.6, y: 0.35 } as const;
@@ -235,7 +244,8 @@ export type ResolvedOverlay =
235
244
  /** Its lines as drawn (a strip's in capitals). */
236
245
  lines: string[];
237
246
  fontSize: number;
238
- side: OverlaySide;
247
+ /** Its side, or `center` on the frame's axis (the default). */
248
+ side: OverlaySide | "center";
239
249
  /** Its paper, unturned; it is drawn turned by `tilt` degrees about its middle. */
240
250
  box: OverlayBox;
241
251
  tilt: number;
@@ -537,7 +547,9 @@ export function resolveEdlOverlays(input: ResolveOverlaysInput): ResolvedOverlay
537
547
  problems.push(`${at}: ${placed.error}`);
538
548
  return;
539
549
  }
540
- if (placed.overlay.kind === "list" && (overlay.style?.stagger === true || overlay.item_words !== undefined || overlay.item_at !== undefined)) {
550
+ // Chips always come in one by one, as a countdown of the points (RV-181 of an adopting app); a stack only when asked.
551
+ const isStaggered = overlay.style?.stagger === true || overlay.item_words !== undefined || overlay.item_at !== undefined;
552
+ if (placed.overlay.kind === "list" && (isStaggered || placed.overlay.chips !== undefined)) {
541
553
  const said = (overlay.item_words ?? []).map((word, item) => findWordStart(word, input.words, `item_words[${item}]`));
542
554
  const missing = said.flatMap((word) => (word.ok ? [] : [word.error]));
543
555
  if (missing.length > 0) {
@@ -644,6 +656,37 @@ function isInsideZone(place: Placement, point: OverlayPoint): boolean {
644
656
  return point.x >= zone.left && point.x <= frame.width - zone.right && point.y >= zone.top && point.y <= frame.height - zone.bottom;
645
657
  }
646
658
 
659
+ /**
660
+ * The left edge of a box `width` wide centred on the frame's vertical axis, as the captions are: the platform safe
661
+ * zone's sides differ (60 px on the left, up to 150 px on the right), so the middle of the zone sits left of the
662
+ * frame's middle (RV-180 of an adopting app). A box no wider than `getCentredSpan` is exactly centred; a wider one
663
+ * (a note, whose room is a share of the whole zone) is pushed inwards only as far as the zone needs.
664
+ */
665
+ export function getCentredLeft(place: Pick<Placement, "zone" | "frame">, width: number, margin: number): number {
666
+ const { zone, frame } = place;
667
+ const lowest = zone.left + margin;
668
+ const highest = frame.width - zone.right - margin - width;
669
+ return Math.round(Math.max(lowest, Math.min(highest, (frame.width - width) / 2)));
670
+ }
671
+
672
+ /** The widest box centred on the frame's axis that stays inside the safe zone: the wider side taken on both edges. */
673
+ function getCentredSpan(place: Pick<Placement, "zone" | "frame">, margin: number): { left: number; width: number } {
674
+ const side = Math.max(place.zone.left, place.zone.right) + margin;
675
+ return { left: side, width: place.frame.width - 2 * side };
676
+ }
677
+
678
+ /**
679
+ * A centred overlay measured so it can sit on the frame's axis: in the whole zone's width as before when it is no
680
+ * wider than the centred span, else again in the centred span (smaller or on more lines), and only when it cannot fit
681
+ * there either in the whole zone, as close to the axis as the zone allows. What fitted before still fits.
682
+ */
683
+ function measureCentred<T extends { ok: true } | { ok: false; error: string }>(input: { whole: number; centred: number; measure: (room: number) => T; getWidth: (result: T & { ok: true }) => number }): T {
684
+ const wide = input.measure(input.whole);
685
+ if (!wide.ok || input.getWidth(wide as T & { ok: true }) <= input.centred) return wide;
686
+ const narrow = input.measure(input.centred);
687
+ return narrow.ok ? narrow : wide;
688
+ }
689
+
647
690
  /** The top of a box `height` tall at a named position of the text region. */
648
691
  function getPositionTop(region: { top: number; bottom: number }, position: OverlayPosition, height: number): number {
649
692
  if (position === "top") return region.top;
@@ -746,9 +789,10 @@ function placeNote(overlay: EdlOverlay, drawn: Drawn, place: Placement): Placed
746
789
  if (top < region.top || top + height > region.bottom) {
747
790
  return { ok: false, error: `the note (${height} px tall) does not fit between the platform safe zone and the captions; use a smaller size or shorter text` };
748
791
  }
749
- const side = overlay.style?.side ?? "left";
750
- const left = side === "right" ? frame.width - zone.right - margin - width : zone.left + margin;
751
- const tilt = (side === "right" ? -1 : 1) * NOTE_TILT[noteStyle];
792
+ // Without a side the note sits on the frame's axis, leaning half as much (RV-182 of an adopting app).
793
+ const side = overlay.style?.side ?? "center";
794
+ const left = side === "center" ? getCentredLeft(place, width, margin) : side === "right" ? frame.width - zone.right - margin - width : zone.left + margin;
795
+ const tilt = side === "center" ? NOTE_TILT[noteStyle] / 2 : (side === "right" ? -1 : 1) * NOTE_TILT[noteStyle];
752
796
  return {
753
797
  ok: true,
754
798
  overlay: { ...drawn, kind: "note", noteStyle, lines, fontSize, side, box: { left, top, width, height }, tilt, tear: getTornEdge(text), wordTimes: null, tick: isTick, tickAt: null },
@@ -799,18 +843,28 @@ function placeEndWord(overlay: EdlOverlay, drawn: Drawn, place: Placement): Plac
799
843
  const { zone, frame } = place;
800
844
  const scale = frame.width / 1080;
801
845
  const margin = Math.round(OVERLAY_MARGIN * scale);
802
- const room = frame.width - zone.left - zone.right - 2 * margin;
803
846
  const text = (overlay.text ?? "").replace(/\s+/g, " ").trim();
804
- let fontSize = Math.round(OVERLAY_FONT_SIZES.end_word[overlay.style?.size ?? "m"] * scale);
805
- for (let shrink = 0; measureHandText(text, fontSize) > room; shrink++) {
806
- if (shrink === MAX_TITLE_SHRINKS) return { ok: false, error: "the end word is too wide for one line even at a smaller size; shorten it or use a smaller size" };
807
- fontSize = Math.round(fontSize * OVERLAY_TITLE_SHRINK);
808
- }
847
+ const own = Math.round(OVERLAY_FONT_SIZES.end_word[overlay.style?.size ?? "m"] * scale);
848
+ const fitted = measureCentred({
849
+ whole: frame.width - zone.left - zone.right - 2 * margin,
850
+ centred: getCentredSpan(place, margin).width,
851
+ measure: (room: number): { ok: true; fontSize: number } | { ok: false; error: string } => {
852
+ let fontSize = own;
853
+ for (let shrink = 0; measureHandText(text, fontSize) > room; shrink++) {
854
+ if (shrink === MAX_TITLE_SHRINKS) return { ok: false, error: "the end word is too wide for one line even at a smaller size; shorten it or use a smaller size" };
855
+ fontSize = Math.round(fontSize * OVERLAY_TITLE_SHRINK);
856
+ }
857
+ return { ok: true, fontSize };
858
+ },
859
+ getWidth: (result) => measureHandText(text, result.fontSize),
860
+ });
861
+ if (!fitted.ok) return fitted;
862
+ const { fontSize } = fitted;
809
863
  const width = measureHandText(text, fontSize);
810
864
  const height = Math.ceil(fontSize * OVERLAY_LINE_HEIGHT);
811
865
  const region = getTextRegion(place);
812
866
  if (region.top + height > region.bottom) return { ok: false, error: `the end word (${height} px tall) does not fit above the captions; use a smaller size` };
813
- const left = Math.round(zone.left + margin + (room - width) / 2);
867
+ const left = getCentredLeft(place, width, margin);
814
868
  return { ok: true, overlay: { ...drawn, kind: "end_word", text, fontSize, box: { left, top: region.top, width, height } } };
815
869
  }
816
870
 
@@ -851,7 +905,12 @@ function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" |
851
905
  const pad = getOverlayPadding({ fontSize, padScale: place.padScale });
852
906
  const margin = Math.round(OVERLAY_MARGIN * scale);
853
907
  const room = frame.width - zone.left - zone.right - 2 * margin;
854
- const chips = overlay.kind === "list" ? getListChipLayout({ items: overlay.items ?? [], layout: overlay.style?.list_layout ?? "stack", fontSize, padScale: place.padScale, room }) : null;
908
+ const chips = overlay.kind === "list" ? measureCentred({
909
+ whole: room,
910
+ centred: getCentredSpan(place, margin).width,
911
+ measure: (width: number) => getListChipLayout({ items: overlay.items ?? [], layout: overlay.style?.list_layout ?? "stack", fontSize, minFontSize: Math.round(LIST_CHIP_MIN_FONT_SIZE * scale), padScale: place.padScale, room: width }),
912
+ getWidth: (result) => result.row?.width ?? 0,
913
+ }) : null;
855
914
  if (chips !== null && !chips.ok) return chips;
856
915
  const row = chips?.row ?? null;
857
916
  const lines = overlay.kind === "list" ? (overlay.items ?? []).length : 1;
@@ -865,12 +924,15 @@ function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" |
865
924
  return { ok: false, error: `the ${overlay.kind.replace("_", " ")} (${height} px tall) does not fit between the platform safe zone and the captions; use a smaller size or fewer points` };
866
925
  }
867
926
  const box = { left: zone.left + margin, top, width: room, height };
927
+ // A centred card (a stack without a side, a keyword aligned center) sits in a box centred on the frame's axis.
928
+ const centred = { ...box, ...getCentredSpan(place, margin) };
868
929
  if (overlay.kind === "list") {
869
- const layout = row === null ? (overlay.style?.side === undefined ? { isCentred: true } : {}) : { chips: placeChipRow(row, box) };
930
+ const isCentred = row === null && overlay.style?.side === undefined;
931
+ const layout = row !== null ? { chips: placeChipRow(row, { ...box, left: getCentredLeft(place, row.width, margin), width: row.width }) } : isCentred ? { isCentred: true } : {};
870
932
  // A row of chips may be drawn smaller than the list's size, to fit one row.
871
- return { ok: true, overlay: { ...drawn, kind: "list", items: overlay.items ?? [], fontSize: row?.fontSize ?? fontSize, side, box, ...layout } };
933
+ return { ok: true, overlay: { ...drawn, kind: "list", items: overlay.items ?? [], fontSize: row?.fontSize ?? fontSize, side, box: isCentred ? centred : box, ...layout } };
872
934
  }
873
- const fields = { text: overlay.text ?? "", fontSize, side, box };
935
+ const fields = { text: overlay.text ?? "", fontSize, side, box: align === "center" ? centred : box };
874
936
  if (overlay.kind === "lower_third") return { ok: true, overlay: { ...drawn, kind: "lower_third", ...fields } };
875
937
  return {
876
938
  ok: true,
@@ -897,7 +959,9 @@ interface ChipRow {
897
959
  /** A row of chips at one type size. */
898
960
  function measureChipRow(items: readonly string[], fontSize: number, padScale: number): ChipRow {
899
961
  const pad = getOverlayPadding({ fontSize, padScale });
900
- const widths = items.map((item) => Math.ceil(estimateTextWidth(item, fontSize) + 2 * pad.x));
962
+ const badge = getChipBadgeSize(fontSize);
963
+ // The badge sits as far from the chip's left edge as from its top, so the left takes the vertical padding.
964
+ const widths = items.map((item) => Math.ceil(estimateTextWidth(item, fontSize) + pad.y + pad.x + badge.size + badge.gap));
901
965
  const gap = Math.round(fontSize * LIST_CHIP_GAP_EM);
902
966
  const width = widths.reduce((sum, chip) => sum + chip, 0) + gap * Math.max(0, widths.length - 1);
903
967
  return { fontSize, widths, height: Math.ceil(fontSize * OVERLAY_LINE_HEIGHT + 2 * pad.y), gap, width };
@@ -905,20 +969,65 @@ function measureChipRow(items: readonly string[], fontSize: number, padScale: nu
905
969
 
906
970
  /**
907
971
  * Whether a list draws as chips and their row (null: the stack), or why it cannot. A row wider than `room` is tried
908
- * smaller, as a title is (by `OVERLAY_TITLE_SHRINK`, at most `MAX_TITLE_SHRINKS` times); one that never fits is refused
909
- * on `chips`, and `auto` falls back to the stack at the list's own size. `stack` never draws chips.
972
+ * smaller, as a title is (by `OVERLAY_TITLE_SHRINK`, `MAX_TITLE_SHRINKS` times; an asked row of chips then on while its type
973
+ * stays at or above `minFontSize`); one that never fits is refused on `chips`, and `auto` falls back to the stack at the list's
974
+ * own size. `stack` never draws chips.
910
975
  */
911
- function getListChipLayout(input: { items: readonly string[]; layout: OverlayListLayout; fontSize: number; padScale: number; room: number }): { ok: true; row: ChipRow | null } | { ok: false; error: string } {
976
+ function getListChipLayout(input: { items: readonly string[]; layout: OverlayListLayout; fontSize: number; minFontSize: number; padScale: number; room: number }): { ok: true; row: ChipRow | null } | { ok: false; error: string } {
912
977
  const { items, layout, room } = input;
913
978
  if (layout === "stack") return { ok: true, row: null };
914
979
  const own = measureChipRow(items, input.fontSize, input.padScale);
915
- for (let shrink = 0, row = own; shrink <= MAX_TITLE_SHRINKS; shrink++, row = measureChipRow(items, Math.round(row.fontSize * OVERLAY_TITLE_SHRINK), input.padScale)) {
980
+ for (let shrink = 0, row = own; ; shrink++) {
916
981
  if (row.width <= room) return { ok: true, row };
982
+ const smaller = Math.round(row.fontSize * OVERLAY_TITLE_SHRINK);
983
+ // `auto` has the stack to fall back to, so only an asked row of chips shrinks past a title's three steps.
984
+ if (shrink >= MAX_TITLE_SHRINKS && (layout === "auto" || smaller < input.minFontSize)) break;
985
+ row = measureChipRow(items, smaller, input.padScale);
917
986
  }
918
987
  if (layout === "auto") return { ok: true, row: null };
919
988
  return { ok: false, error: `the list's points as chips (${own.width} px) do not fit one row (${room} px) even at a smaller size; use list_layout stack or auto, or shorter points` };
920
989
  }
921
990
 
991
+ /** A chip's step badge: its diameter and the room after it, in px. */
992
+ export function getChipBadgeSize(fontSize: number): { size: number; gap: number } {
993
+ return { size: Math.round(fontSize * LIST_CHIP_BADGE_EM.size), gap: Math.round(fontSize * LIST_CHIP_BADGE_EM.gap) };
994
+ }
995
+
996
+ /**
997
+ * A chip's parts (RV-181 of an adopting app): its step badge, a round mark on the chip's left, and the centre its point
998
+ * is written about, in the room after the badge.
999
+ */
1000
+ export function getChipParts(chip: OverlayBox, overlay: { fontSize: number; padScale?: number }): { badge: { centre: OverlayPoint; radius: number }; textX: number } {
1001
+ const pad = getOverlayPadding(overlay);
1002
+ const badge = getChipBadgeSize(overlay.fontSize);
1003
+ const radius = badge.size / 2;
1004
+ const textLeft = chip.left + pad.y + badge.size + badge.gap;
1005
+ return { badge: { centre: { x: chip.left + pad.y + radius, y: chip.top + chip.height / 2 }, radius }, textX: r1(textLeft + (chip.left + chip.width - pad.x - textLeft) / 2) };
1006
+ }
1007
+
1008
+ /** The three points of the tick that takes a covered chip's number's place, inside its badge. */
1009
+ export function getChipTickPoints(badge: { centre: OverlayPoint; radius: number }): OverlayPoint[] {
1010
+ const { centre, radius } = badge;
1011
+ return [
1012
+ { x: r1(centre.x - 0.42 * radius), y: r1(centre.y + 0.02 * radius) },
1013
+ { x: r1(centre.x - 0.1 * radius), y: r1(centre.y + 0.32 * radius) },
1014
+ { x: r1(centre.x + 0.44 * radius), y: r1(centre.y - 0.3 * radius) },
1015
+ ];
1016
+ }
1017
+
1018
+ /**
1019
+ * When each chip of a row is covered: the second the next point comes in, after which the chip steps back (its point
1020
+ * fainter, its number a tick) and the newest point leads, as a countdown does; null for the last chip, and for one
1021
+ * whose next point comes in with it or after the list has gone.
1022
+ */
1023
+ export function getChipCoveredTimes(overlay: Extract<ResolvedOverlay, { kind: "list" }>): (number | null)[] {
1024
+ const times = getListItemTimes(overlay);
1025
+ return times.map((at, index) => {
1026
+ const next = times[index + 1];
1027
+ return next !== undefined && next > at && next < overlay.end ? next : null;
1028
+ });
1029
+ }
1030
+
922
1031
  /** The chips of a row in their final places: centred in `box`, left to right in the points' order. */
923
1032
  function placeChipRow(row: ChipRow, box: OverlayBox): OverlayBox[] {
924
1033
  let left = box.left + Math.round((box.width - row.width) / 2);
@@ -1118,15 +1227,21 @@ function placeCard(overlay: EdlOverlay & { kind: CardKind }, drawn: Drawn, place
1118
1227
  const outer = frame.width - zone.left - zone.right - 2 * margin;
1119
1228
  const fontSize = Math.round(OVERLAY_FONT_SIZES[overlay.kind][overlay.style?.size ?? "m"] * scale);
1120
1229
  const pad = getOverlayPadding({ fontSize, padScale: place.padScale });
1121
- const metrics = { fontSize, pad, room: outer - 2 * pad.x, label: overlay.kind.replace("_", " "), scale };
1122
- const measured =
1123
- overlay.kind === "hook_title" || overlay.kind === "place_card"
1230
+ const measure = (room: number): CardResult => {
1231
+ const metrics = { fontSize, pad, room: room - 2 * pad.x, label: overlay.kind.replace("_", " "), scale };
1232
+ return overlay.kind === "hook_title" || overlay.kind === "place_card"
1124
1233
  ? measureTitle({ ...overlay, kind: overlay.kind }, metrics)
1125
1234
  : overlay.kind === "search_bar"
1126
1235
  ? measureSearchBar(overlay, metrics)
1127
1236
  : overlay.kind === "counter"
1128
1237
  ? measureCounter(overlay, metrics)
1129
1238
  : measureDateStamp(overlay, metrics);
1239
+ };
1240
+ // A date stamp sits on its side of the whole zone; every other card on the frame's axis.
1241
+ const measured =
1242
+ overlay.kind === "date_stamp"
1243
+ ? measure(outer)
1244
+ : measureCentred({ whole: outer, centred: getCentredSpan(place, margin).width, measure, getWidth: (result) => Math.ceil(result.content.width + 2 * pad.x) });
1130
1245
  if (!measured.ok) return measured;
1131
1246
  const { content } = measured;
1132
1247
  const width = Math.ceil(content.width + 2 * pad.x);
@@ -1134,10 +1249,10 @@ function placeCard(overlay: EdlOverlay & { kind: CardKind }, drawn: Drawn, place
1134
1249
  const region = getTextRegion(place);
1135
1250
  const top = getPositionTop(region, overlay.style?.position ?? CARD_POSITIONS[overlay.kind], height);
1136
1251
  if (top < region.top || top + height > region.bottom) {
1137
- return { ok: false, error: `the ${metrics.label} (${height} px tall) does not fit between the platform safe zone and the captions; use a smaller size or shorter text` };
1252
+ return { ok: false, error: `the ${overlay.kind.replace("_", " ")} (${height} px tall) does not fit between the platform safe zone and the captions; use a smaller size or shorter text` };
1138
1253
  }
1139
1254
  const left =
1140
- overlay.kind !== "date_stamp" ? Math.round(zone.left + margin + (outer - width) / 2) : content.fields.side === "right" ? frame.width - zone.right - margin - width : zone.left + margin;
1255
+ overlay.kind !== "date_stamp" ? getCentredLeft(place, width, margin) : content.fields.side === "right" ? frame.width - zone.right - margin - width : zone.left + margin;
1141
1256
  return { ok: true, overlay: { ...drawn, ...content.fields, box: { left, top, width, height } } as ResolvedOverlay };
1142
1257
  }
1143
1258
 
package/src/index.ts CHANGED
@@ -169,6 +169,14 @@ export {
169
169
  findShotBreak,
170
170
  formatOverlayNumber,
171
171
  LIST_CHIP_GAP_EM,
172
+ LIST_CHIP_BADGE_EM,
173
+ LIST_CHIP_COVERED_OPACITY,
174
+ LIST_CHIP_MIN_FONT_SIZE,
175
+ getCentredLeft,
176
+ getChipBadgeSize,
177
+ getChipCoveredTimes,
178
+ getChipParts,
179
+ getChipTickPoints,
172
180
  getDrawnOverlayCard,
173
181
  getListCardsByItem,
174
182
  getListItemTimes,