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,169 +1,169 @@
1
- ---
2
- name: ui-consistency
3
- description: >
4
- Opsfuse UI code consistency guide. Use when building, editing, or reviewing any UI in this
5
- codebase. Covers mandatory code patterns, provider setup, accessibility, and Storybook conventions.
6
- For design tokens use /color-theme. For component APIs use /components.
7
- ---
8
-
9
- # Opsfuse UI — Code Consistency Guide
10
-
11
- **Stack:** React 19 + TypeScript + Vite + Tailwind CSS v4 + shadcn/ui (radix-nova)
12
- **Path alias:** `@/` → `src/`
13
-
14
- > For token decisions (surfaces, text, color, typography, motion) use `/color-theme`.
15
- > For component APIs, props, and variants use `/components`.
16
-
17
- ---
18
-
19
- ## 1. MANDATORY CODE PATTERNS
20
-
21
- ### Always use cn() for classNames
22
-
23
- ```tsx
24
- import { cn } from "@/lib/utils"
25
- // cn = clsx + tailwind-merge — rightmost class wins on conflict
26
- className={cn("base-classes", conditionalClass && "extra", props.className)}
27
- ```
28
-
29
- ### Always use cva() for multi-variant components
30
-
31
- ```tsx
32
- import { cva, type VariantProps } from "class-variance-authority";
33
-
34
- const variants = cva("base", {
35
- variants: {
36
- variant: { default: "...", outline: "..." },
37
- size: { sm: "...", default: "..." },
38
- },
39
- defaultVariants: { variant: "default", size: "default" },
40
- });
41
- ```
42
-
43
- ### Always add data-slot to every component part
44
-
45
- ```tsx
46
- <button data-slot="button" data-variant={variant} data-size={size} />
47
- <div data-slot="card" /><div data-slot="card-header" /><div data-slot="card-content" />
48
- ```
49
-
50
- ### Use asChild for composition flexibility
51
-
52
- ```tsx
53
- <Button asChild>
54
- <a href="/page">Link styled as Button</a>
55
- </Button>
56
- ```
57
-
58
- ### Icons always from `opsfuse-ui/icons`
59
-
60
- ```tsx
61
- import { ChevronDown, Plus, X } from "opsfuse-ui/icons";
62
-
63
- <ChevronDown />
64
- <Plus />
65
- <X />
66
- // Components auto-size SVGs: [&_svg:not([class*='size-'])]:size-4
67
- ```
68
-
69
- Host apps must **not** install or import `lucide-react` directly — the full icon catalog is re-exported as flat named exports from `opsfuse-ui/icons` (and as the `Lucide` namespace from the main entry, for collision cases). Typing the icon name autocompletes from the entire Lucide library, and color comes from `currentColor` (style with `text-*` Tailwind classes, never hardcoded hex). For typing icon-as-prop slots, use `LucideIcon` from `opsfuse-ui/icons`.
70
-
71
- For names that collide with opsfuse component exports (`Badge`, `Calendar`, `Command`, `Form`, `Sheet`, `Sidebar`, `Table`), alias on import (`import { Calendar as CalendarIcon } from "opsfuse-ui/icons"`) or use `<Lucide.Calendar />` from the main entry.
72
-
73
- ### Dates always from `opsfuse-ui/date-fns`
74
-
75
- ```tsx
76
- import { format, addDays, parseISO } from "opsfuse-ui/date-fns";
77
- ```
78
-
79
- Host apps must **not** install or import `date-fns` directly — the full `date-fns` surface (including locales) is re-exported as flat named exports from `opsfuse-ui/date-fns` (and as the `DateFns` namespace from the main entry, for collision cases: `import { DateFns } from "opsfuse-ui"` → `DateFns.format(...)`). This guarantees a single pinned version across the host and library.
80
-
81
- ---
82
-
83
- ## 2. PROVIDERS SETUP (main.tsx)
84
-
85
- **`OpsfuseThemeProvider`** (and `<OpsfuseRoot />`, which delegates to it) mounts the full provider stack: `ConfirmationDialogProvider`, `TooltipProvider`, `AlertProvider`, `DialogProvider`, `SheetProvider`, `SliderDialogProvider`, and `Toaster` (as a sibling of the sheet/slider subtree under `DialogProvider`). Host `main.tsx` should wrap the app once — do not duplicate those providers or add another `<ConfirmationDialogProvider>` (that duplicates the module-level `confirm` registration).
86
-
87
- ```tsx
88
- <OpsfuseThemeProvider className="min-h-svh">
89
- <App />
90
- </OpsfuseThemeProvider>
91
- ```
92
-
93
- **Never fork or reorder the internal provider tree without checking all imperative API call sites.**
94
-
95
- Imperative APIs and where they are satisfied:
96
- | API | Provided by |
97
- |-----|---------------|
98
- | `toast.success/error/loading()` from "sonner" | `<Toaster />` inside `<OpsfuseThemeProvider />` |
99
- | `showAlert({ title, description, variant })` | `<AlertProvider />` inside theme |
100
- | `openDialog({ title, children })` | `<DialogProvider />` inside theme |
101
- | `openSheet({ title, children, side })` | `<SheetProvider />` inside theme |
102
- | `confirm({ title, description?, confirmText?, cancelText?, hideCancel?, hideConfirm?, onConfirm?, onCancel? })` | `<ConfirmationDialogProvider />` inside theme |
103
- | `openSlider({ title, value, min, max, ... })` | `<SliderDialogProvider />` inside theme |
104
- | `<Tooltip>` anywhere in the tree | `<TooltipProvider />` inside theme |
105
-
106
- ---
107
-
108
- ## 3. DARK MODE
109
-
110
- All tokens have dark values in `brands.css` under `.dark` (default brand) and `.brand-*.dark` selectors; `OpsfuseThemeProvider` toggles `dark` on the scope element by watching the host's dark convention.
111
- When adding custom dark styles: use the `dark:` Tailwind prefix.
112
- Never hardcode hex colors — tokens handle light/dark automatically.
113
-
114
- ---
115
-
116
- ## 4. ACCESSIBILITY RULES
117
-
118
- - All interactive elements must have accessible labels (`aria-label` or visible text)
119
- - Icon-only buttons: always `<Button size="icon" aria-label="Description">`
120
- - Form fields: always pair with `<Label htmlFor="id">` or use the `label` prop on `<Input>`
121
- - Disabled states: use `text-text-disabled` / `text-(--disabled-foreground)` on disabled controls only — never for readable body copy
122
- - All provided semantic tokens meet WCAG 4.5:1 minimum contrast
123
- - Use `confirm()` (requires `<OpsfuseThemeProvider />` / `<OpsfuseRoot />`, which mount the confirmation provider) before any destructive action (delete, reset, overwrite)
124
-
125
- ---
126
-
127
- ## 5. STORYBOOK STORY PATTERN
128
-
129
- When creating stories:
130
-
131
- ```tsx
132
- import type { Meta, StoryObj } from "@storybook/react"
133
- import { ComponentName } from "opsfuse-ui"
134
-
135
- const meta: Meta<typeof ComponentName> = {
136
- title: "UI/ComponentName",
137
- component: ComponentName,
138
- argTypes: { variant: { control: "select", options: [...] } },
139
- args: { /* sensible defaults */ },
140
- }
141
- export default meta
142
- type Story = StoryObj<typeof ComponentName>
143
-
144
- export const Default: Story = { args: {} }
145
- export const AllVariants: Story = { render: () => <div className="flex gap-2">...</div> }
146
- ```
147
-
148
- Write stories for all new components. Test in both light and dark mode. Page-level title strips use `PageHeader` from `src/components/ui/Header.tsx` (see `/components` skill).
149
-
150
- **Alert dialog:** Storybook covers `src/components/ui/alert-dialog.tsx` via `confirm()` only. The preview wraps stories in `<OpsfuseRoot />`, which uses `OpsfuseThemeProvider` (full provider stack including `ConfirmationDialogProvider`) — stories must not add another `<ConfirmationDialogProvider>`. In apps, same rule: one theme root. Radix primitives live in `shadcn-alert-dialog.tsx` for internal use — do not add a separate Storybook file for that layer.
151
-
152
- ---
153
-
154
- ## 6. DO / DON'T
155
-
156
- | ✅ DO | ❌ DON'T |
157
- | --------------------------------------------------- | -------------------------------------------------- |
158
- | Use design tokens for all colors | Use arbitrary hex like `#ff0000` or `bg-red-500` |
159
- | Use `cn()` for all className merging | String-concatenate classNames directly |
160
- | Use `cva()` for multi-variant components | Inline ternary chains for variants |
161
- | Add `data-slot` to every component part | Skip `data-slot` on wrapper/part elements |
162
- | Use `<Field>` compound for form inputs | Lay out label + input with raw divs |
163
- | Import icons from `opsfuse-ui/icons` | Import from `lucide-react` or other icon libraries |
164
- | Import dates from `opsfuse-ui/date-fns` | Install/import `date-fns` directly in host apps |
165
- | Use `.transition-micro/smooth/data` motion classes | Hardcode `transition duration-200` everywhere |
166
- | Use `confirm()` before destructive actions | Skip confirmation on destructive button clicks |
167
- | Use spacing tokens `--space-1` through `--space-10` | Use arbitrary gaps like `gap-[13px]` |
168
- | Write stories for all new components | Add components without Storybook coverage |
169
- | Test in light AND dark mode | Only check light mode |
1
+ ---
2
+ name: ui-consistency
3
+ description: >
4
+ Opsfuse UI code consistency guide. Use when building, editing, or reviewing any UI in this
5
+ codebase. Covers mandatory code patterns, provider setup, accessibility, and Storybook conventions.
6
+ For design tokens use /color-theme. For component APIs use /components.
7
+ ---
8
+
9
+ # Opsfuse UI — Code Consistency Guide
10
+
11
+ **Stack:** React 19 + TypeScript + Vite + Tailwind CSS v4 + shadcn/ui (radix-nova)
12
+ **Path alias:** `@/` → `src/`
13
+
14
+ > For token decisions (surfaces, text, color, typography, motion) use `/color-theme`.
15
+ > For component APIs, props, and variants use `/components`.
16
+
17
+ ---
18
+
19
+ ## 1. MANDATORY CODE PATTERNS
20
+
21
+ ### Always use cn() for classNames
22
+
23
+ ```tsx
24
+ import { cn } from "@/lib/utils"
25
+ // cn = clsx + tailwind-merge — rightmost class wins on conflict
26
+ className={cn("base-classes", conditionalClass && "extra", props.className)}
27
+ ```
28
+
29
+ ### Always use cva() for multi-variant components
30
+
31
+ ```tsx
32
+ import { cva, type VariantProps } from "class-variance-authority";
33
+
34
+ const variants = cva("base", {
35
+ variants: {
36
+ variant: { default: "...", outline: "..." },
37
+ size: { sm: "...", default: "..." },
38
+ },
39
+ defaultVariants: { variant: "default", size: "default" },
40
+ });
41
+ ```
42
+
43
+ ### Always add data-slot to every component part
44
+
45
+ ```tsx
46
+ <button data-slot="button" data-variant={variant} data-size={size} />
47
+ <div data-slot="card" /><div data-slot="card-header" /><div data-slot="card-content" />
48
+ ```
49
+
50
+ ### Use asChild for composition flexibility
51
+
52
+ ```tsx
53
+ <Button asChild>
54
+ <a href="/page">Link styled as Button</a>
55
+ </Button>
56
+ ```
57
+
58
+ ### Icons always from `opsfuse-ui/icons`
59
+
60
+ ```tsx
61
+ import { ChevronDown, Plus, X } from "opsfuse-ui/icons";
62
+
63
+ <ChevronDown />
64
+ <Plus />
65
+ <X />
66
+ // Components auto-size SVGs: [&_svg:not([class*='size-'])]:size-4
67
+ ```
68
+
69
+ Host apps must **not** install or import `lucide-react` directly — the full icon catalog is re-exported as flat named exports from `opsfuse-ui/icons` (and as the `Lucide` namespace from the main entry, for collision cases). Typing the icon name autocompletes from the entire Lucide library, and color comes from `currentColor` (style with `text-*` Tailwind classes, never hardcoded hex). For typing icon-as-prop slots, use `LucideIcon` from `opsfuse-ui/icons`.
70
+
71
+ For names that collide with opsfuse component exports (`Badge`, `Calendar`, `Command`, `Form`, `Sheet`, `Sidebar`, `Table`), alias on import (`import { Calendar as CalendarIcon } from "opsfuse-ui/icons"`) or use `<Lucide.Calendar />` from the main entry.
72
+
73
+ ### Dates always from `opsfuse-ui/date-fns`
74
+
75
+ ```tsx
76
+ import { format, addDays, parseISO } from "opsfuse-ui/date-fns";
77
+ ```
78
+
79
+ Host apps must **not** install or import `date-fns` directly — the full `date-fns` surface (including locales) is re-exported as flat named exports from `opsfuse-ui/date-fns` (and as the `DateFns` namespace from the main entry, for collision cases: `import { DateFns } from "opsfuse-ui"` → `DateFns.format(...)`). This guarantees a single pinned version across the host and library.
80
+
81
+ ---
82
+
83
+ ## 2. PROVIDERS SETUP (main.tsx)
84
+
85
+ **`OpsfuseThemeProvider`** (and `<OpsfuseRoot />`, which delegates to it) mounts the full provider stack: `ConfirmationDialogProvider`, `TooltipProvider`, `AlertProvider`, `DialogProvider`, `SheetProvider`, `SliderDialogProvider`, and `Toaster` (as a sibling of the sheet/slider subtree under `DialogProvider`). Host `main.tsx` should wrap the app once — do not duplicate those providers or add another `<ConfirmationDialogProvider>` (that duplicates the module-level `confirm` registration).
86
+
87
+ ```tsx
88
+ <OpsfuseThemeProvider className="min-h-svh">
89
+ <App />
90
+ </OpsfuseThemeProvider>
91
+ ```
92
+
93
+ **Never fork or reorder the internal provider tree without checking all imperative API call sites.**
94
+
95
+ Imperative APIs and where they are satisfied:
96
+ | API | Provided by |
97
+ |-----|---------------|
98
+ | `toast.success/error/loading()` from "sonner" | `<Toaster />` inside `<OpsfuseThemeProvider />` |
99
+ | `showAlert({ title, description, variant })` | `<AlertProvider />` inside theme |
100
+ | `openDialog({ title, children })` | `<DialogProvider />` inside theme |
101
+ | `openSheet({ title, children, side })` | `<SheetProvider />` inside theme |
102
+ | `confirm({ title, description?, confirmText?, cancelText?, hideCancel?, hideConfirm?, onConfirm?, onCancel? })` | `<ConfirmationDialogProvider />` inside theme |
103
+ | `openSlider({ title, value, min, max, ... })` | `<SliderDialogProvider />` inside theme |
104
+ | `<Tooltip>` anywhere in the tree | `<TooltipProvider />` inside theme |
105
+
106
+ ---
107
+
108
+ ## 3. DARK MODE
109
+
110
+ All tokens have dark values in `brands.css` under `.dark` (default brand) and `.brand-*.dark` selectors; `OpsfuseThemeProvider` toggles `dark` on the scope element by watching the host's dark convention.
111
+ When adding custom dark styles: use the `dark:` Tailwind prefix.
112
+ Never hardcode hex colors — tokens handle light/dark automatically.
113
+
114
+ ---
115
+
116
+ ## 4. ACCESSIBILITY RULES
117
+
118
+ - All interactive elements must have accessible labels (`aria-label` or visible text)
119
+ - Icon-only buttons: always `<Button size="icon" aria-label="Description">`
120
+ - Form fields: always pair with `<Label htmlFor="id">` or use the `label` prop on `<Input>`
121
+ - Disabled states: use `text-text-disabled` / `text-(--disabled-foreground)` on disabled controls only — never for readable body copy
122
+ - All provided semantic tokens meet WCAG 4.5:1 minimum contrast
123
+ - Use `confirm()` (requires `<OpsfuseThemeProvider />` / `<OpsfuseRoot />`, which mount the confirmation provider) before any destructive action (delete, reset, overwrite)
124
+
125
+ ---
126
+
127
+ ## 5. STORYBOOK STORY PATTERN
128
+
129
+ When creating stories:
130
+
131
+ ```tsx
132
+ import type { Meta, StoryObj } from "@storybook/react"
133
+ import { ComponentName } from "opsfuse-ui"
134
+
135
+ const meta: Meta<typeof ComponentName> = {
136
+ title: "UI/ComponentName",
137
+ component: ComponentName,
138
+ argTypes: { variant: { control: "select", options: [...] } },
139
+ args: { /* sensible defaults */ },
140
+ }
141
+ export default meta
142
+ type Story = StoryObj<typeof ComponentName>
143
+
144
+ export const Default: Story = { args: {} }
145
+ export const AllVariants: Story = { render: () => <div className="flex gap-2">...</div> }
146
+ ```
147
+
148
+ Write stories for all new components. Test in both light and dark mode. Page-level title strips use `PageHeader` from `src/components/ui/Header.tsx` (see `/components` skill).
149
+
150
+ **Alert dialog:** Storybook covers `src/components/ui/alert-dialog.tsx` via `confirm()` only. The preview wraps stories in `<OpsfuseRoot />`, which uses `OpsfuseThemeProvider` (full provider stack including `ConfirmationDialogProvider`) — stories must not add another `<ConfirmationDialogProvider>`. In apps, same rule: one theme root. Radix primitives live in `shadcn-alert-dialog.tsx` for internal use — do not add a separate Storybook file for that layer.
151
+
152
+ ---
153
+
154
+ ## 6. DO / DON'T
155
+
156
+ | ✅ DO | ❌ DON'T |
157
+ | --------------------------------------------------- | -------------------------------------------------- |
158
+ | Use design tokens for all colors | Use arbitrary hex like `#ff0000` or `bg-red-500` |
159
+ | Use `cn()` for all className merging | String-concatenate classNames directly |
160
+ | Use `cva()` for multi-variant components | Inline ternary chains for variants |
161
+ | Add `data-slot` to every component part | Skip `data-slot` on wrapper/part elements |
162
+ | Use `<Field>` compound for form inputs | Lay out label + input with raw divs |
163
+ | Import icons from `opsfuse-ui/icons` | Import from `lucide-react` or other icon libraries |
164
+ | Import dates from `opsfuse-ui/date-fns` | Install/import `date-fns` directly in host apps |
165
+ | Use `.transition-micro/smooth/data` motion classes | Hardcode `transition duration-200` everywhere |
166
+ | Use `confirm()` before destructive actions | Skip confirmation on destructive button clicks |
167
+ | Use spacing tokens `--space-1` through `--space-10` | Use arbitrary gaps like `gap-[13px]` |
168
+ | Write stories for all new components | Add components without Storybook coverage |
169
+ | Test in light AND dark mode | Only check light mode |
package/LICENSE CHANGED
@@ -1,17 +1,17 @@
1
- Copyright (c) 2026 OpsFuse. All rights reserved.
2
-
3
- This software and its source code are proprietary and confidential.
4
-
5
- No license, express or implied, is granted to any party to use, copy, modify,
6
- merge, publish, distribute, sublicense, or sell copies of this software, except
7
- under a separate written agreement with OpsFuse.
8
-
9
- Unauthorized copying, distribution, or use of this software, via any medium, is
10
- strictly prohibited.
11
-
12
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
13
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
14
- FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
15
- COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
16
- IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
17
- CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1
+ Copyright (c) 2026 OpsFuse. All rights reserved.
2
+
3
+ This software and its source code are proprietary and confidential.
4
+
5
+ No license, express or implied, is granted to any party to use, copy, modify,
6
+ merge, publish, distribute, sublicense, or sell copies of this software, except
7
+ under a separate written agreement with OpsFuse.
8
+
9
+ Unauthorized copying, distribution, or use of this software, via any medium, is
10
+ strictly prohibited.
11
+
12
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
13
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
14
+ FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
15
+ COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
16
+ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
17
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.