@nexterajs/ui 0.0.1 → 0.1.0

package/types/nexterajs-ui-core.d.ts

@@ -1,7 +1,8 @@
 import * as _angular_core from '@angular/core';
-import { InjectionToken, ElementRef, NgZone, TemplateRef } from '@angular/core';
+import { InjectionToken, EnvironmentProviders, ElementRef, NgZone, TemplateRef } from '@angular/core';
 import * as _nexterajs_ui_core from '@nexterajs/ui/core';
 import { ControlValueAccessor } from '@angular/forms';
+import { NxeNumberSeparators } from '@nexterajs/ui/intl';
 
 /**
  * DevExtreme-compatible value-change event payload.
@@ -22,6 +23,309 @@ interface NxeValueChangedEvent<T> {
     /** The component host element (DevExtreme `element`). */
     element: HTMLElement;
 }
+/** Which native event an editor is re-emitting in dx's shape. */
+type NxeEditorEventKind = 'keydown' | 'keyup' | 'input' | 'change' | 'focusin' | 'focusout';
+/**
+ * dx's payload for the keyboard, focus and input events: the native event plus the widget and
+ * its host element, which is what handlers written against DevExtreme expect to receive.
+ */
+interface NxeEditorEvent {
+    event: Event;
+    component: unknown;
+    element: HTMLElement;
+}
+
+/**
+ * Every user-visible string the library renders, in English.
+ *
+ * Flat keys, namespaced by component (`grid.pager.info`). `{0}`, `{1}`... are positional
+ * arguments filled by `NxeMessageService.t(key, ...args)`. English is the default bundle and
+ * the fallback for any key a custom bundle leaves out, so the library renders exactly what it
+ * always did until an application opts into another locale.
+ *
+ * The key set is the type: `NxeMessageKey` is derived from it and the Indonesian bundle is
+ * checked against it, so a key added here without a translation fails to compile.
+ */
+declare const NXE_MESSAGES_EN: {
+    readonly 'common.search': "Search";
+    readonly 'common.clear': "Clear";
+    readonly 'common.close': "Close";
+    readonly 'common.ok': "OK";
+    readonly 'common.cancel': "Cancel";
+    readonly 'common.confirm': "Confirm";
+    readonly 'common.yes': "Yes";
+    readonly 'common.no': "No";
+    readonly 'common.all': "(All)";
+    readonly 'common.selectAll': "Select All";
+    readonly 'common.blanks': "(Blanks)";
+    readonly 'grid.noData': "No data";
+    readonly 'grid.groupPanel': "Drag a column header here to group by that column";
+    readonly 'grid.edit': "Edit";
+    readonly 'grid.save': "Save";
+    readonly 'grid.cancel': "Cancel";
+    readonly 'grid.expand': "Expand";
+    readonly 'grid.collapse': "Collapse";
+    readonly 'grid.expandedRow': "Expanded row";
+    readonly 'grid.collapsedRow': "Collapsed row";
+    readonly 'grid.editableCell': "Editable";
+    readonly 'grid.filterRow.operation': "Filter operation";
+    readonly 'grid.filterRow.reset': "Reset";
+    readonly 'grid.filterRow.true': "true";
+    readonly 'grid.filterRow.false': "false";
+    readonly 'grid.op.contains': "Contains";
+    readonly 'grid.op.notContains': "Does not contain";
+    readonly 'grid.op.startsWith': "Starts with";
+    readonly 'grid.op.endsWith': "Ends with";
+    readonly 'grid.op.equals': "Equals";
+    readonly 'grid.op.notEquals': "Does not equal";
+    readonly 'grid.op.lessThan': "Less than";
+    readonly 'grid.op.greaterThan': "Greater than";
+    readonly 'grid.op.lessThanOrEqual': "Less than or equal to";
+    readonly 'grid.op.greaterThanOrEqual': "Greater than or equal to";
+    readonly 'grid.op.between': "Between";
+    readonly 'grid.pager.info': "Page {0} of {1} ({2} items)";
+    readonly 'grid.pager.navigation': "Page navigation";
+    readonly 'grid.pager.pageSize': "Page size";
+    readonly 'grid.pager.itemsPerPage': "Items per page: {0}";
+    readonly 'grid.pager.previous': "Previous page";
+    readonly 'grid.pager.next': "Next page";
+    readonly 'grid.pager.page': "Page {0}";
+    readonly 'grid.pager.first': "First page";
+    readonly 'grid.pager.last': "Last page";
+    readonly 'grid.pager.total': "{0} items";
+    readonly 'grid.remote.loading': "Loading";
+    readonly 'grid.remote.error': "The data could not be loaded.";
+    readonly 'grid.remote.retry': "Retry";
+    readonly 'uploader.selectFile': "Select File";
+    readonly 'uploader.dropHere': "or Drop here";
+    readonly 'uploader.cancel': "Cancel";
+    readonly 'uploader.sizeB': "{0} b";
+    readonly 'uploader.sizeKb': "{0} Kb";
+    readonly 'uploader.sizeMb': "{0} Mb";
+    readonly 'validation.rule.required': "Required";
+    readonly 'validation.rule.email': "Email is invalid";
+    readonly 'validation.rule.pattern': "Value does not match pattern";
+    readonly 'validation.rule.range': "Value is out of range";
+    readonly 'validation.rule.compare': "Values do not match";
+    readonly 'validation.rule.custom': "Value is invalid";
+    readonly 'validation.field.required': "This field is required.";
+    readonly 'validation.field.email': "Enter a valid email address.";
+    readonly 'validation.field.minlength': "Enter at least {0} characters.";
+    readonly 'validation.field.maxlength': "Enter no more than {0} characters.";
+    readonly 'validation.field.min': "Must be at least {0}.";
+    readonly 'validation.field.max': "Must be at most {0}.";
+    readonly 'validation.field.pattern': "Enter a value in the expected format.";
+    readonly 'validation.field.invalid': "This value is not valid.";
+    readonly 'date.now': "Now";
+    readonly 'date.done': "Done";
+    readonly 'date.hour': "Hour";
+    readonly 'date.minute': "Minute";
+    readonly 'dateRange.start': "Start date";
+    readonly 'dateRange.end': "End date";
+    readonly 'dateRange.startPlaceholder': "Start date";
+    readonly 'dateRange.endPlaceholder': "End date";
+    readonly 'dateRange.dialog': "Choose a date range";
+    readonly 'dateRange.previousMonth': "Previous month";
+    readonly 'dateRange.nextMonth': "Next month";
+    readonly 'dateRange.presets': "Quick ranges";
+    readonly 'dateRange.pickStart': "Select the start date";
+    readonly 'dateRange.pickEnd': "Select the end date";
+    readonly 'dateRange.preset.today': "Today";
+    readonly 'dateRange.preset.yesterday': "Yesterday";
+    readonly 'dateRange.preset.last7Days': "Last 7 days";
+    readonly 'dateRange.preset.last30Days': "Last 30 days";
+    readonly 'dateRange.preset.thisMonth': "This month";
+    readonly 'dateRange.preset.lastMonth': "Last month";
+    readonly 'dateRange.preset.thisYear': "This year";
+    readonly 'dropdown.noData': "No data to display";
+    readonly 'dropdown.selectAll': "Select All";
+    readonly 'uploader.selectFiles': "Select files";
+    readonly 'uploader.dropFiles': "or drop files here";
+    readonly 'uploader.listLabel': "Attached files";
+    readonly 'uploader.acceptHint': "Accepted: {0}";
+    readonly 'uploader.maxSizeHint': "Up to {0} each";
+    readonly 'uploader.maxFilesHint': "Up to {0} files";
+    readonly 'uploader.statusPending': "Waiting to upload";
+    readonly 'uploader.statusUploading': "Uploading {0}%";
+    readonly 'uploader.statusUploaded': "Uploaded";
+    readonly 'uploader.statusFailed': "Upload failed";
+    readonly 'uploader.uploadingFile': "Uploading {0}";
+    readonly 'uploader.uploadFailed': "The upload failed.";
+    readonly 'uploader.cancelled': "Upload cancelled.";
+    readonly 'uploader.cancelFile': "Cancel upload of {0}";
+    readonly 'uploader.retryFile': "Retry upload of {0}";
+    readonly 'uploader.removeFile': "Remove {0}";
+    readonly 'uploader.retry': "Retry";
+    readonly 'uploader.remove': "Remove";
+    readonly 'uploader.rejectType': "{0} is not an accepted file type.";
+    readonly 'uploader.rejectSize': "{0} is larger than {1}.";
+    readonly 'uploader.rejectCount': "{0} is over the limit of {1} files.";
+    readonly 'uploader.announceAdded': "{0} added";
+    readonly 'uploader.announceRemoved': "{0} removed";
+    readonly 'validation.field.fileType': "Only these file types are accepted: {0}.";
+    readonly 'validation.field.fileSize': "Each file must be {0} or smaller.";
+    readonly 'validation.field.maxFiles': "Attach at most {0} files.";
+    readonly 'validation.field.uploading': "Wait for the uploads to finish.";
+    readonly 'validation.field.uploadFailed': "Retry or remove the files that failed to upload.";
+    readonly 'timeline.pending': "Pending";
+    readonly 'stepper.listLabel': "Steps";
+    readonly 'stepper.stepOf': "Step {0} of {1}: {2}";
+    readonly 'stepper.completed': "Completed";
+    readonly 'stepper.error': "Has errors";
+    readonly 'stepper.optional': "Optional";
+    readonly 'stepper.blocked': "Step {0} is not complete. Fix the highlighted fields to continue.";
+    readonly 'notify.close': "Close notification";
+    readonly 'shell.skipToContent': "Skip to content";
+    readonly 'shell.mainNavigation': "Main navigation";
+    readonly 'shell.toggleNavigation': "Toggle navigation";
+    readonly 'shell.closeNavigation': "Close navigation";
+    readonly 'shell.collapseSidebar': "Collapse sidebar";
+    readonly 'shell.expandSidebar': "Expand sidebar";
+    readonly 'pivot.grandTotal': "Grand Total";
+    readonly 'pivot.total': "{0} Total";
+    readonly 'pivot.noData': "No data";
+    readonly 'pivot.showFieldChooser': "Show Field Chooser";
+    readonly 'pivot.chooser.title': "Field Chooser";
+    readonly 'pivot.chooser.allFields': "All Fields";
+    readonly 'pivot.chooser.rowFields': "Row Fields";
+    readonly 'pivot.chooser.columnFields': "Column Fields";
+    readonly 'pivot.chooser.filterFields': "Filter Fields";
+    readonly 'pivot.chooser.dataFields': "Data Fields";
+    readonly 'pivot.chooser.checkState': "Check state";
+    readonly 'pivot.panel.dropFilter': "Drop Filter Fields Here";
+    readonly 'pivot.panel.dropData': "Drop Data Fields Here";
+    readonly 'pivot.panel.dropColumn': "Drop Column Fields Here";
+    readonly 'pivot.panel.dropRow': "Drop Row Fields Here";
+    readonly 'forms.password.show': "Show password";
+    readonly 'forms.password.hide': "Hide password";
+    readonly 'forms.textArea.charactersLeft': "{0} characters left";
+    readonly 'forms.textArea.charactersOver': "{0} characters over the limit";
+    readonly 'forms.numberBox.increase': "Increase";
+    readonly 'forms.numberBox.decrease': "Decrease";
+    readonly 'display.noValue': "No value";
+    readonly 'charts.other': "Other";
+    readonly 'charts.total': "Total";
+    readonly 'charts.empty': "No data to chart";
+    readonly 'charts.legend': "Legend";
+    readonly 'charts.viewAsTable': "View as table";
+    readonly 'charts.viewAsChart': "View as chart";
+    readonly 'charts.navigate': "Chart data. Use the arrow keys to move between points, Escape to leave.";
+    readonly 'charts.navigateSegments': "Chart segments. Use the arrow keys to move between segments, Escape to leave.";
+    readonly 'charts.summary.line': "Line chart, {0} series, {1} points from {2} to {3}.";
+    readonly 'charts.summary.area': "Area chart, {0} series, {1} points from {2} to {3}.";
+    readonly 'charts.summary.stackedArea': "Stacked area chart, {0} series, {1} points from {2} to {3}.";
+    readonly 'charts.summary.series': "{0}: from {1} to {2}, lowest {3}, highest {4}.";
+    readonly 'charts.summary.donut': "Donut chart, {0} segments, total {1}.";
+    readonly 'charts.summary.segment': "{0}: {1}, {2}.";
+    readonly 'charts.table.category': "Category";
+    readonly 'charts.table.segment': "Segment";
+    readonly 'charts.table.value': "Value";
+    readonly 'charts.table.share': "Share";
+    readonly 'avatar.status.online': "Online";
+    readonly 'avatar.status.away': "Away";
+    readonly 'avatar.status.busy': "Busy";
+    readonly 'avatar.status.offline': "Offline";
+    readonly 'avatar.more': "{0} more";
+    readonly 'breadcrumb.label': "Breadcrumb";
+    readonly 'breadcrumb.more': "Show hidden levels";
+};
+/** A key of the message bundle. */
+type NxeMessageKey = keyof typeof NXE_MESSAGES_EN;
+/** A complete message bundle: every key, one string each. */
+type NxeMessages = Readonly<Record<NxeMessageKey, string>>;
+
+/** What an application states once at bootstrap; see {@link provideNxeMessages}. */
+interface NxeMessagesConfig {
+    /** Initial locale (`'en'`, `'id'`, `'id-ID'`...). Default `'en'`. */
+    locale?: string;
+    /** Partial bundle layered over the active language's bundle, whatever the language. */
+    overrides?: Partial<NxeMessages>;
+    /**
+     * Extra or replacement bundles by language (`{ fr: { 'common.cancel': 'Annuler' } }`). A bundle
+     * may be partial: keys it leaves out fall back to English.
+     */
+    bundles?: Readonly<Record<string, Partial<NxeMessages>>>;
+    /**
+     * Set Luxon's `Settings.defaultLocale` to the active locale, so month and weekday names (and
+     * every `MMM` in a display format) follow the language. Default `true`; `false` leaves Luxon
+     * alone. Luxon's previous default is restored when the service is destroyed.
+     */
+    luxon?: boolean;
+    /**
+     * Make number separators follow the locale: `true` uses `1.234,5` for `id` and `1,234.5`
+     * otherwise, or pass your own `{ [language]: separators }` map. It takes effect through
+     * {@link provideNxeMessages}, which then provides {@link NXE_NUMBER_SEPARATORS} as a live view
+     * of the active locale. Default off: numbers keep whatever `NXE_NUMBER_SEPARATORS` says.
+     */
+    separators?: boolean | Readonly<Record<string, NxeNumberSeparators>>;
+}
+/**
+ * The library's initial message configuration, provided by {@link provideNxeMessages}. Absent,
+ * the service starts in English with nothing overridden.
+ */
+declare const NXE_MESSAGES: InjectionToken<NxeMessagesConfig>;
+/**
+ * Runtime-switchable messages for every `nxe-*` component.
+ *
+ * State is signals, so a component that reads {@link t} (or {@link messages}) inside a template or
+ * a `computed` re-renders when the language changes: no reload, no recreation. That is also what
+ * makes it safe under zoneless OnPush, because the template's reactive consumer tracks the read.
+ *
+ * ```ts
+ * const messages = inject(NxeMessageService);
+ * messages.use('id');
+ * messages.t('grid.pager.info', 1, 5, 42); // 'Halaman 1 dari 5 (42 item)'
+ * ```
+ */
+declare class NxeMessageService {
+    private readonly config;
+    private readonly localeState;
+    private readonly customBundle;
+    private readonly overrideState;
+    /** The active locale as the application stated it (`'id'`, `'en-US'`...). */
+    readonly locale: _angular_core.Signal<string>;
+    /** The active language (`'id'` for `'id-ID'`); what picks the bundle. */
+    readonly language: _angular_core.Signal<string>;
+    /** The bundle in force: English, under the language's bundle, under the overrides. */
+    readonly messages: _angular_core.Signal<Readonly<Record<"common.search" | "common.clear" | "common.close" | "common.ok" | "common.cancel" | "common.confirm" | "common.yes" | "common.no" | "common.all" | "common.selectAll" | "common.blanks" | "grid.noData" | "grid.groupPanel" | "grid.edit" | "grid.save" | "grid.cancel" | "grid.expand" | "grid.collapse" | "grid.expandedRow" | "grid.collapsedRow" | "grid.editableCell" | "grid.filterRow.operation" | "grid.filterRow.reset" | "grid.filterRow.true" | "grid.filterRow.false" | "grid.op.contains" | "grid.op.notContains" | "grid.op.startsWith" | "grid.op.endsWith" | "grid.op.equals" | "grid.op.notEquals" | "grid.op.lessThan" | "grid.op.greaterThan" | "grid.op.lessThanOrEqual" | "grid.op.greaterThanOrEqual" | "grid.op.between" | "grid.pager.info" | "grid.pager.navigation" | "grid.pager.pageSize" | "grid.pager.itemsPerPage" | "grid.pager.previous" | "grid.pager.next" | "grid.pager.page" | "grid.pager.first" | "grid.pager.last" | "grid.pager.total" | "grid.remote.loading" | "grid.remote.error" | "grid.remote.retry" | "uploader.selectFile" | "uploader.dropHere" | "uploader.cancel" | "uploader.sizeB" | "uploader.sizeKb" | "uploader.sizeMb" | "validation.rule.required" | "validation.rule.email" | "validation.rule.pattern" | "validation.rule.range" | "validation.rule.compare" | "validation.rule.custom" | "validation.field.required" | "validation.field.email" | "validation.field.minlength" | "validation.field.maxlength" | "validation.field.min" | "validation.field.max" | "validation.field.pattern" | "validation.field.invalid" | "date.now" | "date.done" | "date.hour" | "date.minute" | "dateRange.start" | "dateRange.end" | "dateRange.startPlaceholder" | "dateRange.endPlaceholder" | "dateRange.dialog" | "dateRange.previousMonth" | "dateRange.nextMonth" | "dateRange.presets" | "dateRange.pickStart" | "dateRange.pickEnd" | "dateRange.preset.today" | "dateRange.preset.yesterday" | "dateRange.preset.last7Days" | "dateRange.preset.last30Days" | "dateRange.preset.thisMonth" | "dateRange.preset.lastMonth" | "dateRange.preset.thisYear" | "dropdown.noData" | "dropdown.selectAll" | "uploader.selectFiles" | "uploader.dropFiles" | "uploader.listLabel" | "uploader.acceptHint" | "uploader.maxSizeHint" | "uploader.maxFilesHint" | "uploader.statusPending" | "uploader.statusUploading" | "uploader.statusUploaded" | "uploader.statusFailed" | "uploader.uploadingFile" | "uploader.uploadFailed" | "uploader.cancelled" | "uploader.cancelFile" | "uploader.retryFile" | "uploader.removeFile" | "uploader.retry" | "uploader.remove" | "uploader.rejectType" | "uploader.rejectSize" | "uploader.rejectCount" | "uploader.announceAdded" | "uploader.announceRemoved" | "validation.field.fileType" | "validation.field.fileSize" | "validation.field.maxFiles" | "validation.field.uploading" | "validation.field.uploadFailed" | "timeline.pending" | "stepper.listLabel" | "stepper.stepOf" | "stepper.completed" | "stepper.error" | "stepper.optional" | "stepper.blocked" | "notify.close" | "shell.skipToContent" | "shell.mainNavigation" | "shell.toggleNavigation" | "shell.closeNavigation" | "shell.collapseSidebar" | "shell.expandSidebar" | "pivot.grandTotal" | "pivot.total" | "pivot.noData" | "pivot.showFieldChooser" | "pivot.chooser.title" | "pivot.chooser.allFields" | "pivot.chooser.rowFields" | "pivot.chooser.columnFields" | "pivot.chooser.filterFields" | "pivot.chooser.dataFields" | "pivot.chooser.checkState" | "pivot.panel.dropFilter" | "pivot.panel.dropData" | "pivot.panel.dropColumn" | "pivot.panel.dropRow" | "forms.password.show" | "forms.password.hide" | "forms.textArea.charactersLeft" | "forms.textArea.charactersOver" | "forms.numberBox.increase" | "forms.numberBox.decrease" | "display.noValue" | "charts.other" | "charts.total" | "charts.empty" | "charts.legend" | "charts.viewAsTable" | "charts.viewAsChart" | "charts.navigate" | "charts.navigateSegments" | "charts.summary.line" | "charts.summary.area" | "charts.summary.stackedArea" | "charts.summary.series" | "charts.summary.donut" | "charts.summary.segment" | "charts.table.category" | "charts.table.segment" | "charts.table.value" | "charts.table.share" | "avatar.status.online" | "avatar.status.away" | "avatar.status.busy" | "avatar.status.offline" | "avatar.more" | "breadcrumb.label" | "breadcrumb.more", string>>>;
+    /** Separators for the active locale; en-US for a language with none. */
+    readonly separators: _angular_core.Signal<NxeNumberSeparators>;
+    private readonly luxonSync;
+    private readonly luxonBefore;
+    constructor();
+    /**
+     * Switch language. A string picks a built-in or configured bundle (`'id'`, `'en'`); a bundle
+     * object replaces the language's bundle outright (keys it leaves out fall back to English),
+     * under the locale named by the second argument, or the current one.
+     */
+    use(locale: string): void;
+    use(bundle: Partial<NxeMessages>, locale?: string): void;
+    /** Layer messages over the active bundle. They merge with earlier overrides and survive {@link use}. */
+    override(messages: Partial<NxeMessages>): void;
+    /** Drop every override added since bootstrap; the ones in the configuration stay. */
+    clearOverrides(): void;
+    /**
+     * One message, with `{0}`, `{1}`... replaced by `args`. Reactive: reading it in a template or a
+     * `computed` subscribes that consumer to the language.
+     */
+    t(key: NxeMessageKey, ...args: readonly unknown[]): string;
+    /** Fill `{n}` placeholders; one without an argument is left as written. */
+    static format(template: string, args: readonly unknown[]): string;
+    private setLocale;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeMessageService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NxeMessageService>;
+}
+/**
+ * Registers the library's messages for the application:
+ *
+ * ```ts
+ * provideNxeMessages({ locale: 'id', overrides: { 'grid.noData': 'Belum ada data' } })
+ * ```
+ *
+ * With `separators` set it also provides {@link NXE_NUMBER_SEPARATORS} as a live view of the active
+ * locale's separators, so grids and number boxes go from `1,234.5` to `1.234,5` with the language.
+ */
+declare function provideNxeMessages(config?: NxeMessagesConfig): EnvironmentProviders;
 
 /** A single failed validation rule. */
 interface NxeBrokenRule {
@@ -47,35 +351,40 @@ interface NxeValidationTarget {
     getValue(): unknown;
     validationGroup(): string | undefined;
     setValidationError(message: string | null): void;
+    /**
+     * Tell the editor whether a `required` rule applies, so it can render `aria-required`.
+     * Optional: a target predating this simply does not advertise the requirement.
+     */
+    setRequired?(required: boolean): void;
 }
 /** DI token the editor provides so its nested `nxe-validator` can adapt it. */
 declare const NXE_VALIDATION_TARGET: InjectionToken<NxeValidationTarget>;
 /** A member registered in a validation group (an `nxe-validator`). */
 interface NxeValidationGroupMember {
     validate(): NxeValidationResult;
+    /** Clear the member's error state without validating. Optional for older members. */
+    reset?(): void;
 }
-
 /**
- * Signal-based `ControlValueAccessor` base for every nxe form editor
- * (`nxe-text-box`, `nxe-number-box`, `nxe-date-box`, `nxe-check-box`, `nxe-text-area`,
- * `nxe-select-box`, `nxe-tag-box`, `nxe-radio`, ...).
- *
- * It supports BOTH template-driven (`[(ngModel)]`) and reactive (`formControlName`) forms
- * transparently, as well as DevExtreme-style `[value]` / `[(value)]` two-way binding, and
- * emits the DevExtreme-shaped {@link NxeValueChangedEvent} from `onValueChanged`.
- *
- * Concrete components MUST register themselves as the value accessor, e.g.:
- * ```ts
- * @Component({
- *   selector: 'nxe-text-box',
- *   providers: [{ provide: NG_VALUE_ACCESSOR, useExisting: forwardRef(() => NxeTextBoxComponent), multi: true }],
- *   ...
- * })
- * export class NxeTextBoxComponent extends NxeFormControlBase<string> { ... }
- * ```
+ * An `nxe-validation-group` ancestor, exposed so a validator or a button inside it can join it
+ * without naming a group.
  *
- * Subclasses call {@link commitValue} on user interaction and {@link markAsTouched} on blur.
+ * DevExtreme lets a group be addressed two ways: by a string name shared between a validator and
+ * a button, or structurally by wrapping both in a `dxValidationGroup`. The string form is what
+ * the consuming applications use; this token is the structural one, and an explicit string
+ * always wins over it, as in dx.
  */
+interface NxeValidationGroupScope {
+    /** Opaque, unique per instance — never collides with an application's own group names. */
+    readonly groupKey: string;
+}
+declare const NXE_VALIDATION_GROUP: InjectionToken<NxeValidationGroupScope>;
+/** DevExtreme-shaped `onValidated` payload. */
+interface NxeValidatedEvent extends NxeValidationResult {
+    value: unknown;
+    validationGroup: string;
+}
+
 declare abstract class NxeFormControlBase<T> implements ControlValueAccessor, NxeValidationTarget {
     protected readonly elementRef: ElementRef<HTMLElement>;
     /**
@@ -85,28 +394,128 @@ declare abstract class NxeFormControlBase<T> implements ControlValueAccessor, Nx
     protected readonly ngZone: NgZone;
     /** Application-wide defaults; each editor resolves `binding ?? this ?? literal`. */
     protected readonly nxeDefaults: _nexterajs_ui_core.NxeDefaultOptions;
+    /** The library's runtime-switchable messages; read them in a template or a computed. */
+    protected readonly nxeMessages: NxeMessageService;
     /**
      * The current value — single source of truth. Two-way bindable as `[(value)]` (DevExtreme
      * parity) and also driven by `writeValue` for `ngModel`/`formControlName`.
      */
-    readonly value: _angular_core.ModelSignal<T>;
+    readonly value: _angular_core.ModelSignal<T | null>;
     /** Disabled via the `[disabled]` input (DevExtreme parity); OR-combined with forms disabled. */
     readonly disabledInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
     private readonly disabledByForm;
     /** Effective disabled state (input OR reactive-forms `setDisabledState`). */
     readonly disabled: _angular_core.Signal<boolean>;
     /** Read-only state (DevExtreme `[readOnly]`). */
-    readonly readOnly: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly readOnlyInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Lower-case spelling of {@link readOnlyInput}: it is the name Signal Forms (`[formField]`)
+     * binds a `readonly()` rule to, and the HTML attribute name.
+     */
+    readonly readonlyInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Effective read-only state: `readOnly` OR `readonly`. */
+    readonly readOnly: _angular_core.Signal<boolean>;
+    /**
+     * Signal Forms hides a field with `hidden()` and binds it by this name; also usable on its own.
+     * Hides the host, like `visible=false`.
+     */
+    readonly hiddenInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Signal Forms state, bound by name when the editor carries `[formField]` (and settable by hand).
+     * `invalid` and `errors` put the editor in its invalid state (`nxe-invalid`, `aria-invalid`) once
+     * it is {@link touched}; the message text is `nxe-form-field`'s job.
+     */
+    readonly invalidInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly errorsInput: _angular_core.InputSignal<readonly {
+        readonly kind: string;
+        readonly message?: string;
+    }[] | null | undefined>;
+    protected readonly touchedInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Validation group this editor belongs to (its nested `nxe-validator` registers here). */
-    readonly validationGroupInput: _angular_core.InputSignal<string>;
+    readonly validationGroupInput: _angular_core.InputSignal<string | undefined>;
+    /**
+     * `id` for the INNER control, not the host.
+     *
+     * A caption written as `<label for="x">` has to reach the focusable element, and the host of
+     * a custom element is not it. Without this an editor cannot be labelled at all, which is why
+     * `aria-label` sits beside it: one of the two has to be available.
+     */
+    readonly inputId: _angular_core.InputSignal<string | undefined>;
+    readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
+    readonly ariaLabelledBy: _angular_core.InputSignal<string | undefined>;
+    /** Stable per instance, so the inner control always has an id something can point at. */
+    private readonly fallbackId;
+    readonly controlId: _angular_core.Signal<string>;
+    /**
+     * Ids for a popup listbox and its options.
+     *
+     * `aria-activedescendant` is how a combobox says which option is current while focus stays in
+     * the text field, and it can only point at an id — so the options need stable ones.
+     */
+    panelId(): string;
+    optionId(index: number): string;
+    /**
+     * Whether a nested validator carries a `required` rule.
+     *
+     * Set by the validator rather than declared on the editor: the rule is where the requirement
+     * is actually stated, and duplicating it as an input would let the two disagree.
+     */
+    private readonly requiredByRule;
+    /**
+     * A `required` input, which is what Signal Forms binds a `required()` rule to, so a form that
+     * is not driven by `nxe-validator` can state it too.
+     */
+    readonly requiredInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether the editor is required: the `required` input OR a nested validator's `required` rule. */
+    readonly required: _angular_core.Signal<boolean>;
+    setRequired(value: boolean): void;
     /** The current validation error message (set by a nested `nxe-validator`), or null. */
-    readonly validationError: _angular_core.WritableSignal<string>;
-    /** Whether the control has been blurred at least once. */
-    readonly touched: _angular_core.WritableSignal<boolean>;
+    readonly validationError: _angular_core.WritableSignal<string | null>;
+    private readonly touchedByUser;
+    /** Whether the control has been blurred at least once, or a form says the field was touched. */
+    readonly touched: _angular_core.Signal<boolean>;
+    /**
+     * Whether the editor shows its invalid look: a nested validator's message, or a form's
+     * `invalid`/`errors` once the field is touched (so an untouched, empty required field is not red).
+     */
+    readonly invalidState: _angular_core.Signal<boolean>;
     /** Whether the value has been changed by the user at least once. */
     readonly dirty: _angular_core.WritableSignal<boolean>;
     /** DevExtreme-compatible value-change event. */
     readonly onValueChanged: _angular_core.OutputEmitterRef<NxeValueChangedEvent<T>>;
+    /**
+     * dx's keyboard, focus and input events.
+     *
+     * Native events already reach the host, so these are not about capability — they are about
+     * the call site. A migrated `(onEnterKey)` handler should keep working without being
+     * rewritten as a `(keydown)` with a key check, and `onEnterKey` in particular has no native
+     * equivalent at all.
+     */
+    readonly onKeyDown: _angular_core.OutputEmitterRef<NxeEditorEvent>;
+    readonly onKeyUp: _angular_core.OutputEmitterRef<NxeEditorEvent>;
+    readonly onEnterKey: _angular_core.OutputEmitterRef<NxeEditorEvent>;
+    readonly onInput: _angular_core.OutputEmitterRef<NxeEditorEvent>;
+    readonly onChange: _angular_core.OutputEmitterRef<NxeEditorEvent>;
+    readonly onFocusIn: _angular_core.OutputEmitterRef<NxeEditorEvent>;
+    readonly onFocusOut: _angular_core.OutputEmitterRef<NxeEditorEvent>;
+    /**
+     * When a typed value is committed: dx's `'change'` (on blur), `'input'` (per keystroke) or
+     * `'keyup'`.
+     *
+     * Honoured by the text editors. The number and date boxes stay on `'change'` whatever this
+     * says, because their displayed text is derived from the parsed value: committing mid-entry
+     * would rewrite the field while the user is still typing into it.
+     */
+    readonly valueChangeEvent: _angular_core.InputSignal<"keyup" | "input" | "change">;
+    /** dx universal widget options. */
+    readonly hint: _angular_core.InputSignal<string | undefined>;
+    readonly width: _angular_core.InputSignal<string | number | undefined>;
+    readonly visible: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly tabIndex: _angular_core.InputSignal<number | undefined>;
+    readonly elementAttr: _angular_core.InputSignal<Record<string, string> | undefined>;
+    protected readonly widthStyle: _angular_core.Signal<string | null>;
+    protected readonly elementAttrClass: _angular_core.Signal<string | null>;
+    protected readonly elementAttrId: _angular_core.Signal<string | null>;
     private _onChange;
     private _onTouched;
     /** Host element (the DevExtreme event payload `element`). */
@@ -124,10 +533,42 @@ declare abstract class NxeFormControlBase<T> implements ControlValueAccessor, Nx
      * DevExtreme-shaped `onValueChanged`. No-op when the value is unchanged.
      */
     protected commitValue(next: T | null, event?: Event | null): void;
+    /**
+     * Commit whatever the user has typed but not yet committed, now and synchronously.
+     *
+     * With the default `valueChangeEvent` a typed value commits on blur, so a programmatic submit
+     * (or anything else that reads the model while the field still has focus) would see the old
+     * value. Call this first. It is a no-op when nothing is pending, so it never emits
+     * `onValueChanged` twice for one change, and it does not blur the field or mark it touched.
+     */
+    commit(): void;
+    /** Alias of {@link commit}. */
+    flush(): void;
+    /**
+     * Editors with text that can be typed but not yet committed override this to commit it through
+     * {@link commitValue}. The default is for editors that commit on every interaction.
+     */
+    protected commitPending(_event: Event | null): void;
+    /** Whether Enter in this editor commits the pending text. Multi-line editors narrow it. */
+    protected commitsOnEnter(_event: KeyboardEvent): boolean;
+    /**
+     * Re-emit a native event in dx's shape.
+     *
+     * `onEnterKey` is the one that earns its keep: it has no native equivalent, so every call
+     * site would otherwise carry its own key check.
+     */
+    protected emitEditorEvent(kind: NxeEditorEventKind, event: Event): void;
+    /**
+     * Commit `next` if `valueChangeEvent` says this is the moment.
+     *
+     * Blur always commits, whatever the mode: a value the user typed and then left must not be
+     * discarded because the configured event never fired.
+     */
+    protected commitOn(kind: 'input' | 'keyup' | 'change', next: T | null, event: Event): void;
     /** Mark the control as touched (e.g. on blur), notifying Angular forms exactly once. */
     protected markAsTouched(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeFormControlBase<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NxeFormControlBase<any>, never, never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "disabledInput": { "alias": "disabled"; "required": false; "isSignal": true; }; "readOnly": { "alias": "readOnly"; "required": false; "isSignal": true; }; "validationGroupInput": { "alias": "validationGroup"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "onValueChanged": "onValueChanged"; }, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NxeFormControlBase<any>, never, never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "disabledInput": { "alias": "disabled"; "required": false; "isSignal": true; }; "readOnlyInput": { "alias": "readOnly"; "required": false; "isSignal": true; }; "readonlyInput": { "alias": "readonly"; "required": false; "isSignal": true; }; "hiddenInput": { "alias": "hidden"; "required": false; "isSignal": true; }; "invalidInput": { "alias": "invalid"; "required": false; "isSignal": true; }; "errorsInput": { "alias": "errors"; "required": false; "isSignal": true; }; "touchedInput": { "alias": "touched"; "required": false; "isSignal": true; }; "validationGroupInput": { "alias": "validationGroup"; "required": false; "isSignal": true; }; "inputId": { "alias": "inputId"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; "ariaLabelledBy": { "alias": "aria-labelledby"; "required": false; "isSignal": true; }; "requiredInput": { "alias": "required"; "required": false; "isSignal": true; }; "valueChangeEvent": { "alias": "valueChangeEvent"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "visible": { "alias": "visible"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; "isSignal": true; }; "elementAttr": { "alias": "elementAttr"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "onValueChanged": "onValueChanged"; "onKeyDown": "onKeyDown"; "onKeyUp": "onKeyUp"; "onEnterKey": "onEnterKey"; "onInput": "onInput"; "onChange": "onChange"; "onFocusIn": "onFocusIn"; "onFocusOut": "onFocusOut"; }, never, never, true, never>;
 }
 
 /**
@@ -196,6 +637,12 @@ interface NxeGridDefaultOptions {
     showBorders?: boolean;
     wordWrapEnabled?: boolean;
     noDataText?: string;
+    /**
+     * Widget-mode column resizing: when a manual resize leaves the columns narrower than the grid,
+     * the trailing column takes the rest, while dragging and after, so no blank strip shows on the
+     * right. dx (and the default) lets the table end short of the grid.
+     */
+    resizeFillsGrid?: boolean;
 }
 interface NxePickerDefaultOptions {
     displayExpr?: string;
@@ -219,10 +666,12 @@ interface NxeDefaultOptions {
     readonly dateBox?: {
         displayFormat?: string;
         placeholder?: string;
+        showClearButton?: boolean;
     };
     readonly textBox?: {
         placeholder?: string;
         hoverStateEnabled?: boolean;
+        showClearButton?: boolean;
     };
     readonly textArea?: {
         placeholder?: string;
@@ -230,6 +679,7 @@ interface NxeDefaultOptions {
     };
     readonly numberBox?: {
         format?: string;
+        showClearButton?: boolean;
     };
     readonly button?: {
         focusStateEnabled?: boolean;
@@ -277,7 +727,7 @@ declare class NxeTemplateDirective {
     /** Attribute-form name (`nxeTemplate="name"`); empty in microsyntax usage. */
     readonly attrName: _angular_core.InputSignal<string>;
     /** Microsyntax-form name (`*nxeTemplate="let x of 'name'"` binds `nxeTemplateOf`). */
-    readonly ofName: _angular_core.InputSignal<string>;
+    readonly ofName: _angular_core.InputSignal<string | undefined>;
     /** The template's lookup name, whichever form supplied it. */
     readonly name: _angular_core.Signal<string>;
     readonly templateRef: TemplateRef<unknown>;
@@ -306,6 +756,24 @@ declare function coerceArray<T>(value: T | readonly T[] | null | undefined): T[]
  */
 declare function nxeOptionalBoolean(value: unknown): boolean | undefined;
 
+/**
+ * DevExtreme's `displayExpr` / `valueExpr` / `searchExpr` accessor.
+ *
+ * dx accepts four spellings and the library accepted one — a flat property name — so a dotted
+ * path silently read `item['user.name']` and returned undefined. Silent, because an accessor
+ * that misses looks exactly like a field that is empty.
+ *
+ *   undefined / ''   the item itself      (dx: no expression)
+ *   'this'           the item itself      (dx's documented sentinel)
+ *   'user.name'      a dotted path
+ *   (item) => ...    a function accessor
+ */
+type NxeExpr<T = unknown> = string | ((item: T) => unknown) | undefined | null;
+/** Resolve `expr` against `item`. */
+declare function nxeResolveExpr<T = unknown>(expr: NxeExpr<T>, item: T): unknown;
+/** Resolve `expr` and render it as display text: `null`/`undefined` become the empty string. */
+declare function nxeResolveText<T = unknown>(expr: NxeExpr<T>, item: T): string;
+
 /**
  * Root registry mapping a `validationGroup` string to the `nxe-validator`s in it, mirroring
  * DevExtreme's global ValidationEngine.
@@ -318,11 +786,28 @@ declare class NxeValidationGroupRegistry {
     private readonly groups;
     register(group: string, member: NxeValidationGroupMember): void;
     unregister(group: string, member: NxeValidationGroupMember): void;
+    /**
+     * Clear every member's error state without validating.
+     *
+     * dx's `ValidationGroup.reset()`. The distinction from `validate()` matters after a Cancel:
+     * the fields should stop showing errors, not be re-checked and light up again.
+     */
+    reset(group: string): void;
     /** Validate every member of the group; valid (and empty) groups return `isValid: true`. */
     validate(group: string): NxeValidationResult;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeValidationGroupRegistry, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<NxeValidationGroupRegistry>;
 }
 
-export { NXE_DEFAULT_OPTIONS, NXE_OPTION, NXE_VALIDATION_TARGET, NxeConfigOptionBase, NxeFormControlBase, NxeTemplateDirective, NxeValidationGroupRegistry, coerceArray, nxeOptionalBoolean };
-export type { NxeBrokenRule, NxeConfigOption, NxeDefaultOptions, NxeGridDefaultOptions, NxePickerDefaultOptions, NxeValidationGroupMember, NxeValidationResult, NxeValidationTarget, NxeValueChangedEvent };
+/** Indonesian bundle (Bahasa Indonesia), checked against the English key set. */
+declare const NXE_MESSAGES_ID: NxeMessages;
+
+/**
+ * A byte count as the library writes it in the active language: "512 b", "1.5 Kb", "2.0 Mb" in English,
+ * "512 B", "1,5 KB" in Indonesian (the `uploader.size*` messages). Used by the file input and by the
+ * file-size message of `nxe-form-field`.
+ */
+declare function nxeFormatFileSize(bytes: number, messages: NxeMessageService): string;
+
+export { NXE_DEFAULT_OPTIONS, NXE_MESSAGES, NXE_MESSAGES_EN, NXE_MESSAGES_ID, NXE_OPTION, NXE_VALIDATION_GROUP, NXE_VALIDATION_TARGET, NxeConfigOptionBase, NxeFormControlBase, NxeMessageService, NxeTemplateDirective, NxeValidationGroupRegistry, coerceArray, nxeFormatFileSize, nxeOptionalBoolean, nxeResolveExpr, nxeResolveText, provideNxeMessages };
+export type { NxeBrokenRule, NxeConfigOption, NxeDefaultOptions, NxeEditorEvent, NxeEditorEventKind, NxeExpr, NxeGridDefaultOptions, NxeMessageKey, NxeMessages, NxeMessagesConfig, NxePickerDefaultOptions, NxeValidatedEvent, NxeValidationGroupMember, NxeValidationGroupScope, NxeValidationResult, NxeValidationTarget, NxeValueChangedEvent };