diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 4873a01..476f57a 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -21,7 +21,7 @@ jobs: cache: 'npm' - name: Install dependencies - run: npm ci + run: npm i - name: Build run: npm run build @@ -31,4 +31,4 @@ jobs: if: github.ref == 'refs/heads/main' with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./docs + publish_dir: ./dist diff --git a/.gitignore b/.gitignore index 179b568..4378d70 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .idea .cache +dist node_modules diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index 4b1c401..0000000 --- a/docs/index.html +++ /dev/null @@ -1,4 +0,0 @@ -Web Platform Fundamentals: Building with Native HTML

🚀 Web Platform Fundamentals

Master native HTML capabilities and progressive enhancement patterns. This guide demonstrates how leveraging built-in browser features reduces complexity, improves performance, and creates more maintainable codebases.

🎯 Progressive Disclosure Patterns

JavaScript-Dependent Implementation COMPLEX

⚠️ Implementation Overhead: Manual ARIA state management, keyboard event handling, focus management, and screen reader compatibility.
Custom collapsible implementations require comprehensive event handling, state synchronization across components, and careful attention to accessibility requirements including proper ARIA attributes and keyboard navigation patterns.
Managing state across multiple collapsible sections introduces complexity in event coordination, memory management, and performance optimization, particularly when dealing with dynamic content loading.

❌ Architecture Complexity:

  • Event delegation and memory leak prevention
  • ARIA state synchronization and keyboard trap management
  • Cross-browser compatibility and polyfill requirements

Native Details/Summary Elements ZERO-JS

🎯 Platform Integration: Built-in ARIA semantics, keyboard navigation, screen reader support, and browser-optimized animations.
Semantic HTML Architecture
The HTML5 details/summary pattern provides declarative progressive disclosure without JavaScript dependencies. Browser engines handle state management, accessibility, and user interaction patterns according to platform conventions.
Progressive Enhancement Benefits
Starting with functional HTML ensures graceful degradation across all environments. CSS and JavaScript become enhancement layers rather than functional requirements, improving reliability and reducing technical debt.
Performance Characteristics
Native elements eliminate bundle size overhead, reduce runtime memory consumption, and leverage browser optimizations unavailable to custom implementations. Hardware acceleration and efficient event handling come built-in.

✅ Platform Advantages:

  • Zero JavaScript footprint with full accessibility compliance
  • Browser-native performance optimizations and hardware acceleration
  • Consistent cross-platform behavior with no maintenance overhead

🪟 Modal Dialog Patterns

Custom Modal Implementation BRITTLE

⚠️ Critical Requirements: Focus trapping, inert background content, ESC key handling, backdrop click management, and ARIA modal semantics.

Custom Modal Architecture

This approach requires managing the modal stack, preventing background interaction, coordinating focus management, and ensuring proper cleanup to avoid memory leaks and accessibility violations.

Critical Issue: Background content remains accessible to screen readers and keyboard navigation without explicit inert management.

❌ Implementation Challenges:

  • Focus trap implementation and restoration complexity
  • Modal stack management and z-index coordination
  • Event cleanup and memory leak prevention

Native Dialog Element ROBUST

🎯 Built-in Capabilities: Automatic focus trapping, inert background management, ESC key support, and proper modal semantics.

Native Dialog Element

The HTML5 dialog element provides robust modal functionality with automatic focus management, backdrop interaction handling, and proper accessibility semantics built into the browser engine.

Key Advantage: Background content becomes automatically inert, preventing interaction and screen reader access without additional implementation.

✅ Engine-Level Features:

  • Automatic focus trapping with proper restoration
  • Built-in ESC key handling and backdrop click support
  • Modal semantics and inert background management

📝 Constraint Validation Patterns

Custom Validation Logic FRAGILE

⚠️ Validation Complexity: Custom error messaging, timing coordination, accessibility announcements, and server-client synchronization.
Invalid email format detected
UUID format required: 8-4-4-4-12 hex digits

❌ Validation Brittleness:

  • Regex patterns miss edge cases and internationalization
  • Error timing and accessibility announcement coordination
  • Client-server validation drift and synchronization issues

Constraint Validation API SPEC-COMPLIANT

🎯 Standards-Based: Automatic error announcements, internationalized messages, and CSS pseudo-class integration.

✅ Specification Compliance:

  • RFC-compliant validation patterns with internationalization
  • Automatic error messaging in user's preferred language
  • CSS pseudo-classes (:valid, :invalid) for styling integration

📊 Progress Indication Patterns

Custom Progress Implementation SEMANTIC-VOID

⚠️ Accessibility Gap: No semantic meaning without explicit ARIA implementation and screen reader progress announcements.

Build Progress: 0%

❌ Semantic Limitations:

  • No inherent semantic meaning for assistive technologies
  • Manual ARIA live region management for progress updates
  • Custom animation performance and value interpolation

Native Progress Element SEMANTIC

🎯 Semantic Integration: Built-in progress role, automatic ARIA value announcements, and indeterminate state support.

Compilation Progress

75% complete

Indeterminate Operation (processing)

Processing dependencies...

Dynamic Progress: 0%

0%

✅ Semantic Advantages:

  • Built-in progress role with automatic value announcements
  • Indeterminate state support for unknown duration operations
  • Platform-optimized rendering and animation performance

📅 Temporal Input Patterns

Custom Date Picker HEAVYWEIGHT

⚠️ Implementation Scope: Calendar widget architecture, keyboard navigation, internationalization, timezone handling, and mobile touch optimization.

❌ Implementation Overhead:

  • Large JavaScript libraries and complex calendar logic
  • Mobile UX inconsistency with platform date pickers
  • Internationalization complexity and timezone edge cases

Native Temporal Inputs PLATFORM-NATIVE

🎯 OS Integration: Platform-consistent UI, automatic keyboard navigation, built-in validation, and internationalization support.

✅ Platform Integration:

  • Zero-bundle impact with native OS picker integration
  • Automatic validation and internationalization support
  • Consistent UX aligned with platform conventions

🔍 Autocomplete Patterns

Custom Autocomplete INTERACTION-HEAVY

⚠️ Interaction Complexity: Dropdown positioning, keyboard navigation, ARIA combobox implementation, and mobile touch handling.

❌ Interaction Management:

  • Complex ARIA combobox implementation and state management
  • Dropdown positioning and viewport collision detection
  • Mobile keyboard optimization and touch event handling

Native Datalist Element ZERO-CONFIG

🎯 Native Combobox: Built-in ARIA combobox semantics, keyboard navigation, and platform-consistent interaction patterns.

✅ Zero-Configuration Benefits:

  • Native combobox semantics with automatic ARIA support
  • Platform-consistent keyboard and interaction patterns
  • Form validation integration and graceful degradation

Platform-First Development

Native HTML elements represent years of browser engineering, accessibility research, and web standards evolution. They provide robust functionality with minimal implementation overhead and maximum compatibility.

The Progressive Enhancement Approach:

Leverage browser engines rather than reimplementing their functionality. Your codebase will be more maintainable, your users will have better experiences.

The most sophisticated architecture is often the one that uses existing, well-tested components. Native HTML elements provide decades of optimization and accessibility engineering—build upon this foundation rather than around it.
\ No newline at end of file diff --git a/docs/main.082e2b9e.js b/docs/main.082e2b9e.js deleted file mode 100644 index 27f98ba..0000000 --- a/docs/main.082e2b9e.js +++ /dev/null @@ -1,188 +0,0 @@ -// modules are defined as an array -// [ module function, map of requires ] -// -// map of requires is short require name -> numeric require -// -// anything defined in a previous bundle is accessed via the -// orig method which is the require for previous bundles -parcelRequire = (function (modules, cache, entry, globalName) { - // Save the require from previous bundle to this closure if any - var previousRequire = typeof parcelRequire === 'function' && parcelRequire; - var nodeRequire = typeof require === 'function' && require; - - function newRequire(name, jumped) { - if (!cache[name]) { - if (!modules[name]) { - // if we cannot find the module within our internal map or - // cache jump to the current global require ie. the last bundle - // that was added to the page. - var currentRequire = typeof parcelRequire === 'function' && parcelRequire; - if (!jumped && currentRequire) { - return currentRequire(name, true); - } - - // If there are other bundles on this page the require from the - // previous one is saved to 'previousRequire'. Repeat this as - // many times as there are bundles until the module is found or - // we exhaust the require chain. - if (previousRequire) { - return previousRequire(name, true); - } - - // Try the node require function if it exists. - if (nodeRequire && typeof name === 'string') { - return nodeRequire(name); - } - - var err = new Error('Cannot find module \'' + name + '\''); - err.code = 'MODULE_NOT_FOUND'; - throw err; - } - - localRequire.resolve = resolve; - localRequire.cache = {}; - - var module = cache[name] = new newRequire.Module(name); - - modules[name][0].call(module.exports, localRequire, module, module.exports, this); - } - - return cache[name].exports; - - function localRequire(x){ - return newRequire(localRequire.resolve(x)); - } - - function resolve(x){ - return modules[name][1][x] || x; - } - } - - function Module(moduleName) { - this.id = moduleName; - this.bundle = newRequire; - this.exports = {}; - } - - newRequire.isParcelRequire = true; - newRequire.Module = Module; - newRequire.modules = modules; - newRequire.cache = cache; - newRequire.parent = previousRequire; - newRequire.register = function (id, exports) { - modules[id] = [function (require, module) { - module.exports = exports; - }, {}]; - }; - - var error; - for (var i = 0; i < entry.length; i++) { - try { - newRequire(entry[i]); - } catch (e) { - // Save first error but execute all entries - if (!error) { - error = e; - } - } - } - - if (entry.length) { - // Expose entry point to Node, AMD or browser globals - // Based on https://github.com/ForbesLindesay/umd/blob/master/template.js - var mainExports = newRequire(entry[entry.length - 1]); - - // CommonJS - if (typeof exports === "object" && typeof module !== "undefined") { - module.exports = mainExports; - - // RequireJS - } else if (typeof define === "function" && define.amd) { - define(function () { - return mainExports; - }); - - //