@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

package/dist/docs/skill/wm-uploader.md

@@ -0,0 +1,154 @@
+### Uploader
+- **Element:** `<wm-uploader>`
+
+**Purpose:** 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.
+
+**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.
+
+**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
+
+**Usage notes:**
+
+- `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"`.
+
+**Props:**
+- `button-text` -- Label text on the upload trigger button, e.g. `'Attach files'`. Should
+match the action verb used in any surrounding instructions. _(required)_
+- `drop-area` -- Scope of the drop zone when `uploader-type="drop"`. `'component'` limits
+the drop area to the component; `'page'` expands it to cover the full page while dragging. _(type: `"component" | "page"`; default: `"component"`)_
+- `error-message` -- Puts the uploader in an error state with this message (e.g. `'Please add at
+least one file'`).
+- `file-types` -- Space-separated file extensions displayed to the user as accepted types
+(e.g. `'pdf docx xlsx'`). Actual validation must be handled in the
+`wmUploaderFilesSelected` handler. _(default: `"pdf txt log xml doc docx xls xlsx ppt pptx gif jpg jpeg png csv"`)_
+- `icon` -- Icon displayed on the upload button. Accepts the same formats as wm-button:
+`'#icon-name'` for a Ripple icon or `'/path/to/file.svg#symbol-id'` for a local SVG
+sprite. _(required)_
+- `label` -- Optional label displayed above the upload button. Use when the uploader is
+required (pair with `required-field`) or needs a descriptive heading.
+- `max-files` -- Maximum number of files displayed to the user. Disables the upload button
+when reached. Validation must be handled in the application.
+- `max-size` -- Maximum file size displayed to the user (e.g. `'100 MB'`). Validation must
+be handled in the `wmUploaderFilesSelected` handler.
+- `required-field` -- Displays a required-field asterisk next to the label. Must be used together
+with the `label` prop.
+- `show-info` -- Which metadata to show for each wm-file child in the list. _(type: `"none" | "size" | "time"`; default: `"time"`)_
+- `uploader-type` -- File selection method. `'select'` opens the browser file picker; `'drop'`
+adds a drag-and-drop area. _(type: `"drop" | "select"`; default: `"select"`)_
+
+**Slots:**
+- _(default)_ -- One or more wm-file children representing the current file list.
+
+**Events:**
+- `wmUploaderFilesSelected` -- Fires when the user selects files via the file picker or drops them onto
+the drop zone. The host application should validate the files (type, size, count) and
+begin the upload process. Detail: `File[] -- array of browser `File` objects selected or dropped by the user.`
+
+**Required setup:**
+
+- Handle `wmUploaderFilesSelected` (`event.detail` is an array of browser `File` objects) and hold
+  the files in your own state.
+- Validate type, size, and count in that handler and report problems through `error-message`.
+  `file-types` and `max-size` are shown to the user but not enforced, and `max-files` only
+  disables the control once that many wm-file children exist.
+- Render a wm-file per accepted file, and handle its `wmFileDelete` -- identify the file with
+  `event.target.id` -- by removing it from state.
+- Update each wm-file `progress` as the upload proceeds; it drives the progress bar and the
+  aria-live announcement.
+
+**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.
+
+**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.
+
+**Code example:**
+
+_Select variant_
+
+```html
+<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>
+```
+
+_Select variant with file list management_
+
+```react
+// 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>
+```
+
+_Drop variant_
+
+```html
+<wm-uploader uploader-type="drop" button-text="Upload files" icon="#upload">
+</wm-uploader>
+```
+
+_Drop variant_
+
+```react
+<WmUploader uploaderType="drop" buttonText="Upload files" icon="#upload"
+onWmUploaderFilesSelected={handleFilesSelected} />
+```

package/dist/docs/skill/wm-wrapper.md

@@ -0,0 +1,5 @@
+### Wrapper
+- **Element:** `<wm-wrapper>`
+
+**Events:**
+- `wmWrapperLoaded`

package/dist/esm/app-globals-a1092590.js

@@ -0,0 +1,101 @@
+import './index-3425d80d.js';
+
+const version = "0.1.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/{ripple/chartFunctions-CmeM8Tyx.js → esm/chartFunctions-58637dc9.js}

@@ -1,5 +1,5 @@
-import { h } from './index-CU5QNCKv.js';
-import { i as intl, C as getPosition, v as checkForActiveElInShadow, D as safeMultiplyFloat } from './functions-DVLl0rH_.js';
+import { h } from './index-3425d80d.js';
+import { i as intl, c as checkForActiveElInShadow, e as safeMultiplyFloat, f as getPosition } from './functions-65f1594c.js';
 
 const colors = {
     salmon: "#ff5f4e",
@@ -180,6 +180,7 @@ function handleSliceKeyDown(ev) {
 }
 function handleSliceClick(ev, s) {
     if (this.popoverEl && !this.isTabbing) {
+        this.componentWrapperEl.classList.toggle("interactive-popover", !!s.buttonText);
         s.coords = { x: ev.clientX, y: ev.clientY };
         openPopover(this.popoverEl, s);
         highlightSegmentInfo(Array.from(this.el.shadowRoot.querySelectorAll("[data-segmentindex")), s);
@@ -187,6 +188,7 @@ function handleSliceClick(ev, s) {
 }
 function handleSliceFocus(ev, s) {
     if (this.popoverEl && this.isTabbing) {
+        this.componentWrapperEl.classList.toggle("interactive-popover", !!s.buttonText);
         this.focusedSliceId = s.id;
         s.coords = getPosition(ev.target);
         s.coords.x = s.coords.x + 30;
@@ -721,5 +723,159 @@ function renderHiddenValuesMessage() {
         h("br", null),
         seeDetailsMessage));
 }
+function formatDisplayValue(amount, amountTotal, valueFormat, decimalPlaces = 0) {
+    switch (valueFormat) {
+        case "amount":
+            return amount.toFixed(decimalPlaces);
+        case "percentage":
+            const percentage = (amount / amountTotal) * 100;
+            if (amount > 0 && percentage < 1)
+                return "<1%";
+            if (percentage > 99 && amount !== amountTotal)
+                return ">99%";
+            return `${Math.round(percentage).toFixed(0)}%`;
+        default:
+        case "none":
+            return "";
+    }
+}
+function isNiceInterval(interval, niceValues = [1, 1.5, 2, 2.5, 3, 5, 10]) {
+    const magnitude = Math.pow(10, Math.floor(Math.log10(interval)));
+    const normalized = interval / magnitude;
+    const normalizedComparision = niceValues.some((nice) => Math.abs(normalized - nice) < 0.0001); // check equality with floating point tolerance
+    return normalizedComparision;
+}
+function inferDecimalPlacesFromFloat(value) {
+    // Trims floating point noise and returns significant decimal places, or return 2 for non-terminating values (2/3)
+    if (value === 0 || !Number.isFinite(value))
+        return 0;
+    const maxPlaces = 15;
+    let scaled = Math.abs(value);
+    for (let n = 0; n <= maxPlaces; n++) {
+        // Each iteration, compare the scaled value to the nearest whole number
+        // If the difference is less than the noise margin, return the number of times scaled (decimal places)
+        // Otherwise scale up by 10 and loop
+        const nearest = Math.round(scaled);
+        const noiseMargin = 1e-9;
+        if (Math.abs(scaled - nearest) < noiseMargin) {
+            return n;
+        }
+        scaled *= 10;
+    }
+    return 2;
+}
+function inferDecimalPlacesForUnitValue(value) {
+    // Works with units K and M. Returns decimal places taking unit conversion into account
+    if (value === 0 || !Number.isFinite(value))
+        return 0;
+    const abs = Math.abs(value);
+    let displayUnitValue = abs;
+    if (abs >= 1000000) {
+        displayUnitValue = abs / 1000000;
+    }
+    else if (abs >= 1000) {
+        displayUnitValue = abs / 1000;
+    }
+    return Math.max(inferDecimalPlacesFromFloat(abs), inferDecimalPlacesFromFloat(displayUnitValue));
+}
+function suffixNumber(value, decimalPlaces) {
+    const hasDecimalPlaces = decimalPlaces !== undefined;
+    if (value >= 1000000) {
+        const scaled = value / 1000000;
+        if (hasDecimalPlaces) {
+            return `${scaled.toFixed(decimalPlaces)}M`;
+        }
+        return `${scaled.toFixed(value % 1000000 === 0 ? 0 : 1)}M`;
+    }
+    if (value >= 1000) {
+        const scaled = value / 1000;
+        if (hasDecimalPlaces) {
+            return `${scaled.toFixed(decimalPlaces)}K`;
+        }
+        return `${scaled.toFixed(value % 1000 === 0 ? 0 : 1)}K`;
+    }
+    if (hasDecimalPlaces) {
+        return value.toFixed(decimalPlaces);
+    }
+    return value.toString();
+}
+function findLargestNiceInterval(maxIntervals, total) {
+    // Given a max number of intervals and a total, iterate down until a nice way to divide the total is found.
+    // Otherwise, return 1 interval
+    for (let intervals = maxIntervals; intervals >= 1; intervals--) {
+        const candidateInterval = total / intervals;
+        if (isNiceInterval(candidateInterval)) {
+            return { numIntervals: intervals, interval: candidateInterval };
+        }
+    }
+    return { numIntervals: 1, interval: total };
+}
+function findNiceRoundNumber(value) {
+    // Given a value, find the next "nice" round number >= that value.
+    // Examples: 982 → 1000, 45 → 50, 1234 → 1500, 7 → 10
+    if (value <= 0)
+        return 0;
+    const niceValues = [1, 1.5, 2, 2.5, 3, 5, 10];
+    const magnitude = Math.pow(10, Math.floor(Math.log10(value)));
+    const normalized = value / magnitude;
+    // Find the smallest nice value that is >= the normalized value
+    for (const nice of niceValues) {
+        if (nice >= normalized) {
+            return nice * magnitude;
+        }
+    }
+    // Fallback: next order of magnitude
+    return 10 * magnitude;
+}
+function computeLegendData(data) {
+    const seen = new Set();
+    const result = [];
+    data.forEach((groupItems) => {
+        groupItems.forEach((item) => {
+            if (!seen.has(item.barLegend)) {
+                seen.add(item.barLegend);
+                result.push(item);
+            }
+        });
+    });
+    return result;
+}
+function groupProcessedData(data) {
+    const groups = new Map();
+    data.forEach((item) => {
+        var _a;
+        let groupName = (_a = item.groupName) !== null && _a !== void 0 ? _a : null;
+        if (!groups.has(groupName)) {
+            groups.set(groupName, []);
+        }
+        groups.get(groupName).push(item);
+    });
+    return groups;
+}
+function sortGroupedData(data) {
+    const barData = [...data];
+    // Determine group order and barLegend order by first occurrences
+    const groupOrder = [];
+    barData.forEach((item) => {
+        if (item.groupName && !groupOrder.includes(item.groupName)) {
+            groupOrder.push(item.groupName);
+        }
+    });
+    const barLegendOrder = barData
+        .filter((item) => item.groupName === groupOrder[0])
+        .map((item) => item.barLegend);
+    // Two step sorting: sort by group order, then by barLegend order
+    const sortedBarData = barData.sort((a, b) => {
+        const groupIndexA = groupOrder.indexOf(a.groupName || "");
+        const groupIndexB = groupOrder.indexOf(b.groupName || "");
+        if (groupIndexA !== groupIndexB) {
+            return groupIndexA - groupIndexB;
+        }
+        const legendIndexA = barLegendOrder.indexOf(a.barLegend);
+        const legendIndexB = barLegendOrder.indexOf(b.barLegend);
+        return legendIndexA - legendIndexB;
+    });
+    return sortedBarData;
+}
 
-export { allChartsDetails as a, amountToPercent as b, renderSimpleBar as c, renderStackedBar as d, renderDoughnut as e, exitChart as f, getDetails as g, handleChartKeydown as h, renderLegend as i, renderHiddenValuesMessage as j, renderInstructionsText as k, getInterval as l, abbrNumber as m, renderCompletionMessage as n, renderLegendItem as o, removeSegmentInfoHighlight as r };
+export { allChartsDetails as a, renderSimpleBar as b, renderStackedBar as c, renderDoughnut as d, renderInstructionsText as e, renderLegend as f, getDetails as g, handleChartKeydown as h, renderHiddenValuesMessage as i, exitChart as j, amountToPercent as k, formatDisplayValue as l, renderCompletionMessage as m, renderLegendItem as n, findNiceRoundNumber as o, computeLegendData as p, groupProcessedData as q, removeSegmentInfoHighlight as r, sortGroupedData as s, findLargestNiceInterval as t, suffixNumber as u, getMaxTicks as v, inferDecimalPlacesForUnitValue as w, getInterval as x };