refactor: extract shared LengthStrategy type

[Shinigami92]

related to #1443

Preview:

• https://deploy-preview-3940.fakerjs.dev/api/lorem.html#word

[netlify]

✅ Deploy Preview for fakerjs ready!

Name	Link
🔨 Latest commit	9330894
🔍 Latest deploy log	https://app.netlify.com/projects/fakerjs/deploys/6a6a433a9b1ae400081c90ee
😎 Deploy Preview	https://deploy-preview-3940.fakerjs.dev
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.91%. Comparing base (e59f499) to head (9330894).

Additional details and impacted files

@@           Coverage Diff           @@
##             next    #3940   +/-   ##
=======================================
  Coverage   98.91%   98.91%           
=======================================
  Files         924      925    +1     
  Lines        3224     3230    +6     
  Branches      567      567           
=======================================
+ Hits         3189     3195    +6     
  Misses         31       31           
  Partials        4        4           

Files with missing lines	Coverage Δ
src/modules/lorem/module.ts	100.00% <ø> (ø)
src/modules/word/filter-word-list-by-length.ts	100.00% <ø> (ø)
src/modules/word/module.ts	96.00% <ø> (ø)
src/utils/types.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Shinigami92]

I will add the docs here when #3939 got merged, to not fall into to many merge conflicts

[ST-DDT]

I will add the docs here when #3939 got merged, to not fall into to many merge conflicts

I have added a preview link for ease of verifcation.
AFAICT this PR does not need a docs upgrade, since the union type is already covered.

[xDivisionByZerox]

We would loose the information describing each strategy itself with this PR:

Before	After

[Shinigami92]

We would loose the information describing each strategy itself with this PR:

Before After

That is a blocker for me 🙁
I can throw Claude on this again in next few days

[ST-DDT]

Should we add a Types page?

[Shinigami92]

Should we add a Types page?

If so, it needs clickable links from the method docs. But then you might loose the context / back history and get lost. How about hover tooltips? But these might introduce problems with mobile device docs. 🤔 Do you have further ideas?

[ST-DDT]

Use the shadow type system and add the description as hoverable text.
Aka use the detected types to do actual work.

[Shinigami92]

popover works on desktop and mobile (the popover api is stable since 2024)

[Copilot]

Pull request overview

This PR centralizes the “length mismatch handling” strategy into a shared LengthStrategy/LengthStrategyType in src/utils/types.ts, updates Lorem/Word APIs to use the shared type, and enhances the API docs generator/UI to preserve per-union-member documentation via “shadow type” popovers.

Changes:

• Introduces LengthStrategy + LengthStrategyType in src/utils/types.ts and re-exports them from src/index.ts.
• Updates word/lorem modules (and filterWordListByLength) to use LengthStrategyType instead of repeating the string-literal union.
• Extends API docs processing/output to extract enum-member JSDoc for template-literal “shadow types” and render per-value descriptions as popovers (with snapshot/test coverage).

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/scripts/apidocs/method.example.ts	Adds a shadow-type test fixture (enum + template-literal alias + method).
test/scripts/apidocs/snapshots/method.spec.ts.snap	Updates snapshots to include the new method/type rendering expectations.
src/utils/types.ts	Adds shared LengthStrategy enum and LengthStrategyType alias.
src/modules/word/module.ts	Replaces repeated strategy unions with LengthStrategyType across Word APIs.
src/modules/word/filter-word-list-by-length.ts	Uses LengthStrategyType for the strategy option.
src/modules/lorem/module.ts	Uses LengthStrategyType for the strategy option.
src/index.ts	Re-exports LengthStrategy and LengthStrategyType.
scripts/apidocs/processing/type.ts	Adds shadow-type description extraction + attachment to type members.
scripts/apidocs/processing/parameter.ts	Enriches parameter types with per-value descriptions based on syntactic type nodes.
scripts/apidocs/output/page.ts	Renders parameter types as HTML (with popover triggers for described members).
docs/.vitepress/components/api-docs/method.ts	Clarifies type is HTML.
docs/.vitepress/components/api-docs/method-parameters.vue	Switches type column to v-html and adds popover styling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ST-DDT]

This is a good addition. I'm not sure about the font-family and how the descriptions gets added to the types, but the rest looks good to me.

During review I noticed, that this applies to LengthStrategy and SexType, but not ColorFormats. Which made me think what would be better and consistent UX.
Keep the named type, then show the values+descriptions on hover/popover or explode the enum/union types (as is).

[ST-DDT]

Since the remaining things will be handled in a separate PR, I approve this.

• Discussion: Do we show the enum type values directly or do we show an popover with more details. aka do we give the user a hint that the wrapper type + actual enum exist or should they read that from the signature?
• Inline: Read the enum value description at type creation time, instead of retroactively attaching it.

[ST-DDT]

There appears to be merge conflicts.