xv-webcomponents 1.25.1 → 2.0.0-beta.28

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 crossvertise
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 crossvertise
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,129 +1,249 @@
-# @xv/webcomponents
-
-**Reusable Web Components for XV Applications**  
-This repository contains Web Components built with Stencil.js to provide a modular and reusable UI across multiple applications.
-
----
-
-## Features
-
-**Reusable Web Components** – Designed for multiple XV applications  
-**Stencil.js Powered** – Built using modern Web Component standards  
-**Shadow DOM Support** – Encapsulated styles and functionality  
-**Brand-Specific Theming** – Automatically detects and applies brand styles  
-**Framework Agnostic** – Works with Angular, React, Vue, and plain HTML  
-
----
-
-## Folder Structure
-
-```
-xv-webcomponents/
-│── src/
-│   ├── components/       # Web Component source files
-│   │   ├── button/
-│   │   │   ├── xv-button.tsx
-│   │   │   ├── xv-button.css
-│   │   │   ├── xv-button.e2e.ts
-│   │   │   ├── xv-button.spec.ts
-│   │   ├── checkbox/
-│   │   │   ├── xv-checkbox.tsx
-│   │   │   ├── xv-checkbox.css
-│   │   │   ├── xv-checkbox.e2e.ts
-│   │   │   ├── xv-checkbox.spec.ts
-│   ├── utils/            # Utility functions for components
-│── dist/                 # Compiled distribution files
-│── loader/               # Loader scripts for consuming Web Components
-│── package.json
-│── README.md
-│── stencil.config.ts     # Stencil.js configuration
-```
-
----
-
-## Installation
-
-To install the package from npm:
-```bash
-npm install xv-webcomponents
-```
-
----
-
-## Usage
-
-### **Using in an HTML Page**
-Simply include the Web Component in your HTML:
-```html
-<script type="module" src="https://cdn.yourcompany.com/xv-webcomponents/xv-webcomponents.esm.js"></script>
-<xv-button-v2 label="Click Me" variant="accent"></xv-button-v2>
-```
-
-### **Using in an Angular Project**
-First, import `CUSTOM_ELEMENTS_SCHEMA` in your module:
-```typescript
-import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-import { BrowserModule } from '@angular/platform-browser';
-
-@NgModule({
-  declarations: [],
-  imports: [BrowserModule],
-  schemas: [CUSTOM_ELEMENTS_SCHEMA]
-})
-export class AppModule {}
-```
-Now, use the Web Component in your Angular templates:
-```html
-<xv-button-v2 label="Click Me" variant="primary"></xv-button-v2>
-```
-
-### **Using in a C# Razor Page (MVC)**
-```html
-<xv-button-v2 label="Submit" variant="secondary"></xv-button-v2>
-```
-
-### **Using in Sitefinity CMS**
-Embed the Web Component inside a content block:
-```html
-<xv-button-v2 label="Learn More" variant="ghost"></xv-button-v2>
-```
-
----
-
-## 🛠 Development & Building
-
-### **1️⃣ Build the Components**
-To build all components:
-```bash
-npm run build
-```
-This generates compiled components inside the `dist/` folder.
-
-### **2️⃣ Run Local Development Server**
-To test components locally:
-```bash
-npm start
-```
-This starts a development server and watches for changes.
-
-### **3️⃣ Publish to npm**
-To publish a new version of the package:
-```bash
-npm version patch
-npm publish --access public
-```
-
----
-
-## Contributing
-
-### **Adding a New Component**
-1. Generate a new component:
-   ```bash
-   npm run generate component xv-new-component
-   ```
-2. Implement logic and styles inside `src/components/xv-new-component/`.
-3. Test the component using Jest (`.spec.ts`) and e2e tests.
-4. Run `npm run build` to generate the compiled version.
-5. Commit changes and submit a pull request.
-
+# @xv/webcomponents
+
+**Reusable Web Components for XV Applications**  
+This repository contains Web Components built with Stencil.js to provide a modular and reusable UI across multiple applications.
+
+---
+
+## Features
+
+**Reusable Web Components** – Designed for multiple XV applications  
+**Stencil.js Powered** – Built using modern Web Component standards  
+**Shadow DOM Support** – Encapsulated styles and functionality  
+**Brand-Specific Theming** – Automatically detects and applies brand styles  
+**Framework Agnostic** – Works with Angular, React, Vue, and plain HTML  
+
+---
+
+## Folder Structure
+
+```
+xv-webcomponents/
+├── src/
+│   ├── components/            # One folder per component, plus the API conventions README
+│   │   └── xv-button/
+│   │       ├── xv-button-v2.tsx
+│   │       ├── xv-button-v2.scss
+│   │       ├── xv-button-v2.e2e.ts
+│   │       └── readme.md       # generated by docs-readme
+│   ├── assets/styles/          # Shared SCSS injected into every component (mixins, breakpoints)
+│   ├── utils/                  # Shared helpers
+│   ├── global.scss             # Adopted into every shadow root — keep it minimal
+│   └── index.ts                # Public barrel
+├── scripts/
+│   ├── tag-config.js           # Tag composition and validation
+│   ├── apply-tag-config.js     # Prebuild codemod
+│   └── build-wrappers.js       # Compiles the React and Angular wrappers
+├── tags.config.json            # prefix / suffix
+├── stencil.config.ts
+└── stencil.paths.js            # Paths shared by the config and the scripts
+```
+
+---
+
+## Installation
+
+```bash
+npm install xv-webcomponents
+```
+
+Node 22 or newer is required to build this repository. Consuming the published package has no
+Node requirement.
+
+---
+
+## What the package ships
+
+| Entry point | Contents | For |
+| --- | --- | --- |
+| `xv-webcomponents` | Lazy-loading bundle and types | Script tag, CDN, anything non-bundled |
+| `xv-webcomponents/loader` | `defineCustomElements()` | Registering the lazy bundle by hand |
+| `xv-webcomponents/components/xv-button-v2` | One component and only its dependencies | Bundlers |
+| `xv-webcomponents/components` | Shared helpers only — `setTagTransformer`, `setAssetPath`, `setNonce`. **Not** the components | Runtime configuration |
+| `xv-webcomponents/react` | Compiled React wrappers (JS + `.d.ts`) | React and Next.js |
+| `xv-webcomponents/angular` | Compiled `WebComponentsModule` and component proxies | Angular |
+| `xv-webcomponents/docs.json` | Stencil docs JSON | Tooling, AI agents |
+| `xv-webcomponents/dist/custom-elements.json` | Custom Elements Manifest | Editors, catalogues |
+| `xv-webcomponents/vscode-data.json` | VS Code HTML custom data | Editor completion |
+| `xv-webcomponents/css` | Global stylesheet | Every consumer |
+
+Each `components/<tag>` module registers its element when imported
+(`auto-define-custom-elements`), so no loader call is needed. They tree-shake per component:
+`xv-button-v2` alone bundles to **80 kB** minified, two components to **83 kB**, and all 52 to
+**2.8 MB** — the single-component bundle contains `xv-button-v2` and `xv-loader-v2`, which it uses
+for its loading state, and none of the other 50.
+
+---
+
+## Usage
+
+### HTML page
+
+```html
+<script type="module" src="https://cdn.yourcompany.com/xv-webcomponents/xv-webcomponents.esm.js"></script>
+<xv-button-v2 label="Click Me" variant="accent"></xv-button-v2>
+```
+
+### Bundled application (one component)
+
+```ts
+import 'xv-webcomponents/components/xv-button-v2';
+import 'xv-webcomponents/css';
+```
+
+The barrel at `xv-webcomponents/components` carries helpers, not components — importing it gives
+you `setTagTransformer` and friends, not `XvButtonV2`. Import each component by its own path.
+
+### React / Next.js
+
+```tsx
+import { XvButtonV2 } from 'xv-webcomponents/react';
+
+<XvButtonV2 label="Click Me" variant="accent" onClick={...} />;
+```
+
+The wrappers set **properties**, not attributes, so an array arrives as an array and a `Date` as a
+live `Date` — which is the whole point, because React 18 stringifies both onto a custom element.
+`react` is an optional peer dependency; nothing else is needed. The 1.2 kB of
+`@stencil/react-output-target` the wrappers use at runtime is bundled into `dist/react/runtime.js`
+at build time, so a consumer never installs that package — it pulls `ts-morph`, 15 MB of
+build-time tooling.
+
+### Angular
+
+```typescript
+import { WebComponentsModule } from 'xv-webcomponents/angular';
+
+@NgModule({ imports: [WebComponentsModule] })
+export class FeatureModule {}
+```
+
+`WebComponentsModule` declares and exports all 52 proxies. It has to ship from here: Angular
+refuses to *declare* a component that was compiled in another library, so a consumer can only
+import the module, never assemble its own from `DIRECTIVES`.
+
+The package ships **no** `ControlValueAccessor` directives. Only one accessor may match an element
+— a second one fails at runtime with *More than one custom value accessor matches form control* —
+and the accessors an app writes itself know things the generated ones cannot, such as whether
+`xv-dropdown-v2` is in `multiple` mode. Forms wiring stays with the consumer until each component's
+event naming is settled.
+
+The proxies are compiled ahead of time in partial-Ivy mode, so they need **Angular 21 or newer** in
+the consuming app. `@angular/core`, `@angular/common`, `@angular/forms` and `rxjs` are optional peer
+dependencies — install them only for this path.
+
+### Razor / Sitefinity
+
+```html
+<xv-button-v2 label="Submit" variant="secondary"></xv-button-v2>
+```
+
+---
+
+## Tag names — prefix and suffix
+
+Every tag is composed as `{prefix}{component}{suffix}`. The defaults in `tags.config.json` are the
+canonical names, so nothing is rewritten out of the box:
+
+```json
+{
+  "prefix": "xv-",
+  "suffix": ""
+}
+```
+
+The hyphens live inside the values, so an empty suffix adds nothing and a prefix is never
+concatenated without a separator. Change either value and rebuild:
+
+```json
+{ "prefix": "acme-", "suffix": "-v2" }
+```
+
+`xv-button-v2` then becomes `acme-button-v2-v2` everywhere — the custom element registry,
+`dist/components` filenames, the Angular selectors and value accessors, the React wrappers,
+`components.d.ts`, the docs outputs and the demo page.
+
+**How it works.** Stencil requires `tag:` in `@Component` to be a string literal — a template
+literal fails the build with `tag missing in component decorator` — so the names cannot be computed.
+A prebuild step (`npm run tags`) rewrites a copy of the sources instead:
+
+- on the default config the build runs from `src/` untouched;
+- on any other config `src/` is copied to `tagged-src/` with the names rewritten, and the build
+  runs from there against a generated `tsconfig.tagged.json`. `src/` always keeps canonical names.
+
+A composed name that is not a valid custom element name (no hyphen, or not starting with a
+lowercase letter) fails the build rather than being silently rejected by the browser.
+
+Because the rename happens at build time, every output already carries the configured names —
+including the Angular selectors, which are compiled literals and cannot be changed afterwards.
+Renaming therefore means editing `tags.config.json` and rebuilding, not configuring a consumer.
+
+For the runtime case the package also re-exports `setTagTransformer` from its own bundled Stencil
+runtime. The React wrappers and the lazy loader honour it; **Angular does not**, for the same
+reason — its selectors are literals:
+
+```ts
+import { setTagTransformer } from 'xv-webcomponents';
+```
+
+Import it from here and not from `@stencil/core` — the transformer is module state inside the
+runtime bundled into this package, so a consumer's own copy sets a different one.
+
+---
+
+## 🛠 Development & Building
+
+```bash
+npm run build     # tags -> stencil build -> wrapper compile
+npm start         # dev server with watch
+npm test          # spec and e2e
+```
+
+`npm run build` runs three steps. `prebuild` clears the generated wrapper sources and applies
+`tags.config.json`; `stencil build` writes every output target; `postbuild` compiles
+`react-wrappers/` with `tsc` and `angular-wrappers/` with `ngc`. Both output targets emit
+TypeScript, and neither Next.js nor Angular compiles TypeScript out of `node_modules`.
+
+Generated and gitignored: `dist/`, `loader/`, `www/`, `react-wrappers/`, `angular-wrappers/`, and
+— only for a non-default tag config — `tagged-src/` and `tsconfig.tagged.json`.
+
+### Publishing
+
+```bash
+npm version prerelease --preid=beta
+npm publish --tag beta
+```
+
+The 2.x line publishes to the **`beta`** dist-tag while the migration runs. Never publish it to
+`qa`: `Xv.Identity/Pages/Account/Login.cshtml` loads `unpkg.com/xv-webcomponents@qa` straight from
+the CDN, so that tag reaches production without a deploy.
+
+### Dependencies
+
+`@lit/react` is the only runtime dependency, and only the React wrappers reach it. Everything else
+is a devDependency — the five former runtime dependencies are already bundled into
+`dist`, and `@fortawesome/fontawesome-pro` comes from a private registry, which made any external
+`npm install` fail. `react`, `@stencil/react-output-target` and `@angular/core` are optional peers.
+
+One upgrade is deliberately held back: **Jest 30** — Stencil 4.45 still routes any jest above 29
+to its Jest 27 adapter (`getJestFacade()`). **Puppeteer 25** was unblocked by Stencil 4.45, which
+awaits the now-async `executablePath()`.
+
+---
+
+## Contributing
+
+Read [`src/components/README.md`](src/components/README.md) first — it is the component API contract
+(naming, props, events, slots, CSS custom properties, parts, docs and tests) that every component is
+held to.
+
+### **Adding a New Component**
+1. Generate a new component:
+   ```bash
+   npm run generate component xv-new-component
+   ```
+2. Implement logic and styles inside `src/components/xv-new-component/`.
+3. Test the component using Jest (`.spec.ts`) and e2e tests.
+4. Run `npm run build` to generate the compiled version.
+5. Commit changes and submit a pull request.
+

package/dist/angular/angular-component-lib/utils.d.ts

@@ -0,0 +1,9 @@
+export declare const proxyInputs: (Cmp: any, inputs: string[]) => void;
+export declare const proxyMethods: (Cmp: any, methods: string[]) => void;
+export declare const proxyOutputs: (instance: any, el: any, events: string[]) => void;
+export declare const defineCustomElement: (tagName: string, customElement: any) => void;
+export declare function ProxyCmp(opts: {
+    defineCustomElementFn?: () => void;
+    inputs?: any;
+    methods?: any;
+}): (cls: any) => any;

package/dist/angular/angular-component-lib/utils.js

@@ -0,0 +1,58 @@
+/* eslint-disable */
+/* tslint:disable */
+import { fromEvent } from 'rxjs';
+export const proxyInputs = (Cmp, inputs) => {
+    const Prototype = Cmp.prototype;
+    inputs.forEach((item) => {
+        Object.defineProperty(Prototype, item, {
+            get() {
+                return this.el[item];
+            },
+            set(val) {
+                this.z.runOutsideAngular(() => (this.el[item] = val));
+            },
+            /**
+             * In the event that proxyInputs is called
+             * multiple times re-defining these inputs
+             * will cause an error to be thrown. As a result
+             * we set configurable: true to indicate these
+             * properties can be changed.
+             */
+            configurable: true,
+        });
+    });
+};
+export const proxyMethods = (Cmp, methods) => {
+    const Prototype = Cmp.prototype;
+    methods.forEach((methodName) => {
+        Prototype[methodName] = function () {
+            const args = arguments;
+            return this.z.runOutsideAngular(() => this.el[methodName].apply(this.el, args));
+        };
+    });
+};
+export const proxyOutputs = (instance, el, events) => {
+    events.forEach((eventName) => (instance[eventName] = fromEvent(el, eventName)));
+};
+export const defineCustomElement = (tagName, customElement) => {
+    if (customElement !== undefined && typeof customElements !== 'undefined' && !customElements.get(tagName)) {
+        customElements.define(tagName, customElement);
+    }
+};
+// tslint:disable-next-line: only-arrow-functions
+export function ProxyCmp(opts) {
+    const decorator = function (cls) {
+        const { defineCustomElementFn, inputs, methods } = opts;
+        if (defineCustomElementFn !== undefined) {
+            defineCustomElementFn();
+        }
+        if (inputs) {
+            proxyInputs(cls, inputs);
+        }
+        if (methods) {
+            proxyMethods(cls, methods);
+        }
+        return cls;
+    };
+    return decorator;
+}

package/dist/angular/index.d.ts

@@ -0,0 +1,4 @@
+export * from './proxies';
+export * from './web-components.module';
+import * as d from './proxies';
+export declare const DIRECTIVES: (typeof d.XvAccordionV2 | typeof d.XvAccordionV2Item | typeof d.XvBreadcrumbsV2 | typeof d.XvButtonGroupV2 | typeof d.XvButtonV2 | typeof d.XvCardV2 | typeof d.XvCheckboxV2 | typeof d.XvContentSwitcherItemV2 | typeof d.XvContentSwitcherV2 | typeof d.XvDataTable | typeof d.XvDataTableCell | typeof d.XvDataTableCollapse | typeof d.XvDataTableRow | typeof d.XvDatePicker | typeof d.XvDatepicker | typeof d.XvDropdownV2 | typeof d.XvDropdownV2Item | typeof d.XvFileUploader | typeof d.XvFooter | typeof d.XvGeoMapV2 | typeof d.XvHeader | typeof d.XvHeaderNext | typeof d.XvImageViewer | typeof d.XvLinkV2 | typeof d.XvLoaderV2 | typeof d.XvLoginModal | typeof d.XvMegaMenu | typeof d.XvMegaMenuNext | typeof d.XvModalV2 | typeof d.XvNotificationV2 | typeof d.XvNumberInputV2 | typeof d.XvOverflowMenuV2 | typeof d.XvOverflowMenuV2Item | typeof d.XvPagination | typeof d.XvProgressIndicatorV2 | typeof d.XvProgressIndicatorV2Item | typeof d.XvRadioV2 | typeof d.XvSliderV2 | typeof d.XvTabV2 | typeof d.XvTable | typeof d.XvTableCell | typeof d.XvTableRow | typeof d.XvTabsV2 | typeof d.XvTagCombobox | typeof d.XvTagV2 | typeof d.XvTextInputV2 | typeof d.XvTextarea | typeof d.XvTile | typeof d.XvToggle | typeof d.XvToggleTip | typeof d.XvTooltipV2)[];

package/dist/angular/index.js

@@ -0,0 +1,56 @@
+export * from './proxies';
+export * from './web-components.module';
+import * as d from './proxies';
+export const DIRECTIVES = [
+    d.XvAccordionV2,
+    d.XvAccordionV2Item,
+    d.XvBreadcrumbsV2,
+    d.XvButtonGroupV2,
+    d.XvButtonV2,
+    d.XvCardV2,
+    d.XvCheckboxV2,
+    d.XvContentSwitcherItemV2,
+    d.XvContentSwitcherV2,
+    d.XvDataTable,
+    d.XvDataTableCell,
+    d.XvDataTableCollapse,
+    d.XvDataTableRow,
+    d.XvDatePicker,
+    d.XvDatepicker,
+    d.XvDropdownV2,
+    d.XvDropdownV2Item,
+    d.XvFileUploader,
+    d.XvFooter,
+    d.XvGeoMapV2,
+    d.XvHeader,
+    d.XvHeaderNext,
+    d.XvImageViewer,
+    d.XvLinkV2,
+    d.XvLoaderV2,
+    d.XvLoginModal,
+    d.XvMegaMenu,
+    d.XvMegaMenuNext,
+    d.XvModalV2,
+    d.XvNotificationV2,
+    d.XvNumberInputV2,
+    d.XvOverflowMenuV2,
+    d.XvOverflowMenuV2Item,
+    d.XvPagination,
+    d.XvProgressIndicatorV2,
+    d.XvProgressIndicatorV2Item,
+    d.XvRadioV2,
+    d.XvSliderV2,
+    d.XvTabV2,
+    d.XvTable,
+    d.XvTableCell,
+    d.XvTableRow,
+    d.XvTabsV2,
+    d.XvTagCombobox,
+    d.XvTagV2,
+    d.XvTextInputV2,
+    d.XvTextarea,
+    d.XvTile,
+    d.XvToggle,
+    d.XvToggleTip,
+    d.XvTooltipV2
+];