@electroplix/components 0.3.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 (175) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/LICENSE +21 -0
  3. package/README.md +130 -516
  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.d.ts +1 -1
  9. package/dist/index.esm.js +8644 -7781
  10. package/dist/package.json +97 -0
  11. package/dist/src/components/blog/index.d.ts +5 -5
  12. package/dist/src/components/blog/index.d.ts.map +1 -1
  13. package/dist/src/components/buttons/index.d.ts +19 -15
  14. package/dist/src/components/buttons/index.d.ts.map +1 -1
  15. package/dist/src/components/content/BlockquoteTestimonial.d.ts +1 -1
  16. package/dist/src/components/content/BlockquoteTestimonial.d.ts.map +1 -1
  17. package/dist/src/components/content/CalloutBox.d.ts +4 -3
  18. package/dist/src/components/content/CalloutBox.d.ts.map +1 -1
  19. package/dist/src/components/content/HeadingSection.d.ts +2 -2
  20. package/dist/src/components/content/HeadingSection.d.ts.map +1 -1
  21. package/dist/src/components/content/InlineCodeText.d.ts +4 -3
  22. package/dist/src/components/content/InlineCodeText.d.ts.map +1 -1
  23. package/dist/src/components/content/ParagraphBlock.d.ts +5 -4
  24. package/dist/src/components/content/ParagraphBlock.d.ts.map +1 -1
  25. package/dist/src/components/content/RichMarkdown.d.ts +4 -3
  26. package/dist/src/components/content/RichMarkdown.d.ts.map +1 -1
  27. package/dist/src/components/content/TeamGrid.d.ts +1 -1
  28. package/dist/src/components/content/TeamGrid.d.ts.map +1 -1
  29. package/dist/src/components/content/index.d.ts +7 -7
  30. package/dist/src/components/content/index.d.ts.map +1 -1
  31. package/dist/src/components/data-display/Badge.d.ts +5 -4
  32. package/dist/src/components/data-display/Badge.d.ts.map +1 -1
  33. package/dist/src/components/data-display/BadgeGroup.d.ts +4 -3
  34. package/dist/src/components/data-display/BadgeGroup.d.ts.map +1 -1
  35. package/dist/src/components/data-display/BarChart.d.ts.map +1 -1
  36. package/dist/src/components/data-display/CalendarGrid.d.ts +1 -1
  37. package/dist/src/components/data-display/CalendarGrid.d.ts.map +1 -1
  38. package/dist/src/components/data-display/DataTable.d.ts +3 -3
  39. package/dist/src/components/data-display/DataTable.d.ts.map +1 -1
  40. package/dist/src/components/data-display/LineChart.d.ts.map +1 -1
  41. package/dist/src/components/data-display/PieChart.d.ts +1 -1
  42. package/dist/src/components/data-display/PieChart.d.ts.map +1 -1
  43. package/dist/src/components/data-display/ProgressBar.d.ts.map +1 -1
  44. package/dist/src/components/data-display/RatingStars.d.ts.map +1 -1
  45. package/dist/src/components/data-display/Sparkline.d.ts.map +1 -1
  46. package/dist/src/components/data-display/Timeline.d.ts +1 -1
  47. package/dist/src/components/data-display/Timeline.d.ts.map +1 -1
  48. package/dist/src/components/data-display/index.d.ts +11 -11
  49. package/dist/src/components/data-display/index.d.ts.map +1 -1
  50. package/dist/src/components/ecommerce/index.d.ts +10 -10
  51. package/dist/src/components/ecommerce/index.d.ts.map +1 -1
  52. package/dist/src/components/forms/AddressAutocomplete.d.ts +1 -1
  53. package/dist/src/components/forms/AddressAutocomplete.d.ts.map +1 -1
  54. package/dist/src/components/forms/Captcha.d.ts +2 -2
  55. package/dist/src/components/forms/Captcha.d.ts.map +1 -1
  56. package/dist/src/components/forms/ContactForm.d.ts +1 -1
  57. package/dist/src/components/forms/ContactForm.d.ts.map +1 -1
  58. package/dist/src/components/forms/DateTimePicker.d.ts +2 -2
  59. package/dist/src/components/forms/DateTimePicker.d.ts.map +1 -1
  60. package/dist/src/components/forms/FileUploader.d.ts +1 -1
  61. package/dist/src/components/forms/FileUploader.d.ts.map +1 -1
  62. package/dist/src/components/forms/FormShell.d.ts +1 -1
  63. package/dist/src/components/forms/FormShell.d.ts.map +1 -1
  64. package/dist/src/components/forms/InputField.d.ts +1 -1
  65. package/dist/src/components/forms/InputField.d.ts.map +1 -1
  66. package/dist/src/components/forms/MultiStepWizard.d.ts +1 -1
  67. package/dist/src/components/forms/MultiStepWizard.d.ts.map +1 -1
  68. package/dist/src/components/forms/NewsletterSignup.d.ts +1 -1
  69. package/dist/src/components/forms/NewsletterSignup.d.ts.map +1 -1
  70. package/dist/src/components/forms/RadioGroup.d.ts +1 -1
  71. package/dist/src/components/forms/RadioGroup.d.ts.map +1 -1
  72. package/dist/src/components/forms/SelectDropdown.d.ts +1 -1
  73. package/dist/src/components/forms/SelectDropdown.d.ts.map +1 -1
  74. package/dist/src/components/forms/TextAreaField.d.ts +1 -1
  75. package/dist/src/components/forms/TextAreaField.d.ts.map +1 -1
  76. package/dist/src/components/forms/ToggleSwitch.d.ts +1 -1
  77. package/dist/src/components/forms/ToggleSwitch.d.ts.map +1 -1
  78. package/dist/src/components/forms/ValidationWrapper.d.ts +1 -1
  79. package/dist/src/components/forms/ValidationWrapper.d.ts.map +1 -1
  80. package/dist/src/components/forms/index.d.ts +28 -28
  81. package/dist/src/components/forms/index.d.ts.map +1 -1
  82. package/dist/src/components/hero/CTAOverlayHero.d.ts +1 -1
  83. package/dist/src/components/hero/CTAOverlayHero.d.ts.map +1 -1
  84. package/dist/src/components/hero/CarouselHero.d.ts +1 -1
  85. package/dist/src/components/hero/CarouselHero.d.ts.map +1 -1
  86. package/dist/src/components/hero/HeroShell.d.ts +1 -1
  87. package/dist/src/components/hero/HeroShell.d.ts.map +1 -1
  88. package/dist/src/components/hero/PatternedHero.d.ts +2 -2
  89. package/dist/src/components/hero/PatternedHero.d.ts.map +1 -1
  90. package/dist/src/components/hero/SplitHero.d.ts +1 -1
  91. package/dist/src/components/hero/SplitHero.d.ts.map +1 -1
  92. package/dist/src/components/hero/StaticHero.d.ts +2 -2
  93. package/dist/src/components/hero/StaticHero.d.ts.map +1 -1
  94. package/dist/src/components/hero/VideoHeaderHero.d.ts +1 -1
  95. package/dist/src/components/hero/VideoHeaderHero.d.ts.map +1 -1
  96. package/dist/src/components/hero/index.d.ts +14 -14
  97. package/dist/src/components/hero/index.d.ts.map +1 -1
  98. package/dist/src/components/lists-cards/index.d.ts +5 -5
  99. package/dist/src/components/lists-cards/index.d.ts.map +1 -1
  100. package/dist/src/components/marketing/index.d.ts +10 -10
  101. package/dist/src/components/marketing/index.d.ts.map +1 -1
  102. package/dist/src/components/media/index.d.ts +12 -12
  103. package/dist/src/components/media/index.d.ts.map +1 -1
  104. package/dist/src/components/miscellaneous/index.d.ts +4 -4
  105. package/dist/src/components/miscellaneous/index.d.ts.map +1 -1
  106. package/dist/src/components/modals/index.d.ts +12 -12
  107. package/dist/src/components/modals/index.d.ts.map +1 -1
  108. package/dist/src/components/navigation/AnchorLinks.d.ts +2 -2
  109. package/dist/src/components/navigation/AnchorLinks.d.ts.map +1 -1
  110. package/dist/src/components/navigation/Breadcrumbs.d.ts +1 -1
  111. package/dist/src/components/navigation/Breadcrumbs.d.ts.map +1 -1
  112. package/dist/src/components/navigation/Footer.d.ts +1 -1
  113. package/dist/src/components/navigation/Footer.d.ts.map +1 -1
  114. package/dist/src/components/navigation/LanguageSelector.d.ts +1 -1
  115. package/dist/src/components/navigation/LanguageSelector.d.ts.map +1 -1
  116. package/dist/src/components/navigation/MegaMenu.d.ts +1 -1
  117. package/dist/src/components/navigation/MegaMenu.d.ts.map +1 -1
  118. package/dist/src/components/navigation/Pagination.d.ts.map +1 -1
  119. package/dist/src/components/navigation/PrimaryNav.d.ts.map +1 -1
  120. package/dist/src/components/navigation/SideDrawerNav.d.ts +2 -2
  121. package/dist/src/components/navigation/SideDrawerNav.d.ts.map +1 -1
  122. package/dist/src/components/navigation/SidebarMenu.d.ts +1 -1
  123. package/dist/src/components/navigation/SidebarMenu.d.ts.map +1 -1
  124. package/dist/src/components/navigation/Stepper.d.ts +1 -1
  125. package/dist/src/components/navigation/Stepper.d.ts.map +1 -1
  126. package/dist/src/components/navigation/Tabs.d.ts +2 -2
  127. package/dist/src/components/navigation/Tabs.d.ts.map +1 -1
  128. package/dist/src/components/navigation/index.d.ts +22 -22
  129. package/dist/src/components/navigation/index.d.ts.map +1 -1
  130. package/dist/src/components/onboarding/index.d.ts +9 -9
  131. package/dist/src/components/onboarding/index.d.ts.map +1 -1
  132. package/dist/src/components/search/index.d.ts +2 -2
  133. package/dist/src/components/search/index.d.ts.map +1 -1
  134. package/dist/src/components/site-identity/index.d.ts +4 -4
  135. package/dist/src/components/site-identity/index.d.ts.map +1 -1
  136. package/dist/src/components/social/index.d.ts +7 -7
  137. package/dist/src/components/social/index.d.ts.map +1 -1
  138. package/dist/src/components/user-accounts/index.d.ts +7 -7
  139. package/dist/src/components/user-accounts/index.d.ts.map +1 -1
  140. package/dist/src/core/config.d.ts +1 -1
  141. package/dist/src/core/config.d.ts.map +1 -1
  142. package/dist/src/core/icons.d.ts +1 -1
  143. package/dist/src/core/icons.d.ts.map +1 -1
  144. package/dist/src/core/index.d.ts +7 -7
  145. package/dist/src/core/index.d.ts.map +1 -1
  146. package/dist/src/core/provider.d.ts +20 -20
  147. package/dist/src/core/provider.d.ts.map +1 -1
  148. package/dist/src/core/types.d.ts +4 -4
  149. package/dist/src/core/types.d.ts.map +1 -1
  150. package/dist/src/core/utils.d.ts +1 -1
  151. package/dist/src/core/utils.d.ts.map +1 -1
  152. package/dist/src/index.d.ts +19 -19
  153. package/dist/src/index.d.ts.map +1 -1
  154. package/metadata/blog.json +807 -0
  155. package/metadata/buttons.json +2186 -0
  156. package/metadata/content.json +1152 -0
  157. package/metadata/data-display.json +822 -0
  158. package/metadata/ecommerce.json +1059 -0
  159. package/metadata/forms.json +2637 -0
  160. package/metadata/hero.json +1401 -0
  161. package/metadata/lists-cards.json +848 -0
  162. package/metadata/marketing.json +1235 -0
  163. package/metadata/media.json +800 -0
  164. package/metadata/miscellaneous.json +778 -0
  165. package/metadata/modals.json +954 -0
  166. package/metadata/navigation.json +1348 -0
  167. package/metadata/onboarding.json +615 -0
  168. package/metadata/search.json +559 -0
  169. package/metadata/site-identity.json +555 -0
  170. package/metadata/social.json +654 -0
  171. package/metadata/user-accounts.json +727 -0
  172. package/package.json +97 -85
  173. package/dist/README.md +0 -35
  174. package/dist/src/__tests__/test-utils.d.ts +0 -8
  175. package/dist/src/__tests__/test-utils.d.ts.map +0 -1
package/README.md CHANGED
@@ -1,516 +1,130 @@
1
- # @electroplix/components
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.
4
-
5
- [![npm](https://img.shields.io/npm/v/@electroplix/components)](https://www.npmjs.com/package/@electroplix/components)
6
-
7
- ---
8
-
9
- ## Table of Contents
10
-
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)
20
-
21
- ---
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
- ---
36
-
37
- ## Quick Start
38
-
39
- ### 1. Scaffold your project
40
-
41
- ```bash
42
- npx @electroplix/components init
43
- ```
44
-
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
51
-
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
- }
93
- ```
94
-
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";
104
-
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;
123
- ```
124
-
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`.
151
-
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
- />
185
- ```
186
-
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 |
414
-
415
- ---
416
-
417
- ## Icon System
418
-
419
- The package includes **113+ inline SVG icons** — zero external dependencies:
420
-
421
- ```tsx
422
- import { Icon, ICON_NAMES } from "@electroplix/components";
423
-
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`
430
-
431
- ---
432
-
433
- ## CLI
434
-
435
- ```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
447
- ```
448
-
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 |
474
-
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.
488
-
489
- ### Category hooks
490
-
491
- ```tsx
492
- import { useButtonTheme, useNavTheme } from "@electroplix/components";
493
-
494
- function MyCustomButton() {
495
- const t = useButtonTheme();
496
- return <button style={{ background: t.bgColor, color: t.textColor }}>Custom</button>;
497
- }
498
- ```
499
-
500
- ### `defineConfig(config)`
501
-
502
- Server-safe type-checked config helper. Import from `@electroplix/components/config`.
503
-
504
- ### `mergeTheme(target, ...sources)`
505
-
506
- Shallow-merge theme objects. `undefined` values in sources are skipped.
507
-
508
- ---
509
-
510
- ## Testing
511
-
512
- ```bash
513
- pnpm nx test @electroplix/components
514
- ```
515
-
516
- 19 test suites, 163 tests covering all 18 categories.
1
+ # Electroplix Design System
2
+
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
+
5
+ <!-- Badges: replace placeholders with your CI/status badges -->
6
+
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)]()
11
+
12
+ ## Overview
13
+
14
+ - Purpose: Provide a single, audited source of truth for UI components, design tokens, and frontend utilities used across Electroplix products.
15
+
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
+
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
28
+
29
+ ## Quick Start
30
+
31
+ 1. Install
32
+
33
+ ```bash
34
+ pnpm install
35
+ ```
36
+
37
+ 2. Build All
38
+
39
+ ```bash
40
+ pnpm run build
41
+ ```
42
+
43
+ 3. Run Showcase
44
+
45
+ ```bash
46
+ pnpm nx dev vite-showcase
47
+ ```
48
+
49
+ 4. Run Storybook
50
+
51
+ ```bash
52
+ pnpm nx storybook components
53
+ ```
54
+
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.
61
+
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.
67
+
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.
72
+
73
+ ## Accessibility
74
+ - Each component documents keyboard behaviors, focus management, and limitations.
75
+ - Automated a11y checks in CI.
76
+
77
+ ## Contributing
78
+ - PR process: Fork → feature branch → PR with tests and Storybook demo.
79
+ - All PRs require: unit tests, Storybook story, Green CI.
80
+
81
+ Developer setup
82
+
83
+ ```bash
84
+ pnpm install
85
+ pnpm nx run-many -t test
86
+ pnpm nx dev vite-showcase
87
+ ```
88
+
89
+ Test & release
90
+
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`)
95
+
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/*`.
100
+
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.
105
+
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.
110
+
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
117
+
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`.
122
+
123
+ ## Contact & Support
124
+ - Maintainers: github.com/adnan-the-coder
125
+ - Contribution welcome — link to Issues, Discussions, and PR templates.
126
+
127
+ ## License
128
+ - SPDX: MIT.
129
+
130
+ ---
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.