@soulbatical/tetra-ui 0.2.0 → 0.2.1

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.
Files changed (2) hide show
  1. package/README.md +183 -0
  2. package/package.json +3 -2
package/README.md ADDED
@@ -0,0 +1,183 @@
1
+ # @soulbatical/tetra-ui
2
+
3
+ Shared React frontend framework for Tetra platform projects — config-driven components, hooks, providers, and styling.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @soulbatical/tetra-ui
9
+ ```
10
+
11
+ Only install the peer dependencies you actually use (all are optional except `react`):
12
+
13
+ ```bash
14
+ # Always needed
15
+ npm install react react-dom
16
+
17
+ # Only if you use ./query or ./feature
18
+ npm install @tanstack/react-query
19
+
20
+ # Only if you use ./table
21
+ npm install @tanstack/react-table
22
+
23
+ # Only if you use ./next
24
+ npm install next next-themes
25
+
26
+ # Only if you use ./planner
27
+ npm install @daypilot/daypilot-lite-react
28
+ ```
29
+
30
+ ## Subpath Exports
31
+
32
+ Import only what you need. Each subpath has its own dependency footprint:
33
+
34
+ ```typescript
35
+ // Shadcn/ui primitives (radix + cva + tailwind-merge)
36
+ import { Button, Input, Card, Dialog } from '@soulbatical/tetra-ui/primitives';
37
+
38
+ // Layout & display components (React + lucide only)
39
+ import { ListDetailLayout, AutoCard, InfiniteGrid } from '@soulbatical/tetra-ui/components';
40
+
41
+ // Utility hooks (React only, zero external deps)
42
+ import { useDebounce, useDialog, useQueryState } from '@soulbatical/tetra-ui/hooks';
43
+
44
+ // Auth hooks + API client (requires @supabase/supabase-js)
45
+ import { useAuth, apiClient } from '@soulbatical/tetra-ui/auth';
46
+
47
+ // Query provider + cache hooks (requires @tanstack/react-query)
48
+ import { QueryProvider, useCacheInvalidation } from '@soulbatical/tetra-ui/query';
49
+
50
+ // Data table (requires @tanstack/react-table + tetra-core)
51
+ import { FeatureTable } from '@soulbatical/tetra-ui/table';
52
+
53
+ // Full-stack feature components (requires tetra-core + react-query)
54
+ import { FeatureFilters, FeatureForm, useFeature } from '@soulbatical/tetra-ui/feature';
55
+
56
+ // Next.js providers (requires next + next-themes)
57
+ import { ThemeProvider, ThemeToggle } from '@soulbatical/tetra-ui/next';
58
+
59
+ // Scheduling components (requires @daypilot/daypilot-lite-react)
60
+ import { BookingWidget, WeekCalendar } from '@soulbatical/tetra-ui/planner';
61
+
62
+ // Affiliate dashboard hooks (requires @supabase/supabase-js)
63
+ import { useAffiliateDashboard } from '@soulbatical/tetra-ui/affiliate';
64
+
65
+ // Barrel export — everything (requires ALL peer deps)
66
+ import { Button, ListDetailLayout, useFeature } from '@soulbatical/tetra-ui';
67
+ ```
68
+
69
+ | Subpath | What you get | Extra peer deps needed |
70
+ |---------|-------------|----------------------|
71
+ | `./primitives` | Button, Input, Card, Dialog, Select, Table, Tabs, Badge, Label, Textarea | — |
72
+ | `./components` | ListDetailLayout, AutoCard, InfiniteGrid, PageHeader, StatusBadge, LoadingStates, CookieConsent, OAuthButtons | — |
73
+ | `./hooks` | useDebounce, useDialog, useIsMobile, useQueryState, useInfiniteScroll, useFormSubmit, usePageContext | — |
74
+ | `./auth` | useAuth, apiClient, useOrganizations | @supabase/supabase-js |
75
+ | `./query` | QueryProvider, useCacheInvalidation, useFilterConfigs | @tanstack/react-query |
76
+ | `./table` | FeatureTable | @tanstack/react-table, tetra-core |
77
+ | `./feature` | FeatureFilters, FeatureForm, useFeature | tetra-core, react-query |
78
+ | `./next` | ThemeProvider, ThemeToggle | next, next-themes |
79
+ | `./planner` | BookingWidget, WeekCalendar, TeamPlanner, AvailabilityEditor | @daypilot/daypilot-lite-react |
80
+ | `./affiliate` | useAffiliateDashboard | @supabase/supabase-js |
81
+ | `.` | Everything | All of the above |
82
+
83
+ ## Design Tokens (Theming)
84
+
85
+ All tetra-ui layout and feature components use `--tetra-*` CSS custom properties for colors. No hardcoded Tailwind color classes. This means you can theme every component by setting CSS variables.
86
+
87
+ ### Quick start
88
+
89
+ Import the default tokens:
90
+
91
+ ```css
92
+ @import '@soulbatical/tetra-ui/styles/tokens.css';
93
+ ```
94
+
95
+ Or define your own values:
96
+
97
+ ```css
98
+ :root {
99
+ --tetra-bg: #ffffff;
100
+ --tetra-bg-subtle: #f9fafb;
101
+ --tetra-bg-muted: #f3f4f6;
102
+ --tetra-border: #e5e7eb;
103
+ --tetra-border-subtle: #f3f4f6;
104
+ --tetra-text: #111827;
105
+ --tetra-text-muted: #6b7280;
106
+ --tetra-text-inverted: #ffffff;
107
+ --tetra-accent: #3b82f6;
108
+ --tetra-accent-subtle: #eff6ff;
109
+ --tetra-accent-hover: #2563eb;
110
+ --tetra-danger: #ef4444;
111
+ --tetra-danger-subtle: #fef2f2;
112
+ --tetra-success: #22c55e;
113
+ --tetra-success-subtle: #f0fdf4;
114
+ --tetra-warning: #f59e0b;
115
+ --tetra-warning-subtle: #fffbeb;
116
+ --tetra-radius: 8px;
117
+ --tetra-radius-sm: 4px;
118
+ --tetra-radius-lg: 12px;
119
+ --tetra-font: inherit;
120
+ }
121
+ ```
122
+
123
+ ### Dark mode
124
+
125
+ Override the tokens in a dark scope:
126
+
127
+ ```css
128
+ .dark, [data-theme="dark"] {
129
+ --tetra-bg: #0f172a;
130
+ --tetra-bg-subtle: #1e293b;
131
+ --tetra-bg-muted: #334155;
132
+ --tetra-border: #334155;
133
+ --tetra-border-subtle: #1e293b;
134
+ --tetra-text: #f1f5f9;
135
+ --tetra-text-muted: #94a3b8;
136
+ --tetra-text-inverted: #0f172a;
137
+ --tetra-accent: #60a5fa;
138
+ --tetra-accent-subtle: rgba(30, 58, 138, 0.3);
139
+ --tetra-accent-hover: #93bbfc;
140
+ }
141
+ ```
142
+
143
+ ### Per-section theming
144
+
145
+ Scope tokens to any parent element:
146
+
147
+ ```tsx
148
+ <div style={{ '--tetra-accent': '#f97316' } as React.CSSProperties}>
149
+ <ListDetailLayout ... /> {/* Uses orange accent */}
150
+ </div>
151
+ ```
152
+
153
+ ### What about shadcn/ui primitives?
154
+
155
+ The `./primitives` subpath (Button, Input, Card, etc.) uses shadcn/ui's own token system (`--background`, `--primary`, `--border`, etc.) and is **not** affected by `--tetra-*` tokens. These two systems coexist without conflict.
156
+
157
+ ## Tailwind Preset
158
+
159
+ For projects using Tailwind CSS, tetra-ui provides a preset with the design system's colors, spacing, and typography:
160
+
161
+ ```javascript
162
+ // tailwind.config.js
163
+ import tetraPreset from '@soulbatical/tetra-ui/tailwind-preset';
164
+
165
+ export default {
166
+ presets: [tetraPreset],
167
+ content: [
168
+ './src/**/*.{ts,tsx}',
169
+ './node_modules/@soulbatical/tetra-ui/dist/**/*.js',
170
+ ],
171
+ };
172
+ ```
173
+
174
+ ## Theming Compliance Check
175
+
176
+ The `@soulbatical/tetra-dev-toolkit` includes a `ui-theming` check that enforces:
177
+
178
+ - No Tailwind color classes in tetra-ui components (e.g. `bg-blue-500`)
179
+ - No hardcoded hex/rgb/hsl color values
180
+ - No component-specific CSS vars (e.g. `--ldl-*`) — only `--tetra-*`
181
+ - Brand colors (OAuth buttons) are exempt via `// Brand color` comment
182
+
183
+ This check runs at prepublish time to prevent regressions.
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "restricted"
6
6
  },
7
- "version": "0.2.0",
7
+ "version": "0.2.1",
8
8
  "description": "Shared React frontend framework for Tetra platform projects (Soulbatical BV) — config-driven components, hooks, providers, and styling",
9
9
  "type": "module",
10
10
  "main": "dist/index.js",
@@ -94,7 +94,7 @@
94
94
  "@supabase/supabase-js": "^2.0.0",
95
95
  "@tanstack/react-query": "^5.0.0",
96
96
  "@tanstack/react-table": "^8.0.0",
97
- "next": "^14.0.0 || ^15.0.0",
97
+ "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
98
98
  "next-themes": "^0.4.0",
99
99
  "react": "^18.0.0 || ^19.0.0",
100
100
  "react-dom": "^18.0.0 || ^19.0.0",
@@ -137,6 +137,7 @@
137
137
  "tailwind-merge": "^2.6.0"
138
138
  },
139
139
  "devDependencies": {
140
+ "@daypilot/daypilot-lite-react": "^5.4.1",
140
141
  "@soulbatical/tetra-core": "^0.1.0",
141
142
  "@supabase/supabase-js": "2.93.3",
142
143
  "@tanstack/react-query": "^5.0.0",