@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482-snapshot.20260725230219

package/src/components/ui/.image-uploader.md

@@ -1,25 +1,24 @@
-<!-- source-hash: 7a3018246d0e272d26eee450458f6d52 -->
-A client-side React component that renders a drag-and-drop / click-to-upload image input with preview, replace, and remove functionality. Wraps a hidden `<input type="file">` with validation, loading states, and accessible keyboard interaction.
+<!-- source-hash: 9d7d8b6fd8b5c3617d4c8d6239c931f0 -->
+A client-side React component providing a drag-and-drop / click-to-upload image input with preview, validation, and loading states, wrapped in a `FieldWrapper` for consistent field labeling and error display.
 
 ## Key Components
 
-- **`ImageUploader`** — Main export. Renders the dropzone or image preview depending on whether `value` is set.
-- **`ActionIconButton`** — Internal button used for the "Replace" and "Remove" overlay actions on the image preview.
-- **`formatSize(bytes)`** — Utility that formats a byte count as a human-readable `KB`/`MB` string.
-- **`matchesAccept(file, accept)`** — Validates a `File` against an `accept` string (MIME types and extensions).
+### `ImageUploader` (main export)
+The primary component. Renders an empty dropzone or image preview depending on whether `value` is set.
 
-## Key Props (`ImageUploaderProps`)
+**Key behaviors:**
+- **Empty state** — shows a labeled dropzone with click, keyboard (`Enter`/`Space`), and drag-and-drop support
+- **Preview state** — displays the uploaded image with overlay action buttons (replace / remove)
+- **Loading state** — renders a spinner overlay (on preview) or centered spinner (on empty dropzone)
+- **Validation** — enforces `accept` MIME/extension matching and `maxSize` before calling `onChange`
+- **Auth-aware image rendering** — uses `useAuthedImageSrc` to resolve gateway URLs requiring `Authorization` headers
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `value` | `string` | Current image URL; triggers preview state when set |
-| `onChange` | `(file: File) => void` | Called with the selected/dropped `File` after validation |
-| `onRemove` | `() => void` | Shows trash icon when provided; called on click |
-| `accept` | `string` | Accepted MIME types/extensions. Default: `"image/*"` |
-| `maxSize` | `number` | Max file size in bytes. Default: 25 MB |
-| `aspectRatio` | `string` | CSS aspect-ratio override (e.g. `"16 / 9"`) |
-| `loading` | `boolean` | Shows spinner overlay and disables interaction |
-| `error` | `string` | External error message (internal validation errors take precedence) |
+### `ActionIconButton` (internal)
+Small icon button rendered over the image preview for replace/remove actions. Propagation-safe (`e.stopPropagation()`).
+
+### Helpers (internal)
+- `formatSize(bytes)` — formats byte counts as `KB`/`MB` strings
+- `matchesAccept(file, accept)` — validates a `File` against an `accept` attribute pattern
 
 ## Usage Example
 
@@ -27,12 +26,15 @@ A client-side React component that renders a drag-and-drop / click-to-upload ima
 import { ImageUploader } from "@/components/ui/image-uploader"
 import { useState } from "react"
 
-export function CoverImageField() {
+function CoverImageField() {
   const [imageUrl, setImageUrl] = useState<string | undefined>()
+  const [uploading, setUploading] = useState(false)
 
   const handleChange = async (file: File) => {
+    setUploading(true)
     const url = await uploadToStorage(file) // your upload logic
     setImageUrl(url)
+    setUploading(false)
   }
 
   return (
@@ -40,14 +42,29 @@ export function CoverImageField() {
       value={imageUrl}
       onChange={handleChange}
       onRemove={() => setImageUrl(undefined)}
-      aspectRatio="16 / 9"
-      maxSize={5 * 1024 * 1024} // 5 MB
       fieldLabel="Cover Image"
-      label="Upload a cover photo"
       description="Click or drag and drop"
+      maxSize={10 * 1024 * 1024} // 10 MB
+      aspectRatio="16 / 9"
+      loading={uploading}
     />
   )
 }
 ```
 
-> **Note:** `onChange` receives the raw `File` — the consumer is responsible for uploading it to a server or object storage and updating `value` with the resulting URL.
+## Props Summary
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — | Current image URL; presence triggers preview state |
+| `onChange` | `(file: File) => void` | required | Called after validation passes |
+| `onRemove` | `() => void` | — | Shows remove button when provided |
+| `maxSize` | `number` | `25MB` | Max file size in bytes |
+| `accept` | `string` | `"image/*"` | MIME types or extensions |
+| `aspectRatio` | `string` | — | CSS aspect-ratio (overrides fixed height) |
+| `objectFit` | `string` | `"cover"` | Preview image fit mode |
+| `loading` | `boolean` | `false` | Spinner overlay + disables interaction |
+| `disabled` | `boolean` | `false` | Disables all interaction |
+| `dropzoneClassName` | `string` | — | Override dropzone sizing/styles |
+
+**Source:** [`image-uploader.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/image-uploader.tsx)

package/src/components/ui/.index.md

@@ -1,25 +1,23 @@
-<!-- source-hash: 69fabf50cc24470b1828f706f8765a69 -->
-Central barrel export file for the UI kit library, re-exporting all client-side UI components organized by category (form inputs, layout, navigation, feedback, tables, chat, and more).
+<!-- source-hash: f088145dd2b6ba6e8e59ee78bce57fe6 -->
+Central barrel export file for the `ui-kit` component library, re-exporting all UI components organized by category for consumption by other packages or applications.
 
 ## Key Components
 
-Organized into the following categories:
-
-| Category | Notable Exports |
-|---|---|
-| **Form / Input** | `Button`, `Input`, `Select`, `Checkbox`, `DatePicker`, `TagsInput`, `RadioGroup`, `Switch` |
-| **Layout** | `Dialog`, `Modal`, `ModalV2`, `Sheet`, `Drawer`, `Tabs`, `Separator` |
-| **Navigation** | `Accordion`, `Breadcrumb`, `DropdownMenu`, `NavigationMenu`, `TabNavigation` |
-| **Feedback** | `Alert`, `Badge`, `Progress`, `StatusBadge`, `Toaster`, `StatusIndicator` |
-| **Table** | `Table`, `TableRow`, `TableCell`, `TableHeader`, `TableEmptyState`, `TableTimestampCell` |
-| **Query Report** | `QueryReportTable`, `deriveColumns`, `exportToCSV` |
-| **DataTable** | Headless TanStack Table-based replacement for legacy `Table` |
-| **Pagination** | `CursorPagination`, `CursorPaginationSimple` |
-| **Search / Filter** | `SearchInput`, `FilterList`, `TagSearchInput`, `TagKeyValueFilter` |
-| **Chat / Layout** | `chat`, `ListPageLayout`, `PageContainer`, `PageLayout` |
-| **Ticket** | `TicketStatusTag`, `AssigneeDropdown`, `TicketNoteCard`, `SimpleMarkdownRenderer` |
-| **Media / Upload** | `FileUpload`, `ImageUploader`, `MediaTypeSelector` |
-| **Misc** | `FloatingTooltip`, `TruncateText`, `CircularProgress`, `Skeleton`, `Slider` |
+Exports are grouped into the following categories:
+
+- **UI Components** — form inputs (`input`, `select`, `checkbox`, `textarea`, `date-picker`), display primitives (`button`, `card`, `badge`, `label`), and specialized inputs (`tags-input`, `phone-input`, `password-input`, `markdown-editor`)
+- **Layout** — `modal`, `modal-v2`, `dialog`, `drawer`, `sheet`, `alert-dialog`, `aspect-ratio`, `separator`
+- **Navigation** — `accordion`, `breadcrumb`, `dropdown-menu`, `navigation-menu`, `tabs`, `tab-navigation`
+- **Feedback** — `alert`, `toaster`, `progress`, `skeleton`, `status-badge`, `status-indicator`
+- **Table** — `Table`, `TableRow`, `TableCell`, `TableHeader`, `TableEmptyState`, `TableTimestampCell`, `TableDescriptionCell` with full TypeScript types
+- **QueryReportTable** — `QueryReportTable`, `deriveColumns`, `exportToCSV` for dynamic osquery result rendering
+- **DataTable** — headless TanStack Table-based replacement for legacy `Table`
+- **Pagination** — `CursorPagination`, `CursorPaginationSimple`
+- **Chat & Layout** — `chat`, `list-page-layout`, `page-container`, `page-heading`, `page-layout`, `article-detail-layout`
+- **Search & Filters** — `search-input`, `filter-list`, `filter-checkbox-item`, `tag-key-value-filter`, `hidden-tags-popup`
+- **Ticket** — `ticket-status-tag`, `ticket-note-card`, `ticket-attachments-list`, `assignee-dropdown`
+- **Markdown** — `markdown-editor`, `simple-markdown-renderer`, `RichMarkdownRenderer`
+- **File Upload** — `file-upload`, `image-uploader`
 
 ## Usage Example
 
@@ -27,26 +25,30 @@ Organized into the following categories:
 import {
   Button,
   Input,
-  Select,
   Table,
   TableRow,
   TableCell,
   CursorPagination,
-  StatusBadge,
   QueryReportTable,
-  deriveColumns,
-} from '@your-org/ui-kit'
-
-function DeviceTable({ data, pagination }) {
-  const columns = deriveColumns(data)
+  RichMarkdownRenderer,
+  StatusBadge,
+} from '@openframe/ui-kit'
 
+// Use any exported component directly
+function MyPage() {
   return (
-    <>
-      <QueryReportTable columns={columns} rows={data} />
-      <CursorPagination {...pagination} />
-    </>
+    <div>
+      <Input placeholder="Search..." />
+      <Button variant="primary">Submit</Button>
+      <StatusBadge status="active" />
+      <CursorPagination {...paginationProps} />
+    </div>
   )
 }
 ```
 
-> **Note:** This file is marked `"use client"` — all exported components are client-side only and require a React environment with client rendering support (e.g. Next.js App Router).
+> **Note:** This file is marked `"use client"`, meaning all exported components are React Client Components compatible with Next.js App Router.
+
+## Source
+
+[`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

package/src/components/ui/.info-card-row.md

@@ -0,0 +1,50 @@
+<!-- source-hash: 54d3ba316f38a78a9a5a24c3b644ec8d -->
+A responsive card component that displays a lead section alongside two stat cells in a structured row layout, adapting from a stacked column on mobile to a horizontal row on desktop.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `InfoCardRow` | Component | Main card row with a lead section and two stat cells |
+| `StatCell` | Internal Component | Individual stat cell rendering title, caption, and optional icon |
+| `InfoCardRowSection` | Interface | Shape for each section: `title`, `caption`, and optional `icon` |
+| `InfoCardRowProps` | Interface | Props for `InfoCardRow`: `lead`, `stats` (tuple of 2), `className` |
+
+## Usage Example
+
+```typescript
+import { InfoCardRow } from './info-card-row'
+import { ServerIcon, CpuIcon, MemoryIcon } from './icons'
+
+export function DeviceStats() {
+  return (
+    <InfoCardRow
+      lead={{
+        title: 'DESKTOP-ABC123',
+        caption: 'Windows 11 Pro',
+        icon: <ServerIcon />,
+      }}
+      stats={[
+        {
+          title: 'CPU Usage',
+          caption: '42%',
+          icon: <CpuIcon />,
+        },
+        {
+          title: 'Memory',
+          caption: '8.2 GB',
+          icon: <MemoryIcon />,
+        },
+      ]}
+      className="my-4"
+    />
+  )
+}
+```
+
+## Layout Behavior
+
+- **Mobile:** Lead section stacks above the two stat cells (column direction); icons render inline next to captions
+- **Desktop (`md:`):** All three sections sit side-by-side (row direction); icons float to the right of text
+
+**Source:** [`packages/ui/info-card-row.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/packages/ui/info-card-row.tsx)

package/src/components/ui/.info-card.md

@@ -1,41 +1,48 @@
-<!-- source-hash: 871aa5b6b708ec48977c99b3cc86ea5f -->
-A reusable card component for displaying structured key-value information with optional title, subtitle, progress bar, and clipboard copy support.
+<!-- source-hash: 5f25c6a1147c0ccc8f2e18178114f0c9 -->
+A composable card component for displaying structured key-value metadata, optional progress bars, and a footer section — used for surfacing device, asset, or service detail summaries in the OpenFrame UI.
 
 ## Key Components
 
-- **`InfoCard`** — Main exported component that renders a styled card with title, subtitle, info items, and an optional progress bar
-- **`InfoCardValueRow`** — Internal component rendering a single label/value row with a divider and optional copy-to-clipboard button
-- **`InfoCardData`** — Interface defining the card's data shape including items, optional progress config, and display metadata
-- **`InfoCardProps`** — Component props interface accepting `data` and an optional `className`
+| Export | Type | Description |
+|---|---|---|
+| `InfoCard` | Component | Root card with header, items, progress, and footer |
+| `InfoCardData` | Interface | Data shape for the full card |
+| `InfoCardFooterData` | Interface | Footer section with icon, text, logo, and link |
+| `InfoCardValueRow` | Internal Component | Single label–value row with optional copy-to-clipboard |
+| `InfoCardFooter` | Internal Component | Sticky footer with divider, icon, logo, and external link |
+
+**Sub-features:**
+- `copyable` items show a `Copy01Icon` that toggles to `CheckIcon` on success via `useCopyToClipboard`
+- `value` accepts `string | string[]` — arrays render as stacked rows sharing the same label
+- `progress` delegates to `ProgressBar` with warning/critical thresholds and inverted mode
+- Footer `link` auto-strips the protocol for display if no custom label is provided
 
 ## Usage Example
 
 ```typescript
-import { InfoCard } from './info-card'
+import { InfoCard } from '@openframe/ui'
 
-// Basic usage with copyable values and progress bar
 <InfoCard
   data={{
-    title: "Server Details",
-    subtitle: "Production Node",
-    icon: <ServerIcon />,
+    title: 'workstation-42',
+    subtitle: 'macOS Sonoma 14.5',
     items: [
-      { label: "IP Address", value: "192.168.1.100", copyable: true },
-      { label: "Tags", value: ["web", "prod"], copyable: false },
+      { label: 'IP', value: '192.168.1.10', copyable: true },
+      { label: 'Tags', value: ['managed', 'prod'] },
     ],
     progress: {
-      value: 85,
+      value: 78,
       warningThreshold: 70,
       criticalThreshold: 90,
-      inverted: false,
+    },
+    footer: {
+      text: 'CrowdStrike Falcon',
+      link: { href: 'https://falcon.crowdstrike.com' },
     },
   }}
-  className="max-w-sm"
 />
 ```
 
-## Notes
+## Source
 
-- Multi-value items (arrays) render each value as a separate row, with the label shown only on the first row
-- The progress bar supports `inverted` mode where high values are treated as healthy (green) and low values as critical (red)
-- Copy state resets automatically via the `useCopyToClipboard` hook, toggling between a copy and check icon
+[`info-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/info-card.tsx)

package/src/components/ui/.info-row.md

@@ -1,40 +1,46 @@
-<!-- source-hash: 841435ad2eb230c8516130a8d58de981 -->
-A reusable UI component that renders a single labeled row with a value, connected by a horizontal dotted separator line — commonly used for displaying key-value metadata in detail panels or cards.
+<!-- source-hash: baa2e6475e99010ef2b5ec8a6a1c5209 -->
+A client-side React component that renders a labeled row with a dotted/line separator between a label and its value, optionally accompanied by an icon.
 
 ## Key Components
 
 ### `InfoRow`
-A client-side React component that accepts the following props:
+
+A presentational component that displays a key-value pair in a horizontal layout with a flexible spacer line between them.
+
+**Props (`InfoRowProps`):**
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
-| `label` | `string` | ✅ | Left-aligned label text |
-| `value` | `string` | ✅ | Right-aligned value text |
+| `label` | `string` | ✅ | Left-side label text |
+| `value` | `string` | ✅ | Right-side value text |
 | `icon` | `React.ReactNode` | ❌ | Optional icon rendered inline after the value |
 
 ## Usage Example
 
 ```typescript
 import { InfoRow } from "@/components/info-row"
-import { Globe } from "lucide-react"
-
-export function DeviceDetails() {
-  return (
-    <div className="flex flex-col gap-2">
-      <InfoRow label="Hostname" value="workstation-01" />
-      <InfoRow label="IP Address" value="192.168.1.100" />
-      <InfoRow
-        label="Status"
-        value="Online"
-        icon={<Globe className="w-4 h-4 text-green-400" />}
-      />
-    </div>
-  )
-}
+import { CheckCircleIcon } from "lucide-react"
+
+// Basic usage
+<InfoRow label="Status" value="Active" />
+
+// With an icon
+<InfoRow
+  label="Connection"
+  value="Online"
+  icon={<CheckCircleIcon className="w-4 h-4 text-green-500" />}
+/>
+
+// Stacked in a detail panel
+<div className="flex flex-col gap-2">
+  <InfoRow label="Hostname" value="workstation-01.local" />
+  <InfoRow label="OS" value="Windows 11 Pro" />
+  <InfoRow label="Last Seen" value="2 minutes ago" />
+</div>
 ```
 
-## Layout Behavior
+## Notes
 
-- **Label** — left side, truncates with ellipsis on overflow
-- **Separator** — flexible `1px` horizontal line that fills available space between label and value
-- **Value + Icon** — right side, truncates with ellipsis, icon rendered inline after text
+- Marked as `"use client"` — must run in a browser context.
+- Both label and value truncate with ellipsis (`text-ellipsis`) on overflow, making it safe for long strings in constrained layouts.
+- The separator line (`flex-1 bg-ods-border h-px`) expands to fill available space, creating a consistent aligned layout regardless of label/value length.

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

@@ -0,0 +1,63 @@
+<!-- source-hash: 9804263cca4b069c3d9eafabbce30ff3 -->
+A labeled info card component that renders a vertical stack of `label ── value` rows inside a bordered card, supporting plain text, assignee pickers, status dropdowns, and arbitrary custom content as row values.
+
+## Key Components
+
+### Exported Types
+
+| Type | Description |
+|---|---|
+| `InfoSectionTextValue` | Plain text value with optional avatar, icon, click handler, or link |
+| `InfoSectionAssigneeValue` | Inline assignee picker (wraps `AssigneeDropdownProps`) |
+| `InfoSectionStatusValue` | Inline status dropdown (wraps `TicketStatusTagProps`) |
+| `InfoSectionCustomValue` | Arbitrary `React.ReactNode` content |
+| `InfoSectionValue` | Union of all four value types |
+| `InfoSectionRow` | Single row with `id`, `label`, and `value` |
+| `InfoSectionProps` | Component props: optional `title`, `rows`, `className` |
+
+### Internal Components
+
+- **`TextValue`** — Renders text values with optional leading icon, trailing avatar, link (`href`), or button (`onClick`)
+- **`RowValue`** — Switches on `value.type` to delegate to `AssigneeDropdown`, `TicketStatusTag`, `TextValue`, or custom content
+
+### Main Export
+
+- **`InfoSection`** — The card container; renders an optional caption and maps `rows` into label/divider/value triplets
+
+## Usage Example
+
+```typescript
+import { InfoSection } from './info-section'
+import { UserIcon } from 'lucide-react'
+
+<InfoSection
+  title="Ticket Details"
+  rows={[
+    {
+      id: 'status',
+      label: 'Status',
+      value: { type: 'status', status: 'open', options: [...], onSelect: handleSelect },
+    },
+    {
+      id: 'assignee',
+      label: 'Assignee',
+      value: { type: 'assignee', options: [...], onSelect: handleAssign },
+    },
+    {
+      id: 'org',
+      label: 'Organization',
+      value: {
+        text: 'Acme Corp',
+        imageSrc: '/acme.png',
+        icon: <UserIcon />,
+        href: '/orgs/acme',
+      },
+    },
+    {
+      id: 'notes',
+      label: 'Notes',
+      value: { type: 'custom', content: <NotesBadge count={3} /> },
+    },
+  ]}
+/>
+```

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

@@ -1,53 +1,54 @@
-<!-- source-hash: deeae07a7913733b844e875487c55c37 -->
-A client-side input component built with `React.forwardRef`, supporting labels, validation states, adornments, loading indicators, and a special range slider variant.
+<!-- source-hash: ca32f59bb9a8668d4454172d11f1c7cd -->
+A client-side React input component with support for labels, validation states, adornments, loading indicators, and range slider rendering.
 
 ## Key Components
 
-- **`Input`** — Main exported component extending native `HTMLInputElement` attributes
-- **`InputProps`** — Interface adding `invalid`, `startAdornment`, `endAdornment`, `label`, `error`, `errorVariant`, and `loading` props
-- **`invalidBorderClasses`** — Tailwind class map for `"error"` (red) and `"warning"` (yellow) border states
-- **`FieldWrapper`** — Wraps the input with optional label and error message rendering
-
-## Behavior Notes
-
-- **Range type** renders a styled slider without borders or adornments; still supports `label` via `FieldWrapper`
-- **`loading`** replaces `endAdornment` with a spinning `Loader2` icon
-- **`isInvalid`** is derived from either the `invalid` prop or a truthy `error` string
-- Autofill background override applied via `-webkit-box-shadow` hack for consistent theming
+- **`Input`** — A `forwardRef` component extending `React.InputHTMLAttributes<HTMLInputElement>` with additional props for UI composition and validation feedback.
+- **`InputProps`** — Interface extending native input attributes with fields: `invalid`, `startAdornment`, `endAdornment`, `label`, `error`, `errorVariant`, and `loading`.
+- **`invalidBorderClasses`** — Internal map of Tailwind border classes applied per invalid variant (`"error"` | `"warning"`).
+- **`FieldWrapper`** — Wraps the input with a label and status message when `label` or `error` props are provided.
 
 ## Usage Example
 
 ```typescript
-// Basic input with label and error
+import { Input } from "@/components/ui/input";
+import { Search } from "lucide-react";
+
+// Basic with label and validation
 <Input
   label="Email"
-  type="email"
   placeholder="you@example.com"
   error="Invalid email address"
   errorVariant="error"
 />
 
-// Input with adornments and loading state
+// With adornments and loading state
 <Input
   label="Search"
-  startAdornment={<SearchIcon />}
-  loading={isFetching}
-  placeholder="Search tickets..."
+  startAdornment={<Search />}
+  loading={isSearching}
+  placeholder="Search..."
 />
 
-// Range slider
+// Warning variant (invalid border without error severity)
+<Input
+  label="Username"
+  error="Username is already taken"
+  errorVariant="warning"
+/>
+
+// Range slider (stripped-down rendering, no border/adornments)
 <Input
   type="range"
   label="Volume"
   min={0}
   max={100}
-  defaultValue={50}
 />
+```
 
-// Warning variant
-<Input
-  label="Username"
-  error="Username already taken"
-  errorVariant="warning"
-/>
-```
+## Notes
+
+- `"error"` and `"warning"` variants both mark the field visually invalid (colored border); `"success"` and `"muted"` are informational only.
+- `type="range"` receives a separate rendering path with a custom slider style and no wrapper chrome.
+- The `loading` prop takes precedence over `endAdornment` — both will not render simultaneously.
+- Autofill background override is handled via webkit-specific CSS to preserve theme colors.

package/src/components/ui/.label.md

@@ -1,37 +1,45 @@
-<!-- source-hash: f49e05bbdd3e039f273682acb1b385bc -->
-A client-side React component that provides a flexible label element built on Radix UI primitives with customizable typography and spacing variants.
+<!-- source-hash: 75ae35fff31d350f71633d4b8075a1d7 -->
+Accessible label component built on Radix UI's `LabelPrimitive`, styled with `class-variance-authority` (CVA) to support multiple size and spacing variants.
 
 ## Key Components
 
-- **`labelVariants`** - CVA configuration defining size and spacing variants for consistent label styling
-- **`Label`** - Main component extending Radix UI Label with variant props and forward ref support
+### `labelVariants`
+CVA configuration defining two variant axes:
+
+| Axis | Options | Default |
+|------|---------|---------|
+| `variant` | `default`, `small`, `medium`, `large` | `default` |
+| `spacing` | `default`, `tight`, `normal`, `loose` | `default` |
+
+### `Label`
+A `forwardRef` wrapper around `LabelPrimitive.Root` that merges CVA-generated classes with any additional `className` passed by the consumer.
 
 ## Usage Example
 
 ```typescript
 import { Label } from "./label"
 
-function FormExample() {
-  return (
-    <div>
-      {/* Default label */}
-      <Label htmlFor="email">Email Address</Label>
-      <input id="email" type="email" />
-      
-      {/* Small label with tight spacing */}
-      <Label htmlFor="username" variant="small" spacing="tight">
-        Username
-      </Label>
-      <input id="username" type="text" />
-      
-      {/* Large label with loose spacing */}
-      <Label htmlFor="description" variant="large" spacing="loose">
-        Description
-      </Label>
-      <textarea id="description" />
-    </div>
-  )
-}
+// Default label
+<Label htmlFor="email">Email address</Label>
+
+// Small label with tight spacing
+<Label htmlFor="username" variant="small" spacing="tight">
+  Username
+</Label>
+
+// Large label with loose spacing
+<Label htmlFor="bio" variant="large" spacing="loose">
+  Biography
+</Label>
+
+// With custom class override
+<Label htmlFor="name" className="text-red-500">
+  Required Field
+</Label>
 ```
 
-The component supports four size variants (`default`, `small`, `medium`, `large`) and four spacing options (`default`, `tight`, `normal`, `loose`), providing flexible typography scaling and margin control for form layouts.
+## Notes
+
+- Rendered as a client component (`"use client"`).
+- Inherits all native `<label>` accessibility behaviours from Radix UI, including automatic association with form controls via `htmlFor`.
+- Extend or override styles via the `className` prop; CVA classes are merged using the `cn` utility.