use jsdoc

Author: NgocNhi123

src/docs/components/dialog.stories.tsx

@@ -20,6 +20,18 @@ export const Primary: StoryObj<typeof Dialog> = {
   render: () => <div>None</div>,
 };
 
+/**
+ * Dialog is a [controlled][1], [declarative][3] component:
+ * you should have a boolean [state][2] for whether the dialog should be visible or not,
+ * and conditionally render a dialog based on that state.
+ *
+ * A dialog will call its `onEsc` function when the user press the "Esc" key or click on the backdrop.
+ * It's common to set your state to `false` here to "close" the dialog.
+ *
+ * [1]: https://reactjs.org/docs/forms.html#controlled-components
+ * [2]: https://reactjs.org/docs/hooks-state.html
+ * [3]: https://reactjs.org/docs/refs-and-the-dom.html#when-to-use-refs
+ */
 export const Basic: StoryObj = {
   render: () => {
     const [visible, setVisible] = useState(false);
@@ -34,22 +46,15 @@ export const Basic: StoryObj = {
   },
 };
 
-Utils.story(Basic, {
-  desc: `
-Dialog is a [controlled][1], [declarative][3] component: you should have a
-boolean [state][2] for whether the dialog should be visible or not, and
-conditionally render a dialog based on that state.
-
-A dialog will call its \`onEsc\` function when the user press the "Esc" key or
-click on the backdrop. It's common to set your state to \`false\` here to
-"close" the dialog.
-
-[1]: https://reactjs.org/docs/forms.html#controlled-components
-[2]: https://reactjs.org/docs/hooks-state.html
-[3]: https://reactjs.org/docs/refs-and-the-dom.html#when-to-use-refs
-`,
-});
-
+/**
+ * Out of the box, dialogs render their children as-is, without even a padding,
+ * to allow maximum customization.
+ * Therefore, the Dialog component has supporting components to give you common dialog layout:
+ *
+ * - `Dialog.Body` wraps its children inside a padding.
+ * - `Dialog.Footer` places its children horizontally, with gaps, aligned to end.
+ * - `Dialog.Title` makes its children bold and larger, like a title.
+ */
 export const Layout: StoryObj = {
   render: () => {
     const [visible, setVisible] = useState(false);
@@ -75,18 +80,21 @@ export const Layout: StoryObj = {
   },
 };
 
-Utils.story(Layout, {
-  desc: `
-Out of the box, dialogs render their children as-is, without even a padding,
-to allow maximum customization. Therefore, the Dialog component has supporting
-components to give you common dialog layout:
-
-- \`Dialog.Body\` wraps its children inside a padding.
-- \`Dialog.Footer\` places its children horizontally, with gaps, aligned to end.
-- \`Dialog.Title\` makes its children bold and larger, like a title.
-`,
-});
-
+/**
+ * The Dialog component has some utility methods as alternatives to the browser's built-in dialogs:
+ *
+ * - `Dialog.alert` for [`window.alert`][1]
+ * - `Dialog.confirm` for [`window.confirm`][2]
+ * - `Dialog.prompt` for [`window.prompt`][3]
+ *
+ * They accept the same parameters as their built-in counterparts,
+ * but return async results and thus do not block the main flow.
+ * They are implemented using Moai's components.
+ *
+ * [1]: https://developer.mozilla.org/en-US/docs/Web/API/Window/alert
+ * [2]: https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm
+ * [3]: https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt
+ */
 export const Utilities: StoryObj = {
   render: () => (
     <Button
@@ -99,22 +107,3 @@ export const Utilities: StoryObj = {
     />
   ),
 };
-
-Utils.story(Utilities, {
-  desc: `
-The Dialog component has some utility methods as alternatives to the browser's
-built-in dialogs:
-
-- \`Dialog.alert\` for [\`window.alert\`][1]
-- \`Dialog.confirm\` for [\`window.confirm\`][2]
-- \`Dialog.prompt\` for [\`window.prompt\`][3]
-
-They accept the same parameters as their built-in counterparts, but return
-async results and thus do not block the main flow. They are implemented using
-Moai's components.
-
-[1]: https://developer.mozilla.org/en-US/docs/Web/API/Window/alert
-[2]: https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm
-[3]: https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt
-`,
-});

src/docs/components/icon.stories.tsx

@@ -36,25 +36,30 @@ export const Primary: StoryObj<typeof Icon> = {
   ),
 };
 
+/**
+ * The recommended way to use the Icon component is to import an icon from the [react-icons][1] package
+ * and pass it to the `icon` prop.
+ * All icons in the package can be used with Moai out of the box.
+ *
+ * ~~~ts
+ *
+ * import { FaHome } from "react-icons/fa";
+ * ~~~
+ *
+ * [1]: https://react-icons.github.io/react-icons/
+ */
 export const Basic: StoryObj = {
   render: () => <Icon component={FaHome} />,
 };
 
-Utils.story(Basic, {
-  desc: `
-The recommended way to use the Icon component is to import an icon from the
-[react-icons][1] package and pass it to the \`icon\` prop. All icons in the
-package can be used with Moai out of the box.
-
-~~~ts
-
-import { FaHome } from "react-icons/fa";
-~~~
-
-[1]: https://react-icons.github.io/react-icons/
-`,
-});
-
+/**
+ * To make layout more predictable, icons are rendered as [block elements][1] by default.
+ * However, for icons that are parts of texts, they should be rendered as [inline elements][2].
+ * This is done by setting the `display` prop to `inline`.
+ *
+ * [1]: https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements
+ * [2]: https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements
+ */
 export const Display: StoryObj = {
   render: () => (
     <p>
@@ -65,18 +70,15 @@ export const Display: StoryObj = {
   ),
 };
 
-Utils.story(Display, {
-  desc: `
-To make layout more predictable, icons are rendered as [block elements][1] by
-default. However, for icons that are parts of texts, they should be rendered as
-[inline elements][2]. This is done by setting the \`display\` prop to
-\`inline\`.
-
-[1]: https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements
-[2]: https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements
-`,
-});
-
+/**
+ * SVG icons usually use the [`currentcolor`][1] keyword for their colors.
+ * This means to set the color of an icon, you should set the [text color][2] of its container.
+ * Moai has a [`text`][3] utility that provides predefined, accessible colors for icons.
+ *
+ * [1]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#currentcolor_keyword
+ * [2]: https://developer.mozilla.org/en-US/docs/Web/CSS/color
+ * [3]: /docs/patterns-color-text--page
+ */
 export const Color: StoryObj = {
   render: () => (
     <div className={text.highlightWeak}>
@@ -85,19 +87,16 @@ export const Color: StoryObj = {
   ),
 };
 
-Utils.story(Color, {
-  desc: `
-SVG icons usually use the [\`currentcolor\`][1] keyword for their colors. This
-means to set the color of an icon, you should set the [text color][2] of its
-container. Moai has a [\`text\`][3] utility that provides predefined,
-accessible colors for icons.
-
-[1]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#currentcolor_keyword
-[2]: https://developer.mozilla.org/en-US/docs/Web/CSS/color
-[3]: /docs/patterns-color-text--page
-`,
-});
-
+/**
+ * Technically, the `component` prop expects a [function component][1] that returns an SVG element.
+ * You can use it to display your own custom icons (e.g. logos, product icons).
+ * With tools like [React SVGR][3], you can even create your own icon sets to use with Moai.
+ * See the [Advanced section][2] in the Icon Pattern guide for detail.
+ *
+ * [1]: https://reactjs.org/docs/components-and-props.html#function-and-class-components
+ * [2]: /docs/patterns-icon--advanced
+ * [3]: https://react-svgr.com
+ */
 export const Advanced: StoryObj = {
   render: () => {
     // In practice, this should be defined outside of your component, or even
@@ -111,17 +110,3 @@ export const Advanced: StoryObj = {
     return <Icon component={Line} />;
   },
 };
-
-Utils.story(Advanced, {
-  desc: `
-Technically, the \`component\` prop expects a [function component][1] that
-returns an SVG element. You can use it to display your own custom icons (e.g.
-logos, product icons). With tools like [React SVGR][3], you can even create
-your own icon sets to use with Moai. See the [Advanced section][2] in the Icon
-Pattern guide for detail.
-
-[1]: https://reactjs.org/docs/components-and-props.html#function-and-class-components
-[2]: /docs/patterns-icon--advanced
-[3]: https://react-svgr.com
-`,
-});

src/docs/components/input.stories.tsx

@@ -37,6 +37,26 @@ export const Primary: StoryObj<typeof Input> = {
   ),
 };
 
+/**
+ * Input should be used as a [controlled][1] component.
+ * You should have a [state][2] to store the text value,
+ * and give its control to an Input via its `value` and `setValue` props.
+ * At the moment, these props work with `string` values only.
+ *
+ * To have good accessibility, ensure that your inputs have their matching labels.
+ * You can do it in many ways: wrap the input inside a `label`,
+ * or explicitly [link][3] it to one (like in the example below),
+ * or via the `aria-label` and `aria-labelledby` props.
+ *
+ * Note that Moai's inputs don't have the [confusing][4] default width.
+ * Instead, inputs always fill 100% of their container width.
+ * This means you should control the width of an input via its container.
+ *
+ * [1]: https://reactjs.org/docs/forms.html#controlled-components
+ * [2]: https://reactjs.org/docs/hooks-state.html
+ * [3]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#attr-for
+ * [4]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-size
+ */
 export const Basic: StoryObj = {
   render: () => {
     const [text, setText] = useState<string>("Hello");
@@ -49,29 +69,17 @@ export const Basic: StoryObj = {
   },
 };
 
-Utils.story(Basic, {
-  desc: `
-Input should be used as a [controlled][1] component. You should have a
-[state][2] to store the text value, and give its control to an Input via its
-\`value\` and \`setValue\` props. At the moment, these props work with
-\`string\` values only.
-
-To have good accessibility, ensure that your inputs have their matching labels.
-You can do it in many ways: wrap the input inside a \`label\`, or explicitly
-[link][3] it to one (like in the example below), or via the \`aria-label\` and
-\`aria-labelledby\` props.
-
-Note that Moai's inputs don't have the [confusing][4] default width. Instead,
-inputs always fill 100% of their container width. This means you should control
-the width of an input via its container.
-
-[1]: https://reactjs.org/docs/forms.html#controlled-components
-[2]: https://reactjs.org/docs/hooks-state.html
-[3]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#attr-for
-[4]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-size
-`,
-});
-
+/**
+ * Input follows the [standard approach][1] to support suggestion.
+ * You should define your suggestion as a `datalist` element,
+ * then give its `id` to an input via the `list` prop.
+ *
+ * As a convenient shortcut, you can also define your suggestion directly via the `list` prop
+ * and Input will create the `datalist` element for you.
+ * You'll still need an explicit `id` for the list:
+ *
+ * [1]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist
+ */
 export const Suggestion: StoryObj = {
   render: () => (
     <div style={{ width: 200 }}>
@@ -83,20 +91,17 @@ export const Suggestion: StoryObj = {
   ),
 };
 
-Utils.story(Suggestion, {
-  desc: `
-Input follows the [standard approach][1] to support suggestion. You should
-define your suggestion as a \`datalist\` element, then give its \`id\` to an
-input via the \`list\` prop.
-
-As a convenient shortcut, you can also define your suggestion directly via the
-\`list\` prop and Input will create the \`datalist\` element for you. You'll
-still need an explicit \`id\` for the list:
-
-[1]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist
-`,
-});
-
+/**
+ * Input supports both [controlled][1] and [uncontrolled][2] usages,
+ * making it easy to use them with form builders like [Formik][3] and [React Hook Form][4], right out of the box.
+ * See our [Form guide][5] to learn more.
+ *
+ * [1]: https://reactjs.org/docs/forms.html#controlled-components
+ * [2]: https://reactjs.org/docs/uncontrolled-components.html
+ * [3]: https://formik.org
+ * [4]: https://react-hook-form.com
+ * [5]: /docs/guides-icons--primary
+ */
 export const Form: StoryObj = {
   render: () => (
     // "Fm" is the Formik's namespace
@@ -114,20 +119,13 @@ export const Form: StoryObj = {
   ),
 };
 
-Utils.story(Form, {
-  desc: `
-Input supports both [controlled][1] and [uncontrolled][2] usages, making it
-easy to use them with form builders like [Formik][3] and [React Hook Form][4],
-right out of the box. See our [Form guide][5] to learn more.
-
-[1]: https://reactjs.org/docs/forms.html#controlled-components
-[2]: https://reactjs.org/docs/uncontrolled-components.html
-[3]: https://formik.org
-[4]: https://react-hook-form.com
-[5]: /docs/guides-icons--primary
-`,
-});
-
+/**
+ * An input can have an icon defined via the `icon` prop.
+ * This follows our [Icon standard][1], which supports all SVG icons.
+ * See the [Icon guide][1] to learn more.
+ *
+ * [1]: /docs/guides-icons--primary
+ */
 export const Icon: StoryObj = {
   render: () => (
     // The icon is imported from the "react-icons" external library, like
@@ -141,13 +139,3 @@ export const Icon: StoryObj = {
     </div>
   ),
 };
-
-Utils.story(Icon, {
-  desc: `
-An input can have an icon defined via the \`icon\` prop. This follows our [Icon
-standard][1], which supports all SVG icons. See the [Icon guide][1] to learn
-more.
-
-[1]: /docs/guides-icons--primary
-`,
-});