@eifi1/ui-kit 0.10.0 → 0.11.0

package/src/components/field.tsx

@@ -0,0 +1,137 @@
+/**
+ * A field group with its label ABOVE the control: label, control, hint, error.
+ *
+ * ```tsx
+ * <Field label="IBAN" required hint="22 characters" error={errors.iban}>
+ *   {(ids) => <Input {...ids} value={iban} onChange={…} />}
+ * </Field>
+ * ```
+ *
+ * The kit's `Input` and `Select` float their label inside the field, and the pickers
+ * draw theirs the same way. That is the wrong shape for a control the kit did not
+ * render, a radio group, a range slider, or a form that sets its labels above the
+ * fields throughout — which is what kastlan's wizards are, and why it kept its own
+ * `WizardField` after the kit dropped the one it had never rendered. This is that
+ * group, with the wiring the old one left to the caller: the label names the control
+ * through `htmlFor`, and the control is described by the hint and the error that are
+ * actually on screen.
+ *
+ * ## Wiring
+ *
+ * Pass a function as `children` and it receives {@link FieldControlProps} — `id`,
+ * `aria-describedby`, `aria-invalid` and `aria-required` — to spread on the control.
+ * Plain children render as they are, for a control that wires itself (a checkbox that
+ * carries its own label, a group with `aria-labelledby`); `htmlFor` then points the
+ * label at the control's own id, and the hint and error are on screen but describe
+ * nothing — the same as the `WizardField` this replaces.
+ *
+ * ## Decoupled
+ *
+ * Deliberately knows neither the wizard nor react-hook-form: `error` is a plain
+ * value. Pass `wizard.fieldErrors.iban`, a step-local error, or
+ * `fieldState.error?.message` from a `FormField` render — the markup is the same
+ * whichever of them gates the step, so a step can move between them without its
+ * fields changing. (Inside a react-hook-form form, `FormItem` + `FormLabel` from
+ * `@eifi1/ui-kit/rhf` do the same job with the ids taken from the form.)
+ *
+ * The error is NOT `role="alert"`, for the reason the kit's `error` prop gives (see
+ * `useFieldError` in components/ui.tsx): it is read when focus reaches the control.
+ */
+import { useId, type ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { Label } from "./ui";
+
+/** What a `Field` hands its render-prop children, to spread on the control. */
+export interface FieldControlProps {
+  /** The id the label's `htmlFor` points at. */
+  id: string;
+  /** The ids of the hint and the error that are rendered, or `undefined` when
+   *  neither is. */
+  "aria-describedby": string | undefined;
+  /** `true` while the field has an error, `undefined` otherwise. */
+  "aria-invalid": true | undefined;
+  /** `true` when the field is `required`. The label's star is `aria-hidden`; this
+   *  is what a screen reader hears instead. */
+  "aria-required": true | undefined;
+}
+
+export interface FieldProps {
+  /** The label above the control. Omit it for a group whose control is labelled
+   *  some other way; the hint and error still render. */
+  label?: ReactNode;
+  /** Draws the kit's required mark after the label, and sets `aria-required` on the
+   *  render-prop control. */
+  required?: boolean;
+  /** Muted helper text below the control. */
+  hint?: ReactNode;
+  /** The error below the control. `null`, `false` and `""` are no error — what a
+   *  `touched && errors.x` evaluates to on the happy path. */
+  error?: ReactNode;
+  /** The control's id. Defaults to a generated one; set it when the control carries
+   *  its own id (plain children). */
+  htmlFor?: string;
+  /** Dims the label with its control. */
+  disabled?: boolean;
+  /** The label's size: `sm` for a dense row, `md` otherwise. */
+  labelSize?: "sm" | "md";
+  /** Wrapper className. */
+  className?: string;
+  /** The control. A function receives {@link FieldControlProps} to spread on it. */
+  children: ReactNode | ((control: FieldControlProps) => ReactNode);
+}
+
+const isShown = (node: ReactNode) =>
+  node !== undefined && node !== null && node !== false && node !== "";
+
+export function Field({
+  label,
+  required,
+  hint,
+  error,
+  htmlFor,
+  disabled,
+  labelSize,
+  className,
+  children,
+}: FieldProps) {
+  const generated = useId();
+  const id = htmlFor ?? `${generated}-control`;
+  const hintId = `${generated}-hint`;
+  const errorId = `${generated}-error`;
+  const hasHint = isShown(hint);
+  const hasError = isShown(error);
+  const describedBy = [hasHint && hintId, hasError && errorId].filter(Boolean).join(" ");
+  const control: FieldControlProps = {
+    id,
+    "aria-describedby": describedBy || undefined,
+    "aria-invalid": hasError || undefined,
+    "aria-required": required || undefined,
+  };
+  return (
+    <div data-slot="field" className={cn("grid gap-1.5", className)}>
+      {label !== undefined && (
+        <Label
+          htmlFor={id}
+          required={required}
+          disabled={disabled}
+          size={labelSize}
+          data-error={hasError || undefined}
+          className="data-[error=true]:text-[var(--danger)]"
+        >
+          {label}
+        </Label>
+      )}
+      {typeof children === "function" ? children(control) : children}
+      {hasHint && (
+        <p id={hintId} className="text-[11px] leading-tight text-[var(--text-muted)]">
+          {hint}
+        </p>
+      )}
+      {hasError && (
+        <p id={errorId} className="text-[11px] leading-tight text-[var(--danger)]">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/components/floating-panel.tsx

@@ -1,18 +1,38 @@
 import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
-import type { ButtonHTMLAttributes, CSSProperties, KeyboardEvent, ReactNode, Ref } from "react";
+import type {
+  AnchorHTMLAttributes,
+  ButtonHTMLAttributes,
+  CSSProperties,
+  HTMLAttributes,
+  KeyboardEvent,
+  MouseEvent,
+  ReactElement,
+  ReactNode,
+  Ref,
+} from "react";
 import { X } from "lucide-react";
 
 import { cn } from "../lib/cn";
 import { dirOf, type Direction } from "../lib/direction";
 import { useKitLabels } from "../i18n/kit-labels";
+import { Tooltip, type TooltipSide } from "./tooltip";
 
 export interface FloatingPanelLabels {
   /** Accessible name of the panel header's X. */
   close: string;
+  /**
+   * What a {@link FloatingAction}'s count badge adds to its accessible name ("3 new"),
+   * read after the label: "Invoices, 3 new". The dot itself is hidden from a reader —
+   * a bare "3" read out of context says nothing about what is counted.
+   */
+  badge: (count: number) => string;
 }
 
-export const DEFAULT_FLOATING_PANEL_LABELS: FloatingPanelLabels = { close: "Close" };
+export const DEFAULT_FLOATING_PANEL_LABELS: FloatingPanelLabels = {
+  close: "Close",
+  badge: (count) => `${count} new`,
+};
 
 /** A LOGICAL corner: `bottom-end` is bottom-right in LTR and bottom-left in RTL. */
 export type FloatingCorner = "bottom-end" | "bottom-start";
@@ -89,6 +109,49 @@ export interface FloatingActionButtonProps extends Omit<ButtonHTMLAttributes<HTM
    * in both states; `aria-pressed` already says which one it is in.
    */
   pressed?: boolean;
+  /**
+   * Show `label` beside the icon: the EXTENDED FAB, a pill rather than a disc. For a
+   * corner control whose words are the point — kastlan's offline indicator
+   * (shared/offline/offline-indicator.tsx:39) is a pill saying "Offline — 2 photo(s)
+   * queued" / "Syncing…", hand-placed at `fixed bottom-4 left-4`, i.e. over the
+   * bottom nav and on the wrong side in RTL. Same height as the disc (3rem), so a
+   * {@link FloatingPanel} card above it still clears it.
+   */
+  extended?: boolean;
+  /**
+   * Announce `label` whenever it changes, through a polite `role="status"` region — for
+   * an extended FAB that REPORTS something (kastlan's offline/sync state), where a
+   * sighted user sees the words change and a screen reader user otherwise hears
+   * nothing until they happen to land on the button.
+   *
+   * ⚠️ A live region announces changes, not its own arrival: a FAB that mounts already
+   * saying "Offline" says it to nobody. Keep it mounted and pass `hidden` while there
+   * is nothing to report (kastlan returns `null` when online and idle); the region
+   * stays in the page, and the first real status is heard.
+   */
+  live?: boolean;
+  /**
+   * `primary` (default): the solid brand disc of a page's main action. `surface`: the
+   * page's surface with a hairline border — for a FAB that is a status rather than a
+   * call to action, as kastlan's offline pill is (a brand pill would shout "press me"
+   * at a user who is merely offline). Ignored while `pressed` is set; a toggle has its
+   * own two looks.
+   */
+  variant?: "primary" | "surface";
+  /**
+   * Hover and focus label in the kit {@link Tooltip}, instead of the native `title` —
+   * keksdose has ONE tooltip (dev#523) and wrapped its assistant launcher by hand,
+   * which cannot work: the tooltip's anchor is a `relative inline-flex` span, and this
+   * button is `fixed` and portalled. With `tooltip` the FAB positions a fixed wrapper
+   * instead and the button sits in the tooltip inside it. `true` shows the `label`;
+   * any other content shows that. Implies no native `title` (whatever `nativeTitle`
+   * says): one hover hint, not two. `style` stays on the button; the corner and
+   * `offset` move to the wrapper.
+   */
+  tooltip?: ReactNode;
+  /** Where the {@link tooltip} opens. Default `top`; the bubble is portalled and kept on
+   *  screen, so a corner button's label is not pushed off the edge. */
+  tooltipSide?: TooltipSide;
   ref?: Ref<HTMLButtonElement>;
 }
 
@@ -116,6 +179,11 @@ export function FloatingActionButton({
   offset = "1rem",
   nativeTitle = true,
   pressed,
+  extended = false,
+  live = false,
+  variant = "primary",
+  tooltip,
+  tooltipSide = "top",
   className,
   style,
   type = "button",
@@ -124,13 +192,12 @@ export function FloatingActionButton({
 }: FloatingActionButtonProps) {
   const [marker, dir] = usePortalDir();
   const toggle = pressed !== undefined;
-  // An empty title is "no tooltip", not an attribute with nothing in it.
-  const nativeTip = nativeTitle && title !== "" ? (title ?? label) : undefined;
-  return (
-    <>
-      <span ref={marker} hidden />
-      {typeof document !== "undefined" &&
-        createPortal(
+  const tip = tooltip === true ? label : tooltip === false || tooltip === "" ? undefined : tooltip;
+  const wrapped = tip !== undefined && tip !== null;
+  // An empty title is "no tooltip", not an attribute with nothing in it. The kit
+  // tooltip replaces it outright.
+  const nativeTip = !wrapped && nativeTitle && title !== "" ? (title ?? label) : undefined;
+  const button = (
           <button
             {...rest}
             type={type}
@@ -138,11 +205,19 @@ export function FloatingActionButton({
             aria-label={label}
             aria-pressed={pressed ?? rest["aria-pressed"]}
             title={nativeTip}
-            style={{ ...cornerStyle(corner, offset), ...style }}
+            style={wrapped ? style : { ...cornerStyle(corner, offset), ...style }}
             className={cn(
-              "fixed z-40 inline-flex size-12 items-center justify-center rounded-full",
-              "shadow-lg transition-colors",
-              !toggle && "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]",
+              // Wrapped, the wrapper is the fixed thing and the button sits in it.
+              !wrapped && "fixed z-40",
+              "inline-flex items-center justify-center rounded-full",
+              extended ? "h-12 gap-2 px-4 text-sm font-medium [&_svg]:size-5" : "size-12 [&_svg]:size-6",
+              "shadow-lg transition-colors disabled:cursor-default",
+              !toggle &&
+                variant === "primary" &&
+                "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]",
+              !toggle &&
+                variant === "surface" &&
+                "border border-[var(--border)] bg-[var(--bg-surface)] text-[var(--text-primary)] hover:bg-[var(--bg-hover)] disabled:hover:bg-[var(--bg-surface)]",
               // A toggle sits on the page's surface — a solid brand disc would read as
               // "on" in both states — and says "on" in the brand family.
               toggle && "border border-[var(--border)]",
@@ -151,12 +226,48 @@ export function FloatingActionButton({
               pressed === true &&
                 "border-[var(--brand)] bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)]",
               "outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] focus-visible:ring-offset-2",
-              "[&_svg]:size-6",
               className,
             )}
           >
             {icon}
-          </button>,
+            {/* Visible words, not the name: `aria-label` already is the name, and the
+                span would only repeat it. */}
+            {extended && (
+              <span aria-hidden className="whitespace-nowrap">
+                {label}
+              </span>
+            )}
+          </button>
+  );
+  return (
+    <>
+      <span ref={marker} hidden />
+      {typeof document !== "undefined" &&
+        createPortal(
+          <>
+            {wrapped ? (
+              <div
+                dir={dir}
+                hidden={rest.hidden}
+                style={cornerStyle(corner, offset)}
+                className="fixed z-40 inline-flex"
+              >
+                <Tooltip label={tip} side={tooltipSide} portal>
+                  {/* A fragment when the bubble says the name again, so the tooltip
+                      does not describe the button with its own label — a reader would
+                      hear it twice. Other text is a real description. */}
+                  {tip === label ? <>{button}</> : button}
+                </Tooltip>
+              </div>
+            ) : (
+              button
+            )}
+            {live && (
+              <span role="status" className="sr-only">
+                {label}
+              </span>
+            )}
+          </>,
           document.body,
         )}
     </>
@@ -183,6 +294,10 @@ export interface FloatingPanelProps {
   /** The FAB's native `title` — see {@link FloatingActionButtonProps.nativeTitle}.
    *  `false` for keksdose's assistant launcher, under its one-tooltip rule (dev#523). */
   fabNativeTitle?: boolean;
+  /** The FAB's kit tooltip — see {@link FloatingActionButtonProps.tooltip}. `true` for
+   *  keksdose's assistant launcher, which wanted the kit bubble and had no way to
+   *  put one on a fixed, portalled button (dev#523). */
+  fabTooltip?: ReactNode;
   /** Default: `floatingPanel.close` from the {@link UiKitProvider}, else "Close". */
   closeLabel?: string;
   /**
@@ -239,6 +354,7 @@ export function FloatingPanel({
   corner = "bottom-end",
   offset = "1rem",
   fabNativeTitle,
+  fabTooltip,
   closeLabel,
   initialFocus,
   className,
@@ -308,6 +424,7 @@ export function FloatingPanel({
         corner={corner}
         offset={offset}
         nativeTitle={fabNativeTitle}
+        tooltip={fabTooltip}
         aria-expanded={open}
         aria-controls={open ? panelId : undefined}
         onClick={() => {
@@ -383,3 +500,237 @@ export function FloatingPanel({
     </>
   );
 }
+
+export interface FloatingActionGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, "role"> {
+  /** Name the group ("Register actions"); a reader then introduces the members as one
+   *  set. A group with no name is one more unlabelled wrapper. */
+  "aria-label"?: string;
+  /** Default `bottom-end`. */
+  corner?: FloatingCorner;
+  /** Distance above the nav / home indicator — see {@link FloatingActionButtonProps.offset}. */
+  offset?: string;
+  /** {@link FloatingAction}s, in reading order. */
+  children: ReactNode;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * A floating pill of {@link FloatingAction}s — one to four `size-12` toggles, actions
+ * or links with hairline dividers — pinned to a corner exactly as the
+ * {@link FloatingActionButton} is: `--app-nav-h` and the home indicator cleared, a
+ * logical corner, portalled.
+ *
+ * keksdose built it twice by hand: the /transactions phone toolbar
+ * (transactions-page.tsx:644 — upcoming and pending toggles, an invoices link with a
+ * pending count, and the brand "+") and the feedback page's "awaiting only" toggle
+ * (feedback-page.tsx:854, one button in the group anyway, so the two pages look
+ * alike). Both at `right-4 bottom-20` — `right`, not `end`, so over the page's leading
+ * edge in RTL — with `divide-x`, slate hovers, and each member's `Tooltip` spelled out.
+ *
+ * `role="group"`, NOT a toolbar: every member keeps its own tab stop, as the
+ * hand-built ones did, and there is no arrow-key roving to learn. Hide it where it
+ * does not belong with a class (`md:hidden`, as both keksdose pages do).
+ */
+export function FloatingActionGroup({
+  corner = "bottom-end",
+  offset = "1rem",
+  className,
+  style,
+  children,
+  ...rest
+}: FloatingActionGroupProps) {
+  const [marker, dir] = usePortalDir();
+  return (
+    <>
+      <span ref={marker} hidden />
+      {typeof document !== "undefined" &&
+        createPortal(
+          <div
+            {...rest}
+            role="group"
+            dir={dir}
+            data-corner={corner}
+            style={{ ...cornerStyle(corner, offset), ...style }}
+            className={cn(
+              "fixed z-40 inline-flex flex-row overflow-hidden rounded-2xl",
+              "border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg",
+              // Dividers on the logical start edge of every member but the first, so
+              // they sit between the same two members in RTL. The member is the
+              // tooltip's wrapper span, which is the direct child.
+              "[&>*:not(:first-child)]:border-s [&>*]:border-[var(--border)]",
+              className,
+            )}
+          >
+            {children}
+          </div>,
+          document.body,
+        )}
+    </>
+  );
+}
+
+/** What {@link FloatingActionProps.renderLink} is handed. Spread it onto your router's
+ *  link, mapping `href` — `renderLink={({ href, ...p }) => <Link to={href} {...p} />}`. */
+export interface FloatingActionLinkProps {
+  href: string;
+  /** The member's whole look — keep it. */
+  className: string;
+  children: ReactNode;
+  "aria-label": string;
+  onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+  [key: `aria-${string}`]: string | boolean | number | undefined;
+  [key: `data-${string}`]: unknown;
+}
+
+export interface FloatingActionProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "onClick"> {
+  /** The accessible name, and the tooltip's text. Keep it the same in both states of a
+   *  toggle; `aria-pressed` says which one it is in. */
+  label: string;
+  icon: ReactNode;
+  /** Make it a toggle: `aria-pressed` and the brand "on" look (the brand glyph on the
+   *  quiet brand fill), as {@link FloatingActionButtonProps.pressed}. Ignored on a link. */
+  pressed?: boolean;
+  /**
+   * `primary`: the brand-filled member, for the group's main action (the /transactions
+   * "+"). Default: the quiet one.
+   */
+  variant?: "default" | "primary";
+  /**
+   * A count in a dot at the member's top end corner — the /transactions invoices link's
+   * pending count. Nothing is drawn for `0` or less; above 99 it reads `99+`. The count
+   * joins the accessible name through `floatingPanel.badge` ("Invoices, 3 new"), or
+   * `badgeLabel` when passed.
+   */
+  badge?: number;
+  /** The badge's words for a reader, replacing `floatingPanel.badge` — "3 to review". */
+  badgeLabel?: string;
+  /** The dot's colour. Default `warning`, the pending count's. */
+  badgeTone?: "warning" | "danger" | "brand";
+  /** Show `label` in the kit {@link Tooltip} on hover and focus. Default `true`: the
+   *  members are icon-only and this is their only visible label. */
+  tooltip?: boolean;
+  /** Where the tooltip opens. Default `top` — the group sits at the bottom of the screen. */
+  tooltipSide?: TooltipSide;
+  /** Make it a link — the /transactions invoices member. A plain `<a>` unless
+   *  `renderLink` hands it to your router. */
+  href?: string;
+  /** Render the link through your router's `Link` — see {@link FloatingActionLinkProps}. */
+  renderLink?: (props: FloatingActionLinkProps) => ReactElement;
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  ref?: Ref<HTMLButtonElement>;
+}
+
+const BADGE_TONE: Record<NonNullable<FloatingActionProps["badgeTone"]>, string> = {
+  warning: "bg-[var(--warning)] text-[var(--text-inverse)]",
+  danger: "bg-[var(--danger)] text-[var(--danger-contrast)]",
+  brand: "bg-[var(--brand)] text-[var(--brand-contrast)]",
+};
+
+/**
+ * One member of a {@link FloatingActionGroup}: a `size-12` icon button, toggle or link
+ * with its label in a styled tooltip — what each keksdose member wrapped by hand in
+ * `<Tooltip portal>`. The tooltip is portalled because the group clips (`overflow-hidden`
+ * keeps the brand member's fill inside the pill's corners), and the focus ring is inset
+ * for the same reason.
+ */
+export function FloatingAction({
+  label,
+  icon,
+  pressed,
+  variant = "default",
+  badge,
+  badgeLabel,
+  badgeTone = "warning",
+  tooltip = true,
+  tooltipSide = "top",
+  href,
+  renderLink,
+  className,
+  type = "button",
+  onClick,
+  ref,
+  ...rest
+}: FloatingActionProps) {
+  const labels = useKitLabels("floatingPanel", DEFAULT_FLOATING_PANEL_LABELS);
+  const counted = badge !== undefined && badge > 0;
+  const name = counted ? `${label}, ${badgeLabel ?? labels.badge(badge)}` : label;
+  const isLink = href !== undefined;
+  const look = cn(
+    "relative flex size-12 items-center justify-center transition-colors",
+    "outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--brand)]",
+    "disabled:cursor-not-allowed disabled:opacity-50 [&_svg]:size-5",
+    variant === "primary"
+      ? "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]"
+      : pressed && !isLink
+        ? "bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)]"
+        : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-primary)]",
+    className,
+  );
+  const body = (
+    <>
+      {icon}
+      {counted && (
+        <span
+          aria-hidden
+          data-badge=""
+          className={cn(
+            "pointer-events-none absolute end-1 top-1 h-4 min-w-4 rounded-full px-1 text-center text-[10px] leading-4 font-semibold",
+            BADGE_TONE[badgeTone],
+          )}
+        >
+          {badge > 99 ? "99+" : badge}
+        </span>
+      )}
+    </>
+  );
+
+  let member: ReactElement;
+  if (isLink) {
+    // The button-only attributes stay behind; `aria-*`, `data-*` and the like ride along.
+    const { disabled: _disabled, form: _form, value: _value, name: _name, ...anchorRest } = rest;
+    const linkProps: FloatingActionLinkProps = {
+      ...(anchorRest as AnchorHTMLAttributes<HTMLAnchorElement>),
+      href,
+      "aria-label": name,
+      onClick,
+      className: look,
+      children: body,
+    };
+    const { children: content, ...anchor } = linkProps;
+    member = renderLink ? (
+      <RenderedFloatingLink render={renderLink} {...linkProps} />
+    ) : (
+      <a {...anchor}>{content}</a>
+    );
+  } else {
+    member = (
+      <button
+        {...rest}
+        ref={ref}
+        type={type}
+        aria-label={name}
+        aria-pressed={pressed ?? rest["aria-pressed"]}
+        onClick={onClick}
+        className={look}
+      >
+        {body}
+      </button>
+    );
+  }
+  if (!tooltip) return member;
+  return (
+    // A fragment: the bubble says the member's name, and a description that repeats
+    // the name is read twice.
+    <Tooltip label={label} side={tooltipSide} portal>
+      <>{member}</>
+    </Tooltip>
+  );
+}
+
+/** Calls `renderLink` as a component, so its hooks belong to the link, not to us. */
+function RenderedFloatingLink({
+  render,
+  ...props
+}: FloatingActionLinkProps & { render: (props: FloatingActionLinkProps) => ReactElement }) {
+  return render(props);
+}

package/src/components/list.tsx

@@ -1,5 +1,5 @@
 import { createContext, forwardRef, useContext } from "react";
-import type { ComponentPropsWithoutRef, MouseEvent, ReactElement, ReactNode, Ref } from "react";
+import type { ComponentPropsWithoutRef, HTMLAttributes, MouseEvent, ReactElement, ReactNode, Ref } from "react";
 import { ExternalLink } from "lucide-react";
 import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
@@ -165,6 +165,19 @@ interface ListItemBaseProps {
   className?: string;
   /** Classes on the main target (the button, link or static block). */
   targetClassName?: string;
+  /**
+   * Extra attributes and handlers for the main target — e.g. HTML5 drag-and-drop
+   * (`draggable`, `onDragStart`, `onDragEnd`): lenkbank's segment list drags the WHOLE
+   * 44px row, and a grip inside the button cannot start a drag in Firefox. Spread first,
+   * so the row's own role, name, state and click handling always win.
+   */
+  targetProps?: HTMLAttributes<HTMLElement>;
+  /**
+   * A visible border while unselected, instead of the transparent one. For rows laid out
+   * as a wrapping strip (lenkbank's profile bar), where borderless rows read as loose
+   * text. The selected row's brand border is unchanged.
+   */
+  bordered?: boolean;
   /** `div` for a single row outside a {@link List}; an `<li>` must sit in a list. */
   as?: "li" | "div";
   /** Reaches the main target — the element with the row's name and action. */
@@ -250,6 +263,8 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
     align = "center",
     className,
     targetClassName,
+    targetProps,
+    bordered = false,
     as = "li",
     href,
     renderLink,
@@ -328,9 +343,14 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
     targetClassName,
   );
 
+  // `role` is the row's own (a button, a link, or nothing on a static block): a
+  // targetProps role would silently turn the row into something else.
+  const { role: _ignoredRole, ...targetExtras } = targetProps ?? {};
+
   let main: ReactNode;
   if (isLink) {
     const linkProps: ListItemLinkProps = {
+      ...(targetExtras as Partial<ListItemLinkProps>),
       ...rest,
       ref: ref as Ref<HTMLAnchorElement>,
       href,
@@ -354,6 +374,7 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
   } else if (isButton) {
     main = (
       <button
+        {...(targetExtras as HTMLAttributes<HTMLButtonElement>)}
         {...rest}
         ref={ref as Ref<HTMLButtonElement>}
         type="button"
@@ -372,6 +393,7 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
   } else {
     main = (
       <div
+        {...(targetExtras as HTMLAttributes<HTMLDivElement>)}
         {...rest}
         ref={ref as Ref<HTMLDivElement>}
         aria-disabled={disabled || undefined}
@@ -394,7 +416,11 @@ export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem
       <div
         className={cn(
           "flex min-w-0 items-center rounded-md border transition-colors",
-          selected ? "border-[var(--brand)] bg-[var(--bg-surface-2)]" : "border-transparent",
+          selected
+            ? "border-[var(--brand)] bg-[var(--bg-surface-2)]"
+            : bordered
+              ? "border-[var(--border)]"
+              : "border-transparent",
           interactive && !inert && !selected && "hover:bg-[var(--bg-hover)]",
           disabled && "opacity-50",
           className,