|
| 1 | +'use client' |
| 2 | + |
| 3 | +import { createContext, type ReactNode, useContext, useEffect, useId, useRef } from 'react' |
| 4 | +import { parseAsString, useQueryState } from 'nuqs' |
| 5 | +import styles from '@/app/(product)/_components/settings-parts/settings-page.module.css' |
| 6 | +import { SETTING_ROW_PARAM } from '@/platform/shared/settings-search' |
| 7 | + |
| 8 | +const ROW_WAIT_MS = 4_000 |
| 9 | + |
| 10 | +/** A one-shot signal: nullable with no default, and stripped once answered. */ |
| 11 | +const settingRowParser = parseAsString.withOptions({ history: 'replace', scroll: false }) |
| 12 | + |
| 13 | +/** |
| 14 | + * Brings the row a Settings search result named into view once the section renders it, which may |
| 15 | + * be a chunk and a read away. The param is stripped when the row is found or the wait lapses, |
| 16 | + * because a conditional row may never come, and so a second click on the same result reveals it again. |
| 17 | + */ |
| 18 | +function useSettingRowReveal() { |
| 19 | + const [row, setRow] = useQueryState(SETTING_ROW_PARAM, settingRowParser) |
| 20 | + const rootRef = useRef<HTMLElement>(null) |
| 21 | + useEffect(() => { |
| 22 | + const root = rootRef.current |
| 23 | + if (!row || !root) return |
| 24 | + const selector = `[data-setting-label="${CSS.escape(row)}"]` |
| 25 | + const observer = new MutationObserver(reveal) |
| 26 | + const timer = setTimeout(settle, ROW_WAIT_MS) |
| 27 | + function stop() { |
| 28 | + observer.disconnect() |
| 29 | + clearTimeout(timer) |
| 30 | + } |
| 31 | + function settle() { |
| 32 | + stop() |
| 33 | + void setRow(null) |
| 34 | + } |
| 35 | + function reveal() { |
| 36 | + const element = root?.querySelector(selector) |
| 37 | + if (!element) return |
| 38 | + element.scrollIntoView({ block: 'center' }) |
| 39 | + settle() |
| 40 | + } |
| 41 | + observer.observe(root, { childList: true, subtree: true }) |
| 42 | + reveal() |
| 43 | + return stop |
| 44 | + }, [row, setRow]) |
| 45 | + return rootRef |
| 46 | +} |
| 47 | + |
| 48 | +/** The level of a settings page's heading: `h1` where the page is the document, `h2` under a tab's own heading. */ |
| 49 | +export type SettingsHeadingLevel = 'h1' | 'h2' |
| 50 | + |
| 51 | +interface SettingsPage { |
| 52 | + title: string |
| 53 | + description?: string |
| 54 | + headingLevel: SettingsHeadingLevel |
| 55 | + /** Names the page's region after whichever header it renders. */ |
| 56 | + headingId: string |
| 57 | +} |
| 58 | + |
| 59 | +const SettingsPageContext = createContext<SettingsPage | null>(null) |
| 60 | + |
| 61 | +/** |
| 62 | + * The level and id of the heading a sub-view's header renders: the page's own when it sits in a |
| 63 | + * {@link SettingsBody}, an unnamed `h2` outside one. |
| 64 | + */ |
| 65 | +export function useSettingsHeading(): { level: SettingsHeadingLevel; id?: string } { |
| 66 | + const page = useContext(SettingsPageContext) |
| 67 | + return page ? { level: page.headingLevel, id: page.headingId } : { level: 'h2' } |
| 68 | +} |
| 69 | + |
| 70 | +interface SettingsBodyProps { |
| 71 | + title: string |
| 72 | + /** The page's one-line summary under its title, from the Settings navigation metadata. */ |
| 73 | + description?: string |
| 74 | + headingLevel: SettingsHeadingLevel |
| 75 | + children: ReactNode |
| 76 | +} |
| 77 | + |
| 78 | +/** |
| 79 | + * The one body every settings page, organization or workspace, renders in: Paper's settings column, |
| 80 | + * the reveal of a row a Settings search result named, and the page's title and description for |
| 81 | + * the open section's {@link SettingsPageHeader}. The body draws no heading of its own: the section |
| 82 | + * renders exactly one header, the page's or a sub-view's `DetailHeader`, so a sub-view never stacks |
| 83 | + * under the page title. The surrounding chrome (breadcrumb, tab bar, navigation) stays outside. |
| 84 | + */ |
| 85 | +export function SettingsBody({ title, description, headingLevel, children }: SettingsBodyProps) { |
| 86 | + const headingId = useId() |
| 87 | + const reveal = useSettingRowReveal() |
| 88 | + return ( |
| 89 | + <SettingsPageContext.Provider value={{ title, description, headingLevel, headingId }}> |
| 90 | + <section ref={reveal} className={styles.body} aria-labelledby={headingId}> |
| 91 | + {children} |
| 92 | + </section> |
| 93 | + </SettingsPageContext.Provider> |
| 94 | + ) |
| 95 | +} |
| 96 | + |
| 97 | +/** |
| 98 | + * The page's title and description, as its navigation entry names them. A section renders it in |
| 99 | + * its main view and a sub-view renders `DetailHeader` instead, so the page has one header. Outside a |
| 100 | + * {@link SettingsBody} there is no page to name, so it renders nothing. |
| 101 | + */ |
| 102 | +export function SettingsPageHeader() { |
| 103 | + const page = useContext(SettingsPageContext) |
| 104 | + if (!page) return null |
| 105 | + return ( |
| 106 | + <header className={styles.header}> |
| 107 | + {page.headingLevel === 'h1' ? ( |
| 108 | + <h1 id={page.headingId} data-type='T076'> |
| 109 | + {page.title} |
| 110 | + </h1> |
| 111 | + ) : ( |
| 112 | + <h2 id={page.headingId} data-type='T076'> |
| 113 | + {page.title} |
| 114 | + </h2> |
| 115 | + )} |
| 116 | + {page.description && <p data-type='T067'>{page.description}</p>} |
| 117 | + </header> |
| 118 | + ) |
| 119 | +} |
0 commit comments