@eifi1/ui-kit 0.15.4 → 0.16.0

package/src/components/ui.tsx

@@ -1,4 +1,4 @@
-import { forwardRef, useId, useLayoutEffect, useRef, useState } from "react";
+import { createContext, forwardRef, useContext, useId, useLayoutEffect, useRef, useState } from "react";
 import { ChevronDown, Eye, EyeOff, HelpCircle, Plus, X } from "lucide-react";
 import type { AnchorHTMLAttributes, ButtonHTMLAttributes, ComponentPropsWithoutRef, CSSProperties, InputHTMLAttributes, KeyboardEvent, MouseEvent, ReactElement, ReactNode, Ref, SelectHTMLAttributes, TextareaHTMLAttributes } from "react";
 import { cn } from "../lib/cn";
@@ -46,7 +46,7 @@ const buttonVariantClasses: Record<ButtonVariant, string> = {
   ghost:
     "bg-transparent text-[var(--text-primary)] hover:bg-[var(--bg-surface-2)] focus:ring-[var(--brand)]",
   danger:
-    "bg-[var(--danger)] text-[var(--danger-contrast)] hover:bg-[var(--danger-hover)] focus:ring-[var(--danger-border)]",
+    "bg-[var(--danger)] text-[var(--danger-contrast)] hover:bg-[var(--danger-hover)] focus:ring-[var(--danger-border-strong)]",
   brand:
     "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)] focus:ring-[var(--brand)]",
   // A text link that is still a `<button>` — keksdose's six hand-rolled
@@ -92,7 +92,7 @@ const BUTTON_TONES: Record<Exclude<ButtonTone, "default">, string> = {
   muted:
     "text-[var(--text-secondary)] hover:text-[var(--text-primary)] disabled:hover:text-[var(--text-secondary)]",
   danger:
-    "text-[var(--text-secondary)] hover:text-[var(--danger)] focus:ring-[var(--danger-border)] disabled:hover:text-[var(--text-secondary)]",
+    "text-[var(--text-secondary)] hover:text-[var(--danger)] focus:ring-[var(--danger-border-strong)] disabled:hover:text-[var(--text-secondary)]",
 };
 
 /** Only the two transparent variants take every tone; see {@link ButtonTone}. */
@@ -103,9 +103,9 @@ const TONED_VARIANTS = new Set<ButtonVariant>(["link", "ghost"]);
 // the neutral ones survives the merge.
 const BUTTON_BOXED_DANGER: Partial<Record<ButtonVariant, string>> = {
   secondary:
-    "border-[var(--danger-border)] bg-transparent text-[var(--danger)] hover:bg-[var(--danger-bg)] focus:ring-[var(--danger-border)]",
+    "border-[var(--danger-border)] bg-transparent text-[var(--danger)] hover:bg-[var(--danger-bg)] focus:ring-[var(--danger-border-strong)]",
   primary:
-    "border-[var(--danger-border)] bg-[var(--danger-bg)] text-[var(--danger)] hover:border-[var(--danger)] hover:bg-[var(--danger)] hover:text-[var(--danger-contrast)] focus:ring-[var(--danger-border)] disabled:hover:border-[var(--danger-border)] disabled:hover:bg-[var(--danger-bg)] disabled:hover:text-[var(--danger)]",
+    "border-[var(--danger-border)] bg-[var(--danger-bg)] text-[var(--danger)] hover:border-[var(--danger)] hover:bg-[var(--danger)] hover:text-[var(--danger-contrast)] focus:ring-[var(--danger-border-strong)] disabled:hover:border-[var(--danger-border)] disabled:hover:bg-[var(--danger-bg)] disabled:hover:text-[var(--danger)]",
 };
 
 // `pressed` on a `link`: the brand colour and a heavier weight, which is exactly what
@@ -543,8 +543,8 @@ type ColouredTone = "danger" | "warning" | "info" | "success" | "custom";
 const ICON_BUTTON_TONES: Record<ColouredTone, { quiet: string; toned: string }> = {
   danger: {
     quiet:
-      "text-[var(--text-placeholder)] hover:bg-[var(--danger-bg)] hover:text-[var(--danger)] focus:ring-[var(--danger-border)]",
-    toned: "text-[var(--danger)] hover:bg-[var(--danger-bg)] focus:ring-[var(--danger-border)]",
+      "text-[var(--text-placeholder)] hover:bg-[var(--danger-bg)] hover:text-[var(--danger)] focus:ring-[var(--danger-border-strong)]",
+    toned: "text-[var(--danger)] hover:bg-[var(--danger-bg)] focus:ring-[var(--danger-border-strong)]",
   },
   warning: {
     quiet:
@@ -657,6 +657,26 @@ const ICON_BUTTON_GLYPH_SIZES: Record<IconButtonGlyphSize, string> = {
   28: "[&_svg]:size-7",
 };
 
+// `pending`'s spinner, the size of the glyph it replaces (the `[&_svg]` rules above
+// size only an svg, and the spinner is a bordered span).
+const ICON_BUTTON_SPINNER: Record<IconButtonSize, string> = {
+  "2xl": "size-7",
+  xl: "size-6",
+  lg: "size-5",
+  md: "size-5",
+  sm: "size-5",
+  xs: "size-4",
+  "2xs": "size-3.5",
+};
+const ICON_BUTTON_SPINNER_GLYPH: Record<IconButtonGlyphSize, string> = {
+  12: "size-3",
+  14: "size-3.5",
+  16: "size-4",
+  20: "size-5",
+  24: "size-6",
+  28: "size-7",
+};
+
 export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   /** Any {@link ButtonVariant}; `overlay` — a round translucent disc for use over
    *  an image (see `ICON_BUTTON_OVERLAY`); or `shutter` — a camera's release, a ringed
@@ -804,6 +824,36 @@ export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>
   tooltipSide?: TooltipSide;
   /** Passed to the `label` tooltip's `portal`. Left out, Tooltip decides (see there). */
   tooltipPortal?: boolean;
+  /**
+   * Mount the `label` bubble only while it is up — {@link Tooltip}'s `lazy`. Default
+   * `true` since 0.16.0; `false` is the always-mounted in-place bubble of before.
+   *
+   * Why the label bubble can be lazy when Tooltip's default is not: this bubble
+   * describes nothing. It is wrapped round the button in a fragment precisely so that
+   * it is NOT the button's `aria-describedby` (it would repeat the button's own name),
+   * so there is no description for a lazy mount to take away — the name is the
+   * `aria-label` either way, read in browse mode and on focus alike. What the
+   * always-mounted bubble did do was sit in the DOM as a `role="tooltip"` node full of
+   * text: every IconButton in a row added one to `getAllByRole("tooltip")` and its label
+   * to the row's `textContent`, and two keksdose tests tripped over that (0.15.5 P6).
+   * The cost is the one {@link Tooltip}'s "Lazy in place" note names — a test that
+   * looked the bubble up without hovering now has to hover (or focus) first; pass
+   * `false` while it is migrated. A `disabledReason` bubble is unaffected: that one
+   * stays mounted as it was.
+   */
+  tooltipLazy?: boolean;
+  /**
+   * Busy — the action is in flight: the glyph is swapped for a spinner of the same
+   * size, the button is `aria-busy`, and clicks (and the Enter/Space and form
+   * submission they stand for) are swallowed, so a second press cannot start the
+   * action twice. {@link Button}'s `pending`, with the same contract: `aria-disabled`
+   * rather than `disabled`, so the button that was pressed keeps its focus. The name
+   * (`label` / `aria-label`) stays — `aria-busy` is what says it is working. A SWAP
+   * rather than Button's overlay: the box is square and fixed, so there is no width
+   * for the glyph to hold, and a spinner drawn over a glyph would be two marks in one
+   * 20px square.
+   */
+  pending?: boolean;
   /**
    * Why the action is not available — {@link Button}'s `disabledReason`, on the icon
    * button: keksdose's accounts page cannot hide an account with a balance or delete
@@ -869,6 +919,7 @@ export interface IconButtonLinkProps
       | "tooltip"
       | "tooltipSide"
       | "tooltipPortal"
+      | "tooltipLazy"
     > {
   href: string;
   /** See {@link ButtonLinkProps.renderLink}. */
@@ -887,6 +938,7 @@ export interface IconButtonLinkProps
   pressed?: never;
   disabledReason?: never;
   disabledStyle?: never;
+  pending?: never;
 }
 
 /**
@@ -998,6 +1050,7 @@ function IconButtonLink({
   tooltip = true,
   tooltipSide,
   tooltipPortal,
+  tooltipLazy = true,
   glyphSize,
   badge,
   className,
@@ -1083,7 +1136,13 @@ function IconButtonLink({
   if (!tooltip || label === undefined || label === "") return control;
   return (
     // A fragment, as on the button: the bubble says what `aria-label` already does.
-    <Tooltip label={label} side={tooltipSide} portal={tooltipPortal} className={stretch ? "self-stretch" : undefined}>
+    <Tooltip
+      label={label}
+      side={tooltipSide}
+      portal={tooltipPortal}
+      lazy={tooltipLazy}
+      className={stretch ? "self-stretch" : undefined}
+    >
       <>{control}</>
     </Tooltip>
   );
@@ -1104,7 +1163,9 @@ function IconButtonElement(
     tooltip = true,
     tooltipSide,
     tooltipPortal,
+    tooltipLazy = true,
     disabledReason,
+    pending,
     glyphSize,
     badge,
     disabledStyle = "dim",
@@ -1112,6 +1173,7 @@ function IconButtonElement(
     style,
     onClick,
     onKeyDown,
+    children,
     href: _href,
     renderLink: _renderLink,
     external: _external,
@@ -1125,21 +1187,25 @@ function IconButtonElement(
   const keep = disabledStyle === "keep";
   const reasonId = useId();
   const locked = hasContent(disabledReason);
+  // Pending is inert like a locked button — focusable, every activation swallowed —
+  // without the locked look: the spinner is the state.
+  const inert = locked || Boolean(pending);
   const ownDescribedBy = rest["aria-describedby"];
   const button = (
     <button
       ref={ref}
       {...rest}
-      disabled={locked ? undefined : rest.disabled}
-      aria-disabled={locked || rest["aria-disabled"]}
+      disabled={inert ? undefined : rest.disabled}
+      aria-disabled={inert || rest["aria-disabled"]}
+      aria-busy={pending || rest["aria-busy"]}
       aria-describedby={locked ? (ownDescribedBy ? `${ownDescribedBy} ${reasonId}` : reasonId) : ownDescribedBy}
       aria-label={rest["aria-label"] ?? label}
       aria-pressed={pressed ?? rest["aria-pressed"]}
       style={toneColorStyle(toneColor, style)}
       onClick={(e) => {
         if (stopPropagation) e.stopPropagation();
-        // `preventDefault` too: a locked submit must not submit its form.
-        if (locked) {
+        // `preventDefault` too: a locked (or pending) submit must not submit its form.
+        if (inert) {
           e.preventDefault();
           return;
         }
@@ -1157,9 +1223,24 @@ function IconButtonElement(
         // The disabled look for the focusable kind of disabled, as on Button.
         locked && (keep ? "cursor-default" : "cursor-not-allowed opacity-50"),
         keep && "disabled:cursor-default disabled:opacity-100",
+        pending && "cursor-progress",
         className,
       )}
-    />
+    >
+      {pending ? (
+        // Decorative, as on Button: `aria-busy` says it. Sized to the glyph it stands
+        // in for, in the glyph's colour, so the swap does not change the button's look.
+        <Spinner
+          label={null}
+          className={cn(
+            "border-current/30 border-t-current",
+            glyphSize !== undefined ? ICON_BUTTON_SPINNER_GLYPH[glyphSize] : ICON_BUTTON_SPINNER[size],
+          )}
+        />
+      ) : (
+        children
+      )}
+    </button>
   );
   const control = withIconButtonBadge(button, badge, stretch);
   if (locked) {
@@ -1184,8 +1265,14 @@ function IconButtonElement(
   if (!tooltip || label === undefined || label === "") return control;
   return (
     // A fragment, so Tooltip leaves the button's description alone: the bubble says
-    // exactly what `aria-label` already does.
-    <Tooltip label={label} side={tooltipSide} portal={tooltipPortal} className={stretch ? "self-stretch" : undefined}>
+    // exactly what `aria-label` already does. Lazy by default — see `tooltipLazy`.
+    <Tooltip
+      label={label}
+      side={tooltipSide}
+      portal={tooltipPortal}
+      lazy={tooltipLazy}
+      className={stretch ? "self-stretch" : undefined}
+    >
       <>{control}</>
     </Tooltip>
   );
@@ -1250,7 +1337,7 @@ export const FIELD_FLOATING_PAD = "pt-4 pb-1";
 // stays exactly the size of a valid one and nothing beside it moves when the value
 // arrives.
 export const FIELD_INVALID =
-  "border-[var(--danger-border)] ring-1 ring-[var(--danger-border)] focus:border-[var(--danger)] focus:ring-[var(--danger)]";
+  "border-[var(--danger-border-strong)] ring-1 ring-[var(--danger-border-strong)] focus:border-[var(--danger)] focus:ring-[var(--danger)]";
 
 export const FLOATING_INPUT_CLASS = cn(FIELD_BASE, FIELD_FLOATING_PAD, "peer placeholder:text-transparent");
 
@@ -1887,7 +1974,9 @@ export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement
    *  TEXT (a string or a number) is a caption instead, and goes UNDER the field
    *  like every other field's hint, attached through `aria-describedby`: the label
    *  line is 11px of strip shared with the label, and a sentence placed there was
-   *  set in the value's type on top of both the label and the value. */
+   *  set in the value's type on top of both the label and the value. On an
+   *  UNLABELLED Select (no label line) a FieldHint sits at the field's end edge,
+   *  outside the box. */
   hint?: ReactNode;
   /**
    * `"sm"`: a 28px, 12px-type select for a toolbar or a table header, where the
@@ -1973,38 +2062,59 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select
   // whole rows, at any width.
   const dress = listBox ? "overflow-y-auto [&_option]:py-1" : "appearance-none pe-9";
   if (label === undefined) {
+    const select = (
+      <select
+        ref={ref}
+        // `id` is destructured out of the props to feed `fieldId`, and this branch
+        // never put it back — so an UNLABELLED Select swallowed it and the
+        // consumer's own `<label for="…">` pointed at nothing. The control stayed
+        // in the tab order with no accessible name at all: reachable, and silent
+        // when it was reached. Input and Textarea both forward it here; this is
+        // the third one doing the same thing.
+        id={id}
+        size={nativeSize}
+        {...rest}
+        // OR-ed with the spread for the reason spelled out on Input's copy: this
+        // branch wrote `invalid || undefined`, so passing `aria-invalid` by hand
+        // to a Select — which is what a caller does when the validity is
+        // `"grammar"` or `"spelling"`, or when the paint is not wanted — had the
+        // attribute silently dropped. Input has never done that.
+        aria-invalid={isInvalid || rest["aria-invalid"] || undefined}
+        aria-describedby={describedBy}
+        className={cn(
+          FIELD_BASE,
+          dress,
+          listBox && "py-0",
+          small && SELECT_SM,
+          selectClassName,
+          isInvalid && FIELD_INVALID,
+        )}
+      >
+        {children}
+      </select>
+    );
+    // A FieldHint with no label line to ride (0.15.5 P8): an unlabelled Select — named
+    // by `aria-label` or a `<label>` of the caller's — dropped a non-text `hint`
+    // without a trace, so the "?" a caller passed never rendered and a test looking
+    // for its button found none. It goes at the end of the field instead, outside the
+    // box, as the label line's own hint goes at the end of the label.
+    if (hasContent(hint) && !textHint) {
+      return (
+        <FieldGroup errorEl={below}>
+          <div className={cn("flex items-center gap-1.5", className)}>
+            <div className="relative min-w-0 flex-1">
+              {select}
+              {chevron}
+            </div>
+            <span className="flex shrink-0 items-center">{hint}</span>
+          </div>
+        </FieldGroup>
+      );
+    }
     return (
       <FieldGroup errorEl={below}>
         <div className={cn("relative", className)}>
-          <select
-            ref={ref}
-            // `id` is destructured out of the props to feed `fieldId`, and this branch
-            // never put it back — so an UNLABELLED Select swallowed it and the
-            // consumer's own `<label for="…">` pointed at nothing. The control stayed
-            // in the tab order with no accessible name at all: reachable, and silent
-            // when it was reached. Input and Textarea both forward it here; this is
-            // the third one doing the same thing.
-            id={id}
-            size={nativeSize}
-            {...rest}
-            // OR-ed with the spread for the reason spelled out on Input's copy: this
-            // branch wrote `invalid || undefined`, so passing `aria-invalid` by hand
-            // to a Select — which is what a caller does when the validity is
-            // `"grammar"` or `"spelling"`, or when the paint is not wanted — had the
-            // attribute silently dropped. Input has never done that.
-            aria-invalid={isInvalid || rest["aria-invalid"] || undefined}
-            aria-describedby={describedBy}
-            className={cn(
-              FIELD_BASE,
-              dress,
-              listBox && "py-0",
-              small && SELECT_SM,
-              selectClassName,
-              isInvalid && FIELD_INVALID,
-            )}
-          >
-            {children}
-          </select>
+          {select}
           {chevron}
         </div>
       </FieldGroup>
@@ -2124,6 +2234,13 @@ export interface CardProps extends ComponentPropsWithoutRef<"div"> {
    * Left out, the default card keeps no padding (its CardHeader / CardContent own the
    * rhythm) and `inset` keeps its `p-3`; passing it sets theirs too. A caller's `p-*`
    * in `className` still wins.
+   *
+   * Whenever the card carries a padding — this prop, or the `inset` / `outline` one —
+   * CardHeader, CardContent and CardFooter drop their own `px-6` / `pt-6` / `pb-6`, so
+   * the card's padding is the only one. Before 0.16 they kept it regardless and a
+   * `padding="md"` card with parts was padded twice (40px a side); keksdose's settings
+   * cards zeroed all three parts by hand (`<CardHeader className="p-0">`). A padding set
+   * only through `className` cannot be seen from the parts: use the prop.
    */
   padding?: "none" | "sm" | "md";
   /**
@@ -2137,6 +2254,21 @@ export interface CardProps extends ComponentPropsWithoutRef<"div"> {
    * selectors.
    */
   tone?: CardTone;
+  /**
+   * How loud the `tone` frame is. `"strong"`: a 2px border in the tone's strong
+   * colour — `--danger-border-strong` for `danger`, the tone's own text colour
+   * (`--warning`, `--info`, `--success`) for the others, which have no
+   * `-border-strong` token of their own. For the one tile on a page that guards
+   * something destructive or security-relevant: keksdose's password / delete-account
+   * tile (shared/components/password-danger-card.tsx) wrote `toneFrameClass(tone)` over
+   * the Card by hand for the 2px rule, and `p-[15px]` under it so the content did not
+   * move. Here the extra pixel comes off the padding the same way (`padding` or the
+   * variant's own), so a strong card's content sits exactly where a soft one's does.
+   *
+   * Default `"soft"`: the 1px `-border` it has always been. No effect without `tone`,
+   * nor on `inset`, which has no border to make louder (its tone is a fill).
+   */
+  toneStrength?: "soft" | "strong";
 }
 
 export type CardTone = "warning" | "danger" | "info" | "success";
@@ -2172,13 +2304,49 @@ const CARD_PADDING: Record<NonNullable<CardProps["padding"]>, string> = {
   md: "p-4",
 };
 
-export function Card({ className, children, flush, variant = "default", tone, padding, ...rest }: CardProps) {
+// The same padding one pixel short, for a 2px `toneStrength="strong"` frame: the
+// border grows inwards by that pixel, so the content stays where the 1px card had it.
+const CARD_PADDING_STRONG: Record<NonNullable<CardProps["padding"]>, string> = {
+  none: "p-0",
+  sm: "p-[11px]",
+  md: "p-[15px]",
+};
+
+const CARD_TONES_STRONG: Record<CardTone, string> = {
+  warning: "border-2 border-[var(--warning)]",
+  danger: "border-2 border-[var(--danger-border-strong)]",
+  info: "border-2 border-[var(--info)]",
+  success: "border-2 border-[var(--success)]",
+};
+
+/**
+ * Whether the {@link Card} round the parts carries the padding itself — so CardHeader,
+ * CardContent and CardFooter must not add theirs on top. `false` (no Card, or a default
+ * card with no `padding`) keeps the parts' own `px-6` rhythm, as it always was.
+ */
+const CardPaddedContext = createContext(false);
+
+export function Card({
+  className,
+  children,
+  flush,
+  variant = "default",
+  tone,
+  toneStrength = "soft",
+  padding,
+  ...rest
+}: CardProps) {
   const toned = tone ? CARD_TONES[tone] : undefined;
   // An outline card is bordered like the default one, so a tone recolours its border.
   const bordered = variant !== "inset";
+  const strong = toned !== undefined && bordered && toneStrength === "strong";
+  // The padding the card itself carries: the prop, else the variant's own (`inset`
+  // p-3, `outline` p-4). A default card with no prop carries none — its parts do.
+  const ownPadding = padding ?? (variant === "inset" ? "sm" : variant === "outline" ? "md" : undefined);
   return (
     <div
       data-tone={tone}
+      data-tone-strength={strong ? "strong" : undefined}
       {...rest}
       className={cn(
         variant === "inset"
@@ -2196,39 +2364,80 @@ export function Card({ className, children, flush, variant = "default", tone, pa
                 : "rounded-lg border border-[var(--border)] shadow-sm",
             ),
         toned && (bordered ? toned.border : toned.fill),
+        strong && tone && CARD_TONES_STRONG[tone],
         toned?.title,
-        padding && CARD_PADDING[padding],
+        ownPadding && (strong ? CARD_PADDING_STRONG : CARD_PADDING)[ownPadding],
         className,
       )}
     >
-      {children}
+      <CardPaddedContext.Provider value={ownPadding !== undefined}>{children}</CardPaddedContext.Provider>
     </div>
   );
 }
 
-// Composed shadcn-style Card sub-parts. `Card` stays padding-less (callers set
-// their own padding via className), so these own the padding/rhythm. Token-driven
-// so they re-skin with the palette. Use CardHeader → CardTitle/CardDescription
-// (+ optional CardAction, top-right) → CardContent → CardFooter.
+// Composed shadcn-style Card sub-parts. A default `Card` with no `padding` stays
+// padding-less, so these own the padding/rhythm (`px-6`, the header's `pt-6`, the
+// last part's `pb-6`). A Card that carries a padding of its own — the `padding` prop,
+// or `inset` / `outline`, which have one built in — tells them so through context and
+// they add none on top (see CardPaddedContext). Token-driven so they re-skin with the
+// palette. Use CardHeader → CardTitle/CardDescription (+ optional CardAction,
+// top-right) → CardContent → CardFooter.
 /** The sub-parts add nothing to a `<div>`'s props — they are the SAME element with a
- *  `data-slot` and a padding rhythm — so each name is an alias rather than an empty
+ *  `data-slot` and a padding rhythm — so most names are aliases rather than an empty
  *  interface pretending to be more. They exist so a consumer's own wrapper can say
  *  `CardHeaderProps` instead of `ComponentProps<typeof CardHeader>`. */
-export type CardHeaderProps = ComponentPropsWithoutRef<"div">;
-export type CardTitleProps = ComponentPropsWithoutRef<"div">;
+export interface CardHeaderProps extends ComponentPropsWithoutRef<"div"> {
+  /**
+   * Below the `sm` breakpoint, put the {@link CardAction} UNDER the title and
+   * description instead of beside them. For an action that is wider than an icon —
+   * a "Set up two-factor" button, a checkbox and a filter — which, kept in the
+   * top-end column on a 390px phone, squeezed the title into a ribbon two words wide
+   * (keksdose's settings cards). Off by default: an icon action (the wizard summary's
+   * pencil) is narrow enough to stay beside the title at every width.
+   */
+  stackAction?: boolean;
+}
+export type CardTitleLevel = "div" | "h2" | "h3" | "h4";
+export interface CardTitleProps extends ComponentPropsWithoutRef<"div"> {
+  /**
+   * The element the title is: `"div"` (default) or a heading level. Five of keksdose's
+   * settings cards nested their own `<h2>` / `<h3>` INSIDE CardTitle to put the card in
+   * the page's outline — a heading in a div that looks like a heading. The heading
+   * takes the title's look unchanged (the reset leaves `h2`–`h4` at inherited size and
+   * weight), so only the outline changes.
+   */
+  as?: CardTitleLevel;
+}
 export type CardDescriptionProps = ComponentPropsWithoutRef<"div">;
 export type CardActionProps = ComponentPropsWithoutRef<"div">;
 export type CardContentProps = ComponentPropsWithoutRef<"div">;
 export type CardFooterProps = ComponentPropsWithoutRef<"div">;
 
-export function CardHeader({ className, ...props }: CardHeaderProps) {
+export function CardHeader({ className, stackAction = false, ...props }: CardHeaderProps) {
+  const padded = useContext(CardPaddedContext);
   return (
     <div
       data-slot="card-header"
       className={cn(
         // Grid (not flex) so CardAction can occupy a top-right column; with no
         // action it collapses to one column and title/description stack.
-        "grid auto-rows-min items-start gap-1.5 px-6 pt-6 has-data-[slot=card-action]:grid-cols-[1fr_auto]",
+        //
+        // The two-column switch sets a VARIABLE, not `grid-template-columns`. As
+        // `has-data-[slot=card-action]:grid-cols-[1fr_auto]` it was two classes of
+        // specificity (the class plus the attribute inside `:has()`), and a caller's
+        // `max-sm:grid-cols-1` — one class inside a media query — lost to it at every
+        // width, so the action could never be stacked on a phone from outside. Now the
+        // property itself is set by a plain one-class utility that any `grid-cols-*`
+        // variant of the caller's outranks by coming later in the sheet; the `:has()`
+        // rule only picks the value. The base `1fr` resets the variable so a header
+        // never inherits an ancestor header's two columns.
+        "grid auto-rows-min items-start gap-1.5 [--card-header-cols:1fr] has-data-[slot=card-action]:[--card-header-cols:1fr_auto] grid-cols-[var(--card-header-cols,1fr)]",
+        padded ? "px-0 pt-0" : "px-6 pt-6",
+        // One column under `sm`, and the action back into the flow (DOM order, so
+        // after the description when it is written after it), at the start edge.
+        // The descendant selector outranks CardAction's own placement classes.
+        stackAction &&
+          "max-sm:grid-cols-1 max-sm:[&>[data-slot=card-action]]:col-start-1 max-sm:[&>[data-slot=card-action]]:row-span-1 max-sm:[&>[data-slot=card-action]]:row-start-auto max-sm:[&>[data-slot=card-action]]:justify-self-start",
         className,
       )}
       {...props}
@@ -2236,21 +2445,19 @@ export function CardHeader({ className, ...props }: CardHeaderProps) {
   );
 }
 
-export function CardTitle({ className, ...props }: CardTitleProps) {
-  return (
-    <div
-      data-slot="card-title"
-      className={cn("font-semibold leading-none", className)}
-      {...props}
-    />
-  );
+export function CardTitle({ className, as: Tag = "div", ...props }: CardTitleProps) {
+  return <Tag data-slot="card-title" className={cn("font-semibold leading-none", className)} {...props} />;
 }
 
 export function CardDescription({ className, ...props }: CardDescriptionProps) {
   return (
     <div
       data-slot="card-description"
-      className={cn("text-sm text-[var(--money-neutral)]", className)}
+      // `--text-muted`, the kit's secondary-line colour (StatTile's description, the
+      // field captions). It was `--money-neutral`, a MONEY token that happened to be
+      // a similar grey — and a palette that re-tunes the money colours moved every
+      // card's description with them.
+      className={cn("text-sm text-[var(--text-muted)]", className)}
       {...props}
     />
   );
@@ -2267,19 +2474,22 @@ export function CardAction({ className, ...props }: CardActionProps) {
 }
 
 export function CardContent({ className, ...props }: CardContentProps) {
+  const padded = useContext(CardPaddedContext);
   // `last:pb-6`, not a plain `pb-6`: CardHeader owns the top padding and CardFooter
   // owns the bottom one, so a card WITHOUT a footer had nothing closing it off and
   // its last field sat flush against the card edge (kastlan feedback: the language
   // input touching the card bottom on /profile). Scoping to `:last-child` fixes that
-  // case and leaves a footered card's rhythm exactly as it was.
-  return <div data-slot="card-content" className={cn("px-6 last:pb-6", className)} {...props} />;
+  // case and leaves a footered card's rhythm exactly as it was. Inside a padded Card
+  // the card closes itself off, so there is nothing to add.
+  return <div data-slot="card-content" className={cn(!padded && "px-6 last:pb-6", className)} {...props} />;
 }
 
 export function CardFooter({ className, ...props }: CardFooterProps) {
+  const padded = useContext(CardPaddedContext);
   return (
     <div
       data-slot="card-footer"
-      className={cn("flex items-center px-6 pb-6", className)}
+      className={cn("flex items-center", !padded && "px-6 pb-6", className)}
       {...props}
     />
   );