@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214

package/src/components/ui/.release-changelog-section.md

@@ -1,51 +1,51 @@
-<!-- source-hash: 02bdd5a69b9b56515feb0ba7774fd9b5 -->
-React component that renders a changelog section for product releases, displaying a list of changelog entries with optional section titles and breaking change indicators.
+<!-- source-hash: 7fa49d7ef85ecd5ac09ebac9a632fbac -->
+Renders a collapsible/expandable changelog section for product releases, supporting three display modes: default (always visible), collapsible (toggle open/closed), and preview-first (show first entry with fade-masked overflow).
 
 ## Key Components
 
-- **ReleaseChangelogSection** - Main component that renders a changelog section with title, entry count badge, and formatted entry list
-- **ReleaseChangelogSectionProps** - Interface defining component props including title, entries array, breaking change flag, and markdown renderer
-- **ChangelogEntry** - Type import for individual changelog entries from product release types
+### `ReleaseChangelogSection` (exported)
+Main component accepting these key props:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `string` | Section heading text |
+| `entries` | `ChangelogEntry[]` | List of changelog items to render |
+| `isBreaking` | `boolean` | Applies red styling for breaking changes |
+| `collapsible` | `boolean` | Enables toggle open/close mode (wins over `previewFirst`) |
+| `defaultCollapsed` | `boolean` | Initial collapsed state when `collapsible=true` (default: `true`) |
+| `previewFirst` | `boolean` | Shows first entry fully, fades remaining with "Show N more" toggle |
+| `icon` | `React.ReactNode` | Optional Lucide icon rendered before title |
+| `SimpleMarkdownRenderer` | `ComponentType` | Injected markdown renderer for entry descriptions |
+
+### `ChangelogEntryList` (internal)
+Shared list renderer used by both default and preview-first branches. Renders each `ChangelogEntry` as a left-bordered list item with bold title and markdown-rendered description, with responsive typography tokens pinned via Tailwind `[&_p]:!` overrides.
 
 ## Usage Example
 
 ```typescript
 import { ReleaseChangelogSection } from './release-changelog-section';
-import { SimpleMarkdownRenderer } from './markdown-renderer';
-
-const changelogEntries = [
-  {
-    title: "New authentication system",
-    description: "Implemented OAuth2 support with **enhanced security** features"
-  },
-  {
-    title: "Performance improvements",
-    description: "Reduced API response time by 40%"
-  }
-];
-
-// Regular changelog section
+import { Sparkles } from 'lucide-react';
+
 <ReleaseChangelogSection
   title="New Features"
-  entries={changelogEntries}
-  SimpleMarkdownRenderer={SimpleMarkdownRenderer}
+  entries={[
+    { title: "AI Ticketing", description: "Automated ticket routing via Mingo AI." },
+    { title: "Client Portal", description: "Fae self-service dashboard launched." },
+  ]}
+  icon={<Sparkles className="w-5 h-5" />}
+  previewFirst
+  SimpleMarkdownRenderer={MyMarkdownRenderer}
 />
 
-// Breaking changes section with red styling
+// Collapsible breaking-changes section
 <ReleaseChangelogSection
   title="Breaking Changes"
-  entries={breakingChanges}
-  isBreaking={true}
-  SimpleMarkdownRenderer={SimpleMarkdownRenderer}
-/>
-
-// Hidden title variant
-<ReleaseChangelogSection
-  title="Updates"
-  entries={updates}
-  hideTitle={true}
-  SimpleMarkdownRenderer={SimpleMarkdownRenderer}
+  entries={breakingEntries}
+  isBreaking
+  collapsible
+  defaultCollapsed={false}
+  SimpleMarkdownRenderer={MyMarkdownRenderer}
 />
 ```
 
-The component features responsive styling with custom typography (DM Sans font), border accents for entry items, and conditional red coloring for breaking changes. Each entry displays a title and optional markdown-rendered description.
+> **Note:** When both `collapsible` and `previewFirst` are passed, `collapsible` takes precedence. The `previewFirst` fade toggle resets automatically when `entries.length` changes.

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

@@ -0,0 +1,48 @@
+<!-- source-hash: e33f919319929a558fb7204fa5689d69 -->
+A client-side search input component with debounced querying, filter chip management, keyboard navigation, and a popover-based results dropdown.
+
+## Key Components
+
+### Types
+- **`SearchResult`** — Shape of a single search result (`id`, `title`, `description`, `icon`, `type`, `metadata`)
+- **`FilterChipData`** — Inline filter chip definition with optional variant (`selected`, `category`, `subcategory`, `tag`)
+- **`SearchInputProps`** — Full prop surface for the component (controlled/uncontrolled, debounce, grouping, chip limits, adornments)
+
+### Exported Component
+- **`SearchInput`** — Main component combining:
+  - Debounced input via `useDebounce`
+  - Auto-limiting visible chips via `useAutoLimitTags`
+  - Radix UI `Popover` for the results dropdown
+  - Radix UI `ScrollArea` for scrollable results
+  - Keyboard navigation (`ArrowUp`, `ArrowDown`, `Enter`, `Escape`, `Backspace`)
+  - Grouped results support via `groupBy` prop
+  - Modifier-key-aware result selection (supports cmd/ctrl/middle-click pass-through)
+  - Hidden chips overflow popup via `HiddenTagsPopup`
+
+## Usage Example
+
+```typescript
+import { SearchInput, SearchResult } from "./search-input"
+
+const results: SearchResult[] = [
+  { id: "1", title: "Ticket #1042", description: "Printer offline", type: "ticket" },
+  { id: "2", title: "Client: Acme Corp", type: "client" },
+]
+
+<SearchInput
+  placeholder="Search tickets, clients..."
+  debounceMs={300}
+  results={results}
+  minQueryLength={2}
+  onResultSelect={(result, modifiers) => {
+    if (modifiers?.metaKey) {
+      openInNewTab(result.path)
+    } else {
+      navigate(result.path)
+    }
+  }}
+  filterChips={[{ id: "open", label: "Status: Open", variant: "selected" }]}
+  onFilterRemove={(id) => removeFilter(id)}
+  limitTags="auto"
+/>
+```

package/src/components/ui/.select.md

@@ -1,43 +1,63 @@
-<!-- source-hash: 4e374e3b2f93e6064e92168d97eda2ed -->
-A comprehensive Select component built on Radix UI primitives with custom styling for the Flamingo platform. It provides an accessible dropdown selection interface with proper focus management, keyboard navigation, and visual feedback.
+<!-- source-hash: 223f5a1c3c624e5773b99c85b384c3b9 -->
+Accessible, styled select dropdown component built on Radix UI's Select primitive, integrated with the OpenFrame Design System (ODS) token system and `FieldWrapper` for label/error support.
 
 ## Key Components
 
-- **Select** - Root component that manages the select state
-- **SelectTrigger** - The button that opens the dropdown, styled to match Input components
-- **SelectContent** - The dropdown container with portal rendering and animations
-- **SelectItem** - Individual option items with hover states and check indicators
-- **SelectValue** - Displays the selected value in the trigger
-- **SelectLabel** - Section headers within the dropdown
-- **SelectGroup** - Groups related items together
-- **SelectSeparator** - Visual divider between sections
-- **SelectScrollUpButton/SelectScrollDownButton** - Navigation for long lists
+| Export | Description |
+|--------|-------------|
+| `Select` | Root select primitive (Radix `SelectPrimitive.Root`) |
+| `SelectTrigger` | Styled trigger button with `invalid`, `label`, and `error` props; wraps in `FieldWrapper` |
+| `SelectContent` | Dropdown panel rendered in a portal with open/close animations |
+| `SelectItem` | Individual option row with checkmark indicator and hover/disabled states |
+| `SelectGroup` | Groups related options (Radix `SelectPrimitive.Group`) |
+| `SelectLabel` | Label for an option group |
+| `SelectValue` | Displays the currently selected value placeholder |
+| `SelectSeparator` | Horizontal divider between options |
+| `SelectScrollUpButton` / `SelectScrollDownButton` | Scroll controls for long option lists |
 
 ## Usage Example
 
 ```typescript
-import { 
-  Select, 
-  SelectContent, 
-  SelectItem, 
-  SelectTrigger, 
-  SelectValue 
-} from "./select"
-
-function StatusSelector() {
-  return (
-    <Select defaultValue="active">
-      <SelectTrigger className="w-48">
-        <SelectValue placeholder="Select status..." />
-      </SelectTrigger>
-      <SelectContent>
-        <SelectItem value="active">Active</SelectItem>
-        <SelectItem value="pending">Pending</SelectItem>
-        <SelectItem value="inactive">Inactive</SelectItem>
-      </SelectContent>
-    </Select>
-  )
-}
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
+
+// Basic usage with label and error validation
+<Select>
+  <SelectTrigger label="Region" error={errors.region?.message}>
+    <SelectValue placeholder="Select a region..." />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>North America</SelectLabel>
+      <SelectItem value="us-east">US East</SelectItem>
+      <SelectItem value="us-west">US West</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+
+// Invalid / error state
+<Select>
+  <SelectTrigger label="Priority" invalid error="Priority is required">
+    <SelectValue placeholder="Select priority..." />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="low">Low</SelectItem>
+    <SelectItem value="medium">Medium</SelectItem>
+    <SelectItem value="high">High</SelectItem>
+  </SelectContent>
+</Select>
 ```
 
-The component features dark theme styling with `#212121` background, `#3a3a3a` borders, and accent color highlights for selected items. It includes smooth animations, proper accessibility attributes, and responsive sizing that matches the platform's Input component design.
+## Notes
+
+- **Validation states**: Pass `error` (string) or `invalid` (boolean) to `SelectTrigger` to apply `ods-error` border and icon tinting.
+- **ODS tokens**: All colors use `ods-*` CSS custom properties (`ods-card`, `ods-accent`, `ods-error`, etc.) for consistent theming.
+- **Content width**: Dropdown matches trigger width via `--radix-select-trigger-width` CSS variable.
+- **Accessibility**: Built on Radix UI — keyboard navigation, ARIA roles, and focus management are handled automatically.

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

@@ -1,48 +1,50 @@
-<!-- source-hash: 6ca572f21be54b6053e67fb5bcd5ecad -->
-A React component that renders service information cards with configurable rows, actions, and secret value masking functionality.
+<!-- source-hash: fd0b3b382332c759225974101fb17198 -->
+Displays structured service information in a card layout with labeled rows that support copy, reveal (masked secrets), and external link actions.
 
 ## Key Components
 
-- **`ServiceCard`** - Main card component displaying service details with header, icon, and rows
-- **`ServiceCardRowItem`** - Individual row component with label, value, and action buttons
-- **`MaskedValue`** - Utility component for hiding/showing secret values
-- **`ServiceCardProps`** - Main component props interface
-- **`ServiceCardRow`** - Row configuration interface with actions and display options
-- **`ServiceCardTag`** - Optional tag display interface
-- **`ServiceCardRowAction`** - Action button configuration interface
+- **`ServiceCard`** — Main card component rendering a header (icon, title, subtitle, tag) and a list of data rows
+- **`ServiceCardRowItem`** — Internal row component handling per-row interactivity (reveal/copy/open)
+- **`MaskedValue`** — Renders a value as bullet dots (`•`) until revealed
+- **`ServiceCardProps`** — Props interface for the card
+- **`ServiceCardRow`** — Defines a single row with optional label, secret masking, monospace formatting, href, and action overrides
+- **`ServiceCardTag`** — Badge displayed in the card header
+- **`ServiceCardRowAction`** — Flags controlling which actions (`copy`, `open`, `reveal`) appear per row
 
 ## Usage Example
 
 ```typescript
-import { ServiceCard } from './service-card'
+import { ServiceCard } from '@your-org/ui'
 
-function MyComponent() {
-  return (
-    <ServiceCard
-      title="API Service"
-      subtitle="Production Environment"
-      tag={{ label: "Active" }}
-      rows={[
-        {
-          label: "Endpoint",
-          value: "https://api.example.com",
-          href: "https://api.example.com",
-          actions: { copy: true, open: true }
-        },
-        {
-          label: "API Key",
-          value: "sk_live_abc123xyz789",
-          isSecret: true,
-          monospace: true,
-          actions: { copy: true, reveal: true }
-        },
-        {
-          label: "Status",
-          value: "Running",
-          actions: { copy: false, open: false }
-        }
-      ]}
-    />
-  )
-}
-```
+<ServiceCard
+  title="PostgreSQL"
+  subtitle="Primary database"
+  tag={{ label: 'Production' }}
+  rows={[
+    {
+      label: 'Host',
+      value: 'db.example.com',
+      actions: { copy: true },
+    },
+    {
+      label: 'Password',
+      value: 's3cr3tpassword',
+      isSecret: true,
+      copyValue: 's3cr3tpassword',
+    },
+    {
+      label: 'Console',
+      value: 'Open dashboard',
+      href: 'https://console.example.com',
+      actions: { copy: false, open: true },
+    },
+  ]}
+/>
+```
+
+## Behavior Notes
+
+- **Secrets** default to masked display; `reveal` action toggles visibility
+- **Copy** action defaults to `true`; uses `copyValue` if provided, otherwise falls back to `value`
+- **Open** action is automatically enabled when a `href` is present
+- Falls back to the **OpenFrameLogo** if no `icon` is supplied

package/src/components/ui/.sheet.md

@@ -1,30 +1,36 @@
-<!-- source-hash: e8fb9325bde87bb1cb5577b034ebb17b -->
-A comprehensive sheet/drawer component built on Radix UI Dialog primitives, providing slide-out panels that can appear from any side of the screen with smooth animations and accessibility features.
+<!-- source-hash: b12df94d463c0d388bcb0c53bac39207 -->
+A slide-out panel component built on top of Radix UI's Dialog primitive, supporting four directional variants (top, bottom, left, right) with animated open/close transitions.
 
 ## Key Components
 
-- **Sheet** - Root component that manages sheet state
-- **SheetTrigger** - Button or element that opens the sheet
-- **SheetContent** - Main container with configurable slide direction (`top`, `bottom`, `left`, `right`)
-- **SheetOverlay** - Background overlay with fade animations
-- **SheetClose** - Close button with X icon
-- **SheetHeader/SheetFooter** - Layout containers for sheet sections
-- **SheetTitle/SheetDescription** - Accessible heading and description components
-- **SheetPortal** - Portal for rendering outside component tree
+| Export | Description |
+|--------|-------------|
+| `Sheet` | Root component wrapping Radix Dialog root |
+| `SheetTrigger` | Button/element that opens the sheet |
+| `SheetClose` | Element that closes the sheet |
+| `SheetPortal` | Renders sheet outside DOM hierarchy |
+| `SheetOverlay` | Semi-transparent backdrop (`z-[9997]`) |
+| `SheetContent` | Main panel container with side variants (`top`, `bottom`, `left`, `right`), defaults to `right` |
+| `SheetHeader` | Flex column wrapper for title/description |
+| `SheetFooter` | Flex row wrapper for action buttons |
+| `SheetTitle` | Styled heading (`text-lg font-semibold`) |
+| `SheetDescription` | Styled subtitle (`text-sm text-muted-foreground`) |
 
 ## Usage Example
 
 ```typescript
 import {
   Sheet,
+  SheetTrigger,
   SheetContent,
-  SheetDescription,
   SheetHeader,
   SheetTitle,
-  SheetTrigger,
+  SheetDescription,
+  SheetFooter,
+  SheetClose,
 } from "./sheet"
 
-function MyComponent() {
+export function SettingsPanel() {
   return (
     <Sheet>
       <SheetTrigger asChild>
@@ -33,15 +39,18 @@ function MyComponent() {
       <SheetContent side="right">
         <SheetHeader>
           <SheetTitle>Settings</SheetTitle>
-          <SheetDescription>
-            Configure your application preferences
-          </SheetDescription>
+          <SheetDescription>Manage your preferences.</SheetDescription>
         </SheetHeader>
-        {/* Sheet content */}
+        {/* content */}
+        <SheetFooter>
+          <SheetClose asChild>
+            <button>Close</button>
+          </SheetClose>
+        </SheetFooter>
       </SheetContent>
     </Sheet>
   )
 }
 ```
 
-The component uses class-variance-authority for styling variants and includes built-in animations, focus management, and keyboard navigation. The sheet automatically includes a close button and can be dismissed by clicking the overlay or pressing escape.
+> The `side` prop on `SheetContent` accepts `"top" | "bottom" | "left" | "right"` and drives both positioning and slide animation direction. The close button (`X` icon) is automatically rendered inside `SheetContent`.

package/src/components/ui/.simple-markdown-renderer.md

@@ -1,42 +1,40 @@
-<!-- source-hash: f96a8385aeb28ffc329d74dca516b959 -->
-A client-side React component that renders markdown content with enhanced styling, syntax highlighting, and responsive design using ReactMarkdown with several plugins.
+<!-- source-hash: cb258dc120396ef8c715487b0cdc1022 -->
+Client-side React component that renders LLM-generated markdown safely, combining `react-markdown` with a custom XSS sanitization pipeline and support for GitHub-flavored markdown, syntax highlighting, and embedded media.
 
 ## Key Components
 
-- **`SimpleMarkdownRenderer`** - Main functional component that processes and renders markdown content
-- **`components`** - Memoized object containing custom renderers for markdown elements (code blocks, headings, links, etc.)
-- **Markdown plugins**: `remarkGfm` (GitHub Flavored Markdown), `remarkBreaks` (line breaks), `rehypeHighlight` (syntax highlighting), `rehypeRaw` (HTML support)
+### Security Pipeline
+- **`rehypeStripUnsafe()`** — Custom rehype plugin that strips dangerous HAST nodes after `rehype-raw` parsing. Removes `<script>`, `<style>`, `<object>`, event handler attributes (`on*`), `javascript:` / `data:` URIs, and `iframe srcdoc` vectors.
+- **`srcsetHasUnsafeCandidate()`** — Inspects every candidate URL in `srcset` attributes (not just the first), preventing multi-candidate injection attacks.
+- **`escapeUnknownHtmlTags()`** — Pre-processes markdown text to escape HTML tags not in the `SAFE_HTML_TAGS` allowlist, preventing LLM-emitted XML-style tags (e.g., `<ticket>`, `<their>`) from reaching React as unrecognized custom elements. Preserves code blocks and inline code spans.
+- **`cardAwareUrlTransform()`** — Extends `react-markdown`'s default URL sanitizer to allow the internal `card://` scheme for chat-card markers while keeping all other unsafe schemes blocked.
+
+### Constants & Regexes
+| Export | Purpose |
+|--------|---------|
+| `SAFE_HTML_TAGS` | Allowlist of permitted HTML5 tags forwarded to React |
+| `STRIP_ELEMENTS` | Tags removed entirely at the HAST level |
+| `EVENT_HANDLER_ATTR_RE` | Matches `on*` attribute names |
+| `JAVASCRIPT_URL_RE` / `DATA_URL_RE` | Detect unsafe URL schemes |
+| `TAG_LIKE_REGEX` | Parses HTML-like tags in markdown source |
+
+### Mermaid Support
+- `mermaidStyles` — Responsive CSS for Mermaid SVG diagrams using DM Sans font.
 
 ## Usage Example
 
 ```typescript
 import { SimpleMarkdownRenderer } from './simple-markdown-renderer';
 
-function DocumentationPage() {
-  const markdownContent = `
-# API Documentation
-
-This is a **bold** statement with \`inline code\`.
-
-\`\`\`typescript
-interface User {
-  id: string;
-  name: string;
-}
-\`\`\`
-
-> This is a blockquote with important information.
-  `;
-
-  return (
-    <div>
-      <SimpleMarkdownRenderer 
-        content={markdownContent}
-        className="documentation-content"
-      />
-    </div>
-  );
-}
+// Basic usage — content is sanitized automatically
+<SimpleMarkdownRenderer
+  content="## Hello\n\nThis is **LLM-generated** markdown with `code`."
+/>
+
+// The sanitizer prevents XSS from LLM output automatically:
+// "<script>alert(1)</script>" → stripped
+// "<their> tag" → escaped to &lt;their&gt;
+// "javascript:alert(1)" href → removed
 ```
 
-The component features responsive typography, custom-styled code blocks with language headers, themed blockquotes, and proper hydration handling to prevent SSR mismatches. All styling uses CSS custom properties for theming consistency.
+> **Note:** This renderer is designed specifically for untrusted LLM output. The sanitization pipeline runs in layers: text pre-processing → `rehype-raw` → `rehypeStripUnsafe` → `rehype-highlight`, ensuring no XSS vectors survive even if one layer is bypassed. Community support is available on the [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA).

package/src/components/ui/.sort-column-item.md

@@ -0,0 +1,42 @@
+<!-- source-hash: 576067b7bb2d4b4d4bb10818d0012e49 -->
+A client-side React component that renders a single sortable column item, cycling through ascending, descending, and cleared sort states on click.
+
+## Key Components
+
+### Interfaces & Types
+- **`SortableColumn`** — Defines a column with `key`, `label`, and optional `sortKey`
+- **`SortDirection`** — Union type `"asc" | "desc"`
+- **`SortConfig`** — Configuration shape for a full sort UI (columns list, active sort state, title)
+- **`SortColumnItemProps`** — Props for the `SortColumnItem` component
+
+### Component: `SortColumnItem`
+Renders a clickable row displaying a column label and a directional sort icon. Click behavior cycles through states:
+1. No sort → `"asc"`
+2. `"asc"` → `"desc"`
+3. `"desc"` → calls `onClear()` (if provided) or resets to `"asc"`
+
+Icons used per state:
+- `Arrow01UpIcon` — ascending (accent color)
+- `Arrow01DownIcon` — descending (accent color)
+- `SwitchVrIcon` — unsorted (secondary color)
+
+## Usage Example
+
+```typescript
+import { SortColumnItem, SortableColumn, SortDirection } from "./sort-column-item"
+
+const column: SortableColumn = { key: "name", label: "Name", sortKey: "name" }
+
+function MyTable() {
+  const [direction, setDirection] = useState<SortDirection | undefined>()
+
+  return (
+    <SortColumnItem
+      column={column}
+      currentDirection={direction}
+      onSort={(dir) => setDirection(dir)}
+      onClear={() => setDirection(undefined)}
+    />
+  )
+}
+```

package/src/components/ui/.square-avatar.md

@@ -1,39 +1,49 @@
-<!-- source-hash: 35355c38ee34a9569d3b2519d2f153ca -->
-A flexible avatar component that displays user images with fallback initials, supporting both square and rounded variants with multiple size options.
+<!-- source-hash: 5ede4b179e76c93d7dbba4fcff5327a9 -->
+A flexible avatar component that displays a user image or falls back to initials, supporting both square and round variants with multiple size options.
 
 ## Key Components
 
-- **`getInitials`** - Utility function that extracts first letter of first and last word from a name
-- **`SquareAvatar`** - Main component that renders either an image or initials fallback
-- **`SquareAvatarProps`** - Interface extending HTML div attributes with avatar-specific props
-- **Size variants** - `sm`, `md`, `lg`, `xl` with corresponding pixel dimensions
-- **Shape variants** - `square` (rounded corners) or `round` (circular)
+### `SquareAvatarProps`
+Extends `React.HTMLAttributes<HTMLDivElement>` with:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | — | Image URL |
+| `alt` | `string` | — | Image alt text (also used for initials fallback) |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Controls dimensions (32/40/48/64px) |
+| `fallback` | `string` | — | Preferred string for generating initials |
+| `variant` | `'square' \| 'round'` | `'square'` | Border radius style |
+
+### `SquareAvatar`
+A memoized, forwarded-ref component that renders an image with automatic graceful degradation to initials on load error or missing `src`.
+
+**Fallback behavior:** Uses `getFirstLastInitials()` on `fallback ?? alt`, rendering `'?'` if neither yields initials. The initials layer uses `text-ods-text-primary` to maintain WCAG AA contrast across accent-fill backgrounds (e.g. Mingo cyan, current-user pink).
 
 ## Usage Example
 
 ```typescript
-import { SquareAvatar } from './components/square-avatar';
-
-// With image source
-<SquareAvatar 
-  src="/user-profile.jpg" 
-  alt="John Doe" 
+// Image avatar
+<SquareAvatar
+  src="https://example.com/avatar.jpg"
+  alt="Jane Doe"
   size="lg"
   variant="round"
 />
 
-// Fallback to initials
-<SquareAvatar 
-  fallback="Jane Smith" 
-  size="md" 
+// Initials-only avatar (no src)
+<SquareAvatar
+  fallback="Jane Doe"
+  size="md"
   variant="square"
 />
 
-// Using alt text for initials
-<SquareAvatar 
-  alt="Alex Johnson" 
-  size="sm"
+// With custom className and forwarded ref
+const ref = React.useRef<HTMLDivElement>(null);
+<SquareAvatar
+  ref={ref}
+  src={userAvatarUrl}
+  alt={userName}
+  size="xl"
+  className="ring-2 ring-ods-flamingo-pink"
 />
-```
-
-The component automatically falls back to displaying user initials in a styled container when no image source is provided, making it perfect for user interfaces where profile pictures may not always be available.
+```