_hublib-web/packages/content-suggestions/README.md

# @hublib-web/content-suggestions

Cross-framework content text/title renderer with support for mentions, tags and links.

## Features

- Shared parser in `core` (`findAllEntities`, `findMentions`, `findTags`, `findLinks`).
- React UI components in `react`:
  - `ContentText`
  - `ContentTextWithSuggestions`
  - `ContentTitleWithSuggestions`
- Angular UI components in `angular` (based on `@hublib-web/tach-typography/angular`):
  - `ContentTextComponent`
  - `ContentTextWithSuggestionsComponent`
  - `ContentTitleWithSuggestionsComponent`
- Depends on `@hublib-web/tach-typography` for visual consistency.
- Business logic (API requests for mentions/tags) stays in consumer application.

## Install from Git (SSH tag)

```bash
yarn add "@hublib-web/content-suggestions@git+ssh://git@github.com/ORG/REPO.git#workspace=@hublib-web/content-suggestions&tag=content-suggestions-v0.1.0"
```

`@hublib-web/tach-typography@0.3.0` is a peer dependency.

## Install inside this monorepo

```bash
yarn add @hublib-web/content-suggestions
```

## Release this package

1. Bump `version` in `packages/content-suggestions/package.json`.
2. Build package artifacts:

```bash
yarn workspace @hublib-web/content-suggestions build
```

3. Commit release files:

```bash
git add packages/content-suggestions/package.json packages/content-suggestions/dist
git commit -m "release(content-suggestions): v0.1.0"
```

4. Create and push tag:

```bash
git tag -a content-suggestions-v0.1.0 -m "@hublib-web/content-suggestions v0.1.0"
git push origin main --follow-tags
```

Detailed docs:

- [Release policy](../../docs/release-policy.md)
- [Git installation](../../docs/git-installation.md)

## React usage

```tsx
import { ContentTextWithSuggestions } from "@hublib-web/content-suggestions/react";

<ContentTextWithSuggestions text={text} />;
```

With app-specific mention business logic:

```tsx
<ContentTextWithSuggestions
  text={text}
  renderMention={(entity) => <MyMention entity={entity} />}
  renderTag={(entity) => <MyTagLink entity={entity} />}
/>;
```

By default, tags are rendered as plain styled text (not links).

## Angular usage

Standalone component usage:

```ts
import { Component } from "@angular/core";
import { ContentTextWithSuggestionsComponent } from "@hublib-web/content-suggestions/angular";

@Component({
  standalone: true,
  imports: [ContentTextWithSuggestionsComponent],
  template: `
    <content-text-with-suggestions
      [text]="text"
      [ellipsis]="{ count: 180, expandable: true }"
      [onView]="onView"
    />
  `,
})
export class FeedPostComponent {
  text = "@[John Doe](d290f1ee-6c54-4b01-90e6-d701748f0851) hello #tag";

  onView = () => {
    // analytics
  };
}
```

Title variant with defaults (`weight: "bold"`, `ellipsis: { rows: 2 }`):

```ts
import { ContentTitleWithSuggestionsComponent } from "@hublib-web/content-suggestions/angular";

// template
// <content-title-with-suggestions [text]="title" />
```

Tokenization helper:

```ts
import { createAngularContentTokens } from "@hublib-web/content-suggestions/angular";

const tokens = createAngularContentTokens(text);
```

## Storybook (dev/design system)

Run from repository root:

```bash
yarn workspace @hublib-web/content-suggestions storybook
```

Build static Storybook:

```bash
yarn workspace @hublib-web/content-suggestions storybook:build
```