genx-dataos

v1.0.0-alpha.2

Published

16 days ago

Declarative web development platform - enhance HTML with powerful functionality through simple attributes

Downloads

0High
0Medium
0Low

declarative html attributes accessibility formatting wcag aria a11y progressive-enhancement framework-agnostic vanilla-js web-components no-framework

genX

The Tailwind of Frontend Behavior

Tailwind gave us utility-first CSS. genX gives us utility-first JavaScript.

Inspired by htmx's philosophy that HTML should be powerful enough on its own, genX extends this idea to client-side behavior. Just as Tailwind lets you style elements with class="bg-blue-500 text-center", genX lets you add behavior with fx-format="currency" or dx-draggable="card". No JavaScript to write. No frameworks to learn. Just HTML attributes.

<!-- Format as currency - no JS needed -->
<span fx-format="currency">1299.99</span>  →  $1,299.99

<!-- Make draggable - no JS needed -->
<div dx-draggable="card">Drag me</div>

<!-- Add loading state - no JS needed -->
<button lx-loading="true">Saving...</button>

| | | | | | |---|---|---|---|---| | Features | Architecture | Quick Start | Modules | fmtX Examples | | tableX Examples | Documentation | Testing | Privacy & Security | Browser Support | | Installation | Contributing | Project Status | License | Links |

New to genX? Start with the User Guide for a beginner-friendly introduction with step-by-step examples.

Features

Declarative - Control everything with HTML attributes (fx-*, ax-*, dx-*, etc.)
Lightweight - ~1KB bootloader, modules loaded on-demand
Privacy-First - 100% client-side processing, no tracking, no external calls
Accessible - WCAG 2.1 AA compliant made easy
Fast - Designed for <16ms operations (60 FPS)
Framework Agnostic - Works with vanilla HTML, React, Vue, Angular, htmx, or anything else

Architecture

Universal Bootloader

Scans DOM for genX attributes
Dynamically loads only required modules
Watches for dynamic content via centralized MutationObserver
Powered by domx for efficient DOM observation

Centralized DOM Observation

genX uses domx-bridge to provide a single, shared MutationObserver for all modules. Instead of each module (fmtX, accX, bindX, etc.) creating its own observer, they all subscribe through domx-bridge which delegates to domx. This architecture:

Eliminates duplication - One observer instead of 6+
Improves performance - Single observer with filtered callbacks
Reduces memory - No redundant DOM watchers
Fallback support - Works without domx via native MutationObserver

Module Design

Pure functional JavaScript - No classes, no complex state
Polymorphic processing - Handles multiple input/output formats
Client-side only - Privacy-preserving, no external calls
Performance-first - All operations target <16ms (60 FPS)

See Architecture Documentation for technical specifications.

Quick Start

View the Live Demo

See all modules in action: genX Interactive Demo

Installation

Option 1: CDN (Easiest)

<!-- Add to your HTML <head> with defer attribute -->
<script src="https://cdn.genx.software/v1/bootloader.js" defer></script>

Option 2: Self-Hosted

Copy genX files to your static directory:

# Clone the repository
git clone https://github.com/adamzwasserman/genX.git

# Copy src files to your project's static/js directory
cp genX/src/*.js your-project/static/js/

Add to your HTML <head> with defer attribute:

<script src="/static/js/bootloader.js" defer></script>

Important: Always use the defer attribute to ensure genX loads after the DOM is parsed without blocking page rendering.

Basic Usage

<!-- Currency Formatting -->
<span fx-format="currency" fx-currency="USD">1299.99</span>
<!-- Displays: $1,299.99 -->

<!-- Phone Number Formatting -->
<input type="tel" fx-format="phone" fx-phone-format="us" value="5551234567">
<!-- Displays: (555) 123-4567 -->

<!-- Date Formatting -->
<span fx-format="date" fx-date-format="long">2024-03-15</span>
<!-- Displays: March 15, 2024 -->

<!-- Percentage with Decimal Control -->
<span fx-format="percent" fx-decimals="2">0.1567</span>
<!-- Displays: 15.67% -->

Modules

| Module | Purpose | Prefix | Status | Documentation | |--------|---------|--------|--------|---------------| | fmtX | Text formatting (currency, dates, numbers, phones) | fx-* | ✅ v1.0 | Architecture | | accX | Accessibility (WCAG, ARIA) | ax-* | ✅ v1.0 | Architecture | | loadX | Loading states, skeletons, spinners | lx-* | ✅ v1.0 | Architecture | | navX | Navigation & routing | nx-* | ✅ v1.0 | Architecture | | dragX | Drag & drop | dx-* | ✅ v1.0 | Architecture | | bindX | Reactive data binding | bx-* | ✅ v1.0 | Architecture | | tableX | Enhanced tables | tx-* | ✅ v1.0 | Architecture | | smartX | Auto-detection formatting | sx-* | ✅ v1.0 | - |

fmtX Examples

The fmtX module supports comprehensive formatting with input type selectors:

Currency Formatting

<!-- Basic currency -->
<span fx-format="currency" fx-currency="USD">42.50</span>

<!-- Input type selector: dollars or cents -->
<span fx-format="currency" fx-currency="USD" fx-input-type="cents">4250</span>
<!-- Input: 4250 cents → Output: $42.50 -->

Phone Numbers

Supports multiple US formats and international numbers:

<!-- US formats -->
<span fx-format="phone" fx-phone-format="us">5551234567</span>
<!-- Output: (555) 123-4567 -->

<span fx-format="phone" fx-phone-format="us-dash">5551234567</span>
<!-- Output: 555-123-4567 -->

<span fx-format="phone" fx-phone-format="us-dot">5551234567</span>
<!-- Output: 555.123.4567 -->

<!-- International format -->
<span fx-format="phone" fx-phone-format="intl">+44 20 7946 0958</span>
<!-- Output: +44 20 7946 0958 (normalized) -->

Input format flexibility: Accepts raw digits, pre-formatted numbers, numbers with spaces, or international format. Gracefully handles:

10-digit US numbers
11-digit numbers with country code
Already-formatted numbers (with parentheses, dashes, or dots)
Extra spaces (stripped automatically)
European/international numbers (preserved as-is)

Date & Time

<!-- Date input types: iso, unix, ms -->
<span fx-format="date" fx-date-format="long" fx-input-type="unix">1710518400</span>

<!-- Relative time (always UTC input) -->
<span fx-format="relative">2024-03-15T12:00:00Z</span>
<!-- Output: "2 hours ago" or "in 3 days" -->

Numbers & Percentages

<!-- Percentage with decimal control -->
<span fx-format="percent" fx-decimals="2">0.1567</span>
<!-- Output: 15.67% -->

<!-- Compact numbers (auto-scales: K, M, B, T) -->
<span fx-format="compact">1500000</span>
<!-- Output: 1.5M -->

<!-- File sizes (auto-scales: KB, MB, GB, TB) -->
<span fx-format="filesize">1073741824</span>
<!-- Output: 1.00 GB -->

<!-- Decimal precision control -->
<span fx-format="decimal" fx-decimals="3">3.14159</span>
<!-- Output: 3.142 -->

tableX Examples

The tableX module enhances HTML tables with sorting, filtering, pagination, and responsive layouts—all through declarative attributes.

Column Sorting

<!-- Basic sortable table -->
<table>
  <thead>
    <tr>
      <th class="tx-sortable">Name</th>
      <th class="tx-sortable">Age</th>
      <th class="tx-sortable">Join Date</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Alice</td>
      <td>30</td>
      <td>2024-01-15</td>
    </tr>
    <tr>
      <td>Bob</td>
      <td>25</td>
      <td>2024-02-20</td>
    </tr>
  </tbody>
</table>

How it works:

Click a column header to sort ascending
Click again to sort descending
Click a third time to clear sort (restore original order)
Automatically detects data types (string, number, date)
Shift+click to add secondary/tertiary sorts (multi-column sorting)

Multi-Column Sorting:

Click "Name" to sort by name
Shift+click "Age" to add secondary sort (now sorted by name, then age)
Shift+click "Join Date" to add tertiary sort
Visual priority badges (①②③) show sort order

Data Type Override:

<!-- Force date interpretation with data-value -->
<td data-value="2024-01-15">January 15, 2024</td>

Accessibility:

Keyboard navigation (Tab to headers, Enter/Space to sort)
ARIA live regions announce sort changes
Screen reader friendly sort indicators
Focus styles for keyboard users

Performance:

Sorts 100 rows in <10ms
Sorts 1,000 rows in <100ms
All operations target 60 FPS (<16ms)

Client-Side Pagination

<!-- Basic pagination (default: 10 rows per page) -->
<table tx-paginate="true">
  <thead>
    <tr>
      <th>Product</th>
      <th>Price</th>
      <th>Stock</th>
    </tr>
  </thead>
  <tbody>
    <!-- 100 rows here -->
  </tbody>
</table>

<!-- Custom page size -->
<table tx-paginate="true" tx-per-page="25">
  <!-- ... -->
</table>

How it works:

Automatically hides rows not on current page
Shows Previous/Next navigation buttons
Displays current page info (e.g., "Page 2 of 10")
Keyboard accessible (Tab to buttons, Enter/Space to navigate)
ARIA live regions announce page changes
Previous button disabled on first page
Next button disabled on last page

Combine with sorting:

<!-- Sortable and paginated table -->
<table tx-sortable tx-paginate="true" tx-per-page="20">
  <thead>
    <tr>
      <th class="tx-sortable">Name</th>
      <th class="tx-sortable">Date</th>
      <th class="tx-sortable">Status</th>
    </tr>
  </thead>
  <tbody>
    <!-- Many rows here -->
  </tbody>
</table>

Pagination controls are automatically inserted after the table with Previous, page info, and Next buttons.

Responsive Table Layouts

tableX provides three responsive strategies for mobile-friendly tables, all implemented through CSS-only patterns:

Scroll Mode

Horizontal scrolling with sticky first column for important data:

<table tx-responsive="scroll">
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th>Phone</th>
      <th>Address</th>
      <th>Status</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Alice Smith</td>
      <td>[email protected]</td>
      <td>(555) 123-4567</td>
      <td>123 Main St, City, State 12345</td>
      <td>Active</td>
    </tr>
    <!-- More rows -->
  </tbody>
</table>

How it works:

Table scrolls horizontally on narrow screens
First column (e.g., Name) stays sticky/visible while scrolling
No data hidden, all columns accessible
Best for tables where all data must be viewable

Cards Mode

Stacks rows as mobile-friendly cards on small screens:

<table tx-responsive="cards">
  <thead>
    <tr>
      <th>Product</th>
      <th>Price</th>
      <th>Stock</th>
      <th>Category</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td data-label="Product">Widget Pro</td>
      <td data-label="Price">$29.99</td>
      <td data-label="Stock">150</td>
      <td data-label="Category">Electronics</td>
    </tr>
    <!-- More rows -->
  </tbody>
</table>

How it works:

On screens <768px, rows become stacked cards
Each cell displays with its column label (from data-label)
Headers are hidden automatically
Cards have borders, padding, and proper spacing
Best for tables with moderate number of columns (3-6)

Important: Add data-label attributes to each cell matching the column header text.

Priority Mode

Progressively hides less important columns as screen narrows:

<table tx-responsive="priority">
  <thead>
    <tr>
      <th class="tx-priority-1">Name</th>
      <th class="tx-priority-2">Email</th>
      <th class="tx-priority-3">Phone</th>
      <th class="tx-priority-4">Department</th>
      <th class="tx-priority-5">Location</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td class="tx-priority-1">Alice Smith</td>
      <td class="tx-priority-2">[email protected]</td>
      <td class="tx-priority-3">(555) 123-4567</td>
      <td class="tx-priority-4">Engineering</td>
      <td class="tx-priority-5">Building A</td>
    </tr>
    <!-- More rows -->
  </tbody>
</table>

How it works:

Columns with tx-priority-1 are always visible (most important)
tx-priority-5 columns hide first (at <1024px)
tx-priority-4 hide next (at <900px)
tx-priority-3 hide next (at <768px)
tx-priority-2 hide last (at <600px)
tx-priority-1 always remain visible
Best for tables with many columns where some data is optional

Breakpoints:

<600px: Only priority-1 columns visible
<768px: Priority-1 and priority-2 visible
<900px: Priority-1, 2, and 3 visible
<1024px: Priority-1, 2, 3, and 4 visible
≥1024px: All columns visible

Combine with sorting and pagination:

<table tx-responsive="cards" tx-paginate="true" tx-per-page="20">
  <thead>
    <tr>
      <th class="tx-sortable">Product</th>
      <th class="tx-sortable">Price</th>
      <th class="tx-sortable">Stock</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td data-label="Product">Widget</td>
      <td data-label="Price">$29.99</td>
      <td data-label="Stock">150</td>
    </tr>
    <!-- Many rows -->
  </tbody>
</table>

All three responsive modes work together with sorting and pagination seamlessly.

Table Filtering

tableX provides client-side filtering with live search, debounced input, and multi-column support:

Basic Filtering

<!-- Basic filterable table (searches all columns) -->
<table tx-filterable>
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th>Department</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Alice Smith</td>
      <td>[email protected]</td>
      <td>Engineering</td>
    </tr>
    <tr>
      <td>Bob Jones</td>
      <td>[email protected]</td>
      <td>Sales</td>
    </tr>
    <!-- More rows -->
  </tbody>
</table>

How it works:

Automatically generates search input above table
Live filtering as you type (debounced for performance)
Case-insensitive search across all columns
Shows result count (e.g., "5 rows found")
ARIA live regions announce filter results
Works seamlessly with sorting and pagination

Multi-Column Filtering

Filter only specific columns by name:

<!-- Only search Name and Email columns -->
<table tx-filterable tx-filter-columns="Name,Email">
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th>Department</th>
      <th>Status</th>
    </tr>
  </thead>
  <tbody>
    <!-- Rows -->
  </tbody>
</table>

The tx-filter-columns attribute accepts a comma-separated list of column header names (case-insensitive matching).

Custom Debounce Delay

Control how long to wait after typing stops before filtering:

<!-- Wait 500ms after typing stops (default: 300ms) -->
<table tx-filterable tx-filter-debounce="500">
  <!-- ... -->
</table>

Performance:

Default 300ms debounce prevents excessive filtering during typing
Filters 1,000 rows in <16ms
No page reload or server requests

Combine with Sorting and Pagination

All tableX features work together:

<table tx-filterable tx-filter-columns="Name,Email" tx-paginate="true" tx-per-page="20">
  <thead>
    <tr>
      <th class="tx-sortable">Name</th>
      <th class="tx-sortable">Email</th>
      <th class="tx-sortable">Join Date</th>
      <th>Department</th>
    </tr>
  </thead>
  <tbody>
    <!-- Many rows -->
  </tbody>
</table>

Behavior:

Filter narrows visible rows
Sorting applies to filtered results only
Pagination shows filtered rows across pages
Result count updates as you filter

Accessibility:

Search input has proper label and aria-label
ARIA live regions announce filter results
Keyboard accessible (Tab to input, type to filter)
Screen reader friendly result counts

Accessibility (WCAG 2.1 AA Compliant)

tableX is designed for full accessibility compliance:

Keyboard Navigation

Tab: Navigate between sortable headers, pagination buttons, and filter input
Enter/Space: Sort column (when focused on sortable header)
Shift+Enter/Space: Add secondary/tertiary sort (multi-column)
All interactive elements are keyboard accessible

ARIA Support

Sortable Headers:
- role="columnheader" on all sortable headers
- scope="col" for proper column association
- aria-sort="ascending|descending|none" indicates current sort state
- tabindex="0" makes headers keyboard focusable
Pagination:
- role="navigation" with aria-label="Table pagination"
- aria-disabled="true|false" on Previous/Next buttons
- aria-live="polite" announces page changes
Filtering:
- aria-label="Filter table rows" on search input
- role="status" with aria-live="polite" for result announcements
- Hidden rows marked with aria-hidden="true"
Screen Reader Announcements:
- Sort changes: "Sorted by [column] [direction], [priority]"
- Filter results: "Showing X of Y rows"
- Page changes: "Page X of Y"

Visual Accessibility

Focus Indicators: Visible outline on all focusable elements
High Contrast Mode: Increased opacity and bold indicators
Color Independence: Sort indicators use symbols (▲▼), not just color
Dark Mode: Full support via prefers-color-scheme: dark

Screen Reader Support

Semantic HTML table structure (<table>, <thead>, <tbody>)
Column headers with proper scope attributes
Live regions announce dynamic changes
Hidden elements properly marked with aria-hidden
All controls have accessible names and descriptions

Testing

tableX meets WCAG 2.1 AA standards for:

1.4.3 Contrast (Minimum): All text meets 4.5:1 ratio
2.1.1 Keyboard: Full keyboard accessibility
2.4.3 Focus Order: Logical tab order
2.4.7 Focus Visible: Clear focus indicators
3.2.4 Consistent Identification: Consistent UI patterns
4.1.2 Name, Role, Value: Proper ARIA implementation

Automated Testing: Compatible with axe-core and WAVE for accessibility auditing.

Documentation

User Guide - Beginner-friendly introduction with practical examples
Live Demo - Interactive examples of all modules
Architecture Specs - Technical documentation for each module
Implementation Plans - Development roadmaps and completion reports
Testing Guide - BDD/TDD testing framework

Testing

genX uses a comprehensive BDD/TDD testing framework:

Cucumber BDD - Human-readable feature specifications
Playwright - Browser automation for UI testing
Jest - Unit tests for pure functions
Manual Test Suite - Visual verification in tests/manual/

# Run all tests
npm test

# Run browser tests
npm run test:browser

# Run unit tests
npm run test:unit

# Run BDD tests
npm run test:bdd

Privacy & Security

100% Client-Side - No data sent to servers, ever
No Tracking - No analytics, no telemetry, no cookies
XSS Protected - Safe DOM manipulation, no innerHTML
CSP Compliant - No eval, no inline scripts
GDPR Compliant - No PII collection

Browser Support

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

Requires modern JavaScript features: ES6+, Proxy, MutationObserver, async/await

Installation Options

Option 1: Direct Script Tag

<script src="https://cdn.genx.software/v1/bootloader.js"></script>

Option 2: Local Development

git clone https://github.com/adamzwasserman/genX.git
cd genX
# Include src/bootloader.js in your project

Option 3: npm (Coming Soon)

npm install @genx/core

Contributing

Contributions welcome! This project follows:

BDD/TDD - All features require tests (Cucumber + Playwright + Jest)
Architecture-first - Specifications before implementation
Performance budget - <16ms operations, <1KB bootloader
Privacy-first - No external calls, no tracking

See implementation plans in docs/implementation/ for current development status.

Project Status

Version: 1.0.0-alpha Modules Complete: fmtX, accX, loadX, navX, dragX, tableX, bindX, smartX In Development: (None) Planned: (None - all core modules complete)

Recent Updates:

✅ tableX v1.0 - Column sorting with multi-column support (shift+click)
✅ Phone number formatting with comprehensive US/international support
✅ Input type selectors for dates, currency, percentages
✅ Decimal precision control for percentages and numbers
✅ Comprehensive BDD test suite with Cucumber/Playwright/Jest
✅ Manual test files for visual verification
✅ Updated demo page with clean, minimal styling

Development Acknowledgement

This project was developed with extensive use of AI-assisted coding tools. While the architecture, specifications, and testing have been carefully designed and validated, not all code has been manually reviewed line-by-line. Users should conduct their own security audits and testing before using genX in production environments.

License

MIT License - See LICENSE for details

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

genX

The Tailwind of Frontend Behavior

Table of Contents

Features

Architecture

Universal Bootloader

Centralized DOM Observation

Module Design

Quick Start

View the Live Demo

Installation

Option 1: CDN (Easiest)

Option 2: Self-Hosted

Basic Usage

Modules

fmtX Examples

Currency Formatting

Phone Numbers

Date & Time

Numbers & Percentages

tableX Examples

Column Sorting

Client-Side Pagination

Responsive Table Layouts

Scroll Mode

Cards Mode

Priority Mode

Table Filtering

Basic Filtering

Multi-Column Filtering

Custom Debounce Delay

Combine with Sorting and Pagination

Accessibility (WCAG 2.1 AA Compliant)

Keyboard Navigation

ARIA Support

Visual Accessibility

Screen Reader Support

Testing

Documentation

Testing

Privacy & Security

Browser Support

Installation Options

Option 1: Direct Script Tag

Option 2: Local Development

Option 3: npm (Coming Soon)

Contributing

Project Status

Development Acknowledgement

License

Links