@sanity/personalization-plugin 2.4.1 → 2.5.0-field-level-personalization.1

package/README.md

@@ -2,8 +2,6 @@
 
 ## Previously know as @sanity/personalisation-plugin
 
-> This is a **Sanity Studio v3** plugin.
-
 This plugin allows users to add a/b/n testing experiments to individual fields.
 
 ![image](./overview.gif)
@@ -20,6 +18,7 @@ Once configured you can query the values using the ids of the experiment and var
   - [Validation of individual array items](#validation-of-individual-array-items)
   - [Shape of stored data](#shape-of-stored-data)
   - [Querying data](#querying-data)
+  - [Split testing](#split-testing)
   - [Using experiment fields in an array](#using-experiment-fields-in-an-array)
   - [License](#license)
   - [Develop \& test](#develop--test)
@@ -208,7 +207,6 @@ This would also create two new fields in your schema.
 
 Note that the name key in the field gets rewritten to value and is instead used to name the object field.
 
-
 ## Validation of individual array items
 
 You may wish to validate individual fields for various reasons. From the variant array field, add a validation rule that can look through all the array items, and return item-specific validation messages at the path of that array item.
@@ -260,7 +258,8 @@ The custom input contains buttons which will add new array items with the experi
 }
 ```
 
-Querying data
+## Querying data
+
 Using GROQ filters you can query for a specific experiment, with a fallback to default value like so:
 
 ```ts
@@ -269,9 +268,112 @@ Using GROQ filters you can query for a specific experiment, with a fallback to d
 }
 ```
 
+## Split testing
+
+Split testing involves splitting traffic for one url over 2+ pages, this is used when you want to test more than just a single field in an experiment.
+
+### Studio Setup
+
+To do split testing using this plugin define a type that can store a url path
+
+```ts
+export const path = defineType({
+  name: 'path',
+  type: 'string',
+  validation: (Rule) =>
+    Rule.required().custom(async (value: string | undefined, context) => {
+      if (!value) return true
+      if (!value.startsWith('/')) return 'Must start with "/"'
+      return true
+    }),
+})
+```
+
+add the type to the studio `schema.types` and the plugin config fields:
+
+```ts
+ fieldLevelExperiments({
+        fields: ['path', ...otherFields],
+        experiments: getExperiments,
+      }),
+```
+
+and then create a document type that stores the routing information:
+
+```ts
+export const routing = defineType({
+  name: 'routing',
+  type: 'document',
+  title: 'Routing Experiments',
+  fields: [
+    {
+      name: 'pathExperiment',
+      type: 'experimentPath',
+      initialValue: {active: true},
+    },
+  ],
+  preview: {
+    select: {
+      path: 'pathExperiment.default',
+      experiment: 'pathExperiment.experimentId',
+    },
+    prepare({path, experiment}) {
+      return {
+        title: `${path} - ${experiment}`,
+      }
+    },
+  },
+})
+```
+
+### Frontend usage
+
+In your frontend you will need some middleware that can intercept the request for the page and check if the route is included in your split page testing and if so decide which page the user should see.
+
+In Next.js Middleware it could be something like
+
+```ts
+const ROUTING_QUERY = defineQuery(`*[
+  _type == "routing" &&
+  pathExperiment.default == $path
+][0]{
+  "route": coalesce(pathExperiment.variants[experimentId == $experimentId && variantId == $variantId][0].value, pathExperiment.default)
+}`)
+
+export async function middleware(request: NextRequest) {
+  let response = NextResponse.next()
+  const path = request.nextUrl.pathname
+  // getExperimentValue is a function that will determine a variant based on some user properties
+  const {variant} = await getExperimentValue(path)
+
+  const queryParams = {
+    path,
+    experimentId: 'homepage',
+    variantId: variant?.id || '',
+  }
+
+  // Instead of doing a query for every page this could be queried at build time and stored in a file.
+  const data = await client.fetch(ROUTING_QUERY, queryParams)
+  if (data?.route) {
+    const url = request.nextUrl.clone()
+    url.pathname = data.route
+    const rewrite = NextResponse.rewrite(url)
+    return rewrite
+  }
+
+  return response
+}
+
+export const config = {
+  //only run the middleware on pages
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)'],
+}
+```
+
 ## Using experiment fields in an array
 
 You may want to add experiment fields as a type with in an array in oder to do this you would need to set an initial value for the experiment to active the schema would be something like:
+
 ```ts
 defineField({
       name: 'components',
@@ -286,7 +388,7 @@ defineField({
     }),
 ```
 
-You can then use a groq filter to return the base version of you array member so you don't have to create an experiment specific version 
+You can then use a groq filter to return the base version of you array member so you don't have to create an experiment specific version
 
 ```ts
 *[

package/dist/_chunks-cjs/fieldExperiments.js

@@ -0,0 +1,507 @@
+"use strict";
+var jsxRuntime = require("react/jsx-runtime"), sanity = require("sanity"), ui = require("@sanity/ui"), uuid = require("@sanity/uuid"), react = require("react"), equal = require("fast-deep-equal"), suspendReact = require("suspend-react"), gi = require("react-icons/gi");
+function _interopDefaultCompat(e) {
+  return e && typeof e == "object" && "default" in e ? e : { default: e };
+}
+var equal__default = /* @__PURE__ */ _interopDefaultCompat(equal);
+const ArrayItem = (props) => {
+  const { active } = props.value;
+  return active || props.inputProps.onChange(sanity.set(!0, ["active"])), props.renderDefault(props);
+}, CONFIG_DEFAULT = {
+  fields: [],
+  apiVersion: "2024-11-07",
+  experimentNameOverride: "experiment",
+  variantNameOverride: "variant",
+  variantId: "variantId",
+  variantArrayName: "variants",
+  experimentId: "experimentId"
+}, ExperimentContext = react.createContext({
+  ...CONFIG_DEFAULT,
+  experiments: []
+});
+function useExperimentContext() {
+  return react.useContext(ExperimentContext);
+}
+function ExperimentProvider(props) {
+  const { experimentFieldPluginConfig } = props, client = sanity.useClient({ apiVersion: experimentFieldPluginConfig.apiVersion }), workspace = sanity.useWorkspace(), experiments = Array.isArray(experimentFieldPluginConfig.experiments) ? experimentFieldPluginConfig.experiments : suspendReact.suspend(
+    // eslint-disable-next-line require-await
+    async () => typeof experimentFieldPluginConfig.experiments == "function" ? experimentFieldPluginConfig.experiments(client) : experimentFieldPluginConfig.experiments,
+    [workspace],
+    { equal: equal__default.default }
+  ), context = react.useMemo(
+    () => ({ ...experimentFieldPluginConfig, experiments }),
+    [experimentFieldPluginConfig, experiments]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(ExperimentContext.Provider, { value: context, children: props.renderDefault(props) });
+}
+const ArrayInput = (props) => {
+  const fieldPath = props.path.slice(0, -1), { onItemAppend, variantName, variantId, experimentId } = props, experimentValue = sanity.useFormValue([...fieldPath, experimentId]), { experiments } = useExperimentContext(), handleClick = react.useCallback(
+    async (variant) => {
+      const item = {
+        _key: uuid.uuid(),
+        [variantId]: variant.id,
+        [experimentId]: experimentValue,
+        _type: variantName
+      };
+      onItemAppend(item);
+    },
+    [variantId, experimentId, experimentValue, variantName, onItemAppend]
+  ), filteredVariants = experiments.find((option) => option.id === experimentValue)?.variants || [], usedVariants = (props.value || [])?.map((variant) => variant[variantId]);
+  return /* @__PURE__ */ jsxRuntime.jsxs(ui.Stack, { space: 3, children: [
+    props.renderDefault({ ...props, arrayFunctions: () => null }),
+    /* @__PURE__ */ jsxRuntime.jsx(ui.Inline, { space: 1, children: filteredVariants.map((variant) => /* @__PURE__ */ jsxRuntime.jsx(
+      ui.Button,
+      {
+        text: `Add ${variant.label}`,
+        mode: "ghost",
+        disabled: usedVariants?.includes(variant.id),
+        onClick: () => handleClick(variant)
+      },
+      `${experimentValue}-${variant.id}`
+    )) })
+  ] });
+}, CloseIcon = /* @__PURE__ */ react.forwardRef(function(props, ref) {
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "svg",
+    {
+      "data-sanity-icon": "close",
+      width: "1em",
+      height: "1em",
+      viewBox: "0 0 25 25",
+      fill: "none",
+      xmlns: "http://www.w3.org/2000/svg",
+      ...props,
+      ref,
+      children: /* @__PURE__ */ jsxRuntime.jsx(
+        "path",
+        {
+          d: "M18 7L7 18M7 7L18 18",
+          stroke: "currentColor",
+          strokeWidth: 1.2,
+          strokeLinejoin: "round"
+        }
+      )
+    }
+  );
+}), clearChildrenGroups = (props) => {
+  const children = props.children;
+  return !children || typeof children != "object" || !children.props ? props : {
+    ...props,
+    children: {
+      ...children,
+      props: {
+        ...children.props,
+        children: {
+          ...children.props.children,
+          props: {
+            ...children.props.children?.props,
+            groups: []
+          }
+        }
+      }
+    }
+  };
+}, useAddExperimentAction = (props) => {
+  const { onChange, active, experimentNameOverride } = props, handleAddAction = react.useCallback(() => {
+    onChange([sanity.set(!active, ["active"])]);
+  }, [onChange, active]);
+  return {
+    title: `Add ${experimentNameOverride}`,
+    type: "action",
+    icon: gi.GiSoapExperiment,
+    onAction: handleAddAction,
+    renderAsButton: !0
+  };
+}, useRemoveExperimentAction = (props) => {
+  const { onChange, active, experimentId, experimentNameOverride, variantNameOverride } = props, handleClearAction = react.useCallback(() => {
+    const activeId = ["active"], experiment = [experimentId], variants = [`${variantNameOverride}s`];
+    onChange([sanity.set(!active, activeId), sanity.unset(experiment), sanity.unset(variants)]);
+  }, [onChange, active, experimentId, variantNameOverride]);
+  return {
+    title: `Remove ${experimentNameOverride}`,
+    type: "action",
+    icon: CloseIcon,
+    onAction: handleClearAction,
+    renderAsButton: !0
+  };
+}, createActions = ({
+  onChange,
+  inputId,
+  active,
+  experimentNameOverride,
+  experimentId,
+  variantNameOverride
+}) => {
+  const removeAction = sanity.defineDocumentFieldAction({
+    name: `Remove ${experimentNameOverride}`,
+    useAction: (props) => useRemoveExperimentAction({
+      active: !0,
+      onChange,
+      experimentNameOverride,
+      experimentId,
+      variantNameOverride
+    })
+  }), addAction = sanity.defineDocumentFieldAction({
+    name: `Add ${experimentNameOverride}`,
+    useAction: (props) => useAddExperimentAction({
+      active: !1,
+      onChange,
+      experimentNameOverride
+    })
+  });
+  return active ? removeAction : addAction;
+}, Field = (props) => {
+  const { onChange } = props.inputProps, { inputId, experimentNameOverride, experimentId, variantNameOverride } = props, active = props.value?.active, actionProps = react.useMemo(
+    () => ({
+      onChange,
+      inputId,
+      active,
+      experimentNameOverride,
+      experimentId,
+      variantNameOverride
+    }),
+    [onChange, inputId, active, experimentNameOverride, experimentId, variantNameOverride]
+  ), memoizedActions = react.useMemo(() => {
+    const oldActions = props.actions || [];
+    return [createActions(actionProps), ...oldActions];
+  }, [actionProps, props.actions]), enhancedProps = react.useMemo(() => ({
+    ...clearChildrenGroups(props),
+    actions: memoizedActions
+  }), [props, memoizedActions]);
+  return props.renderDefault(enhancedProps);
+}, Select = (props) => {
+  const {
+    value,
+    // Current field value
+    onChange,
+    // Method to handle patch events,
+    elementProps,
+    listOptions,
+    handleChange
+  } = props;
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    ui.Select,
+    {
+      ...elementProps,
+      fontSize: 2,
+      padding: 3,
+      space: [3, 3, 4],
+      value: value || "",
+      onChange: (event) => handleChange(event, onChange),
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx("option", { value: "", children: "Select an option..." }),
+        listOptions.map(({ value: optionValue, title }) => /* @__PURE__ */ jsxRuntime.jsx("option", { value: optionValue, children: title }, optionValue))
+      ]
+    }
+  );
+}, formatlistOptions = (experiments) => experiments.map((experiment) => ({
+  title: experiment.label,
+  value: experiment.id
+})), Input = (props) => {
+  const { experiments } = useExperimentContext(), id = sanity.useFormValue(["_id"]), additionalChangePath = react.useMemo(
+    () => [...props.path.slice(0, -1), `${props.variantNameOverride}s`],
+    [props.variantNameOverride, props.path]
+  ), subValues = sanity.useFormValue(additionalChangePath), { patch } = sanity.useDocumentOperation(sanity.getPublishedId(id), props.schemaType.name), handleChange = react.useCallback(
+    (event, onChange) => {
+      const inputValue = event.currentTarget.value;
+      if (onChange(inputValue ? sanity.set(inputValue) : sanity.unset()), subValues) {
+        const patchEvent = {
+          unset: [additionalChangePath.join(".")]
+        };
+        patch.execute([patchEvent]);
+      }
+    },
+    [patch, subValues, additionalChangePath]
+  );
+  return experiments.length ? /* @__PURE__ */ jsxRuntime.jsx(Select, { ...props, listOptions: formatlistOptions(experiments), handleChange }) : /* @__PURE__ */ jsxRuntime.jsx(ui.Card, { padding: [3, 3, 4], radius: 2, shadow: 1, tone: "caution", children: /* @__PURE__ */ jsxRuntime.jsxs(ui.Text, { align: "center", size: [2, 2, 3], children: [
+    "There are no defined ",
+    props.experimentNameOverride,
+    "s"
+  ] }) });
+}, VariantInput = (props) => {
+  const experimentPath = props.path.slice(0, -2), defaultValue = sanity.useFormValue([...experimentPath, "default"]), handleClick = () => {
+    props.onChange(sanity.set(defaultValue, ["value"]));
+  };
+  return /* @__PURE__ */ jsxRuntime.jsxs(ui.Stack, { space: 3, children: [
+    props.renderDefault(props),
+    /* @__PURE__ */ jsxRuntime.jsx(ui.Inline, { space: 1, children: /* @__PURE__ */ jsxRuntime.jsx(ui.Button, { text: "Copy default", mode: "ghost", onClick: () => handleClick() }) })
+  ] });
+}, VariantPreview = (props) => {
+  const [subtitle, setSubtitle] = react.useState(void 0), [title, setTitle] = react.useState(void 0), [media, setMedia] = react.useState(void 0), client = sanity.useClient({ apiVersion: "2025-01-01" }), { experiments } = useExperimentContext(), { experiment, variant, value } = props, selectedExperiment = experiments.find((experimentItem) => experimentItem.id === experiment), selectedVariant = selectedExperiment?.variants.find((variantItem) => variantItem.id === variant);
+  react.useEffect(() => {
+    (async () => {
+      if (setTitle(`${selectedExperiment?.label} - ${selectedVariant?.label}`), typeof value == "string")
+        return setSubtitle(value);
+      if (sanity.isReference(value)) {
+        const doc = await client.getDocument(value._ref), referenceType = (props.schemaType.fields.find((field) => field.name === "value")?.type).to.find((field) => field.type?.name === doc?._type), selectFields = {}, previewFields = referenceType?.preview?.select || {};
+        Object.keys(previewFields).forEach((key) => {
+          const valueKey = referenceType?.preview?.select?.[key];
+          selectFields[key] = valueKey && doc ? valueKey?.split(".").reduce((acc, index) => acc[index], doc) : void 0;
+        });
+        const previewContent = referenceType?.preview?.prepare?.(selectFields);
+        return setMedia(previewContent?.media || selectFields.media), setSubtitle(previewContent?.title || selectFields?.title);
+      }
+      return sanity.isImage(value) && setMedia(value), "";
+    })();
+  }, [value, client, selectedExperiment?.label, selectedVariant?.label, props.schemaType]);
+  const previewProps = {
+    ...props,
+    title,
+    subtitle,
+    media
+  };
+  return props.renderDefault(previewProps);
+};
+function flattenSchemaType(schemaType) {
+  return sanity.isDocumentSchemaType(schemaType) ? extractInnerFields(schemaType.fields, [], 5) : (console.error("Schema type is not a document"), []);
+}
+function extractInnerFields(fields, path, maxDepth) {
+  return path.length >= maxDepth ? [] : fields.reduce((acc, field) => {
+    const thisFieldWithPath = { path: [...path, field.name], ...field };
+    if (field.type.jsonType === "object") {
+      const innerFields = extractInnerFields(field.type.fields, [...path, field.name], maxDepth);
+      return [...acc, thisFieldWithPath, ...innerFields];
+    } else if (field.type.jsonType === "array") {
+      const innerFields = (field.type.of || []).reduce((arrayAcc, arrayType) => {
+        if ("fields" in arrayType) {
+          const typeFields = extractInnerFields(arrayType.fields, [...path, field.name], maxDepth);
+          return [...arrayAcc, ...typeFields];
+        }
+        return arrayAcc;
+      }, []);
+      return [...acc, thisFieldWithPath, ...innerFields];
+    }
+    return [...acc, thisFieldWithPath];
+  }, []);
+}
+const createExperimentType = ({
+  field,
+  experimentNameOverride,
+  variantNameOverride,
+  variantId,
+  variantArrayName,
+  experimentId
+}) => {
+  const typeName = typeof field == "string" ? field : field.name, usedName = String(typeName[0]).toUpperCase() + String(typeName).slice(1), variantName = `${variantNameOverride}${usedName}`;
+  return sanity.defineType({
+    name: `${experimentNameOverride}${usedName}`,
+    type: "object",
+    groups: [
+      {
+        name: "default",
+        title: "Default",
+        hidden: ({ parent }) => !Array.isArray(parent)
+      },
+      {
+        name: "experiments",
+        title: "Experiments",
+        hidden: ({ parent }) => !Array.isArray(parent)
+      },
+      {
+        name: "all-fields",
+        title: "All fields",
+        hidden: ({ parent }) => Array.isArray(parent)
+      }
+    ],
+    components: {
+      field: (props) => /* @__PURE__ */ jsxRuntime.jsx(
+        Field,
+        {
+          ...props,
+          experimentId,
+          experimentNameOverride,
+          variantNameOverride
+        }
+      ),
+      item: ArrayItem
+    },
+    fields: [
+      typeof field == "string" ? (
+        // Define a simple field if all we have is the name as a string
+        sanity.defineField({
+          name: "default",
+          type: field,
+          group: "default"
+        })
+      ) : (
+        // Pass in the configured options, but overwrite the name
+        {
+          ...field,
+          name: "default",
+          group: "default"
+        }
+      ),
+      sanity.defineField({
+        name: "active",
+        type: "boolean",
+        hidden: !0,
+        initialValue: !1
+      }),
+      sanity.defineField({
+        name: experimentId,
+        type: "string",
+        group: "experiments",
+        components: {
+          input: (props) => /* @__PURE__ */ jsxRuntime.jsx(
+            Input,
+            {
+              ...props,
+              experimentNameOverride,
+              variantNameOverride
+            }
+          )
+        },
+        hidden: ({ parent }) => !parent?.active
+      }),
+      sanity.defineField({
+        name: variantArrayName,
+        type: "array",
+        group: "experiments",
+        hidden: ({ parent }) => !parent?.[experimentId],
+        components: {
+          input: (props) => /* @__PURE__ */ jsxRuntime.jsx(
+            ArrayInput,
+            {
+              ...props,
+              variantName,
+              variantId,
+              experimentId
+            }
+          )
+        },
+        of: [
+          sanity.defineField({
+            name: variantName,
+            type: variantName
+          })
+        ]
+      })
+    ],
+    preview: {
+      select: {
+        base: "default",
+        experiment: experimentId
+      },
+      prepare: ({ base, experiment }) => {
+        const title = base?.title || base?.name || typeof base == "string" ? base : "", experimentTitle = experiment ? `Experiment: ${experiment}` : "", media = base?.image || base?.photo || base?.media || "";
+        return {
+          title: title || experimentTitle,
+          subtitle: title ? experimentTitle : "",
+          media
+        };
+      }
+    }
+  });
+}, createVariantType = ({
+  field,
+  variantNameOverride,
+  variantId,
+  experimentId
+}) => {
+  const typeName = typeof field == "string" ? field : field.name, usedName = String(typeName[0]).toUpperCase() + String(typeName).slice(1);
+  return sanity.defineType({
+    name: `${variantNameOverride}${usedName}`,
+    title: `${variantNameOverride} array ${usedName}`,
+    type: "object",
+    components: {
+      preview: VariantPreview,
+      input: VariantInput
+    },
+    fields: [
+      {
+        type: "string",
+        name: variantId,
+        readOnly: !0
+      },
+      {
+        type: "string",
+        name: experimentId,
+        hidden: !0
+      },
+      typeof field == "string" ? (
+        // Define a simple field if all we have is the name as a string
+        sanity.defineField({
+          name: "value",
+          type: field
+          // hidden: ({parent}) => !parent?.[`${objectNameOverride}Id`],
+        })
+      ) : (
+        // Pass in the configured options, but overwrite the name
+        {
+          ...field,
+          name: "value"
+          // hidden: ({parent}) => !parent?.[`${objectNameOverride}Id`],
+        }
+      )
+    ],
+    preview: {
+      select: {
+        variant: variantId,
+        experiment: experimentId,
+        value: "value"
+      }
+    }
+  });
+}, fieldSchema = ({
+  fields,
+  experimentNameOverride,
+  variantNameOverride,
+  variantId,
+  variantArrayName,
+  experimentId
+}) => [
+  ...fields.map(
+    (field) => createVariantType({ field, variantNameOverride, variantId, experimentId })
+  ),
+  ...fields.map(
+    (field) => createExperimentType({
+      field,
+      experimentNameOverride,
+      variantNameOverride,
+      variantId,
+      variantArrayName,
+      experimentId
+    })
+  )
+], fieldLevelExperiments = sanity.definePlugin((config) => {
+  const pluginConfig = { ...CONFIG_DEFAULT, ...config }, { fields, experimentNameOverride, variantNameOverride } = pluginConfig, experimentId = `${experimentNameOverride}Id`, variantArrayName = `${variantNameOverride}s`, variantId = `${variantNameOverride}Id`;
+  return {
+    name: "sanity-personalistaion-plugin-field-level-experiments",
+    schema: {
+      types: fieldSchema({
+        fields,
+        experimentNameOverride,
+        variantNameOverride,
+        variantId,
+        variantArrayName,
+        experimentId
+      })
+    },
+    form: {
+      components: {
+        input: (props) => {
+          if (!(props.id === "root" && sanity.isObjectInputProps(props)) || !flattenSchemaType(props.schemaType).some(
+            (field) => field.type.name.startsWith(experimentNameOverride) || field.name.startsWith(experimentNameOverride)
+          ))
+            return props.renderDefault(props);
+          const providerProps = {
+            ...props,
+            experimentFieldPluginConfig: {
+              ...pluginConfig,
+              variantId,
+              variantArrayName,
+              experimentId
+            }
+          };
+          return ExperimentProvider(providerProps);
+        }
+      }
+    }
+  };
+});
+exports.ArrayItem = ArrayItem;
+exports.CloseIcon = CloseIcon;
+exports.clearChildrenGroups = clearChildrenGroups;
+exports.fieldLevelExperiments = fieldLevelExperiments;
+exports.flattenSchemaType = flattenSchemaType;
+//# sourceMappingURL=fieldExperiments.js.map