From cca9228fcb6502784c332eeb186a7860ce93243e Mon Sep 17 00:00:00 2001
From: Mohammer5 <jan-gerke@dhis2.org>
Date: Tue, 19 Nov 2024 16:24:26 +0800
Subject: [PATCH] chore: add updated API.md files

---
 collections/ui/API.md    |  8 +++---
 components/field/API.md  |  1 +
 components/input/API.md  |  2 +-
 components/label/API.md  |  1 +
 components/select/API.md | 57 +++++++++++++++++++++++++++++++++++++++-
 5 files changed, 64 insertions(+), 5 deletions(-)

diff --git a/collections/ui/API.md b/collections/ui/API.md
index 38859e31e6..46f9bf2e72 100644
--- a/collections/ui/API.md
+++ b/collections/ui/API.md
@@ -512,6 +512,7 @@ import { Field } from '@dhis2/ui'
 |error|custom|||Field status. Mutually exclusive with `valid` and `warning` props|
 |helpText|string|||Useful text within the field|
 |label|string|||Label at the top of the field|
+|labelId|string|||id passed to the label element|
 |name|string|||`name` will become the target of the `for`/`htmlFor` attribute on the `<label>` element|
 |required|boolean|||Inidcates this field is required|
 |valid|custom|||Field status. Mutually exclusive with `error` and `warning` props|
@@ -780,9 +781,9 @@ import { Input } from '@dhis2/ui'
 
 |Name|Type|Default|Required|Description|
 |---|---|---|---|---|
-|ariaLabel|string|||Add an aria-label attribute to the input element *|
 |ariaControls|string|||Add an aria-controls attribute to the input element *|
 |ariaHaspopup|string|||Add an aria-haspopup attribute to the input element *|
+|ariaLabel|string|||Add an aria-label attribute to the input element *|
 |autoComplete|string|||The [native `autocomplete` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-autocomplete)|
 |className|string||||
 |clearable|boolean|||Makes the input field clearable|
@@ -902,6 +903,7 @@ import { Label } from '@dhis2/ui'
 |dataTest|string|`'dhis2-uicore-label'`|||
 |disabled|boolean||||
 |htmlFor|string||||
+|id|string||||
 |required|boolean||||
 
 ### Layer
@@ -1916,7 +1918,7 @@ import { SingleSelectA11y } from '@dhis2/ui'
 |valueLabel|custom|`''`||When the option is not in the options list (e.g. not loaded or list is<br/>filtered), but a selected value needs to be displayed, then this prop can<br/>be used to supply the text to be shown.|
 |warning|custom|`false`||Applies 'warning' appearance for validation feedback. Mutually exclusive with `warning` and `valid` props *|
 |onBlur|function|`() => undefined`||Will be called when the combobox is loses focus *|
-|onEndReached|function|||Will be called when the last option is scrolled into the visible area *|
+|onEndReached|function|`() => undefined`||Will be called when the last option is scrolled into the visible area *|
 |onFilterChange|function|`() => undefined`||Will be called when the filter value changes *|
 |onFocus|function|`() => undefined`||Will be called when the combobox is being focused *|
 
@@ -2032,12 +2034,12 @@ import { Menu } from '@dhis2/ui'
 |optionUpdateStrategy|'off' │ 'polite' │ 'assertive'||||
 |selectRef|instanceOf(HTMLElement)||||
 |selected|string||||
+|tabIndex|string||||
 |onBlur|function||||
 |onClose|function||||
 |onEndReached|function||||
 |onFilterChange|function||||
 |onFilterInputKeyDown|function||||
-|onSearch|function||||
 
 ### SelectorBar
 
diff --git a/components/field/API.md b/components/field/API.md
index dc940876dc..7310ea7d8a 100644
--- a/components/field/API.md
+++ b/components/field/API.md
@@ -21,6 +21,7 @@ import { Field } from '@dhis2/ui'
 |error|custom|||Field status. Mutually exclusive with `valid` and `warning` props|
 |helpText|string|||Useful text within the field|
 |label|string|||Label at the top of the field|
+|labelId|string|||id passed to the label element|
 |name|string|||`name` will become the target of the `for`/`htmlFor` attribute on the `<label>` element|
 |required|boolean|||Inidcates this field is required|
 |valid|custom|||Field status. Mutually exclusive with `error` and `warning` props|
diff --git a/components/input/API.md b/components/input/API.md
index 3f2ea00a03..d0d5997084 100644
--- a/components/input/API.md
+++ b/components/input/API.md
@@ -14,9 +14,9 @@ import { Input } from '@dhis2/ui'
 
 |Name|Type|Default|Required|Description|
 |---|---|---|---|---|
-|ariaLabel|string|||Add an aria-label attribute to the input element *|
 |ariaControls|string|||Add an aria-controls attribute to the input element *|
 |ariaHaspopup|string|||Add an aria-haspopup attribute to the input element *|
+|ariaLabel|string|||Add an aria-label attribute to the input element *|
 |autoComplete|string|||The [native `autocomplete` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-autocomplete)|
 |className|string||||
 |clearable|boolean|||Makes the input field clearable|
diff --git a/components/label/API.md b/components/label/API.md
index 83d6b874a0..f09ea32e20 100644
--- a/components/label/API.md
+++ b/components/label/API.md
@@ -19,4 +19,5 @@ import { Label } from '@dhis2/ui'
 |dataTest|string|`'dhis2-uicore-label'`|||
 |disabled|boolean||||
 |htmlFor|string||||
+|id|string||||
 |required|boolean||||
diff --git a/components/select/API.md b/components/select/API.md
index ecf915c28c..a1531a601c 100644
--- a/components/select/API.md
+++ b/components/select/API.md
@@ -207,10 +207,65 @@ import { SingleSelectA11y } from '@dhis2/ui'
 |valueLabel|custom(function)|`''`||When the option is not in the options list (e.g. not loaded or list is<br/>filtered), but a selected value needs to be displayed, then this prop can<br/>be used to supply the text to be shown.|
 |warning|custom|`false`||Applies 'warning' appearance for validation feedback. Mutually exclusive with `warning` and `valid` props *|
 |onBlur|function|`() => undefined`||Will be called when the combobox is loses focus *|
-|onEndReached|function|||Will be called when the last option is scrolled into the visible area *|
+|onEndReached|function|`() => undefined`||Will be called when the last option is scrolled into the visible area *|
 |onFilterChange|function|`() => undefined`||Will be called when the filter value changes *|
 |onFocus|function|`() => undefined`||Will be called when the combobox is being focused *|
 
+### SingleSelectA11yField
+
+#### Usage
+
+To use `SingleSelectA11yField`, you can import the component from the `@dhis2/ui` library  
+
+
+```js
+import { SingleSelectA11yField } from '@dhis2/ui'
+```
+
+
+#### Props
+
+|Name|Type|Default|Required|Description|
+|---|---|---|---|---|
+|idPrefix|string||*|necessary for IDs that are required for accessibility *|
+|label|string||*|Label displayed above the input *|
+|options|arrayOf(custom)||*|An array of options *|
+|onChange|function||*|A callback that will be called with the new value or an empty string *|
+|autoFocus|boolean|||Will focus the select initially *|
+|className|string|||Additional class names that will be applied to the root element *|
+|clearText|custom(function)|||This will allow us to put an aria-label on the clear button *|
+|clearable|boolean|||Whether a clear button should be displayed or not *|
+|customOption|elementType|||Allows to override what's rendered inside the `button[role="option"]`.<br/>Can be overriden on an individual option basis *|
+|dataTest|string|||A value for a `data-test` attribute on the root element *|
+|dense|boolean|||Renders a select with lower height *|
+|disabled|boolean|||Disables all interactions with the select (except focussing) *|
+|empty|node|||Text or component to display when there are no options *|
+|error|custom|||Applies 'error' appearance for validation feedback. Mutually exclusive with `warning` and `valid` props *|
+|filterHelpText|string|||Help text that will be displayed below the input *|
+|filterLabel|string|||Value will be used as aria-label attribute on the filter input *|
+|filterPlaceholder|string|||Placeholder for the filter input *|
+|filterValue|string|||Value of the filter input *|
+|filterable|boolean|||Whether the select should display a filter input *|
+|helpText|string|||Help text, displayed below the input *|
+|loading|boolean|||Will show a loading indicator at the end of the options-list *|
+|menuLoadingText|string|||Text that will be displayed next to the loading indicator *|
+|menuMaxHeight|string|||Allows to modify the max height of the menu *|
+|noMatchText|custom(function)|||String that will be displayed when the select is being filtered but the options array is empty *|
+|optionUpdateStrategy|'off' │ 'polite' │ 'assertive'|||For a11y: How aggressively the user should be updated about changes in options *|
+|placeholder|string|||String to show when there's no value and no valueLabel *|
+|prefix|string|||String that will be displayed before the label of the selected option *|
+|required|boolean|||Whether a value is required or not *|
+|tabIndex|string │ number|||Standard HTML tab-index attribute that will be put on the combobox's root element *|
+|valid|custom|||Applies 'valid' appearance for validation feedback. Mutually exclusive with `warning` and `valid` props *|
+|validationText|string|||Text shown below input when `props.error` is true *|
+|value|string|||As of now, this component does not support being uncontrolled *|
+|valueLabel|custom(function)|||When the option is not in the options list (e.g. not loaded or list is<br/>filtered), but a selected value needs to be displayed, then this prop can<br/>be used to supply the text to be shown.|
+|warning|custom|||Applies 'warning' appearance for validation feedback. Mutually exclusive with `warning` and `valid` props *|
+|onBlur|function|||Will be called when the combobox is loses focus *|
+|onEndReached|function|||Will be called when the last option is scrolled into the visible area *|
+|onFilterChange|function|||Will be called when the filter value changes *|
+|onFocus|function|||Will be called when the combobox is being focused *|
+
 ### SingleSelectField
 
 #### Usage