Introduce dynamic props via resolveProps API

[chrisvxd]

This PR that introduces new APIs for expanding the capability of adaptors

• The resolveProp config API allows users to modify props dynamically without writing them to the Puck data model on a per-component basis.
• The resolveData util function allows users to apply their dynamic props on the server or client before rendering their page with the <Render> component
• The mapProp adaptor API to enable the user to return change the shape of the data returned by the adaptor before applying it as a prop

Additionally:

• It removes the _data API for adaptors in favour of resolveProp. This is a breaking change.
• It makes the types stricter for Fields (considered a Fix).

resolveProps Usage

The Hero component in the demo app contains an example

const config:Config = {
  HeadingBlock: {
    fields: {
      text: {
        type: "text"
      }
    },
    resolveProps: async (props) => {
      // modify props. May include async operations.
      return { props: { ...props, text: "Hello, world" }, locked: { text: true } }
    },
    render: ({ text }) => {
      return <h1>{text}</h1>
    }
  }
}

Pairing it with an adaptor

const quotesAdaptor = {
  name: "Quotes API",
  fetchList: async () => {
    const quotesResponse = await fetch("/api/quotes");
    
    return quotesResponse.json();
  }
};

const config:Config = {
  HeadingBlock: {
    fields: {
      quote: {
        type: "external",
        adaptor: quotesAdaptor
      },
      text: {
        type: "text"
      }
    },
    resolveProps: async (props) => {
      if (props.quote?.id) {
        const quote = await fetch(`/api/quotes/${props.quote.id}`);
        
        return { props: { text: quote.json().content }, locked: { text: true } }
      }
      
      return { props, locked: { text: false } };
    },
    render: ({ text }) => {
      return <h1>{text}</h1>
    }
  }
}

resolveData usage

This should be used by the user to resolve data before rendering their component. It should ideally be used server-side, but can also be used client side in a useEffect hook.

export const MyRSCPage =  async () => {
  const data = await getPage(); // user's database query
  const resolvedData = await resolveData(data);

  return <Render data={data} />
}

mapProp usage

const quotesAdaptor = {
  name: "Quotes API",
  fetchList: async () => {
    const quotesResponse = await fetch("/api/quotes");
    const data =  quotesResponse.json();

    return { id: data.id, title: data };
  },
  // Called _after_ the user selects an item from the adaptor
  mapProp: (prop => ({ id: prop.id }))
};

const config:Config = {
  HeadingBlock: {
    fields: {
      quote: {
        type: "external",
        adaptor: quotesAdaptor
      },
      text: {
        type: "text"
      }
    },
    render: ({ text }) => {
      return <h1>{text}</h1>
    }
  }
}

Tasks

• add tests

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
puck-demo	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Oct 26, 2023 9:58am

[monospaced]

Couple of questions, approving for expediency

[monospaced]

Could Adaptors fetch an object instead of a list?

[chrisvxd]

They could fetch an object but this method needs to return an array to populate the table

[monospaced]

Wonder if "a list of content" is correct in that case? Maybe Fetch content and return an array? I could be missing the point here 😊

[chrisvxd]

I've updated to Fetch content from a third-party API and return an array for clarity

[monospaced]

imported but not used?

[chrisvxd]

Addressed