@maxsteinwender/sort-ui 1.0.8 → 1.1.0

package/guidelines/components.md

@@ -1,406 +0,0 @@
-# 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

@@ -1,247 +0,0 @@
-# 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)