@chassis-ui/docs 0.1.0

package/src/libs/remark.ts

@@ -0,0 +1,205 @@
+import type { Root } from 'mdast'
+import type { MdxJsxAttribute, MdxJsxExpressionAttribute } from 'mdast-util-mdx-jsx'
+import type { Plugin } from 'unified'
+import { visit } from 'unist-util-visit'
+
+// Global registry for config and path functions
+let globalConfigGetter: (() => any) | null = null
+let globalPathGetter: ((path: string) => string) | null = null
+
+// Registration function for consuming sites to provide their config and path functions
+export function registerRemarkFunctions(
+  getConfig: () => any,
+  getChassisDocsPath: (path: string) => string
+) {
+  globalConfigGetter = getConfig
+  globalPathGetter = getChassisDocsPath
+}
+
+// [[config:foo]]
+// [[config:foo.bar]]
+const configRegExp = /\[\[config:(?<name>[\w.]+)]]/g
+// [[docsref:/foo]]
+// [[docsref:/foo/bar#baz]]
+const docsrefRegExp = /\[\[docsref:(?<path>[\w./#-]+)]]/g
+
+// A remark plugin to replace config values embedded in markdown (or MDX) files.
+// For example, [[config:foo]] will be replaced with the value of the `foo` key in the `config.yml` file.
+// Nested values are also supported, e.g. [[config:foo.bar]].
+// Note: this also works in frontmatter.
+// Note: this plugin is meant to facilitate the migration from Hugo to Astro while keeping the differences to a minimum.
+// At some point, this plugin should maybe be removed and embrace a more MDX-friendly syntax.
+export const remarkCxConfig: Plugin<[], Root> = function () {
+  return function remarkCxConfigPlugin(ast, file) {
+    if (containsFrontmatter(file.data.astro)) {
+      replaceInFrontmatter(file.data.astro.frontmatter, replaceConfigInText)
+    }
+
+    // https://github.com/syntax-tree/mdast#nodes
+    // https://github.com/syntax-tree/mdast-util-mdx-jsx#nodes
+    visit(
+      ast,
+      ['code', 'definition', 'image', 'inlineCode', 'link', 'mdxJsxFlowElement', 'text'],
+      (node) => {
+        switch (node.type) {
+          case 'code':
+          case 'inlineCode':
+          case 'text': {
+            node.value = replaceConfigInText(node.value)
+            break
+          }
+          case 'image': {
+            if (node.alt) {
+              node.alt = replaceConfigInText(node.alt)
+            }
+
+            node.url = replaceConfigInText(node.url)
+            break
+          }
+          case 'definition':
+          case 'link': {
+            node.url = replaceConfigInText(node.url)
+            break
+          }
+          case 'mdxJsxFlowElement': {
+            node.attributes = replaceConfigInAttributes(node.attributes)
+            break
+          }
+        }
+      }
+    )
+  }
+}
+
+// A remark plugin to add versionned docs links in markdown (or MDX) files.
+// For example, [[docsref:/foo]] will be replaced with the `/docs/${docs_version}/foo` value with the `docs_version`
+// value being read from the `config.yml` file.
+// Note: this also works in frontmatter.
+// Note: this plugin is meant to facilitate the migration from Hugo to Astro while keeping the differences to a minimum.
+// At some point, this plugin should maybe be removed and embrace a more MDX-friendly syntax.
+export const remarkCxDocsref: Plugin<[], Root> = function () {
+  return function remarkCxDocsrefPlugin(ast, file) {
+    if (containsFrontmatter(file.data.astro)) {
+      replaceInFrontmatter(file.data.astro.frontmatter, replaceDocsrefInText)
+    }
+
+    // https://github.com/syntax-tree/mdast#nodes
+    // https://github.com/syntax-tree/mdast-util-mdx-jsx#nodes
+    visit(
+      ast,
+      [
+        'code',
+        'definition',
+        'image',
+        'inlineCode',
+        'link',
+        'mdxJsxFlowElement',
+        'mdxJsxTextElement',
+        'text'
+      ],
+      (node) => {
+        switch (node.type) {
+          case 'code':
+          case 'inlineCode':
+          case 'text': {
+            node.value = replaceDocsrefInText(node.value)
+            break
+          }
+          case 'definition':
+          case 'link': {
+            node.url = replaceDocsrefInText(node.url)
+            break
+          }
+          case 'mdxJsxFlowElement':
+          case 'mdxJsxTextElement': {
+            node.attributes = replaceDocsrefInAttributes(node.attributes)
+            break
+          }
+        }
+      }
+    )
+  }
+}
+
+export function replaceConfigInText(text: string) {
+  return text.replace(configRegExp, (_match, path) => {
+    const value = getConfigValueAtPath(path)
+
+    if (!value) {
+      throw new Error(`Failed to find a valid configuration value for '${path}'.`)
+    }
+
+    return value
+  })
+}
+
+function replaceConfigInAttributes(attributes: (MdxJsxAttribute | MdxJsxExpressionAttribute)[]) {
+  return attributes.map((attribute) => {
+    if (attribute.type === 'mdxJsxAttribute' && typeof attribute.value === 'string') {
+      attribute.value = replaceConfigInText(attribute.value)
+    }
+
+    return attribute
+  })
+}
+
+export function replaceDocsrefInText(text: string) {
+  if (!globalPathGetter) {
+    throw new Error('remark functions not registered. Call registerRemarkFunctions() first.')
+  }
+  return text.replace(docsrefRegExp, (_match, path) => {
+    return globalPathGetter!(path)
+  })
+}
+
+function replaceDocsrefInAttributes(attributes: (MdxJsxAttribute | MdxJsxExpressionAttribute)[]) {
+  return attributes.map((attribute) => {
+    if (attribute.type === 'mdxJsxAttribute' && typeof attribute.value === 'string') {
+      attribute.value = replaceDocsrefInText(attribute.value)
+    }
+
+    return attribute
+  })
+}
+
+function getConfigValueAtPath(path: string) {
+  if (!globalConfigGetter) {
+    throw new Error('remark functions not registered. Call registerRemarkFunctions() first.')
+  }
+  const config = globalConfigGetter()
+
+  const value = path.split('.').reduce((values, part) => {
+    if (!values || typeof values !== 'object') {
+      return undefined
+    }
+
+    return (values as any)?.[part]
+  }, config as unknown)
+
+  return typeof value === 'string' ? value : undefined
+}
+
+function replaceInFrontmatter(
+  record: Record<string, unknown>,
+  replacer: (value: string) => string
+) {
+  for (const [key, value] of Object.entries(record)) {
+    if (typeof value === 'string') {
+      record[key] = replacer(value)
+    } else if (Array.isArray(value)) {
+      record[key] = value.map((arrayValue) => {
+        return typeof arrayValue === 'string'
+          ? replacer(arrayValue)
+          : typeof arrayValue === 'object'
+            ? replaceInFrontmatter(arrayValue, replacer)
+            : arrayValue
+      })
+    }
+  }
+
+  return record
+}
+
+function containsFrontmatter(data: unknown): data is { frontmatter: Record<string, unknown> } {
+  return data != undefined && typeof data === 'object' && 'frontmatter' in data
+}

package/src/libs/toc.ts

@@ -0,0 +1,44 @@
+import type { MarkdownHeading } from 'astro'
+// import { getConfig } from './config'
+
+// Generate a tree like structure from a list of headings.
+export function generateToc(allHeadings: MarkdownHeading[], config: any) {
+  const headings = allHeadings.filter(
+    (heading) => heading.depth >= config.toc.min && heading.depth <= config.toc.max
+  )
+
+  const toc: TocEntry[] = []
+
+  for (const heading of headings) {
+    if (toc.length === 0) {
+      toc.push({ ...heading, children: [] })
+      continue
+    }
+
+    const previousEntry = toc[toc.length - 1]
+
+    if (heading.depth === previousEntry.depth) {
+      toc.push({ ...heading, children: [] })
+      continue
+    }
+
+    const children = getEntryChildrenAtDepth(previousEntry, heading.depth - previousEntry.depth)
+    children.push({ ...heading, children: [] })
+  }
+
+  return toc
+}
+
+function getEntryChildrenAtDepth(entry: TocEntry, depth: number): TocEntry['children'] {
+  if (!entry) {
+    return []
+  }
+
+  return depth === 1
+    ? entry.children
+    : getEntryChildrenAtDepth(entry.children[entry.children.length - 1], depth - 1)
+}
+
+export interface TocEntry extends MarkdownHeading {
+  children: TocEntry[]
+}

package/src/libs/utils.ts

@@ -0,0 +1,122 @@
+import os from 'os'
+import { slug } from 'github-slugger'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { toString } from 'mdast-util-to-string'
+import { remark } from 'remark'
+import remarkHtml from 'remark-html'
+
+export function capitalizeFirstLetter(str: string) {
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+export function getSequence(start: number, end: number, step = 1) {
+  const sequence = []
+
+  for (let i = start; i <= end; i += step) {
+    sequence.push(i)
+  }
+
+  return sequence
+}
+
+// This function is used in the docs sidebar to generate partial slugs and properly order the sidebar entries and also
+// to generate docs frontmatter sections slugs.
+// Note: this should be refactored and removed, the sidebar ordering defined in `site/data/sidebar.yml` should not rely
+// on slugified custom titles that are expected to generate a string matching the actual file names on disk, this is
+// error prone. Instead, custom sidebar titles should be defined in the frontmatter of the MDX files when needed and
+// `site/data/sidebar.yml` should only reference the actual file names and slug extracted from the docs content
+// collection. Same goes for the docs frontmatter sections.
+export function getSlug(str: string) {
+  return slug(str).replace(/--+/g, '-')
+}
+
+export function trimLeadingAndTrailingSlashes(str: string) {
+  return str.replace(/^\/+|\/+$/g, '')
+}
+
+export function stripMarkdown(str: string) {
+  return toString(fromMarkdown(str))
+}
+
+export function processMarkdownToHtml(markdown: string): string {
+  // Use remark to process markdown to HTML
+  const result = remark().use(remarkHtml).processSync(markdown)
+  return result.toString()
+}
+
+export function titleCase(str: string) {
+  return str.replace(
+    /\w\S*/g,
+    (text) => text.charAt(0).toUpperCase() + text.substring(1).toLowerCase()
+  )
+}
+
+/**
+ * Gets the appropriate host and port for development server
+ * @returns {object} Object with host and port properties
+ */
+function getDevHost() {
+  const hasHostFlag = process.argv.includes('--host')
+  let host = 'localhost'
+  let port = 4321
+
+  // Check for --port command line argument (e.g., astro dev --port 4322)
+  const portFlagIndex = process.argv.findIndex((arg) => arg === '--port')
+  if (portFlagIndex !== -1 && process.argv[portFlagIndex + 1]) {
+    const cliPort = parseInt(process.argv[portFlagIndex + 1], 10)
+    if (!isNaN(cliPort) && cliPort > 0 && cliPort < 65536) {
+      port = cliPort
+    }
+  }
+
+  // Check for PORT environment variable (most common way to override port)
+  if (process.env.PORT) {
+    const envPort = parseInt(process.env.PORT, 10)
+    if (!isNaN(envPort) && envPort > 0 && envPort < 65536) {
+      port = envPort
+    }
+  }
+
+  // Determine host based on --host flag
+  if (hasHostFlag) {
+    const interfaces = os.networkInterfaces()
+    for (const iface of Object.values(interfaces).flat()) {
+      if (iface?.family === 'IPv4' && !iface.internal) {
+        host = iface.address
+        break
+      }
+    }
+  }
+
+  return { host, port }
+}
+
+/**
+ * Determines the site URL based on environment and deployment context
+ * @returns {string} The appropriate site URL for the current environment
+ */
+export function getSiteUrl(config: any) {
+  // Check for explicit SITE_URL override first
+  if (process.env.SITE_URL) {
+    return process.env.SITE_URL
+  }
+
+  // Development: Local server with optional network access
+  if (process.env.NODE_ENV === 'development') {
+    const { host, port } = getDevHost()
+    return `http://${host}:${port}`
+  }
+
+  // Vercel Production: Live production deployment
+  if (process.env.VERCEL_ENV === 'production') {
+    return `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
+  }
+
+  // Vercel Preview: Branch deployments and previews
+  if (process.env.VERCEL_URL) {
+    return `https://${process.env.VERCEL_URL}`
+  }
+
+  // Fallback: Use baseURL from config.yml
+  return config.baseURL
+}

package/src/scss/_anchor.scss

@@ -0,0 +1,21 @@
+.anchor-link {
+  padding: 0 .175rem;
+  font-weight: 400;
+  color: rgba($link-main, .5);
+  text-decoration: none;
+  opacity: 0;
+  @include transition(color .15s ease-in-out, opacity .15s ease-in-out);
+
+  &::after {
+    content: "#";
+  }
+
+  &:focus,
+  &:hover,
+  :hover > &,
+  :target > & {
+    color: $link-main;
+    text-decoration: none;
+    opacity: 1;
+  }
+}

package/src/scss/_brand.scss

@@ -0,0 +1,59 @@
+//
+// Brand guidelines
+//
+
+// Logo series wrapper
+.cxd-brand-logos {
+  color: $cxd-subtle;
+
+  .inverse {
+    color: $white;
+    background-color: $cxd-subtle;
+  }
+}
+
+// Individual items
+.cxd-brand-item {
+  + .cxd-brand-item {
+    border-top: 1px solid var(--cx-border-color);
+  }
+
+  @include media-breakpoint-up(medium) {
+    + .cxd-brand-item {
+      border-top: 0;
+      border-left: 1px solid var(--cx-border-color);
+    }
+  }
+}
+
+//
+// Color swatches
+//
+
+.color-swatches {
+  margin: 0 -5px;
+
+  // Docs colors
+  .cxd-main {
+    background-color: $cxd-main;
+  }
+  .cxd-main-light {
+    background-color: $cxd-main-light;
+  }
+  .cxd-main-lighter {
+    background-color: #e5e1ea;
+  }
+  .cxd-gray {
+    background-color: #f9f9f9;
+  }
+}
+
+.color-swatch {
+  width: 4rem;
+  height: 4rem;
+
+  @include media-breakpoint-up(medium) {
+    width: 6rem;
+    height: 6rem;
+  }
+}

package/src/scss/_buttons.scss

@@ -0,0 +1,36 @@
+@import "@chassis-ui/css/scss/mixins/context";
+@import "@chassis-ui/css/scss/placeholders/context";
+@import "@chassis-ui/css/scss/placeholders/component";
+@import "@chassis-ui/css/scss/placeholders/button";
+// Buttons
+//
+// Custom buttons for the docs.
+
+// scss-docs-start cxd-button
+.cxd-button {
+
+  --#{$prefix}padding-y: var(--#{$prefix}space-3xsmall);
+  --#{$prefix}padding-x: var(--#{$prefix}space-large);
+  --#{$prefix}gap: var(--#{$prefix}space-small);
+  --#{$prefix}font-family: var(--#{$prefix}font-family-text);
+  --#{$prefix}font-size: var(--#{$prefix}font-size-large);
+  --#{$prefix}font-weight: var(--#{$prefix}font-weight-mass);
+  // --#{$prefix}line-height: var(--#{$prefix}line-height-large);
+  --#{$prefix}icon-size: var(--#{$prefix}icon-large);
+
+  display: inline-flex;
+  gap: var(--#{$prefix}gap);
+  align-items: center;
+  text-decoration: if($link-decoration == none, null, none);
+
+  @extend %button, %solid-button, %component, %box-padding;
+
+  &.large {
+    --#{$prefix}font-size: var(--#{$prefix}font-size-xlarge);
+    --#{$prefix}line-height: var(--#{$prefix}line-height-xlarge);
+    --#{$prefix}font-weight: var(--#{$prefix}font-weight-strong);
+    --#{$prefix}icon-size: var(--#{$prefix}icon-xlarge);
+  }
+
+}
+// scss-docs-end cxd-button

package/src/scss/_callouts.scss

@@ -0,0 +1,40 @@
+//
+// Callouts
+//
+
+.cxd-callout {
+  --#{$prefix}link-main-color-rgb: var(--cxd-callout-link);
+  --#{$prefix}code-color: var(--cxd-callout-code-color);
+
+  padding: 1.25rem;
+  margin-top: 1.25rem;
+  margin-bottom: 1.25rem;
+  color: var(--cxd-callout-color, inherit);
+  background-color: var(--cxd-callout-bg, var(--cx-gray-100));
+  border-left: .25rem solid var(--cxd-callout-border, var(--cx-gray-300));
+
+  h4 {
+    margin-bottom: .25rem;
+  }
+
+  > :last-child {
+    margin-bottom: 0;
+  }
+
+  + .cxd-callout {
+    margin-top: -.25rem;
+  }
+
+  .highlight {
+    background-color: rgba($black, .05);
+  }
+}
+
+// Variations
+@each $variant in $cxd-callout-variants {
+  .cxd-callout-#{$variant} {
+    --cxd-callout-color: var(--cx-#{$variant}-fg-main);
+    --cxd-callout-bg: var(--cx-#{$variant}-bg-even);
+    --cxd-callout-border: var(--cx-#{$variant}-border-subtle);
+  }
+}

package/src/scss/_clipboard-js.scss

@@ -0,0 +1,63 @@
+// clipboard.js
+//
+// JS-based `Copy` buttons for code snippets.
+
+.cxd-mode {
+  position: absolute;
+  top: 0;
+  right: 0;
+  z-index: 3;
+  margin-top: .75rem;
+  margin-right: .75rem;
+  .button-mode {
+    background-color: var(--cx-bg-idle);
+    border: var(--cx-border-width) solid var(--cx-border-subtle);
+  }
+  &:not(.cxd-example:hover &) {
+    display: none;
+  }
+}
+.cxd-clipboard,
+.cxd-edit {
+  position: relative;
+  display: none;
+  float: right;
+
+  + .highlight {
+    margin-top: 0;
+  }
+
+  @include media-breakpoint-up(medium) {
+    display: block;
+  }
+}
+
+.button-mode,
+.button-clipboard,
+.button-edit {
+  --cx-icon-color: var(--cx-fg-subtle);
+  --cx-icon-size: var(--cx-icon-small);
+  display: block;
+  padding: .5em .25em;
+  line-height: 1;
+  background-color: var(--cxd-pre-bg);
+  border: 0;
+  @include border-radius(.25rem);
+
+  &:hover {
+    color: var(--cx-hover-color);
+  }
+
+  &:focus {
+    z-index: 3;
+  }
+}
+
+.button-mode,
+.button-clipboard {
+  position: relative;
+  z-index: 2;
+  margin-top: .75rem;
+  margin-right: .75rem;
+}
+

package/src/scss/_code.scss

@@ -0,0 +1,116 @@
+//
+// Docs examples
+//
+
+.cxd-code-snippet {
+  //background-color: var(--cx-bg-evident);
+  margin: 0 ($cxd-gutter-x * -.5) 1rem;
+  border: solid var(--cx-border-subtle);
+  border-width: 1px 0;
+
+  @include media-breakpoint-up(medium) {
+    margin-right: 0;
+    margin-left: 0;
+    border-width: 1px;
+    @include border-radius(var(--cx-border-radius));
+  }
+}
+
+.cxd-example {
+
+  // background-color: var(--cx-bg-main);
+  --cxd-example-padding: 1rem;
+
+  position: relative;
+  padding: var(--cxd-example-padding);
+  margin: 0 ($cxd-gutter-x * -.5) 1rem;
+  border: solid var(--cx-border-subtle);
+  border-width: 1px 0;
+  @include clearfix();
+
+  @include media-breakpoint-up(medium) {
+    --cxd-example-padding: 1.5rem;
+
+    margin-right: 0;
+    margin-left: 0;
+    border-width: 1px;
+    @include border-radius(var(--cx-border-radius));
+    &:has(~ .highlight-toolbar) {
+      @include border-bottom-radius(0);
+    }
+  }
+
+  + p {
+    margin-top: 2rem;
+  }
+}
+
+//
+// Code snippets
+//
+
+.highlight {
+  position: relative;
+  padding: 1.25rem ($cxd-gutter-x * .5);
+  background-color: var(--cxd-pre-bg, var(--cx-bg-even));
+
+
+  @include media-breakpoint-up(medium) {
+    padding: 1.25rem;
+    @include border-radius(calc(var(--cx-border-radius) - 1px));
+  }
+
+  @include media-breakpoint-up(large) {
+    pre {
+      margin-right: 1.875rem;
+    }
+  }
+
+  pre {
+    // padding: .25rem 0 .875rem;
+    // margin-top: .8125rem;
+    margin-bottom: 0;
+    overflow: overlay;
+    @include font-size(var(--cx-font-size-code-small));
+    line-height: var(--cx-line-height-code-small);
+    white-space: pre;
+    background-color: transparent;
+    border: 0;
+  }
+
+  pre code {
+    color: var(--cx-fg-color); // Effectively the base text color
+    word-wrap: normal;
+  }
+}
+
+.cxd-example-snippet .highlight pre {
+  margin-right: 0;
+}
+
+.highlight-toolbar {
+  background-color: var(--cxd-pre-bg, var(--cx-bg-even));
+  border-top: var(--cx-border-width) var(--cx-border-style) var(--cx-border-subtle);
+  border-bottom: var(--cx-border-width) var(--cx-border-style) var(--cx-border-subtle);
+
+  + .highlight {
+    @include border-top-radius(0);
+  }
+
+  > a {
+    @include font-size(var(--cx-font-size-small));
+  }
+}
+
+.cxd-file-ref {
+  .highlight-toolbar {
+    border-top: 0;
+    @include media-breakpoint-up(medium) {
+      @include border-top-radius(calc(var(--cx-border-radius) - 1px));
+    }
+  }
+}
+
+.cxd-content .cxd-code-snippet {
+  margin-bottom: 1rem;
+}