@hearthforge/forms

The descriptor-driven form and wizard engine of HearthForge. A form is data — a FormDescriptor (or a wizard of WizardStepDescriptors) of fields, groups, conditions and validation rules, the types @hearthforge/plugin-sdk defines — and this package renders it with @hearthforge/ui, owning the keyboard behaviour, zod validation, async and cross-field checks, conditional visibility, seeding and accessibility. Every form and wizard in the panel goes through it, and a game plugin describes its config form and creation wizard the same way, so neither ever hand-builds a form.

Install

pnpm add @hearthforge/forms @hearthforge/ui @hearthforge/plugin-sdk

Node >= 22.

Usage

import type { FormDescriptor } from "@hearthforge/plugin-sdk";
import { FormRenderer } from "@hearthforge/forms";

const descriptor: FormDescriptor = {
  fields: [
    { type: "text", key: "serverName", label: "my-game:config.serverName.label", required: true },
    { type: "number", key: "maxPlayers", label: "my-game:config.maxPlayers.label", min: 1, max: 200 },
  ],
  submitLabel: "my-game:config.save",
};

export function ServerSettings({ onSave }: { onSave: (values: Record<string, unknown>) => Promise<void> }) {
  return (
    <FormRenderer
      descriptor={descriptor}
      defaultValues={{ serverName: "", maxPlayers: 20 }}
      onSubmit={(values) => onSave(values)}
    />
  );
}

Labels are i18n keys, resolved through react-i18next; register the package's own catalog once under the forms namespace (import formsEn from "@hearthforge/forms/locales/en", then i18next.addResourceBundle("en", "forms", formsEn, true, true)). WizardRenderer, FormDialog and InlineEdit take descriptors the same way.

In a game plugin this package is provided by the panel through the host share scope (HOST_SHARED_MODULES in @hearthforge/plugin-sdk), exactly like @hearthforge/ui: declare it as a peer and never bundle it.

Peer dependencies

react and react-dom (^18 || ^19), @hearthforge/ui (the matching 0.x line), @hearthforge/plugin-sdk (^0.1.1 || ^0.2.0), zod (^4), i18next, react-i18next and lucide-react. The exact ranges are in package.json.

Versioning

Pre-1.0: a minor release may break the renderer's API; a patch never does. The descriptor format itself is versioned with @hearthforge/plugin-sdk. Maintenance lines publish from release/X.Y branches under the release-X.Y npm dist-tag and never move latest — see Maintenance releases.

License

Apache-2.0.

Links

• Repository: hearthforge/hearthforge-ui
• Descriptor types: @hearthforge/plugin-sdk
• Contributing: CLA.md (required for every contribution)
• HearthForge core: hearthforge/hearthforge