Skip to content

Commit e1af559

Browse files
vursenvursen
authored
docs: explain autoResponsive mode in component's JSDoc (#8758)
1 parent 6525bd4 commit e1af559

File tree

4 files changed

+166
-2
lines changed

4 files changed

+166
-2
lines changed

‎packages/form-layout/src/vaadin-form-layout-mixin.d.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ export declare class FormLayoutMixinClass {
6363
responsiveSteps: FormLayoutResponsiveStep[];
6464

6565
/**
66-
* Enables the auto responsive mode where the component automatically creates and adjusts
66+
* Enables the auto responsive mode in which the component automatically creates and adjusts
6767
* columns based on the container's width. Columns have a fixed width defined by `columnWidth`
6868
* and their number increases up to the limit set by `maxColumns`. The component dynamically
6969
* adjusts the number of columns as the container size changes. When this mode is enabled,

‎packages/form-layout/src/vaadin-form-layout-mixin.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ export const FormLayoutMixin = (superClass) =>
9393
},
9494

9595
/**
96-
* Enables the auto responsive mode where the component automatically creates and adjusts
96+
* Enables the auto responsive mode in which the component automatically creates and adjusts
9797
* columns based on the container's width. Columns have a fixed width defined by `columnWidth`
9898
* and their number increases up to the limit set by `maxColumns`. The component dynamically
9999
* adjusts the number of columns as the container size changes. When this mode is enabled,

‎packages/form-layout/src/vaadin-form-layout.d.ts

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,88 @@ export * from './vaadin-form-layout-mixin.js';
9090
* </vaadin-form-layout>
9191
* ```
9292
*
93+
* ### Auto Responsive Mode
94+
*
95+
* To avoid manually dealing with responsive breakpoints, Form Layout provides an auto-responsive mode
96+
* that automatically creates and adjusts fixed-width columns based on the container's available space.
97+
* The [`columnWidth`](#/elements/vaadin-form-layout#property-columnWidth) and
98+
* [`maxColumns`](#/elements/vaadin-form-layout#property-maxColumns) properties control the column width
99+
* (13em by default) and the maximum number of columns (10 by default) that the Form Layout can create.
100+
*
101+
* ```html
102+
* <vaadin-form-layout auto-responsive>
103+
* <vaadin-text-field label="First Name"></vaadin-text-field>
104+
* <vaadin-text-field label="Last Name"></vaadin-text-field>
105+
* <vaadin-text-area label="Address" colspan="2"></vaadin-text-area>
106+
* </vaadin-form-layout>
107+
* ```
108+
*
109+
* #### Organizing Fields into Rows
110+
*
111+
* By default, each field is placed on a new row. To organize fields into rows, you can either:
112+
*
113+
* 1. Manually wrap fields into [`<vaadin-form-row>`](#/elements/vaadin-form-row) elements.
114+
*
115+
* 2. Enable the [`autoRows`](#/elements/vaadin-form-layout#property-autoRows) property to
116+
* let Form Layout automatically arrange fields in available columns, wrapping to a new
117+
* row when necessary. `<br>` elements can be used to force a new row.
118+
*
119+
* Here is an example of using `<vaadin-form-row>`:
120+
*
121+
* ```html
122+
* <vaadin-form-layout auto-responsive>
123+
* <vaadin-form-row>
124+
* <vaadin-text-field label="First Name"></vaadin-text-field>
125+
* <vaadin-text-field label="Last Name"></vaadin-text-field>
126+
* </vaadin-form-row>
127+
* <vaadin-form-row>
128+
* <vaadin-text-area label="Address" colspan="2"></vaadin-text-area>
129+
* </vaadin-form-row>
130+
* </vaadin-form-layout>
131+
* ```
132+
*
133+
* #### Expanding Columns and Fields
134+
*
135+
* You can configure Form Layout to expand columns to evenly fill any remaining space after
136+
* all fixed-width columns have been created.
137+
* To enable this, set the [`expandColumns`](#/elements/vaadin-form-layout#property-expandColumns)
138+
* property to `true`.
139+
*
140+
* Also, Form Layout can stretch fields to make them take up all available space within columns.
141+
* To enable this, set the [`expandFields`](#/elements/vaadin-form-layout#property-expandFields)
142+
* property to `true`.
143+
*
144+
* #### Customizing Label Position
145+
*
146+
* By default, Form Layout displays labels above the fields. To position labels beside fields, you
147+
* need to wrap each field in a `<vaadin-form-item>` element and define its labels on the wrapper.
148+
* Then, you can enable the [`labelsAside`](#/elements/vaadin-form-layout#property-labelsAside)
149+
* property:
150+
*
151+
* ```html
152+
* <vaadin-form-layout auto-responsive labels-aside>
153+
* <vaadin-form-row>
154+
* <vaadin-form-item>
155+
* <label slot="label">First Name</label>
156+
* <vaadin-text-field></vaadin-text-field>
157+
* </vaadin-form-item>
158+
* <vaadin-form-item>
159+
* <label slot="label">Last Name</label>
160+
* <vaadin-text-field></vaadin-text-field>
161+
* </vaadin-form-item>
162+
* </vaadin-form-row>
163+
* <vaadin-form-row>
164+
* <vaadin-form-item colspan="2">
165+
* <label slot="label">Address</label>
166+
* <vaadin-text-area></vaadin-text-area>
167+
* </vaadin-form-item>
168+
* </vaadin-form-row>
169+
* </vaadin-form-layout>
170+
* ```
171+
*
172+
* With this, FormLayout will display labels beside fields, falling back to
173+
* the default position above the fields only when there isn't enough space.
174+
*
93175
* ### CSS Properties Reference
94176
*
95177
* The following custom CSS properties are available on the `<vaadin-form-layout>`

‎packages/form-layout/src/vaadin-form-layout.js

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,88 @@ registerStyles('vaadin-form-layout', formLayoutStyles, { moduleId: 'vaadin-form-
9393
* </vaadin-form-layout>
9494
* ```
9595
*
96+
* ### Auto Responsive Mode
97+
*
98+
* To avoid manually dealing with responsive breakpoints, Form Layout provides an auto-responsive mode
99+
* that automatically creates and adjusts fixed-width columns based on the container's available space.
100+
* The [`columnWidth`](#/elements/vaadin-form-layout#property-columnWidth) and
101+
* [`maxColumns`](#/elements/vaadin-form-layout#property-maxColumns) properties control the column width
102+
* (13em by default) and the maximum number of columns (10 by default) that the Form Layout can create.
103+
*
104+
* ```html
105+
* <vaadin-form-layout auto-responsive>
106+
* <vaadin-text-field label="First Name"></vaadin-text-field>
107+
* <vaadin-text-field label="Last Name"></vaadin-text-field>
108+
* <vaadin-text-area label="Address" colspan="2"></vaadin-text-area>
109+
* </vaadin-form-layout>
110+
* ```
111+
*
112+
* #### Organizing Fields into Rows
113+
*
114+
* By default, each field is placed on a new row. To organize fields into rows, you can either:
115+
*
116+
* 1. Manually wrap fields into [`<vaadin-form-row>`](#/elements/vaadin-form-row) elements.
117+
*
118+
* 2. Enable the [`autoRows`](#/elements/vaadin-form-layout#property-autoRows) property to
119+
* let Form Layout automatically arrange fields in available columns, wrapping to a new
120+
* row when necessary. `<br>` elements can be used to force a new row.
121+
*
122+
* Here is an example of using `<vaadin-form-row>`:
123+
*
124+
* ```html
125+
* <vaadin-form-layout auto-responsive>
126+
* <vaadin-form-row>
127+
* <vaadin-text-field label="First Name"></vaadin-text-field>
128+
* <vaadin-text-field label="Last Name"></vaadin-text-field>
129+
* </vaadin-form-row>
130+
* <vaadin-form-row>
131+
* <vaadin-text-area label="Address" colspan="2"></vaadin-text-area>
132+
* </vaadin-form-row>
133+
* </vaadin-form-layout>
134+
* ```
135+
*
136+
* #### Expanding Columns and Fields
137+
*
138+
* You can configure Form Layout to expand columns to evenly fill any remaining space after
139+
* all fixed-width columns have been created.
140+
* To enable this, set the [`expandColumns`](#/elements/vaadin-form-layout#property-expandColumns)
141+
* property to `true`.
142+
*
143+
* Also, Form Layout can stretch fields to make them take up all available space within columns.
144+
* To enable this, set the [`expandFields`](#/elements/vaadin-form-layout#property-expandFields)
145+
* property to `true`.
146+
*
147+
* #### Customizing Label Position
148+
*
149+
* By default, Form Layout displays labels above the fields. To position labels beside fields, you
150+
* need to wrap each field in a `<vaadin-form-item>` element and define its labels on the wrapper.
151+
* Then, you can enable the [`labelsAside`](#/elements/vaadin-form-layout#property-labelsAside)
152+
* property:
153+
*
154+
* ```html
155+
* <vaadin-form-layout auto-responsive labels-aside>
156+
* <vaadin-form-row>
157+
* <vaadin-form-item>
158+
* <label slot="label">First Name</label>
159+
* <vaadin-text-field></vaadin-text-field>
160+
* </vaadin-form-item>
161+
* <vaadin-form-item>
162+
* <label slot="label">Last Name</label>
163+
* <vaadin-text-field></vaadin-text-field>
164+
* </vaadin-form-item>
165+
* </vaadin-form-row>
166+
* <vaadin-form-row>
167+
* <vaadin-form-item colspan="2">
168+
* <label slot="label">Address</label>
169+
* <vaadin-text-area></vaadin-text-area>
170+
* </vaadin-form-item>
171+
* </vaadin-form-row>
172+
* </vaadin-form-layout>
173+
* ```
174+
*
175+
* With this, FormLayout will display labels beside fields, falling back to
176+
* the default position above the fields only when there isn't enough space.
177+
*
96178
* ### CSS Properties Reference
97179
*
98180
* The following custom CSS properties are available on the `<vaadin-form-layout>`

0 commit comments

Comments
 (0)