@open-rlb/ng-app 3.1.111 → 3.1.113

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-rlb/ng-app",
-  "version": "3.1.111",
+  "version": "3.1.113",
   "peerDependencies": {
     "@angular/common": ">=21.0.0 <22.0.0",
     "@angular/core": ">=21.0.0 <22.0.0",
@@ -21,6 +21,10 @@
   "dependencies": {
     "tslib": "^2.8.1"
   },
+  "schematics": "./schematics/collection.json",
+  "ng-add": {
+    "save": "dependencies"
+  },
   "sideEffects": false,
   "module": "fesm2022/open-rlb-ng-app.mjs",
   "typings": "types/open-rlb-ng-app.d.ts",
@@ -33,5 +37,9 @@
       "default": "./fesm2022/open-rlb-ng-app.mjs"
     }
   },
-  "type": "module"
+  "type": "module",
+  "files": [
+    "**/*",
+    "schematics/package.json"
+  ]
 }

package/schematics/collection.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../../../../node_modules/@angular-devkit/schematics/collection-schema.json",
+  "schematics": {
+    "ng-add": {
+      "description": "Add @open-rlb/ng-app to an Angular project: install peer dependencies, register Bootstrap styles, and scaffold a runnable application shell (environment, providers, app shell, routes, i18n).",
+      "factory": "./ng-add/index#ngAdd",
+      "schema": "./ng-add/schema.json"
+    }
+  }
+}

package/schematics/ng-add/claude-skills/rlb-app-apps/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: rlb-app-apps
+description: The @open-rlb/ng-app multi-app orchestration — the AppInfo/AppDescriber model, AppsService (the runtime engine), domain + ACL filtering of apps, current-app selection from the route, and root/deep-link redirect rules. Use when registering apps, building an app hub/selector, controlling which app is "current", or debugging why an app isn't shown or selected.
+---
+
+# @open-rlb/ng-app — Apps & Orchestration
+
+`@open-rlb/ng-app` is a **multi-app shell**: a single host hosts one or more logical "apps", each
+described by an `AppInfo`. **`AppsService`** is the runtime engine that filters those apps by
+domain and ACL, selects the current app from the active route, and applies redirect rules. It is
+exported from the public API and **eagerly bootstrapped** by `provideRlbConfig`
+(`provideAppInitializer(() => inject(AppsService))`), so it runs as soon as the app starts.
+
+## The app model — `AppInfo`
+
+An app is registered via `provideApp(appDescriber)` (`AppDescriber.info` is an `AppInfo`). Fields
+that drive runtime behavior:
+
+| Field | Drives |
+|---|---|
+| `type` | App kind/category (e.g. `'app'`); used in `finalizeApp`/route matching. |
+| `enabled` | Whether the app participates. |
+| `core` / `settings` | `AppDetails` — `{ title, description, url, icon, auth }`. `core.url` is the app's landing route and the redirect target. |
+| `viewMode` | `'app'` \| `'settings'` — how the shell frames the app. |
+| `routes` | Route path strings owned by the app; matched against the active URL to select it. |
+| `domains` | If set, the app only appears/activates on those `window.location.hostname`s (domain gating). |
+| `actions` | ACL action names; the app is hidden unless the user holds a matching resource action (ACL gating). |
+| `autoRedirectOnRootEnabled` | At root with multiple apps, redirect to this app's `core.url`. |
+| `data` | Arbitrary payload; carries the ACL `businessIdKey` / `resourceIdKey` values used for permission checks. |
+
+```typescript
+export const appDescriber: AppDescriber = {
+  info: {
+    type: 'app',
+    enabled: true,
+    actions: ['sysadmin'],
+    core: { title: 'My App', description: '', url: '/home', icon: 'bi bi-house', auth: true },
+  },
+  routes,   // Angular Routes; flattened paths are stored on RLB_APPS
+};
+```
+
+## Registration → runtime lifecycle
+
+```
+provideApp(appDescriber)            register the AppInfo into RLB_APPS (multi)
+  → RLB_INIT_PROVIDER.finalizeApps  ACL hook dispatches AppContextActions.finalizeApp → apps gain an `id`
+  → AppsService.apps (computed)     filters finalized apps by domain + ACL resources/actions
+  → router listener (NavigationEnd) matches the route → selects currentApp + applies redirects
+```
+
+This is the "AppsService orchestration" step of the auth pipeline
+(`checkAuthMultiple → resourcesByUser → finalizeApp → AppsService orchestration`). See
+[[rlb-app-auth-acl]] for the ACL hook and [[rlb-app-config]] for `provideApp`/`RLB_APPS`.
+
+## Reading apps from a component
+
+Inject `AppsService` and read its signals (zoneless — use signals, never zone.js):
+
+```typescript
+private apps = inject(AppsService);
+
+readonly visibleApps = this.apps.apps;        // signal: domain- + ACL-filtered AppInfo[]
+readonly current = this.apps.currentApp;      // signal: AppInfo | null
+readonly currentId = this.apps.currentAppId;  // signal: string | undefined
+
+canEdit = this.apps.checkPermissionInCurrentApp('catalog-editor'); // ACL in current app
+this.apps.selectApp(app, 'app', '/home');     // manually select (the app hub/selector uses this)
+```
+
+The built-in app/settings selector pages (`pages/apps/*`, `pages/settings/*`) render
+`apps()` and call `selectApp(...)`.
+
+## Current-app selection & redirect rules
+
+On each `NavigationEnd`, `AppsService` resolves the active route and applies (in order):
+
+1. **Single app at root** → auto-redirect to that app's `core.url`.
+2. **Multiple apps at root** → show the app hub (`currentApp` is `null`), unless an app has
+   `autoRedirectOnRootEnabled` (then redirect to it).
+3. **Deep link** (non-root) → select the app whose `routes`/`core.url` matches the path.
+
+Selection waits until apps are **finalized** (every app has an `id`); until then `currentApp`
+stays unresolved.
+
+## ACL on initial deep-link — `findAppForPath`
+
+Because `currentApp` isn't selected until `NavigationEnd` fires, `permissionGuard` handles the
+first navigation specially: if no `currentApp` yet, it calls
+`appsService.findAppForPath(path)` to locate the owning app from the URL, then
+`checkPermissionForApp(app, action)`. After that, it uses `checkPermissionInCurrentApp(action)`.
+The `*roles` directive also reads `checkPermissionInCurrentApp` (re-runs reactively). See
+[[rlb-app-auth-acl]].
+
+## Multi-provider auth by domain
+
+`AppsService.initAuthProviders()` picks the OIDC provider at startup: if one provider, use it; if
+several, match by `provider.domains` against the current hostname. Multiple matches (or none) log
+a warning and leave the provider unset — give each provider a distinct `domains` entry.
+
+## Gotchas
+
+- **Apps must be finalized** (have an `id`) before selection resolves — driven by the ACL init
+  hook; an empty `apps()` usually means ACL/finalize hasn't run yet.
+- **`currentApp()` is `null` at root** in multi-app (hub) mode — that's expected, not an error.
+- **Domain gating uses `window.location.hostname`** — `localhost` won't match production
+  `domains`; include `localhost` (or omit `domains`) for local dev.
+- Don't re-run `selectApp` redundantly — it no-ops when the id + viewMode are unchanged.
+
+Related: [[rlb-app-config]], [[rlb-app-auth-acl]], [[rlb-app-shell]], [[rlb-app-store]].

package/schematics/ng-add/claude-skills/rlb-app-auth-acl/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: rlb-app-auth-acl
+description: Authentication (OIDC) and authorization (ACL) in @open-rlb/ng-app — OAuth provider config, the oauthGuard and permissionGuard route guards, the *roles structural directive, and the RLB_INIT_PROVIDER ACL startup hook. Use when securing routes/UI or configuring login.
+---
+
+# @open-rlb/ng-app — Auth & ACL
+
+Authentication is OIDC via `angular-auth-oidc-client`; authorization is action-based ACL resolved from the backend on startup.
+
+## Configuring auth
+
+In `environment.ts` under `auth`:
+
+```typescript
+auth: {
+  protocol: 'oauth',
+  storage: 'localStorage',            // 'cookies' | 'localStorage' | 'sessionStorage'
+  interceptor: 'oauth-code-ep',       // attach tokens to endpoint calls
+  allowedUrls: ['https://api.example.com'],
+  enableCompanyInterceptor: true,
+  providers: [{
+    configId: 'default',
+    authority: 'https://login.example.com/realms/your-realm',
+    clientId: 'your-client-id',
+    redirectUrl: 'http://localhost:4200',
+    postLogoutRedirectUri: 'http://localhost:4200',
+    scope: 'openid profile offline_access',
+    acl: { endpointKey: 'http-gateway', path: 'admin/acl/resources' },  // where to fetch ACL
+  }],
+}
+```
+
+The startup pipeline is `checkAuthMultiple → resourcesByUser → finalizeApp → AppsService orchestration` (wired by `provideRlbConfig`). The final step — filtering apps by domain/ACL and selecting the current app from the route — is handled by `AppsService`; see [[rlb-app-apps]].
+
+## Guarding routes
+
+```typescript
+import { oauthGuard, permissionGuard } from '@open-rlb/ng-app';
+
+{ path: 'account', component: AccountComponent, canActivate: [oauthGuard] },
+{ path: 'admin', component: AdminComponent, canActivate: [permissionGuard], data: { action: 'sysadmin' } },
+```
+
+- `oauthGuard` — requires an authenticated session.
+- `permissionGuard` — requires the ACL action named in `route.data.action`.
+
+## Guarding UI
+
+The `*roles` structural directive shows content only if the user holds the action:
+
+```html
+<button *roles="'sysadmin'">Admin only</button>
+```
+
+(`RlbAppModule` provides the directive.)
+
+## ACL startup hook — RLB_INIT_PROVIDER
+
+Implement `RlbInitProvider` to map the user's `UserResource[]` into app instances:
+
+```typescript
+@Injectable()
+export class AppInitAclProvider implements RlbInitProvider {
+  async finalizeApps(resources: UserResource[], store: Store<BaseState>, acl: AclConfiguration) {
+    resources.forEach(company => company.resources.forEach(res => {
+      store.dispatch(AppContextActions.finalizeApp({
+        appType: 'app',
+        appId: `app-${res.resourceId}`,
+        data: {
+          title: res.friendlyName,
+          [acl.businessIdKey]: company.companyId,
+          [acl.resourceIdKey]: res.resourceId,
+        },
+      }));
+    }));
+  }
+}
+```
+
+Register it: `{ provide: RLB_INIT_PROVIDER, useClass: AppInitAclProvider }`. The action names in `appDescriber.info.actions` must match the ACL actions your backend returns.
+
+Related: [[rlb-app-apps]], [[rlb-app-config]], [[rlb-app-store]], [[rlb-app-shell]].

package/schematics/ng-add/claude-skills/rlb-app-config/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: rlb-app-config
+description: Configuration and bootstrap of an app built on @open-rlb/ng-app — the ProjectConfiguration/environment shape, provideRlbConfig(), provideApp(), the AppDescriber, and the RLB_INIT_PROVIDER startup hook. Use when wiring up app.config.ts, editing environment.ts, or changing app metadata/routes.
+---
+
+# @open-rlb/ng-app — Configuration & Bootstrap
+
+You are an expert in bootstrapping an Angular application on the **@open-rlb/ng-app** library. A host app is intentionally thin: it supplies a `ProjectConfiguration` (the environment), an `AppDescriber`, and an optional ACL init provider, then the library wires the store, router, auth, HTTP, i18n and service worker.
+
+## app.config.ts — the three building blocks
+
+```typescript
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRlbConfig(environment),   // store + router + auth + i18n + http + SW + registries
+    provideApp(appDescriber),        // app identity, ACL actions, routes, custom providers
+    { provide: RLB_INIT_PROVIDER, useClass: AppInitAclProvider }, // optional startup ACL mapping
+    provideZonelessChangeDetection(),
+  ],
+};
+```
+
+- `provideRlbConfig(environment)` is the only place the library config is read. It internally calls `provideRlbBootstrap()` (so do NOT call it again), registers the four NgRx feature slices, the default routes derived from `environment.pages`, OIDC auth (`provideRlbCodeBrowserOAuth(env.auth)`), i18n (`provideRlbI18n(env.i18n)`), `provideHttpClient(withInterceptorsFromDi())`, the service worker, and the built-in modal/toast registries.
+- `provideApp(appDescriber)` registers `RLB_APPS` (multi), adds `appDescriber.routes` via `provideRouter`, and spreads any `appDescriber.providers`. At runtime those registered apps are filtered and selected by `AppsService` — see [[rlb-app-apps]].
+
+## environment.ts — ProjectConfiguration
+
+`ProjectConfiguration = IConfiguration & { production: boolean }`. Sections:
+
+| Key | Purpose |
+|---|---|
+| `environment` | app metadata: `appTitle`, `appLogo`, `baseUrl`, `errorDialogName`, `logLevel`, `pwaUpdateEnabled`, `navbarDisabled` |
+| `auth` | OIDC: `protocol: 'oauth'`, `storage`, `interceptor`, `allowedUrls`, `providers[]` (per-provider `authority`/`clientId`/`redirectUrl`/`acl`) |
+| `i18n` | `availableLangs`, `defaultLanguage`, `useLanguageBrowser`, `storeSelectedLanguage`, `cookieStoreName` |
+| `pages` | named route paths for standard pages (notFound, forbidden, support, …) |
+| `endpoints` | named HTTP/WS backends (`{ baseUrl, healthPath, auth, wss }`) referenced by key (e.g. `http-gateway`) |
+| `acl` | `businessIdKey`, `resourceIdKey`, `interceptorMapping` |
+
+Inject any slice with the tokens: `RLB_CFG`, `RLB_CFG_ENV`, `RLB_CFG_I18N`, `RLB_CFG_PAGES`, `RLB_CFG_ACL`, `RLB_CFG_CMS`.
+
+## AppDescriber
+
+```typescript
+export const appDescriber: AppDescriber = {
+  info: {
+    type: 'app',
+    enabled: true,
+    actions: ['sysadmin', ...],   // ACL action names this app understands
+    core: { title, description, url, icon, auth: true },
+    settings: { title, description, url, icon, auth: true },
+  },
+  routes,                          // Angular Routes; flattened paths are registered with RLB_APPS
+  providers: [ /* optional: e.g. RLB_APP_NAVCOMP overrides */ ],
+};
+```
+
+## RLB_INIT_PROVIDER
+
+A class implementing `RlbInitProvider.finalizeApps(resources, store, acl)`. It runs after authentication, turning the user's ACL `UserResource[]` into app instances via `AppContextActions.finalizeApp(...)`. Optional — omit the provider if you don't drive apps from ACL. See [[rlb-app-auth-acl]].
+
+## Common gotchas
+
+- The app is **zoneless** — never rely on zone.js; use signals.
+- `appLogo`/i18n files live under `src/assets`; ensure `assets` includes `src/assets` in `angular.json`.
+- The service worker is `enabled: !isDevMode()`, so it's off under `ng serve`. For production builds, configure `ngsw-config.json` (e.g. `ng add @angular/pwa`).
+
+Related: [[rlb-app-apps]], [[rlb-app-shell]], [[rlb-app-store]], [[rlb-app-auth-acl]].

package/schematics/ng-add/claude-skills/rlb-app-shell/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: rlb-app-shell
+description: The @open-rlb/ng-app application shell — <rlb-app-container>, navbar/sidebar configuration via NgRx actions, language selection, and custom navbar item components (RLB_APP_NAVCOMP). Use when building or customizing the app layout/chrome.
+---
+
+# @open-rlb/ng-app — Application Shell
+
+The shell renders the full app chrome (navbar, sidebar, modal/toast containers, routed content). The host `AppComponent` is thin: it mounts `<rlb-app-container>` and dispatches store actions to configure visibility and items.
+
+## Mounting the shell
+
+```typescript
+@Component({
+  selector: 'app-root',
+  imports: [RlbAppModule],
+  template: `
+    <rlb-app-container
+      modal-container-id="modal-c-1"
+      toast-container-ids="toast-c-1"
+    />`,
+})
+export class AppComponent { /* dispatch config in constructor */ }
+```
+
+`RlbAppModule` aggregates the library's standalone components/directives/pipes; import it wherever you use shell elements (`rlb-app-container`, `rlb-navbar-item`, the `*roles` directive, etc.).
+
+## Configuring navbar & sidebar (NgRx actions)
+
+Dispatch in `AppComponent`'s constructor:
+
+```typescript
+this.store.dispatch(NavbarActions.setLoginVisible({ visible: true }));
+this.store.dispatch(NavbarActions.setSettingsVisible({ visible: true }));
+this.store.dispatch(NavbarActions.setAppsVisible({ visible: true }));
+
+this.store.dispatch(SidebarActions.setAppsVisible({ visible: true }));
+this.store.dispatch(SidebarActions.setItems({
+  items: [
+    { title: 'Menu' },                                   // section header
+    { label: 'Home', url: '/', icon: 'bi bi-house' },
+    { label: 'Profile', url: '/profile', icon: 'bi bi-person', badgeCounter: 3 },
+    { label: 'Links', icon: 'bi bi-link', items: [       // nested
+      { label: 'GitHub', icon: 'bi bi-github', externalUrl: 'https://github.com' },
+    ]},
+  ],
+}));
+
+this.store.dispatch(AppContextActions.setSupportedLanguages({ supportedLanguages: ['en', 'it'] }));
+```
+
+Sidebar item shape: `{ title }` (header) or `{ label, url? | externalUrl?, icon?, badgeCounter?, items? }`.
+
+## Custom navbar item components
+
+Override navbar slots by providing `RLB_APP_NAVCOMP` (via `appDescriber.providers`):
+
+```typescript
+{
+  provide: RLB_APP_NAVCOMP,
+  useValue: {
+    left:  [{ component: MyNavItemComponent, name: 'my-item' }],
+    right: [{ component: MyNavItemComponent, name: 'my-item' }],
+  },
+}
+```
+
+Icons are Bootstrap Icons (`bi bi-*`), available because the shell registers `bootstrap-icons.css`.
+
+Related: [[rlb-app-config]], [[rlb-app-apps]], [[rlb-app-store]], [[rlb-app-auth-acl]].

package/schematics/ng-add/claude-skills/rlb-app-store/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: rlb-app-store
+description: The @open-rlb/ng-app NgRx store — the auth, appContext, navbars, and sidebars feature slices, their action groups, and reading state with signals. Use when dispatching actions or selecting app/auth/navbar/sidebar state.
+---
+
+# @open-rlb/ng-app — Store (NgRx)
+
+The library owns the store. `provideRlbConfig()` registers four feature slices; the host app dispatches actions and selects state. Prefer **signals** (`store.selectSignal`, `toSignal`) over the `async` pipe — the app is zoneless.
+
+## Feature slices
+
+| Feature key | Purpose | Actions |
+|---|---|---|
+| `auth` | login/logout, user info, token | `AuthActions` |
+| `app` (`appContextFeatureKey`) | current app, apps list, theme, language | `AppContextActions` |
+| `navbars` | navbar items, layout mode, visibility | `NavbarActions` |
+| `sidebars` | sidebar items (nested), visibility | `SidebarActions` |
+
+`BaseState` is the combined root state (`AclState & AuthState & SidebarState & NavbarState & AppState`). Type your store as `Store<BaseState>`.
+
+## Reading state
+
+```typescript
+private store = inject(Store<BaseState>);
+
+// signal (preferred)
+currentApp = this.store.selectSignal(s => s[appContextFeatureKey].currentApp);
+
+// or observable
+this.store.select(s => s[appContextFeatureKey].apps).subscribe(/* … */);
+```
+
+## Common actions
+
+```typescript
+AppContextActions.setSupportedLanguages({ supportedLanguages: ['en', 'it'] });
+AppContextActions.finalizeApp({ appType, appId, data });   // register an app instance (see ACL)
+
+NavbarActions.setLoginVisible({ visible });
+NavbarActions.setSettingsVisible({ visible });
+NavbarActions.setAppsVisible({ visible });
+
+SidebarActions.setItems({ items });
+SidebarActions.setAppsVisible({ visible });
+```
+
+`*Internal` action groups (e.g. `AppContextActionsInternal`) are driven by the library's effects — don't dispatch them from app code.
+
+Related: [[rlb-app-shell]], [[rlb-app-apps]], [[rlb-app-auth-acl]], [[rlb-app-config]].

package/schematics/ng-add/files/app/app-init-acl.provider.ts.template

@@ -0,0 +1,54 @@
+import { Injectable } from '@angular/core';
+import { Store } from '@ngrx/store';
+import {
+  AclConfiguration,
+  AppContextActions,
+  appContextFeatureKey,
+  BaseState,
+  RlbInitProvider,
+  UserResource,
+} from '@open-rlb/ng-app';
+
+/**
+ * Runs once on startup after authentication: turns the user's ACL resources into
+ * app instances via `finalizeApp`. This is an example — adapt `appType`/`appId`
+ * and the data mapping to your domain.
+ */
+@Injectable()
+export class AppInitAclProvider implements RlbInitProvider {
+  async finalizeApps(
+    resources: UserResource[],
+    store: Store<BaseState>,
+    acl: AclConfiguration,
+  ): Promise<void> {
+    if (!resources || resources.length === 0) {
+      return;
+    }
+
+    const currentApps = store.selectSignal(state => state[appContextFeatureKey].apps)();
+
+    resources.forEach(company => {
+      company.resources.forEach(res => {
+        const appId = `app-${res.resourceId}`;
+        if (currentApps.findIndex(app => app.id === appId) === -1) {
+          const appData = {
+            title: res.friendlyName,
+            appName: res.friendlyName,
+            [acl.businessIdKey]: company.companyId,
+            [acl.resourceIdKey]: res.resourceId,
+          };
+
+          store.dispatch(
+            AppContextActions.finalizeApp({
+              appType: 'app',
+              appId,
+              data: appData,
+            }),
+          );
+        } else {
+          console.warn(`[AppInitAclProvider]: appId ${appId} exists already, skip finalize`);
+        }
+      });
+    });
+  }
+}

package/schematics/ng-add/files/app/app.component.ts.template

@@ -0,0 +1,44 @@
+import { Component } from '@angular/core';
+import { Store } from '@ngrx/store';
+import {
+  AppContextActions,
+  BaseState,
+  NavbarActions,
+  RlbAppModule,
+  SidebarActions,
+} from '@open-rlb/ng-app';
+
+@Component({
+  selector: 'app-root',
+  imports: [RlbAppModule],
+  template: `
+    <rlb-app-container
+      modal-container-id="modal-c-1"
+      toast-container-ids="toast-c-1"
+    />
+  `,
+})
+export class AppComponent {
+  constructor(public store: Store<BaseState>) {
+    this.store.dispatch(
+      AppContextActions.setSupportedLanguages({
+        supportedLanguages: ['en', 'it'],
+      }),
+    );
+
+    this.store.dispatch(NavbarActions.setLoginVisible({ visible: true }));
+    this.store.dispatch(NavbarActions.setSettingsVisible({ visible: true }));
+    this.store.dispatch(NavbarActions.setAppsVisible({ visible: true }));
+    this.store.dispatch(SidebarActions.setLoginVisible({ visible: false }));
+    this.store.dispatch(SidebarActions.setSettingsVisible({ visible: false }));
+    this.store.dispatch(SidebarActions.setAppsVisible({ visible: true }));
+    this.store.dispatch(
+      SidebarActions.setItems({
+        items: [
+          { title: 'Menu' },
+          { label: 'Home', url: '/', icon: 'bi bi-house' },
+        ],
+      }),
+    );
+  }
+}

package/schematics/ng-add/files/app/app.config.ts.template

@@ -0,0 +1,17 @@
+import { ApplicationConfig, provideZonelessChangeDetection } from '@angular/core';
+import { provideApp, provideRlbConfig, RLB_INIT_PROVIDER } from '@open-rlb/ng-app';
+import { environment } from '../environments/environment';
+import { appDescriber } from './app.describer';
+import { AppInitAclProvider } from './app-init-acl.provider';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRlbConfig(environment),
+    provideApp(appDescriber),
+    {
+      provide: RLB_INIT_PROVIDER,
+      useClass: AppInitAclProvider,
+    },
+    provideZonelessChangeDetection(),
+  ],
+};

package/schematics/ng-add/files/app/app.describer.ts.template

@@ -0,0 +1,30 @@
+import { AppDescriber } from '@open-rlb/ng-app';
+import { routes } from './app.routes';
+
+/**
+ * Describes this app's identity and capabilities to @open-rlb/ng-app.
+ * `actions` are the ACL action names this app understands (used by `permissionGuard`
+ * and the `*roles` directive). Adjust `info` and `actions` to match your app.
+ */
+export const appDescriber: AppDescriber = {
+  info: {
+    type: 'app',
+    enabled: true,
+    actions: ['sysadmin'],
+    core: {
+      title: 'Home',
+      description: 'Application home',
+      url: 'home',
+      icon: 'bi bi-house',
+      auth: true,
+    },
+    settings: {
+      title: 'Settings',
+      description: 'Application settings',
+      url: 'settings',
+      icon: 'bi bi-gear',
+      auth: true,
+    },
+  },
+  routes,
+};

package/schematics/ng-add/files/app/app.routes.ts.template

@@ -0,0 +1,21 @@
+import { Routes } from '@angular/router';
+import { HomeComponent } from './home/home.component';
+
+export const routes: Routes = [
+  {
+    path: '',
+    data: { template: 'app' },
+    component: HomeComponent,
+  },
+  {
+    path: 'home',
+    component: HomeComponent,
+  },
+  // Example of a route guarded by an ACL action:
+  // {
+  //   path: 'protected',
+  //   component: ProtectedComponent,
+  //   canActivate: [permissionGuard],
+  //   data: { action: 'sysadmin' },
+  // },
+];

package/schematics/ng-add/files/app/home/home.component.html.template

@@ -0,0 +1,4 @@
+<div class="container py-4">
+  <h1>{{ title }}</h1>
+  <p>Your @open-rlb/ng-app shell is running. Edit <code>src/app/home/home.component.html</code> to get started.</p>
+</div>

package/schematics/ng-add/files/app/home/home.component.ts.template

@@ -0,0 +1,13 @@
+import { CommonModule } from '@angular/common';
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { RlbAppModule } from '@open-rlb/ng-app';
+
+@Component({
+  selector: 'app-home',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [CommonModule, RlbAppModule],
+  templateUrl: './home.component.html',
+})
+export class HomeComponent {
+  title = 'Home';
+}

package/schematics/ng-add/files/assets/i18n/en.json

@@ -0,0 +1,106 @@
+{
+  "common": {
+    "ok": "Ok",
+    "cancel": "Cancel",
+    "close": "Close",
+    "save": "Save",
+    "delete": "Delete",
+    "add": "Add",
+    "edit": "Edit",
+    "name": "Name",
+    "description": "Description",
+    "search": "Search",
+    "searching": "Searching...",
+    "noResults": "No results",
+    "loading": "Loading...",
+    "yes": "Yes",
+    "no": "No"
+  },
+  "core": {
+    "apps": {
+      "button": "Apps",
+      "title": "Riolabs Apps"
+    },
+    "settings": {
+      "title": "Settings",
+      "generalTitle": "General settings",
+      "generalDescription": "Manage general settings of applications",
+      "support": "Support",
+      "privacy": "Privacy",
+      "cookies": "Cookies",
+      "legal": "Legal",
+      "status": "Status",
+      "logger": "Logger"
+    },
+    "account": {
+      "title": "Account",
+      "email": "Email",
+      "changePassword": "Change password",
+      "firstName": "First name",
+      "lastName": "Last name",
+      "login": "Login",
+      "logout": "Logout",
+      "username": "Username",
+      "session": {
+        "title": "Sessions",
+        "current": "Current session",
+        "ip": "IP",
+        "applications": "Applications",
+        "lastAccess": "Last access",
+        "started": "Started",
+        "expires": "Expires"
+      },
+      "credentials": {
+        "title": "Credentials",
+        "password": "Password",
+        "otp": "One-time password",
+        "name": "Name",
+        "created": "Created",
+        "actions": "Actions",
+        "update": "Update",
+        "delete": "Delete",
+        "noCredentials": "No credentials found for this section",
+        "addOTP": "Configure OTP",
+        "deleteTitle": "Delete credential",
+        "deleteHeader": "Delete credential confirmation",
+        "deleteMessage": "Are you sure you want to delete this credential?"
+      },
+      "settings": {
+        "title": "Account settings",
+        "showMore": "Show more"
+      }
+    },
+    "pwa": {
+      "newVersionAvailable": "New version available",
+      "updateNow": "Update now",
+      "updateMessage": "A new version of the application is available. Do you want to update it now?",
+      "later": "Later",
+      "update": "Update"
+    }
+  },
+  "pages": {
+    "notFound": {
+      "title": "Page not found",
+      "content": "The page you are looking for does not exist.",
+      "button": "Go to home page"
+    },
+    "forbidden": {
+      "title": "Access forbidden",
+      "content": "You do not have permission to access this page.",
+      "button": "Go to home page"
+    },
+
+    "support": {
+      "title": "Support",
+      "legal": "Legal",
+      "name": "Name",
+      "email": "Email",
+      "subject": "Subject",
+      "message": "Message",
+      "send": "Send",
+      "success": "Your message has been sent successfully.",
+      "error": "An error occurred while sending your message.",
+      "infoPage": "For more information, please visit our legal page"
+    }
+  }
+}

package/schematics/ng-add/files/assets/i18n/it.json

@@ -0,0 +1,101 @@
+{
+  "common": {
+    "ok": "Ok",
+    "cancel": "Annulla",
+    "close": "Chiudi",
+    "save": "Salva",
+    "delete": "Elimina",
+    "add": "Aggiungi",
+    "edit": "Modifica",
+    "name": "Nome",
+    "description": "Descrizione",
+    "search": "Cerca",
+    "searching": "Ricerca in corso...",
+    "noResults": "Nessun risultato",
+    "loading": "Caricamento...",
+    "yes": "Sì",
+    "no": "No"
+  },
+  "core": {
+    "apps": {
+      "button": "Applicazioni",
+      "title": "App di Riolabs"
+    },
+    "settings": {
+      "title": "Impostazioni",
+      "generalTitle": "Impostazioni generali",
+      "generalDescription": "Gestisci le impostazioni generali delle applicazioni",
+      "support": "Supporto",
+      "privacy": "Privacy",
+      "cookies": "Cookie",
+      "legal": "Legale",
+      "status": "Stato",
+      "logger": "Logger"
+    },
+    "account": {
+      "title": "Account",
+      "email": "Email",
+      "changePassword": "Cambia password",
+      "firstName": "Nome",
+      "lastName": "Cognome",
+      "login": "Accesso",
+      "logout": "Esci",
+      "username": "Nome utente",
+      "session": {
+        "title": "Sessioni",
+        "current": "Sessione corrente",
+        "ip": "IP",
+        "applications": "Applicazioni",
+        "lastAccess": "Ultimo accesso",
+        "started": "Iniziata",
+        "expires": "Scade il"
+      },
+      "credentials": {
+        "title": "Credenziali",
+        "password": "Password",
+        "otp": "Password monouso",
+        "name": "Nome",
+        "created": "Creato",
+        "actions": "Azioni",
+        "update": "Aggiorna",
+        "delete": "Elimina",
+        "noCredentials": "Nessuna credenziale trovata per questa sezione",
+        "addOTP": "Configura OTP",
+        "deleteTitle": "Elimina credenziale",
+        "deleteHeader": "Conferma eliminazione credenziale",
+        "deleteMessage": "Sei sicuro di voler eliminare questa credenziale?"
+      }
+    },
+    "pwa": {
+      "newVersionAvailable": "Nuova versione disponibile",
+      "updateNow": "Aggiorna ora",
+      "updateMessage": "È disponibile una nuova versione dell'applicazione. Vuoi aggiornarla ora?",
+      "later": "Dopo",
+      "update": "Aggiorna"
+    }
+  },
+  "pages": {
+    "notFound": {
+      "title": "Pagina non trovata",
+      "content": "La pagina che stai cercando non esiste.",
+      "button": "Vai alla home page"
+    },
+    "forbidden": {
+      "title": "Accesso negato",
+      "content": "Non hai i permessi necessari per accedere a questa pagina.",
+      "button": "Vai alla home page"
+    },
+    "support": {
+      "title": "Supporto",
+      "legal": "Legale",
+      "name": "Nome",
+      "email": "Email",
+      "subject": "Oggetto",
+      "message": "Messaggio",
+      "send": "Invia",
+      "success": "Il tuo messaggio è stato inviato con successo.",
+      "error": "Si è verificato un errore durante l'invio del messaggio.",
+      "infoPage": "Per maggiori informazioni, visita la nostra pagina legale"
+    }
+  }
+}

package/schematics/ng-add/files/environments/environment.ts.template

@@ -0,0 +1,86 @@
+import { ProjectConfiguration } from '@open-rlb/ng-app';
+
+/**
+ * Application configuration consumed by `provideRlbConfig(environment)`.
+ *
+ * ⚠ Replace the placeholder values below with your real settings:
+ *   - auth.providers[].authority / clientId / redirectUrl / postLogoutRedirectUri
+ *   - auth.allowedUrls and endpoints[].baseUrl (your API gateway URLs)
+ */
+export const environment: ProjectConfiguration = {
+  production: false,
+  environment: {
+    baseUrl: 'http://localhost:4200',
+    ssr: false,
+    phone: false,
+    appLogo: '', // set to your logo path, e.g. 'assets/logo.svg' (place the file under src/assets)
+    appTitle: 'My App',
+    navbarDisabled: false,
+    errorDialogName: 'error-modal-component',
+    pwaUpdateEnabled: true,
+    errorDialogSize: 'md',
+    logLevel: 'log',
+  },
+  i18n: {
+    availableLangs: ['en', 'it'],
+    defaultLanguage: 'en',
+    useLanguageBrowser: true,
+    storeSelectedLanguage: true,
+    cookieStoreName: 'language',
+  },
+  auth: {
+    protocol: 'oauth',
+    storage: 'localStorage',
+    interceptor: 'oauth-code-ep',
+    allowedUrls: ['https://api.example.com'],
+    enableCompanyInterceptor: true,
+    providers: [
+      {
+        configId: 'default',
+        authority: 'https://login.example.com/realms/your-realm',
+        domains: ['localhost'],
+        redirectUrl: 'http://localhost:4200',
+        postLogoutRedirectUri: 'http://localhost:4200',
+        clientId: 'your-client-id',
+        scope: 'openid profile offline_access',
+        logLevel: 2,
+        acl: {
+          endpointKey: 'http-gateway',
+          path: 'admin/acl/resources',
+        },
+      },
+    ],
+  },
+  pages: {
+    content: { path: 'content' },
+    cookies: { path: 'cookies' },
+    notFound: { path: 'not-found' },
+    forbidden: { path: 'forbidden' },
+    privacy: { path: 'privacy' },
+    support: { path: 'support' },
+    terms: { path: 'terms' },
+    status: { path: 'status' },
+    logger: { path: 'logger' },
+  },
+  endpoints: {
+    'http-gateway': {
+      baseUrl: 'https://api.example.com',
+      auth: true,
+      healthPath: 'health',
+      wss: false,
+    },
+    'ws-gateway': {
+      baseUrl: 'wss://api.example.com',
+      healthPath: 'health',
+      auth: true,
+      wss: true,
+    },
+  },
+  acl: {
+    businessIdKey: 'businessId',
+    resourceIdKey: 'resourceId',
+    interceptorMapping: {
+      companyId: 'companyId',
+    },
+  },
+};

package/schematics/ng-add/files/main.ts.template

@@ -0,0 +1,5 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+import { appConfig } from './app/app.config';
+import { AppComponent } from './app/app.component';
+
+bootstrapApplication(AppComponent, appConfig).catch(err => console.error(err));

package/schematics/ng-add/index.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ngAdd = ngAdd;
+const core_1 = require("@angular-devkit/core");
+const schematics_1 = require("@angular-devkit/schematics");
+const utility_1 = require("@schematics/angular/utility");
+/**
+ * Dependencies the library needs at the consumer side. `@angular/{core,common,forms,router}`
+ * and `rxjs` are intentionally omitted: every Angular app already provides them. Versions mirror
+ * the ranges declared in the library's `peerDependencies`.
+ */
+const DEPENDENCIES = [
+    { name: '@open-rlb/ng-bootstrap', version: '^3.0.1', type: utility_1.DependencyType.Default },
+    { name: '@open-rlb/date-tz', version: '^2.1.1', type: utility_1.DependencyType.Default },
+    { name: '@ngrx/store', version: '^21.0.0', type: utility_1.DependencyType.Default },
+    { name: '@ngrx/effects', version: '^21.0.0', type: utility_1.DependencyType.Default },
+    { name: '@ngrx/operators', version: '^21.0.0', type: utility_1.DependencyType.Default },
+    { name: '@ngrx/signals', version: '^21.0.0', type: utility_1.DependencyType.Default },
+    { name: '@ngx-translate/core', version: '^17.0.0', type: utility_1.DependencyType.Default },
+    { name: '@ngx-translate/http-loader', version: '^17.0.0', type: utility_1.DependencyType.Default },
+    { name: 'angular-auth-oidc-client', version: '^19.0.1', type: utility_1.DependencyType.Default },
+    { name: 'ngx-cookie-service', version: '^21.1.0', type: utility_1.DependencyType.Default },
+    { name: 'ngx-cookie-service-ssr', version: '^21.1.0', type: utility_1.DependencyType.Default },
+    { name: '@angular/service-worker', version: '^21.0.0', type: utility_1.DependencyType.Default },
+    { name: 'bootstrap-icons', version: '^1.13.1', type: utility_1.DependencyType.Default },
+    { name: '@types/bootstrap', version: '^5.2.10', type: utility_1.DependencyType.Dev },
+];
+/** Global styles required for the Bootstrap + @open-rlb/ng-bootstrap look & feel. */
+const STYLE_PATHS = [
+    'node_modules/bootstrap-icons/font/bootstrap-icons.css',
+    'node_modules/@open-rlb/ng-bootstrap/assets/scss/app.scss',
+    'node_modules/@open-rlb/ng-bootstrap/assets/scss/icons.scss',
+];
+/** SCSS `@use`/`@import` resolution root needed by the ng-bootstrap stylesheets. */
+const STYLE_INCLUDE_PATH = 'node_modules';
+/** Source folder for the scaffolded runtime assets (i18n JSON, logo), served at `/assets`. */
+const ASSETS_INPUT = 'src/assets';
+function ngAdd(options) {
+    return async (tree, _context) => {
+        const project = await resolveProject(tree, options.project);
+        return (0, schematics_1.chain)([
+            // 1. Install dependencies (a single npm install is scheduled automatically).
+            ...DEPENDENCIES.map(dep => (0, utility_1.addDependency)(dep.name, dep.version, { type: dep.type })),
+            // 2. Register Bootstrap + ng-bootstrap global styles and the SCSS include path in angular.json.
+            addBootstrapStyles(project),
+            // 3. Scaffold the runnable application shell (providers, environment, app component, routes).
+            options.skipShell ? noop : scaffoldShell(tree, project),
+            // 4. Optionally copy the bundled Claude skills into .claude/skills.
+            options.skipSkills ? noop : copyClaudeSkills(),
+            // 5. Print next steps.
+            logNextSteps(project, options),
+        ]);
+    };
+}
+/** Resolves the target project: the provided name, else the first application, else the first project. */
+async function resolveProject(tree, name) {
+    const workspace = await (0, utility_1.readWorkspace)(tree);
+    if (name) {
+        if (!workspace.projects.has(name)) {
+            throw new schematics_1.SchematicsException(`Project "${name}" was not found in the workspace.`);
+        }
+        return name;
+    }
+    for (const [projectName, project] of workspace.projects) {
+        if (project.extensions['projectType'] === 'application') {
+            return projectName;
+        }
+    }
+    const first = workspace.projects.keys().next().value;
+    if (!first) {
+        throw new schematics_1.SchematicsException('No project found in the workspace to add @open-rlb/ng-app to.');
+    }
+    return first;
+}
+function addBootstrapStyles(project) {
+    return (0, utility_1.updateWorkspace)(workspace => {
+        const target = workspace.projects.get(project)?.targets.get('build');
+        if (!target) {
+            return;
+        }
+        target.options ??= {};
+        const styles = target.options['styles'] ?? [];
+        for (const style of STYLE_PATHS) {
+            const present = styles.some(s => (typeof s === 'string' ? s : s.input) === style);
+            if (!present) {
+                styles.unshift(style);
+            }
+        }
+        target.options['styles'] = styles;
+        const preprocessor = target.options['stylePreprocessorOptions'] ?? {};
+        const includePaths = preprocessor.includePaths ?? [];
+        if (!includePaths.includes(STYLE_INCLUDE_PATH)) {
+            includePaths.push(STYLE_INCLUDE_PATH);
+        }
+        preprocessor.includePaths = includePaths;
+        target.options['stylePreprocessorOptions'] = preprocessor;
+        const assets = target.options['assets'] ?? [];
+        const servesAssets = assets.some(a => {
+            const input = typeof a === 'string' ? a : a.input;
+            return input === ASSETS_INPUT;
+        });
+        if (!servesAssets) {
+            assets.push({ glob: '**/*', input: ASSETS_INPUT, output: 'assets' });
+        }
+        target.options['assets'] = assets;
+    });
+}
+function scaffoldShell(tree, project) {
+    return async () => {
+        const workspace = await (0, utility_1.readWorkspace)(tree);
+        const def = workspace.projects.get(project);
+        const sourceRoot = def?.sourceRoot ?? (def ? `${def.root}/src` : 'src');
+        const templates = (0, schematics_1.apply)((0, schematics_1.url)('./files'), [
+            (0, schematics_1.applyTemplates)({ ...core_1.strings }),
+            (0, schematics_1.move)(sourceRoot),
+        ]);
+        // Overwrite the core shell files: ng add assumes a fresh/near-fresh app and the shell is the
+        // deliverable. Existing files (e.g. the default app.config.ts from `ng new`) are replaced.
+        return (0, schematics_1.mergeWith)(templates, schematics_1.MergeStrategy.Overwrite);
+    };
+}
+/**
+ * Copies the Claude skills bundled with the package into the consumer's
+ * `.claude/skills` folder. Library-authored skills are authoritative, so existing
+ * copies are overwritten to stay in sync with the installed version.
+ */
+function copyClaudeSkills() {
+    const skills = (0, schematics_1.apply)((0, schematics_1.url)('./claude-skills'), [(0, schematics_1.move)('.claude/skills')]);
+    return (0, schematics_1.mergeWith)(skills, schematics_1.MergeStrategy.Overwrite);
+}
+function logNextSteps(project, options) {
+    return (_tree, context) => {
+        const log = context.logger;
+        log.info('');
+        log.info('✅ @open-rlb/ng-app added successfully.');
+        log.info('   • Dependencies installed and added to package.json');
+        log.info('   • Bootstrap + ng-bootstrap styles registered in angular.json');
+        if (!options.skipShell) {
+            log.info(`   • Application shell scaffolded into the "${project}" app:`);
+            log.info('     - src/main.ts bootstraps the AppComponent shell');
+            log.info('     - src/environments/environment.ts (config: auth, endpoints, i18n, pages, acl)');
+            log.info('     - src/app/app.config.ts (provideRlbConfig + provideApp + RLB_INIT_PROVIDER)');
+            log.info('     - src/app/app.component.ts (<rlb-app-container> shell), app.describer.ts, routes, home');
+            log.info('     A default root component from `ng new` (e.g. src/app/app.ts) is now unused and can be deleted.');
+        }
+        if (!options.skipSkills) {
+            log.info('   • Claude skills copied to .claude/skills/ (rlb-app-* guides)');
+        }
+        log.info('');
+        log.info('⚠ Before running: edit src/environments/environment.ts and replace the placeholder');
+        log.info('  OIDC authority/clientId/redirectUrl and endpoint baseUrls with your real values.');
+        log.info('  Then start the app with: ng serve');
+        log.info('');
+    };
+}
+/** A no-op rule. */
+const noop = tree => tree;

package/schematics/ng-add/schema.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/schematics/ng-add/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "OpenRlbNgAppNgAdd",
+  "title": "@open-rlb/ng-app ng-add schematic",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The name of the project to add the library to.",
+      "$default": {
+        "$source": "projectName"
+      }
+    },
+    "skipShell": {
+      "type": "boolean",
+      "default": false,
+      "description": "Do not scaffold the application shell (environment, providers, app component, routes, home)."
+    },
+    "skipSkills": {
+      "type": "boolean",
+      "default": false,
+      "description": "Do not copy the bundled Claude skills into .claude/skills."
+    }
+  },
+  "required": []
+}

package/schematics/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}