administratum 0.2.4 → 0.3.0

data/app/assets/javascripts/administratum.js

@@ -1,5 +1,5 @@
-// Administratum runtime: islands, offcanvas panels, dropdowns, confirmations,
-// flash messages and the light/dark toggle. Plain ES module, no dependencies.
+// Administratum runtime: islands, offcanvas panels, dropdowns, comboboxes,
+// sortable lists, confirmations, flash messages and the light/dark toggle. Plain ES module, no dependencies.
 // Behaviour is attached with event delegation, so it survives Turbo page swaps.
 
 function install() {
@@ -139,6 +139,420 @@ function scheduleFlashDismissal(root = document) {
   })
 }
 
+// -------------------------------------------------------------- comboboxes --
+
+// <select data-adm-combobox> becomes a type-to-filter input. The select stays
+// in the form (visually hidden) and keeps submitting its param. With
+// data-adm-combobox-url, options come from a JSON search endpoint instead:
+// GET url?q=… returning [{ id, label, group }].
+
+const COMBOBOX_SELECTOR = "select[data-adm-combobox]:not([multiple])"
+const comboboxes = new WeakSet()
+let comboboxCount = 0
+
+// Case- and accent-insensitive matching: "Ange" finds "Ängel".
+function fold(text) {
+  return text.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase()
+}
+
+function enhanceComboboxes(root = document) {
+  root.querySelectorAll(COMBOBOX_SELECTOR).forEach((select) => {
+    if (comboboxes.has(select)) return
+    // A Turbo snapshot restores the input without its listeners: rebuild it.
+    const stale = select.previousElementSibling
+    if (stale && stale.matches("[data-adm-combobox-wrapper]")) stale.remove()
+    comboboxes.add(select)
+    createCombobox(select)
+  })
+}
+
+function createCombobox(select) {
+  const id = `adm-combobox-${++comboboxCount}`
+  const data = select.dataset
+  const url = data.admComboboxUrl
+  const minLength = Number(data.admComboboxMin || (url ? 2 : 0))
+  const texts = {
+    empty: data.admComboboxEmpty || "No matches",
+    loading: data.admComboboxLoading || "Searching…",
+    short: (data.admComboboxShort || "Type at least %{count} characters").replace("%{count}", minLength),
+    error: data.admComboboxError || "Search failed"
+  }
+
+  const wrapper = document.createElement("div")
+  wrapper.className = "adm-combobox"
+  wrapper.dataset.admComboboxWrapper = ""
+  const input = document.createElement("input")
+  input.type = "text"
+  input.className = "adm-input adm-combobox-input"
+  input.autocomplete = "off"
+  input.spellcheck = false
+  input.disabled = select.disabled
+  input.setAttribute("role", "combobox")
+  input.setAttribute("aria-autocomplete", "list")
+  input.setAttribute("aria-expanded", "false")
+  input.setAttribute("aria-controls", `${id}-listbox`)
+  const describedBy = select.getAttribute("aria-describedby")
+  if (describedBy) input.setAttribute("aria-describedby", describedBy)
+  const blank = select.querySelector('option[value=""]')
+  if (blank && blank.textContent.trim()) input.placeholder = blank.textContent.trim()
+  const listbox = document.createElement("div")
+  listbox.id = `${id}-listbox`
+  listbox.className = "adm-combobox-listbox"
+  listbox.setAttribute("role", "listbox")
+  listbox.hidden = true
+  wrapper.append(input, listbox)
+  select.before(wrapper)
+
+  select.classList.add("adm-sr-only")
+  select.tabIndex = -1
+  select.setAttribute("aria-hidden", "true")
+  const label = select.id && document.querySelector(`label[for="${CSS.escape(select.id)}"]`)
+  if (label) {
+    label.id ||= `${id}-label`
+    input.setAttribute("aria-labelledby", label.id)
+    label.addEventListener("click", (event) => {
+      event.preventDefault()
+      input.focus()
+    })
+  }
+
+  let results = []
+  let active = -1
+  let typed = false
+  let timer = null
+  let controller = null
+
+  const displayText = () => {
+    const option = select.selectedOptions[0]
+    return option && option.value !== "" ? option.textContent.trim() : ""
+  }
+
+  const localOptions = () => Array.from(select.options)
+    .filter((option) => option.value !== "" && !option.disabled)
+    .map((option) => ({
+      value: option.value,
+      label: option.textContent.trim(),
+      group: option.parentElement instanceof HTMLOptGroupElement ? option.parentElement.label : ""
+    }))
+
+  // Every typed word must appear in the option's label or its group's label.
+  const filterLocal = (query) => {
+    const terms = fold(query).split(/\s+/).filter(Boolean)
+    return localOptions().filter((option) => {
+      const haystack = fold(`${option.group} ${option.label}`)
+      return terms.every((term) => haystack.includes(term))
+    })
+  }
+
+  function setActive(index) {
+    listbox.querySelector(".adm-combobox-option-active")?.classList.remove("adm-combobox-option-active")
+    active = index
+    const option = index >= 0 ? document.getElementById(`${id}-option-${index}`) : null
+    if (!option) {
+      input.removeAttribute("aria-activedescendant")
+      return
+    }
+    option.classList.add("adm-combobox-option-active")
+    input.setAttribute("aria-activedescendant", option.id)
+    option.scrollIntoView({ block: "nearest" })
+  }
+
+  function render(message) {
+    listbox.replaceChildren()
+    if (message) {
+      const note = document.createElement("div")
+      note.className = "adm-combobox-empty"
+      note.textContent = message
+      listbox.append(note)
+    }
+    let group = ""
+    let container = listbox
+    results.forEach((item, index) => {
+      if (item.group !== group) {
+        group = item.group
+        container = listbox
+        if (group) {
+          container = document.createElement("div")
+          container.setAttribute("role", "group")
+          container.setAttribute("aria-labelledby", `${id}-group-${index}`)
+          const heading = document.createElement("div")
+          heading.id = `${id}-group-${index}`
+          heading.className = "adm-combobox-group"
+          heading.setAttribute("role", "presentation")
+          heading.textContent = group
+          container.append(heading)
+          listbox.append(container)
+        }
+      }
+      const option = document.createElement("div")
+      option.id = `${id}-option-${index}`
+      option.className = "adm-combobox-option"
+      option.setAttribute("role", "option")
+      option.setAttribute("aria-selected", String(item.value === select.value))
+      option.dataset.index = index
+      option.textContent = item.label
+      container.append(option)
+    })
+    const selected = results.findIndex((item) => item.value === select.value)
+    setActive(results.length ? Math.max(selected, 0) : -1)
+  }
+
+  function show() {
+    listbox.hidden = false
+    input.setAttribute("aria-expanded", "true")
+  }
+
+  function hide() {
+    clearTimeout(timer)
+    controller?.abort()
+    listbox.hidden = true
+    input.setAttribute("aria-expanded", "false")
+    setActive(-1)
+  }
+
+  async function search(query) {
+    controller?.abort()
+    controller = new AbortController()
+    const target = new URL(url, window.location.href)
+    target.searchParams.set("q", query)
+    try {
+      const response = await fetch(target, { headers: { Accept: "application/json" }, credentials: "same-origin", signal: controller.signal })
+      if (!response.ok) throw new Error(`HTTP ${response.status}`)
+      const items = await response.json()
+      results = items.map((item) => ({ value: String(item.id), label: String(item.label ?? item.id), group: item.group ? String(item.group) : "" }))
+      render(results.length ? null : texts.empty)
+    } catch (error) {
+      if (error.name === "AbortError") return
+      console.error("[administratum] combobox search failed", error)
+      results = []
+      render(texts.error)
+    }
+  }
+
+  // Until the viewer types, the input shows the current choice and the list shows everything.
+  function update() {
+    const query = typed ? input.value.trim() : ""
+    show()
+    if (!url) {
+      results = query ? filterLocal(query) : localOptions()
+      render(results.length ? null : texts.empty)
+    } else if (query.length < minLength) {
+      results = []
+      render(texts.short)
+    } else {
+      clearTimeout(timer)
+      results = []
+      render(texts.loading)
+      timer = setTimeout(() => search(query), 250)
+    }
+  }
+
+  function choose(value, text) {
+    let option = Array.from(select.options).find((candidate) => candidate.value === value)
+    if (!option) {
+      option = new Option(text, value)
+      select.add(option)
+    }
+    if (select.value !== value) {
+      select.value = value
+      select.dispatchEvent(new Event("input", { bubbles: true }))
+      select.dispatchEvent(new Event("change", { bubbles: true }))
+    }
+    input.setCustomValidity("")
+    revert()
+  }
+
+  function revert() {
+    typed = false
+    input.value = displayText()
+  }
+
+  function move(delta) {
+    if (!results.length) return
+    setActive(Math.min(Math.max(active + delta, 0), results.length - 1))
+  }
+
+  revert()
+
+  input.addEventListener("input", () => {
+    typed = true
+    input.setCustomValidity("")
+    update()
+  })
+  input.addEventListener("click", () => {
+    if (listbox.hidden) update()
+  })
+  input.addEventListener("keydown", (event) => {
+    const open = !listbox.hidden
+    switch (event.key) {
+      case "ArrowDown":
+      case "ArrowUp":
+        event.preventDefault()
+        if (!open) update()
+        else if (!event.altKey) move(event.key === "ArrowDown" ? 1 : -1)
+        break
+      case "Enter":
+        if (!open) return
+        event.preventDefault()
+        if (results[active]) choose(results[active].value, results[active].label)
+        hide()
+        break
+      // Escape closes the list (or undoes typing) before it closes a panel.
+      case "Escape":
+        if (!open && !typed) return
+        event.preventDefault()
+        hide()
+        revert()
+        break
+    }
+  })
+  // Clearing the text and leaving picks the blank option, when there is one.
+  input.addEventListener("blur", () => {
+    hide()
+    if (typed && input.value.trim() === "" && blank) choose("", "")
+    else revert()
+  })
+  listbox.addEventListener("mousedown", (event) => event.preventDefault())
+  listbox.addEventListener("click", (event) => {
+    const option = event.target instanceof Element ? event.target.closest('[role="option"]') : null
+    if (!option) return
+    const item = results[Number(option.dataset.index)]
+    choose(item.value, item.label)
+    hide()
+  })
+  // Label clicks and panel autofocus land on the hidden select: pass focus on.
+  select.addEventListener("focus", () => input.focus())
+  select.addEventListener("change", () => {
+    if (document.activeElement !== input) revert()
+  })
+  // The browser can't point at a hidden select, so report on the input.
+  select.addEventListener("invalid", (event) => {
+    event.preventDefault()
+    input.setCustomValidity(select.validationMessage)
+    input.reportValidity()
+  })
+}
+
+// --------------------------------------------------------------- sortables --
+
+// [data-adm-sortable] holds [data-adm-sortable-item] children, each with the
+// controls from reorder_controls. Without JS those are position number fields;
+// with it, drag handles and move up/down buttons that renumber the fields.
+
+const sortables = new WeakSet()
+let drag = null
+let liveRegion = null
+
+function sortableItems(list) {
+  return Array.from(list.children).filter((child) => child.matches("[data-adm-sortable-item]"))
+}
+
+function enhanceSortables(root = document) {
+  root.querySelectorAll("[data-adm-sortable]").forEach((list) => {
+    if (sortables.has(list)) return
+    sortables.add(list)
+    list.querySelectorAll("[data-adm-sortable-handle], [data-adm-sortable-up], [data-adm-sortable-down]").forEach((el) => { el.hidden = false })
+    list.querySelectorAll("[data-adm-sortable-fallback]").forEach((el) => { el.hidden = true })
+    refreshSortable(list)
+  })
+}
+
+function refreshSortable(list) {
+  const items = sortableItems(list)
+  items.forEach((item, index) => {
+    const position = item.querySelector("[data-adm-sortable-position]")
+    if (position) position.value = index + 1
+    const up = item.querySelector("[data-adm-sortable-up]")
+    if (up) up.disabled = index === 0
+    const down = item.querySelector("[data-adm-sortable-down]")
+    if (down) down.disabled = index === items.length - 1
+  })
+}
+
+function announceMove(list, item) {
+  if (!liveRegion || !liveRegion.isConnected) {
+    liveRegion = document.createElement("div")
+    liveRegion.className = "adm-sr-only"
+    liveRegion.setAttribute("aria-live", "polite")
+    document.body.append(liveRegion)
+  }
+  const items = sortableItems(list)
+  const template = item.querySelector("[data-adm-sortable-moved]")?.dataset.admSortableMoved || "Moved to position %{position} of %{count}"
+  liveRegion.textContent = template.replace("%{position}", items.indexOf(item) + 1).replace("%{count}", items.length)
+}
+
+function sortableItemFor(control) {
+  const item = control.closest("[data-adm-sortable-item]")
+  return item && sortables.has(item.parentElement) ? item : null
+}
+
+// Moves an item one step and keeps focus on the control that moved it, or on
+// its opposite button once it reaches the end of the list.
+function moveSortable(item, delta, control) {
+  const list = item.parentElement
+  const items = sortableItems(list)
+  const target = items[items.indexOf(item) + delta]
+  if (!target) return
+  if (delta < 0) target.before(item)
+  else target.after(item)
+  refreshSortable(list)
+  const fallback = item.querySelector(delta < 0 ? "[data-adm-sortable-down]" : "[data-adm-sortable-up]")
+  ;(control.disabled ? fallback : control)?.focus()
+  announceMove(list, item)
+}
+
+document.addEventListener("keydown", (event) => {
+  if (event.key !== "ArrowUp" && event.key !== "ArrowDown") return
+  const handle = event.target instanceof Element ? event.target.closest("[data-adm-sortable-handle]") : null
+  const item = handle && sortableItemFor(handle)
+  if (!item) return
+  event.preventDefault()
+  moveSortable(item, event.key === "ArrowUp" ? -1 : 1, handle)
+})
+
+document.addEventListener("pointerdown", (event) => {
+  if (event.button !== 0) return
+  const handle = event.target instanceof Element ? event.target.closest("[data-adm-sortable-handle]") : null
+  const item = handle && sortableItemFor(handle)
+  if (!item) return
+  event.preventDefault()
+  handle.setPointerCapture(event.pointerId)
+  item.classList.add("adm-sortable-dragging")
+  drag = { item, list: item.parentElement }
+})
+
+// The dragged item goes just before the first other item whose midpoint is
+// below the pointer, or last when there is none.
+document.addEventListener("pointermove", (event) => {
+  if (!drag) return
+  const { item, list } = drag
+  const items = sortableItems(list)
+  const others = items.filter((other) => other !== item)
+  const next = others.find((other) => {
+    const rect = other.getBoundingClientRect()
+    return event.clientY < rect.top + rect.height / 2
+  })
+  const current = items[items.indexOf(item) + 1]
+  if (next === current) return
+  if (next) next.before(item)
+  else others.at(-1)?.after(item)
+  refreshSortable(list)
+})
+
+function endDrag() {
+  if (!drag) return
+  drag.item.classList.remove("adm-sortable-dragging")
+  announceMove(drag.list, drag.item)
+  drag = null
+}
+document.addEventListener("pointerup", endDrag)
+document.addEventListener("pointercancel", endDrag)
+
+function enhance(root = document) {
+  enhanceComboboxes(root)
+  enhanceSortables(root)
+}
+
 // ------------------------------------------------------------------ events --
 
 document.addEventListener("click", (event) => {
@@ -158,6 +572,13 @@ document.addEventListener("click", (event) => {
     return
   }
 
+  const mover = target.closest("[data-adm-sortable-up], [data-adm-sortable-down]")
+  const moved = mover && sortableItemFor(mover)
+  if (moved) {
+    moveSortable(moved, mover.matches("[data-adm-sortable-up]") ? -1 : 1, mover)
+    return
+  }
+
   const dropdownToggle = target.closest("[data-adm-dropdown-toggle]")
   if (dropdownToggle) {
     const dropdown = dropdownToggle.closest("[data-adm-dropdown]")
@@ -189,8 +610,9 @@ document.addEventListener("click", (event) => {
   if (dismiss) dismiss.parentElement.remove()
 })
 
+// A control that handled Escape itself (an open combobox) prevents the default.
 document.addEventListener("keydown", (event) => {
-  if (event.key !== "Escape") return
+  if (event.key !== "Escape" || event.defaultPrevented) return
   closePanels()
   closeDropdowns()
 })
@@ -208,11 +630,13 @@ document.addEventListener("submit", (event) => {
 
 function boot() {
   mountIslands()
+  enhance()
   scheduleFlashDismissal()
 }
 
 document.addEventListener("DOMContentLoaded", boot)
 document.addEventListener("turbo:load", boot)
+document.addEventListener("turbo:frame-load", (event) => enhance(event.target))
 document.addEventListener("turbo:before-render", () => {
   closePanels()
   unmountIslands()
@@ -233,6 +657,8 @@ Administratum.islands = {
 Administratum.csrfToken = () => document.querySelector('meta[name="csrf-token"]')?.content
 Administratum.openPanel = openPanel
 Administratum.closePanels = closePanels
+// Enhances comboboxes and sortable lists in HTML inserted after page load.
+Administratum.enhance = enhance
 
 window.Administratum = Administratum
 

data/app/assets/tailwind/administratum/components.css

@@ -142,8 +142,10 @@
   select[multiple].adm-input { @apply py-1.5; }
   /* Safari ignores padding and height on natively styled selects, so draw
      our own: no native appearance, and a chevron made of two token-coloured
-     gradients (a data-URI SVG would need a hard-coded colour). */
-  select.adm-input:not([multiple]) {
+     gradients (a data-URI SVG would need a hard-coded colour). Searchable
+     selects get the same chevron. */
+  select.adm-input:not([multiple]),
+  .adm-combobox-input {
     @apply appearance-none bg-no-repeat pr-9;
     background-image:
       linear-gradient(45deg, transparent 50%, var(--color-adm-muted) 50%),
@@ -158,16 +160,47 @@
   .adm-form-actions {
     @apply flex flex-wrap items-center gap-2 border-t border-adm-border bg-adm-surface-muted px-6 py-4 sm:pl-[16.5rem];
   }
+  /* Searchable select: administratum.js builds these around select[data-adm-combobox]. */
+  .adm-combobox { @apply relative; }
+  .adm-combobox-listbox {
+    @apply absolute inset-x-0 top-full z-30 mt-1 max-h-72 overflow-y-auto rounded-adm border border-adm-border bg-adm-surface py-1 shadow-lg;
+  }
+  .adm-combobox-group { @apply px-3.5 pt-2.5 pb-1 text-xs font-semibold tracking-wide text-adm-muted uppercase; }
+  .adm-combobox-option { @apply cursor-pointer px-3.5 py-1.5 text-adm-text; }
+  .adm-combobox-option[aria-selected="true"] { @apply font-semibold; }
+  .adm-combobox-option-active,
+  .adm-combobox-option:hover { @apply bg-adm-surface-muted; }
+  .adm-combobox-option-active { @apply shadow-[inset_2px_0_0_var(--color-adm-primary)]; }
+  .adm-combobox-empty { @apply px-3.5 py-2 text-adm-muted; }
+
+  /* Reorder controls (reorder_controls helper). */
+  .adm-sortable-controls { @apply inline-flex items-center gap-1; }
+  .adm-sortable-handle { @apply cursor-grab touch-none; }
+  .adm-sortable-controls .adm-icon-btn:disabled { @apply cursor-not-allowed opacity-40 hover:bg-transparent; }
+  .adm-sortable-position { @apply w-20; }
+  .adm-sortable-dragging { @apply relative z-10 opacity-80 shadow-lg; }
+  .adm-sortable-dragging > td { @apply bg-adm-surface-muted; }
+
   .adm-check { @apply flex items-center gap-2 text-adm-text; }
   .adm-code { @apply font-adm-mono text-xs; }
   .adm-form-footer { @apply flex flex-wrap items-center gap-2; }
 
+  /* Plain adm-alert is danger, as it always was; the variants restyle it.
+     Status tints stay at 10% so their text keeps 4.5:1 (see theme.css). */
   .adm-alert { @apply rounded-adm border border-adm-danger/40 bg-adm-danger/10 px-4 py-3 text-adm-text; }
   .adm-alert-title { @apply mb-1 font-semibold text-adm-danger; }
   .adm-alert ul { @apply list-disc pl-5; }
+  .adm-alert-danger { @apply border-adm-danger/40 bg-adm-danger/10; }
+  .adm-alert-danger .adm-alert-title { @apply text-adm-danger; }
+  .adm-alert-warning { @apply border-adm-warning/40 bg-adm-warning/10; }
+  .adm-alert-warning .adm-alert-title { @apply text-adm-warning; }
+  .adm-alert-info { @apply border-adm-border bg-adm-surface-muted; }
+  .adm-alert-info .adm-alert-title { @apply text-adm-text; }
 
   .adm-badge { @apply inline-flex items-center rounded-full bg-adm-surface-muted px-2 py-0.5 text-xs font-medium text-adm-muted; }
-  .adm-badge-success { @apply bg-adm-success/15 text-adm-success; }
+  .adm-badge-success { @apply bg-adm-success/10 text-adm-success; }
+  .adm-badge-warning { @apply bg-adm-warning/10 text-adm-warning; }
+  .adm-badge-danger { @apply bg-adm-danger/10 text-adm-danger; }
 
   /* Offcanvas panels ------------------------------------------------------ */
   .adm-offcanvas { @apply fixed inset-0 z-40; }

data/app/assets/tailwind/administratum/theme.css

@@ -14,10 +14,12 @@
   --color-adm-muted: oklch(0.52 0.02 260);
   --color-adm-primary: oklch(0.52 0.18 262);
   --color-adm-primary-fg: oklch(0.99 0 0);
-  --color-adm-danger: oklch(0.56 0.2 25);
+  /* Status colours are used as text on their own 10% tint, so each keeps at
+     least 4.5:1 against it (and against the surface) in both themes. */
+  --color-adm-danger: oklch(0.54 0.2 25);
   --color-adm-danger-fg: oklch(0.99 0 0);
-  --color-adm-success: oklch(0.58 0.14 155);
-  --color-adm-warning: oklch(0.75 0.15 75);
+  --color-adm-success: oklch(0.52 0.14 155);
+  --color-adm-warning: oklch(0.52 0.13 70);
   --color-adm-ring: oklch(0.52 0.18 262 / 0.35);
   --color-adm-overlay: oklch(0.2 0.02 260 / 0.45);
 
@@ -41,6 +43,10 @@
     --color-adm-muted: oklch(0.7 0.015 260);
     --color-adm-primary: oklch(0.68 0.15 262);
     --color-adm-primary-fg: oklch(0.16 0.02 260);
+    --color-adm-danger: oklch(0.8 0.13 25);
+    --color-adm-danger-fg: oklch(0.16 0.02 260);
+    --color-adm-success: oklch(0.78 0.14 155);
+    --color-adm-warning: oklch(0.82 0.14 80);
     --color-adm-ring: oklch(0.68 0.15 262 / 0.4);
     --color-adm-overlay: oklch(0.05 0 0 / 0.6);
   }
@@ -55,6 +61,10 @@
       --color-adm-muted: oklch(0.7 0.015 260);
       --color-adm-primary: oklch(0.68 0.15 262);
       --color-adm-primary-fg: oklch(0.16 0.02 260);
+      --color-adm-danger: oklch(0.8 0.13 25);
+      --color-adm-danger-fg: oklch(0.16 0.02 260);
+      --color-adm-success: oklch(0.78 0.14 155);
+      --color-adm-warning: oklch(0.82 0.14 80);
       --color-adm-ring: oklch(0.68 0.15 262 / 0.4);
       --color-adm-overlay: oklch(0.05 0 0 / 0.6);
     }

data/app/controllers/administratum/resource.rb

@@ -15,7 +15,7 @@ module Administratum
 
     helper_method :definition, :resource_class, :paths, :paths_for, :parent_record, :collection_path, :new_resource_path,
                   :resource_path, :edit_resource_path, :action_path, :resource_form_path, :parent_path, :current_index_scope,
-                  :index_scope_count
+                  :index_scope_count, :index_reorderable?
 
     def index
       collection = current_index_scope ? current_index_scope.apply(scoped_collection) : scoped_collection
@@ -59,6 +59,15 @@ module Administratum
       redirect_to after_destroy_path, notice: t("administratum.flash.destroyed", resource: resource_class.singular_label)
     end
 
+    # PATCH positions[id]=n, for resources declared `reorderable`.
+    def reorder
+      reorder_records!(scoped_collection, params.fetch(:positions, {}))
+      respond_to do |format|
+        format.html { redirect_back_or_to after_destroy_path, notice: t("administratum.flash.reordered", resources: resource_class.plural_label) }
+        format.json { head :no_content }
+      end
+    end
+
     # Resources defined in the host app live outside the engine's namespace,
     # so Rails hands them the host's url helpers. Point them back at the engine.
     def self.inherited(subclass)
@@ -113,6 +122,20 @@ module Administratum
       index_scope.apply(scoped_collection).ransack(params[:q], auth_object: :administratum).result.count
     end
 
+    # Reorder controls show on the index while it lists every record, sorted by the position column.
+    def index_reorderable?
+      column = definition.reorder_column
+      return false unless column && @pagy && @search
+
+      @search.sorts.map { |sort| [sort.name, sort.dir] } == [[column.to_s, "asc"]] &&
+        @pagy.count > 1 && @pagy.pages == 1 && @pagy.count == scoped_collection.count
+    end
+
+    # Renumbers `relation` from a positions[id]=n payload. See Administratum::Reorder.
+    def reorder_records!(relation, positions, column: definition.reorder_column || :position)
+      Administratum::Reorder.call(relation, positions, column:)
+    end
+
     def build_resource(attributes = {})
       @parent ? @parent.public_send(definition.parent.association).build(attributes) : model.new(attributes)
     end

data/app/helpers/administratum/application_helper.rb

@@ -7,5 +7,6 @@ module Administratum
     include Administratum::FormHelper
     include Administratum::ResourceHelper
     include Administratum::IslandHelper
+    include Administratum::ReorderHelper
   end
 end