unraid-glass/CLAUDE.md

# Unraid Glass — visionOS Glassmorphism Theme

## Project
Custom CSS + JS theme for Unraid 7.2.3 WebGUI. B&W mountain wallpaper with frosted glass cards, collapsible sidebar, dashboard individual glass cards.

**Gitea:** https://git.xtrm-lab.org/jazzymc/unraid-glass
**Local:** `~/xtrm/unraid-glass/`

## Files

| File | Purpose | Deploy path (persistent) | Deploy path (live) |
|------|---------|--------------------------|---------------------|
| `style.css` | Main CSS theme | `/boot/config/plugins/custom.css/style.css` | `/usr/local/emhttp/plugins/custom.css/style.css` |
| `sidebar.js` | Sidebar toggle + search overlay | `/boot/config/plugins/custom.css/assets/sidebar.js` | `/usr/local/emhttp/plugins/custom.css/assets/sidebar.js` |

## Deployment

Both files must be deployed to TWO paths — persistent (survives reboot) and live (active now):
```bash
scp -i ~/.ssh/id_ed25519_unraid -P 422 style.css root@192.168.10.20:/boot/config/plugins/custom.css/style.css
scp -i ~/.ssh/id_ed25519_unraid -P 422 style.css root@192.168.10.20:/usr/local/emhttp/plugins/custom.css/style.css
scp -i ~/.ssh/id_ed25519_unraid -P 422 sidebar.js root@192.168.10.20:/boot/config/plugins/custom.css/assets/sidebar.js
scp -i ~/.ssh/id_ed25519_unraid -P 422 sidebar.js root@192.168.10.20:/usr/local/emhttp/plugins/custom.css/assets/sidebar.js
```

JS injection is handled by `CustomJS_Loader.page` on the server (persisted via `/boot/config/go`).

## Unraid Sidebar DOM Structure

```
#menu (position: fixed — Unraid's default, DO NOT override)
├── #sidebar-logo (injected by sidebar.js — absolute positioned)
├── #sidebar-toggle-btn (injected by sidebar.js — absolute positioned)
└── #nav-block (position: absolute; top:0; bottom:12px; width:100% — Unraid's default)
    ├── .nav-tile (main nav items — block flow)
    │   └── .nav-item > a (display: inline-flex — Unraid's default)
    │       ├── ::before (icon via font-family: docker-icon, fontawesome, unraid)
    │       ├── bare text node (page name, not wrapped in span)
    │       ├── <b> (only on utility items, display: none in our CSS)
    │       └── <span> (only on utility items, display: none in collapsed)
    └── .nav-tile.right (utility nav items)
        └── .nav-item.CLASSNAME.util > a
            ├── ::before (icon code from page Code= property)
            ├── <b class="icon-u-XXX system"> (icon from page Icon= property)
            └── <span>Label</span>
```

## Critical CSS Lessons

### DO NOT override `position` on `#menu`
Unraid sets `position: fixed` on `#menu`. Overriding with `position: relative` causes the sidebar to collapse and disappear.

### DO NOT override `display` on `.nav-item a`
Unraid sets `display: inline-flex` on `.Theme--sidebar .nav-item a`. Fighting this with `display: grid` or `display: block` doesn't reliably work. Instead, work WITH `inline-flex`:
- Center inline elements via `text-align: center` on parent `.nav-item`
- Center icon via `position: absolute; left: 50%; top: 50%; transform: translate(-50%, -50%)` on `::before`

### `backdrop-filter` creates a containing block
`backdrop-filter` on `#menu` creates a new containing block for `position: fixed` descendants. This means `position: fixed` inside the sidebar is relative to `#menu`, NOT the viewport. The search popup must be moved to `document.body` via JS to escape this.

### Work WITH `#nav-block`, don't replace it
Unraid's `#nav-block` has `position: absolute; top: 0; bottom: 12px; width: 100%; overflow-y: scroll`. Only override `top` (to clear logo+toggle space) and `padding-left`. Don't add flex/grid layout.

### Utility items have DOUBLE icons
Utility `.nav-item` elements have BOTH a `::before` pseudo-element (from page `Code=` property) AND a `<b>` HTML element (from page `Icon=` property). Hide `<b>` with `.nav-item a > * { display: none }`.

### `font-size: 0` for hiding bare text nodes
Main nav items have bare text nodes (not wrapped in `<span>`). CSS `display: none` can't target text nodes. Use `font-size: 0` on the `a` element, then explicit `font-size` on `::before`.

### `gap` affects invisible flex items
Even with `font-size: 0`, text nodes are still flex items. With `gap: 25px` (Unraid default), invisible text creates spacing. Override `gap: 0` in collapsed mode.

## Icon Fonts on Unraid

| Font | Family name | Used by |
|------|-------------|---------|
| Unraid icons | `unraid` | `icon-u-*` classes, utility nav `::before` (thicker strokes) |
| Font Awesome 4 | `FontAwesome` | `.fa` classes, single weight only |
| Docker icons | `docker-icon` | Docker page nav icon |
| Combined | `docker-icon, fontawesome, unraid` | Main nav `::before` (set by Unraid CSS) |

Utility nav `::before` icons use the `unraid` font which has heavier strokes. We replace them with FontAwesome equivalents for consistent thin appearance.

## Utility Button Pages

| Class name | Title | FA4 replacement |
|------------|-------|-----------------|
| `gui_search` | Search | `\f002` |
| `LanguageButton` | Switch Language | `\f0ac` |
| `LogoutButton` | Logout | `\f08b` |
| `TerminalButton` | Terminal | `\f120` |
| `BrowseButton` | File Manager | `\f115` |
| `FeedbackButton` | Feedback | `\f075` |
| `InfoButton` | Info | `\f05a` |
| `LogButton` | Log | `\f0f6` |
| `HelpButton` | Help | `\f059` |
| `LockButton` | Lock/Unlock | `\f09c` (no page Code=, needs manual ::before) |

## Search Overlay

The `dynamix.gui.search` plugin uses hover-trigger in sidebar theme. We replace it with:
- Click-trigger on the search nav-item
- `gui_search()` creates `#guiSearchBoxSpan` inside the sidebar
- JS moves it to `document.body` (escapes backdrop-filter containing block)
- Backdrop overlay with blur
- Cmd+K / Ctrl+K keyboard shortcut
- Escape to close

## Wallpaper

Place wallpaper at `/boot/config/plugins/custom.css/assets/wallpaper.jpg` — accessible at `/custom/wallpaper.jpg`.