html-combobox-element 0.0.1 → 0.0.2-beta.10

package/README.md

@@ -0,0 +1 @@
+# html-combobox-element

package/combobox-skill/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: HTMLComboboxElement
+description: This element provides both "dropdown" or "combobox" functionality wia HTMLSelectElement compatible API, and it may be fully customized. 
+---
+
+## References
+- Consider that <combo-box> is the same as <select> (HTMLSelectElement), but uses <box-option> instead of <option>.
+- Consider that <box-option> is the same as <option> (HTMLOptionElement), just fully customizable.
+- Note that browsers interpret <combo-box> as a REAL form element.
+- Additions that extends the <combo-box> "dropdown" functionality with "combobox" functionality are:
+    - attributes:
+        - filterable: If present, the search input in picker is shown, and during typing, <box-option>'s which textContent didn't match the input value are hidden.
+        - searchable: If present, the search input in picker is shown, to implement custom logic filtering, like server search, fuzzy matching, etc.
+        - clearable: If present, shows a remove button on each selected tag. If multiple is present, an additional clear-all button is shown.
+        - query: Controls the picker's search input value.
+    - events:
+        - input: Fires when user typing something in the picker search input.
+        - close: Fires when the picker closes.
+        - search: Fires when user presses Enter when the picker's search input is in focus.
+    - properties:
+        - changed: Readonly, boolean. Indicates whether the value has been changed after the picker has been opened.
+        - valueAsArray: Readonly, Array<string>. An array of value attributes from all selected <box-option> elements.
+- Typescript:
+    - The HTMLComboboxElement, ComboboxEvent and ComboboxInputEvent interfaces are globally available and don't require import.
+    - The <combo-box>, <box-option> and <box-tag> are declared globally as valid JSX tags including props.
+- Only if React < 19 is used, read the ./legacy-react-restrictions.md
+- Only if you need fully custom <box-tag>, read the ./custom-box-tag.md
+- Only if you need to customize the <combo-box>, read the ./customization.md
+- Only if you need to share the project styles to the <combo-box>, read the ./share-styles.md.
+
+
+## Constraints
+- Changing the <combo-box> source code is strictly prohibited!
+
+## Requirements
+- Direct descendants of <combo-box> may be ONLY:
+    - <box-tag>: optional, max 1, must be first if present.
+    - <box-option>: zero or more, any position.
+    - <optgroup>: zero or more, any position with only <box-option> as direct descendants.
+
+## Usage success criteria
+- The constraints listed above are not violated.
+- The requirements listed above are met.

package/combobox-skill/custom-box-tag.md

@@ -0,0 +1,17 @@
+---
+name: customization
+description: Use this when you need fully custom tags for <combo-box> element. 
+---
+
+## References
+- Note that <box-tag> is a container with named slots.
+- Note that <box-option> provides content for <box-tag> slots.
+
+## Requirements
+- The <box-tag> must contain a direct descendant with attribute `part="clear-tag"`.
+- The <box-tag> slots must also define their part attribute for customization.
+- The <box-tag> must be used only if a fully custom tag is needed.
+- The <box-option> must still use part attribute for customization.
+
+## Constraints
+- Multiple <box-tag> descendants are prohibited.

package/combobox-skill/customization.md

@@ -0,0 +1,23 @@
+---
+name: customization
+description: Use this when you need to write CSS to customize the <combo-box> element. 
+---
+
+## References
+- The <combo-box> is a web-component with shadow root.
+- The <combo-box> exposed parts are:
+  - internal: The container that arrange shadow root descendants.
+  - placeholder: Tag: <div>. Shown when there are no selected tags.
+  - tags: Tag: <div>. Selected tag's container.
+  - clear-all: Tag: <button>. 
+  - dropdown: Tag: <div>. The <combo-box> picker implemented with Popover API.
+  - search-input: Tag: <input>. The picker's search input.
+  - options: Tag: <div>. A scrollable container for <box-option>'s.
+  - tag: Represent <box-tag>.
+  - tag-label: Tag: <span>. Alias to <box-tag> > tag-label. Displays the selected <box-option> label value.
+  - clear-tag: Tag: <div> with tabindex="0". Alias to <box-tag> > clear-tag.
+  - option: Represent <box-option>.
+  - option selected: Represent selected <box-option>.
+
+## Constraints 
+- Interfere the <combo-box> styles without an explicit request from the user is strictly prohibited.

package/combobox-skill/legacy-react-restrictions.md

@@ -0,0 +1,14 @@
+---
+name: legacy-react-restrictions
+description: Use this when you need to use the <combo-box> in a legacy (i.e. less that 19v) React environment.
+---
+
+## References
+- Note React <19 web-components events listeners limitations.
+- Note that there are no special requirements for working with attributes.
+
+## Requirements
+- The legacy React event listener attachment must be used.
+
+## Constraints
+- Creating a wrapper around <combo-box> without an explicit request from the user is strictly prohibited.

package/combobox-skill/share-styles.md

@@ -0,0 +1,17 @@
+---
+name: share-styles
+description: Use this, when you need to share document/page styles to the <combo-box> shadow root. 
+---
+
+## References
+- The <combo-box> uses a constructed style sheet and shares it across all instances.
+- Style sharing is achieved using one or both of two HTMLComboboxElement static methods:
+  - loadCssFromUrls(urls: string[]): adds urls as CSS @import directives to the constructed StyleSheet.
+  - loadCssFromDocumentStyleSheets(): the method internally WAITS until document fully load, and ONLY then inserts all document.styleSheets CSS rules into constructed StyleSheet.
+
+## Requirements
+- Styles must be shared once in the App root.
+- The CSSStyleSheet.insertRule() parsing limitations must be taken into account.
+
+## Constraints 
+- Sharing styles without an explicit request from the user is strictly prohibited.