@dubai-design-system/components-js 4.1.0 → 5.0.0

package/dist/types/stencil-public-runtime.d.ts

@@ -1,4 +1,6 @@
-declare type CustomMethodDecorator<T> = (target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | void;
+type CustomMethodDecorator<T> = (target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | void;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type MixinInstance<F> = F extends (base: MixedInCtor) => MixedInCtor<infer I> ? I : never;
 export interface ComponentDecorator {
     (opts?: ComponentOptions): ClassDecorator;
 }
@@ -61,6 +63,12 @@ export interface ShadowRootOptions {
      * focusable part is given focus, and the shadow host is given any available `:focus` styling.
      */
     delegatesFocus?: boolean;
+    /**
+     * Sets the slot assignment mode for the shadow root. When set to `'manual'`, enables imperative
+     * slotting using the `HTMLSlotElement.assign()` method. Defaults to `'named'` for standard
+     * declarative slotting behavior.
+     */
+    slotAssignment?: 'manual' | 'named';
 }
 export interface ModeStyles {
     [modeName: string]: string | string[];
@@ -117,12 +125,34 @@ export interface EventOptions {
      */
     composed?: boolean;
 }
+export interface AttachInternalsOptions {
+    /**
+     * Initial custom states to set on the ElementInternals.states CustomStateSet.
+     * Each key is the state name and the value is the initial boolean state.
+     *
+     * These states can be targeted with the CSS `:state()` pseudo-class.
+     *
+     * @example
+     * ```tsx
+     * @AttachInternals({ states: { open: true, active: false } })
+     * internals: ElementInternals;
+     * ```
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet
+     */
+    states?: {
+        [stateName: string]: boolean;
+    };
+}
 export interface AttachInternalsDecorator {
-    (): PropertyDecorator;
+    (opts?: AttachInternalsOptions): PropertyDecorator;
 }
 export interface ListenDecorator {
     (eventName: string, opts?: ListenOptions): CustomMethodDecorator<any>;
 }
+export interface ResolveVarFunction {
+    <T>(variable: T): string;
+}
 export interface ListenOptions {
     /**
      * Handlers can also be registered for an event other than the host itself.
@@ -151,7 +181,15 @@ export interface StateDecorator {
     (): PropertyDecorator;
 }
 export interface WatchDecorator {
-    (propName: string): CustomMethodDecorator<any>;
+    (propName: any, watchOptions?: {
+        immediate?: boolean;
+    }): CustomMethodDecorator<(newValue?: any, oldValue?: any, propName?: any, ...args: any[]) => any | void>;
+}
+export interface PropSerializeDecorator {
+    (propName: any): CustomMethodDecorator<(newValue?: any, propName?: string, ...args: any[]) => string | null>;
+}
+export interface AttrDeserializeDecorator {
+    (propName: any): CustomMethodDecorator<(newValue?: any, propName?: string, ...args: any[]) => any>;
 }
 export interface UserBuildConditionals {
     isDev: boolean;
@@ -200,6 +238,24 @@ export declare const AttachInternals: AttachInternalsDecorator;
  * https://stenciljs.com/docs/events#listen-decorator
  */
 export declare const Listen: ListenDecorator;
+/**
+ * The `resolveVar()` function is a compile-time utility that resolves const variables
+ * and object properties to their string literal values. This allows variables to be
+ * used in `@Listen` and `@Event` decorators instead of hardcoded strings.
+ *
+ * @example
+ * ```ts
+ * const MY_EVENT = 'myEvent';
+ * @Listen(resolveVar(MY_EVENT))
+ * ```
+ *
+ * @example
+ * ```ts
+ * const EVENTS = { MY_EVENT: 'myEvent' } as const;
+ * @Event({ eventName: resolveVar(EVENTS.MY_EVENT) })
+ * ```
+ */
+export declare const resolveVar: ResolveVarFunction;
 /**
  * The `@Method()` decorator is used to expose methods on the public API.
  * Class methods decorated with the @Method() decorator can be called directly
@@ -233,6 +289,14 @@ export declare const State: StateDecorator;
  * https://stenciljs.com/docs/reactive-data#watch-decorator
  */
 export declare const Watch: WatchDecorator;
+/**
+ * Decorator to serialize a property to an attribute string.
+ */
+export declare const PropSerialize: PropSerializeDecorator;
+/**
+ * Decorator to deserialize an attribute string to a property.
+ */
+export declare const AttrDeserialize: AttrDeserializeDecorator;
 export type ResolutionHandler = (elm: HTMLElement) => string | undefined | null;
 export type ErrorHandler = (err: any, element?: HTMLElement) => void;
 /**
@@ -260,6 +324,25 @@ export declare function setPlatformHelpers(helpers: {
  * @returns the base path
  */
 export declare function getAssetPath(path: string): string;
+/**
+ * Method to render a virtual DOM tree to a container element.
+ *
+ * @example
+ * ```tsx
+ * import { render } from '@stencil/core';
+ *
+ * const vnode = (
+ *   <div>
+ *     <h1>Hello, world!</h1>
+ *   </div>
+ * );
+ * render(vnode, document.body);
+ * ```
+ *
+ * @param vnode - The virtual DOM tree to render
+ * @param container - The container element to render the virtual DOM tree to
+ */
+export declare function render(vnode: VNode, container: Element): void;
 /**
  * Used to manually set the base path where assets can be found. For lazy-loaded
  * builds the asset path is automatically set and assets copied to the correct
@@ -330,6 +413,58 @@ export declare function readTask(task: RafCallback): void;
  * Unhandled exception raised while rendering, during event handling, or lifecycles will trigger the custom event handler.
  */
 export declare const setErrorHandler: (handler: ErrorHandler) => void;
+export type TagTransformer = (tag: string) => string;
+/**
+ * Sets a tag transformer to be used when rendering your custom elements.
+ * ```ts
+ * setTagTransformer((tag) => {
+ *  if (tag.startsWith('my-')) return `new-${tag}`
+ *  return tag;
+ * });
+ * ```
+ * Will mean all your components that start with `my-` are defined instead with `new-my-` prefix.
+ *
+ * @param transformer the transformer function to use which must return a string.
+ */
+export declare function setTagTransformer(transformer: TagTransformer): void;
+/**
+ * Transforms a tag name using a transformer set via `setTagTransformer`
+ *
+ * @param tag - the tag to transform e.g. `my-tag`
+ * @returns the transformed tag e.g. `new-my-tag`
+ */
+export declare function transformTag(tag: string): string;
+/**
+ * @deprecated - Use `MixedInCtor` instead:
+ * ```ts
+ * import { MixedInCtor } from '@stencil/core';
+ *
+ * const AFactoryFn = <B extends MixedInCtor>(Base: B) => {class A extends Base { propA = A }; return A;}
+ * ```
+ */
+export type MixinFactory = (base: MixedInCtor) => MixedInCtor;
+export type MixedInCtor<T = {}> = new (...args: any[]) => T;
+/**
+ * Compose multiple mixin classes into a single constructor.
+ * The resulting class has the combined instance types of all mixed-in classes.
+ *
+ * Example:
+ * ```ts
+ * import { Mixin, MixedInCtor } from '@stencil/core';
+ *
+ * const AWrap = <B extends MixedInCtor>(Base: B) => {class A extends Base { propA = A }; return A;}
+ * const BWrap = <B extends MixedInCtor>(Base: B) => {class B extends Base { propB = B }; return B;}
+ * const CWrap = <B extends MixedInCtor>(Base: B) => {class C extends Base { propC = C }; return C;}
+ *
+ * class X extends Mixin(AWrap, BWrap, CWrap) {
+ *   render() { return <div>{this.propA} {this.propB} {this.propC}</div>; }
+ * }
+ * ```
+ *
+ * @param mixinFactories mixin factory functions that return a class which extends from the provided class.
+ * @returns a class that is composed from extending each of the provided classes in the order they were provided.
+ */
+export declare function Mixin<const TMixins extends readonly MixinFactory[]>(...mixinFactories: TMixins): abstract new (...args: any[]) => UnionToIntersection<MixinInstance<TMixins[number]>>;
 /**
  * This file gets copied to all distributions of stencil component collections.
  * - no imports
@@ -502,7 +637,7 @@ export interface FunctionalUtilities {
     map: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => ChildNode) => VNode[];
 }
 export interface FunctionalComponent<T = {}> {
-    (props: T, children: VNode[], utils: FunctionalUtilities): VNode | VNode[];
+    (props: T, children: VNode[], utils: FunctionalUtilities): VNode | VNode[] | null;
 }
 /**
  * A Child VDOM node
@@ -544,6 +679,7 @@ export declare namespace h {
     function h(sel: any, data: VNodeData | null, text: string): VNode;
     function h(sel: any, data: VNodeData | null, children: Array<VNode | undefined | null>): VNode;
     function h(sel: any, data: VNodeData | null, children: VNode): VNode;
+    function h(sel: any, data: VNodeData | null, ...children: (VNode | string | number)[]): VNode;
     namespace JSX {
         interface IntrinsicElements extends LocalJSX.IntrinsicElements, JSXBase.IntrinsicElements {
             [tagName: string]: any;
@@ -558,6 +694,36 @@ export declare function h(sel: any, children: Array<VNode | undefined | null>):
 export declare function h(sel: any, data: VNodeData | null, text: string): VNode;
 export declare function h(sel: any, data: VNodeData | null, children: Array<VNode | undefined | null>): VNode;
 export declare function h(sel: any, data: VNodeData | null, children: VNode): VNode;
+export declare function h(sel: any, data: VNodeData | null, ...children: (VNode | string | number)[]): VNode;
+/**
+ * Automatic JSX runtime functions for TypeScript's react-jsx mode.
+ * These functions are called automatically by TypeScript when using "jsx": "react-jsx".
+ * @param type type of node
+ * @param props properties of node
+ * @param key optional key for the node
+ * @returns a jsx vnode
+ */
+export declare function jsx(type: any, props: any, key?: string): VNode;
+/**
+ * Automatic JSX runtime functions for TypeScript's react-jsxmode with multiple children.
+ * @param type type of node
+ * @param props properties of node
+ * @param key optional key for the node
+ * @returns a jsx vnode
+ */
+export declare function jsxs(type: any, props: any, key?: string): VNode;
+/**
+ * Automatic JSX runtime functions for TypeScript's react-jsxdev mode.
+ * These functions are called automatically by TypeScript when using "jsx": "react-jsxdev".
+ * @param type type of node
+ * @param props properties of node
+ * @param key optional key for the node
+ * @param isStaticChildren indicates if the children are static
+ * @param source source information
+ * @param self reference to the component instance
+ * @returns a jsx vnode
+ */
+export declare function jsxDEV(type: any, props: any, key?: string | number, isStaticChildren?: boolean, source?: any, self?: any): VNode;
 /**
  * A virtual DOM node
  */
@@ -587,7 +753,7 @@ declare namespace LocalJSX {
 export { LocalJSX as JSX };
 export declare namespace JSXBase {
     interface IntrinsicElements {
-        slot: JSXBase.SlotAttributes;
+        slot: JSXBase.SlotAttributes<HTMLSlotElement>;
         a: JSXBase.AnchorHTMLAttributes<HTMLAnchorElement>;
         abbr: JSXBase.HTMLAttributes;
         address: JSXBase.HTMLAttributes;
@@ -757,7 +923,7 @@ export declare namespace JSXBase {
         use: JSXBase.SVGAttributes;
         view: JSXBase.SVGAttributes;
     }
-    interface SlotAttributes extends JSXAttributes {
+    interface SlotAttributes<T = HTMLSlotElement> extends JSXAttributes<T> {
         name?: string;
         slot?: string;
         onSlotchange?: (event: Event) => void;
@@ -813,6 +979,9 @@ export declare namespace JSXBase {
         popoverTargetAction?: string;
         popoverTargetElement?: Element | null;
         popoverTarget?: string;
+        command?: string;
+        commandFor?: string;
+        commandfor?: string;
     }
     interface CanvasHTMLAttributes<T> extends HTMLAttributes<T> {
         height?: number | string;
@@ -826,7 +995,8 @@ export declare namespace JSXBase {
     }
     interface DetailsHTMLAttributes<T> extends HTMLAttributes<T> {
         open?: boolean;
-        onToggle?: (event: Event) => void;
+        name?: string;
+        onToggle?: (event: ToggleEvent) => void;
     }
     interface DelHTMLAttributes<T> extends HTMLAttributes<T> {
         cite?: string;
@@ -900,6 +1070,7 @@ export declare namespace JSXBase {
         importance?: 'low' | 'auto' | 'high';
         height?: number | string;
         loading?: 'lazy' | 'auto' | 'eager';
+        referrerPolicy?: ReferrerPolicy;
         sizes?: string;
         src?: string;
         srcSet?: string;
@@ -1532,6 +1703,13 @@ export declare namespace JSXBase {
         z?: number | string;
         zoomAndPan?: string;
     }
+    /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ToggleEvent) */
+    interface ToggleEvent extends Event {
+        /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ToggleEvent/newState) */
+        readonly newState: string;
+        /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ToggleEvent/oldState) */
+        readonly oldState: string;
+    }
     interface DOMAttributes<T> extends JSXAttributes<T> {
         slot?: string;
         part?: string;
@@ -1548,6 +1726,10 @@ export declare namespace JSXBase {
         onCompositionstartCapture?: (event: CompositionEvent) => void;
         onCompositionupdate?: (event: CompositionEvent) => void;
         onCompositionupdateCapture?: (event: CompositionEvent) => void;
+        onBeforeToggle?: (event: ToggleEvent) => void;
+        onBeforeToggleCapture?: (event: ToggleEvent) => void;
+        onToggle?: (event: ToggleEvent) => void;
+        onToggleCapture?: (event: ToggleEvent) => void;
         onFocus?: (event: FocusEvent) => void;
         onFocusCapture?: (event: FocusEvent) => void;
         onFocusin?: (event: FocusEvent) => void;
@@ -1566,10 +1748,6 @@ export declare namespace JSXBase {
         onSubmitCapture?: (event: Event) => void;
         onInvalid?: (event: Event) => void;
         onInvalidCapture?: (event: Event) => void;
-        onBeforeToggle?: (event: Event) => void;
-        onBeforeToggleCapture?: (event: Event) => void;
-        onToggle?: (event: Event) => void;
-        onToggleCapture?: (event: Event) => void;
         onLoad?: (event: Event) => void;
         onLoadCapture?: (event: Event) => void;
         onError?: (event: Event) => void;
@@ -1581,7 +1759,7 @@ export declare namespace JSXBase {
         onKeyUp?: (event: KeyboardEvent) => void;
         onKeyUpCapture?: (event: KeyboardEvent) => void;
         onAuxClick?: (event: MouseEvent) => void;
-        onClick?: (event: MouseEvent) => void;
+        onClick?: (event: PointerEvent) => void;
         onClickCapture?: (event: MouseEvent) => void;
         onContextMenu?: (event: MouseEvent) => void;
         onContextMenuCapture?: (event: MouseEvent) => void;
@@ -1661,6 +1839,8 @@ export declare namespace JSXBase {
         onTransitionRunCapture?: (event: TransitionEvent) => void;
         onTransitionStart?: (event: TransitionEvent) => void;
         onTransitionStartCapture?: (event: TransitionEvent) => void;
+        [key: `aria-${string}`]: string | boolean | undefined;
+        [key: `aria${string}`]: string | boolean | undefined;
     }
 }
 export interface JSXAttributes<T = Element> {
@@ -1671,6 +1851,7 @@ export interface CustomElementsDefineOptions {
     exclude?: string[];
     resourcesUrl?: string;
     syncQueue?: boolean;
+    /** @deprecated in-favour of `setTagTransformer` and `transformTag` */
     transformTagName?: (tagName: string) => string;
     jmp?: (c: Function) => any;
     raf?: (c: FrameRequestCallback) => number;

package/dist/types/utils/contrast.d.ts

@@ -0,0 +1,19 @@
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * Parses a CSS color string as returned by `getComputedStyle()`
+ * (`rgb(r, g, b)` or `rgba(r, g, b, a)`) into its channel values.
+ */
+export declare function parseRgb(color: string): Rgb;
+/** WCAG relative luminance, 0 (black) to 1 (white). */
+export declare function relativeLuminance({ r, g, b }: Rgb): number;
+/**
+ * WCAG contrast ratio between two colors, each either a `getComputedStyle()`
+ * color string or a pre-parsed { r, g, b }. Order doesn't matter — the
+ * lighter color is always treated as the numerator, per spec.
+ */
+export declare function contrastRatio(a: string | Rgb, b: string | Rgb): number;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dubai-design-system/components-js",
-  "version": "4.1.0",
+  "version": "5.0.0",
   "private": false,
   "description": "JavaScript package for the Digital Dubai Design System, offering reusable, customizable components for seamless integration into web applications",
   "main": "dist/index.cjs.js",
@@ -11,7 +11,6 @@
   "unpkg": "dist/stencil/stencil.esm.js",
   "exports": {
     ".": {
-      "types": "./dist/types/index.d.ts",
       "import": "./dist/stencil/stencil.esm.js",
       "require": "./dist/stencil/stencil.cjs.js"
     },
@@ -34,7 +33,8 @@
   },
   "files": [
     "dist/",
-    "loader/"
+    "loader/",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "stencil build",
@@ -44,16 +44,27 @@
     "generate": "stencil generate",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
-    "release": "standard-version"
+    "release": "standard-version",
+    "lint": "eslint src",
+    "lint:report": "eslint src -f json -o ../../docs/a11y/eslint-report.json",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,css}\"",
+    "format": "prettier --write \"src/**/*.{ts,tsx,css}\"",
+    "check:api": "node scripts/check-api-consistency.mjs",
+    "check:api:test": "node --test scripts/check-api-consistency.test.mjs",
+    "test:a11y": "test-storybook --url http://127.0.0.1:6006",
+    "test:a11y:ci": "concurrently -k -s first -n SB,TEST \"http-server storybook-static --port 6006 --silent\" \"wait-on tcp:127.0.0.1:6006 && npm run test:a11y\""
   },
   "dependencies": {
     "chromatic": "^11.11.0",
+    "material-icons": "^1.13.14",
+    "material-symbols": "^0.28.2",
     "quill": "^2.0.2",
     "react-markdown": "^9.0.1"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
     "@stencil/angular-output-target": "^0.10.2",
-    "@stencil/core": "^4.7.0",
+    "@stencil/core": "4.43.5",
     "@stencil/react-output-target": "^0.8.2",
     "@stencil/vue-output-target": "^0.8.8",
     "@storybook/addon-a11y": "^8.2.7",
@@ -64,23 +75,31 @@
     "@storybook/addons": "^7.6.17",
     "@storybook/blocks": "^8.1.11",
     "@storybook/test": "^8.2.7",
+    "@storybook/test-runner": "^0.19.1",
     "@storybook/web-components": "^8.1.11",
     "@storybook/web-components-webpack5": "^8.1.11",
     "@types/jest": "^29.5.6",
     "@types/node": "^16.18.11",
     "@whitespace/storybook-addon-html": "^6.1.1",
+    "axe-playwright": "^2.2.2",
+    "concurrently": "^8.2.2",
+    "eslint": "^9.39.5",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "http-server": "^14.1.1",
     "jest": "^29.7.0",
     "jest-cli": "^29.7.0",
     "lit": "^3.1.4",
-    "prettier": "^3.3.3",
+    "prettier": "^3.9.6",
     "puppeteer": "^21.9.0",
     "react-syntax-highlighter": "^15.5.0",
     "standard-version": "^9.5.0",
-    "storybook": "^8.1.11"
+    "storybook": "^8.1.11",
+    "typescript-eslint": "^8.67.0",
+    "wait-on": "^7.2.0"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "license": "SEE LICENSE IN LICENSE",
-  "gitHead": "e2ec37be4c069cd02f6b8b6d33c3b58583eb5241"
+  "license": "UNLICENSED",
+  "gitHead": "c37cc307e4f1c8f618fd09aed47c782f644c0908"
 }

package/readme.md

@@ -1,78 +1,80 @@
-<p align="center">
-  <a href="#">
-    <img alt="dda-logo" src="https://www.digitaldubai.ae/ResourcePackages/Theme/assets/dist/images/logo.svg" width="60">
-  </a>
-</p>
-
-This package provides web components built using StencilJS as part of the Dubai Design System (DDA), ensuring consistency, reusability, and performance across modern web applications. These components are framework-agnostic and can be used in custom websites without dependency on React, Angular, or Vue.
-
-#### Key Features
-
-Lightweight & Fast: Uses native Web Components for optimal performance.
-
-Customizable: Designed to align with Dubai Design System branding.
-
-Framework-Agnostic: Works with any HTML, JavaScript, or TypeScript-based project.
-
-Accessible & Scalable: Follows best practices for accessibility and responsive design.
-
-#### Usage
-
-1. Include the Web Components Library
-
-Next, add the material-icons package which is the icon package used by DDA:
-
-Start by adding the material-icons package inside the `<head>` tag
-
-```jsx
-
-<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
-
-Add the following script to your HTML to load the library:
-
-<script type="module">
-
- import { defineCustomElements } from "https://cdn.jsdelivr.net/npm/@dubai-design-system/components-js/loader/index.es2017.js";
- 
- defineCustomElements();
-
-</script>
-
-```
-
-#### Add DDA Components in Your HTML
-
-Now you can use DDA components directly in your HTML files:
-
-```jsx
-<dda-button
-        button_color="default-primary"
-        start_icon="sentiment_satisfied"
-        end_icon="arrow_forward"
-        custom_class=""
-        component_mode=""
-        button_id="button"
-        aria_label="button"
-        onclick="console.log('clicked')"
->Button</dda-button>
-```
-
-#### Available Components
-
-<dda-button> - Customizable button component
-
-<dda-dropdown> - Dropdown component with various options
-
-<dda-modal> - Accessible modal dialog
-
-<dda-card> - Card layout with structured content
-
-And more...
-
-#### Contributing
-
-This project is built with a focus on Dubai’s digital transformation and welcomes contributions from the community. Feel free to submit issues, feedback, or feature requests.
-
-#### License
-
-This package is licensed under the Dubai Digital Authority regulations. For more details, refer to the official documentation.
+<p align="center">
+  <a href="#">
+    <img alt="dda-logo" src="https://www.digitaldubai.ae/ResourcePackages/Theme/assets/dist/images/logo.svg" width="60">
+  </a>
+</p>
+
+<h1 align="center">
+Dubai Design System — Web Components
+</h1>
+
+Framework-agnostic web components built with StencilJS as part of the Dubai Design System (DDA). Use them in any HTML, JavaScript, or TypeScript project — no dependency on React, Angular, or Vue.
+
+Framework wrappers are also available: [`@dubai-design-system/components-react`](https://www.npmjs.com/package/@dubai-design-system/components-react), [`@dubai-design-system/components-vue`](https://www.npmjs.com/package/@dubai-design-system/components-vue), and [`@dubai-design-system/components-angular`](https://www.npmjs.com/package/@dubai-design-system/components-angular).
+
+#### Key features
+
+- **Lightweight & fast** — native Web Components with lazy loading.
+- **Customizable** — aligned with Dubai Design System branding, with light and dark themes.
+- **Framework-agnostic** — works in plain HTML or with any framework.
+- **Accessible & responsive** — follows accessibility best practices.
+
+## Setup
+
+### 1. Add the icon fonts
+
+DDA components use Material Icons and Material Symbols. Add both inside your `<head>` tag:
+
+```html
+<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
+<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" rel="stylesheet">
+```
+
+### 2. Load the components
+
+**Option A — CDN (no build step).** Add this script to your HTML, replacing `X.X.X` with the [latest published version](https://www.npmjs.com/package/@dubai-design-system/components-js). **Always pin an exact version in the CDN URL** — unversioned jsdelivr URLs resolve each file independently, so the loader and its chunks can come from different package versions, which breaks rendering:
+
+```html
+<script type="module">
+  import { defineCustomElements } from "https://cdn.jsdelivr.net/npm/@dubai-design-system/components-js@X.X.X/loader/index.es2017.js";
+
+  defineCustomElements();
+</script>
+```
+
+**Option B — npm with a bundler (Vite, Rollup).** Install the package:
+
+```bash
+npm i @dubai-design-system/components-js
+```
+
+Then import the self-registering build for each component you use:
+
+```js
+// each import automatically defines its custom element
+import '@dubai-design-system/components-js/dist/components/dda-button.js';
+import '@dubai-design-system/components-js/dist/components/dda-header.js';
+```
+
+> ⚠️ With Vite or plain Rollup, do **not** use the lazy loader (`@dubai-design-system/components-js/loader`). Its computed dynamic imports cannot be statically analyzed by these bundlers, so component chunks are missing from the build (404 on `dda-*.entry.js`) and components never render. The CDN approach and Angular's builder are unaffected.
+
+### 3. Use the components
+
+```html
+<dda-button
+  button_color="default-primary"
+  start_icon="sentiment_satisfied"
+  end_icon="arrow_forward"
+  button_id="button"
+  aria_label="button"
+  onclick="console.log('clicked')"
+>Button</dda-button>
+```
+
+## Available components
+
+`dda-button`, `dda-dropdown`, `dda-modal`, `dda-card`, `dda-header`, and more.
+
+## License
+
+Copyright (c) 2018-2026 Digital Dubai. All rights reserved. An open-source license is under review and will be announced in a future release.

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2018
-
-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/dist/cjs/app-globals-3a1e7e63.js

@@ -1,7 +0,0 @@
-'use strict';
-
-const globalScripts = () => {};
-
-exports.globalScripts = globalScripts;
-
-//# sourceMappingURL=app-globals-3a1e7e63.js.map

package/dist/cjs/app-globals-3a1e7e63.js.map

@@ -1 +0,0 @@
-{"file":"app-globals-3a1e7e63.js","mappings":";;AAAY,MAAC,aAAa,GAAG,MAAM;;;;","names":[],"sources":["@stencil/core/internal/app-globals"],"sourcesContent":["export const globalScripts = () => {};\n"],"version":3}