@warp-ds/elements 2.10.0-next.2 → 2.10.0-next.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/dist/custom-elements.json +149 -69
  2. package/dist/docs/combobox/accessibility.md +71 -0
  3. package/dist/docs/combobox/api.md +60 -30
  4. package/dist/docs/combobox/combobox.md +203 -30
  5. package/dist/docs/combobox/examples.md +44 -0
  6. package/dist/docs/combobox/usage.md +28 -0
  7. package/dist/docs/icon/accessibility.md +5 -0
  8. package/dist/docs/icon/api.md +37 -0
  9. package/dist/docs/icon/examples.md +45 -0
  10. package/dist/docs/icon/icon.md +107 -0
  11. package/dist/docs/icon/usage.md +11 -0
  12. package/dist/docs/link/api.md +18 -22
  13. package/dist/docs/link/examples.md +75 -0
  14. package/dist/docs/link/link.md +111 -22
  15. package/dist/docs/link/usage.md +18 -0
  16. package/dist/index.d.ts +443 -171
  17. package/dist/packages/affix/affix.js +3 -3
  18. package/dist/packages/affix/affix.js.map +3 -3
  19. package/dist/packages/alert/alert.js +1 -1
  20. package/dist/packages/alert/alert.js.map +3 -3
  21. package/dist/packages/attention/attention.js.map +3 -3
  22. package/dist/packages/button/button.js.map +2 -2
  23. package/dist/packages/checkbox/checkbox.d.ts +40 -11
  24. package/dist/packages/checkbox/checkbox.js.map +2 -2
  25. package/dist/packages/checkbox-group/checkbox-group.d.ts +30 -5
  26. package/dist/packages/checkbox-group/checkbox-group.js.map +2 -2
  27. package/dist/packages/combobox/combobox.a11y.test.js +24 -0
  28. package/dist/packages/combobox/combobox.d.ts +65 -45
  29. package/dist/packages/combobox/combobox.hydration.test.js +39 -1
  30. package/dist/packages/combobox/combobox.js +13 -13
  31. package/dist/packages/combobox/combobox.js.map +3 -3
  32. package/dist/packages/combobox/combobox.stories.js +28 -15
  33. package/dist/packages/combobox/combobox.test.js +110 -0
  34. package/dist/packages/datepicker/datepicker.js.map +3 -3
  35. package/dist/packages/expandable/expandable.js +2 -2
  36. package/dist/packages/expandable/expandable.js.map +3 -3
  37. package/dist/packages/icon/icon.d.ts +13 -3
  38. package/dist/packages/icon/icon.js +2 -2
  39. package/dist/packages/icon/icon.js.map +3 -3
  40. package/dist/packages/icon/icon.react.stories.d.ts +1 -1
  41. package/dist/packages/icon/react.d.ts +2 -2
  42. package/dist/packages/link/link.d.ts +15 -16
  43. package/dist/packages/link/link.js.map +2 -2
  44. package/dist/packages/modal/modal.d.ts +1 -0
  45. package/dist/packages/modal/modal.js +4 -4
  46. package/dist/packages/modal/modal.js.map +2 -2
  47. package/dist/packages/modal-header/modal-header.js +1 -1
  48. package/dist/packages/modal-header/modal-header.js.map +3 -3
  49. package/dist/packages/pagination/pagination.js.map +3 -3
  50. package/dist/packages/pill/pill.js.map +3 -3
  51. package/dist/packages/select/select.js.map +3 -3
  52. package/dist/packages/step/step.js +1 -1
  53. package/dist/packages/step/step.js.map +3 -3
  54. package/dist/packages/toast/toast.js +3 -3
  55. package/dist/packages/toast/toast.js.map +3 -3
  56. package/dist/packages/toast/toast.stories.d.ts +1 -5
  57. package/dist/packages/toast/toast.stories.js +0 -17
  58. package/dist/web-types.json +129 -72
  59. package/package.json +1 -1
package/dist/packages/toast/toast.stories.d.ts CHANGED
@@ -1,13 +1,9 @@
1
1
  import type { Meta, StoryObj } from '@storybook/web-components-vite';
2
- import type { WarpToastContainer } from '../toast-container/toast-container.js';
3
2
  import '../button/button.js';
4
3
  import './toast.js';
5
4
  import '../toast-container/toast-container.js';
6
- declare const containerArgs: Partial<WarpToastContainer> & {
7
- [key: string]: any;
8
- };
9
5
  declare const meta: Meta;
10
6
  export default meta;
11
7
  export declare const Default: StoryObj;
12
- export declare const ToastContainer: StoryObj<typeof containerArgs>;
8
+ export declare const ToastContainer: StoryObj;
13
9
  export declare const Toast: StoryObj;
package/dist/packages/toast/toast.stories.js CHANGED
@@ -1,12 +1,9 @@
1
1
  import { spread } from '@open-wc/lit-helpers';
2
- import { getStorybookHelpers } from '@wc-toolkit/storybook-helpers';
3
2
  import { html } from 'lit';
4
3
  import { prespread } from '../../.storybook/utilities.js';
5
4
  import '../button/button.js';
6
5
  import './toast.js';
7
6
  import '../toast-container/toast-container.js';
8
- const { events, args, argTypes } = getStorybookHelpers('w-pill');
9
- const { events: containerEvents, args: containerArgs, argTypes: containerArgTypes, } = getStorybookHelpers('w-toast-container');
10
7
  const meta = {
11
8
  title: 'Overlays/Toast',
12
9
  };
@@ -22,30 +19,16 @@ export const Default = {
22
19
  },
23
20
  };
24
21
  export const ToastContainer = {
25
- args: containerArgs,
26
22
  render(args) {
27
23
  return html ` <p>This is here to document attributes. See the Default example for a complete usage example.</p>
28
24
  <w-toast-container ${spread(prespread(args))}></w-toast-container>`;
29
25
  },
30
- argTypes: containerArgTypes,
31
- parameters: {
32
- actions: {
33
- handles: containerEvents,
34
- },
35
- },
36
26
  };
37
27
  export const Toast = {
38
- args,
39
28
  render(args) {
40
29
  return html `
41
30
  <p>This is here to document attributes. See the Default example for a complete usage example.</p>
42
31
  <w-toast ${spread(prespread(args))}></w-toast>
43
32
  `;
44
33
  },
45
- argTypes,
46
- parameters: {
47
- actions: {
48
- handles: events,
49
- },
50
- },
51
34
  };
package/dist/web-types.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
3
3
  "name": "@warp-ds/elements",
4
- "version": "2.10.0-next.1",
4
+ "version": "2.10.0-next.3",
5
5
  "description-markup": "markdown",
6
6
  "contributions": {
7
7
  "html": {
@@ -18,12 +18,15 @@
18
18
  },
19
19
  {
20
20
  "name": "size",
21
- "description": "Size: small, medium, large or pixel value (e.g. \"32px\")",
22
- "value": { "type": "'small' | 'medium' | 'large' | string" }
21
+ "description": "Size: small, medium, large or pixel value (e.g. \"32px\").",
22
+ "value": {
23
+ "type": "'small' | 'medium' | 'large' | string",
24
+ "default": "\"medium\""
25
+ }
23
26
  },
24
27
  {
25
28
  "name": "locale",
26
- "description": "Locale used in CDN URL",
29
+ "description": "Locale used for `<title>` text.\n\nReads the `lang` attribute from `<html>`, falls back to 'en'.",
27
30
  "value": { "type": "string" }
28
31
  }
29
32
  ],
@@ -37,12 +40,12 @@
37
40
  },
38
41
  {
39
42
  "name": "size",
40
- "description": "Size: small, medium, large or pixel value (e.g. \"32px\")",
43
+ "description": "Size: small, medium, large or pixel value (e.g. \"32px\").",
41
44
  "type": "'small' | 'medium' | 'large' | string"
42
45
  },
43
46
  {
44
47
  "name": "locale",
45
- "description": "Locale used in CDN URL",
48
+ "description": "Locale used for `<title>` text.\n\nReads the `lang` attribute from `<html>`, falls back to 'en'.",
46
49
  "type": "string"
47
50
  }
48
51
  ],
@@ -353,44 +356,90 @@
353
356
  "attributes": [
354
357
  {
355
358
  "name": "autofocus",
359
+ "description": "Focus the link after it is rendered",
356
360
  "value": { "type": "boolean", "default": "false" }
357
361
  },
358
362
  {
359
363
  "name": "variant",
364
+ "description": "Visual style for the link/button.",
360
365
  "value": {
361
366
  "type": "'negative' | 'primary' | 'secondary' | 'negativeQuiet' | 'utility' | 'quiet' | 'utilityQuiet' | 'overlay' | 'overlayInverted' | 'overlayQuiet' | 'overlayInvertedQuiet'"
362
367
  }
363
368
  },
364
369
  {
365
370
  "name": "small",
371
+ "description": "Render a smaller version",
366
372
  "value": { "type": "boolean", "default": "false" }
367
373
  },
368
- { "name": "href", "value": { "type": "string" } },
374
+ {
375
+ "name": "href",
376
+ "description": "The URL the link points to",
377
+ "value": { "type": "string" }
378
+ },
369
379
  {
370
380
  "name": "disabled",
381
+ "description": "Applies disabled styling, but you need to disable clicks on your own.\n\nThe component renders an `<a>` element; `disabled` affects styling, but does not inherently prevent navigation. If you need to fully disable interaction, omit `href` and/or prevent default click behavior.",
371
382
  "value": { "type": "boolean", "default": "false" }
372
383
  },
373
- { "name": "target", "value": { "type": "string" } },
374
- { "name": "rel", "value": { "type": "string" } },
384
+ {
385
+ "name": "target",
386
+ "description": "Where to display the linked URL (e.g. `_blank`)",
387
+ "value": { "type": "string" }
388
+ },
389
+ {
390
+ "name": "rel",
391
+ "description": "Relationship of the linked URL.\n\nIf `target=\"_blank\"` and `rel` is not provided, the component uses `noopener`.",
392
+ "value": { "type": "string" }
393
+ },
375
394
  {
376
395
  "name": "full-width",
396
+ "description": "Makes the link take up the full width of its parent",
377
397
  "value": { "type": "boolean", "default": "false" }
378
398
  }
379
399
  ],
380
400
  "events": [],
381
401
  "js": {
382
402
  "properties": [
383
- { "name": "autofocus", "type": "boolean" },
403
+ {
404
+ "name": "autofocus",
405
+ "description": "Focus the link after it is rendered",
406
+ "type": "boolean"
407
+ },
384
408
  {
385
409
  "name": "variant",
410
+ "description": "Visual style for the link/button.",
386
411
  "type": "'negative' | 'primary' | 'secondary' | 'negativeQuiet' | 'utility' | 'quiet' | 'utilityQuiet' | 'overlay' | 'overlayInverted' | 'overlayQuiet' | 'overlayInvertedQuiet'"
387
412
  },
388
- { "name": "small", "type": "boolean" },
389
- { "name": "href", "type": "string" },
390
- { "name": "disabled", "type": "boolean" },
391
- { "name": "target", "type": "string" },
392
- { "name": "rel", "type": "string" },
393
- { "name": "fullWidth", "type": "boolean" }
413
+ {
414
+ "name": "small",
415
+ "description": "Render a smaller version",
416
+ "type": "boolean"
417
+ },
418
+ {
419
+ "name": "href",
420
+ "description": "The URL the link points to",
421
+ "type": "string"
422
+ },
423
+ {
424
+ "name": "disabled",
425
+ "description": "Applies disabled styling, but you need to disable clicks on your own.\n\nThe component renders an `<a>` element; `disabled` affects styling, but does not inherently prevent navigation. If you need to fully disable interaction, omit `href` and/or prevent default click behavior.",
426
+ "type": "boolean"
427
+ },
428
+ {
429
+ "name": "target",
430
+ "description": "Where to display the linked URL (e.g. `_blank`)",
431
+ "type": "string"
432
+ },
433
+ {
434
+ "name": "rel",
435
+ "description": "Relationship of the linked URL.\n\nIf `target=\"_blank\"` and `rel` is not provided, the component uses `noopener`.",
436
+ "type": "string"
437
+ },
438
+ {
439
+ "name": "fullWidth",
440
+ "description": "Makes the link take up the full width of its parent",
441
+ "type": "boolean"
442
+ }
394
443
  ],
395
444
  "events": []
396
445
  }
@@ -902,37 +951,37 @@
902
951
  "attributes": [
903
952
  {
904
953
  "name": "name",
905
- "description": "The name of the checkbox, submitted as a name/value pair with form data.",
954
+ "description": "The name of the checkbox.\n\nWhen the checkbox is checked and belongs to a form, this name is submitted with the checkbox value. If the checkbox is inside a `w-checkbox-group` with a name, the group name is used when the checkbox does not have its own name.",
906
955
  "value": { "type": "string | undefined" }
907
956
  },
908
957
  {
909
958
  "name": "value",
910
- "description": "The value of the checkbox, submitted as a name/value pair with form data.",
959
+ "description": "The value submitted when the checkbox is checked.\n\nIf no value attribute is set, the checkbox defaults to `on`. Unchecked and disabled checkboxes do not submit a value.",
911
960
  "value": { "type": "string | null", "default": "null" }
912
961
  },
913
962
  {
914
963
  "name": "indeterminate",
915
- "description": "Draws the checkbox in an indeterminate state.",
964
+ "description": "Whether the checkbox is visually indeterminate.\n\nUse this for parent options that represent a mixed set of child selections. Clicking the checkbox clears the indeterminate state and sets the checkbox to checked.",
916
965
  "value": { "type": "boolean", "default": "false" }
917
966
  },
918
967
  {
919
968
  "name": "checked",
920
- "description": "Draws the checkbox in a checked state (reflected to attribute).",
969
+ "description": "Whether the checkbox is checked.\n\nChecked checkboxes submit their value with form data. The property is reflected to the `checked` attribute.",
921
970
  "value": { "type": "boolean", "default": "false" }
922
971
  },
923
972
  {
924
973
  "name": "disabled",
925
- "description": "Disables the checkbox.",
974
+ "description": "Whether the checkbox is disabled.\n\nDisabled checkboxes cannot be focused, changed, or submitted with form data.",
926
975
  "value": { "type": "boolean", "default": "false" }
927
976
  },
928
977
  {
929
978
  "name": "required",
930
- "description": "Makes the checkbox a required field.",
979
+ "description": "Whether the checkbox must be checked before form submission.\n\nA required checkbox is invalid until it is checked. For requiring at least one option in a set, use `required` on `w-checkbox-group`.",
931
980
  "value": { "type": "boolean", "default": "false" }
932
981
  },
933
982
  {
934
983
  "name": "invalid",
935
- "description": "Draws the checkbox in an invalid state.",
984
+ "description": "Whether the checkbox is visually invalid.\n\nUse this to show an externally managed validation error. Required validation also sets the invalid state after the user interacts with the checkbox or tries to submit the form.",
936
985
  "value": { "type": "boolean", "default": "false" }
937
986
  }
938
987
  ],
@@ -942,37 +991,37 @@
942
991
  { "name": "input", "type": "HTMLInputElement | null" },
943
992
  {
944
993
  "name": "name",
945
- "description": "The name of the checkbox, submitted as a name/value pair with form data.",
994
+ "description": "The name of the checkbox.\n\nWhen the checkbox is checked and belongs to a form, this name is submitted with the checkbox value. If the checkbox is inside a `w-checkbox-group` with a name, the group name is used when the checkbox does not have its own name.",
946
995
  "type": "string | undefined"
947
996
  },
948
997
  {
949
998
  "name": "value",
950
- "description": "The value of the checkbox, submitted as a name/value pair with form data.",
999
+ "description": "The value submitted when the checkbox is checked.\n\nIf no value attribute is set, the checkbox defaults to `on`. Unchecked and disabled checkboxes do not submit a value.",
951
1000
  "type": "string | null"
952
1001
  },
953
1002
  {
954
1003
  "name": "indeterminate",
955
- "description": "Draws the checkbox in an indeterminate state.",
1004
+ "description": "Whether the checkbox is visually indeterminate.\n\nUse this for parent options that represent a mixed set of child selections. Clicking the checkbox clears the indeterminate state and sets the checkbox to checked.",
956
1005
  "type": "boolean"
957
1006
  },
958
1007
  {
959
1008
  "name": "checked",
960
- "description": "Draws the checkbox in a checked state (reflected to attribute).",
1009
+ "description": "Whether the checkbox is checked.\n\nChecked checkboxes submit their value with form data. The property is reflected to the `checked` attribute.",
961
1010
  "type": "boolean"
962
1011
  },
963
1012
  {
964
1013
  "name": "disabled",
965
- "description": "Disables the checkbox.",
1014
+ "description": "Whether the checkbox is disabled.\n\nDisabled checkboxes cannot be focused, changed, or submitted with form data.",
966
1015
  "type": "boolean"
967
1016
  },
968
1017
  {
969
1018
  "name": "required",
970
- "description": "Makes the checkbox a required field.",
1019
+ "description": "Whether the checkbox must be checked before form submission.\n\nA required checkbox is invalid until it is checked. For requiring at least one option in a set, use `required` on `w-checkbox-group`.",
971
1020
  "type": "boolean"
972
1021
  },
973
1022
  {
974
1023
  "name": "invalid",
975
- "description": "Draws the checkbox in an invalid state.",
1024
+ "description": "Whether the checkbox is visually invalid.\n\nUse this to show an externally managed validation error. Required validation also sets the invalid state after the user interacts with the checkbox or tries to submit the form.",
976
1025
  "type": "boolean"
977
1026
  },
978
1027
  {
@@ -1001,28 +1050,32 @@
1001
1050
  "attributes": [
1002
1051
  {
1003
1052
  "name": "label",
1004
- "description": "The group label displayed above the checkboxes.",
1053
+ "description": "The group label displayed above the checkboxes.\n\nUse this to describe the shared question or topic for the checkbox options. The label is connected to the internal group for assistive technologies.",
1005
1054
  "value": { "type": "string" }
1006
1055
  },
1007
1056
  {
1008
1057
  "name": "name",
1009
- "description": "The name applied to child checkboxes when they do not provide one.",
1058
+ "description": "The name applied to child checkboxes when they do not provide one.\n\nUse this when the grouped checkboxes should submit values under the same form field name. Individual checkboxes can still override the group name with their own `name`.",
1010
1059
  "value": { "type": "string" }
1011
1060
  },
1012
1061
  {
1013
1062
  "name": "optional",
1014
- "description": "Whether to show optional text next to the label.",
1063
+ "description": "Whether to show optional text next to the label.\n\nUse this to indicate that selecting an option from the group is not required.",
1015
1064
  "value": { "type": "boolean", "default": "false" }
1016
1065
  },
1017
- { "name": "help-text", "value": { "type": "string" } },
1066
+ {
1067
+ "name": "help-text",
1068
+ "description": "Help text displayed below the checkbox group.\n\nUse this for supporting guidance or validation feedback. When required validation fails, the group replaces this text with the localized required message.",
1069
+ "value": { "type": "string" }
1070
+ },
1018
1071
  {
1019
1072
  "name": "required",
1020
- "description": "Makes the checkbox group required.",
1073
+ "description": "Whether at least one checkbox in the group must be selected.\n\nRequired validation is managed by the group. The individual checkboxes provide the submitted form values.",
1021
1074
  "value": { "type": "boolean", "default": "false" }
1022
1075
  },
1023
1076
  {
1024
1077
  "name": "invalid",
1025
- "description": "Marks the checkbox group as invalid.",
1078
+ "description": "Whether the checkbox group is visually invalid.\n\nUse this to show an externally managed validation error for the group. The invalid state is also shared with child checkboxes for consistent styling and accessibility state.",
1026
1079
  "value": { "type": "boolean", "default": "false" }
1027
1080
  }
1028
1081
  ],
@@ -1031,28 +1084,32 @@
1031
1084
  "properties": [
1032
1085
  {
1033
1086
  "name": "label",
1034
- "description": "The group label displayed above the checkboxes.",
1087
+ "description": "The group label displayed above the checkboxes.\n\nUse this to describe the shared question or topic for the checkbox options. The label is connected to the internal group for assistive technologies.",
1035
1088
  "type": "string"
1036
1089
  },
1037
1090
  {
1038
1091
  "name": "name",
1039
- "description": "The name applied to child checkboxes when they do not provide one.",
1092
+ "description": "The name applied to child checkboxes when they do not provide one.\n\nUse this when the grouped checkboxes should submit values under the same form field name. Individual checkboxes can still override the group name with their own `name`.",
1040
1093
  "type": "string"
1041
1094
  },
1042
1095
  {
1043
1096
  "name": "optional",
1044
- "description": "Whether to show optional text next to the label.",
1097
+ "description": "Whether to show optional text next to the label.\n\nUse this to indicate that selecting an option from the group is not required.",
1045
1098
  "type": "boolean"
1046
1099
  },
1047
- { "name": "helpText", "type": "string" },
1100
+ {
1101
+ "name": "helpText",
1102
+ "description": "Help text displayed below the checkbox group.\n\nUse this for supporting guidance or validation feedback. When required validation fails, the group replaces this text with the localized required message.",
1103
+ "type": "string"
1104
+ },
1048
1105
  {
1049
1106
  "name": "required",
1050
- "description": "Makes the checkbox group required.",
1107
+ "description": "Whether at least one checkbox in the group must be selected.\n\nRequired validation is managed by the group. The individual checkboxes provide the submitted form values.",
1051
1108
  "type": "boolean"
1052
1109
  },
1053
1110
  {
1054
1111
  "name": "invalid",
1055
- "description": "Marks the checkbox group as invalid.",
1112
+ "description": "Whether the checkbox group is visually invalid.\n\nUse this to show an externally managed validation error for the group. The invalid state is also shared with child checkboxes for consistent styling and accessibility state.",
1056
1113
  "type": "boolean"
1057
1114
  }
1058
1115
  ],
@@ -1066,77 +1123,77 @@
1066
1123
  "attributes": [
1067
1124
  {
1068
1125
  "name": "options",
1069
- "description": "The available options to select from",
1126
+ "description": "The available options to select from.\n\nUse this for framework usage, application state, or remote search results. When `options` contains entries, it is used instead of child `<option>` elements.",
1070
1127
  "value": { "type": "ComboboxOption[]", "default": "[]" }
1071
1128
  },
1072
1129
  {
1073
1130
  "name": "label",
1074
- "description": "Label above input",
1131
+ "description": "The label displayed above the input.\n\nUse this to give the combobox a visible and accessible name.",
1075
1132
  "value": { "type": "string | undefined", "default": "''" }
1076
1133
  },
1077
1134
  {
1078
1135
  "name": "placeholder",
1079
- "description": "Input placeholder",
1136
+ "description": "Placeholder text displayed when the input is empty.\n\nUse this as a short hint for the expected input. Do not use placeholder text as a replacement for a label.",
1080
1137
  "value": { "type": "string | undefined", "default": "''" }
1081
1138
  },
1082
1139
  {
1083
1140
  "name": "value",
1084
- "description": "The input value",
1141
+ "description": "The selected or typed value.\n\nWhen an option is selected, this is set to the option value. The displayed text may differ when the option has a separate label.",
1085
1142
  "value": { "type": "string", "default": "''" }
1086
1143
  },
1087
1144
  {
1088
1145
  "name": "open-on-focus",
1089
- "description": "Whether the popover opens when focus is on the text field",
1146
+ "description": "Whether the option list opens when the input receives focus.\n\nUse this when users should see available options before they start typing.",
1090
1147
  "value": { "type": "boolean", "default": "false" }
1091
1148
  },
1092
1149
  {
1093
1150
  "name": "select-on-blur",
1094
- "description": "Select active option on blur",
1151
+ "description": "Whether the active option is selected when the input loses focus.\n\nWhen enabled, the combobox selects the keyboard-highlighted option, or an option whose value exactly matches the current input value, on blur.",
1095
1152
  "value": { "type": "boolean", "default": "true" }
1096
1153
  },
1097
1154
  {
1098
1155
  "name": "match-text-segments",
1099
- "description": "Whether the matching text segments in the options should be highlighted",
1156
+ "description": "Whether matching text segments in options are highlighted.\n\nUse this to visually emphasize the part of each option that matches the current input value.",
1100
1157
  "value": { "type": "boolean", "default": "false" }
1101
1158
  },
1102
1159
  {
1103
1160
  "name": "disable-static-filtering",
1104
- "description": "Disable client-side static filtering",
1161
+ "description": "Whether built-in client-side filtering is disabled.\n\nUse this for remote search or externally filtered results. When disabled, all entries in `options` are rendered as provided.",
1105
1162
  "value": { "type": "boolean", "default": "false" }
1106
1163
  },
1107
1164
  {
1108
1165
  "name": "invalid",
1109
- "description": "Renders the input field in an invalid state",
1166
+ "description": "Whether the combobox is visually invalid.\n\nUse this to show an externally managed validation error. Pair it with `help-text` to explain how to fix the error.",
1110
1167
  "value": { "type": "boolean", "default": "false" }
1111
1168
  },
1112
1169
  {
1113
1170
  "name": "help-text",
1114
- "description": "The content to display as the help text",
1171
+ "description": "Help text displayed below the input.\n\nUse this for supporting guidance or validation feedback.",
1115
1172
  "value": { "type": "string | undefined", "default": "''" }
1116
1173
  },
1117
1174
  {
1118
1175
  "name": "disabled",
1119
- "description": "Whether the element is disabled",
1176
+ "description": "Whether the combobox is disabled.\n\nDisabled comboboxes cannot be focused, changed, or submitted with form data.",
1120
1177
  "value": { "type": "boolean", "default": "false" }
1121
1178
  },
1122
1179
  {
1123
1180
  "name": "required",
1124
- "description": "Whether the element is required",
1181
+ "description": "Whether the combobox is required before form submission.\n\nUse this when the user must provide a value before submitting the form.",
1125
1182
  "value": { "type": "boolean", "default": "false" }
1126
1183
  },
1127
1184
  {
1128
1185
  "name": "optional",
1129
- "description": "Whether to show optional text",
1186
+ "description": "Whether to show optional text next to the label.\n\nUse this to indicate that the combobox is not required.",
1130
1187
  "value": { "type": "boolean", "default": "false" }
1131
1188
  },
1132
1189
  {
1133
1190
  "name": "name",
1134
- "description": "Name attribute for form submission",
1191
+ "description": "The name submitted with the combobox value.\n\nUse this when the combobox belongs to a form and its value should be included in form data.",
1135
1192
  "value": { "type": "string | undefined", "default": "''" }
1136
1193
  },
1137
1194
  {
1138
1195
  "name": "autocomplete",
1139
- "description": "Autocomplete attribute for the input field",
1196
+ "description": "The autocomplete attribute passed to the internal input.\n\nDefaults to `off`. Set this when browser autocomplete should be enabled or scoped to a specific autocomplete token.",
1140
1197
  "value": { "type": "string | undefined", "default": "'off'" }
1141
1198
  }
1142
1199
  ],
@@ -1145,77 +1202,77 @@
1145
1202
  "properties": [
1146
1203
  {
1147
1204
  "name": "options",
1148
- "description": "The available options to select from",
1205
+ "description": "The available options to select from.\n\nUse this for framework usage, application state, or remote search results. When `options` contains entries, it is used instead of child `<option>` elements.",
1149
1206
  "type": "ComboboxOption[]"
1150
1207
  },
1151
1208
  {
1152
1209
  "name": "label",
1153
- "description": "Label above input",
1210
+ "description": "The label displayed above the input.\n\nUse this to give the combobox a visible and accessible name.",
1154
1211
  "type": "string | undefined"
1155
1212
  },
1156
1213
  {
1157
1214
  "name": "placeholder",
1158
- "description": "Input placeholder",
1215
+ "description": "Placeholder text displayed when the input is empty.\n\nUse this as a short hint for the expected input. Do not use placeholder text as a replacement for a label.",
1159
1216
  "type": "string | undefined"
1160
1217
  },
1161
1218
  {
1162
1219
  "name": "value",
1163
- "description": "The input value",
1220
+ "description": "The selected or typed value.\n\nWhen an option is selected, this is set to the option value. The displayed text may differ when the option has a separate label.",
1164
1221
  "type": "string"
1165
1222
  },
1166
1223
  {
1167
1224
  "name": "openOnFocus",
1168
- "description": "Whether the popover opens when focus is on the text field",
1225
+ "description": "Whether the option list opens when the input receives focus.\n\nUse this when users should see available options before they start typing.",
1169
1226
  "type": "boolean"
1170
1227
  },
1171
1228
  {
1172
1229
  "name": "selectOnBlur",
1173
- "description": "Select active option on blur",
1230
+ "description": "Whether the active option is selected when the input loses focus.\n\nWhen enabled, the combobox selects the keyboard-highlighted option, or an option whose value exactly matches the current input value, on blur.",
1174
1231
  "type": "boolean"
1175
1232
  },
1176
1233
  {
1177
1234
  "name": "matchTextSegments",
1178
- "description": "Whether the matching text segments in the options should be highlighted",
1235
+ "description": "Whether matching text segments in options are highlighted.\n\nUse this to visually emphasize the part of each option that matches the current input value.",
1179
1236
  "type": "boolean"
1180
1237
  },
1181
1238
  {
1182
1239
  "name": "disableStaticFiltering",
1183
- "description": "Disable client-side static filtering",
1240
+ "description": "Whether built-in client-side filtering is disabled.\n\nUse this for remote search or externally filtered results. When disabled, all entries in `options` are rendered as provided.",
1184
1241
  "type": "boolean"
1185
1242
  },
1186
1243
  {
1187
1244
  "name": "invalid",
1188
- "description": "Renders the input field in an invalid state",
1245
+ "description": "Whether the combobox is visually invalid.\n\nUse this to show an externally managed validation error. Pair it with `help-text` to explain how to fix the error.",
1189
1246
  "type": "boolean"
1190
1247
  },
1191
1248
  {
1192
1249
  "name": "helpText",
1193
- "description": "The content to display as the help text",
1250
+ "description": "Help text displayed below the input.\n\nUse this for supporting guidance or validation feedback.",
1194
1251
  "type": "string | undefined"
1195
1252
  },
1196
1253
  {
1197
1254
  "name": "disabled",
1198
- "description": "Whether the element is disabled",
1255
+ "description": "Whether the combobox is disabled.\n\nDisabled comboboxes cannot be focused, changed, or submitted with form data.",
1199
1256
  "type": "boolean"
1200
1257
  },
1201
1258
  {
1202
1259
  "name": "required",
1203
- "description": "Whether the element is required",
1260
+ "description": "Whether the combobox is required before form submission.\n\nUse this when the user must provide a value before submitting the form.",
1204
1261
  "type": "boolean"
1205
1262
  },
1206
1263
  {
1207
1264
  "name": "optional",
1208
- "description": "Whether to show optional text",
1265
+ "description": "Whether to show optional text next to the label.\n\nUse this to indicate that the combobox is not required.",
1209
1266
  "type": "boolean"
1210
1267
  },
1211
1268
  {
1212
1269
  "name": "name",
1213
- "description": "Name attribute for form submission",
1270
+ "description": "The name submitted with the combobox value.\n\nUse this when the combobox belongs to a form and its value should be included in form data.",
1214
1271
  "type": "string | undefined"
1215
1272
  },
1216
1273
  {
1217
1274
  "name": "autocomplete",
1218
- "description": "Autocomplete attribute for the input field",
1275
+ "description": "The autocomplete attribute passed to the internal input.\n\nDefaults to `off`. Set this when browser autocomplete should be enabled or scoped to a specific autocomplete token.",
1219
1276
  "type": "string | undefined"
1220
1277
  }
1221
1278
  ],
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@warp-ds/elements",
3
3
  "type": "module",
4
- "version": "2.10.0-next.2",
4
+ "version": "2.10.0-next.4",
5
5
  "packageManager": "pnpm@11.1.0",
6
6
  "description": "Custom elements for Warp",
7
7
  "exports": {