feat: api-component support autoSelect prop

[mynetfan]

Description

ApiComponent新增autoSelect属性，用于在获取备选项之后自动设置一个选项。

• first：自动选择第一个选项
• last：自动选择最后一个选项
• one: 当请求的结果只有一个选项时，自动选择该选项
• false：不自动选择(默认)

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update
• Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.

Checklist

ℹ️ Check all checkboxes - this will indicate that you have done everything in accordance with the rules in CONTRIBUTING.

• If you introduce new functionality, document it. You can run documentation with pnpm run docs:dev command.
• Run the tests with pnpm test.
• Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.
• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

Summary by CodeRabbit

• New Features

  • Introduced an option to automatically select a choice when available. Users can now configure the component to choose the first, last, or sole option automatically.

• Documentation

  • Updated the documentation to clearly explain the new autoSelect feature, its possible values, and their implications for component behavior.
  • Added a new column in the properties table for version requirements.

[coderabbitai]

Walkthrough

The changes introduce a new property, autoSelect, to the API select component, allowing for automatic option selection based on the current value. This property can take values of 'first', 'last', 'one', or false, with a default of false. The documentation has been updated to include this new property, along with its behavior and implications. The component logic in the Vue file has been modified to incorporate this functionality, and an example usage in a form is provided where autoSelect is set to 'first'.

Changes

File(s) Changed	Change Summary
docs/src/.../vben-api-component.md	Added documentation for the new autoSelect property, including a detailed description and table format updates to reflect its behavior when set to 'first', 'last', 'one', or false.
packages/effects/.../api-component.vue	Introduced the autoSelect prop with allowed values ('first', 'last', 'one', false, defaulting to false), updated the default for modelValue to undefined, and enhanced the emitChange function with a switch to auto-select the appropriate option.
playground/src/.../basic.vue	Updated the example form by specifying autoSelect: 'first' in the componentProps for the ApiSelect component, enabling automatic selection of the first option when fetching options from the API.

Sequence Diagram(s)

sequenceDiagram
    participant C as API Component
    participant L as AutoSelect Logic
    participant O as Options Data

    C->>L: Trigger emitChange (modelValue undefined)
    L->>O: Request available options
    O-->>L: Return options list
    L->>C: Evaluate autoSelect:
    Note over L: 'first' selects first,\n'last' selects last,\n'one' selects if single option,\nfalse disables auto-selection
    C->>C: Update modelValue with selected option

Loading

Poem

I'm a rabbit hopping through the code,
With new autoSelect lighting up the load,
Whether it's first, last, or the only one in play,
My steps are agile as changes lead the way,
Cheers to clear logic under the moon's soft glow! 🐰✨

Tip

⚡💬 Agentic Chat (Pro Plan, General Availability)

• We're introducing multi-step agentic chat in review comments and issue comments, within and outside of PR's. This feature enhances review and issue discussions with the CodeRabbit agentic chat by enabling advanced interactions, including the ability to create pull requests directly from comments and add commits to existing pull requests.

---

🪧 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 generate docstrings to generate docstrings for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai plan to trigger planning for file edits and PR creation.
• @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.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

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: 1

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2971ccc and 94e37d6.

📒 Files selected for processing (3)

• docs/src/components/common-ui/vben-api-component.md (2 hunks)
• packages/effects/common-ui/src/components/api-component/api-component.vue (3 hunks)
• playground/src/views/examples/form/basic.vue (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms (5)

• GitHub Check: Check (windows-latest)
• GitHub Check: Lint (windows-latest)
• GitHub Check: Test (windows-latest)
• GitHub Check: post-update (windows-latest)
• GitHub Check: post-update (ubuntu-latest)

🔇 Additional comments (7)

playground/src/views/examples/form/basic.vue (1)

77-77: Implementation looks good!

The autoSelect: 'first' property is correctly added to the ApiSelect component, which will automatically select the first option when data is fetched from the API. This enhances the user experience by providing a default selection.

docs/src/components/common-ui/vben-api-component.md (2)

154-154: Documentation for new property looks good.

The autoSelect property is properly documented with its type and default value.

---

156-163: Clear and comprehensive description.

The detailed explanation of the autoSelect property is well-written and clearly describes all possible values and behaviors.

packages/effects/common-ui/src/components/api-component/api-component.vue (4)

57-64: Well-documented property with clear JSDoc comments.

The JSDoc comments for the autoSelect property are clear and informative, explaining all possible values and their behaviors.

---

85-85: Default value is appropriately set.

Setting autoSelect to false as the default ensures backward compatibility with existing implementations.

---

93-93: Good change from empty string to undefined.

Changing the default value of modelValue from an empty string to undefined aligns better with the auto-select logic, as it now checks for undefined to determine when to apply auto-selection.

---

206-230: Well-implemented auto-selection logic.

The implementation of the auto-selection feature in the emitChange function is clean and handles all the specified cases correctly:

1. Selecting the first option when autoSelect is 'first'
2. Selecting the last option when autoSelect is 'last'
3. Selecting the only option when autoSelect is 'one' and there's exactly one option
4. Not selecting any option when autoSelect is false (default)

This logic only applies when the current value is undefined, preserving existing behavior for other cases.

[changeset-bot]

⚠️ No Changeset found

Latest commit: b2e9cc8

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

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 94e37d6 and b2e9cc8.

📒 Files selected for processing (1)

• docs/src/components/common-ui/vben-api-component.md (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms (5)

• GitHub Check: Check (windows-latest)
• GitHub Check: Test (windows-latest)
• GitHub Check: Lint (windows-latest)
• GitHub Check: post-update (ubuntu-latest)
• GitHub Check: post-update (windows-latest)

🔇 Additional comments (1)

docs/src/components/common-ui/vben-api-component.md (1)

156-164: Review of the autoSelect Feature Documentation

The new section titled “#### autoSelect 自动设置选项” clearly explains the feature and its allowed values:

• first: 自动选择第一个选项
• last: 自动选择最后一个选项
• one: 有且仅有一个选项时，自动选择它
• false: 不自动选择选项

This documentation is clear and user-friendly. Just ensure that the type declaration in the table (line 154) is updated accordingly to avoid any inconsistency.