opsfuse-ui 0.1.23 → 0.1.25

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.
@@ -1,168 +1,169 @@
1
- ---
2
- name: opsfuse-setup
3
- description: >
4
- Integrate opsfuse-ui into a React + Tailwind v4 app: install, CSS, fonts, brand theme,
5
- OpsfuseThemeProvider, and migration. Use when starting integration or migrating an existing app.
6
- ---
7
-
8
- # OpsFuse UI — Integration Guide
9
-
10
- Follow phases in order. For tokens use `/color-theme`; for component APIs use `/components`; for code patterns use `/ui-consistency`.
11
-
12
- ## 0 — Discovery
13
-
14
- Before changing anything:
15
-
16
- 1. Framework (Next App/Pages, Vite, Remix, etc.) and package manager (lockfile).
17
- 2. Existing UI (shadcn, MUI, Chakra, etc.) and which components are used.
18
- 3. Global CSS entry and app root (`layout.tsx`, `main.tsx`, etc.).
19
-
20
- ## 1 — Install
21
-
22
- ```bash
23
- npm install opsfuse-ui
24
- ```
25
-
26
- Peers: `react`, `react-dom` (same major). If `tsconfig.json` exists, prefer `"moduleResolution": "bundler"` (or `node16` / `nodenext`) so `exports` resolve.
27
-
28
- ## 2 — CSS & fonts
29
-
30
- **Tailwind v4 required.** One import in the host global stylesheet (not from JS):
31
-
32
- ```css
33
- @import "tailwindcss";
34
- @import "opsfuse-ui/styles.css";
35
- /* your @theme / @source below this */
36
- ```
37
-
38
- ```ts
39
- import "./globals.css"; // layout / main — not opsfuse-ui/styles.css here
40
- ```
41
-
42
- **Do**
43
-
44
- - Import opsfuse **after** `tailwindcss`; put your `@theme` overrides **below** opsfuse.
45
- - Scan **your** app source only — do **not** `@source` `node_modules/opsfuse-ui/dist/**/*.js` (breaks sidebar/tabs active states).
46
-
47
- **Don't**
48
-
49
- - Import `theme.css` separately or add `layer(opsfuse)` (obsolete).
50
-
51
- **Fonts** — map host fonts to `--font-sans` / `--font-mono` (Next: `next/font` with `variable`; Vite: `:root` or existing font stack).
52
-
53
- ### Troubleshooting
54
-
55
- | Symptom | Fix |
56
- |--------|-----|
57
- | All sidebar items look active / tabs never highlight | Remove host `@source` on opsfuse dist; use only the two imports above. |
58
- | Tabs stay rounded in `line` variant | Tailwind v4 + package ≥ 0.1.10; confirm `data-[variant=line]:rounded-none` in built CSS. |
59
- | Alert dialog header stays centered on `sm+` | Rebuild/reinstall; bundle should ship unlayered `alert-dialog-*` `text-align: left` at `sm`. |
60
-
61
- ## 3 — Brand theme
62
-
63
- Ask the user to pick one:
64
-
65
- | Brand | `theme` prop |
66
- |-------|----------------|
67
- | RecruitSmartly (default) | `"recruitsmartly"` |
68
- | SkillReady | `"skillready"` |
69
- | Verity | `"verity"` |
70
- | WorkLog | `"worklog"` |
71
-
72
- ## 4 — Provider
73
-
74
- Wrap the **entire app** once with `OpsfuseThemeProvider` (brand class, dark sync, portals, imperative APIs, tooltips, toaster). Do **not** nest `ConfirmationDialogProvider`, `TooltipProvider`, `AlertProvider`, `DialogProvider`, `SheetProvider`, `SliderDialogProvider`, or `Toaster` again in the entry file.
75
-
76
- ```tsx
77
- import { OpsfuseThemeProvider } from "opsfuse-ui";
78
-
79
- <OpsfuseThemeProvider theme="skillready" className="min-h-svh">
80
- {children}
81
- </OpsfuseThemeProvider>
82
- ```
83
-
84
- **Imperative APIs** (all provided by the theme provider):
85
-
86
- | API | Use |
87
- |-----|-----|
88
- | `toast.*` from `sonner` | Notifications |
89
- | `showAlert({ … })` | Alert dialog |
90
- | `openDialog` / `openSheet` / `openSlider` | Overlays |
91
- | `confirm({ … })` | Destructive confirm |
92
- | `<Tooltip>` | Tooltips |
93
-
94
- ## 5 — Component migration
95
-
96
- Work file by file: read context, replace UI only, keep logic. Remove dead imports from the old library.
97
-
98
- Use `/components` for the full replacement map, variants, and composition. Quick mappings:
99
-
100
- | Was | Use |
101
- |-----|-----|
102
- | Button | `<Button variant="…">` |
103
- | Text field | `<Input label="…" />` or `<Field>` |
104
- | Select | `<Select>` compound |
105
- | Modal | `<Dialog>` or `openDialog` |
106
- | Drawer | `<Sheet>` / `<Drawer>` |
107
- | Confirm | `confirm()` not `window.confirm()` |
108
- | Toast | `toast()` from `sonner` |
109
-
110
- **Rules:** preserve handlers/state; icon-only buttons need `aria-label`; destructive flows use `confirm()` + `variant="destructive"` where appropriate.
111
-
112
- **Bundle size:** prefer `opsfuse-ui/core` for light apps; `opsfuse-ui/extended` only where needed (charts, calendar, etc.).
113
-
114
- ## 6 — Tokens & dark mode
115
-
116
- Replace hardcoded colors and `gray-*` / palette utilities with opsfuse tokens — see `/color-theme`.
117
-
118
- Dark mode: add `dark` on `<html>`; tokens switch automatically. Use `dark:` with token classes, not hardcoded hex overrides.
119
-
120
- ## 7 — Verify
121
-
122
- - [ ] `@import "opsfuse-ui/styles.css"` after `tailwindcss` in global CSS only
123
- - [ ] No `@source` on opsfuse `dist/`
124
- - [ ] `--font-sans` set; fonts render
125
- - [ ] Single `OpsfuseThemeProvider` with chosen `theme`
126
- - [ ] Tooltips / toasts / `confirm()` work if used
127
- - [ ] Migrated files use tokens, not `text-gray-*` / hex
128
- - [ ] `tsc --noEmit` clean
129
- - [ ] Light + dark checked if the app supports dark mode
130
-
131
- ## Minimal Next.js snippet
132
-
133
- ```css
134
- /* app/globals.css */
135
- @import "tailwindcss";
136
- @import "opsfuse-ui/styles.css";
137
- ```
138
-
139
- ```tsx
140
- // app/layout.tsx
141
- import "./globals.css";
142
- import { OpsfuseThemeProvider } from "opsfuse-ui";
143
-
144
- export default function RootLayout({ children }: { children: React.ReactNode }) {
145
- return (
146
- <html lang="en">
147
- <body>
148
- <OpsfuseThemeProvider theme="recruitsmartly" className="min-h-svh">
149
- {children}
150
- </OpsfuseThemeProvider>
151
- </body>
152
- </html>
153
- );
154
- }
155
- ```
156
-
157
- Vite/CRA: same CSS imports; wrap `<App />` in `main.tsx`.
158
-
159
- ## Do / Don't
160
-
161
- | Do | Don't |
162
- |----|-------|
163
- | One global CSS import after Tailwind | Import styles from JS or `@source` opsfuse dist |
164
- | One root `OpsfuseThemeProvider` | Per-component theme wrappers or duplicate providers |
165
- | `cn()` from `opsfuse-ui` | Concatenate class strings |
166
- | Tokens + `/color-theme` | `text-gray-600`, arbitrary hex |
167
- | Icons from `opsfuse-ui/icons` | `lucide-react` in consuming apps |
168
- | `confirm()` for destructive actions | `window.confirm()` |
1
+ ---
2
+ name: opsfuse-setup
3
+ description: >
4
+ Integrate opsfuse-ui into a React + Tailwind v4 app: install, CSS, fonts, brand theme,
5
+ OpsfuseThemeProvider, and migration. Use when starting integration or migrating an existing app.
6
+ ---
7
+
8
+ # OpsFuse UI — Integration Guide
9
+
10
+ Follow phases in order. For tokens use `/color-theme`; for component APIs use `/components`; for code patterns use `/ui-consistency`.
11
+
12
+ ## 0 — Discovery
13
+
14
+ Before changing anything:
15
+
16
+ 1. Framework (Next App/Pages, Vite, Remix, etc.) and package manager (lockfile).
17
+ 2. Existing UI (shadcn, MUI, Chakra, etc.) and which components are used.
18
+ 3. Global CSS entry and app root (`layout.tsx`, `main.tsx`, etc.).
19
+
20
+ ## 1 — Install
21
+
22
+ ```bash
23
+ npm install opsfuse-ui
24
+ ```
25
+
26
+ Peers: `react`, `react-dom` (same major). If `tsconfig.json` exists, prefer `"moduleResolution": "bundler"` (or `node16` / `nodenext`) so `exports` resolve.
27
+
28
+ ## 2 — CSS & fonts
29
+
30
+ **Tailwind v4 required.** One import in the host global stylesheet (not from JS):
31
+
32
+ ```css
33
+ @import "tailwindcss";
34
+ @import "opsfuse-ui/styles.css";
35
+ /* your @theme / @source below this */
36
+ ```
37
+
38
+ ```ts
39
+ import "./globals.css"; // layout / main — not opsfuse-ui/styles.css here
40
+ ```
41
+
42
+ **Do**
43
+
44
+ - Import opsfuse **after** `tailwindcss`; put your `@theme` overrides **below** opsfuse.
45
+ - Scan **your** app source only — do **not** `@source` `node_modules/opsfuse-ui/dist/**/*.js` (breaks sidebar/tabs active states).
46
+
47
+ **Don't**
48
+
49
+ - Import `theme.css` separately or add `layer(opsfuse)` (obsolete).
50
+
51
+ **Fonts** — map host fonts to `--font-sans` / `--font-mono` (Next: `next/font` with `variable`; Vite: `:root` or existing font stack).
52
+
53
+ ### Troubleshooting
54
+
55
+ | Symptom | Fix |
56
+ |--------|-----|
57
+ | All sidebar items look active / tabs never highlight | Remove host `@source` on opsfuse dist; use only the two imports above. |
58
+ | Tabs stay rounded in `line` variant | Tailwind v4 + package ≥ 0.1.10; confirm `data-[variant=line]:rounded-none` in built CSS. |
59
+ | Alert dialog header stays centered on `sm+` | Rebuild/reinstall; bundle should ship unlayered `alert-dialog-*` `text-align: left` at `sm`. |
60
+
61
+ ## 3 — Brand theme
62
+
63
+ Ask the user to pick one:
64
+
65
+ | Brand | `theme` prop |
66
+ |-------|----------------|
67
+ | RecruitSmartly (default) | `"recruitsmartly"` |
68
+ | SkillReady | `"skillready"` |
69
+ | Verity | `"verity"` |
70
+ | WorkLog | `"worklog"` |
71
+ | LMS (Leave Management) | `"lms"` |
72
+
73
+ ## 4 — Provider
74
+
75
+ Wrap the **entire app** once with `OpsfuseThemeProvider` (brand class, dark sync, portals, imperative APIs, tooltips, toaster). Do **not** nest `ConfirmationDialogProvider`, `TooltipProvider`, `AlertProvider`, `DialogProvider`, `SheetProvider`, `SliderDialogProvider`, or `Toaster` again in the entry file.
76
+
77
+ ```tsx
78
+ import { OpsfuseThemeProvider } from "opsfuse-ui";
79
+
80
+ <OpsfuseThemeProvider theme="skillready" className="min-h-svh">
81
+ {children}
82
+ </OpsfuseThemeProvider>
83
+ ```
84
+
85
+ **Imperative APIs** (all provided by the theme provider):
86
+
87
+ | API | Use |
88
+ |-----|-----|
89
+ | `toast.*` from `sonner` | Notifications |
90
+ | `showAlert({ … })` | Alert dialog |
91
+ | `openDialog` / `openSheet` / `openSlider` | Overlays |
92
+ | `confirm({ … })` | Destructive confirm |
93
+ | `<Tooltip>` | Tooltips |
94
+
95
+ ## 5 — Component migration
96
+
97
+ Work file by file: read context, replace UI only, keep logic. Remove dead imports from the old library.
98
+
99
+ Use `/components` for the full replacement map, variants, and composition. Quick mappings:
100
+
101
+ | Was | Use |
102
+ |-----|-----|
103
+ | Button | `<Button variant="…">` |
104
+ | Text field | `<Input label="…" />` or `<Field>` |
105
+ | Select | `<Select>` compound |
106
+ | Modal | `<Dialog>` or `openDialog` |
107
+ | Drawer | `<Sheet>` / `<Drawer>` |
108
+ | Confirm | `confirm()` not `window.confirm()` |
109
+ | Toast | `toast()` from `sonner` |
110
+
111
+ **Rules:** preserve handlers/state; icon-only buttons need `aria-label`; destructive flows use `confirm()` + `variant="destructive"` where appropriate.
112
+
113
+ **Bundle size:** prefer `opsfuse-ui/core` for light apps; `opsfuse-ui/extended` only where needed (charts, calendar, etc.).
114
+
115
+ ## 6 — Tokens & dark mode
116
+
117
+ Replace hardcoded colors and `gray-*` / palette utilities with opsfuse tokens — see `/color-theme`.
118
+
119
+ Dark mode: add `dark` on `<html>`; tokens switch automatically. Use `dark:` with token classes, not hardcoded hex overrides.
120
+
121
+ ## 7 — Verify
122
+
123
+ - [ ] `@import "opsfuse-ui/styles.css"` after `tailwindcss` in global CSS only
124
+ - [ ] No `@source` on opsfuse `dist/`
125
+ - [ ] `--font-sans` set; fonts render
126
+ - [ ] Single `OpsfuseThemeProvider` with chosen `theme`
127
+ - [ ] Tooltips / toasts / `confirm()` work if used
128
+ - [ ] Migrated files use tokens, not `text-gray-*` / hex
129
+ - [ ] `tsc --noEmit` clean
130
+ - [ ] Light + dark checked if the app supports dark mode
131
+
132
+ ## Minimal Next.js snippet
133
+
134
+ ```css
135
+ /* app/globals.css */
136
+ @import "tailwindcss";
137
+ @import "opsfuse-ui/styles.css";
138
+ ```
139
+
140
+ ```tsx
141
+ // app/layout.tsx
142
+ import "./globals.css";
143
+ import { OpsfuseThemeProvider } from "opsfuse-ui";
144
+
145
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
146
+ return (
147
+ <html lang="en">
148
+ <body>
149
+ <OpsfuseThemeProvider theme="recruitsmartly" className="min-h-svh">
150
+ {children}
151
+ </OpsfuseThemeProvider>
152
+ </body>
153
+ </html>
154
+ );
155
+ }
156
+ ```
157
+
158
+ Vite/CRA: same CSS imports; wrap `<App />` in `main.tsx`.
159
+
160
+ ## Do / Don't
161
+
162
+ | Do | Don't |
163
+ |----|-------|
164
+ | One global CSS import after Tailwind | Import styles from JS or `@source` opsfuse dist |
165
+ | One root `OpsfuseThemeProvider` | Per-component theme wrappers or duplicate providers |
166
+ | `cn()` from `opsfuse-ui` | Concatenate class strings |
167
+ | Tokens + `/color-theme` | `text-gray-600`, arbitrary hex |
168
+ | Icons from `opsfuse-ui/icons` | `lucide-react` in consuming apps |
169
+ | `confirm()` for destructive actions | `window.confirm()` |