@keboola/design 1.2.1 → 1.3.1

package/src/components/MarkdownEditor/plugins/toolbar/BlockTypeDropdown.tsx

@@ -1,5 +1,4 @@
 import { useRef } from 'react';
-import type { ComponentProps } from 'react';
 import { $createCodeNode } from '@lexical/code';
 import { INSERT_ORDERED_LIST_COMMAND, INSERT_UNORDERED_LIST_COMMAND } from '@lexical/list';
 import { $createHeadingNode, $createQuoteNode } from '@lexical/rich-text';
@@ -13,22 +12,31 @@ import {
   type LexicalEditor,
 } from 'lexical';
 
+import {
+  ChevronDown,
+  Heading1,
+  Heading2,
+  Heading3,
+  List as ListIcon,
+  ListOrdered,
+  type LucideIcon,
+  Quote,
+  SquareCode,
+  Type,
+} from '../../../../icons';
 import { cn } from '../../../../utils';
 import { DropdownMenu } from '../../../DropdownMenu';
-import { Icon } from '../../../Icon';
 import { Tooltip } from '../../../Tooltip';
 
-type IconProp = ComponentProps<typeof Icon>['icon'];
-
 const BLOCK_TYPE_META = {
-  paragraph: { label: 'Normal', icon: ['far', 'font'] as IconProp, selectable: true },
-  h1: { label: 'Heading 1', icon: ['far', 'h1'] as IconProp, selectable: true },
-  h2: { label: 'Heading 2', icon: ['far', 'h2'] as IconProp, selectable: true },
-  h3: { label: 'Heading 3', icon: ['far', 'h3'] as IconProp, selectable: true },
-  bullet: { label: 'Bullet List', icon: ['far', 'list-ul'] as IconProp, selectable: false },
-  number: { label: 'Numbered List', icon: ['far', 'list-ol'] as IconProp, selectable: false },
-  quote: { label: 'Quote', icon: ['far', 'block-quote'] as IconProp, selectable: false },
-  code: { label: 'Code Block', icon: 'square-code' as IconProp, selectable: false },
+  paragraph: { label: 'Normal', icon: Type satisfies LucideIcon, selectable: true },
+  h1: { label: 'Heading 1', icon: Heading1 satisfies LucideIcon, selectable: true },
+  h2: { label: 'Heading 2', icon: Heading2 satisfies LucideIcon, selectable: true },
+  h3: { label: 'Heading 3', icon: Heading3 satisfies LucideIcon, selectable: true },
+  bullet: { label: 'Bullet List', icon: ListIcon satisfies LucideIcon, selectable: false },
+  number: { label: 'Numbered List', icon: ListOrdered satisfies LucideIcon, selectable: false },
+  quote: { label: 'Quote', icon: Quote satisfies LucideIcon, selectable: false },
+  code: { label: 'Code Block', icon: SquareCode satisfies LucideIcon, selectable: false },
 } as const;
 
 type BlockType = keyof typeof BLOCK_TYPE_META;
@@ -51,6 +59,7 @@ export const BlockTypeDropdown = ({
 }) => {
   const savedSelectionRef = useRef<BaseSelection | null>(null);
   const currentMeta = isBlockType(blockType) ? BLOCK_TYPE_META[blockType] : null;
+  const CurrentBlockIcon = currentMeta?.icon ?? Type;
 
   const handleOpenChange = (open: boolean) => {
     if (open) {
@@ -107,14 +116,14 @@ export const BlockTypeDropdown = ({
               'hover:tw-bg-neutral-100',
             )}
           >
-            <Icon icon={currentMeta?.icon ?? ['far', 'font']} fixedWidth />
+            <CurrentBlockIcon className="tw-size-4" />
             {currentMeta?.label ?? 'Normal'}
-            <Icon icon={['fas', 'caret-down']} className="tw-text-[8px]" />
+            <ChevronDown className="tw-size-3" />
           </button>
         </DropdownMenu.Trigger>
       </Tooltip>
       <DropdownMenu.Content align="start" className="tw-min-w-40">
-        {BLOCK_TYPE_OPTIONS.map(({ value, label, icon }) => (
+        {BLOCK_TYPE_OPTIONS.map(({ value, label, icon: IconComp }) => (
           <DropdownMenu.Item
             key={value}
             onSelect={() => handleSelect(value)}
@@ -123,7 +132,7 @@ export const BlockTypeDropdown = ({
               blockType === value && 'tw-bg-secondary-50 tw-text-secondary-500',
             )}
           >
-            <Icon icon={icon} fixedWidth />
+            <IconComp className="tw-size-4" />
             {label}
           </DropdownMenu.Item>
         ))}

package/src/components/MarkdownEditor/plugins/toolbar/LinkPanel.tsx

@@ -10,10 +10,10 @@ import {
   type LexicalEditor,
 } from 'lexical';
 
+import { Link as LinkIcon } from '../../../../icons';
 import { Button } from '../../../Button';
 import { ButtonGroup } from '../../../ButtonGroup';
 import { FormGroup } from '../../../FormGroup';
-import { Icon } from '../../../Icon';
 import { TextInput } from '../../../Input';
 import { Label } from '../../../Label';
 
@@ -101,7 +101,7 @@ export const LinkPanel = ({ editor, isLink }: { editor: LexicalEditor; isLink: b
         onClick={() => editor.dispatchCommand(TOGGLE_LINK_COMMAND, null)}
         tooltip="Remove Link"
       >
-        <Icon icon={['far', 'link']} />
+        <LinkIcon className="tw-size-4" />
       </ToolbarButton>
     );
   }
@@ -109,7 +109,7 @@ export const LinkPanel = ({ editor, isLink }: { editor: LexicalEditor; isLink: b
   return (
     <div className="tw-relative">
       <ToolbarButton active={open} onClick={handleOpen} tooltip="Insert Link">
-        <Icon icon={['far', 'link']} />
+        <LinkIcon className="tw-size-4" />
       </ToolbarButton>
       {open && (
         <div

package/src/components/MarkdownEditor/transformers.ts

@@ -115,6 +115,16 @@ export const CUSTOM_TRANSFORMERS: Transformer[] = [
   ...TRANSFORMERS,
 ];
 
+/**
+ * Inline-only subset for `singleLine` mode: keeps text-format (bold/italic/code/strike)
+ * and text-match (links) transformers; drops every element / multiline-element transformer
+ * (headings, lists, HR, code blocks, mermaid). Used for inline-editable titles where the
+ * caller doesn't want block-level markdown syntax to "promote" a line.
+ */
+export const SINGLE_LINE_TRANSFORMERS: Transformer[] = CUSTOM_TRANSFORMERS.filter(
+  (t) => t.type === 'text-format' || t.type === 'text-match',
+);
+
 // --- Table pre/post-processing ---
 // GFM tables can't round-trip through Lexical's markdown (no built-in table transformer).
 // We wrap them in fenced code blocks on import and unwrap on export to preserve them exactly.

package/src/components/MergeEditor/AcceptControls/AcceptButton.tsx

@@ -1,20 +1,25 @@
+import { ChevronsLeft, ChevronsRight } from '../../../icons';
 import { Button } from '../../Button';
 
 type Props = {
   side: 'left' | 'right';
   onAccept: () => void;
+  argo?: boolean;
 };
 
-export const AcceptButton = ({ side, onAccept }: Props) => {
+export const AcceptButton = ({ side, onAccept, argo }: Props) => {
   const label = `Accept ${side === 'left' ? 'production' : 'branch'} version`;
+  const Chevron = side === 'left' ? ChevronsRight : ChevronsLeft;
   return (
     <Button
-      icon={side === 'left' ? ['far', 'chevrons-right'] : ['far', 'chevrons-left']}
       onClick={onAccept}
       variant="outline"
-      size="icon"
+      size="icon-sm"
       title={label}
       aria-label={label}
-    />
+      argo={argo}
+    >
+      <Chevron className="tw-size-5" />
+    </Button>
   );
 };

package/src/components/MergeEditor/AcceptControls/AcceptControls.tsx

@@ -1,5 +1,6 @@
 import type { RefCallback } from 'react';
 
+import { X } from '../../../icons';
 import { cn } from '../../../utils';
 import { Button } from '../../Button';
 import { LINE_HEIGHT_PX, type MergeConflict, PANE_HEADER_HEIGHT_PX } from '../constants';
@@ -12,21 +13,29 @@ type Props = {
   onAccept: (conflict: MergeConflict) => void;
   onDismiss?: (conflict: MergeConflict) => void;
   contentRef?: RefCallback<HTMLDivElement>;
+  argo?: boolean;
 };
 
-// 40px column when there are conflicts to render — wide enough to fit the
-// accept chevron + dismiss icon without overflowing into the adjacent panes
-// (which use `tw-overflow-hidden` and would clip absolutely-positioned
-// children that crossed the boundary). Collapses to 0 when idle so empty
-// merges don't reserve a sliver of layout. Inner wrapper allows horizontal
-// overflow so the icon buttons' focus-visible ring (4px) stays visible past
-// the column edge. Buttons stay aligned with their source-pane chunk via the
-// parent's `translateY(-scrollTop)` follower applied to `contentRef`.
-export const AcceptControls = ({ conflicts, side, onAccept, onDismiss, contentRef }: Props) => (
+// 28px column when there are conflicts to render — wide enough to fit the
+// 24px icon-xs accept chevron + dismiss icon without overflowing into the
+// adjacent panes (which use `tw-overflow-hidden` and would clip absolutely-
+// positioned children that crossed the boundary). Collapses to 0 when idle
+// so empty merges don't reserve a sliver of layout. Inner wrapper allows
+// horizontal overflow so the icon buttons' focus-visible ring stays visible
+// past the column edge. Buttons stay aligned with their source-pane chunk
+// via the parent's `translateY(-scrollTop)` follower applied to `contentRef`.
+export const AcceptControls = ({
+  conflicts,
+  side,
+  onAccept,
+  onDismiss,
+  contentRef,
+  argo,
+}: Props) => (
   <div
     className={cn(
       'tw-z-10 tw-flex tw-shrink-0 tw-flex-col tw-items-center',
-      conflicts.length > 0 ? 'tw-w-10' : 'tw-w-0',
+      conflicts.length > 0 ? 'tw-w-7' : 'tw-w-0',
     )}
   >
     {conflicts.length > 0 && (
@@ -44,16 +53,18 @@ export const AcceptControls = ({ conflicts, side, onAccept, onDismiss, contentRe
                   className="tw-absolute tw-inset-x-0 tw-flex tw-flex-col tw-items-center tw-gap-0.5"
                   style={{ top: `${topOffset}px` }}
                 >
-                  <AcceptButton side={side} onAccept={() => onAccept(conflict)} />
+                  <AcceptButton side={side} onAccept={() => onAccept(conflict)} argo={argo} />
                   {onDismiss && (
                     <Button
-                      icon="xmark"
                       onClick={() => onDismiss(conflict)}
                       variant="outline"
-                      size="icon"
+                      size="icon-sm"
                       title="Dismiss"
                       aria-label={`Dismiss ${side === 'left' ? 'production' : 'branch'} change`}
-                    />
+                      argo={argo}
+                    >
+                      <X className="tw-size-4" />
+                    </Button>
                   )}
                 </div>
               );

package/src/components/MergeEditor/ConflictStatus/ConflictStatusIndicator.tsx

@@ -1,5 +1,5 @@
+import { AlertTriangle, CircleCheck } from '../../../icons';
 import { cn } from '../../../utils';
-import { Icon } from '../../Icon';
 
 type Props = {
   remainingConflicts: number;
@@ -31,7 +31,7 @@ export const ConflictStatusIndicator = ({ remainingConflicts, remainingSafeChang
         colorClass,
       )}
     >
-      <Icon icon={allDone ? 'circle-check' : 'triangle-exclamation'} />
+      {allDone ? <CircleCheck className="tw-size-4" /> : <AlertTriangle className="tw-size-4" />}
       {allDone ? 'All changes resolved' : `${parts.join(', ')} remaining`}
     </p>
   );

package/src/components/MergeEditor/MergeEditor.stories.tsx

@@ -86,6 +86,7 @@ type MergeEditorHookProps = {
   right: string;
   leftLabel?: string;
   rightLabel?: string;
+  argo?: boolean;
 };
 
 const MergeEditorWithHook = ({
@@ -94,6 +95,7 @@ const MergeEditorWithHook = ({
   right = branchText,
   leftLabel = 'Production',
   rightLabel = 'Branch',
+  argo,
 }: Partial<MergeEditorHookProps>) => {
   const {
     mergeValue,
@@ -148,6 +150,7 @@ const MergeEditorWithHook = ({
         middleClassName="tw-border-blue-400"
         rightHeader={<PaneHeader label={rightLabel} sublabel="Version #3" />}
         className="tw-flex-1"
+        argo={argo}
       />
     </div>
   );
@@ -209,3 +212,15 @@ export const BothSidesAddRows: Story = {
     />
   ),
 };
+
+export const Argo: Story = {
+  render: () => <MergeEditorWithHook argo />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Same merge editor with the `argo` prop set. Accept and dismiss buttons inside the editor pick up the argo button palette while the layout chrome is unchanged.',
+      },
+    },
+  },
+};

package/src/components/MergeEditor/MergeEditor.tsx

@@ -30,6 +30,12 @@ type Props = {
   middleClassName?: string;
   rightHeader?: ReactNode;
   className?: string;
+  /**
+   * When true, the editor's internal accept and dismiss buttons render in the
+   * `argo` button variant. Layout chrome (panes, pane headers, scrollers) is
+   * unchanged — only consumer-controlled interactive surfaces switch theme.
+   */
+  argo?: boolean;
 };
 
 export const MergeEditor = ({
@@ -55,6 +61,7 @@ export const MergeEditor = ({
   middleClassName,
   rightHeader,
   className,
+  argo,
 }: Props) => {
   const { registerScroller, registerFollower } = useScrollSync();
 
@@ -81,6 +88,7 @@ export const MergeEditor = ({
         onAccept={acceptLeft}
         onDismiss={dismissLeft}
         contentRef={registerFollower(0, 'left-controls')}
+        argo={argo}
       />
 
       <MergePane
@@ -100,6 +108,7 @@ export const MergeEditor = ({
         onAccept={acceptRight}
         onDismiss={dismissRight}
         contentRef={registerFollower(2, 'right-controls')}
+        argo={argo}
       />
 
       <MergePane

package/src/components/MergeEditor/MergePane.tsx

@@ -44,15 +44,19 @@ export const MergePane = ({
           backgroundColor: colors.neutral[50],
           outline: 'none',
         },
-        '&.cm-editor .cm-scroller': {
-          alignItems: 'stretch !important',
-        },
         '.cm-gutters': {
           backgroundColor: colors.neutral[100],
         },
         '*': { lineHeight: `${LINE_HEIGHT_PX}px` },
         '.cm-lineNumbers .cm-gutterElement': { padding: '0 0 0 25px' },
       }),
+      // Recalc viewport after every doc change so late-settling layouts (alerts
+      // appearing above the editor) don't leave trailing lines blank.
+      EditorView.updateListener.of((update) => {
+        if (update.docChanged) {
+          requestAnimationFrame(() => update.view.dispatch({}));
+        }
+      }),
     ],
     [],
   );
@@ -76,12 +80,26 @@ export const MergePane = ({
     return () => onScrollDOMReady?.(null);
   }, [onScrollDOMReady]);
 
+  // Re-measure on wrapper resize — parent dimensions settle after CM mounts
+  // (fullscreen modal, alerts appearing above the editor).
+  useEffect(() => {
+    const view = editorRef.current?.view;
+    const wrapper = view?.dom.parentElement;
+    if (!view || !wrapper) return;
+
+    const observer = new ResizeObserver(() => view.dispatch({}));
+    observer.observe(wrapper);
+
+    return () => observer.disconnect();
+  }, []);
+
   return (
     <div className={cn('tw-flex tw-min-w-0 tw-flex-1 tw-flex-col tw-overflow-hidden', className)}>
       {header && <div className={cn('tw-bg-white tw-px-4 tw-py-3', headerClassName)}>{header}</div>}
-      <div className="tw-flex tw-h-0 tw-flex-1 tw-flex-col [&_>div]:tw-h-full [&_>div]:tw-overflow-auto">
+      <div className="tw-flex tw-h-0 tw-flex-1 tw-flex-col [&_>div]:tw-h-full">
         <CodeMirror
           ref={editorRef}
+          height="100%"
           value={value}
           onChange={onChange}
           extensions={extensions}

package/src/components/MergeEditor/decorations.ts

@@ -29,11 +29,11 @@ const safeDecoration = Decoration.line({ class: 'cm-merge-safe-line' });
 const conflictDecoration = Decoration.line({ class: 'cm-merge-conflict-line' });
 
 class SafeGutterMarker extends GutterMarker {
-  elementClass = 'cm-merge-safe-gutter';
+  override elementClass = 'cm-merge-safe-gutter';
 }
 
 class ConflictGutterMarker extends GutterMarker {
-  elementClass = 'cm-merge-conflict-gutter';
+  override elementClass = 'cm-merge-conflict-gutter';
 }
 
 const safeGutterMarker = new SafeGutterMarker();

package/src/components/Modal/Modal.stories.tsx

@@ -3,6 +3,8 @@ import type { ComponentProps, FormEventHandler } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { action } from 'storybook/actions';
 
+import { Rocket } from '@keboola/design/icons';
+
 import { Alert } from '../Alert';
 import { Button } from '../Button';
 import { ButtonGroup } from '../ButtonGroup';
@@ -28,7 +30,7 @@ const ModalDefault = (props: ComponentProps<typeof Modal>) => (
     </Modal.Trigger>
 
     <Modal.Content>
-      <Modal.Icon icon="rocket" color="red" />
+      <Modal.Icon color="red" icon={<Rocket />} />
       <Modal.Header title="Default Modal" description="Opens default modal">
         <Alert variant="info">Additional Header stuff</Alert>
       </Modal.Header>
@@ -68,7 +70,7 @@ const ModalLongContent = (props: ComponentProps<typeof Modal>) => (
     </Modal.Trigger>
 
     <Modal.Content>
-      <Modal.Icon icon="rocket" color="red" />
+      <Modal.Icon color="red" icon={<Rocket />} />
       <Modal.Header title="Default Modal" description="Opens default modal">
         <Alert variant="info">Addiitonal Header staff</Alert>
       </Modal.Header>
@@ -232,7 +234,7 @@ const ModalRemoteFormSubmission = (props: ComponentProps<typeof Modal>) => {
       </Modal.Trigger>
 
       <Modal.Content>
-        <Modal.Icon icon="rocket" color="red" />
+        <Modal.Icon color="red" icon={<Rocket />} />
 
         <Modal.Header title="Crate User" description="Opens modal with remote form submission" />
 
@@ -418,7 +420,7 @@ const ModalMultiStepContent = () => {
 
   return (
     <>
-      <Modal.Icon icon="rocket" color="blue" />
+      <Modal.Icon color="blue" icon={<Rocket />} />
       <Modal.Header title="Wizard Form" description="Opens modal with multi-step form" />
 
       <Modal.Body>

package/src/components/Modal/Modal.tsx

@@ -8,16 +8,42 @@ import { ModalHeader } from './ModalHeader';
 import { ModalIcon } from './ModalIcon';
 import { ModalOverlay } from './ModalOverlay';
 
+/**
+ * Props for the `Modal` root — forwarded to Radix `Dialog.Root` (controls `open`, `onOpenChange`,
+ * `defaultOpen`, `modal`).
+ */
 type Props = ComponentProps<typeof Root>;
 
+/**
+ * Blocking dialog for confirmations, forms, and detail views. Built on Radix Dialog.
+ *
+ * **When to use:** the user must act before continuing (confirm a destructive action, fill a short form,
+ * view a focused detail panel). Use the compound parts `Modal.Trigger`, `Modal.Content`, `Modal.Header`,
+ * `Modal.Body`, `Modal.Footer`, and optionally `Modal.Icon` for a status-coloured header glyph.
+ * **When NOT to use:** for slide-in side editing use `Sheet`; for an inline destructive confirmation anchored
+ * to its trigger use `Popconfirm`; for hover previews use `HoverCard`.
+ * **Composition:** wrap `Modal.Content` around `Modal.Header` + `Modal.Body` + `Modal.Footer`. Put `useAppForm`
+ * `FormBody` inside `Modal.Body` and the submit / cancel buttons inside `Modal.Footer`.
+ *
+ * @see RECIPES.md#modal-form — for the canonical form-in-modal composition
+ * @see RECIPES.md#confirm-dialog — for destructive-confirm dialogs
+ */
 export const Modal = (props: Props) => <Root {...props} />;
 
+/** Radix `Dialog.Close` re-export — closes the nearest `Modal` when clicked. Use `asChild` to wrap a `Button`. */
 Modal.Close = Close;
+/** Radix `Dialog.Trigger` re-export — opens the modal. Use `asChild` to wrap a `Button`. */
 Modal.Trigger = Trigger;
 
+/** Modal content container — portals into the overlay, handles sizing (`small` / `medium` / `large`) and open/close animation. */
 Modal.Content = ModalContent;
+/** Scrollable body slot. Place form fields or detail content here; takes available space inside `Modal.Content`. */
 Modal.Body = ModalBody;
+/** Status-coloured circular icon docked to the top-left of `Modal.Content`. Use `color="red"` for destructive, `"orange"` for warning, etc. */
 Modal.Icon = ModalIcon;
+/** Bottom action row. Place the primary + cancel `Button`s here; sits below `Modal.Body`. */
 Modal.Footer = ModalFooter;
+/** Top row with title, optional description, and close icon. Pass `title` / `description` props or nest custom JSX. */
 Modal.Header = ModalHeader;
+/** Backdrop overlay rendered behind `Modal.Content`. Normally implicit — only override for non-standard layouts. */
 Modal.Overlay = ModalOverlay;

package/src/components/Modal/ModalBody.tsx

@@ -2,10 +2,15 @@ import type { ComponentProps } from 'react';
 
 import { cn } from '../../utils';
 
+/** Props for `Modal.Body`. Accepts all `<div>` attributes; `as="form"` is reserved for future use. */
 type Props = ComponentProps<'div'> & {
   as?: 'form';
 };
 
+/**
+ * Scrollable body slot for `Modal`. Place form fields, content blocks, or detail panels here.
+ * Takes available height inside `Modal.Content` and scrolls when content overflows.
+ */
 export const ModalBody = ({ className, ...props }: Props) => (
   <div
     data-slot="modal-body"

package/src/components/Modal/ModalCloseIcon.tsx

@@ -1,8 +1,8 @@
 import type { ComponentProps } from 'react';
 import { Close } from '@radix-ui/react-dialog';
 
+import { X } from '../../icons';
 import { cn } from '../../utils';
-import { Icon } from '../Icon';
 
 type Props = ComponentProps<typeof Close>;
 
@@ -18,8 +18,7 @@ export const ModalCloseIcon = ({ className, ...rest }: Props) => (
       className,
     )}
   >
-    <Icon
-      icon="close"
+    <X
       className={cn(
         'tw-size-4',
         'tw-text-neutral-400',

package/src/components/Modal/ModalContent.tsx

@@ -5,8 +5,16 @@ import { cn } from '../../utils';
 
 import { ModalOverlay } from './ModalOverlay';
 
+/**
+ * Props for `Modal.Content`. `size` controls the max-width (`small` 480px / `medium` default / `large` 4xl).
+ * All other Radix `Dialog.Content` props (`onEscapeKeyDown`, `onPointerDownOutside`, …) pass through.
+ */
 type Props = ComponentProps<typeof Content> & { size?: 'small' | 'medium' | 'large' };
 
+/**
+ * Modal content surface — portals into the overlay and renders the header / body / footer slots.
+ * Stops escape-key propagation so a parent `FullScreenModal` does not also close.
+ */
 export const ModalContent = ({
   size = 'medium',
   className,

package/src/components/Modal/ModalFooter.tsx

@@ -2,8 +2,13 @@ import type { ComponentProps } from 'react';
 
 import { cn } from '../../utils';
 
+/** Props for `Modal.Footer`. Accepts all `<div>` attributes. */
 type Props = ComponentProps<'div'>;
 
+/**
+ * Bottom action row for `Modal`. Layout is up to the caller — typically `tw-flex tw-justify-end tw-gap-2`
+ * with cancel + primary `Button`s.
+ */
 export const ModalFooter = ({ className, ...props }: Props) => (
   <div
     className={cn(

package/src/components/Modal/ModalHeader.tsx

@@ -6,12 +6,23 @@ import { ModalCloseIcon } from './ModalCloseIcon';
 import { ModalDescription } from './ModalDescription';
 import { ModalTitle } from './ModalTitle';
 
+/**
+ * Props for `Modal.Header`. Pass `title` + optional `description` for the standard layout, or nest custom JSX
+ * as `children` to render below the title row.
+ */
 type Props = {
+  /** Title text rendered as `ModalTitle`. Wraps a Radix `Dialog.Title` for a11y. */
   title?: ReactNode;
+  /** Subtitle / supporting text rendered below the title. */
   description?: ReactNode;
+  /** Hide the top-right close icon. Use when the modal must not be dismissible by the icon (still closable via `Modal.Close`). */
   hideCloseIcon?: boolean;
 } & ComponentProps<'div'>;
 
+/**
+ * Modal header slot — title + description row with a built-in close icon.
+ * Renders a bottom border when followed by a `Modal.Body`; drops the border when body contains `Tabs`.
+ */
 export const ModalHeader = ({
   className,
   title,