@maxsteinwender/sort-ui 1.1.0 → 1.1.1

package/guidelines/components.md

@@ -0,0 +1,406 @@
+# Component Usage Guidelines
+
+Complete reference for components in `@maxsteinwender/sort-ui`.
+
+## Component Reuse (CRITICAL)
+
+**Always reuse existing SortUI components — never inline custom markup when a component exists.**
+
+This is the most common failure mode for generated UIs. Pattern:
+
+- Status pill → `<Badge>` (not `<span className="bg-green-100 px-2 py-1 rounded-full">`)
+- Progress indicator → `<ProgressBar>` / `<RadialProgressBar>` (not a custom `<div>`)
+- User image → `<Avatar>` (not `<img className="rounded-full">`)
+- Clickable action → `<Button>` / `<LinkButton>` / `<ControlButton>` (not `<div onClick>`)
+- Form text input → `<InputField>` (not `<input>` with hand-rolled styling)
+- Section header + body → `<Card>` with `CardHeader`/`CardContent`/`CardFooter`
+
+```tsx
+// ✅ DO
+<Badge color="green" shape="pill">Active</Badge>
+<Avatar src="/u.jpg" fallback="MS" size="md" />
+<ProgressBar value={75} label labelText="Upload" />
+
+// ❌ DON'T
+<span className="inline-flex bg-green-100 text-green-800 px-2 py-1 rounded-full text-xs">Active</span>
+<img src="/u.jpg" className="w-10 h-10 rounded-full" />
+<div className="h-2 bg-sui-bg-muted"><div style={{width:"75%"}} className="h-full bg-sui-state-primary" /></div>
+```
+
+---
+
+## Import Paths
+
+```tsx
+// Main components
+import { Button, InputField, Avatar, Badge, Card } from "@maxsteinwender/sort-ui";
+
+// Form components (React Hook Form wrappers) — separate sub-entry
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@maxsteinwender/sort-ui/form";
+
+// Toast
+import { Toaster } from "@maxsteinwender/sort-ui";
+import { toast } from "sonner";
+```
+
+---
+
+## Buttons & Actions
+
+| Component | Variants | Key Props | Common Use |
+|-----------|----------|-----------|------------|
+| **Button** | `default`, `ghost`, `destructive`, `secondary`, `outline`, `ghost-muted` | `variant`, `size`, `shape`, `iconOnly`, `loading`, `asChild` | Primary actions |
+| **ButtonGroup** | — | `size`, `aria-label` (required), `orientation` | Toolbar groups |
+| **ButtonGroupItem** | — | `label`, `leadIcon`, `tailIcon`, `badge`, `iconOnly` | Items in ButtonGroup |
+| **LinkButton** | `default`, `muted`, `informative` | `variant`, `size`, `leadIcon`, `tailIcon` | Styled links |
+| **SocialButton** | `secondary`, `brand` | `brand` (required), `shape`, `iconOnly` | Social login |
+| **ControlButton** | `default`, `inverted` | `size`, `shape`, `dismissLabel`, `asSpan` | Dismiss / small controls |
+| **FilterButton** | — | `selected`, `filterValue`, `onClearFilter` | Filter toggles |
+
+```tsx
+// ✅ iconOnly requires aria-label
+<Button iconOnly aria-label="Settings"><i className="ri-settings-line" /></Button>
+
+// ✅ loading prop replaces manual spinner
+<Button loading>Saving…</Button>
+
+// ✅ Size + variant
+<Button size="lg" variant="destructive">Delete</Button>
+
+// ✅ ButtonGroup
+<ButtonGroup size="md" aria-label="Text formatting">
+  <ButtonGroupItem label="Bold" leadIcon="ri-bold" />
+  <ButtonGroupItem label="Italic" leadIcon="ri-italic" />
+</ButtonGroup>
+```
+
+---
+
+## Navigation
+
+| Component | Variants | Key Props | Common Use |
+|-----------|----------|-----------|------------|
+| **SortBreadcrumb** | `slash`, `arrow`, `dot` | `items`, `variant` | Page navigation |
+| **NavigationMenu** | — | — | Top-level nav with dropdowns |
+| **Tabs** | — | `value`, `onValueChange`, `defaultValue` | Content switching |
+| **Paginator** | `simple`, `numbered`, `dots` | `currentPage`, `totalPages`, `onPageChange` | Pagination |
+| **HorizontalStepper**, **VerticalStepper** | — | `steps`, `currentStep` | Multi-step flows |
+
+```tsx
+<SortBreadcrumb
+  variant="slash"
+  items={[
+    { label: "Home", href: "/" },
+    { label: "Projects", href: "/projects" },
+    { label: "Current Project" },
+  ]}
+/>
+
+<Tabs value={activeTab} onValueChange={setActiveTab}>
+  <TabsList>
+    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
+  </TabsList>
+  <TabsContent value="tab1">…</TabsContent>
+</Tabs>
+```
+
+---
+
+## Forms & Inputs
+
+| Component | Variants | Key Props |
+|-----------|----------|-----------|
+| **InputField** | `default`, `soft`, `shadow` | `label`, `error`, `leadIcon`, `tailIcon`, `prefix`, `suffix`, `leadAddon`, `tailAddon`, `tags`, `leadButton`, `tailButton` |
+| **TextAreaField** | `default`, `soft`, `shadow` | `label`, `error`, `rows` |
+| **Checkbox** | `default`, `shadow` | `checked`, `onCheckedChange`, `variant` |
+| **CheckboxWithText** / **CheckboxCard** | — | `label`, `description`, `checkboxPosition` / `title`, `description`, `layout` |
+| **RadioButton** / **WithText** / **Card** | — | `value`, `label`, `description`, `radioPosition`, `layout` |
+| **Switch** / **SwitchWithText** | — | `checked`, `onCheckedChange`, `label`, `description` |
+| **Select**, **SelectMenu** | — | `value`, `onValueChange`, `searchInput` |
+| **DatePicker**, **DateRangePicker** | — | `date`, `onDateChange`, `dateRange`, `onDateRangeChange` |
+| **FileUpload** | — | `files`, `onFilesAdded`, `accept`, `maxSize`, `multiple`, `autoPreview` |
+| **Slider**, **SliderRange**, **DataRangeSlider** | — | `value`, `onValueChange`, `min`, `max`, `step` |
+
+```tsx
+// InputField with error
+<InputField
+  label="Email"
+  required
+  error={errors.email}
+  leadIcon={<i className="ri-mail-line" />}
+/>
+
+// Addons / prefix / suffix
+<InputField label="Website" leadAddon="https://" tailAddon=".com" />
+<InputField label="Amount" prefix="$" suffix="USD" />
+
+// Checkbox patterns
+<CheckboxCard
+  title="Feature A"
+  description="Description"
+  selected={selected}
+  onSelectedChange={setSelected}
+  checkboxPosition="right"
+/>
+```
+
+**FileUpload workflow (parent-owned state):**
+```tsx
+const [files, setFiles] = useState<UploadFile[]>([]);
+
+<FileUpload
+  files={files}
+  onFilesAdded={(newFiles) => {
+    const uploads = newFiles.map(file => ({
+      id: crypto.randomUUID(),
+      file,
+      state: "uploading" as const,
+      progress: 0,
+    }));
+    setFiles([...files, ...uploads]);
+  }}
+  onRemove={(id) => setFiles(files.filter(f => f.id !== id))}
+  accept="image/*"
+  maxSize={10 * 1024 * 1024}
+  multiple
+  autoPreview
+/>
+```
+
+---
+
+## Data Display
+
+| Component | Variants | Key Props |
+|-----------|----------|-----------|
+| **Avatar** | — | `src`, `fallback`, `size`, `shape`, `ring`, `topBadge`, `bottomBadge`, `color` |
+| **AvatarGroup** | — | `items`, `size`, `stacking`, `aria-label` |
+| **Badge** | `label`, `icon`, `image`, `dot` | `color`, `size`, `shape`, `variant`, `onClose` |
+| **Card** | `default`, `flat` | `variant` |
+| **Table** / **GridTable** | — | row/col composition |
+| **Skeleton** | — | `className` |
+| **EmptyState** | `default`, `icon`, `placeholder-icon` | `title`, `description`, `icon`, `action` |
+
+```tsx
+// Avatar with badge
+<Avatar
+  src="/user.jpg"
+  alt="User"
+  fallback="UN"
+  size="md"
+  bottomBadge
+  bottomBadgeVariant="online"
+  bottomBadgeLabel="Online"
+/>
+
+// Avatar group
+<AvatarGroup
+  items={[
+    { src: "/a.jpg", alt: "Alice", fallback: "A" },
+    { fallback: "B" },
+  ]}
+  size="md"
+  aria-label="2 team members"
+/>
+
+// Badge variants
+<Badge color="green" shape="pill">Active</Badge>
+<Badge variant="icon" icon={<i className="ri-star-fill" />}>Featured</Badge>
+<Badge color="blue" onClose={() => remove()}>Removable Tag</Badge>
+
+// Card composition
+<Card variant="default">
+  <CardCover flush aspectRatio="16/9">
+    <img src="/cover.jpg" alt="Cover" />
+  </CardCover>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Description</CardDescription>
+  </CardHeader>
+  <CardContent>{/* Main content */}</CardContent>
+  <CardFooter>{/* Actions */}</CardFooter>
+</Card>
+```
+
+---
+
+## Feedback
+
+| Component | Variants | Key Props |
+|-----------|----------|-----------|
+| **Alert** | `default`, `destructive` | `variant` |
+| **Toast** | — | via Sonner |
+| **ProgressBar** | `linear`, `dashed` | `value`, `label`, `labelText`, `caption` |
+| **RadialProgressBar** | `default`, `success`, `failed` | `value`, `size`, `shape`, `showValue` |
+| **InlineTips** | `default`, `error`, `success`, `information`, `warning` | `variant`, `colorStyle`, `title` |
+
+```tsx
+// Toast
+import { toast } from "sonner";
+toast.success("Saved");
+toast.error("Failed");
+
+// Progress
+<ProgressBar value={75} label labelText="Upload progress" />
+<RadialProgressBar value={80} size={120} showValue />
+<RadialProgressBar variant="success" value={100} label="Done" shape="half" />
+```
+
+---
+
+## Charts (Recharts — React 19 compat CRITICAL)
+
+**Every Recharts series MUST set `isAnimationActive={false}`.** Recharts 2.x animations rely on removed React 19 APIs and render empty without this prop.
+
+```tsx
+import { ChartContainer, ChartTooltip, ChartTooltipContent, type ChartConfig } from "@maxsteinwender/sort-ui";
+import { LineChart, Line, BarChart, Bar, PieChart, Pie, AreaChart, Area } from "recharts";
+
+const config: ChartConfig = {
+  revenue: { label: "Revenue", color: "var(--chart-1)" },
+  sales:   { label: "Sales",   color: "var(--chart-2)" },
+};
+
+// ✅ Line chart
+<ChartContainer config={config}>
+  <LineChart data={data}>
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <Line dataKey="revenue" stroke="var(--color-revenue)" isAnimationActive={false} />
+  </LineChart>
+</ChartContainer>
+
+// ✅ Bar chart
+<ChartContainer config={config}>
+  <BarChart data={data}>
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <Bar dataKey="sales" fill="var(--color-sales)" isAnimationActive={false} />
+  </BarChart>
+</ChartContainer>
+
+// ✅ Area + Pie
+<Area dataKey="revenue" stroke="var(--color-revenue)" fill="var(--color-revenue)" isAnimationActive={false} />
+<Pie data={pieData} dataKey="value" isAnimationActive={false} />
+
+// ❌ WRONG — animation enabled (default) → empty chart in React 19
+<Line dataKey="revenue" stroke="var(--color-revenue)" />
+```
+
+Chart color tokens: `var(--chart-1)` through `var(--chart-5)`.
+
+---
+
+## Overlays
+
+| Component | Type | Key Props |
+|-----------|------|-----------|
+| **Dialog** | Modal | composition: `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogClose` |
+| **AlertDialog** | Modal | confirmation dialogs |
+| **Sheet** | Drawer | side panels |
+| **Popover** | Floating | popovers |
+| **Tooltip** | Floating | hover tooltips (requires `<TooltipProvider>`) |
+| **DropdownMenu** | Floating | `search`, `searchValue`, `onSearchChange` |
+| **CommandPalette** | Command | cmdk-powered palette |
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Open</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+      <DialogDescription>Description</DialogDescription>
+    </DialogHeader>
+    {/* Content */}
+    <DialogFooter>
+      <DialogClose asChild><Button variant="ghost">Cancel</Button></DialogClose>
+      <Button>Confirm</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button>Menu</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent search searchPlaceholder="Search…">
+    <DropdownMenuLabel>Actions</DropdownMenuLabel>
+    <DropdownMenuItem>Edit</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button iconOnly aria-label="Help"><i className="ri-question-line" /></Button>
+    </TooltipTrigger>
+    <TooltipContent><p>Help text</p></TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+---
+
+## Form Integration (React Hook Form)
+
+**IMPORTANT:** Form components use a separate import path.
+
+```tsx
+import { useForm } from "react-hook-form";
+import { Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage } from "@maxsteinwender/sort-ui/form";
+import { InputField, Button } from "@maxsteinwender/sort-ui";
+
+const form = useForm({ defaultValues: { email: "" } });
+
+<Form {...form}>
+  <form onSubmit={form.handleSubmit(onSubmit)} className="flex flex-col gap-sui-16">
+    <FormField
+      control={form.control}
+      name="email"
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>Email</FormLabel>
+          <FormControl>
+            <InputField {...field} placeholder="you@example.com" />
+          </FormControl>
+          <FormDescription>We'll never share your email.</FormDescription>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+    <Button type="submit">Submit</Button>
+  </form>
+</Form>
+```
+
+---
+
+## Composite Components
+
+| Component | Purpose |
+|-----------|---------|
+| **SignInCard** | Pre-composed sign-in card |
+| **ProductCard** | Pre-composed product card |
+| **MarkdownEditor** | Lexical-based markdown editor |
+| **CodeBlock** | Code display with syntax highlighting |
+| **Userbar**, **SidebarMenuItem**, **SidebarCard** | Sidebar layout primitives |
+
+---
+
+## Icons
+
+**IMPORTANT:** See `icon-discovery.md` for detailed icon guidelines.
+
+SortUI uses **Remix Icons** (bundled). Use `<i className="ri-{name}-{variant}" />` syntax.
+
+```tsx
+<Button><i className="ri-search-line" />Search</Button>
+<i className="ri-user-fill" />
+
+// Icon color via token (no sui- prefix variations — text-sui-icon-* only)
+<i className="ri-user-fill text-sui-icon-subtle" />
+```
+
+**DO NOT** install `lucide-react`, `heroicons`, `react-icons`, or any other icon package.

package/guidelines/icon-discovery.md

@@ -0,0 +1,247 @@
+# Icon Discovery and Usage Guidelines
+
+This document explains how to find and use icons in the SortUI Design System.
+
+## Icon Package
+
+**Bundled with:** `@maxsteinwender/sort-ui` (Remix Icons — no separate install)
+**Import:** Icons are loaded automatically via the main CSS bundle
+**Location in package:** `node_modules/@maxsteinwender/sort-ui/dist/styles.css` (font-icon classes)
+
+**DO NOT install `lucide-react`, `heroicons`, `react-icons`, or any other icon package.** Remix Icons is the single source.
+
+## Naming Convention
+
+```
+ri-{icon-name}-{variant}
+```
+
+**Variants:**
+- `-line` — outlined/stroke style (most common)
+- `-fill` — filled/solid style
+
+**Examples:**
+- `ri-user-line`, `ri-user-fill`
+- `ri-settings-line`, `ri-settings-fill`
+- `ri-arrow-right-line`, `ri-arrow-right-fill`
+- `ri-check-line`, `ri-check-fill`
+- `ri-close-line`, `ri-close-fill`
+
+## Usage
+
+Icons are rendered as `<i>` elements with Remix Icon class names:
+
+```tsx
+<i className="ri-user-line" />
+<i className="ri-settings-fill" />
+<i className="ri-arrow-right-line" />
+```
+
+**Color via icon tokens** (note: icon colors use `text-sui-icon-*`):
+```tsx
+<i className="ri-user-fill text-sui-icon-default" />
+<i className="ri-error-warning-line text-sui-icon-destructive" />
+<i className="ri-check-line text-sui-icon-success" />
+<i className="ri-information-line text-sui-icon-informative" />
+<i className="ri-alarm-warning-line text-sui-icon-warning" />
+<i className="ri-user-line text-sui-icon-subtle" />
+```
+
+**Within SortUI components:**
+```tsx
+// Button with lead icon
+<Button>
+  <i className="ri-search-line" />
+  Search
+</Button>
+
+// Icon-only button — MUST have aria-label
+<Button iconOnly aria-label="Settings">
+  <i className="ri-settings-line" />
+</Button>
+
+// InputField with lead icon
+<InputField
+  leadIcon={<i className="ri-mail-line" />}
+  placeholder="Email"
+/>
+```
+
+## Sizing
+
+Most SortUI components handle icon sizing automatically. When direct size control is needed, use Tailwind text-size utilities — do NOT use `ri-xs` / `ri-sm` helpers:
+
+```tsx
+<i className="ri-user-line text-sm" />
+<i className="ri-user-line text-base" />
+<i className="ri-user-line text-lg" />
+<i className="ri-user-line text-xl" />
+<i className="ri-user-line text-2xl" />
+```
+
+## How to Find Icons
+
+**CRITICAL:** Do NOT guess icon names. Icon names must be verified before use.
+
+### Method 1: Search the bundled CSS
+
+The bundled CSS contains every available icon class. Search `node_modules/@maxsteinwender/sort-ui/dist/styles.css` for keywords:
+
+```bash
+grep -o "\.ri-[a-z0-9-]*user[a-z0-9-]*:before" node_modules/@maxsteinwender/sort-ui/dist/styles.css
+grep -o "\.ri-[a-z0-9-]*calendar[a-z0-9-]*:before" node_modules/@maxsteinwender/sort-ui/dist/styles.css
+```
+
+Example workflow:
+1. Identify keyword (e.g., "calendar")
+2. Search styles.css for `ri-calendar`
+3. Find matching icons: `ri-calendar-line`, `ri-calendar-fill`, `ri-calendar-event-line`, `ri-calendar-2-line`, etc.
+
+### Method 2: Official Remix Icon reference
+
+The design system uses **Remix Icon v4.9.1**. All icons from Remix Icon 4.x are available.
+
+Reference: https://remixicon.com/
+
+**Common icon categories:**
+- **System:** settings, more, menu, close, check, error, information, question, warning
+- **Arrows:** arrow-up, arrow-down, arrow-left, arrow-right, chevron-up, chevron-down
+- **Media:** play, pause, stop, volume, image, camera, video
+- **User:** user, team, account, contacts, profile
+- **Files:** file, folder, attachment, download, upload
+- **Communication:** mail, message, chat, notification, phone
+- **Design:** pencil, brush, palette, format, layout
+- **Business:** briefcase, bank, wallet, price-tag, shopping-cart
+- **Maps:** map, pin, location, navigation, compass
+- **Device:** phone, tablet, computer, keyboard, mouse
+- **Weather:** sun, moon, cloud, rain, snow
+
+## Common Icon Patterns
+
+### Navigation icons
+```tsx
+<i className="ri-arrow-left-line" />
+<i className="ri-arrow-right-line" />
+<i className="ri-arrow-up-line" />
+<i className="ri-arrow-down-line" />
+<i className="ri-chevron-left-line" />
+<i className="ri-chevron-right-line" />
+<i className="ri-menu-line" />
+<i className="ri-close-line" />
+<i className="ri-more-line" />
+```
+
+### Action icons
+```tsx
+<i className="ri-add-line" />
+<i className="ri-subtract-line" />
+<i className="ri-edit-line" />
+<i className="ri-delete-bin-line" />
+<i className="ri-save-line" />
+<i className="ri-download-line" />
+<i className="ri-upload-line" />
+<i className="ri-share-line" />
+<i className="ri-search-line" />
+<i className="ri-filter-line" />
+```
+
+### Status icons
+```tsx
+<i className="ri-check-line text-sui-icon-success" />
+<i className="ri-close-circle-line text-sui-icon-destructive" />
+<i className="ri-error-warning-line text-sui-icon-warning" />
+<i className="ri-information-line text-sui-icon-informative" />
+<i className="ri-checkbox-circle-line text-sui-icon-success" />
+```
+
+### User / Social icons
+```tsx
+<i className="ri-user-line" />
+<i className="ri-user-fill" />
+<i className="ri-team-line" />
+<i className="ri-account-circle-line" />
+<i className="ri-heart-line" />
+<i className="ri-star-line" />
+<i className="ri-thumb-up-line" />
+```
+
+### Communication icons
+```tsx
+<i className="ri-mail-line" />
+<i className="ri-message-line" />
+<i className="ri-chat-line" />
+<i className="ri-notification-line" />
+<i className="ri-phone-line" />
+<i className="ri-send-plane-line" />
+```
+
+### File / Document icons
+```tsx
+<i className="ri-file-line" />
+<i className="ri-folder-line" />
+<i className="ri-attachment-line" />
+<i className="ri-file-text-line" />
+<i className="ri-file-pdf-line" />
+<i className="ri-image-line" />
+```
+
+### Settings / System icons
+```tsx
+<i className="ri-settings-line" />
+<i className="ri-equalizer-line" />
+<i className="ri-tools-line" />
+<i className="ri-lock-line" />
+<i className="ri-eye-line" />
+<i className="ri-eye-off-line" />
+```
+
+## DO / DON'T
+
+**DO:**
+```tsx
+<i className="ri-user-line" />
+<i className="ri-check-line" />    {/* outlined */}
+<i className="ri-check-fill" />    {/* filled */}
+
+// Icon-only button with aria-label
+<Button iconOnly aria-label="Settings">
+  <i className="ri-settings-line" />
+</Button>
+```
+
+**DON'T:**
+```tsx
+// ❌ Guessed icon names
+<i className="ri-profile-line" />   {/* doesn't exist — use ri-user-line */}
+
+// ❌ Installing alternate icon packages
+import { User } from "lucide-react";
+
+// ❌ Icon-only button without aria-label
+<Button iconOnly>
+  <i className="ri-settings-line" />
+</Button>
+```
+
+## Verifying Icon Existence
+
+Before using an icon in generated code:
+
+1. **Search the bundled CSS** for the icon class
+2. **Check the pattern** matches `ri-{name}-line` or `ri-{name}-fill`
+3. **If uncertain**, pick a similar known icon (e.g., `ri-user-line` instead of guessing `ri-profile-line`)
+
+```bash
+# Verify ri-calendar-event-line exists
+grep "ri-calendar-event-line:before" node_modules/@maxsteinwender/sort-ui/dist/styles.css
+# ✓ If output contains "content:" the icon is valid
+```
+
+## Reminders
+
+- **Remix Icons are bundled** — no separate package install
+- **Do NOT install `lucide-react`** or other icon packages
+- **Always verify icon existence** before use
+- **Use `-line` for outlined**, `-fill` for solid
+- **Provide `aria-label`** for icon-only buttons
+- **Icon color via `text-sui-icon-*` tokens** (never raw hex)