@chassis-ui/docs 0.1.10 → 0.3.0

package/src/components/shortcodes/Code.astro

@@ -0,0 +1,289 @@
+---
+import fs from 'node:fs'
+import path from 'node:path'
+import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers'
+import { getConfig } from '@libs/config'
+import { highlightCode } from '../../libs/highlight'
+import Icon from './Icon.astro'
+
+interface Props {
+  /**
+   * If extra JS snippet should be added to StackBlitz or not.
+   * @default false
+   */
+  addStackblitzJs?: boolean
+  /**
+   * The CSS class(es) to be added to the `pre` HTML element when rendering code blocks in Markdown.
+   * Note that this prop is not used when the component is invoked directly.
+   */
+  class?: string
+  /**
+   * The code to highlight.
+   * If an array is passed, elements will be joined with a new line.
+   */
+  code?: string | string[]
+  /**
+   * The CSS class(es) to be added to the `div` wrapper HTML element.
+   */
+  containerClass?: string
+  /**
+   * The language attribute from Shiki/Astro markdown processing
+   */
+  'data-language'?: string
+  /**
+   * The language to use for highlighting.
+   * @see https://shiki.style/languages
+   */
+  lang?: string
+  /**
+   * If the `filePath` prop is defined, this prop can be used to specify a regex containing a match group to extract
+   * only a part of the file.
+   */
+  fileMatch?: string
+  /**
+   * A path to the file containing the code to highlight relative to the root of the repository.
+   * This takes precedence over the `code` prop.
+   */
+  filePath?: string
+  /**
+   * A file path to display in the highlight toolbar instead of the language label.
+   */
+  file?: string
+  /**
+   * Defines if the `<Code>` component is nested inside an `<Example>` component or not.
+   * @default false
+   */
+  nestedInExample?: boolean
+  /**
+   * If true, hides the highlight toolbar (language label and copy button).
+   * @default false
+   */
+  noToolbar?: boolean
+  /**
+   * If true, displays line numbers in the code block.
+   * @default false
+   */
+  lineNumbers?: boolean
+  /**
+   * If true, displays color mode and stackblitz buttons in the toolbar.
+   * @default false
+   */
+  hasPreview?: boolean
+}
+
+const {
+  addStackblitzJs = false,
+  class: className,
+  code,
+  containerClass,
+  'data-language': dataLanguage,
+  file,
+  fileMatch,
+  filePath,
+  lang,
+  nestedInExample = false,
+  noToolbar = false,
+  lineNumbers = false,
+  hasPreview = false
+} = Astro.props
+
+const fileUrl = file
+  ? `${getConfig().repo}/blob/v${getConfig().current_version}/${file}`.replaceAll('\\', '/')
+  : null
+
+// Extract language from multiple possible sources (for markdown code blocks)
+// Priority: lang prop > data-language attribute > className pattern
+let detectedLang = lang || dataLanguage
+if (!detectedLang && className) {
+  const langMatch = className.match(/language-(\w+)/)
+  if (langMatch) {
+    detectedLang = langMatch[1]
+  }
+}
+
+// Format language for display (e.g., "html" -> "HTML", "javascript" -> "JavaScript")
+const displayLang = detectedLang
+  ? detectedLang === 'js'
+    ? 'JavaScript'
+    : detectedLang === 'ts'
+      ? 'TypeScript'
+      : detectedLang === 'html'
+        ? 'HTML'
+        : detectedLang === 'css'
+          ? 'CSS'
+          : detectedLang === 'scss'
+            ? 'SCSS'
+            : detectedLang === 'bash' || detectedLang === 'sh'
+              ? 'Shell'
+              : detectedLang === 'powershell'
+                ? 'PowerShell'
+                : detectedLang.toUpperCase()
+  : ''
+
+let codeToDisplay = filePath
+  ? fs.readFileSync(path.join(process.cwd(), filePath), 'utf8')
+  : Array.isArray(code)
+    ? code.join('\n')
+    : code
+
+if (filePath && fileMatch && codeToDisplay) {
+  const matches = [...codeToDisplay.matchAll(new RegExp(fileMatch, 'g'))]
+
+  if (matches.length === 0) {
+    throw new Error(
+      `The file at ${filePath} does not contain a match for the regex '${fileMatch}'.`
+    )
+  }
+
+  codeToDisplay = matches.map((m) => m[0]).join('\n\n')
+}
+
+const diffTransformers = [transformerNotationDiff(), transformerNotationHighlight()]
+
+let highlightedCode: string | null = null
+if (codeToDisplay && detectedLang) {
+  const { html } = await highlightCode(codeToDisplay, detectedLang, diffTransformers)
+  highlightedCode = html
+}
+---
+
+<script>
+  import { Tooltip } from '@chassis-ui/css'
+  import { initCopyButtons } from '@libs/clipboard'
+
+  document.querySelectorAll('.button-edit').forEach((button) => {
+    Tooltip.getOrCreateInstance(button, { title: 'Edit on StackBlitz' })
+  })
+
+  initCopyButtons('.button-clipboard', (trigger) => {
+    const snippet = trigger.closest('.cxd-code-snippet') || trigger.closest('.cxd-example-snippet')
+    const activeTab = snippet?.querySelector('.code-tab-content.active .astro-code')
+    if (activeTab) {
+      return activeTab.textContent?.trim() || ''
+    }
+
+    return snippet?.querySelector('.astro-code')?.textContent?.trim() || ''
+  })
+</script>
+
+{
+  nestedInExample && !noToolbar && (
+    <div class="cxd-snippet-toolbar">
+      {file ? (
+        <a
+          class="text-decoration-none font-code fg-subtle text-uppercase"
+          href={fileUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          {file}
+        </a>
+      ) : (
+        <small class="font-code fg-subtle text-uppercase">{displayLang}</small>
+      )}
+      <div class="d-flex ms-auto gap-2xsmall">
+        {hasPreview && (
+          <>
+            <button
+              type="button"
+              class="button-mode"
+              title="Toggle color mode"
+              aria-label="Toggle color mode"
+              onclick="toggleTheme(this)"
+            >
+              <Icon name="swatchbook-solid" />
+            </button>
+            <span class="vr mx-2xsmall" />
+            <button
+              type="button"
+              class="button-edit"
+              title="Try it on StackBlitz"
+              aria-label="Try it on StackBlitz"
+              data-sb-js-snippet={addStackblitzJs ? true : undefined}
+            >
+              <Icon name="lightning-solid" />
+            </button>
+          </>
+        )}
+        <button
+          type="button"
+          class="button-clipboard"
+          title="Copy to clipboard"
+          aria-label="Copy to clipboard"
+        >
+          <Icon name="clipboard-outline" />
+        </button>
+      </div>
+    </div>
+  )
+}
+
+{
+  nestedInExample ? (
+    <>
+      {highlightedCode ? (
+        <div class:list={['cxd-code', { 'line-numbers': lineNumbers }]}>
+          <Fragment set:html={highlightedCode} />
+        </div>
+      ) : (
+        <div class:list={['cxd-code', { 'line-numbers': lineNumbers }]}>
+          {/* prettier-ignore */}
+          <pre class={className}><slot /></pre>
+        </div>
+      )}
+    </>
+  ) : (
+    <div class:list={['cxd-code-snippet', containerClass]} data-pagefind-ignore>
+      {!noToolbar && (
+        <div class="cxd-snippet-toolbar">
+          {file ? (
+            <a
+              class="text-decoration-none font-code fg-subtle"
+              href={fileUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              {file}
+            </a>
+          ) : (
+            <small class="font-code fg-subtle text-uppercase">{displayLang}</small>
+          )}
+          <div class="d-flex ms-auto gap-2xsmall">
+            <button
+              type="button"
+              class="button-clipboard"
+              title="Copy to clipboard"
+              aria-label="Copy to clipboard"
+            >
+              <Icon name="clipboard-outline" />
+            </button>
+          </div>
+        </div>
+      )}
+      <slot name="pre" />
+      {!Astro.slots.has('pre') && noToolbar ? (
+        <div class="cxd-clipboard">
+          <button
+            type="button"
+            class="button-clipboard"
+            title="Copy to clipboard"
+            aria-label="Copy to clipboard"
+          >
+            <Icon name="clipboard-outline" />
+          </button>
+        </div>
+      ) : null}
+
+      {highlightedCode ? (
+        <div class:list={['cxd-code', { 'line-numbers': lineNumbers }]}>
+          <Fragment set:html={highlightedCode} />
+        </div>
+      ) : (
+        <div class:list={['cxd-code', { 'line-numbers': lineNumbers }]}>
+          {/* prettier-ignore */}
+          <pre class={className}><slot /></pre>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/shortcodes/DeprecatedIn.astro

@@ -0,0 +1,18 @@
+---
+/**
+ * Deprecated In
+ *
+ * Badge indicating the version in which a feature was deprecated.
+ */
+
+interface Props {
+  /** Version number when the feature was deprecated (e.g. `"2.1.0"`). */
+  version: string
+}
+
+const { version } = Astro.props
+---
+
+<span class="badge large warning smooth mb-medium rounded-medium">
+  Deprecated in v{version}
+</span>

package/src/components/shortcodes/Example.astro

@@ -0,0 +1,132 @@
+---
+import { replacePlaceholdersInHtml } from '../../libs/placeholder'
+import { replaceIconsInHtml } from '../../libs/icon'
+import Code from './Code.astro'
+import Icon from './Icon.astro'
+
+interface Props {
+  /**
+   * Defines if extra JS snippet should be added to StackBlitz or not.
+   * @default false
+   */
+  addStackblitzJs?: boolean
+  /**
+   * The example code.
+   * If an array is passed, elements will be joined with a new line.
+   */
+  code: string | string[]
+  /**
+   * Custom markup to display in the source code section, different from the preview code.
+   * If provided, this will be used instead of the `code` prop for the source display.
+   */
+  customMarkup?: string | string[]
+  /**
+   * The CSS class(es) to be added to the preview wrapping `div` element.
+   */
+  class?: string
+  /**
+   * A file path to display in the highlight toolbar instead of the language label.
+   */
+  file?: string
+  /**
+   * The preview wrapping `div` element ID.
+   */
+  id?: string
+  /**
+   * Language used to display the code.
+   * @default 'html'
+   */
+  lang?: string
+  /**
+   * Defines if the markup should be visible or not.
+   * @default true
+   */
+  showMarkup?: boolean
+  /**
+   * Defines if the preview should be visible or not.
+   * @default true
+   */
+  showPreview?: boolean
+  /**
+   * If true, displays line numbers in the code block.
+   * @default false
+   */
+  lineNumbers?: boolean
+}
+
+const {
+  addStackblitzJs = false,
+  code,
+  customMarkup,
+  class: className,
+  file,
+  id,
+  lang = 'html',
+  lineNumbers = false,
+  showMarkup = true,
+  showPreview = true
+} = Astro.props
+
+let markup = Array.isArray(code) ? code.join('\n') : code
+markup = replacePlaceholdersInHtml(markup)
+markup = replaceIconsInHtml(markup)
+markup = markup
+  .split('\n')
+  .map((line) => line.trimEnd())
+  .join('\n')
+
+// Use customMarkup for source code display if provided, otherwise use the processed markup
+let sourceMarkup = customMarkup
+  ? Array.isArray(customMarkup)
+    ? customMarkup.join('\n')
+    : customMarkup
+  : markup
+
+const simplifiedMarkup = sourceMarkup
+  .replace(
+    /<svg.*class="cxd-placeholder-image(?:-large)?(?: *?cxd-placeholder-image-large)? ?(.*?)".*?<\/svg>/g,
+    (_match, classes) => `<img src="..."${classes ? ` class="${classes}"` : ''} alt="...">`
+  )
+  .replace(
+    /<img.*class="cxd-placeholder-image(?:-large)?(?: *?cxd-placeholder-image-large)? ?(.*?)".*?>/g,
+    (_match, classes) => `<img src="..."${classes ? ` class="${classes}"` : ''} alt="...">`
+  )
+  .replace(/(<svg class="icon\b[^"]*")\s+width="\d+"\s+height="\d+"/g, '$1')
+  .replace(/href="\/static\/icons\/chassis-icons\.svg#/g, 'href="#')
+---
+
+<div class="cxd-example-snippet cxd-code-snippet not-prose" data-pagefind-ignore>
+  {
+    showPreview && (
+      <div id={id} class:list={['cxd-example m-0 border-0 context', className]}>
+        {!showMarkup && (
+          <div class="cxd-mode">
+            <button
+              type="button"
+              class="button-mode"
+              title="Toggle color mode"
+              aria-label="Toggle color mode"
+              onclick="toggleTheme(this)"
+            >
+              <Icon name="swatchbook-solid" />
+            </button>
+          </div>
+        )}
+        <Fragment set:html={markup} />
+      </div>
+    )
+  }
+  {
+    showMarkup && (
+      <Code
+        code={simplifiedMarkup}
+        lang={lang}
+        file={file}
+        lineNumbers={lineNumbers}
+        nestedInExample={true}
+        addStackblitzJs={addStackblitzJs}
+        hasPreview={showPreview}
+      />
+    )
+  }
+</div>

package/src/components/shortcodes/Icon.astro

@@ -0,0 +1,57 @@
+---
+/**
+ * Icon
+ *
+ * Renders a Chassis icon, either as an SVG referencing the icon sprite
+ * or as a font glyph via the `cx-{name}` icon font class.
+ */
+
+interface Props {
+  /** Icon name/id, e.g. `folder-tree`. */
+  name: string
+  /** Additional CSS class(es) to add alongside the standard `icon` class. */
+  class?: string
+  /** Width/height (in px) applied to the SVG. Ignored in `font` mode. */
+  size?: number
+  /** Render as a `<span class="icon cx-{name}">` font glyph instead of an SVG `<use>`. */
+  font?: boolean
+  /** Accessible name. When set, the icon is exposed to assistive tech instead of hidden. */
+  title?: string
+  /** Path to the SVG sprite file. Ignored in `font` mode. */
+  sprite?: string
+  /** Any other attribute (e.g. `style`, `role`) is passed through to the rendered element. */
+  [key: string]: unknown
+}
+
+const {
+  name,
+  class: className,
+  size = 24,
+  font = false,
+  title,
+  sprite = '/static/icons/chassis-icons.svg',
+  ...rest
+} = Astro.props
+---
+
+{
+  font ? (
+    <span
+      class:list={['icon', `cx-${name}`, className]}
+      aria-hidden={title ? undefined : 'true'}
+      aria-label={title}
+      {...rest}
+    />
+  ) : (
+    <svg
+      class:list={['icon', className]}
+      width={size}
+      height={size}
+      aria-hidden={title ? undefined : 'true'}
+      {...rest}
+    >
+      {title && <title>{title}</title>}
+      <use href={`${sprite}#${name}`} />
+    </svg>
+  )
+}

package/src/components/shortcodes/InFigma.astro

@@ -0,0 +1,26 @@
+---
+/**
+ * In Figma
+ *
+ * Badge indicating a variant exists in the Figma component library with bound
+ * design tokens. Renders with a tooltip that can be customized.
+ */
+
+interface Props {
+  /** Custom tooltip text. Defaults to a generated message based on `plural`. */
+  tooltip?: string
+  /** When true, uses plural phrasing in the default tooltip text. */
+  plural?: boolean
+}
+
+const { tooltip, plural } = Astro.props
+const tooltipText =
+  tooltip ??
+  `This variant${plural ? 's' : ''} exist${plural ? '' : 's'} in the Figma component library with bound design tokens.`
+---
+
+<span
+  class="badge large primary smooth mb-medium rounded-medium"
+  data-cx-toggle="tooltip"
+  title={tooltipText}>In Figma</span
+>

package/src/components/shortcodes/JsDocs.astro

@@ -0,0 +1,64 @@
+---
+import fs from 'node:fs'
+import Code from './Code.astro'
+
+// Prints everything between `// js-docs-start "name"` and `// js-docs-end "name"`
+// comments in the docs.
+
+interface Props {
+  /**
+   * Reference name used to find the content to display within the content of the `file` prop.
+   */
+  name: string
+  /**
+   * File path that contains the content to display relative to the root of the repository.
+   */
+  file: string
+}
+
+const { name, file } = Astro.props
+
+if (!name || !file) {
+  throw new Error(
+    `Missing required parameter(s) for the '<JsDocs />' component, expected both 'name' and 'file' but got 'name: ${name}' and 'file: ${file}'.`
+  )
+}
+
+let content: string
+
+try {
+  const fileContent = fs.readFileSync(file, 'utf8')
+
+  const matches = fileContent.match(
+    new RegExp(`// js-docs-start ${name}\n((?:.|\n)*)// js-docs-end ${name}`, 'm')
+  )
+
+  if (!matches || !matches[1]) {
+    throw new Error(
+      `Failed to find the content named '${name}', make sure that '// js-docs-start ${name}' and '// js-docs-end ${name}' are defined.`
+    )
+  }
+
+  content = matches[1]
+
+  // Fix the identation by removing extra spaces at the beginning of each line
+  const lines = content.split('\n')
+  const spaceCounts = lines
+    .filter((line) => line.trim().length > 0)
+    .map((line) => line.match(/^ */)![0].length)
+  const minSpaces = spaceCounts.length ? Math.min(...spaceCounts) : 0
+  content = lines
+    .map((line) => line.slice(minSpaces))
+    .join('\n')
+    .trim()
+} catch (error) {
+  throw new Error(
+    `Failed to find the content to render in the '<JsDocs />' component at '${file}'.`,
+    {
+      cause: error
+    }
+  )
+}
+---
+
+<Code containerClass="cxd-example-snippet cxd-file-ref" code={content} file={file} lang="js" />

package/src/components/shortcodes/Placeholder.astro

@@ -0,0 +1,28 @@
+---
+import { getPlaceholder, type PlaceholderOptions } from '../../libs/placeholder'
+
+type Props = Partial<PlaceholderOptions>
+
+const {
+  options: { background, color, showText, showTitle, text, title },
+  props,
+  type
+} = getPlaceholder(Astro.props)
+---
+
+{
+  type === 'img' ? (
+    // eslint-disable-next-line astro/jsx-a11y/alt-text
+    <img {...props} />
+  ) : (
+    <svg {...props}>
+      {showTitle && <title>{title}</title>}
+      <rect width="100%" height="100%" fill={background} />
+      {showText && (
+        <text x="50%" y="50%" fill={color} dy=".3em">
+          {text}
+        </text>
+      )}
+    </svg>
+  )
+}