docs: omit implementation details from hooks reference#1675
Merged
serikjensen merged 3 commits intomainfrom May 6, 2026
Merged
docs: omit implementation details from hooks reference#1675serikjensen merged 3 commits intomainfrom
serikjensen merged 3 commits intomainfrom
Conversation
serikjensen
requested review from
dmortal,
hukid,
jeffredodd and
krisxcrash
as code owners
Contributor
There was a problem hiding this comment.
Is the semi-colon before the JSX required? It always looks a little odd to my eye
| <Fields.Email label="Email" formHookResult={employeeDetails} /> | ||
| ``` | ||
|
|
||
| Each field reads metadata, form control, and error state directly from the prop. This is the most flexible approach — fields can be placed anywhere in your component tree and interleaved freely with fields from other hooks. |
Contributor
There was a problem hiding this comment.
Would you mind adding an example of two forms? I think I finally pictured it after reading the pros/cons of each approach but actually showing it in code might help with comprehension
Contributor
There was a problem hiding this comment.
Do we not have any default validation messages for hooks?
Member
Author
There was a problem hiding this comment.
Not currently! but this is a good catch, the test here is incorrect. It displays with "REQUIRED"
Going to correct
i'd be open to providing default validation messages, we'd just want to be sure that we aren't putting translations in hooks and we'd also want to be sure that we are providing the translations in the downstream component where the hook is used. I figured that might be easy to miss if the validation errors appeared to be rendering properly
mariechatfield
approved these changes
May 6, 2026
Tightens the hook reference docs to focus on what partners need to build
forms, removing implementation-detail leaks that don't help integrators
and that previously could mislead readers into wiring forms in
non-recommended ways.
- Removed the Advanced: Fields Metadata section from hooks.md so
partners aren't steered toward consuming fieldsMetadata directly.
- Reworded the Fields.Ssn section to describe the masked placeholder +
auto-waived REQUIRED rule behaviorally rather than via the
fieldsMetadata.ssn.hasRedactedValue flag.
- Replaced internal symbols with behavioral descriptions: NAME_REGEX
(Employee Details), FLSA_OVERTIME_SALARY_LIMIT (Compensation),
rev_2020_w4 (Federal Taxes).
- Stripped schema-builder vocabulary ('never'/'always'/predicate,
"schema declares/enforces") from Pay Schedule, Compensation, and
hooks.md.
- Dropped the internal Rule column from the Compensation required-fields
table.
- Removed raw HTTP endpoint paths from Work Address mode descriptions
in favor of mode-only language.
fieldsMetadata is preserved in return-type signatures and the
SignEmployeeFormFieldsMetadata Exported Types entry since those
accurately describe the public return shape without prescribing direct
consumption.
Co-authored-by: Cursor <cursoragent@cursor.com>
- Replace leading-`;` JSX snippets with proper function/expression contexts (Option B SDKFormProvider example, FieldComponent example) so the markdown reads cleanly without ASI defenders. - Add a side-by-side two-hook example after the Choosing an Approach table so readers can picture interleaved (formHookResult) vs grouped (SDKFormProvider) layouts before scrolling to Composing Multiple Hooks. Co-authored-by: Cursor <cursoragent@cursor.com>
serikjensen
force-pushed
the
docs/hooks-omit-fields-metadata
branch
from
7a72698 to
80cca43
Compare
When validationMessages is omitted, the field doesn't go quiet — it displays the raw schema error code (REQUIRED, INVALID_EMAIL, etc.) as the error message. Update the blurb to describe that fallback accurately and steer partners toward always supplying messages. Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Tightens the hook reference docs to focus on what partners need to build forms, removing implementation-detail leaks that don't help integrators and that previously could mislead readers into wiring forms in non-recommended ways.
Changes
Advanced: Fields Metadatasection fromhooks.mdso partners aren't steered toward consumingfieldsMetadatadirectly. Field components consume metadata internally; the recommended path isFields(withFieldComponentfor UI overrides).Fields.Ssnsection to describe the masked placeholder + auto-waivedREQUIREDrule behaviorally instead of viafieldsMetadata.ssn.hasRedactedValue.NAME_REGEX(Employee Details),FLSA_OVERTIME_SALARY_LIMIT(Compensation),rev_2020_w4(Federal Taxes).'never'/'always'/ "predicate", "schema declares/enforces") from Pay Schedule, Compensation, andhooks.mdin favor of partner-facing language.Rulecolumn from the Compensation required-fields table; the remaining columns convey the same partner-relevant info.GET /v1/work_addresses/{work_address_uuid},POST) from Work Address mode descriptions in favor of mode-only language.What was intentionally preserved:
fieldsMetadatain return-type signatures and theSignEmployeeFormFieldsMetadatarow in the Exported Types table — they accurately describe the public return shape without prescribing direct consumption.react-hook-form/Zod/UseFormReturnreferences — partner-relevant framework context, especially for theAdvanced: Hook Form Internalsescape hatch.useCurrentWorkAddressForm,useWorkAddressManagement).Testing
Made with Cursor