@company-semantics/contracts 51.3.0 → 52.1.0

package/src/notifications/renderers/slack/chat.ts

@@ -0,0 +1,167 @@
+/**
+ * A `chatUnit` on Slack — the element this channel used to drop on the floor.
+ *
+ * It was declined whole on the grounds that Block Kit has no vocabulary for
+ * turn-taking. That reasoning was sound about BLOCKS and wrong about the
+ * message: `auth.otp` and `org.invite` both nest their payload inside a
+ * `chatUnit`, so declining the element meant the one-time code and the accept
+ * button never reached Slack at all. That is semantic loss, not a presentation
+ * limitation, and no amount of correctness about turn-taking justifies posting a
+ * login email with no login code in it.
+ *
+ * Slack does have a monospace surface, so the conversation is drawn the way
+ * email draws it — `../ascii`'s bubbles, from the same functions, so the two
+ * channels cannot drift — inside `rich_text_preformatted`.
+ *
+ * **Linked CTAs break OUT of the drawing.** An `actions` block cannot nest
+ * inside `rich_text`, and it should not want to: a native button is the better
+ * control (see `./cta.ts`). So the stream is cut at each linked CTA, and the
+ * button is emitted between the halves. A hrefless CTA — the OTP code — stays
+ * inside the drawing, where the box IS the payload.
+ *
+ * INVARIANTS:
+ * - **No empty preformatted block, ever.** A break-out at the head or tail of
+ *   the stream must not leave a zero-line code box beside the button. Slack
+ *   renders one as a visible empty rectangle, so this is a drawing bug rather
+ *   than a tidiness question. Segments are merged and then filtered, so the
+ *   arithmetic cannot produce one.
+ * - **Adjacent buttons coalesce** into one `actions` block rather than one each
+ *   — see `ctaActions`.
+ * - Continuation dots that folded into a LINKED CTA survive the break-out as
+ *   their own drawn line. Folding them into a button would silently delete them.
+ */
+
+import type { KnownBlock } from "@slack/types";
+
+import type { CallToAction, ChatUnitItem } from "../../content";
+import {
+  type AsciiGeometry,
+  ruleAscii,
+  type MonospaceLine,
+  planChatUnit,
+  renderBubbleAscii,
+  renderChatCtaAscii,
+  renderChatDotsAscii,
+} from "../ascii";
+
+import { preformatted } from "./blocks";
+import { ctaActions } from "./cta";
+
+/**
+ * A stretch of the unit that becomes one block.
+ *
+ * `draw` is monospace lines; `buttons` is a run of linked CTAs. The whole
+ * algorithm below is: classify each part into one of these, merge neighbours of
+ * the same kind, drop anything empty, emit.
+ */
+type Segment =
+  | { kind: "draw"; lines: MonospaceLine[] }
+  | { kind: "buttons"; ctas: CallToAction[] };
+
+/** Classify the planned parts, keeping drawn lines and buttons apart. */
+function segmentsFor(
+  items: ChatUnitItem[],
+  geometry: AsciiGeometry,
+): Segment[] {
+  const segments: Segment[] = [];
+
+  for (const part of planChatUnit(items)) {
+    if (part.kind === "bubble") {
+      segments.push({
+        kind: "draw",
+        lines: renderBubbleAscii(part.turn, geometry),
+      });
+      continue;
+    }
+    if (part.kind === "dots") {
+      segments.push({ kind: "draw", lines: renderChatDotsAscii(geometry) });
+      continue;
+    }
+    if (!part.cta.href) {
+      // The label is the payload. It belongs in the drawing.
+      segments.push({
+        kind: "draw",
+        lines: renderChatCtaAscii(
+          part.cta,
+          part.align,
+          part.withDots,
+          geometry,
+        ),
+      });
+      continue;
+    }
+    // A linked CTA leaves the drawing. Its folded dots do not go with it — they
+    // are part of the conversation's flow, so they stay drawn.
+    if (part.withDots) {
+      segments.push({ kind: "draw", lines: renderChatDotsAscii(geometry) });
+    }
+    segments.push({ kind: "buttons", ctas: [part.cta] });
+  }
+
+  return segments;
+}
+
+/**
+ * Merge neighbouring segments of the same kind.
+ *
+ * Drawn stretches rejoin with a blank line between them, the way email joins its
+ * parts; button runs concatenate so `ctaActions` can lay them out side by side.
+ */
+function merge(segments: Segment[]): Segment[] {
+  const merged: Segment[] = [];
+
+  for (const segment of segments) {
+    const last = merged.at(-1);
+    if (last?.kind === "draw" && segment.kind === "draw") {
+      last.lines = [...last.lines, [], ...segment.lines];
+    } else if (last?.kind === "buttons" && segment.kind === "buttons") {
+      last.ctas = [...last.ctas, ...segment.ctas];
+    } else {
+      merged.push(
+        segment.kind === "draw"
+          ? { kind: "draw", lines: [...segment.lines] }
+          : { kind: "buttons", ctas: [...segment.ctas] },
+      );
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * A conversation as Slack blocks, bracketed by the same `___` rules email draws.
+ *
+ * The rules join the FIRST and LAST drawn stretches rather than becoming blocks
+ * of their own: a unit that opens or closes on a button would otherwise need a
+ * one-line code box holding nothing but a rule, which is the empty-block problem
+ * wearing a disguise. A unit made entirely of buttons draws no rule at all,
+ * because there is no conversation to bracket.
+ */
+export function renderChatUnitBlocks(
+  items: ChatUnitItem[],
+  geometry: AsciiGeometry,
+): KnownBlock[] {
+  const segments = merge(segmentsFor(items, geometry)).filter((segment) =>
+    segment.kind === "buttons"
+      ? segment.ctas.length > 0
+      : segment.lines.length > 0,
+  );
+
+  const drawn = segments.filter((segment) => segment.kind === "draw");
+  if (drawn.length > 0) {
+    const rule = ruleAscii(
+      drawn.flatMap((segment) => segment.lines),
+      geometry,
+    );
+    const first = drawn[0];
+    const last = drawn.at(-1);
+    first.lines = [rule, [], ...first.lines];
+    if (last) last.lines = [...last.lines, rule];
+  }
+
+  return segments.flatMap((segment): KnownBlock[] =>
+    segment.kind === "buttons"
+      ? ctaActions(segment.ctas)
+      : preformatted(segment.lines),
+  );
+}

package/src/notifications/renderers/slack/cta.ts

@@ -0,0 +1,69 @@
+/**
+ * A `callToAction` on Slack — and the one place this channel deliberately
+ * refuses to copy email's drawing.
+ *
+ * **With an `href`: a native `actions` button.** Slack has a real control here
+ * and it is better than anything we could draw — a large touch target, an
+ * unambiguous affordance, keyboard and screen-reader semantics supplied by the
+ * client, and forward compatibility with whatever Slack's button becomes next.
+ * Drawing an ASCII box with a link inside would be sharing the CONTROL
+ * REPRESENTATION, which is not what cross-channel consistency means. The
+ * vocabulary is shared; the control is the channel's own.
+ *
+ * **Without an `href`: the ASCII box.** The label IS the payload — a one-time
+ * code — so there is nothing to click and a button would need a fabricated
+ * destination. Here email's `>> LABEL <<` box is exactly right, drawn by
+ * `../ascii` so the two channels cannot drift a column apart, and set in
+ * `rich_text_preformatted` so Slack renders it monospaced and cleanly
+ * selectable.
+ *
+ * That split is the whole principle in one element: same semantics, same brand
+ * drawing where the channel has nothing better, native primitive where it does.
+ */
+
+import type { ActionsBlock, Button, KnownBlock } from "@slack/types";
+
+import type { CallToAction } from "../../content";
+import { type AsciiGeometry, renderCtaAscii } from "../ascii";
+
+import { ACTIONS_MAX_ELEMENTS, chunk, plainText, preformatted } from "./blocks";
+
+/** A linked CTA as one button. `plain_text` is literal — never escaped. */
+export function ctaButton(cta: CallToAction): Button {
+  return {
+    type: "button",
+    text: plainText(cta.label),
+    // Only ever called for a linked CTA; the caller owns that branch.
+    url: cta.href,
+  };
+}
+
+/**
+ * One `actions` block per run of linked CTAs, split at Slack's element cap.
+ *
+ * Adjacent CTAs coalesce rather than each claiming their own block: two buttons
+ * in one `actions` sit side by side the way a reader expects a choice to be
+ * offered, while two `actions` blocks stack them and read as two unrelated
+ * prompts. Slack caps a block at 25 elements, so a longer run splits rather
+ * than being rejected.
+ */
+export function ctaActions(ctas: CallToAction[]): ActionsBlock[] {
+  return chunk(ctas, ACTIONS_MAX_ELEMENTS).map((group) => ({
+    type: "actions",
+    elements: group.map(ctaButton),
+  }));
+}
+
+/**
+ * A standalone `callToAction` element.
+ *
+ * The hrefless form draws the box; the linked form is a button.
+ */
+export function renderCtaBlocks(
+  cta: CallToAction,
+  geometry: AsciiGeometry,
+): KnownBlock[] {
+  return cta.href
+    ? ctaActions([cta])
+    : preformatted(renderCtaAscii(cta, geometry));
+}