@angular-bootstrap/ngbootstrap 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 2.2.0 - 2026-09-16
+
+### Added
+
+- Five standalone, provider-independent AI controls: Prompt Box, AI Chat, Inline AI Prompt, AI Prompt workspace, and Smart Paste. Exported from the package root.
+- Typed request, response, feedback, and reviewed-field events; application-owned streaming, cancellation, errors, and persistence.
+- Shared `--ngb-*` theme tokens, Bootstrap defaults, optional Material/Tailwind variable mappings, and named palettes.
+- Optional Tailwind v4 utility preset and token/theme integration documentation.
+
+### Changed
+
+- DataGrid consumes shared tokens and preserves theme values in portaled filter panels.
+- Shared theme coverage for pagination/pager, stepper, splitter, tree, typeahead, chips, and drag/drop styles and JSON preview.
+- AI controls provide keyboard instructions, busy-state focus continuity, expanded-panel relationships, live status announcements, and keyboard-focusable review regions.
+- Release validation checks AI exports, theme assets, and optional Tailwind integration packaging.
+- Patched vulnerable transitive build/test dependencies and synchronized the optional Tailwind peer in the lockfile.
+
+### Compatibility
+
+- Bootstrap remains the default; existing DataGrid theme selection remains supported.
+- Angular peer range remains `>=21.0.0 <23.0.0`. No AI provider or Angular Material dependency.
+- Tailwind is an optional peer, required only when compiling the utility integration.
+- AI output is plain text. Attachments, voice, Markdown rendering, AI Grid features, and WebMCP are outside this release.
+
+## 2.1.2 - 2026-07-27
+
+### Fixed
+
+- Removed an unused standalone directive import that created a circular DataGrid dependency and caused the published FESM bundle to throw `Cannot access 'Datagrid' before initialization` in Jest and other direct bundle-loading environments.
+
+### Changed
+
+- Extended release package verification to import the built FESM bundle and confirm that `Datagrid` and `NgbGridHighlightDirective` initialize and remain publicly exported.
+
+### Compatibility
+
+- No public component APIs, selectors, inputs, outputs, or Angular peer ranges changed.
+
 ## 2.1.1 - 2026-07-27
 
 ### Security

package/README.md

@@ -12,6 +12,7 @@ Angular UI for data-heavy apps, with a focus on DataGrid depth, Angular-native F
 - Splitter
 - Stepper
 - Chips
+- AI UI: Prompt Box, Chat, draft workspace, inline edits, and reviewed Smart Paste
 - Drag and drop
 - Angular-native Form Builder workflows
 
@@ -23,6 +24,9 @@ Those projects focus mainly on Bootstrap components for Angular. `@angular-boots
 
 ## Requirements
 
+For shared Bootstrap, Material, and Tailwind themes, palette swatches,
+installation, the optional Tailwind v4 utility preset, and CSS overrides, see the [theme reference and audit](THEMING.md).
+
 - Angular `>=21.0.0 <23.0.0`
 - RxJS `^7.8.0`
 - Bootstrap CSS in the consuming app
@@ -102,8 +106,13 @@ export class UsersGridComponent {
 
 ```bash
 pnpm install
+pnpm lint
 pnpm test
 pnpm build
+pnpm release:verify
+pnpm security:audit
 ```
 
 Build output is written to `dist/`.
+
+For provider-independent assistant controls and request lifecycle guidance, see the [AI UI reference](src/ai/README.md).

package/RELEASE_NOTES.md

@@ -1,26 +1,44 @@
-# @angular-bootstrap/ngbootstrap 2.1.1
-
-This patch release updates the library development and release dependency graph to patched compatible versions. It does not change the public component API or introduce breaking behavior.
-
-## Security
-
-- Updated Angular 22, ng-packagr, Jest, ESLint, TypeScript tooling, and affected transitive dependencies.
-- Added narrowly scoped Jest dependency overrides for patched glob and brace-expansion paths.
-- Refreshed the pnpm lockfile so the complete library dependency graph reports no known vulnerabilities.
-
-## Changed
-
-- The security audit now includes build and test tooling in addition to published runtime dependencies.
-- The audit command explicitly isolates this public library from a parent pnpm workspace when the repository is developed inside the private docs workspace.
-
-## Verification
-
-- Security audit: no known vulnerabilities.
-- Lint: passed.
-- Jest: 27 suites and 319 tests passed.
-- Angular package build and release package validation: passed.
+# @angular-bootstrap/ngbootstrap 2.2.0
+
+This minor release adds provider-independent AI UI components and a shared
+CSS-token theme layer for Angular applications using Bootstrap 5.
+
+## Added
+
+- Prompt Box, AI Chat, Inline AI Prompt, AI Prompt workspace, and Smart Paste,
+  exported from the package root with typed messages and events.
+- Original task, conversation, contextual editing, draft-review, and field-review
+  workflows. Applications own model requests, streaming, cancellation, and storage.
+- Shared `--ngb-*` tokens, Bootstrap defaults, Material/Tailwind variable bridges,
+  palette presets, and optional Tailwind v4 utility integration.
+
+## Improved
+
+- DataGrid theme selection, token consumption, swatches, and portaled filter menus.
+- Shared theming across pager/pagination, stepper, splitter, tree, typeahead,
+  chips, drag/drop styling, and JSON preview.
+- AI keyboard instructions, stable Send/Stop controls, read-only busy inputs,
+  expanded-panel relationships, focus restoration, live announcements, and
+  keyboard-focusable draft review.
+- Package validation for AI exports and theme assets; patched transitive tooling
+  dependencies and synchronized optional-peer lockfile metadata.
+
+## Validation and limits
+
+- 414 library tests, including 42 AI tests; lint, package build, and package checks.
+- Tarball consumer template compilation on Angular 21 and Angular 22.
+- Browser keyboard checks and desktop/mobile theme checks.
+- Audit passes the high-severity threshold. Three moderate advisories remain in
+  the Angular 22.0.8 development dependencies; Angular is a consumer peer, not
+  bundled into the library runtime.
+- Manual VoiceOver/NVDA testing has not been performed. Accessibility support is
+  not a WCAG certification.
 
 ## Compatibility
 
-- Angular peer support remains `>=21.0.0 <23.0.0`.
-- No public DataGrid, drag-and-drop, Form Builder, or component APIs changed in this release.
+Bootstrap remains the default. Angular peers remain `>=21.0.0 <23.0.0`.
+Angular Material and AI provider SDKs are not dependencies. Tailwind is optional.
+AI responses render plain text; Markdown, attachments, voice, AI Grid features,
+and WebMCP are not included.
+
+See `THEMING.md` and `src/ai/README.md` for setup and behavior details.

package/THEMING.md

@@ -0,0 +1,271 @@
+# Shared component themes
+
+## Audit and compatibility
+
+DataGrid already had a real token layer before scoped themes were added:
+82 distinct `--dg-*` names across its styles, covering surfaces, text, borders,
+status colors, selection, hover, focus, shadows, radii, cell/header padding,
+control sizing, typography, and pagination. `_datagrid-tokens.scss` supplied
+Bootstrap mappings and named Bootstrap, Material, and Tailwind palettes.
+The `theme` input defaults to `bootstrap` and writes `data-theme` on the grid.
+
+The gap was not a missing design system. There were no shared `--ngb-*` visual
+tokens, no `data-ngb-theme` wrapper support, and the Material palettes were
+fixed values rather than Angular Material system-variable mappings. Floating
+filter menus copied only the named theme when moving to `document.body`, so
+ancestor-scoped values would have been lost.
+
+| Audit area | Finding before this change |
+| --- | --- |
+| `--ngb-*` in SCSS/CSS | Only the stepper animation-duration hook; no shared visual token layer |
+| Direct `--bs-*` use in DataGrid | 68 references, almost all in the Bootstrap token mixin; one overlay control-radius rule |
+| Hardcoded colors and shadows | Primarily fallback values and named palettes; a grouping error tint also mixed with hardcoded white |
+| Radius | Most uses tokenized; some filter controls used `0.375rem`; pill/handle shapes intentionally use fixed radii |
+| Spacing and fonts | Cell/header padding and font sizes tokenized; many local gaps, button paddings, and small labels remain fixed; font family inherited |
+| Other components | Stepper, drag-drop CSS, pagination inline styles, and JSON preview still reference Bootstrap directly |
+
+This change adds a small public layer above `--dg-*`; it does not replace the
+existing DataGrid palettes. Shared tokens now also cover Stepper, Splitter, Tree, Typeahead, Chips, Pager, pagination, drag/drop feedback, and JSON preview. Bootstrap markup and base CSS
+remain part of the library's styling requirements. Material theming is a token
+bridge, not an implementation of Angular Material components.
+
+## Usage
+
+Keep Bootstrap 5 CSS installed. Load the shared theme entry once in application
+global styles, after Bootstrap, including when using individual component entry points:
+
+```scss
+@use 'sass:meta';
+@import 'bootstrap/dist/css/bootstrap.min.css';
+@include meta.load-css('@angular-bootstrap/ngbootstrap/src/styles/themes');
+```
+
+`src/styles/themes.scss` is shipped as a package asset. DataGrid also includes
+the Bootstrap and Material mappings for compatibility with existing grid-only consumers. No Angular
+Material or Tailwind dependency is required.
+
+```html
+<!-- Bootstrap remains the default. -->
+<ngb-datagrid [columns]="columns" [data]="rows" />
+
+<!-- Multiple themes can coexist on the same page. -->
+<div data-ngb-theme="material">
+  <ngb-datagrid [columns]="columns" [data]="rows" />
+
+  <div data-ngb-theme="bootstrap">
+    <ngb-datagrid [columns]="columns" [data]="rows" />
+  </div>
+</div>
+```
+
+For scoped themes, leave the grid's `theme` input at `bootstrap` (its default).
+Existing explicit named palettes, including `[theme]="'material'"`, remain
+compatible and retain their palette overrides; that input is not the new
+Angular Material bridge. Prefer the wrapper for Material system-variable use.
+
+The nearest theme wrapper wins. Set `--ngb-*` overrides on that wrapper or on
+the grid host. Existing `--dg-*` overrides directly on `.ngb-grid` remain valid.
+
+```css
+.orders[data-ngb-theme="material"] {
+  --ngb-density-row-height: 52px;
+  --ngb-radius-md: 8px;
+}
+```
+
+Bootstrap defaults are fallback chains evaluated on the grid, not aliases
+installed globally on `:root`. This preserves local `--bs-*` overrides,
+`data-bs-theme` scopes, and existing inherited fonts. An explicit Bootstrap
+wrapper defines the same public token names so it can reset a nested Material
+scope. For a scoped dark Bootstrap theme, put `data-bs-theme="dark"` on that
+wrapper (or above it).
+
+## Public token reference
+
+| `--ngb-` suffix | Bootstrap mapping / fallback | Material mapping / fallback |
+| --- | --- | --- |
+| `primary` | `--bs-primary` / `#0d6efd` | `--mat-sys-primary` / `#6750a4` |
+| `on-primary` | White | `--mat-sys-on-primary` / white |
+| `surface` | `--bs-body-bg` / white | `--mat-sys-surface` / `#fffbfe` |
+| `surface-container` | `--bs-tertiary-bg` / `#f8f9fa` | `--mat-sys-surface-container` / `#f3edf7` |
+| `surface-variant` | `--bs-secondary-bg` / `#e9ecef` | `--mat-sys-surface-container-high` / `#ece6f0` |
+| `on-surface` | `--bs-body-color` / `#212529` | `--mat-sys-on-surface` / `#1d1b20` |
+| `on-surface-variant` | `--bs-secondary-color` / `#6c757d` | `--mat-sys-on-surface-variant` / `#49454f` |
+| `border-color` | `--bs-border-color` / `#dee2e6` | `--mat-sys-outline-variant` / `#cac4d0` |
+| `primary-hover` | `--bs-link-hover-color` / `#0a58ca` | Primary mixed with 12% on-surface |
+| `primary-container` | `--bs-primary-bg-subtle` / `#cfe2ff` | `--mat-sys-primary-container` / `#eaddff` |
+| `focus-ring` | `--bs-focus-ring-color` / translucent blue | `--mat-sys-primary` / `#6750a4` |
+| `radius-sm`, `radius-md`, `radius-lg` | Bootstrap radius variables / `0.25`, `0.375`, `0.5rem` | `4`, `12`, `16px` |
+| `font-family` | `--bs-body-font-family` / system sans-serif | `--mat-sys-body-medium-font` / Roboto, Arial, sans-serif |
+| `font-size-sm` | Existing grid cell size `0.84rem` | `--mat-sys-body-medium-size` / `0.875rem` |
+| `density-row-height` | Explicit wrapper: `40px`; unscoped: existing automatic height | `48px` |
+| `elevation-1`, `elevation-2` | Bootstrap small/regular shadows | `--mat-sys-level1`, `--mat-sys-level2` / small menu/card shadows |
+| `disabled-opacity` | Existing `0.45` | `0.38` |
+| `hover-bg` | `--bs-tertiary-bg` / `#f8f9fa` | Surface mixed with 8% on-surface |
+| `selected-bg` | `--bs-primary-bg-subtle` / `#cfe2ff` | `--mat-sys-secondary-container` / `#e8def8` |
+
+Row height is a minimum requested table-cell height; content and padding can
+make rows taller. Existing compact-density options still control padding.
+
+Angular Material system variables must be available on the wrapper or an
+ancestor. If absent, all mappings have standalone light-theme fallbacks. No
+font is downloaded. For Material dark mode, supply a dark set of system
+variables; Bootstrap dark mode alone does not create a Material dark palette.
+See Angular Material's [custom component theming guide](https://github.com/angular/components/blob/main/guides/theming-your-components.md)
+for the supported system color, typography, and elevation variables.
+
+## DataGrid integration
+
+`--dg-*` remains the component-specific layer. Its Bootstrap mixin now resolves
+shared colors, surfaces, borders, radii, shadows, focus, hover, selection, and
+pager styling through `--ngb-*` before existing Bootstrap fallbacks. DataGrid
+also consumes shared font, row-height, disabled-opacity, and control-radius
+tokens. Portaled filter menus snapshot resolved grid tokens when opened, so
+their styling survives moving outside the theme wrapper. Close and reopen an
+open filter menu after changing its ancestor theme.
+
+Existing named palettes and component-specific semantic tokens remain available
+through `--dg-*`. Shared success and danger colors feed the Bootstrap mapping;
+other specialized grid status surfaces remain component tokens. Fixed layout
+gaps, icons, and pill shapes remain component details.
+
+
+## Families and swatches
+
+Every value below works on `data-ngb-theme` for all participating components:
+
+| Family | Wrapper value | Palette |
+| --- | --- | --- |
+| Bootstrap | `bootstrap` | Classic, maps local Bootstrap variables |
+| Bootstrap | `bootstrap-main` | Ocean |
+| Bootstrap | `bootstrap-main-dark` | Midnight, dark |
+| Bootstrap | `bootstrap-nordic` | Aqua Rose |
+| Bootstrap | `bootstrap-urban` | Clay |
+| Bootstrap | `bootstrap-vintage` | Sage |
+| Material | `material` | Angular Material system-variable mapping |
+| Material | `material-main` | Orchid |
+| Material | `material-indigo` | Indigo |
+| Material | `material-deep-purple` | Plum |
+| Tailwind | `tailwind` | Tailwind v4 system-variable mapping |
+| Tailwind | `tailwind-main` | Sky |
+| Tailwind | `tailwind-slate` | Graphite |
+| Tailwind | `tailwind-emerald` | Mint |
+
+Named swatches have fixed palettes and reset every shared token for nested
+scopes. They share the grid presets' primary and surface colors; grid-only
+striping, density, and detailed pager settings remain with the grid's `theme`
+input. Material and Tailwind family mappings read external system variables;
+their named swatches do not.
+
+Additional shared tokens:
+
+| Token | Purpose |
+| --- | --- |
+| `--ngb-success`, `--ngb-on-success` | Completion fill and text; Bootstrap success, Material fallback green, Tailwind green-700 |
+| `--ngb-danger`, `--ngb-on-danger` | Error fill and text; Bootstrap danger, Material error, Tailwind red-700 |
+| `--ngb-select-icon` | Select arrow CSS image; Midnight and Bootstrap dark use a light arrow. Override for custom dark Material/Tailwind surfaces. |
+| `--ngb-space-1` through `--ngb-space-4` | Selected gaps and padding; 0.25, 0.5, 0.75, 1rem; Tailwind maps spacing multiples |
+
+The Tailwind mapping reads `--color-blue-*`, `--color-slate-*`, `--color-white`,
+`--font-sans`, `--text-sm`, `--radius-*`, `--shadow-*`, and `--spacing` with safe
+fallbacks. It does not install Tailwind or remove the Bootstrap requirement.
+For Tailwind v4, use a separate CSS pipeline; omit Preflight when Bootstrap
+supplies base styles and prefix utilities to avoid class collisions. Prefixed
+variables need explicit mappings, such as
+`--ngb-primary: var(--tw-color-indigo-600, #4f46e5)` on the wrapper.
+Tailwind v3 applications can define CSS variables manually. See the official
+[Tailwind Preflight](https://tailwindcss.com/docs/preflight) and
+[Sass compatibility](https://tailwindcss.com/docs/compatibility) guides.
+
+## Component boundaries
+
+The AI UI entry point (Prompt Box, Chat, AI Prompt, Inline AI Prompt, and
+Smart Paste) also consumes the shared tokens for controls, text, surfaces,
+focus, error states, spacing, and corners. Load the global theme stylesheet
+when using this entry point independently.
+
+
+- Stepper: indicators, action buttons, error text, focus and selected spacing.
+  Its explicit `material` and `tailwind` theme inputs create a local mapping;
+  the default input inherits the nearest wrapper.
+- Splitter: separator, handle and keyboard focus. Explicit color inputs win.
+- Tree: text, buttons, checkboxes and focus. Projected/application content is unchanged.
+- Typeahead: controls, suggestions, selection, focus, disabled state, menu elevation.
+- Chips: fill, text, removal button and disabled opacity; pill shape is retained.
+- Pager/pagination: controls and labels; nested DataGrid `--dg-*` overrides retain priority.
+- Drag/drop: global list, compatible/denied hover and placeholder feedback.
+  JSON preview uses shared surfaces and spacing, with its monospace font retained.
+
+No theme selector targets arbitrary application buttons. The old optional
+`styles.css` drag/drop entry no longer contains a global `table button.btn` rule.
+Projected templates, chart series, and the application-built Form Builder
+canvas are application-owned. They can use the same shared variables explicitly.
+The shared themes do not alter component event contracts or keyboard behavior.
+
+
+## Optional Tailwind v4 utility preset
+
+There are two integration directions:
+
+- **ngbootstrap → Tailwind:** the optional preset exposes shared tokens through
+  utilities for application layouts and projected content.
+- **Tailwind → ngbootstrap:** the `tailwind` wrapper or explicit `--ngb-*`
+  overrides read an application's existing Tailwind design variables.
+
+To generate utilities, install and configure Tailwind v4 in the consuming app.
+Tailwind is an optional peer dependency; using built-in palettes does not require
+it. The preset is a packaged CSS asset, not a JavaScript plugin. Keep Bootstrap
+CSS and the global library `themes.scss` entry loaded separately.
+
+```css
+/* Separate CSS entry processed by Tailwind, not Sass. */
+@layer theme, base, components, utilities;
+@import 'tailwindcss/theme.css' layer(theme) prefix(tw);
+@import 'tailwindcss/utilities.css' layer(utilities) prefix(tw);
+@import '@angular-bootstrap/ngbootstrap/styles/tailwind.css';
+```
+
+This setup omits Preflight because Bootstrap supplies base styles. Example:
+
+```html
+<section data-ngb-theme="material-main"
+  class="tw:bg-ngb-surface tw:text-ngb-on-surface tw:rounded-ngb-md tw:p-ngb-4">
+  <ngb-tree [nodes]="folders" />
+</section>
+```
+
+Without `prefix(tw)`, omit `tw:` from class names. With the prefix, variants
+come after it, for example `tw:hover:bg-ngb-hover`. Keep literal utility names
+in source files scanned by the consuming Tailwind build.
+
+| Category | Unprefixed examples |
+| --- | --- |
+| Colors | `bg-ngb-primary`, `text-ngb-on-primary`, `bg-ngb-surface`, `text-ngb-on-surface`, `border-ngb-border` |
+| Interaction | `hover:bg-ngb-hover`, `bg-ngb-selected`, `focus:outline-ngb-focus` |
+| Status | `bg-ngb-success`, `text-ngb-on-success`, `bg-ngb-danger`, `text-ngb-on-danger` |
+| Radius | `rounded-ngb-sm`, `rounded-ngb-md`, `rounded-ngb-lg` |
+| Typography | `font-ngb`, `text-ngb-sm` |
+| Spacing | `p-ngb-1` through `p-ngb-4`, `gap-ngb-2`, `min-h-ngb-row` |
+| Elevation | `shadow-ngb-1`, `shadow-ngb-2` |
+
+Use a theme wrapper with this preset, including for Bootstrap defaults; unscoped
+components can use fallback colors without defining inherited shared tokens.
+`@theme inline` makes generated utilities reference `--ngb-*` directly at the
+styled element, preserving nested theme scopes and live token overrides.
+The preset defines only namespaced aliases. It does not replace Tailwind's
+standard variables, preventing cycles with the reverse Tailwind mapping.
+Do not combine conflicting Bootstrap and Tailwind utility classes on an element.
+
+Verify the optional integration with an independently installed Tailwind v4:
+
+```sh
+node scripts/verify-tailwind-preset.mjs /path/to/tailwind-project
+```
+
+## Naming and scope
+
+Built-in palettes supply predefined shared visual values. Framework integrations
+connect those values to external variables or utility classes. Full component
+themes would additionally implement an entire design system's component metrics,
+structure, and effects. The current library retains Bootstrap-based structures;
+its Material palettes and variable mapping are not a full Material 3 implementation.