@webstrail/ui-library 0.0.0-stage → 1.0.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/LICENSE +21 -0
- package/README.md +518 -2
- package/dist/components/Button/Button.d.ts +2 -0
- package/dist/components/Button/Button.types.d.ts +45 -0
- package/dist/components/Button/index.d.ts +2 -0
- package/dist/components/Checkbox/Checkbox.d.ts +2 -0
- package/dist/components/Checkbox/Checkbox.types.d.ts +38 -0
- package/dist/components/Checkbox/index.d.ts +2 -0
- package/dist/components/Input/Input.d.ts +2 -0
- package/dist/components/Input/Input.types.d.ts +87 -0
- package/dist/components/Input/index.d.ts +2 -0
- package/dist/components/Radio/Radio.d.ts +2 -0
- package/dist/components/Radio/Radio.types.d.ts +119 -0
- package/dist/components/Radio/RadioGroup.d.ts +2 -0
- package/dist/components/Radio/RadioGroupContext.d.ts +13 -0
- package/dist/components/Radio/index.d.ts +4 -0
- package/dist/components/Select/Select.d.ts +2 -0
- package/dist/components/Select/Select.types.d.ts +100 -0
- package/dist/components/Select/index.d.ts +2 -0
- package/dist/components/Switch/Switch.d.ts +2 -0
- package/dist/components/Switch/Switch.types.d.ts +82 -0
- package/dist/components/Switch/index.d.ts +2 -0
- package/dist/components/Textarea/Textarea.d.ts +2 -0
- package/dist/components/Textarea/Textarea.types.d.ts +61 -0
- package/dist/components/Textarea/index.d.ts +2 -0
- package/dist/components/index.d.ts +14 -0
- package/dist/config/config.types.d.ts +232 -0
- package/dist/config/defaultConfig.d.ts +2 -0
- package/dist/config/mergeConfig.d.ts +28 -0
- package/dist/context/UIContext.d.ts +6 -0
- package/dist/context/index.d.ts +1 -0
- package/dist/hooks/index.d.ts +3 -0
- package/dist/hooks/useComponentStyles.d.ts +26 -0
- package/dist/hooks/useUI.d.ts +6 -0
- package/dist/index.cjs +2 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.ts +25 -0
- package/dist/index.js +1577 -0
- package/dist/index.js.map +1 -0
- package/dist/providers/UIProvider.d.ts +20 -0
- package/dist/providers/index.d.ts +2 -0
- package/dist/style.css +1 -0
- package/dist/types/common.d.ts +41 -0
- package/dist/types/index.d.ts +1 -0
- package/dist/utils/classNames.d.ts +11 -0
- package/dist/utils/resolveStyles.d.ts +28 -0
- package/package.json +102 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Webstrail
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,519 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @webstrail/ui-library
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A production-ready, framework-agnostic, enterprise-grade React 19 component library engineered with TypeScript strict mode, CSS Modules isolation, and a 3-tier styling resolution engine.
|
|
4
|
+
|
|
5
|
+
Designed to be used seamlessly across any consumer application styling paradigm: **Tailwind CSS**, **Plain CSS**, **CSS Modules**, **Styled Components**, or **Emotion**.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Table of Contents
|
|
10
|
+
|
|
11
|
+
- [Features](#features)
|
|
12
|
+
- [Architecture & Universal Styling Model](#architecture--universal-styling-model)
|
|
13
|
+
- [Three Styling APIs per Component](#three-styling-apis-per-component)
|
|
14
|
+
- [Style Resolution Priority](#style-resolution-priority)
|
|
15
|
+
- [Installation](#installation)
|
|
16
|
+
- [Getting Started](#getting-started)
|
|
17
|
+
- [Global Configuration System (UIProvider)](#global-configuration-system-uiprovider)
|
|
18
|
+
- [Advanced UIProvider Capabilities](#advanced-uiprovider-capabilities)
|
|
19
|
+
- [UIConfig Reference](#uiconfig-reference)
|
|
20
|
+
- [Component APIs & Examples](#component-apis--examples)
|
|
21
|
+
- [Button](#button)
|
|
22
|
+
- [Input](#input)
|
|
23
|
+
- [Checkbox](#checkbox)
|
|
24
|
+
- [Radio & RadioGroup](#radio--radiogroup)
|
|
25
|
+
- [Switch](#switch)
|
|
26
|
+
- [Select](#select)
|
|
27
|
+
- [Textarea](#textarea)
|
|
28
|
+
- [Consumer Integration Guides](#consumer-integration-guides)
|
|
29
|
+
- [Tailwind CSS Consumer](#tailwind-css-consumer)
|
|
30
|
+
- [CSS Modules / Plain CSS Consumer](#css-modules--plain-css-consumer)
|
|
31
|
+
- [Zero-Provider Standalone Usage](#zero-provider-standalone-usage)
|
|
32
|
+
- [Developer & Quality Scripts](#developer--quality-scripts)
|
|
33
|
+
- [Package Distribution & Publishing](#package-distribution--publishing)
|
|
34
|
+
- [License](#license)
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Features
|
|
39
|
+
|
|
40
|
+
- **React 19 & Strict TypeScript**: Complete IntelliSense, zero `any`, strictly typed props, styles, and configs.
|
|
41
|
+
- **Framework Agnostic**: Internally scoped with CSS Modules; fully compatible with Tailwind utility classes, CSS Modules, or standard CSS in consumer apps.
|
|
42
|
+
- **Zero Style Leakage**: Component styles are completely encapsulated; uses scoped `--wui-*` CSS custom properties, never mutates `:root` dynamically, and does not alter global `body`, `html`, or application layout.
|
|
43
|
+
- **3-Tier Semantic Styling Engine**: Fine-grained property merge combining component `styles` prop > `UIProvider` config > built-in defaults.
|
|
44
|
+
- **3 Concurrent Styling APIs**: Every component supports `className` (classes/Tailwind), `style` (inline `CSSProperties`), and `styles` (semantic tokens).
|
|
45
|
+
- **Accessible (a11y)**: Compliant with WAI-ARIA guidelines, including accessible labels, descriptions, keyboard navigation, and live regions.
|
|
46
|
+
- **Dual Bundle Distribution**: ESM (`dist/index.js`) and CJS (`dist/index.cjs`) with externalized React and generated `.d.ts` declarations.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Architecture & Universal Styling Model
|
|
51
|
+
|
|
52
|
+
### Three Styling APIs per Component
|
|
53
|
+
|
|
54
|
+
Every component in `@webstrail/ui-library` accepts three distinct styling channels:
|
|
55
|
+
|
|
56
|
+
```tsx
|
|
57
|
+
<Input
|
|
58
|
+
// 1. className: For Tailwind utilities, CSS Modules classes, or global class names
|
|
59
|
+
className="w-full rounded-lg bg-blue-50 shadow-sm"
|
|
60
|
+
|
|
61
|
+
// 2. style: Standard React.CSSProperties directly applied to root DOM element
|
|
62
|
+
style={{ marginBottom: '16px' }}
|
|
63
|
+
|
|
64
|
+
// 3. styles: Strongly typed semantic tokens mapped to scoped CSS variables
|
|
65
|
+
styles={{
|
|
66
|
+
height: '48px',
|
|
67
|
+
borderColor: '#2491eb',
|
|
68
|
+
borderRadius: '12px',
|
|
69
|
+
backgroundColor: '#ffffff',
|
|
70
|
+
}}
|
|
71
|
+
/>
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Style Resolution Priority
|
|
75
|
+
|
|
76
|
+
Semantic styles are resolved property-by-property in this exact order:
|
|
77
|
+
|
|
78
|
+
$$\text{Component-level } \texttt{styles} \;\succ\; \text{UIProvider } \texttt{config} \;\succ\; \text{Built-in Library Defaults}$$
|
|
79
|
+
|
|
80
|
+
This is an **immutable, property-level merge**, not a full object replacement. If you specify only `{ borderColor: 'red' }` at the component level, height, padding, font size, and border radius from the Provider and built-in defaults are preserved intact.
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Installation
|
|
85
|
+
|
|
86
|
+
Install using Yarn, NPM, or PNPM:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
# Using Yarn
|
|
90
|
+
yarn add @webstrail/ui-library
|
|
91
|
+
|
|
92
|
+
# Using NPM
|
|
93
|
+
npm install @webstrail/ui-library
|
|
94
|
+
|
|
95
|
+
# Using PNPM
|
|
96
|
+
pnpm add @webstrail/ui-library
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Import the library CSS once in your application entry point (e.g., `main.tsx` or `App.tsx`):
|
|
100
|
+
|
|
101
|
+
```tsx
|
|
102
|
+
import '@webstrail/ui-library/style.css';
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## Getting Started
|
|
108
|
+
|
|
109
|
+
```tsx
|
|
110
|
+
import React from 'react';
|
|
111
|
+
import { UIProvider, Button, Input } from '@webstrail/ui-library';
|
|
112
|
+
import '@webstrail/ui-library/style.css';
|
|
113
|
+
|
|
114
|
+
export function App() {
|
|
115
|
+
return (
|
|
116
|
+
<UIProvider
|
|
117
|
+
config={{
|
|
118
|
+
colors: {
|
|
119
|
+
primary: '#2491eb',
|
|
120
|
+
},
|
|
121
|
+
button: {
|
|
122
|
+
borderRadius: '8px',
|
|
123
|
+
height: '42px',
|
|
124
|
+
},
|
|
125
|
+
}}
|
|
126
|
+
>
|
|
127
|
+
<main style={{ padding: '24px', maxWidth: '400px' }}>
|
|
128
|
+
<Input
|
|
129
|
+
label="Email"
|
|
130
|
+
placeholder="name@example.com"
|
|
131
|
+
styles={{ borderColor: '#d1d5db' }}
|
|
132
|
+
className="mb-4"
|
|
133
|
+
/>
|
|
134
|
+
|
|
135
|
+
<Button
|
|
136
|
+
label="Sign In"
|
|
137
|
+
variant="primary"
|
|
138
|
+
fullWidth
|
|
139
|
+
onClick={() => alert('Signing in...')}
|
|
140
|
+
/>
|
|
141
|
+
</main>
|
|
142
|
+
</UIProvider>
|
|
143
|
+
);
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## Global Configuration System (UIProvider)
|
|
150
|
+
|
|
151
|
+
### Advanced UIProvider Capabilities
|
|
152
|
+
|
|
153
|
+
- **Optional**: All components work out-of-the-box with modern, accessible default styles without a Provider.
|
|
154
|
+
- **Subtree Scoping & Nesting**: Nested `UIProvider` instances inherit from parent providers and override specific properties for a subtree.
|
|
155
|
+
- **Zero Pollution**: No global `:root` mutation. CSS custom properties are scoped to components.
|
|
156
|
+
- **Reactive & Performant**: Configuration merges are memoized; runtime config changes propagate cleanly without unnecessary re-renders.
|
|
157
|
+
|
|
158
|
+
```tsx
|
|
159
|
+
import { UIProvider } from '@webstrail/ui-library';
|
|
160
|
+
|
|
161
|
+
const brandTheme = {
|
|
162
|
+
colors: {
|
|
163
|
+
primary: '#6366f1',
|
|
164
|
+
secondary: '#4338ca',
|
|
165
|
+
text: '#0f172a',
|
|
166
|
+
border: '#cbd5e1',
|
|
167
|
+
error: '#ef4444',
|
|
168
|
+
},
|
|
169
|
+
button: {
|
|
170
|
+
height: '44px',
|
|
171
|
+
borderRadius: '10px',
|
|
172
|
+
fontSize: '15px',
|
|
173
|
+
},
|
|
174
|
+
input: {
|
|
175
|
+
height: '44px',
|
|
176
|
+
borderRadius: '10px',
|
|
177
|
+
focusBorderColor: '#6366f1',
|
|
178
|
+
},
|
|
179
|
+
};
|
|
180
|
+
|
|
181
|
+
export function Root() {
|
|
182
|
+
return (
|
|
183
|
+
<UIProvider config={brandTheme}>
|
|
184
|
+
<Application />
|
|
185
|
+
</UIProvider>
|
|
186
|
+
);
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### UIConfig Reference
|
|
191
|
+
|
|
192
|
+
| Section | Tokens / Configurable Keys |
|
|
193
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
194
|
+
| `colors` | `primary`, `secondary`, `text`, `textSecondary`, `border`, `background`, `error`, `success`, `disabled`, `disabledBackground`, `disabledText`, `focusRing` |
|
|
195
|
+
| `typography` | `fontFamily`, `fontSizeSmall`, `fontSizeMedium`, `fontSizeLarge`, `fontWeightNormal`, `fontWeightMedium`, `fontWeightBold` |
|
|
196
|
+
| `layout` | `borderRadiusSmall`, `borderRadiusMedium`, `borderRadiusLarge` |
|
|
197
|
+
| `button` | `height`, `borderRadius`, `fontSize`, `fontWeight`, `backgroundColor`, `textColor`, `borderColor`, `hoverBackgroundColor`, `hoverTextColor`, `activeBackgroundColor`, `disabledBackgroundColor`, `disabledTextColor`, `padding`, `transition` |
|
|
198
|
+
| `input` | `height`, `borderRadius`, `borderColor`, `textColor`, `placeholderColor`, `backgroundColor`, `focusBorderColor`, `focusRingColor`, `errorBorderColor`, `disabledBackgroundColor`, `disabledTextColor`, `labelColor`, `helperColor`, `errorColor`, `fontSize`, `padding` |
|
|
199
|
+
| `select` | `height`, `borderRadius`, `borderColor`, `textColor`, `placeholderColor`, `backgroundColor`, `focusBorderColor`, `focusRingColor`, `errorBorderColor`, `dropdownBackgroundColor`, `dropdownBorderColor`, `dropdownShadow`, `optionTextColor`, `optionHoverBackgroundColor`, `optionHoverTextColor`, `optionSelectedBackgroundColor`, `optionSelectedTextColor`, `optionSelectedHoverBackgroundColor`, `optionCheckColor`, `optionBorderRadius`, `optionPadding`, `optionFontSize`, `optionFontWeight`, `optionSelectedFontWeight`, `labelColor`, `errorColor` |
|
|
200
|
+
| `checkbox` | `size`, `borderRadius`, `borderColor`, `checkedColor`, `checkmarkColor`, `backgroundColor`, `focusRingColor`, `disabledColor`, `disabledBackgroundColor`, `labelColor`, `fontSize` |
|
|
201
|
+
| `radio` | `size`, `borderColor`, `checkedColor`, `dotColor`, `dotSize`, `backgroundColor`, `focusRingColor`, `disabledColor`, `disabledBackgroundColor`, `labelColor`, `descriptionColor`, `fontSize` |
|
|
202
|
+
| `switch` | `width`, `height`, `thumbSize`, `thumbColor`, `thumbCheckedColor`, `trackColor`, `trackCheckedColor`, `focusRingColor`, `borderRadius`, `disabledOpacity`, `labelColor`, `descriptionColor`, `fontSize` |
|
|
203
|
+
| `textarea` | `minHeight`, `borderRadius`, `borderColor`, `textColor`, `placeholderColor`, `backgroundColor`, `focusBorderColor`, `focusRingColor`, `errorBorderColor`, `disabledBackgroundColor`, `disabledTextColor`, `labelColor`, `helperColor`, `errorColor`, `counterColor`, `fontSize`, `padding` |
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## Component APIs & Examples
|
|
208
|
+
|
|
209
|
+
### Button
|
|
210
|
+
|
|
211
|
+
```tsx
|
|
212
|
+
import { Button } from '@webstrail/ui-library';
|
|
213
|
+
|
|
214
|
+
// Variants
|
|
215
|
+
<Button variant="primary" label="Primary Action" />
|
|
216
|
+
<Button variant="secondary" label="Secondary Action" />
|
|
217
|
+
<Button variant="outline" label="Outline Action" />
|
|
218
|
+
<Button variant="ghost" label="Ghost Action" />
|
|
219
|
+
<Button variant="danger" label="Delete" />
|
|
220
|
+
|
|
221
|
+
// Sizes & States
|
|
222
|
+
<Button size="small" label="Small" />
|
|
223
|
+
<Button size="large" fullWidth loading loadingText="Processing..." />
|
|
224
|
+
<Button disabled label="Disabled" />
|
|
225
|
+
|
|
226
|
+
// Icons
|
|
227
|
+
<Button startIcon={<DownloadIcon />} label="Download Report" />
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### Input
|
|
231
|
+
|
|
232
|
+
```tsx
|
|
233
|
+
import { Input } from '@webstrail/ui-library';
|
|
234
|
+
|
|
235
|
+
// Default Floating Label with smooth transition to top-left corner on focus/fill
|
|
236
|
+
<Input
|
|
237
|
+
label="Work Email"
|
|
238
|
+
placeholder="name@company.com"
|
|
239
|
+
required
|
|
240
|
+
helperText="We will never share your email."
|
|
241
|
+
startIcon={<MailIcon />}
|
|
242
|
+
styles={{
|
|
243
|
+
borderColor: '#94a3b8',
|
|
244
|
+
focusBorderColor: '#2491eb',
|
|
245
|
+
}}
|
|
246
|
+
/>
|
|
247
|
+
|
|
248
|
+
// Static Top Label Mode (disable floating transition)
|
|
249
|
+
<Input
|
|
250
|
+
label="Username"
|
|
251
|
+
floatingLabel={false}
|
|
252
|
+
placeholder="Enter username"
|
|
253
|
+
/>
|
|
254
|
+
|
|
255
|
+
// Error State
|
|
256
|
+
<Input
|
|
257
|
+
label="Username"
|
|
258
|
+
defaultValue="taken_user"
|
|
259
|
+
errorMessage="This username is already taken"
|
|
260
|
+
/>
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### Checkbox
|
|
264
|
+
|
|
265
|
+
```tsx
|
|
266
|
+
import { Checkbox } from '@webstrail/ui-library';
|
|
267
|
+
|
|
268
|
+
// Uncontrolled
|
|
269
|
+
<Checkbox label="Remember me" defaultChecked />
|
|
270
|
+
|
|
271
|
+
// Controlled & Indeterminate
|
|
272
|
+
<Checkbox
|
|
273
|
+
label="Select all items"
|
|
274
|
+
checked={isAllSelected}
|
|
275
|
+
indeterminate={isPartiallySelected}
|
|
276
|
+
onChange={(e) => handleToggleAll(e.target.checked)}
|
|
277
|
+
/>
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
### Select
|
|
281
|
+
|
|
282
|
+
```tsx
|
|
283
|
+
import { Select } from '@webstrail/ui-library';
|
|
284
|
+
|
|
285
|
+
// Standard Select - Option theme automatically adapts to UIProvider primary color
|
|
286
|
+
<Select
|
|
287
|
+
label="Assigned Team"
|
|
288
|
+
placeholder="Choose team..."
|
|
289
|
+
options={[
|
|
290
|
+
{ value: 'eng', label: 'Engineering' },
|
|
291
|
+
{ value: 'product', label: 'Product Management' },
|
|
292
|
+
{ value: 'ops', label: 'Operations', disabled: true },
|
|
293
|
+
]}
|
|
294
|
+
value={selectedTeam}
|
|
295
|
+
onChange={(val) => setSelectedTeam(val)}
|
|
296
|
+
/>;
|
|
297
|
+
|
|
298
|
+
// Custom Option Theming via Config or Component Styles
|
|
299
|
+
<Select
|
|
300
|
+
label="Custom Option Themed Select"
|
|
301
|
+
styles={{
|
|
302
|
+
optionTextColor: '#334155',
|
|
303
|
+
optionHoverBackgroundColor: '#fef3c7',
|
|
304
|
+
optionHoverTextColor: '#92400e',
|
|
305
|
+
optionSelectedBackgroundColor: '#fde68a',
|
|
306
|
+
optionSelectedTextColor: '#78350f',
|
|
307
|
+
optionSelectedHoverBackgroundColor: '#fcd34d',
|
|
308
|
+
optionCheckColor: '#78350f',
|
|
309
|
+
optionPadding: '10px 14px',
|
|
310
|
+
optionBorderRadius: '8px',
|
|
311
|
+
optionSelectedFontWeight: 600,
|
|
312
|
+
}}
|
|
313
|
+
options={[
|
|
314
|
+
{ value: 'admin', label: 'Administrator' },
|
|
315
|
+
{ value: 'editor', label: 'Editor' },
|
|
316
|
+
{ value: 'viewer', label: 'Viewer' },
|
|
317
|
+
]}
|
|
318
|
+
/>;
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
### Radio & RadioGroup
|
|
322
|
+
|
|
323
|
+
```tsx
|
|
324
|
+
import { Radio, RadioGroup } from '@webstrail/ui-library';
|
|
325
|
+
|
|
326
|
+
// Declarative RadioGroup with options & descriptions
|
|
327
|
+
<RadioGroup
|
|
328
|
+
name="plan"
|
|
329
|
+
defaultValue="pro"
|
|
330
|
+
direction="vertical"
|
|
331
|
+
options={[
|
|
332
|
+
{ value: 'free', label: 'Free Tier', description: 'Up to 3 projects' },
|
|
333
|
+
{ value: 'pro', label: 'Pro Tier', description: 'Unlimited projects & priority support' },
|
|
334
|
+
{ value: 'enterprise', label: 'Enterprise', disabled: true },
|
|
335
|
+
]}
|
|
336
|
+
onChange={(val) => console.log('Selected:', val)}
|
|
337
|
+
/>;
|
|
338
|
+
|
|
339
|
+
// Standalone Radio with custom color and size
|
|
340
|
+
<Radio name="payment" value="credit_card" label="Credit Card" color="#10b981" size="20px" />;
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
### Switch
|
|
344
|
+
|
|
345
|
+
```tsx
|
|
346
|
+
import { Switch } from '@webstrail/ui-library';
|
|
347
|
+
|
|
348
|
+
// Standard Switch with labels and secondary description
|
|
349
|
+
<Switch
|
|
350
|
+
label="Enable Notifications"
|
|
351
|
+
description="Receive alerts when tasks complete."
|
|
352
|
+
checked={isEnabled}
|
|
353
|
+
onChange={(checked) => setIsEnabled(checked)}
|
|
354
|
+
/>;
|
|
355
|
+
|
|
356
|
+
// Sizes and thumb icons
|
|
357
|
+
<Switch size="small" defaultChecked />
|
|
358
|
+
<Switch size="medium" defaultChecked checkedIcon={<span>✓</span>} />
|
|
359
|
+
<Switch size="large" defaultChecked />
|
|
360
|
+
|
|
361
|
+
// Custom styling override
|
|
362
|
+
<Switch
|
|
363
|
+
label="Custom Pill Switch"
|
|
364
|
+
defaultChecked
|
|
365
|
+
styles={{
|
|
366
|
+
trackCheckedColor: '#8b5cf6',
|
|
367
|
+
width: '46px',
|
|
368
|
+
height: '24px',
|
|
369
|
+
thumbSize: '18px',
|
|
370
|
+
}}
|
|
371
|
+
/>;
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
### Textarea
|
|
375
|
+
|
|
376
|
+
```tsx
|
|
377
|
+
import { Textarea } from '@webstrail/ui-library';
|
|
378
|
+
|
|
379
|
+
<Textarea
|
|
380
|
+
label="Project Summary"
|
|
381
|
+
placeholder="Describe goals and scope..."
|
|
382
|
+
rows={4}
|
|
383
|
+
maxLength={300}
|
|
384
|
+
showCount
|
|
385
|
+
helperText="Summarize in 300 characters or less."
|
|
386
|
+
/>;
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
---
|
|
390
|
+
|
|
391
|
+
## Consumer Integration Guides
|
|
392
|
+
|
|
393
|
+
### Tailwind CSS Consumer
|
|
394
|
+
|
|
395
|
+
In a consumer application using Tailwind CSS, apply utility classes directly to `className`:
|
|
396
|
+
|
|
397
|
+
```tsx
|
|
398
|
+
import { Button, Input } from '@webstrail/ui-library';
|
|
399
|
+
|
|
400
|
+
export function TailwindDemo() {
|
|
401
|
+
return (
|
|
402
|
+
<div className="flex flex-col gap-4 max-w-sm mx-auto">
|
|
403
|
+
<Input
|
|
404
|
+
placeholder="Search projects..."
|
|
405
|
+
className="w-full rounded-2xl border-indigo-400 bg-indigo-50/50 shadow-sm"
|
|
406
|
+
/>
|
|
407
|
+
<Button
|
|
408
|
+
label="Explore"
|
|
409
|
+
className="w-full uppercase tracking-wider bg-gradient-to-r from-blue-600 to-indigo-600 hover:from-blue-700 hover:to-indigo-700"
|
|
410
|
+
/>
|
|
411
|
+
</div>
|
|
412
|
+
);
|
|
413
|
+
}
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
### CSS Modules / Plain CSS Consumer
|
|
417
|
+
|
|
418
|
+
In a consumer application using CSS Modules:
|
|
419
|
+
|
|
420
|
+
```css
|
|
421
|
+
/* Dashboard.module.css */
|
|
422
|
+
.customCard {
|
|
423
|
+
border: 1px solid #e2e8f0;
|
|
424
|
+
padding: 24px;
|
|
425
|
+
border-radius: 16px;
|
|
426
|
+
}
|
|
427
|
+
.customButton {
|
|
428
|
+
text-transform: uppercase;
|
|
429
|
+
font-weight: 700;
|
|
430
|
+
}
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
```tsx
|
|
434
|
+
import { Button, Input } from '@webstrail/ui-library';
|
|
435
|
+
import styles from './Dashboard.module.css';
|
|
436
|
+
|
|
437
|
+
export function Dashboard() {
|
|
438
|
+
return (
|
|
439
|
+
<div className={styles.customCard}>
|
|
440
|
+
<Input label="Search" className={styles.customInput} />
|
|
441
|
+
<Button label="Search" className={styles.customButton} />
|
|
442
|
+
</div>
|
|
443
|
+
);
|
|
444
|
+
}
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
### Zero-Provider Standalone Usage
|
|
448
|
+
|
|
449
|
+
No `UIProvider` is needed. You can use any component directly:
|
|
450
|
+
|
|
451
|
+
```tsx
|
|
452
|
+
import { Button } from '@webstrail/ui-library';
|
|
453
|
+
|
|
454
|
+
export function Minimal() {
|
|
455
|
+
return <Button label="Click Me" />;
|
|
456
|
+
}
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
---
|
|
460
|
+
|
|
461
|
+
## Developer & Quality Scripts
|
|
462
|
+
|
|
463
|
+
| Command | Purpose |
|
|
464
|
+
| ----------------- | ------------------------------------------------------------------------------------------- |
|
|
465
|
+
| `yarn build` | Type-checks declaration files (`tsc -b`) and builds production distribution (`vite build`). |
|
|
466
|
+
| `yarn lint` | Runs modern ESLint flat config checking for TypeScript and React best practices. |
|
|
467
|
+
| `yarn lint:fix` | Automatically fixes supported ESLint errors. |
|
|
468
|
+
| `yarn format` | Formats all code files with Prettier. |
|
|
469
|
+
| `yarn type-check` | Performs strict TypeScript type checks with `tsc --noEmit`. |
|
|
470
|
+
| `yarn pack` | Packs distribution into a tarball (`webstrail-ui-library-v1.0.0.tgz`) for validation. |
|
|
471
|
+
|
|
472
|
+
---
|
|
473
|
+
|
|
474
|
+
## Package Distribution & Publishing
|
|
475
|
+
|
|
476
|
+
The `package.json` specifies standard distribution mappings:
|
|
477
|
+
|
|
478
|
+
```json
|
|
479
|
+
{
|
|
480
|
+
"name": "@webstrail/ui-library",
|
|
481
|
+
"version": "1.0.0",
|
|
482
|
+
"type": "module",
|
|
483
|
+
"main": "./dist/index.cjs",
|
|
484
|
+
"module": "./dist/index.js",
|
|
485
|
+
"types": "./dist/index.d.ts",
|
|
486
|
+
"style": "./dist/style.css",
|
|
487
|
+
"exports": {
|
|
488
|
+
".": {
|
|
489
|
+
"types": "./dist/index.d.ts",
|
|
490
|
+
"import": "./dist/index.js",
|
|
491
|
+
"require": "./dist/index.cjs"
|
|
492
|
+
},
|
|
493
|
+
"./style.css": "./dist/style.css"
|
|
494
|
+
},
|
|
495
|
+
"files": ["dist", "README.md", "LICENSE"],
|
|
496
|
+
"peerDependencies": {
|
|
497
|
+
"react": "^18.0.0 || ^19.0.0",
|
|
498
|
+
"react-dom": "^18.0.0 || ^19.0.0"
|
|
499
|
+
}
|
|
500
|
+
}
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
To publish to the NPM registry:
|
|
504
|
+
|
|
505
|
+
```bash
|
|
506
|
+
# 1. Run validations
|
|
507
|
+
yarn lint
|
|
508
|
+
yarn type-check
|
|
509
|
+
yarn build
|
|
510
|
+
|
|
511
|
+
# 2. Publish
|
|
512
|
+
npm publish --access public
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
---
|
|
516
|
+
|
|
517
|
+
## License
|
|
518
|
+
|
|
519
|
+
MIT © Webstrail
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { ButtonHTMLAttributes, ReactNode } from 'react';
|
|
2
|
+
import { BaseComponentProps, ComponentSize, ComponentVariant } from '../../types/common';
|
|
3
|
+
import { ButtonStyles } from '../../config/config.types';
|
|
4
|
+
export interface ButtonProps extends BaseComponentProps, Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'style' | 'className'> {
|
|
5
|
+
/**
|
|
6
|
+
* Visual variant style.
|
|
7
|
+
* @default 'primary'
|
|
8
|
+
*/
|
|
9
|
+
variant?: ComponentVariant;
|
|
10
|
+
/**
|
|
11
|
+
* Size of the button.
|
|
12
|
+
* @default 'medium'
|
|
13
|
+
*/
|
|
14
|
+
size?: ComponentSize;
|
|
15
|
+
/**
|
|
16
|
+
* Optional label text (children can also be used).
|
|
17
|
+
*/
|
|
18
|
+
label?: ReactNode;
|
|
19
|
+
/**
|
|
20
|
+
* Loading state. Replaces startIcon with an animated spinner and disables clicking.
|
|
21
|
+
* @default false
|
|
22
|
+
*/
|
|
23
|
+
loading?: boolean;
|
|
24
|
+
/**
|
|
25
|
+
* Text to display alongside the spinner when loading (optional).
|
|
26
|
+
*/
|
|
27
|
+
loadingText?: ReactNode;
|
|
28
|
+
/**
|
|
29
|
+
* Icon displayed before children or label.
|
|
30
|
+
*/
|
|
31
|
+
startIcon?: ReactNode;
|
|
32
|
+
/**
|
|
33
|
+
* Icon displayed after children or label.
|
|
34
|
+
*/
|
|
35
|
+
endIcon?: ReactNode;
|
|
36
|
+
/**
|
|
37
|
+
* Whether button expands to 100% of parent width.
|
|
38
|
+
* @default false
|
|
39
|
+
*/
|
|
40
|
+
fullWidth?: boolean;
|
|
41
|
+
/**
|
|
42
|
+
* Semantic styles override specific to this Button instance.
|
|
43
|
+
*/
|
|
44
|
+
styles?: ButtonStyles;
|
|
45
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import { InputHTMLAttributes, ReactNode, CSSProperties } from 'react';
|
|
2
|
+
import { BaseComponentProps } from '../../types/common';
|
|
3
|
+
import { CheckboxStyles } from '../../config/config.types';
|
|
4
|
+
export interface CheckboxSubElementClassNames {
|
|
5
|
+
container?: string;
|
|
6
|
+
box?: string;
|
|
7
|
+
icon?: string;
|
|
8
|
+
label?: string;
|
|
9
|
+
}
|
|
10
|
+
export interface CheckboxSubElementStyles {
|
|
11
|
+
container?: CSSProperties;
|
|
12
|
+
box?: CSSProperties;
|
|
13
|
+
icon?: CSSProperties;
|
|
14
|
+
label?: CSSProperties;
|
|
15
|
+
}
|
|
16
|
+
export interface CheckboxProps extends BaseComponentProps, Omit<InputHTMLAttributes<HTMLInputElement>, 'style' | 'className' | 'size' | 'type'> {
|
|
17
|
+
/**
|
|
18
|
+
* Optional label text or element.
|
|
19
|
+
*/
|
|
20
|
+
label?: ReactNode;
|
|
21
|
+
/**
|
|
22
|
+
* Whether the checkbox is in an indeterminate (partially checked) state.
|
|
23
|
+
* @default false
|
|
24
|
+
*/
|
|
25
|
+
indeterminate?: boolean;
|
|
26
|
+
/**
|
|
27
|
+
* Semantic styles override for this Checkbox instance.
|
|
28
|
+
*/
|
|
29
|
+
styles?: CheckboxStyles;
|
|
30
|
+
/**
|
|
31
|
+
* Class name overrides for sub-elements.
|
|
32
|
+
*/
|
|
33
|
+
slotClassNames?: CheckboxSubElementClassNames;
|
|
34
|
+
/**
|
|
35
|
+
* Style overrides for sub-elements.
|
|
36
|
+
*/
|
|
37
|
+
slotStyles?: CheckboxSubElementStyles;
|
|
38
|
+
}
|