slack-block-builder - npm Package Compare versions

Comparing version 2.0.0-beta.3 to 2.0.0-beta.4

dist/helpers/get-built-collection.d.ts

 import type { Builder, SlackDto } from '../lib';
-import type { OneOrArray } from '../types';
+import type { Appendable } from '../types';
 export declare type Collection<T> = T[];
-export declare function getBuiltCollection<T extends Builder, Dto extends SlackDto>(...builders: Array<OneOrArray<T>>): Collection<Dto> | [];
+export declare function getBuiltCollection<T extends Builder, Dto extends SlackDto>(...builders: Appendable<T>): Collection<Dto>;

dist/index.d.ts

 export * from './bits';
 export * from './blocks';
 export * from './elements';
+export * from './md';
 export * from './surfaces';
 export * from './utilities';
 export type { SlackDto, SlackViewDto, SlackBlockDto, SlackElementDto, SlackMessageDto, } from './lib';

dist/index.js

@@ -16,3 +16,4 @@ "use strict";
 __exportStar(require("./elements"), exports);
+__exportStar(require("./md"), exports);
 __exportStar(require("./surfaces"), exports);
 __exportStar(require("./utilities"), exports);

dist/lib/builder.d.ts

@@ -7,3 +7,3 @@ import type { ObjectLiteral, Ctor } from '../types';
     protected append(value: unknown[], prop: string): this;
-    protected getResult<T>(Clazz: Ctor<T>, overrideProps?: ObjectLiteral): T;
+    protected getResult<T>(Clazz: Ctor<T>, overrideProps?: ObjectLiteral): Readonly<T>;
 }

dist/lib/builder.js

@@ -32,3 +32,4 @@ "use strict";
     getResult(Clazz, overrideProps) {
-        return new Clazz({ ...this.props, ...overrideProps });
+        const result = new Clazz({ ...this.props, ...overrideProps });
+        return Object.freeze(result);
     }
@@ -35,0 +36,0 @@ /** @internal */

dist/lib/slack-dto.d.ts

@@ -83,14 +83,11 @@ import { SurfaceType, BlockType, ElementType } from '../constants';
 }
-export declare class SlackTypeableDto extends SlackDto {
-    readonly type: string;
-}
-export declare class SlackViewDto extends SlackTypeableDto {
+export declare class SlackViewDto extends SlackDto {
     readonly type: SurfaceType;
     readonly blocks: SlackBlockDto[];
 }
-export declare class SlackBlockDto extends SlackTypeableDto {
+export declare class SlackBlockDto extends SlackDto {
     readonly type: BlockType;
 }
-export declare class SlackElementDto extends SlackTypeableDto {
+export declare class SlackElementDto extends SlackDto {
     readonly type: ElementType;
 }

dist/lib/slack-dto.js

 "use strict";
 /* eslint-disable max-classes-per-file */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SlackElementDto = exports.SlackBlockDto = exports.SlackViewDto = exports.SlackTypeableDto = exports.SlackMessageDto = exports.SlackDto = exports.Param = void 0;
+exports.SlackElementDto = exports.SlackBlockDto = exports.SlackViewDto = exports.SlackMessageDto = exports.SlackDto = exports.Param = void 0;
 var Param;
@@ -93,13 +93,10 @@ (function (Param) {
 exports.SlackMessageDto = SlackMessageDto;
-class SlackTypeableDto extends SlackDto {
+class SlackViewDto extends SlackDto {
 }
-exports.SlackTypeableDto = SlackTypeableDto;
-class SlackViewDto extends SlackTypeableDto {
-}
 exports.SlackViewDto = SlackViewDto;
-class SlackBlockDto extends SlackTypeableDto {
+class SlackBlockDto extends SlackDto {
 }
 exports.SlackBlockDto = SlackBlockDto;
-class SlackElementDto extends SlackTypeableDto {
+class SlackElementDto extends SlackDto {
 }
 exports.SlackElementDto = SlackElementDto;

dist/methods/append-methods.d.ts

@@ -5,3 +5,3 @@ import { Builder } from '../lib';
 import type { OptionGroupBuilder } from '../bits/option-group';
-import type { OneOrArray, FilterString } from '../types';
+import type { Appendable, FilterString } from '../types';
 export declare abstract class Attachments extends Builder {
@@ -14,3 +14,3 @@ /**
      */
-    attachments(attachment: OneOrArray<AttachmentBuilder>, ...attachments: Array<OneOrArray<AttachmentBuilder>>): this;
+    attachments(...attachments: Appendable<AttachmentBuilder>): this;
 }
@@ -28,3 +28,3 @@ export declare abstract class Blocks<T> extends Builder {
      */
-    blocks(block: OneOrArray<T>, ...blocks: Array<OneOrArray<T>>): this;
+    blocks(...blocks: Appendable<T>): this;
 }
@@ -43,3 +43,3 @@ export declare abstract class Elements<T> extends Builder {
      */
-    elements(element: OneOrArray<T>, ...elements: Array<OneOrArray<T>>): this;
+    elements(...elements: Appendable<T>): this;
 }
@@ -59,3 +59,3 @@ export declare abstract class Fields extends Builder {
      */
-    fields(field: OneOrArray<string>, ...fields: Array<OneOrArray<string>>): this;
+    fields(...fields: Appendable<string>): this;
 }
@@ -72,3 +72,3 @@ export declare abstract class Filter extends Builder {
      */
-    filter(filter: OneOrArray<FilterString>, ...filters: Array<OneOrArray<FilterString>>): this;
+    filter(...filters: Appendable<FilterString>): this;
 }
@@ -82,3 +82,3 @@ export declare abstract class InitialChannels extends Builder {
      */
-    initialChannels(channelId: OneOrArray<string>, ...channelIds: Array<OneOrArray<string>>): this;
+    initialChannels(...channelIds: Appendable<string>): this;
 }
@@ -92,3 +92,3 @@ export declare abstract class InitialConversations extends Builder {
      */
-    initialConversations(conversationId: OneOrArray<string>, ...conversationIds: Array<OneOrArray<string>>): this;
+    initialConversations(...conversationIds: Appendable<string>): this;
 }
@@ -105,3 +105,3 @@ export declare abstract class InitialOptions extends Builder {
      */
-    initialOptions(option: OneOrArray<OptionBuilder>, ...options: Array<OneOrArray<OptionBuilder>>): this;
+    initialOptions(...options: Appendable<OptionBuilder>): this;
 }
@@ -115,3 +115,3 @@ export declare abstract class InitialUsers extends Builder {
      */
-    initialUsers(userId: OneOrArray<string>, ...userIds: Array<OneOrArray<string>>): this;
+    initialUsers(...userIds: Appendable<string>): this;
 }
@@ -129,3 +129,3 @@ export declare abstract class OptionGroups extends Builder {
      */
-    optionGroups(optionGroup: OneOrArray<OptionGroupBuilder>, ...optionGroups: Array<OneOrArray<OptionGroupBuilder>>): this;
+    optionGroups(...optionGroups: Appendable<OptionGroupBuilder>): this;
 }
@@ -144,3 +144,3 @@ export declare abstract class Options extends Builder {
      */
-    options(option: OneOrArray<OptionBuilder>, ...options: Array<OneOrArray<OptionBuilder>>): this;
+    options(...options: Appendable<OptionBuilder>): this;
 }

dist/methods/append-methods.js

@@ -9,2 +9,8 @@ "use strict";
 class Attachments extends lib_1.Builder {
+    /**
+     * @description Adds attachments to your message.
+     *
+     * {@link https://api.slack.com/block-kit|Open Official Slack Block Kit Documentation}
+     * {@link https://www.blockbuilder.dev|Open Block Builder Documentation}
+     */
     attachments(...attachments) {
@@ -16,2 +22,12 @@ return this.append(attachments.flat(), constants_1.Prop.Attachments);
 class Blocks extends lib_1.Builder {
+    /**
+     * @description Adds blocks to your view or message.
+     *
+     * **Slack Validation Rules and Tips:**
+     *    * **Required for modals, home tabs, and workflow steps** ⚠
+     *    * Maximum of 100 blocks.
+     *
+     * {@link https://api.slack.com/block-kit|Open Official Slack Block Kit Documentation}
+     * {@link https://www.blockbuilder.dev|Open Block Builder Documentation}
+     */
     blocks(...blocks) {
@@ -23,2 +39,13 @@ return this.append(blocks.flat(), constants_1.Prop.Blocks);
 class Elements extends lib_1.Builder {
+    /**
+     * @description Adds elements to the actions block.
+     *
+     * **Slack Validation Rules and Tips:**
+     *    * **Required** ⚠
+     *    * Maximum of 5 elements.
+     *    * Supported elements are buttons, select and overflow menus, and date pickers.
+     *
+     * {@link https://api.slack.com/block-kit|Open Official Slack Block Kit Documentation}
+     * {@link https://www.blockbuilder.dev|Open Block Builder Documentation}
+     */
     elements(...elements) {
@@ -30,2 +57,14 @@ return this.append(elements.flat(), constants_1.Prop.Elements);
 class Fields extends lib_1.Builder {
+    /**
+     * @description Adds text fields to the section block, in two columns, side-by-side.
+     *
+     * **Slack Validation Rules and Tips:**
+     *    * **Required if the text property is undefined** ⚠
+     *    * Maximum of 10 items.
+     *    * Maximum of 2000 characters for each field.
+     *    * Markdown supported.
+     *
+     * {@link https://api.slack.com/block-kit|Open Official Slack Block Kit Documentation}
+     * {@link https://www.blockbuilder.dev|Open Block Builder Documentation}
+     */
     fields(...fields) {
@@ -37,2 +76,11 @@ return this.append(fields.flat(), constants_1.Prop.Fields);
 class Filter extends lib_1.Builder {
+    /**
+     * @description Defines which conversations should be included in the list.
+     *
+     * **Slack Validation Rules and Tips:**
+     *    * Possible values are *im*, *impm*, *private*, and *public*.
+     *
+     * {@link https://api.slack.com/block-kit|Open Official Slack Block Kit Documentation}
+     * {@link https://www.blockbuilder.dev|Open Block Builder Documentation}
+     */
     filter(...filters) {
@@ -44,2 +92,8 @@ return this.append(filters.flat(), constants_1.Prop.Filter);
 class InitialChannels extends lib_1.Builder {
+    /**
+     * @description Pre-populates the menu with selected, default channels.
+     *
+     * {@link https://api.slack.com/block-kit|Open Official Slack Block Kit Documentation}
+     * {@link https://www.blockbuilder.dev|Open Block Builder Documentation}
+     */
     initialChannels(...channelIds) {
@@ -51,2 +105,8 @@ return this.append(channelIds.flat(), constants_1.Prop.InitialChannels);
 class InitialConversations extends lib_1.Builder {
+    /**
+     * @description Pre-populates the menu with selected, default conversations.
+     *
+     * {@link https://api.slack.com/block-kit|Open Official Slack Block Kit Documentation}
+     * {@link https://www.blockbuilder.dev|Open Block Builder Documentation}
+     */
     initialConversations(...conversationIds) {
@@ -58,2 +118,11 @@ return this.append(conversationIds.flat(), constants_1.Prop.InitialConversations);
 class InitialOptions extends lib_1.Builder {
+    /**
+     * @description Pre-populates the menu or checkbox input with selected, default options.
+     *
+     * **Slack Validation Rules and Tips:**
+     *    * Must be exact matches to options in the menu.
+     *
+     * {@link https://api.slack.com/block-kit|Open Official Slack Block Kit Documentation}
+     * {@link https://www.blockbuilder.dev|Open Block Builder Documentation}
+     */
     initialOptions(...options) {
@@ -65,2 +134,8 @@ return this.append(options.flat(), constants_1.Prop.InitialOptions);
 class InitialUsers extends lib_1.Builder {
+    /**
+     * @description Pre-populates the menu with selected, default users.
+     *
+     * {@link https://api.slack.com/block-kit|Open Official Slack Block Kit Documentation}
+     * {@link https://www.blockbuilder.dev|Open Block Builder Documentation}
+     */
     initialUsers(...userIds) {
@@ -72,2 +147,12 @@ return this.append(userIds.flat(), constants_1.Prop.InitialUsers);
 class OptionGroups extends lib_1.Builder {
+    /**
+     * @description Adds organized groups of options to the select or multi-select menu, each with its own label or title.
+     *
+     * **Slack Validation Rules and Tips:**
+     *    * Maximum of 100 options.
+     *    * Both options and options groups cannot be defined at the same time for any element.
+     *
+     * {@link https://api.slack.com/block-kit|Open Official Slack Block Kit Documentation}
+     * {@link https://www.blockbuilder.dev|Open Block Builder Documentation}
+     */
     optionGroups(...optionGroups) {
@@ -79,2 +164,13 @@ return this.append(optionGroups.flat(), constants_1.Prop.OptionGroups);
 class Options extends lib_1.Builder {
+    /**
+     * @description Adds options to the select or multi-select menu.
+     *
+     * **Slack Validation Rules and Tips:**
+     *    * **Required** ⚠
+     *    * Maximum of 100 options.
+     *    * Both options and options groups cannot be defined at the same time for any element.
+     *
+     * {@link https://api.slack.com/block-kit|Open Official Slack Block Kit Documentation}
+     * {@link https://www.blockbuilder.dev|Open Block Builder Documentation}
+     */
     options(...options) {
@@ -81,0 +177,0 @@ return this.append(options.flat(), constants_1.Prop.Options);

dist/methods/other-methods.d.ts

@@ -12,3 +12,3 @@ import { Builder, SlackDto, SlackBlockDto } from '../lib';
      */
-    buildToObject(): T;
+    buildToObject(): Readonly<T>;
 }
@@ -30,3 +30,3 @@ export declare abstract class End extends Builder {
      */
-    getAttachments(): SlackDto[];
+    getAttachments(): Readonly<SlackDto>[];
 }
@@ -39,3 +39,3 @@ export declare abstract class GetBlocks extends Builder {
      */
-    getBlocks(): SlackBlockDto[];
+    getBlocks(): Readonly<SlackBlockDto>[];
 }
@@ -42,0 +42,0 @@ export declare abstract class PrintPreviewUrl extends Builder {

dist/types/general-interfaces.d.ts

@@ -8,2 +8,2 @@ export interface ObjectLiteral {
 };
-export declare type OneOrArray<T> = T | T[];
+export declare type Appendable<T> = Array<T | T[]>;

dist/utilities/index.d.ts

@@ -1,6 +0,12 @@
-import type { BlockBuilder, OneOrArray } from '../types';
-import type { AttachmentBuilder } from '../bits/attachment';
+import type { BlockBuilder, Appendable } from '../types';
+import type { AttachmentBuilder } from '../bits';
 import type { SlackBlockDto, SlackDto } from '../lib';
-export declare function BlockCollection(block: OneOrArray<BlockBuilder>, ...blocks: Array<OneOrArray<BlockBuilder>>): SlackBlockDto[] | [];
-export declare function AttachmentCollection(attachment: OneOrArray<AttachmentBuilder>, ...attachments: Array<OneOrArray<AttachmentBuilder>>): SlackDto[] | [];
+/**
+ * @description Creates and returns an array of built blocks. Behaves in the same way as all appending methods, such as Surface.blocks().
+ */
+export declare function BlockCollection(...blocks: Appendable<BlockBuilder>): Readonly<SlackBlockDto>[];
+/**
+ * @description Creates and returns an array of built attachments. Behaves in the same way as all appending methods, such as Message.attachments().
+ */
+export declare function AttachmentCollection(...attachments: Appendable<AttachmentBuilder>): Readonly<SlackDto>[];
 declare const utilities: {
@@ -7,0 +13,0 @@ BlockCollection: typeof BlockCollection;

dist/utilities/index.js

 "use strict";
+/* eslint-disable max-len */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Utilities = exports.AttachmentCollection = exports.BlockCollection = void 0;
 const helpers_1 = require("../helpers");
-function BlockCollection(block, ...blocks) {
-    return helpers_1.getBuiltCollection(...[block, ...blocks]);
+/**
+ * @description Creates and returns an array of built blocks. Behaves in the same way as all appending methods, such as Surface.blocks().
+ */
+function BlockCollection(...blocks) {
+    return helpers_1.getBuiltCollection(...blocks);
 }
 exports.BlockCollection = BlockCollection;
-function AttachmentCollection(attachment, ...attachments) {
-    return helpers_1.getBuiltCollection(...[attachment, ...attachments]);
+/**
+ * @description Creates and returns an array of built attachments. Behaves in the same way as all appending methods, such as Message.attachments().
+ */
+function AttachmentCollection(...attachments) {
+    return helpers_1.getBuiltCollection(...attachments);
 }
@@ -12,0 +19,0 @@ exports.AttachmentCollection = AttachmentCollection;

package.json

 {
   "name": "slack-block-builder",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.4",
   "description": "Maintainable code for interactive Slack messages, modals, home tabs, and workflow steps. A must-have for the Slack Block Kit framework.",
@@ -5,0 +5,0 @@ "author": {

README.md

@@ -41,2 +41,3 @@ <p align="center">
 * 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.
 * In-depth [doc site](https://blockbuilder.dev) at [https://blockbuilder.dev](https://blockbuilder.dev).
@@ -101,2 +102,14 @@ * [Support](#block-kit-support-and-reference) for all current Slack Block Kit objects.
 
+The same goes for importing Slack markdown helper functions:
+
+```javascript
+// Importing the Md object
+
+import { Surfaces, Blocks, Md } from 'slack-block-builder';
+
+// Importing the functions top-level
+
+import { Modal, Section, bold, link } from 'slack-block-builder';
+```
+
 ### Group Explanations
@@ -114,2 +127,4 @@
 
+`Md` – Helper functions for formatting text with Slack's markdown. See [Markdown Helpers](#markdown-helpers).
+
 ### Block Kit Support and Reference
@@ -251,3 +266,3 @@
 
-The `Utilities` object contains various utility functions. Currently, there are two:
+The `Utilities` object contains various utility functions for creating UI. Currently, there are two:
 
@@ -295,2 +310,27 @@ `BlockCollection()` – Accepts multiple arguments or an array of blocks and returns them in an array, in their built state.
 
+### 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):
+
+``` javascript
+import { Message, Blocks, Md } from 'slack-block-builder';
+
+const myMdMessage = ({ channel, user }) => {
+  const slashCommands = ['/schedule', '/cancel', '/remind', '/help'];
+
+  return Message({ channel, text: 'Alas, my friend.' })
+    .blocks(
+      Blocks.Section({ text: `:wave: Hi there, ${Md.user(user)}!` }),
+      Blocks.Section({ text: `${Md.italic('Sorry')}, I didn't get that. Why don't you try out some of my slash commands?` }),
+      Blocks.Section({ text: `Here are some of the things that I can do:` }),
+      Blocks.Section()
+        .text(Md.listBullet(slashCommands
+          .map((item) => Md.codeInline(item)))))
+    .asUser()
+    .buildToObject();
+};
+```
+
+[**View Example on Slack Block Kit Builder Website**](https://app.slack.com/block-kit-builder/#%7B%22blocks%22:%5B%7B%22text%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22:wave:%20Hi%20there,%20%3C@U03N067AL%3E%21%22%7D,%22type%22:%22section%22%7D,%7B%22text%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22_Sorry_,%20I%20didn%27t%20get%20that.%20Why%20don%27t%20you%20try%20out%20some%20of%20my%20slash%20commands?%22%7D,%22type%22:%22section%22%7D,%7B%22text%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22Here%20are%20some%20of%20the%20things%20that%20I%20can%20do:%22%7D,%22type%22:%22section%22%7D,%7B%22text%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22%E2%80%A2%20%60/schedule%60%5Cn%E2%80%A2%20%60/cancel%60%5Cn%E2%80%A2%20%60/remind%60%5Cn%E2%80%A2%20%60/help%60%22%7D,%22type%22:%22section%22%7D%5D%7D)
+ 
 ## :link: &nbsp; Other Useful Slack-Related Projects
@@ -297,0 +337,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

260124

increased by4.55%

Number of package files

164

increased by1.23%

Lines of code

5648

increased by5.67%

Number of lines in readme file

348

increased by12.99%

No dependency changes