@nubitio/hydra 0.5.29 → 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
@@ -42,16 +42,38 @@ function addIriField(url, item) {
42
42
  _iri: iri
43
43
  };
44
44
  }
45
+ function isFilterTuple(rule) {
46
+ return Array.isArray(rule) && rule.length === 3 && typeof rule[0] === "string" && typeof rule[1] === "string";
47
+ }
48
+ function isFilterRuleObject(rule) {
49
+ return !!rule && typeof rule === "object" && "field" in rule && "operator" in rule && "value" in rule;
50
+ }
51
+ function coerceFilterTuple(rule) {
52
+ if (isFilterTuple(rule)) return rule;
53
+ if (isFilterRuleObject(rule)) return [
54
+ rule.field,
55
+ rule.operator,
56
+ rule.value
57
+ ];
58
+ if (Array.isArray(rule)) {
59
+ if (rule.length > 0 && Array.isArray(rule[0])) return rule;
60
+ return rule;
61
+ }
62
+ return [rule];
63
+ }
45
64
  function normalizeFilterRules(filterRules, defaultFilterRules) {
46
65
  const filters = [];
47
- defaultFilterRules.forEach((rule) => filters.push(rule));
48
- if (filterRules.length === 3 && typeof filterRules[0] !== "object") filters.push([
49
- filterRules[0],
50
- filterRules[1],
51
- filterRules[2]
52
- ]);
53
- else filterRules.forEach((rule) => {
54
- filters.push(Array.isArray(rule) ? rule : [rule]);
66
+ defaultFilterRules.forEach((rule) => filters.push(coerceFilterTuple(rule)));
67
+ if (filterRules.length === 3 && typeof filterRules[0] !== "object") {
68
+ filters.push([
69
+ filterRules[0],
70
+ filterRules[1],
71
+ filterRules[2]
72
+ ]);
73
+ return filters;
74
+ }
75
+ filterRules.forEach((rule) => {
76
+ filters.push(coerceFilterTuple(rule));
55
77
  });
56
78
  return filters;
57
79
  }
@@ -436,6 +458,7 @@ function parseHydraDoc(doc, entrypointHrefs) {
436
458
  formLayout: cls["x-crud-layout"],
437
459
  workflow: cls["x-workflow"],
438
460
  sequence: cls["x-sequence"],
461
+ embeddedLines: cls["x-embedded-lines"],
439
462
  searchMappings: extractSearchMappings(cls),
440
463
  supportedOperations: Array.from(new Set([...collectionOperationsMap[className] ?? [], ...extractSupportedOperations(cls)]))
441
464
  };
@@ -475,6 +498,30 @@ function parseOpenApiDoc(doc) {
475
498
  return result;
476
499
  }
477
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
478
525
  //#region packages/hydra/HydraToFieldMapper.ts
479
526
  /**
480
527
  * Returns true when the given `range` string declares an XSD integer type.
@@ -537,14 +584,45 @@ function resolveRangeTag(range, propertyType) {
537
584
  * `visibleOnForm: false` excludes the field from the create/edit form only.
538
585
  * `order` maps to the `Field.order` property used by native grid column ordering.
539
586
  */
540
- function applyCrudHints(field, hints) {
541
- if (!hints) return;
542
- if (hints.filterable !== void 0) field.filterable = hints.filterable;
543
- if (hints.sortable !== void 0) field.sortable = hints.sortable;
544
- if (hints.hidden !== void 0 && hints.hidden) field.visible = false;
545
- if (hints.visibleOnForm !== void 0) field.visibleOnForm = hints.visibleOnForm;
546
- if (hints.order !== void 0) field.order = hints.order;
547
- 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(" → ");
548
626
  }
549
627
  /**
550
628
  * Apply `x-sequence` hints: the server-allocated field is read-only and
@@ -634,6 +712,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
634
712
  hideable: false,
635
713
  visibleOnForm: false
636
714
  };
715
+ stampMappingReason(idField, `rule-1 identity (${isIntegerRange(range) ? "numberField" : "textField"})`, applyCrudHints(idField, fieldSchema.crudHints));
637
716
  fields.push(idField);
638
717
  continue;
639
718
  }
@@ -646,7 +725,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
646
725
  ...(fieldSchema.crudHints?.format === "currency" ? (0, _nubitio_crud.currencyField)().readonly(true) : (0, _nubitio_crud.noneField)()).name(name).label(label).required(required).build(),
647
726
  filterable
648
727
  };
649
- applyCrudHints(field, fieldSchema.crudHints);
728
+ stampMappingReason(field, fieldSchema.crudHints?.format === "currency" ? "rule-3 display-only+currency" : "rule-3 display-only", applyCrudHints(field, fieldSchema.crudHints));
650
729
  fields.push(field);
651
730
  continue;
652
731
  }
@@ -660,7 +739,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
660
739
  }))).name(name).label(label).required(required).build(),
661
740
  filterable
662
741
  };
663
- applyCrudHints(field, fieldSchema.crudHints);
742
+ stampMappingReason(field, "rule-3.5 enum", applyCrudHints(field, fieldSchema.crudHints));
664
743
  fields.push(field);
665
744
  continue;
666
745
  }
@@ -672,7 +751,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
672
751
  filterable: false,
673
752
  sortable: false
674
753
  };
675
- applyCrudHints(field, fieldSchema.crudHints);
754
+ stampMappingReason(field, `rule-3.55 ${formatHint}`, applyCrudHints(field, fieldSchema.crudHints));
676
755
  fields.push(field);
677
756
  continue;
678
757
  }
@@ -681,7 +760,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
681
760
  ...(0, _nubitio_crud.currencyField)().name(name).label(label).required(required).build(),
682
761
  filterable
683
762
  };
684
- applyCrudHints(field, fieldSchema.crudHints);
763
+ stampMappingReason(field, "rule-3.6 currency", applyCrudHints(field, fieldSchema.crudHints));
685
764
  fields.push(field);
686
765
  continue;
687
766
  }
@@ -690,7 +769,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
690
769
  ...(0, _nubitio_crud.switchField)().name(name).label(label).required(required).build(),
691
770
  filterable
692
771
  };
693
- applyCrudHints(field, fieldSchema.crudHints);
772
+ stampMappingReason(field, "rule-4 boolean", applyCrudHints(field, fieldSchema.crudHints));
694
773
  fields.push(field);
695
774
  continue;
696
775
  }
@@ -699,7 +778,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
699
778
  ...(0, _nubitio_crud.datetimeField)().name(name).label(label).required(required).build(),
700
779
  filterable
701
780
  };
702
- applyCrudHints(field, fieldSchema.crudHints);
781
+ stampMappingReason(field, "rule-5 dateTime", applyCrudHints(field, fieldSchema.crudHints));
703
782
  fields.push(field);
704
783
  continue;
705
784
  }
@@ -708,7 +787,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
708
787
  ...(0, _nubitio_crud.numberField)().name(name).label(label).required(required).precision(0).build(),
709
788
  filterable
710
789
  };
711
- applyCrudHints(field, fieldSchema.crudHints);
790
+ stampMappingReason(field, "rule-6 integer", applyCrudHints(field, fieldSchema.crudHints));
712
791
  fields.push(field);
713
792
  continue;
714
793
  }
@@ -717,7 +796,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
717
796
  ...(0, _nubitio_crud.numberField)().name(name).label(label).required(required).build(),
718
797
  filterable
719
798
  };
720
- applyCrudHints(field, fieldSchema.crudHints);
799
+ stampMappingReason(field, "rule-7 decimal", applyCrudHints(field, fieldSchema.crudHints));
721
800
  fields.push(field);
722
801
  continue;
723
802
  }
@@ -730,7 +809,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
730
809
  ...(0, _nubitio_crud.entityField)(url, valueField, resolveEntityTextField(relatedSchema, valueField)).name(name).label(label).required(required).build(),
731
810
  filterable
732
811
  };
733
- applyCrudHints(field, fieldSchema.crudHints);
812
+ stampMappingReason(field, `rule-8 entity → ${url || "unknown-url"}`, applyCrudHints(field, fieldSchema.crudHints));
734
813
  fields.push(field);
735
814
  continue;
736
815
  }
@@ -738,7 +817,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
738
817
  ...(0, _nubitio_crud.textField)().name(name).label(label).required(required).build(),
739
818
  filterable
740
819
  };
741
- applyCrudHints(field, fieldSchema.crudHints);
820
+ stampMappingReason(field, `rule-9 text (range=${range ?? "none"})`, applyCrudHints(field, fieldSchema.crudHints));
742
821
  fields.push(field);
743
822
  }
744
823
  if (!hasIdField) {
@@ -752,6 +831,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
752
831
  hideable: false,
753
832
  visibleOnForm: false
754
833
  };
834
+ stampMappingReason(syntheticId, "rule-1b synthetic identity (no id in schema)");
755
835
  fields.unshift(syntheticId);
756
836
  }
757
837
  applySequenceHints(fields, schema);
@@ -808,7 +888,7 @@ async function fetchEntrypointHrefs(httpClient) {
808
888
  }
809
889
  /**
810
890
  * Stable query key used by useHydraMetadata.
811
- * Export this so that consumers (e.g. SmartCrudPage retry button) can
891
+ * Export this so that consumers (e.g. SchemaCrudPage retry button) can
812
892
  * invalidate exactly the right query without coupling to an internal string.
813
893
  */
814
894
  const API_DOC_QUERY_KEY = ["api-doc-discovery"];
@@ -857,13 +937,13 @@ function useHydraMetadata() {
857
937
  * SchemaContext — shared parsed schema, no per-page re-fetch.
858
938
  *
859
939
  * Provides a single shared `useHydraMetadata()` call at the provider level
860
- * so that multiple `SmartCrudPage` instances mounted simultaneously share
940
+ * so that multiple `SchemaCrudPage` instances mounted simultaneously share
861
941
  * one `/api/docs.jsonld` request instead of each issuing their own.
862
942
  *
863
943
  * ## Usage
864
944
  *
865
945
  * ```tsx
866
- * // In your app root (optional — SmartCrudPage still works without it):
946
+ * // In your app root (optional — SchemaCrudPage still works without it):
867
947
  * <SchemaProvider>
868
948
  * <App />
869
949
  * </SchemaProvider>
@@ -878,7 +958,7 @@ const OUTSIDE_PROVIDER = Symbol("OUTSIDE_PROVIDER");
878
958
  const SchemaContext = (0, react.createContext)(OUTSIDE_PROVIDER);
879
959
  /**
880
960
  * Wrap your app (or a subtree) with `SchemaProvider` to share a single
881
- * `/api/docs.jsonld` fetch across all `SmartCrudPage` instances.
961
+ * `/api/docs.jsonld` fetch across all `SchemaCrudPage` instances.
882
962
  */
883
963
  function SchemaProvider({ children }) {
884
964
  const metadata = useHydraMetadata();
@@ -891,7 +971,7 @@ function SchemaProvider({ children }) {
891
971
  * Returns the shared schema context if inside a `<SchemaProvider>`,
892
972
  * otherwise falls back to calling `useHydraMetadata()` directly.
893
973
  *
894
- * This makes `SmartCrudPage` work standalone without requiring a provider.
974
+ * This makes `SchemaCrudPage` work standalone without requiring a provider.
895
975
  */
896
976
  function useSchemaContext() {
897
977
  const ctx = (0, react.useContext)(SchemaContext);
@@ -915,13 +995,20 @@ function useSchemaContext() {
915
995
  * Normalizes an API URL by stripping any leading slash and query string so that
916
996
  * 'api/categories', '/api/categories', and '/api/categories?foo=bar' are treated as equal.
917
997
  */
918
- function normalizeUrl(url) {
998
+ function normalizeUrl$1(url) {
919
999
  const base = url.split("?")[0];
920
1000
  return base.startsWith("/") ? base.slice(1) : base;
921
1001
  }
922
- function useResourceSchema(apiUrl) {
1002
+ function useResourceSchema(apiUrl, options) {
1003
+ const enabled = options?.enabled !== false;
923
1004
  const { data, isLoading, error } = useSchemaContext();
924
1005
  return (0, react.useMemo)(() => {
1006
+ if (!enabled) return {
1007
+ fields: [],
1008
+ isLoading: false,
1009
+ error: void 0,
1010
+ supportedOperations: []
1011
+ };
925
1012
  if (!data) return {
926
1013
  fields: [],
927
1014
  isLoading,
@@ -929,11 +1016,11 @@ function useResourceSchema(apiUrl) {
929
1016
  supportedOperations: []
930
1017
  };
931
1018
  const resourceMap = data.format === "hydra" ? parseHydraDoc(data.doc, data.entrypointHrefs) : parseOpenApiDoc(data.doc);
932
- const normalizedInput = normalizeUrl(apiUrl);
933
- 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);
934
1021
  if (!resourceSchema) {
935
1022
  const knownUrls = Object.values(resourceMap).map((r) => r.apiUrl).sort();
936
- 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, ""));
937
1024
  return {
938
1025
  fields: [],
939
1026
  isLoading: false,
@@ -949,10 +1036,12 @@ function useResourceSchema(apiUrl) {
949
1036
  formLayout: resourceSchema.formLayout,
950
1037
  workflow: resourceSchema.workflow,
951
1038
  sequence: resourceSchema.sequence,
952
- summaryFields: buildSummaryFieldsFromSchema(resourceSchema)
1039
+ summaryFields: buildSummaryFieldsFromSchema(resourceSchema),
1040
+ embeddedLines: resourceSchema.embeddedLines
953
1041
  };
954
1042
  }, [
955
1043
  data,
1044
+ enabled,
956
1045
  isLoading,
957
1046
  error,
958
1047
  apiUrl
@@ -960,8 +1049,8 @@ function useResourceSchema(apiUrl) {
960
1049
  }
961
1050
  //#endregion
962
1051
  //#region packages/hydra/HydraResourceSchemaProvider.tsx
963
- function useHydraResourceSchema({ apiUrl }) {
964
- return useResourceSchema(apiUrl);
1052
+ function useHydraResourceSchema({ apiUrl, enabled }) {
1053
+ return useResourceSchema(apiUrl, { enabled });
965
1054
  }
966
1055
  function HydraResourceSchemaProvider({ children }) {
967
1056
  return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_nubitio_crud.ResourceSchemaProvider, {
@@ -970,15 +1059,89 @@ function HydraResourceSchemaProvider({ children }) {
970
1059
  });
971
1060
  }
972
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
973
1133
  exports.API_DOC_QUERY_KEY = API_DOC_QUERY_KEY;
974
1134
  exports.HydraRemoteDataSource = HydraRemoteDataSource;
975
1135
  exports.HydraResourceSchemaProvider = HydraResourceSchemaProvider;
976
1136
  exports.HydraResourceStoreProvider = HydraResourceStoreProvider;
977
1137
  exports.SchemaProvider = SchemaProvider;
1138
+ exports.buildEmbeddedFormDetail = buildEmbeddedFormDetail;
978
1139
  exports.createHydraResourceStore = createHydraResourceStore;
979
1140
  exports.mapHydraSchemaToFields = mapHydraSchemaToFields;
980
1141
  exports.parseHydraDoc = parseHydraDoc;
981
1142
  exports.parseOpenApiDoc = parseOpenApiDoc;
1143
+ exports.resolveEmbeddedBinding = resolveEmbeddedBinding;
1144
+ exports.resolveInferredFormDetail = resolveInferredFormDetail;
982
1145
  exports.resolveRangeTag = resolveRangeTag;
983
1146
  exports.useHydraMetadata = useHydraMetadata;
984
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
@@ -18,16 +18,38 @@ function addIriField(url, item) {
18
18
  _iri: iri
19
19
  };
20
20
  }
21
+ function isFilterTuple(rule) {
22
+ return Array.isArray(rule) && rule.length === 3 && typeof rule[0] === "string" && typeof rule[1] === "string";
23
+ }
24
+ function isFilterRuleObject(rule) {
25
+ return !!rule && typeof rule === "object" && "field" in rule && "operator" in rule && "value" in rule;
26
+ }
27
+ function coerceFilterTuple(rule) {
28
+ if (isFilterTuple(rule)) return rule;
29
+ if (isFilterRuleObject(rule)) return [
30
+ rule.field,
31
+ rule.operator,
32
+ rule.value
33
+ ];
34
+ if (Array.isArray(rule)) {
35
+ if (rule.length > 0 && Array.isArray(rule[0])) return rule;
36
+ return rule;
37
+ }
38
+ return [rule];
39
+ }
21
40
  function normalizeFilterRules(filterRules, defaultFilterRules) {
22
41
  const filters = [];
23
- defaultFilterRules.forEach((rule) => filters.push(rule));
24
- if (filterRules.length === 3 && typeof filterRules[0] !== "object") filters.push([
25
- filterRules[0],
26
- filterRules[1],
27
- filterRules[2]
28
- ]);
29
- else filterRules.forEach((rule) => {
30
- filters.push(Array.isArray(rule) ? rule : [rule]);
42
+ defaultFilterRules.forEach((rule) => filters.push(coerceFilterTuple(rule)));
43
+ if (filterRules.length === 3 && typeof filterRules[0] !== "object") {
44
+ filters.push([
45
+ filterRules[0],
46
+ filterRules[1],
47
+ filterRules[2]
48
+ ]);
49
+ return filters;
50
+ }
51
+ filterRules.forEach((rule) => {
52
+ filters.push(coerceFilterTuple(rule));
31
53
  });
32
54
  return filters;
33
55
  }
@@ -412,6 +434,7 @@ function parseHydraDoc(doc, entrypointHrefs) {
412
434
  formLayout: cls["x-crud-layout"],
413
435
  workflow: cls["x-workflow"],
414
436
  sequence: cls["x-sequence"],
437
+ embeddedLines: cls["x-embedded-lines"],
415
438
  searchMappings: extractSearchMappings(cls),
416
439
  supportedOperations: Array.from(new Set([...collectionOperationsMap[className] ?? [], ...extractSupportedOperations(cls)]))
417
440
  };
@@ -451,6 +474,30 @@ function parseOpenApiDoc(doc) {
451
474
  return result;
452
475
  }
453
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
454
501
  //#region packages/hydra/HydraToFieldMapper.ts
455
502
  /**
456
503
  * Returns true when the given `range` string declares an XSD integer type.
@@ -513,14 +560,45 @@ function resolveRangeTag(range, propertyType) {
513
560
  * `visibleOnForm: false` excludes the field from the create/edit form only.
514
561
  * `order` maps to the `Field.order` property used by native grid column ordering.
515
562
  */
516
- function applyCrudHints(field, hints) {
517
- if (!hints) return;
518
- if (hints.filterable !== void 0) field.filterable = hints.filterable;
519
- if (hints.sortable !== void 0) field.sortable = hints.sortable;
520
- if (hints.hidden !== void 0 && hints.hidden) field.visible = false;
521
- if (hints.visibleOnForm !== void 0) field.visibleOnForm = hints.visibleOnForm;
522
- if (hints.order !== void 0) field.order = hints.order;
523
- 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(" → ");
524
602
  }
525
603
  /**
526
604
  * Apply `x-sequence` hints: the server-allocated field is read-only and
@@ -610,6 +688,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
610
688
  hideable: false,
611
689
  visibleOnForm: false
612
690
  };
691
+ stampMappingReason(idField, `rule-1 identity (${isIntegerRange(range) ? "numberField" : "textField"})`, applyCrudHints(idField, fieldSchema.crudHints));
613
692
  fields.push(idField);
614
693
  continue;
615
694
  }
@@ -622,7 +701,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
622
701
  ...(fieldSchema.crudHints?.format === "currency" ? currencyField().readonly(true) : noneField()).name(name).label(label).required(required).build(),
623
702
  filterable
624
703
  };
625
- applyCrudHints(field, fieldSchema.crudHints);
704
+ stampMappingReason(field, fieldSchema.crudHints?.format === "currency" ? "rule-3 display-only+currency" : "rule-3 display-only", applyCrudHints(field, fieldSchema.crudHints));
626
705
  fields.push(field);
627
706
  continue;
628
707
  }
@@ -636,7 +715,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
636
715
  }))).name(name).label(label).required(required).build(),
637
716
  filterable
638
717
  };
639
- applyCrudHints(field, fieldSchema.crudHints);
718
+ stampMappingReason(field, "rule-3.5 enum", applyCrudHints(field, fieldSchema.crudHints));
640
719
  fields.push(field);
641
720
  continue;
642
721
  }
@@ -648,7 +727,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
648
727
  filterable: false,
649
728
  sortable: false
650
729
  };
651
- applyCrudHints(field, fieldSchema.crudHints);
730
+ stampMappingReason(field, `rule-3.55 ${formatHint}`, applyCrudHints(field, fieldSchema.crudHints));
652
731
  fields.push(field);
653
732
  continue;
654
733
  }
@@ -657,7 +736,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
657
736
  ...currencyField().name(name).label(label).required(required).build(),
658
737
  filterable
659
738
  };
660
- applyCrudHints(field, fieldSchema.crudHints);
739
+ stampMappingReason(field, "rule-3.6 currency", applyCrudHints(field, fieldSchema.crudHints));
661
740
  fields.push(field);
662
741
  continue;
663
742
  }
@@ -666,7 +745,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
666
745
  ...switchField().name(name).label(label).required(required).build(),
667
746
  filterable
668
747
  };
669
- applyCrudHints(field, fieldSchema.crudHints);
748
+ stampMappingReason(field, "rule-4 boolean", applyCrudHints(field, fieldSchema.crudHints));
670
749
  fields.push(field);
671
750
  continue;
672
751
  }
@@ -675,7 +754,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
675
754
  ...datetimeField().name(name).label(label).required(required).build(),
676
755
  filterable
677
756
  };
678
- applyCrudHints(field, fieldSchema.crudHints);
757
+ stampMappingReason(field, "rule-5 dateTime", applyCrudHints(field, fieldSchema.crudHints));
679
758
  fields.push(field);
680
759
  continue;
681
760
  }
@@ -684,7 +763,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
684
763
  ...numberField().name(name).label(label).required(required).precision(0).build(),
685
764
  filterable
686
765
  };
687
- applyCrudHints(field, fieldSchema.crudHints);
766
+ stampMappingReason(field, "rule-6 integer", applyCrudHints(field, fieldSchema.crudHints));
688
767
  fields.push(field);
689
768
  continue;
690
769
  }
@@ -693,7 +772,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
693
772
  ...numberField().name(name).label(label).required(required).build(),
694
773
  filterable
695
774
  };
696
- applyCrudHints(field, fieldSchema.crudHints);
775
+ stampMappingReason(field, "rule-7 decimal", applyCrudHints(field, fieldSchema.crudHints));
697
776
  fields.push(field);
698
777
  continue;
699
778
  }
@@ -706,7 +785,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
706
785
  ...entityField(url, valueField, resolveEntityTextField(relatedSchema, valueField)).name(name).label(label).required(required).build(),
707
786
  filterable
708
787
  };
709
- applyCrudHints(field, fieldSchema.crudHints);
788
+ stampMappingReason(field, `rule-8 entity → ${url || "unknown-url"}`, applyCrudHints(field, fieldSchema.crudHints));
710
789
  fields.push(field);
711
790
  continue;
712
791
  }
@@ -714,7 +793,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
714
793
  ...textField().name(name).label(label).required(required).build(),
715
794
  filterable
716
795
  };
717
- applyCrudHints(field, fieldSchema.crudHints);
796
+ stampMappingReason(field, `rule-9 text (range=${range ?? "none"})`, applyCrudHints(field, fieldSchema.crudHints));
718
797
  fields.push(field);
719
798
  }
720
799
  if (!hasIdField) {
@@ -728,6 +807,7 @@ function mapHydraSchemaToFields(schema, urlLookup, schemaLookup) {
728
807
  hideable: false,
729
808
  visibleOnForm: false
730
809
  };
810
+ stampMappingReason(syntheticId, "rule-1b synthetic identity (no id in schema)");
731
811
  fields.unshift(syntheticId);
732
812
  }
733
813
  applySequenceHints(fields, schema);
@@ -784,7 +864,7 @@ async function fetchEntrypointHrefs(httpClient) {
784
864
  }
785
865
  /**
786
866
  * Stable query key used by useHydraMetadata.
787
- * Export this so that consumers (e.g. SmartCrudPage retry button) can
867
+ * Export this so that consumers (e.g. SchemaCrudPage retry button) can
788
868
  * invalidate exactly the right query without coupling to an internal string.
789
869
  */
790
870
  const API_DOC_QUERY_KEY = ["api-doc-discovery"];
@@ -833,13 +913,13 @@ function useHydraMetadata() {
833
913
  * SchemaContext — shared parsed schema, no per-page re-fetch.
834
914
  *
835
915
  * Provides a single shared `useHydraMetadata()` call at the provider level
836
- * so that multiple `SmartCrudPage` instances mounted simultaneously share
916
+ * so that multiple `SchemaCrudPage` instances mounted simultaneously share
837
917
  * one `/api/docs.jsonld` request instead of each issuing their own.
838
918
  *
839
919
  * ## Usage
840
920
  *
841
921
  * ```tsx
842
- * // In your app root (optional — SmartCrudPage still works without it):
922
+ * // In your app root (optional — SchemaCrudPage still works without it):
843
923
  * <SchemaProvider>
844
924
  * <App />
845
925
  * </SchemaProvider>
@@ -854,7 +934,7 @@ const OUTSIDE_PROVIDER = Symbol("OUTSIDE_PROVIDER");
854
934
  const SchemaContext = createContext(OUTSIDE_PROVIDER);
855
935
  /**
856
936
  * Wrap your app (or a subtree) with `SchemaProvider` to share a single
857
- * `/api/docs.jsonld` fetch across all `SmartCrudPage` instances.
937
+ * `/api/docs.jsonld` fetch across all `SchemaCrudPage` instances.
858
938
  */
859
939
  function SchemaProvider({ children }) {
860
940
  const metadata = useHydraMetadata();
@@ -867,7 +947,7 @@ function SchemaProvider({ children }) {
867
947
  * Returns the shared schema context if inside a `<SchemaProvider>`,
868
948
  * otherwise falls back to calling `useHydraMetadata()` directly.
869
949
  *
870
- * This makes `SmartCrudPage` work standalone without requiring a provider.
950
+ * This makes `SchemaCrudPage` work standalone without requiring a provider.
871
951
  */
872
952
  function useSchemaContext() {
873
953
  const ctx = useContext(SchemaContext);
@@ -891,13 +971,20 @@ function useSchemaContext() {
891
971
  * Normalizes an API URL by stripping any leading slash and query string so that
892
972
  * 'api/categories', '/api/categories', and '/api/categories?foo=bar' are treated as equal.
893
973
  */
894
- function normalizeUrl(url) {
974
+ function normalizeUrl$1(url) {
895
975
  const base = url.split("?")[0];
896
976
  return base.startsWith("/") ? base.slice(1) : base;
897
977
  }
898
- function useResourceSchema(apiUrl) {
978
+ function useResourceSchema(apiUrl, options) {
979
+ const enabled = options?.enabled !== false;
899
980
  const { data, isLoading, error } = useSchemaContext();
900
981
  return useMemo(() => {
982
+ if (!enabled) return {
983
+ fields: [],
984
+ isLoading: false,
985
+ error: void 0,
986
+ supportedOperations: []
987
+ };
901
988
  if (!data) return {
902
989
  fields: [],
903
990
  isLoading,
@@ -905,11 +992,11 @@ function useResourceSchema(apiUrl) {
905
992
  supportedOperations: []
906
993
  };
907
994
  const resourceMap = data.format === "hydra" ? parseHydraDoc(data.doc, data.entrypointHrefs) : parseOpenApiDoc(data.doc);
908
- const normalizedInput = normalizeUrl(apiUrl);
909
- 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);
910
997
  if (!resourceSchema) {
911
998
  const knownUrls = Object.values(resourceMap).map((r) => r.apiUrl).sort();
912
- 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, ""));
913
1000
  return {
914
1001
  fields: [],
915
1002
  isLoading: false,
@@ -925,10 +1012,12 @@ function useResourceSchema(apiUrl) {
925
1012
  formLayout: resourceSchema.formLayout,
926
1013
  workflow: resourceSchema.workflow,
927
1014
  sequence: resourceSchema.sequence,
928
- summaryFields: buildSummaryFieldsFromSchema(resourceSchema)
1015
+ summaryFields: buildSummaryFieldsFromSchema(resourceSchema),
1016
+ embeddedLines: resourceSchema.embeddedLines
929
1017
  };
930
1018
  }, [
931
1019
  data,
1020
+ enabled,
932
1021
  isLoading,
933
1022
  error,
934
1023
  apiUrl
@@ -936,8 +1025,8 @@ function useResourceSchema(apiUrl) {
936
1025
  }
937
1026
  //#endregion
938
1027
  //#region packages/hydra/HydraResourceSchemaProvider.tsx
939
- function useHydraResourceSchema({ apiUrl }) {
940
- return useResourceSchema(apiUrl);
1028
+ function useHydraResourceSchema({ apiUrl, enabled }) {
1029
+ return useResourceSchema(apiUrl, { enabled });
941
1030
  }
942
1031
  function HydraResourceSchemaProvider({ children }) {
943
1032
  return /* @__PURE__ */ jsx(ResourceSchemaProvider, {
@@ -946,4 +1035,75 @@ function HydraResourceSchemaProvider({ children }) {
946
1035
  });
947
1036
  }
948
1037
  //#endregion
949
- 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.29",
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/crud": "^0.5.29",
54
- "@nubitio/core": "^0.5.29"
53
+ "@nubitio/core": "^0.6.0",
54
+ "@nubitio/crud": "^0.6.0"
55
55
  }
56
56
  }