# OTS Signs Theme — Copilot Instructions

Custom Xibo CMS theme for OTS Signs digital signage service. Built with Twig templates, vanilla CSS, and vanilla JS. No build pipeline — all assets are inlined at runtime.

## Architecture

- **Template engine**: Twig, inheriting from Xibo core's `base.twig`
- **Entry point**: `ots-signs/views/authed.twig` — wraps all authenticated pages (sidebar + topbar + content)
- **CSS delivery**: CSS files are **inlined** inside `<style nonce="...">` tags via `theme-javascript.twig`, not served as static files. This is intentional — it avoids MIME routing issues under the `custom/` path and ensures CSP nonce compliance.
- **JS delivery**: Same inline strategy via `theme-scripts.twig`
- **Config**: `ots-signs/config.php` — sets theme name, URLs, feature flags

### Twig inheritance
```
base.twig (Xibo core)
  ├── authed.twig           ← most pages extend this
  │   ├── dashboard-icon-page.twig
  │   ├── layout-page.twig
  │   └── [40+ admin page templates]
  └── login.twig
```

Partials included in `authed.twig`: `authed-sidebar.twig`, `authed-topbar.twig`, `authed-user-menu.twig`, `authed-notification-drawer.twig`

## Key Xibo Template APIs

These are available in all authenticated Twig templates:

```twig
{# Permission-gated rendering #}
{% if currentUser.featureEnabled("layout.view") %}...{% endif %}

{# User preferences #}
{% set navPos = currentUser.getOptionValue("navigationMenuPosition", "vertical") %}

{# Theme helpers #}
{{ theme.uri("css/override.css") }}
{{ theme.getSetting("DEFAULT_VALUE", fallback) }}
{{ url_for("routeName") }}
{{ trans("string") }}
```

## CSS Architecture

Primary file: `ots-signs/css/override.css`

- Primary color: `#e87800` (orange), exposed as `--primary-color`
- Dark background: `#0f172a`, surface: `#1e293b`
- Sidebar: 256px expanded / 64px collapsed (icon-only), controlled via CSS vars
- `override-dark.css` handles component-level dark mode, floating menus, DataTable contrast

Do **not** add a build step (Sass, PostCSS, etc.) without first discussing it — the inline delivery mechanism requires plain CSS.

## JS Conventions

Single file: `ots-signs/js/theme.js` (440+ lines)

- IIFE pattern — no module bundler
- Uses `localStorage` for theme (`ots-theme`) and sidebar state (`ots-sidebar-collapsed`)
- MutationObserver watches for Xibo's layout editor modal, sets `body.ots-playlist-editor-active`
- Mobile breakpoint: `768px`

## Deployment

Theme lives at: `web/theme/custom/otssigns-beta/` inside the Xibo CMS installation.
The `view_path` in `config.php` must point to the absolute path of the `views/` directory.

## Common UI Patterns

| Pattern | Key class/element |
|---------|------------------|
| Icon dashboard cards | `.icon-dash-card` with `--blue`, `--green`, `--purple`, `--teal` color vars |
| Data grids | `.XiboGrid` wrapper → DataTables (managed by Xibo core) |
| Filter panels | `.XiboFilter` with tab-based advanced filter |
| Page header | `.page-header` with `<h1>` + subtitle |
| Toast/alerts | Bootstrap `.alert-danger/warning/success/info` |
| Forms | `inline.*()` macro system from Xibo core |

## What This Repo Does NOT Have

- No `package.json`, no npm/yarn/pnpm
- No webpack, Vite, Gulp, or Parcel
- No TypeScript — plain JS only
- No PHP unit tests in this repo (Xibo core testing is separate)
- No CI/CD config

Don't suggest adding any of the above unless the user explicitly asks.