@cordwainer/cw-elements 1.0.2 → 1.1.0-alpha.1

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@cordwainer/cw-elements",
-  "version": "1.0.2",
+  "version": "1.1.0-alpha.1",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -1464,6 +1464,360 @@
             ]
           }
         },
+        {
+          "name": "cw-combobox",
+          "description": "Comboboxes combine a text input with a listbox, allowing users to filter a list of options by typing.\n---\n\n\n### **Events:**\n - **cw-change** - Emitted when the control's value changes.\n- **cw-clear** - Emitted when the control's value is cleared.\n- **cw-input** - Emitted when the control receives input, including as the user types to filter options.\n- **cw-focus** - Emitted when the control gains focus.\n- **cw-blur** - Emitted when the control loses focus.\n- **cw-show** - Emitted when the combobox's listbox opens.\n- **cw-after-show** - Emitted after the combobox's listbox opens and all animations are complete.\n- **cw-hide** - Emitted when the combobox's listbox closes.\n- **cw-after-hide** - Emitted after the combobox's listbox closes and all animations are complete.\n- **cw-invalid** - Emitted when the form control has been checked for validity and its constraints aren't satisfied.\n\n### **Methods:**\n - **show()** - Shows the listbox.\n- **hide()** - Hides the listbox.\n- **checkValidity()** - Checks for validity but does not show a validation message. Returns `true` when valid and `false` when invalid.\n- **getForm(): _HTMLFormElement | null_** - Gets the associated form, if one exists.\n- **reportValidity()** - Checks for validity and shows the browser's validation message if the control is invalid.\n- **setCustomValidity(message: _string_)** - Sets a custom validation message. Pass an empty string to restore validity.\n- **focus(options: _FocusOptions_)** - Sets focus on the control.\n- **blur()** - Removes focus from the control.\n\n### **Slots:**\n - _default_ - The listbox options. Must be `<cw-option>` elements. You can use `<cw-divider>` to group items visually.\n- **label** - The input's label. Alternatively, you can use the `label` attribute.\n- **prefix** - Used to prepend a presentational icon or similar element to the combobox.\n- **suffix** - Used to append a presentational icon or similar element to the combobox.\n- **clear-icon** - An icon to use in lieu of the default clear icon.\n- **expand-icon** - The icon to show when the control is expanded and collapsed. Rotates on open and close.\n- **no-options** - Content to show in the listbox when no options match the current filter.\n- **help-text** - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.\n\n### **CSS Parts:**\n - **form-control** - The form control that wraps the label, input, and help text.\n- **form-control-label** - The label's wrapper.\n- **form-control-input** - The combobox's wrapper.\n- **form-control-help-text** - The help text's wrapper.\n- **combobox** - The container that wraps the prefix, suffix, input, tags, clear icon, and expand button.\n- **prefix** - The container that wraps the prefix slot.\n- **suffix** - The container that wraps the suffix slot.\n- **display-input** - The component's `<input>` element.\n- **listbox** - The listbox container where options are slotted.\n- **no-options** - The container shown when no options match the current filter.\n- **loading** - The container shown while `loading` is set.\n- **tags** - The container that houses option tags when `multiple` is used.\n- **tag** - The individual tags that represent each selected option.\n- **tag__base** - The tag's base part.\n- **tag__content** - The tag's content part.\n- **tag__remove-button** - The tag's remove button.\n- **tag__remove-button__base** - The tag's remove button base part.\n- **clear-button** - The clear button.\n- **expand-icon** - The container that wraps the expand icon.",
+          "doc-url": "",
+          "attributes": [
+            {
+              "name": "name",
+              "description": "The name of the combobox, submitted as a name/value pair with form data.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "value",
+              "description": "The default value of the form control. Primarily used for resetting the form control.",
+              "value": { "type": "string | string[]", "default": "''" }
+            },
+            {
+              "name": "size",
+              "description": "The combobox's size.",
+              "value": {
+                "type": "'small' | 'medium' | 'large'",
+                "default": "'medium'"
+              }
+            },
+            {
+              "name": "placeholder",
+              "description": "Placeholder text to show as a hint when the combobox is empty.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "multiple",
+              "description": "Allows more than one option to be selected.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "max-options-visible",
+              "description": "The maximum number of selected options to show when `multiple` is true. After the maximum, \"+n\" will be shown to\nindicate the number of additional items that are selected. Set to 0 to remove the limit.",
+              "value": { "type": "number", "default": "3" }
+            },
+            {
+              "name": "disabled",
+              "description": "Disables the combobox control.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "clearable",
+              "description": "Adds a clear button when the combobox is not empty.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "allow-custom-value",
+              "description": "When set, values typed by the user that don't match any `<cw-option>` are accepted as the control's value. Only\napplies when `multiple` is not set.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "loading",
+              "description": "Shows a loading indicator and \"no options\" message in the listbox. Useful while options are being fetched\nasynchronously in response to the `cw-input` event.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "open",
+              "description": "Indicates whether or not the listbox is open. You can toggle this attribute to show and hide the listbox, or you can\nuse the `show()` and `hide()` methods and this attribute will reflect the combobox's open state.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "hoist",
+              "description": "Enable this option to prevent the listbox from being clipped when the component is placed inside a container with\n`overflow: auto|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "filled",
+              "description": "Draws a filled combobox.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "pill",
+              "description": "Draws a pill-style combobox with rounded edges.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "label",
+              "description": "The combobox's label. If you need to display HTML, use the `label` slot instead.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "placement",
+              "description": "The preferred placement of the combobox's listbox. Note that the actual placement may vary as needed to keep the\nlistbox inside of the viewport.",
+              "value": { "type": "'top' | 'bottom'", "default": "'bottom'" }
+            },
+            {
+              "name": "help-text",
+              "description": "The combobox's help text. If you need to display HTML, use the `help-text` slot instead.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "form",
+              "description": "By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you\nto place the form control outside of a form and associate it with the form that has this `id`. The form must be in\nthe same document or shadow root for this to work.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "required",
+              "description": "The combobox's required attribute.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "getTag",
+              "description": "A function that customizes the tags to be rendered when multiple=true. The first argument is the option, the second\nis the current tag's index. The function should return either a Lit TemplateResult or a string containing trusted\nHTML of the symbol to render at the specified value.",
+              "value": {
+                "type": "(option: CwOption, index: number) => TemplateResult | string | HTMLElement"
+              }
+            }
+          ],
+          "slots": [
+            {
+              "name": "",
+              "description": "The listbox options. Must be `<cw-option>` elements. You can use `<cw-divider>` to group items visually."
+            },
+            {
+              "name": "label",
+              "description": "The input's label. Alternatively, you can use the `label` attribute."
+            },
+            {
+              "name": "prefix",
+              "description": "Used to prepend a presentational icon or similar element to the combobox."
+            },
+            {
+              "name": "suffix",
+              "description": "Used to append a presentational icon or similar element to the combobox."
+            },
+            {
+              "name": "clear-icon",
+              "description": "An icon to use in lieu of the default clear icon."
+            },
+            {
+              "name": "expand-icon",
+              "description": "The icon to show when the control is expanded and collapsed. Rotates on open and close."
+            },
+            {
+              "name": "no-options",
+              "description": "Content to show in the listbox when no options match the current filter."
+            },
+            {
+              "name": "help-text",
+              "description": "Text that describes how to use the input. Alternatively, you can use the `help-text` attribute."
+            }
+          ],
+          "events": [
+            {
+              "name": "cw-change",
+              "description": "Emitted when the control's value changes."
+            },
+            {
+              "name": "cw-clear",
+              "description": "Emitted when the control's value is cleared."
+            },
+            {
+              "name": "cw-input",
+              "description": "Emitted when the control receives input, including as the user types to filter options."
+            },
+            {
+              "name": "cw-focus",
+              "description": "Emitted when the control gains focus."
+            },
+            {
+              "name": "cw-blur",
+              "description": "Emitted when the control loses focus."
+            },
+            {
+              "name": "cw-show",
+              "description": "Emitted when the combobox's listbox opens."
+            },
+            {
+              "name": "cw-after-show",
+              "description": "Emitted after the combobox's listbox opens and all animations are complete."
+            },
+            {
+              "name": "cw-hide",
+              "description": "Emitted when the combobox's listbox closes."
+            },
+            {
+              "name": "cw-after-hide",
+              "description": "Emitted after the combobox's listbox closes and all animations are complete."
+            },
+            {
+              "name": "cw-invalid",
+              "description": "Emitted when the form control has been checked for validity and its constraints aren't satisfied."
+            }
+          ],
+          "js": {
+            "properties": [
+              { "name": "popup", "type": "CwPopup" },
+              { "name": "combobox", "type": "HTMLSlotElement" },
+              { "name": "displayInput", "type": "HTMLInputElement" },
+              { "name": "valueInput", "type": "HTMLInputElement" },
+              { "name": "listbox", "type": "HTMLSlotElement" },
+              { "name": "displayLabel", "type": "string" },
+              { "name": "currentOption", "type": "CwOption | undefined" },
+              { "name": "selectedOptions", "type": "CwOption[]" },
+              {
+                "name": "name",
+                "description": "The name of the combobox, submitted as a name/value pair with form data.",
+                "type": "string"
+              },
+              {
+                "name": "value",
+                "description": "The current value of the combobox, submitted as a name/value pair with form data. When `multiple` is enabled, the\nvalue attribute will be a space-delimited list of values based on the options selected, and the value property will\nbe an array. **For this reason, values must not contain spaces.**"
+              },
+              {
+                "name": "defaultValue",
+                "description": "The default value of the form control. Primarily used for resetting the form control.",
+                "type": "string | string[]"
+              },
+              {
+                "name": "size",
+                "description": "The combobox's size.",
+                "type": "'small' | 'medium' | 'large'"
+              },
+              {
+                "name": "placeholder",
+                "description": "Placeholder text to show as a hint when the combobox is empty.",
+                "type": "string"
+              },
+              {
+                "name": "multiple",
+                "description": "Allows more than one option to be selected.",
+                "type": "boolean"
+              },
+              {
+                "name": "maxOptionsVisible",
+                "description": "The maximum number of selected options to show when `multiple` is true. After the maximum, \"+n\" will be shown to\nindicate the number of additional items that are selected. Set to 0 to remove the limit.",
+                "type": "number"
+              },
+              {
+                "name": "disabled",
+                "description": "Disables the combobox control.",
+                "type": "boolean"
+              },
+              {
+                "name": "clearable",
+                "description": "Adds a clear button when the combobox is not empty.",
+                "type": "boolean"
+              },
+              {
+                "name": "allowCustomValue",
+                "description": "When set, values typed by the user that don't match any `<cw-option>` are accepted as the control's value. Only\napplies when `multiple` is not set.",
+                "type": "boolean"
+              },
+              {
+                "name": "loading",
+                "description": "Shows a loading indicator and \"no options\" message in the listbox. Useful while options are being fetched\nasynchronously in response to the `cw-input` event.",
+                "type": "boolean"
+              },
+              {
+                "name": "open",
+                "description": "Indicates whether or not the listbox is open. You can toggle this attribute to show and hide the listbox, or you can\nuse the `show()` and `hide()` methods and this attribute will reflect the combobox's open state.",
+                "type": "boolean"
+              },
+              {
+                "name": "hoist",
+                "description": "Enable this option to prevent the listbox from being clipped when the component is placed inside a container with\n`overflow: auto|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.",
+                "type": "boolean"
+              },
+              {
+                "name": "filled",
+                "description": "Draws a filled combobox.",
+                "type": "boolean"
+              },
+              {
+                "name": "pill",
+                "description": "Draws a pill-style combobox with rounded edges.",
+                "type": "boolean"
+              },
+              {
+                "name": "label",
+                "description": "The combobox's label. If you need to display HTML, use the `label` slot instead.",
+                "type": "string"
+              },
+              {
+                "name": "placement",
+                "description": "The preferred placement of the combobox's listbox. Note that the actual placement may vary as needed to keep the\nlistbox inside of the viewport.",
+                "type": "'top' | 'bottom'"
+              },
+              {
+                "name": "helpText",
+                "description": "The combobox's help text. If you need to display HTML, use the `help-text` slot instead.",
+                "type": "string"
+              },
+              {
+                "name": "form",
+                "description": "By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you\nto place the form control outside of a form and associate it with the form that has this `id`. The form must be in\nthe same document or shadow root for this to work.",
+                "type": "string"
+              },
+              {
+                "name": "required",
+                "description": "The combobox's required attribute.",
+                "type": "boolean"
+              },
+              {
+                "name": "getTag",
+                "description": "A function that customizes the tags to be rendered when multiple=true. The first argument is the option, the second\nis the current tag's index. The function should return either a Lit TemplateResult or a string containing trusted\nHTML of the symbol to render at the specified value.",
+                "type": "(option: CwOption, index: number) => TemplateResult | string | HTMLElement"
+              },
+              {
+                "name": "validity",
+                "description": "Gets the validity state object"
+              },
+              {
+                "name": "validationMessage",
+                "description": "Gets the validation message"
+              }
+            ],
+            "events": [
+              {
+                "name": "cw-change",
+                "description": "Emitted when the control's value changes."
+              },
+              {
+                "name": "cw-clear",
+                "description": "Emitted when the control's value is cleared."
+              },
+              {
+                "name": "cw-input",
+                "description": "Emitted when the control receives input, including as the user types to filter options."
+              },
+              {
+                "name": "cw-focus",
+                "description": "Emitted when the control gains focus."
+              },
+              {
+                "name": "cw-blur",
+                "description": "Emitted when the control loses focus."
+              },
+              {
+                "name": "cw-show",
+                "description": "Emitted when the combobox's listbox opens."
+              },
+              {
+                "name": "cw-after-show",
+                "description": "Emitted after the combobox's listbox opens and all animations are complete."
+              },
+              {
+                "name": "cw-hide",
+                "description": "Emitted when the combobox's listbox closes."
+              },
+              {
+                "name": "cw-after-hide",
+                "description": "Emitted after the combobox's listbox closes and all animations are complete."
+              },
+              {
+                "name": "cw-invalid",
+                "description": "Emitted when the form control has been checked for validity and its constraints aren't satisfied."
+              }
+            ]
+          }
+        },
         {
           "name": "cw-copy-button",
           "description": "Copies text data to the clipboard when the user clicks the trigger.\n---\n\n\n### **Events:**\n - **cw-copy** - Emitted when the data has been copied.\n- **cw-error** - Emitted when the data could not be copied.\n\n### **Slots:**\n - **copy-icon** - The icon to show in the default copy state. Works best with `<cw-icon>`.\n- **success-icon** - The icon to show when the content is copied. Works best with `<cw-icon>`.\n- **error-icon** - The icon to show when a copy error occurs. Works best with `<cw-icon>`.\n\n### **CSS Properties:**\n - **--success-color** - The color to use for success feedback. _(default: undefined)_\n- **--error-color** - The color to use for error feedback. _(default: undefined)_\n\n### **CSS Parts:**\n - **button** - The internal `<button>` element.\n- **copy-icon** - The container that holds the copy icon.\n- **success-icon** - The container that holds the success icon.\n- **error-icon** - The container that holds the error icon.\n- **tooltip__base** - The tooltip's exported `base` part.\n- **tooltip__base__popup** - The tooltip's exported `popup` part.\n- **tooltip__base__arrow** - The tooltip's exported `arrow` part.\n- **tooltip__body** - The tooltip's exported `body` part.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cordwainer/cw-elements",
   "description": "Cordwainer Elements — Web Component Library, a hard fork of Shoelace (@shoelace-style/shoelace).",
-  "version": "1.0.2",
+  "version": "1.1.0-alpha.1",
   "homepage": "https://cw-elements-b0c7e5.gitlab.io",
   "author": "Matt Hand",
   "license": "MIT",