@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -0,0 +1,536 @@
+import { h, Host, forceUpdate } from "@stencil/core";
+import { debounce, hideTooltip, intl, showTooltip, truncateText } from "../../global/functions";
+/**
+ * Displays a single file row with its name, optional metadata, and configurable action buttons
+ * (preview, download, delete). Adapts responsively — at narrow widths action buttons collapse
+ * into an action menu. Used as a child of wm-file-list or wm-uploader.
+ *
+ * @accessibility
+ * - Icon-only action buttons include context-specific aria labels that embed the filename
+ *   (e.g. "Download report.pdf") so screen reader users know which file each button acts on.
+ * - A visually-hidden `aria-live` region announces upload progress and validation errors.
+ *
+ * @usageNotes
+ * - A unique `id` is required on every wm-file element.
+ * - `name` and `type` are both required; `type` is the file extension only (e.g. `pdf`, not a MIME type).
+ * - `show-info` is automatically inherited from the parent wm-file-list or wm-uploader when set there.
+ * - Pass an empty string to `file-actions` to render no action buttons.
+ *
+ * @example {html} Basic file row
+ * <wm-file-list>
+ *   <wm-file id="file-1" name="report" type="pdf" last-updated="1/28/2020 5:29 PM"></wm-file>
+ * </wm-file-list>
+ *
+ * @example {react} Basic file row
+ * <WmFileList>
+ *   <WmFile id="file-1" name="report" type="pdf" lastUpdated="1/28/2020 5:29 PM" />
+ * </WmFileList>
+ *
+ * @example {html} All metadata and all actions
+ * <wm-file id="file-2" name="thesis" type="docx" file-actions="preview download delete"
+ *   show-info="all" size="3 MB" last-updated="3/15/2024 9:00 AM"
+ *   uploaded-by="Uploaded by Smith, John">
+ * </wm-file>
+ *
+ * @example {react} All metadata and all actions
+ * <WmFile id="file-2" name="thesis" type="docx" fileActions="preview download delete"
+ *   showInfo="all" size="3 MB" lastUpdated="3/15/2024 9:00 AM"
+ *   uploadedBy="Uploaded by Smith, John" />
+ *
+ * @example {html} File in error state
+ * <wm-file id="file-3" name="report" type="pdf" error-message="Upload failed. Please try again."></wm-file>
+ *
+ * @example {react} File in error state
+ * <WmFile id="file-3" name="report" type="pdf" errorMessage="Upload failed. Please try again." />
+ *
+ * @requiredSetup
+ * - Render it inside wm-file-list or wm-uploader; it is not a standalone control.
+ * - Give every wm-file a unique `id`. Its events carry no detail, so `event.target` is the only way
+ *   to tell which file was acted on.
+ * - Handle the events for whichever buttons `file-actions` renders -- `wmFileDelete`,
+ *   `wmFileDownload`, `wmFilePreview` -- bearing in mind it defaults to download and delete.
+ *   Deleting is not automatic: wm-uploader listens for `wmFileDelete` only to move focus, so the row
+ *   stays on screen until you drop the file from your own state.
+ * - Handle `wmFileErrorCleared` by clearing the `error-message` you set; the parent only restores
+ *   focus to the upload button.
+ * - Update `progress` as an upload proceeds; it drives the progress bar and the aria-live
+ *   announcement.
+ *
+ */
+export class File {
+    constructor() {
+        this.fullFilename = `${this.name}.${this.type}`;
+        this.debouncedUpdate = debounce(async () => {
+            forceUpdate(this.el);
+        }, 10);
+        this.name = undefined;
+        this.type = undefined;
+        this.fileActions = "download delete";
+        this.lastUpdated = undefined;
+        this.progress = undefined;
+        this.size = undefined;
+        this.uploadedBy = undefined;
+        this.errorMessage = undefined;
+        this.showInfo = "last-updated";
+    }
+    get isCondensed() {
+        // Breakpoint at which file actions are moved into an action menu
+        return this.el.clientWidth < 500;
+    }
+    get isExtraCondensed() {
+        // Breakpoint at which file info is moved into a details element
+        return this.el.clientWidth < 414;
+    }
+    get needsTruncation() {
+        const boundsEl = this.el.shadowRoot.querySelector(".left-group");
+        const measureEl = this.el.shadowRoot.querySelector(".filename-measure");
+        if (boundsEl && measureEl && boundsEl.clientWidth < measureEl.clientWidth) {
+            return true;
+        }
+        return false;
+    }
+    get isUploading() {
+        return this.progress !== undefined && this.progress < 100;
+    }
+    get previewButtonTooltip() {
+        return intl.formatMessage({
+            id: "file.previewButtonTooltip",
+            defaultMessage: "Preview",
+            description: "Tooltip of a button that triggers a file to be previewed",
+        });
+    }
+    get downloadButtonTooltip() {
+        return intl.formatMessage({
+            id: "file.downloadButtonTooltip",
+            defaultMessage: "Download",
+            description: "Tooltip of a button that triggers a file to be downloaded",
+        });
+    }
+    get deleteButtonTooltip() {
+        return intl.formatMessage({
+            id: "file.deleteButtonTooltip",
+            defaultMessage: "Delete",
+            description: "Tooltip of a button that triggers a file to be deleted",
+        });
+    }
+    get previewActionMessage() {
+        return intl.formatMessage({
+            id: "file.previewAction",
+            defaultMessage: "Preview File",
+            description: "Label of a button that triggers a file to be previewed",
+        });
+    }
+    get downloadActionMessage() {
+        return intl.formatMessage({
+            id: "file.downloadAction",
+            defaultMessage: "Download File",
+            description: "Label of a button that triggers a file to be downloaded",
+        });
+    }
+    get deleteActionMessage() {
+        return intl.formatMessage({
+            id: "file.deleteAction",
+            defaultMessage: "Delete File",
+            description: "Label of a button that triggers a file to be delete",
+        });
+    }
+    get actionMenuLabel() {
+        return intl.formatMessage({
+            id: "file.actionMenuLabel",
+            defaultMessage: "Actions",
+            description: "Label of a button that opens a menu of file actions",
+        });
+    }
+    get clearButtonText() {
+        return intl.formatMessage({
+            id: "file.clearErrorText",
+            defaultMessage: "Clear",
+            description: "Text for a button used to clear an error",
+        });
+    }
+    generateClearButtonLabel(filename) {
+        return intl.formatMessage({
+            id: "file.clearErrorLabel",
+            defaultMessage: "Clear {fileName} error",
+            description: "Label for a button used to clear an error, including filename",
+        }, { fileName: filename });
+    }
+    componentWillLoad() {
+        if (!this.el.id) {
+            console.error("wm-file: a file id is required");
+        }
+        if (!this.name) {
+            console.error('wm-file: "name" is a required property');
+        }
+        if (!this.type) {
+            console.error('wm-file: "type" is a required property');
+        }
+        // inherit showInfo property from parent
+        if (this.el.parentElement && this.el.parentElement.showInfo) {
+            this.showInfo = this.el.parentElement.showInfo;
+        }
+        if (this.showInfo === "time") {
+            console.warn("wm-file: show-info='time' is deprecated, use show-info='last-updated'");
+            this.showInfo = "last-updated";
+        }
+        // rerender on resize in case layout needs to change
+        const resizeObserver = new ResizeObserver(() => this.debouncedUpdate());
+        resizeObserver.observe(this.el);
+    }
+    truncateFilename() {
+        let summaryFilenameEl = this.el.shadowRoot.querySelector("#summary-filename-trunc");
+        if (summaryFilenameEl) {
+            summaryFilenameEl.textContent = truncateText(summaryFilenameEl, this.fullFilename, summaryFilenameEl.parentElement.clientWidth - 32, 7);
+            if (summaryFilenameEl.textContent === this.fullFilename) {
+                summaryFilenameEl.classList.remove("-truncated");
+            }
+            else {
+                summaryFilenameEl.classList.add("-truncated");
+            }
+        }
+    }
+    componentDidRender() {
+        this.truncateFilename();
+    }
+    previewFile() {
+        this.wmFilePreview.emit();
+    }
+    downloadFile() {
+        this.wmFileDownload.emit();
+    }
+    deleteFile() {
+        this.wmFileDelete.emit();
+    }
+    handleFilenameMouseEnter(ev) {
+        // only show tooltip if file name is being truncated (has ellipses)
+        if (ev.target.textContent !== this.fullFilename) {
+            showTooltip("bottom", ev.target, this.fullFilename);
+        }
+    }
+    renderFileName() {
+        const showDetailsToggle = this.isExtraCondensed && (this.needsTruncation || (this.showInfo !== "none" && !this.errorMessage));
+        return (h("div", { class: "left-group" }, h("div", { class: "name-wrapper" }, h("span", { class: "sr-only" }, this.fullFilename), h("span", { "aria-hidden": "true", class: `filename ${showDetailsToggle ? "hidden" : ""}` }, this.fullFilename), this.isUploading && h("span", { class: "sr-only" }, "uploading")), showDetailsToggle && this.renderDetailsToggle()));
+    }
+    renderFileInfo() {
+        return (h("div", { class: "file-info" }, (this.showInfo === "uploaded-by" || this.showInfo === "all") && (h("div", { class: "uploader-name" }, this.uploadedBy)), (this.showInfo === "last-updated" || this.showInfo === "all") && h("div", null, this.lastUpdated), (this.showInfo === "size" || this.showInfo === "all") && h("div", null, this.size)));
+    }
+    renderActionMenu() {
+        const previewItem = (h("wm-menuitem", { icon: "#show", onClick: () => this.previewFile() }, this.previewActionMessage));
+        const downloadItem = (h("wm-menuitem", { icon: "#download", onClick: () => this.downloadFile() }, this.downloadActionMessage));
+        const deleteItem = (h("wm-menuitem", { icon: "#delete", onClick: () => this.deleteFile() }, this.deleteActionMessage));
+        return (h("wm-action-menu", { "action-menu-type": "icon", tooltip: this.actionMenuLabel, "tooltip-position": "bottom", "label-for-identical-buttons": `${this.name} ${this.actionMenuLabel}` }, this.fileActions.includes("preview") && previewItem, this.fileActions.includes("download") && downloadItem, this.fileActions.includes("delete") && deleteItem));
+    }
+    renderFileActionButtons() {
+        const previewButton = (h("wm-button", { class: "preview-button", "button-type": "icononly", tooltip: this.previewButtonTooltip, "tooltip-position": "bottom", "label-for-identical-buttons": `preview ${this.name}`, icon: "#show", onClick: () => this.previewFile() }));
+        const downloadButton = (h("wm-button", { class: "download-button", "button-type": "icononly", tooltip: this.downloadButtonTooltip, "tooltip-position": "bottom", "label-for-identical-buttons": `download ${this.name}`, icon: "#download", onClick: () => this.downloadFile() }));
+        const deleteButton = (h("wm-button", { class: "delete-button", "button-type": "icononly", tooltip: this.deleteButtonTooltip, "tooltip-position": "bottom", "label-for-identical-buttons": `delete ${this.name}`, icon: "#delete", onClick: () => this.deleteFile() }));
+        return (h("div", { class: "file-controls" }, this.fileActions.includes("preview") && previewButton, this.fileActions.includes("download") && downloadButton, this.fileActions.includes("delete") && deleteButton));
+    }
+    renderFileInProgress() {
+        return (h("div", { class: "file-wrapper" }, h("div", { class: "file --progress" }, h("div", { class: "progress", style: {
+                background: `linear-gradient(to right, var(--wmcolor-file-progress) ${this.progress}%, transparent ${this.progress}%)`,
+            } }), this.renderFileName())));
+    }
+    renderFileControls() {
+        const hasSingleFileAction = this.fileActions.split(" ").length === 1;
+        const showActionMenu = this.isCondensed && !hasSingleFileAction;
+        return showActionMenu ? this.renderActionMenu() : this.renderFileActionButtons();
+    }
+    renderDetailsToggle() {
+        return (h("details", { id: "file-details" }, h("summary", null, h("div", { class: "filename-measure", "aria-hidden": "true" }, this.fullFilename), h("span", { id: "summary-filename-trunc", onMouseEnter: (ev) => this.handleFilenameMouseEnter(ev), onMouseLeave: () => hideTooltip() }, this.fullFilename), h("span", { id: "summary-filename-wrap" }, this.fullFilename)), !this.errorMessage && this.renderFileInfo()));
+    }
+    renderFile() {
+        const showRightGroup = !this.errorMessage && (this.fileActions !== "" || this.showInfo !== "none");
+        return (h("div", { class: `file-wrapper` }, h("div", { class: `file ${this.errorMessage ? "--error" : ""}  ${this.isCondensed ? "condensed" : ""} ${this.isExtraCondensed ? "extra-condensed" : ""}` }, this.renderFileName(), showRightGroup && (h("div", { class: "right-group" }, !this.isExtraCondensed && this.renderFileInfo(), this.fileActions !== "" && this.renderFileControls())), this.errorMessage && (h("div", { class: "right-group" }, h("wm-button", { "permanently-delete": true, "button-type": "textonly", "label-for-identical-buttons": this.generateClearButtonLabel(this.name), onClick: () => this.wmFileErrorCleared.emit() }, this.clearButtonText))), this.progress == 100 && h("span", { class: "svg-icon svg-success" })), this.errorMessage && h("div", { class: "error-message" }, this.errorMessage)));
+    }
+    render() {
+        return h(Host, { key: '3d6dc80e1864ae1e61f767dbf9e46ffa13267d19', role: "listitem" }, this.isUploading ? this.renderFileInProgress() : this.renderFile());
+    }
+    static get is() { return "wm-file"; }
+    static get encapsulation() { return "shadow"; }
+    static get delegatesFocus() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["wm-file.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["wm-file.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "name": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": true,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Filename without the extension."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "attribute": "name",
+                "reflect": false
+            },
+            "type": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": true,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "File extension without the leading dot (e.g. `pdf`, `docx`). Not a MIME type."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "attribute": "type",
+                "reflect": false
+            },
+            "fileActions": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Space-separated list of action buttons to display. Accepts any combination of\n`preview`, `download`, and `delete`. Pass an empty string to show no actions."
+                        }, {
+                            "name": "default",
+                            "text": "\"download delete\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "file-actions",
+                "reflect": false,
+                "defaultValue": "\"download delete\""
+            },
+            "lastUpdated": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Upload date/time displayed as file metadata. Any display string is accepted\n(e.g. `\"1/28/2020 5:29 PM\"`)."
+                        }],
+                    "text": ""
+                },
+                "attribute": "last-updated",
+                "reflect": false
+            },
+            "progress": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Upload progress as a percentage (0\u2013100). When set and less than 100, the file\nrenders in an in-progress state with a progress bar."
+                        }],
+                    "text": ""
+                },
+                "attribute": "progress",
+                "reflect": true
+            },
+            "size": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "File size displayed as file metadata. Include the unit in the string\n(e.g. `\"3 MB\"`)."
+                        }],
+                    "text": ""
+                },
+                "attribute": "size",
+                "reflect": false
+            },
+            "uploadedBy": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Uploader attribution displayed as file metadata\n(e.g. `\"Uploaded by Smith, John\"`)."
+                        }],
+                    "text": ""
+                },
+                "attribute": "uploaded-by",
+                "reflect": false
+            },
+            "errorMessage": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Puts the file row in an error state and displays this message below it."
+                        }],
+                    "text": ""
+                },
+                "attribute": "error-message",
+                "reflect": false
+            },
+            "showInfo": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "\"time\" | \"last-updated\" | \"size\" | \"uploaded-by\" | \"all\" | \"none\"",
+                    "resolved": "\"all\" | \"last-updated\" | \"none\" | \"size\" | \"time\" | \"uploaded-by\" | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Which metadata to display alongside the filename. Automatically inherited\nfrom the parent wm-file-list or wm-uploader when set there."
+                        }, {
+                            "name": "default",
+                            "text": "\"last-updated\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "show-info",
+                "reflect": false,
+                "defaultValue": "\"last-updated\""
+            }
+        };
+    }
+    static get events() {
+        return [{
+                "method": "wmFilePreview",
+                "name": "wmFilePreview",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the preview button is clicked."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }, {
+                "method": "wmFileDownload",
+                "name": "wmFileDownload",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the download button is clicked."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }, {
+                "method": "wmFileDelete",
+                "name": "wmFileDelete",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the delete button is clicked."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }, {
+                "method": "wmFileErrorCleared",
+                "name": "wmFileErrorCleared",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user clears a file error by clicking the Clear button."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }];
+    }
+    static get elementRef() { return "el"; }
+}