RenewCMS/docs/design/screens/media-picker.md

Media picker

Route: /article/:id/edit, /articles/{id}/edit. API: GET /v1/media/?q=&limit=&cursor= · POST /v1/media/ (same as the Media page) · Inserted URL: /media/{file}?v={name}.

The existing "Add an image" dialog gains two tabs, Upload and Library. The Upload tab is the current flow unchanged, so it still offers crop and resize, and a new image lands in the library and is inserted as before. The Library tab opens on the Library tab when the library has images and on Upload when it is empty. Images load 24 at a time with "Load more". Newest first, and images already in this article carry "In this article". Alt text is set here and lives only in the article. The dialog is 640 px wide on desktop and a bottom sheet on mobile.

Visual reference: RenewCMS Screens Back-office.dc.html, groups "Media picker", "Editor picker". Frames: AppFrame.dc.html (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.

Copy per state (generated from the board source, pass 2)

Every state below is drawn in light and dark (theme switch on the board), at 1440×900 and 390×844 (both frames sit side by side). Board: RenewCMS Screens Back-office.dc.html. Copy is exact; where a cell is empty the state reuses the fixed copy.

Picker in the editor (group "Media picker", 13 states)

Route: /article/:id/edit. API: GET /v1/media/?q=&limit=&cursor= · POST /v1/media/ (same as the Media page).

The existing "Add an image" dialog gains two tabs, Upload and Library. The Upload tab is the current flow unchanged, so it still offers crop and resize, and a new image lands in the library and is inserted as before. The Library tab opens on the Library tab when the library has images and on Upload when it is empty. Images load 24 at a time with "Load more". Newest first, and images already in this article carry "In this article". Alt text is set here and lives only in the article. The dialog is 640 px wide on desktop and a bottom sheet on mobile.

#	State	Trigger	Copy
1	Upload tab	The image button in the toolbar. Identical to the current "Add an image" content; only the tabs are new. Rejected, uploading and failed states are unchanged.	"Upload"
2	Upload tab: already in your library	A chosen file has the same content as an existing image. Nothing is sent. "Use existing" inserts the existing image (the alt text step follows); "Upload anyway" continues to crop and upload as usual.	"Upload"
3	Library: loading	The Library tab was opened, or a search changed. Skeleton tiles after 150 ms.
4	Library: nothing selected	Newest first. Tiles are buttons labelled with filename, size and use, and Enter or Space selects. Images already in this article carry "In this article". "Insert image" is disabled.
5	Library: selected	One image selected (single selection). Below the grid: thumbnail, filename, dimensions and size, and an optional alt text field. "Insert image" turns on.
6	Library: alt text entered	Alt text is optional. Empty alt text is inserted as a decorative image. It is not saved on the image.	"A kitchen with new oak worktops and white tiles"
7	Library: loading more	"Load more" pressed. The button shows progress and new skeleton tiles appear at the end. Focus stays on the button until the new tiles arrive, then moves to the first new tile.
8	Library: empty	Zero images. "Upload an image" switches to the Upload tab.
9	Library: no results	Search matched nothing. "Clear search" resets it.
10	Library: failed to load	A 500 or network failure. The error shows in the dialog and Try again repeats the request. A 429 uses the same countdown alert as the Media page, and a 401 is handled globally.
11	Inserted	Insert image from either tab. The image goes in at the cursor with the chosen alt text, and the article now has unsaved changes.	"Image added" / "Save to keep it in the article."
12	Remove image: confirm	Remove image on an image in the article. It now only removes it from this article, and the copy says the file stays in the library. The confirm button is neutral, not red, because nothing is deleted. Title: "Remove this image from the article?"
13	Removed	Confirmed. The image leaves the article body, which now has unsaved changes.	"Image removed" / "It's still in your library."

6. Editor image picker (group "Editor picker", 5 states)

Route: /articles/{id}/edit. API: Inserted URL: /media/{file}?v={name}.

The Library tab of the picker gets a Variant select. Options are Original plus the enabled variants, each with its dimensions and format. Once inserted, a block whose variant was deleted or disabled shows an inline warning with a way to fix it. Disabled variants do not appear in the select.

#	State	Trigger	Copy
1	Variant select	An image is selected. The URL line shows what will be inserted.	"Articles" / "How we price a bathroom renovation" / "Edit article"
2	Select open	Original plus five enabled variants.	"Articles" / "How we price a bathroom renovation" / "Edit article"
3	No variants defined	Only Original is offered.	"Articles" / "How we price a bathroom renovation" / "Edit article"
4	Variant deleted	The block keeps its URL. Pick another variant opens the select.	"Articles" / "How we price a bathroom renovation" / "Edit article" / "Variant 'hero' no longer exists."
5	Variant disabled	Same block, different cause. Proposed copy.	"Articles" / "How we price a bathroom renovation" / "Edit article" / "Variant 'hero' is disabled."