@sapudex/web-components 2.48.0 → 2.49.0

package/src/AccordionSpotlight.ts

@@ -0,0 +1,321 @@
+import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
+import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
+import property from "@ui5/webcomponents-base/dist/decorators/property.js";
+import type { DefaultSlot, Slot } from "@ui5/webcomponents-base/dist/UI5Element.js";
+import slot from "@ui5/webcomponents-base/dist/decorators/slot-strict.js";
+import event from "@ui5/webcomponents-base/dist/decorators/event-strict.js";
+import jsxRenderer from "@ui5/webcomponents-base/dist/renderer/JsxRenderer.js";
+import { isDesktop } from "@ui5/webcomponents-base/dist/Device.js";
+import AccordionSpotlightTemplate from "./AccordionSpotlightTemplate.js";
+import AccordionSpotlightItem from "./AccordionSpotlightItem.js";
+import UDExButton from "./Button.js";
+import "@ui5/webcomponents-icons/dist/play.js";
+import "@ui5/webcomponents-icons/dist/pause.js";
+import type { ResizeObserverCallback } from "@ui5/webcomponents-base/dist/delegate/ResizeHandler.js";
+import ResizeHandler from "@ui5/webcomponents-base/dist/delegate/ResizeHandler.js";
+import { BreakpointUtils } from "./utils/Breakpoints.js";
+
+// Styles
+import AccordionSpotlightCss from "./generated/themes/AccordionSpotlight.css.js";
+
+export enum UDExAccordionSpotlightVerticalAlignment {
+  Top = "Top",
+  Center = "Center",
+}
+
+export enum UDExAccordionSpotlightPlacement {
+  Start = "Start",
+  End = "End",
+}
+
+export enum UDExAccordionSpotlightMediaMode {
+  Dynamic = "Dynamic",
+  Static = "Static",
+}
+
+/**
+ * @class
+ *
+ * <h3 class="comment-api-title">Overview</h3>
+ *
+ * Vertical accordion navigation with spotlight layout. Items are listed on the
+ * left; the expanded panel is displayed on the right (desktop) or inline below
+ * the heading (mobile). Follows the WAI-ARIA APG Accordion pattern.
+ *
+ * <h3>Usage</h3>
+ *
+ * For the <code>udex-accordion-spotlight</code>
+ * <h3>ES6 Module Import</h3>
+ *
+ * <code>import "@sapudex/web-components/dist/AccordionSpotlight.js";</code>
+ *
+ * @constructor
+ * @extends UI5Element
+ * @public
+ */
+@customElement({
+  tag: "udex-accordion-spotlight",
+  renderer: jsxRenderer,
+  styles: AccordionSpotlightCss,
+  template: AccordionSpotlightTemplate,
+  dependencies: [AccordionSpotlightItem, UDExButton],
+})
+
+/**
+ * Fired when the expanded item clicked.
+ *
+ * @public
+ * @param {AccordionSpotlightItem} [item] The accordion spotlight item that was clicked
+ */
+@event("item-click", { bubbles: true })
+
+class UDExAccordionSpotlight extends UI5Element {
+  eventDetails!: {
+    "item-click": { item: AccordionSpotlightItem },
+  };
+
+  /**
+   * The index of the currently expanded item (0-based).
+   * Derived from items' <code>selected</code> attribute; kept in sync by the parent.
+   *
+   * @private
+   */
+  @property({ type: Number, noAttribute: true })
+    _selectedIndex: number = 0;
+
+  /**
+   * Vertical alignment of the navigation sidebar relative to the content panel.
+   *
+   * @default "Top"
+   * @public
+   */
+  @property()
+    verticalAlignment: `${UDExAccordionSpotlightVerticalAlignment}` = UDExAccordionSpotlightVerticalAlignment.Top;
+
+  /**
+   * Placement of the navigation sidebar — "Start" (left) or "End" (right).
+   *
+   * @default "Start"
+   * @public
+   */
+  @property()
+    placement: `${UDExAccordionSpotlightPlacement}` = UDExAccordionSpotlightPlacement.Start;
+
+  /**
+   * Enables automatic cycling through items on an interval.
+   *
+   * @default false
+   * @public
+   */
+  @property({ type: Boolean })
+    autoPlay: boolean = false;
+
+  /**
+   * Interval in milliseconds between automatic item advances. Applies only when autoPlay is enabled.
+   *
+   * @default 5000
+   * @public
+   */
+  @property({ type: Number })
+    autoPlayInterval: number = 5000;
+
+  /**
+   * Defines the width of the navigation panel.
+   *
+   * @default "auto"
+   * @public
+   */
+  @property({ type: String })
+    tabWidth: string = "auto";
+
+  /**
+   * Controls how the media area behaves. In <code>Static</code> mode a single
+   * persistent media element (image or video) is displayed alongside the nav
+   * list and never changes when items are expanded. In <code>Dynamic</code>
+   * mode (default) each item provides its own content panel.
+   *
+   * @default "Dynamic"
+   * @public
+   */
+  @property()
+    mediaMode: `${UDExAccordionSpotlightMediaMode}` = UDExAccordionSpotlightMediaMode.Dynamic;
+
+  /**
+   * @private
+   */
+  @property({ type: Boolean, noAttribute: true })
+    _isMobile: boolean = false;
+
+  /**
+   * @private
+   */
+  @property({ type: Boolean, noAttribute: true })
+    _isPaused: boolean = false;
+
+  /**
+   * The slotted AccordionSpotlightItem elements.
+   *
+   * @public
+   */
+  @slot({ type: HTMLElement, "default": true, individualSlots: true })
+    items!: DefaultSlot<AccordionSpotlightItem>;
+
+  /**
+   * Defines optional content rendered below the navigation items.
+   * Use to place a button or any action element beneath the items.
+   *
+   * @slot footer
+   * @public
+   */
+  @slot({ type: HTMLElement })
+    footer!: Slot<HTMLElement>;
+
+  /**
+   * Persistent media area shown in <code>Static</code> media mode.
+   * Place an <code>&lt;img&gt;</code> or <code>&lt;video&gt;</code> element here;
+   * it remains visible regardless of which item is currently expanded.
+   *
+   * @slot media
+   * @public
+   */
+  @slot({ type: HTMLElement })
+    media!: Slot<HTMLElement>;
+
+  _handleResizeBound: ResizeObserverCallback;
+  _autoPlayTimer?: number;
+
+  constructor() {
+    super();
+    this._handleResizeBound = this._handleResize.bind(this);
+  }
+
+  onBeforeRendering() {
+    this._syncItemStates();
+  }
+
+  onAfterRendering() {
+    this._checkMobile();
+  }
+
+  onEnterDOM() {
+    ResizeHandler.register(this, this._handleResizeBound);
+
+    if (isDesktop()) {
+      this.setAttribute("desktop", "");
+    }
+
+    if (this.autoPlay) {
+      const prefersReducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+      if (prefersReducedMotion) {
+        this._isPaused = true;
+      } else {
+        this._startAutoPlay();
+      }
+    }
+  }
+
+  onExitDOM() {
+    ResizeHandler.deregister(this, this._handleResizeBound);
+    this._stopAutoPlay();
+  }
+
+  _handleResize(): void {
+    this._checkMobile();
+  }
+
+  _checkMobile() {
+    const isMobile = BreakpointUtils.isAtMost("S");
+    if (isMobile !== this._isMobile) {
+      this._isMobile = isMobile;
+    }
+  }
+
+  _syncItemStates() {
+    if (this.items.length === 0) {
+      return;
+    }
+
+    const foundIndex = this.items.findIndex(item => item.selected);
+    const activeIndex = foundIndex === -1 ? 0 : foundIndex;
+    this._selectedIndex = activeIndex;
+
+    this.items.forEach((item, index) => {
+      item.selected = index === activeIndex;
+      item._isMobile = this._isMobile;
+    });
+  }
+
+  _startAutoPlay(): void {
+    this._stopAutoPlay();
+    this._isPaused = false;
+    this._autoPlayTimer = window.setInterval(() => {
+      this._advanceItem();
+    }, this.autoPlayInterval);
+  }
+
+  _stopAutoPlay(): void {
+    if (this._autoPlayTimer !== undefined) {
+      window.clearInterval(this._autoPlayTimer);
+      this._autoPlayTimer = undefined;
+    }
+  }
+
+  _advanceItem(): void {
+    const count = this.items.length;
+    if (count === 0) {
+      return;
+    }
+
+    const next = (this._selectedIndex + 1) % count;
+    this._selectItem(next);
+  }
+
+  onPlayButtonClick(): void {
+    if (this._isPaused) {
+      this._startAutoPlay();
+    } else {
+      this._stopAutoPlay();
+      this._isPaused = true;
+    }
+  }
+
+  handleNavItemClick(e: MouseEvent) {
+    const btn = (e.target as HTMLElement).closest<HTMLElement>("[data-index]");
+    if (!btn) {
+      return;
+    }
+    const index = Number.parseInt(btn.dataset.index!);
+    this._selectItem(index);
+  }
+
+  private _selectItem(index: number) {
+    if (index === this._selectedIndex) {
+      return;
+    }
+
+    this._selectedIndex = index;
+    this.items.forEach((item, i) => { item.selected = i === index; });
+    const item = this.items[index];
+    this.fireDecoratorEvent("item-click", { item });
+  }
+
+  get playBtnIcon(): string {
+    return this._isPaused ? "play" : "pause";
+  }
+
+  get showFooterSlot(): boolean {
+    return this.footer?.length > 0;
+  }
+
+  get isStaticMedia(): boolean {
+    return this.mediaMode === UDExAccordionSpotlightMediaMode.Static;
+  }
+
+  get showMediaSlot(): boolean {
+    return this.isStaticMedia && this.media?.length > 0;
+  }
+}
+
+UDExAccordionSpotlight.define();
+
+export default UDExAccordionSpotlight;

package/src/AccordionSpotlightItem.ts

@@ -0,0 +1,117 @@
+import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
+import type { DefaultSlot, Slot } from "@ui5/webcomponents-base/dist/UI5Element.js";
+import slot from "@ui5/webcomponents-base/dist/decorators/slot-strict.js";
+import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
+import property from "@ui5/webcomponents-base/dist/decorators/property.js";
+import jsxRenderer from "@ui5/webcomponents-base/dist/renderer/JsxRenderer.js";
+
+import AccordionSpotlightItemTemplate from "./AccordionSpotlightItemTemplate.js";
+
+// Styles
+import AccordionSpotlightItemCss from "./generated/themes/AccordionSpotlightItem.css.js";
+
+/**
+ * @class
+ *
+ * <h3 class="comment-api-title">Overview</h3>
+ *
+ * A single item within the <code>udex-accordion-spotlight</code> component.
+ * Provides a heading button (<code>aria-expanded</code>) and an associated
+ * content region (<code>role="region"</code>).
+ *
+ * <h3>Usage</h3>
+ *
+ * For the <code>udex-accordion-spotlight-item</code>
+ * <h3>ES6 Module Import</h3>
+ *
+ * <code>import "@sapudex/web-components/dist/AccordionSpotlightItem.js";</code>
+ *
+ * @constructor
+ * @extends UI5Element
+ * @public
+ */
+@customElement({
+  tag: "udex-accordion-spotlight-item",
+  renderer: jsxRenderer,
+  styles: AccordionSpotlightItemCss,
+  template: AccordionSpotlightItemTemplate,
+})
+class UDExAccordionSpotlightItem extends UI5Element {
+  /**
+   * The label text shown in the heading button.
+   *
+   * @default ""
+   * @public
+   */
+  @property()
+    heading: string = "";
+
+  /**
+   * Optional descriptive subtext visible when the item is expanded.
+   *
+   * @default ""
+   * @public
+   */
+  @property()
+    subheading: string = "";
+
+  /**
+   * Whether this item is currently expanded.
+   * Set on the element directly to control the initial selection.
+   *
+   * @default false
+   * @public
+   */
+  @property({ type: Boolean })
+    selected: boolean = false;
+
+  /**
+   * Whether the parent is in mobile layout mode (managed by the parent component).
+   *
+   * @default false
+   * @private
+   */
+  @property({ type: Boolean, noAttribute: true })
+    _isMobile: boolean = false;
+
+  /**
+   * Zero-based index within the parent (managed by the parent component).
+   *
+   * @private
+   */
+  @property({ type: Number, noAttribute: true })
+    _index: number = 0;
+
+  /**
+   * The slotted content for this item's panel.
+   *
+   * @public
+   */
+  @slot({ type: Node, "default": true })
+    content!: DefaultSlot<Node>;
+
+  /**
+   * Defines the link(s) to be displayed in the tab header (vertical orientation only).
+   * Use this slot to add one or more udex-link elements to the tab button.
+   *
+   * @slot link
+   * @public
+   */
+  @slot({ type: HTMLElement })
+    link!: Slot<HTMLElement>;
+
+  get hasLinkSlot(): boolean {
+    return this.link && this.link.length > 0;
+  }
+
+  get linkSlotHtml(): string {
+    if (!this.link || this.link.length === 0) {
+      return "";
+    }
+    return this.link.map(l => l.outerHTML).join("");
+  }
+}
+
+UDExAccordionSpotlightItem.define();
+
+export default UDExAccordionSpotlightItem;

package/src/AccordionSpotlightItemTemplate.tsx

@@ -0,0 +1,7 @@
+import type AccordionSpotlightItem from "./AccordionSpotlightItem.js";
+
+export default function AccordionSpotlightItemTemplate(this: AccordionSpotlightItem) {
+  return (
+    <slot></slot>
+  );
+}

package/src/AccordionSpotlightTemplate.tsx

@@ -0,0 +1,107 @@
+import type AccordionSpotlight from "./AccordionSpotlight.js";
+import UDExButton from "./Button.js";
+import UDExButtonSize from "./types/ButtonSize.js";
+import UDExButtonDesign from "./types/ButtonDesign.js";
+
+export default function AccordionSpotlightTemplate(this: AccordionSpotlight) {
+  const rootClass = "udex-accordion-spotlight";
+
+  return (
+    <div class={`${rootClass}`}>
+      <div
+        class={`${rootClass}__nav`}>
+        {this.autoPlay && (
+          <UDExButton
+            class={`${rootClass}__play-button`}
+            design={UDExButtonDesign.Tertiary}
+            size={UDExButtonSize.Large}
+            icon={this.playBtnIcon}
+            onClick={this.onPlayButtonClick.bind(this)}
+          />
+        )}
+
+        <div class={`${rootClass}__nav-holder`}>
+          {this.items.map((item, index) => (
+            <>
+              <div class={`${rootClass}__nav-item`}>
+                <button
+                  id={item._id}
+                  class={`${rootClass}-item__button ${item.selected ? ` ${rootClass}-item__button--active` : ""}`}
+                  type="button"
+                  aria-expanded={item.selected}
+                  aria-controls={`${item._id}-controls`}
+                  data-index={String(index)}
+                  onClick={this.handleNavItemClick.bind(this)}>
+                  {item.heading}
+                </button>
+
+                {(!!item.subheading || item.hasLinkSlot) && (
+                  <div
+                    class={`${rootClass}-item__expand${item.selected ? ` ${rootClass}-item__expand--open` : ""}`}
+                    aria-hidden={item.selected ? undefined : "true"}
+                    inert={!item.selected}>
+                    <div class={`${rootClass}-item__expand-inner`}>
+                      {!!item.subheading && (
+                        <span class={`${rootClass}-item__subheading`}>
+                          {item.subheading}
+                        </span>
+                      )}
+                      {item.hasLinkSlot &&
+                        <div
+                          class={`${rootClass}-item__links`}
+                          dangerouslySetInnerHTML={{ __html: item.linkSlotHtml }}>
+                        </div>
+                      }
+                    </div>
+                  </div>
+                )}
+              </div>
+
+              {this._isMobile && !this.isStaticMedia && (
+                <div
+                  id={`${item._id}-controls`}
+                  class={`${rootClass}__panel${item.selected ? ` ${rootClass}__panel--open` : ""}`}
+                  role="region"
+                  aria-labelledby={item._id}
+                  aria-hidden={item.selected ? undefined : "true"}
+                  inert={!item.selected}>
+                  <div class={`${rootClass}__panel-inner`}>
+                    <slot name={item._individualSlot}></slot>
+                  </div>
+                </div>
+              )}
+            </>
+          ))}
+        </div>
+        {this.showFooterSlot && (
+          <div class={`${rootClass}__footer`}><slot name="footer"></slot></div>
+        )}
+      </div>
+
+      {this.showMediaSlot && (
+        <div class={`${rootClass}__media`}>
+          <slot name="media"></slot>
+        </div>
+      )}
+
+      {!this._isMobile && !this.isStaticMedia && (
+        <div class={`${rootClass}__content`}>
+          {this.items.map(item => (
+            <div
+              key={item.__id}
+              id={`${item._id}-controls`}
+              class={`${rootClass}__panel${item.selected ? ` ${rootClass}__panel--open` : ""}`}
+              role="region"
+              aria-labelledby={item._id}
+              aria-hidden={item.selected ? undefined : "true"}
+              inert={!item.selected}>
+              <div class={`${rootClass}__panel-inner`}>
+                <slot name={item._individualSlot}></slot>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/BusyIndicator.ts

@@ -1,7 +1,11 @@
 import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
+import property from "@ui5/webcomponents-base/dist/decorators/property.js";
 import BusyIndicator from "@ui5/webcomponents/dist/BusyIndicator.js";
 import jsxRenderer from "@ui5/webcomponents-base/dist/renderer/JsxRenderer.js";
 
+// Styles
+import BusyIndicatorCss from "./generated/themes/BusyIndicator.css.js";
+
 /**
  * @class
  *
@@ -23,10 +27,21 @@ import jsxRenderer from "@ui5/webcomponents-base/dist/renderer/JsxRenderer.js";
 @customElement({
   tag: "udex-busy-indicator",
   renderer: jsxRenderer,
-  styles: [BusyIndicator.styles],
+  styles: [BusyIndicator.styles, BusyIndicatorCss],
 })
 
-class UDExBusyIndicator extends BusyIndicator {}
+class UDExBusyIndicator extends BusyIndicator {
+  /**
+   * Renders the busy indicator inside a surface container — a semi-transparent backdrop
+   * with a white rounded card holding the indicator dots. Use this when the indicator
+   * overlays content where the dots alone would not meet accessibility contrast requirements.
+   *
+   * @default false
+   * @public
+   */
+  @property({ type: Boolean })
+    surfaceContainer!: boolean;
+}
 
 UDExBusyIndicator.define();