@webstrail/ui-library 1.0.0 → 1.0.2

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