neon_sakura 0.1.4

data/CLAUDE.md

@@ -0,0 +1,632 @@
+# CLAUDE.md
+
+## Overview
+
+This document describes the neon_sakura gem and its architecture for use with Claude. The gem extracts styling and theming components from a Rails application to create a reusable set of UI elements that can be shared across multiple Rails projects.
+
+## Git Workflow
+
+**IMPORTANT: Always ask for permission before committing or pushing any changes.**
+- Stage changes and show `git status`
+- Describe what will be committed
+- Wait for explicit user approval before running `git commit`
+- Wait for explicit user approval before running `git push`
+
+## Purpose
+
+The neon_sakura gem is a Rails engine designed to provide:
+- Shared styling components with a dark-themed UI
+- Tailwind-inspired utility classes
+- Reusable UI components like navigation, cards, badges, buttons, tables, alerts
+- Form styling and pagination components
+- Layout templates for application and error pages
+- SVG icon components for common UI elements
+
+## Documentation Updates
+
+When making changes to the gem, ensure that:
+1. CHANGELOG.md is updated with a description of the changes
+2. README.md is updated to reflect any changes in functionality or usage
+3. Any new features or modifications to existing behavior are documented
+
+## Usage
+
+Add to your Gemfile:
+```ruby
+gem 'neon_sakura'
+```
+
+Then run:
+```bash
+bundle install
+```
+
+Include assets in your application layout:
+```erb
+<%# Load neon_sakura stylesheets (Propshaft-compatible) %>
+<%= neon_sakura_stylesheets %>
+
+<%# Load your app-specific styles %>
+<%= stylesheet_link_tag 'application', 'data-turbo-track': 'reload' %>
+
+<%# JavaScript %>
+<%= javascript_include_tag 'application', 'data-turbo-track': 'reload' %>
+```
+
+The `neon_sakura_stylesheets` helper loads all CSS files in the correct order for proper cascade. This is necessary because Propshaft (Rails 8) does not process `@import` statements in CSS files.
+
+Use the provided layouts and components in your views.
+
+## Style Guide (Development Only)
+
+The gem includes a comprehensive style guide at `/style-guide` that showcases all UI components with live previews and code examples. The style guide is automatically enabled in development/test environments and completely hidden in production.
+
+### Configuration
+
+```ruby
+# config/initializers/neon_sakura.rb
+NeonSakura.configure do |config|
+  # Enable/disable the entire style guide (default: true)
+  config.enable_style_guide = true
+
+  # Control navbar link position: :start, :end, :before_logout, or integer (default: :end)
+  config.style_guide_navbar_position = :end
+
+  # Enable/disable Pagy pagination examples (default: true)
+  # When true: Auto-detects Pagy and shows working examples
+  # When false: Hides pagination section entirely
+  config.style_guide_pagy_examples = true
+end
+```
+
+### Pagy Integration
+
+The style guide includes pagination examples using Pagy:
+- **Default behavior** (`style_guide_pagy_examples = true`): Auto-detects Pagy gem and shows working examples
+- **If Pagy not installed**: Shows helpful error message with installation instructions
+- **If disabled** (`style_guide_pagy_examples = false`): Hides pagination section entirely
+- **Error handling**: Gracefully catches Pagy initialization errors and displays configuration help
+
+Pagy is NOT a required dependency - the style guide works without it.
+
+## Architecture
+
+The gem follows the typical Rails engine pattern with:
+- Asset pipeline integration for CSS and JS
+- Layout templates for consistent page structure
+- Component partials for reusable UI elements
+- SVG icon system for consistent iconography
+
+## Stack
+
+- Rails 8 (primary)
+- SQLite (3 databases: main, queue, cache)
+- SolidQueue, Puma, Propshaft
+- Turbo/Stimulus, Pagy, Oj, Node 24
+
+## Dev Rules
+
+- All code must follow Rails 8 conventions
+- Use Oj (`Oj.load/dump`) instead of JSON (2-10x faster)
+- Follow Rails Omakase style compliance
+- 2 spaces indentation for Ruby/JS/CSS/HTML
+- 4 spaces indentation for Python
+- Line length: 120 chars (Ruby), 88 (Python)
+- No tabs, no trailing whitespace
+
+## UI & Styling
+
+- **Never use** inline styles (`style="..."` attributes)
+- **Never use** embedded `<style>` tags
+- All styles must be in CSS files: `app/assets/stylesheets/`
+- Use existing utility classes from `base.css`
+- Dark theme color palette (bg-gray-900, bg-gray-800, text-white, text-cyan-300, etc.)
+- WCAG 2.1 AA accessibility compliance
+- Proper `aria-label` on forms and interactive elements
+- Responsive design (mobile-first)
+
+## Icon Usage
+
+**CRITICAL**: Always verify icons exist before using them in views to avoid MissingTemplate errors.
+
+### Icon Workflow
+
+1. **Search for existing icons first**:
+   ```bash
+   # List all available icons
+   ls app/views/shared/icons/
+
+   # Search for specific icon by name
+   ls app/views/shared/icons/ | grep -i "search_term"
+
+   # Example: Find alert-related icons
+   ls app/views/shared/icons/ | grep -i "alert"
+   # Returns: _alert_circle.html.erb, _alert_triangle.html.erb
+   ```
+
+2. **Use the correct icon name** (without underscore prefix or file extension):
+   ```erb
+   <!-- Correct -->
+   <%= render_theme_icon("alert_circle", css_class: "w-5 h-5") %>
+
+   <!-- Wrong - will cause MissingTemplate error -->
+   <%= render_theme_icon("alert", css_class: "w-5 h-5") %>
+   <%= render_theme_icon("info", css_class: "w-5 h-5") %>
+   ```
+
+3. **If the desired icon doesn't exist**, create a new one:
+
+   **a. Find an appropriate SVG**:
+   - Source: [Heroicons](https://heroicons.com/) (MIT License, commercially safe, no attribution required)
+   - Download the 24x24 outline version
+   - Alternative: Create custom SVG following the same style
+
+   **b. Create the icon partial**:
+   ```bash
+   # File naming: app/views/shared/icons/_icon_name.html.erb
+   # Use snake_case, prefix with underscore
+   touch app/views/shared/icons/_new_icon_name.html.erb
+   ```
+
+   **c. Icon template structure**:
+   ```erb
+   <%# Icon: New Icon Name (brief description) %>
+   <%# Source: https://heroicons.com/ (if applicable) %>
+   <svg xmlns="http://www.w3.org/2000/svg"
+        fill="none"
+        viewBox="0 0 24 24"
+        stroke-width="1.5"
+        stroke="currentColor"
+        class="<%= css_class %>">
+     <!-- SVG path data here -->
+     <path stroke-linecap="round" stroke-linejoin="round" d="..." />
+   </svg>
+   ```
+
+   **d. Key requirements**:
+   - Use `currentColor` for stroke/fill (allows color control via CSS)
+   - Accept `css_class` parameter for size and color classes
+   - Add comment header with icon name and source
+   - Follow existing icon structure (see other icons for examples)
+
+4. **Test the new icon**:
+   ```bash
+   # Verify icon renders without errors
+   bundle exec rake test
+
+   # Check icon appears in style guide
+   # Visit /style-guide in development
+   ```
+
+### Common Icon Names
+
+Icons use descriptive snake_case names:
+- `alert_circle` - Circle with exclamation (info/warning)
+- `alert_triangle` - Triangle with exclamation (error/danger)
+- `check_circle` - Circle with checkmark (success)
+- `cog` - Settings/configuration
+- `palette` - Theme/color settings
+- `package` - Package/module
+- `external_link` - External link indicator
+- `plus` - Add/create
+- `download` - Download action
+
+**Pro tip**: Run `ls app/views/shared/icons/ | sed 's/_//' | sed 's/.html.erb//' | sort` to get a clean list of all available icon names.
+
+## Navbar Synchronization
+
+**CRITICAL**: When updating the main navbar (`app/views/shared/_navbar.html.erb`), ensure that the Mission Control navbar (`app/views/layouts/mission_control/jobs/application.html.erb`) stays synchronized:
+
+- **Colors**: All navbar links should be white (#ffffff) with cyan (#06b6d4) hover
+- **Dropdown styling**: Dropdown menu items follow the same color scheme
+- **Logout button**: Uses same styling as other navbar links
+- **Theme switcher**: Both navbars should support theme switching
+- **Special item types**: Both navbars must handle divider and theme_selector types
+
+When making navbar changes, update BOTH files to maintain consistency across the application.
+
+## Asset Pipeline Architecture
+
+- No preprocessing in dev, auto-digest in prod
+- CSS organization via `app/assets/stylesheets/application.css`
+- No inline styles or embedded style tags
+- Check that new CSS is properly imported in application.css
+
+## Multi-Theme System
+
+Neon Sakura uses a comprehensive theme system with CSS custom properties. **NEVER use hardcoded colors** - always use CSS variables.
+
+### Theme Architecture
+
+Each theme is defined by two dimensions:
+- **Name**: `green` or `purple` (color family)
+- **Mode**: `light` or `dark` (brightness)
+
+Themes are applied via data attributes on the `<html>` element:
+```html
+<html data-theme-name="purple" data-theme-mode="dark">
+```
+
+### CSS Custom Properties (Variables)
+
+**CRITICAL**: ALL colors must use CSS variables. Never hardcode hex colors in utility classes or components.
+
+Available theme variables:
+- `--color-text-primary` - Primary text color
+- `--color-text-secondary` - Secondary text color
+- `--color-text-muted` - Muted/disabled text
+- `--color-background` - Page background
+- `--color-surface` - Card/panel backgrounds
+- `--color-accent` - Primary accent color (purple or green depending on theme)
+- `--color-notification` - Success/notification color
+- `--color-alert` - Error/alert color
+- `--color-warning` - Warning color
+- `--color-border` - Border color
+- `--gradient-from` / `--gradient-to` - Button background gradients
+- `--gradient-from-hover` / `--gradient-to-hover` - Button hover gradients
+- `--text-gradient-from` / `--text-gradient-to` - Text gradients for headings/links
+
+### Built-in Themes
+
+1. **Purple Dark** (default) - Primary accent: #a855f7, Gradient: Blue → Purple
+2. **Purple Light** - Primary accent: #a855f7, Gradient: Purple → Purple
+3. **Green Dark** - Primary accent: #10b981, Gradient: Green → Cyan
+4. **Green Light** - Primary accent: #009990, Gradient: Green → Cyan
+5. **Red Dark** - Primary accent: #ef4444, Gradient: Red → Orange
+6. **Red Light** - Primary accent: #dc2626, Gradient: Red → Orange
+
+### Theme Development Workflow
+
+**When adding new styles:**
+1. ✅ **ALWAYS** use `var(--color-*)` instead of hardcoded colors
+2. ✅ Use `color-mix()` for intermediate shades when needed
+3. ✅ Test your changes in ALL 4 themes (green/purple × light/dark)
+4. ❌ **NEVER** hardcode hex colors like `#a855f7` or `#10b981`
+5. ❌ **NEVER** use theme-specific colors (e.g., "purple" or "green" in class names)
+
+**Good examples:**
+```css
+.my-component {
+  color: var(--color-text-primary);
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+}
+
+.my-button {
+  background: linear-gradient(to right, var(--gradient-from), var(--gradient-to));
+}
+
+.my-heading {
+  background: linear-gradient(to right, var(--text-gradient-from), var(--text-gradient-to));
+  background-clip: text;
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+}
+```
+
+**Bad examples:**
+```css
+/* ❌ NEVER do this */
+.my-component {
+  color: #ffffff;  /* Use var(--color-text-primary) */
+  background: #1f2937;  /* Use var(--color-surface) */
+}
+
+.my-button {
+  background: linear-gradient(to right, #2563eb, #9333ea);  /* Use var(--gradient-from), var(--gradient-to) */
+}
+```
+
+### Adding New Themes
+
+To add a new theme, update `base.css` with new color definitions:
+
+```css
+:root[data-theme-name="custom"][data-theme-mode="dark"] {
+  --color-text-primary: #your-color;
+  --color-background: #your-color;
+  --color-surface: #your-color;
+  --color-accent: #your-color;
+  --color-notification: #your-color;
+  --color-alert: #your-color;
+  --color-warning: #your-color;
+  --color-border: #your-color;
+  --gradient-from: #your-color;
+  --gradient-to: #your-color;
+  --gradient-from-hover: #your-color;
+  --gradient-to-hover: #your-color;
+  --text-gradient-from: #your-color;
+  --text-gradient-to: #your-color;
+}
+```
+
+### Theme Testing
+
+Before committing style changes, test in ALL 6 themes:
+1. **Purple Dark** (default) - Check default appearance
+2. **Purple Light** - Check text visibility and contrast
+3. **Green Dark** - Ensure gradients are green→cyan, not purple
+4. **Green Light** - Check contrast and visibility
+5. **Red Dark** - Ensure gradients are red→orange
+6. **Red Light** - Check text visibility and red accent visibility
+
+Common issues to check:
+- Text visibility on buttons in light themes (should be white)
+- Gradient colors match theme color family:
+  - Green themes: green → cyan gradients
+  - Purple themes: blue → purple gradients
+  - Red themes: red → orange gradients
+- Border visibility in all themes
+- Hover states are visible and distinct
+- Accent color is appropriate for theme (green/purple/red)
+
+### Migrating Hardcoded Colors
+
+When refactoring existing code with hardcoded colors:
+
+1. Identify the semantic meaning of the color
+2. Map to appropriate CSS variable:
+   - `#111827`, `#0f172a` → `var(--color-background)`
+   - `#1f2937`, `#1e293b` → `var(--color-surface)`
+   - `#374151`, `#334155`, `#dee2e6` → `var(--color-border)`
+   - `#ffffff`, `#e2e8f0`, `#545E75` → `var(--color-text-primary)`
+   - `#a855f7`, `#10b981`, `#009990` → `var(--color-accent)`
+   - `#10b981` → `var(--color-notification)`
+   - `#ef4444`, `#DE5959` → `var(--color-alert)`
+   - `#f59e0b` → `var(--color-warning)`
+3. Use `color-mix()` for intermediate shades
+4. Test in all themes
+
+## CSS File Structure
+
+Neon Sakura uses a modular CSS architecture with a flat file structure for Propshaft compatibility.
+
+### File Hierarchy
+
+All CSS files are in the root `app/assets/stylesheets/` directory (no subdirectories):
+
+```
+app/assets/stylesheets/
+├── neon_sakura.css (complete manifest)
+├── base.css (manifest: themes + utilities)
+├── theme-default.css (:root default theme)
+├── theme-purple.css (purple light + dark)
+├── theme-green.css (green light + dark)
+├── theme-red.css (red light + dark)
+├── utility-reset.css (body reset)
+├── utility-layout.css (display, flex, grid)
+├── utility-sizing.css (width, height)
+├── utility-spacing.css (padding, margin, gap)
+├── utility-colors.css (bg/text colors)
+├── utility-borders.css (borders, radius)
+├── utility-typography.css (fonts, text)
+├── utility-gradients.css (gradients)
+├── utility-effects.css (shadows, transitions, hover/focus)
+├── utility-responsive.css (media queries)
+├── components.css (UI components)
+├── forms.css (form styling)
+└── pagy-tailwind.css (pagination)
+```
+
+**Why flat structure?** Propshaft serves all assets from a flat `/assets/` URL path. CSS `@import` statements with subdirectory paths (e.g., `@import "themes/purple.css"`) cause 404 errors because the browser looks for `/assets/themes/purple.css`, which doesn't exist in Propshaft's URL structure.
+
+### Load Order (CRITICAL)
+
+The CSS load order is critical for the cascade:
+
+1. **Themes** (defines CSS variables)
+2. **Utilities** (uses CSS variables)
+3. **Components/Forms** (uses both)
+
+**IMPORTANT**: With Propshaft, `@import` statements are **NOT** processed by the asset pipeline. They are resolved by the browser, which can cause issues when loading CSS from gems.
+
+**Recommended approach**: Use the `neon_sakura_stylesheets` helper in your layout:
+
+```erb
+<%= neon_sakura_stylesheets %>
+```
+
+This helper loads all CSS files individually in the correct order, ensuring proper cascade and browser compatibility.
+
+**Alternative approach**: Load files individually via `stylesheet_link_tag` in the correct order (see the helper source for the exact order).
+
+### Adding New Styles
+
+When adding new styles, follow this file organization:
+
+| Style Type | File | Example |
+|------------|------|---------|
+| Theme colors | `theme-*.css` | New color variables for a theme |
+| Layout utilities | `utility-layout.css` | `.flex`, `.grid`, `.block` |
+| Sizing utilities | `utility-sizing.css` | `.w-*`, `.h-*` |
+| Spacing utilities | `utility-spacing.css` | `.p-*`, `.m-*`, `.gap-*` |
+| Color utilities | `utility-colors.css` | `.bg-*`, `.text-*` |
+| Border utilities | `utility-borders.css` | `.border-*`, `.rounded-*` |
+| Typography | `utility-typography.css` | `.text-*`, `.font-*` |
+| Gradients | `utility-gradients.css` | `.bg-gradient-*`, `.from-*`, `.to-*` |
+| Effects | `utility-effects.css` | `.shadow-*`, `.transition-*`, `.hover:*` |
+| Responsive | `utility-responsive.css` | `@media` queries |
+| UI components | `components.css` | `.card`, `.badge`, `.nav` |
+| Form styling | `forms.css` | Input, button, select styles |
+| Pagination | `pagy-tailwind.css` | Pagy navigation |
+
+### Editing Existing Styles
+
+**DO NOT** create new files for one-off changes. Edit the corresponding file:
+
+- **Theme colors**: Edit `theme-purple.css`, `theme-green.css`, or `theme-red.css`
+- **Utility classes**: Edit the appropriate `utility-*.css` file
+- **Components**: Edit `components.css`
+- **Forms**: Edit `forms.css`
+
+### Creating New Themes
+
+To create a new theme (e.g., `blue`):
+
+1. Create `app/assets/stylesheets/theme-blue.css`
+2. Define both light and dark variants:
+   ```css
+   [data-theme-name="blue"][data-theme-mode="light"] {
+     --color-text-primary: #...;
+     --color-background: #...;
+     /* ... all required variables */
+   }
+
+   [data-theme-name="blue"][data-theme-mode="dark"] {
+     --color-text-primary: #...;
+     --color-background: #...;
+     /* ... all required variables */
+   }
+   ```
+3. Import in both `base.css` and `neon_sakura.css` after existing themes:
+   ```css
+   @import "theme-default.css";
+   @import "theme-purple.css";
+   @import "theme-green.css";
+   @import "theme-red.css";
+   @import "theme-blue.css";  /* Add new theme here */
+   ```
+4. Test in both light and dark modes
+
+## Accessibility Requirements
+
+- All interactive elements must have proper `aria-label` or `aria-labelledby`
+- WCAG 2.1 AA compliance for color contrast
+- Proper heading structure (`h1`, `h2`, etc.)
+- Semantic HTML elements
+
+## Security
+
+- OWASP Top 10 vulnerabilities (SQL injection, XSS, CSRF, etc.)
+- Path traversal attacks in file operations
+- Insecure redirects (must use `only_path: true`)
+- Mass assignment vulnerabilities
+- Exposed secrets or credentials
+- External links must have `rel: "noopener noreferrer"`
+- Proper use of `sanitize` over `raw` for HTML
+- JavaScript: No `innerHTML`, use `addEventListener`, proper escaping with `<%= j variable %>`
+
+## Code Style
+
+- DRY principle (Don't Repeat Yourself)
+- Ruby/JS/CSS/HTML: 2 spaces indentation
+- Python: 4 spaces indentation
+- Line length: 120 chars (Ruby), 88 (Python)
+- No tabs, no trailing whitespace
+- Rails Omakase style compliance
+- Use Oj (`Oj.load/dump`) instead of JSON (2-10x faster)
+- Proper error handling and edge cases
+
+## CSS Linting
+
+Neon Sakura uses Stylelint with the industry-standard configuration for CSS code quality and consistency.
+
+### Setup
+
+1. **Install dependencies** (first time only):
+   ```bash
+   yarn install
+   ```
+
+2. **Run Stylelint manually**:
+   ```bash
+   yarn lint:css        # Check for issues
+   yarn lint:css:fix    # Auto-fix issues
+   ```
+
+### Configuration
+
+- **Config file**: `.stylelintrc.json` - Uses `stylelint-config-standard` for industry-standard CSS linting
+- **Ignore file**: `.stylelintignore` - Excludes vendor files and third-party libraries
+- **Pre-commit hook**: Automatically runs on `git commit` (can be skipped with `--no-verify`)
+
+### Rules
+
+Stylelint enforces:
+- Consistent formatting and spacing
+- Valid CSS syntax
+- No duplicate selectors or properties
+- Proper use of vendor prefixes
+- Color function notation consistency
+- Theme-aware custom properties
+
+### Custom Rules
+
+The gem's configuration customizes the standard ruleset to:
+- Allow Tailwind CSS at-rules (`@tailwind`, `@apply`, etc.)
+- Allow flexible class naming patterns (for utility classes)
+- Allow custom property patterns (for CSS variables)
+- Support vendor prefixes (for browser compatibility)
+- Use legacy color function notation for better browser support
+
+### Common Issues
+
+**Issue**: `Unexpected unknown at-rule "@import"`
+**Fix**: Ensure you're using `@import` in manifest files only (base.css, neon_sakura.css)
+
+**Issue**: `Expected class selector to match pattern`
+**Fix**: This rule is disabled - use any class naming convention needed
+
+**Issue**: `Unexpected vendor-prefixed property`
+**Fix**: This rule is disabled - vendor prefixes are allowed for compatibility
+
+### Integration with Git Hooks
+
+Stylelint runs automatically in the pre-commit hook:
+1. Only runs if yarn and package.json are present
+2. Checks all staged CSS files
+3. Fails commit if issues are found
+4. Provides auto-fix command: `yarn lint:css:fix`
+
+To skip Stylelint (not recommended):
+```bash
+git commit --no-verify
+```
+
+## Search Services
+
+- **Search Services Pattern:**
+  ```ruby
+  def initialize(bypass_cache: false, **options)  # Config only, NO search_term
+    @bypass_cache = bypass_cache
+  end
+
+  def search(search_term)  # search_term HERE
+    search_with_benchmark(search_term)
+  end
+  ```
+- Use `HttpRequestService` with 24h HTTP cache
+- Benchmark execution time for searches
+- Sort results by date (newest first)
+- Services return structured data (arrays of hashes)
+
+## Testing
+
+- Minimum 80% overall test coverage (enforced by CI)
+- Minimum 20% per-file coverage
+- No coverage drops allowed
+- No skipped tests (`skip` is forbidden)
+- Use WebMock for HTTP mocking (NEVER use `define_method` globally - causes test pollution)
+- Health checks for service classes: `domain_up?`, `search_working?`
+- Test both success and error cases
+- Fixtures for WebMock responses
+
+## Pull Requests
+
+- PR descriptions must start with "# What does this PR do?"
+- Pre-commit: RuboCop, Brakeman, Bundle Audit, migrations, secrets
+- Pre-push: Schema consistency, asset compilation, TODO/FIXME
+- Never skip hooks without good reason
+
+## AI PR Reviewer
+
+For each PR (new or updates) that modifies code, Claude will:
+1. Run pre-commit checks (RuboCop, Brakeman, Bundle Audit, migrations, secrets)
+2. Run pre-push checks (schema consistency, asset compilation, TODO/FIXME)
+3. Run the AI code review with the correct system prompt
+4. If code quality issues or security flaws are found, it will fail the PR checks
+
+The AI reviewer uses the following system prompt:
+You are an expert Rails 8 code reviewer for the Neon Sakura gem project.
+
+Always add newlines at the end of new code files

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+git_source(:github) { |_repo_name| "https://github.com/TRex22/neon_sakura" }
+
+# Specify your gem's dependencies in neon_sakura.gemspec
+gemspec