//! The Askama entry point for the described media picker.
//!
//! Shape 4 of the conversion plan (wiki `mnw-shape-conversion-plans`), step 1.
//! [`Act::fills`](quasi_router::Act::fills) is what expresses the deposit, so
//! `static/media-picker.js` is gone.
//!
//! # What a card says now
//!
//! `Act::new(filename, Action::local()).filling("body", reference)`. The
//! destination is a field name and never a caret: a webview inserts at the
//! selection, and where inside a box a value lands was never the description's
//! to say. The action is [`Destination::Local`](quasi_router::Destination), so
//! a pick makes no request at all — the old picker made none either, and the
//! two round trips this shape does cost are the open and the dismiss.
//!
//! # Three defects the shipped picker has, which this does not
//!
//! Found reading `media-picker.js:83-84` against `MediaFileResponse`
//! (`routes/storage/media.rs:66`), and none of them is a conversion decision —
//! the described version cannot have any of the three, because the value is
//! held once on the server instead of being spelled again in a browser.
//!
//! 1. **Every card is unlabelled.** The JSON field is `filename`; the script
//!    reads `f.file_name`, which is `undefined`. So `label.textContent` and
//!    `img.alt` are both the empty string on every tile.
//! 2. **The name filter matches nothing.** `card.dataset.name` comes from the
//!    same `undefined`, so typing one character hides the entire library.
//! 3. **The inserted reference is wrapped twice.** `markdown_ref` is already
//!    `![](folder/file.png)` (`media.rs:109-113`) and `_mediaPickerSelect`
//!    inserts `'![](' + ref + ')'`, so what lands in the box is
//!    `![](![](folder/file.png))`.
//!
//! Filed as its own record rather than only fixed here, because (3) means the
//! documents people have already written with this button carry broken image
//! references that no redeploy repairs.
//!
//! # Why only the grid is replaced when a filter moves
//!
//! The plan said the filter controls carry `changes` and the server re-renders
//! the grid as a fragment. It said the fragment is aimed at the modal; it is
//! aimed at [`GRID`] instead, one region further in. Replacing the modal would
//! replace the box being typed into, which takes the caret with it on every
//! keystroke.
//!
//! The name box also asks through a [`Consult`] rather than through `changes`,
//! which is the plan's one other deviation and is the same call
//! [`crate::quasi::discover_typeahead`] made: `changes` fires per keystroke and
//! a media library is a Postgres round trip, where a consult carries the wait
//! that makes it one question per pause. The folder select keeps `changes`,
//! because a select settles rather than being typed into.
//!
//! # The destination has to be unique in the document, and that is new
//!
//! [`Act::fills`] names a [`Field::name`], and a name identifies a field within
//! one description. `Filling::id_prefix` exists because that stops being true
//! when a document holds two copies of one form, and
//! [`crate::quasi::rich_field`] leans on it: five editors, all named `body`,
//! told apart by their ids.
//!
//! So an editor a picker can write into has to be the only `body` in its
//! document. Both surfaces that had a working button already are:
//! `dashboard-blog-editor.html` holds `post-body` alone, and
//! `item_details.html` holds `text-body` alone under that name. The two section
//! editors on that same page were raw `<textarea>` elements with an id and no
//! name at all, which no description can address, so they are described here
//! too and carry names of their own. See `rich_field::named`.

use makeover_layout::Fit;
use quasi_declare::declare;
use quasi_router::screen::Act;
use quasi_router::{Action, Choice, Consult, Image, Node, RegionKind, Slot};

/// The stem both region ids are built from.
const REGION: &str = "media-picker";

/// The region one editor's picker is drawn into, and the empty box its trigger
/// ships beside it.
///
/// One id for both, so the answer replaces the placeholder rather than nesting
/// inside it, and a dismissal puts the placeholder back.
///
/// **Per destination, not per page.** `item_details.html` carries three of
/// these buttons, and one shared id would be three elements answering to it —
/// which is a duplicate id whichever of them htmx then found first. A picker
/// belongs to the box it was opened for, so its region is named after that box.
#[must_use]
pub fn region_id(into: &str) -> String {
    format!("{REGION}-{into}")
}

/// The panel inside the scrim.
///
/// The modal region is the scrim — fixed, covering the viewport, and what stops
/// the page behind it being pressed — and this is the box that sits in the
/// middle of it. Two regions because a scrim and a panel are two boxes, and one
/// element cannot be both without the panel's contents being laid out across
/// the whole viewport.
#[must_use]
pub fn panel_id(into: &str) -> String {
    format!("{REGION}-{into}-panel")
}

/// The region inside one picker that holds the tiles.
///
/// Addressed separately from [`region_id`] so a filter answer leaves the filter
/// controls, and the caret in them, alone.
#[must_use]
pub fn grid_id(into: &str) -> String {
    format!("{REGION}-{into}-grid")
}

/// Whether a destination name is one this module will build ids and selectors
/// out of.
///
/// `into` arrives on a query string, so it is a reader's string by the time a
/// route hands it back here, and it lands in an `id` and inside a `#`-selector
/// in `hx-target`. Both are escaped by the emitter, so this is not what stops
/// an injection; what it stops is a selector that is escaped, well-formed and
/// means something other than the element it names. The same gate quasi's own
/// emitter puts in front of a handle it builds a program from.
///
/// Every field name in the tree is already a plain handle.
#[must_use]
pub fn addressable(into: &str) -> bool {
    !into.is_empty()
        && into.len() <= 64
        && into
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-' || byte == b'_')
}

/// Where the picker comes from, and where a filtered grid comes from.
pub const PATH: &str = "/media/picker";

/// Where the grid alone comes from.
pub const GRID_PATH: &str = "/media/picker/grid";

/// What dismissing it calls.
pub const CLOSE_PATH: &str = "/media/picker/close";

/// The name the destination field travels under.
///
/// Carried on every action the picker emits, because the picker is opened *for*
/// a box and the route rebuilds the cards against it. The shipped script held
/// the same fact in a module-level `targetTextareaId`.
pub const INTO: &str = "into";

/// The name the typed filter travels under.
///
/// Prefixed, and both of these are, because a fragment's ids come from its
/// field names and this fragment lands inside a document somebody else built.
/// A picker carrying `id="name"` into a page with a name field on it is two
/// elements answering to one id, which is what `Filling::id_prefix` exists to
/// stop inside a form and has no equivalent for a whole document.
pub const NAME: &str = "media-name";

/// The name the chosen folder travels under.
pub const FOLDER: &str = "media-folder";

/// What the panel is called, for a stylesheet.
const PANEL: &str = "media-picker";

/// What the grid of tiles is called.
const GRID_WIDGET: &str = "media-picker-grid";

/// A named assembly, which is the hook a stylesheet attaches to.
///
/// `RegionKind::Widget` rather than `Group` on all three, because that is what
/// the member is for: "the hook a stylesheet or a script attaches to in order to
/// draw the assembly the way a browser does it", and a name that is app
/// vocabulary rather than a class this renderer owns. The ids stay unique per
/// destination and are what an answer is aimed at; the widget name is what the
/// grid and the tiles are drawn by, and it is the same string on every picker in
/// the document.
fn widget(name: &str) -> RegionKind {
    RegionKind::Widget {
        name: name.to_owned(),
    }
}

/// How long the typed filter stands still before the grid is asked for.
///
/// `discover_typeahead`'s number, and for its reason: it is the wait that makes
/// a typed filter one question per pause rather than one per keystroke.
const WAIT: std::time::Duration = std::time::Duration::from_millis(150);

/// One media file, as the picker needs it.
///
/// A view of `MediaFileResponse` rather than that type, so this module names
/// what it draws and nothing else: the picker has no use for an id, a size or a
/// created-at, and taking the whole response would tie the description to the
/// JSON shape of an API route it does not call.
#[derive(Debug, Clone)]
pub struct Entry {
    /// The media file's own id, which is the tile's region id.
    ///
    /// Only here because a tile is two members and the vocabulary has no way to
    /// hold two things together without a region, and a region has an id. See
    /// the header on the gap that costs.
    pub id: String,
    /// What is read on the tile.
    pub filename: String,
    /// Which folder it is in, empty for the root.
    pub folder: String,
    /// What lands in the editor. Already a markdown image reference; this
    /// module never spells one.
    pub reference: String,
    /// Where the thumbnail comes from.
    pub url: String,
    /// Whether there is a thumbnail to show at all.
    pub image: bool,
}

/// The button that opens the picker, and the empty region it lands in.
///
/// Both together because they are one arrangement: a trigger whose answer has
/// nowhere to go is a button that swaps a modal into itself. `into` is the
/// [`Field::name`] of the editor the picked reference goes to.
#[must_use]
pub fn trigger(into: &str) -> String {
    use quasi_axum::Serves as _;

    let act = Act::new(
        "Insert Image",
        Action::get(PATH)
            .carrying(INTO, into)
            .replacing(region_id(into)),
    );

    format!(
        "{}{}",
        quasi_webview::Webview::new().fragment(&Node::Act(act)),
        dismissed(into)
    )
}

/// The picker itself: the filters, and the grid under them.
///
/// `folders` is every folder the reader has, `name` and `folder` are the
/// filters as they currently stand, and `entries` is what those filters
/// already selected — the narrowing is the route's, not this module's, because
/// a filter the server applied is one query rather than a library sent to a
/// browser to hide most of.
#[must_use]
pub fn picker(
    entries: &[Entry],
    folders: &[String],
    into: &str,
    name: &str,
    folder: &str,
) -> String {
    use quasi_axum::Serves as _;

    let mut panel = Slot::new(panel_id(into), widget(PANEL))
        .with(Node::section("Insert from Media Library"))
        .with(Node::Field(Box::new(name_filter(into, name, folder))))
        .with(Node::Field(Box::new(folder_filter(
            folders, into, name, folder,
        ))))
        .with(Node::Region(grid_slot(entries, into)));

    // Last, so the way out is the last thing a reader tabs to rather than the
    // first. It is an ordinary act calling an ordinary route: the shipped
    // dismissal was `display:none` plus a scrim click, and neither is
    // describable — a region that is there and not shown is not a state the
    // vocabulary has, and a scrim is not a control.
    panel = panel.with(Node::Act(Act::new(
        "Close",
        Action::get(CLOSE_PATH)
            .carrying(INTO, into)
            .replacing(region_id(into)),
    )));

    let region = Slot::new(region_id(into), RegionKind::Modal).with(Node::Region(panel));

    quasi_webview::Webview::new().fragment(&Node::Region(region))
}

/// The grid alone, for a filter that moved.
#[must_use]
pub fn grid(entries: &[Entry], into: &str) -> String {
    use quasi_axum::Serves as _;

    quasi_webview::Webview::new().fragment(&Node::Region(grid_slot(entries, into)))
}

/// The empty region, for a dismissal and for the page that has not opened one.
///
/// The same markup in both cases on purpose: "closed" and "never opened" are
/// one state, so there is no third thing for a reader to be in.
#[must_use]
pub fn dismissed(into: &str) -> String {
    use quasi_axum::Serves as _;

    quasi_webview::Webview::new()
        .fragment(&Node::Region(Slot::new(region_id(into), RegionKind::Group)))
}

declare! {
    /// The tiles, or the sentence that says why there are none.
    ///
    /// Two different emptinesses read the same here, and deliberately: a library
    /// with nothing in it and a filter that matched nothing both leave the
    /// reader with the filters they can see and change.
    shape grid_slot(entries: &[Entry], into: &str) -> Slot;

    region grid_id(into) as widget(GRID_WIDGET) {
        text "No media files match. Upload images in your Media Library tab first."
            when entries.is_empty();

        for entry in entries.iter() {
            include card(entry, into);
        }
    }
}

declare! {
    /// One tile: one control, showing the thumbnail and saying the file name.
    ///
    /// The label is the file name, which is the fact the shipped script lost to
    /// a misspelled JSON key. The deposit is `markdown_ref` verbatim, which is
    /// the fact that script wrapped twice.
    ///
    /// `local`, so the press makes no request. The old picker made none either;
    /// what it did instead was 155 lines of DOM building.
    ///
    /// # This was two members and half a tile until quasi 0.69.0
    ///
    /// The conversion found that an [`Act`] was a label and nothing said a
    /// control reads as a picture, so the tile was a region holding the picture
    /// and the control as siblings and only the file name answered a press -- a
    /// reader aiming at the thumbnail, which is the whole affordance of a
    /// picture picker, hit nothing. `Act::shows` (quasicoherent `db998898`) is
    /// that member, and the tile is one control again.
    ///
    /// The region went with it, and so did the id it needed. [`Entry::id`] is
    /// kept for the caller's convenience and no longer addresses anything.
    shape card(entry: &Entry, into: &str) -> Node;

    act &entry.filename to local {
        filling into &entry.reference;
        // The alt is the file name, because that is what the tile is for: a
        // reader who cannot see the thumbnail is choosing between file names,
        // which is exactly what the control says. The fit is the letterbox the
        // shipped tile did with `object-fit: contain`: a thumbnail grid whose
        // files are not all one shape, and the whole picture matters more than
        // filling the square.
        showing Image::new(&entry.url, &entry.filename).lazy().fit(Fit::Contain)
            when entry.image;
    }
}

declare! {
    /// The typed filter.
    ///
    /// It asks rather than writes: see this module's header on why a consult and
    /// not `changes`. The folder rides along under [`Consult::sending`], so
    /// narrowing by name inside a folder stays inside it.
    ///
    /// The folder is also carried on the action, which looks redundant and is
    /// the fallback: htmx drops an address parameter whose name the payload
    /// repeats, so the live select wins whenever it is found, and the carried
    /// value is what a document with no select in reach sends instead.
    ///
    /// `sending` names a field document-wide, which is the vocabulary's own
    /// reading. A document holding two open pickers would therefore match two
    /// selects and send both values. Not guarded, because a picker is a modal
    /// covering the viewport and a reader cannot reach the second trigger while
    /// the first is open; recorded so the next reader knows it was seen rather
    /// than missed.
    shape name_filter(into: &str, name: &str, folder: &str) -> Field;

    field Text NAME "Filter by name" {
        consulting Consult::new(
            Action::get(GRID_PATH)
                .carrying(INTO, into)
                .carrying(FOLDER, folder)
                .replacing(grid_id(into)),
        )
        .after(WAIT)
        .sending([FOLDER]);
        placeholder "Filter by name...";
        value name;
    }
}

declare! {
    /// The folder chooser.
    ///
    /// A consult and not a write: it narrows what the grid shows and puts
    /// nothing anywhere. `Consult::at_once` because a select is at its next
    /// value or its last one and there is nothing to wait out -- which is the
    /// half `aeb44860` left with the description after moving the event to the
    /// renderer. It carries the typed filter forward on the action, because a
    /// field's question sends its own value and nothing else.
    shape folder_filter(folders: &[String], into: &str, name: &str, folder: &str) -> Field;

    field Select FOLDER "Folder" {
        options folder_choices(folders);
        consulting Consult::at_once(
            Action::get(GRID_PATH)
                .carrying(INTO, into)
                .carrying(NAME, name)
                .replacing(grid_id(into)),
        );
        value folder;
    }
}

/// Every folder the reader has, under an "All folders" that clears the filter.
///
/// A supplier because a list built from an iterator is what the deferred table
/// names one for. The root folder is the empty string and reads as `(root)`,
/// which is the one place a folder's value and its label differ.
fn folder_choices(folders: &[String]) -> Vec<Choice> {
    let mut options = vec![Choice::new("", "All folders")];
    options.extend(
        folders
            .iter()
            .map(|folder| Choice::new(folder, if folder.is_empty() { "(root)" } else { folder })),
    );
    options
}

#[cfg(test)]
mod tests {
    use super::*;

    fn entry(filename: &str, folder: &str) -> Entry {
        let reference = if folder.is_empty() {
            format!("![]({filename})")
        } else {
            format!("![]({folder}/{filename})")
        };
        Entry {
            id: "11111111-1111-1111-1111-111111111111".to_owned(),
            filename: filename.to_owned(),
            folder: folder.to_owned(),
            reference,
            url: format!("https://cdn.test/{filename}"),
            image: true,
        }
    }

    /// The whole point of the conversion, and the member it waited eleven days
    /// for: a card names the box it writes into and what lands there.
    #[test]
    fn a_card_names_the_editor_it_writes_into_and_the_reference_it_deposits() {
        let html = grid(&[entry("kick.png", "drums")], "body");

        assert!(html.contains(r#"data-fills="body""#), "{html}");
        assert!(
            html.contains(r#"data-fill="![](drums/kick.png)""#),
            "{html}"
        );
        // Local, so the press is not a request. The shipped picker made none
        // either; this says so in the description rather than by omission.
        assert!(html.contains("data-local"), "{html}");
        assert!(!html.contains("hx-get"), "{html}");
    }

    /// The tile is two members and the picture is one of them. Half a tile is
    /// pressable, which is the gap this conversion found: an `Act` is a label,
    /// so nothing says a control reads as a picture.
    #[test]
    fn a_tile_shows_the_thumbnail_beside_the_control() {
        let html = grid(&[entry("kick.png", "drums")], "body");

        assert!(
            html.contains(r#"src="https://cdn.test/kick.png""#),
            "{html}"
        );
        // The alt is the file name, because choosing without the thumbnail is
        // choosing between names, which is what the control below says too.
        assert!(html.contains(r#"alt="kick.png""#), "{html}");
        assert!(html.contains(r#"loading="lazy""#), "{html}");
        // The fit is in the description, and it is what lets `style.css` cap
        // the tile's height with `max-height` alone: the design system already
        // owns this picture's width, height and background, and an app rule
        // taking one of those is what `makeover-build`'s drift check refuses.
        assert!(html.contains(r#"data-fit="contain""#), "{html}");
        // And the tile is the control, since quasi 0.69.0: the picture is
        // inside the element that answers the press, so aiming at the thumbnail
        // picks the file. It was a `media-card-<id>` region holding the picture
        // and the button as siblings, and only the button answered.
        assert!(
            !html.contains("media-card-"),
            "the per-tile region is gone: {html}"
        );
        let control = html
            .split_once("<button")
            .and_then(|(_, rest)| rest.split_once("</button>"))
            .map_or("", |(inner, _)| inner);
        assert!(control.contains("<img"), "{html}");
        assert!(control.contains("kick.png"), "{html}");
    }

    /// A video has no thumbnail to show, so it is the control alone rather than
    /// a broken image.
    #[test]
    fn a_file_with_nothing_to_show_is_the_control_alone() {
        let mut clip = entry("intro.mp4", "");
        clip.image = false;
        let html = grid(&[clip], "body");

        assert!(!html.contains("<img"), "{html}");
        assert!(html.contains("intro.mp4"), "{html}");
    }

    /// Defect 1 of the three in the header. `media-picker.js` reads
    /// `f.file_name` and the JSON says `filename`, so every tile shipped
    /// unlabelled.
    #[test]
    fn a_card_reads_as_its_file_name() {
        let html = grid(&[entry("kick.png", "drums")], "body");
        assert!(html.contains("kick.png"), "{html}");
    }

    /// Defect 3. `markdown_ref` already carries the wrapper, so what the
    /// shipped button inserted was `![](![](drums/kick.png))`.
    #[test]
    fn a_reference_is_deposited_exactly_once() {
        let html = grid(&[entry("kick.png", "drums")], "body");
        assert!(!html.contains("![](![]("), "{html}");
    }

    /// A file name is a reader's string on its way into an attribute, which is
    /// the one thing the shipped script got right and got right the hard way,
    /// with `textContent` and `dataset`. Here it is the emitter's ordinary
    /// escaping, in both places a name lands.
    #[test]
    fn a_crafted_file_name_stays_a_value() {
        let html = grid(&[entry(r#"" onclick="alert(1)"#, "")], "body");

        assert!(!html.contains(r#"" onclick=""#), "{html}");
        assert!(html.contains("&quot;"), "{html}");
    }

    /// The filters ask for the grid and not for the modal, so the box being
    /// typed into survives its own answer.
    #[test]
    fn a_filter_replaces_the_grid_and_leaves_the_box_it_was_typed_into() {
        let html = picker(
            &[entry("kick.png", "")],
            &["drums".to_owned()],
            "body",
            "",
            "",
        );

        assert!(
            html.contains(r##"hx-target="#media-picker-body-grid""##),
            "{html}"
        );
        assert!(html.contains(r#"hx-get="/media/picker/grid?"#), "{html}");
        // And the wait, which is what makes a typed filter one question per
        // pause rather than one per keystroke against Postgres.
        assert!(html.contains("delay:150ms"), "{html}");
    }

    /// The folder chooser's options, which are a supplier's list now rather
    /// than an argument to `Field::select`. The root folder reads as `(root)`
    /// and is the one place a folder's value and its label differ.
    #[test]
    fn the_folder_chooser_offers_every_folder_and_a_way_to_clear_it() {
        let html = picker(
            &[],
            &["drums".to_owned(), String::new()],
            "body",
            "",
            "drums",
        );

        assert!(html.contains("All folders"), "{html}");
        assert!(html.contains("drums"), "{html}");
        assert!(html.contains("(root)"), "{html}");
    }

    /// The picker is opened for a box, so every action it emits carries which
    /// one. The shipped script held this in a module-level variable.
    #[test]
    fn every_action_carries_the_editor_the_picker_was_opened_for() {
        let html = picker(&[entry("kick.png", "")], &[], "post-body", "", "");
        assert!(html.contains("into"), "{html}");
        assert!(html.contains("post-body"), "{html}");
    }

    /// A modal, said in a word every renderer reads rather than in a fixed
    /// position and a scrim.
    #[test]
    fn the_picker_is_a_modal_and_says_so() {
        let html = picker(&[], &[], "body", "", "");
        assert!(html.contains(r#"role="dialog""#), "{html}");
        assert!(html.contains(r#"aria-modal="true""#), "{html}");
    }

    /// Closed and never-opened are one state, so a page holds the same empty
    /// region before the first press and after the last dismissal.
    #[test]
    fn a_dismissal_leaves_the_region_the_page_started_with() {
        let opened = trigger("body");
        assert!(opened.contains(&dismissed("body")), "{opened}");
        assert!(
            dismissed("body").contains(r#"id="media-picker-body""#),
            "{}",
            dismissed("body")
        );
        assert!(!dismissed("body").contains("kick.png"));
    }

    /// The trigger opens the picker into the region beside it, rather than
    /// swapping a modal into the button that asked for it.
    #[test]
    fn the_trigger_aims_at_the_region_it_ships_with() {
        let html = trigger("body");
        assert!(
            html.contains(r#"hx-get="/media/picker?into=body""#),
            "{html}"
        );
        assert!(
            html.contains(r##"hx-target="#media-picker-body""##),
            "{html}"
        );
    }

    /// An empty library and an empty filter result read the same, and neither
    /// is a blank box.
    #[test]
    fn nothing_to_show_says_so() {
        let html = grid(&[], "body");
        assert!(html.contains("No media files match"), "{html}");
    }
}