fix(spa): banner contrast, Layout Reset, empty-inline collapse (#589, #590, #591)

Three SPA polish bugs / refactors reported against v1.3.0, all
addressed in one patch release.

#589 — experience-toggle strip link contrast collapses in dark mode
-------------------------------------------------------------------
The strip's link used `hover:text-gray-900`, which in light mode is
near-black on the muted `bg-gray-50` strip — readable. In dark mode,
`bg-gray-50` remaps to #0b1020 (near-black) but `hover:text-gray-900`
had no `.dark` remap, so on :hover the text resolved to its raw
Tailwind value (#111827) — essentially the same near-black as the
strip background. Result: text faded INTO the bg on hover, the
opposite of normal hover affordance.

Fixes:
- `frontend/apps/web/src/index.css` adds `.dark` remaps for
  `hover:text-gray-{700,800,900}` (→ #f9fafb) and `hover:text-gray-
  {100,200}` (→ #ffffff). Future components using those JSX-side
  hover variants get the right :hover contrast automatically.
- `django_admin_react/templates/django_admin_react/_experience_toggle_strip.html`
  on the legacy Django admin side switches the link from
  `color: inherit` (no hover state) to an explicit two-token model:
  `var(--link-fg, #1f2937)` at rest, `var(--link-hover-color, #000)`
  on :hover — these are Django admin's own theme variables (defined
  in `admin/css/base.css` from 4.2+), so Django's bundled light and
  dark themes both light the link correctly. A small inline
  `<style>` keeps the strip with zero external CSS dependencies.

#590 — Reset button on Layout modal + shared <ResetButton> primitive
--------------------------------------------------------------------
The Customize / Layout modal (post-#586) had no way to return to the
ModelAdmin's default order + visibility. Manual drag every row back
or open devtools and clear localStorage. Filter row's "Clear all"
solved the same UX gap for filters but with a different inline
implementation — two impls of the same primitive.

- New `frontend/packages/ui/src/ResetButton.tsx` — generic
  return-to-defaults button. Takes `isDirty`, `onReset` (sync OR
  async — pending state for promise-returning callbacks), `label`,
  `disabledHint`, optional `icon` ReactNode, optional `trailing`
  ReactNode. Stays icon-agnostic (the caller passes the icon as a
  prop) so @dar/ui doesn't pick up a lucide-react dep — matches the
  rest of the package's "primitives without an icon library"
  contract.
- `frontend/apps/web/src/pages/ListPage.tsx` "Clear all" button
  refactored to use <ResetButton label="Clear all" icon={<X.../>}>.
  Disabled (not hidden) when no filters apply, with a discoverable
  tooltip "No filters applied" — the affordance stays visible so
  users learn it exists before they need it.
- `frontend/apps/web/src/ColumnLayoutModal.tsx` adds a Reset button
  in the modal header alongside the description. `isDirty` checks
  whether the user has a non-empty saved order OR any hidden col;
  resetting clears both back to empty so the ModelAdmin's
  registered defaults take over.

#591 — empty inlines collapse-or-hide on the detail page
--------------------------------------------------------
A typical detail page registers multiple inlines (comments, history,
attachments, audit). On a freshly-created object none have records
yet — the page becomes a tall stack of empty "No X yet" panels with
no information.

Today an empty + non-addable inline was already hidden entirely
(Option A). What was missing was Option B for empty + addable
inlines: instead of rendering the full "No X yet" panel, render
just the title bar with a caret toggle. The body (the
"No X yet — click Edit to add the first one" hint) only shows when
the operator expands the section.

- New `CollapsedEmptyInline` helper in
  `frontend/apps/web/src/pages/DetailPage.tsx` mirrors the
  `FieldsetSection` collapse pattern (Card + ChevronDown toggle).
- `InlineSection` early-return upgraded:
  - Empty + !can_add → return null  (unchanged Option A).
  - Empty + can_add  → <CollapsedEmptyInline>  (new Option B).
  - Non-empty       → render normally (unchanged).
- Default-collapsed every page load — per-user persistence of which
  empty inlines are expanded isn't worth the storage for a hint
  copy. The "click Edit" affordance below makes the next step
  obvious without enumerating the inline's empty schema.

Bundle impact
-------------
- Main bundle: 263.79 → 265.02 kB (+1.2 kB raw / +0.3 kB gz) for
  the <ResetButton> primitive + the two consumer call sites.
- CSS: 30.66 → 30.83 kB (+170 B raw) for the dark hover remaps.
- ColumnLayoutModal lazy chunk: +0.4 kB (the Reset button + its
  RotateCcw icon import).

No API contract change, no schema change, no settings change.
Patch bump (1.3.0 → 1.3.1).

Closes #589, Closes #590, Closes #591.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: martin-castro-laminr-ai

django_admin_react/templates/django_admin_react/_experience_toggle_strip.html

@@ -5,18 +5,37 @@
   rather than a new admin CSS file so the strip ships without any
   staticfiles requirement on the consumer's side.
 
+  Theme awareness (#589): the link uses CSS custom properties that fall
+  back to a legible-everywhere palette but get overridden by Django
+  admin's own theme variables (`--body-fg`, `--link-fg`,
+  `--link-hover-color`) where present. This keeps contrast WCAG-AA on
+  both Django's default light theme and the dark-mode toggle Django
+  added in 4.2 — hover *brightens* the link, never dims it.
+
   When `visible` is false (either prefix unset, request missing, or
   current path outside the legacy mount), this template renders
   nothing — the surrounding {% block %} stays clean.
 {% endcomment %}
 {% if visible %}
 <div role="region" aria-label="Experience toggle"
-     style="padding:.25rem .75rem; border-bottom:1px solid #e5e7eb;
-            background:#f9fafb; font-size:.75rem; color:#4b5563;">
+     style="padding:.25rem .75rem; border-bottom:1px solid var(--border-color, #e5e7eb);
+            background:var(--darkened-bg, #f9fafb); font-size:.75rem;
+            color:var(--body-fg, #4b5563);">
   <a href="{{ target }}" target="_self" rel="noopener"
-     style="color:inherit; text-decoration:none;">
+     class="dar-experience-toggle-link"
+     style="color:var(--link-fg, #1f2937); text-decoration:underline;
+            text-underline-offset:2px;">
     Looking for the new admin experience?
     <strong style="font-weight:600;">Open this page in {{ react_root }}</strong>
   </a>
 </div>
+{# Inline :hover via <style> so we keep zero external CSS dependencies
+   while still meeting the "hover brightens, never dims" contract (#589). #}
+<style>
+  .dar-experience-toggle-link:hover,
+  .dar-experience-toggle-link:focus-visible {
+    color: var(--link-hover-color, #000000);
+    text-decoration-thickness: 2px;
+  }
+</style>
 {% endif %}

frontend/apps/web/src/ColumnLayoutModal.tsx

@@ -17,7 +17,7 @@
 // rendered without a handle, with a small lock icon and a title=
 // tooltip, so the operator can see WHY it's not draggable.
 
-import { GripVertical, Lock } from 'lucide-react';
+import { GripVertical, Lock, RotateCcw } from 'lucide-react';
 import {
   DndContext,
   KeyboardSensor,
@@ -36,7 +36,7 @@ import {
 } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
 
-import { Checkbox, Modal } from '@dar/ui';
+import { Checkbox, Modal, ResetButton } from '@dar/ui';
 
 export interface ColumnLayoutDescriptor {
   name: string;
@@ -58,6 +58,12 @@ export interface ColumnLayoutModalProps {
   onToggle: (name: string, visibleCount: number) => void;
   /** Persist the new ordering of the non-pk columns. */
   onReorder: (nextNonPkOrder: string[]) => void;
+  /** Is the column layout currently customised vs the registered
+   *  `ModelAdmin` default? Drives the Reset button's enabled state. */
+  isCustomised: boolean;
+  /** Discard any per-user reorder + hide preferences and fall back to
+   *  the registered `ModelAdmin` default (#590). */
+  onReset: () => void;
 }
 
 // Default export to make `React.lazy(() => import('./ColumnLayoutModal'))`
@@ -71,6 +77,8 @@ export default function ColumnLayoutModal({
   visibleColumnCount,
   onToggle,
   onReorder,
+  isCustomised,
+  onReset,
 }: ColumnLayoutModalProps) {
   const sensors = useSensors(
     useSensor(PointerSensor, {
@@ -98,10 +106,24 @@ export default function ColumnLayoutModal({
 
   return (
     <Modal title="Layout" onClose={onClose}>
-      <p className="mb-2 text-xs text-gray-500">
-        Toggle to show or hide. Drag the handle to reorder (keyboard:
-        Tab to a handle, then Space + arrow keys + Space to drop).
-      </p>
+      <div className="mb-2 flex items-center justify-between gap-2">
+        <p className="text-xs text-gray-500">
+          Toggle to show or hide. Drag the handle to reorder (keyboard:
+          Tab to a handle, then Space + arrow keys + Space to drop).
+        </p>
+        {/* Reset (#590): discards the per-user layout and falls back
+            to the registered ModelAdmin default. Disabled when the
+            layout is already at default — the tooltip explains why
+            so the affordance stays discoverable. */}
+        <ResetButton
+          isDirty={isCustomised}
+          onReset={onReset}
+          label="Reset"
+          disabledHint="Layout is already at default"
+          icon={<RotateCcw className="h-4 w-4" aria-hidden />}
+          title="Reset to the default layout"
+        />
+      </div>
       <ul className="space-y-1">
         {pkRow ? (
           <LockedRow

frontend/apps/web/src/index.css

@@ -83,6 +83,21 @@ body,
 .dark .hover\:bg-gray-100:hover {
   background-color: #1f2937 !important;
 }
+/* Hover text-color remaps (#589). Without these, a JSX-side
+   `hover:text-gray-900` (designed against the light surface) resolves
+   to #111827 on :hover under .dark — which is nearly identical to the
+   .dark surface itself, so the text fades INTO the background on
+   hover. Remap the few hover text utilities the app uses so :hover
+   always *increases* contrast against the dark surface, never reduces. */
+.dark .hover\:text-gray-900:hover,
+.dark .hover\:text-gray-800:hover,
+.dark .hover\:text-gray-700:hover {
+  color: #f9fafb !important;
+}
+.dark .hover\:text-gray-200:hover,
+.dark .hover\:text-gray-100:hover {
+  color: #ffffff !important;
+}
 /* Form controls have no explicit bg utility (the @dar/ui Input + the
    filter selects render on the browser-default white), so the bg-white
    remap above misses them — they'd stay white in dark mode. Style them

frontend/apps/web/src/pages/DetailPage.tsx

@@ -905,17 +905,48 @@ function DeleteButton({ label, loadPreview, onConfirm }: DeleteButtonProps) {
   );
 }
 
+// CollapsedEmptyInline (#591) — a slim card showing only the inline's
+// title + a caret toggle. The body (the "No X yet" copy + a hint to
+// enter edit mode) is hidden by default; clicking the title expands
+// it. Default-collapsed every page load — per-user persistence isn't
+// worth the storage for a detail-page hint.
+function CollapsedEmptyInline({ label }: { label: string }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <Card>
+      <button
+        type="button"
+        onClick={() => setOpen((o) => !o)}
+        aria-expanded={open}
+        className="flex w-full items-center justify-between gap-2 text-left text-base font-semibold text-gray-900"
+      >
+        <span>{label}</span>
+        <ChevronDown
+          className={`h-4 w-4 shrink-0 transition-transform ${open ? 'rotate-180' : ''}`}
+          aria-hidden
+        />
+      </button>
+      {open ? (
+        <p className="mt-3 text-sm text-gray-500">
+          No {label.toLowerCase()} yet. Click <span className="font-medium">Edit</span> to
+          add the first one.
+        </p>
+      ) : null}
+    </Card>
+  );
+}
+
 function InlineSection({ inline }: { inline: InlineDescriptor }) {
+  // Empty inline (#591):
+  // - Not addable → hide the whole section (Option A). Empty + read-only
+  //   has zero information value and just lengthens the page.
+  // - Addable → render as a single-line collapsed card with a caret
+  //   (Option B). The operator can see the inline EXISTS (so they
+  //   know to click Edit to add a first child) but the "No X yet"
+  //   placeholder no longer eats vertical space on every load.
   if (inline.rows.length === 0) {
-    // An empty inline the user can't add to is pure noise on the detail
-    // page (#411) — hide the whole section. An empty but *addable* inline
-    // stays, so the first child can still be added.
     if (!inline.can_add) return null;
-    return (
-      <Card title={inline.label}>
-        <p className="py-4 text-sm text-gray-500">No {inline.label.toLowerCase()} yet.</p>
-      </Card>
-    );
+    return <CollapsedEmptyInline label={inline.label} />;
   }
 
   // Per-row link to the child's own change page (#384 — Django's

frontend/apps/web/src/pages/ListPage.tsx

@@ -29,6 +29,7 @@ import {
   Pagination,
   Popover,
   RecordCardList,
+  ResetButton,
   Table,
   useMediaQuery,
 } from '@dar/ui';
@@ -579,23 +580,23 @@ export function ListPage() {
           ) : null
         }
         trailing={
-          // Filter-row trailing slot (#554): "Clear all" (only when at
-          // least one filter is selected — nothing to clear, no button)
-          // and "Customize" (always visible — it's the column-customizer
-          // affordance, independent of filter state) as the last two
-          // buttons on the row, in that order.
+          // Filter-row trailing slot (#554): "Clear all" + "Customize"
+          // as the last two buttons on the row, in that order.
+          // "Clear all" is the shared <ResetButton> primitive from
+          // @dar/ui (#590) — same component the Layout modal uses for
+          // its "Reset" affordance, with the label + icon overridden
+          // for filter-row muscle memory. Renders disabled (not
+          // hidden) when no filters are applied so the affordance
+          // stays discoverable.
           <>
-            {activeFilterCount > 0 && (
-              <button
-                type="button"
-                onClick={() => patchParams((next) => filters.forEach((f) => next.delete(f.name)))}
-                title="Clear all filters"
-                className="inline-flex shrink-0 items-center gap-1.5 rounded-md border border-gray-300 px-3 py-1.5 text-sm hover:bg-gray-100"
-              >
-                <X className="h-4 w-4" aria-hidden />
-                Clear all
-              </button>
-            )}
+            <ResetButton
+              isDirty={activeFilterCount > 0}
+              onReset={() => patchParams((next) => filters.forEach((f) => next.delete(f.name)))}
+              label="Clear all"
+              disabledHint="No filters applied"
+              icon={<X className="h-4 w-4" aria-hidden />}
+              title="Clear all filters"
+            />
             <button
               type="button"
               onClick={() => setColsOpen(true)}
@@ -792,6 +793,23 @@ export function ListPage() {
             visibleColumnCount={visibleColumnCount}
             onToggle={toggleColumn}
             onReorder={setColOrder}
+            // The layout is "customised" when either preference has
+            // any state — a non-empty saved order or any hidden col.
+            // Both persist via localStorage (`dar:colorder:v1:*` and
+            // the columnsKey set); resetting drops both back to the
+            // empty / default state so the ModelAdmin's registered
+            // order + visibility take over again on the next render
+            // (#590).
+            isCustomised={colOrder.length > 0 || hiddenCols.size > 0}
+            onReset={() => {
+              // `usePersistedSet`'s setter takes a functional updater,
+              // not the raw next-value (unlike `useState`); returning a
+              // fresh empty Set clears every saved-hidden entry. The
+              // `colOrder` setter from `usePersistedState` is the
+              // plain useState variant, so it accepts the raw next.
+              setColOrder([]);
+              setHiddenCols(() => new Set<string>());
+            }}
           />
         </Suspense>
       )}

frontend/packages/ui/src/ResetButton.tsx

@@ -0,0 +1,100 @@
+// ResetButton (#590) — shared "return to defaults" affordance for the
+// list-page filter row ("Clear all") and the Column-Layout modal
+// ("Reset"). Both call sites want the same UX primitive: a ghost-styled
+// button with optional leading icon, a pending state, and a disabled
+// tooltip when there is nothing to reset.
+//
+// Lives in @dar/ui so future "reset" surfaces (saved searches, sidebar
+// customizations, etc.) inherit the same visual + a11y contract by
+// construction. The label and icon are configurable per call site so
+// the filter row can keep saying "Clear all" with the `X` icon while
+// the modal says "Reset" with the curved-arrow icon.
+//
+// Icon-agnostic: callers pass the icon node themselves so @dar/ui
+// stays free of an icon-library dep (matches the rest of the package).
+
+import { cloneElement, isValidElement, useState, type ReactNode } from 'react';
+
+export interface ResetButtonProps {
+  /** Is the underlying state actually customised? Disables the button
+   *  with a tooltip when false so the affordance stays discoverable. */
+  isDirty: boolean;
+  /** Run the reset. Promise-returning calls show a pending state; a
+   *  synchronous return runs through the same code path and the
+   *  finally branch flushes instantly. */
+  onReset: () => Promise<void> | void;
+  /** Visible label. Default "Reset". */
+  label?: string;
+  /** Tooltip shown when `isDirty` is false. */
+  disabledHint?: string;
+  /** Leading icon. If a React element that takes `className`, the
+   *  button passes `animate-spin` while a promise-returning onReset
+   *  is in flight (the lucide convention). Pass `null` to opt out. */
+  icon?: ReactNode;
+  /** Extra classes — kept narrow so the visual contract stays uniform. */
+  className?: string;
+  /** `title` for the trigger button when enabled. */
+  title?: string;
+  /** Optional content rendered after the label (e.g. a count chip). */
+  trailing?: ReactNode;
+}
+
+export function ResetButton({
+  isDirty,
+  onReset,
+  label = 'Reset',
+  disabledHint = 'Already at default',
+  icon = null,
+  className,
+  title,
+  trailing,
+}: ResetButtonProps) {
+  const [pending, setPending] = useState(false);
+  const disabled = !isDirty || pending;
+
+  async function run(): Promise<void> {
+    if (disabled) return;
+    setPending(true);
+    try {
+      await onReset();
+    } finally {
+      setPending(false);
+    }
+  }
+
+  const tooltip = disabled && !pending ? disabledHint : title;
+
+  // If the caller's icon is a valid element that accepts a `className`,
+  // augment it with `animate-spin` during a pending promise — the
+  // lucide-react / heroicons convention. Bail out for non-elements
+  // (strings, fragments, null).
+  const renderedIcon =
+    pending && isValidElement<{ className?: string }>(icon)
+      ? cloneElement(icon, {
+          className: `${icon.props.className ?? ''} animate-spin`.trim(),
+        })
+      : icon;
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        void run();
+      }}
+      disabled={disabled}
+      title={tooltip}
+      className={[
+        'inline-flex shrink-0 items-center gap-1.5 rounded-md border border-gray-300 px-3 py-1.5 text-sm',
+        disabled
+          ? 'cursor-not-allowed text-gray-400'
+          : 'text-gray-700 hover:bg-gray-100 hover:text-gray-900',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500',
+        className ?? '',
+      ].join(' ')}
+    >
+      {renderedIcon}
+      <span>{pending ? `${label}…` : label}</span>
+      {trailing}
+    </button>
+  );
+}

frontend/packages/ui/src/index.ts

@@ -45,3 +45,6 @@ export type { BreadcrumbItem, BreadcrumbProps } from './Breadcrumb';
 
 export { Popover } from './Popover';
 export type { PopoverProps } from './Popover';
+
+export { ResetButton } from './ResetButton';
+export type { ResetButtonProps } from './ResetButton';

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-admin-react"
-version = "1.3.0"
+version = "1.3.1"
 description = "A drop-in React single-page admin for Django, driven entirely by ModelAdmin."
 authors = ["django-admin-react contributors"]
 license = "MIT"