@warp-ds/elements 2.10.0-next.1 → 2.10.0-next.3

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 (84) hide show
  1. package/dist/custom-elements.json +146 -69
  2. package/dist/docs/card/accessibility.md +74 -0
  3. package/dist/docs/card/api.md +9 -3
  4. package/dist/docs/card/card.md +234 -3
  5. package/dist/docs/card/examples.md +75 -0
  6. package/dist/docs/card/usage.md +76 -0
  7. package/dist/docs/combobox/accessibility.md +71 -0
  8. package/dist/docs/combobox/api.md +60 -30
  9. package/dist/docs/combobox/combobox.md +203 -30
  10. package/dist/docs/combobox/examples.md +44 -0
  11. package/dist/docs/combobox/usage.md +28 -0
  12. package/dist/docs/icon/accessibility.md +5 -0
  13. package/dist/docs/icon/api.md +37 -0
  14. package/dist/docs/icon/examples.md +45 -0
  15. package/dist/docs/icon/icon.md +107 -0
  16. package/dist/docs/icon/usage.md +11 -0
  17. package/dist/docs/link/api.md +18 -22
  18. package/dist/docs/link/examples.md +75 -0
  19. package/dist/docs/link/link.md +111 -22
  20. package/dist/docs/link/usage.md +18 -0
  21. package/dist/index.d.ts +479 -183
  22. package/dist/packages/affix/affix.js +3 -3
  23. package/dist/packages/affix/affix.js.map +4 -4
  24. package/dist/packages/alert/alert.js +1 -1
  25. package/dist/packages/alert/alert.js.map +3 -3
  26. package/dist/packages/attention/attention.js.map +4 -4
  27. package/dist/packages/attention/attention.test.js +1 -1
  28. package/dist/packages/breadcrumbs/breadcrumbs.js.map +1 -1
  29. package/dist/packages/button/button.js.map +3 -3
  30. package/dist/packages/card/card.d.ts +9 -6
  31. package/dist/packages/card/card.js.map +3 -3
  32. package/dist/packages/checkbox/checkbox.d.ts +40 -11
  33. package/dist/packages/checkbox/checkbox.js.map +2 -2
  34. package/dist/packages/checkbox/checkbox.test.js +1 -1
  35. package/dist/packages/checkbox-group/checkbox-group.a11y.test.js +1 -1
  36. package/dist/packages/checkbox-group/checkbox-group.d.ts +30 -5
  37. package/dist/packages/checkbox-group/checkbox-group.js.map +3 -3
  38. package/dist/packages/combobox/combobox.a11y.test.js +24 -0
  39. package/dist/packages/combobox/combobox.d.ts +65 -45
  40. package/dist/packages/combobox/combobox.hydration.test.js +39 -1
  41. package/dist/packages/combobox/combobox.js +13 -13
  42. package/dist/packages/combobox/combobox.js.map +4 -4
  43. package/dist/packages/combobox/combobox.stories.js +28 -15
  44. package/dist/packages/combobox/combobox.test.js +110 -0
  45. package/dist/packages/datepicker/DatePicker.test.js +1 -1
  46. package/dist/packages/datepicker/datepicker.js.map +4 -4
  47. package/dist/packages/datepicker/datepicker.test.js +1 -1
  48. package/dist/packages/expandable/expandable.js +2 -2
  49. package/dist/packages/expandable/expandable.js.map +3 -3
  50. package/dist/packages/icon/icon.d.ts +13 -3
  51. package/dist/packages/icon/icon.js +2 -2
  52. package/dist/packages/icon/icon.js.map +3 -3
  53. package/dist/packages/icon/icon.react.stories.d.ts +1 -1
  54. package/dist/packages/icon/react.d.ts +2 -2
  55. package/dist/packages/link/link.d.ts +15 -16
  56. package/dist/packages/link/link.js.map +2 -2
  57. package/dist/packages/link/link.test.js +1 -1
  58. package/dist/packages/modal-header/modal-header.js +3 -1
  59. package/dist/packages/modal-header/modal-header.js.map +4 -4
  60. package/dist/packages/page-indicator/page-indicator.js.map +1 -1
  61. package/dist/packages/pagination/pagination.js.map +4 -4
  62. package/dist/packages/pagination/pagination.test.js +1 -1
  63. package/dist/packages/pill/pill.js.map +4 -4
  64. package/dist/packages/radio/radio.test.js +1 -1
  65. package/dist/packages/radio-group/radio-group.a11y.test.js +1 -1
  66. package/dist/packages/radio-group/radio-group.js.map +1 -1
  67. package/dist/packages/select/select.js.map +4 -4
  68. package/dist/packages/slider/slider.js.map +1 -1
  69. package/dist/packages/slider/slider.test.js +1 -1
  70. package/dist/packages/slider-thumb/slider-thumb.js.map +1 -1
  71. package/dist/packages/step/step.js +1 -1
  72. package/dist/packages/step/step.js.map +4 -4
  73. package/dist/packages/switch/switch.a11y.test.js +1 -1
  74. package/dist/packages/tabs/tabs.a11y.test.js +1 -1
  75. package/dist/packages/tabs/tabs.test.js +1 -1
  76. package/dist/packages/textarea/textarea.js.map +1 -1
  77. package/dist/packages/textarea/textarea.test.js +1 -1
  78. package/dist/packages/textfield/textfield.test.js +1 -1
  79. package/dist/packages/toast/toast.js +3 -3
  80. package/dist/packages/toast/toast.js.map +4 -4
  81. package/dist/packages/toast/toast.stories.d.ts +1 -5
  82. package/dist/packages/toast/toast.stories.js +0 -17
  83. package/dist/web-types.json +147 -75
  84. package/package.json +2 -2
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.9.2-next.1",
4
+ "version": "2.10.0-next.2",
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
  }
@@ -858,23 +907,38 @@
858
907
  "attributes": [
859
908
  {
860
909
  "name": "selected",
910
+ "description": "Whether the card is visually selected.\n\nUse this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes.",
861
911
  "value": { "type": "boolean", "default": "false" }
862
912
  },
863
913
  {
864
914
  "name": "flat",
915
+ "description": "Whether the card uses the flat visual treatment.\n\nFlat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface.",
865
916
  "value": { "type": "boolean", "default": "false" }
866
917
  },
867
918
  {
868
919
  "name": "clickable",
920
+ "description": "Whether the whole card is interactive.\n\nWhen set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice.",
869
921
  "value": { "type": "boolean", "default": "false" }
870
922
  }
871
923
  ],
872
924
  "events": [],
873
925
  "js": {
874
926
  "properties": [
875
- { "name": "selected", "type": "boolean" },
876
- { "name": "flat", "type": "boolean" },
877
- { "name": "clickable", "type": "boolean" },
927
+ {
928
+ "name": "selected",
929
+ "description": "Whether the card is visually selected.\n\nUse this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes.",
930
+ "type": "boolean"
931
+ },
932
+ {
933
+ "name": "flat",
934
+ "description": "Whether the card uses the flat visual treatment.\n\nFlat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface.",
935
+ "type": "boolean"
936
+ },
937
+ {
938
+ "name": "clickable",
939
+ "description": "Whether the whole card is interactive.\n\nWhen set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice.",
940
+ "type": "boolean"
941
+ },
878
942
  { "name": "buttonText" }
879
943
  ],
880
944
  "events": []
@@ -887,37 +951,37 @@
887
951
  "attributes": [
888
952
  {
889
953
  "name": "name",
890
- "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.",
891
955
  "value": { "type": "string | undefined" }
892
956
  },
893
957
  {
894
958
  "name": "value",
895
- "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.",
896
960
  "value": { "type": "string | null", "default": "null" }
897
961
  },
898
962
  {
899
963
  "name": "indeterminate",
900
- "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.",
901
965
  "value": { "type": "boolean", "default": "false" }
902
966
  },
903
967
  {
904
968
  "name": "checked",
905
- "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.",
906
970
  "value": { "type": "boolean", "default": "false" }
907
971
  },
908
972
  {
909
973
  "name": "disabled",
910
- "description": "Disables the checkbox.",
974
+ "description": "Whether the checkbox is disabled.\n\nDisabled checkboxes cannot be focused, changed, or submitted with form data.",
911
975
  "value": { "type": "boolean", "default": "false" }
912
976
  },
913
977
  {
914
978
  "name": "required",
915
- "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`.",
916
980
  "value": { "type": "boolean", "default": "false" }
917
981
  },
918
982
  {
919
983
  "name": "invalid",
920
- "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.",
921
985
  "value": { "type": "boolean", "default": "false" }
922
986
  }
923
987
  ],
@@ -927,37 +991,37 @@
927
991
  { "name": "input", "type": "HTMLInputElement | null" },
928
992
  {
929
993
  "name": "name",
930
- "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.",
931
995
  "type": "string | undefined"
932
996
  },
933
997
  {
934
998
  "name": "value",
935
- "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.",
936
1000
  "type": "string | null"
937
1001
  },
938
1002
  {
939
1003
  "name": "indeterminate",
940
- "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.",
941
1005
  "type": "boolean"
942
1006
  },
943
1007
  {
944
1008
  "name": "checked",
945
- "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.",
946
1010
  "type": "boolean"
947
1011
  },
948
1012
  {
949
1013
  "name": "disabled",
950
- "description": "Disables the checkbox.",
1014
+ "description": "Whether the checkbox is disabled.\n\nDisabled checkboxes cannot be focused, changed, or submitted with form data.",
951
1015
  "type": "boolean"
952
1016
  },
953
1017
  {
954
1018
  "name": "required",
955
- "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`.",
956
1020
  "type": "boolean"
957
1021
  },
958
1022
  {
959
1023
  "name": "invalid",
960
- "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.",
961
1025
  "type": "boolean"
962
1026
  },
963
1027
  {
@@ -986,28 +1050,32 @@
986
1050
  "attributes": [
987
1051
  {
988
1052
  "name": "label",
989
- "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.",
990
1054
  "value": { "type": "string" }
991
1055
  },
992
1056
  {
993
1057
  "name": "name",
994
- "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`.",
995
1059
  "value": { "type": "string" }
996
1060
  },
997
1061
  {
998
1062
  "name": "optional",
999
- "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.",
1000
1064
  "value": { "type": "boolean", "default": "false" }
1001
1065
  },
1002
- { "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
+ },
1003
1071
  {
1004
1072
  "name": "required",
1005
- "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.",
1006
1074
  "value": { "type": "boolean", "default": "false" }
1007
1075
  },
1008
1076
  {
1009
1077
  "name": "invalid",
1010
- "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.",
1011
1079
  "value": { "type": "boolean", "default": "false" }
1012
1080
  }
1013
1081
  ],
@@ -1016,28 +1084,32 @@
1016
1084
  "properties": [
1017
1085
  {
1018
1086
  "name": "label",
1019
- "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.",
1020
1088
  "type": "string"
1021
1089
  },
1022
1090
  {
1023
1091
  "name": "name",
1024
- "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`.",
1025
1093
  "type": "string"
1026
1094
  },
1027
1095
  {
1028
1096
  "name": "optional",
1029
- "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.",
1030
1098
  "type": "boolean"
1031
1099
  },
1032
- { "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
+ },
1033
1105
  {
1034
1106
  "name": "required",
1035
- "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.",
1036
1108
  "type": "boolean"
1037
1109
  },
1038
1110
  {
1039
1111
  "name": "invalid",
1040
- "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.",
1041
1113
  "type": "boolean"
1042
1114
  }
1043
1115
  ],
@@ -1051,77 +1123,77 @@
1051
1123
  "attributes": [
1052
1124
  {
1053
1125
  "name": "options",
1054
- "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.",
1055
1127
  "value": { "type": "ComboboxOption[]", "default": "[]" }
1056
1128
  },
1057
1129
  {
1058
1130
  "name": "label",
1059
- "description": "Label above input",
1131
+ "description": "The label displayed above the input.\n\nUse this to give the combobox a visible and accessible name.",
1060
1132
  "value": { "type": "string | undefined", "default": "''" }
1061
1133
  },
1062
1134
  {
1063
1135
  "name": "placeholder",
1064
- "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.",
1065
1137
  "value": { "type": "string | undefined", "default": "''" }
1066
1138
  },
1067
1139
  {
1068
1140
  "name": "value",
1069
- "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.",
1070
1142
  "value": { "type": "string", "default": "''" }
1071
1143
  },
1072
1144
  {
1073
1145
  "name": "open-on-focus",
1074
- "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.",
1075
1147
  "value": { "type": "boolean", "default": "false" }
1076
1148
  },
1077
1149
  {
1078
1150
  "name": "select-on-blur",
1079
- "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.",
1080
1152
  "value": { "type": "boolean", "default": "true" }
1081
1153
  },
1082
1154
  {
1083
1155
  "name": "match-text-segments",
1084
- "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.",
1085
1157
  "value": { "type": "boolean", "default": "false" }
1086
1158
  },
1087
1159
  {
1088
1160
  "name": "disable-static-filtering",
1089
- "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.",
1090
1162
  "value": { "type": "boolean", "default": "false" }
1091
1163
  },
1092
1164
  {
1093
1165
  "name": "invalid",
1094
- "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.",
1095
1167
  "value": { "type": "boolean", "default": "false" }
1096
1168
  },
1097
1169
  {
1098
1170
  "name": "help-text",
1099
- "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.",
1100
1172
  "value": { "type": "string | undefined", "default": "''" }
1101
1173
  },
1102
1174
  {
1103
1175
  "name": "disabled",
1104
- "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.",
1105
1177
  "value": { "type": "boolean", "default": "false" }
1106
1178
  },
1107
1179
  {
1108
1180
  "name": "required",
1109
- "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.",
1110
1182
  "value": { "type": "boolean", "default": "false" }
1111
1183
  },
1112
1184
  {
1113
1185
  "name": "optional",
1114
- "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.",
1115
1187
  "value": { "type": "boolean", "default": "false" }
1116
1188
  },
1117
1189
  {
1118
1190
  "name": "name",
1119
- "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.",
1120
1192
  "value": { "type": "string | undefined", "default": "''" }
1121
1193
  },
1122
1194
  {
1123
1195
  "name": "autocomplete",
1124
- "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.",
1125
1197
  "value": { "type": "string | undefined", "default": "'off'" }
1126
1198
  }
1127
1199
  ],
@@ -1130,77 +1202,77 @@
1130
1202
  "properties": [
1131
1203
  {
1132
1204
  "name": "options",
1133
- "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.",
1134
1206
  "type": "ComboboxOption[]"
1135
1207
  },
1136
1208
  {
1137
1209
  "name": "label",
1138
- "description": "Label above input",
1210
+ "description": "The label displayed above the input.\n\nUse this to give the combobox a visible and accessible name.",
1139
1211
  "type": "string | undefined"
1140
1212
  },
1141
1213
  {
1142
1214
  "name": "placeholder",
1143
- "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.",
1144
1216
  "type": "string | undefined"
1145
1217
  },
1146
1218
  {
1147
1219
  "name": "value",
1148
- "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.",
1149
1221
  "type": "string"
1150
1222
  },
1151
1223
  {
1152
1224
  "name": "openOnFocus",
1153
- "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.",
1154
1226
  "type": "boolean"
1155
1227
  },
1156
1228
  {
1157
1229
  "name": "selectOnBlur",
1158
- "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.",
1159
1231
  "type": "boolean"
1160
1232
  },
1161
1233
  {
1162
1234
  "name": "matchTextSegments",
1163
- "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.",
1164
1236
  "type": "boolean"
1165
1237
  },
1166
1238
  {
1167
1239
  "name": "disableStaticFiltering",
1168
- "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.",
1169
1241
  "type": "boolean"
1170
1242
  },
1171
1243
  {
1172
1244
  "name": "invalid",
1173
- "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.",
1174
1246
  "type": "boolean"
1175
1247
  },
1176
1248
  {
1177
1249
  "name": "helpText",
1178
- "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.",
1179
1251
  "type": "string | undefined"
1180
1252
  },
1181
1253
  {
1182
1254
  "name": "disabled",
1183
- "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.",
1184
1256
  "type": "boolean"
1185
1257
  },
1186
1258
  {
1187
1259
  "name": "required",
1188
- "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.",
1189
1261
  "type": "boolean"
1190
1262
  },
1191
1263
  {
1192
1264
  "name": "optional",
1193
- "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.",
1194
1266
  "type": "boolean"
1195
1267
  },
1196
1268
  {
1197
1269
  "name": "name",
1198
- "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.",
1199
1271
  "type": "string | undefined"
1200
1272
  },
1201
1273
  {
1202
1274
  "name": "autocomplete",
1203
- "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.",
1204
1276
  "type": "string | undefined"
1205
1277
  }
1206
1278
  ],
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@warp-ds/elements",
3
3
  "type": "module",
4
- "version": "2.10.0-next.1",
5
- "packageManager": "pnpm@10.33.4",
4
+ "version": "2.10.0-next.3",
5
+ "packageManager": "pnpm@11.1.0",
6
6
  "description": "Custom elements for Warp",
7
7
  "exports": {
8
8
  ".": {