@rinzai/zen 0.14.0 → 0.16.0

package/dist/docs/calendar-heatmap.md

@@ -0,0 +1,73 @@
+# Calendar Heatmap
+
+A month of days shaded by their value, like spending per day.
+
+```tsx
+import { CalendarHeatmap } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { CalendarHeatmap, type DateString, formatDate, formatMoney } from '@rinzai/zen';
+import { useState } from 'react';
+
+const SPENT: Partial<Record<DateString, number>> = {
+    '2026-09-01': 185000,
+    '2026-09-03': 3840,
+    '2026-09-05': 2500,
+    '2026-09-06': 7800,
+    '2026-09-08': 1460,
+    '2026-09-12': 16450,
+    '2026-09-13': 9150,
+    '2026-09-15': 4200,
+    '2026-09-19': 3180,
+    '2026-09-20': 41200,
+    '2026-09-22': 1199,
+    '2026-09-26': 6420,
+    '2026-09-27': 2210,
+};
+const money = (cents: number) => formatMoney(cents, 'USD', 'en-US', { showDecimals: false });
+
+/** What was spent each day of a month: pick a day to see it. */
+export default function Default() {
+    const [day, setDay] = useState<DateString | null>('2026-09-12');
+    return (
+        <div className="flex w-full max-w-xs flex-col gap-3">
+            <CalendarHeatmap
+                month="2026-09"
+                values={SPENT}
+                locale="en-US"
+                format={money}
+                onSelectedChange={setDay}
+                selected={day}
+            />
+            <p className="text-muted-foreground mt-0! text-sm">
+                {day ? `${formatDate(day, 'en-US', 'long')}: ${money(SPENT[day] ?? 0)} spent` : 'Pick a day'}
+            </p>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### CalendarHeatmap
+
+A month as a grid of days, each shaded by its value (e.g. what was spent
+that day): busy days stand out at a glance. Hover a day for its figure;
+with `onSelectedChange`, days are buttons.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `month` (required) | `string` |  |  |
+| `values` (required) | `Partial<Record<string, number>>` |  | Each day's value, by date ("2026-09-03"); days missing have none. |
+| `className` | `string` |  |  |
+| `format` | `((value: number) => string)` |  | Turns a value into text for its label, e.g. as money. |
+| `label` | `string` |  | Accessible name (default: the month, e.g. "September 2026"). |
+| `locale` | `string` |  |  |
+| `onSelectedChange` | `((day: string) => void)` |  | Makes the days buttons. |
+| `selected` | `string \| null` |  |  |
+| `weekStartsOn` | `number` |  | 0 for Sunday … 6 for Saturday (default: the locale's). |

package/dist/docs/calendar.md

@@ -0,0 +1,101 @@
+# Calendar
+
+A month grid to pick a date or a range, fully keyboard-driven, with limits, blocked days and a year view to jump far.
+
+```tsx
+import { Calendar } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Calendar, formatDate } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Click a day, or use the keyboard: arrows, Home/End, Page Up/Down (Shift for years). The title jumps to any month and year. */
+export default function Default() {
+    const [date, setDate] = useState<string | null>('2026-09-30');
+    return (
+        <div className="flex flex-col items-center gap-3">
+            <Calendar value={date} onValueChange={setDate} locale="en-US" />
+            <p className="text-muted-foreground mt-0! text-xs">
+                {date ? formatDate(date, 'en-US', 'full') : 'No date'}
+            </p>
+        </div>
+    );
+}
+```
+
+### Range
+
+```tsx
+import { Calendar, type DateRange, daysBetween, formatDateRange } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Two months side by side: pick a start, then an end. The days between are previewed as you point. */
+export default function Range() {
+    const [range, setRange] = useState<DateRange | null>({ start: '2026-10-05', end: '2026-10-12' });
+    return (
+        <div className="flex flex-col items-center gap-3">
+            <Calendar mode="range" months={2} value={range} onValueChange={setRange} locale="en-GB" />
+            <p className="text-muted-foreground mt-0! text-xs">
+                {range?.end
+                    ? `${formatDateRange(range.start, range.end, 'en-GB')} · ${daysBetween(range.start, range.end) + 1} days`
+                    : 'Pick the last day'}
+            </p>
+        </div>
+    );
+}
+```
+
+### Limits
+
+```tsx
+import { addDays, Calendar, dayOfWeek, today } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Only the next 60 days, and no weekends: min, max and isDisabled. Weeks start on Monday here, whatever the locale. */
+export default function Limits() {
+    const start = today();
+    const [date, setDate] = useState<string | null>(null);
+    return (
+        <Calendar
+            value={date}
+            onValueChange={setDate}
+            locale="en-US"
+            weekStartsOn={1}
+            min={start}
+            max={addDays(start, 60)}
+            isDisabled={(d) => dayOfWeek(d) === 0 || dayOfWeek(d) === 6}
+        />
+    );
+}
+```
+
+## API reference
+
+### Calendar
+
+A month grid to pick a date, or a range of dates, fully keyboard-driven:
+arrows move by day and week, Home and End to the week's ends, Page Up and
+Down by month (with Shift, by year). The title opens a year and month grid
+to jump far. Dates are "YYYY-MM-DD" strings, so they never shift a day with
+time zones. Inline on a page, or in a popup with DatePicker.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoFocus` | `boolean` |  | Focus the chosen date (or today) when shown, e.g. in a popup. |
+| `className` | `string` |  |  |
+| `defaultMonth` | `string` |  | Month shown first ("YYYY-MM"). Defaults to the chosen date's, or this month. |
+| `defaultValue` | `DateRange \| string \| null` |  | The first date, when the calendar keeps its own. The first range, when the calendar keeps its own. |
+| `isDisabled` | `((date: string) => boolean)` |  | Dates that can't be picked, e.g. weekends or booked days. |
+| `locale` | `string` |  | Decides month and weekday names, and the first day of the week, e.g. "en-IN". Defaults to the LocaleProvider's. |
+| `max` | `string` |  | Latest date that can be picked. |
+| `min` | `string` |  | Earliest date that can be picked ("YYYY-MM-DD"). |
+| `mode` | `"range" \| "single"` |  | Pick a start and then an end; the days between are highlighted, previewed while pointing. |
+| `months` | `number` |  | Months shown side by side (e.g. 2 for ranges). |
+| `onValueChange` | `((date: string) => void) \| ((range: DateRange) => void)` |  |  |
+| `value` | `DateRange \| string \| null` |  | "YYYY-MM-DD", or null for none, when you keep it. The range when you keep it; `end` is null while only the start is picked. |
+| `weekStartsOn` | `number` |  | 0 for Sunday … 6 for Saturday. Defaults to the locale's. |