feat: add data_table block support and surface-rule drift check

Reconciles the validator's surface rules with Slack's canonical
blocks.json (https://docs.slack.dev/blocks.json) per ENG-5108.

- Model the `data_table` block (distinct from `table`): full schema
  with raw_text / raw_number / rich_text cells, row/column/page_size
  bounds, plus BLOCK_TYPE_TO_DEF entry, generated types, and tests.
- Surface rules: `data_table` is forbidden on modal/home, mirroring
  `table`'s empirically confirmed messages-only render behavior
  (blocks.json lists Home tabs, but the table family drops there).
- Add test/surface-drift.test.ts: diffs the forbidden-by-surface sets
  against a committed blocks.json snapshot so the rules can't silently
  diverge. The four intentional deviations (card/modal, file/message,
  table/home, data_table/home) are pinned in an explicit allowlist.
- Document the card and file deviations inline against blocks.json.
- Add a valid data_table demo preset and update README coverage.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: StephenTangCook

README.md

@@ -141,7 +141,7 @@ Each returns an array of human-readable error strings — empty when valid.
 
 ## Coverage
 
-- **20 blocks**: actions, alert, card, carousel, container, context, context_actions, data_visualization, divider, file, header, image, input, markdown, plan, rich_text, section, table, task_card, video.
+- **21 blocks**: actions, alert, card, carousel, container, context, context_actions, data_table, data_visualization, divider, file, header, image, input, markdown, plan, rich_text, section, table, task_card, video.
 - **All block elements**: button, icon_button, workflow_button, feedback_buttons, plain_text / email / url / number inputs, datepicker, datetimepicker, timepicker, file_input, rich_text_input, checkboxes, radio_buttons, image, overflow, url source, and all 5 single + 5 multi-select menu variants.
 - **All 9 composition objects**: text (plain_text + mrkdwn), confirm, option (3 contextual variants), option_group, slack_file, dispatch_action_config, conversation_filter, trigger, workflow.
 - **Rich text**: 4 container kinds (section, list, preformatted, quote) + 10 leaf kinds (text, link, user, usergroup, team, channel, emoji, broadcast, color, date) with style flags.

demo/src/presets.ts

@@ -237,6 +237,38 @@ const twoTables = stringify([
   },
 ]);
 
+const dataTableLeaderboard = stringify([
+  {
+    type: "header",
+    text: { type: "plain_text", text: "Contributor leaderboard" },
+  },
+  {
+    type: "data_table",
+    caption: "Merged PRs by contributor this sprint",
+    page_size: 10,
+    rows: [
+      [
+        { type: "raw_text", text: "Contributor" },
+        { type: "raw_text", text: "Merged PRs" },
+        { type: "raw_text", text: "Status" },
+      ],
+      [
+        { type: "raw_text", text: "ana" },
+        { type: "raw_number", value: 12, text: "12" },
+        {
+          type: "rich_text",
+          elements: [{ type: "rich_text_section", elements: [{ type: "text", text: "on track", style: { bold: true } }] }],
+        },
+      ],
+      [
+        { type: "raw_text", text: "zach" },
+        { type: "raw_number", value: 9, text: "9" },
+        { type: "raw_text", text: "on track" },
+      ],
+    ],
+  },
+]);
+
 const activeUsersChart = stringify([
   {
     type: "header",
@@ -1013,6 +1045,14 @@ export const presets: Preset[] = [
     tone: "invalid",
     json: threeCharts,
   },
+  {
+    id: "data-table",
+    label: "Data table block",
+    surface: "message",
+    blurb: "Interactive `data_table` with raw_text, raw_number, and rich_text cells.",
+    tone: "valid",
+    json: dataTableLeaderboard,
+  },
   {
     id: "markdown-overflow",
     label: "Cumulative markdown > 12k",

src/helpers/check-surface-compatibility.ts

@@ -8,25 +8,29 @@ export type Surface = "message" | "modal" | "home";
 // that powers the "Surfaces" column on each block's reference page. Every
 // block entry there has an `available-in-surfaces` array valued with some
 // subset of ["Modals", "Messages", "Home tabs"]. Whatever's missing from
-// that array is what we forbid here.
-// `file` is only produced by Slack when retrieving messages that contain
-// remote files; apps cannot send it outbound on any surface
-// (https://docs.slack.dev/reference/block-kit/blocks/file-block:
-// "You can't add this block to app surfaces directly...").
+// that array is what we forbid here. `test/surface-drift.test.ts` diffs these
+// sets against a committed snapshot of blocks.json so this can't silently rot.
+//
+// Four entries below intentionally deviate from blocks.json — Slack's canonical
+// data lists a surface where the block doesn't actually render. Each is
+// empirically grounded and kept in the drift test's KNOWN_DEVIATIONS allowlist:
+//   • card / modals   — blocks.json lists Modals; fails to render there.
+//   • file / messages — inbound-only; apps can't send it outbound at all
+//     (https://docs.slack.dev/reference/block-kit/blocks/file-block:
+//     "You can't add this block to app surfaces directly...").
+//   • table / home tabs — blocks.json lists Home tabs; Tightknit testing shows
+//     the table block renders on messages only (modals and home drop it).
+//   • data_table / home tabs — same: blocks.json lists Home tabs, but as a
+//     table-family block it inherits table's messages-only behavior (mirrored
+//     for consistency, pending independent confirmation).
 const BLOCKS_NOT_ALLOWED_IN_MESSAGE = new Set(["alert", "file"]);
 
-// carousel/card are listed as modal-available in Slack's blocks.json but
-// empirically fail to render inside modal views — confirmed by the PR author
-// against the live API. They work in messages and home tabs.
-// `data_visualization` is a messages-only block — its reference page lists
-// "Available in Surfaces: Messages" only
-// (https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block).
-// Forbidden in both modals and home tabs.
 const BLOCKS_NOT_ALLOWED_IN_MODAL = new Set([
   "card",
   "carousel",
   "container",
   "context_actions",
+  "data_table",
   "data_visualization",
   "file",
   "markdown",
@@ -39,6 +43,7 @@ const BLOCKS_NOT_ALLOWED_IN_HOME = new Set([
   "alert",
   "container",
   "context_actions",
+  "data_table",
   "data_visualization",
   "file",
   "markdown",

src/slack-block-kit.schema.json

@@ -1352,6 +1352,69 @@
       ]
     },
 
+    "data_table_cell": {
+      "description": "A cell inside a data_table_block row. `raw_text` / `raw_number` for simple values, `rich_text` for formatted content. Per https://docs.slack.dev/reference/block-kit/blocks/data-table-block. The docs' per-cell schemas list `properties` without a `required` array; we mirror `table_cell` and require the value-bearing field(s). The rule 'the first (header) row cannot contain rich_text cells' is a row-position constraint JSON Schema can't express and is not enforced here.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "text"],
+          "properties": {
+            "type": { "const": "raw_text" },
+            "text": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "value"],
+          "properties": {
+            "type": { "const": "raw_number" },
+            "value": { "type": "number" },
+            "text": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "elements"],
+          "properties": {
+            "type": { "const": "rich_text" },
+            "elements": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/rich_text_container_element" }
+            }
+          }
+        }
+      ]
+    },
+
+    "data_table_block": {
+      "description": "Rich, interactive table with pagination, sorting, and filtering (https://docs.slack.dev/reference/block-kit/blocks/data-table-block). Distinct from `table_block`, which is a simpler static table. The single-table and aggregate 10,000-character limits are payload-level rules not enforced here. `row_header_column_index` must point at an existing column, a cross-field rule JSON Schema can't check (bounded to 0–19 since a row has at most 20 cells).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "caption", "rows"],
+      "properties": {
+        "type": { "const": "data_table" },
+        "block_id": { "$ref": "#/$defs/block_id" },
+        "caption": { "type": "string", "minLength": 1 },
+        "page_size": { "type": "integer", "minimum": 1, "maximum": 100 },
+        "row_header_column_index": { "type": "integer", "minimum": 0, "maximum": 19 },
+        "rows": {
+          "description": "First row is the header; 2–101 rows total (1 header + 1–100 data rows), 1–20 cells per row.",
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 101,
+          "items": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 20,
+            "items": { "$ref": "#/$defs/data_table_cell" }
+          }
+        }
+      }
+    },
+
     "data_visualization_block": {
       "description": "Renders data as a line, bar, area, or pie chart. Messages only (https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block). Slack renders at most two data_visualization blocks per message (enforced via the checkDataVisualizationMax helper, since JSON Schema can't count sibling blocks). Two further runtime rules are enforced via checkDataVisualizationConsistency, since they depend on sibling-field values JSON Schema can't compare: series names must be unique within a chart, and each series must contain exactly one data point per axis_config.categories label.",
       "type": "object",
@@ -1678,6 +1741,7 @@
         { "$ref": "#/$defs/container_block" },
         { "$ref": "#/$defs/context_actions_block" },
         { "$ref": "#/$defs/context_block" },
+        { "$ref": "#/$defs/data_table_block" },
         { "$ref": "#/$defs/data_visualization_block" },
         { "$ref": "#/$defs/divider_block" },
         { "$ref": "#/$defs/file_block" },