konnosDashboard
FirstLevelNav.tsx318 lines · main
1import { useParams } from 'common'
2import { Book, BookOpen } from 'lucide-react'
3import Link from 'next/link'
4import { Fragment, type ReactNode } from 'react'
5import SVG from 'react-inlinesvg'
6import { Button, cn } from 'ui'
7import { ShimmeringLoader } from 'ui-patterns'
8
9import { navigateToSection } from './Content/Content.utils'
10import { API_DOCS_CATEGORIES, DOCS_CONTENT, DOCS_MENU } from './ProjectAPIDocs.constants'
11import { InfiniteListDefault, type RowComponentBaseProps } from '@/components/ui/InfiniteList'
12import { useEdgeFunctionsQuery } from '@/data/edge-functions/edge-functions-query'
13import { useOpenAPISpecQuery } from '@/data/open-api/api-spec-query'
14import { usePaginatedBucketsQuery, type Bucket } from '@/data/storage/buckets-query'
15import { useIsFeatureEnabled } from '@/hooks/misc/useIsFeatureEnabled'
16import { BASE_PATH, DOCS_URL } from '@/lib/constants'
17import { useAppStateSnapshot } from '@/state/app-state'
18
19type DocsSections = typeof DOCS_MENU
20type DocsSection = DocsSections[number]
21type DocsSectionsSubset = readonly DocsSection[]
22type DocsCategory = DocsSection['key']
23type DocsContentRegistry = typeof DOCS_CONTENT
24type DocsSnippet = DocsContentRegistry[keyof DocsContentRegistry]
25
26const Separator = () => <hr className="border-t mt-3! pb-1 mx-3" />
27
28const MENU_BUTTON_CLASSES = cn(
29 'w-full px-4',
30 'text-left text-sm text-foreground-light',
31 'transition hover:text-foreground'
32)
33
34/**
35 * Gets the docs menu items based on feature flags.
36 * @returns An array of menu items to be displayed in the docs navigation.
37 */
38const useDocsMenu = (): DocsSectionsSubset => {
39 const {
40 projectAuthAll: authEnabled,
41 projectStorageAll: storageEnabled,
42 projectEdgeFunctionAll: edgeFunctionsEnabled,
43 realtimeAll: realtimeEnabled,
44 } = useIsFeatureEnabled([
45 'project_auth:all',
46 'project_storage:all',
47 'project_edge_function:all',
48 'realtime:all',
49 ])
50
51 return DOCS_MENU.filter((item) => {
52 if (item.key === 'user-management') return authEnabled
53 if (item.key === 'storage') return storageEnabled
54 if (item.key === 'edge-functions') return edgeFunctionsEnabled
55 if (item.key === 'realtime') return realtimeEnabled
56 return true
57 })
58}
59
60/**
61 * Gets the content snippets for a given documentation category.
62 * @param category - The category of documentation to retrieve snippets for.
63 * @returns An array of content snippets belonging to the specified category.
64 */
65const getSectionSnippets = (category: DocsCategory): DocsSnippet[] =>
66 Object.values(DOCS_CONTENT).filter((snippet) => snippet.category === category)
67
68export const FirstLevelNav = (): ReactNode => {
69 const { ref } = useParams()
70
71 const snap = useAppStateSnapshot()
72 const currentSection = snap.activeDocsSection[0]
73
74 const docsMenu = useDocsMenu()
75
76 return (
77 <>
78 <nav aria-labelledby="api-docs-rest-categories" className="px-2 py-4 border-b">
79 <h2 id="api-docs-rest-categories" className="sr-only">
80 REST API Docs
81 </h2>
82 {docsMenu.map((item) => {
83 const isActive = currentSection === item.key
84
85 return (
86 <Fragment key={item.key}>
87 <button
88 aria-current={isActive ? 'page' : undefined}
89 className={cn(
90 'w-full px-3 py-2 rounded-md',
91 'text-left text-sm',
92 'transition',
93 isActive && 'bg-surface-300'
94 )}
95 onClick={() => snap.setActiveDocsSection([item.key])}
96 >
97 {item.name}
98 </button>
99 {isActive && <Subsections category={item.key} />}
100 </Fragment>
101 )
102 })}
103 </nav>
104
105 <div className="px-2 py-4 border-b">
106 <Button
107 block
108 asChild
109 type="text"
110 size="small"
111 icon={
112 <SVG
113 src={`${BASE_PATH}/img/graphql.svg`}
114 style={{ width: `${16}px`, height: `${16}px` }}
115 className="text-foreground"
116 preProcessor={(code) => code.replace(/svg/, 'svg class="m-auto text-color-inherit"')}
117 />
118 }
119 onClick={() => snap.setShowProjectApiDocs(false)}
120 >
121 <Link className="justify-start!" href={`/project/${ref}/integrations/graphiql`}>
122 GraphiQL
123 </Link>
124 </Button>
125 <Button block asChild type="text" size="small" icon={<BookOpen />}>
126 <Link
127 href={`${DOCS_URL}/guides/graphql`}
128 target="_blank"
129 rel="noreferrer"
130 className="justify-start!"
131 >
132 GraphQL guide
133 </Link>
134 </Button>
135 </div>
136
137 <div className="px-2 py-4">
138 <Button block asChild type="text" size="small" icon={<Book />}>
139 <Link href={`${DOCS_URL}`} target="_blank" rel="noreferrer" className="justify-start!">
140 Documentation
141 </Link>
142 </Button>
143 <Button block asChild type="text" size="small" icon={<BookOpen />}>
144 <Link
145 href={`${DOCS_URL}/guides/api`}
146 target="_blank"
147 rel="noreferrer"
148 className="justify-start!"
149 >
150 REST guide
151 </Link>
152 </Button>
153 </div>
154 </>
155 )
156}
157
158type SubsectionsProps = {
159 category: DocsCategory
160}
161
162const Subsections = ({ category }: SubsectionsProps): ReactNode => {
163 const snippets = getSectionSnippets(category)
164
165 return (
166 <div className="space-y-2 py-2">
167 {snippets.map((snippet) => (
168 <button
169 key={snippet.key}
170 className={MENU_BUTTON_CLASSES}
171 onClick={() => {
172 navigateToSection(snippet.key)
173 }}
174 >
175 {snippet.title}
176 </button>
177 ))}
178 {category === API_DOCS_CATEGORIES.ENTITIES && <TablesSubsections />}
179 {category === API_DOCS_CATEGORIES.STORED_PROCEDURES && <DbFunctionsSubsections />}
180 {category === API_DOCS_CATEGORIES.STORAGE && <StorageSubsections />}
181 {category === API_DOCS_CATEGORIES.EDGE_FUNCTIONS && <EdgeFunctionsSubsections />}
182 </div>
183 )
184}
185
186const TablesSubsections = (): ReactNode => {
187 const { ref } = useParams()
188 const snap = useAppStateSnapshot()
189
190 const { data, isLoading } = useOpenAPISpecQuery(
191 { projectRef: ref },
192 { staleTime: 1000 * 60 * 10 }
193 )
194 const tables = data?.tables ?? []
195
196 // TODO: handle infinite loading of tables
197 return (
198 <>
199 {isLoading && <LoadingIndicator />}
200 {tables.length > 0 && <Separator />}
201 {tables.map((table) => (
202 <button
203 key={table.name}
204 className={MENU_BUTTON_CLASSES}
205 onClick={() => snap.setActiveDocsSection([API_DOCS_CATEGORIES.ENTITIES, table.name])}
206 >
207 {table.name}
208 </button>
209 ))}
210 </>
211 )
212}
213
214const DbFunctionsSubsections = (): ReactNode => {
215 const { ref } = useParams()
216 const snap = useAppStateSnapshot()
217
218 const { data, isLoading } = useOpenAPISpecQuery(
219 { projectRef: ref },
220 { staleTime: 1000 * 60 * 10 }
221 )
222 const functions = data?.functions ?? []
223
224 // TODO: handle virtualization of DB functions
225 return (
226 <>
227 {isLoading && <LoadingIndicator />}
228 {functions.length > 0 && <Separator />}
229 {functions.map((fn) => (
230 <button
231 key={fn.name}
232 className={MENU_BUTTON_CLASSES}
233 onClick={() =>
234 snap.setActiveDocsSection([API_DOCS_CATEGORIES.STORED_PROCEDURES, fn.name])
235 }
236 >
237 {fn.name}
238 </button>
239 ))}
240 </>
241 )
242}
243
244const BucketButton = ({ item: bucket, style }: RowComponentBaseProps<Bucket>) => {
245 const snap = useAppStateSnapshot()
246
247 return (
248 <button
249 key={bucket.name}
250 className={cn(MENU_BUTTON_CLASSES, 'py-1')}
251 style={style}
252 onClick={() => snap.setActiveDocsSection([API_DOCS_CATEGORIES.STORAGE, bucket.name])}
253 >
254 {bucket.name}
255 </button>
256 )
257}
258
259const StorageSubsections = (): ReactNode => {
260 const { ref } = useParams()
261
262 const { data, isLoading, isFetchingNextPage, hasNextPage, fetchNextPage } =
263 usePaginatedBucketsQuery({
264 projectRef: ref,
265 })
266 const buckets = data?.pages.flatMap((page) => page) ?? []
267
268 return (
269 <>
270 {isLoading && <LoadingIndicator />}
271 {buckets.length > 0 && <Separator />}
272 <InfiniteListDefault
273 className="max-h-80"
274 items={buckets}
275 getItemKey={(idx) => buckets[idx]?.name}
276 getItemSize={() => 28}
277 hasNextPage={!!hasNextPage}
278 isLoadingNextPage={isFetchingNextPage}
279 onLoadNextPage={fetchNextPage}
280 ItemComponent={BucketButton}
281 LoaderComponent={({ style }) => <LoadingIndicator style={{ ...style, width: '75%' }} />}
282 />
283 </>
284 )
285}
286
287const EdgeFunctionsSubsections = (): ReactNode => {
288 const { ref } = useParams()
289 const snap = useAppStateSnapshot()
290
291 const { data: edgeFunctions, isLoading } = useEdgeFunctionsQuery({ projectRef: ref })
292
293 // TODO: handle virtualization of edge functions
294 return (
295 <>
296 {isLoading && <LoadingIndicator />}
297 {(edgeFunctions ?? []).length > 0 && <Separator />}
298 {(edgeFunctions ?? []).map((fn) => (
299 <button
300 key={fn.name}
301 className={MENU_BUTTON_CLASSES}
302 onClick={() => snap.setActiveDocsSection([API_DOCS_CATEGORIES.EDGE_FUNCTIONS, fn.name])}
303 >
304 {fn.name}
305 </button>
306 ))}
307 </>
308 )
309}
310
311type LoadingIndicatorProps = {
312 className?: string
313 style?: React.CSSProperties
314}
315
316const LoadingIndicator = ({ className, style }: LoadingIndicatorProps) => (
317 <ShimmeringLoader style={style} className={cn('mx-2', className)} />
318)