@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/ui/.tag-search-input.md

@@ -1,26 +1,25 @@
-<!-- source-hash: 96e461088a5374855c0977550d1322c9 -->
-A controlled search input component that combines inline tag chips with a text input, supporting automatic or fixed tag overflow with a popup for hidden tags.
+<!-- source-hash: bcb66dcc5b0a6be0721e936daa39f1ef -->
+A controlled search input component that combines inline tag display with a text search field, supporting overflow handling for tags that exceed available width.
 
 ## Key Components
 
 ### `TagSearchOption<T>`
-Generic interface representing a selectable tag with a `label` string and typed `value`.
+Generic interface representing a selectable tag with a `label` (display string) and `value` (typed payload, defaults to `string`).
 
 ### `TagSearchInputProps<T>`
-Full props interface for the component, including:
-- `tags` / `searchValue` — controlled state inputs
-- `onSearchChange` / `onTagRemove` / `onClearAll` — mutation callbacks
-- `limitTags` — `number | "auto"` (default `"auto"`) controls visible tag count
+Full prop interface for the component, including:
+- `tags` / `searchValue` — controlled state for active tags and input text
+- `onTagRemove` / `onSearchChange` / `onClearAll` — mutation callbacks
+- `limitTags` — `number | "auto"` controlling visible tag count (defaults to `"auto"` for width-based calculation)
 - `renderTag` / `getLimitTagsText` — render customization slots
-- `onSubmit` / `onKeyDown` — keyboard event hooks
 
 ### `TagSearchInput<T>`
-The main generic component. Renders a styled input container with:
-- **Visible tags** — rendered as `<Tag>` chips up to `visibleCount`
-- **Overflow badge** — a `+N` button that toggles a `HiddenTagsPopup`
-- **Text input** — flex-grows into remaining space
-- **Clear all button** — pinned right, appears when input or tags have values
-- **Off-screen measurement divs** — used by `useAutoLimitTags` to compute available width
+The main generic component. Renders a styled input row with:
+- A pinned **search icon** (left)
+- A **middle zone** containing visible tags, an overflow `+N` badge, and the text input
+- A pinned **clear-all button** (right, conditional)
+- A **`HiddenTagsPopup`** anchored below the `+N` badge for overflow tags
+- Off-screen **measurement containers** used by `useAutoLimitTags` to compute visible tag count
 
 ## Usage Example
 
@@ -28,9 +27,9 @@ The main generic component. Renders a styled input container with:
 import { TagSearchInput, TagSearchOption } from "./tag-search-input"
 
 const options: TagSearchOption<number>[] = [
-  { label: "Windows", value: 1 },
-  { label: "macOS", value: 2 },
-  { label: "Linux", value: 3 },
+  { label: "Billing", value: 1 },
+  { label: "Networking", value: 2 },
+  { label: "Security", value: 3 },
 ]
 
 function FilterBar() {
@@ -42,12 +41,13 @@ function FilterBar() {
       tags={tags}
       searchValue={search}
       onSearchChange={setSearch}
-      onTagRemove={(val) => setTags((prev) => prev.filter((t) => t.value !== val))}
+      onTagRemove={(id) => setTags((prev) => prev.filter((t) => t.value !== id))}
       onClearAll={() => { setTags([]); setSearch("") }}
       onSubmit={(val) => console.log("submitted:", val)}
       limitTags="auto"
-      placeholder="Filter devices..."
     />
   )
 }
-```
+```
+
+**Source:** [`tag-search-input.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tag-search-input.tsx)

package/src/components/ui/.tag-select-dropdown.md

@@ -0,0 +1,59 @@
+<!-- source-hash: eb8b620b4c2ca28727d63d877a8d803a -->
+A multi-select tag picker rendered as a button-triggered Radix UI popover, featuring inline search/filter, checkable tag rows, optional inline tag creation, and per-row delete actions.
+
+## Key Components
+
+### `TagSelectDropdown`
+The main exported component. Opens a popover containing:
+- **Search input** — filters options in real time; `Enter` triggers creation when applicable
+- **Option list** — selected tags float to the top, each row shows a check icon when active and a hover-revealed trash icon when `onDelete` is provided
+- **Create row** — appears when the search query doesn't match any existing tag; enforces `maxCreateLength` with an inline error
+
+### Interfaces
+
+| Export | Purpose |
+|---|---|
+| `TagSelectOption` | `{ id: string; label: string }` — shape of each selectable tag |
+| `TagSelectDropdownProps` | Full prop surface for the dropdown |
+
+### Key Props
+
+| Prop | Type | Description |
+|---|---|---|
+| `options` | `TagSelectOption[]` | All available tags |
+| `selectedIds` | `string[]` | IDs of currently selected tags |
+| `onChange` | `(ids: string[]) => void` | Called with next full selection on toggle |
+| `onCreate` | `(name: string) => void` | Enables inline creation row when provided |
+| `onDelete` | `(id: string) => void` | Enables per-row trash button when provided |
+| `maxCreateLength` | `number` | Optional character cap for new tag names |
+| `isCreating` / `isDeleting` | `boolean` | Disables create/delete buttons during async ops |
+
+## Usage Example
+
+```typescript
+import { TagSelectDropdown, TagSelectOption } from './tag-select-dropdown'
+
+const ALL_TAGS: TagSelectOption[] = [
+  { id: '1', label: 'Urgent' },
+  { id: '2', label: 'Billing' },
+  { id: '3', label: 'Hardware' },
+]
+
+function TagPicker() {
+  const [selected, setSelected] = React.useState<string[]>(['1'])
+
+  return (
+    <TagSelectDropdown
+      options={ALL_TAGS}
+      selectedIds={selected}
+      onChange={setSelected}
+      onCreate={(name) => console.log('Create tag:', name)}
+      onDelete={(id) => console.log('Delete tag:', id)}
+      maxCreateLength={30}
+      triggerLabel="Add Tags"
+    />
+  )
+}
+```
+
+> Selected tag chips are rendered by the caller — this component only manages the picker UI and fires `onChange` with the updated ID array.

package/src/components/ui/.tag.md

@@ -1,58 +1,40 @@
-<!-- source-hash: af3df5d03b971509e29cd6ef6c4c1640 -->
-A client-side Tag component for displaying labeled badges with optional icons and dismissal functionality, built on `class-variance-authority` for variant-based styling.
+<!-- source-hash: 7790074c969073b4d437a54cd0ebac37 -->
+A polymorphic chip/tag UI component with multiple visual variants, sizes, and optional icon/close button support.
 
 ## Key Components
 
-- **`Tag`** — Main component rendering a styled badge with support for icons, labels, and a close button
-- **`tagVariants`** — CVA variant config exported for external reuse; supports 7 visual styles
-- **`TagProps`** — Interface extending `HTMLAttributes<HTMLDivElement>` with tag-specific props
-
-### Variants
-
-| Variant | Use Case |
-|---------|----------|
-| `primary` | Default yellow highlight |
-| `outline` | Dark background with border |
-| `success` | Green success state |
-| `warning` | Yellow warning state |
-| `error` | Red soft error state |
-| `critical` | Solid red critical alert |
-| `grey` | Neutral/muted state |
-
-### Props
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `label` | `React.ReactNode` | Required tag text or content |
-| `variant` | `TagVariant` | Visual style (default: `primary`) |
-| `icon` | `React.ReactNode` | Optional leading icon |
-| `onClose` | `() => void` | Renders dismiss button when provided |
-| `disabled` | `boolean` | Applies disabled styling and prevents interaction |
-| `labelClassName` | `string` | Additional classes for the label span |
+- **`tagVariants`** — `cva` variant config defining two sizes (`default` 32px, `large` 48px) and nine visual variants: `primary`, `outline`, `success`, `warning`, `error`, `critical`, `grey`, `selected`, `selectedCyan`, and `badge`.
+- **`TagProps`** — Interface extending `HTMLAttributes<HTMLDivElement>` with `label`, optional `icon`, `onClose`, `disabled`, `labelClassName`, and `as` (root element override).
+- **`Tag`** — The main component. Renders an icon slot, a truncating label, and an optional close button with `XmarkCircleIcon`.
 
 ## Usage Example
 
 ```typescript
+import { Tag } from "./tag"
+
 // Basic tag
 <Tag label="Active" variant="success" />
 
-// With icon and close button
+// With icon and close handler
 <Tag
-  label="Urgent"
-  variant="critical"
-  icon={<AlertIcon />}
-  onClose={() => removeTag("urgent")}
+  label="Billing"
+  variant="outline"
+  icon={<BillingIcon />}
+  onClose={() => handleRemove("billing")}
 />
 
+// Large selected chip (e.g. tab group)
+<Tag label="Monitoring" variant="selected" size="large" />
+
+// Inline tag inside paragraph content (avoids invalid div-in-p hydration)
+<Tag label="Beta" variant="badge" as="span" />
+
 // Disabled state
-<Tag
-  label="Unavailable"
-  variant="outline"
-  disabled
-/>
+<Tag label="Archived" variant="grey" disabled />
+```
+
+## Notes
 
-// Using tagVariants externally
-<div className={cn(tagVariants({ variant: "warning" }), "custom-class")}>
-  Custom element
-</div>
-```
+- The `as` prop accepts `'div'` (default) or `'span'` — use `'span'` when the tag appears inside phrasing content (e.g. `<p>`) to avoid invalid HTML and hydration errors.
+- `disabled` applies pointer-events-none and muted styling via `disabledTagClasses` and sets `aria-disabled`.
+- The close `<button>` calls `e.stopPropagation()` before invoking `onClose`, preventing unintended parent click handlers from firing.

package/src/components/ui/.tags-input.md

@@ -1,51 +1,51 @@
-<!-- source-hash: 9eb10752292d24eee24cde4356bcc193 -->
-A React component that provides an interactive tags input interface, allowing users to add, remove, and manage a collection of string tags with keyboard shortcuts and validation.
+<!-- source-hash: 9db0eafa66563a94111378c7cb3be888 -->
+A client-side React component for managing a list of string tags with add/remove functionality, keyboard support, and optional tag limits.
 
 ## Key Components
 
-- **TagsInput**: Main component that manages tag state and user interactions
-- **handleAddTag**: Adds new tags with duplicate checking and max limit validation
-- **handleRemoveTag**: Removes tags from the collection
-- **handleKeyPress**: Enables Enter key for adding tags
-- **TagsInputProps**: Interface defining component configuration options
+### `TagsInput` (exported function)
+
+A controlled input component that renders a text field with an "Add" button, a collection of removable badge tags, and an optional tag counter.
+
+**Props (`TagsInputProps`):**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string[]` | `[]` | Current list of tags (controlled) |
+| `onChange` | `(tags: string[]) => void` | — | Callback fired when tags change |
+| `placeholder` | `string` | `"Add a tag..."` | Input placeholder text |
+| `className` | `string` | — | Wrapper `div` class override |
+| `disabled` | `boolean` | `false` | Disables input and remove buttons |
+| `maxTags` | `number` | — | Maximum number of allowed tags |
+| `inputClassName` | `string` | — | Additional classes for the `Input` |
+| `badgeClassName` | `string` | — | Additional classes for each `Badge` |
+| `label` | `string` | — | Optional label rendered above the input |
+
+**Behaviors:**
+- Duplicate tags are silently rejected
+- Tags are added via the **Add** button or by pressing `Enter`
+- Input and Add button are automatically disabled when `maxTags` is reached
+- A `{current}/{max} tags` counter is shown when `maxTags` is set
 
 ## Usage Example
 
 ```typescript
-import { TagsInput } from "./tags-input"
+import { TagsInput } from "@/components/ui/tags-input"
 import { useState } from "react"
 
-function MyForm() {
-  const [tags, setTags] = useState<string[]>([])
+export function MyForm() {
+  const [tags, setTags] = useState<string[]>(["typescript", "react"])
 
   return (
     <TagsInput
+      label="Technologies"
       value={tags}
       onChange={setTags}
-      label="Skills"
-      placeholder="Add a skill..."
+      placeholder="Add a technology..."
       maxTags={5}
-      className="w-full"
-      badgeClassName="bg-blue-100 text-blue-800"
-    />
-  )
-}
-
-// With initial tags
-function PrefilledTags() {
-  const [technologies, setTechnologies] = useState([
-    "React", "TypeScript", "Node.js"
-  ])
-
-  return (
-    <TagsInput
-      value={technologies}
-      onChange={setTechnologies}
-      placeholder="Add technology..."
-      disabled={false}
     />
   )
 }
 ```
 
-The component features duplicate prevention, optional tag limits, keyboard navigation, customizable styling, and accessibility support with proper ARIA labels.
+**Source:** [`tags-input.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tags-input.tsx)

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

@@ -1,52 +1,54 @@
-<!-- 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`.
+<!-- source-hash: c699d2d9dc6f460390da123be652dd71 -->
+A client-side textarea component with optional label, error state, and start/end icon adornments. Supports both a bare layout (border on the `<textarea>` itself) and an adorned layout (border lifted onto a `<label>` wrapper) that auto-sizes via CSS `field-sizing: content`.
 
 ## Key Components
 
-### `Textarea`
-A `React.forwardRef` component extending native `HTMLTextAreaElement` attributes with the following additional props:
+| Export | Type | Description |
+|---|---|---|
+| `Textarea` | `React.ForwardRefExoticComponent` | Main textarea with full design-system styling |
+| `TextareaProps` | `interface` | Extends `React.TextareaHTMLAttributes<HTMLTextAreaElement>` |
 
-| 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 |
+### `TextareaProps` notable fields
 
-**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.
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `invalid` | `boolean` | `false` | Renders red error border and ring |
+| `label` | `string` | — | Label rendered above the field |
+| `error` | `string` | — | Error message below the field; also sets invalid state |
+| `startIcon` | `ReactNode` | — | Adornment at the left edge (renders verbatim) |
+| `endIcon` | `ReactNode` | — | Adornment at the right edge |
+| `endIconAsButton` | `boolean` | `false` | Wraps `endIcon` in a styled `<button>` |
+| `endIconButtonProps` | `ButtonHTMLAttributes` | — | Extra props for the end-icon button |
+| `hideBorder` | `boolean` | `false` | Suppresses border/bg/radius (outer container owns chrome) |
 
 ## Usage Example
 
 ```typescript
-// Basic textarea with label and validation
+import { Textarea } from "@openframe-oss-lib/ui"
+import { SendIcon, PlusIcon } from "lucide-react"
+
+// Basic textarea with validation
 <Textarea
   label="Message"
-  placeholder="Type your message..."
+  placeholder="Type your message…"
   error="Message is required"
 />
 
-// Auto-growing textarea with a submit button icon
+// Composer-style with start + end icons
 <Textarea
-  label="Chat Input"
-  placeholder="Ask something..."
+  placeholder="Ask anything…"
+  startIcon={<PlusIcon />}
   endIcon={<SendIcon />}
   endIconAsButton
   endIconButtonProps={{
-    'aria-label': 'Send message',
+    "aria-label": "Send message",
     onClick: handleSend,
-    disabled: isLoading,
+    disabled: isPending,
   }}
+  hideBorder
 />
+```
 
-// Controlled with disabled state
-<Textarea
-  value={value}
-  onChange={(e) => setValue(e.target.value)}
-  disabled
-  rows={4}
-/>
-```
+## Source
+
+[`textarea.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/textarea.tsx)

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

@@ -1,45 +1,52 @@
-<!-- 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.
+<!-- source-hash: f1475c50075c22f933c4db727027b907 -->
+Renders a bordered list of ticket file attachments with optional thumbnail previews, delete, and download actions.
 
 ## 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
+### Interfaces
+
+- **`TicketAttachment`** — Describes a single attachment entry:
+  - `id` — Unique identifier
+  - `fileName` — Display name
+  - `fileSize` — Human-readable size string
+  - `thumbnailSrc?` — Optional image preview URL
+  - `onDownload?` — Callback to trigger file download
+  - `onDelete?` — When provided, renders a trash button before the download button
+
+- **`TicketAttachmentsListProps`** — Component props:
+  - `attachments` — Array of `TicketAttachment` objects
+  - `className?` — Optional wrapper class override
+  - `size?` — `'default'` (full-row layout) | `'compact'` (reduced padding/icons for in-message rendering)
+
+### Component
+
+- **`TicketAttachmentsList`** — Returns `null` if the attachment array is empty. Renders each attachment as a row with a thumbnail (via `SquareAvatar`) or a generic `FileIcon` fallback, filename, file size, and optional delete/download buttons.
 
 ## Usage Example
 
 ```typescript
-import { TicketAttachmentsList, TicketAttachment } from "./ticket-attachments-list"
+import { TicketAttachmentsList } from "@openframe-oss-lib/components"
 
-const attachments: TicketAttachment[] = [
+const attachments = [
   {
-    id: "1",
+    id: "att-1",
     fileName: "screenshot.png",
-    fileSize: "1.2 MB",
+    fileSize: "142 KB",
     thumbnailSrc: "https://cdn.example.com/thumb.png",
-    onDownload: () => console.log("Downloading screenshot.png"),
+    onDownload: () => downloadFile("att-1"),
+    onDelete: () => deleteAttachment("att-1"),
   },
   {
-    id: "2",
-    fileName: "error-log.txt",
-    fileSize: "48 KB",
-    onDownload: () => console.log("Downloading error-log.txt"),
+    id: "att-2",
+    fileName: "report.pdf",
+    fileSize: "1.2 MB",
+    onDownload: () => downloadFile("att-2"),
   },
 ]
 
-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
+// Full-row layout (e.g. ticket detail panel)
+<TicketAttachmentsList attachments={attachments} />
+
+// Compact layout (e.g. inside a conversation message)
+<TicketAttachmentsList attachments={attachments} size="compact" />
+```

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

@@ -1,56 +1,51 @@
-<!-- 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.
+<!-- source-hash: 7ac50b47361449080e2ba3874b959c5f -->
+A collapsible ticket information panel that displays key ticket metadata (organization, assignee, device, status) in a compact header row, with an expandable section revealing description, attachments, tags, and notes.
 
 ## Key Components
 
 ### `TicketInfoSection`
-Main export. Renders a bordered card with a responsive header grid and optional expanded content area.
+The main exported component rendering a two-state panel:
+- **Collapsed:** Header grid showing organization avatar, assignee dropdown (or unassigned state), device info, status tag, and expand toggle.
+- **Expanded:** Reveals created date, markdown description, file attachments, tag chips, and a full notes section with add/edit/delete support.
 
 ### `InfoCell` (internal)
-Reusable label/value display cell supporting an optional icon and clickable value.
+A small layout primitive rendering a value + label pair with an optional icon. Renders the value as a clickable `<button>` when an `onClick` handler is provided.
 
 ### `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 |
+The full prop interface, including:
+- `statusOptions` / `onStatusSelect` / `isStatusPending` — inline status changer
+- `assigned` — nested object powering the `AssigneeDropdown`
+- `attachments`, `tags`, `notes`, `onAddNote`, `onEditNote`, `onDeleteNote` — expanded-view content
 
 ## 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)}
-    />
-  )
-}
-```
+<TicketInfoSection
+  organization={{ name: "Acme Corp", imageSrc: "/logos/acme.png" }}
+  device={{ name: "MacBook Pro", onClick: () => router.push("/devices/123") }}
+  status="open"
+  statusLabel="Open"
+  statusOptions={[
+    { id: "open", label: "Open" },
+    { id: "closed", label: "Closed" },
+  ]}
+  onStatusSelect={(id) => updateStatus(id)}
+  assigned={{
+    currentAssignee: { id: "u1", name: "Jane Smith" },
+    options: assigneeList,
+    onAssign: (userId) => assignTicket(userId),
+  }}
+  expanded={isExpanded}
+  onExpand={() => setIsExpanded((v) => !v)}
+  description="## Issue\nUser cannot log in after password reset."
+  tags={["network", "priority-high"]}
+  notes={ticketNotes}
+  onAddNote={(text) => addNote(text)}
+/>
+```
+
+## Source
+
+[`ticket-info-section.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ticket-info-section.tsx)

package/src/components/ui/.ticket-status-config-row.md

@@ -0,0 +1,66 @@
+<!-- source-hash: af0402d9923c0e0c41315794a7eff4a9 -->
+A client-side React component that renders a single row in a ticket status configuration UI, supporting both system-defined and custom ticket statuses with drag-and-drop reordering, color picking, and delete controls.
+
+## Key Components
+
+### `TicketStatusConfigRow`
+The primary exported component. Renders a row containing:
+- **Drag handle** — interactive for custom rows, decorative/disabled for system rows
+- **Name input** — editable for custom, read-only for system rows
+- **Color controls** — `ColorPresetSelect` and `ColorPickerInput` shown only for custom rows with color support
+- **Live preview** — `TicketStatusTag` reflecting current name and color
+- **Action button** — info tooltip icon for system rows; delete button (with optional disabled state tooltip) for custom rows
+
+### `WithLeftTooltip` (internal)
+A touch-aware tooltip wrapper that ensures only one tooltip is open at a time via a module-level `dismissOpenTooltip` ref. Renders children unchanged when no `content` is provided.
+
+### `TicketStatusConfigRowProps`
+The full props interface, key fields:
+
+| Prop | Description |
+|---|---|
+| `variant` | `'system'` or `'custom'` — controls editability and available actions |
+| `statusKey` | Canonical key forwarded to `TicketStatusTag` |
+| `onColorChange` | Callback receiving `{ color, preset? }` |
+| `dragHandleProps` / `dragHandleAttributes` | From `@dnd-kit/core` for drag-and-drop |
+| `deleteDisabledReason` | Shown as tooltip when delete is disabled |
+| `isDragging` | Applies visual feedback during drag |
+
+## Usage Example
+
+```typescript
+import { TicketStatusConfigRow } from './ticket-status-config-row'
+
+// Custom row with color picker and delete
+<TicketStatusConfigRow
+  variant="custom"
+  statusKey="row-uuid-123"
+  name={statusName}
+  onNameChange={setStatusName}
+  color={color}
+  presetKey={preset}
+  onColorChange={({ color, preset }) => {
+    setColor(color)
+    setPreset(preset)
+  }}
+  onDelete={handleDelete}
+  deleteDisabled={isOnlyStatus}
+  deleteDisabledReason="At least one status is required"
+  dragHandleProps={listeners}
+  dragHandleAttributes={attributes}
+  isDragging={isDragging}
+/>
+
+// System row (read-only, no delete)
+<TicketStatusConfigRow
+  variant="system"
+  statusKey="RESOLVED"
+  name="Resolved"
+  systemTooltip="Built-in status — cannot be removed"
+  systemTagVariant="outline"
+/>
+```
+
+## Source
+
+[`ticket-status-config-row.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ticket-status-config-row.tsx)