How lordmendes/liquidbrain works
Project type and purpose
• LiquidBrain is an open-source, framework-agnostic JavaScript/TypeScript library (packaged via npm and UMD) that provides autocomplete suggestions for <input>, <textarea>, and contenteditable elements.
• It exposes two main classes—LiquidBrainEngine (business logic) and LiquidBrainUI (DOM/UI integration)—and ships with styles (CSS) plus a UMD build for direct browser use.
File structure
• Top-level files:
• package.json, tsconfig.json, rollup.config.cjs — configuration for package metadata, TypeScript compiler, and bundling.
• readme.md — project documentation.
• .gitignore — VCS ignores.
• Examples/vanilla+html — demo of UMD build usage.
• src/ directory:
• LiquidBrainEngine.ts — core suggestion engine.
• LiquidBrainUI.ts — UI integration layer (event listeners, modal management).
• index.ts — public API exports.
• types.ts — shared type definitions.
• liquidbrain.css — default styling.
• build artifacts (not shown) are generated via Rollup according to rollup.config.cjs.
README for architectural insights
• The README describes separation of concerns: Engine handles data-model parsing, suggestion fetching, insertion logic; UI handles DOM attachment, rendering suggestions, and user interaction.
• It highlights optional custom rendering and customizable markers.
a. Main components:
1. Consumer Application — any web page or framework using LiquidBrain.
2. LiquidBrainUI (Browser/UI layer) — attaches to an input element, listens for keystrokes, triggers engine calls, and renders suggestion modal.
3. LiquidBrainEngine (Logic layer) — processes the data model, resolves nested properties, returns suggestion list, and computes insertion.
4. Data Model — JSON or JS object provided by the consumer describing suggestion hierarchy.
5. CSS Styles — default .liquidbrain-modal, .liquidbrain-suggestion-item, etc.
6. Bundler / Build Pipeline — Rollup + TypeScript, produces ESM, CJS, and UMD artifacts.
7. npm Registry / Direct Download — distribution endpoints.
b. Relationships and data flow:
• Consumer App → (init) → LiquidBrainUI: passes model, inputElement, markers, optional customRenderer.
• LiquidBrainUI → (on keystroke) → LiquidBrainEngine.handleFetchSuggestionsFromValue(value, cursor).
• LiquidBrainEngine → (suggestions) → LiquidBrainUI → (render) → DOM modal styled by CSS.
• UI → (on suggestion select) → Engine.insertSuggestion → UI updates input value and cursor.
• Bundler takes src/ → compiles/transpiles TS → outputs dist/ (ESM/CJS/UMD) → published to npm or distributed via direct download.
c. Architectural patterns and principles:
• Separation of concerns: UI vs. logic.
• Publish-subscribe callbacks for value changes and suggestions.
• Plugin-style extensibility: custom renderer hook.
• Framework-agnostic design promotes portability.
d. Relevant technologies:
• TypeScript for strong types.
• Rollup for bundling.
• Plain DOM APIs, no framework dependencies.
• CSS modular file for default styling.