GitHub - AnnexLabs/AnnexUI: MIT licensed UI library for Typesense.

AnnexUI

AnnexUI is a MIT licensed UI library for Typesense. It's designed to be a clean, UX focused library that gets developers up and running in a few minutes. Include a link to the CDN-hosted JavaScript bundle, set your Typesense cluster settings, and then press ⌘k to see Annex up and running.

It's currently in early-development.

Quick links

1. Quick demos
2. Quick preview
3. Quick intro
4. Quick start
5. Config
6. Attribute-based events
7. Events
8. Methods
9. Templates
10. Additional notes

Quick demos

1. Inline layout: https://annexsearch.com/#inline-demo-01
2. Modal layout: https://annexsearch.com/#modal-demo-01
3. Left panel layout: https://annexsearch.com/#panel-left-demo-01
4. Right panel layout: https://annexsearch.com/#panel-right-demo-01
5. Inline layout (dark mode): https://annexsearch.com/#inline-demo-02
6. Multiple modal layouts: https://annexsearch.com/#modal-demo-03
7. Inline layout (using sku-v0.1.0 templates): https://annexsearch.com/#inline-demo-05

Quick preview

Quick intro

Annex uses Web Components to encapsulate and restrict JavaScript and CSS scope. The fundamental concepts to understand are:

• The UI will be encapsulated within a <annex-search-widget> HTML tag
  • In docs, this will often be referenced as the $annexSearchWidget variable
• This web component exposes a number of methods that developers can use to interact with it (e.g. show, hide, focus, etc)

💪 Out the box, Annex supports the following:

• Four (4) different layouts ('inline', 'modal', 'panel-left' and 'panel-right')
• Dark mode
• Responsive layouts
• Event handling

🎨 Style considerations:

• There are currently 65+ CSS variables that can be overriden
• These control layouts, dimensions, colors, fonts and more

🔒 Privacy and data considerations:

• No data is stored in cookies or localStorage
• Queries are only sent to your Typesense cluster; no middleware is present
• Images are base64-encoded and not requested remotely
• The remote CDN used is jsDelivr

⚡️ Performance considerations:

• Annex currently employs a "Last in, first out" approach to queries
  • This means that if users type quickly, previous searches will be aborted to lower server and bandwidth burden
• Analytics can be facilitate through Events

Quick start

Below you'll find a few lines to get up and running quickly (remember to swap in your Typesense cluster settings).

<script
    type="text/javascript"
    src="https://cdn.jsdelivr.net/gh/AnnexLabs/AnnexUI@0.1.14-stable/dist/bundle.min.js"
    defer></script>
<script type="text/javascript">
    document.addEventListener('DOMContentLoaded', function() {
        let $annexSearchWidget = document.createElement('annex-search-widget');
        $annexSearchWidget.setMutator('typesenseSearchResponse', function(typesenseSearchRequest) {
            let hits = typesenseSearchRequest.getResponse().hits;
            for (let hit of hits) {
                hit.document.uri = 'https://' + (hit.document.hostname) + (hit.document.relativeURL);
                hit.document.imageUrl = hit.document.thumbnailURL;
            }
        });
        $annexSearchWidget.setConfig({
            chips: {
                idle: ['aws', 'fotos', 'layers', 'google', 'figma']
            },
            cluster: {
                apiKey: '606o4DjqwBhFNZ2NKgSiqFsqdMNCbcKx',
                collectionName: 'prod:::tpclwpqz62hq:::crawlerResourceSearch:::v0.1.0',
                hostname: 'b3487cx0hrdu1y6kp-1.a1.typesense.net',
                presetName: 'prod:::tcprkee8nnvp:::crawlerResourceSearch:::v0.1.0',
            },
            keyboardShortcut: '⌘k',
            layout: 'modal',
        });
        $annexSearchWidget.mount();
    });
</script>

Config

Below you'll find a high-level breakdown of configuration options that can be changed. See Config overriding for details on how to do so.

Config overriding

Below are examples showing how configuration options can be set. Worth noting is the flexibility around the key (e.g. can contain a . as a delimter).

$('annex-search-widget').setConfig('$container', document.body);
$('annex-search-widget').setConfig('searchOptions.snippet_threshold', 20);
$('annex-search-widget').setConfig('searchOptions', {
    snippet_threshold: 20
});

Attribute-based events

Below is a list of supported attributes, which when found on an element, will trigger behaviour against the related web component.

Notes:

1. When there is a single web component on the page, the id does not need to be specified in the attribute value
2. When there are multiple web components on the page, the id must be specified in the attribute value
3. Not all layouts support all interactions. For example, an inline $annexSearchWidget cannot be "shown" or "hidden"

Behaviour

Examples (without id)

<a href="#test" data-annex-search="clear">clear the $annexSearchWidget $input</a>
<a href="#test" data-annex-search="disable">disable the $annexSearchWidget</a>
<a href="#test" data-annex-search="enable">enable the $annexSearchWidget</a>
<a href="#test" data-annex-search="focus">focus on the $annexSearchWidget</a>
<a href="#test" data-annex-search="hide">hide the $annexSearchWidget</a>
<a href="#test" data-annex-search-query="search query">show the $annexSearchWidget, insert query and search</a>
<a href="#test" data-annex-search="show">show the $annexSearchWidget</a>
<a href="#test" data-annex-search="toggle">toggle the $annexSearchWidget</a>

Examples (with id)

<a href="#test" data-annex-search="{id}:clear">clear the $annexSearchWidget $input</a>
<a href="#test" data-annex-search="{id}:disable">disable on the $annexSearchWidget</a>
<a href="#test" data-annex-search="{id}:enable">enable on the $annexSearchWidget</a>
<a href="#test" data-annex-search="{id}:focus">focus on the $annexSearchWidget</a>
<a href="#test" data-annex-search="{id}:hide">hide the $annexSearchWidget</a>
<a href="#test" data-annex-search-query="{id}:search query">show the $annexSearchWidget, insert query and search</a>
<a href="#test" data-annex-search="{id}:show">show the $annexSearchWidget</a>
<a href="#test" data-annex-search="{id}:toggle">toggle the $annexSearchWidget</a>

Events

Events can be processed either through the config options set via setConfig or via native event listeners (e.g. $annexSearchWidget.addEventListener('result.click', handler)). Below you'll find a list of supported events.

When events are processed through native event listeners, arguments are accessible via the event.detail property.

Example "native" event handling

$('annex-search-widget').addEventListener('root.show', function(customEvent) {
    console.log(customEvent);
    console.log(customEvent.detail);
});

Methods

Below you'll find methods that can be called against an $annexSearchWidget reference. While you'll find other public events available when inspecting the element, only the ones below are currently supported.

Templates

While Annex does it's best to work (to some degree) "out of the box", any meaningful implementation will require developers to define their own templates.

In practice, this means passing in String values for the different web component states (along with defining your own styles).

This part of Annex is a work-in-progress, and more documentation will be added soon, however until then use the table below as a guide to the available template keys that can be overridden.

Additional notes

Below are some additional notes that may prove useful to developers. Feel free to open a PR on this README.md file with anything else you think would be useful to others.

Styling (using vars)

While docs related to styling will come soon, below you'll see a quick example of how styling can be executed against an Annex instance.

<style type="text/css">
    annex-search-widget {
        --annex-search-show-panel-duration: 2000ms;
    }
    annex-search-widget::part(result-content-price) {
        background-color: rgba(0, 0, 0, 0.60);
        color: #ffffff;
    }
    @media (prefers-color-scheme: dark) {
        annex-search-widget::part(result-content-price) {
            background-color: #ffffff;
            color: rgba(0, 0, 0, 0.60);
        }
    }
</style>

Vendors / Dependencies

Currently, the only 3rd party vendor included in Annex is Lodash v4.17.21. Lodash is used to facilitate more robust templating logic.

This minification of vendors / dependencies is by design, in large part to lower the likelihood of supply chain attacks.

Preset without config options

The code below shows the simplest example of Annex. By specifying a presetName value, your Typesense cluster knows how to perform the query. Along with that, the default config options (e.g. '⌘k' for the keyboard shortcut, layout being 'modal', etc.) are good enough to get going.

This does assume your Typesense collection schema is "simple enough" that Annex can determine what the title, body and URL of the result ought to be (during rendering).

<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/AnnexLabs/AnnexUI@0.1.14-stable/dist/bundle.min.js" defer></script>
<script type="text/javascript">
    document.addEventListener('DOMContentLoaded', function() {
        let $annexSearchWidget = document.createElement('annex-search-widget');
        $annexSearchWidget.setConfig({
            cluster: {
                apiKey: '606o4DjqwBhFNZ2NKgSiqFsqdMNCbcKx',
                collectionName: 'prod:::tpclwpqz62hq:::crawlerResourceSearch:::v0.1.0',
                hostname: 'b3487cx0hrdu1y6kp-1.a1.typesense.net',
                presetName: 'prod:::tcprkee8nnvp:::crawlerResourceSearch:::v0.1.0',
            }
        });
        $annexSearchWidget.mount();
    });
</script>

Edge cases considered

• High-resolution monitors that immediately ought to trigger a loadMore flow (because there's not scrollbar)
• Aborting Typesense cluster queries when the search input value changes
• Prevention of mobile zooming when the search input is focused on

Releases

Below are a command-notes that are helpful to the author during version-bumping. Namely, to cd into the directory (after version strings have been changed), building the dist-files, commit, tagging and pushing the tag.

Thereafter a release can be created via /releases.

• cd TurtlePHP/application/vendors/submodules/AnnexUI/
• ./scripts/dist.sh
• git add . && git commit -m "Version bump" && git push
• git tag -a 0.1.14-stable -m "Release based tag"
• git push origin 0.1.14-stable