Auto check examples in /components/docs

[AlexanderZeilmann]

While looking at primefaces/primereact#6774, I found a variety of other components for which the TypeScript types seem to be slightly off. Therefore my question: Is there a way to automatically check the types of Typescript examples in the `/components/docs folder? All problems here will end up as errors in the code of the users. So ideally these code examples are validated for type problems and other errors.

Steps to reproduce:

1. Go to the following incomplete list of URLs
2. Open the Typescript example in stackblitz
3. Wait for npm install && npm run dev to complete
4. Hover the wiggle lines to see the errors

https://primereact.org/stepper/#basic

• Type '{ children: Element[]; ref: MutableRefObject<null>; style: { flexBasis: string; }; }' is not assignable to type 'IntrinsicAttributes & StepperProps & { children?: ReactNode; } & RefAttributes<StepperRefAttributes>'. Property 'style' does not exist on type 'IntrinsicAttributes & StepperProps & { children?: ReactNode; } & RefAttributes<StepperRefAttributes>'

• 'stepperRef.current' is possibly 'null'.

https://primereact.org/floatlabel/#basic

• Type '{ children: string; for: string; }' is not assignable to type 'DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>'. Property 'for' does not exist on type 'DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>'. Did you mean 'htmlFor'?

https://primereact.org/inputotp/#template

• Cannot find name 'InputHTMLAttributes'.

• Type '({ events, props }: CustomInputProps) => JSX.Element' is not assignable to type 'TemplateType<InputOtpProps>'. Type '({ events, props }: CustomInputProps) => JSX.Element' is not assignable to type '(props: InputOtpProps) => ReactNode'. Types of parameters '__0' and 'props' are incompatible. Type 'InputOtpProps' is missing the following properties from type 'CustomInputProps': events, props

Alternatives

If an automatic check is not feasible, it would make sense to go through the TypeScript examples manually and correct the type annotations.

[melloware]

PR's for Typescript fixes are always welcome.

[AlexanderZeilmann]

Yes, I know, but wouldn't automatic checks that run as part of the build process make more sense than fixing them one by one?
I implemented quick-and-dirty version of this: Run through all files in the docs folder, save the TypeScript code in a standalone file and run the TypeScript compiler over the files. This works well and finds several errors.

[melloware]

@AlexanderZeilmann PR is welcome!

[vieira-brz]

To automatically check the TypeScript types in your /components/docs folder for the PrimeReact components, there are several approaches you can take to ensure that these examples are correct and won't cause errors when used by developers. Here are a few strategies you might consider:

1. Automated Testing with TypeScript Compiler

You can use the TypeScript compiler (tsc) to automatically check for type errors in your code examples. Here’s a basic setup you could use:

• Create a Script: Write a TypeScript script that imports each component example as a module and tries to compile it.
• Run tsc: Use the TypeScript compiler to check for errors. You can integrate this into a CI/CD pipeline to ensure examples are tested automatically on each update.

2. Using ESLint with TypeScript

Set up ESLint with the TypeScript parser to lint your examples. This not only checks for type errors but also enforces code style and best practices.

• Configure ESLint: Use @typescript-eslint/parser and @typescript-eslint/eslint-plugin for TypeScript support.
• Create Linting Rules: Define rules that help identify common mistakes specific to your library’s usage.
• Automate Linting: Include this as part of your continuous integration process.

3. Unit Testing with Type Assertions

Write unit tests that specifically assert type compatibility. Tools like tsd allow you to write assertions about TypeScript types directly in your tests.

• Setup tsd: This tool lets you write tests that assert types are what you expect.
• Integrate Testing: Run these tests as part of your standard test suite.

4. Custom Tooling

For a more tailored solution, develop a custom tool that:

• Reads TypeScript files from your /components/docs directory.
• Analyzes them using the TypeScript compiler API to check for specific type-related issues.
• Reports errors in a manner that integrates well with your existing development workflows.

5. Manual Review Enhanced with Tooling

While automated checks are valuable, they might not catch everything, especially nuances in how components are supposed to be used versus how they are documented. Combining automated tooling with periodic manual reviews could provide a balance between automation and accuracy.

• Periodic Manual Checks: Schedule regular reviews of the TypeScript examples to ensure they not only are type-correct but also make sense from a user’s perspective.
• Documentation Team: Involve a team that specifically handles documentation and examples, ensuring high quality and up-to-date examples.

Next Steps

• Integrate into Build Pipeline: Whatever method you choose, integrate it into your build or deployment pipeline to ensure examples are always tested before being published.
• Feedback Loop: Make it easy for users to report issues with documentation directly, perhaps integrating a feedback system directly in the documentation site.

This approach will help you maintain a high standard for your TypeScript examples, reducing the likelihood of errors making their way into user code.