FRD-061: Export Menu Widget

Field	Value
Owner	David Holmes
Status	Draft
Last Updated	2026-05-26
Target Release	v2.0.0 (P2)
T-Shirt Size	S
Type	Widget

---

Document Summary

A dropdown-based export menu widget that lets users choose an export format, optionally select which fields to include, and trigger a download. Designed for data tables, reports, and dashboard exports across SaaS products.

---

Introduction

Overview

Data export is a recurring need in SaaS applications. Users expect to download table data, reports, or filtered views in formats like CSV, JSON, XLSX, or PDF. This widget provides a standardized export dropdown with format selection, optional field picking, and a download CTA.

Goals

• Dropdown menu triggered by an export button.
• Format picker supporting configurable format options (CSV, JSON, XLSX, PDF, etc.).
• Optional field-selection checklist for choosing which columns/fields to export.
• Download CTA that invokes a consumer callback with selected format and fields.
• Ship Storybook stories covering format-only, with-field-selection, and loading states.

Non-Goals

• Actual file generation (consumer produces the file blob or URL).
• Server-side export orchestration.
• Scheduled or recurring exports.
• Email delivery of export files.

---

Scope

In Scope

Item	Description
ExportMenu component	Dropdown with format picker, field selector, and download CTA
Format options	Configurable list of export formats
Field selection	Optional checklist of fields/columns to include
Download action	Calls onExport({ format, fields }) callback
Storybook stories	FormatsOnly, WithFieldSelection, Loading, Disabled

Out of Scope

Item	Rationale
File generation	Consumer handles blob/URL creation
Background export jobs	Requires backend queuing infrastructure
Export history	Separate widget concern

---

Users and Pain Points

User	Pain Point
Data analysts	Inconsistent export options across different tables and views
Product teams	Rebuilding export menus per feature with varying format support
End users	Not knowing which formats are available or what data will be included

---

Definitions

Term	Definition
Export format	The file type for the download (e.g., CSV, JSON, XLSX, PDF)
Field selection	A subset of available data columns the user chooses to include
Download CTA	The button that initiates the export/download action

---

Current State

No export menu widget exists. Products use ad-hoc dropdown menus or inline buttons for exports. The DropdownMenu primitive is available and can serve as the foundation.

---

Proposed Solution

Create an ExportMenu widget at src/components/widgets/export-menu.tsx that:

1. Renders a trigger button (configurable label, defaults to “Export”).
2. Opens a dropdown menu with format options as selectable items.
3. Optionally shows a field-selection checklist when fields prop is provided.
4. Includes a “Download” or “Export” CTA at the bottom of the dropdown.
5. Calls onExport with the selected format and fields.
6. Supports a loading state that shows a spinner on the CTA and disables interaction.

---

Requirements

The widget is a controlled dropdown that delegates all file generation to the consumer via callbacks. It must not trigger file downloads directly.

---

Functional Requirements

ID	Requirement	Priority
FR-01	Render a trigger button that opens the export dropdown	Must
FR-02	Display a list of format options with icons and labels	Must
FR-03	Allow single-select of a format (radio behavior)	Must
FR-04	Optionally display a field checklist with select-all/deselect-all	Should
FR-05	Render a download CTA button inside the dropdown	Must
FR-06	Call onExport({ format, fields }) when CTA is clicked	Must
FR-07	Support a loading prop that disables CTA and shows spinner	Must
FR-08	Support a disabled prop on the trigger button	Must
FR-09	Close the dropdown after successful export callback	Should
FR-10	Pre-select a default format via defaultFormat prop	Should

---

Non-Functional Requirements

ID	Requirement
NFR-01	Bundle size under 2 KB gzipped (excluding shared primitives)
NFR-02	Dropdown opens within one animation frame
NFR-03	Full light/dark theme support

---

API / Interface Requirements

interface ExportFormat {
  id: string;
  label: string;
  icon?: ReactNode;
  description?: string;
}

interface ExportField {
  id: string;
  label: string;
  defaultSelected?: boolean;
}

interface ExportMenuProps {
  formats: ExportFormat[];
  fields?: ExportField[];
  defaultFormat?: string;
  triggerLabel?: string;       // default "Export"
  downloadLabel?: string;      // default "Download"
  loading?: boolean;
  disabled?: boolean;
  onExport: (payload: { format: string; fields?: string[] }) => void | Promise<void>;
  className?: string;
}

---

Accessibility Requirements

ID	Requirement
A11Y-01	Dropdown follows WAI-ARIA menu pattern with keyboard navigation
A11Y-02	Format options use role="menuitemradio" with aria-checked
A11Y-03	Field checkboxes use role="menuitemcheckbox" with aria-checked
A11Y-04	Trigger button has aria-haspopup="menu" and aria-expanded
A11Y-05	Loading state conveys status via aria-busy on the CTA

---

Content and Documentation Requirements

• Storybook doc page with props, usage examples, and integration guidance.
• Stories: FormatsOnly, WithFieldSelection, Loading, Disabled, PreselectedFormat.
• JSDoc on all exported types and the main component.

---

Dependencies

Dependency	Type	Notes
DropdownMenu	Internal	Menu container and item primitives
Button	Internal	Trigger and download CTA
Checkbox	Internal	Field selection items
Spinner	Internal	Loading state

---

Risks and Tradeoffs

Risk	Impact	Mitigation
Long field lists overflow the dropdown	Poor UX	Cap visible fields at 10 with scroll; add search filter in follow-up
Format icons inconsistency	Visual clutter	Provide default icons for common formats (CSV, JSON, PDF, XLSX)
Async export takes too long	User re-clicks	Disable CTA during loading; show progress if export is slow

---

Open Questions

1. Should the dropdown remain open during async export, or close immediately?
2. Do we need a “Select columns” sub-menu or inline checklist?
3. Should there be a “Remember my preferences” option using localStorage?

---

Acceptance Criteria

• Trigger button opens a dropdown with format options.
• Selecting a format and clicking download calls onExport with correct payload.
• Field selection checklist works with select-all/deselect-all.
• Loading state disables the CTA and shows a spinner.
• All Storybook stories render without errors.
• Passes axe accessibility audit with zero violations.
• Unit tests cover format selection, field selection, and export callback.

---

LLM Handoff Instructions

When implementing this FRD:

1. Create src/components/widgets/export-menu.tsx.
2. Use DropdownMenu from @/components/ui/dropdown-menu as the foundation.
3. Create src/components/widgets/export-menu.stories.tsx with all listed stories.
4. Create src/components/widgets/export-menu.test.tsx.
5. Provide default icons for CSV (FileText), JSON (Code2), PDF (FileText), XLSX (Table) from the icon pack.
6. Follow existing widget patterns for prop naming and callback conventions.

---

Decision Log

Date	Decision	Rationale
2026-05-26	Widget does not generate files	Keeps the widget portable; file generation varies by data source
2026-05-26	Field selection is optional	Many exports don’t need field picking; keeps the simple case simple

---

Document History

Date	Version	Author	Changes
2026-05-26	0.1	David Holmes	Initial draft