@keboola/design 1.2.1 → 1.3.1

package/src/blocks/MultiActionButtonGroup/MultiActionButton.stories.tsx

@@ -2,6 +2,7 @@ import type { ComponentType } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { TooltipProvider } from '../../components/Tooltip';
+import { Copy, Pencil, Trash2 } from '../../icons';
 
 import { MultiActionButton } from './MultiActionButton';
 import { MultiActionButtonGroup } from './MultiActionButtonGroup';
@@ -20,7 +21,7 @@ export default {
     disabled: false,
     isLoading: false,
     tooltipContent: 'Action',
-    icon: 'trash',
+    icon: <Trash2 />,
     onClick: () => alert('Button clicked'),
   },
   argTypes: {
@@ -37,21 +38,21 @@ type Story = StoryObj<typeof MultiActionButton>;
 
 export const Default: Story = {
   args: {
-    icon: 'pen',
+    icon: <Pencil />,
     tooltipContent: 'Edit',
   },
 };
 
 export const Delete: Story = {
   args: {
-    icon: 'trash',
+    icon: <Trash2 />,
     tooltipContent: 'Delete',
   },
 };
 
 export const Loading: Story = {
   args: {
-    icon: 'pen',
+    icon: <Pencil />,
     tooltipContent: 'Saving...',
     isLoading: true,
   },
@@ -59,7 +60,7 @@ export const Loading: Story = {
 
 export const Disabled: Story = {
   args: {
-    icon: 'trash',
+    icon: <Trash2 />,
     tooltipContent: 'Delete (disabled)',
     disabled: true,
   },
@@ -69,19 +70,19 @@ export const ButtonGroup: Story = {
   render: () => (
     <MultiActionButtonGroup>
       <MultiActionButtonGroup.Button
-        icon="pen"
+        icon={<Pencil />}
         label="Edit"
         tooltipContent="Edit"
         onClick={() => alert('Edit clicked')}
       />
       <MultiActionButtonGroup.Button
-        icon="copy"
+        icon={<Copy />}
         label="Copy"
         tooltipContent="Copy"
         onClick={() => alert('Copy clicked')}
       />
       <MultiActionButtonGroup.Button
-        icon="trash"
+        icon={<Trash2 />}
         label="Delete"
         tooltipContent="Delete"
         onClick={() => alert('Delete clicked')}
@@ -94,20 +95,20 @@ export const ButtonGroupWithMixedStates: Story = {
   render: () => (
     <MultiActionButtonGroup>
       <MultiActionButtonGroup.Button
-        icon="pen"
+        icon={<Pencil />}
         label="Edit"
         tooltipContent="Edit"
         onClick={() => alert('Edit clicked')}
       />
       <MultiActionButtonGroup.Button
-        icon="copy"
+        icon={<Copy />}
         label="Copy"
         tooltipContent="Processing..."
         isLoading={true}
         onClick={() => {}}
       />
       <MultiActionButtonGroup.Button
-        icon="trash"
+        icon={<Trash2 />}
         label="Delete"
         tooltipContent="Delete (disabled)"
         disabled={true}

package/src/blocks/MultiActionButtonGroup/MultiActionButton.tsx

@@ -1,12 +1,12 @@
 import type { ComponentProps, ReactNode } from 'react';
 
 import { Button } from '../../components/Button';
-import type { Icon } from '../../components/Icon';
 import { Tooltip } from '../../components/Tooltip';
+import { renderLegacyIcon } from '../../utils/legacyIcon';
 
 type Props = {
   disabled?: boolean;
-  icon: ComponentProps<typeof Icon>['icon'];
+  icon: ReactNode;
   isLoading?: boolean;
   label: string;
   onClick: ComponentProps<typeof Button>['onClick'];
@@ -28,13 +28,14 @@ export const MultiActionButton = ({
   <Tooltip placement="top" tooltip={tooltipContent} triggerAsChild variant={tooltipVariant}>
     <Button
       disabled={disabled}
-      icon={icon}
       isLoading={isLoading}
       aria-label={label}
       onClick={onClick}
       variant="invisible"
       size="icon"
       data-testid={dataTestId}
-    />
+    >
+      {!isLoading && renderLegacyIcon(icon)}
+    </Button>
   </Tooltip>
 );

package/src/blocks/MultiCombobox/MultiCombobox.tsx

@@ -11,8 +11,8 @@ import {
   isGroupItem,
   isLabeledItem,
 } from '../../components/Combobox/utils';
-import type { Icon } from '../../components/Icon';
 import { InputGroup } from '../../components/InputGroup';
+import { ChevronDown, X } from '../../icons';
 
 type ComboboxProps<Value> = BaseCombobox.Root.Props<Value, true>;
 type ComboboxInputProps = ComponentProps<typeof Combobox.Input>;
@@ -20,9 +20,13 @@ type ComboboxInputGroupProps = ComponentProps<typeof Combobox.InputGroup>;
 type ComboboxItemProps = ComponentProps<typeof Combobox.Item>;
 type ComboboxChipsProps = ComponentProps<typeof Combobox.Chips>;
 
-type IconName = ComponentProps<typeof Icon>['icon'];
 type Indicator = NonNullable<ComboboxItemProps['indicator']>;
 
+/**
+ * Props for `MultiCombobox`. Generic over `Value` (the item shape) and `GroupShape` (optional group wrapper).
+ * Use `itemToLabel` / `itemToIcon` / `itemToDisabled` to project custom item shapes; use `filter` to override
+ * the default substring matcher.
+ */
 type Props<Value, GroupShape extends Group<Value> = Group<Value>> = Pick<
   ComboboxInputProps,
   'placeholder' | 'id'
@@ -50,7 +54,7 @@ type Props<Value, GroupShape extends Group<Value> = Group<Value>> = Pick<
 
     // item specific
     itemToLabel?: (item: Value) => ReactNode;
-    itemToIcon?: (item: Value) => IconName | undefined;
+    itemToIcon?: (item: Value) => ReactNode;
     itemToDisabled?: (item: Value) => boolean;
 
     // gropu specific
@@ -65,6 +69,19 @@ const selectAllItem: LabeledItem = {
 const isSelectAllItem = <Value,>(item: Value) =>
   isLabeledItem(item) && item.value === '__select_all__';
 
+/**
+ * Multi-selection combobox with chip display and search. Built on Base UI Combobox.
+ *
+ * **When to use:** picking several items from a searchable enumerated list (filter by tags, assign labels).
+ * Items render as chips above the input; `maxVisible` collapses excess into a `+N more` chip.
+ * **When NOT to use:** for single selection use `Combobox`; for short enums without search use `Select`;
+ * for free-form chip entry where the user types arbitrary new values use `Tagger`.
+ * **Composition:** wrap in `FormGroup` for label + help text, or use `useAppForm` for form integration.
+ * Pass `allowSelectAll` for a sticky "Select All" item when the full enum is small.
+ *
+ * @see RECIPES.md#creatable-multi-combobox — for free-form-plus-enumerated patterns
+ * @see RECIPES.md#filter-toolbar — for combining multi-select with other filter chips
+ */
 export const MultiCombobox = <Value, GroupShape extends Group<Value> = Group<Value>>({
   // root props
   items: _itemsProp,
@@ -194,17 +211,16 @@ export const MultiCombobox = <Value, GroupShape extends Group<Value> = Group<Val
                 className="tw-w-auto tw-min-w-[120px] tw-flex-1"
               />
               {allowClear && (
-                <InputGroup.Button asChild icon="xmark" aria-label="Clear" disabled={disabled}>
-                  <BaseCombobox.Clear />
+                <InputGroup.Button asChild aria-label="Clear" disabled={disabled}>
+                  <BaseCombobox.Clear>
+                    <X className="tw-size-4" />
+                  </BaseCombobox.Clear>
                 </InputGroup.Button>
               )}
-              <InputGroup.Button
-                disabled={disabled}
-                asChild
-                icon="chevron-down"
-                aria-label="Open combobox"
-              >
-                <BaseCombobox.Trigger />
+              <InputGroup.Button disabled={disabled} asChild aria-label="Open combobox">
+                <BaseCombobox.Trigger>
+                  <ChevronDown className="tw-size-4" />
+                </BaseCombobox.Trigger>
               </InputGroup.Button>
             </div>
           </div>

package/src/blocks/PageHeader/AGENTS.md

@@ -65,13 +65,73 @@ either variant.
 - **Compose** existing `Breadcrumb`, `Badge`, `DropdownMenu`, `Tabs` from
   `@keboola/design` — slots take any `ReactNode`, but use the design-system
   pieces.
-- Title and description can be any `ReactNode`; pass an
-  `InlineEditableText` (when it lands) for editable titles per the Detail
-  pattern.
+- Title and description can be any `ReactNode`. For Linear-style inline
+  editing, compose `MarkdownEditor` (from `@keboola/design`) directly into
+  the slots — `PageHeader` does not depend on Lexical itself; only callers
+  that opt into editing pull it in.
+
+## Inline editing
+
+The `title` and `description` slots accept any `ReactNode`, so they can hold
+an editable `MarkdownEditor` in place of the static text. Follows the
+[inline-editable-text pattern](https://github.com/evviku/design-system-docs/tree/main/docs/patterns/inline-editable-text):
+
+- **No edit icon, no save / cancel buttons.**
+- **Blur, Cmd+Enter, or Enter (title only) commits** via `onSave`.
+- **Esc reverts** via `onCancel` — the caller resets state to the last
+  committed value inside this handler.
+- **Description clamps to ~2 lines with a bottom fade** in display state
+  (use the `clampDisplay` prop); focus expands to full height. Fade
+  replaces ellipsis per the spec.
+
+Use `compact` + `saveOnBlur` for both slots, plus `singleLine` for the
+title and `clampDisplay` for the description. Maintain a two-state
+(`committed` / `draft`) pattern so `onCancel` can revert without losing
+the committed value:
+
+```tsx
+import { MarkdownEditor } from '@keboola/design';
+
+const [committedTitle, setCommittedTitle] = useState(initial.title);
+const [draftTitle, setDraftTitle] = useState(committedTitle);
+// (same for description)
+
+<PageHeader.Detail
+  breadcrumbs={...}
+  title={
+    <MarkdownEditor
+      compact singleLine saveOnBlur
+      value={draftTitle}
+      onChange={setDraftTitle}
+      onSave={() => { setCommittedTitle(draftTitle); save({ title: draftTitle }); }}
+      onCancel={() => setDraftTitle(committedTitle)}
+      placeholder="Untitled"
+      className="tw-m-0 tw-text-3xl tw-font-semibold tw-leading-9 tw-text-foreground tw-break-words"
+    />
+  }
+  description={
+    <MarkdownEditor
+      compact saveOnBlur clampDisplay
+      value={draftDescription}
+      onChange={setDraftDescription}
+      onSave={() => { setCommittedDescription(draftDescription); save({ description: draftDescription }); }}
+      onCancel={() => setDraftDescription(committedDescription)}
+      placeholder="Add a description…"
+      className="tw-m-0 tw-max-w-[800px] tw-break-words tw-text-sm tw-leading-5 tw-text-muted-foreground"
+    />
+  }
+  primaryAction={...}
+/>;
+```
+
+The `titleClass` / `descriptionClass` constants exported from
+`./styles.ts` carry the canonical typography — pass them through
+`className` so the editor visually matches the static variant.
 
 ## Stories
 
 - `IndexFlows` — description + secondary/primary actions, no header nav.
 - `IndexStorage` — `metadata` count summary + 5-tab `headerNav`.
 - `DetailBucket` — breadcrumbs + overflow + badges + primary action.
+- `DetailEditable` — inline-editable title + description via `MarkdownEditor`.
 - `DetailDataApp` — primary + secondary actions + 3-tab `headerNav`.

package/src/blocks/PageHeader/PageHeader.stories.tsx

@@ -1,14 +1,27 @@
+import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
+import {
+  BookOpen,
+  Bug,
+  Copy,
+  EllipsisVertical,
+  Trash2,
+  Upload,
+  Users,
+} from '@keboola/design/icons';
+
 import { Badge } from '../../components/Badge';
 import { Breadcrumb } from '../../components/Breadcrumb';
 import { Button } from '../../components/Button';
 import { DropdownMenu } from '../../components/DropdownMenu';
+import { MarkdownEditor } from '../../components/MarkdownEditor';
 import { Tabs, TabsContent } from '../../components/Tabs';
 import { PageLayout } from '../PageLayout';
 import { SplitButton } from '../SplitButton';
 
 import { PageHeader } from './PageHeader';
+import { descriptionClass, titleClass } from './styles';
 
 type Story = StoryObj<typeof PageHeader.Index>;
 
@@ -41,7 +54,9 @@ export const IndexFlows: Story = {
         title="Flows"
         description="Build flows with branching logic and conditions. Tasks run based on previous results, errors, or custom expressions."
         documentation={
-          <Button argo variant="invisible" icon="book-blank" aria-label="Documentation" />
+          <Button argo variant="invisible" aria-label="Documentation">
+            <BookOpen className="tw-size-4" />
+          </Button>
         }
         action={
           <>
@@ -73,7 +88,9 @@ export const IndexStorage: Story = {
         title="Storage"
         metadata="3 buckets and 39 tables"
         documentation={
-          <Button argo variant="invisible" icon="book-blank" aria-label="Documentation" />
+          <Button argo variant="invisible" aria-label="Documentation">
+            <BookOpen className="tw-size-4" />
+          </Button>
         }
         action={
           <SplitButton
@@ -81,14 +98,13 @@ export const IndexStorage: Story = {
             onClick={() => {}}
             actions={
               <>
-                <SplitButton.Action icon="upload" onClick={() => {}}>
-                  Upload file
-                </SplitButton.Action>
+                <SplitButton.Action onClick={() => {}}>Upload file</SplitButton.Action>
                 <SplitButton.Action icon="cloud-arrow-down" onClick={() => {}}>
                   Import from external storage
                 </SplitButton.Action>
               </>
             }
+            icon={<Upload className="tw-size-4" />}
           >
             New bucket
           </SplitButton>
@@ -147,19 +163,17 @@ export const DetailBucket: Story = {
         overflowActions={
           <DropdownMenu>
             <DropdownMenu.Trigger asChild>
-              <Button
-                argo
-                variant="invisible"
-                size="icon-sm"
-                icon="ellipsis-vertical"
-                aria-label="More actions"
-              />
+              <Button argo variant="invisible" size="icon-sm" aria-label="More actions">
+                <EllipsisVertical className="tw-size-4" />
+              </Button>
             </DropdownMenu.Trigger>
             <DropdownMenu.Content align="end">
-              <DropdownMenu.Item icon="copy">Copy</DropdownMenu.Item>
-              <DropdownMenu.Item icon="user-group">Manage permissions</DropdownMenu.Item>
+              <DropdownMenu.Item icon={<Copy className="tw-size-4" />}>Copy</DropdownMenu.Item>
+              <DropdownMenu.Item icon={<Users className="tw-size-4" />}>
+                Manage permissions
+              </DropdownMenu.Item>
               <DropdownMenu.Separator />
-              <DropdownMenu.Item icon="trash">Delete</DropdownMenu.Item>
+              <DropdownMenu.Item icon={<Trash2 className="tw-size-4" />}>Delete</DropdownMenu.Item>
             </DropdownMenu.Content>
           </DropdownMenu>
         }
@@ -177,14 +191,13 @@ export const DetailBucket: Story = {
             onClick={() => {}}
             actions={
               <>
-                <SplitButton.Action icon="upload" onClick={() => {}}>
-                  Upload CSV
-                </SplitButton.Action>
+                <SplitButton.Action onClick={() => {}}>Upload CSV</SplitButton.Action>
                 <SplitButton.Action icon="link" onClick={() => {}}>
                   Link existing table
                 </SplitButton.Action>
               </>
             }
+            icon={<Upload className="tw-size-4" />}
           >
             Add table
           </SplitButton>
@@ -197,6 +210,93 @@ export const DetailBucket: Story = {
   ),
 };
 
+// Detail — editable (inline edit on title + description per the inline-editable-text pattern spec).
+const DetailEditableRender = () => {
+  // Two-state pattern: `committed` is what's persisted; `draft` tracks in-progress edits.
+  // onSave (blur / Cmd+Enter / Enter on title) commits draft → committed.
+  // onCancel (Esc) reverts draft ← committed.
+  const [committedTitle, setCommittedTitle] = useState('Marketing bucket');
+  const [draftTitle, setDraftTitle] = useState(committedTitle);
+  const [committedDescription, setCommittedDescription] = useState(
+    'Contains marketing datasets and transformation outputs. This description is intentionally long so you can see how the display state clamps to two lines with a bottom fade — focus the field and it expands to full height for editing.',
+  );
+  const [draftDescription, setDraftDescription] = useState(committedDescription);
+
+  return (
+    <PageLayout>
+      <PageHeader.Detail
+        breadcrumbs={
+          <Breadcrumb>
+            <Breadcrumb.List>
+              <Breadcrumb.Item>
+                <Breadcrumb.Link href="#">Storage</Breadcrumb.Link>
+              </Breadcrumb.Item>
+              <Breadcrumb.Separator />
+              <Breadcrumb.Item>
+                <Breadcrumb.Page>{committedTitle || 'Untitled'}</Breadcrumb.Page>
+              </Breadcrumb.Item>
+            </Breadcrumb.List>
+          </Breadcrumb>
+        }
+        title={
+          <MarkdownEditor
+            compact
+            singleLine
+            saveOnBlur
+            value={draftTitle}
+            onChange={setDraftTitle}
+            onSave={() => setCommittedTitle(draftTitle)}
+            onCancel={() => setDraftTitle(committedTitle)}
+            placeholder="Untitled"
+            className={titleClass}
+          />
+        }
+        badges={<Badge color="green">Active</Badge>}
+        description={
+          <MarkdownEditor
+            compact
+            saveOnBlur
+            clampDisplay
+            value={draftDescription}
+            onChange={setDraftDescription}
+            onSave={() => setCommittedDescription(draftDescription)}
+            onCancel={() => setDraftDescription(committedDescription)}
+            placeholder="Add a description…"
+            className={descriptionClass}
+          />
+        }
+        primaryAction={
+          <Button argo onClick={() => {}}>
+            Add table
+          </Button>
+        }
+      />
+      <PageLayout.Content>
+        <details className="tw-rounded tw-border tw-border-border tw-bg-muted/30 tw-p-4">
+          <summary className="tw-cursor-pointer tw-text-sm tw-text-muted-foreground">
+            Committed state (only updates on save — Esc reverts draft)
+          </summary>
+          <pre className="tw-mt-2 tw-whitespace-pre-wrap tw-text-xs">
+            {JSON.stringify({ title: committedTitle, description: committedDescription }, null, 2)}
+          </pre>
+        </details>
+      </PageLayout.Content>
+    </PageLayout>
+  );
+};
+
+export const DetailEditable: Story = {
+  render: () => <DetailEditableRender />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Inline editing per the [inline-editable-text pattern spec](https://github.com/evviku/design-system-docs/tree/main/docs/patterns/inline-editable-text). Click the title or description to edit in place; no edit icon, no save / cancel buttons. **Blur, Enter (title), or Cmd+Enter commits** via `onSave`. **Esc reverts** via `onCancel` (caller resets state to last committed). Description uses `clampDisplay` so it clamps to ~2 lines + bottom fade when not focused; focusing expands to full height. Both slots accept any `ReactNode`, so `PageHeader` stays Lexical-free.',
+      },
+    },
+  },
+};
+
 // Detail — sales dashboard (primary + secondary actions + header nav).
 export const DetailDataApp: Story = {
   render: () => (
@@ -218,19 +318,15 @@ export const DetailDataApp: Story = {
         overflowActions={
           <DropdownMenu>
             <DropdownMenu.Trigger asChild>
-              <Button
-                argo
-                variant="invisible"
-                size="icon-sm"
-                icon="ellipsis-vertical"
-                aria-label="More actions"
-              />
+              <Button argo variant="invisible" size="icon-sm" aria-label="More actions">
+                <EllipsisVertical className="tw-size-4" />
+              </Button>
             </DropdownMenu.Trigger>
             <DropdownMenu.Content align="end">
-              <DropdownMenu.Item icon="copy">Duplicate</DropdownMenu.Item>
-              <DropdownMenu.Item icon="bug">Debug mode</DropdownMenu.Item>
+              <DropdownMenu.Item icon={<Copy className="tw-size-4" />}>Duplicate</DropdownMenu.Item>
+              <DropdownMenu.Item icon={<Bug className="tw-size-4" />}>Debug mode</DropdownMenu.Item>
               <DropdownMenu.Separator />
-              <DropdownMenu.Item icon="trash">Delete</DropdownMenu.Item>
+              <DropdownMenu.Item icon={<Trash2 className="tw-size-4" />}>Delete</DropdownMenu.Item>
             </DropdownMenu.Content>
           </DropdownMenu>
         }

package/src/blocks/PageHeader/PageHeader.tsx

@@ -1,7 +1,22 @@
 import { PageHeaderDetail } from './PageHeaderDetail';
 import { PageHeaderIndex } from './PageHeaderIndex';
 
+/**
+ * Structured page-header block that encodes the evviku page-header patterns 1:1 at the type level.
+ *
+ * **When to use:** every kbc-ui page with a structured header (title + actions + optional badges /
+ * description / tabs). Choose `PageHeader.Index` for list / collection pages, `PageHeader.Detail` for
+ * single-entity pages with breadcrumbs.
+ * **When NOT to use:** for layouts that don't match either pattern, host custom JSX inside
+ * `PageLayout.Header` directly. For routing-driven tab rows below the header use `PageLayout.Tabs`.
+ * **Composition:** nest inside `PageLayout.Header`. Always opt into `Button argo` for any buttons passed
+ * into header slots. The variant types enforce pattern constraints (e.g. `Index` rejects breadcrumbs).
+ *
+ * @see RECIPES.md#page-header-tabs — for the canonical page-header + tabs composition
+ */
 export const PageHeader = {
+  /** Index variant — top-level list / collection pages. No breadcrumbs; `metadata` wins over `description`. */
   Index: PageHeaderIndex,
+  /** Detail variant — single-entity pages with required breadcrumbs and an overflow-actions slot. Max 2 visible actions. */
   Detail: PageHeaderDetail,
 };

package/src/blocks/PageHeader/PageHeaderDetail.tsx

@@ -9,17 +9,39 @@ import { badgesClass, descriptionClass, titleClass, titleRowClass } from './styl
 //   - Breadcrumbs are required; overflow menu sits on the breadcrumbs row.
 //   - Max two visible actions: `primaryAction` + optional `secondaryAction`.
 //   - All other actions belong in the breadcrumbs-row overflow menu.
-type PageHeaderDetailProps = ComponentPropsWithoutRef<'header'> & {
+/**
+ * Props for `PageHeader.Detail`. Detail pages enforce mandatory breadcrumbs, ≤ 2 visible actions, and an
+ * overflow-menu slot on the breadcrumbs row.
+ */
+type PageHeaderDetailProps = Omit<ComponentPropsWithoutRef<'header'>, 'title'> & {
+  /** `Breadcrumb` chain ending in the entity name (last item is not a link). Required. */
   breadcrumbs: ReactNode;
+  /** `DropdownMenu` for tertiary actions. Sits on the breadcrumbs row, not the title row. */
   overflowActions?: ReactNode;
   title: ReactNode;
+  /** Inline `Badge`s rendered next to the title (status, environment, version). */
   badges?: ReactNode;
   description?: ReactNode;
+  /** Primary action (`Button argo`). Use the verb appropriate to the entity (Deploy / Run / Save). */
   primaryAction?: ReactNode;
+  /** Optional second action (`Button argo variant="secondary"`). Everything beyond goes in `overflowActions`. */
   secondaryAction?: ReactNode;
+  /** Optional `Tabs` row below the title block. */
   headerNav?: ReactNode;
 };
 
+/**
+ * Page header for single-entity pages.
+ *
+ * **When to use:** the page shows one entity (a bucket, flow, data app) with a parent hierarchy worth
+ * breadcrumbing. Primary action is typically "edit / deploy / run on this entity".
+ * **When NOT to use:** for top-level list pages use `PageHeader.Index`. For pages without a parent
+ * hierarchy use `PageHeader.Index` even if they show one entity.
+ * **Composition:** nest inside `PageLayout.Header`. Pass `Button argo` for actions. Anything beyond the
+ * 2-visible-actions cap belongs in `overflowActions` (a `DropdownMenu`), not in extra slots.
+ *
+ * @see RECIPES.md#list-detail — for the list-page → detail-page navigation pattern
+ */
 export const PageHeaderDetail = ({
   ref,
   className,

package/src/blocks/PageHeader/PageHeaderIndex.tsx

@@ -9,15 +9,34 @@ import { descriptionClass, titleClass, titleRowClass } from './styles';
 //   - No breadcrumbs (top-level pages).
 //   - `metadata` wins over `description` (mutually exclusive in pattern).
 //   - At most one primary `action`; pair with the `documentation` icon button.
-type PageHeaderIndexProps = ComponentPropsWithoutRef<'header'> & {
+/**
+ * Props for `PageHeader.Index`. Index pages have no breadcrumbs and no overflow menu — search and filters
+ * belong in `PageLayout.Toolbar`, not here.
+ */
+type PageHeaderIndexProps = Omit<ComponentPropsWithoutRef<'header'>, 'title'> & {
   title: ReactNode;
+  /** Prose description shown below the title. Mutually exclusive with `metadata` in the pattern; `metadata` wins when both are passed. */
   description?: ReactNode;
+  /** Count / system summary shown below the title (e.g. "3 buckets and 39 tables"). Wins over `description`. */
   metadata?: ReactNode;
+  /** Icon-only docs button (`Button argo variant="invisible" icon="book-blank"`). Sits next to `action`. */
   documentation?: ReactNode;
+  /** Primary "create / add new X" `Button`. Pass `Button argo`. */
   action?: ReactNode;
+  /** Optional `Tabs` row rendered below the title block. Use only when >1 dataset / section is worth navigating to. */
   headerNav?: ReactNode;
 };
 
+/**
+ * Page header for top-level list / collection pages.
+ *
+ * **When to use:** the page is a list (Flows, Storage, Jobs, …) with no parent in the same section.
+ * Primary action is typically "create / add a new X".
+ * **When NOT to use:** for single-entity detail pages use `PageHeader.Detail`; for layouts that don't fit
+ * either pattern host custom JSX in `PageLayout.Header` directly.
+ * **Composition:** nest inside `PageLayout.Header`. Always pass `Button argo` into `action` and
+ * `documentation`. Search and filter chips belong in `PageLayout.Toolbar`, not here.
+ */
 export const PageHeaderIndex = ({
   ref,
   className,

package/src/blocks/PageLayout/PageLayout.tsx

@@ -2,6 +2,11 @@ import type { ComponentPropsWithoutRef, ElementRef, Ref } from 'react';
 
 import { cn } from '../../utils';
 
+/**
+ * Props for `PageLayout` root. `maxWidth` constrains the content column —
+ * `narrow` (976px) for forms, `default` (1280px) for most pages, `wide` (1600px) for dense detail views,
+ * `full` for edge-to-edge layouts.
+ */
 type RootProps = ComponentPropsWithoutRef<'div'> & {
   maxWidth?: 'default' | 'narrow' | 'wide' | 'full';
 };
@@ -120,11 +125,32 @@ const Footer = ({
   </footer>
 );
 
+/**
+ * Compound page-chrome block. Provides every kbc-ui page with the same content-column shape:
+ * max-width container + vertical rhythm + named slots.
+ *
+ * **When to use:** every new kbc-ui page. Do not roll your own `<div className="tw-flex tw-flex-col">`
+ * chrome. Host `PageHeader.Index` / `PageHeader.Detail` inside `PageLayout.Header` for the structured
+ * page-header patterns.
+ * **When NOT to use:** the left-rail `Sidebar` lives in the app shell outside `PageLayout`. For embedded
+ * widgets or modal bodies the layout chrome is the modal / card itself, not `PageLayout`.
+ * **Composition:** `PageLayout` is opinionated about chrome only — slots accept any `ReactNode`. Put
+ * search / filter pills in `PageLayout.Toolbar`, never in the header. Form submit bars go in
+ * `PageLayout.Footer sticky`.
+ *
+ * @see RECIPES.md#list-detail — for the index → detail page pattern
+ */
 export const PageLayout = Object.assign(Root, {
+  /** Detail-pattern breadcrumb row. Usually composed automatically by `PageHeader.Detail` — slot exists for layouts that don't fit either `PageHeader` variant. */
   Breadcrumbs,
+  /** Host slot for `PageHeader.Index` / `PageHeader.Detail`, or custom header JSX when neither variant fits. */
   Header,
+  /** Escape hatch for routing-based tab rows. Use `Tabs` / `TabsContent` core components inside, never a raw `<button>`. */
   Tabs,
+  /** Search / filter pill row. Belongs here, NOT in the header per the page-header patterns. */
   Toolbar,
+  /** Main content slot. Lists, cards, tables. */
   Content,
+  /** Bottom action bar — form submit + cancel. Pass `sticky` for a footer that pins to the viewport. */
   Footer,
 });