@narrative.io/jsonforms-provider-protocols 3.0.0-beta.14 → 3.0.0-beta.17

package/src/core/resolveScope.ts

@@ -1,3 +1,5 @@
+import { deepDeref, deref } from "./refs";
+
 /**
  * Resolve a JSON Forms scope path to its schema within a root schema.
  * Handles nested paths like "#/properties/parent/properties/child".
@@ -6,6 +8,12 @@
  *   - "properties" segments navigate into object `.properties`
  *   - "items" segments navigate into array `.items`
  *   - all other segments index directly into the current object
+ *
+ * `$ref` nodes are dereferenced transparently at every step, so scopes that
+ * cross a `$ref` boundary (e.g. `items: { $ref: "#/$defs/X" }`) resolve to
+ * the target schema rather than returning `{}`. The returned schema is also
+ * deep-dereferenced so downstream walkers (e.g. `getProjectedSchema`) can
+ * operate on a self-contained sub-schema without needing the original root.
  */
 export function resolveScopeSchema(
   scope: string,
@@ -17,13 +25,14 @@ export function resolveScopeSchema(
 
   // Remove the leading "#/" and split into segments
   const path = scope.replace(/^#\/?/, "");
-  if (!path) return rootSchema;
+  if (!path) return deepDeref(rootSchema, rootSchema);
 
   const segments = path.split("/");
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let current: any = rootSchema;
 
   for (const segment of segments) {
+    current = deref(current, rootSchema);
     if (!current || typeof current !== "object") return undefined;
 
     if (segment === "properties") {
@@ -35,5 +44,5 @@ export function resolveScopeSchema(
     }
   }
 
-  return current;
+  return deepDeref(current, rootSchema);
 }

package/src/vue/components/ProviderAutocomplete.vue

@@ -12,10 +12,11 @@ const props = defineProps<{
   path: string;
 }>();
 const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
-const { projectedData, handleProjectedChange: handleChange } = useProjection(
-  control,
-  rawHandleChange,
-);
+const {
+  projectedData,
+  projectedLabel,
+  handleProjectedChange: handleChange,
+} = useProjection(control, rawHandleChange);
 
 const binding = computed(() => {
   const provider = control.value.uischema?.options?.provider;
@@ -57,9 +58,7 @@ const onSelect = (event: { value?: { value?: unknown } | unknown }) => {
 
 <template>
   <div class="jf-control">
-    <label v-if="control.schema.title" class="jf-label">{{
-      control.schema.title
-    }}</label>
+    <label v-if="projectedLabel" class="jf-label">{{ projectedLabel }}</label>
     <div v-if="control.description" class="jf-description">
       {{ control.description }}
     </div>

package/src/vue/components/ProviderMultiSelect.vue

@@ -5,6 +5,7 @@ import { computed, inject, watch } from "vue";
 import { useProvider } from "../composables/useProvider";
 import { useProjection } from "../composables/useProjection";
 import { shouldAutoSelectMulti } from "../utils/autoSelect";
+import { resolvePlaceholder } from "../utils/placeholder";
 import MultiSelect from "primevue/multiselect";
 
 const props = defineProps<{
@@ -13,10 +14,11 @@ const props = defineProps<{
   path: string;
 }>();
 const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
-const { projectedData, handleProjectedChange: handleChange } = useProjection(
-  control,
-  rawHandleChange,
-);
+const {
+  projectedData,
+  projectedLabel,
+  handleProjectedChange: handleChange,
+} = useProjection(control, rawHandleChange);
 
 const binding = computed(() => {
   const provider = control.value.uischema?.options?.provider;
@@ -94,19 +96,17 @@ const value = computed({
 
 const placeholder = computed(() => {
   if (loading.value) return "Loading…";
-  // Check for placeholder in uischema options
-  const uischemaPlaceholder = (
-    control.value.uischema as { options?: { placeholder?: string } }
-  )?.options?.placeholder;
-  return uischemaPlaceholder || "Select…";
+  return resolvePlaceholder(
+    control.value.uischema,
+    projectedLabel.value,
+    "select",
+  );
 });
 </script>
 
 <template>
   <div class="jf-control">
-    <label v-if="control.schema.title" class="jf-label">{{
-      control.schema.title
-    }}</label>
+    <label v-if="projectedLabel" class="jf-label">{{ projectedLabel }}</label>
     <div v-if="control.description" class="jf-description">
       {{ control.description }}
     </div>

package/src/vue/components/ProviderSelect.vue

@@ -6,6 +6,7 @@ import { useProvider } from "../composables/useProvider";
 import { useDeriveInitialValue } from "../composables/useDeriveInitialValue";
 import { useProjection } from "../composables/useProjection";
 import { shouldAutoSelect } from "../utils/autoSelect";
+import { resolvePlaceholder } from "../utils/placeholder";
 import Dropdown from "primevue/dropdown";
 
 const props = defineProps<{
@@ -14,10 +15,11 @@ const props = defineProps<{
   path: string;
 }>();
 const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
-const { projectedData, handleProjectedChange: handleChange } = useProjection(
-  control,
-  rawHandleChange,
-);
+const {
+  projectedData,
+  projectedLabel,
+  handleProjectedChange: handleChange,
+} = useProjection(control, rawHandleChange);
 
 const binding = computed(() => {
   const provider = control.value.uischema?.options?.provider;
@@ -79,19 +81,17 @@ const value = computed({
 
 const placeholder = computed(() => {
   if (loading.value) return "Loading…";
-  // Check for placeholder in uischema options
-  const uischemaPlaceholder = (
-    control.value.uischema as { options?: { placeholder?: string } }
-  )?.options?.placeholder;
-  return uischemaPlaceholder || "Select…";
+  return resolvePlaceholder(
+    control.value.uischema,
+    projectedLabel.value,
+    "select",
+  );
 });
 </script>
 
 <template>
   <div class="jf-control">
-    <label v-if="control.schema.title" class="jf-label">{{
-      control.schema.title
-    }}</label>
+    <label v-if="projectedLabel" class="jf-label">{{ projectedLabel }}</label>
     <div v-if="control.description" class="jf-description">
       {{ control.description }}
     </div>

package/src/vue/primevue/JfEnum.vue

@@ -49,6 +49,7 @@ import { useDeriveInitialValue } from "../composables/useDeriveInitialValue";
 import { useProjection } from "../composables/useProjection";
 import { useDirtyValidation } from "../composables/useDirtyValidation";
 import { shouldAutoSelect } from "../utils/autoSelect";
+import { resolvePlaceholder } from "../utils/placeholder";
 import Dropdown from "primevue/dropdown";
 
 // Access props from the component instance
@@ -131,9 +132,10 @@ const {
 
 const placeholder = computed<string | undefined>(() => {
   if (loading.value) return "Loading…";
-  return (
-    (control.value.uischema as { options?: { placeholder?: string } })?.options
-      ?.placeholder ?? control.value.description
+  return resolvePlaceholder(
+    control.value.uischema,
+    projectedLabel.value,
+    "select",
   );
 });
 

package/src/vue/primevue/JfEnumArray.vue

@@ -47,6 +47,7 @@ import { useDerive } from "../composables/useDerive";
 import { useProjection } from "../composables/useProjection";
 import { useDirtyValidation } from "../composables/useDirtyValidation";
 import { shouldAutoSelectMulti } from "../utils/autoSelect";
+import { resolvePlaceholder } from "../utils/placeholder";
 import MultiSelect from "primevue/multiselect";
 
 // Access props from the component instance
@@ -164,9 +165,10 @@ watch(
 
 const placeholder = computed<string | undefined>(() => {
   if (loading.value) return "Loading…";
-  return (
-    (control.value.uischema as { options?: { placeholder?: string } })?.options
-      ?.placeholder ?? control.value.description
+  return resolvePlaceholder(
+    control.value.uischema,
+    projectedLabel.value,
+    "select",
   );
 });
 

package/src/vue/primevue/JfNumber.vue

@@ -45,6 +45,7 @@ import { useDerive } from "../composables/useDerive";
 import { useDeriveInitialValue } from "../composables/useDeriveInitialValue";
 import { useProjection } from "../composables/useProjection";
 import { useDirtyValidation } from "../composables/useDirtyValidation";
+import { resolvePlaceholder } from "../utils/placeholder";
 import InputNumber from "primevue/inputnumber";
 
 // Access props from the component instance
@@ -64,8 +65,8 @@ const options = computed(
       ?.options ?? {},
 );
 
-const placeholder = computed<string | undefined>(
-  () => (options.value.placeholder as string) ?? control.value.description,
+const placeholder = computed<string | undefined>(() =>
+  resolvePlaceholder(control.value.uischema, projectedLabel.value, "input"),
 );
 
 // Add derive functionality

package/src/vue/primevue/JfText.vue

@@ -46,6 +46,7 @@ import { useDerive } from "../composables/useDerive";
 import { useDeriveInitialValue } from "../composables/useDeriveInitialValue";
 import { useProjection } from "../composables/useProjection";
 import { useDirtyValidation } from "../composables/useDirtyValidation";
+import { resolvePlaceholder } from "../utils/placeholder";
 import InputText from "primevue/inputtext";
 import AutoComplete from "primevue/autocomplete";
 
@@ -111,16 +112,23 @@ watch(query, () => {
   if (binding.value?.load === "query") reload();
 });
 
+const isAutocomplete = computed(() => !!binding.value);
+
 const placeholder = computed<string | undefined>(() => {
   if (loading.value) return "Loading…";
-  return (
-    (control.value.uischema as { options?: { placeholder?: string } })?.options
-      ?.placeholder ?? control.value.description
+  const explicit = (
+    control.value.uischema as { options?: { placeholder?: string } }
+  )?.options?.placeholder;
+  if (explicit) return explicit;
+  // In autocomplete mode the input is really a search box — use matching UX.
+  if (isAutocomplete.value) return "Type to search…";
+  return resolvePlaceholder(
+    control.value.uischema,
+    projectedLabel.value,
+    "input",
   );
 });
 
-const isAutocomplete = computed(() => !!binding.value);
-
 // Add derive functionality
 useDerive({ control, handleChange, data: projectedData });
 

package/src/vue/primevue/JfTextArea.vue

@@ -43,6 +43,7 @@ import { useJsonFormsControl } from "@jsonforms/vue";
 import { computed, getCurrentInstance } from "vue";
 import { useProjection } from "../composables/useProjection";
 import { useDirtyValidation } from "../composables/useDirtyValidation";
+import { resolvePlaceholder } from "../utils/placeholder";
 import Textarea from "primevue/textarea";
 
 // Access props from the component instance
@@ -56,10 +57,8 @@ const {
   projectedLabel,
 } = useProjection(control, rawHandleChange);
 
-const placeholder = computed<string | undefined>(
-  () =>
-    (control.value.uischema as { options?: { placeholder?: string } })?.options
-      ?.placeholder ?? control.value.description,
+const placeholder = computed<string | undefined>(() =>
+  resolvePlaceholder(control.value.uischema, projectedLabel.value, "input"),
 );
 
 // Track user interaction — errors only show after blur

package/src/vue/utils/placeholder.ts

@@ -0,0 +1,42 @@
+/**
+ * Placeholder resolution for form controls.
+ *
+ * Precedence:
+ *   1. `uischema.options.placeholder` (explicit author intent — always wins)
+ *   2. `Select ${label}` or `Enter ${label}` when a label is resolvable
+ *   3. Kind-appropriate bare fallback
+ *
+ * Never falls back to `schema.description` — descriptions are rendered as
+ * prose above the field by our renderers, so re-using them as placeholder
+ * produces a duplicated, truncated string inside the input.
+ */
+
+export type PlaceholderKind = "select" | "input";
+
+/**
+ * Strip a trailing required-indicator asterisk (" *" or "*") that `resolveLabel`
+ * appends for required fields, so composed placeholders read naturally.
+ */
+function stripRequiredMarker(label: string): string {
+  return label.replace(/\s*\*\s*$/, "").trim();
+}
+
+export function resolvePlaceholder(
+  uischema: { options?: unknown } | undefined,
+  resolvedLabel: string | undefined,
+  kind: PlaceholderKind,
+): string | undefined {
+  const options = uischema?.options;
+  const explicit =
+    options && typeof options === "object"
+      ? (options as Record<string, unknown>).placeholder
+      : undefined;
+  if (typeof explicit === "string" && explicit.length > 0) return explicit;
+
+  const label = resolvedLabel ? stripRequiredMarker(resolvedLabel) : "";
+  if (label) {
+    return kind === "select" ? `Select ${label}` : `Enter ${label}`;
+  }
+
+  return kind === "select" ? "Select…" : undefined;
+}