app.js Function Reference for PunctuOwlity Web

app.js contains all client-side application logic for the PunctuOwlity web app and is loaded on every page via a <script src="app.js"> tag at the bottom of each HTML file’s <body>. Shared setup — logo injection, back-button wiring, password-toggle listeners, and the topbar menu — runs unconditionally on every page. Page-specific logic (event rendering, form submission handlers, and SMS preference routing) is gated behind checks on document.body.dataset.page, which is set as a data-page attribute in each HTML file.

Because app.js is shared by all pages, every function and constant defined at the top level is available in every page context. The events grid logic is guarded by if(document.body.dataset.page === 'main') and the add/edit form logic by if(document.body.dataset.page === 'add'); these are the only explicit dataset.page checks in the file. Form handlers on other pages (login, sign-up) attach via optional chaining (?.addEventListener) so they safely no-op on pages where the element is absent.

Event Storage

`getEvents`

const getEvents = () => { ... }

Reads the saved events array from localStorage. If the key is missing, the stored value is not a valid JSON array, or any exception is thrown during parsing, the function falls back to the built-in seedEvents array. Every record — whether loaded from storage or from the seed — is passed through normalizeEvent before being returned. Returns: Event[] — a normalized array of event objects ready for rendering.

`saveEvents`

const saveEvents = e => localStorage.setItem('punctuowlity-events', JSON.stringify(e))

Serializes the provided events array to JSON and writes it to localStorage under the key 'punctuowlity-events'. No validation is performed; callers are responsible for passing a well-formed array of event objects.

Event[]

required

The full array of event objects to persist. The previous value is overwritten entirely.

`normalizeEvent`

const normalizeEvent = event => { ... }

Transforms a raw or partially-formed event object into a fully normalized event. This function is the single source of truth for all display-ready field values. It is called on every event that passes through getEvents. Note that the add-event.html submit handler builds its item object manually rather than delegating to normalizeEvent; the resulting object is stored directly via saveEvents. The transformation steps are applied in order:

Show Step 1 — Resolve fullDate

The raw date string is read from event.fullDate or event.date. Two formats are accepted:

YYYY-MM-DD (regex /^\d{4}-\d{2}-\d{2}$/) — used as-is.
MM/DD/YYYY (regex /^\d{2}\/\d{2}\/\d{4}$/) — split on / and reassembled as YYYY-MM-DD.

A Date object is constructed as new Date($T00:00:00) (local midnight, avoiding timezone shifts). If the date is unparseable, valid is set to false and derived fields fall back to "---" and "00".

Show Step 2 — Resolve time display

rawTime is read from event.rawTime or event.time. If it matches /^\d{1,2}:\d{2}$/, it is converted to a 12-hour display string:

Suffix: hours ≥ 12 → "PM", otherwise "AM".
Hour: hours % 12 || 12, zero-padded to two digits.
Result format: "HH:MMsuffix" — e.g. "06:30PM", "01:30PM".

If rawTime is an empty string or does not match the pattern, displayTime is set to "ALL DAY".

Show Step 3 — Auto-detect category

If event.category is not set, the lowercased title is tested against keyword patterns:

"birthday" → category "birthday"
/(appointment|dentist|dental|doctor)/ → category "appointment"
/(trip|travel|vacation)/ → category "trip"
No match → category "general"

Existing category values are always preserved.

Show Step 4 — Build return object

The function spreads the original event and overwrites all derived fields:

id → String(event.id || Date.now())
day → parsed.toLocaleDateString('en-US', { weekday: 'short' }).toUpperCase() or event.day || "---"
date → zero-padded day number from parsed, or event.date zero-padded, or "00"
fullDate → resolved ISO string
rawTime → normalized 24-hour string (empty for all-day)
time → 12-hour display string or "ALL DAY"
title → String(event.title || '')
category → resolved category string
alert → Boolean(event.alert)

Returns: A fully normalized Event object with all fields populated.

User / Account Storage

User records are stored in both localStorage and sessionStorage so that accounts survive browser restarts while also being available in private-browsing sessions where localStorage may be restricted.

`getUsers`

const getUsers = () => accountStorage.get()

Iterates the available storage backends (localStorage first, then sessionStorage) and returns the first array it successfully parses from the 'punctuowlity-users' key. Returns an empty array if no valid data is found in any storage. Returns: User[] — the array of registered user objects, or [] if none exist.

`saveUsers`

const saveUsers = users => accountStorage.set(users)

Serializes the users array to JSON and writes it to every available storage backend. Succeeds even if only one backend accepts the write.

users

User[]

required

The complete array of user objects to persist. Replaces any previously stored value.

Returns: boolean — true if at least one storage backend accepted the write; false if all writes failed (e.g. storage quota exceeded in all backends).

UI Helpers

`toast`

const toast = message => { ... }

Creates a transient notification element with the CSS class "toast" and appends it to document.body. Any existing .toast element is removed before the new one is inserted, so rapid successive calls never stack.

message

string

required

The text content to display in the notification. Rendered as textContent, not HTML.

The toast lifecycle:

Element is created and appended.
requestAnimationFrame triggers the "show" CSS class to start the entrance transition.
After 2400 ms, the "show" class is removed to start the exit transition.
After an additional 250 ms, the element is removed from the DOM.

Example calls from the application:

toast('Event Deleted');
toast('Event Added');
toast('Event Updated');
toast('Passwords do not match!');
toast('Invalid Username or Password');
toast('Account Created Successfully');

`icon`

const icon = name => `<svg aria-hidden="true"><use href="assets/icons.svg#${name}"/></svg>`

Returns an inline SVG string that references a symbol from the shared sprite sheet at assets/icons.svg. The aria-hidden="true" attribute ensures the icon is invisible to screen readers (all interactive elements provide their own aria-label).

name

string

required

The symbol ID within assets/icons.svg. Examples used in the application: "back", "search", "add-alarm", "edit", "delete", "alarm-on", "alarm-off".

Returns: string — an SVG HTML string suitable for use with innerHTML or insertAdjacentHTML.

Seed Events

The seedEvents constant is the fallback data set used when localStorage contains no valid events. All four objects are fully pre-normalized.

const seedEvents = [
  {
    id: 'project',
    day: 'SAT',
    date: '05',
    fullDate: '2025-04-05',
    rawTime: '',
    title: 'Project Two Due',
    time: 'ALL DAY',
    category: 'all',
    alert: false
  },
  {
    id: 'birthday',
    day: 'SAT',
    date: '12',
    fullDate: '2025-04-12',
    rawTime: '18:30',
    title: "Nich's Birthday",
    time: '06:30PM',
    category: 'birthday',
    alert: true
  },
  {
    id: 'dentist',
    day: 'MON',
    date: '14',
    fullDate: '2025-04-14',
    rawTime: '13:30',
    title: 'Dentist',
    time: '01:30PM',
    category: 'appointment',
    alert: false
  },
  {
    id: 'wedding',
    day: 'SUN',
    date: '20',
    fullDate: '2025-04-20',
    rawTime: '15:00',
    title: "Jessica's Wedding",
    time: '03:00PM',
    category: 'trip',
    alert: false
  }
];

Storage Keys Reference

The following table lists every key used by app.js across localStorage and sessionStorage.

Key	Storage type	Value type	Purpose
`punctuowlity-events`	`localStorage`	JSON array of `Event` objects	Persists all user-created events between sessions
`punctuowlity-users`	`localStorage` + `sessionStorage`	JSON array of `User` objects	Stores registered user accounts
`punctuowlity-authenticated`	`sessionStorage`	String `"true"`	Tracks whether the current session is authenticated; cleared when the tab closes
`punctuowlity-sms`	`localStorage`	String `"allowed"` or `"denied"`	Records the user’s SMS/notification preference from `sms.html`; absence triggers a redirect to `sms.html`
`punctuowlity-notified-{id}-{date}`	`sessionStorage`	String `"true"`	Prevents duplicate notifications for the same event on the same day

Get Started

Core Features

Architecture & Data

Reference

app.js Function Reference for PunctuOwlity Web

Event Storage

`getEvents`

`saveEvents`

`normalizeEvent`

User / Account Storage

`getUsers`

`saveUsers`

UI Helpers

`toast`

`icon`

Seed Events

Storage Keys Reference

Build docs developers (and LLMs) love

Get Started

Core Features

Architecture & Data

Reference

Documentation Index

​Event Storage

​getEvents

​saveEvents

​normalizeEvent

​User / Account Storage

​getUsers

​saveUsers

​UI Helpers

​toast

​icon

​Seed Events

​Storage Keys Reference

Build docs developers (and LLMs) love

Event Storage

`getEvents`

`saveEvents`

`normalizeEvent`

User / Account Storage

`getUsers`

`saveUsers`

UI Helpers

`toast`

`icon`

Seed Events

Storage Keys Reference