From 92c107c939e4d26c099636f054e4683ad4e85a5c Mon Sep 17 00:00:00 2001
From: rhysd <lin90162@yahoo.co.jp>
Date: Sun, 1 Oct 2023 23:10:23 +0900
Subject: [PATCH] rename `set_placeholder` to `set_placeholder_text` and add
 more APIs

---
 examples/popup_placeholder.rs         |  2 +-
 examples/ratatui_popup_placeholder.rs |  2 +-
 examples/single_line.rs               |  2 +-
 src/textarea.rs                       | 62 ++++++++++++++++++++++++++-
 4 files changed, 63 insertions(+), 5 deletions(-)

diff --git a/examples/popup_placeholder.rs b/examples/popup_placeholder.rs
index 6b5cb9c..a18f656 100644
--- a/examples/popup_placeholder.rs
+++ b/examples/popup_placeholder.rs
@@ -38,7 +38,7 @@ fn main() -> io::Result<()> {
     // set placeholder
 
     textarea.set_placeholder_style(Style::default());
-    textarea.set_placeholder("prompt message");
+    textarea.set_placeholder_text("prompt message");
     loop {
         term.draw(|f| {
             f.render_widget(textarea.widget(), area);
diff --git a/examples/ratatui_popup_placeholder.rs b/examples/ratatui_popup_placeholder.rs
index 860c759..021de04 100644
--- a/examples/ratatui_popup_placeholder.rs
+++ b/examples/ratatui_popup_placeholder.rs
@@ -36,7 +36,7 @@ fn main() -> io::Result<()> {
     };
     textarea.set_style(Style::default().fg(Color::Yellow));
     textarea.set_placeholder_style(Style::default());
-    textarea.set_placeholder("prompt message");
+    textarea.set_placeholder_text("prompt message");
     loop {
         term.draw(|f| {
             f.render_widget(textarea.widget(), area);
diff --git a/examples/single_line.rs b/examples/single_line.rs
index d61899d..5b7ed42 100644
--- a/examples/single_line.rs
+++ b/examples/single_line.rs
@@ -37,7 +37,7 @@ fn main() -> io::Result<()> {
 
     let mut textarea = TextArea::default();
     textarea.set_cursor_line_style(Style::default());
-    textarea.set_placeholder("enter a valid float, eg 1.56".to_string());
+    textarea.set_placeholder_text("Enter a valid float (e.g. 1.56)");
     let layout =
         Layout::default().constraints([Constraint::Length(3), Constraint::Min(1)].as_slice());
     let mut is_valid = validate(&mut textarea);
diff --git a/src/textarea.rs b/src/textarea.rs
index eca4a30..61b11af 100644
--- a/src/textarea.rs
+++ b/src/textarea.rs
@@ -1238,14 +1238,72 @@ impl<'a> TextArea<'a> {
         self.line_number_style
     }
 
-    /// sets the placeholder text
-    pub fn set_placeholder(&mut self, placeholder: impl Into<String>) {
+    /// Set the placeholder text. The text is set in the textarea when no text is input. Setting a non-empty string `""`
+    /// enables the placeholder. The default value is an empty string so the placeholder is disabled by default.
+    /// To customize the text style, see [`TextArea::set_placeholder_style`].
+    /// ```
+    /// use tui_textarea::TextArea;
+    ///
+    /// let mut textarea = TextArea::default();
+    /// assert_eq!(textarea.placeholder_text(), "");
+    /// assert!(textarea.placeholder_style().is_none());
+    ///
+    /// textarea.set_placeholder_text("Hello");
+    /// assert_eq!(textarea.placeholder_text(), "Hello");
+    /// assert!(textarea.placeholder_style().is_some());
+    /// ```
+    pub fn set_placeholder_text(&mut self, placeholder: impl Into<String>) {
         self.placeholder = placeholder.into();
     }
 
+    /// Set the style of the placeholder text. The default style is a dark gray text.
+    /// ```
+    /// use tui::style::{Style, Color};
+    /// use tui_textarea::TextArea;
+    ///
+    /// let mut textarea = TextArea::default();
+    /// assert_eq!(textarea.placeholder_style(), None); // When the placeholder is disabled
+    ///
+    /// textarea.set_placeholder_text("Enter your message"); // Enable placeholder by setting non-empty text
+    ///
+    /// let style = Style::default().bg(Color::Blue);
+    /// textarea.set_placeholder_style(style);
+    /// assert_eq!(textarea.placeholder_style(), Some(style));
+    /// ```
     pub fn set_placeholder_style(&mut self, style: Style) {
         self.placeholder_style = style;
     }
+
+    /// Get the placeholder text. An empty string means the placeholder is disabled. The default value is an empty string.
+    /// ```
+    /// use tui_textarea::TextArea;
+    ///
+    /// let textarea = TextArea::default();
+    /// assert_eq!(textarea.placeholder_text(), "");
+    /// ```
+    pub fn placeholder_text(&self) -> &'_ str {
+        self.placeholder.as_str()
+    }
+
+    /// Get the placeholder style. When the placeholder text is empty, it returns `None` since the placeholder is disabled.
+    /// The default style is a dark gray text.
+    /// ```
+    /// use tui_textarea::TextArea;
+    ///
+    /// let mut textarea = TextArea::default();
+    /// assert_eq!(textarea.placeholder_style(), None);
+    ///
+    /// textarea.set_placeholder_text("hello");
+    /// assert!(textarea.placeholder_style().is_some());
+    /// ```
+    pub fn placeholder_style(&self) -> Option<Style> {
+        if self.placeholder.is_empty() {
+            None
+        } else {
+            Some(self.placeholder_style)
+        }
+    }
+
     /// Set the style of cursor. By default, a cursor is rendered in the reversed color. Setting the same style as
     /// cursor line hides a cursor.
     /// ```