@xiriframework/xiri-ng

Angular UI component library for the Xiri Framework — a JSON-driven approach where your backend defines the UI and xiri-ng renders it. Pairs with xiri-go (Go backend) or any backend that emits the expected JSON shape.

Installation

npm install @xiriframework/xiri-ng

Setup

Register the Xiri services in your application config. api is the base URL prepended to HTTP requests made by XiriDataService:

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideRouter } from '@angular/router';
import { provideXiriServices } from '@xiriframework/xiri-ng';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideRouter(routes),
    provideXiriServices({ api: '/api/' }),
  ],
};

The main entry point: xiri-dyncomponent

xiri-ng is designed around a central component that dynamically renders an array of JSON component definitions:

<xiri-dyncomponent [data]="components"></xiri-dyncomponent>

import { XiriDynComponentComponent, XiriDynData } from '@xiriframework/xiri-ng';

components: XiriDynData[] = [
  { type: 'page-header', data: { title: 'Dashboard' } },
  { type: 'stat-grid',   data: { stats: [...], columns: 4 } },
  { type: 'table',       data: { url: '/api/devices', ... } },
];

Individual components can also be used directly (all are standalone):

import { XiriTableComponent } from '@xiriframework/xiri-ng';

@Component({
  selector: 'app-devices',
  imports: [XiriTableComponent],
  template: `<xiri-table [settings]="tableSettings" />`,
})
export class DevicesComponent { /* ... */ }

Components

40+ standalone Material-Design components. Import individually for tree-shaking.

Forms & data

| Component | Use case | | ---------------------------- | -------------------------------------------------- | | XiriFormComponent | Dynamic form with backend-driven fields + submit | | XiriFormFieldsComponent | Just the fields — full control over submit flow | | XiriQueryComponent | Filter form + live results via xiri-dyncomponent | | XiriTableComponent | Full data table — sort, paginate, filter, inline-edit, export | | XiriRawTableComponent | Minimal table for static data | | XiriDialogComponent | Modal dialogs (question / form / table / waiting) | | XiriStepperComponent | Multi-step wizard |

Layout & navigation

| Component | Use case | | ---------------------------- | -------------------------------------------------- | | XiriPageHeaderComponent | Page title + subtitle + actions | | XiriToolbarComponent | Toolbar with title, search, buttons | | XiriSectionComponent | Collapsible content sections | | XiriDividerComponent | Section divider with optional text/icon | | XiriTabsComponent | Material tabs with lazy-loading | | XiriExpansionComponent | Accordion panels with lazy-loading | | XiriSidenavComponent | Side navigation with nested items | | XiriBreadcrumbComponent | Breadcrumb trail |

Cards, lists, info

| Component | Use case | | --------------------------------- | --------------------------------------------- | | XiriCardComponent | Card container with header + content | | XiriCardlinkComponent | Clickable card as a navigation link | | XiriLinksComponent | List of navigation links/buttons | | XiriListComponent | Sectioned list with favorites | | XiriInfopointComponent | Info card (icon + text + optional link) | | XiriImagetextComponent | Image + text card | | XiriDescriptionListComponent | Key/value pairs in 1-3 columns |

Stats, progress, feedback

| Component | Use case | | ----------------------------- | ------------------------------------------------- | | XiriStatComponent | Single KPI tile with value + label + trend | | XiriStatGridComponent | Grid of KPI tiles | | XiriMultiprogressComponent | Multi-row progress bars | | XiriTimelineComponent | Vertical or horizontal timeline | | XiriEmptyStateComponent | Empty-state placeholder with optional action | | XiriSkeletonComponent | Loading skeleton (text/circle/rect/table-row) | | XiriAlertComponent | Alert / confirmation dialog content | | XiriDoneComponent | Success checkmark | | XiriErrorComponent | Error message display | | XiriHeaderComponent | In-page section header |

Buttons & search

| Component | Use case | | ----------------------------- | ------------------------------------------------- | | XiriButtonComponent | Single button with action handling | | XiriButtonlineComponent | Horizontal button line | | XiriButtonstyleComponent | Internal — button visual renderer | | XiriSearchComponent | Debounced search input |

Services

All services are providedIn: 'root' and are activated by provideXiriServices():

| Service | Purpose | | ------------------------------- | ----------------------------------------------------------------- | | XiriDataService | HTTP client with automatic snackbar response handling | | XiriSnackbarService | Toast notifications (success, error, info, warning) | | XiriResponseHandlerService | Parses backend responses (refresh, goto, table-update) centrally | | XiriFormService | Form data fetch/submit + state persistence | | XiriDownloadService | File download handling (blob → browser) | | XiriDateService | Unix timestamp ↔ locale-formatted strings (via date-fns) | | XiriNumberService | Locale-aware number formatting | | XiriLocalStorageService | Typed localStorage wrapper with timestamp-based expiry | | XiriSessionStorageService | Typed sessionStorage wrapper | | ThemeService | Theme management (light / dark / auto) via signals |

Pipes

• SafehtmlPipe (| safeHtml) — bypass DomSanitizer for trusted HTML. Never feed user input into this pipe.

Claude Code support

The main repository ships a Claude Code skill (xiri-ng-expert) that teaches Claude the full API, patterns, and conventions. See the main README for installation.

Peer dependencies

• Angular 21+
• Angular Material 21+
• Angular CDK 21+
• RxJS 7.8+
• date-fns 4+
• @date-fns/tz 1+
• ngx-mat-select-search 8+
• material-symbols ≥ 0.40

License

Apache-2.0