@tightknitai/block-kitchen 0.10.23 → 0.10.25

package/README.md

@@ -139,6 +139,8 @@ Given no height to work with — a plain `<div>` in ordinary document flow — i
 | `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. |
 | `blockActions` | `BlockAction[]` | no | Host buttons added to every block's action toolbar, before Edit / Duplicate / Delete. Each is `{ id, label, icon, onSelect }`, and `onSelect` receives the block's `{ index, childIndex }`. See [Adding your own block actions](#adding-your-own-block-actions-blockactions). |
+| `renderBlockAdornment` | `(position: BlockPosition) => ReactNode` | no | Host content shown beside every block, at its right edge, all the time (unlike `blockActions`, which show on hover), e.g. a count of comments on the block. Return `null` for a block with nothing to show. See [Adding your own block actions](#adding-your-own-block-actions-blockactions). |
+| `blockEditors` | `CustomBlockEditor[]` | no | Host forms that replace the built-in editor for the blocks they match. Each is `{ id, label, match, component }`. The block stays ordinary Block Kit. See [Editing a block your way](#editing-a-block-your-way-blockeditors). |
 | `customEmojis` | `CustomEmoji[]` | no | Workspace custom emoji (`{ name, url, alias }`) the preview resolves. Entries with a `url` render `:name:` as the workspace image; alias entries (`url: null`) fall back to their target emoji. Render-only — never serialized into the emitted Block Kit JSON. A caller-supplied `previewHooks.emoji` takes precedence. |
 | `mentions` | `{ searchUsers, getUserName?, searchChannels?, getChannelName? }` | no | Opt-in rich-text mentions. `@` and the Mention button search users; when `searchChannels` is provided, `#` and the Channel button search channels. Picks serialize as Slack `user` / `channel` elements. See [Mentions](#mentions-opt-in). |
 | `palette` | `PaletteSection[]` | no | The left-hand palette of draggable variants. Defaults to `defaultPalette`. Spread it to filter, reorder, or add your own pre-configured variants — see [Customizing the palette](#customizing-the-palette). |
@@ -149,6 +151,7 @@ Given no height to work with — a plain `<div>` in ordinary document flow — i
 | `paletteSearchPlaceholder` | `string` | no | Placeholder text for the palette search input. Defaults to `'Search blocks…'`. Useful for localization. |
 | `allowedSurfaces` | `PreviewSurface[]` | no | Allowlist of preview surfaces (`'message'`, `'modal'`, `'app_home'`). Defaults to `['message']` — surface dropdown is hidden when only one surface is allowed. The first entry is the initial selection. |
 | `showThemeControl` | `boolean` | no | Defaults to `true`. When `false`, the toolbar's light/dark toggle is hidden and the theme stays at `defaultPreviewTheme`. Ignored when `previewTheme` is set (a controlled theme always hides the toggle). |
+| `undoRedoShortcuts` | `boolean` | no | Defaults to `true`: `Ctrl`/`Cmd` + `Z` undoes and `Ctrl`/`Cmd` + `Shift` + `Z` (or `Ctrl` + `Y`) redoes, like the toolbar's Undo / Redo buttons. Pass `false` to leave those keys to the host. See [Undo & redo](#undo--redo). |
 | `defaultPreviewTheme` | `'light' \| 'dark'` | no | Initial (uncontrolled) preview theme. Pass the host app's current theme so the preview opens matched to the consuming app's appearance. Ignored when `previewTheme` is provided. |
 | `previewTheme` | `'light' \| 'dark'` | no | Controlled preview theme. When set, the preview renders in this theme, follows it reactively, and the toolbar's light/dark toggle is hidden so the host app fully owns the theme. Leave unset to keep the preview uncontrolled (seeded from `defaultPreviewTheme`, toggle shown). |
 | `sendButtonLabel` | `string` | no | Label and accessible name for the toolbar's Send button (which opens the send dialog). Defaults to `'Review & send'` (the dialog is the review step). Override it for product-specific copy, e.g. `'Send to channel…'`. |
@@ -467,6 +470,19 @@ top-level block). Map it onto the blocks `onChange` last reported; builder
 ids never leave the package. An `svg` icon is sized to match the built-in
 ones.
 
+For something that should show all the time, like a count of comments on
+each block, pass `renderBlockAdornment`. It's called with the same position
+and renders beside the block, at its right edge; return `null` for a block
+with nothing to show:
+
+```tsx
+<BlockKitchen
+  renderBlockAdornment={({ index, childIndex }) =>
+    childIndex === null && counts[index] ? <CommentCount count={counts[index]} /> : null
+  }
+/>
+```
+
 Each block's row also carries `data-bk-block-index` (plus
 `data-bk-child-index` inside a container), so the host can find a block on
 the canvas, for example to scroll to it or highlight it:
@@ -475,6 +491,41 @@ the canvas, for example to scroll to it or highlight it:
 document.querySelector(`.bk-root [data-bk-block-index="${index}"]:not([data-bk-child-index])`);
 ```
 
+## Editing a block your way (`blockEditors`)
+
+Some blocks mean something to your app beyond their Block Kit shape: a
+"Share on LinkedIn" button, say, whose URL is built from the text of a post.
+Editing that URL by hand in the built-in buttons form is no way to write a
+post. `blockEditors` lets the host supply the form instead:
+
+```tsx
+const LINKEDIN_EDITOR: CustomBlockEditor = {
+  id: "linkedin-share",
+  label: "Share on LinkedIn",
+  match: (block) => isLinkedInShareBlock(block), // your own check
+  component: ({ block, onChange }) => (
+    <Textarea
+      value={postTextFrom(block)}
+      onChange={(e) => onChange(withPostText(block, e.target.value))}
+    />
+  ),
+};
+
+<BlockKitchen blockEditors={[LINKEDIN_EDITOR]} {...rest} />;
+```
+
+When a block's edit popover opens, the first editor whose `match` accepts the
+block replaces the built-in form, under the heading "Edit {label}". The
+popover keeps its validation errors, Block ID field and Done button. Blocks no
+editor matches keep the built-in form, and so does every block when the prop
+is left out.
+
+The block itself stays ordinary Block Kit, so the preview, validation, the
+JSON view and sending all treat it like any other. That also means `match` has
+to recognize the block from what it holds (a URL, an `action_id`): a message
+loaded back from Slack carries nothing else. Keep the array referentially
+stable (module scope or `useMemo`).
+
 ## Customizing the palette
 
 On desktop the palette is a rail down the left-hand side, with a chevron handle on its outer border that hides and restores it — collapsed, the preview gets the full width, and the rail comes back with its open sections and search exactly as they were. Below the `md` breakpoint there's no rail: the toolbar's **Blocks** button opens the palette as a bottom sheet instead, and picking a block closes it.
@@ -511,6 +562,28 @@ const PALETTE: readonly PaletteSection[] = [
 
 Variant `id`s must be unique across the array — the drag-drop lookup keys by id.
 
+### Badges and locked variants
+
+A variant can carry a `badge`, a small tag beside its label such as the plan
+it belongs to. Set `locked` as well to show a block without letting the user
+add it: it can't be dragged, has no add button, and picking it calls
+`onLockedSelect`, for example to open an upgrade prompt.
+
+```tsx
+const shareVariant: PaletteVariant = {
+  id: "linkedin_share",
+  label: "Share on LinkedIn",
+  factory: () => linkedInShareBlock(),
+  badge: { label: "Enterprise", icon: Crown },
+  locked: !plan.includesLinkedIn,
+  onLockedSelect: () => openUpgradeDialog(),
+};
+```
+
+A locked variant without `onLockedSelect` is inert. In the mobile sheet,
+picking one closes the sheet first, so whatever the host opens isn't stacked
+on top of it.
+
 ### Simple vs advanced palette
 
 By default the palette opens on everything it has: every section, plus the search input. For consumers whose users are writing ordinary messages rather than building interactive apps, `paletteMode="simple"` opens on a short starter list instead — no sections, no search — behind an **Advanced** link that swaps in the full palette (and back).
@@ -714,8 +787,8 @@ Defense-in-depth: blocks are validated against [slack-block-kit-validator](https
 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:
+and **Redo** buttons (disabled when there's nothing to step to), and these
+keyboard shortcuts do the same:
 
 | Shortcut | Action |
 |---|---|
@@ -729,10 +802,23 @@ Notes:
   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`.
+  inline rich-text editor is focused (including the fields in a block's
+  editor popover), `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 shortcuts are scoped to the builder**, so they don't hijack the host
+  page's own `Ctrl/Cmd+Z`. They act while focus is inside the builder, or
+  while nothing on the page has focus (focus is on `<body>`, or on a host
+  element wrapping the builder) and the last click landed in the builder.
+  That second case covers a click on the canvas background, or deleting a
+  block, which unmounts the Delete button that had focus. After a click
+  elsewhere on the page, or with focus in one of the host's own fields, the
+  keys are left alone.
+- With nothing to undo or redo, or when something else already handled the
+  key press (`defaultPrevented`), the shortcut does nothing and doesn't call
+  `preventDefault`.
+- **Opting out.** Pass `undoRedoShortcuts={false}` to turn the shortcuts off
+  and leave those keys to the host. The toolbar buttons still work, and
+  their tooltips stop mentioning the shortcuts.
 - **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

package/dist/helpers.d.cts

@@ -1,5 +1,5 @@
-import { S as SupportedBlock } from './palette-DFTL0Han.cjs';
-export { aa as SupportedBlockType } from './palette-DFTL0Han.cjs';
+import { S as SupportedBlock } from './palette-DTE9U5si.cjs';
+export { ad as SupportedBlockType } from './palette-DTE9U5si.cjs';
 import 'react';
 import 'slack-web-api-client';
 

package/dist/helpers.d.ts

@@ -1,5 +1,5 @@
-import { S as SupportedBlock } from './palette-DFTL0Han.js';
-export { aa as SupportedBlockType } from './palette-DFTL0Han.js';
+import { S as SupportedBlock } from './palette-DTE9U5si.js';
+export { ad as SupportedBlockType } from './palette-DTE9U5si.js';
 import 'react';
 import 'slack-web-api-client';