feat(integrations): Add PathMappingList component for repo code mappings

evanpurkhiser · evanpurkhiser · commit 7800bb595540 · 2026-06-10T14:11:43.000-04:00
Wraps PathMapping with the add/remove/expand orchestration: a single row
can be expanded at a time, empty rows are omitted from the reported value,
and adding another path is blocked while a duplicate mapping is unresolved.
diff --git a/static/app/components/connectRepository/pathMapping.tsx b/static/app/components/connectRepository/pathMapping.tsx
@@ -11,7 +11,7 @@ import {Tooltip} from '@sentry/scraps/tooltip';
 import {IconArrow, IconBranch, IconChevron, IconDelete} from 'sentry/icons';
 import {t} from 'sentry/locale';
 
-interface PathMappingValue {
+export interface PathMappingValue {
   branch: string;
   sourceRoot: string;
   stackRoot: string;
@@ -64,6 +64,15 @@ const schema = z.object({
   branch: z.string(),
 });
 
+/**
+ * Canonical form of a mapping used to compare two mappings for equality. The
+ * branch is resolved to its effective value (an empty branch becomes `main`),
+ * so mappings that differ only by that defaulting parse to the same values.
+ */
+export const normalizedPathMappingSchema = schema.extend({
+  branch: z.string().transform(resolveBranch),
+});
+
 /**
  * Sample stack frame path used to illustrate how the stack trace root is
  * rewritten to the source code root in the preview.
diff --git a/static/app/components/connectRepository/pathMappingList.spec.tsx b/static/app/components/connectRepository/pathMappingList.spec.tsx
@@ -0,0 +1,151 @@
+import {render, screen, userEvent} from 'sentry-test/reactTestingLibrary';
+
+import type {PathMappingValue} from 'sentry/components/connectRepository/pathMapping';
+import {PathMappingList} from 'sentry/components/connectRepository/pathMappingList';
+
+function renderPathMappingList(
+  props: Partial<Parameters<typeof PathMappingList>[0]> = {}
+) {
+  return render(<PathMappingList onChange={() => {}} {...props} />);
+}
+
+const MAPPINGS: PathMappingValue[] = [
+  {stackRoot: 'app/', sourceRoot: 'static/app/', branch: 'main'},
+  {stackRoot: 'src/', sourceRoot: 'src/app/', branch: 'frontend'},
+];
+
+describe('PathMappingList', () => {
+  describe('empty', () => {
+    it('starts with a single new mapping open for editing', () => {
+      renderPathMappingList();
+
+      expect(screen.getByText(/Paths \(1\)/)).toBeInTheDocument();
+      expect(screen.getByRole('textbox', {name: 'Stack trace root'})).toBeInTheDocument();
+    });
+
+    it('disables "Add another path" while the empty row is being edited', () => {
+      renderPathMappingList();
+
+      expect(screen.getByRole('button', {name: 'Add another path'})).toBeDisabled();
+    });
+
+    it('reports filled values through onChange', async () => {
+      const onChange = jest.fn();
+      renderPathMappingList({onChange});
+
+      await userEvent.type(
+        screen.getByRole('textbox', {name: 'Stack trace root'}),
+        'lib/'
+      );
+
+      expect(onChange).toHaveBeenLastCalledWith([
+        expect.objectContaining({stackRoot: 'lib/', branch: 'main'}),
+      ]);
+    });
+  });
+
+  describe('with existing mappings', () => {
+    it('renders each mapping as a collapsed summary', () => {
+      renderPathMappingList({pathMappings: MAPPINGS});
+
+      expect(screen.getByText(/Paths \(2\)/)).toBeInTheDocument();
+      expect(screen.getByText('app/')).toBeInTheDocument();
+      expect(screen.getByText('src/')).toBeInTheDocument();
+      expect(
+        screen.queryByRole('textbox', {name: 'Stack trace root'})
+      ).not.toBeInTheDocument();
+    });
+
+    it('expands a single mapping at a time', async () => {
+      renderPathMappingList({pathMappings: MAPPINGS});
+
+      const [first, second] = screen.getAllByRole('button', {
+        name: 'Expand path mapping',
+      });
+
+      await userEvent.click(first!);
+      expect(screen.getByRole('textbox', {name: 'Stack trace root'})).toHaveValue('app/');
+
+      await userEvent.click(second!);
+      expect(screen.getByRole('textbox', {name: 'Stack trace root'})).toHaveValue('src/');
+      expect(screen.getAllByRole('textbox', {name: 'Stack trace root'})).toHaveLength(1);
+    });
+
+    it('adds a new mapping when "Add another path" is clicked', async () => {
+      renderPathMappingList({pathMappings: MAPPINGS});
+
+      await userEvent.click(screen.getByRole('button', {name: 'Add another path'}));
+
+      expect(screen.getByText(/Paths \(3\)/)).toBeInTheDocument();
+      expect(screen.getByRole('textbox', {name: 'Stack trace root'})).toHaveValue('');
+    });
+
+    it('removes a mapping and reports the change', async () => {
+      const onChange = jest.fn();
+      renderPathMappingList({pathMappings: MAPPINGS, onChange});
+
+      const [firstDelete] = screen.getAllByRole('button', {
+        name: 'Delete path mapping',
+      });
+      await userEvent.click(firstDelete!);
+
+      expect(screen.getByText(/Paths \(1\)/)).toBeInTheDocument();
+      expect(onChange).toHaveBeenLastCalledWith([
+        expect.objectContaining({stackRoot: 'src/'}),
+      ]);
+    });
+
+    it('falls back to a fresh open row when the last mapping is deleted', async () => {
+      const onChange = jest.fn();
+      renderPathMappingList({pathMappings: [MAPPINGS[0]!], onChange});
+
+      await userEvent.click(screen.getByRole('button', {name: 'Delete path mapping'}));
+
+      expect(screen.getByText(/Paths \(1\)/)).toBeInTheDocument();
+      expect(screen.getByRole('textbox', {name: 'Stack trace root'})).toHaveValue('');
+      expect(onChange).toHaveBeenLastCalledWith([]);
+    });
+  });
+
+  describe('duplicate mappings', () => {
+    it('blocks adding another path until the duplicate is resolved', () => {
+      const duplicates: PathMappingValue[] = [
+        {stackRoot: 'app/', sourceRoot: 'static/app/', branch: 'main'},
+        {stackRoot: 'app/', sourceRoot: 'static/app/', branch: 'main'},
+      ];
+      renderPathMappingList({pathMappings: duplicates});
+
+      expect(screen.getByRole('button', {name: 'Add another path'})).toBeDisabled();
+    });
+
+    it('treats an empty branch as a duplicate of the default branch', () => {
+      const duplicates: PathMappingValue[] = [
+        {stackRoot: 'app/', sourceRoot: 'static/app/', branch: ''},
+        {stackRoot: 'app/', sourceRoot: 'static/app/', branch: 'main'},
+      ];
+      renderPathMappingList({pathMappings: duplicates});
+
+      expect(screen.getByRole('button', {name: 'Add another path'})).toBeDisabled();
+    });
+  });
+
+  describe('add another path', () => {
+    it('reopens a trailing empty row instead of stacking a new one', async () => {
+      renderPathMappingList({pathMappings: [MAPPINGS[0]!]});
+
+      // Add a new empty row, then collapse it by expanding the existing one.
+      await userEvent.click(screen.getByRole('button', {name: 'Add another path'}));
+      expect(screen.getByText(/Paths \(2\)/)).toBeInTheDocument();
+
+      await userEvent.click(screen.getByRole('button', {name: 'Expand path mapping'}));
+      expect(screen.getByRole('textbox', {name: 'Stack trace root'})).toHaveValue('app/');
+
+      // The trailing empty row is now collapsed, so adding reopens it rather
+      // than appending a third row.
+      await userEvent.click(screen.getByRole('button', {name: 'Add another path'}));
+
+      expect(screen.getByText(/Paths \(2\)/)).toBeInTheDocument();
+      expect(screen.getByRole('textbox', {name: 'Stack trace root'})).toHaveValue('');
+    });
+  });
+});
diff --git a/static/app/components/connectRepository/pathMappingList.stories.tsx b/static/app/components/connectRepository/pathMappingList.stories.tsx
@@ -0,0 +1,22 @@
+import {useState} from 'react';
+
+import type {PathMappingValue} from 'sentry/components/connectRepository/pathMapping';
+import {PathMappingList} from 'sentry/components/connectRepository/pathMappingList';
+import * as Storybook from 'sentry/stories';
+
+export default Storybook.story('PathMappingList', story => {
+  story('Empty (starts with a new path)', () => {
+    const [pathMappings, setPathMappings] = useState<PathMappingValue[]>([]);
+
+    return <PathMappingList pathMappings={pathMappings} onChange={setPathMappings} />;
+  });
+
+  story('With existing paths', () => {
+    const [pathMappings, setPathMappings] = useState([
+      {stackRoot: 'app/', sourceRoot: 'static/app/', branch: 'main'},
+      {stackRoot: 'src/', sourceRoot: 'src/app/', branch: 'frontend'},
+    ]);
+
+    return <PathMappingList pathMappings={pathMappings} onChange={setPathMappings} />;
+  });
+});
diff --git a/static/app/components/connectRepository/pathMappingList.tsx b/static/app/components/connectRepository/pathMappingList.tsx
@@ -0,0 +1,175 @@
+import {useRef, useState} from 'react';
+
+import {Button} from '@sentry/scraps/button';
+import {Flex, Stack} from '@sentry/scraps/layout';
+import {Text} from '@sentry/scraps/text';
+
+import {IconAdd} from 'sentry/icons';
+import {t, tct} from 'sentry/locale';
+
+import {
+  normalizedPathMappingSchema,
+  PathMapping,
+  type PathMappingValue,
+} from './pathMapping';
+
+interface PathMappingListProps {
+  /**
+   * Called whenever the set of mappings changes. Receives the list of mappings
+   * that have content (empty new rows are omitted).
+   */
+  onChange: (pathMappings: PathMappingValue[]) => void;
+  /**
+   * The persisted mappings to seed the list with. When empty, the list starts
+   * with a single new mapping ready to fill out.
+   */
+  pathMappings?: PathMappingValue[];
+}
+
+interface Entry {
+  id: number;
+  /**
+   * New (not-yet-persisted) rows render the editable form without a summary
+   * while expanded. Existing rows keep their summary pinned above the form.
+   */
+  isNew: boolean;
+  value: PathMappingValue;
+}
+
+const EMPTY_MAPPING: PathMappingValue = {stackRoot: '', sourceRoot: '', branch: ''};
+
+const hasContent = (value: PathMappingValue) =>
+  value.stackRoot.trim() !== '' || value.sourceRoot.trim() !== '';
+
+const mappingKey = (value: PathMappingValue) => {
+  const {stackRoot, sourceRoot, branch} = normalizedPathMappingSchema.parse(value);
+  return `${stackRoot}\0${sourceRoot}\0${branch}`;
+};
+
+/**
+ * Whether two or more filled mappings are identical. Used to block adding
+ * another path until the duplicate is resolved.
+ */
+const hasDuplicateMappings = (entries: Entry[]) => {
+  const keys = entries
+    .filter(entry => hasContent(entry.value))
+    .map(entry => mappingKey(entry.value));
+
+  return new Set(keys).size !== keys.length;
+};
+
+export function PathMappingList({pathMappings, onChange}: PathMappingListProps) {
+  const idRef = useRef(0);
+  const nextId = () => idRef.current++;
+
+  const [entries, setEntries] = useState<Entry[]>(() => {
+    const seeded = (pathMappings ?? []).map(value => ({
+      id: nextId(),
+      isNew: false,
+      value,
+    }));
+
+    return seeded.length > 0
+      ? seeded
+      : [{id: nextId(), isNew: true, value: EMPTY_MAPPING}];
+  });
+
+  // Only a single mapping can be expanded at a time. Start with the initial new
+  // mapping open; otherwise everything is collapsed.
+  const [openId, setOpenId] = useState<number | null>(() =>
+    entries.length === 1 && entries[0]!.isNew ? entries[0]!.id : null
+  );
+
+  const commit = (next: Entry[]) => {
+    setEntries(next);
+    onChange(next.map(entry => entry.value).filter(hasContent));
+  };
+
+  const handleChange = (id: number, value: PathMappingValue) => {
+    commit(entries.map(entry => (entry.id === id ? {...entry, value} : entry)));
+  };
+
+  const handleDelete = (id: number) => {
+    const remaining = entries.filter(entry => entry.id !== id);
+
+    // Deleting the last mapping would leave nothing to fill out, so fall back
+    // to a fresh open row — the same state the list seeds itself with when
+    // there are no mappings to begin with.
+    if (remaining.length === 0) {
+      const newId = nextId();
+      commit([{id: newId, isNew: true, value: EMPTY_MAPPING}]);
+      setOpenId(newId);
+      return;
+    }
+
+    commit(remaining);
+    setOpenId(open => (open === id ? null : open));
+  };
+
+  const handleAddAnother = () => {
+    // If the last row is still empty, just reopen it rather than stacking
+    // another blank row on top of it.
+    const last = entries.at(-1);
+    if (last && !hasContent(last.value)) {
+      setOpenId(last.id);
+      return;
+    }
+
+    const id = nextId();
+    setEntries([...entries, {id, isNew: true, value: EMPTY_MAPPING}]);
+    setOpenId(id);
+  };
+
+  const toggle = (id: number) => setOpenId(open => (open === id ? null : id));
+
+  const duplicate = hasDuplicateMappings(entries);
+  const addDisabledReason = duplicate
+    ? t('Resolve the duplicate path mapping first')
+    : undefined;
+
+  // Nothing to add while the trailing empty row is already open for editing —
+  // "Add another path" only reopens it when it's collapsed.
+  const last = entries.at(-1);
+  const editingEmptyRow =
+    last !== undefined && !hasContent(last.value) && openId === last.id;
+
+  return (
+    <Stack gap="lg">
+      <Stack gap="xs">
+        <Text bold>{tct('Paths ([count])', {count: entries.length})}</Text>
+        <Text size="sm" variant="muted">
+          {t(
+            'Tell Sentry how to translate file paths, so errors open the right line of code.'
+          )}
+        </Text>
+      </Stack>
+
+      <Stack gap="md">
+        {entries.map(entry => (
+          <PathMapping
+            key={entry.id}
+            {...entry.value}
+            editing={openId === entry.id}
+            isNew={entry.isNew}
+            onChange={value => handleChange(entry.id, value)}
+            onDelete={() => handleDelete(entry.id)}
+            onExpandToggle={() => toggle(entry.id)}
+          />
+        ))}
+      </Stack>
+
+      <Flex justify="end">
+        <Button
+          size="xs"
+          variant="transparent"
+          icon={<IconAdd />}
+          disabled={Boolean(addDisabledReason) || editingEmptyRow}
+          tooltipProps={{title: addDisabledReason}}
+          onClick={handleAddAnother}
+        >
+          {t('Add another path')}
+        </Button>
+      </Flex>
+    </Stack>
+  );
+}
