FRD-060: Share Modal Widget

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

---

Document Summary

A share modal widget that provides copy-link, invite-by-email, and permission-level toggling in a single dialog. Suitable for sharing documents, dashboards, projects, or any resource that supports link-based and email-based collaboration.

---

Introduction

Overview

Sharing resources is a universal SaaS pattern. Teams repeatedly build share dialogs with inconsistent UX for link copying, email invitations, and permission management. This widget standardizes the pattern into a reusable, accessible modal.

Goals

• One-click copy-link with confirmation feedback.
• Email invitation input with multiple-recipient support.
• Permission-level selector (e.g., Viewer, Editor, Admin) per invite.
• Display existing share recipients with their permission levels.
• Ship Storybook stories covering all interaction states.

Non-Goals

• Actual email delivery (consumer handles via callback).
• User search or autocomplete from a directory service.
• Granular per-field or per-section permissions.
• Public/private link toggle with server-side enforcement.

---

Scope

In Scope

Item	Description
ShareModal component	Modal dialog with copy-link, invite form, and recipient list
Copy-link section	URL display with copy button and toast/inline confirmation
Invite-by-email section	Email input, permission selector, and send button
Recipient list	Shows current recipients with name, email, and permission level
Permission toggle	Dropdown to change permission level per recipient
Storybook stories	Default, WithRecipients, InviteSent, CopyConfirmation, Loading

Out of Scope

Item	Rationale
Email delivery	Backend concern; widget calls onInvite callback
User directory search	Requires integration with identity provider
Link expiration settings	Future enhancement
Embedded share (non-modal)	Can extract to a separate component later

---

Users and Pain Points

User	Pain Point
SaaS product teams	Building share dialogs from scratch per project
End users	Inconsistent sharing flows across different product areas
Administrators	No standard way to view and manage who has access

---

Definitions

Term	Definition
Share link	A URL that grants access to a resource
Permission level	The access tier granted to a recipient (e.g., Viewer, Editor)
Recipient	A user who has been granted access via email invite or link

---

Current State

No share modal exists in the design system. Products implement ad-hoc share dialogs using the base Dialog component, leading to inconsistent patterns for link copying, invitation, and permission management.

---

Proposed Solution

Create a ShareModal widget at src/components/widgets/share-modal.tsx that:

1. Wraps the existing Dialog component.
2. Displays a read-only URL field with a copy-to-clipboard button.
3. Provides an email input for inviting new recipients with a permission-level dropdown.
4. Lists current recipients with their permission levels and an option to revoke.
5. Calls consumer-provided callbacks for invite, permission change, and revoke actions.

---

Requirements

The modal must be fully controlled (open state via props), use existing Dialog primitives, and handle clipboard API gracefully with fallback.

---

Functional Requirements

ID	Requirement	Priority
FR-01	Display a share URL with a copy-to-clipboard button	Must
FR-02	Show inline confirmation (“Copied!”) after successful copy	Must
FR-03	Provide an email text input for entering recipient addresses	Must
FR-04	Support comma-separated multiple email entry	Must
FR-05	Include a permission-level dropdown (configurable options)	Must
FR-06	Call onInvite({ emails, permission }) on send	Must
FR-07	Display a list of current recipients with name, email, and permission	Must
FR-08	Allow permission changes on existing recipients via onChangePermission	Should
FR-09	Allow revoking access via onRevoke(recipientId)	Should
FR-10	Validate email format before allowing send	Must

---

Non-Functional Requirements

ID	Requirement
NFR-01	Clipboard copy works in all modern browsers; graceful fallback with execCommand
NFR-02	Modal animation follows design-system motion tokens
NFR-03	Full light/dark theme support

---

API / Interface Requirements

interface ShareRecipient {
  id: string;
  name?: string;
  email: string;
  permission: string;
  avatarUrl?: string;
}

interface ShareModalProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  shareUrl: string;
  recipients?: ShareRecipient[];
  permissionOptions: { value: string; label: string }[];
  defaultPermission?: string;
  title?: string;
  onInvite?: (payload: { emails: string[]; permission: string }) => Promise<void>;
  onChangePermission?: (recipientId: string, permission: string) => void;
  onRevoke?: (recipientId: string) => void;
  className?: string;
}

---

Accessibility Requirements

ID	Requirement
A11Y-01	Modal traps focus and returns focus on close per WAI-ARIA dialog pattern
A11Y-02	Copy button announces result via aria-live region
A11Y-03	Email input has a visible label
A11Y-04	Permission dropdown is keyboard-navigable
A11Y-05	Recipient list items have accessible names including email and permission
A11Y-06	Revoke buttons include aria-label with recipient name

---

Content and Documentation Requirements

• Storybook doc page with props, usage examples, and composition guidance.
• Stories: Default, WithRecipients, InviteSending, CopyConfirmation, EmptyRecipients.
• JSDoc on all exported types and the main component.

---

Dependencies

Dependency	Type	Notes
Dialog	Internal	Modal container
Button	Internal	Copy, send, and revoke actions
Input	Internal	Email entry
DropdownMenu or Select	Internal	Permission selector
Clipboard API	Browser	Copy-to-clipboard; execCommand fallback

---

Risks and Tradeoffs

Risk	Impact	Mitigation
Clipboard API unavailable in older browsers	Copy fails silently	Implement execCommand fallback; show manual-copy instructions
Email validation false negatives	Valid emails rejected	Use a permissive regex; let server do final validation
Large recipient lists	Modal becomes unwieldy	Cap visible list at 10; add “Show all” expansion

---

Open Questions

1. Should the modal support a “link permissions” section (e.g., “Anyone with link can view”)?
2. Do we need avatar rendering for recipients, or just initials?
3. Should there be a “copy invite link” per-recipient option?

---

Acceptance Criteria

• Share URL is displayed and copyable with one click.
• Copy confirmation appears and auto-dismisses.
• Email input validates format and supports multiple addresses.
• Permission dropdown works for new invites and existing recipients.
• onInvite, onChangePermission, and onRevoke callbacks fire correctly.
• All Storybook stories render without errors.
• Passes axe accessibility audit with zero violations.
• Unit tests cover copy, invite, permission change, and revoke flows.

---

LLM Handoff Instructions

When implementing this FRD:

1. Create src/components/widgets/share-modal.tsx.
2. Use the existing Dialog component as the modal shell.
3. Use navigator.clipboard.writeText with document.execCommand("copy") fallback.
4. Create src/components/widgets/share-modal.stories.tsx with all listed stories.
5. Create src/components/widgets/share-modal.test.tsx.
6. Follow existing widget conventions (see team-switcher.tsx for modal-based widget patterns).
7. Email validation: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ is sufficient for client-side.

---

Decision Log

Date	Decision	Rationale
2026-05-26	Fully controlled modal (open/onOpenChange)	Consistent with Dialog API; consumer owns trigger
2026-05-26	Permission options are consumer-configurable	Different products have different permission models

---

Document History

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