@inferencesh/ui 0.0.0-stage → 0.1.2

package/src/docs/steps.tsx

@@ -0,0 +1,105 @@
+'use client'
+
+import { cn } from '../utils'
+import { Check, Circle } from 'lucide-react'
+import React, { useMemo } from 'react'
+
+// =============================================================================
+// Steps Component
+// =============================================================================
+
+interface StepInfo {
+    title: string
+    children: React.ReactNode
+    icon?: React.ReactNode
+}
+
+function extractSteps(children: React.ReactNode): StepInfo[] {
+    const steps: StepInfo[] = []
+
+    React.Children.forEach(children, (child) => {
+        if (!React.isValidElement(child)) return
+
+        const type = child.type
+        const typeName = typeof type === 'string' ? type.toLowerCase() : ''
+
+        if (typeName === 'step' || (typeof type === 'function' && (type as React.FC).displayName === 'DocsStep')) {
+            const props = child.props as { title?: string; icon?: React.ReactNode; children?: React.ReactNode }
+            steps.push({
+                title: props.title || '',
+                icon: props.icon,
+                children: props.children,
+            })
+        }
+    })
+
+    return steps
+}
+
+export interface StepsProps {
+    children: React.ReactNode
+    className?: string
+    /** Title text size: 'p' (default), 'h2', 'h3' */
+    titleSize?: 'p' | 'h2' | 'h3'
+}
+
+export function Steps({ children, className, titleSize = 'p' }: StepsProps) {
+    const steps = useMemo(() => extractSteps(children), [children])
+
+    if (steps.length === 0) {
+        return <div className={className}><span>{children}</span></div>
+    }
+
+    const titleClasses = {
+        'p': 'text-base font-semibold',
+        'h2': 'text-xl font-bold',
+        'h3': 'text-lg font-semibold',
+    }
+
+    return (
+        <div className={cn('my-6 space-y-0', className)}>
+            {steps.map((step, i) => (
+                <div key={i} className="relative flex gap-4 pb-8 last:pb-0">
+                    {/* Vertical line */}
+                    {i < steps.length - 1 && (
+                        <div className="absolute left-[15px] top-8 h-[calc(100%-16px)] w-px bg-border" />
+                    )}
+
+                    {/* Step number indicator */}
+                    <div className="relative flex h-8 w-8 shrink-0 items-center justify-center rounded-full border-2 border-brand-pink bg-background text-sm font-semibold text-brand-pink">
+                        {step.icon || i + 1}
+                    </div>
+
+                    {/* Content */}
+                    <div className="flex-1 pt-0.5">
+                        {step.title && (
+                            <div className={cn(titleClasses[titleSize], 'mb-2')}>
+                                {step.title}
+                            </div>
+                        )}
+                        <div className="text-sm text-muted-foreground prose prose-sm dark:prose-invert max-w-none">
+                            {step.children}
+                        </div>
+                    </div>
+                </div>
+            ))}
+        </div>
+    )
+}
+
+// =============================================================================
+// Step Component (individual step)
+// =============================================================================
+
+export interface StepProps {
+    title?: string
+    icon?: React.ReactNode
+    children: React.ReactNode
+}
+
+export function Step({ children }: StepProps) {
+    // This component is just a marker - actual rendering happens in Steps
+    return <>{children}</>
+}
+
+Step.displayName = 'DocsStep'

package/src/docs/table-of-contents.tsx

@@ -0,0 +1,174 @@
+"use client"
+
+import { cn } from '../utils'
+import { useEffect, useMemo, useState } from 'react'
+import { TableOfContentsIcon } from 'lucide-react'
+
+export interface TocItem {
+  id: string
+  title: string
+  level?: number
+  children?: TocItem[]
+}
+
+interface TableOfContentsProps {
+  /** Markdown content to extract headings from */
+  content?: string
+  /** Pre-defined items (alternative to content extraction) */
+  items?: TocItem[]
+  /** Optional header slot (e.g., language selector) */
+  header?: React.ReactNode
+  /** Optional footer slot (e.g., link to full docs) */
+  footer?: React.ReactNode
+  className?: string
+}
+
+// Extract headings from markdown content (h2 and h3 only, h1 is page title)
+// Nests h3s under their preceding h2
+function extractHeadings(content: string): TocItem[] {
+  const result: TocItem[] = []
+  const lines = content.split('\n')
+  let currentH2: TocItem | null = null
+
+  for (const line of lines) {
+    const match = line.match(/^(#{2,3})\s+(.+)$/)
+    if (match) {
+      const level = match[1].length
+      const title = match[2].trim()
+      // Create a URL-safe ID from the heading text
+      const id = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/(^-|-$)/g, '')
+
+      if (level === 2) {
+        currentH2 = { id, title, level, children: [] }
+        result.push(currentH2)
+      } else if (level === 3) {
+        const item = { id, title, level }
+        if (currentH2) {
+          currentH2.children = currentH2.children || []
+          currentH2.children.push(item)
+        } else {
+          // h3 without preceding h2, add to root
+          result.push(item)
+        }
+      }
+    }
+  }
+
+  return result
+}
+
+// Flatten nested items for intersection observer
+function flattenItems(items: TocItem[]): TocItem[] {
+  return items.flatMap(item => [item, ...(item.children || [])])
+}
+
+export function TableOfContents({ content, items, header, footer, className }: TableOfContentsProps) {
+  const [activeId, setActiveId] = useState<string>('')
+
+  // Use provided items or extract from markdown
+  const tocItems = useMemo(() => {
+    if (items) return items
+    if (content) return extractHeadings(content)
+    return []
+  }, [items, content])
+
+  // Flatten for observer
+  const allItems = useMemo(() => flattenItems(tocItems), [tocItems])
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id)
+          }
+        })
+      },
+      {
+        rootMargin: '-80px 0px -80% 0px',
+        threshold: 0,
+      }
+    )
+
+    // Observe all heading elements
+    allItems.forEach(({ id }) => {
+      const element = document.getElementById(id)
+      if (element) {
+        observer.observe(element)
+      }
+    })
+
+    return () => observer.disconnect()
+  }, [allItems])
+
+  if (tocItems.length === 0) {
+    return null
+  }
+
+  const renderItem = (item: TocItem, isChild = false) => {
+    const isActive = activeId === item.id
+    const level = item.level || (isChild ? 3 : 2)
+
+    return (
+      <li key={item.id}>
+        <a
+          href={`#${item.id}`}
+          onClick={(e) => {
+            e.preventDefault()
+            const element = document.getElementById(item.id)
+            if (element) {
+              element.scrollIntoView({ behavior: 'smooth' })
+              setActiveId(item.id)
+            }
+          }}
+          className={cn(
+            'flex items-center text-[13px] py-1 -ml-px border-l transition-colors lowercase',
+            !isChild && 'pl-3 font-medium',
+            isChild && 'pl-4 text-xs',
+            isActive
+              ? 'border-brand-pink text-brand-pink'
+              : 'border-transparent text-muted-foreground hover:text-foreground hover:border-muted-foreground'
+          )}
+        >
+          {isChild && (
+            <span className={cn(
+              "mr-1.5 text-[10px] font-mono",
+              isActive ? "text-brand-pink" : "text-muted-foreground/50"
+            )}>
+              └
+            </span>
+          )}
+          {item.title}
+        </a>
+        {item.children && item.children.length > 0 && (
+          <ul className="space-y-0.5">
+            {item.children.map(child => renderItem(child, true))}
+          </ul>
+        )}
+      </li>
+    )
+  }
+
+  return (
+    <nav className={cn('relative', className)}>
+      {header}
+
+      <div className="flex items-center gap-2 mb-3">
+        <TableOfContentsIcon className="h-4 w-4 text-muted-foreground" />
+        <p className="text-xs font-bold text-muted-foreground">
+          on this page
+        </p>
+      </div>
+
+      <ul className="space-y-1 border-l border-border">
+        {tocItems.map(item => renderItem(item))}
+      </ul>
+
+      {footer}
+    </nav>
+  )
+}
+

package/src/examples/guide-markdown.ts

@@ -0,0 +1,129 @@
+/**
+ * Generate a full API guide as markdown for an app.
+ * Used by CopyMenu on both app.inference.sh and inference shell SEO pages.
+ */
+
+import { apiKeySetup, generateBackgroundExamples, generateFileExamples, generateResultOnlyExamples, generateStreamingExamples, installCommands } from '.'
+import { exampleInput } from '../lib/example-input'
+import { getFieldsFromSchema } from '../lib/schema'
+
+export type GuideLanguage = 'python' | 'typescript' | 'javascript' | 'swift' | 'curl' | 'belt'
+
+export interface GuideApp {
+  name: string
+  namespace?: string
+  description?: string
+}
+
+export interface GuideVersion {
+  short_id?: string
+  input_schema?: any
+  output_schema?: any
+  setup_schema?: any
+  functions?: Record<string, { name?: string; description?: string; input_schema?: any; output_schema?: any }>
+  default_function?: string
+}
+
+/** Where a key is made. /settings/<path> on the app opens that settings page. */
+export const API_KEYS_URL = 'https://app.inference.sh/settings/keys'
+
+export function generateGuideMarkdown(
+  app: GuideApp,
+  version: GuideVersion | undefined,
+  language: GuideLanguage = 'curl',
+  functionName?: string | null,
+  keysUrl: string = API_KEYS_URL,
+): string {
+  const namespace = app.namespace || ''
+  const shortId = version?.short_id
+  const defaultFn = version?.default_function || 'run'
+  const effectiveFn = functionName || defaultFn
+  const func = version?.functions?.[effectiveFn]
+  const schema = func?.input_schema || version?.input_schema || {}
+  const outputSchemaObj = func?.output_schema || version?.output_schema
+
+  // :function only when it is not the default of a multi-function app
+  const hasManyFunctions = version?.functions && Object.keys(version.functions).length > 1
+  const fnSuffix = (hasManyFunctions && effectiveFn !== defaultFn) ? `:${effectiveFn}` : ''
+  const versionSuffix = shortId ? `@${shortId}` : ''
+  const appRef = `${namespace}/${app.name}${versionSuffix}${fnSuffix}`
+
+  const params = { appRef, shortId, input: exampleInput(schema) }
+  const resultExamples = generateResultOnlyExamples(params)
+  const streamExamples = generateStreamingExamples(params)
+  const backgroundExamples = generateBackgroundExamples(params)
+  const fileEx = generateFileExamples(appRef)[language]
+  const keySetup = apiKeySetup[language] || apiKeySetup.curl
+  const installCmd = installCommands[language]
+  const codeLang = (language === 'curl' || language === 'belt') ? 'bash' : language
+  // swift installs through Package.swift, not a shell command
+  const installLang = language === 'swift' ? 'swift' : 'bash'
+
+  const inputFields = schema ? getFieldsFromSchema(schema).fields : []
+  const outputFields = outputSchemaObj ? getFieldsFromSchema(outputSchemaObj).fields : []
+
+  const code = (lang: string, body: string) => ['```' + lang, body.trim(), '```']
+
+  const lines = [
+    `# ${app.name} API Guide`,
+    '',
+    '## About',
+    `${app.description?.toLowerCase() || `Run ${app.name} via API.`}`,
+    '',
+    '## Get an API Key',
+    language === 'belt'
+      ? `Create one in [settings → api keys](${keysUrl}), or sign in with \`belt login\`. The examples read it from \`${keySetup.variable}\`.`
+      : `Create one in [settings → api keys](${keysUrl}). The examples read it from \`${keySetup.variable}\`.`,
+    '',
+    ...code('bash', keySetup.command),
+    '',
+    '## 1. Calling the API',
+    '',
+    ...(installCmd
+      ? ['### Install the Client', '', ...code(installLang, installCmd.command)]
+      : ['### Base URL', '', '`https://api.inference.sh`. No version prefix. Every response wraps its result in a `data` field.']),
+    '',
+    '### Run and Get Result',
+    language === 'curl'
+      ? 'Send `"wait": true` to hold the connection until the task finishes. Without it the call returns right away with the task still running.'
+      : 'Submit a request and wait for the final result.',
+    '',
+    ...code(codeLang, resultExamples[language] || ''),
+    '',
+    '### Stream Live Updates',
+    language === 'curl'
+      ? 'Send `"stream": true` and the response is a server-sent event stream that ends when the task does.'
+      : 'Get real-time progress updates as the task runs.',
+    '',
+    ...code(codeLang, streamExamples[language] || ''),
+    '',
+    '### Run in the Background',
+    'Start the task and get its id back right away, then check on it with `GET /tasks/{id}`. It is done when `status` is 10 (completed), 11 (failed) or 12 (cancelled).',
+    '',
+    ...code(codeLang, backgroundExamples[language] || ''),
+    '',
+    '## 2. Files',
+    '',
+    '### Automatic Upload',
+    '',
+    ...code(codeLang, fileEx.auto),
+    '',
+    '### Manual Upload',
+    '',
+    ...code(codeLang, fileEx.manual),
+    '',
+    '## 3. Schema',
+    '',
+    '### Input',
+    inputFields.length > 0
+      ? inputFields.map(f => `- **${f.key}** (${f.type || f.resolved?.type || 'any'})${f.isRequired ? ' *required*' : ''}: ${f.description || f.title || ''}`).join('\n')
+      : 'No input parameters defined.',
+    '',
+    '### Output',
+    outputFields.length > 0
+      ? outputFields.map(f => `- **${f.key}** (${f.type || f.resolved?.type || 'any'}): ${f.description || f.title || ''}`).join('\n')
+      : 'See task output for result format.',
+  ]
+
+  return lines.join('\n')
+}