Issue-836 Document Types

[scotthillson]

Description

Allow all file types in Documents except for images and videos. The Media collection is for images and videos. See issue for more detail.

Related Issues

#836

Key Changes

Adds a layout field to the Document block so editors can choose between embedding a PDF in an iframe or showing a download link button. Also removes the hardcoded mimeTypes allowlist from the Documents collection and replaces it with a validation hook that blocks only images and videos, allowing any other file type (PDFs, KML, XML, etc.) to be uploaded without needing to enumerate every MIME type.
The iframe title was generalized from "Document PDF" to "Document" since non-PDF files can now be embedded.

How to test

Upload a PDF to the Documents collection — should succeed
Try to upload an image file into documents, you'll see a toast error

Screenshots / Demo video

Migration Explanation

Adds a layout column (nullable select) to the blocks_document table. No data is destroyed; existing rows get null which the component treats as embed.

[github-actions]

Preview deployment: https://issue-836.preview.avy-fx.org

[busbyk]

Thanks for the contribution @scotthillson!

I've requested a few changes. Let me know if you have any questions.

[busbyk]

I just added to our docs/coding-guide.md to outline our preferences for migration naming and resolving migration conflicts when merging in main has new migrations. Can you please follow those instructions and update this PR's migrations accordingly? #1077

[busbyk]

If there is no browser viewer for a given file type and the layout is set to embed, the file is automatically downloaded when visiting the page that the DocumentBlock is on:

I can't find the behavior documented anywhere but it seems that if we set an iframe's src attribute to a file with a MIME type that it does not have a built-in viewer for, the file is automatically downloaded when the iframe is rendered. We definitely don't want this behavior so we need to account for this.

It seems that PDF, HTML, Plain text, and XML/KML can all be rendered in an iframe. So we need conditional logic in the collection that only allows setting the displayAs field to embed when the file's MIME type is one of ['application/pdf', 'text/html', 'text/plain', 'text/xml', 'application/xml', 'application/vnd.google-earth.kml+xml', '.kml']. If we discover there are other MIME types that browsers can reliably render, we could add to that list.

[busbyk]

This was a good assumption to make but I think we should fallback to download due to the browser behavior that might result in a file being automatically downloaded if the browser can't render it in an iframe. See my other comment.

We only have one page with DocumentBlocks in production, so this would be easy enough to go and update manually after we deploy this.

[rchlfryn]

@scotthillson Checking in to see if you need any help. Let us know!

[github-actions]

Migration Safety Check

Found 4 potential issues:

20260809_234316_add_display_as_to_document_block.ts

Warning (line 6): ALTER keyword detected - review for data loss

sql`ALTER TABLE \`home_pages_blocks_document_block\` ADD \`display_as\` text DEFAULT 'download';`,

Warning (line 9): ALTER keyword detected - review for data loss

sql`ALTER TABLE \`_home_pages_v_blocks_document_block\` ADD \`display_as\` text DEFAULT 'download';`,

Warning (line 12): ALTER keyword detected - review for data loss

sql`ALTER TABLE \`pages_blocks_document_block\` ADD \`display_as\` text DEFAULT 'download';`,

Warning (line 15): ALTER keyword detected - review for data loss

sql`ALTER TABLE \`_pages_v_blocks_document_block\` ADD \`display_as\` text DEFAULT 'download';`,

---

Review these patterns and add backup/restore logic if needed. See docs/migration-safety.md for guidance.

[scotthillson]

Hey! @busbyk I think this is ready for another pass. Fingers crossed I have this knocked out in just the 1-2 passes!

[rchlfryn]

Apologies for the delay in the review. Other priorities kept getting in the way. Because of the delay you will need to merge/rebase main and rerun the migration to get the latest.

[rchlfryn]

This won't allow HTML and re-breaks the old allowlisted types.

Uploading HTML fails with Restricted file type detected -- set 'allowRestrictedFileTypes' to true. That's Payload core (checkFileRestrictions), not the hook. When mimeTypes is absent, it enforces a built-in blocklist (text/html, php, js, exe…) and throws before the hook runs. Removing the allowlist also drops the pdf/php/xml/kml types the old list permitted.

Fix — keep an allowlist instead of removing it:

 upload: {
   staticDir: path.resolve(dirname, '../../../public/documents'),
   mimeTypes: [
     'application/pdf',
     'application/xml',
     'text/xml',
     'application/octet-stream',
     'application/vnd.google-earth.kml+xml',
     '.kml',
     'text/html',
     'text/csv',
   ],
 },

A set mimeTypes bypasses the blocklist, so HTML passes while unlisted executables stay blocked. validateNotImageOrVideo can be dropped (image/video just aren't listed).

The alternative (remove mimeTypes + allowRestrictedFileTypes: true) matches the issue literally but also permits .exe/.js on public URLs. Given staff-only uploads of static docs, the allowlist seems safer.

[rchlfryn]

Existing Document blocks render as embedded iframes today. After this PR they flip to download links. The migration backfills display_as to 'download', and this line resolves anything not explicitly 'embed' to download. So every published PDF becomes a download button on deploy. I think we can just pass displayAs as is instead of creating a place for this to silently fail. Remove this and update to check displayAs below.

Suggested change

const resolvedDisplay = displayAs === 'embed' && isEmbeddable ? 'embed' : 'download'

Also adding required: true will remove the possibility of this being null

[rchlfryn]

Let's add required: true here to remove the possibility of null

[rchlfryn]

This should be passed in DocumentBlockProps so we don't need to add it here

Suggested change

	// displayAs is present in the block config but absent from generated types until pnpm generate:types is run
	displayAs?: 'download' | 'embed' | null