ngx-form-designer 0.0.23

package/README.md

@@ -0,0 +1,279 @@
+# NgxFormDesigner
+
+A visual Form Designer for Angular applications, featuring a drag-and-drop interface, responsive layout management, and an enterprise-grade rules engine.
+
+## Features
+- **Drag & Drop**: Intuitive canvas for arranging widgets.
+- **Responsive Layout**: Row/Column system with breakpoint support.
+- **Rules Engine**: Conditional logic (show/hide, validation, disabling) based on field values.
+- **Event Workspace**: Dedicated Events tab for configuring `change/click/blur` actions (`setValue`, `log`, `api`).
+- **Event Datasource Runtime**: API event actions write to `datasourceId`, and mapped widgets auto-refresh.
+- **Search Widget**: Dedicated `core.form:search` widget with autosuggest list + datasource-backed querying.
+- **JSON Schema**: Export/Import forms as simple JSON.
+- **Modern UI**: Built with Tailwind CSS and lucide-angular icons.
+
+## Documentation
+
+Full beginner-friendly docs live in `projects/ngx-form-designer/docs/README.md`:
+
+- `projects/ngx-form-designer/docs/GETTING_STARTED.md`
+- `projects/ngx-form-designer/docs/PUBLIC_API.md`
+- `projects/ngx-form-designer/docs/ARCHITECTURE.md`
+- `projects/ngx-form-designer/docs/SCHEMA_REFERENCE.md`
+- `projects/ngx-form-designer/docs/WIDGETS.md`
+- `projects/ngx-form-designer/docs/PLUGINS.md`
+- `projects/ngx-form-designer/docs/DATA_SOURCES.md`
+- `projects/ngx-form-designer/docs/EVENT_DATASOURCE_RUNTIME.md`
+
+## Installation
+
+```bash
+npm install ngx-form-designer
+```
+
+## Dependencies
+
+This library relies on **Tailwind CSS** and **lucide-angular** for UI styling and iconography.
+
+1.  **Tailwind CSS**: The library uses Tailwind utility classes.
+    
+    **Option A: Using the Preset (Recommended)**
+    In your `tailwind.config.js` (or similar), add the preset:
+
+    ```javascript
+    module.exports = {
+      presets: [
+        require('ngx-form-designer/tailwind.preset.js')
+      ],
+      content: [
+        "./src/**/*.{html,ts}",
+        "./node_modules/ngx-form-designer/**/*.{html,ts,mjs}"
+      ],
+    }
+    ```
+
+    **Option B: Manual Configuration**
+    If you prefer to manually copy the theme tokens, see `projects/ngx-form-designer/docs/STYLING_AND_THEME.md`.
+
+**Design tokens (recommended):** The demo/theme uses Tailwind tokens like `accent-*`, `ink-*`, `slate-*`, `shadow-card`, and `shadow-popover`. If your app doesn’t define them, the UI will still work but can look different. See `projects/ngx-form-designer/docs/STYLING_AND_THEME.md`.
+
+2.  **lucide-angular**: Install and configure lucide-angular icons:
+
+```bash
+npm install lucide-angular
+```
+
+In your `app.config.ts`, import and provide the icons you need:
+```typescript
+import { LucideAngularModule, icons } from 'lucide-angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // ... other providers
+    importProvidersFrom(LucideAngularModule.pick(icons))
+  ]
+};
+```
+
+## Usage
+
+Import `JsonFormDesignerComponent` (standalone) into your component or route.
+
+```typescript
+import { Component } from '@angular/core';
+import { JsonFormDesignerComponent } from 'ngx-form-designer';
+
+@Component({
+  standalone: true,
+  imports: [JsonFormDesignerComponent],
+  template: `<app-json-form-designer></app-json-form-designer>`
+})
+export class MyComponent {}
+```
+
+If you want the full scaffolded UI (top bar + template library) with minimal setup, use the shell component:
+
+```typescript
+import { Component } from '@angular/core';
+import { FormDesignerShellComponent, type DesignerEventApiDefinition } from 'ngx-form-designer';
+
+@Component({
+  standalone: true,
+  imports: [FormDesignerShellComponent],
+  template: `<app-form-designer-shell [eventApis]="eventApis"></app-form-designer-shell>`
+})
+export class MyDesignerPage {
+  eventApis: DesignerEventApiDefinition[] = [];
+}
+```
+
+## Provider setup (required)
+
+Widgets are registered via plugins. The simplest setup is to register the built-in plugin pack:
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import { CORE_DESIGNER_PLUGINS, provideDesignerPlugins } from 'ngx-form-designer';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    ...provideDesignerPlugins(CORE_DESIGNER_PLUGINS),
+  ]
+};
+```
+
+Without this, the palette will be empty and the renderer can’t resolve widgets.
+
+## Publishing
+
+Build the library:
+```bash
+ng build ngx-form-designer
+```
+
+Publish from dist:
+```bash
+cd dist/ngx-form-designer
+npm publish
+```
+## Data Sources (API-only)
+
+The library uses a "Data Sources over APIs" architecture. Widgets should not store large datasets (CSV/JSON arrays) directly in schema. Instead, they reference a `datasourceId` and delegate data fetching to a registered `DataProvider`.
+
+Full guide: `projects/ngx-form-designer/docs/DATA_SOURCES.md`.
+
+### Concepts
+
+1.  **Datasource ID**: A stable string identifier (e.g., `countries`, `users`, `products`) representing a dataset.
+2.  **DataProvider Pipeline**: Widgets request data via the `DataProvider` service.
+    - `DataProvider` delegates to `DataSourceClient`.
+    - `DataSourceClient` is an abstraction you implement (or use the default) to fetch data.
+3.  **Designer & Runtime Consistency**: The Form Designer uses the exact same pipeline to render "Live Previews" of data in the configuration panel.
+
+### Event datasource
+
+Event API actions also write into `datasourceId` (event datasource). Any widget mapped to that datasource (select/search/table/text/date/time) refreshes after the event API call completes.
+
+### Backend API Contract
+
+If you use the HTTP-based `DataSourceClient`, your backend should implement these endpoints:
+
+| Method | Endpoint | Description |
+| :--- | :--- | :--- |
+| `GET` | `/data-sources` | List available data sources (id, label) |
+| `GET` | `/data-sources/{sourceId}` | Get details for a specific source |
+| `GET` | `/data-sources/{sourceId}/columns` | Get column definitions (name, type) |
+| `POST` | `/data-sources/{sourceId}/query` | query rows with filtering/sorting/paging |
+
+**Query Payload Example:**
+```json
+{
+  "page": { "limit": 50, "offset": 0 },
+  "search": { "term": "foo", "columns": ["name"] },
+  "filters": [
+    { "column": "category", "op": "eq", "value": "active" }
+  ],
+  "sort": [ { "column": "name", "dir": "asc" } ]
+}
+```
+
+### Host App Setup
+
+#### 1. In-Memory / Mock Setup
+Use this for rapid prototyping or testing without a real backend.
+
+```typescript
+import { DataCatalog, InMemoryDataCatalogService } from 'ngx-form-designer';
+
+// in app.config.ts
+providers: [
+  { provide: DataCatalog, useExisting: InMemoryDataCatalogService }
+]
+```
+
+#### 2. HTTP Backend Setup
+Use this to connect to your real API.
+
+```typescript
+import { provideHttpDataSourceClient } from 'ngx-form-designer';
+
+// in app.config.ts
+providers: [
+  provideHttpDataSourceClient({
+    baseUrl: 'https://api.example.com',
+    getHeaders: () => ({ Authorization: 'Bearer ' + myAuthService.getToken() })
+  })
+]
+```
+
+### Configuration Examples
+
+#### Basic Dropdown (Select)
+Fetches data from `countries` source, uses `name` as label and `isoCode` as value.
+
+```json
+{
+  "type": "select",
+  "dataConfig": {
+    "type": "source",
+    "datasourceId": "countries",
+    "labelKey": "name",
+    "valueKey": "isoCode"
+  }
+}
+```
+
+#### Search-Enabled Dropdown
+Enables server-side search to handle large datasets.
+
+```json
+{
+  "type": "select",
+  "dataConfig": {
+    "type": "source",
+    "datasourceId": "products",
+    "labelKey": "productName",
+    "valueKey": "id",
+    "searchEnabled": true,
+    "optionsLimit": 20,
+    "searchColumns": ["productName", "sku"]
+  }
+}
+```
+
+#### Tree Select (Hierarchical)
+Expects a flat list of nodes where each node has an ID and a Parent ID.
+
+```json
+{
+  "type": "tree-select",
+  "dataConfig": {
+    "type": "source",
+    "datasourceId": "departments",
+    "labelKey": "title",
+    "valueKey": "id",
+    "treeIdKey": "id",
+    "treeParentKey": "parentId"
+  }
+}
+```
+
+#### Data Table
+Paged table view with server-side sorting.
+
+```json
+{
+  "type": "table",
+  "dataConfig": {
+    "type": "source",
+    "datasourceId": "orders",
+    "pageSize": 10,
+    "sort": [{ "column": "createdAt", "dir": "desc" }]
+  },
+  "columns": [
+    { "key": "id", "label": "Order ID" },
+    { "key": "total", "label": "Amount" },
+    { "key": "status", "label": "Status" }
+  ]
+}
+```

package/convert-legacy-rem-to-sass-function.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+
+const DEFAULT_EXTENSIONS = ['.scss'];
+const DEFAULT_EXCLUDES = ['.git', '.angular', '.next', '.nuxt', 'coverage', 'dist', 'node_modules', 'tmp'];
+
+function formatPxIntent(value, precision) {
+  const rounded = Number(value.toFixed(precision));
+  const normalized = Number.isInteger(rounded) ? `${rounded}` : `${rounded}`;
+  return normalized.replace(/(\.\d*?[1-9])0+$/u, '$1').replace(/\.0$/u, '');
+}
+
+function normalizeUseStatement(useStatement) {
+  return useStatement?.trim() ?? '';
+}
+
+function withUseStatement(text, useStatement) {
+  const normalizedUseStatement = normalizeUseStatement(useStatement);
+  if (!normalizedUseStatement || text.includes(normalizedUseStatement)) {
+    return text;
+  }
+
+  return `${normalizedUseStatement}\n\n${text}`;
+}
+
+export function convertLegacyRemToSassFunctionInText(text, options = {}) {
+  const basePx = options.basePx ?? 10;
+  const precision = options.precision ?? 6;
+
+  const convertedText = text.replace(/(-?(?:\d+\.?\d*|\.\d+))rem\b/gu, (match, numericPart) => {
+    const originalValue = Number(numericPart);
+    if (!Number.isFinite(originalValue) || originalValue === 0) {
+      return match;
+    }
+
+    return `rem(${formatPxIntent(originalValue * basePx, precision)})`;
+  });
+
+  if (convertedText === text) {
+    return text;
+  }
+
+  return withUseStatement(convertedText, options.useStatement);
+}
+
+async function collectFiles(targetPath, options, collected = []) {
+  const stats = await fs.stat(targetPath);
+  if (stats.isFile()) {
+    if (options.includeExtensions.includes(path.extname(targetPath).toLowerCase())) {
+      collected.push(targetPath);
+    }
+    return collected;
+  }
+
+  const entries = await fs.readdir(targetPath, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && options.excludeDirectories.has(entry.name)) {
+      continue;
+    }
+
+    await collectFiles(path.join(targetPath, entry.name), options, collected);
+  }
+
+  return collected;
+}
+
+export async function processScssTargetPath(targetPath, options = {}) {
+  const resolvedOptions = {
+    basePx: options.basePx ?? 10,
+    precision: options.precision ?? 6,
+    useStatement: normalizeUseStatement(options.useStatement),
+    write: options.write ?? false,
+    includeExtensions: options.includeExtensions ?? DEFAULT_EXTENSIONS,
+    excludeDirectories: new Set(options.excludeDirectories ?? DEFAULT_EXCLUDES)
+  };
+
+  const absoluteTargetPath = path.resolve(targetPath);
+  const files = await collectFiles(absoluteTargetPath, resolvedOptions);
+  const changedFiles = [];
+
+  for (const filePath of files) {
+    const currentText = await fs.readFile(filePath, 'utf8');
+    const nextText = convertLegacyRemToSassFunctionInText(currentText, resolvedOptions);
+    if (nextText === currentText) {
+      continue;
+    }
+
+    const replacements = [...currentText.matchAll(/(-?(?:\d+\.?\d*|\.\d+))rem\b/gu)]
+      .filter(([, numericPart]) => Number(numericPart) !== 0)
+      .length;
+
+    changedFiles.push({ filePath, replacements, nextText });
+
+    if (resolvedOptions.write) {
+      await fs.writeFile(filePath, nextText, 'utf8');
+    }
+  }
+
+  return {
+    targetPath: absoluteTargetPath,
+    changedFiles,
+    visitedFiles: files.length
+  };
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/convert-legacy-rem-to-sass-function.mjs <target-path> [--write]
+    [--base=10] [--precision=6] [--use=\"@use 'styles/units' as *;\"]
+    [--exclude=node_modules,dist,.git]
+
+Only .scss files are scanned. Dry-run is the default.`);
+}
+
+function parseCliArgs(argv) {
+  const [targetPath, ...flags] = argv;
+  if (!targetPath || targetPath === '--help' || targetPath === '-h') {
+    return { showHelp: true };
+  }
+
+  const options = {
+    write: false,
+    basePx: 10,
+    precision: 6,
+    useStatement: '',
+    excludeDirectories: DEFAULT_EXCLUDES
+  };
+
+  for (const flag of flags) {
+    if (flag === '--write') {
+      options.write = true;
+      continue;
+    }
+    if (flag.startsWith('--base=')) {
+      options.basePx = Number(flag.slice('--base='.length));
+      continue;
+    }
+    if (flag.startsWith('--precision=')) {
+      options.precision = Number(flag.slice('--precision='.length));
+      continue;
+    }
+    if (flag.startsWith('--use=')) {
+      options.useStatement = flag.slice('--use='.length);
+      continue;
+    }
+    if (flag.startsWith('--exclude=')) {
+      options.excludeDirectories = flag
+        .slice('--exclude='.length)
+        .split(',')
+        .map(value => value.trim())
+        .filter(Boolean);
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${flag}`);
+  }
+
+  if (![options.basePx, options.precision].every(Number.isFinite)) {
+    throw new Error('Numeric arguments must be finite numbers.');
+  }
+
+  return { showHelp: false, targetPath, options };
+}
+
+async function main() {
+  try {
+    const parsed = parseCliArgs(process.argv.slice(2));
+    if (parsed.showHelp) {
+      printUsage();
+      return;
+    }
+
+    const result = await processScssTargetPath(parsed.targetPath, parsed.options);
+    if (!result.changedFiles.length) {
+      console.log(`No legacy rem values needed conversion in ${result.targetPath}`);
+      return;
+    }
+
+    for (const changedFile of result.changedFiles) {
+      console.log(`${parsed.options.write ? 'updated' : 'would update'} ${changedFile.filePath} (${changedFile.replacements} replacements)`);
+    }
+
+    console.log(
+      `${parsed.options.write ? 'Updated' : 'Found'} ${result.changedFiles.length} file(s) out of ${result.visitedFiles} scanned in ${result.targetPath}`
+    );
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  await main();
+}