@nshipster/sosumi 1.0.0

package/src/lib/hig/render.ts

@@ -0,0 +1,514 @@
+/**
+ * Human Interface Guidelines (HIG) rendering functionality
+ */
+
+import { extractTitleFromIdentifier } from "../reference/render"
+import type { ContentItem, TextFragment } from "../types"
+import type {
+  HIGExternalReference,
+  HIGImageReference,
+  HIGPageJSON,
+  HIGReference,
+  HIGTableOfContents,
+  HIGTocItem,
+  HIGTopicSection,
+} from "./types"
+import { isHIGImageReference } from "./util"
+
+// ============================================================================
+// RENDERING FUNCTIONS
+// ============================================================================
+
+/**
+ * Render HIG page JSON to markdown
+ */
+export async function renderHIGFromJSON(jsonData: HIGPageJSON, sourceUrl: string): Promise<string> {
+  let markdown = ""
+
+  // Generate front matter
+  markdown += generateHIGFrontMatter(jsonData, sourceUrl)
+
+  // Add navigation breadcrumbs for HIG
+  const breadcrumbs = generateHIGBreadcrumbs(sourceUrl)
+  if (breadcrumbs) {
+    markdown += breadcrumbs
+  }
+
+  // Add role heading if available
+  if (jsonData.metadata?.role) {
+    const roleDisplay =
+      jsonData.metadata.role === "collectionGroup" ? "Guide Collection" : jsonData.metadata.role
+    markdown += `**${roleDisplay}**\n\n`
+  }
+
+  // Add title
+  const title = jsonData.metadata?.title || ""
+  if (title) {
+    markdown += `# ${title}\n\n`
+  }
+
+  // Add abstract
+  if (jsonData.abstract && Array.isArray(jsonData.abstract)) {
+    const abstractText = jsonData.abstract
+      .filter((item: TextFragment) => item.type === "text")
+      .map((item: TextFragment) => item.text)
+      .join("")
+
+    if (abstractText.trim()) {
+      markdown += `> ${abstractText}\n\n`
+    }
+  }
+
+  // Add primary content sections
+  if (jsonData.primaryContentSections) {
+    for (const section of jsonData.primaryContentSections) {
+      if (section.kind === "content" && section.content) {
+        markdown += renderHIGContent(section.content, jsonData.references)
+      }
+    }
+  }
+
+  // Add regular content sections
+  if (jsonData.sections && jsonData.sections.length > 0) {
+    markdown += renderHIGContent(jsonData.sections, jsonData.references)
+  }
+
+  // Add topic sections (unless hidden)
+  if (jsonData.topicSections && jsonData.topicSectionsStyle !== "hidden") {
+    markdown += renderHIGTopicSections(jsonData.topicSections, jsonData.references)
+  }
+
+  // Trim whitespace
+  markdown = markdown.trim()
+
+  // Add footer
+  markdown += `\n\n---\n\n`
+  markdown += `*Extracted by [sosumi.ai](https://sosumi.ai) - Making Apple docs AI-readable.*\n`
+  markdown += `*This is unofficial content. All Human Interface Guidelines belong to Apple Inc.*\n`
+
+  return markdown
+}
+
+/**
+ * Render HIG table of contents to markdown
+ */
+export async function renderHIGTableOfContents(tocData: HIGTableOfContents): Promise<string> {
+  let markdown = ""
+
+  // Generate front matter
+  markdown += `---\n`
+  markdown += `title: Human Interface Guidelines\n`
+  markdown += `description: Apple's Human Interface Guidelines - Complete table of contents\n`
+  markdown += `source: https://developer.apple.com/design/human-interface-guidelines/\n`
+  markdown += `timestamp: ${new Date().toISOString()}\n`
+  markdown += `---\n\n`
+
+  // Add title and introduction
+  markdown += `# Human Interface Guidelines\n\n`
+  markdown += `> Apple's comprehensive guide to designing interfaces for all Apple platforms.\n\n`
+
+  // Render the table of contents
+  if (tocData.interfaceLanguages?.swift) {
+    markdown += renderHIGTocItems(tocData.interfaceLanguages.swift, 2)
+  }
+
+  // Add footer
+  markdown += `\n\n---\n\n`
+  markdown += `*Extracted by [sosumi.ai](https://sosumi.ai) - Making Apple docs AI-readable.*\n`
+  markdown += `*This is unofficial content. All Human Interface Guidelines belong to Apple Inc.*\n`
+
+  return markdown
+}
+
+// ============================================================================
+// PRIVATE HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Generate front matter for HIG pages
+ */
+function generateHIGFrontMatter(jsonData: HIGPageJSON, sourceUrl: string): string {
+  const frontMatter: Record<string, string> = {}
+
+  if (jsonData.metadata?.title) {
+    frontMatter.title = jsonData.metadata.title
+  }
+
+  if (jsonData.abstract && Array.isArray(jsonData.abstract)) {
+    const description = jsonData.abstract
+      .filter((item: TextFragment) => item.type === "text")
+      .map((item: TextFragment) => item.text)
+      .join("")
+      .trim()
+    if (description) {
+      frontMatter.description = description
+    }
+  }
+
+  frontMatter.source = sourceUrl
+  frontMatter.timestamp = new Date().toISOString()
+
+  // Convert to YAML format
+  const yamlLines = Object.entries(frontMatter).map(([key, value]) => `${key}: ${value}`)
+  return `---\n${yamlLines.join("\n")}\n---\n\n`
+}
+
+/**
+ * Generate breadcrumb navigation for HIG
+ */
+function generateHIGBreadcrumbs(sourceUrl: string): string {
+  const url = new URL(sourceUrl)
+  const pathParts = url.pathname.split("/").filter(Boolean)
+  // pathParts will be: ["design", "human-interface-guidelines", "foundations", "color"] for foundations/color
+
+  if (pathParts.length < 3) return "" // Need at least /design/human-interface-guidelines
+
+  let breadcrumbs = `**Navigation:** [Human Interface Guidelines](/design/human-interface-guidelines)`
+
+  // Add breadcrumbs for all parts after /design/human-interface-guidelines
+  // This includes both intermediate and final parts
+  for (let i = 3; i < pathParts.length; i++) {
+    const part = pathParts[i]
+    // Build path up to this point
+    const path = `/${pathParts.slice(0, i + 1).join("/")}`
+    const formattedPart = part.replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase())
+    breadcrumbs += ` › [${formattedPart}](${path})`
+  }
+
+  return `${breadcrumbs}\n\n`
+}
+
+/**
+ * Render HIG content items
+ */
+function renderHIGContent(
+  content: ContentItem[],
+  references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+): string {
+  let markdown = ""
+
+  for (const item of content) {
+    if (item.type === "links" && item.items && item.style === "compactGrid") {
+      // Handle the special case of link grids (like on the getting started page)
+      for (const linkId of item.items) {
+        if (typeof linkId === "string") {
+          const reference = references[linkId]
+          if (reference && !isHIGImageReference(reference)) {
+            const title = reference.title || "Untitled"
+            const url = reference.url || "#"
+            const refAbstract = (reference as HIGReference).abstract
+            const abstract = Array.isArray(refAbstract)
+              ? refAbstract.map((a: TextFragment) => a.text).join("")
+              : ""
+
+            markdown += `- [${title}](${url})`
+            if (abstract) {
+              markdown += ` - ${abstract}`
+            }
+            markdown += "\n"
+          }
+        }
+      }
+      markdown += "\n"
+    } else {
+      // Handle other content types using the existing content renderer
+      markdown += renderContentItem(item, references)
+    }
+  }
+
+  return markdown
+}
+
+/**
+ * Render individual content item
+ */
+function renderContentItem(
+  item: ContentItem,
+  references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+): string {
+  let markdown = ""
+
+  if (item.type === "heading") {
+    const level = Math.min(item.level || 2, 6)
+    const hashes = "#".repeat(level)
+    markdown += `${hashes} ${item.text}\n\n`
+  } else if (item.type === "paragraph") {
+    if (item.inlineContent) {
+      const text = renderHIGInlineContent(item.inlineContent, references)
+      markdown += `${text}\n\n`
+    }
+  } else if (item.type === "codeListing") {
+    let code = ""
+    if (Array.isArray(item.code)) {
+      code = item.code.join("\n")
+    } else {
+      code = String(item.code || "")
+    }
+    const syntax = item.syntax || "swift"
+    markdown += `\`\`\`${syntax}\n${code}\n\`\`\`\n\n`
+  } else if (item.type === "unorderedList" && item.items) {
+    for (const listItem of item.items) {
+      const itemText = renderHIGContent(listItem.content || [], references)
+      markdown += `- ${itemText.replace(/\n\n$/, "")}\n`
+    }
+    markdown += "\n"
+  } else if (item.type === "orderedList" && item.items) {
+    item.items.forEach((listItem: ContentItem, index: number) => {
+      const itemText = renderHIGContent(listItem.content || [], references)
+      markdown += `${index + 1}. ${itemText.replace(/\n\n$/, "")}\n`
+    })
+    markdown += "\n"
+  } else if (item.type === "table") {
+    markdown += renderHIGTable(item, references)
+  } else if (item.type === "aside") {
+    markdown += renderHIGAside(item, references)
+  } else if (item.type === "row") {
+    markdown += renderHIGRow(item, references)
+  } else if (item.type === "video") {
+    markdown += renderHIGVideo(item, references)
+  }
+
+  return markdown
+}
+
+/**
+ * Render a HIG table to markdown.
+ * HIG tables use header: "row" and rows[rowIndex][cellIndex] = ContentItem[].
+ */
+function renderHIGTable(
+  item: ContentItem,
+  references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+): string {
+  const table = item as ContentItem & {
+    header?: string
+    rows?: ContentItem[][][]
+  }
+  const rows = table.rows ?? []
+  if (rows.length === 0) return ""
+
+  const escapeCell = (s: string) => s.replace(/\|/g, "\\|").replace(/\n/g, " ").trim()
+  const renderCell = (cell: ContentItem | ContentItem[]) => {
+    const items = Array.isArray(cell) ? cell : [cell]
+    const text = renderHIGContent(items, references)
+    return escapeCell(text)
+  }
+
+  const firstRowIsHeader = table.header === "row"
+  let markdown = ""
+
+  rows.forEach((row, rowIndex) => {
+    const cells = row.map((cell) => renderCell(cell))
+    if (cells.length === 0) return
+    markdown += `| ${cells.join(" | ")} |\n`
+    if (firstRowIsHeader && rowIndex === 0) {
+      markdown += `| ${cells.map(() => "---").join(" | ")} |\n`
+    }
+  })
+
+  return markdown ? `${markdown}\n` : ""
+}
+
+/**
+ * Render a HIG aside/callout block to markdown.
+ */
+function renderHIGAside(
+  item: ContentItem,
+  references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+): string {
+  const aside = item as ContentItem & { style?: string; name?: string }
+  const rawType = (aside.style || aside.name || "note").toLowerCase()
+  const calloutType = mapHIGAsideStyleToCallout(rawType)
+  const asideContent = item.content ? renderHIGContent(item.content, references) : ""
+  const cleanContent = asideContent.trim().replace(/\n/g, "\n> ")
+  if (!cleanContent) return ""
+  return `> [!${calloutType}]\n> ${cleanContent}\n\n`
+}
+
+/**
+ * Render a HIG row block by rendering each column content in order.
+ */
+function renderHIGRow(
+  item: ContentItem,
+  references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+): string {
+  const row = item as ContentItem & {
+    columns?: Array<{
+      content?: ContentItem[]
+    }>
+  }
+  if (!row.columns || row.columns.length === 0) return ""
+
+  let markdown = ""
+  for (const column of row.columns) {
+    if (column.content && column.content.length > 0) {
+      markdown += renderHIGContent(column.content, references)
+    }
+  }
+  return markdown
+}
+
+/**
+ * Render a HIG video block as a markdown link.
+ */
+function renderHIGVideo(
+  item: ContentItem,
+  references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+): string {
+  const video = item as ContentItem & {
+    identifier?: string
+    metadata?: {
+      abstract?: TextFragment[]
+    }
+  }
+  if (!video.identifier) return ""
+
+  const reference = references[video.identifier] as
+    | {
+        type?: string
+        alt?: string
+        variants?: Array<{ url?: string }>
+      }
+    | undefined
+
+  const videoUrl = reference?.variants?.[0]?.url
+  if (!videoUrl) return ""
+
+  const abstractText = (video.metadata?.abstract ?? [])
+    .filter((fragment) => fragment.type === "text")
+    .map((fragment) => fragment.text)
+    .join("")
+    .trim()
+  const label = abstractText || reference?.alt || "Video"
+
+  return `[${label}](${videoUrl})\n\n`
+}
+
+/**
+ * Render HIG inline content
+ */
+function renderHIGInlineContent(
+  inlineContent: ContentItem[],
+  references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+): string {
+  return inlineContent
+    .map((item) => {
+      if (item.type === "text") {
+        return item.text
+      } else if (item.type === "codeVoice") {
+        return `\`${item.code}\``
+      } else if (item.type === "reference") {
+        const reference = item.identifier ? references[item.identifier] : undefined
+        const refTitle =
+          reference && !isHIGImageReference(reference)
+            ? (reference as HIGReference | HIGExternalReference).title
+            : undefined
+        const title =
+          item.title ||
+          item.text ||
+          refTitle ||
+          (item.identifier ? extractTitleFromIdentifier(item.identifier) : "")
+        const url = reference ? (isHIGImageReference(reference) ? "#" : reference.url) : "#"
+        return `[${title}](${url})`
+      } else if (item.type === "emphasis") {
+        return `*${
+          item.inlineContent ? renderHIGInlineContent(item.inlineContent, references) : ""
+        }*`
+      } else if (item.type === "strong") {
+        return `**${
+          item.inlineContent ? renderHIGInlineContent(item.inlineContent, references) : ""
+        }**`
+      } else if (item.type === "image" && item.identifier) {
+        const reference = references[item.identifier]
+        if (reference && isHIGImageReference(reference)) {
+          const imageUrl = reference.variants?.[0]?.url
+          if (imageUrl) {
+            return `![${reference.alt ?? ""}](${imageUrl})`
+          }
+        }
+        return ""
+      }
+      return item.text || ""
+    })
+    .join("")
+}
+
+/**
+ * Render HIG topic sections
+ */
+function renderHIGTopicSections(
+  topicSections: HIGTopicSection[],
+  references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+): string {
+  let markdown = ""
+
+  for (const section of topicSections) {
+    if (section.title) {
+      markdown += `## ${section.title}\n\n`
+    }
+
+    if (section.identifiers) {
+      for (const id of section.identifiers) {
+        const reference = references[id]
+        if (reference && !isHIGImageReference(reference)) {
+          const title = reference.title || "Untitled"
+          const url = reference.url || "#"
+          const refAbstract = (reference as HIGReference).abstract
+          const abstract = Array.isArray(refAbstract)
+            ? refAbstract.map((a: TextFragment) => a.text).join("")
+            : ""
+
+          markdown += `- [${title}](${url})`
+          if (abstract) {
+            markdown += ` - ${abstract}`
+          }
+          markdown += "\n"
+        }
+      }
+      markdown += "\n"
+    }
+  }
+
+  return markdown
+}
+
+function mapHIGAsideStyleToCallout(style: string): string {
+  switch (style.toLowerCase()) {
+    case "warning":
+      return "WARNING"
+    case "important":
+      return "IMPORTANT"
+    case "caution":
+      return "CAUTION"
+    case "tip":
+      return "TIP"
+    case "deprecated":
+      return "WARNING"
+    default:
+      return "NOTE"
+  }
+}
+
+/**
+ * Render HIG table of contents items
+ */
+function renderHIGTocItems(items: HIGTocItem[], headingLevel: number): string {
+  let markdown = ""
+
+  for (const item of items) {
+    if (item.type === "module" || item.type === "symbol") {
+      // Main sections get headings
+      const hashes = "#".repeat(Math.min(headingLevel, 6))
+      markdown += `${hashes} ${item.title}\n\n`
+
+      if (item.children) {
+        markdown += renderHIGTocItems(item.children, headingLevel + 1)
+      }
+    } else if (item.type === "article") {
+      // Articles get listed as links
+      const url = item.path
+      markdown += `- [${item.title}](${url})\n`
+    }
+  }
+
+  return markdown
+}

package/src/lib/hig/types.ts

@@ -0,0 +1,206 @@
+/**
+ * Human Interface Guidelines (HIG) specific types
+ */
+
+import type { ContentItem, PrimaryContentSection, TextFragment } from "../types"
+
+// ============================================================================
+// HIG TYPES
+// ============================================================================
+
+/**
+ * Represents an icon reference in the HIG ToC
+ */
+export interface HIGIconReference {
+  alt: string
+  identifier: string
+  type: "image"
+  variants: Array<{
+    traits: string[]
+    url: string
+  }>
+}
+
+/**
+ * Represents an item in the HIG table of contents
+ */
+export interface HIGTocItem {
+  children?: HIGTocItem[]
+  icon?: string
+  path: string
+  title: string
+  type: "module" | "symbol" | "article"
+}
+
+/**
+ * Represents the complete HIG table of contents structure
+ */
+export interface HIGTableOfContents {
+  includedArchiveIdentifiers: string[]
+  interfaceLanguages: {
+    swift: HIGTocItem[]
+  }
+  references: Record<string, HIGIconReference>
+  schemaVersion: {
+    major: number
+    minor: number
+    patch: number
+  }
+}
+
+/**
+ * HIG-specific image metadata with card/icon types
+ */
+export interface HIGImage {
+  identifier: string
+  type: "icon" | "card" | "image"
+}
+
+/**
+ * HIG page metadata with locale and image support
+ */
+export interface HIGMetadata {
+  role: string
+  title: string
+  images?: HIGImage[]
+  availableLocales?: string[]
+}
+
+/**
+ * HIG-specific identifier with interface language
+ */
+export interface HIGIdentifier {
+  interfaceLanguage: string
+  url: string
+}
+
+/**
+ * HIG hierarchy information
+ */
+export interface HIGHierarchy {
+  paths: string[][]
+}
+
+/**
+ * HIG topic section structure
+ */
+export interface HIGTopicSection {
+  title?: string
+  identifiers: string[]
+  anchor?: string
+}
+
+/**
+ * HIG image variant with resolution and color mode support
+ */
+export interface HIGImageVariant {
+  traits: string[]
+  url: string
+}
+
+/**
+ * HIG image reference with variants
+ */
+export interface HIGImageReference {
+  alt: string | null
+  identifier: string
+  type: "icon" | "card" | "image"
+  variants: HIGImageVariant[]
+}
+
+/**
+ * HIG reference item (for linked articles and topics)
+ */
+export interface HIGReference {
+  kind: string
+  role?: string
+  title: string
+  url: string
+  abstract?: TextFragment[]
+  identifier: string
+  images?: HIGImage[]
+  type: "topic"
+}
+
+/**
+ * External/non-topic reference appearing in HIG references map
+ */
+export interface HIGExternalReference {
+  title: string
+  identifier: string
+  titleInlineContent?: TextFragment[]
+  url: string
+  type: string // e.g. "link"
+}
+
+/**
+ * HIG legal notices
+ */
+export interface HIGLegalNotices {
+  copyright: string
+  termsOfUse: string
+  privacy?: string
+  privacyPolicy?: string
+}
+
+/**
+ * The main HIG page JSON structure
+ */
+export interface HIGPageJSON {
+  // Metadata and identification
+  metadata: HIGMetadata
+  kind: "article"
+  identifier: HIGIdentifier
+  hierarchy: HIGHierarchy
+
+  // Content sections
+  sections: ContentItem[]
+  primaryContentSections: PrimaryContentSection[]
+  abstract: TextFragment[]
+
+  // Topic organization
+  topicSections?: HIGTopicSection[]
+  topicSectionsStyle?: "hidden" | "list" | "compactGrid"
+
+  // References to other content and images
+  references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>
+
+  // Schema version
+  schemaVersion: {
+    major: number
+    minor: number
+    patch: number
+  }
+
+  // Legal information
+  legalNotices?: HIGLegalNotices
+}
+
+// ============================================================================
+// TYPE GUARDS
+// ============================================================================
+
+/**
+ * Type guard to check if a reference is an image reference
+ */
+export function isHIGImageReference(
+  ref: HIGReference | HIGImageReference | HIGExternalReference,
+): ref is HIGImageReference {
+  return "alt" in ref && "variants" in ref
+}
+
+/**
+ * Type guard to check if a reference is a topic reference
+ */
+export function isHIGTopicReference(
+  ref: HIGReference | HIGImageReference | HIGExternalReference,
+): ref is HIGReference {
+  return ref.type === "topic"
+}
+
+/**
+ * Type guard to check if a ToC item has children
+ */
+export function hasChildren(item: HIGTocItem): boolean {
+  return item.children !== undefined && item.children.length > 0
+}