npm - @maxsteinwender/sort-ui - Versions diffs - 1.0.8 → 1.1.0 - Mend

@maxsteinwender/sort-ui 1.0.8 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/dist/index.d.mts +63 -1
package/dist/index.d.ts +63 -1
package/dist/index.js +662 -542
package/dist/index.mjs +661 -541
package/dist/styles.css +294 -212
package/dist/tailwind-preset.js +13 -0
package/dist/tailwind-preset.mjs +13 -0
package/package.json +5 -3
package/guidelines/Guidelines.md +0 -294
package/guidelines/components.md +0 -406
package/guidelines/icon-discovery.md +0 -247
package/guidelines/setup.md +0 -343
package/guidelines/styles.md +0 -356
package/guidelines/tokens.md +0 -354

package/guidelines/setup.md DELETED Viewed

@@ -1,343 +0,0 @@
-# SortUI Design System — Setup Instructions
-Complete setup guide for integrating `@maxsteinwender/sort-ui` into your project.
----
-## Package Manager
-**Use npm.** This package is authored and published using npm. Examples in these guidelines always show `npm install`. Do not suggest `pnpm add` or `yarn add`.
----
-## Package Installation
-**CRITICAL**: You MUST explicitly install every package listed below as a direct dependency, exactly as written. Transitive availability does NOT count as installed.
-```bash
-npm install @maxsteinwender/sort-ui
-```
-Add to your `package.json`:
-```json
-{
-  "dependencies": {
-    "@maxsteinwender/sort-ui": "^1.0.8"
-  }
-}
-```
-**Peer dependencies (required):**
-- `react` >= 19.0.0
-- `react-dom` >= 19.0.0
-If using form components (React Hook Form wrappers), install:
-```bash
-npm install react-hook-form
-```
----
-## CSS Import
-Import the bundled CSS **once** at your app entry point (e.g., root layout, `_app.tsx`, or `main.tsx`):
-```tsx
-import "@maxsteinwender/sort-ui/styles.css";
-```
-This loads:
-- Design tokens (CSS custom properties)
-- Remix Icons (font icons, bundled)
-- Component styles
-- Redaction font (bundled)
-- Geist Sans + Geist Mono (bundled)
-**IMPORTANT:** Only import this CSS file once. Do not import it in multiple files.
----
-## Theme Configuration — All 4 Themes
-Apply ONE of these classes to the root `<html>` (or `<body>`) element. The SortUI Design System ships **four** themes and all four must render correctly for any generated UI.
-| Theme Class | Color Scheme | Mode |
-|-------------|--------------|------|
-| `light` | zinc/blue | light (default) |
-| `dark` | zinc/blue | dark |
-| `theme-2` | neutral/orange | light |
-| `theme-2-dark` | neutral/orange | dark |
-**Example — light (default):**
-```tsx
-// app/layout.tsx
-import "@maxsteinwender/sort-ui/styles.css";
-export default function RootLayout({ children }) {
-  return (
-    <html lang="en" className="light">
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-**Example — dark:**
-```tsx
-<html lang="en" className="dark">
-  <body>{children}</body>
-</html>
-```
-**Example — theme-2 (neutral/orange, light):**
-```tsx
-<html lang="en" className="theme-2">
-  <body>{children}</body>
-</html>
-```
-**Example — theme-2-dark (neutral/orange, dark):**
-```tsx
-<html lang="en" className="theme-2-dark">
-  <body>{children}</body>
-</html>
-```
-**Dynamic theme switching:**
-```tsx
-"use client";
-import { useEffect, useState } from "react";
-type Theme = "light" | "dark" | "theme-2" | "theme-2-dark";
-export function ThemeProvider({ children }: { children: React.ReactNode }) {
-  const [theme, setTheme] = useState<Theme>("light");
-  useEffect(() => {
-    document.documentElement.className = theme;
-  }, [theme]);
-  return <>{children}</>;
-}
-```
-Theme variants swap CSS variables automatically — never hard-code theme-specific class logic in components.
----
-## Tailwind CSS v3 Setup
-**IMPORTANT:** SortUI targets **Tailwind CSS v3** (`^3.4.1`). It is **NOT** Tailwind v4. Do not use the v4 `@theme` directive or v4-only APIs. The package ships a **Tailwind v3 preset** that extends Tailwind with SUI design tokens.
-### 1. Install Tailwind CSS v3
-```bash
-npm install -D tailwindcss@^3.4.1 postcss autoprefixer
-```
-### 2. Configure Tailwind
-Import the SortUI preset in your `tailwind.config.ts` (or `tailwind.config.js`):
-```ts
-// tailwind.config.ts
-import type { Config } from "tailwindcss";
-import sortUiPreset from "@maxsteinwender/sort-ui/tailwind-preset";
-const config: Config = {
-  presets: [sortUiPreset],
-  content: [
-    "./src/app/**/*.{ts,tsx,js,jsx}",
-    "./src/components/**/*.{ts,tsx,js,jsx}",
-  ],
-};
-export default config;
-```
-**JavaScript version:**
-```js
-// tailwind.config.js
-const sortUiPreset = require("@maxsteinwender/sort-ui/tailwind-preset");
-module.exports = {
-  presets: [sortUiPreset],
-  content: [
-    "./src/app/**/*.{ts,tsx,js,jsx}",
-    "./src/components/**/*.{ts,tsx,js,jsx}",
-  ],
-};
-```
-### 3. Add Tailwind v3 directives
-Create or update your global CSS file (e.g., `globals.css`):
-```css
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-```
-**IMPORTANT:** Import `@maxsteinwender/sort-ui/styles.css` BEFORE your global CSS file:
-```tsx
-// app/layout.tsx
-import "@maxsteinwender/sort-ui/styles.css";
-import "./globals.css";
-```
----
-## Tailwind Utility Classes (correct naming)
-The SortUI preset exposes utility classes that follow the `sui-` prefix rules in `Guidelines.md`:
-| Token Category | Prefix? | Tailwind Classes | Example |
-|----------------|---------|------------------|---------|
-| Background | `sui-` | `bg-sui-bg-default`, `bg-sui-bg-subtle` | `<div className="bg-sui-bg-default" />` |
-| Text | `sui-` | `text-sui-text-default`, `text-sui-text-subtle` | `<p className="text-sui-text-default" />` |
-| Border color | `sui-` | `border-sui-border-default` | `<div className="border border-sui-border-default" />` |
-| Icon color | `sui-` | `text-sui-icon-default`, `text-sui-icon-destructive` | `<i className="ri-user-line text-sui-icon-subtle" />` |
-| Spacing | `sui-` | `p-sui-24`, `gap-sui-16`, `m-sui-8`, `space-y-sui-16` | `<div className="p-sui-24 gap-sui-16" />` |
-| Radius | **no prefix** | `rounded-md`, `rounded-lg`, `rounded-full`, `rounded-card-md` | `<div className="rounded-lg" />` |
-| Shadow | **no prefix** | `shadow-default`, `shadow-card`, `shadow-focus`, `shadow-modal-md` | `<div className="shadow-card" />` |
-| Border width | **no prefix** | `border`, `border-md`, `border-lg` | `<div className="border-md" />` |
-❌ `shadow-sui-default`, `shadow-sui-card`, `shadow-sm`, `shadow-md`, `shadow-lg` — **these do not exist.**
-❌ `rounded-sui-md`, `rounded-sui-lg`, `rounded-sui-full` — **these do not exist.**
----
-## Toast Provider Setup
-If using the Toast component (powered by Sonner), add the `<Toaster />` component to your root layout:
-```tsx
-// app/layout.tsx
-import { Toaster } from "@maxsteinwender/sort-ui";
-import "@maxsteinwender/sort-ui/styles.css";
-export default function RootLayout({ children }) {
-  return (
-    <html lang="en" className="light">
-      <body>
-        {children}
-        <Toaster />
-      </body>
-    </html>
-  );
-}
-```
-**Usage:**
-```tsx
-import { toast } from "sonner";
-toast.success("Operation successful");
-toast.error("Something went wrong");
-```
----
-## Tooltip Provider Setup
-If using Tooltip components, wrap your app with `<TooltipProvider>`:
-```tsx
-import { TooltipProvider } from "@maxsteinwender/sort-ui";
-export default function RootLayout({ children }) {
-  return (
-    <html lang="en" className="light">
-      <body>
-        <TooltipProvider>{children}</TooltipProvider>
-      </body>
-    </html>
-  );
-}
-```
----
-## Form Integration
-For form components, install `react-hook-form` and import from the `/form` entry point:
-```bash
-npm install react-hook-form
-```
-```tsx
-import { useForm } from "react-hook-form";
-import { Form, FormField, FormItem, FormLabel, FormControl, 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>
-          <FormMessage />
-        </FormItem>
-      )}
-    />
-    <Button type="submit">Submit</Button>
-  </form>
-</Form>
-```
----
-## Icon Usage
-Icons are bundled with the design system (Remix Icons). No additional installation required.
-```tsx
-<i className="ri-user-line" />
-<i className="ri-settings-fill" />
-<Button>
-  <i className="ri-search-line" />
-  Search
-</Button>
-```
-**DO NOT install `lucide-react`, `heroicons`, `react-icons`, or any other icon package.**
-See `icon-discovery.md` for the icon verification workflow.
----
-## TypeScript Support
-The package ships TypeScript definitions; no additional setup required.
-```tsx
-import type { ButtonProps, InputFieldProps } from "@maxsteinwender/sort-ui";
-```
----
-## Setup Checklist
-- [ ] Installed `@maxsteinwender/sort-ui` via **npm** (not pnpm/yarn)
-- [ ] Imported `@maxsteinwender/sort-ui/styles.css` once at app entry
-- [ ] Set one of the 4 theme classes on `<html>`: `light`, `dark`, `theme-2`, or `theme-2-dark`
-- [ ] Configured **Tailwind v3** with SortUI preset (not v4)
-- [ ] Added `@tailwind base; @tailwind components; @tailwind utilities;` to global CSS
-- [ ] Added `<Toaster />` to root layout (if using toasts)
-- [ ] Wrapped app with `<TooltipProvider>` (if using tooltips)
-- [ ] Installed `react-hook-form` (if using form components)
-- [ ] Did NOT install `lucide-react` or any additional icon package

package/guidelines/styles.md DELETED Viewed

@@ -1,356 +0,0 @@
-# Style System Guidelines
-Spacing, layout, responsive patterns, and CSS methodology for SortUI.
-## CSS Methodology
-SortUI uses **Tailwind CSS v3** (`^3.4.1`). It is **NOT** Tailwind v4. The design system provides:
-1. **Design tokens** (CSS custom properties)
-2. **Tailwind v3 preset** (extends Tailwind with SUI tokens)
-3. **Component classes** (component-specific styles)
-**Never emit Tailwind v4 syntax** (`@theme` directive, v4-only APIs). Always author styles for Tailwind v3.
----
-## Spacing Scale (WITH `sui-` prefix)
-SortUI uses a numeric spacing scale based on pixels. Use with `gap-`, `p-`, `m-`, `space-x-`, `space-y-`, etc.
-| Class | Size | Common Usage |
-|-------|------|--------------|
-| `gap-sui-none` | 0px | No spacing |
-| `gap-sui-1` | 1px | Hairline |
-| `gap-sui-2` | 2px | Minimal |
-| `gap-sui-4` | 4px | Extra small |
-| `gap-sui-6` | 6px | Small− |
-| `gap-sui-8` | 8px | Small |
-| `gap-sui-12` | 12px | Medium small |
-| `gap-sui-16` | 16px | Medium — form field gap |
-| `gap-sui-20` | 20px | Medium+ |
-| `gap-sui-24` | 24px | Large — card padding |
-| `gap-sui-32` | 32px | Section gap |
-| `gap-sui-40` | 40px | XXL |
-| `gap-sui-48` | 48px | XXXL |
-| `gap-sui-64` | 64px | Large sections |
-| `gap-sui-80` | 80px | Hero |
-| `gap-sui-96` – `gap-sui-384` | 96–384px | Page sections, hero spacing |
-**Usage:**
-```tsx
-<div className="p-sui-24" />        {/* padding: 24px */}
-<div className="m-sui-16" />        {/* margin: 16px */}
-<div className="gap-sui-12" />      {/* gap: 12px */}
-<div className="space-x-sui-8" />   {/* horizontal spacing */}
-<div className="space-y-sui-16" />  {/* vertical spacing */}
-```
----
-## Common Spacing Patterns
-### Component Spacing
-| Pattern | Class |
-|---------|-------|
-| Input field padding | `px-sui-12 py-sui-10` |
-| Button padding (md) | `px-sui-12 py-sui-8` |
-| Button padding (lg) | `px-sui-16 py-sui-12` |
-| Card padding | `p-sui-24` |
-| Form field gap | `gap-sui-16` |
-| Section gap | `gap-sui-32` or `gap-sui-48` |
-| Page margins | `mx-sui-24` or `mx-sui-32` |
-### Layout Spacing
-| Context | Class | Rationale |
-|---------|-------|-----------|
-| Between form fields | `gap-sui-16` | Comfortable reading distance |
-| Between form sections | `gap-sui-32` | Clear visual grouping |
-| Card internal padding | `p-sui-24` | Balanced white space |
-| Modal/dialog padding | `p-sui-24` or `p-sui-32` | |
-| Navigation items | `gap-sui-8` or `gap-sui-12` | |
-**Example form spacing:**
-```tsx
-<form className="flex flex-col gap-sui-16">
-  <InputField label="Name" />
-  <InputField label="Email" />
-  <div className="mt-sui-16">
-    <h3 className="text-sui-text-default">Additional Info</h3>
-  </div>
-  <TextAreaField label="Bio" />
-  <Button className="mt-sui-24">Submit</Button>
-</form>
-```
----
-## Layout Primitives
-SortUI does not provide explicit layout components (Stack, Inline, Box). Use **Tailwind Flexbox and Grid utilities** for layout.
-### Flexbox Patterns
-```tsx
-{/* Vertical stack */}
-<div className="flex flex-col gap-sui-16">…</div>
-{/* Horizontal inline */}
-<div className="flex flex-row gap-sui-8 items-center">…</div>
-{/* Space between (navbar) */}
-<div className="flex items-center justify-between">…</div>
-{/* Centered content */}
-<div className="flex items-center justify-center min-h-screen">…</div>
-```
-### Grid Patterns
-```tsx
-{/* Responsive cards grid */}
-<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-sui-24">
-  <Card>Item 1</Card>
-  <Card>Item 2</Card>
-  <Card>Item 3</Card>
-</div>
-{/* Form grid */}
-<div className="grid grid-cols-1 md:grid-cols-2 gap-sui-16">
-  <InputField label="First Name" />
-  <InputField label="Last Name" />
-  <InputField label="Email" className="md:col-span-2" />
-</div>
-{/* Dashboard grid */}
-<div className="grid grid-cols-12 gap-sui-24">
-  <div className="col-span-12 lg:col-span-8">Main</div>
-  <div className="col-span-12 lg:col-span-4">Sidebar</div>
-</div>
-```
----
-## Responsive Patterns
-### Breakpoints (Tailwind v3)
-SortUI uses the **default Tailwind v3 breakpoints**:
-| Breakpoint | Min Width | Usage |
-|------------|-----------|-------|
-| `sm` | 640px | Small tablets |
-| `md` | 768px | Tablets |
-| `lg` | 1024px | Laptops |
-| `xl` | 1280px | Desktops |
-| `2xl` | 1536px | Large desktops |
-**Mobile-first approach:**
-```tsx
-<div className="p-sui-16 md:p-sui-24 lg:p-sui-32">Content</div>
-```
-### Responsive Spacing
-| Pattern | Mobile | Tablet | Desktop |
-|---------|--------|--------|---------|
-| Page container padding | `px-sui-16` | `md:px-sui-24` | `lg:px-sui-32` |
-| Section gap | `gap-sui-32` | `md:gap-sui-48` | `lg:gap-sui-64` |
-| Grid columns | 1 | 2 | 3–4 |
-```tsx
-<div className="px-sui-16 md:px-sui-24 lg:px-sui-32 py-sui-32 md:py-sui-48 lg:py-sui-64">
-  <div className="max-w-7xl mx-auto">
-    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-sui-24">
-      {/* Cards */}
-    </div>
-  </div>
-</div>
-```
----
-## Radius & Shadow in Layouts (NO `sui-` prefix)
-Always use the correct class names (see `tokens.md` for the full list):
-```tsx
-{/* ✅ Card with radius + shadow */}
-<div className="bg-sui-bg-card border border-sui-border-default rounded-lg shadow-card p-sui-24">
-  Content
-</div>
-{/* ✅ Pill */}
-<div className="rounded-full bg-sui-badge-blue px-sui-12 py-sui-4">Label</div>
-{/* ❌ Wrong */}
-<div className="rounded-sui-lg shadow-sui-card" />
-<div className="rounded-lg shadow-md" />
-```
----
-## Styling Approach
-**Use Tailwind utilities FIRST:**
-```tsx
-<div className="flex items-center gap-sui-12 p-sui-16 bg-sui-bg-default border border-sui-border-default rounded-lg">
-  Content
-</div>
-```
-**Use CSS custom properties for dynamic values:**
-```tsx
-<div style={{
-  color: "var(--text-subtle)",
-  padding: "var(--spacing-16)",
-}}>
-  Content
-</div>
-```
-**Override component styles via `className`:**
-```tsx
-<Button className="w-full md:w-auto">
-  Full width on mobile, auto on desktop
-</Button>
-```
-### Custom CSS (when needed, token-based only)
-```css
-.custom-card {
-  background: var(--bg-card);
-  border: 1px solid var(--border-default);
-  border-radius: var(--radius-md);
-  padding: var(--spacing-24);
-  box-shadow: var(--shadow-card);
-}
-.custom-card:hover {
-  box-shadow: var(--shadow-modal-sm);
-}
-```
----
-## Component Reuse Rule (CRITICAL)
-**Reuse existing SortUI components** instead of inlining custom markup. This keeps styling consistent across themes.
-```tsx
-// ✅ DO — reuse components
-<Badge color="green" shape="pill">Active</Badge>
-<Avatar src="/u.jpg" fallback="MS" size="md" />
-<ProgressBar value={75} label labelText="Upload" />
-<Button variant="default" size="md">Save</Button>
-// ❌ DON'T — inline markup
-<span className="inline-flex bg-green-100 text-green-800 px-sui-8 py-sui-4 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 rounded-full overflow-hidden">
-  <div style={{ width: "75%" }} className="h-full bg-sui-state-primary" />
-</div>
-```
----
-## DO / DON'T
-**DO:**
-```tsx
-<div className="gap-sui-16 p-sui-24" />
-<div className="bg-sui-bg-default text-sui-text-default" />
-<div className="p-sui-16 md:p-sui-24 lg:p-sui-32" />
-<div className="flex flex-col gap-sui-16" />
-<div className="rounded-md shadow-card" />
-<Button className="w-full md:w-auto">Submit</Button>
-```
-**DON'T:**
-```tsx
-<div className="gap-[16px] p-[24px]" />                    {/* ❌ arbitrary */}
-<div className="bg-[#ffffff] text-[#111115]" />            {/* ❌ hex */}
-<div className="lg:p-sui-32 md:p-sui-24 p-sui-16" />       {/* ❌ desktop-first */}
-<Button style={{ padding: "20px" }}>Submit</Button>         {/* ❌ inline style */}
-<div className="rounded-sui-md shadow-sui-default" />       {/* ❌ wrong prefix */}
-<div className="rounded-md shadow-md shadow-lg" />          {/* ❌ generic shadow */}
-```
----
-## Layout Examples
-### Dashboard Layout
-```tsx
-<div className="min-h-screen bg-sui-bg-subtle">
-  <header className="bg-sui-bg-default border-b border-sui-border-default px-sui-24 py-sui-16">
-    <div className="max-w-7xl mx-auto flex items-center justify-between">
-      <h1 className="text-sui-text-default font-semibold">Dashboard</h1>
-      <nav className="flex gap-sui-12">
-        <Button variant="ghost">Settings</Button>
-      </nav>
-    </div>
-  </header>
-  <main className="max-w-7xl mx-auto px-sui-24 py-sui-32">
-    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-sui-24">
-      <Card>…</Card>
-      <Card>…</Card>
-      <Card>…</Card>
-    </div>
-  </main>
-</div>
-```
-### Form Layout
-```tsx
-<div className="max-w-md mx-auto p-sui-24">
-  <form className="flex flex-col gap-sui-16">
-    <h2 className="text-2xl font-semibold text-sui-text-default mb-sui-8">Sign Up</h2>
-    <InputField label="Name" required />
-    <InputField label="Email" type="email" required />
-    <InputField label="Password" type="password" required />
-    <CheckboxWithText label="I agree to the terms" />
-    <Button type="submit" className="mt-sui-16">Create Account</Button>
-  </form>
-</div>
-```
-### Article Layout
-```tsx
-<div className="max-w-4xl mx-auto px-sui-24 py-sui-64">
-  <article className="space-y-sui-32">
-    <header className="space-y-sui-16">
-      <h1 className="text-4xl font-bold text-sui-text-default">Article Title</h1>
-      <p className="text-sui-text-muted">Published on Jan 1, 2026</p>
-    </header>
-    <div className="prose">
-      <p className="text-sui-text-default">Article content…</p>
-    </div>
-    <footer className="border-t border-sui-border-default pt-sui-24">
-      <div className="flex items-center gap-sui-12">
-        <Avatar src="/author.jpg" fallback="JD" size="md" />
-        <div>
-          <p className="font-semibold text-sui-text-default">John Doe</p>
-          <p className="text-sm text-sui-text-subtle">Author</p>
-        </div>
-      </div>
-    </footer>
-  </article>
-</div>
-```
----
-## Summary
-- **Tailwind v3**, mobile-first, semantic tokens
-- **Spacing with `sui-` prefix**: `gap-sui-16`, `p-sui-24`, `m-sui-8`
-- **Radius & Shadow WITHOUT `sui-` prefix**: `rounded-md`, `shadow-card`
-- **Use Flexbox and Grid utilities** for layout
-- **Reuse SortUI components** (Badge, Avatar, Button, ProgressBar, etc.) instead of inlining markup
-- **Responsive breakpoints**: `sm`, `md`, `lg`, `xl`, `2xl`
-- **Semantic color tokens** over hard-coded hex/rgb
-- **Common spacing**: 16px between form fields, 24px card padding, 32px section gaps