@xngui/core

Shared design-system contracts for every @xngui/* package.

Install

pnpm add @xngui/core

Usually installed alongside @xngui/components — most apps import types and provideX() from here.

Main entry — @xngui/core

Typed unions, event payloads, data-pipeline shapes, and capability interfaces.

import type { XSize, XVariant, XDataQuery, XOpenBound } from '@xngui/core';

| Area | File | Examples | | ------------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Visual | types/visual.ts | XVariant, XColor, XAppearance, XDensity | | Size | types/size.ts | XSize, XWidth, XHeight | | Tokens | types/tokens.ts | XSpacingStep, XRadiusStep, XSemanticToken | | Layout | types/layout.ts | XPlacement, XOrientation, XOverlayLayer | | State | types/state.ts | XStatus, XLoadingMode, XDisabled | | Interaction | types/interaction.ts | XTrigger, XActivation, XScrollStrategy | | Capabilities | types/capabilities.ts | XDisableable, XOpenBound, XToastHost — signal implements contracts; some are aspirational until adopted by components | | Form | types/form.ts | XOption, XValidateOn, XValidationState | | Typography | types/typography.ts | XTextSize, XFontWeight, XTextOverflow | | Data | types/data.ts | XDataQuery, XFilter, XDataLoader | | Events | types/events.ts | XChangeEvent, XPageEvent, XSortEvent | | Media | types/media.ts | XIconPosition, XIconSize, XImageFit |

Theme mode types (XThemeMode, XResolvedTheme) live in @xngui/theme.

X_STORAGE_KEYS and browser persistence services live in @xngui/core/storage.

Capability contracts

types/capabilities.ts defines signal-based implements shapes for interactive components. Shipped adopters include XOpenBound (dialog, drawer, alert-dialog), XToastHost (toast), and XCollapsible (sidebar). Others (XPaginated, XSortable, XPlayback, …) are forward-looking contracts — prefer them when adding or refactoring the matching component.

Secondary entries

| Import | Purpose | | --------------------- | ------------------------------------------------------------------------------------------------- | | @xngui/core/config | provideX, provideXConfig, XConfigService, XConfig | | @xngui/core/i18n | XLocaleService, XTranslationService, XIntlService, XTranslatePipe, provideXTranslations | | @xngui/core/errors | provideXErrorHandler, XErrorHandlerService, domain errors | | @xngui/core/files | XFileService, XFileSource, pick/validate/resolve/download helpers, XFileError | | @xngui/core/logging | provideXLogger, XLoggerService, XLogger | | @xngui/core/storage | XLocalStorageService, XIndexedDbService, X_STORAGE_KEYS |

App bootstrap

import { provideX } from '@xngui/core/config';

export const appConfig = {
  providers: [
    provideX({
      config: { size: 'md', validateOn: 'touched' },
      locale: 'en-US',
    }),
  ],
};

provideX registers config defaults, optional logger/error handler overrides, locale, and optional translation packs from component i18n.ts catalogs.

Browser persistence

import { inject } from '@angular/core';
import { XLocalStorageService, XIndexedDbService, X_STORAGE_KEYS } from '@xngui/core/storage';

const local = inject(XLocalStorageService);
local.set(X_STORAGE_KEYS.theme, 'dark');

const db = inject(XIndexedDbService);
await db.open('my-app', { version: 1, stores: [{ name: 'drafts' }] });
await db.set('my-app', 'drafts', 'page-1', { title: 'Notes' });