@gravitee/graphene-core 2.16.0 → 2.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravitee/graphene-core",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "type": "module",
   "description": "Gravitee's Graphene design system: accessible React components, design tokens, icons, and shared ESLint/TypeScript configs. Built on shadcn/ui and Tailwind.",
   "keywords": [

package/snippets/json-schema-form-simple.tsx

@@ -0,0 +1,53 @@
+// Snippet: Render a plugin JSON Schema in a single useForm
+//
+// Use when a host module receives a JSON Schema (from a Gravitee plugin or
+// API definition) and the form has **no fields besides those declared in the
+// schema**. One useForm, one resolver, one submit handler.
+// Do NOT use for hand-coded forms — write the fields directly with Graphene
+// primitives (Field, Input, Select…) instead.
+// Do NOT use when the form has host-owned meta fields (name, description,
+// etc.) alongside the schema — see snippets/json-schema-form-with-meta.tsx.
+//
+// Replace {PLACEHOLDERS} with your actual values.
+// See Storybook "Composed/JsonSchemaForm → Playground" for an interactive demo.
+
+import { useMemo } from 'react';
+import { useForm } from 'react-hook-form';
+import { Button, extractDefaults, JsonSchemaForm, jsonSchemaResolver } from '@gravitee/graphene-core';
+import type { JsonSchema } from '@gravitee/graphene-core';
+
+interface PluginConfigPageProps {
+  // Immutable: passing a new reference re-builds the form and recompiles ajv.
+  readonly pluginSchema: JsonSchema;
+
+  // Pass a stable reference (e.g. from a TanStack Query / SWR cache, or wrap with `useMemo`
+  // at the call site). A fresh object on every parent render defeats the `defaultValues`
+  // memo and re-seeds the form, wiping in-progress user edits.
+  readonly initialValue?: Record<string, unknown>;
+  readonly onSave: (data: Record<string, unknown>) => void;
+}
+
+export function PluginConfigPage({ pluginSchema, initialValue, onSave }: PluginConfigPageProps) {
+  // Memoize so `jsonSchemaResolver` does not recompile ajv on every parent render.
+  const resolver = useMemo(() => jsonSchemaResolver(pluginSchema), [pluginSchema]);
+  const defaultValues = useMemo(
+    () => initialValue ?? (extractDefaults(pluginSchema) as Record<string, unknown>) ?? {},
+    [pluginSchema, initialValue],
+  );
+
+  const form = useForm({
+    resolver,
+    defaultValues,
+    criteriaMode: 'all', // surface every failing ajv keyword per field (FieldError renders them as a list)
+    mode: 'onTouched', // validate on first blur, then on every change
+  });
+
+  // `noValidate` disables the browser's HTML5 validation popups so the resolver +
+  // <FieldError> remain the single source of validation messages.
+  return (
+    <form noValidate onSubmit={form.handleSubmit(onSave)} className="flex flex-1 flex-col gap-4 p-8">
+      <JsonSchemaForm schema={pluginSchema} control={form.control} name="" />
+      <Button type="submit">Save</Button>
+    </form>
+  );
+}

package/snippets/json-schema-form-with-meta.tsx

@@ -0,0 +1,97 @@
+// Snippet: Mix host-owned meta fields with a plugin JSON Schema
+//
+// Use when a host module renders a plugin config (immutable JSON Schema from
+// the backend) alongside host-owned meta fields (name, description, or any
+// extra logic validated by your favourite schema lib).
+// One useForm shared across both — `composeResolvers` merges Zod + ajv
+// errors so RHF surfaces them on the right inputs.
+// Do NOT use for the simple case (no meta) — see snippets/json-schema-form-simple.tsx.
+// Do NOT install Zod just for this — any RHF-compatible resolver works:
+// `yupResolver`, `joiResolver`, `valibotResolver`, or a hand-written
+// `Resolver<T>`. Only the first argument to `composeResolvers` changes.
+//
+// Replace {PLACEHOLDERS} with your actual values.
+// See Storybook "Composed/JsonSchemaForm → With external (hand-coded) fields".
+
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useMemo } from 'react';
+import { type Control, type Resolver, useForm } from 'react-hook-form';
+import { z } from 'zod';
+import type { JsonSchema } from '@gravitee/graphene-core';
+import {
+  Button,
+  composeResolvers,
+  extractDefaults,
+  Field,
+  FieldError,
+  FieldLabel,
+  Input,
+  JsonSchemaForm,
+  jsonSchemaResolver,
+} from '@gravitee/graphene-core';
+
+// Host-owned meta — extend with z.union / z.refine / async checks as needed.
+const metaSchema = z.object({
+  name: z.string().min(1, 'Name is required'),
+});
+
+type FormValues = z.infer<typeof metaSchema> & { config: Record<string, unknown> };
+
+interface PluginConfigPageProps {
+  readonly pluginSchema: JsonSchema;
+  readonly initialValue?: Partial<FormValues>;
+  readonly onSave: (data: FormValues) => void;
+}
+
+export function PluginConfigPage({ pluginSchema, initialValue, onSave }: PluginConfigPageProps) {
+  // `basePath: 'config'` must match the `name` prop on <JsonSchemaForm> below.
+  // Cast widens zodResolver to the composite values shape — each inner resolver reads
+  // only its own slice of `values` at runtime, so the cast is sound.
+  const resolver = useMemo(
+    () =>
+      composeResolvers<FormValues>(
+        zodResolver(metaSchema) as unknown as Resolver<FormValues>,
+        jsonSchemaResolver<FormValues>(pluginSchema, { basePath: 'config' }),
+      ),
+    [pluginSchema],
+  );
+
+  // Defaults: schema defaults seed `config`, then saved values override per key. Spread
+  // `initialValue` at the top level for meta; explicit merge on `config` so saved-but-partial
+  // configs do NOT wipe schema defaults for fields the user never touched (or that the schema
+  // added in a newer plugin version). For deeply nested schemas, swap `Object.assign` for a
+  // recursive merge (e.g. lodash.merge).
+  const schemaDefaults = useMemo(
+    () => (extractDefaults(pluginSchema) as Record<string, unknown>) ?? {},
+    [pluginSchema],
+  );
+
+  const form = useForm<FormValues>({
+    resolver,
+    mode: 'onTouched',
+    criteriaMode: 'all',
+    defaultValues: {
+      name: '',
+      ...initialValue,
+      config: { ...schemaDefaults, ...(initialValue?.config ?? {}) },
+    },
+  });
+  const { name: nameError } = form.formState.errors;
+
+  return (
+    <form noValidate onSubmit={form.handleSubmit(onSave)} className="flex flex-1 flex-col gap-4 p-8">
+      {/* Host meta — validated by Zod. Duplicate this block for `description`, etc. */}
+      <Field data-invalid={!!nameError}>
+        <FieldLabel htmlFor="name">Name</FieldLabel>
+        <Input id="name" {...form.register('name')} aria-invalid={!!nameError} />
+        {nameError && <FieldError errors={[nameError]} />}
+      </Field>
+
+      {/* Plugin sub-tree — fields registered under `values.config.*`. JsonSchemaForm is typed
+          against the generic RHF FieldValues; cast widens the narrow composite control. */}
+      <JsonSchemaForm schema={pluginSchema} control={form.control as unknown as Control} name="config" />
+
+      <Button type="submit">Save</Button>
+    </form>
+  );
+}

package/dist/composed/JsonSchemaForm/utils/ajv-messages.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ajv-messages.d.ts","sourceRoot":"","sources":["../../../../src/composed/JsonSchemaForm/utils/ajv-messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAyBvC,iBAAS,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG9D;AAOD,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/composed/JsonSchemaForm/utils/extractDefaults.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"extractDefaults.d.ts","sourceRoot":"","sources":["../../../../src/composed/JsonSchemaForm/utils/extractDefaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG9D,iBAAS,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAWpD;AA2BD,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/composed/JsonSchemaForm/utils/jsonSchemaResolver.d.ts

@@ -1,5 +0,0 @@
-import { Resolver } from 'react-hook-form';
-import { JsonSchema } from '../models/json-schema.types';
-declare function jsonSchemaResolver<TFieldValues extends Record<string, unknown> = Record<string, unknown>>(schema: JsonSchema): Resolver<TFieldValues>;
-export { jsonSchemaResolver };
-//# sourceMappingURL=jsonSchemaResolver.d.ts.map

package/dist/composed/JsonSchemaForm/utils/jsonSchemaResolver.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"jsonSchemaResolver.d.ts","sourceRoot":"","sources":["../../../../src/composed/JsonSchemaForm/utils/jsonSchemaResolver.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA2B,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAO9D,iBAAS,kBAAkB,CAAC,YAAY,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChG,MAAM,EAAE,UAAU,GACjB,QAAQ,CAAC,YAAY,CAAC,CA4BxB;AA6GD,OAAO,EAAE,kBAAkB,EAAE,CAAC"}