@pokle/basecoat 0.3.10-beta2.pokle

package/docs/src/components/checkbox.njk

@@ -0,0 +1,101 @@
+---
+layout: layouts/page.njk
+title: Checkbox
+description: A control that allows the user to toggle between checked and not checked.
+toc:
+  - label: Usage
+    id: usage
+  - label: Examples
+    id: examples
+    children:
+      - label: Disabled
+        id: example-disabled
+      - label: With text
+        id: example-with-text
+      - label: Form
+        id: example-form
+---
+
+{% from "macros/code_preview.njk" import code_preview %}
+{% from "macros/code_block.njk" import code_block %}
+
+{% set code %}<label class="label gap-3">
+  <input type="checkbox" class="input">
+  Accept terms and conditions
+</label>{% endset %}
+{{ code_preview("checkbox", code) }}
+
+<h2 id="usage">Usage</h2>
+
+<section class="prose">
+  <p>Add the <code>input</code> class to your <code>&lt;input type="radio"&gt;</code> elements or have a parent with the <code>form</code> class (<a href="/components/form">read more about form</a>). You can also set the <code>aria-invalid</code> attribute to <code>true</code> to make the input invalid.</p>
+</section>
+
+{% set code %}<input type="checkbox" class="input">{% endset %}
+{{ code_block(code) }}
+
+<h2 id="examples"><a href="#examples">Examples</a></h2>
+
+<h3 id="example-disabled"><a href="#example-disabled">Disabled</a></h3>
+
+{% set code %}<label class="label gap-3">
+  <input type="checkbox" class="input" disabled>
+  Accept terms and conditions
+</label>{% endset %}
+{{ code_preview("checkbox-disabled", code) }}
+
+<h3 id="example-with-text"><a href="#example-with-text">With text</a></h3>
+
+{% set code %}<div class="flex items-start gap-3">
+  <input type="checkbox" id="checkbox-with-text" class="input">
+  <div class="grid gap-2">
+    <label for="checkbox-with-text" class="label">Accept terms and conditions</label>
+    <p class="text-muted-foreground text-sm">By clicking this checkbox, you agree to the terms and conditions.</p>
+  </div>
+</div>{% endset %}
+{{ code_preview("checkbox-with-text", code) }}
+
+<h3 id="example-form"><a href="#example-form">Form</a></h3>
+
+{% set code %}<form class="form flex flex-row items-start gap-3 rounded-md border p-4 shadow-xs">
+  <input type="checkbox" id="checkbox-form-1">
+  <div class="flex flex-col gap-1">
+    <label for="checkbox-form-1" class="leading-snug">Use different settings for my mobile devices</label>
+    <p class="text-muted-foreground text-sm leading-snug">You can manage your mobile notifications in the mobile settings page.</p>
+  </div>
+</form>{% endset %}
+{{ code_preview("input-form", code) }}
+
+{% set code %}<form class="form flex flex-col gap-4">
+  <header>
+    <label for="demo-form-checkboxes" class="text-base leading-normal">Sidebar</label>
+    <p class="text-muted-foreground text-sm">Select the items you want to display in the sidebar.</p>
+  </header>
+  <fieldset id="demo-form-checkboxes" class="flex flex-col gap-2">
+    <label class="font-normal leading-tight">
+      <input type="checkbox" name="demo-form-checkboxes" value="1" checked>
+      Recents
+    </label>
+    <label class="font-normal leading-tight">
+      <input type="checkbox" name="demo-form-checkboxes" value="2" checked>
+      Home
+    </label>
+    <label class="font-normal leading-tight">
+      <input type="checkbox" name="demo-form-checkboxes" value="3">
+      Applications
+    </label>
+    <label class="font-normal leading-tight">
+      <input type="checkbox" name="demo-form-checkboxes" value="4">
+      Desktop
+    </label>
+    <label class="font-normal leading-tight">
+      <input type="checkbox" name="demo-form-checkboxes" value="5">
+      Download
+    </label>
+    <label class="font-normal leading-tight">
+      <input type="checkbox" name="demo-form-checkboxes" value="6">
+      Documents
+    </label>
+  </fieldset>
+</form>{% endset %}
+{{ code_preview("input-form", code) }}

package/docs/src/components/combobox.njk

@@ -0,0 +1,293 @@
+---
+layout: layouts/page.njk
+title: Combobox
+description: Autocomplete input and command palette with a list of suggestions.
+toc:
+  - label: Usage
+    id: usage
+    children:
+      - label: HTML + JavaScript
+        id: usage-html-js
+        children:
+          - label: "Step 1: Include the JavaScript files"
+            id: usage-html-js-1
+          - label: "Step 2: Add your combobox HTML"
+            id: usage-html-js-2
+          - label: HTML structure
+            id: usage-html-js-3
+          - label: JavaScript events
+            id: usage-html-js-4
+          - label: JavaScript methods
+            id: usage-html-js-5
+      - label: Jinja and Nunjucks
+        id: usage-macro
+  - label: Examples
+    id: examples
+    children:
+      - label: Scrollable
+        id: example-scrollable
+      - label: Top side
+        id: example-top
+---
+
+{% from "macros/code_preview.njk" import code_preview %}
+{% from "macros/code_block.njk" import code_block %}
+{% from "select.njk" import select %}
+
+{% set options_frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"] %}
+{% set code_html %}
+{% call select(
+  trigger_attrs={"class": "w-[200px]"},
+  listbox_attrs={"data-empty": "No framework found."},
+  is_combobox=true,
+  search_placeholder="Search framework..."
+) %}
+  {% for framework in options_frameworks %}
+    <div role="option" data-value="{{ framework }}">{{ framework }}</div>
+  {% endfor %}
+{% endcall %}
+{% endset %}
+
+{{ code_preview("combobox", code_html | prettyHtml) }}
+
+<h2 id="usage"><a href="#usage">Usage</a></h2>
+
+<h3 id="usage-html-js"><a href="#usage-html-js">HTML + JavaScript</a></h3>
+
+<h4 id="usage-html-js-1"><a href="#usage-html-js-1">Step 1: Include the JavaScript files</a></h4>
+
+<section class="prose">
+  <p>You can either <a href="/installation/#install-cdn-all">include the JavaScript file for all the components</a>, or just the one for this component by adding this to the <code>&lt;head&gt;</code> of your page:</p>
+</section>
+
+{% set code_script %}<script src="https://cdn.jsdelivr.net/npm/basecoat-css@{{ pkg.version }}/dist/js/basecoat.min.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/basecoat-css@{{ pkg.version }}/dist/js/select.min.js" defer></script>{% endset %}
+{{ code_block(code_script | prettyHtml, "html") }}
+
+<div class="flex flex-wrap gap-2 my-6">
+  <a class="badge-outline" href="/installation/#install-js">
+    Components with JavaScript
+    {% lucide "arrow-right" %}
+  </a>
+  <a class="badge-outline" href="/installation/#install-cli">
+    Use the CLI
+    {% lucide "arrow-right" %}
+  </a>
+  <a class="badge-outline" href="https://github.com/hunvreus/basecoat/blob/main/src/js/select.js" target="_blank">
+    select.js
+    {% lucide "arrow-right" %}
+  </a>
+</div>
+
+<h4 id="usage-html-js-2"><a href="#usage-html-js-2">Step 2: Add your combobox HTML</a></h4>
+
+<section class="prose">
+  <p>Combobox uses the same markup and JavaScript as the <a href="/components/select#usage-html-js">Select component</a>, the only difference being the search box at the top of the listbox:</p>
+</section>
+
+{{ code_block(code_html | prettyHtml, "html") }}
+
+<h4 id="usage-html-js-3"><a href="#usage-html-js-3">HTML structure</a></h4>
+
+<section class="prose">
+  <dl>
+    <dt><code class="highlight language-html">&lt;div class="select"&gt;</code></dt>
+    <dd>Wraps around the entire component.
+      <dl>
+        <dt><code class="highlight language-html">&lt;button type="button" popovertarget="{ POPOVER_ID }"&gt;</code></dt>
+        <dd>
+          <p>The trigger to open the popover, can also have the following attributes:</p>
+          <ul>
+            <li><code>id="{BUTTON_ID}"</code>: linked to by the <code>aria-labelledby</code> attribute of the listbox.</li>
+            <li><code>aria-haspopup="listbox"</code>: indicates that the button opens a listbox.</li>
+            <li><code>aria-controls="{ LISTBOX_ID }"</code>: points to the listbox's id.</li>
+            <li><code>aria-expanded="false"</code>: tracks the popover's state.</li>
+            <li><code>aria-activedescendant="{ OPTION_ID }"</code>: points to the active option's id.</li>
+          </ul>
+        </dd>
+        <dt><code class="highlight language-html">&lt;div popover class="popover" id="{ POPOVER_ID }"&gt;</code></dt>
+        <dd>As with the <a href="/components/popover">Popover</a> component, you can set up the side and alignment of the popover using the <code>data-side</code> and <code>data-align</code> attributes.
+        <dl>
+          <dt><code class="highlight language-html">&lt;header&gt;</code></dt>
+          <dd>Contains the search input to filter the options in the listbox.</dd>
+          <dt><code class="highlight language-html">&lt;div role="listbox"&gt;</code></dt>
+          <dd>The listbox containing the options. Should have the following attributes:
+            <ul>
+              <li><code>id="{ LISTBOX_ID }"</code>: refered to by the <code>aria-controls</code> attribute of the trigger.</li>
+              <li><code>aria-labelledby="{ BUTTON_ID }"</code>: linked to by the button's <code>id</code> attribute.</li>
+            </ul>
+            <dl>
+              <dt><code class="highlight language-html">&lt;div role="option" data-value="{ VALUE }"&gt;</code></dt>
+              <dd>Option that can be selected. Should have a unique id if you use the <code>aria-activedescendant</code> attribute on the trigger. Optional attributes:
+                <ul>
+                  <li><code>data-filter</code>: custom text used for filtering (if different from displayed content, e.g., <code>data-filter="united states"</code>)</li>
+                  <li><code>data-keywords</code>: additional keywords for enhanced filtering (e.g., <code>data-keywords="bread fruit"</code>)</li>
+                  <li><code>data-force</code>: forces the option to always display, regardless of filter (e.g., <code>data-force</code>)</li>
+                  <li><code>aria-disabled="true"</code>: marks option as disabled (excluded from selection and keyboard navigation)</li>
+                </ul>
+              </dd>
+              <dt><code class="highlight language-html">&lt;hr role="separator"&gt;</code> <span class="badge-secondary">Optional</span></dt>
+              <dd>Separator between groups/options.</dd>
+              <dt><code class="highlight language-html">&lt;div role="group"&gt;</code> <span class="badge-secondary">Optional</span></dt>
+              <dd>Group of options, can have a <code>aria-labelledby</code> attribute to link to a heading.</dd>
+              <dt><code class="highlight language-html">&lt;span role="heading"&gt;</code></dt>
+              <dd>Group heading, must have an <code>id</code> attribute if you use the <code>aria-labelledby</code> attribute on the group.</dd>
+            </dl>
+          </dd>
+        </dl>
+      </dl>
+    </dd>
+    <dt><code class="highlight language-html">&lt;input type="hidden" name="{ NAME }" value="{ VALUE }"&gt;</code> <span class="badge-secondary">Optional</span></dt>
+    <dd>The hidden input that holds the value of the field (if needed).</dd>
+  </dl>
+</section>
+
+<h4 id="usage-html-js-4"><a href="#usage-html-js-4">JavaScript events</a></h4>
+
+<section class="prose">
+  <dl>
+    <dt><code>basecoat:initialized</code></dt>
+    <dd>Once the component is fully initialized, it dispatches a custom (non-bubbling) <code>basecoat:initialized</code> event on itself.</dd>
+    <dt><code>basecoat:popover</code></dt>
+    <dd>When the popover opens, the component dispatches a custom (non-bubbling) <code>basecoat:popover</code> event on <code>document</code>. Other popover components (Combobox, Dropdown Menu, Popover and Select) listen for this to close any open popovers.</dd>
+    <dt><code>change</code></dt>
+    <dd>When the selected value changes, the component dispatches a custom (bubbling) <code>change</code> event on itself, with the selected value in <code>event.detail</code> (e.g. <code>{detail: {value: "something"}}</code>).</dd>
+  </dl>
+</section>
+
+<h4 id="usage-html-js-5"><a href="#usage-html-js-4">JavaScript methods</a></h4>
+
+<section class="prose">
+  <dl>
+    <dt><code>selectByValue</code></dt>
+    <dd>
+      <p>You can call this method on the component after it is initialized to select an option by value (i.e. the option with the matching <code>data-value</code> attribute):</p>
+
+{% set code_script %}<script>
+  const comboboxComponent = document.querySelector('#my-combobox');
+  comboboxComponent.addEventListener('basecoat:initialized', () => {
+    comboboxComponent.selectByValue('apple');
+  });
+</script>{% endset %}
+{{ code_block(code_script | prettyHtml, "html") }}
+    </dd>
+  </dl>
+</section>
+
+<h3 id="usage-macro"><a href="#usage-macro">Jinja and Nunjucks</a></h3>
+
+<div class="prose">
+  <p>You can use the <code class="relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-xs">select()</code> Nunjucks or Jinja macro for this component. If you use one of the macros, make sure to set <code>is_combobox</code> to <code>True</code> (or <code>true</code> for Nunjucks).</p>
+</div>
+
+<div class="flex flex-wrap gap-2 my-6">
+  <a class="badge-outline" href="/installation/#install-macros" target="_blank">
+    Use Nunjucks or Jinja macros
+    {% lucide "arrow-right" %}
+  </a>
+  <a class="badge-outline" href="https://github.com/hunvreus/basecoat/blob/main/src/jinja/select.html.jinja" target="_blank">
+    Jinja macro
+    {% lucide "arrow-right" %}
+  </a>
+  <a class="badge-outline" href="https://github.com/hunvreus/basecoat/blob/main/src/nunjucks/select.njk" target="_blank">
+    Nunjucks macro
+    {% lucide "arrow-right" %}
+  </a>
+</div>
+
+{% set raw_code %}{% raw %}{% call select(
+  listbox_attrs={"data-empty": "No framework found."},
+  is_combobox=true
+) %}
+  <div role="option" data-value="nextjs">Next.js</div>
+  <div role="option" data-value="sveltekit">SvelteKit</div>
+  <div role="option" data-value="nuxtjs">Nuxt.js</div>
+  <div role="option" data-value="remix">Remix</div>
+  <div role="option" data-value="astro">Astro</div>
+{% endcall %}{% endraw %}{% endset %}
+{{ code_block(raw_code, "jinja") }}
+
+<h2 id="examples"><a href="#examples">Examples</a></h2>
+
+<h3 id="example-scrollable"><a href="#example-scrollable">Scrollable</a></h3>
+
+{% set options_timezones = [
+  {
+    label: "Americas",
+    timezones: [
+      { value: "America/New_York", label: "(GMT-5) New York" },
+      { value: "America/Los_Angeles", label: "(GMT-8) Los Angeles" },
+      { value: "America/Chicago", label: "(GMT-6) Chicago" },
+      { value: "America/Toronto", label: "(GMT-5) Toronto" },
+      { value: "America/Vancouver", label: "(GMT-8) Vancouver" },
+      { value: "America/Sao_Paulo", label: "(GMT-3) São Paulo" }
+    ]
+  },
+  {
+    label: "Europe",
+    timezones: [
+      { value: "Europe/London", label: "(GMT+0) London" },
+      { value: "Europe/Paris", label: "(GMT+1) Paris" },
+      { value: "Europe/Berlin", label: "(GMT+1) Berlin" },
+      { value: "Europe/Rome", label: "(GMT+1) Rome" },
+      { value: "Europe/Madrid", label: "(GMT+1) Madrid" },
+      { value: "Europe/Amsterdam", label: "(GMT+1) Amsterdam" }
+    ]
+  },
+  {
+    label: "Asia/Pacific",
+    timezones: [
+      { value: "Asia/Tokyo", label: "(GMT+9) Tokyo" },
+      { value: "Asia/Shanghai", label: "(GMT+8) Shanghai" },
+      { value: "Asia/Singapore", label: "(GMT+8) Singapore" },
+      { value: "Asia/Dubai", label: "(GMT+4) Dubai" },
+      { value: "Australia/Sydney", label: "(GMT+11) Sydney" },
+      { value: "Asia/Seoul", label: "(GMT+9) Seoul" }
+    ]
+  }
+] %}
+{% set code %}
+{% call select(
+  trigger_attrs={"class": "w-[200px]"},
+  popover_attrs={"class": "w-72"},
+  listbox_attrs={"data-empty": "No timezone found."},
+  is_combobox=true,
+  search_placeholder="Search timezone..."
+) %}
+  <div class="max-h-64 overflow-y-auto scrollbar">
+    {% for group in options_timezones %}
+      <div role="group" aria-labelledby="demo-combobox-timezones-group-{{ loop.index0 }}">
+        <div role="heading" id="demo-combobox-timezones-group-{{ loop.index0 }}">{{ group.label }}</div>
+        {% for timezone in group.timezones %}
+          <div role="option" data-value="{{ timezone.value}}">
+            {{ timezone.label }}
+          </div>
+        {% endfor %}
+      </div>
+    {% endfor %}
+  </div>
+  <hr role="separator">
+  <div role="option">
+    {% lucide "circle-plus" %}
+    Create timezone
+  </div>
+{% endcall %}
+{% endset %}
+{{ code_preview("combobox-with-groups", code | prettyHtml) }}
+
+<h3 id="example-top"><a href="#example-top">Top side</a></h3>
+
+{% set options_frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"] %}
+{% set code %}
+{% call select(
+  trigger_attrs={"class": "w-[200px]"},
+  listbox_attrs={"data-empty": "No framework found."},
+  is_combobox=true,
+  search_placeholder="Search framework...",
+  popover_attrs={"data-side": "top"}
+) %}
+  {% for framework in options_frameworks %}
+    <div role="option" data-value="{{ framework }}">{{ framework }}</div>
+  {% endfor %}
+{% endcall %}{% endset %}
+{{ code_preview("combobox", code | prettyHtml) }}