@sableui/react 0.6.1 → 0.7.0

package/dist/components/date-picker/date-picker.meta.js

@@ -0,0 +1,164 @@
+// src/components/date-picker/date-picker.meta.ts
+var datePickerMeta = {
+  name: "DatePicker",
+  summary: `Date (and optionally time) picker: a field-shaped trigger (the Input / SelectTrigger shell) opens a Popover holding Sable's Calendar. With granularity="day" selecting a day fires onValueChange and closes; granularity="minute" adds an hour + minute row of Selects and keeps the time-of-day when the day changes.`,
+  status: "stable",
+  keywords: [
+    "date picker",
+    "calendar",
+    "date input",
+    "date time picker",
+    "time",
+    "schedule",
+    "form"
+  ],
+  usage: {
+    description: 'Use DatePicker when users need to choose one date \u2014 or, with granularity="minute", one date and time \u2014 from a compact control.',
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it in forms where a typed date alone would be error-prone."
+      },
+      {
+        guidance: "do",
+        description: "Show clear selected and disabled states when date rules apply."
+      },
+      {
+        guidance: "do",
+        description: 'Set granularity="minute" when a time matters, with a minuteStep that matches the real precision (15 for meetings, 5 for scheduled posts).'
+      },
+      {
+        guidance: "dont",
+        description: "Do not show a time without saying which zone it is in. A meeting time with no zone is wrong for everyone not in yours \u2014 wrap the picker in a Field whose description names the zone."
+      },
+      {
+        guidance: "dont",
+        description: "Do not leave the format ambiguous. `03/04` is two different dates depending on the reader's locale \u2014 the trigger shows a formatted date precisely so the interpretation is not guessed."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Calendar",
+      "Field"
+    ]
+  },
+  props: [
+    {
+      name: "value",
+      type: "Date",
+      description: "The selected date (controlled). When absent, the trigger shows a muted placeholder."
+    },
+    {
+      name: "defaultValue",
+      type: "Date",
+      description: "Initial value when uncontrolled (no `value` prop)."
+    },
+    {
+      name: "onValueChange",
+      type: "(date: Date | undefined) => void",
+      description: 'Fired when the day is chosen or cleared, and under granularity="minute" when the hour or minute changes. With granularity="day" it also closes the popover.'
+    },
+    {
+      name: "onChange",
+      type: "(date: Date | undefined) => void",
+      description: "Deprecated alias for onValueChange, kept for backwards compatibility. Both fire when set; prefer onValueChange.",
+      deprecated: "onValueChange"
+    },
+    {
+      name: "granularity",
+      type: '"day" | "minute"',
+      default: '"day"',
+      description: 'What the picker chooses. "minute" adds an hour + minute row and keeps the popover open so day and time can be set in any order.'
+    },
+    {
+      name: "minuteStep",
+      type: "number",
+      default: "5",
+      description: 'Minute increment for the time row (granularity="minute" only).'
+    },
+    {
+      name: "defaultTime",
+      type: "string",
+      default: '"00:00"',
+      description: 'Time-of-day shown and applied while nothing is selected yet, as 24h "HH:mm" \u2014 the first day pick lands on this time instead of midnight (granularity="minute" only).'
+    },
+    {
+      name: "placeholder",
+      type: "string",
+      default: '"Pick a date" ("Pick date & time" with granularity="minute")',
+      description: "Trigger label shown when no date is selected."
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      description: "Disable the trigger and block selection."
+    },
+    {
+      name: "minDate",
+      type: "Date",
+      description: "Earliest selectable day (inclusive). Earlier days are disabled and navigation is bounded."
+    },
+    {
+      name: "maxDate",
+      type: "Date",
+      description: "Latest selectable day (inclusive). Later days are disabled and navigation is bounded."
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Extra classes merged onto the trigger."
+    },
+    {
+      name: "id / aria-label / aria-labelledby / aria-describedby / aria-invalid / aria-required",
+      type: "button attributes",
+      description: "Forwarded to the trigger, so a wrapping Field ties its label to the picker and announces its description and error. Pass them yourself only when labelling the picker without a Field."
+    }
+  ],
+  tokensUsed: [
+    "primary",
+    "primary-foreground",
+    "accent",
+    "accent-foreground",
+    "foreground",
+    "muted-foreground",
+    "popover",
+    "popover-foreground",
+    "border",
+    "input",
+    "card",
+    "ring"
+  ],
+  a11y: [
+    "Trigger opens on click/Enter/Space; the popover traps focus and restores it to the trigger on close (Base UI Popover).",
+    "The calendar grid (react-day-picker) provides a roving tabindex, arrow-key day navigation, and aria-selected on the chosen day.",
+    "Navigation chevrons render through the Icon adapter and inherit the calendar's button labels.",
+    "Esc and outside press dismiss the popover.",
+    'With granularity="minute" the hour and minute Selects are full Base UI listboxes (typeahead, ARIA) labelled "Hour" and "Minute"; selecting a day keeps the chosen time-of-day, so day and time can be set in any order.'
+  ],
+  examples: [
+    {
+      label: "Controlled",
+      code: "const [date, setDate] = useState<Date>()\n<DatePicker value={date} onValueChange={setDate} />"
+    },
+    {
+      label: "Custom placeholder",
+      code: '<DatePicker placeholder="Schedule for\u2026" value={date} onValueChange={setDate} />'
+    },
+    {
+      label: "Date and time",
+      code: 'const [start, setStart] = useState<Date>()\n<DatePicker granularity="minute" value={start} onValueChange={setStart} minDate={new Date()} defaultTime="09:00" minuteStep={15} />'
+    },
+    {
+      label: "Disabled",
+      code: "<DatePicker disabled />"
+    },
+    {
+      label: "Bounded (no past dates)",
+      code: "<DatePicker value={date} onValueChange={setDate} minDate={new Date()} />"
+    }
+  ]
+};
+export {
+  datePickerMeta
+};

package/dist/components/date-picker/index.js

@@ -0,0 +1,7 @@
+// src/components/date-picker/index.ts
+import { DatePicker } from "./date-picker.js";
+import { datePickerMeta } from "./date-picker.meta.js";
+export {
+  DatePicker,
+  datePickerMeta
+};

package/dist/components/date-tile/date-tile.js

@@ -0,0 +1,29 @@
+// src/components/date-tile/date-tile.tsx
+import { cn } from "../../lib/cn.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function isoDay(date) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+function DateTile({ date, locale, className, ...props }) {
+  const month = new Intl.DateTimeFormat(locale, { month: "short" }).format(date);
+  return /* @__PURE__ */ jsxs(
+    "time",
+    {
+      dateTime: isoDay(date),
+      className: cn(
+        "grid h-fit w-14 shrink-0 overflow-hidden rounded-[min(var(--radius-md),--spacing(3))] bg-muted text-center text-foreground",
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx("span", { className: "bg-primary py-0.5 text-label-sm text-primary-foreground", children: month }),
+        /* @__PURE__ */ jsx("span", { className: "flex h-9 items-center justify-center text-heading-3 leading-none tabular-nums lining-nums", children: date.getDate() })
+      ]
+    }
+  );
+}
+DateTile.displayName = "DateTile";
+export {
+  DateTile
+};

package/dist/components/date-tile/date-tile.meta.js

@@ -0,0 +1,72 @@
+// src/components/date-tile/date-tile.meta.ts
+var dateTileMeta = {
+  name: "DateTile",
+  summary: "A calendar-page date: the short month on a primary band over the day number, in a <time> element. The leading visual of an event, booking or deadline row.",
+  keywords: ["date", "calendar", "event", "day", "month", "schedule", "booking", "tile"],
+  usage: {
+    description: "Use DateTile as the leading visual when the date is what a reader scans a list or card by \u2014 events, bookings, deadlines, releases. It sits beside a title and a time line, usually in an Entity's `leading` slot or a flex row in a CardContent. For a date inside a sentence or a row's metadata, use text or RelativeTime instead.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Pair the tile with a title and the full time or range in text beside it; the tile only names the day."
+      },
+      {
+        guidance: "do",
+        description: "Keep every row of a list on DateTile so the dates line up as one column."
+      },
+      {
+        guidance: "dont",
+        description: 'Use it for timestamps ("2 hours ago", "Oct 14, 10:02") \u2014 that is RelativeTime or plain metadata text.'
+      },
+      {
+        guidance: "dont",
+        description: "Stretch it to its neighbour's height or restyle the band per row; the tile is a fixed shape so a column of them reads as one calendar."
+      }
+    ],
+    anatomy: [
+      { name: "Band", required: true, description: "The short month name on the primary colour." },
+      { name: "Day", required: true, description: "The day of the month, on the muted surface." }
+    ]
+  },
+  related: {
+    components: ["Entity", "Card", "RelativeTime", "Calendar"]
+  },
+  status: "stable",
+  props: [
+    {
+      name: "date",
+      type: "Date",
+      description: 'The day to show, read in local time. Rendered as `<time dateTime="YYYY-MM-DD">`.'
+    },
+    {
+      name: "locale",
+      type: "string",
+      default: "runtime locale",
+      description: "BCP 47 locale for the month name."
+    }
+  ],
+  tokensUsed: ["muted", "primary", "primary-foreground", "foreground"],
+  motion: [
+    { slot: "arrival", part: "Tile", recipe: "none", why: "A static label; it appears with whatever row or card holds it." },
+    { slot: "response", part: "Tile", recipe: "none", why: "Not interactive." },
+    { slot: "transition", part: "Tile", recipe: "none", why: "It has no states to move between." },
+    { slot: "activity", part: "Tile", recipe: "none", why: "Nothing runs in the background." }
+  ],
+  a11y: [
+    'Renders a <time> with a machine-readable `dateTime`, so the day is announced as text ("Oct 14") and parsable as a date.',
+    "The tile names only the day \u2014 state the weekday, time or range in the text beside it, where it is read in order."
+  ],
+  examples: [
+    {
+      label: "Event row",
+      code: '<Row gap={4} align="start">\n	<DateTile date={new Date(2026, 9, 14)} />\n	<Stack gap={1}>\n		<span className="text-title-lg">Design review</span>\n		<span className="text-body-sm text-muted-foreground">Tuesday, 2:00 \u2013 2:45 PM</span>\n	</Stack>\n</Row>'
+    },
+    {
+      label: "In an Entity list",
+      code: '<CardList>\n	<Entity leading={<DateTile date={new Date(2026, 9, 14)} />} title="Design review" subtitle="Tuesday, 2:00 PM" />\n	<Entity leading={<DateTile date={new Date(2026, 9, 21)} />} title="Launch" subtitle="Tuesday, all day" />\n</CardList>'
+    }
+  ]
+};
+export {
+  dateTileMeta
+};

package/dist/components/date-tile/index.js

@@ -0,0 +1,7 @@
+// src/components/date-tile/index.ts
+import { DateTile } from "./date-tile.js";
+import { dateTileMeta } from "./date-tile.meta.js";
+export {
+  DateTile,
+  dateTileMeta
+};

package/dist/components/destructive-action-modal/destructive-action-modal.js

@@ -0,0 +1,130 @@
+"use client";
+
+// src/components/destructive-action-modal/destructive-action-modal.tsx
+import { useEffect, useRef, useState } from "react";
+import { Button } from "../button/index.js";
+import {
+  AlertDialog,
+  AlertDialogClose,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle
+} from "../dialog/index.js";
+import { Code } from "../code/index.js";
+import { Field } from "../form/index.js";
+import { Input } from "../input/index.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+function DestructiveActionModal({
+  open,
+  onOpenChange,
+  title,
+  description,
+  confirmLabel = "Delete",
+  cancelLabel = "Cancel",
+  onConfirm,
+  pending,
+  confirmingLabel,
+  children,
+  confirmText
+}) {
+  const [typed, setTyped] = useState("");
+  const [internalBusy, setInternalBusy] = useState(false);
+  const inFlight = useRef(false);
+  const cancelRef = useRef(null);
+  const controlledPending = pending !== void 0;
+  const busy = pending ?? internalBusy;
+  useEffect(() => {
+    if (!open) {
+      setTyped("");
+    }
+  }, [open]);
+  const requiresMatch = typeof confirmText === "string" && confirmText.length > 0;
+  const matched = !requiresMatch || typed === confirmText;
+  async function handleConfirm() {
+    if (!matched || busy || inFlight.current) {
+      return;
+    }
+    inFlight.current = true;
+    try {
+      const result = onConfirm();
+      if (controlledPending) {
+        return;
+      }
+      if (result instanceof Promise) {
+        setInternalBusy(true);
+        try {
+          await result;
+          setInternalBusy(false);
+          onOpenChange(false);
+        } catch {
+          setInternalBusy(false);
+        }
+      } else {
+        onOpenChange(false);
+      }
+    } finally {
+      inFlight.current = false;
+    }
+  }
+  function handleOpenChange(next) {
+    if (busy && !next) {
+      return;
+    }
+    onOpenChange(next);
+  }
+  return /* @__PURE__ */ jsx(AlertDialog, { open, onOpenChange: handleOpenChange, children: /* @__PURE__ */ jsxs(AlertDialogContent, { initialFocus: cancelRef, children: [
+    /* @__PURE__ */ jsxs(AlertDialogHeader, { children: [
+      /* @__PURE__ */ jsx(AlertDialogTitle, { children: title }),
+      description ? /* @__PURE__ */ jsx(AlertDialogDescription, { children: description }) : null
+    ] }),
+    children != null || requiresMatch ? /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-4", children: [
+      children,
+      requiresMatch ? /* @__PURE__ */ jsx(
+        Field,
+        {
+          label: /* @__PURE__ */ jsxs(Fragment, { children: [
+            "Type ",
+            /* @__PURE__ */ jsx(Code, { children: confirmText }),
+            " to confirm"
+          ] }),
+          children: /* @__PURE__ */ jsx(
+            Input,
+            {
+              value: typed,
+              onChange: (event) => setTyped(event.target.value),
+              placeholder: confirmText,
+              autoComplete: "off",
+              autoCapitalize: "off",
+              spellCheck: false
+            }
+          )
+        }
+      ) : null
+    ] }) : null,
+    /* @__PURE__ */ jsxs(AlertDialogFooter, { children: [
+      /* @__PURE__ */ jsx(
+        AlertDialogClose,
+        {
+          render: /* @__PURE__ */ jsx(Button, { ref: cancelRef, variant: "secondary", disabled: busy, children: cancelLabel })
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        Button,
+        {
+          variant: "destructive",
+          loading: busy,
+          loadingLabel: confirmingLabel ?? confirmLabel,
+          disabled: !matched,
+          onClick: handleConfirm,
+          children: confirmLabel
+        }
+      )
+    ] })
+  ] }) });
+}
+DestructiveActionModal.displayName = "DestructiveActionModal";
+export {
+  DestructiveActionModal
+};

package/dist/components/destructive-action-modal/destructive-action-modal.meta.js

@@ -0,0 +1,136 @@
+// src/components/destructive-action-modal/destructive-action-modal.meta.ts
+var destructiveActionModalMeta = {
+  name: "DestructiveActionModal",
+  summary: "Confirmation modal for irreversible actions, built on AlertDialog (role=alertdialog; a backdrop click does not dismiss). Pairs a secondary Cancel with a destructive confirm; awaits an async onConfirm (spinner + stays open on failure) or takes an external pending flag; optional body slot and type-to-confirm guard for high-stakes deletions.",
+  status: "stable",
+  keywords: [
+    "destructive",
+    "modal",
+    "confirmation",
+    "danger"
+  ],
+  usage: {
+    description: "Use DestructiveActionModal to confirm irreversible or high-risk actions before they run.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Name the affected object and the consequence of the action in plain language."
+      },
+      {
+        guidance: "do",
+        description: "Make the destructive action visually distinct from the cancel path."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it for routine low-risk actions where undo or inline confirmation would be faster."
+      },
+      {
+        guidance: "dont",
+        description: "Do not put the destructive action where Cancel usually sits, or make it the default focus. A confirmation dialog exists to add friction; autofocusing Delete removes the friction it was added for."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Dialog",
+      "Button",
+      "Banner"
+    ]
+  },
+  props: [
+    {
+      name: "open",
+      type: "boolean",
+      description: "Controlled open state."
+    },
+    {
+      name: "onOpenChange",
+      type: "(open: boolean) => void",
+      description: "Called when the open state should change (Esc, Cancel, or confirm). A backdrop click does not dismiss."
+    },
+    {
+      name: "title",
+      type: "ReactNode",
+      description: "Modal heading \u2014 names the irreversible action."
+    },
+    {
+      name: "description",
+      type: "ReactNode",
+      description: "Optional supporting copy explaining the consequence."
+    },
+    {
+      name: "confirmLabel",
+      type: "string",
+      default: '"Delete"',
+      description: "Label for the destructive confirm button."
+    },
+    {
+      name: "cancelLabel",
+      type: "string",
+      default: '"Cancel"',
+      description: "Label for the dismissing secondary button."
+    },
+    {
+      name: "onConfirm",
+      type: "() => void | Promise<void>",
+      description: "Called when the user confirms. If it returns a Promise the modal shows an in-flight spinner, closes on resolve, and stays open on reject; if void it closes immediately (unless pending is controlled)."
+    },
+    {
+      name: "pending",
+      type: "boolean",
+      description: "Externally-driven in-flight state. Overrides the internal await tracking; the parent owns closing (the modal stays open on a synchronous confirm)."
+    },
+    {
+      name: "confirmingLabel",
+      type: "string",
+      default: "confirmLabel",
+      description: "Confirm-button label shown while the action is in flight."
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "Body content rendered between the description and the type-to-confirm Input / footer \u2014 e.g. a warning <Note>."
+    },
+    {
+      name: "confirmText",
+      type: "string",
+      description: "When set, renders an Input the user must type matching to enable the destructive confirm button."
+    }
+  ],
+  tokensUsed: [
+    "card",
+    "card-foreground",
+    "border",
+    "muted-foreground",
+    "foreground",
+    "input",
+    "destructive",
+    "destructive-foreground",
+    "secondary",
+    "secondary-foreground"
+  ],
+  a11y: [
+    `Built on AlertDialog (Base UI): role="alertdialog", focus trapping, scroll lock, and aria-modal. Esc dismisses; a click on the backdrop does not, so a stray click can't throw away the decision.`,
+    "Focus opens on Cancel \u2014 the safe action \u2014 even when a type-to-confirm Input comes first, so a reflexive Enter never fires the destructive action.",
+    "The title labels the modal; the description describes it.",
+    "The type-to-confirm Input is wired to its label via htmlFor; the destructive Button is disabled (not just hidden) until the text matches.",
+    "While a confirm is in flight (awaited onConfirm or pending), both buttons disable, the confirm Button sets aria-busy, and Esc dismissal is blocked so the action can't be interrupted or double-fired."
+  ],
+  examples: [
+    {
+      label: "Basic",
+      code: "<DestructiveActionModal open={open} onOpenChange={setOpen} title='Delete post?' description='This permanently removes the post. This cannot be undone.' onConfirm={handleDelete} />"
+    },
+    {
+      label: "Async confirm (awaited spinner)",
+      code: "<DestructiveActionModal open={open} onOpenChange={setOpen} title='Block user?' description='They can no longer interact with you.' confirmLabel='Block' confirmingLabel='Blocking\u2026' onConfirm={() => blockUser(id)} />"
+    },
+    {
+      label: "Body slot + type-to-confirm",
+      code: "<DestructiveActionModal open={open} onOpenChange={setOpen} title='Delete this post?' confirmText='gold rush' confirmLabel='Delete forever' onConfirm={handleDelete}><Note tone='warning'>Collectors who minted this edition keep their copies.</Note></DestructiveActionModal>"
+    }
+  ]
+};
+export {
+  destructiveActionModalMeta
+};

package/dist/components/destructive-action-modal/index.js

@@ -0,0 +1,9 @@
+// src/components/destructive-action-modal/index.ts
+import {
+  DestructiveActionModal
+} from "./destructive-action-modal.js";
+import { destructiveActionModalMeta } from "./destructive-action-modal.meta.js";
+export {
+  DestructiveActionModal,
+  destructiveActionModalMeta
+};