@mapomodule/form 2.0.0-beta.9 → 2.0.0-experimental.1

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.
Files changed (145) hide show
  1. package/README.md +38 -119
  2. package/dist/index.d.mts +2 -1
  3. package/dist/index.d.ts +3 -1
  4. package/dist/index.d.ts.map +1 -1
  5. package/dist/index.mjs +1 -0
  6. package/dist/module.d.mts +1 -0
  7. package/dist/module.d.ts.map +1 -1
  8. package/dist/module.json +1 -1
  9. package/dist/module.mjs +9 -0
  10. package/dist/runtime/components/MapoFocusPortal.vue +9 -2
  11. package/dist/runtime/components/MapoFocusPortal.vue.d.ts.map +1 -1
  12. package/dist/runtime/components/MapoForm.vue +28 -6
  13. package/dist/runtime/components/MapoForm.vue.d.ts +13 -1
  14. package/dist/runtime/components/MapoForm.vue.d.ts.map +1 -1
  15. package/dist/runtime/components/MapoFormAnnotation.vue +79 -0
  16. package/dist/runtime/components/MapoFormAnnotation.vue.d.ts +27 -0
  17. package/dist/runtime/components/MapoFormAnnotation.vue.d.ts.map +1 -0
  18. package/dist/runtime/components/MapoFormAnnotationBadges.vue +28 -0
  19. package/dist/runtime/components/MapoFormAnnotationBadges.vue.d.ts +13 -0
  20. package/dist/runtime/components/MapoFormAnnotationBadges.vue.d.ts.map +1 -0
  21. package/dist/runtime/components/MapoFormField.vue +47 -11
  22. package/dist/runtime/components/MapoFormField.vue.d.ts +15 -9
  23. package/dist/runtime/components/MapoFormField.vue.d.ts.map +1 -1
  24. package/dist/runtime/components/MapoFormGroup.vue +18 -2
  25. package/dist/runtime/components/MapoFormGroup.vue.d.ts.map +1 -1
  26. package/dist/runtime/components/MapoFormTabs.vue +50 -8
  27. package/dist/runtime/components/MapoFormTabs.vue.d.ts.map +1 -1
  28. package/dist/runtime/components/fields/MapoMediaField.vue +5 -3
  29. package/dist/runtime/components/fields/MapoMediaField.vue.d.ts.map +1 -1
  30. package/dist/runtime/components/fields/MapoMediaM2mField.vue +3 -2
  31. package/dist/runtime/components/fields/MapoMediaM2mField.vue.d.ts.map +1 -1
  32. package/dist/runtime/components/fields/MapoRepeater.vue +73 -14
  33. package/dist/runtime/components/fields/MapoRepeater.vue.d.ts.map +1 -1
  34. package/dist/runtime/components/fields/MapoRepeaterBlockPicker.vue +167 -0
  35. package/dist/runtime/components/fields/MapoRepeaterBlockPicker.vue.d.ts +20 -0
  36. package/dist/runtime/components/fields/MapoRepeaterBlockPicker.vue.d.ts.map +1 -0
  37. package/dist/runtime/components/fields/MapoRepeaterItem.vue +46 -10
  38. package/dist/runtime/components/fields/MapoRepeaterItem.vue.d.ts +6 -2
  39. package/dist/runtime/components/fields/MapoRepeaterItem.vue.d.ts.map +1 -1
  40. package/dist/runtime/components/fields/MapoWygEditor.vue +19 -13
  41. package/dist/runtime/components/fields/MapoWygEditor.vue.d.ts.map +1 -1
  42. package/dist/runtime/composables/useFieldAnnotation.d.ts +18 -0
  43. package/dist/runtime/composables/useFieldAnnotation.d.ts.map +1 -0
  44. package/dist/runtime/composables/useFieldAnnotation.js +16 -0
  45. package/dist/runtime/composables/useFocusMode.d.ts +3 -1
  46. package/dist/runtime/composables/useFocusMode.d.ts.map +1 -1
  47. package/dist/runtime/composables/useFormFromSchema.d.ts +23 -1
  48. package/dist/runtime/composables/useFormFromSchema.d.ts.map +1 -1
  49. package/dist/runtime/composables/useFormFromSchema.js +171 -32
  50. package/dist/runtime/composables/useMapoForm.d.ts +21 -3
  51. package/dist/runtime/composables/useMapoForm.d.ts.map +1 -1
  52. package/dist/runtime/composables/useMapoForm.js +49 -15
  53. package/dist/runtime/types/annotation.d.ts +43 -0
  54. package/dist/runtime/types/annotation.d.ts.map +1 -0
  55. package/dist/runtime/types/annotation.js +0 -0
  56. package/dist/runtime/types/descriptor.d.ts +81 -4
  57. package/dist/runtime/types/descriptor.d.ts.map +1 -1
  58. package/dist/runtime/types/index.d.ts +2 -1
  59. package/dist/runtime/types/index.d.ts.map +1 -1
  60. package/dist/runtime/utils/annotations.d.ts +40 -0
  61. package/dist/runtime/utils/annotations.d.ts.map +1 -0
  62. package/dist/runtime/utils/annotations.js +78 -0
  63. package/dist/runtime/utils/draft.d.ts +21 -0
  64. package/dist/runtime/utils/draft.d.ts.map +1 -0
  65. package/dist/runtime/utils/draft.js +108 -0
  66. package/dist/runtime/utils/fieldComponent.d.ts +9 -0
  67. package/dist/runtime/utils/fieldComponent.d.ts.map +1 -0
  68. package/dist/runtime/utils/fieldComponent.js +12 -0
  69. package/dist/runtime/utils/fieldFocus.d.ts +24 -0
  70. package/dist/runtime/utils/fieldFocus.d.ts.map +1 -0
  71. package/dist/runtime/utils/fieldFocus.js +41 -0
  72. package/dist/runtime/utils/fieldsToJsonSchema.d.ts +38 -0
  73. package/dist/runtime/utils/fieldsToJsonSchema.d.ts.map +1 -0
  74. package/dist/runtime/utils/fieldsToJsonSchema.js +248 -0
  75. package/dist/runtime/utils/repeaterTemplates.d.ts +26 -0
  76. package/dist/runtime/utils/repeaterTemplates.d.ts.map +1 -0
  77. package/dist/runtime/utils/repeaterTemplates.js +51 -0
  78. package/dist/runtime/utils/reveal.d.ts +34 -0
  79. package/dist/runtime/utils/reveal.d.ts.map +1 -0
  80. package/dist/runtime/utils/reveal.js +29 -0
  81. package/dist/runtime/utils/tabVisibility.d.ts +18 -0
  82. package/dist/runtime/utils/tabVisibility.d.ts.map +1 -0
  83. package/dist/runtime/utils/tabVisibility.js +18 -0
  84. package/package.json +5 -5
  85. package/src/__tests__/MapoFocusPortal.component.test.ts +97 -0
  86. package/src/__tests__/MapoForm.component.test.ts +79 -0
  87. package/src/__tests__/MapoFormAnnotation.component.test.ts +244 -0
  88. package/src/__tests__/MapoFormField.component.test.ts +508 -0
  89. package/src/__tests__/MapoFormGroup.component.test.ts +141 -0
  90. package/src/__tests__/MapoFormTabs.component.test.ts +254 -0
  91. package/src/__tests__/MapoRepeaterItem.component.test.ts +286 -0
  92. package/src/__tests__/MapoWygEditor.component.test.ts +95 -0
  93. package/src/__tests__/annotations.test.ts +227 -0
  94. package/src/__tests__/draft.test.ts +221 -0
  95. package/src/__tests__/fieldComponent.test.ts +31 -0
  96. package/src/__tests__/fieldExtensions.test.ts +63 -0
  97. package/src/__tests__/fieldFocus.test.ts +178 -0
  98. package/src/__tests__/fieldsToJsonSchema.test.ts +630 -0
  99. package/src/__tests__/headlessRenderer.ts +85 -0
  100. package/src/__tests__/repeaterTemplates.test.ts +154 -0
  101. package/src/__tests__/reveal.test.ts +89 -0
  102. package/src/__tests__/schemaSources.test.ts +132 -0
  103. package/src/__tests__/tabVisibility.test.ts +102 -0
  104. package/src/__tests__/useFormFromSchema.test.ts +387 -0
  105. package/src/__tests__/useMapoForm.test.ts +213 -2
  106. package/src/index.ts +9 -0
  107. package/src/module.ts +9 -0
  108. package/src/runtime/components/MapoFocusPortal.vue +15 -2
  109. package/src/runtime/components/MapoForm.vue +47 -4
  110. package/src/runtime/components/MapoFormAnnotation.vue +113 -0
  111. package/src/runtime/components/MapoFormAnnotationBadges.vue +41 -0
  112. package/src/runtime/components/MapoFormField.vue +72 -11
  113. package/src/runtime/components/MapoFormGroup.vue +20 -2
  114. package/src/runtime/components/MapoFormTabs.vue +64 -8
  115. package/src/runtime/components/fields/MapoMediaField.vue +5 -3
  116. package/src/runtime/components/fields/MapoMediaM2mField.vue +3 -2
  117. package/src/runtime/components/fields/MapoRepeater.vue +82 -14
  118. package/src/runtime/components/fields/MapoRepeaterBlockPicker.vue +188 -0
  119. package/src/runtime/components/fields/MapoRepeaterItem.vue +56 -8
  120. package/src/runtime/components/fields/MapoWygEditor.vue +22 -14
  121. package/src/runtime/composables/useFieldAnnotation.ts +38 -0
  122. package/src/runtime/composables/useFocusMode.ts +7 -1
  123. package/src/runtime/composables/useFormFromSchema.ts +303 -41
  124. package/src/runtime/composables/useMapoForm.ts +103 -23
  125. package/src/runtime/types/annotation.ts +53 -0
  126. package/src/runtime/types/descriptor.ts +94 -4
  127. package/src/runtime/types/index.ts +10 -0
  128. package/src/runtime/utils/annotations.ts +169 -0
  129. package/src/runtime/utils/draft.ts +158 -0
  130. package/src/runtime/utils/fieldComponent.ts +34 -0
  131. package/src/runtime/utils/fieldFocus.ts +73 -0
  132. package/src/runtime/utils/fieldsToJsonSchema.ts +405 -0
  133. package/src/runtime/utils/repeaterTemplates.ts +103 -0
  134. package/src/runtime/utils/reveal.ts +68 -0
  135. package/src/runtime/utils/tabVisibility.ts +44 -0
  136. package/dist/__tests__/__mocks__/nuxt-imports.d.ts +0 -4
  137. package/dist/__tests__/__mocks__/nuxt-imports.d.ts.map +0 -1
  138. package/dist/__tests__/camomillaRoundTrip.test.d.ts +0 -2
  139. package/dist/__tests__/camomillaRoundTrip.test.d.ts.map +0 -1
  140. package/dist/__tests__/registry.test.d.ts +0 -2
  141. package/dist/__tests__/registry.test.d.ts.map +0 -1
  142. package/dist/__tests__/useFormFromSchema.test.d.ts +0 -2
  143. package/dist/__tests__/useFormFromSchema.test.d.ts.map +0 -1
  144. package/dist/__tests__/useMapoForm.test.d.ts +0 -2
  145. package/dist/__tests__/useMapoForm.test.d.ts.map +0 -1
@@ -1,7 +1,94 @@
1
- import { resolveSchema, extractDefs, matchesSchema } from "@mapomodule/utils";
1
+ import {
2
+ ATTRS_KEYWORD,
3
+ FIELD_KEYWORD,
4
+ resolveSchema,
5
+ extractDefs,
6
+ matchesSchema
7
+ } from "@mapomodule/utils";
8
+ export const TEMPLATE_PROPERTY = "_template";
9
+ export const KEYWORD_ATTRS = {
10
+ number: { min: "minimum", max: "maximum" },
11
+ slider: { min: "minimum", max: "maximum" },
12
+ text: { minLength: "minLength", maxLength: "maxLength" },
13
+ textarea: { minLength: "minLength", maxLength: "maxLength" },
14
+ email: { minLength: "minLength", maxLength: "maxLength" },
15
+ url: { minLength: "minLength", maxLength: "maxLength" },
16
+ repeater: { minItems: "minItems", maxItems: "maxItems" },
17
+ "media-m2m": { minItems: "minItems", maxItems: "maxItems" }
18
+ };
19
+ export function isUnsafeAttr(name) {
20
+ return /^on/i.test(name) || /^(innerhtml|outerhtml|innertext|textcontent|srcdoc|formaction)$/i.test(
21
+ name
22
+ );
23
+ }
24
+ const ENUM_LABELS = "_enumLabels";
25
+ const ENUM_EXTRAS = "_enumExtras";
26
+ function isRecord(value) {
27
+ return typeof value === "object" && value !== null && !Array.isArray(value);
28
+ }
29
+ function safeEntries(record) {
30
+ return Object.fromEntries(
31
+ Object.entries(record).filter(([name]) => !isUnsafeAttr(name))
32
+ );
33
+ }
34
+ function jsonType(schema) {
35
+ return Array.isArray(schema.type) ? schema.type.find((v) => v !== "null") : schema.type;
36
+ }
37
+ function withLabeledChoices(schema) {
38
+ const union = schema.oneOf ?? schema.anyOf;
39
+ if (!union) return schema;
40
+ const choices = union.filter(
41
+ (branch) => isRecord(branch) && branch.type !== "null"
42
+ );
43
+ const isChoiceList = choices.length > 0 && choices.every((branch) => "const" in branch);
44
+ if (!isChoiceList) return schema;
45
+ const { oneOf: _oneOf, anyOf: _anyOf, ...rest } = schema;
46
+ const nullable = choices.length < union.length;
47
+ return {
48
+ ...rest,
49
+ enum: choices.map((branch) => branch.const),
50
+ [ENUM_LABELS]: choices.map(
51
+ (branch) => branch.title ?? String(branch.const)
52
+ ),
53
+ [ENUM_EXTRAS]: choices.map((branch) => branch[ATTRS_KEYWORD]),
54
+ ...nullable ? { _nullable: true } : {}
55
+ };
56
+ }
57
+ function defName(ref) {
58
+ return ref.replace(/^#\/\$defs\//, "").replace(/^#\/definitions\//, "");
59
+ }
60
+ function refsOf(schema) {
61
+ if (!isRecord(schema)) return [];
62
+ const branches = [
63
+ schema,
64
+ ...Array.isArray(schema.anyOf) ? schema.anyOf : [],
65
+ ...Array.isArray(schema.oneOf) ? schema.oneOf : []
66
+ ];
67
+ return branches.flatMap(
68
+ (branch) => isRecord(branch) && typeof branch.$ref === "string" ? [defName(branch.$ref)] : []
69
+ );
70
+ }
71
+ function resolveProperty(raw, defs) {
72
+ if (!isRecord(raw)) return { schema: {}, refs: [] };
73
+ const schema = resolveSchema(withLabeledChoices(raw), defs);
74
+ const items = schema.items;
75
+ if (!isRecord(items)) return { schema, refs: refsOf(raw) };
76
+ return {
77
+ schema: {
78
+ ...schema,
79
+ items: resolveSchema(withLabeledChoices(items), defs)
80
+ },
81
+ refs: [...refsOf(raw), ...refsOf(items)]
82
+ };
83
+ }
84
+ function isTemplateItems(items) {
85
+ return !!items?.oneOf && items.discriminator?.propertyName === TEMPLATE_PROPERTY;
86
+ }
2
87
  function mapType(schema, key) {
88
+ const marked = schema[FIELD_KEYWORD];
89
+ if (typeof marked === "string" && marked) return marked;
3
90
  if (schema.enum) return "select";
4
- const t = Array.isArray(schema.type) ? schema.type.find((v) => v !== "null") : schema.type;
91
+ const t = jsonType(schema);
5
92
  const fmt = schema.format;
6
93
  if (t === "string") {
7
94
  if (fmt === "textarea") return "textarea";
@@ -9,6 +96,10 @@ function mapType(schema, key) {
9
96
  if (fmt === "date-time") return "datetime";
10
97
  if (fmt === "time") return "time";
11
98
  if (fmt === "color") return "color";
99
+ if (fmt === "email") return "email";
100
+ if (fmt === "uri" || fmt === "url") return "url";
101
+ if (fmt === "binary") return "file";
102
+ if (schema.contentMediaType === "text/html") return "editor";
12
103
  if (typeof schema.maxLength === "number" && schema.maxLength > 255)
13
104
  return "textarea";
14
105
  return "text";
@@ -21,45 +112,58 @@ function mapType(schema, key) {
21
112
  if (t === "array") {
22
113
  const items = schema.items;
23
114
  if (items?.type === "relation") return "m2m";
115
+ if (isTemplateItems(items)) return "repeater";
24
116
  if (items?.type === "object" || items?.properties) return "repeater";
25
117
  return "select";
26
118
  }
27
119
  if (t === "object") {
28
120
  const props = Object.keys(schema.properties ?? {});
29
- if (props.includes("title") && props.includes("description") && (props.includes("url") || props.includes("slug")))
121
+ if (props.includes("title") && props.includes("description") && (props.includes("url") || props.includes("slug") || props.includes("permalink")))
30
122
  return "seo";
31
123
  return `object:${key}`;
32
124
  }
33
125
  return "text";
34
126
  }
127
+ export function schemaFieldType(schema, key) {
128
+ return mapType(resolveProperty(schema, {}).schema, key);
129
+ }
130
+ function selectAttrs(schema) {
131
+ const isArray = jsonType(schema) === "array";
132
+ const choices = isArray ? schema.items : schema;
133
+ const values = isRecord(choices) ? choices.enum : void 0;
134
+ const labels = choices?.[ENUM_LABELS];
135
+ const extras = choices?.[ENUM_EXTRAS];
136
+ return {
137
+ ...values ? {
138
+ options: values.map((value, index) => {
139
+ const extra = extras?.[index];
140
+ return {
141
+ ...isRecord(extra) ? safeEntries(extra) : {},
142
+ text: labels?.[index] ?? String(value),
143
+ value
144
+ };
145
+ })
146
+ } : {},
147
+ ...isArray ? { multiple: true } : {}
148
+ };
149
+ }
35
150
  function buildAttrs(schema, type) {
36
- const attrs = {};
37
- if (type === "select") {
38
- if (schema.enum) {
39
- attrs.options = schema.enum.map((v) => ({
40
- text: String(v),
41
- value: v
42
- }));
43
- }
44
- }
45
- if (type === "number") {
46
- if (schema.minimum !== void 0) attrs.min = schema.minimum;
47
- if (schema.maximum !== void 0) attrs.max = schema.maximum;
48
- }
49
- if (type === "text" || type === "textarea") {
50
- if (schema.maxLength !== void 0) attrs.maxLength = schema.maxLength;
51
- if (schema.minLength !== void 0) attrs.minLength = schema.minLength;
151
+ const attrs = type === "select" ? selectAttrs(schema) : {};
152
+ for (const [attr, keyword] of Object.entries(KEYWORD_ATTRS[type] ?? {})) {
153
+ if (schema[keyword] !== void 0) attrs[attr] = schema[keyword];
52
154
  }
53
155
  if (type === "fks" || type === "m2m") {
54
156
  const ext = schema;
55
157
  attrs.endpoint = ext.endpoint ?? ext.relation ?? "";
56
158
  attrs.returnObject = true;
57
- if (type === "m2m") attrs.multiple = true;
159
+ if (type === "m2m" || ext.multiple === true) attrs.multiple = true;
58
160
  }
59
161
  if (type === "date" || type === "datetime") {
60
162
  if (schema.minimum) attrs.min = schema.minimum;
61
163
  if (schema.maximum) attrs.max = schema.maximum;
62
164
  }
165
+ const own = schema[ATTRS_KEYWORD];
166
+ if (isRecord(own)) Object.assign(attrs, safeEntries(own));
63
167
  return attrs;
64
168
  }
65
169
  function collectRules(schema) {
@@ -85,8 +189,35 @@ function makeVisible(ifSchema, side) {
85
189
  return side === "then" ? matches : !matches;
86
190
  };
87
191
  }
88
- function propertyToDescriptor(key, rawSchema, defs, requiredKeys, rules) {
89
- const schema = resolveSchema(rawSchema, defs);
192
+ function objectDescriptors(schema, defs, chain, skip) {
193
+ const required = new Set(schema.required ?? []);
194
+ const rules = collectRules(schema);
195
+ return Object.entries(schema.properties ?? {}).filter(([key]) => key !== skip).map(
196
+ ([key, value]) => propertyToDescriptor(key, value, defs, required, rules, chain)
197
+ );
198
+ }
199
+ function templatesOf(items, defs, chain) {
200
+ const templates = {};
201
+ for (const raw of items.oneOf ?? []) {
202
+ if (!isRecord(raw)) continue;
203
+ const branch = resolveSchema(raw, defs);
204
+ const key = branch.properties?.[TEMPLATE_PROPERTY]?.const;
205
+ if (typeof key !== "string") continue;
206
+ const inner = /* @__PURE__ */ new Set([...chain, ...refsOf(raw)]);
207
+ const fields = objectDescriptors(branch, defs, inner, TEMPLATE_PROPERTY);
208
+ const own = branch[ATTRS_KEYWORD];
209
+ const presentation = isRecord(own) ? safeEntries(own) : {};
210
+ const meta = {
211
+ ...branch.title ? { label: branch.title } : {},
212
+ ...typeof branch.description === "string" ? { description: branch.description } : {},
213
+ ...presentation
214
+ };
215
+ templates[key] = Object.keys(meta).length ? { ...meta, fields } : fields;
216
+ }
217
+ return templates;
218
+ }
219
+ function propertyToDescriptor(key, rawSchema, defs, requiredKeys, rules, chain) {
220
+ const { schema, refs } = resolveProperty(rawSchema, defs);
90
221
  const type = mapType(schema, key);
91
222
  const attrs = buildAttrs(schema, type);
92
223
  let visible;
@@ -100,29 +231,36 @@ function propertyToDescriptor(key, rawSchema, defs, requiredKeys, rules) {
100
231
  break;
101
232
  }
102
233
  }
234
+ const items = type === "repeater" ? schema.items : void 0;
235
+ const isCycle = refs.some((name) => chain.has(name));
236
+ const inner = /* @__PURE__ */ new Set([...chain, ...refs]);
237
+ const hasTemplates = !!items && isTemplateItems(items) && !isCycle;
238
+ if (hasTemplates) attrs.templates = templatesOf(items, defs, inner);
103
239
  const base = {
104
240
  key,
105
241
  type,
106
242
  label: schema.title ?? void 0,
107
243
  required: requiredKeys.has(key),
108
244
  ...schema.readOnly ? { readonly: true } : {},
245
+ // A value the backend never returns, such as a password: keep it out of drafts.
246
+ ...schema.writeOnly ? { noDraft: true } : {},
247
+ ...schema.translatable ? { translatable: true } : {},
109
248
  ...visible ? { visible } : {},
110
249
  ...Object.keys(attrs).length ? { attrs } : {}
111
250
  };
112
- if (type === "repeater" && schema.items) {
113
- const itemSchema = resolveSchema(schema.items, defs);
114
- const childRequired = new Set(itemSchema.required ?? []);
115
- const childProps = itemSchema.properties ?? {};
116
- const childRules = collectRules(itemSchema);
117
- base.fields = Object.entries(childProps).map(
118
- ([k, v]) => propertyToDescriptor(k, v, defs, childRequired, childRules)
119
- );
251
+ if (items && !hasTemplates) {
252
+ base.fields = isCycle ? [] : objectDescriptors(items, defs, inner);
120
253
  }
121
254
  return base;
122
255
  }
123
256
  export function useFormFromSchema(schema, options = {}) {
124
257
  const { exclude = [], overrides = {} } = options;
125
- const defs = extractDefs(schema);
258
+ const defs = Object.fromEntries(
259
+ Object.entries(extractDefs(schema)).map(([name, def]) => [
260
+ name,
261
+ isRecord(def) ? withLabeledChoices(def) : def
262
+ ])
263
+ );
126
264
  const properties = schema.properties ?? {};
127
265
  const requiredKeys = new Set(schema.required ?? []);
128
266
  const rules = collectRules(schema);
@@ -134,7 +272,8 @@ export function useFormFromSchema(schema, options = {}) {
134
272
  rawProp,
135
273
  defs,
136
274
  requiredKeys,
137
- rules
275
+ rules,
276
+ /* @__PURE__ */ new Set()
138
277
  );
139
278
  const override = overrides[key];
140
279
  const final = override ? { ...descriptor, ...override } : descriptor;
@@ -1,5 +1,6 @@
1
1
  import { type Ref, type MaybeRef } from "vue";
2
- import type { AnyFieldDescriptor, FieldRegistry } from "../types/index.js";
2
+ import type { AnyFieldDescriptor, FieldAnnotations, FieldRegistry } from "../types/index.js";
3
+ import type { FieldRevealRequest } from "../utils/reveal.js";
3
4
  /** Options accepted by `useMapoForm()`. */
4
5
  export interface UseMapoFormOptions<T extends object> {
5
6
  model: Ref<T>;
@@ -19,11 +20,19 @@ export interface UseMapoFormOptions<T extends object> {
19
20
  registry: FieldRegistry;
20
21
  /**
21
22
  * When set, enables automatic draft persistence to localStorage.
22
- * Key is prefixed with `mapo:draft:`. Drafts expire after 24 h.
23
+ * Key is prefixed with `mapo:draft:` and the signed-in user's id, so
24
+ * accounts on one browser never share a draft. Drafts expire after 24 h,
25
+ * and the fields marked `noDraft` are left out of them.
23
26
  * Call the returned `checkDraft()` after the model is populated to offer restore.
24
- * Example: `"article:42"` → `mapo:draft:article:42`.
27
+ * Example: `"article:42"` → `mapo:draft:1:article:42` for the user with id `1`.
25
28
  */
26
29
  draftKey?: MaybeRef<string | undefined>;
30
+ /**
31
+ * Marks shown next to the labels of the fields, keyed by the path of the
32
+ * value (`title`, `translations.it.title`, `blocks.0.title`). Changing the
33
+ * map updates the marks without remounting the fields.
34
+ */
35
+ annotations?: MaybeRef<FieldAnnotations | undefined>;
27
36
  }
28
37
  /** State exposed when a pending draft is found in localStorage. */
29
38
  export interface MapoDraftBanner {
@@ -47,6 +56,14 @@ export interface MapoFormContext<T extends object> {
47
56
  markTouched: (key: string) => void;
48
57
  isTouched: (key: string) => boolean;
49
58
  submitted: Ref<boolean>;
59
+ /** Optional, so a context built by hand without marks keeps working. */
60
+ annotations?: Readonly<Ref<FieldAnnotations>>;
61
+ /**
62
+ * The field `revealField()` brings into view, while it does: the tab, the
63
+ * group and the repeater item that hold it open, and the field focuses
64
+ * its control. Optional, as `annotations`.
65
+ */
66
+ reveal?: Readonly<Ref<FieldRevealRequest | undefined>>;
50
67
  }
51
68
  /** Injection key for the current Mapo form context. */
52
69
  export declare const FORM_KEY: unique symbol;
@@ -80,6 +97,7 @@ export declare function useMapoForm<T extends object>(options: UseMapoFormOption
80
97
  resetDirty: () => void;
81
98
  getPatch: () => Partial<T>;
82
99
  submit: (handler: (model: T | Partial<T>, isNew: boolean) => Promise<void>, isNew?: boolean) => Promise<void>;
100
+ revealField: (path: string) => Promise<boolean>;
83
101
  ctx: MapoFormContext<T>;
84
102
  draftBanner: Ref<{
85
103
  savedAt: Date;
@@ -1 +1 @@
1
- {"version":3,"file":"useMapoForm.d.ts","sourceRoot":"","sources":["../../../src/runtime/composables/useMapoForm.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"useMapoForm.d.ts","sourceRoot":"","sources":["../../../src/runtime/composables/useMapoForm.ts"],"names":[],"mappings":"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"}
@@ -1,9 +1,12 @@
1
1
  import {
2
2
  ref,
3
+ shallowRef,
3
4
  computed,
4
5
  toRaw,
5
6
  toValue,
6
7
  watch,
8
+ getCurrentScope,
9
+ onScopeDispose,
7
10
  provide,
8
11
  inject
9
12
  } from "vue";
@@ -14,6 +17,10 @@ import {
14
17
  debounce
15
18
  } from "@mapomodule/utils";
16
19
  import { resolveFieldAccessor } from "../types/index.js";
20
+ import { valuePath } from "../utils/annotations.js";
21
+ import { modelForDraft } from "../utils/draft.js";
22
+ import { fieldAtPath } from "../utils/reveal.js";
23
+ import { isFieldShown } from "../utils/tabVisibility.js";
17
24
  import { useCurrentLang } from "./useCurrentLang.js";
18
25
  import { useSnackStore } from "@mapomodule/store/runtime/stores/snack";
19
26
  import { useMapoT } from "@mapomodule/i18n/runtime/composables/useMapoT";
@@ -29,6 +36,7 @@ function safeClone(v) {
29
36
  return JSON.parse(JSON.stringify(raw));
30
37
  }
31
38
  export const FORM_KEY = Symbol("mapoForm");
39
+ const REVEAL_TIMEOUT_MS = 3e3;
32
40
  function provideMapoForm(ctx) {
33
41
  provide(FORM_KEY, ctx);
34
42
  }
@@ -63,7 +71,10 @@ export function useMapoForm(options) {
63
71
  (val) => {
64
72
  const entries = Object.entries(val);
65
73
  if (!entries.length) return;
66
- const lines = entries.map(([field, msgs]) => `${field}: ${msgs.join(", ")}`).join("\n");
74
+ const lines = entries.map(([field, msgs]) => {
75
+ const label = toValue(fields).find((descriptor) => descriptor.key === field)?.label || field;
76
+ return `${label}: ${msgs.join(", ")}`;
77
+ }).join("\n");
67
78
  snack.show(lines, "error");
68
79
  },
69
80
  { deep: true }
@@ -115,16 +126,10 @@ export function useMapoForm(options) {
115
126
  const key = _draftStorageKey();
116
127
  if (!key || !isDirty.value || typeof localStorage === "undefined") return;
117
128
  try {
118
- const noDraftKeys = new Set(
119
- toValue(fields).filter((f) => f.noDraft).map((f) => f.key)
120
- );
121
- const snapshot = toRaw(model.value);
122
- const filtered = noDraftKeys.size > 0 ? Object.fromEntries(
123
- Object.entries(snapshot).filter(([k]) => !noDraftKeys.has(k))
124
- ) : snapshot;
129
+ const values = modelForDraft(toRaw(model.value), toValue(fields));
125
130
  localStorage.setItem(
126
131
  key,
127
- JSON.stringify({ model: filtered, savedAt: Date.now() })
132
+ JSON.stringify({ model: values, savedAt: Date.now() })
128
133
  );
129
134
  } catch {
130
135
  }
@@ -147,11 +152,7 @@ export function useMapoForm(options) {
147
152
  return merged;
148
153
  });
149
154
  function resolvePath(descriptor) {
150
- const lang = currentLang.value;
151
- if (descriptor.translatable && lang) {
152
- return `translations.${lang}.${descriptor.key}`;
153
- }
154
- return descriptor.key;
155
+ return valuePath(descriptor, currentLang.value);
155
156
  }
156
157
  function initLang(lang) {
157
158
  const m = model.value;
@@ -258,6 +259,36 @@ export function useMapoForm(options) {
258
259
  return map;
259
260
  });
260
261
  const findDescriptor = (key) => fieldIndex.value.get(key);
262
+ const reveal = shallowRef();
263
+ function revealField(path) {
264
+ reveal.value?.settle(false);
265
+ const located = fieldAtPath(
266
+ toValue(fields),
267
+ path,
268
+ currentLang.value
269
+ );
270
+ const isShown = located ? isFieldShown(located.field, model.value) : false;
271
+ if (!located || !isShown) return Promise.resolve(false);
272
+ return new Promise((resolve) => {
273
+ let isSettled = false;
274
+ const request = {
275
+ path,
276
+ key: located.field.key,
277
+ rest: located.rest,
278
+ // Called only once the request is out, after the timer below.
279
+ settle: (focused) => {
280
+ if (isSettled) return;
281
+ isSettled = true;
282
+ clearTimeout(timer);
283
+ if (reveal.value === request) reveal.value = void 0;
284
+ resolve(focused);
285
+ }
286
+ };
287
+ const timer = setTimeout(() => request.settle(false), REVEAL_TIMEOUT_MS);
288
+ reveal.value = request;
289
+ });
290
+ }
291
+ if (getCurrentScope()) onScopeDispose(() => reveal.value?.settle(false));
261
292
  const ctx = {
262
293
  model,
263
294
  fields,
@@ -278,7 +309,9 @@ export function useMapoForm(options) {
278
309
  },
279
310
  markTouched,
280
311
  isTouched,
281
- submitted
312
+ submitted,
313
+ annotations: computed(() => toValue(options.annotations) ?? {}),
314
+ reveal
282
315
  };
283
316
  function setFieldValuePublic(keyOrDescriptor, val) {
284
317
  if (typeof keyOrDescriptor === "string") {
@@ -317,6 +350,7 @@ export function useMapoForm(options) {
317
350
  resetDirty,
318
351
  getPatch,
319
352
  submit,
353
+ revealField,
320
354
  ctx,
321
355
  draftBanner,
322
356
  checkDraft,
@@ -0,0 +1,43 @@
1
+ /**
2
+ * A Nuxt UI color: one of the built-in semantic colors, or a color the app
3
+ * registers in its theme (`ui.theme.colors`).
4
+ */
5
+ export type FieldAnnotationColor = "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | (string & {});
6
+ /** A button in the popover of a field annotation. */
7
+ export interface FieldAnnotationAction {
8
+ /** Button text. */
9
+ label: string;
10
+ /** Iconify name shown before the text, e.g. `i-lucide-check`. */
11
+ icon?: string;
12
+ /** Button color. Default: `neutral`. */
13
+ color?: FieldAnnotationColor;
14
+ /** Runs when the button is clicked. */
15
+ onClick: () => void;
16
+ }
17
+ /**
18
+ * A mark that decorates a field from outside its descriptor: an icon next to the
19
+ * label that opens a popover, and a count on the tab that holds the field.
20
+ */
21
+ export interface FieldAnnotation {
22
+ /**
23
+ * Short text: the accessible name of the mark and the title of its popover,
24
+ * e.g. "Suggested by AI".
25
+ */
26
+ label: string;
27
+ /** Iconify name of the mark. Default: `i-lucide-info`. */
28
+ icon?: string;
29
+ /** Color of the mark and of its tab count. Default: `neutral`. */
30
+ color?: FieldAnnotationColor;
31
+ /** Adds a dot to the mark, to ask for attention without another icon. */
32
+ dot?: boolean;
33
+ /** Longer text in the popover, under the title. */
34
+ description?: string;
35
+ /** Buttons at the bottom of the popover. */
36
+ actions?: readonly FieldAnnotationAction[];
37
+ }
38
+ /**
39
+ * Annotations keyed by the path of the field's value, the same paths as the
40
+ * server errors: `title`, `translations.it.title`, `blocks.0.title`.
41
+ */
42
+ export type FieldAnnotations = Record<string, FieldAnnotation>;
43
+ //# sourceMappingURL=annotation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"annotation.d.ts","sourceRoot":"","sources":["../../../src/runtime/types/annotation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,WAAW,GACX,SAAS,GACT,MAAM,GACN,SAAS,GACT,OAAO,GACP,SAAS,GACT,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACpC,mBAAmB;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,uCAAuC;IACvC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,yEAAyE;IACzE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC5C;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC"}
File without changes
@@ -61,11 +61,34 @@ export interface FieldAccessor<TValue = unknown, TModel = unknown> {
61
61
  lang?: string;
62
62
  }) => TValue;
63
63
  }
64
+ /**
65
+ * Properties that packages and apps add to every field descriptor, with type
66
+ * checking. The form engine never reads them: whoever declares a property reads
67
+ * it, for example a custom field or the `property` option of
68
+ * `fieldsToJsonSchema()`.
69
+ *
70
+ * Declare a property by augmenting this interface. Keep it optional, and give it
71
+ * a name of your own so it cannot clash with a descriptor property.
72
+ *
73
+ * @example
74
+ * // In an app: a .d.ts file the app's tsconfig includes
75
+ * declare module "mapomodule/types" {
76
+ * interface FieldExtensions {
77
+ * help?: string;
78
+ * }
79
+ * }
80
+ *
81
+ * // Makes the file a module, so the block above adds to Mapo's types
82
+ * // instead of replacing them.
83
+ * export {};
84
+ */
85
+ export interface FieldExtensions {
86
+ }
64
87
  /**
65
88
  * Common properties shared by every field descriptor.
66
89
  * All concrete descriptor types extend this interface.
67
90
  */
68
- interface FieldBase<T> {
91
+ interface FieldBase<T> extends FieldExtensions {
69
92
  /** Model key. Accepts a direct `keyof T` or a dotted path up to 4 levels deep (e.g. `"data.hero.title"`). */
70
93
  key: DeepKeyOf<T>;
71
94
  /** Human-readable label displayed above the field. */
@@ -165,8 +188,11 @@ interface FieldBase<T> {
165
188
  /** Direct component override. Takes priority over `registry.mapping[type]`. */
166
189
  is?: Component;
167
190
  /**
168
- * When `true`, this field's value is excluded from draft snapshots saved to localStorage.
191
+ * When `true`, this field's value is excluded from draft snapshots saved to localStorage,
192
+ * wherever it is: at its key (a dotted key included), in every language for a
193
+ * translatable or `synci18n` field, and in each item of a repeater that declares it.
169
194
  * Use for sensitive fields (passwords, API keys, tokens) that should never be persisted client-side.
195
+ * A value that an `accessor` writes at another path is not reached: mark that field too.
170
196
  */
171
197
  noDraft?: boolean;
172
198
  }
@@ -277,6 +303,42 @@ export interface MapDescriptor<T = Record<string, unknown>> extends FieldBase<T>
277
303
  zoom?: number;
278
304
  };
279
305
  }
306
+ /**
307
+ * How a template's preview `image` fits its picker card: the CSS `object-fit` values.
308
+ * `contain` shows the whole image, `cover` fills the card and crops the edges.
309
+ */
310
+ export type RepeaterImageFit = "contain" | "cover" | "fill" | "none" | "scale-down";
311
+ /**
312
+ * A repeater block template with presentation metadata.
313
+ * Use it instead of a bare field array to describe the block in the picker.
314
+ */
315
+ export interface RepeaterTemplate {
316
+ /** Field descriptors of the block. */
317
+ fields: AnyFieldDescriptor[];
318
+ /** Human-readable name. Defaults to the template key. */
319
+ label?: string;
320
+ /** Short explanation of what the block is for. */
321
+ description?: string;
322
+ /** Iconify name (e.g. `i-lucide-image`). Used as the preview fallback and in the item header. */
323
+ icon?: string;
324
+ /** Preview image URL, shown in the picker card. Takes precedence over `wireframe` and `icon`. */
325
+ image?: string;
326
+ /**
327
+ * How `image` fits the picker card (CSS `object-fit`). Default: the repeater's
328
+ * `attrs.templateImageFit`, else `contain`, which shows the whole image.
329
+ */
330
+ imageFit?: RepeaterImageFit;
331
+ /** Draw a schematic preview generated from the template fields (used when there is no `image`). */
332
+ wireframe?: boolean;
333
+ /** Group name: the picker shows one filter chip per category. */
334
+ category?: string;
335
+ }
336
+ /** A {@link RepeaterTemplate} normalized for display, with its key and defaults applied. @internal */
337
+ export interface NormalizedRepeaterTemplate extends Omit<RepeaterTemplate, "label" | "imageFit"> {
338
+ key: string;
339
+ label: string;
340
+ imageFit: RepeaterImageFit;
341
+ }
280
342
  /** Descriptor for a drag-and-drop repeater with nested field descriptors. */
281
343
  export interface RepeaterDescriptor<T = Record<string, unknown>> extends FieldBase<T> {
282
344
  type: `${KnownFieldType.Repeater}`;
@@ -286,8 +348,23 @@ export interface RepeaterDescriptor<T = Record<string, unknown>> extends FieldBa
286
348
  */
287
349
  fields?: AnyFieldDescriptor[];
288
350
  attrs?: {
289
- /** Multiple templates for heterogeneous items (`oneOf` discriminated union). */
290
- templates?: Record<string, AnyFieldDescriptor[]>;
351
+ /**
352
+ * Multiple templates for heterogeneous items (`oneOf` discriminated union).
353
+ * A value is either a bare field array or a {@link RepeaterTemplate} with label,
354
+ * description, icon, preview image and category.
355
+ */
356
+ templates?: Record<string, AnyFieldDescriptor[] | RepeaterTemplate>;
357
+ /**
358
+ * How the user chooses a template when adding an item: `select` (dropdown),
359
+ * `modal` (card gallery with search) or `auto`. Default: `auto`, which uses the
360
+ * modal when there are more than 3 templates.
361
+ */
362
+ picker?: "auto" | "select" | "modal";
363
+ /**
364
+ * How the templates' preview images fit the picker cards (CSS `object-fit`).
365
+ * A template's own `imageFit` wins. Default: `contain`.
366
+ */
367
+ templateImageFit?: RepeaterImageFit;
291
368
  /** Label shown when an item is collapsed. Receives the item and its index. */
292
369
  previewLabel?: (item: unknown, index: number) => string;
293
370
  confirmDelete?: boolean;