cortena-ui 1.2.0 → 1.3.0

package/src/components/dropzone.tsx

@@ -21,6 +21,30 @@ import { cn } from "@/lib/cn";
  * `onFiles` receives only the accepted files; rejections go to `onReject`.
  * `FileList` and `formatFileSize` are separate parts for listing what was
  * picked, so a form can keep the zone and the list in different places.
+ *
+ * ## Wrapping a whole page as a drop target
+ *
+ * `noClick` and `noKeyboard` turn off the two activators that only make sense
+ * on a dashed box: clicking anywhere inside opens the file dialog, and Enter /
+ * Space on the focused root does the same. A page-sized zone wraps content
+ * that has its own buttons and inputs, so both have to go — otherwise every
+ * click in the page opens a file picker.
+ *
+ * ```tsx
+ * <Dropzone noClick noKeyboard onFiles={upload} className="min-h-dvh border-0 bg-transparent p-0">
+ *   {({ isDragActive, open }) => (
+ *     <>
+ *       <PageContent />
+ *       <Button onClick={open}>Browse…</Button>
+ *       {isDragActive ? <DropHint /> : null}
+ *     </>
+ *   )}
+ * </Dropzone>
+ * ```
+ *
+ * The render-prop form gets react-dropzone's `open()`, which is the way back
+ * to the file dialog from a deliberate control. With `noClick` the root also
+ * drops its `cursor-pointer`, since it is no longer clickable.
  */
 
 const UNITS = ["B", "KB", "MB", "GB", "TB"] as const;
@@ -71,6 +95,10 @@ export interface DropzoneProps extends Omit<
   /** Most files accepted per drop; `0` means unlimited. */
   maxFiles?: number;
   disabled?: boolean;
+  /** Do not open the file dialog on click; for a zone that wraps clickable content. @default false */
+  noClick?: boolean;
+  /** Do not open the file dialog on Enter or Space; pair with `noClick`. @default false */
+  noKeyboard?: boolean;
   /** Primary line of the default body. */
   label?: React.ReactNode;
   /** Muted second line of the default body; derived from `accept` and `maxSize` when omitted. */
@@ -87,6 +115,8 @@ function Dropzone({
   maxSize,
   maxFiles,
   disabled = false,
+  noClick = false,
+  noKeyboard = false,
   label,
   hint,
   children,
@@ -100,6 +130,8 @@ function Dropzone({
     maxSize,
     maxFiles,
     disabled,
+    noClick,
+    noKeyboard,
     onDropAccepted: (files) => onFiles(files),
     onDropRejected: (rejections) => onReject?.(rejections),
   });
@@ -168,7 +200,7 @@ function Dropzone({
         className: cn(
           "group/dropzone flex flex-col items-center justify-center gap-2 p-6 text-center",
           "rounded-[var(--ds-radius-lg)] border border-dashed border-[var(--ds-border)] bg-[var(--ds-card)]",
-          "cursor-pointer select-none outline-none",
+          noClick ? "select-none outline-none" : "cursor-pointer select-none outline-none",
           "transition-[border-color,background-color] duration-[var(--ds-duration-fast)] ease-[var(--ds-ease-out)]",
           "hover:border-[var(--ds-border-strong)] hover:bg-[var(--ds-hover)]",
           "focus-visible:border-[var(--ds-ring)] focus-visible:ring-[3px] focus-visible:ring-[var(--ds-ring)]/40",
@@ -184,6 +216,8 @@ function Dropzone({
       data-reject={isDragReject || undefined}
       data-focused={isFocused || undefined}
       data-disabled={disabled || undefined}
+      data-no-click={noClick || undefined}
+      data-no-keyboard={noKeyboard || undefined}
     >
       <input data-slot="dropzone-input" {...getInputProps()} />
       {body}

package/src/components/section-card.tsx

@@ -29,6 +29,10 @@ export interface SectionCardProps extends Omit<CardProps, "title"> {
  * SectionCard — a Card with a header row (title, description, actions), a
  * body and an optional footer. It composes the Card parts rather than
  * restyling them, so a SectionCard and a hand-built Card look identical.
+ *
+ * `render` is Card's and reaches the outer element, so a section card can be
+ * the landmark it is named after: `render={<section aria-labelledby={id} />}`
+ * with the same `id` on the title, or `render={<aside />}` for a side panel.
  */
 function SectionCard({
   title,

package/src/components/select.tsx

@@ -18,9 +18,38 @@ import { cn } from "@/lib/cn";
  * - `onValueChange` receives `(value, eventDetails)`.
  * - `SelectContent` defaults to the dropdown layout; pass
  *   `alignItemWithTrigger` for Base UI's native-like overlay of the selected item.
+ *
+ * ## Typing the value
+ *
+ * `null` is the cleared / placeholder state, so `onValueChange` always hands
+ * back `Value | null`, never bare `Value`. Name the value type on the element
+ * to keep that union at `string | null` instead of letting inference widen it:
+ *
+ * ```tsx
+ * const [status, setStatus] = useState("");
+ *
+ * <Select<string>
+ *   // "" is not a value any item carries; `|| null` is the placeholder state,
+ *   // which is what makes SelectValue fall back to its `placeholder`.
+ *   value={status || null}
+ *   onValueChange={(next) => setStatus(next ?? "")} // next: string | null
+ * >
+ * ```
+ *
+ * Without the explicit `<string>` the type argument is inferred from `value`,
+ * so a `string | null` value widens `Value` and the handler's parameter turns
+ * into `string | null | null`. Multi-select narrows too:
+ * `<Select<string, true> multiple>` hands back `string[]`, never `null`.
+ *
+ * `SelectProps` is the same props type, for a wrapper that forwards them.
  */
+export type SelectProps<
+  Value = string,
+  Multiple extends boolean | undefined = false,
+> = SelectPrimitive.Root.Props<Value, Multiple>;
+
 function Select<Value, Multiple extends boolean | undefined = false>(
-  props: SelectPrimitive.Root.Props<Value, Multiple>,
+  props: SelectProps<Value, Multiple>,
 ) {
   return <SelectPrimitive.Root {...props} />;
 }

package/src/components/sheet.tsx

@@ -2,7 +2,7 @@
 
 import { Dialog as SheetPrimitive } from "@base-ui/react/dialog";
 import { cva, type VariantProps } from "class-variance-authority";
-import type * as React from "react";
+import * as React from "react";
 import { cn } from "@/lib/cn";
 
 /**
@@ -12,9 +12,43 @@ import { cn } from "@/lib/cn";
  * Description, Close); only the Popup's placement differs, chosen by `side`.
  * `SheetContent` composes Portal + Backdrop + Popup so consumers keep writing
  * `<SheetContent side="right">…</SheetContent>`.
+ *
+ * ## Non-modal side panels
+ *
+ * `modal={false}` is the help-panel / inspector case: a sheet read *alongside*
+ * the app rather than instead of it. No backdrop is rendered, focus is not
+ * trapped, page scroll is not locked, and the rest of the page stays clickable,
+ * so a user can keep working with the panel open. `modal="trap-focus"` is the
+ * middle setting Base UI offers: focus stays inside, the page still scrolls.
+ *
+ * ```tsx
+ * <Sheet modal={false} open={helpOpen} onOpenChange={setHelpOpen}>
+ *   <SheetContent side="right" disablePointerDismissal>…</SheetContent>
+ * </Sheet>
+ * ```
+ *
+ * A non-modal sheet closes when focus or a press leaves it; pass
+ * `disablePointerDismissal` (a Base UI Root prop, forwarded) to keep it open
+ * until the user closes it. `modal` is on the Root because that is where Base
+ * UI reads it; `SheetContent` picks the backdrop up from there through context.
  */
-function Sheet(props: SheetPrimitive.Root.Props) {
-  return <SheetPrimitive.Root {...props} />;
+const SheetModalContext = React.createContext<boolean | "trap-focus">(true);
+
+export interface SheetProps extends SheetPrimitive.Root.Props {
+  /**
+   * `true` (default) traps focus, locks page scroll and draws a backdrop.
+   * `false` draws no backdrop and traps nothing, for a panel read alongside
+   * the app. `"trap-focus"` keeps focus in but leaves the page scrollable.
+   */
+  modal?: boolean | "trap-focus";
+}
+
+function Sheet({ modal = true, ...props }: SheetProps) {
+  return (
+    <SheetModalContext.Provider value={modal}>
+      <SheetPrimitive.Root modal={modal} {...props} />
+    </SheetModalContext.Provider>
+  );
 }
 
 function SheetTrigger(props: SheetPrimitive.Trigger.Props) {
@@ -85,12 +119,14 @@ function SheetContent({
   container,
   ...props
 }: SheetContentProps) {
+  const modal = React.useContext(SheetModalContext);
   return (
     <SheetPortal keepMounted={keepMounted} container={container}>
-      <SheetOverlay />
+      {modal === false ? null : <SheetOverlay />}
       <SheetPrimitive.Popup
         data-slot="sheet-content"
         data-side={side}
+        data-modal={modal === false ? undefined : modal === true ? "" : modal}
         className={cn(sheetVariants({ side }), className)}
         {...props}
       >

package/src/components/sortable-list.tsx

@@ -4,7 +4,9 @@ import {
   DndContext,
   DragOverlay,
   KeyboardSensor,
+  MouseSensor,
   PointerSensor,
+  TouchSensor,
   closestCenter,
   useSensor,
   useSensors,
@@ -40,8 +42,29 @@ import { cn } from "@/lib/cn";
  * By default the whole row is the drag activator. Pass `handle` to restrict
  * dragging to a `<SortableHandle>` (or any element given `handleProps`) so
  * buttons and inputs inside a row stay clickable.
+ *
+ * ## Touch
+ *
+ * A pointer drag and a touch scroll start the same way, so something has to
+ * say which one a finger means. In handle mode only the small handle is
+ * `touch-none`, so the rest of the row scrolls: nothing to decide. In
+ * whole-row mode the whole row is `touch-none`, which is why a touch list
+ * whose rows are the activators cannot be scrolled by dragging over them.
+ *
+ * `touchScroll` is the way out, and it defaults to whichever of those is
+ * already true — `true` in handle mode, `false` in whole-row mode, so existing
+ * lists behave exactly as before. Setting it `true` on a whole-row list drops
+ * `touch-none` and swaps the PointerSensor for a MouseSensor plus a
+ * TouchSensor with delay activation: a quick swipe scrolls, a press held for
+ * {@link TOUCH_DELAY_MS} picks the row up. `false` in handle mode is the
+ * opposite trade — the row never scrolls under a finger.
  */
 
+/** How long a finger must rest on a row before it becomes a drag. */
+const TOUCH_DELAY_MS = 250;
+/** How far it may slip in that time and still count as a press, not a scroll. */
+const TOUCH_TOLERANCE_PX = 8;
+
 /** Spread onto the element that should start a drag. */
 export interface SortableHandleProps extends Partial<DraggableAttributes> {
   ref: (element: HTMLElement | null) => void;
@@ -63,17 +86,40 @@ export interface SortableRenderState {
   isDragging: boolean;
 }
 
+/** What moved where, passed to `onReorder` alongside the reordered array. */
+export interface SortableReorderDetails {
+  /** Index the item came from, in the array as it was passed in. */
+  from: number;
+  /** Index it landed on. */
+  to: number;
+  /** Id of the item that moved (`getId` of the dragged item). */
+  activeId: UniqueIdentifier;
+  /** Id of the item it was dropped onto. */
+  overId: UniqueIdentifier;
+}
+
 export interface SortableListProps<T> extends Omit<React.ComponentProps<"ul">, "children"> {
   items: readonly T[];
   /** Stable id per item; must be unique within the list. */
   getId: (item: T) => UniqueIdentifier;
-  /** Called with the reordered array after a successful drop. */
-  onReorder: (next: T[]) => void;
+  /**
+   * Called with the reordered array after a successful drop, and with the move
+   * itself — `{ from, to, activeId, overId }` — for a server that persists a
+   * position rather than the whole list.
+   */
+  onReorder: (next: T[], details: SortableReorderDetails) => void;
   renderItem: (item: T, state: SortableRenderState) => React.ReactNode;
   /** Layout axis; also selects the sorting strategy. */
   orientation?: "vertical" | "horizontal";
   /** Only a `<SortableHandle>` (or an element given `handleProps`) starts a drag. */
   handle?: boolean;
+  /**
+   * Let a finger scroll the page over the rows. Defaults to `handle`: `true`
+   * in handle mode, `false` in whole-row mode, which is what each already did.
+   * `true` on a whole-row list drops `touch-none` and uses a TouchSensor with
+   * delay activation, so a swipe scrolls and a held press drags.
+   */
+  touchScroll?: boolean;
   /** Disables every sensor and hides the handles. */
   disabled?: boolean;
   /** Class name for each item wrapper. */
@@ -106,11 +152,12 @@ interface SortableItemProps<T> {
   item: T;
   handle: boolean;
   disabled: boolean;
+  touchScroll: boolean;
   renderItem: SortableListProps<T>["renderItem"];
   className: string | undefined;
 }
 
-function SortableItem<T>({ id, item, handle, disabled, renderItem, className }: SortableItemProps<T>) {
+function SortableItem<T>({ id, item, handle, disabled, touchScroll, renderItem, className }: SortableItemProps<T>) {
   const { attributes, listeners, setNodeRef, setActivatorNodeRef, transform, transition, isDragging } =
     useSortable({ id, disabled });
 
@@ -134,7 +181,9 @@ function SortableItem<T>({ id, item, handle, disabled, renderItem, className }:
         style={{ transform: CSS.Translate.toString(transform), transition }}
         className={cn(
           itemClassName,
-          !handle && !disabled && "cursor-grab touch-none data-[dragging]:cursor-grabbing",
+          !handle && !disabled && "cursor-grab data-[dragging]:cursor-grabbing",
+          // touch-action is what decides whether a finger scrolls or drags.
+          !touchScroll && !disabled && "touch-none",
           className,
         )}
         {...rowActivator}
@@ -184,15 +233,27 @@ function SortableList<T>({
   orientation = "vertical",
   handle = false,
   disabled = false,
+  touchScroll = handle,
   itemClassName: itemClass,
   className,
   ...props
 }: SortableListProps<T>) {
   const [activeId, setActiveId] = React.useState<UniqueIdentifier | null>(null);
-  const sensors = useSensors(
-    useSensor(PointerSensor, { activationConstraint: { distance: 4 } }),
-    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
-  );
+  // Only a whole-row list needs the split sensors: in handle mode the row is
+  // already scrollable because only the handle is touch-none, and swapping
+  // sensors there would put a 250 ms delay on the handle for no gain.
+  const delayTouch = touchScroll && !handle;
+  // Every sensor is created on every render (they are hooks); which ones are
+  // handed to DndContext is what changes.
+  const pointerSensor = useSensor(PointerSensor, { activationConstraint: { distance: 4 } });
+  const mouseSensor = useSensor(MouseSensor, { activationConstraint: { distance: 4 } });
+  const touchSensor = useSensor(TouchSensor, {
+    activationConstraint: { delay: TOUCH_DELAY_MS, tolerance: TOUCH_TOLERANCE_PX },
+  });
+  const keyboardSensor = useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates });
+  const pointerSensors = useSensors(pointerSensor, keyboardSensor);
+  const splitSensors = useSensors(mouseSensor, touchSensor, keyboardSensor);
+  const sensors = delayTouch ? splitSensors : pointerSensors;
   const ids = React.useMemo(() => items.map(getId), [items, getId]);
   const activeItem = activeId === null ? undefined : items[ids.indexOf(activeId)];
 
@@ -207,7 +268,12 @@ function SortableList<T>({
       const from = ids.indexOf(active.id);
       const to = ids.indexOf(over.id);
       if (from < 0 || to < 0) return;
-      onReorder(arrayMove([...items], from, to));
+      onReorder(arrayMove([...items], from, to), {
+        from,
+        to,
+        activeId: active.id,
+        overId: over.id,
+      });
     },
     [ids, items, onReorder],
   );
@@ -230,6 +296,7 @@ function SortableList<T>({
           data-slot="sortable-list"
           data-orientation={orientation}
           data-disabled={disabled || undefined}
+          data-touch-scroll={touchScroll ? "" : undefined}
           className={cn(
             "flex list-none gap-2 p-0",
             orientation === "horizontal" ? "flex-row flex-wrap" : "flex-col",
@@ -244,6 +311,7 @@ function SortableList<T>({
               item={item}
               handle={handle}
               disabled={disabled}
+              touchScroll={touchScroll}
               renderItem={renderItem}
               className={itemClass}
             />

package/src/components/spinner.tsx

@@ -6,21 +6,38 @@ import { cn } from "@/lib/cn";
 export interface SpinnerProps extends React.ComponentProps<"span"> {
   /** Diameter in px. Defaults to 16. */
   size?: number;
+  /**
+   * `inverse` for a spinner on a filled surface — inside a primary or
+   * destructive Button, on a toast, on any `-foreground` pairing. The default
+   * ring is `--ds-border` with a `--ds-primary` leading edge, which all but
+   * disappears on a primary fill; `inverse` draws both from
+   * `--ds-primary-foreground` instead.
+   */
+  tone?: "default" | "inverse";
 }
 
 /**
- * Spinner — a ring with a primary-coloured leading edge. Announces itself as
+ * Spinner — a ring with a coloured leading edge. Announces itself as
  * `role="status"` with a "Loading" label; pass `aria-label` to override.
+ *
+ * ```tsx
+ * <Button disabled>
+ *   <Spinner tone="inverse" /> Saving…
+ * </Button>
+ * ```
  */
-function Spinner({ className, size = 16, style, ...props }: SpinnerProps) {
+function Spinner({ className, size = 16, tone = "default", style, ...props }: SpinnerProps) {
   return (
     <span
       data-slot="spinner"
+      data-tone={tone}
       role="status"
       aria-label="Loading"
       className={cn(
-        "inline-block shrink-0 animate-spin rounded-[var(--ds-radius-full)]",
-        "border-2 border-[var(--ds-border)] border-t-[var(--ds-primary)]",
+        "inline-block shrink-0 animate-spin rounded-[var(--ds-radius-full)] border-2",
+        tone === "inverse"
+          ? "border-[var(--ds-primary-foreground)]/35 border-t-[var(--ds-primary-foreground)]"
+          : "border-[var(--ds-border)] border-t-[var(--ds-primary)]",
         className,
       )}
       style={{ width: size, height: size, ...style }}

package/src/components/status-dot.tsx

@@ -3,12 +3,25 @@
 import type * as React from "react";
 import { cn } from "@/lib/cn";
 
-type StatusDotTone = "accent" | "success" | "warning" | "danger" | "info" | "neutral";
+/**
+ * The error tone is `destructive`, the same spelling Button, Alert and Badge
+ * use. `danger` is a deprecated alias of it and paints the same.
+ */
+type StatusDotTone =
+  | "accent"
+  | "success"
+  | "warning"
+  | "destructive"
+  /** @deprecated Use `destructive`; this alias paints the same. */
+  | "danger"
+  | "info"
+  | "neutral";
 
 const TONE_CLASS: Record<StatusDotTone, string> = {
   accent: "bg-[var(--ds-primary)]",
   success: "bg-[var(--ds-success)]",
   warning: "bg-[var(--ds-warning)]",
+  destructive: "bg-[var(--ds-destructive)]",
   danger: "bg-[var(--ds-destructive)]",
   info: "bg-[var(--ds-info)]",
   neutral: "bg-[var(--ds-text-tertiary)]",

package/src/index.ts

@@ -11,6 +11,8 @@ export type { AlertProps } from "@/components/alert";
 export { Avatar, AvatarFallback, AvatarImage } from "@/components/avatar";
 export { Badge, badgeVariants } from "@/components/badge";
 export type { BadgeProps } from "@/components/badge";
+export { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from "@/components/breadcrumb";
+export type { BreadcrumbLinkProps } from "@/components/breadcrumb";
 export { ButtonLink } from "@/components/button-link";
 export type { ButtonLinkProps } from "@/components/button-link";
 export { Button, buttonVariants } from "@/components/button";
@@ -69,14 +71,14 @@ export type { SectionCardProps } from "@/components/section-card";
 export { Segmented } from "@/components/segmented";
 export type { SegmentedOption, SegmentedProps } from "@/components/segmented";
 export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue } from "@/components/select";
-export type { SelectContentProps, SelectTriggerProps } from "@/components/select";
+export type { SelectContentProps, SelectProps, SelectTriggerProps } from "@/components/select";
 export { Separator } from "@/components/separator";
 export type { SeparatorProps } from "@/components/separator";
 export { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, sheetVariants } from "@/components/sheet";
-export type { SheetContentProps } from "@/components/sheet";
+export type { SheetContentProps, SheetProps } from "@/components/sheet";
 export { Skeleton } from "@/components/skeleton";
 export { SortableHandle, SortableList, arrayMove } from "@/components/sortable-list";
-export type { SortableHandleProps, SortableListProps, SortableRenderState } from "@/components/sortable-list";
+export type { SortableHandleProps, SortableListProps, SortableRenderState, SortableReorderDetails } from "@/components/sortable-list";
 export { Spinner } from "@/components/spinner";
 export type { SpinnerProps } from "@/components/spinner";
 export { StatusDot } from "@/components/status-dot";

package/src/lib/render.tsx

@@ -0,0 +1,39 @@
+import type * as React from "react";
+
+/**
+ * The `render` prop for the components that are plain markup rather than Base
+ * UI primitives (Card, SectionCard, ButtonLink, BreadcrumbLink).
+ *
+ * Base UI parts take their own `render` and need nothing from here. The rest
+ * are a `<div>` or an `<a>` this package writes itself, and a consumer
+ * sometimes needs a different element under the same styling: a Card that is
+ * the page's `<aside>` landmark, or a link that is the router's `<Link>`.
+ * Passing an element rather than a component keeps the call site readable and
+ * lets the caller set props on it (`render={<Link to="/x" />}`).
+ *
+ * `props` wins over the passed element's own props, so the `className` and
+ * handlers a component computed are not silently dropped, while the element's
+ * own props (`href`, `to`, `aria-labelledby`) come through untouched. What a
+ * component lets a *caller* override is decided by the order it builds `props`
+ * in, not here. Children are `children`, falling back to the element's.
+ */
+export type RenderProp = React.ReactElement<Record<string, unknown>>;
+
+export function renderWith(
+  render: RenderProp | undefined,
+  props: Record<string, unknown>,
+  children: React.ReactNode,
+  Fallback: React.ElementType,
+): React.ReactElement {
+  if (!render) {
+    const Element = Fallback;
+    return <Element {...props}>{children}</Element>;
+  }
+  const Element = render.type as React.ElementType;
+  const given = render.props as { children?: React.ReactNode };
+  return (
+    <Element {...(render.props as Record<string, unknown>)} {...props}>
+      {children ?? given.children}
+    </Element>
+  );
+}