Merge pull request #77 from raycharius/v2.4.0

✨ Add support for focus_on_load and conditional helpers

README.md

@@ -35,6 +35,7 @@
 
 * Declarative [SwiftUI](https://developer.apple.com/xcode/swiftui/) inspired syntax.
 * Commonly-used UI components, such as a `Paginator` and `Accordion`.
+* Inline conditional helper functions for declaratively appending or omitting UI content.
 * The ability to build more complex flows using loops and conditionals.
 * A `printPreviewURL()` method that outputs a link to preview your UI on Slack's [Block Kit Builder website](https://app.slack.com/block-kit-builder) for easier prototyping.
 * A set of helper functions for formatting text with Slack's markdown standard.
@@ -214,12 +215,10 @@ Both of these examples render the message below. And the best part? It only took
 
 ### Creating a Simple Modal
 
-Let's take a look at how modals are created. Here we'll also take a look at working with Bits and with loops, by adding options with the `Array.map()` method.
-
-You'll noticed that we've added an inline condition that returns an initial option only if one has been passed into the function. This is because all the setter methods prune values of `undefined`, uncovering opportunities for inline logic. 
+Let's take a look at how modals are created. Here we'll also take a look at working with Bits and with loops, by adding options with the `Array.map()` method. 
 
 ```javascript
-import { Modal, Blocks, Elements, Bits } from 'slack-block-builder';
+import { Modal, Blocks, Elements, Bits, setIfTruthy } from 'slack-block-builder';
 
 export default ({ menuOptions, selected }) =>
   Modal({ title: 'PizzaMate', submit: 'Get Fed' })
@@ -240,7 +239,7 @@ export default ({ menuOptions, selected }) =>
             .actionId('item')
             .options(menuOptions
               .map((item) => Bits.Option({ text: item.name, value: item.id })))
-            .initialOption(selected && Bits.Option({ text: selected.name, value: selected.id }))))
+            .initialOption(setIfTruthy(selected, Bits.Option({ text: selected.name, value: selected.id })))))
     .buildToJSON();
 ```
 
@@ -383,6 +382,52 @@ const unfurl = ({ channel, ts, url }) => client.chat.unfurl({
 .catch((error) => console.log(error));
 ```
 
+### Working With Inline Conditionals
+
+There are a few helper functions available to make it easy to work with inline conditionals within your UI source code.
+
+They can be imported separately:
+
+```javascript
+import { setIfTruthy, omitIfTruthy, setIfFalsy, omitIfFalsy } from 'slack-block-builder';
+```
+
+Or as a part of the `conditionals` object:
+
+```javascript
+import { conditionals } from 'slack-block-builder';
+```
+
+Each function accepts to arguments – the first being a value that is evaluated whether it is either `null`, `undefined`, or `false`, and the second being the value to set or omit:
+
+```javascript
+import { Modal, Blocks, Elements, Bits, setIfTruthy } from 'slack-block-builder';
+
+export default ({ groups, selectedGroup, selectedGroupMembers }) => Modal()
+  .title('Edit Groups')
+  .callbackId('submit-edit-groups')
+  .blocks(
+    Blocks.Section({ text: 'Hello! Need to edit some groups?'}),
+    Blocks.Input({ label: 'Select a group to get started' })
+      .dispatchAction()
+      .element(
+        Elements.StaticSelect({ placeholder: 'Select a group...' })
+          .actionId('selectedGroup')
+          .options(groups
+            .map(({ name, id }) => Bits.Option({ text: name, value: id })))),
+    setIfTruthy(selectedGroup, [
+      Blocks.Input({ label: 'Current group members' })
+        .element(
+          Elements.UserMultiSelect({ placeholder: 'Select members...' })
+            .actionId('groupMembers')
+            .initialUsers(selectedGroupMembers))
+    ]))
+  .submit(setIfTruthy(selectedGroup, 'Save Changes'))
+  .buildToJSON();
+```
+
+These functions essentially return either the value passed into as the second argument or `undefined`, depending on the condition. Please note that falsy is defined as `null`, `undefined`, or `false`. To avoid side effects, values such as `0` or `''` are not considered to be falsy.
+
 ### Markdown Helpers
 
 Often you'll find that you need to format text in your messages and modals. *Block Builder* has helper functions available to simply that process. They are available both as members of the `Md` object and as top-level imports. You can find the full list of functions on the [Block Builder doc site](https://blockbuilder.dev):

docs-generator/getters/get-method-data-array.ts

@@ -27,7 +27,7 @@ export interface MethodData {
 
 export default (): MethodData[] => {
   const basePath = './src';
-  const folder = 'methods';
+  const folder = 'internal/methods';
 
   return getFilePathsFromFolder(basePath, folder, ['index.ts', 'required-methods.ts'])
     .map((file) => {

docs/_sidebar.md

@@ -70,6 +70,7 @@
 * **Other**
   * [Block Collection](other/block-collection.md "Block Builder – Block Collection – Maintainable JavaScript Code for Slack Block Kit")
   * [Attachment Collection](other/attachment-collection.md "Block Builder – Attachment Collection – Maintainable JavaScript Code for Slack Block Kit")
+  * [Conditionals](other/conditionals.md "Block Builder – Conditionals – Maintainable JavaScript Code for Slack Block Kit")
   * [Markdown](other/markdown.md "Block Builder – Markdown – Maintainable JavaScript Code for Slack Block Kit")   
 
 * **About**

docs/bits/introduction.md

@@ -6,7 +6,7 @@ The `Bits` object in **Block Builder** contains various bits and pieces from the
 
 ### Accessing Bits in Block Builder
 
-All of the composition objects provided by the [Slack Block Kit](https://api.slack.com/block-kit) framework are supported in **Block Builder** and most are accessed through the `Bits` object, which is a top-level import. The others (Markdown, Plain-Text, Filter) are created in the background when a view is compiled.
+All of the composition objects provided by the [Slack Block Kit](https://api.slack.com/block-kit) framework are supported in **Block Builder** and most are accessed through the `Bits` object, which is a top-level import. The others (Markdown, Plain-Text, FilterType) are created in the background when a view is compiled.
 
 The `Bits` object also contains a method called `Attachment()` which builds out attachments for messages.
 

docs/elements/channel-multi-select.md

@@ -42,6 +42,11 @@ ChannelMultiSelectBuilder.initialChannels([string1[, ...[, stringN]]);
 
 Pre-populates the menu with selected, default channels. 
 ```javascript
+ChannelMultiSelectBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
+```javascript
 ChannelMultiSelectBuilder.actionId(string);
 ```
 

docs/elements/channel-select.md

@@ -36,6 +36,11 @@ Each instance of the `ChannelSelectBuilder` object has chainable setter methods
 
 All setter methods return `this`, the instance of `ChannelSelectBuilder` on which it is called.
 
+```javascript
+ChannelSelectBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
 ```javascript
 ChannelSelectBuilder.responseUrlEnabled(boolean?);
 ```

docs/elements/checkboxes.md

@@ -43,6 +43,11 @@ CheckboxesBuilder.options([Option1[, ...[, OptionN]]);
 
 Adds options to the select or multi-select menu. 
 ```javascript
+CheckboxesBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
+```javascript
 CheckboxesBuilder.actionId(string);
 ```
 

docs/elements/conversation-multi-select.md

@@ -62,6 +62,11 @@ ConversationMultiSelectBuilder.excludeBotUsers(boolean?);
 
 Excludes conversations with bot users from the menu's options. Defaults to `true`.
 ```javascript
+ConversationMultiSelectBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
+```javascript
 ConversationMultiSelectBuilder.actionId(string);
 ```
 

docs/elements/conversation-select.md

@@ -57,6 +57,11 @@ ConversationSelectBuilder.excludeBotUsers(boolean?);
 
 Excludes conversations with bot users from the menu's options. Defaults to `true`.
 ```javascript
+ConversationSelectBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
+```javascript
 ConversationSelectBuilder.responseUrlEnabled(boolean?);
 ```
 

docs/elements/datepicker.md

@@ -36,6 +36,11 @@ Each instance of the `DatePickerBuilder` object has chainable setter methods for
 
 All setter methods return `this`, the instance of `DatePickerBuilder` on which it is called.
 
+```javascript
+DatePickerBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
 ```javascript
 DatePickerBuilder.actionId(string);
 ```

docs/elements/external-multi-select.md

@@ -44,6 +44,11 @@ ExternalMultiSelectBuilder.initialOptions([Option1[, ...[, OptionN]]);
 
 Pre-populates the menu or checkbox input with selected, default options. 
 ```javascript
+ExternalMultiSelectBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
+```javascript
 ExternalMultiSelectBuilder.actionId(string);
 ```
 

docs/elements/external-select.md

@@ -36,6 +36,11 @@ Each instance of the `ExternalSelectBuilder` object has chainable setter methods
 
 All setter methods return `this`, the instance of `ExternalSelectBuilder` on which it is called.
 
+```javascript
+ExternalSelectBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
 ```javascript
 ExternalSelectBuilder.actionId(string);
 ```

docs/elements/radio-buttons.md

@@ -38,6 +38,11 @@ RadioButtonsBuilder.options([Option1[, ...[, OptionN]]);
 
 Adds options to the select or multi-select menu. 
 ```javascript
+RadioButtonsBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
+```javascript
 RadioButtonsBuilder.actionId(string);
 ```
 

docs/elements/static-multi-select.md

@@ -52,6 +52,11 @@ StaticMultiSelectBuilder.options([Option1[, ...[, OptionN]]);
 
 Adds options to the select or multi-select menu. 
 ```javascript
+StaticMultiSelectBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
+```javascript
 StaticMultiSelectBuilder.actionId(string);
 ```
 

docs/elements/static-select.md

@@ -45,6 +45,11 @@ StaticSelectBuilder.options([Option1[, ...[, OptionN]]);
 
 Adds options to the select or multi-select menu. 
 ```javascript
+StaticSelectBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
+```javascript
 StaticSelectBuilder.actionId(string);
 ```
 

docs/elements/text-input.md

@@ -51,6 +51,11 @@ TextInputBuilder.dispatchActionOnEnterPressed(boolean?);
 
 Instructs the Slack API to dispatch an interaction payload to your app when the user presses the enter key while the input is in focus. Defaults to `true`.
 ```javascript
+TextInputBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
+```javascript
 TextInputBuilder.multiline(boolean?);
 ```
 

docs/elements/timepicker.md

@@ -36,6 +36,11 @@ Each instance of the `TimePickerBuilder` object has chainable setter methods for
 
 All setter methods return `this`, the instance of `TimePickerBuilder` on which it is called.
 
+```javascript
+TimePickerBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
 ```javascript
 TimePickerBuilder.actionId(string);
 ```

docs/elements/user-multi-select.md

@@ -42,6 +42,11 @@ UserMultiSelectBuilder.initialUsers([string1[, ...[, stringN]]);
 
 Pre-populates the menu with selected, default users. 
 ```javascript
+UserMultiSelectBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
+```javascript
 UserMultiSelectBuilder.actionId(string);
 ```
 

docs/elements/user-select.md

@@ -36,6 +36,11 @@ Each instance of the `UserSelectBuilder` object has chainable setter methods for
 
 All setter methods return `this`, the instance of `UserSelectBuilder` on which it is called.
 
+```javascript
+UserSelectBuilder.focusOnLoad(boolean?);
+```
+
+Sets an element to have auto focus on opening the view Defaults to `true`.
 ```javascript
 UserSelectBuilder.actionId(string);
 ```

docs/other/conditionals.md

@@ -0,0 +1,43 @@
+# Conditionals
+
+### Accessing Inline Conditional Helpers 
+
+The helpers for inline conditionals can be imported as a part of the `conditionals` object, or as top-level imports:
+
+```javascript
+import { conditionals } from 'slack-block-builder';
+```
+
+```javascript
+import { setIfTruthy, omitIfTruthy, setIfFalsy, omitIfFalsy } from 'slack-block-builder';
+```
+
+Each function accepts to arguments – the first being a value that is evaluated whether it is either `null`, `undefined`, or `false`, and the second being the value to set or omit:
+
+```javascript
+import { Modal, Blocks, Elements, Bits, setIfTruthy } from 'slack-block-builder';
+
+export default ({ groups, selectedGroup, selectedGroupMembers }) => Modal()
+  .title('Edit Groups')
+  .callbackId('submit-edit-groups')
+  .blocks(
+    Blocks.Section({ text: 'Hello! Need to edit some groups?'}),
+    Blocks.Input({ label: 'Select a group to get started' })
+      .dispatchAction()
+      .element(
+        Elements.StaticSelect({ placeholder: 'Select a group...' })
+          .actionId('selectedGroup')
+          .options(groups
+            .map(({ name, id }) => Bits.Option({ text: name, value: id })))),
+    setIfTruthy(selectedGroup, [
+      Blocks.Input({ label: 'Current group members' })
+        .element(
+          Elements.UserMultiSelect({ placeholder: 'Select members...' })
+            .actionId('groupMembers')
+            .initialUsers(selectedGroupMembers))
+    ]))
+  .submit(setIfTruthy(selectedGroup, 'Save Changes'))
+  .buildToJSON();
+```
+
+These functions essentially return either the value passed into as the second argument or `undefined`, depending on the condition. Please note that falsy is defined as `null`, `undefined`, or `false`. To avoid side effects, values such as `0` or `''` are not considered to be falsy.