@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -1,17 +1,100 @@
 import { TooltipPlacement } from "../../global/interfaces";
+/**
+ * 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.
+ *
+ * @category Communication
+ *
+ * @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.
+ * - 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." />
+ *
+ */
 export declare class Toggletip {
     el: HTMLWmToggletipElement;
+    /**
+     * @description Accessible label for the trigger button. Also shown as a hover/focus tooltip
+     * while the panel is closed. Required for screen reader users.
+     * @required
+     */
     label?: string;
+    /**
+     * @description Content displayed inside the toggletip panel when opened. Also announced
+     * via an `aria-live` region when the panel opens.
+     * @required
+     */
     tooltip: string;
+    /**
+     * @description Preferred opening direction for the panel. Auto-corrected if the panel would
+     * overflow the viewport.
+     * @default "bottom-right"
+     */
     tooltipPosition: TooltipPlacement;
+    /**
+     * @description Size of the trigger button icon. `'large'` satisfies WCAG 2.5.8 touch
+     * target requirements.
+     * @default "small"
+     */
     targetSize: "small" | "large";
+    /**
+     * @description Visual style of the trigger icon. `'info'` shows an info icon; `'ai'` shows
+     * an animated sparkle icon.
+     * @default "info"
+     */
+    toggletipType: "info" | "ai";
     isHidden: boolean;
     private toggletipEl;
+    private buttonEl;
     private liveRegionEl;
-    private scrollableParent?;
-    private tooltipMessage;
+    private scrollableParents;
+    private tooltipInfoMessage;
+    private tooltipAITooltip;
     get isOpen(): boolean;
+    get tooltipMessage(): string;
     get toggletipPosition(): TooltipPlacement;
+    /**
+     * 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;
     debouncedReveal: (this: any) => void;
@@ -19,8 +102,11 @@ export declare class Toggletip {
     handleResize(): void;
     handleKeydown(ev: KeyboardEvent): void;
     handleClick(ev: MouseEvent): void;
+    handleScroll(): void;
+    handlePopoverToggle(ev: ToggleEvent): void;
     open(): void;
     handleBlur(): void;
     announceToggletip(): void;
+    renderIcon(): any;
     render(): any;
 }

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

@@ -1,4 +1,88 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * 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.
+ *
+ * @category Form Inputs
+ *
+ * @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} />
+ *
+ * @requiredSetup
+ * - 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.
+ *
+ *
+ */
 export declare class Uploader {
     el: HTMLWmUploaderElement;
     private uploadButtonEl;
@@ -6,16 +90,67 @@ export declare class Uploader {
     private dropOverlayEl;
     private assertiveLiveRegionEl;
     private politeLiveRegionEl;
+    /**
+     * @description Optional label displayed above the upload button. Use when the uploader is
+     * required (pair with `required-field`) or needs a descriptive heading.
+     */
     label?: string;
+    /**
+     * @description File selection method. `'select'` opens the browser file picker; `'drop'`
+     * adds a drag-and-drop area.
+     * @default "select"
+     */
     uploaderType: "select" | "drop";
+    /**
+     * @description 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.
+     * @default "component"
+     */
     dropArea: "component" | "page";
+    /**
+     * @description Label text on the upload trigger button, e.g. `'Attach files'`. Should
+     * match the action verb used in any surrounding instructions.
+     * @required
+     */
     buttonText: string;
+    /**
+     * @description 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.
+     */
     icon: string;
+    /**
+     * @description 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"
+     */
     fileTypes: string;
+    /**
+     * @description Maximum file size displayed to the user (e.g. `'100 MB'`). Validation must
+     * be handled in the `wmUploaderFilesSelected` handler.
+     */
     maxSize?: string;
+    /**
+     * @description Maximum number of files displayed to the user. Disables the upload button
+     * when reached. Validation must be handled in the application.
+     */
     maxFiles?: number;
+    /**
+     * @description Puts the uploader in an error state with this message (e.g. `'Please add at
+     * least one file'`).
+     */
     errorMessage?: string;
+    /**
+     * @description Displays a required-field asterisk next to the label. Must be used together
+     * with the `label` prop.
+     * @default false
+     */
     requiredField?: boolean;
+    /**
+     * @description Which metadata to show for each wm-file child in the list.
+     * @default "time"
+     */
     showInfo: "size" | "time" | "none";
     isTabbing: boolean;
     notif: string;
@@ -23,7 +158,14 @@ export declare class Uploader {
     private srProgress?;
     private batchCount;
     private prevUploadCount;
-    private fileIdToDelete;
+    private deletedEl?;
+    private elToFocusOnDelete?;
+    /**
+     * @description 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.
+     * @eventDetails File[] — array of browser `File` objects selected or dropped by the user.
+     */
     wmUploaderFilesSelected: EventEmitter<File[]>;
     get isDisabled(): boolean;
     get fileEls(): HTMLWmFileElement[];
@@ -34,7 +176,7 @@ export declare class Uploader {
     toggleTabbingOn(): void;
     toggleTabbingOff(): void;
     handleFileErrorCleared(): void;
-    storeDeletedId(ev: CustomEvent): void;
+    handleFileDelete(ev: CustomEvent): void;
     announceError(): void;
     handleDocumentDragEnter(): void;
     handleDocumentMouseOut(): void;
@@ -49,9 +191,9 @@ export declare class Uploader {
     componentDidLoad(): void;
     handleChildMutation(mutationRecord: MutationRecord): void;
     handleProgressUpdate(mutationRecord: MutationRecord): void;
-    focusAfterFileRemoval(mutationRecord: MutationRecord): void;
     handleUploadButtonClick(ev: Event): void;
     handleUploadButtonChange(): void;
+    handleLabelMouseEnter(ev: MouseEvent): void;
     announce(message: string, liveRegionEl: HTMLElement): void;
     renderIcon(): any;
     renderUploadButton(): any;

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

@@ -1,4 +1,7 @@
 import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * @category Layout Containers
+ */
 export declare class Wrapper {
     el: any;
     wmWrapperLoaded: EventEmitter<void>;