@electroplix/components 0.4.1 → 0.5.0-alpha.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 (173) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/LICENSE +21 -0
  3. package/README.md +88 -474
  4. package/SECURITY.md +19 -0
  5. package/cli.cjs +510 -485
  6. package/dist/config.d.ts +73 -0
  7. package/dist/config.esm.js +229 -0
  8. package/dist/index.esm.js +6531 -6668
  9. package/dist/package.json +97 -0
  10. package/dist/src/components/blog/index.d.ts +5 -5
  11. package/dist/src/components/blog/index.d.ts.map +1 -1
  12. package/dist/src/components/buttons/index.d.ts +38 -8
  13. package/dist/src/components/buttons/index.d.ts.map +1 -1
  14. package/dist/src/components/content/BlockquoteTestimonial.d.ts +1 -1
  15. package/dist/src/components/content/BlockquoteTestimonial.d.ts.map +1 -1
  16. package/dist/src/components/content/CalloutBox.d.ts +4 -3
  17. package/dist/src/components/content/CalloutBox.d.ts.map +1 -1
  18. package/dist/src/components/content/HeadingSection.d.ts +2 -2
  19. package/dist/src/components/content/HeadingSection.d.ts.map +1 -1
  20. package/dist/src/components/content/InlineCodeText.d.ts +4 -3
  21. package/dist/src/components/content/InlineCodeText.d.ts.map +1 -1
  22. package/dist/src/components/content/ParagraphBlock.d.ts +5 -4
  23. package/dist/src/components/content/ParagraphBlock.d.ts.map +1 -1
  24. package/dist/src/components/content/RichMarkdown.d.ts +4 -3
  25. package/dist/src/components/content/RichMarkdown.d.ts.map +1 -1
  26. package/dist/src/components/content/TeamGrid.d.ts.map +1 -1
  27. package/dist/src/components/content/index.d.ts +7 -7
  28. package/dist/src/components/content/index.d.ts.map +1 -1
  29. package/dist/src/components/data-display/Badge.d.ts +5 -4
  30. package/dist/src/components/data-display/Badge.d.ts.map +1 -1
  31. package/dist/src/components/data-display/BadgeGroup.d.ts +4 -3
  32. package/dist/src/components/data-display/BadgeGroup.d.ts.map +1 -1
  33. package/dist/src/components/data-display/BarChart.d.ts.map +1 -1
  34. package/dist/src/components/data-display/CalendarGrid.d.ts +1 -1
  35. package/dist/src/components/data-display/CalendarGrid.d.ts.map +1 -1
  36. package/dist/src/components/data-display/DataTable.d.ts +3 -3
  37. package/dist/src/components/data-display/DataTable.d.ts.map +1 -1
  38. package/dist/src/components/data-display/LineChart.d.ts.map +1 -1
  39. package/dist/src/components/data-display/PieChart.d.ts +1 -1
  40. package/dist/src/components/data-display/PieChart.d.ts.map +1 -1
  41. package/dist/src/components/data-display/ProgressBar.d.ts.map +1 -1
  42. package/dist/src/components/data-display/RatingStars.d.ts.map +1 -1
  43. package/dist/src/components/data-display/Sparkline.d.ts.map +1 -1
  44. package/dist/src/components/data-display/Timeline.d.ts +1 -1
  45. package/dist/src/components/data-display/Timeline.d.ts.map +1 -1
  46. package/dist/src/components/data-display/index.d.ts +11 -11
  47. package/dist/src/components/data-display/index.d.ts.map +1 -1
  48. package/dist/src/components/ecommerce/index.d.ts +8 -8
  49. package/dist/src/components/ecommerce/index.d.ts.map +1 -1
  50. package/dist/src/components/forms/AddressAutocomplete.d.ts +1 -1
  51. package/dist/src/components/forms/AddressAutocomplete.d.ts.map +1 -1
  52. package/dist/src/components/forms/Captcha.d.ts +2 -2
  53. package/dist/src/components/forms/Captcha.d.ts.map +1 -1
  54. package/dist/src/components/forms/ContactForm.d.ts +1 -1
  55. package/dist/src/components/forms/ContactForm.d.ts.map +1 -1
  56. package/dist/src/components/forms/DateTimePicker.d.ts +2 -2
  57. package/dist/src/components/forms/DateTimePicker.d.ts.map +1 -1
  58. package/dist/src/components/forms/FileUploader.d.ts +1 -1
  59. package/dist/src/components/forms/FileUploader.d.ts.map +1 -1
  60. package/dist/src/components/forms/FormShell.d.ts +1 -1
  61. package/dist/src/components/forms/FormShell.d.ts.map +1 -1
  62. package/dist/src/components/forms/InputField.d.ts +1 -1
  63. package/dist/src/components/forms/InputField.d.ts.map +1 -1
  64. package/dist/src/components/forms/MultiStepWizard.d.ts +1 -1
  65. package/dist/src/components/forms/MultiStepWizard.d.ts.map +1 -1
  66. package/dist/src/components/forms/NewsletterSignup.d.ts +1 -1
  67. package/dist/src/components/forms/NewsletterSignup.d.ts.map +1 -1
  68. package/dist/src/components/forms/RadioGroup.d.ts +1 -1
  69. package/dist/src/components/forms/RadioGroup.d.ts.map +1 -1
  70. package/dist/src/components/forms/SelectDropdown.d.ts +1 -1
  71. package/dist/src/components/forms/SelectDropdown.d.ts.map +1 -1
  72. package/dist/src/components/forms/TextAreaField.d.ts +1 -1
  73. package/dist/src/components/forms/TextAreaField.d.ts.map +1 -1
  74. package/dist/src/components/forms/ToggleSwitch.d.ts +1 -1
  75. package/dist/src/components/forms/ToggleSwitch.d.ts.map +1 -1
  76. package/dist/src/components/forms/ValidationWrapper.d.ts +1 -1
  77. package/dist/src/components/forms/ValidationWrapper.d.ts.map +1 -1
  78. package/dist/src/components/forms/index.d.ts +28 -28
  79. package/dist/src/components/forms/index.d.ts.map +1 -1
  80. package/dist/src/components/hero/CTAOverlayHero.d.ts +1 -1
  81. package/dist/src/components/hero/CTAOverlayHero.d.ts.map +1 -1
  82. package/dist/src/components/hero/CarouselHero.d.ts +1 -1
  83. package/dist/src/components/hero/CarouselHero.d.ts.map +1 -1
  84. package/dist/src/components/hero/HeroShell.d.ts +1 -1
  85. package/dist/src/components/hero/HeroShell.d.ts.map +1 -1
  86. package/dist/src/components/hero/PatternedHero.d.ts +2 -2
  87. package/dist/src/components/hero/PatternedHero.d.ts.map +1 -1
  88. package/dist/src/components/hero/SplitHero.d.ts +1 -1
  89. package/dist/src/components/hero/SplitHero.d.ts.map +1 -1
  90. package/dist/src/components/hero/StaticHero.d.ts +2 -2
  91. package/dist/src/components/hero/StaticHero.d.ts.map +1 -1
  92. package/dist/src/components/hero/VideoHeaderHero.d.ts +1 -1
  93. package/dist/src/components/hero/VideoHeaderHero.d.ts.map +1 -1
  94. package/dist/src/components/hero/index.d.ts +14 -14
  95. package/dist/src/components/hero/index.d.ts.map +1 -1
  96. package/dist/src/components/lists-cards/index.d.ts +7 -7
  97. package/dist/src/components/lists-cards/index.d.ts.map +1 -1
  98. package/dist/src/components/marketing/index.d.ts +5 -5
  99. package/dist/src/components/marketing/index.d.ts.map +1 -1
  100. package/dist/src/components/media/index.d.ts +7 -7
  101. package/dist/src/components/media/index.d.ts.map +1 -1
  102. package/dist/src/components/miscellaneous/index.d.ts +4 -4
  103. package/dist/src/components/miscellaneous/index.d.ts.map +1 -1
  104. package/dist/src/components/modals/index.d.ts +5 -5
  105. package/dist/src/components/modals/index.d.ts.map +1 -1
  106. package/dist/src/components/navigation/AnchorLinks.d.ts +2 -2
  107. package/dist/src/components/navigation/AnchorLinks.d.ts.map +1 -1
  108. package/dist/src/components/navigation/Breadcrumbs.d.ts +1 -1
  109. package/dist/src/components/navigation/Breadcrumbs.d.ts.map +1 -1
  110. package/dist/src/components/navigation/Footer.d.ts +1 -1
  111. package/dist/src/components/navigation/Footer.d.ts.map +1 -1
  112. package/dist/src/components/navigation/LanguageSelector.d.ts +1 -1
  113. package/dist/src/components/navigation/LanguageSelector.d.ts.map +1 -1
  114. package/dist/src/components/navigation/MegaMenu.d.ts +1 -1
  115. package/dist/src/components/navigation/MegaMenu.d.ts.map +1 -1
  116. package/dist/src/components/navigation/Pagination.d.ts.map +1 -1
  117. package/dist/src/components/navigation/PrimaryNav.d.ts.map +1 -1
  118. package/dist/src/components/navigation/SideDrawerNav.d.ts +2 -2
  119. package/dist/src/components/navigation/SideDrawerNav.d.ts.map +1 -1
  120. package/dist/src/components/navigation/SidebarMenu.d.ts +1 -1
  121. package/dist/src/components/navigation/SidebarMenu.d.ts.map +1 -1
  122. package/dist/src/components/navigation/Stepper.d.ts +1 -1
  123. package/dist/src/components/navigation/Stepper.d.ts.map +1 -1
  124. package/dist/src/components/navigation/Tabs.d.ts +2 -2
  125. package/dist/src/components/navigation/Tabs.d.ts.map +1 -1
  126. package/dist/src/components/navigation/index.d.ts +22 -22
  127. package/dist/src/components/navigation/index.d.ts.map +1 -1
  128. package/dist/src/components/onboarding/index.d.ts +7 -7
  129. package/dist/src/components/onboarding/index.d.ts.map +1 -1
  130. package/dist/src/components/search/index.d.ts +3 -3
  131. package/dist/src/components/search/index.d.ts.map +1 -1
  132. package/dist/src/components/site-identity/index.d.ts +5 -5
  133. package/dist/src/components/site-identity/index.d.ts.map +1 -1
  134. package/dist/src/components/social/index.d.ts +7 -7
  135. package/dist/src/components/social/index.d.ts.map +1 -1
  136. package/dist/src/components/user-accounts/index.d.ts +6 -6
  137. package/dist/src/components/user-accounts/index.d.ts.map +1 -1
  138. package/dist/src/core/config.d.ts +1 -1
  139. package/dist/src/core/config.d.ts.map +1 -1
  140. package/dist/src/core/icons.d.ts +1 -1
  141. package/dist/src/core/icons.d.ts.map +1 -1
  142. package/dist/src/core/index.d.ts +7 -7
  143. package/dist/src/core/index.d.ts.map +1 -1
  144. package/dist/src/core/provider.d.ts +20 -20
  145. package/dist/src/core/provider.d.ts.map +1 -1
  146. package/dist/src/core/types.d.ts +4 -4
  147. package/dist/src/core/types.d.ts.map +1 -1
  148. package/dist/src/core/utils.d.ts +1 -1
  149. package/dist/src/core/utils.d.ts.map +1 -1
  150. package/dist/src/index.d.ts +19 -19
  151. package/dist/src/index.d.ts.map +1 -1
  152. package/metadata/blog.json +807 -0
  153. package/metadata/buttons.json +2186 -0
  154. package/metadata/content.json +1152 -0
  155. package/metadata/data-display.json +822 -0
  156. package/metadata/ecommerce.json +1059 -0
  157. package/metadata/forms.json +2637 -0
  158. package/metadata/hero.json +1401 -0
  159. package/metadata/lists-cards.json +848 -0
  160. package/metadata/marketing.json +1235 -0
  161. package/metadata/media.json +800 -0
  162. package/metadata/miscellaneous.json +778 -0
  163. package/metadata/modals.json +954 -0
  164. package/metadata/navigation.json +1348 -0
  165. package/metadata/onboarding.json +615 -0
  166. package/metadata/search.json +559 -0
  167. package/metadata/site-identity.json +555 -0
  168. package/metadata/social.json +654 -0
  169. package/metadata/user-accounts.json +727 -0
  170. package/package.json +18 -6
  171. package/dist/README.md +0 -35
  172. package/dist/src/__tests__/test-utils.d.ts +0 -8
  173. package/dist/src/__tests__/test-utils.d.ts.map +0 -1
package/README.md CHANGED
@@ -1,516 +1,130 @@
1
- # @electroplix/components
1
+ # Electroplix Design System
2
2
 
3
- > Parametric, config-driven React UI components. **153 components** across **18 categories** — zero external CSS, zero icon dependencies, fully themeable via a single provider.
3
+ Electroplix Design System is a modular, production-grade collection of UI components, design tokens, utilities, and tooling to accelerate consistent frontend development across Electroplix applications. Built for reliability, accessibility, theming, and performance, this repository packages reusable components and libraries for consumption in NX monorepos and downstream applications.
4
4
 
5
- [![npm](https://img.shields.io/npm/v/@electroplix/components)](https://www.npmjs.com/package/@electroplix/components)
5
+ <!-- Badges: replace placeholders with your CI/status badges -->
6
6
 
7
- ---
7
+ [![Build Status](https://img.shields.io/badge/build-passing-brightgreen)]()
8
+ [![License](https://img.shields.io/badge/license-MIT-blue)]()
9
+ [![Latest Release](https://img.shields.io/badge/release-0.5.0--alpha.0-blue)]()
10
+ [![Vulnerabilities](https://img.shields.io/badge/vulnerabilities-none-brightgreen)]()
8
11
 
9
- ## Table of Contents
12
+ ## Overview
10
13
 
11
- - [Installation](#installation)
12
- - [Quick Start](#quick-start)
13
- - [Configuration](#configuration)
14
- - [Component Categories](#component-categories)
15
- - [Icon System](#icon-system)
16
- - [CLI](#cli)
17
- - [Utilities](#utilities)
18
- - [API Reference](#api-reference)
19
- - [Testing](#testing)
14
+ - Purpose: Provide a single, audited source of truth for UI components, design tokens, and frontend utilities used across Electroplix products.
20
15
 
21
- ---
16
+ ### Goals
17
+ - Consistency: Shared visual language and API patterns.
18
+ - Accessibility: WCAG-compliant components and accessible patterns.
19
+ - Performance: Lightweight builds and tree-shaking-friendly packages.
20
+ - Security: Dependency hygiene and security-first development.
21
+ - Reusability: Multi-package Nx-friendly structure for apps and micro-frontends.
22
22
 
23
- ## Installation
24
-
25
- ```bash
26
- npm install @electroplix/components
27
- # or
28
- pnpm add @electroplix/components
29
- # or
30
- yarn add @electroplix/components
31
- ```
32
-
33
- **Peer dependencies:** `react >=18.0.0` and `react-dom >=18.0.0`
34
-
35
- ---
23
+ ## Contents
24
+ - `/packages/components` — UI components (React 19)
25
+ - `/examples/vite-showcase` — Gallery app for component validation
26
+ - `/e2e/components-e2e` — Playwright end-to-end tests
27
+ - `/scripts` — Build, release, and audit helpers
36
28
 
37
29
  ## Quick Start
38
30
 
39
- ### 1. Scaffold your project
31
+ 1. Install
40
32
 
41
33
  ```bash
42
- npx @electroplix/components init
34
+ pnpm install
43
35
  ```
44
36
 
45
- This creates two files:
46
-
47
- - **`electroplix.config.ts`** — your global theme configuration
48
- - **`components/providers.tsx`** — a `"use client"` wrapper for the provider
49
-
50
- ### 2. Update your layout
37
+ 2. Build All
51
38
 
52
- Your root layout stays as a **Server Component** — import the client-side `Providers` wrapper:
53
-
54
- ```tsx
55
- // app/layout.tsx — Server Component (no "use client" needed here)
56
- import { Providers } from "../components/providers";
57
-
58
- export default function RootLayout({ children }: { children: React.ReactNode }) {
59
- return (
60
- <html>
61
- <body>
62
- <Providers>{children}</Providers>
63
- </body>
64
- </html>
65
- );
66
- }
67
- ```
68
-
69
- > **Why a separate `providers.tsx`?**
70
- > `ElectroplixProvider` uses React Context (`createContext`), which only works in Client Components.
71
- > By isolating it in a `"use client"` file, your layout stays a Server Component so metadata,
72
- > static content, and other server-only features continue to work.
73
-
74
- ### 3. Use components in client pages
75
-
76
- ```tsx
77
- "use client";
78
- import {
79
- PrimaryNav,
80
- StaticHero,
81
- PrimaryButton,
82
- } from "@electroplix/components";
83
-
84
- export default function HomePage() {
85
- return (
86
- <>
87
- <PrimaryNav logoText="MyApp" links={[{ label: "Home", href: "/" }]} />
88
- <StaticHero title="Welcome" subtitle="Build faster." ctaLabel="Get Started" />
89
- <PrimaryButton label="Click me" onClick={() => alert("Clicked!")} />
90
- </>
91
- );
92
- }
39
+ ```bash
40
+ pnpm run build
93
41
  ```
94
42
 
95
- ---
96
-
97
- ## Configuration
98
-
99
- The `electroplix.config.ts` file uses the server-safe `./config` entry point (no React, no `"use client"`):
100
-
101
- ```ts
102
- // electroplix.config.ts
103
- import { defineConfig } from "@electroplix/components/config";
43
+ 3. Run Showcase
104
44
 
105
- const config = defineConfig({
106
- // ── Global overrides (applied to ALL categories) ──────────
107
- accentColor: "#7C3AED",
108
- textColor: "#E5E7EB",
109
- bgColor: "#0b0b0c",
110
- borderColor: "rgba(255,255,255,0.14)",
111
- radius: 14,
112
- fontFamily: "Inter, system-ui, sans-serif",
113
-
114
- // ── Per-category overrides ────────────────────────────────
115
- navigation: { sticky: true, height: 64 },
116
- hero: { minH: 600 },
117
- buttons: { bgColor: "#e94560", radius: 12 },
118
- forms: { inputBg: "rgba(255,255,255,0.05)" },
119
- ecommerce: { accentColor: "#10B981" },
120
- });
121
-
122
- export default config;
45
+ ```bash
46
+ pnpm nx dev vite-showcase
123
47
  ```
124
48
 
125
- **How merging works:** Global `BaseTheme` props (like `accentColor`, `bgColor`) are spread into every category as a baseline. Per-category overrides take priority. Built-in defaults fill any gaps.
126
-
127
- ### Available config keys
128
-
129
- | Key | Theme Type | Category |
130
- |-----|-----------|----------|
131
- | `blog` | `BlogTheme` | Blog components |
132
- | `buttons` | `ButtonTheme` | Button components |
133
- | `content` | `ContentTheme` | Content components |
134
- | `dataDisplay` | `DataDisplayTheme` | Charts, tables, badges |
135
- | `ecommerce` | `EcommerceTheme` | Product cards, cart, checkout |
136
- | `forms` | `FormsTheme` | Form inputs and wizards |
137
- | `hero` | `HeroTheme` | Hero sections |
138
- | `listsCards` | `ListsCardsTheme` | Lists, cards, pricing |
139
- | `marketing` | `MarketingTheme` | Marketing blocks |
140
- | `media` | `MediaTheme` | Images, video, galleries |
141
- | `miscellaneous` | `MiscTheme` | Misc UI utilities |
142
- | `modals` | `ModalsTheme` | Modals, toasts, tooltips |
143
- | `navigation` | `NavigationTheme` | Navbars, tabs, menus |
144
- | `onboarding` | `OnboardingTheme` | Wizards, tours, FAQ |
145
- | `search` | `SearchTheme` | Search bars and results |
146
- | `siteIdentity` | `SiteIdentityTheme` | Logo, branding |
147
- | `social` | `SocialTheme` | Social sharing, login |
148
- | `userAccounts` | `UserAccountsTheme` | Auth forms, profile |
149
-
150
- **Global BaseTheme props** (set at root level): `bgColor`, `textColor`, `accentColor`, `borderColor`, `fontFamily`, `radius`, `spacing`, `headingSize`, `bodySize`, `fontWeight`, `lineHeight`, `letterSpacing`, `shadow`.
49
+ 4. Run Storybook
151
50
 
152
- ---
153
-
154
- ## Component Categories
155
-
156
- ### Navigation (10)
157
-
158
- | Component | Key Props | Description |
159
- |-----------|----------|-------------|
160
- | `PrimaryNav` | `logoText`, `links`, `showSearch`, `showCTA`, `sticky` | Main navigation bar |
161
- | `SidebarMenu` | `items`, `width` | Vertical sidebar navigation |
162
- | `SideDrawerNav` | `links`, `width`, `position` | Slide-out drawer navigation |
163
- | `MegaMenu` | `label`, `sections` | Dropdown mega menu |
164
- | `Tabs` | `tabs`, `defaultTab`, `orientation` | Tab navigation |
165
- | `Breadcrumbs` | `items`, `showHomeIcon` | Breadcrumb trail |
166
- | `Pagination` | `currentPage`, `totalPages`, `onPageChange` | Page navigation |
167
- | `Stepper` | `steps`, `currentStep`, `orientation` | Step indicator |
168
- | `AnchorLinks` | `items`, `orientation`, `offset` | In-page anchor navigation |
169
- | `LanguageSelector` | `languages`, `current`, `onChange` | Language picker dropdown |
170
-
171
- ```tsx
172
- <PrimaryNav
173
- logoText="Acme"
174
- links={[
175
- { label: "Products", href: "/products" },
176
- { label: "Pricing", href: "/pricing" },
177
- { label: "Docs", href: "/docs" },
178
- ]}
179
- showSearch
180
- showCTA
181
- ctaText="Sign Up"
182
- ctaHref="/signup"
183
- sticky
184
- />
51
+ ```bash
52
+ pnpm nx storybook components
185
53
  ```
186
54
 
187
- ### Hero (7)
188
-
189
- | Component | Key Props | Description |
190
- |-----------|----------|-------------|
191
- | `HeroShell` | `as`, `bgColor`, `minH`, `maxW`, `children` | Base hero wrapper |
192
- | `StaticHero` | `title`, `subtitle`, `ctaLabel`, `onCta` | Simple static hero |
193
- | `CarouselHero` | `slides`, `autoplay`, `intervalMs` | Auto-rotating hero slides |
194
- | `CTAOverlayHero` | `title`, `bgImage`, `overlay`, `form` | Hero with CTA overlay |
195
- | `PatternedHero` | `title`, `pattern`, `stats`, `badge` | Hero with decorative pattern |
196
- | `SplitHero` | `title`, `image`, `features`, `reverse` | Side-by-side hero |
197
- | `VideoHeaderHero` | `videoSrc`, `poster`, `title` | Full-width video hero |
198
-
199
- ### Buttons (10)
200
-
201
- | Component | Key Props | Description |
202
- |-----------|----------|-------------|
203
- | `PrimaryButton` | `label`, `onClick`, `icon`, `isLoading` | Filled primary button |
204
- | `SecondaryButton` | `label`, `onClick` | Outlined secondary button |
205
- | `TertiaryButton` | `label`, `onClick` | Ghost/text button |
206
- | `IconButton` | `icon`, `onClick`, `size` | Icon-only button |
207
- | `FloatingActionButton` | `icon`, `onClick`, `position`, `fixed` | FAB button |
208
- | `ButtonGroup` | `buttons`, `toggle`, `onChange` | Grouped/toggle buttons |
209
- | `LoadingButton` | `label`, `onClick`, `isLoading` | Button with spinner |
210
- | `ShareButton` | `url`, `label` | Native share / clipboard |
211
- | `DownloadButton` | `fileUrl`, `label` | File download button |
212
- | `PrintButton` | `label` | Print page button |
213
-
214
- ### Forms (14)
215
-
216
- | Component | Key Props | Description |
217
- |-----------|----------|-------------|
218
- | `FormShell` | `maxW`, `px`, `py`, `children` | Form layout wrapper |
219
- | `InputField` | `label`, `name`, `type`, `value`, `onChange`, `error` | Text/email/password input |
220
- | `TextAreaField` | `label`, `value`, `onChange`, `showPreview` | Multi-line text area with markdown preview |
221
- | `SelectDropdown` | `options`, `value`, `onChange`, `label` | Dropdown select |
222
- | `RadioGroup` | `options`, `value`, `onChange`, `label` | Radio button group |
223
- | `ToggleSwitch` | `label`, `checked`, `onChange` | On/off toggle |
224
- | `DateTimePicker` | `label`, `mode`, `value`, `onChange` | Date/time/datetime picker |
225
- | `FileUploader` | `onFiles`, `accept`, `maxSize` | Drag-and-drop file upload |
226
- | `ContactForm` | `title`, `onSubmit` | Pre-built contact form |
227
- | `NewsletterSignup` | `title`, `subtitle`, `onSubmit` | Email signup form |
228
- | `MultiStepWizard` | `steps`, `onFinish` | Multi-step form wizard |
229
- | `Captcha` | `mode`, `onVerify` | Text/math captcha |
230
- | `AddressAutocomplete` | `suggestions`, `onQuery`, `onSelect` | Address autocomplete |
231
- | `ValidationWrapper` | `errors`, `children`, `success` | Error/success message wrapper |
232
-
233
- ### Content (6)
234
-
235
- | Component | Key Props | Description |
236
- |-----------|----------|-------------|
237
- | `BlockquoteTestimonial` | `quote`, `author`, `role`, `avatarUrl` | Styled blockquote |
238
- | `CalloutBox` | `variant`, `title`, `message`, `dismissible` | Alert/callout box (info/warning/error/success) |
239
- | `HeadingSection` | `eyebrow`, `title`, `subtitle`, `align` | Section heading block |
240
- | `InlineCodeText` | `text`, `copyable` | Inline code with syntax highlighting |
241
- | `ParagraphBlock` | `paragraphs`, `showDropCap` | Formatted paragraph(s) |
242
- | `RichMarkdown` | `markdown`, `baseSize` | Mini markdown renderer |
243
-
244
- ### Data Display (11)
245
-
246
- | Component | Key Props | Description |
247
- |-----------|----------|-------------|
248
- | `Badge` | `children`, `tone`, `pill` | Status/label badge |
249
- | `BadgeGroup` | `items`, `tone`, `title` | Grouped badges |
250
- | `BarChart` | `data`, `labels`, `title`, `showGrid` | SVG bar chart |
251
- | `LineChart` | `data`, `labels`, `title`, `showGrid` | SVG line chart |
252
- | `PieChart` | `data`, `labels`, `title` | SVG pie chart |
253
- | `Sparkline` | `data`, `width`, `height` | Compact trend line |
254
- | `ProgressBar` | `value`, `showLabel`, `showTrend` | Progress indicator |
255
- | `RatingStars` | `value`, `outOf`, `interactive`, `onChange` | Star rating |
256
- | `DataTable` | `columns`, `rows`, `pageSize`, `searchable` | Sortable/paginated table |
257
- | `CalendarGrid` | `year`, `month`, `marks`, `onDateClick` | Month calendar grid |
258
- | `Timeline` | `items` | Vertical timeline |
259
-
260
- ### Ecommerce (10)
261
-
262
- | Component | Key Props | Description |
263
- |-----------|----------|-------------|
264
- | `ProductCard` | `product`, `currency`, `onAddToCart` | Product display card |
265
- | `ProductGrid` | `products`, `columns`, `onAddToCart` | Product card grid |
266
- | `ProductDetail` | `product`, `images`, `variants`, `onAddToCart` | Full product page |
267
- | `VariantSelector` | `groups`, `selected`, `onChange` | Size/color variant picker |
268
- | `CartDrawer` | `items`, `onQtyChange`, `onRemove`, `onCheckout` | Slide-out cart drawer |
269
- | `MiniCartPanel` | `items`, `currency`, `onCheckout` | Compact cart summary |
270
- | `OrderSummary` | `orderId`, `lines`, `total`, `currency` | Order receipt/summary |
271
- | `QuickAddButton` | `productId`, `label`, `onAdd` | Quick add-to-cart button |
272
- | `WishlistButton` | `productId`, `wishlisted`, `onToggle` | Heart wishlist toggle |
273
- | `PaymentButtons` | `methods`, `onPay` | Payment method buttons |
274
-
275
- ### Lists & Cards (8)
276
-
277
- | Component | Key Props | Description |
278
- |-----------|----------|-------------|
279
- | `BlockShell` | `maxW`, `children` | Section wrapper |
280
- | `Accordion` | `items`, `allowMultiple` | Expandable accordion |
281
- | `GenericList` | `items`, `title` | Simple labeled list |
282
- | `FeatureGrid` | `items`, `columns`, `title` | Feature card grid |
283
- | `ItemCardGrid` | `items`, `columns`, `onItemClick` | Clickable card grid |
284
- | `PricingTable` | `plans`, `onSelect` | Pricing tier comparison |
285
- | `SortableTable` | `columns`, `rows`, `caption` | Sortable data table |
286
- | `LCTimeline` | `items` | Lists & Cards timeline |
287
-
288
- ### Marketing (8)
289
-
290
- | Component | Key Props | Description |
291
- |-----------|----------|-------------|
292
- | `ComparisonTable` | `plans`, `features`, `onSelect` | Feature comparison table |
293
- | `CountdownTimer` | `targetDate`, `label`, `onExpire` | Countdown to date |
294
- | `FeatureHighlights` | `items`, `columns`, `title` | Feature showcase grid |
295
- | `LeadMagnetGate` | `title`, `description`, `onSubmit`, `children` | Gated content form |
296
- | `MarketingHeroBlock` | `headline`, `subheadline`, `ctaLabel` | Marketing hero section |
297
- | `PromoPopup` | `title`, `message`, `ctaLabel`, `isOpen` | Promotional popup |
298
- | `TestimonialsCarousel` | `testimonials`, `autoPlay` | Rotating testimonials |
299
- | `TrustBadges` | `badges`, `title` | Trust/certification badges |
300
-
301
- ### Media (11)
302
-
303
- | Component | Key Props | Description |
304
- |-----------|----------|-------------|
305
- | `MediaShell` | `maxW`, `children` | Media section wrapper |
306
- | `ResponsiveVideo` | `src`, `poster`, `aspectRatio` | Responsive video player |
307
- | `AudioEmbed` | `src`, `title`, `showWaveform` | Audio player |
308
- | `AvatarProfile` | `src`, `name`, `size`, `badge` | User avatar |
309
- | `IconGrid` | `icons`, `columns` | Icon showcase grid |
310
- | `ImageGallery` | `items`, `columns`, `onSelect` | Image gallery |
311
- | `LightboxGallery` | `items`, `columns` | Gallery with lightbox |
312
- | `MasonryGrid` | `items`, `columns` | Masonry layout |
313
- | `PolaroidImage` | `src`, `caption`, `rotation` | Polaroid-style image |
314
- | `LottieOrSVG` | `type`, `src`, `width`, `height` | Lottie/SVG renderer |
315
- | `ImageCropperUploader` | `onUpload`, `accept`, `maxSizeMB` | Image upload with preview |
316
-
317
- ### Miscellaneous (8)
318
-
319
- | Component | Key Props | Description |
320
- |-----------|----------|-------------|
321
- | `CookieConsent` | `message`, `onAccept`, `onDecline`, `position` | Cookie consent bar |
322
- | `ScrollProgressBar` | `color`, `height` | Scroll progress indicator |
323
- | `ThemeToggle` | `isDark`, `onToggle` | Dark/light mode toggle |
324
- | `EmptyState` | `icon`, `title`, `description`, `ctaLabel` | Empty state placeholder |
325
- | `AppInstallBanner` | `title`, `iosUrl`, `androidUrl` | App install CTA |
326
- | `DownloadBlock` | `fileName`, `fileSize`, `href` | File download block |
327
- | `InlineCode` | `children`, `copyable` | Inline code snippet |
328
- | `RSSFeed` | `items`, `title` | RSS feed display |
329
-
330
- ### Modals (9)
331
-
332
- | Component | Key Props | Description |
333
- |-----------|----------|-------------|
334
- | `OverlayBase` | `isOpen`, `onClose`, `children`, `position` | Base overlay wrapper |
335
- | `GenericModal` | `isOpen`, `title`, `onClose`, `children` | Generic modal dialog |
336
- | `ConfirmDialog` | `isOpen`, `title`, `message`, `onConfirm` | Confirmation dialog |
337
- | `FormDialog` | `isOpen`, `title`, `onSubmit`, `children` | Modal with form |
338
- | `LoadingOverlay` | `isOpen`, `message` | Full-screen loading |
339
- | `Tooltip` | `text`, `position`, `children` | Hover tooltip |
340
- | `ToastBanners` | `toasts`, `onDismiss`, `position` | Toast notifications |
341
- | `CookieNotice` | `isOpen`, `onAccept`, `onDecline` | Cookie consent modal |
342
- | `WelcomePopup` | `isOpen`, `title`, `message`, `onCta` | Welcome popup |
343
-
344
- ### Onboarding (6)
345
-
346
- | Component | Key Props | Description |
347
- |-----------|----------|-------------|
348
- | `FAQAccordion` | `items`, `title`, `allowMultiple` | FAQ expandable list |
349
- | `OnboardingWizard` | `steps`, `onComplete` | Step-by-step onboarding |
350
- | `ProductTour` | `steps`, `isOpen`, `onComplete` | Guided product tour |
351
- | `TooltipHelp` | `text`, `position` | Help tooltip with icon |
352
- | `SupportChat` | `messages`, `onSend`, `title` | Chat-like support widget |
353
- | `ContactSupportBlock` | `email`, `phone`, `title` | Support contact block |
354
-
355
- ### Search (6)
356
-
357
- | Component | Key Props | Description |
358
- |-----------|----------|-------------|
359
- | `SiteSearchBar` | `placeholder`, `onSearch`, `autoFocus` | Search input bar |
360
- | `AutoSuggest` | `suggestions`, `onSelect`, `onQueryChange` | Autocomplete search |
361
- | `FacetFilters` | `facets`, `selected`, `onChange` | Faceted filter sidebar |
362
- | `SearchResultCard` | `item`, `onClick` | Individual search result |
363
- | `SearchResults` | `items`, `query`, `loading` | Search results list |
364
- | `SearchEmptyState` | `query`, `title` | No results placeholder |
365
-
366
- ### Site Identity (6)
367
-
368
- | Component | Key Props | Description |
369
- |-----------|----------|-------------|
370
- | `LogoDisplay` | `src`, `alt`, `width`, `href` | Logo image display |
371
- | `AnimatedBrandMark` | `text`, `fontSize`, `accentColor` | Animated brand text |
372
- | `Taglines` | `lines`, `rotate`, `interval` | Rotating taglines |
373
- | `BrandingShell` | `logoSrc`, `brandName`, `tagline` | Brand identity wrapper |
374
- | `BrandIconGrid` | `icons`, `columns` | Brand icon showcase |
375
- | `FaviconUploader` | `onUpload`, `currentSrc` | Favicon upload with preview |
376
-
377
- ### Social (7)
378
-
379
- | Component | Key Props | Description |
380
- |-----------|----------|-------------|
381
- | `SocialShareBar` | `url`, `title`, `networks` | Social sharing buttons |
382
- | `SocialLoginButtons` | `providers`, `onLogin` | OAuth login buttons |
383
- | `SocialEmbed` | `type`, `url`, `width` | Social media embed |
384
- | `FollowLike` | `isFollowed`, `followerCount`, `onFollow` | Follow/like toggle |
385
- | `ReactionsBar` | `reactions`, `onReact` | Emoji reactions bar |
386
- | `CommentsBox` | `comments`, `onSubmit` | Comment section |
387
- | `ReviewsForm` | `onSubmit` | Rating + review form |
388
-
389
- ### User Accounts (7)
390
-
391
- | Component | Key Props | Description |
392
- |-----------|----------|-------------|
393
- | `AuthForm` | `mode`, `onSubmit`, `loading`, `error` | Login/signup form |
394
- | `PasswordReset` | `onSubmit`, `loading`, `success` | Password reset form |
395
- | `MultiFactorAuthInput` | `length`, `onComplete`, `error` | MFA code input |
396
- | `ProfileOverview` | `name`, `email`, `avatar`, `stats` | Profile display card |
397
- | `ProfileSettings` | `name`, `email`, `onSave` | Profile edit form |
398
- | `AccountSettings` | `sections`, `title` | Account settings sections |
399
- | `RoleBadge` | `role`, `variant`, `color` | User role badge |
400
-
401
- ### Blog (9)
402
-
403
- | Component | Key Props | Description |
404
- |-----------|----------|-------------|
405
- | `BlogCard` | `post`, `onClick`, `variant` | Blog post card (vertical/horizontal/minimal) |
406
- | `AuthorByline` | `name`, `avatar`, `bio`, `date` | Author info block |
407
- | `TagList` | `tags`, `onTagClick`, `activeTag` | Tag/category list |
408
- | `BlogBadge` | `label`, `color` | Blog category badge |
409
- | `ReadingBar` | `color`, `height`, `containerRef` | Reading progress bar |
410
- | `ArticleRenderer` | `html`, `maxW` | HTML article renderer |
411
- | `RelatedPosts` | `posts`, `title`, `onPostClick` | Related posts grid |
412
- | `ArchiveList` | `groups`, `onPostClick` | Grouped archive list |
413
- | `CommentsSection` | `comments`, `onSubmit` | Threaded comments |
55
+ ## Core Principles
56
+ - API Stability: Semantic versioning and clear deprecation policy.
57
+ - Accessibility: Keyboard interactions, focus management, and ARIA where required.
58
+ - Theming & Tokens: All visual values come from tokens; runtime theme overrides supported.
59
+ - Small Surface Area: Components are composable and unopinionated where appropriate.
60
+ - Test Coverage: Unit tests, visual regression tests, and accessibility audits.
414
61
 
415
- ---
416
-
417
- ## Icon System
418
-
419
- The package includes **113+ inline SVG icons** — zero external dependencies:
62
+ ## Usage & Conventions
63
+ - Folder layout: each package follows `src`, `__tests__`, `stories`/`examples`, `package.json`.
64
+ - Export policy: small default bundle + named exports for tree-shaking.
65
+ - Linting & Formatting: **Biome** at workspace root.
66
+ - Types: Fully typed with TypeScript; builds emit declaration files.
420
67
 
421
- ```tsx
422
- import { Icon, ICON_NAMES } from "@electroplix/components";
68
+ ## Security & Auditing
69
+ - Regular dependency scans via Dependabot and automated security checks in CI.
70
+ - Releases follow the **Nx Release** workflow with conventional commits.
71
+ - Maintain `CHANGELOG.md` for historical traceability.
423
72
 
424
- <Icon name="search" size={24} color="#8B5CF6" />
425
- <Icon name="shopping-cart" size={20} />
426
- <Icon name="heart" />
427
- ```
428
-
429
- All available icon names: `activity`, `alert-circle`, `alert-triangle`, `align-left`, `arrow-left`, `arrow-right`, `arrow-up-right`, `award`, `bar-chart`, `bar-chart-3`, `bell`, `bot`, `building-2`, `calendar`, `camera`, `check`, `check-circle`, `check-circle-2`, `chevron-down`, `chevron-left`, `chevron-right`, `chevrons-left`, `chevrons-right`, `chevron-up`, `circle`, `circle-dot`, `clipboard`, `clock`, `code`, `command`, `cookie`, `copy`, `corner-down-left`, `credit-card`, `download`, `edit-2`, `external-link`, `eye`, `eye-off`, `file`, `file-code`, `file-down`, `file-text`, `filter`, `gift`, `github`, `globe`, `grid-3x3`, `headphones`, `heart`, `help-circle`, `home`, `image`, `inbox`, `info`, `layout-grid`, `link-2`, `list`, `list-checks`, `loader-2`, `lock`, `mail`, `map-pin`, `menu`, `message-circle`, `message-square`, `minus`, `moon`, `more-horizontal`, `more-vertical`, `music`, `package`, `palette`, `paperclip`, `phone`, `pie-chart`, `play`, `plus`, `printer`, `quote`, `receipt`, `refresh-cw`, `rocket`, `rss`, `scale`, `search`, `search-code`, `search-x`, `send`, `settings`, `share-2`, `shield`, `shield-check`, `shopping-bag`, `shopping-cart`, `smartphone`, `sparkles`, `star`, `sun`, `table`, `tag`, `toggle-left`, `toggle-right`, `trash`, `trash-2`, `trending-down`, `trending-up`, `truck`, `type`, `upload`, `user`, `user-plus`, `verified`, `volume-2`, `wallet`, `x`, `x-circle`, `zap`, `zoom-in`
73
+ ## Accessibility
74
+ - Each component documents keyboard behaviors, focus management, and limitations.
75
+ - Automated a11y checks in CI.
430
76
 
431
- ---
77
+ ## Contributing
78
+ - PR process: Fork → feature branch → PR with tests and Storybook demo.
79
+ - All PRs require: unit tests, Storybook story, Green CI.
432
80
 
433
- ## CLI
81
+ Developer setup
434
82
 
435
83
  ```bash
436
- # Scaffold config + providers
437
- npx @electroplix/components init
438
-
439
- # Show all components in a category
440
- npx @electroplix/components add navigation
441
-
442
- # Show import instructions for a single component
443
- npx @electroplix/components add PrimaryNav
444
-
445
- # Browse all 153 components with tree view
446
- npx @electroplix/components list
84
+ pnpm install
85
+ pnpm nx run-many -t test
86
+ pnpm nx dev vite-showcase
447
87
  ```
448
88
 
449
- The `add` command accepts both **component names** (`PrimaryNav`, `BlogCard`) and **category names** (`navigation`, `data-display`, `social`).
450
-
451
- ---
452
-
453
- ## Utilities
454
-
455
- Exported utility functions and hooks:
456
-
457
- | Export | Type | Description |
458
- |--------|------|-------------|
459
- | `sx(...styles)` | Function | Merge style objects |
460
- | `cn(...classes)` | Function | Merge class names |
461
- | `money(amount, currency)` | Function | Format currency |
462
- | `truncate(text, length)` | Function | Truncate text with ellipsis |
463
- | `timeAgo(date)` | Function | Relative time string |
464
- | `useFocusTrap(ref)` | Hook | Trap keyboard focus inside element |
465
- | `useClickOutside(ref, cb)` | Hook | Detect clicks outside element |
466
- | `useMediaQuery(query)` | Hook | Responsive media query |
467
- | `useDebounce(value, ms)` | Hook | Debounce a value |
468
- | `validate(value, rules)` | Function | Run validation rules |
469
- | `emailRule`, `requiredRule` | Rule | Pre-built validation rules |
470
- | `minLengthRule(n)`, `maxLengthRule(n)` | Rule factory | Length validators |
471
- | `baseButtonStyle(opts)` | Function | Base button CSS |
472
- | `inputStyle(opts)` | Function | Base input CSS |
473
- | `labelStyle(opts)` | Function | Base label CSS |
89
+ Test & release
474
90
 
475
- ---
476
-
477
- ## API Reference
478
-
479
- ### `ElectroplixProvider`
480
-
481
- ```tsx
482
- <ElectroplixProvider config={myConfig}>
483
- {children}
484
- </ElectroplixProvider>
485
- ```
486
-
487
- - **`config`** — `Partial<ElectroplixConfig> | undefined` — optional theme overrides. Supports both root-level `BaseTheme` props (global) and per-category objects.
91
+ - Tests: `pnpm nx test`
92
+ - Lint: `pnpm nx lint`
93
+ - Build: `pnpm nx build`
94
+ - Release: `pnpm run release` (recommended tools: `changesets` or `standard-version`)
488
95
 
489
- ### Category hooks
96
+ ## Versioning & Release
97
+ - Semantic Versioning (MAJOR.MINOR.PATCH).
98
+ - Automated changelog generation with `changesets` or `standard-version`.
99
+ - Releases signed and published to npm under `@electroplix/*`.
490
100
 
491
- ```tsx
492
- import { useButtonTheme, useNavTheme } from "@electroplix/components";
101
+ ## Governance & Licensing
102
+ - License: MIT (adjust if necessary).
103
+ - Maintainers: list core team and escalation path in `MAINTAINERS.md`.
104
+ - Security policy: include `SECURITY.md` with responsible disclosure process.
493
105
 
494
- function MyCustomButton() {
495
- const t = useButtonTheme();
496
- return <button style={{ background: t.bgColor, color: t.textColor }}>Custom</button>;
497
- }
498
- ```
106
+ ## Roadmap
107
+ - **v1**: Core components, tokens, CI security pipeline.
108
+ - **v2**: Runtime design tokens, multi-theme support, component composition utilities.
109
+ - **v3**: Cross-framework adapters (Vue, Svelte) and enhanced visual regression testing.
499
110
 
500
- ### `defineConfig(config)`
111
+ ## Examples & Recipes
112
+ Point to `/examples` for concrete pages showcasing:
113
+ - Theming and token overrides
114
+ - Form patterns and validation
115
+ - Modal & focus-trap best practices
116
+ - Performance tips and bundle analysis
501
117
 
502
- Server-safe type-checked config helper. Import from `@electroplix/components/config`.
118
+ ## FAQ
119
+ - How to upgrade: See migration guides and deprecation timeline in `docs/`.
120
+ - How to report vulnerabilities: See `SECURITY.md` for disclosure steps.
121
+ - Support: open an issue or discussion, or contact maintainers listed in `MAINTAINERS.md`.
503
122
 
504
- ### `mergeTheme(target, ...sources)`
123
+ ## Contact & Support
124
+ - Maintainers: github.com/adnan-the-coder
125
+ - Contribution welcome — link to Issues, Discussions, and PR templates.
505
126
 
506
- Shallow-merge theme objects. `undefined` values in sources are skipped.
127
+ ## License
128
+ - SPDX: MIT.
507
129
 
508
130
  ---
509
-
510
- ## Testing
511
-
512
- ```bash
513
- pnpm nx test @electroplix/components
514
- ```
515
-
516
- 19 test suites, 163 tests covering all 18 categories.
package/SECURITY.md ADDED
@@ -0,0 +1,19 @@
1
+ # Security Policy
2
+
3
+ ## Supported Versions
4
+
5
+ | Version | Supported |
6
+ | ------- | ------------------ |
7
+ | 0.5.x | :white_check_mark: |
8
+ | < 0.5 | :x: |
9
+
10
+ ## Reporting a Vulnerability
11
+
12
+ We take the security of our project seriously. If you believe you have found a security vulnerability in the Electroplix Design System, please report it to us by emailing security@electroplix.com.
13
+
14
+ Please include:
15
+ - A description of the issue
16
+ - Steps to reproduce
17
+ - Potential impact
18
+
19
+ We will respond within 48 hours and provide updates throughout the resolution process.