Initial API thoughts

[joshuadavidthomas]

This is a discussion to gather my thoughts about the initial API for django-bird. All of this has been bouncing around in my head for a while, but I've never taken the time to actually write it down until now. I'm still not 100% on what the final API for defining and using django-bird components is, but I hope in actually getting it out of my head and down on the page that the obvious path will reveal itself.

Anyone is welcome to comment, to offer your own thoughts, or even alternatives if you should have one.

[joshuadavidthomas]

Single component (basic)

Definition

{# bird/h1.html #}
<h1>
    {{ slot }}
</h1>
<style>
    h1 {
        font-size: 2rem;
    }
</style>

{# bird/h1.html #}
<h1>
    {{ slot name="default" }}
</h1>
<style>
    h1 {
        font-size: 2rem;
    }
</style>

{# bird/h1.html #}
<h1>
    {% slot %}
        Fallback content
    {% endslot %}
</h1>
<style>
    h1 {
        font-size: 2rem;
    }
</style>

{# bird/h1.html #}
<h1>
    {% slot default %}
        Fallback content
    {% endslot default %}
</h1>
<style>
    h1 {
        font-size: 2rem;
    }
</style>

Usage

<bird:h1>
    This is an H1 component
</bird:h1>

[joshuadavidthomas]

Single component (named slots)

Definition

{# bird/h1.html #}
<h1>
    {% slot %}
    {% endslot %}
</h1>
{% if slots.subheading %}
    <p role="doc-subtitle">
        {% slot subheading %}
        {% endslot subheading %}
    </p>
{% endif %}
<style>
    h1 {
        font-size: 2rem;
    }
    p {
        font-size: 1.25rem;
    }
</style>

Usage

<bird:h1>
    This is an H1 component
    <bird:h1 slot="subheading">
        ...with a subheading
    </bird:h1>
</bird:h1>

[joshuadavidthomas]

Multiple/grouped components

Directory structure

I'm using a heading component as a simple example, even though in the real world you wouldn't likely split out a heading component this way.

Option A

bird
└── heading
    ├── h1.html
    ├── h2.html
    ├── h3.html
    ├── h4.html
    ├── h5.html
    ├── h6.html
    └── index.html

Option B

If index.html doesn't make sense, maybe having the main template be the same name as the directory would be fine:

bird
└── heading
    ├── heading.html
    ├── h1.html
    ├── h2.html
    ├── h3.html
    ├── h4.html
    ├── h5.html
    └── h6.html

Option C

bird
├── heading.html
├── heading.h1.html
├── heading.h2.html
├── heading.h3.html
├── heading.h4.html
├── heading.h5.html
└── heading.h6.html

Definition

{# bird/heading/index.html #}
{% if level == "1" %}
    <bird:heading.h1>{{ slot }}</bird:heading.h1>
...

Usage

<bird:heading level="1">
    This is an H1 component
</bird:heading>
<bird:heading level="2">
    This is an H2 component
</bird:heading>
...

[joshuadavidthomas]

Component islands

Definition

{# bird/carousel/index.html #}
{# TODO #}

{# bird/carousel/item.html #}
{# TODO #}

Usage

{# 11ty/is-land style #}
<bird:carousel on="idle">
    <bird:carousel.item />
    <bird:carousel.item />
    <bird:carousel.item />
</bird:carousel>

{# Astro style #}
<bird:carousel client="idle">
    <bird:carousel.item />
    <bird:carousel.item />
    <bird:carousel.item />
</bird:carousel>

Client directives

Directive signifier choices:

• on (11ty/is-lands)
• client (Astro)

Directive states:

• load
• idle
• visible
• media
• interaction

Inspiration and references

• Astro Islands
• Astro Template Directives Reference
• Islands Architecture, blog post by Preact creator Jason Miller
• 11ty/is-lands, <is-land> Web Component library from 11ty

[joshuadavidthomas]

A major impetus for this wanting to create this library in the first place is Caleb Porzio's talk introducing his component library, Flux, at Laracon US 2024:

Flux, the UI Library for Livewire | Caleb Porzio at Laracon US 2024 in Dallas, TX

[joshuadavidthomas]

Component examples

Accordion

A basic component with sub-components.

<flux:accordion>
    <flux:accordion.item>
        <flux:accordion.heading>What's your refund policy?</flux:accordion.heading>

        <flux:accordion.content>
            If you are not satisfied with your purchase, we offer a 30-day money-back guarantee. Please contact our support team for assistance.
        </flux:accordion.content>
    </flux:accordion.item>

    <flux:accordion.item>
        <flux:accordion.heading>Do you offer any discounts for bulk purchases?</flux:accordion.heading>

        <flux:accordion.content>
            Yes, we offer special discounts for bulk orders. Please reach out to our sales team with your requirements.
        </flux:accordion.content>
    </flux:accordion.item>

    <flux:accordion.item>
        <flux:accordion.heading>How do I track my order?</flux:accordion.heading>

        <flux:accordion.content>
            Once your order is shipped, you will receive an email with a tracking number. Use this number to track your order on our website.
        </flux:accordion.content>
    </flux:accordion.item>
</flux:accordion>

Autocomplete

A form input with a synced field. I imagine swapping in Alpine's x-model for wire:model (I assume a Livewire thing) would accomplish the same thing.

<flux:autocomplete wire:model="state" label="State of residence">
    <flux:autocomplete.item>Alabama</flux:autocomplete.item>
    <flux:autocomplete.item>Arkansas</flux:autocomplete.item>
    <flux:autocomplete.item>California</flux:autocomplete.item>
    <!-- ... -->
</flux:autocomplete>

Card

With a heading and subheading, in a swapped order.

<flux:card size="sm">
    <flux:subheading>Year to date</flux:subheading>

    <flux:heading size="xl" class="mb-1">$7,532.16</flux:heading>

    <div class="flex items-center gap-2">
        <flux:icon.arrow-trending-up variant="micro" class="text-green-600 dark:text-green-500" />

        <span class="text-sm text-green-600 dark:text-green-500">15.2%</span>
    </div>
</flux:card>

Dropdown

<flux:dropdown>
    <flux:button icon-trailing="chevron-down">Options</flux:button>

    <flux:menu>
        <flux:menu.item icon="plus">New post</flux:menu.item>

        <flux:menu.separator />

        <flux:menu.submenu heading="Sort by">
            <flux:menu.radio.group>
                <flux:menu.radio checked>Name</flux:menu.radio>
                <flux:menu.radio>Date</flux:menu.radio>
                <flux:menu.radio>Popularity</flux:menu.radio>
            </flux:menu.radio.group>
        </flux:menu.submenu>

        <flux:menu.submenu heading="Filter">
            <flux:menu.checkbox checked>Draft</flux:menu.checkbox>
            <flux:menu.checkbox checked>Published</flux:menu.checkbox>
            <flux:menu.checkbox>Archived</flux:menu.checkbox>
        </flux:menu.submenu>

        <flux:menu.separator />

        <flux:menu.item variant="danger" icon="trash">Delete</flux:menu.item>
    </flux:menu>
</flux:dropdown>

Modal

<flux:modal.trigger name="edit-profile">
    <flux:button>Edit profile</flux:button>
</flux:modal.trigger>

<flux:modal name="edit-profile" class="md:w-96 space-y-6">
    <div>
        <flux:heading size="lg">Update profile</flux:heading>
        <flux:subheading>Make changes to your personal details.</flux:subheading>
    </div>

    <flux:input label="Name" placeholder="Your name" />

    <flux:input label="Date of birth" type="date" />

    <div class="flex">
        <flux:spacer />

        <flux:button type="submit" variant="primary">Save changes</flux:button>
    </div>
</flux:modal>