feat(studio): color-variant swatch picker for color fields (#1833)

* feat(studio): color-variant swatch picker for color fields

Color fields (`colorVariant` on metrics / dashboard widgets, etc.) are a fixed
semantic palette but were edited as text dropdowns — the admin couldn't see the
actual color. Add a shared swatch picker (colored circles, selected ring) used
everywhere:

- color-variant-field: shared COLOR_VARIANTS palette + ColorVariantPicker.
- widgets: 'color-picker' widget (enum -> swatch row; free string -> native hex
  input) + registry entry.
- SchemaForm: auto-detect color fields by name convention (color/colorVariant/
  *Color) so generic forms get the picker without per-form wiring.
- DashboardWidgetInspector: Color Variant now a swatch row.
- block-config + PageBlockInspector: new 'color' field kind; object-metric
  Color renders as swatches.

Verified live: page object-metric Color and dashboard widget Color Variant both
render the swatch row with the correct color selected.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test(studio): allow the new 'color' block-config field kind

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

packages/app-shell/src/views/metadata-admin/SchemaForm.tsx

@@ -295,6 +295,22 @@ function detectIconWidget(name: string, schema: JsonSchema | undefined): string
   return undefined;
 }
 
+/**
+ * Detect the color swatch picker by NAME CONVENTION: a string field named
+ * `color`, `colorVariant`, or `*Color`. An enum gets the semantic swatch row;
+ * a free string gets the native hex picker. Mirrors the icon/field-ref
+ * conventions so color fields are consistent across every metadata type.
+ */
+function detectColorWidget(name: string, schema: JsonSchema | undefined): string | undefined {
+  const isString =
+    schema?.type === 'string' ||
+    Array.isArray(schema?.enum) ||
+    (Array.isArray(schema?.anyOf) && (schema!.anyOf as JsonSchema[]).some((b) => b?.type === 'string'));
+  if (!isString) return undefined;
+  if (name === 'color' || name === 'colorVariant' || /Color$/.test(name)) return 'color-picker';
+  return undefined;
+}
+
 /* -------------------------------------------------------------------------- */
 /* FormView spec (subset)                                                     */
 /* -------------------------------------------------------------------------- */
@@ -758,6 +774,10 @@ function FieldRow({
     else {
       const iconWidget = detectIconWidget(name, schema);
       if (iconWidget) widget = iconWidget;
+      else {
+        const colorWidget = detectColorWidget(name, schema);
+        if (colorWidget) widget = colorWidget;
+      }
     }
   }
 

packages/app-shell/src/views/metadata-admin/color-variant-field.tsx

@@ -0,0 +1,83 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Shared color-variant swatch picker.
+ *
+ * Metadata color fields (`colorVariant` on metrics / dashboard widgets, badge
+ * tones, …) are a fixed SEMANTIC palette, not arbitrary hex. A row of colored
+ * swatches is far more scannable than a text dropdown — the admin sees the
+ * actual color, like Linear/Notion label pickers. Reused by the generic
+ * SchemaForm `color-picker` widget and the curated inspectors so every color
+ * field looks and behaves the same.
+ */
+
+import * as React from 'react';
+import { cn } from '@object-ui/components';
+
+export interface ColorVariant { value: string; label: string; css: string }
+
+/** Canonical semantic palette (mirrors the renderer's colorVariant tokens). */
+export const COLOR_VARIANTS: ColorVariant[] = [
+  { value: 'default', label: 'Default', css: '#9ca3af' },
+  { value: 'blue', label: 'Blue', css: '#3b82f6' },
+  { value: 'teal', label: 'Teal', css: '#14b8a6' },
+  { value: 'orange', label: 'Orange', css: '#f97316' },
+  { value: 'purple', label: 'Purple', css: '#a855f7' },
+  { value: 'success', label: 'Success', css: '#22c55e' },
+  { value: 'warning', label: 'Warning', css: '#f59e0b' },
+  { value: 'danger', label: 'Danger', css: '#ef4444' },
+  // common aliases so non-canonical tokens still get a sensible swatch
+  { value: 'green', label: 'Green', css: '#22c55e' },
+  { value: 'red', label: 'Red', css: '#ef4444' },
+  { value: 'amber', label: 'Amber', css: '#f59e0b' },
+];
+
+const CSS_BY_VALUE: Record<string, string> = Object.fromEntries(COLOR_VARIANTS.map((c) => [c.value, c.css]));
+
+/** Resolve a token (or hex) to a CSS color; unknown tokens fall back to neutral. */
+export function colorVariantCss(value: string | undefined): string {
+  if (!value) return '#9ca3af';
+  if (/^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(value)) return value;
+  return CSS_BY_VALUE[value] ?? '#9ca3af';
+}
+
+export function ColorVariantPicker({ value, onChange, disabled, options }: {
+  value: string | undefined;
+  onChange: (v: string) => void;
+  disabled?: boolean;
+  /** Restrict/relabel the choices; defaults to the full canonical palette. */
+  options?: Array<{ value: string; label?: string }>;
+}) {
+  const opts: ColorVariant[] = options
+    ? options.map((o) => ({ value: o.value, label: o.label ?? o.value, css: colorVariantCss(o.value) }))
+    : COLOR_VARIANTS.slice(0, 8); // canonical 8 (skip aliases in the default row)
+  const current = value ?? 'default';
+  return (
+    <div className="flex flex-wrap gap-1.5" role="radiogroup">
+      {opts.map((o) => {
+        const on = current === o.value;
+        return (
+          <button
+            key={o.value}
+            type="button"
+            role="radio"
+            aria-checked={on}
+            aria-label={o.label}
+            title={o.label}
+            disabled={disabled}
+            onClick={() => onChange(o.value)}
+            className={cn(
+              'flex h-7 w-7 items-center justify-center rounded-full border transition-all',
+              on
+                ? 'border-transparent ring-2 ring-foreground/60 ring-offset-1 ring-offset-background'
+                : 'border-border hover:scale-110',
+              disabled && 'cursor-not-allowed opacity-50',
+            )}
+          >
+            <span className="h-4 w-4 rounded-full" style={{ backgroundColor: o.css }} />
+          </button>
+        );
+      })}
+    </div>
+  );
+}

packages/app-shell/src/views/metadata-admin/inspectors/DashboardWidgetInspector.tsx

@@ -17,6 +17,7 @@
  */
 
 import * as React from 'react';
+import { ColorVariantPicker } from '../color-variant-field';
 import { X } from 'lucide-react';
 import {
   Button,
@@ -296,26 +297,12 @@ export function DashboardWidgetInspector({
       </Field>
 
       <Field id="widget-color" label={t('engine.inspector.widget.color', locale)}>
-        <Select
+        <ColorVariantPicker
           value={widget.colorVariant ?? 'default'}
-          onValueChange={(v) =>
-            patchWidget({
-              colorVariant: v as DashboardWidgetSchema['colorVariant'],
-            })
-          }
+          onChange={(v) => patchWidget({ colorVariant: v as DashboardWidgetSchema['colorVariant'] })}
           disabled={readOnly}
-        >
-          <SelectTrigger id="widget-color">
-            <SelectValue />
-          </SelectTrigger>
-          <SelectContent>
-            {COLORS.map((c) => (
-              <SelectItem key={c} value={c}>
-                {c}
-              </SelectItem>
-            ))}
-          </SelectContent>
-        </Select>
+          options={COLORS.map((c) => ({ value: c }))}
+        />
       </Field>
 
       <div className="grid grid-cols-2 gap-3">

packages/app-shell/src/views/metadata-admin/inspectors/PageBlockInspector.tsx

@@ -26,6 +26,7 @@ import {
   moveArray,
 } from './_shared';
 import { BLOCK_CONFIG, blockHasConfig, type BlockPropField } from '../previews/block-config';
+import { ColorVariantPicker } from '../color-variant-field';
 import { useObjectOptions } from '../previews/useObjectOptions';
 import { useObjectFields } from '../previews/useObjectFields';
 import {
@@ -384,6 +385,18 @@ export function PageBlockInspector({ selection, draft, onPatch, onClearSelection
           <InspectorCheckboxField key={k} label={f.label} value={!!read(f.name)}
             onCommit={(v) => write(f.name, v)} disabled={readOnly} />
         );
+      case 'color':
+        return (
+          <div key={k} className="space-y-1">
+            <Label className="text-xs text-muted-foreground">{f.label}</Label>
+            <ColorVariantPicker
+              value={read(f.name) != null ? String(read(f.name)) : undefined}
+              onChange={(v) => write(f.name, v)}
+              disabled={readOnly}
+              options={f.options}
+            />
+          </div>
+        );
       case 'select':
         return (
           <InspectorSelectField key={k} label={f.label}

packages/app-shell/src/views/metadata-admin/previews/__tests__/block-config.test.ts

@@ -44,7 +44,7 @@ describe('block-config', () => {
   it('every field (incl. nested array items) has a name, label and valid kind', () => {
     const kinds = new Set([
       'text', 'number', 'boolean', 'select', 'string-list', 'array',
-      'object-picker', 'field-picker', 'field-list',
+      'object-picker', 'field-picker', 'field-list', 'color',
     ]);
     const check = (f: any, path: string) => {
       expect(f.name, `${path}.name`).toBeTruthy();

packages/app-shell/src/views/metadata-admin/previews/block-config.ts

@@ -26,6 +26,7 @@ export type BlockPropField =
   | { name: string; label: string; kind: 'select'; options: Array<{ value: string; label: string }> }
   | { name: string; label: string; kind: 'string-list'; placeholder?: string }
   | { name: string; label: string; kind: 'array'; itemFields: BlockPropField[]; addLabel?: string }
+  | { name: string; label: string; kind: 'color'; options?: Array<{ value: string; label: string }> }
   // Schema-driven pickers — dropdowns populated from the live metadata.
   | { name: string; label: string; kind: 'object-picker'; placeholder?: string }
   | ({ name: string; label: string; kind: 'field-picker'; placeholder?: string } & ObjectSource)
@@ -92,7 +93,7 @@ export const BLOCK_CONFIG: Record<string, BlockPropField[]> = {
     { name: 'description', label: 'Description', kind: 'text' },
     { name: 'icon', label: 'Icon', kind: 'text', placeholder: 'lucide icon name' },
     {
-      name: 'colorVariant', label: 'Color', kind: 'select',
+      name: 'colorVariant', label: 'Color', kind: 'color',
       options: [
         { value: 'default', label: 'Default' },
         { value: 'blue', label: 'Blue' },

packages/app-shell/src/views/metadata-admin/widgets.tsx

@@ -41,6 +41,7 @@ import { ChevronDown, ChevronsUpDown, ChevronUp, Plus, Search, Trash2 } from 'lu
 // @ts-ignore - lucide-react has no `exports` field; subpath types live alongside dynamic.mjs
 import { iconNames } from 'lucide-react/dynamic.mjs';
 import { detectLocale, t } from './i18n';
+import { ColorVariantPicker } from './color-variant-field';
 
 export interface WidgetContext {
   /** Names of all object metadata records (for `ref:object`). */
@@ -1584,6 +1585,52 @@ function FilterBuilderWidget({ value, onChange, readOnly, context }: WidgetProps
   );
 }
 
+/* -------------------------------------------------------------------------- */
+/* color-picker — semantic swatch row (enum) or native hex input (free color) */
+/* -------------------------------------------------------------------------- */
+
+function ColorPickerWidget({ value, onChange, readOnly, schema, fieldSpec }: WidgetProps) {
+  const enumOpts: Array<{ value: string; label?: string }> | null =
+    Array.isArray(fieldSpec?.options) && fieldSpec!.options!.length
+      ? fieldSpec!.options!.map((o) => ({ value: o.value, label: o.label }))
+      : Array.isArray(schema?.enum)
+        ? (schema!.enum as unknown[]).filter((v): v is string => typeof v === 'string').map((v) => ({ value: v }))
+        : null;
+
+  if (enumOpts && enumOpts.length) {
+    return (
+      <ColorVariantPicker
+        value={value == null ? undefined : String(value)}
+        onChange={(v) => onChange(v)}
+        disabled={readOnly}
+        options={enumOpts}
+      />
+    );
+  }
+
+  // Free color → native picker + hex text.
+  const v = value == null ? '' : String(value);
+  return (
+    <div className="flex items-center gap-2">
+      <input
+        type="color"
+        value={/^#([0-9a-f]{6})$/i.test(v) ? v : '#000000'}
+        disabled={readOnly}
+        onChange={(e) => onChange(e.target.value)}
+        className="h-8 w-10 shrink-0 rounded border border-input bg-background p-0.5 disabled:opacity-60"
+        aria-label="Color"
+      />
+      <Input
+        value={v}
+        placeholder="#RRGGBB"
+        disabled={readOnly}
+        onChange={(e) => onChange(e.target.value || undefined)}
+        className="h-8 text-sm font-mono"
+      />
+    </div>
+  );
+}
+
 export const WIDGETS: Record<string, WidgetRenderer> = {
   'ref:object': RefObjectWidget,
   'filter-mode': FilterModeWidget,
@@ -1595,6 +1642,7 @@ export const WIDGETS: Record<string, WidgetRenderer> = {
   'filter-builder': FilterBuilderWidget,
   'view-ref': ViewRefWidget,
   'icon': IconPickerWidget,
+  'color-picker': ColorPickerWidget,
   'master-detail': MasterDetailWidget,
   'string-tags': StringTagsWidget,
   'multiselect': MultiSelectWidget,