@haneinfo/frontend-instances 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 Haneinfo. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the proprietary and
+confidential property of Haneinfo. No part of the Software may be copied, modified, merged,
+published, distributed, sublicensed, or sold without the prior written permission of Haneinfo.
+
+The Software is provided for internal use by Haneinfo and its authorized personnel only, and is
+NOT licensed for external distribution or open-source use.
+
+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 HANEINFO 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,69 @@
-# Temporary Holding Version
+# @haneinfo/frontend-instances
 
-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.
+Reusable instance lists, collaboration and import/export pages for React 19 / Next 16.
+Backend packages stay free of React and NestJS is not a dependency of this package.
+
+## Mounting
+
+Import `renderInstanceListPage`, `renderInstanceDetailPage` and `renderImportPage` from
+`@haneinfo/frontend-instances/server`. Each returns a server-renderable React tree. Supply:
+
+- `apiFetch<T>(path, init?)`, using the current authenticated session and an App-owned API URL.
+- `LinkComponent`, `t(LabelKey)`, `getCurrentUser()`, and `basePath`.
+- An App Server Action calling `performInstanceRequest(apiFetch, request)` and returning
+  `{ data }` or `{ error: instanceError(error) }` after checking the session.
+- For imports, an authenticated `uploadAction(FormData)` calling `readImportUpload`, plus
+  the App's `{ code, label }[]` machine choices.
+
+The list additionally takes `machineCode` and promised `searchParams: { query?: string }`.
+The detail takes `id`. The import takes `machines` and `uploadAction`.
+All UI labels are injected. System field labels use `t`; Form labels stay verbatim from the API.
+See `LabelKey` and the complete English/zh-TW mounting examples in
+`validation/equipment-loan/instance-frontend/app/` in the source repository.
+
+Add `@source "../../node_modules/@haneinfo/frontend-instances/dist";` to the App's Tailwind
+CSS source declarations. Mount navigation in the App's sidebar, not generated plugin files.
+Set the App's Server Action body limit to allow multipart uploads (the example uses 16 MB).
+The backend HTTP body limit remains App-owned; API rejections are shown in the UI.
+
+## Client components and contracts
+
+`@haneinfo/frontend-instances/client` exports `ListClient`, `DetailClient`, `ImportClient`,
+`FilterEditor`, `JobStatus`, `JobReport`, `ImportConfirmation` and `prepareFilter`.
+Use the server renderers for normal mounting. `@haneinfo/frontend-instances/contracts` exports
+HTTP-only types and `labelKeys`. The server entry also exports the contracts, `dateRange`,
+`importMapping`, `normalizeQuery`, `performInstanceRequest`, `readImportUpload` and `instanceError`.
+
+Lists support PREDICATE/GROUP AND/OR, all eight operators, inclusive date ranges, up to eight
+sort keys, selected columns and offset/limit pagination (1–500). IN uses one literal per line.
+Datetime-local controls are explicitly UTC. Exports use the last applied query, not unapplied
+editor changes. Saved views default to private; sharing controls depend only on `canShare`.
+
+Details use pinned subject Form labels and the merged timeline; mentions come only from the
+instance-specific mentionable API. Following comes from the timeline or mutation response.
+Comments are append-only plain text and AI comments have a visible attribution.
+
+CSV and xlsx headers are read using csv-parse and ExcelJS on the server, with a 10 MB upload
+bound. The backend performs the complete preflight and authorization. Duplicate keys are
+optional, mapped top-level keys with a five-key maximum. Preflight never confirms an import.
+Confirmation requires a separate button click; global errors and zero valid rows disable it.
+Re-upload to change a completed preflight's mapping.
+
+`JobStatus` polls every two seconds, stops on terminal status or failure, and bounds automatic
+polling to 90 requests. A manual refresh resumes polling. Job state is owner-authorized by the
+backend. Binary result bytes and uploaded job params are removed before returning jobs to clients.
+
+## Downloads and safety
+
+Mount `${basePath}/download?path=...` as an authenticated, no-store streaming GET proxy. Constrain
+the path to `/import-export/(imports|exports)/<id>/file`, forward the current session token to
+that exact backend-provided `downloadPath`, and forward its disposition/type. Never synthesize
+job download paths or put file bytes/tokens in the URL. The App example includes this route.
+
+Use real Next Server Actions so same-origin CSRF checks apply. All mutations have an immediate
+in-memory submission lock and disabled pending buttons. The backend remains authoritative for
+authorization and validation; the UI does not recreate RBAC. 401/403/404 display generic localized
+messages without raw API details. All user content is rendered as text nodes, including errors,
+field values, names, and timeline details. No HTML or Markdown rendering is used.
+
+No instance creation, submission, approval, rejection or transition controls are included.

package/agent-guide.md

@@ -0,0 +1,35 @@
+# Instance frontend agent guide
+
+Use this package to mount shared instance lists, read-only details with collaboration, and
+human-confirmed bulk imports. Read the README for exact entry points and injected dependencies.
+Do not add React or Next dependencies to list-view, collaboration, import-export or background-jobs.
+
+## HTTP contracts
+
+- List metadata: GET `/list-view/machines/:code/fields`; query: POST the same machine's `/query`.
+- Views: GET/POST `/list-view/views`; PATCH `/list-view/views/:id/sharing`. Preserve `canShare`.
+- Details: GET `/state-machine-instances/:id` uses the pinned subject Form bundle.
+- Timeline: GET `/state-machine-instances/:id/timeline?offset=&limit=50`, including `following`.
+- People: GET `/state-machine-instances/:id/mentionable?q=`, at most twenty eligible people.
+- Collaboration: POST `comments` with `{ body }`, using `@{id}` from the people picker;
+  POST/DELETE `follow`. There are no comment edit/delete controls.
+- Imports: GET `/import-export/machines/:code/fields`; POST `/import-export/imports/preflight`
+  with file format/base64, header-to-key mapping, and optional duplicateKey (one to five keys).
+- Human confirmation: POST `/import-export/imports/:id/confirm` with `{ confirmed: true }` only
+  from an explicit button event, never from polling, render, an effect, or an AI tool.
+- Exports: POST `/import-export/exports` with `{ format, source: { machineCode, query } }`.
+- Jobs: GET `/background-jobs/:id`; downloads use the result's exact `downloadPath` through
+  an App-owned authenticated streaming proxy. The API alone decides job ownership and expiry.
+
+The minimal types are local HTTP contracts; never import backend runtime packages for types.
+Keep the API adapter and authentication in the App, with Server Action CSRF protection.
+Keep API error values and all user-controlled content as plain text. Do not inspect role names
+to decide sharing or visibility. Use both English and zh-TW translations for new UI text.
+
+## Validation
+
+Run package build/typecheck/tests and workspace build:graph, lint, specs:lint. Component tests
+render actual HTML, test authorization and escaping, and verify confirmation and parameters.
+Use the equipment-loan validation overlay for full production-build/browser acceptance. Always
+restore and finish it, including original manifest/lockfile bytes and dependency installation.
+Do not release, version, approve a decision, or commit as part of frontend validation.

package/dist/client.d.ts

@@ -0,0 +1,62 @@
+import { type Condition, type FormField, type ImportField, type InstanceAction, type InstanceQuery, type Job, type JobResult, type Labels, type ListResult, type QueryField, type SavedView, type Timeline, type UploadAction } from './contracts.js';
+export declare function FilterEditor({ condition, fields, labels, onChange, depth, }: {
+    condition: Condition;
+    fields: QueryField[];
+    labels: Labels;
+    onChange: (value: Condition) => void;
+    depth?: number;
+}): import("react").JSX.Element;
+declare function prepareFilter(condition: Condition, fields: QueryField[]): Condition | undefined;
+export { prepareFilter };
+export declare function ListClient({ fields, initial, initialQuery, views: initialViews, machineCode, basePath, labels: t, action, }: {
+    fields: QueryField[];
+    initial: ListResult;
+    initialQuery: InstanceQuery;
+    views: SavedView[];
+    machineCode: string;
+    basePath: string;
+    labels: Labels;
+    action: InstanceAction;
+}): import("react").JSX.Element;
+export declare function DetailClient({ id, data, fields, state, submitterId, createdAt, initial, initialNumbers, labels: t, action, }: {
+    id: string;
+    data: Record<string, unknown>;
+    fields: FormField[];
+    state: string;
+    submitterId: string | null;
+    createdAt: string;
+    initial: Timeline;
+    initialNumbers?: string[];
+    labels: Labels;
+    action: InstanceAction;
+}): import("react").JSX.Element;
+export declare function JobStatus({ initial, labels: t, action, downloadBase, onComplete, }: {
+    initial: Job;
+    labels: Labels;
+    action: InstanceAction;
+    downloadBase: string;
+    onComplete?: (job: Job) => void;
+}): import("react").JSX.Element;
+export declare function JobReport({ result, labels: t, downloadBase, }: {
+    result: JobResult;
+    labels: Labels;
+    downloadBase: string;
+}): import("react").JSX.Element;
+export declare function ImportClient({ machines, fields: initialFields, labels: t, action, uploadAction, downloadBase, }: {
+    machines: {
+        code: string;
+        label: string;
+    }[];
+    fields: ImportField[];
+    labels: Labels;
+    action: InstanceAction;
+    uploadAction: UploadAction;
+    downloadBase: string;
+}): import("react").JSX.Element;
+export declare function ImportConfirmation({ job, labels: t, pending, onConfirm, }: {
+    job: Job;
+    labels: Labels;
+    pending: boolean;
+    onConfirm: () => void;
+}): import("react").JSX.Element | null;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.tsx"],"names":[],"mappings":"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"}