@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/components/ui/.textarea.md

@@ -1,42 +1,52 @@
-<!-- source-hash: fb292df7a4c271bf8bfb904b650f406a -->
-A customizable textarea component built with React forwardRef that provides consistent styling and error state handling for form inputs in the Flamingo design system.
+<!-- source-hash: ec4ed0c801de7134f1ad25648dec0319 -->
+A client-side textarea component supporting labels, validation states, and optional end icons (as decorative spans or interactive buttons), built on top of `FieldWrapper`.
 
 ## Key Components
 
-- **TextareaProps**: Interface extending React's textarea attributes with an `invalid` prop for error states
-- **Textarea**: Forwardref component that renders a styled textarea with comprehensive visual states
-- **cn**: Utility function for conditional class name merging
+### `Textarea`
+A `React.forwardRef` component extending native `HTMLTextAreaElement` attributes with the following additional props:
 
-The component features dark theme styling, focus states with accent color rings, hover effects, and vertical resizing capability. Error states are handled through the `invalid` prop which applies red border styling.
+| Prop | Type | Description |
+|------|------|-------------|
+| `invalid` | `boolean` | Renders red error border/ring |
+| `label` | `string` | Label text above the textarea |
+| `error` | `string` | Error message below the textarea |
+| `endIcon` | `React.ReactNode` | Icon rendered at the right edge |
+| `endIconAsButton` | `boolean` | Wraps `endIcon` in a styled `<button>` |
+| `endIconButtonProps` | `ButtonHTMLAttributes` | Extra props for the end-icon button |
+
+**Two layout modes:**
+- **Without `endIcon`**: Border and background styles live directly on the `<textarea>` element.
+- **With `endIcon`**: A `<label>` wrapper hosts the border/background so the icon appears visually inside the field. The textarea uses `[field-sizing:content]` for native CSS auto-grow and caps height at `160px` with internal scroll.
 
 ## Usage Example
 
 ```typescript
-import { Textarea } from "./textarea"
-import { useState } from "react"
-
-function CommentForm() {
-  const [comment, setComment] = useState("")
-  const [hasError, setHasError] = useState(false)
-
-  return (
-    <div className="space-y-4">
-      <Textarea 
-        placeholder="Enter your comment..."
-        value={comment}
-        onChange={(e) => setComment(e.target.value)}
-        invalid={hasError}
-        rows={4}
-      />
-      
-      <Textarea
-        placeholder="Optional feedback"
-        className="min-h-[120px]"
-        disabled
-      />
-    </div>
-  )
-}
-```
-
-The component automatically handles focus management, supports all standard textarea attributes, and maintains visual consistency with the broader form input system through shared design tokens and responsive behaviors.
+// Basic textarea with label and validation
+<Textarea
+  label="Message"
+  placeholder="Type your message..."
+  error="Message is required"
+/>
+
+// Auto-growing textarea with a submit button icon
+<Textarea
+  label="Chat Input"
+  placeholder="Ask something..."
+  endIcon={<SendIcon />}
+  endIconAsButton
+  endIconButtonProps={{
+    'aria-label': 'Send message',
+    onClick: handleSend,
+    disabled: isLoading,
+  }}
+/>
+
+// Controlled with disabled state
+<Textarea
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+  disabled
+  rows={4}
+/>
+```

package/src/components/ui/.ticket-attachments-list.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 9fe959702866abb3d54c107fab70e0a4 -->
+Renders a styled list of file attachments for a support ticket, displaying thumbnail or file icon, name, size, and an optional download button per item.
+
+## Key Components
+
+- **`TicketAttachment`** — Interface describing a single attachment: `id`, `fileName`, `fileSize`, optional `thumbnailSrc`, and optional `onDownload` callback
+- **`TicketAttachmentsListProps`** — Props interface accepting an `attachments` array and optional `className`
+- **`TicketAttachmentsList`** — Main component that maps over attachments, rendering each row with a `SquareAvatar` (if thumbnail exists) or a fallback `FileIcon`, truncated filename, file size, and a download button
+
+## Usage Example
+
+```typescript
+import { TicketAttachmentsList, TicketAttachment } from "./ticket-attachments-list"
+
+const attachments: TicketAttachment[] = [
+  {
+    id: "1",
+    fileName: "screenshot.png",
+    fileSize: "1.2 MB",
+    thumbnailSrc: "https://cdn.example.com/thumb.png",
+    onDownload: () => console.log("Downloading screenshot.png"),
+  },
+  {
+    id: "2",
+    fileName: "error-log.txt",
+    fileSize: "48 KB",
+    onDownload: () => console.log("Downloading error-log.txt"),
+  },
+]
+
+export default function TicketDetail() {
+  return (
+    <TicketAttachmentsList
+      attachments={attachments}
+      className="mt-4"
+    />
+  )
+}
+```
+
+## Notes
+
+- Returns `null` when the `attachments` array is empty — safe to render unconditionally
+- Long filenames are truncated with CSS and exposed via the `title` attribute for full visibility on hover
+- Download button only renders when `onDownload` is provided

package/src/components/ui/.ticket-detail-section.md

@@ -0,0 +1,29 @@
+<!-- source-hash: cc870cf8d23036d002a435c07bd1d5aa -->
+A reusable layout component that renders a labeled section within a ticket detail view, pairing an uppercase secondary-text heading with arbitrary child content.
+
+## Key Components
+
+### `TicketDetailSection`
+A simple presentational component that wraps a section label and its associated content in a flex column layout.
+
+**Props (`TicketDetailSectionProps`):**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `string` | Section heading displayed in secondary text style |
+| `children` | `React.ReactNode` | Content rendered below the label |
+| `className` | `string?` | Optional additional CSS classes |
+
+## Usage Example
+
+```typescript
+import { TicketDetailSection } from "./ticket-detail-section"
+
+export function TicketDetails() {
+  return (
+    <TicketDetailSection label="Assigned To">
+      <span>John Doe</span>
+    </TicketDetailSection>
+  )
+}
+```

package/src/components/ui/.ticket-info-section.md

@@ -0,0 +1,56 @@
+<!-- source-hash: 25c594905e7f584756ad751975cbc35e -->
+A collapsible ticket information panel that displays key ticket metadata (organization, assignee, device, status) in a header row, with an expandable section revealing additional details like description, attachments, tags, and notes.
+
+## Key Components
+
+### `TicketInfoSection`
+Main export. Renders a bordered card with a responsive header grid and optional expanded content area.
+
+### `InfoCell` (internal)
+Reusable label/value display cell supporting an optional icon and clickable value.
+
+### `TicketInfoSectionProps`
+Full interface for the component:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `organization` | `{ name, imageSrc? }` | Org name and avatar |
+| `device` | `{ name, icon?, onClick? }` | Device name with optional navigation |
+| `status` | `string` | Rendered via `TicketStatusTag` |
+| `assigned` | `AssignedConfig` | Assignee dropdown config |
+| `expanded` | `boolean` | Controls expanded section visibility |
+| `onExpand` | `() => void` | Expand/collapse toggle handler |
+| `description` | `string` | Markdown/HTML content |
+| `attachments` | `TicketAttachment[]` | Downloadable file list |
+| `tags` | `string[]` | Label tags |
+| `notes` | `TicketNote[]` | Notes with add/edit/delete handlers |
+
+## Usage Example
+
+```typescript
+import { TicketInfoSection } from "./ticket-info-section"
+
+function TicketPage() {
+  const [expanded, setExpanded] = React.useState(false)
+
+  return (
+    <TicketInfoSection
+      organization={{ name: "Acme Corp", imageSrc: "/acme-logo.png" }}
+      device={{ name: "DESKTOP-XYZ01", onClick: () => router.push("/devices/1") }}
+      status="open"
+      expanded={expanded}
+      onExpand={() => setExpanded(prev => !prev)}
+      assigned={{
+        currentAssignee: { id: "u1", name: "Jane Doe" },
+        options: assigneeOptions,
+        onAssign: (userId) => handleAssign(userId),
+      }}
+      createdAt="Jan 15, 2025"
+      description="**Issue:** User cannot log in.\n\nSteps to reproduce..."
+      tags={["urgent", "auth"]}
+      notes={notes}
+      onAddNote={(text) => addNote(text)}
+    />
+  )
+}
+```

package/src/components/ui/.ticket-note-card.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 88db6ae7f82dae65095e5d817320bc8e -->
+A client-side React component that renders a single ticket note with inline editing, delete, and author attribution capabilities.
+
+## Key Components
+
+### Interfaces
+
+- **`TicketNote`** — Data model for a note, including `id`, `text`, `authorName`, `authorAvatar`, `createdAt`, and `isOwn` (controls edit/delete visibility)
+- **`TicketNoteCardProps`** — Component props accepting a `TicketNote`, optional `onEdit`/`onDelete` callbacks, and `className`
+
+### Component
+
+- **`TicketNoteCard`** — Stateful card component managing edit mode toggle, text input state, save/cancel/keyboard interactions (`Enter` to save, `Escape` to cancel)
+
+## Usage Example
+
+```typescript
+import { TicketNoteCard, TicketNote } from "./ticket-note-card"
+
+const note: TicketNote = {
+  id: "note-1",
+  text: "Customer confirmed the issue is reproducible on Windows only.",
+  authorName: "Jane Doe",
+  authorAvatar: "https://cdn.example.com/avatars/jane.png",
+  createdAt: "Jan 15, 2025",
+  isOwn: true,
+}
+
+function NoteList() {
+  const handleEdit = (id: string, text: string) => {
+    console.log("Updated note:", id, text)
+  }
+
+  const handleDelete = (id: string) => {
+    console.log("Deleted note:", id)
+  }
+
+  return (
+    <TicketNoteCard
+      note={note}
+      onEdit={handleEdit}
+      onDelete={handleDelete}
+      className="my-2"
+    />
+  )
+}
+```
+
+## Behavior Notes
+
+- Edit/delete actions are only rendered when `note.isOwn` is `true`
+- Save is disabled if the trimmed input is empty
+- Uses `SquareAvatar` for author display and `Input` for inline editing

package/src/components/ui/.ticket-notes-section.md

@@ -0,0 +1,54 @@
+<!-- source-hash: b7535dbf79220d22a1a0b0b0e1da828e -->
+A client-side React component that renders a list of ticket notes with an optional inline input for adding new notes.
+
+## Key Components
+
+### `TicketNotesSectionProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `notes` | `TicketNote[]` | Array of note objects to display |
+| `onAddNote` | `(text: string) => void` | Callback when a new note is submitted; omitting it hides the input UI |
+| `onEditNote` | `(id: string, text: string) => void` | Callback to update an existing note |
+| `onDeleteNote` | `(id: string) => void` | Callback to remove a note |
+| `isAddingNote` | `boolean` | Disables input and send button during async submission |
+| `className` | `string` | Additional CSS classes for the wrapper |
+
+### `TicketNotesSection`
+The default export. Manages local `noteText` state and exposes two submission paths:
+- **`Enter` key** (without `Shift`) triggers `handleSend`
+- **Send button** click triggers `handleSend`
+
+Both paths trim whitespace and short-circuit if the input is empty or `isAddingNote` is `true`.
+
+## Usage Example
+
+```typescript
+import { TicketNotesSection } from "./ticket-notes-section"
+import type { TicketNote } from "./ticket-note-card"
+
+const notes: TicketNote[] = [
+  { id: "1", text: "Checked network config", author: "Alice", createdAt: "2024-01-10" },
+]
+
+function TicketDetail() {
+  const [adding, setAdding] = React.useState(false)
+
+  const handleAdd = async (text: string) => {
+    setAdding(true)
+    await saveNote(text)
+    setAdding(false)
+  }
+
+  return (
+    <TicketNotesSection
+      notes={notes}
+      onAddNote={handleAdd}
+      onEditNote={(id, text) => updateNote(id, text)}
+      onDeleteNote={(id) => removeNote(id)}
+      isAddingNote={adding}
+    />
+  )
+}
+```
+
+> **Note:** The add-note input row only renders when `onAddNote` is provided, making the component usable in read-only contexts by simply omitting the prop.

package/src/components/ui/.ticket-status-tag.md

@@ -0,0 +1,49 @@
+<!-- source-hash: 5f8fd0a180217b9085f7ea5f038d319a -->
+Renders a styled badge for ticket statuses, normalizing any known status string (backend, chat, dialog-layer) into a canonical `TicketStatus` value with the correct color variant and optional icon.
+
+## Key Components
+
+### Types & Exports
+| Export | Description |
+|--------|-------------|
+| `TicketStatus` | Canonical union type: `'ACTIVE' \| 'TECH_REQUIRED' \| 'ON_HOLD' \| 'RESOLVED' \| 'ARCHIVED'` |
+| `TicketStatusTagProps` | Props interface for the main component |
+
+### Utility Functions
+| Function | Description |
+|----------|-------------|
+| `resolveTicketStatus(status)` | Maps any known alias to a canonical `TicketStatus`; returns `null` for unknowns |
+| `getTicketStatusConfig(status)` | Returns `{ label, variant, icon }` for a given status string |
+| `getTicketStatusTag(status)` | Drop-in utility returning label/variant/icon for use outside the component |
+
+### Component
+- **`TicketStatusTag`** — Wraps the base `Tag` component with resolved status config. Supports label override, hex `color` override with automatic contrast text, `showIcon` toggle, and additional `className`.
+
+## Usage Example
+
+```typescript
+// Basic usage
+<TicketStatusTag status="ACTIVE" />
+
+// With alias from dialog layer
+<TicketStatusTag status="ACTION_REQUIRED" />
+
+// HubSpot pipeline stage — custom label, canonical color
+<TicketStatusTag status="OPEN" label="Waiting on Contact" />
+
+// Hex color override (e.g. from a custom pipeline stage)
+<TicketStatusTag status="ON_HOLD" color="#7C3AED" />
+
+// Utility usage outside JSX
+const { label, variant } = getTicketStatusTag('resolved')
+// → { label: 'Resolved', variant: 'outline', icon: <CheckCircleIcon /> }
+```
+
+### Status → Variant Map
+| Status | Variant | Icon |
+|--------|---------|------|
+| `ACTIVE` | `success` | — |
+| `TECH_REQUIRED` | `warning` | — |
+| `ON_HOLD` | `error` | — |
+| `RESOLVED` | `outline` | ✅ CheckCircle |
+| `ARCHIVED` | `grey` | — |

package/src/components/ui/.title-content-block.md

@@ -1,41 +1,40 @@
-<!-- source-hash: 996ae0afe94f2dd7bb1173eb32a69763 -->
-A flexible React component for displaying title-content pairs with consistent typography and spacing, commonly used for labeled data displays and section headings.
+<!-- source-hash: 63aa69e366662eef49a80f4c013e6522 -->
+A reusable React component that renders a labeled content block with a title and content element, supporting configurable typography, spacing, and semantic HTML elements.
 
 ## Key Components
 
-- **`TitleContentBlock`** - Main component that renders a title above content with customizable styling
-- **`TitleContentBlockProps`** - TypeScript interface defining all component props including styling and semantic options
-- **`spacingMap`** - Internal mapping object for consistent vertical spacing between title and content
+### `TitleContentBlock`
+The main export — a client-side React component that pairs a title label with a primary content value.
+
+### `TitleContentBlockProps`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | — | Label/title text |
+| `content` | `React.ReactNode` | — | Primary content value |
+| `titleColor` | `string` | `text-ods-text-secondary` | Tailwind color class for title |
+| `titleClassName` | `string` | `text-h5 tracking-[-0.28px]` | Additional title styles |
+| `contentClassName` | `string` | `text-h2 tracking-[-0.64px] text-ods-text-primary` | Content element styles |
+| `containerClassName` | `string` | `''` | Wrapper `div` styles |
+| `titleAs` | `h1–h6 \| div` | `div` | Semantic element for the title |
+| `contentAs` | `h1–h6 \| p \| div` | `h4` | Semantic element for the content |
+| `spacing` | `sm \| md \| lg` | `md` | Vertical gap between title and content |
 
 ## Usage Example
 
 ```typescript
-import { TitleContentBlock } from './title-content-block';
-
-// Basic usage with default styling
+// Basic usage — stat or metric display
 <TitleContentBlock
-  title="Project Status"
-  content="In Progress"
+  title="Total Devices"
+  content="1,248"
 />
 
-// Advanced usage with custom styling and semantic elements
+// Custom semantic elements and spacing
 <TitleContentBlock
-  title="Revenue"
-  content="$1,234,567"
+  title="Active Tickets"
+  content={<span className="text-red-500">42</span>}
   titleAs="h3"
   contentAs="p"
   spacing="lg"
-  titleColor="text-blue-600"
-  contentClassName="text-green-600 font-bold text-xl"
-  containerClassName="p-4 bg-gray-50 rounded"
+  containerClassName="p-4 rounded-lg bg-ods-surface"
 />
-
-// Dynamic content example
-<TitleContentBlock
-  title="User Count"
-  content={<span>{userCount.toLocaleString()}</span>}
-  spacing="sm"
-/>
-```
-
-The component uses Azeret Mono font family by default and provides three spacing options (sm/md/lg) with responsive text sizing. Both title and content elements can be rendered as different HTML tags for proper semantic structure.
+```

package/src/components/ui/.toaster.md

@@ -1,45 +1,57 @@
-<!-- source-hash: ba005812ae189473256085a9a1a1fafd -->
-A React client-side component that provides a customized toast notification system using Sonner with theme-aware styling.
+<!-- source-hash: 1847d3dd263a7c340149cc9157774ef5 -->
+A client-side toast notification system built on top of [Sonner](https://sonner.emilkowal.ski/), providing styled toast components with variant support, progress indicators, and a specialized command approval flow.
 
 ## Key Components
 
-- **Toaster**: Main component that renders the Sonner toast container with custom positioning and styling
-- Positioned at bottom-right with custom CSS classes for consistent theming
-- Supports different toast types (error, success, warning, info) with distinct visual styles
+| Export | Type | Description |
+|--------|------|-------------|
+| `Toaster` | Component | Root provider wrapping Sonner's `Toaster`; injects the `toast-progress` keyframe animation |
+| `ToastCard` | Component | Standard toast card with title, description, colored dot indicator, dismiss button, and animated progress bar |
+| `CommandApprovalToast` | Component | Expandable toast with Approve/Reject actions for AI command authorization flows |
+| `showToast` | Function | Imperative helper to fire a `ToastCard` toast |
+| `showCommandApprovalToast` | Function | Imperative helper to fire a `CommandApprovalToast` |
+| `ToastVariant` | Type | `'default' \| 'success' \| 'warning' \| 'error' \| 'info'` |
 
 ## Usage Example
 
+**Mount the provider once (root layout):**
+
 ```typescript
-import { Toaster } from './toaster'
-import { toast } from 'sonner'
+import { Toaster } from '@/components/toaster'
 
-// Include in your app layout
-function Layout({ children }: { children: React.ReactNode }) {
+export default function RootLayout({ children }) {
   return (
-    <div>
+    <>
       {children}
-      <Toaster />
-    </div>
+      <Toaster position="bottom-right" />
+    </>
   )
 }
+```
 
-// Trigger toasts from anywhere in your app
-function MyComponent() {
-  const handleSuccess = () => {
-    toast.success('Operation completed successfully!')
-  }
+**Fire a standard toast:**
 
-  const handleError = () => {
-    toast.error('Something went wrong')
-  }
+```typescript
+import { showToast } from '@/components/toaster'
 
-  return (
-    <div>
-      <button onClick={handleSuccess}>Success Toast</button>
-      <button onClick={handleError}>Error Toast</button>
-    </div>
-  )
-}
+showToast({ title: 'Saved', description: 'Changes saved successfully.', variant: 'success' })
+
+// Shorthand
+showToast('Operation complete')
+```
+
+**Request command approval (Mingo AI flow):**
+
+```typescript
+import { showCommandApprovalToast } from '@/components/toaster'
+
+showCommandApprovalToast({
+  command: 'apt-get upgrade -y',
+  toolType: 'terminal',
+  approvalDescription: 'This will upgrade all system packages.',
+  onApprove: () => executeCommand(),
+  onReject: () => cancelJob(),
+})
 ```
 
-The component uses ODS (design system) CSS custom properties for consistent theming across toast states, with semi-transparent backgrounds and matching borders for visual hierarchy.
+> `CommandApprovalToast` defaults to `duration: Infinity` so it persists until the technician explicitly approves or rejects the action.

package/src/components/ui/.tooltip.md

@@ -1,27 +1,34 @@
-<!-- source-hash: a3607c1ea05dad72d4bcf94d01e56f46 -->
-A React tooltip component built on Radix UI primitives with dark theme styling and maximum z-index for overlay visibility.
+<!-- source-hash: 7a9da2d80c73e939b410ce27e719aa66 -->
+Accessible tooltip component built on Radix UI primitives, providing animated, portal-rendered tooltips with consistent ODS (OpenFrame Design System) styling.
 
 ## Key Components
 
-- **TooltipProvider** - Context provider for tooltip functionality
-- **Tooltip** - Root tooltip container component
-- **TooltipTrigger** - Element that triggers the tooltip on hover/focus
-- **TooltipContent** - Styled tooltip content with portal rendering and animations
+| Export | Type | Description |
+|--------|------|-------------|
+| `TooltipProvider` | Component | Context provider required at the app/layout level to manage tooltip state |
+| `Tooltip` | Component | Root wrapper controlling open/close behavior |
+| `TooltipTrigger` | Component | Element that activates the tooltip on hover/focus |
+| `TooltipContent` | Component | Styled content panel rendered in a portal with enter/exit animations |
 
 ## Usage Example
 
 ```typescript
-import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tooltip"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
 
-function App() {
+export function ActionButton() {
   return (
     <TooltipProvider>
       <Tooltip>
         <TooltipTrigger asChild>
           <button>Hover me</button>
         </TooltipTrigger>
-        <TooltipContent>
-          <p>This is a tooltip message</p>
+        <TooltipContent side="top">
+          <p>Helpful context here</p>
         </TooltipContent>
       </Tooltip>
     </TooltipProvider>
@@ -29,4 +36,8 @@ function App() {
 }
 ```
 
-The component features a dark theme with `#1A1A1A` background, smooth fade/zoom animations, and maximum z-index (`2147483647`) to ensure tooltips appear above all other content. The content automatically positions itself relative to the trigger with a 4px offset and includes directional slide animations.
+## Notes
+
+- `TooltipContent` defaults to `sideOffset={4}` and supports all four sides (`top`, `bottom`, `left`, `right`) with direction-aware slide-in animations via Tailwind data attributes.
+- Content is injected via a **portal**, ensuring correct stacking context (`z-[1400]`) above modals and overlays.
+- `TooltipProvider` should be placed high in the component tree (e.g., root layout) to avoid nesting multiple providers unnecessarily.

package/src/components/ui/.truncate-text.md

@@ -0,0 +1,39 @@
+<!-- source-hash: 8d0022286e01a2ce895c17613d9cae17 -->
+Renders truncated text using ODS typography tokens, displaying a `FloatingTooltip` with the full content only when overflow is detected via `ResizeObserver`.
+
+## Key Components
+
+- **`TruncateText`** — Main export. Wraps a `<span>` with overflow detection and conditionally enables a tooltip.
+- **`TruncateTextProps`** — Interface defining all configuration options.
+- **`TruncateTextVariant`** — Union type (`'h1'`–`'h6'`) mapping to ODS typography utilities.
+- **`TruncateTextTone`** — Union type (`'primary'` | `'secondary'`) mapping to ODS text colour utilities.
+- **Overflow detection** — Uses `ResizeObserver` to re-check truncation on container resize; single-line uses `scrollWidth`, multi-line uses `scrollHeight`.
+
+## Usage Example
+
+```typescript
+// Single-line truncation (default h4 / primary)
+<TruncateText>{deviceName}</TruncateText>
+
+// Secondary caption style with custom tooltip side
+<TruncateText variant="h6" tone="secondary" side="bottom">
+  {email}
+</TruncateText>
+
+// Multi-line clamp with custom tooltip content
+<TruncateText lines={3} tooltip={<span>Full description here</span>}>
+  {longDescription}
+</TruncateText>
+
+// Monospace heading font, forced secondary tone
+<TruncateText variant="h5" tone="secondary" mono>
+  {ticketId}
+</TruncateText>
+```
+
+## Behaviour Notes
+
+- Tooltip is **disabled** until actual overflow occurs — no tooltip shown for short strings.
+- `lines={1}` applies Tailwind `truncate` (single-line ellipsis); `lines={2–6}` applies `line-clamp-N`.
+- `tooltip` prop defaults to `children` when omitted.
+- The `mono` prop swaps the font family to `--font-family-heading` while preserving the variant's size scale.