From fc9edc7baba119c8cbfd6600e79a7b24fd220df0 Mon Sep 17 00:00:00 2001
From: mertsincan <sincan.mert@gmail.com>
Date: Sun, 7 Aug 2022 23:49:29 +0100
Subject: [PATCH] Update CascadeSelectDoc.vue

---
 src/views/cascadeselect/CascadeSelectDoc.vue | 373 ++++++++++++-------
 1 file changed, 242 insertions(+), 131 deletions(-)

diff --git a/src/views/cascadeselect/CascadeSelectDoc.vue b/src/views/cascadeselect/CascadeSelectDoc.vue
index da12a4aec..6f30ea0a9 100644
--- a/src/views/cascadeselect/CascadeSelectDoc.vue
+++ b/src/views/cascadeselect/CascadeSelectDoc.vue
@@ -17,9 +17,9 @@ import CascadeSelect from 'primevue/cascadeselect';
 		<p>CascadeSelect requires a value to bind and a collection of arbitrary objects with a nested hierarchy. <i>optionGroupLabel</i>
             is used for the text of a category and <i>optionGroupChildren</i> is to define the children of the category. Note that order of the <i>optionGroupChildren</i>
             matters and it should correspond to the data hierarchy.</p>
-                    
+
 <pre v-code><code>
-&lt;CascadeSelect v-model="selectedCity" :options="countries" optionLabel="cname" optionGroupLabel="name" 
+&lt;CascadeSelect v-model="selectedCity" :options="countries" optionLabel="cname" optionGroupLabel="name"
                         :optionGroupChildren="['states', 'cities']" style="minWidth: 14rem" &gt;
 
 </code></pre>
@@ -48,11 +48,11 @@ data() &#123;
                             &#123;cname: 'Townsville', code: 'A-TO'&#125;
                         ]
                     &#125;,
-                    
+
                 ]
             &#125;,
             &#123;
-                name: 'Canada', 
+                name: 'Canada',
                 code: 'CA',
                 states: [
                     &#123;
@@ -69,7 +69,7 @@ data() &#123;
                             &#123;cname: 'Toronto', code: 'C-TO'&#125;
                         ]
                     &#125;,
-                    
+
                 ]
             &#125;,
             &#123;
@@ -113,7 +113,7 @@ data() &#123;
         <p>Content of an item can be customized with the <i>option</i> template.</p>
 
 <pre v-code><code><template v-pre>
-&lt;CascadeSelect v-model="selectedCity" :options="countries" optionLabel="cname" optionGroupLabel="name" 
+&lt;CascadeSelect v-model="selectedCity" :options="countries" optionLabel="cname" optionGroupLabel="name"
         :optionGroupChildren="['states', 'cities']" style="minWidth: 14rem"&gt;
     &lt;template #option="slotProps"&gt;
         &lt;div class="country-item"&gt;
@@ -164,6 +164,12 @@ data() &#123;
                         <td>null</td>
                         <td>Property name or getter function to use as the value of an option, defaults to the option itself when not defined.</td>
                     </tr>
+                    <tr>
+                        <td>optionDisabled</td>
+                        <td>string | function</td>
+                        <td>null</td>
+                        <td>Property name or getter function to use as the disabled flag of an option, defaults to false when not defined.</td>
+                    </tr>
                     <tr>
                         <td>optionGroupLabel</td>
                         <td>string | function</td>
@@ -195,10 +201,46 @@ data() &#123;
                         <td>A property to uniquely identify an option.</td>
                     </tr>
                     <tr>
-                        <td>tabindex</td>
-                        <td>number</td>
+                        <td>inputId</td>
+                        <td>string</td>
                         <td>null</td>
-                        <td>Index of the element in tabbing order.</td>
+                        <td>Identifier of the underlying input element.</td>
+                    </tr>
+                    <tr>
+                        <td>inputStyle</td>
+                        <td>any</td>
+                        <td>null</td>
+                        <td>Inline style of the input field.</td>
+                    </tr>
+                    <tr>
+                        <td>inputClass</td>
+                        <td>string</td>
+                        <td>null</td>
+                        <td>Style class of the input field.</td>
+                    </tr>
+                    <tr>
+                        <td>inputProps</td>
+                        <td>object</td>
+                        <td>null</td>
+                        <td>Uses to pass all properties of the HTMLInputElement/HTMLSpanElement to the focusable input element inside the component.</td>
+                    </tr>
+                    <tr>
+                        <td>panelStyle</td>
+                        <td>any</td>
+                        <td>null</td>
+                        <td>Inline style of the overlay panel.</td>
+                    </tr>
+                    <tr>
+                        <td>panelClass</td>
+                        <td>string</td>
+                        <td>null</td>
+                        <td>Style class of the overlay panel.</td>
+                    </tr>
+                    <tr>
+                        <td>panelProps</td>
+                        <td>object</td>
+                        <td>null</td>
+                        <td>Uses to pass all properties of the HTMLDivElement to the overlay panel.</td>
                     </tr>
                     <tr>
                         <td>appendTo</td>
@@ -220,40 +262,64 @@ data() &#123;
                         <td>Icon to display in loading state.</td>
                     </tr>
                     <tr>
-                        <td>inputId</td>
+                        <td>autoOptionFocus</td>
+                        <td>boolean</td>
+                        <td>true</td>
+                        <td>Whether to focus on the first visible or selected element when the overlay panel is shown.</td>
+                    </tr>
+                    <tr>
+                        <td>searchLocale</td>
+                        <td>string</td>
+                        <td>undefined</td>
+                        <td>Locale to use in searching. The default locale is the host environment's current locale.</td>
+                    </tr>
+                    <tr>
+                        <td>searchMessage</td>
+                        <td>string</td>
+                        <td>{0} results are available</td>
+                        <td>Text to be displayed in hidden accessible field when filtering returns any results. Defaults to value from PrimeVue locale configuration.</td>
+                    </tr>
+                    <tr>
+                        <td>selectionMessage</td>
+                        <td>string</td>
+                        <td>{0} items selected</td>
+                        <td>Text to be displayed in hidden accessible field when options are selected. Defaults to value from PrimeVue locale configuration.</td>
+                    </tr>
+                    <tr>
+                        <td>emptySelectionMessage</td>
+                        <td>string</td>
+                        <td>No selected item</td>
+                        <td>Text to be displayed in hidden accessible field when any option is not selected. Defaults to value from PrimeVue locale configuration.</td>
+                    </tr>
+                    <tr>
+                        <td>emptySearchMessage</td>
+                        <td>string</td>
+                        <td>No results found</td>
+                        <td>Text to be displayed when filtering does not return any results. Defaults to value from PrimeVue locale configuration.</td>
+                    </tr>
+                    <tr>
+                        <td>emptyMessage</td>
+                        <td>string</td>
+                        <td>No available options</td>
+                        <td>Text to be displayed when there are no options available. Defaults to value from PrimeVue locale configuration.</td>
+                    </tr>
+                    <tr>
+                        <td>tabindex</td>
+                        <td>number</td>
+                        <td>0</td>
+                        <td>Index of the element in tabbing order.</td>
+                    </tr>
+                    <tr>
+                        <td>aria-label</td>
                         <td>string</td>
                         <td>null</td>
-                        <td>Identifier of the underlying input element.</td>
+                        <td>Defines a string value that labels an interactive element.</td>
                     </tr>
                     <tr>
-                        <td>inputProps</td>
-                        <td>object</td>
-                        <td>null</td>
-                        <td></td>
-                    </tr>
-                    <tr>
-                        <td>inputClass</td>
-                        <td>any</td>
-                        <td>null</td>
-                        <td>Style class of the input field.</td>
-                    </tr>
-                    <tr>
-                        <td>inputStyle</td>
-                        <td>any</td>
-                        <td>null</td>
-                        <td>Inline style of the input field.</td>
-                    </tr>
-                    <tr>
-                        <td>panelClass</td>
+                        <td>aria-labelledby</td>
                         <td>string</td>
                         <td>null</td>
-                        <td>Style class of the overlay panel.</td>
-                    </tr>
-                    <tr>
-                        <td>panelProps</td>
-                        <td>object</td>
-                        <td>null</td>
-                        <td></td>
+                        <td>Establishes relationships between the component and label(s) where its value should be one or more element IDs.</td>
                     </tr>
 				</tbody>
 			</table>
@@ -276,6 +342,21 @@ data() &#123;
                             event.value: Selected option value </td>
                         <td>Callback to invoke on value change.</td>
                     </tr>
+                    <tr>
+                        <td>focus</td>
+                        <td>event</td>
+                        <td>Callback to invoke when the component receives focus.</td>
+                    </tr>
+                    <tr>
+                        <td>blur</td>
+                        <td>event</td>
+                        <td>Callback to invoke when the component loses focus.</td>
+                    </tr>
+                    <tr>
+                        <td>click</td>
+                        <td>event</td>
+                        <td>Callback to invoke on click.</td>
+                    </tr>
                     <tr>
                         <td>group-change</td>
                         <td>event.originalEvent: Original event <br />
@@ -371,18 +452,21 @@ data() &#123;
                     <tr>
                         <td>p-cascadeselect-item</td>
                         <td>An item in the list.</td>
+                    </tr>
+                    <tr>
+                        <td>p-overlay-open</td>
+                        <td>Container element when overlay is visible.</td>
                     </tr>
 				</tbody>
 			</table>
 		</div>
 
         <h5>Accessibility</h5>
-        <DevelopmentSection>
-            <h6>Screen Reader</h6>
-            <p>Value to describe the component can either be provided with <i>aria-labelledby</i> or <i>aria-label</i> props. The cascadeselect element has a <i>combobox</i> role
-            in addition to <i>aria-haspopup</i> and <i>aria-expanded</i> attributes. The relation between the combobox and the popup is created with <i>aria-controls</i> that refers to the id of the popup.</p>
-            <p>The popup list has an id that refers to the <i>aria-controls</i> attribute of the <i>combobox</i> element and uses <i>tree</i> as the role. Each list item has a <i>treeitem</i> role along with <i>aria-label</i>, <i>aria-selected</i> and <i>aria-expanded</i> attributes. The container
-            element of a treenode has the <i>group</i> role. The <i>aria-setsize</i>, <i>aria-posinset</i> and <i>aria-level</i> attributes are calculated implicitly and added to each treeitem.</p>
+        <h6>Screen Reader</h6>
+        <p>Value to describe the component can either be provided with <i>aria-labelledby</i> or <i>aria-label</i> props. The cascadeselect element has a <i>combobox</i> role
+        in addition to <i>aria-haspopup</i> and <i>aria-expanded</i> attributes. The relation between the combobox and the popup is created with <i>aria-controls</i> that refers to the id of the popup.</p>
+        <p>The popup list has an id that refers to the <i>aria-controls</i> attribute of the <i>combobox</i> element and uses <i>tree</i> as the role. Each list item has a <i>treeitem</i> role along with <i>aria-label</i>, <i>aria-selected</i> and <i>aria-expanded</i> attributes. The container
+        element of a treenode has the <i>group</i> role. The <i>aria-setsize</i>, <i>aria-posinset</i> and <i>aria-level</i> attributes are calculated implicitly and added to each treeitem.</p>
 
 <pre v-code><code>
 &lt;span id="dd1"&gt;Options&lt;/span&gt;
@@ -392,82 +476,109 @@ data() &#123;
 
 </code></pre>
 
-            <h6>Closed State Keyboard Support</h6>
-            <div class="doc-tablewrapper">
-                <table class="doc-table">
-                    <thead>
-                        <tr>
-                            <th>Key</th>
-                            <th>Function</th>
-                        </tr>
-                    </thead>
-                    <tbody>
-                        <tr>
-                            <td><i>tab</i></td>
-                            <td>Moves focus to the cascadeselect element.</td>
-                        </tr>
-                        <tr>
-                            <td><i>space</i></td>
-                            <td>Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.</td>
-                        </tr>
-                        <tr>
-                            <td><i>down arrow</i></td>
-                            <td>Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.</td>
-                        </tr>
-                    </tbody>
-                </table>
-            </div>
+        <h6>Closed State Keyboard Support</h6>
+        <div class="doc-tablewrapper">
+            <table class="doc-table">
+                <thead>
+                    <tr>
+                        <th>Key</th>
+                        <th>Function</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <tr>
+                        <td><i>tab</i></td>
+                        <td>Moves focus to the cascadeselect element.</td>
+                    </tr>
+                    <tr>
+                        <td><i>space</i></td>
+                        <td>Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.</td>
+                    </tr>
+                    <tr>
+                        <td><i>enter</i></td>
+                        <td>Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.</td>
+                    </tr>
+                    <tr>
+                        <td><i>down arrow</i></td>
+                        <td>Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.</td>
+                    </tr>
+                    <tr>
+                        <td><i>up arrow</i></td>
+                        <td>Opens the popup and moves visual focus to the selected option, if there is none then last option receives the focus.</td>
+                    </tr>
+                    <tr>
+                        <td><i>any printable character</i></td>
+                        <td>Opens the popup and moves focus to the option whose label starts with the characters being typed, if there is none then first option receives the focus.</td>
+                    </tr>
+                </tbody>
+            </table>
+        </div>
 
-            <h6>Popup Keyboard Support</h6>
-            <div class="doc-tablewrapper">
-                <table class="doc-table">
-                    <thead>
-                        <tr>
-                            <th>Key</th>
-                            <th>Function</th>
-                        </tr>
-                    </thead>
-                    <tbody>
-                        <tr>
-                            <td><i>tab</i></td>
-                            <td>Hides the popup and moves focus to the next tabbable element.</td>
-                        </tr>
-                        <tr>
-                            <td><i>shift</i> + <i>tab</i></td>
-                            <td>Hides the popup and moves focus to the previous tabbable element.</td>
-                        </tr>
-                        <tr>
-                            <td><i>enter</i></td>
-                            <td>Selects the focused option and closes the popup.</td>
-                        </tr>
-                        <tr>
-                            <td><i>space</i></td>
-                            <td>Selects the focused option and closes the popup.</td>
-                        </tr>
-                        <tr>
-                            <td><i>escape</i></td>
-                            <td>Closes the popup, moves focus to the cascadeselect element.</td>
-                        </tr>
-                        <tr>
-                            <td><i>down arrow</i></td>
-                            <td>Moves focus to the next option.</td>
-                        </tr>
-                        <tr>
-                            <td><i>up arrow</i></td>
-                            <td>Moves focus to the previous option.</td>
-                        </tr>
-                        <tr>
-                            <td><i>right arrow</i></td>
-                            <td>If option is closed, opens the option otherwise moves focus to the first child option.</td>
-                        </tr>
-                        <tr>
-                            <td><i>left arrow</i></td>
-                            <td>If option is open, closes the option otherwise moves focus to the parent option.</td>
-                        </tr>
-                    </tbody>
-                </table>
-            </div>
-        </DevelopmentSection>
+        <h6>Popup Keyboard Support</h6>
+        <div class="doc-tablewrapper">
+            <table class="doc-table">
+                <thead>
+                    <tr>
+                        <th>Key</th>
+                        <th>Function</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <tr>
+                        <td><i>tab</i></td>
+                        <td>Hides the popup and moves focus to the next tabbable element. If there is none, the focusable option is selected and the overlay is closed then moves focus to next element in page.</td>
+                    </tr>
+                    <tr>
+                        <td><i>shift</i> + <i>tab</i></td>
+                        <td>Hides the popup and moves focus to the previous tabbable element.</td>
+                    </tr>
+                    <tr>
+                        <td><i>enter</i></td>
+                        <td>Selects the focused option and closes the popup.</td>
+                    </tr>
+                    <tr>
+                        <td><i>space</i></td>
+                        <td>Selects the focused option and closes the popup.</td>
+                    </tr>
+                    <tr>
+                        <td><i>escape</i></td>
+                        <td>Closes the popup, moves focus to the cascadeselect element.</td>
+                    </tr>
+                    <tr>
+                        <td><i>down arrow</i></td>
+                        <td>Moves focus to the next option.</td>
+                    </tr>
+                    <tr>
+                        <td><i>up arrow</i></td>
+                        <td>Moves focus to the previous option.</td>
+                    </tr>
+                    <tr>
+                        <td><i>alt</i> + <i>up arrow</i></td>
+                        <td>Selects the focused option and closes the popup, then moves focus to the cascadeselect element.</td>
+                    </tr>
+                    <tr>
+                        <td><i>right arrow</i></td>
+                        <td>If option is closed, opens the option otherwise moves focus to the first child option.</td>
+                    </tr>
+                    <tr>
+                        <td><i>left arrow</i></td>
+                        <td>If option is open, closes the option otherwise moves focus to the parent option.</td>
+                    </tr>
+                    <tr>
+                        <td><i>home</i></td>
+                        <td>Moves input cursor at the end, if not then moves focus to the first option.</td>
+                    </tr>
+                    <tr>
+                        <td><i>end</i></td>
+                        <td>Moves input cursor at the beginning, if not then moves focus to the last option.</td>
+                    </tr>
+                    <tr>
+                        <td><i>any printable character</i></td>
+                        <td>Moves focus to the option whose label starts with the characters being typed.</td>
+                    </tr>
+                </tbody>
+            </table>
+        </div>
 
 		<h5>Dependencies</h5>
 		<p>None.</p>
@@ -489,7 +600,7 @@ export default {
                 :optionGroupChildren="['states', 'cities']" style="minWidth: 14rem" placeholder="Select a City" />
 
         <h5>Templating</h5>
-        <CascadeSelect v-model="selectedCity2" :options="countries" optionLabel="cname" optionGroupLabel="name" 
+        <CascadeSelect v-model="selectedCity2" :options="countries" optionLabel="cname" optionGroupLabel="name"
                 :optionGroupChildren="['states', 'cities']" style="minWidth: 14rem" placeholder="Select a City">
             <template #option="slotProps">
                 <div class="country-item">
@@ -532,11 +643,11 @@ export default {
                                 {cname: 'Townsville', code: 'A-TO'}
                             ]
                         },
-                        
+
                     ]
                 },
                 {
-                    name: 'Canada', 
+                    name: 'Canada',
                     code: 'CA',
                     states: [
                         {
@@ -553,7 +664,7 @@ export default {
                                 {cname: 'Toronto', code: 'C-TO'}
                             ]
                         },
-                        
+
                     ]
                 },
                 {
@@ -588,7 +699,7 @@ export default {
                     ]
                 }
             ]
-        } 
+        }
     }
 }
 <\\/script>
@@ -611,7 +722,7 @@ img {
                 :optionGroupChildren="['states', 'cities']" style="minWidth: 14rem" placeholder="Select a City" />
 
         <h5>Templating</h5>
-        <CascadeSelect v-model="selectedCity2" :options="countries" optionLabel="cname" optionGroupLabel="name" 
+        <CascadeSelect v-model="selectedCity2" :options="countries" optionLabel="cname" optionGroupLabel="name"
                 :optionGroupChildren="['states', 'cities']" style="minWidth: 14rem" placeholder="Select a City">
             <template #option="slotProps">
                 <div class="country-item">
@@ -655,11 +766,11 @@ export default {
                             {cname: 'Townsville', code: 'A-TO'}
                         ]
                     },
-                    
+
                 ]
             },
             {
-                name: 'Canada', 
+                name: 'Canada',
                 code: 'CA',
                 states: [
                     {
@@ -676,7 +787,7 @@ export default {
                             {cname: 'Toronto', code: 'C-TO'}
                         ]
                     },
-                    
+
                 ]
             },
             {
@@ -735,7 +846,7 @@ img {
                     :option-group-children="['states', 'cities']" style="minWidth: 14rem" placeholder="Select a City"></p-cascadeselect>
 
             <h5>Templating</h5>
-            <p-cascadeselect v-model="selectedCity2" :options="countries" option-label="cname" option-group-label="name" 
+            <p-cascadeselect v-model="selectedCity2" :options="countries" option-label="cname" option-group-label="name"
                     :option-group-children="['states', 'cities']" style="minWidth: 14rem" placeholder="Select a City">
                 <template #option="slotProps">
                     <div class="country-item">
@@ -778,11 +889,11 @@ img {
                                     {cname: 'Townsville', code: 'A-TO'}
                                 ]
                             },
-                            
+
                         ]
                     },
                     {
-                        name: 'Canada', 
+                        name: 'Canada',
                         code: 'CA',
                         states: [
                             {
@@ -799,7 +910,7 @@ img {
                                     {cname: 'Toronto', code: 'C-TO'}
                                 ]
                             },
-                            
+
                         ]
                     },
                     {