@sakura-ui/sakura-ui 0.5.0 → 0.5.2

package/packages/markdown/src/components/Markdown.tsx

@@ -1,63 +1,13 @@
-import React, { Children } from 'react'
-import * as production from 'react/jsx-runtime'
-import { remark } from 'remark'
-import { unified } from 'unified'
-import remarkParse from 'remark-parse'
-import remarkGfm from 'remark-gfm'
-import remarkDirective from 'remark-directive'
-import remarkRehype from 'remark-rehype'
-import remarkBreaks from 'remark-breaks'
-import rehypeRaw from 'rehype-raw'
-import rehypeExternalLinks from 'rehype-external-links'
-import rebypeShiftHeding from 'rehype-shift-heading'
-import rehypeReact from 'rehype-react'
-import rehypeSlug from 'rehype-slug'
-import { cx } from '@sakura-ui/helper'
-import {
-  Link,
-  H1,
-  H2,
-  H3,
-  H4,
-  H5,
-  H6,
-  Table,
-  Caption,
-  Thead,
-  Tbody,
-  Th,
-  Tr,
-  Td,
-  Ul,
-  Ol,
-  Pre,
-  Code,
-  Faq,
-  Question,
-  Answer,
-  Button,
-  Card,
-  CardImg,
-  CardHeader,
-  CardBody,
-  CardFooter,
-  LinkCard,
-  LinkCardHeader,
-  LinkCardFooter,
-  type CardHeaderAs,
-  OverflowContainer
-} from '@sakura-ui/core'
-import {
-  attrPlugin,
-  youtubePlugin,
-  linkButtonPlugin,
-  gridPlugin,
-  cellPlugin,
-  cardPlugin,
-  faqPlugin,
-  headingsPlugin,
-  type HeadingItem
-} from '../plugins'
+import { H2, Link, Ul } from '@sakura-ui/core'
+import React from 'react'
+import { type HeadingItem, render, type RenderResult } from '../render'
+
+/**
+ * What the server, and the first render in the browser, have to show. The
+ * pipeline sanitises and styles through the DOM, so it cannot run where there
+ * is no document.
+ */
+const NOTHING_YET: RenderResult = { html: '', headings: [] }
 
 interface TocProps {
   items: HeadingItem[]
@@ -80,310 +30,58 @@ export const TableOfContents = ({ items }: TocProps) => {
   )
 }
 
-interface TableContainerProps extends React.ComponentPropsWithoutRef<'table'> {}
-
-const TableContainer = (props: TableContainerProps) => {
-  const { className, children, ...restProps } = props
-
-  return (
-    <OverflowContainer>
-      <Table className={cx(className)} {...restProps}>
-        {children}
-      </Table>
-    </OverflowContainer>
-  )
-}
-
-interface DataProps {
-  [key: `data-${string}`]: unknown
-}
-
-interface AnchorProps extends React.ComponentPropsWithoutRef<'a'>, DataProps {}
-
-const Anchor = (props: AnchorProps) => {
-  const { children, href, ...restProps } = props
-
-  if (restProps['data-node'] === 'link-button') {
-    return (
-      <Button as="a" variant="secondary" href={href}>
-        {children}
-      </Button>
-    )
+export namespace Markdown {
+  export interface Props {
+    tocTitle?: string
+    showToc?: boolean
+    /** Moves every heading down by this many levels. */
+    shiftHeading?: number
+    /** How deep the table of contents goes. Defaults to 2. */
+    tocMaxDepth?: number
+    children: string
   }
-
-  return (
-    <Link href={href} {...restProps}>
-      {children}
-    </Link>
-  )
-}
-
-interface ArticleProps
-  extends React.ComponentPropsWithoutRef<'article'>,
-    DataProps {}
-
-const Article = (props: ArticleProps) => {
-  const { children, className, ...restProps } = props
-
-  const node = restProps['data-node']
-
-  if (node === 'card') {
-    // The href now lives on the title, which is what carries the link.
-    if (restProps['data-behavior'] === 'link') {
-      return <LinkCard className={cx(className)}>{children}</LinkCard>
-    }
-    return <Card className={cx(className)}>{children}</Card>
-  }
-
-  return (
-    <article className={className} {...restProps}>
-      {children}
-    </article>
-  )
-}
-
-interface DivProps extends React.ComponentPropsWithoutRef<'div'>, DataProps {
-  headingLevel?: CardHeaderAs
-}
-
-const Div = (props: DivProps) => {
-  const { children, headingLevel = 'h3', ...restProps } = props
-
-  const node = restProps['data-node']
-  const isLink = restProps['data-behavior'] === 'link'
-
-  if (node === 'card-title') {
-    if (isLink) {
-      return (
-        <LinkCardHeader
-          as={headingLevel}
-          href={restProps['data-href'] as string}
-        >
-          {children}
-        </LinkCardHeader>
-      )
-    }
-    return <CardHeader as={headingLevel}>{children}</CardHeader>
-  }
-  if (node === 'card-description') {
-    return <CardBody>{children}</CardBody>
-  }
-  if (node === 'card-footer') {
-    if (isLink) {
-      return <LinkCardFooter>{children}</LinkCardFooter>
-    }
-    return <CardFooter>{children}</CardFooter>
-  }
-
-  if (restProps['data-behavior'] === 'list') {
-    // Set the css class configured for cells to the ul tag
-    return (
-      <ul className={restProps.className}>
-        {Children.map(children, (child) => (
-          <li className="sm:grid" key={Math.random()}>
-            {child}
-          </li>
-        ))}
-      </ul>
-    )
-  }
-
-  return <div {...restProps}>{children}</div>
-}
-
-interface ImgProps extends React.ComponentPropsWithoutRef<'img'>, DataProps {}
-
-const Img = (props: ImgProps) => {
-  const { children, className, ...restProps } = props
-
-  if (restProps['data-node'] === 'card-img') {
-    return (
-      <CardImg
-        className={cx('w-full aspect-[352/226]', className)}
-        {...restProps}
-      />
-    )
-  }
-
-  if (restProps['data-node'] === 'cell-img') {
-    // biome-ignore lint/a11y/useAltText: alt is carried by restProps from the markdown image syntax
-    return <img className={cx('mb-4', className)} {...restProps} />
-  }
-
-  // biome-ignore lint/a11y/useAltText: alt is carried by restProps from the markdown image syntax
-  return <img className={className} {...restProps} />
-}
-
-interface IframeProps extends React.ComponentPropsWithoutRef<'iframe'> {}
-
-const Iframe = (props: IframeProps) => {
-  const { className, children, ...restProps } = props
-
-  const styleMargin = `
-    my-8
-  `
-
-  let style = `
-    aspect-video
-    w-full
-    max-w-[470px]
-  `
-
-  if (props.width || props.height) {
-    style = `
-      aspect-video
-      w-full
-      lg:aspect-auto
-      lg:w-[${props.width}px]
-      lg:h-[${props.height}px]
-    `
-  }
-
-  return (
-    <iframe className={cx(styleMargin, style, className)} {...restProps}>
-      {children}
-    </iframe>
-  )
-}
-
-const sleep = (time: number) =>
-  new Promise((resolve) => setTimeout(resolve, time))
-
-type Props = {
-  tocTitle?: string
-  showToc?: boolean
-  shiftHeding?: number
-  children: string
 }
 
 export const Markdown = ({
   children,
   showToc,
   tocTitle = '目次',
-  shiftHeding = 0
-}: Props) => {
-  const [toc, setToc] = React.useState<HeadingItem[]>([])
-  const [element, setElement] = React.useState(<React.Fragment />)
-
-  const markdown2Headings = React.useCallback((md: string) => {
-    // biome-ignore lint/suspicious/noExplicitAny: remark does not type the data that plugins attach to the VFile
-    const result: any = remark().use(headingsPlugin).processSync(md)
-
-    const headings: HeadingItem[] = result.data.fm.headings.filter(
-      (obj: HeadingItem) => obj.depth < 3
-    )
-
-    return headings
-  }, [])
-
-  const markdown2ReactElements = React.useCallback(
-    (md: string) => {
-      // Card titles sit in the body of the document, so h3 is the natural base.
-      // rehype-shift-heading cannot reach them because they are still divs when
-      // it runs, so the same shift is applied here.
-      const cardHeadingLevel = `h${Math.min(
-        6,
-        Math.max(1, 3 + shiftHeding)
-      )}` as CardHeaderAs
-
-      const rhypeReactOptions = {
-        ...production,
-        components: {
-          a: Anchor,
-          article: Article,
-          button: Button,
-          code: Code,
-          dl: Faq,
-          dt: Question,
-          dd: Answer,
-          h1: H1,
-          h2: H2,
-          h3: H3,
-          h4: H4,
-          h5: H5,
-          h6: H6,
-          iframe: Iframe,
-          img: Img,
-          ul: Ul,
-          ol: Ol,
-          pre: Pre,
-          table: TableContainer,
-          caption: Caption,
-          thead: Thead,
-          tbody: Tbody,
-          th: Th,
-          tr: Tr,
-          td: Td,
-          div: (props: DivProps) => (
-            <Div {...props} headingLevel={cardHeadingLevel} />
-          )
-        }
-      }
-
-      const elem = unified()
-        .use(remarkParse) // md    -> mdast     (Markdown Abstract Syntax Tree)
-        .use(remarkGfm) // mdast -> GFM mdast (GitHub Flavored Markdown Abstract Syntax Tree)
-        .use(remarkDirective) // support for directive syntax
-        .use(remarkBreaks)
-        .use(attrPlugin)
-        .use(youtubePlugin)
-        .use(linkButtonPlugin)
-        .use(cellPlugin)
-        .use(cardPlugin)
-        .use(faqPlugin)
-        .use(gridPlugin)
-        .use(remarkRehype, {
-          allowDangerousHtml: true
-        }) // mdast -> hast      (HTML Abstract Syntax Tree)
-        .use(rehypeRaw) // hast  -> hast
-        .use(rehypeExternalLinks, { target: '_blank' }) // hast  -> hast
-        .use(rebypeShiftHeding, { shift: shiftHeding }) // hast  -> hast
-        .use(rehypeSlug)
-        // biome-ignore lint/suspicious/noExplicitAny: rehype-react's declared option type rejects the component map it accepts at runtime
-        .use(rehypeReact, rhypeReactOptions as any) // hast  -> React Elements
-        .processSync(md).result
-      return elem
-    },
-    [shiftHeding]
-  )
+  shiftHeading = 0,
+  tocMaxDepth = 2
+}: Markdown.Props) => {
+  // Converted in an effect, not while rendering. useMemo runs on the server as
+  // well, and the pipeline reaches for document, so rendering there threw
+  // instead of producing the empty output the caller could recover from. This
+  // way the server and the first render in the browser agree, and the markup
+  // arrives once the effect has run.
+  const [{ html, headings }, setResult] =
+    React.useState<RenderResult>(NOTHING_YET)
 
   React.useEffect(() => {
-    setToc(markdown2Headings(children))
-    setElement(markdown2ReactElements(children))
-  }, [children, markdown2Headings, markdown2ReactElements])
+    setResult(render(children, { shiftHeading, tocMaxDepth }))
+  }, [children, shiftHeading, tocMaxDepth])
 
   React.useEffect(() => {
-    // Necessary to make in-page links work.
-    const scrollToHash = async () => {
-      await sleep(500)
-      if (location.hash) {
-        document
-          .getElementById(decodeURI(location.hash.substring(1)))
-          ?.scrollIntoView()
-      }
-    }
-    scrollToHash()
-  }, [])
-
-  const style = `
-    rounded-3xl
-    p-10
-    bg-yellow-50
-  `
+    // The browser looked for the anchor before this markup existed, so the jump
+    // is made again once it does.
+    if (!html) return
+    const id = decodeURI(window.location.hash.slice(1))
+    if (!id) return
+    document.getElementById(id)?.scrollIntoView()
+  }, [html])
 
   return (
     <div className="py-8 flex flex-col gap-8">
-      {showToc && (
-        <nav className={style}>
-          <h2 className="mb-4 font-bold text-h-xs-m sm:text-h-xs">
-            {tocTitle}
-          </h2>
+      {showToc && headings.length > 0 && (
+        <nav className="rounded-3xl p-10 bg-yellow-50">
+          <H2 className="pt-0">{tocTitle}</H2>
           <Ul>
-            <TableOfContents items={toc} />
+            <TableOfContents items={headings} />
           </Ul>
         </nav>
       )}
-      {element}
+      {/* The markup is sanitised in src/sanitize.ts before it gets here. */}
+      <div dangerouslySetInnerHTML={{ __html: html }} />
     </div>
   )
 }

package/packages/markdown/src/components/index.ts

@@ -1 +1 @@
-export { Markdown } from './Markdown'
+export { Markdown, TableOfContents } from './Markdown'

package/packages/markdown/src/decorate.ts

@@ -0,0 +1,164 @@
+import { styles } from '@sakura-ui/core'
+import Slugger from 'github-slugger'
+import { classNames } from './marked/html'
+
+/**
+ * Applies the look of the design system to the finished document.
+ *
+ * This runs over the sanitised DOM rather than inside the markdown renderer so
+ * that a table written as raw HTML — 56 of the guide's documents do — is styled
+ * the same as one written with pipes. The pipeline this replaces had the same
+ * property, because rehype-raw turned the raw HTML into real nodes before the
+ * tag to component mapping ran.
+ */
+
+export type HeadingItem = {
+  id?: string
+  depth: number
+  value?: string
+  children?: HeadingItem[]
+}
+
+/** tag name to the classes the matching component puts on it */
+const CLASS_BY_TAG: Record<string, string> = {
+  h1: styles.headingStyle.h1,
+  h2: styles.headingStyle.h2,
+  h3: styles.headingStyle.h3,
+  h4: styles.headingStyle.h4,
+  h5: styles.headingStyle.h5,
+  h6: styles.headingStyle.h6,
+  ul: styles.ulStyle,
+  ol: styles.olStyle,
+  pre: styles.preStyle,
+  code: styles.codeStyle,
+  table: styles.tableBorderStyle,
+  caption: styles.captionStyle,
+  th: classNames(styles.thStyle, styles.tableBorderStyle),
+  tr: styles.tableBorderStyle,
+  td: classNames(styles.tdStyle, styles.tableBorderStyle),
+  a: styles.linkStyle
+}
+
+/** Elements a directive rendered are already dressed; leave them be. */
+const isDirectiveOutput = (element: Element) =>
+  element.hasAttribute('data-sakura')
+
+const addClass = (element: Element, value: string) => {
+  const merged = classNames(element.getAttribute('class') ?? '', value)
+  if (merged) element.setAttribute('class', merged)
+}
+
+const HEADINGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6'])
+
+/**
+ * Says that the link leaves the page. The glyph is hidden from assistive
+ * technology and the words next to it carry the meaning instead, which is what
+ * the Icon component does.
+ */
+const appendNewTabIcon = (anchor: Element, document: Document) => {
+  if (anchor.querySelector('[data-sakura-new-tab]')) return
+  const glyph = document.createElement('span')
+  glyph.setAttribute('aria-hidden', 'true')
+  glyph.setAttribute('data-sakura-new-tab', 'true')
+  glyph.setAttribute(
+    'class',
+    classNames(styles.iconSizeStyle[16], styles.iconStyle, 'ml-0.5')
+  )
+  glyph.textContent = 'open_in_new'
+  const label = document.createElement('span')
+  label.setAttribute('class', 'sr-only')
+  label.textContent = 'Opens in new tab'
+  anchor.append(glyph, label)
+}
+
+export type DecorateOptions = {
+  shiftHeading: number
+  tocMaxDepth: number
+}
+
+export type DecorateResult = {
+  headings: HeadingItem[]
+}
+
+const clampLevel = (level: number) => Math.min(6, Math.max(1, level))
+
+export const decorate = (
+  root: DocumentFragment | Element,
+  document: Document,
+  options: DecorateOptions
+): DecorateResult => {
+  const { shiftHeading, tocMaxDepth } = options
+  const slugger = new Slugger()
+  const flat: HeadingItem[] = []
+
+  // The heading level has to move before the id is read, so that the id belongs
+  // to the element that ends up in the document.
+  if (shiftHeading !== 0) {
+    for (const heading of Array.from(
+      root.querySelectorAll('h1,h2,h3,h4,h5,h6')
+    )) {
+      const depth = Number(heading.tagName[1])
+      const moved = document.createElement(
+        `h${clampLevel(depth + shiftHeading)}`
+      )
+      for (const attribute of Array.from(heading.attributes)) {
+        moved.setAttribute(attribute.name, attribute.value)
+      }
+      moved.innerHTML = heading.innerHTML
+      heading.replaceWith(moved)
+    }
+  }
+
+  for (const element of Array.from(root.querySelectorAll('*'))) {
+    const tag = element.tagName.toLowerCase()
+
+    // One id, generated once, for headings from markdown and from raw HTML
+    // alike. The pipeline this replaces generated them in two passes that
+    // disagreed whenever a heading held an image, raw HTML or a directive, and
+    // the table of contents then linked to anchors that were not there.
+    if (HEADINGS.has(tag)) {
+      const text = element.textContent ?? ''
+      const asked = element.getAttribute('id')
+      // An id the author asked for is kept as written, but still handed to the
+      // slugger, so that a heading further down does not generate the same one.
+      if (asked) slugger.slug(asked)
+      const id = asked || slugger.slug(text)
+      element.setAttribute('id', id)
+      flat.push({ id, depth: Number(tag[1]) - shiftHeading, value: text })
+    }
+
+    if (isDirectiveOutput(element)) continue
+
+    if (tag === 'a') {
+      const href = element.getAttribute('href') ?? ''
+      if (
+        href.startsWith('http') ||
+        element.getAttribute('target') === '_blank'
+      ) {
+        element.setAttribute('target', '_blank')
+        // The content writes target="_blank" 41 times and rel not once, which
+        // leaves the opened page holding a handle on this one.
+        element.setAttribute('rel', 'noopener noreferrer')
+        appendNewTabIcon(element, document)
+      }
+    }
+
+    const cls = CLASS_BY_TAG[tag]
+    if (cls) addClass(element, cls)
+  }
+
+  // A wide table scrolls inside its own box rather than pushing the page.
+  for (const table of Array.from(root.querySelectorAll('table'))) {
+    const parent = table.parentElement
+    if (parent?.dataset?.sakuraTableContainer === 'true') continue
+    const container = document.createElement('div')
+    container.setAttribute('class', classNames(styles.overflowContainerStyle))
+    container.dataset.sakuraTableContainer = 'true'
+    table.replaceWith(container)
+    container.appendChild(table)
+  }
+
+  return {
+    headings: flat.filter((h) => h.depth <= tocMaxDepth) as HeadingItem[]
+  }
+}

package/packages/markdown/src/index.ts

@@ -1 +1,3 @@
-export { Markdown } from './components'
+export { Markdown, TableOfContents } from './components'
+export { render } from './render'
+export type { HeadingItem, RenderOptions, RenderResult } from './render'

package/packages/markdown/src/marked/attributes.ts

@@ -0,0 +1,88 @@
+const ATTR_RE =
+  /([#.])?([A-Za-z_:][-A-Za-z0-9_.:]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'{}]+)))?/g
+
+export type Attrs = Record<string, string>
+
+/**
+ * Where `{#name}` is kept, apart from anything written as `key=value`.
+ *
+ * A sigil says something about the element itself and means the same on every
+ * directive; an attribute is the directive's own, and each reads the ones it
+ * knows. Keeping them in one place would let a directive that wanted an
+ * attribute called `id` take the anchor's place, which is how the video on a
+ * youtube embed came to be called `id` and stayed that way.
+ *
+ * A key beginning with `#` cannot be written as `key=value`, since an attribute
+ * name has to start with a letter, so there is nowhere for the two to meet.
+ */
+export const ANCHOR = '#id'
+
+/** Parses the inside of `{...}`: `key=value key2="値 2" #id .cls` */
+export const parseAttrs = (body: string | null): Attrs => {
+  const out: Attrs = {}
+  if (!body) return out
+  ATTR_RE.lastIndex = 0
+  let m = ATTR_RE.exec(body)
+  while (m !== null) {
+    const [, sigil, key, doubleQuoted, singleQuoted, bare] = m
+    const value = doubleQuoted ?? singleQuoted ?? bare
+    if (sigil === '#') {
+      out[ANCHOR] = key
+    } else if (sigil === '.') {
+      out.class = out.class ? `${out.class} ${key}` : key
+    } else {
+      out[key] = value ?? ''
+    }
+    m = ATTR_RE.exec(body)
+  }
+  return out
+}
+
+/**
+ * Reads a delimited run, counting nesting. remark-directive accepts a label
+ * like `[a [b] c]`, so matching `\[([^\]]*)\]` would cut it in the wrong place.
+ */
+export const readDelimited = (
+  src: string,
+  start: number,
+  open: string,
+  close: string
+): { value: string; end: number } | null => {
+  if (src[start] !== open) return null
+  let depth = 0
+  for (let i = start; i < src.length; i++) {
+    const ch = src[i]
+    if (ch === '\\') {
+      i++
+      continue
+    }
+    if (ch === '\n') return null
+    if (ch === open) {
+      depth++
+    } else if (ch === close) {
+      depth--
+      if (depth === 0) return { value: src.slice(start + 1, i), end: i + 1 }
+    }
+  }
+  return null
+}
+
+/** An optional `[label]` followed by an optional `{attrs}`, starting at index i */
+export const readTail = (
+  src: string,
+  i: number
+): { label: string | null; attrs: Attrs; end: number } => {
+  let label: string | null = null
+  const labelRun = readDelimited(src, i, '[', ']')
+  if (labelRun) {
+    label = labelRun.value
+    i = labelRun.end
+  }
+  let attrs: Attrs = {}
+  const attrRun = readDelimited(src, i, '{', '}')
+  if (attrRun) {
+    attrs = parseAttrs(attrRun.value)
+    i = attrRun.end
+  }
+  return { label, attrs, end: i }
+}