@bigbinary/neeto-pdf-frontend 1.0.1

package/README.md

@@ -0,0 +1,413 @@
+# neeto-pdf-nano
+
+`neeto-pdf-nano` provides shared PDF document support for neeto products. It
+publishes two packages:
+
+- `neeto-pdf-engine`, a Rails engine for storing PDF templates and mappings,
+  exposing document APIs, and rendering completed PDFs.
+- `@bigbinary/neeto-pdf-frontend`, a React package for managing templates,
+  mapping fields, previewing PDFs, and selecting email attachments.
+
+The host product still owns its routes and permissions, the model that owns the
+documents, the fields shown in the editor, preview records, email settings, and
+the values used when rendering a completed PDF.
+
+## Requirements
+
+The backend expects a Rails application with Active Record, Active Storage,
+PostgreSQL, and `NeetoCommonsBackend::Api::BaseController`. The provided
+migration uses UUIDs for document and owner IDs and uses `jsonb` columns.
+
+The frontend expects the standard neeto application setup for React Query,
+i18next, Axios, neetoUI, neetoMolecules, and Tailwind CSS. The email attachment
+components must be rendered inside a Formik.
+
+## Backend setup
+
+### 1. Add the engine
+
+Add the gem to the host application's `Gemfile`:
+
+```ruby
+source "NEETO_GEM_SERVER_URL" do
+  # Existing gems
+  gem "neeto-pdf-engine"
+end
+```
+
+Then install it:
+
+```sh
+bundle install
+```
+
+### 2. Install the database migration
+
+Copy only `db/migrate/20260706120000_create_neeto_pdf_engine_documents.rb` from
+this engine into the host application's `db/migrate` directory. Give the copied
+file a timestamp that does not conflict with a host migration, then run:
+
+```sh
+bundle exec rails db:migrate
+```
+
+Do not run the general engine migration installer yet. This repository still
+contains migrations inherited from the nano template that do not belong to the
+PDF feature.
+
+The migration stores `owner_id` as a UUID. Adjust and test the migration before
+running it if the host's owner model does not use UUID primary keys.
+
+### 3. Configure the document owner
+
+Create `config/initializers/neeto_pdf_engine.rb` in the host application and set
+the class name of the model that owns PDF documents:
+
+```ruby
+NeetoPdfEngine.owner_class = "Form"
+```
+
+The value must be a class-name string. The owner must either be the current
+organization or support `where(organization: @organization)`, because the engine
+scopes every request through `@organization`.
+
+Add an association to the owner model so its PDF documents are removed with the
+owner:
+
+```ruby
+class Form < ApplicationRecord
+  belongs_to :organization
+
+  has_many :neeto_pdf_documents,
+    as: :owner,
+    class_name: "NeetoPdfEngine::Document",
+    dependent: :destroy
+end
+```
+
+### 4. Mount the engine
+
+Mount the engine at a stable path in `config/routes.rb`:
+
+```ruby
+mount NeetoPdfEngine::Engine, at: "/neeto_pdf"
+```
+
+The frontend API base URL for this mount point is:
+
+```js
+const pdfApiBaseUrl = "/neeto_pdf/api/v1";
+```
+
+### 5. Enforce product permissions
+
+The engine authenticates requests and scopes documents to the current
+organization and owner. It does not know the host product's permission model.
+The host must enforce permissions for every applicable read and write endpoint
+on the server. Add the check through the host's shared API authorization layer
+or prepend a host-owned controller override with a permission `before_action` to
+`NeetoPdfEngine::Api::V1::DocumentsController`.
+
+The frontend `canManage` prop only controls parts of the interface. It is not a
+server-side authorization check and must not be used as one.
+
+## Frontend setup
+
+### 1. Add the package
+
+Install the frontend package in the host application:
+
+```sh
+yarn add @bigbinary/neeto-pdf-frontend pdf-lib@1.17.1 pdfjs-dist@6.1.200
+```
+
+The package uses the host's configured Axios instance and expects the normal
+neeto request and response case transformations. It also expects a React Query
+provider and an initialized i18next instance.
+
+Template uploads in the provided UI use the neetoMolecules `FileUpload` direct
+upload flow. Confirm that Active Storage direct uploads are configured and that
+uploaded files receive a signed ID before integrating the documents page.
+
+### 2. Include package styles
+
+The components use Tailwind utility classes from the installed package. Make
+sure the host's Tailwind stylesheet scans `@bigbinary` packages. For Tailwind
+CSS 4, add an appropriate `@source` path relative to the host stylesheet:
+
+```css
+@import "tailwindcss" important;
+@source "../../../../node_modules/@bigbinary";
+```
+
+Keep the host application's usual neetoUI and neetoMolecules styles enabled.
+There is no separate PDF package stylesheet to import.
+
+### 3. Load translations
+
+Applications using the standard neeto-commons build configuration load
+translations from installed `@bigbinary` packages automatically. Other hosts
+must merge the package's `app/javascript/src/translations/en.json` file into
+their i18next resources before rendering these components.
+
+### 4. Install the PDF.js worker
+
+The editor loads the PDF.js worker from `/pdf.worker.min.js`. Add a script to
+the host application's `package.json` that copies the worker from the installed
+`pdfjs-dist` version:
+
+```json
+{
+  "scripts": {
+    "sync:pdf-worker": "mkdir -p public && cp -f node_modules/pdfjs-dist/build/pdf.worker.min.mjs public/pdf.worker.min.js"
+  }
+}
+```
+
+Prepend `yarn sync:pdf-worker &&` to the host's existing `build` and `dev`
+commands so the sync runs in development and production. The host must serve the
+copied file at the root URL `/pdf.worker.min.js`.
+
+## Documents page
+
+`PdfDocumentsPage` lists the owner's templates and supports uploading, renaming,
+replacing, cloning, and deleting documents. The host owns the route that renders
+this page and the route used to open the editor.
+
+```jsx
+import { PdfDocumentsPage } from "@bigbinary/neeto-pdf-frontend";
+
+const Documents = ({ formId, selectedPdfDocumentIds }) => (
+  <PdfDocumentsPage
+    apiBaseUrl="/neeto_pdf/api/v1"
+    canManage={canManagePdfDocuments}
+    emailRoutes={{
+      submitter: submitterEmailSettingsUrl,
+      receiver: receiverEmailSettingsUrl,
+    }}
+    ownerId={formId}
+    selectedPdfDocumentIds={selectedPdfDocumentIds}
+    onOpenEditor={document => navigateToPdfEditor(document.id)}
+  />
+);
+```
+
+`onOpenEditor` receives the full document object, not only its ID.
+`selectedPdfDocumentIds` is display-only on this page; the host's email settings
+remain the source of truth for selected attachments.
+
+Use the optional `renderHeader` and `renderContent` props when the page needs to
+fit an existing host layout:
+
+```jsx
+<PdfDocumentsPage
+  renderHeader={({ actionBlock, title }) => (
+    <HostPageHeader {...{ actionBlock, title }} />
+  )}
+  renderContent={content => <HostPageContent>{content}</HostPageContent>}
+  {...otherProps}
+/>
+```
+
+## Editor page
+
+The host must load and normalize its product-specific fields and preview records
+before passing them to `PdfEditorPage`. The nano does not import form or
+submission APIs from a host product.
+
+```jsx
+import { PdfEditorPage } from "@bigbinary/neeto-pdf-frontend";
+
+<PdfEditorPage
+  apiBaseUrl="/neeto_pdf/api/v1"
+  canManage={canManagePdfDocuments}
+  documentId={documentId}
+  fields={pdfFields}
+  homeUrl={pdfDocumentsUrl}
+  isPreviewLoading={isPreviewLoading}
+  mode={mode}
+  ownerId={formId}
+  ownerRecord={form}
+  previewPage={previewPage}
+  previewRecord={submission}
+  previewTotal={submissionsTotal}
+  onBack={navigateToPdfDocuments}
+  onModeChange={setMode}
+  onPreviewPageChange={setPreviewPage}
+/>;
+```
+
+Pass a real `homeUrl` so the visible back action has a valid link. Use `onBack`
+as well when the host needs custom history behavior. The `mode` and
+`onModeChange` props are optional; pass them when editor mode should be stored
+in the host URL or state.
+
+### Field shape
+
+Each host field may include the following values:
+
+```js
+{
+  id: "record-id",
+  key: "email",
+  recordId: "record-id",
+  slug: "email",
+  label: "Email",
+  kind: "email",
+  icon: EmailIcon,
+  typeLabel: "Email"
+}
+```
+
+Use stable IDs and slugs. Convert HTML labels to plain text, omit records that
+cannot contain answers, and attach the host's icon and type label before passing
+fields to the editor. The nano adds its own system fields for form name,
+submission ID, and submission date.
+
+### Preview record shape
+
+Preview records should have an ID, a creation time, and responses whose slugs
+match the editor fields:
+
+```js
+{
+  id: "submission-id",
+  createdAt: "2026-07-14T10:30:00Z",
+  responses: [
+    { slug: "email", value: "oliver@example.com" }
+  ]
+}
+```
+
+The preview will be blank for a field when its slug has no matching response.
+
+## Email attachment controls
+
+`PdfAttachmentSelector` and `PdfAttachmentsPreview` read the top-level
+`pdfDocumentIds` field from Formik. Pass all available PDF documents to both
+components; the preview component filters the selected documents itself.
+
+```jsx
+import {
+  PdfAttachmentSelector,
+  PdfAttachmentsPreview,
+} from "@bigbinary/neeto-pdf-frontend";
+import { Formik, Form } from "formik";
+
+<Formik
+  initialValues={{ pdfDocumentIds: persistedPdfDocumentIds }}
+  onSubmit={saveEmailSettings}
+>
+  <Form>
+    <PdfAttachmentSelector documents={pdfDocuments} />
+    <PdfAttachmentsPreview documents={pdfDocuments} />
+  </Form>
+</Formik>;
+```
+
+In a typical host integration, this value appears in three forms:
+
+- Formik uses `pdfDocumentIds`.
+- Frontend API objects use `customFields.pdfDocumentIds`.
+- Rails persistence uses `custom_fields["pdf_document_ids"]`.
+
+The host email API must permit an array at `custom_fields[:pdf_document_ids]`.
+Remove IDs for deleted or inaccessible documents before saving email settings.
+
+## Rendering PDFs on the server
+
+The renderer knows how to place text on the template, but it does not know how
+the host stores or formats product data. Pass either a callable or an object
+that implements `value_for(mapping)`:
+
+```ruby
+document = form.neeto_pdf_documents.find(document_id)
+
+attachment = NeetoPdfEngine::Documents::RendererService.new(
+  document,
+  value_resolver: ->(mapping) { value_for_submission(mapping, submission) },
+  filename_context: { id: submission.id }
+).process
+```
+
+The result contains the generated filename, MIME type, and raw PDF bytes:
+
+```ruby
+{
+  filename: "agreement-123.pdf",
+  mime_type: "application/pdf",
+  content: "<binary PDF>"
+}
+```
+
+When rendering selected email attachments, always scope document IDs to their
+owner instead of querying IDs globally:
+
+```ruby
+documents = NeetoPdfEngine::Document.where(
+  owner_type: "Form",
+  owner_id: form.id,
+  id: selected_pdf_document_ids
+)
+```
+
+The host mailer decides whether the raw `content` needs Base64 encoding or any
+other transformation.
+
+The renderer currently turns whitespace into a single line and supports ASCII
+and Latin-1 text. Values outside that character range are removed, so hosts
+should account for this when deciding which fields can be rendered. Browser
+downloads and server-generated attachments can also differ for some styles;
+underline mappings are currently rendered only by the browser.
+
+## API reference
+
+With the engine mounted at `/neeto_pdf`, these endpoints are available:
+
+```text
+GET    /neeto_pdf/api/v1/documents
+POST   /neeto_pdf/api/v1/documents
+GET    /neeto_pdf/api/v1/documents/:id
+PATCH  /neeto_pdf/api/v1/documents/:id
+PUT    /neeto_pdf/api/v1/documents/:id
+PATCH  /neeto_pdf/api/v1/documents/:id/template_file
+POST   /neeto_pdf/api/v1/documents/:id/clone
+DELETE /neeto_pdf/api/v1/documents/:id
+```
+
+Every request must include `owner_id`. The engine derives the polymorphic owner
+type from `NeetoPdfEngine.owner_class`; clients cannot choose `owner_type`.
+Member actions are also scoped to that owner.
+
+The package UI uploads templates through the host's Active Storage direct upload
+setup and sends the signed blob ID. A custom client may instead send the PDF as
+multipart `FormData` under `template_file`. Do not set multipart boundaries
+manually.
+
+When a document is renamed, update both `name` and `output_filename` if the host
+does not expose a separate output filename field. The default filename follows
+this pattern:
+
+```text
+<parameterized-document-name>-{{id}}.pdf
+```
+
+The renderer replaces `{{id}}` with `filename_context[:id]`.
+
+## Local development
+
+To use a local checkout of the Rails engine from a neighboring host, point the
+host Gemfile to this repository:
+
+```ruby
+gem "neeto-pdf-engine", path: "../neeto-pdf-nano"
+```
+
+For frontend package development, follow the
+[frontend package development guide](https://neetozone.neetokb.com/p/a-d34cb4b0).
+
+## Publishing
+
+Follow the
+[building and releasing packages](https://neetozone.neetokb.com/articles/building-and-releasing-packages)
+guide to publish the gem or frontend package.

package/app/javascript/src/translations/ar.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "مرحبًا بك في نيتو ويل نانو"
+  }
+}

package/app/javascript/src/translations/bg.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Добре дошли в neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/ca.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Benvingut a neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/cs.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Vítejte na neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/da.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Velkommen til neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/de.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Willkommen beim neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/en.json

@@ -0,0 +1,109 @@
+{
+  "neetoPdf": {
+    "common": {
+      "cancel": "Cancel",
+      "height": "Height",
+      "save": "Save",
+      "width": "Width"
+    },
+    "pdfDocuments": {
+      "title": "PDF documents",
+      "description": "Upload your own PDF template and drop form answers onto it - one document is generated for every submission.",
+      "newDocument": "New document",
+      "attachedToEmail": "Attached to email",
+      "empty": "Upload a PDF template to get started.",
+      "uploadSuccess": "PDF document has been uploaded successfully.",
+      "uploadError": "Unable to upload PDF document.",
+      "errors": {
+        "invalidType": "must be a PDF file",
+        "fileTooLarge": "must be 10 MB or smaller"
+      },
+      "menu": {
+        "edit": "Edit",
+        "rename": "Rename",
+        "updatePdf": "Update PDF",
+        "clone": "Clone",
+        "delete": "Delete"
+      },
+      "rename": {
+        "title": "Rename document",
+        "label": "Name",
+        "placeholder": "Enter document name",
+        "success": "PDF document has been renamed successfully.",
+        "error": "Unable to rename PDF document."
+      },
+      "updatePdf": {
+        "success": "PDF document has been updated successfully.",
+        "error": "Unable to update PDF document."
+      },
+      "clone": {
+        "success": "PDF document has been cloned successfully.",
+        "error": "Unable to clone PDF document."
+      },
+      "delete": {
+        "title": "Delete PDF document?",
+        "message": "You are deleting \"{{name}}\". This can't be undone.",
+        "success": "PDF document has been deleted successfully.",
+        "error": "Unable to delete PDF document."
+      },
+      "sendPdfInEmail": {
+        "title": "Send PDF in email",
+        "description": "Attach the generated PDFs to the email sent on each submission.",
+        "submitter": "Send the PDF to the form submitter",
+        "notification": "Send the PDF in the notification email"
+      },
+      "attachments": {
+        "title": "Attachments",
+        "description": "Attach generated PDF documents to this email.",
+        "empty": "Upload a PDF document to attach it to this email.",
+        "fileType": "PDF",
+        "selected": "{{count}} PDF attached to email",
+        "selected_other": "{{count}} PDFs attached to email",
+        "previewTitle": "{{count}} attachment",
+        "previewTitle_other": "{{count}} attachments"
+      },
+      "editor": {
+        "back": "Back to PDF documents",
+        "addNewElement": "Add new element",
+        "addNewElementDescription": "To add elements, click or drag them onto the preview.",
+        "mapFields": "Map fields",
+        "previewWithData": "Preview with data",
+        "downloadPdf": "Download PDF",
+        "downloadTooltip": "Download this submission as a PDF",
+        "downloadHint": "Switch to Preview with data to download",
+        "downloadError": "Unable to generate the PDF.",
+        "formFields": "Form fields",
+        "formFieldsDescription": "Drag a field onto the document, or click + to place it.",
+        "searchFields": "Search fields",
+        "searchElements": "Search elements",
+        "answers": "Answers",
+        "system": "System",
+        "noFields": "No fields match your search.",
+        "addField": "Add to document",
+        "renderError": "Unable to render this PDF.",
+        "saveSuccess": "Field placements have been saved.",
+        "saveError": "Unable to save field placements.",
+        "systemFields": {
+          "formName": "Form name",
+          "submissionId": "Submission ID",
+          "submissionDate": "Submission date"
+        },
+        "field": {
+          "title": "Field",
+          "emptyTitle": "No field selected",
+          "emptyDescription": "Click a placed field on the document to edit its font, size, color and format, or drag its edges to resize.",
+          "font": "Font",
+          "size": "Size",
+          "format": "Format",
+          "fontColor": "Font color",
+          "alignment": "Alignment",
+          "remove": "Remove from document"
+        },
+        "preview": {
+          "counter": "Submission {{page}} of {{total}}",
+          "noSubmissions": "No submissions yet"
+        }
+      }
+    }
+  }
+}

package/app/javascript/src/translations/es-MX.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Bienvenido a neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/es.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Bienvenido a neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/et.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Tere tulemast neeto ratta nano"
+  }
+}

package/app/javascript/src/translations/fi.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Tervetuloa neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/fil.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Maligayang pagdating sa neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/fr.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Bienvenue dans neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/he.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "ברוכים הבאים ל-neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/hi.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "नीटो व्हील नैनो में आपका स्वागत है"
+  }
+}

package/app/javascript/src/translations/hr.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Dobrodošli u neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/hu.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Üdvözöljük a neeto wheel nano-n"
+  }
+}

package/app/javascript/src/translations/id.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Selamat datang di neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/index.js

@@ -0,0 +1,3 @@
+import en from "./en.json";
+
+export { en };

package/app/javascript/src/translations/it.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Benvenuto su neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/ja.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "ネートホイールナノへようこそ"
+  }
+}

package/app/javascript/src/translations/ko.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "네이토 휠 나노에 오신 것을 환영합니다"
+  }
+}

package/app/javascript/src/translations/nl.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Welkom bij neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/pl.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Witamy w neeto wheel nano"
+  }
+}

package/app/javascript/src/translations/pt-BR.json

@@ -0,0 +1,5 @@
+{
+  "neetoWheel": {
+    "welcomeScreen": "Bem-vindo ao neeto wheel nano"
+  }
+}