From 2569e9dcd5187c23ced864d66cbf1b3883a5760d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?A=CC=81ngel=20Rolda=CC=81n=20Marti=CC=81nez?= Date: Mon, 18 Mar 2024 13:29:42 +0100 Subject: [PATCH 1/3] fix(BFormTags) add limitTagText in the HTML add BFormTags documentation create some unit test for BFormTags --- apps/docs/src/docs/components/form-group.md | 62 +- apps/docs/src/docs/components/form-tags.md | 1368 ++++++++++++++++- apps/docs/src/docs/components/form.md | 18 +- .../src/components/BFormTags/BFormTags.vue | 8 +- .../components/BFormTags/form-tags.spec.ts | 29 + 5 files changed, 1455 insertions(+), 30 deletions(-) create mode 100644 packages/bootstrap-vue-next/src/components/BFormTags/form-tags.spec.ts diff --git a/apps/docs/src/docs/components/form-group.md b/apps/docs/src/docs/components/form-group.md index efe6222f9..78c4fc456 100644 --- a/apps/docs/src/docs/components/form-group.md +++ b/apps/docs/src/docs/components/form-group.md @@ -99,18 +99,56 @@ columns does not exceed `12`. See the [Layout and Grid System](/docs/components/layout#how-it-works) docs for further information. -| Prop | Description | -| ----------------- | --------------------------------- | -| `label-cols` | Applies to breakpoint `xs` up | -| `label-cols-sm` | Applies to breakpoint `sm` and up | -| `label-cols-md` | Applies to breakpoint `md` and up | -| `label-cols-lg` | Applies to breakpoint `lg` and up | -| `label-cols-xl` | Applies to breakpoint `xl` and up | -| `content-cols` | Applies to breakpoint `xs` up | -| `content-cols-sm` | Applies to breakpoint `sm` and up | -| `content-cols-md` | Applies to breakpoint `md` and up | -| `content-cols-lg` | Applies to breakpoint `lg` and up | -| `content-cols-xl` | Applies to breakpoint `xl` and up | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropDescription
label-colsApplies to breakpoint xs up
label-cols-smApplies to breakpoint sm and up
label-cols-mdApplies to breakpoint md and up
label-cols-lgApplies to breakpoint xl and up
label-cols-xlApplies to breakpoint xl and up
content-colsApplies to breakpoint xs up
content-cols-smApplies to breakpoint sm and up
content-cols-mdApplies to breakpoint md and up
content-cols-lgApplies to breakpoint xl and up
content-cols-xlApplies to breakpoint xl and up
+Tags are added by clicking the Add button, pressing the Enter key or optionally when the change event fires on the new tag input (i.e. when focus moves from the input). The Add button will only appear when the user has entered a new tag value. + + + + + + +

Value: {{ basicUsageTags }}

+ + ``` - + + + +## Tag creation using separators + +To auto create tags when a separator character is typed (i.e. Space, ,, etc.), set the `separator` prop to the character that will trigger the tag to be added. If multiple separator characters are needed, then include them as a single string (i.e. ' ,;'), or an array of characters (i.e. `[' ', ',', ';']`), which will trigger a new tag to be added when Space, ,, or ; are typed). Separators must be a single character. + +The following example will auto create a tag when Space, ,, or ; are typed: + + + + + + +

Value: {{ usingSeparators }}

+ + + + +## Last tag removal via backspace keypress + +When the prop `remove-on-delete` is set, and the user presses Backspace (or Del) and the input value is empty, the last tag in the tag list will be removed. + + + + + + +> + + Press Backspace to remove the last tag entered + + +

Value: {{ tagRemoval }}

+ + + + +## Styling Options + +Several props are available to alter the basic styling of the default tagged interface: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropDescription
tag-pillsRenders the tags with the appearance of pills
tag-variantApplies one of the Bootstrap contextual variant theme colors to the tags
sizeSet the size of the component's appearance. sm, md (default), or lg
placeholderThe placeholder text for the new tag input element
state + Sets the contextual state of the control. Set to true (for valid), false (for invalid), or null +
disabledPlaces the component in a disabled state
+ +For additional props, see the component reference section at the bottom of this page. + +The focus and validation state styling of the component relies upon BootstrapVue's custom CSS. + + + + + + +

Value: {{ stylingOptions }}

+ + + + +## Using with native browser `
` submission + +The value of the tagged input will not be submitted via standard form `action` unless you provide a name via the name prop. When a name is provided, `` will create a hidden `` for each tag. The hidden input will have the `name` attribute set to the value of the `name` prop. + +The hidden inputs will also be generated when using [custom rendering](#custom-rendering-with-default-scoped-slot) (when the `name` prop is set). + +## Tag validation + +By default, `` detects when the user is attempting to enter a (case-sensitive) duplicate tag, and will provide integrated feedback to the user. + +You can optionally provide a tag validator method via the `tag-validator` prop. The validator function will receive one argument which is the tag being added, and should return either `true` if the tag passes validation and can be added, or `false` if the tag fails validation (in which case it is not added to the array of tags). Integrated feedback will be provided to the user listing the invalid tag(s) that could not be added. + +Tag validation occurs only for tags added via user input. Changes to the tags via the `v-model` are not validated. + + + + + + + + + + +### Detecting new, invalid, and duplicate tags + +The event `tag-state` will be emitted whenever new tags are entered into the new tag input element, tags that do not pass validation, or duplicate tags are detected. The event handler will receive three arrays as its arguments: + +- `validTags` (tags that pass validation) +- `invalidTags` (tags that do not pass validation) +- `duplicateTags` (tags that would be a duplicate of existing or validTags) + +The event will be emitted only when the new tag input changes (characters are entered that would be considered part of a tag), or when the user attempts to add a tag (i.e. via Enter, clicking the Add button, or entering a separator). The three arrays will be empty when the user clears the new tag input element (or contains just spaces). + +If you are providing your own feedback for duplicate and invalid tags (via the use of the tag-state event) outside of the `` component, you can disable the built in duplicate and invalid messages by setting the props duplicate-tag-text and invalid-tag-text (respectively) to either an empty string ('') or null. + + + + + + +

Tags: {{ detectingTags }}

+

Event values:

+
    +
  • validTags: {{ validTags }}
    • +
  • invalidTags: {{ invalidTags }}
    • +
  • duplicateTags: {{ duplicateTags }}
    • +
+ + + + +## Limiting tags + +If you want to limit the amount of tags the user is able to add use the `limit` prop. When configured, adding more tags than the `limit` allows is only possible by the `v-model`. + +When the limit of tags is reached, the user is still able to type but adding more tags is disabled. A message is shown to give the user feedback about the reached limit. This message can be configured by the `limit-tags-text` prop. Setting it to either an empty string (`''`) or `null` will disable the feedback. + +Removing tags is unaffected by the `limit` prop. + + + + + +

Value: {{ limitTagsModel }}

+ + + + +## Custom rendering with default scoped slot + +If you fancy a different look and feel for the tags control, you can provide your own custom rendering via the default scoped slot. You can either create your own tags, or use our helper `` component. + +### Scope properties + +The default scoped slot provides numerous properties and methods for use in rendering your custom interface. Not all properties or methods are required to generate your interface. + +The default slot scope properties are as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
addButtonTextStringThe value of the add-button-text prop
addButtonVariantStringThe value of the add-button-variant prop
addTagFunctionMethod to add a new tag. Assumes the tag is the value of the input, but optionally accepts one argument which is the tag value to be added
disableAddButtonBooleanWill be true if the tag(s) in the input cannot be added (all invalid and/or duplicates)
disabledBooleantrue if the component is in the disabled state. Value of the disabled prop
duplicateTagTextStringThe value of the duplicate-tag-text prop
duplicateTagsArrayArray of the duplicate tag(s) the user has entered
formStringThe value of the form prop
inputAttrsObjectObject of attributes to apply to the new tag input element via v-bind="inputAttrs". See below for details
inputHandlersObjectObject of event handlers to apply to the new tag input element via v-on="inputHandlers". See below for details
inputIdStringID to add to the new tag input element. Defaults to prop input-id. If not provided a unique ID is auto-generated. Also available via 'inputAttrs.id'
inputTypeStringType of input to render (normalized version of prop input-type)
invalidTagTextStringThe value of the invalid-tag-text prop
invalidTagsArrayArray of the invalid tag(s) the user has entered
isDuplicateBooleantrue if the user input contains duplicate tag(s)
isInvalidBooleantrue if the user input contains invalid tag(s)
isLimitReachedBooleantrue if a limit is configured and the amount of tags has reached the limit
limitTagsTextStringThe value of the limit-tags-text prop
limitTagsTextStringThe value of the limit-tags-text prop
limitStringThe value of the limit prop
noTagRemoveBooleanThe value of the no-tag-remove prop
placeholderStringThe value of the placeholder prop
removeTagFunctionMethod to remove a tag. Accepts one argument which is the tag value to remove
requiredBooleanThe value of the required prop
separatorStringThe value of the separator prop
sizeStringThe value of the size prop
stateBooleanThe contextual state of the component. Value of the state prop. Possible values are true, false or null
tagClassString, Array, or ObjectThe value of the tag-variant prop. Class (or classes) to apply to the tag elements
tagPillsBooleanThe value of the tag-pills prop.
tagRemoveLabelStringValue of the tag-remove-label prop. Used as the aria-label attribute on the remove button of tags
tagVariantStringValue of the tag-variant prop.
tagsArrayArray of current tag strings
+ +#### `inputAttrs` object properties + +The `inputAttrs` object contains attributes to bind (`v-bind`) to the new tag input element. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
disabledBooleanThe disabled attribute for the new tag input. Value of the disabled prop
formStringThe value of the form prop
idStringThe id attribute for the new tag input
valueStringThe value attribute for the new tag input
+ +The `inputAttrs` object will also include any attributes set via the `input-attrs` prop. Note that the above attributes take precedence over any of the same attributes specified in the `input-attrs` prop. + +#### `inputHandlers` object properties + +The `inputHandlers` object contains event handlers to bind (`v-on`) to the new tag input element. + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
changeFunctionEvent handler for the input element change event. Accepts a single argument of either an event object or a string. Change will trigger adding the tag.
inputFunctionEvent handler for the input element input event. Accepts a single argument of either an event object or a string. Updates the internal v-model for the new tag input element
keydownFunctionEvent handler for the input element keydown Enter and Del events. Accepts a single argument which is the native keydown event object
+ +The `change` handler, when needed, must be enabled via the `add-on-change` prop, otherwise it is a noop method. + +### Using native browser inputs + +The scope contains attributes and event handlers that can be directly bound to native `` or ``~~ +- `BFormDatalist` Easily create a `` for use with `BFormInput` or plain `` ### Form text helper diff --git a/packages/bootstrap-vue-next/src/components/BFormTags/BFormTags.vue b/packages/bootstrap-vue-next/src/components/BFormTags/BFormTags.vue index 45db11a9b..d9a7df25c 100644 --- a/packages/bootstrap-vue-next/src/components/BFormTags/BFormTags.vue +++ b/packages/bootstrap-vue-next/src/components/BFormTags/BFormTags.vue @@ -104,8 +104,8 @@ {{ duplicateTagText }}: {{ inputValue }} - Tag limit reached + {{ limitTagsText }} @@ -116,8 +116,8 @@