@aurora-ds/components 0.25.1 → 1.1.0

package/README.md

@@ -4,13 +4,9 @@
 >
 > This library is designed for my personal projects and is not intended for public use. Feel free to use it as inspiration or reference, but no support or maintenance is guaranteed.
 
-A React component library with **default theme included**. Ready to use in 3 lines of code.
+A React component library built on top of [`@aurora-ds/theme`](https://www.npmjs.com/package/@aurora-ds/theme) v4, shipping ready-to-use light and dark themes.
 
-**Key Features:**
-- ✅ **Default theme included** - No configuration needed
-- ✅ **TypeScript autocomplete** - Full IntelliSense support
-- ✅ **Easy to customize** - Spread operator to override
-- ✅ **Built with `@aurora-ds/theme` v3** - Powerful theming system
+> 🚧 **Reset in progress** — The component catalog has been wiped and is being rebuilt from scratch. Currently only the themes are exported. Components will be added back progressively.
 
 ## Installation
 
@@ -22,215 +18,56 @@ yarn add @aurora-ds/components @aurora-ds/theme react react-dom
 
 ```tsx
 import { ThemeProvider } from '@aurora-ds/theme'
-import { defaultTheme, Button } from '@aurora-ds/components'
+import { lightTheme } from '@aurora-ds/components'
 
 function App() {
   return (
-    <ThemeProvider theme={defaultTheme}>
-      <Button label="Click me" variant="contained" />
+    <ThemeProvider theme={lightTheme}>
+      {/* your app */}
     </ThemeProvider>
   )
 }
 ```
 
-That's it! 🎉
-
-## 🎨 Customization
-
-### Use Case 1: Change Token Values
-
-You have two options to customize the theme:
-
-#### Option A: Using spread operator (simple)
-
-```tsx
-import { defaultTheme } from '@aurora-ds/components'
-import { colors } from '@aurora-ds/theme'
-
-const myTheme = {
-  ...defaultTheme,
-  colors: {
-    ...defaultTheme.colors,
-    primary: colors.purple[600],     // Change primary color
-    success: colors.teal[600],       // Change success color
-  },
-  spacing: {
-    ...defaultTheme.spacing,
-    lg: '2rem',                       // Change large spacing
-  },
-  radius: {
-    ...defaultTheme.radius,
-    md: '1rem',                       // Change medium radius
-  }
-}
-
-<ThemeProvider theme={myTheme}>
-  <App />
-</ThemeProvider>
-```
-
-#### Option B: Using `createTheme` (type-safe)
+A `darkTheme` is also exported and ready to use:
 
 ```tsx
-import { createTheme, colors } from '@aurora-ds/theme'
-import { defaultTheme } from '@aurora-ds/components'
-
-const myTheme = createTheme({
-  ...defaultTheme,
-  colors: {
-    ...defaultTheme.colors,
-    primary: colors.purple[600],
-    success: colors.teal[600],
-  }
-})
-
-<ThemeProvider theme={myTheme}>
-  <App />
-</ThemeProvider>
+import { darkTheme } from '@aurora-ds/components'
 ```
 
-Both approaches work! `createTheme` provides additional type validation.
-
-### Use Case 2: Add Custom Tokens
-
-If you need tokens that don't exist in `defaultTheme` (for very specific use cases):
-
-**Step 1: Create your theme types**
-```typescript
-// src/theme/theme.types.ts
-import type { Theme as BaseTheme } from '@aurora-ds/components'
-
-export interface Theme extends BaseTheme {
-  colors: BaseTheme['colors'] & {
-    brand: string           // New custom token
-    custom: string          // New custom token
-  }
-  customSpacing: {          // Entirely new category
-    hero: string
-    section: string
-  }
-}
-```
+## 🎨 Custom Theme
 
-**Step 2: Create module augmentation**
-```typescript
-// src/theme/theme.module.ts
-import type { Theme } from './theme.types'
+You can build your own theme by reusing the exported palettes/values or by composing a brand new one with `createTheme` from `@aurora-ds/theme`. See `src/theme/themes/lightTheme.ts` for a reference.
 
-declare module '@aurora-ds/theme' {
-  interface ThemeRegistry {
-    theme: Theme
-  }
-}
-```
-
-**Step 3: Create your theme with `createTheme`**
-```typescript
-// src/theme/theme.ts
-import './theme.module'
-import { createTheme, colors } from '@aurora-ds/theme'
-import { defaultTheme } from '@aurora-ds/components'
+```tsx
+import { createTheme } from '@aurora-ds/theme'
+import { lightTheme, type Theme } from '@aurora-ds/components'
 
-export const myTheme = createTheme({
-  ...defaultTheme,
+const myTheme: Theme = createTheme({
+  ...lightTheme,
   colors: {
-    ...defaultTheme.colors,
-    brand: colors.purple[600],      // Your custom token
-    custom: colors.pink[500],       // Your custom token
+    ...lightTheme.colors,
+    primaryMain: '#ff5722',
   },
-  customSpacing: {                  // Your custom category
-    hero: '10rem',
-    section: '5rem',
-  }
-} as Theme)
-```
-
-**Step 4: Use it**
-```typescript
-// src/App.tsx
-import { myTheme } from './theme/theme'
-
-<ThemeProvider theme={myTheme}>
-  <App />
-</ThemeProvider>
-```
-
-Now you get autocomplete on your custom tokens! ✅
-
-> **Note:** Most projects won't need this. The default theme already includes common tokens like `highlight`, `accent`, and `link`.
-
-### Use Case 3: Multiple Themes (Light/Dark)
-
-Create multiple theme variants:
-
-```typescript
-import { createTheme, colors } from '@aurora-ds/theme'
-import { defaultTheme } from '@aurora-ds/components'
-
-// Light theme (use default)
-export const lightTheme = defaultTheme
-
-// Dark theme with createTheme
-export const darkTheme = createTheme({
-  ...defaultTheme,
-  colors: {
-    ...defaultTheme.colors,
-    background: colors.slate[950],
-    surface: colors.slate[900],
-    text: colors.slate[50],
-    primary: colors.indigo[400],
-    secondary: colors.slate[800],
-    border: colors.slate[800],
-    // ... other dark mode colors
-  }
 })
-
-// In your app
-const [isDark, setIsDark] = useState(false)
-
-<ThemeProvider theme={isDark ? darkTheme : lightTheme}>
-  <App />
-</ThemeProvider>
 ```
 
 ## 📦 Available Tokens
 
-The `defaultTheme` includes these token categories:
+The themes include the following token categories:
 
-- **colors**: `primary`, `secondary`, `error`, `success`, `warning`, `info`, `highlight`, `accent`, `link`, `text`, `background`, etc.
-- **spacing**: `none`, `2xs` (2px), `xs` (4px), `sm` (8px), `md` (16px), `lg` (24px), `xl` (32px), etc.
-- **radius**: `none`, `xs` (2px), `sm` (4px), `md` (6px), `lg` (8px), `xl` (12px), `2xl` (16px), `full`
-- **fontSize**: `2xs` (10px), `xs` (12px), `sm` (14px), `md` (16px), `lg` (20px), `xl` (24px), etc.
-- **fontWeight**: `light` (300), `regular` (400), `medium` (500), `semibold` (600), `bold` (700)
-- **shadows**, **transition**, **breakpoints**, **zIndex**, etc.
+- **colors** — full palette (surface, text, primary, secondary, success, warning, error, info, border, link, skeleton, …)
+- **spacing**, **radius**, **shadows**
+- **fontSize**, **fontWeight**, **lineHeight**
+- **transition**, **opacity**, **zIndex**, **breakpoints**
 
-💡 See all values in `src/theme/values/`
+See the source under `src/theme/` for the exact values.
 
 ## 🧩 Available Components
 
-| Category | Components |
-|----------|-----------|
-| **Actions** | Button, IconButton, ButtonToggle, ButtonToggleGroup |
-| **Layout** | Box, Card, Stack, Grid, Page, PageSection, Separator |
-| **Foundation** | Text, Icon |
-| **Forms** | Input, TextArea, Select, DatePicker, Form, FilePicker, ImagePicker |
-| **Data Display** | Status, Avatar, AvatarGroup, Skeleton |
-| **Navigation** | Breadcrumb, Tabs, DrawerItem, Pagination |
-| **Overlay** | Alert, Accordion, Menu, Modal |
+_None yet — the catalog is being rebuilt._
 
-## ♿ Accessibility
-
-All components are built with accessibility in mind:
-
-- **Button / IconButton** — `aria-label`, `aria-pressed` (toggle), `aria-busy` (loading), `aria-expanded`, `aria-controls`
-- **Input / TextArea / Select** — `aria-required`, `aria-invalid`, `aria-errormessage` (auto-linked error messages), `id` for label associations
-- **Avatar** — `role="button"` + keyboard support (Enter/Space) when `onClick` is provided
-- **Alert** — `role="alert"`, dynamic `aria-live` (`assertive` for errors, `polite` for others), `aria-atomic`
-- **Modal** — `role="dialog"`, `aria-modal`, `aria-labelledby` (linked to title), full focus trap, focus restoration on close
-- **Breadcrumb** — `role="navigation"`, `aria-label="breadcrumb"`
-- **Text** — `id` prop for `aria-labelledby` / `aria-describedby` references
-
-## 📁 Component Self-Contained Structure
+## 📁 Component Self-Contained Structure (target)
 
 Each component folder contains all its utils locally, making copy-paste to another project straightforward:
 
@@ -244,6 +81,14 @@ src/components/<category>/<component>/
 └── index.ts
 ```
 
+## Commands
+
+- `yarn start` — Start Storybook dev server
+- `yarn build` — Build the library
+- `yarn build-storybook` — Build Storybook for deployment
+- `yarn lint` — Run ESLint
+- `yarn test` — Run tests (Vitest)
+
 ## License
 
 MIT