ui crate docs & spring cleaning (#18768)

Similar to https://github.com/zed-industries/zed/pull/18690 &
https://github.com/zed-industries/zed/pull/18695, this PR enables
required docs for `ui` and does some cleanup.

Changes:
- Enables the `deny(missing_docs)` crate-wide.
- Adds `allow(missing_docs)` on many modules until folks pick them up to
document them
- Documents some modules (all in `ui/src/styles`)
- Crate root-level organization: Traits move to `traits`, other misc
organization
- Cleaned out a bunch of unused code.

Note: I'd like to remove `utils/format_distance` but the assistant panel
uses it. To move it over to use the `time_format` crate we may need to
update it to use `time` instead of `chrono`. Needs more investigation.

Release Notes:

- N/A

crates/ui/src/components/avatar/avatar.rs

@@ -2,16 +2,6 @@ use crate::prelude::*;
 
 use gpui::{img, AnyElement, Hsla, ImageSource, Img, IntoElement, Styled};
 
-/// The shape of an [`Avatar`].
-#[derive(Debug, Default, PartialEq, Clone)]
-pub enum AvatarShape {
-    /// The avatar is shown in a circle.
-    #[default]
-    Circle,
-    /// The avatar is shown in a rectangle with rounded corners.
-    RoundedRectangle,
-}
-
 /// An element that renders a user avatar with customizable appearance options.
 ///
 /// # Examples
@@ -20,7 +10,6 @@ pub enum AvatarShape {
 /// use ui::{Avatar, AvatarShape};
 ///
 /// Avatar::new("path/to/image.png")
-///     .shape(AvatarShape::Circle)
 ///     .grayscale(true)
 ///     .border_color(gpui::red());
 /// ```
@@ -33,6 +22,7 @@ pub struct Avatar {
 }
 
 impl Avatar {
+    /// Creates a new avatar element with the specified image source.
     pub fn new(src: impl Into<ImageSource>) -> Self {
         Avatar {
             image: img(src),
@@ -42,26 +32,6 @@ impl Avatar {
         }
     }
 
-    /// Sets the shape of the avatar image.
-    ///
-    /// This method allows the shape of the avatar to be specified using an [`AvatarShape`].
-    /// It modifies the corner radius of the image to match the specified shape.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// use ui::{Avatar, AvatarShape};
-    ///
-    /// Avatar::new("path/to/image.png").shape(AvatarShape::Circle);
-    /// ```
-    pub fn shape(mut self, shape: AvatarShape) -> Self {
-        self.image = match shape {
-            AvatarShape::Circle => self.image.rounded_full(),
-            AvatarShape::RoundedRectangle => self.image.rounded_md(),
-        };
-        self
-    }
-
     /// Applies a grayscale filter to the avatar image.
     ///
     /// # Examples
@@ -76,6 +46,11 @@ impl Avatar {
         self
     }
 
+    /// Sets the border color of the avatar.
+    ///
+    /// This might be used to match the border to the background color of
+    /// the parent element to create the illusion of cropping another
+    /// shape underneath (for example in face piles.)
     pub fn border_color(mut self, color: impl Into<Hsla>) -> Self {
         self.border_color = Some(color.into());
         self
@@ -87,6 +62,7 @@ impl Avatar {
         self
     }
 
+    /// Sets the current indicator to be displayed on the avatar, if any.
     pub fn indicator<E: IntoElement>(mut self, indicator: impl Into<Option<E>>) -> Self {
         self.indicator = indicator.into().map(IntoElement::into_any_element);
         self
@@ -95,10 +71,6 @@ impl Avatar {
 
 impl RenderOnce for Avatar {
     fn render(mut self, cx: &mut WindowContext) -> impl IntoElement {
-        if self.image.style().corner_radii.top_left.is_none() {
-            self = self.shape(AvatarShape::Circle);
-        }
-
         let border_width = if self.border_color.is_some() {
             px(2.)
         } else {

crates/ui/src/components/avatar/avatar_audio_status_indicator.rs

@@ -2,12 +2,17 @@ use gpui::AnyView;
 
 use crate::prelude::*;
 
+/// The audio status of an player, for use in representing
+/// their status visually on their avatar.
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy)]
 pub enum AudioStatus {
+    /// The player's microphone is muted.
     Muted,
+    /// The player's microphone is muted, and collaboration audio is disabled.
     Deafened,
 }
 
+/// An indicator that shows the audio status of a player.
 #[derive(IntoElement)]
 pub struct AvatarAudioStatusIndicator {
     audio_status: AudioStatus,
@@ -15,6 +20,7 @@ pub struct AvatarAudioStatusIndicator {
 }
 
 impl AvatarAudioStatusIndicator {
+    /// Creates a new `AvatarAudioStatusIndicator`
     pub fn new(audio_status: AudioStatus) -> Self {
         Self {
             audio_status,
@@ -22,6 +28,7 @@ impl AvatarAudioStatusIndicator {
         }
     }
 
+    /// Sets the tooltip for the indicator.
     pub fn tooltip(mut self, tooltip: impl Fn(&mut WindowContext) -> AnyView + 'static) -> Self {
         self.tooltip = Some(Box::new(tooltip));
         self

crates/ui/src/components/avatar/avatar_availability_indicator.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use crate::prelude::*;
 
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy)]

crates/ui/src/components/button/button.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use gpui::{AnyView, DefiniteLength};
 
 use crate::{prelude::*, ElevationIndex, IconPosition, KeyBinding, Spacing};

crates/ui/src/components/button/button_icon.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use crate::{prelude::*, Icon, IconName, IconSize};
 
 /// An icon that appears within a button.

crates/ui/src/components/button/button_like.rs

@@ -1,8 +1,9 @@
+#![allow(missing_docs)]
 use gpui::{relative, CursorStyle, DefiniteLength, MouseButton};
 use gpui::{transparent_black, AnyElement, AnyView, ClickEvent, Hsla, Rems};
 use smallvec::SmallVec;
 
-use crate::{prelude::*, Elevation, ElevationIndex, Spacing};
+use crate::{prelude::*, ElevationIndex, Spacing};
 
 /// A trait for buttons that can be Selected. Enables setting the [`ButtonStyle`] of a button when it is selected.
 pub trait SelectableButton: Selectable {
@@ -145,20 +146,12 @@ pub(crate) struct ButtonLikeStyles {
     pub icon_color: Hsla,
 }
 
-fn element_bg_from_elevation(elevation: Option<Elevation>, cx: &mut WindowContext) -> Hsla {
+fn element_bg_from_elevation(elevation: Option<ElevationIndex>, cx: &mut WindowContext) -> Hsla {
     match elevation {
-        Some(Elevation::ElevationIndex(ElevationIndex::Background)) => {
-            cx.theme().colors().element_background
-        }
-        Some(Elevation::ElevationIndex(ElevationIndex::ElevatedSurface)) => {
-            cx.theme().colors().surface_background
-        }
-        Some(Elevation::ElevationIndex(ElevationIndex::Surface)) => {
-            cx.theme().colors().elevated_surface_background
-        }
-        Some(Elevation::ElevationIndex(ElevationIndex::ModalSurface)) => {
-            cx.theme().colors().background
-        }
+        Some(ElevationIndex::Background) => cx.theme().colors().element_background,
+        Some(ElevationIndex::ElevatedSurface) => cx.theme().colors().surface_background,
+        Some(ElevationIndex::Surface) => cx.theme().colors().elevated_surface_background,
+        Some(ElevationIndex::ModalSurface) => cx.theme().colors().background,
         _ => cx.theme().colors().element_background,
     }
 }
@@ -166,7 +159,7 @@ fn element_bg_from_elevation(elevation: Option<Elevation>, cx: &mut WindowContex
 impl ButtonStyle {
     pub(crate) fn enabled(
         self,
-        elevation: Option<Elevation>,
+        elevation: Option<ElevationIndex>,
         cx: &mut WindowContext,
     ) -> ButtonLikeStyles {
         let filled_background = element_bg_from_elevation(elevation, cx);
@@ -196,7 +189,7 @@ impl ButtonStyle {
 
     pub(crate) fn hovered(
         self,
-        elevation: Option<Elevation>,
+        elevation: Option<ElevationIndex>,
         cx: &mut WindowContext,
     ) -> ButtonLikeStyles {
         let mut filled_background = element_bg_from_elevation(elevation, cx);
@@ -281,7 +274,7 @@ impl ButtonStyle {
     #[allow(unused)]
     pub(crate) fn disabled(
         self,
-        elevation: Option<Elevation>,
+        elevation: Option<ElevationIndex>,
         cx: &mut WindowContext,
     ) -> ButtonLikeStyles {
         element_bg_from_elevation(elevation, cx).fade_out(0.82);
@@ -348,7 +341,7 @@ pub struct ButtonLike {
     pub(super) selected_style: Option<ButtonStyle>,
     pub(super) width: Option<DefiniteLength>,
     pub(super) height: Option<DefiniteLength>,
-    pub(super) layer: Option<Elevation>,
+    pub(super) layer: Option<ElevationIndex>,
     size: ButtonSize,
     rounding: Option<ButtonLikeRounding>,
     tooltip: Option<Box<dyn Fn(&mut WindowContext) -> AnyView>>,
@@ -463,7 +456,7 @@ impl ButtonCommon for ButtonLike {
     }
 
     fn layer(mut self, elevation: ElevationIndex) -> Self {
-        self.layer = Some(elevation.into());
+        self.layer = Some(elevation);
         self
     }
 }

crates/ui/src/components/button/icon_button.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use gpui::{AnyView, DefiniteLength};
 
 use super::button_like::{ButtonCommon, ButtonLike, ButtonSize, ButtonStyle};

crates/ui/src/components/button/toggle_button.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use gpui::{AnyView, ClickEvent};
 
 use crate::{prelude::*, ButtonLike, ButtonLikeRounding, ElevationIndex};

crates/ui/src/components/checkbox.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 mod checkbox_with_label;
 
 pub use checkbox_with_label::*;

crates/ui/src/components/checkbox/checkbox.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use gpui::{div, prelude::*, ElementId, IntoElement, Styled, WindowContext};
 
 use crate::prelude::*;

crates/ui/src/components/checkbox/checkbox_with_label.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use std::sync::Arc;
 
 use crate::{prelude::*, Checkbox};

crates/ui/src/components/context_menu.rs

@@ -1,6 +1,7 @@
+#![allow(missing_docs)]
 use crate::{
-    h_flex, prelude::*, v_flex, Icon, IconName, KeyBinding, Label, List, ListItem, ListSeparator,
-    ListSubHeader, WithRemSize,
+    h_flex, prelude::*, utils::WithRemSize, v_flex, Icon, IconName, KeyBinding, Label, List,
+    ListItem, ListSeparator, ListSubHeader,
 };
 use gpui::{
     px, Action, AnyElement, AppContext, DismissEvent, EventEmitter, FocusHandle, FocusableView,

crates/ui/src/components/disclosure.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use std::sync::Arc;
 
 use gpui::{ClickEvent, CursorStyle};

crates/ui/src/components/divider.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use gpui::{Hsla, IntoElement};
 
 use crate::prelude::*;

crates/ui/src/components/dropdown_menu.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use gpui::{AnchorCorner, ClickEvent, CursorStyle, MouseButton, View};
 
 use crate::{prelude::*, ContextMenu, PopoverMenu};

crates/ui/src/components/facepile.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use crate::prelude::*;
 use gpui::{AnyElement, StyleRefinement};
 use smallvec::SmallVec;

crates/ui/src/components/icon.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use gpui::{svg, AnimationElement, Hsla, IntoElement, Rems, Transformation};
 use serde::{Deserialize, Serialize};
 use strum::{EnumIter, EnumString, IntoStaticStr};

crates/ui/src/components/image.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use gpui::{svg, IntoElement, Rems, RenderOnce, Size, Styled, WindowContext};
 use serde::{Deserialize, Serialize};
 use strum::{EnumIter, EnumString, IntoStaticStr};

crates/ui/src/components/indicator.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use crate::{prelude::*, AnyIcon};
 
 #[derive(Default)]

crates/ui/src/components/keybinding.rs

@@ -1,5 +1,7 @@
+#![allow(missing_docs)]
+use crate::PlatformStyle;
 use crate::{h_flex, prelude::*, Icon, IconName, IconSize};
-use gpui::{relative, Action, FocusHandle, IntoElement, Keystroke};
+use gpui::{relative, Action, FocusHandle, IntoElement, Keystroke, WindowContext};
 
 #[derive(IntoElement, Clone)]
 pub struct KeyBinding {
@@ -192,3 +194,173 @@ impl KeyIcon {
         Self { icon }
     }
 }
+
+/// Returns a textual representation of the key binding for the given [`Action`].
+pub fn text_for_action(action: &dyn Action, cx: &mut WindowContext) -> Option<String> {
+    let key_binding = cx.bindings_for_action(action).last().cloned()?;
+    Some(text_for_key_binding(key_binding, PlatformStyle::platform()))
+}
+
+/// Returns a textual representation of the key binding for the given [`Action`]
+/// as if the provided [`FocusHandle`] was focused.
+pub fn text_for_action_in(
+    action: &dyn Action,
+    focus: &FocusHandle,
+    cx: &mut WindowContext,
+) -> Option<String> {
+    let key_binding = cx.bindings_for_action_in(action, focus).last().cloned()?;
+    Some(text_for_key_binding(key_binding, PlatformStyle::platform()))
+}
+
+/// Returns a textual representation of the given key binding for the specified platform.
+pub fn text_for_key_binding(
+    key_binding: gpui::KeyBinding,
+    platform_style: PlatformStyle,
+) -> String {
+    key_binding
+        .keystrokes()
+        .iter()
+        .map(|keystroke| text_for_keystroke(keystroke, platform_style))
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+/// Returns a textual representation of the given [`Keystroke`].
+pub fn text_for_keystroke(keystroke: &Keystroke, platform_style: PlatformStyle) -> String {
+    let mut text = String::new();
+
+    let delimiter = match platform_style {
+        PlatformStyle::Mac => '-',
+        PlatformStyle::Linux | PlatformStyle::Windows => '+',
+    };
+
+    if keystroke.modifiers.function {
+        match platform_style {
+            PlatformStyle::Mac => text.push_str("fn"),
+            PlatformStyle::Linux | PlatformStyle::Windows => text.push_str("Fn"),
+        }
+
+        text.push(delimiter);
+    }
+
+    if keystroke.modifiers.control {
+        match platform_style {
+            PlatformStyle::Mac => text.push_str("Control"),
+            PlatformStyle::Linux | PlatformStyle::Windows => text.push_str("Ctrl"),
+        }
+
+        text.push(delimiter);
+    }
+
+    if keystroke.modifiers.alt {
+        match platform_style {
+            PlatformStyle::Mac => text.push_str("Option"),
+            PlatformStyle::Linux | PlatformStyle::Windows => text.push_str("Alt"),
+        }
+
+        text.push(delimiter);
+    }
+
+    if keystroke.modifiers.platform {
+        match platform_style {
+            PlatformStyle::Mac => text.push_str("Command"),
+            PlatformStyle::Linux => text.push_str("Super"),
+            PlatformStyle::Windows => text.push_str("Win"),
+        }
+
+        text.push(delimiter);
+    }
+
+    if keystroke.modifiers.shift {
+        match platform_style {
+            PlatformStyle::Mac | PlatformStyle::Linux | PlatformStyle::Windows => {
+                text.push_str("Shift")
+            }
+        }
+
+        text.push(delimiter);
+    }
+
+    fn capitalize(str: &str) -> String {
+        let mut chars = str.chars();
+        match chars.next() {
+            None => String::new(),
+            Some(first_char) => first_char.to_uppercase().collect::<String>() + chars.as_str(),
+        }
+    }
+
+    let key = match keystroke.key.as_str() {
+        "pageup" => "PageUp",
+        "pagedown" => "PageDown",
+        key => &capitalize(key),
+    };
+
+    text.push_str(key);
+
+    text
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_text_for_keystroke() {
+        assert_eq!(
+            text_for_keystroke(&Keystroke::parse("cmd-c").unwrap(), PlatformStyle::Mac),
+            "Command-C".to_string()
+        );
+        assert_eq!(
+            text_for_keystroke(&Keystroke::parse("cmd-c").unwrap(), PlatformStyle::Linux),
+            "Super+C".to_string()
+        );
+        assert_eq!(
+            text_for_keystroke(&Keystroke::parse("cmd-c").unwrap(), PlatformStyle::Windows),
+            "Win+C".to_string()
+        );
+
+        assert_eq!(
+            text_for_keystroke(
+                &Keystroke::parse("ctrl-alt-delete").unwrap(),
+                PlatformStyle::Mac
+            ),
+            "Control-Option-Delete".to_string()
+        );
+        assert_eq!(
+            text_for_keystroke(
+                &Keystroke::parse("ctrl-alt-delete").unwrap(),
+                PlatformStyle::Linux
+            ),
+            "Ctrl+Alt+Delete".to_string()
+        );
+        assert_eq!(
+            text_for_keystroke(
+                &Keystroke::parse("ctrl-alt-delete").unwrap(),
+                PlatformStyle::Windows
+            ),
+            "Ctrl+Alt+Delete".to_string()
+        );
+
+        assert_eq!(
+            text_for_keystroke(
+                &Keystroke::parse("shift-pageup").unwrap(),
+                PlatformStyle::Mac
+            ),
+            "Shift-PageUp".to_string()
+        );
+        assert_eq!(
+            text_for_keystroke(
+                &Keystroke::parse("shift-pageup").unwrap(),
+                PlatformStyle::Linux
+            ),
+            "Shift+PageUp".to_string()
+        );
+        assert_eq!(
+            text_for_keystroke(
+                &Keystroke::parse("shift-pageup").unwrap(),
+                PlatformStyle::Windows
+            ),
+            "Shift+PageUp".to_string()
+        );
+    }
+}

crates/ui/src/components/label/highlighted_label.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use std::ops::Range;
 
 use gpui::{FontWeight, HighlightStyle, StyledText};

crates/ui/src/components/label/label.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use gpui::{StyleRefinement, WindowContext};
 
 use crate::{prelude::*, LabelCommon, LabelLike, LabelSize, LineHeightStyle};

crates/ui/src/components/label/label_like.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use gpui::{relative, AnyElement, FontWeight, StyleRefinement, Styled, UnderlineStyle};
 use settings::Settings;
 use smallvec::SmallVec;

crates/ui/src/components/list/list.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use gpui::AnyElement;
 use smallvec::SmallVec;
 

crates/ui/src/components/list/list_header.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use std::sync::Arc;
 
 use crate::{h_flex, prelude::*, Disclosure, Label};

crates/ui/src/components/list/list_item.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use std::sync::Arc;
 
 use gpui::{px, AnyElement, AnyView, ClickEvent, MouseButton, MouseDownEvent, Pixels};

crates/ui/src/components/list/list_separator.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use crate::prelude::*;
 
 #[derive(IntoElement)]

crates/ui/src/components/list/list_sub_header.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use crate::prelude::*;
 use crate::{h_flex, Icon, IconName, IconSize, Label};
 

crates/ui/src/components/modal.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use crate::{
     h_flex, v_flex, Clickable, Color, Headline, HeadlineSize, IconButton, IconButtonShape,
     IconName, Label, LabelCommon, LabelSize, Spacing,

crates/ui/src/components/numeric_stepper.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use gpui::ClickEvent;
 
 use crate::{prelude::*, IconButtonShape};

crates/ui/src/components/popover.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use crate::prelude::*;
 use crate::v_flex;
 use gpui::{

crates/ui/src/components/popover_menu.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use std::{cell::RefCell, rc::Rc};
 
 use gpui::{

crates/ui/src/components/radio.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use std::sync::Arc;
 
 use crate::prelude::*;

crates/ui/src/components/right_click_menu.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use std::{cell::RefCell, rc::Rc};
 
 use gpui::{

crates/ui/src/components/settings_container.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use gpui::AnyElement;
 use smallvec::SmallVec;
 

crates/ui/src/components/settings_group.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use gpui::AnyElement;
 use smallvec::SmallVec;
 

crates/ui/src/components/stack.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use gpui::{div, Div};
 
 use crate::StyledExt;

crates/ui/src/components/stories.rs

@@ -1,3 +1,6 @@
+// We allow missing docs for stories as the docs will more or less be
+// "This is the ___ story", which is not very useful.
+#![allow(missing_docs)]
 mod avatar;
 mod button;
 mod checkbox;

crates/ui/src/components/tab.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use std::cmp::Ordering;
 
 use gpui::{AnyElement, IntoElement, Stateful};

crates/ui/src/components/tab_bar.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use gpui::{AnyElement, ScrollHandle};
 use smallvec::SmallVec;
 

crates/ui/src/components/tool_strip.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use crate::prelude::*;
 use gpui::*;
 

crates/ui/src/components/tooltip.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use gpui::{Action, AnyView, FocusHandle, IntoElement, Render, VisualContext};
 use settings::Settings;
 use theme::ThemeSettings;