@atlashub/smartstack-cli 4.75.0 → 4.79.0

package/templates/skills/application/references/extensions-system.md

@@ -0,0 +1,158 @@
+# Extension System — Slot/Fill, Page Overrides, Hooks
+
+> **Reference for `application` skill** — how a client project enriches a SmartStack page without forking the SDK.
+
+## When This Reference Applies
+
+- Client wants to inject content into an existing SmartStack page (header action, table column, side panel)
+- Client wants to fully replace a built-in page with a custom one
+- Client needs to react to navigation/auth/tenant lifecycle events
+- The user asks "how do I add a column to UsersList", "how do I override the AdministrationDashboard page", "how do I customize a SmartStack form"
+
+---
+
+## Three extension mechanisms
+
+### 1. Page overrides — `componentRegistry` + `PageRegistry`
+
+Override a built-in page by registering your component under the same key :
+
+```tsx
+// In your client componentRegistry.generated.ts (or a custom registry.ts)
+import { PageRegistry } from '@atlashub/smartstack';
+import { lazy } from 'react';
+
+PageRegistry.register(
+  'administration.users',                       // built-in key — replaces SmartStack page
+  lazy(() => import('@/pages/MyCustomUsers')),  // your component
+);
+
+// Or via SmartStackConfig.extensions.pages (declarative)
+const config: SmartStackConfig = {
+  apiUrl: '...',
+  extensions: {
+    pages: {
+      'administration.users': () => import('@/pages/MyCustomUsers'),
+    },
+  },
+};
+```
+
+The `DynamicRouter` calls `PageRegistry.resolve(componentKey)` and your override wins.
+
+> **Tip** — for net-new pages on client-defined routes, prefer the MCP tool `mcp__smartstack__scaffold_routes` to keep `componentRegistry.generated.ts` consistent.
+
+### 2. Slot / Fill — render-prop injection
+
+Inject content into a named slot exposed by a SmartStack page :
+
+```tsx
+import { Fill } from '@atlashub/smartstack';
+
+// Inject into the slot 'users.header.actions'
+<Fill slot="users.header.actions">
+  <button onClick={...}>My custom action</button>
+</Fill>
+```
+
+Available slot names follow the convention `{section}.{location}.{purpose}` (see `extensions/types.ts` SlotName union for the full list — examples : `users.header.actions`, `users.table.columns.before`, `users.table.row.actions`, `users.form.fields.after`, `users.detail.tabs.after`).
+
+You can declare slots once via `SmartStackConfig.extensions.slots` :
+
+```ts
+extensions: {
+  slots: {
+    'users.header.actions': MyHeaderWidget,
+    'dashboard.kpi.before': MyKpi,
+  }
+}
+```
+
+### 3. Lifecycle hooks
+
+Subscribe to platform events from anywhere :
+
+```ts
+extensions: {
+  hooks: {
+    onAuthSuccess: (user) => analytics.identify(user.id),
+    onTenantSwitch: (tenant) => router.navigate('/dashboard'),
+    onNavigationChanged: (menu) => console.log('menu refreshed'),
+  }
+}
+```
+
+---
+
+## Table columns & form fields extensions
+
+Extend the standard `DataTable` or `EntityForm` of any built-in section :
+
+```ts
+extensions: {
+  tableColumns: {
+    'administration.users.list': [
+      {
+        key: 'department',
+        label: 'Department',
+        render: (row) => row.department?.name,
+        align: 'left',
+        sortable: true,
+      },
+    ],
+  },
+  formFields: {
+    'administration.users.create': [
+      {
+        name: 'department',
+        type: 'select',
+        label: 'Department',
+        options: () => departmentApi.list(),
+        validation: { required: true },
+      },
+    ],
+  },
+}
+```
+
+These extensions are consumed by the corresponding hooks in the SmartStack page :
+
+```tsx
+const extraColumns = useTableColumnExtensions('administration.users.list');
+const extraFields = useFormFieldExtensions('administration.users.create');
+```
+
+---
+
+## DO / DON'T
+
+| ✅ DO | ❌ DON'T |
+|---|---|
+| Use `PageRegistry.register()` once at startup | Register the same key twice (last wins, but ambiguous) |
+| Use lazy imports for page overrides | Import override pages eagerly (kills code splitting) |
+| Match exact componentKey from the navigation menu | Guess the key — read it from `/api/navigation/menu` response |
+| Use slots for additive content | Use slots to remove content (use page override instead) |
+| Type custom column data via `row` typing | Cast `row as any` |
+
+---
+
+## MCP delegation
+
+For complex extension scaffolds (page override + slots + tests), prefer the MCP tool over hand-written code :
+
+| Goal | MCP tool |
+|---|---|
+| Generate a page override + register it | `mcp__smartstack__scaffold_frontend_extension` (type: `page-override`) |
+| Generate a custom Slot component | `mcp__smartstack__scaffold_frontend_extension` (type: `slot`) |
+| Generate a custom column extension | `mcp__smartstack__scaffold_frontend_extension` (type: `table-column`) |
+
+---
+
+## Reference source files (read-only)
+
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\extensions\PageRegistry.tsx`
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\extensions\types.ts` (SlotName, ColumnExtension, FormFieldExtension)
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\extensions\ExtensionContext.tsx` (useExtensions, useTableColumnExtensions, useFormFieldExtensions)
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\extensions\SlotFill.tsx` (Slot, Fill, SlotFillProvider)
+
+See also [smartstack-provider.md](smartstack-provider.md) for the SmartStackConfig shape that hosts `extensions`.

package/templates/skills/application/references/frontend-route-naming.md

@@ -79,19 +79,21 @@ const applicationRoutes: ApplicationRouteExtensions = {
 
 ## Implementation Pattern
 
+> **v3.46+ note** — The domain-specific layouts `AdminLayout`, `BusinessLayout`, `UserLayout`, `HRLayout`, `SalesLayout` are REMOVED. `AppLayout` is now the SOLE shell for authenticated application routes. Routes are resolved dynamically by `DynamicRouter` via `componentRegistry.generated.ts` — the JSX `<Route>` blocks below are illustrative for naming convention only, not for manual declaration. See `references/smartstack-provider.md` for the full provider/router setup.
+
 When generating routes, apply kebab-case to all multi-word segments:
 
 ```tsx
-// CORRECT
-<Route path="/human-resources" element={<HRLayout />}>
+// CORRECT — kebab-case convention (illustrative — actual routes flow through DynamicRouter)
+<Route path="/human-resources" element={<AppLayout />}>
   <Route path="employees" element={<EmployeesPage />} />
   <Route path="time-management" element={<TimeManagementPage />} />
 </Route>
 
 // FORBIDDEN
-<Route path="/humanresources" element={<HRLayout />} />
-<Route path="/HR" element={<HRLayout />} />
-<Route path="/human_resources" element={<HRLayout />} />
+<Route path="/humanresources" element={<AppLayout />} />
+<Route path="/HR" element={<AppLayout />} />
+<Route path="/human_resources" element={<AppLayout />} />
 ```
 
 ---

package/templates/skills/application/references/frontend-verification.md

@@ -4,13 +4,15 @@
 
 ## Routing Rules
 
+> ⚠️ **DEPRECATED PATTERN — v3.46+** : Domain-specific layouts (`SalesLayout`, `AdminLayout`, `BusinessLayout`, `UserLayout`, `HRLayout`) are REMOVED. There are now **only 4 layouts** : `AppLayout` (sole shell for authenticated app routes), `AuthLayout` (login/register), `PublicLayout` (public pages), `DocsLayout` (documentation). The "manual `<Route>` declaration" examples below are LEGACY ; on v3.46+ routes are resolved by `DynamicRouter` via `componentRegistry.generated.ts` (see Section 5b below + `references/smartstack-provider.md`). The examples are kept for projects on v3.6 and earlier.
+
 ### Rule 1: Routes MUST be inside Layout wrappers
 
-**CRITICAL:** All routes MUST be nested inside the appropriate context layout. This is what provides the SmartStack shell (header with AvatarMenu, sidebar, navigation).
+**CRITICAL (legacy v3.6 only):** All routes MUST be nested inside the appropriate context layout. This is what provides the SmartStack shell (header with AvatarMenu, sidebar, navigation). On v3.46+, `AppLayout` is the SOLE shell.
 
 ```tsx
-// CORRECT - Inside SalesLayout (shell renders: header + AvatarMenu + sidebar)
-<Route path="/sales" element={<SalesLayout />}>
+// CORRECT (v3.46+) - Inside AppLayout (shell renders: header + AvatarMenu + sidebar)
+<Route path="/sales" element={<AppLayout />}>
   <Route path="products" element={<ProductsPage />} />
 </Route>
 
@@ -23,8 +25,8 @@
 **CRITICAL:** SmartStack requires NESTED routes within the layout:
 
 ```tsx
-// CORRECT - Nested routes inside layout
-<Route path="/sales" element={<SalesLayout />}>
+// CORRECT - Nested routes inside layout (v3.46+ uses AppLayout)
+<Route path="/sales" element={<AppLayout />}>
   <Route path="products">
     <Route index element={<Navigate to="products" replace />} />
     <Route path="products" element={<ProductsPage />} />

package/templates/skills/application/references/provider-template.md

@@ -42,10 +42,12 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         }
         else
         {
+            // v3.46+ signature : Zone removed. New flags isOpen + isPersonal at the END (optional, default false).
             app = NavigationApplication.Create(
-                ApplicationZone.Business, appEntry.Code, appEntry.Label,
+                appEntry.Code, appEntry.Label,
                 appEntry.Description, appEntry.Icon, appEntry.IconType,
-                appEntry.Route, appEntry.DisplayOrder);
+                appEntry.Route, appEntry.DisplayOrder,
+                isOpen: appEntry.IsOpen, isPersonal: appEntry.IsPersonal);
             context.NavigationApplications.Add(app);
             await ((DbContext)context).SaveChangesAsync(ct);
 

package/templates/skills/application/references/smartstack-provider.md

@@ -0,0 +1,118 @@
+# SmartStackProvider — Wrapping the Client App
+
+> **Reference for `application` skill** — how to bootstrap a SmartStack client project (npm `@atlashub/smartstack`) using the SDK provider.
+
+## When This Reference Applies
+
+- The client project consumes `@atlashub/smartstack` as an npm package (v3.7+)
+- You are generating or auditing `App.tsx` / `main.tsx` / the application bootstrap
+- The user asks "how do I wrap my app", "where do I put providers", "how do I configure SmartStack"
+
+If the project is the SmartStack platform itself (`SmartStack.app`), the platform's internal `App.tsx` already inlines the providers and does NOT use `<SmartStackProvider>` — only client projects use it.
+
+---
+
+## SmartStackConfig shape
+
+```ts
+interface SmartStackConfig {
+  apiUrl: string;                          // REQUIRED — backend root URL (e.g. "https://api.client.com")
+  defaultLanguage?: 'fr' | 'en' | 'it' | 'de';  // default 'fr'
+  debug?: boolean;                          // verbose logging
+  logo?: ReactNode;                         // override branding logo
+  appName?: string;                         // displayed in title/header fallback
+  licenseKey?: string;                      // license string (validated against /api/license)
+  extensions?: ExtensionConfig;             // see references/extensions-system.md
+}
+```
+
+---
+
+## Wrapping order (Outer → Inner)
+
+```tsx
+import { BrowserRouter } from 'react-router-dom';
+import { SmartStackProvider, DynamicRouter } from '@atlashub/smartstack';
+import '@atlashub/smartstack/theme.css';
+
+const config: SmartStackConfig = {
+  apiUrl: import.meta.env.VITE_API_URL,
+  defaultLanguage: 'fr',
+  appName: 'My Client App',
+};
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <BrowserRouter>
+      <SmartStackProvider config={config}>
+        <DynamicRouter />
+      </SmartStackProvider>
+    </BrowserRouter>
+  </StrictMode>,
+);
+```
+
+`<SmartStackProvider>` internally nests, in this order :
+
+```
+SmartStackContext (config)
+└─ GlobalErrorBoundary
+   └─ ExtensionProvider
+      └─ ThemeProvider
+         └─ FeatureConfigProvider
+            └─ AuthProvider
+               └─ TenantProvider
+                  └─ LicenseProvider
+                     └─ FavoritesProvider
+                        └─ SidebarProvider
+                           └─ SessionProvider
+                              └─ ThemeSync
+                                 └─ NavigationProvider
+                                    └─ SignalRProvider
+                                       └─ {children}
+```
+
+**Do NOT re-wrap any of these providers manually.** They are exported only for advanced cases (e.g., Storybook).
+
+---
+
+## Hooks consumable from any descendant
+
+| Hook | Context | Returns |
+|---|---|---|
+| `useSmartStack()` | SmartStackContext | `{ config }` |
+| `useAuth()` | AuthContext | `{ user, login, logout, refresh, hasPermission }` |
+| `useTenant()` | TenantContext | `{ currentTenant, userTenants, switchTenant, isGlobalView }` |
+| `useNavigation()` | NavigationContext | `{ menu, reload, currentApp, currentModule, isLoading }` |
+| `useTheme()` | ThemeContext | `{ mode, selectedTheme, selectedPreset, setTheme, setPreset, toggleMode }` |
+| `useLicense()` | LicenseContext | `{ license, isFeatureEnabled, hasModule }` |
+| `useSignalR()` | SignalRContext | `{ isConnected, on, off, emit }` |
+| `useFavorites()` | FavoritesContext | `{ favorites, toggleFavorite, isFavorite }` |
+| `useSidebar()` | SidebarContext | `{ isCollapsed, toggle, setCollapsed }` |
+| `useFeatureConfig()` | FeatureConfigContext | `{ features }` |
+| `useDocPanel()` | DocPanelContext | `{ isOpen, toggle, openDoc }` |
+
+See [contexts-cheatsheet.md](contexts-cheatsheet.md) for usage examples.
+
+---
+
+## DO / DON'T
+
+| ✅ DO | ❌ DON'T |
+|---|---|
+| Place `<SmartStackProvider>` exactly once at root | Wrap the same provider twice |
+| Put `<BrowserRouter>` ABOVE `<SmartStackProvider>` | Put `<SmartStackProvider>` above the router |
+| Read config via `useSmartStack()` from any descendant | Pass config down via props |
+| Import `componentRegistry.generated` in `main.tsx` BEFORE the render | Forget the import (DynamicRouter will not resolve pages) |
+| Wait for `i18nReady` promise before render | Render before i18n loaded (causes FOUC) |
+| Provide `apiUrl` via `import.meta.env.VITE_API_URL` | Hardcode the backend URL |
+
+---
+
+## Reference source files (read-only — DO NOT copy verbatim)
+
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\provider\SmartStackProvider.tsx`
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\router\types.ts` (SmartStackConfig)
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\main.tsx` (i18nReady + componentRegistry import)
+
+For overrides via `extensions`, see [extensions-system.md](extensions-system.md).