feat: add form handleCollapsedChange event

[Elm1992]

Description

增加 form 组件展开收起的事件，我的需求是收起的时候要清空所有收起项，应该还有些别的需求吧。

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

  • Added an optional callback to receive form collapse/expand state changes so apps can react when forms are toggled.

• Behavior Changes

  • Form API input is now optional, allowing the form component to be used without an external form API.

• Bug Fixes / Robustness

  • Improved handling of submit/reset flows and Enter key behavior to avoid errors when form API or state is absent; nullish form values now default to empty objects.

[changeset-bot]

⚠️ No Changeset found

Latest commit: e61f39f

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]

Walkthrough

Added an optional handleCollapsedChange callback to the Vben Form API and wired it through types, default state, and component handlers; also made formApi optional and added defensive nullish checks in form usage components. (50 words)

Changes

Cohort / File(s)	Summary
Types packages/@core/ui-kit/form-ui/src/types.ts	Added optional prop handleCollapsedChange?: (collapsed: boolean) => void to VbenFormProps.
Form API packages/@core/ui-kit/form-ui/src/form-api.ts	Initialized handleCollapsedChange in default Vben form props (default undefined).
Context Types packages/@core/ui-kit/form-ui/src/use-form-context.ts	Made formApi optional on ExtendFormProps (formApi?: ExtendedFormApi).
Component Implementations packages/@core/ui-kit/form-ui/src/vben-form.vue, packages/@core/ui-kit/form-ui/src/vben-use-form.vue, packages/@core/ui-kit/form-ui/src/components/form-actions.vue	handleUpdateCollapsed now assigns boolean directly and calls props.handleCollapsedChange?.(value) / forward.value.handleCollapsedChange?.(value). Added optional chaining and nullish fallbacks around formApi, state, getValues() and other accesses; guarded Enter handling for non-textarea.
Documentation docs/src/components/common-ui/vben-form.md	Documented new handleCollapsedChange prop in API and props list.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant UI as User UI (vben-form)
  participant Comp as vben-form / vben-use-form
  participant Parent as Parent (consumer)

  rect rgb(230,247,255)
    note right of Comp: Collapse toggle triggered
    UI ->> Comp: toggleCollapsed(value: boolean)
  end

  alt collapsed changed
    Comp ->> Comp: state.collapsed = value
    Comp ->> Parent: call handleCollapsedChange?(value)
    note right of Parent: optional callback invoked
  else unchanged / no handler
    note right of Comp: no callback or no-op
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–30 minutes

• Files touching types, default state, docs, and multiple Vue components with optional-chaining and guard changes.
• Pay extra attention to:
  • packages/@core/ui-kit/form-ui/src/vben-use-form.vue (lifecycle/watch interactions and optional formApi usage).
  • Correctness of forwarded handleCollapsedChange invocation paths.
  • Places where getValues() now defaults to {} to ensure no behavioral regressions.

Possibly related PRs

• fix: handleValuesChange brings processed values #5970 — modifies form components to obtain processed values via formApi.getValues(); closely related to getValues() fallbacks.
• fix: form submission not appropriate #5126 — modifies vben-use-form.vue value-change/submit-on-change handling and lifecycle/watch setup; overlaps with optional formApi and defensive checks.

Suggested labels

enhancement

Suggested reviewers

• anncwb
• vince292007
• jinmao88
• mynetfan

Poem

🐇 A tiny hop when panels fold,
I whisper changes, meek and bold.
If curtains close or gates unlace,
I send a ping — a soft embrace.
Hooray for forms that know their place. ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description partially follows the template with type of change selected, but the main description is incomplete and in Chinese, with most checklist items unchecked indicating incomplete preparation.	Provide a detailed English description of the feature, explain the implementation approach, and complete the pre-submission checklist items to demonstrate thorough review and testing.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main feature being added: a new handleCollapsedChange event for the form component.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 665a71f and 6b1dcb1.

📒 Files selected for processing (2)

• packages/@core/ui-kit/form-ui/src/components/form-actions.vue (2 hunks)
• packages/@core/ui-kit/form-ui/src/vben-use-form.vue (7 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)

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

🔇 Additional comments (8)

packages/@core/ui-kit/form-ui/src/components/form-actions.vue (2)

50-50: Defensive fallback is appropriate.

The ?? {} fallback safely handles the case where getValues() might return nullish values, even though the guard above (lines 41-43) ensures formApi is defined.

---

59-59: Optional chaining correctly handles potentially undefined formApi.

The use of ?. and ?? {} ensures the function operates safely when formApi is not provided, consistent with the broader changes making formApi optional throughout the form UI.

packages/@core/ui-kit/form-ui/src/vben-use-form.vue (6)

46-50: Well-implemented collapse state change handler.

The implementation correctly updates the collapsed state and triggers the new handleCollapsedChange callback. The optional chaining ensures safe execution when either formApi or the callback is not provided.

---

58-60: Good improvement to textarea handling.

The explicit check for HTMLTextAreaElement correctly prevents Enter key from submitting the form when the user intends to create a new line in a textarea. This enhances the user experience for multi-line text inputs.

---

66-68: Optional chaining correctly guards debounced submit.

The combination of short-circuit evaluation and optional chaining ensures the debounced submit only executes when all required conditions and APIs are available.

---

79-79: Defensive programming in change detection.

The optional chaining at line 79 and line 96, combined with the nullish coalescing fallback at line 98, ensures the change detection logic operates safely even when state or formApi is undefined. The fallback to an empty object is appropriate for the callback signature.

Also applies to: 96-98

---

115-115: Template bindings safely handle optional state.

Using state?.collapsed in both Form and FormActions bindings correctly handles the case where state is undefined (when formApi is not provided). Vue will gracefully treat undefined as a valid prop value.

Also applies to: 132-132

---

28-28: No breaking change for the public API.

The component is an internal implementation detail wrapped by useVbenForm(), which always provides formApi. Direct external usage of vben-use-form.vue is not part of the public API surface—consumers should use useVbenForm() instead. Making formApi optional is a safe defensive improvement that allows the component to handle edge cases gracefully without affecting the public interface.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

packages/@core/ui-kit/form-ui/src/vben-use-form.vue (1)

46-51: Consider simplifying boolean coercion.

The !!value coercion is defensive but unnecessary since value is already typed as boolean. You could simplify to const collapsedValue = value; or use value directly. However, the defensive coding provides runtime safety if the type contract is violated.

Apply this diff if you prefer a cleaner approach:

 const handleUpdateCollapsed = (value: boolean) => {
-  const collapsedValue = !!value;
-  props.formApi?.setState({ collapsed: collapsedValue });
+  props.formApi?.setState({ collapsed: value });
   // 触发收起展开状态变化回调
-  forward.value.handleCollapsedChange?.(collapsedValue);
+  forward.value.handleCollapsedChange?.(value);
 };

packages/@core/ui-kit/form-ui/src/vben-form.vue (1)

42-47: Consider simplifying boolean coercion (same pattern as vben-use-form.vue).

Similar to the implementation in vben-use-form.vue, the !!value coercion is unnecessary given the typed parameter. The defensive coding is acceptable but could be simplified for clarity.

Apply this diff for a cleaner approach:

 const handleUpdateCollapsed = (value: boolean) => {
-  const collapsedValue = !!value;
-  currentCollapsed.value = collapsedValue;
+  currentCollapsed.value = value;
   // 触发收起展开状态变化回调
-  props.handleCollapsedChange?.(collapsedValue);
+  props.handleCollapsedChange?.(value);
 };

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1e09fa4 and 0139d41.

📒 Files selected for processing (6)

• docs/src/components/common-ui/vben-form.md (1 hunks)
• packages/@core/ui-kit/form-ui/src/form-api.ts (1 hunks)
• packages/@core/ui-kit/form-ui/src/types.ts (1 hunks)
• packages/@core/ui-kit/form-ui/src/use-form-context.ts (1 hunks)
• packages/@core/ui-kit/form-ui/src/vben-form.vue (1 hunks)
• packages/@core/ui-kit/form-ui/src/vben-use-form.vue (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

packages/@core/ui-kit/form-ui/src/use-form-context.ts (1)

packages/@core/ui-kit/form-ui/src/types.ts (2)

• VbenFormProps (350-434)
• ExtendedFormApi (436-440)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)

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

🔇 Additional comments (3)

packages/@core/ui-kit/form-ui/src/types.ts (1)

382-385: LGTM! Type definition is correct.

The optional callback property is properly typed with a clear signature. The documentation comment clearly describes its purpose.

packages/@core/ui-kit/form-ui/src/form-api.ts (1)

39-39: LGTM! Default state initialization is correct.

The initialization follows the established pattern for other callback handlers in the default state.

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

338-338: LGTM! Documentation is complete and accurate.

The prop is properly documented with correct type signature and clear description.