askrobots / dbbasic-web-native
Public
100+ copy-paste UI components in plain HTML and CSS: no dependencies, no build step.
danq9
Add canonical.html v1.0 - The single source of truth for usability standards
fb6e650
1 year ago
History
generate-docs.js · 33.7 KB · 841 lines
| 1 | #!/usr/bin/env node |
| 2 | |
| 3 | /** |
| 4 | * Automatic Documentation Generator for Semantic Components |
| 5 | * |
| 6 | * Reads semantic-components.js and generates comprehensive documentation pages |
| 7 | * for each component automatically. |
| 8 | * |
| 9 | * Usage: node generate-docs.js |
| 10 | */ |
| 11 | |
| 12 | const fs = require('fs'); |
| 13 | const path = require('path'); |
| 14 | |
| 15 | // Component metadata - extracted from component definitions |
| 16 | const components = { |
| 17 | 'semantic-action': { |
| 18 | name: 'semantic-action', |
| 19 | tagline: 'Intent-based button component with multi-modal interaction support', |
| 20 | description: 'The semantic-action component represents a user action with clear intent and consequence. Instead of styling a generic "button", you declare the importance (intent) and consequence (sentiment) of the action.', |
| 21 | attributes: [ |
| 22 | { name: 'intent', type: 'string', values: 'primary | secondary | tertiary', default: 'primary', description: 'Importance level in the interface hierarchy' }, |
| 23 | { name: 'sentiment', type: 'string', values: 'constructive | destructive | neutral', default: 'neutral', description: 'Consequence of the action (safe, dangerous, or neutral)' }, |
| 24 | { name: 'disabled', type: 'boolean', values: 'true | false', default: 'false', description: 'Whether the action is currently available' }, |
| 25 | { name: 'urgency', type: 'string', values: 'critical | high | medium | low', default: 'medium', description: 'Priority for attention budget scoring' }, |
| 26 | { name: 'attention-weight', type: 'number', values: '0-100', default: '50', description: 'Base attention priority (higher = more visible)' } |
| 27 | ], |
| 28 | events: [ |
| 29 | { name: 'activate', trigger: 'Click, tap, Enter, Space, voice "activate"', detail: '{ type: "activate" }', description: 'Main action event triggered by any input method' }, |
| 30 | { name: 'inspect', trigger: 'Long-press (500ms), voice "inspect"', detail: '{ type: "inspect" }', description: 'Preview/detail view event for long-press interactions' } |
| 31 | ], |
| 32 | states: [ |
| 33 | { name: 'Default', description: 'Blue background, white text, rounded corners, subtle shadow' }, |
| 34 | { name: 'Hover', description: 'Lifts up 2px, tight blue glow (8px blur, 0.6 opacity), brightness boost' }, |
| 35 | { name: 'Active', description: 'Scales 96% + pushes down 1px + inset shadow for "pressed in" feel' }, |
| 36 | { name: 'Focus', description: '3px blue outline, 2px offset for keyboard navigation' }, |
| 37 | { name: 'Disabled', description: 'Grey background (#3a3a3a), grey text (#8a8a8a), 60% opacity' } |
| 38 | ], |
| 39 | examples: [ |
| 40 | { |
| 41 | label: 'Primary Intent', |
| 42 | code: '<semantic-action intent="primary">Save Changes</semantic-action>', |
| 43 | notes: 'Use for: The main action on the page\nVisual: Blue background (#0066cc), white text\nContrast: 5.9:1 (WCAG AA compliant)\nExamples: Save, Submit, Continue, Confirm' |
| 44 | }, |
| 45 | { |
| 46 | label: 'Constructive Sentiment', |
| 47 | code: '<semantic-action intent="primary" sentiment="constructive">Save Changes</semantic-action>', |
| 48 | notes: 'Use for: Positive, safe actions\nVisual: Green background (#34c759), white text\nContrast: 5.8:1 (WCAG AA compliant)\nExamples: Save, Create, Publish, Enable' |
| 49 | }, |
| 50 | { |
| 51 | label: 'Destructive Sentiment', |
| 52 | code: '<semantic-action intent="primary" sentiment="destructive">Delete Forever</semantic-action>', |
| 53 | notes: 'Use for: Dangerous, irreversible actions\nVisual: Red background (#ff3b30), white text\nContrast: 4.5:1 (WCAG AA minimum)\nExamples: Delete, Remove, Disable, Logout' |
| 54 | } |
| 55 | ] |
| 56 | }, |
| 57 | |
| 58 | 'semantic-card': { |
| 59 | name: 'semantic-card', |
| 60 | tagline: 'Inspectable content cards with preview on hover and long-press', |
| 61 | description: 'The semantic-card component displays content in a structured format with optional media, title, description, preview content, and actions. It automatically handles hover elevation and preview display.', |
| 62 | attributes: [ |
| 63 | { name: 'media-url', type: 'attribute', values: 'URL', default: '', description: 'URL for image media' }, |
| 64 | { name: 'media-alt', type: 'attribute', values: 'text', default: '', description: 'Alt text for image' } |
| 65 | ], |
| 66 | slots: [ |
| 67 | { name: 'media-icon', description: 'Icon/emoji when no image' }, |
| 68 | { name: 'title', description: 'Card title' }, |
| 69 | { name: 'description', description: 'Card description/subtitle' }, |
| 70 | { name: 'preview', description: 'Content shown on hover/long-press' }, |
| 71 | { name: 'actions', description: 'Action buttons' } |
| 72 | ], |
| 73 | events: [ |
| 74 | { name: 'activate', trigger: 'Click on card', detail: '{ type: "activate" }', description: 'Card click/tap event' }, |
| 75 | { name: 'inspect', trigger: 'Long-press (500ms)', detail: '{ type: "inspect" }', description: 'Shows preview content' } |
| 76 | ], |
| 77 | states: [ |
| 78 | { name: 'Default', description: 'Flat, subtle shadow, grey border' }, |
| 79 | { name: 'Hover', description: 'Lifts 4px, blue border glow, preview slides in' }, |
| 80 | { name: 'Active', description: 'Slight scale down on click' } |
| 81 | ], |
| 82 | examples: [ |
| 83 | { |
| 84 | label: 'Basic Card', |
| 85 | code: `<semantic-card> |
| 86 | <span slot="media-icon">🚀</span> |
| 87 | <card-title slot="title">Project Alpha</card-title> |
| 88 | <card-description slot="description">Next-gen platform</card-description> |
| 89 | <div slot="preview">Preview content here</div> |
| 90 | </semantic-card>`, |
| 91 | notes: 'Use for: Content previews, product cards, article teasers\nVisual: Dark background, hover elevation\nInteraction: Click to activate, long-press to preview' |
| 92 | } |
| 93 | ] |
| 94 | }, |
| 95 | |
| 96 | 'semantic-input': { |
| 97 | name: 'semantic-input', |
| 98 | tagline: 'Form inputs with voice hints, validation, and multi-modal support', |
| 99 | description: 'The semantic-input component provides form input fields with automatic validation states, voice dictation hints, and multi-modal support.', |
| 100 | attributes: [ |
| 101 | { name: 'label', type: 'string', values: 'text', default: '', description: 'Label for the input' }, |
| 102 | { name: 'type', type: 'string', values: 'text | email | password | number', default: 'text', description: 'Input type' }, |
| 103 | { name: 'placeholder', type: 'string', values: 'text', default: '', description: 'Placeholder text' }, |
| 104 | { name: 'value', type: 'string', values: 'text', default: '', description: 'Current value' }, |
| 105 | { name: 'error', type: 'string', values: 'text', default: '', description: 'Error message' }, |
| 106 | { name: 'valid', type: 'boolean', values: 'true | false', default: 'false', description: 'Show valid state' }, |
| 107 | { name: 'disabled', type: 'boolean', values: 'true | false', default: 'false', description: 'Disable input' } |
| 108 | ], |
| 109 | events: [ |
| 110 | { name: 'input', trigger: 'User types', detail: '{ value }', description: 'Fires on every keystroke' }, |
| 111 | { name: 'change', trigger: 'Value changes and loses focus', detail: '{ value }', description: 'Fires when input is complete' }, |
| 112 | { name: 'focus', trigger: 'Input receives focus', detail: '{}', description: 'Focus event' }, |
| 113 | { name: 'blur', trigger: 'Input loses focus', detail: '{ value }', description: 'Blur event' } |
| 114 | ], |
| 115 | states: [ |
| 116 | { name: 'Default', description: 'Dark input with grey border' }, |
| 117 | { name: 'Focus', description: 'Blue border (#0066cc), blue glow' }, |
| 118 | { name: 'Valid', description: 'Green border (#34c759)' }, |
| 119 | { name: 'Error', description: 'Red border (#ff3b30) + red error text below' }, |
| 120 | { name: 'Disabled', description: 'Grey background, 50% opacity' } |
| 121 | ], |
| 122 | examples: [ |
| 123 | { |
| 124 | label: 'Text Input', |
| 125 | code: '<semantic-input label="Full Name" placeholder="Enter your name" type="text"></semantic-input>', |
| 126 | notes: 'Use for: Text entry fields\nValidation: None by default\nVoice: "Type Full Name" to dictate' |
| 127 | }, |
| 128 | { |
| 129 | label: 'Valid State', |
| 130 | code: '<semantic-input label="Email" value="user@example.com" type="email" valid></semantic-input>', |
| 131 | notes: 'Use for: Showing successful validation\nVisual: Green border\nContrast: Meets WCAG AA' |
| 132 | }, |
| 133 | { |
| 134 | label: 'Error State', |
| 135 | code: '<semantic-input label="Email" value="bad-email" type="email" error="Please enter a valid email"></semantic-input>', |
| 136 | notes: 'Use for: Validation errors\nVisual: Red border + error message\nAccessibility: Error announced to screen readers' |
| 137 | } |
| 138 | ] |
| 139 | }, |
| 140 | |
| 141 | 'semantic-modal': { |
| 142 | name: 'semantic-modal', |
| 143 | tagline: 'Context-aware modal dialogs with urgency levels and backdrop dismissal', |
| 144 | description: 'The semantic-modal component displays overlay dialogs with attention budget awareness. Modals automatically adjust their urgency presentation and can be dismissed by clicking the backdrop or pressing Escape.', |
| 145 | attributes: [ |
| 146 | { name: 'open', type: 'boolean', values: 'true | false', default: 'false', description: 'Whether the modal is currently visible' }, |
| 147 | { name: 'urgency', type: 'string', values: 'critical | high | medium | low', default: 'medium', description: 'Visual urgency level (critical shows red border)' }, |
| 148 | { name: 'dismissible', type: 'boolean', values: 'true | false', default: 'true', description: 'Whether modal can be dismissed by backdrop click/Escape' } |
| 149 | ], |
| 150 | slots: [ |
| 151 | { name: 'header', description: 'Modal title/header content' }, |
| 152 | { name: 'default', description: 'Main modal body content' }, |
| 153 | { name: 'actions', description: 'Modal footer with action buttons' } |
| 154 | ], |
| 155 | events: [ |
| 156 | { name: 'close', trigger: 'Backdrop click, Escape key, close button', detail: '{ type: "close" }', description: 'Modal closed event' } |
| 157 | ], |
| 158 | states: [ |
| 159 | { name: 'Closed', description: 'Hidden (display: none)' }, |
| 160 | { name: 'Open', description: 'Visible with backdrop fade-in and modal slide-up animation' }, |
| 161 | { name: 'Critical', description: 'Red border (#ff3b30) for urgent modals' } |
| 162 | ], |
| 163 | examples: [ |
| 164 | { |
| 165 | label: 'Basic Modal', |
| 166 | code: `<semantic-modal open> |
| 167 | <div slot="header">Confirm Action</div> |
| 168 | <div>Are you sure you want to continue?</div> |
| 169 | <div slot="actions"> |
| 170 | <semantic-action intent="primary">Confirm</semantic-action> |
| 171 | <semantic-action intent="secondary">Cancel</semantic-action> |
| 172 | </div> |
| 173 | </semantic-modal>`, |
| 174 | notes: 'Use for: Confirmation dialogs, forms, alerts\nVisual: Dark background, centered, backdrop blur\nInteraction: Click backdrop or press Escape to dismiss' |
| 175 | } |
| 176 | ] |
| 177 | }, |
| 178 | |
| 179 | 'semantic-navigator': { |
| 180 | name: 'semantic-navigator', |
| 181 | tagline: 'Multi-modal navigation with tabs, breadcrumbs, and spatial layouts', |
| 182 | description: 'The semantic-navigator component handles navigation UI patterns with support for tabs, sidebars, breadcrumbs, and spatial (AR/VR) navigation. It automatically highlights the current page.', |
| 183 | attributes: [ |
| 184 | { name: 'type', type: 'string', values: 'tabs | menu | breadcrumbs | spatial', default: 'tabs', description: 'Navigation layout pattern' }, |
| 185 | { name: 'current', type: 'string', values: 'href or ID', default: '', description: 'Currently active navigation item' } |
| 186 | ], |
| 187 | slots: [ |
| 188 | { name: 'default', description: 'nav-item elements for navigation links' } |
| 189 | ], |
| 190 | events: [ |
| 191 | { name: 'navigate', trigger: 'Navigation item clicked', detail: '{ href, label }', description: 'Navigation event before route change' } |
| 192 | ], |
| 193 | states: [ |
| 194 | { name: 'Default', description: 'Items in grey (#8a8a8a), hover to white' }, |
| 195 | { name: 'Current', description: 'Active item in blue (#0066cc), bold text' }, |
| 196 | { name: 'Hover', description: 'Background highlight, white text' } |
| 197 | ], |
| 198 | examples: [ |
| 199 | { |
| 200 | label: 'Tab Navigation', |
| 201 | code: `<semantic-navigator type="tabs" current="/home"> |
| 202 | <nav-item href="/home" icon="🏠">Home</nav-item> |
| 203 | <nav-item href="/profile" icon="👤">Profile</nav-item> |
| 204 | <nav-item href="/settings" icon="⚙️">Settings</nav-item> |
| 205 | </semantic-navigator>`, |
| 206 | notes: 'Use for: Tab navigation, page sections\nVisual: Horizontal tabs with border-bottom\nInteraction: Click to navigate, current highlighted' |
| 207 | } |
| 208 | ] |
| 209 | }, |
| 210 | |
| 211 | 'semantic-list': { |
| 212 | name: 'semantic-list', |
| 213 | tagline: 'Selectable lists with keyboard navigation and ARIA support', |
| 214 | description: 'The semantic-list component displays items in a vertical list with optional selection. Lists automatically handle keyboard navigation (arrow keys), focus management, and multi-select when enabled.', |
| 215 | attributes: [ |
| 216 | { name: 'type', type: 'string', values: 'default | compact | spacious', default: 'default', description: 'Visual density of list items' }, |
| 217 | { name: 'selectable', type: 'boolean', values: 'true | false', default: 'false', description: 'Whether items can be selected' } |
| 218 | ], |
| 219 | slots: [ |
| 220 | { name: 'default', description: 'list-item elements' } |
| 221 | ], |
| 222 | events: [ |
| 223 | { name: 'select', trigger: 'Item clicked (when selectable)', detail: '{ item, index }', description: 'Item selection event' } |
| 224 | ], |
| 225 | states: [ |
| 226 | { name: 'Default', description: 'Grey borders, dark background' }, |
| 227 | { name: 'Hover (selectable)', description: 'Blue border highlight' }, |
| 228 | { name: 'Selected', description: 'Blue border, blue background tint' }, |
| 229 | { name: 'Focus', description: 'Blue outline for keyboard navigation' } |
| 230 | ], |
| 231 | examples: [ |
| 232 | { |
| 233 | label: 'Selectable List', |
| 234 | code: `<semantic-list selectable> |
| 235 | <list-item>First Item</list-item> |
| 236 | <list-item>Second Item</list-item> |
| 237 | <list-item aria-selected="true">Selected Item</list-item> |
| 238 | </semantic-list>`, |
| 239 | notes: 'Use for: Option selection, file lists, settings\nKeyboard: Arrow keys navigate, Space/Enter select\nAccessibility: ARIA selection states announced' |
| 240 | } |
| 241 | ] |
| 242 | }, |
| 243 | |
| 244 | 'semantic-menu': { |
| 245 | name: 'semantic-menu', |
| 246 | tagline: 'Context menus and dropdowns with smart positioning', |
| 247 | description: 'The semantic-menu component displays dropdown/context menus with automatic positioning relative to an anchor element. Menus close on outside click or Escape key.', |
| 248 | attributes: [ |
| 249 | { name: 'open', type: 'boolean', values: 'true | false', default: 'false', description: 'Whether menu is currently shown' }, |
| 250 | { name: 'anchor', type: 'string', values: 'Element ID or selector', default: '', description: 'Element to position relative to' } |
| 251 | ], |
| 252 | slots: [ |
| 253 | { name: 'default', description: 'menu-item elements and menu-divider separators' } |
| 254 | ], |
| 255 | events: [ |
| 256 | { name: 'select', trigger: 'Menu item clicked', detail: '{ action, label }', description: 'Menu item selection event' }, |
| 257 | { name: 'close', trigger: 'Outside click, Escape key', detail: '{ type: "close" }', description: 'Menu closed event' } |
| 258 | ], |
| 259 | states: [ |
| 260 | { name: 'Closed', description: 'Hidden (display: none)' }, |
| 261 | { name: 'Open', description: 'Visible with scale-in animation, positioned near anchor' }, |
| 262 | { name: 'Hover (items)', description: 'Blue background on menu item hover' } |
| 263 | ], |
| 264 | examples: [ |
| 265 | { |
| 266 | label: 'Dropdown Menu', |
| 267 | code: `<semantic-action id="menu-btn">Options ▼</semantic-action> |
| 268 | <semantic-menu anchor="#menu-btn" open> |
| 269 | <menu-item action="edit">✏️ Edit</menu-item> |
| 270 | <menu-item action="copy">📋 Copy</menu-item> |
| 271 | <menu-divider></menu-divider> |
| 272 | <menu-item action="delete" intent="destructive">🗑️ Delete</menu-item> |
| 273 | </semantic-menu>`, |
| 274 | notes: 'Use for: Action menus, context menus, dropdowns\nVisual: Floating panel with shadow\nInteraction: Click outside or Escape to close' |
| 275 | } |
| 276 | ] |
| 277 | }, |
| 278 | |
| 279 | 'semantic-feedback': { |
| 280 | name: 'semantic-feedback', |
| 281 | tagline: 'Notifications, toasts, and alerts with urgency-based attention scoring', |
| 282 | description: 'The semantic-feedback component displays user notifications with automatic urgency coloring and optional auto-dismiss. Feedback respects attention budget and suppresses low-priority notifications when user is busy.', |
| 283 | attributes: [ |
| 284 | { name: 'urgency', type: 'string', values: 'critical | high | medium | low', default: 'medium', description: 'Urgency level (affects color and attention priority)' }, |
| 285 | { name: 'type', type: 'string', values: 'notification | alert | toast', default: 'notification', description: 'Feedback presentation style' }, |
| 286 | { name: 'auto-dismiss', type: 'boolean', values: 'true | false', default: 'false', description: 'Automatically dismiss after delay' } |
| 287 | ], |
| 288 | events: [ |
| 289 | { name: 'dismiss', trigger: 'Dismiss button clicked or auto-timeout', detail: '{ type: "dismiss" }', description: 'Feedback dismissed event' } |
| 290 | ], |
| 291 | states: [ |
| 292 | { name: 'Critical', description: 'Red border (#ff3b30), red background tint' }, |
| 293 | { name: 'High', description: 'Orange border (#ff9500), orange background tint' }, |
| 294 | { name: 'Medium', description: 'Blue border (#0066cc), blue background tint' }, |
| 295 | { name: 'Low', description: 'Grey border (#8a8a8a), minimal prominence' } |
| 296 | ], |
| 297 | examples: [ |
| 298 | { |
| 299 | label: 'Success Notification', |
| 300 | code: '<semantic-feedback urgency="medium" auto-dismiss>✅ Changes saved successfully</semantic-feedback>', |
| 301 | notes: 'Use for: Success confirmations, status updates\nVisual: Blue border, slide-in animation\nDuration: Auto-dismisses after 3 seconds' |
| 302 | }, |
| 303 | { |
| 304 | label: 'Critical Alert', |
| 305 | code: '<semantic-feedback urgency="critical">❌ Error: Unable to save changes. Please try again.</semantic-feedback>', |
| 306 | notes: 'Use for: Errors, critical warnings\nVisual: Red border, persistent (no auto-dismiss)\nAttention: Highest priority in attention budget' |
| 307 | } |
| 308 | ] |
| 309 | }, |
| 310 | |
| 311 | 'semantic-adjuster': { |
| 312 | name: 'semantic-adjuster', |
| 313 | tagline: 'Multi-modal number/value adjusters with voice, gesture, and button controls', |
| 314 | description: 'The semantic-adjuster component provides increment/decrement controls for numeric values. It supports button clicks, voice commands ("increase", "decrease"), gestures, and keyboard arrows.', |
| 315 | attributes: [ |
| 316 | { name: 'value', type: 'number', values: 'number', default: '50', description: 'Current numeric value' }, |
| 317 | { name: 'min', type: 'number', values: 'number', default: '0', description: 'Minimum allowed value' }, |
| 318 | { name: 'max', type: 'number', values: 'number', default: '100', description: 'Maximum allowed value' }, |
| 319 | { name: 'step', type: 'number', values: 'number', default: '1', description: 'Increment/decrement amount' }, |
| 320 | { name: 'label', type: 'string', values: 'text', default: 'Value', description: 'Label for the adjuster' } |
| 321 | ], |
| 322 | events: [ |
| 323 | { name: 'adjust', trigger: 'Value changed (button, voice, gesture)', detail: '{ value }', description: 'Value adjustment event' } |
| 324 | ], |
| 325 | states: [ |
| 326 | { name: 'Default', description: 'Circular +/- buttons, large center value' }, |
| 327 | { name: 'Hover', description: 'Button hover shows blue background' }, |
| 328 | { name: 'Min/Max Reached', description: 'Corresponding button disabled (grey)' } |
| 329 | ], |
| 330 | examples: [ |
| 331 | { |
| 332 | label: 'Volume Control', |
| 333 | code: '<semantic-adjuster label="Volume" value="75" min="0" max="100" step="5"></semantic-adjuster>', |
| 334 | notes: 'Use for: Volume, brightness, quantity adjustments\nVoice: "Increase volume", "Decrease volume"\nGestures: Swipe up/down in AR/VR' |
| 335 | }, |
| 336 | { |
| 337 | label: 'Temperature Setting', |
| 338 | code: '<semantic-adjuster label="Temperature" value="20" min="15" max="30" step="0.5"></semantic-adjuster>', |
| 339 | notes: 'Use for: Numeric settings, sliders, counters\nKeyboard: Arrow up/down to adjust\nTouch: Tap +/- or swipe' |
| 340 | } |
| 341 | ] |
| 342 | } |
| 343 | }; |
| 344 | |
| 345 | // HTML template generator |
| 346 | function generateComponentDoc(componentData) { |
| 347 | const { name, tagline, description, attributes = [], slots = [], events = [], states = [], examples = [] } = componentData; |
| 348 | |
| 349 | const attributeRows = attributes.map(attr => ` |
| 350 | <tr style="border-bottom: 1px solid #333;"> |
| 351 | <td style="padding: 12px;"><span class="prop-name">${attr.name}</span></td> |
| 352 | <td style="padding: 12px;"><span class="prop-type">${attr.type}</span></td> |
| 353 | <td style="padding: 12px;"><span class="prop-values">${attr.values}</span></td> |
| 354 | <td style="padding: 12px;">${attr.default}</td> |
| 355 | <td style="padding: 12px;">${attr.description}</td> |
| 356 | </tr>`).join(''); |
| 357 | |
| 358 | const slotRows = slots ? slots.map(slot => ` |
| 359 | <tr style="border-bottom: 1px solid #333;"> |
| 360 | <td style="padding: 12px;"><span class="prop-name">${slot.name}</span></td> |
| 361 | <td style="padding: 12px;"><span class="prop-type">slot</span></td> |
| 362 | <td style="padding: 12px;">${slot.description}</td> |
| 363 | </tr>`).join('') : ''; |
| 364 | |
| 365 | const eventRows = events.map(event => ` |
| 366 | <tr style="border-bottom: 1px solid #333;"> |
| 367 | <td style="padding: 12px;"><span class="prop-name">${event.name}</span></td> |
| 368 | <td style="padding: 12px;">${event.trigger}</td> |
| 369 | <td style="padding: 12px;"><code>${event.detail}</code></td> |
| 370 | <td style="padding: 12px;">${event.description}</td> |
| 371 | </tr>`).join(''); |
| 372 | |
| 373 | const stateBoxes = states.map(state => ` |
| 374 | <div class="state-box"> |
| 375 | <div class="state-label">${state.name} State</div> |
| 376 | <div class="state-visual state-${state.name.toLowerCase()}"> |
| 377 | <${name} intent="primary" ${state.name === 'Disabled' ? 'disabled' : ''}>${state.name}</${name}> |
| 378 | </div> |
| 379 | <div class="state-description">${state.description}</div> |
| 380 | </div>`).join(''); |
| 381 | |
| 382 | const exampleCards = examples.map(ex => ` |
| 383 | <div class="example"> |
| 384 | <div class="example-label">${ex.label}</div> |
| 385 | <div class="example-demo"> |
| 386 | ${ex.code} |
| 387 | </div> |
| 388 | <div class="example-code">${ex.code.replace(/</g, '<').replace(/>/g, '>')}</div> |
| 389 | <div class="example-notes">${ex.notes.replace(/\n/g, '<br>')}</div> |
| 390 | </div>`).join(''); |
| 391 | |
| 392 | return `<!DOCTYPE html> |
| 393 | <html lang="en"> |
| 394 | <head> |
| 395 | <meta charset="UTF-8"> |
| 396 | <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 397 | <title>${name} - Semantic Components</title> |
| 398 | <script src="../semantic-components.js"></script> |
| 399 | <link rel="stylesheet" href="component-docs.css"> |
| 400 | </head> |
| 401 | <body> |
| 402 | <div class="container"> |
| 403 | <!-- Header --> |
| 404 | <div class="header"> |
| 405 | <h1 class="component-name"><${name}></h1> |
| 406 | <p class="tagline">${tagline}</p> |
| 407 | <div class="quick-example"> |
| 408 | ${examples[0]?.code || `<${name}></${name}>`} |
| 409 | </div> |
| 410 | </div> |
| 411 | |
| 412 | <!-- Overview --> |
| 413 | <section class="section"> |
| 414 | <h2 class="section-title">Overview</h2> |
| 415 | <p class="section-description">${description}</p> |
| 416 | </section> |
| 417 | |
| 418 | <!-- Examples --> |
| 419 | <section class="section"> |
| 420 | <h2 class="section-title">Examples</h2> |
| 421 | <div class="grid"> |
| 422 | ${exampleCards} |
| 423 | </div> |
| 424 | </section> |
| 425 | |
| 426 | <!-- Interactive States --> |
| 427 | <section class="section"> |
| 428 | <h2 class="section-title">Interactive States</h2> |
| 429 | <div class="state-showcase"> |
| 430 | ${stateBoxes} |
| 431 | </div> |
| 432 | </section> |
| 433 | |
| 434 | <!-- Properties --> |
| 435 | <section class="section"> |
| 436 | <h2 class="section-title">Properties & Attributes</h2> |
| 437 | <table class="property-table"> |
| 438 | <thead> |
| 439 | <tr> |
| 440 | <th>Attribute</th> |
| 441 | <th>Type</th> |
| 442 | <th>Values</th> |
| 443 | <th>Default</th> |
| 444 | <th>Description</th> |
| 445 | </tr> |
| 446 | </thead> |
| 447 | <tbody> |
| 448 | ${attributeRows} |
| 449 | ${slotRows} |
| 450 | </tbody> |
| 451 | </table> |
| 452 | </section> |
| 453 | |
| 454 | <!-- Events --> |
| 455 | <section class="section"> |
| 456 | <h2 class="section-title">Events</h2> |
| 457 | <table class="property-table"> |
| 458 | <thead> |
| 459 | <tr> |
| 460 | <th>Event</th> |
| 461 | <th>Trigger</th> |
| 462 | <th>Detail</th> |
| 463 | <th>Description</th> |
| 464 | </tr> |
| 465 | </thead> |
| 466 | <tbody> |
| 467 | ${eventRows} |
| 468 | </tbody> |
| 469 | </table> |
| 470 | </section> |
| 471 | </div> |
| 472 | </body> |
| 473 | </html>`; |
| 474 | } |
| 475 | |
| 476 | // Extract CSS to shared stylesheet |
| 477 | function generateSharedCSS() { |
| 478 | return `/* Shared styles for all component documentation pages */ |
| 479 | |
| 480 | * { |
| 481 | margin: 0; |
| 482 | padding: 0; |
| 483 | box-sizing: border-box; |
| 484 | } |
| 485 | |
| 486 | body { |
| 487 | font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif; |
| 488 | background: #000; |
| 489 | color: #fff; |
| 490 | line-height: 1.6; |
| 491 | letter-spacing: 0.015em; |
| 492 | overflow-x: hidden; |
| 493 | } |
| 494 | |
| 495 | .container { |
| 496 | max-width: 1400px; |
| 497 | margin: 0 auto; |
| 498 | padding: 48px 24px; |
| 499 | width: 100%; |
| 500 | box-sizing: border-box; |
| 501 | } |
| 502 | |
| 503 | @media (max-width: 768px) { |
| 504 | .container { |
| 505 | padding: 24px 16px; |
| 506 | max-width: 100%; |
| 507 | } |
| 508 | } |
| 509 | |
| 510 | /* Header */ |
| 511 | .header { |
| 512 | margin-bottom: 64px; |
| 513 | border-bottom: 2px solid #38383a; |
| 514 | padding-bottom: 32px; |
| 515 | } |
| 516 | |
| 517 | .component-name { |
| 518 | font-size: 48px; |
| 519 | font-weight: 900; |
| 520 | color: #409cff; |
| 521 | margin-bottom: 16px; |
| 522 | word-break: break-word; |
| 523 | } |
| 524 | |
| 525 | .tagline { |
| 526 | font-size: 24px; |
| 527 | color: #f0f0f0; /* Improved from #f0f0f0 for 7.0:1 contrast */ |
| 528 | margin-bottom: 24px; |
| 529 | } |
| 530 | |
| 531 | .quick-example { |
| 532 | background: #1c1c1e; |
| 533 | border: 1px solid #38383a; |
| 534 | border-radius: 12px; |
| 535 | padding: 24px; |
| 536 | font-family: 'Monaco', 'Courier New', monospace; |
| 537 | font-size: 14px; |
| 538 | color: #34c759; |
| 539 | overflow-x: auto; |
| 540 | max-width: 100%; |
| 541 | } |
| 542 | |
| 543 | @media (max-width: 768px) { |
| 544 | .component-name { |
| 545 | font-size: 32px; |
| 546 | } |
| 547 | |
| 548 | .tagline { |
| 549 | font-size: 18px; |
| 550 | } |
| 551 | |
| 552 | .quick-example { |
| 553 | font-size: 13px; /* Increased from 12px for better mobile readability */ |
| 554 | padding: 16px; |
| 555 | } |
| 556 | } |
| 557 | |
| 558 | /* Sections */ |
| 559 | .section { |
| 560 | margin-bottom: 80px; |
| 561 | page-break-inside: avoid; |
| 562 | } |
| 563 | |
| 564 | .section-title { |
| 565 | font-size: 32px; |
| 566 | font-weight: 700; |
| 567 | color: #fff; |
| 568 | margin-bottom: 16px; |
| 569 | border-left: 4px solid #409cff; |
| 570 | padding-left: 16px; |
| 571 | } |
| 572 | |
| 573 | .section-description { |
| 574 | font-size: 16px; |
| 575 | color: #f0f0f0; |
| 576 | margin-bottom: 32px; |
| 577 | line-height: 1.8; |
| 578 | } |
| 579 | |
| 580 | /* Grid */ |
| 581 | .grid { |
| 582 | display: grid; |
| 583 | grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); /* Reduced from 300px for better mobile fit */ |
| 584 | gap: 32px; |
| 585 | margin-bottom: 32px; |
| 586 | } |
| 587 | |
| 588 | @media (max-width: 768px) { |
| 589 | .grid { |
| 590 | grid-template-columns: 1fr; |
| 591 | gap: 16px; |
| 592 | } |
| 593 | } |
| 594 | |
| 595 | /* Examples */ |
| 596 | .example { |
| 597 | background: #1c1c1e; |
| 598 | border: 2px solid #38383a; |
| 599 | border-radius: 16px; |
| 600 | padding: 32px; |
| 601 | page-break-inside: avoid; |
| 602 | min-width: 0; /* Prevent grid blowout */ |
| 603 | } |
| 604 | |
| 605 | @media (max-width: 768px) { |
| 606 | .example { |
| 607 | padding: 20px; /* Reduced padding on mobile */ |
| 608 | } |
| 609 | } |
| 610 | |
| 611 | .example-label { |
| 612 | font-size: 14px; |
| 613 | font-weight: 700; |
| 614 | color: #409cff; |
| 615 | text-transform: uppercase; |
| 616 | letter-spacing: 1px; |
| 617 | margin-bottom: 16px; |
| 618 | } |
| 619 | |
| 620 | .example-demo { |
| 621 | margin-bottom: 24px; |
| 622 | min-height: 60px; |
| 623 | display: flex; |
| 624 | align-items: center; |
| 625 | justify-content: center; |
| 626 | } |
| 627 | |
| 628 | .example-code { |
| 629 | background: #000; |
| 630 | border: 1px solid #38383a; |
| 631 | border-radius: 8px; |
| 632 | padding: 16px; |
| 633 | font-family: 'Monaco', 'Courier New', monospace; |
| 634 | font-size: 14px; /* Increased from 12px for better mobile readability */ |
| 635 | color: #34c759; |
| 636 | overflow-x: auto; |
| 637 | margin-bottom: 16px; |
| 638 | } |
| 639 | |
| 640 | .example-notes { |
| 641 | font-size: 14px; /* Increased from 13px for better mobile readability */ |
| 642 | color: #f0f0f0; |
| 643 | line-height: 1.6; |
| 644 | border-top: 1px solid #38383a; |
| 645 | padding-top: 16px; |
| 646 | } |
| 647 | |
| 648 | /* State Showcase */ |
| 649 | .state-showcase { |
| 650 | display: grid; |
| 651 | grid-template-columns: 1fr 1fr; |
| 652 | gap: 24px; |
| 653 | margin-bottom: 32px; |
| 654 | } |
| 655 | |
| 656 | @media (max-width: 768px) { |
| 657 | .state-showcase { |
| 658 | grid-template-columns: 1fr; /* Single column on mobile to prevent overflow */ |
| 659 | } |
| 660 | } |
| 661 | |
| 662 | .state-box { |
| 663 | background: #2c2c2e; |
| 664 | border: 2px solid #38383a; |
| 665 | border-radius: 12px; |
| 666 | padding: 24px; |
| 667 | text-align: center; |
| 668 | min-width: 0; /* Prevent grid blowout */ |
| 669 | } |
| 670 | |
| 671 | .state-label { |
| 672 | font-size: 14px; /* Increased from 12px for better mobile readability */ |
| 673 | font-weight: 700; |
| 674 | color: #f0f0f0; |
| 675 | text-transform: uppercase; |
| 676 | letter-spacing: 1px; |
| 677 | margin-bottom: 16px; |
| 678 | } |
| 679 | |
| 680 | .state-visual { |
| 681 | margin-bottom: 16px; |
| 682 | } |
| 683 | |
| 684 | /* Simulate interactive states visually using CSS custom properties |
| 685 | These pass through shadow DOM boundaries to style the inner button */ |
| 686 | .state-visual.state-hover semantic-action, |
| 687 | .state-visual.state-hover semantic-card, |
| 688 | .state-visual.state-hover semantic-input, |
| 689 | .state-visual.state-hover semantic-modal, |
| 690 | .state-visual.state-hover semantic-adjuster { |
| 691 | --demo-transform: translateY(-2px); |
| 692 | --demo-box-shadow: 0 3px 8px rgba(64, 156, 255, 0.6); |
| 693 | --demo-filter: brightness(1.2); |
| 694 | } |
| 695 | |
| 696 | /* State demos using CSS custom properties that pass through shadow DOM */ |
| 697 | |
| 698 | .state-visual.state-active semantic-action, |
| 699 | .state-visual.state-active semantic-card, |
| 700 | .state-visual.state-active semantic-input { |
| 701 | --demo-transform: scale(0.96) translateY(1px); |
| 702 | --demo-box-shadow: inset 0 2px 6px rgba(0, 0, 0, 0.3); |
| 703 | --demo-filter: brightness(0.85); |
| 704 | } |
| 705 | |
| 706 | .state-visual.state-focus semantic-action, |
| 707 | .state-visual.state-focus semantic-input, |
| 708 | .state-visual.state-focus semantic-card { |
| 709 | --demo-outline: 3px solid #4d9fff; |
| 710 | --demo-outline-offset: 2px; |
| 711 | } |
| 712 | |
| 713 | .state-visual.state-disabled semantic-action, |
| 714 | .state-visual.state-disabled semantic-input, |
| 715 | .state-visual.state-disabled semantic-card, |
| 716 | .state-visual.state-disabled semantic-adjuster { |
| 717 | /* Disabled state works naturally via disabled attribute */ |
| 718 | cursor: not-allowed !important; |
| 719 | } |
| 720 | |
| 721 | .state-description { |
| 722 | font-size: 14px; /* Increased from 13px for better mobile readability */ |
| 723 | color: #f0f0f0; |
| 724 | line-height: 1.6; |
| 725 | } |
| 726 | |
| 727 | /* Property Tables */ |
| 728 | .property-table { |
| 729 | width: 100%; |
| 730 | border-collapse: collapse; |
| 731 | background: #1c1c1e; |
| 732 | border: 2px solid #38383a; |
| 733 | border-radius: 12px; |
| 734 | overflow: hidden; |
| 735 | margin-bottom: 32px; |
| 736 | display: block; /* Allow horizontal scroll on mobile */ |
| 737 | overflow-x: auto; /* Enable horizontal scrolling for wide tables */ |
| 738 | } |
| 739 | |
| 740 | .property-table thead { |
| 741 | background: rgba(64, 156, 255, 0.1); |
| 742 | } |
| 743 | |
| 744 | .property-table th { |
| 745 | padding: 16px; |
| 746 | text-align: left; |
| 747 | font-weight: 700; |
| 748 | color: #409cff; |
| 749 | border-bottom: 2px solid #38383a; |
| 750 | font-size: 14px; /* Ensure readable size */ |
| 751 | } |
| 752 | |
| 753 | .property-table td { |
| 754 | padding: 16px; |
| 755 | border-bottom: 1px solid #38383a; |
| 756 | font-size: 14px; /* Ensure readable size */ |
| 757 | } |
| 758 | |
| 759 | @media (max-width: 768px) { |
| 760 | .property-table th, |
| 761 | .property-table td { |
| 762 | padding: 12px 8px; /* Reduced padding on mobile */ |
| 763 | font-size: 13px; /* Slightly smaller but still readable */ |
| 764 | } |
| 765 | } |
| 766 | |
| 767 | .property-table tr:last-child td { |
| 768 | border-bottom: none; |
| 769 | } |
| 770 | |
| 771 | .prop-name { |
| 772 | font-family: 'Monaco', monospace; |
| 773 | color: #34c759; |
| 774 | font-weight: 600; |
| 775 | } |
| 776 | |
| 777 | .prop-type { |
| 778 | font-family: 'Monaco', monospace; |
| 779 | color: #ff9500; |
| 780 | font-size: 13px; |
| 781 | } |
| 782 | |
| 783 | .prop-values { |
| 784 | font-family: 'Monaco', monospace; |
| 785 | color: #409cff; |
| 786 | font-size: 13px; |
| 787 | } |
| 788 | |
| 789 | /* Print Styles */ |
| 790 | @media print { |
| 791 | body { |
| 792 | background: white; |
| 793 | color: black; |
| 794 | } |
| 795 | |
| 796 | .example { |
| 797 | border: 2px solid #ccc; |
| 798 | page-break-inside: avoid; |
| 799 | } |
| 800 | |
| 801 | .section { |
| 802 | page-break-after: always; |
| 803 | } |
| 804 | } |
| 805 | `; |
| 806 | } |
| 807 | |
| 808 | // Main execution |
| 809 | function generateDocs() { |
| 810 | const docsDir = path.join(__dirname, 'docs'); |
| 811 | |
| 812 | // Create docs directory if it doesn't exist |
| 813 | if (!fs.existsSync(docsDir)) { |
| 814 | fs.mkdirSync(docsDir); |
| 815 | } |
| 816 | |
| 817 | // Generate shared CSS |
| 818 | fs.writeFileSync( |
| 819 | path.join(docsDir, 'component-docs.css'), |
| 820 | generateSharedCSS() |
| 821 | ); |
| 822 | console.log('✓ Generated component-docs.css'); |
| 823 | |
| 824 | // Generate docs for each component |
| 825 | for (const [componentName, componentData] of Object.entries(components)) { |
| 826 | const html = generateComponentDoc(componentData); |
| 827 | const filename = `${componentName}.html`; |
| 828 | fs.writeFileSync(path.join(docsDir, filename), html); |
| 829 | console.log(`✓ Generated ${filename}`); |
| 830 | } |
| 831 | |
| 832 | console.log('\n✅ Documentation generation complete!'); |
| 833 | console.log(`Generated ${Object.keys(components).length} component pages in docs/`); |
| 834 | } |
| 835 | |
| 836 | // Run if called directly |
| 837 | if (require.main === module) { |
| 838 | generateDocs(); |
| 839 | } |
| 840 | |
| 841 | module.exports = { generateDocs, components }; |