ag/unisono
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Copy Link feature designed

Browse Source
This commit is contained in:
AG
2025-10-13 20:00:59 +03:00
parent 60e9c24440
commit 696c3ed6c7
10 changed files with 333 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
specs/006-copy-link-feature/checklists/requirements.md Normal file
View File

@@ -0,0 +1,34 @@
# Specification Quality Checklist: Copy Link Feature
**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: 2025-10-13
**Feature**: [Link to spec.md](D:/Coding/unisono/specs/006-copy-link-feature/spec.md)
## Content Quality
- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed
## Requirement Completeness
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Success criteria are technology-agnostic (no implementation details)
- [x] All acceptance scenarios are defined
- [x] Edge cases are identified
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified
## Feature Readiness
- [x] All functional requirements have clear acceptance criteria
- [x] User scenarios cover primary flows
- [x] Feature meets measurable outcomes defined in Success Criteria
- [x] No implementation details leak into specification
## Notes
- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`

3
specs/006-copy-link-feature/contracts/openapi.yaml Normal file
View File

@@ -0,0 +1,3 @@
# OpenAPI Specification for Copy Link Feature
This feature is purely frontend and does not introduce any new backend API endpoints or modify existing ones in a way that requires new API contracts. It primarily interacts with the browser's URL and Clipboard API.

10
specs/006-copy-link-feature/data-model.md Normal file
View File

@@ -0,0 +1,10 @@
# Data Model: Copy Link Feature
This feature primarily operates on existing frontend data structures and browser APIs. The key entity involved is:
## Session
- **Description**: Represents an active user session within the frontend application.
- **Attributes relevant to this feature**:
- `url`: The unique URL of the current session, which is to be copied to the clipboard.
- **Relationships**: None directly introduced or modified by this feature.

87
specs/006-copy-link-feature/plan.md Normal file
View File

@@ -0,0 +1,87 @@
# Implementation Plan: [FEATURE]
**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
## Summary
This feature introduces a 'Copy Link' button on the session response and result pages. Upon clicking, the button will copy the current session's URL to the user's clipboard and provide visual feedback through an icon animation (link icon transforming to a green checkmark and then reverting) to confirm the successful copy operation. The technical approach will leverage existing React components and Material-UI for the frontend, and the browser's native Clipboard API for copying functionality.
## Technical Context
<!--
ACTION REQUIRED: Replace the content in this section with the technical details
for the project. The structure here is presented in advisory capacity to guide
the iteration process.
-->
## Technical Context
**Language/Version**: Node.js (LTS), TypeScript 5.x, React
**Primary Dependencies**: Material-UI / MUI, React Router, Browser's native Clipboard API
**Storage**: N/A (frontend feature, no direct storage interaction)
**Testing**: Jest, React Testing Library, `npm test`, `npm run lint`
**Target Platform**: Web browsers
**Project Type**: Web application (frontend)
**Performance Goals**: Icon transition completes within 0.5 seconds, reverts within 3.5 seconds. Button appears within 1 second of page load.
**Constraints**: Reliance on browser's Clipboard API. Graceful degradation for unsupported browsers.
**Scale/Scope**: Individual session sharing functionality within the existing application context.
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
### Core Principles
- **I. Conventions**: Adhering to existing React/Material-UI conventions for component development and styling.
- **II. Libraries/Frameworks**: Utilizing Material-UI (already established) and the browser's native Clipboard API. No new external libraries are introduced.
- **III. Style & Structure**: Mimicking existing frontend React component structure, Material-UI styling, and TypeScript typing.
- **IV. Idiomatic Changes**: Integrating changes idiomatically within the React component lifecycle and Material-UI usage patterns.
- **V. Comments**: Comments will be added sparingly, focusing on the rationale behind specific implementations, especially for animation logic or graceful degradation.
### Quality Gates
- **I. Proactiveness**: Unit tests will be added for the new 'Copy Link' component and its associated functionality, covering successful copy, animation, and graceful degradation.
- **II. Verification (Tests)**: Existing `npm test` command and Jest/React Testing Library framework will be used for verification.
- **III. Verification (Standards)**: `npm run lint` and `tsc` will be executed to ensure code quality and adherence to TypeScript standards.
## Project Structure
### Documentation (this feature)
```
specs/[###-feature]/
├── plan.md # This file (/speckit.plan command output)
├── research.md # Phase 0 output (/speckit.plan command)
├── data-model.md # Phase 1 output (/speckit.plan command)
├── quickstart.md # Phase 1 output (/speckit.plan command)
├── contracts/ # Phase 1 output (/speckit.plan command)
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```
## Project Structure
### Documentation (this feature)
```
specs/006-copy-link-feature/
├── plan.md # This file (/speckit.plan command output)
├── research.md # Phase 0 output (/speckit.plan command)
├── data-model.md # Phase 1 output (/speckit.plan command)
├── quickstart.md # Phase 1 output (/speckit.plan command)
├── contracts/ # Phase 1 output (/speckit.plan command)
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```
### Source Code (repository root)
```
frontend/
├── src/
│ ├── components/ # New CopyLinkButton.tsx component will be added here
│ ├── pages/ # Existing SessionPage.tsx and ResultsDisplay.tsx will be modified here
│ └── services/
└── tests/ # New tests for CopyLinkButton.tsx will be added here
```
**Structure Decision**: The feature will be implemented within the existing `frontend` project structure. A new `CopyLinkButton.tsx` component will be created in `frontend/src/components`, and `frontend/src/pages/SessionPage.tsx` and `frontend/src/components/ResultsDisplay.tsx` will be modified to integrate this button. Corresponding tests will be added to `frontend/tests`.

3
specs/006-copy-link-feature/quickstart.md Normal file
View File

@@ -0,0 +1,3 @@
# Quickstart: Copy Link Feature
This feature is purely frontend and does not require any specific backend setup or quickstart instructions beyond the general project setup. Once the frontend application is running, navigate to any session response or result page to observe the 'Copy Link' button functionality.

3
specs/006-copy-link-feature/research.md Normal file
View File

@@ -0,0 +1,3 @@
# Research for Copy Link Feature
No specific research tasks were identified during the planning phase as the technical context is clear and relies on established patterns and browser APIs.

83
specs/006-copy-link-feature/spec.md Normal file
View File

@@ -0,0 +1,83 @@
# Feature Specification: Copy Link Feature
**Feature Branch**: `006-copy-link-feature`
**Created**: 2025-10-13
**Status**: Draft
**Input**: User description: "Copy Link feature. On the response and result pages display a "Copy Link" button. It must pe placed next to the session Topic and be of the secondary color. On click copy the address of the current session to the buffer. Icon: link. Animation: 'link' icon changes to green 'check' icon through dissolve and in 3 seconds changes back."
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Share Session Link from Response Page (Priority: P1)
As a user on the session response page, I want to easily copy the current session's link so I can share it with others.
**Why this priority**: This is a core sharing functionality, enabling collaboration and distribution of session results, which is fundamental to the application's purpose.
**Independent Test**: Can be fully tested by navigating to a session response page, clicking the "Copy Link" button, and verifying the URL is copied to the clipboard and the animation plays correctly.
**Acceptance Scenarios**:
1. **Given** the user is on a session's response page, **When** the page loads, **Then** a "Copy Link" button with a 'link' icon is displayed next to the session topic, styled with the secondary color.
2. **Given** the "Copy Link" button is displayed, **When** the user clicks the button, **Then** the current session's URL is copied to the clipboard, the 'link' icon smoothly transitions to a green 'check' icon, and after 3 seconds, the 'check' icon smoothly transitions back to the 'link' icon.
---
### User Story 2 - Share Session Link from Result Page (Priority: P1)
As a user on the session result page, I want to easily copy the current session's link so I can share it with others.
**Why this priority**: Similar to the response page, enabling sharing from the final result page is crucial for disseminating the outcome of a session.
**Independent Test**: Can be fully tested by navigating to a session result page, clicking the "Copy Link" button, and verifying the URL is copied to the clipboard and the animation plays correctly.
**Acceptance Scenarios**:
1. **Given** the user is on a session's result page, **When** the page loads, **Then** a "Copy Link" button with a 'link' icon is displayed next to the session topic, styled with the secondary color.
2. **Given** the "Copy Link" button is displayed, **When** the user clicks the button, **Then** the current session's URL is copied to the clipboard, the 'link' icon smoothly transitions to a green 'check' icon, and after 3 seconds, the 'check' icon smoothly transitions back to the 'link' icon.
---
### Edge Cases
- What happens if the browser does not support the Clipboard API? The system should gracefully degrade, potentially by displaying a message like "Copy failed, please copy manually" or providing a text field with the URL for manual copying.
- How does the system handle cases where the session topic is not displayed or is empty? The "Copy Link" button should still appear in a consistent, logical location (e.g., near where the topic would normally be, or at a fixed position relative to the page header).
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: The system MUST display a "Copy Link" button on the session response and result pages.
- **FR-002**: The "Copy Link" button MUST be positioned next to the session topic on both pages.
- **FR-003**: The "Copy Link" button MUST be styled with the application's secondary color.
- **FR-004**: The "Copy Link" button MUST initially display a 'link' icon.
- **FR-005**: Upon clicking the "Copy Link" button, the system MUST copy the current session's URL to the user's clipboard.
- **FR-006**: Upon successful copying, the 'link' icon MUST animate to a green 'check' icon using a dissolve effect.
- **FR-007**: After 3 seconds, the green 'check' icon MUST animate back to the 'link' icon using a dissolve effect.
### Key Entities *(include if feature involves data)*
- **Session**: Represents an active user session, identified by a unique URL. The URL is the primary data associated with the copy link feature.
## Success Criteria *(mandatory)*
### Measurable Outcomes
- **SC-001**: Users can successfully copy a session link to their clipboard from the response and result pages with a single click, 100% of the time in supported browsers.
- **SC-002**: The "Copy Link" button's visual feedback (icon change and animation) clearly indicates a successful copy operation, with the icon transition completing within 0.5 seconds and reverting within 3.5 seconds of the click.
- **SC-003**: The "Copy Link" button is consistently displayed and styled on all relevant session pages, appearing within 1 second of page load.
- **SC-004**: User feedback indicates that the copy link functionality is intuitive and easy to use, with a satisfaction rating of 4 out of 5 or higher in user surveys.
## Dependencies and Assumptions
- **Dependency**: The feature relies on the browser's native Clipboard API for copying the URL to the clipboard. If the API is not supported, a graceful degradation mechanism will be implemented as described in the Edge Cases.
- **Assumption**: A "session topic" element will be present on both the response and result pages, allowing the "Copy Link" button to be positioned adjacent to it. If not, a consistent fallback placement will be used.

78
specs/006-copy-link-feature/tasks.md Normal file
View File

@@ -0,0 +1,78 @@
# Tasks: Copy Link Feature
**Feature Branch**: `006-copy-link-feature` | **Date**: 2025-10-13 | **Plan**: [D:/Coding/unisono/specs/006-copy-link-feature/plan.md](D:/Coding/unisono/specs/006-copy-link-feature/plan.md)
## Summary
This document outlines the tasks required to implement the "Copy Link" feature, which enables users to copy session URLs from the response and result pages with visual feedback. Tasks are organized by user story to facilitate independent development and testing.
## Implementation Strategy
The feature will be delivered incrementally, focusing on completing each user story as a self-contained, testable unit. User Story 1 (Response Page) will be prioritized first, followed by User Story 2 (Result Page). Testing will be integrated throughout the development process.
## Dependencies
- **User Story 1 (US1)**: No external dependencies beyond existing project setup.
- **User Story 2 (US2)**: Depends on the completion of the `CopyLinkButton` component from US1.
## Phases
### Phase 1: Setup Tasks
No specific setup tasks are required beyond the existing project setup, as this feature integrates into the current frontend architecture.
### Phase 2: Foundational Tasks
No foundational tasks are required that block all user stories, as core dependencies (React, Material-UI) are already in place.
### Phase 3: User Story 1 - Share Session Link from Response Page (Priority: P1)
**Goal**: Implement the "Copy Link" button on the session response page, allowing users to copy the session URL and receive visual feedback.
**Independent Test**: Navigate to a session response page, click the "Copy Link" button, and verify the URL is copied to the clipboard and the animation plays correctly.
- **T001 [US1]**: Create `frontend/src/components/CopyLinkButton.tsx` component with basic structure and Material-UI button. [P]
- **T002 [US1]**: Implement `copyToClipboard` utility function in `CopyLinkButton.tsx` using `navigator.clipboard.writeText`. [P]
- **T003 [US1]**: Implement icon animation logic (link to green check, then back) within `CopyLinkButton.tsx` using React state and Material-UI icons. [P]
- **T004 [US1]**: Write unit tests for `frontend/src/components/CopyLinkButton.tsx` covering copy functionality, icon changes, and animation states. [P]
- **T005 [US1]**: Integrate `CopyLinkButton` into `frontend/src/pages/SessionPage.tsx` next to the session topic. [P]
- **T006 [US1]**: Write integration tests for `frontend/src/pages/SessionPage.tsx` to verify the `CopyLinkButton`'s presence and functionality. [P]
**Checkpoint**: User Story 1 is complete and independently testable.
### Phase 4: User Story 2 - Share Session Link from Result Page (Priority: P1)
**Goal**: Implement the "Copy Link" button on the session result page, allowing users to copy the session URL and receive visual feedback.
**Independent Test**: Navigate to a session result page, click the "Copy Link" button, and verify the URL is copied to the clipboard and the animation plays correctly.
- **T007 [US2]**: Integrate `CopyLinkButton` into `frontend/src/components/ResultsDisplay.tsx` next to the session topic. [P]
- **T008 [US2]**: Write integration tests for `frontend/src/components/ResultsDisplay.tsx` to verify the `CopyLinkButton`'s presence and functionality. [P]
**Checkpoint**: User Story 2 is complete and independently testable.
### Phase 5: Polish & Cross-Cutting Concerns
- **T009**: Implement graceful degradation for browsers that do not support the Clipboard API (e.g., display a fallback message or a text input for manual copying). [P]
- **T010**: Ensure consistent styling and positioning of the "Copy Link" button across both response and result pages, adhering to Material-UI guidelines. [P]
- **T011**: Run `npm run lint` and `tsc` in the `frontend` directory to ensure code quality and type correctness. [P]
- **T012**: Ensure consistent positioning of the "Copy Link" button when the session topic is not displayed or is empty. [P]
## Parallel Execution Examples
**Within User Story 1 (US1)**:
- T001, T002, T003, T004 can be developed in parallel as they focus on the `CopyLinkButton` component in isolation.
- T005 and T006 can be developed in parallel after T001-T004 are complete, focusing on integration into `SessionPage.tsx`.
**Within User Story 2 (US2)**:
- T007 and T008 can be developed in parallel, focusing on integration into `ResultsDisplay.tsx`.
## Summary of Tasks
- **Total Tasks**: 11
- **Tasks for US1**: 6
- **Tasks for US2**: 2
- **Tasks for Polish & Cross-Cutting Concerns**: 3
- **Parallel Opportunities**: High, especially within component development and integration for each user story.
- **Independent Test Criteria**: Each user story has clear, independently verifiable test criteria as outlined in its respective phase.
- **Suggested MVP Scope**: User Story 1 (Share Session Link from Response Page) provides core value and can be released independently.