## Install

```bash
npm install wordhug
```

Each framework is an optional peer dependency; install only the one you use.

| Framework | Import from      | Peer dependency               | Text goes in   |
| --------- | ---------------- | ----------------------------- | -------------- |
| React     | `wordhug/react`  | `react` 18+                   | `children`     |
| Vue       | `wordhug/vue`    | `vue` 3.3+                    | default slot   |
| Solid     | `wordhug/solid`  | `solid-js` and `@solidjs/web` 2+ | `children`  |
| Svelte    | `wordhug/svelte` | `svelte` 5+                   | `text` prop    |
| Astro     | `wordhug/astro`  | –                             | `text` prop    |
| None      | `wordhug`        | –                             | `wordhugHtml` |
| Markdown  | `wordhug/rehype` | –                             | markdown text |

### Upgrading from 0.1

The React component moved to its own subpath. Change the import:

```diff
- import { WordHug } from "wordhug";
+ import { WordHug } from "wordhug/react";
```

`parseBrackets` is still imported from `wordhug`.

## Usage

### React

```tsx
import { WordHug } from "wordhug/react";

export function Hero() {
  return (
    <h1>
      <WordHug>{"Fresh bread [delivered daily] to [your door]"}</WordHug>
    </h1>
  );
}
```

`WordHug` has no hooks and no `"use client"` directive, so it renders in React Server Components as well as on the client.

| Prop        | Type                          | Default                       | Description                          |
| ----------- | ----------------------------- | ----------------------------- | ------------------------------------ |
| `children`  | `React.ReactNode`             | –                             | Text and elements to render (see below). Empty input renders nothing. |
| `as`        | `React.ElementType`           | `"span"`                      | Element that wraps each group.       |
| `className` | `string`                      | –                             | Class name on each group wrapper.    |
| `style`     | `CSSProperties \| null`       | `{ display: "inline-block" }` | Inline style on each group wrapper. Pass `null` to style groups only through `className`. |

Strings and numbers in the children are joined into one text, including inside arrays and fragments, so JSX expressions work inside brackets. Elements stay where they are, and a group can contain them: each element is one unit that is never split. Brackets inside an element are not read, so a group can't start in one element and end in another.

```tsx
<WordHug>Hello [{user.name}], you have [{count} new messages]</WordHug>
<WordHug>Fresh bread for [only <strong>$3</strong> a loaf]</WordHug>
```

#### `wordhug()`

The same thing as a function that returns a React node, for places where a component is awkward, such as props that take a node or text built in a loop. It takes the same input as `children` and the same options as the props.

```tsx
import { wordhug } from "wordhug/react";

<Button label={wordhug("Save [all changes]")} />;
wordhug("Pay [only $9.99]", { className: "nowrap", style: null });
```

### Vue

```vue
<script setup>
import { WordHug } from "wordhug/vue";
</script>

<template>
  <h1><WordHug class="nowrap">Fresh bread [delivered daily] to [your door]</WordHug></h1>
</template>
```

The text comes from the default slot: plain text and `{{ }}` interpolations are joined into one text, and elements and components stay where they are, each as one unit a group can contain. Brackets inside an element are not read. `class` and `style` go on each group wrapper, not on a root element. `style` defaults to `display: inline-block`; `:style="null"` removes it. `as` takes a tag name or a component and defaults to `"span"`.

`wordhug(text, options)` returns the same output as a VNode, for render functions, Vue JSX or anything that expects a VNode. Options are `as`, `class` and `style`, as for the component:

```ts
import { h } from "vue";
import { wordhug } from "wordhug/vue";

h("h1", [wordhug("Fresh bread [delivered daily]", { class: "nowrap" })]);
```

### Solid

```tsx
import { WordHug } from "wordhug/solid";

<h1>
  <WordHug class="nowrap">{"Fresh bread [delivered daily] to [your door]"}</WordHug>
</h1>;
```

Props: `children` (string), `as` (tag or component, default `"span"`), `class`, and `style` (object or string, default `{ display: "inline-block" }`, `null` removes it). Re-renders when any prop changes. Requires Solid 2.

`wordhug(text, options)` returns the same output as a `JSX.Element`, for props that take an element or text built in a loop. It reads its arguments once, so call it inside JSX (`{wordhug(title())}`) or a memo to keep it reactive:

```tsx
import { wordhug } from "wordhug/solid";

<Button label={wordhug("Save [all changes]", { class: "nowrap" })} />;
```

### Svelte

```svelte
<script>
  import { WordHug } from "wordhug/svelte";
</script>

<h1><WordHug text="Fresh bread [delivered daily] to [your door]" /></h1>
```

Props: `text` (string), `as` (tag name, default `"span"`), `class`, and `style` (string, default `"display: inline-block"`, `null` removes it). Requires Svelte 5; the component ships as source and is compiled by your build.

### Astro

```astro
---
import WordHug from "wordhug/astro";
---

<h1><WordHug text="Fresh bread [delivered daily] to [your door]" /></h1>
```

Same props as Svelte: `text`, `as`, `class`, `style`. Renders static HTML with no client JavaScript.

### Plain HTML: `wordhugHtml`

```ts
import { wordhugHtml } from "wordhug";

wordhugHtml("Fish & [chips]", { class: "nowrap" });
// → 'Fish &amp; <span class="nowrap" style="display: inline-block">chips</span>'
```

Options are `as` (tag name), `class` and `style`, as for Svelte. Text and attributes are HTML-escaped, so the result is safe to insert with `innerHTML`.

This was called `renderToHtml` before 0.3. The old name still works but is deprecated and will be removed in a future release.

### Markdown: `wordhug/rehype`

A [rehype](https://github.com/rehypejs/rehype) plugin, for markdown and anything else that goes through unified, such as Astro's markdown, MDX and many CMS pipelines. Writers put brackets in their markdown and groups come out in the HTML.

```ts
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import rehypeWordhug from "wordhug/rehype";

const html = String(
  await unified()
    .use(remarkParse)
    .use(remarkRehype)
    .use(rehypeWordhug, { class: "nowrap" })
    .use(rehypeStringify)
    .process("Fresh bread [delivered daily] to [your door]"),
);
```

In Astro, add it to `markdown.rehypePlugins` in `astro.config.mjs`:

```js
import rehypeWordhug from "wordhug/rehype";

export default { markdown: { rehypePlugins: [rehypeWordhug] } };
```

Options are `as` (tag name), `class` and `style`, as for `wordhugHtml`.

The plugin runs after markdown is parsed, so links (`[text](url)`), references with a definition, footnotes and task list boxes are already handled; only brackets left in the text become groups. A group can contain inline formatting such as `**bold**` or `*italic*`, but can't start in one element and end in another. Code spans, code blocks and `<pre>`, `<script>` and `<style>` are left alone, and text without groups is left exactly as it was.

Markdown removes a backslash before a bracket, so for a literal bracket write two backslashes: `\\[sic\\]` renders `[sic]`.

### Styling

Groups work without any stylesheet: each wrapper gets `display: inline-block` inline. To use a class instead (for example Tailwind's `inline-block` or `whitespace-nowrap`), pass a class and a `null` style.

An inline-block group moves to the next line as a whole. If a group is wider than its container, it still wraps inside its own box rather than overflowing. Use `white-space: nowrap` if you would rather it never break and overflow instead. Note that a parent's `text-decoration` (such as a link underline) does not carry into inline-block groups.

### Parsing rules

- `[...]` marks a group. Groups can nest: `[a [b c] d]`.
- A bracket without a partner is kept as literal text: `a ] b` and `a [ b` render unchanged.
- Runs of whitespace collapse to a single space, and whitespace at the start and end of the text and of each group is removed.
- Text touching a bracket stays attached: `(see [page 3])` renders `(see <span>page 3</span>)`.
- Empty groups (`[]`) are dropped.
- To show a literal bracket, put a backslash before it: `\[sic\]` renders `[sic]` and never forms a group. A backslash before any other character is kept as is.

In JSX text, Vue and Svelte templates and Astro attributes a backslash is literal, so `<WordHug>Quote \[sic\]</WordHug>` and `text="Quote \[sic\]"` work as written. Inside a JavaScript string the backslash itself needs escaping: `{"Quote \\[sic\\]"}`.

### `parseBrackets`

The parser is exported from the package root, which imports no framework, so you can render the tree any way you like.

```ts
import { parseBrackets } from "wordhug";

parseBrackets("Hello [big world] today");
// [
//   { type: "text", value: "Hello " },
//   { type: "group", children: [{ type: "text", value: "big world" }] },
//   { type: "text", value: " today" },
// ]
```

Types `Node`, `TextNode`, `GroupNode` and `WordhugHtmlOptions` are exported from `wordhug`, and `RehypeWordhugOptions` from `wordhug/rehype`; `WordHugProps` is exported from `wordhug/react`, `wordhug/solid` and `wordhug/svelte`, and `WordHugOptions` from `wordhug/react`, `wordhug/vue` and `wordhug/solid`.
