@xiriframework/xiri-ng 0.2.26 → 0.2.27

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

@@ -0,0 +1,277 @@
+# Tables — xiri-ng Reference
+
+Zwei Komponenten: `xiri-raw-table` (minimal) und `xiri-table` (voll — Paging, Sort, Search, Inline-Edit, Selection, Server-Side).
+
+## XiriRawTableComponent
+
+### Selector
+
+`xiri-raw-table`
+
+### Inputs
+
+```typescript
+@input.required settings: XiriRawTableSettings;
+
+export interface XiriRawTableSettings {
+  data: any[];                    // Zeilen
+  fields?: XiriTableField[];      // Spalten
+  dense?: number;                 // 6-12, CSS-Klasse 'dense-X'
+  forceMinWidth?: boolean;
+  showHeader?: boolean;           // Default false. Bei true wird die <thead>-Zeile mit
+                                  // Spalten-Headern (column.header) gerendert.
+}
+```
+
+### Outputs
+
+Keine.
+
+Kein Sorting, kein Paging, kein Editing. Nur Daten rendern.
+
+**Header-Zeile standardmäßig aus.** Aufrufer (xiri-card, xiri-dialog) setzen `showHeader` aus dem Backend-Payload (xiri-go: `*Card.WithTableHeader()` bzw. `Dialog.WithTableHeader()`).
+
+## XiriTableComponent
+
+### Selector
+
+`xiri-table`
+
+### Inputs
+
+```typescript
+@input.required settings: XiriTableSettings;
+@input          filterData: any = undefined;
+@input          dyncomponent: TemplateRef<any> = undefined;   // Custom-Cell-Rendering
+```
+
+### Outputs
+
+```typescript
+@output clickedRow: EventEmitter<any>;   // volles Row-Object
+```
+
+### Öffentliche Methoden
+
+```typescript
+reload(): void
+searchDo(text: string): void
+selection: SelectionModel<any>         // Checkbox-Selection (wenn options.select)
+isAllSelected(): boolean
+masterToggle(): void
+
+// Inline-Edit
+startInlineEdit(row: any, column: XiriTableField, skipSavingCheck?: boolean): void
+cancelInlineEdit(): void
+saveInlineEdit(row: any, column: XiriTableField): void
+isEditing(row: any, fieldId: string): boolean
+isSaving(row: any, fieldId: string): boolean
+```
+
+### XiriTableSettings
+
+```typescript
+export interface XiriTableSettings {
+  url?: string;                       // API-Endpoint (POST mit filterData-payload)
+  data?: any[];                       // Alternative zu url — statische Daten
+  fields?: XiriTableField[];
+  options?: XiriTableOptions;
+  hasFilter?: boolean;                // True wenn filterData extern gesetzt
+}
+```
+
+### XiriTableOptions
+
+```typescript
+export interface XiriTableOptions {
+  reload?: boolean;
+  dense?: boolean;
+  sort?: boolean = true;
+  search?: boolean = true;
+  class?: string;
+
+  pagination?: boolean = true;
+  itemsPerPage?: number = 50;
+  pageSizes?: number[] = [10, 25, 50, 100, 500];
+
+  select?: boolean;                    // Checkbox für Row-Selection
+  selectButtons?: XiriButton[];        // Buttons die auf Selection wirken
+
+  title?: string;
+  textNoData?: string = 'no data found';
+  emptyState?: XiriTableEmptyState;
+
+  buttons?: XiriButtonlineSettings;    // Action-Buttons über der Tabelle
+
+  minWidth?: string;
+  scrollHeight?: string;
+
+  saveState?: boolean = false;         // Persist in SessionStorage
+  saveStateId?: string;
+
+  // Inline-Edit
+  saveInput?: string;
+  saveInputUrl?: string;
+  editUrl?: string;                    // POST-URL für Inline-Edit-Save
+
+  borders?: boolean;
+  bordersHeader?: boolean;
+  footer?: boolean;                    // Footer-Row mit count/sum/static
+
+  serverSide?: boolean;                // Paging/Sort/Search serverseitig
+}
+```
+
+### XiriTableField
+
+```typescript
+export interface XiriTableField {
+  id: string;
+  name: string;
+  format?: string;              // 'text' | 'number' | 'html' | 'icon' | 'button' | 'chips' | ...
+  search?: boolean;
+  sort?: boolean;
+
+  buttons?: XiriButton[];       // Action-Buttons in der Zelle
+  icons?: { icon: string; color?: string; hint?: string }[];
+
+  display?: string;             // CSS-Klasse auf <td>
+  header?: string;              // Custom Header-Text (falls ≠ name)
+  sticky?: boolean;
+
+  // Inline-Edit
+  inputType?: string;
+  inputRequired?: boolean;
+  inputLang?: string;
+  inputPaste?: boolean;
+
+  // Formatierung
+  textPrefix?: string;
+  textSuffix?: string;
+  width?: string;
+  minWidth?: string;
+
+  hide?: boolean;
+  headerSpan?: number;          // colspan für Header-Gruppen
+
+  align?: 'left' | 'center' | 'right';
+  footer?: 'no' | 'count' | 'sum' | 'static';
+  webformat?: string;           // 'integer' | 'float1'-'float4'
+
+  editable?: boolean;
+  editableOptions?: { value: string; label: string; color?: string }[];
+  editableOptionsUrl?: string;
+}
+```
+
+### Chips-Format (Status-Tags pro Zelle)
+
+`format: 'chips'` rendert pro Zelle ein Array farbiger Pills. Der Cell-Wert ist `Array<{label: string, color?: XiriColor}>`. Single-Value-Spalten liefern ein 1-elementiges Array (z. B. `[{ label: '45%', color: 'red' }]`).
+
+```typescript
+fields: [
+  { id: 'state',  name: 'State',         format: 'chips' },
+  { id: 'metric', name: 'Battery',       format: 'chips' },
+  { id: 'tags',   name: 'Tags',          format: 'chips' },
+],
+data: [
+  { id: 1,
+    state:  [ { label: 'Attention',     color: 'warn' } ],
+    metric: [ { label: '45%',           color: 'red' } ],
+    tags:   [ { label: 'Frontend', color: 'primary' },
+              { label: 'Angular',  color: 'emerald' } ] },
+]
+```
+
+CSS-Klasse pro Chip: `.xiri-chip-display.<color>` (z. B. `.xiri-chip-display.red`). Theme-Farben (`primary`/`accent`/`warn`/…) und Extended-Farben (`red`/`green`/`yellow`/`gray`/…) werden vom Theming bereitgestellt.
+
+**Editierbar (Multi-Select-Chips):** zusätzlich `editable: true` + `editableOptions` (oder `editableOptionsUrl`) auf dem Field — der Inline-Editor öffnet einen Multi-Select. Der Cell-Wert beim Edit-Save ist das Array der ausgewählten Labels.
+
+**Backend-Pendant in xiri-go:** `b.ChipsField(id, name, accessor)` wo `accessor func(T) []table.Chip` (siehe `xiri-go-expert references/table-builder.md`).
+
+## Server-Side-Pagination — Flow
+
+Wenn `options.serverSide: true`, postet die Tabelle bei jeder Änderung (Sort/Filter/Page) an `settings.url` mit Payload:
+
+```json
+{
+  "pageIndex": 0,
+  "pageSize": 50,
+  "sortBy": "name",
+  "sortDir": "asc",
+  "search": "foo",
+  "filter": { ... filterData ... }
+}
+```
+
+Erwartete Response:
+
+```typescript
+{
+  data: any[];
+  total: number;
+}
+```
+
+## Beispiel — voll konfigurierte Tabelle
+
+```typescript
+tableSettings: XiriTableSettings = {
+  url: '/api/devices',
+  options: {
+    serverSide: true,
+    pagination: true,
+    itemsPerPage: 50,
+    sort: true,
+    search: true,
+    saveState: true,
+    saveStateId: 'devices-table',
+    select: true,
+    selectButtons: [
+      { text: 'Löschen', type: 'raised', color: 'warn',
+        action: 'api', url: '/api/devices/bulk-delete' },
+    ],
+    editUrl: '/api/devices/inline-edit',
+    footer: true,
+    buttons: {
+      class: 'small',
+      buttons: [
+        { text: 'Neu', type: 'raised', color: 'primary',
+          action: 'dialog', url: '/api/devices/add' },
+      ],
+    },
+  },
+  fields: [
+    { id: 'id',     name: 'ID',     format: 'number', sticky: true, width: '80px' },
+    { id: 'name',   name: 'Name',   search: true, sort: true },
+    { id: 'status', name: 'Status', format: 'icon',
+      icons: [
+        { icon: 'check_circle', color: 'success', hint: 'Aktiv' },
+        { icon: 'cancel',       color: 'warn',    hint: 'Inaktiv' },
+      ]},
+    { id: 'count',  name: 'Anzahl', format: 'number',
+      webformat: 'integer', align: 'right', footer: 'sum' },
+    { id: 'note',   name: 'Notiz', editable: true, inputType: 'text' },
+    { id: 'actions', name: '', format: 'button',
+      buttons: [
+        { text: '', type: 'icon', icon: 'edit',
+          action: 'dialog', url: '/api/devices/edit' },
+        { text: '', type: 'icon', icon: 'delete', color: 'warn',
+          action: 'dialog', url: '/api/devices/delete' },
+      ]},
+  ],
+};
+```
+
+## Reload nach Edit
+
+```typescript
+@ViewChild(XiriTableComponent) table!: XiriTableComponent;
+
+onButtonResult(res: XiriButtonResult) {
+  this.responseHandler.handle(res.result, {
+    onTableRefresh: () => this.table.reload(),
+    onTableUpdate: (id, field, content) => { /* optimistic UI */ },
+  });
+}
+```

package/skills/xiri-ng-expert/references/theming-i18n.md

@@ -0,0 +1,120 @@
+# Theming, Colors & i18n — xiri-ng Reference
+
+## Farben
+
+```typescript
+export type XiriThemeColor =
+  | 'primary' | 'secondary' | 'tertiary' | 'accent'
+  | 'warn' | 'error' | 'success';
+
+export type XiriExtendedColor =
+  | 'emerald' | 'red' | 'yellow' | 'green' | 'blue' | 'purple'
+  | 'gray' | 'lightgray' | 'darkgray' | 'orange'
+  | 'white' | 'black' | 'inherit';
+
+export type XiriColor = XiriThemeColor | XiriExtendedColor;
+```
+
+Wird in fast allen Settings-Interfaces genutzt (`iconColor`, `color`, `headerIconColor`). Für Backend-JSON: als String serialisiert (z.B. `"primary"`, `"warn"`).
+
+## ThemeService
+
+```typescript
+import { ThemeService } from '@xiriframework/xiri-ng';
+
+private theme = inject(ThemeService);
+
+theme.mode                         // Signal<'light' | 'dark' | 'auto'>
+theme.isDark                       // computed Signal<boolean>
+theme.isLight                      // computed Signal<boolean>
+
+theme.setTheme('dark' | 'light' | 'auto');   // persistiert in localStorage
+theme.toggle();                               // light ↔ dark
+theme.resetToAuto();                          // folgt System-Präferenz
+```
+
+Typischer Toolbar-Toggle:
+
+```typescript
+@Component({ ... })
+export class HeaderComponent {
+  private theme = inject(ThemeService);
+  isDark = this.theme.isDark;
+  toggle() { this.theme.toggle(); }
+}
+```
+
+## Material-Design-3 Theming
+
+xiri-ng setzt auf Angular Material 3 mit SCSS-Theme-Konfiguration im konsumierenden Projekt. Typisches Setup:
+
+```scss
+// src/styles.scss
+@use '@angular/material' as mat;
+
+html {
+  @include mat.theme((
+    color: (
+      primary: mat.$azure-palette,
+      tertiary: mat.$blue-palette,
+    ),
+    typography: Roboto,
+    density: 0,
+  ));
+}
+
+// Dark-Mode via ThemeService's 'dark'-Klasse auf <body>
+body.dark {
+  color-scheme: dark;
+}
+```
+
+Die Komponenten nutzen `mat.*-theme` Tokens — kein Hart-kodiertes CSS.
+
+## Locale & Sprache
+
+Backend (`xiri-go`) schickt `UiContext` mit Locale/Timezone pro Response. Frontend propagiert das an `XiriDateService` und `XiriNumberService`:
+
+```typescript
+// z.B. in einem auth-response-handler:
+import { de } from 'date-fns/locale';
+
+this.date.setLocale('de-DE', de);
+this.date.setTimezone('Europe/Vienna');
+this.number.setLocale('de-DE');
+```
+
+### Date-Format-Helper
+
+```typescript
+date.unixToStringDateTime(1708800000)   // '2024-02-24 18:00'
+date.unixToStringDate(1708800000)       // '24. Feb.'
+date.unixToStringDateYear(1708800000)   // '24. Feb. 24'
+date.unixToLocal(1708800000)            // Date-Objekt oder null
+date.dateToUnix(new Date())             // number
+```
+
+### Number-Format-Helper
+
+```typescript
+number.formatNumber(1234.567, 'integer')  // '1.235'
+number.formatNumber(1234.567, 'float2')   // '1.234,57'
+number.formatNumber(1234.567, 'float4')   // '1.234,5670'
+```
+
+## SafehtmlPipe
+
+```html
+{{ htmlString | safeHtml }}
+```
+
+Nur verwenden wenn der HTML-String vertrauenswürdig ist (nicht aus User-Input). Umgeht Angulars DomSanitizer.
+
+## Conventions im Library-Code
+
+- Alle Komponenten: **standalone**, `OnPush`, kebab-case-Selector mit `xiri-`-Prefix
+- Alle Directives: camelCase-Selector (z.B. `[xiriSelect]`)
+- Signals für State, `input()`/`output()` für Komponenten-API
+- `UntypedFormGroup` für dynamisch konstruierte Forms (Field-Liste aus JSON)
+- `Observable` für HTTP, keine Promises
+- Kein NgModule — niemand importiert xiri-ng als Modul