@unopsitg/ux 21.1.0 → 21.1.1

package/AGENTS.md

@@ -0,0 +1,72 @@
+# @unopsitg/ux — AI Agent Integration Guide
+
+This file is for AI coding assistants (Cursor, Claude Code, Copilot, etc.) working in projects that depend on `@unopsitg/ux`.
+
+## What this library provides
+
+- **Layout shell** — full application chrome (sidebar, topbar, breadcrumb, configurator)
+- **Brand theme** — PrimeNG / PrimeUIX preset (`BrandSoft`) with UNOPS brand colors
+- **Tailwind CSS** — design tokens, custom utilities, and component animations
+- **Shared types** — demo data interfaces
+
+## Quick setup (or run `ng add @unopsitg/ux`)
+
+1. Create `.postcssrc.json` (not `.mjs` — Angular 21 esbuild ignores `.mjs`):
+   ```json
+   { "plugins": { "@tailwindcss/postcss": {} } }
+   ```
+
+2. Create `src/tailwind.css`:
+   ```css
+   @import "../node_modules/@unopsitg/ux/assets/tailwind.css";
+   @source "../node_modules/@unopsitg/ux/fesm2022";
+   ```
+
+3. In `angular.json` styles:
+   ```json
+   ["node_modules/@unopsitg/ux/assets/styles.scss", "src/tailwind.css", "node_modules/primeicons/primeicons.css", "src/styles.scss"]
+   ```
+
+4. In `angular.json` assets:
+   ```json
+   { "glob": "**/*", "input": "node_modules/@unopsitg/ux/assets/opp", "output": "assets/opp" }
+   ```
+
+5. In `app.config.ts` providers:
+   ```typescript
+   import { providePrimeNG } from 'primeng/config';
+   import { BrandSoft, TOPBAR_PROFILE_MENU_CONFIG, LayoutService } from '@unopsitg/ux';
+
+   providePrimeNG({ theme: { preset: BrandSoft, options: { darkModeSelector: '.app-dark' } } })
+   ```
+
+## Critical rules
+
+- **NEVER** put `@source` directives in `.scss` files — Sass passes them through as inert text.
+- **NEVER** use `postcss.config.mjs` — Angular 21 esbuild silently ignores it.
+- **NEVER** reference `node_modules/@unopsitg/ux/assets/tailwind.css` directly in `angular.json` — use the `src/tailwind.css` wrapper for correct `@source` path resolution.
+- Shell-critical utilities (`.hidden`, `.animate-scalein`, `.animate-fadeout`) ship as real CSS. Do not redefine them.
+
+## Injection tokens
+
+| Token | Purpose | Shape |
+|-------|---------|-------|
+| `MENU_MODEL` | Sidebar menu tree | `MenuItem[]` |
+| `SIDEBAR_LOGO` | Expanded/compact logo URLs | `{ expanded, compact, alt }` |
+| `TOPBAR_MOBILE_LOGO` | Mobile header logos | `{ light, dark }` |
+| `TOPBAR_PROFILE_MENU_CONFIG` | Profile dropdown items | `{ items: { id, label, icon, command?, separator? }[] }` |
+
+## Theme initialization
+
+`LayoutService` defaults to `darkTheme: true`. To avoid a flash of light mode, add an `APP_INITIALIZER`:
+
+```typescript
+import { APP_INITIALIZER } from '@angular/core';
+import { LayoutService } from '@unopsitg/ux';
+
+{ provide: APP_INITIALIZER, useFactory: (ls: LayoutService) => () => ls.toggleDarkMode(), deps: [LayoutService], multi: true }
+```
+
+## Full documentation
+
+See `README.md` in this package for complete configuration reference.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unopsitg/ux",
-  "version": "21.1.0",
+  "version": "21.1.1",
   "description": "UNOPS Angular 21 layout shell, brand theme (PrimeNG / PrimeUIX), and shared types",
   "keywords": [
     "angular",
@@ -9,6 +9,10 @@
     "layout"
   ],
   "license": "UNLICENSED",
+  "schematics": "./schematics/collection.json",
+  "ng-add": {
+    "save": "dependencies"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/opp_plus/unops-ng21_ux.git"

package/schematics/collection.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
+  "schematics": {
+    "ng-add": {
+      "description": "Set up @unopsitg/ux in an Angular project",
+      "factory": "./ng-add/index#ngAdd",
+      "schema": "./ng-add/schema.json"
+    }
+  }
+}

package/schematics/ng-add/index.d.ts

@@ -0,0 +1,7 @@
+import { Rule } from '@angular-devkit/schematics';
+interface Schema {
+    project?: string;
+    darkMode?: boolean;
+}
+export declare function ngAdd(options: Schema): Rule;
+export {};

package/schematics/ng-add/index.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ngAdd = ngAdd;
+const schematics_1 = require("@angular-devkit/schematics");
+const tasks_1 = require("@angular-devkit/schematics/tasks");
+const PEER_DEPS = {
+    primeng: '^21.0.4',
+    '@primeuix/themes': '^2.0.0',
+    primeicons: '^7.0.0',
+    '@tailwindcss/postcss': '^4.0.0',
+    'tailwindcss': '^4.0.0',
+};
+const STYLES_ENTRIES = [
+    'node_modules/@unopsitg/ux/assets/styles.scss',
+    'src/tailwind.css',
+    'node_modules/primeicons/primeicons.css',
+    'src/styles.scss',
+];
+const ASSETS_ENTRY = {
+    glob: '**/*',
+    input: 'node_modules/@unopsitg/ux/assets/opp',
+    output: 'assets/opp',
+};
+function ngAdd(options) {
+    return (0, schematics_1.chain)([
+        addPeerDependencies(),
+        createPostcssConfig(),
+        createTailwindWrapper(),
+        patchAngularJson(options),
+        patchAppConfig(options),
+        createCursorRule(),
+        installDependencies(),
+    ]);
+}
+function addPeerDependencies() {
+    return (tree) => {
+        const pkgPath = '/package.json';
+        const buffer = tree.read(pkgPath);
+        if (!buffer) {
+            throw new schematics_1.SchematicsException('Could not find package.json');
+        }
+        const pkg = JSON.parse(buffer.toString('utf-8'));
+        if (!pkg.dependencies) {
+            pkg.dependencies = {};
+        }
+        for (const [name, version] of Object.entries(PEER_DEPS)) {
+            if (!pkg.dependencies[name] && !pkg.devDependencies?.[name]) {
+                pkg.dependencies[name] = version;
+            }
+        }
+        tree.overwrite(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+        return tree;
+    };
+}
+function createPostcssConfig() {
+    return (tree) => {
+        const path = '/.postcssrc.json';
+        if (tree.exists(path)) {
+            return tree;
+        }
+        tree.create(path, JSON.stringify({ plugins: { '@tailwindcss/postcss': {} } }, null, 2) + '\n');
+        return tree;
+    };
+}
+function createTailwindWrapper() {
+    return (tree) => {
+        const path = '/src/tailwind.css';
+        if (tree.exists(path)) {
+            return tree;
+        }
+        tree.create(path, [
+            '@import "../node_modules/@unopsitg/ux/assets/tailwind.css";',
+            '@source "../node_modules/@unopsitg/ux/fesm2022";',
+            '',
+        ].join('\n'));
+        return tree;
+    };
+}
+function patchAngularJson(options) {
+    return (tree) => {
+        const angularJsonPath = '/angular.json';
+        const buffer = tree.read(angularJsonPath);
+        if (!buffer) {
+            throw new schematics_1.SchematicsException('Could not find angular.json');
+        }
+        const workspace = JSON.parse(buffer.toString('utf-8'));
+        const projectName = options.project || workspace.defaultProject || Object.keys(workspace.projects)[0];
+        const project = workspace.projects[projectName];
+        if (!project) {
+            throw new schematics_1.SchematicsException(`Project "${projectName}" not found in angular.json`);
+        }
+        const buildTarget = project.architect?.build || project.targets?.build;
+        if (!buildTarget) {
+            throw new schematics_1.SchematicsException(`No build target found for project "${projectName}"`);
+        }
+        const buildOptions = buildTarget.options || (buildTarget.options = {});
+        // Patch styles
+        const styles = buildOptions.styles || [];
+        const desiredStyles = STYLES_ENTRIES.filter((s) => !styles.includes(s));
+        if (desiredStyles.length > 0) {
+            const srcStylesIdx = styles.indexOf('src/styles.scss');
+            if (srcStylesIdx >= 0) {
+                // Insert library styles before src/styles.scss
+                const before = desiredStyles.filter((s) => s !== 'src/styles.scss');
+                styles.splice(srcStylesIdx, 0, ...before);
+            }
+            else {
+                styles.push(...desiredStyles);
+            }
+            buildOptions.styles = styles;
+        }
+        // Patch assets
+        const assets = buildOptions.assets || [];
+        const hasOppAsset = assets.some((a) => typeof a === 'object' && a.input === ASSETS_ENTRY.input);
+        if (!hasOppAsset) {
+            assets.push(ASSETS_ENTRY);
+            buildOptions.assets = assets;
+        }
+        tree.overwrite(angularJsonPath, JSON.stringify(workspace, null, 2) + '\n');
+        return tree;
+    };
+}
+function patchAppConfig(options) {
+    return (tree) => {
+        const configPath = '/src/app/app.config.ts';
+        if (!tree.exists(configPath)) {
+            // Try alternate path
+            const altPath = '/src/app.config.ts';
+            if (!tree.exists(altPath)) {
+                return tree;
+            }
+            return patchConfigFile(tree, altPath, options);
+        }
+        return patchConfigFile(tree, configPath, options);
+    };
+}
+function patchConfigFile(tree, path, options) {
+    const content = tree.read(path).toString('utf-8');
+    if (content.includes('@unopsitg/ux')) {
+        return tree;
+    }
+    const darkMode = options.darkMode !== false;
+    const importBlock = [
+        "import { providePrimeNG } from 'primeng/config';",
+        "import { BrandSoft, TOPBAR_PROFILE_MENU_CONFIG, LayoutService } from '@unopsitg/ux';",
+    ].join('\n');
+    const providerBlock = `    providePrimeNG({ theme: { preset: BrandSoft, options: { darkModeSelector: '.app-dark' } } }),`;
+    // Insert imports at the top (after existing imports)
+    const lastImportIdx = content.lastIndexOf('\nimport ');
+    let result;
+    if (lastImportIdx >= 0) {
+        const endOfImportLine = content.indexOf('\n', lastImportIdx + 1);
+        result =
+            content.slice(0, endOfImportLine + 1) +
+                importBlock +
+                '\n' +
+                content.slice(endOfImportLine + 1);
+    }
+    else {
+        result = importBlock + '\n\n' + content;
+    }
+    // Insert provider into providers array
+    const providersMatch = result.match(/providers\s*:\s*\[/);
+    if (providersMatch && providersMatch.index != null) {
+        const insertPos = providersMatch.index + providersMatch[0].length;
+        result =
+            result.slice(0, insertPos) + '\n' + providerBlock + '\n' + result.slice(insertPos);
+    }
+    tree.overwrite(path, result);
+    return tree;
+}
+function createCursorRule() {
+    return (tree) => {
+        const rulePath = '/.cursor/rules/unopsitg-ux.mdc';
+        if (tree.exists(rulePath)) {
+            return tree;
+        }
+        const content = `---
+description: Integration rules for @unopsitg/ux library
+globs: ["**/*.{ts,html,scss,css,json}"]
+alwaysApply: false
+---
+
+# @unopsitg/ux Integration
+
+This project uses the @unopsitg/ux Angular library for its layout shell, brand theme, and shared components.
+
+## Critical Integration Invariants
+
+1. **PostCSS config must be JSON format** — use \`.postcssrc.json\`, never \`.mjs\`. Angular 21 esbuild silently ignores \`.mjs\` configs.
+2. **Never put \`@source\` directives in \`.scss\` files** — Sass copies them as inert text. Use \`src/tailwind.css\` (a plain CSS file) for Tailwind directives.
+3. **The \`src/tailwind.css\` wrapper** resolves \`@source\` paths from the project root where Angular runs PostCSS. Do not reference the library's \`assets/tailwind.css\` directly in \`angular.json\`.
+4. **Shell utilities** (\`.hidden\`, \`.animate-scalein\`, \`.animate-fadeout\`) are shipped as real CSS in the library. Do not redefine them.
+
+## Available Injection Tokens
+
+| Token | Purpose | Shape |
+|-------|---------|-------|
+| \`MENU_MODEL\` | Sidebar menu tree | \`MenuItem[]\` |
+| \`SIDEBAR_LOGO\` | Expanded/compact logo URLs | \`{ expanded, compact, alt }\` |
+| \`TOPBAR_MOBILE_LOGO\` | Mobile header logos | \`{ light, dark }\` |
+| \`TOPBAR_PROFILE_MENU_CONFIG\` | Profile dropdown items | \`{ items: { id, label, icon, command?, separator? }[] }\` |
+
+## Theme
+
+- \`LayoutService.layoutConfig()\` holds the active theme state.
+- \`LayoutService.toggleDarkMode()\` synchronizes \`.app-dark\` on \`<html>\`.
+- Use an \`APP_INITIALIZER\` to call \`toggleDarkMode()\` at startup to avoid a flash of wrong theme.
+
+## Full Documentation
+
+See \`node_modules/@unopsitg/ux/README.md\` for complete setup and configuration.
+`;
+        tree.create(rulePath, content);
+        return tree;
+    };
+}
+function installDependencies() {
+    return (_tree, context) => {
+        context.addTask(new tasks_1.NodePackageInstallTask());
+    };
+}

package/schematics/ng-add/schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "SchematicsUnopsUxNgAdd",
+  "title": "UNOPS UX ng-add schematic",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The project to add @unopsitg/ux to.",
+      "$default": {
+        "$source": "projectName"
+      }
+    },
+    "darkMode": {
+      "type": "boolean",
+      "default": true,
+      "description": "Whether the app starts in dark mode."
+    }
+  },
+  "required": []
+}