@webstrail/ui-library 0.0.0-stage → 1.0.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 (47) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +524 -3
  3. package/dist/components/Button/Button.d.ts +2 -0
  4. package/dist/components/Button/Button.types.d.ts +45 -0
  5. package/dist/components/Button/index.d.ts +2 -0
  6. package/dist/components/Checkbox/Checkbox.d.ts +2 -0
  7. package/dist/components/Checkbox/Checkbox.types.d.ts +38 -0
  8. package/dist/components/Checkbox/index.d.ts +2 -0
  9. package/dist/components/Input/Input.d.ts +2 -0
  10. package/dist/components/Input/Input.types.d.ts +87 -0
  11. package/dist/components/Input/index.d.ts +2 -0
  12. package/dist/components/Radio/Radio.d.ts +2 -0
  13. package/dist/components/Radio/Radio.types.d.ts +119 -0
  14. package/dist/components/Radio/RadioGroup.d.ts +2 -0
  15. package/dist/components/Radio/RadioGroupContext.d.ts +13 -0
  16. package/dist/components/Radio/index.d.ts +4 -0
  17. package/dist/components/Select/Select.d.ts +2 -0
  18. package/dist/components/Select/Select.types.d.ts +100 -0
  19. package/dist/components/Select/index.d.ts +2 -0
  20. package/dist/components/Switch/Switch.d.ts +2 -0
  21. package/dist/components/Switch/Switch.types.d.ts +82 -0
  22. package/dist/components/Switch/index.d.ts +2 -0
  23. package/dist/components/Textarea/Textarea.d.ts +2 -0
  24. package/dist/components/Textarea/Textarea.types.d.ts +61 -0
  25. package/dist/components/Textarea/index.d.ts +2 -0
  26. package/dist/components/index.d.ts +14 -0
  27. package/dist/config/config.types.d.ts +232 -0
  28. package/dist/config/defaultConfig.d.ts +2 -0
  29. package/dist/config/mergeConfig.d.ts +28 -0
  30. package/dist/context/UIContext.d.ts +6 -0
  31. package/dist/context/index.d.ts +1 -0
  32. package/dist/hooks/index.d.ts +3 -0
  33. package/dist/hooks/useComponentStyles.d.ts +26 -0
  34. package/dist/hooks/useUI.d.ts +6 -0
  35. package/dist/index.cjs +2 -0
  36. package/dist/index.cjs.map +1 -0
  37. package/dist/index.d.ts +25 -0
  38. package/dist/index.js +1577 -0
  39. package/dist/index.js.map +1 -0
  40. package/dist/providers/UIProvider.d.ts +20 -0
  41. package/dist/providers/index.d.ts +2 -0
  42. package/dist/style.css +1 -0
  43. package/dist/types/common.d.ts +41 -0
  44. package/dist/types/index.d.ts +1 -0
  45. package/dist/utils/classNames.d.ts +11 -0
  46. package/dist/utils/resolveStyles.d.ts +28 -0
  47. package/package.json +104 -6
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,524 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ -->
@@ -0,0 +1,2 @@
1
+ import { ButtonProps } from './Button.types';
2
+ export declare const Button: import('react').ForwardRefExoticComponent<ButtonProps & import('react').RefAttributes<HTMLButtonElement>>;
@@ -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,2 @@
1
+ export { Button } from './Button';
2
+ export type { ButtonProps } from './Button.types';
@@ -0,0 +1,2 @@
1
+ import { CheckboxProps } from './Checkbox.types';
2
+ export declare const Checkbox: import('react').ForwardRefExoticComponent<CheckboxProps & import('react').RefAttributes<HTMLInputElement>>;
@@ -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
+ }
@@ -0,0 +1,2 @@
1
+ export { Checkbox } from './Checkbox';
2
+ export type { CheckboxProps, CheckboxSubElementClassNames, CheckboxSubElementStyles, } from './Checkbox.types';
@@ -0,0 +1,2 @@
1
+ import { InputProps } from './Input.types';
2
+ export declare const Input: import('react').ForwardRefExoticComponent<InputProps & import('react').RefAttributes<HTMLInputElement>>;