@company-semantics/contracts 52.0.0 → 53.0.0

package/src/notifications/renderers/slack/README.md

@@ -12,66 +12,102 @@ record, a string and a different record, which is `../../renderer.ts`'s "each
 renderer returns its natural type" held by real modules rather than asserted about
 the type itself.
 
-The whole channel is one `index.ts` — the surfaces, the escaping, and the
-renderer. `../email` splits across seven modules because it carries real markup;
-this one composes blocks and has no markup to own.
+| module       | what it holds                                                    |
+| ------------ | ---------------------------------------------------------------- |
+| `index.ts`   | `slackRenderer`, the element switch, the title                   |
+| `message.ts` | `SlackMessage`, the channel's natural type                       |
+| `blocks.ts`  | Slack's surfaces, and `../ascii`'s runs bridged onto them        |
+| `cta.ts`     | the button / the drawn box, and why a CTA is one or the other    |
+| `chat.ts`    | `chatUnit` → a drawn conversation, cut where a button breaks out |
 
-## The blocks are Slack's, not ours
+## The voice is monospace, and it is REAL
 
-`SlackMessage.blocks` is `KnownBlock[]` from **`@slack/types`** — the published
-type package behind `node-slack-sdk`, so it is the same union Slack's API
-validates against. This channel used to hand-write a five-block approximation;
-ADR-CONTRACTS-090 retires it. A renderer whose output type is invented can drift
-from the wire format silently and nothing in this package would notice — the
-compiler is the only thing that can, and only if the types are theirs.
+The narrative content is drawn by `../ascii` — the same functions email's
+`text/plain` surface uses, so a conversation cannot come out a column apart on the
+two channels — and set in `rich_text_preformatted`, which Slack renders in a
+monospace face itself.
 
-`index.ts` re-exports the block types it uses, so a consumer can name them without
-taking its own dependency on `@slack/types`. Widen that list rather than
-redeclaring a shape.
+That last clause is the whole point. The brand voice reaches a real workspace
+here, not just the Ladle gallery. Nothing in the app applies a stylesheet to make
+this look monospace; it IS monospace, because of the block type.
 
-The field names are snake_case (`image_url`, `alt_text`) because Block Kit is a
-wire format and those are its names. That is deliberate, not a lapse in the
-repo's camelCase convention.
+## Where the voice stops, and why that is not a compromise
 
-## What is still non-functional
+Controls, structure and images use Slack's own primitives:
 
-- **It does not send.** No token, no channel id, no `chat.postMessage`. A renderer
-  renders; delivery and the decision to deliver are the backend's —
-  `SlackChannelDelivery` throws `ChannelNotImplementedError` by design.
-- **The copy is invented**, not relocated from a shipped Slack app. There is no
-  golden here the way `../email` has one. The SHAPE is legitimate Block Kit and
-  `__tests__/index.test.ts` pins it; the WORDING is expected to change when a kind
-  is actually posted to Slack.
+- a linked `callToAction` is a native `actions` button
+- `divider` is a `divider`
+- `heroImage` is an `image`
+
+Slack's button beats anything we could draw inside a code block — 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.
+Sharing a VOCABULARY across channels is the goal; sharing a control
+REPRESENTATION is not. The drift worth preventing is semantic drift, not a
+requirement that a button and a plaintext email match byte for byte.
+
+## There is no author-set colour or font — do not go looking again
+
+The entire Block Kit schema contains two colour-ish fields and neither helps:
+
+| Candidate          | What it actually is                                        |
+| ------------------ | ---------------------------------------------------------- |
+| `Button.style`     | `'primary' \| 'danger'` — and Slack's `primary` is GREEN   |
+| `RichTextColor`    | renders a colour SWATCH from a hex, not coloured text      |
+| `AlertBlock.level` | `'default' \| 'info' \| 'warning' \| 'error' \| 'success'` |
+| `CardBlock`        | images, title, subtitle, body, actions — no colour         |
+| attachment `color` | legacy; the documentation page 404s                        |
+
+No font or size field exists anywhere, on any block. A `header` block is
+`plain_text` and Slack owns its typography completely — which is why the title is
+NOT a header block here (see below). Any future attempt to brand this channel with
+CSS belongs in a gallery, not in a renderer, and a gallery that does it is lying
+about what ships.
+
+## The title is body text, not a `header` block
+
+`HeaderBlock` is `{ type, text }`. Slack picks the size, weight, face and colour,
+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 with a rule under it
+makes it monospace in a real workspace.
+
+What that costs is Slack's large headline treatment. What it does not cost is the
+push notification or the screen reader: those read `SlackMessage.text`, which is
+`metadata.title` and never came from the header block.
 
 ## Element → block
 
-| Element                           | Block                                                      |
-| --------------------------------- | ---------------------------------------------------------- |
-| `metadata.title`                  | `header` (+ the `text` fallback)                           |
-| `greeting`, `body`, `warning`     | `section` (mrkdwn)                                         |
-| `keyValueTable`                   | `section.fields` — Slack's two-column facts, chunked at 10 |
-| `callToAction` **with** `href`    | `actions` + `button`                                       |
-| `callToAction` **without** `href` | `rich_text` › `rich_text_preformatted`                     |
-| `list`                            | `rich_text` › `rich_text_list` (`bullet` / `ordered`)      |
-| `divider`                         | `divider`                                                  |
-| `metadata`, `notice`, `signature` | `context`                                                  |
-| `heroImage`                       | `image`                                                    |
-| `chatUnit`                        | _declined_                                                 |
-
-## The one decline
-
-`supports` answers `false` for `chatUnit` alone. Block Kit has no vocabulary for
-turn-taking, and flattening a conversation into a run of sections drops the
-attribution that IS the meaning — which the content model names as the reason to
-decline a whole element rather than approximate it.
-
-Everything else Slack genuinely depicts, **including the `heroImage` that `../sms`
-has no surface for**. That difference is the point of shipping three channels
-rather than one: same `NotificationContent`, no channel tags on it, three channels
-of differing capability each keeping what they can show.
-
-`metadata` and `notice` become `context` blocks — Slack's own device for
-de-emphasised small print, which is exactly what `MetadataElement` exists to be.
+| Element                                              | Block                                        |
+| ---------------------------------------------------- | -------------------------------------------- |
+| `metadata.title`                                     | monospace lines + a full-width rule          |
+| `greeting`, `body`, `notice`, `warning`, `signature` | `rich_text` › `rich_text_preformatted`       |
+| `keyValueTable`, `metadata`                          | `Label: value` lines, in the same flow       |
+| `callToAction` **with** `href`                       | `actions` + `button`                         |
+| `callToAction` **without** `href`                    | the drawn `>> LABEL <<` box, in the flow     |
+| `chatUnit`                                           | a drawn conversation, cut for any linked CTA |
+| `list`                                               | `rich_text` › `rich_text_list`               |
+| `divider`                                            | `divider`                                    |
+| `heroImage`                                          | `image`                                      |
+
+Contiguous monospace COALESCES into one block. Slack draws every
+`rich_text_preformatted` as its own bordered box, so one block per element stacks
+a grey rectangle per element; email's `text/plain` body is one continuous surface
+and so is this. The run breaks only at a native primitive.
+
+## Nothing is declined any more
+
+`supports` answers `true` for every element.
+
+`chatUnit` was the one decline, on the grounds that Block Kit has no vocabulary
+for turn-taking. That was sound about BLOCKS and wrong about the message: both
+`auth.otp` and `org.invite` 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 notification with no login
+code in it.
+
+A monospace drawing depicts the conversation AND keeps the attribution the decline
+was protecting, so there is nothing left to decline.
 
 ## Invariants
 
@@ -79,36 +115,56 @@ de-emphasised small print, which is exactly what `MetadataElement` exists to be.
   environment, no I/O. The brand and the copyright year come from `context.brand`.
   `signature` is the element that used to hide a `new Date()`; here there is
   nowhere to hide.
-- `supports` is total over `NotificationElementType` and AGREES with `render`:
-  `chatUnit` is omitted, never approximated and never thrown on.
-- **Escaping follows the SURFACE, not the string.** Every user-controlled string
-  reaching an **mrkdwn** surface passes through `escapeMrkdwn` — the same rule
-  `../email` applies with `escapeHtml`. But `plain_text` (header, button label)
-  and `rich_text` (the OTP code, list items) are **literal**: escaping them is a
-  DEFECT, because those surfaces do not parse the entities and the reader sees
-  `Acme &amp; Co`. The old subset had no literal surface beyond a button label, so
-  the distinction only became load-bearing with `header` and `rich_text`. The
-  compiler cannot help — both surfaces are `string` — so
-  `__tests__/index.test.ts` pins both halves.
-- Slack's documented LIMITS are enforced here, not left to the API to reject: a
-  header truncates at 150 characters, `section.fields` chunks at 10. These are
-  400s from `chat.postMessage`, not fidelity gaps.
-- `renderElement` switches over all TWELVE element types, not the eleven
-  `supports` admits. The declined arm is unreachable; writing it out is what makes
-  the compiler prove the two lists agree. Do not collapse it into a `default` —
-  that would silently swallow a thirteenth member of the union.
-- A `callToAction` with no `href` becomes a code block, never a button. `href`
-  absent means the label IS the payload (an OTP code); a button with no
-  destination is a lie about what the notification is asking for.
-- `metadata.title` is spent TWICE and neither use replaces the other:
-  `SlackMessage.text` is the fallback Slack shows where blocks cannot render (a
-  push notification, a screen reader), and the `header` block is what the message
-  looks like. It is the same content-level fact email spends as its subject —
-  three channel uses of one fact, which is why it lives on the content rather than
-  in a channel's registry. Only the block carries the 150-char limit; the fallback
-  is untruncated.
+- **`assertNever`, not `supports`, is what protects the next element.** With
+  `supports` total-true it can no longer be the guard: an unmapped thirteenth
+  element would fall through and post a message with a hole in it — the `chatUnit`
+  bug under a new name, and harder to see, because there would be no `supports`
+  returning false to point at. `renderElement` therefore has NO `default` arm and
+  ends in `assertNever`, so adding a variant fails compilation until someone
+  chooses how Slack says it.
+- **There is no mrkdwn surface here, and that is a safety property.** Escaping
+  used to be a per-call-site rule: `mrkdwn` parses `&`/`<`/`>` and had to be
+  escaped, `plain_text` and `rich_text` are literal and had to NOT be. Both
+  mistakes were possible and neither was a type error, because both surfaces are
+  `string`. Moving the body to `rich_text_preformatted` retired the last mrkdwn
+  emitter, so `escapeMrkdwn`, `mrkdwn`, `section` and `context` were DELETED
+  rather than kept in case — a helper that exists is one someone will reach for,
+  and reaching for that one is now always the bug.
+- **No empty `rich_text_preformatted`, ever.** Slack draws one as a visible empty
+  rectangle, so a break-out at the head or tail of a chat unit must not leave a
+  zero-line box beside the button. `./chat.ts` merges segments and then filters.
+- **Adjacent linked CTAs coalesce** into one `actions` block. Two buttons in one
+  block sit side by side the way a reader expects a choice; two blocks stack them
+  and read as two unrelated prompts. Slack caps a block at 25 elements.
+- A `callToAction` with no `href` is drawn, never made a button. `href` absent
+  means the label IS the payload (an OTP code); a button with no destination is a
+  lie about what the notification is asking for.
+- Slack's documented limits are enforced here, not left to the API: an `actions`
+  block splits at 25 elements. The header's 150-char cap left with the header
+  block.
 - 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`.
 - This channel is unreachable from `../../render.ts`'s `renderEmail` and touches
   no parity fixture. It cannot change a sent email, and it must not acquire the
   ability to.
+
+## The blocks are Slack's, not ours
+
+`SlackMessage.blocks` is `KnownBlock[]` from **`@slack/types`** — the published
+type package behind `node-slack-sdk`, so it is the same union Slack's API
+validates against. `index.ts` re-exports the block types it uses, so a consumer can
+name them without taking its own dependency on `@slack/types`. Widen that list
+rather than redeclaring a shape.
+
+The field names are snake_case (`image_url`, `alt_text`) because Block Kit is a
+wire format and those are its names. That is deliberate, not a lapse in the repo's
+camelCase convention.
+
+## What is still non-functional
+
+- **It does not send.** No token, no channel id, no `chat.postMessage`. A renderer
+  renders; delivery and the decision to deliver are the backend's —
+  `SlackChannelDelivery` throws `ChannelNotImplementedError` by design.
+- **The copy is invented**, not relocated from a shipped Slack app. The SHAPE is
+  legitimate Block Kit and `__tests__/index.test.ts` pins it; the WORDING is
+  expected to change when a kind is actually posted to Slack.

package/src/notifications/renderers/slack/__tests__/README.md

@@ -10,8 +10,9 @@ not pin the Block Kit wording. They pin the contract a placeholder still owes:
 read from `RenderContext`, and a content carrying all twelve element types
 rendering without throwing.
 
-One exception: the mrkdwn escaping IS pinned exactly. Everything else here is a
-fidelity gap that a real Slack kind will close; unescaped user input would be a
+One exception: the ABSENCE of an mrkdwn surface is pinned exactly. Everything
+else here is a fidelity gap that a real Slack kind will close; escaped user input
+reaching a literal surface would be a
 real defect shipped in a published package.
 
 ## Invariants