@eifi1/ui-kit 0.6.0 → 0.7.0

package/src/components/dialog-frame.tsx

@@ -42,6 +42,15 @@ export interface DialogFrameProps extends Omit<ModalProps, "labelledBy" | "child
    * calling `onClose` directly unmounts it at once.
    */
   actions?: ReactNode | ((close: () => void) => ReactNode);
+  /**
+   * Controls that belong to the HEADER rather than to the actions row — an "Edit"
+   * toggle, a status badge with a menu, a "Copy link" (kastlan). Rendered beside the
+   * title, before the optional X; on a phone, where title and controls do not fit on
+   * one line, they wrap under the title and the X keeps its corner.
+   *
+   * A function receives the animated close, as `actions` does.
+   */
+  headerActions?: ReactNode | ((close: () => void) => ReactNode);
   /**
    * Show an X in the header. Off by default: a centred dialog has a backdrop and
    * Escape, and a form dialog has a Cancel. On for a dialog that commits as it goes
@@ -52,8 +61,24 @@ export interface DialogFrameProps extends Omit<ModalProps, "labelledBy" | "child
   closeLabel?: string;
   /** Extra classes for the scrolling body (default spacing `space-y-3`). */
   bodyClassName?: string;
-  /** The body. */
-  children: ReactNode;
+  /**
+   * Extra classes for the header row (default padding `px-4 pt-4 pb-3`), merged last —
+   * `px-3` for a phone sheet whose body runs at `px-3`, so heading and fields share
+   * one gutter.
+   */
+  headerClassName?: string;
+  /**
+   * A rule under the header, the twin of the one over the actions row — for a tall or
+   * full-screen body that scrolls under a header which stays. The body then starts a
+   * step below the rule instead of flush against it.
+   */
+  headerDivider?: boolean;
+  /**
+   * The body. Optional: a dialog whose title, description and actions are the whole
+   * of it (a "you have unsynced changes" question) leaves it out, and the frame then
+   * renders no body at all rather than an empty padded one.
+   */
+  children?: ReactNode;
 }
 
 /**
@@ -92,9 +117,12 @@ export function DialogFrame({
   description,
   headingAs: Heading = "h2",
   actions,
+  headerActions,
   closeButton = false,
   closeLabel,
   bodyClassName,
+  headerClassName,
+  headerDivider = false,
   className,
   children,
   "aria-describedby": describedBy,
@@ -103,6 +131,8 @@ export function DialogFrame({
   const titleId = useId();
   const descriptionId = useId();
   const hasDescription = description !== undefined && description !== null;
+  // `false` too, so `{cond && <Body/>}` with a false `cond` means "no body".
+  const hasBody = children !== undefined && children !== null && children !== false;
 
   return (
     <Modal
@@ -116,30 +146,50 @@ export function DialogFrame({
       // to the body, which is the only part that should move.
       className={cn("flex flex-col overflow-hidden p-0", className)}
     >
-      <div className="flex shrink-0 items-start justify-between gap-2 px-4 pt-4 pb-3">
-        <div className="min-w-0">
-          <Heading id={titleId} className="text-lg font-semibold leading-snug text-[var(--text-primary)]">
-            {title}
-          </Heading>
-          {hasDescription && (
-            <p id={descriptionId} className="mt-0.5 text-sm text-[var(--text-muted)]">
-              {description}
-            </p>
-          )}
-        </div>
-        {closeButton && <FrameClose label={closeLabel} onClose={modal.onClose} />}
-      </div>
       <div
         className={cn(
-          // `min-h-0` is what lets a flex child shrink below its content and scroll;
-          // `last:pb-4` closes a frame that has no actions row under it.
-          "min-h-0 flex-1 space-y-3 overflow-y-auto overscroll-contain px-4 pb-3 last:pb-4",
-          bodyClassName,
+          // `last:pb-4`: a frame with neither body nor actions closes on its header.
+          "flex shrink-0 items-start justify-between gap-2 px-4 pt-4 pb-3 last:pb-4",
+          headerDivider && "border-b border-[var(--border)]",
+          headerClassName,
         )}
       >
-        {children}
+        {/* Title and header actions share a wrapping row of their own, so it is THEY
+            that wrap on a phone — the actions drop under a title that needs its 12rem —
+            while the X stays outside it, pinned to the top-end corner. */}
+        <div className="flex min-w-0 flex-1 flex-wrap items-start justify-between gap-x-3 gap-y-2">
+          <div className="min-w-0 grow basis-48">
+            <Heading id={titleId} className="text-lg font-semibold leading-snug text-[var(--text-primary)]">
+              {title}
+            </Heading>
+            {hasDescription && (
+              <p id={descriptionId} className="mt-0.5 text-sm text-[var(--text-muted)]">
+                {description}
+              </p>
+            )}
+          </div>
+          {headerActions !== undefined && headerActions !== null && headerActions !== false && (
+            <FrameHeaderActions actions={headerActions} onClose={modal.onClose} />
+          )}
+        </div>
+        {closeButton && <FrameClose label={closeLabel} onClose={modal.onClose} />}
       </div>
-      {actions !== undefined && actions !== null && <FrameActions actions={actions} onClose={modal.onClose} />}
+      {hasBody && (
+        <div
+          className={cn(
+            // `min-h-0` is what lets a flex child shrink below its content and scroll;
+            // `last:pb-4` closes a frame that has no actions row under it.
+            "min-h-0 flex-1 space-y-3 overflow-y-auto overscroll-contain px-4 pb-3 last:pb-4",
+            headerDivider && "pt-3",
+            bodyClassName,
+          )}
+        >
+          {children}
+        </div>
+      )}
+      {actions !== undefined && actions !== null && (
+        <FrameActions actions={actions} onClose={modal.onClose} divider={hasBody} />
+      )}
     </Modal>
   );
 }
@@ -161,18 +211,43 @@ function FrameClose({ label, onClose }: { label?: string; onClose: () => void })
   );
 }
 
+/** The header's own controls; a component for the same reason as {@link FrameClose}. */
+function FrameHeaderActions({
+  actions,
+  onClose,
+}: {
+  actions: NonNullable<DialogFrameProps["headerActions"]>;
+  onClose: () => void;
+}) {
+  const close = useContext(ModalCloseContext) ?? onClose;
+  return (
+    <div data-dialog-header-actions="" className="flex shrink-0 flex-wrap items-center gap-2">
+      {typeof actions === "function" ? actions(close) : actions}
+    </div>
+  );
+}
+
 function FrameActions({
   actions,
   onClose,
+  divider,
 }: {
   actions: NonNullable<DialogFrameProps["actions"]>;
   onClose: () => void;
+  /** Off when there is no body: nothing scrolls, so there is no edge to mark, and a
+   *  rule straight under the description would cut the question from its answers. */
+  divider: boolean;
 }) {
   const close = useContext(ModalCloseContext) ?? onClose;
   return (
     // The border marks where the scrolling stops; `flex-wrap` keeps three long
     // translated labels on a phone from pushing the row wider than the sheet.
-    <div className="flex shrink-0 flex-wrap items-center justify-end gap-2 border-t border-[var(--border)] px-4 py-3">
+    <div
+      className={cn(
+        "flex shrink-0 flex-wrap items-center justify-end gap-2 px-4 py-3",
+        divider && "border-t border-[var(--border)]",
+      )}
+    >
       {typeof actions === "function" ? actions(close) : actions}
     </div>
   );

package/src/components/disclosure.tsx

@@ -149,7 +149,27 @@ export interface DisclosureProps extends Omit<ComponentPropsWithoutRef<"div">, "
   headerClassName?: string;
   /** Extra classes for the body's wrapper — where its padding and spacing live. */
   bodyClassName?: string;
-  children: ReactNode;
+  /**
+   * Content at the far end of the header row, beside the title: a count, a date, a
+   * status chip, an action button. It is a SIBLING of the header button, never inside
+   * it — a button may not contain another interactive element, and a count inside it
+   * would also be read as part of the button's name. The header button still spans
+   * the row under it (a stretched hit area), so clicking the empty space or the
+   * card's chevron still toggles, while whatever sits in `trailing` gets its own
+   * clicks. With `trailing`, the card's chevron moves after it, to the row's end.
+   */
+  trailing?: ReactNode;
+  /**
+   * Trigger-only mode: the id of an element the CALLER renders elsewhere — the hidden
+   * rows of a table, a panel in another column — which this header shows and hides.
+   * The header's `aria-controls` points at it and the disclosure renders no body of
+   * its own (`children`, `bodyClassName` and `keepMounted` are ignored). Pair it with
+   * `open` / `onOpenChange`: the caller owns the state, since the caller renders what
+   * it governs.
+   */
+  controls?: string;
+  /** The body. Not rendered in trigger-only mode ({@link DisclosureProps.controls}). */
+  children?: ReactNode;
 }
 
 /**
@@ -178,6 +198,8 @@ export function Disclosure({
   disabled,
   headerClassName,
   bodyClassName,
+  trailing,
+  controls,
   className,
   children,
   ...rest
@@ -186,6 +208,10 @@ export function Disclosure({
   const open = controlled ?? own;
   const bodyId = useId();
   const card = variant === "card";
+  const triggerOnly = controls !== undefined;
+  // The card's header squares its lower corners only when a body opens under it.
+  const joined = open && !triggerOnly;
+  const hasTrailing = trailing !== undefined && trailing !== null && trailing !== false;
 
   const toggle = () => {
     const next = !open;
@@ -197,43 +223,79 @@ export function Disclosure({
     <button
       type="button"
       aria-expanded={open}
-      aria-controls={bodyId}
+      aria-controls={triggerOnly ? controls : bodyId}
       disabled={disabled}
       onClick={toggle}
+      data-disclosure-trigger=""
       className={cn(
         "flex w-full gap-2 text-start outline-none disabled:cursor-not-allowed disabled:opacity-50",
-        "focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
+        hasTrailing
+          ? // Stretched over the whole header row (the row is `relative`), so the space
+            // round `trailing` and the card's chevron still toggle; the ring and the
+            // card's hover paint on the stretched area / the row, not the text box.
+            cn(
+              "min-w-0 flex-1 after:absolute after:inset-0 after:content-['']",
+              "focus-visible:after:ring-2 focus-visible:after:ring-inset focus-visible:after:ring-[var(--brand)]",
+              card ? cn("after:rounded-lg", joined && "after:rounded-b-none") : "after:rounded-sm",
+            )
+          : "focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
         card
           ? cn(
-              "items-center justify-between rounded-lg p-4 hover:bg-[var(--bg-hover)] focus-visible:ring-inset",
-              open && "rounded-b-none",
+              "items-center justify-between rounded-lg p-4",
+              hasTrailing ? "pe-0" : "hover:bg-[var(--bg-hover)] focus-visible:ring-inset",
+              joined && "rounded-b-none",
             )
           : "items-center rounded-sm text-sm font-medium text-[var(--text-secondary)] hover:text-[var(--text-primary)]",
         headerClassName,
       )}
     >
       {!card && <Chevron open={open} leading />}
-      <span className="min-w-0">
+      {/* `flex-1`: the title takes the row, so whatever a caller puts at its end sits
+          at the header's far edge. */}
+      <span className="min-w-0 flex-1">
         <span className={cn("block", card && "text-sm font-semibold text-[var(--text-primary)]")}>{title}</span>
         {hint !== undefined && (
           <span className="mt-0.5 block text-xs font-normal text-[var(--text-muted)]">{hint}</span>
         )}
       </span>
-      {card && <Chevron open={open} />}
+      {card && !hasTrailing && <Chevron open={open} />}
     </button>
   );
 
+  // Preflight already makes h1–h6 inherit size and weight, so the heading adds
+  // structure and nothing visible.
+  const header = Heading ? <Heading className={hasTrailing ? "min-w-0 flex-1" : undefined}>{button}</Heading> : button;
+
   return (
     <div
       {...rest}
       className={cn(card && "rounded-lg border border-[var(--border)] bg-[var(--bg-surface)] shadow-sm", className)}
     >
-      {/* Preflight already makes h1–h6 inherit size and weight, so the heading adds
-          structure and nothing visible. */}
-      {Heading ? <Heading>{button}</Heading> : button}
-      <Collapse id={bodyId} open={open} keepMounted={keepMounted}>
-        <div className={cn(card ? "space-y-3 px-4 pb-4" : "space-y-2 pt-2", bodyClassName)}>{children}</div>
-      </Collapse>
+      {hasTrailing ? (
+        <div
+          className={cn(
+            "relative flex items-center gap-2",
+            card &&
+              cn(
+                "rounded-lg pe-4 has-[[data-disclosure-trigger]:enabled:hover]:bg-[var(--bg-hover)]",
+                joined && "rounded-b-none",
+              ),
+          )}
+        >
+          {header}
+          {/* Positioned, so it paints over the stretched button and takes its own
+              clicks; the chevron is not, so a click on it lands on the button. */}
+          <div className="relative flex shrink-0 items-center gap-2">{trailing}</div>
+          {card && <Chevron open={open} />}
+        </div>
+      ) : (
+        header
+      )}
+      {!triggerOnly && (
+        <Collapse id={bodyId} open={open} keepMounted={keepMounted}>
+          <div className={cn(card ? "space-y-3 px-4 pb-4" : "space-y-2 pt-2", bodyClassName)}>{children}</div>
+        </Collapse>
+      )}
     </div>
   );
 }

package/src/components/dropdown.tsx

@@ -11,6 +11,7 @@ import { useAnchoredPanel } from "../hooks/use-anchored-panel";
 import { useEscapeKey, useOutsideClick } from "../hooks/use-dismiss";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
 import { cn } from "../lib/cn";
+import { useAnchorDir } from "./use-anchor-dir";
 
 /**
  * Open state + close-on-outside-click for the custom dropdowns (MultiSelect,
@@ -225,8 +226,12 @@ export interface DropdownPanelProps extends ComponentPropsWithoutRef<"div"> {
   panelRef?: RefObject<HTMLDivElement | null>;
   /** Panel width in px, for the anchored form (the CSS `w-*` cannot be measured). */
   width?: number;
-  /** Which of the panel's edges lines up with the trigger's, room permitting. */
-  align?: "left" | "right";
+  /** Which of the panel's edges lines up with the trigger's, room permitting.
+   *  `start`/`end` follow the trigger's reading direction — `end` is the right edge
+   *  in a left-to-right form and the left one in a right-to-left form — and are what
+   *  the kit's own pickers pass; `left`/`right` stay physical. Default `end`, which
+   *  is the old `right` in a left-to-right page. */
+  align?: "left" | "right" | "start" | "end";
   children: ReactNode;
 }
 
@@ -239,7 +244,7 @@ export interface DropdownPanelProps extends ComponentPropsWithoutRef<"div"> {
  *
  * Without `anchorRef` the panel is `position: absolute` inside whatever relative box
  * the caller put it in, and the caller places it with `className` (`w-64`,
- * `right-0 top-full`). That is fine in a page that does not scroll around it, and
+ * `end-0 top-full`). That is fine in a page that does not scroll around it, and
  * wrong the moment an ancestor has `overflow` — the panel is then CLIPPED by that
  * ancestor's box, with no error and no scrollbar, just a list with its side sliced
  * off. Keksdose dev#548 is what that looks like in practice: the app's own content
@@ -266,12 +271,13 @@ export function DropdownPanel({
   anchorRef,
   panelRef,
   width = 256,
-  align = "right",
+  align = "end",
   children,
   style,
   ...rest
 }: DropdownPanelProps) {
   const anchored = useAnchoredPanel(anchorRef ?? EMPTY_REF, Boolean(anchorRef));
+  const dir = useAnchorDir(anchorRef ?? EMPTY_REF, Boolean(anchorRef));
   const body = (
     <>
       {header}
@@ -313,12 +319,18 @@ export function DropdownPanel({
   if (!rect) return null;
   // Clamped exactly as `Popover` clamps: the panel may leave the trigger's edge to
   // stay on screen, because a list half off the viewport is the bug this exists for.
-  const wanted = align === "right" ? rect.right - width : rect.left;
+  // The portal leaves the subtree the trigger's `dir` came from, so it is read off
+  // the trigger — for the alignment here, and for the panel's own `dir` below,
+  // without which a right-to-left form got a left-to-right list.
+  const physical =
+    align === "start" ? (dir === "rtl" ? "right" : "left") : align === "end" ? (dir === "rtl" ? "left" : "right") : align;
+  const wanted = physical === "right" ? rect.right - width : rect.left;
   const left = Math.min(Math.max(8, wanted), window.innerWidth - width - 8);
   return createPortal(
     <div
       {...rest}
       ref={panelRef}
+      dir={dir}
       // The caller's `style` is kept underneath, but the placement is measured rather
       // than chosen (dev#548: an `overflow` ancestor clipped a third of this panel
       // away), so those five values are the panel's own.

package/src/components/entity-combobox.tsx

@@ -7,20 +7,30 @@ import {
   ComboboxPanel,
   useComboboxCore,
   useComboboxFieldError,
+  type ComboClearValue,
   type ComboOption,
 } from "./combobox-core";
 import { DEFAULT_COMBOBOX_LABELS, DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
 
-export type { ComboOption } from "./combobox-core";
+export type { ComboClearValue, ComboOption } from "./combobox-core";
 
 /** `onChange` is the kit's — "a selection was made", carrying values — rather
  *  than the div's form event, so the DOM's spelling of it is omitted. */
-export interface EntityComboboxProps<V extends string | number>
+export interface EntityComboboxProps<V extends string | number, C extends ComboClearValue = null>
   extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
-  /** Selected id, or null/undefined when nothing is selected. */
-  value: V | null | undefined;
-  /** Selecting an option emits its value; the clear button emits `null`. */
-  onChange: (value: V | null) => void;
+  /** Selected id; `null`, `undefined` or `clearValue` when nothing is selected. */
+  value: V | C | null | undefined;
+  /** Selecting an option emits its value; the clear button emits `clearValue`. */
+  onChange: (value: V | C) => void;
+  /**
+   * What the clear button emits. Default `null`. Pass `""` for a form whose schema
+   * wants an empty string for "no choice" (a zod `z.string()` field), rather than
+   * mapping `null` in every `onChange` — the type of `onChange` follows it, so the
+   * mapping cannot be forgotten on one field and not another. The picker also reads
+   * the value back as empty, so `value=""` shows the placeholder and no "×".
+   * See {@link ComboClearValue} for why the choice is closed.
+   */
+  clearValue?: C;
   /** Already-loaded options (client-side filtered). Also used to resolve the
    *  trigger label for the current `value`. */
   options?: ComboOption<V>[];
@@ -70,9 +80,10 @@ export interface EntityComboboxProps<V extends string | number>
  * the shared field/anchor/dismiss/search primitives (no cmdk/Radix). For picking
  * several entities use {@link MultiEntityCombobox}.
  */
-export function EntityCombobox<V extends string | number>({
+export function EntityCombobox<V extends string | number, C extends ComboClearValue = null>({
   value,
   onChange,
+  clearValue = null as C,
   options,
   loadOptions,
   loading,
@@ -95,7 +106,7 @@ export function EntityCombobox<V extends string | number>({
   loadErrorLabel,
   "aria-label": ariaLabel,
   ...rest
-}: EntityComboboxProps<V>) {
+}: EntityComboboxProps<V, C>) {
   const core = useComboboxCore<V>({
     options,
     loadOptions,
@@ -120,11 +131,13 @@ export function EntityCombobox<V extends string | number>({
   // belongs to whoever renders both ends of it.
   const listboxId = useId();
 
-  const selectedOption = value == null ? null : resolve(value);
+  // The clear value is "nothing selected" too, whichever one the caller picked.
+  const chosen: V | null = value == null || value === clearValue ? null : (value as V);
+  const selectedOption = chosen == null ? null : resolve(chosen);
   const q = core.query.trim();
   const showCreate =
     Boolean(onCreate) && q.length > 0 && !results.some((o) => o.label.toLowerCase() === q.toLowerCase());
-  const showClear = Boolean(clearable && value != null && !disabled);
+  const showClear = Boolean(clearable && chosen != null && !disabled);
   /** What the closed control is showing — the second half of its accessible name. */
   const triggerText = selectedOption?.label ?? placeholder ?? "";
 
@@ -184,7 +197,7 @@ export function EntityCombobox<V extends string | number>({
         }}
         className={cn(
           FIELD_TRIGGER,
-          "pr-9",
+          "pe-9",
           label !== undefined && FIELD_FLOATING_PAD,
           disabled && "cursor-not-allowed opacity-50",
           field.isInvalid && FIELD_INVALID,
@@ -215,9 +228,9 @@ export function EntityCombobox<V extends string | number>({
             aria-label={labels.clear}
             onClick={(e) => {
               e.stopPropagation();
-              onChange(null);
+              onChange(clearValue);
             }}
-            className="absolute right-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]"
+            className="absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]"
           >
             <X className="size-4" />
           </span>