Admin Shared Template Helper Requirements

Current status: planning and helper requirement reference. Do not treat proposed helper names on this page as available APIs until code inspection confirms them.

Related pages: Admin UI/Admin Cleanup Implementation Contract, Centralized Systems/Shared Admin List Behavior.

Purpose

This document records the shared Admin helper and template capabilities needed so addon developers can follow the Admin cleanup contract without copying local UI code.

It is a planning document, not a claim that every helper already exists.

Current Drift

The documentation now defines a strict Admin view contract, but the code may not yet provide every helper needed to make that contract effortless.

Until helpers exist, implementers must match the visible and behavioral contract manually.

When the same manual pattern appears in more than one addon, it should become shared Admin functionality.

Required Helper Areas

The shared Admin layer should provide helpers or templates for:

• shell mounting
• breadcrumbs
• task panels
• notices
• list toolbar
• row-count selector
• search input
• filters
• sortable headers
• pagination
• state markers
• empty states
• form panels
• form action rows
• modal frame
• fragment response framing
• return-state handling

Proposed Helper Names

Final names may change during code implementation, but the shared Admin layer should expose capabilities equivalent to:

• amv_admin_render_page
• amv_admin_render_breadcrumbs
• amv_admin_render_task_panel
• amv_admin_render_notice_stack
• amv_admin_render_list_toolbar
• amv_admin_render_per_page_select
• amv_admin_render_search_input
• amv_admin_render_filter_controls
• amv_admin_render_sort_header
• amv_admin_render_pagination
• amv_admin_render_state_marker
• amv_admin_render_empty_state
• amv_admin_render_form_panel
• amv_admin_render_form_actions
• amv_admin_render_modal_frame
• amv_admin_capture_list_state
• amv_admin_build_return_url

This list is intended to describe needed capabilities.

Do not document these names in the developer Wiki as existing APIs until the code actually provides them.

List State Helper Requirements

The shared list state helper should support:

• q
• page
• per_page
• sort
• dir
• filter keys
• stable per-list retained state
• return URLs from list to create/edit/detail
• preserved state after redirect-after-POST

The helper should avoid addon-local query names for normal list screens.

Toolbar Helper Requirements

The shared toolbar helper should render:

• left action group
• spacer
• row-count selector
• search input
• filter trigger when real filters exist

It should support disabled but visible normal workflow actions.

It should not force domain-specific actions into hardcoded Admin logic.

The addon should declare available actions; the shared helper should render them in the governed order.

Sort and Pagination Helper Requirements

Sort and pagination helpers must preserve list state.

Sort headers must use the shared fixed-width indicator.

Pagination must render below the table or empty state.

Changing search, row-count, or filters should return to page 1 unless a shared Admin rule says otherwise.

State Marker Helper Requirements

The state helper should accept a raw lifecycle value and render:

• capitalized human label
• Pages-style square marker
• governed color meaning
• accessible text label

It should not render pill badges, icons, raw lowercase values, or color-only states.

Notice Helper Requirements

The notice helper should:

• render success, warning, error, and info messages
• place notices below title/eyebrow and above toolbar/form body
• support simple success auto-clear around 10 seconds
• avoid disrupting toolbar layout

Form Helper Requirements

The form helper should support:

• compact panel structure
• grouped fields
• multi-column short fields where practical
• wide long-text/editor fields
• Advanced sections
• action rows
• cancel URLs that preserve list state

The helper must not own addon validation rules.

Modal Helper Requirements

The modal helper should own:

• overlay
• panel frame
• theme colors
• title placement
• close behavior
• spacing rhythm
• contrast

Addon content should mount inside the shared modal frame.

Wiki Readiness Rule

Before these helper names are added to the live developer Wiki as APIs, inspect the code and verify:

• helper exists
• accepted arguments are known
• return type is known
• expected escaping behavior is known
• examples match actual code

If the helper does not exist, the Wiki may document the intended rule and current limitation, but must not present the helper as available.

Final Rule

The Admin UI standard becomes easy for addon developers only when repeated UI mechanics are centralized.

Until then, documentation must clearly separate final intended rules from currently available helper APIs.