docs: basic styles, mentions, links sections

Author: hejsztynx

docs/docs/rich-text-formatting/basic-styles.md

@@ -0,0 +1,116 @@
+---
+sidebar_position: 1
+---
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import BasicStylesEditor from '@site/src/examples/BasicStylesEditor';
+import BasicStylesEditorSrc from '!!raw-loader!@site/src/examples/BasicStylesEditor';
+
+# Basic styles
+
+In [Your first editor](/fundamentals/your-first-editor) you wired up a single
+**Bold** button. Every other formatting style works exactly the same way: a
+`toggle` method on the `ref` changes the text, and `onChangeState` reports back
+whether the style is active. The only exceptions to that rule are **mentions**,
+**links** and **inline images**, which work a bit differently. They cannot be toggled
+on/off on any text - they require additional data to be valid,but you'll learn more
+about them in further sections. This page walks through the rest of the basic rich
+text styles and the one core distinction that shapes how they behave - **inline**
+versus **paragraph** formatting.
+
+## Inline styles
+
+Inline styles wrap a range of characters. Toggling one applies it to exactly the
+characters you have selected, or - if nothing is selected - arms it so the next
+characters you type come out styled. This is the family the bold belongs to:
+
+- **Bold** - `toggleBold()`
+- **Italic** - `toggleItalic()`
+- **Underline** - `toggleUnderline()`
+- **Strikethrough** - `toggleStrikeThrough()`
+- **Inline code** - `toggleInlineCode()`
+
+They combine freely, so a word can be bold and italic and underlined at
+once.
+
+:::note
+
+There are two more inline styles, which you cannot toggle quite like the others - **links** and **mentions**. You'll learn about them in their respective sections, once you finish this chapter.
+
+:::
+
+## Paragraph styles
+
+Paragraph styles apply to a whole paragraph at once. Toggling one affects the entire paragraph the
+cursor sits in (or every paragraph the selection touches), no matter how much of
+it is actually selected. The common ones are:
+
+- **Headings** - `toggleH1()` through `toggleH6()`
+- **Blockquote** - `toggleBlockQuote()`
+- **Code block** - `toggleCodeBlock()`
+- **Unordered list** - `toggleUnorderedList()`
+- **Ordered list** - `toggleOrderedList()`
+- **Checkbox list** - `toggleCheckboxList(checked: boolean)`
+
+:::note
+
+We will not touch list styles for now - we'll cover them in-depth in their [own section](/rich-text-formatting/lists).
+
+:::
+
+The key difference from inline styles is that **a paragraph can only have one
+paragraph style at a time**. A line can't be both a heading and a blockquote, so
+toggling a second paragraph style replaces the first rather than stacking on top.
+The editor surfaces this through the `isConflicting` flag in `onChangeState`.
+
+Code blocks go one step further: they **block** inline styles entirely. You
+can't make text bold inside a code block, and `onChangeState` reports bold as
+`isBlocking` there so you can grey the button out.
+
+:::tip
+
+The full table of what every style blocks or conflicts with is available in
+[Supported tags](/fundamentals/html-format-and-supported-tags) and the `onChangeState` behavior is described in [Style state model](/fundamentals/core-concepts#the-style-state-model).
+
+:::
+
+## Building the toolbar
+
+A toolbar with many styles is just the [first editor](/fundamentals/your-first-editor)
+loop repeated. Each button reads its slice of the `onChangeState` payload for
+`isActive` (to highlight it) and `isBlocking` (to disable it), and calls the
+matching `toggle` method on press:
+
+```tsx
+const inlineButtons = [
+  { label: 'Bold', state: state?.bold, onPress: () => ref.current?.toggleBold() },
+  { label: 'Italic', state: state?.italic, onPress: () => ref.current?.toggleItalic() },
+  { label: 'Underline', state: state?.underline, onPress: () => ref.current?.toggleUnderline() },
+  { label: 'Strike', state: state?.strikeThrough, onPress: () => ref.current?.toggleStrikeThrough() },
+];
+
+const paragraphButtons = [
+  { label: 'H1', state: state?.h1, onPress: () => ref.current?.toggleH1() },
+  { label: 'H2', state: state?.h2, onPress: () => ref.current?.toggleH2() },
+  { label: 'Quote', state: state?.blockQuote, onPress: () => ref.current?.toggleBlockQuote() },
+  { label: 'Code', state: state?.codeBlock, onPress: () => ref.current?.toggleCodeBlock() },
+];
+```
+
+## Try it out
+
+And just like that we've expanded our editor with several new styles to choose
+from a small toolbar. Select some text and toggle inline styles, or place the cursor
+on a line and try the paragraph ones - notice how switching from **H1** to **Quote**
+swaps the style instead of adding to it, and how the inline buttons grey out once
+you're inside a **Code** block.
+
+<InteractiveExample src={BasicStylesEditorSrc} component={BasicStylesEditor} />
+
+:::info
+
+This page is about _what_ each style does, using the built-in defaults. To change
+how they look - heading sizes, blockquote borders, code block colors - see
+[Styling the input](/core-functionalities/styling-the-input).
+
+:::

docs/docs/rich-text-formatting/basic-styles.mdx

@@ -0,0 +1,115 @@
+---
+sidebar_position: 2
+---
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import LinksEditor from '@site/src/examples/LinksEditor';
+import LinksEditorSrc from '!!raw-loader!@site/src/examples/LinksEditor';
+
+# Links
+
+A link is a piece of text with a URL attached to it. The editor creates links in
+two ways - **automatically**, as the user types something that looks like a URL,
+and **manually**, when you call `setLink` on a range of text. The two produce
+links that behave differently, so it's worth understanding both.
+
+## Automatic links
+
+By default the editor watches what the user types and turns anything that looks
+like a URL into a link on its own - no code required. These are **autolinks**.
+
+Because an autolink is tied to the text that produced it, it stays a link only as
+long as that text still matches. The moment the user edits the words, the pattern
+no longer holds and the link naturally breaks.
+
+### Customizing detection
+
+You control what counts as a link with the
+`linkRegex` prop. Pass your own `RegExp`
+to recognize custom patterns - for example, only `https://` URLs or a custom
+scheme that detects references like `issue-123`:
+
+```tsx
+// Detect "issue-123" style tokens as links.
+const linkRegex = /issue-\d+/g;
+
+<EnrichedTextInput linkRegex={linkRegex} /* ... */ />;
+```
+
+:::note
+
+On iOS and Android the pattern is matched by the platform's native regex engine,
+so not every JavaScript regex feature is available there - variable-width
+lookbehinds, for instance, won't work. Pass `null` to turn automatic detection
+off entirely.
+
+:::
+
+## Manual links
+
+Manual links are applied explicitly with the
+`setLink` ref method:
+
+```ts
+setLink(start: number, end: number, text: string, url: string)
+```
+
+It sets a link over the range from `start` to `end`, showing `text` and pointing
+at `url`. Unlike an autolink, a manual link is a real, standalone style - the
+user can keep editing its text and it stays a link.
+
+:::tip
+
+The three positional arguments line up exactly with the
+`onChangeSelection` event payload, which reports
+the current `start`, `end`, and the `text` it spans. So "link the current
+selection" can be implemented quite simply:
+
+:::
+
+```tsx
+const [selection, setSelection] = useState<OnChangeSelectionEvent | null>(null);
+
+// ...
+<EnrichedTextInput
+  onChangeSelection={e => setSelection(e.nativeEvent)}
+  /* ... */
+/>;
+
+const addLink = () => {
+  if (!selection) return;
+  ref.current?.setLink(
+    selection.start,
+    selection.end,
+    selection.text,
+    'https://swmansion.com',
+  );
+};
+```
+
+:::tip
+
+Passing a different `text` than what's selected replaces the selected text before
+applying the link. To strip a link while keeping its text, call
+`removeLink(start, end)`.
+
+:::
+
+## Try it out
+
+The editor below uses a custom `linkRegex` that autolinks `issue-123` tokens on
+top of the usual URL detection - type either and watch it become a link. Then
+select some words and hit **Link the selection** to attach a URL manually.
+Notice the difference afterward: editing the manual link's text keeps it a link,
+while editing an autolinked token breaks it.
+
+<InteractiveExample src={LinksEditorSrc} component={LinksEditor} />
+
+:::info
+
+This page covers creating and detecting links. To react to links the user
+touches, listen for the
+`onLinkDetected` event, and to change how
+links look, see [Styling the input](/core-functionalities/styling-the-input).
+
+:::

docs/docs/rich-text-formatting/links.md

@@ -0,0 +1,97 @@
+---
+sidebar_position: 3
+---
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import MentionEditor from '@site/src/examples/MentionEditor';
+import MentionEditorSrc from '!!raw-loader!@site/src/examples/MentionEditor';
+
+# Mentions
+
+This is a powerful feature allowing for a customizable inline style for a "mentioning" phrase - `@someone`,
+`#some-channel`, or whatever pattern fits your app. Each mention is able to carry any custom data you attach to it, so it's more than
+styled text: it's a reference you can act on later.
+
+## Mention indicators
+
+A mention begins with an **indicator** - a single character that tells the editor
+"a mention starts here". The set of recognized indicators is controlled by the
+`mentionIndicators` prop, which defaults to
+`['@']`:
+
+```tsx
+// Recognize both @user and #channel mentions.
+<EnrichedTextInput mentionIndicators={['@', '#']} /* ... */ />;
+```
+
+Typing one of these characters starts a mention. You can also start one
+programmatically with `startMention(indicator)`.
+
+## Inserting a mention with `setMention`
+
+Once a mention is being edited - the user has typed an indicator, or you've
+called `startMention` - you insert the finished mention with `setMention`:
+
+```ts
+setMention(
+  indicator: string,
+  text: string,
+  attributes?: Record<string, string>,
+)
+```
+
+`setMention` replaces whatever the user has typed including the indicator with
+`text`. It also stores any `attributes` you pass - this is useful if you want to associate a mention with some data. Those attributes are preserved through the HTML, so they
+survive a round-trip through `getHTML` and `setValue`.
+
+```tsx
+const insertMention = (user: { id: string; name: string }) => {
+  ref.current?.setMention('@', `@${user.name}`, { id: user.id });
+};
+```
+
+:::note
+
+`setMention` is only operational when an actual mention preceded by an indicator is being edited. Otherwise it does nothing.
+
+:::
+
+## Try it out
+
+Type `@`, then tap the button to turn it
+into a completed `@mention`. Notice how you can type a part of a mention, e.g. `@Jo`, move the cursor inside its range and the mention insertion will properly replace it. The result is a single styled unit - try deleting one of its characters and see how it's removed.
+
+<InteractiveExample src={MentionEditorSrc} component={MentionEditor} />
+
+:::note
+
+A mention query spans up to two words - the editor keeps tracking the mention after one
+space, and a second space ends it. That makes `@John Doe` a valid mention.
+
+:::
+
+## Driving mentions with events
+
+This example is deliberately bare-bones - one hard-coded user behind a button.
+A real app watches what the user types after the
+indicator and shows a picker. Three events give you everything you need for
+that:
+
+- **`onStartMention`** fires when a mention starts - a good moment to open your suggestion list.
+- **`onChangeMention`** fires on every edit to the query, handing you the text
+  typed after the indicator - use it to filter the list.
+- **`onEndMention`** fires when the mention stops being edited - the cursor
+  moved away, or the query was closed - so you can dismiss the list.
+
+You'd open the list on `onStartMention`, filter it on `onChangeMention`, and
+call `setMention` when the user picks someone. This example doesn't wire up any
+of that; the full picker flow is covered end-to-end in the
+[Mention-only input](/guides/mention-only-input) guide.
+
+:::tip
+
+Prefix your custom attribute names with `data-` (e.g. `{ 'data-profile-url': user.profileUrl }`).
+Non-standard attributes can be dropped when the HTML passes through a sanitizer -
+this library's, or one on your own backend - whereas `data-*` attributes are the HTML standard for persisting custom data and are kept.
+
+:::