@kjaniec-dev/ui 0.2.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.
- package/README.md +89 -0
- package/dist/index.cjs +976 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +281 -0
- package/dist/index.d.ts +281 -0
- package/dist/index.js +895 -0
- package/dist/index.js.map +1 -0
- package/dist/ui.css +26 -0
- package/package.json +71 -0
package/README.md
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# @kjaniec-dev/ui
|
|
2
|
+
|
|
3
|
+
React + TypeScript component library built on top of the **@kjaniec-dev/design** token system. Every component styles itself through the Tailwind theme mapping in `@kjaniec-dev/design/tailwind.css` — so light/dark mode and any token change flow through automatically with zero per-component overrides.
|
|
4
|
+
|
|
5
|
+
## Install (within the monorepo)
|
|
6
|
+
|
|
7
|
+
This package lives in `packages/ui` and depends on the sibling design package:
|
|
8
|
+
|
|
9
|
+
```jsonc
|
|
10
|
+
// peerDependencies
|
|
11
|
+
"react": ">=18",
|
|
12
|
+
"react-dom": ">=18",
|
|
13
|
+
"@kjaniec-dev/design": "*"
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Runtime deps: `class-variance-authority`, `clsx`, `tailwind-merge`.
|
|
17
|
+
|
|
18
|
+
## Setup
|
|
19
|
+
|
|
20
|
+
In your app's global stylesheet, import the design tokens (Tailwind v4 `@theme`) and the small runtime stylesheet that ships keyframes + the slider thumb:
|
|
21
|
+
|
|
22
|
+
```css
|
|
23
|
+
@import "@kjaniec-dev/design/tailwind.css";
|
|
24
|
+
@import "@kjaniec-dev/ui/ui.css";
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Toggle dark mode by adding the `.dark` class to `<html>` (the design package remaps every `--kj-*` variable under `.dark`).
|
|
28
|
+
|
|
29
|
+
## Usage
|
|
30
|
+
|
|
31
|
+
```tsx
|
|
32
|
+
import { Button, Card, CardHeader, CardTitle, Badge, ToastProvider, useToast } from "@kjaniec-dev/ui";
|
|
33
|
+
|
|
34
|
+
function Example() {
|
|
35
|
+
const { toast } = useToast();
|
|
36
|
+
return (
|
|
37
|
+
<Card>
|
|
38
|
+
<CardHeader>
|
|
39
|
+
<CardTitle>Workspace</CardTitle>
|
|
40
|
+
<Badge variant="success" dot>Active</Badge>
|
|
41
|
+
</CardHeader>
|
|
42
|
+
<Button onClick={() => toast({ message: "Saved!", tone: "success" })}>
|
|
43
|
+
Save
|
|
44
|
+
</Button>
|
|
45
|
+
</Card>
|
|
46
|
+
);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
// Wrap the app once so useToast() works:
|
|
50
|
+
// <ToastProvider><App /></ToastProvider>
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Live demo
|
|
54
|
+
|
|
55
|
+
Two ways to preview:
|
|
56
|
+
|
|
57
|
+
- **Storybook** (recommended for development) — an isolated preview of every component, auto-generated prop docs from the TSX types, controls for clicking through variants, a light/dark toggle in the toolbar and an accessibility (a11y) audit tab on every page:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npm install
|
|
61
|
+
npm run storybook
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
- `demo.html` — a **standalone, runnable gallery** in a single file. Open it in a browser (no build) to see and click through every component in light/dark. It loads the real component source via Babel + the Tailwind token mapping, so it's the same code that ships in `src/`.
|
|
65
|
+
|
|
66
|
+
## Components
|
|
67
|
+
|
|
68
|
+
| Group | Exports |
|
|
69
|
+
|---|---|
|
|
70
|
+
| **Actions** | `Button` |
|
|
71
|
+
| **Status** | `Badge`, `Alert`, `Spinner`, `Progress` |
|
|
72
|
+
| **Forms** | `Input`, `Textarea`, `Select`, `Label`, `Hint`, `Field` |
|
|
73
|
+
| **Selection** | `Checkbox`, `Radio`, `Switch`, `Slider`, `Segmented` |
|
|
74
|
+
| **Layout** | `Card` (+ `CardHeader/Title/Description/Content/Footer`), `Stat`, `Avatar`, `AvatarGroup` |
|
|
75
|
+
| **Navigation** | `Tabs`, `Accordion`, `DropdownMenu`, `Breadcrumb`, `Pagination` |
|
|
76
|
+
| **Data** | `Table` (+ `TableWrap/Header/Body/Row/Head/Cell`) |
|
|
77
|
+
| **Overlays** | `Modal`, `Tooltip`, `ToastProvider` / `useToast` |
|
|
78
|
+
|
|
79
|
+
## Conventions
|
|
80
|
+
|
|
81
|
+
- **Variants via CVA.** Components with visual modes (`Button`, `Badge`, `Avatar`, `Alert`) expose a typed `variant` / `size` / `tone` prop through `class-variance-authority`.
|
|
82
|
+
- **`className` always merges.** Every component runs its classes through `cn()` (`clsx` + `tailwind-merge`), so a caller-supplied `className` reliably wins conflicts.
|
|
83
|
+
- **`forwardRef` everywhere** that wraps a single DOM node.
|
|
84
|
+
- **Controlled where it matters.** `Tabs`, `Accordion`, `Segmented`, `Pagination`, `Modal` accept controlled state; `Tabs`/`Accordion` also support an uncontrolled `defaultValue`.
|
|
85
|
+
- **Tokens, not hex.** Components reference Tailwind classes that map to `--kj-*` variables (`bg-primary`, `rounded-kj-md`, `shadow-kj-sm`), never literal colors — so the kit re-themes for free.
|
|
86
|
+
|
|
87
|
+
## Source of truth
|
|
88
|
+
|
|
89
|
+
The HTML/CSS reference (`KJ Product Kit.html` + `design/components.css` in the design repo) is the visual spec these components mirror. If a component's look should change, update both so the static gallery and the React library stay in sync.
|