Skip to content

FEATURES.md

Latest commit

 

History

History
344 lines (249 loc) · 11.5 KB

FEATURES.md

File metadata and controls

344 lines (249 loc) · 11.5 KB

Navet Feature Map

This document is a current implementation map for Navet's major product areas. It is intended to help contributors understand where behavior lives, which sections are active, and where story/test coverage is expected to exist.

Feature Inventory

Current active feature folders under src/app/features/:

  • auth
  • calendar
  • climate
  • dashboard
  • energy
  • lighting
  • media
  • notifications
  • person
  • rss
  • scenes
  • security
  • sensors
  • settings
  • tasks
  • vacuum
  • weather

Additional notes:

  • cross-feature imports should prefer a feature's root index.ts when that entrypoint exists
  • notifications is a supporting feature surfaced through shared app-shell UI rather than a top-level section

App Shell

Root app composition

src/app/App.tsx assembles:

  • the i18n provider
  • the global error display
  • the authenticated split between login and dashboard shell
  • the PWA update prompt
  • the network status surface
  • the notification/toast layer
  • theme- and viewport-related DOM synchronization

Shared app-shell composition lives primarily under src/app/components/layout/.

Current layout ownership includes:

  • header and sidebar
  • room navigation
  • section navigation helpers
  • section customization shell/button
  • mobile command, search, and section sheets
  • reusable section layouts such as locks, media, and security

State and Data Flow

Shared state

Navet uses Zustand for all shared reactive state.

Current store files:

  • auth-store.ts
  • config-store.ts
  • edit-mode-store.ts
  • error-store.ts
  • home-assistant-store.ts
  • navigation-store.ts
  • search-store.ts
  • settings-store.ts
  • theme-store.ts

Shared selectors live in src/app/stores/selectors.ts and should be preferred over full-store subscriptions.

Home Assistant flow

src/app/services/home-assistant.service.ts is the public Home Assistant facade. It composes:

The facade emits typed updates for:

  • entities
  • config
  • registries
  • connection

The store updates only the affected slices for each event. Avoid broad "copy the whole service state" sync patterns.

Navigation keeps currentRoom persisted in the store while activeSection is derived from the URL through src/app/navigation/sections.ts.

Top-Level Sections

The current primary section model is:

  • home
  • energy
  • security
  • tasks
  • locks
  • lights
  • media
  • settings

Section routing and lazy loading are coordinated by src/app/features/dashboard/components/dashboard-section-router.tsx.

Section ownership

  • home: room-driven dashboard overview, editable zone-based home canvas, and home widgets
  • energy: energy dashboard, setup wizard, drilldown flow, and energy-only custom widget band
  • security: camera-first section built on the shared device-section shell
  • tasks: Home Assistant automation/task summaries grouped into sections
  • locks: lock-focused section built on the shared device-section shell
  • lights: all-lights overview using the dashboard all-view grid in custom grouping mode
  • media: grouped media section with audio and TV-specific presentation
  • settings: appearance, localization, dashboard, interaction, project, and system settings

Dashboard

Ownership

The dashboard feature owns:

  • card registration
  • entity visibility
  • custom-card placement
  • room ordering
  • card ordering
  • dashboard-specific persisted layout state
  • home overview layout state
  • sectioned and flow layout behavior

Important paths:

Current custom widgets

Current CardType values for dashboard/section widgets:

  • rss
  • photo
  • note
  • battery
  • energy-now
  • button
  • map

Home-widget implementations currently live under src/app/features/dashboard/components/widgets/.

The widget store also uses special room sentinels:

  • __home__ for widgets attached to the home overview
  • __energy__ for widgets attached to the energy section band

Home widgets may additionally persist zone overrides via src/app/features/dashboard/zones/.

Room sourcing

Home-room navigation is assembled from two sources:

This keeps the room list stable when registry-backed area names exist while still surfacing devices whose room can only be inferred from entity metadata.

Home overview zones

The All home view is grouped into four named zones:

  • hero
  • actions
  • status
  • analytics

Default placement and fallback resolution live in:

Feature Ownership Highlights

calendar

climate

energy

lighting

media

notifications

rss

security

settings

tasks

vacuum

weather

Shared UI System

Ownership split

  • primitives/: low-level reusable UI such as shared buttons, card shells, header parts, and compact text
  • patterns/: composed shared structures
  • system/: curated export and token-story surface
  • ui-kit/: canonical shared import surface for docs, stories, and stable shared consumers
  • shared/: app-specific shared UI and compatibility shims
  • layout/: app-shell and section-level composition
  • ui/: wrappers around library primitives and dropdown/dialog infrastructure

See ../README.md and README.md for the higher-level explanation.

Storybook support

Storybook is the review surface for:

  • token and theme stories
  • shared primitives and patterns
  • layout and navigation surfaces
  • entity cards
  • dashboard widgets
  • settings sections
  • energy-specific visuals

Shared story helpers live in src/app/storybook/story-frames.tsx and src/app/storybook/story-docs.ts.

Testing Map

Vitest is the preferred path for:

  • shared utility logic
  • persisted store behavior
  • controller composition
  • browser-dependent hooks
  • token and entity-mapping helpers
  • dashboard actions and feature-specific logic seams

Current co-located __tests__/ directories:

  • src/app/components/layout/__tests__/
  • src/app/components/shared/theme/__tests__/
  • src/app/components/system/tokens/__tests__/
  • src/app/features/calendar/components/calendar/__tests__/
  • src/app/features/dashboard/components/__tests__/
  • src/app/features/dashboard/hooks/__tests__/
  • src/app/features/dashboard/stores/__tests__/
  • src/app/features/energy/components/dashboard/__tests__/
  • src/app/features/energy/components/energy-setup-wizard/__tests__/
  • src/app/features/energy/services/__tests__/
  • src/app/features/energy/utils/__tests__/
  • src/app/features/lighting/components/__tests__/
  • src/app/features/lighting/components/light-card/__tests__/
  • src/app/features/media/components/media-card/__tests__/
  • src/app/features/media/components/media/__tests__/
  • src/app/features/rss/components/rss-feed-card/__tests__/
  • src/app/features/tasks/components/__tests__/
  • src/app/features/tasks/utils/__tests__/
  • src/app/features/vacuum/components/vacuum/__tests__/
  • src/app/hooks/__tests__/
  • src/app/stores/__tests__/
  • src/app/utils/__tests__/

Shared test harness support lives in src/test/.

Maintenance Expectations

  • Update this file when top-level sections, feature ownership, widget types, or test locations change
  • Remove references to deleted feature folders or moved paths instead of leaving historical hints in active docs
  • Prefer describing the actual current tree over describing an intended future architecture