Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[docs-infra] Remove random layout assignment #40862

Merged
merged 5 commits into from
Feb 14, 2024
Merged

[docs-infra] Remove random layout assignment #40862

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9b75979
[docs-infra] Remove random layout assignement
alexfauquette Jan 30, 2024
39a98f9
new Gtag behavior
alexfauquette Jan 31, 2024
359188e
Allow to store layout with distinct keys
alexfauquette Jan 31, 2024
59f1c27
fix lint
alexfauquette Jan 31, 2024
f5f1a19
move default definition
alexfauquette Feb 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion docs/src/modules/components/ApiPage.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,13 @@ Heading.propTypes = {
};

export default function ApiPage(props) {
const { descriptions, disableAd = false, pageContent } = props;
const {
descriptions,
disableAd = false,
pageContent,
defaultLayout = 'table',
layoutStorageKey,
} = props;
const t = useTranslate();
const userLanguage = useUserLanguage();

Expand Down Expand Up @@ -257,6 +263,8 @@ export default function ApiPage(props) {
propertiesDescriptions={propDescriptions}
componentName={pageContent.name}
spreadHint={spreadHint}
defaultLayout={defaultLayout}
layoutStorageKey={layoutStorageKey?.props}
/>
{cssComponent && (
<React.Fragment>
Expand Down Expand Up @@ -314,13 +322,17 @@ export default function ApiPage(props) {
slotGuideLink &&
t('api-docs.slotDescription').replace(/{{slotGuideLink}}/, slotGuideLink)
}
defaultLayout={defaultLayout}
layoutStorageKey={layoutStorageKey?.slots}
/>
<ClassesSection
componentClasses={componentClasses}
componentName={pageContent.name}
classDescriptions={classDescriptions}
spreadHint={t('api-docs.classesDescription')}
styleOverridesLink={styleOverridesLink}
defaultLayout={defaultLayout}
layoutStorageKey={layoutStorageKey?.classes}
displayClassKeys
/>
</MarkdownElement>
Expand All @@ -334,8 +346,14 @@ export default function ApiPage(props) {
}

ApiPage.propTypes = {
defaultLayout: PropTypes.oneOf(['collapsed', 'expanded', 'table']),
descriptions: PropTypes.object.isRequired,
disableAd: PropTypes.bool,
layoutStorageKey: PropTypes.shape({
classes: PropTypes.string,
props: PropTypes.string,
slots: PropTypes.string,
}),
pageContent: PropTypes.object.isRequired,
};

Expand Down
13 changes: 11 additions & 2 deletions docs/src/modules/components/ApiPage/sections/ClassesSection.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import { ComponentClassDefinition } from '@mui-internal/docs-utilities';
import Box from '@mui/material/Box';
import ToggleDisplayOption, {
API_LAYOUT_STORAGE_KEYS,
ApiDisplayOptions,
useApiPageOption,
} from 'docs/src/modules/components/ApiPage/sections/ToggleDisplayOption';
import ClassesList, { getHash } from 'docs/src/modules/components/ApiPage/list/ClassesList';
Expand Down Expand Up @@ -49,6 +50,8 @@ export type ClassesSectionProps = {
title: string;
titleHash: string;
level?: 'h2' | 'h3' | 'h4';
defaultLayout: ApiDisplayOptions;
layoutStorageKey?: string;
displayClassKeys: boolean;
styleOverridesLink: string;
};
Expand All @@ -64,10 +67,12 @@ export default function ClassesSection(props: ClassesSectionProps) {
level: Level = 'h2',
displayClassKeys,
styleOverridesLink,
defaultLayout,
layoutStorageKey = API_LAYOUT_STORAGE_KEYS.classes,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should have the default values for layoutStorageKey defined in ApiPage. I imagine if we override them, we want people to override them for the whole page.

} = props;
const t = useTranslate();

const [displayOption, setDisplayOption] = useApiPageOption(API_LAYOUT_STORAGE_KEYS.classes);
const [displayOption, setDisplayOption] = useApiPageOption(layoutStorageKey, defaultLayout);

if (!componentClasses || componentClasses.length === 0) {
return null;
Expand Down Expand Up @@ -101,7 +106,11 @@ export default function ClassesSection(props: ClassesSectionProps) {
</svg>
</a>
</Level>
<ToggleDisplayOption displayOption={displayOption} setDisplayOption={setDisplayOption} />
<ToggleDisplayOption
displayOption={displayOption}
setDisplayOption={setDisplayOption}
sectionType="classes"
/>
</Box>
{spreadHint && <p dangerouslySetInnerHTML={{ __html: spreadHint }} />}
{displayOption === 'table' ? (
Expand Down
12 changes: 10 additions & 2 deletions docs/src/modules/components/ApiPage/sections/PropertiesSection.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,10 +51,12 @@ export default function PropertiesSection(props) {
spreadHint,
hooksParameters = false,
hooksReturnValue = false,
defaultLayout,
layoutStorageKey = API_LAYOUT_STORAGE_KEYS.props,
} = props;
const t = useTranslate();

const [displayOption, setDisplayOption] = useApiPageOption(API_LAYOUT_STORAGE_KEYS.props);
const [displayOption, setDisplayOption] = useApiPageOption(layoutStorageKey, defaultLayout);
const formatedProperties = Object.entries(properties)
.filter(([, propData]) => propData.description !== '@ignore')
.map(([propName, propData]) => {
Expand Down Expand Up @@ -131,7 +133,11 @@ export default function PropertiesSection(props) {
</svg>
</a>
</Level>
<ToggleDisplayOption displayOption={displayOption} setDisplayOption={setDisplayOption} />
<ToggleDisplayOption
displayOption={displayOption}
setDisplayOption={setDisplayOption}
sectionType="props"
/>
</Box>
{spreadHint && <p dangerouslySetInnerHTML={{ __html: spreadHint }} />}
{displayOption === 'table' ? (
Expand All @@ -145,8 +151,10 @@ export default function PropertiesSection(props) {

PropertiesSection.propTypes = {
componentName: PropTypes.string,
defaultLayout: PropTypes.oneOf(['collapsed', 'expanded', 'table']).isRequired,
hooksParameters: PropTypes.bool,
hooksReturnValue: PropTypes.bool,
layoutStorageKey: PropTypes.string,
level: PropTypes.string,
properties: PropTypes.object.isRequired,
propertiesDescriptions: PropTypes.object.isRequired,
Expand Down
13 changes: 11 additions & 2 deletions docs/src/modules/components/ApiPage/sections/SlotsSection.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import Box from '@mui/material/Box';
import { useTranslate } from 'docs/src/modules/utils/i18n';
import ToggleDisplayOption, {
API_LAYOUT_STORAGE_KEYS,
ApiDisplayOptions,
useApiPageOption,
} from 'docs/src/modules/components/ApiPage/sections/ToggleDisplayOption';
import SlotsList from 'docs/src/modules/components/ApiPage/list/SlotsList';
Expand All @@ -16,6 +17,8 @@ export type SlotsSectionProps = {
title?: string;
titleHash?: string;
level?: 'h2' | 'h3' | 'h4';
defaultLayout: ApiDisplayOptions;
layoutStorageKey?: string;
spreadHint?: string;
};

Expand All @@ -28,10 +31,12 @@ export default function SlotsSection(props: SlotsSectionProps) {
titleHash = 'slots',
level: Level = 'h2',
spreadHint,
defaultLayout,
layoutStorageKey = API_LAYOUT_STORAGE_KEYS.slots,
} = props;
const t = useTranslate();

const [displayOption, setDisplayOption] = useApiPageOption(API_LAYOUT_STORAGE_KEYS.slots);
const [displayOption, setDisplayOption] = useApiPageOption(layoutStorageKey, defaultLayout);

if (!componentSlots || componentSlots.length === 0) {
return null;
Expand Down Expand Up @@ -63,7 +68,11 @@ export default function SlotsSection(props: SlotsSectionProps) {
</svg>
</a>
</Level>
<ToggleDisplayOption displayOption={displayOption} setDisplayOption={setDisplayOption} />
<ToggleDisplayOption
displayOption={displayOption}
setDisplayOption={setDisplayOption}
sectionType="slots"
/>
</Box>
{spreadHint && <p dangerouslySetInnerHTML={{ __html: spreadHint }} />}
{displayOption === 'table' ? (
Expand Down
88 changes: 40 additions & 48 deletions docs/src/modules/components/ApiPage/sections/ToggleDisplayOption.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,87 +7,54 @@ import TableChartRoundedIcon from '@mui/icons-material/TableChartRounded';
import ReorderRoundedIcon from '@mui/icons-material/ReorderRounded';
import useEnhancedEffect from '@mui/utils/useEnhancedEffect';

type ApiDisplayOptions = 'collapsed' | 'expanded' | 'table';
export type ApiDisplayOptions = 'collapsed' | 'expanded' | 'table';

const options: ApiDisplayOptions[] = ['collapsed', 'expanded', 'table'];
const DEFAULT_LAYOUT: ApiDisplayOptions = 'expanded';

export const API_LAYOUT_STORAGE_KEYS = {
default: 'apiPage_default',
slots: 'apiPage_slots',
props: 'apiPage_props',
css: 'apiPage_css',
classes: 'apiPage_classes',
} as const;

// https://stackoverflow.com/a/20084661
function isBot() {
return /bot|googlebot|crawler|spider|robot|crawling/i.test(navigator.userAgent);
}

function getRandomOption() {
if (isBot()) {
// When crawlers visit the page, they should not have to expand items
return DEFAULT_LAYOUT;
}
// A default layout is saved in localstorage at first render to make sure all section start with the same layout.
const savedDefaultOption = localStorage.getItem(
API_LAYOUT_STORAGE_KEYS.default,
) as null | ApiDisplayOptions;

if (savedDefaultOption !== null && options.includes(savedDefaultOption)) {
return savedDefaultOption;
}

const randomOption = options[Math.floor(options.length * Math.random())];
try {
localStorage.setItem(API_LAYOUT_STORAGE_KEYS.default, randomOption);
} catch (error) {
// Do nothing
}
return randomOption;
}

let neverHydrated = true;

function getOption(storageKey: string) {
function getOption(storageKey: string, defaultValue: ApiDisplayOptions): ApiDisplayOptions {
if (neverHydrated) {
return DEFAULT_LAYOUT;
return defaultValue;
}
try {
const savedOption = localStorage.getItem(storageKey);

if (savedOption !== null && options.includes(savedOption as ApiDisplayOptions)) {
return savedOption as ApiDisplayOptions;
}

const randomOption = getRandomOption();

return randomOption;
} catch (error) {
return DEFAULT_LAYOUT;
return defaultValue;
}
return defaultValue;
}

export function useApiPageOption(
storageKey: string,
defaultValue: ApiDisplayOptions,
): [ApiDisplayOptions, (newOption: ApiDisplayOptions) => void] {
const [option, setOption] = React.useState(getOption(storageKey));
const [option, setOption] = React.useState(getOption(storageKey, defaultValue));

useEnhancedEffect(() => {
neverHydrated = false;
const newOption = getOption(storageKey);
const newOption = getOption(storageKey, defaultValue);
setOption(newOption);
}, [storageKey]);
}, [storageKey, defaultValue]);

React.useEffect(() => {
if (option !== DEFAULT_LAYOUT) {
if (option !== defaultValue) {
const id = document.location.hash.slice(1);
const element = document.getElementById(id);
element?.scrollIntoView();
}
return undefined;
}, [option]);
}, [option, defaultValue]);

const updateOption = React.useCallback(
(newOption: ApiDisplayOptions) => {
Expand Down Expand Up @@ -141,10 +108,14 @@ const TooltipToggleButton = React.forwardRef<HTMLButtonElement, TooltipToggleBut
interface ToggleDisplayOptionProps {
displayOption: ApiDisplayOptions;
setDisplayOption: (newValue: ApiDisplayOptions) => void;
/**
* The type of section. This value is used to send correct event to Google Analytics.
*/
sectionType: 'classes' | 'props' | 'slots';
}

export default function ToggleDisplayOption(props: ToggleDisplayOptionProps) {
const { displayOption, setDisplayOption } = props;
const { displayOption, setDisplayOption, sectionType } = props;

const handleAlignment = (
event: React.MouseEvent<HTMLElement>,
Expand Down Expand Up @@ -182,13 +153,34 @@ export default function ToggleDisplayOption(props: ToggleDisplayOptionProps) {
},
}}
>
<TooltipToggleButton value="collapsed" aria-label="colapsed list" title="Collapse list view">
<TooltipToggleButton
value="collapsed"
aria-label="colapsed list"
title="Collapse list view"
data-ga-event-category="layout"
data-ga-event-action={sectionType}
data-ga-event-label="collapsed"
>
<ReorderRoundedIcon size="small" />
</TooltipToggleButton>
<TooltipToggleButton value="expanded" aria-label="expanded list" title="Expand list view">
<TooltipToggleButton
value="expanded"
aria-label="expanded list"
title="Expand list view"
data-ga-event-category="layout"
data-ga-event-action={sectionType}
data-ga-event-label="expanded"
>
<CalendarViewDayRoundedIcon />
</TooltipToggleButton>
<TooltipToggleButton value="table" aria-label="table" title="Table view">
<TooltipToggleButton
value="table"
aria-label="table"
title="Table view"
data-ga-event-category="layout"
data-ga-event-action={sectionType}
data-ga-event-label="table"
>
<TableChartRoundedIcon />
</TooltipToggleButton>
</ToggleButtonGroup>
Expand Down
14 changes: 13 additions & 1 deletion docs/src/modules/components/ComponentsApiContent.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Heading.propTypes = {
};

export default function ComponentsApiContent(props) {
const { descriptions, pageContents } = props;
const { descriptions, pageContents, defaultLayout = 'table', layoutStorageKey } = props;
const t = useTranslate();
const userLanguage = useUserLanguage();
const router = useRouter();
Expand Down Expand Up @@ -150,6 +150,8 @@ export default function ComponentsApiContent(props) {
spreadHint={spreadHint}
level="h3"
titleHash={`${componentNameKebabCase}-props`}
defaultLayout={defaultLayout}
layoutStorageKey={layoutStorageKey?.props}
/>
<br />
{cssComponent && (
Expand Down Expand Up @@ -216,6 +218,8 @@ export default function ComponentsApiContent(props) {
slotGuideLink &&
t('api-docs.slotDescription').replace(/{{slotGuideLink}}/, slotGuideLink)
}
defaultLayout={defaultLayout}
layoutStorageKey={layoutStorageKey?.slots}
/>
<ClassesSection
componentClasses={componentClasses}
Expand All @@ -224,6 +228,8 @@ export default function ComponentsApiContent(props) {
spreadHint={t('api-docs.classesDescription')}
titleHash={`${componentNameKebabCase}-classes`}
level="h3"
defaultLayout={defaultLayout}
layoutStorageKey={layoutStorageKey?.classes}
/>
</MarkdownElement>
<svg style={{ display: 'none' }} xmlns="http://www.w3.org/2000/svg">
Expand All @@ -237,7 +243,13 @@ export default function ComponentsApiContent(props) {
}

ComponentsApiContent.propTypes = {
defaultLayout: PropTypes.oneOf(['collapsed', 'expanded', 'table']),
descriptions: PropTypes.object.isRequired,
layoutStorageKey: PropTypes.shape({
classes: PropTypes.string,
props: PropTypes.string,
slots: PropTypes.string,
}),
pageContents: PropTypes.object.isRequired,
};

Expand Down
Loading
Loading