From 7e05511477e5402d7dedae485fbe849cf6e9fa70 Mon Sep 17 00:00:00 2001 From: Roly Gutierrez Date: Thu, 12 Nov 2026 16:50:04 -0400 Subject: [PATCH] fix(FOUR-34392): align agents, hexagonal base, and create-project wizard docs: decouple from PLG; restore screen/custom-vue patterns with package slug. feat(rename): preserve upsert skills after npx skills install. feat: add Shared domain Model and ValidatesWithJsonSchema with swaggest. https://processmaker.atlassian.net/browse/FOUR-34392 --- AGENTS.md | 129 ++++------ README.md | 8 +- ai-docs/best-code-practices.md | 11 +- ai-docs/credit-deal-coverage.html | 2 +- ai-docs/custom-vue-components.md | 332 +++---------------------- ai-docs/hexagonal.md | 73 +++--- ai-docs/models.md | 21 ++ ai-docs/report.md | 6 +- ai-docs/structure.md | 19 +- composer.json | 3 + projects/AGENTS.md | 14 ++ projects/README.md | 16 +- rename-project.php | 167 +++++++++++++ src/Projects/Shared/Domain/Model.php | 40 +++ src/Traits/ValidatesWithJsonSchema.php | 206 +++++++++++++++ stories/Configure.mdx | 8 +- 16 files changed, 602 insertions(+), 453 deletions(-) create mode 100644 ai-docs/models.md create mode 100644 projects/AGENTS.md create mode 100644 src/Projects/Shared/Domain/Model.php create mode 100644 src/Traits/ValidatesWithJsonSchema.php diff --git a/AGENTS.md b/AGENTS.md index 89cdfc1..947d470 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,11 +12,11 @@ Ask only if missing: 1. **Slug** (kebab-case): e.g. `project-name` 2. **Pascal name**: e.g. `ProjectName` -3. **Table prefix** (short, unique, like Military `amil_`): e.g. `ahs_` +3. **Table prefix** (short, unique): e.g. `ahs_` ## Target tree -Replace `{slug}` / `{Pascal}` / `{prefix}`. Full tree: [structure.md](structure.md). +Replace `{slug}` / `{Pascal}` / `{prefix}`. Full tree: [ai-docs/structure.md](ai-docs/structure.md). ``` ai-docs/{slug}/ @@ -25,11 +25,9 @@ ai-docs/{slug}/ architecture/workflow.md architecture/frontend.md -projects/{slug}/bpmn/{slug}-transcript.xml -projects/{slug}/bpmn/{slug}-applicant.xml +projects/{slug}/bpmn/{slug}-{purpose}.xml projects/{slug}/scripts/{slug}-{action}.php -# ProjectName: projects/{slug}/scripts/{project-name}/{title}.php -projects/{slug}/tce-{slug}/{process-name}/{screen-name}.yaml +projects/{slug}/screens/{slug}-{purpose}.yaml src/Projects/{Pascal}/ Domain/Entities/ @@ -63,33 +61,33 @@ Copy this checklist and complete it in order: ### 1. Folders + ai-docs -Create `ai-docs/{slug}/` the same way as `ai-docs/high-school/` (domain index + architecture docs). +Create `ai-docs/{slug}/` (domain index + architecture docs). See [ai-docs/structure.md](ai-docs/structure.md). `AGENTS.md` must list: - Architecture doc links - BPMN files and `DB_ID` / `process_id` (fill after upsert-process-bpmn) - `pm:screenRef` → YAML + Vue path -- `pm:scriptRef` → `projects/{slug}/scripts/{slug}-*.php` → Application use case (ProjectName: `projects/{slug}/scripts/{slug}-title.php`) +- `pm:scriptRef` → `projects/{slug}/scripts/{slug}-*.php` → Application use case ### 2. Hexagonal PHP -Create `src/Projects/{Pascal}/` per [hexagonal.md](hexagonal.md). Namespace: `ProcessMaker\Package\PackagePlg\Projects\{Pascal}`. Existing PSR-4 (`PackagePlg\` → `src`) covers it; do not add a new autoload root. +Create `src/Projects/{Pascal}/` per [ai-docs/hexagonal.md](ai-docs/hexagonal.md). Namespace: `ProcessMaker\Package\PackageSkeleton\Projects\{Pascal}`. Existing PSR-4 (`PackageSkeleton\` → `src`) covers it; do not add a new autoload root. After `rename-project.php`, `PackageSkeleton` becomes the package Pascal name. -**Skeleton** is empty folders (`Domain/Entities`, `Domain/Schemas`, `Domain/Ports`, `Application/UseCases`, `Infrastructure/Persistence`). Do not invent a dummy `Student` entity. First use case appears when there is a script task: `{Action}` under `Application/UseCases/` with `$data` in / array out. No port until there is DB/HTTP. Shape: [hexagonal.md](hexagonal.md). +**Skeleton** is empty folders (`Domain/Entities`, `Domain/Schemas`, `Domain/Ports`, `Application/UseCases`, `Infrastructure/Persistence`) plus shared base [Model](src/Projects/Shared/Domain/Model.php). Do not invent a dummy entity. First use case appears when there is a script task: `{Action}` under `Application/UseCases/` with `$data` in / array out. No port until there is DB/HTTP. Shape: [ai-docs/hexagonal.md](ai-docs/hexagonal.md). Entities: [ai-docs/models.md](ai-docs/models.md). -- Domain: entities extending shared `Projects\Shared\Domain\Model` **when there is a real entity**. Ports only when there is I/O. Schemas in `Domain/Schemas/`. See [models.md](models.md). -- Application: one use case per script task (replaces Military `*Actions` statics). Constructor-inject ports **if** the use case talks to DB/HTTP. Search Shared/Military before writing a new class; extract duplicated I/O to a Shared port. Verb+object names and purpose docblocks — see [hexagonal.md](hexagonal.md). -- Infrastructure: RedBean adapters implementing ports. Copy `ScriptTaskContainer` + `app()` helper only if this domain already uses that pattern (Military). Prefer wrapper `isset` + `new UseCase($adapter)` or `new UseCase()` with no deps. Never Laravel `app()` from script tasks. +- Domain: entities extending shared `Projects\Shared\Domain\Model` **when there is a real entity**. Ports only when there is I/O. Schemas in `Domain/Schemas/`. +- Application: one use case per script task. Constructor-inject ports **if** the use case talks to DB/HTTP. Search `src/Projects/Shared` before writing a new class; extract duplicated I/O to a Shared port. +- Infrastructure: RedBean (or HTTP) adapters implementing ports. Prefer wrapper `isset` + `new UseCase($adapter)` or `new UseCase()` with no deps. Never Laravel `app()` from script tasks. -HTTP/Eloquent stays in `src/Http` and `src/Models/{Pascal}` only for package APIs. Script tasks must not call those models. Domain entities must extend `ProcessMaker\Package\PackagePlg\Projects\Shared\Domain\Model`, never a new project-local base and never Eloquent. +HTTP/Eloquent stays in `src/Http` and `src/Models/{Pascal}` only for package APIs. Script tasks must not call those models. Domain entities must extend `ProcessMaker\Package\PackageSkeleton\Projects\Shared\Domain\Model`, never a new project-local base and never Eloquent. -Table names: `{prefix}_*` (Military: `amil_*`). Document them in `architecture/database.md`. +Table names: `{prefix}_*`. Document them in `architecture/database.md`. ### 3. Scripts - Filename basename **equals** the ProcessMaker script **title**. -- kebab-case: `{slug}-{action}.php`. Optional `-se` suffix for Smart Extract. Keep legacy titles (`APP - …`) unchanged. +- kebab-case: `{slug}-{action}.php`. Optional `-se` suffix for Smart Extract. - Thin wrapper: global `$data` in, return array. Constructor-inject ports when there is I/O. PHPUnit `include`s the wrapper and may set port fakes (`isset(...)`). ```php @@ -100,40 +98,36 @@ Table names: `{prefix}_*` (Military: `amil_*`). Document them in `architecture/d * * BPMN scriptTask: {human label} ({process}). * Thin wrapper: global $data in, merged process array out. - * Logic: {UseCase}. I/O: none, or port + RedBean/Guzzle adapter (not Laravel Http). + * Logic: {UseCase}. I/O: none, or port + adapter (not Laravel Http). */ -use ProcessMaker\Package\PackagePlg\Projects\{Pascal}\Application\UseCases\{Action}; +use ProcessMaker\Package\PackageSkeleton\Projects\{Pascal}\Application\UseCases\{Action}; return (new {Action}())->handle($data); ``` -When the use case needs a port, construct the adapter in the wrapper (`isset($transcripts) && $transcripts instanceof TranscriptRepository ? $transcripts : new RedBeanTranscriptRepository()`) only if that port **and** adapter exist under `src/Projects/`. Do not import a Shared port class that is not in the tree. Second copy of the same I/O → extract Shared then. +When the use case needs a port, construct the adapter in the wrapper (`isset($port) && $port instanceof PortInterface ? $port : new RedBeanAdapter()`) only if that port **and** adapter exist under `src/Projects/`. Use RedBean or Guzzle adapters from `Infrastructure/` — not Laravel `Http` or Eloquent from script tasks. ### 4. Screens (YAML + Vue) **Version in git as YAML**, not Screen Builder JSON dumps. -- File: `documentation/tce-{slug}/{process-name}/{kebab-screen}.yaml` +- File: `projects/{slug}/screens/{kebab-screen}.yaml` - A domain-specific root Vue component composed from local child components. The root owns domain coordination; child components own distinct controls or sections. - Every screen item must include an item-level `inspector: []` when no inspector fields are defined; Screen Builder validation expects this array. -- Use one `VueComponentRenderTemplate` for a simple screen, or expose multiple direct components/items when Screen Builder must insert or replace controls between sections. +- Use one `VueComponentRenderTemplate` for a simple screen, or multiple direct components/items when Screen Builder must insert or replace controls between sections. - Vue root: `resources/js/projects/{slug}/{camelOrPascalFolder}/{ScreenName}.vue` -- Local children: `components/{Domain}{Section}.vue`; import them locally for internal composition. In `public-screen-components.json`, the parent entry must declare its direct children in nested `components`, and every child must also have an independent top-level `{ name, key }` entry. Repeat recursively for nested child dependencies. Register only the root with `registerPublicScreenComponent` in the applicable FORM/DISPLAY Screen Builder entrypoints and package-wide when the screen is used outside Screen Builder. -- Reuse `resources/js/projects/shared/` first (CAT1 in military frontend.md), but assume each domain has independent business logic. Similar screens are references, not implementations. -- Before coding, document the screen extension points: which sections are code-owned, slot-based, direct `contentVue` components, or separate Screen Builder items. +- Local children: `components/{Domain}{Section}.vue`; import them locally for internal composition. In `resources/js/designer/public-screen-components.json`, the parent entry must declare its direct children in nested `components`, and every child must also have an independent top-level `{ name, key }` entry. Register only the root with `registerPublicScreenComponent` in the applicable FORM/DISPLAY Screen Builder entrypoints (and package-wide when the screen runs outside Screen Builder). +- Reuse `resources/js/projects/shared/` first when a control is used by 2+ screens; each domain still owns its business logic. +- Before coding, document which sections are code-owned, slot-based, `contentVue` components, or separate Screen Builder items (see [custom-vue-components.md](./ai-docs/custom-vue-components.md)). - New UUID per YAML control (`uuidgen`). - `handlerVue` maps process `$data` into the Vue `v-model`; guard `this.data` because Screen Builder may evaluate the handler before transient process data exists. -Do not use legacy `APP - APV3 - ...` screen titles. - ### 5. BPMN -- `{slug}-transcript.xml` — TCO reviews extracted transcript -- `{slug}-applicant.xml` — application / articulation (if in scope) -- **Design for readability:** keep the top-level graph as a short phase story (Capture → Validate → Review → …). Put the tasks, gateways, and flows of each phase inside an embedded `bpmn:subProcess` (same request). Use `bpmn:adHocSubProcess` / `bpmn:transaction` only when those semantics are needed. See [.agents/skills/pm4-sub-process/design.md](.agents/skills/pm4-sub-process/design.md). -- **CallActivity** only when reusing another published process or needing a separate child request (e.g. shared `documentation/bpmn/upload-transcript.xml`). Do not create a child process merely to hide nodes — embed them instead. -- Prefer [pm4-process](.agents/skills/pm4-process/SKILL.md) + [pm4-sub-process](.agents/skills/pm4-sub-process/SKILL.md) when authoring or editing BPMN with the AI. +- Prefer readable top-level phases; put phase detail inside embedded `bpmn:subProcess` when helpful. +- **CallActivity** only when reusing another published process or needing a separate child request. +- Prefer [pm4-process](.agents/skills/pm4-process/SKILL.md) + [pm4-sub-process](.agents/skills/pm4-sub-process/SKILL.md) when those skills are installed (create-project wizard). ### 6. Publish @@ -153,35 +147,33 @@ Before publishing or handing off a new screen: - Run ESLint on modified Vue/JavaScript source. - Run relevant Storybook interaction tests for loading, empty, error, success, and submit/cancel behavior. -- After Storybook verification, list each relevant story as a markdown link `[ExportName](http://127.0.0.1:7007/?path=/story/)`. See root `AGENTS.md` → *After verifying Storybook (frontend handoff)*. +- After Storybook verification, list each relevant story as a markdown link `[ExportName](http://127.0.0.1:7007/?path=/story/)`. - Review SonarQube findings introduced in `resources/js/projects/**`; fix new Blocker, Critical, and Major issues. -- Keep complexity, duplication, unused code, unsafe nested access, and unhandled API failures out of new code. -- Guard `this.data` in `handlerVue` because the Screen Builder editor may evaluate it before transient process data exists. -- Do not use broad SonarQube exclusions or unexplained lint suppressions; document any unavoidable suppression. -- Include validation commands and pre-existing findings in the PR description. +- Guard `this.data` in `handlerVue`. +- Do not use broad SonarQube exclusions or unexplained lint suppressions. ## Naming | Asset | Convention | Example | | --- | --- | --- | -| Domain slug | kebab-case | `high-school` | -| PHP path / namespace | `src/Projects/{Pascal}/` | `ProcessMaker\Package\PackagePlg\Projects\HighSchool` | -| Domain model base | extend shared `Model` | `ProcessMaker\Package\PackagePlg\Projects\Shared\Domain\Model` | -| JSON Schema | `Domain/Schemas/{entity}.schema.json` | `src/Projects/HighSchool/Domain/Schemas/student.schema.json` | -| BPMN file | `{slug}-{purpose}.xml` | `high-school-transcript.xml` | -| Script file/title | `{slug}-{action}.php` | `high-school-execute-transcript-actions.php` | -| Screen YAML | `{slug}-{purpose}.yaml` | `high-school-transcript.yaml` | -| Vue folder | camelCase or Pascal matching peers | `transcriptHighSchool/` | -| Storybook | `Projects/{Pascal}/...` | `Projects/HighSchool/Transcript` | -| DB tables | `{prefix}_*` | `ahs_transcripts` | +| Domain slug | kebab-case | `project-name` | +| PHP path / namespace | `src/Projects/{Pascal}/` | `ProcessMaker\Package\PackageSkeleton\Projects\ProjectName` | +| Domain model base | extend shared `Model` | `ProcessMaker\Package\PackageSkeleton\Projects\Shared\Domain\Model` | +| JSON Schema | `Domain/Schemas/{entity}.schema.json` | `src/Projects/ProjectName/Domain/Schemas/record.schema.json` | +| BPMN file | `{slug}-{purpose}.xml` | `project-name-intake.xml` | +| Script file/title | `{slug}-{action}.php` | `project-name-save-record.php` | +| Screen YAML | `{slug}-{purpose}.yaml` | `project-name-intake.yaml` | +| Vue folder | camelCase or Pascal matching peers | `intakeForm/` | +| Storybook | `Projects/{Pascal}/...` | `Projects/ProjectName/Intake` | +| DB tables | `{prefix}_*` | `ahs_records` | | PHP locals | camelCase words, not loop letters | `$institutionId` not `$instCode` / `$x` | ## Do not -- Put new hexagonal PHP in `src/{Pascal}/` or `src/Military/` (use `src/Projects/{Pascal}/`) +- Put new hexagonal PHP outside `src/Projects/{Pascal}/` - Add a project-local `*Model` base; extend `Projects\Shared\Domain\Model` - Put JSON schemas under `src/Models/{Pascal}/Schemas/` for new domains -- Put domain logic only inside `documentation/scripts/*.php` +- Put domain logic only inside unversioned ProcessMaker UI assets - Call Laravel Eloquent from script tasks - Store screens only in ProcessMaker (YAML is the versioned artifact) - Store processes only in Modeler (BPMN XML is the versioned artifact) @@ -189,7 +181,6 @@ Before publishing or handing off a new screen: - Create ad-hoc Storybook top-level groups - Write skills or docs under `~/.cursor/skills-cursor/` - ## Storybook organization Run Storybook with Node 20+: @@ -198,56 +189,40 @@ Run Storybook with Node 20+: All story entries should be grouped using the `title` field as the canonical structure. -Keep named story exports in each `*.stories.js` file in alphabetical order by -export name. Keep the default metadata export at the top; sort only the named -stories that follow it. +Keep named story exports in each `*.stories.js` file in alphabetical order by export name. Keep the default metadata export at the top; sort only the named stories that follow it. Use these Storybook top-level groups: -- `Components`: shared reusable UI components. - - Keep legacy `UI` stories under `Components/UI/*`. -- `Projects`: domain-specific stories grouped under: - - `Projects/{ProjectName}/*` -Aim to keep stories close to their implementation area, and prefer moving any story into the most specific group above rather than creating ad-hoc top-level groups. +- `Components`: shared reusable UI components. +- `Projects`: domain-specific stories under `Projects/{ProjectName}/*` ### After verifying Storybook (frontend handoff) -When frontend changes are verified with Storybook (interaction tests or manual -checks), list each relevant story as a **markdown link** whose label is the -story export name and whose target opens that story. Do not paste bare URLs -beside the name. +List each relevant story as a markdown link whose label is the story export name: - Dev server: `npm run storybook` → `http://127.0.0.1:7007` - Link form: `[ExportName](http://127.0.0.1:7007/?path=/story/)` -- Resolve `` from the running index when available - (`http://127.0.0.1:7007/index.json` → `entries[].id`), or from the CSF - `title` + export name in Storybook kebab-case - (e.g. title `Projects/CollegeV2/Applicant/CollegeCourseEvaluation` + export - `AutoSelectSentToStudent` → - `projects-collegev2-applicant-collegecourseevaluation--auto-select-sent-to-student`). +- Resolve `` from `http://127.0.0.1:7007/index.json` → `entries[].id`, or from CSF `title` + export name in Storybook kebab-case. -Example handoff: +## PHPUnit development -- [AutoSelectSentToStudent](http://127.0.0.1:7007/?path=/story/projects-collegev2-applicant-collegecourseevaluation--auto-select-sent-to-student) -- [SendCourseToStudent](http://127.0.0.1:7007/?path=/story/projects-collegev2-applicant-collegecourseevaluation--send-course-to-student) +Prefer: -## PHPUnit development -If you need to run a phpunit test prefer to use: ``` -/usr/local/bin/phpunit vendor/processmaker/package-example4/{test_path} +/usr/local/bin/phpunit vendor/processmaker/package-skeleton/{test_path} ``` -Test script tasks could have some special behavior, it usually expect to have a global variable $data and return an array, some tests for script task can be found at `tests/Unit/Documentation` +Script tasks usually expect a global `$data` and return an array. Script wrapper tests live under `tests/Unit/Documentation` when present. ## Cross-domain architecture -- [Best code practices](./ai-docs/best-code-practices.md): **SonarQube must pass** on changed code, cognitive complexity ≤ 15, classes ≤ 20 methods, and related quality expectations. -- [Custom Vue Components](./ai-docs/custom-vue-components.md): administration, Screen Builder runtime resolution, browser caching, security, and Screen Import/Export dependencies. +- [Best code practices](./ai-docs/best-code-practices.md): **SonarQube must pass** on changed code, cognitive complexity ≤ 15, classes ≤ 20 methods. - [Projects hexagonal organization](./ai-docs/hexagonal.md) +- [Domain models](./ai-docs/models.md) - [Projects assets organization](./projects/AGENTS.md) ## Projects Domain-Specific Instructions -Each project have its particular structure, refer to: +Each project has its own structure under: - [project-name](./ai-docs/{project-name}/AGENTS.md) diff --git a/README.md b/README.md index 078cb02..93e6e60 100644 --- a/README.md +++ b/README.md @@ -25,12 +25,12 @@ PM_SKILLS_PROFILE=migration NAYRA_SERVER=https://pm.example.com PM_SYNC_TOKEN= ``` ## Development -If you need to create a new ProcessMaker package run the following commands: +Prefer `composer create-project` above. To rename a local clone: ``` -git clone https://github.com/ProcessMaker/package-skeleton.git -cd package-skeleton -php rename-project.php package-skeleton +git clone https://github.com/ProcessMaker/package-skeleton.git my-package +cd my-package +php rename-project.php my-package composer install npm install npm run dev diff --git a/ai-docs/best-code-practices.md b/ai-docs/best-code-practices.md index 9510c0a..4586c93 100644 --- a/ai-docs/best-code-practices.md +++ b/ai-docs/best-code-practices.md @@ -1,8 +1,8 @@ # Best code practices -Cross-project coding standards for package-plg. Prefer these when writing or refactoring code so SonarQube and review stay green. +Cross-project coding standards for Package Skeleton (and packages created from it). Prefer these when writing or refactoring code so SonarQube and review stay green. -**SOLID:** On every frontend and backend implementation, apply SOLID. Agent skill: [`.cursor/skills/apply-solid/SKILL.md`](../.cursor/skills/apply-solid/SKILL.md). +**SOLID:** On every frontend and backend implementation, apply SOLID (single responsibility, open/closed, Liskov, interface segregation, dependency inversion). ## Sonar review (required) @@ -21,7 +21,7 @@ Keep each function/method at cognitive complexity ≤ 15. When a method approach ## Use at most 3 returns in a function -Functions should not contain too many return statements +Functions should not contain too many return statements. ## Class size @@ -38,9 +38,10 @@ Prefer optional chain expressions (`?.`) over nested null/undefined checks. They ## Related to code -- Do not use unnecessary use of boolean literals in conditional expression. e.g. `condition ? true : false` when `condition` is already a boolean. -- [S7744] Do not use unnecessary fallback objects should not be used when spreading in object literals. +- Do not use unnecessary boolean literals in conditional expressions, e.g. `condition ? true : false` when `condition` is already a boolean. +- [S7744] Do not use unnecessary fallback objects when spreading in object literals. ## Related to Vue components + - Declare emits array for all emitted events. - Declare the props as object that include type of the properties. diff --git a/ai-docs/credit-deal-coverage.html b/ai-docs/credit-deal-coverage.html index 62e2d1c..ca58e15 100644 --- a/ai-docs/credit-deal-coverage.html +++ b/ai-docs/credit-deal-coverage.html @@ -155,7 +155,7 @@

Implemented, and still needs a manual check

Publication

-

On 10 November 2026 the versioned assets were created on https://tce-eng.dev.cloud.processmaker.net: scripts 227–242, screens 433–489, process credit-deal-notification (83), and process credit-deal-process (84). Publication does not change the percentages above. The package classes, the Vue bundle, the acd_* migration, and the seed data were not installed with those assets, so a case still cannot run end to end. The Send Email task’s pm:config screenRef was stored as the named reference ${screen:credit-deal-notification-email}; the connector reads that JSON, so screen 464 still has to be selected on the task.

+

On 10 November 2026 the versioned assets were published to the PM4 instance set in package .env as PM_BASE_URL (configured at composer create-project): scripts 227–242, screens 433–489, process credit-deal-notification (83), and process credit-deal-process (84). Publication does not change the percentages above. The package classes, the Vue bundle, the acd_* migration, and the seed data were not installed with those assets, so a case still cannot run end to end. The Send Email task’s pm:config screenRef was stored as the named reference ${screen:credit-deal-notification-email}; the connector reads that JSON, so screen 464 still has to be selected on the task.

Credit Deal coverage report. Inventory of 358 PM3 assets. 317 resolved (88%), 41 open. Functionality 83% on the closing path and 66% including generated documents and the dashboard.
diff --git a/ai-docs/custom-vue-components.md b/ai-docs/custom-vue-components.md index 0130dc2..9b4f621 100644 --- a/ai-docs/custom-vue-components.md +++ b/ai-docs/custom-vue-components.md @@ -1,22 +1,12 @@ -# Custom Vue Components +# Custom Vue components -## Purpose - -Package PLG allows administrators to replace selected Vue components used directly by a ProcessMaker Screen without modifying or rebuilding the official component. It also allows administrators to create DB-only Vue components for use in `contentVue`. +Optional capability for packages created from Package Skeleton. Implement routes and controllers in **your** package slug (`{package-slug}`); this skeleton documents the pattern only — it does not ship the full administration stack by default. -The customization boundary is `VueComponentRenderTemplate`. Normal Vue development continues to use static imports. Internal components imported locally by an official component are not replaced. - -Example: +## Purpose -```html - -``` +Allow administrators to replace selected Vue components used directly by a Screen (`contentVue`) without rebuilding the official Screen Builder bundle. The customization boundary is `VueComponentRenderTemplate`. Static imports inside an official SFC are not replaced. -The Screen declares the component identity: +Screen configuration example: ```json { @@ -29,24 +19,17 @@ The Screen declares the component identity: } ``` -If an enabled customization exists for the key, that component is registered locally in the dynamic template. Otherwise Vue resolves the official global component. +If an enabled customization exists for the key, it is registered locally in the dynamic template; otherwise Vue resolves the official global component. ## Core invariants -- `key` is the stable, unique identity of a component. -- A key has at most one current customization in `custom_vue_components`. -- Screens store `name` and `key`; they never store a custom component ID, UUID, hash, or revision. -- An official component uses an `@/…vue` key and has a code-based fallback. -- A DB-only component uses a `custom://slug` key and has no official fallback. -- `content_hash` is only a cache identifier. It is not a functional revision selected by a Screen. -- If revision history is added later, the component owns the single active revision. Screens must continue referencing only the key. -- Customization is local to a `VueComponentRenderTemplate` instance. Never overwrite a component globally at runtime. - -## Official and DB-only components +- `key` is the stable identity of a component (`@/…vue` or `custom://slug`). +- Screens store `name` and `key` only — never a custom component ID, UUID, or content hash. +- Customization is local to each `VueComponentRenderTemplate` instance. -### Official component +## Catalog (code-owned components) -Official components are listed in the catalog and registered by `registerPublicScreenCatalog`. Each entry is `{ name, key }` plus an optional `components` array of direct `{ name, key }` children. The loader bundles only those catalog files and `registerPublicScreenComponent` wraps an entry that declares children so those tags resolve when the SFC renders. A customization registered for a child key replaces the official child at render time. +Register the catalog once per Screen Builder entrypoint (FORM, DISPLAY, and any designer admin bundle you add): ```js import registerPublicScreenCatalog from './registerPublicScreenCatalog'; @@ -54,298 +37,43 @@ import registerPublicScreenCatalog from './registerPublicScreenCatalog'; registerPublicScreenCatalog(); ``` -FORM, DISPLAY, and the administration page call that helper. Do not enumerate `registerPublicScreenComponent` in those entrypoints. - -The canonical catalog is stored in: +Canonical catalog path in git: ```text resources/js/designer/public-screen-components.json ``` -Both the FORM/DISPLAY entrypoints and the backend administration page consume this catalog. Only components intentionally designed for the no-build runtime belong in it. `CustomizableSummaryCard` is the reference implementation: it has no imports, uses globally available BootstrapVue components, plain Vue 2 JavaScript, Bootstrap classes, and plain CSS. - -### DB-only component - -A component authored entirely in the administration UI uses a key such as: - -```text -custom://student-summary -``` - -It must be declared with both name and key in the Screen configuration. If it is missing, disabled, or invalid, rendering fails because no official implementation exists. - -## Data model - -Migration: - -```text -database/migrations/2026_09_15_000000_create_custom_vue_components_table.php -``` - -Model: - -```text -src/Models/CustomVueComponent.php -``` - -Important fields: - -| Field | Meaning | -|---|---| -| `uuid` | Import/Export asset identity; unrelated to a Screen UUID | -| `key` | Unique runtime identity (`@/...vue` or `custom://slug`) | -| `name` | Vue tag/component name used in `contentVue` | -| `template` | Vue 2 runtime template | -| `script` | Trusted function body inlined into the public asset `factory`, e.g. `return { props: {} }` | -| `style` | Optional CSS injected once per key | -| `preview_template` | Optional example markup rendered only in the administration preview | -| `preview_script` | Optional Vue options function body for the example wrapper | -| `content_hash` | SHA-256 over executable component content | -| `enabled` | Whether runtime manifests may expose the customization | - -The model recomputes `content_hash` on every save. Preview fields are intentionally excluded because they are documentation for the administration UI and are not included in the public runtime asset. The database enforces unique `uuid` and unique `key`. - -## Administration - -Web page: - -```text -GET /designer/custom-components -resources/views/custom-components/index.blade.php -``` - -It is linked from the Designer sidebar and protected by `view-settings`. Mutations require `edit-settings`. - -Authenticated API under the package API prefix (`/api/1.0`): - -```text -GET /package-plg/custom-vue-components -GET /package-plg/custom-vue-components/catalog -GET /package-plg/custom-vue-components/catalog/{name}/source -GET /package-plg/custom-vue-components/{component} -POST /package-plg/custom-vue-components -PUT /package-plg/custom-vue-components/{component} -DELETE /package-plg/custom-vue-components/{component} -``` - -Controller: - -```text -src/Http/Controllers/Api/CustomVueComponentController.php -``` - -The source endpoint reads only allowlisted catalog entries, extracts Vue SFC blocks, and converts `export default` to the runtime `return` format. It reports imports and module loading as blocking diagnostics. It rejects `