[docs][base-ui] Revise the structure of the Component docs (#38529)

mui · Aug 22, 2023 · 792a065 · 792a065
1 parent c832860
commit 792a065
Show file tree

Hide file tree

Showing 4 changed files with 13 additions and 85 deletions.
diff --git a/docs/data/base/components/autocomplete/autocomplete.md b/docs/data/base/components/autocomplete/autocomplete.md
@@ -8,15 +8,18 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
 
 # Autocomplete
 
-<p class="description">The Autocomplete component is a text input enhanced by a panel of suggested options.</p>
+<p class="description">An autocomplete component is a text input enhanced by a panel of suggested options.</p>
 
 {{"component": "modules/components/ComponentLinkHeader.js", "design": false}}
 
 {{"component": "modules/components/ComponentPageTabs.js"}}
 
 ## Introduction
 
-The autocomplete component is an enhanced text input that shows a list of suggested options as users type and lets them select an option from the list. It implements the WAI-ARIA Combobox pattern, and is typically used to assist users in completing form inputs or search queries faster.
+An autocomplete component is an enhanced text input that shows a list of suggested options as users type, and lets them select an option from the list.
+
+Base UI provides the `useAutocomplete` hook for building a custom Autocomplete.
+It implements the WAI-ARIA Combobox pattern, and is typically used to assist users in completing form inputs or search queries faster.
 
 {{"demo": "AutocompleteIntroduction", "defaultCodeOpen": false, "bg": "gradient"}}
 
@@ -30,51 +33,18 @@ To learn more about implementing a custom Autocomplete, you can explore the [`us
 
 :::
 
-## Usage
+## Hook
 
-After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this hook as follows:
+### Usage
 
 ```jsx
 import { useAutocomplete } from '@mui/base/useAutocomplete';
-
-export default function App() {
-  const {
-    getRootProps,
-    getInputProps,
-    getListboxProps,
-    getOptionProps,
-    groupedOptions,
-  } = useAutocomplete({
-    options: [
-      { label: 'The Dark Knight', year: 2008 },
-      { label: '12 Angry Men', year: 1957 },
-      { label: "Schindler's List", year: 1993 },
-    ],
-    getOptionLabel: (option) => option.label,
-  });
-
-  return (
-    <React.Fragment>
-      <div {...getRootProps()}>
-        <input {...getInputProps()} />
-      </div>
-      {groupedOptions.length > 0 && (
-        <ul {...getListboxProps()}>
-          {groupedOptions.map((option, index) => (
-            <li {...getOptionProps({ option, index })}>{option.label}</li>
-          ))}
-        </ul>
-      )}
-    </React.Fragment>
-  );
-}
 ```
 
-## Basics
-
-The useAutocomplete hook requires a list of `options` to be displayed when the textbox receives focus. The value must be chosen from a predefined set of values.
+The `useAutocomplete` hook requires a list of `options` to be displayed when the textbox receives focus.
+The value must be chosen from a predefined set of values.
 
-The following demo shows how to create a simple combobox, apply some styling, and write the selected value to a state variable using the `onChange` prop:
+The following demo shows how to create a simple combobox, apply styles, and write the selected value to a state variable using the `onChange` prop:
 
 {{"demo": "UseAutocomplete.js"}}
 
@@ -113,7 +83,7 @@ const {
 
 ### Controlled states
 
-The useAutocomplete hook has two states that can be controlled:
+The `useAutocomplete` hook has two states that can be controlled:
 
 1. the "value" state with the `value`/`onChange` props combination. This state represents the value selected by the user, for instance when pressing <kbd class="key">Enter</kbd>.
 2. the "input value" state with the `inputValue`/`onInputChange` props combination. This state represents the value displayed in the textbox.

diff --git a/docs/data/base/components/slider/slider.md b/docs/data/base/components/slider/slider.md
@@ -28,23 +28,10 @@ Sliders are ideal for interface controls that benefit from a visual representati
 
 ### Usage
 
-After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this component using the following basic elements:
-
 ```jsx
 import { Slider } from '@mui/base/Slider';
-
-export default function MyApp() {
-  return <Slider />;
-}
 ```
 
-### Basics
-
-The following demo shows how to create and style two basic sliders.
-Notice that both are set to a default value of 10 with the `defaultValue` prop, and the second slider cannot be adjusted due to the `disabled` prop:
-
-{{"demo": "UnstyledSliderBasic", "defaultCodeOpen": false}}
-
 ### Anatomy
 
 The Slider component is composed of a root `<span>` that houses several interior `<span>` elements:

diff --git a/docs/data/base/components/switch/switch.md b/docs/data/base/components/switch/switch.md
@@ -25,22 +25,10 @@ The Switch component provides users with a switch for toggling between two mutua
 
 ### Usage
 
-After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this component using the following basic elements:
-
 ```jsx
 import { Switch } from '@mui/base/Switch';
-
-export default function MyApp() {
-  return <Switch />;
-}
 ```
 
-### Basics
-
-The following demo shows how to assign styles and props to the Switch component:
-
-{{"demo": "UnstyledSwitchIntroduction"}}
-
 ### Anatomy
 
 The Switch component is composed of a root `<span>` that houses three interior slots—a track, a thumb, and an input:
@@ -96,7 +84,7 @@ import { useSwitch } from '@mui/base/useSwitch';
 The `useSwitch` hook lets you apply the functionality of a switch to a fully custom component.
 It returns props to be placed on the custom component, along with fields representing the component's internal state.
 
-Hooks _do not_ support [slot props](#slot-props), but they do support [customization props](#customization).
+Hooks _do not_ support [slot props](#custom-structure), but they do support [customization props](#customization).
 
 :::info
 Hooks give you the most room for customization, but require more work to implement.
@@ -115,4 +103,4 @@ You may not need to use hooks unless you find that you're limited by the customi
 
 ## Accessibility
 
-To make the switch component accessible, you should ensure that the corresponding labels reflect the current state of the switch.
+To make the Switch component accessible, you should ensure that the corresponding labels reflect the Switch's current state.
diff --git a/docs/data/base/components/tabs/tabs.md b/docs/data/base/components/tabs/tabs.md
@@ -30,30 +30,13 @@ Tabs are implemented using a collection of related components:
 
 ### Usage
 
-After [installation](/base-ui/getting-started/quickstart/#installation), you can start building with this component collection using the following basic elements:
-
 ```jsx
 import { Tab } from '@mui/base/Tab';
 import { TabsList } from '@mui/base/TabsList';
 import { TabPanel } from '@mui/base/TabPanel';
 import { Tabs } from '@mui/base/Tabs';
-
-export default function MyApp() {
-  return (
-    <Tabs>
-      <TabsList>
-        <Tab>{/* tab one */}</Tab>
-        <Tab>{/* tab two */}</Tab>
-      </TabsList>
-      <TabPanel>{/* panel one */}</TabPanel>
-      <TabPanel>{/* panel two */}</TabPanel>
-    </Tabs>
-  );
-}
 ```
 
-### Basics
-
 By default, Tab components and their corresponding panels are **zero-indexed** (i.e. the first tab has a `value` of `0`, then `1`, `2`, etc.).
 Clicking on a given Tab opens the panel with the same `value`, which corresponds to the order in which each component is nested within its container.