# pinlocker

> A simple lock screen with PIN code for hybrid mobile app

Latest version **0.0.1-beta.3** (published 2020-10-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install pinlocker
pnpm add pinlocker
yarn add pinlocker
bun add pinlocker
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.1-beta.3 |
| Published | 2020-10-06 |
| First published | 2019-12-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | sepidar |

## Links

- npm: https://www.npmjs.com/package/pinlocker
- npm.io page: https://npm.io/package/pinlocker

## Dependencies (2)

- [@capacitor/cli](https://npm.io/package/@capacitor/cli.md) ^1.4.0
- [@capacitor/core](https://npm.io/package/@capacitor/core.md) ^1.4.0

## Recent versions

- 0.0.1-beta.3 (latest) — 2020-10-06
- 0.0.1-beta.1 (beta) — 2019-12-27
- 0.0.1-beta.2 — 2019-12-27
- 0.0.1-beta.0 — 2019-12-26

## README

# A simple lock screen with PIN code for hybrid mobile app

PinLocker is a simple PIN code inspired by [react-native-pincode]() and the api is similar to that.

PinLocker are built using the Web Components standard that work on any framework or without one.

## Installation

### Vanilla JS

- Put a script tag in the head of your html file then you can use the pinlocker anywhere:

```bash
<!DOCTYPE html>
<html lang="en">

<head>
   <script src="https://unpkg.com/pinlocker/latest/dist/pinlocker.js"></script>
</head>

<body>
   <pinlocker-app status="enter"></pinlocker-app>
</body>

</html>
```

  

### Vue

- Run `npm install pinlocker --save`

- modify 'main.js' file as belows:


```bash

import Vue from 'vue';
import App from './App.vue';

import { defineCustomElements as definePinlocker } from 'pinlocker/dist/loader';
  
Vue.config.productionTip = false;
Vue.config.ignoredElements = ['pinlocker-app'];

definePinlocker(window)

new Vue({
render: h => h(App)
}).$mount('#app');
```

### React

- Run `npm install pinlocker --save`

- modify `index.js` file as below:

```bash
import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import registerServiceWorker from './registerServiceWorker';

import { applyPolyfills, defineCustomElements } from 'pinlocker/dist/loader';  

ReactDOM.render(<App />, document.getElementById('root'));

registerServiceWorker();

applyPolyfills().then(() => {
   defineCustomElements(window);
});
```

for more information please go to https://custom-elements-everywhere.com/.

### Angular
- Run `npm install pinlocker --save`
- Including the CUSTOM_ELEMENTS_SCHEMA in the module:
```bash
import { BrowserModule } from '@angular/platform-browser';
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { AppComponent } from './app.component';
 
@NgModule({
declarations: [AppComponent],
imports: [BrowserModule, FormsModule],
bootstrap: [AppComponent],
schemas: [CUSTOM_ELEMENTS_SCHEMA],
})

export class AppModule {}
```

- Add function defineCustomElements() to your `main.ts`:
  
```bash
import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';
import { environment } from './environments/environment';
import { defineCustomElements } from 'pinlocker/dist/loader';
 
if  (environment.production) {
   enableProdMode();
}

platformBrowserDynamic().bootstrapModule(AppModule)
.catch(err => console.log(err));

defineCustomElements(window);
```

## Usage

Basic usage requires choosing between the choose, enter and locked modes.

- choose : requires the user to choose and to confirm a PIN code
- enter : requires the user to enter the PIN code he previously chose
- locked : prints a locked screen for a given time if the user failed to enter his/her PIN code too many times

`<pinlocker-app status="enter"></pinlocker-app>`

## Options

| Attribute | Description | Default |
| ------------------------------------ | ----------- | ----------- |
| `button-delete-text` | Text of the of the button used to delete a previous entry on the PIN panel | `delete` |
| `disable-lock-screen` | Boolean to disable the lock screen | `false` |
| `handle-result-enter-pin` | Function to be used to handle the PIN code entered by the user. To be used with the **`pinStatus`** props | `undefined` |
| `max-attempts` | Number of attempts the user is given before locking the application | `3` |
| `password-length` | Length of the password the user has to enter | `4` |
| `pin-status` | Status coming back to the PIN component after the **`handleResultEnterPin`** function. The status type is a value of the `PinResultStatus` enum (`initial`, `success`, `failure`, `locked`) | `undefined` |
| `status` | Indicates the mode that should be used (see _Usage_ section for the different modes available) | `undefined` |
| `stored-pin` | The PIN code previously stored with the `storePin` function | `undefined` |
| `subtitle-choose` | String used as a subtitle on the PIN code choose page | `to keep your information secure` |
| `subtitle-confirm` | String used as a subtitle on the PIN code confirmation page | `undefined` |
| `subtitle-enter` | String used as a subtitle on the PIN code enter page | `undefined` |
| `subtitle-error` | String used as a subtitle on the PIN code pages when an error occurs (wrong PIN code used for `enter` or `confirm` modes) | `Please try again` |
| `text-button-locked-page` | String to be used as text on the button in the locked application page | `Quit` |
| `text-description-locked-page` | String to be used as a description on the locked application page | `To protect your information, access has been locked for {timeLocked} minutes.` |
| `text-sub-description-locked-page` | String to be used as a subtitle on the locked application page | `Come back later and try again.` |
| `text-title-locked-page` | String to be used as a title on the locked application page | `Maximum attempts reached` |
| `time-locked` | Number of milliseconds where the application should be locked after `maxAttempts` failed attempts from the user | `300000` (5 minutes) |
| `title-attempt-failed` | String used as a title on the PIN enter page when the user enters a wrong PIN code | `Incorrect PIN Code` |
| `title-choose` | String used as a title on the PIN choose page | `1 - Enter a PIN Code` |
| `title-confirm` | String used as a title on the PIN confirm page | `2 - Confirm your PIN Code` |
| `title-confirm-failed` | String used as a title on the PIN confirm page when the user enters a wrong PIN code | `Your entries did not match` |
| `title-enter` | String used as a title on the PIN enter page | `Enter your PIN Code` |

## Events

| Event | Description | Default |
| ----------------------- | ----------- | --------------------- |
| `clickButtonLockedPage` | Function to be used when the user taps the button on the locked application page | Kills the app by throwing `Quit application` |
| `endProcessFunction` | Function to handle the end of the process | `None` |
| `finishProcess` | Function to be used when the user enters the right PIN code | Removes the values in Storage and set the status to `success` |
| `getCurrentPinLength` | Function returning the length of the current PIN code | `None` |

## Contributing

## License

## Changelog

---
_Source: https://npm.io/package/pinlocker · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._