@moraby/app-launcher 2.0.13 → 2.0.17

package/README.md

@@ -137,47 +137,41 @@ function Header() {
 }
 ```
 
-### With Settings UI (Admin Mode)
+### With Settings UI (Custom User Apps)
 
-The package includes a built-in Settings modal for managing apps.
+The `AppLauncher` can now intelligently handle custom user applications and automatically merge them with your default configuration. Simply add the `allowCustomApps` prop along with a `storageKey`:
 
 ```tsx
-import { useState } from 'react';
-import { AppLauncher, AppSettings, AppItem } from '@moraby/app-launcher';
+import { AppLauncher } from '@moraby/app-launcher';
 import '@moraby/app-launcher/styles.css';
 
-function AdminLauncher() {
-  const [showSettings, setShowSettings] = useState(false);
-  // Your state management logic here (or use provided props)
-  const [apps, setApps] = useState<AppItem[]>([]);
-
+function Header() {
   return (
-    <>
-      {/* 
-        IMPORTANT: 'renderFooter' is required to show the Settings button! 
-        Without it, the launcher will just show the apps list (which might be empty).
-      */}
+    <header>
       <AppLauncher
-        apps={apps}
-        renderFooter={() => <button onClick={() => setShowSettings(true)}>Settings</button>}
-      />
-
-      <AppSettings
-        isOpen={showSettings}
-        onClose={() => setShowSettings(false)}
-        apps={apps}
-        onAdd={(app) => setApps([...apps, { ...app, id: Date.now().toString() }])}
-        onUpdate={(id, updates) =>
-          setApps(apps.map((a) => (a.id === id ? { ...a, ...updates } : a)))
-        }
-        onDelete={(id) => setApps(apps.filter((a) => a.id !== id))}
+        configUrl="https://example.com/apps.json"
+        storageKey="my-user-apps-storage-key"
+        allowCustomApps={true}
       />
-    </>
+    </header>
   );
 }
 ```
 
-**Note:** If you forget `renderFooter`, there will be no button to open the settings!
+This setup will automatically:
+1. Fetch default applications from `configUrl`.
+2. Inject a "Settings" button in the App Launcher dropdown footer.
+3. Show the built-in Settings modal allowing users to intuitively add, edit, export, and delete custom apps.
+4. Merge default apps with user-defined apps intrinsically.
+5. Persist the user's custom preferences safely in `localStorage` securely!
+
+### Modal Rendering & CSS Isolation
+
+The `AppSettings` modal renders using a **React Portal** directly attached to `document.body`. 
+
+- **Placement & Clipping:** This prevents the modal from being clipped by host application styles such as `overflow: hidden` or complex `z-index` stacking contexts.
+- **Client-Side Only:** In Next.js App Router, ensure the component (or its parent wrapper) is a Client Component (`'use client'`) since `document.body` is required.
+- **CSS Isolation:** The launcher utilizes targeted CSS resets (`all: revert`, explicit `box-sizing`) to protect its buttons and SVG icons from host application global styles (e.g., global `button {}` or `svg {}` styles bleeding into the component).
 
 ## Configuration JSON Format
 
@@ -202,12 +196,15 @@ Export your configuration from the admin app and host it as a JSON file:
 
 ## Props
 
-| Prop         | Type                     | Description                                   |
-| ------------ | ------------------------ | --------------------------------------------- |
-| `configUrl`  | `string`                 | URL to fetch configuration from (JSON or API) |
-| `apps`       | `AppItem[]`              | Direct array of apps to display               |
-| `className`  | `string`                 | Custom class name for the container           |
-| `onAppClick` | `(app: AppItem) => void` | Custom click handler                          |
+| Prop               | Type                     | Description                                                        |
+| ------------------ | ------------------------ | ------------------------------------------------------------------ |
+| `configUrl`        | `string`                 | URL to fetch default configuration from (JSON or API)              |
+| `apps`             | `AppItem[]`              | Direct array of default apps to display                            |
+| `className`        | `string`                 | Custom class name for the container                                |
+| `onAppClick`       | `(app: AppItem) => void` | Custom click handler                                               |
+| `storageKey`       | `string`                 | Optional localStorage key to save custom apps alongside defaults   |
+| `allowCustomApps`  | `boolean`                | If true, intrinsically shows the Settings UI to manage user apps   |
+| `renderFooter`     | `() => ReactNode`        | Optional explicitly rendered footer inside the dropdown            |
 
 ## Icons