grocery-app/docs/guides/management-modal-patterns.md

Management Modal Patterns

Use this guide for modals that manage scoped lists of app-owned records, such as store items, store zones, and store locations.

Current adopters:

• Store item catalog management.
• Store location management.
• Store location zone management.

Purpose

• Management modals should keep users in the current workflow while they inspect, edit, add, or remove records for a scoped parent.
• The parent scope must be obvious in the title, for example Costco Items.
• Modals should avoid repeating table labels inside every row. Use row layout, grouping, and the edit surface for detail.

Structure

• Header: title, one short description when the scope is not obvious, and a close button.
• Primary toolbar: search input plus the primary create action inline.
• Bulk toolbar: destructive or multi-select actions above the list, separate from search/create controls.
• List: compact rows with the record's primary identity and any essential visual affordance.
• Editor: clicking or tapping a row opens the edit/settings modal for that record.
• Confirmation: destructive actions must use ConfirmSlideModal, not browser dialogs.

Row Behavior

• Normal mode: the entire row opens settings for that record.
• Delete mode: the row toggles selected/unselected state and does not open settings.
• Selection state must be visible on the row and must not rely only on color.
• Avoid per-row action buttons when the same action applies to every row.

Bulk Delete Pattern

• Show a Delete Items button above the list for users with delete permission.
• Clicking Delete Items enters delete mode, clears any previous selection, and changes the button to Confirm Delete (#).
• Show a Cancel button while delete mode is active.
• Disable confirm while zero items are selected.
• Clicking confirm opens ConfirmSlideModal; only the slide confirmation performs the mutation.
• On success, exit delete mode, clear selection, refresh the list, and show a toast.
• On failure, keep the modal open and show a toast with the API error summary.

Permission Rules

• Keep authorization server-side. Client visibility only improves UX.
• Members can open item settings when the API allows them to manage item details.
• Delete controls should be shown only to owners/admins when deletion is admin-scoped.

Accessibility

• Modal containers should use dialog semantics when practical.
• Rows that perform actions should be keyboard reachable.
• Delete-mode rows should expose selected state with aria-pressed or an equivalent state.
• Buttons must have stable labels that describe the action in the current mode.