flea-qml 0.0.0-stage → 0.2.0

package/ui/boot/Commons/UntypedInput.qml

@@ -0,0 +1,152 @@
+pragma Singleton
+import QtQuick
+import Quickshell
+import Quickshell.Io
+import Quickshell.Services.Pipewire
+import "AudioNodesModel.js" as Model
+
+// Volume and mute of the default input when Quickshell gives it no
+// PwNode.audio: Quickshell types only exact media classes, so a virtual source
+// (an Audio/Source/Virtual, such as EasyEffects' or a platform's microphone
+// mapping) has no volume or mute there. They go through wpctl instead, once for
+// the whole shell. Reads and writes name the node by id, a reply for a node no
+// longer tracked is dropped, and writes run one at a time with only the latest
+// volume kept, so a slider drag cannot land on another input later.
+Singleton {
+  id: root
+
+  readonly property var source: Pipewire.defaultAudioSource
+  // The default input is untyped, so this drives it.
+  readonly property bool active: !!source && !source.audio
+  // Every handler reads nodeId itself: a property bound to it could still hold
+  // its old value when onNodeIdChanged runs.
+  readonly property int nodeId: active ? source.id : -1
+
+  property bool known: false
+  property real volume: 0
+  property bool muted: false
+
+  property int generation: 0
+  property int readGeneration: -1
+  property bool readAgain: false
+  property var pendingVolume: null
+  property var pendingMute: null
+
+  // pactl subscribe is started again when it ends, unless it keeps ending at
+  // once (no pipewire-pulse), which would only respawn it forever.
+  property real subscribedAt: 0
+  property int quickExits: 0
+
+  onNodeIdChanged: reset()
+  Component.onCompleted: reset()
+
+  function reset() {
+    generation++
+    known = false
+    pendingVolume = null
+    pendingMute = null
+    quickExits = 0
+    events.running = nodeId >= 0
+    refresh()
+  }
+
+  function refresh() {
+    if (nodeId < 0) return
+    if (reader.running || writer.running) {
+      readAgain = true
+      return
+    }
+    readGeneration = generation
+    reader.command = ["wpctl", "get-volume", String(nodeId)]
+    reader.running = true
+  }
+
+  function setVolume(value) {
+    if (nodeId < 0) return
+    volume = Math.max(0, Math.min(1, value))
+    pendingVolume = [String(nodeId), volume.toFixed(2)]
+    flush()
+  }
+
+  function setMuted(value) {
+    if (nodeId < 0 || !known) return
+    muted = value
+    pendingMute = [String(nodeId), value ? "1" : "0"]
+    flush()
+  }
+
+  function flush() {
+    if (reader.running || writer.running) return true
+    var args = null
+    if (pendingMute !== null) {
+      args = ["wpctl", "set-mute"].concat(pendingMute)
+      pendingMute = null
+    } else if (pendingVolume !== null) {
+      args = ["wpctl", "set-volume"].concat(pendingVolume)
+      pendingVolume = null
+    }
+    if (!args) return false
+    writer.command = args
+    writer.running = true
+    return true
+  }
+
+  function settle() {
+    if (flush()) return
+    if (readAgain) {
+      readAgain = false
+      refresh()
+    }
+  }
+
+  Process {
+    id: reader
+    stdout: StdioCollector {
+      waitForEnd: true
+      onStreamFinished: {
+        var level = Model.parseWpctlVolume(text)
+        if (!level || root.nodeId < 0 || root.readGeneration !== root.generation) return
+        if (root.pendingVolume !== null || root.pendingMute !== null || writer.running) return
+        root.volume = level.volume
+        root.muted = level.muted
+        root.known = true
+      }
+    }
+    onExited: root.settle()
+  }
+
+  Process {
+    id: writer
+    onExited: {
+      root.readAgain = true
+      root.settle()
+    }
+  }
+
+  // The volume keys, the mute key and other apps change the node too. pactl
+  // translates its events, so they are read in the C locale.
+  Process {
+    id: events
+    command: ["pactl", "subscribe"]
+    environment: ({ LC_ALL: "C" })
+    onRunningChanged: if (running) root.subscribedAt = Date.now()
+    onExited: {
+      root.quickExits = Date.now() - root.subscribedAt < 1000 ? root.quickExits + 1 : 0
+      if (root.nodeId >= 0 && root.quickExits < 5) resubscribe.start()
+    }
+    stdout: SplitParser {
+      onRead: function(line) {
+        if (String(line).indexOf(" on source #") !== -1) root.refresh()
+      }
+    }
+  }
+
+  Timer {
+    id: resubscribe
+    interval: 2000
+    onTriggered: if (root.nodeId >= 0 && !events.running) {
+      events.running = true
+      root.refresh()
+    }
+  }
+}

package/ui/boot/Commons/Util.qml

@@ -0,0 +1,188 @@
+pragma Singleton
+import Quickshell
+import QtQuick
+
+// Shared utility helpers used across plugins. Pure functions only — no
+// state. Anything stateful belongs on Color, Style, or a service.
+QtObject {
+  id: root
+
+  // Manual click forwarding must honor the same clipping as Qt's hit test.
+  // Collapsed drawers keep their children laid out beyond the visible edge.
+  function itemContainsPoint(target, source, x, y) {
+    if (!target || !target.contains(target.mapFromItem(source, x, y))) return false
+    for (var item = target; item; item = item.parent) {
+      if (!item.visible || item.opacity === 0 || !item.enabled) return false
+      if (item.clip && !item.contains(item.mapFromItem(source, x, y))) return false
+    }
+    return true
+  }
+
+  function clamp(value, min, max) {
+    var n = Number(value)
+    if (!isFinite(n)) return min
+    return Math.max(min, Math.min(max, n))
+  }
+
+  function clampAlpha(value) {
+    return clamp(value, 0, 1)
+  }
+
+  function wheelSteps(accumulator, delta) {
+    // Some mouse/compositor combinations scale a single notch well beyond
+    // Qt's conventional 120 units. Keep one event to one step while still
+    // accumulating the smaller deltas emitted by touchpads.
+    delta = Math.max(-120, Math.min(120, delta))
+    if (accumulator * delta < 0) accumulator = 0
+    var total = accumulator + delta
+    var steps = total < 0 ? Math.ceil(total / 120) : Math.floor(total / 120)
+    return { steps: steps, remainder: total - steps * 120 }
+  }
+
+  // Compose a base color with an opacity. Accepts a color object or a hex
+  // string; null/undefined yields transparent black at the requested alpha.
+  function alpha(c, opacity) {
+    var a = clampAlpha(opacity)
+    if (!c) return Qt.rgba(0, 0, 0, a)
+    if (typeof c === "string") c = Qt.color(c)
+    return Qt.rgba(c.r, c.g, c.b, a)
+  }
+
+  // file:// URL with each path segment percent-encoded so spaces and
+  // special chars in user paths don't break Image.source.
+  function fileUrl(path) {
+    if (!path) return ""
+    return "file://" + String(path).split("/").map(encodeURIComponent).join("/")
+  }
+
+  function isVideoPath(path) {
+    return /\.(mp4|m4v|mov|webm|mkv|avi)$/i.test(String(path || ""))
+  }
+
+  // Single-quote a string for bash. The replace handles embedded single
+  // quotes by closing, escaping, and re-opening the literal.
+  function shellQuote(value) {
+    return "'" + String(value || "").replace(/'/g, "'\\''") + "'"
+  }
+
+  function execDetached(command) {
+    Quickshell.execDetached(["bash", "-lc", command])
+  }
+
+  // Run an argv vector without a shell interpreting it: the constant `exec "$@"`
+  // means the args only ever land in positional parameters, which bash expands
+  // without re-tokenizing — so untrusted data ($(id), a filename) stays literal.
+  // The login shell (-l) keeps the PATH/session env GUI targets (omasnap, mpv,
+  // xdg-open) need. Prefer this over execDetached for anything built from input.
+  function execArgv(argv) {
+    Quickshell.execDetached(["bash", "-lc", 'exec "$@"', "bash"].concat(argv))
+  }
+
+  function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+  }
+
+  function canonicalWidgetId(id) {
+    return String(id || "")
+  }
+
+  // Best-effort base64 decode. Returns "" on parse failure rather than
+  // surfacing garbage downstream.
+  function decodeBase64(value) {
+    var s = String(value || "")
+    if (!s) return ""
+    try { return Qt.atob(s) } catch (e) { return "" }
+  }
+
+  function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value === undefined ? null : value))
+  }
+
+  // Parse the last line of a custom-module / indicator process output as
+  // waybar-style JSON ({text, class, tooltip, ...}). Falls back to {text: raw}
+  // when the output isn't JSON, and {} for empty output.
+  function parseModuleJson(raw) {
+    var text = String(raw || "").trim()
+    if (!text) return {}
+    var lines = text.split("\n")
+    try {
+      return JSON.parse(lines[lines.length - 1])
+    } catch (e) {
+      return { text: text }
+    }
+  }
+
+  // Standard Qt text-editing keys shared by every searchable panel's filter:
+  //   Backspace       delete previous character
+  //   Ctrl+Backspace  delete previous word (Qt DeleteStartOfWord)
+  //   Ctrl+U          clear the whole field
+  // True only when the event would actually change the text, so an empty
+  // filter never swallows the key — panels keep their own empty-filter
+  // fallbacks (e.g. menu back-navigation) in later branches.
+  // The arrow a horizontal key press means along the reading direction: in a
+  // right-to-left layout, mirrored, Left moves forward and Right back. With
+  // vim set, h and l count as Left and Right too.
+  function readingKey(event, vim) {
+    var key = event.key
+    if (vim && (key === Qt.Key_H || event.text === "h")) key = Qt.Key_Left
+    else if (vim && (key === Qt.Key_L || event.text === "l")) key = Qt.Key_Right
+    if (I18n.rightToLeft) {
+      if (key === Qt.Key_Left) return Qt.Key_Right
+      if (key === Qt.Key_Right) return Qt.Key_Left
+    }
+    return key
+  }
+
+  function editsFilter(event, text) {
+    if (!text) return false
+    // Alt/Meta-modified sequences belong to other shortcuts — never edit here.
+    if (event.modifiers & (Qt.AltModifier | Qt.MetaModifier)) return false
+    if (event.key === Qt.Key_U)                     // Ctrl+U only (not Ctrl+Shift+U → Unicode input)
+      return event.modifiers === Qt.ControlModifier
+    return event.key === Qt.Key_Backspace           // plain, Shift, or Ctrl Backspace
+  }
+
+  // New filter text after applying an edit key. Assumes editsFilter(event, text).
+  function editedFilter(event, text) {
+    if (event.key === Qt.Key_U) return ""                        // Ctrl+U: clear
+    if (event.modifiers & Qt.ControlModifier)                    // Ctrl+Backspace: word
+      return text.replace(/\s+$/, "").replace(/\S+$/, "")
+    return text.slice(0, -1)                                     // Backspace: char
+  }
+
+  // Layout normalization shared by bar config consumers
+  // so the two never drift. Entries are deep-cloned to decouple from the
+  // input config; consumers can mutate without leaking back to shell.json.
+  function normalizeLayoutEntry(entry) {
+    if (typeof entry === "string") return { id: canonicalWidgetId(entry) }
+    if (isPlainObject(entry) && entry.id) {
+      var copy = cloneJson(entry)
+      copy.id = canonicalWidgetId(copy.id)
+      return copy
+    }
+    return null
+  }
+
+  function normalizeLayoutSection(list) {
+    if (!Array.isArray(list)) return []
+    var out = []
+    for (var i = 0; i < list.length; i++) {
+      var e = normalizeLayoutEntry(list[i])
+      if (e) out.push(e)
+    }
+    return out
+  }
+
+  // The bar's sections in the order they run along it, and tray, drawn
+  // inside the tray's drawer. The center box sits in the middle of the bar;
+  // centerBegin and centerEnd hang off its two edges.
+  readonly property var barSections: ["left", "centerBegin", "center", "centerEnd", "right", "tray"]
+
+  function normalizeLayout(layout) {
+    var src = isPlainObject(layout) ? layout : {}
+    var out = {}
+    for (var i = 0; i < barSections.length; i++)
+      out[barSections[i]] = normalizeLayoutSection(src[barSections[i]])
+    return out
+  }
+}

package/ui/boot/Commons/qmldir

@@ -0,0 +1,13 @@
+module qs.Commons
+singleton AudioNodes 1.0 AudioNodes.qml
+singleton Border 1.0 Border.qml
+singleton Color 1.0 Color.qml
+singleton I18n 1.0 I18n.qml
+singleton InputDevices 1.0 InputDevices.qml
+singleton IpcRegistry 1.0 IpcRegistry.qml
+singleton InputMethodState 1.0 InputMethodState.qml
+singleton Style 1.0 Style.qml
+singleton UntypedInput 1.0 UntypedInput.qml
+singleton Util 1.0 Util.qml
+ShellIpc 1.0 ShellIpc.qml
+Translations 1.0 Translations.qml

package/ui/boot/LICENSE-omarchy

@@ -0,0 +1,20 @@
+Copyright (c) David Heinemeier Hansson
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/ui/boot/Ui/BackgroundMedia.qml

@@ -0,0 +1,49 @@
+import QtQuick
+import qs.Commons
+
+// The shell draws stills only. OWE owns video backgrounds on the desktop, and
+// it feeds the lock screen through its own socket.
+Item {
+  id: root
+
+  property string path: ""
+  property int version: 0
+  // Unversioned images cache by path. A caller whose version changes with every
+  // new file, as the lock's does, may cache too: the version is in the URL.
+  property bool cached: version === 0
+  // A caller that knows the size its screen needs, in physical pixels, sets
+  // constrainDecode and decodeSize. The image then waits for that size rather
+  // than decoding at the file's native size first.
+  property bool constrainDecode: false
+  property size decodeSize: Qt.size(0, 0)
+  readonly property var current: imageLoader.item
+  readonly property bool ready: current ? current.ready : false
+  // The file behind path could not be loaded, as when it was deleted.
+  readonly property bool failed: current ? current.failed : false
+  readonly property bool video: Util.isVideoPath(path)
+  // Cache-bust images selected in a running lock session, so a theme switch
+  // that replaces the file behind an unchanged path shows the new pixels.
+  readonly property url imageUrl: path && !video ? Util.fileUrl(path) + (version ? "?v=" + version : "") : ""
+
+  Loader {
+    id: imageLoader
+    anchors.fill: parent
+    active: root.path !== "" && !root.video
+    sourceComponent: imageComponent
+  }
+
+  Component {
+    id: imageComponent
+
+    Image {
+      readonly property bool ready: status === Image.Ready
+      readonly property bool failed: status === Image.Error
+      source: !root.constrainDecode || root.decodeSize.width > 0 ? root.imageUrl : ""
+      fillMode: Image.PreserveAspectCrop
+      asynchronous: true
+      cache: root.cached
+      sourceSize.width: root.constrainDecode ? root.decodeSize.width : (root.version > 0 ? width : 0)
+      sourceSize.height: root.constrainDecode ? root.decodeSize.height : (root.version > 0 ? height : 0)
+    }
+  }
+}

package/ui/boot/Ui/BarIconButton.qml

@@ -0,0 +1,106 @@
+import QtQuick
+import Quickshell
+import qs.Commons
+
+WidgetButton {
+  id: root
+
+  property Component iconComponent: null
+  property real slotSize: Style.bar.iconSlot
+  property real opticalSize: Style.bar.iconCanvas
+  property real iconSize: Math.min(Style.bar.iconSize, opticalSize)
+  readonly property real visualIconSize: Style.bar.iconSize
+  readonly property real canvasSize: Math.max(visualIconSize, opticalSize)
+  property string labelText: ""
+  property bool debugOpticalBounds: Quickshell.env("OMARCHY_DEBUG_BAR_ICONS") === "1"
+  // A label shifts the icon within the centered group.
+  readonly property real opticalCenterErrorX:
+    content.x + opticalCanvas.x + (glyph.visible ? glyph.paintedCenterX : customIcon.width / 2 + customIcon.centerErrorX) - root.width / 2
+      - (label.visible ? (label.implicitWidth + Style.space(4)) / 2 : 0)
+  readonly property real opticalCenterErrorY:
+    content.y + (glyph.visible ? glyph.paintedCenterY : customIcon.height / 2 + customIcon.centerErrorY) - root.height / 2
+  readonly property real glyphPaintedWidth: glyph.visible ? glyph.paintedWidth : 0
+  readonly property real glyphPaintedHeight: glyph.visible ? glyph.paintedHeight : 0
+  readonly property real glyphBaselineY: glyph.visible ? glyph.baselineY : 0
+  readonly property int glyphFontSize: glyph.visible ? glyph.renderedFontSize : 0
+  readonly property real componentPaintedWidth: customIcon.visible ? customIcon.paintedWidth : 0
+  readonly property real componentPaintedHeight: customIcon.visible ? customIcon.paintedHeight : 0
+  readonly property rect componentSourceBounds: customIcon.sourceBounds
+
+  labelVisible: false
+  hasVisualContent: text !== "" || iconComponent !== null || labelText !== ""
+  fontSize: Style.bar.iconFont
+  fixedWidth: vertical ? -1 : slotSize
+  fixedHeight: vertical ? slotSize : -1
+
+  Item {
+    id: content
+    // Exact coordinates preserve the center of odd-width slots.
+    x: (root.width - width) / 2
+    y: (root.height - height) / 2
+    width: root.canvasSize + (label.visible ? label.implicitWidth + Style.space(4) : 0)
+    height: root.canvasSize
+
+    Text {
+      id: label
+      visible: root.labelText !== ""
+      textFormat: Text.PlainText
+      text: root.labelText
+      font.family: root.fontFamily
+      font.pixelSize: root.fontSize
+      color: root.active && root.useActiveColor ? root.activeColor : root.foreground
+      y: (parent.height - height) / 2
+        + (labelMetrics.descent - labelMetrics.ascent + labelMetrics.tightBoundingRect("0").height) / 2
+      renderType: Text.NativeRendering
+    }
+
+    FontMetrics {
+      id: labelMetrics
+      font: label.font
+    }
+
+    Item {
+      id: opticalCanvas
+      x: label.visible ? label.implicitWidth + Style.space(4) : 0
+      width: root.canvasSize
+      height: root.canvasSize
+
+      OpticalGlyph {
+        id: glyph
+        anchors.fill: parent
+        visible: root.iconComponent === null
+        text: root.text
+        fontFamily: root.fontFamily
+        fontSize: root.fontSize
+        paintedSize: root.visualIconSize
+        color: root.active && root.useActiveColor ? root.activeColor : root.foreground
+        rotation: root.textRotation
+        debugBounds: root.debugOpticalBounds
+      }
+
+      BarIconContent {
+        id: customIcon
+        anchors.fill: parent
+        visible: root.iconComponent !== null
+        sourceComponent: root.iconComponent
+        sourceSize: root.opticalSize
+      }
+
+      Rectangle {
+        visible: root.debugOpticalBounds && root.iconComponent !== null
+        anchors.fill: parent
+        color: "transparent"
+        border.width: 1
+        border.color: "#4488ff"
+      }
+    }
+  }
+
+  Rectangle {
+    visible: root.debugOpticalBounds
+    anchors.fill: parent
+    color: "transparent"
+    border.width: 1
+    border.color: "#ff4455"
+  }
+}

package/ui/boot/Ui/BarIconContent.qml

@@ -0,0 +1,38 @@
+import QtQuick
+import qs.Commons
+
+Item {
+  id: root
+
+  property Component sourceComponent: null
+  property real sourceSize: Style.bar.iconCanvas
+  readonly property rect sourceBounds: bounds.mappedBounds
+  readonly property real contentScale: sourceBounds.width > 0 && sourceBounds.height > 0
+    ? Style.bar.iconSize / Math.max(sourceBounds.width, sourceBounds.height) : 1
+  readonly property real paintedWidth: sourceBounds.width * contentScale
+  readonly property real paintedHeight: sourceBounds.height * contentScale
+  readonly property real centerErrorX: content.x + (sourceBounds.x + sourceBounds.width / 2) * contentScale - width / 2
+  readonly property real centerErrorY: content.y + (sourceBounds.y + sourceBounds.height / 2) * contentScale - height / 2
+
+  Loader {
+    id: content
+    sourceComponent: root.sourceComponent
+    onLoaded: {
+      // Keep declared dimensions. Empty wrapper items receive a source canvas.
+      if (!(item instanceof Image)) {
+        if (item.width <= 0) item.width = Qt.binding(function() { return root.sourceSize })
+        if (item.height <= 0) item.height = Qt.binding(function() { return root.sourceSize })
+      }
+    }
+    transformOrigin: Item.TopLeft
+    scale: root.contentScale
+    x: root.width / 2 - (root.sourceBounds.x + root.sourceBounds.width / 2) * scale
+    y: root.height / 2 - (root.sourceBounds.y + root.sourceBounds.height / 2) * scale
+  }
+
+  IconContentBounds {
+    id: bounds
+    sourceItem: content.item
+    boundsParent: content
+  }
+}

package/ui/boot/Ui/BarIndicator.qml

@@ -0,0 +1,53 @@
+import QtQuick
+import qs.Commons
+
+BarIconButton {
+  id: root
+
+  property string moduleName: ""
+  property var settings: ({})
+  property string activeText: ""
+  property string inactiveText: activeText
+  property string activeTooltipText: ""
+  property string inactiveTooltipText: activeTooltipText
+  property string indicatorBlock: "single"
+  property var indicatorHost: null
+  property var activeOverride: null
+  // An indicator with nothing to turn on, such as a remote session, shows only
+  // while it is active, never among the inactive ones a hover reveals.
+  property bool revealWhenInactive: true
+  readonly property bool effectiveActive: activeOverride === null || activeOverride === undefined ? active : activeOverride === true
+  readonly property bool belongsInBlock: indicatorBlock === "active" ? effectiveActive : (indicatorBlock === "inactive" ? !effectiveActive && revealWhenInactive : true)
+  readonly property bool inactiveRevealed: !effectiveActive && revealWhenInactive && !!indicatorHost && indicatorHost.revealInactiveIndicators
+
+  function extractData(raw) {
+    return Util.parseModuleJson(raw)
+  }
+
+  function syncIndicatorOpacity() {
+    root.opacity = !belongsInBlock ? 0 : (effectiveActive ? 1 : (inactiveRevealed ? 0.45 : 0))
+  }
+
+  Component.onCompleted: syncIndicatorOpacity()
+  onActiveChanged: syncIndicatorOpacity()
+  onEffectiveActiveChanged: syncIndicatorOpacity()
+  onBarChanged: syncIndicatorOpacity()
+  onBelongsInBlockChanged: syncIndicatorOpacity()
+  onInactiveRevealedChanged: syncIndicatorOpacity()
+  onIndicatorBlockChanged: syncIndicatorOpacity()
+
+  visible: belongsInBlock && (text !== "" || keepSpace)
+  text: effectiveActive ? activeText : inactiveText
+  tooltipText: effectiveActive ? activeTooltipText : inactiveTooltipText
+  keepSpace: true
+  dimmed: !effectiveActive
+  concealed: !effectiveActive && !inactiveRevealed
+  interactive: belongsInBlock && (effectiveActive || indicatorBlock === "inactive" || inactiveRevealed)
+  useActiveColor: false
+  maintainIndicatorReveal: indicatorBlock === "inactive"
+  revealHost: indicatorHost
+  horizontalMargin: 5
+  verticalPadding: 5
+  fixedWidth: vertical ? -1 : Style.bar.statusSlot
+  fixedHeight: vertical ? Style.bar.statusSlot : -1
+}

package/ui/boot/Ui/BarWidget.qml

@@ -0,0 +1,50 @@
+import QtQuick
+import qs.Commons
+
+// Base item every bar widget extends. Codifies the properties the bar host
+// injects into each widget slot:
+//   bar         - the host Bar instance (foreground/background/run/etc).
+//   moduleName  - widget's canonical id, used by the host registry to look
+//                 up settings and to disambiguate inline IPC routes.
+//   settings    - per-widget overrides read from shell.json's layout entry.
+//   fixedEdge   - the edge of the widget that stays put when it grows:
+//                 "start" (left, or top on a vertical bar), "end", or
+//                 "center" when it grows both ways. Content laid out
+//                 against it stays put while the widget grows.
+//
+// Widgets are free to add their own properties, signals, and child items.
+Item {
+  id: root
+
+  property QtObject bar: null
+  property string moduleName: ""
+  property var settings: ({})
+  property string fixedEdge: "center"
+
+  // Bar geometry, lifted off the host. Widgets read these constantly to pick
+  // between horizontal/vertical layouts; defining them on the base keeps the
+  // `bar ? bar.x : fallback` ternary out of every widget body.
+  readonly property bool vertical: bar ? bar.vertical : false
+  readonly property int barSize: bar ? bar.barSize : Style.bar.sizeHorizontal
+
+  // Run `method` on every live instance of this widget. An IPC target only
+  // ever routes to one handler, but a bar surface exists per monitor, so the
+  // instance that owns the target relays the call to its peers — otherwise a
+  // refresh would land on a single screen and leave the others stale.
+  function broadcast(method) {
+    var items = bar && typeof bar.moduleWidgets === "function"
+      ? bar.moduleWidgets(moduleName) : [root]
+    for (var i = 0; i < items.length; i++) {
+      if (items[i] && typeof items[i][method] === "function") items[i][method]()
+    }
+  }
+
+  // Read a single value from this widget's inline shell.json entry, with a
+  // fallback for missing/null values. Every widget that takes user-tunable
+  // settings needs this; defining it once on the base keeps the wiring
+  // consistent.
+  function setting(name, fallback) {
+    var value = settings ? settings[name] : undefined
+    return value === undefined || value === null ? fallback : value
+  }
+}