@deijose/nix-ionic 0.2.0 → 0.3.1

package/README.md

@@ -29,14 +29,98 @@ npm install @deijose/nix-ionic @deijose/nix-js @ionic/core
 
 ---
 
-## Quick start
+## Modular component loading (v0.3.0+)
+
+Starting with v0.3.0, `setupNixIonic()` only registers **6 minimal core components** needed for routing (`ion-app`, `ion-router`, `ion-route`, `ion-router-outlet`, `ion-back-button`, `ion-icon`). All other components are loaded **on demand**.
+
+This means you **only pay for what you use**, reducing your initial bundle size dramatically.
+
+### Three ways to load components
+
+#### 1. Individual components (maximum tree-shaking) ✅
+
+Import only the exact components you need:
+
+```typescript
+import { setupNixIonic } from "@deijose/nix-ionic";
+import {
+  defineIonHeader,
+  defineIonToolbar,
+  defineIonTitle,
+  defineIonContent,
+  defineIonButton,
+} from "@deijose/nix-ionic/components";
+
+setupNixIonic({
+  components: [
+    defineIonHeader,
+    defineIonToolbar,
+    defineIonTitle,
+    defineIonContent,
+    defineIonButton,
+  ],
+});
+```
+
+#### 2. Category bundles (balanced approach)
 
-### 1. Initialize Ionic in `main.ts`
+Load components by category:
 
 ```typescript
-import { defineCustomElements } from "@ionic/core/loader";
-defineCustomElements();
+import { setupNixIonic } from "@deijose/nix-ionic";
+import { layoutComponents } from "@deijose/nix-ionic/bundles/layout";
+import { buttonComponents } from "@deijose/nix-ionic/bundles/buttons";
+import { listComponents } from "@deijose/nix-ionic/bundles/lists";
+
+setupNixIonic({
+  components: [...layoutComponents, ...buttonComponents, ...listComponents],
+});
+```
+
+**Available bundles:**
+
+| Bundle | Import path | Components |
+|---|---|---|
+| Layout | `@deijose/nix-ionic/bundles/layout` | header, toolbar, title, content, footer, buttons |
+| Navigation | `@deijose/nix-ionic/bundles/navigation` | menu, menu-button |
+| Forms | `@deijose/nix-ionic/bundles/forms` | input, textarea, checkbox, toggle, select, select-option, radio, radio-group, range, searchbar |
+| Lists | `@deijose/nix-ionic/bundles/lists` | list, list-header, item, item-divider, item-sliding, item-options, item-option, label, note, card, card-header, card-title, card-subtitle, card-content |
+| Feedback | `@deijose/nix-ionic/bundles/feedback` | spinner, progress-bar, skeleton-text, badge, avatar, thumbnail |
+| Buttons | `@deijose/nix-ionic/bundles/buttons` | button, fab, fab-button, fab-list, ripple-effect |
+| Overlays | `@deijose/nix-ionic/bundles/overlays` | modal, popover, toast, alert |
+| **All** | `@deijose/nix-ionic/bundles/all` | All of the above |
+
+#### 3. All components (same as v0.2.x)
+
+If you want backward-compatible behavior with all components loaded at once:
+
+```typescript
+import { setupNixIonic } from "@deijose/nix-ionic";
+import { allComponents } from "@deijose/nix-ionic/bundles/all";
+
+setupNixIonic({ components: allComponents });
+```
+
+### Migration from v0.2.x
+
+```diff
+  import { setupNixIonic } from "@deijose/nix-ionic";
++ import { allComponents } from "@deijose/nix-ionic/bundles/all";
+
+- setupNixIonic();
++ setupNixIonic({ components: allComponents });
+```
 
+Or better yet, import only what you actually use for a smaller bundle.
+
+---
+
+## Quick start
+
+### 1. Initialize and Mount in `main.ts`
+
+```typescript
+// 1. Core Styles (order matters)
 import "@ionic/core/css/core.css";
 import "@ionic/core/css/normalize.css";
 import "@ionic/core/css/structure.css";
@@ -44,28 +128,37 @@ import "@ionic/core/css/typography.css";
 import "@ionic/core/css/padding.css";
 import "@ionic/core/css/flex-utils.css";
 import "@ionic/core/css/display.css";
-```
-
-### 2. Define your routes
+import "./style.css";
 
-```typescript
+// 2. Framework Imports
 import { NixComponent, html, mount } from "@deijose/nix-js";
-import { IonRouterOutlet } from "@deijose/nix-ionic";
+import { setupNixIonic, IonRouterOutlet } from "@deijose/nix-ionic";
+import { layoutComponents } from "@deijose/nix-ionic/bundles/layout";
+import { defineIonButton } from "@deijose/nix-ionic/components";
+
+// 3. Pages
 import { HomePage }   from "./pages/HomePage";
 import { DetailPage } from "./pages/DetailPage";
 
+// Configure and inject Ionic Core (only the components you use)
+setupNixIonic({
+  components: [...layoutComponents, defineIonButton],
+});
+
+// 4. Router Configuration
 const outlet = new IonRouterOutlet([
   { path: "/",           component: (ctx) => new HomePage(ctx)   },
-  { path: "/detail/:id", component: (ctx) => new DetailPage(ctx) },
-  { path: "/profile",    component: (ctx) => ProfilePage(ctx)    },
+  { path: "/detail/:id", component: (ctx) => new DetailPage(ctx) }
 ]);
 
+// 5. App Component
 class App extends NixComponent {
-  render() {
+  override render() {
     return html`<ion-app>${outlet}</ion-app>`;
   }
 }
 
+// 6. Bootstrap
 mount(new App(), "#app");
 ```
 
@@ -288,6 +381,17 @@ interface PageContext {
 
 ## API Reference
 
+### `setupNixIonic(options?)`
+
+```typescript
+setupNixIonic(options?: {
+  iconAssetPath?: string;
+  components?: ComponentDefiner[];
+}): void
+```
+
+Initializes Ionic Core and registers the minimal routing components. Pass additional components via `options.components`.
+
 ### `IonRouterOutlet`
 
 ```typescript
@@ -349,6 +453,7 @@ useIonViewDidLeave(lc:  PageLifecycle, fn: () => void): void
 | `ion-back-button` | native | wrapper | wrapper |
 | Lifecycle hooks | directive | hooks | `IonPage` / composables |
 | Navigation API | `NavController` | `useHistory` | `useRouter()` |
+| Modular loading | ❌ | ❌ | ✅ tree-shakeable |
 
 
 ## Project setup
@@ -429,11 +534,7 @@ my-app/
 ### `main.ts` — entry point
 
 ```typescript
-// ── Ionic loader ─────────────────────────────────────────────────────────────
-import { defineCustomElements } from "@ionic/core/loader";
-defineCustomElements();
-
-// ── Ionic CSS (order matters) ─────────────────────────────────────────────────
+// 1. Core Styles (order matters)
 import "@ionic/core/css/core.css";
 import "@ionic/core/css/normalize.css";
 import "@ionic/core/css/structure.css";
@@ -441,31 +542,37 @@ import "@ionic/core/css/typography.css";
 import "@ionic/core/css/padding.css";
 import "@ionic/core/css/flex-utils.css";
 import "@ionic/core/css/display.css";
-
-// ── App styles ────────────────────────────────────────────────────────────────
 import "./style.css";
 
-// ── App ───────────────────────────────────────────────────────────────────────
+// 2. Framework Imports
 import { NixComponent, html, mount } from "@deijose/nix-js";
-import type { NixTemplate } from "@deijose/nix-js";
-import { IonRouterOutlet } from "@deijose/nix-ionic";
+import { setupNixIonic, IonRouterOutlet } from "@deijose/nix-ionic";
+import { layoutComponents } from "@deijose/nix-ionic/bundles/layout";
+import { buttonComponents } from "@deijose/nix-ionic/bundles/buttons";
+
+// 3. Pages
+import { HomePage }   from "./pages/HomePage";
+import { DetailPage } from "./pages/DetailPage";
 
-import { HomePage }    from "./pages/HomePage";
-import { DetailPage }  from "./pages/DetailPage";
-import { ProfilePage } from "./pages/ProfilePage";
+// Configure and inject Ionic Core
+setupNixIonic({
+  components: [...layoutComponents, ...buttonComponents],
+});
 
+// 4. Router Configuration
 const outlet = new IonRouterOutlet([
   { path: "/",           component: (ctx) => new HomePage(ctx)   },
-  { path: "/detail/:id", component: (ctx) => new DetailPage(ctx) },
-  { path: "/profile",    component: (ctx) => ProfilePage(ctx)    },
+  { path: "/detail/:id", component: (ctx) => new DetailPage(ctx) }
 ]);
 
+// 5. App Component
 class App extends NixComponent {
-  override render(): NixTemplate {
+  override render() {
     return html`<ion-app>${outlet}</ion-app>`;
   }
 }
 
+// 6. Bootstrap
 mount(new App(), "#app");
 ```