# Table Action Column Pattern

## Objective

Put row actions in one predictable place and reveal them the same way everywhere.

A single convention for where row-level actions sit in a table, which ones are always visible, and which collapse into an overflow menu.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Inventory every table in the app and list the row-level actions each one offers today. Group them into a small shared set — the one or two the user reaches for constantly, and the long tail that belongs behind an overflow control.
2. Fix the action column to one edge of the row and keep it there in every table, at a fixed width that does not change with the contents of the row. A column that drifts by a few pixels between tables costs the user a re-scan on every screen.
3. Make the actions reachable by keyboard: the row's controls must be in tab order in visual order, the overflow menu must open on Enter or Space, and arrow keys must move within the menu without leaving the table.
4. Reserve the space for actions the current user cannot perform rather than removing the cell, so rows stay aligned when permissions differ between records in the same table.
5. Do not reveal actions only on hover. Hover-only controls are invisible on touch, invisible to keyboard users until focus lands, and invisible to anyone scanning a screenshot; hover may emphasise, but it must not be the only way to find them.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- The one or two actions people use most must be visible without opening anything. Burying edit or delete under an overflow menu turns a one-click task into three.
- Touch has no hover and no focus ring, so the pattern must be usable by tapping alone, with hit areas that do not overlap the row's own tap target.
- An overflow menu opening near the bottom or right edge of a scroll container will be clipped by the container's overflow, so the menu must escape its ancestor or flip to the opposite side.
- When some rows allow an action and others do not, the columns must still line up. Disabled with an explanation is usually better than absent.
- Tapping or clicking an action must not also trigger the row's own click behaviour, such as opening the record.
- Destructive actions in the row need the same confirmation as they have elsewhere, and must not sit adjacent to a harmless action in the visible set.
- The action column must survive horizontal scrolling on narrow screens — either pinned to the edge or moved somewhere deliberate, never left floating off-screen.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Every table places row actions in the same position, at the same width.
- [ ] The primary actions are visible without hover, focus, or a menu.
- [ ] All row actions are reachable and operable by keyboard alone, in visual order.
- [ ] An open overflow menu is fully visible regardless of the row's position in a scrolling container.
- [ ] Rows the user cannot act on keep the column's alignment.
- [ ] Triggering a row action never also activates the row's navigation.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.