@jack-henry/jh-elements 2.0.0-beta.14 → 2.0.0-beta.15

package/NOTICE

@@ -1,5 +1,5 @@
 ===========================================================
-Jack Henry Design System
+Forge Design System
 Copyright 2025 Jack Henry
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

package/README.md

@@ -6,8 +6,8 @@ SPDX-License-Identifier: Apache-2.0
 
 ## @jack-henry/jh-elements
 
-Contains Jack Henry's web component library. To get started, visit our documentation sites.
+Contains the Forge Design System web component library. To get started, visit our documentation sites.
 
-* [Jackhenry.design](https://jackhenry.design) focuses on introducing the underlying concepts of the Design System, usage guidelines, and a style guide.
+* [Jackhenry.design](https://jackhenry.design) focuses on introducing the underlying concepts of the design system, usage guidelines, and a style guide.
 * [Storybook](https://main--68f8e6a25b256d0ef89b13e6.chromatic.com/?path=/docs/welcome-about-jh--docs) focuses on technical implementations and considerations 
 for engineers including author guidance and a playground where you can test drive our components.

package/components/badge/badge.js

@@ -2,8 +2,9 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-import { LitElement, css, html } from 'lit';
+import { css, html } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
+import { JhElement } from '../element/element.js';
 
 /**
  * @cssprop --jh-badge-border-radius - The badge border radius. Defaults to `--jh-border-radius-pill`.
@@ -12,7 +13,7 @@ import { ifDefined } from 'lit/directives/if-defined.js';
  * 
  * @customElement jh-badge
  */
-export class JhBadge extends LitElement {
+export class JhBadge extends JhElement {
   static get styles() {
     return css`
     :host {
@@ -70,5 +71,4 @@ export class JhBadge extends LitElement {
     `;
   }
 }
-customElements.define('jh-badge', JhBadge);
-
+JhBadge.register('jh-badge', JhBadge);

package/components/button/button.js

@@ -2,8 +2,9 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-import { LitElement, css, html } from 'lit';
+import { css, html } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
+import { JhElement } from '../element/element.js';
 import '../progress/progress.js';
 
 /**
@@ -108,15 +109,12 @@ import '../progress/progress.js';
  * @slot jh-button-icon-right - Use to insert an icon on the right side of the button and for single icon buttons.
  * @customElement jh-button
  */
-export class JhButton extends LitElement {
+export class JhButton extends JhElement {
   /** @ignore */
   static get formAssociated() {
     return true;
   }
 
-  /** @type {ElementInternals} */
-  #internals;
-
   /** @type {?string} */
   #value;
 
@@ -806,9 +804,7 @@ export class JhButton extends LitElement {
   constructor() {
     super();
     /** @type {ElementInternals} */
-    this.#internals = this.attachInternals();
-    /** @type {ElementInternals} */
-    this.#internals.form;
+    this.internals.form;
     /** @type {'true'|'false'} */
     this.accessibleDisabled = null;
     /** @type {?string} */
@@ -853,7 +849,7 @@ export class JhButton extends LitElement {
     const oldValue = this.#value;
     if (newValue !== oldValue) {
       this.#value = newValue;
-      this.#internals.setFormValue(newValue);
+      this.internals.setFormValue(newValue);
     }
     this.requestUpdate('value', oldValue);
   }
@@ -888,8 +884,8 @@ export class JhButton extends LitElement {
 
   #onClick(event) {
     //If I'm a submit button in a form and I'm not disabled submit the form
-    if (this.submit && this.#internals.form && !this.disabled) {
-      this.#internals.form.requestSubmit();
+    if (this.submit && this.internals.form && !this.disabled) {
+      this.internals.form.requestSubmit();
     }
   }
 
@@ -1008,5 +1004,4 @@ export class JhButton extends LitElement {
     }
   }
 }
-
-customElements.define('jh-button', JhButton);
+JhButton.register('jh-button', JhButton);

package/components/card/card.js

@@ -2,8 +2,9 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-import { LitElement, css, html } from 'lit';
+import { css, html } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
+import { JhElement } from '../element/element.js';
 import '../divider/divider.js';
 
 /**
@@ -31,7 +32,7 @@ import '../divider/divider.js';
  * @slot jh-card-footer - Use to insert card footer content.
  * @customElement jh-card
  */
-export class JhCard extends LitElement {
+export class JhCard extends JhElement {
   static get styles() {
     return css`
       :host {
@@ -341,5 +342,4 @@ export class JhCard extends LitElement {
     `;
   }
 }
-
-customElements.define('jh-card', JhCard);
+JhCard.register('jh-card', JhCard);

package/components/checkbox/checkbox.js

@@ -2,10 +2,9 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-import { LitElement, css, html } from 'lit';
+import { css, html } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
-
-let id = 0;
+import { JhElement } from '../element/element.js';
 
 /**
  * @cssprop --jh-checkbox-opacity-disabled - The checkbox opacity when disabled. Defaults to `--jh-opacity-disabled`.
@@ -54,22 +53,19 @@ let id = 0;
  * @cssprop --jh-checkbox-input-color-border-indeterminate-disabled - The checkbox border-color when indeterminate and disabled. Defaults to `--jh-color-content-brand-enabled`.
  * @cssprop --jh-checkbox-status-color-border-indeterminate-disabled - The checkbox color when indeterminate status mark when disabled. Defaults to `--jh-color-content-on-brand-enabled`.
  *
- * @event jh-change - Dispatched when the state of the checkbox has changed.
+ * @event jh-change - Dispatched when the state of the checkbox has changed. Event payload includes the `checked` state of the checkbox and can be accessed via `e.detail.state.checked`.
  *
  * @customElement jh-checkbox
  */
-export class JhCheckbox extends LitElement {
+export class JhCheckbox extends JhElement {
   static get formAssociated() {
     return true;
   }
+
   /** @type {?Boolean} */
   #checked;
-  /** @type {?Number} */
-  #id;
   /** @type {?Boolean} */
   #indeterminate;
-  /** @type {ElementInternals} */
-  #internals;
   /** @type {?string} */
   #value;
 
@@ -456,7 +452,6 @@ export class JhCheckbox extends LitElement {
 
   constructor() {
     super();
-    this.#internals = this.attachInternals();
     /** @type {?boolean} */
     this.checked = false;
     /** @type {?boolean} */
@@ -475,22 +470,17 @@ export class JhCheckbox extends LitElement {
     this.accessibleLabel = null;
   }
 
-  connectedCallback() {
-    super.connectedCallback();
-    this.#id = id++;
-  }
-
   /**
    * Returns the checkbox's parent form element.
    * @type {?HTMLFormElement}
    */
   get form() {
-    return this.#internals.form;
+    return this.internals.form;
   }
 
   /** @ignore */
   get validity() {
-    return this.#internals.validity;
+    return this.internals.validity;
   }
 
   /** @type {?string} */
@@ -537,20 +527,19 @@ export class JhCheckbox extends LitElement {
 
   #updateFormValue(value, checked, indeterminate) {
     if (!indeterminate) {
-      this.#internals.setFormValue(checked ? value || 'on' : null);
-    } else this.#internals.setFormValue(null);
+      this.internals.setFormValue(checked ? value || 'on' : null);
+    } else this.internals.setFormValue(null);
   }
 
   #handleChange(e) {
     this.checked = e.target.checked;
     this.indeterminate = false;
     this.#updateFormValue(this.value, this.checked, this.indeterminate);
-    const options = {
-      bubbles: true,
-      composed: true,
-      cancelable: true,
-    };
-    this.dispatchEvent(new CustomEvent('jh-change', options));
+    this.dispatchCustomEvent('jh-change', {
+      state: {
+        checked: this.checked,
+      },
+    });
   }
 
   render() {
@@ -559,7 +548,7 @@ export class JhCheckbox extends LitElement {
 
     if (this.helperText) {
       helperText = html`
-        <p class="helper-text" id="checkbox-helper-text-${this.#id}">
+        <p class="helper-text" id="checkbox-helper-text-${this.uniqueId}">
           ${this.helperText}
         </p>
       `;
@@ -568,7 +557,7 @@ export class JhCheckbox extends LitElement {
     if (this.label) {
       label = html`
         <div class="label-container">
-          <label class="label-text" for="checkbox-label-${this.#id}">
+          <label class="label-text" for="checkbox-label-${this.uniqueId}">
             ${this.label}
           </label>
           ${helperText}
@@ -587,9 +576,9 @@ export class JhCheckbox extends LitElement {
         aria-label=${ifDefined(this.accessibleLabel)}
         value=${ifDefined(this.value)}
         name=${ifDefined(this.name)}
-        id=${ifDefined(this.label ? `checkbox-label-${this.#id}` : null)}
+        id=${ifDefined(this.label ? `checkbox-label-${this.uniqueId}` : null)}
         aria-describedby=${ifDefined(
-          this.helperText ? `checkbox-helper-text-${this.#id}` : null
+          this.helperText ? `checkbox-helper-text-${this.uniqueId}` : null
         )}
       />
       <span aria-hidden="true"></span>
@@ -597,5 +586,4 @@ export class JhCheckbox extends LitElement {
     `;
   }
 }
-
-customElements.define('jh-checkbox', JhCheckbox);
+JhCheckbox.register('jh-checkbox', JhCheckbox);

package/components/checkbox-group/checkbox-group.js

@@ -2,10 +2,10 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-import { LitElement, css, html } from 'lit';
+import { css, html } from 'lit';
+import { JhElement } from '../element/element.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 
-let id = 0;
 /**
  *
  * @cssprop --jh-checkbox-group-label-color-text - The label text color. Defaults to `--jh-color-content-primary-enabled`.
@@ -23,10 +23,7 @@ let id = 0;
  *
  * @customElement jh-checkbox-group
  */
-export class JhCheckboxGroup extends LitElement {
-  /** @type {?Number} */
-  #id;
-
+export class JhCheckboxGroup extends JhElement {
   static get styles() {
     return css`
       :host {
@@ -211,11 +208,6 @@ export class JhCheckboxGroup extends LitElement {
     this.showIndicator = false;
   }
 
-  connectedCallback() {
-    super.connectedCallback();
-    this.#id = id++;
-  }
-
   firstUpdated() {
     const slot = this.renderRoot?.querySelector('slot');
     this.#syncDisabledToChildren();
@@ -239,13 +231,13 @@ export class JhCheckboxGroup extends LitElement {
 
   #getAriaDescribedBy() {
     if (this.errorText && this.invalid && this.helperText && this.label) {
-      return `checkbox-group-error-${this.#id} checkbox-group-helper-${
-        this.#id
+      return `checkbox-group-error-${this.uniqueId} checkbox-group-helper-${
+        this.uniqueId
       }`;
     } else if (this.errorText && this.invalid) {
-      return `checkbox-group-error-${this.#id}`;
+      return `checkbox-group-error-${this.uniqueId}`;
     } else if (this.helperText && this.label) {
-      return `checkbox-group-helper-${this.#id}`;
+      return `checkbox-group-helper-${this.uniqueId}`;
     }
   }
 
@@ -264,24 +256,24 @@ export class JhCheckboxGroup extends LitElement {
     }
 
     if (this.helperText) {
-      helperText = html`<p class="helper-text" id="checkbox-group-helper-${this.#id}">${this.helperText}</p>`;
+      helperText = html`<p class="helper-text" id="checkbox-group-helper-${this.uniqueId}">${this.helperText}</p>`;
     }
 
     if (this.label) {
       label = html`
-        <legend class="label" for="checkbox-group-label-${this.#id}">
+        <legend class="label" for="checkbox-group-label-${this.uniqueId}">
           ${this.label}${indicator}
         </legend>
         ${helperText}`;
     }
 
     if (this.invalid && this.errorText) {
-      errorText = html`<p class="error-text" id="checkbox-group-error-${this.#id}">${this.errorText}</p>`;
+      errorText = html`<p class="error-text" id="checkbox-group-error-${this.uniqueId}">${this.errorText}</p>`;
     }
 
     return html`
       <fieldset
-        id=${ifDefined(this.label ? `checkbox-group-label-${this.#id}` : null)}
+        id=${ifDefined(this.label ? `checkbox-group-label-${this.uniqueId}` : null)}
         aria-describedby=${ifDefined(this.#getAriaDescribedBy())}
         ?required=${this.required}
         aria-invalid=${ifDefined(this.invalid ? 'true' : null)}
@@ -294,4 +286,4 @@ export class JhCheckboxGroup extends LitElement {
     `;
   }
 }
-customElements.define('jh-checkbox-group', JhCheckboxGroup);
+JhCheckboxGroup.register('jh-checkbox-group', JhCheckboxGroup);

package/components/divider/divider.js

@@ -2,7 +2,8 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-import { LitElement, css } from 'lit';
+import { css } from 'lit';
+import { JhElement } from '../element/element.js';
 
 /**
  * @cssprop --jh-divider-border-width - The divider width. Defaults to `--jh-border-decorative-width`.
@@ -11,7 +12,7 @@ import { LitElement, css } from 'lit';
  * @cssprop --jh-divider-space-inset - The divider margin-left. Defaults to `0`.
  * @customElement jh-divider
  */
-export class JhDivider extends LitElement {
+export class JhDivider extends JhElement {
   static get styles() {
     return css`
         :host {
@@ -67,7 +68,7 @@ export class JhDivider extends LitElement {
           margin-left: var(--inset, var(--jh-divider-space-inset));
         }
       `
-        }
+  }
 
   static get properties() {
     return {
@@ -87,5 +88,4 @@ export class JhDivider extends LitElement {
     this.inset = null;
   }
 }
-
-customElements.define('jh-divider', JhDivider);
+JhDivider.register('jh-divider', JhDivider);

package/components/element/element.js

@@ -0,0 +1,94 @@
+/**
+ * SPDX-FileCopyrightText: 2025 Jack Henry
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { LitElement } from 'lit';
+
+let id = 0;
+
+export class JhElement extends LitElement {
+  /** @type {ElementInternals} */
+  #internals;
+  /** @type {number} */
+  #id;
+
+  constructor() {
+    super();
+    /** @type {ElementInternals} */
+    this.#internals = this.attachInternals();
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#id = id++;
+  }
+
+  // getter for unique id
+  get uniqueId() {
+    return this.#id;
+  }
+
+  // getter for element internals
+  /** @ignore */
+  get internals() {
+    return this.#internals;
+  }
+
+  dispatchCustomEvent(eventName, detail = {}) {
+    // gather base detail info
+    let baseDetail = {
+      form: {
+        formName: this.form?.name || null,
+        name: this.name || null,
+      },
+      state: {
+        value: this.value || null,
+      },
+      reference: {
+        originHost: this.localName, 
+      },
+      meta: {
+        timestamp: Date.now(), 
+      },
+    };
+
+    const keysToMerge = ['form', 'state', 'reference', 'meta'];
+    let finalDetail = { ...baseDetail };
+
+    // merge subclass properties into the base properties for each key
+    for (const key of keysToMerge) {
+      if (detail[key]) {
+        finalDetail[key] = { ...baseDetail[key], ...detail[key] };
+      }
+    }
+
+    // Handle any "extra" properties that aren't in the standard keys
+    Object.keys(detail).forEach(key => {
+      if (!keysToMerge.includes(key)) {
+        finalDetail[key] = detail[key];
+      }
+    });
+
+    // create and dispatch event
+    const event = new CustomEvent(eventName, {
+      detail: finalDetail,
+      bubbles: true,
+      composed: true,
+      cancelable: true,
+    });
+    this.dispatchEvent(event);
+  }
+
+  // register method to avoid custom element registry conflicts
+  static register(tagName, targetClass) {
+    if (customElements.get(tagName)) {
+      console.warn(
+        `Registry Conflict: <${tagName}> is already owned by another script.`
+      );
+      return;
+    }
+    customElements.define(tagName, targetClass);
+  }
+}

package/components/icon/icon.js

@@ -2,7 +2,8 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-import { LitElement, css, html } from 'lit';
+import { css, html } from 'lit';
+import { JhElement } from '../element/element.js';
 
 /**
  * @cssprop --jh-icon-color-fill - The icon color. Defaults to `--jh-color-content-secondary-enabled`.
@@ -11,14 +12,11 @@ import { LitElement, css, html } from 'lit';
  * @cssprop --jh-icon-size-medium - The icon size when `size="medium"`. Defaults to `--jh-dimension-600`.
  * @cssprop --jh-icon-size-large - The icon size when `size="large"`. Defaults to `--jh-dimension-900`.
  * @cssprop --jh-icon-size-extra-large - The icon size when `size="extra-large"`. Defaults to `--jh-dimension-1400`.
+ * @cssprop --jh-icon-size-extra-extra-large - The icon size when `size="extra-extra-large"`. Defaults to `--jh-dimension-2100`.
  * @slot default - Use to insert the icon SVG content.
  * @customElement jh-icon
  */
-export class JhIcon extends LitElement {
-
-  /** @type {ElementInternals} */
-  #internals;
-
+export class JhIcon extends JhElement {
   static get styles() {
     return css`
       :host {
@@ -60,6 +58,12 @@ export class JhIcon extends LitElement {
           var(--jh-dimension-1400)
         );
       }
+      :host([size='xx-large']) {
+        --icon-size: var(
+          --jh-icon-size-extra-extra-large,
+          var(--jh-dimension-2100)
+        );
+      }
       svg,
       ::slotted(*) {
         width: 100%;
@@ -79,11 +83,9 @@ export class JhIcon extends LitElement {
   }
   constructor() {
     super();
-    this.#internals = this.attachInternals();
-    this.#internals.role = 'graphics-symbol';
-    this.#internals.ariaHidden = 'true';
-
-    /** @type {'x-small'|'small'|'medium'|'large'|'x-large'} */
+    this.internals.role = 'graphics-symbol';
+    this.internals.ariaHidden = 'true';
+    /** @type {'x-small'|'small'|'medium'|'large'|'x-large'|'xx-large'} */
     this.size = 'medium';
   }
 
@@ -93,4 +95,4 @@ export class JhIcon extends LitElement {
     `;
   }
 }
-customElements.define('jh-icon', JhIcon);
+JhIcon.register('jh-icon', JhIcon);