[docs] Convert alpha component docs to new docs template #392

colmtuite · 2024-05-02T03:36:33Z

Preview: https://deploy-preview-392--base-ui.netlify.app/base-ui/react-checkbox/

github-actions · 2024-05-02T03:36:59Z

docs/data/base/components/number-field/number-field.md


-{{"demo": "UnstyledNumberFieldIntroduction", "defaultCodeOpen": false, "bg": "gradient"}}
+Base UI components are all available as a single package.


🚫 [vale] _{reported by reviewdog 🐶}
[MUI.MuiBrandName] Use a non-breaking space (option+space on Mac, Alt+0160 on Windows or AltGr+Space on Linux, instead of space) for brand name ('Base UI' instead of 'Base UI')

github-actions · 2024-05-02T03:36:59Z

docs/data/base/components/switch/switch.md


-{{"demo": "UnstyledSwitchIntroduction", "defaultCodeOpen": false, "bg": "gradient"}}
+Base UI components are all available as a single package.


🚫 [vale] _{reported by reviewdog 🐶}
[MUI.MuiBrandName] Use a non-breaking space (option+space on Mac, Alt+0160 on Windows or AltGr+Space on Linux, instead of space) for brand name ('Base UI' instead of 'Base UI')

github-actions · 2024-05-02T03:36:59Z

docs/data/base/components/checkbox/checkbox.md


-{{"demo": "UnstyledCheckboxIntroduction", "defaultCodeOpen": false, "bg": "gradient"}}
+Base UI components are all available as a single package.


🚫 [vale] _{reported by reviewdog 🐶}
[MUI.MuiBrandName] Use a non-breaking space (option+space on Mac, Alt+0160 on Windows or AltGr+Space on Linux, instead of space) for brand name ('Base UI' instead of 'Base UI')

docs/data/base/components/checkbox/checkbox.md

docs/data/base/components/switch/switch.md

michaldudak · 2024-05-02T07:56:02Z

Maybe it's something to address separately (and later): I find the style of these three components' demos quite different. It would be great if we restyled them so they feel like they belong to the same design system.

colmtuite · 2024-05-02T08:47:08Z

I find the style of these three components' demos quite different.

@michaldudak Yep the design consistency, design quality, CSS consistency, and CSS quality needs to be improved. I'll do it in a separate PR.

docs/data/base/components/checkbox/checkbox.md

atomiks · 2024-05-02T10:52:11Z

docs/data/base/components/number-field/number-field.md


 ## Accessibility

-Ensure the number field has an accessible name via a `label` element.
+Ensure the number field has an accessible name via a `<label/>` element.


<label> rather than <label/> is used for the other documents. It would be good to have a code example like they do as well here.

atomiks · 2024-05-02T10:53:53Z

docs/data/base/components/number-field/number-field.md

+```jsx
+<NumberField.Input render={(props) => <MyCustomInput {...props} />}> />
+```


We should show the two methods now that we support them:

<NumberField.Input render={<MyCustomInput />} />

This is where it's important to mention that the components need to forwardRef and spread all props to the underlying DOM element ("be open for extension")

(This one also has a stray > that I've removed)

<NumberField.Input render={(props) => <MyCustomInput {...props} />} />

Since this impacts most components and is duplicate content, I'm gonna move this into the global page in the "getting started" section. We can still include this little section on each page with a link to the more detailed page, but I think we should avoid duplicating this large block on every component page.

flaviendelangle

Just a few nitpicks while reading the new doc

docs/data/base/components/number-field/number-field.md

flaviendelangle · 2024-05-28T10:03:05Z

docs/data/base/components/number-field/number-field.md


 {{"component": "modules/components/ComponentLinkHeader.js", "design": false}}

 {{"component": "modules/components/ComponentPageTabs.js"}}

-## Introduction
+{{"demo": "UnstyledNumberFieldIntroduction", "defaultCodeOpen": false, "bg": "gradient"}}


What is the logic behind the style of each CSS technology in this demo?
On the checkbox we have:

MUI System: blue

Tailwind CSS: pink

Plain CSS: grey

Here we have:

MUI System: grey

Tailwind CSS: darker grey

Plain CSS: grey

I personally think having the color switch when you change CSS technology is a great visual indication that something did change.
And having coherent colors throughout the components would be nice.

Will redesign the demos in a separate PR.

flaviendelangle · 2024-05-28T10:06:30Z

docs/data/base/components/switch/switch.md

 import * as Switch from '@base_ui/react/Switch';
 ```

-### Anatomy
+## Anatomy


I think we miss the equivalent of these section

Same for Checkbox

Will consider for a separate PR.

flaviendelangle · 2024-05-28T10:10:33Z

docs/data/base/components/tabs/tabs.md

@@ -84,18 +84,6 @@ Though not required, you can add the `value` prop to the Tab and Tab Panel to
 </Tabs.Root>


Not strictly related to this PR, but having a demo on the "Orientation" section instead of just a text would be great

We're making an effort to minimise the page length. I think this is less important for an unstyled lib, since there's nothing really to see here except the orientation changing. It only gets interesting when you apply a height restriction, which would only happen in styled land.

So I'll skip this for now but will keep it in mind and maybe revisit once we make other unrelated docs improvements, and get a better sense of how many demos we can add before the pages feel too long.

samuelsycamore

These are looking really good! This review is mostly about style and formatting consistency.

samuelsycamore · 2024-05-30T15:32:31Z

docs/data/base/components/checkbox/checkbox.md

@@ -9,108 +9,78 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/

 # Checkbox

-<p class="description">Checkboxes give users binary choices when presented with multiple options in a series.</p>
+<p class="description">Checkbox give users a binary choice between multiple options in a series.</p>


Suggested change

Checkbox give users a binary choice between multiple options in a series.

Checkbox gives users a binary choice between multiple options in a series.

I think I prefer it in plural form though

Suggested change

Checkbox give users a binary choice between multiple options in a series.

Checkboxes give users a binary choice between multiple options in a series.

Will leave it in singular form because we need to apply either singular or plural to all components here, and we run into issues with plural. Fixed the typo though.

samuelsycamore · 2024-05-30T15:33:26Z

docs/data/base/components/checkbox/checkbox.md


- **Forward all props**: Your component should spread all props to the underlying element.
- **Forward the `ref`**: Your component should use [`forwardRef`](https://react.dev/reference/react/forwardRef) to ensure the Checkbox components can access the element via a ref.
+Checkbox is composed of two components.


Suggested change

Checkbox is composed of two components.

Checkbox is composed of two components:

samuelsycamore · 2024-05-30T15:34:14Z

docs/data/base/components/checkbox/checkbox.md

 ```

-### Indeterminate state
+## Indeterminate state

 To make the checkbox indeterminate, add the `indeterminate` prop to override the appearance of the checkbox. The checkbox remains in an indeterminate state regardless of user interaction until set back to `false`.


Always capitalize component names

Suggested change

To make the checkbox indeterminate, add the `indeterminate` prop to override the appearance of the checkbox. The checkbox remains in an indeterminate state regardless of user interaction until set back to `false`.

To make the Checkbox indeterminate, add the `indeterminate` prop to override the appearance of the Checkbox. The Checkbox remains in an indeterminate state regardless of user interaction until set back to `false`.

samuelsycamore · 2024-05-30T15:35:16Z

docs/data/base/components/checkbox/checkbox.md


 To make the checkbox indeterminate, add the `indeterminate` prop to override the appearance of the checkbox. The checkbox remains in an indeterminate state regardless of user interaction until set back to `false`.

 {{"demo": "UnstyledCheckboxIndeterminate.js"}}

-An indeterminate checkbox's main use case is representing the state of a parent checkbox where only some of its children are checked:
+The primary use case for an indeterminate checkbox is representing the state of a parent checkbox where only some of its children are checked.


just pointing this out for the sake of clarification: lowercase "checkbox" works in this context since we're discussing the general concept rather than the specific Base UI component.

samuelsycamore · 2024-05-30T15:36:12Z

docs/data/base/components/number-field/number-field.md

-### Anatomy
+## Anatomy
+
+NumberField is implemented using a collection of related components:


Suggested change

NumberField is implemented using a collection of related components:

Number Field is implemented using a collection of related components:

If we're referencing the actual component—as we want to emphasise via capitalisation—we should omit the space, since we're not talking about a "number field" in general, we're talking about Base UI's "NumberField".

The convention we've established is to treat these component names as proper nouns, capitalized and with spaces between words, to differentiate between The Base UI Component and the concept of such a component. Material UI used to (inconsistently) style these names like NumberField but we've moved to Number Field over the last couple years. This doc explains the conventions: https://www.notion.so/mui-org/Style-conventions-for-MUI-components-and-products-dff7d2d7d1ba4a4abd47f48cf345b800

Ok I updated it

samuelsycamore · 2024-05-30T15:45:08Z

docs/data/base/components/number-field/number-field.md

@@ -190,46 +189,40 @@ The pointer is locked while scrubbing, allowing the user to scrub infinitely wit
 </NumberField.ScrubArea>
 ```

-In your CSS, ensure any `label` elements inside the `ScrubArea` specify `cursor: unset`. You can rotate the above macOS-style cursor 90 degrees using a `transform` style.
+In your CSS, ensure any `<label/>` elements inside the `ScrubArea` specify `cursor: unset`. You can rotate the above macOS-style cursor 90 degrees using a `transform` style.


Suggested change

In your CSS, ensure any `<label/>` elements inside the `ScrubArea` specify `cursor: unset`. You can rotate the above macOS-style cursor 90 degrees using a `transform` style.

In your CSS, ensure any `<label>` elements inside the Scrub Area specify `cursor: unset`.

You can rotate the above macOS-style cursor 90 degrees using a `transform` style.

samuelsycamore · 2024-05-30T15:45:20Z

docs/data/base/components/number-field/number-field.md

@@ -190,46 +189,40 @@ The pointer is locked while scrubbing, allowing the user to scrub infinitely wit
 </NumberField.ScrubArea>
 ```

-In your CSS, ensure any `label` elements inside the `ScrubArea` specify `cursor: unset`. You can rotate the above macOS-style cursor 90 degrees using a `transform` style.
+In your CSS, ensure any `<label/>` elements inside the `ScrubArea` specify `cursor: unset`. You can rotate the above macOS-style cursor 90 degrees using a `transform` style.

 :::info
 In Safari, the pointer is not locked. However, this doesn't affect the ability to scrub infinitely.


Suggested change

In Safari, the pointer is not locked. However, this doesn't affect the ability to scrub infinitely.

In Safari, the pointer is not locked.

However, this doesn't affect the ability to scrub infinitely.

samuelsycamore · 2024-05-30T15:46:12Z

docs/data/base/components/number-field/number-field.md


 ## Accessibility

-Ensure the number field has an accessible name via a `label` element.
+Ensure the number field has an accessible name via a `<label/>` element.


Suggested change

Ensure the number field has an accessible name via a `<label/>` element.

Ensure the Number Field has an accessible name via a `<label>` element.

I've already changed this based on conflicting feedback, but will go with this suggested change since this is what I had initially. We can get our ducks in a row later on I guess.

samuelsycamore · 2024-05-30T15:46:33Z

docs/data/base/components/switch/switch.md

-### Anatomy
+## Anatomy
+
+Switch is composed of two components.


Suggested change

Switch is composed of two components.

Switch is composed of two components:

samuelsycamore · 2024-05-30T15:46:49Z

docs/data/base/components/switch/switch.md


-The Switch component is composed of a root that houses one interior slot—a thumb:
+- `<Switch.Root />` renders a `<button>`.
+- `<Switch.Thumbs />` renders a `<span>` for providing a visual indicator.


Suggested change

- `<Switch.Thumbs />` renders a `` for providing a visual indicator.

- `<Switch.Thumb />` renders a `` for providing a visual indicator.

colmtuite · 2024-05-30T18:22:01Z

@flaviendelangle @samuelsycamore Thanks for the feedback. I've pushed a commit incorporating your changes.

colmtuite · 2024-05-31T15:28:51Z

Any approvals going? @atomiks @samuelsycamore

samuelsycamore · 2024-05-31T16:23:07Z

docs/data/base/components/number-field/number-field.md


-The `ScrubArea` subcomponent lets users scrub the value with their pointer as a faster alternative to the stepper buttons. This is useful in high-density UIs, such as an image editor that changes the width, height, or location of a layer:
+The `ScrubArea` subcomponent lets users increment/decrement the value via a click+drag interaction with pointer, as a faster alternative to the stepper buttons. This is useful in high-density UIs, such as an image editor that changes the width, height, or location of a layer. You could wrap an icon or a `<label/>` in the `ScrubArea` component.


Suggested change

The `ScrubArea` subcomponent lets users increment/decrement the value via a click+drag interaction with pointer, as a faster alternative to the stepper buttons. This is useful in high-density UIs, such as an image editor that changes the width, height, or location of a layer. You could wrap an icon or a `<label/>` in the `ScrubArea` component.

The Scrub Area subcomponent lets users increment and decrement the value via a click-and-drag interaction with pointer, as a faster alternative to the stepper buttons.

This is useful in high-density UIs, such as an image editor that changes the width, height, or location of a layer.

You could wrap an icon or a `<label>` in the Scrub Area component.

@flaviendelangle is this description of scrubbing more clear to you?

colmtuite added 3 commits May 2, 2024 04:08

Convert NumberField docs to new docs template

c00ec7b

Convert Switch docs to new docs template

b78fa9c

Convert Checkbox docs to new docs template

23fc607

colmtuite requested review from atomiks and michaldudak May 2, 2024 03:36

github-actions bot reviewed May 2, 2024

View reviewed changes

michaldudak changed the title ~~Convert alpha component docs to new docs template~~ [docs] Convert alpha component docs to new docs template May 2, 2024

michaldudak added the docs Improvements or additions to the documentation label May 2, 2024

michaldudak reviewed May 2, 2024

View reviewed changes

docs/data/base/components/checkbox/checkbox.md Outdated Show resolved Hide resolved

michaldudak reviewed May 2, 2024

View reviewed changes

docs/data/base/components/switch/switch.md Outdated Show resolved Hide resolved

colmtuite added 2 commits May 2, 2024 09:42

Consistent naming for render prop section

f10cbad

Consistent a11y sections

94fe6fb

colmtuite requested a review from michaldudak May 2, 2024 08:45

michaldudak reviewed May 2, 2024

View reviewed changes

docs/data/base/components/checkbox/checkbox.md Outdated Show resolved Hide resolved

Rearrange render prop sections

1129343

colmtuite requested a review from michaldudak May 2, 2024 10:13

atomiks reviewed May 2, 2024

View reviewed changes

colmtuite requested a review from samuelsycamore May 2, 2024 17:08

flaviendelangle reviewed May 28, 2024

View reviewed changes

samuelsycamore reviewed May 30, 2024

View reviewed changes

colmtuite added 2 commits May 30, 2024 19:07

Incorproate flaviens feedback

cebc5ec

Incorporate feedback from sam

21d116f

Add space to NumberField

9b73d83

samuelsycamore reviewed May 31, 2024

View reviewed changes


		{{"demo": "UnstyledNumberFieldIntroduction", "defaultCodeOpen": false, "bg": "gradient"}}
		Base UI components are all available as a single package.


		{{"demo": "UnstyledSwitchIntroduction", "defaultCodeOpen": false, "bg": "gradient"}}
		Base UI components are all available as a single package.


		{{"demo": "UnstyledCheckboxIntroduction", "defaultCodeOpen": false, "bg": "gradient"}}
		Base UI components are all available as a single package.

		@@ -84,18 +84,6 @@ Though not required, you can add the `value` prop to the Tab and Tab Panel to
		</Tabs.Root>

	<p class="description">Checkbox give users a binary choice between multiple options in a series.</p>
	<p class="description">Checkbox gives users a binary choice between multiple options in a series.</p>

	<p class="description">Checkbox give users a binary choice between multiple options in a series.</p>
	<p class="description">Checkboxes give users a binary choice between multiple options in a series.</p>

	Checkbox is composed of two components.
	Checkbox is composed of two components:

	To make the checkbox indeterminate, add the `indeterminate` prop to override the appearance of the checkbox. The checkbox remains in an indeterminate state regardless of user interaction until set back to `false`.
	To make the Checkbox indeterminate, add the `indeterminate` prop to override the appearance of the Checkbox. The Checkbox remains in an indeterminate state regardless of user interaction until set back to `false`.

	NumberField is implemented using a collection of related components:
	Number Field is implemented using a collection of related components:

	In your CSS, ensure any `<label/>` elements inside the `ScrubArea` specify `cursor: unset`. You can rotate the above macOS-style cursor 90 degrees using a `transform` style.
	In your CSS, ensure any `<label>` elements inside the Scrub Area specify `cursor: unset`.
	You can rotate the above macOS-style cursor 90 degrees using a `transform` style.

	In Safari, the pointer is not locked. However, this doesn't affect the ability to scrub infinitely.
	In Safari, the pointer is not locked.
	However, this doesn't affect the ability to scrub infinitely.

	Ensure the number field has an accessible name via a `<label/>` element.
	Ensure the Number Field has an accessible name via a `<label>` element.

	Switch is composed of two components.
	Switch is composed of two components:

	- `<Switch.Thumbs />` renders a `<span>` for providing a visual indicator.
	- `<Switch.Thumb />` renders a `<span>` for providing a visual indicator.


		The `ScrubArea` subcomponent lets users scrub the value with their pointer as a faster alternative to the stepper buttons. This is useful in high-density UIs, such as an image editor that changes the width, height, or location of a layer:
		The `ScrubArea` subcomponent lets users increment/decrement the value via a click+drag interaction with pointer, as a faster alternative to the stepper buttons. This is useful in high-density UIs, such as an image editor that changes the width, height, or location of a layer. You could wrap an icon or a `<label/>` in the `ScrubArea` component.

[docs] Convert alpha component docs to new docs template #392

Are you sure you want to change the base?

[docs] Convert alpha component docs to new docs template #392

Conversation

colmtuite commented May 2, 2024 • edited by oliviertassinari

github-actions bot May 2, 2024

Choose a reason for hiding this comment

github-actions bot May 2, 2024

Choose a reason for hiding this comment

github-actions bot May 2, 2024

Choose a reason for hiding this comment

michaldudak commented May 2, 2024

colmtuite commented May 2, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

flaviendelangle left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

samuelsycamore left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

colmtuite commented May 30, 2024

colmtuite commented May 31, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

colmtuite commented May 2, 2024 •

edited by oliviertassinari

colmtuite commented May 2, 2024 •

edited