@eifi1/ui-kit 0.47.0 → 0.48.1

package/src/components/dropdown.tsx

@@ -3,6 +3,7 @@ import type {
   ComponentPropsWithoutRef,
   ComponentPropsWithRef,
   KeyboardEvent as ReactKeyboardEvent,
+  PointerEvent as ReactPointerEvent,
   ReactNode,
   Ref,
   RefObject,
@@ -10,7 +11,7 @@ import type {
 import { createPortal } from "react-dom";
 import { Search } from "lucide-react";
 import { anchoredInline, useAnchoredPanel } from "../hooks/use-anchored-panel";
-import { runOwnKeyDown, takeEscape, useDismissLayer, useOutsideClick } from "../hooks/use-dismiss";
+import { pressInside, runOwnKeyDown, takeEscape, useDismissLayer, useOutsideClick } from "../hooks/use-dismiss";
 import type { DismissLayer } from "../hooks/use-dismiss";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
 import { cn } from "../lib/cn";
@@ -371,6 +372,13 @@ export function DropdownPanel({
     runOwnKeyDown(e, onKeyDown, panelRef && listLayers.get(panelRef));
     takeEscape(e);
   };
+  // A press in a panel opened from a row (a popover, its lists) is inside the list for
+  // `useDropdown`'s outside press, though portalled elsewhere (dev#623).
+  const markInside = pressInside(panelRef);
+  const handlePointerDownCapture = (e: ReactPointerEvent<HTMLDivElement>) => {
+    rest.onPointerDownCapture?.(e);
+    markInside?.(e);
+  };
   const body = (
     <>
       {header}
@@ -399,6 +407,7 @@ export function DropdownPanel({
         style={style}
         ref={setPanel}
         onKeyDown={handleKeyDown}
+        onPointerDownCapture={handlePointerDownCapture}
         className={cn(
           "absolute z-30 mt-1 rounded-md border border-subtle bg-surface shadow-lg",
           "[&>ul]:max-h-64",
@@ -425,6 +434,7 @@ export function DropdownPanel({
       ref={setPanel}
       dir={dir}
       onKeyDown={handleKeyDown}
+      onPointerDownCapture={handlePointerDownCapture}
       // 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 these values are the panel's own. Flipped above, it hangs from its

package/src/components/floating-panel.tsx

@@ -17,6 +17,7 @@ import { cn } from "../lib/cn";
 import { FOCUS_RING } from "./focus-ring";
 import { dirOf, type Direction } from "../lib/direction";
 import { registerFloating } from "../lib/floating-stack";
+import { useFloatClearance } from "../lib/float-clearance";
 import { isComposing } from "../lib/ime";
 import { takeEscape } from "../hooks/use-dismiss";
 import { useKitLabels, useKitLink } from "../i18n/kit-labels";
@@ -179,6 +180,11 @@ export interface FloatingActionButtonProps extends Omit<ButtonHTMLAttributes<HTM
  *
  * While mounted it reports its box (`lib/floating-stack.ts`), so `ServerWakeNotice`
  * stacks above it rather than over it.
+ *
+ * 0.48: while mounted, `hidden` or not, it also publishes the room it takes above the
+ * nav (`offset` + 3rem + a 0.5rem gap) as `--app-float-clearance` on `<html>` (the
+ * largest of several wins), and `AppShell` pads its `<main>` past it on a phone, so the
+ * page's last row no longer ends under the button (keksdose dev#612).
  */
 export function FloatingActionButton({
   label,
@@ -206,6 +212,10 @@ export function FloatingActionButton({
   // The fixed element — the button, or the wrapper when there is a tooltip.
   const [fixed, setFixed] = useState<HTMLElement | null>(null);
   useEffect(() => (fixed ? registerFloating(fixed) : undefined), [fixed]);
+  // The room it takes above the nav, for AppShell's <main> to pad past (keksdose
+  // dev#612). Hidden too: the room is the launcher's while it is mounted, so the page
+  // does not change length under the reader as it hides and shows.
+  useFloatClearance(offset);
   const buttonRef = useCallback(
     (node: HTMLButtonElement | null) => {
       assignRef(ref, node);
@@ -332,6 +342,14 @@ export interface FloatingPanelProps {
   className?: string;
   /** Extra classes for the scrolling body. */
   bodyClassName?: string;
+  /**
+   * 0.48: take the FAB and the panel off screen while keeping both mounted — the open
+   * state and the bottom room (`--app-float-clearance`) stay, and an open panel is back
+   * when this turns `false`. keksdose's assistant launcher steps aside while an editor
+   * or a modal covers its corner (dev#612); unmounting it instead would give the room
+   * back and shorten the page under the reader's thumb.
+   */
+  hidden?: boolean;
   children: ReactNode;
 }
 
@@ -382,6 +400,7 @@ export function FloatingPanel({
   initialFocus,
   className,
   bodyClassName,
+  hidden = false,
   children,
 }: FloatingPanelProps) {
   const labels = useKitLabels(
@@ -457,8 +476,9 @@ export function FloatingPanel({
         offset={offset}
         nativeTitle={fabNativeTitle}
         tooltip={fabTooltip}
+        hidden={hidden || undefined}
         aria-expanded={open}
-        aria-controls={open ? panelId : undefined}
+        aria-controls={open && !hidden ? panelId : undefined}
         onClick={() => {
           // A press ON the FAB closing the panel: the FAB keeps focus by being clicked,
           // nothing to hand back.
@@ -467,6 +487,7 @@ export function FloatingPanel({
         }}
       />
       {open &&
+        !hidden &&
         typeof document !== "undefined" &&
         createPortal(
           // A container for Escape bubbling up from anything inside it, as a dialog is.
@@ -572,6 +593,8 @@ export function FloatingActionGroup({
   ...rest
 }: FloatingActionGroupProps) {
   const [marker, dir] = usePortalDir();
+  // As the FAB's (keksdose dev#612): its 3rem members plus the frame's 1px borders.
+  useFloatClearance(offset, "2px");
   return (
     <>
       <span ref={marker} hidden />

package/src/components/hover-menu.tsx

@@ -163,7 +163,8 @@ export function HoverMenu({
     };
   }, [open, close]);
 
-  useOutsideClick(wrapperRef, close, open);
+  // A press in a panel opened from a row (a popover, its lists) is inside (dev#623).
+  const markInside = useOutsideClick(wrapperRef, close, open);
 
   const menuRef = useRef<HTMLDivElement>(null);
   /** Set by a keyboard press on the trigger, so the open that follows moves focus into
@@ -290,6 +291,10 @@ export function HoverMenu({
       className={cn("relative", className)}
       onMouseEnter={handleMouseEnter}
       onMouseLeave={handleMouseLeave}
+      onPointerDownCapture={(e) => {
+        rest.onPointerDownCapture?.(e);
+        markInside(e);
+      }}
       onKeyDown={(e) => {
         // The caller's handler sees Escape only while this menu is the layer on top: a
         // tooltip on one of its rows takes that press first (round 0.35 R2, the rule

package/src/components/icon-button.tsx

@@ -25,6 +25,7 @@ import {
   HOVER_INK,
   ICON_BUTTON_PRESSED,
   RenderedButtonLink,
+  HIT_AREA_LARGE,
   TOUCH_TARGET_LARGE,
   buttonVariantClasses,
 } from "./button-look";
@@ -106,7 +107,7 @@ const ICON_BUTTON_TEXT_STRETCH_SIZES: Record<IconButtonSize, string> = {
 // (2.75rem is 55 px at Large). `md` … `xs` grow their box to it. `2xs` is the action ON
 // a chip or a tab, whose box cannot grow without growing the chip: it keeps its box and
 // gets a 48 px hit area instead — an invisible `::after` centred on it, which takes the
-// taps a finger lands round the glyph.
+// taps a finger lands round the glyph (`HIT_AREA_LARGE`).
 const ICON_BUTTON_TOUCH_LARGE: Record<IconButtonSize, string> = {
   "2xl": "",
   xl: "",
@@ -114,8 +115,7 @@ const ICON_BUTTON_TOUCH_LARGE: Record<IconButtonSize, string> = {
   md: TOUCH_TARGET_LARGE,
   sm: TOUCH_TARGET_LARGE,
   xs: TOUCH_TARGET_LARGE,
-  "2xs":
-    "relative large:after:absolute large:after:inset-[calc((100%-48px)/2)] large:after:content-['']",
+  "2xs": HIT_AREA_LARGE,
 };
 
 // A tone re-colours the glyph without changing what the variant draws around it.

package/src/components/popover.tsx

@@ -157,7 +157,9 @@ export function Popover({
       }
     : null;
 
-  useOutsideClick([triggerRef, panelRef], close, open);
+  // A press in a list opened from inside — a CurrencySelect's, a combobox's, another
+  // popover's — reaches the panel through the React tree and is inside (dev#623).
+  const markInside = useOutsideClick([triggerRef, panelRef], close, open);
   // A layer on the Escape stack while open (Wave 2, DUP-1): a list opened inside closes
   // first, and the dialog this popover sits in only after it — the calculator on an
   // amount field in a Modal is exactly that.
@@ -216,6 +218,10 @@ export function Popover({
             // silently do nothing on a panel whose children are not yet tabbable.
             tabIndex={-1}
             onKeyDown={handleKeyDown}
+            onPointerDownCapture={(e) => {
+              rest.onPointerDownCapture?.(e);
+              markInside(e);
+            }}
             style={{
               // Merged over the caller's, never replaced by it: these are measured
               // against the trigger every scroll and resize, and a panel that dropped

package/src/components/table-skeleton.tsx

@@ -0,0 +1,133 @@
+import type { ComponentPropsWithRef } from "react";
+import { cn } from "../lib/cn";
+import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
+import { Skeleton } from "./skeleton";
+
+export interface TableSkeletonProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  /** Rows per group (or in all, without `groups`). Default 5. */
+  rows?: number;
+  /** Columns, the name column included. Default 3. */
+  columns?: number;
+  /**
+   * `list` (default): a name bar of varying width, then the other columns as figures at
+   * the row's end — from three columns up they go under the name on a phone, as a card
+   * list draws them. `grid`: a label column, then one equal block per column, clipped
+   * at the edge — a heatmap or a matrix.
+   */
+  variant?: "list" | "grid";
+  /** This many group header bars, each over `rows` rows (a budget's groups). Default none. */
+  groups?: number;
+  /** A row of this many stat-tile outlines above the panel. Default none. */
+  tiles?: number;
+  /** A title and a hint line at the top of the panel, as a card's head. */
+  heading?: boolean;
+  /** The panel's border and surface. Default `true`; `false` for a panel the caller frames. */
+  framed?: boolean;
+  /** What is said, once. Default `common.loading` ("Loading…") from the provider. */
+  label?: string;
+}
+
+/** Name widths that differ from row to row, so the outline reads as a list rather than
+ *  a striped block. */
+const NAME_WIDTHS = ["w-2/5", "w-1/2", "w-1/3", "w-5/12"];
+
+/**
+ * The outline of a table or a list while its data loads (0.48, keksdose dev #628) — so a
+ * page does not jump from a centred spinner to a long list when the data lands.
+ * keksdose hand-built three of these (TabSkeleton, BudgetSkeleton,
+ * VarianceHeatmapSkeleton), each a stack of `Skeleton`s with its own sr-only line.
+ *
+ * ONE `role="status"` region says "Loading…" once; every placeholder inside is
+ * `aria-hidden` — not one announcement per row. The pulse stops under reduced motion
+ * (`Skeleton`'s own rule); the shapes stay. Props and `ref` go to the region.
+ */
+export function TableSkeleton({
+  rows = 5,
+  columns = 3,
+  variant = "list",
+  groups = 0,
+  tiles = 0,
+  heading = false,
+  framed = true,
+  label,
+  className,
+  ...rest
+}: TableSkeletonProps) {
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const figures = Math.max(0, columns - 1);
+  const grid = variant === "grid";
+  // Three figures don't fit beside a name on a phone; one or two do.
+  const stack = !grid && figures >= 2;
+
+  const row = (key: number) =>
+    grid ? (
+      <div key={key} className="flex items-center gap-1" data-skeleton-row="">
+        <Skeleton className="h-7 w-28 shrink-0" />
+        {Array.from({ length: figures }, (_, c) => (
+          <Skeleton key={c} className="h-7 w-12 shrink-0" />
+        ))}
+      </div>
+    ) : (
+      <div
+        key={key}
+        className={cn("flex items-center gap-4 px-4 py-3", stack && "max-sm:flex-col max-sm:items-stretch max-sm:gap-2")}
+        data-skeleton-row=""
+      >
+        <Skeleton className={cn("h-4", NAME_WIDTHS[key % NAME_WIDTHS.length])} />
+        {figures > 0 && (
+          <div className={cn("ms-auto flex gap-6", stack && "max-sm:ms-0 max-sm:justify-between max-sm:gap-2")}>
+            {Array.from({ length: figures }, (_, f) => (
+              <Skeleton key={f} className="h-4 w-16 md:w-24" />
+            ))}
+          </div>
+        )}
+      </div>
+    );
+
+  const block = (offset: number) => (
+    <div className={grid ? "space-y-1 overflow-hidden" : "divide-y divide-subtle"}>
+      {Array.from({ length: rows }, (_, r) => row(offset + r))}
+    </div>
+  );
+
+  return (
+    // `relative`: the containing block for the sr-only text (sr-only-containment.test).
+    <div {...rest} role="status" className={cn("relative", className)} data-skeleton-preset="table">
+      <span className="sr-only">{label ?? common.loading}</span>
+      <div aria-hidden="true" className="flex flex-col gap-4">
+        {tiles > 0 && (
+          <div className="grid grid-cols-[repeat(auto-fit,minmax(9rem,1fr))] gap-3">
+            {Array.from({ length: tiles }, (_, i) => (
+              <div key={i} className="rounded-lg border border-subtle bg-surface p-4" data-skeleton-tile="">
+                <Skeleton className="h-3 w-24 max-w-full" />
+                <Skeleton className="mt-3 h-7 w-32 max-w-full" />
+              </div>
+            ))}
+          </div>
+        )}
+        <div
+          className={cn("overflow-clip", framed && "rounded-lg border border-subtle bg-surface", grid && "p-3")}
+          data-skeleton-panel=""
+        >
+          {heading && (
+            <div className={cn(grid ? "mb-3" : "px-4 pt-4 pb-2")} data-skeleton-heading="">
+              <Skeleton className="h-4 w-40 max-w-full" />
+              <Skeleton className="mt-2 h-3 w-64 max-w-full" />
+            </div>
+          )}
+          {groups > 0
+            ? Array.from({ length: groups }, (_, g) => (
+                <div key={g} className={cn(g > 0 && "border-t border-subtle")}>
+                  <div className="flex items-center gap-3 bg-surface-2 px-4 py-2.5" data-skeleton-group="">
+                    <Skeleton className={cn("h-4", g % 2 ? "w-24" : "w-28")} />
+                    <Skeleton className="ms-auto h-4 w-12" />
+                  </div>
+                  {block(g * rows)}
+                </div>
+              ))
+            : block(0)}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/tabs.tsx

@@ -11,6 +11,7 @@ import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import { mergeRefs } from "./field-parts";
 import { DEFAULT_TABS_LABELS } from "./ui-labels";
 import { IconButton } from "./icon-button";
+import { HIT_AREA_LARGE } from "./button-look";
 
 /** One tab of a {@link Tabs} strip. */
 export interface TabItem<T extends string> {
@@ -48,16 +49,10 @@ export interface TabsLabels {
   add: string;
   /** Accessible name of a tab's × — "Remove <tab>". */
   remove: (tab: string) => string;
-  /** The `overflowCue` › over the strip's end, while tabs lie past it: "More tabs". */
+  /** The `overflowCue` › after the strip's end, while tabs lie past it: "More tabs". */
   more: string;
-  /** The `overflowCue` ‹ over the strip's start, while tabs lie before it: "Previous tabs". */
+  /** The `overflowCue` ‹ before the strip's start, while tabs lie before it: "Previous tabs". */
   previous: string;
-  /**
-   * @deprecated 0.47: not drawn any more — the caret that turned into "back to the
-   * first tab" at the strip's end is now a ‹ of its own (`previous`). Accepted and
-   * ignored; removed in 0.48.
-   */
-  backToFirst?: string;
 }
 
 // Defined in ./ui-labels, which holds no component code (0.34, KS U8).
@@ -84,8 +79,8 @@ export interface TabsProps<T extends string>
   onChange: (id: T) => void;
   className?: string;
   /**
-   * Carets over the ends of a SCROLLING strip (0.40, kk run 79 gap 1; 0.47, keksdose
-   * live #410 round 4): a › over the strip's end while tabs lie past it, and a ‹ over
+   * Carets at the ends of a SCROLLING strip (0.40, kk run 79 gap 1; 0.47, keksdose
+   * live #410 round 4): a › after the strip's end while tabs lie past it, and a ‹ before
    * its start while tabs lie before it — each there only while something is hidden
    * past ITS edge (1 px slack, so a few cut-off pixels count), each a step of three
    * quarters of the strip's width toward its own side. Neither ever changes direction:
@@ -94,8 +89,12 @@ export interface TabsProps<T extends string>
    *
    * The edge fade alone could read as the end of the row: the last visible tab can
    * finish exactly where the fade begins, so nothing looks cut off (keksdose live #410).
-   * The carets sit OVER the strip's ends (positioned, on the page's surface), not beside
-   * it, so the strip's width never changes as they come and go. Out of the tab order —
+   * Since 0.48 (live #410 rounds 5–6) the carets are bare glyphs BESIDE the strip — the ‹
+   * before it, the › after it — centred on the labels, muted and primary on hover, with
+   * no frame, fill or shadow; until 0.47 they were framed buttons laid over the strip's
+   * last visible tabs. While the strip overflows at all it keeps a 24px gutter at both
+   * ends, and each caret sits in its own, so scrolling never changes the strip's width
+   * or moves its labels; a strip that fits has no gutters. Out of the tab order —
    * the keyboard walks the strip with the arrow keys, which bring the focused tab into
    * view. At every width. Ignored on a vertical strip (a side nav is a column, not a
    * row). Names: `tabs.more` / `tabs.previous`. keksdose's `scroll-edge-cues.tsx` is
@@ -262,7 +261,7 @@ export function Tabs<T extends string>({
   const stripRef = useRef<HTMLDivElement>(null);
   const setStrip = useMemo(() => mergeRefs(stripRef, ref), [ref]);
   const fade = useStripFade(stripRef);
-  // See `overflowCue`: a ‹ over the start while tabs lie before it, a › over the end
+  // See `overflowCue`: a ‹ before the strip while tabs lie before it, a › after it
   // while tabs lie past it — `fade.overflow` names the cut ends in reading-direction terms.
   const cue = overflowCue && !vertical;
   const cueStart = cue && (fade.overflow === "start" || fade.overflow === "both");
@@ -276,27 +275,56 @@ export function Tabs<T extends string>({
     const toward = (side === "end" ? 1 : -1) * (rtl ? -1 : 1);
     strip.scrollBy({ left: toward * Math.round(strip.clientWidth * 0.75), behavior });
   };
-  // OVER the strip's end, on the page's surface, so the caret reads as a control and not
-  // as one more faded tab — and so it can come and go without the strip changing width
-  // under the thumb. The position sits on a wrapper of ours: IconButton puts its
-  // tooltip's span around the button, and a class on the button would land inside it.
-  const cueAt = (side: "start" | "end") => (
+  // In a GUTTER of its own at the strip's end (0.48, keksdose live #410 rounds 5–6): a
+  // bare glyph — no frame, fill or shadow — muted until the pointer comes. Round 5 put
+  // each cue in the flow beside the strip, so it took 24px the moment it appeared and the
+  // labels jumped sideways at every edge the scroll crossed ("It has problems with moving
+  // to left and right especially when moving the scroll bar"). Now the strip box keeps a
+  // 24px gutter at BOTH ends for as long as the strip overflows at all (`px-[24px]`, see
+  // `stripBox`), and each gutter is absolute in that padding, so a cue coming or going
+  // never moves the strip, its labels or the scroll position under the thumb. A strip
+  // that fits has no gutters: its width changes only when it starts or stops overflowing.
+  // The gutter carries the strip's 1px rule on beneath the glyph, and lifts the glyph
+  // onto the LABELS' centre rather than the box's: a tab's 2px underline (`border-b-2`)
+  // sits on the rule (`-mb-px`), so the labels are centred 2px above the box's bottom —
+  // the gutter's 1px rule (`border-b`) plus 1px more (`pb-px`).
+  // 24px wide at every text size (KS N3): at Large `sm`'s 48px minimum made each cue
+  // 48px, and at 360px the two left a two-tab strip 100px. 24 PIXELS, not `w-6`: the rem
+  // grows with the text size (24 / 30 / 36px), and at Extra large on a 360px phone the two
+  // gutters took 72px of a 226px strip and a sheet tab wrapped to seven lines (0.48 build
+  // review 2, KS N1). The 48px touch target is an
+  // invisible hit area round the glyph instead (`HIT_AREA_LARGE`, as `2xs`), over the
+  // strip's faded edge, not room taken from the row. The wrapper inside the gutter is
+  // ours because IconButton puts its tooltip's span around the button.
+  const gutterAt = (side: "start" | "end", shown: boolean) => (
     <div
-      data-tabs-overflow-cue={side}
-      className={cn("absolute top-1/2 z-10 flex -translate-y-1/2", side === "start" ? "start-0" : "end-0")}
+      data-tabs-cue-gutter={side}
+      className={cn(
+        "absolute inset-y-0 flex w-[24px] items-center justify-center border-b border-subtle pb-px",
+        side === "start" ? "start-0" : "end-0",
+      )}
     >
-      <IconButton
-        size="sm"
-        variant="secondary"
-        className="bg-surface shadow-sm"
-        tabIndex={-1}
-        type="button"
-        label={side === "start" ? text.previous : text.more}
-        labelVisible={false}
-        onClick={() => onCue(side)}
-      >
-        {side === "start" ? <ChevronLeft className="rtl:-scale-x-100" /> : <ChevronRight className="rtl:-scale-x-100" />}
-      </IconButton>
+      {shown && (
+        <div data-tabs-overflow-cue={side} className="flex">
+          <IconButton
+            size="sm"
+            variant="ghost"
+            className={cn(
+              "w-[24px] large:min-w-0 bg-transparent text-muted hover:bg-transparent hover:text-primary",
+              // Over the strip's faded edge, for ‹ too.
+              HIT_AREA_LARGE,
+              "large:after:z-[1]",
+            )}
+            tabIndex={-1}
+            type="button"
+            label={side === "start" ? text.previous : text.more}
+            labelVisible={false}
+            onClick={() => onCue(side)}
+          >
+            {side === "start" ? <ChevronLeft className="rtl:-scale-x-100" /> : <ChevronRight className="rtl:-scale-x-100" />}
+          </IconButton>
+        </div>
+      )}
     </div>
   );
   // The OPEN tab is scrolled into the strip whenever it changes — on mount too, for a
@@ -590,13 +618,15 @@ export function Tabs<T extends string>({
         {text.remove(nameOf(activeTab))}
       </button>
     ) : null;
-  // The positioned box the carets sit in, over the strip's two ends (see `overflowCue`).
-  // There whether or not the strip overflows right now, so a resize never re-parents it.
+  // The box the cues sit in, ‹ in the gutter before the strip and › in the one after it
+  // (see `gutterAt`). There whether or not the strip overflows right now, so a resize
+  // never re-parents it; the gutters only while it overflows at all.
+  const gutters = cue && fade.overflow !== undefined;
   const stripBox = cue ? (
-    <div className={cn("relative flex min-w-0", !onAdd && "flex-1")}>
+    <div className={cn("relative flex min-w-0", !onAdd && "flex-1", gutters && "px-[24px]")}>
       {tablist}
-      {cueStart && cueAt("start")}
-      {cueEnd && cueAt("end")}
+      {gutters && gutterAt("start", cueStart)}
+      {gutters && gutterAt("end", cueEnd)}
     </div>
   ) : (
     tablist

package/src/components/use-table-state.ts

@@ -1,4 +1,5 @@
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { SetStateAction } from "react";
 import { useLocation, useSearchParams } from "react-router";
 import { useKitTableStorageKeyPrefix } from "../i18n/kit-labels";
 import { readStored, writeStored } from "../lib/safe-storage";
@@ -24,6 +25,17 @@ interface PersistedState {
   pageSize: number | "all";
   widths?: Record<string, number>;
   hidden?: string[];
+  /** 0.48: the `defaultHidden` columns the user ticked back on — an entry that beats the
+   *  default. Written only when non-empty, so a table without such columns stores what
+   *  it always did. */
+  shown?: string[];
+}
+
+/** The hidden set as drawn: the stored one plus every `defaultHidden` column the view
+ *  holds no entry for (neither hidden nor `shown`). */
+function withDefaultHidden(view: { hidden: Set<string>; shown: Set<string> }, defaults: string[]): Set<string> {
+  const extra = defaults.filter((k) => !view.hidden.has(k) && !view.shown.has(k));
+  return extra.length === 0 ? view.hidden : new Set([...view.hidden, ...extra]);
 }
 
 export const DEFAULT_PERSIST_PREFIX = "hbui-table:";
@@ -338,7 +350,45 @@ export function useTableState<T>({
   );
   const pageSize = pageSizeProp ?? internalPageSize;
   const [widths, setWidths] = useState<Record<string, number>>(() => initial.widths ?? {});
-  const [hiddenCols, setHiddenCols] = useState<Set<string>>(() => new Set(initial.hidden ?? []));
+  // Hidden columns (0.48, keksdose #617): what the user chose — `hidden`, and `shown`
+  // for a `defaultHidden` column ticked back on — kept apart from the defaults, which
+  // are applied on read and never stored. Keyed on the default keys as a string: every
+  // call site builds `columns` inline, so the array is new on every render.
+  const [view, setView] = useState(() => ({
+    hidden: new Set<string>(initial.hidden ?? []),
+    shown: new Set<string>(initial.shown ?? []),
+  }));
+  const defaultHiddenSig = columns
+    .filter((c) => c.defaultHidden)
+    .map((c) => c.key)
+    .join("\u0000");
+  const hiddenCols = useMemo(
+    () => withDefaultHidden(view, defaultHiddenSig ? defaultHiddenSig.split("\u0000") : []),
+    [view, defaultHiddenSig],
+  );
+  // The panel hands over the next DRAWN set; what changed is recorded as a choice.
+  const setHiddenCols = useCallback(
+    (action: SetStateAction<Set<string>>) =>
+      setView((v) => {
+        const defaults = defaultHiddenSig ? defaultHiddenSig.split("\u0000") : [];
+        const prev = withDefaultHidden(v, defaults);
+        const next = typeof action === "function" ? action(prev) : action;
+        const hidden = new Set(v.hidden);
+        const shown = new Set(v.shown);
+        for (const k of next) {
+          if (prev.has(k)) continue;
+          hidden.add(k);
+          shown.delete(k);
+        }
+        for (const k of prev) {
+          if (next.has(k)) continue;
+          hidden.delete(k);
+          if (defaults.includes(k)) shown.add(k);
+        }
+        return { hidden, shown };
+      }),
+    [defaultHiddenSig],
+  );
   const [showSettings, setShowSettings] = useState(false);
   const headRefs = useMemo(() => new Map<string, HTMLTableCellElement>(), []);
 
@@ -360,7 +410,8 @@ export function useTableState<T>({
         filters,
         pageSize: pageSize === Infinity ? "all" : pageSize,
         widths,
-        hidden: Array.from(hiddenCols),
+        hidden: Array.from(view.hidden),
+        ...(view.shown.size > 0 ? { shown: Array.from(view.shown) } : {}),
       });
   useEffect(() => {
     if (!storageKey) return;

package/src/data-table.ts

@@ -30,6 +30,8 @@ export type {
 // 0.46.1 (keksdose N3): a swipe plan as `RowActions`' actions — the desktop column's own
 // derivation, for an app's hand-built actions column.
 export { swipePlanRowActions } from "./components/data-table-row-actions";
+// 0.48 (keksdose dev #605): a `groupBy` level (also `mobileGroupBy`'s) and the `loadMore` footer.
+export type { DataTableGroupBy, DataTableLoadMore } from "./components/data-table-groups";
 export * from "./components/data-table-cells";
 export { useTableUrlState, readTableUrlState } from "./components/use-table-state";
 export type {