@tightknitai/block-kitchen 0.9.9 → 0.10.0

package/README.md

@@ -105,11 +105,15 @@ export function MyBuilderPage() {
 | `workspaceName` | `string` | no | Shown in the preview chrome to mimic a real Slack message header. |
 | `initialBlocks` | `SupportedBlock[]` | no | Starting draft. If omitted, the builder starts empty. |
 | `onChange` | `(blocks: SupportedBlock[]) => void` | no | Fires on every state change. Use this to persist the draft (URL, localStorage, etc). |
-| `loadChannels` | `() => Promise<{ id: string; name: string }[]>` | yes | Returns channels available to send to. The package never makes Slack API calls itself. |
-| `loadSendAsUserStatus` | `() => Promise<{ canSendAsUser: boolean; oauthUrl?: string }>` | yes | Whether the current user has a Slack user-token and can post as themselves. If `canSendAsUser` is false, `oauthUrl` is shown as a "Sign in with Slack" link. |
-| `onSend` | `(payload) => Promise<{ ok: boolean; error?: string }>` | yes | Called when the user submits the send dialog. Payload is `{ channelId, blocks, sendAsUser }`. |
-| `editing` | `{ onLoadMessage, onUpdate, loadRecentMessages? }` | no | Opt-in edit mode. When present, the toolbar exposes "Edit message": the user pastes a Slack message link, `onLoadMessage({ link })` returns a host-computed [editability verdict](#editing-an-existing-message-opt-in), and a successful load flips the primary action to "Update message" wired to `onUpdate`. Pass `loadRecentMessages` to add a "recent messages from this app" picker beside the paste input; the user picks a channel first (reusing `loadChannels`) and the lookup is scoped to it. Omit `editing` to keep send-only behavior. |
-| `loadButtonLabel` | `string` | no | Label + accessible name for the toolbar button that opens the load-message dialog (the edit-mode entry point). Defaults to `'Load message'`. Only shown when `editing` is set and no message is loaded. |
+| `onValidationChange` | `(summary: ValidationSummary) => void` | no | Fires when the draft's validation verdict changes (debounced alongside the builder's own validation pass — not on every keystroke). `summary` is `{ valid, errorCount, errors }`: the exact verdict the issues chip/sheet shows, always scoped to the `message` surface. Lets a host-owned CTA gate on validity in [compose-only mode](#compose-only-mode-bring-your-own-send-flow) without re-running the validator. |
+| `loadChannels` | `() => Promise<{ id: string; name: string }[]>` | grouped\* | Returns channels available to send to. The package never makes Slack API calls itself. |
+| `loadSendAsUserStatus` | `() => Promise<{ canSendAsUser: boolean; oauthUrl?: string }>` | grouped\* | Whether the current user has a Slack user-token and can post as themselves. If `canSendAsUser` is false, `oauthUrl` is shown as a "Sign in with Slack" link. |
+| `onSend` | `(payload) => Promise<{ ok: boolean; error?: string }>` | grouped\* | Called when the user submits the send dialog. Payload is `{ channelId, blocks, sendAsUser, extras? }` (`extras` only when `renderSendExtras` is wired). |
+| `renderSendExtras` | `(ctx: SendExtrasContext) => ReactNode` | no | Renders host-defined fields inside the built-in send dialog, below the channel and identity pickers. Collect values with `ctx.setExtras(patch)`; they arrive on `onSend` as `payload.extras`. Requires the send trio. See [Extending the send dialog](#extending-the-send-dialog-custom-fields). |
+| `primaryAction` | `{ label, onClick, disableWhenInvalid? }` | no | Compose-only mode only: a host-owned button in the toolbar slot where "Review & send" normally sits. `onClick` receives `{ blocks, validation, loadedMessage }` — the current draft, the same verdict `onValidationChange` reports, and the currently [loaded message](#loading-an-existing-message-opt-in) (`null` unless `loading` is configured and one is loaded). See [Keeping the CTA in the toolbar](#keeping-the-cta-in-the-toolbar-primaryaction). |
+| `loading` | `{ onLoadMessage, loadRecentMessages?, loadChannels?, initialTarget?, onLoadedMessageChange? }` | no | Opt-in: [load an existing message](#loading-an-existing-message-opt-in) into the editor. Adds a "Find message" toolbar entry — the user pastes a Slack permalink (or picks a recent message) and the draft is hydrated with its blocks. Loading is a *composition* concern, so it works in **both** send mode and compose-only mode. `onLoadedMessageChange` reports the loaded target (`null` on exit) so a host-owned commitment step can stay in sync. |
+| `onUpdate` | `(payload) => Promise<{ ok: boolean; error?: string }>` | no | Opt-in update-in-place mode (send mode only); sibling to `onSend`, but the payload carries the source `channel + ts`. With `loading` configured, a loaded message flips the primary action to a "Review & update" split button wired to it (`chat.update`). |
+| `loadButtonLabel` | `string` | no | Label + accessible name for the toolbar button that opens the load-message dialog. Defaults to `'Find message'`. Only shown when `loading` is configured. |
 | `updateButtonLabel` | `string` | no | Label for the toolbar's primary button while a message is loaded for editing. It's a split button: clicking it updates the message in place; the menu beside it also offers "Send as a new message" (post the current blocks as new). Defaults to `'Review & update'`. |
 | `confirmUpdateLabel` | `string` | no | Label for the update dialog's final confirm button. Defaults to `'Update message'` (shows `'Updating…'` while in flight). |
 | `previewHooks` | `PreviewHooks` | no | Hooks forwarded to `slack-blocks-to-jsx`'s `<Message>` for resolving user / channel / emoji directives. |
@@ -127,17 +131,184 @@ export function MyBuilderPage() {
 | `confirmSendLabel` | `string` | no | Label for the send dialog's final confirm button. Defaults to `'Send'` (shows `'Sending…'` while in flight). |
 | `theme` | `BrandTheme \| BrandPreset` | no | Branding tokens applied to the builder chrome (toolbar, palette, popovers, dialogs). Accepts a `Partial<BrandTokens>` map and optional `light`/`dark` overrides. See [Styling](#styling) below. |
 
-## Editing an existing message (opt-in)
+\* The send trio — `loadChannels`, `loadSendAsUserStatus`, `onSend` — is
+all-or-nothing: provide all three for the built-in send flow, or omit all
+three for [compose-only mode](#compose-only-mode-bring-your-own-send-flow)
+(no send button; your app owns the send flow). Wiring only some of the three
+is a type error. `onUpdate` and `renderSendExtras` require the trio;
+`primaryAction` requires its absence (the built-in Send/Update flow owns the
+toolbar's primary slot otherwise). `loading` is mode-agnostic — it works
+with or without the trio.
 
-By default the builder is send-only. Pass `editing` to let users load an
-already-posted message, edit its blocks, and dispatch a `chat.update`. The
+## Compose-only mode (bring your own send flow)
+
+Omit the send trio entirely and the builder renders no send button — it
+becomes a pure Block Kit editor. This is the right shape when composing is
+one step in a flow your app owns (a wizard, an audience picker, a scheduler):
+the package owns *composition* (authoring, preview, validation UX) and your
+app owns *distribution* (audiences, identity, scheduling, delivery). The
+only thing that crosses the boundary is the blocks array.
+
+Mirror the draft with `onChange`, gate your own CTA with
+`onValidationChange`, and hand `toSlackBlocks(draft)` to whatever comes next:
+
+```tsx
+import { useState } from "react";
+import {
+  BlockKitchen,
+  toSlackBlocks,
+  type SupportedBlock,
+  type ValidationSummary,
+} from "@tightknitai/block-kitchen";
+
+function ComposeStep({ onNext }: { onNext: (blocks: SupportedBlock[]) => void }) {
+  const [draft, setDraft] = useState<SupportedBlock[]>([]);
+  const [validation, setValidation] = useState<ValidationSummary | null>(null);
+
+  return (
+    <>
+      <BlockKitchen onChange={setDraft} onValidationChange={setValidation} />
+      {/* Your CTA, your copy, your placement — gated on the builder's own verdict. */}
+      <button
+        disabled={draft.length === 0 || validation?.valid === false}
+        onClick={() => onNext(toSlackBlocks(draft))}
+      >
+        Next: choose audience
+      </button>
+    </>
+  );
+}
+```
+
+Notes:
+
+- The rest of the toolbar (Clear, View JSON, the issues chip, theme/surface
+  controls) is unchanged — users can still inspect problems in the issues
+  sheet; only the moment of commitment moves into your app.
+- `onValidationChange` reports the same verdict the issues sheet displays
+  (validated against the `message` surface, like Send), so your CTA and the
+  in-builder issue count can never disagree.
+- [Loading an existing message](#loading-an-existing-message-opt-in) works
+  here too — pass `loading` and the "Find message" entry appears. The loaded
+  target (channel + ts + editability verdict) reaches your app via
+  `primaryAction`'s `loadedMessage` context and
+  `loading.onLoadedMessageChange`, so your own commitment step can offer
+  "update in place" alongside "post as new".
+- The built-in *update* flow (`onUpdate`) is unavailable in compose-only
+  mode: dispatching a `chat.update` is inherently bound to a channel +
+  timestamp + token, so it only exists alongside the send integration.
+
+### Keeping the CTA in the toolbar (`primaryAction`)
+
+The example above renders its CTA outside the builder. If you want the button
+to sit where "Review & send" normally sits — say a message drafter whose
+primary action is "Save template" — pass `primaryAction`:
+
+```tsx
+<BlockKitchen
+  primaryAction={{
+    label: "Save template",
+    onClick: ({ blocks, validation }) => openSaveModal(blocks, validation),
+    // Send-style gating is opt-in. Default is enabled-while-invalid: a
+    // drafter usually allows committing a work-in-progress draft and
+    // surfaces the verdict in its own flow instead.
+    disableWhenInvalid: false,
+  }}
+/>
+```
+
+`onClick` receives the current draft in the builder's native format (the same
+shape `onChange` reports — persist that to re-open the draft later; run it
+through `toSlackBlocks` for the Slack-ready payload) plus the validation
+verdict `onValidationChange` would report. The button is never disabled for
+an empty draft; gate on `blocks.length` in `onClick` if you need that.
+
+### Building a bespoke send flow from the exported primitives
+
+If your custom flow ends in something send-shaped, you don't have to rebuild
+the built-in dialog's machinery — the send-flow primitives are exported:
+
+- `SendDialog` — the built-in dialog as a standalone component
+  (`SendDialogProps`): channel loading/error states, bot-vs-user identity
+  picker, OAuth hand-off, in-flight and failure states. Mount it against your
+  own trigger.
+- `useSlackSignIn(loadStatus, { open, enabled })` — the OAuth sign-in state
+  machine behind the identity picker: fetches user-token status on open,
+  refreshes on window focus, and background-polls after the OAuth tab opens
+  until the token appears.
+- `SlackSignInButton` — the "Sign in with Slack" button with its polling
+  spinner, for wiring `useSlackSignIn` into your own dialog.
+
+## Extending the send dialog (custom fields)
+
+When the built-in send flow is *almost* right — you want the channel picker,
+identity picker, and sending states, plus a few controls of your own (a
+cross-post toggle, a custom sender name) — pass `renderSendExtras` instead of
+rebuilding the dialog. It renders below the built-in fields, and whatever you
+collect via `setExtras` arrives on `onSend` as `payload.extras`:
+
+```tsx
+<BlockKitchen
+  loadChannels={loadChannels}
+  loadSendAsUserStatus={loadSendAsUserStatus}
+  renderSendExtras={({ extras, setExtras }) => (
+    <>
+      <label>
+        <input
+          type="checkbox"
+          checked={Boolean(extras.alsoPostToIntranet)}
+          onChange={(e) => setExtras({ alsoPostToIntranet: e.target.checked })}
+        />
+        Also publish to the intranet
+      </label>
+      <label>
+        Custom sender name
+        <input
+          type="text"
+          value={String(extras.senderName ?? "")}
+          onChange={(e) => setExtras({ senderName: e.target.value })}
+        />
+      </label>
+    </>
+  )}
+  onSend={async ({ channelId, blocks, sendAsUser, extras }) => {
+    await api.send({ channelId, blocks, sendAsUser, ...extras }); // your code
+    return { ok: true };
+  }}
+/>
+```
+
+Notes:
+
+- The `extras` object is owned by the dialog: it resets every time the dialog
+  opens (alongside the channel and identity pickers), and `setExtras(patch)`
+  shallow-merges. Render controlled inputs from `extras`.
+- The context also carries the currently selected `channelId` (`null` until
+  channels load) and `sendAsUser`, so extras can react to them — e.g. only
+  offer cross-posting for certain channels.
+- `payload.extras` is present iff `renderSendExtras` is wired, so existing
+  `onSend` handlers never see a new key.
+- The dialog renders in a portal attached to `document.body`, so CSS that
+  relies on ancestor selectors from your app's DOM won't reach slot content —
+  style it directly (inline, CSS modules, utility classes).
+- For customizations that generalize something the dialog already models
+  (identities, channels), prefer proposing a first-class prop over routing
+  them through extras; the slot is for genuinely host-specific concerns.
+
+## Loading an existing message (opt-in)
+
+By default the builder starts from a blank canvas. Pass `loading` to let
+users load an already-posted message's blocks into the editor — paste a
+permalink, or pick from a "recent messages from this app" list. Loading is a
+*composition* concern, so it works in **both** send mode and
+[compose-only mode](#compose-only-mode-bring-your-own-send-flow). The
 package stays integration-agnostic: it makes no Slack calls and computes
 nothing about who can edit; the host does both.
 
 ```tsx
 <BlockKitchen
-  /* …send-only props… */
-  editing={{
+  /* …send trio, or nothing (compose-only)… */
+  loading={{
     // Host parses the pasted permalink, fetches the message, and returns a
     // verdict. `chat.update` only edits a message authored by the calling
     // token, so the host decides: bot message → 'bot', the user's own
@@ -155,17 +326,11 @@ nothing about who can edit; the host does both.
         return { ok: true, channelId: msg.channel, channelName: msg.channelName, ts: msg.ts, blocks: msg.blocks, editableVia: 'user', ...author };
       return { ok: false, reason: 'Only messages your app or you posted can be edited.', blocks: msg.blocks };
     },
-    // Sibling to onSend; carries the source channel + ts. `asUser` follows
-    // the verdict's `editableVia`.
-    onUpdate: async ({ channelId, ts, blocks, asUser }) => {
-      await chatUpdate({ channel: channelId, ts, blocks, asUser }); // your code
-      return { ok: true };
-    },
     // Optional: adds a "recent messages from this app" picker beside the paste
-    // input. The user first picks a channel (reusing `loadChannels`), then this
-    // is called with that `channelId` so the lookup scans only one channel.
-    // These are editable-by-construction (the app authored them), so picking one
-    // loads it straight into edit mode (no verdict needed).
+    // input. The user first picks a channel, then this is called with that
+    // `channelId` so the lookup scans only one channel. These are
+    // editable-by-construction (the app authored them), so picking one loads
+    // it directly (no verdict needed).
     loadRecentMessages: async (channelId) => {
       const msgs = await fetchRecentAppMessages(channelId); // your code
       return msgs.map((m) => ({
@@ -177,17 +342,68 @@ nothing about who can edit; the host does both.
         label: m.preview // one-line preview shown in the picker row
       }));
     }
+    // In send mode the recent picker's channel list reuses the send trio's
+    // `loadChannels`. In compose-only mode there is no trio — pass
+    // `loadChannels` here too, or the picker is hidden.
   }}
 />
 ```
 
-- On `ok`, the builder hydrates with `blocks`, shows an edit-mode badge, locks
-  the destination to the source channel, and fixes the post-as identity to
-  `editableVia` (the `'user'` path reuses `loadSendAsUserStatus` for the "Sign
-  in with Slack" gate).
+- On `ok`, the builder hydrates with `blocks` and shows a loaded banner
+  ("References an existing message in #channel"), with the author's
+  name/avatar in the preview header.
 - On `{ ok: false, reason }`, the load dialog renders the reason inline and
   offers **Open as a new message instead**. Pass `blocks` on the failure
   result to hydrate the draft for that fallback.
+- `loading.onLoadedMessageChange` reports the loaded target — and `null`
+  when the user exits it — so host state stays in sync (most useful in
+  compose-only mode, where your app owns what happens next). It can
+  **re-fire for the same `channelId` + `ts`** when the host's verdict or
+  metadata changed (e.g. `editableVia` flipping after a Slack sign-in), so
+  key host state on the full target, not `ts` alone.
+- The banner's **"Switch to a new message"** exit is mode-aware: in send
+  mode it clears the canvas and reopens the load dialog (the edit-centric
+  "pick a different message" flow); in compose-only mode it only detaches
+  the reference and **keeps the draft** — loading seeded a composition, and
+  a misclick must not destroy it.
+
+### Updating it in place (send mode)
+
+In send mode, pair `loading` with `onUpdate` to dispatch a `chat.update` for
+the loaded message. The primary action flips to a "Review & update" split
+button (the menu also offers "Send as a new message"), the destination is
+locked to the source channel, and the post-as identity is fixed to the
+verdict's `editableVia` (the `'user'` path reuses `loadSendAsUserStatus` for
+the "Sign in with Slack" gate).
+
+```tsx
+<BlockKitchen
+  /* …send trio… */
+  loading={{ onLoadMessage }}
+  // Sibling to onSend; carries the source channel + ts. `asUser` follows
+  // the verdict's `editableVia`.
+  onUpdate={async ({ channelId, ts, blocks, asUser }) => {
+    await chatUpdate({ channel: channelId, ts, blocks, asUser }); // your code
+    return { ok: true };
+  }}
+/>
+```
+
+With `loading` alone (no `onUpdate`), a loaded message can still be posted
+as a brand-new message via the regular Send flow — there's just no in-place
+update. In compose-only mode `onUpdate` doesn't exist; implement your own
+update against the target from `loadedMessage` / `onLoadedMessageChange`.
+
+> **Migrating from the pre-split `editing` bundle (≤ 0.9.x):** the load
+> fields move to `loading` unchanged, and `onUpdate` becomes a top-level
+> prop (the `editing` wrapper is gone).
+>
+> ```tsx
+> // Before
+> <BlockKitchen editing={{ onLoadMessage, onUpdate, loadRecentMessages }} />
+> // After
+> <BlockKitchen loading={{ onLoadMessage, loadRecentMessages }} onUpdate={onUpdate} />
+> ```
 
 ## Customizing the palette
 
@@ -225,9 +441,9 @@ Variant `id`s must be unique across the array — the drag-drop lookup keys by i
 
 ## Boundary
 
-The package is deliberately decoupled from any Slack SDK or backend. It does not import HTTP clients, OAuth libraries, or workspace-state systems. Everything I/O-shaped is brokered through props.
+The package is deliberately decoupled from any Slack SDK or backend. It does not import HTTP clients, OAuth libraries, or workspace-state systems. Everything I/O-shaped is brokered through props — and the send flow itself is optional: see [compose-only mode](#compose-only-mode-bring-your-own-send-flow) when your app owns the moment of commitment.
 
-Helpers also exported:
+Helpers and send-flow primitives also exported:
 
 ```ts
 import {
@@ -235,18 +451,31 @@ import {
   encodeBlocksToString,    // base64url-encode a blocks array (for URL state)
   decodeBlocksFromString,
   defaultPalette,          // the built-in palette — spread to customize
+  SendDialog,              // the built-in send dialog, standalone (bespoke send flows)
+  useSlackSignIn,          // the OAuth sign-in state machine behind the identity picker
+  SlackSignInButton,       // the "Sign in with Slack" button + polling spinner
 } from "@tightknitai/block-kitchen";
 
 import type {
   SupportedBlock,
   SupportedBlockType,
   BlockKitchenProps,
+  BlockKitchenBaseProps,        // shared props
+  BlockKitchenSendProps,        // the send trio + `onUpdate` + `renderSendExtras`
+  LoadingConfig,                // load an existing message (works in both modes)
+  LoadedMessage,                // the loaded target: channel + ts + verdict
+  BlockKitchenComposeOnlyProps, // the trio explicitly absent + `primaryAction`
   PaletteSection,
   PaletteVariant,
   SendPayload,
   SendResult,
+  SendDialogProps,
+  SendExtrasContext,
+  PrimaryActionConfig,
+  PrimaryActionContext,
   ChannelOption,
   SendAsUserStatus,
+  ValidationSummary,
   PreviewHooks,
 } from "@tightknitai/block-kitchen";
 ```

package/dist/helpers.d.cts

@@ -1,5 +1,5 @@
-import { T as SupportedBlock } from './palette-CKP8CK5Z.cjs';
-export { U as SupportedBlockType } from './palette-CKP8CK5Z.cjs';
+import { _ as SupportedBlock } from './palette-C8sPJuXx.cjs';
+export { $ as SupportedBlockType } from './palette-C8sPJuXx.cjs';
 import 'react';
 import 'slack-web-api-client';
 

package/dist/helpers.d.ts

@@ -1,5 +1,5 @@
-import { T as SupportedBlock } from './palette-CKP8CK5Z.js';
-export { U as SupportedBlockType } from './palette-CKP8CK5Z.js';
+import { _ as SupportedBlock } from './palette-C8sPJuXx.js';
+export { $ as SupportedBlockType } from './palette-C8sPJuXx.js';
 import 'react';
 import 'slack-web-api-client';