docs: add forms guide

[ryo-manba]

📝 Description

Created the form guidelines that will be added in the following PR.

• feat: add form component #3036

Reference: Forms – React Aria

⛳️ Current behavior (updates)

🚀 New behavior

💣 Is this a breaking change (Yes/No):

📝 Additional Information

Summary by CodeRabbit

• New Features

  • Added a new "Forms" route in the Guide section, linking to comprehensive documentation on handling forms with NextUI components.

• Documentation

  • Introduced a detailed guide for form handling, covering submission methods, validation techniques, and integration with form libraries.
  • Updated routing documentation for improved clarity on client-side navigation and integration with NextUI components.

• Style

  • Adjusted visual indentation for level 4 headings in the table of contents for better readability.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5fe7486

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
nextui-docs-v2	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Sep 30, 2024 2:10am
nextui-storybook-v2	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Sep 30, 2024 2:10am

[coderabbitai]

Walkthrough

The pull request introduces several changes, including the modification of the paddingLeftByLevel object in the DocsToc component to adjust the visual indentation of level 4 headings. Additionally, a new route for "Forms" is added to the routes.json file, and comprehensive documentation for handling forms using NextUI components is introduced. Updates to the routing documentation enhance clarity regarding client-side routing integration with NextUI components.

Changes

Files	Change Summary
apps/docs/components/docs/toc.tsx	Modified paddingLeftByLevel for level 4 headings from "pl-3" to "pl-6".
apps/docs/config/routes.json	Added a new route for "Forms" with key form, title Forms, and path /docs/guide/form.mdx.
apps/docs/content/docs/guide/form.mdx	Introduced a guide on handling forms with NextUI components, covering submission methods and validation.
apps/docs/content/docs/guide/routing.mdx	Updated instructions for client-side routing integration, clarifying usage of hooks and configuration.

Possibly related PRs

• fix(system): missing useHref logic #2943: Addresses the useHref logic relevant to the NextUIProvider setup discussed in the routing documentation.
• feat(docs): added tanstack router to the routing section in the documentation #3271: Enhances routing documentation by integrating the useHref prop, directly related to this PR's changes.
• refactor(docs): overall documentation #3274: Refactors overall documentation, including routing sections that relate to the updates in this PR.
• fix(docs): missing tw nested groups in docs #3751: Improves documentation clarity regarding Tailwind CSS, indirectly connecting to the overall documentation improvements.
• fix(docs): replace twitter logo/links with x logo/links #3815: Updates references from Twitter to X in documentation, part of broader documentation updates aligned with this PR.

Suggested labels

📋 Scope : Docs

Suggested reviewers

• wingkwong
• jrgarciadev

---

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 0

🧹 Outside diff range and nitpick comments (12)

apps/docs/components/docs/toc.tsx (1)

22-22: Approved: Improved visual hierarchy for level 4 headings

The change from "pl-3" to "pl-6" for level 4 headings enhances the visual hierarchy in the table of contents, making it easier for users to distinguish between different heading levels. This improvement aligns well with the PR's objective of enhancing documentation and guidelines.

For consistency and future-proofing, consider using a multiple of a base padding unit. For example, if we assume "pl-3" represents 3 units of padding, we could use "pl-9" (3 * 3) instead of "pl-6" for level 4. This approach would make it easier to maintain a consistent scale if you need to add more levels in the future.

-  4: "pl-6",
+  4: "pl-9",

apps/docs/content/docs/guide/routing.mdx (4)

Line range hint 87-93: LGTM: Enhanced root layout example with NextUIProvider

The updated code snippet provides a more comprehensive example of wrapping the root layout with NextUIProvider. The addition of the lang attribute and className to the html tag is a good practice for accessibility and theming.

Consider adding a brief comment explaining the purpose of the dark class, as it might not be immediately clear to all readers why it's being added.

---

102-106: LGTM: Added helpful section on handling Next.js basePath

The new "Add useHref (Optional)" section is a valuable addition, providing clear instructions for users who need to work with the Next.js basePath configuration. The code snippets and explanations are accurate and helpful.

To enhance clarity, consider adding a brief explanation of what the basePath setting does and why a user might need to use it. This context could help readers better understand the purpose of this optional configuration.

Also applies to: 118-121

---

165-167: LGTM: Clear instructions for handling basePath in Next.js Pages Router

The updates to the basePath configuration section for Next.js Pages Router provide clear and accurate instructions. The code snippet is correct and consistent with the App Router example.

For consistency with the App Router section, consider adding a brief note explaining why a user might need to use the basePath configuration. This would provide similar context across both routing approaches.

---

185-189: LGTM: Enhanced React Router integration instructions

The updates to the React Router section provide more comprehensive information about integrating with NextUIProvider. The explanation of useHref and basename is particularly helpful for users with complex routing setups. The code snippet is clear and includes all necessary imports.

To further improve clarity, consider adding a brief explanation or link to documentation about what the basename option in React Router does. This would help readers understand why they might need to use the useHref hook in this context.

Also applies to: 194-195

apps/docs/content/docs/guide/form.mdx (6)

1-28: LGTM! Clear introduction and explanation of labels and help text.

The introduction and "Labels and help text" section provide a solid foundation for understanding NextUI form components. The emphasis on accessibility is commendable.

Consider adding a brief explanation of why labels and help text are important for accessibility. This could help developers understand the significance of these features beyond just UI design.

---

29-90: LGTM! Comprehensive coverage of form submission methods.

The "Submitting data" section effectively explains both uncontrolled and controlled forms, providing clear code examples for each approach.

In the controlled form example (lines 70-89), consider adding a brief comment explaining the benefits of using controlled components, such as real-time validation or dynamic form behavior based on user input.

---

91-205: LGTM! Comprehensive coverage of validation techniques.

The "Validation" section provides a thorough explanation of various validation approaches, including built-in validation, custom error messages, custom validation, and real-time validation. The code examples effectively illustrate each technique.

In the real-time validation example (lines 172-204), consider adding a debounce function to the onValueChange handler. This would prevent excessive validation checks while the user is typing, improving performance and user experience.

---

206-367: LGTM! Comprehensive coverage of server-side validation techniques.

The "Server validation" section provides an excellent overview of server-side validation approaches, including schema validation and integration with React Server Actions and Remix. The code examples are clear and illustrative.

In the server-side validation examples, consider adding a brief explanation or example of how to handle unexpected server errors (e.g., network issues) in addition to validation errors. This would provide a more complete picture of error handling in form submissions.

---

368-416: LGTM! Clear explanation of form library integration.

The "Form libraries" section provides a good introduction to integrating NextUI components with form libraries, focusing on React Hook Form. The code example effectively demonstrates the integration process.

Consider adding a brief mention or example of integrating with other popular form libraries, such as Formik. This would provide a more comprehensive overview of form library integration options for developers.

---

1-416: LGTM! Consistent and well-structured code examples.

The code examples throughout the document are consistently written in TypeScript, using functional components and React hooks. They effectively demonstrate the usage of NextUI components and adhere to modern React best practices.

For improved consistency, consider adding type annotations to all function parameters and return types in the code examples. This would further enhance the TypeScript usage and provide clearer documentation for developers.

apps/docs/config/routes.json (1)

40-45: LGTM! Consider expanding keywords for better searchability.

The new "Forms" route is well-structured and appropriately placed within the "Guide" section. The key, title, and path are consistent with the existing pattern.

Consider expanding the keywords to include more relevant terms. For example:

-  "keywords": "forms, form validation, nextui",
+  "keywords": "forms, form validation, input handling, form submission, nextui",

This could improve searchability and help users find the forms documentation more easily.

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL

📥 Commits

Files that changed from the base of the PR and between e308198 and 5fe7486.

📒 Files selected for processing (4)

• apps/docs/components/docs/toc.tsx (1 hunks)
• apps/docs/config/routes.json (1 hunks)
• apps/docs/content/docs/guide/form.mdx (1 hunks)
• apps/docs/content/docs/guide/routing.mdx (12 hunks)

🔇 Additional comments (5)

apps/docs/content/docs/guide/routing.mdx (4)

61-64: LGTM: Improved Next.js App Router setup instructions

The changes in this section enhance the clarity of the setup instructions for Next.js App Router. The addition of the "use client" directive and the correct imports improve the code snippet's completeness and accuracy.

---

139-139: LGTM: Improved Next.js Pages Router setup instructions

The updates to the Next.js Pages Router section enhance the clarity of the setup instructions. The addition of necessary imports and type definitions in the code snippet improves its completeness and accuracy.

Also applies to: 144-146

---

229-231: LGTM: Improved Remix integration instructions

The updates to the Remix section provide clearer and more accurate information about integrating NextUIProvider. The explanation that Remix uses React Router under the hood is helpful, and the guidance on where to render NextUIProvider in a Remix app is valuable. The code snippet is clear and includes all necessary imports.

Also applies to: 236-237

---

Line range hint 1-329: Overall assessment: Significant improvements to the routing guide

This update to the routing guide brings substantial improvements across various sections, including Next.js (both App and Pages Router), React Router, and Remix. The changes consistently enhance clarity, provide more comprehensive examples, and offer valuable insights for different routing scenarios.

Key improvements:

1. Clearer setup instructions for Next.js App and Pages Router
2. New section on handling Next.js basePath configuration
3. Enhanced explanation of React Router integration
4. Improved Remix integration instructions

These changes align well with the PR objectives of enhancing documentation. The guide now provides a more robust and user-friendly resource for developers integrating NextUI components with various routing solutions.

apps/docs/content/docs/guide/form.mdx (1)

1-416: LGTM! Well-structured and comprehensive form handling guide.

The document is excellently structured, providing a logical progression from basic form concepts to advanced topics like server-side validation and form library integration. The consistent use of code examples throughout the guide enhances understanding and practical application.