Let custom field types open the media picker

[odama626]

Background

addFile() covers half of what a File/Image-like custom field needs: a control can hand the CMS a file and have it uploaded with the entry, with folder resolution, naming, deduplication and the editorial workflow all handled. Thanks for that; it removed a lot of fragile code from my widget.

The other half is missing. A custom control can add a new file but can't let the user pick one that already exists. The public API is init, getFieldType, renderRichText, registerCustomFormat, registerEditorComponent, registerEventListener, registerFieldType, registerPreviewStyle and registerPreviewTemplate, and controls receive value, field, forID, classNameWrapper, entry, onChange, addFile and ref. Nothing reaches the asset library, and image and file aren't in REUSABLE_BUILTIN_FIELD_TYPES, so getFieldType('image') can't be used to borrow the built-in UI either.

Use case

A field type that stores an image plus derived data: { original, tiny, optimized, aspectRatio }. The control generates a thumbnail and a resized WebP in the browser and stores all three paths and the ratio. Upload works well. Choosing an image already in the repo does not, so editors have to re-upload a file that's already there, and the widget has to reimplement browsing, search, previews and stock integrations to offer anything close to the built-in experience.

Any custom field type that stores a path in a shape of its own hits this: an image with alt text and focal point, a gallery with per-item captions, a download with a label.

Proposal

A control prop that opens the same Select Assets dialog the built-in File/Image field uses, resolved with what the user picked:

const asset = await this.props.pickFile({ accept: 'image/*' });
// → { path, url, file } | null when dismissed

path would be the public path to store, matching what a built-in Image field would write for the same asset, and file a Blob/File for controls that need the bytes, which is what my widget needs to derive its thumbnail. null on dismiss keeps the call site simple.

Options worth having, all optional: accept to filter by type, multiple for controls holding several files, and possibly folder for a control that wants a specific library folder rather than the field's default.

Everything else already exists behind the dialog: folder resolution matches what addFile() does today via getAssetLibraryFolderMap(), and the public path comes from getAssetPublicURL().

Alternative considered

Adding image and file to REUSABLE_BUILTIN_FIELD_TYPES would also solve it, but those editors read and write the draft store directly, and a control composing one would be stuck with the built-in value shape, which is the thing these field types need to change.

Version

@sveltia/cms 0.210.2

[kyoshino]

Will check.

[kyoshino]

Claude implemented addFile and pointed out this is the relevant Netlify/Decap CMS issue, which was closed as stale:

• Interacting with Media library from Custom Widget decaporg/decap-cms#3927

We’ll ship it today or tomorrow.

[kyoshino]

Done in v0.211.0 🎉 Doc