npm - @electroplix/components - Versions diffs - 0.2.0 → 0.2.1 - Mend

@electroplix/components 0.2.0 → 0.2.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 (80) hide show

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # @electroplix/components
-> Parametric, config-driven React UI components. **~154 components** across **18 categories** — zero external CSS, zero icon dependencies, fully themeable via a single provider.
+> Parametric, config-driven React UI components. **153 components** across **18 categories** — zero external CSS, zero icon dependencies, fully themeable via a single provider.
 [![npm](https://img.shields.io/npm/v/@electroplix/components)](https://www.npmjs.com/package/@electroplix/components)
@@ -36,27 +36,42 @@ yarn add @electroplix/components
 ## Quick Start
-### 1. Wrap your app with the provider
+### 1. Scaffold your project
+```bash
+npx @electroplix/components init
+```
+This creates two files:
+- **`electroplix.config.ts`** — your global theme configuration
+- **`components/providers.tsx`** — a `"use client"` wrapper for the provider
+### 2. Update your layout
+Your root layout stays as a **Server Component** — import the client-side `Providers` wrapper:
 ```tsx
-// app/layout.tsx (Next.js App Router)
-import { ElectroplixProvider } from "@electroplix/components";
-import config from "./electroplix.config";
+// app/layout.tsx — Server Component (no "use client" needed here)
+import { Providers } from "../components/providers";
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html>
       <body>
-        <ElectroplixProvider config={config}>
-          {children}
-        </ElectroplixProvider>
+        <Providers>{children}</Providers>
       </body>
     </html>
   );
 }
 ```
-### 2. Use components anywhere
+> **Why a separate `providers.tsx`?**
+> `ElectroplixProvider` uses React Context (`createContext`), which only works in Client Components.
+> By isolating it in a `"use client"` file, your layout stays a Server Component so metadata,
+> static content, and other server-only features continue to work.
+### 3. Use components in client pages
 ```tsx
 "use client";
@@ -64,8 +79,6 @@ import {
   PrimaryNav,
   StaticHero,
   PrimaryButton,
-  ContactForm,
-  BlogCard,
 } from "@electroplix/components";
 export default function HomePage() {
@@ -83,36 +96,34 @@ export default function HomePage() {
 ## Configuration
-Create an `electroplix.config.ts` file using the server-safe `./config` entry:
+The `electroplix.config.ts` file uses the server-safe `./config` entry point (no React, no `"use client"`):
 ```ts
 // electroplix.config.ts
 import { defineConfig } from "@electroplix/components/config";
-export default defineConfig({
-  navigation: {
-    bgColor: "#1a1a2e",
-    accentColor: "#e94560",
-    sticky: true,
-    height: 64,
-  },
-  buttons: {
-    bgColor: "#e94560",
-    textColor: "#ffffff",
-    radius: 12,
-  },
-  hero: {
-    bgColor: "#16213e",
-    minH: 600,
-  },
-  forms: {
-    inputBg: "rgba(255,255,255,0.05)",
-    radius: 8,
-  },
-  // ... configure any of the 18 categories
+const config = defineConfig({
+  // ── Global overrides (applied to ALL categories) ──────────
+  accentColor: "#7C3AED",
+  textColor: "#E5E7EB",
+  bgColor: "#0b0b0c",
+  borderColor: "rgba(255,255,255,0.14)",
+  radius: 14,
+  fontFamily: "Inter, system-ui, sans-serif",
+  // ── Per-category overrides ────────────────────────────────
+  navigation: { sticky: true, height: 64 },
+  hero:       { minH: 600 },
+  buttons:    { bgColor: "#e94560", radius: 12 },
+  forms:      { inputBg: "rgba(255,255,255,0.05)" },
+  ecommerce:  { accentColor: "#10B981" },
 });
+export default config;
 ```
+**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.
 ### Available config keys
 | Key | Theme Type | Category |
@@ -136,7 +147,7 @@ export default defineConfig({
 | `social` | `SocialTheme` | Social sharing, login |
 | `userAccounts` | `UserAccountsTheme` | Auth forms, profile |
-Every theme extends `BaseTheme` which provides: `bgColor`, `textColor`, `accentColor`, `borderColor`, `fontFamily`, `radius`, `spacing`, `headingSize`, `bodySize`, `fontWeight`, `lineHeight`, `letterSpacing`, `shadow`.
+**Global BaseTheme props** (set at root level): `bgColor`, `textColor`, `accentColor`, `borderColor`, `fontFamily`, `radius`, `spacing`, `headingSize`, `bodySize`, `fontWeight`, `lineHeight`, `letterSpacing`, `shadow`.
 ---
@@ -185,17 +196,6 @@ Every theme extends `BaseTheme` which provides: `bgColor`, `textColor`, `accentC
 | `SplitHero` | `title`, `image`, `features`, `reverse` | Side-by-side hero |
 | `VideoHeaderHero` | `videoSrc`, `poster`, `title` | Full-width video hero |
-```tsx
-<StaticHero
-  title="Build Incredible Products"
-  subtitle="Ship faster with pre-built components."
-  ctaLabel="Get Started Free"
-  onCta={() => router.push("/signup")}
-  titleSize={48}
-  align="center"
-/>
-```
 ### Buttons (10)
 | Component | Key Props | Description |
@@ -211,25 +211,6 @@ Every theme extends `BaseTheme` which provides: `bgColor`, `textColor`, `accentC
 | `DownloadButton` | `fileUrl`, `label` | File download button |
 | `PrintButton` | `label` | Print page button |
-```tsx
-<PrimaryButton
-  label="Add to Cart"
-  icon="shopping-cart"
-  onClick={handleAddToCart}
-  bgColor="#7C3AED"
-  radius={12}
-/>
-<ButtonGroup
-  buttons={[
-    { label: "Monthly", value: "monthly" },
-    { label: "Yearly", value: "yearly" },
-  ]}
-  toggle
-  onChange={(v) => setBilling(v)}
-/>
-```
 ### Forms (14)
 | Component | Key Props | Description |
@@ -249,27 +230,6 @@ Every theme extends `BaseTheme` which provides: `bgColor`, `textColor`, `accentC
 | `AddressAutocomplete` | `suggestions`, `onQuery`, `onSelect` | Address autocomplete |
 | `ValidationWrapper` | `errors`, `children`, `success` | Error/success message wrapper |
-```tsx
-<InputField
-  label="Email"
-  name="email"
-  type="email"
-  value={email}
-  onChange={(e) => setEmail(e.target.value)}
-  error={errors.email}
-  icon="mail"
-/>
-<MultiStepWizard
-  steps={[
-    { label: "Personal", content: <PersonalStep /> },
-    { label: "Payment", content: <PaymentStep /> },
-    { label: "Confirm", content: <ConfirmStep /> },
-  ]}
-  onFinish={handleSubmit}
-/>
-```
 ### Content (6)
 | Component | Key Props | Description |
@@ -297,26 +257,6 @@ Every theme extends `BaseTheme` which provides: `bgColor`, `textColor`, `accentC
 | `CalendarGrid` | `year`, `month`, `marks`, `onDateClick` | Month calendar grid |
 | `Timeline` | `items` | Vertical timeline |
-```tsx
-<BarChart
-  data={[120, 280, 150, 350, 210]}
-  labels={["Mon", "Tue", "Wed", "Thu", "Fri"]}
-  title="Weekly Sales"
-  showGrid
-/>
-<DataTable
-  columns={[
-    { key: "name", label: "Name" },
-    { key: "email", label: "Email" },
-    { key: "role", label: "Role" },
-  ]}
-  rows={users}
-  pageSize={10}
-  searchable
-/>
-```
 ### Ecommerce (10)
 | Component | Key Props | Description |
@@ -332,14 +272,6 @@ Every theme extends `BaseTheme` which provides: `bgColor`, `textColor`, `accentC
 | `WishlistButton` | `productId`, `wishlisted`, `onToggle` | Heart wishlist toggle |
 | `PaymentButtons` | `methods`, `onPay` | Payment method buttons |
-```tsx
-<ProductCard
-  product={{ id: "1", name: "T-Shirt", price: 29.99, image: "/tshirt.jpg" }}
-  currency="USD"
-  onAddToCart={(p) => addToCart(p)}
-/>
-```
 ### Lists & Cards (8)
 | Component | Key Props | Description |
@@ -484,7 +416,7 @@ Every theme extends `BaseTheme` which provides: `bgColor`, `textColor`, `accentC
 ## Icon System
-The package includes **113+ inline SVG icons** — zero external dependencies. Use the `Icon` component:
+The package includes **113+ inline SVG icons** — zero external dependencies:
 ```tsx
 import { Icon, ICON_NAMES } from "@electroplix/components";
@@ -500,19 +432,22 @@ All available icon names: `activity`, `alert-circle`, `alert-triangle`, `align-l
 ## CLI
-The package includes a CLI for scaffolding:
 ```bash
-# Initialize config file
-npx electroplix-components init
+# Scaffold config + providers
+npx @electroplix/components init
+# Show all components in a category
+npx @electroplix/components add navigation
-# Add a component category to your project
-npx electroplix-components add navigation
+# Show import instructions for a single component
+npx @electroplix/components add PrimaryNav
-# List all available components
-npx electroplix-components list
+# Browse all 153 components with tree view
+npx @electroplix/components list
 ```
+The `add` command accepts both **component names** (`PrimaryNav`, `BlogCard`) and **category names** (`navigation`, `data-display`, `social`).
 ---
 ## Utilities
@@ -549,12 +484,10 @@ Exported utility functions and hooks:
 </ElectroplixProvider>
 ```
-- **`config`** — `Partial<ElectroplixConfig> | undefined` — optional theme overrides for any/all categories. Falls back to `defaultConfig` for unset values.
+- **`config`** — `Partial<ElectroplixConfig> | undefined` — optional theme overrides. Supports both root-level `BaseTheme` props (global) and per-category objects.
 ### Category hooks
-Each component internally calls its category hook. You can also use them directly:
 ```tsx
 import { useButtonTheme, useNavTheme } from "@electroplix/components";
@@ -566,7 +499,7 @@ function MyCustomButton() {
 ### `defineConfig(config)`
-Type-safe config authoring helper. Returns the config as-is.
+Server-safe type-checked config helper. Import from `@electroplix/components/config`.
 ### `mergeTheme(target, ...sources)`
@@ -581,9 +514,3 @@ pnpm nx test @electroplix/components
 ```
 19 test suites, 163 tests covering all 18 categories.
----
-## License
-MIT