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

@tournant/notification

v1.0.0

Published

Screenreader friendly notification messages

Downloads

3

Readme

@tournant/alert

Notification messages that can be picked up by screenreaders. Implements the status role by default. But can also be used an alert widget.

Installation

We are following standard package procedures. You can install the component using NPM or Yarn.

npm install @tournant/notification --save

If you use Yarn:

yarn add @tournant/notification

Once the component is installed you need to import it wherever you want to use it.

import TournantNotification from '@tournant/notification'

Don’t forget to add it to the registered components (been there, done that):

components: {
  TournantNotification,
  // ... all the other amazing components
}

Usage

The default usage of this component is the implementation of the status role. This role sets aria-live to polite, meaning that the text content of the component will be read after the screenreader has finished its current output.

If you need to announce something important, change the prop type to be assertive. This will render the component with a role of alert and interrupt a screen reader in its current output.

Usage as a status message

A status message is a message that will be announced after the current output. It is useful if, say, a new page has been loaded. This is the default behaviour.

<!-- Input !-->
<tournant-notification message="Page 4 has been loaded" />

<!-- Output -->
<div role="status" class="t-ui-alert is-info">Page 4 has been loaded</div>
>

Usage as an alert message

An alert will be announced immdiately. It is useful if, say, a critical error has occured.

<!-- Input !-->
<tournant-notification
	type="assertive"
	message="There has been an error parsing your data."
/>

<!-- Output -->
<div role="alert" state="error" class="t-ui-alert is-info">
	There has been an error parsing your data
</div>
>

Props

The following props can be used to control the component:

  • message: Required. A string that should be added to page and read out by screen readers.
  • state: Default: info. A state level, with which you can control visual representation. See section #css below.
  • type: Default: polite. Controls the announcement by a screen reader. Must be either assertive or polite.
  • hideAfterSeconds: Default: 5. The time which should pass before the message is hidden.

Timeout

Alerts are only status messages. As such, they do not require user interaction. The spec is pretty clear:

Neither authors nor user agents are required to set or manage focus to them in order for them to be processed. Since alerts are not required to receive focus, content authors SHOULD NOT require users to close an alert.

That’s why it is important to clear messages after a while. The while depends on the length of your messages. We use a default value of five seconds. But you are free to change to this with the hideAfterSeconds prop.

Note: It is named hideAfterSeconds. We multiply the value by 1,000 in the component. Do not pass miliseconds as a value.

Once the timeout elapses, the component sets aria-hidden to true and display: none. We do this to make it easier to comply with the ARIA requirements. You should, nonetheless, take care of discarding old messages in your app yourself.

TalkBack Usage Notes

From our testing it seems as if TalkBack on Android reads alert content twice.

CSS

The component exposes the t-ui-alert class by default. Additionally it will set the current state prepended by «is» as its class. Some examples:

<!-- Input !-->
<tournant-notification state="error" type="assertive" message="404 Not Found" />
<!-- Output !-->
<div role="alert" class="t-ui-alert is-error">404 Not Found</div>

<!-- Input !-->
<tournant-notification state="success" message="200 OK" />
<!-- Output !-->
<div role="status" class="t-ui-alert is-success">200 OK</div>

States can be whatever you want:

<!-- Input !-->
<tournant-notification state="im-a-teapot" message="418 I’m a Teapot" />
<!-- Output !-->
<div role="status" class="t-ui-alert is-im-a-teapot">418 I’m a Teapot</div>

These can act as a helper to style the component matching the state.

Hiding messages

If the timeout elapsed and the message has not been removed from the outside, aria-hidden will be set to true. To keep the UI in sync, display: none is added to the root element.

The component will emit the event messageTimeout as soon as the timeout elapses. You can use this event to run a clean-up task in your app.

Bugs & Enhancements

If you found a bug, please create a bug ticket.

For enhancements please refer to the contributing guidelines.