Repository files navigation

Activates a suggestion menu to expand text snippets as you type.

$ npm install --save @github/text-expander-element

Import as ES modules:

import'@github/text-expander-element'

With a script tag:

<scripttype="module"src="./node_modules/@github/text-expander-element/dist/bundle.js">

<text-expanderkeys=": @ #"multiword="#"><textarea></textarea></text-expander>

• keys is a space separated list of menu activation keys
• multiword defines whether the expansion should use several words or not
  • you can provide a space separated list of activation keys that should support multi-word matching
• suffix is a string that is appended to the value during expansion, default is a single space character

text-expander-change is fired when a key is matched. Inevent.detail you can find:

• key: The matched key; for example::.
• text: The matched text; for example:cat, for:cat.
  • If thekey is specified in themultiword attribute then the matched text can contain multiple words; for examplecat and dog for:cat and dog.
• provide: A function to be called when you have the menu results. Takes aPromise with{matched: boolean, fragment: HTMLElement} wherematched tells the element whether a suggestion is available, andfragment is the menu content to be displayed on the page.

constexpander=document.querySelector('text-expander')expander.addEventListener('text-expander-change',function(event){const{key, provide, text}=event.detailif(key!==':')returnconstsuggestions=document.querySelector('.emoji-suggestions').cloneNode(true)suggestions.hidden=falsefor(constsuggestionofsuggestions.children){if(!suggestion.textContent.match(text)){suggestion.remove()}}provide(Promise.resolve({matched:suggestions.childElementCount>0,fragment:suggestions}))})

The returned fragment should be consisted of filtered[role=option] items to be selected. For example:

<ulclass="emoji-suggestions"hidden><lirole="option"data-value="🐈">🐈 :cat2:</li><lirole="option"data-value="🐕">🐕 :dog:</li></ul>

text-expander-value is fired when an item is selected. Inevent.detail you can find:

• key: The matched key; for example::.
• item: The selected item. This would be one of the[role=option]. Use this to work out thevalue.
• value: A null value placeholder to replace the query. To replace the text query, simply re-assign this value.
• continue: A boolean value to specify whether to continue autocompletion after inserting a value. Defaults tofalse. If set totrue, will not add a space after inserted value and will keep firing thetext-expander-change event.

constexpander=document.querySelector('text-expander')expander.addEventListener('text-expander-value',function(event){const{key, item}=event.detailif(key===':'){event.detail.value=item.getAttribute('data-value')}})

text-expander-committed is fired after the underlyinginput value has been updated in the DOM. Inevent.detail you can find:

• input: TheHTMLInputElement orHTMLTextAreaElement that just hadvalue changes committed to the DOM.

constexpander=document.querySelector('text-expander')expander.addEventListener('text-expander-committed',function(event){const{input}=event.detail})

text-expander-activate is fired just after the menu has been assigned and appended to the DOM, and just before it is about to be positioned near the text to expand. This is useful for assigning classes or calling imperative methods to show the menu, such as.showPopover().

text-expander-deactivate is fired just before the menu is going to be unassigned and removed from the DOM. This is useful for removing classes or running cleanup like removing from caches.

Browsers without nativecustom element support require apolyfill.

• Chrome
• Firefox
• Safari
• Microsoft Edge

npm installnpm test

Distributed under the MIT license. See LICENSE for details.