Content publisher intent

.container {
  width: 100%;
  height: 100%;
}

/* Scale down preview on mobile devices */
@media (max-width: 600px) {
  .container {
    transform: scale(0.3);
  }
}

/* Avatar styling to match social media appearance */
.avatar {
  transform: scale(0.6);
  width: 24px;
  height: 24px;
  transform-origin: top left;
}

/* Text placeholder for loading states */
.textPlaceholder {
  min-width: calc(8 * 20);
}

/* Container for media images */
.imageContainer {
  border-radius: var(--ui-kit-radius-element-standard);
  overflow: hidden; /* Enable border radius */
}

/* Row containing all images */
.imageRow {
  overflow-y: hidden;
  overflow-x: auto;
  height: 400px;
  display: flex;
}

/* Individual image and placeholder styling */
.imagePlaceholder,
.image {
  width: 400px;
  height: 400px;
  object-fit: cover;
  display: inline-block;
  position: relative;
}

import type {
  OutputType,
  PreviewMedia,
  RenderPreviewUiInvocationContext,
} from "@canva/intents/content";
import { useEffect, useState } from "react";
import { useIntl } from "react-intl";
import { parsePublishSettings } from "./types";
import * as styles from "./preview_ui.css";
import {
  Box,
  Text,
  Rows,
  Columns,
  Column,
  Avatar,
  Placeholder,
  TextPlaceholder,
  ImageCard,
} from "@canva/app-ui-kit";
import type { Preview } from "@canva/intents/content";
import { isImagePreviewReady, type PublishSettings } from "./types";

// Static user data for demo purposes
// In production, fetch real user data from your platform's API
const username = "username";
const IMAGE_WIDTH = 400;

interface PreviewUiProps {
  invocationContext: RenderPreviewUiInvocationContext;
  registerOnPreviewChange: (
    callback: (opts: {
      previewMedia: PreviewMedia[];
      outputType: OutputType;
      publishRef?: string;
    }) => void,
  ) => () => void;
}

// Main preview UI component that receives preview updates when settings or pages change.
// preview UI is more flexible to align with your platform's design system, so it is not constrained to the Canva design system.
export const PreviewUi = ({
  invocationContext,
  registerOnPreviewChange,
}: PreviewUiProps) => {
  const [previewData, setPreviewData] = useState<{
    previewMedia?: PreviewMedia[];
    outputType?: OutputType;
    publishRef?: string;
  } | null>(
    invocationContext
      ? {
          previewMedia:
            (invocationContext?.previewMedia as PreviewMedia[]) || [],
          outputType:
            (invocationContext?.outputType as OutputType) || undefined,
          publishRef: invocationContext?.publishRef,
        }
      : null,
  );

  // Register to receive preview updates whenever settings or pages change
  useEffect(() => {
    const dispose = registerOnPreviewChange((data) => {
      setPreviewData(data);
    });
    return dispose;
  }, [registerOnPreviewChange]);

  const { previewMedia, publishRef, outputType } = previewData ?? {};
  const publishSettings = parsePublishSettings(publishRef);

  return (
    <div className={styles.container}>
      <Box
        display="flex"
        alignItems="center"
        justifyContent="center"
        flexDirection="column"
        width="full"
        height="full"
      >
        {outputType?.id === "post" && (
          <PostPreview previewMedia={previewMedia} settings={publishSettings} />
        )}
      </Box>
    </div>
  );
};

interface PreviewProps {
  previewMedia: PreviewMedia[] | undefined;
  settings: PublishSettings | undefined;
}

// Renders a social media post preview with user info, media, and caption
export const PostPreview = ({ previewMedia, settings }: PreviewProps) => {
  const isLoading = !previewMedia;

  const caption = settings?.caption;

  // TODO: You should update this value to match the visuals you're hoping to achieve with your export preview
  // Image width + padding + border
  const previewWidth = 400 + 32 + 2;

  return (
    <div style={{ width: previewWidth }}>
      <Box
        display="flex"
        alignItems="center"
        justifyContent="center"
        background="surface"
        borderRadius="large"
        padding="2u"
        border="standard"
      >
        <Rows spacing="2u">
          <UserInfo isLoading={isLoading} />
          <ImagePreview previewMedia={previewMedia} />
          <Caption isLoading={isLoading} caption={caption} />
        </Rows>
      </Box>
    </div>
  );
};

// Renders user profile information with avatar and username
const UserInfo = ({ isLoading }: { isLoading: boolean }) => {
  return (
    <Columns spacing="1u" alignY="center">
      <Column width="content">
        <div className={styles.avatar}>
          <Avatar name={username} />
        </div>
      </Column>
      <Column width="content">
        {isLoading ? (
          <div className={styles.textPlaceholder}>
            <TextPlaceholder size="medium" />
          </div>
        ) : (
          <Text size="small" variant="bold">
            {username}
          </Text>
        )}
      </Column>
    </Columns>
  );
};

// Renders the post caption with username
const Caption = ({
  isLoading,
  caption,
}: {
  isLoading: boolean;
  caption: string | undefined;
}) => {
  return (
    <>
      {isLoading ? (
        <div className={styles.textPlaceholder}>
          <TextPlaceholder size="medium" />
        </div>
      ) : (
        caption && (
          <Text lineClamp={2} size="small">
            {caption}
          </Text>
        )
      )}
    </>
  );
};

// Renders a single image post preview
const ImagePreview = ({
  previewMedia,
}: {
  previewMedia: PreviewMedia[] | undefined;
}) => {
  const isLoading = !previewMedia;
  const media = previewMedia?.find((media) => media.mediaSlotId === "media");
  const fullWidth = (media?.previews.length ?? 1) * IMAGE_WIDTH;

  return (
    <div className={styles.imageContainer}>
      {isLoading || !media?.previews.length ? (
        <div className={styles.imagePlaceholder}>
          <Placeholder shape="rectangle" />
        </div>
      ) : (
        <div className={styles.imageRow} style={{ width: fullWidth }}>
          {media?.previews
            .filter((p) => p.kind !== "email")
            .map((p) => {
              return (
                <div key={p.id} className={styles.image}>
                  <PreviewRenderer preview={p} />
                </div>
              );
            })}
        </div>
      )}
    </div>
  );
};

// Renders individual preview based on its type and status
const PreviewRenderer = ({ preview }: { preview: Preview }) => {
  if (preview.kind === "email") {
    return null;
  }

  const intl = useIntl();

  // Handle different preview states
  if (preview.status === "loading") {
    return (
      <ImageStatusText
        text={intl.formatMessage({
          defaultMessage: "Loading...",
          description:
            "Loading state text shown while image preview is loading",
        })}
      />
    );
  }

  if (preview.status === "error") {
    return (
      <ImageStatusText
        text={intl.formatMessage({
          defaultMessage: "Error loading preview",
          description: "Error message shown when image preview fails to load",
        })}
      />
    );
  }

  // Handle image previews (ready status)
  if (isImagePreviewReady(preview)) {
    return (
      <ImageCard
        alt={intl.formatMessage(
          {
            defaultMessage: "Image preview {id}",
            description: "Alt text for image preview thumbnails",
          },
          { id: preview.id },
        )}
        thumbnailUrl={preview.url}
      />
    );
  }

  // Fallback for unknown preview types
  return (
    <Box
      width="full"
      height="full"
      padding="2u"
      display="flex"
      alignItems="center"
      justifyContent="center"
    >
      <Text size="medium" tone="tertiary" alignment="center">
        {intl.formatMessage({
          defaultMessage: "Preview not available",
          description: "Fallback text shown when preview type is not supported",
        })}
      </Text>
    </Box>
  );
};

// Helper component to display status text for loading/error states
const ImageStatusText = ({ text }: { text: string }) => (
  <Box
    width="full"
    height="full"
    padding="2u"
    display="flex"
    alignItems="center"
    justifyContent="center"
  >
    <Text size="medium" tone="tertiary" alignment="center">
      {text}
    </Text>
  </Box>
);

import type {
  PublishSettingsSettingsUiContext,
  RenderSettingsUiRequest,
} from "@canva/intents/content";
import { FormField, Rows, Text, TextInput } from "@canva/app-ui-kit";
import { useCallback, useEffect, useState } from "react";
import { useIntl } from "react-intl";
import * as styles from "styles/components.css";
import type { PublishSettings } from "./types";
import { parsePublishSettings } from "./types";

// Settings UI component for configuring publish settings
export const SettingUi = ({
  invocationContext,
  updatePublishSettings,
  registerOnContextChange,
}: RenderSettingsUiRequest) => {
  const intl = useIntl();
  const [settings, setSettings] = useState<PublishSettings>(
    parsePublishSettings(invocationContext?.publishRef) ??
      ({ caption: "" } as PublishSettings),
  );
  const [settingsUiContext, setSettingsUiContext] =
    useState<PublishSettingsSettingsUiContext | null>(null);

  // Listen for settings UI context changes (e.g., when output type changes)
  useEffect(() => {
    const dispose = registerOnContextChange({
      onContextChange: (context) => {
        if (context.reason !== "publish_settings") return;
        setSettingsUiContext(context);
      },
    });
    return dispose;
  }, [registerOnContextChange]);

  // Helper function to both set the settings locally and propagate them to Canva
  const setAndPropagateSettings = useCallback(
    (updatedSettings: PublishSettings) => {
      setSettings(updatedSettings);
      updatePublishSettings({
        publishRef: JSON.stringify(updatedSettings),
        validityState: validatePublishRef(updatedSettings),
      });
    },
    [updatePublishSettings],
  );

  return (
    <div className={styles.scrollContainer}>
      <Rows spacing="2u">
        <Text>{settingsUiContext?.outputType.displayName}</Text>
        <FormField
          label={intl.formatMessage({
            defaultMessage: "Caption",
            description:
              "Label for the caption input field in publish settings",
          })}
          control={(props) => (
            <TextInput
              {...props}
              value={settings.caption}
              onChange={(caption) =>
                setAndPropagateSettings({ ...settings, caption })
              }
            />
          )}
        />
      </Rows>
    </div>
  );
};

// Validates the publish settings to enable/disable the publish button
// Returns "valid" when all required fields are filled
const validatePublishRef = (publishRef: PublishSettings) => {
  // caption is required
  if (publishRef.caption.length === 0) {
    return "invalid_missing_required_fields";
  }
  return "valid";
};

import type { Preview } from "@canva/intents/content";

// Type definition for publish settings
// In production, extend this to include all platform-specific settings
export interface PublishSettings {
  caption: string;
}

// Utility function to safely parse publish settings
export function parsePublishSettings(
  publishRef?: string,
): PublishSettings | undefined {
  if (!publishRef) return undefined;

  try {
    return JSON.parse(publishRef) as PublishSettings;
  } catch {
    return undefined;
  }
}

// Type guard to check if a preview is an image preview that's ready to display
export function isImagePreviewReady(preview: Preview): preview is Preview & {
  kind: "image";
  status: "ready";
  url: string;
} {
  return (
    preview.kind === "image" && preview.status === "ready" && "url" in preview
  );
}

# Content publisher intent

This example demonstrates how to use the Content Publisher intent to publish Canva designs to external platforms. It shows a social media publishing use case with posts.

For API reference docs and instructions on running this example, see: <https://www.canva.dev/docs/apps/content-publisher/>.

## What this example demonstrates

- **App Settings UI**: Platform-specific publishing settings (caption configuration)
- **App Preview UI**: Visual preview showing how the design will appear on your platform
- **Output types**: Configuring different publishing formats (social media posts)
- **Publish content**: Example implementation of the `publishContent` callback

## Implementation notes

NOTE: This example differs from what is expected for public apps to pass a Canva review:

- **Static user data**: This example uses hardcoded usernames and avatar data. Production apps should fetch real user data from your platform's API.
- **API integration**: This example uses mock data. Production apps need to implement proper API authentication, rate limiting, and error handling for the `publishContent` callback.
- **Error handling**: Production apps should have comprehensive error handling for network failures, API errors, and edge cases.
- **Validation**: Production apps should implement platform-specific validation (e.g., caption length limits, aspect ratio requirements).
- **Code structure**: The code structure is simplified. Production apps using [intents](https://www.canva.dev/docs/apps/intents/) are recommended to call the prepareContentPublisher function from src/intents/content_publisher/index.tsx