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)); }