@xiriframework/xiri-ng 0.2.26 → 0.2.28

package/skills/xiri-ng-expert/references/dyncomponent.md

@@ -0,0 +1,130 @@
+# xiri-dyncomponent — JSON-Renderer
+
+Die `xiri-dyncomponent` ist der Kern des JSON-Driven-UI Patterns: ein Array von `XiriDynData`-Objekten wird zu einer Kette von xiri-Komponenten gerendert.
+
+## Selector
+
+`xiri-dyncomponent`
+
+## Inputs
+
+```typescript
+@input.required data: XiriDynData[];
+@input          filterData: any = undefined;
+@input          dyncomponent: TemplateRef<any> = undefined;
+  // Optional: TemplateRef für Custom-Rendering (type: 'custom' oder unbekannter type).
+```
+
+## Outputs
+
+Keine.
+
+## XiriDynData Interface
+
+```typescript
+export interface XiriDynData {
+  id?: number;                            // Wird auto-generiert wenn fehlt.
+  type: XiriDynDataType | (string & {});  // Komponenten-Typ.
+  data?: any;                             // Settings-Objekt der Ziel-Komponente.
+  display?: string;                       // CSS-Klassen für Wrapper.
+  newRow?: boolean;                       // Grid-Layout: neue Zeile beginnen.
+  mode?: string;                          // Nur für 'barchart': 'simple' | 'stacked' | 'heatmap'
+}
+
+export type XiriDynDataType =
+  | 'card' | 'buttonline' | 'table' | 'cardlink' | 'links'
+  | 'form' | 'query' | 'stepper' | 'header' | 'list'
+  | 'spacer' | 'container'
+  | 'infopoint' | 'multiprogress' | 'imagetext'
+  | 'tabs' | 'expansion' | 'infotext' | 'html'
+  | 'stat' | 'empty-state' | 'timeline'
+  | 'page-header' | 'section' | 'divider'
+  | 'stat-grid' | 'toolbar' | 'description-list'
+  | 'barchart' | 'linechart' | 'piechart' | 'gaugechart'
+  | 'heatmap' | 'calendar' | 'tree' | 'sankey' | 'gantt';
+```
+
+## Mapping type → Komponente
+
+| `type`              | Rendered Component     | `data` = Settings-Interface          |
+| ------------------- | ---------------------- | ------------------------------------ |
+| `card`              | `xiri-card`            | `XiriCardSettings`                   |
+| `buttonline`        | `xiri-buttonline`      | `XiriButtonlineSettings`             |
+| `table`             | `xiri-table`           | `XiriTableSettings`                  |
+| `cardlink`          | `xiri-cardlink`        | `XiriCardlinkSettings`               |
+| `links`             | `xiri-links`           | `XiriLinksSettings`                  |
+| `form`              | `xiri-form`            | `XiriFormSettings`                   |
+| `query`             | `xiri-query`           | `XiriQuerySettings`                  |
+| `stepper`           | `xiri-stepper`         | `XiriStepperSettings`                |
+| `header`            | `xiri-header`          | `XiriHeaderSettings`                 |
+| `list`              | `xiri-list`            | `XiriListSettings`                   |
+| `infopoint`         | `xiri-infopoint`       | `XiriInfopointSettings`              |
+| `multiprogress`     | `xiri-multiprogress`   | `XiriMultiprogressSettings`          |
+| `imagetext`         | `xiri-imagetext`       | `XiriImagetextSettings`              |
+| `tabs`              | `xiri-tabs`            | `XiriTabsSettings`                   |
+| `expansion`         | `xiri-expansion`       | `XiriExpansionSettings`              |
+| `stat`              | `xiri-stat`            | `XiriStatSettings`                   |
+| `empty-state`       | `xiri-empty-state`     | `XiriEmptyStateSettings`             |
+| `timeline`          | `xiri-timeline`        | `XiriTimelineSettings`               |
+| `page-header`       | `xiri-page-header`     | `XiriPageHeaderSettings`             |
+| `section`           | `xiri-section`         | `XiriSectionSettings` (rekursiv!)    |
+| `divider`           | `xiri-divider`         | `XiriDividerSettings`                |
+| `stat-grid`         | `xiri-stat-grid`       | `XiriStatGridSettings`               |
+| `toolbar`           | `xiri-toolbar`         | `XiriToolbarSettings`                |
+| `description-list`  | `xiri-description-list`| `XiriDescriptionListSettings`        |
+| `barchart`          | `xiri-barchart`        | `XiriBarChartSettings` (+ `mode` auf XiriDynData) |
+| `linechart`         | `xiri-linechart`       | `XiriLineChartSettings`              |
+| `piechart`          | `xiri-piechart`        | `XiriPieChartSettings`               |
+| `gaugechart`        | `xiri-gaugechart`      | `XiriGaugeChartSettings`             |
+| `heatmap`           | `xiri-heatmap`         | `XiriHeatmapSettings`                |
+| `calendar`          | `xiri-calendar`        | `XiriCalendarSettings`               |
+| `tree`              | `xiri-tree`            | `XiriTreeSettings`                   |
+| `sankey`            | `xiri-sankey`          | `XiriSankeySettings`                 |
+| `gantt`             | `xiri-gantt`           | `XiriGanttSettings`                  |
+| `spacer`            | vertical spacer div    | `{ size?: string }`                  |
+| `container`         | wrapper div            | `{ components: XiriDynData[] }`      |
+| `infotext`          | Text-Absatz            | `{ text: string }`                   |
+| `html`              | innerHTML (SafeHtml)   | `{ html: string }`                   |
+
+## Custom-Rendering via TemplateRef
+
+Für Typen außerhalb der Liste: übergib einen `dyncomponent` TemplateRef als Fallback.
+
+```html
+<xiri-dyncomponent [data]="components" [dyncomponent]="customTpl"/>
+
+<ng-template #customTpl let-item>
+  <app-my-custom-widget [data]="item.data"/>
+</ng-template>
+```
+
+Der TemplateRef erhält das gesamte `XiriDynData`-Item als Context (`$implicit`).
+
+## Verschachtelung
+
+`section`, `tabs`, `expansion` und `container` akzeptieren in ihren `data`-Feldern wieder `XiriDynData[]` (rekursiv) — die `xiri-dyncomponent` rendert alle Ebenen durch.
+
+```typescript
+const page: XiriDynData[] = [
+  { type: 'page-header', data: { title: 'Dashboard' } },
+  { type: 'stat-grid',   data: { stats: [...], columns: 4 } },
+  { type: 'section', data: {
+      title: 'Details',
+      collapsible: true,
+      components: [
+        { type: 'table', data: { url: '/api/items' } },
+        { type: 'divider', data: {} },
+        { type: 'infopoint', data: { text: 'Hinweis', icon: 'info' } },
+      ],
+  }},
+];
+```
+
+## filterData — Weitergabe an Tabellen und Buttons
+
+`filterData` wird automatisch an alle `xiri-table`-, `xiri-buttonline`- und `xiri-toolbar`-Kinder weitergereicht. Das ist wichtig, wenn ein `xiri-query` Filter-Werte setzt, die Tabellen oder API-Buttons konsumieren sollen.
+
+```html
+<xiri-query [settings]="qs" (change)="filter = $event"></xiri-query>
+<xiri-dyncomponent [data]="results" [filterData]="filter"/>
+```

package/skills/xiri-ng-expert/references/form-fields.md

@@ -0,0 +1,282 @@
+# Form-Fields — xiri-ng Reference
+
+## XiriFormFieldsComponent
+
+Renderer für `XiriFormField[]`. Baut intern eine `UntypedFormGroup` mit Reactive Validators, handhabt `showWhen`, collapsible Headers und alle 19 Feldtypen.
+
+### Selector
+
+`xiri-form-fields`
+
+### Inputs
+
+```typescript
+@input form: XiriFormField[] | null = null
+@input display: XiriFormFieldDisplay = 'full'       // 'full' | 'line' | 'small'
+@input disabled: boolean = false
+@input check: Observable<void> = null                // Trigger für Revalidierung
+```
+
+### Outputs
+
+```typescript
+@output formChange: EventEmitter<any>
+  // Emittet die UntypedFormGroup (nicht nur values) bei Änderungen.
+```
+
+### Öffentliche API
+
+```typescript
+formGroup: UntypedFormGroup                       // Reactive Form
+
+isFieldVisible(field: XiriFormField): boolean
+toggleSection(header: XiriFormField): void
+isSectionCollapsed(headerId: string): boolean
+```
+
+### Zugriff auf Werte und Validität
+
+```typescript
+@ViewChild(XiriFormFieldsComponent) fieldsCmp!: XiriFormFieldsComponent;
+
+submit() {
+  if (this.fieldsCmp.formGroup.invalid) {
+    this.fieldsCmp.formGroup.markAllAsTouched();
+    return;
+  }
+  const payload = this.fieldsCmp.formGroup.value;
+  this.data.post('/api/save', payload)
+    .subscribe(res => this.responseHandler.handle(res));
+}
+```
+
+## XiriFormField Interface
+
+```typescript
+export interface XiriFormField {
+  // --- Basis ---
+  id: string;
+  type: string;               // siehe Liste unten
+  subtype?: string;           // z.B. 'email' subtype von 'text'
+  formtype?: string;          // Alt-Weg, gleich wie type
+
+  // --- Label & Display ---
+  name?: string;              // Label
+  hint?: string;
+  class?: string;
+  textPrefix?: string;
+  textSuffix?: string;
+  iconPrefix?: string;
+  iconSuffix?: string;
+  locale?: string;
+  placeholder?: string;       // v.a. für bool / header
+
+  // --- Wert & Validierung ---
+  value?: any;
+  validations?: XiriFormValidator[];
+  list?: XiriFormFieldSelectOption[];   // für select/treeselect
+  texts?: object;                        // für timelimit
+
+  // --- State ---
+  hide?: boolean;
+  required?: boolean;
+  disabled?: boolean;
+  collapsible?: boolean;     // header
+  collapsed?: boolean;       // header initial
+
+  // --- Constraints ---
+  min?: number;              // number | date | array-length
+  max?: number;
+  pattern?: string;          // regex
+
+  // --- Select / Model / Treeselect ---
+  multiple?: boolean;
+  url?: string;              // load options von Backend
+  search?: boolean;
+  serverSideSearch?: boolean;
+  params?: object;
+
+  // --- File ---
+  accept?: string;
+  pwdhide?: boolean;         // password
+
+  // --- Question / Waiting ---
+  icon?: string;
+  iconColor?: XiriColor;
+  done?: boolean;
+
+  // --- Conditional Display ---
+  showWhen?: XiriFormFieldCondition | XiriFormFieldCondition[];
+
+  // --- Weitere ---
+  rows?: number;             // textarea
+  array?: any[];             // alt zu list
+  tree?: boolean;
+  control?: FormControl;     // Internal
+}
+```
+
+### Feld-Typen
+
+| `type`          | Rendered als                                      | Wichtige Properties                |
+| --------------- | ------------------------------------------------- | ---------------------------------- |
+| `text`          | Mat-Input                                         | `subtype` (email/url), `pattern`   |
+| `email`         | Mat-Input type=email                              |                                    |
+| `password`      | Mat-Input type=password                           | `pwdhide`                          |
+| `textarea`      | Mat-Textarea                                      | `rows`                             |
+| `number`        | Mat-Input type=number                             | `min`, `max`, `textSuffix`         |
+| `bool`          | Mat-Checkbox / Slide-Toggle                       | `placeholder` für Begleittext      |
+| `select`        | Mat-Select mit `list`                             | `multiple`, `search`               |
+| `multiselect`   | Mat-Select mit `multiple: true`                   | `list` oder `url`                  |
+| `model`         | Mat-Select mit Backend-Load                       | `url`, `serverSideSearch`          |
+| `object`        | Komplexes Objekt-Select (JSON-Value)              | `url`, `list`                      |
+| `treeselect`    | Tree-Picker                                       | `url`, `tree: true`                |
+| `date`          | Mat-Datepicker (Unix-Timestamp)                   | `min`, `max`                       |
+| `datetime`      | Date + Time Picker                                | `min`, `max`                       |
+| `daterange`     | Start- + End-Date                                 | `min`, `max`                       |
+| `datetimerange` | Start- + End-DateTime                             |                                    |
+| `yearmonth`     | Monats-Picker (Multi-Year-View, MM.yyyy)          | `min`, `max` (Unix), `required`    |
+| `file`          | File-Upload Button                                | `accept`                           |
+| `volume`        | Volume-Slider (mit Einheit via `textSuffix`)      | `min`, `max`                       |
+| `timelimit`     | Time-Limit Auswahl                                | `texts` (Label-Overrides)          |
+| `chips`         | Mat-Chip-List                                     | `list`, `validations`              |
+| `question`      | Read-Only Frage + Icon (z.B. Confirmation-Dialog) | `icon`, `iconColor`, `done`        |
+| `waiting`       | Loading-Spinner                                   |                                    |
+| `header`        | Sektions-Header (mit optional Collapse)           | `collapsible`, `collapsed`         |
+
+#### `yearmonth` — Monats-Auswahl
+
+Render: eigener `<xiri-yearmonth>`, intern Mat-Datepicker mit `startView="multi-year"`.
+Value wird auf den **1. des Monats 00:00 (lokal)** normalisiert und als Unix-Timestamp
+(Sekunden) zurückgegeben. Anzeige-Format `MM.yyyy`, Picker-Labels `MMM yyyy` /
+`MMMM yyyy`. Default `required: true`, wenn nicht explizit gesetzt.
+
+```typescript
+{ id: 'period', type: 'yearmonth', name: 'Berichtsmonat',
+  required: true,
+  min: <unixSeconds>,   // optional, untere Schranke
+  max: <unixSeconds>    // optional, obere Schranke
+}
+```
+
+Backend-Pendant: `field.NewYearMonthField(...)` (siehe xiri-go-expert).
+
+### showWhen — Conditional Visibility
+
+```typescript
+export interface XiriFormFieldCondition {
+  field: string;
+  operator: 'equals' | 'notEquals' | 'contains'
+          | 'greaterThan' | 'lessThan' | 'in' | 'notEmpty';
+  value?: any;
+}
+```
+
+Einzelne Bedingung:
+
+```typescript
+{ id: 'reason', type: 'text', name: 'Grund',
+  showWhen: { field: 'active', operator: 'equals', value: false } }
+```
+
+Array = **UND**-Verknüpfung:
+
+```typescript
+{ id: 'priorityNote', type: 'textarea', name: 'Prio-Notiz',
+  showWhen: [
+    { field: 'priority', operator: 'in', value: ['high', 'critical'] },
+    { field: 'note',     operator: 'notEmpty' },
+  ]}
+```
+
+### Select-Optionen
+
+```typescript
+export interface XiriFormFieldSelectOption {
+  id: number;
+  name: string;
+  disabled?: boolean;
+  color?: XiriColor;
+}
+```
+
+Inline (statisch):
+
+```typescript
+{ id: 'status', type: 'select', name: 'Status',
+  list: [
+    { id: 1, name: 'Aktiv',    color: 'success' },
+    { id: 2, name: 'Inaktiv',  color: 'warn' },
+    { id: 3, name: 'Gesperrt', color: 'error', disabled: true },
+  ]}
+```
+
+Per Backend (`model` oder `select` mit `url`):
+
+```typescript
+{ id: 'group', type: 'model', name: 'Gruppe',
+  url: '/api/groups/options',
+  serverSideSearch: true,
+  params: { tenant: 42 } }
+```
+
+Das Backend liefert `XiriFormFieldSelectOption[]` zurück.
+
+## XiriFormValidator
+
+```typescript
+export interface XiriFormValidator {
+  type: 'required' | 'minlength' | 'maxlength' | 'pattern' |
+        'min' | 'max' | 'email' | ...;
+  value?: any;
+  message?: string;
+}
+```
+
+Beispiel:
+
+```typescript
+{ id: 'pwd', type: 'password', name: 'Passwort',
+  validations: [
+    { type: 'required' },
+    { type: 'minlength', value: 8, message: 'Mind. 8 Zeichen' },
+    { type: 'pattern',   value: '.*[0-9].*', message: '≥1 Zahl' },
+  ]}
+```
+
+## XiriSelectDirective
+
+Interne Directive für Mat-Select mit Client- oder Server-side-Search. Wird normalerweise nicht direkt verwendet — `XiriFormFieldsComponent` setzt sie automatisch für `select`, `multiselect`, `model`, `object`.
+
+### Selector
+
+`[xiriSelect]` auf `<mat-select>`
+
+### Inputs (mit Alias)
+
+```typescript
+@input({ alias: 'values' })
+  values: XiriFormFieldSelectOption[] = [];
+
+@input({ alias: 'serverSideSearch' })
+  serverSideSearch: boolean = false;
+
+@input({ alias: 'serverUrl' })
+  serverUrl: string = '';
+
+@input({ alias: 'serverParams' })
+  serverParams: any = {};
+
+@input({ alias: 'predicate' })
+  predicate: XiriSelectPredicate = DEFAULT_PREDICATE;   // (option, term) => boolean
+
+@input({ alias: 'compare' })
+  compare: XiriSelectCompare = DEFAULT_COMPARE;          // (a, b) => boolean
+```
+
+### API
+
+```typescript
+get formControl(): UntypedFormControl;
+get filter(): Observable<XiriFormFieldSelectOption[]>;
+```

package/skills/xiri-ng-expert/references/setup.md

@@ -0,0 +1,177 @@
+# Setup & Services — xiri-ng Reference
+
+## provideXiriServices
+
+```typescript
+import { provideXiriServices } from '@xiriframework/xiri-ng';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(),
+    provideXiriServices({ api: '/api/' }),
+  ],
+};
+```
+
+Signatur:
+
+```typescript
+function provideXiriServices(config: Partial<XiriDataServiceConfig>): EnvironmentProviders
+
+class XiriDataServiceConfig {
+  api: string = '/api/';
+}
+```
+
+Alle xiri-Services sind `providedIn: 'root'` — kein manuelles Registrieren nötig.
+
+## XiriDataService
+
+HTTP-Client mit automatischer Snackbar-Integration (parst `response.message` + `response.messageType`).
+
+```typescript
+get(url: string): Observable<Object>
+post(url: string, data: any): Observable<any>
+
+postFile(url: string, data: any): Observable<any>
+  // responseType: 'blob' — gibt rohes Blob zurück
+
+postFileResponse(url: string, data: any): Observable<HttpResponse<Blob>>
+  // mit Headern (für Filename aus Content-Disposition) — nutze mit XiriDownloadService
+
+getConfigApi(): string
+  // aktuelle Base-URL (z.B. '/api/')
+
+postDownload(url: string, data: any): void
+  // DEPRECATED — nutze postFileResponse() + XiriDownloadService.download()
+```
+
+URLs werden mit `getConfigApi()` prefixed, wenn sie nicht absolut sind.
+
+## XiriSnackbarService
+
+```typescript
+success(message: string, duration?: number, action?: string): MatSnackBarRef
+error  (message: string, duration?: number, action?: string): MatSnackBarRef
+info   (message: string, duration?: number, action?: string): MatSnackBarRef
+warning(message: string, duration?: number, action?: string): MatSnackBarRef
+
+handleResponse(response: any): boolean
+  // Gibt true zurück wenn response.message existiert und gezeigt wurde.
+  // messageType mapt auf success | error | warning | info.
+```
+
+Wird von `XiriDataService` intern aufgerufen — du musst `handleResponse` nur selber aufrufen, wenn du die Response manuell behandelst.
+
+## XiriResponseHandlerService
+
+Zentrale Logik für Backend-Responses aus `xiri-go` (`ReturnGoto`, `ReturnRefreshPage`, `ReturnRefreshTable`, `ReturnUpdateTableField`).
+
+```typescript
+handle(result: any, callbacks?: {
+  onTableRefresh?: () => void;
+  onTableUpdate?: (id: any, field: string, content: any) => void;
+}): void
+```
+
+Verhalten je nach `result.refreshType` / `result.gotoUrl`:
+- Navigation → `Router.navigateByUrl`
+- Page-Refresh → `window.location.reload()`
+- Table-Refresh → ruft `onTableRefresh()` wenn gesetzt
+- Table-Update → ruft `onTableUpdate(id, field, content)` wenn gesetzt
+
+## XiriFormService
+
+Orchestriert Form-Fetch/Submit mit State-Persistierung.
+
+```typescript
+get(url: string, data?: any, extra?: any): Observable<XiriFormServiceData>
+  // GET wenn data === null, sonst POST. Gibt geparste FormServiceData zurück.
+
+parse(res: XiriFormServiceReturn): XiriFormServiceData
+  // Parst rohe Backend-Response (type: 'form' | 'question' | 'waiting').
+
+loadState(saveStateId: string | null | undefined,
+          fields: XiriFormField[]): XiriFormField[]
+  // Merged persistierte Values in die Fields (SessionStorage, 3600s Timeout).
+
+saveState(saveStateId: string | null | undefined, values: any): void
+  // Persistiert in SessionStorage.
+```
+
+## XiriThemeService (ThemeService)
+
+Signal-basiert, System-Präferenz-aware.
+
+```typescript
+readonly mode: Signal<ThemeMode>     // 'light' | 'dark' | 'auto'
+readonly isDark: Signal<boolean>     // computed
+readonly isLight: Signal<boolean>    // computed
+
+setTheme(mode: ThemeMode): void      // persistiert in localStorage
+toggle(): void                       // wechselt zwischen light/dark
+resetToAuto(): void                  // auto = folgt OS
+```
+
+Beispiel in einer Komponente:
+
+```typescript
+private theme = inject(ThemeService);
+
+toggleTheme() { this.theme.toggle(); }
+darkMode = computed(() => this.theme.isDark());
+```
+
+## XiriDownloadService
+
+```typescript
+download(result: HttpResponse<Blob>, filename: string, openInNewTab: boolean): boolean
+  // Erstellt blob-URL, triggert Download oder öffnet Tab. True bei Erfolg.
+```
+
+Kombination mit `XiriDataService.postFileResponse`:
+
+```typescript
+this.data.postFileResponse('/api/export', payload).subscribe(res => {
+  this.download.download(res, 'export.xlsx', false);
+});
+```
+
+## XiriDateService
+
+Unix-Timestamp ↔ lokale Datums-Strings mit Timezone + Locale.
+
+```typescript
+setTimezone(tz: string): void
+setLocale(localeString: string, locale: Locale): void   // date-fns Locale
+
+unixToLocal(stime: number): Date | null
+unixToStringDateTime(stime: number): string   // 'yyyy-MM-dd HH:mm'
+unixToStringDate(stime: number): string       // 'd. LLL.'
+unixToStringDateYear(stime: number): string   // 'd. LLL. yy'
+dateToUnix(date: Date): number
+```
+
+Der Backend-`UiContext` schickt Locale/Timezone als Teil der JSON-Responses → Kalibrierung via `setLocale` / `setTimezone` erfolgt typischerweise in einem Auth-/Startup-Flow.
+
+## XiriNumberService
+
+```typescript
+setLocale(locale: string): void   // Default: 'de-DE'
+formatNumber(value: number, webformat?: string): string
+  // webformat: 'integer' | 'float1' | 'float2' | 'float3' | 'float4'
+```
+
+## XiriLocalStorageService / XiriSessionStorageService
+
+Wrapper mit Timestamp-Metadaten und In-Memory-Fallback (falls localStorage blockiert).
+
+```typescript
+set(name: string, value: any): void              // speichert mit Timestamp
+get(name: string): any                            // value oder null
+getTimeout(name: string, maxSeconds: number): any // null wenn älter als maxSeconds
+remove(name: string): void
+clear(): void
+```
+
+`XiriSessionStorageService` hat dieselbe API, wird v.a. für Form-State und Table-State genutzt (`saveState: true` in Table/Query).