makeover-layout 0.52.4

//! The adaptation members: which affordances exist at a given input class
//! and window size class.
//!
//! <!-- wiki: makeover-touch -->
//!
//! `makeover` answers *what colour*. `makeover-geometry` answers *how much
//! space*, and owns the two axes an adaptation is stated against:
//! [`Density`] (pointer or touch) and [`SizeClass`] (compact, medium,
//! expanded). The rest of this crate answers *what the thing is*. This
//! module answers one question and no other:
//!
//! > Does this affordance exist here?
//!
//! Like the rest of the crate it emits nothing. It is a description, rendered
//! to CSS by `makeover-webview` and to whatever the other renderers can express.
//!
//! # Why this is a description and not a density preset
//!
//! What an adaptive stylesheet changes falls into buckets, and each has an
//! owner:
//!
//! | bucket | retired by |
//! |---|---|
//! | density | a `makeover-geometry` preset |
//! | type | the type scale |
//! | columns | [`ColumnRoom`](crate::ColumnRoom) |
//! | reflow | [`Arrangement`](crate::Arrangement) |
//! | **show/hide** | **[`Affordance`]** |
//! | **reposition** | **[`Affordance`]** |
//! | **appearance** | **[`Affordance`]** |
//!
//! The bottom three are what no spacing scale can retire. `display: none` on a
//! keyboard hint says *the affordance does not exist on touch*. No amount of
//! gap retuning expresses that, and a scale that tried would be putting a
//! product claim on a measurement axis.
//!
//! [`Affordance::Gesture`] and [`Affordance::Haptic`] adapt *behaviour*, which
//! no stylesheet contains. Without them the density question gets answered in
//! script by sniffing (`'ontouchstart' in window`), where no stylesheet can see
//! it.
//!
//! # The two axes are borrowed, never redefined
//!
//! Boundaries are not this module's job. `makeover-geometry` quotes Material 3's
//! window size classes at 600 and 840 and carries [`Density`]; this module names
//! affordances *against* those two and adds no third axis, no fourth class and
//! no breakpoint of its own. If a rule here wants a boundary that does not
//! exist, that is a conversation with `makeover-geometry`, not a constant.
//!
//! # What density is allowed to gate
//!
//! Density is a claim about **the contact patch and nothing else**. So it gates
//! affordances that depend on an interaction a fingertip cannot perform:
//! hovering, and the keyboard chrome that documents shortcuts a touch surface
//! has no way to send. It does not gate anything that is really about how much
//! screen there is. A phone is small *and* touch; a tablet is big *and* touch.
//!
//! `density_gates_only_what_the_contact_patch_touches` asserts that separation. Putting a screen-budget
//! claim on the input device is the failure this module exists to prevent, and
//! re-introducing it has to come to the test and say so.
//!
//! # Both densities gain something
//!
//! Touch is not pointer minus what a fingertip cannot do.
//! [`Affordance::Hover`]'s own doc says a fingertip has no hover state *and that
//! something else has to carry the same actions*, so something here has to be
//! that something. [`Affordance::Anchored`] and [`Affordance::Overflow`]
//! compensate on the size axis; [`Affordance::Gesture`] and
//! [`Affordance::Haptic`] compensate on the density axis, and both are gained
//! by touch rather than lost to it.
//!
//! [`Affordance::gained_by`] makes each member declare which density it belongs
//! to, and
//! `a_density_member_is_available_on_exactly_the_density_it_declares` checks the
//! declaration against the rule. So a new member still cannot quietly invert:
//! it has to say which way it goes, in code, and the test is where a wrong
//! answer surfaces.
//!
//! # Collapsing is allowed, inverting is not
//!
//! Borrowed verbatim from `makeover-geometry`, where two gap relationships both
//! resolve to zero cells on a terminal and stay two members regardless. Two
//! affordances here may have identical availability ([`Affordance::Hover`] and
//! [`Affordance::Hint`] do) and are still two members, because the call
//! site names *what is being gated*, not the rule. What must never happen is
//! one of them becoming available where the other is not for a reason that is
//! really the same reason.
//!
//! # Deliberately absent
//!
//! **A navigation shell fork.** Two navigation shells behind one breakpoint are
//! two shells rather than one shell adapting, and choosing to build two is a
//! product decision. This module will not describe it. Named here the way
//! the crate names validation absent, so nobody has to discover it.
//!
//! **Which columns a narrow window keeps.** A column is ranked rather than
//! gated, so the cutoff for a size class lives with the ranking, in
//! [`ColumnRoom`](crate::ColumnRoom).
//!
//! **Which class applies.** The app decides, from a measured width via
//! [`SizeClass::at_width`] and from whatever it already knows about the input.
//! This module takes both as arguments and never sniffs.
//!
//! **What a renderer does when an affordance is unavailable.** Hiding it,
//! substituting it, or showing it unconditionally anyway is renderer policy.
//! The crate already deleted `Fill::fallback` for being exactly that.

use makeover_geometry::{Density, SizeClass};

/// An affordance whose existence depends on the surface it is offered on.
///
/// Drawn from what apps already gate by hand rather than from a taxonomy.
/// The crate's admission rule applies and is the reason each addition has to
/// point at call sites rather than at a category:
/// guessing is how a description becomes a framework.
///
/// Each answers [`Self::available`] against the two axes and nothing else. An
/// affordance that is always available is not an affordance this module has
/// anything to say about, and `every_member_is_an_adaptation` asserts none has
/// snuck in.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Affordance {
    /// Anything a consumer reveals on hover: a row's action cluster, a
    /// hover toolbar, a preview popover.
    ///
    /// The crate records hover-revealed row actions as behaviour of
    /// [`RowPart::Actions`](crate::RowPart::Actions) rather than as app policy. A fingertip has no hover
    /// state at all, so the affordance does not exist on touch, and something
    /// else has to carry the same actions: [`Self::Gesture`].
    Hover,
    /// Chrome documenting a keyboard interaction: shortcut badges, key hints,
    /// a "press / to search" line.
    ///
    /// Strictly this is a claim about
    /// having a keyboard rather than about the contact patch, and [`Density`]
    /// is the closest honest proxy the family carries. Stated rather than
    /// hidden, because a detachable-keyboard tablet is where the proxy breaks
    /// and a third axis is what fixing it would cost.
    Hint,
    /// A secondary panel standing beside the primary content: a saved-views
    /// rail, a filter sidebar, an inspector.
    ///
    /// Purely a screen-budget claim (a touchscreen laptop should keep it), so
    /// this reads [`SizeClass`] alone.
    Ancillary,
    /// The detail half of a list-detail split, shown *alongside* the list
    /// rather than navigated to.
    ///
    /// Unavailable is not the same as absent: the detail still exists, it is
    /// reached by navigation instead of by adjacency, and which of the two a
    /// screen gets is what [`Arrangement`](crate::Arrangement) is describing.
    Detail,
    /// Navigation or a primary action cluster pinned to a fixed screen edge
    /// instead of sitting in the flow of the page.
    ///
    /// The reposition bucket. It exists to compensate for what a compact window cannot hold in flow,
    /// so unlike the two above it is available at the *narrow* end and not the
    /// wide one. That inversion is the point: an adaptation that only ever
    /// removes things describes a degraded layout rather than a different one.
    Anchored,
    /// An action cluster collapsed behind one control rather than laid out
    /// inline.
    ///
    /// The other compensating member. [`ColumnRoom::kept_at`](crate::ColumnRoom::kept_at)
    /// already handles a *table* narrowing by dropping columns; this is the
    /// same pressure on a cluster of controls, which cannot drop any of them
    /// and folds instead.
    Overflow,
    /// A direct-manipulation gesture on content: swipe-to-action, long-press to
    /// select, pull to refresh, swipe to navigate, drag to dismiss.
    ///
    /// The density axis's compensating member, and the answer to the question
    /// [`Self::Hover`] asks and cannot answer. A fingertip has no hover state,
    /// so the row actions a pointer reveals by hovering have to arrive some
    /// other way; on both webview apps that way is a swipe.
    ///
    /// **One member for five gestures, on purpose.** Apps gate all five behind
    /// one fact about the surface, so five members would be minted from one.
    /// If a surface ever offers swipe without long-press, splitting this is
    /// additive and the call sites that named `Gesture` keep meaning what they
    /// meant.
    Gesture,
    /// Confirmation delivered through the contact patch rather than the eye: the
    /// tick as a drag crosses a threshold, the thump as a gesture fires.
    ///
    /// A contact-patch claim, which is what makes it this module's business
    /// despite being the one member nothing on screen shows.
    ///
    /// The proxy breaks where the hardware has haptics and the user or the OS
    /// has switched them off. That is neither [`Density`] nor [`SizeClass`], and
    /// it is stated here rather than fixed for the same reason [`Self::Hint`]
    /// states the detachable-keyboard case: a third axis is what fixing it would
    /// cost. **This member says the surface can, never that the user wants.**
    /// Asking the platform whether haptics are enabled is the renderer's job.
    Haptic,
}

impl Affordance {
    /// Whether this affordance exists on a surface with the given input class
    /// and screen budget.
    ///
    /// The whole module in one call. A renderer asks per affordance and never
    /// branches on a width.
    #[must_use]
    pub const fn available(self, density: Density, size: SizeClass) -> bool {
        match self {
            // Contact patch, lost to a fingertip.
            Self::Hover | Self::Hint => matches!(density, Density::Pointer),
            // Contact patch, gained by one. A mouse can neither swipe a row nor
            // feel a confirmation, and a phone-sized window has nothing to do
            // with either.
            Self::Gesture | Self::Haptic => matches!(density, Density::Touch),
            // Screen budget. The input device has no opinion about any of them.
            Self::Ancillary => matches!(size, SizeClass::Expanded),
            Self::Detail => matches!(size, SizeClass::Medium | SizeClass::Expanded),
            Self::Anchored | Self::Overflow => matches!(size, SizeClass::Compact),
        }
    }

    /// Which [`Density`] this affordance belongs to, or `None` when it reads the
    /// screen budget instead.
    ///
    /// Each member declares its own direction, and
    /// `a_density_member_is_available_on_exactly_the_density_it_declares` holds
    /// the declaration to the rule. There is no module-wide one-directional
    /// rule: see the module doc.
    ///
    /// Exposed rather than kept private for the same reason [`Self::reads_density`]
    /// is: it is the module's claim about itself, and a renderer that has one
    /// density can read it directly instead of probing [`Self::available`] twice.
    #[must_use]
    pub const fn gained_by(self) -> Option<Density> {
        match self {
            Self::Hover | Self::Hint => Some(Density::Pointer),
            Self::Gesture | Self::Haptic => Some(Density::Touch),
            Self::Ancillary | Self::Detail | Self::Anchored | Self::Overflow => None,
        }
    }

    /// Which of the two axes this affordance's availability reads.
    ///
    /// Declared per member rather than derived, so the tests can hold each
    /// declaration against what [`Self::available`] actually does.
    #[must_use]
    pub const fn axis(self) -> AffordanceAxis {
        match self {
            Self::Hover | Self::Hint | Self::Gesture | Self::Haptic => AffordanceAxis::Density,
            Self::Ancillary | Self::Detail | Self::Anchored | Self::Overflow => {
                AffordanceAxis::Size
            }
        }
    }

    /// Whether this affordance's availability reads [`Density`] at all.
    ///
    /// Exposed rather than kept private because it is the module's own claim
    /// about itself: exactly the members gating a contact-patch interaction say
    /// yes. A renderer with one density can skip the rest entirely.
    #[must_use]
    pub const fn reads_density(self) -> bool {
        matches!(self.axis(), AffordanceAxis::Density)
    }

    /// Whether this affordance's availability reads [`SizeClass`] at all.
    #[must_use]
    pub const fn reads_size(self) -> bool {
        matches!(self.axis(), AffordanceAxis::Size)
    }

    /// Every member, in declaration order.
    ///
    /// A slice rather than an array, so a new member changes a length and not
    /// a type: `Affordance` is `#[non_exhaustive]` for exactly that reason.
    #[must_use]
    pub const fn all() -> &'static [Self] {
        &[
            Self::Hover,
            Self::Hint,
            Self::Ancillary,
            Self::Detail,
            Self::Anchored,
            Self::Overflow,
            Self::Gesture,
            Self::Haptic,
        ]
    }

    /// The CSS class name an app may hang off this, without the leading dot.
    ///
    /// Present for the same reason [`SizeClass::token`] is: a webview renderer
    /// needs a stable name, and minting it per app is how two apps end up with
    /// `has-hover` and `hover-capable`.
    #[must_use]
    pub const fn token(self) -> &'static str {
        match self {
            Self::Hover => "offers-hover",
            Self::Hint => "offers-hint",
            Self::Ancillary => "offers-ancillary",
            Self::Detail => "offers-detail",
            Self::Anchored => "offers-anchored",
            Self::Overflow => "offers-overflow",
            Self::Gesture => "offers-gesture",
            Self::Haptic => "offers-haptic",
        }
    }
}

/// The axis an [`Affordance`] reads: the input class or the screen budget.
///
/// Every member reads exactly one. `#[non_exhaustive]` because a member that
/// genuinely read both would be added here as a third answer, and
/// `no_member_reads_both_axes` is where that claim would be withdrawn.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum AffordanceAxis {
    /// [`Density`]: pointer or touch.
    Density,
    /// [`SizeClass`]: compact, medium or expanded.
    Size,
}

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

    /// Whether `a`'s availability changes with density at any size.
    fn varies_by_density(a: Affordance) -> bool {
        SizeClass::all()
            .iter()
            .any(|&s| a.available(Density::Pointer, s) != a.available(Density::Touch, s))
    }

    /// Whether `a`'s availability changes with size at either density.
    fn varies_by_size(a: Affordance) -> bool {
        [Density::Pointer, Density::Touch].iter().any(|&d| {
            SizeClass::all()
                .iter()
                .any(|&s| a.available(d, s) != a.available(d, SizeClass::Compact))
        })
    }

    /// Every combination of the two axes, narrowest and coarsest first.
    fn surfaces() -> Vec<(Density, SizeClass)> {
        let mut out = Vec::new();
        for d in [Density::Pointer, Density::Touch] {
            for &s in SizeClass::all() {
                out.push((d, s));
            }
        }
        out
    }

    #[test]
    fn density_gates_only_what_the_contact_patch_touches() {
        // The failure this module exists to avoid: a screen-budget claim
        // smuggled onto the input axis, which is what let the old Touch gap
        // preset set a floor under a preset quoted from the HIG. Adding a
        // density dependency to a screen-budget affordance has to come here
        // and say so.
        for &a in Affordance::all() {
            assert_eq!(
                varies_by_density(a),
                a.reads_density(),
                "{a:?} disagrees with its own reads_density()"
            );
        }
    }

    #[test]
    fn size_gates_only_what_screen_budget_touches() {
        for &a in Affordance::all() {
            assert_eq!(
                varies_by_size(a),
                a.reads_size(),
                "{a:?} disagrees with its own reads_size()"
            );
        }
    }

    #[test]
    fn no_member_reads_both_axes() {
        // Not a law of adaptation, a statement about the members that exist.
        // Measured off `available`, so a member whose rule starts reading the
        // second axis fails here whatever its `axis` declares. A member that
        // genuinely reads both is allowed, and this test is where the claim
        // gets withdrawn rather than quietly falsified.
        for &a in Affordance::all() {
            assert!(
                !(varies_by_density(a) && varies_by_size(a)),
                "{a:?} reads both axes; update this test and say why"
            );
        }
    }

    #[test]
    fn every_member_is_an_adaptation() {
        // A member available everywhere, or nowhere, is not describing an
        // adaptation and does not belong in this module.
        for &a in Affordance::all() {
            let yes = surfaces()
                .iter()
                .filter(|&&(d, s)| a.available(d, s))
                .count();
            assert!(yes > 0, "{a:?} exists on no surface");
            assert!(yes < surfaces().len(), "{a:?} exists on every surface");
        }
    }

    #[test]
    fn availability_is_contiguous_across_the_size_ladder() {
        // No member may exist at compact and expanded but not medium. A hole
        // in the middle is always an off-by-one, never a design.
        for &a in Affordance::all() {
            for d in [Density::Pointer, Density::Touch] {
                let run: Vec<bool> = SizeClass::all()
                    .iter()
                    .map(|&s| a.available(d, s))
                    .collect();
                let transitions = run.windows(2).filter(|w| w[0] != w[1]).count();
                assert!(
                    transitions <= 1,
                    "{a:?} at {d:?} is available in a broken run: {run:?}"
                );
            }
        }
    }

    #[test]
    fn compact_compensates_rather_than_only_losing() {
        // The reposition bucket is the reason this module is not just a
        // hide-list. Whatever compact takes
        // away, something has to give back.
        for d in [Density::Pointer, Density::Touch] {
            assert!(!Affordance::Detail.available(d, SizeClass::Compact));
            assert!(Affordance::Anchored.available(d, SizeClass::Compact));
        }
    }

    #[test]
    fn hover_and_hint_collapse_and_that_is_allowed() {
        // Borrowed from makeover-geometry, where bound and peer both resolve to
        // zero cells on a terminal and stay two members. Identical rules are
        // not a duplicate; the call site names what is gated.
        for (d, s) in surfaces() {
            assert_eq!(
                Affordance::Hover.available(d, s),
                Affordance::Hint.available(d, s)
            );
        }
        assert_ne!(Affordance::Hover.token(), Affordance::Hint.token());
    }

    /// The other density. Two members, so this is total, and writing it here
    /// rather than in `makeover-geometry` keeps the axis definition borrowed
    /// rather than extended.
    fn opposite(d: Density) -> Density {
        match d {
            Density::Pointer => Density::Touch,
            Density::Touch => Density::Pointer,
        }
    }

    #[test]
    fn a_density_member_is_available_on_exactly_the_density_it_declares() {
        // Direction is a property of each member rather than of the module:
        // Gesture and Haptic are gained by touch. A member still cannot invert
        // quietly. It declares its density in `gained_by`, and this is where a
        // declaration that disagrees with the rule shows up.
        for &a in Affordance::all() {
            match a.gained_by() {
                Some(gained) => {
                    assert!(
                        a.reads_density(),
                        "{a:?} declares a density but denies reading one"
                    );
                    for &s in SizeClass::all() {
                        assert!(
                            a.available(gained, s),
                            "{a:?} declares {gained:?} but is unavailable there at {s:?}"
                        );
                        assert!(
                            !a.available(opposite(gained), s),
                            "{a:?} declares {gained:?} but is also available on the other density at {s:?}"
                        );
                    }
                }
                None => assert!(
                    !a.reads_density(),
                    "{a:?} reads density but declares no side"
                ),
            }
        }
    }

    #[test]
    fn both_densities_gain_something() {
        // A module where only pointer gains members describes touch as a lesser
        // pointer. If the touch-gained members ever go, this fails rather than
        // passing quietly on an empty set.
        for d in [Density::Pointer, Density::Touch] {
            assert!(
                Affordance::all().iter().any(|a| a.gained_by() == Some(d)),
                "no member is gained by {d:?}"
            );
        }
    }

    #[test]
    fn the_density_axis_compensates_rather_than_only_losing() {
        // The density-axis twin of `compact_compensates_rather_than_only_losing`:
        // Hover's own doc says something else has to carry the actions a
        // fingertip cannot hover to reveal, and Gesture is that something.
        for &s in SizeClass::all() {
            assert!(!Affordance::Hover.available(Density::Touch, s));
            assert!(Affordance::Gesture.available(Density::Touch, s));
        }
    }

    #[test]
    fn tokens_are_distinct() {
        let mut seen: Vec<&str> = Affordance::all().iter().map(|a| a.token()).collect();
        seen.sort_unstable();
        let before = seen.len();
        seen.dedup();
        assert_eq!(seen.len(), before);
    }

    #[test]
    fn the_axes_are_borrowed_not_redefined() {
        // Imported rather than mirrored, so there is exactly one definition
        // of each in the family. A local copy is how two crates start
        // disagreeing about where 600px is.
        assert_eq!(SizeClass::Medium.min_px(), 600);
        assert_eq!(SizeClass::Expanded.min_px(), 840);
        assert_eq!(SizeClass::at_width(599), SizeClass::Compact);
    }
}