@sableui/react 0.13.1 → 0.14.0

package/dist/components/confirm-button/confirm-button.js

@@ -0,0 +1,179 @@
+"use client";
+
+// src/components/confirm-button/confirm-button.tsx
+import {
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+import { cn } from "../../lib/cn.js";
+import { isPromise } from "../../lib/is-promise.js";
+import { StackedActionsContext } from "../../lib/presentation.js";
+import { motionAttribute } from "../../motion/MotionProvider.js";
+import { useAutoSize } from "../../motion/useAutoSize.js";
+import { Button } from "../button/button.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var OPTICAL_START = "[--button-ps:calc(var(--button-px)-(--spacing(0.5)))] ps-(--button-ps)";
+var DOUBLE_PRESS_GUARD_MS = 300;
+function defaultConfirmLabel(label) {
+  if (typeof label !== "string" || label.trim() === "") return "Confirm?";
+  return `Confirm ${label.charAt(0).toLowerCase()}${label.slice(1)}?`;
+}
+function ConfirmButton({
+  children,
+  confirmLabel,
+  onConfirm,
+  timeout = 3e3,
+  variant = "secondary",
+  confirmVariant = "destructive",
+  size,
+  icon,
+  confirmHint = "Press again to confirm.",
+  motion,
+  disabled,
+  className,
+  onBlur,
+  onKeyDown,
+  ref,
+  ...props
+}) {
+  const stacked = useContext(StackedActionsContext);
+  const callerSized = /(^|\s)([\w-]+:)*(w-|flex-1|grow(\s|$)|basis-)/.test(className ?? "");
+  const autoSize = useAutoSize({ enabled: !stacked && !callerSized });
+  const [phase, setPhase] = useState("idle");
+  const armedAt = useRef(0);
+  const rootRef = useRef(null);
+  const armed = phase !== "idle";
+  const prompt = confirmLabel ?? defaultConfirmLabel(children);
+  const disarm = useCallback(() => setPhase((p) => p === "armed" ? "idle" : p), []);
+  useEffect(() => {
+    if (phase !== "armed") return;
+    const timer = setTimeout(disarm, timeout);
+    return () => clearTimeout(timer);
+  }, [phase, timeout, disarm]);
+  useEffect(() => {
+    if (phase !== "armed") return;
+    const onPointerDown = (event) => {
+      if (!rootRef.current?.contains(event.target)) disarm();
+    };
+    document.addEventListener("pointerdown", onPointerDown, true);
+    return () => document.removeEventListener("pointerdown", onPointerDown, true);
+  }, [phase, disarm]);
+  useEffect(() => {
+    if (disabled) setPhase((p) => p === "armed" ? "idle" : p);
+  }, [disabled]);
+  const handleClick = (_event) => {
+    if (phase === "idle") {
+      armedAt.current = Date.now();
+      setPhase("armed");
+      return;
+    }
+    if (phase !== "armed" || Date.now() - armedAt.current < DOUBLE_PRESS_GUARD_MS) return;
+    const result = onConfirm();
+    if (isPromise(result)) {
+      setPhase("confirming");
+      const idle = () => setPhase("idle");
+      result.then(idle, idle);
+      return result;
+    }
+    setPhase("idle");
+    return result;
+  };
+  const handleKeyDown = (event) => {
+    if (event.key === "Escape" && phase === "armed") {
+      event.preventDefault();
+      event.stopPropagation();
+      disarm();
+    }
+    onKeyDown?.(event);
+  };
+  const handleBlur = (event) => {
+    disarm();
+    onBlur?.(event);
+  };
+  const setRefs = (node) => {
+    rootRef.current = node;
+    autoSize.outerRef.current = node;
+    if (typeof ref === "function") ref(node);
+    else if (ref) ref.current = node;
+  };
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs(
+      Button,
+      {
+        ...props,
+        ref: setRefs,
+        size,
+        variant: armed ? confirmVariant : variant,
+        disabled,
+        "data-state": armed ? "armed" : "idle",
+        "data-motion": motionAttribute(motion),
+        className: cn(
+          // overflow-clip: while the width eases, the content is already at
+          // its new size, so it is clipped to the button rather than painting
+          // past its fill. A ring is a box-shadow and is not clipped.
+          "relative overflow-clip motion-size",
+          // The icon lives inside the measured span (below), not in Button's
+          // iconStart slot, so Button's optical start padding is restated.
+          icon != null && OPTICAL_START,
+          className
+        ),
+        onClick: handleClick,
+        onKeyDown: handleKeyDown,
+        onBlur: handleBlur,
+        children: [
+          /* @__PURE__ */ jsxs(
+            "span",
+            {
+              ref: autoSize.innerRef,
+              className: "inline-flex w-max items-center gap-(--control-gap) transition-opacity duration-(--motion-duration-fast) ease-standard",
+              children: [
+                icon,
+                /* @__PURE__ */ jsxs("span", { className: "inline-grid overflow-x-clip", children: [
+                  /* @__PURE__ */ jsx(ConfirmLabel, { active: !armed, children }),
+                  /* @__PURE__ */ jsx(ConfirmLabel, { active: armed, children: prompt })
+                ] })
+              ]
+            }
+          ),
+          phase === "armed" ? /* @__PURE__ */ jsx(
+            "span",
+            {
+              "aria-hidden": "true",
+              "data-slot": "confirm-countdown",
+              className: "pointer-events-none absolute inset-x-(--button-px) bottom-1 h-0.5 origin-left rounded-full bg-current opacity-40 transition-[scale] ease-linear scale-x-0 starting:scale-x-100 rtl:origin-right",
+              style: {
+                transitionDuration: `calc(${timeout}ms * var(--motion-scale, 1) * var(--motion-expressive, 1))`
+              }
+            }
+          ) : null
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx("span", { role: "status", className: "sr-only", children: phase === "armed" ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      prompt,
+      " ",
+      confirmHint
+    ] }) : null })
+  ] });
+}
+ConfirmButton.displayName = "ConfirmButton";
+function ConfirmLabel({ active, children }) {
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      "aria-hidden": active ? void 0 : "true",
+      "data-active": active,
+      className: cn(
+        "col-start-1 row-start-1 flex justify-center transition-opacity duration-(--motion-duration-fast) ease-standard",
+        active ? "w-max" : "w-0 opacity-0"
+      ),
+      children: /* @__PURE__ */ jsx("span", { className: "sable-label-trim", children })
+    }
+  );
+}
+export {
+  ConfirmButton
+};

package/dist/components/confirm-button/confirm-button.meta.js

@@ -0,0 +1,143 @@
+// src/components/confirm-button/confirm-button.meta.ts
+var confirmButtonMeta = {
+  name: "ConfirmButton",
+  summary: 'An inline two-step confirm for a low-stakes destructive or irreversible action: the first press arms it ("Delete" \u2192 "Confirm delete?", destructive), a second press within a few seconds runs it, and leaving it disarms it.',
+  status: "stable",
+  keywords: [
+    "confirm",
+    "confirmation",
+    "two-step",
+    "press again",
+    "click again",
+    "arm",
+    "delete",
+    "remove",
+    "destructive",
+    "inline confirm",
+    "hold to confirm"
+  ],
+  usage: {
+    description: "Use ConfirmButton when an action deserves one beat of second thought but not a modal: deleting a draft, removing a row, revoking one token, clearing a list that can be rebuilt. The question appears on the button the user is already pressing, so confirming costs one more press in the same place and backing out costs nothing.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: 'Keep the idle label a plain verb ("Delete", "Remove", "Revoke") and let the confirm label ask about it ("Confirm delete?" by default, or `confirmLabel`). The user should read the consequence on the very control they are about to press again.'
+      },
+      {
+        guidance: "do",
+        description: "Leave room for it to grow. The button eases wider to fit the question, so give it space at the end of a row or in a table's action column rather than wedging it between fixed-width neighbours."
+      },
+      {
+        guidance: "do",
+        description: "Return the promise from `onConfirm` when the action is async. The button stays armed with a spinner until it settles and refuses further presses, so a slow network cannot run it twice."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it for high-stakes or wide-reaching actions \u2014 deleting a project, an account, anything other people depend on. Those need the consequence spelled out and a typed or deliberate confirmation; use DestructiveActionModal.",
+        instead: ["DestructiveActionModal"]
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it where an undo is possible. If the action can be reversed, run it on the first press and offer Undo in a Toast \u2014 no question at all is faster than a good question.",
+        instead: ["Toast"]
+      },
+      {
+        guidance: "dont",
+        description: 'Do not use it for a non-destructive primary action ("Save", "Send"). Asking twice for something harmless teaches people to press twice without reading, which is what defeats the confirm when it matters; use Button.',
+        instead: ["Button"]
+      }
+    ]
+  },
+  related: {
+    components: ["Button", "DestructiveActionModal", "Toast", "OverflowMenu"]
+  },
+  props: [
+    { name: "children", type: "ReactNode", description: 'The idle label \u2014 the action, e.g. "Delete".' },
+    {
+      name: "confirmLabel",
+      type: "ReactNode",
+      default: '"Confirm <label>?"',
+      description: 'The label while armed. Defaults to "Confirm delete?" for a text label "Delete" (first letter lowered) and "Confirm?" otherwise. Pass it to localise.'
+    },
+    {
+      name: "onConfirm",
+      type: "() => unknown",
+      description: "Runs on the second press while armed. Return a promise to hold the button armed with a spinner until it settles."
+    },
+    { name: "timeout", type: "number", default: "3000", description: "How long it waits for the second press, in ms. A decision time, so it is not scaled by motion settings." },
+    { name: "variant", type: "ButtonVariant", default: '"secondary"', description: "The idle look \u2014 any Button variant." },
+    { name: "confirmVariant", type: "ButtonVariant", default: '"destructive"', description: "The armed look \u2014 any Button variant." },
+    { name: "size", type: '"xs" | "sm" | "md" | "cta"', default: '"md"', description: "A labelled Button size. Icon-only sizes are excluded: the label is the interaction." },
+    { name: "icon", type: "ReactNode", description: 'A leading icon kept through both states, e.g. `<Icon name="trash" />`.' },
+    { name: "disabled", type: "boolean", default: "false", description: "Disables it; disabling while armed also disarms." },
+    {
+      name: "confirmHint",
+      type: "string",
+      default: '"Press again to confirm."',
+      description: "Read to assistive tech after the armed label when it arms. Override to localise."
+    },
+    {
+      name: "motion",
+      type: '"full" | "subtle" | "off"',
+      default: '"full"',
+      description: "How much motion this component uses: `full` (default) inherits the app's policy, `subtle` keeps feedback and drops the flourish, `off` stills it. It can only turn motion down \u2014 it never overrides a reader's reduce-motion setting. The width easing and the draining countdown are the flourish; the label cross-fade and colour change stay."
+    }
+  ],
+  variants: {
+    variant: ["primary", "secondary", "ghost", "outline", "destructive", "link", "floating", "field", "on-color", "on-color-outline", "on-color-ghost"],
+    confirmVariant: ["destructive", "primary", "secondary", "outline"],
+    size: ["xs", "sm", "md", "cta"]
+  },
+  tokensUsed: ["secondary", "secondary-foreground", "destructive", "destructive-foreground", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "It is a button in a row of actions, and arrives with that row. Its moment is the arming, not the mount."
+    },
+    {
+      slot: "response",
+      recipe: "motion-press",
+      part: "Root",
+      why: "Inherited from Button with motion-interactive. The press settle confirms the first press landed even before the label has finished changing \u2014 which is what stops a second, accidental press."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-size",
+      part: "Root",
+      why: "Arming changes the label, so the button's width changes. Easing it makes the button visibly grow into the question and its neighbours travel, instead of the row jumping under the pointer that is about to press again. useAutoSize measures the content and writes a px width for motion-size to ease between (a content-sized box is width:auto before and after, which cannot transition). The labels cross-fade in one cell so there is never a frame with both or neither."
+    },
+    {
+      slot: "activity",
+      recipe: "custom",
+      part: "Countdown",
+      why: "While armed, a thin line drains along the foot of the button over the timeout \u2014 the only way to see that the question expires. A transition on scale, timed by the `timeout` prop and multiplied by the motion scale and expressive factor, so under reduced motion or `subtle` it is absent rather than frozen full."
+    }
+  ],
+  a11y: [
+    "A native <button> through Button. Focus stays on it through both presses; Enter and Space confirm exactly as a click does.",
+    "Only the current label is in the accessible name \u2014 the other is aria-hidden \u2014 so the name changes to the question while armed.",
+    `Arming is also announced through a polite role=status region outside the button ("Confirm delete? Press again to confirm."), because a focused button's name change is not read by every screen reader.`,
+    "Escape disarms and is consumed, so it does not also close the dialog or popover around it. Focus leaving, a press elsewhere, or the timeout disarm it too.",
+    "A second press within 300ms of arming is ignored: a double-click is a habit, not a decision.",
+    "Under reduced motion the label still changes and the colour still turns; only the width easing and countdown are dropped."
+  ],
+  examples: [
+    {
+      label: "Delete a row",
+      code: '<ConfirmButton icon={<Icon name="trash" />} onConfirm={() => removeRow(id)}>Delete</ConfirmButton>'
+    },
+    {
+      label: "Custom question, longer wait",
+      code: '<ConfirmButton variant="ghost" size="sm" confirmLabel="Revoke this key?" timeout={5000} onConfirm={revokeKey}>Revoke</ConfirmButton>'
+    },
+    {
+      label: "Async confirm",
+      code: "<ConfirmButton onConfirm={() => api.deleteDraft(draft.id)}>Discard draft</ConfirmButton>"
+    }
+  ]
+};
+export {
+  confirmButtonMeta
+};

package/dist/components/confirm-button/index.js

@@ -0,0 +1,7 @@
+// src/components/confirm-button/index.ts
+import { ConfirmButton } from "./confirm-button.js";
+import { confirmButtonMeta } from "./confirm-button.meta.js";
+export {
+  ConfirmButton,
+  confirmButtonMeta
+};

package/dist/components/context-card/context-card.meta.js

@@ -26,7 +26,8 @@ var contextCardMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not open it on click. It is a hover/focus preview; making it click-triggered gives you a Popover with no dismiss affordance and no way to reach the content it previews."
+        description: "Do not open it on click. It is a hover/focus preview; making it click-triggered gives you a Popover with no dismiss affordance and no way to reach the content it previews.",
+        instead: ["Popover"]
       }
     ],
     anatomy: [

package/dist/components/data-table/data-table.js

@@ -122,8 +122,12 @@ function DataTable({
                     /* @__PURE__ */ jsx(
                       Icon,
                       {
-                        name: active && sort.direction === "desc" ? "chevron-down" : "chevron-up",
-                        className: cn("text-xs", !active && "opacity-60")
+                        name: "chevron-up",
+                        className: cn(
+                          "text-xs motion-interactive",
+                          active && sort.direction === "desc" && "rotate-180",
+                          !active && "opacity-60"
+                        )
                       }
                     )
                   ]

package/dist/components/data-table/data-table.meta.js

@@ -139,6 +139,38 @@ var dataTableMeta = {
     }
   ],
   tokensUsed: ["muted-foreground", "foreground", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "Rows render with the page or the query that produced them. Staggering rows in delays reading a table someone opened to scan."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Row",
+      why: "Body rows ease to a muted wash under the pointer (TableRow's recipe), which keeps the eye on the right line across a wide row of numbers. Sortable headers are ghost Buttons and answer on Button's recipe."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Sort chevron",
+      why: "One chevron turns to show direction instead of two glyphs swapping, so ascending to descending reads as the same column reversing. Its opacity rises from the resting 60% as the column becomes the sort."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Row",
+      why: "A checked row's fill eases in across its cells, so selecting by checkbox reads as the row being picked rather than a band stamped over it."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "DataTable has no loading state. While data is fetched, render Skeleton rows (motion-shimmer) in its place \u2014 only the caller knows a fetch is in flight."
+    }
+  ],
   a11y: [
     "Sorted columns set aria-sort=ascending/descending on the header cell.",
     "Sortable headers are real <button>s with a focus-visible ring, keyboard-operable.",

package/dist/components/dialog/dialog.meta.js

@@ -38,7 +38,8 @@ var dialogMeta = {
       },
       {
         guidance: "dont",
-        description: "Put large multipage workflows in a centered dialog. Use Sheet or a page route when the task needs space."
+        description: "Put large multipage workflows in a centered dialog. Use Sheet or a page route when the task needs space.",
+        instead: ["Sheet"]
       },
       {
         guidance: "do",
@@ -46,7 +47,8 @@ var dialogMeta = {
       },
       {
         guidance: "dont",
-        description: `Use size="fullscreen" for forms, confirmations, or anything that isn't media. A dialog that happens to need room is a Sheet or a page; the fullscreen affordances (dark scrim, corner close, centred content) all assume something to look at.`
+        description: `Use size="fullscreen" for forms, confirmations, or anything that isn't media. A dialog that happens to need room is a Sheet or a page; the fullscreen affordances (dark scrim, corner close, centred content) all assume something to look at.`,
+        instead: ["Sheet"]
       },
       {
         guidance: "dont",
@@ -54,7 +56,8 @@ var dialogMeta = {
       },
       {
         guidance: "dont",
-        description: "Open a dialog for passive status updates. Use Toast, Banner, or InlineStatus instead."
+        description: "Open a dialog for passive status updates. Use Toast, Banner, or InlineStatus instead.",
+        instead: ["Toast", "Banner", "InlineStatus"]
       },
       {
         guidance: "do",

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

@@ -47,7 +47,8 @@ var disclosurePickerMeta = {
       },
       {
         guidance: "dont",
-        description: "Use it in a page-register form. A form field that pushes the form down on open reads as a layout jump; that is Select's job."
+        description: "Use it in a page-register form. A form field that pushes the form down on open reads as a layout jump; that is Select's job.",
+        instead: ["Select"]
       },
       {
         guidance: "dont",

package/dist/components/entity/entity.meta.js

@@ -86,6 +86,32 @@ var entityMeta = {
     density: ["compact", "comfortable"]
   },
   tokensUsed: ["accent", "accent-foreground", "foreground", "muted-foreground", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "Rows arrive with the list they belong to. Entering one at a time is a stagger, and a stagger on a list someone opened to scan is a delay."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Root",
+      why: "Only the interactive row reacts: its hover fill, a step off the surface it sits on, eases in. A static row never fakes clickability, and an interactive one answers the pointer without flicker as it moves down a list."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Root",
+      why: "`selected` eases the fill onto the current row of a list\u2013detail view, so opening another record reads as the selection moving rather than two rows flashing."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "A record row has nothing of its own to wait for. A row whose action is pending puts a loading Button in `action`."
+    }
+  ],
   a11y: [
     "Default rows are presentational layout; semantics come from the content you place in title/subtitle/action.",
     "interactive rows render a real <button> around the leading visual and text, with its ::after stretched over the whole row \u2014 native focus, a focus-visible ring, and Enter/Space. The action slot sits outside that button and above the overlay, so a Button there stays valid HTML and keeps its own clicks.",