@misoto22/folio 0.0.0 → 0.16.0

package/dist/components/DatePicker/DatePicker.d.ts

@@ -0,0 +1,130 @@
+import * as react from 'react';
+import { ComponentProps } from 'react';
+import { DateRange } from 'react-day-picker';
+export { DateRange } from 'react-day-picker';
+import { Calendar } from '../Calendar/Calendar.js';
+
+/** A named shortcut in the rail beside the calendar. */
+interface DatePreset<T> {
+    label: string;
+    /** Computed when clicked, not when rendered — "today" must mean today. */
+    value: () => T;
+}
+/**
+ * The shortcuts a range picker is asked for on nearly every screen it appears
+ * on, so they ship rather than being rebuilt per dashboard.
+ *
+ * Computed on click: a preset list built at render time freezes "today" at
+ * whenever the page loaded, which is wrong for anything left open overnight.
+ */
+declare const RANGE_PRESETS: DatePreset<DateRange>[];
+/** The single-date equivalent. */
+declare const DATE_PRESETS: DatePreset<Date>[];
+interface DatePickerProps {
+    value?: Date;
+    defaultValue?: Date;
+    onValueChange?: (value: Date | undefined) => void;
+    /**
+     * Names the control. Required — the trigger's text is a value, not a label.
+     *
+     * Announced together with the printed date rather than instead of it, so
+     * `format` reaches a screen reader as well as the screen. Inside a `Field`
+     * with a label, that label names the trigger and this one is not repeated.
+     */
+    label: string;
+    placeholder?: string;
+    disabled?: boolean;
+    /**
+     * Days the reader may not choose.
+     *
+     * Reaches the calendar AND the shortcut rail: a preset landing on a blocked
+     * day is drawn unavailable and refuses the click, rather than committing a
+     * value the grid beside it would not accept.
+     */
+    disabledDates?: ComponentProps<typeof Calendar>['disabled'];
+    /** How the chosen date is printed on the trigger. */
+    format?: (date: Date) => string;
+    /**
+     * Shortcuts shown beside the grid. Pass `true` for the built-in set, an array
+     * for your own, or leave it off for none.
+     */
+    presets?: boolean | DatePreset<Date>[];
+    className?: string;
+    /** The TRIGGER's id — the element a label points at. A `Field` sets it. */
+    id?: string;
+    /** Ids of the copy describing the control. A `Field` sets it from hint, error and description. */
+    'aria-describedby'?: string;
+    /** Announced on the trigger. A `Field` sets it from `error`. */
+    'aria-invalid'?: boolean | 'true' | 'false';
+}
+/**
+ * A date, chosen from a calendar.
+ *
+ * A trigger and a `Calendar` in a `Popover` — not a new component so much as
+ * the composition people otherwise assemble slightly differently on every
+ * screen.
+ *
+ * It is deliberately NOT a text input with a calendar attached. A typed date
+ * needs parsing, and parsing needs a format, and a format is a locale argument
+ * nobody wins. When typing genuinely matters — a birth date, a long way back —
+ * the calendar's month and year are dropdowns, which is the same journey
+ * without the ambiguity.
+ *
+ * @example
+ * <Field label="Publish on"><DatePicker label="Publish on" /></Field>
+ */
+declare function DatePicker({ value, defaultValue, onValueChange, label, placeholder, disabled, disabledDates, format, presets, className, id, 'aria-describedby': describedBy, 'aria-invalid': ariaInvalid, }: DatePickerProps): react.JSX.Element;
+interface DateRangePickerProps {
+    value?: DateRange;
+    defaultValue?: DateRange;
+    onValueChange?: (value: DateRange | undefined) => void;
+    /** Names the control. Announced together with the printed range, not instead of it. */
+    label: string;
+    placeholder?: string;
+    disabled?: boolean;
+    /**
+     * Days the reader may not choose.
+     *
+     * Reaches the shortcut rail as well as the grid, at the ENDS of each preset
+     * range — a shortcut whose interior straddles a blocked day is still offered,
+     * the way the grid still lets a reader drag a range across one.
+     */
+    disabledDates?: ComponentProps<typeof Calendar>['disabled'];
+    /** How many months are shown side by side. Falls back to one under `sm`. */
+    months?: number;
+    format?: (date: Date) => string;
+    /**
+     * Shortcuts shown beside the grid — Last 30 days and its neighbours. `true`
+     * for the built-in set, an array for your own.
+     *
+     * On by default here and off on the single picker, because "last 30 days" is
+     * most of what a range picker is ever asked for, while a single date is
+     * usually a specific one.
+     */
+    presets?: boolean | DatePreset<DateRange>[];
+    className?: string;
+    /** The TRIGGER's id — the element a label points at. A `Field` sets it. */
+    id?: string;
+    /** Ids of the copy describing the control. A `Field` sets it from hint, error and description. */
+    'aria-describedby'?: string;
+    /** Announced on the trigger. A `Field` sets it from `error`. */
+    'aria-invalid'?: boolean | 'true' | 'false';
+}
+/**
+ * A span of dates — a stay, a reporting period, a filter.
+ *
+ * Two months side by side, because a range that crosses a month boundary is the
+ * common case, and paging back and forth to see both ends is what makes a range
+ * picker tiring. They stack under `sm`, where two would not fit — the calendar's
+ * own `months` class already carries that, so there is nothing to override.
+ *
+ * The panel stays open until both ends are chosen: a range is not a value until
+ * it has a second date, and closing on the first one would mean re-opening to
+ * finish.
+ *
+ * @example
+ * <DateRangePicker label="Reporting period" />
+ */
+declare function DateRangePicker({ value, defaultValue, onValueChange, label, placeholder, disabled, disabledDates, months, format, presets, className, id, 'aria-describedby': describedBy, 'aria-invalid': ariaInvalid, }: DateRangePickerProps): react.JSX.Element;
+
+export { DATE_PRESETS, DatePicker, type DatePickerProps, type DatePreset, DateRangePicker, type DateRangePickerProps, RANGE_PRESETS, DatePicker as default };

package/dist/components/DatePicker/DatePicker.js

@@ -0,0 +1,257 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { RiCalendarLine } from "@remixicon/react";
+import { useId, useRef, useState } from "react";
+import { dateMatchModifiers } from "react-day-picker";
+import { cn } from "../../lib/cn.js";
+import { Calendar } from "../Calendar/Calendar.js";
+import { useFieldControl } from "../Field/field-control.js";
+import { Popover, PopoverContent, PopoverTrigger } from "../Popover/Popover.js";
+const daysAgo = (n) => {
+  const to = /* @__PURE__ */ new Date();
+  const from = /* @__PURE__ */ new Date();
+  from.setDate(from.getDate() - (n - 1));
+  return { from, to };
+};
+const RANGE_PRESETS = [
+  { label: "Last 7 days", value: () => daysAgo(7) },
+  { label: "Last 30 days", value: () => daysAgo(30) },
+  { label: "Last 90 days", value: () => daysAgo(90) },
+  { label: "Last 12 months", value: () => daysAgo(365) },
+  {
+    label: "Month to date",
+    value: () => {
+      const to = /* @__PURE__ */ new Date();
+      return { from: new Date(to.getFullYear(), to.getMonth(), 1), to };
+    }
+  },
+  {
+    label: "Year to date",
+    value: () => {
+      const to = /* @__PURE__ */ new Date();
+      return { from: new Date(to.getFullYear(), 0, 1), to };
+    }
+  }
+];
+const DATE_PRESETS = [
+  { label: "Today", value: () => /* @__PURE__ */ new Date() },
+  {
+    label: "Tomorrow",
+    value: () => {
+      const date = /* @__PURE__ */ new Date();
+      date.setDate(date.getDate() + 1);
+      return date;
+    }
+  },
+  {
+    label: "In a week",
+    value: () => {
+      const date = /* @__PURE__ */ new Date();
+      date.setDate(date.getDate() + 7);
+      return date;
+    }
+  },
+  {
+    label: "In a month",
+    value: () => {
+      const date = /* @__PURE__ */ new Date();
+      date.setMonth(date.getMonth() + 1);
+      return date;
+    }
+  }
+];
+function PresetRail({
+  presets,
+  onPick,
+  label,
+  blocked
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      role: "group",
+      "aria-label": label,
+      className: "flex shrink-0 flex-col gap-0.5 border-b border-(--rule) p-2 sm:border-b-0 sm:border-e max-sm:flex-row max-sm:flex-wrap",
+      children: presets.map((preset) => /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          disabled: blocked?.(preset.value()) ?? false,
+          onClick: () => {
+            const next = preset.value();
+            if (blocked?.(next)) return;
+            onPick(next);
+          },
+          className: "rounded-(--radius-sm) px-2.5 py-1.5 text-start text-[13px] text-(--ink-2) transition-colors duration-(--duration-fast) hover:bg-(--stone) hover:text-(--ink) disabled:opacity-(--disabled-opacity) disabled:pointer-events-none",
+          children: preset.label
+        },
+        preset.label
+      ))
+    }
+  );
+}
+const TRIGGER = "flex w-full items-center justify-between gap-2 rounded-(--radius) border border-(--rule-2) bg-(--paper) px-(--field-px) py-(--field-py) text-start text-sm transition-colors duration-(--duration-fast) hover:border-(--rule-hard) disabled:opacity-(--disabled-opacity) disabled:pointer-events-none";
+const formatDate = (date) => new Intl.DateTimeFormat(void 0, { dateStyle: "medium" }).format(date);
+function DatePicker({
+  value,
+  defaultValue,
+  onValueChange,
+  label,
+  placeholder = "Pick a date",
+  disabled = false,
+  disabledDates,
+  format = formatDate,
+  presets,
+  className,
+  id,
+  "aria-describedby": describedBy,
+  "aria-invalid": ariaInvalid
+}) {
+  const rail = presets === true ? DATE_PRESETS : presets || void 0;
+  const [open, setOpen] = useState(false);
+  const [uncontrolled, setUncontrolled] = useState(defaultValue);
+  const current = value ?? uncontrolled;
+  const field = useFieldControl();
+  const generated = useId();
+  const triggerId = id ?? generated;
+  const valueId = `${triggerId}-value`;
+  const nameId = field?.labelId ?? `${triggerId}-name`;
+  const choose = (next) => {
+    if (value === void 0) setUncontrolled(next);
+    onValueChange?.(next);
+    if (next) setOpen(false);
+  };
+  const refuses = (date) => disabledDates !== void 0 && dateMatchModifiers(date, disabledDates);
+  return /* @__PURE__ */ jsxs(Popover, { open, onOpenChange: setOpen, children: [
+    /* @__PURE__ */ jsxs(
+      PopoverTrigger,
+      {
+        id: triggerId,
+        "aria-labelledby": `${nameId} ${valueId}`,
+        "aria-describedby": describedBy,
+        "aria-invalid": ariaInvalid || void 0,
+        disabled,
+        className: cn(TRIGGER, current ? "text-(--ink)" : "text-(--ink-3-aa)", className),
+        children: [
+          field?.labelId == null && /* @__PURE__ */ jsx("span", { id: nameId, className: "sr-only", children: label }),
+          /* @__PURE__ */ jsx("span", { id: valueId, className: "truncate", children: current ? format(current) : placeholder }),
+          /* @__PURE__ */ jsx(RiCalendarLine, { size: 14, "aria-hidden": true, className: "shrink-0 text-(--ink-3-aa)" })
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx(PopoverContent, { label, align: "start", className: "w-auto overflow-hidden p-0", children: /* @__PURE__ */ jsxs("div", { className: "flex flex-col sm:flex-row", children: [
+      rail && /* @__PURE__ */ jsx(
+        PresetRail,
+        {
+          presets: rail,
+          onPick: choose,
+          label: `${label} shortcuts`,
+          blocked: refuses
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        Calendar,
+        {
+          mode: "single",
+          selected: current,
+          onSelect: choose,
+          disabled: disabledDates,
+          autoFocus: true
+        }
+      )
+    ] }) })
+  ] });
+}
+function DateRangePicker({
+  value,
+  defaultValue,
+  onValueChange,
+  label,
+  placeholder = "Pick a range",
+  disabled = false,
+  disabledDates,
+  months = 2,
+  format = formatDate,
+  presets = true,
+  className,
+  id,
+  "aria-describedby": describedBy,
+  "aria-invalid": ariaInvalid
+}) {
+  const rail = presets === true ? RANGE_PRESETS : presets || void 0;
+  const [open, setOpen] = useState(false);
+  const [uncontrolled, setUncontrolled] = useState(defaultValue);
+  const current = value ?? uncontrolled;
+  const field = useFieldControl();
+  const generated = useId();
+  const triggerId = id ?? generated;
+  const valueId = `${triggerId}-value`;
+  const nameId = field?.labelId ?? `${triggerId}-name`;
+  const refuses = (range) => disabledDates !== void 0 && [range.from, range.to].some((date) => date != null && dateMatchModifiers(date, disabledDates));
+  const clicks = useRef(0);
+  const choose = (next) => {
+    clicks.current += 1;
+    if (value === void 0) setUncontrolled(next);
+    onValueChange?.(next);
+    if (clicks.current >= 2 && next?.from && next.to) setOpen(false);
+  };
+  const setPanel = (next) => {
+    if (next) clicks.current = 0;
+    setOpen(next);
+  };
+  const complete = current?.from && current.to && current.from.getTime() !== current.to.getTime();
+  const printed = current?.from ? complete ? `${format(current.from)} \u2013 ${format(current.to)}` : `${format(current.from)} \u2013 \u2026` : placeholder;
+  return /* @__PURE__ */ jsxs(Popover, { open, onOpenChange: setPanel, children: [
+    /* @__PURE__ */ jsxs(
+      PopoverTrigger,
+      {
+        id: triggerId,
+        "aria-labelledby": `${nameId} ${valueId}`,
+        "aria-describedby": describedBy,
+        "aria-invalid": ariaInvalid || void 0,
+        disabled,
+        className: cn(TRIGGER, current?.from ? "text-(--ink)" : "text-(--ink-3-aa)", className),
+        children: [
+          field?.labelId == null && /* @__PURE__ */ jsx("span", { id: nameId, className: "sr-only", children: label }),
+          /* @__PURE__ */ jsx("span", { id: valueId, className: "truncate", children: printed }),
+          /* @__PURE__ */ jsx(RiCalendarLine, { size: 14, "aria-hidden": true, className: "shrink-0 text-(--ink-3-aa)" })
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx(PopoverContent, { label, align: "start", className: "w-auto overflow-hidden p-0", children: /* @__PURE__ */ jsxs("div", { className: "flex flex-col sm:flex-row", children: [
+      rail && /* @__PURE__ */ jsx(
+        PresetRail,
+        {
+          presets: rail,
+          onPick: (next) => {
+            if (value === void 0) setUncontrolled(next);
+            onValueChange?.(next);
+            setOpen(false);
+          },
+          label: `${label} shortcuts`,
+          blocked: refuses
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        Calendar,
+        {
+          mode: "range",
+          selected: current,
+          onSelect: choose,
+          disabled: disabledDates,
+          numberOfMonths: months,
+          autoFocus: true
+        }
+      )
+    ] }) })
+  ] });
+}
+var DatePicker_default = DatePicker;
+export {
+  DATE_PRESETS,
+  DatePicker,
+  DateRangePicker,
+  RANGE_PRESETS,
+  DatePicker_default as default
+};
+//# sourceMappingURL=DatePicker.js.map

package/dist/components/DatePicker/DatePicker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/DatePicker/DatePicker.tsx"],"sourcesContent":["'use client'\n\nimport { RiCalendarLine } from '@remixicon/react'\nimport { useId, useRef, useState, type ComponentProps } from 'react'\nimport { dateMatchModifiers, type DateRange } from 'react-day-picker'\nimport { cn } from '../../lib/cn'\nimport { Calendar } from '../Calendar/Calendar'\nimport { useFieldControl } from '../Field/field-control'\nimport { Popover, PopoverContent, PopoverTrigger } from '../Popover/Popover'\n\nexport type { DateRange }\n\n/** A named shortcut in the rail beside the calendar. */\nexport interface DatePreset<T> {\n  label: string\n  /** Computed when clicked, not when rendered — \"today\" must mean today. */\n  value: () => T\n}\n\n/** `n` days back from today, inclusive of today. */\nconst daysAgo = (n: number): DateRange => {\n  const to = new Date()\n  const from = new Date()\n  from.setDate(from.getDate() - (n - 1))\n  return { from, to }\n}\n\n/**\n * The shortcuts a range picker is asked for on nearly every screen it appears\n * on, so they ship rather than being rebuilt per dashboard.\n *\n * Computed on click: a preset list built at render time freezes \"today\" at\n * whenever the page loaded, which is wrong for anything left open overnight.\n */\nexport const RANGE_PRESETS: DatePreset<DateRange>[] = [\n  { label: 'Last 7 days', value: () => daysAgo(7) },\n  { label: 'Last 30 days', value: () => daysAgo(30) },\n  { label: 'Last 90 days', value: () => daysAgo(90) },\n  { label: 'Last 12 months', value: () => daysAgo(365) },\n  {\n    label: 'Month to date',\n    value: () => {\n      const to = new Date()\n      return { from: new Date(to.getFullYear(), to.getMonth(), 1), to }\n    },\n  },\n  {\n    label: 'Year to date',\n    value: () => {\n      const to = new Date()\n      return { from: new Date(to.getFullYear(), 0, 1), to }\n    },\n  },\n]\n\n/** The single-date equivalent. */\nexport const DATE_PRESETS: DatePreset<Date>[] = [\n  { label: 'Today', value: () => new Date() },\n  {\n    label: 'Tomorrow',\n    value: () => {\n      const date = new Date()\n      date.setDate(date.getDate() + 1)\n      return date\n    },\n  },\n  {\n    label: 'In a week',\n    value: () => {\n      const date = new Date()\n      date.setDate(date.getDate() + 7)\n      return date\n    },\n  },\n  {\n    label: 'In a month',\n    value: () => {\n      const date = new Date()\n      date.setMonth(date.getMonth() + 1)\n      return date\n    },\n  },\n]\n\n/**\n * The rail of shortcuts.\n *\n * A `<nav>`-less list of plain buttons rather than a menu: they set the same\n * value the grid beside them sets, so they are part of one control and should\n * Tab in the same pass rather than opening something.\n *\n * Setting the same value means being refused for the same reasons: a shortcut\n * that commits a date the grid beside it will not accept hands the caller back\n * a value the control itself calls invalid. `blocked` is asked at render, so the\n * button is visibly unavailable rather than silently inert, and again on click,\n * because the value is computed then — \"today\" has to mean today.\n */\nfunction PresetRail<T>({\n  presets,\n  onPick,\n  label,\n  blocked,\n}: {\n  presets: DatePreset<T>[]\n  onPick: (value: T) => void\n  label: string\n  blocked?: (value: T) => boolean\n}) {\n  return (\n    <div\n      role=\"group\"\n      aria-label={label}\n      className=\"flex shrink-0 flex-col gap-0.5 border-b border-(--rule) p-2 sm:border-b-0 sm:border-e max-sm:flex-row max-sm:flex-wrap\"\n    >\n      {presets.map((preset) => (\n        <button\n          key={preset.label}\n          type=\"button\"\n          disabled={blocked?.(preset.value()) ?? false}\n          onClick={() => {\n            const next = preset.value()\n            if (blocked?.(next)) return\n            onPick(next)\n          }}\n          className=\"rounded-(--radius-sm) px-2.5 py-1.5 text-start text-[13px] text-(--ink-2) transition-colors duration-(--duration-fast) hover:bg-(--stone) hover:text-(--ink) disabled:opacity-(--disabled-opacity) disabled:pointer-events-none\"\n        >\n          {preset.label}\n        </button>\n      ))}\n    </div>\n  )\n}\n\nconst TRIGGER =\n  'flex w-full items-center justify-between gap-2 rounded-(--radius) border border-(--rule-2) bg-(--paper) px-(--field-px) py-(--field-py) text-start text-sm transition-colors duration-(--duration-fast) hover:border-(--rule-hard) disabled:opacity-(--disabled-opacity) disabled:pointer-events-none'\n\n/**\n * The visitor's own locale, not a fixed `dd/mm/yyyy`.\n *\n * `03/04` is March the fourth in one country and the third of April in the\n * next, and there is no format that is unambiguous to everyone. `Intl` already\n * knows which one this reader expects.\n */\nconst formatDate = (date: Date) =>\n  new Intl.DateTimeFormat(undefined, { dateStyle: 'medium' }).format(date)\n\nexport interface DatePickerProps {\n  value?: Date\n  defaultValue?: Date\n  onValueChange?: (value: Date | undefined) => void\n  /**\n   * Names the control. Required — the trigger's text is a value, not a label.\n   *\n   * Announced together with the printed date rather than instead of it, so\n   * `format` reaches a screen reader as well as the screen. Inside a `Field`\n   * with a label, that label names the trigger and this one is not repeated.\n   */\n  label: string\n  placeholder?: string\n  disabled?: boolean\n  /**\n   * Days the reader may not choose.\n   *\n   * Reaches the calendar AND the shortcut rail: a preset landing on a blocked\n   * day is drawn unavailable and refuses the click, rather than committing a\n   * value the grid beside it would not accept.\n   */\n  disabledDates?: ComponentProps<typeof Calendar>['disabled']\n  /** How the chosen date is printed on the trigger. */\n  format?: (date: Date) => string\n  /**\n   * Shortcuts shown beside the grid. Pass `true` for the built-in set, an array\n   * for your own, or leave it off for none.\n   */\n  presets?: boolean | DatePreset<Date>[]\n  className?: string\n  /** The TRIGGER's id — the element a label points at. A `Field` sets it. */\n  id?: string\n  /** Ids of the copy describing the control. A `Field` sets it from hint, error and description. */\n  'aria-describedby'?: string\n  /** Announced on the trigger. A `Field` sets it from `error`. */\n  'aria-invalid'?: boolean | 'true' | 'false'\n}\n\n/**\n * A date, chosen from a calendar.\n *\n * A trigger and a `Calendar` in a `Popover` — not a new component so much as\n * the composition people otherwise assemble slightly differently on every\n * screen.\n *\n * It is deliberately NOT a text input with a calendar attached. A typed date\n * needs parsing, and parsing needs a format, and a format is a locale argument\n * nobody wins. When typing genuinely matters — a birth date, a long way back —\n * the calendar's month and year are dropdowns, which is the same journey\n * without the ambiguity.\n *\n * @example\n * <Field label=\"Publish on\"><DatePicker label=\"Publish on\" /></Field>\n */\nexport function DatePicker({\n  value,\n  defaultValue,\n  onValueChange,\n  label,\n  placeholder = 'Pick a date',\n  disabled = false,\n  disabledDates,\n  format = formatDate,\n  presets,\n  className,\n  id,\n  'aria-describedby': describedBy,\n  'aria-invalid': ariaInvalid,\n}: DatePickerProps) {\n  const rail = presets === true ? DATE_PRESETS : presets || undefined\n  const [open, setOpen] = useState(false)\n  const [uncontrolled, setUncontrolled] = useState<Date | undefined>(defaultValue)\n  const current = value ?? uncontrolled\n\n  const field = useFieldControl()\n  const generated = useId()\n  const triggerId = id ?? generated\n  const valueId = `${triggerId}-value`\n  const nameId = field?.labelId ?? `${triggerId}-name`\n\n  const choose = (next: Date | undefined) => {\n    if (value === undefined) setUncontrolled(next)\n    onValueChange?.(next)\n    if (next) setOpen(false)\n  }\n\n  const refuses = (date: Date) =>\n    disabledDates !== undefined && dateMatchModifiers(date, disabledDates)\n\n  return (\n    <Popover open={open} onOpenChange={setOpen}>\n      <PopoverTrigger\n        id={triggerId}\n        // The label and the printed date, in that order. `aria-label` outranked\n        // the trigger's own text, so `format` reached the screen and nothing\n        // else — the chosen date was invisible to a screen reader.\n        aria-labelledby={`${nameId} ${valueId}`}\n        aria-describedby={describedBy}\n        aria-invalid={ariaInvalid || undefined}\n        disabled={disabled}\n        className={cn(TRIGGER, current ? 'text-(--ink)' : 'text-(--ink-3-aa)', className)}\n      >\n        {field?.labelId == null && (\n          <span id={nameId} className=\"sr-only\">\n            {label}\n          </span>\n        )}\n        <span id={valueId} className=\"truncate\">\n          {current ? format(current) : placeholder}\n        </span>\n        <RiCalendarLine size={14} aria-hidden className=\"shrink-0 text-(--ink-3-aa)\" />\n      </PopoverTrigger>\n      <PopoverContent label={label} align=\"start\" className=\"w-auto overflow-hidden p-0\">\n        <div className=\"flex flex-col sm:flex-row\">\n          {rail && (\n            <PresetRail\n              presets={rail}\n              onPick={choose}\n              label={`${label} shortcuts`}\n              blocked={refuses}\n            />\n          )}\n          <Calendar\n            mode=\"single\"\n            selected={current}\n            onSelect={choose}\n            disabled={disabledDates}\n            autoFocus\n          />\n        </div>\n      </PopoverContent>\n    </Popover>\n  )\n}\n\nexport interface DateRangePickerProps {\n  value?: DateRange\n  defaultValue?: DateRange\n  onValueChange?: (value: DateRange | undefined) => void\n  /** Names the control. Announced together with the printed range, not instead of it. */\n  label: string\n  placeholder?: string\n  disabled?: boolean\n  /**\n   * Days the reader may not choose.\n   *\n   * Reaches the shortcut rail as well as the grid, at the ENDS of each preset\n   * range — a shortcut whose interior straddles a blocked day is still offered,\n   * the way the grid still lets a reader drag a range across one.\n   */\n  disabledDates?: ComponentProps<typeof Calendar>['disabled']\n  /** How many months are shown side by side. Falls back to one under `sm`. */\n  months?: number\n  format?: (date: Date) => string\n  /**\n   * Shortcuts shown beside the grid — Last 30 days and its neighbours. `true`\n   * for the built-in set, an array for your own.\n   *\n   * On by default here and off on the single picker, because \"last 30 days\" is\n   * most of what a range picker is ever asked for, while a single date is\n   * usually a specific one.\n   */\n  presets?: boolean | DatePreset<DateRange>[]\n  className?: string\n  /** The TRIGGER's id — the element a label points at. A `Field` sets it. */\n  id?: string\n  /** Ids of the copy describing the control. A `Field` sets it from hint, error and description. */\n  'aria-describedby'?: string\n  /** Announced on the trigger. A `Field` sets it from `error`. */\n  'aria-invalid'?: boolean | 'true' | 'false'\n}\n\n/**\n * A span of dates — a stay, a reporting period, a filter.\n *\n * Two months side by side, because a range that crosses a month boundary is the\n * common case, and paging back and forth to see both ends is what makes a range\n * picker tiring. They stack under `sm`, where two would not fit — the calendar's\n * own `months` class already carries that, so there is nothing to override.\n *\n * The panel stays open until both ends are chosen: a range is not a value until\n * it has a second date, and closing on the first one would mean re-opening to\n * finish.\n *\n * @example\n * <DateRangePicker label=\"Reporting period\" />\n */\nexport function DateRangePicker({\n  value,\n  defaultValue,\n  onValueChange,\n  label,\n  placeholder = 'Pick a range',\n  disabled = false,\n  disabledDates,\n  months = 2,\n  format = formatDate,\n  presets = true,\n  className,\n  id,\n  'aria-describedby': describedBy,\n  'aria-invalid': ariaInvalid,\n}: DateRangePickerProps) {\n  const rail = presets === true ? RANGE_PRESETS : presets || undefined\n  const [open, setOpen] = useState(false)\n  const [uncontrolled, setUncontrolled] = useState<DateRange | undefined>(defaultValue)\n  const current = value ?? uncontrolled\n\n  const field = useFieldControl()\n  const generated = useId()\n  const triggerId = id ?? generated\n  const valueId = `${triggerId}-value`\n  const nameId = field?.labelId ?? `${triggerId}-name`\n\n  const refuses = (range: DateRange) =>\n    disabledDates !== undefined &&\n    [range.from, range.to].some((date) => date != null && dateMatchModifiers(date, disabledDates))\n\n  /**\n   * How many days have been clicked since the panel opened.\n   *\n   * Counted, rather than inferred from the range being \"complete\", because the\n   * first click returns `{ from: day, to: day }` — a complete range by any\n   * reading of the value. Closing on that meant every attempt at a range\n   * produced a one-day one and shut the panel, which is the opposite of what a\n   * range picker is for.\n   */\n  const clicks = useRef(0)\n\n  const choose = (next: DateRange | undefined) => {\n    clicks.current += 1\n    if (value === undefined) setUncontrolled(next)\n    onValueChange?.(next)\n    if (clicks.current >= 2 && next?.from && next.to) setOpen(false)\n  }\n\n  const setPanel = (next: boolean) => {\n    if (next) clicks.current = 0\n    setOpen(next)\n  }\n\n  const complete = current?.from && current.to && current.from.getTime() !== current.to.getTime()\n  const printed = current?.from\n    ? complete\n      ? `${format(current.from)} – ${format(current.to!)}`\n      : `${format(current.from)} – …`\n    : placeholder\n\n  return (\n    <Popover open={open} onOpenChange={setPanel}>\n      <PopoverTrigger\n        id={triggerId}\n        // The label and the printed range together — see DatePicker above.\n        aria-labelledby={`${nameId} ${valueId}`}\n        aria-describedby={describedBy}\n        aria-invalid={ariaInvalid || undefined}\n        disabled={disabled}\n        className={cn(TRIGGER, current?.from ? 'text-(--ink)' : 'text-(--ink-3-aa)', className)}\n      >\n        {field?.labelId == null && (\n          <span id={nameId} className=\"sr-only\">\n            {label}\n          </span>\n        )}\n        <span id={valueId} className=\"truncate\">\n          {printed}\n        </span>\n        <RiCalendarLine size={14} aria-hidden className=\"shrink-0 text-(--ink-3-aa)\" />\n      </PopoverTrigger>\n      <PopoverContent label={label} align=\"start\" className=\"w-auto overflow-hidden p-0\">\n        <div className=\"flex flex-col sm:flex-row\">\n          {rail && (\n            <PresetRail\n              presets={rail}\n              onPick={(next) => {\n                // A preset is a complete range in one gesture, so the panel\n                // closes — unlike a first click on the grid, which is half an\n                // answer.\n                if (value === undefined) setUncontrolled(next)\n                onValueChange?.(next)\n                setOpen(false)\n              }}\n              label={`${label} shortcuts`}\n              blocked={refuses}\n            />\n          )}\n          <Calendar\n            mode=\"range\"\n            selected={current}\n            onSelect={choose}\n            disabled={disabledDates}\n            numberOfMonths={months}\n            autoFocus\n          />\n        </div>\n      </PopoverContent>\n    </Popover>\n  )\n}\n\nexport default DatePicker\n"],"mappings":"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","names":[]}

package/dist/components/DescriptionList/DescriptionList.d.ts

@@ -0,0 +1,73 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+
+interface DescriptionListItem {
+    /**
+     * A stable key. Optional: the index is used when it is absent, which is
+     * correct for the fixed field list a record page renders and wrong for a list
+     * whose rows are added, removed or reordered — pass it there.
+     */
+    id?: string;
+    /** The label. Rendered as a `<dt>`. */
+    term: ReactNode;
+    /** The value. Rendered as a `<dd>`, so it can be a `Badge` or a link. */
+    description: ReactNode;
+}
+/**
+ * Where the value sits relative to its label.
+ *
+ * `row` is the record-page shape: label in a fixed column at the inline start,
+ * value beside it, so a reader scans the labels down one edge. It collapses to
+ * one column under the `sm` breakpoint, because a 12rem label column on a phone
+ * leaves the value about eight characters wide.
+ *
+ * `stacked` puts the value under its label at every width — the right answer
+ * inside a card or a sidebar that is narrow by design rather than by viewport.
+ */
+type DescriptionListLayout = 'row' | 'stacked';
+interface DescriptionListProps extends HTMLAttributes<HTMLDListElement> {
+    /** The pairs, in the order they should read. An empty array renders nothing. */
+    items: DescriptionListItem[];
+    /** How the value sits relative to its label. See {@link DescriptionListLayout}. */
+    layout?: DescriptionListLayout;
+    /**
+     * Draws a hairline under every pair but the last. Off for a list inside a
+     * card that already has an edge, on for a list that is the page's structure.
+     */
+    divided?: boolean;
+}
+/**
+ * A record's fields: label, value, label, value.
+ *
+ * The single most repeated shape in any detail page, and the one most often
+ * hand-built out of a `<div>` grid — which loses the only thing the markup was
+ * carrying. A `<dl>` tells a screen reader that "Owner" names the thing beside
+ * it; a grid of divs tells it there are two columns of unrelated text, and the
+ * reader has to infer the pairing from reading order alone.
+ *
+ * Reach for `Table` instead when there are several records. This is one record
+ * seen from the front; a table is many records seen from above.
+ *
+ * Each pair is wrapped in a `<div>` — which the HTML specification allows
+ * inside a `<dl>` precisely so a pair can be laid out as a unit — so the
+ * hairline runs the full width of the row rather than stopping in the column
+ * gap.
+ *
+ * An empty `items` renders `null` rather than an empty bordered box. A record
+ * with no fields is a state the page above should be handling with an
+ * `EmptyState`, and a hairline around nothing looks like a component that
+ * failed to load.
+ *
+ * @example
+ * <DescriptionList
+ *   items={[
+ *     { term: 'Owner', description: 'Henry Chen' },
+ *     { term: 'Status', description: <Badge tone="success">Deployed</Badge> },
+ *   ]}
+ * />
+ * @example
+ * <DescriptionList layout="stacked" divided={false} items={fields} />
+ */
+declare function DescriptionList({ items, layout, divided, className, ...rest }: DescriptionListProps): react.JSX.Element | null;
+
+export { DescriptionList, type DescriptionListItem, type DescriptionListLayout, type DescriptionListProps, DescriptionList as default };

package/dist/components/DescriptionList/DescriptionList.js

@@ -0,0 +1,35 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "../../lib/cn.js";
+const LAYOUT = {
+  row: "grid gap-x-6 gap-y-1 sm:grid-cols-[minmax(0,12rem)_minmax(0,1fr)]",
+  stacked: "grid gap-y-1"
+};
+function DescriptionList({
+  items,
+  layout = "row",
+  divided = true,
+  className,
+  ...rest
+}) {
+  if (items.length === 0) return null;
+  return /* @__PURE__ */ jsx("dl", { className: cn("m-0", !divided && "flex flex-col gap-3", className), ...rest, children: items.map((item, index) => /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cn(
+        LAYOUT[layout],
+        divided && "border-b border-(--rule) py-3 first:pt-0 last:border-b-0 last:pb-0"
+      ),
+      children: [
+        /* @__PURE__ */ jsx("dt", { className: "text-sm text-(--ink-3-aa)", children: item.term }),
+        /* @__PURE__ */ jsx("dd", { className: "m-0 text-sm text-(--ink-2)", children: item.description })
+      ]
+    },
+    item.id ?? index
+  )) });
+}
+var DescriptionList_default = DescriptionList;
+export {
+  DescriptionList,
+  DescriptionList_default as default
+};
+//# sourceMappingURL=DescriptionList.js.map

package/dist/components/DescriptionList/DescriptionList.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/components/DescriptionList/DescriptionList.tsx"],"sourcesContent":["import type { HTMLAttributes, ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\n\nexport interface DescriptionListItem {\n  /**\n   * A stable key. Optional: the index is used when it is absent, which is\n   * correct for the fixed field list a record page renders and wrong for a list\n   * whose rows are added, removed or reordered — pass it there.\n   */\n  id?: string\n  /** The label. Rendered as a `<dt>`. */\n  term: ReactNode\n  /** The value. Rendered as a `<dd>`, so it can be a `Badge` or a link. */\n  description: ReactNode\n}\n\n/**\n * Where the value sits relative to its label.\n *\n * `row` is the record-page shape: label in a fixed column at the inline start,\n * value beside it, so a reader scans the labels down one edge. It collapses to\n * one column under the `sm` breakpoint, because a 12rem label column on a phone\n * leaves the value about eight characters wide.\n *\n * `stacked` puts the value under its label at every width — the right answer\n * inside a card or a sidebar that is narrow by design rather than by viewport.\n */\nexport type DescriptionListLayout = 'row' | 'stacked'\n\nexport interface DescriptionListProps extends HTMLAttributes<HTMLDListElement> {\n  /** The pairs, in the order they should read. An empty array renders nothing. */\n  items: DescriptionListItem[]\n  /** How the value sits relative to its label. See {@link DescriptionListLayout}. */\n  layout?: DescriptionListLayout\n  /**\n   * Draws a hairline under every pair but the last. Off for a list inside a\n   * card that already has an edge, on for a list that is the page's structure.\n   */\n  divided?: boolean\n}\n\nconst LAYOUT: Record<DescriptionListLayout, string> = {\n  row: 'grid gap-x-6 gap-y-1 sm:grid-cols-[minmax(0,12rem)_minmax(0,1fr)]',\n  stacked: 'grid gap-y-1',\n}\n\n/**\n * A record's fields: label, value, label, value.\n *\n * The single most repeated shape in any detail page, and the one most often\n * hand-built out of a `<div>` grid — which loses the only thing the markup was\n * carrying. A `<dl>` tells a screen reader that \"Owner\" names the thing beside\n * it; a grid of divs tells it there are two columns of unrelated text, and the\n * reader has to infer the pairing from reading order alone.\n *\n * Reach for `Table` instead when there are several records. This is one record\n * seen from the front; a table is many records seen from above.\n *\n * Each pair is wrapped in a `<div>` — which the HTML specification allows\n * inside a `<dl>` precisely so a pair can be laid out as a unit — so the\n * hairline runs the full width of the row rather than stopping in the column\n * gap.\n *\n * An empty `items` renders `null` rather than an empty bordered box. A record\n * with no fields is a state the page above should be handling with an\n * `EmptyState`, and a hairline around nothing looks like a component that\n * failed to load.\n *\n * @example\n * <DescriptionList\n *   items={[\n *     { term: 'Owner', description: 'Henry Chen' },\n *     { term: 'Status', description: <Badge tone=\"success\">Deployed</Badge> },\n *   ]}\n * />\n * @example\n * <DescriptionList layout=\"stacked\" divided={false} items={fields} />\n */\nexport function DescriptionList({\n  items,\n  layout = 'row',\n  divided = true,\n  className,\n  ...rest\n}: DescriptionListProps) {\n  if (items.length === 0) return null\n\n  return (\n    <dl className={cn('m-0', !divided && 'flex flex-col gap-3', className)} {...rest}>\n      {items.map((item, index) => (\n        <div\n          key={item.id ?? index}\n          className={cn(\n            LAYOUT[layout],\n            divided && 'border-b border-(--rule) py-3 first:pt-0 last:border-b-0 last:pb-0',\n          )}\n        >\n          <dt className=\"text-sm text-(--ink-3-aa)\">{item.term}</dt>\n          <dd className=\"m-0 text-sm text-(--ink-2)\">{item.description}</dd>\n        </div>\n      ))}\n    </dl>\n  )\n}\n\nexport default DescriptionList\n"],"mappings":"AA0FQ,SAOE,KAPF;AAzFR,SAAS,UAAU;AAwCnB,MAAM,SAAgD;AAAA,EACpD,KAAK;AAAA,EACL,SAAS;AACX;AAkCO,SAAS,gBAAgB;AAAA,EAC9B;AAAA,EACA,SAAS;AAAA,EACT,UAAU;AAAA,EACV;AAAA,EACA,GAAG;AACL,GAAyB;AACvB,MAAI,MAAM,WAAW,EAAG,QAAO;AAE/B,SACE,oBAAC,QAAG,WAAW,GAAG,OAAO,CAAC,WAAW,uBAAuB,SAAS,GAAI,GAAG,MACzE,gBAAM,IAAI,CAAC,MAAM,UAChB;AAAA,IAAC;AAAA;AAAA,MAEC,WAAW;AAAA,QACT,OAAO,MAAM;AAAA,QACb,WAAW;AAAA,MACb;AAAA,MAEA;AAAA,4BAAC,QAAG,WAAU,6BAA6B,eAAK,MAAK;AAAA,QACrD,oBAAC,QAAG,WAAU,8BAA8B,eAAK,aAAY;AAAA;AAAA;AAAA,IAPxD,KAAK,MAAM;AAAA,EAQlB,CACD,GACH;AAEJ;AAEA,IAAO,0BAAQ;","names":[]}

package/dist/components/Diagram/Diagram.d.ts

@@ -0,0 +1,86 @@
+import * as react from 'react';
+
+interface DiagramNode {
+    /** Only needed when an edge names this node. */
+    id?: string;
+    /** The node's name, set in the interface face. */
+    label: string;
+    /** What it is — one short line, a step back. */
+    note?: string;
+    /** The one node the diagram is about. At most one or two per diagram. */
+    accent?: boolean;
+    /** How this node's children are laid out. Defaults to a row. */
+    direction?: 'row' | 'column';
+    children?: DiagramNode[];
+    /** A line printed under the frame, outside it — what the box means. */
+    footnote?: string;
+}
+interface DiagramEdge {
+    from: string;
+    to: string;
+    label?: string;
+}
+interface DiagramSpec {
+    /** How the top-level nodes are laid out. Defaults to a row. */
+    direction?: 'row' | 'column';
+    nodes: DiagramNode[];
+    /**
+     * Arrows between adjacent siblings, by id and in the order the rank runs.
+     * Each edge is spent the first time a pair matches it, at whatever depth
+     * that pair sits — and an edge that matches nothing says so in development
+     * rather than drawing nothing and reporting nothing.
+     */
+    edges?: DiagramEdge[];
+    /** The figure's caption. */
+    caption?: string;
+    /** Names the figure for assistive tech when the caption does not. */
+    label?: string;
+}
+interface DiagramProps {
+    spec: DiagramSpec;
+    className?: string;
+}
+/**
+ * A flow or architecture diagram, drawn out of the system's own parts.
+ *
+ * The alternative it replaces is a fenced block of box-drawing characters —
+ * `┌──────┬──────┐` — which is a picture rendered in a font chosen for code. It
+ * inherits the code block's frame and scrollbar, so a diagram reads as terminal
+ * output; it cannot wrap, so on a phone it either overflows or is scaled to
+ * nothing; the box edges are text, so a screen reader reads the rules out loud;
+ * and none of it responds to the theme.
+ *
+ * The other alternative is a diagramming library, which is several hundred
+ * kilobytes of layout engine, renders after hydration, and draws in its own
+ * palette. This is neither: hairline frames on the radius scale, mono labels,
+ * the muted step for anything supporting — so a diagram belongs to the page it
+ * sits on. It server-renders, because it is markup.
+ *
+ * NESTING IS CONTAINMENT, which is what most architecture diagrams actually
+ * describe: this is inside that, and these two sit beside each other. Edges are
+ * for the sequence between siblings, not for arbitrary wiring — a diagram that
+ * needs arbitrary wiring is a diagram that wants a drawing, and this will not
+ * pretend otherwise.
+ *
+ * It takes a spec rather than markup, so a fenced ```diagram block in an
+ * article and a hand-written figure on a page are one renderer and one look —
+ * and a wrong diagram is corrected by editing data.
+ *
+ * @example
+ * <Diagram
+ *   spec={{
+ *     caption: 'One request, end to end.',
+ *     edges: [{ from: 'edge', to: 'app', label: 'HTTPS' }],
+ *     nodes: [
+ *       { id: 'edge', label: 'Edge', note: 'CDN' },
+ *       { id: 'app', label: 'Application', children: [
+ *         { label: 'Router', accent: true },
+ *         { label: 'Handlers' },
+ *       ] },
+ *     ],
+ *   }}
+ * />
+ */
+declare function Diagram({ spec, className }: DiagramProps): react.JSX.Element;
+
+export { Diagram, type DiagramEdge, type DiagramNode, type DiagramProps, type DiagramSpec, Diagram as default };