Files
collabry-components/README.md
T
2026-11-14 08:49:19 +01:00

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