Skip to content

Commit ceccb9c

Browse files
Copilotdnafication
Copilot
and
dnafication
authored
Enhance documentation with comprehensive feature descriptions and contribution guidelines (#14)
* Initial plan * Enhance documentation with comprehensive project information Co-authored-by: dnafication <6381587+dnafication@users.noreply.github.com> * Address code review feedback - remove icon that may not render consistently Co-authored-by: dnafication <6381587+dnafication@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: dnafication <6381587+dnafication@users.noreply.github.com>
1 parent 193d0a8 commit ceccb9c

2 files changed

Lines changed: 251 additions & 30 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 153 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,196 @@
11
# Contributing to Talk Timer
22

3-
Thank you for considering contributing to Talk Timer! Your help is greatly appreciated.
3+
Thank you for considering contributing to Talk Timer! Your help is greatly appreciated. This guide will help you get started with contributing to the project.
4+
5+
## Table of Contents
6+
7+
- [Getting Started](#getting-started)
8+
- [Development Workflow](#development-workflow)
9+
- [Code Style](#code-style)
10+
- [Technology Stack](#technology-stack)
11+
- [Project Structure](#project-structure)
12+
- [Testing Your Changes](#testing-your-changes)
13+
- [Submitting Your Contribution](#submitting-your-contribution)
414

515
## Getting Started
616

717
To get started with development, follow these steps:
818

919
1. **Fork the repository**: Click the "Fork" button at the top right of the repository page.
20+
1021
2. **Clone your fork**: Clone your forked repository to your local machine.
1122
```bash
1223
git clone https://github.com/your-username/talk-timer.git
24+
cd talk-timer
1325
```
14-
3. **Install dependencies**: Navigate to the project directory and install the dependencies. We use `npm` in this example, but you can use `yarn`, `pnpm`, or `bun` as well.
26+
27+
3. **Install dependencies**: Install the project dependencies. We use `npm` in this example, but you can use `yarn`, `pnpm`, or `bun` as well.
1528
```bash
16-
cd talk-timer
1729
npm install
1830
```
31+
1932
4. **Run the development server**: Start the development server to see your changes live.
2033
```bash
2134
npm run dev
2235
```
36+
37+
Open [http://localhost:3000](http://localhost:3000) in your browser to view the application.
2338

2439
## Development Workflow
2540

2641
1. **Create a branch**: Create a new branch for your feature or bugfix.
2742
```bash
2843
git checkout -b feature/your-feature-name
44+
# or
45+
git checkout -b fix/your-bugfix-name
2946
```
30-
2. **Make changes**: Make your changes to the codebase.
31-
3. **Test your changes**: Ensure that your changes work as expected and do not break existing functionality.
32-
4. **Commit your changes**: Commit your changes with a clear and descriptive commit message.
47+
48+
2. **Make changes**: Make your changes to the codebase. Follow the [Code Style](#code-style) guidelines.
49+
50+
3. **Test your changes**: Ensure that your changes work as expected and do not break existing functionality. See [Testing Your Changes](#testing-your-changes) for details.
51+
52+
4. **Format your code**: Run the formatter to ensure consistent code style.
53+
```bash
54+
npm run format
55+
```
56+
57+
5. **Commit your changes**: Commit your changes with a clear and descriptive commit message.
3358
```bash
59+
git add .
3460
git commit -m "Add feature: description of your feature"
61+
# or
62+
git commit -m "Fix: description of the bug fix"
3563
```
36-
5. **Push your changes**: Push your changes to your forked repository.
64+
65+
6. **Push your changes**: Push your changes to your forked repository.
3766
```bash
3867
git push origin feature/your-feature-name
3968
```
40-
6. **Create a pull request**: Create a pull request from your forked repository to the main repository.
41-
7. **Review and merge**: Wait for your pull request to be reviewed and merged. Make any necessary changes if requested.
69+
70+
7. **Create a pull request**: Create a pull request from your forked repository to the main repository. Provide a clear description of your changes and any relevant context.
71+
72+
8. **Review and merge**: Wait for your pull request to be reviewed and merged. Make any necessary changes if requested by maintainers.
4273

4374
## Code Style
4475

45-
Please follow the existing code style and use the provided linters. Run the following command to check for linting errors:
76+
This project follows specific code style guidelines to maintain consistency:
77+
78+
### TypeScript
79+
80+
- **Strict mode enabled**: The project uses TypeScript with strict compiler options
81+
- Use type inference where possible
82+
- Use `interface` for component props
83+
- Use descriptive variable and function names
84+
85+
### React Patterns
86+
87+
- Use **functional components** with hooks
88+
- Mark client components with `'use client'` directive at the top of the file
89+
- Use `useCallback` for memoized callbacks
90+
- Use `useEffect` for side effects (timers, event listeners)
91+
92+
### Formatting
93+
94+
- **Indentation**: 2 spaces (no tabs)
95+
- **Quotes**: Single quotes for strings
96+
- **Semicolons**: No semicolons
97+
- **Line width**: Keep lines reasonably short
98+
99+
### Styling
100+
101+
- Use **Tailwind CSS** utility classes
102+
- Use the `cn()` utility from `lib/utils.ts` for conditional className merging
103+
- Follow the existing color scheme (green → yellow → red gradients)
104+
105+
### Linting and Formatting
106+
107+
Please follow the existing code style and use the provided linters. Run the following commands before committing:
46108

47109
```bash
110+
# Check for linting and formatting errors
48111
npm run lint
112+
113+
# Auto-format code
114+
npm run format
49115
```
50116

51-
## Check for Build and Start
117+
## Technology Stack
52118

53-
Please check if the project builds and starts correctly before creating a pull request. Run the following command to build and start the project:
119+
- **Framework**: Next.js 14 (App Router)
120+
- **Language**: TypeScript (strict mode enabled)
121+
- **UI Library**: React 18
122+
- **Styling**: Tailwind CSS with shadcn/ui components
123+
- **Icons**: Radix UI Icons and Lucide React
124+
- **Build Tool**: Next.js built-in bundler
54125

55-
```bash
56-
npm run build
57-
npm start
126+
## Project Structure
127+
128+
```
129+
/
130+
├── app/ # Next.js App Router pages
131+
│ ├── layout.tsx # Root layout
132+
│ └── page.tsx # Home page
133+
├── components/ # React components
134+
│ ├── ui/ # shadcn/ui components (button, input, dialog, label)
135+
│ ├── talk-timer.tsx # Main timer component
136+
│ ├── timer-display.tsx # Timer display component
137+
│ ├── footer.tsx # Footer with controls
138+
│ └── progress-bar.tsx # Progress bar component
139+
├── lib/ # Utility functions
140+
│ └── utils.ts # cn() utility for className merging
141+
└── .github/ # GitHub configuration
58142
```
143+
144+
### Key Components
145+
146+
- **TalkTimer** (`components/talk-timer.tsx`): Main component that manages timer state and logic
147+
- **TimerDisplay** (`components/timer-display.tsx`): Displays the timer and talk title
148+
- **Footer** (`components/footer.tsx`): Contains control buttons and settings dialog
149+
- **ProgressBar** (`components/progress-bar.tsx`): Shows progress at the top of the screen
150+
151+
## Testing Your Changes
152+
153+
Before creating a pull request, please ensure:
154+
155+
1. **The project builds successfully**:
156+
```bash
157+
npm run build
158+
```
159+
160+
2. **There are no linting errors**:
161+
```bash
162+
npm run lint
163+
```
164+
165+
3. **The application runs correctly**:
166+
```bash
167+
npm run dev
168+
```
169+
Then manually test the following:
170+
- Starting/stopping/resetting the timer
171+
- Fullscreen toggle (both button and keyboard shortcut)
172+
- Settings dialog (title and thresholds)
173+
- Color transitions at the configured thresholds
174+
- Progress bar functionality
175+
- Auto-hiding footer controls
176+
177+
4. **Your changes don't break existing functionality**: Test the entire application to ensure your changes don't negatively impact other features.
178+
179+
## Submitting Your Contribution
180+
181+
When submitting a pull request:
182+
183+
1. **Provide a clear title**: Use a descriptive title that summarizes your changes
184+
2. **Write a detailed description**: Explain what changes you made and why
185+
3. **Reference related issues**: If your PR addresses an issue, reference it (e.g., "Fixes #123")
186+
4. **Include screenshots**: If your changes affect the UI, include before/after screenshots
187+
5. **Be responsive**: Be prepared to respond to feedback and make requested changes
188+
189+
## Questions?
190+
191+
If you have any questions or need help, feel free to:
192+
- Open an issue for discussion
193+
- Comment on an existing issue
194+
- Reach out to the maintainers
195+
196+
Thank you for contributing to Talk Timer! 🎉

‎README.md‎

Lines changed: 98 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,110 @@
1-
# Talk Timer
1+
# Talk Timer ⚡
22

3-
A simple timer for talks, with configurable time for warning and end of talk.
3+
A simple, fullscreen-capable timer application designed for tracking talk durations with visual feedback. Perfect for lightning talks, presentations, and Toastmasters meetings!
4+
5+
Inspired by [Toastmasters Timer Zoom Backgrounds](https://www.toastmasters.org/resources/timer-zoom-backgrounds), this app provides clear visual cues to help speakers stay on time.
46

57
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). It uses [shadcn/ui](https://ui.shadcn.com/) for the UI components.
68

79
## Features
810

11+
- **Visual Color Transitions**: Timer changes colors based on configurable time thresholds
12+
- 🟢 Green: Initial state (before warning threshold)
13+
- 🟡 Yellow: Warning state (approaching time limit)
14+
- 🔴 Red: Overtime state (exceeded time limit)
15+
16+
- **Progress Bar**: White progress bar at the top of the screen shows elapsed time relative to the red threshold
17+
918
- **Fullscreen Mode**: Toggle fullscreen mode for a distraction-free timer experience
1019
- Click the fullscreen button (maximize/minimize icon) in the footer controls
1120
- Use the keyboard shortcut **F** to quickly toggle fullscreen mode
1221
- Works across different browsers and devices
1322

23+
- **Configurable Settings**: Customize your timer experience
24+
- Set a custom talk title
25+
- Configure yellow threshold (warning time in seconds)
26+
- Configure red threshold (overtime time in seconds)
27+
28+
- **Auto-hiding Controls**: Footer controls automatically hide after 3 seconds of inactivity, reappearing on mouse movement
29+
30+
- **Document Title Updates**: Browser tab title shows elapsed time when the timer is running
31+
32+
## Usage
33+
34+
1. **Starting the Timer**: Click the Play button (▶️) in the footer controls
35+
2. **Pausing the Timer**: Click the Pause button (⏸) while the timer is running
36+
3. **Resetting the Timer**: Click the Reset button (↻) to set the timer back to 00:00
37+
4. **Configuring Settings**: Click the Settings button (⚙️) to:
38+
- Change the talk title
39+
- Set the yellow threshold (warning time in seconds, default: 90 seconds)
40+
- Set the red threshold (overtime time in seconds, default: 120 seconds)
41+
5. **Fullscreen Mode**:
42+
- Click the Fullscreen button or press **F** key
43+
- Press **Esc** or **F** key again to exit fullscreen
44+
45+
### Keyboard Shortcuts
46+
47+
- **F**: Toggle fullscreen mode (disabled when typing in input fields)
48+
1449
## Getting Started
1550

16-
First, run the development server:
51+
### Prerequisites
1752

18-
```bash
19-
npm run dev
20-
# or
21-
yarn dev
22-
# or
23-
pnpm dev
24-
# or
25-
bun dev
26-
```
53+
- Node.js 18.x or later
54+
- npm, yarn, pnpm, or bun
55+
56+
### Installation
57+
58+
1. Clone the repository:
59+
```bash
60+
git clone https://github.com/dnafication/talk-timer.git
61+
cd talk-timer
62+
```
63+
64+
2. Install dependencies:
65+
```bash
66+
npm install
67+
```
2768

28-
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
69+
3. Run the development server:
70+
```bash
71+
npm run dev
72+
```
2973

30-
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
74+
4. Open [http://localhost:3000](http://localhost:3000) with your browser to see the timer.
3175

32-
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
76+
The page auto-updates as you edit files. This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
77+
78+
## Technology Stack
79+
80+
- **Framework**: Next.js 14 (App Router)
81+
- **Language**: TypeScript (strict mode)
82+
- **UI Library**: React 18
83+
- **Styling**: Tailwind CSS
84+
- **UI Components**: [shadcn/ui](https://ui.shadcn.com/)
85+
- **Icons**: Radix UI Icons and Lucide React
86+
87+
## Project Structure
88+
89+
```
90+
/
91+
├── app/ # Next.js App Router pages
92+
│ ├── layout.tsx # Root layout
93+
│ └── page.tsx # Home page
94+
├── components/ # React components
95+
│ ├── ui/ # shadcn/ui components
96+
│ ├── talk-timer.tsx # Main timer component
97+
│ ├── timer-display.tsx # Timer display component
98+
│ ├── footer.tsx # Footer with controls
99+
│ └── progress-bar.tsx # Progress bar component
100+
├── lib/ # Utility functions
101+
│ └── utils.ts # cn() utility for className merging
102+
└── .github/ # GitHub configuration
103+
```
104+
105+
## Contributing
106+
107+
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.
33108

34109
## Learn More
35110

@@ -40,8 +115,16 @@ To learn more about Next.js, take a look at the following resources:
40115

41116
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
42117

118+
### Related Resources
119+
120+
- [Toastmasters Timer Zoom Backgrounds](https://www.toastmasters.org/resources/timer-zoom-backgrounds) - The inspiration for this application
121+
43122
## Deploy on Vercel
44123

45124
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
46125

47126
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
127+
128+
## License
129+
130+
This project is open source and available under the [MIT License](LICENSE).

0 commit comments

Comments
 (0)