searchlight_highlight 0.2.2

A pure Dart reimplementation of Orama's standalone highlight package.

Searchlight Highlight

Searchlight Highlight is a pure Dart reimplementation of Orama's standalone highlight package shape for Searchlight, the independent Dart reimplementation of Orama's in-memory search and indexing model.

Companion core package:

• searchlight provides indexing, querying, and persistence for the content you highlight here.

It exposes the same core helper surface audited from Orama Highlight:

• Highlight
• highlightStrategy
• HighlightOptions
• HighlightStrategy
• Position

Status

searchlight_highlight matches the audited Orama Highlight source contract:

• stateful Highlight class
• highlight(text, searchTerm) returns this
• inclusive Position(start, end) offsets
• HTML getter for rendered highlighted markup
• trim(trimLength, [ellipsis]) behavior that re-highlights the trimmed text
• highlightStrategy.WHOLE_WORD_MATCH
• highlightStrategy.PARTIAL_MATCH
• highlightStrategy.PARTIAL_MATCH_FULL_WORD

Important package-shape note:

• Orama Highlight is a standalone helper package, not a create-time plugin
• searchlight_highlight matches that package shape directly
• it does not require the Searchlight extension system
• it is the canonical highlight package for the Searchlight ecosystem

Platform Support

searchlight_highlight is a pure Dart package:

• no Flutter dependency
• no dart:io requirement
• works anywhere plain Dart strings work, including Flutter apps

Installation

dart pub add searchlight_highlight

# or from a Flutter app
flutter pub add searchlight_highlight

Quick Start

import 'package:searchlight_highlight/searchlight_highlight.dart';

void main() {
  final highlighted = Highlight().highlight(
    'The quick brown fox jumps over the lazy dog',
    'brown fox',
  );

  print(highlighted.positions);
  print(highlighted.HTML);
  // trim() re-highlights the trimmed excerpt on the same stateful instance.
  print(highlighted.trim(18));
}

Output:

[Position(start: 10, end: 14), Position(start: 16, end: 18)]
The quick <mark class="orama-highlight">brown</mark> <mark class="orama-highlight">fox</mark> jumps over the lazy dog
...he quick <mark class="orama-highlight">brown</mark> <mark class="orama-highlight">fox</mark>...

Configuration

HighlightOptions mirrors the audited Orama source:

final highlighter = Highlight(
  const HighlightOptions(
    caseSensitive: false,
    strategy: 'partialMatch',
    HTMLTag: 'mark',
    // This is the package default.
    CSSClass: 'orama-highlight',
  ),
);

The supported strategy constants are:

• highlightStrategy.WHOLE_WORD_MATCH
• highlightStrategy.PARTIAL_MATCH
• highlightStrategy.PARTIAL_MATCH_FULL_WORD

Example with a full-word partial strategy:

import 'package:searchlight_highlight/searchlight_highlight.dart';

void main() {
  final highlighted = Highlight(
    HighlightOptions(
      strategy: highlightStrategy.PARTIAL_MATCH_FULL_WORD,
    ),
  ).highlight(
    'The quick brown fox jumps over the lazy dog',
    'fo umps ve',
  );

  print(highlighted.HTML);
}

Relationship To Searchlight Packages

Choose dependencies based on the job:

• only text highlighting: install searchlight_highlight
• Searchlight search plus post-search excerpts/highlights: install searchlight and searchlight_highlight
• Markdown or HTML extraction plus Searchlight search plus highlights: install searchlight_parsedoc, searchlight, and searchlight_highlight

searchlight_highlight owns:

• strict parity with the audited Orama standalone package API
• inclusive Position offsets
• HTML-markup output via HTML
• Orama-style stateful trimming semantics

searchlight owns:

• index creation
• document storage
• query execution
• persistence

searchlight_parsedoc owns:

• Markdown and HTML extraction into Searchlight-ready records
• folder-based document ingestion helpers for supported VM targets

This package does not own:

• index creation
• document parsing
• Flutter widgets

Flutter apps typically use Position ranges to build TextSpan trees or highlighted preview widgets.

HTML safety note:

• HTML is a convenience string built from the original source text plus the configured wrapper tag
• it does not escape or sanitize the underlying text for you
• if you render that output in an HTML context, sanitize according to your app requirements

Important offset rule:

• Position.end is inclusive
• Flutter substring logic should therefore use end + 1

Flutter Rendering Pattern

searchlight_highlight stays pure Dart, but Flutter rendering is straightforward because the package returns plain strings plus Position ranges.

For highlighted inline text, build TextSpan ranges from positions:

import 'package:flutter/material.dart';
import 'package:searchlight_highlight/searchlight_highlight.dart';

List<InlineSpan> buildHighlightSpans(
  BuildContext context,
  String text,
  List<Position> positions,
) {
  if (positions.isEmpty) {
    return [TextSpan(text: text)];
  }

  final spans = <InlineSpan>[];
  var cursor = 0;

  for (final position in positions) {
    final start = position.start;
    final endExclusive = position.end + 1;

    if (start > cursor) {
      spans.add(TextSpan(text: text.substring(cursor, start)));
    }

    spans.add(
      TextSpan(
        text: text.substring(start, endExclusive),
        style: const TextStyle(fontWeight: FontWeight.bold),
      ),
    );
    cursor = endExclusive;
  }

  if (cursor < text.length) {
    spans.add(TextSpan(text: text.substring(cursor)));
  }

  return spans;
}

For body/source rendering, keep responsibilities separate:

• use searchlight_highlight for the match positions or HTML output
• use flutter_markdown_plus when you want rendered Markdown source bodies

MarkdownBody(data: record.displayBody);

The Flutter validation app under example/ shows both patterns in one place.

Example

The repository includes:

• a console sample under example/searchlight_highlight_example.dart
• a Flutter validation app under example/

The Flutter app proves two paths:

• standalone searchlight_highlight usage
• searchlight_parsedoc + searchlight + searchlight_highlight working together over live .md and .html folders

Current example-app constraints:

• the live folder-ingestion flow is desktop-only in the current app
• the example app overrides the HTML class to searchlight-highlight; the package default remains orama-highlight

Run it with:

dart run example/searchlight_highlight_example.dart

For the Flutter app:

cd example
flutter pub get
flutter run -d macos

Inside the app:

• use Standalone highlight to inspect positions, HTML, and trim()
• use Parsedoc + highlight to choose a local folder and verify parsed Markdown or HTML records are searchable and highlight correctly

Additional Information

This package intentionally keeps the audited Orama package boundary narrow. Potential follow-up helpers such as Flutter TextSpan adapters or richer snippet builders should only be added after strict parity is complete and explicitly documented as additive behavior.