docs(components): [layout] (#10682)

* docs(components): [layout]
* Adjust API style

* docs(components): [layout]

docs/en-US/component/layout.md

@@ -101,41 +101,45 @@ The classes are:
 - `hidden-lg-and-up` - hide when on large viewports and up
 - `hidden-xl-only` - hide when on extra large viewports only
 
-## Row Attributes
+## Row API
 
-| Name    | Description                         | Type   | Accepted Values                                          | Default |
-| ------- | ----------------------------------- | ------ | -------------------------------------------------------- | ------- |
-| gutter  | grid spacing                        | number | —                                                        | 0       |
-| justify | horizontal alignment of flex layout | string | start/end/center/space-around/space-between/space-evenly | start   |
-| align   | vertical alignment of flex layout   | string | top/middle/bottom                                        | top     |
-| tag     | custom element tag                  | string | (\*)                                                     | div     |
+### Row Attributes
 
-## Row Slots
+| Name    | Description                         | Type                                                                                           | Default |
+| ------- | ----------------------------------- | ---------------------------------------------------------------------------------------------- | ------- |
+| gutter  | grid spacing                        | ^[number]                                                                                      | 0       |
+| justify | horizontal alignment of flex layout | ^[string]`'start' \| 'end' \| 'center' \| 'space-around' \| 'space-between' \| 'space-evenly'` | start   |
+| align   | vertical alignment of flex layout   | ^[string]`'top' \| 'middle' \| 'bottom'`                                                       | top     |
+| tag     | custom element tag                  | ^[string]                                                                                      | div     |
 
-| Name | Description               | Subtags |
-| ---- | ------------------------- | ------- |
-| —    | customize default content | Col     |
+### Row Slots
 
-## Col Attributes
+| Name    | Description               | Subtags |
+| ------- | ------------------------- | ------- |
+| default | customize default content | Col     |
 
-| Name   | Description                                         | Type                                      | Accepted Values | Default |
-| ------ | --------------------------------------------------- | ----------------------------------------- | --------------- | ------- |
-| span   | number of column the grid spans                     | number                                    | —               | 24      |
-| offset | number of spacing on the left side of the grid      | number                                    | —               | 0       |
-| push   | number of columns that grid moves to the right      | number                                    | —               | 0       |
-| pull   | number of columns that grid moves to the left       | number                                    | —               | 0       |
-| xs     | `<768px` Responsive columns or column props object  | number/object (e.g. {span: 4, offset: 4}) | —               | —       |
-| sm     | `≥768px` Responsive columns or column props object  | number/object (e.g. {span: 4, offset: 4}) | —               | —       |
-| md     | `≥992px` Responsive columns or column props object  | number/object (e.g. {span: 4, offset: 4}) | —               | —       |
-| lg     | `≥1200px` Responsive columns or column props object | number/object (e.g. {span: 4, offset: 4}) | —               | —       |
-| xl     | `≥1920px` Responsive columns or column props object | number/object (e.g. {span: 4, offset: 4}) | —               | —       |
-| tag    | custom element tag                                  | string                                    | (\*)            | div     |
+## Col API
 
-## Col Slots
+### Col Attributes
 
-| Name | Description               |
-| ---- | ------------------------- |
-| —    | customize default content |
+| Name   | Description                                         | Type                                                                                  | Default |
+| ------ | --------------------------------------------------- | ------------------------------------------------------------------------------------- | ------- |
+| span   | number of column the grid spans                     | ^[number]                                                                             | 24      |
+| offset | number of spacing on the left side of the grid      | ^[number]                                                                             | 0       |
+| push   | number of columns that grid moves to the right      | ^[number]                                                                             | 0       |
+| pull   | number of columns that grid moves to the left       | ^[number]                                                                             | 0       |
+| xs     | `<768px` Responsive columns or column props object  | ^[number] / ^[object]`{span?: number, offset?: number, pull?: number, push?: number}` | —       |
+| sm     | `≥768px` Responsive columns or column props object  | ^[number] / ^[object]`{span?: number, offset?: number, pull?: number, push?: number}` | —       |
+| md     | `≥992px` Responsive columns or column props object  | ^[number] / ^[object]`{span?: number, offset?: number, pull?: number, push?: number}` | —       |
+| lg     | `≥1200px` Responsive columns or column props object | ^[number] / ^[object]`{span?: number, offset?: number, pull?: number, push?: number}` | —       |
+| xl     | `≥1920px` Responsive columns or column props object | ^[number] / ^[object]`{span?: number, offset?: number, pull?: number, push?: number}` | —       |
+| tag    | custom element tag                                  | ^[string]                                                                             | div     |
+
+### Col Slots
+
+| Name    | Description               |
+| ------- | ------------------------- |
+| default | customize default content |
 
 <style lang="scss">
 @use '../../examples/layout/index.scss';

packages/components/col/src/col.ts

@@ -11,42 +11,72 @@ export type ColSizeObject = {
 export type ColSize = number | ColSizeObject
 
 export const colProps = buildProps({
+  /**
+   * @description custom element tag
+   */
   tag: {
     type: String,
     default: 'div',
   },
+  /**
+   * @description number of column the grid spans
+   */
   span: {
     type: Number,
     default: 24,
   },
+  /**
+   * @description number of spacing on the left side of the grid
+   */
   offset: {
     type: Number,
     default: 0,
   },
+  /**
+   * @description number of columns that grid moves to the left
+   */
   pull: {
     type: Number,
     default: 0,
   },
+  /**
+   * @description number of columns that grid moves to the right
+   */
   push: {
     type: Number,
     default: 0,
   },
+  /**
+   * @description `<768px` Responsive columns or column props object
+   */
   xs: {
     type: definePropType<ColSize>([Number, Object]),
     default: () => mutable({} as const),
   },
+  /**
+   * @description `≥768px` Responsive columns or column props object
+   */
   sm: {
     type: definePropType<ColSize>([Number, Object]),
     default: () => mutable({} as const),
   },
+  /**
+   * @description `≥992px` Responsive columns or column props object
+   */
   md: {
     type: definePropType<ColSize>([Number, Object]),
     default: () => mutable({} as const),
   },
+  /**
+   * @description `≥1200px` Responsive columns or column props object
+   */
   lg: {
     type: definePropType<ColSize>([Number, Object]),
     default: () => mutable({} as const),
   },
+  /**
+   * @description `≥1920px` Responsive columns or column props object
+   */
   xl: {
     type: definePropType<ColSize>([Number, Object]),
     default: () => mutable({} as const),

packages/components/col/src/col.vue

@@ -1,5 +1,5 @@
 <template>
-  <component :is="tag" :class="[ns.b(), classes]" :style="style">
+  <component :is="tag" :class="colKls" :style="style">
     <slot />
   </component>
 </template>
@@ -29,7 +29,7 @@ const style = computed(() => {
   return styles
 })
 
-const classes = computed(() => {
+const colKls = computed(() => {
   const classes: string[] = []
   const pos = ['span', 'offset', 'pull', 'push'] as const
 
@@ -60,6 +60,6 @@ const classes = computed(() => {
   if (gutter.value) {
     classes.push(ns.is('guttered'))
   }
-  return classes
+  return [ns.b(), classes]
 })
 </script>

packages/components/row/src/row.ts

@@ -14,19 +14,31 @@ export const RowJustify = [
 export const RowAlign = ['top', 'middle', 'bottom'] as const
 
 export const rowProps = buildProps({
+  /**
+   * @description custom element tag
+   */
   tag: {
     type: String,
     default: 'div',
   },
+  /**
+   * @description grid spacing
+   */
   gutter: {
     type: Number,
     default: 0,
   },
+  /**
+   * @description horizontal alignment of flex layout
+   */
   justify: {
     type: String,
     values: RowJustify,
     default: 'start',
   },
+  /**
+   * @description vertical alignment of flex layout
+   */
   align: {
     type: String,
     values: RowAlign,

packages/components/row/src/row.vue

@@ -1,13 +1,5 @@
 <template>
-  <component
-    :is="tag"
-    :class="[
-      ns.b(),
-      ns.is(`justify-${props.justify}`, justify !== 'start'),
-      ns.is(`align-${props.align}`, align !== 'top'),
-    ]"
-    :style="style"
-  >
+  <component :is="tag" :class="rowKls" :style="style">
     <slot />
   </component>
 </template>
@@ -41,4 +33,10 @@ const style = computed(() => {
   styles.marginRight = styles.marginLeft = `-${props.gutter / 2}px`
   return styles
 })
+
+const rowKls = computed(() => [
+  ns.b(),
+  ns.is(`justify-${props.justify}`, props.justify !== 'start'),
+  ns.is(`align-${props.align}`, props.align !== 'top'),
+])
 </script>