@rimelight/ui 0.0.23 → 0.0.25

package/src/plugins/starlightDocsApi/extract-vue.ts

@@ -0,0 +1,286 @@
+import { readFileSync } from "node:fs"
+import ts from "typescript"
+import type { PropMeta, SlotMeta, EmitMeta } from "./types"
+
+function extractScriptBlock(content: string): string | null {
+  const match =
+    content.match(/<script[^>]*lang=["']ts["'][^>]*>([\s\S]*?)<\/script>/) ||
+    content.match(/<script[^>]*>([\s\S]*?)<\/script>/)
+  return match?.[1] ?? null
+}
+
+function extractTemplateBlock(content: string): string {
+  const match = content.match(/<template[^>]*>([\s\S]*?)<\/template>/)
+  return match?.[1] ?? ""
+}
+
+function getJSDocDescription(node: ts.Node): string {
+  const jsDocs = ts.getJSDocCommentsAndTags(node)
+  if (jsDocs.length === 0) return ""
+
+  const comment = jsDocs[0]
+  if (comment && ts.isJSDoc(comment)) {
+    const text = comment.comment
+    if (typeof text === "string") return text.trim()
+    if (Array.isArray(text))
+      return text
+        .map((t) => (typeof t === "string" ? t : t.text))
+        .join(" ")
+        .trim()
+  }
+  return ""
+}
+
+function extractPropsFromInterface(node: ts.InterfaceDeclaration): PropMeta[] {
+  const props: PropMeta[] = []
+  for (const member of node.members) {
+    if (ts.isPropertySignature(member) && member.name && ts.isIdentifier(member.name)) {
+      const propName = member.name.text
+      if (propName === "class" || propName.startsWith("data-")) continue
+      const type = member.type ? member.type.getText().replace(/^[^:]+:\s*/, "") : "unknown"
+      const isOptional = member.questionToken !== undefined
+      const description = getJSDocDescription(member)
+      props.push({ name: propName, type, required: !isOptional, description })
+    }
+  }
+  return props
+}
+
+function extractPropsFromTypeLiteral(
+  node: ts.TypeLiteralNode,
+  defaults?: Record<string, string>
+): PropMeta[] {
+  const props: PropMeta[] = []
+  for (const member of node.members) {
+    if (ts.isPropertySignature(member) && member.name && ts.isIdentifier(member.name)) {
+      const propName = member.name.text
+      if (propName === "class" || propName.startsWith("data-")) continue
+      const type = member.type ? member.type.getText().replace(/^[^:]+:\s*/, "") : "unknown"
+      const isOptional = member.questionToken !== undefined
+      const defaultVal = defaults?.[propName]
+      const prop: PropMeta = { name: propName, type, required: !isOptional, description: "" }
+      if (defaultVal !== undefined) prop.default = defaultVal
+      props.push(prop)
+    }
+  }
+  return props
+}
+
+function getTypeRefName(typeArg: ts.TypeNode): string | null {
+  if (ts.isTypeReferenceNode(typeArg) && ts.isIdentifier(typeArg.typeName)) {
+    return typeArg.typeName.text
+  }
+  return null
+}
+
+export function extractVueMetaDirect(filePath: string): {
+  props: PropMeta[]
+  slots: SlotMeta[]
+  emits: EmitMeta[]
+} {
+  const content = readFileSync(filePath, "utf-8")
+  const scriptContent = extractScriptBlock(content)
+
+  const props: PropMeta[] = []
+  const slots: SlotMeta[] = []
+  const emits: EmitMeta[] = []
+
+  if (scriptContent) {
+    const sourceFile = ts.createSourceFile(
+      "component.ts",
+      scriptContent,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TS
+    )
+
+    const interfaces = new Map<string, ts.InterfaceDeclaration>()
+    const destructuredDefaults: Record<string, string> = {}
+
+    function collectDeclarations(node: ts.Node) {
+      if (ts.isInterfaceDeclaration(node)) {
+        interfaces.set(node.name.text, node)
+      }
+      if (ts.isVariableStatement(node)) {
+        for (const decl of node.declarationList.declarations) {
+          if (
+            decl.initializer &&
+            ts.isCallExpression(decl.initializer) &&
+            ts.isObjectBindingPattern(decl.name)
+          ) {
+            const expr = decl.initializer.expression
+            const fnName = ts.isIdentifier(expr) ? expr.text : ""
+            if (fnName === "defineProps") {
+              for (const element of decl.name.elements) {
+                if (
+                  ts.isBindingElement(element) &&
+                  ts.isIdentifier(element.name) &&
+                  element.initializer
+                ) {
+                  destructuredDefaults[element.name.text] = element.initializer.getText()
+                }
+              }
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, collectDeclarations)
+    }
+    collectDeclarations(sourceFile)
+
+    function visit(node: ts.Node) {
+      if (ts.isCallExpression(node)) {
+        const expr = node.expression
+        const fnName = ts.isIdentifier(expr) ? expr.text : ""
+
+        if (fnName === "defineProps") {
+          if (node.typeArguments && node.typeArguments.length > 0) {
+            const typeArg = node.typeArguments[0]!
+            const refName = getTypeRefName(typeArg)
+            if (refName) {
+              const iface = interfaces.get(refName)
+              if (iface) {
+                const extracted = extractPropsFromInterface(iface)
+                for (const p of extracted) {
+                  const d = destructuredDefaults[p.name]
+                  if (d !== undefined) p.default = d
+                }
+                props.push(...extracted)
+              }
+            } else if (ts.isTypeLiteralNode(typeArg)) {
+              props.push(...extractPropsFromTypeLiteral(typeArg))
+            }
+          } else if (node.arguments.length > 0) {
+            const arg = node.arguments[0]!
+            if (ts.isTypeLiteralNode(arg)) {
+              props.push(...extractPropsFromTypeLiteral(arg))
+            }
+          }
+        }
+
+        if (fnName === "withDefaults" && node.arguments.length > 0) {
+          const callArg = node.arguments[0]!
+          if (ts.isCallExpression(callArg)) {
+            const innerFn = ts.isIdentifier(callArg.expression) ? callArg.expression.text : ""
+            if (innerFn === "defineProps") {
+              const defaultsObj = node.arguments[1]!
+              const defaults: Record<string, string> = {}
+              if (ts.isObjectLiteralExpression(defaultsObj)) {
+                for (const prop of defaultsObj.properties) {
+                  if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                    defaults[prop.name.text] = prop.initializer.getText()
+                  }
+                }
+              }
+
+              if (callArg.typeArguments && callArg.typeArguments.length > 0) {
+                const typeArg = callArg.typeArguments[0]!
+                const refName = getTypeRefName(typeArg)
+                if (refName) {
+                  const iface = interfaces.get(refName)
+                  if (iface) {
+                    const baseProps = extractPropsFromInterface(iface)
+                    for (const p of baseProps) {
+                      const d = defaults[p.name]
+                      if (d !== undefined) p.default = d
+                    }
+                    props.push(...baseProps)
+                  }
+                } else if (ts.isTypeLiteralNode(typeArg)) {
+                  props.push(...extractPropsFromTypeLiteral(typeArg, defaults))
+                }
+              } else if (callArg.arguments.length > 0) {
+                const arg = callArg.arguments[0]!
+                if (ts.isTypeLiteralNode(arg)) {
+                  props.push(...extractPropsFromTypeLiteral(arg, defaults))
+                }
+              }
+            }
+          }
+        }
+
+        if (fnName === "defineSlots") {
+          const typeArg = node.typeArguments?.[0]
+          if (typeArg && ts.isTypeLiteralNode(typeArg)) {
+            for (const member of typeArg.members) {
+              if (ts.isMethodSignature(member) && member.name && ts.isIdentifier(member.name)) {
+                const slotName = member.name.text
+                const bindings: Record<string, string> = {}
+                if (member.parameters.length > 0) {
+                  const param = member.parameters[0]
+                  if (param?.type) {
+                    const typeText = param.type.getText()
+                    bindings["props"] = typeText
+                  }
+                }
+                slots.push({ name: slotName, bindings, description: "" })
+              }
+            }
+          }
+        }
+
+        if (fnName === "defineEmits") {
+          const typeArg = node.typeArguments?.[0]
+          const runtimeArg = node.arguments?.[0]
+
+          if (typeArg && ts.isTypeLiteralNode(typeArg)) {
+            for (const member of typeArg.members) {
+              if (
+                ts.isPropertySignature(member) &&
+                member.name &&
+                ts.isIdentifier(member.name) &&
+                member.type
+              ) {
+                const emitName = member.name.text
+                let payloadType = "void"
+                if (ts.isFunctionTypeNode(member.type) && member.type.parameters.length > 0) {
+                  const param = member.type.parameters[0]
+                  if (param?.type) {
+                    payloadType = param.type.getText()
+                  }
+                }
+                emits.push({ name: emitName, type: payloadType, description: "" })
+              }
+            }
+          } else if (runtimeArg && ts.isTypeLiteralNode(runtimeArg)) {
+            for (const member of runtimeArg.members) {
+              if (
+                ts.isPropertySignature(member) &&
+                member.name &&
+                ts.isIdentifier(member.name) &&
+                member.type
+              ) {
+                const emitName = member.name.text
+                let payloadType = "void"
+                if (ts.isFunctionTypeNode(member.type) && member.type.parameters.length > 0) {
+                  const param = member.type.parameters[0]
+                  if (param?.type) {
+                    payloadType = param.type.getText()
+                  }
+                }
+                emits.push({ name: emitName, type: payloadType, description: "" })
+              }
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+
+    visit(sourceFile)
+  }
+
+  const templateContent = extractTemplateBlock(content)
+  const slotMatches = templateContent.matchAll(/<slot(?:\s+name=["']([^"']+)["'])?/g)
+  for (const match of slotMatches) {
+    const slotName = match[1] ?? "default"
+    if (!slots.some((s) => s.name === slotName)) {
+      slots.push({ name: slotName, bindings: {}, description: "" })
+    }
+  }
+  if (!slots.length) {
+    slots.push({ name: "default", bindings: {}, description: "" })
+  }
+
+  return { props, slots, emits }
+}

package/src/plugins/starlightDocsApi/index.ts

@@ -0,0 +1,265 @@
+import type { AstroIntegration } from "astro"
+import virtual from "vite-plugin-virtual"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { readFileSync, existsSync, readdirSync } from "node:fs"
+import ts from "typescript"
+import type { ComponentMeta, PropMeta, SlotMeta, EmitMeta, ThemeMeta } from "./types"
+import { extractVueMetaDirect } from "./extract-vue"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const uiRoot = path.resolve(__dirname, "..", "..", "..")
+
+function pascalToKebab(name: string): string {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()
+}
+
+function extractAstroPropsFromInterface(sourceFile: ts.SourceFile): PropMeta[] {
+  const props: PropMeta[] = []
+
+  function visit(node: ts.Node) {
+    if (
+      (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) &&
+      node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+    ) {
+      const name = node.name.text
+      if (name.endsWith("Props") || name === "Props") {
+        if (ts.isInterfaceDeclaration(node)) {
+          for (const member of node.members) {
+            if (ts.isPropertySignature(member) && member.name && ts.isIdentifier(member.name)) {
+              const propName = member.name.text
+              if (propName === "class" || propName.startsWith("data-")) continue
+              const type = member.type ? member.type.getText().replace(/^[^:]+:\s*/, "") : "unknown"
+              const isOptional = member.questionToken !== undefined
+              props.push({ name: propName, type, required: !isOptional, description: "" })
+            }
+          }
+        } else if (ts.isTypeAliasDeclaration(node) && ts.isTypeLiteralNode(node.type)) {
+          for (const member of node.type.members) {
+            if (ts.isPropertySignature(member) && member.name && ts.isIdentifier(member.name)) {
+              const propName = member.name.text
+              if (propName === "class" || propName.startsWith("data-")) continue
+              const type = member.type ? member.type.getText().replace(/^[^:]+:\s*/, "") : "unknown"
+              const isOptional = member.questionToken !== undefined
+              props.push({ name: propName, type, required: !isOptional, description: "" })
+            }
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+
+  visit(sourceFile)
+  return props
+}
+
+function extractAstroMeta(filePath: string): { props: PropMeta[]; slots: SlotMeta[] } {
+  const content = readFileSync(filePath, "utf-8")
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/)
+  if (!frontmatterMatch) return { props: [], slots: [] }
+
+  const frontmatter = frontmatterMatch[1]
+  const sourceFile = ts.createSourceFile(
+    "component.ts",
+    frontmatter ?? "",
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  )
+
+  const props = extractAstroPropsFromInterface(sourceFile)
+
+  const slots: SlotMeta[] = []
+  const slotMatches = content.matchAll(/<slot(?:\s+name=["']([^"']+)["'])?/g)
+  for (const match of slotMatches) {
+    slots.push({ name: match[1] ?? "default", bindings: {}, description: "" })
+  }
+  if (!slots.length) slots.push({ name: "default", bindings: {}, description: "" })
+
+  return { props, slots }
+}
+
+function safeParse(code: string): unknown {
+  try {
+    const normalized = code
+      .replace(/'/g, '"')
+      .replace(/,\s*\}/g, "}")
+      .replace(/,\s*\]/g, "]")
+    return JSON.parse(normalized)
+  } catch {
+    return {}
+  }
+}
+
+function isStringOrArray(value: unknown): value is string | string[] {
+  return typeof value === "string" || Array.isArray(value)
+}
+
+function isStringRecord(value: unknown): value is Record<string, string | string[]> {
+  if (typeof value !== "object" || value === null) return false
+  return Object.values(value).every(isStringOrArray)
+}
+
+function isVariantRecord(
+  value: unknown
+): value is Record<string, Record<string, Record<string, string | string[]>>> {
+  if (typeof value !== "object" || value === null) return false
+  return Object.values(value).every(
+    (v) => typeof v === "object" && v !== null && Object.values(v).every(isStringRecord)
+  )
+}
+
+function isCompoundArray(value: unknown): value is Record<string, unknown>[] {
+  return Array.isArray(value) && value.every((v) => typeof v === "object" && v !== null)
+}
+
+function isDefaultVariants(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}
+
+function extractThemeMeta(componentName: string, themesDir: string): ThemeMeta | null {
+  if (!existsSync(themesDir)) return null
+
+  const themeFiles = readdirSync(themesDir).filter((f) => f.endsWith(".theme.ts"))
+  let themePath: string | null = null
+  for (const file of themeFiles) {
+    const baseName = file.replace(".theme.ts", "")
+    if (baseName === componentName.toLowerCase()) {
+      themePath = path.join(themesDir, file)
+      break
+    }
+  }
+
+  if (!themePath || !existsSync(themePath)) return null
+
+  const content = readFileSync(themePath, "utf-8")
+  const slotsMatch = content.match(/slots:\s*\[([^\]]*)\]/)
+  const baseMatch = content.match(/base:\s*(\{[\s\S]*?\n[ \t]*\})/)
+  const variantsMatch = content.match(/variants:\s*(\{[\s\S]*?\n[ \t]*\})/)
+  const compoundMatch = content.match(/compoundVariants:\s*(\[[\s\S]*?\n[ \t]*\])/)
+  const defaultVariantsMatch = content.match(/defaultVariants:\s*(\{[\s\S]*?\n[ \t]*\})/)
+
+  const slots = slotsMatch
+    ? slotsMatch[1]!
+        .split(",")
+        .map((s) => s.trim().replace(/["']/g, ""))
+        .filter(Boolean)
+    : []
+
+  const parsedBase = baseMatch ? safeParse(baseMatch[1]!) : {}
+  const parsedVariants = variantsMatch ? safeParse(variantsMatch[1]!) : {}
+  const parsedCompound = compoundMatch ? safeParse(compoundMatch[1]!) : []
+  const parsedDefaults = defaultVariantsMatch ? safeParse(defaultVariantsMatch[1]!) : {}
+
+  return {
+    slots,
+    base: isStringRecord(parsedBase) ? parsedBase : {},
+    variants: isVariantRecord(parsedVariants) ? parsedVariants : {},
+    compoundVariants: isCompoundArray(parsedCompound) ? parsedCompound : [],
+    defaultVariants: isDefaultVariants(parsedDefaults) ? parsedDefaults : {}
+  }
+}
+
+function getComponentNameFromFilename(filename: string): string {
+  return filename.replace(/^(RLA|RLV)/, "").replace(/\.(astro|vue)$/, "")
+}
+
+function extractAllMeta(): Record<string, ComponentMeta> {
+  const componentsDir = path.join(uiRoot, "src", "components")
+  const themesDir = path.join(uiRoot, "src", "themes")
+
+  const vueDir = path.join(componentsDir, "vue")
+  const astroDir = path.join(componentsDir, "astro")
+
+  const vueFiles = existsSync(vueDir)
+    ? readdirSync(vueDir).filter((f: string) => f.endsWith(".vue"))
+    : []
+  const astroFiles = existsSync(astroDir)
+    ? readdirSync(astroDir).filter((f: string) => f.endsWith(".astro") && f !== "Head.astro")
+    : []
+
+  const vueComponents = new Map<string, string>()
+  const astroComponents = new Map<string, string>()
+
+  for (const f of vueFiles) vueComponents.set(getComponentNameFromFilename(f), f)
+  for (const f of astroFiles) astroComponents.set(getComponentNameFromFilename(f), f)
+
+  const allNames = new Set([...vueComponents.keys(), ...astroComponents.keys()])
+  const result: Record<string, ComponentMeta> = {}
+
+  for (const name of [...allNames].toSorted()) {
+    const vueFile = vueComponents.get(name)
+    const astroFile = astroComponents.get(name)
+
+    let props: PropMeta[] = []
+    let slots: SlotMeta[] = []
+    let emits: EmitMeta[] = []
+    const frameworks: ("astro" | "vue")[] = []
+
+    if (vueFile) {
+      frameworks.push("vue")
+      try {
+        const vueMeta = extractVueMetaDirect(path.join(vueDir, vueFile))
+        props = vueMeta.props
+        slots = vueMeta.slots
+        emits = vueMeta.emits
+      } catch (err) {
+        console.warn(`[starlightDocsApi] Failed to extract Vue meta for ${vueFile}:`, err)
+      }
+    }
+
+    if (astroFile) {
+      frameworks.push("astro")
+      if (!vueFile) {
+        try {
+          const astroMeta = extractAstroMeta(path.join(astroDir, astroFile))
+          props = astroMeta.props
+          slots = astroMeta.slots
+        } catch (err) {
+          console.warn(`[starlightDocsApi] Failed to extract Astro meta for ${astroFile}:`, err)
+        }
+      }
+    }
+
+    const theme = extractThemeMeta(name, themesDir)
+
+    result[pascalToKebab(name)] = {
+      name,
+      astroComponent: astroFile ?? null,
+      vueComponent: vueFile ?? null,
+      frameworks,
+      props,
+      slots,
+      emits,
+      theme
+    }
+  }
+
+  return result
+}
+
+export interface StarlightDocsApiConfig {}
+
+export default function starlightDocsApi(_config?: StarlightDocsApiConfig): AstroIntegration {
+  return {
+    name: "rimelight-ui-starlight-docs-api",
+    hooks: {
+      "astro:config:setup": ({ updateConfig, logger }) => {
+        logger.info("Initializing @rimelight/ui docs API")
+
+        const meta = extractAllMeta()
+
+        updateConfig({
+          vite: {
+            plugins: [
+              virtual({
+                "virtual:rimelight-ui-docs-meta": `export default ${JSON.stringify(meta)}`
+              })
+            ]
+          }
+        } as Record<string, unknown>)
+      }
+    }
+  }
+}

package/src/plugins/starlightDocsApi/types.ts

@@ -0,0 +1,40 @@
+export interface PropMeta {
+  name: string
+  type: string
+  default?: string
+  required: boolean
+  description: string
+}
+
+export interface SlotMeta {
+  name: string
+  bindings: Record<string, string>
+  description: string
+}
+
+export interface EmitMeta {
+  name: string
+  type: string
+  description: string
+}
+
+export interface ThemeMeta {
+  slots: string[]
+  base: Record<string, string | string[]>
+  variants: Record<string, Record<string, Record<string, string | string[]>>>
+  compoundVariants: Record<string, unknown>[]
+  defaultVariants: Record<string, unknown>
+}
+
+export interface ComponentMeta {
+  name: string
+  astroComponent: string | null
+  vueComponent: string | null
+  frameworks: ("astro" | "vue")[]
+  props: PropMeta[]
+  slots: SlotMeta[]
+  emits: EmitMeta[]
+  theme: ThemeMeta | null
+}
+
+export type ComponentMetaMap = Record<string, ComponentMeta>

package/src/plugins/starlightDocsApi/utils.ts

@@ -0,0 +1,45 @@
+import type { PropMeta, ThemeMeta } from "./types"
+
+export function kebabToPascal(name: string): string {
+  return name
+    .split("-")
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join("")
+}
+
+export function filterProps(
+  props: PropMeta[],
+  options: { hide?: string[]; show?: string[] }
+): PropMeta[] {
+  if (options.show?.length) {
+    return props.filter((p) => options.show!.includes(p.name))
+  }
+  if (options.hide?.length) {
+    return props.filter((p) => !options.hide!.includes(p.name))
+  }
+  return props
+}
+
+export function generateThemeCode(componentName: string, theme: ThemeMeta): string {
+  const componentConfig: Record<string, unknown> = {
+    ...(theme.slots.length ? { slots: theme.slots } : {}),
+    ...(Object.keys(theme.base).length ? { base: theme.base } : {}),
+    ...(Object.keys(theme.variants).length ? { variants: theme.variants } : {}),
+    ...(theme.compoundVariants.length ? { compoundVariants: theme.compoundVariants } : {}),
+    ...(Object.keys(theme.defaultVariants).length ? { defaultVariants: theme.defaultVariants } : {})
+  }
+
+  return `// astro.config.ts
+import { ui } from "@rimelight/ui"
+import { defineConfig } from "astro/config"
+
+export default defineConfig({
+  integrations: [
+    ui({
+      components: {
+        ${componentName}: ${JSON.stringify(componentConfig, null, 6).replace(/\n/g, "\n        ")}
+      }
+    })
+  ]
+})`
+}