jsx-slack
Version:
Build JSON object for Slack Block Kit surfaces from JSX
143 lines (142 loc) • 5.01 kB
TypeScript
/** @jsx createElementInternal */
import { MrkdwnElement } from '@slack/types';
import { JSXSlack } from '../../jsx';
interface MrkdwnProps {
children: JSXSlack.ChildElements;
/**
* A boolean value whether to bypass HTML-like formatting by jsx-slack.
*
* If enabled, you can bypass HTML-like formatting, and disable auto escape for
* [mrkdwn special chracters](https://api.slack.com/reference/surfaces/formatting#escaping).
* The defined string in the content will be set as the `text` field of text
* composition object as is. Any JSX tags cannot use in contents.
*
* It's useful for rendering a raw string that is including
* [advanced mrkdwn format for Slack](https://api.slack.com/reference/surfaces/formatting#advanced).
*
* ```jsx
* <Blocks>
* <Section>
* <Mrkdwn raw verbatim>
* {'Hey <@U0123ABCD>, thanks for submitting your report.'}
* </Mrkdwn>
* </Section>
* </Blocks>
* ```
*/
raw?: boolean;
/**
* A boolean value whether to disable automatic parsing for links, channel
* names, and mentions by Slack. Will parse if not defined.
*
* @remarks
* **We recommend always use `<Mrkdwn verbatim>` in your app.**
*
* Slack is pointing out it has some possibilities for breaking messages.
* _Read "[Why you should consider disabling automatic parsing](https://api.slack.com/reference/surfaces/formatting#why_you_should_consider_disabling_automatic_parsing)"
* in the documentation by Slack._
*/
verbatim?: boolean;
}
/**
* Generate [the text composition object](https://api.slack.com/reference/block-kit/composition-objects#textthe)
* for `mrkdwn` type.
*
* You should contain the content of the message formatted by HTML-like elements
* in its children (except for `<Mrkdwn raw>`).
*
* jsx-slack built-in components that allowed HTML-like elements in children
* generate an implicit text composition object using `mrkdwn` type with
* recommended usage by Slack. You can override it by defining `<Mrkdwn>` as an
* only element of supported components.
*
* ---
*
* ### Bypass HTML-like formatting
*
* HTML-like formatting by jsx-slack is a comfortable way to define Slack Block
* Kit surfaces with familiar syntaxes, but auto-escape for
* [mrkdwn special chracters](https://api.slack.com/reference/surfaces/formatting#escaping)
* may interfere with the completed mrkdwn text.
*
* You can use `<Mrkdwn raw>` if you want to use the raw mrkdwn string as is. It
* bypasses HTML-like formatting so you cannot use any JSX tags in contents.
*
* ```jsx
* <Blocks>
* <Section>
* <Mrkdwn raw verbatim>
* {'Hey <@U0123ABCD>, thanks for submitting your report.'}
* </Mrkdwn>
* </Section>
* </Blocks>
* ```
*
* ---
*
* ### Automatic parsing _([not recommended](https://api.slack.com/reference/surfaces/formatting#why_you_should_consider_disabling_automatic_parsing))_
*
* jsx-slack has disabled automatic parsing of URL, mention, and channel link by
* Slack to prevent breaking explicitly specified formatting. By using
* `<Mrkdwn verbatim={false}>`, you can instruct to enable parsing them.
*
* ```jsx
* <Blocks>
* {
* // Section block
* }
* <Section>
* <Mrkdwn verbatim={false}>https://example.com/</Mrkdwn>
* </Section>
* {
* // Section block with fields
* }
* <Section>
* <Field>
* <Mrkdwn verbatim={false}>#general</Mrkdwn>
* </Field>
* </Section>
* {
* // Context block
* }
* <Context>
* <Mrkdwn verbatim={false}>@here</Mrkdwn>
* Hello!
* </Context>
* {
* // Confirm composition object
* }
* <Actions>
* <Button
* confirm={
* <Confirm title="Commit your action" confirm="Yes, please" deny="Cancel">
* <Mrkdwn verbatim={false}>
* <b>@foobar</b> Are you sure?
* </Mrkdwn>
* </Confirm>
* }
* >
* Button
* </Button>
* </Actions>
* </Blocks>
* ```
*
* @remarks
* **We recommend never to turn on automatic parsing via
* `<Mrkdwn verbatim={false}>` in your app.** It's just an escape hatch, and
* probably you always must use `<Mrkdwn verbatim>`.
*
* Slack is pointing out it has some possibilities for breaking messages. _Read
* "[Why you should consider disabling automatic parsing](https://api.slack.com/reference/surfaces/formatting#why_you_should_consider_disabling_automatic_parsing)"
* in the documentation by Slack._
*
* @returns The JSON of the composition object for mrkdwn text
*/
export declare const Mrkdwn: import("../../jsx-internals").BuiltInComponent<MrkdwnProps>;
export declare const mrkdwn: (text: JSXSlack.ChildElements, defaultOpts?: Omit<MrkdwnProps, 'children'>, force?: boolean) => MrkdwnElement;
export declare const mrkdwnForOption: (children: JSXSlack.ChildElements, defaultOpts?: Omit<MrkdwnProps, 'children'>) => {
text: MrkdwnElement;
description?: MrkdwnElement | undefined;
};
export {};