diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 517024f..b9f9fce 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,36 +1,40 @@ -# Unisono Constitution + +# Agree on Desires Constitution ## Core Principles -### I. Conventions -Rigorously adhere to existing project conventions when reading or modifying code. Analyze surrounding code, tests, and configuration first. +### I. Defined Technology Stack +All development MUST adhere to the approved technology stack. This ensures consistency, maintainability, and streamlined operations. +- **Backend**: Node.js +- **Frontend**: React +- **UI Framework**: Material Design 3 (Material-UI / MUI) +- **Containerization**: Docker -### II. Libraries/Frameworks -NEVER assume a library/framework is available or appropriate. Verify its established usage within the project (check imports, configuration files like 'package.json', 'Cargo.toml', 'requirements.txt', 'build.gradle', etc., or observe neighboring files) before employing it. +### II. UI/UX Consistency +All user interfaces MUST adhere to Material Design 3 principles and components. This creates a cohesive, predictable, and high-quality user experience. Rationale: Avoids fragmented design and reduces redundant styling efforts. -### III. Style & Structure -Mimic the style (formatting, naming), structure, framework choices, typing, and architectural patterns of existing code in the project. +### III. Container-First Development +All application services and development environments MUST run within Docker containers. This ensures environment parity from local development to production, simplifies setup, and improves deployment reliability. -### IV. Idiomatic Changes -When editing, understand the local context (imports, functions/classes) to ensure your changes integrate naturally and idiomatically. +### IV. Test-Driven Development (TDD) +New features and bug fixes MUST follow a Test-Driven Development approach. Tests should be written first to define the requirements, fail before implementation, and pass upon completion. This ensures code quality, reduces regressions, and clarifies requirements. -### V. Comments -Add code comments sparingly. Focus on *why* something is done, especially for complex logic, rather than *what* is done. Only add high-value comments if necessary for clarity or if requested by the user. Do not edit comments that are separate from the code you are changing. *NEVER* talk to the user or describe your changes through comments. - -## Quality Gates - -### I. Proactiveness -Fulfill the user's request thoroughly. When adding features or fixing bugs, this includes adding tests to ensure quality. Consider all created files, especially tests, to be permanent artifacts unless the user says otherwise. - -### II. Verification (Tests) -If applicable and feasible, verify the changes using the project's testing procedures. Identify the correct test commands and frameworks by examining 'README' files, build/package configuration (e.g., 'package.json'), or existing test execution patterns. NEVER assume standard test commands. - -### III. Verification (Standards) -VERY IMPORTANT: After making code changes, execute the project-specific build, linting and type-checking commands (e.g., 'tsc', 'npm run lint', 'ruff check .') that you have identified for this project (or obtained from the user). This ensures code quality and adherence to standards. If unsure about these commands, you can ask the user if they'd like you to run them and if so how to. +### V. API-First Design +The backend and frontend are decoupled and communicate via a well-defined API contract. The API contract SHOULD be defined and reviewed before implementation begins. This allows for parallel development and clear integration points. ## Governance -All PRs/reviews must verify compliance with these principles. Complexity must be justified. +All development activities, code reviews, and architectural decisions must align with this constitution. Proposed deviations require a formal amendment to this document. -**Version**: 1.0 | **Ratified**: 2025-10-13 | **Last Amended**: 2025-10-13 - \ No newline at end of file +**Version**: 1.0.0 | **Ratified**: 2025-10-09 | **Last Amended**: 2025-10-09 \ No newline at end of file diff --git a/GEMINI.md b/GEMINI.md index 43b4573..8565a89 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -11,6 +11,8 @@ Auto-generated from all feature plans. Last updated: 2025-10-13 - Ephemeral server-side storage (in-memory/session store) for encrypted session data, purged on session termination. - Node.js (LTS), TypeScript 5.x + React, Material-UI / MUI, WebSocket library, Express.js (005-simple-http-auth) - Ephemeral server-side storage (in-memory/session store) for encrypted session data, `.env` file for passphrase. (005-simple-http-auth) +- Node.js (LTS), TypeScript 5.x, React + Material-UI / MUI, React Router, Browser's native Clipboard API (006-copy-link-feature) +- N/A (frontend feature, no direct storage interaction) (006-copy-link-feature) ## Project Structure ``` @@ -41,9 +43,9 @@ npm run lint Node.js (LTS), TypeScript 5.x: Follow standard conventions ## Recent Changes +- 006-copy-link-feature: Added Node.js (LTS), TypeScript 5.x, React + Material-UI / MUI, React Router, Browser's native Clipboard API - 005-simple-http-auth: Added Node.js (LTS), TypeScript 5.x + React, Material-UI / MUI, WebSocket library, Express.js - 004-afraid-to-ask: Implemented ephemeral server-side storage for encrypted session data, WebSocket communication, and Google Cloud Natural Language API. -- 003-redesign-you-find: Added Material-UI / MUI diff --git a/specs/006-copy-link-feature/checklists/requirements.md b/specs/006-copy-link-feature/checklists/requirements.md new file mode 100644 index 0000000..410df82 --- /dev/null +++ b/specs/006-copy-link-feature/checklists/requirements.md @@ -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` \ No newline at end of file diff --git a/specs/006-copy-link-feature/contracts/openapi.yaml b/specs/006-copy-link-feature/contracts/openapi.yaml new file mode 100644 index 0000000..a813f07 --- /dev/null +++ b/specs/006-copy-link-feature/contracts/openapi.yaml @@ -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. diff --git a/specs/006-copy-link-feature/data-model.md b/specs/006-copy-link-feature/data-model.md new file mode 100644 index 0000000..0a29cd6 --- /dev/null +++ b/specs/006-copy-link-feature/data-model.md @@ -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. diff --git a/specs/006-copy-link-feature/plan.md b/specs/006-copy-link-feature/plan.md new file mode 100644 index 0000000..9123c20 --- /dev/null +++ b/specs/006-copy-link-feature/plan.md @@ -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 + + + +## 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`. + diff --git a/specs/006-copy-link-feature/quickstart.md b/specs/006-copy-link-feature/quickstart.md new file mode 100644 index 0000000..3669b88 --- /dev/null +++ b/specs/006-copy-link-feature/quickstart.md @@ -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. diff --git a/specs/006-copy-link-feature/research.md b/specs/006-copy-link-feature/research.md new file mode 100644 index 0000000..cd38e71 --- /dev/null +++ b/specs/006-copy-link-feature/research.md @@ -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. diff --git a/specs/006-copy-link-feature/spec.md b/specs/006-copy-link-feature/spec.md new file mode 100644 index 0000000..808b630 --- /dev/null +++ b/specs/006-copy-link-feature/spec.md @@ -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. diff --git a/specs/006-copy-link-feature/tasks.md b/specs/006-copy-link-feature/tasks.md new file mode 100644 index 0000000..13023f4 --- /dev/null +++ b/specs/006-copy-link-feature/tasks.md @@ -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.