105 lines
6.3 KiB
Markdown
105 lines
6.3 KiB
Markdown
# @collabry/components
|
|
|
|
React 19 + Tailwind CSS component library for the Collabry UI, built on [shadcn/ui](https://ui.shadcn.com) (Radix UI, cmdk, Sonner), with a Storybook catalogue.
|
|
|
|
```sh
|
|
npm install
|
|
npm run storybook # http://localhost:6006
|
|
npm run build # library → dist/ (ESM, types, collabry.css)
|
|
npm run build-storybook # static Storybook → storybook-static/
|
|
npm run typecheck
|
|
```
|
|
|
|
## Use in an app
|
|
|
|
```tsx
|
|
import { ThemeProvider, Button, Toaster } from '@collabry/components';
|
|
import '@collabry/components/styles.css';
|
|
import '@fontsource/lato/400.css';
|
|
import '@fontsource/lato/700.css';
|
|
import '@fontsource/lato/900.css';
|
|
|
|
<ThemeProvider theme="dark" accent="#6A5FCB" tint="off" className="min-h-screen bg-app">
|
|
<Button variant="primary">Neue Aufgabe</Button>
|
|
<Toaster /> {/* once, if you use toast() */}
|
|
</ThemeProvider>;
|
|
```
|
|
|
|
`react` and `react-dom` (19) are peer dependencies; `radix-ui`, `cmdk`, `sonner`, `class-variance-authority`, `lucide-react`, `clsx` and `tailwind-merge` come with the package.
|
|
|
|
Dialogs, menus and popovers portal into the nearest `ThemeProvider` element, so they keep its theme, accent and tint.
|
|
|
|
## Composition
|
|
|
|
Components are small parts you assemble, like shadcn/ui. They don't take data objects or config props; each part renders one element, takes `className` and `ref`, and has a `data-slot` (`card-title`, `nav-item`, …) to target it from outside. Parts that are often links or headings accept `asChild`. The design (spacing, colors, states) lives in the parts; structure and data live in your code.
|
|
|
|
```tsx
|
|
<CardFrame>
|
|
<Card asChild>
|
|
<section aria-labelledby="h-tasks">
|
|
<CardHeader>
|
|
<CardTitle id="h-tasks">
|
|
Meine Aufgaben <CountBadge>6</CountBadge>
|
|
</CardTitle>
|
|
<CardAction>…</CardAction>
|
|
</CardHeader>
|
|
<TaskTable aria-label="Meine Aufgaben">
|
|
<TaskRow done={task.status === 'done'}>
|
|
<TaskCell>
|
|
<TaskCheckbox checked={…} onCheckedChange={…} aria-label="…" />
|
|
</TaskCell>
|
|
<TaskCell>
|
|
<TaskTitle>{task.title}</TaskTitle>
|
|
<TaskMeta>…</TaskMeta>
|
|
</TaskCell>
|
|
…
|
|
</TaskRow>
|
|
</TaskTable>
|
|
</section>
|
|
</Card>
|
|
</CardFrame>
|
|
```
|
|
|
|
Conventions:
|
|
|
|
- State flows down through context where it's shared: `Field` wires label, control and messages (`id`, `aria-describedby`, `aria-invalid`); `Sidebar` tells its parts whether it's collapsed; `TaskTable` sets the column grid of its rows.
|
|
- Overlays use the Radix pattern: `Dialog` + `DialogTrigger` + `DialogContent`, `Menu` + `MenuTrigger` + `MenuContent`, `Popover` + `PopoverTrigger` + `PopoverContent`. Controlled (`open` / `onOpenChange`) or not.
|
|
- Text the user sees is German by default (labels like "Schließen"); pass your own children or `aria-label` to change it.
|
|
- The stories are the reference compositions; `src/stories/examples.tsx` holds the bigger ones (notification panel, account menu).
|
|
|
|
## Structure
|
|
|
|
- `src/styles/tokens.css`: design tokens (`--cl-*`) for dark and light, with accent and tint derived via `color-mix`
|
|
- `src/styles/index.css`: Tailwind v4 theme mapping tokens to utilities (`bg-surface`, `text-fg-muted`, `border-line`, …) and to shadcn's token names
|
|
- `src/components/ui/`: shadcn/ui primitives (`components.json`), restyled to the Collabry tokens
|
|
- `src/components/<Name>/<Name>.tsx` + `<Name>.stories.tsx`: Collabry parts built from `ui/`
|
|
|
|
## Components
|
|
|
|
| Area | Parts |
|
|
| --- | --- |
|
|
| Foundations | `ThemeProvider`, `Button`, `CardFrame`, `Card`, `CardHeader`, `CardHeading`, `CardTitle`, `CardDescription`, `CardAction`, `CardFooter`, `PageHeader`, `PageHeading`, `PageEyebrow`, `PageTitle`, `PageDescription`, `PageActions`, `Empty*`, `SectionLabel`, `MetaSeparator`, `Spinner`, `Logo` |
|
|
| Forms | `Field`, `FieldHeader`, `FieldLabel`, `FieldNote`, `FieldDescription`, `FieldError`, `Input`, `InputGroup`, `InputGroupAddon`, `InputGroupButton`, `PasswordInput`, `Textarea`, `Select`, `SelectOption`, `Checkbox`, `TaskCheckbox`, `SegmentedControl`, `SegmentedControlItem`, `SegmentedControlCount` |
|
|
| Display | `StatusBadge`, `CountBadge`, `RoleBadge`, `Swatch`, `Kbd`, `KbdGroup`, `IndicatorDot`, `Avatar`, `AvatarImage`, `AvatarFallback`, `PersonAvatar`, `AvatarGroup`, `ProgressBar`, `StatusProgress`, `StatusBar`, `StatusLegend` |
|
|
| Overlays | `Dialog*`, `AlertDialog*`, `Drawer*`, `Menu*`, `Popover*`, `Command*`, `SearchTrigger`, `Toast`, `ToastAction`, `ToastClose`, `Toaster`, `toast()`, `Notification*` |
|
|
| Navigation | `Sidebar`, `SidebarHeader`, `SidebarLogo`, `SidebarActions`, `SidebarButton`, `SidebarToggle`, `SidebarNav`, `NavItem`, `NavItemLabel`, `SidebarFooter`, `SidebarUserButton`, `SidebarUserName`, `MobileHeader*`, `MobileTabBar`, `MobileTab` |
|
|
| Tasks | `TaskTable`, `TaskTableHeader`, `TaskTableHead`, `TaskRow`, `TaskCell`, `TaskOpenButton`, `TaskTitle`, `TaskMeta`, `TaskCommentCount`, `TaskAssignee`, `TaskDue`, `TaskTableEmpty`, `TaskSection*`, `PriorityLabel`, `Deadline*`, `DateTile`, `Comment*` |
|
|
| Groups | `GroupRow*`, `GroupCard*`, `NewGroupTile*`, `InviteBanner*` |
|
|
| Calendar | `CalendarGrid`, `CalendarWeekday`, `CalendarDay*`, `CalendarChip`, `CalendarMarker`, `CalendarLegend*`, `CalendarToolbar`, `CalendarNav`, `CalendarRangeLabel`, `FilterChip`, `FilterChipSwatch`, `DayEvent*` |
|
|
| Settings | `SettingsNav*`, `SettingsSection*`, `SettingsRow*`, `ThemePicker`, `ThemeOption`, `ThemePreview`, `ThemeOptionLabel`, `ColorSchemePicker`, `ColorSchemeOption`, `SaveStatus` |
|
|
| Auth | `AuthBrandPanel`, `AuthBrandContent`, `AuthHeadline`, `Feature*`, `PasswordRules`, `PasswordRule`, `passwordRules()` |
|
|
|
|
## Adding shadcn/ui components
|
|
|
|
```sh
|
|
npx shadcn@latest add <component>
|
|
npm uninstall cn
|
|
```
|
|
|
|
Then, in the new `src/components/ui/<component>.tsx`:
|
|
|
|
- change `import { cn } from "cn"` to `import { cn } from "@/lib/cn"` (the registry now imports shadcn's `cn` package; ours knows the custom text and shadow scales)
|
|
- pass `container={usePortalContainer()}` (from `@/lib/portal`) to every `*.Portal`
|
|
- shadcn token names (`bg-popover`, `text-muted-foreground`, `border-border`, …) map to Collabry colors, except `accent`, which is the brand color here: replace `focus:bg-accent` / `hover:bg-accent` with `bg-hover-menu`
|
|
- the `animate-in` / `fade-in-0` / `zoom-in-95` classes need `tw-animate-css`, which is not installed; use `data-[state=open]:animate-panel-in` instead
|