Prose

import { Prose } from '@snapshot-ui/react';
import type { ReactElement } from 'react';
import { REPORT } from './prose-fixtures';
import { OwnMarkdown } from './prose-markdown';

/** A server component: a report you write, rendered from Markdown into Prose, with no client JavaScript. */
export default function ProseReport(): ReactElement {
  return (
    <Prose as="article" style={{ width: '100%' }}>
      <OwnMarkdown>{REPORT}</OwnMarkdown>
    </Prose>
  );
}

import { Prose, ProseScroll } from '@snapshot-ui/react';
import type { ReactElement } from 'react';
import Markdown, { type Components, type Options } from 'react-markdown';
import remarkGfm from 'remark-gfm';

/** The words the map names a table and a code block with, and an image's alt text with, in the page's language. */
export interface MarkdownLabels {
  /** Starts a table's name, before its column headers: "Table". */
  table: string;
  /** A code block's name, before its language when it has one: "Code". */
  code: string;
  /** Read before an image's alt text, and not shown: "Image:". */
  image: string;
}

const ENGLISH: MarkdownLabels = { table: 'Table', code: 'Code', image: 'Image:' };

/** The part of the HTML tree react-markdown hands a component as `node`, as far as the map reads it. */
interface Node {
  type: string;
  tagName?: string;
  value?: string;
  properties?: { className?: unknown };
  children?: Node[];
}

/** The text a node holds. */
const textOf = (node: Node): string =>
  node.type === 'text' ? (node.value ?? '') : (node.children ?? []).map(textOf).join('');

/** The elements among a node's children with this tag. */
const childrenNamed = (node: Node | undefined, tag: string): Node[] =>
  (node?.children ?? []).filter((child) => child.tagName === tag);

/** A table's name from its column headers, so a page with several regions tells them apart. */
function tableName(node: Node | undefined, labels: MarkdownLabels): string {
  const [head] = childrenNamed(node, 'thead');
  const [row] = childrenNamed(head, 'tr');
  const headers = childrenNamed(row, 'th').map((cell) => textOf(cell).trim());
  return headers.length > 0 ? `${labels.table}: ${headers.join(', ')}` : labels.table;
}

/** A code block's name: its language when the fence gives one, and its first line. */
function codeName(node: Node | undefined, labels: MarkdownLabels): string {
  const [code] = childrenNamed(node, 'code');
  const classes = code?.properties?.className;
  const language = Array.isArray(classes)
    ? classes.find((name): name is string => typeof name === 'string' && name.startsWith('language-'))
    : undefined;
  // Its first line tells two blocks apart, as a table's headers do.
  const first = (code ? textOf(code) : '').trim().split('\n')[0] ?? '';
  const line = first.length > 40 ? `${first.slice(0, 40)}...` : first;
  const kind = language ? `${labels.code}, ${language.slice('language-'.length)}` : labels.code;
  return line ? `${kind}: ${line}` : kind;
}

/** The parts both maps share: a table scrolls in a region named by its headers, a code block in one of its own. */
const scrolling = (labels: MarkdownLabels): Components => ({
  table: ({ node, children }) => (
    <ProseScroll aria-label={tableName(node, labels)}>
      <table>{children}</table>
    </ProseScroll>
  ),
  pre: ({ node, children }) => (
    // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex -- a code block that scrolls must take focus to scroll by keyboard
    <pre role="region" aria-label={codeName(node, labels)} tabIndex={0}>
      {children}
    </pre>
  ),
});

/**
 * The map for Markdown a model writes. A link becomes its text and an image its alt text, so the reader is never
 * sent to an address or shown a picture from one; a link within the page, such as a footnote's, stays a link.
 */
export const modelOutput = (labels: MarkdownLabels = ENGLISH): Components => ({
  ...scrolling(labels),
  a: ({ children, ...link }) => {
    // react-markdown's tree node is not an attribute of the link.
    delete link.node;
    return link.href?.startsWith('#') ? (
      <a {...link}>{children}</a>
    ) : (
      <span className="prose-unlinked">{children}</span>
    );
  },
  img: ({ alt }) =>
    alt ? (
      <span className="prose-image">
        <span className="visually-hidden">{labels.image} </span>
        {alt}
      </span>
    ) : null,
});

/** The map for your own content, such as a help article: its links stay links. */
export const ownContent = (labels: MarkdownLabels = ENGLISH): Components => scrolling(labels);

interface MarkdownProps {
  children: string;
  labels?: MarkdownLabels;
  /** Passed to remark-rehype, such as the footnotes' label in the page's language. */
  remarkRehypeOptions?: Options['remarkRehypeOptions'];
}

/** Model output, rendered on the server: GitHub's tables and footnotes, and no HTML at all. */
export function ModelMarkdown({ children, labels, remarkRehypeOptions }: MarkdownProps): ReactElement {
  return (
    <Markdown
      remarkPlugins={[remarkGfm]}
      remarkRehypeOptions={remarkRehypeOptions}
      skipHtml
      components={modelOutput(labels)}
    >
      {children}
    </Markdown>
  );
}

/** Your own Markdown, rendered on the server, with its links. */
export function OwnMarkdown({ children, labels, remarkRehypeOptions }: MarkdownProps): ReactElement {
  return (
    <Markdown
      remarkPlugins={[remarkGfm]}
      remarkRehypeOptions={remarkRehypeOptions}
      components={ownContent(labels)}
    >
      {children}
    </Markdown>
  );
}

const SNIPPET = `Read [the full report](https://example.com/report) at https://example.com/reports/2026/october?view=all.

![Spending by category in October](https://example.com/october.png) <script>track()</script>`;

/** A server component: what a model wrote, with its link, its address and its image turned into text. */
export default function ProseMarkdown(): ReactElement {
  return (
    <Prose style={{ width: '100%' }}>
      <ModelMarkdown>{SNIPPET}</ModelMarkdown>
    </Prose>
  );
}

import { Prose } from '@snapshot-ui/react';
import type { ReactElement } from 'react';
import { MODEL_OUTPUT } from './prose-fixtures';
import { ModelMarkdown } from './prose-markdown';

/**
 * A server component: a report a model wrote, rendered with skipHtml and the model output map. The link reads as
 * the text around it, the bare address breaks anywhere, the image shows its alt text in a small box, the one
 * with no alt text is not drawn, and the HTML never reaches the page.
 */
export default function ProseModelOutput(): ReactElement {
  return (
    <Prose as="article" style={{ width: '100%' }}>
      <ModelMarkdown>{MODEL_OUTPUT}</ModelMarkdown>
    </Prose>
  );
}

'use client';

import { CopyButton, Prose } from '@snapshot-ui/react';
import type { ReactElement } from 'react';

const ANSWER =
  'Spending on food is down 12% this month, mostly from fewer restaurant visits. Groceries held steady at $410.';

export default function CopyButtonAnswer(): ReactElement {
  // While an answer streams in, the app marks its body aria-busy="true" and sets it false once it has finished.
  const isStreaming = false;
  return (
    <article aria-label="Answer" className="stack" style={{ width: '100%', maxWidth: '36rem' }}>
      <Prose aria-busy={isStreaming}>
        <p>{ANSWER}</p>
      </Prose>
      {/* The footer is never busy, so the copy button's status in it is always heard. */}
      <footer className="row">
        <CopyButton value={ANSWER} labels={{ copy: 'Copy answer' }} />
      </footer>
    </article>
  );
}

import { Prose, ProseScroll } from '@snapshot-ui/react';
import type { ReactElement } from 'react';

const ROWS = [
  ['Rent', '$1,450.00', '$1,450.00', '$0.00', '44%', '$1,450.00'],
  ['Groceries', '$588.15', '$612.40', '+$24.25', '19%', '$650.00'],
  ['Eating out', '$431.00', '$286.90', '-$144.10', '9%', '$300.00'],
  ['Transport', '$214.60', '$198.30', '-$16.30', '6%', '$250.00'],
  ['Utilities', '$176.20', '$181.75', '+$5.55', '6%', '$200.00'],
];

/** Six columns of figures in a ProseScroll: on a phone the table scrolls inside its named region, not the page. */
export default function ProseWideTable(): ReactElement {
  return (
    <Prose style={{ width: '100%' }}>
      <p>
        Each category against September and its budget, with <mark>eating out</mark> down the most.
      </p>
      <ProseScroll aria-label="October by category, table">
        <table>
          <thead>
            <tr>
              <th scope="col">Category</th>
              {['September', 'October', 'Change', 'Share', 'Budget'].map((name) => (
                <th key={name} scope="col" style={{ textAlign: 'end' }}>
                  {name}
                </th>
              ))}
            </tr>
          </thead>
          <tbody>
            {ROWS.map(([category = '', ...figures]) => (
              <tr key={category}>
                <th scope="row">{category}</th>
                {figures.map((figure, index) => (
                  <td key={index} style={{ textAlign: 'end' }}>
                    {figure}
                  </td>
                ))}
              </tr>
            ))}
          </tbody>
        </table>
      </ProseScroll>
    </Prose>
  );
}

import { BarChart, type BarValue } from '@snapshot-ui/charts';
import { Badge, Prose } from '@snapshot-ui/react';
import type { ReactElement } from 'react';

/** An amount as the app formats it: the number to draw and the string to say it. */
const money = (value: number): BarValue => ({ value, valueLabel: `$${value.toFixed(2)}` });

/**
 * A chart and a badge inside an article, with no not-prose: prose leaves every library component as it is
 * anywhere, its figure, its rows and its table included, and spaces the chart as a block of the article.
 */
export default function ProseWithChart(): ReactElement {
  return (
    <Prose as="article" style={{ width: '100%' }}>
      <h2>
        Where October went <Badge tone="info">New</Badge>
      </h2>
      <p>Rent was most of the month, as it is every month, and eating out fell by a third.</p>
      <BarChart
        aria-label="Spending by category, October"
        orientation="horizontal"
        categories={['Rent', 'Groceries', 'Eating out', 'Transport', 'Utilities']}
        series={[{ label: 'October', values: [1450, 612.4, 286.9, 198.3, 181.75].map(money) }]}
      />
      <p>Refunds are counted in the month they arrive.</p>
    </Prose>
  );
}

import { Card, Prose } from '@snapshot-ui/react';
import type { ReactElement } from 'react';
import { COACHING_NOTE } from './prose-fixtures';
import { ModelMarkdown } from './prose-markdown';

/**
 * A weekly note in a Card: the card's padding is the article's inset, an h2 starts it, and the code block at its
 * foot takes the card's concentric corner.
 */
export default function ProseCard(): ReactElement {
  return (
    <Card style={{ maxWidth: 560, marginInline: 'auto', width: '100%' }}>
      <Prose>
        <ModelMarkdown>{COACHING_NOTE}</ModelMarkdown>
      </Prose>
    </Card>
  );
}

import { Prose } from '@snapshot-ui/react';
import type { ReactElement } from 'react';
import { GOALS_GUIDE_FA } from './prose-fixtures';
import { OwnMarkdown, type MarkdownLabels } from './prose-markdown';

/** The map's names in Persian, and the footnotes' label and back link, which GFM writes in English otherwise. */
const PERSIAN: MarkdownLabels = { table: 'جدول', code: 'کد', image: 'تصویر:' };
const FOOTNOTES = { footnoteLabel: 'پانویس‌ها', footnoteBackLabel: 'بازگشت به متن' };

/**
 * The goals guide in Persian, in Vazirmatn: markers and the quote's rule on the right, Persian digits, emphasis
 * by weight, and code and figures left to right.
 */
export default function ProsePersian(): ReactElement {
  return (
    <div lang="fa" dir="rtl" style={{ width: '100%' }}>
      <Prose as="article">
        <OwnMarkdown labels={PERSIAN} remarkRehypeOptions={FOOTNOTES}>
          {GOALS_GUIDE_FA}
        </OwnMarkdown>
      </Prose>
    </div>
  );
}