From 80dc9a391932b64ce9af0d1da7bb75e9007c26a2 Mon Sep 17 00:00:00 2001 From: grigkar Date: Mon, 13 Oct 2025 09:39:47 +0200 Subject: [PATCH] Update README.md --- README.md | 156 ++++++++++++++++++++++++++---------------------------- 1 file changed, 76 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index 87889b9..3b7ba37 100644 --- a/README.md +++ b/README.md @@ -1,108 +1,104 @@ -Masked Input Plugin for jQuery -============================== -**Notice: This project is no longer being maintained.** +# โ›ฝ Fuel Tracker โ€” MVP -I started this project [over 10 years ago](https://forum.jquery.com/topic/jquery-introduction-and-masked-input-plugin) to fill a need for a side project I was working on at the time. Nothing ever became of that side project, but this little plugin lived on. Over the years it brought me joy to stumble on sites using this thing. It was super encouraging to hear from people using it in their own products. I tried for a while to maintain it, even after I had moved away from front end web development. +A **web application** that helps drivers record fuel fill-ups and analyze consumption and costs over time. +Built as an MVP to demonstrate clean architecture, usability, and maintainability. -The time has come to officially call it quits. The web has changed(**A LOT**) and there are better things out there like [Cleave.js](https://nosir.github.io/cleave.js/). I'll leave this repo up for posterity in an archived state. Thank you to everyone who contributed to or used this plugin over the years. +--- +## ๐Ÿ“‹ Overview -Overview --------- -This is a masked input plugin for the jQuery javascript library. It allows a user to more easily enter fixed width input where you would like them to enter the data in a certain format (dates,phone numbers, etc). It has been tested on Internet Explorer, Firefox, Safari, Opera, and Chrome. A mask is defined by a format made up of mask literals and mask definitions. Any character not in the definitions list below is considered a mask literal. Mask literals will be automatically entered for the user as they type and will not be able to be removed by the user.The following mask definitions are predefined: +**Goal:** Provide individual drivers with a simple tool to: +- Record each fuel fill-up (station, fuel brand/grade, total paid, liters, odometer) +- Track history and calculate key efficiency metrics +- Compare consumption and costs by brand, period, or vehicle -* a - Represents an alpha character (A-Z,a-z) -* 9 - Represents a numeric character (0-9) -* \* - Represents an alphanumeric character (A-Z,a-z,0-9) +**Primary user:** Individual driver (multi-car supported) -### Usage -First, include the jQuery and masked input javascript files. +**Assumptions:** +- All fuel-ups are *full* fuel-ups +- Odometer values increase monotonically per vehicle +- Base units are **metric** (km, L, currency entered by user) -```html - - -``` +**Out of scope:** OCR, fleet management, trip logging, or tax reports -Next, call the mask function for those items you wish to have masked. +--- -```html -jQuery(function($){ - $("#date").mask("99/99/9999"); - $("#phone").mask("(999) 999-9999"); - $("#tin").mask("99-9999999"); - $("#ssn").mask("999-99-9999"); -}); -``` +## ๐Ÿ” Roles & Permissions -Optionally, if you are not satisfied with the underscore ('_') character as a placeholder, you may pass an optional argument to the maskedinput method. +| Role | Capabilities | +|------|---------------| +| **Anonymous** | View landing page, sign up / sign in | +| **Authenticated User** | Full CRUD on their vehicles and fuel entries, view dashboards | +| **Admin (future)** | Developer-only tools, not included in MVP | -```html -jQuery(function($){ - $("#product").mask("99/99/9999",{placeholder:" "}); -}); -``` +--- -Optionally, if you would like to execute a function once the mask has been completed, you can specify that function as an optional argument to the maskedinput method. +## โš™๏ธ Functional Requirements -```html -jQuery(function($){ - $("#product").mask("99/99/9999",{completed:function(){alert("You typed the following: "+this.val());}}); -}); -``` +### ๐Ÿ”‘ Authentication +- Sign up / Sign in with email + password +- Password policy: 8+ chars, at least 1 letter + 1 number +- Session-based authentication (cookies) -Optionally, if you would like to disable the automatic discarding of the uncomplete input, you may pass an optional argument to the maskedinput method -```html -jQuery(function($){ - $("#product").mask("99/99/9999",{autoclear: false}); -}); -``` +### ๐Ÿ‘ค User Profile & Settings +- Fields: display name, currency, unit preferences, timezone +- Unit conversions at *view time* (data stored in metric) -You can now supply your own mask definitions. -```html -jQuery(function($){ - $.mask.definitions['~']='[+-]'; - $("#eyescript").mask("~9.99 ~9.99 999"); -}); -``` +### ๐Ÿš— Vehicle Management +- Add / edit / delete vehicles +- Fields: name, make/model, year, fuel type -You can have part of your mask be optional. Anything listed after '?' within the mask is considered optional user input. The common example for this is phone number + optional extension. +### โ›ฝ Fuel Entry Management +- Add / edit / delete fill-ups +- Fields: date, odometer, station, brand, grade, liters, total, notes +- Validation: no negative or zero values, odometer > previous -```html -jQuery(function($){ - $("#phone").mask("(999) 999-9999? x99999"); -}); -``` +### ๐Ÿ“Š Derived Metrics +- Distance since last fill-up +- Price per liter +- Efficiency: **L/100km** or **MPG** +- Cost per km/mi +- Rolling averages (30 days) and all-time stats -If your requirements aren't met by the predefined placeholders, you can always add your own. For example, maybe you need a mask to only allow hexadecimal characters. You can add your own definition for a placeholder, say 'h', like so: `$.mask.definitions['h'] = "[A-Fa-f0-9]";` Then you can use that to mask for something like css colors in hex with a `mask "#hhhhhh"`. +### ๐Ÿ“ˆ Dashboards +- Overview cards: avg. consumption, total spend, distance, cost per km +- Line charts: cost per liter and consumption over time +- Brand/grade comparison table -```html -jQuery(function($){ - $("#phone").mask("#hhhhhh"); -}); -``` +--- +## ๐Ÿงฑ Non-Functional Requirements -By design, this plugin will reject input which doesn't complete the mask. You can bypass this by using a '?' character at the position where you would like to consider input optional. For example, a mask of "(999) 999-9999? x99999" would require only the first 10 digits of a phone number with extension being optional. +- Password hashing (strong one-way) +- HTTPS + Secure cookies +- User data isolation +- Pages render < 2s on broadband +- DB queries (โ‰ค5k entries) complete < 500ms +- GDPR: data export (CSV) & delete on request +- Supports latest Chrome (desktop + mobile) +--- -Getting the bits ----------------- -We generally recommend that you use [bower](http://bower.io) to install jquery.maskedinput plugin. +## ๐Ÿงฉ Tech Stack - $ bower install --save jquery.maskedinput +| Layer | Technology | +|-------|-------------| +| **Frontend** | ReactJS or Angular 2+, responsive design | +| **Backend** | Java (Spring Boot) / Node.js (NestJS) / .NET | +| **Database** | PostgreSQL | +| **DevOps** | Docker, docker-compose | +| **Migrations** | Liquibase (or equivalent) | +--- -Setting up your Developer Environment -------------------------------------- -jQuery Masked Input uses [NodeJS](http://www.nodejs.org) and [GruntJS](http://www.gruntjs.com) as it's developer platform and build automation tool. +## ๐Ÿงช Definition of Done -To get your environment setup correctly, you'll need nodejs version 0.8.25 or greater installed. You'll also need to install the grunt command line tool: +โœ… All MVP screens implemented: +Landing, Sign Up/In, Dashboard, Vehicle Management, Fill-Up Form, History, Statistics, Settings, Legal, Error Page - $ sudo npm install -g grunt-cli - -Once node is installed on your system all that you need to do is install the developer dependencies and run the grunt build: - - $ npm install - $ grunt - -All of the tests for jQuery Masked Input are run using the [jasmine](http://jasmine.github.io/) test runner. +โœ… Core flows covered by integration tests +โœ… Validation, performance & data isolation verified +โœ… Runs after clean clone: +```bash +git clone +docker compose up