@clidey/dory 1.0.3 → 1.0.6

package/src/mdx/async-api.tsx

@@ -1,48 +1,37 @@
-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"
+import { Table, Td, Th } from "./table"
+import { WebSocketPanel, type WebSocketServer } from "./websocket-playground"
+
+interface Schema {
+  $ref?: string
+  type?: string
+  format?: string
+  enum?: unknown[]
+  items?: Schema
+  properties?: Record<string, Schema>
+  required?: string[]
+  description?: string
+  default?: unknown
+  example?: unknown
+}
 
 interface AsyncAPIMessage {
+  $ref?: string
   name?: string
   title?: string
   summary?: string
   description?: string
   payload?: Schema
   headers?: Schema
-  correlationId?: {
-    description?: string
-    location?: string
-  }
-  schemaFormat?: string
   contentType?: string
-  examples?: any[]
+  examples?: unknown[]
 }
 
 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
-    }
-  }
+  message?: AsyncAPIMessage | { oneOf?: AsyncAPIMessage[] }
 }
 
 interface AsyncAPIChannel {
@@ -52,302 +41,142 @@ interface AsyncAPIChannel {
   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
-  }>
+  info: { title: string; version: string; description?: string }
+  servers?: Record<string, WebSocketServer & { host?: string; pathname?: string; protocol?: string; description?: string; title?: string }>
   channels: Record<string, AsyncAPIChannel>
   components?: Components
-  defaultContentType?: string
 }
 
+type Direction = 'SEND' | 'RECV'
+
 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)
-    }
+    const name = schema.$ref.replace(/^#\/components\/schemas\//, '')
+    return resolveSchema(components.schemas?.[name], 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
-    }
+    const properties: Record<string, Schema> = {}
+    for (const [key, value] of Object.entries(schema.properties)) properties[key] = resolveSchema(value, components)
+    return { ...schema, properties }
   }
-
   return schema
 }
 
-function isDirectMessage(message: AsyncAPIMessage | { oneOf?: AsyncAPIMessage[] } | undefined): message is AsyncAPIMessage {
-  return message != null && !('oneOf' in message);
+/** Messages an operation carries, with `$ref` and `oneOf` resolved against components. */
+function messagesOf(operation: AsyncAPIOperation | undefined, components: Components): AsyncAPIMessage[] {
+  if (!operation?.message) return []
+  const list = 'oneOf' in operation.message && operation.message.oneOf ? operation.message.oneOf : [operation.message as AsyncAPIMessage]
+  return list.map((message) => {
+    if (!message.$ref) return message
+    const name = message.$ref.replace(/^#\/components\/messages\//, '')
+    return { name, ...(components.messages?.[name] ?? {}) }
+  })
 }
 
-export function AsyncAPI({ 
-  asyncAPIJson, 
-  channel: selectedChannel, 
-  operation: selectedOperation 
-}: { 
+function typeLabel(schema: Schema): string {
+  if (schema.enum) return `enum<${schema.type ?? 'string'}>`
+  if (schema.type === 'array') return `array<${schema.items ? typeLabel(schema.items) : 'any'}>`
+  if (schema.format) return `${schema.type ?? 'string'} · ${schema.format}`
+  return schema.type ?? 'object'
+}
+
+/**
+ * WebSocket operation page: a numbered "Connect" section with the live panel,
+ * a "Message types" table (SEND for publish, RECV for subscribe) and the payload fields.
+ */
+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)
+  const { channels, components = {}, servers } = asyncAPIJson
+  const channel = channels[selectedChannel]
+  const operation = channel?.[selectedOperation]
+  if (!channel || !operation) return null
+
+  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,
+      }))
+    : []
+
+  const rows: Array<{ name: string; direction: Direction; description?: string }> = [
+    ...messagesOf(channel.publish, components).map((m) => ({ name: m.name ?? m.title ?? 'message', direction: 'SEND' as Direction, description: m.summary ?? m.description })),
+    ...messagesOf(channel.subscribe, components).map((m) => ({ name: m.name ?? m.title ?? 'message', direction: 'RECV' as Direction, description: m.summary ?? m.description })),
+  ]
+  const primary = messagesOf(operation, components)[0]
+  const payload = primary?.payload ? resolveSchema(primary.payload, components) : undefined
+  const headerExample = primary?.headers ? resolveSchema(primary.headers, components) : undefined
+  const defaultHeaders: Record<string, string> = {}
+  for (const [name, schema] of Object.entries(headerExample?.properties ?? {})) {
+    if (schema.example !== undefined) defaultHeaders[name] = String(schema.example)
   }
 
-  // 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-muted-foreground 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 className="dory-asyncapi max-w-none w-full">
+      {(operation.description || operation.summary) && <p className="dory-lead -mt-4 mb-6">{operation.description || operation.summary}</p>}
+
+      <h2 id="connect" className="dory-h2 font-heading mb-3 mt-10"><span>Connect</span></h2>
+      <WebSocketPanel url={channel.address ?? selectedChannel} servers={wsServers} headers={defaultHeaders} />
+
+      {rows.length > 0 && (
+        <>
+          <h2 id="message-types" className="dory-h2 font-heading mb-3 mt-10"><span>Message types</span></h2>
+          <Table>
+            <thead>
+              <tr>
+                <Th>Type</Th>
+                <Th>Dir</Th>
+                <Th>Description</Th>
+              </tr>
+            </thead>
+            <tbody>
+              {rows.map((row) => (
+                <tr key={`${row.direction}-${row.name}`}>
+                  <Td><span className="font-mono text-xs">{row.name}</span></Td>
+                  <Td>
+                    <span className={row.direction === 'SEND' ? 'font-mono text-xs font-semibold text-[var(--brand-readable,#b65401)]' : 'font-mono text-xs font-semibold text-[var(--primary)]'}>
+                      {row.direction}
+                    </span>
+                  </Td>
+                  <Td>{row.description}</Td>
+                </tr>
+              ))}
+            </tbody>
+          </Table>
+        </>
+      )}
+
+      {payload?.properties && (
+        <>
+          <h2 id="payload" className="dory-h2 font-heading mb-3 mt-10"><span>Payload</span></h2>
+          {primary?.contentType && <p className="-mt-2 mb-2 font-mono text-xs text-muted-foreground">{primary.contentType}</p>}
+          <Properties>
+            {Object.entries(payload.properties).map(([name, schema]) => (
+              <Property key={name} name={name} type={typeLabel(schema)} required={payload.required?.includes(name)} defaultValue={schema.default}>
+                {schema.description}
+              </Property>
+            ))}
+          </Properties>
+        </>
+      )}
     </div>
   )
-}
+}

package/src/mdx/callout.tsx

@@ -1,28 +1,21 @@
-import { Alert, AlertTitle, AlertDescription } from '@clidey/ux'
+import classNames from 'classnames'
 import { Icon } from "./icon"
 
-const typeToVariant = {
-  note: 'default',
-  warning: 'destructive',
-  info: 'default',
-  tip: 'default',
-  check: 'default',
-} as const
-
 const icons = {
-  note: 'InfoCircle',
+  note: 'Info',
   warning: 'AlertTriangle',
-  info: 'InfoCircle',
-  tip: 'Lightbulb',
-  check: 'CheckCircle',
+  info: 'Info',
+  tip: 'Star',
+  check: 'Check',
 } as const
 
-const typeColors = {
-  note: 'border-emerald-500/30 bg-emerald-500/10 text-emerald-900 dark:text-emerald-200',
-  warning: 'border-amber-500/30 bg-amber-500/10 text-amber-900 dark:text-amber-200 *:data-[slot=alert-description]:text-inherit dark:data-[slot=alert-description]:text-inherit',
-  info: 'border-blue-500/30 bg-blue-500/10 text-blue-900 dark:text-blue-200',
-  tip: 'border-green-500/30 bg-green-500/10 text-green-900 dark:text-green-200',
-  check: 'border-purple-500/30 bg-purple-500/10 text-purple-900 dark:text-purple-200',
+// Each type gets a distinct surface and icon badge shape so they stay distinguishable without color.
+const typeStyles = {
+  note: { box: 'bg-muted border-[var(--border)]', badge: 'bg-card border border-[var(--border)] text-foreground rounded-md' },
+  warning: { box: 'bg-background border-[var(--highlight)]', badge: 'bg-[var(--highlight)] text-[var(--highlight-foreground)] rounded-[5px]' },
+  info: { box: 'bg-accent border-transparent', badge: 'bg-[var(--primary)] text-white rounded-[5px]' },
+  tip: { box: 'bg-[var(--success-muted)] border-transparent', badge: 'border border-foreground/70 text-foreground rounded-md' },
+  check: { box: 'bg-background border-[var(--border)]', badge: 'bg-[var(--success-muted)] text-foreground rounded-[5px]' },
 }
 
 export function Callout({
@@ -34,12 +27,17 @@ export function Callout({
   children: React.ReactNode
   type?: keyof typeof icons
 }) {
+  const styles = typeStyles[type]
   return (
-    <Alert variant={typeToVariant[type]} className={`my-6 ${typeColors[type]}`}>
-      <Icon icon={icons[type]} className="h-4 w-4" />
-      <AlertTitle>{title}</AlertTitle>
-      <AlertDescription>{children}</AlertDescription>
-    </Alert>
+    <div role="note" className={classNames('dory-callout not-prose my-5 flex gap-3 rounded-lg border px-4 py-3 text-foreground', styles.box)}>
+      <span className={classNames('mt-px flex size-6 shrink-0 items-center justify-center', styles.badge)}>
+        <Icon icon={icons[type]} className="h-3 w-3 !stroke-current" />
+      </span>
+      <div className="min-w-0 flex-1">
+        <p className="font-semibold leading-snug">{title}</p>
+        <div className="leading-relaxed [&_p]:mb-0">{children}</div>
+      </div>
+    </div>
   )
 }
 

package/src/mdx/card.tsx

@@ -1,18 +1,13 @@
 import classNames from "classnames";
-import {
-  Card as UXCard,
-  CardHeader,
-  CardTitle,
-  CardDescription,
-  CardContent
-} from '@clidey/ux'
+import { withBase } from '../utils/base-path';
 import { Icon } from "./icon";
 import type { ComponentChildren } from "preact";
 
-export function CardGroup({ children, cols = 2 }: { children: React.ReactNode; cols?: number }) {
+export function CardGroup({ children, cols = 2, numbered = false }: { children: React.ReactNode; cols?: number; numbered?: boolean }) {
   return (
     <div className={classNames(
-      'not-prose my-12 grid grid-cols-1 gap-6',
+      'not-prose my-6 grid grid-cols-1 gap-3',
+      numbered && 'dory-cards-numbered',
       cols === 2 && 'sm:grid-cols-2',
       cols === 3 && 'sm:grid-cols-3',
       cols === 4 && 'sm:grid-cols-4'
@@ -36,19 +31,22 @@ export function Card({
   children?: ComponentChildren
 }) {
   return (
-    <UXCard className="group relative border-ring border-1 border-black/10 dark:border-white/10">
-      {href && <a href={href} className="absolute inset-0 z-10" aria-label={title} />}
-      <CardHeader>
-        <div className="flex items-center gap-3">
-          {icon && <Icon icon={icon} className="h-8 w-8" />}
-          <CardTitle className="text-base">{title}</CardTitle>
+    <div className="dory-card group relative flex flex-col rounded-lg border border-[var(--border)] bg-card p-4 transition-shadow hover:shadow-[0_2px_10px_rgb(14_34_64/0.07)]">
+      {href && <a href={withBase(href)} className="absolute inset-0 z-10 rounded-lg" aria-label={title} />}
+      {(icon || href) && (
+        <div className="mb-3 flex items-start justify-between">
+          {icon ? (
+            <span className="flex size-8 items-center justify-center rounded-md bg-accent text-[var(--primary)]">
+              <Icon icon={icon} className="h-4 w-4 !stroke-current" />
+            </span>
+          ) : <span />}
+          {href && <Icon icon="ExternalLink" className="h-3.5 w-3.5 !stroke-[var(--muted-foreground)]" />}
         </div>
-      </CardHeader>
-      <CardContent>
-        <CardDescription className="text-sm leading-tight">
-          {description ?? children}
-        </CardDescription>
-      </CardContent>
-    </UXCard>
+      )}
+      <p className="font-heading text-[15px] font-semibold tracking-tight text-foreground">{title}</p>
+      <div className="mt-1 text-[13px] leading-normal text-muted-foreground [&_p]:mb-0">
+        {description ?? children}
+      </div>
+    </div>
   )
 }

package/src/mdx/chip.tsx

@@ -0,0 +1,14 @@
+/** Wrapping row of Chips with even gaps. */
+export function ChipGroup({ children }: { children: preact.ComponentChildren }) {
+  return <div className="not-prose my-4 flex flex-wrap gap-2">{children}</div>
+}
+
+/** Pill label with a brand-colored dot, for short lists such as supported databases. Links when `href` is set. */
+export function Chip({ children, href }: { children: preact.ComponentChildren; href?: string }) {
+  const className = 'inline-flex items-center gap-2 rounded-full border border-[var(--border)] bg-card px-3.5 py-1.5 text-[13px] font-medium text-foreground'
+  const dot = <span aria-hidden="true" className="size-1.5 shrink-0 rounded-full bg-[var(--primary)]" />
+  if (href) {
+    return <a href={href} className={`${className} hover:border-[var(--primary)]`}>{dot}{children}</a>
+  }
+  return <span className={className}>{dot}{children}</span>
+}