npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@thoughtbot/trix-mentions-element

v0.1.2

Published

Activates a suggestion menu to embed attachments as you type.

Downloads

790

Readme

<trix-mentions> element

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

Inspired by @github/text-expander-element.

Installation

$ npm install --save @thoughtbot/trix-mentions-element

Usage

Script

Import as ES modules:

import Trix from 'trix'
import '@thoughtbot/trix-mentions-element'

window.Trix = Trix

With a script tag:

<script type="module" src="./node_modules/@thoughtbot/trix-mentions-element/dist/bundle.js">

Markup

<trix-mentions keys="@ #" multiword="#">
  <trix-editor></trix-editor>
</trix-mentions>

Attributes

  • 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
  • name is the name of the key used when merging a match's text into a URL
  • src the path or URL to retrieve options from
  • data-turbo-frame used to identify which <turbo-frame> element to navigate when the menu of options is active

Events

trix-mentions-change is fired when a key is matched. In event.detail you can find:

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

Warning

Event listener callbacks are synchronous and will not block to wait for Promise resolution. If your provide callback is asynchronous, make sure to chain additional Promise instances with Promise.then, or make sure to nest any async or await keywords within the callback function passed to detail.provide.

const expander = document.querySelector('trix-mentions')

expander.addEventListener('trix-mentions-change', function(event) {
  const {key, provide, text} = event.detail
  if (key !== '@') return

  const suggestions = document.querySelector('.emoji-suggestions').cloneNode(true)
  suggestions.hidden = false
  for (const suggestion of suggestions.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. Any attribute whose name it prefixed by data-trix-attachment- will transformed into camelCase and used to create a Trix.Attachment instance under the hood. For example:

<ul class="emoji-suggestions" hidden>
  <li role="option" data-trix-attachment-content="🐈"
                    data-trix-attachment-content-type="application/vnd.my-application.mention">
    🐈 @cat2
  </li>
  <li role="option" data-trix-attachment-content="🐕"
                    data-trix-attachment-content-type="application/vnd.my-application.mention">
    🐕 @dog
  </li>
</ul>

Alternatively, Trix.Attachment options can be serialized into a JSON object and encoded into a single [data-trix-attchment] attribute. Additional data-trix-attachment- prefixed attributes will be merged in as overrides.

When the Trix.Attachment options are missing a content key, the selected [role="option"] element's innerHTML will serve as the content: value.

trix-mentions-value is fired when an item is selected. In event.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 the value.
  • value: A null value placeholder to replace the query. To replace the query text, re-assign this value.
const expander = document.querySelector('trix-mentions')

expander.addEventListener('trix-mentions-value', function(event) {
  const {key, item}  = event.detail
  if (key === '@') {
    const contentType = item.getAttribute('data-trix-attachment-content-type')
    const content = item.getAttribute('data-trix-attachment-content')

    event.detail.value = {content, contentType}
  }
})

Often times, when [role="option"] elements encode the Trix.Attachment arguments into their data-trix-attachment-prefixed attributes, trix-mentions-value event listeners can be omitted entirely.

Built-in support for Turbo Frames

All <trix-mentions> elements have built-in support for driving <turbo-frame> elements.

First, render them with a [name] attribute to serve as the query parameter key, and a [data-turbo-frame] attribute that references a <turbo-frame> element with a matching [id] attribute:

<trix-mentions key="@" name="query" data-turbo-frame="users">
  <trix-editor></trix-editor>
</trix-mentions>
<turbo-frame id="users" role="listbox" hidden></turbo-frame>

Make sure to render the <turbo-frame> with the [hidden] attribute to start.

Then, whenever a trix-mentions-change event is dispatched that bubbles without any calls to CustomEvent.detail.provide, the <trix-mentions> element will merge its current match's text into its [src] attribute (using the [name] attribute as its key) then write that value to the <turbo-frame> element's [src] attribute. It'll wait for the FrameElement.loaded promise to resolve before proceeding. When the <trix-mentions> element's [src] attribute is missing, it'll merge the name-value pair directly into the <turbo-frame> element's [src] attribute's search parameters.

Finally, it'll manage the <turbo-frame> element's [hidden] attribute and keep it synchronized with the visibility of the expanded list of options.

Trix-powered Action Text mentions

Inspired by Implementing rich-text mentions with Action Text by George Claghorn

The <trix-mentions> element integrates with Action Text attachments to embed server-generated HTML renderings of Active Record instances.

Start with a User model:

class User < ApplicationRecord
  scope :where_username_like, ->(text) {
    if text.present?
      where("username LIKE ?", text + "%")
    else
      none
    end
  }
end

Include the ActionText::Attachable module into the class:

 class User < ApplicationRecord
+  include ActionText::Attachable
+
   scope :where_username_like, ->(text) {
     if text.present?
       where("username LIKE ?", text + "%")
     else
       none
     end
   }
 end

Action Text will generate the HTML for an attached User record by rendering the partial name it returns from its User#to_trix_content_attachment_partial_path method. By default, that method will return users/user.

If you'd like to render a different partial, override it to return a different path:

 class User < ApplicationRecord
   include ActionText::Attachable

   scope :where_username_like, ->(text) {
     if text.present?
       where("username LIKE ?", text + "%")
     else
       none
     end
   }
+
+  def to_trix_content_attachment_partial_path
+    "users/trix_content_attachment"
+  end
 end

Then, declare the partial's template:

<%# app/views/users/_trix_content_attachment.html.erb %>
<span>@<%= user.username %></span>

The record instance will be available under a key that matches its class name. In this case, user:

Next, render the <trix-mentions>. In this example, we'll nest a <trix-editor> element to serve as its input, and a <turbo-frame> element to serve as its listbox:

<trix-mentions key="@" name="query" data-turbo-frame="users">
  <trix-editor></trix-editor>
  <turbo-frame id="users" role="listbox" hidden>
  </turbo-frame>
<trix-mentions>

Within the <turbo-frame> element, render a list of [role="option"] elements that match the value of params[:query]:

 <trix-mentions key="@" name="query" data-turbo-frame="users">
   <trix-editor></trix-editor>
   <turbo-frame id="users" role="listbox" hidden>
+    <% User.where_username_like(params[:query]).each do |user| %>
+      <button id="<%= dom_id(user, :mention) %>" type="button" role="option" tabindex="-1">
+        <%= render user.to_trix_content_attachment_partial_path, user: user %>
+     </button>
+    <% end %>
   </turbo-frame>
 <trix-mentions>

Then, encode the User#attachable_sgid into the element's [data-trix-attachment-sgid] attribute:

 <trix-mentions key="@" name="query" data-turbo-frame="users">
   <trix-editor></trix-editor>
   <turbo-frame id="users" role="listbox" hidden>
     <% User.where_username_like(params[:query]).each do |user| %>
-      <button id="<%= dom_id(user, :mention) %>" type="button" role="option" tabindex="-1">
+      <button id="<%= dom_id(user, :mention) %>" type="button" role="option" tabindex="-1"
+              data-trix-attachment-sgid="<%= user.attachable_sgid %>">
         <%= render user.to_trix_content_attachment_partial_path, user: user %>
      </button>
     <% end %>
   </turbo-frame>
 <trix-mentions>

If the Trix.Attachment instance requires more attributes, you can encode their values under kebab-case key names with a data-trix-attachment- prefix, or as a single JSON-encoded object under the [data-trix-attachment] key:

 <trix-mentions key="@" name="query" data-turbo-frame="users">
   <trix-editor></trix-editor>
   <turbo-frame id="users" role="listbox" hidden>
     <% User.where_username_like(params[:query]).each do |user| %>
-      <button id="<%= dom_id(user, :mention) %>" type="button" role="option" tabindex="-1">
+      <button id="<%= dom_id(user, :mention) %>" type="button" role="option" tabindex="-1"
+              data-trix-attachment="<%= html_escape { sgid: user.attachable_sgid, content_type: "..." }.to_json %>">
         <%= render user.to_trix_content_attachment_partial_path, user: user %>
      </button>
     <% end %>
   </turbo-frame>
 <trix-mentions>

Then, declare a partial template for Action Text to render when it encounters attached User instances. By default, Action Text will attempt to render users/user, but that partial path can be overridden by declaring User#to_attachable_partial_path:

 class User < ApplicationRecord
   include ActionText::Attachable

   scope :where_username_like, ->(text) {
     if text.present?
       where("username LIKE ?", text + "%")
     else
       none
     end
   }

   def to_trix_content_attachment_partial_path
     "users/trix_content_attachment"
   end

+  def to_atachable_partial_path
+    "users/attachable"
+  end
 end

Finally, declare the template to render an attached User:

<%# app/views/users/_attachable.html.erb %>

<%= link_to user do %>
  <%= render user.to_trix_content_attachment_partial_path, user: user %>
<% end %>

Browser support

Browsers without native custom element support require a polyfill.

  • Chrome
  • Firefox
  • Safari
  • Microsoft Edge

Development

npm install
npm test

Please read CONTRIBUTING.md.

License

Distributed under the MIT license. See LICENSE for details.