@conform-ed/contracts 0.0.8 → 0.0.9

package/src/h5p/v1/semantics.ts

@@ -0,0 +1,268 @@
+import { z } from "zod";
+
+// Conditional visibility rule for a field — renders/hides based on another field's value.
+const showWhenRuleSchema = z.object({
+  field: z.string(),
+  equals: z.union([z.string(), z.boolean(), z.number(), z.array(z.string())]),
+});
+
+const showWhenSchema = z.object({
+  type: z.enum(["and", "or"]).optional(),
+  rules: z.array(showWhenRuleSchema),
+});
+
+// Shared optional base properties present on all field types.
+const baseFieldShape = {
+  name: z.string().min(1),
+  label: z.string().optional(),
+  description: z.string().optional(),
+  importance: z.enum(["high", "medium", "low"]).optional(),
+  optional: z.boolean().optional(),
+  common: z.boolean().optional(),
+  default: z.unknown().optional(),
+  widget: z.string().optional(),
+  showWhen: showWhenSchema.optional(),
+  // When field is hidden by showWhen, reset value to null
+  nullWhenHidden: z.boolean().optional(),
+  // Override default copy/paste behaviour in editor
+  copy: z.boolean().optional(),
+};
+
+// TypeScript-side recursive types must be declared manually to avoid circular inference.
+export interface H5pFieldBase {
+  name: string;
+  label?: string;
+  description?: string;
+  importance?: "high" | "medium" | "low";
+  optional?: boolean;
+  common?: boolean;
+  default?: unknown;
+  widget?: string;
+  showWhen?: { type?: "and" | "or"; rules: Array<{ field: string; equals: unknown }> };
+  nullWhenHidden?: boolean;
+  copy?: boolean;
+}
+
+export interface H5pTextField extends H5pFieldBase {
+  type: "text";
+  maxLength?: number;
+  minLength?: number;
+  regexp?: { pattern: string; modifiers?: string; description?: string };
+  placeholder?: string;
+  enterMode?: string;
+  tags?: string[];
+  font?: unknown;
+}
+export interface H5pHtmlField extends H5pFieldBase {
+  type: "html";
+  tags?: string[];
+  maxLength?: number;
+  minLength?: number;
+  placeholder?: string;
+  font?: unknown;
+}
+export interface H5pNumberField extends H5pFieldBase {
+  type: "number";
+  min?: number;
+  max?: number;
+  steps?: number;
+  decimals?: number;
+}
+export interface H5pBooleanField extends H5pFieldBase {
+  type: "boolean";
+}
+export interface H5pImageField extends H5pFieldBase {
+  type: "image";
+  allowedMimeTypes?: string[];
+  disableCopyright?: boolean;
+}
+export interface H5pAudioField extends H5pFieldBase {
+  type: "audio";
+  allowedMimeTypes?: string[];
+  disableConversion?: boolean;
+}
+export interface H5pVideoField extends H5pFieldBase {
+  type: "video";
+  allowedMimeTypes?: string[];
+  disableConversion?: boolean;
+}
+export interface H5pFileField extends H5pFieldBase {
+  type: "file";
+  allowedMimeTypes?: string[];
+}
+export interface H5pSelectField extends H5pFieldBase {
+  type: "select";
+  options: Array<{ value: string; label: string }>;
+  multiple?: boolean;
+}
+export interface H5pLibraryField extends H5pFieldBase {
+  type: "library";
+  options?: string[];
+}
+export interface H5pGroupField extends H5pFieldBase {
+  type: "group";
+  fields: H5pSemanticsField[];
+  isSubContent?: boolean;
+  expanded?: boolean;
+}
+export interface H5pListField extends H5pFieldBase {
+  type: "list";
+  field: H5pSemanticsField;
+  min?: number;
+  max?: number;
+  entity?: string;
+  widgets?: Array<{ name: string; label?: string }>;
+}
+export interface H5pTableField extends H5pFieldBase {
+  type: "table";
+  columns: H5pSemanticsField[];
+  rows?: number;
+}
+
+export type H5pSemanticsField =
+  | H5pTextField
+  | H5pHtmlField
+  | H5pNumberField
+  | H5pBooleanField
+  | H5pImageField
+  | H5pAudioField
+  | H5pVideoField
+  | H5pFileField
+  | H5pSelectField
+  | H5pLibraryField
+  | H5pGroupField
+  | H5pListField
+  | H5pTableField;
+
+// --- Zod schemas ---
+
+// Leaf field schemas (no recursion)
+const textFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("text"),
+  maxLength: z.number().int().positive().optional(),
+  minLength: z.number().int().nonnegative().optional(),
+  regexp: z
+    .object({ pattern: z.string(), modifiers: z.string().optional(), description: z.string().optional() })
+    .optional(),
+  placeholder: z.string().optional(),
+  enterMode: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  font: z.unknown().optional(),
+});
+
+const htmlFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("html"),
+  tags: z.array(z.string()).optional(),
+  maxLength: z.number().int().positive().optional(),
+  minLength: z.number().int().nonnegative().optional(),
+  placeholder: z.string().optional(),
+  font: z.unknown().optional(),
+});
+
+const numberFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("number"),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  steps: z.number().positive().optional(),
+  decimals: z.number().int().nonnegative().optional(),
+});
+
+const booleanFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("boolean"),
+});
+
+const imageFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("image"),
+  allowedMimeTypes: z.array(z.string()).optional(),
+  disableCopyright: z.boolean().optional(),
+});
+
+const audioFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("audio"),
+  allowedMimeTypes: z.array(z.string()).optional(),
+  disableConversion: z.boolean().optional(),
+});
+
+const videoFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("video"),
+  allowedMimeTypes: z.array(z.string()).optional(),
+  disableConversion: z.boolean().optional(),
+});
+
+const fileFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("file"),
+  allowedMimeTypes: z.array(z.string()).optional(),
+});
+
+const selectFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("select"),
+  options: z.array(z.object({ value: z.string(), label: z.string() })),
+  multiple: z.boolean().optional(),
+});
+
+const libraryFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("library"),
+  options: z.array(z.string()).optional(),
+});
+
+// Recursive field schemas — use z.lazy so they can reference the outer union.
+// Using let-then-assign pattern (same as cmi5 Block/Au schemas).
+let h5pSemanticsFieldSchemaInternal: z.ZodType<H5pSemanticsField>;
+
+const groupFieldSchema: z.ZodType<H5pGroupField> = z.object({
+  ...baseFieldShape,
+  type: z.literal("group"),
+  fields: z.lazy(() => z.array(h5pSemanticsFieldSchemaInternal)),
+  isSubContent: z.boolean().optional(),
+  expanded: z.boolean().optional(),
+}) as z.ZodType<H5pGroupField>;
+
+const listFieldSchema: z.ZodType<H5pListField> = z.object({
+  ...baseFieldShape,
+  type: z.literal("list"),
+  field: z.lazy(() => h5pSemanticsFieldSchemaInternal),
+  min: z.number().int().nonnegative().optional(),
+  max: z.number().int().positive().optional(),
+  entity: z.string().optional(),
+  widgets: z.array(z.object({ name: z.string(), label: z.string().optional() })).optional(),
+}) as z.ZodType<H5pListField>;
+
+const tableFieldSchema: z.ZodType<H5pTableField> = z.object({
+  ...baseFieldShape,
+  type: z.literal("table"),
+  columns: z.lazy(() => z.array(h5pSemanticsFieldSchemaInternal)),
+  rows: z.number().int().positive().optional(),
+}) as z.ZodType<H5pTableField>;
+
+h5pSemanticsFieldSchemaInternal = z.union([
+  textFieldSchema,
+  htmlFieldSchema,
+  numberFieldSchema,
+  booleanFieldSchema,
+  imageFieldSchema,
+  audioFieldSchema,
+  videoFieldSchema,
+  fileFieldSchema,
+  selectFieldSchema,
+  libraryFieldSchema,
+  groupFieldSchema,
+  listFieldSchema,
+  tableFieldSchema,
+]) as z.ZodType<H5pSemanticsField>;
+
+// The schema for a single semantics field (any type).
+export const H5pSemanticsFieldSchema: z.ZodType<H5pSemanticsField> = h5pSemanticsFieldSchemaInternal;
+
+// The top-level semantics.json document — an array of field definitions.
+export const H5pSemanticsSchema = z.array(H5pSemanticsFieldSchema);
+export type H5pSemantics = z.infer<typeof H5pSemanticsSchema>;

package/src/h5p/v1/shared.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+
+export function strictObject<T extends z.ZodRawShape>(shape: T) {
+  return z.object(shape).strict();
+}
+
+// Machine name: alphanumeric, hyphens, dots — used in machineName fields and folder names.
+// Pattern from h5p-php-library H5PValidator::isValidRequiredH5pData
+export const H5pMachineNameSchema = z.string().regex(/^[\w0-9-.]{1,255}$/iu);
+
+// Library folder name without patch: "H5P.Image-1.1", "H5P.Column-1.22"
+// Patch version is intentionally excluded from folder names and dependency references per spec.
+export const H5pLibraryFolderNameSchema = z.string().regex(/^[\w0-9-.]{1,255}-\d{1,5}\.\d{1,5}$/u);
+
+// Version reference used in preloadedDependencies / dynamicDependencies / editorDependencies.
+// Patch is intentionally omitted — any patch of the specified major.minor is acceptable.
+export const H5pVersionRefSchema = strictObject({
+  machineName: H5pMachineNameSchema,
+  majorVersion: z.number().int().nonnegative().max(99999),
+  minorVersion: z.number().int().nonnegative().max(99999),
+});
+
+// Standard H5P license codes as used in h5p.json and library.json.
+// "U" = undisclosed/unknown (H5P default when no license is specified).
+export const H5pLicenseSchema = z.enum([
+  "CC BY",
+  "CC BY-SA",
+  "CC BY-NC",
+  "CC BY-NC-SA",
+  "CC BY-ND",
+  "CC BY-NC-ND",
+  "CC0",
+  "GNU GPL",
+  "PD",
+  "ODC PDDL",
+  "CC PDM",
+  "U",
+]);
+
+export const H5pAuthorSchema = strictObject({
+  name: z.string().min(1),
+  role: z.string().optional(),
+});
+
+export const H5pChangelogEntrySchema = strictObject({
+  date: z.string(),
+  changes: z.array(z.string()),
+});
+
+// Inferred types
+export type H5pMachineName = z.infer<typeof H5pMachineNameSchema>;
+export type H5pLibraryFolderName = z.infer<typeof H5pLibraryFolderNameSchema>;
+export type H5pVersionRef = z.infer<typeof H5pVersionRefSchema>;
+export type H5pLicense = z.infer<typeof H5pLicenseSchema>;
+export type H5pAuthor = z.infer<typeof H5pAuthorSchema>;
+export type H5pChangelogEntry = z.infer<typeof H5pChangelogEntrySchema>;

package/src/index.ts

@@ -30,3 +30,5 @@ export * as ClrV2_0 from "./clr/v2_0";
 export * as OpenBadgesV3_0 from "./open-badges/v3_0";
 export * as OneRosterV1_2 from "./oneroster/v1_2";
 export * as VcDataModelV2_0 from "./vc-data-model/v2_0";
+export * as H5pV1 from "./h5p/v1";
+export { H5pV1DerivedZodTemplates } from "./h5p/v1";

package/test/h5p-v1.test.ts

@@ -0,0 +1,330 @@
+import { expect, test } from "bun:test";
+import { H5pV1 } from "@conform-ed/contracts";
+
+// --- PackageManifest (h5p.json) ---
+
+test("H5P PackageManifest accepts a minimal valid h5p.json", () => {
+  const result = H5pV1.Schemas.PackageManifest.safeParse({
+    title: "My H5P Content",
+    language: "en",
+    machineName: "H5P.CoursePresentation",
+    mainLibrary: "H5P.CoursePresentation",
+    preloadedDependencies: [{ machineName: "H5P.CoursePresentation", majorVersion: 1, minorVersion: 27 }],
+    embedTypes: ["iframe"],
+  });
+  expect(result.success).toBe(true);
+});
+
+test("H5P PackageManifest accepts all optional fields", () => {
+  const result = H5pV1.Schemas.PackageManifest.safeParse({
+    title: "Interactive Video",
+    language: "en-US",
+    machineName: "H5P.InteractiveVideo",
+    mainLibrary: "H5P.InteractiveVideo",
+    preloadedDependencies: [
+      { machineName: "H5P.InteractiveVideo", majorVersion: 1, minorVersion: 28 },
+      { machineName: "H5P.Video", majorVersion: 1, minorVersion: 6 },
+    ],
+    embedTypes: ["iframe", "div"],
+    contentType: "Interactive Video",
+    description: "An interactive video content type",
+    author: "H5P Community",
+    authors: [{ name: "Jane Doe", role: "Author" }],
+    license: "CC BY",
+    licenseVersion: "4.0",
+    licenseExtras: "Attribution required",
+    yearFrom: 2020,
+    yearTo: 2024,
+    defaultLanguage: "en",
+    a11yTitle: "Interactive Video",
+    changes: [{ date: "01-01-24 00:00:00", changes: ["Initial release"] }],
+  });
+  expect(result.success).toBe(true);
+});
+
+test("H5P PackageManifest rejects missing required title", () => {
+  const result = H5pV1.Schemas.PackageManifest.safeParse({
+    language: "en",
+    machineName: "H5P.Image",
+    mainLibrary: "H5P.Image",
+    preloadedDependencies: [{ machineName: "H5P.Image", majorVersion: 1, minorVersion: 1 }],
+    embedTypes: ["div"],
+  });
+  expect(result.success).toBe(false);
+});
+
+test("H5P PackageManifest rejects invalid machine name", () => {
+  const result = H5pV1.Schemas.PackageManifest.safeParse({
+    title: "Test",
+    language: "en",
+    machineName: "invalid machine name!",
+    mainLibrary: "H5P.Image",
+    preloadedDependencies: [{ machineName: "H5P.Image", majorVersion: 1, minorVersion: 1 }],
+    embedTypes: ["div"],
+  });
+  expect(result.success).toBe(false);
+});
+
+test("H5P PackageManifest rejects invalid embed type", () => {
+  const result = H5pV1.Schemas.PackageManifest.safeParse({
+    title: "Test",
+    language: "en",
+    machineName: "H5P.Image",
+    mainLibrary: "H5P.Image",
+    preloadedDependencies: [{ machineName: "H5P.Image", majorVersion: 1, minorVersion: 1 }],
+    embedTypes: ["flash"],
+  });
+  expect(result.success).toBe(false);
+});
+
+test("H5P PackageManifest rejects yearTo < yearFrom", () => {
+  const result = H5pV1.Schemas.PackageManifest.safeParse({
+    title: "Test",
+    language: "en",
+    machineName: "H5P.Image",
+    mainLibrary: "H5P.Image",
+    preloadedDependencies: [{ machineName: "H5P.Image", majorVersion: 1, minorVersion: 1 }],
+    embedTypes: ["div"],
+    yearFrom: 2024,
+    yearTo: 2020,
+  });
+  expect(result.success).toBe(false);
+});
+
+test("H5P PackageManifest rejects duplicate embed types", () => {
+  const result = H5pV1.Schemas.PackageManifest.safeParse({
+    title: "Test",
+    language: "en",
+    machineName: "H5P.Image",
+    mainLibrary: "H5P.Image",
+    preloadedDependencies: [{ machineName: "H5P.Image", majorVersion: 1, minorVersion: 1 }],
+    embedTypes: ["iframe", "iframe"],
+  });
+  expect(result.success).toBe(false);
+});
+
+// --- LibraryManifest (library.json) ---
+
+test("H5P LibraryManifest accepts a minimal valid library.json", () => {
+  const result = H5pV1.Schemas.LibraryManifest.safeParse({
+    title: "Image",
+    machineName: "H5P.Image",
+    majorVersion: 1,
+    minorVersion: 1,
+    patchVersion: 33,
+    runnable: 0,
+  });
+  expect(result.success).toBe(true);
+});
+
+test("H5P LibraryManifest accepts a runnable library with full fields", () => {
+  const result = H5pV1.Schemas.LibraryManifest.safeParse({
+    title: "True/False Question",
+    machineName: "H5P.TrueFalse",
+    majorVersion: 1,
+    minorVersion: 8,
+    patchVersion: 24,
+    runnable: 1,
+    description: "True/False question content type",
+    author: "H5P Community",
+    license: "MIT",
+    preloadedJs: [{ path: "h5p-true-false.js" }],
+    preloadedCss: [{ path: "h5p-true-false.css" }],
+    preloadedDependencies: [
+      { machineName: "H5P.Question", majorVersion: 1, minorVersion: 5 },
+      { machineName: "H5P.JoubelUI", majorVersion: 1, minorVersion: 3 },
+    ],
+    embedTypes: ["iframe"],
+    w: 640,
+    h: 480,
+    fullscreen: 0,
+    contentType: "Question",
+    coreApi: { majorVersion: 1, minorVersion: 28 },
+    metadataSettings: { disable: 0, disableExtraTitleField: 0 },
+  });
+  expect(result.success).toBe(true);
+});
+
+test("H5P LibraryManifest rejects invalid machineName", () => {
+  const result = H5pV1.Schemas.LibraryManifest.safeParse({
+    title: "Bad Library",
+    machineName: "bad name with spaces",
+    majorVersion: 1,
+    minorVersion: 0,
+    patchVersion: 0,
+    runnable: 0,
+  });
+  expect(result.success).toBe(false);
+});
+
+// --- Shared schemas ---
+
+test("H5P VersionRef rejects patch version (not part of the schema)", () => {
+  // The schema only allows machineName, majorVersion, minorVersion
+  const result = H5pV1.Shared.VersionRef.safeParse({
+    machineName: "H5P.Image",
+    majorVersion: 1,
+    minorVersion: 1,
+    patchVersion: 33,
+  });
+  // strictObject rejects extra fields
+  expect(result.success).toBe(false);
+});
+
+test("H5P LibraryFolderName validates correct folder name", () => {
+  expect(H5pV1.Shared.LibraryFolderName.safeParse("H5P.Image-1.1").success).toBe(true);
+  expect(H5pV1.Shared.LibraryFolderName.safeParse("H5P.Column-1.22").success).toBe(true);
+  expect(H5pV1.Shared.LibraryFolderName.safeParse("H5P.InteractiveVideo-1.28").success).toBe(true);
+});
+
+test("H5P LibraryFolderName rejects folder names with patch version", () => {
+  expect(H5pV1.Shared.LibraryFolderName.safeParse("H5P.Image-1.1.33").success).toBe(false);
+});
+
+// --- Semantics (semantics.json) ---
+
+test("H5P Semantics accepts a simple text field", () => {
+  const result = H5pV1.Schemas.SemanticsField.safeParse({
+    name: "question",
+    type: "text",
+    label: "Question",
+    importance: "high",
+    maxLength: 500,
+  });
+  expect(result.success).toBe(true);
+});
+
+test("H5P Semantics accepts a boolean field", () => {
+  const result = H5pV1.Schemas.SemanticsField.safeParse({
+    name: "enableRetry",
+    type: "boolean",
+    label: "Enable Retry",
+    default: true,
+    optional: true,
+  });
+  expect(result.success).toBe(true);
+});
+
+test("H5P Semantics accepts a select field with options", () => {
+  const result = H5pV1.Schemas.SemanticsField.safeParse({
+    name: "correct",
+    type: "select",
+    label: "Correct Answer",
+    options: [
+      { value: "true", label: "True" },
+      { value: "false", label: "False" },
+    ],
+  });
+  expect(result.success).toBe(true);
+});
+
+test("H5P Semantics accepts a group with nested fields", () => {
+  const result = H5pV1.Schemas.SemanticsField.safeParse({
+    name: "behaviour",
+    type: "group",
+    label: "Behavioural settings",
+    expanded: true,
+    fields: [
+      { name: "enableRetry", type: "boolean", label: "Enable retry button" },
+      { name: "enableSolutionsButton", type: "boolean", label: "Enable solution button" },
+      { name: "autoCheck", type: "boolean", label: "Auto-check" },
+    ],
+  });
+  expect(result.success).toBe(true);
+});
+
+test("H5P Semantics accepts a list field containing a group", () => {
+  const result = H5pV1.Schemas.SemanticsField.safeParse({
+    name: "alternatives",
+    type: "list",
+    label: "Answer Alternatives",
+    min: 2,
+    entity: "alternative",
+    field: {
+      name: "alternative",
+      type: "group",
+      fields: [
+        { name: "text", type: "html", label: "Text", importance: "high" },
+        { name: "correct", type: "boolean", label: "Correct" },
+      ],
+    },
+  });
+  expect(result.success).toBe(true);
+});
+
+test("H5P Semantics accepts deeply nested groups (3 levels)", () => {
+  const result = H5pV1.Schemas.Semantics.safeParse([
+    {
+      name: "outer",
+      type: "group",
+      fields: [
+        {
+          name: "middle",
+          type: "group",
+          fields: [{ name: "inner", type: "text", label: "Inner text" }],
+        },
+      ],
+    },
+  ]);
+  expect(result.success).toBe(true);
+});
+
+test("H5P Semantics accepts library field with options", () => {
+  const result = H5pV1.Schemas.SemanticsField.safeParse({
+    name: "content",
+    type: "library",
+    label: "Content",
+    options: ["H5P.Image 1.1", "H5P.Video 1.6", "H5P.Audio 1.5"],
+  });
+  expect(result.success).toBe(true);
+});
+
+test("H5P Semantics accepts an image field", () => {
+  const result = H5pV1.Schemas.SemanticsField.safeParse({
+    name: "file",
+    type: "image",
+    label: "Image",
+    importance: "high",
+    allowedMimeTypes: ["image/jpeg", "image/png", "image/gif", "image/svg+xml"],
+  });
+  expect(result.success).toBe(true);
+});
+
+test("H5P Semantics rejects unknown field type", () => {
+  const result = H5pV1.Schemas.SemanticsField.safeParse({
+    name: "bad",
+    type: "richtext",
+    label: "Bad Type",
+  });
+  expect(result.success).toBe(false);
+});
+
+test("H5P Semantics rejects field without name", () => {
+  const result = H5pV1.Schemas.SemanticsField.safeParse({
+    type: "text",
+    label: "No name",
+  });
+  expect(result.success).toBe(false);
+});
+
+// --- MediaFile (content.json sub-structure) ---
+
+test("H5P MediaFile accepts a valid image file reference", () => {
+  const result = H5pV1.Schemas.MediaFile.safeParse({
+    path: "images/my-photo.jpg",
+    mime: "image/jpeg",
+    copyright: { license: "CC BY", author: "John Doe", year: "2024" },
+    width: 1920,
+    height: 1080,
+  });
+  expect(result.success).toBe(true);
+});
+
+test("H5P LibraryEmbed accepts a valid embedded library reference", () => {
+  const result = H5pV1.Schemas.LibraryEmbed.safeParse({
+    library: "H5P.Image 1.1",
+    params: { file: { path: "images/img.jpg", mime: "image/jpeg" }, alt: "A photo" },
+    subContentId: "abc123",
+  });
+  expect(result.success).toBe(true);
+});