analytics/PlausibleWeb.Live.Components.ComboBox.html
2024-01-23 09:24:50 +00:00

477 lines
22 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="ExDoc v0.31.1">
<meta name="project" content="Plausible v0.0.1">
<title>PlausibleWeb.Live.Components.ComboBox — Plausible v0.0.1</title>
<link rel="stylesheet" href="dist/html-elixir-FM2CSD74.css" />
<script src="dist/handlebars.runtime-NWIB6V2M.js"></script>
<script src="dist/handlebars.templates-43PMFBC7.js"></script>
<script src="dist/sidebar_items-244BB8AE.js"></script>
<script src="docs_config.js"></script>
<script async src="dist/html-L4O5OK2K.js"></script>
</head>
<body data-type="modules" class="page-module">
<script>
try {
var settings = JSON.parse(localStorage.getItem('ex_doc:settings') || '{}');
if (settings.theme === 'dark' ||
((settings.theme === 'system' || settings.theme == null) &&
window.matchMedia('(prefers-color-scheme: dark)').matches)
) {
document.body.classList.add('dark')
}
} catch (error) { }
</script>
<div class="main">
<button id="sidebar-menu" class="sidebar-button sidebar-toggle" aria-label="toggle sidebar" aria-controls="sidebar">
<i class="ri-menu-line ri-lg" title="Collapse/expand sidebar"></i>
</button>
<div class="background-layer"></div>
<nav id="sidebar" class="sidebar">
<div class="sidebar-header">
<div class="sidebar-projectInfo">
<a href="readme.html" class="sidebar-projectImage">
<img src="assets/logo.png" alt="Plausible" />
</a>
<div>
<a href="readme.html" class="sidebar-projectName" translate="no">
Plausible
</a>
<div class="sidebar-projectVersion" translate="no">
v0.0.1
</div>
</div>
</div>
<ul id="sidebar-listNav" class="sidebar-listNav" role="tablist">
<li>
<button id="extras-list-tab-button" role="tab" data-type="extras" aria-controls="extras-tab-panel" aria-selected="true" tabindex="0">
Pages
</button>
</li>
<li>
<button id="modules-list-tab-button" role="tab" data-type="modules" aria-controls="modules-tab-panel" aria-selected="false" tabindex="-1">
Modules
</button>
</li>
<li>
<button id="tasks-list-tab-button" role="tab" data-type="tasks" aria-controls="tasks-tab-panel" aria-selected="false" tabindex="-1">
<span translate="no">Mix</span> Tasks
</button>
</li>
</ul>
</div>
<div id="extras-tab-panel" class="sidebar-tabpanel" role="tabpanel" aria-labelledby="extras-list-tab-button">
<ul id="extras-full-list" class="full-list"></ul>
</div>
<div id="modules-tab-panel" class="sidebar-tabpanel" role="tabpanel" aria-labelledby="modules-list-tab-button" hidden>
<ul id="modules-full-list" class="full-list"></ul>
</div>
<div id="tasks-tab-panel" class="sidebar-tabpanel" role="tabpanel" aria-labelledby="tasks-list-tab-button" hidden>
<ul id="tasks-full-list" class="full-list"></ul>
</div>
</nav>
<main class="content">
<output role="status" id="toast"></output>
<div class="content-outer">
<div id="content" class="content-inner">
<div class="top-search">
<div class="search-settings">
<form class="search-bar" action="search.html">
<label class="search-label">
<span class="sr-only">Search documentation of Plausible</span>
<input name="q" type="text" class="search-input" placeholder="Search Documentation (press /)" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" />
</label>
<button type="submit" class="search-button" aria-label="Submit Search">
<i class="ri-search-2-line ri-lg" aria-hidden="true" title="Submit search"></i>
</button>
<button type="button" tabindex="-1" class="search-close-button" aria-hidden="true">
<i class="ri-close-line ri-lg" title="Cancel search"></i>
</button>
</form>
<div class="autocomplete">
</div>
<button class="icon-settings display-settings">
<i class="ri-settings-3-line"></i>
<span class="sr-only">Settings</span>
</button>
</div>
</div>
<h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible_web/live/components/combo_box.ex#L1" title="View Source" class="icon-action" rel="help">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
<span translate="no">PlausibleWeb.Live.Components.ComboBox</span>
<small class="app-vsn" translate="no">(Plausible v0.0.1)</small>
</h1>
<section id="moduledoc">
<p>Phoenix LiveComponent for a combobox UI element with search and selection
functionality.</p><p>The component allows users to select an option from a list of options,
which can be searched by typing in the input field.</p><p>The component renders an input field with a dropdown anchor and a
hidden input field for submitting the selected value.</p><p>The number of options displayed in the dropdown is limited to 15
by default but can be customized. When a user types into the input
field, the component searches the available options and provides
suggestions based on the input.</p><p>Any function can be supplied via <code class="inline">suggest_fun</code> attribute</p><ul><li>see the provided <code class="inline">ComboBox.StaticSearch</code>.</li></ul><p>In most cases the <code class="inline">suggest_fun</code> runs an operation that could be deferred,
so by default, the <code class="inline">async={true}</code> attr calls it in a background Task
and updates the suggestions asynchronously. This way, you can render
the component without having to wait for suggestions to load.</p><p>If you explicitly need to make the operation sychronous, you may
pass <code class="inline">async={false}</code> option.</p><p>If your initial <code class="inline">options</code> are not provided up-front at initial render,
lack of <code class="inline">options</code> attr value combined with <code class="inline">async=true</code> calls the
<code class="inline">suggest_fun.(&quot;&quot;, [])</code> asynchronously - that special clause can be used
to provide the initial set of suggestions updated right after the initial render.</p><p>To simplify integration testing, suggestions load up synchronously during
tests. This lets you skip waiting for suggestions messages
to arrive. The asynchronous behaviour alone is already tested in
ComboBox own test suite, so there is no need for additional
verification.</p>
</section>
<section id="summary" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#summary">
<i class="ri-link-m" aria-hidden="true"></i>
</a>
<span class="text">Summary</span>
</h1>
<div class="summary-functions summary">
<h2>
<a href="#functions">Functions</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#dropdown/1" translate="no">dropdown(assigns)</a>
</div>
<div class="summary-synopsis"><h2>Attributes</h2><ul><li><code class="inline">ref</code> (<code class="inline">:string</code>) (required)</li><li><code class="inline">suggestions</code> (<code class="inline">:list</code>) - Defaults to <code class="inline">[]</code>.</li><li><code class="inline">suggest_fun</code> (<code class="inline">:any</code>) (required)</li><li><code class="inline">target</code> (<code class="inline">:any</code>)</li><li><code class="inline">creatable</code> (<code class="inline">:boolean</code>) (required)</li><li><code class="inline">display_value</code> (<code class="inline">:string</code>) (required)</li></ul></div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#dropdown_anchor/1" translate="no">dropdown_anchor(assigns)</a>
</div>
<div class="summary-synopsis"><h2>Attributes</h2><ul><li><code class="inline">id</code> (<code class="inline">:any</code>) (required)</li></ul></div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#handle_event/3" translate="no">handle_event(binary, params, socket)</a>
</div>
<div class="summary-synopsis"><p>Callback implementation for <a href="https://hexdocs.pm/phoenix_live_view/0.20.3/Phoenix.LiveComponent.html#c:handle_event/3"><code class="inline">Phoenix.LiveComponent.handle_event/3</code></a>.</p></div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#option/1" translate="no">option(assigns)</a>
</div>
<div class="summary-synopsis"><h2>Attributes</h2><ul><li><code class="inline">display_value</code> (<code class="inline">:string</code>) (required)</li><li><code class="inline">submit_value</code> (<code class="inline">:string</code>) (required)</li><li><code class="inline">ref</code> (<code class="inline">:string</code>) (required)</li><li><code class="inline">target</code> (<code class="inline">:any</code>)</li><li><code class="inline">idx</code> (<code class="inline">:integer</code>) (required)</li><li><code class="inline">creatable</code> (<code class="inline">:boolean</code>) - Defaults to <code class="inline">false</code>.</li></ul></div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#render/1" translate="no">render(assigns)</a>
</div>
<div class="summary-synopsis"><h2>Attributes</h2><ul><li><code class="inline">placeholder</code> (<code class="inline">:string</code>) - Defaults to <code class="inline">&quot;Select option or search by typing&quot;</code>.</li><li><code class="inline">id</code> (<code class="inline">:any</code>) (required)</li><li><code class="inline">options</code> (<code class="inline">:list</code>) - Defaults to <code class="inline">[]</code>.</li><li><code class="inline">submit_name</code> (<code class="inline">:string</code>) (required)</li><li><code class="inline">display_value</code> (<code class="inline">:string</code>) - Defaults to <code class="inline">&quot;&quot;</code>.</li><li><code class="inline">submit_value</code> (<code class="inline">:string</code>) - Defaults to <code class="inline">&quot;&quot;</code>.</li><li><code class="inline">suggest_fun</code> (<code class="inline">:any</code>) (required)</li><li><code class="inline">suggestions_limit</code> (<code class="inline">:integer</code>)</li><li><code class="inline">class</code> (<code class="inline">:string</code>) - Defaults to <code class="inline">&quot;&quot;</code>.</li><li><code class="inline">required</code> (<code class="inline">:boolean</code>) - Defaults to <code class="inline">false</code>.</li><li><code class="inline">creatable</code> (<code class="inline">:boolean</code>) - Defaults to <code class="inline">false</code>.</li><li><code class="inline">errors</code> (<code class="inline">:list</code>) - Defaults to <code class="inline">[]</code>.</li><li><code class="inline">async</code> (<code class="inline">:boolean</code>) - Defaults to <code class="inline">true</code>.</li><li><code class="inline">on_selection_made</code> (<code class="inline">:any</code>)</li></ul></div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#select_option/4" translate="no">select_option(js \\ %JS{}, id, submit_value, display_value)</a>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#update/2" translate="no">update(assigns, socket)</a>
</div>
<div class="summary-synopsis"><p>Callback implementation for <a href="https://hexdocs.pm/phoenix_live_view/0.20.3/Phoenix.LiveComponent.html#c:update/2"><code class="inline">Phoenix.LiveComponent.update/2</code></a>.</p></div>
</div>
</div>
</section>
<section id="functions" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#functions">
<i class="ri-link-m" aria-hidden="true"></i>
</a>
<span class="text">Functions</span>
</h1>
<div class="functions-list">
<section class="detail" id="dropdown/1">
<div class="detail-header">
<a href="#dropdown/1" class="detail-link" title="Link to this function">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this function</span>
</a>
<h1 class="signature" translate="no">dropdown(assigns)</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible_web/live/components/combo_box.ex#L173" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<h2 id="dropdown/1-attributes" class="section-heading">
<a href="#dropdown/1-attributes" class="hover-link">
<i class="ri-link-m" aria-hidden="true"></i>
</a>
<span class="text">Attributes</span>
</h2>
<ul><li><code class="inline">ref</code> (<code class="inline">:string</code>) (required)</li><li><code class="inline">suggestions</code> (<code class="inline">:list</code>) - Defaults to <code class="inline">[]</code>.</li><li><code class="inline">suggest_fun</code> (<code class="inline">:any</code>) (required)</li><li><code class="inline">target</code> (<code class="inline">:any</code>)</li><li><code class="inline">creatable</code> (<code class="inline">:boolean</code>) (required)</li><li><code class="inline">display_value</code> (<code class="inline">:string</code>) (required)</li></ul>
</section>
</section>
<section class="detail" id="dropdown_anchor/1">
<div class="detail-header">
<a href="#dropdown_anchor/1" class="detail-link" title="Link to this function">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this function</span>
</a>
<h1 class="signature" translate="no">dropdown_anchor(assigns)</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible_web/live/components/combo_box.ex#L145" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<h2 id="dropdown_anchor/1-attributes" class="section-heading">
<a href="#dropdown_anchor/1-attributes" class="hover-link">
<i class="ri-link-m" aria-hidden="true"></i>
</a>
<span class="text">Attributes</span>
</h2>
<ul><li><code class="inline">id</code> (<code class="inline">:any</code>) (required)</li></ul>
</section>
</section>
<section class="detail" id="handle_event/3">
<div class="detail-header">
<a href="#handle_event/3" class="detail-link" title="Link to this function">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this function</span>
</a>
<h1 class="signature" translate="no">handle_event(binary, params, socket)</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible_web/live/components/combo_box.ex#L273" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>Callback implementation for <a href="https://hexdocs.pm/phoenix_live_view/0.20.3/Phoenix.LiveComponent.html#c:handle_event/3"><code class="inline">Phoenix.LiveComponent.handle_event/3</code></a>.</p>
</section>
</section>
<section class="detail" id="option/1">
<div class="detail-header">
<a href="#option/1" class="detail-link" title="Link to this function">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this function</span>
</a>
<h1 class="signature" translate="no">option(assigns)</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible_web/live/components/combo_box.ex#L231" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<h2 id="option/1-attributes" class="section-heading">
<a href="#option/1-attributes" class="hover-link">
<i class="ri-link-m" aria-hidden="true"></i>
</a>
<span class="text">Attributes</span>
</h2>
<ul><li><code class="inline">display_value</code> (<code class="inline">:string</code>) (required)</li><li><code class="inline">submit_value</code> (<code class="inline">:string</code>) (required)</li><li><code class="inline">ref</code> (<code class="inline">:string</code>) (required)</li><li><code class="inline">target</code> (<code class="inline">:any</code>)</li><li><code class="inline">idx</code> (<code class="inline">:integer</code>) (required)</li><li><code class="inline">creatable</code> (<code class="inline">:boolean</code>) - Defaults to <code class="inline">false</code>.</li></ul>
</section>
</section>
<section class="detail" id="render/1">
<div class="detail-header">
<a href="#render/1" class="detail-link" title="Link to this function">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this function</span>
</a>
<h1 class="signature" translate="no">render(assigns)</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible_web/live/components/combo_box.ex#L74" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<h2 id="render/1-attributes" class="section-heading">
<a href="#render/1-attributes" class="hover-link">
<i class="ri-link-m" aria-hidden="true"></i>
</a>
<span class="text">Attributes</span>
</h2>
<ul><li><code class="inline">placeholder</code> (<code class="inline">:string</code>) - Defaults to <code class="inline">&quot;Select option or search by typing&quot;</code>.</li><li><code class="inline">id</code> (<code class="inline">:any</code>) (required)</li><li><code class="inline">options</code> (<code class="inline">:list</code>) - Defaults to <code class="inline">[]</code>.</li><li><code class="inline">submit_name</code> (<code class="inline">:string</code>) (required)</li><li><code class="inline">display_value</code> (<code class="inline">:string</code>) - Defaults to <code class="inline">&quot;&quot;</code>.</li><li><code class="inline">submit_value</code> (<code class="inline">:string</code>) - Defaults to <code class="inline">&quot;&quot;</code>.</li><li><code class="inline">suggest_fun</code> (<code class="inline">:any</code>) (required)</li><li><code class="inline">suggestions_limit</code> (<code class="inline">:integer</code>)</li><li><code class="inline">class</code> (<code class="inline">:string</code>) - Defaults to <code class="inline">&quot;&quot;</code>.</li><li><code class="inline">required</code> (<code class="inline">:boolean</code>) - Defaults to <code class="inline">false</code>.</li><li><code class="inline">creatable</code> (<code class="inline">:boolean</code>) - Defaults to <code class="inline">false</code>.</li><li><code class="inline">errors</code> (<code class="inline">:list</code>) - Defaults to <code class="inline">[]</code>.</li><li><code class="inline">async</code> (<code class="inline">:boolean</code>) - Defaults to <code class="inline">true</code>.</li><li><code class="inline">on_selection_made</code> (<code class="inline">:any</code>)</li></ul>
</section>
</section>
<section class="detail" id="select_option/4">
<span id="select_option/3"></span>
<div class="detail-header">
<a href="#select_option/4" class="detail-link" title="Link to this function">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this function</span>
</a>
<h1 class="signature" translate="no">select_option(js \\ %JS{}, id, submit_value, display_value)</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible_web/live/components/combo_box.ex#L266" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
</section>
</section>
<section class="detail" id="update/2">
<div class="detail-header">
<a href="#update/2" class="detail-link" title="Link to this function">
<i class="ri-link-m" aria-hidden="true"></i>
<span class="sr-only">Link to this function</span>
</a>
<h1 class="signature" translate="no">update(assigns, socket)</h1>
<a href="https://github.com/plausible/analytics/blob/main/lib/plausible_web/live/components/combo_box.ex#L44" class="icon-action" rel="help" title="View Source">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>Callback implementation for <a href="https://hexdocs.pm/phoenix_live_view/0.20.3/Phoenix.LiveComponent.html#c:update/2"><code class="inline">Phoenix.LiveComponent.update/2</code></a>.</p>
</section>
</section>
</div>
</section>
<footer class="footer">
<p>
<span class="line">
<button class="a-main footer-button display-quick-switch" title="Search HexDocs packages">
Search HexDocs
</button>
<a href="Plausible.epub" title="ePub version">
Download ePub version
</a>
</span>
</p>
<p class="built-using">
Built using
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener" translate="no">ExDoc</a> (v0.31.1) for the
<a href="https://elixir-lang.org" title="Elixir" target="_blank" translate="no">Elixir programming language</a>
</p>
</footer>
</div>
</div>
</main>
</div>
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad: true})</script>
</body>
</html>