From 6541d1c0627ea228c07a380e232ffc74a99ae7a8 Mon Sep 17 00:00:00 2001 From: Vitali Haradkou Date: Tue, 4 Oct 2022 22:51:19 +0400 Subject: [PATCH] fix link props add docs about each react component --- packages/docs/docs/api/fmt/react/bold.mdx | 16 +++++++-- packages/docs/docs/api/fmt/react/cash.mdx | 35 +++++++++---------- packages/docs/docs/api/fmt/react/code.mdx | 21 +++++++++++ packages/docs/docs/api/fmt/react/command.mdx | 19 ++++++++++ packages/docs/docs/api/fmt/react/email.mdx | 21 +++++++++++ packages/docs/docs/api/fmt/react/hash.mdx | 29 +++++++-------- packages/docs/docs/api/fmt/react/italic.mdx | 20 +++++++++-- packages/docs/docs/api/fmt/react/link.mdx | 20 +++++++++++ packages/docs/docs/api/fmt/react/mention.mdx | 19 ++++++++++ packages/docs/docs/api/fmt/react/phone.mdx | 23 ++++++++++++ packages/docs/docs/api/fmt/react/render.mdx | 26 +++++++------- packages/docs/docs/api/fmt/react/spoiler.mdx | 21 +++++++++++ .../docs/docs/api/fmt/react/strikethrough.mdx | 20 +++++++---- .../docs/docs/api/fmt/react/underline.mdx | 20 +++++++++-- packages/docs/docs/tutorial/fmt/jsx.mdx | 4 ++- packages/fmt/react/link.tsx | 14 ++++++-- 16 files changed, 266 insertions(+), 62 deletions(-) diff --git a/packages/docs/docs/api/fmt/react/bold.mdx b/packages/docs/docs/api/fmt/react/bold.mdx index 1388c8e..6573e7c 100644 --- a/packages/docs/docs/api/fmt/react/bold.mdx +++ b/packages/docs/docs/api/fmt/react/bold.mdx @@ -1,7 +1,19 @@ -# Bold +# Bold API Mark input text as **bold** +added in 1.5.0 + +## Import + +```jsx +import Bold from "@tlgr/fmt/react/bold"; +// or +import { Bold } from "@tlgr/fmt/react"; +``` + ## Props -### children - JSX element or string +| Name | Type | Default | Description | +| -------- | ---- | ------- | ----------------------------- | +| children | node | | The content of the component. | diff --git a/packages/docs/docs/api/fmt/react/cash.mdx b/packages/docs/docs/api/fmt/react/cash.mdx index 196908d..b3c05a9 100644 --- a/packages/docs/docs/api/fmt/react/cash.mdx +++ b/packages/docs/docs/api/fmt/react/cash.mdx @@ -1,24 +1,23 @@ -# Cash +# Cash API -## cash(number, opts) +append currency to number -Added in 1.3.0 +added in 1.5.0 -Mark input number with cash +## Import -- `number` - <[number][number]> Cash price. -- `opts` - <[Object][object]> format options. +```jsx +import Cash from "@tlgr/fmt/react/cash"; +// or +import { Cash } from "@tlgr/fmt/react"; +``` - - `locale` - <[string][string]> format locale. Default `en-US`. - - `currency` - <[string][string]> Currency code, e.g. `JPY`, `USD`, `EUR`. Default `USD`. - - `currencyDisplay` - <[string][string]>. Currency display. - - `maximumSignificantDigits` - <[number][number]> maximum digits for not floating part. - - `minimumSignificantDigits` - <[number][number]> minimum digits for not floating part. - - `maximumFractionDigits` - <[number][number]> maximum digits for floating part. - - `minimumFractionDigits` - <[number][number]> maximum digits for floating part. - - `minimumIntegerDigits` - <[number][number]> minimum integer digits. - - `signDisplay` - <[string][string]> sign display. Possible values: `auto` | `never` | `always` | `exceptZero`. +## Props + +| Name | Type | Default | Description | +| --------------- | ------ | ------- | -------------------------------- | +| cash | string | | Required. numeric representation | +| locale | string | en-US | Intl.format locale | +| currency | string | USD | Intl.format currency code | +| currencyDisplay | string | $ | Intl.format currency display | -[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#numeric_types -[object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object -[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type diff --git a/packages/docs/docs/api/fmt/react/code.mdx b/packages/docs/docs/api/fmt/react/code.mdx index e69de29..dd638d4 100644 --- a/packages/docs/docs/api/fmt/react/code.mdx +++ b/packages/docs/docs/api/fmt/react/code.mdx @@ -0,0 +1,21 @@ +# Code API + +Returns code snippet representation + +added in 1.5.0 + +## Import + +```jsx +import Code from "@tlgr/fmt/react/code"; +// or +import { Code } from "@tlgr/fmt/react"; +``` + +## Props + +| Name | Type | Default | Description | +| -------- | ------ | ------- | ----------------------------------------------------- | +| children | node | | The content of the component. | +| type | string | inline | Component render type. Can be "inline" or "multiline" | +| lang | string | | language code. E.g. `python`, `py`, `js` | diff --git a/packages/docs/docs/api/fmt/react/command.mdx b/packages/docs/docs/api/fmt/react/command.mdx index e69de29..de20e92 100644 --- a/packages/docs/docs/api/fmt/react/command.mdx +++ b/packages/docs/docs/api/fmt/react/command.mdx @@ -0,0 +1,19 @@ +# Command API + +Add `/` to command name + +added in 1.5.0 + +## Import + +```jsx +import Command from "@tlgr/fmt/react/command"; +// or +import { Command } from "@tlgr/fmt/react"; +``` + +## Props + +| Name | Type | Default | Description | +| ---- | ------ | ------- | ------------- | +| name | string | | Command name. | diff --git a/packages/docs/docs/api/fmt/react/email.mdx b/packages/docs/docs/api/fmt/react/email.mdx index e69de29..6673f4a 100644 --- a/packages/docs/docs/api/fmt/react/email.mdx +++ b/packages/docs/docs/api/fmt/react/email.mdx @@ -0,0 +1,21 @@ +# Email API + +Returns email representation. Example `first_last@domen.com` + +added in 1.5.0 + +## Import + +```jsx +import Email from "@tlgr/fmt/react/email"; +// or +import { Eommand } from "@tlgr/fmt/react"; +``` + +## Props + +| Name | Type | Default | Description | +| ----- | ------ | ------- | ---------------------------------------------------------------------------------------------------- | +| name | string | | Required for domen. Email name with last name. E.g. `fist_last` | +| domen | string | | Required for name. Email domen. E.g. `example.com` | +| email | string | | Required if name and domen is not provided. full email representation. E.g. `first_last@example.com` | diff --git a/packages/docs/docs/api/fmt/react/hash.mdx b/packages/docs/docs/api/fmt/react/hash.mdx index 0d18add..e3ca9c6 100644 --- a/packages/docs/docs/api/fmt/react/hash.mdx +++ b/packages/docs/docs/api/fmt/react/hash.mdx @@ -1,22 +1,19 @@ -# Hash +# Hash API -## hash(tag) +Add `#` to name -Added in 1.3.0 +added in 1.5.0 -converts `text` to `#text` +## Import -- `tag` - <[string][string]> - Tag name. Should be word without spaces. +```jsx +import Hash from "@tlgr/fmt/react/hash"; +// or +import { Hash } from "@tlgr/fmt/react"; +``` -[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type +## Props -## hashes(tags) - -Added in 1.3.0 - -apply `hash` function for each tag. - -- `tags` - <[Array][array]> - Tags array. Each tag should be a word without spaces. - -[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type -[array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array +| Name | Type | Default | Description | +| ---- | ------ | ------- | ----------- | +| hash | string | | Hash name. | diff --git a/packages/docs/docs/api/fmt/react/italic.mdx b/packages/docs/docs/api/fmt/react/italic.mdx index 764257a..06f4997 100644 --- a/packages/docs/docs/api/fmt/react/italic.mdx +++ b/packages/docs/docs/api/fmt/react/italic.mdx @@ -1,3 +1,19 @@ -# Italic +# Italic API -Marks text _italic_ +Mark input text as _bold_ + +added in 1.5.0 + +## Import + +```jsx +import Italic from "@tlgr/fmt/react/italic"; +// or +import { Italic } from "@tlgr/fmt/react"; +``` + +## Props + +| Name | Type | Default | Description | +| -------- | ---- | ------- | ----------------------------- | +| children | node | | The content of the component. | diff --git a/packages/docs/docs/api/fmt/react/link.mdx b/packages/docs/docs/api/fmt/react/link.mdx index e69de29..17f2d52 100644 --- a/packages/docs/docs/api/fmt/react/link.mdx +++ b/packages/docs/docs/api/fmt/react/link.mdx @@ -0,0 +1,20 @@ +# Link API + +return link representation + +added in 1.5.0 + +## Import + +```jsx +import Link from "@tlgr/fmt/react/link"; +// or +import { Link } from "@tlgr/fmt/react"; +``` + +## Props + +| Name | Type | Default | Description | +| ---- | ------------ | ------- | ------------------ | +| url | `URL/string` | | link URL | +| name | `string` | | link display names | diff --git a/packages/docs/docs/api/fmt/react/mention.mdx b/packages/docs/docs/api/fmt/react/mention.mdx index e69de29..5e27d5c 100644 --- a/packages/docs/docs/api/fmt/react/mention.mdx +++ b/packages/docs/docs/api/fmt/react/mention.mdx @@ -0,0 +1,19 @@ +# Mention API + +return mention to user + +added in 1.5.0 + +## Import + +```jsx +import Mention from "@tlgr/fmt/react/mention"; +// or +import { Mention } from "@tlgr/fmt/react"; +``` + +## Props + +| Name | Type | Default | Description | +| -------- | -------- | ------- | ----------------------------------------- | +| username | `string` | | user name which you would like to mention | diff --git a/packages/docs/docs/api/fmt/react/phone.mdx b/packages/docs/docs/api/fmt/react/phone.mdx index e69de29..f2c3516 100644 --- a/packages/docs/docs/api/fmt/react/phone.mdx +++ b/packages/docs/docs/api/fmt/react/phone.mdx @@ -0,0 +1,23 @@ +# Phone API + +return formatted phone number. + +It uses [`awesome-phonenumber`](https://www.npmjs.com/package/awesome-phonenumber) under the hood. + +added in 1.5.0 + +## Import + +```jsx +import Phone from "@tlgr/fmt/react/phone"; +// or +import { Phone } from "@tlgr/fmt/react"; +``` + +## Props + +| Name | Type | Default | Description | +| ---------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| phone | `string/number` | | phone number | +| format | string | | phone number format | +| regionCode | string | | Region code for the phone number (only required if phoneNumber is on a national format). Example: 'SE' for Sweden, 'CH' for Switzerland, etc. | diff --git a/packages/docs/docs/api/fmt/react/render.mdx b/packages/docs/docs/api/fmt/react/render.mdx index f52687f..1f0182f 100644 --- a/packages/docs/docs/api/fmt/react/render.mdx +++ b/packages/docs/docs/api/fmt/react/render.mdx @@ -1,15 +1,13 @@ -# Fmt +# render -Formatter function which implements node.js `util.inspect` function. +Returns HTML raw texts -Returns raw texts with telegram entities modifiers - -## fmt(input, [...args]) +## render(children, [...args]) added in 1.3.0 -- `input` - <[string][string]>. Input string, accepts `TemplateStringArray` instead of string. -- `args` - <[array][array]> Formatter arguments. See `util.inspect` about inspect arguments. +- `children` - <[JSX.Element][jsxelement]>. Input string, accepts `TemplateStringArray` instead of string. +- `args` - <[Object][object]> reply context object. Note: `render` already uses `{parse_mode: 'HTML'}`. Do not overwrite this property ## returns @@ -18,12 +16,16 @@ Array of raw text without text modifiers and array of modifiers. ### Example ```jsx -const formatteed = fmt(`some ${bold("bold")} text`); -formatted[0]; // some bold text -formatted[1]; // { entities: [ -// { lenght: 4, offset: 5, type: 'bold' } -// ]} +const formatteed = render( + + some bold text + +); +formatted[0]; // some bold text +formatted[1]; // { parse_mode: 'HTML'} ``` +[object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object +[jsxelement]: https://preactjs.com/guide/v10/api-reference/#h--createelement [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type [array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array diff --git a/packages/docs/docs/api/fmt/react/spoiler.mdx b/packages/docs/docs/api/fmt/react/spoiler.mdx index e69de29..6ea6909 100644 --- a/packages/docs/docs/api/fmt/react/spoiler.mdx +++ b/packages/docs/docs/api/fmt/react/spoiler.mdx @@ -0,0 +1,21 @@ +# Spoiler API + +return formatted phone number. + +It uses [`awesome-phonenumber`](https://www.npmjs.com/package/awesome-phonenumber) under the hood. + +added in 1.5.0 + +## Import + +```jsx +import Spoiler from "@tlgr/fmt/react/spoiler"; +// or +import { Spoiler } from "@tlgr/fmt/react"; +``` + +## Props + +| Name | Type | Default | Description | +| -------- | ---- | ------- | ------------ | +| children | node | | spoiler text | diff --git a/packages/docs/docs/api/fmt/react/strikethrough.mdx b/packages/docs/docs/api/fmt/react/strikethrough.mdx index d5ee8c2..d983dc4 100644 --- a/packages/docs/docs/api/fmt/react/strikethrough.mdx +++ b/packages/docs/docs/api/fmt/react/strikethrough.mdx @@ -1,11 +1,19 @@ -# Strikethrough +# Strikethrough API -Marks text as strikethrough +return strikethrough text -## strikethrough(text) +added in 1.5.0 -Added in 1.3.0 +## Import -## returns +```jsx +import Strikethrough from "@tlgr/fmt/react/strikethrough"; +// or +import { Strikethrough } from "@tlgr/fmt/react"; +``` -decorated text +## Props + +| Name | Type | Default | Description | +| -------- | ---- | ------- | -------------- | +| children | node | | component text | diff --git a/packages/docs/docs/api/fmt/react/underline.mdx b/packages/docs/docs/api/fmt/react/underline.mdx index fd02efc..e8e9acf 100644 --- a/packages/docs/docs/api/fmt/react/underline.mdx +++ b/packages/docs/docs/api/fmt/react/underline.mdx @@ -1,3 +1,19 @@ -# Underline +# Underline API -Marks text as underline +returns Underline text + +added in 1.5.0 + +## Import + +```jsx +import Underline from "@tlgr/fmt/react/underline"; +// or +import { Underline } from "@tlgr/fmt/react"; +``` + +## Props + +| Name | Type | Default | Description | +| -------- | ---- | ------- | -------------- | +| children | node | | component text | diff --git a/packages/docs/docs/tutorial/fmt/jsx.mdx b/packages/docs/docs/tutorial/fmt/jsx.mdx index 60bd4ed..abbb751 100644 --- a/packages/docs/docs/tutorial/fmt/jsx.mdx +++ b/packages/docs/docs/tutorial/fmt/jsx.mdx @@ -59,8 +59,10 @@ bot.start((ctx) => { bot.launch(); ``` -::: tip +:::tip + Better to wrap high-level component with `Fragment` component from `preact` library. + ::: ## Limitations & Pitfalls diff --git a/packages/fmt/react/link.tsx b/packages/fmt/react/link.tsx index 93f64a2..98e2723 100644 --- a/packages/fmt/react/link.tsx +++ b/packages/fmt/react/link.tsx @@ -1,6 +1,14 @@ import { h } from 'preact'; -export default function (url: string | URL, name?: string) { - const link = url.toString(); - return {name ?? link} +type Props = { + url: string | URL; + name?: string; +} + +/** + * Returns HTML link representation + */ +export default function (props: Props) { + const link = props.url.toString(); + return {props.name ?? link} }