laif-ds

# AppTimePicker ## Overview Standalone time picker component for selecting hours, minutes, and optionally seconds. Displays a trigger with a clock icon and opens a popover with scrollable columns for each time unit. Supports controlled/uncontrolled usage, UTC mode, clearable selection, min/max time constraints, multiple sizes, and visual variants. --- ## Props | Prop | Type | Default | Description | | ---------------- | ----------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------ | | `value` | `Date` | `undefined` | Controlled selected time as a Date object. | | `onChange` | `(date: Date \| undefined) => void` | `undefined` | Callback fired when the selected time changes. | | `onClear` | `() => void` | `undefined` | Callback fired when the value is cleared. | | `label` | `string \| React.ReactNode` | `undefined` | Label displayed above the trigger. | | `placeholder` | `string` | `"Seleziona orario"` | Placeholder text shown when no time is selected. | | `disabled` | `boolean` | `false` | Disables the time picker. | | `clearable` | `boolean` | `false` | Show a clear (X) button in the trigger to reset the selection. | | `className` | `string` | `""` | Additional CSS classes applied to the trigger element. | | `labelClassName` | `string` | `""` | CSS classes for the label element. | | `wrpClassName` | `string` | `""` | CSS classes for the outer wrapper `<div>`. | | `size` | `"sm" \| "default" \| "lg"` | `"default"` | Size variant of the trigger. | | `variant` | `"default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| "link"` | `"default"` | Visual variant of the trigger. | | `useUtc` | `boolean` | `false` | Use UTC time instead of local time. Shows a "UTC" badge. | | `withSeconds` | `boolean` | `false` | Show a seconds column in the time picker. | | `minuteStep` | `number` | `1` | Step interval for minute options (`1`-`59`). | | `secondStep` | `number` | `1` | Step interval for second options (`1`-`59`). | | `minTime` | `Date` | `undefined` | Minimum selectable time. Hours/minutes/seconds before this are disabled. | | `maxTime` | `Date` | `undefined` | Maximum selectable time. Hours/minutes/seconds after this are disabled. | | `id` | `string` | `undefined` | HTML `id` for the trigger element. | | `data-testid` | `string` | `undefined` | `data-testid` attribute for E2E testing (e.g. Playwright). | --- ## Behavior ### Time Selection - **Columns**: The popover displays scrollable columns for hours (00–23) and minutes. Minute values follow `minuteStep` and an optional seconds column follows `secondStep` when `withSeconds` is `true`. - **Scroll-to-selected**: When the popover opens, the selected value is automatically scrolled into view. - **Display format**: The trigger shows time in `HH:MM` format (or `HH:MM:SS` with `withSeconds`). ### Controlled vs Uncontrolled - **Controlled**: Pass `value` and `onChange` to manage state externally. The component detects controlled mode by checking if the `value` prop is provided (even if `undefined`). - **Uncontrolled**: Omit the `value` prop entirely. The component manages its own internal state. ### Clearable - **Trigger clear button**: When `clearable` is `true` and a value is selected, an X button appears in the trigger. - **Popover clear button**: A "Clear" button always appears at the bottom of the popover when a value is selected. - **Callbacks**: Both `onChange(undefined)` and `onClear()` are called when clearing. ### Min/Max Time Constraints - **Disabled options**: When `minTime` or `maxTime` is set, out-of-range hours are visually disabled and not selectable. - **Cascading constraints**: Minutes are constrained only when the selected hour matches the boundary hour. Seconds are constrained only when both hour and minute match. - **UTC-aware**: Constraints respect the `useUtc` setting. ### UTC Mode - When `useUtc` is `true`, all time reading/writing uses UTC methods (`getUTCHours`, `setUTCHours`, etc.). - A small "UTC" badge is displayed in the trigger. --- ## Exported Types ```ts type AppTimePickerSize = "sm" | "default" | "lg"; type AppTimePickerVariant = | "default" | "destructive" | "outline" | "secondary" | "ghost" | "link"; interface AppTimePickerProps { /* see Props table above */ } ``` --- ## Examples ### Basic ```tsx import { AppTimePicker } from "laif-ds"; import { useState } from "react"; export function BasicTimePicker() { const [time, setTime] = useState<Date | undefined>(); return ( <AppTimePicker value={time} onChange={setTime} label="Select Time" placeholder="Pick a time" /> ); } ``` ### With Seconds ```tsx import { AppTimePicker } from "laif-ds"; import { useState } from "react"; export function TimePickerWithSeconds() { const [time, setTime] = useState<Date | undefined>(); return ( <AppTimePicker value={time} onChange={setTime} withSeconds label="Time with Seconds" /> ); } ``` ### Clearable ```tsx import { AppTimePicker } from "laif-ds"; import { useState } from "react"; export function ClearableTimePicker() { const [time, setTime] = useState<Date | undefined>(new Date()); return ( <AppTimePicker value={time} onChange={setTime} clearable label="Clearable Picker" /> ); } ``` ### UTC Mode ```tsx import { AppTimePicker } from "laif-ds"; import { useState } from "react"; export function UtcTimePicker() { const [time, setTime] = useState<Date | undefined>(new Date()); return ( <AppTimePicker value={time} onChange={setTime} useUtc label="UTC Time Picker" /> ); } ``` ### Min/Max Time Constraints ```tsx import { AppTimePicker } from "laif-ds"; import { useState } from "react"; export function BusinessHoursTimePicker() { const [time, setTime] = useState<Date | undefined>(); const minTime = new Date(); minTime.setHours(9, 0, 0, 0); const maxTime = new Date(); maxTime.setHours(17, 30, 0, 0); return ( <AppTimePicker value={time} onChange={setTime} minTime={minTime} maxTime={maxTime} label="Business Hours Only" /> ); } ``` ### Sizes and Variants ```tsx import { AppTimePicker } from "laif-ds"; export function TimePickerVariants() { return ( <div className="flex flex-col gap-4"> <AppTimePicker size="sm" label="Small" /> <AppTimePicker size="default" label="Default" /> <AppTimePicker size="lg" label="Large" /> <AppTimePicker variant="outline" label="Outline Variant" /> <AppTimePicker variant="ghost" label="Ghost Variant" /> </div> ); } ``` ### Disabled ```tsx import { AppTimePicker } from "laif-ds"; export function DisabledTimePicker() { return <AppTimePicker value={new Date()} disabled label="Disabled Picker" />; } ``` ### In Dialog ```tsx import { AppTimePicker } from "laif-ds"; import { AppDialog } from "laif-ds"; import { Button } from "laif-ds"; import { useState } from "react"; export function TimePickerInDialog() { const [time, setTime] = useState<Date | undefined>(); const [open, setOpen] = useState(false); return ( <AppDialog open={open} onOpenChange={setOpen} title="Seleziona Orario" description="Scegli l'orario per la tua prenotazione." trigger={<Button>Apri Time Picker Dialog</Button>} footer={ <> <Button variant="outline" onClick={() => setOpen(false)}> Annulla </Button> <Button onClick={() => setOpen(false)}>Conferma</Button> </> } asChild > <div className="space-y-4"> <AppTimePicker value={time} onChange={setTime} label="Orario di inizio" placeholder="Seleziona un'orario" clearable /> {time && ( <div className="bg-d-muted/50 flex items-center gap-2 rounded border p-3 text-sm"> <span className="text-d-muted-foreground">Orario selezionato:</span> <span className="font-medium tabular-nums"> {time.toLocaleTimeString("it-IT", { hour: "2-digit", minute: "2-digit", })} </span> </div> )} </div> </AppDialog> ); } ``` --- ## Helper Component: TimePickerColumn The `TimePickerColumn` component is exported and can be used independently (e.g., inside the `DatePicker` component for datetime selection). ### TimePickerColumn Props | Prop | Type | Default | Description | | ---------------- | -------------------------------- | ----------- | ------------------------------------------------------- | | `options` | `number[]` | — | Array of numeric options to display. | | `value` | `number \| undefined` | `undefined` | Currently selected value. | | `onChange` | `(value: number) => void` | — | Callback fired when an option is selected. | | `type` | `"hour" \| "minute" \| "second"` | — | Column type — determines the header label (HH, MM, SS). | | `className` | `string` | `""` | Additional CSS classes for the column wrapper. | | `disabledValues` | `Set<number>` | `undefined` | Set of values that should be disabled (not selectable). | --- ## Notes - **Sizing**: Use `size` to control the trigger height (sm: h-8, default: h-9, lg: h-10). - **Variants**: Use `variant` to change the trigger's visual style (background, border, text color). - **UTC badge**: When `useUtc` is `true`, a small "UTC" label appears in the trigger for clarity. - **Controlled detection**: The component uses `props.hasOwnProperty("value")` to detect controlled mode, so passing `value={undefined}` keeps it controlled. - **Performance**: Option arrays (0–23 for hours, 0–59 for minutes/seconds) are memoized to avoid re-creation on every render. - **Accessibility**: The trigger has proper ARIA attributes. Disabled options in the columns are not focusable. - **Integration with DatePicker**: The `TimePickerColumn` sub-component is reused by `DatePicker` when `showTime` is enabled.