Introducing Dynamic Theme Switcher

CODE_OF_CONDUCT.md

@@ -2,45 +2,51 @@
 
 ## Our Pledge
 
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+In the interest of fostering an open and welcoming community, we as contributors and maintainers pledge to make participation in this project and our community a harassment-free experience for everyone. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment include:
+Examples of behavior that contributes to a positive environment:
 
 - Using welcoming and inclusive language
 - Being respectful of differing viewpoints and experiences
 - Gracefully accepting constructive criticism
 - Focusing on what is best for the community
-- Showing empathy towards other community members
+- Showing empathy toward other community members
 
 Examples of unacceptable behavior by participants include:
 
-- The use of sexualized language or imagery and unwelcome sexual attention or advances
-- Trolling, insulting/derogatory comments, and personal or political attacks
-- Public or private harassment
-- Publishing others' private information, such as a physical or electronic address, without explicit permission
-- Other conduct which could reasonably be considered inappropriate in a professional setting
+- Violence, threats of violence, or violent language
+- Discriminatory jokes and language, or derogatory comments
+- Posting sexually explicit content or sexual attention
+- Deliberate intimidation, stalking, or harassment
+- Publishing private information without permission
+- Other conduct which could reasonably be considered abusive or inappropriate in a professional setting
 
 ## Our Responsibilities
 
-Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any behavior that violates this Code of Conduct.
 
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+Maintainers have the right and responsibility to remove, edit, or reject contributions, and to ban or otherwise restrict participants who behave inappropriately.
 
-## Scope
+## Reporting and Enforcement
 
-This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+If you are subject to or witness unacceptable behavior, please report it. Reports will be handled with discretion and investigated promptly and fairly.
 
-## Enforcement
+Report incidents to: [@teociaps](mailto:teociaps.github@gmail.com) or open an issue marked as confidential on the project repository if available.
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project owner [@teociaps](mailto:ciapparellimatteo@gmail.com). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
+When reporting, include as much detail as possible: what happened, when, where, and any supporting evidence (e.g., screenshots, links).
 
-Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+## Scope
 
-## Attribution
+This Code of Conduct applies within project spaces and in public spaces when an individual is representing the project (e.g., using an official project e-mail address, posting via an official social media account, or acting as an appointed representative).
 
-This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+## Enforcement Process
 
-For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq
+Reports will be reviewed and investigated by the project maintainers. The maintainers will determine actions they deem appropriate, which may include asking the participant to apologize, removing content, temporary suspension, or permanent banning from project spaces.
+
+The maintainers will strive to keep the reporter's identity confidential when requested.
+
+## Attribution
 
+This Code of Conduct is adapted from the Contributor Covenant v3.0 (https://www.contributor-covenant.org/version/3/0/code_of_conduct/). By participating in this project, you agree to abide by this code.

CONTRIBUTING.md

@@ -8,138 +8,235 @@ This project and everyone participating in it are governed by our [Code of Condu
 
 ## How to Contribute
 
-1. **Fork the repository to your GitHub account.**
-2. Clone the forked repository to your local machine.
+1. **Fork the repository** to your GitHub account.
+2. **Clone** the forked repository to your local machine.
 3. Create a **new branch** for your contribution:
 
 	```bash
 	git checkout -b feature/my-feature
 	```
 
-4. Make your changes and commit them:
+4. Make your changes and **commit** them:
 
 	```bash
 	git commit -m "Add new feature"
 	```
 
-5. Push the changes to your fork:
+5. **Push** the changes to your fork:
 
 	```bash
 	git push origin feature/my-feature
 	```
 
 6. Open a **pull request (PR)** against the **main** branch of the original repository.
 
-## Working with Styles and Scripts
+## Project Structure
 
-When contributing changes to CSS or JavaScript files for themes, please follow these guidelines to ensure both original and minified versions are properly maintained.
+Understanding the project layout helps you navigate the codebase:
+
+- **`src/AspNetCore.Swagger.Themes.Common/`** - Core theme system shared between packages
+- **`src/AspNetCore.SwaggerUI.Themes/`** - Swashbuckle.AspNetCore integration
+- **`src/NSwag.AspNetCore.Themes/`** - NSwag.AspNetCore integration
+- **`samples/`** - Example applications demonstrating usage
+- **`tests/`** - Unit and integration tests
+
+## Working with Themes
+
+### Adding or Modifying Themes
+
+Themes are defined as CSS files with optional JavaScript for advanced features. When working with themes:
+
+1. **Original files** - Make your changes in the non-minified `.css` or `.js` files
+2. **Minified versions** - Must be manually updated (see Minification Process below)
+3. **Headers** - Minified files require specific comment headers for testing
 
 ### Minification Process
 
-The project includes both original and minified versions of assets. The minified versions are used at runtime for optimal performance, while original files serve as fallbacks.
+The project uses minified versions at runtime for performance. After editing CSS or JavaScript:
 
-#### CSS Files
+#### For CSS Files
 
 1. Navigate to [CSS Minifier](https://www.toptal.com/developers/cssminifier)
-2. For each modified CSS file (e.g., `common.css`, `dark.css`, etc.):
-   - Open the original CSS file and copy its entire content
-   - Paste the content into the online minifier
-   - Click **"Minify"** to generate the compressed version
-   - Copy the minified output
-   - **Add the compact header** at the beginning of the minified content (see format below)
-   - Paste the result into the corresponding `.min.css` file (e.g., `common.min.css`)
-   - **Important**: Verify that placeholders are preserved:
-     - For `common.css` and `modern.common.css`, ensure `#STICKY_OPERATIONS` is still present in the minified output
-
-#### JavaScript Files
+2. Copy the **entire content** of your modified CSS file
+3. Paste into the minifier and click **"Minify"**
+4. Copy the minified output
+5. Add the **compact header** at the very beginning (format below)
+6. Paste into the corresponding `.min.css` file
+7. **Verify placeholders** are preserved (e.g., `#STICKY_OPERATIONS` in `common.css`)
+
+#### For JavaScript Files
 
 1. Navigate to [JavaScript Minifier](https://www.toptal.com/developers/javascript-minifier)
-2. For each modified JavaScript file (e.g., `modern.js`):
-   - Open the original JavaScript file and copy its entire content
-   - Paste the content into the online minifier
-   - Click **"Minify"** to generate the compressed version
-   - Copy the minified output
-   - **Add the compact header** at the beginning of the minified content (see format below)
-   - Paste the result into the corresponding `.min.js` file (e.g., `modern.min.js`)
-   - **Important**: Verify that all placeholders are preserved in the minified output:
-     - `{$PINNABLE_TOPBAR}`
-     - `{$BACK_TO_TOP}`
-     - `{$EXPAND_COLLAPSE_ALL_OPERATIONS}`
-
-#### Minified File Header Format
-
-All minified files must start with a compact comment header for test compatibility. The format is:
+2. Copy the **entire content** of your modified JavaScript file
+3. Paste into the minifier and click **"Minify"**
+4. Copy the minified output
+5. Add the **compact header** at the very beginning (format below)
+6. Paste into the corresponding `.min.js` file
+7. **Verify all placeholders** are preserved:
+   - `{$PINNABLE_TOPBAR}`
+   - `{$BACK_TO_TOP}`
+   - `{$EXPAND_COLLAPSE_ALL_OPERATIONS}`
+   - `{$THEME_SWITCHER}`
+
+#### Minified Header Format
+
+All minified files must start with this compact comment:
 
 ```
-/*StyleName*/[minified content here...]
+/*Name*/[minified content]
 ```
 
-**Examples**:
-- `dark.min.css` → `/*Dark*/body{color:...`
-- `modern.dark.min.css` → `/*Modern Dark*/body{color:...`
-- `common.min.css` → `/*Common Style*/body{color:...`
-- `modern.min.js` → `/*Modern UI*/const rootElement=...`
+**Examples:**
+- `dark.min.css` → `/*Dark Theme*/body{...`
+- `common.min.css` → `/*Common*/body{...`
+- `ui.min.js` → `/*Swagger UI*/const ...`
+
+> **Why?** Tests verify headers are present and correctly formatted. This ensures minification was done properly.
 
-#### Committing Changes
+#### Placeholder Preservation
 
-When committing style or script changes, always include both the original and minified versions:
+Placeholders like `{$THEME_SWITCHER}` are replaced at runtime based on user settings. Minification **must preserve** these exact strings, or features will break.
+
+### Committing Theme Changes
+
+Always commit both original **and** minified versions:
 
 ```bash
 git add src/AspNetCore.Swagger.Themes.Common/AspNetCore/Swagger/Themes/Styles/*.css
 git add src/AspNetCore.Swagger.Themes.Common/AspNetCore/Swagger/Themes/Scripts/*.js
-git commit -m "Update theme styles: [description of changes]"
+git commit -m "Add new ocean theme"
+```
+
+## Testing Your Changes
+
+Before submitting a pull request:
+
+### 1. Build the Solution
+
+```bash
+dotnet build -c Release
+```
+
+Ensure there are no compilation errors.
+
+### 2. Run Tests
+
+```bash
+dotnet test
 ```
 
-### Why Placeholders Matter
+All tests must pass, including:
+- Minified header format tests
+- Theme discovery tests
+- Integration tests
 
-The placeholders (`#STICKY_OPERATIONS`, `{$PINNABLE_TOPBAR}`, etc.) are dynamically replaced at runtime based on user configuration. It is critical that minification preserves these exact strings to maintain functionality.
+### 3. Test with Sample Applications
 
-### Testing Your Changes
+Run both sample projects to verify functionality:
 
-Before submitting your pull request:
+```bash
+# Swashbuckle sample
+dotnet run --project samples/Sample.AspNetCore.SwaggerUI.Swashbuckle
 
-1. Build the project:
-   ```bash
-   dotnet build -c Release
-   ```
+# NSwag sample
+dotnet run --project samples/Sample.AspNetCore.SwaggerUI.NSwag
+```
 
-2. Run the tests to ensure minified headers are correct:
-   ```bash
-   dotnet test
-   ```
+### 4. Manual Verification
 
-3. Test with the sample applications:
-   ```bash
-   dotnet run --project samples/Sample.AspNetCore.SwaggerUI.Swashbuckle
-   ```
+Open the sample app in your browser and verify:
 
-4. Verify that:
-   - Themes render correctly
-   - Advanced features work as expected (pinnable topbar, back-to-top button, etc.)
-   - No console errors appear in the browser's developer tools
-   - Tests pass
+- ✅ Themes render correctly
+- ✅ Theme switcher dropdown appears and works (if enabled)
+- ✅ Custom themes are discovered automatically
+- ✅ Advanced features work (pinnable topbar, back-to-top, etc.)
+- ✅ No console errors in browser developer tools
+- ✅ Standalone themes load without extra dependencies
 
 ## Pull Request Guidelines
-- Ensure your code adheres to the existing coding standards.
-- Include relevant documentation and test cases for your changes.
-- For style/script changes, include both original and minified versions with proper headers.
-- Keep your pull request focused. If you are addressing multiple issues, submit separate pull requests for each.
-- Be responsive to comments and feedback on your pull request.
 
-## Reporting Bugs and Issues
-If you find a bug or have a question, please open an issue on GitHub. When reporting a bug, provide as much detail as possible, including:
+- **Follow existing code style** - Match the patterns you see in the codebase
+- **Include tests** - Add or update tests for your changes
+- **Update documentation** - If adding features, update relevant docs
+- **Keep PRs focused** - One feature or fix per PR (submit separate PRs for multiple changes)
+- **Provide context** - Explain *why* the change is needed, not just *what* changed
+- **Be responsive** - Address feedback and questions promptly
 
-- A clear and concise description of the bug.
-- Steps to reproduce the issue.
-- Expected behavior and actual behavior.
-- Screenshots or code snippets, if applicable.
+### Good PR Practices
 
-## Feature Requests
-We welcome suggestions for new features or improvements. Please open an issue to propose your ideas.
+- Use descriptive titles: `feat: add sunset theme` not `update css`
+- Reference issues: `Fixes #123` or `Closes #456`
+- Include screenshots for visual changes
+- Test across .NET 8, 9, and 10 if possible
+
+## Reporting Bugs
+
+Found a bug? Please open an issue with:
+
+- **Clear description** of the problem
+- **Steps to reproduce** the issue
+- **Expected vs. actual behavior**
+- **Environment details:**
+  - Which package (Swashbuckle or NSwag)
+  - .NET version
+  - Browser (if UI-related)
+- **Screenshots or code snippets** if applicable
+
+## Suggesting Features
+
+We welcome feature suggestions! When proposing a feature:
+
+- **Describe the use case** - What problem does it solve?
+- **Explain the benefit** - How does it improve the project?
+- **Consider backward compatibility** - Will it break existing code?
+- **Offer to help** - Can you contribute the implementation?
+
+## Development Tips
+
+### Quick Testing Loop
+
+For rapid iteration during development:
+
+1. Make your changes
+2. Build: `dotnet build`
+3. Run sample: `dotnet run --project samples/Sample.AspNetCore.SwaggerUI.Swashbuckle`
+4. Refresh browser (F5) (clear the browser cache if necessary) to see changes
+
+### Organizing Custom Themes
+
+When adding example custom themes, use subfolders for clarity:
+
+```
+samples/YourSample/SwaggerThemes/
+├── CompanyThemes/
+│   └── corporate-blue.css
+└── SeasonalThemes/
+    └── holiday-red.css
+```
+
+This demonstrates best practices for users organizing their own themes.
+
+### Standalone vs. Regular Themes
+
+- **Regular themes** - Depend on `common.css` and may use JavaScript features
+- **Standalone themes** - Prefix with `standalone.` (e.g., `standalone.custom.css`) for zero dependencies
+
+Choose based on whether you need shared styles or prefer total independence.
+
+## Questions?
+
+Not sure about something? Feel free to:
+
+- Open an issue for clarification
+- Ask in your pull request
+- Reference existing code patterns
 
 ## License
-By contributing to this project, you agree that your contributions will be licensed under the [License](LICENSE) file.
 
-Thank you for your contributions!
+By contributing, you agree that your contributions will be licensed under the same [MIT License](LICENSE) that covers the project.
+
+---
+
+Thank you for making SwaggerUI.Themes better! 🎨
 
-**_@teociaps_**
+**[@teociaps](https://github.com/teociaps)**