From aaaf764331c215d7558e7797a1db670e03fbfad1 Mon Sep 17 00:00:00 2001
From: Orion Kindel <cakekindel@gmail.com>
Date: Wed, 19 May 2021 16:21:35 -0700
Subject: [PATCH] feat: plaintext input (#128)

---
 Makefile.toml                    |   4 +
 src/block_elements/mod.rs        |   9 +-
 src/block_elements/radio.rs      |  66 +++++-
 src/block_elements/text_input.rs | 345 +++++++++++++++++++++++++++++++
 src/blocks/actions.rs            |   9 +-
 src/blocks/input.rs              |  19 +-
 6 files changed, 440 insertions(+), 12 deletions(-)
 create mode 100644 src/block_elements/text_input.rs

diff --git a/Makefile.toml b/Makefile.toml
index 4664440..52a2461 100644
--- a/Makefile.toml
+++ b/Makefile.toml
@@ -26,6 +26,10 @@ command = "cargo"
 args = ["fmt"]
 dependencies = ["install-fmt"]
 
+[tasks.doctest-slow]
+command = "cargo"
+args = ["--locked", "test", "--jobs", "1", "--doc", "--", "--quiet"]
+
 [tasks.doctest]
 command = "cargo"
 args = ["--locked", "test", "--doc", "--", "--quiet"]
diff --git a/src/block_elements/mod.rs b/src/block_elements/mod.rs
index 2c8ed93..d566a00 100644
--- a/src/block_elements/mod.rs
+++ b/src/block_elements/mod.rs
@@ -11,6 +11,9 @@ pub use button::Contents as Button;
 pub mod select;
 pub use select::Select;
 
+pub mod text_input;
+pub use text_input::TextInput;
+
 /// # Block Elements - interactive components
 /// [slack api docs 🔗](https://api.slack.com/reference/block-kit/block-elements)
 ///
@@ -34,9 +37,11 @@ pub enum BlockElement<'a> {
   Image,
   MultiSelect,
   OverflowMenu,
-  PlainInput,
   RadioButtons(Radio<'a>),
 
+  #[serde(rename = "plain_text_input")]
+  TextInput(TextInput<'a>),
+
   #[serde(rename = "channels_select")]
   SelectPublicChannel(select::PublicChannel<'a>),
 
@@ -62,6 +67,7 @@ impl<'a> BlockElement<'a> {
       | Self::SelectUser(cts) => cts.validate(),
       | Self::SelectExternal(cts) => cts.validate(),
       | Self::SelectStatic(cts) => cts.validate(),
+      | Self::RadioButtons(cts) => cts.validate(),
       | rest => todo!("validation not implemented for {:?}", rest),
     }
   }
@@ -69,6 +75,7 @@ impl<'a> BlockElement<'a> {
 
 convert!(impl From<Button> for BlockElement<'static> => |b| BlockElement::Button(b));
 convert!(impl<'a> From<Radio<'a>> for BlockElement<'a> => |b| BlockElement::RadioButtons(b));
+convert!(impl<'a> From<TextInput<'a>> for BlockElement<'a> => |t| BlockElement::TextInput(t));
 
 convert!(impl<'a> From<Select<'a>> for BlockElement<'a>
     => |s| match s {
diff --git a/src/block_elements/radio.rs b/src/block_elements/radio.rs
index f51235f..0e52aee 100644
--- a/src/block_elements/radio.rs
+++ b/src/block_elements/radio.rs
@@ -11,13 +11,18 @@ use crate::{compose::{opt::{AnyText, UrlUnset},
 
 pub type MyOpt<'a> = Opt<'a, AnyText, UrlUnset>;
 
+/// # Radio Buttons
+///
 /// A radio button group that allows a user to choose one item from a list of possible options.
 ///
-/// Works in [blocks ]: Section, Actions, Input
-/// Works in [app surfaces ]: Home tabs, Modals, Messages
+/// [slack api docs 🔗]
+///
+/// Works in [blocks 🔗]: Section, Actions, Input
+/// Works in [app surfaces 🔗]: Home tabs, Modals, Messages
 ///
-/// [blocks ]: https://api.slack.com/reference/block-kit/blocks
-/// [app surfaces ]: https://api.slack.com/surfaces
+/// [slack api docs 🔗]: https://api.slack.com/reference/block-kit/block-elements#radio
+/// [blocks 🔗]: https://api.slack.com/reference/block-kit/blocks
+/// [app surfaces 🔗]: https://api.slack.com/surfaces
 #[derive(Clone, Debug, Hash, PartialEq, Ser, De, Validate)]
 pub struct Radio<'a> {
   #[validate(length(max = 255))]
@@ -37,10 +42,42 @@ pub struct Radio<'a> {
 }
 
 impl<'a> Radio<'a> {
+  /// Build a new Radio Button Group
+  ///
+  /// # Example
+  /// See docs for `RadioBuilder`.
   pub fn builder() -> build::RadioBuilderInit<'a> {
     build::RadioBuilderInit::new()
   }
 
+  /// Validate that this select element agrees with Slack's model requirements
+  ///
+  /// # Errors
+  /// - length of `action_id` greater than 255
+  /// - length of `options` greater than 10
+  /// - one or more of `options` is invalid
+  /// - `initial_option` is set and an invalid `Opt`
+  /// - `confirm` is set and an invalid `Confirm`
+  ///
+  /// # Example
+  /// ```
+  /// use slack_blocks::{block_elements::Radio, compose::Opt};
+  ///
+  /// fn repeat<T: Copy>(el: T, n: usize) -> impl Iterator<Item = T> {
+  ///   std::iter::repeat(el).take(n)
+  /// }
+  ///
+  /// let long_string: String = repeat('a', 256).collect();
+  /// let opt = Opt::builder().text_md("foo").value("bar").build();
+  ///
+  /// let opts = repeat(&opt, 11).map(|o| o.clone()).collect::<Vec<_>>();
+  ///
+  /// let input = Radio::builder().action_id(long_string)
+  ///                             .options(opts)
+  ///                             .build();
+  ///
+  /// assert!(matches!(input.validate(), Err(_)))
+  /// ```
   pub fn validate(&self) -> ValidationResult {
     Validate::validate(self)
   }
@@ -101,6 +138,7 @@ pub mod build {
   }
 
   impl<'a, T, A, O> RadioBuilder<'a, T, A, O> {
+    /// Construct a new RadioBuilder
     pub fn new() -> Self {
       Self { action_id: None,
              options: None,
@@ -201,6 +239,26 @@ pub mod build {
   }
 
   impl<'a, T> RadioBuilder<'a, T, Set<method::action_id>, Set<method::options>> {
+    /// All done building, now give me a darn radio button group!
+    ///
+    /// > `no method name 'build' found for struct 'RadioBuilder<...>'`?
+    /// Make sure all required setter methods have been called. See docs for `RadioBuilder`.
+    ///
+    /// ```compile_fail
+    /// use slack_blocks::block_elements::Radio;
+    ///
+    /// let foo = Radio::builder().build(); // Won't compile!
+    /// ```
+    ///
+    /// ```
+    /// use slack_blocks::{block_elements::Radio, compose::Opt};
+    ///
+    /// let foo = Radio::builder().action_id("bar")
+    ///                           .options(vec![Opt::builder().text_md("foo")
+    ///                                                       .value("bar")
+    ///                                                       .build()])
+    ///                           .build();
+    /// ```
     pub fn build(self) -> Radio<'a> {
       Radio { action_id: self.action_id.unwrap(),
               options: self.options.unwrap(),
diff --git a/src/block_elements/text_input.rs b/src/block_elements/text_input.rs
new file mode 100644
index 0000000..94add94
--- /dev/null
+++ b/src/block_elements/text_input.rs
@@ -0,0 +1,345 @@
+use std::borrow::Cow;
+
+use serde::{Deserialize as De, Serialize as Ser};
+use validator::Validate;
+
+use crate::{text, val_helpr::*};
+
+/// Interaction types that you would like to receive a [`block_actions` payload 🔗] for.
+///
+/// [`block_actions` payload 🔗]: https://api.slack.com/reference/interaction-payloads/block-actions
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Ser, De)]
+#[serde(untagged, rename_all = "snake_case")]
+pub enum ActionTrigger {
+  /// Payload is dispatched when user presses the enter key while the input is in focus.
+  ///
+  /// Hint text will appear underneath the input explaining to the user to press enter to submit.
+  OnEnterPressed,
+
+  /// Payload is dispatched when a character is entered (or removed) in the input.
+  OnCharacterEntered,
+}
+
+/// [api docs](https://api.slack.com/reference/block-kit/composition-objects#dispatch_action_config)
+#[derive(Clone, Debug, Hash, PartialEq, Ser, De)]
+struct DispatchActionConfig {
+  trigger_actions_on: Vec<ActionTrigger>,
+}
+
+/// # Plain Text Input
+///
+/// [slack api docs 🔗]
+///
+/// A plain-text input, similar to the HTML `<input>` tag, creates a field where a user can enter freeform data.
+/// It can appear as a single-line field or a larger textarea using the `multiline` flag.
+///
+/// Works in [blocks 🔗]: Input
+/// Works in [app surfaces 🔗]: Home tabs, Modals, Messages
+///
+/// [slack api docs 🔗]: https://api.slack.com/reference/block-kit/block-elements#radio
+#[derive(Clone, Debug, Hash, PartialEq, Ser, De, Validate)]
+pub struct TextInput<'a> {
+  #[validate(length(max = 255))]
+  action_id: Cow<'a, str>,
+  #[validate(custom = "validate_placeholder")]
+  placeholder: Option<text::Text>,
+  initial_value: Option<Cow<'a, str>>,
+  multiline: Option<bool>,
+  #[validate(range(max = 3000))]
+  min_length: Option<u32>,
+  max_length: Option<u32>,
+  dispatch_action_config: Option<DispatchActionConfig>,
+}
+
+impl<'a> TextInput<'a> {
+  /// Build a new text input block element
+  ///
+  /// # Examples
+  /// See example for `build::TextInputBuilder`.
+  pub fn builder() -> build::TextInputBuilderInit<'a> {
+    build::TextInputBuilderInit::new()
+  }
+
+  /// Validate that this select element agrees with Slack's model requirements
+  ///
+  /// # Errors
+  /// - length of `placeholder` greater than 150
+  /// - length of `action_id` greater than 255
+  /// - value of `min_length` greater than 3000
+  ///
+  /// # Example
+  /// ```
+  /// use slack_blocks::block_elements::TextInput;
+  ///
+  /// let long_string = || std::iter::repeat('a').take(256).collect::<String>();
+  ///
+  /// let input = TextInput::builder().action_id(long_string())
+  ///                                 .placeholder(long_string())
+  ///                                 .min_length(3001)
+  ///                                 .build();
+  ///
+  /// assert!(matches!(input.validate(), Err(_)))
+  /// ```
+  pub fn validate(&self) -> ValidationResult {
+    Validate::validate(self)
+  }
+}
+
+fn validate_placeholder<'a>(p: &text::Text) -> ValidatorResult {
+  below_len("TextInput.placeholder", 150, p)
+}
+
+pub mod build {
+  use std::marker::PhantomData;
+
+  use super::*;
+  use crate::build::*;
+
+  #[allow(non_camel_case_types)]
+  pub mod method {
+    pub struct action_id;
+  }
+
+  pub type TextInputBuilderInit<'a> =
+    TextInputBuilder<'a, RequiredMethodNotCalled<method::action_id>>;
+
+  /// Build a Text Input element
+  ///
+  /// Allows you to construct a text input safely, with compile-time checks
+  /// on required setter methods.
+  ///
+  /// # Required Methods
+  /// `TextInputBuilder::build()` is only available if these methods have been called:
+  ///  - `action_id`
+  ///
+  /// # Examples
+  ///
+  /// ```
+  /// use slack_blocks::{blocks::{Block, Input}, block_elements::TextInput};
+  ///
+  /// let text_input = TextInput::builder()
+  ///                            .action_id("plate_num")
+  ///                            .placeholder("ABC1234")
+  ///                            .length(1..=7)
+  ///                            .build();
+  ///
+  /// let block: Block = Input::from_label_and_element("enter custom license plate", text_input)
+  ///                          .dispatch_block_actions()
+  ///                          .into();
+  /// ```
+  pub struct TextInputBuilder<'a, A> {
+    action_id: Option<Cow<'a, str>>,
+    placeholder: Option<text::Text>,
+    initial_value: Option<Cow<'a, str>>,
+    multiline: Option<bool>,
+    min_length: Option<u32>,
+    max_length: Option<u32>,
+    dispatch_action_config: Option<DispatchActionConfig>,
+    state: PhantomData<A>,
+  }
+
+  impl<'a, A> TextInputBuilder<'a, A> {
+    /// Construct a new text input builder of empty state
+    pub fn new() -> Self {
+      Self { action_id: None,
+             placeholder: None,
+             initial_value: None,
+             multiline: None,
+             min_length: None,
+             max_length: None,
+             dispatch_action_config: None,
+             state: PhantomData::<_> }
+    }
+
+    /// Set `action_id` (**Required**)
+    ///
+    /// An identifier for the input value when the parent modal is submitted.
+    ///
+    /// You can use this when you receive a `view_submission` payload [to identify the value of the input element 🔗].
+    ///
+    /// Should be unique among all other `action_id`s in the containing block.
+    ///
+    /// Maximum length for this field is 255 characters.
+    ///
+    /// [to identify the value of the input element 🔗]: https://api.slack.com/surfaces/modals/using#handling-submissions
+    pub fn action_id(self,
+                     action_id: impl Into<Cow<'a, str>>)
+                     -> TextInputBuilder<'a, Set<method::action_id>> {
+      TextInputBuilder { action_id: Some(action_id.into()),
+                         placeholder: self.placeholder,
+                         initial_value: self.initial_value,
+                         multiline: self.multiline,
+                         min_length: self.min_length,
+                         max_length: self.max_length,
+                         dispatch_action_config: self.dispatch_action_config,
+                         state: PhantomData::<_> }
+    }
+
+    /// Add a new event trigger (Optional)
+    ///
+    /// In messages, in order to receive events you must invoke this method and set `dispatch_action` to `true` on the containing Input block.
+    ///
+    /// In modals and other contexts, the value of this element will be included with the submission of the form.
+    ///
+    /// By invoking this with `ActionTrigger::OnCharacterEntered`, `ActionTrigger::OnEnterPressed`, or both,
+    /// you can configure the input element to send additional events when these triggers are fired by the client.
+    ///
+    /// For more info on these events, see [`block_actions` interaction payload 🔗].
+    ///
+    /// [`block_actions` interaction payload 🔗]: https://api.slack.com/reference/interaction-payloads/block-actions
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use slack_blocks::{blocks::{Block, Input}, block_elements::TextInput};
+    ///
+    /// let text_input = TextInput::builder()
+    ///                            .action_id("plate_num")
+    ///                            .placeholder("ABC1234")
+    ///                            .length(1..=7)
+    ///                            .build();
+    ///
+    /// let block: Block = Input::from_label_and_element("enter custom license plate", text_input)
+    ///                          .dispatch_block_actions()
+    ///                          .into();
+    /// ```
+    pub fn trigger_action_on(mut self, trigger: ActionTrigger) -> Self {
+      let config =
+        self.dispatch_action_config
+            .map(|mut c| {
+              if !c.trigger_actions_on.contains(&trigger) {
+                c.trigger_actions_on.push(trigger)
+              }
+
+              c
+            })
+            .unwrap_or_else(|| DispatchActionConfig { trigger_actions_on:
+                                                        vec![trigger] });
+
+      self.dispatch_action_config = Some(config);
+      self
+    }
+
+    /// Set `placeholder` (**Optional**)
+    ///
+    /// A [`plain_text` only text object 🔗] that defines the placeholder text shown in the plain-text input.
+    ///
+    /// Maximum length for the `text` in this field is 150 characters.
+    ///
+    /// [`plain_text` only text object 🔗]: https://api.slack.com/reference/block-kit/composition-objects#text
+    pub fn placeholder(mut self, placeholder: impl Into<text::Plain>) -> Self {
+      self.placeholder = Some(placeholder.into().into());
+      self
+    }
+
+    /// Set `initial value` (**Optional**)
+    ///
+    /// The initial value in the plain-text input when it is loaded.
+    pub fn initial_value(mut self, init: impl Into<Cow<'a, str>>) -> Self {
+      self.initial_value = Some(init.into());
+      self
+    }
+
+    /// Set `multiline` to `true` (**Optional**)
+    ///
+    /// Indicates that the input will be a larger textarea, rather than a single line.
+    pub fn multiline(mut self) -> Self {
+      self.multiline = Some(true);
+      self
+    }
+
+    /// Set `min_length` (**Optional**)
+    ///
+    /// The minimum length of input that the user must provide.
+    ///
+    /// If the user provides less, they will receive an error.
+    ///
+    /// Maximum value is 3000.
+    pub fn min_length(mut self, min: u32) -> Self {
+      self.min_length = Some(min.into());
+      self
+    }
+
+    /// Set `max_length` (**Optional**)
+    ///
+    /// The maximum length of input that the user can provide.
+    ///
+    /// If the user provides more, they will receive an error.
+    pub fn max_length(mut self, max: u32) -> Self {
+      self.max_length = Some(max.into());
+      self
+    }
+
+    /// Set `min_length` and/or `max_length` with a rust range literal (**Optional**)
+    ///
+    /// ```
+    /// use slack_blocks::block_elements::TextInput;
+    ///
+    /// TextInput::builder().action_id("vanity_plate")
+    ///                     .placeholder("enter your desired custom license plate")
+    ///                     .length(1..=7);
+    /// ```
+    ///
+    /// ```
+    /// use slack_blocks::block_elements::TextInput;
+    ///
+    /// TextInput::builder().action_id("first_name")
+    ///                     .placeholder("enter your first name")
+    ///                     .length(2..);
+    /// ```
+    ///
+    /// ```
+    /// use slack_blocks::block_elements::TextInput;
+    ///
+    /// TextInput::builder()
+    ///           .action_id("does nothing")
+    ///           .placeholder("This is the same as not calling length at all!")
+    ///           .length(..);
+    /// ```
+    pub fn length(mut self, rng: impl std::ops::RangeBounds<u32>) -> Self {
+      use std::ops::Bound;
+
+      self.min_length = match rng.start_bound() {
+        | Bound::Included(min) => Some(*min),
+        | Bound::Excluded(min) => Some(min + 1),
+        | Bound::Unbounded => None,
+      };
+
+      self.max_length = match rng.end_bound() {
+        | Bound::Included(max) => Some(*max),
+        | Bound::Excluded(max) => Some(max - 1),
+        | Bound::Unbounded => None,
+      };
+
+      self
+    }
+  }
+
+  impl<'a> TextInputBuilder<'a, Set<method::action_id>> {
+    /// All done building, now give me a darn select element!
+    ///
+    /// > `no method name 'build' found for struct 'text_input::build::TextInputBuilder<...>'`?
+    /// Make sure all required setter methods have been called. See docs for `TextInputBuilder`.
+    ///
+    /// ```compile_fail
+    /// use slack_blocks::block_elements::TextInput;
+    ///
+    /// let sel = TextInput::builder().build(); // Won't compile!
+    /// ```
+    ///
+    /// ```
+    /// use slack_blocks::block_elements::TextInput;
+    ///
+    /// let sel = TextInput::builder().action_id("bar").build();
+    /// ```
+    pub fn build(self) -> TextInput<'a> {
+      TextInput { action_id: self.action_id.unwrap(),
+                  placeholder: self.placeholder,
+                  initial_value: self.initial_value,
+                  multiline: self.multiline,
+                  min_length: self.min_length,
+                  max_length: self.max_length,
+                  dispatch_action_config: self.dispatch_action_config }
+    }
+  }
+}
diff --git a/src/blocks/actions.rs b/src/blocks/actions.rs
index b99b52d..bb5049a 100644
--- a/src/blocks/actions.rs
+++ b/src/blocks/actions.rs
@@ -4,7 +4,7 @@ use serde::{Deserialize, Serialize};
 use validator::Validate;
 
 use crate::{block_elements,
-            block_elements::{select, Button, Radio},
+            block_elements::{select, Button, Radio, TextInput},
             convert,
             val_helpr::ValidationResult};
 
@@ -202,8 +202,8 @@ pub enum BlockElement<'a> {
   Checkboxes,
   DatePicker,
   OverflowMenu,
-  PlainInput,
-  RadioButtons(block_elements::Radio<'a>),
+  TextInput(TextInput<'a>),
+  RadioButtons(Radio<'a>),
 
   /// All Select types are supported.
   SelectPublicChannel(select::PublicChannel<'a>),
@@ -265,7 +265,7 @@ impl<'a> TryFrom<block_elements::BlockElement<'a>> for self::BlockElement<'a> {
       | El::OverflowMenu => Ok(OverflowMenu),
       | El::RadioButtons(r) => Ok(RadioButtons(r)),
       | El::Button(cts) => Ok(Button(cts)),
-      | El::PlainInput => Ok(PlainInput),
+      | El::TextInput(t) => Ok(TextInput(t)),
       | El::Checkboxes => Ok(Checkboxes),
       | El::DatePicker => Ok(DatePicker),
       | _ => Err(()),
@@ -280,3 +280,4 @@ convert!(impl<'a> From<select::External<'a>> for self::BlockElement<'a>  => |s|
 convert!(impl<'a> From<select::Static<'a>> for self::BlockElement<'a>  => |s| self::BlockElement::SelectStatic(s));
 convert!(impl     From<Button> for self::BlockElement<'static> => |b| self::BlockElement::Button(b));
 convert!(impl<'a> From<Radio<'a>> for self::BlockElement<'a> => |b| self::BlockElement::RadioButtons(b));
+convert!(impl<'a> From<TextInput<'a>> for self::BlockElement<'a> => |t| self::BlockElement::TextInput(t));
diff --git a/src/blocks/input.rs b/src/blocks/input.rs
index f93d957..7578de3 100644
--- a/src/blocks/input.rs
+++ b/src/blocks/input.rs
@@ -1,7 +1,7 @@
 use serde::{Deserialize, Serialize};
 use validator::Validate;
 
-use crate::{block_elements::select,
+use crate::{block_elements::{select, Radio, TextInput},
             compose::text,
             convert,
             val_helpr::ValidationResult};
@@ -32,6 +32,9 @@ pub struct Contents<'a> {
   #[validate(custom = "validate::hint")]
   hint: Option<text::Text>,
 
+  #[serde(skip_serializing_if = "Option::is_none")]
+  dispatch_action: Option<bool>,
+
   #[serde(skip_serializing_if = "Option::is_none")]
   optional: Option<bool>,
 }
@@ -74,6 +77,7 @@ impl<'a> Contents<'a> {
                element: element.into(),
                block_id: None,
                hint: None,
+               dispatch_action: None,
                optional: None }
   }
 
@@ -178,6 +182,12 @@ impl<'a> Contents<'a> {
     self
   }
 
+  /// Will allow the elements in this block to dispatch block_actions payloads. Defaults to false.
+  pub fn dispatch_block_actions(mut self) -> Self {
+    self.dispatch_action = Some(true);
+    self
+  }
+
   /// Validate that this Input block agrees with Slack's model requirements
   ///
   /// # Errors
@@ -222,8 +232,8 @@ pub enum InputElement<'a> {
   Checkboxes,
   DatePicker,
   MultiSelect,
-  PlainInput,
-  RadioButtons,
+  TextInput(TextInput<'a>),
+  Radio(Radio<'a>),
 }
 
 use select::PublicChannel as SelectPublicChannel;
@@ -232,6 +242,9 @@ convert! {
         => |contents| InputElement::SelectPublicChannel(contents)
 }
 
+convert!(impl<'a> From<Radio<'a>> for InputElement<'a> => |r| InputElement::Radio(r));
+convert!(impl<'a> From<TextInput<'a>> for InputElement<'a> => |r| InputElement::TextInput(r));
+
 mod validate {
   use crate::{compose::text,
               val_helpr::{below_len, ValidatorResult}};