ux4g-components-angular 1.4.1 → 1.5.0

package/dist/tooltip/README.md

@@ -1397,6 +1397,140 @@ Full list: `accessibility-bar`, `accordion`, `alert`, `avatar`, `badge`, `breadc
 
 ---
 
+## Native Wrappers
+
+In addition to the default thin wrappers documented above, this package provides **Native Wrappers** — Angular components that internally generate the complete UX4G-compliant DOM structure. With Native Wrappers, you declare a single element with input bindings and get a fully rendered, accessible, interactive component without writing any HTML markup.
+
+### Architecture Decision
+
+> **Thin Wrappers are the default export. Native Wrappers are opt-in via `/native/` sub-paths.** This decision shall not be reversed without a major version bump.
+
+- Existing thin wrapper imports (e.g., `ux4g-components-angular/dropdown`) remain unchanged
+- Native Wrappers use the `/native/` sub-path convention (e.g., `ux4g-components-angular/native/dropdown`)
+- Both can coexist in the same application without conflicts
+
+### Import Convention
+
+```ts
+// Thin Wrapper (default — unchanged)
+import { UX4GDropdownModule } from 'ux4g-components-angular/dropdown';
+
+// Native Wrapper (opt-in)
+import { UX4GNativeDropdownComponent } from 'ux4g-components-angular/native/dropdown';
+```
+
+### Usage Example
+
+```ts
+// app.component.ts
+import { Component } from '@angular/core';
+import { UX4GNativeDropdownComponent } from 'ux4g-components-angular/native/dropdown';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [UX4GNativeDropdownComponent],
+  template: `
+    <ux4g-native-dropdown
+      [options]="options"
+      [(ngModel)]="selected"
+      placeholder="Select..."
+      size="md"
+    ></ux4g-native-dropdown>
+  `,
+})
+export class AppComponent {
+  options = [
+    { label: 'Option 1', value: '1' },
+    { label: 'Option 2', value: '2' },
+    { label: 'Option 3', value: '3', disabled: true },
+  ];
+  selected = '1';
+}
+```
+
+Compare this to the thin wrapper approach, which requires manual HTML structure:
+
+```html
+<!-- Thin wrapper — consumer provides all HTML structure -->
+<ux4g-dropdown type="selection" mode="single" size="md" state="default">
+  <ux4g-dropdown-item value="1">Option 1</ux4g-dropdown-item>
+  <ux4g-dropdown-item value="2">Option 2</ux4g-dropdown-item>
+  <ux4g-dropdown-item value="3">Option 3</ux4g-dropdown-item>
+</ux4g-dropdown>
+```
+
+### Available Native Wrapper Components (19)
+
+| Import Path | Component |
+|---|---|
+| `ux4g-components-angular/native/dropdown` | Dropdown |
+| `ux4g-components-angular/native/accordion` | Accordion |
+| `ux4g-components-angular/native/tabs` | Tabs |
+| `ux4g-components-angular/native/modal` | Modal |
+| `ux4g-components-angular/native/carousel` | Carousel |
+| `ux4g-components-angular/native/date-picker` | Date Picker |
+| `ux4g-components-angular/native/time-picker` | Time Picker |
+| `ux4g-components-angular/native/drawer` | Drawer |
+| `ux4g-components-angular/native/combobox` | Combobox |
+| `ux4g-components-angular/native/search` | Search |
+| `ux4g-components-angular/native/otp` | OTP Input |
+| `ux4g-components-angular/native/progress` | Progress Indicator |
+| `ux4g-components-angular/native/file-upload` | File Upload |
+| `ux4g-components-angular/native/table` | Table |
+| `ux4g-components-angular/native/stepper` | Stepper |
+| `ux4g-components-angular/native/popover` | Popover |
+| `ux4g-components-angular/native/tooltip` | Tooltip |
+| `ux4g-components-angular/native/avatar` | Avatar |
+| `ux4g-components-angular/native/chip` | Chip |
+
+### Key Differences from Thin Wrappers
+
+| Feature | Thin Wrapper | Native Wrapper |
+|---|---|---|
+| DOM structure | Consumer provides HTML | Generated internally |
+| Data attributes | Consumer adds manually | Included automatically |
+| ARIA attributes | Consumer manages | Built-in |
+| Interactive behaviors | Consumer wires up | Works via Runtime JS auto-init |
+| Angular Forms | N/A | `ControlValueAccessor` support |
+| Standalone | NgModule-based | `standalone: true` (NgModule also available) |
+
+### Angular Forms Integration
+
+Native Wrappers for form control components implement `ControlValueAccessor`, so they work with both template-driven and reactive forms:
+
+```html
+<!-- Template-driven -->
+<ux4g-native-dropdown [options]="options" [(ngModel)]="selected"></ux4g-native-dropdown>
+
+<!-- Reactive forms -->
+<ux4g-native-dropdown [options]="options" formControlName="country"></ux4g-native-dropdown>
+```
+
+### Standalone and NgModule Support
+
+Native Wrappers are declared as `standalone: true` for Angular 17+ consumers. An NgModule is also provided for backward compatibility:
+
+```ts
+// Standalone (Angular 17+)
+import { UX4GNativeDropdownComponent } from 'ux4g-components-angular/native/dropdown';
+
+@Component({
+  standalone: true,
+  imports: [UX4GNativeDropdownComponent],
+  // ...
+})
+
+// NgModule (Angular 15–16)
+import { UX4GNativeDropdownModule } from 'ux4g-components-angular/native/dropdown';
+
+@NgModule({
+  imports: [UX4GNativeDropdownModule],
+})
+```
+
+---
+
 ## Related Packages
 
 - [`ux4g-components-web`](https://www.npmjs.com/package/ux4g-components-web) — CSS bundle and shared types (required)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ux4g-components-angular",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "type": "module",
   "description": "UX4G Design System — Angular wrapper components",
   "scripts": {
@@ -315,6 +315,120 @@
       "import": "./dist/tooltip/fesm2022/ux4g-components-angular-tooltip.mjs",
       "require": "./dist/tooltip/fesm2022/ux4g-components-angular-tooltip.mjs",
       "default": "./dist/tooltip/fesm2022/ux4g-components-angular-tooltip.mjs"
+    },
+    "./native/accordion": {
+      "types": "./dist/native/accordion/index.d.ts",
+      "import": "./dist/native/accordion/fesm2022/ux4g-components-angular-native-accordion.mjs",
+      "require": "./dist/native/accordion/fesm2022/ux4g-components-angular-native-accordion.mjs",
+      "default": "./dist/native/accordion/fesm2022/ux4g-components-angular-native-accordion.mjs"
+    },
+    "./native/tabs": {
+      "types": "./dist/native/tabs/index.d.ts",
+      "import": "./dist/native/tabs/fesm2022/ux4g-components-angular-native-tabs.mjs",
+      "require": "./dist/native/tabs/fesm2022/ux4g-components-angular-native-tabs.mjs",
+      "default": "./dist/native/tabs/fesm2022/ux4g-components-angular-native-tabs.mjs"
+    },
+    "./native/carousel": {
+      "types": "./dist/native/carousel/index.d.ts",
+      "import": "./dist/native/carousel/fesm2022/ux4g-components-angular-native-carousel.mjs",
+      "require": "./dist/native/carousel/fesm2022/ux4g-components-angular-native-carousel.mjs",
+      "default": "./dist/native/carousel/fesm2022/ux4g-components-angular-native-carousel.mjs"
+    },
+    "./native/dropdown": {
+      "types": "./dist/native/dropdown/index.d.ts",
+      "import": "./dist/native/dropdown/fesm2022/ux4g-components-angular-native-dropdown.mjs",
+      "require": "./dist/native/dropdown/fesm2022/ux4g-components-angular-native-dropdown.mjs",
+      "default": "./dist/native/dropdown/fesm2022/ux4g-components-angular-native-dropdown.mjs"
+    },
+    "./native/modal": {
+      "types": "./dist/native/modal/index.d.ts",
+      "import": "./dist/native/modal/fesm2022/ux4g-components-angular-native-modal.mjs",
+      "require": "./dist/native/modal/fesm2022/ux4g-components-angular-native-modal.mjs",
+      "default": "./dist/native/modal/fesm2022/ux4g-components-angular-native-modal.mjs"
+    },
+    "./native/drawer": {
+      "types": "./dist/native/drawer/index.d.ts",
+      "import": "./dist/native/drawer/fesm2022/ux4g-components-angular-native-drawer.mjs",
+      "require": "./dist/native/drawer/fesm2022/ux4g-components-angular-native-drawer.mjs",
+      "default": "./dist/native/drawer/fesm2022/ux4g-components-angular-native-drawer.mjs"
+    },
+    "./native/time-picker": {
+      "types": "./dist/native/time-picker/index.d.ts",
+      "import": "./dist/native/time-picker/fesm2022/ux4g-components-angular-native-time-picker.mjs",
+      "require": "./dist/native/time-picker/fesm2022/ux4g-components-angular-native-time-picker.mjs",
+      "default": "./dist/native/time-picker/fesm2022/ux4g-components-angular-native-time-picker.mjs"
+    },
+    "./native/combobox": {
+      "types": "./dist/native/combobox/index.d.ts",
+      "import": "./dist/native/combobox/fesm2022/ux4g-components-angular-native-combobox.mjs",
+      "require": "./dist/native/combobox/fesm2022/ux4g-components-angular-native-combobox.mjs",
+      "default": "./dist/native/combobox/fesm2022/ux4g-components-angular-native-combobox.mjs"
+    },
+    "./native/date-picker": {
+      "types": "./dist/native/date-picker/index.d.ts",
+      "import": "./dist/native/date-picker/fesm2022/ux4g-components-angular-native-date-picker.mjs",
+      "require": "./dist/native/date-picker/fesm2022/ux4g-components-angular-native-date-picker.mjs",
+      "default": "./dist/native/date-picker/fesm2022/ux4g-components-angular-native-date-picker.mjs"
+    },
+    "./native/search": {
+      "types": "./dist/native/search/index.d.ts",
+      "import": "./dist/native/search/fesm2022/ux4g-components-angular-native-search.mjs",
+      "require": "./dist/native/search/fesm2022/ux4g-components-angular-native-search.mjs",
+      "default": "./dist/native/search/fesm2022/ux4g-components-angular-native-search.mjs"
+    },
+    "./native/otp": {
+      "types": "./dist/native/otp/index.d.ts",
+      "import": "./dist/native/otp/fesm2022/ux4g-components-angular-native-otp.mjs",
+      "require": "./dist/native/otp/fesm2022/ux4g-components-angular-native-otp.mjs",
+      "default": "./dist/native/otp/fesm2022/ux4g-components-angular-native-otp.mjs"
+    },
+    "./native/table": {
+      "types": "./dist/native/table/index.d.ts",
+      "import": "./dist/native/table/fesm2022/ux4g-components-angular-native-table.mjs",
+      "require": "./dist/native/table/fesm2022/ux4g-components-angular-native-table.mjs",
+      "default": "./dist/native/table/fesm2022/ux4g-components-angular-native-table.mjs"
+    },
+    "./native/progress": {
+      "types": "./dist/native/progress/index.d.ts",
+      "import": "./dist/native/progress/fesm2022/ux4g-components-angular-native-progress.mjs",
+      "require": "./dist/native/progress/fesm2022/ux4g-components-angular-native-progress.mjs",
+      "default": "./dist/native/progress/fesm2022/ux4g-components-angular-native-progress.mjs"
+    },
+    "./native/stepper": {
+      "types": "./dist/native/stepper/index.d.ts",
+      "import": "./dist/native/stepper/fesm2022/ux4g-components-angular-native-stepper.mjs",
+      "require": "./dist/native/stepper/fesm2022/ux4g-components-angular-native-stepper.mjs",
+      "default": "./dist/native/stepper/fesm2022/ux4g-components-angular-native-stepper.mjs"
+    },
+    "./native/file-upload": {
+      "types": "./dist/native/file-upload/index.d.ts",
+      "import": "./dist/native/file-upload/fesm2022/ux4g-components-angular-native-file-upload.mjs",
+      "require": "./dist/native/file-upload/fesm2022/ux4g-components-angular-native-file-upload.mjs",
+      "default": "./dist/native/file-upload/fesm2022/ux4g-components-angular-native-file-upload.mjs"
+    },
+    "./native/popover": {
+      "types": "./dist/native/popover/index.d.ts",
+      "import": "./dist/native/popover/fesm2022/ux4g-components-angular-native-popover.mjs",
+      "require": "./dist/native/popover/fesm2022/ux4g-components-angular-native-popover.mjs",
+      "default": "./dist/native/popover/fesm2022/ux4g-components-angular-native-popover.mjs"
+    },
+    "./native/tooltip": {
+      "types": "./dist/native/tooltip/index.d.ts",
+      "import": "./dist/native/tooltip/fesm2022/ux4g-components-angular-native-tooltip.mjs",
+      "require": "./dist/native/tooltip/fesm2022/ux4g-components-angular-native-tooltip.mjs",
+      "default": "./dist/native/tooltip/fesm2022/ux4g-components-angular-native-tooltip.mjs"
+    },
+    "./native/avatar": {
+      "types": "./dist/native/avatar/index.d.ts",
+      "import": "./dist/native/avatar/fesm2022/ux4g-components-angular-native-avatar.mjs",
+      "require": "./dist/native/avatar/fesm2022/ux4g-components-angular-native-avatar.mjs",
+      "default": "./dist/native/avatar/fesm2022/ux4g-components-angular-native-avatar.mjs"
+    },
+    "./native/chip": {
+      "types": "./dist/native/chip/index.d.ts",
+      "import": "./dist/native/chip/fesm2022/ux4g-components-angular-native-chip.mjs",
+      "require": "./dist/native/chip/fesm2022/ux4g-components-angular-native-chip.mjs",
+      "default": "./dist/native/chip/fesm2022/ux4g-components-angular-native-chip.mjs"
     }
   },
   "typesVersions": {
@@ -471,6 +585,63 @@
       ],
       "tooltip": [
         "./dist/tooltip/index.d.ts"
+      ],
+      "native/accordion": [
+        "./dist/native/accordion/index.d.ts"
+      ],
+      "native/tabs": [
+        "./dist/native/tabs/index.d.ts"
+      ],
+      "native/carousel": [
+        "./dist/native/carousel/index.d.ts"
+      ],
+      "native/dropdown": [
+        "./dist/native/dropdown/index.d.ts"
+      ],
+      "native/modal": [
+        "./dist/native/modal/index.d.ts"
+      ],
+      "native/drawer": [
+        "./dist/native/drawer/index.d.ts"
+      ],
+      "native/time-picker": [
+        "./dist/native/time-picker/index.d.ts"
+      ],
+      "native/combobox": [
+        "./dist/native/combobox/index.d.ts"
+      ],
+      "native/date-picker": [
+        "./dist/native/date-picker/index.d.ts"
+      ],
+      "native/search": [
+        "./dist/native/search/index.d.ts"
+      ],
+      "native/otp": [
+        "./dist/native/otp/index.d.ts"
+      ],
+      "native/table": [
+        "./dist/native/table/index.d.ts"
+      ],
+      "native/progress": [
+        "./dist/native/progress/index.d.ts"
+      ],
+      "native/stepper": [
+        "./dist/native/stepper/index.d.ts"
+      ],
+      "native/file-upload": [
+        "./dist/native/file-upload/index.d.ts"
+      ],
+      "native/popover": [
+        "./dist/native/popover/index.d.ts"
+      ],
+      "native/tooltip": [
+        "./dist/native/tooltip/index.d.ts"
+      ],
+      "native/avatar": [
+        "./dist/native/avatar/index.d.ts"
+      ],
+      "native/chip": [
+        "./dist/native/chip/index.d.ts"
       ]
     }
   },
@@ -479,16 +650,18 @@
   ],
   "peerDependencies": {
     "@angular/common": ">=15.0.0",
-    "@angular/core": ">=15.0.0"
+    "@angular/core": ">=15.0.0",
+    "@angular/forms": ">=15.0.0"
   },
   "dependencies": {
     "@angular/compiler-cli": "^19.2.20",
-    "ux4g-components-web": "^1.4.1"
+    "ux4g-components-web": "^1.5.0"
   },
   "devDependencies": {
     "@angular/common": "^19.2.20",
     "@angular/compiler": "^19.2.20",
     "@angular/core": "^19.2.20",
+    "@angular/forms": "19.2.20",
     "@angular/platform-browser": "^19.2.20",
     "@angular/platform-browser-dynamic": "^19.2.20",
     "@types/jest": "^29.5.14",