From 5648a0f2a1489b2e8ba6c03c9473f1978c6d487c Mon Sep 17 00:00:00 2001
From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Date: Wed, 15 Jul 2026 22:24:26 +0800
Subject: [PATCH] feat(spec): page variable source renders as a component
 picker (objectui#2328)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The page form's `variables` repeater now declares explicit sub-fields and pins
`{ field: 'source', widget: 'ref:component' }` so Studio can pick a page
variable's `source` (the component that writes it) from the page's real
components instead of a free-text id — mirroring the sibling `object`
`ref:object` picker. The `ref:component` widget ships in objectui.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/page-var-source-component-picker.md | 13 +++++++++++++
 packages/spec/src/ui/page.form.ts              | 16 +++++++++++++++-
 2 files changed, 28 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/page-var-source-component-picker.md

diff --git a/.changeset/page-var-source-component-picker.md b/.changeset/page-var-source-component-picker.md
new file mode 100644
index 0000000000..6c40914960
--- /dev/null
+++ b/.changeset/page-var-source-component-picker.md
@@ -0,0 +1,13 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec): page variable `source` renders as a component picker (objectui#2328)
+
+The page metadata form's `variables` repeater now declares explicit sub-fields
+and pins `{ field: 'source', widget: 'ref:component' }`. A page variable's
+`source` names the component (by `id`) that writes it, so Studio can offer it as
+a dropdown of the components actually placed on the page — mirroring how the
+sibling `object` field uses `ref:object` — instead of a free-text input the
+author has to type an id into by hand. The `ref:component` widget itself lives
+in objectui (app-shell metadata-admin); this change is the form-spec trigger.
diff --git a/packages/spec/src/ui/page.form.ts b/packages/spec/src/ui/page.form.ts
index f6d88c3bcc..cd58204e01 100644
--- a/packages/spec/src/ui/page.form.ts
+++ b/packages/spec/src/ui/page.form.ts
@@ -52,7 +52,21 @@ export const pageForm = defineForm({
       visibleWhen: "data.type != 'list'",
       fields: [
         { field: 'object', widget: 'ref:object', helpText: 'Bound object (for Record pages)' },
-        { field: 'variables', type: 'repeater', helpText: 'Local page state variables' },
+        {
+          field: 'variables',
+          type: 'repeater',
+          helpText: 'Local page state variables',
+          // Explicit sub-fields so `source` can use the `ref:component` picker —
+          // a variable's `source` names the component (by `id`) that writes it,
+          // so it's chosen from the page's real canvas components, not typed by
+          // hand. Keep in sync with PageVariableSchema.
+          fields: [
+            { field: 'name', required: true, helpText: 'Variable name — exposed to expressions as `page.<name>`' },
+            { field: 'type', helpText: 'Value type' },
+            { field: 'defaultValue', helpText: 'Initial value (defaults to a type-appropriate empty value)' },
+            { field: 'source', widget: 'ref:component', helpText: 'Component (by id) that writes this variable — e.g. an element:record_picker' },
+          ],
+        },
       ],
     },
     {