@futdevpro/fsm-dynamo 1.15.20 → 1.15.22

package/src/_modules/ngx-models/_models/control-models/forms-new/field-new-settings.control-model.ts

@@ -0,0 +1,85 @@
+import { DyFM_Field_Type } from '../../../_enums/field-type.enum';
+import { DyFM_FieldNew_Validator_Type } from '../../../_enums/forms-new/field-new-validator-type.enum';
+
+/**
+ * Validator descriptor — JSON-serializálható, server-importálható.
+ *
+ * A `value` mező típus-függő: `minLength`/`maxLength`/`min`/`max` esetén `number`,
+ * `pattern` esetén `string` (regex source), egyébként `undefined`.
+ *
+ * A `message` opcionális — ha hiányzik, a render-réteg default üzenetet használ.
+ */
+export interface DyFM_FieldNew_Validator_Descriptor {
+  type: DyFM_FieldNew_Validator_Type;
+  value?: string | number;
+  message?: string;
+}
+
+/**
+ * Forms v2 (BL-FORMS-V2 Wave-1A) — Field Settings base class.
+ *
+ * POJO, JSON-serializálható, **dynamo-ngx-models**-ben él, hogy a szerver-oldali
+ * `fsm-dynamo` is tudja példányosítani / type-import-olni.
+ *
+ * Wave-1 megkötések:
+ *  - `key` kötelező + NEM tartalmazhat `.`-ot (nested-key tiltva — Wave-2 hozza).
+ *  - Function-mezők (`onSubmit`, `compareWith`, …) NEM ezen az osztályon — a Params
+ *    konstruktor `runtimeOptions` argumentumában.
+ *
+ * @see _specifications/forms-v2/02-architecture-spec.md (2.2)
+ * @see _specifications/forms-v2/04-verification.md (Q7, Q9)
+ */
+export abstract class DyFM_FieldNew_Settings<T = unknown> {
+  /** A field azonosítója + data-key. Wave-1-ben NEM tartalmazhat `.`-ot. */
+  key!: string;
+
+  /** Mező-típus diszkriminátor — minden subclass override-olja konkrét enum-szal. */
+  abstract readonly type: DyFM_Field_Type;
+
+  /** Megjelenítendő label. Asterisk + `required` esetén render-réteg jelzi. */
+  label?: string;
+
+  /** Helper / leírás (tooltip / fieldset-magyarázat). */
+  description?: string;
+
+  /** Placeholder (üres input megjelenítése). */
+  placeholder?: string;
+
+  /** Default érték — primitív vagy egyszerű object. */
+  defaultValue?: T;
+
+  /** Validator descriptor-ok (POJO, NEM Angular ValidatorFn). */
+  validators?: DyFM_FieldNew_Validator_Descriptor[];
+
+  /** Disabled flag — kezdeti állapot. A runtime Signal-en át felülírható. */
+  disabled?: boolean;
+
+  /** Read-only mód külön a disabled-től (gomb-feliratoknak külön). */
+  readOnly?: boolean;
+
+  /** Grid-méret 12-col rendszeren. Default 12 = full-width. */
+  gridSize?: number;
+
+  /** Kötelező-e — shortcut a `validators[required]` mellett a label-asterisk-hez. */
+  required?: boolean;
+
+  /** `data-testid` érték — Wave-1-ben ad-hoc, lásd 04-verify Q6. */
+  testId?: string;
+
+  /**
+   * @param set Részleges (Partial) konstruktor-input. A `key` kötelező; nested-key
+   *            (`'.'`-ot tartalmazó) Wave-1-ben dob.
+   */
+  constructor(set: Partial<DyFM_FieldNew_Settings<T>> = {}) {
+    if (!set.key) {
+      throw new Error('DyFM_FieldNew_Settings: `key` is required');
+    }
+    if (set.key.includes('.')) {
+      throw new Error(
+        'DyFM_FieldNew_Settings: Wave-1 does not support nested keys (`.` in `key`). ' +
+        'Use a flat `key` or wait for Wave-2.',
+      );
+    }
+    Object.assign(this, set);
+  }
+}

package/src/_modules/ngx-models/_models/control-models/forms-new/field-new-types.ts

@@ -0,0 +1,24 @@
+import { DyFM_CheckboxFieldNew_Settings } from './checkbox-field-new-settings.control-model';
+import { DyFM_DateFieldNew_Settings } from './date-field-new-settings.control-model';
+import { DyFM_MultiselectFieldNew_Settings } from './multiselect-field-new-settings.control-model';
+import { DyFM_NumberFieldNew_Settings } from './number-field-new-settings.control-model';
+import { DyFM_SelectFieldNew_Settings } from './select-field-new-settings.control-model';
+import { DyFM_TextAreaFieldNew_Settings } from './textarea-field-new-settings.control-model';
+import { DyFM_TextFieldNew_Settings } from './text-field-new-settings.control-model';
+
+/**
+ * Forms v2 (Wave-1A) — Settings-szintű discriminated union.
+ *
+ * Ezen a típuson a TypeScript `field.type === DyFM_Field_Type.text` után már a
+ * `DyFM_TextFieldNew_Settings` altípust ismeri (type-narrowing).
+ *
+ * @see _specifications/forms-v2/02-architecture-spec.md (11. mátrix)
+ */
+export type DyFM_FieldNew_Settings_AnyType =
+  | DyFM_TextFieldNew_Settings
+  | DyFM_TextAreaFieldNew_Settings
+  | DyFM_NumberFieldNew_Settings
+  | DyFM_CheckboxFieldNew_Settings
+  | DyFM_SelectFieldNew_Settings<unknown>
+  | DyFM_MultiselectFieldNew_Settings<unknown>
+  | DyFM_DateFieldNew_Settings;

package/src/_modules/ngx-models/_models/control-models/forms-new/form-new-settings.control-model.ts

@@ -0,0 +1,40 @@
+import { DyFM_FieldNew_Settings_AnyType } from './field-new-types';
+
+/**
+ * Forms v2 (Wave-1A) — Form Settings (POJO, server-importálható).
+ *
+ * Pure adat — function-handlers (`onSubmit`, `onCancel`) a Params kétparaméteres
+ * konstruktor `runtimeOptions`-ában élnek (lásd 02-spec section 5.2 + 04-verify Q7).
+ *
+ * @template T A form-adat target-típusa (pl. `{ name: string; priority: number }`).
+ * @see _specifications/forms-v2/02-architecture-spec.md (5.2)
+ */
+export class DyFM_FormNew_Settings<T = unknown> {
+  /** Megjelenítendő cím. */
+  title?: string;
+
+  /** Egyedi azonosító (storage-key alapja, debug-helye). */
+  id?: string;
+
+  /** A form mezői — diszkriminált union per-típus Settings-szel. */
+  fields: DyFM_FieldNew_Settings_AnyType[] = [];
+
+  /** Cancel-gomb feliratának fenntartása (Wave-2-ben kibővülhet `cancelButton: DyFM_Button_Params`-ra). */
+  cancelLabel?: string;
+
+  /** Submit-gomb felirata. */
+  submitLabel?: string;
+
+  /**
+   * Wave-1-re elég a `T` típus-paraméter — bár a `fields` runtime-on `_AnyType`-ot
+   * tárol. A `T` később (Wave-2-ben) szigorúbb derived-data-típus-checkre használható.
+   */
+  private readonly __typeHelper?: T;
+
+  constructor(set: Partial<DyFM_FormNew_Settings<T>>) {
+    Object.assign(this, set);
+    if (!this.fields) {
+      this.fields = [];
+    }
+  }
+}

package/src/_modules/ngx-models/_models/control-models/forms-new/forms-new.spec.ts

@@ -0,0 +1,179 @@
+import { DyFM_Field_Type } from '../../../_enums/field-type.enum';
+import { DyFM_FieldNew_Validator_Type } from '../../../_enums/forms-new/field-new-validator-type.enum';
+import {
+  DyFM_CheckboxFieldNew_Settings,
+  DyFM_DateFieldNew_Settings,
+  DyFM_FieldNew_Settings,
+  DyFM_FormNew_Settings,
+  DyFM_MultiselectFieldNew_Settings,
+  DyFM_NumberFieldNew_Settings,
+  DyFM_SelectFieldNew_Settings,
+  DyFM_SelectNewOption,
+  DyFM_TextAreaFieldNew_Settings,
+  DyFM_TextFieldNew_Settings,
+} from './index';
+
+describe('| Forms v2 — Wave-1A Settings layer', () => {
+
+  describe('| DyFM_FieldNew_Settings base — guardrails', () => {
+    it('| throws if `key` is missing', () => {
+      expect(() => new DyFM_TextFieldNew_Settings({} as never))
+        .toThrowError(/`key` is required/);
+    });
+
+    it('| throws if `key` contains `.` (nested-key Wave-1 prohibited)', () => {
+      expect(() => new DyFM_TextFieldNew_Settings({ key: 'user.name' } as never))
+        .toThrowError(/nested keys/);
+    });
+
+    it('| accepts a flat `key`', () => {
+      const s = new DyFM_TextFieldNew_Settings({ key: 'title' });
+      expect(s.key).toBe('title');
+      expect(s.type).toBe(DyFM_Field_Type.text);
+    });
+
+    it('| ignores explicit `type` in the input set (readonly guard)', () => {
+      // A user incorrectly passes `type: 'number'` to TextField — the readonly hardcoded
+      // type should win.
+      const s = new DyFM_TextFieldNew_Settings({
+        key: 'x',
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        type: DyFM_Field_Type.number as any,
+      });
+      expect(s.type).toBe(DyFM_Field_Type.text);
+    });
+  });
+
+  describe('| DyFM_TextFieldNew_Settings', () => {
+    it('| stores mask/prefix/suffix/maxLength', () => {
+      const s = new DyFM_TextFieldNew_Settings({
+        key: 'phone', mask: '(000) 000-0000', prefix: '+', suffix: ' US', maxLength: 14,
+      });
+      expect(s.mask).toBe('(000) 000-0000');
+      expect(s.prefix).toBe('+');
+      expect(s.suffix).toBe(' US');
+      expect(s.maxLength).toBe(14);
+    });
+  });
+
+  describe('| DyFM_TextAreaFieldNew_Settings', () => {
+    it('| stores rows/maxLength + type is textarea', () => {
+      const s = new DyFM_TextAreaFieldNew_Settings({ key: 'desc', rows: 5, maxLength: 500 });
+      expect(s.type).toBe(DyFM_Field_Type.textarea);
+      expect(s.rows).toBe(5);
+      expect(s.maxLength).toBe(500);
+    });
+  });
+
+  describe('| DyFM_NumberFieldNew_Settings', () => {
+    it('| stores min/max/step + type is number', () => {
+      const s = new DyFM_NumberFieldNew_Settings({ key: 'priority', min: 0, max: 100, step: 5 });
+      expect(s.type).toBe(DyFM_Field_Type.number);
+      expect(s.min).toBe(0);
+      expect(s.max).toBe(100);
+      expect(s.step).toBe(5);
+    });
+  });
+
+  describe('| DyFM_CheckboxFieldNew_Settings', () => {
+    it('| default constructor + type is checkbox', () => {
+      const s = new DyFM_CheckboxFieldNew_Settings({ key: 'done' });
+      expect(s.type).toBe(DyFM_Field_Type.checkbox);
+    });
+    it('| stores mode (toggle / checkbox) + labelPosition', () => {
+      const s = new DyFM_CheckboxFieldNew_Settings({
+        key: 'active', mode: 'toggle', labelPosition: 'before',
+      });
+      expect(s.mode).toBe('toggle');
+      expect(s.labelPosition).toBe('before');
+    });
+  });
+
+  describe('| DyFM_SelectFieldNew_Settings<T>', () => {
+    it('| stores options + type is select', () => {
+      const opts: DyFM_SelectNewOption<string>[] = [
+        { label: 'A', value: 'a' },
+        { label: 'B', value: 'b', disabled: true },
+      ];
+      const s = new DyFM_SelectFieldNew_Settings<string>({ key: 'category', options: opts });
+      expect(s.type).toBe(DyFM_Field_Type.select);
+      expect(s.options.length).toBe(2);
+      expect(s.options[1].disabled).toBe(true);
+    });
+    it('| defaults to empty options[]', () => {
+      const s = new DyFM_SelectFieldNew_Settings<string>({ key: 'category' });
+      expect(s.options).toEqual([]);
+    });
+  });
+
+  describe('| DyFM_MultiselectFieldNew_Settings<T>', () => {
+    it('| stores options + type is multiselect + defaultValue is T[]', () => {
+      const s = new DyFM_MultiselectFieldNew_Settings<string>({
+        key: 'tags',
+        options: [{ label: 'A', value: 'a' }, { label: 'B', value: 'b' }],
+        defaultValue: ['a'],
+      });
+      expect(s.type).toBe(DyFM_Field_Type.multiselect);
+      expect(s.options.length).toBe(2);
+      expect(s.defaultValue).toEqual(['a']);
+    });
+  });
+
+  describe('| DyFM_DateFieldNew_Settings', () => {
+    it('| stores minDate/maxDate as ISO strings + type is date', () => {
+      const s = new DyFM_DateFieldNew_Settings({
+        key: 'dueDate', minDate: '2026-01-01', maxDate: '2026-12-31',
+      });
+      expect(s.type).toBe(DyFM_Field_Type.date);
+      expect(s.minDate).toBe('2026-01-01');
+      expect(s.maxDate).toBe('2026-12-31');
+    });
+  });
+
+  describe('| DyFM_FormNew_Settings<T>', () => {
+    it('| stores title and fields (discriminated union)', () => {
+      const titleField = new DyFM_TextFieldNew_Settings({ key: 'title', required: true });
+      const prioField = new DyFM_NumberFieldNew_Settings({ key: 'prio', min: 0, max: 100 });
+      const form = new DyFM_FormNew_Settings<{ title: string; prio: number }>({
+        title: 'Task editor',
+        fields: [titleField, prioField],
+      });
+      expect(form.title).toBe('Task editor');
+      expect(form.fields.length).toBe(2);
+      expect(form.fields[0].type).toBe(DyFM_Field_Type.text);
+      expect(form.fields[1].type).toBe(DyFM_Field_Type.number);
+    });
+    it('| defaults to empty fields[]', () => {
+      const form = new DyFM_FormNew_Settings({});
+      expect(form.fields).toEqual([]);
+    });
+  });
+
+  describe('| Validators (descriptor shape sanity)', () => {
+    it('| stores a required + maxLength descriptor on the field', () => {
+      const s = new DyFM_TextFieldNew_Settings({
+        key: 'title',
+        validators: [
+          { type: DyFM_FieldNew_Validator_Type.required },
+          { type: DyFM_FieldNew_Validator_Type.maxLength, value: 100, message: 'Too long' },
+        ],
+      });
+      expect(s.validators).toBeDefined();
+      expect(s.validators!.length).toBe(2);
+      expect(s.validators![0].type).toBe(DyFM_FieldNew_Validator_Type.required);
+      expect(s.validators![1].value).toBe(100);
+      expect(s.validators![1].message).toBe('Too long');
+    });
+  });
+
+  describe('| Settings discriminated-union typing', () => {
+    it('| each field type narrows correctly in a switch', () => {
+      const fields: DyFM_FieldNew_Settings[] = [
+        new DyFM_TextFieldNew_Settings({ key: 't' }),
+        new DyFM_NumberFieldNew_Settings({ key: 'n' }),
+      ];
+      const types = fields.map((f) => f.type);
+      expect(types).toEqual([DyFM_Field_Type.text, DyFM_Field_Type.number]);
+    });
+  });
+});

package/src/_modules/ngx-models/_models/control-models/forms-new/index.ts

@@ -0,0 +1,13 @@
+// Forms v2 (BL-FORMS-V2 Wave-1A) — Settings réteg barrel-export.
+// Lásd: _specifications/forms-v2/
+
+export * from './field-new-settings.control-model';
+export * from './text-field-new-settings.control-model';
+export * from './textarea-field-new-settings.control-model';
+export * from './number-field-new-settings.control-model';
+export * from './checkbox-field-new-settings.control-model';
+export * from './select-field-new-settings.control-model';
+export * from './multiselect-field-new-settings.control-model';
+export * from './date-field-new-settings.control-model';
+export * from './form-new-settings.control-model';
+export * from './field-new-types';

package/src/_modules/ngx-models/_models/control-models/forms-new/multiselect-field-new-settings.control-model.ts

@@ -0,0 +1,27 @@
+import { DyFM_Field_Type } from '../../../_enums/field-type.enum';
+import { DyFM_FieldNew_Settings } from './field-new-settings.control-model';
+import { DyFM_SelectNewOption } from './select-field-new-settings.control-model';
+
+/**
+ * Forms v2 (Wave-1A) — multi-select field settings.
+ *
+ * Wave-1 render: **checkbox-list** (egy checkbox per option, `T[]` value).
+ * Chip-display Wave-2 (lásd 03-implementation-plan Wave-1B / Wave-2A).
+ *
+ * @see _specifications/forms-v2/04-verification.md (C kockázat-mátrix)
+ */
+export class DyFM_MultiselectFieldNew_Settings<T = string> extends DyFM_FieldNew_Settings<T[]> {
+  override readonly type: DyFM_Field_Type.multiselect = DyFM_Field_Type.multiselect;
+
+  /** Választási opciók listája. */
+  options: DyFM_SelectNewOption<T>[] = [];
+
+  constructor(set: Partial<DyFM_MultiselectFieldNew_Settings<T>>) {
+    super(set);
+    const { type: _ignoredType, ...rest } = set;
+    Object.assign(this, rest);
+    if (!this.options) {
+      this.options = [];
+    }
+  }
+}

package/src/_modules/ngx-models/_models/control-models/forms-new/number-field-new-settings.control-model.ts

@@ -0,0 +1,24 @@
+import { DyFM_Field_Type } from '../../../_enums/field-type.enum';
+import { DyFM_FieldNew_Settings } from './field-new-settings.control-model';
+
+/**
+ * Forms v2 (Wave-1A) — number field settings.
+ *
+ * @see _specifications/forms-v2/02-architecture-spec.md (2.2)
+ */
+export class DyFM_NumberFieldNew_Settings extends DyFM_FieldNew_Settings<number> {
+  override readonly type: DyFM_Field_Type.number = DyFM_Field_Type.number;
+
+  /** Minimum érték (inclusive). */
+  min?: number;
+  /** Maximum érték (inclusive). */
+  max?: number;
+  /** Lépés-méret (HTML `step` attribútum). */
+  step?: number;
+
+  constructor(set: Partial<DyFM_NumberFieldNew_Settings>) {
+    super(set);
+    const { type: _ignoredType, ...rest } = set;
+    Object.assign(this, rest);
+  }
+}

package/src/_modules/ngx-models/_models/control-models/forms-new/select-field-new-settings.control-model.ts

@@ -0,0 +1,46 @@
+import { DyFM_Field_Type } from '../../../_enums/field-type.enum';
+import { DyFM_FieldNew_Settings } from './field-new-settings.control-model';
+
+/**
+ * Forms v2 (Wave-1A) — select option shape (label/value pár).
+ *
+ * POJO — szerver-importálható. A `compareWith` függvény NEM itt él, hanem a Params
+ * runtime-options-jában (lásd 02-spec section 5.2).
+ */
+export interface DyFM_SelectNewOption<T> {
+  label: string;
+  value: T;
+  /** Opcionális per-option disabled flag. */
+  disabled?: boolean;
+  /** Opcionális leírás (pl. tooltip a chip vagy dropdown alatt). */
+  description?: string;
+}
+
+/**
+ * Forms v2 (Wave-1A) — single select field settings.
+ *
+ * Multi-select: `DyFM_MultiselectFieldNew_Settings` (külön osztály).
+ *
+ * @see _specifications/forms-v2/02-architecture-spec.md (2.2)
+ */
+export class DyFM_SelectFieldNew_Settings<T = string> extends DyFM_FieldNew_Settings<T> {
+  override readonly type: DyFM_Field_Type.select = DyFM_Field_Type.select;
+
+  /** Választási opciók listája. */
+  options: DyFM_SelectNewOption<T>[] = [];
+
+  /**
+   * Opcionális null-option (üres-választás) — ha string, label-ként renderelődik.
+   * Ha `false` (vagy hiányzik), nincs null-option.
+   */
+  nullOptionLabel?: string;
+
+  constructor(set: Partial<DyFM_SelectFieldNew_Settings<T>>) {
+    super(set);
+    const { type: _ignoredType, ...rest } = set;
+    Object.assign(this, rest);
+    if (!this.options) {
+      this.options = [];
+    }
+  }
+}

package/src/_modules/ngx-models/_models/control-models/forms-new/text-field-new-settings.control-model.ts

@@ -0,0 +1,30 @@
+import { DyFM_Field_Type } from '../../../_enums/field-type.enum';
+import { DyFM_FieldNew_Settings } from './field-new-settings.control-model';
+
+/**
+ * Forms v2 (Wave-1A) — text input field settings.
+ *
+ * Egysoros text. Multi-line szöveghez `DyFM_TextAreaFieldNew_Settings` van.
+ *
+ * @see _specifications/forms-v2/02-architecture-spec.md (2.2)
+ */
+export class DyFM_TextFieldNew_Settings extends DyFM_FieldNew_Settings<string> {
+  override readonly type: DyFM_Field_Type.text = DyFM_Field_Type.text;
+
+  /** Beviteli maszk (pl. `'(00) 000-0000'`). Render-réteg konzumálja. */
+  mask?: string;
+  /** Input prefix-string (pl. `'$'`). */
+  prefix?: string;
+  /** Input suffix-string (pl. `'kg'`). */
+  suffix?: string;
+  /** Karakter-korlát. */
+  maxLength?: number;
+
+  constructor(set: Partial<DyFM_TextFieldNew_Settings>) {
+    super(set);
+    // A `type` mezőt kiszűrjük a Partial-ból, mert a readonly-osztály-mezőt JS-szinten
+    // Object.assign felülírhatná (lásd 05-deep-review C.9).
+    const { type: _ignoredType, ...rest } = set;
+    Object.assign(this, rest);
+  }
+}

package/src/_modules/ngx-models/_models/control-models/forms-new/textarea-field-new-settings.control-model.ts

@@ -0,0 +1,22 @@
+import { DyFM_Field_Type } from '../../../_enums/field-type.enum';
+import { DyFM_FieldNew_Settings } from './field-new-settings.control-model';
+
+/**
+ * Forms v2 (Wave-1A) — textarea (multi-line text) field settings.
+ *
+ * @see _specifications/forms-v2/02-architecture-spec.md (2.2)
+ */
+export class DyFM_TextAreaFieldNew_Settings extends DyFM_FieldNew_Settings<string> {
+  override readonly type: DyFM_Field_Type.textarea = DyFM_Field_Type.textarea;
+
+  /** Sor-szám hint (default 3). */
+  rows?: number;
+  /** Karakter-korlát. */
+  maxLength?: number;
+
+  constructor(set: Partial<DyFM_TextAreaFieldNew_Settings>) {
+    super(set);
+    const { type: _ignoredType, ...rest } = set;
+    Object.assign(this, rest);
+  }
+}

package/src/_modules/ngx-models/_models/control-models/frames/frames-pojo.spec.ts

@@ -0,0 +1,108 @@
+import { DyFM_HeaderItem_Type } from '../../../_enums/frames/header-item-type.enum';
+import { DyFM_Header_Position } from '../../../_enums/frames/header-position.enum';
+import { DyFM_SideNavBadge_Color } from '../../../_enums/frames/side-nav-badge-color.enum';
+import { DyFM_HeaderItem_Settings } from './header-item-settings.control-model';
+import { DyFM_MainFrame_Settings } from './main-frame-settings.control-model';
+import { DyFM_SideNavItem_Settings } from './side-nav-item-settings.control-model';
+import { DyFM_SideNav_Settings } from './side-nav-settings.control-model';
+
+describe('CCAP-mirror Wave-1a — Frames POJO', () => {
+
+  describe('DyFM_HeaderItem_Settings', () => {
+    it('| throws if `id` missing', () => {
+      expect(() => new DyFM_HeaderItem_Settings({ type: DyFM_HeaderItem_Type.logo }))
+        .toThrowError(/`id` is required/);
+    });
+
+    it('| throws if `type` missing', () => {
+      expect(() => new DyFM_HeaderItem_Settings({ id: 'logo' } as Partial<DyFM_HeaderItem_Settings>))
+        .toThrowError(/`type` is required/);
+    });
+
+    it('| accepts a Signal-like callable on `signal`', () => {
+      let count = 5;
+      const item = new DyFM_HeaderItem_Settings({
+        id: 'errBadge',
+        type: DyFM_HeaderItem_Type.badgeIndicator,
+        position: DyFM_Header_Position.right,
+        signal: (): number => count,
+      });
+      expect(item.signal!()).toBe(5);
+      count = 7;
+      expect(item.signal!()).toBe(7);
+    });
+  });
+
+  describe('DyFM_MainFrame_Settings', () => {
+    it('| throws if `headerItems` missing', () => {
+      expect(() => new DyFM_MainFrame_Settings()).toThrowError(/`headerItems` is required/);
+    });
+
+    it('| accepts empty headerItems array', () => {
+      const f = new DyFM_MainFrame_Settings({ headerItems: [] });
+      expect(f.headerItems).toEqual([]);
+    });
+
+    it('| accepts header item list with defaults', () => {
+      const f = new DyFM_MainFrame_Settings({
+        headerItems: [
+          new DyFM_HeaderItem_Settings({ id: 'logo', type: DyFM_HeaderItem_Type.logo }),
+        ],
+        headerHeightPx: 44,
+        sideNavWidthPx: 256,
+        sideNavCollapsible: true,
+      });
+      expect(f.headerItems.length).toBe(1);
+      expect(f.headerHeightPx).toBe(44);
+    });
+  });
+
+  describe('DyFM_SideNavItem_Settings', () => {
+    it('| throws if `id` missing', () => {
+      expect(() => new DyFM_SideNavItem_Settings({ label: 'Home' })).toThrowError(/`id` is required/);
+    });
+
+    it('| throws if `label` missing', () => {
+      expect(() => new DyFM_SideNavItem_Settings({ id: 'home' })).toThrowError(/`label` is required/);
+    });
+
+    it('| accepts a Signal-like callable on `badgeSignal`', () => {
+      let count = 0;
+      const item = new DyFM_SideNavItem_Settings({
+        id: 'errors',
+        label: 'Errors',
+        routerLink: '/errors',
+        badgeSignal: (): number => count,
+        badgeColor: DyFM_SideNavBadge_Color.red,
+      });
+      expect(item.badgeSignal!()).toBe(0);
+      count = 3;
+      expect(item.badgeSignal!()).toBe(3);
+      expect(item.badgeColor).toBe(DyFM_SideNavBadge_Color.red);
+    });
+
+    it('| supports nested childItems', () => {
+      const parent = new DyFM_SideNavItem_Settings({
+        id: 'settings',
+        label: 'Settings',
+        childItems: [
+          new DyFM_SideNavItem_Settings({ id: 'profile', label: 'Profile' }),
+          new DyFM_SideNavItem_Settings({ id: 'security', label: 'Security' }),
+        ],
+      });
+      expect(parent.childItems!.length).toBe(2);
+      expect(parent.childItems![0].id).toBe('profile');
+    });
+  });
+
+  describe('DyFM_SideNav_Settings', () => {
+    it('| throws if `items` missing', () => {
+      expect(() => new DyFM_SideNav_Settings()).toThrowError(/`items` is required/);
+    });
+
+    it('| accepts empty items array', () => {
+      const s = new DyFM_SideNav_Settings({ items: [] });
+      expect(s.items).toEqual([]);
+    });
+  });
+});

package/src/_modules/ngx-models/_models/control-models/frames/header-item-settings.control-model.ts

@@ -0,0 +1,52 @@
+import { DyFM_HeaderItem_Type } from '../../../_enums/frames/header-item-type.enum';
+import { DyFM_Header_Position } from '../../../_enums/frames/header-position.enum';
+
+/**
+ * CCAP-mirror Wave-1a — Frame header item POJO (Q9 paraméterezett).
+ *
+ * A `DyFM_MainFrame_Settings.headerItems[]` lista eleme. Per-type külön renderer-
+ * blokk a `DyNX_FrameHeader_Component` template-jében.
+ *
+ * Function-handler (onClick) NEM ezen — runtimeOptions-ben (per Forms v2 minta).
+ *
+ * @see _specifications/ccap-mirror/02-architecture-spec.md (L szakasz)
+ */
+export class DyFM_HeaderItem_Settings {
+  /** Egyedi id (kulcs a runtimeOptions function-mapping-hez). */
+  id!: string;
+
+  /** Item kind discriminator (logo, icon, text, badge-indicator, spacer, custom). */
+  type!: DyFM_HeaderItem_Type;
+
+  /** Megjelenítendő szöveg (`text`, `badge-indicator` esetén). */
+  label?: string;
+
+  /** Material-symbols icon-name (`icon`, `badge-indicator` esetén). */
+  iconName?: string;
+
+  /** Layout pozíció (left/center/right). Default: left. */
+  position?: DyFM_Header_Position;
+
+  /** Router-link (ha clickable). */
+  href?: string;
+
+  /**
+   * Q11-minta: consumer bind-olt Signal-jét veszi át (`badge-indicator` esetén
+   * a count vagy boolean visible-state). A Signal callable interface-szerű
+   * (`() => number | boolean`), így NEM kötődik az @angular/core-ra.
+   */
+  signal?: () => number | boolean;
+
+  /** `data-testid`. */
+  testId?: string;
+
+  constructor(set: Partial<DyFM_HeaderItem_Settings> = {}) {
+    if (!set.id) {
+      throw new Error('DyFM_HeaderItem_Settings: `id` is required');
+    }
+    if (!set.type) {
+      throw new Error('DyFM_HeaderItem_Settings: `type` is required');
+    }
+    Object.assign(this, set);
+  }
+}