@open-mercato/ui 0.7.0 → 0.7.1-develop.7102.1.b41f7e3e51

package/src/backend/AppShell.tsx

@@ -411,6 +411,19 @@ function resolveItemKey(item: { id?: string; href: string }): string {
   return item.href
 }
 
+// Horizontal padding lives on each sidebar block rather than on the <aside>, so the scroll
+// container never needs a negative-margin bleed to reach the panel edges. The transition keeps the
+// compact/expanded padding step in sync with the aside's width animation.
+function sidebarBlockPadding(compact: boolean): string {
+  return `${compact ? 'px-2' : 'px-3'} transition-[padding] duration-200 ease-out`
+}
+
+// An InjectionSpot renders nothing when no widget is registered, so its wrapper must collapse
+// instead of surviving as an empty flex child that still costs a full `gap-3`.
+function sidebarInjectionWrapper(compact: boolean): string {
+  return `${sidebarBlockPadding(compact)} empty:hidden`
+}
+
 function SerializedIcon({ markup }: { markup: string }) {
   return <span aria-hidden="true" dangerouslySetInnerHTML={{ __html: markup }} />
 }
@@ -772,17 +785,9 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
     setOpenGroups((prev) => (prev[key] === false ? { ...prev, [key]: true } : prev))
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [pathname, navGroups])
-  // Keep header state in sync with props (server-side updates)
-  React.useEffect(() => {
-    setHeaderTitle(currentTitle)
-    setHeaderBreadcrumb(breadcrumb)
-  }, [currentTitle, breadcrumb])
-  // Clear breadcrumb on client-side navigation so stale state doesn't persist;
-  // the new page's ApplyBreadcrumb (if any) will set the correct values.
-  // Must be a layout effect: when a prefetched navigation commits the new
-  // pathname and the new page together, child passive effects (ApplyBreadcrumb)
-  // run before parent ones, so a passive clear here would wipe the value the
-  // incoming page just set.
+  // Reset stale header state before applying server props and before the new
+  // page's passive ApplyBreadcrumb effect. The ordering matters for layouts
+  // that persist across client-side navigation.
   const prevPathname = React.useRef(pathname)
   useIsomorphicLayoutEffect(() => {
     if (pathname !== prevPathname.current) {
@@ -791,6 +796,12 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
       setHeaderBreadcrumb(undefined)
     }
   }, [pathname])
+  // Keep header state in sync with props (server-side updates). A child page's
+  // ApplyBreadcrumb effect runs afterward and may refine this static trail.
+  useIsomorphicLayoutEffect(() => {
+    setHeaderTitle(currentTitle)
+    setHeaderBreadcrumb(breadcrumb)
+  }, [currentTitle, breadcrumb])
 
   // Keep navGroups in sync when server-provided groups change
   React.useEffect(() => {
@@ -806,11 +817,12 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
   ) {
     const sortedSections = [...sections].sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
     const lastVisibleIndex = sortedSections.length - 1
+    const blockPadding = sidebarBlockPadding(compact)
 
     return (
       <div className="flex h-full flex-col gap-3">
         {!hideHeader && (
-          <div className="mb-2">
+          <div className={`mb-2 ${blockPadding}`}>
             <Link
               href="/backend"
               className={`flex items-center gap-3 rounded-xl transition-colors hover:bg-muted ${compact ? 'p-2 justify-center' : 'p-3'}`}
@@ -822,16 +834,18 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
           </div>
         )}
         {!compact && !hideSearch && (
-          <SearchInput
-            value={navQuery}
-            onChange={setNavQuery}
-            placeholder={t('appShell.searchNavPlaceholder', 'Search...')}
-            aria-label={t('appShell.searchNavAria', 'Search navigation')}
-            clearLabel={t('appShell.searchNavClear', 'Clear search')}
-            className="mb-2"
-          />
+          <div className={blockPadding}>
+            <SearchInput
+              value={navQuery}
+              onChange={setNavQuery}
+              placeholder={t('appShell.searchNavPlaceholder', 'Search...')}
+              aria-label={t('appShell.searchNavAria', 'Search navigation')}
+              clearLabel={t('appShell.searchNavClear', 'Clear search')}
+              className="mb-2"
+            />
+          </div>
         )}
-        <div data-sidebar-scroll="true" className={`flex flex-1 flex-col gap-3 overflow-y-auto scrollbar-hide pr-1 ${compact ? '-ml-2 pl-2' : '-ml-3 pl-3'}`}>
+        <div data-sidebar-scroll="true" className="flex flex-1 flex-col gap-3 overflow-x-hidden overflow-y-auto scrollbar-hide">
           <nav className="flex flex-col gap-2">
           {sortedSections.map((section, sectionIndex) => {
             const sectionNavQueryActive = hideSearch ? false : navQueryActive
@@ -911,7 +925,11 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
             }
 
             return (
-              <div key={section.id}>
+              <div
+                key={section.id}
+                className={`${blockPadding} ${sectionIndex !== lastVisibleIndex ? 'border-b pb-2' : ''}`}
+                data-sidebar-group="true"
+              >
                 {!compact && (
                   <Button
                     variant="muted"
@@ -928,7 +946,6 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
                     {sortedItems.map((item) => renderSectionItem(item))}
                   </div>
                 )}
-                {sectionIndex !== lastVisibleIndex && <div className={`my-2 border-t ${compact ? '-ml-2 -mr-3' : '-ml-3 -mr-4'}`} />}
               </div>
             )
           })}
@@ -939,9 +956,12 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
   }
 
   function renderSidebar(compact: boolean, hideHeader?: boolean, forceMainOnly?: boolean) {
+    const blockPadding = sidebarBlockPadding(compact)
+    const injectionWrapper = sidebarInjectionWrapper(compact)
+
     if (!isChromeReady && isChromeLoading) {
       return (
-        <div className="flex flex-col min-h-full gap-3" data-testid="backend-chrome-loading">
+        <div className={`flex min-h-full flex-col gap-3 ${blockPadding}`} data-testid="backend-chrome-loading">
           {!hideHeader ? (
             <div className="mb-2">
               <Link
@@ -954,7 +974,7 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
               </Link>
             </div>
           ) : null}
-          <div className="flex flex-1 flex-col gap-3 pr-1">
+          <div className="flex flex-1 flex-col gap-3">
             <div className="space-y-3">
               <div className="h-8 rounded bg-muted/50" />
               <div className="space-y-2 pl-1">
@@ -1009,7 +1029,7 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
     return (
       <div className="flex h-full flex-col gap-3">
         {!hideHeader && (
-          <div className="mb-2">
+          <div className={`mb-2 ${blockPadding}`}>
             <Link
               href="/backend"
               className={`flex items-center gap-3 rounded-xl transition-colors hover:bg-muted ${compact ? 'p-2 justify-center' : 'p-3'}`}
@@ -1021,22 +1041,26 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
           </div>
         )}
         {shouldRenderSidebarInjectionSpots ? (
-          <InjectionSpot
-            spotId={BACKEND_SIDEBAR_TOP_INJECTION_SPOT_ID}
-            context={injectionContext}
-          />
+          <div className={injectionWrapper} data-sidebar-injection-wrapper="true">
+            <InjectionSpot
+              spotId={BACKEND_SIDEBAR_TOP_INJECTION_SPOT_ID}
+              context={injectionContext}
+            />
+          </div>
         ) : null}
         {!compact && (
-          <SearchInput
-            value={navQuery}
-            onChange={setNavQuery}
-            placeholder={t('appShell.searchNavPlaceholder', 'Search...')}
-            aria-label={t('appShell.searchNavAria', 'Search navigation')}
-            clearLabel={t('appShell.searchNavClear', 'Clear search')}
-            className="mb-2"
-          />
+          <div className={blockPadding}>
+            <SearchInput
+              value={navQuery}
+              onChange={setNavQuery}
+              placeholder={t('appShell.searchNavPlaceholder', 'Search...')}
+              aria-label={t('appShell.searchNavAria', 'Search navigation')}
+              clearLabel={t('appShell.searchNavClear', 'Clear search')}
+              className="mb-2"
+            />
+          </div>
         )}
-        <div data-sidebar-scroll="true" className={`flex flex-1 flex-col gap-3 overflow-y-auto scrollbar-hide pr-1 ${compact ? '-ml-2 pl-2' : '-ml-3 pl-3'}`}>
+        <div data-sidebar-scroll="true" className="flex flex-1 flex-col gap-3 overflow-x-hidden overflow-y-auto scrollbar-hide">
           {(() => {
               const isSettingsPath = (href: string) => {
                 if (href === '/backend/settings') return true
@@ -1065,10 +1089,12 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
                 <>
                   <nav className="flex flex-col gap-2" data-testid="sidebar">
                     {shouldRenderSidebarInjectionSpots ? (
-                      <InjectionSpot
-                        spotId={BACKEND_SIDEBAR_NAV_INJECTION_SPOT_ID}
-                        context={injectionContext}
-                      />
+                      <div className={injectionWrapper} data-sidebar-injection-wrapper="true">
+                        <InjectionSpot
+                          spotId={BACKEND_SIDEBAR_NAV_INJECTION_SPOT_ID}
+                          context={injectionContext}
+                        />
+                      </div>
                     ) : null}
                     {mainGroups.map((g, gi) => {
                       const groupId = resolveGroupKey(g)
@@ -1082,7 +1108,11 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
                       })
                       if (visibleItems.length === 0) return null
                       return (
-                        <div key={groupId}>
+                        <div
+                          className={`${blockPadding} ${gi !== mainLastVisibleGroupIndex ? 'border-b pb-2' : ''}`}
+                          key={groupId}
+                          data-sidebar-group="true"
+                        >
                           {!compact && (
                             <Button
                               variant="muted"
@@ -1175,7 +1205,6 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
                               })}
                             </div>
                           )}
-                          {gi !== mainLastVisibleGroupIndex && <div className={`my-2 border-t ${compact ? '-ml-2 -mr-3' : '-ml-3 -mr-4'}`} />}
                         </div>
                       )
                     })}
@@ -1184,7 +1213,7 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
               )
             })()}
         </div>
-        <div className="sticky bottom-0 bg-background pb-1">
+        <div className={`sticky bottom-0 bg-background pb-1 ${injectionWrapper}`} data-sidebar-injection-wrapper="true">
           {shouldRenderSidebarInjectionSpots ? (
             <InjectionSpot
               spotId={BACKEND_SIDEBAR_NAV_FOOTER_INJECTION_SPOT_ID}
@@ -1229,15 +1258,17 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
     if (!sections) return null
     return (
       <div className="flex h-full flex-col gap-2">
-        <Link
-          href="/backend"
-          className="inline-flex items-center gap-2 rounded-lg px-2 py-2 text-sm font-semibold text-foreground transition-colors hover:bg-muted"
-          data-testid="appshell-section-back-to-main"
-          aria-label={t('backend.nav.backToMain', 'Back to Main')}
-        >
-          <ChevronLeft className="size-4 shrink-0" aria-hidden />
-          <span className="truncate">{title}</span>
-        </Link>
+        <div className={sidebarBlockPadding(false)}>
+          <Link
+            href="/backend"
+            className="inline-flex items-center gap-2 rounded-lg px-2 py-2 text-sm font-semibold text-foreground transition-colors hover:bg-muted"
+            data-testid="appshell-section-back-to-main"
+            aria-label={t('backend.nav.backToMain', 'Back to Main')}
+          >
+            <ChevronLeft className="size-4 shrink-0" aria-hidden />
+            <span className="truncate">{title}</span>
+          </Link>
+        </div>
         <div className="min-h-0 flex-1">
           {renderSectionSidebar(sections, title, false, true, true)}
         </div>
@@ -1306,7 +1337,7 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
         {effectiveCollapsed ? <PanelLeftOpen className="size-4" /> : <PanelLeftClose className="size-4" />}
       </button>
       {/* Desktop main sidebar */}
-      <aside ref={sidebarAsideRef} className={`${asideClassesBase} ${effectiveCollapsed ? 'px-2' : 'px-3'} hidden lg:block lg:sticky lg:top-0 lg:h-svh lg:self-start lg:overflow-hidden lg:relative transition-[width,padding] duration-200 ease-out`} style={{ width: asideWidth }}>
+      <aside ref={sidebarAsideRef} className={`${asideClassesBase} px-0 hidden lg:block lg:sticky lg:top-0 lg:h-svh lg:self-start lg:overflow-hidden lg:relative transition-[width] duration-200 ease-out`} style={{ width: asideWidth }}>
         {renderSidebar(effectiveCollapsed, false, isSectionView)}
         {/* Scroll affordance — gradient fade + clickable chevron that flips up when
             the user reaches the bottom and disappears when nothing is scrollable
@@ -1351,7 +1382,7 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
           original swap behavior to fit the narrow width. */}
       {isSectionView ? (
         <aside
-          className={`${asideClassesBase} px-3 hidden lg:block lg:sticky lg:top-0 lg:h-svh lg:self-start lg:overflow-hidden lg:relative`}
+          className={`${asideClassesBase} px-0 hidden lg:block lg:sticky lg:top-0 lg:h-svh lg:self-start lg:overflow-hidden lg:relative`}
           style={{ width: '240px' }}
           data-testid="appshell-section-sidebar"
         >
@@ -1573,7 +1604,7 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
                   ? `mobile-drawer-tab-${mobileDrawerView === 'main' ? 'main' : 'section'}`
                   : undefined
               }
-              className="min-h-0 flex-1 overflow-y-auto overflow-x-hidden p-3"
+              className="min-h-0 flex-1 overflow-y-auto overflow-x-hidden py-3"
             >
               {/* Force expanded sidebar in mobile drawer, hide its header and collapse toggle */}
               {renderSidebar(false, true, mobileDrawerView === 'main')}

package/src/backend/DataTable.tsx

@@ -128,6 +128,14 @@ export type PaginationProps = {
   pageSize: number
   total: number
   totalPages: number
+  /**
+   * `total` (and the `totalPages` derived from it) is a floor, not an exact
+   * count — the server capped the list count (`totalIsCapped: true` on the
+   * list payload). Capped totals render as "{total}+" and pagination stays
+   * open past the floor via short-page detection instead of ending at
+   * `ceil(total / pageSize)`.
+   */
+  totalIsCapped?: boolean
   onPageChange: (page: number) => void
   durationMs?: number | null
   cacheStatus?: 'hit' | 'miss' | null
@@ -301,7 +309,7 @@ export type DataTableProps<T extends RowData> = {
   emptyState?: React.ReactNode
   error?: React.ReactNode | string | null
   rowActions?: (row: T) => React.ReactNode
-  onRowClick?: (row: T) => void
+  onRowClick?: (row: T, event: React.MouseEvent<HTMLTableRowElement>) => void
   rowClickActionIds?: string[]
   disableRowClick?: boolean
   bulkActions?: BulkAction<T>[]
@@ -2613,8 +2621,21 @@ export function DataTable<T extends RowData>({
     if (!pagination || pagination.total === 0) return null
 
     const { page, totalPages, onPageChange, durationMs, cacheStatus } = pagination
+    const totalIsCapped = pagination.totalIsCapped === true
+    // Short-page detection: a full current page means a next page may exist,
+    // even past the capped floor. `data` holds exactly the rendered page's rows.
+    const pageIsFull = data.length >= pagination.pageSize
     const startItem = (page - 1) * pagination.pageSize + 1
-    const endItem = Math.min(page * pagination.pageSize, pagination.total)
+    // Past a capped floor, `total` can sit below the window — derive the end
+    // of the range from the rows actually shown instead.
+    const endItem = totalIsCapped
+      ? Math.max(startItem, startItem + data.length - 1)
+      : Math.min(page * pagination.pageSize, pagination.total)
+    // Short-page detection false-positives when the true row count is an exact
+    // multiple of `pageSize`: Next stays enabled on the last full page and the
+    // page after it comes back empty. `total` is the cap rather than 0, so the
+    // pager still renders — claim no range rather than "X to X" over no rows.
+    const pageIsEmpty = data.length === 0
     const effectiveDuration = (typeof durationMs === 'number' && Number.isFinite(durationMs) && durationMs >= 0)
       ? durationMs
       : measuredDurationMs ?? undefined
@@ -2653,17 +2674,27 @@ export function DataTable<T extends RowData>({
           page={page}
           pageSize={pagination.pageSize}
           total={pagination.total}
+          totalIsCapped={totalIsCapped}
+          hasNextPage={totalIsCapped ? pageIsFull : undefined}
           onPageChange={(next) => { onPageChange(next); scrollTableIntoView() }}
           onPageSizeChange={pagination.onPageSizeChange ? (next) => {
             pagination.onPageSizeChange!(next)
             scrollTableIntoView()
           } : undefined}
           pageSizeOptions={pageSizeOptions}
-          formatPageInfo={() =>
-            durationLabel
+          formatPageInfo={() => {
+            if (totalIsCapped) {
+              if (pageIsEmpty) {
+                return t('ui.dataTable.pagination.resultsCappedNoRows', 'No further results past {total}', { total: pagination.total })
+              }
+              return durationLabel
+                ? t('ui.dataTable.pagination.resultsCappedWithDuration', 'Showing {start} to {end} of {total}+ results in {duration}', { start: startItem, end: endItem, total: pagination.total, duration: durationLabel })
+                : t('ui.dataTable.pagination.resultsCapped', 'Showing {start} to {end} of {total}+ results', { start: startItem, end: endItem, total: pagination.total })
+            }
+            return durationLabel
               ? t('ui.dataTable.pagination.resultsWithDuration', 'Showing {start} to {end} of {total} results in {duration}', { start: startItem, end: endItem, total: pagination.total, duration: durationLabel })
               : t('ui.dataTable.pagination.results', 'Showing {start} to {end} of {total} results', { start: startItem, end: endItem, total: pagination.total })
-          }
+          }}
           formatPageSizeLabel={(size) =>
             `${size} ${t('ui.dataTable.pagination.perPage', 'per page')}`
           }
@@ -2672,7 +2703,7 @@ export function DataTable<T extends RowData>({
         />
       </div>
     )
-  }, [pagination, showQueryTime, measuredDurationMs, scrollTableIntoView, t])
+  }, [pagination, data, showQueryTime, measuredDurationMs, scrollTableIntoView, t])
 
   // Auto filters: fetch custom field defs when requested
   const resolvedEntityIds = React.useMemo(() => {
@@ -3193,7 +3224,10 @@ export function DataTable<T extends RowData>({
   const shouldRenderHeader = hasTitle || renderToolbarInline || shouldRenderActionsWrapper || shouldRenderToolbarBelow
   const containerClassName = embedded ? '' : 'rounded-lg border bg-card mx-1 sm:mx-2'
   const headerWrapperClassName = embedded ? 'pb-3' : 'px-4 py-3 border-b'
-  const headerContentClassName = 'flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between'
+  // The header row wraps once the actions no longer fit beside the title (the
+  // title keeps a 12rem floor); before, the title collapsed to a sliver and
+  // the wrapped action buttons rendered over it on narrow layouts.
+  const headerContentClassName = 'flex flex-col gap-2 sm:flex-row sm:flex-wrap sm:items-center sm:justify-between'
   const toolbarWrapperClassName = embedded ? 'mt-2' : 'mt-3 pt-3 border-t'
   const tableScrollWrapperClassName = embedded ? '' : 'overflow-auto'
 
@@ -3249,11 +3283,11 @@ export function DataTable<T extends RowData>({
         <div className={headerWrapperClassName}>
           {(hasTitle || shouldRenderActionsWrapper || renderToolbarInline) && (
             <div className={headerContentClassName}>
-              <div className="flex-1 min-w-0">
+              <div className="flex-1 min-w-0 sm:basis-48">
                 {renderToolbarInline ? builtToolbar : titleContent}
               </div>
               {shouldRenderActionsWrapper ? (
-                <div className="flex flex-wrap items-center gap-2 min-h-[2.25rem]">
+                <div className="flex flex-wrap items-center gap-2 min-h-[2.25rem] sm:ml-auto sm:justify-end">
                   {refreshButtonConfig ? (
                     <Button
                       type="button"
@@ -3464,7 +3498,7 @@ export function DataTable<T extends RowData>({
                       }
                       
                       if (onRowClick) {
-                        onRowClick(row.original as T)
+                        onRowClick(row.original as T, e)
                       } else if (defaultRowAction) {
                         if (defaultRowAction.href) {
                           router.push(defaultRowAction.href)

package/src/backend/__tests__/AppShell.test.tsx

@@ -9,6 +9,7 @@ import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWith
 
 const mockInjectionSpot = jest.fn()
 let mockPathname = '/backend/users'
+let mockInjectionSpotRendersNothing = false
 
 jest.mock('next/link', () => {
   const React = require('react')
@@ -39,6 +40,7 @@ jest.mock('next/navigation', () => ({
 jest.mock('../injection/InjectionSpot', () => ({
   InjectionSpot: (props: { spotId: string; context?: Record<string, unknown> }) => {
     mockInjectionSpot(props)
+    if (mockInjectionSpotRendersNothing) return null
     return <div data-testid={`injection-spot:${props.spotId}`} />
   },
 }))
@@ -55,7 +57,9 @@ jest.mock('../injection/eventBridge', () => ({
 }))
 
 jest.mock('../injection/StatusBadgeInjectionSpot', () => ({
-  StatusBadgeInjectionSpot: () => <div data-testid="status-badge-injection-spot" />,
+  StatusBadgeInjectionSpot: () => (
+    mockInjectionSpotRendersNothing ? null : <div data-testid="status-badge-injection-spot" />
+  ),
 }))
 
 jest.mock('../operations/LastOperationBanner', () => ({
@@ -117,6 +121,7 @@ describe('AppShell', () => {
   beforeEach(() => {
     mockInjectionSpot.mockClear()
     mockPathname = '/backend/users'
+    mockInjectionSpotRendersNothing = false
   })
 
   beforeAll(() => {
@@ -471,6 +476,52 @@ describe('AppShell', () => {
     })
   })
 
+  it('keeps the new page breadcrumb after client-side navigation', async () => {
+    mockPathname = '/backend/documents'
+
+    const { rerender } = renderWithProviders(
+      <AppShell
+        email="demo@example.com"
+        groups={groups}
+        currentTitle="Documents"
+        breadcrumb={[{ label: 'Documents' }]}
+      >
+        <ApplyBreadcrumb title="Documents" breadcrumb={[{ label: 'Documents' }]} />
+        <div>Documents list</div>
+      </AppShell>,
+      { dict },
+    )
+
+    await waitFor(() => {
+      expect(within(screen.getByRole('navigation', { name: 'Breadcrumb' })).getByText('Documents')).toBeInTheDocument()
+    })
+
+    mockPathname = '/backend/documents/document-id'
+    rerender(
+      <AppShell
+        email="demo@example.com"
+        groups={groups}
+        currentTitle="Documents"
+        breadcrumb={[{ label: 'Documents' }]}
+      >
+        <ApplyBreadcrumb
+          title="Document"
+          breadcrumb={[
+            { label: 'Documents', href: '/backend/documents' },
+            { label: 'Document' },
+          ]}
+        />
+        <div>Document detail</div>
+      </AppShell>,
+    )
+
+    await waitFor(() => {
+      const breadcrumb = screen.getByRole('navigation', { name: 'Breadcrumb' })
+      expect(within(breadcrumb).getByRole('link', { name: 'Documents' })).toHaveAttribute('href', '/backend/documents')
+      expect(within(breadcrumb).getByText('Document')).toHaveAttribute('aria-current', 'page')
+    })
+  })
+
   it('keeps settings parent item active on descendant routes outside explicit child list', async () => {
     mockPathname = '/backend/entities/user/example%3Acalendar_entity'
 
@@ -577,6 +628,116 @@ describe('AppShell', () => {
     }
   })
 
+  describe('sidebar layout', () => {
+    const multiGroups = [
+      groups[0],
+      {
+        id: 'commerce',
+        name: 'Commerce',
+        items: [{ href: '/backend/orders', title: 'Orders' }],
+      },
+      {
+        id: 'ops',
+        name: 'Ops',
+        items: [{ href: '/backend/jobs', title: 'Jobs' }],
+      },
+    ]
+
+    it('collapses sidebar injection-spot wrappers when their spots render nothing', async () => {
+      mockInjectionSpotRendersNothing = true
+
+      const { container } = renderWithProviders(
+        <AppShell email="demo@example.com" groups={groups}>
+          <div>Child content</div>
+        </AppShell>,
+        { dict },
+      )
+
+      await waitFor(() => {
+        expect(screen.getByText('Users List')).toBeInTheDocument()
+      })
+
+      const wrappers = Array.from(container.querySelectorAll('[data-sidebar-injection-wrapper="true"]'))
+      expect(wrappers.length).toBeGreaterThan(0)
+      for (const wrapper of wrappers) {
+        // The spot rendered nothing, so the wrapper is an empty flex child of the sidebar's
+        // `gap-3` column and would still cost a full gap unless it collapses itself.
+        expect(wrapper.children).toHaveLength(0)
+        expect(wrapper).toHaveClass('empty:hidden')
+      }
+    })
+
+    it('keeps every sidebar injection spot inside a self-collapsing wrapper', async () => {
+      const { container } = renderWithProviders(
+        <AppShell email="demo@example.com" groups={groups}>
+          <div>Child content</div>
+        </AppShell>,
+        { dict },
+      )
+
+      await waitFor(() => {
+        expect(screen.getByText('Users List')).toBeInTheDocument()
+      })
+
+      const sidebarSpotIds = ['backend:sidebar:top', 'backend:sidebar:nav', 'backend:sidebar:nav:footer', 'backend:sidebar:footer']
+      for (const spotId of sidebarSpotIds) {
+        const spot = container.querySelector(`[data-testid="injection-spot:${spotId}"]`)
+        expect(spot).not.toBeNull()
+        expect(spot!.closest('[data-sidebar-injection-wrapper="true"]')).not.toBeNull()
+      }
+    })
+
+    it('renders group separators on the group wrapper itself, skipping the last visible group', async () => {
+      const { container } = renderWithProviders(
+        <AppShell email="demo@example.com" groups={multiGroups}>
+          <div>Child content</div>
+        </AppShell>,
+        { dict },
+      )
+
+      await waitFor(() => {
+        expect(screen.getByText('Orders')).toBeInTheDocument()
+      })
+
+      const sidebar = screen.getByTestId('sidebar')
+      const groupWrappers = Array.from(sidebar.querySelectorAll('[data-sidebar-group="true"]'))
+      expect(groupWrappers).toHaveLength(multiGroups.length)
+      groupWrappers.forEach((wrapper, index) => {
+        const isLast = index === groupWrappers.length - 1
+        expect(wrapper).toHaveClass(isLast ? 'px-3' : 'border-b')
+        expect(wrapper.classList.contains('border-b')).toBe(!isLast)
+        expect(wrapper.classList.contains('pb-2')).toBe(!isLast)
+      })
+
+      // The old standalone bleeding separator elements must not come back — they were what
+      // forced the scroll container's negative-margin bleed in the first place.
+      expect(container.querySelectorAll('[data-sidebar-scroll="true"] div.border-t')).toHaveLength(0)
+    })
+
+    it('pads sidebar content blocks instead of bleeding the scroll container out of the aside', async () => {
+      const { container } = renderWithProviders(
+        <AppShell email="demo@example.com" groups={groups}>
+          <div>Child content</div>
+        </AppShell>,
+        { dict },
+      )
+
+      await waitFor(() => {
+        expect(screen.getByText('Users List')).toBeInTheDocument()
+      })
+
+      const scrollContainers = Array.from(container.querySelectorAll('[data-sidebar-scroll="true"]'))
+      expect(scrollContainers.length).toBeGreaterThan(0)
+      for (const scroller of scrollContainers) {
+        expect(scroller).toHaveClass('overflow-x-hidden')
+        for (const className of Array.from(scroller.classList)) {
+          expect(className.startsWith('-ml-')).toBe(false)
+          expect(className.startsWith('-mr-')).toBe(false)
+        }
+      }
+    })
+  })
+
   describe('two-level sidebar (settings/profile mode)', () => {
     it('renders main + section sidebars side-by-side when on a settings path', async () => {
       mockPathname = '/backend/entities/user'