taninux/docs/eww-panel-dock-integration.md

TANINUX → eww: Panel & Dock — Settings-Vertrag (Handover)

Für die TANINUX-Instanz, die die „Panel & Dock"-Seite baut. Analog zur Akzent-Kette: TANINUX schreibt EINE Config-Datei, eww konsumiert sie. Die eww-Seite (Variablen, :style/:visible, Watcher) ist bereits gebaut — du brauchst nur die Datei zu schreiben.

Gegenstücke: eww-accent-integration.md (Akzent), eww-integration.md (Gesamtvertrag).

---

1. Wo die Werte liegen

Datei: ~/.local/share/taninux/panel.json ($XDG_DATA_HOME/taninux/panel.json, Fallback ~/.local/share/...) — JSON, eine Datei, neben gui.json. Existiert mit Defaults; eww seedet sie zur Not.

{
  "version": 1,
  "dock": {
    "autohide":   true,
    "icon_size":  42,
    "hide_delay": 1.2
  },
  "bar": {
    "clock_format": "%H:%M %A, %d.%m.%Y",
    "modules": {
      "music": true, "sys": true, "updates": true,
      "net": true, "bt": true, "vol": true
    }
  }
}

---

2. Die Knöpfe (Keys, Typ, erlaubte Werte)

Key	Typ	Werte / Range	Wirkung in eww	Live?
dock.autohide	bool	true / false	false = Dock immer sichtbar; true = Hover-Trigger	live
dock.icon_size	int	24 – 64 (px)	Icon-Größe im Dock (:style min-width/height)	live
dock.hide_delay	number	0.2 – 5.0 (Sekunden)	Nachhall, bis das Dock nach Verlassen schließt	next-hide
bar.clock_format	string	strftime (z.B. %H:%M)	Format der Uhr in der Bar-Mitte	≤10 s
bar.modules	object	Keys: music sys updates net bt vol	Welche Rechts-Module die Bar zeigt	live
updates.include_aur	bool	true/false (Default false)	AUR im Update-Scope (Zähler+Liste). Opt-in, braucht paru	poll

• updates.include_aur (Top-Level-Sektion updates): TANINUX-Hub macht AUR zum Opt-in (Default Repo+Flatpak). scripts/updates.sh soll diesen Key lesen und nur dann paru -Qua mitzählen/-listen. JSON-Schema der Liste bleibt [{name, old, new}] (gern + src). Beispiel-Lesen: inc=$(jq -r '.updates.include_aur // false' "$PANEL_JSON").
• bar.modules ist ein Objekt { "<modul>": true/false } (nicht Liste) — fehlt ein Key, gilt er als sichtbar. Module: music (Now-Playing-Mini), sys (CPU/RAM), updates (Update-Zähler), net, bt, vol.
• Clamping macht eww defensiv (icon_size 24–64, ungültiges → Default). Trotzdem bitte in der GUI validieren (Spin 24–64, Slider 0.2–5.0).

Noch nicht im v1 (bewusst): dock.position (left/bottom/right) und feste Größen der Bar/Dock-Fenster. Die brauchen eww reload + Geometrie-Neubau (Orientierungswechsel bei bottom). Sag Bescheid, wenn du das willst — dann erweitere ich die eww-Seite und dieses Doc; bis dahin nicht in der GUI anbieten.

---

3. Wie man anwendet

Du schreibst panel.json — mehr nicht. eww zieht nach, auf zwei Wegen:

1. Automatisch: ein Watcher (scripts/panelcfg.sh watch, läuft aus launch.sh) pollt die Datei alle 2 s und wendet Änderungen an.
2. Sofort (optional, empfohlen für „Apply"): nach dem Schreiben einmal

   ~/eww/scripts/panelcfg.sh apply
   

   feuern — dann greift es ohne die 2-s-Latenz. (Best-effort, schadet nie.)

Kein eww reload nötig für die v1-Knöpfe. Intern macht panelcfg.sh: eww update cfg-icon-size=… cfg-modules=…, schaltet Autohide imperativ, und clock_format/hide_delay werden on-demand gelesen. (Du musst die eww-Variablennamen nicht kennen — nur panel.json schreiben.)

---

4. Die Grenze — wer schreibt was

• panel.json gehört dir (TANINUX). Schreib es frei. eww liest es nur.
• Gepinnte Dock-Apps liegen NICHT in panel.json, sondern in ~/.config/eww/dock-pins — eine simple Zeilen-Datei, Format exec|class|icon:

  librewolf|librewolf|librewolf
  kitty|kitty|kitty
  code|Code|code-oss
  

  • exec = Startbefehl, class = Fensterklasse (app_id/WM_CLASS), icon = Icon-Name (Papirus). eww spiegelt Änderungen automatisch (Poll alle 2 s).
  • Die Zeilen-REIHENFOLGE = die Dock-Reihenfolge. → Drag & Drop bitte hier bauen: Die „Dock"-Gruppe zeigt die gepinnten Apps als ziehbare GTK-Liste; beim Loslassen schreibst du dock-pins in der neuen Reihenfolge neu. eww sortiert das Dock in ≤2 s nach. Echtes DnD im eww-Dock selbst geht nicht (eww/GTK3 hat keine Drag-Primitiven) — deshalb gehört das in deine GTK-Seite. (eww bietet zusätzlich „Move up/Move down" im Dock-Rechtsklick als Schnell-Option — die schreibt dieselbe Datei.)
  • Du darfst diese Datei direkt lesen UND schreiben (z.B. die Pin-Liste in der GUI verwalten). eww mutiert sie auch selbst (Dock-Rechtsklick → Pin/Unpin). Zwei-Wege ist ok, weil das Format trivial und idempotent ist — schreib die ganze Datei neu, eww liest sie beim nächsten Poll.
  • Falls du lieber Befehle feuerst statt zu schreiben: ~/eww/scripts/dock.sh pin <class> / unpin <class>.
• ~/eww/** (yuck/scss/andere scripts) ist eww-intern. Für Settings brauchst du das nie anzufassen — alles läuft über panel.json + dock-pins.

Darfst du eww trotzdem direkt anfassen?

Ja — für Code/Feature-Arbeit an der Bar selbst (neue Widgets, Layout) ist es EIN Projekt, kein Tabu. Einzige harte Regel: nie zwei Editoren gleichzeitig auf derselben Datei (genau das hat beim Hyprland→Sway-Umbau Chaos gemacht). Für Settings aber gilt: über panel.json gehen, nicht eww hand-editieren — sonst ist jede GUI-Änderung ein yuck-Edit (brittle + Race-Gefahr).

---

Status (gebaut & getestet)

• ✅ panel.json (Default vorhanden) + scripts/panelcfg.sh (apply/watch/get).
• ✅ dock.icon_size live (24–64, getestet 42↔56), bar.modules live, dock.autohide imperativ, bar.clock_format via scripts/clock.sh, dock.hide_delay aus der JSON gelesen.
• ✅ Watcher in launch.sh eingetragen.
• ⏳ dock.position/Fenstergrößen = Reload-Thema, auf Anfrage.

Damit kannst du core/panel.py (Read/Write panel.json + optional dock-pins, Apply = Datei schreiben + panelcfg.sh apply) und die GTK-Seite „Panel & Dock" (Gruppen Top bar / Dock) direkt bauen.