@djangocfg/ui-tools 2.1.430 → 2.1.431

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.430",
+  "version": "2.1.431",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -329,8 +329,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.430",
-    "@djangocfg/ui-core": "^2.1.430",
+    "@djangocfg/i18n": "^2.1.431",
+    "@djangocfg/ui-core": "^2.1.431",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -405,9 +405,9 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.430",
-    "@djangocfg/typescript-config": "^2.1.430",
-    "@djangocfg/ui-core": "^2.1.430",
+    "@djangocfg/i18n": "^2.1.431",
+    "@djangocfg/typescript-config": "^2.1.431",
+    "@djangocfg/ui-core": "^2.1.431",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^25.2.3",

package/src/tools/chat/README.md

@@ -49,6 +49,8 @@ export function MyChat() {
 - **Personas.** `config.user` + `config.assistant` for default identity; `message.sender` for per-message overrides.
 - **Audio.** Pass `audio: ChatAudioConfig` (sounds map) to `<ChatLauncher>` — the hook runs internally. Built on `@djangocfg/ui-core/hooks/useNotificationSounds`: Safari unlock, persisted mute, per-event toggles, reduced-motion respect. Slack/Linear-style per-event volume scale (error ≈ 0.25, mention ≈ 1.0). **Built-in sounds bundled as base64 data URLs** in the lazy chat chunk (~136KB) — `audio={{}}` just works. `silenced` + `onSoundEvent` for native hosts (cmdop_go / Tauri).
 - **Rich attachments.** `AttachmentsGrid` for thumbnails, `AttachmentsList` for custom renderers; `onAttachmentOpen` for lightbox.
+- **Unified attach pipeline.** Paperclip, `+` menu, drag-drop and ⌘V/Ctrl+V all funnel through one validated path (`useComposerAttach`); set `showAttachmentButton` / `attach` and the composer ships its own picker. Optional `uploadFn` is the only web/Wails seam.
+- **Paste-as-chunk.** A long plain-text paste (over `attach.pasteTextThreshold`, default 2000 chars — ChatGPT/Claude behaviour) becomes a `type:'text'` "Pasted text" attachment chip instead of flooding the textarea. The chip opens a read-only `PastedTextDialog` preview (rendered via `MarkdownMessage`); the exact payload rides in `ChatAttachment.text` to `onSubmit(content, attachments)`. Toggle with `attach.pasteTextAsChunk`.
 - **Tool-payload dispatcher.** `dispatchToolPayload(matchers, fallback)` — pluggable predicates render `<LazyJsonTree>` / `<LazyMap>` / etc.
 - **Persisted dock prefs.** `headerSlots.modeToggle.persistAs: 'my.key'` stores `mode` / `side` / `width` in localStorage; the toggle lets users flip popover ↔ side and survives reloads. (`useChatDockPrefs()` is now owned by the launcher internally — no longer a consumer-facing hook.)
 - **UX guards.** Auto-focus composer on dock open, two-step Escape (textarea blur → close), click-to-focus on empty message area **and** on the composer surface padding (Slack / Linear / ChatGPT style), `useHotkey('mod+/')` toggle.
@@ -1023,6 +1025,14 @@ type ComposerModelPickerProps, type ComposerModelOption,
 type ComposerBannerProps, type ComposerBannerAction, type ComposerRichTextareaProps,
 type ComposerTextareaProps, type SendButtonProps, type AttachButtonProps
 
+// Attach pipeline — picker + drag-drop + ⌘V (files) + paste-as-chunk (text)
+useComposerAttach, useComposerAttachContext,
+fileToAttachment, revokeAttachmentUrl,
+textToAttachment, deriveTextTitle, DEFAULT_PASTE_TEXT_THRESHOLD,
+PastedTextDialog,
+type ComposerAttachConfig, type ComposerAttachHandle, type ComposerAcceptType,
+type ComposerUploadFn, type ComposerUploadResult, type PastedTextDialogProps
+
 // Message blocks
 MessageBlocks, createBlockRegistry, BUILTIN_BLOCK_REGISTRY
 type MessageBlock, type BlockAppearance, type BlockRegistry,
@@ -1095,3 +1105,14 @@ Recommended pairing for a "vehicle cards" / "tax breakdown" / "chart" widget on
 - `Shift+Enter` — newline.
 - `Esc` — cancel current streaming turn (when focused inside the composer).
 - Launcher hotkey: configurable via `<ChatLauncher hotkey={…}>` (e.g. `⌘/`).
+
+## Related — conversation-history sidebar
+
+`ChatRoot` renders a single conversation; the **list of past sessions**
+(the left sidebar in desktop chat apps) is app-owned, not part of this
+tool. The recommended way to render it is the **`Tree`** tool with
+`appearance={{ variant: 'list' }}` — a macOS-sidebar look (no file icons,
+auto-height rows for *title + meta*, quiet selection) with collapsible
+group branches (e.g. Today / Yesterday / … or by topic) and a built-in
+right-click menu (rename / delete). See `data/Tree/README.md` → *Variant —
+explorer vs list*. cmdop's `SessionsTree` is the reference consumer.

package/src/tools/chat/composer/PastedTextDialog.tsx

@@ -0,0 +1,88 @@
+'use client';
+
+import { useMemo } from 'react';
+import { FileText } from 'lucide-react';
+
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { MarkdownMessage } from '../../dev/code/MarkdownMessage';
+
+export interface PastedTextDialogProps {
+  /** Whether the dialog is open. */
+  open: boolean;
+  /** Open-state change handler (Esc / overlay click / close button). */
+  onOpenChange: (open: boolean) => void;
+  /** The raw pasted text to preview. */
+  text: string;
+  /** Short title shown in the header (the chip's derived title). */
+  title?: string;
+}
+
+/**
+ * Read-only preview for a "Pasted text" attachment chunk.
+ *
+ * Renders the raw paste through `MarkdownMessage` — the same chat-tuned
+ * renderer used for message bubbles, so fenced code blocks, tables and
+ * GFM all come out formatted, with the plain-text fast path kicking in
+ * for prose-only pastes. View-only by design: there is no edit affordance.
+ *
+ * Built on ui-core's radix `Dialog` primitive with local open-state — it
+ * does not touch the global `dialog-service` (that service is shaped for
+ * imperative string-message alerts/confirms, not arbitrary content). The
+ * caller owns `open` so the chip can drive it from a click.
+ */
+export function PastedTextDialog({
+  open,
+  onOpenChange,
+  text,
+  title,
+}: PastedTextDialogProps) {
+  // A rough size hint for the header (chars / KB) — cheap, derived.
+  const meta = useMemo(() => {
+    const chars = text.length;
+    const kb = new Blob([text]).size / 1024;
+    return kb >= 1
+      ? `${chars.toLocaleString()} chars · ${kb.toFixed(1)} KB`
+      : `${chars.toLocaleString()} chars`;
+  }, [text]);
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent
+        className={cn(
+          'flex max-h-[80dvh] w-full max-w-2xl flex-col gap-3 p-0',
+        )}
+        // This is a read-only preview — there is no primary action to
+        // focus. radix would otherwise autofocus the first focusable node,
+        // which is the (visually hover-hidden) "Copy" button inside the
+        // markdown code block — surfacing a stray focus ring on open.
+        // Prevent the default and keep focus on the panel itself; Esc /
+        // overlay click still dismiss, and Tab reaches controls normally.
+        onOpenAutoFocus={(e) => e.preventDefault()}
+      >
+        <DialogHeader className="shrink-0 space-y-1 border-b border-border px-5 pb-3 pt-5 text-left">
+          <DialogTitle className="flex items-center gap-2 text-base">
+            <span className="grid size-7 shrink-0 place-items-center rounded-md bg-primary/15 text-primary">
+              <FileText aria-hidden className="size-4" />
+            </span>
+            <span className="min-w-0 truncate">{title ?? 'Pasted text'}</span>
+          </DialogTitle>
+          <p className="pl-9 text-xs text-muted-foreground">{meta}</p>
+        </DialogHeader>
+
+        {/* Scrollable body — `MarkdownMessage` formats the paste. */}
+        <div className="min-h-0 flex-1 overflow-y-auto px-5 pb-5">
+          <MarkdownMessage content={text} size="sm" />
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export default PastedTextDialog;

package/src/tools/chat/composer/index.ts

@@ -40,6 +40,15 @@ export {
 } from './useComposerAttach';
 export { useComposerAttachContext } from './AttachContext';
 export { fileToAttachment, revokeAttachmentUrl } from './fileToAttachment';
+export {
+  textToAttachment,
+  deriveTextTitle,
+  DEFAULT_PASTE_TEXT_THRESHOLD,
+} from './textToAttachment';
+export {
+  PastedTextDialog,
+  type PastedTextDialogProps,
+} from './PastedTextDialog';
 export {
   parseSlashState,
   filterCommands,

package/src/tools/chat/composer/textToAttachment.ts

@@ -0,0 +1,69 @@
+/**
+ * `string → ChatAttachment` — the producer for "Pasted text" chunks.
+ *
+ * When a long paste is converted into an attachment chip instead of
+ * being dumped into the textarea (ChatGPT/Claude behaviour), the raw
+ * text is minted into a `type:'text'` attachment. Its payload lives in
+ * `text` (exact, newline-preserving); `url` is empty since there is no
+ * blob backing it.
+ *
+ * Mirrors `fileToAttachment` so the picker, drag-drop, file-paste and
+ * text-paste paths all funnel into the same `ChatAttachment` shape.
+ */
+
+import { createId } from '../core/ids';
+import type { ChatAttachment } from '../types';
+
+/** Default character threshold above which a paste becomes a chunk. */
+export const DEFAULT_PASTE_TEXT_THRESHOLD = 2000;
+
+/** Max length of the auto-derived title (first non-empty line). */
+const TITLE_MAX = 32;
+
+/**
+ * Derive a short, human-readable title from the pasted text — the first
+ * non-empty line, collapsed and ellipsised (e.g. "Valuing the Bali Vec…").
+ * Falls back to a generic label for whitespace-only / empty input.
+ */
+export function deriveTextTitle(text: string): string {
+  const firstLine = text
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .find((l) => l.length > 0);
+  if (!firstLine) return 'Pasted text';
+  // Strip leading markdown markers (heading `#`, blockquote `>`, list
+  // bullets `-`/`*`/`+`) so a markdown paste reads as plain text on the
+  // chip — the title is a label, not source. The payload is untouched.
+  const stripped = firstLine
+    .replace(/^#{1,6}\s+/, '')
+    .replace(/^>\s+/, '')
+    .replace(/^[-*+]\s+/, '')
+    .trim();
+  // Collapse internal runs of whitespace so a title never wraps oddly.
+  const collapsed = (stripped || firstLine).replace(/\s+/g, ' ');
+  return collapsed.length > TITLE_MAX
+    ? `${collapsed.slice(0, TITLE_MAX).trimEnd()}…`
+    : collapsed;
+}
+
+/**
+ * Convert a pasted string into a `type:'text'` `ChatAttachment`.
+ *
+ * - `name`  — short title derived from the first line (shown on the chip).
+ * - `text`  — the full, exact payload (sent to `onSubmit` alongside the
+ *             message content).
+ * - `url`   — empty: text chunks have no blob backing.
+ * - `sizeBytes` — UTF-8 byte length, for an optional "N chars / KB" hint.
+ */
+export function textToAttachment(text: string): ChatAttachment {
+  return {
+    id: createId('att'),
+    type: 'text',
+    url: '',
+    name: deriveTextTitle(text),
+    mimeType: 'text/plain',
+    sizeBytes: new Blob([text]).size,
+    status: 'ready',
+    text,
+  };
+}

package/src/tools/chat/composer/types.ts

@@ -198,6 +198,19 @@ export interface ComposerAttachConfig {
   pasteEnabled?: boolean;
   /** Called when a file is rejected (size / type / count). */
   onReject?: (file: File, reason: 'size' | 'type' | 'count') => void;
+  /**
+   * Convert a long plain-text paste (⌘V / Ctrl+V) into a "Pasted text"
+   * attachment chip instead of dumping it into the textarea — the
+   * ChatGPT/Claude behaviour. Default `true`. Short pastes (below
+   * {@link pasteTextThreshold}) always go straight into the textarea.
+   */
+  pasteTextAsChunk?: boolean;
+  /**
+   * Character threshold above which a plain-text paste becomes a chunk.
+   * Default `2000` (matches Claude / LibreChat). Ignored when
+   * `pasteTextAsChunk` is `false`.
+   */
+  pasteTextThreshold?: number;
 }
 
 /** Imperative handle the attach pipeline exposes to the composer + menu. */

package/src/tools/chat/composer/useComposerAttach.tsx

@@ -5,6 +5,10 @@ import { useCallback, useEffect, useMemo, useRef, type RefObject } from 'react';
 import { buildAcceptString, useClipboardPaste } from '../../forms/Uploader';
 import type { UseChatComposerReturn } from '../hooks/useChatComposer';
 import { fileToAttachment, revokeAttachmentUrl } from './fileToAttachment';
+import {
+  DEFAULT_PASTE_TEXT_THRESHOLD,
+  textToAttachment,
+} from './textToAttachment';
 import type {
   ComposerAcceptType,
   ComposerAttachConfig,
@@ -59,6 +63,8 @@ export function useComposerAttach({
     maxSizeBytes,
     multiple = true,
     pasteEnabled = true,
+    pasteTextAsChunk = true,
+    pasteTextThreshold = DEFAULT_PASTE_TEXT_THRESHOLD,
     uploadFn,
     onReject,
   } = config;
@@ -187,6 +193,47 @@ export function useComposerAttach({
     pasteScopeRef,
   );
 
+  // Long-text paste → "Pasted text" chunk. A separate listener from the
+  // file path above: `useClipboardPaste` deliberately ignores pastes
+  // that carry text into a text field (so it doesn't hijack typing), so
+  // it never sees this case. We intercept here, before the browser
+  // inserts the text into the textarea, and mint a `type:'text'`
+  // attachment instead — the ChatGPT/Claude behaviour.
+  const pasteTextEnabled = pasteEnabled && pasteTextAsChunk && !disabled;
+  useEffect(() => {
+    if (!pasteTextEnabled) return undefined;
+    const target: HTMLElement | Document = pasteScopeRef?.current ?? document;
+
+    const onPaste = (e: Event) => {
+      const ev = e as ClipboardEvent;
+      const cd = ev.clipboardData;
+      if (!cd) return;
+      // Only chunk pastes aimed at the composer's editable surface —
+      // a paste into some unrelated input inside the scope is left alone.
+      const node = ev.target;
+      const el =
+        node instanceof HTMLElement ? node : null;
+      const isEditable =
+        el != null &&
+        (el instanceof HTMLTextAreaElement ||
+          el instanceof HTMLInputElement ||
+          el.isContentEditable);
+      if (!isEditable) return;
+      // A file/blob paste is the image path's job — don't steal it.
+      if (Array.from(cd.items).some((i) => i.kind === 'file')) return;
+      const text = cd.getData('text/plain');
+      if (text.length < pasteTextThreshold) return;
+      // Respect the file-count cap (text chunks share the attachment list).
+      const c = composerRef.current;
+      if (maxFiles != null && c.attachments.length >= maxFiles) return;
+      e.preventDefault();
+      c.addAttachment(textToAttachment(text));
+    };
+
+    target.addEventListener('paste', onPaste);
+    return () => target.removeEventListener('paste', onPaste);
+  }, [pasteTextEnabled, pasteTextThreshold, maxFiles, pasteScopeRef]);
+
   // On unmount, free any object-URLs still held by staged attachments
   // (drafts abandoned without sending). `composerRef` gives the latest
   // list without re-running the effect on every attach.

package/src/tools/chat/messages/Attachments.tsx

@@ -1,10 +1,11 @@
 'use client';
 
-import { type ReactNode } from 'react';
-import { File as FileIcon, X } from 'lucide-react';
+import { type ReactNode, useState } from 'react';
+import { File as FileGlyph, FileText, X } from 'lucide-react';
 
 import { cn } from '@djangocfg/ui-core/lib';
 
+import { PastedTextDialog } from '../composer/PastedTextDialog';
 import { useChatDestructiveStyles } from '../styles';
 import type { ChatAttachment } from '../types';
 
@@ -19,6 +20,7 @@ export interface AttachmentRendererArgs {
 export type AttachmentRenderer = (args: AttachmentRendererArgs) => ReactNode;
 
 export interface AttachmentRendererMap {
+  text?: AttachmentRenderer;
   image?: AttachmentRenderer;
   audio?: AttachmentRenderer;
   video?: AttachmentRenderer;
@@ -143,6 +145,12 @@ export function Attachments(props: AttachmentsProps) {
 // ---------------------------------------------------------------------------
 
 function AttachmentTile({ attachment, onClick, onRemove }: AttachmentRendererArgs) {
+  // "Pasted text" chunks are self-contained — they open their own preview
+  // dialog on click rather than going through the generic `onClick`.
+  if (attachment.type === 'text') {
+    return <TextChunkTile attachment={attachment} onRemove={onRemove} />;
+  }
+
   const isImage = attachment.type === 'image';
   const isUploading = attachment.status === 'uploading';
 
@@ -150,12 +158,15 @@ function AttachmentTile({ attachment, onClick, onRemove }: AttachmentRendererArg
     <img
       src={attachment.thumbnailUrl ?? attachment.url}
       alt={attachment.name ?? 'attachment'}
-      className="h-16 w-16 rounded-md object-cover"
+      // `--radius-control` (~10px) — the design-system token for value
+      // chips / controls (see ui-core base.css). Keeps every chip rounded
+      // consistently, a touch softer than the old `rounded-md`.
+      className="h-16 w-16 rounded-[var(--radius-control)] object-cover"
       loading="lazy"
     />
   ) : (
-    <div className="flex max-w-44 items-center gap-2 rounded-md border border-border bg-background/60 px-2 py-1.5 text-xs">
-      <FileIcon aria-hidden className="size-4 shrink-0 text-muted-foreground" />
+    <div className="flex max-w-44 items-center gap-2 rounded-[var(--radius-control)] border border-border bg-background/60 px-2 py-1.5 text-xs">
+      <FileGlyph aria-hidden className="size-4 shrink-0 text-muted-foreground" />
       <span className="truncate">{attachment.name ?? 'file'}</span>
     </div>
   );
@@ -163,14 +174,20 @@ function AttachmentTile({ attachment, onClick, onRemove }: AttachmentRendererArg
   return (
     <div className="relative">
       {onClick ? (
-        <button type="button" onClick={onClick} className="block">
+        // Interactive only when the host wired `onClick` — only then does
+        // the chip read as clickable (cursor + hover lift + focus ring).
+        <button
+          type="button"
+          onClick={onClick}
+          className="block cursor-pointer rounded-[var(--radius-control)] transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50"
+        >
           {inner}
         </button>
       ) : (
         inner
       )}
       {isUploading ? (
-        <div className="pointer-events-none absolute inset-0 flex items-center justify-center rounded-md bg-background/70 text-[10px] font-medium">
+        <div className="pointer-events-none absolute inset-0 flex items-center justify-center rounded-[var(--radius-control)] bg-background/70 text-[10px] font-medium">
           {attachment.progress != null ? `${Math.round(attachment.progress * 100)}%` : '…'}
         </div>
       ) : null}
@@ -179,6 +196,53 @@ function AttachmentTile({ attachment, onClick, onRemove }: AttachmentRendererArg
   );
 }
 
+/**
+ * Tile for a `type:'text'` chunk — a two-line "Pasted text" chip in the
+ * same surface style as file chips (title + "Pasted text" sublabel).
+ * Clicking it opens a read-only `PastedTextDialog` preview of the full
+ * payload. Mirrors ChatGPT's pasted-text card + click-to-expand.
+ */
+function TextChunkTile({
+  attachment,
+  onRemove,
+}: {
+  attachment: ChatAttachment;
+  onRemove?: () => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const title = attachment.name ?? 'Pasted text';
+  return (
+    <div className="relative">
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        aria-label={`Preview ${title}`}
+        className="block cursor-pointer rounded-[var(--radius-control)] text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50"
+      >
+        <div className="flex max-w-56 items-center gap-2 rounded-[var(--radius-control)] border border-border bg-background/60 px-2 py-1.5 transition-colors hover:bg-background">
+          {/* Inner glyph plate keeps the tighter `rounded-md` — a nested
+              surface should round a notch less than its container
+              (concentric radii) so the corners read cleanly. */}
+          <span className="grid size-7 shrink-0 place-items-center rounded-md bg-primary/15 text-primary">
+            <FileText aria-hidden className="size-4" />
+          </span>
+          <span className="flex min-w-0 flex-col">
+            <span className="truncate text-xs font-medium">{title}</span>
+            <span className="truncate text-[11px] text-muted-foreground">Pasted text</span>
+          </span>
+        </div>
+      </button>
+      {onRemove ? <RemoveBtn onRemove={onRemove} /> : null}
+      <PastedTextDialog
+        open={open}
+        onOpenChange={setOpen}
+        text={attachment.text ?? ''}
+        title={title}
+      />
+    </div>
+  );
+}
+
 function RemoveBtn({ onRemove }: { onRemove: () => void }) {
   const styles = useChatDestructiveStyles();
   return (
@@ -187,7 +251,7 @@ function RemoveBtn({ onRemove }: { onRemove: () => void }) {
       aria-label="Remove attachment"
       onClick={onRemove}
       className={cn(
-        'absolute -right-1.5 -top-1.5 grid h-4 w-4 place-items-center rounded-full border border-border bg-background text-muted-foreground',
+        'absolute -right-1.5 -top-1.5 grid h-4 w-4 cursor-pointer place-items-center rounded-full border border-border bg-background text-muted-foreground',
         styles.hoverStrong,
       )}
     >

package/src/tools/chat/types/attachment.ts

@@ -4,7 +4,11 @@
 
 export interface ChatAttachment {
   id: string;
-  type: 'image' | 'file' | 'audio' | 'video';
+  type: 'image' | 'file' | 'audio' | 'video' | 'text';
+  /**
+   * Object-URL / remote URL for binary attachments. Empty string for
+   * `type:'text'` chunks — those carry their payload in `text`, not a URL.
+   */
   url: string;
   thumbnailUrl?: string;
   name?: string;
@@ -15,6 +19,13 @@ export interface ChatAttachment {
   progress?: number;
   /** Extracted text from images (OCR). */
   ocrText?: string;
+  /**
+   * Raw text payload for `type:'text'` chunks — the "Pasted text"
+   * attachment minted when a long paste is converted into a chip
+   * instead of dumped into the textarea (ChatGPT/Claude behaviour).
+   * Preserves exact content: newlines, indentation, stack traces.
+   */
+  text?: string;
 }
 
 export interface ChatSource {

package/src/tools/data/Tree/README.md

@@ -376,6 +376,7 @@ Defaults are English. Function-shaped entries (`confirmDeleteTitle(count)`, `con
 ```tsx
 <TreeRoot
   appearance={{
+    variant: 'explorer',      // 'explorer' (default) | 'list'
     density: 'cozy',          // 'compact' | 'cozy' | 'comfortable'
     accent: 'default',        // 'subtle' | 'default' | 'strong'
     radius: 'sm',             // 'none' | 'sm' | 'md'
@@ -387,6 +388,35 @@ Defaults are English. Function-shaped entries (`confirmDeleteTitle(count)`, `con
 />
 ```
 
+### Variant — `explorer` vs `list`
+
+`variant` is a high-level look that sets sensible defaults for three
+fields (`hideLeafIcons`, `hideFolderIcons`, `rowSizing`,
+`showActiveIndicator`); any of those passed explicitly still wins.
+
+| Variant | Look | Defaults |
+| --- | --- | --- |
+| `'explorer'` (default) | Classic file/folder tree | leaf + folder icons, **fixed** single-line rows, active bar on |
+| `'list'` | macOS-sidebar / **chat-history** list | **no icons** (chevron only on groups), **auto-height** rows (multi-line label friendly), quiet selection (no active bar) |
+
+```tsx
+// A grouped chat-history sidebar (date / topic buckets → sessions),
+// multi-line rows (title + dimmed meta), no file glyphs:
+<TreeRoot<Payload>
+  data={groupedSessions}
+  getItemName={(n) => label(n)}
+  appearance={{ variant: 'list', indent: 10 }}
+  showIndentGuides={false}
+  renderLabel={({ node }) => /* title + meta */ null}
+/>
+```
+
+Fine-grained fields (override the variant):
+
+- `hideLeafIcons` / `hideFolderIcons` — drop the per-row icon (chevron stays).
+- `rowSizing: 'fixed' | 'auto'` — `auto` turns `rowHeight` into a *minimum*
+  so a multi-line label grows the row instead of overflowing.
+
 The resolved appearance is exposed on the root container as CSS variables:
 
 ```

package/src/tools/data/Tree/components/TreeRow.tsx

@@ -175,7 +175,16 @@ function TreeRowRaw<T>({ row, className }: TreeRowProps<T>) {
       tabIndex={-1}
       style={{
         paddingLeft: 6 + level * appearance.indent,
-        height: 'var(--tree-row-height)',
+        // `auto` sizing lets a multi-line label (e.g. title + meta in a
+        // chat-history list) grow the row instead of overflowing a fixed
+        // height. `fixed` keeps the classic single-line explorer row.
+        ...(appearance.rowSizing === 'auto'
+          ? {
+              minHeight: 'var(--tree-row-height)',
+              paddingTop: 4,
+              paddingBottom: 4,
+            }
+          : { height: 'var(--tree-row-height)' }),
         gap: 'var(--tree-gap)',
       }}
       {...(dnd.active ? draggable.listeners : {})}
@@ -234,7 +243,7 @@ function TreeRowRaw<T>({ row, className }: TreeRowProps<T>) {
         />
       ) : renderIcon ? (
         renderIcon(slot)
-      ) : (
+      ) : (isFolder ? appearance.hideFolderIcons : appearance.hideLeafIcons) ? null : (
         <TreeIcon isFolder={isFolder} isExpanded={isExpanded} />
       )}