@mmlogic/components 0.1.9 → 0.1.11

package/README.md

@@ -1,6 +1,6 @@
 # @mmlogic/components
 
-A **Stencil.js v4** web component library for rendering dynamic forms and paginated data tables from API descriptors. Components are framework-agnostic and work in any HTML/JS environment. An Angular output target is included.
+A **Stencil.js v4** web component library for rendering dynamic forms and paginated data tables from API descriptors. Components are framework-agnostic (plain HTML/JS) and an Angular output target is included.
 
 ## Installation
 
@@ -13,7 +13,8 @@ npm install @mmlogic/components
 ### Vanilla HTML / JS
 
 ```html
-<script type="module" src="node_modules/@mmlogic/components/dist/mosterd-components/mosterd-components.esm.js"></script>
+<link rel="stylesheet" href="node_modules/@mmlogic/components/dist/mosterdcomponents/mosterdcomponents.css" />
+<script type="module" src="node_modules/@mmlogic/components/dist/mosterdcomponents/mosterdcomponents.esm.js"></script>
 
 <mrd-form id="my-form"></mrd-form>
 
@@ -28,7 +29,8 @@ npm install @mmlogic/components
 ### Via CDN (unpkg)
 
 ```html
-<script type="module" src="https://unpkg.com/@mmlogic/components/dist/mosterd-components/mosterd-components.esm.js"></script>
+<link rel="stylesheet" href="https://unpkg.com/@mmlogic/components/dist/mosterdcomponents/mosterdcomponents.css" />
+<script type="module" src="https://unpkg.com/@mmlogic/components/dist/mosterdcomponents/mosterdcomponents.esm.js"></script>
 ```
 
 ### Angular
@@ -50,45 +52,118 @@ export class AppModule {}
 
 ### `<mrd-form>`
 
-Renders a complete form from a layout descriptor. Handles validation, RTL layout (Arabic locale), and emits the submitted values.
+Renders a complete form from a layout descriptor. Handles validation, RTL layout (Arabic locale), and orchestrates file uploads, relation search, and dependent dropdowns.
 
 ```html
-<mrd-form id="form" locale="nl-NL"></mrd-form>
+<mrd-form id="form" locale="nl-NL" show-cancel></mrd-form>
 ```
 
 ```js
+const form = document.getElementById('form');
+
 form.layout = {
-  title: 'New order',
+  title: 'New invoice',
   items: [
-    { type: 'FIELD', field: { name: 'name', label: 'Name', dataType: 'TEXT', required: true } },
+    { type: 'FIELD', field: { name: 'description', label: 'Description', dataType: 'TEXT', required: true } },
     { type: 'FIELD', field: { name: 'amount', label: 'Amount', dataType: 'CURRENCY' } },
   ]
 };
-form.addEventListener('mrdSubmit', e => console.log(e.detail.values));
-form.addEventListener('mrdCancel', () => console.log('cancelled'));
+
+form.addEventListener('mrdSubmit', e => console.log(e.detail));
+form.addEventListener('mrdCancel', () => history.back());
 ```
 
-**Props**
+#### Props
 
-| Prop | Type | Description |
-|---|---|---|
-| `layout` | `ClientLayout` | Form descriptor with title and items |
-| `values` | `Record<string, any>` | Initial field values |
-| `locale` | `string` | BCP 47 locale (default: `navigator.language`) |
-| `disabled` | `boolean` | Disables all inputs |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `layout` | `ClientLayout` | required | Form descriptor with `title` and `items[]` |
+| `values` | `Record<string, any>` | `{}` | Initial field values; re-setting this prop re-fills the form (edit mode) |
+| `locale` | `string` | `navigator.language` | BCP 47 locale for labels, validation messages, and formatting |
+| `referenceHref` | `string` | `''` | Absolute href of a parent/context object. Combined with `referenceClass`, `mrd-form` automatically pre-fills the matching relation field so dependent dropdowns load without any host-side form logic. |
+| `referenceClass` | `string` | `''` | `mostSignificantClass` of the parent object (e.g. `'clientAgreements'`). Used to locate the relation field to pre-fill. |
+| `showCancel` | `boolean` | `false` | When `true`, shows a Cancel button next to Submit in the footer. |
 
-**Events**
+#### Events
 
 | Event | Detail | Description |
 |---|---|---|
-| `mrdSubmit` | `{ values: Record<string, any> }` | Form submitted and valid |
-| `mrdCancel` | — | Cancel button clicked |
+| `mrdSubmit` | `Record<string, any>` | Fired on valid submit. Payload contains only layout fields; relation values are normalised to plain href strings. |
+| `mrdCancel` | — | Fired when the Cancel button is clicked. Host handles navigation. |
+| `mrdSearch` | `{ query: string; relatedClass: string }` | Relation search requested. Host calls `field.setSearchResults(results)` with the API response. |
+| `mrdFetchAll` | see below | All records requested for a DROPDOWN relation. Host calls `field.setAllRecords(results)`. |
+| `mrdUpload` | `{ name: string; file: File }` | A file was selected. Host uploads the file and calls `form.setFieldValue(name, uri)` when done. The field shows a loading spinner until the URI arrives. |
+
+#### Methods
+
+| Method | Description |
+|---|---|
+| `setFieldValue(name, value)` | Inject a value into a named field from outside (e.g. after a file upload completes). |
+| `setSearchResults(results)` | *(on `mrd-relation-field`)* Populate the search autocomplete list. |
+| `setAllRecords(results)` | *(on `mrd-relation-field`)* Populate a DROPDOWN `<select>` with all records. |
+
+#### `mrdFetchAll` event detail
+
+```ts
+{
+  name: string;                  // field name — use to find the mrd-relation-field element
+  relatedClass: string;          // dot-notation class (e.g. "legalmanager.budget")
+  mostSignificantClass?: string; // URL segment (e.g. "budgets")
+  commonRelation?: string;       // name of the dependency field (for dependent dropdowns)
+  filter?: string;               // query param name
+  filterValue?: string;          // href of the selected dependency; empty string = clear list
+}
+```
+
+#### Full integration example
+
+```js
+// mrdSearch — typeahead for RELATION fields
+form.addEventListener('mrdSearch', async (e) => {
+  const { query, relatedClass } = e.detail;
+  const data = await fetch(`/api/search/${relatedClass}?q=${query}`).then(r => r.json());
+  const field = form.querySelector(`mrd-relation-field[name="${relatedClass}"]`);
+  field?.setSearchResults(data.map(r => ({ id: r._links.self.href, label: r.name })));
+});
+
+// mrdFetchAll — populate DROPDOWN selects (including dependent dropdowns)
+form.addEventListener('mrdFetchAll', async (e) => {
+  const { name, mostSignificantClass, filter, filterValue } = e.detail;
+  const field = form.querySelector(`mrd-relation-field[name="${name}"]`);
+  if (!field) return;
+
+  if (filter && !filterValue) {       // dependency cleared → empty the list
+    field.setAllRecords([]);
+    return;
+  }
+
+  let url = `/data/${tenantId}/${mostSignificantClass}`;
+  if (filter && filterValue) url += `?${filter}=${encodeURIComponent(filterValue)}`;
+  const result = await fetch(url).then(r => r.json());
+  const records = Object.values(result._embedded ?? {})[0] ?? [];
+  field.setAllRecords(records.map(r => ({ id: r._links.self.href, label: r.name })));
+});
+
+// mrdUpload — stream file to server before submit
+form.addEventListener('mrdUpload', async (e) => {
+  const { name, file } = e.detail;
+  const formData = new FormData();
+  formData.append('file', file);
+
+  // Get pre-signed upload URL from server, then POST the file
+  const uploadUrl = await fetch('/api/upload').then(r => r.json());
+  const [uri] = await fetch(uploadUrl, { method: 'POST', body: formData }).then(r => r.json());
+
+  // Return the stored URI to the field — spinner disappears, value is ready for submit
+  form.setFieldValue(name, uri);
+});
+```
 
 ---
 
 ### `<mrd-table>`
 
-A virtual-scroll paginated table. Only the visible rows (plus a configurable buffer) are rendered in the DOM. Pages are fetched on demand via an event.
+A virtual-scroll paginated table with column sorting, Excel-style filtering, toolbar actions, and a pagination footer. Only visible rows are in the DOM; pages are fetched on demand via an event.
 
 ```html
 <mrd-table id="table"></mrd-table>
@@ -97,60 +172,105 @@ A virtual-scroll paginated table. Only the visible rows (plus a configurable buf
 ```js
 const table = document.getElementById('table');
 
-table.columns       = view.values;       // TableColumn[] from dashboard API
+table.columns       = view.columns;        // TableColumn[]
 table.totalElements = page.totalElements;
 table.pageSize      = page.size;
-table.tableHeight   = 500;               // px, fixed container height
-table.locale        = 'nl-NL';
+table.tableHeight   = 500;                 // px, fixed container height
+table.locale        = 'nl-NL';            // en / nl / ar / fr
 table.defaultSort   = view.defaultSort ?? '';
+table.actions       = [
+  { action: 'create', label: 'New record',        icon: 'assets/sprites.svg#icon-plus',       variant: 'primary' },
+  { action: 'export', label: 'Export to Excel',   icon: 'assets/sprites.svg#icon-file-excel', disabled: true },
+];
+
+let activeFilters = [];
+
+table.addEventListener('mrdFilter', (e) => {
+  activeFilters = e.detail.filters;   // ColumnFilter[]
+});
 
 table.addEventListener('mrdLoadPage', async (e) => {
   const { page, sort } = e.detail;
-  const url      = `${dataHref}?page=${page}${sort ? '&sort=' + sort : ''}`;
-  const result   = await fetch(url, { headers: { Authorization: `Bearer ${token}` } }).then(r => r.json());
-  const rows     = Object.values(result._embedded ?? {})[0] ?? [];
+  const params = new URLSearchParams();
+  if (page > 0) params.set('page', String(page));
+  if (sort)     params.set('sort', sort);
+  activeFilters.forEach(f => {
+    if (f.operator === 'isEmpty')     { params.set(f.field, '');                   return; }
+    if (f.operator === 'isNotEmpty')  { params.set(f.field + '_notempty', 'true'); return; }
+    if (f.values?.length)             { params.set(f.field, f.values.join(','));    return; }
+    if (f.value  != null) params.set(f.field,           String(f.value));
+    if (f.from   != null) params.set(f.field + '_from',  String(f.from));
+    if (f.to     != null) params.set(f.field + '_to',    String(f.to));
+  });
+  const qs     = params.toString();
+  const result = await fetch(qs ? `${dataUrl}?${qs}` : dataUrl).then(r => r.json());
+  const rows   = Object.values(result._embedded ?? {})[0] ?? [];
   await table.setPage(page, rows);
 });
 
+table.addEventListener('mrdAction', (e) => {
+  if (e.detail.action === 'create') location.href = '/new';
+  if (e.detail.action === 'export') window.open(excelUrl, '_blank');
+});
+
+table.addEventListener('mrdRowClick', (e) => {
+  location.href = e.detail._links.self.href;
+});
+
 await table.init();
-await table.setPage(0, page0Rows); // inject pre-fetched page 0
+await table.setPage(0, page0Rows); // inject pre-fetched page 0 without a second request
 ```
 
-**Props**
+#### Props
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `columns` | `TableColumn[]` | `[]` | Column definitions |
-| `totalElements` | `number` | `0` | Total records (`0` = non-paginated mode using `rows` prop) |
-| `pageSize` | `number` | `20` | Records per page |
+| `totalElements` | `number` | `0` | Total record count. `0` = non-paginated mode (use `rows` prop instead) |
+| `pageSize` | `number` | `20` | Records per page (must match API page size) |
 | `rowHeight` | `number` | `36` | Row height in px |
-| `tableHeight` | `number` | `500` | Container height in px |
-| `locale` | `string` | `navigator.language` | Locale for cell formatting |
+| `tableHeight` | `number` | `500` | Fixed scroll-container height in px |
+| `locale` | `string` | `navigator.language` | Locale for cell formatting and built-in labels (`en`/`nl`/`ar`/`fr`) |
 | `defaultSort` | `string` | `''` | Initial sort, e.g. `"timestamp,desc"` or `"name"` |
 | `rows` | `Record[]` | `[]` | Rows for non-paginated mode |
+| `actions` | `TableAction[]` | `[]` | Toolbar action buttons (`{ action, label, icon?, variant?, disabled? }`) |
 
-**Events**
+#### Events
 
 | Event | Detail | Description |
 |---|---|---|
 | `mrdLoadPage` | `{ page: number; sort: string }` | Fired when a page needs to be fetched |
+| `mrdRowClick` | row object | Fired when a data row is clicked |
+| `mrdAction` | `{ action: string }` | Fired when a toolbar action button is clicked |
+| `mrdFilter` | `{ filters: ColumnFilter[] }` | Fired when active column filters change |
 
-**Methods**
+#### Methods
 
 | Method | Description |
 |---|---|
-| `init()` | Reset state and render window; call after props are set and before `setPage(0, …)` |
-| `setPage(page, rows)` | Inject fetched rows for a page number |
+| `init()` | Reset state and render window. Call after all props are set and before `setPage(0, …)`. |
+| `setPage(page, rows)` | Inject fetched rows for a page. Automatically clamps the render window when the page is shorter than `pageSize` — prevents shimmer rows beyond actual data. |
 
-**Column sorting**
+**Sort format:** `"fieldName"` for ASC, `"fieldName,desc"` for DESC — append directly as `&sort=<value>`.
 
-Click any column header to sort. Clicking again toggles ASC ↔ DESC. The active column is highlighted and shows ▲ / ▼. The `sort` value in the `mrdLoadPage` event is the raw query-param value (`"fieldname"` or `"fieldname,desc"`).
+#### Column filtering
+
+A filter-toggle button (▼) in the toolbar activates filter mode. Clicking ▾ in any column header opens a popup with sort and type-specific filter controls. Supported per data type:
+
+| DataType | Filter |
+|---|---|
+| TEXT, EMAIL, HYPERLINK, RELATION | Starts with / equals / is empty / is not empty |
+| INTEGER, DECIMAL, PERCENTAGE, CURRENCY | Exact value or from–to range |
+| DATE, DATETIME, TIME | Exact date or from–to range |
+| BOOLEAN | All / Yes / No |
+| LIST | Checkbox list |
+| FILE, IMAGE | Not supported |
 
 ---
 
 ### Field components
 
-Individual input components can be used standalone. Each emits `mrdChange` and `mrdBlur`.
+All leaf components can be used standalone. Each emits `mrdChange` and `mrdBlur`.
 
 | Component | DataType | Description |
 |---|---|---|
@@ -165,53 +285,68 @@ Individual input components can be used standalone. Each emits `mrdChange` and `
 | `<mrd-email-field>` | `EMAIL` | Email input with validation |
 | `<mrd-hyperlink-field>` | `HYPERLINK` | URL input with validation |
 | `<mrd-list-field>` | `LIST` | Single dropdown or multi-checkbox |
-| `<mrd-file-field>` | `FILE` | Drag-and-drop file upload |
-| `<mrd-image-field>` | `IMAGE` | Drag-and-drop image upload with preview |
-| `<mrd-relation-field>` | `RELATION` | Search (event-driven) or dropdown |
+| `<mrd-file-field>` | `FILE` | Drag-and-drop file upload with upload spinner |
+| `<mrd-image-field>` | `IMAGE` | Drag-and-drop image upload with local preview and spinner |
+| `<mrd-relation-field>` | `RELATION` | Typeahead search (event-driven) or DROPDOWN select |
 
-**Common props for field components**
+#### Common props
 
 | Prop | Type | Description |
 |---|---|---|
-| `name` | `string` | Field name, included in `mrdChange` detail |
+| `name` | `string` | Field name, echoed in event detail |
 | `label` | `string` | Visible label |
 | `value` | `any` | Current value |
-| `required` | `boolean` | Shows validation error when empty on blur |
+| `required` | `boolean` | Validates on blur; shows error when empty |
 | `disabled` | `boolean` | Disables the input |
-| `locale` | `string` | BCP 47 locale for formatting |
+| `locale` | `string` | BCP 47 locale |
 
-**Events for field components**
+#### Common events
 
-| Event | Detail |
-|---|---|
-| `mrdChange` | `{ name: string; value: any }` |
-| `mrdBlur` | `{ name: string; value: any }` |
+| Event | Detail | Description |
+|---|---|---|
+| `mrdChange` | `{ name: string; value: any }` | Fired on every value change |
+| `mrdBlur` | `{ name: string; value: any }` | Fired on blur (triggers validation) |
+| `mrdUpload` | `{ name: string; file: File }` | *(file/image only)* Fired immediately when a file is selected so the host can stream it to the server |
+
+#### File / image upload flow
+
+When a file is picked:
+1. The field emits `mrdUpload` with the raw `File` object.
+2. The field immediately shows a spinner and updates its value to the `File` (blocking submit).
+3. The host uploads the file and calls `form.setFieldValue(name, uri)` (or `field.value = uri`).
+4. The field detects the string URI, clears the spinner, and is ready for submit.
+
+The submit payload always contains the final URI string — never a `File` object.
 
 ---
 
 ## Theming
 
-All visual properties are CSS custom properties. Override them on `:root` or any ancestor element:
+All design tokens are CSS custom properties. The default primary colour is **green** (`#16a34a`). Override on `:root` or any ancestor to match your brand:
 
 ```css
 :root {
-  --mrd-color-primary:      #2563eb;
-  --mrd-color-neutral-100:  #f3f4f6;
-  --mrd-border-radius:      0.375rem;
-  --mrd-font-size-sm:       0.875rem;
-  /* see full list in src/global/variables.scss */
+  --mrd-color-primary:       #16a34a;   /* green-600 — change to your brand colour */
+  --mrd-color-primary-light: #dcfce7;
+  --mrd-color-primary-dark:  #15803d;
+  --mrd-color-primary-hover: #166534;
+  --mrd-shadow-focus:        0 0 0 3px rgb(22 163 74 / 0.2); /* match primary */
+
+  --mrd-color-neutral-100:   #f3f4f6;
+  --mrd-border-radius:       0.375rem;
+  --mrd-font-size-sm:        0.875rem;
 }
 ```
 
+The full list is defined in `src/global/variables.scss` and exposed in the built file `dist/mosterdcomponents/mosterdcomponents.css`.
+
 ---
 
 ## TypeScript types
 
-Types are exported from the package root:
-
 ```ts
-import type { TableColumn } from '@mmlogic/components/dist/types/utils/cell-renderer';
-import type { ClientLayout, ClientLayoutItem } from '@mmlogic/components/dist/types/types/client-layout';
+import type { ClientLayout, ClientLayoutItem, RelationSearchResult } from '@mmlogic/components';
+import type { TableColumn, TableAction, ColumnFilter } from '@mmlogic/components/dist/types/utils/cell-renderer';
 ```
 
 ---