@unifylib/ui-lib 1.2.15 → 1.2.17

package/cli/client-app-component-guide.md

@@ -1,166 +1,166 @@
-# Create ui-lib Components in Client Apps
-
-This guide explains how feature teams create new screens in client applications using `ui-lib` components and the `iq-ui` generator.
-
-## Prerequisites
-
-- `ui-lib` workspace built locally (for local development flow), or package installed from registry.
-- Client app is an Angular app (for example `lynx-entities-shell-fe`).
-- `@iq/ui-lib` or `@unifylib/ui-lib` import path is decided in your app.
-
----
-
-## 1) Local development setup (`@iq/ui-lib`)
-
-Use this when you develop `ui-lib` and the client app side-by-side.
-
-From `ui-lib/library-package-workspace`:
-
-```bash
-ng build iq-ui-lib --watch
-npm link dist/iq/ui-lib
-```
-
-From the client app root:
-
-```bash
-npm link @iq/ui-lib
-```
-
-Verify the package link:
-
-```bash
-npm ls -g --depth=0
-```
-
----
-
-## 2) Generate a screen scaffold
-
-From the client app root, generate a new feature screen:
-
-```bash
-npx iq-ui -g form-screen src/app/registration --import-path @iq/ui-lib
-```
-
-This creates:
-
-- `registration.settings.ts`
-- `registration.component.ts`
-- `registration.component.html`
-- `registration.component.scss`
-
-Useful options:
-
-- `-g <type>`: `form-screen`, `table-screen`, `section-form`, `line-editor`, `dashboard`, `permission-matrix`
-- `--import-path <p>`: usually `@iq/ui-lib` (local) or `@unifylib/ui-lib` (published)
-- `--name <n>`: override generated base name
-- `--labels-section <s>`: override `PageInfo.labelsSection`
-- `--api-uri <u>`: override `PageInfo.apiUri`
-- `--fields-count <n>`: placeholder fields count (form/section/line)
-- `--dry-run`: preview generated files without writing
-- `--i18n-path <p>`: update translation JSON with template keys used by generated files.
-  - file mode: `src/assets/en.json`
-  - folder mode: `src/assets` (updates translation-like files only, such as `en.json` / `ar.json`; skips config JSON files)
-
-Example table screen:
-
-```bash
-npx iq-ui -g table-screen src/app/device-list --import-path @iq/ui-lib
-```
-
-Example with translation template update:
-
-```bash
-npx iq-ui -g table-screen src/app/device-list --import-path @iq/ui-lib --i18n-path src/assets/en.json
-```
-
-Example updating both `en.json` and `ar.json` in assets:
-
-```bash
-npx iq-ui -g table-screen src/app/device-list --import-path @iq/ui-lib --i18n-path src/assets
-```
-
----
-
-## 3) What to add in the client app (required setup)
-
-To use `iq-ui` comfortably in a client app, add/confirm the following:
-
-1. **Library availability** (choose one):
-   - local link flow: `npm link @iq/ui-lib`
-   - installed dependency flow: `npm install @unifylib/ui-lib`
-
-2. **Optional package script** (recommended) in client app `package.json`:
-
-```json
-{
-  "scripts": {
-    "gen:ui": "iq-ui"
-  }
-}
-```
-
-Then run:
-
-```bash
-npm run gen:ui -- -g form-screen src/app/registration --import-path @iq/ui-lib
-```
-
-3. **Optional shared barrel** if your app centralizes imports:
-
-```ts
-// src/app/shared/ui-lib-imports.ts
-export * from "@iq/ui-lib";
-```
-
-Then generate using:
-
-```bash
-npx iq-ui -g form-screen src/app/registration --import-path src/app/shared/ui-lib-imports
-```
-
-4. **Route registration** for each generated screen so it is reachable in the client app.
-
----
-
-## 4) Wire the generated component into the client app
-
-1. Add route (or include component in a parent standalone component).
-2. Add i18n labels for generated keys.
-3. Replace placeholder fields/columns with business fields.
-4. Update API values (`apiUri`, list actions, filters, validators).
-
-Generated files are intentionally starter templates; treat them as scaffolding.
-
----
-
-## 5) If `npx iq-ui` fails with 404
-
-Error:
-
-`404 Not Found - GET https://registry.npmjs.org/iq-ui`
-
-Means `iq-ui` binary is not available in the current app context. Fix by ensuring one of:
-
-- linked package exists (`npm link @iq/ui-lib` after building/linking library), or
-- dependency is installed in the app (`npm install @unifylib/ui-lib` / local file install).
-
-Then run `npx iq-ui ...` again.
-
----
-
-## 6) Published package flow (`@unifylib/ui-lib`)
-
-If you are not using local links:
-
-```bash
-npm install @unifylib/ui-lib
-npx iq-ui -g form-screen src/app/registration --import-path @unifylib/ui-lib
-```
-
-If your app re-exports symbols from `src/app/shared/ui-lib-imports`, you can generate against that barrel:
-
-```bash
-npx iq-ui -g form-screen src/app/registration --import-path src/app/shared/ui-lib-imports
-```
+# Create ui-lib Components in Client Apps
+
+This guide explains how feature teams create new screens in client applications using `ui-lib` components and the `iq-ui` generator.
+
+## Prerequisites
+
+- `ui-lib` workspace built locally (for local development flow), or package installed from registry.
+- Client app is an Angular app (for example `lynx-entities-shell-fe`).
+- `@iq/ui-lib` or `@unifylib/ui-lib` import path is decided in your app.
+
+---
+
+## 1) Local development setup (`@iq/ui-lib`)
+
+Use this when you develop `ui-lib` and the client app side-by-side.
+
+From `ui-lib/library-package-workspace`:
+
+```bash
+ng build iq-ui-lib --watch
+npm link dist/iq/ui-lib
+```
+
+From the client app root:
+
+```bash
+npm link @iq/ui-lib
+```
+
+Verify the package link:
+
+```bash
+npm ls -g --depth=0
+```
+
+---
+
+## 2) Generate a screen scaffold
+
+From the client app root, generate a new feature screen:
+
+```bash
+npx iq-ui -g form-screen src/app/registration --import-path @iq/ui-lib
+```
+
+This creates:
+
+- `registration.settings.ts`
+- `registration.component.ts`
+- `registration.component.html`
+- `registration.component.scss`
+
+Useful options:
+
+- `-g <type>`: `form-screen`, `table-screen`, `section-form`, `line-editor`, `dashboard`, `permission-matrix`
+- `--import-path <p>`: usually `@iq/ui-lib` (local) or `@unifylib/ui-lib` (published)
+- `--name <n>`: override generated base name
+- `--labels-section <s>`: override `PageInfo.labelsSection`
+- `--api-uri <u>`: override `PageInfo.apiUri`
+- `--fields-count <n>`: placeholder fields count (form/section/line)
+- `--dry-run`: preview generated files without writing
+- `--i18n-path <p>`: update translation JSON with template keys used by generated files.
+  - file mode: `src/assets/en.json`
+  - folder mode: `src/assets` (updates translation-like files only, such as `en.json` / `ar.json`; skips config JSON files)
+
+Example table screen:
+
+```bash
+npx iq-ui -g table-screen src/app/device-list --import-path @iq/ui-lib
+```
+
+Example with translation template update:
+
+```bash
+npx iq-ui -g table-screen src/app/device-list --import-path @iq/ui-lib --i18n-path src/assets/en.json
+```
+
+Example updating both `en.json` and `ar.json` in assets:
+
+```bash
+npx iq-ui -g table-screen src/app/device-list --import-path @iq/ui-lib --i18n-path src/assets
+```
+
+---
+
+## 3) What to add in the client app (required setup)
+
+To use `iq-ui` comfortably in a client app, add/confirm the following:
+
+1. **Library availability** (choose one):
+   - local link flow: `npm link @iq/ui-lib`
+   - installed dependency flow: `npm install @unifylib/ui-lib`
+
+2. **Optional package script** (recommended) in client app `package.json`:
+
+```json
+{
+  "scripts": {
+    "gen:ui": "iq-ui"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run gen:ui -- -g form-screen src/app/registration --import-path @iq/ui-lib
+```
+
+3. **Optional shared barrel** if your app centralizes imports:
+
+```ts
+// src/app/shared/ui-lib-imports.ts
+export * from "@iq/ui-lib";
+```
+
+Then generate using:
+
+```bash
+npx iq-ui -g form-screen src/app/registration --import-path src/app/shared/ui-lib-imports
+```
+
+4. **Route registration** for each generated screen so it is reachable in the client app.
+
+---
+
+## 4) Wire the generated component into the client app
+
+1. Add route (or include component in a parent standalone component).
+2. Add i18n labels for generated keys.
+3. Replace placeholder fields/columns with business fields.
+4. Update API values (`apiUri`, list actions, filters, validators).
+
+Generated files are intentionally starter templates; treat them as scaffolding.
+
+---
+
+## 5) If `npx iq-ui` fails with 404
+
+Error:
+
+`404 Not Found - GET https://registry.npmjs.org/iq-ui`
+
+Means `iq-ui` binary is not available in the current app context. Fix by ensuring one of:
+
+- linked package exists (`npm link @iq/ui-lib` after building/linking library), or
+- dependency is installed in the app (`npm install @unifylib/ui-lib` / local file install).
+
+Then run `npx iq-ui ...` again.
+
+---
+
+## 6) Published package flow (`@unifylib/ui-lib`)
+
+If you are not using local links:
+
+```bash
+npm install @unifylib/ui-lib
+npx iq-ui -g form-screen src/app/registration --import-path @unifylib/ui-lib
+```
+
+If your app re-exports symbols from `src/app/shared/ui-lib-imports`, you can generate against that barrel:
+
+```bash
+npx iq-ui -g form-screen src/app/registration --import-path src/app/shared/ui-lib-imports
+```

package/cli/generators/dashboard.js

@@ -1,147 +1,147 @@
-"use strict";
-
-/**
- * @param {{
- *  kebab: string,
- *  pascal: string,
- *  labelsSection: string,
- *  importPath: string,
- * }} ctx
- */
-function generate(ctx) {
-  const fileBase = ctx.kebab;
-
-  const componentTs = `import { ChangeDetectionStrategy, Component, inject } from "@angular/core";
-import { Router } from "@angular/router";
-import { TranslateModule } from "@ngx-translate/core";
-import { ActionCardComponent, FeatureItem } from "${ctx.importPath}";
-
-@Component({
-  selector: "app-${fileBase}",
-  standalone: true,
-  imports: [ActionCardComponent, TranslateModule],
-  templateUrl: "./${fileBase}.component.html",
-  styleUrls: ["./${fileBase}.component.scss"],
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class ${ctx.pascal}Component {
-  private readonly router = inject(Router);
-
-  readonly cardAFeatures: FeatureItem[] = [
-    { textKey: "${ctx.labelsSection}.FEATURE_1" },
-    { textKey: "${ctx.labelsSection}.FEATURE_2" },
-  ];
-
-  readonly cardBFeatures: FeatureItem[] = [
-    { textKey: "${ctx.labelsSection}.FEATURE_3" },
-    { textKey: "${ctx.labelsSection}.FEATURE_4" },
-  ];
-
-  navigateA(): void {
-    void this.router.navigate(["/${ctx.kebab}", "feature-a"]);
-  }
-
-  navigateB(): void {
-    void this.router.navigate(["/${ctx.kebab}", "feature-b"]);
-  }
-}
-`;
-
-  const componentHtml = `<div class="dashboard-container">
-  <div class="welcome-section">
-    <h1 class="welcome-title">{{ '${ctx.labelsSection}.TITLE' | translate }}</h1>
-    <p class="welcome-subtitle">{{ '${ctx.labelsSection}.SUBTITLE' | translate }}</p>
-  </div>
-
-  <div class="cards-grid">
-    <lib-action-card
-      class="action-card-item"
-      icon="dashboard"
-      [titleKey]="'${ctx.labelsSection}.CARD_A_TITLE'"
-      [descriptionKey]="'${ctx.labelsSection}.CARD_A_DESC'"
-      [buttonTextKey]="'${ctx.labelsSection}.CARD_A_CTA'"
-      iconColor="#0d4261"
-      borderColor="#bcd4e6"
-      [buttonGradient]="'linear-gradient(90deg, #e3f0ff 0%, #0d4261 100%)'"
-      [topBorderHeight]="14"
-      variant="extended"
-      [features]="cardAFeatures"
-      [featuresHeadingKey]="'${ctx.labelsSection}.FEATURES'"
-      [showDivider]="true"
-      (buttonClick)="navigateA()">
-    </lib-action-card>
-
-    <lib-action-card
-      class="action-card-item"
-      icon="add_to_queue"
-      [titleKey]="'${ctx.labelsSection}.CARD_B_TITLE'"
-      [descriptionKey]="'${ctx.labelsSection}.CARD_B_DESC'"
-      [buttonTextKey]="'${ctx.labelsSection}.CARD_B_CTA'"
-      iconColor="#8067A4"
-      borderColor="#BDB3CA"
-      [buttonGradient]="'linear-gradient(90deg, #D1CBD8 0%, #8168A5 100%)'"
-      [topBorderHeight]="14"
-      variant="extended"
-      [features]="cardBFeatures"
-      [featuresHeadingKey]="'${ctx.labelsSection}.FEATURES'"
-      [showDivider]="true"
-      (buttonClick)="navigateB()">
-    </lib-action-card>
-  </div>
-</div>
-`;
-
-  const componentScss = `.dashboard-container {
-  padding: 1.5rem;
-}
-
-.welcome-section {
-  margin-bottom: 2rem;
-}
-
-.welcome-title {
-  margin: 0 0 0.5rem;
-}
-
-.welcome-subtitle {
-  margin: 0;
-  opacity: 0.85;
-}
-
-.cards-grid {
-  display: grid;
-  gap: 1.5rem;
-  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
-}
-
-.action-card-item {
-  min-height: 100%;
-}
-`;
-
-  return [
-    { relative: `${fileBase}.component.ts`, content: componentTs },
-    { relative: `${fileBase}.component.html`, content: componentHtml },
-    { relative: `${fileBase}.component.scss`, content: componentScss },
-  ];
-}
-
-function getTranslations(ctx) {
-  return {
-    [`${ctx.labelsSection}.TITLE`]: `${ctx.pascal} Dashboard`,
-    [`${ctx.labelsSection}.SUBTITLE`]: "Choose an option to continue",
-    [`${ctx.labelsSection}.FEATURES`]: "Features",
-    [`${ctx.labelsSection}.CARD_A_TITLE`]: "Card A",
-    [`${ctx.labelsSection}.CARD_A_DESC`]: "Description for card A",
-    [`${ctx.labelsSection}.CARD_A_CTA`]: "Open",
-    [`${ctx.labelsSection}.CARD_B_TITLE`]: "Card B",
-    [`${ctx.labelsSection}.CARD_B_DESC`]: "Description for card B",
-    [`${ctx.labelsSection}.CARD_B_CTA`]: "Open",
-    [`${ctx.labelsSection}.FEATURE_1`]: "Feature 1",
-    [`${ctx.labelsSection}.FEATURE_2`]: "Feature 2",
-    [`${ctx.labelsSection}.FEATURE_3`]: "Feature 3",
-    [`${ctx.labelsSection}.FEATURE_4`]: "Feature 4",
-  };
-}
-
-module.exports = { generate, getTranslations };
+"use strict";
+
+/**
+ * @param {{
+ *  kebab: string,
+ *  pascal: string,
+ *  labelsSection: string,
+ *  importPath: string,
+ * }} ctx
+ */
+function generate(ctx) {
+  const fileBase = ctx.kebab;
+
+  const componentTs = `import { ChangeDetectionStrategy, Component, inject } from "@angular/core";
+import { Router } from "@angular/router";
+import { TranslateModule } from "@ngx-translate/core";
+import { ActionCardComponent, FeatureItem } from "${ctx.importPath}";
+
+@Component({
+  selector: "app-${fileBase}",
+  standalone: true,
+  imports: [ActionCardComponent, TranslateModule],
+  templateUrl: "./${fileBase}.component.html",
+  styleUrls: ["./${fileBase}.component.scss"],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ${ctx.pascal}Component {
+  private readonly router = inject(Router);
+
+  readonly cardAFeatures: FeatureItem[] = [
+    { textKey: "${ctx.labelsSection}.FEATURE_1" },
+    { textKey: "${ctx.labelsSection}.FEATURE_2" },
+  ];
+
+  readonly cardBFeatures: FeatureItem[] = [
+    { textKey: "${ctx.labelsSection}.FEATURE_3" },
+    { textKey: "${ctx.labelsSection}.FEATURE_4" },
+  ];
+
+  navigateA(): void {
+    void this.router.navigate(["/${ctx.kebab}", "feature-a"]);
+  }
+
+  navigateB(): void {
+    void this.router.navigate(["/${ctx.kebab}", "feature-b"]);
+  }
+}
+`;
+
+  const componentHtml = `<div class="dashboard-container">
+  <div class="welcome-section">
+    <h1 class="welcome-title">{{ '${ctx.labelsSection}.TITLE' | translate }}</h1>
+    <p class="welcome-subtitle">{{ '${ctx.labelsSection}.SUBTITLE' | translate }}</p>
+  </div>
+
+  <div class="cards-grid">
+    <lib-action-card
+      class="action-card-item"
+      icon="dashboard"
+      [titleKey]="'${ctx.labelsSection}.CARD_A_TITLE'"
+      [descriptionKey]="'${ctx.labelsSection}.CARD_A_DESC'"
+      [buttonTextKey]="'${ctx.labelsSection}.CARD_A_CTA'"
+      iconColor="#0d4261"
+      borderColor="#bcd4e6"
+      [buttonGradient]="'linear-gradient(90deg, #e3f0ff 0%, #0d4261 100%)'"
+      [topBorderHeight]="14"
+      variant="extended"
+      [features]="cardAFeatures"
+      [featuresHeadingKey]="'${ctx.labelsSection}.FEATURES'"
+      [showDivider]="true"
+      (buttonClick)="navigateA()">
+    </lib-action-card>
+
+    <lib-action-card
+      class="action-card-item"
+      icon="add_to_queue"
+      [titleKey]="'${ctx.labelsSection}.CARD_B_TITLE'"
+      [descriptionKey]="'${ctx.labelsSection}.CARD_B_DESC'"
+      [buttonTextKey]="'${ctx.labelsSection}.CARD_B_CTA'"
+      iconColor="#8067A4"
+      borderColor="#BDB3CA"
+      [buttonGradient]="'linear-gradient(90deg, #D1CBD8 0%, #8168A5 100%)'"
+      [topBorderHeight]="14"
+      variant="extended"
+      [features]="cardBFeatures"
+      [featuresHeadingKey]="'${ctx.labelsSection}.FEATURES'"
+      [showDivider]="true"
+      (buttonClick)="navigateB()">
+    </lib-action-card>
+  </div>
+</div>
+`;
+
+  const componentScss = `.dashboard-container {
+  padding: 1.5rem;
+}
+
+.welcome-section {
+  margin-bottom: 2rem;
+}
+
+.welcome-title {
+  margin: 0 0 0.5rem;
+}
+
+.welcome-subtitle {
+  margin: 0;
+  opacity: 0.85;
+}
+
+.cards-grid {
+  display: grid;
+  gap: 1.5rem;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+}
+
+.action-card-item {
+  min-height: 100%;
+}
+`;
+
+  return [
+    { relative: `${fileBase}.component.ts`, content: componentTs },
+    { relative: `${fileBase}.component.html`, content: componentHtml },
+    { relative: `${fileBase}.component.scss`, content: componentScss },
+  ];
+}
+
+function getTranslations(ctx) {
+  return {
+    [`${ctx.labelsSection}.TITLE`]: `${ctx.pascal} Dashboard`,
+    [`${ctx.labelsSection}.SUBTITLE`]: "Choose an option to continue",
+    [`${ctx.labelsSection}.FEATURES`]: "Features",
+    [`${ctx.labelsSection}.CARD_A_TITLE`]: "Card A",
+    [`${ctx.labelsSection}.CARD_A_DESC`]: "Description for card A",
+    [`${ctx.labelsSection}.CARD_A_CTA`]: "Open",
+    [`${ctx.labelsSection}.CARD_B_TITLE`]: "Card B",
+    [`${ctx.labelsSection}.CARD_B_DESC`]: "Description for card B",
+    [`${ctx.labelsSection}.CARD_B_CTA`]: "Open",
+    [`${ctx.labelsSection}.FEATURE_1`]: "Feature 1",
+    [`${ctx.labelsSection}.FEATURE_2`]: "Feature 2",
+    [`${ctx.labelsSection}.FEATURE_3`]: "Feature 3",
+    [`${ctx.labelsSection}.FEATURE_4`]: "Feature 4",
+  };
+}
+
+module.exports = { generate, getTranslations };