# Data Table Cell Primitives

## Objective

Render every kind of table cell the same way, wherever the table happens to be.

A shared set of cell renderers for numbers, dates, people, statuses, links, and row actions, used by every table in the app.

## 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. Catalogue the cell types the app's tables already render and reduce them to a small set: number and currency, date and relative time, person or avatar, status or badge, link or identifier, and an actions cell.
2. Separate each cell's underlying value from its presentation, so sorting, filtering, grouping, and export operate on the raw value while the user sees the formatted one.
3. Align and format numerically consistent cells the same way everywhere — figures right-aligned with tabular figures and a fixed precision per column, dates in the user's locale and time zone, currency with its code where more than one is possible.
4. Give every cell type an explicit rendering for absent data, for the loading state, and for a value the current user is not permitted to see, and make those three visually distinct from one another.
5. Do not put more than one focusable control in a cell without deciding how it is reached. An actions cell with three buttons multiplies the tab stops in a hundred-row table; expose one primary control and put the rest behind a single menu, and leave header pinning to Sticky Table Header rather than adding a second scroll mechanism here.

## 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

- Sorting on the displayed string rather than the underlying value puts ten before nine and orders dates alphabetically; every cell must carry a sort value distinct from its label, and relative times must sort on the real timestamp.
- Absent, still loading, and redacted are three different states and must not collapse into one dash. A blank where the user lacks permission reads as no data and leads people to draw the wrong conclusion from the table.
- Cells must stay readable when compact. Truncate with a clear affordance and the full value available on hover and focus, keep it to one line, and make sure the truncation happens on the text rather than clipping the whole cell.
- Row-level keyboard navigation breaks when cells add their own arrow key handling or insert extra tab stops; cell contents must cooperate with the table's existing focus model rather than compete with it.
- Zero, null, and empty string are different values and each needs its own treatment — a zero balance is a fact, an unknown balance is not.
- Long free text and long identifiers must not set the column width; give each cell type a sensible maximum and let the column keep its share.
- Numbers rendered for display must round consistently with what the app exports, or a user reconciling a downloaded file against the screen will find figures that do not agree.

## 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 in the app renders its cells through the shared primitives.
- [ ] Sorting, filtering, and export use the raw value, never the formatted string.
- [ ] Numbers are right-aligned with consistent precision, and dates respect the user's locale and time zone.
- [ ] Missing, loading, and redacted values are visually and textually distinct.
- [ ] Each row contributes a predictable number of tab stops regardless of how many actions it has.
- [ ] Truncated cells expose their full value on hover and on focus.
- [ ] Displayed and exported values agree to the same precision.
- [ ] 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.