[Feature][CSS] Add comment to the generated css type according to description.

Add description in comment of the index.d.ts for each property.
Properties with empty desc will be logged out to terminal.

issue: f-6748648523

Author: zhongyr

tools/css_generator/css_defines/1-top.json

@@ -6,7 +6,7 @@
   "version": "1.0",
   "author": "wangzhixuan",
   "consumption_status": "layout-only",
-  "desc": "top offset",
+  "desc": "The `top` CSS property participates in specifying the vertical position.",
   "compat_data": {
     "top": {
       "__compat": {

tools/css_generator/css_defines/120-overflow-x.json

@@ -10,7 +10,7 @@
     "hidden",
     "visible"
   ],
-  "desc": "",
+  "desc": "The `overflow-x` property specifies whether to clip the content when it overflows at the left and right edges.",
   "is_shorthand": false,
   "formal_syntax": "<overflow-block>"
 }

tools/css_generator/css_defines/121-overflow-y.json

@@ -10,7 +10,7 @@
     "hidden",
     "visible"
   ],
-  "desc": "",
+  "desc": "The `overflow-y` property specifies whether to clip the content when it overflows at the top and bottom edges.",
   "is_shorthand": false,
   "formal_syntax": "<overflow-block>"
 }

tools/css_generator/css_defines/2-left.json

@@ -6,7 +6,7 @@
   "version": "1.0",
   "author": "wangzhixuan",
   "consumption_status": "layout-only",
-  "desc": "left offset",
+  "desc": "The `left` CSS property participates in specifying the horizontal position of a positioned element.",
   "compat_data": {
     "left": {
       "__compat": {

tools/css_generator/css_defines/25-overflow.json

@@ -10,7 +10,7 @@
     "hidden",
     "visible"
   ],
-  "desc": "",
+  "desc": "The `overflow` property specifies whether to clip the content when the content of an element is too big.",
   "is_shorthand": true,
   "formal_syntax": "<overflow-block>{1,2}"
 }

tools/css_generator/css_defines/3-right.json

@@ -6,7 +6,7 @@
   "version": "1.0",
   "author": "wangzhixuan",
   "consumption_status": "layout-only",
-  "desc": "right offset",
+  "desc": "The `right` CSS property participates in specifying the horizontal position of a positioned element.",
   "compat_data": {
     "right": {
       "__compat": {

tools/css_generator/css_defines/4-bottom.json

@@ -6,7 +6,7 @@
   "version": "1.0",
   "author": "wangzhixuan",
   "consumption_status": "layout-only",
-  "desc": "bottom offset",
+  "desc": "The `bottom` CSS property participates in specifying the vertical position.",
   "compat_data": {
     "bottom": {
       "__compat": {

tools/css_generator/css_defines/98-background-image.json

@@ -6,6 +6,7 @@
   "version": "1.0",
   "author": "tangruiwen",
   "consumption_status": "skip",
-  "desc": "",
-  "is_shorthand": false
+  "desc": "The `background-image` CSS property sets one or more background images on an element.",
+  "is_shorthand": false,
+  "formal_syntax": "<bg-image>#"
 }

tools/css_generator/generate_types.py

@@ -33,6 +33,10 @@ def resolve_type(type_str, values_map, resolved_cache):
 
     # Handle direct primitives in the syntax string like '<length> | 0'
     if type_str not in values_map:
+        # It's a complex syntax like `url(<string>)` or `linear-gradient(...)`
+        if "(" in type_str:
+            return "(string & {})"
+
         if type_str == "string":
             return "(string & {})"
 
@@ -49,6 +53,12 @@ def resolve_type(type_str, values_map, resolved_cache):
         return type_str
 
     definition = values_map[type_str]
+
+    # If the definition itself is a complex function, treat as string
+    if "(" in definition:
+        resolved_cache[type_str] = "(string & {})"
+        return "(string & {})"
+
     parts = [part.strip() for part in definition.split("|")]
 
     resolved_parts = [resolve_type(part, values_map, resolved_cache) for part in parts]
@@ -78,6 +88,7 @@ def main():
 
     processed_properties = {}
     print(f"Processing property definitions from: {CSS_DEFINES_PATH}")
+    properties_with_empty_desc = []
 
     for filename in sorted(os.listdir(CSS_DEFINES_PATH)):
         if not filename.endswith(".json"):
@@ -96,8 +107,13 @@ def main():
             print(f"Warning: 'name' not found in {filename}, skipping.")
             continue
 
+        prop_desc = prop_define.get("desc", "").strip()
+        if not prop_desc:
+            properties_with_empty_desc.append(prop_name)
+
         print(f"- Processing {prop_name} from {filename}")
         prop_syntax = prop_define.get("formal_syntax")
+        original_syntax = prop_syntax
 
         final_types = set()
         if not prop_syntax:
@@ -109,6 +125,11 @@ def main():
             if has_multiplier:
                 prop_syntax = re.sub(r"\{[0-9,]+\}", "", prop_syntax).strip()
 
+            # Handle hash multiplier for comma-separated lists
+            has_hash_multiplier = prop_syntax.endswith("#")
+            if has_hash_multiplier:
+                prop_syntax = prop_syntax[:-1].strip()
+
             # Split syntax to handle cases like '<length-percentage> | auto'
             syntax_parts = [part.strip() for part in prop_syntax.split("|")]
             resolved_syntax_parts = [
@@ -120,7 +141,7 @@ def main():
                 for t in p.split("|"):
                     final_types.add(t.strip())
 
-            if has_multiplier:
+            if has_multiplier or has_hash_multiplier:
                 # For properties that can have multiple values (e.g., `overflow: hidden visible`),
                 # we also add a general string type to cover all combinations.
                 final_types.add("(string & {})")
@@ -131,7 +152,12 @@ def main():
         ts_type = " | ".join(sorted(list(final_types)))
 
         camel_prop_name = to_camel_case(prop_name)
-        processed_properties[camel_prop_name] = ts_type
+        processed_properties[camel_prop_name] = {
+            "type": ts_type,
+            "desc": prop_desc,
+            "syntax": original_syntax,
+            "name": prop_name,
+        }
 
     print(f"Loading Mako template from: {TEMPLATE_PATH}")
     template = Template(filename=TEMPLATE_PATH)
@@ -143,6 +169,11 @@ def main():
     with open(OUTPUT_PATH, "w", encoding="utf-8") as f:
         f.write(output_content)
 
+    if properties_with_empty_desc:
+        print("\nProperties with empty 'desc':")
+        for prop_name in properties_with_empty_desc:
+            print(f"- {prop_name}")
+
     print(f"\n✅ Successfully generated {OUTPUT_PATH}")
 
 

tools/css_generator/index.d.ts

@@ -4,6 +4,13 @@
  */
 
 export interface Properties {
+  /**
+   * The `top` CSS property participates in specifying the vertical position.
+   *
+   * **Syntax**: `<length-percentage> | auto`
+   *
+   * @see https://lynxjs.org/api/css/properties/top
+   */
   top?: 'auto' | (string & {}) | 0 | undefined;
   borderTopColor?: (string & {}) | number | undefined;
   backgroundOrigin?: (string & {}) | number | undefined;
@@ -28,7 +35,21 @@ export interface Properties {
   borderBottomStyle?: (string & {}) | number | undefined;
   implicitAnimation?: (string & {}) | number | undefined;
   borderRadius?: (string & {}) | number | undefined;
+  /**
+   * The `overflow-x` property specifies whether to clip the content when it overflows at the left and right edges.
+   *
+   * **Syntax**: `<overflow-block>`
+   *
+   * @see https://lynxjs.org/api/css/properties/overflow-x
+   */
   overflowX?: 'hidden' | 'visible' | undefined;
+  /**
+   * The `overflow-y` property specifies whether to clip the content when it overflows at the top and bottom edges.
+   *
+   * **Syntax**: `<overflow-block>`
+   *
+   * @see https://lynxjs.org/api/css/properties/overflow-y
+   */
   overflowY?: 'hidden' | 'visible' | undefined;
   wordBreak?: (string & {}) | number | undefined;
   backgroundClip?: (string & {}) | number | undefined;
@@ -37,8 +58,18 @@ export interface Properties {
   outlineStyle?: (string & {}) | number | undefined;
   outlineWidth?: (string & {}) | number | undefined;
   verticalAlign?: (string & {}) | number | undefined;
+  /**
+   * auto
+   *
+   * @see https://lynxjs.org/api/css/properties/caret-color
+   */
   caretColor?: (string & {}) | number | undefined;
   borderTopLeftRadius?: (string & {}) | number | undefined;
+  /**
+   * lynx layout direction
+   *
+   * @see https://lynxjs.org/api/css/properties/direction
+   */
   direction?: (string & {}) | number | undefined;
   relativeId?: (string & {}) | number | undefined;
   relativeAlignTop?: (string & {}) | number | undefined;
@@ -51,14 +82,49 @@ export interface Properties {
   relativeLeftOf?: (string & {}) | number | undefined;
   borderBottomLeftRadius?: (string & {}) | number | undefined;
   relativeLayoutOnce?: (string & {}) | number | undefined;
+  /**
+   * TBD
+   *
+   * @see https://lynxjs.org/api/css/properties/relative-center
+   */
   relativeCenter?: (string & {}) | number | undefined;
+  /**
+   * enter transition name
+   *
+   * @see https://lynxjs.org/api/css/properties/enter-transition-name
+   */
   enterTransitionName?: (string & {}) | number | undefined;
+  /**
+   * enter transition name
+   *
+   * @see https://lynxjs.org/api/css/properties/exit-transition-name
+   */
   exitTransitionName?: (string & {}) | number | undefined;
+  /**
+   * enter transition name
+   *
+   * @see https://lynxjs.org/api/css/properties/pause-transition-name
+   */
   pauseTransitionName?: (string & {}) | number | undefined;
+  /**
+   * enter transition name
+   *
+   * @see https://lynxjs.org/api/css/properties/resume-transition-name
+   */
   resumeTransitionName?: (string & {}) | number | undefined;
+  /**
+   * flex and wrap
+   *
+   * @see https://lynxjs.org/api/css/properties/flex-flow
+   */
   flexFlow?: (string & {}) | number | undefined;
   zIndex?: (string & {}) | number | undefined;
   textDecorationColor?: (string & {}) | number | undefined;
+  /**
+   * default linear layout gravity for children
+   *
+   * @see https://lynxjs.org/api/css/properties/linear-cross-gravity
+   */
   linearCrossGravity?: (string & {}) | number | undefined;
   borderTopRightRadius?: (string & {}) | number | undefined;
   marginInlineStart?: (string & {}) | number | undefined;
@@ -100,6 +166,11 @@ export interface Properties {
   justifyItems?: (string & {}) | number | undefined;
   justifySelf?: (string & {}) | number | undefined;
   gridAutoFlow?: (string & {}) | number | undefined;
+  /**
+   * The filter CSS property applies graphical effects like blur or color shift to an element. Filters are commonly used to adjust the rendering of images, backgrounds, and borders.
+   *
+   * @see https://lynxjs.org/api/css/properties/filter
+   */
   filter?: (string & {}) | number | undefined;
   listMainAxisGap?: (string & {}) | number | undefined;
   listCrossAxisGap?: (string & {}) | number | undefined;
@@ -115,6 +186,13 @@ export interface Properties {
   XAutoFontSize?: (string & {}) | number | undefined;
   XAutoFontSizePresetSizes?: (string & {}) | number | undefined;
   mask?: (string & {}) | number | undefined;
+  /**
+   * The `left` CSS property participates in specifying the horizontal position of a positioned element.
+   *
+   * **Syntax**: `<length-percentage> | auto`
+   *
+   * @see https://lynxjs.org/api/css/properties/left
+   */
   left?: 'auto' | (string & {}) | 0 | undefined;
   borderTopWidth?: (string & {}) | number | undefined;
   maskRepeat?: (string & {}) | number | undefined;
@@ -139,13 +217,32 @@ export interface Properties {
   fontFeatureSettings?: (string & {}) | number | undefined;
   fontOpticalSizing?: (string & {}) | number | undefined;
   color?: (string & {}) | number | undefined;
+  XPlaceholderColor?: (string & {}) | number | undefined;
+  XPlaceholderFontFamily?: (string & {}) | number | undefined;
+  XPlaceholderFontSize?: (string & {}) | number | undefined;
+  XPlaceholderFontWeight?: (string & {}) | number | undefined;
+  XPlaceholderFontStyle?: (string & {}) | number | undefined;
   opacity?: (string & {}) | number | undefined;
   display?: (string & {}) | number | undefined;
+  /**
+   * The `overflow` property specifies whether to clip the content when the content of an element is too big.
+   *
+   * **Syntax**: `<overflow-block>{1,2}`
+   *
+   * @see https://lynxjs.org/api/css/properties/overflow
+   */
   overflow?: 'hidden' | 'visible' | (string & {}) | undefined;
   height?: (string & {}) | number | undefined;
   width?: (string & {}) | number | undefined;
   maxWidth?: (string & {}) | number | undefined;
   minWidth?: (string & {}) | number | undefined;
+  /**
+   * The `right` CSS property participates in specifying the horizontal position of a positioned element.
+   *
+   * **Syntax**: `<length-percentage> | auto`
+   *
+   * @see https://lynxjs.org/api/css/properties/right
+   */
   right?: 'auto' | (string & {}) | 0 | undefined;
   maxHeight?: (string & {}) | number | undefined;
   minHeight?: (string & {}) | number | undefined;
@@ -157,6 +254,13 @@ export interface Properties {
   margin?: (string & {}) | number | undefined;
   marginLeft?: (string & {}) | number | undefined;
   marginRight?: (string & {}) | number | undefined;
+  /**
+   * The `bottom` CSS property participates in specifying the vertical position.
+   *
+   * **Syntax**: `<length-percentage> | auto`
+   *
+   * @see https://lynxjs.org/api/css/properties/bottom
+   */
   bottom?: 'auto' | (string & {}) | 0 | undefined;
   marginTop?: (string & {}) | number | undefined;
   marginBottom?: (string & {}) | number | undefined;
@@ -221,6 +325,13 @@ export interface Properties {
   aspectRatio?: (string & {}) | number | undefined;
   textDecoration?: (string & {}) | number | undefined;
   textShadow?: (string & {}) | number | undefined;
-  backgroundImage?: (string & {}) | number | undefined;
+  /**
+   * The `background-image` CSS property sets one or more background images on an element.
+   *
+   * **Syntax**: `<bg-image>#`
+   *
+   * @see https://lynxjs.org/api/css/properties/background-image
+   */
+  backgroundImage?: 'none' | (string & {}) | undefined;
   backgroundPosition?: (string & {}) | number | undefined;
 }