docs: lists, imgs, alignment, shortcuts sections

Author: hejsztynx

docs/docs/rich-text-formatting/inline-images.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 5
+---
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import ImagesEditor from '@site/src/examples/ImagesEditor';
+import ImagesEditorSrc from '!!raw-loader!@site/src/examples/ImagesEditor';
+
+# Inline images
+
+Aside from just styled text, the library offers much more. This includes inline images - pictures embedded straight into the text flow.
+
+## Inserting an image
+
+You can insert it explicitly with the `setImage` ref method:
+
+```ts
+setImage(src: string, width: number, height: number)
+```
+
+- `src` - an absolute file path or a remote image URL.
+- `width` / `height` - the size the image should render at.
+
+The image lands on its own line at the current selection, replacing any
+selected text.
+
+```tsx
+const insertImage = () => {
+  ref.current?.setImage('https://picsum.photos/320/160', 160, 80);
+};
+```
+
+:::note
+
+You are responsible for the `width` and `height` you pass - the editor does not
+measure the image for you, so if you want to preserve a picture's aspect ratio you
+need to compute it yourself before calling `setImage`.
+
+:::
+
+## When the source can't load
+
+If the `src` can't be resolved - a broken URL, a missing file - the editor doesn't
+error out and renders a static placeholder in the image's place instead.
+
+## Try it out
+
+Place the cursor in the input and insert an image. The first button inserts a real
+photo from [Lorem Picsum](https://picsum.photos) at a matching size; the second
+points at a source that doesn't exist, so you get the fallback placeholder rather
+than a crash.
+
+<InteractiveExample src={ImagesEditorSrc} component={ImagesEditor} />
+
+:::info
+
+Images can also arrive by pasting rather than through `setImage` - the editor
+surfaces those through the `onPasteImages` event, which hands you each image's URI,
+MIME type, and dimensions so you can upload or resize before inserting.
+
+:::

docs/docs/rich-text-formatting/inline-images.mdx

@@ -0,0 +1,69 @@
+---
+sidebar_position: 4
+---
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import ListsEditor from '@site/src/examples/ListsEditor';
+import ListsEditorSrc from '!!raw-loader!@site/src/examples/ListsEditor';
+
+# Lists
+
+Lists are [paragraph styles](/rich-text-formatting/basic-styles#paragraph-styles),
+just like headings and blockquotes - toggling one affects the whole paragraph the
+cursor sits in, or every paragraph the selection touches. The editor supports three
+kinds:
+
+- **Unordered list** - `toggleUnorderedList()`
+- **Ordered list** - `toggleOrderedList()`
+- **Checkbox list** - `toggleCheckboxList(checked: boolean)`
+
+Because they're paragraph styles, **only one can be active on a paragraph at a
+time**. Toggling a second list type (or any other paragraph style) replaces the
+first rather than stacking - the editor reports this through the `isConflicting`
+flag in `onChangeState`, exactly as described in
+[Basic styles](/rich-text-formatting/basic-styles#paragraph-styles).
+
+:::note
+
+The library does not support nested lists. You can only create a single level list. If you try to insert a nested list in any way, e.g. by calling `setValue` on the editor's `ref`, the list will get flattened by the [normalizer](/fundamentals/core-concepts#normalization).
+
+:::
+
+## Bulleted and numbered lists
+
+These two take no arguments - each call converts the affected paragraphs into a
+list, and calling it again turns them back into plain paragraphs:
+
+```tsx
+ref.current?.toggleUnorderedList();
+ref.current?.toggleOrderedList();
+```
+
+## Checkbox lists
+
+This list's items need a starting state. `toggleCheckboxList` takes a `checked` boolean that
+decides whether newly created boxes begin checked or unchecked:
+
+```tsx
+// New items start unchecked.
+ref.current?.toggleCheckboxList(false);
+```
+
+Once the list exists, the user can tick individual items by tapping their
+checkbox - you don't need to wire anything up for that.
+
+## Try it out
+
+Type a few lines, place the cursor on one (or select several), and toggle each
+list type. Notice how switching from **Bulleted** to **Numbered** swaps the style
+instead of stacking, inserting a new line keeps the list format by creating an another element and how tapping a checkbox in the checkbox list toggles just that item.
+
+<InteractiveExample src={ListsEditorSrc} component={ListsEditor} />
+
+:::info
+
+This page covers creating lists. To change how they look - bullet color and size,
+marker weight, checkbox size, indentation - see
+[Styling the input](/core-functionalities/styling-the-input).
+
+:::

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

@@ -0,0 +1,40 @@
+---
+sidebar_position: 6
+---
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import TextAlignmentEditor from '@site/src/examples/TextAlignmentEditor';
+import TextAlignmentEditorSrc from '!!raw-loader!@site/src/examples/TextAlignmentEditor';
+
+# Text alignment
+
+Alignment controls how a paragraph's text sits within the input's width. It's a
+per-paragraph property - every paragraph the selection touches gets aligned - and
+you set it with the `setTextAlignment` ref method:
+
+```ts
+setTextAlignment(alignment: 'left' | 'center' | 'right' | 'justify' | 'auto')
+```
+
+The five values are:
+
+- **`left`**, **`center`**, **`right`** - align the text to that direction.
+- **`justify`** - stretch each line to fill the full width.
+- **`auto`** - reset to the system's natural alignment.
+
+Unlike the paragraph styles from [Basic styles](/rich-text-formatting/basic-styles),
+text alignment does not report its state with the `isActive` / `isConflicting` booleans in `onChangeState`. Instead it exposes `alignment` with its relevant string value.
+
+```tsx
+const [state, setState] = useState<OnChangeStateEvent | null>(null);
+
+// Highlight the button that matches the paragraph at the cursor.
+const isActive = state?.alignment === 'center';
+```
+
+## Try it out
+
+Type a paragraph or two, place the cursor on one, and try each alignment. The
+active button reflects `state.alignment` for the paragraph the cursor is in.
+
+<InteractiveExample src={TextAlignmentEditorSrc} component={TextAlignmentEditor} />

docs/docs/rich-text-formatting/lists.mdx

@@ -0,0 +1,82 @@
+---
+sidebar_position: 7
+---
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import TextShortcutsEditor from '@site/src/examples/TextShortcutsEditor';
+import TextShortcutsEditorSrc from '!!raw-loader!@site/src/examples/TextShortcutsEditor';
+
+# Text shortcuts
+
+Text shortcuts let users format as they type, the way Markdown editors do -
+typing `#` turns a line into a heading, wrapping a word in `**` makes it bold.
+You configure them with the `textShortcuts` prop, an array that maps a `trigger`
+string to a `style`:
+
+```tsx
+<EnrichedTextInput
+  textShortcuts={[
+    { trigger: '# ', style: 'h1' },
+    { trigger: '**', style: 'bold' },
+  ]}
+  /* ... */
+/>;
+```
+
+The `style` values are the same rich text styles you met in
+[Basic styles](/rich-text-formatting/basic-styles) - and the inline vs. paragraph
+distinction is exactly what decides how a shortcut fires.
+
+## Paragraph vs. inline shortcuts
+
+The two families of styles trigger differently, because they format different
+things:
+
+- **Paragraph shortcuts** (`h1`–`h6`, `blockquote`, `codeblock`,
+  `unordered_list`, `ordered_list`, `checkbox_list`) fire at the **start of a
+  paragraph**. The trigger is the prefix you type before the line's content -
+  e.g. `#` for a heading, `-` for a bulleted list. Since a paragraph can only hold
+  one paragraph style, these only fire on a **plain** paragraph: if the line is
+  already a heading or a list item, typing the prefix does nothing.
+
+- **Inline shortcuts** (`bold`, `italic`, `underline`, `strikethrough`,
+  `inline_code`) fire when you type a **closing delimiter** around some text, so
+  typing `**word**` bolds `word`.
+
+:::note
+
+The usual [style rules](/rich-text-formatting/basic-styles#paragraph-styles) still
+apply to shortcut-triggered styles. If the target style is **blocked** by an
+active one (e.g. bold inside a code block).
+
+:::
+
+## Defaults
+
+Even without the prop, two shortcuts are active out of the box:
+
+```ts
+[
+  { trigger: '- ', style: 'unordered_list' },
+  { trigger: '1. ', style: 'ordered_list' },
+];
+```
+
+Passing your own array replaces these defaults entirely, and passing an empty
+array (`textShortcuts={[]}`) disables shortcuts altogether.
+
+## Try it out
+
+The editor below wires up one shortcut of each kind - a paragraph one (`#` → H1)
+and an inline one (`**` → bold). Start a line with `#` and watch it become a
+heading, then wrap a word in `**stars**` to bold it.
+
+<InteractiveExample src={TextShortcutsEditorSrc} component={TextShortcutsEditor} />
+
+:::info
+
+On Web, the same styles are also reachable through
+[keyboard shortcuts](/api-reference/enriched-text-input) like ⌘B / Ctrl+B,
+independent of the `textShortcuts` prop.
+
+:::

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

@@ -0,0 +1,67 @@
+import { EnrichedTextInput } from 'react-native-enriched-html';
+import type { EnrichedTextInputInstance } from 'react-native-enriched-html';
+import { useRef } from 'react';
+import { View, StyleSheet, Pressable, Text } from 'react-native';
+
+export default function App() {
+  const ref = useRef<EnrichedTextInputInstance>(null);
+
+  const insertImage = () => {
+    // A real, loadable image. You supply the dimensions yourself - here we
+    // ask Lorem Picsum for a 320x160 photo and pass the proportionally down-scaled size.
+    ref.current?.setImage('https://picsum.photos/320/160', 160, 80);
+  };
+
+  const insertBrokenImage = () => {
+    // An unreachable source. The editor renders its static placeholder
+    // instead of failing, so you can see what a broken image looks like.
+    ref.current?.setImage('https://picsum.photos/does-not-exist', 160, 80);
+  };
+
+  return (
+    <View style={styles.container}>
+      <EnrichedTextInput
+        ref={ref}
+        style={styles.input}
+        placeholder="Place the cursor, then insert an image below..."
+      />
+      <View style={styles.row}>
+        <Pressable style={styles.button} onPress={insertImage}>
+          <Text style={styles.text}>Insert image</Text>
+        </Pressable>
+        <Pressable style={styles.button} onPress={insertBrokenImage}>
+          <Text style={styles.text}>Insert broken image</Text>
+        </Pressable>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { gap: 12 },
+  input: {
+    fontSize: 18,
+    color: '#232736',
+    padding: 12,
+    borderRadius: 12,
+    minHeight: 96,
+    backgroundColor: '#eef0ff',
+  },
+  row: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    justifyContent: 'center',
+    gap: 8,
+  },
+  button: {
+    padding: 8,
+    paddingHorizontal: 16,
+    borderRadius: 24,
+    borderWidth: 1,
+    borderColor: '#919fcf',
+  },
+  text: {
+    textAlign: 'center',
+    color: '#919fcf',
+  },
+});