221 lines
7.4 KiB
Elixir
221 lines
7.4 KiB
Elixir
defmodule RiverConnectWeb.Components.UI do
|
|
@moduledoc """
|
|
SaladUI - A comprehensive UI component library for Phoenix LiveView applications.
|
|
|
|
SaladUI provides a collection of accessible, customizable UI components that combine
|
|
server-side rendering with client-side interactivity. Built specifically for Phoenix
|
|
LiveView, it offers seamless integration between Elixir and JavaScript.
|
|
|
|
## Features
|
|
|
|
- **40+ UI Components** - Buttons, forms, overlays, navigation, and data display
|
|
- **Accessibility First** - ARIA compliant with keyboard navigation and screen reader support
|
|
- **LiveView Integration** - Two-way communication between server and client
|
|
- **Customizable** - Tailwind CSS based with variant support
|
|
- **Type Safe** - Full attribute validation and documentation
|
|
|
|
## Quick Start
|
|
|
|
Add SaladUI to your Phoenix application:
|
|
|
|
# In your core components module
|
|
use SaladUI
|
|
|
|
# In templates
|
|
<.button variant="primary" phx-click="save">
|
|
Save Changes
|
|
</.button>
|
|
|
|
## Component Categories
|
|
|
|
### Layout & Structure
|
|
- `card/1` - Content containers with headers and footers
|
|
- `separator/1` - Visual dividers between content sections
|
|
- `scroll_area/1` - Custom scrollable containers
|
|
|
|
### Forms & Input
|
|
- `button/1` - Interactive buttons with multiple variants
|
|
- `input/1` - Text inputs with validation support
|
|
- `textarea/1` - Multi-line text input areas
|
|
- `checkbox/1` - Binary choice inputs
|
|
- `radio_group/1` - Single choice from multiple options
|
|
- `select/1` - Dropdown selection menus
|
|
- `slider/1` - Range value selection
|
|
- `switch/1` - Toggle controls
|
|
- `form/1`, `form_item/1`, `form_label/1` - Form structure and validation
|
|
|
|
### Navigation
|
|
- `tabs/1` - Tabbed content navigation
|
|
- `breadcrumb/1` - Hierarchical navigation paths
|
|
- `pagination/1` - Page navigation controls
|
|
- `sidebar/1` - Application navigation sidebars
|
|
|
|
### Overlays & Dialogs
|
|
- `dialog/1` - Modal dialogs and confirmations
|
|
- `alert_dialog/1` - Alert and confirmation dialogs
|
|
- `sheet/1` - Slide-out panels
|
|
- `popover/1` - Contextual popup content
|
|
- `tooltip/1` - Hover information displays
|
|
- `hover_card/1` - Rich hover content
|
|
- `dropdown_menu/1` - Contextual action menus
|
|
|
|
### Feedback & Status
|
|
- `alert/1` - Status messages and notifications
|
|
- `badge/1` - Labels and status indicators
|
|
- `progress/1` - Progress bars and loading states
|
|
- `skeleton/1` - Loading placeholder content
|
|
|
|
### Data Display
|
|
- `table/1` - Data tables with sorting and selection
|
|
- `chart/1` - Data visualization charts
|
|
- `avatar/1` - User profile images
|
|
- `accordion/1` - Collapsible content sections
|
|
|
|
### Utility
|
|
- `toggle/1`, `toggle_group/1` - Toggle controls and groups
|
|
- `collapsible/1` - Expandable content areas
|
|
- `command/1` - Command palette interfaces
|
|
|
|
## Architecture
|
|
|
|
SaladUI uses a hybrid architecture combining:
|
|
|
|
- **Phoenix Function Components** - Server-side rendering with HEEx templates
|
|
- **JavaScript State Machines** - Client-side behavior and interactivity
|
|
- **LiveView Hooks** - Seamless server-client communication
|
|
- **Automatic ARIA** - Accessibility attributes managed by the framework
|
|
|
|
## Usage Patterns
|
|
|
|
### Basic Component Usage
|
|
|
|
<.button variant="outline" size="lg">
|
|
Large Outline Button
|
|
</.button>
|
|
|
|
### Form Integration
|
|
|
|
<.form for={@form} phx-change="validate" phx-submit="save">
|
|
<.form_item>
|
|
<.form_label>Email</.form_label>
|
|
<.form_control>
|
|
<.input field={@form[:email]} type="email" />
|
|
</.form_control>
|
|
<.form_message field={@form[:email]} />
|
|
</.form_item>
|
|
</.form>
|
|
|
|
### Interactive Components with Events
|
|
|
|
<.dialog id="user-dialog" on-open={JS.push("dialog_opened")}>
|
|
<.dialog_trigger>
|
|
<.button>Edit Profile</.button>
|
|
</.dialog_trigger>
|
|
<.dialog_content>
|
|
<!-- Dialog content -->
|
|
</.dialog_content>
|
|
</.dialog>
|
|
|
|
### Server-Client Communication
|
|
|
|
# Send commands to components from LiveView
|
|
def handle_event("open_dialog", _params, socket) do
|
|
socket = RiverConnectWeb.Components.UI.LiveView.send_command(socket, "user-dialog", "open")
|
|
{:noreply, socket}
|
|
end
|
|
|
|
## Customization
|
|
|
|
Components support extensive customization through:
|
|
|
|
- **Variants** - Pre-defined style variations (e.g., `variant="destructive"`)
|
|
- **Classes** - Custom CSS classes via the `class` attribute
|
|
- **Slots** - Flexible content areas within components
|
|
- **Attributes** - Comprehensive configuration options
|
|
|
|
## Accessibility
|
|
|
|
All components include:
|
|
|
|
- Proper ARIA attributes and roles
|
|
- Keyboard navigation support
|
|
- Focus management for overlays
|
|
- Screen reader announcements
|
|
- High contrast support
|
|
|
|
## Development
|
|
|
|
When extending SaladUI:
|
|
|
|
1. **Follow naming conventions** - Use `kebab-case` for data attributes
|
|
2. **Implement state machines** - Define clear states and transitions
|
|
3. **Handle accessibility** - Include ARIA configuration
|
|
4. **Test thoroughly** - Verify keyboard and screen reader usage
|
|
5. **Document examples** - Provide clear usage examples
|
|
"""
|
|
|
|
def component do
|
|
quote do
|
|
use Phoenix.Component
|
|
|
|
import RiverConnectWeb.Components.UI.Helpers
|
|
|
|
alias Phoenix.LiveView.JS
|
|
|
|
defp classes(input) do
|
|
TwMerge.merge(List.flatten(input))
|
|
end
|
|
end
|
|
end
|
|
|
|
@doc """
|
|
When used, dispatch to the appropriate macro.
|
|
"""
|
|
defmacro __using__(which) when is_atom(which) do
|
|
apply(__MODULE__, which, [])
|
|
end
|
|
|
|
defmacro __using__(_) do
|
|
quote do
|
|
import RiverConnectWeb.Components.UI.Accordion
|
|
import RiverConnectWeb.Components.UI.Alert
|
|
import RiverConnectWeb.Components.UI.AlertDialog
|
|
import RiverConnectWeb.Components.UI.Avatar
|
|
import RiverConnectWeb.Components.UI.Badge
|
|
import RiverConnectWeb.Components.UI.Breadcrumb
|
|
import RiverConnectWeb.Components.UI.Button
|
|
import RiverConnectWeb.Components.UI.Card
|
|
import RiverConnectWeb.Components.UI.Chart
|
|
import RiverConnectWeb.Components.UI.Checkbox
|
|
import RiverConnectWeb.Components.UI.Collapsible
|
|
import RiverConnectWeb.Components.UI.Dialog
|
|
import RiverConnectWeb.Components.UI.DropdownMenu
|
|
import RiverConnectWeb.Components.UI.Form
|
|
import RiverConnectWeb.Components.UI.Helpers
|
|
import RiverConnectWeb.Components.UI.HoverCard
|
|
import RiverConnectWeb.Components.UI.Icon
|
|
import RiverConnectWeb.Components.UI.Input
|
|
import RiverConnectWeb.Components.UI.Label
|
|
import RiverConnectWeb.Components.UI.Menu
|
|
import RiverConnectWeb.Components.UI.Pagination
|
|
import RiverConnectWeb.Components.UI.Popover
|
|
import RiverConnectWeb.Components.UI.Progress
|
|
import RiverConnectWeb.Components.UI.RadioGroup
|
|
import RiverConnectWeb.Components.UI.ScrollArea
|
|
import RiverConnectWeb.Components.UI.Select
|
|
import RiverConnectWeb.Components.UI.Separator
|
|
import RiverConnectWeb.Components.UI.Sheet
|
|
import RiverConnectWeb.Components.UI.Sidebar
|
|
import RiverConnectWeb.Components.UI.Skeleton
|
|
import RiverConnectWeb.Components.UI.Slider
|
|
import RiverConnectWeb.Components.UI.Switch
|
|
import RiverConnectWeb.Components.UI.Table
|
|
import RiverConnectWeb.Components.UI.Tabs
|
|
import RiverConnectWeb.Components.UI.Textarea
|
|
import RiverConnectWeb.Components.UI.Toggle
|
|
import RiverConnectWeb.Components.UI.ToggleGroup
|
|
import RiverConnectWeb.Components.UI.Tooltip
|
|
end
|
|
end
|
|
end
|