@stack-mode/site-manager-kit 0.0.0-stage → 1.44.0

package/src/visual-accents.ts

@@ -0,0 +1,126 @@
+/*
+ * Gold accent words in a heading: one text value plus the ranges of it shown in the accent color, marked with the
+ * Accent control, never typed markup. Stored as `{ accents: [[start, end], ...] }` in the key's valueJson beside its
+ * text, so every reader of the text keeps working. Pure and safe in the browser. Site Manager has the same
+ * rules (src/modules/site_copy/accents.ts there); change both together.
+ */
+
+export type Accent = [number, number];
+export type AccentRun = { text: string; accent: boolean };
+
+const MAX_RANGES = 50;
+
+/**
+ * The ranges, checked against the text: whole numbers inside it, empty ones dropped, sorted, and overlapping or
+ * touching ones merged. Null when the shape isn't a list of [start, end] pairs.
+ */
+export function normalizeAccents(text: string, accents: unknown): Accent[] | null {
+  if (!Array.isArray(accents) || accents.length > MAX_RANGES) return null;
+  const out: Accent[] = [];
+  for (const a of accents) {
+    if (!Array.isArray(a) || a.length !== 2 || !a.every((n) => Number.isInteger(n))) return null;
+    const start = Math.max(0, Math.min(a[0] as number, text.length));
+    const end = Math.max(0, Math.min(a[1] as number, text.length));
+    if (end > start) out.push([start, end]);
+  }
+  out.sort((x, y) => x[0] - y[0]);
+  const merged: Accent[] = [];
+  for (const r of out) {
+    const last = merged[merged.length - 1];
+    if (last && r[0] <= last[1]) last[1] = Math.max(last[1], r[1]);
+    else merged.push([r[0], r[1]]);
+  }
+  return merged;
+}
+
+/** The text as runs, plain and accented, in order. Empty runs are left out. */
+export function accentRuns(text: string, accents: Accent[]): AccentRun[] {
+  const runs: AccentRun[] = [];
+  let at = 0;
+  for (const [s, e] of accents) {
+    if (s > at) runs.push({ text: text.slice(at, s), accent: false });
+    runs.push({ text: text.slice(s, e), accent: true });
+    at = e;
+  }
+  if (at < text.length) runs.push({ text: text.slice(at), accent: false });
+  return runs.filter((r) => r.text.length > 0);
+}
+
+/** The accents stored with a text value, or undefined when it has none (an older heading split into two keys). */
+export function storedAccents(valueJson: unknown, text: string): Accent[] | undefined {
+  const a = (valueJson as { accents?: unknown } | null)?.accents;
+  if (a === undefined) return undefined;
+  return normalizeAccents(text, a) ?? [];
+}
+
+/** Runs back to one text and its ranges, the way the heading editor reads what was typed. */
+export function fromRuns(runs: AccentRun[]): { text: string; accents: Accent[] } {
+  let text = "";
+  const accents: Accent[] = [];
+  for (const r of runs) {
+    if (r.accent && r.text) accents.push([text.length, text.length + r.text.length]);
+    text += r.text;
+  }
+  return { text, accents: normalizeAccents(text, accents) ?? [] };
+}
+
+/** A text value's gold words as runs, for a site's heading component: one plain run when it has none. */
+export function headingRuns(value: { text: string | null; accents?: Accent[] | null } | null | undefined): AccentRun[] {
+  const text = value?.text ?? "";
+  return accentRuns(text, normalizeAccents(text, value?.accents ?? []) ?? []);
+}
+
+/*
+ * Bold, italic and gold together: a text value may mark words as important (strong, rendered <strong>), emphasized
+ * (em, rendered <em>) and gold (accents, a styled span). All are ranges of the plain text, never markup.
+ */
+export type Mark = "accent" | "strong" | "em";
+export type MarkedRun = { text: string; accent: boolean; strong: boolean; em: boolean };
+export type Marks = { accents?: Accent[] | null; strong?: Accent[] | null; em?: Accent[] | null };
+
+/** The text as runs split wherever a mark starts or ends. Empty runs are left out. */
+export function markedRuns(text: string, marks: Marks): MarkedRun[] {
+  const accents = normalizeAccents(text, marks.accents ?? []) ?? [];
+  const strong = normalizeAccents(text, marks.strong ?? []) ?? [];
+  const em = normalizeAccents(text, marks.em ?? []) ?? [];
+  const cuts = new Set<number>([0, text.length]);
+  for (const [s, e] of [...accents, ...strong, ...em]) {
+    cuts.add(s);
+    cuts.add(e);
+  }
+  const points = [...cuts].sort((a, b) => a - b);
+  const inside = (ranges: Accent[], i: number) => ranges.some(([s, e]) => i >= s && i < e);
+  const runs: MarkedRun[] = [];
+  for (let i = 0; i < points.length - 1; i++) {
+    const from = points[i]!;
+    const to = points[i + 1]!;
+    if (to <= from) continue;
+    const run = { text: text.slice(from, to), accent: inside(accents, from), strong: inside(strong, from), em: inside(em, from) };
+    const last = runs[runs.length - 1];
+    if (last && last.accent === run.accent && last.strong === run.strong && last.em === run.em) last.text += run.text;
+    else runs.push(run);
+  }
+  return runs;
+}
+
+/** Runs back to one text and its ranges of each mark, the way the editor reads what was typed. */
+export function fromMarkedRuns(runs: { text: string; accent?: boolean; strong?: boolean; em?: boolean }[]): { text: string; accents: Accent[]; strong: Accent[]; em: Accent[] } {
+  let text = "";
+  const accents: Accent[] = [];
+  const strong: Accent[] = [];
+  const em: Accent[] = [];
+  for (const r of runs) {
+    const span: Accent = [text.length, text.length + r.text.length];
+    if (r.text && r.accent) accents.push(span);
+    if (r.text && r.strong) strong.push(span);
+    if (r.text && r.em) em.push(span);
+    text += r.text;
+  }
+  const n = (x: Accent[]) => normalizeAccents(text, x) ?? [];
+  return { text, accents: n(accents), strong: n(strong), em: n(em) };
+}
+
+/** A text value as runs with every mark, for a site's text components: one plain run when it has none. */
+export function textRuns(value: { text: string | null; accents?: Accent[] | null; strong?: Accent[] | null; em?: Accent[] | null } | null | undefined): MarkedRun[] {
+  return markedRuns(value?.text ?? "", value ?? {});
+}