refactor: move frontend/ to examples/frontend/

The Lit + Vite HOMECORE web UI is an example consumer of the
sensing stack, not a top-level deliverable — relocate it under
examples/ alongside the other sensor and dashboard demos.

Add an entry to examples/README.md so it's discoverable.

Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv
2026-05-27 12:20:49 -04:00
parent 224689a5bc
commit 04f205a05e
26 changed files with 14 additions and 0 deletions
@@ -0,0 +1,194 @@
/**
* `<hc-app-shell>` — top-level layout: sticky header + horizontal sidenav + content slot.
* Page shell mirrors cognitum-v0's appbar + wrap layout (ADR-131 §3).
*/
import { LitElement, html, css } from 'lit';
import { customElement, property, state } from 'lit/decorators.js';
export interface NavItem {
id: string;
label: string;
/** Raw SVG string for the icon */
iconSvg?: string;
}
const DEFAULT_NAV: NavItem[] = [
{ id: 'dashboard', label: 'Dashboard' },
{ id: 'states', label: 'States' },
{ id: 'services', label: 'Services' },
{ id: 'settings', label: 'Settings' },
];
@customElement('hc-app-shell')
export class AppShell extends LitElement {
@property({ type: String }) locationName = 'HOMECORE';
@property({ type: String }) version = '0.1.0';
@property({ type: Array }) navItems: NavItem[] = DEFAULT_NAV;
@state() private activeId = 'dashboard';
static styles = css`
:host { display: block; min-height: 100dvh; background: var(--hc-bg, #0b0e13); }
/* ── Appbar ── */
.appbar {
position: sticky;
top: 0;
z-index: 50;
background: hsl(220 25% 6% / 0.9);
backdrop-filter: blur(8px);
-webkit-backdrop-filter: blur(8px);
border-bottom: 1px solid hsl(220 15% 18% / 0.8);
display: flex;
align-items: center;
gap: 1rem;
padding: 0 1.25rem;
height: 3.25rem;
}
.brand {
display: flex;
align-items: center;
gap: 0.5rem;
font-family: var(--hc-font-display, 'Outfit', system-ui, sans-serif);
font-weight: 600;
font-size: 0.9375rem;
color: var(--hc-text, #e6eaee);
white-space: nowrap;
flex-shrink: 0;
}
.brand-icon {
width: 32px;
height: 32px;
border-radius: 0.4rem;
background: var(--hc-primary, #19d4e5);
display: flex;
align-items: center;
justify-content: center;
color: var(--hc-primary-fg, #0b0e13);
font-size: 1rem;
font-weight: 700;
}
.nav {
display: flex;
align-items: center;
gap: 0.25rem;
overflow-x: auto;
scrollbar-width: none;
flex: 1;
mask-image: linear-gradient(to right, black calc(100% - 24px), transparent);
}
.nav::-webkit-scrollbar { display: none; }
.nav-link {
position: relative;
display: inline-flex;
align-items: center;
gap: 0.4rem;
padding: 0.4rem 0.7rem;
border-radius: 0.4rem;
font-family: var(--hc-font-display, 'Outfit', system-ui, sans-serif);
font-size: 0.8125rem;
font-weight: 500;
color: var(--hc-text-muted, #7b899d);
background: transparent;
border: none;
cursor: pointer;
white-space: nowrap;
transition: color 150ms, background 150ms;
}
.nav-link:hover {
color: var(--hc-text, #e6eaee);
background: hsl(220 20% 14%);
}
.nav-link:focus-visible {
outline: 2px solid hsl(185 80% 50% / 0.6);
outline-offset: 1px;
}
.nav-link:active { transform: translateY(1px); }
.nav-link.active { color: var(--hc-primary, #19d4e5); }
.nav-link.active::after {
content: '';
position: absolute;
bottom: -2px;
left: 0.7rem;
right: 0.7rem;
height: 2px;
background: var(--hc-primary, #19d4e5);
border-radius: 9999px;
}
.version-chip {
font-family: var(--hc-font-mono, 'JetBrains Mono', monospace);
font-size: 0.6875rem;
color: var(--hc-text-muted, #7b899d);
white-space: nowrap;
flex-shrink: 0;
}
/* ── Main content ── */
main {
max-width: 1400px;
margin-inline: auto;
padding-inline: 1.25rem;
padding-block: 1.5rem;
}
/* ── Footer ── */
footer {
border-top: 1px solid hsl(220 15% 18%);
text-align: center;
padding: 1rem 1.25rem;
font-family: var(--hc-font-mono, 'JetBrains Mono', monospace);
font-size: 0.75rem;
color: var(--hc-text-muted, #7b899d);
}
`;
private onNavClick(id: string) {
this.activeId = id;
this.dispatchEvent(new CustomEvent('hc-navigate', { detail: { id }, bubbles: true, composed: true }));
}
render() {
return html`
<header class="appbar" part="appbar">
<div class="brand">
<div class="brand-icon" aria-hidden="true">H</div>
${this.locationName}
</div>
<nav class="nav" aria-label="Primary navigation">
${this.navItems.map(item => html`
<button
class="nav-link ${this.activeId === item.id ? 'active' : ''}"
@click=${() => this.onNavClick(item.id)}
aria-current=${this.activeId === item.id ? 'page' : 'false'}
>${item.label}</button>
`)}
</nav>
<span class="version-chip">v${this.version}</span>
</header>
<main part="content">
<slot></slot>
</main>
<footer part="footer">
HOMECORE &mdash; ${this.locationName} &mdash; v${this.version}
</footer>
`;
}
}
declare global {
interface HTMLElementTagNameMap {
'hc-app-shell': AppShell;
}
}
@@ -0,0 +1,259 @@
/**
* `<hc-entity-form>` — create / edit form for a single entity.
*
* Props:
* .entityId — pre-populated when editing; empty for create
* .state — pre-populated state value
* .attributes — pre-populated JSON object
* .editing — true to lock entity_id (HA wire-compat doesn't rename)
*
* Emits:
* hc-entity-submit detail: { entity_id, state, attributes }
* hc-entity-cancel
*
* Validation (client-side; backend validates again):
* - entity_id matches /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/
* - state is non-empty
* - attributes parses as a JSON object (not array, not scalar)
*/
import { LitElement, html, css } from 'lit';
import { customElement, property, state } from 'lit/decorators.js';
const ENTITY_ID_RE = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/;
/**
* Known Home Assistant domain prefixes. We don't reject unknown domains
* (the API accepts any matching the regex), but unknown ones get a
* warning so the operator sees what's standard. Add new domains here
* as integrations land.
*/
const KNOWN_DOMAINS = new Set([
'sensor', 'binary_sensor', 'switch', 'light', 'climate', 'cover',
'fan', 'media_player', 'lock', 'camera', 'vacuum', 'humidifier',
'water_heater', 'scene', 'script', 'automation', 'input_boolean',
'input_number', 'input_text', 'input_select', 'input_datetime',
'person', 'device_tracker', 'zone', 'sun', 'weather', 'calendar',
'remote', 'siren', 'select', 'number', 'text', 'button',
'homeassistant', 'homecore', 'group', 'notify', 'tts', 'alarm_control_panel',
]);
type FieldValidity = { ok: true } | { ok: false; level: 'err' | 'warn'; msg: string };
function validateEntityId(id: string): FieldValidity {
const trimmed = id.trim();
if (!trimmed) return { ok: false, level: 'err', msg: 'required' };
if (!ENTITY_ID_RE.test(trimmed)) {
return {
ok: false,
level: 'err',
msg: 'must match domain.snake_case (lowercase, digits, underscores)',
};
}
const domain = trimmed.split('.')[0]!;
if (!KNOWN_DOMAINS.has(domain)) {
return {
ok: false,
level: 'warn',
msg: `unknown domain "${domain}" — HA-standard domains include sensor / light / switch / binary_sensor / climate`,
};
}
return { ok: true };
}
function validateState(s: string): FieldValidity {
if (!s.trim()) return { ok: false, level: 'err', msg: 'required' };
return { ok: true };
}
function validateAttrs(raw: string): FieldValidity {
if (!raw.trim()) return { ok: true }; // empty = {}
try {
const parsed = JSON.parse(raw);
if (typeof parsed !== 'object' || Array.isArray(parsed) || parsed === null) {
return { ok: false, level: 'err', msg: 'must be a JSON object (not array, not scalar)' };
}
return { ok: true };
} catch (e) {
return { ok: false, level: 'err', msg: `JSON parse: ${e instanceof Error ? e.message : String(e)}` };
}
}
@customElement('hc-entity-form')
export class EntityForm extends LitElement {
@property({ type: String }) entityId = '';
@property({ type: String }) state = '';
@property({ type: Object }) entityAttrs: Record<string, unknown> = {};
@property({ type: Boolean }) editing = false;
@state() private _attrs = '';
@state() private _err: string | null = null;
/** Per-field live validity. `null` = haven't typed yet (no decoration). */
@state() private _idValid: FieldValidity | null = null;
@state() private _stateValid: FieldValidity | null = null;
@state() private _attrsValid: FieldValidity | null = null;
static styles = css`
:host { display: block; font-family: var(--hc-font-sans, 'Outfit', system-ui, sans-serif); color: var(--hc-text, #e6eaee); }
label { display: block; margin: 12px 0 4px; font-size: 12px; color: var(--hc-text-muted, #7b899d); }
input, textarea {
width: 100%; box-sizing: border-box;
padding: 8px 10px; background: hsl(220 25% 10%);
border: 1px solid var(--hc-border, #2a323e); border-radius: 6px;
color: var(--hc-text, #e6eaee);
font-family: var(--hc-font-mono, 'JetBrains Mono', monospace);
font-size: 13px;
}
input:focus, textarea:focus { outline: 2px solid hsl(185 80% 50% / 0.5); border-color: var(--hc-primary, #19d4e5); }
input[disabled] { opacity: 0.5; cursor: not-allowed; }
input.invalid, textarea.invalid { border-color: hsl(0 60% 50%); }
input.warn, textarea.warn { border-color: hsl(38 80% 55%); }
.field-status { font-size: 11px; margin-top: 4px; display: flex; align-items: center; gap: 6px; }
.field-status.ok { color: hsl(150 60% 55%); }
.field-status.err { color: hsl(0 70% 70%); }
.field-status.warn { color: hsl(38 80% 65%); }
.field-status .sigil { display: inline-block; width: 12px; text-align: center; font-weight: 700; }
button.primary[disabled] { background: hsl(220 15% 20%); color: var(--hc-text-muted, #7b899d); border-color: var(--hc-border, #2a323e); cursor: not-allowed; }
textarea { min-height: 90px; resize: vertical; }
.hint { font-size: 11px; color: var(--hc-text-muted, #7b899d); margin-top: 4px; }
.err { margin-top: 10px; padding: 10px; border: 1px solid #b35a5a; border-radius: 6px; background: hsl(0 35% 12%); color: #f0c0c0; font-size: 12px; }
button {
padding: 8px 16px;
border: 1px solid var(--hc-border, #2a323e);
border-radius: 6px;
background: hsl(220 25% 14%);
color: var(--hc-text, #e6eaee);
font-size: 13px;
font-weight: 500;
cursor: pointer;
font-family: inherit;
}
button.primary { background: var(--hc-primary, #19d4e5); color: var(--hc-primary-fg, #0b0e13); border-color: var(--hc-primary, #19d4e5); font-weight: 600; }
button:hover { background: hsl(220 20% 18%); }
button.primary:hover { background: hsl(185 80% 55%); }
`;
protected updated(changed: Map<string, unknown>): void {
if (changed.has('entityAttrs')) {
this._attrs = JSON.stringify(this.entityAttrs, null, 2);
}
}
/** Allow the host (Dashboard) to surface a server-side error inline. */
public setSubmitError(msg: string | null): void {
this._err = msg;
}
/** True iff every field is valid (warnings are OK, errors block). Public so the host can bind a disabled state on the submit button. */
public isValid(): boolean {
const checks = [
validateEntityId(this.entityId),
validateState(this.state),
validateAttrs(this._attrs),
];
return !checks.some((c) => !c.ok && c.level === 'err');
}
private _onIdInput(v: string) {
this.entityId = v;
this._idValid = validateEntityId(v);
}
private _onStateInput(v: string) {
this.state = v;
this._stateValid = validateState(v);
}
private _onAttrsInput(v: string) {
this._attrs = v;
this._attrsValid = validateAttrs(v);
}
private _statusLine(label: string, v: FieldValidity | null) {
if (v === null) return html``;
if (v.ok) return html`<div class="field-status ok"><span class="sigil">✓</span>${label} OK</div>`;
return html`<div class="field-status ${v.level}">
<span class="sigil">${v.level === 'warn' ? '!' : '✗'}</span>${v.msg}
</div>`;
}
private _fieldClass(v: FieldValidity | null): string {
if (v === null || v.ok) return '';
return v.level;
}
/** Public — call from host to trigger validation + emit submit event. */
public requestSubmit(): void { this._submit(); }
/** Public — call from host to dispatch cancel. */
public requestCancel(): void { this._cancel(); }
private _submit() {
const id = this.entityId.trim();
if (!ENTITY_ID_RE.test(id)) {
this._err = `entity_id must match domain.snake_case (got "${id}")`;
return;
}
const stateVal = this.state.trim();
if (!stateVal) {
this._err = 'state must not be empty';
return;
}
let attrs: Record<string, unknown> = {};
if (this._attrs.trim()) {
try {
const parsed = JSON.parse(this._attrs);
if (typeof parsed !== 'object' || Array.isArray(parsed) || parsed === null) {
this._err = 'attributes must be a JSON object (not array, not scalar)';
return;
}
attrs = parsed as Record<string, unknown>;
} catch (e) {
this._err = `attributes JSON parse failed: ${e instanceof Error ? e.message : String(e)}`;
return;
}
}
this._err = null;
this.dispatchEvent(new CustomEvent('hc-entity-submit', {
detail: { entity_id: id, state: stateVal, attributes: attrs },
bubbles: true, composed: true,
}));
}
private _cancel() {
this._err = null;
this.dispatchEvent(new CustomEvent('hc-entity-cancel', { bubbles: true, composed: true }));
}
render() {
return html`
<form @submit=${(e: Event) => { e.preventDefault(); this._submit(); }}>
<label for="eid">entity_id</label>
<input id="eid" .value=${this.entityId}
class=${this._fieldClass(this._idValid)}
?disabled=${this.editing}
@input=${(e: Event) => this._onIdInput((e.target as HTMLInputElement).value)}
placeholder="light.kitchen_ceiling" />
<div class="hint">format: <code>domain.snake_case</code> — domain like sensor / light / switch / binary_sensor</div>
${this._statusLine('entity_id', this._idValid)}
<label for="state">state</label>
<input id="state" .value=${this.state}
class=${this._fieldClass(this._stateValid)}
@input=${(e: Event) => this._onStateInput((e.target as HTMLInputElement).value)}
placeholder="on / off / 42 / 14.5 / detected" />
${this._statusLine('state', this._stateValid)}
<label for="attrs">attributes (JSON object)</label>
<textarea id="attrs" .value=${this._attrs}
class=${this._fieldClass(this._attrsValid)}
@input=${(e: Event) => this._onAttrsInput((e.target as HTMLTextAreaElement).value)}
placeholder='{ "friendly_name": "Kitchen Ceiling", "brightness": 230 }'></textarea>
<div class="hint">optional; leave blank for <code>{}</code></div>
${this._statusLine('attributes', this._attrsValid)}
${this._err ? html`<div class="err">${this._err}</div>` : ''}
</form>
`;
}
}
declare global { interface HTMLElementTagNameMap { 'hc-entity-form': EntityForm; } }
+112
View File
@@ -0,0 +1,112 @@
/**
* `<hc-modal>` — minimal accessible overlay modal.
*
* Open / close by setting the `open` property. Closes on Escape and
* on backdrop click. Content goes in the default slot; an optional
* named "footer" slot is rendered below the content.
*
* Emits `hc-modal-close` on close so the host can clean up.
*/
import { LitElement, html, css } from 'lit';
import { customElement, property } from 'lit/decorators.js';
@customElement('hc-modal')
export class Modal extends LitElement {
@property({ type: Boolean, reflect: true }) open = false;
@property({ type: String }) heading = '';
static styles = css`
:host { display: contents; }
.backdrop {
position: fixed;
inset: 0;
background: hsl(220 25% 4% / 0.65);
backdrop-filter: blur(4px);
-webkit-backdrop-filter: blur(4px);
display: flex;
align-items: center;
justify-content: center;
z-index: 100;
padding: 16px;
}
.dialog {
background: var(--hc-bg, #0b0e13);
border: 1px solid var(--hc-border, #2a323e);
border-radius: 10px;
box-shadow: 0 24px 64px hsl(220 25% 2% / 0.6);
width: min(560px, calc(100vw - 32px));
max-height: calc(100vh - 32px);
display: flex;
flex-direction: column;
overflow: hidden;
font-family: var(--hc-font-sans, 'Outfit', system-ui, sans-serif);
color: var(--hc-text, #e6eaee);
}
header {
padding: 14px 18px;
border-bottom: 1px solid var(--hc-border, #2a323e);
display: flex;
align-items: center;
justify-content: space-between;
font-weight: 600;
font-size: 15px;
}
button.close {
background: transparent;
border: none;
color: var(--hc-text-muted, #7b899d);
cursor: pointer;
font-size: 18px;
line-height: 1;
padding: 4px 8px;
border-radius: 4px;
}
button.close:hover { background: hsl(220 20% 14%); color: var(--hc-text, #e6eaee); }
.body { padding: 16px 18px; overflow-y: auto; }
.footer {
padding: 12px 18px;
border-top: 1px solid var(--hc-border, #2a323e);
display: flex;
justify-content: flex-end;
gap: 8px;
}
`;
connectedCallback(): void {
super.connectedCallback();
this._onKey = this._onKey.bind(this);
window.addEventListener('keydown', this._onKey);
}
disconnectedCallback(): void {
window.removeEventListener('keydown', this._onKey);
super.disconnectedCallback();
}
private _onKey(e: KeyboardEvent) {
if (this.open && e.key === 'Escape') this._close();
}
private _close() {
this.open = false;
this.dispatchEvent(new CustomEvent('hc-modal-close', { bubbles: true, composed: true }));
}
render() {
if (!this.open) return html``;
return html`
<div class="backdrop" @click=${(e: Event) => { if (e.target === e.currentTarget) this._close(); }}>
<div class="dialog" role="dialog" aria-modal="true" aria-label=${this.heading}>
<header>
<span>${this.heading}</span>
<button class="close" @click=${this._close} aria-label="Close">×</button>
</header>
<div class="body"><slot></slot></div>
<div class="footer"><slot name="footer"></slot></div>
</div>
</div>
`;
}
}
declare global { interface HTMLElementTagNameMap { 'hc-modal': Modal; } }
@@ -0,0 +1,183 @@
/**
* `<hc-state-card>` — renders one HOMECORE entity state in the cognitum-v0 card style.
* Uses Lit 3 (LitElement + html/css template tags).
*/
import { LitElement, html, css, nothing } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import type { StateView } from '../api/types.js';
@customElement('hc-state-card')
export class StateCard extends LitElement {
// `delegatesFocus` lets Tab key traversal from the light DOM reach the
// role="button" element inside this card's shadow root. Without it the
// user can only activate the card via mouse click or by JS-focusing the
// inner div; with it, the natural tab sequence flows through every card.
static shadowRootOptions = { ...LitElement.shadowRootOptions, delegatesFocus: true };
@property({ type: Object }) state!: StateView;
/** Optional: icon SVG string (use `iconSvg()` from lucide.ts) */
@property({ type: String }) iconSvg?: string;
static styles = css`
:host {
display: block;
}
.card {
background: var(--hc-gradient-card, linear-gradient(180deg, #181c24 0%, #111318 100%));
border: 1px solid hsl(220 15% 18% / 0.5);
border-radius: var(--hc-radius, 0.75rem);
box-shadow: var(--hc-shadow-card, 0 8px 32px -8px hsl(220 25% 2% / 0.8));
padding: 1.25rem;
transition: transform 200ms, border-color 200ms;
}
.card:hover {
transform: translateY(-2px);
border-color: hsl(185 80% 50% / 0.4);
}
.card { cursor: pointer; position: relative; }
.card:focus-visible { outline: 2px solid var(--hc-primary, #19d4e5); outline-offset: 2px; }
button.delete {
position: absolute;
top: 0.5rem; right: 0.5rem;
width: 24px; height: 24px;
border: none;
border-radius: 4px;
background: transparent;
color: var(--hc-text-muted, #7b899d);
cursor: pointer;
font-size: 16px;
line-height: 1;
padding: 0;
opacity: 0;
transition: opacity 150ms, background 150ms, color 150ms;
}
.card:hover button.delete,
.card:focus-within button.delete { opacity: 1; }
button.delete:hover { background: hsl(0 50% 30%); color: hsl(0 80% 88%); }
button.delete:focus-visible { opacity: 1; outline: 2px solid hsl(0 60% 55%); }
.header {
display: flex;
align-items: flex-start;
gap: 0.75rem;
margin-bottom: 0.75rem;
}
.icon-wrap {
flex-shrink: 0;
width: 38px;
height: 38px;
border-radius: var(--hc-radius-sm, 0.4rem);
background: hsl(220 20% 14%);
display: flex;
align-items: center;
justify-content: center;
color: var(--hc-primary, #19d4e5);
}
.meta { flex: 1; min-width: 0; }
.entity-id {
font-family: var(--hc-font-mono, 'JetBrains Mono', monospace);
font-size: 0.6875rem;
font-weight: 600;
color: var(--hc-text-muted, #7b899d);
text-overflow: ellipsis;
overflow: hidden;
white-space: nowrap;
letter-spacing: 0.05em;
}
.state-value {
font-family: var(--hc-font-display, 'Outfit', system-ui, sans-serif);
font-size: 1.125rem;
font-weight: 600;
color: var(--hc-text, #e6eaee);
letter-spacing: -0.02em;
margin-top: 0.2rem;
}
.badge {
display: inline-flex;
align-items: center;
padding: 0.15rem 0.5rem;
border-radius: 9999px;
border: 1px solid var(--hc-border, #272b34);
font-family: var(--hc-font-mono, monospace);
font-size: 0.6875rem;
font-weight: 600;
}
.badge.on { color: #26d867; border-color: hsl(142 70% 50% / 0.4); }
.badge.off { color: #d22c2c; border-color: hsl(0 65% 50% / 0.4); }
.timestamp {
font-family: var(--hc-font-mono, monospace);
font-size: 0.625rem;
color: var(--hc-text-muted, #7b899d);
margin-top: 0.75rem;
}
`;
private badgeClass(state: string): string {
const s = state.toLowerCase();
if (s === 'on' || s === 'open' || s === 'home' || s === 'running') return 'on';
if (s === 'off' || s === 'closed' || s === 'away' || s === 'unavailable') return 'off';
return '';
}
render() {
if (!this.state) return nothing;
const { entity_id, state, last_updated } = this.state;
const badge = this.badgeClass(state);
return html`
<div class="card" part="card" role="button" tabindex="0"
@click=${this._onClick}
@keydown=${(e: KeyboardEvent) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); this._onClick(); } }}
aria-label="Edit ${entity_id}">
<button class="delete" type="button"
@click=${this._onDelete}
@keydown=${(e: KeyboardEvent) => { e.stopPropagation(); }}
aria-label="Delete ${entity_id}"
title="Delete ${entity_id}">×</button>
<div class="header">
${this.iconSvg
? html`<div class="icon-wrap" .innerHTML=${this.iconSvg}></div>`
: nothing}
<div class="meta">
<div class="entity-id" title=${entity_id}>${entity_id}</div>
<div class="state-value">${state}</div>
</div>
<span class="badge ${badge}">${state}</span>
</div>
<div class="timestamp">updated ${new Date(last_updated).toLocaleTimeString()}</div>
</div>
`;
}
private _onClick() {
this.dispatchEvent(new CustomEvent('hc-state-card-click', {
detail: { state: this.state }, bubbles: true, composed: true,
}));
}
private _onDelete(e: Event) {
// Stop propagation so the parent card's click handler (which would
// open the edit modal) doesn't also fire.
e.stopPropagation();
this.dispatchEvent(new CustomEvent('hc-state-card-delete', {
detail: { state: this.state }, bubbles: true, composed: true,
}));
}
}
declare global {
interface HTMLElementTagNameMap {
'hc-state-card': StateCard;
}
}