@usgb/forms 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 USGB
+
+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

@@ -0,0 +1,110 @@
+# @usgb/forms
+
+Sample React package that builds with [tsup](https://tsup.egoist.dev/) and publishes to npm using [OIDC trusted publishing](https://docs.npmjs.com/trusted-publishers/). Releases do not use a long-lived `NPM_TOKEN`.  Replace this code and this readme with real versions.
+
+## What's included
+
+- React 18+ form primitives (`Form`, `TextField`) with TypeScript types
+- Dual ESM/CJS build output in `dist/`
+- CI on pull requests
+- Manual publish from GitHub Actions via OIDC (no git tags)
+
+## Local development
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+Peer dependencies: `react` and `react-dom` >= 18.
+
+## Publish with OIDC
+
+Trusted publishing creates a trust relationship between npm and this repository. GitHub Actions mints a short-lived OIDC token; npm CLI 11.5.1+ exchanges it for a publish credential. No npm write token is stored in GitHub.
+
+Requirements:
+
+- Node 22.14.0+ (this workflow uses Node 24)
+- npm 11.5.1+
+- GitHub-hosted runners (self-hosted runners are not supported)
+- A public GitHub repository if you want automatic provenance attestations
+
+### 1. Point `package.json` at the real package and repo
+
+Update these fields before the first publish. npm checks that `repository.url` matches the GitHub repository that is publishing:
+
+```json
+{
+  "name": "@your-scope/forms",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OWNER/REPO.git"
+  }
+}
+```
+
+### 2. Create the npm package (first publish only)
+
+Trusted publishers are configured on an existing package. Create the package on [npmjs.com](https://www.npmjs.com/) if it does not exist yet, or publish once with a granular token and then switch to OIDC.
+
+### 3. Add a trusted publisher on npmjs.com
+
+Open the package **Settings → Trusted Publisher**, choose **GitHub Actions**, and enter values that match this repository exactly (all fields are case-sensitive):
+
+| Field | Value |
+| --- | --- |
+| Organization or user | `OWNER` |
+| Repository | `REPO` |
+| Workflow filename | `publish.yml` |
+| Environment name | `npm-publish` |
+| Allowed actions | `npm publish` |
+
+Use only the workflow filename (`publish.yml`), not `.github/workflows/publish.yml`. npm validates the top-level workflow that started the run.
+
+### 4. Protect the GitHub environment (recommended)
+
+Create a GitHub environment named `npm-publish` and add required reviewers if you want a human approval step before each release. The environment name in the workflow and on npmjs.com must match.
+
+### 5. Release
+
+Bump `version` in `package.json` without creating a git tag, then run the publish workflow from the Actions tab.
+
+```bash
+npm version patch --no-git-tag-version   # or minor / major
+git add package.json package-lock.json
+git commit -m "Release 0.1.1"
+git push origin main
+```
+
+In GitHub, open **Actions → Publish Package → Run workflow** and run it on `main`. [`.github/workflows/publish.yml`](.github/workflows/publish.yml) then:
+
+1. Requests `id-token: write` so Actions can mint an OIDC token
+2. Installs Node 24 (ships npm 11.x)
+3. Runs tests and the library build
+4. Publishes the version already in `package.json` with **no token secret**
+
+npm automatically attaches [provenance](https://docs.npmjs.com/generating-provenance-statements/) for public packages published from a public repository. Do not pass `--provenance`; the CLI enables it when OIDC publishing is in use.
+
+### 6. Lock down token publishing (recommended)
+
+After the first OIDC publish succeeds, on the package **Settings → Publishing access** select **Require two-factor authentication and disallow tokens**. Trusted publishing keeps working because it does not use classic npm tokens.
+
+## Workflow notes
+
+- `permissions.id-token: write` is required. Without it the CLI cannot obtain an OIDC token and publish fails with `ENEEDAUTH`.
+- Do not set `NODE_AUTH_TOKEN` or `NPM_TOKEN` on the publish step. A leftover token can mask a broken trusted-publisher config.
+- `actions/setup-node` must set `registry-url: https://registry.npmjs.org`.
+- If this workflow is later called from another workflow, npm still checks the **calling** workflow filename, and both jobs need `id-token: write`.
+- Private dependencies still need a **read-only** npm token for `npm ci`. Trusted publishing only authenticates `npm publish`.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+| --- | --- |
+| `ENEEDAUTH` / unable to authenticate | Workflow filename, repo, or environment does not match the trusted publisher |
+| 404 during OIDC exchange | Trusted publisher is missing, or npm CLI is older than 11.5.1 |
+| Provenance missing | Repository or package is private |
+| `npm ci` fails on private deps | Need a read-only install token; OIDC does not apply to install |
+
+See the [npm trusted publishing docs](https://docs.npmjs.com/trusted-publishers/) for the full provider matrix and security recommendations.

package/dist/index.cjs

@@ -0,0 +1,64 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Form: () => Form,
+  TextField: () => TextField
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/Form.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function Form({ children, ...props }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("form", { ...props, children });
+}
+
+// src/TextField.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function TextField({
+  label,
+  error,
+  id,
+  name,
+  ...props
+}) {
+  const inputId = id ?? name;
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { children: [
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("label", { htmlFor: inputId, children: label }),
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      "input",
+      {
+        id: inputId,
+        name,
+        ...props,
+        "aria-invalid": error ? "true" : void 0,
+        "aria-describedby": error && inputId ? `${inputId}-error` : void 0
+      }
+    ),
+    error ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { id: inputId ? `${inputId}-error` : void 0, role: "alert", children: error }) : null
+  ] });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Form,
+  TextField
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/Form.tsx","../src/TextField.tsx"],"sourcesContent":["export { Form } from \"./Form\";\nexport type { FormProps } from \"./Form\";\n\nexport { TextField } from \"./TextField\";\nexport type { TextFieldProps } from \"./TextField\";\n","import type { FormHTMLAttributes, ReactNode } from \"react\";\n\nexport type FormProps = FormHTMLAttributes<HTMLFormElement> & {\n  children: ReactNode;\n};\n\nexport function Form({ children, ...props }: FormProps) {\n  return <form {...props}>{children}</form>;\n}\n","import type { InputHTMLAttributes } from \"react\";\n\nexport type TextFieldProps = InputHTMLAttributes<HTMLInputElement> & {\n  label: string;\n  error?: string;\n};\n\nexport function TextField({\n  label,\n  error,\n  id,\n  name,\n  ...props\n}: TextFieldProps) {\n  const inputId = id ?? name;\n\n  return (\n    <div>\n      <label htmlFor={inputId}>{label}</label>\n      <input\n        id={inputId}\n        name={name}\n        {...props}\n        aria-invalid={error ? \"true\" : undefined}\n        aria-describedby={error && inputId ? `${inputId}-error` : undefined}\n      />\n      {error ? (\n        <p id={inputId ? `${inputId}-error` : undefined} role=\"alert\">\n          {error}\n        </p>\n      ) : null}\n    </div>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACOS;AADF,SAAS,KAAK,EAAE,UAAU,GAAG,MAAM,GAAc;AACtD,SAAO,4CAAC,UAAM,GAAG,OAAQ,UAAS;AACpC;;;ACSI,IAAAA,sBAAA;AAVG,SAAS,UAAU;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAAmB;AACjB,QAAM,UAAU,MAAM;AAEtB,SACE,8CAAC,SACC;AAAA,iDAAC,WAAM,SAAS,SAAU,iBAAM;AAAA,IAChC;AAAA,MAAC;AAAA;AAAA,QACC,IAAI;AAAA,QACJ;AAAA,QACC,GAAG;AAAA,QACJ,gBAAc,QAAQ,SAAS;AAAA,QAC/B,oBAAkB,SAAS,UAAU,GAAG,OAAO,WAAW;AAAA;AAAA,IAC5D;AAAA,IACC,QACC,6CAAC,OAAE,IAAI,UAAU,GAAG,OAAO,WAAW,QAAW,MAAK,SACnD,iBACH,IACE;AAAA,KACN;AAEJ;","names":["import_jsx_runtime"]}

package/dist/index.d.cts

@@ -0,0 +1,15 @@
+import * as react from 'react';
+import { FormHTMLAttributes, ReactNode, InputHTMLAttributes } from 'react';
+
+type FormProps = FormHTMLAttributes<HTMLFormElement> & {
+    children: ReactNode;
+};
+declare function Form({ children, ...props }: FormProps): react.JSX.Element;
+
+type TextFieldProps = InputHTMLAttributes<HTMLInputElement> & {
+    label: string;
+    error?: string;
+};
+declare function TextField({ label, error, id, name, ...props }: TextFieldProps): react.JSX.Element;
+
+export { Form, type FormProps, TextField, type TextFieldProps };

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import * as react from 'react';
+import { FormHTMLAttributes, ReactNode, InputHTMLAttributes } from 'react';
+
+type FormProps = FormHTMLAttributes<HTMLFormElement> & {
+    children: ReactNode;
+};
+declare function Form({ children, ...props }: FormProps): react.JSX.Element;
+
+type TextFieldProps = InputHTMLAttributes<HTMLInputElement> & {
+    label: string;
+    error?: string;
+};
+declare function TextField({ label, error, id, name, ...props }: TextFieldProps): react.JSX.Element;
+
+export { Form, type FormProps, TextField, type TextFieldProps };

package/dist/index.js

@@ -0,0 +1,36 @@
+// src/Form.tsx
+import { jsx } from "react/jsx-runtime";
+function Form({ children, ...props }) {
+  return /* @__PURE__ */ jsx("form", { ...props, children });
+}
+
+// src/TextField.tsx
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+function TextField({
+  label,
+  error,
+  id,
+  name,
+  ...props
+}) {
+  const inputId = id ?? name;
+  return /* @__PURE__ */ jsxs("div", { children: [
+    /* @__PURE__ */ jsx2("label", { htmlFor: inputId, children: label }),
+    /* @__PURE__ */ jsx2(
+      "input",
+      {
+        id: inputId,
+        name,
+        ...props,
+        "aria-invalid": error ? "true" : void 0,
+        "aria-describedby": error && inputId ? `${inputId}-error` : void 0
+      }
+    ),
+    error ? /* @__PURE__ */ jsx2("p", { id: inputId ? `${inputId}-error` : void 0, role: "alert", children: error }) : null
+  ] });
+}
+export {
+  Form,
+  TextField
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/Form.tsx","../src/TextField.tsx"],"sourcesContent":["import type { FormHTMLAttributes, ReactNode } from \"react\";\n\nexport type FormProps = FormHTMLAttributes<HTMLFormElement> & {\n  children: ReactNode;\n};\n\nexport function Form({ children, ...props }: FormProps) {\n  return <form {...props}>{children}</form>;\n}\n","import type { InputHTMLAttributes } from \"react\";\n\nexport type TextFieldProps = InputHTMLAttributes<HTMLInputElement> & {\n  label: string;\n  error?: string;\n};\n\nexport function TextField({\n  label,\n  error,\n  id,\n  name,\n  ...props\n}: TextFieldProps) {\n  const inputId = id ?? name;\n\n  return (\n    <div>\n      <label htmlFor={inputId}>{label}</label>\n      <input\n        id={inputId}\n        name={name}\n        {...props}\n        aria-invalid={error ? \"true\" : undefined}\n        aria-describedby={error && inputId ? `${inputId}-error` : undefined}\n      />\n      {error ? (\n        <p id={inputId ? `${inputId}-error` : undefined} role=\"alert\">\n          {error}\n        </p>\n      ) : null}\n    </div>\n  );\n}\n"],"mappings":";AAOS;AADF,SAAS,KAAK,EAAE,UAAU,GAAG,MAAM,GAAc;AACtD,SAAO,oBAAC,UAAM,GAAG,OAAQ,UAAS;AACpC;;;ACSI,SACE,OAAAA,MADF;AAVG,SAAS,UAAU;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAAmB;AACjB,QAAM,UAAU,MAAM;AAEtB,SACE,qBAAC,SACC;AAAA,oBAAAA,KAAC,WAAM,SAAS,SAAU,iBAAM;AAAA,IAChC,gBAAAA;AAAA,MAAC;AAAA;AAAA,QACC,IAAI;AAAA,QACJ;AAAA,QACC,GAAG;AAAA,QACJ,gBAAc,QAAQ,SAAS;AAAA,QAC/B,oBAAkB,SAAS,UAAU,GAAG,OAAO,WAAW;AAAA;AAAA,IAC5D;AAAA,IACC,QACC,gBAAAA,KAAC,OAAE,IAAI,UAAU,GAAG,OAAO,WAAW,QAAW,MAAK,SACnD,iBACH,IACE;AAAA,KACN;AAEJ;","names":["jsx"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@usgb/forms",
+  "version": "0.1.0",
+  "description": "Sample React form components published to npm with OIDC trusted publishing.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "jsdom": "^26.1.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usgb/forms.git"
+  },
+  "keywords": [
+    "react",
+    "forms",
+    "oidc",
+    "trusted-publishing"
+  ]
+}