@fragments-sdk/ui 0.7.5 → 0.8.0

package/README.md

@@ -44,30 +44,63 @@ function App() {
 
 | Component | Category | Description |
 |-----------|----------|-------------|
-| Alert | Feedback | Contextual feedback messages with severity levels |
-| Avatar | Display | User or entity profile images with fallbacks |
-| Badge | Display | Status indicators and labels |
-| Button | Actions | Primary interaction element with variants |
-| Card | Layout | Content container with optional sections |
-| Checkbox | Forms | Binary selection control |
-| CircularProgress | Feedback | Circular loading/progress indicator |
-| Dialog | Overlay | Modal dialogs with compound API |
-| EmptyState | Feedback | Placeholder for empty content areas |
-| Grid | Layout | Responsive grid layout with breakpoint support |
-| Input | Forms | Text input with label, error, and helper text |
-| Menu | Overlay | Dropdown action menus |
-| Popover | Overlay | Floating content panels |
-| Progress | Feedback | Linear progress bar |
-| RadioGroup | Forms | Single-select from a group of options |
-| Select | Forms | Dropdown selection control |
-| Separator | Layout | Visual divider between content |
-| Skeleton | Feedback | Loading placeholder that preserves layout |
-| Table | Data | Data table with sorting and selection |
-| Tabs | Navigation | Tabbed content panels |
-| Textarea | Forms | Multi-line text input |
-| Toast | Feedback | Transient notifications |
-| Toggle | Forms | On/off switch control |
-| Tooltip | Overlay | Contextual information on hover |
+| Accordion | Layout | Vertically stacked, collapsible content sections. Use for organizing related content that can be progressively disclosed. |
+| Alert | Feedback | Contextual feedback messages for user actions or system status. Supports multiple severity levels with optional actions and dismissibility. |
+| AppShell | Layout | Full layout wrapper integrating sidebar, header, main content, and optional aside panel. Supports two layout modes: stacked (header on top) and sidebar-inset (sidebar full height). |
+| Avatar | Display | Visual representation of a user or entity |
+| Badge | Display | Compact label for status, counts, or categorization. Draws attention to metadata without dominating the layout. |
+| Box | Layout | Primitive layout component for applying spacing, backgrounds, and borders. A flexible container for building custom layouts. |
+| Breadcrumbs | Navigation | Breadcrumb navigation showing the current page location within a hierarchy. Helps users navigate back through parent pages. |
+| Button | Forms | Interactive element for user actions and form submissions |
+| ButtonGroup | Forms | Groups related buttons together with consistent spacing and alignment. Useful for action bars, toolbars, and related button sets. |
+| Card | Layout | Container for grouping related content |
+| Chart | Display | Composable chart wrapper for recharts with theme-aware tooltips, legends, and color integration. |
+| Checkbox | Forms | Binary toggle for form fields. Use for options that require explicit submission, unlike Toggle which takes effect immediately. |
+| Chip | Forms | Interactive pill-shaped element for filtering, selecting, and tagging. Supports single and multi-select via Chip.Group. |
+| CodeBlock | Display | Syntax-highlighted code display with copy functionality, theming, diff view, and collapsible sections |
+| Collapsible | Layout | An interactive component that expands/collapses to show or hide content |
+| ColorPicker | Forms | Color selection control with hex input and visual picker. Displays a swatch that opens a full color picker on click. |
+| Combobox | Forms | Searchable select input that filters a dropdown list of options as you type. Supports single and multiple selection with chips. |
+| ConversationList | Ai | Scrollable message container with auto-scroll and history loading |
+| Dialog | Feedback | Modal overlay for focused user interactions. Use for confirmations, forms, or content requiring full attention. |
+| EmptyState | Feedback | Placeholder for empty content areas. Provides context, guidance, and actions when no data is available. |
+| Field | Forms | Compositional form field wrapper providing validation, labels, descriptions, and error messages. Use for advanced form needs beyond baked-in Input/Textarea props. |
+| Fieldset | Forms | Groups related form fields with an accessible legend. Use to organize forms into logical sections. |
+| Form | Forms | Form wrapper that handles server-side error distribution to Field components. Pairs with Field for complete form validation. |
+| Grid | Layout | Responsive grid layout for arranging items in columns with consistent spacing |
+| Header | Navigation | Composable header with slots for brand, navigation, search, and actions. Supports dropdown nav groups via Header.NavMenu. Designed for use within AppShell with responsive mobile support. |
+| Icon | Display | Wrapper for Phosphor icons with consistent sizing and semantic colors. Provides standardized icon rendering across the design system. |
+| Image | Display | Responsive image component with aspect ratio control, loading states, and error fallbacks. Handles image display with consistent styling. |
+| Input | Forms | Text input field for single-line user data entry |
+| Link | Navigation | Styled anchor element for navigation. Supports internal and external links with consistent visual treatment. |
+| List | Display | Compound component for rendering ordered or unordered lists with consistent styling. Supports bullet, numbered, and icon-prefixed items. |
+| Listbox | Forms | Controlled listbox for search results, autocomplete dropdowns, and command menus. Provides Menu-like styling without requiring a trigger. |
+| Loading | Feedback | Versatile loading indicator with multiple variants for showing progress or waiting states |
+| Markdown | Display | Renders markdown strings as styled prose using react-markdown and remark-gfm. Supports headings, lists, tables, code blocks, blockquotes, and more. |
+| Menu | Feedback | Dropdown menu for actions and commands. Use for contextual actions, overflow menus, or grouped commands. |
+| Message | Ai | Individual chat message display with role-based styling |
+| Popover | Feedback | Rich content overlay anchored to a trigger element. Use for forms, detailed information, or interactive content that should stay in context. |
+| Progress | Feedback | Visual indicator of task completion or loading state. Available in linear and circular variants. |
+| Prompt | Ai | Multi-line input with toolbar for AI/chat interfaces |
+| RadioGroup | Forms | Single selection from a list of mutually exclusive options |
+| ScrollArea | Layout | A styled scrollable container with thin scrollbars and optional fade indicators. |
+| Select | Forms | Dropdown for choosing from a list of options. Use when there are more than 4-5 choices that would clutter the UI. |
+| Separator | Layout | Visual divider between content sections. Use to create clear visual boundaries and improve content organization. |
+| Sidebar | Navigation | Responsive navigation sidebar with collapsible desktop mode and mobile drawer behavior. |
+| Skeleton | Feedback | Placeholder loading state for content |
+| Slider | Forms | Range input control for selecting a numeric value within a defined range. Supports labels, value display, and custom step intervals. |
+| Stack | Layout | Flexible layout component for arranging children in rows or columns with consistent spacing. Supports responsive direction and gap. |
+| Table | Display | Data table with sorting and row selection. Use for displaying structured data that needs to be scanned, compared, or acted upon. |
+| Tabs | Navigation | Organize content into switchable panels. Use for related content that benefits from a compact, navigable layout. |
+| Text | Display | Typography component for rendering text with consistent styling. Supports various sizes, weights, colors, and semantic elements. |
+| Textarea | Forms | Multi-line text input for longer form content |
+| Theme | Navigation | Theme management system with provider, toggle, and hook pattern. Supports light, dark, and system modes with localStorage persistence. |
+| ThinkingIndicator | Ai | Animated indicator showing AI is processing |
+| Toast | Feedback | Brief, non-blocking notification messages |
+| Toggle | Forms | Binary on/off switch for settings and preferences. Provides immediate visual feedback and is ideal for options that take effect instantly. |
+| ToggleGroup | Forms | A group of toggle buttons where only one can be selected at a time. Useful for switching between views, modes, or options. |
+| Tooltip | Feedback | Contextual help text that appears on hover or focus. Perfect for explaining icons, truncated text, or providing additional context. |
+| VisuallyHidden | Navigation | Hides content visually while keeping it accessible to screen readers. Essential for accessible icon-only buttons and supplementary text. |
 
 ## Design Tokens
 
@@ -178,7 +211,7 @@ You can still override individual tokens directly:
 
 **Existing code continues to work.** The seed system is fully backward compatible:
 
-- Existing `@use '@fragments/ui/tokens'` imports work unchanged
+- Existing `@use '@fragments-sdk/ui/tokens'` imports work unchanged
 - Individual variable overrides (`$fui-color-accent: #blue`) still work
 - CSS variable usage (`var(--fui-color-accent)`) works
 - Component APIs remain the same