Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
181 lines (119 loc) · 6.1 KB

CONTRIBUTING.md

File metadata and controls

181 lines (119 loc) · 6.1 KB

Contributing to Base UI

Base UI vs. MUI organization

Base UI is an open-source project of the MUI organization. The repositories are part of the same codebase. mui/base-ui imports the code infrastructure from mui/material-ui. You can find the "contributing" guide for the main repository in mui/material-ui/CONTRIBUTING.md.

Most of the content in the main repository "contributing" guide applies to this repository. There are, however, a few differences:

  • The default GitHub branch might be different.
  • The local documentation site opens on a different port: 3005 instead of 3000.

Documentation

Autogenerated files

  • types.md files (for example, docs/src/app/(docs)/react/components/toggle/types.md) are autogenerated. Do not edit them manually. They are regenerated when running pnpm docs:dev (on page visit), pnpm docs:build, or pnpm docs:validate.
  • Some page.mdx files are page indexes (for example, docs/src/app/(docs)/react/components/page.mdx). You can tell because they contain a comment saying they are autogenerated. The list at the top of these files can be reordered and tagged (for example, [New], [Preview]), but the outline content below the list should not be manually edited. Run pnpm docs:build, pnpm docs:validate, or pnpm docs:dev (on page visit) to regenerate it.
  • Page indexes are useful for navigating the docs. Start at docs/src/app/(docs)/react/page.mdx to see a high-level overview, then follow links to narrow in on the specific page you need.

Adding a new component's docs page

  1. Create the component's page, for example, docs/src/app/(docs)/react/components/button/page.mdx.

  2. Create a types.ts file next to the page. For a single-part component, use createTypes:

    import { Toggle } from '@base-ui/react/toggle';
import { createTypes } from 'docs/src/utils/createTypes';

export const TypesToggle = createTypes(import.meta.url, Toggle);

    For a multi-part component, use createMultipleTypes:

    import { Checkbox } from '@base-ui/react/checkbox';
import { createMultipleTypes } from 'docs/src/utils/createTypes';

const { types, AdditionalTypes } = createMultipleTypes(import.meta.url, Checkbox);

export const TypesCheckbox = types;
export const TypesCheckboxAdditional = AdditionalTypes;

  3. Import and use the types component in the page:

    Single-part:

    ## API Reference

import { TypesToggle } from './types';

<TypesToggle />

    Multi-part:

    ## API Reference

import { TypesCheckbox } from './types';

### Root

<TypesCheckbox.Root />

### Indicator

<TypesCheckbox.Indicator />

  4. Start the dev server with pnpm docs:dev and visit the page (for example, http://localhost:3005/react/components/toggle). The types.md file is generated automatically. If you prefer not to open the browser, run pnpm docs:build to generate all files.

Adding a demo

Create a demo component file inside a demos/ directory next to the page, for example, docs/src/app/(docs)/react/components/button/demos/basic/ButtonBasic.tsx:

import * as React from 'react';
import { Button } from '@base-ui/react/button';

export default function ButtonBasic() {
  return (
    <div>
      <Button>Basic Button</Button>
    </div>
  );
}

Then create an index.ts that wraps the component with createDemo:

import { createDemo } from 'docs/src/utils/createDemo';
import ButtonBasic from './ButtonBasic';

export const DemoButtonBasic = createDemo(import.meta.url, ButtonBasic);

For demos with multiple variants (for example, Tailwind CSS and CSS Modules), use createDemoWithVariants:

import { createDemoWithVariants } from 'docs/src/utils/createDemo';
import CssModules from './css-modules';
import Tailwind from './tailwind';

export const DemoButtonHero = createDemoWithVariants(import.meta.url, { CssModules, Tailwind });

Page structure conventions

  • The page title is derived from the # h1 heading at the top of the page.mdx.
  • The page description is derived from the <Subtitle> component immediately after the h1.
  • Next.js export const metadata = {} should be placed at the end of the page.mdx file. It is typically used for SEO keywords. To hide a page from search engines, add robots: { index: false }.
# Toggle

<Subtitle>A two-state button that can be on or off.</Subtitle>

[//]: # 'page content'

export const metadata = {
  keywords: ['React Toggle', 'Toggle Button Component'],
};

Troubleshooting

Namespaces in types.md

For types exposed within a namespace, they must also be exposed as a globally accessible type for createTypes to work. For example, ToggleProps is exposed within the Toggle namespace, but it also needs to be exported at the top level of the module:

export type AlertDialogPopupProps = {
  // ...
};
export declare namespace AlertDialogPopup {
  // ...
  type Props = AlertDialogPopupProps;
}

Some symptoms of this issue are:

  • AlertDialogPopupProps is shown in types.md instead of AlertDialog.Popup.Props
  • DialogPopupProps is shown in types.md instead of AlertDialog.Popup.Props

Check the export's index.ts file, for example, packages/react/alert-dialog/index.ts, to verify that the type is exported at the top level. If not, add an export for it:

export type {
  DialogPopupProps as AlertDialogPopupProps,
  DialogPopupState as AlertDialogPopupState,
} from '../dialog/popup/DialogPopup';

Broken Type Links

If the broken links checker finds some links that don't have a corresponding id, check that all an exports parts are rendered.

If all parts are present, you might need to render the additional types component. By default, they are hidden on the page so they don't need a heading, but are needed to enable popovers.

## API reference

import { TypesCheckbox, TypesCheckboxAdditional } from './types';

### Root

<TypesCheckbox.Root />

### Indicator

<TypesCheckbox.Indicator />

<TypesCheckboxAdditional />