@clidey/dory 0.30.0 → 0.33.0

package/src/mdx/api.tsx

@@ -0,0 +1,354 @@
+import { Tab, TabGroup, TabList, TabPanel, TabPanels } from '@headlessui/react'
+import classNames from 'classnames'
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from 'react'
+import { Tag } from './tag'
+import { CheckIcon } from 'lucide-react'
+import { Button, Card } from '@clidey/ux'
+
+const languageNames: Record<string, string> = {
+  js: 'JavaScript',
+  ts: 'TypeScript',
+  javascript: 'JavaScript',
+  typescript: 'TypeScript',
+  php: 'PHP',
+  python: 'Python',
+  ruby: 'Ruby',
+  go: 'Go',
+}
+
+function getPanelTitle({
+  title,
+  language,
+}: {
+  title?: string
+  language?: string
+}) {
+  if (title) {
+    return title
+  }
+  if (language && language in languageNames) {
+    return languageNames[language]
+  }
+  return 'API'
+}
+
+function ClipboardIcon(props: React.ComponentPropsWithoutRef<'svg'>) {
+  return (
+    <svg viewBox="0 0 20 20" aria-hidden="true" {...props}>
+      <path
+        strokeWidth="0"
+        d="M5.5 13.5v-5a2 2 0 0 1 2-2l.447-.894A2 2 0 0 1 9.737 4.5h.527a2 2 0 0 1 1.789 1.106l.447.894a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2h-5a2 2 0 0 1-2-2Z"
+      />
+      <path
+        fill="none"
+        strokeLinejoin="round"
+        d="M12.5 6.5a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2h-5a2 2 0 0 1-2-2v-5a2 2 0 0 1 2-2m5 0-.447-.894a2 2 0 0 0-1.79-1.106h-.527a2 2 0 0 0-1.789 1.106L7.5 6.5m5 0-1 1h-3l-1-1"
+      />
+    </svg>
+  )
+}
+
+function CopyButton({ code }: { code: string }) {
+  const [copyCount, setCopyCount] = useState(0)
+  const copied = copyCount > 0
+
+  useEffect(() => {
+    if (copyCount > 0) {
+      const timeout = setTimeout(() => setCopyCount(0), 1000)
+      return () => {
+        clearTimeout(timeout)
+      }
+    }
+  }, [copyCount])
+
+  return (
+    <Button
+      className={classNames(
+        'group/button absolute top-3.5 right-4 overflow-hidden rounded-full py-1 pr-3 pl-2 text-2xs font-medium opacity-0 backdrop-blur-sm transition group-hover:opacity-100 focus:opacity-100',
+        copied
+          ? 'bg-sky-400/10 ring-1 ring-sky-400/20 ring-inset'
+          : 'bg-white/5 hover:bg-white/7.5 dark:bg-white/2.5 dark:hover:bg-white/5',
+      )}
+      onClick={() => {
+        window.navigator.clipboard.writeText(code).then(() => {
+          setCopyCount((count) => count + 1)
+        })
+      }}
+    >
+      <span
+        aria-hidden={copied}
+        className={classNames(
+          'pointer-events-none flex items-center gap-0.5 text-zinc-400 transition duration-300',
+          copied && '-translate-y-1.5 opacity-0',
+        )}
+      >
+        <ClipboardIcon className="h-4 w-4 fill-zinc-500/20 stroke-zinc-500 transition-colors group-hover/button:stroke-zinc-400" />
+      </span>
+      <span
+        aria-hidden={!copied}
+        className={classNames(
+          'pointer-events-none absolute inset-0 flex items-center justify-center text-sky-400 transition duration-300',
+          !copied && 'translate-y-1.5 opacity-0',
+        )}
+      >
+        <CheckIcon className="h-4 w-4" />
+      </span>
+    </Button>
+  )
+}
+
+function APIPanelHeader({ tag, label }: { tag?: string; label?: string }) {
+  if (!tag && !label) {
+    return null
+  }
+
+  return (
+    <div className="flex h-9 items-center gap-2 px-4">
+      {tag && (
+        <div className="dark flex">
+          <Tag variant="small">{tag}</Tag>
+        </div>
+      )}
+      {tag && label && (
+        <span className="h-0.5 w-0.5 rounded-full bg-zinc-500" />
+      )}
+      {label && (
+        <span className="font-mono text-xs text-zinc-400">{label}</span>
+      )}
+    </div>
+  )
+}
+
+function APIPanel({
+  children,
+  tag,
+  label,
+  code,
+}: {
+  children: React.ReactNode
+  tag?: string
+  label?: string
+  code?: string
+}) {
+  const child = Children.only(children)
+
+  if (isValidElement(child)) {
+    // @ts-expect-error child.props is not typed
+    tag = child.props.tag ?? tag
+    // @ts-expect-error child.props is not typed
+    label = child.props.label ?? label
+    // @ts-expect-error child.props is not typed
+    code = child.props.code ?? code
+  }
+
+  return (
+    <div className="group dark:bg-white/2.5">
+      <APIPanelHeader tag={tag} label={label} />
+      <div className="relative">
+        <pre className="overflow-x-auto p-4 text-xs">{children}</pre>
+        {/* @ts-expect-error code is not typed */}
+        <CopyButton code={code} />
+      </div>
+    </div>
+  )
+}
+
+function APIGroupHeader({
+  title,
+  children,
+  selectedIndex,
+}: {
+  title: string
+  children: React.ReactNode
+  selectedIndex: number
+}) {
+  const hasTabs = Children.count(children) > 1
+
+  if (!title && !hasTabs) {
+    return null
+  }
+
+  return (
+    <div className="flex min-h-[calc(--spacing(12)+1px)] flex-wrap items-start gap-x-4 px-4 pt-2">
+      {title && (
+        <h3 className="mr-auto pt-3 text-xs font-semibold">
+          {title}
+        </h3>
+      )}
+      {hasTabs && (
+        <TabList className="-mb-px flex gap-4 text-xs font-medium">
+          {Children.map(children, (child, childIndex) => (
+            <Tab
+              className={classNames(
+                'pt-2 transition data-selected:not-data-focus:outline-hidden',
+                childIndex === selectedIndex
+                  ? 'border-sky-500 text-sky-400'
+                  : 'border-transparent text-zinc-400 hover:text-zinc-300',
+              )}
+            >
+              {/* @ts-expect-error child.props is not typed */}
+              {getPanelTitle(isValidElement(child) ? child.props : {})}
+            </Tab>
+          ))}
+        </TabList>
+      )}
+    </div>
+  )
+}
+
+function APIGroupPanels({
+  children,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof APIPanel>) {
+  const hasTabs = Children.count(children) > 1
+
+  if (hasTabs) {
+    return (
+      <TabPanels>
+        {Children.map(children, (child) => (
+          <TabPanel>
+            <APIPanel {...props}>{child}</APIPanel>
+          </TabPanel>
+        ))}
+      </TabPanels>
+    )
+  }
+
+  return <APIPanel {...props}>{children}</APIPanel>
+}
+function usePreventLayoutShift() {
+  const positionRef = useRef<HTMLElement>(null)
+  const rafRef = useRef<number>()
+
+  useEffect(() => {
+    return () => {
+      if (typeof rafRef.current !== 'undefined') {
+        window.cancelAnimationFrame(rafRef.current)
+      }
+    }
+  }, [])
+
+  return {
+    positionRef,
+    preventLayoutShift(callback: () => void) {
+      if (!positionRef.current) {
+        return
+      }
+
+      const initialTop = positionRef.current.getBoundingClientRect().top
+
+      callback()
+
+      rafRef.current = window.requestAnimationFrame(() => {
+        const newTop =
+          positionRef.current?.getBoundingClientRect().top ?? initialTop
+        window.scrollBy(0, newTop - initialTop)
+      })
+    },
+  }
+}
+
+function useTabGroupProps(availableLanguages: Array<string>) {
+  const [selectedIndex, setSelectedIndex] = useState(0)
+  const [preferredLanguages, setPreferredLanguages] = useState<string[]>([])
+  
+  const activeLanguage = [...availableLanguages].sort(
+    (a, z) => preferredLanguages.indexOf(z) - preferredLanguages.indexOf(a),
+  )[0]
+  const languageIndex = availableLanguages.indexOf(activeLanguage)
+  const newSelectedIndex = languageIndex === -1 ? selectedIndex : languageIndex
+  
+  if (newSelectedIndex !== selectedIndex) {
+    setSelectedIndex(newSelectedIndex)
+  }
+
+  const { positionRef, preventLayoutShift } = usePreventLayoutShift()
+
+  return {
+    as: 'div' as const,
+    ref: positionRef,
+    selectedIndex,
+    onChange: (newSelectedIndex: number) => {
+      preventLayoutShift(() => {
+        const newLanguage = availableLanguages[newSelectedIndex]
+        setPreferredLanguages(prev => [
+          ...prev.filter(lang => lang !== newLanguage),
+          newLanguage
+        ])
+      })
+    },
+  }
+}
+
+const APIGroupContext = createContext(false)
+
+export function APIGroup({
+  children,
+  title,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof APIGroupPanels> & { title: string }) {
+  const languages =
+    Children.map(children, (child) =>
+      // @ts-expect-error child.props is not typed
+      getPanelTitle(isValidElement(child) ? child.props : {}),
+    ) ?? []
+  const tabGroupProps = useTabGroupProps(languages)
+  const hasTabs = Children.count(children) > 1
+
+  const header = (
+    <APIGroupHeader title={title} selectedIndex={tabGroupProps.selectedIndex}>
+      {children}
+    </APIGroupHeader>
+  )
+  const panels = <APIGroupPanels {...props}>{children}</APIGroupPanels>
+
+  return (
+    <APIGroupContext.Provider value={true}>
+      {hasTabs ? (
+        <Card className="py-0 border-black/10 bg-none overflow-hidden mb-4">
+          <TabGroup {...tabGroupProps}>
+            <div className="not-prose">
+              {header}
+              {panels}
+            </div>
+          </TabGroup>
+        </Card>
+      ) : (
+        <Card className="py-0 border-black/10 bg-none overflow-hidden mb-4">
+          <div className="not-prose">
+            {header}
+            {panels}
+          </div>
+        </Card>
+      )}
+    </APIGroupContext.Provider>
+  )
+}
+
+export function API({
+  children,
+  ...props
+}: React.ComponentPropsWithoutRef<'code'>) {
+  const isGrouped = useContext(APIGroupContext)
+
+  if (isGrouped) {
+    if (typeof children !== 'string') {
+      throw new Error(
+        '`API` children must be a string when nested inside a `APIGroup`.',
+      )
+    }
+    return <code {...props}>
+      {children}
+    </code>
+  }
+
+  return <code {...props}>{children}</code>
+}

package/src/mdx/async-api.tsx

@@ -0,0 +1,353 @@
+import { useState } from "preact/hooks"
+import { APIGroup } from "./api"
+import { PlayButton } from "./api-playground"
+import { Fence } from "./fence"
+import { Properties, Property } from "./open-api"
+import { Tag } from "./tag"
+import { Col, Row } from "./text"
+import { WebSocketPlayground, type WebSocketServer } from "./websocket-playground"
+import { Button, Sheet, SheetContent, SheetHeader, SheetTitle } from "@clidey/ux"
+
+interface AsyncAPIMessage {
+  name?: string
+  title?: string
+  summary?: string
+  description?: string
+  payload?: Schema
+  headers?: Schema
+  correlationId?: {
+    description?: string
+    location?: string
+  }
+  schemaFormat?: string
+  contentType?: string
+  examples?: any[]
+}
+
+interface AsyncAPIOperation {
+  operationId?: string
+  summary?: string
+  description?: string
+  tags?: Array<{
+    name: string
+    description?: string
+  }>
+  message?: AsyncAPIMessage | {
+    oneOf?: AsyncAPIMessage[]
+  }
+  bindings?: {
+    ws?: {
+      method?: string
+      query?: Schema
+      headers?: Schema
+      bindingVersion?: string
+    }
+  }
+}
+
+interface AsyncAPIChannel {
+  address?: string
+  title?: string
+  summary?: string
+  description?: string
+  subscribe?: AsyncAPIOperation
+  publish?: AsyncAPIOperation
+  parameters?: Record<string, Parameter>
+  messages?: Record<string, AsyncAPIMessage>
+  bindings?: {
+    ws?: {
+      method?: string
+      query?: Schema
+      headers?: Schema
+      bindingVersion?: string
+    }
+  }
+}
+
+interface Schema {
+  $ref?: string
+  type?: string
+  items?: Schema
+  properties?: Record<string, Schema>
+  required?: string[]
+  description?: string
+  default?: any
+  example?: any
+  format?: string
+  enum?: any[]
+  oneOf?: Schema[]
+  anyOf?: Schema[]
+  allOf?: Schema[]
+}
+
+interface Parameter {
+  description?: string
+  schema?: Schema
+  location?: string
+  default?: any
+}
+
+interface Components {
+  schemas?: Record<string, Schema>
+  messages?: Record<string, AsyncAPIMessage>
+  parameters?: Record<string, Parameter>
+}
+
+interface Info {
+  title: string
+  version: string
+  description?: string
+  termsOfService?: string
+  contact?: {
+    name?: string
+    url?: string
+    email?: string
+  }
+  license?: {
+    name: string
+    url?: string
+  }
+}
+
+export interface AsyncAPIJson {
+  asyncapi: string
+  info: Info
+  servers?: Record<string, WebSocketServer & {
+    host?: string
+    pathname?: string
+    protocol?: string
+    protocolVersion?: string
+    description?: string
+    title?: string
+    summary?: string
+    variables?: Record<string, any>
+    security?: any[]
+    tags?: Array<{
+      name: string
+      description?: string
+    }>
+    bindings?: any
+  }>
+  channels: Record<string, AsyncAPIChannel>
+  components?: Components
+  defaultContentType?: string
+}
+
+function resolveSchema(schema: Schema | undefined, components: Components): Schema {
+  if (!schema) return {}
+
+  if (schema.$ref) {
+    const refPath = schema.$ref.replace(/^#\/components\/schemas\//, '')
+    return resolveSchema(components.schemas?.[refPath], components)
+  }
+
+  if (schema.type === 'array' && schema.items) {
+    return {
+      ...schema,
+      items: resolveSchema(schema.items, components)
+    }
+  }
+
+  if (schema.properties) {
+    const resolvedProps: Record<string, Schema> = {}
+    for (const [key, value] of Object.entries(schema.properties)) {
+      resolvedProps[key] = resolveSchema(value, components)
+    }
+    return {
+      ...schema,
+      properties: resolvedProps
+    }
+  }
+
+  return schema
+}
+
+function isDirectMessage(message: AsyncAPIMessage | { oneOf?: AsyncAPIMessage[] } | undefined): message is AsyncAPIMessage {
+  return message != null && !('oneOf' in message);
+}
+
+export function AsyncAPI({ 
+  asyncAPIJson, 
+  channel: selectedChannel, 
+  operation: selectedOperation 
+}: { 
+  asyncAPIJson: AsyncAPIJson
+  channel: string
+  operation: 'subscribe' | 'publish'
+}) {
+  const { channels, components, servers } = asyncAPIJson;
+  const [showPlayground, setShowPlayground] = useState(false)
+
+  const handleShowPlayground = () => {
+    setShowPlayground(true)
+  }
+
+  // Convert AsyncAPI servers to WebSocket servers
+  const wsServers: WebSocketServer[] = servers ? Object.entries(servers).map(([key, server]) => ({
+    url: `${server.protocol}://${server.host}${server.pathname || ''}`,
+    description: server.description || server.title || key,
+    protocol: server.protocol
+  })) : [];
+
+  return (
+    <div className="max-w-none w-full">
+      <Sheet open={showPlayground} onOpenChange={setShowPlayground} modal={true}>
+        <SheetContent side="bottom" className="h-[90vh] w-full overflow-y-auto p-8">
+          <SheetHeader className="p-0">
+            <SheetTitle>WebSocket Playground</SheetTitle>
+          </SheetHeader>
+          <WebSocketPlayground
+            url={selectedChannel}
+            servers={wsServers}
+          />
+        </SheetContent>
+      </Sheet>
+
+      {Object.entries(channels).map(([channelPath, channelDetails]) => {
+        if (channelPath !== selectedChannel) {
+          return null
+        }
+
+        const operation = channelDetails[selectedOperation]
+        if (!operation) {
+          return null
+        }
+
+        const { summary, description, message } = operation
+        const resolvedMessage = isDirectMessage(message) ? message : 
+          (message?.oneOf && message.oneOf.length > 0 ? message.oneOf[0] : undefined)
+
+        return (
+          <div key={channelPath} className="my-8">
+            <Row cols={2}>
+              <Col>
+                <h2 className="flex items-center mt-4">
+                  <Tag variant="medium" className="mr-2 py-1 px-4 rounded-lg">
+                    {selectedOperation.toUpperCase()}
+                  </Tag>
+                  <span className="ml-2 font-mono">{channelPath}</span>
+                </h2>
+
+                {(summary || description) && (
+                  <p>{summary || description}</p>
+                )}
+
+                {resolvedMessage && (
+                  <div className="mt-4">
+                    <h3>Message</h3>
+                    {resolvedMessage.title && <h4>{resolvedMessage.title}</h4>}
+                    {resolvedMessage.description && <p>{resolvedMessage.description}</p>}
+                    
+                    {resolvedMessage.payload && (
+                      <div className="mt-4">
+                        <h4>Payload</h4>
+                        {(() => {
+                          const resolvedPayload = resolveSchema(resolvedMessage.payload, components || {})
+                          return (
+                            <Properties>
+                              {Object.entries(resolvedPayload.properties || {}).map(([propName, prop]) => (
+                                <Property
+                                  key={propName}
+                                  name={propName}
+                                  type={prop.type || 'string'}
+                                  required={resolvedPayload.required?.includes(propName)}
+                                >
+                                  {prop.description}
+                                  {prop.default !== undefined && (
+                                    <span className="text-gray-500 ml-1">(default: {JSON.stringify(prop.default)})</span>
+                                  )}
+                                </Property>
+                              ))}
+                            </Properties>
+                          )
+                        })()}
+                      </div>
+                    )}
+
+                    {resolvedMessage.headers && (
+                      <div className="mt-4">
+                        <h4>Headers</h4>
+                        {(() => {
+                          const resolvedHeaders = resolveSchema(resolvedMessage.headers, components || {})
+                          return (
+                            <Properties>
+                              {Object.entries(resolvedHeaders.properties || {}).map(([headerName, header]) => (
+                                <Property
+                                  key={headerName}
+                                  name={headerName}
+                                  type={header.type || 'string'}
+                                  required={resolvedHeaders.required?.includes(headerName)}
+                                >
+                                  {header.description}
+                                </Property>
+                              ))}
+                            </Properties>
+                          )
+                        })()}
+                      </div>
+                    )}
+
+                    {resolvedMessage?.examples && resolvedMessage.examples.length > 0 && (
+                      <div className="mt-4">
+                        <h4>Examples</h4>
+                        {resolvedMessage.examples.map((example: any, idx: number) => (
+                          <Fence key={idx} language="json">
+                            {JSON.stringify(example, null, 2)}
+                          </Fence>
+                        ))}
+                      </div>
+                    )}
+                  </div>
+                )}
+
+                {components?.schemas && (
+                  <div className="mt-4">
+                    <h3>Schemas</h3>
+                    {Object.entries(components.schemas).filter(([, schema]) => schema.properties).map(([name, schema]) => (
+                      <div key={name} className="mt-4">
+                        <h4>{name}</h4>
+                        <Properties>
+                          {Object.entries(schema.properties || {}).map(([propName, prop]) => (
+                            <Property
+                              key={propName}
+                              name={propName}
+                              type={prop.type || 'string'}
+                              required={schema.required?.includes(propName)}
+                            >
+                              {prop.description}
+                            </Property>
+                          ))}
+                        </Properties>
+                      </div>
+                    ))}
+                  </div>
+                )}
+              </Col>
+              <Col sticky>
+                <Button
+                  onClick={handleShowPlayground}
+                  className='ml-auto mt-3 flex items-center gap-2 rounded-lg px-4 py-2 text-sm font-medium'
+                >
+                  Try
+                  <PlayButton className="h-4 w-4" />
+                </Button>
+                <APIGroup title="Message" tag={selectedOperation.toUpperCase()} label={channelPath}>
+                  <>
+                    {resolvedMessage?.payload && (() => {
+                      const resolvedPayload = resolveSchema(resolvedMessage.payload, components || {})
+                      return (
+                        <Fence language="json">
+                          {JSON.stringify(resolvedPayload, null, 2)}
+                        </Fence>
+                      )
+                    })()}
+                  </>
+                </APIGroup>
+              </Col>
+            </Row>
+          </div>
+        )
+      })}
+    </div>
+  )
+}