iwb-serenity-password-vue-2 v0.3.0

Password

A password field as a form of a Vue 2 component for Serenity (Immoweb’s design system).

It includes a password reveal button.

Table of contents

• Summary usage
• Installation
• Props - v-model - name
  • autocomplete - label - show-password-label - hide-password-label - in-modal - error
• Events
• Accessibility
• Various - Changelog - Development - License

Summary usage

In a Vue component:

<template>
    <form>
        <!-- fields, buttons… -->

        <iw-password
            v-model="password"
            name="login-password"
            label="Password"
            show-password-label="Show password"
            password-shown-text="Password is shown"
            password-hidden-text="Password is hidden"
        />

    </form>
</template>

<script>
import Vue from "vue";
import iwPassword from "iwb-serenity-password-vue-2";

export default Vue.extend({
    data: function() {
        return {
            password: "", // bound to component with `v-model`
        };
    },
});
</script>

Additionally, you can check the demo app.

Installation

This component works in project including:

• Vue 2 (for other versions of Vue, see iwb-serenity-password)
• Serenity 2, for the base CSS used by this package styles.

1. Run this command in your terminal:

npm install iwb-serenity-password-vue-2

2. Register the component in the <script> part of a Vue component:

import Vue from "vue";
import iwPassword from "iwb-serenity-password-vue-2";

export default Vue.extend({
    components: {
        iwPassword: Password, // register <iw-password>
    },
});

3. Add the styles after an import of Serenity:

$public-path: "/public";

@import "iwb_serenity/src/scss/serenity";
@import "iwb-serenity-password-vue-2"; // this import the styles

⚠️ Projects bundled with Vite should use @import "iwb-serenity-password-vue-2/scss"; (because Vite doesn’t seem to handle sass nor style fields in libraries package.json).

Props

The attributes accepted by the component.

• Mandatory: v-model, name, label, show-password-label, hide-password-label.
• Optional: in-modal, error.

v-model (string)

Learn more about v-model in Vue’s documentation.

name (?string)

The name parameter in <input type="password" name="this-value">. It defaults to password.

autocomplete (?string)

The autocomplete parameter in <input type="password" autocomplete="this-value">. It defaults to current-password, as it’s the most common use case. For a new password or a password change, new-password is recommended.

label (string)

The displayed label of the field.

show-password-label (string)

The label of the password revealer button.

password-hidden-text (string) and password-shown-text (string)

The text announced by screen readers when the password isn’t revealed (password-hidden-text) or revealed (password-shown-text).

in-modal (?boolean)

Default value: false.

When set to true, changes the field background from white to primary-blue-llll.

error (?string)

Default value: an empty string.

When non-empty, an error message associated to the password field.

Events

You don’t need to listen to any event (@input="someAction") when using v-model.

If you still need to listent to its unique event (input), be aware that the component only emits it when its internal <input type="password"> element fires the native change event.

Typically, this happens on blur, when the field loses its focus. The component doesn’t fire an event for each key the user types.

Accessibility

A password is always a required field, so the user expects it to be required. To indicate that requirement to assistive technologies, the component is using aria-required.

The required attribute was dismissed for two reasons:

• It has accessibility flaws: when submiting a login form with an empty password, the password field is focused and the screen reader (VoiceOver) announces “please fill this field” but doesn’t announce the name of the field.
• Currently, our apps only rely on server-side validation.

The field is marked as invalid (using aria-invalid) only when an error message is provided. When it is, the error message is appended to the field accessible label (using aria-labelledby).

The password reveal button is only visible (and focusable) when the field isn’t empty. Its label never changes (“show password”), but the announcement varies when the password is shown/hidden:

• the <button> makes use of aria-pressed;
• a live region (aria-live="polite") is explicit about the state: (e.g. “The password is visible|hidden”).

More background, resources and discussions in the pull request.

Changelog

See CHANGELOG.md.

Development

1. Clone the repository:

git clone git@github.com:axel-springer-kugawana/iwb_serenity.git

2. Go to this folder:

cd iwb_serenity/packages/vue-2-password

3. Install dependencies:

npm install

4. You can help preview your changes made in /src by running the demo app:

npm run serve

You can also test the local version of the package in a local app by using the npm link feature, as described in the instructions in the root repository documentation.

Be aware that it may not work for testing the styles, and that the project that will use the local version of the package will need to update its symlinks configuration. When using vue-cli, in config.vue.js:

module.exports = {
    // many things…

    // add this:
    configureWebpack: {
        /**
         * Fix double Vue (or other packages) import when developing and
         * locally testing a component (using `npm link`) meant to be
         * packaged. A warning was printed in the browser console:
         *
         * `[Vue warn]: Invalid VNode type: Symbol(Comment)`
         *
         * https://github.com/vuejs/core/issues/2064#issuecomment-797365133
         */
        resolve: {
            symlinks: false,
            alias: {
                vue: path.resolve('./node_modules/vue')
            },
        },
    },
}

5. Ignore TypeScript errors

Though the component can be consumed by an app using TypeScript, it throws a type error while developing. We have chosen to not use class components, which is the only way to have Vue 2 packages fully compliant with TypeScript. As a workaround, the entry point still is a TypeScript file (src/index.ts) and contains a compatible component declaration.

For reference, this is the type error you can ignore:

ERROR in …/iwb_serenity/packages/vue-2-password/src/index.ts(8,7): 8:7 Type '{ props: { value: { type: StringConstructor; required: boolean; default: string; }; label: { type: StringConstructor; required: boolean; }; showPasswordLabel: { ...; }; hidePasswordLabel: { ...; }; name: { ...; }; error: { ...; }; inModal: { ...; }; }; data: () => any; computed: { ...; }; methods: { ...; }; }' is missing the following properties from type 'VueConstructor<Vue>': extend, nextTick, set, delete, and 10 more.

6. (to be documented: add tests)

7. Submit your changes by opening a pull request.

License

The iwb-serenity-password-vue-2 package is open-sourced software licensed under the MIT license.