## What kind of change does this PR introduce?
visual parity fix and refresh + component extraction (stacked on #49942)
## What is the current behavior?
guide and reference sidebars each hand-roll their own collapsible
section visuals
## What is the new behavior?
- adds `NavSection` composition components (`NavSectionCaret`,
`NavSectionContent`, `NavSectionList`) shared by both navs via radix
`asChild`, so the rail, caret, and motion have a single source of truth
- fixes ui drift between both so navs get the same left rail beside
expanded children, the same caret and animation
- enhances link click area so space between rows is part of the click
target
| state | preview |
| -------|------|
| before | <img width="430" height="288" alt="image"
src="https://github.com/user-attachments/assets/0052d4b7-7793-43cf-8416-2a5445b95148"
/> |
| after | <img width="430" height="288" alt="image"
src="https://github.com/user-attachments/assets/42713ee3-e147-4e53-a58d-3f3de278264d"
/> |
## How to test?
1. run `pnpm dev:docs`
2. open [guide
page](http://localhost:3001/docs/guides/integrations/build-a-supabase-oauth-integration)
3. open [reference
page](http://localhost:3001/docs/reference/dart/introduction)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added animated expand/collapse behavior and rotating caret indicators
to documentation navigation sections.
* Added active-child indicators for clearer navigation context.
* **Improvements**
* Standardized spacing, borders, and animation styles across guide and
reference navigation.
* Improved collapsible animations to support varying content sizes more
reliably.
* Navigation items without links or child content, including disabled
nested items, are no longer displayed.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What kind of change does this PR introduce?
bug fix (accessibility) + test coverage
## What is the current behavior?
the guides sidebar renders invalid list markup: group headers and
dividers sit directly under the root `ul`, and accordion links render as
`li` elements without an owning list
fixes
[DOCS-1279](https://linear.app/supabase/issue/DOCS-1279/guides-sidebar-put-li-elements-directly-in-the-ul)
## What is the new behavior?
- sidebar renders a semantic hierarchy: every `ul` has only `li`
children, every `li` has an immediate list parent, and the menu header
sits outside the item list. pure markup change,
- docs e2e scans the guide navigation separately from the article and
blocks the `list` and `listitem` axe rules there against sample pages
that include different usages (flat links, grouped links, nested
accordion)
## How to test?
run the docs dev server, then the scoped a11y suite:
```bash
pnpm dev:docs
pnpm e2e:docs:a11y
```
## Follow up
visuals and behavior are unchanged here but better parity between
guide/reference is handled in the stacked pr
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Improved documentation navigation rendering for nested guide items,
active states, and disabled entries.
* Ensured navigation groups and child links use valid, testable list
structures.
* **Tests**
* Added coverage verifying that guide navigation changes run the
appropriate documentation pages.
* Confirmed unrelated documentation changes can be skipped by the
end-to-end workflow.
* **Chores**
* Updated documentation test scope detection to include guide navigation
changes.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## Stack
Draft stack extracted from `docs/monitoring`. Merge bottom-up. The
troubleshooting *catalog* rewrite (`content/troubleshooting` and the
Diagnosing UI) stays out of scope.
1. #49503 move inspect and advisors
2. #49501 split Studio logs from ClickHouse queries
3. #49500 treat reports as signal dashboards
4. #49502 add Observe the data hub
5. #49506 add agent setup components
6. #49504 add hire-an-agent templates
7. **#49505** restructure observability nav, overview, Detecting, and
flatten Observe the data ← **this PR**
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
Docs update. Top layer in the observability stack.
## What is the current behavior?
The section is still titled Monitoring and Debugging, with a Debugging /
Monitoring split that does not match the new pages. The debugging guide
is still the master layer-isolation + symptom table. Observe the data is
split into “what data” vs “where to observe it,” which duplicates the
source pages.
## What is the new behavior?
- Section title is Observability
- Overview groups Observe the data, Detect and resolve, Hire an agent,
and Export
- **Observe the data is flattened by source.** Logs, Metrics API,
Database, Advisors, and Reports each list where to read that source.
There is no separate MCP/API/CLI/Studio nav group.
- **Observe vs Detecting:** Observe is the catalog (what exists, how to
access it). Detecting is how to *use* those sources to pick up a Health
/ Security / Performance / Usage signal. Named errors skip to
Diagnosing.
- Studio Logs sits under Logs. Reports sits beside the other sources.
- Troubleshooting stays in the global menu and also appears as
Diagnosing under Detect and resolve
## Additional context
This is the last PR in the stack. Together the seven PRs reconstruct the
`docs/monitoring` observability IA and guide content, without shipping
the troubleshooting catalog overhaul.
<!-- CURSOR_AGENT_PR_BODY_END -->
<div><a
href="https://cursor.com/agents/bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a
href="https://cursor.com/background-agent?bcId=bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div>
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com>
Co-authored-by: Nik Richers <nik@validmind.ai>
## Problem
In order to update to react 19, we need to update several dependencies
## Solution
- migrate to the `radix` umbrella package to ease upgrade
- update some dependencies
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Consolidated Radix UI usage to a single unified package across apps
and packages, updated package manifests and workspace catalog entries.
No user-facing behavior, visuals, or public APIs changed.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Ivan Vasilov <vasilov.ivan@gmail.com>
* refactor(docs): enhance NavigationMenuGuideListItems component
* cleanup..
* Resolve formatting conflicts in NavigationMenuGuideListItems
* Came up with a crazy recursive approach...
* some changes.
* More cleanups...
* more cleanups....
* formatting the stuff
* refactor(navigation): remove sample menu data and optimize icon rendering in RecursiveNavigation
* cleanup...
* feat: enhance navigation with recursive dropdown indicators and performance optimizations
- Add visual chevron indicators for expandable sidebar items
- Implement recursive navigation system using existing NavMenuSection types
- Auto-expand accordion sections containing current active page on load/refresh
- Extract LinkContainer as independent component to prevent recreation on renders
- Fix React 19 compatibility issues with ref handling using useCallback pattern
- Resolve duplicate key warnings with improved key generation strategy
- Optimize accordion transition timing (500ms duration with ease-in-out) to prevent element overlap
- Preserve existing icon logic with hasLightIcon support for theme variants
- Maintain backward compatibility with existing navigation data structures
Performance improvements:
- Memoized recursive components to prevent unnecessary re-renders
- Stable component references for better React reconciliation
- Proper TypeScript interfaces with explicit prop definitions
UX improvements:
- Smooth accordion animations with physics-based easing
- Clear visual indicators for expandable menu items
- Automatic expansion of sections containing current page
- Professional-grade transition animations
Technical details:
- Uses existing NavMenuSection recursive type structure
- Implements containsActivePath helper for active page detection
- Leverages Radix UI accordion with proper data-state attributes
- Maintains all existing functionality including dynamic menu injection
* Cleanup...
* feat: implement cookie-based persisted state for navigation accordion
- Replace localStorage with cookie-based persistence for SSR compatibility
- Add proper cookie helpers with SameSite=Lax and 30-day expiration
- Implement initialization state to prevent hydration mismatches
- Maintain auto-expand functionality for active page sections
- Preserve user's manual accordion state across page refreshes and sessions
- Add debounced cookie updates (300ms) for performance optimization
- Use proper cookie naming convention: 'supabase-docs-nav-state'
Benefits:
- SSR compatible: Works with server-side rendering
- Cross-session persistence: Maintains state across browser sessions
- Better security: Cookies are more secure than localStorage
- Performance: Debounced updates prevent excessive cookie writes
- User experience: Seamless navigation state preservation
* refactor: implement individual item-based persistence following reference pattern
- Replace global state management with individual item persistence
- Use sessionStorage with 'nav-expansion-' prefix for each item
- Follow the exact pattern from reference: usePersistedExpansionState hook
- Maintain auto-expansion for active page sections
- Simplify state management by removing complex global state
- Each accordion item manages its own expansion state independently
- Preserve user's manual toggle state across page refreshes
- Use sessionStorage instead of cookies for better performance
Benefits:
- Cleaner architecture: Each item manages its own state
- Better performance: No global state updates
- Simpler logic: Direct item-to-storage mapping
- Reference pattern compliance: Follows established patterns
- Individual control: Each section can be toggled independently
- Session persistence: Maintains state during browser session
* refactor: implement URL-driven navigation state following Supabase docs pattern
- Replace sessionStorage persistence with URL-driven expansion state
- Follow the established Supabase docs pattern: URL as single source of truth
- Remove individual item persistence hooks in favor of pathname-based logic
- Implement useUrlDrivenExpansion hook that determines open sections from current URL
- Use getSectionsContainingPath to find all sections that should be expanded
- Remove manual toggle functionality - sections open/close based on URL navigation
- Maintain smooth transitions and visual indicators for expandable sections
- Ensure consistency and reliability by using URL as the definitive state source
Benefits:
- Reliability: URL is always the single source of truth
- Consistency: Matches existing Supabase docs navigation behavior
- Simplicity: No complex state management or storage concerns
- Performance: No localStorage/sessionStorage operations
- SSR Compatible: Works perfectly with server-side rendering
- Predictable: Navigation state is always consistent with current page
* persistant state.
* file delete
* cleanup..
* file cleanup
* cleanup...
* cleanup..
* formatting..
* aww shit that it.
---------
Co-authored-by: Alan Daniel <stylesshjs@gmail.com>
- Disabled pages were still showing up as navigation items on the command
menu, removing those as well.
- Integrations section was also not fully disabled, removing that.
* Refactor Drawer component and add date-fns dependency
Refactored the Drawer component for improved slot-based structure, updated styles, and added 'use client' directive. Added 'date-fns' as a dependency in design-system, updated tsconfig paths for icons, and marked ToggleGroup as a client component.
* nit: add env for svg path
* fix: instructions
* accent color docs and basic tidy
* copy value feature
* improve color contrast
* increase contrast on text-warning in light mode
* update changelog
* replace outdated text-warning utility classes
* remove redundant warning-600
* minor design-system docs updates
* docs updates
* remove unused brand-button class
* update docs
* fix: restore brand default
* update docs brand text color
* low hanging branded text fruit
* Nit refactor and clean up
* re-add Kemal’s README instructions for hot reload
---------
Co-authored-by: Jonathan Summers-Muir <MildTomato@users.noreply.github.com>
Co-authored-by: Joshen Lim <joshenlimek@gmail.com>
There were two bugs when trying to run the integrations page locally
with NEXT_PUBLIC_IS_PLATFORM=false:
1. The IS_PLATFORM check imported from common was not evaluating
correctly to a boolean. This is because I slapped a 'use client' on the
entire common package last year -_-""" which caused all its imports to
be evaluated to functions when used in server components. I have now
moved the 'use client's down to the submodules that actually need it.
2. When the integrations submenu is empty, the navigation menu errors
out because it expects all navigation items to either have children or
have links. Have updated this to gracefully hide empty headers.
* fix: make sidebar collapse work when hash is selected
* fix: persist sidebar highlight when hash is selected
* chore: cleanup
* fix: fix enterprise sso case
* set up multiple themes in studio
* set up multiple themes in studio
* set up multiple themes in docs and www
* update all resolvedTheme to also include deep-dark
* update all resolvedTheme checks to also include deep-dark
* update tailwind.config.js tokens
* update tailwind.config.js tokens
* update leftover scale12 token
* update if resolvedTheme _doesn't_ include 'dark'
* update more styling tokens
* add dynamic themes to CmdK
* fix nav and footer for multi theme
* add data-theme selector output to transformTokens.js
* update code-hike.css to target data-theme css
* update tailwindcss to ^3.3.5
* ThemeImage with light and dark src for www and docs
* add brand-button styling token
* update old dark theme boolean
* update old dark theme boolean
* make homepage product visuals themeable
* update product page themed images
* update badge green with brand
* fix roles list appearance
* fix auth widget in auth page
* update more dark logic
* update more dark logic
* add button default bg and border
* update pricing page theme styling
* clean up Themeimage
* remove forceDark in homepage
* update dark:border-dark occurrences
* update dark:border-dark occurrences
* fix dark mode base colors
* remove foreground-strong
* fix notification badge bg
* remove some dark: selectors
* update dark: selectors
* update code-hike deep dark bg color
* fix comment typo
* update border-button-hover token
* fix customer story logo
* remove some more dark: selectors
* restore forceDark in www homepage
* fix auth react icon
* fix homepage product visuals
* remove theme
* add brand-link token
* fix checkbox bg
* npm install
* more visible EntityListItem active bg
* fix --background-alternative-default css vars
---------
Co-authored-by: Jonathan Summers-Muir <MildTomato@users.noreply.github.com>
* migrate some www components to tokens
* consolidate InteractiveShimmerCard to Panel component
* update tokens in blog
* update tokens in careers page
* update tokens in customers section
* update tokens in open-source section
* update tokens in Realtime page
* update tokens in Storage and Vector
* update tokens in SplitCodeBlockCarousel
* update tokens in PGCharts
* remove unused css files
* update tokens in Card
* update tokens in Pricing page
* clean up priving page imports
* remove hardcoded theme vars
* migrate first half of defaultTheme.ts to tokens
* migrate second half of defaultTheme.ts to tokens
* improve inputs
* add foreground to text-light and text-lighter
* add foreground to text-light and text-lighter
* migrate docs components with styling tokens
* migrate docs components with styling tokens
* fix broken Repos component
* fix broken classes in blog
* update tokens on Button and other components
* update tokens on IconPanel
* update studio main layout base styling tokens
* update tokens across studio, docs and www
* update tokens across studio, docs and www
* update ui/Panel to styling tokens
* update ExampleProject and TableEditorMenu tokens
* www vector page tokens
* update studio UI tokens
* update other studio UI tokens
* update more studio UI tokens
* change tokens here, change tokens there
* finish updating colors with tokens variables
* add gui sandbox for theme experimentation
* use common package for www, docs and studio and fix Command K tokens
* provide light mode default tokens options
* fix conflict leftover
* update loading line
* fix className typo
* fix prettier
* update themeSandbox preset default values
* fix text-background0
* prettier
* update warningBanner with warning color
* switch all border-border with border-default
* improve border-secondary and foreground-muted in light mode
* force ring color on toggle
* fix button bg color and border-muted light token
* fix input bg color
* fix dark button hover
* fix homepage product card
* fix code-hike table header colors
* button dark border
* remove tabIndex leftover from homepage main ctas
---------
Co-authored-by: Kevin Grüneberg <k.grueneberg1994@gmail.com>
Co-authored-by: Jonathan Summers-Muir <MildTomato@users.noreply.github.com>
* update deps + image codemod (studio)
* update next links (studio)
* update deps
* update links (ui)
* remove next-transpile-modules
* move next-themes dependency
* chore: update ConfirmDialog
* chore: remove old ConfirmModal js file. migrated to TS
* dependency wrangling
* remove empty page
* update next links (www)
* First run bump react-data-grid-v7 beta 4
* fix package-lock.json
* more deps wrangling
* update recharts
* update sentry options
* fix some broken things in www
* studio fixes
* fix graphiql
* fix studio build
* fix menu hydration
* small build error
* update turbo
* fix www typescript errors
* docs image codemod
* links codemod docs
* fix docs typescript errors
* move useConsent to ui to prevent circular deps
* Fix links
* Fix homepage
* Fix links
* move studio/ to apps/
* Revert "move studio/ to apps/"
This reverts commit 1b0a985fcb.
* disable outputFileTracingRoot
* remove outputFileTracingRoot
* fix homepage product cards
* fix PrivacySettings links
* Fix links
* Fix the build for www.
* Minor fixes for JWTGenerator.
* Fix the docs and ui tests.
* Revert codehike back to 0.8.3
* remove ConfirmAlert()
* reenable babel because mobx hates me
* fix blog image and comparison page avatar
* Fix svg errors
* update image synthax
* Fix code hike
* Move the button in a div so that it doesn't inherit its parent height and make the button look weird.
* When components are defined in a component, they get recreated on each render. This makes them unstable in certain cases and causes infinite rerenders.
* Replace the next/head usage with next/script.
* Chore/upgrade next 13 fix table editor (#18431)
* fix table editor styling and fix row deletion logic
* Fix deleting selected rows from header, and fix checkboxes not clearing up
* Fix deleting all rows when filter applied, and fix deleting all rows
* Fix grid size styling issue
* Fix TS error
* Hydration errors
* studio org pages fixes
* fix more studio links
* audit logs fixes
* dropdown icon styling fixes
* fix some images in www
* upgrade to next 14
* try new sentry wrapper for api
* see if this is even invoked
* Revert "see if this is even invoked"
This reverts commit 86c3973ffa.
* Revert "try new sentry wrapper for api"
This reverts commit f67623ebad.
* Revert "upgrade to next 14"
This reverts commit a24dd6131e.
* chore: allow node version 19/20
* Try to fix the LogTable so that it renders with the newer "react-data-grid" version.
* Fix type errors in the log renderer code.
* Fix the replication screen.
* Add the CSS for the GraphiQL.
* Fix SQL editor results rendering
* Lint
* Fix SQL editor results height issue
* Fix auth RLS not invalidating RQ when toggling RLS
* Fix database tables new/edit column regressed
* Fix migrations page empty state if migrations schema not yet created
* Fix API side panel docs temp remove postgrest text for column description PK and FK
* Fix + improve timeout handling in SQL editor
---------
Co-authored-by: Jonathan Summers-Muir <MildTomato@users.noreply.github.com>
Co-authored-by: Joshen Lim <joshenlimek@gmail.com>
Co-authored-by: Francesco Sansalvadore <f.sansalvadore@gmail.com>
Co-authored-by: Terry Sutton <saltcod@gmail.com>
Co-authored-by: Ivan Vasilov <vasilov.ivan@gmail.com>
Co-authored-by: Kevin Grüneberg <k.grueneberg1994@gmail.com>
Danny White
