@aigne/doc-smith 0.8.14 → 0.8.15-beta.1

package/prompts/detail/custom/custom-components.md

@@ -1,19 +1,11 @@
 <custom_components_usage>
 When generating document details, you can use the following custom components at appropriate locations based on their descriptions and functionality to enhance document presentation:
 
-- `<x-card>`
-- `<x-cards>`
-- `<x-field>`
-- `<x-field-desc>`
-- `<x-field-group>`
-
-## `<x-card>` Single Card Component
+## XCard: Individual link display card
 
 Suitable for displaying individual links with a richer and more visually appealing presentation format.
 
-### Syntax Rules
-
-Attributes:
+### Attributes
 
 - `data-title` (required): Card title.
 - `data-icon` (optional): Icon identifier (e.g., lucide:icon-name or material-symbols:rocket-outline).
@@ -25,84 +17,80 @@ Attributes:
 - `data-horizontal` (optional): Whether to use horizontal layout.
 - `data-cta` (optional): Button text (call to action).
 
-Body content:
+### Children
 
 - Must be written within `<x-card>...</x-card>` children.
-- must be **plain text only**. Any markdown formatting will cause rendering errors and must be avoided.
+- **Plain Text Only**: All markdown formatting is prohibited, including inline formats like `code`, **bold**, _italic_, [links](), and block-level formats like headers (# ##), lists (- \*), code blocks (```), tables (|), and any other markdown syntax. Only plain text content is allowed.
 
-### Examples
+### Good Examples
 
-<card_good_examples>
 Example 1: Basic card with icon and description
 
-```
+```md
 <x-card data-title="alarm()" data-icon="lucide:alarm-clock"> SIGALRM: Sent when a real-time timer has expired. </x-card>
 ```
 
 Example 2: Horizontal card layout
 
-```
+```md
 <x-card data-title="Horizontal card" data-icon="lucide:atom" data-horizontal="true">
 This is an example of a horizontal card.
 </x-card>
 ```
 
-</card_good_examples>
+### Bad Examples
 
-<card_bad_examples>
-Example 1: Markdown formatting in card content
+Example 1: Inline Markdown formatting in card content
 
-```
+```md
 <x-card data-title="alarm()" data-icon="lucide:alarm-clock"> `SIGALRM`: Sent when a real-time timer has expired. </x-card>
 ```
 
 Example 2: Code block inside card content
 
-```
+```md
 <x-card data-title="ctrl_break()" data-icon="lucide:keyboard">
   Creates a listener for "ctrl-break" events.
 
-  \`\`\`rust
-  use tokio::signal::windows::ctrl_break;
-
-  #[tokio::main]
-  async fn main() -> std::io::Result<()> {
-  let mut stream = ctrl_break()?;
-  stream.recv().await;
-  println!("got ctrl-break");
-  Ok(())
-  }
-  \`\`\`
+\`\`\`rust
+use tokio::signal::windows::ctrl_break;
+
+#[tokio::main]
+async fn main() -> std::io::Result<()> {
+let mut stream = ctrl_break()?;
+stream.recv().await;
+println!("got ctrl-break");
+Ok(())
+}
+\`\`\`
 </x-card>
 ```
 
-</card_bad_examples>
-
-## `<x-cards>` Card List Component
+## XCards: Multiple cards container
 
 Suitable for displaying multiple links using a card list format, providing a richer and more visually appealing presentation.
 
-### Syntax Rules
-
-Attributes:
+### Attributes
 
 - data-columns (optional): Number of columns, integer (e.g., 2, 3). Default is 2.
   - Must contain multiple <x-card> elements internally.
 
-Body content:
+### Children
 
 - Must contain multiple <x-card> elements internally.
-- **Consistency requirement**: All <x-card> elements within the same <x-cards> must maintain visual consistency:
+
+### Usage Rules
+
+- **Visual Consistency**: All <x-card> elements within the same <x-cards> must maintain visual consistency:
   - It's recommended to always provide data-icon for each card.
   - Or all cards should have data-image.
   - Avoid mixing (some with icons, some with only images).
 
-### Examples
+### Good Examples
 
-<cards_good_examples>
 Example 1: Three-column cards with icons
 
-```
+```md
 <x-cards data-columns="3">
   <x-card data-title="Feature 1" data-icon="lucide:rocket">Description of Feature 1.</x-card>
   <x-card data-title="Feature 2" data-icon="lucide:bolt">Description of Feature 2.</x-card>
@@ -112,234 +100,326 @@ Example 1: Three-column cards with icons
 
 Example 2: Two-column cards with images
 
-```
+```md
 <x-cards data-columns="2">
-<x-card data-title="Card A" data-image="https://picsum.photos/id/10/300/300">Content A</x-card>
-<x-card data-title="Card B" data-image="https://picsum.photos/id/11/300/300">Content B</x-card>
+  <x-card data-title="Card A" data-image="https://picsum.photos/id/10/300/300">Content A</x-card>
+  <x-card data-title="Card B" data-image="https://picsum.photos/id/11/300/300">Content B</x-card>
 </x-cards>
 ```
 
-</cards_good_examples>
-
-## `<x-field>` Individual Field Component
+## XField: Structured data field
 
 Suitable for displaying API parameters, return values, context data, and any structured data with metadata in a clean, organized format. Supports nested structures for complex data types.
 
-### Syntax Rules
-
-Attributes:
+### Attributes
 
 - `data-name` (optional): The name of the field/parameter
-- `data-type` (optional): The data type of the field (e.g., "string", "number", "boolean", "object", "array")
+- `data-type` (optional): The data type of the field (e.g., "string", "number", "boolean", "symbol", "object", "array", "function")
 - `data-default` (optional): Default value for the field
 - `data-required` (optional): Whether the field is required ("true" or "false")
 - `data-deprecated` (optional): Whether the field is deprecated ("true" or "false")
 - `data-desc` (optional): Simple description of the field (plain text only)
-  - Mutually exclusive with `data-desc`: Use either `data-desc` attribute OR `<x-field-desc>` element, not both
 
-Body content:
+### Children
 
 - For simple types (string, number, boolean): children can be empty or contain exactly one `<x-field-desc>` element
 - For complex types (object, array), children contain nested `<x-field>` elements and optionally one `<x-field-desc>` element
-  - Maximum nesting depth: 5 levels (to avoid overly complex structures)
-- Only one `<x-field-desc>` element per `<x-field>` is allowed
-- **Always use opening/closing tags format**: `<x-field ...></x-field>` for all types
 
-### Examples
+### Usage Rules
+
+- **Opening/Closing Tags Format**: `<x-field ...></x-field>` for all types
+- **Maximum Nesting Depth**: 5 levels (to avoid overly complex structures)
+- **Description Mutually Exclusive**: Use either `data-desc` attribute OR `<x-field-desc>` element, not both
+- **Single Description Rule**: Only one `<x-field-desc>` element per `<x-field>` is allowed
+- **Grouping Requirement**: Wrap the outermost `<x-field>` elements with `<x-field-group>`, even if there's only one `<x-field>` element
+- **Recursive Structure**: Use recursive `<x-field>` structures to fully express complex object type hierarchies, decomposing all nested properties into more fundamental types
+- **Fixed Value Fields**: For fields that accept a limited set of predefined values (including enums, constants, or fixed strings), use `<x-field>` with the base data type (e.g., "string", "number") in the `data-type` attribute, and list all possible values in the description.
+- **Function-Type Fields**: For fields with `data-type="function"`, nest `<x-field>` elements for parameters (`data-name="parameters"`) and return value (`data-name="returnValue"`) **whenever their types are available**.
+
+### Good Examples
 
-<field_good_examples>
 Example 1: Simple field with all attributes
 
-```
-<x-field data-name="user_id" data-type="string" data-default="u0911" data-required="true" data-deprecated="true" data-desc="Unique identifier for the user. Must be a valid UUID v4 format."></x-field>
+```md
+### Returns
+
+<x-field-group>
+  <x-field data-name="user_id" data-type="string" data-default="u0911" data-required="true" data-deprecated="true" data-desc="Unique identifier for the user. Must be a valid UUID v4 format."></x-field>
+</x-field-group>
 ```
 
 Example 2: Field with markdown description
 
-```
-<x-field data-name="api_key" data-type="string" data-required="true">
-  <x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section. Keep it secure and never expose it in client-side code.</x-field-desc>
-</x-field>
+```md
+### Context
+
+<x-field-group>
+  <x-field data-name="api_key" data-type="string" data-required="true">
+    <x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section. Keep it secure and never expose it in client-side code.</x-field-desc>
+  </x-field>
+</x-field-group>
 ```
 
 Example 3: Nested object structure
 
-```
-<x-field data-name="session" data-type="object" data-required="true">
-  <x-field-desc markdown>Contains all **authentication** and **authorization** data for the current user session. This object is automatically populated after successful login.</x-field-desc>
-  <x-field data-name="user" data-type="object" data-required="true" data-desc="User basic information">
-    <x-field data-name="name" data-type="string" data-required="true" data-default="John Doe" data-desc="User name"></x-field>
-    <x-field data-name="email" data-type="string" data-required="true" data-default="john.doe@example.com">
-        <x-field-desc markdown>Primary email address used for **login** and **notifications**. Must be a valid email format.</x-field-desc>
+```md
+### Properties
+
+<x-field-group>
+  <x-field data-name="session" data-type="object" data-required="true">
+    <x-field-desc markdown>Contains all **authentication** and **authorization** data for the current user session. This object is automatically populated after successful login.</x-field-desc>
+    <x-field data-name="user" data-type="object" data-required="true" data-desc="User basic information">
+      <x-field data-name="name" data-type="string" data-required="true" data-default="John Doe" data-desc="User name"></x-field>
+      <x-field data-name="email" data-type="string" data-required="true" data-default="john.doe@example.com">
+          <x-field-desc markdown>Primary email address used for **login** and **notifications**. Must be a valid email format.</x-field-desc>
+      </x-field>
+      <x-field data-name="avatar" data-type="string" data-required="false" data-default="https://example.com/avatars/john-doe.jpg" data-desc="User avatar URL"></x-field>
+    </x-field>
+    <x-field data-name="permissions" data-type="array" data-required="true" data-default='["read", "write", "admin"]'>
+      <x-field-desc markdown>Array of **permission strings** that determine what actions the user can perform. Common values: `"read"`, `"write"`, `"admin"`, `"delete"`.</x-field-desc>
     </x-field>
-    <x-field data-name="avatar" data-type="string" data-required="false" data-default="https://example.com/avatars/john-doe.jpg" data-desc="User avatar URL"></x-field>
-  </x-field>
-  <x-field data-name="permissions" data-type="array" data-required="true" data-default='["read", "write", "admin"]'>
-    <x-field-desc markdown>Array of **permission strings** that determine what actions the user can perform. Common values: `"read"`, `"write"`, `"admin"`, `"delete"`.</x-field-desc>
   </x-field>
-</x-field>
+</x-field-group>
 ```
 
-</field_good_examples>
+Example 4: Multiple fields for Parameters
 
-<field_bad_examples>
-Example 1: Using multiple `<x-field-desc>` elements
+```md
+### Parameters
 
+<x-field-group>
+  <x-field data-name="user_id" data-type="string" data-required="true" data-desc="Unique identifier for the user. Must be a valid UUID v4 format."></x-field>
+  <x-field data-name="include_profile" data-type="boolean" data-required="false" data-default="false" data-desc="Whether to include the user's profile information in the response"></x-field>
+  <x-field data-name="options" data-type="object" data-required="false" data-desc="Additional options for the request">
+    <x-field data-name="format" data-type="string" data-required="false" data-default="json">
+      <x-field-desc>Response format: `json` or `xml`</x-field-desc>
+    </x-field>
+    <x-field data-name="locale" data-type="string" data-required="false" data-default="en" data-desc="Language locale for localized content"></x-field>
+  </x-field>
+</x-field-group>
 ```
-<x-field data-name="api_key" data-type="string" data-required="true">
-  <x-field-desc markdown>Your **API key** for authentication.</x-field-desc>
-  <x-field-desc markdown>Keep it secure and never expose it.</x-field-desc>
-</x-field>
+
+Example 5: Enum values with base type and description
+
+```md
+### Status
+
+<x-field-group>
+  <x-field data-name="status" data-type="string" data-required="true" data-default="pending" data-desc="Current status of the request. Possible values: 'pending', 'processing', 'completed', 'failed'"></x-field>
+  <x-field data-name="priority" data-type="number" data-required="false" data-default="1">
+    <x-field-desc markdown>Priority level for the task. **Valid values**: `1` (low), `2` (medium), `3` (high), `4` (urgent)</x-field-desc>
+  </x-field>
+</x-field-group>
 ```
 
-Example 2: Using self-closing tag
+Example 6: Function type field with nested parameters and return value
+
+```md
+### API Methods
 
+<x-field-group>
+  <x-field data-name="authenticate" data-type="function" data-required="true" data-desc="Authenticates a user with email and password">
+    <x-field data-name="parameters" data-type="object" data-desc="Function parameters">
+      <x-field data-name="email" data-type="string" data-required="true" data-desc="User's email address"></x-field>
+      <x-field data-name="password" data-type="string" data-required="true" data-desc="User's password"></x-field>
+      <x-field data-name="rememberMe" data-type="boolean" data-required="false" data-default="false" data-desc="Whether to keep user logged in"></x-field>
+    </x-field>
+    <x-field data-name="returnValue" data-type="object" data-desc="Function return value">
+      <x-field data-name="success" data-type="boolean" data-required="true" data-desc="Whether authentication was successful"></x-field>
+      <x-field data-name="token" data-type="string" data-required="false" data-desc="JWT token if authentication successful"></x-field>
+      <x-field data-name="user" data-type="object" data-required="false" data-desc="User information if authentication successful">
+        <x-field data-name="id" data-type="string" data-required="true" data-desc="User ID"></x-field>
+        <x-field data-name="name" data-type="string" data-required="true" data-desc="User's display name"></x-field>
+        <x-field data-name="email" data-type="string" data-required="true" data-desc="User's email address"></x-field>
+      </x-field>
+    </x-field>
+  </x-field>
+</x-field-group>
 ```
-<x-field data-name="user_id" data-type="string" data-required="true" data-desc="User identifier" />
+
+### Bad Examples
+
+Example 1: Using self-closing tag (violates "Opening/Closing Tags Format" rule)
+
+```md
+<x-field-group>
+  <x-field data-name="user_id" data-type="string" data-required="true" data-desc="User identifier" />
+</x-field-group>
 ```
 
-Example 3: Using both `data-desc` and `<x-field-desc>`
+Example 2: Using both `data-desc` and `<x-field-desc>` (violates "Description Mutually Exclusive" rule)
 
+```md
+<x-field-group>
+  <x-field data-name="api_key" data-type="string" data-required="true" data-desc="API key for authentication">
+    <x-field-desc markdown>Your **API key** for authentication. Keep it secure and never expose it.</x-field-desc>
+  </x-field>
+</x-field-group>
 ```
-<x-field data-name="api_key" data-type="string" data-required="true" data-desc="API key for authentication">
-  <x-field-desc markdown>Your **API key** for authentication. Keep it secure and never expose it.</x-field-desc>
-</x-field>
+
+Example 3: Using multiple `<x-field-desc>` elements (violates "Single Description Rule")
+
+```md
+<x-field-group>
+  <x-field data-name="config" data-type="object" data-required="true">
+    <x-field-desc markdown>Configuration object for the application.</x-field-desc>
+    <x-field-desc markdown>Contains all runtime settings and preferences.</x-field-desc>
+  </x-field>
+</x-field-group>
 ```
 
-Example 4: Nesting other child elements
+Example 4: Nesting other child elements (violates "Children" rule)
 
+```md
+<x-field-group>
+  <x-field data-name="user" data-type="object" data-required="true">
+    <div>User information</div>
+    <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
+  </x-field>
+</x-field-group>
 ```
-<x-field data-name="user" data-type="object" data-required="true">
-  <div>User information</div>
-  <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
+
+Example 5: Missing x-field-group wrapper (violates "Grouping Requirement" rule)
+
+```md
+<x-field data-name="apiConfig" data-type="object" data-required="true" data-desc="API configuration object">
+  <x-field data-name="baseUrl" data-type="string" data-required="true" data-desc="Base URL for API calls"></x-field>
+  <x-field data-name="timeout" data-type="number" data-required="false" data-default="5000" data-desc="Request timeout in milliseconds"></x-field>
 </x-field>
 ```
 
-</field_bad_examples>
+Example 6: Exceeding maximum nesting depth (violates "Maximum Nesting Depth" rule)
 
-## `<x-field-desc>` Field Description Component
+```md
+<x-field-group>
+  <x-field data-name="level1" data-type="object" data-required="true">
+    <x-field data-name="level2" data-type="object" data-required="true">
+      <x-field data-name="level3" data-type="object" data-required="true">
+        <x-field data-name="level4" data-type="object" data-required="true">
+          <x-field data-name="level5" data-type="object" data-required="true">
+            <x-field data-name="level6" data-type="string" data-required="true" data-desc="Too deep nesting"></x-field>
+          </x-field>
+        </x-field>
+      </x-field>
+    </x-field>
+  </x-field>
+</x-field-group>
+```
 
-Used to provide rich text descriptions for `<x-field>` elements, supporting inline markdown formatting for enhanced readability.
+## XFieldDesc Rich field description
 
-### Syntax Rules
+Used to provide rich text descriptions for `<x-field>` elements, supporting inline markdown formatting for enhanced readability.
 
-Attributes:
+### Attributes
 
 - `markdown` (required): **MUST** be set to "markdown" . This attribute is mandatory and cannot be omitted
   - **Validation**: `<x-field-desc>` without `markdown` attribute will be rejected
 
-Body content:
+### Children
 
 - Supports **bold text**, `inline code`, _italic text_, and other inline markdown
-- Cannot contain block-level elements (no code blocks, headers, lists)
-- **Description text as child content**: Description text must be provided as child content of `<x-field-desc>`, not as the value of the `markdown` attribute
+- Description text must be provided as child content of `<x-field-desc>`, not as the value of the `markdown` attribute
+- **Inline Markdown Only**: Allow only inline Markdown (e.g., `**bold**`, *italic*, `inline code`); block elements like code blocks, headings, lists, or tables are **not allowed**.
 
-Structure constraints:
+### Usage Rules
 
-- Must be child of `<x-field>`: `<x-field-desc>` can only appear as a child element of `<x-field>` components
+- **Parent Requirement**: Must be child of `<x-field>`: `<x-field-desc>` can only appear as a child element of `<x-field>` components
 
-### Examples
+### Good Examples
 
-<field_desc_good_examples>
 Example 1: Basic markdown description
 
-```
+```md
 <x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section. Keep it secure and never expose it in client-side code.</x-field-desc>
 ```
 
 Example 2: Description with inline code
 
-```
+```md
 <x-field-desc markdown>**JWT token** containing user identity and permissions. Expires in `24 hours` by default. Use the `refresh_token` to obtain a new one.</x-field-desc>
 ```
 
-</field_desc_good_examples>
+### Bad Examples
 
-<field_desc_bad_examples>
-Example 1: Missing markdown attribute
+Example 1: Missing markdown attribute (violates "markdown attribute required" rule)
 
-```
+```md
 <x-field data-name="api_key" data-type="string" data-required="true">
   <x-field-desc>Your **API key** for authentication.</x-field-desc>
 </x-field>
 ```
 
-Example 2: Incorrect markdown attribute usage
+Example 2: Incorrect markdown attribute usage (violates "markdown attribute format" rule)
 
-```
+```md
 <x-field data-name="api_key" data-type="string" data-required="true">
   <x-field-desc markdown="Your **API key** for authentication."></x-field-desc>
 </x-field>
 ```
 
-Example 3: Using self-closing tag
+Example 3: Using self-closing tag (violates "opening/closing tags format" rule)
 
-```
+```md
 <x-field data-name="user_id" data-type="string" data-required="true">
   <x-field-desc markdown />
 </x-field>
 ```
 
-Example 4: Containing block-level elements
+Example 4: Containing block-level elements (violates "Inline Content Only" rule)
 
-```
+````md
 <x-field data-name="config" data-type="object" data-required="true">
   <x-field-desc markdown>
-    Configuration object for the application.
-
-    # Important Notes
+    **Configuration settings** for the application.
+    
+    ## Important Notes
     - Set debug to true for development
     - Use production database in production
-
-    \`\`\`javascript
+    
+    ```javascript
     const config = { debug: true };
-    \`\`\`
+    ```
   </x-field-desc>
 </x-field>
-```
+````
 
-Example 5: Used outside of x-field component
+Example 5: Used outside of x-field component (violates "Parent Requirement" rule)
 
-```
+```md
 <x-field-desc markdown>This description is not inside an x-field component.</x-field-desc>
 ```
 
-Example 6: Used as child of other components
+Example 6: Used as child of other components (violates "Parent Requirement" rule)
 
-```
+```md
 <x-field-group>
   <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
   <x-field-desc markdown>This description is not inside an x-field component.</x-field-desc>
 </x-field-group>
 ```
 
-</field_desc_bad_examples>
-
-## `<x-field-group>` Field Group Component
+## XFieldGroup: Field grouping container
 
 Used to group multiple related `<x-field>` elements at the top level, indicating they belong to the same object or context. This provides better organization and visual grouping for related parameters.
 
-### Syntax Rules
-
-Attributes:
+### Attributes
 
 - No attributes required
 
-Body content:
+### Children
 
 - Only `<x-field>` elements are allowed as children
 
-Structure:
+### Usage Rules
 
-- Top-level organization: Used only at the top level for grouping related `<x-field>`
-- Cannot be nested inside other `<x-field>` or `<x-field-group>` elements
+- **Top-Level Only**: Used only at the top level for grouping related `<x-field>` elements. Cannot be nested inside other `<x-field>` or `<x-field-group>` elements
+- **Structured Data Only**: Use `<x-field-group>` for fields **other than simple types** (`string`, `number`, `boolean`, `symbol`), e.g., Properties, Context, Parameters, Return values. For simple-type fields, use plain Markdown text.
 
-### Examples
+### Good Examples
 
-<field_group_good_examples>
 Example 1: Product information fields
 
-```
+```md
 <x-field-group>
   <x-field data-name="name" data-type="string" data-required="true" data-desc="The name of the product."></x-field>
   <x-field data-name="description" data-type="string" data-required="false" data-desc="An optional description for the product."></x-field>
@@ -350,12 +430,11 @@ Example 1: Product information fields
 </x-field-group>
 ```
 
-</field_group_good_examples>
+### Bad Examples
 
-<field_group_bad_examples>
-Example 1: Nested inside x-field component
+Example 1: Nested inside x-field component (violates "Top-Level Only" rule)
 
-```
+```md
 <x-field data-name="user" data-type="object" data-required="true">
   <x-field-group>
     <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
@@ -364,9 +443,9 @@ Example 1: Nested inside x-field component
 </x-field>
 ```
 
-Example 2: Nested inside another x-field-group
+Example 2: Nested inside another x-field-group (violates "Top-Level Only" rule)
 
-```
+```md
 <x-field-group>
   <x-field data-name="user" data-type="object" data-required="true" data-desc="User information"></x-field>
   <x-field-group>
@@ -376,9 +455,9 @@ Example 2: Nested inside another x-field-group
 </x-field-group>
 ```
 
-Example 3: Containing non-x-field elements
+Example 3: Containing non-x-field elements (violates "Only x-field elements allowed" rule)
 
-```
+```md
 <x-field-group>
   <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
   <div>Additional information</div>
@@ -386,6 +465,21 @@ Example 3: Containing non-x-field elements
 </x-field-group>
 ```
 
-</field_group_bad_examples>
+Example 4: Empty x-field-group (violates "Must contain x-field elements" rule)
+
+```md
+<x-field-group>
+</x-field-group>
+```
+
+Example 5: Using x-field-group for simple-type (violates "Structured Data Only" rule)
+
+```md
+### appName
+
+<x-field-group>
+  <x-field data-name="appName" data-type="string" data-required="true" data-desc="specifies the name of the application"></x-field>
+</x-field-group>
+```
 
-</custom_components_usage>
+</custom_components_usage>