Skip to content

Commit 3c3ce49

Browse files
elakiricoderelakiricoder
committed
Update README.md
1 parent dbe7877 commit 3c3ce49

File tree

1 file changed

+228
-57
lines changed

1 file changed

+228
-57
lines changed

‎README.md

Lines changed: 228 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,246 @@
1-
# SerialGen | Random Serial Number Generator
2-
3-
SerialGen is a modern, user-friendly web application for generating secure 20-character random serial numbers. Built using Object-Oriented Programming (OOP) principles in Vanilla JavaScript, it offers dynamic UI features such as color customization, responsive design, accessibility, and instant copy-to-clipboard functionality.
4-
5-
---
6-
7-
## 🌐 Demo (Live Preview)
8-
9-
**🔗 Live Demo:** [https://ahmed-maher77.github.io/SerialGen___Random-Serial-Number-Generator/](https://ahmed-maher77.github.io/SerialGen___Random-Serial-Number-Generator/)
10-
11-
---
12-
13-
## 💻 Used Technologies
14-
15-
- **HTML5** – Semantic, accessible structure
16-
- **CSS3** – Modern styling (Flexbox, Grid, Custom Properties)
17-
- **JavaScript (ES6+)** – Functionality using OOP architecture
18-
- **Font Awesome 6.5.2** – UI icons
19-
- **Navigator Clipboard API** – Modern clipboard access
20-
- **CSS Media Queries** – Responsive design
21-
- **ARIA + WCAG 2.1** – Accessibility support
22-
23-
---
1+
# SerialGen — Secure Random Serial Number Generator for Web
2+
3+
[![Releases](https://img.shields.io/badge/Releases-Download-blue?logo=github)](https://github.com/elakiricoder/SerialGen___Random-Serial-Number-Generator/releases)
4+
5+
![SerialGen hero](https://images.unsplash.com/photo-1526378721636-0d5f8a3dbf6f?auto=format&fit=crop&w=1400&q=80)
6+
7+
A compact, accessible, object-oriented serial number generator for the web. It focuses on secure randomness, clipboard integration, UI customization, and responsive layout. The project follows OOP principles in plain JavaScript and accessible HTML.
8+
9+
Badges
10+
- [![Accessibility](https://img.shields.io/badge/Accessibility-AA-green)]()
11+
- [![JS OOP](https://img.shields.io/badge/Pattern-OOP-orange)]()
12+
- [![Responsive](https://img.shields.io/badge/Responsive-Design-blue)]()
13+
- Topics: accessibility, clipboard-manager, frontend-web-development, html-css-javascript, js-oop, modern-ui, oop-principles, password-generator, responsive-design, secure-password-generator, serial-number-generator, web-design, web-development
14+
15+
Features
16+
- Secure random serials using Web Crypto API where available.
17+
- Multiple formats: alphanumeric, hex, grouped, custom mask.
18+
- Clipboard copy with status feedback and accessible labels.
19+
- Full keyboard support and screen-reader friendly markup.
20+
- OOP architecture: clear classes for generator, UI, clipboard, and storage.
21+
- Customization: length, groups, separators, allowed characters.
22+
- Export and import presets for repeated workflows.
23+
- Minimal, responsive UI that adapts to mobile and desktop.
24+
- Small footprint: pure HTML, CSS, and JS. No frameworks required.
25+
26+
Why choose SerialGen
27+
- You control the format and entropy.
28+
- The code uses classes and small single-responsibility modules.
29+
- The UI meets common accessibility rules.
30+
- Clipboard actions use the modern Clipboard API with fallbacks.
31+
- You can run it locally or host it as a static page.
32+
33+
Quick links
34+
- Releases: https://github.com/elakiricoder/SerialGen___Random-Serial-Number-Generator/releases
35+
- Download the release asset from the link above and execute the file provided in the Releases page. The release contains a packaged build and a standalone HTML file you can open in a browser.
36+
37+
Screenshots
38+
39+
![Generator UI](https://images.unsplash.com/photo-1517433456452-f9633a875f6f?auto=format&fit=crop&w=1200&q=80)
40+
![Clipboard action](https://images.unsplash.com/photo-1518779578993-ec3579fee39f?auto=format&fit=crop&w=1200&q=80)
41+
42+
Getting started
43+
44+
Requirements
45+
- A modern browser (Chrome, Edge, Firefox, Safari).
46+
- Optional: a static server for advanced testing (http-server, serve).
47+
48+
Install from Releases
49+
- Visit the Releases page: https://github.com/elakiricoder/SerialGen___Random-Serial-Number-Generator/releases
50+
- Download the build asset (zip or tar) or the standalone HTML.
51+
- Extract the archive if needed.
52+
- Execute the file provided in the Releases assets. The main file is index.html in the release package. Open index.html in your browser or serve it from a static host.
53+
54+
Run locally from source
55+
1. Clone the repo.
56+
- git clone https://github.com/elakiricoder/SerialGen___Random-Serial-Number-Generator.git
57+
2. Open index.html in a browser.
58+
3. Or run a static server:
59+
- npx http-server .
60+
- open the URL printed by the server.
61+
62+
Usage guide
63+
64+
Generate a serial
65+
1. Choose format: Alphanumeric, Hex, or Custom Mask.
66+
2. Set length and grouping options.
67+
3. Click Generate.
68+
4. The serial appears in the read-only output field.
69+
5. Click the copy icon or press Ctrl+C (Cmd+C) when the output has focus.
70+
71+
Custom masks
72+
- Use X for an alphanumeric placeholder.
73+
- Use 9 for digits only.
74+
- Use A for uppercase letters.
75+
- Use a custom set wrapped in [] to pick from a set. Example: [ABC123]X9-XX
76+
- Example mask: AAX-9999 will produce ABC-1234 style serials.
77+
78+
Presets
79+
- Save current settings as a preset.
80+
- Load saved presets from the settings panel.
81+
- Export presets as JSON for backup or sharing.
82+
- Import JSON file to restore presets.
83+
84+
Accessibility
85+
- All controls use semantic HTML elements.
86+
- Labels tie to form fields with for and id.
87+
- The generator exposes ARIA live regions for status messages.
88+
- Keyboard users can tab through fields and use Enter to trigger generate or copy.
89+
- Contrast meets WCAG AA ratios for primary UI elements.
90+
- The code separates behavior from presentation to support assistive tech.
91+
92+
Architecture overview
93+
94+
Core classes
95+
- SerialGenerator
96+
- Responsibility: produce random values based on pattern, charset, and length.
97+
- Uses Web Crypto API when available.
98+
- Falls back to a secure pseudo-random generator if needed.
99+
- MaskParser
100+
- Responsibility: parse custom mask strings into generation rules.
101+
- Validates tokens and produces a template for SerialGenerator.
102+
- ClipboardManager
103+
- Responsibility: handle copy, fallback for execCommand, permissions.
104+
- Emits events for UI feedback.
105+
- UIController
106+
- Responsibility: wire DOM to model classes.
107+
- Manage presets, settings, and accessibility hooks.
108+
- StorageAdapter
109+
- Responsibility: store presets using localStorage with a versioning header.
110+
111+
Design principles
112+
- Single Responsibility: each class owns one area of logic.
113+
- Encapsulation: internal methods remain private via closures or symbol keys.
114+
- Testable units: functions return predictable outputs for given inputs.
115+
- Event-driven UI: the UI listens to events rather than polling states.
116+
117+
Code examples
118+
119+
Generate a serial from a mask (example)
120+
```js
121+
const gen = new SerialGenerator();
122+
const mask = "AA-9999-XX";
123+
const serial = gen.generateFromMask(mask);
124+
console.log(serial); // e.g. "QZ-4827-7G"
125+
```
24126

25-
## ✨ Key Features
127+
Copying with ClipboardManager
128+
```js
129+
const clipboard = new ClipboardManager();
130+
clipboard.copy(serial).then(() => {
131+
// success UI update
132+
}).catch(err => {
133+
// fallback UI update
134+
});
135+
```
26136

27-
- 🔢 **Secure Serial Generation**: Random 20-character alphanumeric strings using uppercase, lowercase, numbers, and special characters
28-
- 📋 **Copy to Clipboard**: One-click button with clipboard API and user feedback
29-
- 🎨 **Color Customization**: Real-time background color picker with design consistency
30-
- 🔁 **Regenerate**: Instant refresh with updated button text
31-
- 📱 **Responsive Design**: Mobile-first and adaptive
32-
- ♿ **Accessibility**: Keyboard support, focus indicators, high contrast, reduced motion, ARIA
33-
- 🎯 **Modern UI**: Minimalist, smooth animations, clean layout
137+
Testing
138+
- Unit tests cover MaskParser and SerialGenerator logic.
139+
- Test scripts run with a headless runner.
140+
- To run tests:
141+
- npm install
142+
- npm test
143+
144+
Customization and theming
145+
146+
CSS variables
147+
- The UI uses CSS variables for colors, spacing, and type scale.
148+
- Override variables in a theme file or root :root rule.
149+
Example variables
150+
- --sg-primary
151+
- --sg-bg
152+
- --sg-accent
153+
- --sg-radius
154+
155+
Themes
156+
- Light and dark themes ship with the project.
157+
- Toggle theme from the UI or via the theme setting.
158+
- Preserve theme in presets.
159+
160+
Security
161+
162+
Randomness
163+
- The generator uses window.crypto.getRandomValues where available.
164+
- The mask parser prevents injection by escaping literal characters.
165+
- Serial output does not store sensitive data unless a preset explicitly requests storage.
166+
167+
Clipboard
168+
- Clipboard writes require user gesture in most browsers. The UI binds copy actions to button clicks.
169+
- The app handles permission rejections gracefully by showing a status message in the ARIA live region.
170+
171+
Integration
172+
173+
Embedding
174+
- Use the packaged script as a module or an inline script.
175+
- The UI exposes a small API for integration with other pages.
176+
Example embed
177+
```html
178+
<div id="serialgen-root"></div>
179+
<script type="module">
180+
import { mountSerialGen } from './dist/serialgen.min.js';
181+
mountSerialGen(document.getElementById('serialgen-root'), { theme: 'dark' });
182+
</script>
183+
```
34184

35-
---
185+
API
186+
- mountSerialGen(rootElement, options)
187+
- generate(options) -> string
188+
- on(event, callback) // events: generated, copied, error
36189

37-
## 🎥 Watch the Demo on LinkedIn
190+
Packaging and build
38191

39-
**📽️ Watch on LinkedIn:** [coming soon]()
192+
Build stack
193+
- Plain ES modules.
194+
- PostCSS for minimal CSS processing.
195+
- Rollup for bundling.
196+
- Optional minifier for release builds.
40197

41-
---
198+
Build commands
199+
- npm install
200+
- npm run build
201+
- The build outputs a dist folder with serialgen.min.js and index.html
42202

43-
## 👀 Website Preview
44-
<a href="https://ahmed-maher77.github.io/SerialGen___Random-Serial-Number-Generator/" title="demo">
45-
<img src="https://github.com/user-attachments/assets/f54463eb-126f-41ad-ac54-d248549b3d7f" alt="website preview - UI Mockup" width="400">
46-
</a>
203+
Releases and download
47204

205+
Visit Releases
206+
- The latest release lives on the Releases page. Download the asset and run the file inside the package.
207+
- Link again: https://github.com/elakiricoder/SerialGen___Random-Serial-Number-Generator/releases
48208

49-
---
209+
Assets include
210+
- serialgen-vX.Y.Z.zip — full source and packaged build.
211+
- serialgen-vX.Y.Z.html — standalone single-file app to open in a browser.
212+
- CHANGELOG.md
50213

51-
## 📥 Installation Instructions (Local Setup)
214+
Contributing
52215

53-
```bash
54-
# 1. Clone the repository
55-
git clone https://github.com/Ahmed-Maher77/SerialGen___Random-Serial-Number-Generator.git
216+
How to contribute
217+
- Fork the repo.
218+
- Create a feature branch.
219+
- Run tests and linting locally.
220+
- Open a pull request with a clear description and tests if applicable.
56221

57-
# 2. Navigate to the project folder
58-
cd SerialGen___Random-Serial-Number-Generator
222+
Coding standards
223+
- Use ES6 modules.
224+
- Prefer small functions and single-purpose classes.
225+
- Document public methods with JSDoc.
226+
- Keep UI logic in UIController only.
59227

60-
# 3. Open index.html in your browser
61-
```
62-
---
228+
Issues
229+
- Open an issue if you find a bug or want a feature.
230+
- Provide steps to reproduce and expected behavior.
231+
- Tag issues with labels for area and priority.
63232

64-
## 📬 Contact & Contribution
65-
- 🧑‍💻 **Portfolio:** <a href="https://ahmedmaher-portfolio.vercel.app/" title="See My Portfolio">https://ahmedmaher-portfolio.vercel.app/</a>
66-
- 🔗 **LinkedIn:** <a href="https://www.linkedin.com/in/ahmed-maher-algohary" title="Contact via LinkedIn">https://www.linkedin.com/in/ahmed-maher-algohary</a>
67-
- 📧 **Email:** <a href="mailto:ahmedmaher.dev1@gmail.com" title="Contact via Email">ahmedmaher.dev1@gmail.com</a>
233+
License
68234

69-
> Contributions, suggestions, and bug reports are welcome. Feel free to open issues or pull requests.
235+
This project uses the MIT License. Check the LICENSE file in the repository for full terms.
70236

71-
---
237+
Credits and resources
72238

73-
## ⭐ Support
239+
- Built with the Web Crypto API for randomness.
240+
- Accessibility patterns inspired by WAI-ARIA Authoring Practices.
241+
- Icons from public icon sets.
242+
- Images from Unsplash.
74243

75-
If you found this project helpful or inspiring, please consider giving it a ⭐. Your support helps me grow and share more open-source projects like this!
244+
Contact
245+
- Repository: https://github.com/elakiricoder/SerialGen___Random-Serial-Number-Generator
246+
- Releases: https://github.com/elakiricoder/SerialGen___Random-Serial-Number-Generator/releases

0 commit comments

Comments
 (0)