@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/docs/wm-chart-legend.md

@@ -0,0 +1,31 @@
+# `wm-chart-legend`
+
+External legend component for wm-chart-bar and wm-chart-column. Retrieves color and label
+data from one or more charts via element IDs, allowing a single legend to serve multiple
+charts. Hidden from screen readers -- relevant data is announced when the user interacts with
+the associated chart directly.
+
+For simple single-chart scenarios, the `config.showLegend` option on wm-chart-bar or
+wm-chart-column renders an internal legend without requiring this element. Use
+wm-chart-legend when sharing one legend across multiple charts or when external placement
+is required.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `chartIds` | `chart-ids` | `string` | `""` |  |  |
+| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |  |
+| `printMode` | `print-mode` | `boolean` | `false` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmLegendItemClick` | `{ idx: number; }` | ✓ |  |
+| `wmLegendItemHover` | `{ idx: number; }` | ✓ |  |
+
+## Used By
+
+- `wm-chart-bar`
+- `wm-chart-column`

package/dist/docs/wm-chart-slice.md

@@ -0,0 +1,14 @@
+# `wm-chart-slice`
+
+Data slice for a wm-chart composition chart. Each slice represents one segment of the whole.
+Always used as a direct child of wm-chart.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `amount` | `amount` | `string \| undefined` |  |  |  |
+| `legend` | `legend` | `string \| undefined` |  |  |  |
+| `popoverButtonText` | `popover-button-text` | `string \| undefined` |  |  |  |
+| `popoverText` | `popover-text` | `string \| undefined` |  |  |  |
+| `popoverTitle` | `popover-title` | `string \| undefined` |  |  |  |

package/dist/docs/wm-chart.md

@@ -0,0 +1,30 @@
+# `wm-chart`
+
+Composition chart component rendering doughnut or stacked bar charts. Composed of a parent
+wm-chart element and wm-chart-slice children. Has 3 doughnut subtypes and 5 bar subtypes,
+each designed for a specific composition use case.
+
+**Important:** The bar subtypes (`bar2`-`bar7`) are COMPOSITION patterns -- they show parts
+of a whole for specific qualitative use cases. They are NOT general-purpose bar charts. For
+general comparison or distribution bar charts, use wm-chart-bar or wm-chart-column instead.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `chartType` | `chart-type` | `"bar" \| "bar2" \| "bar3" \| "bar4" \| "bar5" \| "bar6" \| "bar7" \| "doughnut" \| "doughnut1" \| "doughnut2" \| "doughnut3"` | `"doughnut1"` |  |  |
+| `label` | `label` | `string \| undefined` |  |  |  |
+| `labelPosition` | `label-position` | `"left" \| "none" \| "top"` | `"top"` |  |  |
+| `labelWidth` | `label-width` | `string` | `"150px"` |  |  |
+| `notStartedColor` | `not-started-color` | `boolean` | `false` |  |  |
+| `printMode` | `print-mode` | `boolean` | `false` |  |  |
+| `printModeFormat` | `print-mode-format` | `"amount" \| "percentage"` | `"amount"` |  |  |
+| `showBarLegend` | `show-bar-legend` | `boolean` | `false` |  |  |
+| `showGrid` | `show-grid` | `boolean \| undefined` | `true` |  |  |
+| `showLegend` | `show-legend` | `boolean` | `true` |  |  |
+| `subinfo` | `subinfo` | `string \| undefined` |  |  |  |
+| `valueFormat` | `value-format` | `"amount" \| "none" \| "percentage"` | `"none"` |  |  |
+
+## Depends On
+
+- `priv-chart-popover-old`

package/dist/docs/wm-date-range.md

@@ -0,0 +1,215 @@
+# `wm-date-range`
+
+Two linked date inputs (start and end) with a shared calendar popup for selecting a date
+range. Users can type or click to set each date. Provides separate error states for start
+and end, and emits distinct blur events for each input. Use instead of two native
+`<input type="date">` elements when a range is required.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `dateFormat` | `date-format` | `string` | `"mm/dd/yyyy"` |  |  |
+| `disabled` | `disabled` | `boolean` | `false` |  |  |
+| `errorMessage` | `error-message` | `string \| undefined` |  |  |  |
+| `invalidEnd` | `invalid-end` | `boolean` | `false` |  |  |
+| `invalidStart` | `invalid-start` | `boolean` | `false` |  |  |
+| `labelEnd` | `label-end` | `string` | `""` |  |  |
+| `labelStart` | `label-start` | `string` | `""` |  |  |
+| `preselected` | `preselected` | `string \| undefined` |  |  |  |
+| `requiredField` | `required-field` | `boolean` | `false` |  |  |
+| `valueEnd` | `value-end` | `string \| undefined` | `""` |  |  |
+| `valueStart` | `value-start` | `string \| undefined` | `""` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmEndInputBlur` | `any` | ✓ |  |
+| `wmRangeSelection` | `any` | ✓ |  |
+| `wmStartInputBlur` | `any` | ✓ |  |
+
+## Methods
+
+### `isValidISO(input?: string) => Promise<boolean>`
+
+**Parameters**
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `input` | `string \| undefined` | - The string to validate. |
+
+**Returns** `Promise<boolean>` -- `true` if the string is a valid ISO date, `false` otherwise.
+
+### `reformatDate(inputFormat: string, outputFormat: string, date?: string) => Promise<string>`
+
+**Parameters**
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `inputFormat` | `string` | - Format of the input date string (`"US"`, `"INT"`, or `"ISO"`). |
+| `outputFormat` | `string` | - Desired output format (`"US"`, `"INT"`, or `"ISO"`). |
+| `date` | `string \| undefined` | - The date string to reformat. |
+
+**Returns** `Promise<string>` -- The reformatted date string, an empty string if `date` is omitted, or the original
+string unchanged if it cannot be parsed.
+
+## Depends On
+
+- `priv-calendar`
+
+# wm-date-range
+
+## Purpose
+
+A paired date input that lets users specify both a start and end date by typing or using a shared calendar popup. The two values are treated as a single, related range.
+
+---
+
+## When to Use
+
+- **Collecting a bounded time period with a start and end** -- when a user needs to define a window of time (a reporting period, an enrollment window, a project timeline), use Date Range to capture both boundary dates as a single, semantically linked input rather than two independent Datepickers.
+- **Filtering data by a date range** -- when a user is narrowing results by a time window (e.g., "show records between these two dates"), Date Range provides the right interaction model with a shared calendar that highlights the selected span visually.
+- **Enforcing range integrity at the form level** -- when the application needs to validate that the start date precedes the end date, Date Range exposes the right blur events and standardized error messages to handle all range validation scenarios consistently.
+- **Allowing range selection via a shared calendar popup** -- when users benefit from seeing both dates in context on a calendar, Date Range's shared popup highlights the full selected range, which two independent Datepickers cannot do.
+
+---
+
+## Do Not Use For
+
+- **Two separate dates that happen to be related** -- if the two dates are logically a range, use Date Range; two independent Datepickers have no shared calendar, no range highlighting, and no built-in mechanism to enforce that start precedes end.
+- **Selecting a single point in time** -- if the user is selecting one date rather than a span, use wm-datepicker; Date Range always manages two values and two validation states, which is unnecessary overhead for a single date.
+
+---
+
+## Related Components
+
+- `<wm-datepicker>` -- if only a single date is needed rather than a start-and-end pair, use Datepicker; Date Range always manages two values and is only appropriate when both are required together.
+- `<wm-timepicker>` -- if the range also needs to capture times of day, Date Range has no time input; pair it with Timepicker fields for the start and end times separately.
+- `<wm-select>` -- if the user is choosing from a predefined list of named time periods (e.g., "Q1 2025", "Fall Semester") rather than specifying arbitrary dates, Select is more appropriate; Date Range is for open-ended date entry.
+
+---
+
+## Accessibility
+
+- Validating on every keystroke: all validations should be performed on blur, not while the user is still typing; premature validation fires errors before the user has finished entering a value.
+- Clearing errors on blur: errors should be cleared when the field is focused again, not when it blurs; reversing this produces confusing behavior where errors appear and disappear at unexpected moments.
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- `labelStart` -- required; the accessible label for the start date input
+- `labelEnd` -- required; the accessible label for the end date input
+- `dateFormat` -- specifies the expected date format for both inputs
+- `preselected` -- a date string used to pre-position the calendar when it opens
+- `valueStart` -- the current start date value
+- `valueEnd` -- the current end date value
+- `invalidStart` -- marks the start date input as invalid; triggers error styling
+- `invalidEnd` -- marks the end date input as invalid; triggers error styling
+- `errorMessage` -- validation error text displayed below the component
+- `requiredField` -- marks both fields as required
+- `disabled` -- disables both inputs and the calendar button
+
+---
+
+## Events
+
+- `wmRangeSelection` -- fires when the user completes a range selection in the calendar
+- `wmStartInputBlur` -- fires when the start date input loses focus; trigger start date validation here
+- `wmEndInputBlur` -- fires when the end date input loses focus; trigger end date and range integrity validation here
+
+---
+
+## Methods
+
+- `reformatDate(inputFormat, outputFormat, date?)` -- converts a date string between formats
+- `isValidISO(input?)` -- returns whether the provided date string is a valid ISO date
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*
+
+# wm-datepicker
+
+## Purpose
+
+A form input that lets users specify a single date either by typing it directly into a text field or by selecting it from a calendar popup.
+
+---
+
+## When to Use
+
+- **Collecting a single date value in a form** -- when a user needs to provide one specific date (a due date, start date, birth date, submission deadline), Datepicker is the standard input, offering both typed entry for speed and a calendar popup for browsing.
+
+---
+
+## Do Not Use For
+
+- **Selecting a start and end date together** -- if the input represents a range, use wm-date-range instead; Datepicker only captures a single date and has no concept of a paired second value.
+- **Inputs where time is also required** -- Datepicker captures dates only; if the user also needs to specify a time, pair it with wm-timepicker rather than expecting Datepicker to handle both.
+
+---
+
+## Related Components
+
+- `<wm-date-range>` -- if the user needs to select both a start and end date together, use Date Range; Datepicker is for a single date only.
+- `<wm-timepicker>` -- if a time of day is also required alongside the date, pair Datepicker with Timepicker; Datepicker has no time input capability.
+- `<wm-input>` -- if the value being collected looks like a date but has no need for calendar navigation or date validation (e.g., a free-form year field), a plain Input may be sufficient; Datepicker is warranted when the calendar picker or date validation utilities add genuine value.
+
+---
+
+## Accessibility
+
+- Accepting dates in a specific format: when the application requires a particular date format (e.g., international vs. US ordering), use the date-format property to communicate the expected format via the placeholder and screen reader messages, reducing input errors.
+- Pre-focusing the calendar on a relevant date: when a default or suggested date exists (e.g., today, the start of a term), use the preselected property to open the calendar already positioned at that date, reducing navigation for the user.
+- Validating a date entry externally: when the application needs to check whether a user-entered date is valid before saving, the component exposes isValidIso and reformatDate methods to support format conversion and validation without requiring custom parsing logic.
+- Do not omit the label when hiding the visual label: the label is required for accessibility even when label-position="none"; omitting it leaves the field without a name for screen reader users.
+- Conditional DOM rendering to show/hide the component: because the component manages its own calendar popup state, removing and re-adding it from the DOM can cause unexpected behavior; control visibility through other means.
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- `label` -- required for accessibility even when label-position="none"
+- `labelPosition` -- "top", "left", or "none"
+- `dateFormat` -- specifies the expected date format (e.g., MM/DD/YYYY)
+- `preselected` -- a date string used to pre-position the calendar when it opens; does not set the field value
+- `value` -- the current date value of the input
+- `errorMessage` -- validation error text displayed below the field
+- `requiredField` -- marks the field as required
+- `disabled` -- disables the input and calendar button
+
+---
+
+## Events
+
+- `wmDatepickerDateSelected` -- fires when the user selects a date or types a complete valid date
+- `wmDatepickerInputBlurred` -- fires when the input loses focus
+
+---
+
+## Methods
+
+- `reformatDate(inputFormat, outputFormat, date?)` -- converts a date string between formats
+- `isValidIso(input?)` -- returns whether the current or provided date string is a valid ISO date
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-datepicker.md

@@ -0,0 +1,210 @@
+# `wm-datepicker`
+
+Date input that lets users type a date or pick one from a calendar popup. Supports
+configurable date formats, pre-selection, validation, and full keyboard navigation of the calendar.
+Use instead of native `<input type="date">`.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `dateFormat` | `date-format` | `string` | `"mm/dd/yyyy"` |  |  |
+| `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 \| undefined` | `""` |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmDatepickerDateSelected` | `any` | ✓ |  |
+| `wmDatepickerInputBlurred` | `any` | ✓ |  |
+
+## Methods
+
+### `isValidIso(input?: string) => Promise<boolean>`
+
+**Parameters**
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `input` | `string \| undefined` | - The string to validate. |
+
+**Returns** `Promise<boolean>` -- `true` if the string is a valid ISO date, `false` otherwise.
+
+### `reformatDate(inputFormat: "US" | "INT" | "ISO", outputFormat: "US" | "INT" | "ISO", date?: string) => Promise<string>`
+
+**Parameters**
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `inputFormat` | `"US" \| "INT" \| "ISO"` | - Format of the input date string. |
+| `outputFormat` | `"US" \| "INT" \| "ISO"` | - Desired output format. |
+| `date` | `string \| undefined` | - The date string to reformat. |
+
+**Returns** `Promise<string>` -- The reformatted date string, an empty string if `date` is omitted or falsy, or the
+original string unchanged if it cannot be parsed.
+
+## Depends On
+
+- `priv-calendar`
+
+# wm-date-range
+
+## Purpose
+
+A paired date input that lets users specify both a start and end date by typing or using a shared calendar popup. The two values are treated as a single, related range.
+
+---
+
+## When to Use
+
+- **Collecting a bounded time period with a start and end** -- when a user needs to define a window of time (a reporting period, an enrollment window, a project timeline), use Date Range to capture both boundary dates as a single, semantically linked input rather than two independent Datepickers.
+- **Filtering data by a date range** -- when a user is narrowing results by a time window (e.g., "show records between these two dates"), Date Range provides the right interaction model with a shared calendar that highlights the selected span visually.
+- **Enforcing range integrity at the form level** -- when the application needs to validate that the start date precedes the end date, Date Range exposes the right blur events and standardized error messages to handle all range validation scenarios consistently.
+- **Allowing range selection via a shared calendar popup** -- when users benefit from seeing both dates in context on a calendar, Date Range's shared popup highlights the full selected range, which two independent Datepickers cannot do.
+
+---
+
+## Do Not Use For
+
+- **Two separate dates that happen to be related** -- if the two dates are logically a range, use Date Range; two independent Datepickers have no shared calendar, no range highlighting, and no built-in mechanism to enforce that start precedes end.
+- **Selecting a single point in time** -- if the user is selecting one date rather than a span, use wm-datepicker; Date Range always manages two values and two validation states, which is unnecessary overhead for a single date.
+
+---
+
+## Related Components
+
+- `<wm-datepicker>` -- if only a single date is needed rather than a start-and-end pair, use Datepicker; Date Range always manages two values and is only appropriate when both are required together.
+- `<wm-timepicker>` -- if the range also needs to capture times of day, Date Range has no time input; pair it with Timepicker fields for the start and end times separately.
+- `<wm-select>` -- if the user is choosing from a predefined list of named time periods (e.g., "Q1 2025", "Fall Semester") rather than specifying arbitrary dates, Select is more appropriate; Date Range is for open-ended date entry.
+
+---
+
+## Accessibility
+
+- Validating on every keystroke: all validations should be performed on blur, not while the user is still typing; premature validation fires errors before the user has finished entering a value.
+- Clearing errors on blur: errors should be cleared when the field is focused again, not when it blurs; reversing this produces confusing behavior where errors appear and disappear at unexpected moments.
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- `labelStart` -- required; the accessible label for the start date input
+- `labelEnd` -- required; the accessible label for the end date input
+- `dateFormat` -- specifies the expected date format for both inputs
+- `preselected` -- a date string used to pre-position the calendar when it opens
+- `valueStart` -- the current start date value
+- `valueEnd` -- the current end date value
+- `invalidStart` -- marks the start date input as invalid; triggers error styling
+- `invalidEnd` -- marks the end date input as invalid; triggers error styling
+- `errorMessage` -- validation error text displayed below the component
+- `requiredField` -- marks both fields as required
+- `disabled` -- disables both inputs and the calendar button
+
+---
+
+## Events
+
+- `wmRangeSelection` -- fires when the user completes a range selection in the calendar
+- `wmStartInputBlur` -- fires when the start date input loses focus; trigger start date validation here
+- `wmEndInputBlur` -- fires when the end date input loses focus; trigger end date and range integrity validation here
+
+---
+
+## Methods
+
+- `reformatDate(inputFormat, outputFormat, date?)` -- converts a date string between formats
+- `isValidISO(input?)` -- returns whether the provided date string is a valid ISO date
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*
+
+# wm-datepicker
+
+## Purpose
+
+A form input that lets users specify a single date either by typing it directly into a text field or by selecting it from a calendar popup.
+
+---
+
+## When to Use
+
+- **Collecting a single date value in a form** -- when a user needs to provide one specific date (a due date, start date, birth date, submission deadline), Datepicker is the standard input, offering both typed entry for speed and a calendar popup for browsing.
+
+---
+
+## Do Not Use For
+
+- **Selecting a start and end date together** -- if the input represents a range, use wm-date-range instead; Datepicker only captures a single date and has no concept of a paired second value.
+- **Inputs where time is also required** -- Datepicker captures dates only; if the user also needs to specify a time, pair it with wm-timepicker rather than expecting Datepicker to handle both.
+
+---
+
+## Related Components
+
+- `<wm-date-range>` -- if the user needs to select both a start and end date together, use Date Range; Datepicker is for a single date only.
+- `<wm-timepicker>` -- if a time of day is also required alongside the date, pair Datepicker with Timepicker; Datepicker has no time input capability.
+- `<wm-input>` -- if the value being collected looks like a date but has no need for calendar navigation or date validation (e.g., a free-form year field), a plain Input may be sufficient; Datepicker is warranted when the calendar picker or date validation utilities add genuine value.
+
+---
+
+## Accessibility
+
+- Accepting dates in a specific format: when the application requires a particular date format (e.g., international vs. US ordering), use the date-format property to communicate the expected format via the placeholder and screen reader messages, reducing input errors.
+- Pre-focusing the calendar on a relevant date: when a default or suggested date exists (e.g., today, the start of a term), use the preselected property to open the calendar already positioned at that date, reducing navigation for the user.
+- Validating a date entry externally: when the application needs to check whether a user-entered date is valid before saving, the component exposes isValidIso and reformatDate methods to support format conversion and validation without requiring custom parsing logic.
+- Do not omit the label when hiding the visual label: the label is required for accessibility even when label-position="none"; omitting it leaves the field without a name for screen reader users.
+- Conditional DOM rendering to show/hide the component: because the component manages its own calendar popup state, removing and re-adding it from the DOM can cause unexpected behavior; control visibility through other means.
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- `label` -- required for accessibility even when label-position="none"
+- `labelPosition` -- "top", "left", or "none"
+- `dateFormat` -- specifies the expected date format (e.g., MM/DD/YYYY)
+- `preselected` -- a date string used to pre-position the calendar when it opens; does not set the field value
+- `value` -- the current date value of the input
+- `errorMessage` -- validation error text displayed below the field
+- `requiredField` -- marks the field as required
+- `disabled` -- disables the input and calendar button
+
+---
+
+## Events
+
+- `wmDatepickerDateSelected` -- fires when the user selects a date or types a complete valid date
+- `wmDatepickerInputBlurred` -- fires when the input loses focus
+
+---
+
+## Methods
+
+- `reformatDate(inputFormat, outputFormat, date?)` -- converts a date string between formats
+- `isValidIso(input?)` -- returns whether the current or provided date string is a valid ISO date
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-file-list.md

@@ -0,0 +1,95 @@
+# `wm-file-list`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `showInfo` | `show-info` | `"all" \| "last-updated" \| "none" \| "size" \| "uploaded-by"` | `"last-updated"` |  |  |
+
+## Slots
+
+| Name | Description |
+| ---- | ----------- |
+| _(default)_ | One or more wm-file child elements. |
+
+# wm-file-list
+
+## Purpose
+
+A read-only display component that presents a list of existing files with their metadata and per-file actions (preview, download, delete), distinct from the Uploader in that it surfaces files already in the system rather than accepting new ones.
+
+---
+
+## When to Use
+
+- **Displaying files already associated with a record** -- when a page or form needs to show files that have previously been uploaded or attached (e.g., supporting documents on a profile, attachments on a submission), use File List to surface them with consistent metadata and actions.
+- **Allowing users to download or preview existing files** -- when the user's relationship to the files is read-access (they need to open or save a file but not replace it), use File List with file-actions="preview download" on each wm-file.
+- **Surfacing file-level error states** -- when a specific file in the list has failed validation or processing, use the error-message property on the individual wm-file to communicate the problem at the file level rather than at the form level.
+
+---
+
+## Do Not Use For
+
+- **Accepting new file uploads** -- File List is explicitly read-only and has no upload mechanism; if users need to add files, use wm-uploader instead, and pair it with File List to show what has already been uploaded.
+- **Empty states** -- File List has no empty state handling built in; if the list may be empty and that state needs a message or call to action, the surrounding page must handle that.
+- **General-purpose lists of records** -- File List is purpose-built for files with extensions, metadata, and file-specific actions; it is not a substitute for a generic list or table of records.
+
+---
+
+## Related Components
+
+- `<wm-uploader>` -- if users need to add new files, use Uploader; File List is strictly for displaying and acting on files that already exist. The two are commonly paired: Uploader to add, File List to review what has been added.
+
+---
+
+## Accessibility
+
+_Not documented_
+
+---
+
+## Variants / Types
+
+_None documented_
+
+---
+
+## Props
+
+- wm-file-list props:
+- `showInfo` -- controls which metadata columns are shown: "size", "last-updated", "uploaded-by", "all", or "none"
+- `wm-file props (child` -- one per file):
+- `name` -- required; the file's display name
+- `type` -- required; the file's MIME type or extension
+- `showInfo` -- overrides the parent list's showInfo for this individual file
+- `fileActions` -- space-separated string of actions available on this file (e.g., "preview download delete")
+- `progress` -- upload progress as a number 0-100; renders a progress bar when set
+- `errorMessage` -- error text scoped to this individual file
+- `size` -- display string for the file size (e.g., "2.4 MB")
+- `lastUpdated` -- display string for the last updated timestamp
+- `uploadedBy` -- display string for the name of the user who uploaded the file
+
+---
+
+## Events
+
+- `wmFilePreview` -- fires when the user activates the preview action
+- `wmFileDownload` -- fires when the user activates the download action
+- `wmFileDelete` -- fires when the user activates the delete action
+- `wmFileErrorCleared` -- fires when the user dismisses a file-level error
+
+---
+
+## Methods
+
+- _None exposed_
+
+---
+
+## Code Example
+
+*(to be filled in by developer)*

package/dist/docs/wm-file.md

@@ -0,0 +1,34 @@
+# `wm-file`
+
+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.
+
+## Props
+
+| Name | Attribute | Type | Default | Required | Description |
+| ---- | --------- | ---- | ------- | -------- | ----------- |
+| `errorMessage` | `error-message` | `string \| undefined` |  |  |  |
+| `fileActions` | `file-actions` | `string` | `"download delete"` |  |  |
+| `lastUpdated` | `last-updated` | `string \| undefined` |  |  |  |
+| `name` | `name` | `string` |  | ✓ |  |
+| `progress` | `progress` | `number \| undefined` |  |  |  |
+| `showInfo` | `show-info` | `"all" \| "last-updated" \| "none" \| "size" \| "time" \| "uploaded-by" \| undefined` | `"last-updated"` |  |  |
+| `size` | `size` | `string \| undefined` |  |  |  |
+| `type` | `type` | `string` |  | ✓ |  |
+| `uploadedBy` | `uploaded-by` | `string \| undefined` |  |  |  |
+
+## Events
+
+| Event | Detail | Bubbles | Description |
+| ----- | ------ | ------- | ----------- |
+| `wmFileDelete` | `any` | ✓ |  |
+| `wmFileDownload` | `any` | ✓ |  |
+| `wmFileErrorCleared` | `any` | ✓ |  |
+| `wmFilePreview` | `any` | ✓ |  |
+
+## Depends On
+
+- `wm-menuitem`
+- `wm-action-menu`
+- `wm-button`