🚀 ln-ashlar

Unified, zero-dependency frontend framework for both Server-Rendered (SSR) & Client-Side SPA applications. Delivering a high-performance harmony between server-rendered HTML or REST/JSON APIs, semantic SCSS mixins, client-side routing, and attribute-driven, zero-initialization vanilla JS components. Built with zero runtime dependencies for maximum speed, longevity, and security.

🌐 Live Interactive Demo: ashlar.live.net.mk

🏛️ The Dual-Core DOM-First Paradigm (SSR + Client-Side SPA)

ln-ashlar is built on a DOM-First architecture. The browser works directly with native DOM standards, not a heavy Virtual DOM compilation layer.

Whether your architecture relies on Server-Rendered HTML (Laravel, Go, Django, Rails) or Client-Side SPAs consuming REST/JSON APIs, ln-ashlar provides first-class support for both paradigms:

1. 🌐 Server-Rendered HTML (SSR Mode)

• Progressive HTML Enhancement: Your backend delivers complete, semantic, indexable HTML.
• Instant First Paint: Fast to render, SEO-friendly, and accessible in milliseconds.
• Zero Boilerplate: HTML elements auto-activate via attributes (data-ln-modal, data-ln-filter, data-ln-data-store) backed by a native MutationObserver.

2. ⚡ Client-Side Single-Page Applications (SPA / JSON Mode)

• Built-in SPA Router (ln-router): Full client-side routing with dynamic parameters (/users/:id), catch-all paths (*), atomic region swapping (replaceChildren), and cancelable navigation intercepts (ln-router:before-navigate).
• Compound Hash-State Codec (hash.js): Deep linking and overlay state tracking (#tab:settings&modal:42) that preserves browser Back/Forward navigation without page reloads.
• JSON API Data Layer (ln-http, ln-api-connector, ln-store): Native async JSON client with abort control, queueing, and 3-Tier local storage (Memory + IndexedDB/localStorage).
• Client-Side Reactive Rendering (lnCore.renderList & reactiveState): Declaratively render and bind JSON API payloads into <template> nodes with Proxy-backed reactive state updates without Virtual DOM overhead.
• Modular Authoring (spa-starter/): Out-of-the-box SPA scaffold supporting co-located view modules (App.defineView()) and session-long modules (App.defineModule()).

[!NOTE] Runtime Icon CDN Dependency: While ln-ashlar has zero runtime npm package dependencies, the ln-icon component fetches SVG icons dynamically from jsDelivr (Tabler Icons) or a custom CDN URL. Once fetched, they are stored in localStorage so subsequent page views load instantly and work offline. If the client is offline and localStorage is empty, icon requests will fail silently and not display.

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

Heavy Virtual-DOM (React / Vue / Angular) vs. DOM-First ln-ashlar

| Architectural Dimension | Heavy Virtual-DOM (React / Vue / Angular) | DOM-First ln-ashlar (SSR or SPA) | | :--- | :--- | :--- | | Execution Paradigm | Heavy Virtual DOM compilation layer in memory. | Native W3C DOM APIs (MutationObserver, Custom Attributes). | | Application Architecture | SPA only (requires Next.js/Nuxt for SSR). | Dual Mode: Built-in Client-Side SPA (ln-router + spa-starter) AND SSR Mode. | | Data Sources | REST / GraphQL JSON APIs. | Both REST / JSON APIs (ln-http, renderList) AND Server HTML. | | Dependencies | Megabytes of JS, hundreds of npm packages. | Zero Dependencies (0 npm packages at runtime). | | Security Risks | High (transitive dependency supply chain risks). | Zero supply-chain vulnerabilities. | | Longevity & Support | EOL breaking upgrades every 6-18 months. | 100% Stable (built on eternal W3C browser standards). | | Progressive Adoption | All-or-nothing SPA deployment. | Progressive: drop a single ln-table or ln-router onto any page. |

🧭 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 @livenetworks/ashlar

Import source files into your main entries:

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

// main.js - Import and auto-initialize JS components
import '@livenetworks/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-data-store + ln-data-coordinator), Render (ln-table), Submit (ln-form), and Validate (ln-validate). Details the parallel fan-out write pipeline (optimistic cache write + offline queue) 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 the same-origin AJAX fragment trust boundary. | | 🧠 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 each module's usage guide and architecture reference, both in js/ln-*/README.md.

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 | | Sort | ⇅ ln-sort docs | 📄 sort 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-data-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