create-ui5-freestyle-lr 0.2.0

package/README.md

@@ -0,0 +1,141 @@
+# create-ui5-freestyle-lr
+
+Scaffolder for **freestyle SAPUI5 List Report** apps. Ask a few questions, fetch
+your OData `$metadata`, and get a running UI5 app with filter bar, value helps,
+pagination, sorting, grouping, column settings, and i18n — all plain SAPUI5
+code you own and can edit.
+
+> Not Fiori Elements (annotation-driven). This is a freestyle template that
+> generates explicit views and controllers you can customise directly.
+
+## Usage
+
+```bash
+npm create ui5-freestyle-lr@latest my-app
+cd my-app
+npm install
+npm start
+```
+
+The CLI asks a short series of questions (app namespace, OData URL, credentials),
+fetches the `$metadata`, then lets you pick columns, filters, value helps, and
+search fields interactively from the live entity set.
+
+Afterwards the generated project is yours — plain UI5 + `@ui5/cli` v3,
+no runtime dependency on this package.
+
+## What you get
+
+```
+my-app/
+├── package.json                   @ui5/cli v3 scripts (start / build)
+├── ui5.yaml                       SAPUI5 framework config + OData proxy
+├── README.md                      How-to for the generated project
+└── webapp/
+    ├── Component.js, manifest.json, index.html
+    ├── view/
+    │   ├── App.view.xml
+    │   ├── Worklist.view.xml       DynamicPage + VariantManagement + FilterBar + Table + Footer pagination
+    │   ├── NotFound.view.xml
+    │   └── fragments/
+    │       ├── SortDialog.fragment.xml
+    │       ├── GroupDialog.fragment.xml
+    │       ├── InfoPopover.fragment.xml            (demo pattern)
+    │       └── <Field>VH.fragment.xml              (one per value-help filter)
+    ├── controller/
+    │   ├── App.controller.js
+    │   ├── BaseController.js        helpers (getRouter, getModel, getResourceBundle, onNavBack)
+    │   ├── Worklist.controller.js   pagination, sort/group, column settings, filter build, VH handlers
+    │   ├── ErrorHandler.js          centralised OData error handling
+    │   └── NotFound.controller.js
+    ├── model/
+    │   ├── formatter.js             formatDate / formatPartnerId / formatStrongCode / numberUnit / _animateValue
+    │   └── models.js                device + FLP model factories
+    ├── i18n/                        i18n.properties (+ i18n_de.properties if German enabled)
+    ├── css/style.css
+    └── localService/metadata.xml    snapshot of your OData $metadata
+```
+
+## Features in the generated app
+
+- **DynamicPage** layout with collapsible filter bar header
+- **VariantManagement** (`sap.ui.fl.variants.VariantManagement`) for "My View"
+  save / load of the current filter, sort, group, column visibility, page
+  size, and search. Persisted client-side via the `LocalStorageConnector`
+  (one-line swap to `LrepConnector` for SAP-backend storage).
+- **FilterBar** with three filter input types, picked automatically from the
+  OData property type:
+  - `DateRangeSelection` for `Edm.DateTime` / `Edm.DateTimeOffset`
+  - `MultiInput` + value-help dialog when you point a filter at a lookup EntitySet
+  - Plain `MultiInput` for free-text contains-search
+- **Table** columns auto-sized by Edm type:
+  - First key field → `ObjectIdentifier`
+  - Dates → `Text` with the `formatDate` formatter
+  - Booleans → accept/decline icon
+  - Numbers → `Text` with `numberUnit` formatter (right-aligned)
+  - Strings → plain `Text`
+- **Excel export** (`sap.ui.export.Spreadsheet`) — refetches all matching
+  rows respecting current filters and sort, with a confirm dialog above
+  1 000 rows. Column types are derived from the OData metadata at scaffold
+  time, so dates land as Excel date cells. Animated progress dialog while
+  the file is generated.
+- **Server-side pagination** with `$top` / `$skip` + a separate `$count` query
+  for total pages. Footer has page combo, step input for rows-per-page,
+  prev/next/first/last buttons.
+- **Auto-refresh** toggle button — re-fetches the table every 30 s while
+  active. The footer shows the last-refreshed timestamp as an
+  `ObjectStatus` + `<cite>` formatted text.
+- **Sharp table corners** (CSS class `lrTable`) — `border-radius: 0` on the
+  table root, header toolbar, and info toolbar for a flatter monitoring
+  look.
+- **Sort dialog**, **group dialog**, **column settings dialog** (all from the
+  table header toolbar).
+- **Info bar** that shows a human-readable summary of the active filter,
+  search, sort, and group state.
+- **Search bar** across the columns you pick (joined with `or`).
+- **InfoPopover** demo pattern — click a row-level link, open a popover with
+  row-specific details. Replace the fields to match your own data.
+- **Centralised ErrorHandler** attached to the OData model.
+- **Scroll-to-top animation** after page change.
+- **URL state persistence** — search / sort / group / page mirrored to the
+  hash so a refresh or shared link preserves the view.
+- **i18n** (English + optional German).
+- **localService/metadata.xml** snapshot so offline development works.
+
+## Prompts
+
+```
+? App namespace (com.company.module.app)
+? App title
+? App description
+? Minimum UI5 version              (default 1.120.0)
+? Include German translations?     (default yes)
+
+? OData metadata source            (fetch live / provide local file)
+? Service URL
+? Username / password
+? Allow self-signed certificates?  (default yes, for on-prem dev systems)
+
+? Main EntitySet                   (dropdown from $metadata)
+? Table columns                    (checkbox, all checked by default)
+? Filter bar fields                (checkbox)
+? For each filter:                 (plain MultiInput / with ValueHelp EntitySet)
+? Search fields                    (string properties only)
+? Default sort field + direction
+```
+
+## Adding a filter / column / value help after scaffolding
+
+The generated project has a section at the bottom of its own `README.md` with
+a step-by-step copy-paste recipe. The template is one-shot: re-running the
+CLI creates a new project; changes to an existing one are done by hand.
+
+## Requirements
+
+- Node.js 18+
+- For live metadata fetch: network access to the SAP OData service and
+  credentials the service accepts (basic auth).
+
+## Licence
+
+MIT

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "create-ui5-freestyle-lr",
+  "version": "0.2.0",
+  "description": "Scaffolder for freestyle SAPUI5 List Report apps with dynamic FilterBar, pagination, value helps, sort/group dialogs, and i18n.",
+  "type": "module",
+  "bin": {
+    "create-ui5-freestyle-lr": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "sapui5",
+    "ui5",
+    "fiori",
+    "list-report",
+    "scaffolder",
+    "create",
+    "freestyle",
+    "odata"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^5.3.8",
+    "axios": "^1.7.0",
+    "ejs": "^3.1.10",
+    "fast-xml-parser": "^4.4.0",
+    "picocolors": "^1.0.1"
+  },
+  "license": "MIT"
+}

package/src/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import pc from "picocolors";
+import { runBasicPrompts } from "./prompts/basic.js";
+import { runOdataPrompts } from "./prompts/odata.js";
+import { runFieldPrompts } from "./prompts/fields.js";
+import { render } from "./render/engine.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function printBanner() {
+  console.log();
+  console.log(pc.bold(pc.cyan("create-ui5-freestyle-lr")));
+  console.log(pc.dim("Scaffold a freestyle SAPUI5 List Report app"));
+  console.log();
+}
+
+function resolveTarget(rawArg) {
+  if (!rawArg) {
+    console.error(pc.red("Error: target directory is required"));
+    console.error(pc.dim("Usage: npm create ui5-freestyle-lr <project-name>"));
+    process.exit(1);
+  }
+  const targetDir = path.resolve(process.cwd(), rawArg);
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+    console.error(pc.red(`Error: directory "${rawArg}" exists and is not empty`));
+    process.exit(1);
+  }
+  mkdirSync(targetDir, { recursive: true });
+  return targetDir;
+}
+
+async function main() {
+  printBanner();
+
+  const rawArg = process.argv[2];
+  const targetDir = resolveTarget(rawArg);
+
+  const basic = await runBasicPrompts();
+  const odata = await runOdataPrompts();
+  const fields = await runFieldPrompts(odata.metadata);
+
+  const answers = {
+    ...basic,
+    serviceUrl: odata.serviceUrl,
+    rawMetadataXml: odata.rawMetadataXml,
+    ...fields,
+  };
+
+  console.log();
+  console.log(pc.dim("Rendering project..."));
+  await render(answers, targetDir);
+
+  console.log();
+  console.log(pc.green("Project created."));
+  console.log();
+  console.log(pc.dim("Next steps:"));
+  console.log(`  cd ${path.relative(process.cwd(), targetDir) || "."}`);
+  console.log("  npm install");
+  console.log("  npm start");
+  console.log();
+}
+
+main().catch((err) => {
+  if (err && err.name === "ExitPromptError") {
+    console.log(pc.dim("\nAborted."));
+    process.exit(0);
+  }
+  console.error(pc.red("\nFailed:"), err?.message || err);
+  process.exit(1);
+});

package/src/metadata/fetch.js

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import https from "node:https";
+import axios from "axios";
+
+function buildMetadataUrl(serviceUrl) {
+  const trimmed = serviceUrl.trim().replace(/\/+$/, "");
+  return `${trimmed}/$metadata`;
+}
+
+export async function fetchMetadataFromUrl({ serviceUrl, username, password, insecure }) {
+  const url = buildMetadataUrl(serviceUrl);
+
+  const config = {
+    responseType: "text",
+    headers: { Accept: "application/xml" },
+    timeout: 30000,
+    transformResponse: [(data) => data],
+  };
+
+  if (username) {
+    config.auth = { username, password: password || "" };
+  }
+
+  if (insecure) {
+    config.httpsAgent = new https.Agent({ rejectUnauthorized: false });
+  }
+
+  const response = await axios.get(url, config);
+
+  if (typeof response.data !== "string" || response.data.length === 0) {
+    throw new Error(`Metadata response from ${url} was empty`);
+  }
+  return response.data;
+}
+
+export async function readMetadataFromFile(filePath) {
+  const xml = await readFile(filePath, "utf8");
+  if (!xml || xml.length === 0) {
+    throw new Error(`Metadata file ${filePath} is empty`);
+  }
+  return xml;
+}

package/src/metadata/parse.js

@@ -0,0 +1,104 @@
+import { XMLParser } from "fast-xml-parser";
+
+const parser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  allowBooleanAttributes: true,
+  parseAttributeValue: false,
+  removeNSPrefix: true,
+});
+
+function toArray(value) {
+  if (value === undefined || value === null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function stripNamespace(typeRef) {
+  if (!typeRef) return "";
+  const idx = typeRef.lastIndexOf(".");
+  return idx >= 0 ? typeRef.substring(idx + 1) : typeRef;
+}
+
+function buildEntityTypeIndex(schema) {
+  const index = new Map();
+  for (const entityType of toArray(schema.EntityType)) {
+    const name = entityType["@_Name"];
+    if (name) index.set(name, entityType);
+  }
+  return index;
+}
+
+function extractKeyNames(entityType) {
+  const key = entityType.Key;
+  if (!key) return new Set();
+  return new Set(toArray(key.PropertyRef).map((ref) => ref["@_Name"]).filter(Boolean));
+}
+
+function normalizeProperty(prop, keyNames) {
+  const name = prop["@_Name"];
+  return {
+    name,
+    type: prop["@_Type"] || "Edm.String",
+    label: prop["@_label"] || prop["@_sap:label"] || name,
+    isKey: keyNames.has(name),
+    nullable: prop["@_Nullable"] !== "false",
+    maxLength: prop["@_MaxLength"],
+    precision: prop["@_Precision"],
+    scale: prop["@_Scale"],
+    creatable: prop["@_creatable"] !== "false",
+    updatable: prop["@_updatable"] !== "false",
+    sortable: prop["@_sortable"] !== "false",
+    filterable: prop["@_filterable"] !== "false",
+  };
+}
+
+export function parseMetadata(xml) {
+  const parsed = parser.parse(xml);
+
+  const edmx = parsed.Edmx;
+  if (!edmx) throw new Error("Could not find <edmx:Edmx> root in metadata");
+
+  const dataServices = edmx.DataServices;
+  if (!dataServices) throw new Error("Could not find <edmx:DataServices> in metadata");
+
+  const schemas = toArray(dataServices.Schema);
+  if (schemas.length === 0) throw new Error("Could not find any <Schema> in metadata");
+
+  const entitySets = [];
+  let namespace = "";
+
+  for (const schema of schemas) {
+    const schemaNs = schema["@_Namespace"] || "";
+    if (!namespace) namespace = schemaNs;
+
+    const entityTypeIndex = buildEntityTypeIndex(schema);
+
+    for (const container of toArray(schema.EntityContainer)) {
+      for (const entitySet of toArray(container.EntitySet)) {
+        const setName = entitySet["@_Name"];
+        const entityTypeRef = entitySet["@_EntityType"];
+        const entityTypeName = stripNamespace(entityTypeRef);
+        const entityType = entityTypeIndex.get(entityTypeName);
+
+        if (!entityType) continue;
+
+        const keyNames = extractKeyNames(entityType);
+        const properties = toArray(entityType.Property)
+          .map((p) => normalizeProperty(p, keyNames))
+          .filter((p) => p.name);
+
+        entitySets.push({
+          name: setName,
+          entityType: entityTypeName,
+          properties,
+        });
+      }
+    }
+  }
+
+  if (entitySets.length === 0) {
+    throw new Error("No EntitySets found in metadata");
+  }
+
+  return { namespace, entitySets };
+}

package/src/prompts/basic.js

@@ -0,0 +1,43 @@
+import { input, confirm } from "@inquirer/prompts";
+
+const NAMESPACE_RE = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+
+export async function runBasicPrompts() {
+  const appId = await input({
+    message: "App namespace (e.g. com.company.module.app):",
+    validate: (s) =>
+      NAMESPACE_RE.test(s.trim()) ||
+      "Namespace must be dotted lowercase, at least two segments (e.g. com.acme.myapp)",
+  });
+
+  const appTitle = await input({
+    message: "App title:",
+    default: "My UI5 App",
+    validate: (s) => s.trim().length > 0 || "Title cannot be empty",
+  });
+
+  const appDescription = await input({
+    message: "App description:",
+    default: "",
+  });
+
+  const minUI5Version = await input({
+    message: "Minimum UI5 version:",
+    default: "1.120.0",
+    validate: (s) => SEMVER_RE.test(s.trim()) || "Must be semver, e.g. 1.120.0",
+  });
+
+  const hasGerman = await confirm({
+    message: "Include German translations (i18n_de.properties) in addition to English?",
+    default: true,
+  });
+
+  return {
+    appId: appId.trim(),
+    appTitle: appTitle.trim(),
+    appDescription: appDescription.trim(),
+    minUI5Version: minUI5Version.trim(),
+    hasGerman,
+  };
+}

package/src/prompts/fields.js

@@ -0,0 +1,144 @@
+import { select, checkbox } from "@inquirer/prompts";
+
+const STRING_TYPES = new Set(["Edm.String", "Edm.Guid"]);
+
+function formatPropertyChoice(prop) {
+  const typeLabel = prop.type.replace(/^Edm\./, "");
+  const keyMark = prop.isKey ? " [key]" : "";
+  const labelExtra = prop.label && prop.label !== prop.name ? ` — "${prop.label}"` : "";
+  return {
+    name: `${prop.name}${keyMark}  (${typeLabel})${labelExtra}`,
+    value: prop.name,
+    checked: false,
+  };
+}
+
+export async function runFieldPrompts(metadata) {
+  const entitySetName = await select({
+    message: "Main EntitySet (the list the table will display):",
+    choices: metadata.entitySets.map((es) => ({
+      name: `${es.name}  (type: ${es.entityType}, ${es.properties.length} props)`,
+      value: es.name,
+    })),
+  });
+
+  const entitySet = metadata.entitySets.find((es) => es.name === entitySetName);
+  const props = entitySet.properties;
+
+  const columns = await checkbox({
+    message: "Table columns (space to toggle, enter to confirm):",
+    choices: props.map((p) => ({
+      ...formatPropertyChoice(p),
+      checked: true,
+    })),
+    validate: (answer) => answer.length > 0 || "Pick at least one column",
+  });
+
+  const filterFields = await checkbox({
+    message: "Filter bar fields:",
+    choices: props
+      .filter((p) => p.filterable)
+      .map((p) => formatPropertyChoice(p)),
+  });
+
+  const valueHelpCandidates = metadata.entitySets.filter(
+    (es) => es.name !== entitySetName && es.properties.length >= 2
+  );
+
+  const filters = [];
+  for (const fieldName of filterFields) {
+    const prop = props.find((p) => p.name === fieldName);
+    const isDate = prop.type === "Edm.DateTime" || prop.type === "Edm.DateTimeOffset";
+    const inputType = isDate
+      ? "dateRange"
+      : await select({
+          message: `Filter input for "${fieldName}":`,
+          choices: [
+            { name: "Plain MultiInput (no value help)", value: "multiInput" },
+            { name: "MultiInput with Value Help (pick an EntitySet below)", value: "valueHelp" },
+          ],
+        });
+
+    let valueHelp = null;
+    if (inputType === "valueHelp") {
+      if (valueHelpCandidates.length === 0) {
+        console.log("  (No other EntitySets available for value help — falling back to plain input.)");
+      } else {
+        const vhEntitySet = await select({
+          message: `  Value help for "${fieldName}" — EntitySet:`,
+          choices: [
+            { name: "(none — plain input after all)", value: null },
+            ...valueHelpCandidates.map((es) => ({
+              name: `${es.name}  (${es.properties.length} props)`,
+              value: es.name,
+            })),
+          ],
+        });
+        if (vhEntitySet) {
+          const vhSet = metadata.entitySets.find((es) => es.name === vhEntitySet);
+          const keyProp = vhSet.properties.find((p) => p.isKey) || vhSet.properties[0];
+          const textProp =
+            vhSet.properties.find((p) => !p.isKey && STRING_TYPES.has(p.type)) ||
+            vhSet.properties.find((p) => !p.isKey) ||
+            keyProp;
+          valueHelp = {
+            entitySet: vhEntitySet,
+            keyField: keyProp.name,
+            textField: textProp.name,
+          };
+        }
+      }
+    }
+
+    filters.push({
+      fieldName,
+      type: prop.type,
+      label: prop.label,
+      inputType: valueHelp ? "valueHelp" : inputType,
+      valueHelp,
+    });
+  }
+
+  const stringProps = props.filter((p) => STRING_TYPES.has(p.type));
+  const searchFields =
+    stringProps.length > 0
+      ? await checkbox({
+          message: "Fields included in the live search (optional — empty = no search bar):",
+          choices: stringProps.map((p) => formatPropertyChoice(p)),
+        })
+      : [];
+
+  const sortableProps = props.filter((p) => p.sortable);
+  const defaultSortField = await select({
+    message: "Default sort field:",
+    choices: [
+      { name: "(no default sort)", value: null },
+      ...sortableProps.map((p) => ({
+        name: `${p.name}  (${p.type.replace(/^Edm\./, "")})`,
+        value: p.name,
+      })),
+    ],
+  });
+
+  let defaultSortDescending = false;
+  if (defaultSortField) {
+    defaultSortDescending = await select({
+      message: "Sort direction:",
+      choices: [
+        { name: "Ascending", value: false },
+        { name: "Descending", value: true },
+      ],
+    });
+  }
+
+  return {
+    entitySet: entitySetName,
+    entityType: entitySet.entityType,
+    keyFields: props.filter((p) => p.isKey).map((p) => p.name),
+    columns: columns.map((name) => props.find((p) => p.name === name)),
+    filters,
+    searchFields,
+    defaultSortField,
+    defaultSortDescending,
+  };
+}

package/src/prompts/odata.js

@@ -0,0 +1,57 @@
+import { input, password, select, confirm } from "@inquirer/prompts";
+import pc from "picocolors";
+import { fetchMetadataFromUrl, readMetadataFromFile } from "../metadata/fetch.js";
+import { parseMetadata } from "../metadata/parse.js";
+
+export async function runOdataPrompts() {
+  const source = await select({
+    message: "OData metadata source:",
+    choices: [
+      { name: "Fetch from live service (URL + credentials)", value: "live" },
+      { name: "Provide local metadata.xml file", value: "file" },
+    ],
+  });
+
+  let xml;
+  let serviceUrl;
+
+  if (source === "live") {
+    serviceUrl = await input({
+      message: "Service URL (e.g. http://host:port/sap/opu/odata/sap/XYZ_SRV/):",
+      validate: (s) => /^https?:\/\//i.test(s.trim()) || "URL must start with http:// or https://",
+    });
+    const user = await input({ message: "Username:" });
+    const pass = await password({ message: "Password:", mask: "*" });
+    const insecure = await confirm({
+      message: "Allow self-signed / invalid SSL certificates?",
+      default: true,
+    });
+
+    console.log(pc.dim("Fetching $metadata..."));
+    try {
+      xml = await fetchMetadataFromUrl({
+        serviceUrl: serviceUrl.trim(),
+        username: user.trim(),
+        password: pass,
+        insecure,
+      });
+    } catch (err) {
+      throw new Error(`Failed to fetch metadata: ${err.message}`);
+    }
+  } else {
+    const filePath = await input({
+      message: "Path to metadata.xml:",
+      validate: (s) => s.trim().length > 0 || "Path is required",
+    });
+    xml = await readMetadataFromFile(filePath.trim());
+    serviceUrl = await input({
+      message: "Service URL to configure in manifest.json (e.g. /sap/opu/odata/sap/XYZ_SRV/):",
+      validate: (s) => s.trim().length > 0 || "Service URL is required",
+    });
+  }
+
+  const metadata = parseMetadata(xml);
+  console.log(pc.green(`Parsed ${metadata.entitySets.length} entity set(s) from namespace "${metadata.namespace}"`));
+
+  return { metadata, serviceUrl: serviceUrl.trim(), rawMetadataXml: xml };
+}