@nubitio/hydra 0.5.30 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -458,6 +458,7 @@ function parseHydraDoc(doc, entrypointHrefs) {
458
458
  formLayout: cls["x-crud-layout"],
459
459
  workflow: cls["x-workflow"],
460
460
  sequence: cls["x-sequence"],
461
+ embeddedLines: cls["x-embedded-lines"],
461
462
  searchMappings: extractSearchMappings(cls),
462
463
  supportedOperations: Array.from(new Set([...collectionOperationsMap[className] ?? [], ...extractSupportedOperations(cls)]))
463
464
  };
@@ -497,6 +498,30 @@ function parseOpenApiDoc(doc) {
497
498
  return result;
498
499
  }
499
500
  //#endregion
501
+ //#region packages/hydra/crudHintDeprecations.ts
502
+ const warned = /* @__PURE__ */ new Set();
503
+ function isDev$1() {
504
+ return typeof window !== "undefined" && (window.location.hostname === "localhost" || window.location.hostname === "127.0.0.1" || window.location.hostname.endsWith(".localhost"));
505
+ }
506
+ /** Warn once per session when legacy x-crud keys are used. */
507
+ function warnDeprecatedCrudHints(hints, fieldName) {
508
+ if (!hints || !isDev$1()) return;
509
+ if (hints.hidden !== void 0 && hints.hideInGrid === void 0) {
510
+ const key = `hidden:${fieldName}`;
511
+ if (!warned.has(key)) {
512
+ warned.add(key);
513
+ console.warn(`[Nubit] x-crud.hidden on "${fieldName}" is deprecated — use hideInGrid instead.`);
514
+ }
515
+ }
516
+ if (hints.visibleOnForm !== void 0 && hints.showInForm === void 0) {
517
+ const key = `visibleOnForm:${fieldName}`;
518
+ if (!warned.has(key)) {
519
+ warned.add(key);
520
+ console.warn(`[Nubit] x-crud.visibleOnForm on "${fieldName}" is deprecated — use showInForm instead.`);
521
+ }
522
+ }
523
+ }
524
+ //#endregion
500
525
  //#region packages/hydra/HydraToFieldMapper.ts
501
526
  /**
502
527
  * Returns true when the given `range` string declares an XSD integer type.
@@ -559,14 +584,45 @@ function resolveRangeTag(range, propertyType) {
559
584
  * `visibleOnForm: false` excludes the field from the create/edit form only.
560
585
  * `order` maps to the `Field.order` property used by native grid column ordering.
561
586
  */
562
- function applyCrudHints(field, hints) {
563
- if (!hints) return;
564
- if (hints.filterable !== void 0) field.filterable = hints.filterable;
565
- if (hints.sortable !== void 0) field.sortable = hints.sortable;
566
- if (hints.hidden !== void 0 && hints.hidden) field.visible = false;
567
- if (hints.visibleOnForm !== void 0) field.visibleOnForm = hints.visibleOnForm;
568
- if (hints.order !== void 0) field.order = hints.order;
569
- if (hints.width !== void 0) field.width = hints.width;
587
+ function applyCrudHints(field, hints, fieldName) {
588
+ const applied = [];
589
+ if (!hints) return applied;
590
+ warnDeprecatedCrudHints(hints, fieldName ?? field.name);
591
+ if (hints.filterable !== void 0) {
592
+ field.filterable = hints.filterable;
593
+ applied.push(`filterable=${hints.filterable}`);
594
+ }
595
+ if (hints.sortable !== void 0) {
596
+ field.sortable = hints.sortable;
597
+ applied.push(`sortable=${hints.sortable}`);
598
+ }
599
+ if (hints.hideInGrid ?? hints.hidden) {
600
+ field.visible = false;
601
+ applied.push("hideInGrid");
602
+ }
603
+ const showInForm = hints.showInForm ?? hints.visibleOnForm;
604
+ if (showInForm !== void 0) {
605
+ field.visibleOnForm = showInForm;
606
+ applied.push(`showInForm=${showInForm}`);
607
+ }
608
+ if (hints.readonly !== void 0) {
609
+ field.readonly = hints.readonly;
610
+ applied.push(`readonly=${hints.readonly}`);
611
+ }
612
+ if (hints.order !== void 0) {
613
+ field.order = hints.order;
614
+ applied.push(`order=${hints.order}`);
615
+ }
616
+ if (hints.width !== void 0) {
617
+ field.width = hints.width;
618
+ applied.push(`width=${hints.width}`);
619
+ }
620
+ return applied;
621
+ }
622
+ function stampMappingReason(field, rule, hintSuffix) {
623
+ const parts = [rule];
624
+ if (hintSuffix && hintSuffix.length > 0) parts.push(`x-crud: ${hintSuffix.join(", ")}`);
625
+ field.mappingReason = parts.join(" → ");
570
626
  }
571
627
  /**
572
628
  * Apply `x-sequence` hints: the server-allocated field is read-only and
@@ -656,6 +712,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
656
712
  hideable: false,
657
713
  visibleOnForm: false
658
714
  };
715
+ stampMappingReason(idField, `rule-1 identity (${isIntegerRange(range) ? "numberField" : "textField"})`, applyCrudHints(idField, fieldSchema.crudHints));
659
716
  fields.push(idField);
660
717
  continue;
661
718
  }
@@ -668,7 +725,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
668
725
  ...(fieldSchema.crudHints?.format === "currency" ? (0, _nubitio_crud.currencyField)().readonly(true) : (0, _nubitio_crud.noneField)()).name(name).label(label).required(required).build(),
669
726
  filterable
670
727
  };
671
- applyCrudHints(field, fieldSchema.crudHints);
728
+ stampMappingReason(field, fieldSchema.crudHints?.format === "currency" ? "rule-3 display-only+currency" : "rule-3 display-only", applyCrudHints(field, fieldSchema.crudHints));
672
729
  fields.push(field);
673
730
  continue;
674
731
  }
@@ -682,7 +739,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
682
739
  }))).name(name).label(label).required(required).build(),
683
740
  filterable
684
741
  };
685
- applyCrudHints(field, fieldSchema.crudHints);
742
+ stampMappingReason(field, "rule-3.5 enum", applyCrudHints(field, fieldSchema.crudHints));
686
743
  fields.push(field);
687
744
  continue;
688
745
  }
@@ -694,7 +751,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
694
751
  filterable: false,
695
752
  sortable: false
696
753
  };
697
- applyCrudHints(field, fieldSchema.crudHints);
754
+ stampMappingReason(field, `rule-3.55 ${formatHint}`, applyCrudHints(field, fieldSchema.crudHints));
698
755
  fields.push(field);
699
756
  continue;
700
757
  }
@@ -703,7 +760,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
703
760
  ...(0, _nubitio_crud.currencyField)().name(name).label(label).required(required).build(),
704
761
  filterable
705
762
  };
706
- applyCrudHints(field, fieldSchema.crudHints);
763
+ stampMappingReason(field, "rule-3.6 currency", applyCrudHints(field, fieldSchema.crudHints));
707
764
  fields.push(field);
708
765
  continue;
709
766
  }
@@ -712,7 +769,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
712
769
  ...(0, _nubitio_crud.switchField)().name(name).label(label).required(required).build(),
713
770
  filterable
714
771
  };
715
- applyCrudHints(field, fieldSchema.crudHints);
772
+ stampMappingReason(field, "rule-4 boolean", applyCrudHints(field, fieldSchema.crudHints));
716
773
  fields.push(field);
717
774
  continue;
718
775
  }
@@ -721,7 +778,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
721
778
  ...(0, _nubitio_crud.datetimeField)().name(name).label(label).required(required).build(),
722
779
  filterable
723
780
  };
724
- applyCrudHints(field, fieldSchema.crudHints);
781
+ stampMappingReason(field, "rule-5 dateTime", applyCrudHints(field, fieldSchema.crudHints));
725
782
  fields.push(field);
726
783
  continue;
727
784
  }
@@ -730,7 +787,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
730
787
  ...(0, _nubitio_crud.numberField)().name(name).label(label).required(required).precision(0).build(),
731
788
  filterable
732
789
  };
733
- applyCrudHints(field, fieldSchema.crudHints);
790
+ stampMappingReason(field, "rule-6 integer", applyCrudHints(field, fieldSchema.crudHints));
734
791
  fields.push(field);
735
792
  continue;
736
793
  }
@@ -739,7 +796,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
739
796
  ...(0, _nubitio_crud.numberField)().name(name).label(label).required(required).build(),
740
797
  filterable
741
798
  };
742
- applyCrudHints(field, fieldSchema.crudHints);
799
+ stampMappingReason(field, "rule-7 decimal", applyCrudHints(field, fieldSchema.crudHints));
743
800
  fields.push(field);
744
801
  continue;
745
802
  }
@@ -752,7 +809,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
752
809
  ...(0, _nubitio_crud.entityField)(url, valueField, resolveEntityTextField(relatedSchema, valueField)).name(name).label(label).required(required).build(),
753
810
  filterable
754
811
  };
755
- applyCrudHints(field, fieldSchema.crudHints);
812
+ stampMappingReason(field, `rule-8 entity → ${url || "unknown-url"}`, applyCrudHints(field, fieldSchema.crudHints));
756
813
  fields.push(field);
757
814
  continue;
758
815
  }
@@ -760,7 +817,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
760
817
  ...(0, _nubitio_crud.textField)().name(name).label(label).required(required).build(),
761
818
  filterable
762
819
  };
763
- applyCrudHints(field, fieldSchema.crudHints);
820
+ stampMappingReason(field, `rule-9 text (range=${range ?? "none"})`, applyCrudHints(field, fieldSchema.crudHints));
764
821
  fields.push(field);
765
822
  }
766
823
  if (!hasIdField) {
@@ -774,6 +831,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
774
831
  hideable: false,
775
832
  visibleOnForm: false
776
833
  };
834
+ stampMappingReason(syntheticId, "rule-1b synthetic identity (no id in schema)");
777
835
  fields.unshift(syntheticId);
778
836
  }
779
837
  applySequenceHints(fields, schema);
@@ -830,7 +888,7 @@ async function fetchEntrypointHrefs(httpClient) {
830
888
  }
831
889
  /**
832
890
  * Stable query key used by useHydraMetadata.
833
- * Export this so that consumers (e.g. SmartCrudPage retry button) can
891
+ * Export this so that consumers (e.g. SchemaCrudPage retry button) can
834
892
  * invalidate exactly the right query without coupling to an internal string.
835
893
  */
836
894
  const API_DOC_QUERY_KEY = ["api-doc-discovery"];
@@ -879,13 +937,13 @@ function useHydraMetadata() {
879
937
  * SchemaContext — shared parsed schema, no per-page re-fetch.
880
938
  *
881
939
  * Provides a single shared `useHydraMetadata()` call at the provider level
882
- * so that multiple `SmartCrudPage` instances mounted simultaneously share
940
+ * so that multiple `SchemaCrudPage` instances mounted simultaneously share
883
941
  * one `/api/docs.jsonld` request instead of each issuing their own.
884
942
  *
885
943
  * ## Usage
886
944
  *
887
945
  * ```tsx
888
- * // In your app root (optional — SmartCrudPage still works without it):
946
+ * // In your app root (optional — SchemaCrudPage still works without it):
889
947
  * <SchemaProvider>
890
948
  * <App />
891
949
  * </SchemaProvider>
@@ -900,7 +958,7 @@ const OUTSIDE_PROVIDER = Symbol("OUTSIDE_PROVIDER");
900
958
  const SchemaContext = (0, react.createContext)(OUTSIDE_PROVIDER);
901
959
  /**
902
960
  * Wrap your app (or a subtree) with `SchemaProvider` to share a single
903
- * `/api/docs.jsonld` fetch across all `SmartCrudPage` instances.
961
+ * `/api/docs.jsonld` fetch across all `SchemaCrudPage` instances.
904
962
  */
905
963
  function SchemaProvider({ children }) {
906
964
  const metadata = useHydraMetadata();
@@ -913,7 +971,7 @@ function SchemaProvider({ children }) {
913
971
  * Returns the shared schema context if inside a `<SchemaProvider>`,
914
972
  * otherwise falls back to calling `useHydraMetadata()` directly.
915
973
  *
916
- * This makes `SmartCrudPage` work standalone without requiring a provider.
974
+ * This makes `SchemaCrudPage` work standalone without requiring a provider.
917
975
  */
918
976
  function useSchemaContext() {
919
977
  const ctx = (0, react.useContext)(SchemaContext);
@@ -937,13 +995,20 @@ function useSchemaContext() {
937
995
  * Normalizes an API URL by stripping any leading slash and query string so that
938
996
  * 'api/categories', '/api/categories', and '/api/categories?foo=bar' are treated as equal.
939
997
  */
940
- function normalizeUrl(url) {
998
+ function normalizeUrl$1(url) {
941
999
  const base = url.split("?")[0];
942
1000
  return base.startsWith("/") ? base.slice(1) : base;
943
1001
  }
944
- function useResourceSchema(apiUrl) {
1002
+ function useResourceSchema(apiUrl, options) {
1003
+ const enabled = options?.enabled !== false;
945
1004
  const { data, isLoading, error } = useSchemaContext();
946
1005
  return (0, react.useMemo)(() => {
1006
+ if (!enabled) return {
1007
+ fields: [],
1008
+ isLoading: false,
1009
+ error: void 0,
1010
+ supportedOperations: []
1011
+ };
947
1012
  if (!data) return {
948
1013
  fields: [],
949
1014
  isLoading,
@@ -951,11 +1016,11 @@ function useResourceSchema(apiUrl) {
951
1016
  supportedOperations: []
952
1017
  };
953
1018
  const resourceMap = data.format === "hydra" ? parseHydraDoc(data.doc, data.entrypointHrefs) : parseOpenApiDoc(data.doc);
954
- const normalizedInput = normalizeUrl(apiUrl);
955
- const resourceSchema = Object.values(resourceMap).find((r) => normalizeUrl(r.apiUrl) === normalizedInput);
1019
+ const normalizedInput = normalizeUrl$1(apiUrl);
1020
+ const resourceSchema = Object.values(resourceMap).find((r) => normalizeUrl$1(r.apiUrl) === normalizedInput);
956
1021
  if (!resourceSchema) {
957
1022
  const knownUrls = Object.values(resourceMap).map((r) => r.apiUrl).sort();
958
- const slugMatch = knownUrls.find((url) => normalizeUrl(url).replace(/[-_]/g, "") === normalizedInput.replace(/[-_]/g, ""));
1023
+ const slugMatch = knownUrls.find((url) => normalizeUrl$1(url).replace(/[-_]/g, "") === normalizedInput.replace(/[-_]/g, ""));
959
1024
  return {
960
1025
  fields: [],
961
1026
  isLoading: false,
@@ -971,10 +1036,12 @@ function useResourceSchema(apiUrl) {
971
1036
  formLayout: resourceSchema.formLayout,
972
1037
  workflow: resourceSchema.workflow,
973
1038
  sequence: resourceSchema.sequence,
974
- summaryFields: buildSummaryFieldsFromSchema(resourceSchema)
1039
+ summaryFields: buildSummaryFieldsFromSchema(resourceSchema),
1040
+ embeddedLines: resourceSchema.embeddedLines
975
1041
  };
976
1042
  }, [
977
1043
  data,
1044
+ enabled,
978
1045
  isLoading,
979
1046
  error,
980
1047
  apiUrl
@@ -982,8 +1049,8 @@ function useResourceSchema(apiUrl) {
982
1049
  }
983
1050
  //#endregion
984
1051
  //#region packages/hydra/HydraResourceSchemaProvider.tsx
985
- function useHydraResourceSchema({ apiUrl }) {
986
- return useResourceSchema(apiUrl);
1052
+ function useHydraResourceSchema({ apiUrl, enabled }) {
1053
+ return useResourceSchema(apiUrl, { enabled });
987
1054
  }
988
1055
  function HydraResourceSchemaProvider({ children }) {
989
1056
  return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_nubitio_crud.ResourceSchemaProvider, {
@@ -992,15 +1059,89 @@ function HydraResourceSchemaProvider({ children }) {
992
1059
  });
993
1060
  }
994
1061
  //#endregion
1062
+ //#region packages/hydra/buildEmbeddedFormDetail.ts
1063
+ /**
1064
+ * Builds a {@link ResourceFormDetail} from `x-embedded-lines` metadata and the
1065
+ * line entity schema in the API doc.
1066
+ */
1067
+ function buildEmbeddedFormDetail({ binding, lineSchema, resourceMap, overrides }) {
1068
+ const fields = lineSchema ? mapHydraSchemaToFields(lineSchema, (className) => resourceMap?.[className]?.apiUrl, (className) => resourceMap?.[className]).filter((field) => !field.isIdentity && field.name !== binding.parentQueryParam) : [];
1069
+ return {
1070
+ propertyName: binding.propertyName,
1071
+ url: (0, _nubitio_crud.embeddedLinesUrl)(binding.routePath, binding.parentQueryParam),
1072
+ allowAdding: true,
1073
+ allowDeleting: true,
1074
+ allowUpdating: true,
1075
+ fields,
1076
+ ...overrides
1077
+ };
1078
+ }
1079
+ function resolveEmbeddedBinding(schema, propertyName) {
1080
+ const bindings = schema.embeddedLines ?? [];
1081
+ if (bindings.length === 0) return void 0;
1082
+ if (!propertyName) return bindings[0];
1083
+ return bindings.find((b) => b.propertyName === propertyName) ?? bindings[0];
1084
+ }
1085
+ //#endregion
1086
+ //#region packages/hydra/resolveInferredFormDetail.ts
1087
+ function normalizeUrl(url) {
1088
+ const base = url.split("?")[0];
1089
+ return base.startsWith("/") ? base.slice(1) : base;
1090
+ }
1091
+ function shouldInferFormDetail(formDetail, embeddedLines) {
1092
+ if (!embeddedLines?.length) return false;
1093
+ if (formDetail?.inferFields === false) return false;
1094
+ if (formDetail?.fields && formDetail.fields.length > 0) return false;
1095
+ return true;
1096
+ }
1097
+ /**
1098
+ * Builds or augments `formDetail` from `x-embedded-lines` when the parent
1099
+ * resource publishes embedded line metadata.
1100
+ *
1101
+ * Inference runs automatically when `x-embedded-lines` is present unless:
1102
+ * - `formDetail.inferFields === false` (explicit opt-out), or
1103
+ * - `formDetail.fields` is a non-empty manual array.
1104
+ */
1105
+ function resolveInferredFormDetail(apiUrl, formDetail, schemaData, embeddedLines) {
1106
+ if (!shouldInferFormDetail(formDetail, embeddedLines) || !schemaData) return formDetail;
1107
+ const resourceMap = schemaData.format === "hydra" ? parseHydraDoc(schemaData.doc, schemaData.entrypointHrefs) : parseOpenApiDoc(schemaData.doc);
1108
+ const parentSchema = Object.values(resourceMap).find((schema) => normalizeUrl(schema.apiUrl) === normalizeUrl(apiUrl));
1109
+ const binding = resolveEmbeddedBinding({
1110
+ className: parentSchema?.className ?? "",
1111
+ apiUrl,
1112
+ fields: parentSchema?.fields ?? [],
1113
+ embeddedLines: parentSchema?.embeddedLines ?? embeddedLines
1114
+ }, formDetail?.propertyName);
1115
+ if (!binding) return formDetail;
1116
+ const lineSchema = resourceMap[binding.lineClass];
1117
+ const { inferFields: _infer, fields: _fields, ...overrides } = formDetail ?? {};
1118
+ const built = buildEmbeddedFormDetail({
1119
+ binding,
1120
+ lineSchema,
1121
+ resourceMap,
1122
+ overrides
1123
+ });
1124
+ return {
1125
+ ...built,
1126
+ ...formDetail,
1127
+ propertyName: built.propertyName,
1128
+ url: built.url,
1129
+ fields: built.fields
1130
+ };
1131
+ }
1132
+ //#endregion
995
1133
  exports.API_DOC_QUERY_KEY = API_DOC_QUERY_KEY;
996
1134
  exports.HydraRemoteDataSource = HydraRemoteDataSource;
997
1135
  exports.HydraResourceSchemaProvider = HydraResourceSchemaProvider;
998
1136
  exports.HydraResourceStoreProvider = HydraResourceStoreProvider;
999
1137
  exports.SchemaProvider = SchemaProvider;
1138
+ exports.buildEmbeddedFormDetail = buildEmbeddedFormDetail;
1000
1139
  exports.createHydraResourceStore = createHydraResourceStore;
1001
1140
  exports.mapHydraSchemaToFields = mapHydraSchemaToFields;
1002
1141
  exports.parseHydraDoc = parseHydraDoc;
1003
1142
  exports.parseOpenApiDoc = parseOpenApiDoc;
1143
+ exports.resolveEmbeddedBinding = resolveEmbeddedBinding;
1144
+ exports.resolveInferredFormDetail = resolveInferredFormDetail;
1004
1145
  exports.resolveRangeTag = resolveRangeTag;
1005
1146
  exports.useHydraMetadata = useHydraMetadata;
1006
1147
  exports.useResourceSchema = useResourceSchema;
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { DataRecord, GridData } from "@nubitio/core";
2
- import { DataRecord as DataRecord$1, Field, FormLayout, ResourceFilterDescriptor, ResourceFilterRule, ResourceLoadOptions, ResourceSchemaResolution, ResourceSortDescriptor, ResourceStore, ResourceStoreFactory, ResourceStoreOptions } from "@nubitio/crud";
2
+ import { DataRecord as DataRecord$1, Field, FormLayout, ResourceFilterDescriptor, ResourceFilterRule, ResourceFormDetail, ResourceLoadOptions, ResourceSchemaResolution, ResourceSortDescriptor, ResourceStore, ResourceStoreFactory, ResourceStoreOptions } from "@nubitio/crud";
3
3
  import React, { ReactNode } from "react";
4
4
 
5
5
  //#region packages/hydra/HydraRemoteDataSource.d.ts
@@ -60,10 +60,22 @@ interface CrudHints {
60
60
  filterable?: boolean;
61
61
  /** Override whether the field can be sorted in the grid. */
62
62
  sortable?: boolean;
63
- /** When true, the column is hidden from the grid by default (the form still shows the field). */
63
+ /**
64
+ * When true, the column is hidden from the grid (the form still shows the field).
65
+ * @deprecated Prefer `hideInGrid`.
66
+ */
64
67
  hidden?: boolean;
65
- /** When false, the field is excluded from the create/edit form (the grid still shows the column). */
68
+ /** When true, hide the column from the grid. Preferred over `hidden`. */
69
+ hideInGrid?: boolean;
70
+ /**
71
+ * When false, exclude from the create/edit form (the grid still shows the column).
72
+ * @deprecated Prefer `showInForm`.
73
+ */
66
74
  visibleOnForm?: boolean;
75
+ /** When false, exclude from the form. Preferred over `visibleOnForm`. */
76
+ showInForm?: boolean;
77
+ /** When true, render as read-only in the create/edit form. */
78
+ readonly?: boolean;
67
79
  /** Column display order. */
68
80
  order?: number;
69
81
  /** Column width in pixels or as a CSS string. */
@@ -144,6 +156,15 @@ interface SequenceSchema {
144
156
  padding?: number;
145
157
  scope?: string[];
146
158
  }
159
+ /** Master-detail line metadata from nubitio/admin-bundle EmbeddedLinesDocumentationNormalizer. */
160
+ interface EmbeddedLinesSchema {
161
+ propertyName: string;
162
+ lineClass: string;
163
+ lineEntityClass?: string;
164
+ routePath: string;
165
+ parentQueryParam: string;
166
+ reloadUrl: string;
167
+ }
147
168
  interface HydraClass {
148
169
  '@id': string;
149
170
  '@type': string;
@@ -159,6 +180,8 @@ interface HydraClass {
159
180
  * @nubitio/crud's FormLayout shape.
160
181
  */
161
182
  'x-crud-layout'?: FormLayout;
183
+ /** Embedded line collections declared on parent document resources. */
184
+ 'x-embedded-lines'?: EmbeddedLinesSchema[];
162
185
  /**
163
186
  * Hydra search template describing server-side filterable query params.
164
187
  * Present on collection operations in API Platform JSON-LD responses.
@@ -249,6 +272,8 @@ interface HydraResourceSchema {
249
272
  workflow?: WorkflowSchema;
250
273
  /** Server-allocated sequence field (nubitio/sequence-bundle). */
251
274
  sequence?: SequenceSchema;
275
+ /** Embedded line collections (nubitio/admin-bundle). */
276
+ embeddedLines?: EmbeddedLinesSchema[];
252
277
  }
253
278
  interface OpenApiProperty {
254
279
  type?: string;
@@ -355,10 +380,29 @@ declare function resolveRangeTag(range: string | undefined, propertyType: string
355
380
  */
356
381
  declare function mapHydraSchemaToFields(schema: HydraResourceSchema, urlLookup?: (className: string) => string | undefined, schemaLookup?: (className: string) => HydraResourceSchema | undefined): Field[];
357
382
  //#endregion
383
+ //#region packages/hydra/buildEmbeddedFormDetail.d.ts
384
+ interface BuildEmbeddedFormDetailOptions {
385
+ binding: EmbeddedLinesSchema;
386
+ lineSchema?: HydraResourceSchema;
387
+ resourceMap?: Record<string, HydraResourceSchema>;
388
+ overrides?: Partial<Omit<ResourceFormDetail, 'fields' | 'url'>>;
389
+ }
390
+ /**
391
+ * Builds a {@link ResourceFormDetail} from `x-embedded-lines` metadata and the
392
+ * line entity schema in the API doc.
393
+ */
394
+ declare function buildEmbeddedFormDetail({
395
+ binding,
396
+ lineSchema,
397
+ resourceMap,
398
+ overrides
399
+ }: BuildEmbeddedFormDetailOptions): ResourceFormDetail;
400
+ declare function resolveEmbeddedBinding(schema: HydraResourceSchema, propertyName?: string): EmbeddedLinesSchema | undefined;
401
+ //#endregion
358
402
  //#region packages/hydra/useHydraMetadata.d.ts
359
403
  /**
360
404
  * Stable query key used by useHydraMetadata.
361
- * Export this so that consumers (e.g. SmartCrudPage retry button) can
405
+ * Export this so that consumers (e.g. SchemaCrudPage retry button) can
362
406
  * invalidate exactly the right query without coupling to an internal string.
363
407
  */
364
408
  declare const API_DOC_QUERY_KEY: readonly ["api-doc-discovery"];
@@ -369,9 +413,22 @@ interface UseHydraMetadataResult {
369
413
  }
370
414
  declare function useHydraMetadata(): UseHydraMetadataResult;
371
415
  //#endregion
416
+ //#region packages/hydra/resolveInferredFormDetail.d.ts
417
+ /**
418
+ * Builds or augments `formDetail` from `x-embedded-lines` when the parent
419
+ * resource publishes embedded line metadata.
420
+ *
421
+ * Inference runs automatically when `x-embedded-lines` is present unless:
422
+ * - `formDetail.inferFields === false` (explicit opt-out), or
423
+ * - `formDetail.fields` is a non-empty manual array.
424
+ */
425
+ declare function resolveInferredFormDetail(apiUrl: string, formDetail: ResourceFormDetail | undefined, schemaData: UseHydraMetadataResult['data'], embeddedLines?: HydraResourceSchema['embeddedLines']): ResourceFormDetail | undefined;
426
+ //#endregion
372
427
  //#region packages/hydra/useResourceSchema.d.ts
373
428
  type UseResourceSchemaResult = ResourceSchemaResolution;
374
- declare function useResourceSchema<T extends DataRecord$1 = DataRecord$1>(apiUrl: string): UseResourceSchemaResult;
429
+ declare function useResourceSchema<T extends DataRecord$1 = DataRecord$1>(apiUrl: string, options?: {
430
+ enabled?: boolean;
431
+ }): UseResourceSchemaResult;
375
432
  //#endregion
376
433
  //#region packages/hydra/SchemaContext.d.ts
377
434
  interface SchemaProviderProps {
@@ -379,7 +436,7 @@ interface SchemaProviderProps {
379
436
  }
380
437
  /**
381
438
  * Wrap your app (or a subtree) with `SchemaProvider` to share a single
382
- * `/api/docs.jsonld` fetch across all `SmartCrudPage` instances.
439
+ * `/api/docs.jsonld` fetch across all `SchemaCrudPage` instances.
383
440
  */
384
441
  declare function SchemaProvider({
385
442
  children
@@ -395,8 +452,8 @@ interface UseSchemaContextResult {
395
452
  * Returns the shared schema context if inside a `<SchemaProvider>`,
396
453
  * otherwise falls back to calling `useHydraMetadata()` directly.
397
454
  *
398
- * This makes `SmartCrudPage` work standalone without requiring a provider.
455
+ * This makes `SchemaCrudPage` work standalone without requiring a provider.
399
456
  */
400
457
  declare function useSchemaContext(): UseSchemaContextResult;
401
458
  //#endregion
402
- export { API_DOC_QUERY_KEY, type ApiDoc, type HydraApiDoc, HydraRemoteDataSource, HydraResourceSchemaProvider, type HydraResourceSchemaProviderProps, HydraResourceStoreProvider, type HydraResourceStoreProviderProps, type OpenApiDoc, type RemoteDataSourceOptions, type RemoteFilterDescriptor, type RemoteLoadOptions, type RemoteSortDescriptor, SchemaProvider, type SequenceSchema, type UseSchemaContextResult, type WorkflowSchema, type WorkflowTransitionSchema, createHydraResourceStore, mapHydraSchemaToFields, parseHydraDoc, parseOpenApiDoc, resolveRangeTag, useHydraMetadata, useResourceSchema, useSchemaContext };
459
+ export { API_DOC_QUERY_KEY, type ApiDoc, type EmbeddedLinesSchema, type HydraApiDoc, HydraRemoteDataSource, HydraResourceSchemaProvider, type HydraResourceSchemaProviderProps, HydraResourceStoreProvider, type HydraResourceStoreProviderProps, type OpenApiDoc, type RemoteDataSourceOptions, type RemoteFilterDescriptor, type RemoteLoadOptions, type RemoteSortDescriptor, SchemaProvider, type SequenceSchema, type UseSchemaContextResult, type WorkflowSchema, type WorkflowTransitionSchema, buildEmbeddedFormDetail, createHydraResourceStore, mapHydraSchemaToFields, parseHydraDoc, parseOpenApiDoc, resolveEmbeddedBinding, resolveInferredFormDetail, resolveRangeTag, useHydraMetadata, useResourceSchema, useSchemaContext };
package/dist/index.d.mts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { DataRecord, GridData } from "@nubitio/core";
2
2
  import React, { ReactNode } from "react";
3
- import { DataRecord as DataRecord$1, Field, FormLayout, ResourceFilterDescriptor, ResourceFilterRule, ResourceLoadOptions, ResourceSchemaResolution, ResourceSortDescriptor, ResourceStore, ResourceStoreFactory, ResourceStoreOptions } from "@nubitio/crud";
3
+ import { DataRecord as DataRecord$1, Field, FormLayout, ResourceFilterDescriptor, ResourceFilterRule, ResourceFormDetail, ResourceLoadOptions, ResourceSchemaResolution, ResourceSortDescriptor, ResourceStore, ResourceStoreFactory, ResourceStoreOptions } from "@nubitio/crud";
4
4
 
5
5
  //#region packages/hydra/HydraRemoteDataSource.d.ts
6
6
  type RemoteFilterDescriptor = ResourceFilterDescriptor;
@@ -60,10 +60,22 @@ interface CrudHints {
60
60
  filterable?: boolean;
61
61
  /** Override whether the field can be sorted in the grid. */
62
62
  sortable?: boolean;
63
- /** When true, the column is hidden from the grid by default (the form still shows the field). */
63
+ /**
64
+ * When true, the column is hidden from the grid (the form still shows the field).
65
+ * @deprecated Prefer `hideInGrid`.
66
+ */
64
67
  hidden?: boolean;
65
- /** When false, the field is excluded from the create/edit form (the grid still shows the column). */
68
+ /** When true, hide the column from the grid. Preferred over `hidden`. */
69
+ hideInGrid?: boolean;
70
+ /**
71
+ * When false, exclude from the create/edit form (the grid still shows the column).
72
+ * @deprecated Prefer `showInForm`.
73
+ */
66
74
  visibleOnForm?: boolean;
75
+ /** When false, exclude from the form. Preferred over `visibleOnForm`. */
76
+ showInForm?: boolean;
77
+ /** When true, render as read-only in the create/edit form. */
78
+ readonly?: boolean;
67
79
  /** Column display order. */
68
80
  order?: number;
69
81
  /** Column width in pixels or as a CSS string. */
@@ -144,6 +156,15 @@ interface SequenceSchema {
144
156
  padding?: number;
145
157
  scope?: string[];
146
158
  }
159
+ /** Master-detail line metadata from nubitio/admin-bundle EmbeddedLinesDocumentationNormalizer. */
160
+ interface EmbeddedLinesSchema {
161
+ propertyName: string;
162
+ lineClass: string;
163
+ lineEntityClass?: string;
164
+ routePath: string;
165
+ parentQueryParam: string;
166
+ reloadUrl: string;
167
+ }
147
168
  interface HydraClass {
148
169
  '@id': string;
149
170
  '@type': string;
@@ -159,6 +180,8 @@ interface HydraClass {
159
180
  * @nubitio/crud's FormLayout shape.
160
181
  */
161
182
  'x-crud-layout'?: FormLayout;
183
+ /** Embedded line collections declared on parent document resources. */
184
+ 'x-embedded-lines'?: EmbeddedLinesSchema[];
162
185
  /**
163
186
  * Hydra search template describing server-side filterable query params.
164
187
  * Present on collection operations in API Platform JSON-LD responses.
@@ -249,6 +272,8 @@ interface HydraResourceSchema {
249
272
  workflow?: WorkflowSchema;
250
273
  /** Server-allocated sequence field (nubitio/sequence-bundle). */
251
274
  sequence?: SequenceSchema;
275
+ /** Embedded line collections (nubitio/admin-bundle). */
276
+ embeddedLines?: EmbeddedLinesSchema[];
252
277
  }
253
278
  interface OpenApiProperty {
254
279
  type?: string;
@@ -355,10 +380,29 @@ declare function resolveRangeTag(range: string | undefined, propertyType: string
355
380
  */
356
381
  declare function mapHydraSchemaToFields(schema: HydraResourceSchema, urlLookup?: (className: string) => string | undefined, schemaLookup?: (className: string) => HydraResourceSchema | undefined): Field[];
357
382
  //#endregion
383
+ //#region packages/hydra/buildEmbeddedFormDetail.d.ts
384
+ interface BuildEmbeddedFormDetailOptions {
385
+ binding: EmbeddedLinesSchema;
386
+ lineSchema?: HydraResourceSchema;
387
+ resourceMap?: Record<string, HydraResourceSchema>;
388
+ overrides?: Partial<Omit<ResourceFormDetail, 'fields' | 'url'>>;
389
+ }
390
+ /**
391
+ * Builds a {@link ResourceFormDetail} from `x-embedded-lines` metadata and the
392
+ * line entity schema in the API doc.
393
+ */
394
+ declare function buildEmbeddedFormDetail({
395
+ binding,
396
+ lineSchema,
397
+ resourceMap,
398
+ overrides
399
+ }: BuildEmbeddedFormDetailOptions): ResourceFormDetail;
400
+ declare function resolveEmbeddedBinding(schema: HydraResourceSchema, propertyName?: string): EmbeddedLinesSchema | undefined;
401
+ //#endregion
358
402
  //#region packages/hydra/useHydraMetadata.d.ts
359
403
  /**
360
404
  * Stable query key used by useHydraMetadata.
361
- * Export this so that consumers (e.g. SmartCrudPage retry button) can
405
+ * Export this so that consumers (e.g. SchemaCrudPage retry button) can
362
406
  * invalidate exactly the right query without coupling to an internal string.
363
407
  */
364
408
  declare const API_DOC_QUERY_KEY: readonly ["api-doc-discovery"];
@@ -369,9 +413,22 @@ interface UseHydraMetadataResult {
369
413
  }
370
414
  declare function useHydraMetadata(): UseHydraMetadataResult;
371
415
  //#endregion
416
+ //#region packages/hydra/resolveInferredFormDetail.d.ts
417
+ /**
418
+ * Builds or augments `formDetail` from `x-embedded-lines` when the parent
419
+ * resource publishes embedded line metadata.
420
+ *
421
+ * Inference runs automatically when `x-embedded-lines` is present unless:
422
+ * - `formDetail.inferFields === false` (explicit opt-out), or
423
+ * - `formDetail.fields` is a non-empty manual array.
424
+ */
425
+ declare function resolveInferredFormDetail(apiUrl: string, formDetail: ResourceFormDetail | undefined, schemaData: UseHydraMetadataResult['data'], embeddedLines?: HydraResourceSchema['embeddedLines']): ResourceFormDetail | undefined;
426
+ //#endregion
372
427
  //#region packages/hydra/useResourceSchema.d.ts
373
428
  type UseResourceSchemaResult = ResourceSchemaResolution;
374
- declare function useResourceSchema<T extends DataRecord$1 = DataRecord$1>(apiUrl: string): UseResourceSchemaResult;
429
+ declare function useResourceSchema<T extends DataRecord$1 = DataRecord$1>(apiUrl: string, options?: {
430
+ enabled?: boolean;
431
+ }): UseResourceSchemaResult;
375
432
  //#endregion
376
433
  //#region packages/hydra/SchemaContext.d.ts
377
434
  interface SchemaProviderProps {
@@ -379,7 +436,7 @@ interface SchemaProviderProps {
379
436
  }
380
437
  /**
381
438
  * Wrap your app (or a subtree) with `SchemaProvider` to share a single
382
- * `/api/docs.jsonld` fetch across all `SmartCrudPage` instances.
439
+ * `/api/docs.jsonld` fetch across all `SchemaCrudPage` instances.
383
440
  */
384
441
  declare function SchemaProvider({
385
442
  children
@@ -395,8 +452,8 @@ interface UseSchemaContextResult {
395
452
  * Returns the shared schema context if inside a `<SchemaProvider>`,
396
453
  * otherwise falls back to calling `useHydraMetadata()` directly.
397
454
  *
398
- * This makes `SmartCrudPage` work standalone without requiring a provider.
455
+ * This makes `SchemaCrudPage` work standalone without requiring a provider.
399
456
  */
400
457
  declare function useSchemaContext(): UseSchemaContextResult;
401
458
  //#endregion
402
- export { API_DOC_QUERY_KEY, type ApiDoc, type HydraApiDoc, HydraRemoteDataSource, HydraResourceSchemaProvider, type HydraResourceSchemaProviderProps, HydraResourceStoreProvider, type HydraResourceStoreProviderProps, type OpenApiDoc, type RemoteDataSourceOptions, type RemoteFilterDescriptor, type RemoteLoadOptions, type RemoteSortDescriptor, SchemaProvider, type SequenceSchema, type UseSchemaContextResult, type WorkflowSchema, type WorkflowTransitionSchema, createHydraResourceStore, mapHydraSchemaToFields, parseHydraDoc, parseOpenApiDoc, resolveRangeTag, useHydraMetadata, useResourceSchema, useSchemaContext };
459
+ export { API_DOC_QUERY_KEY, type ApiDoc, type EmbeddedLinesSchema, type HydraApiDoc, HydraRemoteDataSource, HydraResourceSchemaProvider, type HydraResourceSchemaProviderProps, HydraResourceStoreProvider, type HydraResourceStoreProviderProps, type OpenApiDoc, type RemoteDataSourceOptions, type RemoteFilterDescriptor, type RemoteLoadOptions, type RemoteSortDescriptor, SchemaProvider, type SequenceSchema, type UseSchemaContextResult, type WorkflowSchema, type WorkflowTransitionSchema, buildEmbeddedFormDetail, createHydraResourceStore, mapHydraSchemaToFields, parseHydraDoc, parseOpenApiDoc, resolveEmbeddedBinding, resolveInferredFormDetail, resolveRangeTag, useHydraMetadata, useResourceSchema, useSchemaContext };
package/dist/index.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  import { createCoreHttpClient, useCoreConfig, useCoreHttpClient } from "@nubitio/core";
2
2
  import { createContext, useContext, useMemo } from "react";
3
- import { ResourceSchemaProvider, ResourceStoreProvider, currencyField, datetimeField, entityField, enumField, fileField, imageField, noneField, numberField, switchField, textField } from "@nubitio/crud";
3
+ import { ResourceSchemaProvider, ResourceStoreProvider, currencyField, datetimeField, embeddedLinesUrl, entityField, enumField, fileField, imageField, noneField, numberField, switchField, textField } from "@nubitio/crud";
4
4
  import { jsx } from "react/jsx-runtime";
5
5
  import { useQuery } from "@tanstack/react-query";
6
6
  //#region packages/hydra/HydraRemoteDataSource.ts
@@ -434,6 +434,7 @@ function parseHydraDoc(doc, entrypointHrefs) {
434
434
  formLayout: cls["x-crud-layout"],
435
435
  workflow: cls["x-workflow"],
436
436
  sequence: cls["x-sequence"],
437
+ embeddedLines: cls["x-embedded-lines"],
437
438
  searchMappings: extractSearchMappings(cls),
438
439
  supportedOperations: Array.from(new Set([...collectionOperationsMap[className] ?? [], ...extractSupportedOperations(cls)]))
439
440
  };
@@ -473,6 +474,30 @@ function parseOpenApiDoc(doc) {
473
474
  return result;
474
475
  }
475
476
  //#endregion
477
+ //#region packages/hydra/crudHintDeprecations.ts
478
+ const warned = /* @__PURE__ */ new Set();
479
+ function isDev$1() {
480
+ return typeof window !== "undefined" && (window.location.hostname === "localhost" || window.location.hostname === "127.0.0.1" || window.location.hostname.endsWith(".localhost"));
481
+ }
482
+ /** Warn once per session when legacy x-crud keys are used. */
483
+ function warnDeprecatedCrudHints(hints, fieldName) {
484
+ if (!hints || !isDev$1()) return;
485
+ if (hints.hidden !== void 0 && hints.hideInGrid === void 0) {
486
+ const key = `hidden:${fieldName}`;
487
+ if (!warned.has(key)) {
488
+ warned.add(key);
489
+ console.warn(`[Nubit] x-crud.hidden on "${fieldName}" is deprecated — use hideInGrid instead.`);
490
+ }
491
+ }
492
+ if (hints.visibleOnForm !== void 0 && hints.showInForm === void 0) {
493
+ const key = `visibleOnForm:${fieldName}`;
494
+ if (!warned.has(key)) {
495
+ warned.add(key);
496
+ console.warn(`[Nubit] x-crud.visibleOnForm on "${fieldName}" is deprecated — use showInForm instead.`);
497
+ }
498
+ }
499
+ }
500
+ //#endregion
476
501
  //#region packages/hydra/HydraToFieldMapper.ts
477
502
  /**
478
503
  * Returns true when the given `range` string declares an XSD integer type.
@@ -535,14 +560,45 @@ function resolveRangeTag(range, propertyType) {
535
560
  * `visibleOnForm: false` excludes the field from the create/edit form only.
536
561
  * `order` maps to the `Field.order` property used by native grid column ordering.
537
562
  */
538
- function applyCrudHints(field, hints) {
539
- if (!hints) return;
540
- if (hints.filterable !== void 0) field.filterable = hints.filterable;
541
- if (hints.sortable !== void 0) field.sortable = hints.sortable;
542
- if (hints.hidden !== void 0 && hints.hidden) field.visible = false;
543
- if (hints.visibleOnForm !== void 0) field.visibleOnForm = hints.visibleOnForm;
544
- if (hints.order !== void 0) field.order = hints.order;
545
- if (hints.width !== void 0) field.width = hints.width;
563
+ function applyCrudHints(field, hints, fieldName) {
564
+ const applied = [];
565
+ if (!hints) return applied;
566
+ warnDeprecatedCrudHints(hints, fieldName ?? field.name);
567
+ if (hints.filterable !== void 0) {
568
+ field.filterable = hints.filterable;
569
+ applied.push(`filterable=${hints.filterable}`);
570
+ }
571
+ if (hints.sortable !== void 0) {
572
+ field.sortable = hints.sortable;
573
+ applied.push(`sortable=${hints.sortable}`);
574
+ }
575
+ if (hints.hideInGrid ?? hints.hidden) {
576
+ field.visible = false;
577
+ applied.push("hideInGrid");
578
+ }
579
+ const showInForm = hints.showInForm ?? hints.visibleOnForm;
580
+ if (showInForm !== void 0) {
581
+ field.visibleOnForm = showInForm;
582
+ applied.push(`showInForm=${showInForm}`);
583
+ }
584
+ if (hints.readonly !== void 0) {
585
+ field.readonly = hints.readonly;
586
+ applied.push(`readonly=${hints.readonly}`);
587
+ }
588
+ if (hints.order !== void 0) {
589
+ field.order = hints.order;
590
+ applied.push(`order=${hints.order}`);
591
+ }
592
+ if (hints.width !== void 0) {
593
+ field.width = hints.width;
594
+ applied.push(`width=${hints.width}`);
595
+ }
596
+ return applied;
597
+ }
598
+ function stampMappingReason(field, rule, hintSuffix) {
599
+ const parts = [rule];
600
+ if (hintSuffix && hintSuffix.length > 0) parts.push(`x-crud: ${hintSuffix.join(", ")}`);
601
+ field.mappingReason = parts.join(" → ");
546
602
  }
547
603
  /**
548
604
  * Apply `x-sequence` hints: the server-allocated field is read-only and
@@ -632,6 +688,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
632
688
  hideable: false,
633
689
  visibleOnForm: false
634
690
  };
691
+ stampMappingReason(idField, `rule-1 identity (${isIntegerRange(range) ? "numberField" : "textField"})`, applyCrudHints(idField, fieldSchema.crudHints));
635
692
  fields.push(idField);
636
693
  continue;
637
694
  }
@@ -644,7 +701,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
644
701
  ...(fieldSchema.crudHints?.format === "currency" ? currencyField().readonly(true) : noneField()).name(name).label(label).required(required).build(),
645
702
  filterable
646
703
  };
647
- applyCrudHints(field, fieldSchema.crudHints);
704
+ stampMappingReason(field, fieldSchema.crudHints?.format === "currency" ? "rule-3 display-only+currency" : "rule-3 display-only", applyCrudHints(field, fieldSchema.crudHints));
648
705
  fields.push(field);
649
706
  continue;
650
707
  }
@@ -658,7 +715,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
658
715
  }))).name(name).label(label).required(required).build(),
659
716
  filterable
660
717
  };
661
- applyCrudHints(field, fieldSchema.crudHints);
718
+ stampMappingReason(field, "rule-3.5 enum", applyCrudHints(field, fieldSchema.crudHints));
662
719
  fields.push(field);
663
720
  continue;
664
721
  }
@@ -670,7 +727,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
670
727
  filterable: false,
671
728
  sortable: false
672
729
  };
673
- applyCrudHints(field, fieldSchema.crudHints);
730
+ stampMappingReason(field, `rule-3.55 ${formatHint}`, applyCrudHints(field, fieldSchema.crudHints));
674
731
  fields.push(field);
675
732
  continue;
676
733
  }
@@ -679,7 +736,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
679
736
  ...currencyField().name(name).label(label).required(required).build(),
680
737
  filterable
681
738
  };
682
- applyCrudHints(field, fieldSchema.crudHints);
739
+ stampMappingReason(field, "rule-3.6 currency", applyCrudHints(field, fieldSchema.crudHints));
683
740
  fields.push(field);
684
741
  continue;
685
742
  }
@@ -688,7 +745,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
688
745
  ...switchField().name(name).label(label).required(required).build(),
689
746
  filterable
690
747
  };
691
- applyCrudHints(field, fieldSchema.crudHints);
748
+ stampMappingReason(field, "rule-4 boolean", applyCrudHints(field, fieldSchema.crudHints));
692
749
  fields.push(field);
693
750
  continue;
694
751
  }
@@ -697,7 +754,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
697
754
  ...datetimeField().name(name).label(label).required(required).build(),
698
755
  filterable
699
756
  };
700
- applyCrudHints(field, fieldSchema.crudHints);
757
+ stampMappingReason(field, "rule-5 dateTime", applyCrudHints(field, fieldSchema.crudHints));
701
758
  fields.push(field);
702
759
  continue;
703
760
  }
@@ -706,7 +763,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
706
763
  ...numberField().name(name).label(label).required(required).precision(0).build(),
707
764
  filterable
708
765
  };
709
- applyCrudHints(field, fieldSchema.crudHints);
766
+ stampMappingReason(field, "rule-6 integer", applyCrudHints(field, fieldSchema.crudHints));
710
767
  fields.push(field);
711
768
  continue;
712
769
  }
@@ -715,7 +772,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
715
772
  ...numberField().name(name).label(label).required(required).build(),
716
773
  filterable
717
774
  };
718
- applyCrudHints(field, fieldSchema.crudHints);
775
+ stampMappingReason(field, "rule-7 decimal", applyCrudHints(field, fieldSchema.crudHints));
719
776
  fields.push(field);
720
777
  continue;
721
778
  }
@@ -728,7 +785,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
728
785
  ...entityField(url, valueField, resolveEntityTextField(relatedSchema, valueField)).name(name).label(label).required(required).build(),
729
786
  filterable
730
787
  };
731
- applyCrudHints(field, fieldSchema.crudHints);
788
+ stampMappingReason(field, `rule-8 entity → ${url || "unknown-url"}`, applyCrudHints(field, fieldSchema.crudHints));
732
789
  fields.push(field);
733
790
  continue;
734
791
  }
@@ -736,7 +793,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
736
793
  ...textField().name(name).label(label).required(required).build(),
737
794
  filterable
738
795
  };
739
- applyCrudHints(field, fieldSchema.crudHints);
796
+ stampMappingReason(field, `rule-9 text (range=${range ?? "none"})`, applyCrudHints(field, fieldSchema.crudHints));
740
797
  fields.push(field);
741
798
  }
742
799
  if (!hasIdField) {
@@ -750,6 +807,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
750
807
  hideable: false,
751
808
  visibleOnForm: false
752
809
  };
810
+ stampMappingReason(syntheticId, "rule-1b synthetic identity (no id in schema)");
753
811
  fields.unshift(syntheticId);
754
812
  }
755
813
  applySequenceHints(fields, schema);
@@ -806,7 +864,7 @@ async function fetchEntrypointHrefs(httpClient) {
806
864
  }
807
865
  /**
808
866
  * Stable query key used by useHydraMetadata.
809
- * Export this so that consumers (e.g. SmartCrudPage retry button) can
867
+ * Export this so that consumers (e.g. SchemaCrudPage retry button) can
810
868
  * invalidate exactly the right query without coupling to an internal string.
811
869
  */
812
870
  const API_DOC_QUERY_KEY = ["api-doc-discovery"];
@@ -855,13 +913,13 @@ function useHydraMetadata() {
855
913
  * SchemaContext — shared parsed schema, no per-page re-fetch.
856
914
  *
857
915
  * Provides a single shared `useHydraMetadata()` call at the provider level
858
- * so that multiple `SmartCrudPage` instances mounted simultaneously share
916
+ * so that multiple `SchemaCrudPage` instances mounted simultaneously share
859
917
  * one `/api/docs.jsonld` request instead of each issuing their own.
860
918
  *
861
919
  * ## Usage
862
920
  *
863
921
  * ```tsx
864
- * // In your app root (optional — SmartCrudPage still works without it):
922
+ * // In your app root (optional — SchemaCrudPage still works without it):
865
923
  * <SchemaProvider>
866
924
  * <App />
867
925
  * </SchemaProvider>
@@ -876,7 +934,7 @@ const OUTSIDE_PROVIDER = Symbol("OUTSIDE_PROVIDER");
876
934
  const SchemaContext = createContext(OUTSIDE_PROVIDER);
877
935
  /**
878
936
  * Wrap your app (or a subtree) with `SchemaProvider` to share a single
879
- * `/api/docs.jsonld` fetch across all `SmartCrudPage` instances.
937
+ * `/api/docs.jsonld` fetch across all `SchemaCrudPage` instances.
880
938
  */
881
939
  function SchemaProvider({ children }) {
882
940
  const metadata = useHydraMetadata();
@@ -889,7 +947,7 @@ function SchemaProvider({ children }) {
889
947
  * Returns the shared schema context if inside a `<SchemaProvider>`,
890
948
  * otherwise falls back to calling `useHydraMetadata()` directly.
891
949
  *
892
- * This makes `SmartCrudPage` work standalone without requiring a provider.
950
+ * This makes `SchemaCrudPage` work standalone without requiring a provider.
893
951
  */
894
952
  function useSchemaContext() {
895
953
  const ctx = useContext(SchemaContext);
@@ -913,13 +971,20 @@ function useSchemaContext() {
913
971
  * Normalizes an API URL by stripping any leading slash and query string so that
914
972
  * 'api/categories', '/api/categories', and '/api/categories?foo=bar' are treated as equal.
915
973
  */
916
- function normalizeUrl(url) {
974
+ function normalizeUrl$1(url) {
917
975
  const base = url.split("?")[0];
918
976
  return base.startsWith("/") ? base.slice(1) : base;
919
977
  }
920
- function useResourceSchema(apiUrl) {
978
+ function useResourceSchema(apiUrl, options) {
979
+ const enabled = options?.enabled !== false;
921
980
  const { data, isLoading, error } = useSchemaContext();
922
981
  return useMemo(() => {
982
+ if (!enabled) return {
983
+ fields: [],
984
+ isLoading: false,
985
+ error: void 0,
986
+ supportedOperations: []
987
+ };
923
988
  if (!data) return {
924
989
  fields: [],
925
990
  isLoading,
@@ -927,11 +992,11 @@ function useResourceSchema(apiUrl) {
927
992
  supportedOperations: []
928
993
  };
929
994
  const resourceMap = data.format === "hydra" ? parseHydraDoc(data.doc, data.entrypointHrefs) : parseOpenApiDoc(data.doc);
930
- const normalizedInput = normalizeUrl(apiUrl);
931
- const resourceSchema = Object.values(resourceMap).find((r) => normalizeUrl(r.apiUrl) === normalizedInput);
995
+ const normalizedInput = normalizeUrl$1(apiUrl);
996
+ const resourceSchema = Object.values(resourceMap).find((r) => normalizeUrl$1(r.apiUrl) === normalizedInput);
932
997
  if (!resourceSchema) {
933
998
  const knownUrls = Object.values(resourceMap).map((r) => r.apiUrl).sort();
934
- const slugMatch = knownUrls.find((url) => normalizeUrl(url).replace(/[-_]/g, "") === normalizedInput.replace(/[-_]/g, ""));
999
+ const slugMatch = knownUrls.find((url) => normalizeUrl$1(url).replace(/[-_]/g, "") === normalizedInput.replace(/[-_]/g, ""));
935
1000
  return {
936
1001
  fields: [],
937
1002
  isLoading: false,
@@ -947,10 +1012,12 @@ function useResourceSchema(apiUrl) {
947
1012
  formLayout: resourceSchema.formLayout,
948
1013
  workflow: resourceSchema.workflow,
949
1014
  sequence: resourceSchema.sequence,
950
- summaryFields: buildSummaryFieldsFromSchema(resourceSchema)
1015
+ summaryFields: buildSummaryFieldsFromSchema(resourceSchema),
1016
+ embeddedLines: resourceSchema.embeddedLines
951
1017
  };
952
1018
  }, [
953
1019
  data,
1020
+ enabled,
954
1021
  isLoading,
955
1022
  error,
956
1023
  apiUrl
@@ -958,8 +1025,8 @@ function useResourceSchema(apiUrl) {
958
1025
  }
959
1026
  //#endregion
960
1027
  //#region packages/hydra/HydraResourceSchemaProvider.tsx
961
- function useHydraResourceSchema({ apiUrl }) {
962
- return useResourceSchema(apiUrl);
1028
+ function useHydraResourceSchema({ apiUrl, enabled }) {
1029
+ return useResourceSchema(apiUrl, { enabled });
963
1030
  }
964
1031
  function HydraResourceSchemaProvider({ children }) {
965
1032
  return /* @__PURE__ */ jsx(ResourceSchemaProvider, {
@@ -968,4 +1035,75 @@ function HydraResourceSchemaProvider({ children }) {
968
1035
  });
969
1036
  }
970
1037
  //#endregion
971
- export { API_DOC_QUERY_KEY, HydraRemoteDataSource, HydraResourceSchemaProvider, HydraResourceStoreProvider, SchemaProvider, createHydraResourceStore, mapHydraSchemaToFields, parseHydraDoc, parseOpenApiDoc, resolveRangeTag, useHydraMetadata, useResourceSchema, useSchemaContext };
1038
+ //#region packages/hydra/buildEmbeddedFormDetail.ts
1039
+ /**
1040
+ * Builds a {@link ResourceFormDetail} from `x-embedded-lines` metadata and the
1041
+ * line entity schema in the API doc.
1042
+ */
1043
+ function buildEmbeddedFormDetail({ binding, lineSchema, resourceMap, overrides }) {
1044
+ const fields = lineSchema ? mapHydraSchemaToFields(lineSchema, (className) => resourceMap?.[className]?.apiUrl, (className) => resourceMap?.[className]).filter((field) => !field.isIdentity && field.name !== binding.parentQueryParam) : [];
1045
+ return {
1046
+ propertyName: binding.propertyName,
1047
+ url: embeddedLinesUrl(binding.routePath, binding.parentQueryParam),
1048
+ allowAdding: true,
1049
+ allowDeleting: true,
1050
+ allowUpdating: true,
1051
+ fields,
1052
+ ...overrides
1053
+ };
1054
+ }
1055
+ function resolveEmbeddedBinding(schema, propertyName) {
1056
+ const bindings = schema.embeddedLines ?? [];
1057
+ if (bindings.length === 0) return void 0;
1058
+ if (!propertyName) return bindings[0];
1059
+ return bindings.find((b) => b.propertyName === propertyName) ?? bindings[0];
1060
+ }
1061
+ //#endregion
1062
+ //#region packages/hydra/resolveInferredFormDetail.ts
1063
+ function normalizeUrl(url) {
1064
+ const base = url.split("?")[0];
1065
+ return base.startsWith("/") ? base.slice(1) : base;
1066
+ }
1067
+ function shouldInferFormDetail(formDetail, embeddedLines) {
1068
+ if (!embeddedLines?.length) return false;
1069
+ if (formDetail?.inferFields === false) return false;
1070
+ if (formDetail?.fields && formDetail.fields.length > 0) return false;
1071
+ return true;
1072
+ }
1073
+ /**
1074
+ * Builds or augments `formDetail` from `x-embedded-lines` when the parent
1075
+ * resource publishes embedded line metadata.
1076
+ *
1077
+ * Inference runs automatically when `x-embedded-lines` is present unless:
1078
+ * - `formDetail.inferFields === false` (explicit opt-out), or
1079
+ * - `formDetail.fields` is a non-empty manual array.
1080
+ */
1081
+ function resolveInferredFormDetail(apiUrl, formDetail, schemaData, embeddedLines) {
1082
+ if (!shouldInferFormDetail(formDetail, embeddedLines) || !schemaData) return formDetail;
1083
+ const resourceMap = schemaData.format === "hydra" ? parseHydraDoc(schemaData.doc, schemaData.entrypointHrefs) : parseOpenApiDoc(schemaData.doc);
1084
+ const parentSchema = Object.values(resourceMap).find((schema) => normalizeUrl(schema.apiUrl) === normalizeUrl(apiUrl));
1085
+ const binding = resolveEmbeddedBinding({
1086
+ className: parentSchema?.className ?? "",
1087
+ apiUrl,
1088
+ fields: parentSchema?.fields ?? [],
1089
+ embeddedLines: parentSchema?.embeddedLines ?? embeddedLines
1090
+ }, formDetail?.propertyName);
1091
+ if (!binding) return formDetail;
1092
+ const lineSchema = resourceMap[binding.lineClass];
1093
+ const { inferFields: _infer, fields: _fields, ...overrides } = formDetail ?? {};
1094
+ const built = buildEmbeddedFormDetail({
1095
+ binding,
1096
+ lineSchema,
1097
+ resourceMap,
1098
+ overrides
1099
+ });
1100
+ return {
1101
+ ...built,
1102
+ ...formDetail,
1103
+ propertyName: built.propertyName,
1104
+ url: built.url,
1105
+ fields: built.fields
1106
+ };
1107
+ }
1108
+ //#endregion
1109
+ export { API_DOC_QUERY_KEY, HydraRemoteDataSource, HydraResourceSchemaProvider, HydraResourceStoreProvider, SchemaProvider, buildEmbeddedFormDetail, createHydraResourceStore, mapHydraSchemaToFields, parseHydraDoc, parseOpenApiDoc, resolveEmbeddedBinding, resolveInferredFormDetail, resolveRangeTag, useHydraMetadata, useResourceSchema, useSchemaContext };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nubitio/hydra",
3
- "version": "0.5.30",
3
+ "version": "0.6.0",
4
4
  "type": "module",
5
5
  "description": "Hydra / OpenAPI adapter for @nubitio/crud — automatic schema discovery and data source from API Platform docs.",
6
6
  "license": "MIT",
@@ -50,7 +50,7 @@
50
50
  "react": "^19.0.0",
51
51
  "react-dom": "^19.0.0",
52
52
  "react-i18next": "^14.0.0",
53
- "@nubitio/core": "^0.5.30",
54
- "@nubitio/crud": "^0.5.30"
53
+ "@nubitio/core": "^0.6.0",
54
+ "@nubitio/crud": "^0.6.0"
55
55
  }
56
56
  }