@nifrajs/web 1.0.0 → 1.1.0

package/dist/forms.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `@nifrajs/web/forms` — a typed form ↔ backend-schema binding. The three artifacts that must agree —
+ * a form's `<input name>`, the action's `formData.get`, and the typed-client payload — all key off the
+ * ONE route body schema, derived purely from `typeof backend`. A typo'd field name, or a field the
+ * schema doesn't have, becomes a COMPILE error instead of a silent runtime empty.
+ *
+ *   import type { backend } from "../backend"
+ *   import { formFor } from "@nifrajs/web/forms"
+ *
+ *   const f = formFor<typeof backend, "/todos">()   // method defaults to "post"
+ *   // In the component (any framework — spread the props onto an input):
+ *   <input {...f.field("text")} />                  // "text" ∈ the body's keys, else a compile error
+ *   // In the action:
+ *   const text = f.read(await request.formData(), "text")   // an orphan key won't compile
+ *   await api.todos.post({ text })                  // payload already typed by nifra
+ *
+ * Framework-agnostic + dependency-free: no codegen, no schema is bundled into the client, and the
+ * runtime is a trivial pass-through — all the work is in the types. It checks the field KEY, never the
+ * MEANING (a `field("email")` collecting a phone is still valid here); that stays an app/AI concern.
+ */
+import type { RouteInfo, Server } from "@nifrajs/core";
+type FormEntry = ReturnType<FormData["get"]>;
+type FormEntries = ReturnType<FormData["getAll"]>;
+/** The route registry baked into a server's type (`typeof app`). */
+type RegistryOf<App> = App extends Server<infer R, infer _Ctx> ? R : never;
+/** Every route path the app declares — constrains `Path`, so a wrong path is itself a type error. */
+export type RoutePaths<App> = keyof RegistryOf<App> & string;
+/** The body object type of `App`'s `Method Path` route (`never` when the route declares no body). */
+export type RouteBody<App, Path extends string, Method extends string> = Path extends keyof RegistryOf<App> ? Uppercase<Method> extends keyof RegistryOf<App>[Path] ? (RegistryOf<App>[Path][Uppercase<Method>] & RouteInfo)["body"] : never : never;
+/** The valid field names for that route's body — the schema's keys as a string union. */
+export type FieldKey<App, Path extends string, Method extends string> = [
+    RouteBody<App, Path, Method>
+] extends [never] ? never : keyof RouteBody<App, Path, Method> & string;
+/** Extra attributes merged into the returned input props (id, type, defaultValue, placeholder, …). */
+export type FieldProps = Record<string, unknown>;
+export interface FormHandle<App, Path extends string, Method extends string> {
+    /** Input props for a schema field. `name` is constrained to the body's keys — a typo, or a field the
+     * schema doesn't have, is a COMPILE error. Spread onto an element: `<input {...f.field("text")} />`. */
+    field<K extends FieldKey<App, Path, Method>>(name: K, props?: FieldProps): FieldProps & {
+        name: K;
+    };
+    /** `formData.get`, key-constrained to the body's fields — reading an orphan key won't compile. */
+    read<K extends FieldKey<App, Path, Method>>(form: FormData, name: K): FormEntry;
+    /** `formData.getAll`, key-checked the same way. */
+    readAll<K extends FieldKey<App, Path, Method>>(form: FormData, name: K): FormEntries;
+}
+/**
+ * Bind a form to a backend route's body schema at the type level. `App` is `typeof backend`; `Path` is
+ * constrained to the app's real routes (a wrong path is a type error); `Method` defaults to `"post"`.
+ */
+export declare function formFor<App, Path extends RoutePaths<App>, Method extends string = "post">(): FormHandle<App, Path, Method>;
+export {};
+//# sourceMappingURL=forms.d.ts.map

package/dist/forms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forms.d.ts","sourceRoot":"","sources":["../src/forms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAItD,KAAK,SAAS,GAAG,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAA;AAC5C,KAAK,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAA;AAEjD,oEAAoE;AACpE,KAAK,UAAU,CAAC,GAAG,IAAI,GAAG,SAAS,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AAE1E,qGAAqG;AACrG,MAAM,MAAM,UAAU,CAAC,GAAG,IAAI,MAAM,UAAU,CAAC,GAAG,CAAC,GAAG,MAAM,CAAA;AAE5D,qGAAqG;AACrG,MAAM,MAAM,SAAS,CACnB,GAAG,EACH,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,MAAM,IACnB,IAAI,SAAS,MAAM,UAAU,CAAC,GAAG,CAAC,GAClC,SAAS,CAAC,MAAM,CAAC,SAAS,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GACnD,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,MAAM,CAAC,GAC9D,KAAK,GACP,KAAK,CAAA;AAET,yFAAyF;AACzF,MAAM,MAAM,QAAQ,CAAC,GAAG,EAAE,IAAI,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM,IAAI;IACtE,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC;CAC7B,SAAS,CAAC,KAAK,CAAC,GACb,KAAK,GACL,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;AAE/C,sGAAsG;AACtG,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEhD,MAAM,WAAW,UAAU,CAAC,GAAG,EAAE,IAAI,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM;IACzE;4GACwG;IACxG,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EACzC,IAAI,EAAE,CAAC,EACP,KAAK,CAAC,EAAE,UAAU,GACjB,UAAU,GAAG;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAA;IAC3B,kGAAkG;IAClG,IAAI,CAAC,CAAC,SAAS,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,CAAA;IAC/E,mDAAmD;IACnD,OAAO,CAAC,CAAC,SAAS,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAA;CACrF;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACrB,GAAG,EACH,IAAI,SAAS,UAAU,CAAC,GAAG,CAAC,EAC5B,MAAM,SAAS,MAAM,GAAG,MAAM,KAC3B,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAUjC"}

package/dist/forms.js

@@ -0,0 +1,16 @@
+/**
+ * Bind a form to a backend route's body schema at the type level. `App` is `typeof backend`; `Path` is
+ * constrained to the app's real routes (a wrong path is a type error); `Method` defaults to `"post"`.
+ */
+export function formFor() {
+    const handle = {
+        field: (name, props) => ({
+            ...(props ?? {}),
+            name,
+        }),
+        read: (form, name) => form.get(name),
+        readAll: (form, name) => form.getAll(name),
+    };
+    return handle;
+}
+//# sourceMappingURL=forms.js.map

package/dist/forms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forms.js","sourceRoot":"","sources":["../src/forms.ts"],"names":[],"mappings":"AAmEA;;;GAGG;AACH,MAAM,UAAU,OAAO;IAKrB,MAAM,MAAM,GAAG;QACb,KAAK,EAAE,CAAC,IAAY,EAAE,KAAkB,EAAiC,EAAE,CAAC,CAAC;YAC3E,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;YAChB,IAAI;SACL,CAAC;QACF,IAAI,EAAE,CAAC,IAAc,EAAE,IAAY,EAAa,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;QACjE,OAAO,EAAE,CAAC,IAAc,EAAE,IAAY,EAAe,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;KAC1E,CAAA;IACD,OAAO,MAAkD,CAAA;AAC3D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/web",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Framework-agnostic SSR core for nifra — the render seam + HTML document orchestration.",
   "keywords": [
     "bun",
@@ -39,6 +39,11 @@
       "types": "./dist/client.d.ts",
       "default": "./dist/client.js"
     },
+    "./forms": {
+      "bun": "./src/forms.ts",
+      "types": "./dist/forms.d.ts",
+      "default": "./dist/forms.js"
+    },
     "./islands": {
       "bun": "./src/islands.ts",
       "types": "./dist/islands.d.ts",
@@ -102,7 +107,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/core": "1.0.0"
+    "@nifrajs/core": "1.1.0"
   },
   "peerDependencies": {
     "sass": "^1.0.0",
@@ -117,6 +122,7 @@
     }
   },
   "devDependencies": {
+    "@nifrajs/schema": "workspace:*",
     "sass": "^1.77.0",
     "vite": "^8.0.0"
   },

package/src/forms.ts

@@ -0,0 +1,86 @@
+/**
+ * `@nifrajs/web/forms` — a typed form ↔ backend-schema binding. The three artifacts that must agree —
+ * a form's `<input name>`, the action's `formData.get`, and the typed-client payload — all key off the
+ * ONE route body schema, derived purely from `typeof backend`. A typo'd field name, or a field the
+ * schema doesn't have, becomes a COMPILE error instead of a silent runtime empty.
+ *
+ *   import type { backend } from "../backend"
+ *   import { formFor } from "@nifrajs/web/forms"
+ *
+ *   const f = formFor<typeof backend, "/todos">()   // method defaults to "post"
+ *   // In the component (any framework — spread the props onto an input):
+ *   <input {...f.field("text")} />                  // "text" ∈ the body's keys, else a compile error
+ *   // In the action:
+ *   const text = f.read(await request.formData(), "text")   // an orphan key won't compile
+ *   await api.todos.post({ text })                  // payload already typed by nifra
+ *
+ * Framework-agnostic + dependency-free: no codegen, no schema is bundled into the client, and the
+ * runtime is a trivial pass-through — all the work is in the types. It checks the field KEY, never the
+ * MEANING (a `field("email")` collecting a phone is still valid here); that stays an app/AI concern.
+ */
+import type { RouteInfo, Server } from "@nifrajs/core"
+
+// Derived from `FormData` itself (not the `FormDataEntryValue` global) so this file stays DOM-lib-free:
+// `@nifrajs/web`'s server surface is typechecked by the root config, which has no DOM lib.
+type FormEntry = ReturnType<FormData["get"]>
+type FormEntries = ReturnType<FormData["getAll"]>
+
+/** The route registry baked into a server's type (`typeof app`). */
+type RegistryOf<App> = App extends Server<infer R, infer _Ctx> ? R : never
+
+/** Every route path the app declares — constrains `Path`, so a wrong path is itself a type error. */
+export type RoutePaths<App> = keyof RegistryOf<App> & string
+
+/** The body object type of `App`'s `Method Path` route (`never` when the route declares no body). */
+export type RouteBody<
+  App,
+  Path extends string,
+  Method extends string,
+> = Path extends keyof RegistryOf<App>
+  ? Uppercase<Method> extends keyof RegistryOf<App>[Path]
+    ? (RegistryOf<App>[Path][Uppercase<Method>] & RouteInfo)["body"]
+    : never
+  : never
+
+/** The valid field names for that route's body — the schema's keys as a string union. */
+export type FieldKey<App, Path extends string, Method extends string> = [
+  RouteBody<App, Path, Method>,
+] extends [never]
+  ? never
+  : keyof RouteBody<App, Path, Method> & string
+
+/** Extra attributes merged into the returned input props (id, type, defaultValue, placeholder, …). */
+export type FieldProps = Record<string, unknown>
+
+export interface FormHandle<App, Path extends string, Method extends string> {
+  /** Input props for a schema field. `name` is constrained to the body's keys — a typo, or a field the
+   * schema doesn't have, is a COMPILE error. Spread onto an element: `<input {...f.field("text")} />`. */
+  field<K extends FieldKey<App, Path, Method>>(
+    name: K,
+    props?: FieldProps,
+  ): FieldProps & { name: K }
+  /** `formData.get`, key-constrained to the body's fields — reading an orphan key won't compile. */
+  read<K extends FieldKey<App, Path, Method>>(form: FormData, name: K): FormEntry
+  /** `formData.getAll`, key-checked the same way. */
+  readAll<K extends FieldKey<App, Path, Method>>(form: FormData, name: K): FormEntries
+}
+
+/**
+ * Bind a form to a backend route's body schema at the type level. `App` is `typeof backend`; `Path` is
+ * constrained to the app's real routes (a wrong path is a type error); `Method` defaults to `"post"`.
+ */
+export function formFor<
+  App,
+  Path extends RoutePaths<App>,
+  Method extends string = "post",
+>(): FormHandle<App, Path, Method> {
+  const handle = {
+    field: (name: string, props?: FieldProps): FieldProps & { name: string } => ({
+      ...(props ?? {}),
+      name,
+    }),
+    read: (form: FormData, name: string): FormEntry => form.get(name),
+    readAll: (form: FormData, name: string): FormEntries => form.getAll(name),
+  }
+  return handle as unknown as FormHandle<App, Path, Method>
+}