@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/docs/wm-textarea.md

@@ -0,0 +1,101 @@
+# `wm-textarea`
+
+Multi-line plain-text editing control with a drag handle for vertical resizing. Shares
+most functionality with wm-input. Use instead of native `<textarea>` in all Watermark UI.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `characterLimit` | `character-limit` | `number \| undefined` |  |  |  |
+| `disabled` | `disabled` | `boolean` | `false` |  |  |
+| `errorMessage` | `error-message` | `string \| undefined` |  |  |  |
+| `info` | `info` | `string \| undefined` |  |  |  |
+| `inputHeight` | `input-height` | `string` | `""` |  |  |
+| `inputWidth` | `input-width` | `string` | `""` |  |  |
+| `label` | `label` | `string` |  | ✓ |  |
+| `labelPosition` | `label-position` | `"left" \| "none" \| "top"` | `"top"` |  |  |
+| `placeholder` | `placeholder` | `string` | `""` |  |  |
+| `requiredField` | `required-field` | `boolean` | `false` |  |  |
+| `value` | `value` | `string` | `""` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmTextareaValueChanged` | `{ value: string; }` | ✓ |  |
+
+# wm-textarea
+
+## Purpose
+
+A multi-line plain-text input for collecting longer, free-form written responses, with a user-resizable height and the same validation, character limiting, and labeling features as wm-input.
+
+---
+
+## When to Use
+
+- **Collecting a narrative, description, or open-ended response** -- when a user needs to write more than a short phrase (a program description, assessment rationale, comment, or notes field), use Textarea to give them a multi-line editing surface.
+- **Accepting long-form text with a character cap** -- when the field has a meaningful maximum length (e.g., a mission statement capped at 500 characters), use character-limit to display a running count and turn it red at the limit, while still allowing free editing.
+- **Setting an initial height appropriate to the expected content volume** -- when the typical response will be longer or shorter than the default three lines, use input-height to size the field to match user expectations.
+- **Displaying supplementary guidance below the field** -- when the field benefits from a brief instruction that stays visible while the user types, use the info property to show it persistently below the input area.
+
+---
+
+## Do Not Use For
+
+- **Short, single-line values** -- if the expected value is a name, identifier, number, or any other brief string, use wm-input instead; Textarea signals to users that a longer response is expected and wastes vertical space for short values.
+
+---
+
+## Related Components
+
+- `<wm-input>` -- if the expected value fits on a single line, use Input; Textarea is only warranted when multi-line content is genuinely expected. The two share nearly identical props, events, and accessibility behavior, the choice is almost entirely single-line vs. multi-line.
+
+---
+
+## Accessibility
+
+- Setting an initial value via the value prop: value is a getter only; to pre-populate the field, set the text content of the element directly (e.g., <wm-textarea>initial value</wm-textarea>). Using value as a setter will not work.
+- Hard-blocking input beyond the character limit: Textarea intentionally does not prevent typing past character-limit; the application must enforce the limit on submission externally.
+- Omitting the label when hiding the visual label: label is required for accessibility even when label-position="none"; omitting it leaves the field unnamed for screen reader users.
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- `label` -- required; the field's accessible name even when label-position="none"
+- `labelPosition` -- "top", "left", or "none"
+- `value` -- getter only; reflects the current field value. To set an initial value, use the element's text content slot, not this prop
+- `placeholder` -- placeholder text shown when the field is empty
+- `characterLimit` -- maximum character count; displays a running count. Does not block typing.
+- `inputHeight` -- CSS height value for the textarea; defaults to three lines
+- `inputWidth` -- CSS width value for the textarea
+- `info` -- helper text displayed persistently below the field
+- `errorMessage` -- validation error text; announced via live region when set
+- `requiredField` -- marks the field as required
+- `disabled` -- disables the textarea
+
+---
+
+## Events
+
+- `wmTextareaValueChanged` -- fires on each change to the textarea value; detail includes { value: string }
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-timepicker.md

@@ -0,0 +1,122 @@
+# `wm-timepicker`
+
+Time input that lets users type a time or pick one from a dropdown list of 15-minute
+intervals. Supports 12-hour and 24-hour display and provides `reformatTime` and
+`isValidTime` utility methods. Use instead of native `<input type="time">`.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `disabled` | `disabled` | `boolean` | `false` |  |  |
+| `errorMessage` | `error-message` | `string \| undefined` |  |  |  |
+| `label` | `label` | `string` | `""` |  |  |
+| `labelPosition` | `label-position` | `"left" \| "none" \| "top"` | `"top"` |  |  |
+| `preselected` | `preselected` | `string \| undefined` |  |  |  |
+| `requiredField` | `required-field` | `boolean` | `false` |  |  |
+| `value` | `value` | `string` | `""` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmTimepickerInputBlurred` | `any` | ✓ |  |
+| `wmTimepickerTimeSelected` | `any` | ✓ |  |
+
+## Methods
+
+### `isValidTime(input: string) => Promise<boolean>`
+
+**Parameters**
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `input` | `string` | The time string to validate. |
+
+**Returns** `Promise<boolean>` -- `true` if the string is a valid time, `false` otherwise.
+
+### `reformatTime(format: "12" | "24", time: TimeFormat12 | TimeFormat24) => Promise<string>`
+
+**Parameters**
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `format` | `"12" \| "24"` | The target format: `"12"` for 12-hour (e.g. `"02:30 PM"`), `"24"` for
+24-hour (e.g. `"14:30"`). |
+| `time` | `string` | The time string to convert. Accepts both 12-hour and 24-hour input. |
+
+**Returns** `Promise<string>` -- The reformatted time string.
+
+# wm-timepicker
+
+## Purpose
+
+A form input that lets users specify a time of day either by typing directly into a text field or by selecting from a scrollable dropdown list of time increments.
+
+---
+
+## When to Use
+
+- **Collecting a specific time of day in a form** -- Timepicker is the standard input, offering both typed entry for precision and a dropdown for browsing.
+- **Pre-focusing the dropdown on a relevant time** -- when a default or suggested time exists (e.g., the start of a business day), use the preselected property in 24hr format to open the dropdown already positioned at that time.
+- **Pairing with Datepicker for a full date-and-time value** -- when a form requires both a date and a time of day, pair Timepicker with wm-datepicker to collect each value with its purpose-built input; Timepicker handles the time portion only.
+
+---
+
+## Do Not Use For
+
+- **Collecting a date with no time component** -- if the value is a date only, use wm-datepicker alone; adding Timepicker implies a time dimension that may not exist in the data.
+- **Plain text entry for a time value** -- a plain wm-input offers no time validation, no format guidance, no dropdown for browsing, and no reformatTime or isValidTime utilities; whenever a time of day is being collected, Timepicker is always the correct component.
+
+---
+
+## Related Components
+
+- `<wm-datepicker>` -- if the value is a date rather than a time, use Datepicker; when both are needed, the two should be paired as separate inputs rather than combined into one.
+- `<wm-input>` -- a plain Input has no time-specific behavior; whenever the value being collected is a time of day, Timepicker is always the right choice over a generic text field.
+- `<wm-select>` -- if the user is choosing from a small, fixed list of named time slots or periods (e.g., "Morning", "Afternoon", "Evening") rather than a precise time of day, Select may be more appropriate; Timepicker is for collecting an actual clock time.
+
+---
+
+## Accessibility
+
+- Omitting the label when hiding the visual label: label is required for accessibility even when label-position="none"; omitting it leaves the field unnamed for screen reader users.
+- Passing preselected in 12hr format: the preselected property expects a 24hr time string; passing a 12hr format (e.g., "09:00 AM") will fail to parse and the dropdown will fall back to 09:00 AM regardless.
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- `label` -- required for accessibility even when label-position="none"
+- `labelPosition` -- "top", "left", or "none"
+- `preselected` -- a 24hr time string used to pre-position the dropdown when it opens; must be in 24hr format
+- `value` -- the current time value of the input
+- `errorMessage` -- validation error text displayed below the field
+- `requiredField` -- marks the field as required
+- `disabled` -- disables the input and dropdown button
+
+---
+
+## Events
+
+- `wmTimepickerTimeSelected` -- fires when the user selects a time or types a complete valid time
+- `wmTimepickerInputBlurred` -- fires when the input loses focus
+
+---
+
+## Methods
+
+- `isValidTime(input: string)` -- returns whether the provided time string is valid
+- `reformatTime(format: "12" | "24", time)` -- converts a time string between 12hr and 24hr formats
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-toggletip.md

@@ -0,0 +1,86 @@
+# `wm-toggletip`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `label` | `label` | `string \| undefined` |  |  |  |
+| `targetSize` | `target-size` | `"large" \| "small"` | `"small"` |  |  |
+| `toggletipType` | `toggletip-type` | `"ai" \| "info"` | `"info"` |  |  |
+| `tooltip` | `tooltip` | `string` |  | ✓ |  |
+| `tooltipPosition` | `tooltip-position` | `"bottom" \| "bottom-left" \| "bottom-right" \| "left" \| "right" \| "top" \| "top-left" \| "top-right"` | `"bottom-right"` |  |  |
+
+# wm-toggletip
+
+## Purpose
+
+A small information button (an 'i' icon) that reveals a contextual explanation bubble when clicked, used to clarify a nearby control or piece of content without navigating away or interrupting the workflow.
+
+---
+
+## When to Use
+
+- Use a Toggletip to surface a brief supplementary explanation on demand without cluttering the interface.
+- **Explaining a concept or term inline** -- when a page contains terminology, metrics, or calculated values that users may not recognize, a Toggletip lets curious users get the definition without requiring everyone to read it by default.
+- **Providing AI-related contextual information** -- when content or a control is AI-generated or AI-assisted, use toggletip-type="ai" to visually signal the AI context and explain what it means or how it was produced.
+- **Adding help content to a standalone control** -- when the Toggletip is placed away from tight inline content (e.g., a section header or card), use target-size="large" to meet touch target size requirements and make it easier to tap on mobile.
+
+---
+
+## Do Not Use For
+
+- **Describing what a button does when clicked** -- a tooltip on hover/focus describes button behavior; a Toggletip on click provides contextual information about content or a control. Using a Toggletip to describe button behavior is the wrong pattern.
+- **Lengthy or rich content** -- if the explanation requires formatting, links, multiple paragraphs, or interactive content, it belongs in a Flyout or another container, not a Toggletip.
+- **System messages, errors, or alerts** -- Toggletip is strictly a user-initiated help tool and should never be used to surface notifications that users might miss if they do not click the icon.
+
+---
+
+## Related Components
+
+_None_
+
+---
+
+## Accessibility
+
+- Omitting the label property: the label is required for accessibility and must describe the Toggletip's specific purpose for screen reader users (e.g., "More information about weighted GPA"); leaving it blank renders the button meaningless to non-visual users.
+
+---
+
+## Variants / Types
+
+- `toggletip-type="info"` -- standard information icon; use for general contextual help
+- `toggletip-type="ai"` -- AI-branded icon; use when the explanation relates to AI-generated or AI-assisted content
+- `target-size="small"` -- compact touch target for inline or dense contexts
+- `target-size="large"` -- larger touch target for standalone placements or mobile contexts
+
+---
+
+## Props
+
+- `tooltip` -- required; the text displayed in the explanation bubble
+- `label` -- required for accessibility; the screen-reader-only description that gives the Toggletip specific meaning in context. The visible hover tooltip always reads "More information" and cannot be changed.
+- `tooltipPosition` -- controls where the bubble appears; auto-corrects if the configured position would render off-screen
+
+---
+
+## Events
+
+_None exposed_
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-uploader.md

@@ -0,0 +1,114 @@
+# `wm-uploader`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `buttonText` | `button-text` | `string` |  | ✓ |  |
+| `dropArea` | `drop-area` | `"component" \| "page"` | `"component"` |  |  |
+| `errorMessage` | `error-message` | `string \| undefined` |  |  |  |
+| `fileTypes` | `file-types` | `string` | `"pdf txt log xml doc docx xls xlsx ppt pptx gif jpg jpeg png csv"` |  |  |
+| `icon` | `icon` | `string` |  | ✓ |  |
+| `label` | `label` | `string \| undefined` |  |  |  |
+| `maxFiles` | `max-files` | `number \| undefined` |  |  |  |
+| `maxSize` | `max-size` | `string \| undefined` |  |  |  |
+| `requiredField` | `required-field` | `boolean \| undefined` |  |  |  |
+| `showInfo` | `show-info` | `"none" \| "size" \| "time"` | `"time"` |  |  |
+| `uploaderType` | `uploader-type` | `"drop" \| "select"` | `"select"` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmUploaderFilesSelected` | `File[]` | ✓ |  |
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | One or more wm-file children representing the current file list. |
+
+# wm-uploader
+
+## Purpose
+
+A file upload component that lets users select or drag-and-drop files for later access, managing the file list, upload progress, and per-file actions (preview, download, delete) in a single integrated surface.
+
+---
+
+## When to Use
+
+- **Uploading files that will be stored and accessed later** -- when users need to attach supporting documents, evidence files, or other assets to a record (not to import data), Uploader is the right component; it is explicitly designed for file storage workflows, not data ingestion.
+- **File upload is part of the user's primary workflow** -- use the drop variant when users frequently upload documents and benefit from a prominent drag-and-drop area; use the select variant when uploading is a secondary action and a compact button trigger is more appropriate.
+- **Enforcing file type, size, or count constraints** -- when the upload has restrictions, use file-types, max-size, and max-files to communicate those constraints visibly to users; the component surfaces the constraints in the UI.
+- **Providing per-file actions after upload** -- when users need to preview, download, or delete individual uploaded files, use file-actions on each wm-file child to configure which actions are available per file.
+
+---
+
+## Do Not Use For
+
+- **Read-only file display** -- if no new files need to be uploaded and the user only needs to view, download, or delete existing files, use wm-file-list instead; Uploader adds unnecessary upload affordances when no upload action is required.
+- **Full-page drop zone when multiple upload areas or competing page interactions exist** -- drop-area="page" is only appropriate when uploading is the singular primary action on that page.
+- **Not keeping progress up to date on wm-file during upload** -- the progress property must be kept current during upload to ensure the progress bar renders correctly and screen readers receive accurate status announcements. This is mandatory, not optional.
+
+---
+
+## Related Components
+
+- `<wm-file-list>` -- if no new files need to be uploaded and the use case is purely displaying and acting on existing files, use File List; Uploader is only warranted when the user needs to add new files. The two are commonly paired: Uploader to add, File List to display files from a different source.
+- `<wm-button>` with a custom file input -- Uploader handles progress tracking, error states, per-file actions, accessibility, and responsive behavior that a bare button cannot; always prefer Uploader for file upload workflows.
+
+---
+
+## Accessibility
+
+_Not documented_
+
+---
+
+## Variants / Types
+
+- `uploader-type="select"` -- a compact button trigger for file selection
+- `uploader-type="drop"` -- a prominent drag-and-drop area
+- `drop-area="component"` -- the drop zone is scoped to the component itself
+- `drop-area="page"` -- the entire page acts as a drop zone; only appropriate when uploading is the singular primary action on the page
+
+---
+
+## Props
+
+- `buttonText` -- required; the label for the upload trigger button
+- `uploaderType` -- "select" or "drop"
+- `dropArea` -- "component" or "page"; controls the scope of the drag-and-drop zone
+- `fileTypes` -- accepted file types (e.g., ".pdf,.docx")
+- `maxSize` -- maximum file size as a string (e.g., "10MB")
+- `maxFiles` -- maximum number of files that can be uploaded at once
+- `showInfo` -- controls what metadata is shown per file: "size", "time", or "none"
+- `label` -- optional visible label above the uploader
+- `icon` -- icon displayed in the drop zone area
+- `errorMessage` -- validation error text displayed below the component
+- `requiredField` -- marks the uploader as required
+
+---
+
+## Events
+
+- `wmUploaderFilesSelected` -- fires when the user selects or drops files; detail is a File[] array
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-wrapper.md

@@ -0,0 +1,7 @@
+# `wm-wrapper`
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmWrapperLoaded` | `void` | ✓ |  |

package/dist/esm/app-globals-466ed44b.js

@@ -0,0 +1,101 @@
+import './index-3425d80d.js';
+
+const version = "5.31.0-alpha.1";
+
+// PRINT RIPPLE VERSION IN CONSOLE
+// test envs return 0 for plugin.length
+// do not print version number there as it causes issues
+if (window.navigator.plugins.length > 0) {
+    console.log("%cRipple component library %c%s", "color: #575195; font-weight: bold", "font-weight: bold", version);
+}
+// Dispatching events to track whether user is navigating with keyboard or mouse
+// no longer necessary for keyboard focus indicators (thanks to :focus-visible)
+// but still used in several components for other things (search for isTabbing)
+function wmComponentKeys(ev) {
+    if (ev.key == "Tab") {
+        var event = new Event("wmUserIsTabbing");
+        window.dispatchEvent(event);
+        document.querySelector("body").classList.add("wmcl-user-is-tabbing");
+    }
+    if (ev.key == "ArrowLeft" || ev.key == "ArrowUp" || ev.key == "ArrowRight" || ev.key == "ArrowDown") {
+        var event = new Event("wmUserIsKeying");
+        window.dispatchEvent(event);
+        document.querySelector("body").classList.add("wmcl-user-is-keying");
+    }
+}
+function wmComponentMouseDownOnce() {
+    var event = new Event("wmUserIsNotTabbing");
+    window.dispatchEvent(event);
+    document.querySelector("body").classList.remove("wmcl-user-is-tabbing");
+    document.querySelector("body").classList.remove("wmcl-user-is-keying");
+}
+window.addEventListener("keydown", wmComponentKeys);
+window.addEventListener("mousedown", wmComponentMouseDownOnce);
+// TOOLTIP
+// Add a tooltip element
+// This allows tooltips to be always at the highest stacking context (always on top)
+// Element is added withing a container to avoid performance impact
+const tooltipContainer = document.createElement("div");
+tooltipContainer.id = "wm-tooltip-container";
+const tooltipEl = document.createElement("div");
+tooltipEl.id = "wm-tooltip";
+tooltipEl.classList.add("wm-tooltip");
+tooltipEl.setAttribute("popover", "manual");
+tooltipEl.setAttribute("aria-hidden", "true");
+const tooltipStyles = document.createElement("style");
+tooltipStyles.textContent = `
+.wm-tooltip {
+  position: fixed;
+  overflow: hidden;
+  pointer-events: none;
+  line-height: normal;
+  font-family: inherit;
+  font-size: 0.875rem;
+  text-transform: none;
+  font-weight: normal;
+  background: var(--wmcolor-tooltip-background);
+  color: var(--wmcolor-tooltip-text);
+  z-index: 999999;
+  max-width: var(--wmTooltipMaxWidth, 13.75rem);
+  margin-right: 1.5rem;
+  padding: 0.375rem;
+  transition-property: opacity;
+  transition-delay: 0s;
+  opacity: 0;
+  inset: unset;
+  top: 0;
+  left: 0;
+  transform: translateZ(0);
+  will-change: transform;
+  transform: translate(var(--wmTooltipLeft), var(--wmTooltipTop));
+  border: none;
+}
+
+.wm-tooltip:popover-open {
+  opacity: 0;
+}
+
+.wm-tooltip.show {
+  transition-delay: 500ms;
+  opacity: 1;
+}
+`;
+const body = document.querySelector("body");
+if (body) {
+    document.head.appendChild(tooltipStyles);
+    tooltipContainer.appendChild(tooltipEl);
+    body.appendChild(tooltipContainer);
+}
+else {
+    document.addEventListener("DOMContentLoaded", () => {
+        const body = document.querySelector("body");
+        document.head.appendChild(tooltipStyles);
+        tooltipContainer.appendChild(tooltipEl);
+        body.appendChild(tooltipContainer);
+    });
+}
+const globalFn = () => { };
+
+const globalScripts = globalFn;
+
+export { globalScripts as g };

package/dist/esm/loader.js

@@ -1,6 +1,6 @@
 import { b as bootstrapLazy } from './index-3425d80d.js';
 export { s as setNonce } from './index-3425d80d.js';
-import { g as globalScripts } from './app-globals-0d90343d.js';
+import { g as globalScripts } from './app-globals-466ed44b.js';
 
 const defineCustomElements = async (win, options) => {
   if (typeof window === 'undefined') return undefined;