# Compound Component Pattern

## Objective

Let related parts of a component share state while the caller keeps control of the arrangement.

Groups of subcomponents that coordinate shared state internally while leaving structure and ordering to the call site.

## 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. Identify the components currently configured through long lists of props for their internal parts — a tabs component taking an array of labels, a dialog taking title, body, and footer as strings — and let the caller compose those parts instead.
2. Keep the shared state inside the group. Selection, open state, active index, and registration of the parts are the group's responsibility, and callers should not have to wire them together to get correct behaviour.
3. Support both a self-managing mode and a caller-controlled mode for the shared state, and make them mutually exclusive rather than allowing a half-controlled configuration that fights itself.
4. Give each subcomponent a clear error when it renders outside its group, naming the parent it requires. A part that silently renders inert because it found no shared state is very hard to diagnose from a screenshot.
5. Do not couple the parts by inspecting children, cloning them, or reaching for a particular position in the child list. That breaks the moment someone wraps a part in a conditional, a layout element, or a component of their own — which is exactly the flexibility this pattern exists to allow.

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

- A subcomponent rendered outside its required parent must fail with a message naming that parent rather than rendering as an inert element. Silence here produces a control that looks right and does nothing.
- Reordering or wrapping the parts must not break accessibility. The relationships that assistive technology relies on — which label belongs to which panel, which trigger controls which region — must be established through explicit association rather than through the order the parts happen to appear in.
- Shared state passed implicitly is easy to depend on by accident. Keep what the group provides deliberately small and documented, so a caller cannot end up relying on internals that change in the next release.
- Both a self-managing and a caller-controlled mode must be supported, and switching between them mid-life must be refused or handled explicitly rather than leaving two sources of truth disagreeing about which item is selected.
- Parts rendered conditionally, in a loop, or through an intermediate wrapper must still register with the group, so keyboard navigation and roving focus cover exactly the parts that are present.
- Nesting one group inside another — a menu within a menu, tabs within a panel — must resolve to the nearest enclosing group, not the outermost one.
- Duplicated or missing required parts, such as two panels claiming the same identifier or a trigger with no matching panel, need a development-time warning.

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

- [ ] Related components are composed at the call site rather than configured through arrays or slot-shaped prop lists.
- [ ] Shared state is owned by the group, and callers get correct behaviour without wiring it themselves.
- [ ] A subcomponent used outside its parent raises an error naming the required parent.
- [ ] Self-managing and caller-controlled modes are both supported and cannot be mixed.
- [ ] Wrapping, reordering, or conditionally rendering the parts leaves accessibility relationships intact.
- [ ] The group's implementation never inspects, clones, or indexes into its children.
- [ ] Nested groups resolve to the nearest enclosing parent.
- [ ] 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.