@nubitio/hydra 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -359,9 +359,17 @@ function extractEntrypointCollectionOperations(doc) {
 * Parse a raw `/api/docs.jsonld` Hydra JSON-LD response into a typed
 * Record<className, HydraResourceSchema>.
 *
+* @param entrypointHrefs - Optional map of entrypoint property name → real
+*   collection href, read from the API entrypoint document (`GET /api`).
+*   When provided it is the **authoritative** source for resource URLs;
+*   the dash-case + pluralize heuristic only fills the gaps. The heuristic
+*   cannot know the backend's path segment generator (underscores vs dashes)
+*   nor handle irregular plurals (Series, Settings, …), so always prefer
+*   passing the real hrefs.
+*
 * @throws Error if doc is not a valid Hydra ApiDocumentation.
 */
-function parseHydraDoc(doc) {
+function parseHydraDoc(doc, entrypointHrefs) {
 	const result = {};
 	const collectionOperationsMap = extractEntrypointCollectionOperations(doc);
 	const urlMap = {};
@@ -372,7 +380,8 @@ function parseHydraDoc(doc) {
 		const propId = sp.property?.["@id"];
 		if (range && propId) {
 			const className = range.replace("#", "");
-			urlMap[className] = deriveApiUrl(propId);
+			const propName = propId.split("/").pop() ?? "";
+			urlMap[className] = entrypointHrefs?.[propName] ?? deriveApiUrl(propId);
 		}
 	}
 	for (const cls of doc["supportedClass"]) {
@@ -391,7 +400,8 @@ function parseHydraDoc(doc) {
 				readable,
 				writeable,
 				"hydra:title": sp["title"] ?? sp["hydra:title"] ?? void 0,
-				crudHints: sp["x-crud"]
+				crudHints: sp["x-crud"],
+				enumOptions: Array.isArray(sp["enum"]) ? sp["enum"] : void 0
 			});
 		}
 		result[className] = {
@@ -424,7 +434,8 @@ function parseOpenApiDoc(doc) {
 				propertyType: "rdf:Property",
 				required: required.has(fieldName),
 				readable,
-				writeable
+				writeable,
+				enumOptions: Array.isArray(prop.enum) ? prop.enum : void 0
 			});
 		}
 		result[className] = {
@@ -495,6 +506,7 @@ function resolveRangeTag(range, propertyType) {
 * Only properties that are explicitly set (`!== undefined`) are applied.
 *
 * `hidden: true` sets `visible: false` so the column is hidden in the grid.
+* `visibleOnForm: false` excludes the field from the create/edit form only.
 * `order` maps to the `Field.order` property used by native grid column ordering.
 */
 function applyCrudHints(field, hints) {
@@ -502,6 +514,7 @@ function applyCrudHints(field, hints) {
 	if (hints.filterable !== void 0) field.filterable = hints.filterable;
 	if (hints.sortable !== void 0) field.sortable = hints.sortable;
 	if (hints.hidden !== void 0 && hints.hidden) field.visible = false;
+	if (hints.visibleOnForm !== void 0) field.visibleOnForm = hints.visibleOnForm;
 	if (hints.order !== void 0) field.order = hints.order;
 	if (hints.width !== void 0) field.width = hints.width;
 }
@@ -586,11 +599,11 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
 		}
 		if (!readable) continue;
 		const hydraTitle = fieldSchema["hydra:title"];
-		const label = hydraTitle && hydraTitle.trim() !== "" ? hydraTitle : toLabel(name);
+		const label = hydraTitle && hydraTitle.trim() !== "" && hydraTitle !== name ? hydraTitle : toLabel(name);
 		const filterable = filterableProperties.size === 0 ? true : filterableProperties.has(name);
 		if (!writeable) {
 			const field = {
-				...(0, _nubitio_crud.noneField)().name(name).label(label).required(required).build(),
+				...(fieldSchema.crudHints?.format === "currency" ? (0, _nubitio_crud.currencyField)().readonly(true) : (0, _nubitio_crud.noneField)()).name(name).label(label).required(required).build(),
 				filterable
 			};
 			applyCrudHints(field, fieldSchema.crudHints);
@@ -598,6 +611,19 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
 			continue;
 		}
 		const tag = resolveRangeTag(range, propertyType);
+		const enumOptions = fieldSchema.enumOptions;
+		if (enumOptions && enumOptions.length > 0 && (tag === "text" || tag === "integer" || tag === "decimal")) {
+			const field = {
+				...(0, _nubitio_crud.enumField)(enumOptions.map((value) => ({
+					value,
+					text: toLabel(String(value)).replace(/\b[a-z]/g, (c) => c.toUpperCase())
+				}))).name(name).label(label).required(required).build(),
+				filterable
+			};
+			applyCrudHints(field, fieldSchema.crudHints);
+			fields.push(field);
+			continue;
+		}
 		if (tag === "boolean") {
 			const field = {
 				...(0, _nubitio_crud.switchField)().name(name).label(label).required(required).build(),
@@ -627,7 +653,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
 		}
 		if (tag === "decimal") {
 			const field = {
-				...(0, _nubitio_crud.numberField)().name(name).label(label).required(required).build(),
+				...(fieldSchema.crudHints?.format === "currency" ? (0, _nubitio_crud.currencyField)() : (0, _nubitio_crud.numberField)()).name(name).label(label).required(required).build(),
 				filterable
 			};
 			applyCrudHints(field, fieldSchema.crudHints);
@@ -673,6 +699,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
 //#region packages/hydra/useHydraMetadata.ts
 const JSONLD_URL = "/api/docs.jsonld";
 const JSON_URL = "/api/docs.json";
+const ENTRYPOINT_URL = "/api";
 const isDev = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
 /**
 * Try to fetch and validate a Hydra JSON-LD doc.
@@ -694,6 +721,30 @@ async function fetchOpenApiDoc(httpClient, url) {
 	return json;
 }
 /**
+* Fetch the API entrypoint (`GET /api`) and extract its property → collection
+* href map: `{ "salesDocument": "/api/sales-documents", … }`.
+*
+* This is the canonical source for resource URLs — it reflects the backend's
+* actual route generator instead of guessing via dash-case + pluralize.
+* Returns `undefined` on any failure (auth-gated entrypoint, network error,
+* unexpected shape) so the caller can fall back to the heuristic; URL
+* discovery must never take the whole admin down.
+*/
+async function fetchEntrypointHrefs(httpClient) {
+	try {
+		const { data } = await httpClient.get(ENTRYPOINT_URL);
+		if (!data || typeof data !== "object") return void 0;
+		const hrefs = {};
+		for (const [key, value] of Object.entries(data)) {
+			if (key.startsWith("@")) continue;
+			if (typeof value === "string" && value.startsWith("/")) hrefs[key] = value;
+		}
+		return Object.keys(hrefs).length > 0 ? hrefs : void 0;
+	} catch {
+		return;
+	}
+}
+/**
 * Stable query key used by useHydraMetadata.
 * Export this so that consumers (e.g. SmartCrudPage retry button) can
 * invalidate exactly the right query without coupling to an internal string.
@@ -707,9 +758,11 @@ const API_DOC_QUERY_KEY = ["api-doc-discovery"];
 */
 async function fetchApiDoc(httpClient) {
 	try {
+		const [doc, entrypointHrefs] = await Promise.all([fetchHydraDoc(httpClient, JSONLD_URL), fetchEntrypointHrefs(httpClient)]);
 		return {
 			format: "hydra",
-			doc: await fetchHydraDoc(httpClient, JSONLD_URL)
+			doc,
+			entrypointHrefs
 		};
 	} catch {}
 	try {
@@ -813,15 +866,19 @@ function useResourceSchema(apiUrl) {
 			error,
 			supportedOperations: []
 		};
-		const resourceMap = data.format === "hydra" ? parseHydraDoc(data.doc) : parseOpenApiDoc(data.doc);
+		const resourceMap = data.format === "hydra" ? parseHydraDoc(data.doc, data.entrypointHrefs) : parseOpenApiDoc(data.doc);
 		const normalizedInput = normalizeUrl(apiUrl);
 		const resourceSchema = Object.values(resourceMap).find((r) => normalizeUrl(r.apiUrl) === normalizedInput);
-		if (!resourceSchema) return {
-			fields: [],
-			isLoading: false,
-			error: /* @__PURE__ */ new Error(`No schema found for ${apiUrl} in API doc`),
-			supportedOperations: []
-		};
+		if (!resourceSchema) {
+			const knownUrls = Object.values(resourceMap).map((r) => r.apiUrl).sort();
+			const slugMatch = knownUrls.find((url) => normalizeUrl(url).replace(/[-_]/g, "") === normalizedInput.replace(/[-_]/g, ""));
+			return {
+				fields: [],
+				isLoading: false,
+				error: /* @__PURE__ */ new Error(`No schema found for ${apiUrl} in API doc.` + (slugMatch ? ` Did you mean ${slugMatch}? If your backend generates underscore paths, configure API Platform's dash generator (path_segment_name_generator: api_platform.metadata.path_segment_name_generator.dash) or update the frontend resource path to match.` : "") + ` Known resource URLs: ${knownUrls.join(", ") || "(none)"}`),
+				supportedOperations: []
+			};
+		}
 		return {
 			fields: mapHydraSchemaToFields(resourceSchema, (className) => resourceMap[className]?.apiUrl, (className) => resourceMap[className]),
 			isLoading: false,

package/dist/index.d.cts

@@ -65,12 +65,16 @@ interface CrudHints {
   filterable?: boolean;
   /** Override whether the field can be sorted in the grid. */
   sortable?: boolean;
-  /** When true, the column is hidden from the grid by default. */
+  /** When true, the column is hidden from the grid by default (the form still shows the field). */
   hidden?: boolean;
+  /** When false, the field is excluded from the create/edit form (the grid still shows the column). */
+  visibleOnForm?: boolean;
   /** Column display order. */
   order?: number;
   /** Column width in pixels or as a CSS string. */
   width?: number;
+  /** Render hint for scalar fields. 'currency' maps decimals to a currency control. */
+  format?: 'currency';
 }
 interface HydraSupportedProperty {
   '@type': 'SupportedProperty';
@@ -99,6 +103,12 @@ interface HydraSupportedProperty {
    * `#[ApiProperty(openapiContext: ['x-crud' => [...]])]` on the PHP entity.
    */
   'x-crud'?: CrudHints;
+  /**
+   * Allowed values forwarded by `TranslatedDocumentationNormalizer` from
+   * `#[ApiProperty(openapiContext: ['enum' => [...]])]`. When present, the
+   * field mapper renders a select control instead of a free-text input.
+   */
+  enum?: Array<string | number>;
 }
 /**
  * A single entry from `supportedOperation` on a Hydra class.
@@ -170,6 +180,8 @@ interface HydraFieldSchema {
    * When present, these values override inferred field properties in the mapper.
    */
   crudHints?: CrudHints;
+  /** Allowed values (renders as a select). From `enum` on the supported property. */
+  enumOptions?: Array<string | number>;
 }
 /**
  * A single entry from a Hydra `hydra:search` / `hydra:mapping` block.
@@ -218,9 +230,18 @@ interface OpenApiDoc {
     schemas: Record<string, OpenApiSchema>;
   };
 }
+/**
+ * Map of entrypoint property name → real collection href, read from the API
+ * entrypoint document (`GET /api` → `{ "salesDocument": "/api/sales-documents", … }`).
+ * This is the canonical source for resource URLs: when present it overrides
+ * the dash-case + pluralize heuristic, which cannot know the backend's path
+ * generator or handle irregular plurals.
+ */
+type HydraEntrypointHrefs = Record<string, string>;
 type ApiDoc = {
   format: 'hydra';
   doc: HydraApiDoc;
+  entrypointHrefs?: HydraEntrypointHrefs;
 } | {
   format: 'openapi';
   doc: OpenApiDoc;
@@ -231,9 +252,17 @@ type ApiDoc = {
  * Parse a raw `/api/docs.jsonld` Hydra JSON-LD response into a typed
  * Record<className, HydraResourceSchema>.
  *
+ * @param entrypointHrefs - Optional map of entrypoint property name → real
+ *   collection href, read from the API entrypoint document (`GET /api`).
+ *   When provided it is the **authoritative** source for resource URLs;
+ *   the dash-case + pluralize heuristic only fills the gaps. The heuristic
+ *   cannot know the backend's path segment generator (underscores vs dashes)
+ *   nor handle irregular plurals (Series, Settings, …), so always prefer
+ *   passing the real hrefs.
+ *
  * @throws Error if doc is not a valid Hydra ApiDocumentation.
  */
-declare function parseHydraDoc(doc: HydraApiDoc): Record<string, HydraResourceSchema>;
+declare function parseHydraDoc(doc: HydraApiDoc, entrypointHrefs?: HydraEntrypointHrefs): Record<string, HydraResourceSchema>;
 /**
  * Parse a raw `/api/docs.json` OpenAPI 3.1 response into the same
  * Record<className, HydraResourceSchema> output shape so that

package/dist/index.d.mts

@@ -65,12 +65,16 @@ interface CrudHints {
   filterable?: boolean;
   /** Override whether the field can be sorted in the grid. */
   sortable?: boolean;
-  /** When true, the column is hidden from the grid by default. */
+  /** When true, the column is hidden from the grid by default (the form still shows the field). */
   hidden?: boolean;
+  /** When false, the field is excluded from the create/edit form (the grid still shows the column). */
+  visibleOnForm?: boolean;
   /** Column display order. */
   order?: number;
   /** Column width in pixels or as a CSS string. */
   width?: number;
+  /** Render hint for scalar fields. 'currency' maps decimals to a currency control. */
+  format?: 'currency';
 }
 interface HydraSupportedProperty {
   '@type': 'SupportedProperty';
@@ -99,6 +103,12 @@ interface HydraSupportedProperty {
    * `#[ApiProperty(openapiContext: ['x-crud' => [...]])]` on the PHP entity.
    */
   'x-crud'?: CrudHints;
+  /**
+   * Allowed values forwarded by `TranslatedDocumentationNormalizer` from
+   * `#[ApiProperty(openapiContext: ['enum' => [...]])]`. When present, the
+   * field mapper renders a select control instead of a free-text input.
+   */
+  enum?: Array<string | number>;
 }
 /**
  * A single entry from `supportedOperation` on a Hydra class.
@@ -170,6 +180,8 @@ interface HydraFieldSchema {
    * When present, these values override inferred field properties in the mapper.
    */
   crudHints?: CrudHints;
+  /** Allowed values (renders as a select). From `enum` on the supported property. */
+  enumOptions?: Array<string | number>;
 }
 /**
  * A single entry from a Hydra `hydra:search` / `hydra:mapping` block.
@@ -218,9 +230,18 @@ interface OpenApiDoc {
     schemas: Record<string, OpenApiSchema>;
   };
 }
+/**
+ * Map of entrypoint property name → real collection href, read from the API
+ * entrypoint document (`GET /api` → `{ "salesDocument": "/api/sales-documents", … }`).
+ * This is the canonical source for resource URLs: when present it overrides
+ * the dash-case + pluralize heuristic, which cannot know the backend's path
+ * generator or handle irregular plurals.
+ */
+type HydraEntrypointHrefs = Record<string, string>;
 type ApiDoc = {
   format: 'hydra';
   doc: HydraApiDoc;
+  entrypointHrefs?: HydraEntrypointHrefs;
 } | {
   format: 'openapi';
   doc: OpenApiDoc;
@@ -231,9 +252,17 @@ type ApiDoc = {
  * Parse a raw `/api/docs.jsonld` Hydra JSON-LD response into a typed
  * Record<className, HydraResourceSchema>.
  *
+ * @param entrypointHrefs - Optional map of entrypoint property name → real
+ *   collection href, read from the API entrypoint document (`GET /api`).
+ *   When provided it is the **authoritative** source for resource URLs;
+ *   the dash-case + pluralize heuristic only fills the gaps. The heuristic
+ *   cannot know the backend's path segment generator (underscores vs dashes)
+ *   nor handle irregular plurals (Series, Settings, …), so always prefer
+ *   passing the real hrefs.
+ *
  * @throws Error if doc is not a valid Hydra ApiDocumentation.
  */
-declare function parseHydraDoc(doc: HydraApiDoc): Record<string, HydraResourceSchema>;
+declare function parseHydraDoc(doc: HydraApiDoc, entrypointHrefs?: HydraEntrypointHrefs): Record<string, HydraResourceSchema>;
 /**
  * Parse a raw `/api/docs.json` OpenAPI 3.1 response into the same
  * Record<className, HydraResourceSchema> output shape so that

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { createCoreHttpClient, useCoreConfig, useCoreHttpClient } from "@nubitio/core";
 import { createContext, useContext, useMemo } from "react";
-import { ResourceSchemaProvider, ResourceStoreProvider, datetimeField, entityField, noneField, numberField, switchField, textField } from "@nubitio/crud";
+import { ResourceSchemaProvider, ResourceStoreProvider, currencyField, datetimeField, entityField, enumField, noneField, numberField, switchField, textField } from "@nubitio/crud";
 import { jsx } from "react/jsx-runtime";
 import { useQuery } from "@tanstack/react-query";
 //#region packages/hydra/HydraRemoteDataSource.ts
@@ -335,9 +335,17 @@ function extractEntrypointCollectionOperations(doc) {
 * Parse a raw `/api/docs.jsonld` Hydra JSON-LD response into a typed
 * Record<className, HydraResourceSchema>.
 *
+* @param entrypointHrefs - Optional map of entrypoint property name → real
+*   collection href, read from the API entrypoint document (`GET /api`).
+*   When provided it is the **authoritative** source for resource URLs;
+*   the dash-case + pluralize heuristic only fills the gaps. The heuristic
+*   cannot know the backend's path segment generator (underscores vs dashes)
+*   nor handle irregular plurals (Series, Settings, …), so always prefer
+*   passing the real hrefs.
+*
 * @throws Error if doc is not a valid Hydra ApiDocumentation.
 */
-function parseHydraDoc(doc) {
+function parseHydraDoc(doc, entrypointHrefs) {
 	const result = {};
 	const collectionOperationsMap = extractEntrypointCollectionOperations(doc);
 	const urlMap = {};
@@ -348,7 +356,8 @@ function parseHydraDoc(doc) {
 		const propId = sp.property?.["@id"];
 		if (range && propId) {
 			const className = range.replace("#", "");
-			urlMap[className] = deriveApiUrl(propId);
+			const propName = propId.split("/").pop() ?? "";
+			urlMap[className] = entrypointHrefs?.[propName] ?? deriveApiUrl(propId);
 		}
 	}
 	for (const cls of doc["supportedClass"]) {
@@ -367,7 +376,8 @@ function parseHydraDoc(doc) {
 				readable,
 				writeable,
 				"hydra:title": sp["title"] ?? sp["hydra:title"] ?? void 0,
-				crudHints: sp["x-crud"]
+				crudHints: sp["x-crud"],
+				enumOptions: Array.isArray(sp["enum"]) ? sp["enum"] : void 0
 			});
 		}
 		result[className] = {
@@ -400,7 +410,8 @@ function parseOpenApiDoc(doc) {
 				propertyType: "rdf:Property",
 				required: required.has(fieldName),
 				readable,
-				writeable
+				writeable,
+				enumOptions: Array.isArray(prop.enum) ? prop.enum : void 0
 			});
 		}
 		result[className] = {
@@ -471,6 +482,7 @@ function resolveRangeTag(range, propertyType) {
 * Only properties that are explicitly set (`!== undefined`) are applied.
 *
 * `hidden: true` sets `visible: false` so the column is hidden in the grid.
+* `visibleOnForm: false` excludes the field from the create/edit form only.
 * `order` maps to the `Field.order` property used by native grid column ordering.
 */
 function applyCrudHints(field, hints) {
@@ -478,6 +490,7 @@ function applyCrudHints(field, hints) {
 	if (hints.filterable !== void 0) field.filterable = hints.filterable;
 	if (hints.sortable !== void 0) field.sortable = hints.sortable;
 	if (hints.hidden !== void 0 && hints.hidden) field.visible = false;
+	if (hints.visibleOnForm !== void 0) field.visibleOnForm = hints.visibleOnForm;
 	if (hints.order !== void 0) field.order = hints.order;
 	if (hints.width !== void 0) field.width = hints.width;
 }
@@ -562,11 +575,11 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
 		}
 		if (!readable) continue;
 		const hydraTitle = fieldSchema["hydra:title"];
-		const label = hydraTitle && hydraTitle.trim() !== "" ? hydraTitle : toLabel(name);
+		const label = hydraTitle && hydraTitle.trim() !== "" && hydraTitle !== name ? hydraTitle : toLabel(name);
 		const filterable = filterableProperties.size === 0 ? true : filterableProperties.has(name);
 		if (!writeable) {
 			const field = {
-				...noneField().name(name).label(label).required(required).build(),
+				...(fieldSchema.crudHints?.format === "currency" ? currencyField().readonly(true) : noneField()).name(name).label(label).required(required).build(),
 				filterable
 			};
 			applyCrudHints(field, fieldSchema.crudHints);
@@ -574,6 +587,19 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
 			continue;
 		}
 		const tag = resolveRangeTag(range, propertyType);
+		const enumOptions = fieldSchema.enumOptions;
+		if (enumOptions && enumOptions.length > 0 && (tag === "text" || tag === "integer" || tag === "decimal")) {
+			const field = {
+				...enumField(enumOptions.map((value) => ({
+					value,
+					text: toLabel(String(value)).replace(/\b[a-z]/g, (c) => c.toUpperCase())
+				}))).name(name).label(label).required(required).build(),
+				filterable
+			};
+			applyCrudHints(field, fieldSchema.crudHints);
+			fields.push(field);
+			continue;
+		}
 		if (tag === "boolean") {
 			const field = {
 				...switchField().name(name).label(label).required(required).build(),
@@ -603,7 +629,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
 		}
 		if (tag === "decimal") {
 			const field = {
-				...numberField().name(name).label(label).required(required).build(),
+				...(fieldSchema.crudHints?.format === "currency" ? currencyField() : numberField()).name(name).label(label).required(required).build(),
 				filterable
 			};
 			applyCrudHints(field, fieldSchema.crudHints);
@@ -649,6 +675,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
 //#region packages/hydra/useHydraMetadata.ts
 const JSONLD_URL = "/api/docs.jsonld";
 const JSON_URL = "/api/docs.json";
+const ENTRYPOINT_URL = "/api";
 const isDev = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
 /**
 * Try to fetch and validate a Hydra JSON-LD doc.
@@ -670,6 +697,30 @@ async function fetchOpenApiDoc(httpClient, url) {
 	return json;
 }
 /**
+* Fetch the API entrypoint (`GET /api`) and extract its property → collection
+* href map: `{ "salesDocument": "/api/sales-documents", … }`.
+*
+* This is the canonical source for resource URLs — it reflects the backend's
+* actual route generator instead of guessing via dash-case + pluralize.
+* Returns `undefined` on any failure (auth-gated entrypoint, network error,
+* unexpected shape) so the caller can fall back to the heuristic; URL
+* discovery must never take the whole admin down.
+*/
+async function fetchEntrypointHrefs(httpClient) {
+	try {
+		const { data } = await httpClient.get(ENTRYPOINT_URL);
+		if (!data || typeof data !== "object") return void 0;
+		const hrefs = {};
+		for (const [key, value] of Object.entries(data)) {
+			if (key.startsWith("@")) continue;
+			if (typeof value === "string" && value.startsWith("/")) hrefs[key] = value;
+		}
+		return Object.keys(hrefs).length > 0 ? hrefs : void 0;
+	} catch {
+		return;
+	}
+}
+/**
 * Stable query key used by useHydraMetadata.
 * Export this so that consumers (e.g. SmartCrudPage retry button) can
 * invalidate exactly the right query without coupling to an internal string.
@@ -683,9 +734,11 @@ const API_DOC_QUERY_KEY = ["api-doc-discovery"];
 */
 async function fetchApiDoc(httpClient) {
 	try {
+		const [doc, entrypointHrefs] = await Promise.all([fetchHydraDoc(httpClient, JSONLD_URL), fetchEntrypointHrefs(httpClient)]);
 		return {
 			format: "hydra",
-			doc: await fetchHydraDoc(httpClient, JSONLD_URL)
+			doc,
+			entrypointHrefs
 		};
 	} catch {}
 	try {
@@ -789,15 +842,19 @@ function useResourceSchema(apiUrl) {
 			error,
 			supportedOperations: []
 		};
-		const resourceMap = data.format === "hydra" ? parseHydraDoc(data.doc) : parseOpenApiDoc(data.doc);
+		const resourceMap = data.format === "hydra" ? parseHydraDoc(data.doc, data.entrypointHrefs) : parseOpenApiDoc(data.doc);
 		const normalizedInput = normalizeUrl(apiUrl);
 		const resourceSchema = Object.values(resourceMap).find((r) => normalizeUrl(r.apiUrl) === normalizedInput);
-		if (!resourceSchema) return {
-			fields: [],
-			isLoading: false,
-			error: /* @__PURE__ */ new Error(`No schema found for ${apiUrl} in API doc`),
-			supportedOperations: []
-		};
+		if (!resourceSchema) {
+			const knownUrls = Object.values(resourceMap).map((r) => r.apiUrl).sort();
+			const slugMatch = knownUrls.find((url) => normalizeUrl(url).replace(/[-_]/g, "") === normalizedInput.replace(/[-_]/g, ""));
+			return {
+				fields: [],
+				isLoading: false,
+				error: /* @__PURE__ */ new Error(`No schema found for ${apiUrl} in API doc.` + (slugMatch ? ` Did you mean ${slugMatch}? If your backend generates underscore paths, configure API Platform's dash generator (path_segment_name_generator: api_platform.metadata.path_segment_name_generator.dash) or update the frontend resource path to match.` : "") + ` Known resource URLs: ${knownUrls.join(", ") || "(none)"}`),
+				supportedOperations: []
+			};
+		}
 		return {
 			fields: mapHydraSchemaToFields(resourceSchema, (className) => resourceMap[className]?.apiUrl, (className) => resourceMap[className]),
 			isLoading: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubitio/hydra",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Hydra / OpenAPI adapter for @nubitio/crud — automatic schema discovery and data source from API Platform docs.",
   "license": "MIT",
@@ -50,7 +50,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-i18next": "^14.0.0",
-    "@nubitio/crud": "^0.2.0",
-    "@nubitio/core": "^0.2.0"
+    "@nubitio/core": "^0.3.0",
+    "@nubitio/crud": "^0.3.0"
   }
 }