Merge pull request #699 from objectstack-ai/copilot/implement-element-library-and-builder

Author: hotlong

packages/spec/src/studio/index.ts

@@ -81,3 +81,17 @@ export {
   // Object Designer Helpers
   defineObjectDesignerConfig,
 } from './object-designer.zod';
+
+export {
+  // Interface Builder Schemas
+  CanvasSnapSettingsSchema,
+  CanvasZoomSettingsSchema,
+  ElementPaletteItemSchema,
+  InterfaceBuilderConfigSchema,
+
+  // Interface Builder Types
+  type CanvasSnapSettings,
+  type CanvasZoomSettings,
+  type ElementPaletteItem,
+  type InterfaceBuilderConfig,
+} from './interface-builder.zod';

packages/spec/src/studio/interface-builder.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from 'vitest';
+import {
+  CanvasSnapSettingsSchema,
+  CanvasZoomSettingsSchema,
+  ElementPaletteItemSchema,
+  InterfaceBuilderConfigSchema,
+  type InterfaceBuilderConfig,
+} from './interface-builder.zod';
+
+// ---------------------------------------------------------------------------
+// CanvasSnapSettingsSchema
+// ---------------------------------------------------------------------------
+describe('CanvasSnapSettingsSchema', () => {
+  it('should accept empty config with defaults', () => {
+    const settings = CanvasSnapSettingsSchema.parse({});
+    expect(settings.enabled).toBe(true);
+    expect(settings.gridSize).toBe(8);
+    expect(settings.showGrid).toBe(true);
+    expect(settings.showGuides).toBe(true);
+  });
+
+  it('should accept custom snap settings', () => {
+    const settings = CanvasSnapSettingsSchema.parse({
+      enabled: false,
+      gridSize: 16,
+      showGrid: false,
+      showGuides: false,
+    });
+    expect(settings.enabled).toBe(false);
+    expect(settings.gridSize).toBe(16);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CanvasZoomSettingsSchema
+// ---------------------------------------------------------------------------
+describe('CanvasZoomSettingsSchema', () => {
+  it('should accept empty config with defaults', () => {
+    const settings = CanvasZoomSettingsSchema.parse({});
+    expect(settings.min).toBe(0.25);
+    expect(settings.max).toBe(3);
+    expect(settings.default).toBe(1);
+    expect(settings.step).toBe(0.1);
+  });
+
+  it('should accept custom zoom settings', () => {
+    const settings = CanvasZoomSettingsSchema.parse({
+      min: 0.5,
+      max: 5,
+      default: 1.5,
+      step: 0.25,
+    });
+    expect(settings.min).toBe(0.5);
+    expect(settings.max).toBe(5);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ElementPaletteItemSchema
+// ---------------------------------------------------------------------------
+describe('ElementPaletteItemSchema', () => {
+  it('should accept valid palette item', () => {
+    const item = ElementPaletteItemSchema.parse({
+      type: 'element:button',
+      label: 'Button',
+      category: 'interactive',
+    });
+    expect(item.type).toBe('element:button');
+    expect(item.defaultWidth).toBe(4);
+    expect(item.defaultHeight).toBe(2);
+  });
+
+  it('should accept all category values', () => {
+    const categories = ['content', 'interactive', 'data', 'layout'] as const;
+    categories.forEach(category => {
+      expect(() => ElementPaletteItemSchema.parse({
+        type: 'element:text',
+        label: 'Text',
+        category,
+      })).not.toThrow();
+    });
+  });
+
+  it('should reject without required fields', () => {
+    expect(() => ElementPaletteItemSchema.parse({})).toThrow();
+    expect(() => ElementPaletteItemSchema.parse({ type: 'element:text' })).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// InterfaceBuilderConfigSchema
+// ---------------------------------------------------------------------------
+describe('InterfaceBuilderConfigSchema', () => {
+  it('should accept empty config with defaults', () => {
+    const config: InterfaceBuilderConfig = InterfaceBuilderConfigSchema.parse({});
+    expect(config.showLayerPanel).toBe(true);
+    expect(config.showPropertyPanel).toBe(true);
+    expect(config.undoLimit).toBe(50);
+  });
+
+  it('should accept full builder config', () => {
+    const config = InterfaceBuilderConfigSchema.parse({
+      snap: { enabled: true, gridSize: 4 },
+      zoom: { min: 0.5, max: 2 },
+      palette: [
+        { type: 'element:button', label: 'Button', category: 'interactive' },
+        { type: 'element:text', label: 'Text', category: 'content' },
+      ],
+      showLayerPanel: false,
+      showPropertyPanel: true,
+      undoLimit: 100,
+    });
+
+    expect(config.snap?.gridSize).toBe(4);
+    expect(config.palette).toHaveLength(2);
+    expect(config.undoLimit).toBe(100);
+  });
+});

packages/spec/src/studio/interface-builder.zod.ts

@@ -0,0 +1,69 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * @module studio/interface-builder
+ *
+ * Studio Interface Builder Protocol
+ *
+ * Defines the specification for the drag-and-drop Interface Builder UI.
+ * The builder allows visual composition of blank pages by placing
+ * elements on a grid canvas with snapping, alignment, and layer ordering.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Canvas Snap Settings Schema
+ * Controls grid snapping behavior during element placement.
+ */
+export const CanvasSnapSettingsSchema = z.object({
+  enabled: z.boolean().default(true).describe('Enable snap-to-grid'),
+  gridSize: z.number().int().min(1).default(8).describe('Snap grid size in pixels'),
+  showGrid: z.boolean().default(true).describe('Show grid overlay on canvas'),
+  showGuides: z.boolean().default(true).describe('Show alignment guides when dragging'),
+});
+
+/**
+ * Canvas Zoom Settings Schema
+ * Controls zoom behavior for the builder canvas.
+ */
+export const CanvasZoomSettingsSchema = z.object({
+  min: z.number().min(0.1).default(0.25).describe('Minimum zoom level'),
+  max: z.number().max(10).default(3).describe('Maximum zoom level'),
+  default: z.number().default(1).describe('Default zoom level'),
+  step: z.number().default(0.1).describe('Zoom step increment'),
+});
+
+/**
+ * Element Palette Item Schema
+ * An element available in the builder palette for drag-and-drop placement.
+ */
+export const ElementPaletteItemSchema = z.object({
+  type: z.string().describe('Component type (e.g. "element:button", "element:text")'),
+  label: z.string().describe('Display label in palette'),
+  icon: z.string().optional().describe('Icon name for palette display'),
+  category: z.enum(['content', 'interactive', 'data', 'layout'])
+    .describe('Palette category grouping'),
+  defaultWidth: z.number().int().min(1).default(4).describe('Default width in grid columns'),
+  defaultHeight: z.number().int().min(1).default(2).describe('Default height in grid rows'),
+});
+
+/**
+ * Interface Builder Config Schema
+ * Configuration for the Studio Interface Builder.
+ */
+export const InterfaceBuilderConfigSchema = z.object({
+  snap: CanvasSnapSettingsSchema.optional().describe('Canvas snap settings'),
+  zoom: CanvasZoomSettingsSchema.optional().describe('Canvas zoom settings'),
+  palette: z.array(ElementPaletteItemSchema).optional()
+    .describe('Custom element palette (defaults to all registered elements)'),
+  showLayerPanel: z.boolean().default(true).describe('Show layer ordering panel'),
+  showPropertyPanel: z.boolean().default(true).describe('Show property inspector panel'),
+  undoLimit: z.number().int().min(1).default(50).describe('Maximum undo history steps'),
+});
+
+// Type Exports
+export type CanvasSnapSettings = z.infer<typeof CanvasSnapSettingsSchema>;
+export type CanvasZoomSettings = z.infer<typeof CanvasZoomSettingsSchema>;
+export type ElementPaletteItem = z.infer<typeof ElementPaletteItemSchema>;
+export type InterfaceBuilderConfig = z.infer<typeof InterfaceBuilderConfigSchema>;

packages/spec/src/ui/component.zod.ts

@@ -167,6 +167,59 @@ export const ElementImagePropsSchema = z.object({
   aria: AriaPropsSchema.optional().describe('ARIA accessibility attributes'),
 });
 
+/**
+ * ----------------------------------------------------------------------
+ * 4. Interactive Element Components (Phase B — Element Library)
+ * ----------------------------------------------------------------------
+ */
+
+export const ElementButtonPropsSchema = z.object({
+  label: I18nLabelSchema.describe('Button display label'),
+  variant: z.enum(['primary', 'secondary', 'danger', 'ghost', 'link'])
+    .optional().default('primary').describe('Button visual variant'),
+  size: z.enum(['small', 'medium', 'large'])
+    .optional().default('medium').describe('Button size'),
+  icon: z.string().optional().describe('Icon name (Lucide icon)'),
+  iconPosition: z.enum(['left', 'right'])
+    .optional().default('left').describe('Icon position relative to label'),
+  disabled: z.boolean().optional().default(false).describe('Disable the button'),
+  /** ARIA accessibility */
+  aria: AriaPropsSchema.optional().describe('ARIA accessibility attributes'),
+});
+
+export const ElementFilterPropsSchema = z.object({
+  object: z.string().describe('Object to filter'),
+  fields: z.array(z.string()).describe('Filterable field names'),
+  targetVariable: z.string().optional().describe('Page variable to store filter state'),
+  layout: z.enum(['inline', 'dropdown', 'sidebar'])
+    .optional().default('inline').describe('Filter display layout'),
+  showSearch: z.boolean().optional().default(true).describe('Show search input'),
+  /** ARIA accessibility */
+  aria: AriaPropsSchema.optional().describe('ARIA accessibility attributes'),
+});
+
+export const ElementFormPropsSchema = z.object({
+  object: z.string().describe('Object for the form'),
+  fields: z.array(z.string()).optional().describe('Fields to display (defaults to all editable fields)'),
+  mode: z.enum(['create', 'edit']).optional().default('create').describe('Form mode'),
+  submitLabel: I18nLabelSchema.optional().describe('Submit button label'),
+  onSubmit: z.string().optional().describe('Action expression on form submit'),
+  /** ARIA accessibility */
+  aria: AriaPropsSchema.optional().describe('ARIA accessibility attributes'),
+});
+
+export const ElementRecordPickerPropsSchema = z.object({
+  object: z.string().describe('Object to pick records from'),
+  displayField: z.string().describe('Field to display as the record label'),
+  searchFields: z.array(z.string()).optional().describe('Fields to search against'),
+  filter: z.any().optional().describe('Filter criteria for available records'),
+  multiple: z.boolean().optional().default(false).describe('Allow multiple record selection'),
+  targetVariable: z.string().optional().describe('Page variable to bind selected record ID(s)'),
+  placeholder: I18nLabelSchema.optional().describe('Placeholder text'),
+  /** ARIA accessibility */
+  aria: AriaPropsSchema.optional().describe('ARIA accessibility attributes'),
+});
+
 /**
  * ----------------------------------------------------------------------
  * Component Props Map
@@ -210,6 +263,12 @@ export const ComponentPropsMap = {
   'element:number': ElementNumberPropsSchema,
   'element:image': ElementImagePropsSchema,
   'element:divider': EmptyProps,
+
+  // Interactive Elements
+  'element:button': ElementButtonPropsSchema,
+  'element:filter': ElementFilterPropsSchema,
+  'element:form': ElementFormPropsSchema,
+  'element:record_picker': ElementRecordPickerPropsSchema,
 } as const;
 
 /**

packages/spec/src/ui/index.ts

@@ -29,3 +29,4 @@ export * from './animation.zod';
 export * from './notification.zod';
 export * from './dnd.zod';
 export * from './interface.zod';
+export * from './sharing.zod';