Mini Calendar

# Brok UI: Mini Calendar (`mini-calendar`)

A compact week strip: weekday over day number, a month label, arrows that page by a week, ISO value, keyboard navigation, min/max bounds; localized with Intl.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add mini-calendar
```

## Usage

```blade
{{-- A live week strip: the arrows page by a week, the month label follows, and the pick posts an ISO date. --}}
<x-ui.mini-calendar name="day" value="2026-09-24" />
```

## Props

- `name` (string, default `mini-calendar`) — Hidden input name.
- `value` (string, default ``) — Selected ISO date.
- `start` (string, default ``) — First day shown; defaults to the week of value or today, aligned to firstDay.
- `days` (int, default `7`) — How many days to show (3-14).
- `locale` (mixed|null, default `null`) — Intl locale override.
- `firstDay` (int, default `1`) — First weekday alignment for the strip (0 = Sunday).
- `min` (mixed|null, default `null`) — ISO date lower bound; earlier days are disabled.
- `max` (mixed|null, default `null`) — ISO date upper bound; later days are disabled.

## Use when

- Use when date, time, or bounded-value context helps users enter valid values faster and with fewer errors.
- Embedding a compact, always-visible week strip for picking a nearby day, such as in a booking or scheduling widget.
- Wanting a smaller footprint than the full calendar month grid.

## Avoid when

- Do not force a picker when expert users can type the value faster and validation is straightforward.
- Needing a full month view or a range selection; use calendar or date-range-picker instead.

## Anti-patterns

- Forcing a picker when typing is faster

## Rules

- Use the `<brok:mini-calendar>` tag (or `<x-ui.mini-calendar>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/mini-calendar
- Registry JSON (files, props, contract): https://brokui.dev/r/open/mini-calendar.json

{{--
    Props:
    - value: the selected ISO date; start: the first day shown (defaults to the
      week of `value` or today, aligned to `first-day`); days: how many to show.
    - The arrows page by that many days and the month label follows the strip.
    - min / max: ISO bounds; days outside them are disabled.
--}}
@props([
    'name' => 'mini-calendar',
    'value' => '',
    'start' => '',
    'days' => 7,
    'locale' => null,
    'firstDay' => 1,
    'min' => null,
    'max' => null,
])

{{--
    Mini Calendar — a compact week strip (weekday over day number) with a month
    label and prev/next arrows that page the strip. The selected day posts as
    an ISO yyyy-mm-dd hidden value and dispatches `change`; Arrow keys move
    between days, Enter/Space select. Localized with Intl.
--}}
@php
    $count = max(3, min(14, (int) (is_array($days) ? 7 : $days)));
    $config = ['value' => $value, 'start' => $start, 'days' => $count, 'locale' => $locale, 'firstDay' => (int) $firstDay, 'min' => $min, 'max' => $max];
@endphp

<section
    x-data="uiMiniCalendar(@js($config))"
    {{-- Modelable: `x-model` (Alpine) and `wire:model` (Livewire binds through
         the same x-model contract) attach to the root. Inert without either. --}}
    x-modelable="model"
    data-slot="mini-calendar"
    :aria-label="@js(__('Date picker for')) + ' ' + monthLabel"
    {{ $attributes->except(['name'])->merge(['class' => 'inline-block w-fit rounded-md border border-border bg-card p-3 text-card-foreground']) }}
>
    @if ($name)
        <input type="hidden" name="{{ $name }}" :value="value" />
    @endif

    {{-- Header --}}
    <div class="mb-2 flex items-center justify-between gap-2">
        <h3 class="text-sm font-medium" aria-live="polite" x-text="monthLabel"></h3>
        <div class="flex items-center gap-1">
            <button type="button" @click="page(-1)" aria-label="{{ __('Previous week') }}" class="inline-flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none">
                <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 rtl:-scale-x-100"><path d="m15 18-6-6 6-6" /></svg>
            </button>
            <button type="button" @click="page(1)" aria-label="{{ __('Next week') }}" class="inline-flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none">
                <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 rtl:-scale-x-100"><path d="m9 18 6-6-6-6" /></svg>
            </button>
        </div>
    </div>

    {{-- Day strip --}}
    <div role="radiogroup" aria-label="{{ __('Select a day') }}" class="flex items-stretch gap-1" @keydown="onKey($event)">
        <template x-for="day in visible" :key="day.iso">
            <button
                type="button"
                role="radio"
                :aria-checked="day.iso === value"
                :aria-disabled="day.disabled ? 'true' : null"
                :aria-label="day.long"
                :data-date="day.iso"
                :data-today="day.today || null"
                :tabindex="day.iso === focusIso ? 0 : -1"
                @click="select(day.iso)"
                class="group flex w-10 cursor-pointer flex-col items-center gap-1 rounded-md py-1 text-center outline-none focus-visible:ring-2 focus-visible:ring-ring aria-[disabled=true]:cursor-not-allowed aria-[disabled=true]:opacity-40"
            >
                <span class="text-2xs font-medium uppercase tracking-wide text-muted-foreground transition-colors group-aria-checked:text-foreground" x-text="day.weekday"></span>
                <span
                    class="flex size-8 items-center justify-center rounded-full text-sm font-medium tabular-nums text-foreground transition-colors group-hover:bg-accent group-hover:text-accent-foreground group-aria-checked:bg-primary group-aria-checked:text-primary-foreground group-aria-checked:hover:bg-primary group-data-[today=true]:font-semibold motion-reduce:transition-none"
                    x-text="day.number"
                ></span>
                {{-- Today: a dot under the number; it goes light on the selected fill. --}}
                <span class="size-1 rounded-full" :class="day.today ? 'bg-primary group-aria-checked:bg-primary/40' : 'bg-transparent'" aria-hidden="true"></span>
            </button>
        </template>
    </div>
</section>

/**
 * Mini calendar behavior — a week strip that pages by its own width.
 *
 * `start` is the first visible day (aligned to `firstDay` unless given);
 * `page(±1)` moves the strip by `days`. Selecting sets the ISO `value`, moves
 * the roving focus and dispatches `change` ({ value }). Arrow keys move between
 * the visible days and roll the strip at either edge; Home/End jump to the
 * strip's ends. Labels come from Intl for the given locale.
 *
 * Self-registers on `alpine:init` so import order does not matter.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiMiniCalendar', (config = {}) => ({
        value: config.value || '',
        days: config.days ?? 7,
        locale: config.locale || document.documentElement.lang || 'en',
        firstDay: config.firstDay ?? 1,
        min: config.min || '',
        max: config.max || '',
        startIso: '',
        focusIso: '',
        visible: [],
        monthLabel: '',
        root: null,

        init() {
            this.root = this.$el;
            const anchor = config.start ? this.fromIso(config.start) : this.value ? this.fromIso(this.value) : new Date();
            let start = anchor;
            if (!config.start) {
                // Align to the week that holds the anchor.
                const lead = (anchor.getDay() - this.firstDay + 7) % 7;
                start = new Date(anchor.getFullYear(), anchor.getMonth(), anchor.getDate() - lead);
            }
            this.startIso = this.toIso(start);
            this.focusIso = this.value || this.toIso(new Date());
            this.build();
            if (!this.visible.some((d) => d.iso === this.focusIso)) this.focusIso = this.visible[0].iso;
        },

        /**
         * Modelable value (`x-modelable="model"` on the root): the ISO date or
         * ''. An inbound date outside the visible strip moves the strip to it.
         */
        get model() {
            return this.value;
        },
        set model(v) {
            const next = v == null ? '' : String(v);
            if (next === this.value) return;
            this.value = next;
            if (next === '') return;
            this.focusIso = next;
            if (!this.visible.some((d) => d.iso === next)) {
                const anchor = this.fromIso(next);
                const lead = (anchor.getDay() - this.firstDay + 7) % 7;
                this.startIso = this.toIso(new Date(anchor.getFullYear(), anchor.getMonth(), anchor.getDate() - lead));
                this.build();
            }
        },

        toIso(date) {
            return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
        },
        fromIso(iso) {
            const [y, m, d] = iso.split('-').map(Number);
            return new Date(y, m - 1, d);
        },
        addDays(iso, n) {
            const d = this.fromIso(iso);
            d.setDate(d.getDate() + n);
            return this.toIso(d);
        },
        isDisabled(iso) {
            return (this.min && iso < this.min) || (this.max && iso > this.max);
        },

        build() {
            const today = this.toIso(new Date());
            const weekday = new Intl.DateTimeFormat(this.locale, { weekday: 'short' });
            const long = new Intl.DateTimeFormat(this.locale, { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' });
            this.visible = Array.from({ length: this.days }, (_, i) => {
                const iso = this.addDays(this.startIso, i);
                const date = this.fromIso(iso);
                return {
                    iso,
                    number: date.getDate(),
                    weekday: weekday.format(date).replace(/\.$/, '').slice(0, 2),
                    long: long.format(date),
                    today: iso === today,
                    disabled: this.isDisabled(iso),
                };
            });
            // "June 2026", or "Jun – Jul 2026" when the strip crosses a month.
            const first = this.fromIso(this.visible[0].iso);
            const last = this.fromIso(this.visible[this.visible.length - 1].iso);
            if (first.getMonth() === last.getMonth()) {
                this.monthLabel = new Intl.DateTimeFormat(this.locale, { month: 'long', year: 'numeric' }).format(first);
            } else {
                const short = new Intl.DateTimeFormat(this.locale, { month: 'short' });
                const year = new Intl.DateTimeFormat(this.locale, { year: 'numeric' });
                this.monthLabel = `${short.format(first)} – ${short.format(last)} ${year.format(last)}`;
            }
        },

        page(direction) {
            this.startIso = this.addDays(this.startIso, direction * this.days);
            this.build();
            if (!this.visible.some((d) => d.iso === this.focusIso)) this.focusIso = this.visible[0].iso;
        },

        select(iso) {
            if (this.isDisabled(iso)) return;
            this.value = iso;
            this.focusIso = iso;
            this.$dispatch('change', { value: iso });
        },

        focusDay(iso) {
            this.focusIso = iso;
            if (!this.visible.some((d) => d.iso === iso)) {
                this.startIso = iso < this.startIso ? this.addDays(this.startIso, -this.days) : this.addDays(this.startIso, this.days);
                this.build();
            }
            this.$nextTick(() => this.root.querySelector(`[data-date="${iso}"]`)?.focus());
        },

        onKey(event) {
            const rtl = getComputedStyle(this.root).direction === 'rtl';
            switch (event.key) {
                case 'ArrowRight': this.focusDay(this.addDays(this.focusIso, rtl ? -1 : 1)); break;
                case 'ArrowLeft': this.focusDay(this.addDays(this.focusIso, rtl ? 1 : -1)); break;
                case 'Home': this.focusDay(this.visible[0].iso); break;
                case 'End': this.focusDay(this.visible[this.visible.length - 1].iso); break;
                case 'Enter':
                case ' ': this.select(this.focusIso); break;
                default: return;
            }
            event.preventDefault();
        },
    }));
});