@company-semantics/contracts 51.3.0 → 52.1.0

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

@@ -3,18 +3,24 @@
  *
  * Where `../sms` proves the content model survives the poorest channel, this one
  * proves the other edge: a channel whose output is neither a string nor email's
- * `{ subject, text, html }`, but a tree of typed blocks. Between the three, `Out`
- * has been a record, a string and a different record — which is the seam property
- * `../../renderer.ts` states in prose ("each renderer returns its natural type",
- * no `ChannelOutput` supertype) held by real modules rather than asserted.
+ * `{ subject, text, html }`, but a tree of typed blocks. The blocks are Slack's
+ * OWN vocabulary — `@slack/types`' `KnownBlock` is the union Slack's API
+ * validates against, so a drift from the wire format is a compile error rather
+ * than a silent one.
  *
- * The blocks are Slack's OWN vocabulary: `@slack/types` is the published type
- * package behind `node-slack-sdk`, so `KnownBlock` is the same union Slack's API
- * validates against. This channel used to hand-write a five-block approximation
- * of Block Kit; that is what ADR-CONTRACTS-090 retires. A renderer whose output
- * type is invented can drift from the wire format silently, and no test in this
- * package would notice — the compiler is the only thing that can, and it can only
- * help if the types are theirs.
+ * **The voice.** This channel's narrative content is monospace, drawn by
+ * `../ascii` — the same functions the email's `text/plain` surface uses, so a
+ * conversation cannot come out a column apart on the two channels. Slack's
+ * `rich_text_preformatted` is the surface that makes it possible: it is set in a
+ * monospace face by Slack itself, so the voice here is REAL rather than a
+ * stylesheet the gallery applies and a workspace ignores.
+ *
+ * **Where the voice stops.** Controls, structure and the title are exempt and
+ * use Slack's own primitives: a linked CTA is an `actions` button (`./cta.ts`),
+ * a table is a `table` block (`./table.ts`), the headline is a `header`, and an
+ * image is an `image`. Sharing a VOCABULARY across channels is the goal; sharing
+ * a control REPRESENTATION is not, and a native button beats an ASCII box drawn
+ * inside a code block on every measure that matters to a reader.
  *
  * It is STILL non-functional in the one sense that matters most:
  *
@@ -22,143 +28,71 @@
  *   renderer renders; delivery and the decision to deliver are the backend's
  *   (`SlackChannelDelivery` throws `ChannelNotImplementedError` by design).
  *
- * What it is no longer: low fidelity. The copy is still invented rather than
- * relocated from a shipped Slack app — there is no golden here the way `../email`
- * has one — but the SHAPE is legitimate Block Kit and the `__tests__` pin it.
- *
  * INVARIANTS:
  * - Pure — a function of `(content, context)`. No clock, no environment, no I/O.
  *   The brand and the copyright year come from `context.brand`.
- * - `supports` is total, and agrees with `render`: `chatUnit` is omitted, never
- *   approximated and never thrown on.
- * - Escaping follows the SURFACE, not the string. `mrkdwn` is Slack's dialect and
- *   every user-controlled string reaching one passes through `escapeMrkdwn`;
- *   `plain_text` and `rich_text` are literal surfaces and must NOT be escaped, or
- *   the reader sees `&`. See `escapeMrkdwn`.
+ * - `supports` is total-true: Slack can now depict every element. That is a
+ *   claim about TODAY, and `assertNever` below is what keeps it true tomorrow —
+ *   see the note on the switch.
+ * - Escaping follows the SURFACE, not the string. See `./blocks.ts`.
  * - Slack's documented limits are enforced here, not left to the API to reject:
- *   a header truncates at 150 chars, section fields chunk at 10.
+ *   a header truncates at 150 chars, an `actions` block splits at 25 elements.
  * - Nothing here reads `metadata.kind`. A renderer that special-cases a kind has
  *   lost the model — the fix for a missing fact is upstream in `compose`.
  */
 
-import type {
-  ActionsBlock,
-  ContextBlock,
-  DividerBlock,
-  HeaderBlock,
-  ImageBlock,
-  KnownBlock,
-  MrkdwnElement,
-  PlainTextElement,
-  RichTextBlock,
-  RichTextSection,
-  SectionBlock,
-} from "@slack/types";
+import type { KnownBlock } from "@slack/types";
 
 import type { NotificationContent, NotificationElement } from "../../content";
 import type { RenderContext } from "../../context";
 import type { Renderer } from "../../renderer";
+import {
+  type AsciiGeometry,
+  geometryFor,
+  keyValueLines,
+  proseLines,
+  fullRuleAscii,
+  signatureLines,
+} from "../ascii";
+import { COMPANY_URL } from "../brand";
+import { MONOSPACE_COLUMNS } from "../layout";
 
-// =============================================================================
-// Slack's documented limits
-// =============================================================================
+import { coalescePreformatted, preformatted } from "./blocks";
+import { renderChatUnitBlocks } from "./chat";
+import { renderCtaBlocks } from "./cta";
 
-/** A `header` block's text. Slack rejects the message beyond this. */
-const HEADER_MAX_CHARS = 150;
+export type { SlackMessage } from "./message";
 
-/** Fields per `section`. A longer table chunks across sections rather than 400s. */
-const SECTION_MAX_FIELDS = 10;
+import type { SlackMessage } from "./message";
 
-// =============================================================================
-// One Slack message
-// =============================================================================
+/** The same budget email's plain-text surface draws inside (`../layout.ts`). */
+const GEOMETRY: AsciiGeometry = geometryFor(MONOSPACE_COLUMNS);
 
 /**
- * This channel's natural output type.
+ * A refusal to let a future element disappear quietly.
  *
- * `blocks` is `KnownBlock[]` — Slack's own union, not ours. `text` is the
- * notification-and-fallback string Slack shows where blocks cannot render (a push
- * notification, a screen reader). It is `metadata.title`, which is the same field
- * email spends as its subject and this channel ALSO spends as its `header` block:
- * one content-level fact, three channel-level uses, which is why it lives on the
- * content rather than in a channel's registry.
- */
-export interface SlackMessage {
-  text: string;
-  blocks: KnownBlock[];
-}
-
-// =============================================================================
-// Surfaces
-// =============================================================================
-
-/**
- * Slack's three reserved characters, for `mrkdwn` surfaces ONLY.
+ * `supports` returns true for everything, which is a fact about the twelve
+ * elements that exist today. Left alone, that answer would also cover a
+ * thirteenth: the switch below would fall through, return no blocks, and Slack
+ * would post a message with a silent hole in it — which is precisely the
+ * `chatUnit` bug, reincarnated under a new name and harder to see, because there
+ * would no longer be a `supports` returning false to point at it.
  *
- * Everything else is literal, so — unlike HTML — this is the whole of the rule.
- *
- * ⚠️ Applying this to a `plain_text` or `rich_text` surface is a DEFECT, not
- * belt-and-braces: those surfaces do not parse `&`/`<`/`>`, so an escaped string
- * renders the entity itself and the reader sees `Acme &amp; Co`. The old
- * hand-written subset could not express the distinction because it had no literal
- * surfaces beyond a button label; `header` and `rich_text` make it load-bearing.
- * `__tests__/index.test.ts` pins both halves.
+ * So the switch has no `default`. Adding a `NotificationElement` variant makes
+ * this line fail to compile until someone has chosen how Slack says it.
  */
-function escapeMrkdwn(value: string): string {
-  return value
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
-}
-
-/** An mrkdwn text object, from an already-escaped string. */
-function mrkdwn(text: string): MrkdwnElement {
-  return { type: "mrkdwn", text };
-}
-
-/** A literal text object. Never escaped — see `escapeMrkdwn`. */
-function plainText(text: string): PlainTextElement {
-  return { type: "plain_text", text };
-}
-
-/** A section carrying pre-escaped mrkdwn. */
-function section(text: string): SectionBlock {
-  return { type: "section", text: mrkdwn(text) };
-}
-
-/** A context block carrying pre-escaped mrkdwn. */
-function context(text: string): ContextBlock {
-  return { type: "context", elements: [mrkdwn(text)] };
+function assertNever(element: never): never {
+  throw new Error(
+    `Slack renderer has no representation for element: ${JSON.stringify(element)}`,
+  );
 }
 
-/** A rich-text section wrapping literal text. */
-function richTextSection(text: string): RichTextSection {
-  return { type: "rich_text_section", elements: [{ type: "text", text }] };
-}
-
-/** Split into chunks of at most `size`. Slack caps several collections. */
-function chunk<T>(items: T[], size: number): T[][] {
-  const chunks: T[][] = [];
-  for (let index = 0; index < items.length; index += size) {
-    chunks.push(items.slice(index, index + size));
-  }
-  return chunks;
-}
-
-// =============================================================================
-// Rendering
-// =============================================================================
-
 /**
  * One element as zero or more blocks.
  *
- * Zero and many are both real here — `chatUnit` yields nothing, and an element is
- * free to become several blocks — which is why this returns an array where
- * `../sms`'s equivalent returns a string. The switch is total over all twelve
- * types rather than the eleven `supports` admits: the declined arm is unreachable
- * (`render` filters on `supports` first), but writing it out is what makes the
- * compiler prove the two lists agree. A `default` arm would silently swallow a
- * thirteenth member of the union.
+ * Zero is still reachable — an empty table or an empty drawing yields nothing —
+ * but it is now always a statement about EMPTY CONTENT, never about a channel
+ * that gave up on the element.
  */
 function renderElement(
   element: NotificationElement,
@@ -166,58 +100,25 @@ function renderElement(
 ): KnownBlock[] {
   switch (element.type) {
     case "greeting":
-      return [section(`Hi ${escapeMrkdwn(element.recipientName ?? "there")},`)];
+      return preformatted(
+        proseLines(`Hi ${element.recipientName ?? "there"},`, GEOMETRY),
+      );
     case "body":
-      return [section(escapeMrkdwn(element.text))];
+      return preformatted(proseLines(element.text, GEOMETRY));
     case "keyValueTable":
-      // `fields` is Slack's own two-column device for exactly this — facts that
-      // belong together, laid out side by side. The old subset had no `fields`,
-      // so it flattened the table into `*label:* value` lines and lost the
-      // grouping that `KeyValueTable` exists to carry. The `:` was presentation
-      // and lives in no element (see ../../kinds/README.md); Slack's answer is a
-      // bold label above its value, so the colon is simply gone.
-      //
-      // Slack caps a section at ten fields; a longer table becomes more sections
-      // rather than an API rejection.
-      return chunk(element.rows, SECTION_MAX_FIELDS).map((rows) => ({
-        type: "section",
-        fields: rows.map((row) =>
-          mrkdwn(`*${escapeMrkdwn(row.label)}*\n${escapeMrkdwn(row.value)}`),
-        ),
-      }));
+      // `Label: value` lines in the monospace flow, exactly as the email says
+      // them. A `table` block was tried here and removed: it draws its own
+      // bordered grid, so every key/value pair cut the message into another
+      // container and a two-fact notification arrived as five stacked boxes.
+      // The email states these as plain lines and reads as one thing; matching
+      // that is worth more than column alignment two rows never needed.
+      return preformatted(keyValueLines(element.rows));
     case "callToAction":
-      // `href` absent means the label IS the payload (an OTP code), so it becomes
-      // a preformatted block — Slack's code-block surface, which renders it in a
-      // monospaced box the reader can select cleanly — rather than a button with
-      // a fabricated destination. `rich_text` is a LITERAL surface: no escaping.
-      return element.href
-        ? [
-            {
-              type: "actions",
-              elements: [
-                {
-                  type: "button",
-                  text: plainText(element.label),
-                  url: element.href,
-                },
-              ],
-            },
-          ]
-        : [
-            {
-              type: "rich_text",
-              elements: [
-                {
-                  type: "rich_text_preformatted",
-                  elements: [{ type: "text", text: element.label }],
-                },
-              ],
-            },
-          ];
+      return renderCtaBlocks(element, GEOMETRY);
     case "list":
-      // A real `rich_text_list`, not bullet characters glued onto a string. Slack
-      // draws the markers, the indentation and the numbering; `ordered` maps onto
-      // its own `style`. Literal surface — no escaping.
+      // A real `rich_text_list`, not bullet characters glued onto a string.
+      // Slack draws the markers, the indentation and the numbering; `ordered`
+      // maps onto its own `style`. Literal surface — no escaping.
       return [
         {
           type: "rich_text",
@@ -225,7 +126,10 @@ function renderElement(
             {
               type: "rich_text_list",
               style: element.ordered ? "ordered" : "bullet",
-              elements: element.items.map(richTextSection),
+              elements: element.items.map((item) => ({
+                type: "rich_text_section",
+                elements: [{ type: "text", text: item }],
+              })),
             },
           ],
         },
@@ -233,68 +137,68 @@ function renderElement(
     case "divider":
       return [{ type: "divider" }];
     case "warning":
-      // Fieldless by design: the banner IS the content and its prominence is the
-      // channel's to choose. Slack's answer is an emoji and bold text.
-      return [section(":warning: *Security notice*")];
+      // Fieldless by design: the banner IS the content. Email sets it in the
+      // same squared glyphs, and they are the only part of this notification
+      // whose shape survives a channel with no colour of its own.
+      return preformatted(proseLines("🆆🅰🆁🅽🅸🅽🅶", GEOMETRY));
     case "metadata":
-      // A context block, because this element exists to BE de-emphasisable —
-      // diagnostic detail about the request, distinct from the facts themselves.
-      return [
-        context(
-          [
-            element.label ? `*${escapeMrkdwn(element.label)}*` : "",
-            ...element.rows.map(
-              (row) => `${escapeMrkdwn(row.label)}: ${escapeMrkdwn(row.value)}`,
-            ),
-          ]
-            .filter(Boolean)
-            .join(" · "),
-        ),
-      ];
+      // Same lines as `keyValueTable`, under the element's own heading. The
+      // de-emphasis a `context` block used to give this is dropped on purpose:
+      // it pulled the diagnostics out of the monospace flow into Slack's sans,
+      // so the one element meant to recede was the one that looked different
+      // from everything around it.
+      return preformatted(keyValueLines(element.rows, element.label));
     case "notice":
-      return [context(element.lines.map(escapeMrkdwn).join("\n"))];
+      return preformatted(
+        element.lines.flatMap((line) => proseLines(line, GEOMETRY)),
+      );
+    case "chatUnit":
+      return renderChatUnitBlocks(element.items, GEOMETRY);
     case "signature":
+      // The same sign-off email draws, from the same function — the marker, the
+      // copyright line, the URL. The URL arrives as a LINK run, which the
+      // preformatted surface admits; email's plain-text body can only flatten it.
+      //
       // Both the signer fallback and the year come from the context. This is the
       // element that used to hide a `new Date()`; here there is nowhere to hide.
-      return [
-        context(
-          `© ${renderContext.brand.copyrightYear} ${escapeMrkdwn(
-            element.signer ?? renderContext.brand.name,
-          )}`,
+      return preformatted(
+        signatureLines(
+          element.signer ?? renderContext.brand.name,
+          renderContext.brand.copyrightYear,
+          COMPANY_URL,
         ),
-      ];
+      );
     case "heroImage":
       return [{ type: "image", image_url: element.src, alt_text: element.alt }];
-    case "chatUnit":
-      return [];
+    default:
+      return assertNever(element);
   }
 }
 
 /**
- * The `header` block — `metadata.title`, the same fact email spends as its
- * subject.
+ * The title, as the first lines of the message body.
  *
- * A real Slack message leads with its headline; the old subset spent the title
- * only on the invisible `text` fallback, so the message opened straight into "Hi
- * there," and the reader had to infer what it was about from the body. Both uses
- * are correct and neither replaces the other: `text` is what a push notification
- * and a screen reader get, `header` is what the message looks like.
+ * NOT a `header` block. A header is `plain_text` and Slack owns its typography
+ * entirely — `HeaderBlock` is `{ type, text }` and there is no font, size,
+ * weight or colour anywhere in the schema — so a header would be the one line of
+ * the notification that could never be set in the brand's face. Putting the
+ * title in the monospace body makes it monospace FOR REAL, in a workspace as
+ * well as in the gallery, rather than by a stylesheet the gallery applies and
+ * Slack ignores.
  *
- * `plain_text` is a literal surface AND Slack's only option here — a header does
- * not parse mrkdwn — so the title is passed through unescaped and truncated to
- * Slack's documented 150.
+ * What that costs is Slack's large headline treatment, which is what makes a
+ * message scannable in a busy channel. The trade is deliberate: the title is
+ * still the FALLBACK (`text`), so a push notification and a screen reader
+ * announce it exactly as before — the header block was never what carried it
+ * there.
+ *
+ * A rule underneath does the work the type size used to.
  */
-function renderHeader(content: NotificationContent): HeaderBlock[] {
+function renderTitle(content: NotificationContent): KnownBlock[] {
   const title = content.metadata.title.trim();
   if (!title) return [];
-  return [
-    { type: "header", text: plainText(truncate(title, HEADER_MAX_CHARS)) },
-  ];
-}
-
-/** Cut to `max` characters, marking the cut so a clipped headline reads as one. */
-function truncate(value: string, max: number): string {
-  return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
+  const lines = proseLines(title, GEOMETRY);
+  return preformatted([...lines, fullRuleAscii(GEOMETRY)]);
 }
 
 /**
@@ -305,25 +209,27 @@ function truncate(value: string, max: number): string {
 export const slackRenderer: Renderer<SlackMessage> = {
   id: "slack",
   /**
-   * One decline: `chatUnit`.
+   * Slack depicts every element.
    *
-   * Block Kit has no vocabulary for turn-taking. Flattening a conversation into a
-   * run of sections would drop the attribution that IS the meaning, which the
-   * content model names as the reason to decline the whole element rather than
-   * approximate it. Everything else Slack can genuinely depict — including the
-   * hero image `../sms` has no surface for, which is the point of having two
-   * stubs rather than one.
+   * `chatUnit` was the one decline, on the grounds that Block Kit has no
+   * vocabulary for turn-taking. True of blocks, and beside the point about
+   * messages: the kinds that nest a payload inside a `chatUnit` were arriving
+   * with the payload missing. A monospace drawing depicts the conversation and
+   * keeps the attribution the decline was protecting, so there is nothing left
+   * to decline.
+   *
+   * `assertNever` in `renderElement`, not this answer, is what protects the
+   * NEXT element.
    */
-  supports: (elementType) => elementType !== "chatUnit",
+  supports: () => true,
   render: (content: NotificationContent, renderContext: RenderContext) => ({
     text: content.metadata.title,
-    blocks: [
-      ...renderHeader(content),
+    blocks: coalescePreformatted([
+      ...renderTitle(content),
       ...content.sections
         .flatMap((section_) => section_.elements)
-        .filter((element) => slackRenderer.supports(element.type))
         .flatMap((element) => renderElement(element, renderContext)),
-    ],
+    ]),
   }),
 };
 
@@ -343,4 +249,5 @@ export type {
   PlainTextElement,
   RichTextBlock,
   SectionBlock,
-};
+  TableBlock,
+} from "@slack/types";

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

@@ -0,0 +1,23 @@
+/**
+ * This channel's natural output type.
+ *
+ * In its own module so `./index.ts`, `./chat.ts` and the backend's delivery can
+ * all name it without importing the renderer itself.
+ */
+
+import type { KnownBlock } from "@slack/types";
+
+/**
+ * One Slack message.
+ *
+ * `blocks` is `KnownBlock[]` — Slack's own union, not ours. `text` is the
+ * notification-and-fallback string Slack shows where blocks cannot render (a push
+ * notification, a screen reader). It is `metadata.title`, which is the same field
+ * email spends as its subject and this channel ALSO spends as its `header` block:
+ * one content-level fact, three channel-level uses, which is why it lives on the
+ * content rather than in a channel's registry.
+ */
+export interface SlackMessage {
+  text: string;
+  blocks: KnownBlock[];
+}