feat(harmonia): Attachments / Snapshot files panel (function:Attachment UI) (#6373)

* feat(intent): function: Attachment — file-attachment composition child (end-to-end)

A `function: Attachment` entity is a first-class composition child of its master (native
1:n, master-detail wiring unchanged), turning file attachments into a modeled, type-safe
detail rather than a bespoke subsystem. Builds on the merged CMS Attachments SDK (#6370).

Intent/EDM (engine-intent):
- `attachment` added to IntentParser ENTITY_FUNCTIONS; EntityIntent.isAttachment().
- EdmIntentGenerator injects the standard file-metadata columns (FileName [major],
  ContentType, FileSize [BIGINT], StoragePath, Uuid — all read-only, upload-set) + implicit
  audit, and marks the entity attachmentEntity="true". The author declares no primary key on
  an attachment child, so a generated integer Id is synthesized (otherwise the entity/
  controller would have no PK).

Controller (template-application-rest-java):
- Gated on attachmentEntity, the generated controller gains POST /upload (multipart →
  stores each file in the tenant CMS at /Attachments/<Master>/<yyyy>/<MM>/<uuid>/<file>,
  persists one row per file with the reference + metadata), GET /{id}/download (permission-
  scoped stream, never a raw documents?path=), and deleteById also removes the CMS file.

SDK (api-modules-java):
- Attachments.storeUploads(master) reads the servlet parts Spring's multipart resolver has
  already parsed (the controller is served by a Spring @PostMapping, which consumes the body
  before commons-fileupload could), so the generated controller only ever sees Attachment.

Test: EdmIntentGeneratorTest asserts the injected metadata + Id PK; RecordAttachmentIT drives
the full HTTP round-trip (multipart upload → verbatim download → delete → gone) through the
real multipart servlet path and tenant CMS.

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

* feat(harmonia): Attachments / Snapshot files panel for function:Attachment children

Renders a composition child declared `function: Attachment` (or, forthcoming, `function:
Snapshot`) as a purpose-built Files panel instead of a generic row table — the UI half of
the record-attachments feature (backend in #6371, storage SDK in #6370).

Shared runtime (application-core):
- detailPanel gains a `files` mode (parallel to the existing `calendar` mode): lists the
  master-filtered files with per-file Download (a plain browser GET to the controller's
  `/{id}/download`), and — unless read-only — an Upload control (multipart POST to `/upload`)
  and per-file Remove (reuses the detail delete, which also drops the CMS file). Like a
  calendar, a files panel always renders (its empty state is meaningful).
- api client: request() now sends a FormData body as-is (browser sets the multipart boundary)
  instead of JSON-encoding it, so the upload goes through the same client + auth/error path.

Harmonia templates:
- detail-register emits `files: { readOnly: <attachmentReadOnly> }` for an `attachmentEntity`
  child (read-only flips it to download-only — the generated Snapshot case).
- form-view (editable), document-view (editable), master-view (read-only browse) each render
  the files branch: an x-h-info-page empty state + file cards (name/size/Download[/Remove]),
  gated on `def.files`; the row table + Add button are suppressed for a files detail. $refs is
  ${dollar}-escaped so Velocity leaves the Alpine ref alone.

Editable path verified end-to-end on a generated CompanyAttachment (upload → master-filtered
list → verbatim download → remove). Read-only (Snapshot) branch is in place, activated once the
`attachmentReadOnly` marker lands with `function: Snapshot`.

Depends on #6371 (function: Attachment backend + controller verbs).

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

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: delchev

components/resources/application-core/src/main/resources/META-INF/dirigible/application-core/shell/js/components/detailPanel.js

@@ -27,6 +27,14 @@
  * table: the same master-filtered rows become events; event-click edits the child, date-click
  * creates one with the master FK AND the clicked date preset. An empty month is meaningful, so a
  * calendar panel shows the calendar even with zero rows.
+ *
+ * A def carrying `files: { readOnly }` (a composition child declared `function: Attachment` or
+ * `function: Snapshot`) renders as a Files panel instead of the table: the master-filtered rows are
+ * uploaded files, each downloadable via the controller's `/{id}/download` route. Editable (Attachment):
+ * an Upload control adds files (multipart POST to `/upload`) and each row can be removed. Read-only
+ * (Snapshot): download only — no upload, no delete (copies are generated server-side, e.g. on issue).
+ * Like a calendar, a files panel always renders (its empty state is meaningful), never the shared
+ * "no records" line.
  */
 function detailPanel(def, masterId) {
   return {
@@ -39,6 +47,8 @@ function detailPanel(def, masterId) {
     deleteOpen: false,
     deleteTarget: null,
     deleteBusy: false,
+    uploading: false,     // files defs only
+    fileError: null,
     // Reactive config for the embedded x-h-calendar (calendar defs only); rebuilt on every load.
     calCfg: { view: (def.calendar && def.calendar.view) || 'month', events: [] },
 
@@ -112,6 +122,10 @@ function detailPanel(def, masterId) {
         if (this.def.calendar) {
           this.calCfg = { view: this.def.calendar.view || 'month', events: this.buildEvents() };
           this.state = 'default';
+        } else if (this.def.files) {
+          // A files panel always renders (its empty state carries the upload prompt / "generated on
+          // issue" note), so it never falls back to the shared "no records" line.
+          this.state = 'default';
         } else {
           this.state = this.rows.length === 0 ? 'empty' : 'default';
         }
@@ -225,6 +239,51 @@ function detailPanel(def, masterId) {
       window.PineconeRouter.navigate('/' + this.def.entity + '/create' + q);
     },
 
+    // --- files panel (files defs only) ----------------------------------------------------------
+    // Read-only (Snapshot): download only. Editable (Attachment): upload + remove.
+    get filesReadOnly() { return !!(this.def.files && this.def.files.readOnly); },
+
+    // Absolute URL of the controller's download route (a plain browser GET, not the fetch client):
+    // apiPath is relative to restBase, so prepend it once. The row's own id keys the file.
+    downloadHref(row) {
+      const base = (App.config && App.config.restBase) || '';
+      return base + this.def.apiPath + '/' + encodeURIComponent(row[this.def.primaryKey]) + '/download';
+    },
+
+    // Human-readable size from the injected FileSize column (bytes).
+    fileSizeText(row) {
+      const n = Number(row.FileSize);
+      if (!isFinite(n) || n <= 0) return '';
+      const units = ['B', 'KB', 'MB', 'GB'];
+      let v = n, i = 0;
+      while (v >= 1024 && i < units.length - 1) { v /= 1024; i++; }
+      return (i === 0 ? v : v.toFixed(1)) + ' ' + units[i];
+    },
+
+    // Multipart upload of the picked files to the controller's /upload route (master FK query),
+    // then reload. FormData bodies are sent as-is by the api client (browser sets the boundary).
+    async uploadFiles(fileList) {
+      const files = Array.from(fileList || []);
+      if (!files.length || this.masterId == null) return;
+      this.uploading = true;
+      this.fileError = null;
+      try {
+        const fd = new FormData();
+        files.forEach(f => fd.append('file', f, f.name));
+        const q = '?' + encodeURIComponent(this.def.masterEntityId) + '=' + encodeURIComponent(this.masterId);
+        await App.services.api.post(this.def.apiPath + '/upload' + q, fd);
+        await this.load();
+      } catch (e) {
+        this.fileError = App.services.apiErrors.messageFor(e, 'Upload failed.');
+      } finally {
+        this.uploading = false;
+      }
+    },
+    onFilePick(e) {
+      this.uploadFiles(e.target.files);
+      e.target.value = ''; // allow re-picking the same file
+    },
+
     askDelete(row) { this.deleteTarget = row; this.deleteOpen = true; },
     async confirmDelete() {
       if (!this.deleteTarget) return;

components/resources/application-core/src/main/resources/META-INF/dirigible/application-core/shell/js/services/api.js

@@ -89,10 +89,15 @@ App.services.api = {
   async request(method, url, body, opts = {}) {
     const baseUrl = this.resolveBaseUrl(opts);
 
+    // A FormData body is a multipart upload: send it as-is and let the browser set the
+    // Content-Type (with its boundary) — never JSON-encode it or override the header.
+    const isForm = (typeof FormData !== 'undefined') && (body instanceof FormData);
+
     // X-Requested-With marks the call as programmatic for browsers without Sec-Fetch-Mode: the
     // server then answers an expired session with a PLAIN 401 (no Basic challenge), so the
     // browser's native login dialog never pops over a background poll.
-    const headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'X-Requested-With': 'XMLHttpRequest' };
+    const headers = { 'Accept': 'application/json', 'X-Requested-With': 'XMLHttpRequest' };
+    if (!isForm) headers['Content-Type'] = 'application/json';
     const language = this.language();
     if (language) headers['Accept-Language'] = language;
 
@@ -101,7 +106,7 @@ App.services.api = {
       r = await fetch(`${baseUrl}${url}`, {
         method,
         headers,
-        body: body ? JSON.stringify(body) : undefined,
+        body: body ? (isForm ? body : JSON.stringify(body)) : undefined,
         credentials: 'same-origin'
       });
     } catch (e) {

components/template/template-application-ui-harmonia-java/src/main/resources/META-INF/dirigible/template-application-ui-harmonia-java/ui/perspective/document/document-view.html.template

@@ -290,7 +290,7 @@
       <div x-data="detailPanel({...d, returnTo: '/${name}/' + id + (isPreview ? '/preview' : '/edit')}, id)" x-h-card class="w-full">
         <div x-h-card-header>
           <h3 x-h-card-title x-text="T(d.tkey, d.label)"></h3>
-          <div x-h-card-action x-show="masterId && !isPreview">
+          <div x-h-card-action x-show="masterId && !isPreview && !def.files">
             <button x-h-button data-variant="primary" data-size="sm" @click="addRow()"><i role="img" x-h-lucide data-lucide="plus"></i><span x-text="T('$projectName:${tprefix}.defaults.add', 'Add')"></span></button>
           </div>
         </div>
@@ -306,7 +306,52 @@
               <div x-h-calendar="calCfg" style="height: 420px" @event-click="onEventClick" @date-click="onDateClick"></div>
             </div>
           </template>
-          <template x-if="!def.calendar">
+#set($dollar = '$')
+          <!-- A files detail (function: Attachment / Snapshot): download always; upload + remove only
+               when editable (not preview) and not a read-only Snapshot. ${dollar}refs is escaped so
+               Velocity leaves the Alpine ref alone. -->
+          <template x-if="def.files">
+            <div x-show="state === 'default'" class="vbox gap-3">
+              <div x-show="fileError" x-h-alert data-variant="negative" role="alert"><div x-h-alert-description x-text="fileError"></div></div>
+              <template x-if="masterId &amp;&amp; !isPreview &amp;&amp; !filesReadOnly">
+                <div class="hbox items-center gap-2">
+                  <input type="file" multiple class="hidden" x-ref="fileInput" @change="onFilePick(${dollar}event)" :disabled="uploading" />
+                  <button type="button" x-h-button data-variant="outline" data-size="sm" :disabled="uploading" @click="${dollar}refs.fileInput.click()">
+                    <span x-show="uploading" x-h-spinner></span>
+                    <i x-show="!uploading" role="img" x-h-lucide data-lucide="upload"></i>
+                    <span x-text="uploading ? T('$projectName:${tprefix}.defaults.uploading', 'Uploading…') : T('$projectName:${tprefix}.defaults.upload', 'Upload')"></span>
+                  </button>
+                </div>
+              </template>
+              <template x-if="rows.length === 0">
+                <div x-h-info-page>
+                  <div x-h-info-page-header>
+                    <div x-h-info-page-media.icon><i role="img" x-h-lucide data-lucide="paperclip"></i></div>
+                    <div x-h-info-page-title x-text="filesReadOnly ? T('$projectName:${tprefix}.messages.noCopies', 'No copies yet') : T('$projectName:${tprefix}.messages.noFiles', 'No attachments')"></div>
+                    <div x-h-info-page-description x-text="filesReadOnly ? T('$projectName:${tprefix}.messages.noCopiesHint', 'A copy is stored automatically when the document is issued.') : T('$projectName:${tprefix}.messages.noFilesHint', 'Upload files to attach them to this document.')"></div>
+                  </div>
+                </div>
+              </template>
+              <template x-if="rows.length > 0">
+                <div class="vbox gap-2">
+                  <template x-for="row in rows" :key="row[def.primaryKey]">
+                    <div x-h-card class="hbox items-center gap-3 p-3">
+                      <i role="img" x-h-lucide data-lucide="file-text" class="shrink-0"></i>
+                      <div class="vbox gap-0 grow min-w-0">
+                        <span class="text-sm truncate" x-text="row.FileName"></span>
+                        <span class="text-xs text-muted-foreground" x-text="fileSizeText(row)"></span>
+                      </div>
+                      <a x-h-button data-variant="transparent" data-size="sm" :href="downloadHref(row)" target="_blank" rel="noopener" aria-label="Download"><i role="img" x-h-lucide data-lucide="download"></i></a>
+                      <template x-if="!isPreview &amp;&amp; !filesReadOnly">
+                        <button type="button" x-h-button data-variant="transparent" data-size="sm" @click="askDelete(row)" aria-label="Remove"><i role="img" x-h-lucide data-lucide="trash-2"></i></button>
+                      </template>
+                    </div>
+                  </template>
+                </div>
+              </template>
+            </div>
+          </template>
+          <template x-if="!def.calendar &amp;&amp; !def.files">
           <div x-show="state === 'default'" x-h-table-container.scroll style="max-height: 320px">
             <table x-h-table data-borders="rows">
               <thead x-h-table-header>

components/template/template-application-ui-harmonia-java/src/main/resources/META-INF/dirigible/template-application-ui-harmonia-java/ui/perspective/manage/form-view.html.template

@@ -218,7 +218,7 @@
         <div x-data="detailPanel({...d, returnTo: '/${name}/' + id + (isPreview ? '/preview' : '/edit')}, id)" x-h-card>
           <div x-h-card-header>
             <h3 x-h-card-title x-text="d.label"></h3>
-            <div x-h-card-action x-show="!isPreview">
+            <div x-h-card-action x-show="!isPreview && !def.files">
               <button type="button" x-h-button data-variant="primary" data-size="sm" @click="addRow()"><i role="img" x-h-lucide data-lucide="plus"></i><span x-text="T('$projectName:${tprefix}.defaults.add', 'Add')"></span></button>
             </div>
           </div>
@@ -234,7 +234,52 @@
                 <div x-h-calendar="calCfg" style="height: 420px" @event-click="onEventClick" @date-click="onDateClick"></div>
               </div>
             </template>
-            <template x-if="!def.calendar">
+#set($dollar = '$')
+            <!-- A files detail (function: Attachment / Snapshot): download always; upload + remove
+                 only when editable (not preview) and not a read-only Snapshot (copies are generated
+                 server-side). $refs is escaped (${dollar}refs) so Velocity leaves the Alpine ref alone. -->
+            <template x-if="def.files">
+              <div x-show="state === 'default'" class="vbox gap-3">
+                <div x-show="fileError" x-h-alert data-variant="negative" role="alert"><div x-h-alert-description x-text="fileError"></div></div>
+                <template x-if="!isPreview &amp;&amp; !filesReadOnly">
+                  <div class="hbox items-center gap-2">
+                    <input type="file" multiple class="hidden" x-ref="fileInput" @change="onFilePick(${dollar}event)" :disabled="uploading" />
+                    <button type="button" x-h-button data-variant="outline" data-size="sm" :disabled="uploading" @click="${dollar}refs.fileInput.click()">
+                      <span x-show="uploading" x-h-spinner></span>
+                      <i x-show="!uploading" role="img" x-h-lucide data-lucide="upload"></i>
+                      <span x-text="uploading ? T('$projectName:${tprefix}.defaults.uploading', 'Uploading…') : T('$projectName:${tprefix}.defaults.upload', 'Upload')"></span>
+                    </button>
+                  </div>
+                </template>
+                <template x-if="rows.length === 0">
+                  <div x-h-info-page>
+                    <div x-h-info-page-header>
+                      <div x-h-info-page-media.icon><i role="img" x-h-lucide data-lucide="paperclip"></i></div>
+                      <div x-h-info-page-title x-text="filesReadOnly ? T('$projectName:${tprefix}.messages.noCopies', 'No copies yet') : T('$projectName:${tprefix}.messages.noFiles', 'No attachments')"></div>
+                      <div x-h-info-page-description x-text="filesReadOnly ? T('$projectName:${tprefix}.messages.noCopiesHint', 'A copy is stored automatically when the document is issued.') : T('$projectName:${tprefix}.messages.noFilesHint', 'Upload files to attach them to this record.')"></div>
+                    </div>
+                  </div>
+                </template>
+                <template x-if="rows.length > 0">
+                  <div class="vbox gap-2">
+                    <template x-for="row in rows" :key="row[def.primaryKey]">
+                      <div x-h-card class="hbox items-center gap-3 p-3">
+                        <i role="img" x-h-lucide data-lucide="file-text" class="shrink-0"></i>
+                        <div class="vbox gap-0 grow min-w-0">
+                          <span class="text-sm truncate" x-text="row.FileName"></span>
+                          <span class="text-xs text-muted-foreground" x-text="fileSizeText(row)"></span>
+                        </div>
+                        <a x-h-button data-variant="transparent" data-size="sm" :href="downloadHref(row)" target="_blank" rel="noopener" aria-label="Download"><i role="img" x-h-lucide data-lucide="download"></i></a>
+                        <template x-if="!isPreview &amp;&amp; !filesReadOnly">
+                          <button type="button" x-h-button data-variant="transparent" data-size="sm" @click="askDelete(row)" aria-label="Remove"><i role="img" x-h-lucide data-lucide="trash-2"></i></button>
+                        </template>
+                      </div>
+                    </template>
+                  </div>
+                </template>
+              </div>
+            </template>
+            <template x-if="!def.calendar &amp;&amp; !def.files">
             <div x-show="state === 'default'" x-h-table-container.scroll style="max-height: 320px">
               <table x-h-table data-borders="rows">
                 <thead x-h-table-header>

components/template/template-application-ui-harmonia-java/src/main/resources/META-INF/dirigible/template-application-ui-harmonia-java/ui/perspective/master/detail-register.js.template

@@ -35,6 +35,12 @@ App.registerDetail('${masterEntity}', {
   // Rendered as an embedded x-h-calendar panel on the master page (intent view: calendar on a
   // composition child); the shared detailPanel maps the rows to events by these properties.
   calendar: { start: '${calendarStartProperty}'#if($calendarEndProperty), end: '${calendarEndProperty}'#end#if($calendarTitleProperty), title: '${calendarTitleProperty}'#end#if($calendarColorProperty), color: '${calendarColorProperty}'#end, view: '${calendarInitialView}', range: #if($calendarRange)true#{else}false#end },
+#end
+#if($attachmentEntity)
+  // Rendered as a Files panel (function: Attachment / Snapshot): the shared detailPanel lists the
+  // uploaded files with download, and — unless read-only — an upload control + per-file remove.
+  // Read-only (a generated Snapshot child) shows download only. See detailPanel `files`.
+  files: { readOnly: #if($attachmentReadOnly)true#{else}false#end },
 #end
   columns: [
 #foreach($property in $properties)

components/template/template-application-ui-harmonia-java/src/main/resources/META-INF/dirigible/template-application-ui-harmonia-java/ui/perspective/master/master-view.html.template

@@ -186,7 +186,36 @@
                   <div x-h-calendar="calCfg" style="height: 420px" @event-click="onEventClick" @date-click="onDateClick"></div>
                 </div>
               </template>
-              <template x-if="!def.calendar">
+              <!-- A files detail (function: Attachment / Snapshot) on the read-only browse pane: the
+                   files are downloadable here; upload/remove happen on the record's Edit form. -->
+              <template x-if="def.files">
+                <div x-show="state === 'default'" class="vbox gap-3">
+                  <template x-if="rows.length === 0">
+                    <div x-h-info-page>
+                      <div x-h-info-page-header>
+                        <div x-h-info-page-media.icon><i role="img" x-h-lucide data-lucide="paperclip"></i></div>
+                        <div x-h-info-page-title x-text="filesReadOnly ? T('$projectName:${tprefix}.messages.noCopies', 'No copies yet') : T('$projectName:${tprefix}.messages.noFiles', 'No attachments')"></div>
+                        <div x-h-info-page-description x-text="filesReadOnly ? T('$projectName:${tprefix}.messages.noCopiesHint', 'A copy is stored automatically when the document is issued.') : T('$projectName:${tprefix}.messages.noFilesHint', 'Files are managed from the record’s Edit form.')"></div>
+                      </div>
+                    </div>
+                  </template>
+                  <template x-if="rows.length > 0">
+                    <div class="vbox gap-2">
+                      <template x-for="row in rows" :key="row[def.primaryKey]">
+                        <div x-h-card class="hbox items-center gap-3 p-3">
+                          <i role="img" x-h-lucide data-lucide="file-text" class="shrink-0"></i>
+                          <div class="vbox gap-0 grow min-w-0">
+                            <span class="text-sm truncate" x-text="row.FileName"></span>
+                            <span class="text-xs text-muted-foreground" x-text="fileSizeText(row)"></span>
+                          </div>
+                          <a x-h-button data-variant="transparent" data-size="sm" :href="downloadHref(row)" target="_blank" rel="noopener" aria-label="Download"><i role="img" x-h-lucide data-lucide="download"></i></a>
+                        </div>
+                      </template>
+                    </div>
+                  </template>
+                </div>
+              </template>
+              <template x-if="!def.calendar &amp;&amp; !def.files">
               <div x-show="state === 'default'" x-h-table-container.scroll style="max-height: 320px">
                 <table x-h-table data-borders="rows">
                   <thead x-h-table-header>