@unopsitg/ux 21.1.0 → 21.2.0

package/AGENTS.md

@@ -0,0 +1,86 @@
+# @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 (Tailwind v4 source file)
+- **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 "tailwindcss";
+   @import "@unopsitg/ux/tailwind";
+   ```
+
+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. Install dev dependencies:
+   ```bash
+   npm install -D @tailwindcss/postcss tailwindcss postcss
+   ```
+
+6. 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** add `node_modules/@unopsitg/ux/assets/tailwind.css` directly to `angular.json` styles — Angular's esbuild does NOT run PostCSS on node_modules CSS, so all directives pass through as raw text and zero utilities are generated.
+- **ALWAYS** use `src/tailwind.css` with `@import "@unopsitg/ux/tailwind"` — this lives in the source tree where PostCSS processes it.
+- **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.
+- Shell-critical utilities (`.hidden`, `.animate-scalein`, `.animate-fadeout`) ship as real CSS. Do not redefine them.
+
+## Package exports
+
+| Import path | Resolves to |
+|-------------|-------------|
+| `@unopsitg/ux` | `fesm2022/unopsitg-ux.mjs` (Angular library) |
+| `@unopsitg/ux/tailwind` | `assets/tailwind.css` (Tailwind v4 source) |
+| `@unopsitg/ux/styles` | `assets/styles.scss` (layout SCSS) |
+
+## 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/README.md

@@ -44,11 +44,25 @@ export const appConfig: ApplicationConfig = {
 
 ## Styles and assets
 
-Reference library SCSS/Tailwind and copy bundled logos into your app output:
+### Automated setup
 
-### PostCSS configuration
+```bash
+ng add @unopsitg/ux
+```
+
+This creates all required files and patches `angular.json` + `app.config.ts` automatically. The rest of this section documents the manual equivalent.
+
+### Understanding `assets/tailwind.css`
+
+The library ships `assets/tailwind.css` as a **Tailwind v4 source file** — it contains `@plugin`, `@source`, `@theme`, and `@utility` directives that must be processed by `@tailwindcss/postcss` to generate utility classes.
 
-Angular 21's `application` builder (esbuild) only loads JSON-format PostCSS configs. Create `.postcssrc.json` in the project root:
+> **Do NOT add `assets/tailwind.css` directly to angular.json styles.** Angular's esbuild/Vite builder does not run PostCSS on CSS files referenced from `node_modules` — it inlines them as raw text. All directives will appear literally in the browser output and zero utilities will be generated.
+
+### Manual setup
+
+#### 1. PostCSS configuration
+
+Angular 21's `application` builder only loads JSON-format PostCSS configs. Create `.postcssrc.json` in the project root:
 
 ```json
 {
@@ -58,9 +72,20 @@ Angular 21's `application` builder (esbuild) only loads JSON-format PostCSS conf
 }
 ```
 
-> **Warning:** `.mjs` configs (`postcss.config.mjs`) are silently ignored by esbuild. If Tailwind directives pass through unprocessed, check the config format first.
+> **Warning:** `.mjs` configs (`postcss.config.mjs`) are silently ignored by esbuild.
+
+#### 2. Tailwind entry point
+
+Create `src/tailwind.css` — this lives in your source tree so Angular **will** run PostCSS on it:
+
+```css
+@import "tailwindcss";
+@import "@unopsitg/ux/tailwind";
+```
+
+The `@unopsitg/ux/tailwind` export resolves to the library's `assets/tailwind.css` via the package `exports` field. The file includes brand tokens, custom utilities, and a `@source` directive that scans the library's compiled JS for class references.
 
-### angular.json styles and assets
+#### 3. angular.json styles and assets
 
 ```json
 "styles": [
@@ -75,23 +100,20 @@ Angular 21's `application` builder (esbuild) only loads JSON-format PostCSS conf
 ]
 ```
 
-### Tailwind content scan
+#### 4. Dev dependencies
 
-Library components use Tailwind utility classes. Tailwind 4 only generates utilities for classes it finds in scanned sources. The library's `assets/tailwind.css` contains a `@source "../fesm2022"` directive, but Angular resolves this relative to the **project root** — not the package directory. To fix path resolution, create a thin wrapper CSS file:
-
-```css
-/* src/tailwind.css */
-@import "../node_modules/@unopsitg/ux/assets/tailwind.css";
-@source "../node_modules/@unopsitg/ux/fesm2022";
+```bash
+npm install -D @tailwindcss/postcss tailwindcss postcss
 ```
 
-Reference `src/tailwind.css` in `angular.json` styles (as shown above) instead of the library file directly. The `@source` in your wrapper resolves from the project root where Angular actually runs PostCSS.
-
-> **Do not** put `@source` directives in `.scss` files — Sass copies them as inert text and PostCSS/Tailwind never processes them.
+### Troubleshooting
 
-**Verify:** after `ng serve`, check the compiled CSS for `.flex { display: flex }`. If missing, the `@source` path is wrong.
+- **Tailwind directives appear as raw text in browser CSS** — you added the library's CSS directly to `angular.json` instead of using `src/tailwind.css`.
+- **"The path './assets/tailwind.css' is not exported"** — upgrade to `@unopsitg/ux@21.2.0+` which adds the `./tailwind` export.
+- **Zero utilities generated** — verify `.postcssrc.json` exists (not `.mjs`) and `src/tailwind.css` is in the styles array.
+- **Do not** put `@source` directives in `.scss` files — Sass copies them as inert text.
 
-When developing **inside this monorepo**, use paths under `projects/unops-ux/src/assets/` instead of `node_modules`.
+**Verify:** after `ng serve`, inspect the compiled CSS for `.flex { display: flex }`. If missing, PostCSS is not running on your tailwind entry point.
 
 ## Tokens
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unopsitg/ux",
-  "version": "21.1.0",
+  "version": "21.2.0",
   "description": "UNOPS Angular 21 layout shell, brand theme (PrimeNG / PrimeUIX), and shared types",
   "keywords": [
     "angular",
@@ -9,6 +9,21 @@
     "layout"
   ],
   "license": "UNLICENSED",
+  "schematics": "./schematics/collection.json",
+  "ng-add": {
+    "save": "dependencies"
+  },
+  "exports": {
+    "./tailwind": "./assets/tailwind.css",
+    "./styles": "./assets/styles.scss",
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/unopsitg-ux.d.ts",
+      "default": "./fesm2022/unopsitg-ux.mjs"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/opp_plus/unops-ng21_ux.git"
@@ -29,15 +44,6 @@
   },
   "module": "fesm2022/unopsitg-ux.mjs",
   "typings": "types/unopsitg-ux.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./types/unopsitg-ux.d.ts",
-      "default": "./fesm2022/unopsitg-ux.mjs"
-    }
-  },
   "sideEffects": false,
   "type": "module",
   "dependencies": {

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,241 @@
+"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 RUNTIME_DEPS = {
+    primeng: '^21.0.4',
+    '@primeuix/themes': '^2.0.0',
+    primeicons: '^7.0.0',
+};
+const DEV_DEPS = {
+    '@tailwindcss/postcss': '^4.0.0',
+    tailwindcss: '^4.0.0',
+    postcss: '^8.4.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 = {};
+        }
+        if (!pkg.devDependencies) {
+            pkg.devDependencies = {};
+        }
+        for (const [name, version] of Object.entries(RUNTIME_DEPS)) {
+            if (!pkg.dependencies[name] && !pkg.devDependencies[name]) {
+                pkg.dependencies[name] = version;
+            }
+        }
+        for (const [name, version] of Object.entries(DEV_DEPS)) {
+            if (!pkg.dependencies[name] && !pkg.devDependencies[name]) {
+                pkg.devDependencies[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 "tailwindcss";',
+            '@import "@unopsitg/ux/tailwind";',
+            '',
+        ].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. **\`assets/tailwind.css\` is a Tailwind v4 source file** (not pre-compiled CSS). It contains \`@plugin\`, \`@source\`, \`@theme\`, and \`@utility\` directives that must be processed by \`@tailwindcss/postcss\`. Never add it directly to \`angular.json\` styles — it will be inlined as raw text with no utility generation.
+3. **Use \`src/tailwind.css\`** as the entry point. It imports \`tailwindcss\` and \`@unopsitg/ux/tailwind\` via the package exports. This file IS processed by PostCSS because it lives in \`src/\`.
+4. **Never put \`@source\` directives in \`.scss\` files** — Sass copies them as inert text.
+5. **Shell utilities** (\`.hidden\`, \`.animate-scalein\`, \`.animate-fadeout\`) are shipped as real CSS in the library. Do not redefine them.
+
+## Correct src/tailwind.css
+
+\`\`\`css
+@import "tailwindcss";
+@import "@unopsitg/ux/tailwind";
+\`\`\`
+
+## 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": []
+}