@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

package/dist/types/components/wm-button/wm-button.d.ts

@@ -1,25 +1,211 @@
 import { TooltipPlacement, validButtonTypes } from "../../global/interfaces";
+/**
+ * Interactive button element that triggers actions and workflows. Has seven visual
+ * types plus AI variants.
+ *
+ * @category Basic Controls
+ *
+ * @slot - Button label text. Required for all types. For `icononly` and `navigational`
+ *   buttons, slotted text is not rendered visually but is used as the accessible name
+ *   when no `tooltip` or `label-for-identical-buttons` is provided.
+ *
+ * @keyboardInteraction Enter - Fires a click event on the button (mirrors native button behavior).
+ *
+ * @accessibility
+ * `aria-label` resolution order (highest priority first):
+ * 1. `aria-label-passthrough`
+ * 2. `label-for-identical-buttons` (or `tooltip` for icononly/navigational types)
+ * 3. Nothing set — browser derives the label from visible text or slotted content
+ *
+ * `aria-expanded` — set via `aria-expanded-passthrough` (not directly on `<wm-button>`).
+ * `aria-haspopup="menu"` — applied automatically when the host element has an `aria-haspopup` attribute.
+ *
+ * @usageNotes
+ * - **primary**: Use sparingly — ideally once per page or section — for the single most
+ *   important action.
+ * - **pairpositive / pairnegative**: Must always be used together for binary choices where
+ *   neither option is preferred (e.g. Approve / Reject). Do not use one without the other.
+ * - **AI variants** (`primary-ai`, `secondary-ai`, etc.): Do not set the `icon` prop —
+ *   the AI icon is applied automatically.
+ * - **icononly / navigational**: Both `icon` and `tooltip` are required.
+ * - Do not use slotted text (emoji, Unicode glyphs, or characters styled to look like an icon)
+ *   to simulate an icon. Use the `icon` prop so the icon is rendered as a proper SVG/MDI glyph
+ *   with correct sizing, color, and accessibility treatment.
+ *
+ * @example {html} Primary button — the preferred action on a page or section. Use once per context.
+ * <wm-button button-type="primary">Save changes</wm-button>
+ *
+ * @example {react} Primary button
+ * <WmButton buttonType="primary" onClick={handleSave}>Save changes</WmButton>
+ *
+ * @example {html} Primary and secondary pair — the most common pattern.
+ * <wm-button button-type="secondary">Cancel</wm-button>
+ * <wm-button button-type="primary">Save changes</wm-button>
+ *
+ * @example {react} Primary and secondary pair
+ * <WmButton buttonType="secondary" onClick={handleCancel}>Cancel</WmButton>
+ * <WmButton buttonType="primary" onClick={handleSave}>Save changes</WmButton>
+ *
+ * @example {html} Text-only button with icon
+ * <wm-button button-type="textonly" icon="#edit">Edit</wm-button>
+ *
+ * @example {react} Text-only button with icon
+ * <WmButton buttonType="textonly" icon="#edit">Edit</WmButton>
+ *
+ * @example {html} Icon-only button — icon, tooltip, and slot text are all required.
+ * <wm-button button-type="icononly" icon="#edit" tooltip="Edit record">Edit record</wm-button>
+ *
+ * @example {react} Icon-only button
+ * <WmButton buttonType="icononly" icon="#edit" tooltip="Edit record">Edit record</WmButton>
+ *
+ * @example {html} Icon-only button with local SVG sprite
+ * <wm-button button-type="icononly" icon="/assets/icons.svg#pencil" tooltip="Edit">Edit</wm-button>
+ *
+ * @example {html} Navigational button — for back/forward navigation in flyout panels.
+ * <wm-button button-type="navigational" icon="#back" tooltip="Back">Back</wm-button>
+ *
+ * @example {react} Navigational button
+ * <WmButton buttonType="navigational" icon="#back" tooltip="Back">Back</WmButton>
+ *
+ * @example {html} Positive/negative pair — binary choice, neither option preferred. Must be used as a pair.
+ * <wm-button button-type="pairnegative">Reject</wm-button>
+ * <wm-button button-type="pairpositive">Approve</wm-button>
+ *
+ * @example {react} Positive/negative pair
+ * <WmButton buttonType="pairnegative" onClick={handleReject}>Reject</WmButton>
+ * <WmButton buttonType="pairpositive" onClick={handleApprove}>Approve</WmButton>
+ *
+ * @example {html} Permanently delete — danger styling for irreversible destructive actions only.
+ * <wm-button button-type="primary" permanently-delete="true">Delete account</wm-button>
+ *
+ * @example {react} Permanently delete
+ * <WmButton buttonType="primary" permanentlyDelete={true}>Delete account</WmButton>
+ *
+ * @example {html} Disabled button
+ * <wm-button button-type="primary" disabled="true">Save</wm-button>
+ *
+ * @example {react} Disabled button
+ * <WmButton buttonType="primary" disabled={true}>Save</WmButton>
+ *
+ * @example {html} Form submit button — use is-submit instead of a native type=submit button.
+ * <form>
+ *   <wm-button button-type="primary" is-submit="true">Submit</wm-button>
+ * </form>
+ *
+ * @example {react} Form submit button
+ * <WmButton buttonType="primary" isSubmit={true}>Submit</WmButton>
+ *
+ * @example {html} Button on dark background
+ * <wm-button button-type="secondary" custom-background="dark">Continue</wm-button>
+ *
+ * @example {react} Button on dark background
+ * <WmButton buttonType="secondary" customBackground="dark">Continue</WmButton>
+ *
+ * @example {html} AI primary button — icon is applied automatically, do not set icon prop.
+ * <wm-button button-type="primary-ai">Generate summary</wm-button>
+ *
+ * @example {react} AI primary button
+ * <WmButton buttonType="primary-ai">Generate summary</WmButton>
+ *
+ * @example {html} Rotated icon — reuse directional icons with icon-rotate.
+ * <wm-button button-type="icononly" icon="#back" icon-rotate="180" tooltip="Forward">Forward</wm-button>
+ *
+ * @example {react} Rotated icon
+ * <WmButton buttonType="icononly" icon="#back" iconRotate={180} tooltip="Forward">Forward</WmButton>
+ *
+ * @example {html} Identical buttons — use label-for-identical-buttons to disambiguate for screen readers.
+ * <wm-button button-type="secondary" label-for-identical-buttons="Edit course: Introduction to Biology">Edit</wm-button>
+ * <wm-button button-type="secondary" label-for-identical-buttons="Edit course: Advanced Chemistry">Edit</wm-button>
+ *
+ * @example {react} Identical buttons
+ * <WmButton buttonType="secondary" labelForIdenticalButtons="Edit course: Introduction to Biology">Edit</WmButton>
+ * <WmButton buttonType="secondary" labelForIdenticalButtons="Edit course: Advanced Chemistry">Edit</WmButton>
+ *
+ */
 export declare class Button {
     el: HTMLWmButtonElement;
     private buttonEl;
+    /**
+     * @description Disables the button, preventing interaction and applying disabled styling.
+     * @default false
+     */
     disabled: boolean;
     get isDisabled(): boolean;
+    /**
+     * @description Visual style of the button. 'primary' for the single preferred action (use sparingly, ideally once per page/section). 'secondary' for other actions, often alongside a primary. 'textonly' for low-emphasis actions. 'icononly' requires icon and tooltip. 'navigational' for icon-only back/forward navigation (e.g. flyout back button). 'pairpositive' and 'pairnegative' must be used together for binary choices (neither is preferred, e.g. Approve/Reject). AI variants apply AI styling automatically — do not set the icon property on AI types. 'selector' and 'selector-primary' are internal types used by wm-select — do not use directly.
+     * @default "secondary"
+     */
     buttonType: validButtonTypes;
+    /**
+     * @description Icon to display. Required when button-type is 'icononly' or 'navigational'. Formats: '#icon-name' for a commonly-used Ripple icon (e.g. '#edit', '#add-person'), '/path/to/file.svg#symbol-id' for a local SVG sprite symbol, or an MDI character code like 'f3eb' (deprecated). Do not set on AI button types — their icon is applied automatically.
+     * @conditionallyRequired when button-type is 'icononly' or 'navigational' (conditionallyRequired means that the prop is required, but only if the button-type is 'icononly' or 'navigational')
+     */
     icon?: string;
+    /**
+     * @description Change size of the icon to fine tune the visual rendering if it appears too large or small. Not
+     * intended for general sizing. Accepts any valid CSS size value, e.g. '22px' or '1.3rem'.
+     */
     iconSize?: string;
+    /**
+     * @description Rotates the icon by the given number of degrees. For use with the icon property.
+     */
     iconRotate?: number;
+    /**
+     * @description Flips the icon along the specified axis. For use with the icon property.
+     */
     iconFlip?: "horizontal" | "vertical";
+    /**
+     * @description Tooltip text displayed on hover.
+     * @conditionallyRequired when button-type is 'icononly' or 'navigational' (conditionallyRequired means that the prop is required, but only if the button-type is 'icononly' or 'navigational')
+     */
     tooltip?: string;
+    /**
+     * @description Accessibility prop. Use ONLY when multiple buttons on the same page share identical visible text or identical tooltips. Set this to a more descriptive label for screen readers; leave the visible button text or tooltip unchanged. Sets aria-label to this value.
+     * @conditionallyRequired when multiple buttons on the same page share identical visible text or identical tooltips (conditionallyRequired means that the prop is required, but only if multiple buttons on the same page share identical visible text or identical tooltips)
+     */
     labelForIdenticalButtons?: string;
+    /**
+     * @description Position of the tooltip relative to the button. If there is insufficient space at the specified position, the component repositions automatically.
+     * @default "bottom-right"
+     */
     tooltipPosition: TooltipPlacement;
+    /**
+     * @description Applies danger/destructive styling to the button. Use sparingly and only for irreversible destructive actions (e.g. permanently deleting an account or record). Applied as a modifier — not a separate button-type.
+     * @default false
+     */
     permanentlyDelete?: boolean;
+    /**
+     * @description For 'textonly' buttons only. When false, text is truncated with an ellipsis and a tooltip reveals the full text on hover.
+     * @default true
+     */
     textWrap: boolean;
+    /**
+     * @description Set to 'dark' to render button styles appropriate for a dark background surface.
+     */
     customBackground?: string;
+    /**
+     * @description When true, the button submits its containing form. Equivalent to type="submit" on a native button element.
+     * @default false
+     */
     isSubmit: boolean;
+    /**
+     * @description Sets the button's `aria-label`. Takes priority over `label-for-identical-buttons` and over
+     * the label automatically derived from `tooltip` for `icononly` and `navigational` buttons. Use
+     * this prop instead of setting `aria-label` directly on `<wm-button>`.
+     */
+    ariaLabelPassthrough?: string;
+    /**
+     * @description Sets the button's `aria-expanded` attribute. Use on buttons that toggle a disclosure region,
+     * menu, popover, or dialog. Use this prop instead of setting `aria-expanded` directly on
+     * `<wm-button>`.
+     * @default false
+     */
+    ariaExpandedPassthrough?: boolean;
     isTabbing: boolean;
     private id;
     private ariaPopup;
     get isTruncated(): boolean;
+    get isAriaExpanded(): boolean | undefined;
     get hasTooltip(): boolean;
     get buttonClasses(): string;
     toggleTabbingOn(): void;
@@ -32,6 +218,11 @@ export declare class Button {
     handleKeydown(ev: KeyboardEvent): void;
     handleMouseEnter(ev: MouseEvent): void;
     handleFocus(ev: FocusEvent): void;
+    /**
+     * Register CSS custom properties for AI gradient animations
+     * These need to be registered in JS since @property doesn't work in shadow DOM
+     */
+    private registerCSSProperties;
     componentWillLoad(): void;
     componentDidLoad(): void;
     getAriaLabel(): string | undefined;

package/dist/types/components/wm-file/wm-file.d.ts

@@ -1,21 +1,129 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * 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 declare class File {
     el: HTMLWmFileElement;
+    /**
+     * @description Filename without the extension.
+     * @required
+     */
     name: string;
+    /**
+     * @description File extension without the leading dot (e.g. `pdf`, `docx`). Not a MIME type.
+     * @required
+     */
     type: string;
+    /**
+     * @description Space-separated list of action buttons to display. Accepts any combination of
+     * `preview`, `download`, and `delete`. Pass an empty string to show no actions.
+     * @default "download delete"
+     */
     fileActions: string;
+    /**
+     * @description Upload date/time displayed as file metadata. Any display string is accepted
+     * (e.g. `"1/28/2020 5:29 PM"`).
+     */
     lastUpdated?: string;
+    /**
+     * @description Upload progress as a percentage (0–100). When set and less than 100, the file
+     * renders in an in-progress state with a progress bar.
+     */
     progress?: number;
+    /**
+     * @description File size displayed as file metadata. Include the unit in the string
+     * (e.g. `"3 MB"`).
+     */
     size?: string;
+    /**
+     * @description Uploader attribution displayed as file metadata
+     * (e.g. `"Uploaded by Smith, John"`).
+     */
     uploadedBy?: string;
+    /**
+     * @description Puts the file row in an error state and displays this message below it.
+     */
     errorMessage?: string;
+    /**
+     * @description Which metadata to display alongside the filename. Automatically inherited
+     * from the parent wm-file-list or wm-uploader when set there.
+     * @default "last-updated"
+     */
     showInfo?: "time" | "last-updated" | "size" | "uploaded-by" | "all" | "none";
     private fullFilename;
+    /**
+     * @description Fires when the preview button is clicked.
+     */
     wmFilePreview: EventEmitter;
+    /**
+     * @description Fires when the download button is clicked.
+     */
     wmFileDownload: EventEmitter;
+    /**
+     * @description Fires when the delete button is clicked.
+     */
     wmFileDelete: EventEmitter;
+    /**
+     * @description Fires when the user clears a file error by clicking the Clear button.
+     */
     wmFileErrorCleared: EventEmitter;
     get isCondensed(): boolean;
+    get isExtraCondensed(): boolean;
+    get needsTruncation(): boolean;
     get isUploading(): boolean;
     get previewButtonTooltip(): string;
     get downloadButtonTooltip(): string;
@@ -28,7 +136,7 @@ export declare class File {
     generateClearButtonLabel(filename: string): string;
     componentWillLoad(): void;
     debouncedUpdate: (this: any) => void;
-    setFilename(): void;
+    truncateFilename(): void;
     componentDidRender(): void;
     previewFile(): void;
     downloadFile(): void;
@@ -40,6 +148,7 @@ export declare class File {
     renderFileActionButtons(): any;
     renderFileInProgress(): any;
     renderFileControls(): any;
+    renderDetailsToggle(): any;
     renderFile(): any;
     render(): any;
 }

package/dist/types/components/wm-file-list/wm-file-list.d.ts

@@ -1,5 +1,77 @@
+/**
+ * Read-only list of files with optional preview and download actions. Visually similar to the
+ * Uploader but with no upload capability. Use when displaying existing files users can view or
+ * download, not when they need to upload new ones.
+ *
+ * @category Form Inputs
+ *
+ * @slot - One or more wm-file child elements.
+ *
+ * @usageNotes
+ * - Each child wm-file requires a unique `id`, a `name`, and a `type` (file extension).
+ * - Set `show-info` on wm-file-list to apply the same metadata display to all children — each
+ *   wm-file inherits it automatically. Individual wm-file elements can still override it.
+ *
+ * @example {html} File list with default metadata (last-updated)
+ * <wm-file-list>
+ *   <wm-file id="file-1" name="report" type="pdf" last-updated="1/28/2020 5:29 PM"></wm-file>
+ *   <wm-file id="file-2" name="thesis" type="docx" last-updated="3/15/2024 9:00 AM"></wm-file>
+ * </wm-file-list>
+ *
+ * @example {react} File list with managed state
+ * // wm-file-list does not manage its own state — drive the file list from React state.
+ * // wmFileDelete fires on the wm-file element; use e.target.id to remove the matching entry.
+ * // showInfo on wm-file-list propagates automatically to all wm-file children.
+ * const [files, setFiles] = useState([
+ *   { id: "file-1", name: "annual-report", type: "pdf", lastUpdated: "1/28/2024 5:29 PM" },
+ *   { id: "file-2", name: "budget-summary", type: "xlsx", lastUpdated: "3/15/2024 9:00 AM" },
+ * ]);
+ *
+ * <WmFileList>
+ *   {files.map((f) => (
+ *     <WmFile key={f.id} id={f.id} name={f.name} type={f.type} lastUpdated={f.lastUpdated}
+ *       onWmFileDelete={(e) => setFiles((prev) => prev.filter((f) => f.id !== e.target.id))} />
+ *   ))}
+ * </WmFileList>
+ *
+ * @example {html} Show all metadata
+ * <wm-file-list show-info="all">
+ *   <wm-file id="file-1" name="report" type="pdf"
+ *     size="3 MB" last-updated="1/28/2020 5:29 PM" uploaded-by="Uploaded by Smith, John">
+ *   </wm-file>
+ * </wm-file-list>
+ *
+ * @example {react} Show all metadata with preview and download handlers
+ * // fileActions controls which buttons appear; omit delete or pass fileActions="" for none.
+ * // onWmFilePreview and onWmFileDownload fire on the wm-file element; e.target.name is the filename.
+ * const [files, setFiles] = useState([
+ *   { id: "file-3", name: "thesis", type: "docx", size: "3.2 MB",
+ *     lastUpdated: "1/28/2024 5:29 PM", uploadedBy: "Uploaded by Smith, John",
+ *     fileActions: "preview download delete" },
+ *   { id: "file-4", name: "presentation", type: "pptx", size: "8.5 MB",
+ *     lastUpdated: "3/15/2024 9:00 AM", uploadedBy: "Uploaded by Doe, Jane",
+ *     fileActions: "download delete" },
+ * ]);
+ *
+ * <WmFileList showInfo="all">
+ *   {files.map((f) => (
+ *     <WmFile key={f.id} id={f.id} name={f.name} type={f.type}
+ *       size={f.size} lastUpdated={f.lastUpdated} uploadedBy={f.uploadedBy}
+ *       fileActions={f.fileActions}
+ *       onWmFilePreview={(e) => alert(`Preview: ${e.target.name}`)}
+ *       onWmFileDownload={(e) => alert(`Download: ${e.target.name}`)}
+ *       onWmFileDelete={(e) => setFiles((prev) => prev.filter((f) => f.id !== e.target.id))} />
+ *   ))}
+ * </WmFileList>
+ *
+ */
 export declare class FileList {
     el: HTMLWmFileListElement;
+    /**
+     * @description Which metadata to display for each file alongside its name. Propagated
+     * automatically to all wm-file children.
+     * @default "last-updated"
+     */
     showInfo: "size" | "last-updated" | "uploaded-by" | "all" | "none";
     render(): any;
 }