astro-lyra 0.0.0

package/README.md

@@ -0,0 +1,40 @@
+# Lyra
+
+> Astro-native forms: one Zod schema for client + server, View Transitions safe, and post-submit UX that doesn't fight you.
+
+`astro-lyra` is an Astro integration that handles the hard parts of forms in Astro so you don't have to:
+
+- **One schema, both sides** — define your form with [Zod](https://zod.dev) once; validate on the client and the server with the same source of truth.
+- **View Transitions safe** — the client runtime re-initializes correctly across Astro navigations. No broken scripts, no lost state.
+- **Post-submit UX, solved** — inline success/error messages, no jarring scroll-to-top, optional redirect — with or without JavaScript (progressive enhancement).
+- **Bring your own handler** — submit to your own Astro Action or endpoint. No backend lock-in.
+- **Spam honeypot built in** — basic bot protection with zero external services.
+
+> Status: planning. Implementation is spec-driven — see [`openspec/`](./openspec) for the proposal, specs, design, and tasks.
+
+## Install (planned)
+
+```sh
+npx astro add astro-lyra
+```
+
+## Form schema contract
+
+Every form submission arrives as `FormData`, where every value is a string. Use
+`z.coerce.*` for any field that isn't a string so the value is converted to the
+right type during validation:
+
+```ts
+const schema = z.object({
+  email: z.string().email(),      // string — no coercion needed
+  age: z.coerce.number().min(18), // number — coerce the FormData string
+  subscribe: z.coerce.boolean(),  // boolean — coerce "true"/"on"
+});
+```
+
+A plain `z.number()` reports a validation error for that field (not a crash),
+pointing you back to `z.coerce.number()`.
+
+## License
+
+MIT

package/dist/components/Form.astro

@@ -0,0 +1,114 @@
+---
+import type { defineForm } from "../define-form.js";
+import { HONEY_FIELD } from "../shared/constants.js";
+
+interface Props {
+  /** defineForm() result — supplies schema and descriptor for field rendering */
+  form: ReturnType<typeof defineForm>;
+  /** Native form action URL or Astro Action name */
+  action?: string;
+  /** HTTP method — always POST for mutation forms */
+  method?: "POST";
+  /** Set false to opt-out of JS enhancement (native POST only) */
+  enhance?: boolean;
+  /** Client-side redirect target on successful submission */
+  redirect?: string;
+  /** Field-level errors for SSR re-render without JS */
+  errors?: Record<string, string[]>;
+  /** Pre-populated field values for no-JS re-render after server validation */
+  values?: Record<string, string>;
+}
+
+const {
+  form: _form,
+  action,
+  method = "POST",
+  enhance = true,
+  redirect,
+  errors = {},
+  values = {},
+} = Astro.props;
+
+/**
+ * Map a descriptor field type to the appropriate HTML input type.
+ * email and other strings map to "text" — the descriptor only knows the
+ * JS type (string/number/boolean), not the semantic format.
+ */
+function mapInputType(descriptorType: string): string {
+  if (descriptorType === "number") return "number";
+  if (descriptorType === "boolean") return "checkbox";
+  return "text";
+}
+---
+
+<form
+  method={method}
+  action={action}
+  data-lyra-redirect={redirect || undefined}
+>
+  {/* Honeypot: off-screen, invisible to humans, reachable by bots that fill all fields.
+      NOT display:none — that hides it from bots too.
+      aria-hidden prevents screen readers from announcing it.
+      tabindex="-1" prevents keyboard focus. */}
+  <span
+    aria-hidden="true"
+    style="position:absolute;opacity:0;pointer-events:none;width:0;height:0;overflow:hidden"
+  >
+    <input
+      type="text"
+      name={HONEY_FIELD}
+      tabindex="-1"
+      autocomplete="off"
+    />
+  </span>
+
+  {/* Inline feedback region — client runtime writes success/error messages here.
+      role="status" + aria-live="polite" announces content changes to screen readers.
+      Left empty at SSR; field-level errors appear adjacent to each input below. */}
+  <div data-lyra-status role="status" aria-live="polite"></div>
+
+  {/* Descriptor-driven fields — rendered from form.descriptor.fields so that
+      aria-describedby can be wired at SSR time (impossible with slot-only approach).
+      Each field gets:
+        - a <label> linked to the input via for/id
+        - an <input> with the appropriate type and required attribute
+        - when errors[name] present: aria-describedby pointing to the error span
+        - when errors[name] present: a <span role="alert"> adjacent to the input */}
+  {_form.descriptor.fields.map((field) => {
+    const fieldErrors = errors[field.name];
+    const hasError = !!fieldErrors && fieldErrors.length > 0;
+    const inputId = `lyra-field-${field.name}`;
+    const errorId = `lyra-err-${field.name}`;
+    return (
+      <div>
+        <label for={inputId}>{field.name}</label>
+        <input
+          id={inputId}
+          name={field.name}
+          type={mapInputType(field.type)}
+          required={field.required || undefined}
+          aria-describedby={hasError ? errorId : undefined}
+          value={values[field.name] ?? undefined}
+        />
+        {hasError && (
+          <span id={errorId} role="alert">
+            {fieldErrors!.join(", ")}
+          </span>
+        )}
+      </div>
+    );
+  })}
+
+  {/* Custom content — submit button, extra inputs, or any user markup.
+      Rendered after the auto-generated fields so layout flows naturally. */}
+  <slot />
+</form>
+
+{
+  enhance && (
+    <script data-astro-rerun>
+      import { init } from "../runtime/enhance.js";
+      init();
+    </script>
+  )
+}

package/dist/integration.js

@@ -0,0 +1,13 @@
+// src/integration.ts
+function lyra(_opts) {
+  return {
+    name: "astro-lyra",
+    hooks: {
+      "astro:config:setup": (_params) => {
+      }
+    }
+  };
+}
+export {
+  lyra as default
+};

package/dist/server/index.js

@@ -0,0 +1,37 @@
+// src/server/index.ts
+import "zod";
+
+// src/shared/constants.ts
+var HONEY_FIELD = "_honey";
+
+// src/server/index.ts
+function validateForm(data, form, opts) {
+  if (opts?.honeypot !== false) {
+    const honeyValue = data.get(HONEY_FIELD);
+    if (honeyValue !== null && honeyValue !== "") {
+      return { ok: false, spam: true };
+    }
+  }
+  const formData = {};
+  data.forEach((value, key) => {
+    if (key !== HONEY_FIELD && typeof value === "string") {
+      formData[key] = value;
+    }
+  });
+  const parsed = form.schema.safeParse(Object.fromEntries(data));
+  if (parsed.success) {
+    return { ok: true, data: parsed.data };
+  }
+  const fieldErrors = {};
+  for (const issue of parsed.error.issues) {
+    const fieldName = issue.path.length > 0 ? String(issue.path[0]) : "_form";
+    if (!fieldErrors[fieldName]) {
+      fieldErrors[fieldName] = [];
+    }
+    fieldErrors[fieldName].push(issue.message);
+  }
+  return { ok: false, fieldErrors, formData };
+}
+export {
+  validateForm
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "astro-lyra",
+  "version": "0.0.0",
+  "description": "Astro-native form integration: Zod-typed validation, View Transitions safe, and post-submit UX done right.",
+  "type": "module",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "astro-component",
+    "forms",
+    "zod",
+    "validation",
+    "view-transitions"
+  ],
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/integration.js",
+    "./Form.astro": "./dist/components/Form.astro",
+    "./server": "./dist/server/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "astro": "^4.0.0 || ^5.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@astrojs/compiler": "2.13.1",
+    "@playwright/test": "^1.48.0",
+    "@types/jsdom": "^28.0.3",
+    "@types/node": "^25.9.3",
+    "astro": "^5.0.0",
+    "esbuild": "0.27.7",
+    "jsdom": "^29.1.1",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0",
+    "zod": "^3.23.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "pnpm --filter playground dev",
+    "test": "vitest run && vitest run --config vitest.component.config.ts",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "typecheck": "tsc --noEmit"
+  }
+}