LiquidBrain

A lightweight, framework-agnostic autocomplete library for input fields, textareas, and contenteditable elements. LiquidBrain provides dynamic suggestions based on a given data model, allowing for nested property access and customizable markers.

Table of Contents

• LiquidBrain
  • Table of Contents
  • Features
  • Installation
    • Using NPM (Recommended)
    • Using Yarn
    • Direct Download
  • Usage
    • Initialization
      • Importing the Library
    • Basic Example
  • Options
  • API Reference
    • LiquidBrainEngine
      • Constructor
      • Methods
    • LiquidBrainUI
      • Constructor
      • Methods
  • Examples
    • Vanilla JavaScript Example
  • Custom Renderer
  • CSS Styles
  • Contributing
    • Development Setup
  • License
  • Contact
  • Acknowledgments

Features

• Framework-Agnostic: Works with plain JavaScript, React, Angular, or any other framework.
• Flexible Input Support: Supports <input>, <textarea>, and contenteditable elements.
• Nested Suggestions: Handles nested data models for deep property access.
• Customizable Markers: Define your own start and end markers for triggering autocomplete.
• Custom Rendering: Optionally provide a custom renderer for the suggestions modal.
• Keyboard Navigation: Navigate suggestions using arrow keys and select with Enter.

Installation

Using NPM (Recommended)

npm install liquidbrain

Using Yarn

yarn add liquidbrain

Direct Download

Download the liquidbrain.umd.js file from the dist directory and include it in your project.

Usage

Initialization

Importing the Library

ES Modules:

import { LiquidBrainUI } from 'liquidbrain';

CommonJS:

const { LiquidBrainUI } = require('liquidbrain');

UMD (Browser):

<script src="path/to/liquidbrain.umd.js"></script>
<script>
  const { LiquidBrainUI } = LiquidBrain;
</script>

Basic Example

// Define your data model
const model = {
  user: {
    name: 'John Doe',
    email: '[email protected]',
    address: {
      city: 'Anytown',
      country: 'USA',
    },
  },
  company: {
    name: 'Example Corp',
    industry: 'Technology',
  },
};

// Get the input element
const inputElement = document.getElementById('myInput');

// Initialize LiquidBrainUI
const ui = new LiquidBrainUI({
  model,
  inputElement,
  markers: { start: '{{', end: '}}' }, // Optional
});

Options

The LiquidBrainUI constructor accepts an options object with the following properties:

• model (Model, required): The data model used for generating suggestions.
• inputElement (HTMLElement, required): The element to attach the autocomplete functionality to (<input>, <textarea>, or contenteditable element).
• markers ({ start: string; end: string }, optional): Custom start and end markers for triggering autocomplete. Defaults to { start: '{{', end: '}}' }.
• customRenderer (Function, optional): A function to customize the rendering of the suggestions modal.

API Reference

LiquidBrainEngine

The LiquidBrainEngine class manages autocomplete suggestions, text insertion, and cursor positioning.

Constructor

new LiquidBrainEngine(
  model: Model,
  onValueChange: (newValue: string) => void,
  onSuggestionsChange: (newSuggestions: Suggestion[]) => void,
  markers?: { start: string; end: string }
)

Parameters:

• model: The data model for generating suggestions.
• onValueChange: Callback function when the input value changes.
• onSuggestionsChange: Callback function when the suggestions list changes.
• markers: Custom markers for triggering autocomplete.

Methods

• handleFetchSuggestionsFromValue(value: string, cursor: number): void

  Fetches suggestions based on the current input value and cursor position.

• insertSuggestion(suggestion: Suggestion, value: string, cursor: number): { newValue: string; newCursor: number }

  Inserts the selected suggestion into the input value.

• isCaretWithinMarkers(value: string, cursor: number): boolean

  Checks if the caret is within the defined markers.

• getCurrentSuggestions(): Suggestion[]

  Returns the current list of suggestions.

LiquidBrainUI

The LiquidBrainUI class handles the user interface, integrating the engine with the DOM.

Constructor

new LiquidBrainUI(options: LiquidBrainUIOptions)

LiquidBrainUIOptions:

• model: The data model for generating suggestions.
• inputElement: The target input element (<input>, <textarea>, or contenteditable).
• markers: Custom markers for triggering autocomplete.
• customRenderer: Function to customize the suggestions modal rendering.

Methods

• destroy(): void

  Cleans up event listeners and DOM elements created by the instance.

Examples

Vanilla JavaScript Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>LiquidBrain Example</title>
  <link rel="stylesheet" href="path/to/liquidbrain.css">
</head>
<body>
  <input type="text" id="myInput" placeholder="Type here...">

  <script src="path/to/liquidbrain.umd.js"></script>
  <script>
    const { LiquidBrainUI } = LiquidBrain;

    const model = {
      user: {
        name: 'Alice',
        email: '[email protected]',
      },
      date: '2023-10-10',
    };

    const inputElement = document.getElementById('myInput');

    const ui = new LiquidBrainUI({
      model,
      inputElement,
      markers: { start: '{{', end: '}}' },
    });
  </script>
</body>
</html>

Custom Renderer

You can provide a custom renderer function to change how the suggestions modal is displayed.

const ui = new LiquidBrainUI({
  model,
  inputElement,
  customRenderer: (modalElement, suggestions, selectedIndex, applySuggestion) => {
    // Clear existing content
    modalElement.innerHTML = '';

    // Create your custom suggestions list
    suggestions.forEach((suggestion, index) => {
      const item = document.createElement('div');
      item.textContent = suggestion.template;
      item.className = 'custom-suggestion-item';

      if (index === selectedIndex) {
        item.classList.add('selected');
      }

      item.addEventListener('click', () => applySuggestion(suggestion));

      modalElement.appendChild(item);
    });
  },
});

CSS Styles

Include the following CSS styles to style the default suggestions modal. Adjust as needed for your application's design.

/* liquidbrain.css */

.liquidbrain-modal {
  min-width: 250px;
  background-color: #fff;
  box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1);
  border-radius: 4px;
  font-family: 'Roboto', sans-serif;
  z-index: 1000;
}

.liquidbrain-suggestion-list {
  list-style: none;
  margin: 0;
  padding: 0;
}

.liquidbrain-suggestion-item {
  display: flex;
  flex-direction: column;
  padding: 10px 16px;
  cursor: pointer;
  border-bottom: 1px solid #e0e0e0;
}

.liquidbrain-suggestion-item:last-child {
  border-bottom: none;
}

.liquidbrain-suggestion-item:hover,
.liquidbrain-suggestion-item.selected {
  background-color: #f5f5f5;
}

.primary-text {
  font-size: 16px;
  color: rgba(0, 0, 0, 0.87);
}

.secondary-text {
  font-size: 14px;
  color: rgba(0, 0, 0, 0.54);
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub to contribute to this project.

Development Setup

1. Clone the Repository

   git clone https://github.com/LordMendes/liquidbrain.git

2. Install Dependencies

   cd liquidbrain
   npm install

3. Build the Library

   npm run build

4. Run Tests (if any)

   npm test

License

This project is licensed under the MIT License.

Contact

For questions or support, please open an issue on GitHub

Acknowledgments

• Inspired by the need for a simple, flexible autocomplete solution.