# Dario's Speed Dial

A single-file, zero-dependency browser speed dial page.  
All settings, dials, folders, and images are stored in **localStorage** — no server, no account, no internet required to run.

---

## Table of Contents

1. [Getting Started](#getting-started)
2. [Features Overview](#features-overview)
3. [Folders](#folders)
4. [Dials](#dials)
5. [Dial Thumbnail Modes](#dial-thumbnail-modes)
6. [Search Bar](#search-bar)
7. [Clock and Date](#clock-and-date)
8. [Background Images](#background-images)
9. [Settings Panel](#settings-panel)
10. [Connectivity Monitor](#connectivity-monitor)
11. [Theme and Colors](#theme-and-colors)
12. [Import and Export](#import-and-export)
13. [Custom CSS Guide](#custom-css-guide)
14. [Keyboard Shortcuts](#keyboard-shortcuts)
15. [Localization](#localization)
16. [Storage Notes](#storage-notes)
17. [Technical Notes](#technical-notes)

---

## Getting Started

1. Save `DarioSpeedDial.html` anywhere on your computer.
2. Open it in any modern browser (Firefox, Brave, Chrome, Edge).
3. Set it as your browser's home page or new-tab page.
4. Right-click a folder or dial to edit, delete, move, or refresh it.

No installation, no dependencies, no internet connection required to use the page itself.

---

## Features Overview

| Feature | Description |
|---|---|
| Folders | Organize dials into named tabs in the top bar |
| Dials | Bookmarks displayed as thumbnail cards |
| Thumbnail Modes | Auto favicon, solid color, or custom image |
| Search Bar | Search dial names across all or current folder |
| Clock / Date | Live clock with configurable format, locale, fonts |
| Background Images | Per-element background images (page, top bar, search bar, clock, folder buttons) |
| Dark / Light theme | Toggle with one click; separate color palettes for each |
| Custom CSS | Full CSS override capability with a built-in guide |
| Export / Import | Save and restore all settings and dials as a JSON file |
| Connectivity Monitor | Detects internet outages; warns before favicon refreshes fail |
| Drag and Drop | Reorder dials and folders by dragging |
| Multi-language UI | 10 languages: English, Spanish, Hebrew, German, French, Italian, Portuguese, Russian, Greek, Arabic |
| Inline favicon and Apple touch icon | No external icon files needed |

---

## Folders

Folders appear as tabs in the top bar. Click a folder tab to switch to it.

### Adding a Folder

Click the **folder+** button (top right of the top bar) to open the Add Folder panel.  
Enter a name and click **Save**.

### Editing a Folder

Right-click a folder tab → **Edit** to open the Folder Settings panel, where you can change:

- Name
- Text color, background color, border color
- Corner radius
- Background image (for the folder tab button itself)
- Font (family, size, bold/italic/underline)

### Deleting a Folder

A folder can only be deleted if it is **empty** (contains no dials).  
Right-click an empty folder → **Delete**.

### Moving all Dials

Right-click a folder → **Move all to…** to move every dial in that folder to another folder at once.

### Reordering Folders

Drag a folder tab left or right to reorder it.

---

## Dials

Dials are bookmark cards displayed in the main grid area.

### Adding a Dial

Click the **dial+** button (top right) to open the Add Dial panel.  
Enter a URL (required) and optionally a name. If no name is given, one is generated from the URL hostname.  
Click **Save** to add with default settings, or **More Settings…** to go directly to the full Dial Settings panel.

### Quick Edit

Right-click a dial → **Edit** to open a quick Name + URL editor.  
Click **More Settings…** inside that panel to escalate to the full Dial Settings.

### Full Dial Settings

Right-click a dial → **Edit** → **More Settings…** (or right-click and choose Advanced Edit) to access:

- Name and URL
- Name text color, name background color, name background transparency
- Thumbnail border color, name border color
- Thumbnail corner radius
- Thumbnail Mode (see below)
- Name font (family, size, bold/italic/underline)
- Hover note (optional text appended to the tooltip when mouse rests on the dial)
- **Apply Default** — reset styles to the current saved default
- **Save as Default** — save the current style as the default for all new dials

### Dial Tooltip

Resting the cursor on any dial for half a second shows a tooltip containing:

- **📁 Folder name** — always shown, so you always know which folder the dial belongs to (useful especially during search, when dials from multiple folders are visible at once)
- **Note** — shown on a second line below the folder name, if a note has been set for that dial

### Deleting a Dial

Right-click a dial → **Delete**. A confirmation is required.

### Moving a Dial

Right-click a dial → **Move to…** to move it to another folder.

### Reordering Dials

Drag a dial card to a new position in the grid. The order is preserved after page reload.

---

## Dial Thumbnail Modes

Each dial can display its thumbnail in one of three modes, selectable in the Dial Settings panel:

### Auto Favicon
The thumbnail shows the website's favicon fetched automatically from Google's favicon service (`https://www.google.com/s2/favicons?domain=…&sz=128`).  
Requires an internet connection. Use **Refresh Favicon** inside Dial Settings or the context menu **Refresh Thumbnail** to re-fetch.

### Solid Color
The thumbnail shows a solid color background with the first letter of the hostname displayed over it.  
Choose any color with the color picker. No internet required.

### Custom Image
Upload any image from your computer to use as the thumbnail.  
The image is automatically resized to a maximum of **100 px wide** and encoded as a PNG for storage efficiency.

---

## Search Bar

The search bar filters dials by name in real time.

- Press **Esc** or click the **×** button to clear the search.
- The **scope button** (right side of the search bar, labelled **All** or **Folder**) toggles whether search covers all folders or only the currently active folder. This preference is saved across sessions.
- The search bar can be hidden entirely from **Settings → Other Settings → Show Search Bar**.

---

## Clock and Date

The clock in the top bar is live and updates every second.

### Clock Styles

| Style | Effect |
|---|---|
| Stretched (default) | Clock is vertically stretched by 1.2× for a distinctive look |
| Normal | Standard proportions |
| Compact | Slightly compressed vertically |

Change the style in **Settings → Clock → Clock Style**.

### Time Format

- 12-hour or 24-hour, configurable in **Settings → Clock → Time Options**.
- Optional seconds display.

### Date Format

Choices: `MM/DD/YYYY`, `DD/MM/YYYY`, `YYYY-MM-DD`, `Month D, YYYY`.  
Optional weekday name and ISO 8601 week number display.

### Locale

The locale controls how month names, weekday names, and time periods (AM/PM) are displayed.  
It is independent of the UI language — you can have English UI with Hebrew locale for Hebrew month names.

### Clock Fonts

Separate fonts for the time and date displays, configurable in **Settings → Clock**.  
Each has family, size (with unit: em, px, %, rem), bold, italic, and underline.

---

## Background Images

Background images can be set for:

| Target | Notes |
|---|---|
| Page background | Resized to max 1280 px wide, JPEG quality ~91% (≤9% quality loss) |
| Top bar | Resized to fit the top bar's actual rendered size |
| Search bar | Resized to fit the search bar's actual rendered size |
| Clock area | Resized to fit the clock container's actual rendered size |
| Folder tab buttons | Set per-folder in Folder Settings |

All images are stored in localStorage as base64 data URIs.  
Images are compressed using canvas-based JPEG encoding to minimize storage use.  
A storage warning banner appears if localStorage quota is exceeded.

### Clearing Images

Use the **Clear** button next to each image preview in the Settings panel.

---

## Settings Panel

Open with the **⚙** button in the top bar. The panel is organized into collapsible accordion sections:

| Section | Contents |
|---|---|
| **Colors** | All theme colors including rgba-capable pickers for clock BG, folders bar BG, and folder count badge |
| **Clock** | Clock colors, style, time/date format, locale, fonts |
| **Background Images** | All background image pickers |
| **Other Settings** | Search engine, search bar visibility, folder count badge, offline banner style, language |
| **Theme Tools** | Restore defaults, random theme generator, custom CSS, export/import |

### Accordion Sections

Click any section header to expand or collapse it. Section state is not saved between sessions (panels always open with the default expanded sections visible).

---

## Connectivity Monitor

The page actively monitors your internet connection in the background.

### How it works

- On page load, `navigator.onLine` is checked immediately, then a real probe is sent to a known endpoint (`https://www.gstatic.com/generate_204`) to verify actual connectivity.
- The probe runs every **15 seconds** in the background.
- The browser's built-in `online` and `offline` events are also listened to for faster reaction.

### Status Indicator

A small colored dot appears next to the ⚙ button in the top bar:

- **Green** — online
- **Red** — offline

### Offline Banner

When the connection is lost, the page can notify you in one of two ways, controlled by **Settings → Other Settings → Show Offline Banner**:

**Banner enabled (default):** a yellow bar appears below the top bar containing:

- A message explaining that favicon refresh is unavailable
- A **Set image manually** button — if a Dial Settings panel is open, this triggers a local file picker for a custom image; otherwise it shows instructions
- A **Dismiss** button to hide the banner for the current offline episode (it reappears on the next offline episode)

**Banner disabled:** instead of the persistent bar, a small slide-up toast notification appears in the bottom-right corner of the screen for 4 seconds, then fades away automatically. No persistent bar, no clutter — just a brief heads-up.

### Favicon Refresh with Connectivity Check

All thumbnail refresh operations (single dial, all in folder, all dials in all folders) check connectivity before running. If offline, the offline banner is shown and the refresh is skipped — no broken images.

### Refresh Operations

| Operation | How to trigger |
|---|---|
| Refresh one dial's thumbnail | Right-click dial → **Refresh Thumbnail** |
| Refresh all thumbnails in current folder | Right-click folder → **Refresh All Thumbnails** |
| Refresh ALL dials across all folders | Right-click folder → **Refresh ALL Dials (all folders)** |

---

## Theme and Colors

### Dark / Light Mode

Click the sun/moon button in the top bar to toggle between dark and light mode.  
Each mode has its own independent color palette — changes made in dark mode do not affect light mode colors and vice versa.

### Color Pickers

Simple colors use a standard color picker.  
Colors with transparency (clock background, folders bar background, folder count badge) use a **color picker + opacity slider** pair.

### Random Theme Generator

**Settings → Theme Tools → Generate Random** generates a random harmonious color palette for the current theme. Text colors are automatically adjusted for contrast (light text on dark backgrounds, dark text on light).

### Restore Defaults

**Settings → Theme Tools → Restore Defaults** resets all colors for the current theme to the built-in defaults.

---

## Import and Export

### Export

**Settings → Theme Tools → Export** saves all settings, folders, dials, and images to a `.json` file on your computer. This is a complete backup.

### Import

**Settings → Theme Tools → Import** loads a previously exported `.json` file. This replaces all current data.  
The import validates the file format before applying.

---

## Custom CSS Guide

**Settings → Theme Tools → Custom CSS** opens a CSS editor where you can write any CSS rules to override the default appearance.

Use `!important` to ensure your rules take effect.

### Common Selectors

```css
/* Main page background */
body { background-color: #0a0a1a !important; }

/* Top bar */
.top-bar { border-radius: 0 !important; }

/* Clock */
.time { letter-spacing: 0.1em !important; }
.date { font-size: 0.7em !important; }

/* Search box */
#search-box { border-radius: 20px !important; }

/* All folder tabs */
.folder { border-radius: 0 !important; }

/* Active (selected) folder tab */
.folder.active { font-style: italic !important; }

/* All dial cards */
.dial { opacity: 0.9; }
.dial:hover { opacity: 1; transform: scale(1.05); transition: all 0.15s; }

/* Dial thumbnail box */
.dial-thumbnail { box-shadow: 0 2px 8px rgba(0,0,0,0.4) !important; }

/* Dial name label */
.dial-name { font-size: 0.75em !important; }
```

### Targeting Specific Items

Every folder and dial element has a `data-id` attribute you can target:

```css
/* Style one specific folder tab */
.folder[data-id="abc123"] {
    background: linear-gradient(135deg, #1a237e, #4a90e2) !important;
    color: white !important;
}

/* Style all dials in a specific folder — not directly possible with CSS alone,
   but you can target by data-id on the dial card */
.dial[data-id="def456"] .dial-name {
    color: gold !important;
    font-weight: bold !important;
}

.dial[data-id="def456"] .dial-thumbnail {
    border: 2px solid gold !important;
}
```

To find a `data-id`: right-click the folder or dial, choose **Inspect** in your browser's developer tools, and look for the `data-id` attribute on the element.

### Dial Thumbnail Overlays

```css
/* Add a subtle gradient overlay to all dial thumbnails */
.dial-thumbnail::after {
    content: '';
    position: absolute;
    inset: 0;
    background: linear-gradient(to bottom, transparent 60%, rgba(0,0,0,0.4));
    border-radius: inherit;
    pointer-events: none;
}

/* Make solid-color thumbnails show only the letter, no background */
.dial-thumbnail-solid { display: none !important; }
```

### Hover Animations

```css
/* Smooth scale-up on hover */
.dial {
    transition: transform 0.15s ease;
}
.dial:hover {
    transform: scale(1.08);
}

/* Glow effect on hover */
.dial:hover .dial-thumbnail {
    box-shadow: 0 0 12px var(--highlight-color) !important;
}
```

### CSS Variables

The following CSS custom properties are available and reflect the current theme:

| Variable | Default (dark) | Description |
|---|---|---|
| `--background-color` | `#1a1a1a` | Page background |
| `--foreground-color` | `#e0e0e0` | Default text |
| `--highlight-color` | `#4a90e2` | Accent / active color |
| `--highlight-text-color` | `#ffffff` | Text on highlighted elements |
| `--panel-background-color` | `#2c2c2c` | Floating panels background |
| `--border-color` | `#444444` | Borders and dividers |
| `--time-color` | `#ffffff` | Clock time text |
| `--date-color` | `#ffffff` | Clock date text |
| `--clock-bg-color` | `rgba(44,44,44,0.1)` | Clock container background (rgba) |
| `--folders-bar-bg-color` | `rgba(44,44,44,0.1)` | Folders bar background (rgba) |
| `--folder-count-bg-color` | `rgba(74,74,30,0.8)` | Folder count badge background (rgba) |

Use them in your custom CSS:

```css
.dial-thumbnail {
    border-color: var(--highlight-color) !important;
}
```

---

## Keyboard Shortcuts

| Key | Action |
|---|---|
| `Esc` | Close any open panel, dismiss context menu |
| `Enter` | Confirm (when a panel's Save button is focused) |
| `Tab` | Navigate between form fields |

---

## Localization

The UI language is set in **Settings → Other Settings → Language**.  
The date/time locale (affects month names, weekday names, AM/PM) is set in **Settings → Clock → Locale**.

These two settings are intentionally independent — for example, you can have an English UI with a Hebrew locale (showing Hebrew month and day names in the clock).

When you change the UI language, a subtle hint appears offering to also sync the locale to match. This defaults to **off** so your locale preference is preserved.

### Supported Languages

English, Spanish, Hebrew, German, French, Italian, Portuguese, Russian, Greek, Arabic.

---

## Storage Notes

All data is stored in the browser's `localStorage` under the key `speedDialState`.

- **Limit**: typically 5–10 MB depending on browser.
- **Images** are the largest consumers. Each image is compressed before storage:
  - Page backgrounds: max 1280 px wide, JPEG ~91% quality
  - Other element backgrounds: sized to the element's actual rendered dimensions
  - Dial custom thumbnails: max 100 px wide, PNG
  - Folder tab images: max 100 px wide, PNG
- If the quota is exceeded, a warning banner appears. To free space, clear unused background images from the Settings panel.
- The **Export** function saves everything to a local file — use it as a backup before clearing data.
- **Incognito / Private windows**: localStorage is cleared when the private window closes, so your dials will not persist there.

---

## Technical Notes

- **Single file**: everything — HTML, CSS, JavaScript, inline favicon — is in one `.html` file.
- **No dependencies**: no jQuery, no frameworks, no CDN calls.
- **Favicon**: embedded as a base64 SVG data URI in the `<link rel="icon">` tag — no external icon file needed.
- **IDs**: generated using `crypto.randomUUID()` (with a `Date.now()`-based fallback) to avoid collisions.
- **State**: only persistent data (folders, dials, settings) is saved to localStorage. Transient UI state (open panels, drag state, context menu target) is kept in memory only and never persisted.
- **Font sizes**: stored as a `{sizeVal, sizeUnit}` pair (e.g. `{sizeVal: "1.2", sizeUnit: "em"}`) to allow unit-aware editing. Old single-string format is migrated automatically on first load.
- **Color storage**: rgba values are stored as separate hex + alpha pairs to make them editable with standard color pickers + range sliders. Old rgba string format is migrated automatically.
- **Connectivity probe**: uses `fetch` with `mode: 'no-cors'` against `https://www.gstatic.com/generate_204`. Any response (even opaque) counts as online. A 5-second abort timeout prevents hanging.
- **Week numbers**: ISO 8601 standard (week 1 = the week containing the first Thursday of the year).

---

*DarioSpeedDial — authored by Dario Ruggi*