From f6218df061bc3b2d28b81a3cfdeded35e494aeb8 Mon Sep 17 00:00:00 2001 From: phranck Date: Thu, 5 Feb 2026 22:10:05 +0100 Subject: [PATCH] Chore: finalize flat-appearance plan and update status files --- .../xcshareddata/IDETemplateMacros.plist | 2 +- plans/done/2026-02-05-flat-appearance.md | 146 ++++++++++++++++++ to-dos.md | 10 +- 3 files changed, 149 insertions(+), 9 deletions(-) create mode 100644 plans/done/2026-02-05-flat-appearance.md diff --git a/.swiftpm/xcode/package.xcworkspace/xcshareddata/IDETemplateMacros.plist b/.swiftpm/xcode/package.xcworkspace/xcshareddata/IDETemplateMacros.plist index edc86073..3779d361 100644 --- a/.swiftpm/xcode/package.xcworkspace/xcshareddata/IDETemplateMacros.plist +++ b/.swiftpm/xcode/package.xcworkspace/xcshareddata/IDETemplateMacros.plist @@ -9,7 +9,7 @@ // ___FILENAME___ // // Created by LAYERED.work -// CC BY-NC-SA 4.0 +// License: MIT diff --git a/plans/done/2026-02-05-flat-appearance.md b/plans/done/2026-02-05-flat-appearance.md new file mode 100644 index 00000000..0e0bc0e9 --- /dev/null +++ b/plans/done/2026-02-05-flat-appearance.md @@ -0,0 +1,146 @@ +# Remove Block/Flat Appearances — Simplify to Border-Only Rendering + +## Completed — 2026-02-05 + +Outcome changed from the original plan: instead of replacing Block with Flat, **both were removed entirely**. The framework now has 4 standard border-based appearances only (line, rounded, doubleLine, heavy). BorderStyle.ascii was also removed. Surface color tokens (surfaceBackground, surfaceHeaderBackground, elevatedBackground) eliminated. 36 files changed, +225 / −1140 lines. 526 tests / 84 suites passing. + +**Created:** 2026-02-05 +**Branch:** `refactor/flat-appearance` (from `main`) +**Supersedes:** "Remove Block Appearance" task in to-dos.md + +## Original Goal + +Replace the fragile Block Appearance (half-block Unicode characters `▄▀█` that break across terminals) with a simpler **Flat Appearance**: same colored background surfaces from the theme palette, but **no borders at all**. Pure ANSI background fills. + +## Design + +### What stays + +- **Three surface color tokens**: `surfaceBackground`, `surfaceHeaderBackground`, `elevatedBackground` — these define the visual hierarchy and are the core of the "flat" look. +- **Color hierarchy**: background (darkest) → surfaceHeaderBackground → surfaceBackground → elevatedBackground (brightest). +- **Per-view section coloring**: ContainerView header/footer use `surfaceHeaderBackground`, body uses `surfaceBackground`. Buttons use `elevatedBackground`. + +### What changes + +| Aspect | Block (old) | Flat (new) | +|--------|-------------|------------| +| Border characters | `▄▀█` half/full blocks | None — `BorderStyle.none` (spaces) | +| Section transitions | `blockSeparator` with FG/BG trick | No separator — sections distinguished by background color only | +| Side borders | `█` full blocks | No side borders — content fills full width with background color | +| Top/bottom edges | `▄▄▄` / `▀▀▀` rows | No edge rows — background starts/ends with content | +| Terminal compat | Broken in many terminals | Universal — only requires ANSI background color support | + +### What gets removed + +- `BlockPalette` protocol — the 3 color properties move into `Palette` directly +- `BorderStyle.block` preset + `blockBottomHorizontal` + `blockFooterSeparator` statics +- `BorderRenderer` block methods: `blockTopBorder`, `blockBottomBorder`, `blockContentLine`, `blockSeparator` +- All `appearance.rawId == .block` branches in views — replaced with `== .flat` branches +- `BlockThemePage.swift` example page — replace with `FlatThemePage.swift` or integrate into existing demo + +### Migration: `BlockPalette` → `Palette` + +Move the 3 surface color properties from `BlockPalette` into `Palette`: + +```swift +// Before: separate protocol +protocol BlockPalette: Palette { + var surfaceBackground: Color { get } + var surfaceHeaderBackground: Color { get } + var elevatedBackground: Color { get } +} + +// After: integrated into Palette with defaults +protocol Palette { + // ... existing 13 properties ... + var surfaceBackground: Color { get } // default: background.lighter(by: 0.10) + var surfaceHeaderBackground: Color { get } // default: background.lighter(by: 0.07) + var elevatedBackground: Color { get } // default: surfaceHeaderBackground.lighter(by: 0.08) +} +``` + +This eliminates the `as? BlockPalette` casts and fallbacks throughout the codebase. + +### Flat Rendering — Per Component + +All flat-rendered sections use **1 character horizontal padding** (left and right) so content doesn't stick to the edges. This replaces the `█` side borders from block rendering with simple space padding inside the background fill. + +**ContainerView:** +- Header lines: persistent background = `surfaceHeaderBackground`, 1-char padding left/right. No top border row. +- Body lines: persistent background = `surfaceBackground`, 1-char padding left/right. No side borders. +- Footer lines: persistent background = `surfaceHeaderBackground`, 1-char padding left/right. No bottom border row. +- No separator rows between sections — color change alone provides visual distinction. + +**BorderModifier (Box, `.border()`):** +- All content lines: persistent background = `surfaceBackground`, 1-char padding left/right. +- No border rows or side characters. + +**Button:** +- Padded label with persistent background = `elevatedBackground`. +- No `[` `]` brackets. Same as block, just without the block characters. + +**StatusBar:** +- Full-width content with persistent background = `statusBarBackground`, 1-char padding left/right. +- No border rows. + +**AppHeader:** +- Full-width content with persistent background = `appHeaderBackground`, 1-char padding left/right. +- Bottom divider: thin line using `─` (standard divider, not `▀`), or no divider at all — TBD. + +**Menu:** +- Header lines: persistent background = `surfaceHeaderBackground`, 1-char padding left/right. +- Item lines: persistent background = `surfaceBackground`, 1-char padding left/right. +- No separator row. + +## Steps + +## Completed — 2026-02-05 + +### Phase 1: Palette Refactoring + +- [x] Move `surfaceBackground`, `surfaceHeaderBackground`, `elevatedBackground` from `BlockPalette` into `Palette` with default implementations +- [x] Remove `BlockPalette` protocol entirely +- [x] Change `SystemPalette: BlockPalette` → `SystemPalette: Palette` +- [x] Remove `Palette` convenience accessors (`blockSurfaceBackground` etc.) — use direct property access +- [x] Update `SemanticColor` — keep the 3 surface cases, simplify `resolve()` to use `Palette` directly (no cast) +- [x] Keep `Color.Semantic` accessors — renamed comments from "BlockPalette" to "Surface" +- [x] Update related tests + +### Phase 2: Appearance & BorderStyle Cleanup + +- [x] Rename `Appearance.block` → `Appearance.flat` (keep same registry slot) +- [x] Remove `BorderStyle.block`, `.blockBottomHorizontal`, `.blockFooterSeparator` +- [x] Set `Appearance.flat` to use `BorderStyle.none` +- [x] Update `AppearanceRegistry` and cycling order +- [x] Update `AppearanceTests` + +### Phase 3: Rendering Simplification + +- [x] Remove `BorderRenderer` block methods (4 methods) +- [x] Add `flatContentLine(content:innerWidth:backgroundColor:)` — persistent BG + 1-char padding +- [x] Rewrite `BorderModifier` → `renderFlatStyle` (background-only, no borders) +- [x] Rewrite `ContainerView` → `renderFlatStyle` (header/body/footer sections) +- [x] Rewrite `Button` flat branch (rename check only) +- [x] Rewrite `StatusBar` → `renderFlatBordered` (single background line) +- [x] Rewrite `AppHeader` → `renderFlat` (background + thin `─` divider) +- [x] Rewrite `Menu` flat branch (section-aware coloring, skip divider) +- [x] Clean up `DimmedModifier` ornament set (removed `▄▀█▌▐`) + +### Phase 4: Example App & Tests + +- [x] Rename `BlockThemePage` → `FlatThemePage` +- [x] Replace `BorderRendererBlockTests` with `BorderRendererFlatTests` (3 tests) +- [x] Update `PaletteDefaultTests` → `PaletteSurfaceDefaultTests` +- [x] Update `PredefinedPaletteTests` — renamed luminance order tests +- [x] Full `swift build` + `swiftlint` + `swift test` — 536 tests / 88 suites passing + +### Phase 5: Cleanup + +- [x] Grep for "block" references in Sources/ and Tests/ — updated 11 doc comments +- [x] PR (pending) + +## Risk Assessment + +- **Low risk**: The rendering is simpler than what it replaces. ANSI background colors work everywhere. +- **Migration**: Purely internal refactoring. No public API surface changes beyond renaming `.block` → `.flat`. +- **Visual difference**: Flat will look slightly different from Block — no smooth half-block transitions. But that's the point: simpler, universal, still visually distinct from bordered appearances. diff --git a/to-dos.md b/to-dos.md index e545d56f..443d449e 100644 --- a/to-dos.md +++ b/to-dos.md @@ -23,12 +23,6 @@ (none) -### Refactoring - -#### High - -- [ ] **Remove Block Appearance** — Delete all block rendering code, BorderStyle.block, BlockPalette, SemanticColor block tokens, block tests, DocC references. New branch after PR #77 merge. - ### Performance - [ ] **`View._printChanges()` Equivalent** — Debug mechanism that logs why body was re-evaluated @@ -36,7 +30,6 @@ ### Infrastructure - [ ] **Example App Redesign** — Feature catalog → multiple small example apps -- [ ] **GitHub → Codeberg Migration** — `gh2cb`, Woodpecker CI, DNS migration ### Testing & Docs @@ -47,6 +40,7 @@ ### 2026-02-05 +- [x] **Remove Block/Flat Appearances** — Eliminated block, flat, and ascii appearances. 4 border-based styles remain (line, rounded, doubleLine, heavy). Removed BlockPalette, surface tokens, stale DocC. −1140 lines. - [x] **Notification System** — Fire-and-forget `NotificationService`, fade-in/out animation, word-wrap, top-right overlay, Box rendering. No severity styles, no Binding. (PR #77) - [x] **Render Performance Phase 2** — Cache invalidation fix, Equatable on 15 types/views, debug tooling, example app decomposition + `.equatable()`, DocC documentation (PR #74) @@ -150,4 +144,4 @@ Permanent architectural concern. Synthesized from the [SwiftUI performance artic --- -**Last Updated:** 2026-02-05 21:35 +**Last Updated:** 2026-02-05 22:10