@unopsitg/ux 21.1.1 → 21.2.0

package/AGENTS.md

@@ -6,7 +6,7 @@ This file is for AI coding assistants (Cursor, Claude Code, Copilot, etc.) worki
 
 - **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 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`)
@@ -18,8 +18,8 @@ This file is for AI coding assistants (Cursor, Claude Code, Copilot, etc.) worki
 
 2. Create `src/tailwind.css`:
    ```css
-   @import "../node_modules/@unopsitg/ux/assets/tailwind.css";
-   @source "../node_modules/@unopsitg/ux/fesm2022";
+   @import "tailwindcss";
+   @import "@unopsitg/ux/tailwind";
    ```
 
 3. In `angular.json` styles:
@@ -32,7 +32,12 @@ This file is for AI coding assistants (Cursor, Claude Code, Copilot, etc.) worki
    { "glob": "**/*", "input": "node_modules/@unopsitg/ux/assets/opp", "output": "assets/opp" }
    ```
 
-5. In `app.config.ts` providers:
+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';
@@ -42,11 +47,20 @@ This file is for AI coding assistants (Cursor, Claude Code, Copilot, etc.) worki
 
 ## 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.
-- **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.
 
+## 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 |

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.1",
+  "version": "21.2.0",
   "description": "UNOPS Angular 21 layout shell, brand theme (PrimeNG / PrimeUIX), and shared types",
   "keywords": [
     "angular",
@@ -13,6 +13,17 @@
   "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"
@@ -33,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/ng-add/index.js

@@ -3,12 +3,15 @@ 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 = {
+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',
+    tailwindcss: '^4.0.0',
+    postcss: '^8.4.0',
 };
 const STYLES_ENTRIES = [
     'node_modules/@unopsitg/ux/assets/styles.scss',
@@ -43,11 +46,19 @@ function addPeerDependencies() {
         if (!pkg.dependencies) {
             pkg.dependencies = {};
         }
-        for (const [name, version] of Object.entries(PEER_DEPS)) {
-            if (!pkg.dependencies[name] && !pkg.devDependencies?.[name]) {
+        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;
     };
@@ -69,8 +80,8 @@ function createTailwindWrapper() {
             return tree;
         }
         tree.create(path, [
-            '@import "../node_modules/@unopsitg/ux/assets/tailwind.css";',
-            '@source "../node_modules/@unopsitg/ux/fesm2022";',
+            '@import "tailwindcss";',
+            '@import "@unopsitg/ux/tailwind";',
             '',
         ].join('\n'));
         return tree;
@@ -188,9 +199,17 @@ This project uses the @unopsitg/ux Angular library for its layout shell, brand t
 ## 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.
+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