@potentiajs/core 0.1.0-preview.0

package/examples/file-routing-basic/generate.js

@@ -0,0 +1,21 @@
+import { generateFileRoutes } from '@potentiajs/core/file-routing';
+
+export async function generate() {
+  const result = await generateFileRoutes({
+    rootDir: new URL('./routes', import.meta.url).pathname,
+    outputFile: new URL('./.potentia/routes.generated.js', import.meta.url).pathname
+  });
+
+  if (!result.ok) {
+    const details = result.errors.map((error) => `${error.code}: ${error.message}`).join('\n');
+    throw new Error(`File route generation failed:\n${details}`);
+  }
+
+  return result;
+}
+
+if (import.meta.main) {
+  const result = await generate();
+  console.log(`generated ${result.routes} route files and ${result.scopes} route scopes`);
+  console.log(result.outputFile);
+}

package/examples/file-routing-basic/routes/health.js

@@ -0,0 +1,3 @@
+import { json, ok, route } from '@potentiajs/core';
+
+export default route('GET', '/health', () => ok(json({ ok: true })));

package/examples/file-routing-basic/routes/index.js

@@ -0,0 +1,3 @@
+import { ok, route, text } from '@potentiajs/core';
+
+export default route('GET', '/', () => ok(text('file routing home')));

package/examples/file-routing-basic/routes/users/[id].js

@@ -0,0 +1,6 @@
+import { json, ok, route } from '@potentiajs/core';
+
+export default route('GET', '/:id', (ctx) => ok(json({
+  id: ctx.params.id,
+  from: 'file-routing-basic'
+})));

package/examples/file-routing-basic/routes/users/_routes.js

@@ -0,0 +1,15 @@
+import { createRoutes } from '@potentiajs/core';
+
+export default createRoutes({
+  hooks: {
+    afterResponse: [(ctx, response) => {
+      response.headers.set('x-file-routing-scope', 'users');
+      response.headers.set('x-file-routing-path', ctx.path);
+      return response;
+    }]
+  },
+  meta: {
+    example: 'file-routing-basic',
+    scope: 'users'
+  }
+});

package/examples/form-rendering-basic/README.md

@@ -0,0 +1,43 @@
+# Form Rendering Basic Example
+
+This example demonstrates the experimental optional server-side HTML renderer.
+
+It combines:
+
+- `action(...)`
+- `projectForm(...)`
+- `createFormState(...)`
+- `renderForm(...)` from `@potentiajs/core/forms`
+
+The renderer returns a plain HTML string. It is escaped by default and does not add a frontend runtime, JSX, hydration, client SDK, OpenAPI generator, session/flash helper, or multipart/file handling.
+
+## What it shows
+
+- projecting an action input contract into form metadata
+- rendering projected fields as plain HTML
+- rendering explicit textarea, hidden, and select fields
+- preserving safe state values
+- omitting sensitive password values
+- rendering field errors
+- using `data-potentia-*` styling/testing hooks
+- adding baseline accessibility attributes such as `aria-describedby` and `aria-invalid`
+- escaping output by default
+
+Textarea and hidden inputs require explicit projection metadata (`field.input === 'textarea'` or `field.input === 'hidden'`, with object `field.input.type` tolerated). Options render as `<select>` from string options or `{ value, label }` objects. The renderer does not add classNames, raw HTML, JSX, a frontend runtime, or hydration.
+
+## Run locally
+
+```bash
+bun examples/form-rendering-basic/index.js
+```
+
+## Package import
+
+When installed from the package, import the renderer from the forms subpath:
+
+```js
+import { action, createFormState, projectForm } from '@potentiajs/core';
+import { renderForm } from '@potentiajs/core/forms';
+```
+
+`renderForm` is intentionally not exported from the package root.

package/examples/form-rendering-basic/index.js

@@ -0,0 +1,120 @@
+import { optional, sigil } from '@weipertda/sigiljs';
+
+import { action, createFormState, projectForm } from '../../src/index.js';
+import { renderForm } from '../../src/forms.js';
+
+const CreateUserInput = sigil({
+  name: String,
+  email: String,
+  password: optional(String)
+});
+
+export const createUserAction = action('users.create.rendered-form', () => ({ ok: true }), {
+  input: CreateUserInput,
+  meta: { description: 'Create a user from a rendered form' }
+});
+
+const baseProjection = projectForm(createUserAction);
+
+export const formProjection = {
+  ...baseProjection,
+  fields: baseProjection.fields.concat([
+    {
+      kind: 'field',
+      name: 'bio',
+      path: ['bio'],
+      field: 'bio',
+      label: 'Bio',
+      help: 'Plain text only.',
+      placeholder: 'Tell us about this user',
+      input: 'textarea',
+      required: false,
+      multiple: false,
+      sensitive: false,
+      options: null,
+      defaultValue: null,
+      contract: { kind: 'example', expected: 'string' },
+      meta: null
+    },
+    {
+      kind: 'field',
+      name: 'role',
+      path: ['role'],
+      field: 'role',
+      label: 'Role',
+      help: null,
+      placeholder: null,
+      input: { type: 'text' },
+      required: true,
+      multiple: false,
+      sensitive: false,
+      options: ['user', { value: 'admin', label: 'Admin' }],
+      defaultValue: 'user',
+      contract: { kind: 'example', expected: 'string' },
+      meta: null
+    },
+    {
+      kind: 'field',
+      name: 'csrf',
+      path: ['csrf'],
+      field: 'csrf',
+      label: 'CSRF token',
+      help: null,
+      placeholder: null,
+      input: 'hidden',
+      required: true,
+      multiple: false,
+      sensitive: false,
+      options: null,
+      defaultValue: 'example-token',
+      contract: { kind: 'example', expected: 'string' },
+      meta: null
+    }
+  ])
+};
+
+export const failedState = createFormState({
+  ok: false,
+  values: {
+    name: 'Ada Lovelace',
+    email: 'not-an-email',
+    password: 'secret-value-is-not-rendered',
+    bio: '<curious engineer>',
+    role: 'admin',
+    csrf: 'posted-token'
+  },
+  issues: [
+    {
+      code: 'invalid_email',
+      message: 'Email must be valid',
+      path: ['email'],
+      field: 'email',
+      boundary: 'input',
+      source: 'framework',
+      expected: 'email',
+      received: 'string',
+      meta: null
+    },
+    {
+      code: 'too_short',
+      message: 'Bio is too short',
+      path: ['bio'],
+      field: 'bio',
+      boundary: 'input',
+      source: 'framework',
+      expected: 'string',
+      received: 'string',
+      meta: null
+    }
+  ]
+});
+
+export const html = renderForm(formProjection, {
+  action: '/users',
+  state: failedState,
+  submitLabel: 'Create user'
+});
+
+if (import.meta.main) {
+  console.log(html);
+}

package/examples/full-flow-basic/README.md

@@ -0,0 +1,141 @@
+# Full Flow Basic Example
+
+This example shows Potentia as a compact contract-native app foundation.
+
+It demonstrates:
+
+```txt
+file routes
+→ generated routes
+→ app
+→ action/form contract metadata
+→ URL-encoded POST
+→ contract validation
+→ form projection
+→ server-rendered HTML
+→ form state after failure
+→ explicit redirect after success
+```
+
+No JSX, frontend runtime, browser hydration, client SDK, OpenAPI generator, database, auth, session/flash helper, or multipart/file upload helper is used.
+
+## Route tree
+
+```txt
+examples/full-flow-basic/
+  generate.js
+  app.js
+  form.js
+  routes/
+    index.js
+    users/
+      index.js
+      new.js
+      [id].js
+      _routes.js
+```
+
+Generated routes:
+
+```txt
+GET  /
+GET  /users/new
+POST /users
+GET  /users/:id
+```
+
+## Generate routes
+
+From the repository root:
+
+```bash
+bun examples/full-flow-basic/generate.js
+```
+
+The generated module is written to:
+
+```txt
+examples/full-flow-basic/.potentia/routes.generated.js
+```
+
+The generated output is inspectable JavaScript and is not scanned from the filesystem at request time. It should not be committed for this example.
+
+## Check generated routes
+
+The CLI can verify the generated file is current:
+
+```bash
+bun bin/potentia.js routes check \
+  --cwd examples/full-flow-basic \
+  --root routes \
+  --out .potentia/routes.generated.js \
+  --json
+```
+
+## Run the app locally
+
+After generation:
+
+```bash
+bun examples/full-flow-basic/app.js
+```
+
+Then open:
+
+```txt
+http://localhost:3000/users/new
+```
+
+## Form flow
+
+### GET form
+
+```txt
+GET /users/new
+→ projectForm(createUserAction)
+→ renderForm(...)
+→ HTML response
+```
+
+### POST validation failure
+
+```txt
+POST /users
+content-type: application/x-www-form-urlencoded
+
+name=&email=bad&password=secret
+```
+
+The example validates the parsed input with the SigilJS contract plus small example-level checks. It returns status `400`, renders field errors, preserves safe values, and omits the password value.
+
+Rendered forms include `data-potentia-*` styling/testing hooks and baseline accessibility attributes such as `aria-describedby` and `aria-invalid` when help text or errors are present.
+
+### POST domain failure
+
+```txt
+POST /users
+name=Ada&email=taken@example.com&password=secret
+```
+
+The example returns status `409` and renders a root form error from `createFormState(...)`.
+
+### POST success
+
+```txt
+POST /users
+name=Ada&email=ada@example.com&password=secret
+```
+
+The example redirects explicitly:
+
+```txt
+303 Location: /users/ada
+```
+
+## Ergonomic note
+
+Current action route execution validates `action.input` before the action handler runs. That is good for API-style failures, but same-route HTML form re-rendering after input-contract failure needs explicit handling today.
+
+This example keeps the framework unchanged: it uses `action(...)` + `projectForm(...)` for contract-native form metadata and performs the POST validation/render path explicitly in the route handler.
+
+A future design gate could improve action HTML failure rendering ergonomics.

package/examples/full-flow-basic/app.js

@@ -0,0 +1,16 @@
+import { createApp } from '@potentiajs/core';
+
+import routes from './.potentia/routes.generated.js';
+
+export const app = createApp({
+  routes: [routes]
+});
+
+if (import.meta.main) {
+  Bun.serve({
+    port: 3000,
+    fetch: app.fetch
+  });
+
+  console.log('Potentia full-flow example running at http://localhost:3000');
+}

package/examples/full-flow-basic/form.js

@@ -0,0 +1,205 @@
+import { sigil } from '@weipertda/sigiljs';
+
+import { action, createFormState, projectForm, redirect } from '@potentiajs/core';
+import { renderForm } from '@potentiajs/core/forms';
+
+export const takenEmails = new Set(['taken@example.com']);
+
+export const CreateUserInput = sigil({
+  name: String,
+  email: String,
+  password: String
+});
+
+export const createUserAction = action('users.create.full-flow', () => null, {
+  input: CreateUserInput,
+  meta: { description: 'Create a user account' }
+});
+
+export const createUserForm = projectForm(createUserAction);
+
+export function renderCreateUserPage(options = {}) {
+  const state = options.state || null;
+  const status = options.status || 200;
+  const formHtml = renderForm(createUserForm, {
+    action: '/users',
+    state: state,
+    submitLabel: 'Create account',
+    idPrefix: 'create-user'
+  });
+
+  return htmlResponse(`<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Create user · Potentia full flow</title>
+</head>
+<body>
+  <main>
+    <h1>Create a user account</h1>
+    <p>This page is rendered on the server from projected action metadata.</p>
+${indent(formHtml, 4)}
+  </main>
+</body>
+</html>`, status);
+}
+
+export async function handleCreateUser(request) {
+  const input = await parseUrlEncoded(request);
+  const validation = validateCreateUserInput(input);
+
+  if (!validation.ok) {
+    return renderCreateUserPage({
+      status: 400,
+      state: createFormState({
+        ok: false,
+        values: input,
+        issues: validation.issues,
+        error: {
+          code: 'POTENTIA_EXAMPLE_VALIDATION_FAILED',
+          message: 'Please fix the highlighted fields.'
+        }
+      })
+    });
+  }
+
+  if (takenEmails.has(input.email)) {
+    return renderCreateUserPage({
+      status: 409,
+      state: createFormState({
+        ok: false,
+        values: input,
+        error: {
+          code: 'USER_EMAIL_TAKEN',
+          message: 'Email is already in use.'
+        }
+      })
+    });
+  }
+
+  return redirect(`/users/${slugify(input.name)}`, 303);
+}
+
+export function renderUserPage(id) {
+  return htmlResponse(`<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>User ${escapeHtml(id)} · Potentia full flow</title>
+</head>
+<body>
+  <main>
+    <h1>User ${escapeHtml(id)}</h1>
+    <p>The account flow completed with an explicit 303 redirect.</p>
+    <p><a href="/users/new">Create another user</a></p>
+  </main>
+</body>
+</html>`);
+}
+
+export function renderHomePage() {
+  return htmlResponse(`<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Potentia full flow</title>
+</head>
+<body>
+  <main>
+    <h1>Potentia full-flow example</h1>
+    <p>File routes, actions, contracts, projected forms, rendered HTML, form state, and redirects.</p>
+    <p><a href="/users/new">Create a user account</a></p>
+  </main>
+</body>
+</html>`);
+}
+
+function validateCreateUserInput(input) {
+  const parsed = CreateUserInput.safeParse(input);
+  const issues = [];
+
+  if (!parsed.success && parsed.error) {
+    issues.push(toIssue(parsed.error));
+  }
+
+  if (!input.name) issues.push(issue('missing_required', 'Name is required.', ['name']));
+  if (!input.email) {
+    issues.push(issue('missing_required', 'Email is required.', ['email']));
+  } else if (!input.email.includes('@')) {
+    issues.push(issue('invalid_email', 'Email must include @.', ['email']));
+  }
+  if (!input.password) issues.push(issue('missing_required', 'Password is required.', ['password']));
+
+  return { ok: issues.length === 0, issues: dedupeIssues(issues) };
+}
+
+function toIssue(error) {
+  const path = Array.isArray(error.path) ? error.path : [];
+  return issue(error.code || 'invalid_value', error.message || 'Invalid value.', path);
+}
+
+function issue(code, message, path) {
+  return {
+    code: code,
+    message: message,
+    path: path,
+    field: path.length > 0 ? path.join('.') : null,
+    boundary: 'input',
+    source: 'framework',
+    expected: 'string',
+    received: 'string',
+    meta: null
+  };
+}
+
+function dedupeIssues(issues) {
+  const seen = new Set();
+  const result = [];
+  for (const item of issues) {
+    const key = `${item.field}:${item.code}:${item.message}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(item);
+  }
+  return result;
+}
+
+async function parseUrlEncoded(request) {
+  const text = await request.text();
+  const params = new URLSearchParams(text);
+  return {
+    name: params.get('name') || '',
+    email: params.get('email') || '',
+    password: params.get('password') || ''
+  };
+}
+
+function htmlResponse(html, status = 200) {
+  return new Response(html, {
+    status: status,
+    headers: { 'content-type': 'text/html; charset=utf-8' }
+  });
+}
+
+function slugify(value) {
+  const slug = String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'user';
+}
+
+function escapeHtml(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function indent(value, spaces) {
+  const padding = ' '.repeat(spaces);
+  return String(value).split('\n').map((line) => `${padding}${line}`).join('\n');
+}

package/examples/full-flow-basic/generate.js

@@ -0,0 +1,21 @@
+import { generateFileRoutes } from '@potentiajs/core/file-routing';
+
+export async function generate() {
+  const result = await generateFileRoutes({
+    rootDir: new URL('./routes', import.meta.url).pathname,
+    outputFile: new URL('./.potentia/routes.generated.js', import.meta.url).pathname
+  });
+
+  if (!result.ok) {
+    const details = result.errors.map((error) => `${error.code}: ${error.message}`).join('\n');
+    throw new Error(`Full-flow route generation failed:\n${details}`);
+  }
+
+  return result;
+}
+
+if (import.meta.main) {
+  const result = await generate();
+  console.log(`generated ${result.routes} route files and ${result.scopes} route scopes`);
+  console.log(result.outputFile);
+}

package/examples/full-flow-basic/routes/index.js

@@ -0,0 +1,5 @@
+import { route } from '@potentiajs/core';
+
+import { renderHomePage } from '../form.js';
+
+export default route('GET', '/', () => renderHomePage());

package/examples/full-flow-basic/routes/users/[id].js

@@ -0,0 +1,5 @@
+import { route } from '@potentiajs/core';
+
+import { renderUserPage } from '../../form.js';
+
+export default route('GET', '/:id', (ctx) => renderUserPage(ctx.params.id));

package/examples/full-flow-basic/routes/users/_routes.js

@@ -0,0 +1,8 @@
+import { createRoutes } from '@potentiajs/core';
+
+export default createRoutes({
+  meta: {
+    example: 'full-flow-basic',
+    scope: 'users'
+  }
+});

package/examples/full-flow-basic/routes/users/index.js

@@ -0,0 +1,5 @@
+import { route } from '@potentiajs/core';
+
+import { handleCreateUser } from '../../form.js';
+
+export default route('POST', '/', (ctx) => handleCreateUser(ctx.request));

package/examples/full-flow-basic/routes/users/new.js

@@ -0,0 +1,5 @@
+import { route } from '@potentiajs/core';
+
+import { renderCreateUserPage } from '../../form.js';
+
+export default route('GET', '/new', () => renderCreateUserPage());