diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e40cd39e..6e369499a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,17 @@ Changelog is rather internal in nature. See release notes for the public overvie ## Upcoming version 5.x.x (`develop` branch) +- [#549] + - **Description:** Internal refactor of `KSelect` as part of moving away from Keen UI where related files were renamed and some functionality that wasn't exposed for public use was removed. + - **Products impact:** none + - **Addresses:** - + - **Components:** - + - **Breaking:** no + - **Impacts a11y:** - + - **Guidance:** Thorough QA of places that use `KSelect` is recommended due to the large scope of refactor. + +[#549]: https://github.com/learningequality/kolibri-design-system/pull/549 + - [#615] - **Description:** Removes KImg props related to dimensions: `height`, `width`, `maxHeight`, `minHeight`, `maxWidth`, `minWidth` - **Products impact:** updated API diff --git a/lib/KSelect/KeenUiSelectOption.vue b/lib/KSelect/KSelectOption.vue similarity index 99% rename from lib/KSelect/KeenUiSelectOption.vue rename to lib/KSelect/KSelectOption.vue index fa9cc859a..3d2faef2e 100644 --- a/lib/KSelect/KeenUiSelectOption.vue +++ b/lib/KSelect/KSelectOption.vue @@ -48,7 +48,7 @@ import UiIcon from '../keen/UiIcon'; export default { - name: 'KeenUiSelectOption', + name: 'KSelectOption', components: { UiIcon, }, diff --git a/lib/KSelect/KeenUiSelect.vue b/lib/KSelect/KeenUiSelect.vue deleted file mode 100644 index b4011191d..000000000 --- a/lib/KSelect/KeenUiSelect.vue +++ /dev/null @@ -1,1197 +0,0 @@ - - - - - - - diff --git a/lib/KSelect/index.vue b/lib/KSelect/index.vue index a92a9008e..cc4dcdbb8 100644 --- a/lib/KSelect/index.vue +++ b/lib/KSelect/index.vue @@ -1,40 +1,146 @@ @@ -43,7 +149,15 @@ import has from 'lodash/has'; import isObject from 'lodash/isObject'; - import UiSelect from './KeenUiSelect'; + import fuzzysearch from 'fuzzysearch'; + import startswith from 'lodash/startsWith'; + import sortby from 'lodash/sortBy'; + import UiIcon from '../keen/UiIcon'; + + import { looseIndexOf, looseEqual } from '../keen/helpers/util'; + import { scrollIntoView, resetScroll } from '../keen/helpers/element-scroll'; + import config from '../keen/config'; + import KSelectOption from './KSelectOption.vue'; function areValidOptions(array) { return array.every(object => { @@ -60,13 +174,19 @@ return has(object, 'value') && has(object, 'label'); } - /** - * Used to select or filter items - */ + /* + A customized version of a select component that was originally + copied from older version of Keen UI. Note that in + https://github.com/learningequality/kolibri-design-system/pull/549, + the component went through larger refactor as part of migrating away from Keen + and some pieces we didn't use were removed. When adding new features, + it may still be helpful to check out the referenced PR to see if some + of the removed functionality may be handy, at least as inspiration. */ export default { name: 'KSelect', components: { - UiSelect, + UiIcon, + KSelectOption, }, model: { event: 'change', @@ -93,6 +213,13 @@ return areValidOptions(val); }, }, + /** + * Placeholder + */ + placeholder: { + type: String, + default: '', + }, /** * Label */ @@ -101,12 +228,39 @@ default: null, }, /** - * Whether disabled or not + * Floating Label */ - disabled: { + floatingLabel: { + type: Boolean, + default: true, + }, + /** + * Whether multiple options can be selected or not + */ + multiple: { type: Boolean, default: false, }, + /** + * Delimiter for multiple selected options + */ + multipleDelimiter: { + type: String, + default: ', ', + }, + /** + * Text displayed if no results + */ + noResultsText: { + type: String, + default: '', + }, + keys: { + type: Object, + default() { + return config.data.UiSelect.keys; + }, + }, /** * Whether invalid or not */ @@ -122,20 +276,19 @@ default: null, }, /** - * Whether or not display as inline block + * Help text */ - inline: { - type: Boolean, - default: false, - }, - floatingLabel: { - type: Boolean, - default: true, - }, - placeholder: { + help: { type: String, default: null, }, + /** + * Whether disabled or not + */ + disabled: { + type: Boolean, + default: false, + }, /** * Whether to turn into a clearable state * when an option has been selected. @@ -148,22 +301,228 @@ type: String, default: '', }, + /** + * Whether or not display as inline block + */ + inline: { + type: Boolean, + default: false, + }, }, + data() { return { + query: '', + isInsideModal: false, + isActive: false, + isTouched: false, + highlightedOption: null, + showDropdown: false, + initialValue: JSON.stringify(this.value), + quickMatchString: '', + quickMatchTimeout: null, + scrollableAncestor: null, + dropdownButtonBottom: 'auto', + maxDropdownHeight: 256, // workaround for Keen-ui not displaying floating labels for empty objects selection: Object.keys(this.value || {}).length === 0 ? '' : this.value, }; }, + computed: { name() { - return `k-select-${this._uid}`; + return `ui-select-${this._uid}`; + }, + classes() { + return [ + `ui-select-type-basic`, + { 'is-active': this.isActive }, + { 'is-invalid': this.invalid }, + { 'is-touched': this.isTouched }, + { 'is-disabled': this.disabled }, + { 'is-multiple': this.multiple }, + { 'has-label': this.hasLabel }, + { 'has-floating-label': this.hasFloatingLabel }, + { 'ui-select-inline': this.inline }, + { 'ui-select-disabled': this.disabled }, + ]; + }, + + labelClasses() { + return { + 'is-inline': this.hasFloatingLabel && this.isLabelInline, + 'is-floating': this.hasFloatingLabel && !this.isLabelInline, + }; + }, + + hasLabel() { + return Boolean(this.label) || Boolean(this.$slots.default); + }, + + hasFloatingLabel() { + return this.hasLabel && this.floatingLabel; + }, + + isLabelInline() { + return this.selection.length === 0 && !this.isActive; + }, + + hasFeedback() { + return Boolean(this.help) || Boolean(this.invalidText) || Boolean(this.$slots.error); + }, + + showError() { + return this.invalid && (Boolean(this.invalidText) || Boolean(this.$slots.error)); + }, + + showHelp() { + return !this.showError && (Boolean(this.help) || Boolean(this.$slots.help)); + }, + + filteredOptions() { + return this.options.filter((option, index) => { + return this.defaultFilter(option, index); + }); + }, + + displayText() { + if (this.multiple) { + if (this.selection.length > 0) { + return this.selection + .map(selection => selection[this.keys.label] || selection) + .join(this.multipleDelimiter); + } + + return ''; + } + return this.selection ? this.selection[this.keys.label] || this.selection : ''; + }, + + hasDisplayText() { + return Boolean(this.displayText.length); + }, + + hasNoResults() { + if (this.query.length === 0) { + return false; + } + + return this.filteredOptions.length === 0; + }, + + submittedValue() { + // Assuming that if there is no name, then there's no + // need to computed the submittedValue + if (!this.name || !this.selection) { + return; + } + + if (Array.isArray(this.selection)) { + return this.selection.map(option => option[this.keys.value] || option).join(','); + } + + return this.selection[this.keys.value] || this.selection; + }, + + // Returns the index of the currently highlighted option + highlightedIndex() { + return this.options.findIndex(option => looseEqual(this.highlightedOption, option)); + }, + + // Returns an array containing the options and extra annotations + annotatedOptions() { + const options = JSON.parse(JSON.stringify(this.options)); + return options.map((option, index) => { + // If not object, create object + if (typeof option !== 'object') { + option = { + [this.keys.value]: option, + [this.keys.label]: option, + }; + } + + // Add index to object + option.index = index; + + // Check if valid prev/next + if (!option.disabled) { + if (index < this.highlightedIndex) { + option.validPreviousOption = true; + } else if (index > this.highlightedIndex) { + option.validNextOption = true; + } + } + + // Check if matches + option.startsWith = startswith( + option[this.keys.label].toLowerCase(), + this.quickMatchString.toLowerCase() + ); + + return option; + }); + }, + activeColorStyle() { + if (this.isActive) { + return { + color: this.$themeTokens.primary, + }; + } + + return {}; + }, + activeBorderStyle() { + if (this.isActive && !this.clearableState) { + return { + borderBottomColor: this.$themeTokens.primary, + }; + } else if (this.clearableState) { + return { + cursor: 'default', + }; + } + + return {}; + }, + clearableState() { + return ( + this.clearable && this.selection && Object.keys(this.selection).length && !this.disabled + ); }, }, + watch: { - value(inputValue) { - this.selection = inputValue; + filteredOptions() { + this.highlightedOption = this.filteredOptions[0]; + resetScroll(this.$refs.optionsList); }, + + showDropdown() { + if (this.showDropdown) { + this.onOpen(); + this.$emit('dropdown-open'); + } else { + this.onClose(); + this.$emit('dropdown-close'); + } + }, + + query() { + this.$emit('query-change', this.query); + }, + + quickMatchString(string) { + if (string) { + if (this.quickMatchTimeout) { + clearTimeout(this.quickMatchTimeout); + this.quickMatchTimeout = null; + } + this.quickMatchTimeout = setTimeout(() => { + this.quickMatchString = ''; + }, 500); + } + }, + selection(newSelection) { /* Emits new selection.*/ if (!this.disabled) { @@ -171,12 +530,354 @@ } }, }, + + created() { + if (!this.selection || this.selection === '') { + this.setValue(null); + } + }, + + mounted() { + document.addEventListener('click', this.onExternalClick); + // Find nearest scrollable ancestor + this.scrollableAncestor = this.$el; + while ( + (this.scrollableAncestor && + this.scrollableAncestor.clientHeight < this.scrollableAncestor.scrollHeight) || + !/auto|scroll/.test(window.getComputedStyle(this.scrollableAncestor).overflowY) + ) { + if (!this.scrollableAncestor.parentNode) { + break; + } + this.scrollableAncestor = this.scrollableAncestor.parentNode; + + // Stop if we reach the body-- tagName is likely uppercase + if (/body/i.test(this.scrollableAncestor.tagName)) { + break; + } + } + + // look for KSelects nested within modals + const allSelects = document.querySelectorAll('div.modal div.ui-select'); + // create array from a nodelist [IE does not support Array.from()] + const allSelectsArr = Array.prototype.slice.call(allSelects); + this.isInsideModal = allSelectsArr.includes(this.$el); + }, + + beforeDestroy() { + document.removeEventListener('click', this.onExternalClick); + }, + methods: { - handleChange(newSelection) { - this.selection = newSelection; + setValue(value) { + value = value ? value : this.multiple ? [] : ''; + this.selection = value; + + this.$emit('input', value); + }, + + // Highlights the matching option on key input + highlightQuickMatch(event) { + // https://github.com/ccampbell/mousetrap/blob/master/mousetrap.js#L39 + const specialKeyCodes = [ + 8, + 9, + 13, + 16, + 17, + 18, + 20, + 27, + 32, + 33, + 34, + 35, + 36, + 37, + 38, + 39, + 40, + 45, + 46, + 91, + 93, + 224, + ]; + const keyCode = event.keyCode; + if (specialKeyCodes.includes(keyCode)) { + return; + } + + const character = event.key.toString(); + this.quickMatchString += character; + let matchingItems = this.annotatedOptions.filter( + option => option.startsWith && !option.disabled + ); + if (matchingItems.length !== 0) { + matchingItems = sortby(matchingItems, [this.keys.label]); + matchingItems = sortby(matchingItems, item => item[this.keys.label].length); + this.highlightOption(this.options[matchingItems[0].index]); + } + }, + + // Highlights the previous valid option + highlightPreviousOption() { + const options = this.annotatedOptions; + let validPreviousOptionIndex = -1; + for (let i = 0; i < options.length; i++) { + if (options[i].validPreviousOption) { + validPreviousOptionIndex = i; + } + } + if (validPreviousOptionIndex !== -1) { + this.highlightOption(this.options[validPreviousOptionIndex]); + } + }, + + // Highlights the next valid option + highlightNextOption() { + const options = this.annotatedOptions; + const validNextOptionIndex = options.findIndex(option => option.validNextOption); + if (validNextOptionIndex !== -1) { + this.highlightOption(this.options[validNextOptionIndex]); + } + }, + + // Highlights the option + highlightOption(option, options = { autoScroll: true }) { + if ( + !option || + option.disabled || + looseEqual(this.highlightedOption, option) || + this.$refs.options.length === 0 + ) { + return; + } + + this.highlightedOption = option; + this.openDropdown(); + + if (options.autoScroll) { + const index = this.filteredOptions.findIndex(option => + looseEqual(this.highlightedOption, option) + ); + const optionToScrollTo = this.$refs.options[index]; + if (optionToScrollTo) { + this.scrollOptionIntoView(optionToScrollTo.$el); + } + } + }, + + selectHighlighted() { + if ( + this.highlightedOption && + !this.highlightedOption.disabled && + this.$refs.options.length > 0 + ) { + this.selectOption(this.highlightedOption); + } + }, + + selectOption(option, options = { autoClose: true }) { + if (!option || option.disabled) { + return; + } + + const shouldSelect = this.multiple && !this.isOptionSelected(option); + + if (this.multiple) { + this.updateOption(option, { select: shouldSelect }); + } else { + this.setValue(option); + } + + this.$emit('select', option, { + selected: !this.isOptionSelected(option), + }); + + this.clearQuery(); + + if (!this.multiple && options.autoClose) { + this.closeDropdown(); + } + }, + + // Checks if option is highlighted + isOptionHighlighted(option) { + return looseEqual(this.highlightedOption, option); + }, + + isOptionSelected(option) { + if (this.multiple) { + return looseIndexOf(this.selection, option) > -1; + } + return looseEqual(this.selection, option); + }, + + updateOption(option, options = { select: true }) { + let value = []; + let updated = false; + const i = looseIndexOf(this.selection, option); + + if (options.select && i < 0) { + value = this.selection.concat(option); + updated = true; + } + + if (!options.select && i > -1) { + value = this.selection.slice(0, i).concat(this.selection.slice(i + 1)); + updated = true; + } + + if (updated) { + this.setValue(value); + } + }, + + defaultFilter(option) { + const query = this.query.toLowerCase(); + let text = option[this.keys.label] || option; + + if (typeof text === 'string') { + text = text.toLowerCase(); + } + + return fuzzysearch(query, text); + }, + + clearQuery() { + this.query = ''; + }, + + toggleDropdown() { + // if called on dropdown inside modal, dropdown will generally render above input/placeholder when opened, + // rather than below it: we want to render dropdown above input only in cases where there isn't enough + // space available beneath input, but when dropdown extends outside a modal the func doesn't work as intended + if (!this.isInsideModal) this.calculateSpaceBelow(); + + this[this.showDropdown ? 'closeDropdown' : 'openDropdown'](); + }, + + openDropdown() { + if (this.disabled || this.clearableState) { + return; + } + + if (this.highlightedIndex === -1) { + this.highlightNextOption(); + } + + this.showDropdown = true; + // IE: clicking label doesn't focus the select element + // to set isActive to true + if (!this.isActive) { + this.isActive = true; + } + }, + + closeDropdown(options = { autoBlur: false }) { + this.showDropdown = false; + this.query = ''; + if (!this.isTouched) { + this.isTouched = true; + this.$emit('touch'); + } + + if (options.autoBlur) { + this.isActive = false; + } else { + this.$refs.label.focus(); + } + }, + + onMouseover(option) { + if (this.showDropdown) { + this.highlightOption(option, { autoScroll: false }); + } + }, + + onFocus(e) { + if (this.isActive) { + return; + } + + this.isActive = true; + this.$emit('focus', e); + }, + + onBlur(e) { + this.isActive = false; + this.$emit('blur', e); + + if (this.showDropdown) { + this.closeDropdown({ autoBlur: true }); + } + }, + + onOpen() { + this.highlightedOption = this.multiple ? null : this.selection; + this.$nextTick(() => { + this.$refs['dropdown'].focus(); + const selectedOption = this.$refs.optionsList.querySelector('.is-selected'); + if (selectedOption) { + this.scrollOptionIntoView(selectedOption); + } else { + this.scrollOptionIntoView( + this.$refs.optionsList.querySelector('.ui-select-option:not(.is-disabled)') + ); + } + }); + }, + + onClose() { + this.highlightedOption = this.multiple ? null : this.selection; + }, + + onExternalClick(e) { + if (!this.$el.contains(e.target)) { + if (this.showDropdown) { + this.closeDropdown({ autoBlur: true }); + } else if (this.isActive) { + this.isActive = false; + } + } }, - handleSelect(newSelection, options) { - this.$emit('select', newSelection, options); + + scrollOptionIntoView(optionEl) { + scrollIntoView(optionEl, { + container: this.$refs.optionsList, + marginTop: 180, + }); + }, + + /** + * @public + */ + reset() { + this.setValue(JSON.parse(this.initialValue)); + this.clearQuery(); + this.resetTouched(); + this.highlightedOption = null; + }, + + resetTouched(options = { touched: false }) { + this.isTouched = options.touched; + }, + calculateSpaceBelow() { + // Get the height of element + const buttonHeight = this.$el.getBoundingClientRect().height; + + // Get the position of the element relative to the viewport + const buttonPosition = this.$el.getBoundingClientRect().top; + + // Check if there is enough space below element + // and update the "dropdownButtonBottom" data property accordingly + const notEnoughSpaceBelow = + buttonPosition > this.maxDropdownHeight && + this.scrollableAncestor.offsetHeight - buttonPosition < + buttonHeight + this.maxDropdownHeight; + + this.dropdownButtonBottom = notEnoughSpaceBelow ? buttonHeight + 'px' : 'auto'; }, }, }; @@ -186,22 +887,248 @@