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

[docs-infra] Simplify CSS classes extraction in API docs generator #39808

Merged
merged 10 commits into from
Nov 30, 2023
Merged

[docs-infra] Simplify CSS classes extraction in API docs generator #39808

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
ad150e3
Simplify CSS classes extraction in API docs builder
michaldudak Nov 8, 2023
b68249d
Adapt the docs to the new data format
michaldudak Nov 8, 2023
93d34a5
Run the API generation script
michaldudak Nov 8, 2023
a12f8a9
Sort classes by name
michaldudak Nov 9, 2023
1369eb9
Fix ToC links to classes sections
michaldudak Nov 9, 2023
1fb8e6e
Discard malformed localStorage values in ToggleDisplayOption
michaldudak Nov 9, 2023
5120ad5
Merge branch 'master' into simplify-css-classes-extraction
michaldudak Nov 20, 2023
a394217
Do not show rule names on global state classes
michaldudak Nov 20, 2023
6586230
Fix docs export
michaldudak Nov 21, 2023
da5c2fb
Merge remote-tracking branch 'upstream/master' into simplify-css-clas…
michaldudak Nov 29, 2023
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: 7 additions & 13 deletions docs/src/modules/components/ApiPage.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,9 @@ import Ad from 'docs/src/modules/components/Ad';
import PropertiesSection, {
getPropsToC,
} from 'docs/src/modules/components/ApiPage/sections/PropertiesSection';
import CSSSection, { getCssToC } from 'docs/src/modules/components/ApiPage/sections/CssSection';
import ClassesSection from 'docs/src/modules/components/ApiPage/sections/ClassesSection';
import ClassesSection, {
getClassesToC,
} from 'docs/src/modules/components/ApiPage/sections/ClassesSection';
import SlotsSection from 'docs/src/modules/components/ApiPage/sections/SlotsSection';

export function getTranslatedHeader(t, header) {
Expand Down Expand Up @@ -78,7 +79,6 @@ export default function ApiPage(props) {
inheritance,
props: componentProps,
spread,
styles: componentStyles,
slots: componentSlots,
classes: componentClasses,
} = pageContent;
Expand Down Expand Up @@ -140,10 +140,10 @@ export default function ApiPage(props) {
inheritance,
themeDefaultProps: pageContent.themeDefaultProps,
}),
...getCssToC({
...getClassesToC({
t,
componentName: pageContent.name,
componentStyles,
componentClasses,
}),
componentSlots?.length > 0 && createTocEntry('slots'),
hasClasses && createTocEntry('classes'),
Copy link
Member

Choose a reason for hiding this comment

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

With this modification, you will get a ToC with

  • classes (expanded)
  • slots
  • classes

Should replace the hasClasses && createTocEntry('classes'), by ...getClassesToC({ }) to respect the page order

Copy link
Member Author

Choose a reason for hiding this comment

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

Good catch, thanks!
It won't actually ever call createTocEntry('classes') because I introduced a bug in hasClasses ;)

Expand Down Expand Up @@ -311,14 +311,6 @@ export default function ApiPage(props) {
</React.Fragment>
)}

<CSSSection
componentStyles={componentStyles}
classDescriptions={classDescriptions}
componentName={pageContent.name}
spreadHint={t('api-docs.cssDescription')}
styleOverridesLink={styleOverridesLink}
/>

<SlotsSection
componentSlots={componentSlots}
slotDescriptions={slotDescriptions}
Expand All @@ -334,6 +326,8 @@ export default function ApiPage(props) {
componentName={pageContent.name}
classDescriptions={classDescriptions}
spreadHint={t('api-docs.classesDescription')}
styleOverridesLink={styleOverridesLink}
displayClassKeys
/>
</MarkdownElement>
<svg style={{ display: 'none' }} xmlns="http://www.w3.org/2000/svg">
Expand Down
89 changes: 0 additions & 89 deletions docs/src/modules/components/ApiPage/list/CSSList.tsx
View file
Open in desktop

This file was deleted.

70 changes: 49 additions & 21 deletions docs/src/modules/components/ApiPage/list/ClassesList.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,49 +1,77 @@
/* eslint-disable react/no-danger */
import * as React from 'react';
import { styled } from '@mui/material/styles';
import { ComponentClassDefinition } from '@mui-internal/docs-utilities';
import { useTranslate } from 'docs/src/modules/utils/i18n';
import ExpendableApiItem, {
import ExpandableApiItem, {
ApiItemContaier,
} from 'docs/src/modules/components/ApiPage/list/ExpendableApiItem';
} from 'docs/src/modules/components/ApiPage/list/ExpandableApiItem';
import { brandingDarkTheme as darkTheme } from 'docs/src/modules/brandingTheme';

export type ClassesFormatedParams = {
className: string;
isGlobalStateClass: boolean;
cssClassName: string;
description?: string;
componentName: string;
};
const StyledApiItem = styled(ExpandableApiItem)(
({ theme }) => ({
'& p': {
margin: 0,
},
'& .prop-list-title': {
...theme.typography.body2,
fontWeight: theme.typography.fontWeightSemiBold,
color: theme.palette.text.primary,
paddingRight: 5,
whiteSpace: 'nowrap',
margin: 0,
},
'& .prop-list-class': {
margin: 0,
},
}),
({ theme }) => ({
[`:where(${theme.vars ? '[data-mui-color-scheme="dark"]' : '.mode-dark'}) &`]: {
'& .prop-list-title': {
color: `var(--muidocs-palette-grey-50, ${darkTheme.palette.grey[50]})`,
},
},
}),
);

type ClassesListProps = {
classes: ClassesFormatedParams[];
displayOption: 'collapsed' | 'expended';
componentName: string;
classes: ComponentClassDefinition[];
displayOption: 'collapsed' | 'expanded';
displayClassKeys?: boolean;
};
type HashParams = { componentName?: string; className: string };

export const getHash = ({ componentName, className }: HashParams) =>
`${componentName ? `${componentName}-` : ''}classes-${className}`;

export default function ClassesList(props: ClassesListProps) {
const { classes, displayOption } = props;

const { classes, displayOption, componentName, displayClassKeys } = props;
const t = useTranslate();

return (
<ApiItemContaier>
{classes.map((params) => {
const { className, isGlobalStateClass, cssClassName, description, componentName } = params;
{classes.map((classDefinition) => {
const { className, key, description, isGlobal } = classDefinition;

return (
<ExpendableApiItem
id={getHash({ componentName, className })}
key={className}
note={isGlobalStateClass ? t('api-docs.state') : ''}
title={cssClassName}
<StyledApiItem
id={getHash({ componentName, className: key })}
key={key}
note={isGlobal ? t('api-docs.state') : ''}
title={`.${className}`}
type="classes"
displayOption={displayOption}
isExtendable={!!description}
>
{description && <p dangerouslySetInnerHTML={{ __html: description }} />}
</ExpendableApiItem>
{displayClassKeys && (
<p className="prop-list-class">
<span className="prop-list-title">{'Rule name'}:</span>
<code className="Api-code">{key}</code>
</p>
)}
</StyledApiItem>
);
})}
</ApiItemContaier>
Expand Down
6 changes: 3 additions & 3 deletions ...onents/ApiPage/list/ExpendableApiItem.tsx → ...onents/ApiPage/list/ExpandableApiItem.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ export type ApiItemProps = {
className?: string;
children?: React.ReactNode;
sx?: SxProps;
displayOption?: 'collapsed' | 'expended';
displayOption?: 'collapsed' | 'expanded';
};

function ApiItem(props: ApiItemProps) {
Expand All @@ -197,10 +197,10 @@ function ApiItem(props: ApiItemProps) {
...other
} = props;

const [isExtended, setIsExtended] = React.useState(() => displayOption === 'expended');
const [isExtended, setIsExtended] = React.useState(() => displayOption === 'expanded');

React.useEffect(() => {
setIsExtended(displayOption === 'expended');
setIsExtended(displayOption === 'expanded');
}, [displayOption]);
return (
<Root
Expand Down
8 changes: 4 additions & 4 deletions docs/src/modules/components/ApiPage/list/PropertiesList.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@ import {
brandingDarkTheme as darkTheme,
brandingLightTheme as lightTheme,
} from 'docs/src/modules/brandingTheme';
import ExpendableApiItem, {
import ExpandableApiItem, {
ApiItemContaier,
} from 'docs/src/modules/components/ApiPage/list/ExpendableApiItem';
} from 'docs/src/modules/components/ApiPage/list/ExpandableApiItem';

const StyledApiItem = styled(ExpendableApiItem)(
const StyledApiItem = styled(ExpandableApiItem)(
({ theme }) => ({
'& .prop-list-description': {
marginBottom: 10,
Expand Down Expand Up @@ -144,7 +144,7 @@ export interface PropDescriptionParams {

interface PropertiesListProps {
properties: PropDescriptionParams[];
displayOption: 'collapsed' | 'expended';
displayOption: 'collapsed' | 'expanded';
}

export default function PropertiesList(props: PropertiesListProps) {
Expand Down
14 changes: 7 additions & 7 deletions docs/src/modules/components/ApiPage/list/SlotsList.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ import {
brandingDarkTheme as darkTheme,
} from 'docs/src/modules/brandingTheme';
import { useTranslate } from 'docs/src/modules/utils/i18n';
import ExpendableApiItem, {
import ExpandableApiItem, {
ApiItemContaier,
} from 'docs/src/modules/components/ApiPage/list/ExpendableApiItem';
} from 'docs/src/modules/components/ApiPage/list/ExpandableApiItem';

const StyledApiItem = styled(ExpendableApiItem)(
const StyledApiItem = styled(ExpandableApiItem)(
({ theme }) => ({
'.slot-classname, .slot-default-element': {
marginBottom: 8,
Expand Down Expand Up @@ -58,7 +58,7 @@ export const getHash = ({ componentName, className }: HashParams) =>

interface SlotsListProps {
slots: SlotsFormatedParams[];
displayOption: 'collapsed' | 'expended';
displayOption: 'collapsed' | 'expanded';
}

export default function SlotsList(props: SlotsListProps) {
Expand Down Expand Up @@ -91,16 +91,16 @@ export default function SlotsList(props: SlotsListProps) {
)}
{className && (
<p className="slot-classname">
<span className="prop-list-title">{t('api-docs.globalClass')}:</span>{' '}
<span className="prop-list-title">{t('api-docs.className')}:</span>{' '}
<code
dangerouslySetInnerHTML={{ __html: className }}
dangerouslySetInnerHTML={{ __html: `.${className}` }}
className="global-class-value"
/>
</p>
)}
{defaultValue && (
<p className="slot-default-element">
<span className="prop-list-title">{t('api-docs.default')}:</span>{' '}
<span className="prop-list-title">{t('api-docs.defaultComponent')}:</span>{' '}
<code className="default-slot-value">{defaultValue}</code>
</p>
)}
Expand Down
Loading