@rastr/pdf-template 0.0.0-stage → 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ondřej Synek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @rastr/pdf-template
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The PDF report template format (`version: 1`) and the layout engine shared with `Rastr.Export`.
+`validateTemplate` checks a template and reports every issue with its path. `layoutReport` turns a
+template and data into absolutely placed pages. The same algorithm in C# produces the same layout to
+0.01 mm (contract fixtures in `contracts/pdf-layout`).
+
+`ReportInput.summaryRow` (texts per field) is drawn as a bold row with a rule above it after the last
+table row when `table.summary` is true; it moves to a new page (with the header) when it does not fit.
+Expressions reading a missing `summary.*` value produce a layout warning.
+
+## Template storage
+
+Templates are stored per grid (`gridId`). `shared` means visible to the whole company; otherwise only
+its author sees it. The server decides this from the signed-in user. Each grid has at most one
+default template.
+
+```ts
+import { createLocalTemplateStore, createRestTemplateStore, templateLoader } from '@rastr/pdf-template';
+
+const local = createLocalTemplateStore(); // one localStorage key, 'rastr.pdf-templates'
+const rest = createRestTemplateStore({ url: '/api/pdf-templates', headers: () => ({ Authorization: `Bearer ${token}` }) });
+
+await rest.save({ gridId: 'orders', name: 'Přehled', isDefault: true, shared: false, template });
+const loadDefault = templateLoader(rest, 'orders'); // for GridPdfOptions.template; null → default look
+```
+
+- `TemplateStore` has `list(gridId)`, `load(id)`, `save(input)` (no `id` creates a new template) and
+  `remove(id)`. An application can implement it over its own API.
+- A failed request is a `TemplateStoreError` with `status`. A 400 for an invalid template carries the
+  server's `issues`.
+- A stored `template` is `unknown`: validate it before use.
+- REST contract: `contracts/wire/pdf-templates.md`. On the server,
+  `app.MapRastrPdfTemplates("/api/pdf-templates")` (`Rastr.AspNetCore`) maps it over the
+  application's `IPdfTemplateRepository` and validates templates before they are stored.