@tonzxz/government-forms 0.1.0

package/FORM_CATALOG.md

@@ -0,0 +1,44 @@
+# Form catalog
+
+Import a listed code as `@tonzxz/government-forms/inventory/<code>`. For example: `/inventory/pr`. The requested `/inventory/pplc` path aliases `/inventory/ppelc`. Each report entry exports default/`Form`, `definition`, and `Preview`, plus the dedicated components listed below. Purchase Order and Inventory item use `/inventory/po` and `/inventory/item` with their dedicated props.
+
+All 25 codes below have a baseline configurable entry form through `GovernmentForm`. “Baseline only” means the standalone registry-based renderer, not the page-specific embedded editor. Dedicated entry components retain their extracted props and layouts. Approval flows, lookup loading, and inventory effects are supplied by the consumer.
+
+| Code | Dedicated entry component | Document preview |
+| --- | --- | --- |
+| `pr` | PurchaseRequestCreateForm | `PrDocumentPreview` |
+| `ris` | RisCreateForm / RISForm | `RisDocumentPreview / RISPreview` |
+| `stock-card` | StockCardCreateForm | `ScDocumentPreview / StockCardPreview` |
+| `property-card` | Baseline only | `PropertyCardPreview` |
+| `iar` | IarCreateForm | `IarDocumentPreview / IarPreview` |
+| `rsmi` | RsmiCreateForm | `RsmiDocumentBody` |
+| `wmr` | WastematerialReportWmrCreateForm | `WmrDocumentPreview / WmrRecordPreview` |
+| `ptr` | Baseline only | `PtrPreview` |
+| `iirup` | Baseline only | `IirupPreview` |
+| `ppelc` | Baseline only | `PPELCPreview` |
+| `spc` | Baseline only | `SpcPreview` |
+| `splc` | SplcEntryForm (line-item editor) | `SplcPreview` |
+| `regspi` | RegSpiCreateForm | `RegSpiPreview` |
+| `itr` | ItrCreateForm | `ItrPreview` |
+| `rrsp` | Baseline only | `RrspPreview` |
+| `rspi` | Baseline only | `RspiPreview` |
+| `rpcsp` | Baseline only | `RpcspPreview` |
+| `rlsddsp` | Baseline only | `RlsddspPreview` |
+| `iirusp` | IiruspCreateForm | `IiruspDocumentPreview` |
+| `par` | Baseline only | `ParPreview` |
+| `ics` | Baseline only | `IcsPreview` |
+| `rlsddp` | RlsddpCreateForm | `RlsddpDocumentPreview / RlsddpPreview` |
+| `rpci` | Baseline only | `RpciPreview` |
+| `rpcppe` | Baseline only | `RpcppePreview` |
+| `rsmp` | RsmpCreateForm | `RsmpDocumentPreview` |
+
+Additional extracted components outside the reports directory:
+
+| Form | Entry | Preview |
+| --- | --- | --- |
+| Purchase Order | `PurchaseOrderCreateForm` | `PurchaseOrderPreview` |
+| Inventory item | `InventoryItemForm` | `InventoryItemPreview` |
+
+Purchase Order receives eligible purchase requests, approver display data and the generated PO number from the host. It does not query or authorize those records itself. Inventory item types are exported as `Inventory` and `InventoryStatus`.
+
+`extraction-manifest.json` records original source paths and SHA-256 hashes for traceability. Most source components are copied with import rewrites; the PO and RSMP forms were separated from their page/modal shells. Agency branding and remote font loading were removed where found. These are extracted application templates, not a guarantee that every agency accepts an identical document layout.

package/README.md

@@ -0,0 +1,165 @@
+# Government forms
+
+An installable React 19 library extracted from BCS IMS. The npm package is `@tonzxz/government-forms`; its inventory entry point is `@tonzxz/government-forms/inventory`. The package is configured for public npm distribution.
+
+## Included
+
+- 25 configurable report definitions, available through `GovernmentForm`.
+- Extracted dedicated report entry forms, purchase-order entry/preview, and inventory-item entry/preview.
+- Printable document components and existing PDF, print, and spreadsheet helpers.
+- TypeScript declarations and prebuilt CSS. No Next.js, database, environment variables, authentication provider, or `@repo/*` packages required.
+
+See [FORM_CATALOG.md](./FORM_CATALOG.md) for exact coverage. **Configurable definitions are the original baseline field configurations, not identical copies of every live page.** Several live pages add data lookups, workflow-specific fields, and actions; these remain the consumer's responsibility. Use the dedicated components where listed to retain those extracted entry layouts.
+
+## Install
+
+Install from npm:
+
+```sh
+npm install @tonzxz/government-forms react@^19 react-dom@^19
+```
+
+Before publishing, install the generated archive in a different repository:
+
+```sh
+npm install /absolute/path/to/tonzxz-government-forms-0.1.0.tgz
+```
+
+The public package can be installed without npm authentication. Consumers use the exact same package version independently; deployments and databases stay separate.
+
+
+## Inventory import paths
+
+Install the package once with `npm install @tonzxz/government-forms`. `/inventory` and `/inventory/pr` are import paths inside that package, not separate npm installations.
+
+```tsx
+import { GovernmentForm, createFormValues } from "@tonzxz/government-forms/inventory";
+import PRForm, { definition, Preview, PurchaseRequestCreateForm } from "@tonzxz/government-forms/inventory/pr";
+import PPLCForm from "@tonzxz/government-forms/inventory/pplc";
+import "@tonzxz/government-forms/inventory/styles.css";
+
+// Inside a React component:
+const [value, setValue] = useState(() => createFormValues(definition));
+<PRForm value={value} onChange={setValue} onSubmit={savePurchaseRequest} />;
+```
+
+Every report code in the catalog has an `/inventory/<code>` entry. Each exports its configurable form as both `default` and `Form`, plus `definition`, `Preview`, and the original named preview. Dedicated entry components are also exported where available. `Preview` and dedicated entry components retain their own typed props; their data models differ from the generic form payload.
+
+`/inventory/pplc` is an alias for the existing PPELC form (`/inventory/ppelc`); its document code stays `ppelc`. Additional paths `/inventory/po` and `/inventory/item` export their dedicated entry components as `default`/`Form` and their previews as `Preview`; these two do not have a generic `definition`. Existing root and `/forms/<code>` imports remain supported.
+
+## A complete controlled form
+
+In Next.js, put this component in a file with `"use client"` and import the CSS from the root layout. In Vite, import the CSS once from the application entry point. The compiled stylesheet includes Tailwind's reset and utility rules; import it before application overrides. Tailwind is not required in the consuming project.
+
+```tsx
+"use client";
+import { useState } from "react";
+import {
+  GovernmentForm,
+  createFormValues,
+  formDefinitions,
+} from "@tonzxz/government-forms/inventory";
+import "@tonzxz/government-forms/inventory/styles.css";
+
+export function PurchaseRequest() {
+  const [value, setValue] = useState(() => createFormValues(formDefinitions.pr));
+
+  return (
+    <GovernmentForm
+      code="pr"
+      value={value}
+      onChange={setValue}
+      onSubmit={async data => {
+        const response = await fetch("/api/purchase-requests", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(data),
+        });
+        if (!response.ok) throw new Error("Unable to save the purchase request.");
+      }}
+    />
+  );
+}
+```
+
+`/api/purchase-requests` is an illustrative host endpoint, not provided by the library. The payload is `{ values: Record<string,string>, rows: Record<string,string>[] }`. Map it to your own API model. A successful callback does not clear the form; the host decides whether to reset or navigate. Errors display inline and preserve entered values. Submission is locked while the callback is pending.
+
+The generic form validates required fields, finite numeric values, integer fields, dates and select options. It does not assert stock availability, approval authority, document numbering uniqueness, calculated totals, or minimum line count. Add client validation through `validate`, and enforce all business rules and authorization on the server.
+
+## Agency customization
+
+```tsx
+const definition = {
+  ...formDefinitions.pr,
+  title: "Agency purchase request",
+  fields: [
+    ...formDefinitions.pr.fields,
+    { id: "fundingCode", label: "Funding code", type: "text" as const, required: true },
+  ],
+};
+// Pass definition={definition} to GovernmentForm.
+```
+
+Create a new definition object rather than mutating the shared registry. Override labels, field order, options, required/read-only flags, and line-item fields. Pass React children for additional sections. Dates marked `defaultToday` use the local calendar date. Auto-generated document numbers must be supplied by the host.
+
+For a specific form use `@tonzxz/government-forms/inventory/pr` (default export plus named `Form`, `definition`, `Preview`, and `PurchaseRequestCreateForm`), or `@tonzxz/government-forms/inventory/definitions` for server-side metadata and validation without the React entry point.
+
+## Existing dedicated components
+
+```tsx
+import { PurchaseRequestCreateForm, ParPreview } from "@tonzxz/government-forms/inventory";
+import type { ComponentProps } from "react";
+type PurchaseRequestProps = ComponentProps<typeof PurchaseRequestCreateForm>;
+```
+
+Dedicated components keep their original typed props: values, field-change callbacks, line-item operations, optional lookup results, and tab state. They do not automatically fetch or save. The declarations show each component's full interface. PR types are also available from `@tonzxz/government-forms/reports/pr/types`.
+
+```tsx
+<ParPreview
+  entityName="Your agency"
+  parNo="PAR-2026-001"
+  items={[{ description: "Laptop", quantity: "1", unit: "unit", amount: "45000" }]}
+/>
+```
+
+`ScDocumentPreview` accepts an optional `entityName` prop; `PurchaseOrderPreview` uses `data.entityName`. Agency names are not hard-coded. Preview layouts retain their source paper sizes, so place them inside an overflow container on narrow screens.
+
+## Export utilities
+
+```ts
+import { exportPreviewElementToPdf } from "@tonzxz/government-forms/gam/utils/export-preview-pdf";
+import { printElement } from "@tonzxz/government-forms/gam/utils/print-element";
+import { exportParXlsx } from "@tonzxz/government-forms/gam/utils/export-par-xlsx";
+```
+
+Call DOM, PDF, download, and print helpers in the browser after rendering and loading any supplied images. Source report helpers and types are available through the corresponding `reports/<report>/...` subpaths. Font rendering and final pagination should be checked against each client's accepted document template before rollout.
+
+## What the host supplies
+
+Authentication, permissions, database tables/migrations, API adapters, attachments, record numbering, approval assignments, signatures, workflow transitions, stock transactions, and audit history. The package does not install backend modules or create routes. Client-side status fields and displayed role controls do not grant authorization.
+
+Application page shells, dashboards, authentication/account forms, support/ticket forms, and report compilation/issuance workflow pages are not exported as complete applications. Their form data and relevant report templates are represented in the catalog where applicable.
+
+## Development and release
+
+From this workspace:
+
+```sh
+pnpm --filter @tonzxz/government-forms build
+pnpm --filter @tonzxz/government-forms test
+pnpm --filter @tonzxz/government-forms typecheck
+cd packages/government-forms
+npm pack --pack-destination artifacts
+```
+
+`npm pack` builds and tests first. Only `dist`, documentation and the extraction manifest are included. The package has no install scripts and does not run database migrations. The source package directory can be moved into its own repository: its build dependencies use registry versions, without workspace catalogs. `scripts/extract.mjs` is an explicit migration tool that alone requires the original repository; normal build/publish never runs it. Re-running extraction overwrites the copied components and requires review.
+
+Publishing requires an account authorized to publish under the `@tonzxz` personal scope. `publishConfig.access` is `public`. Authenticate interactively using `npm login`, verify the account using `npm whoami`, then run `npm publish` from this package directory. Never commit registry tokens. For subsequent releases, increment the version and document breaking prop, definition or print-layout changes. Pin the selected release in each client application.
+
+The original application is unchanged and still uses its original form files. This extraction is an initial snapshot, recorded in `extraction-manifest.json`; subsequent fixes should be made in this package and adopted by clients through versioned releases. Switching BCS IMS itself to consume this package is a separate integration step.
+
+## Independent consumer verification
+
+After packing, `node scripts/test-consumer.mjs` installs the archive into an OS temporary directory, checks consumer TypeScript without skipping declaration errors, builds a Vite browser application, and tests a native ESM import. This check requires network access and does not modify another client repository.
+
+`artifacts/consumer-path.txt` records that fixture. Run Vite there on `127.0.0.1:4178`, then `node scripts/test-browser.mjs` exercises the fixture in headless Chrome. Set `CHROME_EXECUTABLE` on systems where Chrome is not at the default macOS path. Screenshots are saved under ignored `artifacts/`.