slackblock 1.1.0 → 2.0.0-beta.1

package/CHANGELOG.md

@@ -1,6 +1,58 @@
 # Changelog
 
+## 2.0.0-beta.1
+
+### Patch Changes
+
+- 2dc3b09: Fixes included files
+
+## 2.0.0-beta.0
+
+### Major Changes
+
+- e243699: ---
+
+  React dependency removed — migrate jsxImportSource to "slackblock"
+
+  In your tsconfig.json, change:
+  "jsxImportSource": "react" → "jsxImportSource": "slackblock"
+
+  Remove react / react-dom from your dependencies. No JSX syntax changes required.
+
+  ***
+
+  Breaking changes:
+  - React peer dependency dropped; replaced with a zero-dependency custom JSX runtime
+  - @slack/web-api runtime dependency removed; Slack types are now bundled locally
+  - Node.js >=20 required (previously >=18 was tolerated in practice)
+  - render() now defaults to validate: 'warn', emitting console warnings when output
+    would violate Slack Block Kit limits (text too long, too many options, etc.).
+    Pass { validate: 'off' } to suppress all warnings.
+
+  New API:
+  - renderToBlocks(element, options?) — returns Block[] directly; use for modals and
+    home tabs where no <Message> wrapper is needed. Fragments are unwrapped transparently.
+  - renderToMessage(element, options?) — named alias for render(); both are equivalent.
+  - blockKitBuilderUrl(blocks) — generates a Block Kit Builder preview URL for a block array.
+  - escapeMrkdwn(text) — escapes Slack mrkdwn special characters in plain text strings.
+  - validate option on render() / renderToBlocks() / renderToMessage():
+    'warn' (default) — console.warn on limit violations
+    'strict' — throws SlackblockValidationError on any violation
+    'off' — no validation
+  - SlackblockValidationError — structured error with .path, .rule, and .message fields.
+  - RenderOptions and ValidationMode types exported from package root.
+
+  Other improvements:
+  - strictNullChecks enabled; zero `any` types in source
+  - All public components and render functions have JSDoc
+  - Component reference at docs/components.md
+  - Validation guide at docs/validation.md
+  - Migration guides from jsx-slack and slack-block-builder at docs/migrating-\*.md
+  - 12 Block Kit JSON samples in examples/block-kit/ covering all validatable components
+  - Changesets-based release automation with npm provenance
+
 ### 1.1.0
+
 - Drop `@slack/web-api` runtime dependency; types replicated locally
 - Lower Node engine requirement to `>=20` (from `>=24`)
 - Add CI matrix for Node 20, 22, and 24
@@ -11,6 +63,7 @@
 - Fix publish hygiene: delete `.npmignore`, rename `prepublish` → `prepublishOnly`
 
 ### 1.0.1
+
 - Upgrade `@slack/web-api` to 7.14.1 (resolves CVE-2026-25639 via axios upgrade)
 - Bump `rollup` to 4.59.0 (resolves CVE-2026-27606)
 - Bump `minimatch` to 10.2.3+ (resolves CVE-2026-27904, CVE-2026-27903, CVE-2026-26996)
@@ -18,6 +71,7 @@
 - Resolve CVE-2026-25547 via minimatch 10.2.3+ (replaces @isaacs/brace-expansion)
 
 ### 1.0.0
+
 - Modernize tooling (Node 24, pnpm, tsup, Vitest, XO, Husky + lint-staged)
 - Stabilize parser/transformer routing and align output types to serialized JSON
 - Expand Block Kit coverage (header, rich_text, video, checkboxes, time/datetime pickers)
@@ -25,26 +79,34 @@
 - Add validation warnings for Slack limits
 
 ### 0.4.0
+
 - Allow for `<Section/>` blocks to have `null` components (useful for conditional renders)
 
 ### 0.3.1
+
 - Fix issue that caused an error to be thrown if a child is `null`
 
 ### 0.3.0
+
 - Add `Container` block to allow for better conditional rendering
 
 ### 0.2.0
+
 - Add ability to color messages
 
 ### 0.1.0
+
 - Add all additional props to the top level `<Message/>` component
 - Remove `token` / `channel` prop since they are out of scope for the component
 
 ### 0.0.4
+
 - Fix issue where `<Actions/>` block would have incorrect type
 
 ### 0.0.3
+
 - Fix issue where `<Button/>` element was outputting `actionId` when it should be `action_id`
 
 ### 0.0.1 / 0.0.2
+
 - Initial release

package/README.md

@@ -1,95 +1,254 @@
 # SlackBlock
-JSX-based Slack message renderer
+
+JSX-based Slack Block Kit message renderer
 
 [![CI](https://github.com/kolyaventuri/block/actions/workflows/ci.yml/badge.svg)](https://github.com/kolyaventuri/block/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/slackblock)](https://www.npmjs.com/package/slackblock)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/types-included-blue)](https://www.typescriptlang.org/)
+
+Build Slack messages with JSX. No React required — SlackBlock ships its own lightweight JSX runtime. Write your blocks as components, call `render()`, and post the result straight to the Slack API.
+
+---
+
+## Compatibility
+
+| | Supported |
+|---|---|
+| Node.js | `>= 20` |
+| TypeScript | `>= 5.0` |
+| React | Not required — uses a built-in JSX runtime |
+
+---
+
+## Install
+
+```sh
+npm install slackblock
+# or
+pnpm add slackblock
+# or
+yarn add slackblock
+```
+
+---
 
-## What
-A message builder for Slack bots, using JSX with a React-compatible API. Generally follows the [Block Kit](https://api.slack.com/block-kit) naming and options.
+## TypeScript setup
 
-## Getting started
-Install the library with your package manager, for example `pnpm add slackblock`.
+Add the following options to your `tsconfig.json`:
 
-- Import the renderer with `import render from 'slackblock';`
-- Import the top level `Message` block, along with any blocks you need from `import { Message, Section, Text, ... } from 'slackblock/block';`
-- Build your message!
-```jsx
-/* example */
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "slackblock"
+  }
+}
+```
+
+This tells TypeScript to use SlackBlock's built-in JSX runtime instead of React.
+
+---
+
+## Quick start
 
-const text = <Text plainText>Hello</Text>;
+```tsx
+import render from 'slackblock';
+import { Message, Section, Text, Header, Divider, Actions, Button } from 'slackblock/block';
 
 const message = render(
-  <Message>
-    <Section text={text}>
-      <Text>Some *message* for _Slack_.</Text>
-    </Section>
+  <Message text="Deployment complete">
+    <Header text="Deploy finished" />
+    <Section text={<Text>Service *api* deployed to production.</Text>} />
+    <Divider />
+    <Actions>
+      <Button actionId="view_logs" url="https://example.com/logs">View logs</Button>
+      <Button actionId="rollback" style="danger">Rollback</Button>
+    </Actions>
   </Message>
 );
 
-console.log(message);
-/*
-  {
-    "blocks": [
-      {
-        "type": "section",
-        "text": {
-          "type": "plain_text",
-          "text": "Hello"
-        },
-        "fields": [
-          {
-            "type": "mrkdwn",
-            "text": "Some *message* for _Slack_."
-          }
-        ]
-      }
-    ]
+// message is ready to post — just add your channel:
+await slackClient.chat.postMessage({ channel: '#deploys', ...message });
+```
+
+The rendered output is a plain object you can spread directly into `chat.postMessage`.
+
+---
+
+## API
+
+### `render(element, options?)` — default export
+
+Renders a `<Message>` tree to a full Slack message payload.
+
+```ts
+import render from 'slackblock';
+
+const message = render(<Message text="Hello">...</Message>);
+// → { text: "Hello", blocks: [...] }
+```
+
+The top-level element must be a `<Message>`. Throws a `TypeError` otherwise.
+
+### `renderToMessage(element, options?)`
+
+Named alias for `render`. Use whichever reads more naturally in your codebase.
+
+```ts
+import { renderToMessage } from 'slackblock';
+```
+
+### `renderToBlocks(element, options?)`
+
+Renders any JSX element (or fragment) directly to a `Block[]` array, without a `<Message>` wrapper. Useful for modals and home tabs, which accept a `blocks` array rather than a full message payload.
+
+```tsx
+import { renderToBlocks } from 'slackblock';
+import { Section, Text } from 'slackblock/block';
+
+const blocks = renderToBlocks(
+  <>
+    <Section text={<Text>Hello from a modal</Text>} />
+  </>
+);
+// → [{ type: "section", text: { type: "mrkdwn", text: "Hello from a modal" } }]
+```
+
+### `blockKitBuilderUrl(blocks)`
+
+Returns a [Block Kit Builder](https://app.slack.com/block-kit-builder) URL for the given blocks. Open it in a browser to preview layout and interactivity during development.
+
+```ts
+import { renderToBlocks, blockKitBuilderUrl } from 'slackblock';
+
+const blocks = renderToBlocks(<Section text={<Text>Hello</Text>} />);
+console.log(blockKitBuilderUrl(blocks));
+// → https://app.slack.com/block-kit-builder#{"blocks":[...]}
+```
+
+### `escapeMrkdwn(text)`
+
+Escapes Slack mrkdwn special characters (`*`, `_`, `~`, `` ` ``, `>`, `&`, `<`, `>`) in a string. Use this when inserting untrusted user content into a mrkdwn text field.
+
+```ts
+import { escapeMrkdwn } from 'slackblock';
+
+const safe = escapeMrkdwn(userInput); // "hello *world*" → "hello \*world\*"
+```
+
+### Options
+
+Both `render` / `renderToMessage` / `renderToBlocks` accept an optional `options` object:
+
+```ts
+type RenderOptions = {
+  validate?: 'off' | 'warn' | 'strict'; // default: 'warn'
+};
+```
+
+See [docs/validation.md](docs/validation.md) for details.
+
+---
+
+## Validation
+
+SlackBlock validates your message against Slack's documented limits and required fields. The `validate` option controls what happens when a violation is detected:
+
+| Mode | Behavior |
+|------|----------|
+| `'warn'` (default) | Logs a warning to `console.warn`; rendering continues |
+| `'strict'` | Throws a `SlackblockValidationError` |
+| `'off'` | No validation |
+
+```tsx
+// Throw on any violation — recommended for tests
+const message = render(<Message>...</Message>, { validate: 'strict' });
+```
+
+```ts
+import { SlackblockValidationError } from 'slackblock';
+
+try {
+  render(<Message>...</Message>, { validate: 'strict' });
+} catch (err) {
+  if (err instanceof SlackblockValidationError) {
+    console.error(err.message); // "Message > Header: Header text exceeds 150 characters."
+    console.error(err.path);    // ["Message", "Header"]
+    console.error(err.rule);    // "too-long"
   }
-*/
+}
+```
+
+See [docs/validation.md](docs/validation.md) for the full rule reference.
+
+---
+
+## Conventions
+
+**camelCase props** — Slack's API uses `snake_case`; SlackBlock uses `camelCase` props that map to the correct API fields:
+
+```tsx
+// Slack API: { "block_id": "...", "action_id": "..." }
+<Button blockId="my_block" actionId="my_action">Click me</Button>
+```
+
+**Children as fields** — When Slack expects an array (e.g. select options, section fields), pass them as JSX children:
+
+```tsx
+<Select placeholder="Pick one" actionId="pick">
+  <Option value="a">Option A</Option>
+  <Option value="b">Option B</Option>
+</Select>
 ```
 
-There is a `<Container/>` component, which allows for conditional rendering by passing through the children as though it didn't exist.
-```jsx
-const elem = (
+**Conditional rendering** — Use `<Container>` to wrap elements that may or may not render, or use standard JS short-circuit expressions:
+
+```tsx
+<Message text="Hello">
+  {isAdmin && <Section text={<Text>Admin panel</Text>} />}
   <Container>
-    <Text>Test</Text>
+    {items.map(item => <Section key={item.id} text={<Text>{item.name}</Text>} />)}
   </Container>
-);
+</Message>
+```
 
-const shouldDoThing = ...;
+**Color / attachment** — Setting `color` on `<Message>` wraps blocks in a legacy attachment for the colored left border. `color` accepts any hex value or Slack named colors:
 
-const message = render(
-  <Message>
-    {shouldDoThing && elem}
-  </Message>
-);
+```tsx
+<Message text="Alert" color="#ff0000">
+  <Section text={<Text>Something went wrong.</Text>} />
+</Message>
 ```
 
-## Things to note
-- The outputted message only needs to have your `token` and desired `channel_id` added, and it will be ready to send to the slack API!
-- React is a peer dependency and used only as a JSX runtime (no DOM renderer required).
-- There is limited input validation (for example, date/time formats and select constraints). Warnings are emitted for common Slack limits (IDs, text lengths, block counts). Non-recognized blocks will be ignored, but Slack will be the ultimate decider if your message is valid. Validation is on the roadmap.
-- There is currently almost no documentation. This will be resolved, but in general...
-  - If a Slack message wants a property in format `foo_bar`, you will add it as a `fooBar` property in your message(ex: `<Element fooBar='blah'/>`)
-  - If a component such as a `<Section/>` wants fields which seem like children, they probably are for the sake of rendering. This is especially important with `select` menus, as your `<Option/>` tags will be passed as children
-    - ex:
-     ```jsx
-       <Select ...>
-         <Option value="val">text</Option>
-         <Option value="val2">text2</Option>
-       </Select>
-     ``` 
+---
+
+## Supported components
+
+**Layout blocks:** `Message`, `Section`, `Actions`, `Context`, `Divider`, `File`, `Header`, `Image` (block), `Input`, `RichText`, `Video`
+
+**Block elements:** `Text`, `Image` (element), `Button`, `Confirmation`
+
+**Input elements:** `Select`, `Option`, `OptionGroup`, `Overflow`, `Checkboxes`, `RadioGroup`, `TextInput`, `DatePicker`, `TimePicker`, `DateTimePicker`
+
+**Rich text helpers:** `RichTextSection`, `RichTextList`, `RichTextQuote`, `RichTextPreformatted`, `RichTextText`, `RichTextLink`, `RichTextUser`, `RichTextChannel`, `RichTextEmoji`, `RichTextDate`, `RichTextBroadcast`, `RichTextUserGroup`
+
+**Utility:** `Container`
+
+See [docs/components.md](docs/components.md) for the full props reference.
 
-## Supported blocks and elements
-Blocks: `Message` (top-level), `Section`, `Actions`, `Context`, `Divider`, `File`, `Image` (block), `Header`, `Input`, `RichText`, `Video`.
+---
 
-Elements: `Text`, `Image` (element), `Button`, `Confirmation`, `Select`, `Option`, `OptionGroup`, `Overflow`, `RadioGroup`, `Checkboxes`, `DatePicker`, `TimePicker`, `DateTimePicker`, `TextInput`.
+## Further reading
 
-Rich text helpers: `RichTextSection`, `RichTextList`, `RichTextQuote`, `RichTextPreformatted`, `RichTextText`, `RichTextLink`, `RichTextUser`, `RichTextChannel`, `RichTextEmoji`, `RichTextDate`, `RichTextBroadcast`, `RichTextUserGroup`.
+- [Component reference](docs/components.md) — all components with props tables
+- [Validation guide](docs/validation.md) — validation modes and error handling
+- [Migrating from jsx-slack](docs/migrating-from-jsx-slack.md)
+- [Migrating from slack-block-builder](docs/migrating-from-slack-block-builder.md)
+- [Slack Block Kit reference](https://api.slack.com/block-kit)
 
-Field support highlights: `select` filters/min query length, `option` description, `focusOnLoad` for inputs, `dispatchActionConfig` for text inputs, and `accessibilityLabel` on buttons.
+---
 
+## License
 
-## TODO
-- Add real documentation
-- Add validation
-- Add richer rich_text validation
+MIT