@softure-ai/marketing-kit 0.32.0 → 0.33.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.
@@ -24,7 +24,10 @@ import {
24
24
  getOverlayPadding,
25
25
  getPlaceCardPinRow,
26
26
  getPlaceCardPinSize,
27
+ getListCardsByItem,
28
+ getListItemTimes,
27
29
  getTitleContentBox,
30
+ type OverlayBox,
28
31
  type ResolvedOverlay,
29
32
  } from "./overlays.js";
30
33
 
@@ -90,6 +93,13 @@ function getOverlayCss(colors: OverlayColors, fonts: { heading: string; interfac
90
93
  `.ov-dot{flex:none;width:.36em;height:.36em;border-radius:50%;background:${colors.accent}}`,
91
94
  `.ov-list .ov-card{flex-direction:column;align-items:flex-start;gap:0;line-height:${OVERLAY_LIST_LINE_HEIGHT};font-weight:650}`,
92
95
  `.ov-list li{display:flex;align-items:center;gap:.45em;list-style:none}`,
96
+ // A list's card grows with its points (RV-144 of an adopting app): sized per point, the later points clipped until
97
+ // they come in; a centred stack centres its lines, and chips are cards of their own, one per point.
98
+ `.ov-list .ov-card.grow{box-sizing:border-box;overflow:hidden;flex:none}`,
99
+ `.ov-list .ov-card.cen{align-items:center;text-align:center}`,
100
+ `.ov-list li{white-space:nowrap}`,
101
+ `.ov.center .ov-card{transform-origin:50% 100%}`,
102
+ `.ov-list .ov-chip{position:absolute;box-sizing:border-box;flex-direction:row;align-items:center;justify-content:center;white-space:nowrap;line-height:${OVERLAY_LINE_HEIGHT};transform-origin:50% 100%}`,
93
103
  `.ov-svg{position:absolute;inset:0;width:100%;height:100%;overflow:visible}`,
94
104
  `.ov-search,.ov-counter .ov-card,.ov-date .ov-card,.ov-place,.ov-sub,.ov-line{white-space:nowrap}`,
95
105
  // A title card fills its fitted box, so a typed title keeps its width; a centred typed line hides its untyped
@@ -118,7 +128,7 @@ function getOverlayCss(colors: OverlayColors, fonts: { heading: string; interfac
118
128
  `.ov-ul{position:absolute;height:${UNDERLINE_EM.height}em;border-radius:${UNDERLINE_EM.height / 2}em;background:${colors.accent};transform:scaleX(0);transform-origin:0% 50%}`,
119
129
  `.ov-pinrow{display:flex;justify-content:center}`,
120
130
  `.ov-stack.left .ov-pinrow{justify-content:flex-start}`,
121
- `.st li,.pd .ov-pinrow svg,.pl .ov-line,.sd .ov-sub{opacity:0}`,
131
+ `.pd .ov-pinrow svg,.pl .ov-line,.sd .ov-sub{opacity:0}`,
122
132
  // An underlined keyword keeps only its drawn bar: the card's own accent edge would be a second line under it.
123
133
  `.ov-keyword.ul .ov-card{border-bottom-color:transparent}`,
124
134
  // The brand's style (after the kinds' own rules, so it wins over them; the search bar stays a pill).
@@ -252,26 +262,22 @@ interface MarkupContext {
252
262
  frame: { width: number; height: number };
253
263
  }
254
264
 
255
- /** A keyword, a lower third or a list, entering as the soft pill (or by its own entrance). */
256
- function addSideText(overlay: Extract<ResolvedOverlay, { kind: "keyword" | "lower_third" | "list" }>, id: string, context: MarkupContext, out: OverlayMarkup): void {
265
+ /** A keyword or a lower third, entering as the soft pill (or by its own entrance). */
266
+ function addSideText(overlay: Extract<ResolvedOverlay, { kind: "keyword" | "lower_third" }>, id: string, context: MarkupContext, out: OverlayMarkup): void {
257
267
  const { box, fontSize, side } = overlay;
258
268
  const colors = getOverlayColors(overlay, context.colors);
259
269
  const cardStyle = getCardStyle(overlay, colors, context.scale);
260
270
  const dotStyle = overlay.colors.accent === undefined ? "" : ` style="background:${colors.accent}"`;
261
- const isTyped = overlay.typing !== null && overlay.kind !== "list";
271
+ const isTyped = overlay.typing !== null;
262
272
  const style = `left:${box.left}px;top:${box.top}px;width:${box.width}px;height:${box.height}px;font-size:${fontSize}px;align-items:${overlay.kind === "lower_third" ? "flex-end" : "flex-start"}`;
263
- const text = overlay.kind === "list" ? "" : isTyped ? toTypedHtml(overlay.text) : escapeHtml(overlay.text);
273
+ const text = isTyped ? toTypedHtml(overlay.text) : escapeHtml(overlay.text);
264
274
  const wipe = overlay.entrance === "wipe" ? `<i class="ov-wipe" id="${id}w"></i>` : "";
265
275
  const underline = overlay.kind === "keyword" && overlay.underline === true ? `<i class="ov-ul" id="${id}u" style="${getUnderlineStyle(overlay)}"></i>` : "";
266
- const staggered = overlay.kind === "list" ? overlay.itemStarts : undefined;
267
- const body =
268
- overlay.kind === "list"
269
- ? `<ul class="ov-card"${cardStyle}>${wipe}${overlay.items.map((item, i) => `<li id="${id}i${i}"><i class="ov-dot"${dotStyle}></i>${escapeHtml(item)}</li>`).join("")}</ul>`
270
- : `<div class="ov-card"${cardStyle}>${wipe}${overlay.kind === "lower_third" ? `<i class="ov-dot" id="${id}d"${dotStyle}></i>` : ""}<span id="${id}t">${text}</span>${underline}</div>`;
271
- out.html.push(clipDiv(overlay, id, `ov ov-${overlay.kind.replace("_", "-")}${side === "right" ? " right" : ""}${isTyped ? " ty" : ""}${staggered === undefined ? "" : " st"}${underline === "" ? "" : " ul"}`, style, body));
276
+ const body = `<div class="ov-card"${cardStyle}>${wipe}${overlay.kind === "lower_third" ? `<i class="ov-dot" id="${id}d"${dotStyle}></i>` : ""}<span id="${id}t">${text}</span>${underline}</div>`;
277
+ out.html.push(clipDiv(overlay, id, `ov ov-${overlay.kind.replace("_", "-")}${side === "right" ? " right" : ""}${isTyped ? " ty" : ""}${underline === "" ? "" : " ul"}`, style, body));
272
278
  if (overlay.entrance !== null) {
273
279
  out.tweens.push(...getMotionTweens(`#${id} .ov-card`, getEntranceMotion(overlay.entrance, overlay.easing ?? "smooth", context.frame), overlay.start));
274
- if (overlay.kind !== "list") out.tweens.push(...getTypingTweens(id, overlay, [...overlay.text].length));
280
+ out.tweens.push(...getTypingTweens(id, overlay, [...overlay.text].length));
275
281
  } else {
276
282
  // The soft pill's entrance: the card rises from its foot, then its dot and its text settle in, eased out without
277
283
  // overshoot (RV-133 of an adopting app: nothing grows past its size).
@@ -280,16 +286,7 @@ function addSideText(overlay: Extract<ResolvedOverlay, { kind: "keyword" | "lowe
280
286
  out.tweens.push(`tl.fromTo("#${id}d", { scale: 0 }, { scale: 1, duration: 0.35, ease: "power2.out", immediateRender: false }, ${r3(overlay.start + 0.25)});`);
281
287
  out.tweens.push(`tl.fromTo("#${id}t", { opacity: 0, x: -10 }, { opacity: 1, x: 0, duration: 0.4, ease: "power3.out", immediateRender: false }, ${r3(overlay.start + 0.3)});`);
282
288
  }
283
- if (overlay.kind === "list" && staggered === undefined) {
284
- overlay.items.forEach((_item, i) => {
285
- out.tweens.push(`tl.fromTo("#${id}i${i}", { opacity: 0, y: 14 }, { opacity: 1, y: 0, duration: 0.35, ease: "power3.out", immediateRender: false }, ${r3(overlay.start + 0.2 + 0.12 * i)});`);
286
- });
287
- }
288
289
  }
289
- // A staggered list's points come in one by one, each on its own second (`itemStarts`).
290
- staggered?.forEach((at, i) => {
291
- out.tweens.push(`tl.fromTo("#${id}i${i}", { opacity: 0, y: ${r3(14 * context.scale)} }, { opacity: 1, y: 0, duration: 0.35, ease: "power3.out", immediateRender: false }, ${at});`);
292
- });
293
290
  if (underline !== "") {
294
291
  out.tweens.push(`tl.fromTo("#${id}u", { scaleX: 0 }, { scaleX: 1, duration: ${UNDERLINE_SECONDS}, ease: "power2.out", immediateRender: false }, ${r3(overlay.start + getEntranceSeconds(overlay.entrance, overlay, context.frame))});`);
295
292
  }
@@ -298,6 +295,68 @@ function addSideText(overlay: Extract<ResolvedOverlay, { kind: "keyword" | "lowe
298
295
  );
299
296
  }
300
297
 
298
+ /** The seconds a list's card takes to grow to its next point, and a point to come in. */
299
+ const LIST_GROW_SECONDS = 0.35;
300
+
301
+ /** A card's entrance at `start`: its named entrance, else the soft pill rising from its foot (eased out, no overshoot). */
302
+ function getListCardEntrance(overlay: Extract<ResolvedOverlay, { kind: "list" }>, target: string, start: number, context: MarkupContext): string[] {
303
+ if (overlay.entrance !== null) return getMotionTweens(target, getEntranceMotion(overlay.entrance, overlay.easing ?? "smooth", context.frame), start);
304
+ return [`tl.fromTo("${target}", { scale: 0.88, y: ${r3(18 * context.scale)}, opacity: 0 }, { scale: 1, y: 0, opacity: 1, duration: 0.45, ease: "power3.out", immediateRender: false }, ${start});`];
305
+ }
306
+
307
+ /** A card's size and padding as inline CSS, in px. */
308
+ function getListCardSize(card: OverlayBox, pad: { x: number; y: number }): string {
309
+ return `width:${card.width}px;height:${card.height}px;padding:${pad.y}px ${pad.x}px`;
310
+ }
311
+
312
+ /**
313
+ * A list (RV-144 of an adopting app): a stack, one card whose first point comes in with it and which grows to each next
314
+ * point as it comes in (eased out, no overshoot; centred lines in the frame's middle without a side), or chips, one card
315
+ * per point in its final place of a centred row, each entering on its own second from the left. Every card leaves
316
+ * together.
317
+ */
318
+ function addList(overlay: Extract<ResolvedOverlay, { kind: "list" }>, id: string, context: MarkupContext, out: OverlayMarkup): void {
319
+ const { box, fontSize } = overlay;
320
+ const colors = getOverlayColors(overlay, context.colors);
321
+ const own = getCardStyle(overlay, colors, context.scale).replace(/^ style="|"$/g, "");
322
+ const pad = getOverlayPadding(overlay);
323
+ const times = getListItemTimes(overlay);
324
+ const cards = getListCardsByItem(overlay);
325
+ const wipe = (suffix: string) => (overlay.entrance === "wipe" ? `<i class="ov-wipe" id="${id}w${suffix}"></i>` : "");
326
+ const style = `left:${box.left}px;top:${box.top}px;width:${box.width}px;height:${box.height}px;font-size:${fontSize}px;align-items:flex-start`;
327
+ if (overlay.chips !== undefined) {
328
+ const chips = overlay.chips.map((chip, i) => {
329
+ const place = `left:${chip.left - box.left}px;top:${chip.top - box.top}px;${getListCardSize(chip, pad)}${i === 0 ? "" : ";visibility:hidden"}${own === "" ? "" : `;${own}`}`;
330
+ return `<div class="ov-card ov-chip" id="${id}c${i}" style="${place}">${wipe(String(i))}<span>${escapeHtml(overlay.items[i] as string)}</span></div>`;
331
+ });
332
+ out.html.push(clipDiv(overlay, id, "ov ov-list chips", style, chips.join("")));
333
+ times.forEach((at, i) => {
334
+ if (i > 0) out.tweens.push(`tl.set("#${id}c${i}", { visibility: "visible" }, ${at});`);
335
+ out.tweens.push(...getListCardEntrance(overlay, `#${id}c${i}`, at, context));
336
+ });
337
+ } else {
338
+ const isCentred = overlay.isCentred === true;
339
+ const dotStyle = overlay.colors.accent === undefined ? "" : ` style="background:${colors.accent}"`;
340
+ const first = times.filter((at) => at <= overlay.start).length - 1;
341
+ const card = (cards[first] as OverlayBox[])[0] as OverlayBox;
342
+ const items = overlay.items.map((item, i) => `<li id="${id}i${i}"${i > first ? ` style="opacity:0"` : ""}>${isCentred ? "" : `<i class="ov-dot"${dotStyle}></i>`}${escapeHtml(item)}</li>`);
343
+ const cardStyle = `${getListCardSize(card, pad)}${own === "" ? "" : `;${own}`}`;
344
+ const side = isCentred ? " center" : overlay.side === "right" ? " right" : "";
345
+ out.html.push(clipDiv(overlay, id, `ov ov-list${side}`, style, `<ul class="ov-card grow${isCentred ? " cen" : ""}" style="${cardStyle}">${wipe("")}${items.join("")}</ul>`));
346
+ out.tweens.push(...getListCardEntrance(overlay, `#${id} .ov-card`, overlay.start, context));
347
+ // Each later point: the card eases to its new size as the point fades up into it.
348
+ times.forEach((at, i) => {
349
+ if (i <= first) return;
350
+ const next = (cards[i] as OverlayBox[])[0] as OverlayBox;
351
+ out.tweens.push(`tl.to("#${id} .ov-card", { width: ${next.width}, height: ${next.height}, duration: ${LIST_GROW_SECONDS}, ease: "power3.out" }, ${at});`);
352
+ out.tweens.push(`tl.fromTo("#${id}i${i}", { opacity: 0, y: ${r3(14 * context.scale)} }, { opacity: 1, y: 0, duration: ${LIST_GROW_SECONDS}, ease: "power3.out", immediateRender: false }, ${at});`);
353
+ });
354
+ }
355
+ out.tweens.push(
356
+ ...getExitTweens(`#${id} .ov-card`, overlay, context.frame, `tl.to("#${id} .ov-card", { scale: 0.94, y: 14, opacity: 0, duration: ${EXIT_SECONDS}, ease: "power2.in" }, ${r3(overlay.end - EXIT_SECONDS)});`),
357
+ );
358
+ }
359
+
301
360
  /** Where a keyword's underline sits in its card: under the text, inside the card's padding. */
302
361
  function getUnderlineStyle(overlay: Extract<ResolvedOverlay, { kind: "keyword" }>): string {
303
362
  const pad = overlay.padScale ?? 1;
@@ -454,7 +513,8 @@ export function getOverlayMarkup(
454
513
  const out: OverlayMarkup = { html: [], css: getOverlayCss(input.colors, { heading: input.headingFont, interface: input.interfaceFont ?? "inherit" }, input.style, context.scale), tweens: [] };
455
514
  for (const overlay of drawn) {
456
515
  const id = `ov${overlay.index}`;
457
- if (overlay.kind === "keyword" || overlay.kind === "lower_third" || overlay.kind === "list") addSideText(overlay, id, context, out);
516
+ if (overlay.kind === "list") addList(overlay, id, context, out);
517
+ else if (overlay.kind === "keyword" || overlay.kind === "lower_third") addSideText(overlay, id, context, out);
458
518
  else if (overlay.kind === "arrow" || overlay.kind === "highlight") addMark(overlay, id, context, out);
459
519
  else addCard(overlay, id, context, out);
460
520
  }
@@ -74,6 +74,15 @@ export const OVERLAY_PINS = ["none", "static", "drop"] as const;
74
74
 
75
75
  export type OverlayPin = (typeof OVERLAY_PINS)[number];
76
76
 
77
+ /**
78
+ * How a list draws its points: `stack` (one centred card, its points one under another, the card growing as each one
79
+ * comes in), `chips` (each point its own small card, side by side in one centred row, entering in turn from the left)
80
+ * or `auto` (chips when every point fits one row at the list's size, else the stack). Without it: `stack`.
81
+ */
82
+ export const OVERLAY_LIST_LAYOUTS = ["stack", "chips", "auto"] as const;
83
+
84
+ export type OverlayListLayout = (typeof OVERLAY_LIST_LAYOUTS)[number];
85
+
77
86
  /** The longest a place card's subtitle waits after its title, in seconds. */
78
87
  export const MAX_OVERLAY_SUBTITLE_DELAY = 0.6;
79
88
 
@@ -152,6 +161,8 @@ export interface EdlOverlayStyle {
152
161
  easing?: OverlayEasing;
153
162
  /** A list's points come in one by one (on their `item_words` when given, else spaced automatically). */
154
163
  stagger?: boolean;
164
+ /** How a list draws its points (`stack` without it). */
165
+ list_layout?: OverlayListLayout;
155
166
  /** Seconds a place card's subtitle waits after its title (0 to `MAX_OVERLAY_SUBTITLE_DELAY`). */
156
167
  subtitle_delay?: number;
157
168
  /** A place card's accent pin above its title. */
@@ -327,6 +338,7 @@ function checkOverlayStyle(overlay: EdlOverlay, issue: (path: string[], message:
327
338
  if (style.subtitle_delay !== undefined && kind !== "place_card") issue(["style", "subtitle_delay"], "only a place_card has a subtitle; leave subtitle_delay out");
328
339
  if (style.pin !== undefined && kind !== "place_card") issue(["style", "pin"], "only a place_card draws a pin; leave pin out");
329
340
  if (style.stagger !== undefined && kind !== "list") issue(["style", "stagger"], "only a list has points to stagger; leave stagger out");
341
+ if (style.list_layout !== undefined && kind !== "list") issue(["style", "list_layout"], "only a list lays out points; leave list_layout out");
330
342
  if (style.underline !== undefined && kind !== "keyword") issue(["style", "underline"], "only a keyword is underlined; leave underline out");
331
343
  if ((style.exit !== undefined || style.easing !== undefined) && kind === "punch_in") issue(["style", style.exit === undefined ? "easing" : "exit"], "a punch_in eases the picture itself; leave exit and easing out");
332
344
  if (style.colors === undefined) return;
@@ -442,6 +454,12 @@ export const overlaySchema = z
442
454
  align: z.enum(OVERLAY_ALIGNS).optional().describe("center (the default) or left: how a hook_title's or a place_card's lines sit in their card."),
443
455
  subtitle_size: z.enum(OVERLAY_SIZES).optional().describe("s, m (the default, about 55 % of the title) or l: a place_card's subtitle size."),
444
456
  stagger: z.boolean().optional().describe("A list only: its points come in one by one (on item_words when given, else spaced automatically)."),
457
+ list_layout: z
458
+ .enum(OVERLAY_LIST_LAYOUTS)
459
+ .optional()
460
+ .describe(
461
+ "A list only: stack (the default: one centred card growing as each point comes in), chips (each point its own small card in one centred row, entering in turn from the left) or auto (chips when they fit one row, else stack).",
462
+ ),
445
463
  subtitle_delay: z
446
464
  .number()
447
465
  .min(0)
@@ -14,6 +14,7 @@ import {
14
14
  type OverlayEntrance,
15
15
  type OverlayExit,
16
16
  type OverlayKind,
17
+ type OverlayListLayout,
17
18
  type OverlayPosition,
18
19
  type OverlaySide,
19
20
  type OverlaySize,
@@ -61,6 +62,8 @@ const MAX_TITLE_SHRINKS = 3;
61
62
  /** A text overlay's line height and its box's padding, in font sizes. */
62
63
  export const OVERLAY_LINE_HEIGHT = 1.15;
63
64
  export const OVERLAY_LIST_LINE_HEIGHT = 1.4;
65
+ /** The room between two chips of a list's row, in font sizes. */
66
+ export const LIST_CHIP_GAP_EM = 0.3;
64
67
  /** A place card title's line height, tighter for its big type. */
65
68
  export const OVERLAY_TITLE_LINE_HEIGHT = 1.05;
66
69
  export const OVERLAY_PADDING_EM = { x: 0.6, y: 0.35 } as const;
@@ -146,7 +149,18 @@ export type ResolvedOverlay =
146
149
  | (OverlayBase & { kind: "punch_in"; scale: number; ease: number })
147
150
  | (Drawn & { kind: "keyword"; text: string; fontSize: number; side: OverlaySide; box: OverlayBox; underline?: boolean })
148
151
  | (Drawn & { kind: "lower_third"; text: string; fontSize: number; side: OverlaySide; box: OverlayBox })
149
- | (Drawn & { kind: "list"; items: string[]; fontSize: number; side: OverlaySide; box: OverlayBox; itemStarts?: number[] })
152
+ | (Drawn & {
153
+ kind: "list";
154
+ items: string[];
155
+ fontSize: number;
156
+ side: OverlaySide;
157
+ box: OverlayBox;
158
+ itemStarts?: number[];
159
+ /** Its card sits in the middle of `box` with its lines centred (a stack without `style.side`); absent: on its side. */
160
+ isCentred?: boolean;
161
+ /** Each point's own card in one row (`style.list_layout` chips, or auto when they fit); absent: one stacked card. */
162
+ chips?: OverlayBox[];
163
+ })
150
164
  | (Drawn & { kind: "arrow"; from: OverlayPoint; to: OverlayPoint })
151
165
  | (Drawn & { kind: "highlight"; rect: OverlayBox })
152
166
  | (Drawn & { kind: "hook_title"; lines: string[]; place: string | null; fontSize: number; placeFontSize: number; align?: OverlayAlign; box: OverlayBox })
@@ -285,9 +299,13 @@ export function getOverlayBounds(overlay: ResolvedOverlay): OverlayBox | null {
285
299
 
286
300
  type SideTextOverlay = Extract<ResolvedOverlay, { kind: "keyword" | "lower_third" | "list" }>;
287
301
 
288
- /** A keyword's, a lower third's or a list's lines as the draft draws them: a list's points with their bullets. */
302
+ /**
303
+ * A keyword's, a lower third's or a list's lines as the draft draws them: a list's points with their bullets on a list
304
+ * on its side; a centred stack and chips draw their points without bullets.
305
+ */
289
306
  export function getSideTextLines(overlay: SideTextOverlay): string[] {
290
- const lines = overlay.kind === "list" ? overlay.items.map((item) => `• ${item}`) : [overlay.text];
307
+ const hasBullets = overlay.kind === "list" && overlay.isCentred !== true && overlay.chips === undefined;
308
+ const lines = overlay.kind === "list" ? overlay.items.map((item) => (hasBullets ? `• ${item}` : item)) : [overlay.text];
291
309
  return lines.map((line) => line.replace(/\s+/g, " ").trim());
292
310
  }
293
311
 
@@ -299,11 +317,53 @@ export function getSideTextLines(overlay: SideTextOverlay): string[] {
299
317
  */
300
318
  export function getDrawnOverlayCard(overlay: ResolvedOverlay): OverlayBox | null {
301
319
  if (overlay.kind !== "keyword" && overlay.kind !== "lower_third" && overlay.kind !== "list") return getOverlayBounds(overlay);
320
+ if (overlay.kind === "list" && overlay.chips !== undefined) return getBoxesUnion(overlay.chips);
321
+ return getSideTextCard(overlay, getSideTextLines(overlay), overlay.box.height);
322
+ }
323
+
324
+ /** The card of a side text fitted to `lines`, `height` tall from the box's top: on its side, or in the box's middle. */
325
+ function getSideTextCard(overlay: SideTextOverlay, lines: readonly string[], height: number): OverlayBox {
302
326
  const { box, fontSize, side } = overlay;
303
327
  const padX = getOverlayPadding(overlay).x;
304
- const textWidth = Math.max(0, ...getSideTextLines(overlay).map((line) => estimateTextWidth(line, fontSize)));
328
+ const textWidth = Math.max(0, ...lines.map((line) => estimateTextWidth(line, fontSize)));
305
329
  const width = Math.min(box.width, Math.ceil(textWidth + 2 * padX));
306
- return { left: side === "right" ? box.left + box.width - width : box.left, top: box.top, width, height: box.height };
330
+ const isCentred = overlay.kind === "list" && overlay.isCentred === true;
331
+ const left = isCentred ? box.left + Math.round((box.width - width) / 2) : side === "right" ? box.left + box.width - width : box.left;
332
+ return { left, top: box.top, width, height };
333
+ }
334
+
335
+ /** The smallest box round every box of a non-empty list. */
336
+ function getBoxesUnion(boxes: readonly OverlayBox[]): OverlayBox {
337
+ const left = Math.min(...boxes.map((box) => box.left));
338
+ const top = Math.min(...boxes.map((box) => box.top));
339
+ const right = Math.max(...boxes.map((box) => box.left + box.width));
340
+ const bottom = Math.max(...boxes.map((box) => box.top + box.height));
341
+ return { left, top, width: right - left, height: bottom - top };
342
+ }
343
+
344
+ /**
345
+ * A list's drawn boxes after each point has come in (RV-144 of an adopting app): `cards[i]` is what shows once points
346
+ * 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
347
+ * widest), so it never stands sized for the whole list nor empty: its first point comes in with it. Chips add one
348
+ * card at a time, each in its final place (`overlay.chips`), so the row is centred once complete and nothing already
349
+ * shown moves. Every entry holds one box per drawn card.
350
+ */
351
+ export function getListCardsByItem(overlay: Extract<ResolvedOverlay, { kind: "list" }>): OverlayBox[][] {
352
+ if (overlay.chips !== undefined) {
353
+ const chips = overlay.chips;
354
+ return chips.map((_chip, index) => chips.slice(0, index + 1));
355
+ }
356
+ const lines = getSideTextLines(overlay);
357
+ const padY = getOverlayPadding(overlay).y;
358
+ return lines.map((_line, index) => {
359
+ const height = index === lines.length - 1 ? overlay.box.height : Math.ceil((index + 1) * overlay.fontSize * OVERLAY_LIST_LINE_HEIGHT + 2 * padY);
360
+ return [getSideTextCard(overlay, lines.slice(0, index + 1), height)];
361
+ });
362
+ }
363
+
364
+ /** The film seconds each point of a list comes in at: its own (`itemStarts`), the first with the card; else all with the card. */
365
+ export function getListItemTimes(overlay: Extract<ResolvedOverlay, { kind: "list" }>): number[] {
366
+ return overlay.items.map((_item, index) => (index === 0 ? overlay.start : (overlay.itemStarts?.[index] ?? overlay.start)));
307
367
  }
308
368
 
309
369
  /**
@@ -394,7 +454,8 @@ export function resolveEdlOverlays(input: ResolveOverlaysInput): ResolvedOverlay
394
454
  return;
395
455
  }
396
456
  const times = overlay.item_at ?? (overlay.item_words === undefined ? undefined : said.map((word) => (word as { start: number }).start));
397
- placed.overlay.itemStarts = getListItemStarts({ start, end, count: placed.overlay.items.length, ...(times === undefined ? {} : { words: times }) });
457
+ // The first point comes in with the card, so the card never stands empty (RV-144 of an adopting app).
458
+ placed.overlay.itemStarts = getListItemStarts({ start, end, count: placed.overlay.items.length, ...(times === undefined ? {} : { words: times }) }).map((at, item) => (item === 0 ? start : at));
398
459
  }
399
460
  if (placed.overlay.kind === "punch_in") {
400
461
  if (edl.segments[segment]?.motion === "kenburns") {
@@ -539,10 +600,15 @@ function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" |
539
600
  const scale = frame.width / 1080;
540
601
  const side = overlay.style?.side ?? (overlay.kind === "keyword" ? "right" : "left");
541
602
  const fontSize = Math.round(OVERLAY_FONT_SIZES[overlay.kind][overlay.style?.size ?? "m"] * scale);
542
- const padY = getOverlayPadding({ fontSize, padScale: place.padScale }).y;
603
+ const pad = getOverlayPadding({ fontSize, padScale: place.padScale });
604
+ const margin = Math.round(OVERLAY_MARGIN * scale);
605
+ const room = frame.width - zone.left - zone.right - 2 * margin;
606
+ const chips = overlay.kind === "list" ? getListChipLayout({ items: overlay.items ?? [], layout: overlay.style?.list_layout ?? "stack", fontSize, padScale: place.padScale, room }) : null;
607
+ if (chips !== null && !chips.ok) return chips;
608
+ const row = chips?.row ?? null;
543
609
  const lines = overlay.kind === "list" ? (overlay.items ?? []).length : 1;
544
610
  const lineHeight = overlay.kind === "list" ? OVERLAY_LIST_LINE_HEIGHT : OVERLAY_LINE_HEIGHT;
545
- const height = Math.ceil(lines * fontSize * lineHeight + 2 * padY);
611
+ const height = row === null ? Math.ceil(lines * fontSize * lineHeight + 2 * pad.y) : row.height;
546
612
  const region = getTextRegion(place);
547
613
  // Without a position, each kind's own place: the lower third on the captions' room, the keyword in the middle, the list high.
548
614
  const position = overlay.style?.position ?? (overlay.kind === "lower_third" ? "bottom" : overlay.kind === "keyword" ? "middle" : null);
@@ -550,14 +616,61 @@ function placeSideText(overlay: EdlOverlay & { kind: "keyword" | "lower_third" |
550
616
  if (top < region.top || top + height > region.bottom) {
551
617
  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` };
552
618
  }
553
- const margin = Math.round(OVERLAY_MARGIN * scale);
554
- const box = { left: zone.left + margin, top, width: frame.width - zone.left - zone.right - 2 * margin, height };
555
- if (overlay.kind === "list") return { ok: true, overlay: { ...drawn, kind: "list", items: overlay.items ?? [], fontSize, side, box } };
619
+ const box = { left: zone.left + margin, top, width: room, height };
620
+ if (overlay.kind === "list") {
621
+ const layout = row === null ? (overlay.style?.side === undefined ? { isCentred: true } : {}) : { chips: placeChipRow(row, box) };
622
+ // A row of chips may be drawn smaller than the list's size, to fit one row.
623
+ return { ok: true, overlay: { ...drawn, kind: "list", items: overlay.items ?? [], fontSize: row?.fontSize ?? fontSize, side, box, ...layout } };
624
+ }
556
625
  const fields = { text: overlay.text ?? "", fontSize, side, box };
557
626
  if (overlay.kind === "lower_third") return { ok: true, overlay: { ...drawn, kind: "lower_third", ...fields } };
558
627
  return { ok: true, overlay: { ...drawn, kind: "keyword", ...fields, ...(overlay.style?.underline === true ? { underline: true } : {}) } };
559
628
  }
560
629
 
630
+ /** A list's chips before they are placed: their type size, each one's width, their common height, the row's width with its gaps. */
631
+ interface ChipRow {
632
+ fontSize: number;
633
+ widths: number[];
634
+ height: number;
635
+ gap: number;
636
+ width: number;
637
+ }
638
+
639
+ /** A row of chips at one type size. */
640
+ function measureChipRow(items: readonly string[], fontSize: number, padScale: number): ChipRow {
641
+ const pad = getOverlayPadding({ fontSize, padScale });
642
+ const widths = items.map((item) => Math.ceil(estimateTextWidth(item, fontSize) + 2 * pad.x));
643
+ const gap = Math.round(fontSize * LIST_CHIP_GAP_EM);
644
+ const width = widths.reduce((sum, chip) => sum + chip, 0) + gap * Math.max(0, widths.length - 1);
645
+ return { fontSize, widths, height: Math.ceil(fontSize * OVERLAY_LINE_HEIGHT + 2 * pad.y), gap, width };
646
+ }
647
+
648
+ /**
649
+ * Whether a list draws as chips and their row (null: the stack), or why it cannot. A row wider than `room` is tried
650
+ * smaller, as a title is (by `OVERLAY_TITLE_SHRINK`, at most `MAX_TITLE_SHRINKS` times); one that never fits is refused
651
+ * on `chips`, and `auto` falls back to the stack at the list's own size. `stack` never draws chips.
652
+ */
653
+ function getListChipLayout(input: { items: readonly string[]; layout: OverlayListLayout; fontSize: number; padScale: number; room: number }): { ok: true; row: ChipRow | null } | { ok: false; error: string } {
654
+ const { items, layout, room } = input;
655
+ if (layout === "stack") return { ok: true, row: null };
656
+ const own = measureChipRow(items, input.fontSize, input.padScale);
657
+ for (let shrink = 0, row = own; shrink <= MAX_TITLE_SHRINKS; shrink++, row = measureChipRow(items, Math.round(row.fontSize * OVERLAY_TITLE_SHRINK), input.padScale)) {
658
+ if (row.width <= room) return { ok: true, row };
659
+ }
660
+ if (layout === "auto") return { ok: true, row: null };
661
+ 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` };
662
+ }
663
+
664
+ /** The chips of a row in their final places: centred in `box`, left to right in the points' order. */
665
+ function placeChipRow(row: ChipRow, box: OverlayBox): OverlayBox[] {
666
+ let left = box.left + Math.round((box.width - row.width) / 2);
667
+ return row.widths.map((width) => {
668
+ const chip = { left, top: box.top, width, height: row.height };
669
+ left += width + row.gap;
670
+ return chip;
671
+ });
672
+ }
673
+
561
674
  type CardKind = "hook_title" | "search_bar" | "place_card" | "counter" | "date_stamp";
562
675
 
563
676
  /** The default position of each card. */
package/src/index.ts CHANGED
@@ -99,6 +99,7 @@ export {
99
99
  OVERLAY_ENTRANCES_BY_KIND,
100
100
  OVERLAY_EXITS,
101
101
  OVERLAY_PINS,
102
+ OVERLAY_LIST_LAYOUTS,
102
103
  MAX_OVERLAY_SUBTITLE_DELAY,
103
104
  OVERLAY_KINDS,
104
105
  OVERLAY_POSITIONS,
@@ -117,6 +118,7 @@ export {
117
118
  type OverlayEntrance,
118
119
  type OverlayExit,
119
120
  type OverlayKind,
121
+ type OverlayListLayout,
120
122
  type OverlayPin,
121
123
  type OverlayPosition,
122
124
  type OverlaySide,
@@ -154,7 +156,10 @@ export {
154
156
  PUNCH_IN_SCALES,
155
157
  findShotBreak,
156
158
  formatOverlayNumber,
159
+ LIST_CHIP_GAP_EM,
157
160
  getDrawnOverlayCard,
161
+ getListCardsByItem,
162
+ getListItemTimes,
158
163
  getOverlayBounds,
159
164
  getOverlayPadding,
160
165
  getPlaceCardPinRow,