[code-infra] Upgrade react-docgen to v8

docs/pages/joy-ui/api/select.json

@@ -24,7 +24,7 @@
     "indicator": { "type": { "name": "node" } },
     "listboxId": { "type": { "name": "string" } },
     "listboxOpen": { "type": { "name": "bool" }, "default": "undefined" },
-    "multiple": { "type": { "name": "bool" } },
+    "multiple": { "type": { "name": "bool" }, "default": "false" },
     "name": { "type": { "name": "string" } },
     "onChange": { "type": { "name": "func" } },
     "onClose": { "type": { "name": "func" } },

docs/src/pages/premium-themes/onepirate/modules/form/FormButton.js

@@ -19,6 +19,7 @@ function FormButton(props) {
 FormButton.propTypes = {
   /**
    * If `true`, the component is disabled.
+   * @default false
    */
   disabled: PropTypes.bool,
   mounted: PropTypes.bool,

docs/translations/api-docs-joy/avatar-group/avatar-group.json

@@ -5,14 +5,12 @@
       "description": "Used to render icon or text elements inside the AvatarGroup if <code>src</code> is not set. This can be an element, or just a string."
     },
     "color": {
-      "description": "The color of the component. It supports those theme colors that make sense for this component."
+      "description": "The color context for the avatar children. It has no effect on the AvatarGroup."
     },
     "component": {
       "description": "The component used for the root node. Either a string to use a HTML element or a component."
     },
-    "size": {
-      "description": "The size of the component. It accepts theme values between &#39;sm&#39; and &#39;lg&#39;."
-    },
+    "size": { "description": "The size of the component and the avatar children." },
     "slotProps": { "description": "The props used for each slot inside." },
     "slots": { "description": "The components used for each slot inside." },
     "sx": {

docs/translations/api-docs-joy/radio-group/radio-group.json

@@ -6,7 +6,7 @@
       "description": "The color of the component. It supports those theme colors that make sense for this component."
     },
     "component": {
-      "description": "The component used for the root node. Either a string to use a HTML element or a component."
+      "description": "The component used for the Root slot. Either a string to use a HTML element or a component."
     },
     "defaultValue": {
       "description": "The default value. Use when the component is not controlled."

docs/translations/api-docs-joy/select/select.json

@@ -50,6 +50,7 @@
       "description": "If <code>true</code>, the Select cannot be empty when submitting form."
     },
     "size": { "description": "The size of the component." },
+    "slotProps": { "description": "The props used for each slot inside." },
     "slots": { "description": "The components used for each slot inside." },
     "startDecorator": { "description": "Leading adornment for the select." },
     "sx": {

packages-internal/scripts/typescript-to-proptypes/src/generatePropTypes.ts

@@ -34,6 +34,10 @@ export interface GeneratePropTypesOptions {
    * Previous source code of the validator for each prop type
    */
   previousPropTypesSource?: Map<string, string>;
+  /**
+   * Previous JSDoc comment source for each prop type
+   */
+  previousPropTypesJsDoc?: Map<string, string>;
   /**
    * Given the `prop`, the `previous` source of the validator and the `generated` source:
    * What source should be injected? `previous` is `undefined` if the validator
@@ -108,6 +112,7 @@ export function generatePropTypes(
     includeJSDoc = true,
     sortProptypes = true,
     previousPropTypesSource = new Map<string, string>(),
+    previousPropTypesJsDoc = new Map<string, string>(),
     reconcilePropTypes = (_prop: PropTypeDefinition, _previous: string, generated: string) =>
       generated,
     shouldInclude,
@@ -306,7 +311,13 @@ export function generatePropTypes(
       })}${isRequired === true ? '.isRequired' : ''}`,
     );
 
-    return `${jsDoc(propTypeDefinition)}"${propTypeDefinition.name}": ${validatorSource},`;
+    const previousJsDoc = previousPropTypesJsDoc.get(propTypeDefinition.name);
+    const jsDocSource =
+      previousJsDoc !== undefined && validatorSource.includes('@typescript-to-proptypes-ignore')
+        ? `${previousJsDoc}\n`
+        : jsDoc(propTypeDefinition);
+
+    return `${jsDocSource}"${propTypeDefinition.name}": ${validatorSource},`;
   }
 
   const propTypes = component.types.slice();

packages-internal/scripts/typescript-to-proptypes/src/getPropTypesFromFile.ts

@@ -34,20 +34,52 @@ function getSymbolDocumentation({
 }: {
   symbol: ts.Symbol | undefined;
   project: TypeScriptProject;
+  parentType?: ts.Type;
 }): string | undefined {
   if (symbol === undefined) {
     return undefined;
   }
 
   const decl = symbol.getDeclarations();
-  if (decl) {
-    // @ts-ignore
-    const comments = ts.getJSDocCommentsAndTags(decl[0]) as readonly any[];
-    if (comments && comments.length === 1) {
-      const commentNode = comments[0];
-      if (ts.isJSDoc(commentNode)) {
-        return doctrine.unwrapComment(commentNode.getText()).trim();
+  if (decl && decl.length > 0) {
+    // This behavior tries to replicate how TypeScript itself merges JSDoc comments
+    // It is a complex logic that changes based on the kind of declarations
+    // There is an open issue for it in: https://github.com/microsoft/TypeScript/issues/30901
+    //
+    // For intersection types (A & B), the symbol may have multiple declarations.
+    // We need to handle three cases:
+    // 1. Intersection (type C = A & B): merge JSDoc from all declarations (deduplicated)
+    // 2. Interface extends (interface Z extends X, Y): use the (only) declaration's JSDoc
+    // 3. Interface override (interface W extends X { prop }): use the override's JSDoc (which is the only declaration)
+    //
+    // Note: TypeScript gives us:
+    // - Multiple declarations for intersection types (one from each constituent type)
+    // - Single declaration for interface extends (from the original interface)
+    // - Single declaration for interface override (from the overriding interface)
+
+    // Get JSDoc comments paired with their declarations
+    const declarationsWithComments = decl
+      .map((d) => {
+        const jsDocNodes = ts.getJSDocCommentsAndTags(d).filter((node) => ts.isJSDoc(node));
+        const comment =
+          jsDocNodes.length > 0
+            ? doctrine.unwrapComment(jsDocNodes[0].getText()).trim()
+            : undefined;
+        return { declaration: d, comment };
+      })
+      .filter((item) => item.comment !== undefined);
+
+    if (declarationsWithComments.length > 0) {
+      // If there's only one declaration with a comment, use it
+      // This handles both interface extends and interface override cases
+      if (declarationsWithComments.length === 1) {
+        return declarationsWithComments[0].comment;
       }
+
+      // Multiple declarations with comments - this is the intersection case (type C = A & B)
+      // Merge JSDoc comments, deduplicating identical ones
+      const uniqueComments = [...new Set(declarationsWithComments.map((d) => d.comment))];
+      return uniqueComments.join('\n');
     }
   }
 
@@ -116,7 +148,7 @@ function checkType({
     return createObjectType({ jsDoc: undefined });
   }
 
-  const typeNode = type as any;
+  const typeNode = type;
   const symbol = typeNode.aliasSymbol ? typeNode.aliasSymbol : typeNode.symbol;
   const jsDoc = getSymbolDocumentation({ symbol, project });
 
@@ -396,16 +428,18 @@ function checkSymbol({
   symbol,
   location,
   typeStack,
+  parentType,
 }: {
   project: PropTypesProject;
   symbol: ts.Symbol;
   location: ts.Node;
   typeStack: readonly number[];
+  parentType?: ts.Type;
 }): PropTypeDefinition {
   const declarations = symbol.getDeclarations();
   const declaration = declarations && declarations[0];
   const symbolFilenames = getSymbolFileNames(symbol);
-  const jsDoc = getSymbolDocumentation({ symbol, project });
+  const jsDoc = getSymbolDocumentation({ symbol, project, parentType });
 
   // TypeChecker keeps the name for
   // { a: React.ElementType, b: React.ReactElement | boolean }
@@ -498,9 +532,9 @@ function squashPropTypeDefinitions({
 }): PropTypeDefinition {
   const distinctDefinitions = new Map<number, PropTypeDefinition>();
   propTypeDefinitions.forEach((definition) => {
-    if (!distinctDefinitions.has(definition.$$id)) {
-      distinctDefinitions.set(definition.$$id, definition);
-    }
+    // Always update so that the last definition's jsDoc wins
+    // This ensures that when types are intersected (A & B), the last type's documentation is used
+    distinctDefinitions.set(definition.$$id, definition);
   });
 
   if (distinctDefinitions.size === 1 && !onlyUsedInSomeSignatures) {
@@ -513,16 +547,20 @@ function squashPropTypeDefinitions({
     types.push(createUndefinedType({ jsDoc: undefined }));
   }
 
+  // Use the last definition's jsDoc so that when types are intersected (A & B),
+  // the last type's documentation wins
+  const lastDefinition = definitions[definitions.length - 1];
+
   return {
-    name: definitions[0].name,
-    jsDoc: definitions[0].jsDoc,
+    name: lastDefinition.name,
+    jsDoc: lastDefinition.jsDoc,
     propType: createUnionType({
       // TODO: jsDoc from squashing is dropped
       jsDoc: undefined,
       types,
     }),
     filenames: new Set(definitions.flatMap((definition) => Array.from(definition.filenames))),
-    $$id: definitions[0].$$id,
+    $$id: lastDefinition.$$id,
   };
 }
 
@@ -544,6 +582,7 @@ function generatePropTypesFromNode(
         project: params.project,
         location: parsedComponent.location,
         typeStack: [(componentType as any).id],
+        parentType: componentType,
       }),
     );
 

packages-internal/scripts/typescript-to-proptypes/src/injectPropTypesInFile.ts

@@ -174,6 +174,7 @@ function createBabelPlugin({
   let alreadyImported = false;
   const originalPropTypesPaths = new Map<string, babel.NodePath>();
   const previousPropTypesSources = new Map<string, Map<string, string>>();
+  const previousPropTypesJsDocs = new Map<string, Map<string, string>>();
 
   function injectPropTypes(injectOptions: {
     path: babel.NodePath;
@@ -185,11 +186,14 @@ function createBabelPlugin({
 
     const previousPropTypesSource =
       previousPropTypesSources.get(nodeName) || new Map<string, string>();
+    const previousPropTypesJsDoc =
+      previousPropTypesJsDocs.get(nodeName) || new Map<string, string>();
 
     const source = generatePropTypes(props, {
       ...otherOptions,
       importedName: importName,
       previousPropTypesSource,
+      previousPropTypesJsDoc,
       reconcilePropTypes,
       shouldInclude: (prop) => shouldInclude({ component: props, prop, usedProps }),
     });
@@ -269,6 +273,9 @@ function createBabelPlugin({
               const previousPropTypesSource = new Map<string, string>();
               previousPropTypesSources.set(componentName, previousPropTypesSource);
 
+              const previousPropTypesJsDoc = new Map<string, string>();
+              previousPropTypesJsDocs.set(componentName, previousPropTypesJsDoc);
+
               let maybeObjectExpression = node.expression.right;
               // Component.propTypes = {} as any;
               //                       ^^^^^^^^^ expression.right
@@ -286,15 +293,38 @@ function createBabelPlugin({
                 maybeObjectExpression.properties.forEach((property) => {
                   if (babelTypes.isObjectProperty(property)) {
                     const validatorSource = code.slice(property.value.start, property.value.end);
+
+                    let propName: string | undefined;
                     if (babelTypes.isIdentifier(property.key)) {
-                      previousPropTypesSource.set(property.key.name, validatorSource);
+                      propName = property.key.name;
                     } else if (babelTypes.isStringLiteral(property.key)) {
-                      previousPropTypesSource.set(property.key.value, validatorSource);
+                      propName = property.key.value;
                     } else {
                       console.warn(
                         `${state.filename}: Possibly missed original proTypes source. Can only determine names for 'Identifiers' and 'StringLiteral' but received '${property.key.type}'.`,
                       );
                     }
+
+                    if (propName !== undefined) {
+                      previousPropTypesSource.set(propName, validatorSource);
+
+                      const leadingComments = property.leadingComments;
+                      if (leadingComments) {
+                        const jsDocComment = leadingComments.find(
+                          (c) => c.type === 'CommentBlock' && c.value.startsWith('*'),
+                        );
+                        if (
+                          jsDocComment &&
+                          jsDocComment.start != null &&
+                          jsDocComment.end != null
+                        ) {
+                          previousPropTypesJsDoc.set(
+                            propName,
+                            code.slice(jsDocComment.start, jsDocComment.end),
+                          );
+                        }
+                      }
+                    }
                   }
                 });
               }