@nexterajs/ui 0.0.2 → 0.1.0

package/README.md

@@ -1,64 +1,309 @@
-# NexteraUi
+# @nexterajs/ui
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 22.1.0.
+An Angular 22 component library that replaces DevExtreme: data grid and tree list, pivot grid, editors and pickers,
+dialogs, menus, tabs, an app shell, toasts, and a zero-dependency XLSX writer and reader. Every component is standalone,
+signal-based and OnPush, and every colour, size and string can be changed by the application: colours through
+`--nxe-ui-*` CSS custom properties, strings through a runtime-switchable message bundle (English and Indonesian ship).
 
-## Code scaffolding
+The package is split into 18 secondary entry points, so an application only bundles what it imports.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+## Install
 
 ```bash
-ng generate component component-name
+npm install @nexterajs/ui @angular/cdk @angular/animations luxon
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+| Peer dependency | Version | Needed for |
+|---|---|---|
+| `@angular/core`, `@angular/common`, `@angular/forms` | `^22.0.0` | everything |
+| `@angular/cdk` | `^22.0.0` | overlays, dialogs, menus, focus traps |
+| `@angular/animations` | `^22.0.0` | shared animation definitions |
+| `luxon` | `^3.0.0` | date box, calendar, date formats |
+| `rxjs` | `^7.8.0` | everything |
+| `@angular/router` | `^22.0.0`, **optional** | `@nexterajs/ui/shell` and `@nexterajs/ui/navigation` |
 
-```bash
-ng generate --help
+`@angular/router` is optional: an application that never imports the shell or navigation entry points does not need
+it. The package root re-exports every entry point, so an application that imports from the bare `@nexterajs/ui` does
+need it installed.
+
+## Register the styles
+
+Component look and feel is encapsulated in each component; what has to be global ships as one SCSS bundle,
+`@nexterajs/ui/styles` (`styles/index.scss`). Register it **last** in `angular.json`, under
+`projects.<app>.architect.build.options.styles` (and under `test` if your tests render components):
+
+```json
+"styles": [
+  "src/styles.scss",
+  "node_modules/@nexterajs/ui/styles/index.scss"
+]
 ```
 
-## Building
+That is all a DevExtreme-era application needs: the bundle and the component sheets carry dx.light's look themselves
+(the widget base and its `#333` text, the grid's structure, cell padding and header, the editor and dropdown chrome), so
+a copy of `dx.light.css` or an extract of it (`dx-compat.css`) can be deleted. Where an app skinned DevExtreme, it sets
+tokens (see Theming) instead of restating selectors. From SCSS, `@use '@nexterajs/ui/styles';` loads the same bundle.
 
-To build the library, run:
+Two optional sheets stay outside the bundle, because each is a port of a third-party stylesheet whose overrides depend on
+load order:
 
-```bash
-ng build nextera-ui
+| File | Required | Holds | Where in the list |
+|---|---|---|---|
+| `styles/index.scss` | always | design tokens, widget base, grid structure, editor and dropdown chrome, icons, drag and badge rules | **last** |
+| `styles/_toast.scss` | if you use `NxeToastService` (`@nexterajs/ui/notify`) | toast container, positions, colours, progress bar | **before** your own stylesheet |
+| `styles/_scrollbar.scss` | only if you use `[nxeScrollbar]` (`@nexterajs/ui/styling`) | hides the native bar, draws the rails | **before** your own stylesheet |
+
+**The bundle does not include the toast or scrollbar chrome.** Without `_toast.scss` toasts render with no fixed
+container, position or colours; without `_scrollbar.scss` an `[nxeScrollbar]` element keeps its native scrollbar and
+the rails the directive adds are unstyled. Each file is a value-for-value port of the stylesheet it replaces
+(ngx-toastr's `toastr.css`, `perfect-scrollbar.css`), so register it where that stylesheet used to sit: before your own
+stylesheet, so your overrides of the toast or rail rules (a `width` on `.toast-top-center`) still win on order.
+
+`index.scss` goes last so its component chrome lands above any reset you ship. Your token overrides do not depend on
+order (see Theming): the library declares its tokens at `:where(:root)`, which has zero specificity, so a plain
+`:root { }` block in `src/styles.scss` (or any app token file) wins wherever it sits in the list. The toast and
+scrollbar files read the same tokens, with fallbacks, so they need nothing else.
+
+## Use a component
+
+Import the standalone component from its entry point:
+
+```ts
+import { Component, signal } from '@angular/core';
+import { NxeButtonComponent, NxeTextBoxComponent } from '@nexterajs/ui/forms';
+import { NxeColumnComponent, NxeDataGridComponent } from '@nexterajs/ui/grid';
+
+@Component({
+  selector: 'app-orders',
+  imports: [NxeButtonComponent, NxeTextBoxComponent, NxeDataGridComponent, NxeColumnComponent],
+  template: `
+    <nxe-text-box [(value)]="search" placeholder="Search" />
+    <nxe-data-grid [dataSource]="orders()">
+      <nxe-column dataField="poNumber" caption="PO" />
+      <nxe-column dataField="total" caption="Total" dataType="number" />
+    </nxe-data-grid>
+    <nxe-button type="default" text="Save" (onClick)="save()" />
+  `,
+})
+export class OrdersComponent {
+  readonly search = signal('');
+  readonly orders = signal<Order[]>([]);
+  save(): void { /* … */ }
+}
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+Prefer a specific entry point over the bare `@nexterajs/ui`: it keeps the pivot engine and the XLSX writer out of your
+bundle and out of your dev-server rebuilds.
 
-### Publishing the Library
+## Theming
 
-Once the project is built, you can publish your library by following these steps:
+Override `--nxe-ui-*` custom properties from your own `:root`. No build step, no `!important`. The defaults reproduce
+DevExtreme's dx.light, so setting nothing changes nothing.
 
-1. Navigate to the `dist` directory:
+```scss
+// src/styles.scss (or an app token file it uses)
+:root {
+  --nxe-ui-font-size: 13px;
+  --nxe-ui-accent: #005caa;                   // primary buttons, focus, selection
+  --nxe-ui-button-hover-bg-primary: #004d8f;  // hover and pressed shades are literals:
+  --nxe-ui-button-active-bg-primary: #003d72; // set them whenever you set the fill
+  --nxe-ui-button-focus-ring: var(--nxe-ui-focus-ring); // opt in to a visible keyboard focus ring
+}
 
-   ```bash
-   cd dist/nextera-ui
-   ```
+// Dark theme: the library switches its values under a `.dark` class (on <html> or any ancestor).
+// Restate every token you overrode, or the library's own dark value replaces yours.
+:root.dark {
+  --nxe-ui-accent: #4da3e8;
+  --nxe-ui-button-hover-bg-primary: #7ab9e8;
+  --nxe-ui-button-active-bg-primary: #9acbee;
+}
+```
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+What to know before you theme:
 
-## Running unit tests
+- **Your `:root` beats the library, in any order.** The library's light defaults are declared at `:where(:root)` and
+  its dark values at `:where(.dark)`, both zero specificity.
+- **Restate overrides under `:root.dark`.** A token you set only in `:root` is replaced by the library's dark value as
+  soon as `.dark` is on.
+- **Set button hover and active shades explicitly.** `--nxe-ui-button-bg-{primary,success,danger}` follow
+  `--nxe-ui-accent`, `--nxe-ui-success` and `--nxe-ui-danger`, but `--nxe-ui-button-hover-bg-*` and
+  `--nxe-ui-button-active-bg-*` are fixed colours (dx's shades are not a constant mix), so a new fill keeps the old
+  hover and pressed colours until you set them too.
+- **Buttons draw no focus ring by default**, as in DevExtreme. Opt in with
+  `--nxe-ui-button-focus-ring: var(--nxe-ui-focus-ring)` (or any `box-shadow` value). Do: a keyboard user otherwise
+  cannot see which button has focus.
+- **Accessibility: override the stock danger and success buttons.** The default danger button is white text on
+  `#d9534f`, 3.96:1, which fails WCAG AA (4.5:1) for button-sized text; the default success button (white on `#5cb85c`)
+  is 2.48:1. For example:
 
-To execute unit tests with the [Vitest](https://vitest.dev/) test runner, use the following command:
+  ```scss
+  :root {
+    --nxe-ui-button-bg-danger: #b4322a;        // 6.1:1 with white
+    --nxe-ui-button-hover-bg-danger: #9a2a23;
+    --nxe-ui-button-active-bg-danger: #7a211b;
+  }
+  ```
 
-```bash
-ng test
+  Do the same for `--nxe-ui-button-bg-success` and its hover and active tokens, and restate them under `:root.dark`.
+- A `nxe-density-compact` class on an ancestor tightens control heights and padding.
+
+- **Skin the grid with tokens, not cell selectors.** `--nxe-ui-grid-cell-padding` (dx's 7px),
+  `--nxe-ui-grid-cell-vertical-align` (middle), `--nxe-ui-grid-edge-padding` (the first and last cell's outer side),
+  `--nxe-ui-grid-header-bg` and `--nxe-ui-grid-header-color` (the caption row), and `--nxe-ui-grid-indicator-scale` /
+  `--nxe-ui-grid-indicator-offset` (the sort and filter marks). Set them at `:root`, or on a subtree such as
+  `nxe-tree-list` or a card, and they reach every grid inside. The cell rules carry zero specificity, so an existing
+  app rule still wins while you move it to a token.
+
+The full list of tokens (193, in 22 groups) with light defaults, dark values and what each one colours is in
+`docs/TOKENS.md` in the nextera-library repository. It is generated from `styles/_tokens.scss`, which ships in this
+package (`node_modules/@nexterajs/ui/styles/_tokens.scss`) and carries the same list with a comment on each token.
+
+## Internationalisation
+
+Every string the library renders itself (pager, no-data text, filter operators, calendar, validation, uploader, pivot
+captions, shell and dialog labels) comes from `NxeMessageService` in `@nexterajs/ui/core`. English is the default and
+Indonesian (`id`) ships; switching the language re-renders live components in place.
+
+```ts
+import { provideNxeMessages } from '@nexterajs/ui/core';
+
+bootstrapApplication(App, {
+  providers: [
+    provideNxeMessages({
+      locale: 'id',                                   // 'en' (default) or 'id'; 'id-ID' picks 'id'
+      overrides: { 'grid.noData': 'Belum ada data' }, // kept across language switches
+      separators: true,                               // 1.234,5 under id, 1,234.5 under en
+    }),
+  ],
+});
 ```
 
-## Running end-to-end tests
+```ts
+import { inject } from '@angular/core';
+import { NxeMessageService } from '@nexterajs/ui/core';
 
-For end-to-end (e2e) testing, run:
+const messages = inject(NxeMessageService);
+messages.use('en');                                   // switch at runtime
+messages.use({ 'common.cancel': 'Annuler' }, 'fr');   // an ad hoc bundle under a locale
+messages.override({ 'grid.pager.info': 'Hal. {0}/{1}' });
+```
 
-```bash
-ng e2e
+`provideNxeMessages` also takes `bundles` (more languages; a partial bundle falls back to English) and `luxon` (default
+`true`: Luxon's default locale follows the language, so month and weekday names do too). A component input such as
+`noDataText` always wins over the bundle. To follow an app-owned language service such as Transloco, subscribe to its
+language stream with `takeUntilDestroyed()` and call `messages.use(lang)`. Form-field error messages are set with
+`provideNxeErrorMessages` from `@nexterajs/ui/forms`.
+
+## Entry points
+
+| Entry point | Holds |
+|---|---|
+| `@nexterajs/ui/core` | Message service and bundles, default-options token, form-control and config-option base classes, `nxeTemplate` |
+| `@nexterajs/ui/forms` | Button, text box, text area, number box, date box, check box, radio group, switch, OTP box, form field, scroll view |
+| `@nexterajs/ui/dropdowns` | Select box, tag box, drop-down box, list, autocomplete |
+| `@nexterajs/ui/grid` | Data grid and tree list, filter row, header filters, grouping, summaries, master-detail, remote data source, paginator, Excel export |
+| `@nexterajs/ui/pivot` | Pivot grid, its data source, field panel and chooser, chart binding, Excel export |
+| `@nexterajs/ui/display` | Tag, badge, spinner, skeleton, empty state, card, description list |
+| `@nexterajs/ui/charts` | Line, area and donut charts: SVG, light and dark palette tokens, legend, tooltip, data table alternative |
+| `@nexterajs/ui/overlay` | Dialog service, confirmation service, menu |
+| `@nexterajs/ui/navigation` | Tabs, with a router mode (needs `@angular/router`) |
+| `@nexterajs/ui/shell` | App shell, side navigation, top bar (needs `@angular/router`) |
+| `@nexterajs/ui/notify` | Toast service and toast component (register `styles/_toast.scss`) |
+| `@nexterajs/ui/tree-view` | Tree view |
+| `@nexterajs/ui/file-uploader` | File uploader |
+| `@nexterajs/ui/validation` | Validator, validation rules and group, rule evaluators |
+| `@nexterajs/ui/intl` | Date and number format engines, number separator tokens |
+| `@nexterajs/ui/excel` | Zero-dependency XLSX writer and reader, zip, `nxeSaveAs` |
+| `@nexterajs/ui/styling` | Overlay pane helper, `[nxeScrollbar]` (register `styles/_scrollbar.scss`), DevExtreme class-name compatibility |
+| `@nexterajs/ui/animations` | Shared animation definitions |
+
+## Component index
+
+Names only. Inputs, outputs, keyboard behaviour and examples are in the full documentation: the `README.md` at the root
+of the nextera-library repository.
+
+- **core**: `NxeMessageService`, `provideNxeMessages`, `NXE_MESSAGES_EN`, `NXE_MESSAGES_ID`, `NXE_DEFAULT_OPTIONS`,
+  `NxeFormControlBase`, `NxeConfigOptionBase`, `[nxeTemplate]`
+- **forms**: `nxe-button`, `nxe-text-box`, `nxe-text-area`, `nxe-number-box`, `nxe-date-box`, `nxe-check-box`,
+  `nxe-radio-group`, `nxe-switch`, `nxe-otp-box`, `nxe-form-field`, `nxe-scroll-view`, `provideNxeErrorMessages`
+- **dropdowns**: `nxe-select-box`, `nxe-tag-box`, `nxe-drop-down-box`, `nxe-list`, `nxe-autocomplete` (with
+  `[nxeAutocomplete]` and `nxe-option`), `nxe-auto-complete`
+- **grid**: `nxe-data-grid`, `nxe-tree-list`, `nxe-column`, `nxe-selection`, `nxe-paging`, `nxe-pager`,
+  `nxe-filter-row`, `nxe-header-filter`, `nxe-grouping`, `nxe-group-panel`, `nxe-summary`, `nxe-editing`,
+  `nxe-master-detail`, `nxe-scrolling`, `nxe-paginator`, `NxeRemoteDataSource`, `nxeFlattenFilter`, `nxeFilterAnd`,
+  `nxeFilterOr`, `exportDataGrid`, `exportNxeGridToExcel`
+- **pivot**: `nxe-pivot-grid`, `NxePivotDataSource`, `nxe-pivot-field-panel`, `nxe-pivot-field-chooser`, `nxe-chart`,
+  `NxeExcelExportService`
+- **display**: `nxe-tag`, `nxe-badge` (with `[nxeBadgeAnchor]`), `nxe-spinner`, `nxe-skeleton`, `nxe-empty-state`,
+  `nxe-card`, `nxe-description-list`, `nxe-description-item`
+- **overlay**: `NxeDialogService`, `NxeDialogRef`, `NxeConfirmService`, `[nxe-dialog-title]`, `[nxe-dialog-content]`,
+  `[nxe-dialog-actions]`, `nxe-menu`, `[nxeMenuTriggerFor]`, `nxe-menu-item` / `[nxe-menu-item]`, `nxe-menu-divider`
+- **navigation**: `nxe-tabs`, `nxe-tab`, `ng-template[nxeTabContent]`
+- **shell**: `nxe-shell`, `nxe-sidenav`, `nxe-topbar`, `ng-template[nxeSidenavIcon]`
+- **notify**: `NxeToastService`, `provideNxeToast`, `nxe-toast`
+- **tree-view**: `nxe-tree-view`
+- **file-uploader**: `nxe-file-uploader`
+- **validation**: `nxe-validator`, `nxe-validation-rule`, `nxe-validation-group`, `NxeValidators`
+- **intl**: `formatNumber`, `parseNumber`, `formatDisplay`, `parseDisplay`, `NXE_NUMBER_SEPARATORS`,
+  `NXE_ID_SEPARATORS`
+- **excel**: `NxeWorkbook`, `NxeWorksheet`, `readXlsxFirstSheet`, `nxeSaveAs`
+- **styling**: `[nxeScrollbar]`, `nxePane`, `provideNxeDxCompat`
+- **animations**: `nxeAnimations`, `NxeAnimationCurves`, `NxeAnimationDurations`
+
+## Consuming a local build (`file:` or `npm link`)
+
+To try an unreleased build, point the application at the built package (`npm run build:ui` in the library repository
+writes `dist/nextera-ui`):
+
+```json
+"dependencies": { "@nexterajs/ui": "file:../nextera-library/dist/nextera-ui" }
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+npm installs a `file:` directory dependency (and `npm link`) as a symlink. Followed to its real path, the library
+resolves `@angular/core` from the library repository's own `node_modules`, so the application ends up with two copies
+of Angular: `NG0203` (`inject()` called outside an injection context) at runtime, or `INPUT_SIGNAL_BRAND` type errors
+in the editor. Three settings keep the library on the application's copy:
+
+1. `angular.json`, the build target's options:
+
+   ```json
+   "build": { "options": { "preserveSymlinks": true } }
+   ```
+
+2. `tsconfig.json`, `compilerOptions`:
+
+   ```json
+   "preserveSymlinks": true
+   ```
+
+3. Unit tests with `@angular/build:unit-test` (Vitest). Vitest loads dependencies with Node's own resolver, which
+   follows the symlink regardless, so inline the package to route its imports through Vite. Turn on the runner config
+   in `angular.json`:
+
+   ```json
+   "test": { "builder": "@angular/build:unit-test", "options": { "runnerConfig": true } }
+   ```
+
+   and add `vitest-base.config.mjs` next to `angular.json` (the file `runnerConfig: true` looks for):
+
+   ```js
+   import { defineConfig } from 'vitest/config';
+
+   export default defineConfig({
+     test: {
+       server: { deps: { inline: [/@nexterajs\/ui/] } },
+     },
+   });
+   ```
+
+Remove all three when you switch back to a published version.
+
+## Browser support
+
+The browsers Angular 22 supports. The stylesheets use `color-mix()`, `:where()`, `:has()`, container queries and
+`dvh` units, which puts the floor at Chrome and Edge 111, Firefox 121 and Safari 16.4. Internet Explorer and legacy
+Edge are not supported.
 
-## Additional Resources
+## License
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+Apache-2.0. See `LICENSE` and `NOTICE` in this package.