Skip to content

Commit

Permalink
docs(form): Updated form menu components for better documentation and…
Browse files Browse the repository at this point in the history
… examples in code
  • Loading branch information
mlaursen committed Apr 22, 2021
1 parent 01caa0b commit d9695b7
Show file tree
Hide file tree
Showing 4 changed files with 176 additions and 0 deletions.
29 changes: 29 additions & 0 deletions packages/form/src/menu/MenuItemCheckbox.tsx
Expand Up @@ -12,6 +12,35 @@ export type MenuItemCheckboxProps = BaseMenuItemInputToggleProps;
* This is a simple wrapper for the {@link MenuItemInputToggle} component to
* render it as a checkbox and pulling the checkbox icon from the
* {@link IconProvider}.
*
* @example
* Simple Example
* ```tsx
* import { ReactElement, useState } from "react";
* import { DropdownMenu } from "@react-md/menu";
* import { MenuItemCheckbox } from "@react-md/form";
*
* function Example(): ReactElement {
* const [checked, setChecked] = useState(false);
*
* return (
* <DropdownMenu
* id="dropdown-menu-id"
* items={[
* <MenuItemCheckbox
* id="checkbox-1"
* checked={checked}
* onCheckedChange={(nextChecked) => setChecked(nextChecked)}
* >
* Checkbox
* </MenuItemCheckbox>,
* ]}
* >
* Button
* </DropdownMenu>
* );
* }
* ```
*/
export const MenuItemCheckbox = forwardRef<
HTMLLIElement,
Expand Down
12 changes: 12 additions & 0 deletions packages/form/src/menu/MenuItemInputToggle.tsx
Expand Up @@ -103,6 +103,15 @@ export interface BaseMenuItemInputToggleProps
export interface MenuItemInputToggleProps extends BaseMenuItemInputToggleProps {
/**
* The input toggle type to render.
*
* Note for the `radio` type:
* If a `menu` or `menubar` contains more than one group of `menuitemradio`
* elements, or if the `menu` contains one group and other, unrelated menu
* items, authors **SHOULD** nest each set of related `menuitemradio` elements
* in an element using the `group` role, and authors **SHOULD** delimit the
* group from other menu items with an element using the separator role.
*
* @see {@link https://www.w3.org/TR/wai-aria-1.1/#menuitemradio}
*/
type: "checkbox" | "radio" | "switch";
}
Expand All @@ -112,6 +121,9 @@ export interface MenuItemInputToggleProps extends BaseMenuItemInputToggleProps {
* instead the `MenuItemCheckbox`, `MenuItemRadio`, or `MenuItemSwitch` should
* be used instead.
*
* @see {@link MenuItemCheckbox} for checkbox examples
* @see {@link MenuItemRadio} for radio examples
* @see {@link MenuItemSwitch} for switch examples
* @remarks \@since 2.8.0
*/
export const MenuItemInputToggle = forwardRef<
Expand Down
106 changes: 106 additions & 0 deletions packages/form/src/menu/MenuItemRadio.tsx
Expand Up @@ -12,6 +12,112 @@ export type MenuItemRadioProps = BaseMenuItemInputToggleProps;
* This is a simple wrapper for the {@link MenuItemInputToggle} component to
* render it as a radio and pulling the radio icon from the
* {@link IconProvider}.
*
* @remarks
* If a menu or menubar contains more than one group of menuitemradio elements,
* or if the menu contains one group and other, unrelated menu items, authors
* SHOULD nest each set of related menuitemradio elements in an element using
* the group role, and authors SHOULD delimit the group from other menu items
* with an element using the separator role.
* @see {@link https://www.w3.org/TR/wai-aria-1.1/#menuitemradio}
*
* @example
* Only Radio Items
* ```tsx
* import { ReactElement, useState } from "react";
* import { DropdownMenu } from "@react-md/menu";
* import { MenuItemRadio } from "@react-md/form";
*
* function Example(): ReactElement {
* const [value, setValue] = useState("value1");
*
* return (
* <DropdownMenu
* id="dropdown-menu-id"
* items={[
* <MenuItemRadio
* id="radio-1"
* checked={value === "value1"}
* onCheckedChange={() => setValue("value1")}
* >
* Radio 1
* </MenuItemRadio>,
* <MenuItemRadio
* id="radio-2"
* checked={value === "value2"}
* onCheckedChange={() => setValue("value2")}
* >
* Radio 2
* </MenuItemRadio>,
* <MenuItemRadio
* id="radio-3"
* checked={value === "value3"}
* onCheckedChange={() => setValue("value3")}
* >
* Radio 3
* </MenuItemRadio>,
* ]}
* >
* Button
* </DropdownMenu>
* );
* }
* ```
*
* @example
* With Other Items
* ```tsx
* import { ReactElement, useState } from "react";
* import { DropdownMenu, MenuItemSeparator } from "@react-md/menu";
* import { MenuItemRadio, MenuItemSwitch } from "@react-md/form";
*
* function Example(): ReactElement {
* const [value, setValue] = useState("value1");
*
* return (
* <DropdownMenu
* id="dropdown-menu-id"
* items={[
* <MenuItemSwitch
* id="switch-id"
* checked={checked}
* onCheckedChange={nextChecked => setChecked(nextChecked)}
* >
* Light mode
* </MenuItemSwitch>,
* <MenuItemSeparator />,
* <div role="group" aria-label="My Group Label">
* <MenuItemRadio
* id="radio-1"
* checked={value === "value1"}
* onCheckedChange={() => setValue("value1")}
* >
* Radio 1
* </MenuItemRadio>,
* <MenuItemRadio
* id="radio-2"
* checked={value === "value2"}
* onCheckedChange={() => setValue("value2")}
* >
* Radio 2
* </MenuItemRadio>,
* <MenuItemRadio
* id="radio-3"
* checked={value === "value3"}
* onCheckedChange={() => setValue("value3")}
* >
* Radio 3
* </MenuItemRadio>
* </div>,
* ]}
* >
* Button
* </DropdownMenu>
* );
* }
* ```
*
* @remarks \@since 2.8.0
*/
export const MenuItemRadio = forwardRef<HTMLLIElement, MenuItemRadioProps>(
function MenuItemRadio({ icon: propIcon, ...props }, ref) {
Expand Down
29 changes: 29 additions & 0 deletions packages/form/src/menu/MenuItemSwitch.tsx
Expand Up @@ -12,6 +12,35 @@ export type MenuItemSwitchProps = Omit<BaseMenuItemInputToggleProps, "icon">;
* This is a simple wrapper for the {@link MenuItemInputToggle} component to
* render it as a switch.
*
* @example
* Simple Example
* ```tsx
* import { ReactElement, useState } from "react";
* import { DropdownMenu } from "@react-md/menu";
* import { MenuItemSwitch } from "@react-md/form";
*
* function Example(): ReactElement {
* const [checked, setChecked] = useState(false);
*
* return (
* <DropdownMenu
* id="dropdown-menu-id"
* items={[
* <MenuItemSwitch
* id="switch-1"
* checked={checked}
* onCheckedChange={(nextChecked) => setChecked(nextChecked)}
* >
* Switch
* </MenuItemSwitch>,
* ]}
* >
* Button
* </DropdownMenu>
* );
* }
* ```
*
* @remarks \@since 2.8.0
*/
export const MenuItemSwitch = forwardRef<HTMLLIElement, MenuItemSwitchProps>(
Expand Down

0 comments on commit d9695b7

Please sign in to comment.