diff --git a/docs/css/custom.css b/docs/css/custom.css index ef75d05..0742668 100644 --- a/docs/css/custom.css +++ b/docs/css/custom.css @@ -12,10 +12,10 @@ .content { > h2 { - @apply mt-16 mb-6 scroll-m-22 border-b pb-4 text-xl font-semibold tracking-tight first:mt-0; + @apply mt-12 lg:mt-20 mb-6 scroll-m-22 text-2xl font-semibold tracking-tight first:mt-0; } > h3 { - @apply mt-8 mb-6 scroll-m-22 text-lg font-semibold tracking-tight; + @apply mt-8 mb-6 scroll-m-22 text-xl font-semibold tracking-tight; } > h4 { @apply my-6 scroll-m-22 font-semibold tracking-tight; @@ -44,6 +44,18 @@ @apply mt-2; } } + dl { + @apply border-b pb-3 my-6; + dt { + @apply border-t pt-3 mt-3 first:mt-0; + } + dd { + @apply mt-2; + } + dl { + @apply mt-4 border-b-0 pb-0 pl-8 my-0; + } + } b, strong { @apply font-semibold; diff --git a/docs/src/_includes/layouts/base.njk b/docs/src/_includes/layouts/base.njk index cf0b5b1..038e022 100644 --- a/docs/src/_includes/layouts/base.njk +++ b/docs/src/_includes/layouts/base.njk @@ -65,12 +65,11 @@ - - + {# #} - + @@ -78,7 +77,12 @@ + @@ -60,39 +50,12 @@ document.addEventListener('alpine:init', () => { {% endset %} -{{ code_preview("dropdown-menu", code_script | prettyHtml ~ code_html | prettyHtml) }} +{{ code_preview("dropdown-menu", code_html | prettyHtml) }}

Usage

-
- {% lucide "circle-alert" %} -

This component requires Javascript.

-
-
-

This example uses some simple Tailwind CSS styles along with the Dropdown Menu.

- -

You can include the Javascript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

+

This example uses some simple Tailwind CSS styles along with the Dropdown Menu component (which may require JavaScript).

-
- - Components with Javascript - {% lucide "arrow-right" %} - - - Use the CLI - {% lucide "arrow-right" %} - - - Individual JS file (select.js) - {% lucide "arrow-right" %} - -
- -{% from "tabs.njk" import tabs %} -{% set tabsets = [ - { tab: "HTML", panel: code_block(code_html | prettyHtml, class="") }, - { tab: "Javascipt (Alpine.js)", panel: code_block(code_script | prettyHtml, class="") } -] %} -{{ tabs(id="alert-dialog", tabsets=tabsets) }} \ No newline at end of file +{{ code_block(code_html | prettyHtml, class="") }} \ No newline at end of file diff --git a/docs/src/components/combobox.njk b/docs/src/components/combobox.njk index d3488bd..988d550 100644 --- a/docs/src/components/combobox.njk +++ b/docs/src/components/combobox.njk @@ -6,7 +6,7 @@ toc: - label: Usage id: usage children: - - label: HTML + Javascript + - label: HTML + JavaScript id: usage-default - label: Jinja and Nunjucks id: usage-macro @@ -52,11 +52,11 @@ document.addEventListener('alpine:init', () => {

Usage

-

HTML + Javascript

+

HTML + JavaScript

{% lucide "circle-alert" %} -

This component requires Javascript.

+

This component requires JavaScript.

@@ -68,12 +68,12 @@ document.addEventListener('alpine:init', () => {
  • data-empty to set up the message when the search is empty.
    • -

    You can include the Javascript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    +

    You can include the JavaScript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    - Components with Javascript + Components with JavaScript {% lucide "arrow-right" %} diff --git a/docs/src/components/dialog.njk b/docs/src/components/dialog.njk index eabe3d6..160a04f 100644 --- a/docs/src/components/dialog.njk +++ b/docs/src/components/dialog.njk @@ -6,8 +6,10 @@ toc: - label: Usage id: usage children: - - label: HTML + Javascript - id: usage-default + - label: HTML + id: usage-html + - label: JavasScript + id: usage-html - label: Jinja and Nunjucks id: usage-macro - label: Examples @@ -30,12 +32,10 @@ toc: id="demo-dialog-edit-profile", title="Edit profile", description="Make changes to your profile here. Click save when you're done.", - main_attrs={"x-ref": "myDialog"}, trigger="Edit Profile", trigger_attrs={"class": "btn-outline"}, content_attrs={"class": "w-full sm:max-w-[425px] max-h-[612px]"}, - footer=footer, - register_on=["alpine:init", "htmx:afterSwap"] + footer=footer ) %}
    @@ -50,75 +50,40 @@ toc: {% endcall %} {% endset %} -{% set code_script %} - -{% endset %} - -{{ code_preview("dialog", code_script | prettyHtml ~ code_html | prettyHtml) }} +{{ code_preview("dialog", code_html | prettyHtml) }}

    Usage

    -

    HTML + Javascript

    - -
    - {% lucide "circle-alert" %} -

    This component requires Javascript.

    -
    +

    HTML

    -

    The component is structured as such:

    -
      -
    • A <div class="dialog"> which wraps around the entire component and holds it state (e.g. open/close).
      • -
    • A <button> that acts as the trigger to open or close the popover.
      • -
    • A <div role="dialog"> that holds the dialog itself. It also acts as the backdrop for the dialog.
      • -
    • Inside of it, we have: -
        -
      • A <header> that contains the title (<h2>) and description (<p>) of the dialog.
        • -
      • A <section> for the content.
        • -
      • A <footer> that usually contains actions.
        • -
      • A close <button>.
        • -
      -
      • -
    -

    You can include the Javascript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    +

    The component has the following structure:

    +
    +
    <dialog class="dialog">
    +
    Wraps around the entire component and acts as its backdrop. +
    +
    <header>
    +
    Contains the header for the dialog: +
    +
    <h2>
    +
    The title of the dialog.
    +
    <p> Optional
    +
    The description of the dialog.
    +
    +
    +
    <section> Optional
    +
    For the content.
    +
    <footer> Optional
    +
    Usually contains actions.
    +
    <form method="dialog"> Optional
    +
    A form that contains a single button to close the dialog.
    +
    +
    +
    +

    The example below also include a <button type="button> to show how we can open the dialog using the showModal() method as well as aria-related attributes recommended for accessiblity:

    .

    -
    - - Components with Javascript - {% lucide "arrow-right" %} - - - Use the CLI - {% lucide "arrow-right" %} - - - Individual JS file (dialog.js) - {% lucide "arrow-right" %} - -
    - -{% from "tabs.njk" import tabs %} -{% set tabsets = [ - { tab: "HTML", panel: code_block(code_html | prettyHtml, class="") }, - { tab: "Javascipt (Alpine.js)", panel: code_block(code_script | prettyHtml, class="") } -] %} -{{ tabs(id="combobox", tabsets=tabsets) }} - -
    -

    The component will dispatch dialog:opened and dialog:closed events when the dialog is opened or closed. You can also dispatch dialog:open and dialog:close events to open or close the dialog programmatically. You will need the element to have an id to be able to target it (e.g. <div id="my-dialog" class="dialog">):

    -
    - -{% set code_dispatch %}{% endset %} -{{ code_block(code_dispatch | prettyHtml, "html") }} +{{ code_block(code_html | prettyHtml, class="") }}

    Jinja and Nunjucks

    @@ -141,20 +106,19 @@ document.addEventListener('alpine:init', () => {
    -{% set raw_code %}{% raw %}{% set footer %} - - +{% set raw_code %}{% raw %}{% set code_html %} +{% set footer %} + + {% endset %} {% call dialog( id="demo-dialog-edit-profile", title="Edit profile", description="Make changes to your profile here. Click save when you're done.", - main_attrs={"x-ref": "myDialog"}, trigger="Edit Profile", trigger_attrs={"class": "btn-outline"}, content_attrs={"class": "w-full sm:max-w-[425px] max-h-[612px]"}, - footer=footer, - register_on=["alpine:init", "htmx:afterSwap"] + footer=footer ) %}
    diff --git a/docs/src/components/dropdown-menu.njk b/docs/src/components/dropdown-menu.njk index 8621e45..767a287 100644 --- a/docs/src/components/dropdown-menu.njk +++ b/docs/src/components/dropdown-menu.njk @@ -6,7 +6,7 @@ toc: - label: Usage id: usage children: - - label: HTML + Javascript + - label: HTML + JavaScript id: usage-default - label: Jinja and Nunjucks id: usage-macro @@ -76,11 +76,11 @@ toc:

    Usage

    -

    HTML + Javascript

    +

    HTML + JavaScript

    {% lucide "circle-alert" %} -

    This component requires Javascript.

    +

    This component requires JavaScript.

    @@ -105,12 +105,12 @@ toc:
  • data-align can be set to start, center, or end to change the alignment of the popover.
    • -

    You can include the Javascript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    +

    You can include the JavaScript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    - Components with Javascript + Components with JavaScript {% lucide "arrow-right" %} diff --git a/docs/src/components/popover.njk b/docs/src/components/popover.njk index 904e8d4..6bf76bc 100644 --- a/docs/src/components/popover.njk +++ b/docs/src/components/popover.njk @@ -6,7 +6,7 @@ toc: - label: Usage id: usage children: - - label: HTML + Javascript + - label: HTML + JavaScript id: usage-default - label: Jinja and Nunjucks id: usage-macro @@ -64,11 +64,17 @@ document.addEventListener('alpine:init', () => {

    Usage

    -

    HTML + Javascript

    +

    HTML

    {% lucide "circle-alert" %} -

    This component requires Javascript.

    +

    This component requires JavaScript.

    +

    By default, you can use the component without JavaScript. However, you may want to include some JavaScript to support older browsers and accessiblity features, including keyboard navigation.

    +
    + +
    + {% lucide "circle-alert" %} +

    This component requires JavaScript.

    @@ -87,12 +93,12 @@ document.addEventListener('alpine:init', () => {
  • data-align can be set to start, center, or end to change the alignment of the popover.
    • -

    You can include the Javascript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    +

    You can include the JavaScript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    - Components with Javascript + Components with JavaScript {% lucide "arrow-right" %} diff --git a/docs/src/components/select.njk b/docs/src/components/select.njk index a6e2a0a..7d43670 100644 --- a/docs/src/components/select.njk +++ b/docs/src/components/select.njk @@ -8,7 +8,7 @@ toc: children: - label: HTML id: usage-html - - label: HTML + Javascript + - label: HTML + JavaScript id: usage-js - label: Jinja and Nunjucks id: usage-macro @@ -73,39 +73,66 @@ toc: {{ code_block(code_native) }} -

    HTML + Javascript

    +

    HTML + JavaScript

    -

    If you need to do more than what <select> allows (e.g. HTML options), you can use this component. It is structured as such:

    - -
      -
    • A <div class="popover"> which wraps around the entire component and holds it state (e.g. open/close).
      • -
    • A <button> that acts as the trigger to open or close the popover.
      • -
    • A <div data-popover> that holds the content of the popover.
      • -
    • Inside of the <div data-popover> is a <nav role="listbox"> that contains a combination of: -
        -
      • <div role="option"> for the options with a data-value attribute.
        • -
      • <hr role="separator"> to display a horizontal separator.
        • -
      • <div role="group"> to group options.
        • -
      • <span role="heading"> for group headings.
        • -
      -
      • -
    • An <input type="hidden"> to hold the value of the field (if needed).
      • -
    - -

    As with the Popover component, you can set up a few additional options on the <div data-popover> element:

    - -
      -
    • data-side can be set to top, bottom, left, or right to change the side of the popover.
      • -
    • data-align can be set to start, center, or end to change the alignment of the popover.
      • -
    - -

    You can include the Javascript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    +

    The component has the following structure:

    +
    +
    <div class="select">
    +
    Wraps around the entire component. +
    +
    <button type="button" popovertarget="{ POPOVER_ID }">
    +
    +

    The trigger to open the popover, can also have the following attributes:

    +
      +
    • id="{BUTTON_ID}": linked to by the aria-labelledby attribute of the listbox.
      • +
    • aria-haspopup="listbox": indicates that the button opens a listbox.
      • +
    • aria-controls="{ LISTBOX_ID }": points to the listbox's id.
      • +
    • aria-expanded="false": tracks the popover's state.
      • +
    • aria-activedescendant="{ OPTION_ID }": points to the active option's id.
      • +
    +
    +
    <div popover class="popover" id="{ POPOVER_ID }">
    +
    As with the Popover component, you can set up the side and alignment of the popover using the data-side and data-align attributes. +
    +
    <div role="listbox">
    +
    The listbox containing the options. Should have the following attributes: +
      +
    • id="{ LISTBOX_ID }": refered to by the aria-controls attribute of the trigger.
      • +
    • aria-labelledby="{ BUTTON_ID }": linked to by the button's id attribute.
      • +
    +
    +
    <div role="option" data-value="{ VALUE }">
    +
    Option that can be selected.Should have a unique id if you use the aria-activedescendant attribute on the trigger.
    +
    <hr role="separator"> Optional
    +
    Separator between groups/options.
    +
    <div role="group"> Optional
    +
    Group of options.
    +
    <span role="heading">
    +
    Group heading.
    +
    +
    +
    +
    +
    +
    <input type="hidden" name="{ NAME }" value="{ VALUE }"> Optional
    +
    The hidden input that holds the value of the field (if needed).
    +
    +

    More aria-related attributes are also recommended as illustrated in the example below:

    +{{ code_block(code_html | prettyHtml, "html") }} + +
    +

    This component requires you to include the select.js file and recommends you include the CSS anchor positioning polyfill to support older browsers. You can either include the code shown below in your <head> or use one of the alternative methods.

    +
    + +{% set code_script %}{% raw %}{% endraw %}{% endset %} +{{ code_block(code_script | prettyHtml, "html") }} +
    - Components with Javascript + Components with JavaScript {% lucide "arrow-right" %} @@ -118,36 +145,10 @@ toc:
    -{% from "tabs.njk" import tabs %} -{% set tabsets = [ - { tab: "HTML", panel: code_block(code_html | prettyHtml, class="") }, - { tab: "Javascipt (Alpine.js)", panel: code_block(code_script | prettyHtml, class="") } -] %} -{{ tabs(id="select", tabsets=tabsets) }} - -
    -

    The component will dispatch a select:change event when a value is selected, along with the value and label of the selected option in the detail object.

    -
    -

    Jinja and Nunjucks

    -

    You can use the dropdown_menu() Nunjucks or Jinja macro for this component.

    -
    - -
    - - Use Nunjucks or Jinja macros - {% lucide "arrow-right" %} - - - Jinja macro - {% lucide "arrow-right" %} - - - Nunjucks macro - {% lucide "arrow-right" %} - +

    You can use the select() Nunjucks or Jinja macro for this component.

    {% set raw_code %}{% raw %}{{ select( @@ -167,6 +168,21 @@ toc: ) }}{% endraw %}{% endset %} {{ code_block(raw_code, "jinja") }} +
    + + Use Nunjucks or Jinja macros + {% lucide "arrow-right" %} + + + Jinja macro + {% lucide "arrow-right" %} + + + Nunjucks macro + {% lucide "arrow-right" %} + +
    +

    Examples

    Scrollable

    diff --git a/docs/src/components/sidebar.njk b/docs/src/components/sidebar.njk index 298c464..8695925 100644 --- a/docs/src/components/sidebar.njk +++ b/docs/src/components/sidebar.njk @@ -6,7 +6,7 @@ toc: - label: Usage id: usage children: - - label: HTML + Javascript + - label: HTML + JavaScript id: usage-default - label: Jinja and Nunjucks id: usage-macro @@ -18,11 +18,11 @@ toc:

    Usage

    -

    HTML + Javascript

    +

    HTML + JavaScript

    {% lucide "circle-alert" %} -

    This component requires Javascript.

    +

    This component requires JavaScript.

    @@ -40,12 +40,12 @@ toc:

    Any elememt on the page can toggle, open or close the sidebar by dispatching the sidebar:toggle, sidebar:open or sidebar:close events.

    -

    You can include the Javascript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    +

    You can include the JavaScript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    - Components with Javascript + Components with JavaScript {% lucide "arrow-right" %} diff --git a/docs/src/components/table.njk b/docs/src/components/table.njk index 8193880..95e45e5 100644 --- a/docs/src/components/table.njk +++ b/docs/src/components/table.njk @@ -10,7 +10,8 @@ toc: {% from "macros/code_preview.njk" import code_preview %} {% from "macros/code_block.njk" import code_block %} -{% set code %} +{% set code %}
    +
    @@ -70,7 +71,8 @@ toc: -
    A list of your recent invoices.
    $2,500.00
    {% endset %} + +
    {% endset %} {{ code_preview("table", code, "w-full") }}

    Usage

    diff --git a/docs/src/components/tabs.njk b/docs/src/components/tabs.njk index f574234..79c352d 100644 --- a/docs/src/components/tabs.njk +++ b/docs/src/components/tabs.njk @@ -6,7 +6,7 @@ toc: - label: Usage id: usage children: - - label: HTML + Javascript + - label: HTML + JavaScript id: usage-default - label: Jinja and Nunjucks id: usage-macro @@ -90,11 +90,11 @@ document.addEventListener('alpine:init', () => {

    Usage

    -

    HTML + Javascript

    +

    HTML + JavaScript

    {% lucide "circle-alert" %} -

    This component requires Javascript.

    +

    This component requires JavaScript.

    @@ -106,12 +106,12 @@ document.addEventListener('alpine:init', () => {
  • A series of <div role="tabpanel"> that holds the tab panels corresponding to each tab button.
    • -

    You can include the Javascript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    +

    You can include the JavaScript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    - Components with Javascript + Components with JavaScript {% lucide "arrow-right" %} diff --git a/docs/src/components/toast.njk b/docs/src/components/toast.njk index 529fd14..c328077 100644 --- a/docs/src/components/toast.njk +++ b/docs/src/components/toast.njk @@ -6,7 +6,7 @@ toc: - label: Usage id: usage children: - - label: HTML + Javascript + - label: HTML + JavaScript id: usage-default children: - label: Append a toast @@ -52,11 +52,11 @@ toc:

    Usage

    -

    HTML + Javascript

    +

    HTML + JavaScript

    {% lucide "circle-alert" %} -

    This component requires Javascript.

    +

    This component requires JavaScript.

    @@ -64,12 +64,12 @@ toc:

    The <template id="toast-template"> bit is only required if you plan on using the $toast() method (see below).

    -

    You will also need to include the Javascript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    +

    You will also need to include the JavaScript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. x-bind, x-data, @click).

    - Components with Javascript + Components with JavaScript {% lucide "arrow-right" %} @@ -191,7 +191,7 @@ document.addEventListener('alpine:init', () => {
  • action (optional): an object to define an action button:
    • label: the label of the action button.
      • -
    • click (optional): a string of Javascript to execute when the button is clicked.
      • +
    • click (optional): a string of JavaScript to execute when the button is clicked.
    • url (optional): a URL to link to when the button is clicked.
    • diff --git a/docs/src/installation.njk b/docs/src/installation.njk index 6ff8bc3..a7fd718 100644 --- a/docs/src/installation.njk +++ b/docs/src/installation.njk @@ -14,7 +14,7 @@ toc: id: install-css-import - label: That's it id: install-css-done - - label: Components with Javascript + - label: Components with JavaScript id: install-js - label: Use the CLI id: install-cli @@ -67,20 +67,20 @@ toc:

    That's it

    You can now use any of the Basecoat classes in your project (e.g. btn, card, input, etc). Read the documentation about each component to get started (e.g. button, card, input, etc).

    -

    Some components (e.g. Select) require Javascript code to work.

    +

    Some components (e.g. Select) require JavaScript code to work.

    -

    Components with Javascript

    +

    Components with JavaScript

    -

    Some components require Javascript code to work.

    +

    Some components require JavaScript code to work.

    The documentation provides Alpine.js code snippets to cover that. Make sure to install Alpine.js if you decide to use them.

    For simple components like Accordion or Slider, you will notice some inline Alpine.js code that you can just copy along with the rest of the HTML.

    For more complex components (Dialog, Dropdown Menu, Popover, Select, Tabs and Toast), you have one of 2 options:

      -
    • Copy the Javascript snippet provided in the documentation page into your project.
      • +
    • Copy the JavaScript snippet provided in the documentation page into your project.

    • Download the script as a separate file and include it in your project (or let the CLI do it for you). If you use this approach, make sure to load the file before the Alpine.js core JS file and register the component on the alpine:init event. For example:

      {% set code %} @@ -93,7 +93,7 @@ toc: {{ code_block(code, "html") }}
    -

    You are also welcome to write your own Javascript.

    +

    You are also welcome to write your own JavaScript.

    All of the components try and implement WAI-ARIA standards to make them accessible.

    @@ -117,15 +117,15 @@ toc: {{ tabs(id="cli-execution", tabsets=exec_tabsets, label="Execute CLI commands to add components:") }}
    -

    You will be asked to confirm the template engine and destination directory for the Javascript and macros.

    +

    You will be asked to confirm the template engine and destination directory for the JavaScript and macros.

    Use Nunjucks or Jinja macros

    -

    For more complex components, you can use Nunjucks or Jinja macros to help you generate the HTML and Javascript code.

    +

    For more complex components, you can use Nunjucks or Jinja macros to help you generate the HTML and JavaScript code.

    To install them, either copy them directly from the GitHub repository or use the CLI to do the work for you.

    -

    For example, here's how you could use the select() macro to generate the HTML and Javascript code for a Select component:

    +

    For example, here's how you could use the select() macro to generate the HTML and JavaScript code for a Select component:

    {% set code %}{% raw %}{% call select() %}
    Fruits @@ -137,7 +137,7 @@ toc:
    {% endcall %}{% endraw %}{% endset %} {{ code_block(code, "jinja") }} -

    Make sure to include the Javascript code before Alpine.js core JS file:

    +

    Make sure to include the JavaScript code before Alpine.js core JS file:

    {% set code %}