@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/collection/components/wm-toggletip/wm-toggletip.js

@@ -1,5 +1,54 @@
 import { Host, h } from "@stencil/core";
 import { showTooltip, hideTooltip, shouldOpenUp, shouldOpenDown, shouldShiftLeft, shouldShiftRight, intl, debounce, findAllScrollableParents, getCumulativeScrollOffset, } from "../../global/functions";
+/**
+ * Toggletip button that shows a small informational panel when clicked. Two visual types:
+ * `'info'` renders an info icon button; `'ai'` renders an animated AI sparkle icon. The
+ * panel content is provided via the `tooltip` prop and is announced to screen readers via
+ * an `aria-live` region.
+ *
+ * @keyboardInteraction
+ * - **Enter / Space**: Opens or toggles the toggletip panel.
+ * - **Escape**: Closes the panel without propagating (will not close a parent modal).
+ * - **Tab**: Closes the panel and advances focus to the next element.
+ *
+ * @accessibility
+ * - `label` sets the `aria-label` on the trigger button — required even though the button
+ *   has a visual icon.
+ * - The panel content is announced via `role="status"` / `aria-live="polite"` when opened,
+ *   and re-announced if the button is activated while the panel is already open.
+ * - A hover/focus tooltip shows `"More information"` (info type) or `"Powered by AI"` (ai
+ *   type) while the panel is closed.
+ *
+ * @usageNotes
+ * - Both `label` and `tooltip` are required; the component logs a console error on load if
+ *   either is missing.
+ * - `tooltip-position` is the preferred opening direction; the component auto-corrects it if
+ *   the panel would overflow the viewport.
+ *
+ * @example {html} Info toggletip
+ * <wm-toggletip
+ *   label="More about this field"
+ *   tooltip="This field accepts ISO 8601 dates.">
+ * </wm-toggletip>
+ *
+ * @example {react} Info toggletip
+ * <WmToggletip label="More about this field" tooltip="This field accepts ISO 8601 dates." />
+ *
+ * @example {html} AI toggletip
+ * <wm-toggletip
+ *   toggletip-type="ai"
+ *   label="AI-generated content"
+ *   tooltip="This summary was generated by AI and may contain errors.">
+ * </wm-toggletip>
+ *
+ * @example {react} AI toggletip
+ * <WmToggletip
+ *   toggletipType="ai"
+ *   label="AI-generated content"
+ *   tooltip="This summary was generated by AI and may contain errors." />
+ *
+ * @category Communication
+ */
 export class Toggletip {
     constructor() {
         this.scrollableParents = [];
@@ -229,11 +278,11 @@ export class Toggletip {
         }
     }
     render() {
-        return (h(Host, { key: '81915f49745dada074e724bf80f94d0992a0ac9f', class: `size-${this.targetSize}` }, h("button", { key: '5e00d8e3b6d7a8c8141130ac14f6c2720d672ec2', ref: (el) => (this.buttonEl = el), class: "button", type: "button", "aria-label": this.label, popoverTarget: "toggletip", popoverTargetAction: "toggle", onClick: () => this.open(),
+        return (h(Host, { key: 'ddac8497dcda9e0189cce22d3dbf1155fb87dc1f', class: `size-${this.targetSize}` }, h("button", { key: 'e3b137bd798f71756e39aa1df07d3aac1ed5e4c0', ref: (el) => (this.buttonEl = el), class: "button", type: "button", "aria-label": this.label, popoverTarget: "toggletip", popoverTargetAction: "toggle", onClick: () => this.open(),
             // In order to position the tooltip identically to the toggletip, its presence is determined by these four events
-            onMouseEnter: () => !this.isOpen && showTooltip(this.toggletipPosition, this.el, this.tooltipMessage), onMouseLeave: () => hideTooltip(), onFocus: () => !this.isOpen && showTooltip(this.toggletipPosition, this.el, this.tooltipMessage), onBlur: () => this.handleBlur() }, this.renderIcon()), h("div", { key: 'c5786961cb7691c17cc7ebb4f1333d9ec3155eec', popover: "", ref: (el) => (this.toggletipEl = el), class: `toggletip ${this.targetSize} ${this.isHidden ? "hidden" : ""}`, id: "toggletip",
+            onMouseEnter: () => !this.isOpen && showTooltip(this.toggletipPosition, this.el, this.tooltipMessage), onMouseLeave: () => hideTooltip(), onFocus: () => !this.isOpen && showTooltip(this.toggletipPosition, this.el, this.tooltipMessage), onBlur: () => this.handleBlur() }, this.renderIcon()), h("div", { key: '65fb469a82de024d88eb7f3f60f16888dd2c8183', popover: "", ref: (el) => (this.toggletipEl = el), class: `toggletip ${this.targetSize} ${this.isHidden ? "hidden" : ""}`, id: "toggletip",
             // @ts-ignore - despite what Typescript says, this is a valid event for popover elements
-            onToggle: (ev) => this.handlePopoverToggle(ev) }, this.tooltip), h("div", { key: '407093c6d04a498b1ea201fe2ef52295ff111e98', ref: (el) => (this.liveRegionEl = el), class: "live-region sr-only", role: "status", "aria-live": "polite", "aria-atomic": "true" })));
+            onToggle: (ev) => this.handlePopoverToggle(ev) }, this.tooltip), h("div", { key: 'c3cd8f6083ca5eedbdfb8efa4a60231c9dfb40f8', ref: (el) => (this.liveRegionEl = el), class: "live-region sr-only", role: "status", "aria-live": "polite", "aria-atomic": "true" })));
     }
     static get is() { return "wm-toggletip"; }
     static get encapsulation() { return "shadow"; }
@@ -261,7 +310,13 @@ export class Toggletip {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Accessible label for the trigger button. Also shown as a hover/focus tooltip\nwhile the panel is closed. Required for screen reader users."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "label",
@@ -278,7 +333,13 @@ export class Toggletip {
                 "required": true,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Content displayed inside the toggletip panel when opened. Also announced\nvia an `aria-live` region when the panel opens."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "tooltip",
@@ -301,7 +362,13 @@ export class Toggletip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Preferred opening direction for the panel. Auto-corrected if the panel would\noverflow the viewport."
+                        }, {
+                            "name": "default",
+                            "text": "\"bottom-right\""
+                        }],
                     "text": ""
                 },
                 "attribute": "tooltip-position",
@@ -319,7 +386,13 @@ export class Toggletip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Size of the trigger button icon. `'large'` satisfies WCAG 2.5.8 touch\ntarget requirements."
+                        }, {
+                            "name": "default",
+                            "text": "\"small\""
+                        }],
                     "text": ""
                 },
                 "attribute": "target-size",
@@ -337,7 +410,13 @@ export class Toggletip {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Visual style of the trigger icon. `'info'` shows an info icon; `'ai'` shows\nan animated sparkle icon."
+                        }, {
+                            "name": "default",
+                            "text": "\"info\""
+                        }],
                     "text": ""
                 },
                 "attribute": "toggletip-type",

package/dist/collection/components/wm-uploader/wm-uploader.js

@@ -1,6 +1,77 @@
 import { h, Host, forceUpdate, } from "@stencil/core";
 import { uploaderMessages } from "../../global/intl";
 import { intl, hideTooltip, showTooltip } from "../../global/functions";
+/**
+ * File upload component for attaching files. Composed of a trigger button and a list of
+ * wm-file children. Two variants: `'select'` opens the browser file picker; `'drop'` adds a
+ * drag-and-drop area. The component emits events when files are selected and when file
+ * actions are triggered — the application is responsible for validation, upload, and managing
+ * the file list. Use wm-file-list instead when displaying files without uploading.
+ *
+ * @slot - One or more wm-file children representing the current file list.
+ *
+ * @accessibility
+ * - The number of in-progress uploads and aggregate upload percentage are announced via
+ *   `aria-live` regions.
+ * - Deletion focus is managed automatically: moves to the next file, then the previous file,
+ *   then the upload button.
+ * - The `progress` prop on wm-file children must be kept up to date for proper screen reader
+ *   accessibility.
+ *
+ * @usageNotes
+ * - `button-text` is required.
+ * - Validate files (type, size, count) in the `wmUploaderFilesSelected` handler; set
+ *   `error-message` on the uploader or on individual wm-file elements externally.
+ * - Announce file deletions to screen readers using wm-snackbar.
+ * - `drop-area="page"` expands the drop zone to the full page while dragging; only valid
+ *   when `uploader-type="drop"`.
+ *
+ * @example {html} Select variant
+ * <wm-uploader button-text="Attach files" icon="#attach" label="Project documents">
+ *   <wm-file id="f1" name="proposal" type="pdf" size="1.2 MB"></wm-file>
+ * </wm-uploader>
+ *
+ * @example {react} Select variant with file list management
+ * // wmUploaderFilesSelected emits a FileList -- use Array.from() to iterate.
+ * // Extract name (without extension) and type (extension only) for each wm-file child.
+ * // wmFileDelete fires on the wm-file element; use e.target.id to identify which to remove.
+ * // showInfo on the uploader propagates automatically to all wm-file children.
+ * let nextId = 1;
+ * const [files, setFiles] = useState([]);
+ *
+ * const handleFilesSelected = (e) => {
+ *   const newFiles = Array.from(e.detail).map((file) => {
+ *     const lastDot = file.name.lastIndexOf(".");
+ *     const name = lastDot > 0 ? file.name.slice(0, lastDot) : file.name;
+ *     const type = lastDot > 0 ? file.name.slice(lastDot + 1) : "file";
+ *     return { id: String(nextId++), name, type, size: `${(file.size / 1024).toFixed(1)} KB` };
+ *   });
+ *   setFiles((prev) => [...prev, ...newFiles]);
+ * };
+ *
+ * const handleDelete = (e) => {
+ *   const id = e.target.id;
+ *   setFiles((prev) => prev.filter((f) => f.id !== id));
+ * };
+ *
+ * <WmUploader buttonText="Attach files" icon="#attach" label="Project documents" showInfo="size"
+ *   onWmUploaderFilesSelected={handleFilesSelected}>
+ *   {files.map((f) => (
+ *     <WmFile key={f.id} id={f.id} name={f.name} type={f.type} size={f.size}
+ *       onWmFileDelete={handleDelete} />
+ *   ))}
+ * </WmUploader>
+ *
+ * @example {html} Drop variant
+ * <wm-uploader uploader-type="drop" button-text="Upload files" icon="#upload">
+ * </wm-uploader>
+ *
+ * @example {react} Drop variant
+ * <WmUploader uploaderType="drop" buttonText="Upload files" icon="#upload"
+ *   onWmUploaderFilesSelected={handleFilesSelected} />
+ *
+ * @category Form Inputs
+ */
 export class Uploader {
     constructor() {
         this.batchCount = 0; // used to calculate the aggregate upload progress
@@ -316,9 +387,9 @@ export class Uploader {
         return (h("div", { class: `drop-area -${this.dropArea}`, ref: (el) => (this.dropAreaEl = el), onDragEnter: (ev) => this.handleDragEnter(ev), onDragOver: (ev) => this.handleDragOver(ev), onDragLeave: (ev) => this.handleDragLeave(ev), onDrop: (ev) => this.handleDrop(ev) }, this.dropArea == "page" && (h("div", { ref: (el) => (this.dropOverlayEl = el), class: "drop-overlay", popover: "manual" }, h("span", { class: "upload-arrow" }), h("span", null, "Drop to Upload")))));
     }
     render() {
-        return (h(Host, { key: 'b648d4def7e7c2288b05f4a11979104c3d6a5c42', class: `-${this.dropArea}` }, this.uploaderType == "drop" && this.renderDropArea(), this.label && this.renderLabel(), this.renderHeader(), this.renderListContainer(), h("div", { key: '44af23ab572d796da9e677861fa6f6463328d447', ref: (el) => (this.assertiveLiveRegionEl = el), class: "live-region sr-only", "aria-live": "assertive" // since it's directly linked to the action the user took, it should be read in priority. With polite, some messages get dismissed in favor of the page title
+        return (h(Host, { key: 'ea1278a812caed995ebcc9b895e34ff12f5d06c7', class: `-${this.dropArea}` }, this.uploaderType == "drop" && this.renderDropArea(), this.label && this.renderLabel(), this.renderHeader(), this.renderListContainer(), h("div", { key: '674d1a5a2ef621337fe7d73a5fa07cac8dba45f3', ref: (el) => (this.assertiveLiveRegionEl = el), class: "live-region sr-only", "aria-live": "assertive" // since it's directly linked to the action the user took, it should be read in priority. With polite, some messages get dismissed in favor of the page title
             ,
-            "aria-atomic": "true" }), h("div", { key: '5ae821400d1b569698206a17b20d1bd1c0328d82', ref: (el) => (this.politeLiveRegionEl = el), class: "live-region sr-only", "aria-live": "polite", "aria-atomic": "true" })));
+            "aria-atomic": "true" }), h("div", { key: '13560fdcf221bbd60fa188abf88189e0f1d1a75d', ref: (el) => (this.politeLiveRegionEl = el), class: "live-region sr-only", "aria-live": "polite", "aria-atomic": "true" })));
     }
     static get is() { return "wm-uploader"; }
     static get encapsulation() { return "shadow"; }
@@ -346,7 +417,10 @@ export class Uploader {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Optional label displayed above the upload button. Use when the uploader is\nrequired (pair with `required-field`) or needs a descriptive heading."
+                        }],
                     "text": ""
                 },
                 "attribute": "label",
@@ -363,7 +437,13 @@ export class Uploader {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "File selection method. `'select'` opens the browser file picker; `'drop'`\nadds a drag-and-drop area."
+                        }, {
+                            "name": "default",
+                            "text": "\"select\""
+                        }],
                     "text": ""
                 },
                 "attribute": "uploader-type",
@@ -381,7 +461,13 @@ export class Uploader {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Scope of the drop zone when `uploader-type=\"drop\"`. `'component'` limits\nthe drop area to the component; `'page'` expands it to cover the full page while dragging."
+                        }, {
+                            "name": "default",
+                            "text": "\"component\""
+                        }],
                     "text": ""
                 },
                 "attribute": "drop-area",
@@ -399,7 +485,13 @@ export class Uploader {
                 "required": true,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Label text on the upload trigger button, e.g. `'Attach files'`. Should\nmatch the action verb used in any surrounding instructions."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "button-text",
@@ -416,7 +508,10 @@ export class Uploader {
                 "required": true,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Icon displayed on the upload button. Accepts the same formats as wm-button:\n`'#icon-name'` for a Ripple icon or `'/path/to/file.svg#symbol-id'` for a local SVG\nsprite."
+                        }],
                     "text": ""
                 },
                 "attribute": "icon",
@@ -433,7 +528,13 @@ export class Uploader {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Space-separated file extensions displayed to the user as accepted types\n(e.g. `'pdf docx xlsx'`). Actual validation must be handled in the\n`wmUploaderFilesSelected` handler."
+                        }, {
+                            "name": "default",
+                            "text": "\"pdf txt log xml doc docx xls xlsx ppt pptx gif jpg jpeg png csv\""
+                        }],
                     "text": ""
                 },
                 "attribute": "file-types",
@@ -451,7 +552,10 @@ export class Uploader {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Maximum file size displayed to the user (e.g. `'100 MB'`). Validation must\nbe handled in the `wmUploaderFilesSelected` handler."
+                        }],
                     "text": ""
                 },
                 "attribute": "max-size",
@@ -468,7 +572,10 @@ export class Uploader {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Maximum number of files displayed to the user. Disables the upload button\nwhen reached. Validation must be handled in the application."
+                        }],
                     "text": ""
                 },
                 "attribute": "max-files",
@@ -485,7 +592,10 @@ export class Uploader {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Puts the uploader in an error state with this message (e.g. `'Please add at\nleast one file'`)."
+                        }],
                     "text": ""
                 },
                 "attribute": "error-message",
@@ -502,7 +612,13 @@ export class Uploader {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Displays a required-field asterisk next to the label. Must be used together\nwith the `label` prop."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "required-field",
@@ -519,7 +635,13 @@ export class Uploader {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Which metadata to show for each wm-file child in the list."
+                        }, {
+                            "name": "default",
+                            "text": "\"time\""
+                        }],
                     "text": ""
                 },
                 "attribute": "show-info",
@@ -543,7 +665,13 @@ export class Uploader {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user selects files via the file picker or drops them onto\nthe drop zone. The host application should validate the files (type, size, count) and\nbegin the upload process."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "File[] \u2014 array of browser `File` objects selected or dropped by the user."
+                        }],
                     "text": ""
                 },
                 "complexType": {

package/dist/collection/components/wm-wrapper/wm-wrapper.js

@@ -1,3 +1,6 @@
+/**
+ * @category Layout Containers
+ */
 export class Wrapper {
     componentDidLoad() {
         this.wmWrapperLoaded.emit();

package/dist/collection/global/services/__mocks__/http-service.js

@@ -79,7 +79,7 @@ const navigatorResponse = {
         },
         {
             description: "something with an id containing admin",
-            iconUrl: "not.important",
+            iconUrl: "https://cdn.watermarkinsights.com/images/login/platform.svg",
             id: "banana_admin_shoe",
             linkUrl: "irrelevant",
             name: "Platform Admin",