@alexgorbatchev/shadcn 0.0.19 → 0.0.21

package/llms/components/dates/Calendar.md

@@ -0,0 +1,539 @@
+# Calendar
+
+Story: @alexgorbatchev/shadcn/components/dates/Calendar
+Source: src/components/stories/dates/Calendar.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/dates/Calendar.stories.tsx)
+
+## Public imports
+
+```tsx
+import { Calendar, CalendarDayButton } from "@alexgorbatchev/shadcn/calendar";
+import { DirectionProvider, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, InputGroup, InputGroupAddon, InputGroupInput, Button, Field, FieldGroup, FieldLabel, Input, Popover, PopoverContent, PopoverTitle, PopoverTrigger, ToggleGroup, ToggleGroupItem, cn } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import type { ComponentProps, ReactElement } from "react";
+import type { DateRange } from "@daypicker/react";
+import { TZDate } from "@daypicker/react";
+import { useId, useState } from "react";
+import { CalendarIcon, Clock2Icon } from "lucide-react";
+```
+
+## Default component
+
+```tsx
+Calendar
+```
+
+## Story controls
+
+```tsx
+{ density: { control: "select", options: ["compact", "comfortable"] } }
+```
+
+## Default args
+
+```tsx
+{ defaultMonth: new Date(2026, 9), today: new Date(2026, 9, 8) }
+```
+
+## Default render
+
+```tsx
+function Render(args) {
+    const [date, setDate] = useState<Date | undefined>(new Date(2026, 9, 8));
+    return (<div>
+        <Calendar {...args} mode="single" selected={date} onSelect={setDate}/>
+        <output aria-label="Selected day">{date?.getDate()}</output>
+      </div>);
+}
+```
+
+## Examples
+
+Storybook CSF excerpts. Default args and render apply unless overridden. Local helpers, fixtures, decorators, and providers may be required; these are reference excerpts, not standalone consumer modules. Interaction tests are omitted.
+
+### Default
+
+```tsx
+{}
+```
+
+### Compact
+
+```tsx
+{
+    args: { density: "compact" }
+}
+```
+
+### Range
+
+```tsx
+{
+    render: function Render() {
+        const [range, setRange] = useState<DateRange | undefined>();
+        return (<div>
+        <Calendar mode="range" defaultMonth={new Date(2026, 9)} today={new Date(2026, 9, 8)} selected={range} onSelect={setRange} numberOfMonths={2}/>
+        <output aria-label="Selected range">
+          {range?.from?.getDate()} – {range?.to?.getDate()}
+        </output>
+      </div>);
+    }
+}
+```
+
+### Dropdowns
+
+```tsx
+{
+    args: {
+        captionLayout: "dropdown",
+        showWeekNumber: true,
+        startMonth: new Date(2020, 0),
+        endMonth: new Date(2030, 11),
+    }
+}
+```
+
+### DisabledDays
+
+```tsx
+{
+    args: { disabled: { dayOfWeek: [0, 6] } }
+}
+```
+
+### Multiple
+
+```tsx
+{
+    render: function Render() {
+        const [dates, setDates] = useState<Date[] | undefined>([]);
+        return (<div>
+        <Calendar mode="multiple" defaultMonth={new Date(2026, 9)} today={new Date(2026, 9, 8)} selected={dates} onSelect={setDates}/>
+        <output aria-label="Selected dates">{dates?.map((date) => date.getDate()).join(", ")}</output>
+      </div>);
+    }
+}
+```
+
+### RightToLeft
+
+```tsx
+{
+    args: { dir: "rtl" }
+}
+```
+
+### CustomCellSize
+
+```tsx
+{
+    args: { className: "[--cell-size:3rem]", components: { DayButton: PricedCalendarDayButton } }
+}
+```
+
+### RightToLeftCustomCellSize
+
+```tsx
+{
+    args: { ...CustomCellSize.args, dir: "rtl" }
+}
+```
+
+### BookedDates
+
+```tsx
+{
+    args: {
+        disabled: [new Date(2026, 9, 10), new Date(2026, 9, 11)],
+        modifiers: { booked: [new Date(2026, 9, 10), new Date(2026, 9, 11)] },
+        modifiersClassNames: { booked: "[&>button]:line-through" },
+    }
+}
+```
+
+### RightToLeftBookedDates
+
+```tsx
+{
+    args: { ...BookedDates.args, dir: "rtl" }
+}
+```
+
+### WeekNumbers
+
+```tsx
+{
+    args: { showWeekNumber: true }
+}
+```
+
+### RightToLeftWeekNumbers
+
+```tsx
+{
+    args: { showWeekNumber: true, dir: "rtl" }
+}
+```
+
+### TimeZone
+
+```tsx
+{
+    render: function Render(args) {
+        const [date, setDate] = useState<Date | undefined>(new TZDate(2026, 9, 8, "Pacific/Kiritimati"));
+        return (<div>
+        <Calendar {...args} mode="single" timeZone="Pacific/Kiritimati" defaultMonth={new TZDate(2026, 9, 1, "Pacific/Kiritimati")} today={new TZDate(2026, 9, 8, "Pacific/Kiritimati")} selected={date} onSelect={setDate}/>
+        <output aria-label="Selected instant">{date?.toISOString()}</output>
+        <output aria-label="Selected zoned date">
+          {date && new Intl.DateTimeFormat("en-US", { timeZone: "Pacific/Kiritimati", dateStyle: "long" }).format(date)}
+        </output>
+      </div>);
+    }
+}
+```
+
+### RightToLeftTimeZone
+
+```tsx
+{
+    render: function Render(args) {
+        const [date, setDate] = useState<Date | undefined>(new TZDate(2026, 9, 8, "Pacific/Kiritimati"));
+        return (<div>
+        <Calendar {...args} mode="single" timeZone="Pacific/Kiritimati" defaultMonth={new TZDate(2026, 9, 1, "Pacific/Kiritimati")} today={new TZDate(2026, 9, 8, "Pacific/Kiritimati")} selected={date} onSelect={setDate}/>
+        <output aria-label="Selected instant">{date?.toISOString()}</output>
+        <output aria-label="Selected zoned date">
+          {date && new Intl.DateTimeFormat("en-US", { timeZone: "Pacific/Kiritimati", dateStyle: "long" }).format(date)}
+        </output>
+      </div>);
+    },
+    args: { dir: "rtl" }
+}
+```
+
+### Presets
+
+```tsx
+{
+    render: function Render(args) {
+        const [date, setDate] = useState<Date | undefined>(new Date(2026, 9, 8));
+        const [month, setMonth] = useState(new Date(2026, 9, 1));
+        return (<Card className="w-fit">
+        <CardHeader>
+          <CardTitle>Schedule a reminder</CardTitle>
+          <CardDescription>Choose a date or a preset.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Calendar {...args} mode="single" month={month} onMonthChange={setMonth} selected={date} onSelect={setDate} fixedWeeks/>
+        </CardContent>
+        <CardFooter className="flex-col items-start gap-control-gap">
+          <ToggleGroup aria-label="Reminder presets" onValueChange={(values) => {
+                const offsets: Record<string, number> = { today: 0, tomorrow: 1, fortnight: 14 };
+                const offset = offsets[values[0] ?? ""];
+                if (offset !== undefined) {
+                    const next = new Date(2026, 9, 8 + offset);
+                    setDate(next);
+                    setMonth(new Date(next.getFullYear(), next.getMonth(), 1));
+                }
+            }}>
+            <ToggleGroupItem value="today">Today</ToggleGroupItem>
+            <ToggleGroupItem value="tomorrow">Tomorrow</ToggleGroupItem>
+            <ToggleGroupItem value="fortnight">In two weeks</ToggleGroupItem>
+          </ToggleGroup>
+          <output aria-label="Reminder date">{date && formatDate(date)}</output>
+        </CardFooter>
+      </Card>);
+    }
+}
+```
+
+### RightToLeftPresets
+
+```tsx
+{
+    render: function Render(args) {
+        const [date, setDate] = useState<Date | undefined>(new Date(2026, 9, 8));
+        const [month, setMonth] = useState(new Date(2026, 9, 1));
+        return (<Card className="w-fit">
+        <CardHeader>
+          <CardTitle>Schedule a reminder</CardTitle>
+          <CardDescription>Choose a date or a preset.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Calendar {...args} mode="single" month={month} onMonthChange={setMonth} selected={date} onSelect={setDate} fixedWeeks/>
+        </CardContent>
+        <CardFooter className="flex-col items-start gap-control-gap">
+          <ToggleGroup aria-label="Reminder presets" onValueChange={(values) => {
+                const offsets: Record<string, number> = { today: 0, tomorrow: 1, fortnight: 14 };
+                const offset = offsets[values[0] ?? ""];
+                if (offset !== undefined) {
+                    const next = new Date(2026, 9, 8 + offset);
+                    setDate(next);
+                    setMonth(new Date(next.getFullYear(), next.getMonth(), 1));
+                }
+            }}>
+            <ToggleGroupItem value="today">Today</ToggleGroupItem>
+            <ToggleGroupItem value="tomorrow">Tomorrow</ToggleGroupItem>
+            <ToggleGroupItem value="fortnight">In two weeks</ToggleGroupItem>
+          </ToggleGroup>
+          <output aria-label="Reminder date">{date && formatDate(date)}</output>
+        </CardFooter>
+      </Card>);
+    },
+    args: { dir: "rtl" }
+}
+```
+
+### TimeInputs
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        const [date, setDate] = useState<Date | undefined>(new Date(2026, 9, 8));
+        const [start, setStart] = useState("10:30:00"), [end, setEnd] = useState("12:30:00");
+        return (<Card className="w-fit">
+        <CardHeader>
+          <CardTitle>Book a session</CardTitle>
+          <CardDescription>Choose a date and time interval.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Calendar {...args} mode="single" selected={date} onSelect={setDate}/>
+        </CardContent>
+        <CardFooter className="flex-col items-start gap-panel">
+          <FieldGroup>
+            <Field>
+              <FieldLabel htmlFor={id + "-start"}>Start time</FieldLabel>
+              <InputGroup>
+                <InputGroupInput id={id + "-start"} type="time" step="1" value={start} onChange={(event) => setStart(event.target.value)}/>
+                <InputGroupAddon>
+                  <Clock2Icon aria-hidden="true"/>
+                </InputGroupAddon>
+              </InputGroup>
+            </Field>
+            <Field>
+              <FieldLabel htmlFor={id + "-end"}>End time</FieldLabel>
+              <InputGroup>
+                <InputGroupInput id={id + "-end"} type="time" step="1" value={end} onChange={(event) => setEnd(event.target.value)}/>
+                <InputGroupAddon>
+                  <Clock2Icon aria-hidden="true"/>
+                </InputGroupAddon>
+              </InputGroup>
+            </Field>
+          </FieldGroup>
+          <output aria-label="Session interval">
+            {date && formatDate(date)} {start} – {end}
+          </output>
+        </CardFooter>
+      </Card>);
+    }
+}
+```
+
+### RightToLeftTimeInputs
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        const [date, setDate] = useState<Date | undefined>(new Date(2026, 9, 8));
+        const [start, setStart] = useState("10:30:00"), [end, setEnd] = useState("12:30:00");
+        return (<Card className="w-fit">
+        <CardHeader>
+          <CardTitle>Book a session</CardTitle>
+          <CardDescription>Choose a date and time interval.</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Calendar {...args} mode="single" selected={date} onSelect={setDate}/>
+        </CardContent>
+        <CardFooter className="flex-col items-start gap-panel">
+          <FieldGroup>
+            <Field>
+              <FieldLabel htmlFor={id + "-start"}>Start time</FieldLabel>
+              <InputGroup>
+                <InputGroupInput id={id + "-start"} type="time" step="1" value={start} onChange={(event) => setStart(event.target.value)}/>
+                <InputGroupAddon>
+                  <Clock2Icon aria-hidden="true"/>
+                </InputGroupAddon>
+              </InputGroup>
+            </Field>
+            <Field>
+              <FieldLabel htmlFor={id + "-end"}>End time</FieldLabel>
+              <InputGroup>
+                <InputGroupInput id={id + "-end"} type="time" step="1" value={end} onChange={(event) => setEnd(event.target.value)}/>
+                <InputGroupAddon>
+                  <Clock2Icon aria-hidden="true"/>
+                </InputGroupAddon>
+              </InputGroup>
+            </Field>
+          </FieldGroup>
+          <output aria-label="Session interval">
+            {date && formatDate(date)} {start} – {end}
+          </output>
+        </CardFooter>
+      </Card>);
+    },
+    args: { dir: "rtl" }
+}
+```
+
+### DatePicker
+
+```tsx
+{
+    render: (args) => <DatePickerComposition {...args}/>
+}
+```
+
+### DatePickerCompact
+
+```tsx
+{
+    render: (args) => <DatePickerComposition {...args}/>,
+    args: { density: "compact" }
+}
+```
+
+### DatePickerRtl
+
+```tsx
+{
+    render: (args) => <DatePickerComposition {...args}/>,
+    args: { dir: "rtl" },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```
+
+### DatePickerPresets
+
+```tsx
+{
+    render: (args) => <DatePickerComposition {...args} hasPresets/>
+}
+```
+
+### DatePickerTime
+
+```tsx
+{
+    render: (args) => <DatePickerComposition {...args} hasTime/>
+}
+```
+
+### DatePickerRange
+
+```tsx
+{
+    render: (args) => <RangePicker {...args}/>
+}
+```
+
+### DatePickerBirthDate
+
+```tsx
+{
+    render: (args) => <BirthDatePicker {...args}/>
+}
+```
+
+### DatePickerInput
+
+```tsx
+{
+    render: (args) => <DateInputPickerExample {...args}/>
+}
+```
+
+### DatePickerInputCompact
+
+```tsx
+{
+    render: (args) => <DateInputPickerExample {...args}/>,
+    args: { density: "compact" }
+}
+```
+
+### DatePickerInputRtl
+
+```tsx
+{
+    render: (args) => <DateInputPickerExample {...args}/>,
+    args: { dir: "rtl" },
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ]
+}
+```
+
+### DatePickerNaturalLanguage
+
+```tsx
+{
+    render: (args) => <DateInputPickerExample {...args} isNaturalLanguage/>
+}
+```
+
+### DatePickerPresetsRtl
+
+```tsx
+{
+    render: (args) => <DatePickerComposition {...args} hasPresets/>,
+    args: { dir: "rtl" },
+    decorators: DatePickerRtl.decorators
+}
+```
+
+### DatePickerTimeRtl
+
+```tsx
+{
+    render: (args) => <DatePickerComposition {...args} hasTime/>,
+    args: { dir: "rtl" },
+    decorators: DatePickerRtl.decorators
+}
+```
+
+### DatePickerRangeRtl
+
+```tsx
+{
+    render: (args) => <RangePicker {...args}/>,
+    args: { dir: "rtl" },
+    decorators: DatePickerRtl.decorators
+}
+```
+
+### DatePickerBirthDateRtl
+
+```tsx
+{
+    render: (args) => <BirthDatePicker {...args}/>,
+    args: { dir: "rtl" },
+    decorators: DatePickerRtl.decorators
+}
+```
+
+### DatePickerNaturalLanguageRtl
+
+```tsx
+{
+    render: (args) => <DateInputPickerExample {...args} isNaturalLanguage/>,
+    args: { dir: "rtl" },
+    decorators: DatePickerRtl.decorators
+}
+```

package/llms/components/dates/DatePicker.md

@@ -0,0 +1,97 @@
+# DatePicker
+
+Story: @alexgorbatchev/shadcn/components/dates/DatePicker
+Source: src/components/stories/dates/DatePicker.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/dates/DatePicker.stories.tsx)
+
+## Public imports
+
+```tsx
+import { DatePicker, DateRangePicker } from "@alexgorbatchev/shadcn/calendar";
+import { Button } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { fr } from "@daypicker/react/locale/fr";
+import { useState, type ReactElement } from "react";
+```
+
+## Default component
+
+```tsx
+DatePicker
+```
+
+## Default args
+
+```tsx
+{
+    label: "Appointment date",
+    calendarProps: { defaultMonth: new Date(2026, 9), today: new Date(2026, 9, 8) },
+    onValueChange: fn(),
+}
+```
+
+## Default render
+
+```tsx
+(args) => <DatePicker {...args}/>
+```
+
+## Examples
+
+Storybook CSF excerpts. Default args and render apply unless overridden. Local helpers, fixtures, decorators, and providers may be required; these are reference excerpts, not standalone consumer modules. Interaction tests are omitted.
+
+### Default
+
+```tsx
+{}
+```
+
+### Disabled
+
+```tsx
+{
+    args: { disabled: true }
+}
+```
+
+### Controlled
+
+```tsx
+{
+    render: () => <ControlledExample />
+}
+```
+
+### Range
+
+```tsx
+{
+    render: () => (<DateRangePicker label="Reporting period" startName="start" endName="end" calendarProps={{ defaultMonth: new Date(2026, 9), today: new Date(2026, 9, 8) }}/>)
+}
+```
+
+### FormValues
+
+```tsx
+{
+    render: () => (<form aria-label="Dates">
+      <DatePicker label="Appointment" name="appointment" defaultValue={new Date(2026, 9, 9)}/>
+      <DateRangePicker label="Period" startName="start" endName="end" defaultValue={{ from: new Date(2026, 9, 9), to: new Date(2026, 9, 12) }}/>
+      <DatePicker label="Unavailable date" name="disabled-date" defaultValue={new Date(2026, 9, 9)} disabled/>
+      <DateRangePicker label="Unavailable period" startName="disabled-start" endName="disabled-end" defaultValue={{ from: new Date(2026, 9, 9) }} disabled/>
+    </form>)
+}
+```
+
+### Localized
+
+```tsx
+{
+    render: () => <DatePicker label="Date française" locale={fr} defaultValue={new Date(2026, 9, 9)}/>
+}
+```