ux4g-components-web 1.4.1 → 1.5.0

package/README.md

@@ -1071,6 +1071,82 @@ UX4G provides built-in focus ring styles for keyboard accessibility. Focus rings
 
 ---
 
+## DOM Generators (Advanced)
+
+The `./dom-generators` export provides framework-agnostic functions that produce complete UX4G-compliant DOM structure descriptors (`NodeDescriptor` trees). These are used internally by React and Angular Native Wrappers, but are also available for:
+
+- **Framework authors** building wrappers for Vue, Svelte, Solid, or other frameworks
+- **Testing** — verify generated DOM structure without rendering in a browser
+- **Server-side rendering** — produce HTML from NodeDescriptor trees in Node.js
+- **Custom integrations** — any scenario where you need the complete UX4G markup structure as data
+
+### Import
+
+```ts
+import { generateDropdownDOM, generateAccordionDOM, generateTabsDOM } from 'ux4g-components-web/dom-generators';
+```
+
+### Usage Example
+
+```ts
+import { generateDropdownDOM } from 'ux4g-components-web/dom-generators';
+
+const descriptor = generateDropdownDOM({
+  options: [
+    { label: 'Option 1', value: '1' },
+    { label: 'Option 2', value: '2' },
+    { label: 'Option 3', value: '3', disabled: true },
+  ],
+  value: '1',
+  placeholder: 'Select...',
+  size: 'md',
+  state: 'default',
+});
+
+// descriptor is a NodeDescriptor tree:
+// { tag: 'div', props: { className: '...', ... }, children: [...] }
+```
+
+### Available Generator Functions
+
+| Function | Component |
+|---|---|
+| `generateDropdownDOM()` | Dropdown |
+| `generateAccordionDOM()` | Accordion |
+| `generateTabsDOM()` | Tabs |
+| `generateModalDOM()` | Modal |
+| `generateCarouselDOM()` | Carousel |
+| `generateDatePickerDOM()` | Date Picker |
+| `generateTimePickerDOM()` | Time Picker |
+| `generateDrawerDOM()` | Drawer |
+| `generateComboboxDOM()` | Combobox |
+| `generateSearchDOM()` | Search |
+| `generateOtpDOM()` | OTP Input |
+| `generateProgressDOM()` | Progress Indicator |
+| `generateFileUploadDOM()` | File Upload |
+| `generateTableDOM()` | Table |
+| `generateStepperDOM()` | Stepper |
+| `generatePopoverDOM()` | Popover |
+| `generateTooltipDOM()` | Tooltip |
+| `generateAvatarDOM()` | Avatar |
+| `generateChipDOM()` | Chip |
+
+### NodeDescriptor Type
+
+```ts
+interface NodeDescriptor {
+  tag: string;
+  props: Record<string, string | boolean | number | undefined>;
+  children: (NodeDescriptor | string)[];
+}
+```
+
+Each function returns a `NodeDescriptor` tree that includes all CSS classes, `data-ux4g-*` attributes for Runtime JS compatibility, and ARIA attributes for accessibility. Convert the tree to actual DOM using your framework's element creation API (e.g., `React.createElement`, Angular `Renderer2`, or `document.createElement`).
+
+> **Note:** DOM Generators are pure functions with no framework dependencies. They import Class Builder functions from `./types` internally. Invalid props throw a `DOMGeneratorValidationError` with a descriptive message.
+
+---
+
 ## Related Packages
 
 - [`ux4g-components-react`](https://www.npmjs.com/package/ux4g-components-react) — React wrapper components

package/dist/__tests__/css-bundle.integration.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Integration tests for CSS bundle
+ * Validates: Requirements 2.7, 2.9
+ *
+ * These tests verify that the built styles/ux4g.css contains the expected
+ * selectors for dark theme support and button disabled states.
+ *
+ * NOTE: The CSS bundle is currently built from placeholder files, so these
+ * tests will fail until real CSS is in place — that is expected.
+ */
+export {};