FRD: Availability Picker

Document Summary

Field	Details
Feature Name	Availability Picker
Status	Draft
Owner	David Holmes
Contributors	Design, Engineering
Target Release	v2.0.0 (P2)
Related Links	Roadmap item #54
Last Updated	2026-05-26

---

Introduction

Overview

Availability Picker is a scheduling widget that combines InlineCalendar with a time-slot grid to let users select one or more date-and-time combinations for availability or appointment scheduling. It produces a structured payload of selected slots that consumers can submit to a booking API. The existing InlineCalendar and ScheduleCalendar provide the date-selection foundation; this widget adds the time-slot grid, multi-day selection, and structured output.

Goals

• Deliver an <AvailabilityPicker> component that pairs a calendar with a time-slot grid.
• Support multi-day selection for indicating availability across multiple dates.
• Produce a structured payload of selected date/time slots.
• Compose existing InlineCalendar for date selection.
• Ship Storybook stories with realistic scheduling scenarios.

Non-Goals

• Backend booking API integration or availability checking.
• Timezone conversion (consumer provides slots in the desired timezone).
• Recurring availability rules (one-off selection only).
• Integration with external calendar services (Google Calendar, Outlook, etc.).
• Drag-to-select across multiple time slots (click-to-toggle only).

---

Scope

In Scope

Area	Description
Component	<AvailabilityPicker> combining calendar and time-slot grid
Date Selection	InlineCalendar composition for selecting dates
Time-Slot Grid	Grid of time slots (configurable interval) for each selected date
Multi-Day	Users can select slots across multiple days
Structured Payload	onChange fires with { date: string; time: string }[]
States	Loading time slots, no available slots, error
Stories	Storybook stories for single-day, multi-day, and edge cases

Out of Scope

Area	Reason
Backend availability checking	Consumer provides available slots; widget handles selection
Timezone conversion	Consumer responsibility
Recurring availability	One-off selection; recurring patterns are ScheduleCalendar territory
Drag-to-select	Click-to-toggle is simpler and more accessible
External calendar sync	Application-layer concern

---

Users and Pain Points

User Groups

User	Description	Needs
Developers	Engineers building scheduling features	A composable date+time picker using DS components
Designers	Design-system consumers	Consistent scheduling UX aligned with DS tokens
End Users	People selecting availability or booking times	Intuitive date and time selection across multiple days

Pain Points

User	Pain Point	Impact
Developers	Building date+time selection requires wiring calendar, time grid, and state management from scratch	Complex implementation, inconsistent UX
End Users	Many scheduling UIs require selecting one day at a time, requiring multiple round-trips	Frustrating multi-day availability indication

---

Definitions

Term	Definition
Availability Picker	A widget combining a calendar and time-slot grid for selecting date/time combinations
Time Slot	A selectable time option within a day (e.g., “9:00 AM”, “9:30 AM”)
Slot Interval	The time gap between consecutive slots (e.g., 15 min, 30 min, 60 min)
Selected Slots	The structured list of date/time combinations the user has chosen

---

Current State

Existing Behavior

InlineCalendar provides an always-visible month calendar with day selection and event dots. ScheduleCalendar provides a custody/assignment calendar with party-based day coloring. Neither component includes a time-slot selection layer or multi-day availability indication.

Current Limitations

• No time-slot grid component exists in the design system.
• InlineCalendar supports single-date selection only.
• No structured payload for date+time combinations.
• No multi-day selection pattern.

Existing Workarounds

• Developers build custom time-slot grids with buttons or radio groups.
• Multi-day availability requires multiple calendar interactions or external tools (Calendly, etc.).

---

Proposed Solution

Summary

Introduce <AvailabilityPicker> that renders an InlineCalendar on the left (or top on mobile) and a time-slot grid on the right (or bottom). When a user selects a date on the calendar, the time-slot grid shows available slots for that date. Users toggle slots on/off by clicking. Selected slots across all dates are tracked and emitted via onChange. A summary section below shows all selected date/time pairs.

Key Capabilities

• Calendar-driven date selection via InlineCalendar.
• Configurable time-slot grid (interval, start hour, end hour).
• Multi-day selection: slots selected on one date persist when navigating to another date.
• Structured onChange payload with all selected slots.
• Summary display of selected slots with remove capability.
• Available vs. unavailable slot states (consumer marks which slots are available).

User Experience

Users see a calendar alongside a time-slot grid. They click a date on the calendar, and the grid shows time slots for that day. Available slots are clickable; unavailable slots are greyed out. Clicking a slot toggles it. A summary below lists all selected slots across all dates. Users can remove a slot from the summary by clicking its remove button.

Developer Experience

<AvailabilityPicker
  availableSlots={[
    { date: "2026-06-01", times: ["09:00", "09:30", "10:00", "10:30"] },
    { date: "2026-06-02", times: ["14:00", "14:30", "15:00"] },
  ]}
  slotInterval={30}
  onChange={(selected) => setSelectedSlots(selected)}
/>

---

Requirements

ID	Requirement	Priority	Notes
FR-001	AvailabilityPicker renders a calendar alongside a time-slot grid	Must	-
FR-002	Time-slot grid shows slots for the selected calendar date	Must	-
FR-003	Multi-day selection persists slots across date navigation	Must	-
FR-004	onChange fires with structured { date, time }[] payload	Must	-
FR-005	Summary section displays all selected slots with remove	Should	-
FR-006	Available vs. unavailable slot states are visually distinct	Must	-
FR-007	Loading, empty (no slots), and error states are handled	Must	-

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

---

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	availableSlots prop accepts { date: string; times: string[] }[] defining which slots are selectable	Consumer controls availability	Must
FUNC-002	slotInterval prop configures the display interval (15, 30, or 60 minutes)	Flexible for different use cases	Should
FUNC-003	Clicking an available slot toggles it selected/unselected	Intuitive toggle UX	Must
FUNC-004	Unavailable time slots (not in availableSlots) render as disabled/greyed	Clear distinction from available	Must
FUNC-005	Navigating to a different calendar date shows that date’s time slots while preserving prior selections	Multi-day workflow	Must
FUNC-006	Summary section lists all selected slots grouped by date with remove buttons	Review and edit selections	Should
FUNC-007	Calendar dates with available slots show event dots	Visual cue for availability	Should
FUNC-008	When no slots are available for a selected date, display “No available times” message	Clear feedback	Must
FUNC-009	onChange fires on every selection/deselection with the complete selected set	Real-time payload updates	Must

---

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Renders in under 50ms for 30 days with 20 slots each	Performance	Must
NFR-002	Time-slot grid and calendar are keyboard-navigable	Accessibility	Must
NFR-003	Works in light and dark themes	Theming	Must
NFR-004	Responsive layout: side-by-side on desktop, stacked on mobile	Responsiveness	Must
NFR-005	No new runtime dependencies beyond InlineCalendar	Maintainability	Must

---

API / Interface Requirements

Public API

Name	Type	Description	Required
availableSlots	AvailableDay[]	Dates and their available time strings	Yes
value	SelectedSlot[]	Currently selected date/time pairs (controlled)	No
onChange	(selected: SelectedSlot[]) => void	Selection change callback	Yes
slotInterval	15 | 30 | 60	Time slot interval in minutes	No (default: 30)
minDate	string	Earliest selectable date (YYYY-MM-DD)	No
maxDate	string	Latest selectable date (YYYY-MM-DD)	No
isLoading	boolean	Show loading state for time slots	No
error	string	Error message	No
className	string	Additional CSS classes	No

Types

interface AvailableDay {
  date: string;   // YYYY-MM-DD
  times: string[]; // HH:MM in 24h format
}

interface SelectedSlot {
  date: string;  // YYYY-MM-DD
  time: string;  // HH:MM
}

Example Usage

import { AvailabilityPicker } from "@/components/ui/availability-picker";

const [selected, setSelected] = useState<SelectedSlot[]>([]);

<AvailabilityPicker
  availableSlots={[
    { date: "2026-06-01", times: ["09:00", "09:30", "10:00", "14:00", "14:30"] },
    { date: "2026-06-02", times: ["10:00", "10:30", "11:00"] },
  ]}
  value={selected}
  onChange={setSelected}
  slotInterval={30}
/>

API Notes

• Time strings use 24-hour format ("09:00", "14:30").
• Date strings use YYYY-MM-DD format matching InlineCalendar.
• value/onChange pattern enables controlled usage; uncontrolled is also supported (internal state).
• Calendar event dots are auto-generated from availableSlots dates.

---

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Time-slot grid uses role="grid" with aria-label including the selected date	-
A11Y-002	Each time slot is role="gridcell" and focusable with keyboard	Arrow keys navigate, Space/Enter toggles
A11Y-003	Selected slots have aria-pressed="true"	Toggle button pattern
A11Y-004	Unavailable slots have aria-disabled="true" and are skipped by arrow-key navigation	-
A11Y-005	Summary section is a list with remove buttons having descriptive aria-label	e.g., “Remove June 1 at 9:00 AM”
A11Y-006	Calendar delegates to InlineCalendar’s existing accessibility	-

Checklist

• Keyboard support is defined.
• Focus behavior is defined.
• Screen reader behavior is defined.
• Color contrast requirements are met.
• Reduced motion behavior is considered.
• Semantic HTML expectations are documented.
• ARIA usage is defined only where needed.

---

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	Storybook docs page with overview and props table	Storybook	Must
DOC-002	”When to use / When not to use” guidance	Storybook docs	Must
DOC-003	Stories for single-day selection, multi-day selection, and fully booked dates	Storybook	Must
DOC-004	Story demonstrating responsive layout (side-by-side and stacked)	Storybook	Should

---

Dependencies

Dependency	Type	Owner	Status	Notes
InlineCalendar	Engineering	Design System	Ready	Date selection
Button	Engineering	Design System	Ready	Time slot toggle buttons and remove buttons
Badge	Engineering	Design System	Ready	Selected slot summary tags
Design tokens	Design	Design System	Ready	Color, spacing, typography

---

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
No timezone handling may confuse users across timezones	Slots displayed without timezone context	Document that consumer should display timezone label; add optional timezone display prop
Large availability sets (30 days x 48 half-hour slots) create many DOM nodes	Performance concern	Render only the active date’s slots; summary uses virtual list if needed
Click-to-toggle (not drag) may be slow for selecting many consecutive slots	More clicks required	Add “Select All Available” shortcut button for the active date
No recurring availability	Users indicating weekly patterns must select each day individually	Intentionally one-off; recurring is ScheduleCalendar’s domain

---

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should a “Select All” button be included for each date’s available slots?	David Holmes	Open	—
Q-002	Should the time-slot grid support a duration concept (e.g., 1-hour meeting vs. 30-min slot)?	David Holmes	Open	—
Q-003	Should a timezone label be displayed?	David Holmes	Open	—
Q-004	Should the calendar support range selection (start date to end date) in addition to multi-day?	David Holmes	Open	—

---

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	Calendar renders via InlineCalendar with event dots on dates with available slots	FR-001, FUNC-007
AC-002	Selecting a date shows available time slots in the grid	FR-002, FUNC-001
AC-003	Clicking an available slot toggles it selected/deselected	FUNC-003
AC-004	Unavailable slots render as disabled and non-interactive	FUNC-004
AC-005	Navigating to another date preserves prior selections	FR-003, FUNC-005
AC-006	onChange fires with all selected slots on each toggle	FR-004, FUNC-009
AC-007	Summary section lists selected slots with working remove buttons	FR-005, FUNC-006
AC-008	”No available times” message shows for dates without slots	FUNC-008
AC-009	Layout is side-by-side on desktop and stacked on mobile	NFR-004
AC-010	All Storybook stories render without errors	DOC-003
AC-011	Component passes axe accessibility audit	NFR-002

---

LLM Handoff Instructions

Expected LLM Behavior

• Follow the requirements and acceptance criteria in this document.
• Do not expand scope beyond the In Scope section.
• Respect the Out of Scope section.
• Compose InlineCalendar for date selection; do not rebuild calendar UI.
• Use Button with toggle styling for time slots.
• Use Badge for selected-slot summary items.
• Implement responsive layout with CSS media queries or container queries.
• Only render time slots for the currently selected date; track all selections in state.
• Place stories under the SaaS Widgets Storybook section.

LLM Should Not

• Implement timezone conversion.
• Add recurring availability rules.
• Add drag-to-select interaction.
• Modify existing InlineCalendar component.
• Add external calendar service integration.

---

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Click-to-toggle rather than drag-to-select	More accessible, simpler implementation, works on touch	David Holmes
2026-05-26	Consumer provides available slots rather than generating from rules	Decouples from backend logic; more flexible	David Holmes
2026-05-26	Compose InlineCalendar rather than building a new calendar	Reuses tested calendar component; avoids duplication	David Holmes

---

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft