@tightknitai/block-kitchen 0.9.10 → 0.10.1

package/README.md

@@ -110,9 +110,10 @@ export function MyBuilderPage() {
 | `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 }` — the current draft plus the same verdict `onValidationChange` reports. See [Keeping the CTA in the toolbar](#keeping-the-cta-in-the-toolbar-primaryaction). |
-| `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. |
+| `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. |
@@ -134,9 +135,10 @@ export function MyBuilderPage() {
 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. `editing` and `renderSendExtras` require the trio;
+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).
+toolbar's primary slot otherwise). `loading` is mode-agnostic — it works
+with or without the trio.
 
 ## Compose-only mode (bring your own send flow)
 
@@ -186,9 +188,15 @@ Notes:
 - `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.
-- `editing` is unavailable in compose-only mode: updating an existing message
-  is inherently bound to its channel + timestamp, so the update flow only
-  exists alongside the send integration.
+- [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`)
 
@@ -287,17 +295,20 @@ Notes:
   (identities, channels), prefer proposing a first-class prop over routing
   them through extras; the slot is for genuinely host-specific concerns.
 
-## Editing an existing message (opt-in)
+## Loading an existing message (opt-in)
 
-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
+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
@@ -315,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) => ({
@@ -337,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
 
@@ -405,7 +461,9 @@ import type {
   SupportedBlockType,
   BlockKitchenProps,
   BlockKitchenBaseProps,        // shared props
-  BlockKitchenSendProps,        // the send trio + `editing` + `renderSendExtras`
+  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,
@@ -436,6 +494,37 @@ Pass [`customEmojis`](#props) to add your workspace's custom emoji: image entrie
 
 Defense-in-depth: blocks are validated against [slack-block-kit-validator](https://github.com/TightknitAI/slack-block-kit-validator) before send. Issues are surfaced in the issues sheet with line numbers — users can fix them inline before posting.
 
+## Undo & redo
+
+Every edit to the draft is undoable — adding, deleting, duplicating,
+reordering, dragging in and out of containers, editing a block's fields, and
+the toolbar's **Clear** and **View JSON → apply**. The toolbar shows **Undo**
+and **Redo** buttons (disabled when there's nothing to step to), and the
+keyboard shortcuts work whenever focus is inside the builder:
+
+| Shortcut | Action |
+|---|---|
+| `Ctrl`/`Cmd` + `Z` | Undo |
+| `Ctrl`/`Cmd` + `Shift` + `Z`, or `Ctrl` + `Y` | Redo |
+
+Notes:
+
+- **Typing coalesces.** A run of edits to the *same* field collapses into a
+  single undo step, so one `Ctrl+Z` rewinds the whole edit rather than one
+  character at a time. Editing a different block, or any structural change,
+  starts a new step.
+- **Native text undo is preserved.** While a text input, textarea, or the
+  inline rich-text editor is focused, `Ctrl/Cmd+Z` performs the browser's
+  own per-character undo — the builder only takes over when focus is on the
+  canvas or toolbar. The shortcut is scoped to the builder, so it never
+  hijacks the host app's own `Ctrl/Cmd+Z`.
+- **Loading is a fresh baseline.** [Loading an existing
+  message](#loading-an-existing-message-opt-in) (or "open as new") starts a
+  new document with an empty history — undo won't step back across the load
+  into the previous draft. **Clear**, by contrast, is undoable.
+- Undo and redo are ordinary draft changes, so they flow through `onChange`
+  (and re-run validation) like any other edit.
+
 ## Styling
 
 Ships a compiled stylesheet at `@tightknitai/block-kitchen/styles.css`. The styles use CSS custom properties (`--background`, `--primary`, `--border`, etc.) for theming. Consumers must provide values for these vars — the standard shadcn/ui token set works as-is.

package/dist/helpers.d.cts

@@ -1,5 +1,5 @@
-import { Z as SupportedBlock } from './palette-Duj901T6.cjs';
-export { _ as SupportedBlockType } from './palette-Duj901T6.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 { Z as SupportedBlock } from './palette-Duj901T6.js';
-export { _ as SupportedBlockType } from './palette-Duj901T6.js';
+import { _ as SupportedBlock } from './palette-C8sPJuXx.js';
+export { $ as SupportedBlockType } from './palette-C8sPJuXx.js';
 import 'react';
 import 'slack-web-api-client';