Time Slots

A day as a track to drag a booking across.

Source
$npx @dinachi/cli@latest add time-slots

10:45 to 12:00 GMT · 1 h 15 min

layout
past
disabled

Usage

import { useState } from "react"
import { Button } from "@/components/ui/button"
import { TimeSlots, type TimeSlot } from "@/components/ui/time-slots"

export function Room({ busy }: { busy: TimeSlot[] }) {
  const [slot, setSlot] = useState<TimeSlot | null>(null)
  return (
    <TimeSlots aria-label="Room" timeZone="GMT" busy={busy} value={slot} onValueChange={setSlot}>
      <Button size="sm" disabled={!slot}>Book</Button>
    </TimeSlots>
  )
}

Examples

10:45 to 12:00 GMT · 1 h 15 min

A room's day, with busy time a booking can't cross.
import { useState } from 'react';
import { Button } from '@/components/ui/button';
import { TimeSlots, type TimeSlot } from '@/components/ui/time-slots';

export function Example({ busy }: { busy: TimeSlot[] }) {
  const [slot, setSlot] = useState<TimeSlot | null>({ start: 645, end: 720 });
  return (
    <TimeSlots aria-label="Room" className="max-w-3xl" timeZone="GMT" busy={busy} value={slot} onValueChange={setSlot}>
      <Button size="sm" disabled={!slot}>Book</Button>
    </TimeSlots>
  );
}

Notes

Minutes and zones

Every time is minutes since midnight, in whatever zone timeZone names. Convert before you pass busy, and after you read value. Pass now as a Date with an IANA timeZone and the track works out the time there.

Pressing the track

Pressing free time starts a new booking there, even on top of the current one. Only the handles at either end resize it. Near the end of a free stretch, the new booking runs back from the press so it still fits.

Phone and desktop

Below 768px the day turns vertical, as half-hour rows. Tap a free row, then a later one to stretch the booking to it. Tapping a lone booked row clears it.

API

value
agent
{ start, end } | null
The booking, in minutes since midnight. 10:45 to 12:00 is { start: 645, end: 720 }.
defaultValue{ start, end } | null
Starting booking when uncontrolled.
onValueChange
agent
(value, details) => void
Runs on every change, for people and agents, including each step of a drag. details.cancel() refuses it.
timeZonestring
Required. Named beside the booking, such as GMT. When it is an IANA zone such as Europe/London, a now given as a Date is read in it.
mode
agent
"range" | "single" = "range"
single picks one time, such as an arrival, held for minDuration. Its value is still { start, end }; forms and agents get HH:MM.
min
agent
number = 480
Where the day starts, in minutes. 08:00 by default.
max
agent
number = 1200
Where the day ends, in minutes. 20:00 by default.
step
agent
number = 15
Minutes a booking snaps to.
busy
agent
{ start, end }[]
Taken time. A booking can't cross it.
now
agent
number | Date
The time now. Time before it is shaded and can't be booked. Minutes, or a Date read in timeZone against date: a later day has no past, an earlier one is all past.
minDuration
agent
number = step
The shortest booking, in minutes. Rounded up to a whole number of steps.
maxDuration
agent
number
The longest booking, in minutes. The whole day by default. Rounded down to a whole number of steps.
dateDate
The day being booked, named above the track.
formatTime(minutes: number) => string = 24-hour HH:MM
How a time reads in the ticks, rows and readout. Midnight reads 00:00 at either end of the day.
layout"auto" | "horizontal" | "vertical" = "auto"
horizontal is a track to drag across. vertical is rows of half an hour, or the nearest whole number of steps, to tap. auto switches at 768px.
localeLocale
A date-fns locale for the day's name.
dir"ltr" | "rtl"
Reading direction. The track and arrow keys follow it.
disabled
agent
boolean = false
Blocks people and agents.
namestring
Submits the booking as HH:MM/HH:MM, or HH:MM in single mode.
requiredboolean = false
Fails form validation until a time is booked.
childrenReactNode
Sits beside the readout, such as a Book button.

Agent

Inside an AgentProvider, it appears in agent.snapshot() as slider.

Reads

label

The aria-label, "Booking" by default.

value

The booking as ["HH:MM", "HH:MM"], "HH:MM" in single mode, or nothing.

Actions

setValue(["10:45", "12:00"])

Books a span. "11am to 12:30" works too; null clears it. In single mode one time, "3pm", is enough.

An agent's change runs through onValueChange like anyone's. isAgentChange(details) is true for it; details.cancel() refuses it. A span that crosses busy time, starts before now, leaves the day, misses the step, or is shorter or longer than allowed is refused with the reason.

await agent.act({
  steps: [{ ref: "Room", action: "setValue", args: [["14:00", "15:00"]] }],
})

Accessibility

  • The track is a slider named Time span, or Time in single mode, inside a group carrying the component's label. Its value text is the booking with its zone and length, such as 10:45 to 12:00 GMT, 1 h 15 min.
  • The slider's description lists busy and past time, since the arrows step over it.
  • In rows, each row is a button named with its time and whether it is free, booked, busy, past or unavailable. Only one row is in the tab order.
  • In rows, the readout is a live region, so the booking is announced as it changes. On the track, the slider announces it instead.
  • Busy and unavailable time is hatched, at 3:1 or more against free time in both themes, so it reads without color. Past time sits behind the now line.