@openmfp/webcomponents 0.6.1

package/docs/declarative-form.md

@@ -0,0 +1,178 @@
+# DeclarativeForm
+
+A dynamic form web component that renders fields from a declarative field definition. The component does not execute validation logic. It emits per-field change events based on each field's `validation` strategy, accepts host-owned field errors, and emits a nested value only when the host triggers submit.
+
+## Tags
+
+| Usage                              | Tag                         |
+| ---------------------------------- | --------------------------- |
+| Angular component                  | `<mfp-declarative-form>`    |
+| Web Component (framework-agnostic) | `<mfp-wc-declarative-form>` |
+
+---
+
+## Usage as a web component
+
+```html
+<mfp-wc-declarative-form id="form"></mfp-wc-declarative-form>
+
+<script type="module">
+  const form = document.getElementById('form');
+
+  form.fields = [
+    { name: 'metadata.name', label: 'Name', required: true, validation: 'onChange' },
+    { name: 'metadata.namespace', label: 'Namespace', validation: 'onBlur' },
+  ];
+
+  form.addEventListener('fieldChange', (event) => {
+    const { fieldProperty, value } = event.detail;
+    const fieldErrors = { ...form.fieldErrors };
+
+    if (fieldProperty === 'metadata.name' && !value) {
+      fieldErrors[fieldProperty] = 'Name is required';
+    } else {
+      fieldErrors[fieldProperty] = null;
+    }
+
+    form.fieldErrors = fieldErrors;
+  });
+
+  form.addEventListener('formSubmit', (event) => {
+    console.log(event.detail);
+    // { metadata: { name: 'my-app', namespace: 'default' } }
+  });
+
+  // Trigger when the surrounding page decides the form should submit.
+  form.submit();
+</script>
+```
+
+> `fields`, `initialValues`, and `fieldErrors` are JavaScript properties, not HTML attributes.
+
+---
+
+## Usage as an Angular component
+
+```ts
+import {
+  DeclarativeForm,
+  FormFieldChangeEvent,
+  FormFieldDefinition,
+  FormFieldErrors,
+} from '@openmfp/webcomponents';
+
+@Component({
+  imports: [DeclarativeForm],
+  template: `
+    <mfp-declarative-form
+      #form
+      [fields]="fields"
+      [initialValues]="initialValues"
+      [fieldErrors]="fieldErrors"
+      (fieldChange)="onFieldChange($event)"
+      (formSubmit)="onSubmit($event)"
+    />
+
+    <button type="button" (click)="form.submit()">Save</button>
+  `,
+})
+export class MyComponent {
+  fields: FormFieldDefinition[] = [
+    { name: 'metadata.name', label: 'Name', required: true, validation: 'onChange' },
+    { name: 'metadata.namespace', label: 'Namespace', validation: 'onBlur' },
+  ];
+
+  initialValues = {
+    'metadata.name': 'my-app',
+    'metadata.namespace': 'default',
+  };
+
+  fieldErrors: FormFieldErrors = {};
+
+  onFieldChange(event: FormFieldChangeEvent): void {
+    const { fieldProperty, value } = event;
+    this.fieldErrors = {
+      ...this.fieldErrors,
+      [fieldProperty]: !value ? 'Field is required' : null,
+    };
+  }
+
+  onSubmit(value: Record<string, unknown>): void {
+    // value is nested: { metadata: { name: 'my-app', namespace: 'default' } }
+  }
+}
+```
+
+---
+
+## API
+
+### Inputs
+
+| Input           | Type                      | Required | Default | Description                                                                   |
+| --------------- | ------------------------- | -------- | ------- | ----------------------------------------------------------------------------- |
+| `fields`        | `FormFieldDefinition[]`   | yes      | -       | Field definitions to render                                                   |
+| `initialValues` | `Record<string, unknown>` | no       | `{}`    | Initial values keyed by exact `field.name`                                    |
+| `fieldErrors`   | `FormFieldErrors`         | no       | `{}`    | Host-owned errors keyed by exact `field.name`                                 |
+| `editMode`      | `boolean`                 | no       | `false` | Signals edit mode to consumers; does not change component behavior on its own |
+
+### Outputs / Events
+
+| Event        | Detail payload              | Description                                                        |
+| ------------ | --------------------------- | ------------------------------------------------------------------ |
+| `fieldChange` | `FormFieldChangeEvent`      | Fires per-field based on the field's `validation` strategy         |
+| `formSubmit` | `Record<string, unknown>`   | Fires when `submit()` is called; value is nested                   |
+
+---
+
+## Types
+
+```ts
+interface FormFieldDefinition {
+  name: string;                          // Field key; dots create nested submit output paths
+  label?: string;                        // Display label shown above the field
+  required?: boolean;                    // Visual required marker only
+  values?: string[];                     // Static select options
+  disabled?: boolean;                    // Disables the field
+  validation?: 'onBlur' | 'onChange';    // When to emit fieldChange for this field
+}
+
+interface FormFieldChangeEvent {
+  fieldProperty: string;  // The field property name (matches field.name)
+  value: unknown;       // Current value of the control
+}
+
+type FormFieldErrors = Record<string, string | null>;
+```
+
+`fieldChange` emits a single field at a time:
+
+```ts
+{ fieldProperty: 'metadata.name', value: 'my-app' }
+```
+
+`formSubmit` emits a nested object:
+
+```ts
+{
+  metadata: {
+    name: 'my-app',
+    namespace: 'default',
+  },
+}
+```
+
+---
+
+## Validation
+
+- The component never executes validators.
+- `required` only renders the required marker on the label/input.
+- The `validation` property on each field controls when `fieldChange` fires:
+  - `'onChange'` — fires on every value change.
+  - `'onBlur'` — fires when the field loses focus.
+  - Not set — no `fieldChange` event is emitted for that field.
+- On initialization (and when `initialValues` changes), the component emits `fieldChange` for every field that has a `validation` strategy. This lets the host run validation immediately and disable the submit button before the user interacts.
+- The host validates the received `FormFieldChangeEvent` and updates `fieldErrors`.
+- A field shows `Negative` value state and the error message only when it is dirty or touched and `fieldErrors[field.name]` is a non-empty string.
+- Empty, missing, or `null` errors render as no error.

package/docs/declarative-table-card.md

@@ -0,0 +1,235 @@
+# DeclarativeTableCard
+
+A card component that wraps `mfp-declarative-table` and adds a header, search, and optional create/edit/delete dialogs. Form validation and async submit state are owned by the host application.
+
+## Tags
+
+| Usage                              | Tag                               |
+| ---------------------------------- | --------------------------------- |
+| Angular component                  | `<mfp-declarative-table-card>`    |
+| Web Component (framework-agnostic) | `<mfp-wc-declarative-table-card>` |
+
+---
+
+## Usage as a web component
+
+```html
+<mfp-wc-declarative-table-card id="card"></mfp-wc-declarative-table-card>
+
+<script type="module">
+  const card = document.getElementById('card');
+
+  card.resources = [
+    {
+      id: '1',
+      metadata: { name: 'api-server', namespace: 'default' },
+      status: { phase: 'Running' },
+    },
+  ];
+
+  card.config = {
+    header: 'Pods',
+    tableConfig: {
+      fields: [
+        { label: 'Name', property: 'metadata.name' },
+        { label: 'Namespace', property: 'metadata.namespace' },
+      ],
+    },
+    createResourceFormConfig: {
+      fields: [
+        { name: 'metadata.name', label: 'Name', required: true },
+        { name: 'metadata.namespace', label: 'Namespace' },
+      ],
+      title: 'Create Pod',
+      confirmLabel: 'Create',
+    },
+  };
+
+  card.addEventListener('createFieldChange', (event) => {
+    const { fieldProperty, value } = event.detail;
+
+    card.createFormState = {
+      fieldErrors: {
+        ...card.createFormState?.fieldErrors,
+        [fieldProperty]: !value ? 'Field is required' : null,
+      },
+    };
+  });
+
+  card.addEventListener('createSubmit', async (event) => {
+    await createPod(event.detail);
+    card.createFormState = {};
+    card.closeCreateDialog();
+  });
+</script>
+```
+
+---
+
+## Usage as an Angular component
+
+```ts
+import {
+  DeclarativeTableCard,
+  FormFieldChangeEvent,
+  TableCardConfig,
+  TableCardFormState,
+} from '@openmfp/webcomponents';
+
+@Component({
+  imports: [DeclarativeTableCard],
+  template: `
+    <mfp-declarative-table-card
+      #tableCard
+      [config]="config"
+      [resources]="pods"
+      [createFormState]="createFormState"
+      [editFormState]="editFormState"
+      (createFieldChange)="onCreateFieldChange($event)"
+      (editFieldChange)="onEditFieldChange($event)"
+      (createSubmit)="onCreateSubmit($event, tableCard)"
+      (editSubmit)="onEditSubmit($event, tableCard)"
+      (deleteSubmit)="onDeleteSubmit($event, tableCard)"
+      (searchChanged)="onSearch($event)"
+    />
+  `,
+})
+export class MyComponent {
+  pods = [];
+  createFormState: TableCardFormState = {};
+  editFormState: TableCardFormState = {};
+
+  config: TableCardConfig = {
+    header: 'Pods',
+    tableConfig: {
+      fields: [
+        { label: 'Name', property: 'metadata.name' },
+        { label: 'Namespace', property: 'metadata.namespace' },
+      ],
+    },
+    createResourceFormConfig: {
+      fields: [
+        { name: 'metadata.name', label: 'Name', required: true },
+        { name: 'metadata.namespace', label: 'Namespace' },
+      ],
+      title: 'Create Pod',
+      confirmLabel: 'Create',
+    },
+    deleteResourceConfirmationConfig: {
+      title: 'Delete Pod?',
+      message: 'This action cannot be undone.',
+      confirmLabel: 'Delete',
+    },
+  };
+
+  onCreateFieldChange(event: FormFieldChangeEvent): void {
+    const { fieldProperty, value } = event;
+    this.createFormState = {
+      fieldErrors: {
+        ...this.createFormState.fieldErrors,
+        [fieldProperty]: !value ? 'Field is required' : null,
+      },
+    };
+  }
+
+  onEditFieldChange(event: {
+    resource: Pod;
+    formChangeEvent: FormFieldChangeEvent;
+  }): void {
+    // Validate event.formChangeEvent and update editFormState.
+  }
+
+  async onCreateSubmit(
+    value: Record<string, unknown>,
+    tableCard: DeclarativeTableCard<Pod>,
+  ): Promise<void> {
+    await this.createPod(value);
+    this.createFormState = {};
+    tableCard.closeCreateDialog();
+  }
+
+  async onEditSubmit(
+    event: { resource: Pod; value: Record<string, unknown> },
+    tableCard: DeclarativeTableCard<Pod>,
+  ): Promise<void> {
+    await this.updatePod(event.resource, event.value);
+    this.editFormState = {};
+    tableCard.closeEditDialog();
+  }
+
+  async onDeleteSubmit(
+    pod: Pod,
+    tableCard: DeclarativeTableCard<Pod>,
+  ): Promise<void> {
+    await this.deletePod(pod);
+    tableCard.closeDeleteDialog();
+  }
+}
+```
+
+---
+
+## API
+
+### Inputs
+
+| Input             | Type                 | Required | Default | Description                                               |
+| ----------------- | -------------------- | -------- | ------- | --------------------------------------------------------- |
+| `resources`       | `T[]`                | yes      | -       | Data rows passed to the inner table                       |
+| `config`          | `TableCardConfig`    | yes      | -       | Static table, button, and dialog configuration            |
+| `createFormState` | `TableCardFormState` | no       | `{}`    | Runtime validation and submit state for the create dialog |
+| `editFormState`   | `TableCardFormState` | no       | `{}`    | Runtime validation and submit state for the edit dialog   |
+
+### Outputs / Events
+
+| Event                    | Payload                                           | Description                                                  |
+| ------------------------ | ------------------------------------------------- | ------------------------------------------------------------ |
+| `createFieldChange`       | `FormFieldChangeEvent`                            | Re-emits per-field change from the create form               |
+| `editFieldChange`         | `{ resource: T; formChangeEvent: FormFieldChangeEvent }` | Re-emits per-field change from the edit form with resource   |
+| `createSubmit`           | `Record<string, unknown>`                         | Fires when the create dialog Save button is clicked          |
+| `editSubmit`             | `{ resource: T; value: Record<string, unknown> }` | Fires when the edit dialog Save button is clicked            |
+| `deleteSubmit`           | `T`                                               | Fires when the delete dialog Delete button is clicked        |
+| `searchChanged`          | `string`                                          | Emits 300 ms after the search input changes                  |
+| `tableRowClicked`        | `T`                                               | Emits when a table row is clicked                            |
+| `loadMoreResources`      | -                                                 | Emits when the user triggers load more                       |
+| `paginationLimitChanged` | `number`                                          | Emits when the user changes page size                        |
+| `actionButtonClick`      | `ValueCellButtonClickEvent<T>`                    | Emits for row-action buttons other than built-in edit/delete |
+
+### Methods
+
+| Method                | Description              |
+| --------------------- | ------------------------ |
+| `closeCreateDialog()` | Closes the create dialog |
+| `closeEditDialog()`   | Closes the edit dialog   |
+| `closeDeleteDialog()` | Closes the delete dialog |
+
+Submit events do not close dialogs automatically. Close the dialog after successful validation, save, or delete.
+
+---
+
+## Configuration types
+
+```ts
+interface TableCardConfig {
+  header: string;
+  headerTooltip?: string;
+  tableConfig: TableConfig;
+  buttonSettings?: TableCardButtonSettings;
+  createResourceFormConfig?: ResourceFormConfig;
+  editResourceFormConfig?: ResourceFormConfig;
+  deleteResourceConfirmationConfig?: DeleteResourceConfirmationConfig;
+}
+
+interface ResourceFormConfig {
+  fields: FormFieldDefinition[];
+  title?: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+}
+
+interface TableCardFormState {
+  fieldErrors?: FormFieldErrors;
+}
+```
+
+`ResourceFormConfig` is static. Keep runtime errors in `createFormState` / `editFormState`. The submit button is disabled when any entry in `fieldErrors` is truthy.