From d4bf8d0eeac2ec5926bbba5aba80bf25163b67f4 Mon Sep 17 00:00:00 2001
From: Ryan Hughes <ryan@heyoodle.com>
Date: Mon, 18 May 2026 12:36:46 -0400
Subject: [PATCH] omarchy dev ui-preview: jump to a specific section via
 argument

Pass a section name to open the gallery with the cursor already on
that component instead of scrolling from the top. Useful when
iterating on a single widget.

  omarchy dev ui-preview              # default position
  omarchy dev ui-preview button       # land on the Button section
  omarchy dev ui-preview button-group # land on ButtonGroup
  omarchy dev ui-preview slider       # land on Slider, etc.

The bin script forwards the argument as {"section": "..."} in the
shell summon payload. The gallery's open(payloadJson) parses it,
clamps against visibleSections (unknown names fall back to default),
and sets focusSection + selectedIndex inside the existing Qt.callLater
so the cursor's hasCursor bindings fire ensureCursorVisible
automatically.
---
 bin/omarchy-dev-ui-preview                 | 17 ++++++++++++++-
 shell/plugins/dev-gallery/GalleryPanel.qml | 24 +++++++++++++++++++---
 2 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/bin/omarchy-dev-ui-preview b/bin/omarchy-dev-ui-preview
index 3c209d10..20c1d133 100755
--- a/bin/omarchy-dev-ui-preview
+++ b/bin/omarchy-dev-ui-preview
@@ -1,5 +1,20 @@
 #!/bin/bash
 
 # omarchy:summary=Open the omarchy-shell dev gallery (qs.Ui kit preview)
+# omarchy:args=[section]
+# omarchy:examples=omarchy dev ui-preview | omarchy dev ui-preview button | omarchy dev ui-preview button-group | omarchy dev ui-preview slider
+#
+# Pass a section name to jump straight to that component instead of
+# scrolling from the top. Section names match the cursor section ids in
+# shell/plugins/dev-gallery/GalleryPanel.qml — `button`, `button-group`,
+# `cursor-surface`, `slider`, `toggle`, `dropdown`, etc. Unknown names
+# are ignored and the gallery opens at its normal default position.
 
-omarchy-shell shell summon omarchy.dev-gallery '{}'
+if [[ $# -gt 0 && -n $1 ]]; then
+  section="$1"
+  payload=$(printf '{"section":"%s"}' "${section//\"/}")
+else
+  payload='{}'
+fi
+
+omarchy-shell shell summon omarchy.dev-gallery "$payload"
diff --git a/shell/plugins/dev-gallery/GalleryPanel.qml b/shell/plugins/dev-gallery/GalleryPanel.qml
index 982c7a2a..2a7f0520 100644
--- a/shell/plugins/dev-gallery/GalleryPanel.qml
+++ b/shell/plugins/dev-gallery/GalleryPanel.qml
@@ -21,10 +21,28 @@ Item {
   function open(payloadJson) {
     closingFromHost = false
     window.visible = true
-    // Defer focus so the FloatingWindow's content tree is in place; the
-    // hasCursor bindings on each demo target scroll themselves into view
-    // via onHasCursorChanged, so no explicit scroll call is needed here.
+
+    // Optional { section: "button" } in the payload lets `omarchy dev
+    // ui-preview <section>` open the gallery with the cursor already on
+    // a specific component, so iterating on one widget doesn't require
+    // scrolling from the top each time. Unknown section names are
+    // ignored — the gallery opens at its default position.
+    var requested = ""
+    if (payloadJson) {
+      try {
+        var parsed = JSON.parse(String(payloadJson))
+        if (parsed && typeof parsed.section === "string") requested = parsed.section
+      } catch (e) { /* ignore */ }
+    }
+
+    // Defer the section assignment + focus so the FloatingWindow's
+    // content tree is mounted. The hasCursor bindings on each demo
+    // target then scroll themselves into view via onHasCursorChanged.
     Qt.callLater(function() {
+      if (requested && visibleSections.indexOf(requested) !== -1) {
+        focusSection = requested
+        selectedIndex = sectionFirstIndex(requested)
+      }
       if (keyCatcher) keyCatcher.forceActiveFocus()
     })
   }