Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
54 commits
Select commit Hold shift + click to select a range
9b9d81a
ref: unify breadcrumbs and title slot in TopBar
TkDodo Oct 6, 2026
94ca48f
ref: unify title slot and breadcrumbs
TkDodo Oct 6, 2026
b8fd10d
fix: types
TkDodo Oct 6, 2026
58d0e93
replace help with labelTooltip
TkDodo Oct 6, 2026
081b59c
ref: move badge to leadingItems
TkDodo Oct 6, 2026
53aa164
remove href
TkDodo Oct 6, 2026
b762160
re-use select-projects
TkDodo Oct 6, 2026
9812261
move featureBadge to trailingActions
TkDodo Oct 6, 2026
13454a2
streamline feature badges
TkDodo Oct 6, 2026
495fc33
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 6, 2026
95a6ab0
remove status from topBar
TkDodo Oct 6, 2026
b55df61
remove unused linkLabel
TkDodo Oct 6, 2026
3d7bcc2
ref: update migrate-breadcrumb-list skill
TkDodo Oct 6, 2026
7840ad4
revert changes to editableText
TkDodo Oct 6, 2026
d34250f
replace pageHeadingQuestionTooltip with readTheDocs
TkDodo Oct 6, 2026
2a3ea62
inline children props
TkDodo Oct 6, 2026
9674e0b
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 6, 2026
158eff9
fix tests
TkDodo Oct 6, 2026
b29fd91
inline eventInputName
TkDodo Oct 6, 2026
2b2a7b9
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 6, 2026
e80e934
fix: only wrap the actual title in an h1, not everything around it
TkDodo Oct 6, 2026
a42f229
remove select from title-item
TkDodo Oct 6, 2026
7209ec3
fix some layout issues
TkDodo Oct 6, 2026
f43f318
fix: make sure editable title doesn't wrap everything in h1
TkDodo Oct 6, 2026
fb61152
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 6, 2026
0b2a8b9
typed items
TkDodo Oct 6, 2026
eb61b2d
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 6, 2026
c7f4da4
remove link, separate trigger
TkDodo Oct 6, 2026
a555371
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 6, 2026
b85b11c
export types
TkDodo Oct 6, 2026
dd3316d
type select
TkDodo Oct 6, 2026
45b77b5
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 6, 2026
6eba3e2
remove BreadcrumbContext
TkDodo Oct 6, 2026
56f08a3
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 6, 2026
4ef6f97
remove fallback boolean
TkDodo Oct 6, 2026
593aa8a
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 6, 2026
576da7d
simplify I guess
TkDodo Oct 6, 2026
abe2df6
move settingsBreadcrumb to routes
TkDodo Oct 6, 2026
5273b28
restore links on select
TkDodo Oct 7, 2026
9c99ec3
merge master
TkDodo Oct 7, 2026
72241b3
ref: do not pass title object syntax when unnecessary
TkDodo Oct 7, 2026
d2b16aa
integrationUrl field
TkDodo Oct 7, 2026
f4c6be6
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 7, 2026
dd1a4fd
better fallback
TkDodo Oct 7, 2026
aa5f9e3
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 7, 2026
89d0a10
fix tests
TkDodo Oct 7, 2026
a8f9501
fix test: badge is outside of h1
TkDodo Oct 7, 2026
47d6ca4
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 7, 2026
2058e42
include select in menu
TkDodo Oct 7, 2026
f8f07d9
Merge branch 'master' into tkdodo/ref/de-1599-topbar-breadcrumbs-title
TkDodo Oct 7, 2026
39293f4
ref: rename to DocumentationHint
TkDodo Oct 7, 2026
ae3ca23
update skills and docs
TkDodo Oct 7, 2026
caf9f50
merge master
TkDodo Oct 7, 2026
61f5dec
fix: import
TkDodo Oct 7, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
221 changes: 71 additions & 150 deletions .agents/skills/migrate-breadcrumb-list/SKILL.md

Large diffs are not rendered by default.

35 changes: 26 additions & 9 deletions .agents/skills/migrate-breadcrumb-list/SOURCES.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,18 @@

- `components/core/breadcrumbList/` — authoritative for the item unions and every prop. The types win over the story.
- `components/core/breadcrumbList/breadcrumbList.mdx` — authoritative for composition and editorial rules (copy-vs-menu, always-present pagination).
- `views/navigation/topBar.tsx` — slot names, and the `<Heading as="h1">` that makes the title outlet the page heading.
- `views/navigation/topBar.tsx` — slot names and title outlet layout; `components/core/breadcrumbList/` owns the heading markup.
- Reference migrations: getsentry/sentry#120729 (conversations), #120794 (trace view), #123128 (transaction summary), #121282 (dashboards actions), #123569 (replay actions). #122697 removed the migration flag; the earlier PRs' flag forks are dead patterns.
- Ten already-migrated call sites in `static/app/views/`, enumerated in `SKILL.md`.
- Current examples in `static/app/views/` are listed in `SKILL.md`; re-read them before adapting them.
- `tests/js/sentry-test/reactTestingLibrary.tsx` supplies TopBar slot outlets in the default test renderer.

## Decisions

- **Guidance is inline, not a component prop.** A `pageFilters` prop on `BreadcrumbItemLinkProps` was designed and rejected: four real call sites cannot express themselves in an enum (whole-query-minus-N keys, inheriting from an `EventView`, and a drawer-tab crumb that is not page navigation), and an escape hatch would defeat the forcing function. A `pageFilterQuery` helper was also built and dropped — at the converted call site its diff was equivalent to the spread it replaced.
- **Page-filter policy is treated as settled.** Whether a given crumb _should_ carry filters is a product decision. The skill teaches how to replicate existing behaviour, not how to choose.
- **`references/evidence/` was not created.** The two cold runs below are summarised here instead; their findings are already promoted into rules, and the skill has a defined end of life.

## Iteration
## Historical iteration

Two cold runs, each a fresh agent given only the skill and one target file, in an isolated worktree.

Expand All @@ -29,14 +30,30 @@ Run 2 also found a regression introduced by run 1's fix — the step 6 "add as s

## Gaps

- No cold run against Shape C, the hardest shape (`explore/components/breadcrumb.tsx`, four consumers with branch-dependent titles).
- The historical cold runs below have not been repeated against the current single-slot API.
- The overflow collapse cannot be tested in jsdom, so no run has exercised it.
- Reachability, not file counts, determines whether a call-site inconsistency is user-visible; the inventory records shapes but not reachability.
- Choosing the title on a Shape B or Shape C page is a judgement the skill can frame but not decide — it supplies a priority order and answer keys, not a rule.
- `select-projects` has no production consumer, so its guidance is untested by use.
- Choosing a title in mixed legacy or shared headers still requires inspecting the caller and its conditions.
- JSX element prop annotations do not enforce component identity. The documented `badge`/`button` element API remains in the implementation; the proposed props-only replacement has not been implemented.

## Current API correction

- Retained the existing migration scope and reference-backed workflow. This is an update of the existing skill, not a new skill or provider-specific workflow.
- Replaced public two-slot examples with one breadcrumbs slot and a required typed title. Removed the obsolete Layout.Title shim guidance.
- Documented rich labelTooltip content, trailing feature badges, and standard EditableText behavior. Restricted select to parent breadcrumbs. Removed guidance for unsupported title props.
- Corrected the claim that ReactElement<Props> restricts the JSX component. It does not.
- Replaced the stale test setup instructions using the current shared renderer, and removed guidance that would preserve tests solely for deleted decorations.
- Rebuilt the inventory from current imports. Removed already-migrated wrappers from the backlog and replaced fixed importer-count rules with inspection of remaining navigation needs.
- Sources for these corrections: the current breadcrumb item implementations, TopBar, `views/settings/components/settingsBreadcrumb/settingsBreadcrumbSelector.tsx` and `views/settings/components/settingsBreadcrumb/settingsBreadcrumbsProvider.tsx`, EditableIssueViewHeader, secondary navigation badge definitions, and the default React Testing Library renderer.
- Trigger checks: "migrate breadcrumbs", "replace sentry/components/breadcrumbs", and "preserve page filters during breadcrumb migration" should activate the skill. "Inspect event breadcrumbs", "add a CMDK group", and "redesign Settings routing" should not.
- Other skill references to breadcrumbs were checked. Container-query guidance remains valid; CMDK breadcrumb terminology and backend telemetry breadcrumbs are unrelated to this API.

## Maintenance

- Update `SKILL.md` when the item unions gain or lose a type, when a TopBar slot is added or renamed, or when a shape category stops matching what is left in the tree.
- Delete the `preservePageFilters` section once no legacy importer still passes the prop: `grep -rln "preservePageFilters: true" static/app --include='*.tsx'`.
- Prune `references/call-site-inventory.md` as rows land. **When it empties and the legacy-importer count reaches 4, delete this skill** — it exists to retire a migration, and outliving that migration is how it rots.
- Update the API map and examples when the title/item unions, action shapes, or public TopBar props change.
- Recheck the test renderer before prescribing providers or outlets.
- Rebuild the importer inventory after migrations; do not use a hard-coded count as a completion or deletion condition.
- Retire this migration skill only when the remaining references no longer include page-navigation work and required separate navigation landmarks are preserved.

- Restricted the breadcrumbs slot to typed `items` and `title`; removed arbitrary children. Migrated Settings route links and menus to the shared list, and documented external links and parent selectors.
- Settings parent ownership now follows the shared route layout: singular `handle.settingsBreadcrumb` entries from all matched routes compose in order and feed a downward-only context. Shared pathless routes avoid repeated parent entries. Pages retain their titles. Sources: `SettingsBreadcrumbsProvider`, `BreadcrumbTitle`, and the Settings route declarations and navigation tests. This replaces route-path reconstruction and the organization-prefix workaround.
Original file line number Diff line number Diff line change
@@ -1,110 +1,46 @@
# Call-site inventory
# Find migration work

Regenerate the classification rather than trusting a list — this migration's own PRs invalidate any table of paths. The hard rows below are the part that cannot be regenerated.
Regenerate the inventory before editing. A file can already use the typed title API while still rendering legacy parent breadcrumbs.

## Contents
## Search and classify

- [Classify](#classify)
- [Hard rows](#hard-rows)
- [Wrapper consumer map](#wrapper-consumer-map)

## Classify

```bash
cd "$(git rev-parse --show-toplevel)"
EXCLUDE='components/breadcrumbs.spec.tsx|events/eventDrawer.tsx|groupDistributionCrumbs.tsx'
for f in $(grep -rl "from 'sentry/components/breadcrumbs'" static/app | grep -Ev "$EXCLUDE" | sort); do
printf '%-70s jsx=%s h1=%s LT=%s titleSlot=%s styled=%s\n' "${f#static/app/}" \
"$(grep -c '<Breadcrumbs' "$f")" "$(grep -c 'as="h1"' "$f")" \
"$(grep -c 'Layout.Title' "$f")" "$(grep -c 'TopBar.Slot name="title"' "$f")" \
"$(grep -c 'styled(Breadcrumbs)' "$f")"
done
```

Read the fingerprint as:

| Fingerprint | Shape |
| --------------------------------------- | ------------------------------------------------------- |
| `titleSlot>0`, `LT=0`, `h1=0` | **A1** or **A2** — check what the slot's first child is |
| `LT>0` | **B** |
| `h1>0` | **E** |
| `titleSlot=0`, `jsx>0`, exported symbol | **C** — count consumers below |
| `jsx=0`, `styled=0` | the type-only adapter |
| `jsx=0`, `styled=1` | **A1** via a `styled(Breadcrumbs)` alias |

To separate A1 from A2, look at the element inside the slot. `<Breadcrumbs` or a JSX-valued variable is A1; a component name is A2 and the caller's slot must be deleted.
Prefer native code search. When unavailable:

```bash
f=static/app/views/automations/new.tsx
ln=$(grep -n 'TopBar.Slot name="title"' "$f" | head -1 | cut -d: -f1)
sed -n "$((ln+1))p" "$f"
rg -l "from 'sentry/components/breadcrumbs'" static/app static/gsApp
```

A file absent from the fingerprint output is already migrated. Do not re-add it.

## Hard rows

Four files cost far more than their fingerprint suggests.

### `views/performance/breadcrumb.tsx` — blocked, do last

Type-only, and it looks like a one-file delete. It is not. `getTabCrumbs()` returns `Crumb[]` that flows:

```
performance/breadcrumb.tsx getTabCrumbs()
→ performance/transactionSummary/header.tsx
→ {...headerProps}
→ insights/pages/{frontend,backend,mobile}/*PageHeader.tsx (3 shims)
→ insights/pages/domainViewHeader.tsx additionalBreadCrumbs?: Crumb[] ← public prop
```

Six files, three shapes. Deleting the adapter first breaks `header.tsx` and surfaces the chain at typecheck with no guidance on whether to expand scope or revert. Do these four as one PR, after everything else. Confirm the chain still holds before starting:

```bash
grep -rn 'getTabCrumbs\|additionalBreadCrumbs' static/app --include='*.tsx'
```

`getTransactionSummaryParentCrumbs` in the same file is already the new-style builder — the migration deletes `getTabCrumbs` around it, it does not rewrite both.

### `views/explore/components/breadcrumb.tsx` — hardest file in the set

`ExploreBreadcrumb`, four consumers: `explore/{metrics,spans,logs}/content.tsx` and `explore/replays/list.tsx`. Each one gates the _title source_ on the same boolean that gates the trail, so the title is branch-dependent and step 3 has no single answer. Each also carries sibling nodes in the title slot (a `FeatureBadge`, a tooltip) that have no home in the new API.

Hoist the ternary above both slots and give each branch its own `BreadcrumbList.Title`. Migrating only the true branch nests `breadcrumbs` inside `title`.

The wrapper's own crumb builder uses four independent `if`s, so an unrecognized dataset yields a single unlinked leaf. After dropping the leaf, `items` is empty and the trail renders nothing — which is correct here. Do not invent a parent.

### `views/insights/pages/domainViewHeader.tsx` — the Shape B exception

No leaf crumb: `crumbs[0]` is a linked parent, and `Layout.Title` is `{headerTitle || domainTitle}`. Applying "`Layout.Title` wins" mechanically produces the same string as both a parent link and the heading, where today the page renders one heading. Keep the `crumbs.length > 1` guard as a condition on the `breadcrumbs` slot. `additionalBreadCrumbs` is a public prop — retyping it is what unblocks the row above.
Read each match and its consumers. Classify its current structure:

### `views/preprod/install/buildInstallHeader.tsx` — three branches, one component
| Structure | Migration |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Legacy parents beside a typed breadcrumbs slot | Move only the parent trail into the existing slot's `items`; preserve its title |
| Legacy crumb array containing the current page | Split the leaf into the required typed `title` and pass only parents to the slot’s `items` |
| Shared wrapper that renders the slot | Change its consumers in the same patch; remove wrapping slots |
| Conditional saved-query and landing headers | Preserve a complete title and parent trail in each branch |
| Legacy `Crumb[]` builder | Trace all consumers before changing its return type |
| Navigation outside TopBar | Check landmark and layout needs before replacing it |

Three separate `TopBar.Slot name="title"` blocks with three different crumb arrays, plus a `styled(Breadcrumbs)` alias to delete. Each branch needs its own title decision, and the pending branch's label is a row of `Placeholder`s with no representable form — see `title-item.md`. Mirror `views/dashboards/dashboardBreadcrumbTitle.tsx`'s one-early-return-per-state structure.
Public `TopBar.Slot name="title"` and `Layout.Title` are removed. Treat them as legacy input only if encountered on an older branch, never as the output of migration.

## Wrapper consumer map
## Remaining cases to inspect

Shape C wrappers and their consumers. Re-derive with `grep -rl '<SymbolName' static/app --include='*.tsx' | grep -v spec.tsx`.
These paths were verified during the typed-title API update; recheck them instead of treating this as a fixed backlog:

| Wrapper | Consumers |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `components/profiling/profilingBreadcrumbs.tsx` | `profileHeader.tsx`, `continuousProfileHeader.tsx` |
| `views/alerts/builder/builderBreadCrumbs.tsx` | `views/alerts/edit.tsx` |
| `views/detectors/components/forms/common/breadcrumbs.tsx` | `newDetectorLayout.tsx`, `editDetectorLayout.tsx` |
| `views/discover/breadcrumb.tsx` | `views/discover/results/resultsHeader.tsx` |
| `views/explore/components/breadcrumb.tsx` | `metrics/content.tsx`, `spans/content.tsx`, `logs/content.tsx`, `replays/list.tsx` |
- `static/app/views/preprod/buildDetails/header/buildDetailsHeaderContent.tsx`: legacy breadcrumbs plus a typed title. Preserve the build metadata and page actions.
- `static/app/views/preprod/buildComparison/header/buildCompareHeaderContent.tsx`: legacy breadcrumbs and comparison metadata. Determine the current page label from the full header.
- `static/app/views/insights/pages/domainViewHeader.tsx`: a typed `headerTitle` or domain-name fallback, plus legacy parent breadcrumbs. Preserve the existing parent length guard; do not duplicate the domain name.
- `static/app/views/performance/breadcrumb.tsx`: legacy `Crumb[]` flows through header props into the domain header. Search `getTabCrumbs` and `additionalBreadCrumbs` and migrate the connected consumers together.
- `static/app/views/insights/crons/components/monitorHeader.tsx`: legacy category crumbs beside a typed monitor title. Keep the monitor name as the title and resolve real destinations for parent categories.

Two answer keys worth copying rather than re-deriving:
The Discover, Explore saved-query, dashboard, and preprod install headers are useful migrated examples. Inspect current code; old notes about their public `title` slots no longer apply.

- **An unlinked leaf that must become a link.** `views/detectors/components/uptime/details.tsx` has `{label: t('Uptime Monitor')}` with no `to`. The destination is not in that file, but `views/detectors/components/details/common/header.tsx` already links `getDetectorTypeLabel(detector.type)` → `makeMonitorTypePathname(organization.slug, detector.type)` for exactly this crumb.
- **A spec that renders a wrapper with no TopBar at all.** `components/profiling/profilingBreadcrumbs.spec.tsx` cannot work as written once the wrapper owns two slots. See `tests.md`.
## Retain separate navigation when needed

## Never migrated
- `static/app/components/breadcrumbs.spec.tsx` tests the legacy component while it remains in use.
- `static/app/components/events/eventDrawer.tsx` renders navigation outside the page title.
- `static/app/views/issueDetails/groupDistributions/groupDistributionCrumbs.tsx` supplies crumbs for that separate navigation.

| File | Why it stays |
| ------------------------------------------------------------------- | ------------------------------------------------------------- |
| `components/breadcrumbs.spec.tsx` | The legacy component's own spec; goes when the component does |
| `components/events/eventDrawer.tsx` (`NavigationCrumbs`) | Renders outside the page `<h1>` and needs a `<nav>` landmark |
| `views/issueDetails/groupDistributions/groupDistributionCrumbs.tsx` | Consumes `NavigationCrumbs` |
`BreadcrumbList` renders an `<ol>` without a navigation landmark. Preserve any landmark required by these callers; do not migrate them solely to lower the importer count.

`BreadcrumbList` renders a bare `<ol>` with no landmark mode, so those two are blocked on a component capability. `views/settings/components/settingsBreadcrumb/` is a separate route-driven system that derives crumbs from `useRoutes()` and receives titles via a context side-effect.
Settings routes each contribute one parent item through `handle.settingsBreadcrumb`, including full destination templates and selector switching destinations. Pathless routes share common parents. `SettingsBreadcrumbsProvider` collects entries from all matched routes in order and supplies resolved parent items through downward-only context. `BreadcrumbTitle` combines these with the page's title and additional items. Every Settings page still owns its title through `BreadcrumbTitle` or `SettingsPageHeader`; layouts do not register titles or render a fallback.
Loading
Loading