From 0890c34de6e89c0d475f735a518e9236a7f3a439 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agust=C3=ADn=20Busso?= <90727999+agustinbusso@users.noreply.github.com> Date: Fri, 13 Nov 2026 17:29:42 -0300 Subject: [PATCH] Add screen preview presets Persist named preview data presets for screens and versions, expose them through the screen API and MCP tools, and add Screen Builder controls to create, edit, reorder, apply, and update presets. --- .../Process/ScreenBuilderController.php | 1 + ProcessMaker/Mcp/Screens/ScreenCatalog.php | 46 ++- ProcessMaker/Mcp/Servers/ScreenServer.php | 3 +- .../Mcp/Tools/Screens/CreateScreenTool.php | 3 +- .../Mcp/Tools/Screens/ScreenFields.php | 9 + .../Mcp/Tools/Screens/UpdateScreenTool.php | 3 +- ProcessMaker/Models/Screen.php | 3 + ProcessMaker/Models/ScreenVersion.php | 1 + ...0_add_preview_presets_to_screens_table.php | 39 ++ .../js/processes/screen-builder/screen.vue | 339 ++++++++++++++++++ tests/Feature/Api/ScreenTest.php | 16 + 11 files changed, 457 insertions(+), 6 deletions(-) create mode 100644 database/migrations/2026_11_13_110400_add_preview_presets_to_screens_table.php diff --git a/ProcessMaker/Http/Controllers/Process/ScreenBuilderController.php b/ProcessMaker/Http/Controllers/Process/ScreenBuilderController.php index 76727289ef..5e9aa2c40f 100644 --- a/ProcessMaker/Http/Controllers/Process/ScreenBuilderController.php +++ b/ProcessMaker/Http/Controllers/Process/ScreenBuilderController.php @@ -36,6 +36,7 @@ public function edit(ScreenBuilderManager $manager, Screen $screen, $processId = 'computed', 'custom_css', 'watchers', + 'preview_presets', ])); } diff --git a/ProcessMaker/Mcp/Screens/ScreenCatalog.php b/ProcessMaker/Mcp/Screens/ScreenCatalog.php index 47b2d78e4f..be1320f912 100644 --- a/ProcessMaker/Mcp/Screens/ScreenCatalog.php +++ b/ProcessMaker/Mcp/Screens/ScreenCatalog.php @@ -45,7 +45,7 @@ public function __construct(private readonly ScreenConfigValidator $validator) /** * @var list */ - private const JSON_FIELDS = ['config', 'computed', 'watchers']; + private const JSON_FIELDS = ['config', 'computed', 'watchers', 'preview_presets']; private const JSON_FIELD_MESSAGE = ' must be a JSON object or array.'; @@ -151,7 +151,7 @@ public function update(User $user, array $input): array $attributes = $this->writable($validated); if ($attributes === []) { throw ValidationException::withMessages([ - 'screen' => 'Provide at least one field to update: title, description, type, screen_category_id, config, computed, watchers, or custom_css.', + 'screen' => 'Provide at least one field to update: title, description, type, screen_category_id, config, computed, watchers, preview_presets, or custom_css.', ]); } @@ -321,9 +321,48 @@ private function normalize(array $input): array $input['config'] = $this->normalizeConfig($input['config']); } + if (isset($input['preview_presets']) && is_array($input['preview_presets'])) { + $input['preview_presets'] = $this->normalizePreviewPresets($input['preview_presets']); + } + return $input; } + /** + * Designer stores each preset.data as a JSON string so empty objects survive PHP json_decode. + * + * @param array $presets + * @return list + */ + private function normalizePreviewPresets(array $presets): array + { + $normalized = []; + foreach ($presets as $preset) { + if (!is_array($preset)) { + continue; + } + $title = isset($preset['title']) && is_string($preset['title']) ? $preset['title'] : ''; + $data = $preset['data'] ?? '{}'; + if (is_array($data)) { + $data = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) ?: '{}'; + } elseif (!is_string($data)) { + $data = '{}'; + } else { + try { + json_decode($data, true, 512, JSON_THROW_ON_ERROR); + } catch (JsonException) { + $data = '{}'; + } + } + $normalized[] = [ + 'title' => $title, + 'data' => $data, + ]; + } + + return $normalized; + } + /** * Ensure pages/items are Screen Builder–safe (missing inspector crashes the designer). * @@ -404,7 +443,7 @@ private function decodeJson(string $field, string $value): array */ private function writable(array $input): array { - $fields = ['title', 'description', 'type', 'screen_category_id', 'config', 'computed', 'custom_css', 'watchers']; + $fields = ['title', 'description', 'type', 'screen_category_id', 'config', 'computed', 'custom_css', 'watchers', 'preview_presets']; return array_intersect_key($input, array_flip($fields)); } @@ -434,6 +473,7 @@ private function detail(Screen $screen): array 'config' => $screen->config, 'computed' => $screen->computed, 'watchers' => $screen->watchers, + 'preview_presets' => $screen->preview_presets, 'custom_css' => $screen->custom_css, 'created_at' => $this->timestamp($screen->created_at), ]; diff --git a/ProcessMaker/Mcp/Servers/ScreenServer.php b/ProcessMaker/Mcp/Servers/ScreenServer.php index f02cc26915..7a561d8bd2 100644 --- a/ProcessMaker/Mcp/Servers/ScreenServer.php +++ b/ProcessMaker/Mcp/Servers/ScreenServer.php @@ -36,7 +36,8 @@ config is the screen builder page array; every control in page.items must include `"inspector": []` (or a real inspector list) or the designer crashes. create/update reject configs with empty FormSelectList options (missing optionsList). New FORM/DISPLAY screens are built as a Vue Component Editor mount (VueComponentRenderTemplate with a thin contentVue); do not add native FileUpload / FormSelectList / SignaturePad siblings. -For the full rules (control shape, component registration, domain fields, refactor parity), follow the `pm4-screen` skill from the ProcessMaker Skills repository (`npx skills add processmaker/skills`). +On every create and every Vue refactor, set `preview_presets`: named Preview payloads covering empty/start, happy path, and each major UI branch. Each item is `{ "title": "...", "data": "" }` — `data` must be a JSON string so `{}` survives PHP decode. +For the full rules (control shape, component registration, domain fields, refactor parity, preview presets), follow the `pm4-screen` skill from the ProcessMaker Skills repository (`npx skills add processmaker/skills`), especially `preview-presets.md`. update-screen changes only the fields you send. delete-screen cannot remove a default screen. MARKDOWN)] diff --git a/ProcessMaker/Mcp/Tools/Screens/CreateScreenTool.php b/ProcessMaker/Mcp/Tools/Screens/CreateScreenTool.php index 55e577d9ec..da670ca41a 100644 --- a/ProcessMaker/Mcp/Tools/Screens/CreateScreenTool.php +++ b/ProcessMaker/Mcp/Tools/Screens/CreateScreenTool.php @@ -15,7 +15,7 @@ #[Name('create-screen')] #[Title('Create Screen')] -#[Description('Creates a ProcessMaker screen. Requires title, description, type, and screen_category_id. Rejects invalid config (e.g. FormSelectList without optionsList). Prefer validate-screen first.')] +#[Description('Creates a ProcessMaker screen. Requires title, description, type, and screen_category_id. Rejects invalid config (e.g. FormSelectList without optionsList). Prefer validate-screen first. Always include preview_presets covering empty/start, happy path, and each major UI branch; each preset.data must be a JSON string.')] class CreateScreenTool extends ScreenTool { public function handle(Request $request, ScreenCatalog $screens): Response|ResponseFactory @@ -39,6 +39,7 @@ public function schema(JsonSchema $schema): array 'config' => ScreenFields::config($schema), 'computed' => $schema->array()->description('Computed properties for the screen.'), 'watchers' => $schema->array()->description('Screen watchers.'), + 'preview_presets' => ScreenFields::previewPresets($schema), 'custom_css' => $schema->string()->description('Custom CSS applied when the screen renders.'), ]; } diff --git a/ProcessMaker/Mcp/Tools/Screens/ScreenFields.php b/ProcessMaker/Mcp/Tools/Screens/ScreenFields.php index de72500524..dc7befde07 100644 --- a/ProcessMaker/Mcp/Tools/Screens/ScreenFields.php +++ b/ProcessMaker/Mcp/Tools/Screens/ScreenFields.php @@ -21,6 +21,8 @@ final class ScreenFields public const CONFIG = 'Screen builder config. An array of page objects. Each control in page.items must include inspector (use [] when unknown); pages should include items ([]) even when empty.'; + public const PREVIEW_PRESETS = 'Named Screen Builder Preview payloads. Array of { title, data }. data MUST be a JSON string (not a nested object) so empty {} survive PHP json_decode. Required on create and Vue refactor: cover empty/start, happy path, and each major UI branch.'; + public static function id(JsonSchema $schema): IntegerType { return $schema->integer() @@ -62,4 +64,11 @@ public static function config(JsonSchema $schema): ArrayType ->items($schema->object()) ->description(self::CONFIG); } + + public static function previewPresets(JsonSchema $schema): ArrayType + { + return $schema->array() + ->items($schema->object()) + ->description(self::PREVIEW_PRESETS); + } } diff --git a/ProcessMaker/Mcp/Tools/Screens/UpdateScreenTool.php b/ProcessMaker/Mcp/Tools/Screens/UpdateScreenTool.php index 42e2bb2c70..e91a926f47 100644 --- a/ProcessMaker/Mcp/Tools/Screens/UpdateScreenTool.php +++ b/ProcessMaker/Mcp/Tools/Screens/UpdateScreenTool.php @@ -16,7 +16,7 @@ #[Name('update-screen')] #[Title('Update Screen')] -#[Description('Updates a ProcessMaker screen. Send only the fields that should change. Rejects invalid config (e.g. FormSelectList without optionsList). Prefer validate-screen first. Does not reset config to the last published version.')] +#[Description('Updates a ProcessMaker screen. Send only the fields that should change. Rejects invalid config (e.g. FormSelectList without optionsList). Prefer validate-screen first. Does not reset config to the last published version. On create/refactor follow-ups, set preview_presets (each data as JSON string) covering all major UI cases.')] #[IsIdempotent] class UpdateScreenTool extends ScreenTool { @@ -42,6 +42,7 @@ public function schema(JsonSchema $schema): array 'config' => ScreenFields::config($schema), 'computed' => $schema->array()->description('Computed properties for the screen.'), 'watchers' => $schema->array()->description('Screen watchers.'), + 'preview_presets' => ScreenFields::previewPresets($schema), 'custom_css' => $schema->string()->description('Custom CSS applied when the screen renders.'), ]; } diff --git a/ProcessMaker/Models/Screen.php b/ProcessMaker/Models/Screen.php index 734af25e52..2740a7cef4 100644 --- a/ProcessMaker/Models/Screen.php +++ b/ProcessMaker/Models/Screen.php @@ -31,6 +31,7 @@ * @property array computed * @property array custom_css * @property array watchers + * @property array preview_presets * @property string label * @property Carbon type * @property Carbon $updated_at @@ -44,6 +45,7 @@ * @OA\Property(property="config", type="array", @OA\Items(type="object")), * @OA\Property(property="computed", type="array", @OA\Items(type="object")), * @OA\Property(property="watchers", type="array", @OA\Items(type="object")), + * @OA\Property(property="preview_presets", type="array", @OA\Items(type="object")), * @OA\Property(property="custom_css", type="string"), * @OA\Property(property="screen_category_id", type="string"), * ), @@ -89,6 +91,7 @@ class Screen extends ProcessMakerModel implements ScreenInterface, PrometheusMet 'config' => 'array', 'computed' => 'array', 'watchers' => 'array', + 'preview_presets' => 'array', 'translations' => 'array', ]; diff --git a/ProcessMaker/Models/ScreenVersion.php b/ProcessMaker/Models/ScreenVersion.php index ead25ce27b..fb4567583e 100644 --- a/ProcessMaker/Models/ScreenVersion.php +++ b/ProcessMaker/Models/ScreenVersion.php @@ -32,6 +32,7 @@ class ScreenVersion extends ProcessMakerModel implements ScreenInterface, Promet 'config' => 'array', 'computed' => 'array', 'watchers' => 'array', + 'preview_presets' => 'array', 'translations' => 'array', ]; diff --git a/database/migrations/2026_11_13_110400_add_preview_presets_to_screens_table.php b/database/migrations/2026_11_13_110400_add_preview_presets_to_screens_table.php new file mode 100644 index 0000000000..d39a69ceb3 --- /dev/null +++ b/database/migrations/2026_11_13_110400_add_preview_presets_to_screens_table.php @@ -0,0 +1,39 @@ +mediumText('preview_presets')->nullable()->after('watchers'); + }); + + Schema::table('screen_versions', function (Blueprint $table) { + $table->mediumText('preview_presets')->nullable()->after('watchers'); + }); + } + + /** + * Reverse the migrations. + * + * @return void + */ + public function down() + { + Schema::table('screen_versions', function (Blueprint $table) { + $table->dropColumn('preview_presets'); + }); + + Schema::table('screens', function (Blueprint $table) { + $table->dropColumn('preview_presets'); + }); + } +}; diff --git a/resources/js/processes/screen-builder/screen.vue b/resources/js/processes/screen-builder/screen.vue index ca28bca394..2d13af2a82 100644 --- a/resources/js/processes/screen-builder/screen.vue +++ b/resources/js/processes/screen-builder/screen.vue @@ -122,6 +122,133 @@ id="showDataInput" v-model="showDataInput" > + + +
+ + +
+
= this.previewPresets.length) { + return null; + } + return index; + }, + previewPresetDirty() { + const index = this.normalizedActivePreviewPresetIndex; + if (index === null || !this.previewInputValid) { + return false; + } + return !_.isEqual( + JSON.parse(this.previewInput), + this.getPresetDataObject(this.previewPresets[index]), + ); + }, + previewPresetsForApi() { + return this.previewPresets.map((preset) => ({ + title: preset.title, + // string: PHP json_decode turns {} into [] if data is an object + data: this.serializePresetData(preset.data), + })); + }, displayBuilder() { return this.mode === "editor"; }, @@ -687,6 +875,7 @@ export default { computed: this.computed, custom_css: this.customCSS, watchers: this.watchers, + preview_presets: this.previewPresetsForApi, }) .then(() => { // Set draft status. @@ -759,6 +948,138 @@ export default { this.updateDataPreview(); } }, 1000), + previewPresetRowCss(index) { + return index % 2 === 0 ? "striped" : "bg-default"; + }, + normalizePreviewPresets(presets) { + if (!Array.isArray(presets)) { + return []; + } + return presets.map((preset) => ({ + title: preset.title || "", + data: this.serializePresetData(preset.data), + })); + }, + serializePresetData(data) { + if (typeof data === "string") { + try { + return JSON.stringify(JSON.parse(data)); + } catch (err) { + return "{}"; + } + } + return JSON.stringify(data ?? {}); + }, + getPresetDataObject(preset) { + if (!preset) { + return {}; + } + if (typeof preset.data === "string") { + try { + return JSON.parse(preset.data); + } catch (err) { + return {}; + } + } + return preset.data ?? {}; + }, + persistPreviewPresets() { + this.screen.preview_presets = this.previewPresetsForApi; + this.handleAutosave(true); + }, + applyPreviewPreset(index) { + const presetIndex = Number(index); + const preset = this.previewPresets[presetIndex]; + if (!preset || typeof preset.data === "undefined") { + return; + } + this.activePreviewPresetIndex = presetIndex; + this.previewInput = JSON.stringify(this.getPresetDataObject(preset), null, 2); + this.previewData = JSON.parse(this.previewInput); + this.previewDataStringify = this.previewInput; + this.rendererKey += 1; + if (this.mode === "preview") { + this.$dataProvider.flushScreenCache(); + } + }, + updateActivePreviewPreset() { + const index = this.normalizedActivePreviewPresetIndex; + if (index === null || !this.previewInputValid) { + return; + } + this.$set( + this.previewPresets[index], + "data", + this.serializePresetData(JSON.parse(this.previewInput)), + ); + this.persistPreviewPresets(); + }, + discardPreviewPresetChanges() { + const index = this.normalizedActivePreviewPresetIndex; + if (index === null) { + return; + } + this.applyPreviewPreset(index); + }, + addPreviewPreset() { + if (!this.previewInputValid) { + ProcessMaker.alert(this.$t("Invalid JSON Data Object"), "danger"); + return; + } + this.previewPresetCardType = "insert"; + this.previewPresetTitle = ""; + this.previewPresetEditIndex = null; + this.showPreviewPresetCard = true; + }, + showEditPreviewPreset(index) { + this.previewPresetCardType = "edit"; + this.previewPresetEditIndex = Number(index); + this.previewPresetTitle = this.previewPresets[this.previewPresetEditIndex].title; + this.showPreviewPresetCard = true; + }, + cancelPreviewPresetCard() { + this.showPreviewPresetCard = false; + this.previewPresetEditIndex = null; + this.previewPresetTitle = ""; + }, + savePreviewPresetCard() { + const title = (this.previewPresetTitle || "").trim(); + if (!title) { + return; + } + if (this.previewPresetCardType === "insert") { + if (!this.previewInputValid) { + return; + } + this.previewPresets.push({ + title, + data: this.serializePresetData(JSON.parse(this.previewInput)), + }); + this.activePreviewPresetIndex = this.previewPresets.length - 1; + } else { + const preset = this.previewPresets[this.previewPresetEditIndex]; + if (!preset) { + return; + } + this.$set(preset, "title", title); + } + this.cancelPreviewPresetCard(); + this.persistPreviewPresets(); + }, + removePreviewPreset(index) { + const removeIndex = Number(index); + const active = this.normalizedActivePreviewPresetIndex; + this.previewPresets.splice(removeIndex, 1); + if (active === removeIndex) { + this.activePreviewPresetIndex = null; + } else if (active !== null && active > removeIndex) { + this.activePreviewPresetIndex = active - 1; + } + this.persistPreviewPresets(); + }, + onPreviewPresetsReorder() { + this.persistPreviewPresets(); + }, // eslint-disable-next-line func-names updateDataPreview: debounce(function () { this.previewDataStringify = JSON.stringify(this.previewData, null, 2); @@ -880,6 +1201,9 @@ export default { that.computed = that.screen.computed ? that.screen.computed : []; that.customCSS = that.screen.custom_css ? that.screen.custom_css : ""; that.watchers = that.screen.watchers ? that.screen.watchers : []; + that.previewPresets = that.normalizePreviewPresets( + that.screen.preview_presets, + ); that.previewInput = "{}"; that.preview.custom_css = that.customCSS; ProcessMaker.EventBus.$emit("screen-builder-start", that); @@ -1167,6 +1491,7 @@ export default { computed: this.computed, custom_css: this.customCSS, watchers: this.watchers, + preview_presets: this.previewPresetsForApi, }) .then((response) => { if (exportScreen) { @@ -1289,6 +1614,20 @@ body { max-width: 265px; } +.preview-presets { + max-height: 220px; + overflow-y: auto; + font-size: 0.875rem; + + .striped { + background-color: rgba(0, 0, 0, 0.05); + } + + .fa-plus-square { + cursor: pointer; + } +} + .data-collapse { height: 225px; } diff --git a/tests/Feature/Api/ScreenTest.php b/tests/Feature/Api/ScreenTest.php index d6b15608b3..c6455de761 100644 --- a/tests/Feature/Api/ScreenTest.php +++ b/tests/Feature/Api/ScreenTest.php @@ -299,6 +299,13 @@ public function testUpdateDraftScreen() 'computed' => [['id' => 2, 'name' => 'test', 'type' => 'expression', 'formula' => 'test', 'property' => 'test']], 'custom_css' => '.class { font-size: large; }', 'watchers' => '[{"input_data":"{}","script_configuration":"{}","synchronous":false,"show_async_loading":false,"run_onload":false,"name":"Watchers","watching":"form_input_1","script":{"id":"script-4","uuid":"98a4376e-efb8-4c10-83fd-01199398eddc","key":null,"title":"Autosave","description":"Autosave","language":"php","code":"","timeout":60,"run_as_user_id":1,"status":"ACTIVE","script_category_id":"1","script_executor_id":3},"script_id":"4","script_key":null,"uid":"16794186944621"}]', + 'preview_presets' => [ + [ + 'title' => 'Empty contact', + // data stored as JSON string so empty objects ({}) survive PHP json_decode + 'data' => '{"email":"jane@example.com","contact":{}}', + ], + ], 'type' => $screen->type, 'screen_category_id' => $screen->screen_category_id, ]); @@ -313,6 +320,15 @@ public function testUpdateDraftScreen() $this->assertEquals($draft->computed, [['id' => 2, 'name' => 'test', 'type' => 'expression', 'formula' => 'test', 'property' => 'test']]); $this->assertEquals($draft->custom_css, '.class { font-size: large; }'); $this->assertEquals($draft->watchers, '[{"input_data":"{}","script_configuration":"{}","synchronous":false,"show_async_loading":false,"run_onload":false,"name":"Watchers","watching":"form_input_1","script":{"id":"script-4","uuid":"98a4376e-efb8-4c10-83fd-01199398eddc","key":null,"title":"Autosave","description":"Autosave","language":"php","code":"","timeout":60,"run_as_user_id":1,"status":"ACTIVE","script_category_id":"1","script_executor_id":3},"script_id":"4","script_key":null,"uid":"16794186944621"}]'); + $this->assertEquals( + [ + [ + 'title' => 'Empty contact', + 'data' => '{"email":"jane@example.com","contact":{}}', + ], + ], + $draft->preview_presets + ); $this->assertLessThan(3, $draft->updated_at->diffInSeconds($screen->updated_at)); }