🚀 ln-ashlar

Unified frontend library for LiveNetworks projects. Delivering a high-performance harmony between server-rendered HTML, semantic SCSS mixins, and attribute-driven, zero-initialization vanilla JS components. Built with zero dependencies for maximum speed, longevity, and security.

🏛️ The DOM-First Paradigm (Why ln-ashlar?)

Modern web development has fallen into a trap of excessive complexity. ln-ashlar is an architectural statement: the browser works with HTML, not a Virtual DOM.

Instead of downloading megabytes of JavaScript, compiling in runtime, and displaying empty "skeleton screens" while waiting for cascading API waterfalls, ln-ashlar champions a DOM-First, progressive, and local-first approach:

1. Server-Rendered HTML: Your backend (Laravel, Go, Rails, etc.) delivers complete, semantic, indexable HTML. Fast to paint, SEO-friendly, and accessible in milliseconds.
2. Zero-Initialization JS: Modular interactivity is driven by standard HTML attributes (data-ln-modal, data-ln-filter, data-ln-store). A native MutationObserver registers and activates components automatically. No new Component() or init() boilerplate required.
3. Pure SCSS Styling via @include: HTML remains semantic, describing what the element is. SCSS mixins describe how it looks. Visual styling is fully decoupled from markup.
4. Zero Dependencies: 100% immune to npm supply chain attacks and package obsolescence. Built exclusively on eternal, backward-compatible W3C web standards.

[!TIP] 📖 Read the complete engineering manifesto!
For a detailed historical analysis of processing cycles, performance (Skeleton Screens vs. IndexedDB cache), the obsolescence issues of SPA frameworks, and security CVE risks with npm, read our complete Architectural Philosophy.

JS-First (React / Vue / Angular) vs. DOM-First with ln-ashlar

| Architectural Challenge | Mainstream JS-First (SPA) | DOM-First with ln-ashlar | | :--- | :--- | :--- | | Primary Rendering | Client-side via heavy Virtual DOM compilation. | Server-side via standard HTML. | | Binding & Config | Inside JS files via imports, props, and states. | Directly in HTML via semantic data-ln attributes. | | Network Overhead | Megabytes of JS, hundreds of transitive npm packages. | Zero-Dependency (0 npm packages at runtime). | | Security Risks | High (transitive dependency supply chain vulnerability). | Zero. Native vanilla JS communicating directly with Web APIs. | | Longevity & Support | EOL cycles every 6-18 months (breaking framework upgrades). | 100% Stable (backed by permanent W3C web standards). | | Progressive Adoption | All-or-nothing SPA deployment. | Progressive: drop a single ln-data-table onto any layout. |

🧭 Four Core Philosophy Principles

Four strict principles drive every technical decision in this library:

1. HTML describes WHAT, not HOW — Use semantic elements only. No presentational or utility classes in markup (avoid grid-4, text-secondary, flex). Visual changes happen in SCSS, never in HTML.
2. Style via @include on semantic selectors — Projects write #user-table { @include table-base; }, not <table class="table table-striped">. The selector describes the element; the mixin describes how it looks.
3. Every color is a CSS variable — Always use hsl(var(--color-primary)), never hardcoded hex codes like #2737a1. This makes the entire design system fully customizable at any scope via simple variable overrides.
4. JS is attribute-driven, zero init — Interactivity is declared via attributes (data-ln-modal, data-ln-filter, data-ln-toggle). A single MutationObserver registers, binds, and cleans up instances automatically.

⚡ Quick Start

ln-ashlar is a source-only package. Import SCSS and JS directly and let your project's bundler compile them.

1. Install via npm

npm install ln-ashlar

Import source files into your main entries:

// main.scss - Import SCSS tokens, mixins, and defaults
@use 'ln-ashlar/scss/ln-ashlar.scss';

// main.js - Import and auto-initialize JS components
import 'ln-ashlar/js/index.js';

2. Install as a Git Submodule (Alternative)

git submodule add .../ln-ashlar.git resources/ln-ashlar

Then reference the submodule paths:

@use 'resources/ln-ashlar/scss/ln-ashlar.scss';

import 'resources/ln-ashlar/js/index.js';

3. Build & Watch (For Library Demos Only)

If you are developing inside this repository, compile the static demo assets:

npm run build   # Produces demo/dist/ln-ashlar.{css,js,iife.js} + compiles HTML demo pages
npm run dev     # Watch mode (automatic compilation on SCSS or JS changes)

Note: The demo/dist/ artifact exists solely for the demo pages. Product consumers should always bundle from source.

📐 Core Architecture Specifications

Deep architectural blueprints detailing the engine driving ln-ashlar.

| Specification | Contents | |:---|:---| | 📖 Architecture Philosophy | The DOM-First engineering manifesto detailing computing cycles, framework EOL risks, and performance. | | 🔄 Data Flow Architecture | Rules governing how data moves. Splits responsibilities into four isolated concerns: Data (ln-store), Render (ln-data-table), Submit (ln-form), and Validate (ln-validate). Details the optimistic and offline write pipeline with a comprehensive Mermaid flow diagram. | | 🧭 3-Tier Local-First Storage Specs | Technical reference for decoupling storage caches (ln-data-store), network gateways (ln-*-connector), and data transformations (ln-mapper) under a single parent Data Coordinator (ln-data-coordinator). | | ⚡ Reactive Architecture Reference | Blueprint on how components manage internal state using Proxy traps (reactiveState and deepReactive), batched microtask rendering, DOM bindings (fill, renderList), and attribute-to-state bridges. | | 📐 Design System Specifications | Complete styling specs covering CSS Custom Properties, layout grids, buttons, responsive breakpoints, typography hierarchies, dark mode theming, and icons. | | 🛡️ Security & Threat Mitigation | Deep architectural security analysis covering Web Crypto API encryption-at-rest, strict CSP compliance (no dynamic eval), sensitive DOM attribute protections, and AJAX XSS sanitization filters. | | 🧠 Architect Overview Guide | The master developer guide introducing the DOM-First doctrine, component inventories, override architectures, and new project integration pipelines. |

📚 General Documentation Index

For detailed manual instructions, properties, attributes, and events of individual components:

• 📚 Complete Documentation Index — The master roadmap containing direct links to usage guides (js/ln-*/README.md) and internal architecture sheets (docs/js/*.md) for every module.

CSS Layer Reference

| Guide | Scope | |---|---| | 🎨 Design Tokens | All CSS custom properties: colors, spacing, borders, typography scale, z-index. | | 🎛️ Mixins Reference | Extensive list of all SCSS @include recipes available for semantic styling. | | 📑 Forms | Declarative layout patterns, spacing, grids, and input validation states. | | 📇 Cards | Custom properties and mixins for basic card structures and section headers. | | 📊 Tables | Tabular layout patterns, striped themes, and responsive screen-overflow. | | 🗺️ Navigation | Semantic navigation bar mixins, sidebar layouts, and collapsible drawer states. | | 📏 Layout | Flexbox, grid utilities, container query states, and collapsible selectors. | | 📁 Sections | Visual separation blocks and responsive layout containers. | | 🧭 Breadcrumbs | Horizontal navigation trail styling mixins. | | 📦 Container Queries | Mobile-first component layouts reacting to the width of their parent container. |

JS Components Reference

| Component | Usage Guide (HTML Attributes / Events) | Technical Architecture (State / Render Loops) | |---|---|---| | Core Utilities | — | 🛠️ Core helpers reference | | Component Pattern | — | 🧠 JS Component Design Guide | | SVG Icons | 🏷️ Icon SVG Sprite Reference | 🌐 On-Demand CDN routing & injection | | Toggle | 🎚️ ln-toggle docs | 📄 toggle architecture | | Accordion | 📂 ln-accordion docs | 📄 accordion architecture | | Modal | 🪟 ln-modal docs | 📄 modal architecture | | Tabs | 🔖 ln-tabs docs | 📄 tabs architecture | | Toast | 🔔 ln-toast docs | 📄 toast architecture | | Dropdown | 🔽 ln-dropdown docs | 📄 dropdown architecture | | Popover | 💬 ln-popover docs | 📄 popover architecture | | Tooltip (JS) | 💬 ln-tooltip docs | 📄 tooltip architecture | | Navigation | 🗺️ ln-nav docs | 📄 nav architecture | | Filter | 🔍 ln-filter docs | 📄 filter architecture | | Search | 🔎 ln-search docs | 📄 search architecture | | Table | 📊 ln-table docs | 📄 table architecture | | Table Sort | 📊 ln-table docs (Sort) | 📄 table-sort architecture | | Data Table | 📊 ln-data-table docs | 📄 data-table architecture | | Sortable | 🔃 ln-sortable docs | 📄 sortable architecture | | Progress | 📈 ln-progress docs | 📄 progress architecture | | Circular Progress | 📈 ln-circular-progress docs | 📄 circular-progress architecture | | Link | 🔗 ln-link docs | 📄 link architecture | | Confirm | ⚠️ ln-confirm docs | 📄 confirm architecture | | Upload | 📤 ln-upload docs | 📄 upload architecture | | AJAX | 🔄 ln-ajax docs | 📄 ajax architecture | | HTTP | — | 📄 http service architecture | | Store | 🗄️ ln-store docs | 📄 store cache architecture | | API Connector | 🔌 ln-api-connector docs | — | | CouchDB Connector | 🔌 ln-couchdb-connector docs | 📄 couchdb-connector architecture | | Form | 📝 ln-form docs | 📄 form lifecycle architecture | | Validate | ⚠️ ln-validate docs | 📄 validate architecture | | Time | 🕒 ln-time docs | 📄 time architecture | | Autosave | 💾 ln-autosave docs | 📄 autosave architecture | | Autoresize | ↕️ ln-autoresize docs | 📄 autoresize architecture | | Translations | 🗣️ ln-translations docs | 📄 translations architecture | | External Links | 🌐 ln-external-links docs | 📄 external-links architecture |

🖥️ Interactive Demo Site

ln-ashlar ships with a complete local dashboard environment inside demo/admin/. The demo is itself a project consuming ln-ashlar, showing real-world layout structures, component setups, and customized semantic SCSS:

demo/admin/index.html       ← Dashboard Overview (cards, navigation, timelines)
demo/admin/mixins.html      ← Interactive visual catalog of all SCSS mixins
demo/admin/icons.html       ← Live SVG sprite icons browser (with live search/filter)
demo/admin/{component}.html ← Standalone interactive playground pages for JS components