Skip to content

Commit 80787f6

Browse files
StormsysStormsys
committed
Rewrite CLAUDE.md to match actual codebase
- Version 0.1.0-alpha (not 1.0.0) - 1 custom element (not 3; gap-card and layout-break removed) - Correct file tree (no base-layout.ts, gap-card.ts, layout-break.ts) - Architecture: GridLayout extends LitElement directly (no BaseLayout) - Add extracted utility modules (template.ts, grid-utils.ts, yaml.ts) - Add test file references - Document known gaps
1 parent 949b157 commit 80787f6

1 file changed

Lines changed: 47 additions & 39 deletions

File tree

‎CLAUDE.md‎

Lines changed: 47 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,19 @@
1-
# CLAUDE.md — AI Assistant Guide for sections-grid-layout
2-
3-
This file provides context for AI assistants working in this repository.
1+
# CLAUDE.md -- AI Assistant Guide for sections-grid-layout
42

53
---
64

75
## Project Overview
86

97
**sections-grid-layout** is a Home Assistant Lovelace custom **view** plugin that places native HA `hui-section` elements into a CSS Grid with Jinja template evaluation and responsive design support.
108

11-
- **Version**: 1.0.0
9+
- **Version**: 0.1.0-alpha
1210
- **License**: MIT
1311
- **Author**: Stormsys
1412
- **HA minimum version**: 2024.2.0 (native Sections view required)
1513
- **Distribution**: HACS
1614
- **Compiled output**: `sections-grid-layout.js`
1715

18-
The project registers one view layout element (`sections-grid-layout`) plus two helper cards (`gap-card-sgl`, `layout-break-sgl`). It coexists safely with the stock `layout-card`.
16+
The project registers one custom element (`sections-grid-layout`) and two patches. It coexists safely with the stock `layout-card`.
1917

2018
---
2119

@@ -26,69 +24,71 @@ The project registers one view layout element (`sections-grid-layout`) plus two
2624
├── src/
2725
│ ├── main.ts # Entry point
2826
│ ├── types.ts # Shared TypeScript interfaces
29-
│ ├── helpers.ts # Utility functions + selector options
30-
│ ├── gap-card.ts # <gap-card-sgl>
31-
│ ├── layout-break.ts # <layout-break-sgl>
32-
│ └── layouts/
33-
│ ├── base-layout.ts # Abstract LitElement base
34-
│ └── grid.ts # <sections-grid-layout> — main file
27+
│ ├── helpers.ts # Selector options constant
28+
│ ├── template.ts # Template evaluation (pure functions)
29+
│ ├── grid-utils.ts # Grid area parsing and section helpers (pure functions)
30+
│ ├── yaml.ts # YAML serializer/parser (pure functions)
31+
│ ├── layouts/
32+
│ │ └── grid.ts # <sections-grid-layout> -- main file
3533
│ └── patches/
3634
│ ├── hui-view-editor.ts # Adds "Sections Grid" to view type dropdown
3735
│ └── hui-card-element-editor.ts # Preserves view_layout on card save
36+
├── tests/
37+
│ ├── template-evaluation.test.ts
38+
│ ├── grid-utils.test.ts
39+
│ ├── yaml.test.ts
40+
│ └── build-output.test.ts
3841
├── rollup.config.js
3942
├── tsconfig.json
43+
├── vitest.config.ts
4044
├── package.json
4145
├── hacs.json
42-
├── sections-grid-layout.js # Compiled output — DO NOT edit
46+
├── sections-grid-layout.js # Compiled output -- DO NOT edit
47+
├── CHANGELOG.md
4348
└── README.md
4449
```
4550

4651
---
4752

48-
## Build System
53+
## Build & Test
4954

5055
```bash
5156
npm install
52-
npm run build # Production build → sections-grid-layout.js
53-
npm run watch # Watch mode (no minification)
57+
npm run build # Production build -> sections-grid-layout.js
58+
npm run watch # Watch mode (no minification)
59+
npm test # Run unit tests (vitest)
60+
npm run test:watch # Watch mode for tests
5461
```
5562

5663
---
5764

58-
## Custom Elements
59-
60-
| Element | File | Role |
61-
|---|---|---|
62-
| `sections-grid-layout` | layouts/grid.ts | CSS Grid view layout |
63-
| `gap-card-sgl` | gap-card.ts | Spacing card |
64-
| `layout-break-sgl` | layout-break.ts | Flow break card |
65-
66-
---
67-
6865
## Architecture
6966

7067
```
7168
LitElement
72-
└── BaseLayout (base-layout.ts)
73-
└── GridLayout (layouts/grid.ts)
69+
└── GridLayout (src/layouts/grid.ts)
7470
```
7571

76-
### `base-layout.ts`
77-
Abstract base. Manages `editMode`, card visibility, and the FAB (suppressed in sections mode by GridLayout's `_render_fab()` override).
72+
`GridLayout` extends `LitElement` directly (no base class).
7873

7974
### `grid.ts`
8075
- **CSS Grid rendering**: Applies `grid-template-areas/columns/rows` from `layout` config
8176
- **Section management**: Creates/destroys `hui-section` wrappers; maintains `_sectionsCache`; auto-saves new sections to lovelace config
82-
- **Jinja template evaluation**: Evaluates `{{ states() }}`, `{{ state_attr() }}`, `{% if %}` in `custom_css`; tracks entities in `_trackedEntities`; debounced via `requestAnimationFrame`
77+
- **Jinja template evaluation**: Calls pure functions from `template.ts` for `{{ states() }}`, `{{ state_attr() }}`, `{% if %}` in `custom_css`; tracks entities in `_trackedEntities`; debounced via `requestAnimationFrame`
8378
- **Background images**: Fixed positioning, blur, opacity, template support
8479
- **Kiosk mode**: `layout.kiosk: true` makes `#root` fixed-position, filling viewport below HA header; edit-mode offset adjusts for tab bar
8580
- **Layout zoom**: `layout.zoom` applies CSS `zoom` to `#root`
86-
- **Per-section styling**: `scrollable`, `background`, `backdrop_blur`, `zoom`, `overflow` on each `SectionConfig` — applied as classes/inline styles on `.section-container`
87-
- **Edit mode UI**: Section labels with grid-area name; loose-cards container for orphan cards
88-
- **`_updateSectionsLovelace()`**: Pushes fresh `lovelace` AND fresh `config` (looked up by `grid_area`) to each `hui-section` so it never renders from a stale snapshot
81+
- **Per-section styling**: `scrollable`, `background`, `backdrop_blur`, `zoom`, `overflow`, `padding`, `tint`, `variables`, `mediaquery` on each section
82+
- **Edit mode UI**: Section labels with grid-area name; loose-cards container for orphan cards; overlay tester panel
83+
- **`_updateSectionsLovelace()`**: Pushes fresh `lovelace` AND fresh `config` to each `hui-section`
84+
85+
### Extracted utility modules (pure functions, testable without DOM)
86+
- **`template.ts`**: `evaluateCssTemplates()`, `evaluateOverlayContent()`, `extractEntitiesFromTemplate()`
87+
- **`grid-utils.ts`**: `detectAllGridAreas()`, `formatAreaName()`, `ensureSectionsForAllAreas()`
88+
- **`yaml.ts`**: `sectionConfigToYaml()`, `yamlScalar()`, `parseYaml()`
8989

9090
### `patches/hui-view-editor.ts`
91-
Adds only `sections-grid-layout` to the view type dropdown. Guard flag `_sectionsGridLayoutPatched` prevents double-patching when layout-card is also loaded.
91+
Adds `sections-grid-layout` to the view type dropdown. Guard flag `_sectionsGridLayoutPatched` prevents double-patching when layout-card is also loaded.
9292

9393
### `patches/hui-card-element-editor.ts`
9494
Preserves `view_layout` when the card element editor saves changes.
@@ -113,6 +113,7 @@ Preserves `view_layout` when the card element editor saves changes.
113113
| State value | `{{ states('sensor.temperature') }}` |
114114
| Attribute value | `{{ state_attr('climate.living', 'temperature') }}` |
115115
| Conditional | `{% if is_state('binary_sensor.dark', 'on') %}...{% endif %}` |
116+
| Negative | `{% if not is_state('binary_sensor.dark', 'on') %}...{% endif %}` |
116117

117118
---
118119

@@ -121,7 +122,9 @@ Preserves `view_layout` when the card element editor saves changes.
121122
| Task | File |
122123
|---|---|
123124
| Grid rendering / section logic | `src/layouts/grid.ts` |
124-
| Base layout / FAB behaviour | `src/layouts/base-layout.ts` |
125+
| Template evaluation | `src/template.ts` |
126+
| Grid area parsing | `src/grid-utils.ts` |
127+
| YAML serializer/parser | `src/yaml.ts` |
125128
| Shared types | `src/types.ts` |
126129
| View type dropdown | `src/patches/hui-view-editor.ts` |
127130
| view_layout preservation | `src/patches/hui-card-element-editor.ts` |
@@ -130,14 +133,19 @@ Preserves `view_layout` when the card element editor saves changes.
130133

131134
## Compatibility with layout-card
132135

133-
- Only `sections-grid-layout` is registered — masonry/horizontal/vertical are untouched
136+
- Only `sections-grid-layout` is registered -- masonry/horizontal/vertical are untouched
134137
- Patch guard is `_sectionsGridLayoutPatched` (distinct from layout-card's guard)
135138
- Both can be loaded simultaneously without conflict
136139

137140
---
138141

139142
## Constraints
140143

141-
- **Never edit `sections-grid-layout.js` directly** — overwritten on build
142-
- **HA 2024.2+ only** — `hui-section` did not exist before that release
143-
- **No automated tests** — validate manually via Docker or real HA instance
144+
- **Never edit `sections-grid-layout.js` directly** -- overwritten on build
145+
- **HA 2024.2+ only** -- `hui-section` did not exist before that release
146+
147+
---
148+
149+
## Known Gaps
150+
151+
- `background_blur` is NOT handled in layout-level `mediaquery` overrides (only works at base level)

0 commit comments

Comments
 (0)