docs: move HYPERSCRIPT-RULES.md and MODERN-WEB-TECHNIQUES.md to doc/ folder
This commit is contained in:
juanatsap
@@ -0,0 +1,134 @@
|
||||
# Hyperscript Development Rules
|
||||
|
||||
## MANDATORY RULES - ALWAYS FOLLOW
|
||||
|
||||
### Rule 1: Code Cleanliness
|
||||
**More than 3 lines of hyperscript → Move to function in file**
|
||||
|
||||
- Inline hyperscript in HTML should be kept minimal (≤3 lines)
|
||||
- Longer logic MUST be extracted to named functions in .\_hs files
|
||||
- HTML templates should be clean and readable
|
||||
|
||||
### Rule 2: File Structure - Hyperscript 0.9.12 Limitation
|
||||
**Maximum 3 `def` statements TOTAL across ALL files**
|
||||
|
||||
⚠️ **CRITICAL**: Hyperscript 0.9.12 has a parser limitation - more than 3 `def` statements **across ALL loaded .\_hs files** causes:
|
||||
```
|
||||
Error: Expected 'end' but found 'def'
|
||||
```
|
||||
|
||||
**Solution for Global Reusable Functions**: Use regular JavaScript instead
|
||||
- `static/js/cv-functions.js` - Global toggle and utility functions
|
||||
- toggleCVLength(), toggleIcons(), toggleTheme()
|
||||
- syncPdfHover(), syncPrintHover(), highlightZoomControl()
|
||||
|
||||
**Solution for Hyperscript-Specific Logic**: Keep max 3 defs
|
||||
- `static/hyperscript/functions._hs` - ONLY hyperscript-specific utilities (printFriendly, initScrollBehavior, handleScroll)
|
||||
|
||||
**Why JavaScript for Global Functions:**
|
||||
- ✅ No artificial limits
|
||||
- ✅ Better performance (native JS)
|
||||
- ✅ Better debugging
|
||||
- ✅ Can still be called from hyperscript using `call toggleIcons(my.checked)`
|
||||
|
||||
### Rule 3: HTML Structure Cleanliness
|
||||
**HTML must be as clean as possible regarding hyperscript**
|
||||
|
||||
✅ **GOOD** - Clean, readable:
|
||||
```html
|
||||
<input type="checkbox"
|
||||
id="lengthToggle"
|
||||
_="on change call toggleCVLength(my.checked)">
|
||||
```
|
||||
|
||||
❌ **BAD** - Inline logic nightmare:
|
||||
```html
|
||||
<input type="checkbox"
|
||||
id="lengthToggle"
|
||||
_="on change
|
||||
if my.checked
|
||||
remove .cv-short from .cv-paper
|
||||
add .cv-long to .cv-paper
|
||||
set localStorage['cv-length'] to 'long'
|
||||
set #lengthToggleMenu's checked to true
|
||||
else
|
||||
remove .cv-long from .cv-paper
|
||||
add .cv-short to .cv-paper
|
||||
set localStorage['cv-length'] to 'short'
|
||||
set #lengthToggleMenu's checked to false
|
||||
end">
|
||||
```
|
||||
|
||||
## File Organization
|
||||
|
||||
```
|
||||
static/hyperscript/
|
||||
├── functions._hs → Core utilities (3 defs max)
|
||||
├── toggles._hs → Toggle functions (3 defs max)
|
||||
└── hover._hs → Hover sync functions (3 defs max)
|
||||
```
|
||||
|
||||
### Load Order in templates/index.html:
|
||||
```html
|
||||
<script type="text/hyperscript" src="/static/hyperscript/functions._hs"></script>
|
||||
<script type="text/hyperscript" src="/static/hyperscript/toggles._hs"></script>
|
||||
<script type="text/hyperscript" src="/static/hyperscript/hover._hs"></script>
|
||||
<script src="https://unpkg.com/hyperscript.org@0.9.12"></script>
|
||||
```
|
||||
|
||||
## Required Functions
|
||||
|
||||
### Core Functions (functions._hs)
|
||||
1. `printFriendly()` - Handle print-friendly view
|
||||
2. `initScrollBehavior()` - Initialize scroll variables
|
||||
3. `handleScroll()` - Manage scroll behavior and fixed button positioning
|
||||
|
||||
### Toggle Functions (toggles._hs)
|
||||
1. `toggleCVLength(isLong)` - Switch between short/long CV
|
||||
2. `toggleIcons(showIcons)` - Show/hide icons
|
||||
3. `toggleTheme(isClean)` - Switch between default/clean theme
|
||||
|
||||
### Hover Sync Functions (hover._hs)
|
||||
1. `syncPdfHover(show)` - Sync hover state across PDF buttons
|
||||
2. `syncPrintHover(show)` - Sync hover state across print buttons
|
||||
3. `highlightZoomControl(show)` - Highlight zoom control on hover
|
||||
|
||||
## Why These Rules Exist
|
||||
|
||||
### Maintainability
|
||||
- Functions with descriptive names are self-documenting
|
||||
- Easier to test and debug
|
||||
- Changes in one place instead of scattered across templates
|
||||
|
||||
### Performance
|
||||
- Browser caches .\_hs files
|
||||
- Reduces HTML payload size
|
||||
- Cleaner separation of concerns
|
||||
|
||||
### Hyperscript 0.9.12 Limitation
|
||||
- Parser breaks with >3 `def` in single file
|
||||
- MUST split into multiple files
|
||||
- Each file: ≤3 `def` statements
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
❌ **DON'T**: Put all functions in one file if you have >3 defs
|
||||
❌ **DON'T**: Write long inline hyperscript in HTML
|
||||
❌ **DON'T**: Delete functions to work around the 3-def limit
|
||||
|
||||
✅ **DO**: Split functions across multiple .\_hs files
|
||||
✅ **DO**: Keep HTML clean with function calls
|
||||
✅ **DO**: Maintain all required functions for clean architecture
|
||||
|
||||
## Testing After Changes
|
||||
|
||||
1. Check browser console for parse errors
|
||||
2. Verify all functions are defined (no "X is null" errors)
|
||||
3. Test all toggles work correctly
|
||||
4. Hard refresh browser (Ctrl+Shift+R) to clear cache
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-17
|
||||
**Hyperscript Version**: 0.9.12
|
||||
**Status**: MANDATORY - ALWAYS FOLLOW
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,167 @@
|
||||
<objective>
|
||||
Implement a keyboard shortcuts help feature that displays all available keyboard shortcuts in the CV web application. This feature will help users discover and use keyboard shortcuts efficiently, improving the overall user experience and accessibility.
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
This is a CV (resume) web application built with:
|
||||
- Backend: Go with Hono-like routing patterns
|
||||
- Frontend: HTMX + Hyperscript for interactivity
|
||||
- Styling: Modern CSS with native HTML5 elements
|
||||
- Philosophy: Minimal JavaScript, progressive enhancement, native browser APIs
|
||||
|
||||
The app already has:
|
||||
- An info modal using native `<dialog>` element (reference pattern)
|
||||
- Fixed action buttons (info icon, back-to-top, print, etc.)
|
||||
- Keyboard shortcuts implemented but not documented
|
||||
- HTMX-driven interactions with server endpoints
|
||||
|
||||
Before starting, read the project documentation to understand the application structure and conventions:
|
||||
@CLAUDE.md
|
||||
@MODERN-WEB-TECHNIQUES.md
|
||||
</context>
|
||||
|
||||
<research>
|
||||
Use the architecture agent to thoroughly analyze the codebase and identify ALL keyboard shortcuts and user actions:
|
||||
|
||||
1. **Examine documentation** to understand application features and architecture
|
||||
2. **Review all Go endpoints** to identify available actions (toggles, language switching, etc.)
|
||||
3. **Search for keyboard event handlers** in hyperscript and JavaScript files
|
||||
4. **Identify interactive elements** (buttons, toggles, forms) and their functions
|
||||
5. **Analyze HTMX attributes** (hx-post, hx-get) to understand available actions
|
||||
|
||||
Create a comprehensive list of:
|
||||
- Existing keyboard shortcuts (Ctrl+P for print, Ctrl+0 for zoom reset, etc.)
|
||||
- Actions that could benefit from keyboard shortcuts
|
||||
- Standard browser shortcuts that work in the app (Ctrl+F for find, etc.)
|
||||
</research>
|
||||
|
||||
<requirements>
|
||||
1. **Icon Button**: Create a keyboard shortcuts help button
|
||||
- Position: Near the existing info icon in the fixed action buttons area
|
||||
- Icon: Keyboard icon (use iconify-icon like other buttons)
|
||||
- Behavior: Opens keyboard shortcuts modal on click
|
||||
- Styling: Consistent with existing action buttons
|
||||
|
||||
2. **Modal Dialog**: Create a keyboard shortcuts help modal
|
||||
- Use native `<dialog>` element (follow info modal pattern)
|
||||
- Display all keyboard shortcuts in organized groups
|
||||
- Include descriptions of what each shortcut does
|
||||
- Clean, readable layout with proper spacing
|
||||
|
||||
3. **Shortcuts Organization**: Group shortcuts logically
|
||||
- Navigation shortcuts (scroll, jump to sections)
|
||||
- View controls (zoom, toggles)
|
||||
- Actions (print, download)
|
||||
- Browser shortcuts (search, refresh)
|
||||
|
||||
4. **Accessibility**:
|
||||
- Proper ARIA labels for the button
|
||||
- Keyboard navigation (ESC to close, Tab for focus)
|
||||
- Screen reader friendly descriptions
|
||||
|
||||
5. **Bilingual Support**:
|
||||
- Spanish and English translations
|
||||
- Follow existing i18n patterns in the codebase
|
||||
</requirements>
|
||||
|
||||
<implementation>
|
||||
Follow the existing architectural patterns in the codebase:
|
||||
|
||||
1. **Modal Pattern**:
|
||||
- Use native `<dialog>` element (see existing info modal as reference)
|
||||
- Include `::backdrop` styling for overlay
|
||||
- Close button with onclick="this.closest('dialog').close()"
|
||||
- Simple inline onclick for opening: `onclick="document.getElementById('shortcuts-modal').showModal()"`
|
||||
|
||||
2. **Button Pattern**:
|
||||
- Follow fixed action button styling
|
||||
- Use iconify-icon for the keyboard icon (find appropriate icon from mdi: collection)
|
||||
- Position using existing CSS patterns for action buttons
|
||||
|
||||
3. **File Structure**:
|
||||
- Create modal template in `./templates/partials/modals/` or similar
|
||||
- Add button to appropriate location (likely near info button)
|
||||
- Update CSS if needed for styling
|
||||
|
||||
4. **NO JavaScript required** for basic open/close (use native dialog features)
|
||||
- Only use inline onclick attributes following existing patterns
|
||||
- Leverage browser's built-in dialog functionality
|
||||
|
||||
WHY these patterns matter:
|
||||
- Native `<dialog>` provides built-in accessibility, focus management, and ESC key handling
|
||||
- Inline onclick keeps code simple and colocated with markup (following project philosophy)
|
||||
- Consistent styling ensures professional, cohesive UI
|
||||
- Minimal JavaScript aligns with project's "almost 0 JavaScript" goal
|
||||
</implementation>
|
||||
|
||||
<shortcuts_content>
|
||||
Based on your research, include shortcuts such as (but not limited to):
|
||||
|
||||
**Zoom Controls:**
|
||||
- Ctrl/Cmd + Plus: Zoom in
|
||||
- Ctrl/Cmd + Minus: Zoom out
|
||||
- Ctrl/Cmd + 0: Reset zoom to 100%
|
||||
|
||||
**Actions:**
|
||||
- Ctrl/Cmd + P: Print friendly version
|
||||
|
||||
**Browser Shortcuts (mention these too):**
|
||||
- Ctrl/Cmd + F: Find in page
|
||||
- Ctrl/Cmd + R: Refresh page
|
||||
|
||||
Add any other shortcuts discovered during research.
|
||||
|
||||
Organize them in a clean table or list format with:
|
||||
- Shortcut keys (visual representation)
|
||||
- Description of action
|
||||
- Bilingual labels (ES/EN)
|
||||
</shortcuts_content>
|
||||
|
||||
<output>
|
||||
Create/modify the following files:
|
||||
|
||||
1. `./templates/partials/modals/shortcuts-modal.html` - Keyboard shortcuts modal dialog
|
||||
2. Modify the appropriate template to add the keyboard shortcuts button (likely where other action buttons are)
|
||||
3. Update CSS if needed for button positioning and modal styling (follow existing patterns)
|
||||
|
||||
Use relative paths and ensure all changes integrate seamlessly with existing code.
|
||||
</output>
|
||||
|
||||
<verification>
|
||||
Before declaring complete, verify:
|
||||
|
||||
1. **Research Complete**:
|
||||
- Run searches to confirm all keyboard shortcuts are identified
|
||||
- Check that all major user actions are covered
|
||||
|
||||
2. **Functionality**:
|
||||
- Button appears in correct position near info icon
|
||||
- Clicking button opens modal
|
||||
- ESC key closes modal
|
||||
- Backdrop click closes modal
|
||||
- Close button works
|
||||
|
||||
3. **Visual Integration**:
|
||||
- Button styling matches other action buttons
|
||||
- Modal styling matches info modal
|
||||
- Layout is clean and readable
|
||||
|
||||
4. **Bilingual**:
|
||||
- All text has Spanish and English versions
|
||||
- Language switching works correctly
|
||||
|
||||
5. **Accessibility**:
|
||||
- ARIA labels present
|
||||
- Keyboard navigation works
|
||||
- Focus management is correct
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Keyboard shortcuts help button visible and clickable near info icon
|
||||
- Modal displays comprehensive list of all keyboard shortcuts
|
||||
- Modal follows native `<dialog>` pattern (like info modal)
|
||||
- All shortcuts organized logically with clear descriptions
|
||||
- Bilingual support (ES/EN) working correctly
|
||||
- Zero JavaScript required for basic functionality (native dialog features only)
|
||||
- Code follows project philosophy and existing patterns
|
||||
</success_criteria>
|
||||
Reference in New Issue
Block a user