reactbin/specs/016-copy-url-toast/spec.md

Feature Specification: Copy URL & Toast Notifications

Feature Branch: 016-copy-url-toast Created: 2026-05-09 Status: Draft

User Scenarios & Testing (mandatory)

User Story 1 - Copy Image URL from Detail Page (Priority: P1)

A user viewing an image on the detail page wants to share the direct link to that image. They click a "Copy URL" button and the image's direct URL is instantly copied to their clipboard, ready to paste anywhere.

Why this priority: This is the core feature and the primary user value. Everything else builds on it.

Independent Test: Open any image detail page. Click the "Copy URL" button. Paste into a text editor — confirm the pasted value is the direct URL to that image.

Acceptance Scenarios:

1. Given a user is on an image detail page, When they click "Copy URL", Then the image's direct URL is copied to their clipboard.
2. Given a user clicks "Copy URL", When the copy succeeds, Then a confirmation toast appears briefly and disappears on its own.
3. Given a user clicks "Copy URL", When the clipboard is unavailable (e.g. browser denies permission), Then a toast appears indicating the copy failed.

---

User Story 2 - Reusable Toast Notification System (Priority: P2)

Any part of the application can trigger a brief, non-blocking notification (toast) to confirm an action or surface an error. The toast appears, persists for a short time, then disappears automatically without user interaction.

Why this priority: The toast infrastructure is needed by US1 and is designed as a foundation for future features (e.g. upload confirmation, filter saved, delete confirmed).

Independent Test: Trigger a toast programmatically. Confirm it appears with the correct message, then disappears automatically after a few seconds without any user interaction.

Acceptance Scenarios:

1. Given a toast is triggered, When it appears, Then it displays the provided message and is visible above other content.
2. Given a toast is visible, When sufficient time passes, Then it disappears automatically without user interaction.
3. Given multiple toasts are triggered in quick succession, When they appear, Then they stack or queue without overlapping illegibly.
4. Given a toast is visible, When the user interacts with the rest of the page, Then the toast does not block or intercept those interactions.

---

Edge Cases

• What happens when the clipboard API is not available or permission is denied? → Show an error toast.
• What happens if the user clicks "Copy URL" multiple times rapidly? → Each click copies and shows a toast; toasts queue or stack cleanly.
• What happens on a very long URL? → URL is copied in full; toast message is fixed (not the URL itself).

Requirements (mandatory)

Functional Requirements

• FR-001: The image detail page MUST display a "Copy URL" button.
• FR-002: Clicking "Copy URL" MUST copy the image's direct URL to the system clipboard.
• FR-003: A success toast MUST appear after a successful copy, confirming the action to the user.
• FR-004: A failure toast MUST appear if the copy cannot be completed (e.g. clipboard permission denied).
• FR-005: Toasts MUST disappear automatically after a fixed duration without requiring user interaction.
• FR-006: Toasts MUST NOT block user interaction with the rest of the page.
• FR-007: The toast system MUST be reusable — any part of the application must be able to trigger a toast with a custom message.
• FR-008: Multiple toasts triggered in quick succession MUST display without overlapping illegibly.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: A user can copy an image URL in a single click with no additional steps.
• SC-002: Toast confirmation appears within 300ms of the copy action completing.
• SC-003: Toasts disappear automatically within 5 seconds of appearing.
• SC-004: The toast system can be triggered from any page or component without modifying the toast component itself.

Assumptions

• The image's direct URL is already available on the detail page (it is — currently displayed or derivable from the current route and API response).
• Users are on modern browsers with Clipboard API support; graceful degradation covers the failure case via an error toast.
• One toast variant is sufficient for v1: a simple text message with success/error styling. No actions, no dismiss button required.
• Toast duration of approximately 3 seconds is appropriate (standard convention).
• The detail page already exists; this feature adds to it without redesigning it.