@clidey/dory 0.1.0

package/src/mdx/open-api.tsx

@@ -0,0 +1,325 @@
+import { useState } from "preact/hooks"
+import { APIGroup } from "./api"
+import { APIPlayground, PlayButton, type Server } from "./api-playground"
+import { Fence } from "./fence"
+import { Tag } from "./tag"
+import { Col, Row } from "./text"
+import { motion } from "motion/react"
+
+export function Properties({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="my-2">
+      <ul
+        role="list"
+        className="m-0 max-w-[calc(var(--container-lg)-(--spacing(8)))] list-none divide-y divide-zinc-900/5 p-0 dark:divide-white/10"
+      >
+        {children}
+      </ul>
+    </div>
+  )
+}
+
+export function Property({
+  name,
+  children,
+  type,
+  required = false,
+}: {
+  name: string
+  children: React.ReactNode
+  type?: string
+  required?: boolean
+}) {
+  return (
+    <div className="m-0 px-0 first:pt-0 last:pb-0">
+      <div className="my-4 flex flex-wrap items-center gap-x-3 gap-2">
+        <Tag className="px-4 py-1">{name}</Tag>
+        <p className="font-mono text-xs text-zinc-400 dark:text-zinc-500">
+          {type}
+        </p>
+        {required && <span className="text-rose-400 ml-1 text-xs">Required</span>}
+        <p className="w-full flex-none [&>:first-child]:mt-0 [&>:last-child]:mb-0 text-sm">
+          {children}
+        </p>
+      </div>
+    </div>
+  )
+}
+
+interface ParamFieldProps {
+  body: string;
+  type: string;
+  default?: string | number;
+  required?: boolean;
+  children: React.ReactNode;
+}
+
+export function ParamField({ body, type, default: defaultValue, required, children }: ParamFieldProps) {
+  return (
+    <Property name={body} type={type} required={required}>
+      {children}
+      {defaultValue != null && (
+        <span className="text-gray-500 ml-1">(default: {defaultValue})</span>
+      )}
+    </Property>
+  );
+}
+
+interface ResponseFieldProps {
+  name: string;
+  type: string;
+  required?: boolean;
+  children: React.ReactNode;
+}
+
+export function ResponseField({ name, type, required, children }: ResponseFieldProps) {
+  return (
+    <Property name={name} type={type} required={required}>
+      {children}
+    </Property>
+  );
+}
+
+interface Schema {
+  $ref?: string;
+  type?: string;
+  items?: Schema;
+  properties?: Record<string, Schema>;
+  required?: boolean;
+  description?: string;
+  default?: string | number;
+}
+
+interface Components {
+  schemas?: Record<string, Schema>;
+}
+
+interface Parameter {
+  name: string;
+  schema?: Schema;
+  required?: boolean;
+  description?: string;
+}
+
+interface Content {
+  schema?: Schema;
+}
+
+interface RequestBody {
+  description?: string;
+  content?: {
+    'application/json'?: Content;
+  };
+}
+
+interface Response {
+  content?: {
+    'application/json'?: Content;
+  };
+}
+
+interface PathMethod {
+  description?: string;
+  parameters?: Parameter[];
+  requestBody?: RequestBody;
+  responses: Record<string, Response>;
+}
+
+export interface OpenAPIJson {
+  paths: Record<string, Record<string, PathMethod>>;
+  components: Components;
+  servers?: Server[];
+}
+
+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;
+}
+
+export function OpenAPI({ openAPIJson, method: selectedMethod, path: selectedPath }: { openAPIJson: OpenAPIJson, method: string, path: string }) {
+  const { paths, components } = openAPIJson;
+  const [showPlayground, setShowPlayground] = useState(false);
+
+  const handleShowPlayground = () => {
+    setShowPlayground(true);
+  }
+
+  return (
+    <div className="max-w-none w-full">
+      {
+        showPlayground &&
+        <motion.div
+          initial={{ x: "100%" }}
+          animate={{ x: 0 }}
+          exit={{ x: "100%" }}
+          transition={{ type: "spring", damping: 20 }}
+          className="fixed inset-y-0 right-0 w-full max-w-3xl bg-white dark:bg-[#1e1e1e] shadow-xl z-50 overflow-y-auto border-l border-zinc-200 dark:border-zinc-800"
+        >
+          <div className="p-6">
+            <div className="flex justify-between items-center mb-6">
+              <h2 className="text-xl font-semibold">API Playground</h2>
+              <button
+                onClick={() => setShowPlayground(false)}
+                className="text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200"
+              >
+                <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+                </svg>
+              </button>
+            </div>
+            <APIPlayground
+              method={selectedMethod}
+              url={selectedPath}
+              servers={openAPIJson.servers}
+            />
+          </div>
+        </motion.div>
+      }
+
+      {Object.entries(paths).map(([path, methods]) => {
+        if (path !== selectedPath) {
+          return null;
+        }
+
+        return (
+          <div key={path} className="my-8">
+            {Object.entries(methods).map(([method, details]) => {
+            const { description, parameters, requestBody, responses } = details;
+            const methodUpper = method.toUpperCase();
+
+            if (methodUpper !== selectedMethod) {
+              return null;
+            }
+
+            return (
+              <Row key={`${method}-${path}`} cols={2}>
+                <Col>
+                  <h2 className="flex items-center mt-4">
+                    <Tag variant="medium" className="mr-2 py-1 px-4 rounded-lg">{methodUpper}</Tag>
+                    <span className="ml-2 font-mono">{path}</span>
+                  </h2>
+
+                  {description && <p>{description}</p>}
+
+                  {parameters && parameters.length > 0 && (
+                    <div className="mt-4">
+                      <h3>Parameters</h3>
+                      <Properties>
+                        {parameters.map((param) => (
+                          <ParamField 
+                            key={param.name}
+                            body={param.name}
+                            type={param.schema?.type ?? 'string'}
+                            required={param.required}
+                            default={param.schema?.default}
+                          >
+                            {param.description}
+                          </ParamField>
+                        ))}
+                      </Properties>
+                    </div>
+                  )}
+                  {requestBody && (
+                    <div className="mt-4">
+                      <h3>Request Body</h3>
+                      <p>{requestBody.description}</p>
+                      {requestBody.content?.['application/json']?.schema && (
+                        (() => {
+                          const resolvedSchema = resolveSchema(requestBody.content['application/json'].schema, components);
+                          return (
+                            <Properties>
+                              {Object.entries(resolvedSchema.properties || {}).map(([propName, prop]) => (
+                                <ParamField
+                                  key={propName}
+                                  body={propName}
+                                  type={prop.type ?? 'string'}
+                                  required={prop.required}
+                                  default={prop.default}
+                                >
+                                  {prop.description}
+                                </ParamField>
+                              ))}
+                            </Properties>
+                          );
+                        })()
+                      )}
+                    </div>
+                  )}
+                  {components?.schemas && (
+                    <div>
+                      <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]) => (
+                              <ResponseField
+                                key={propName}
+                                name={propName}
+                                type={prop.type ?? 'string'}
+                                required={prop.required}
+                              >
+                                {prop.description}
+                              </ResponseField>
+                            ))}
+                          </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 transition bg-sky-600 text-white hover:bg-sky-700'>
+                      Try
+                    <PlayButton className="h-4 w-4" />
+                  </button>
+                  <APIGroup title="Request" tag={methodUpper} label={path}>
+                    {Object.entries(responses).map(([code, response]) => (
+                      <div key={code} title={code}>
+                        {response.content?.['application/json']?.schema && (() => {
+                          const resolvedSchema = resolveSchema(response.content['application/json'].schema, components);
+                          return (
+                            <Fence language="json">
+                                {JSON.stringify(resolvedSchema, null, 2)}
+                            </Fence>
+                          );
+                        })()}
+                      </div>
+                    ))}
+                  </APIGroup>
+                </Col>
+              </Row>
+            )
+          })}
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/src/mdx/source.tsx

@@ -0,0 +1,47 @@
+type PathRange = {
+    path: string;
+    range: string;
+};
+
+type SourceProps = {
+    url: string;
+    branch?: string;
+    paths: PathRange[];
+};
+
+export const Source = ({ url, branch = "main", paths }: SourceProps) => {
+    const createSourceUrl = (path: string, range: string) => {
+        const [start, end] = range.split('-');
+
+        if (url.includes('github.com')) {
+            return `${url}/blob/${branch}/${path}#L${start}${end ? `-L${end}` : ''}`;
+        } else if (url.includes('bitbucket.org')) {
+            return `${url}/src/${branch}/${path}#lines-${start}${end ? `:${end}` : ''}`;
+        } else if (url.includes('gitlab.com')) {
+            return `${url}/-/blob/${branch}/${path}#L${range.replace('-', '-')}`;
+        }
+
+        return url;
+    };
+
+    return (
+        <div>
+            <p className="text-sm text-slate-900 dark:text-white">Sources:</p>
+            <ul className="list-none pl-0 flex flex-wrap gap-2 mt-2">
+                {paths.map(({ path, range }) => (
+                    <li key={path + range}>
+                        <a
+                            href={createSourceUrl(path, range)}
+                            target="_blank"
+                            rel="noopener noreferrer"
+                            className="rounded px-3 py-1 font-mono text-sm text-slate-700 dark:text-slate-400 hover:opacity-80 transition-colors border border-slate-200 dark:border-slate-700"
+                        >
+                            {path}
+                            <span className="ml-2 opacity-70">{range}</span>
+                        </a>
+                    </li>
+                ))}
+            </ul>
+        </div>
+    );
+};

package/src/mdx/step.tsx

@@ -0,0 +1,49 @@
+import classNames from "classnames"
+import { Children } from "preact/compat"
+
+export function Steps({ children }: { children: preact.ComponentChildren }) {
+  const steps = Children.toArray(children) as preact.ComponentChildren[];
+  return (
+    <nav aria-label="Progress" className="py-16">
+      <div className="overflow-hidden">
+        {steps.map((step, stepIdx) => {
+          const stepElement = Children.toArray(step)[0] as preact.JSX.Element;
+          return (
+            <div key={stepIdx} className={classNames(
+              {
+                "pb-10": stepIdx !== steps.length - 1,
+                "pb-2": stepIdx === steps.length - 1,
+              },
+              'relative'
+            )}>
+              <div aria-hidden="true" className="absolute top-10 left-4 h-full w-[0.5px] bg-gray-300/50 dark:bg-gray-600/50" style={{ top: '40px', height: 'calc(100% - 44px)' }} />
+              <div className="group relative flex items-start">
+                <span className="flex h-9 items-center">
+                  <span className="relative z-10 flex size-8 items-center justify-center rounded-full bg-white dark:bg-gray-800 group-hover:border-gray-400">
+                    <span className="text-sm font-medium text-gray-500 dark:text-white">
+                      {stepIdx + 1}
+                    </span>
+                  </span>
+                </span>
+                <span className="ml-4 flex min-w-0 flex-col">
+                  <p className="text-lg font-medium text-inherit">{stepElement.props.title}</p>
+                </span>
+              </div>
+              <div className="ml-12 not-prose">
+                {stepElement.props.children}
+              </div>
+            </div>
+          )
+        })}
+      </div>
+    </nav>
+  )
+}
+
+export function Step({ 
+  children 
+}: { 
+  children: preact.ComponentChildren 
+}) {
+  return <p className='text-sm'>{children}</p>
+}

package/src/mdx/table.tsx

@@ -0,0 +1,15 @@
+import type { JSX } from 'preact/jsx-runtime';
+
+export const Table = (props: JSX.IntrinsicElements['table']) => (
+  <div className="overflow-x-auto rounded-lg my-8">
+    <table className="border-collapse w-full border border-gray-300/10 rounded-lg" {...props} />
+  </div>
+);
+
+export const Th = (props: JSX.IntrinsicElements['th']) => (
+  <th className="border border-gray-300/10 p-2 bg-gray-100/25 text-left first:rounded-tl-lg last:rounded-tr-lg" {...props} />
+);
+
+export const Td = (props: JSX.IntrinsicElements['td']) => (
+  <td className="border border-gray-300/10 p-2 text-left last-row:first:rounded-bl-lg last-row:last:rounded-br-lg" {...props} />
+);

package/src/mdx/tag.tsx

@@ -0,0 +1,66 @@
+import classNames from 'classnames'
+
+const variantStyles = {
+  small: '',
+  medium: 'rounded-lg px-1.5 ring-1 ring-inset',
+}
+
+const colorStyles = {
+  emerald: {
+    small: 'text-emerald-500 dark:text-emerald-400',
+    medium:
+      'ring-emerald-300 dark:ring-emerald-400/30 bg-emerald-400/10 text-emerald-500 dark:text-emerald-400',
+  },
+  sky: {
+    small: 'text-sky-500',
+    medium:
+      'ring-sky-300 bg-sky-400/10 text-sky-500 dark:ring-sky-400/30 dark:bg-sky-400/10 dark:text-sky-400',
+  },
+  amber: {
+    small: 'text-amber-500',
+    medium:
+      'ring-amber-300 bg-amber-400/10 text-amber-500 dark:ring-amber-400/30 dark:bg-amber-400/10 dark:text-amber-400',
+  },
+  rose: {
+    small: 'text-red-500 dark:text-rose-500',
+    medium:
+      'ring-rose-200 bg-rose-50 text-red-500 dark:ring-rose-500/20 dark:bg-rose-400/10 dark:text-rose-400',
+  },
+  zinc: {
+    small: 'text-zinc-400 dark:text-zinc-500',
+    medium:
+      'ring-zinc-200 bg-zinc-50 text-zinc-500 dark:ring-zinc-500/20 dark:bg-zinc-400/10 dark:text-zinc-400',
+  },
+}
+
+const valueColorMap = {
+  GET: 'emerald',
+  POST: 'sky',
+  PUT: 'amber',
+  DELETE: 'rose',
+} as Record<string, keyof typeof colorStyles>
+
+export function Tag({
+  children,
+  variant = 'medium',
+  color = valueColorMap[children] ?? 'zinc',
+  className,
+}: {
+  children: keyof typeof valueColorMap & (string)
+  variant?: keyof typeof variantStyles
+  color?: keyof typeof colorStyles
+  className?: string
+}) {
+  return (
+    <span
+      className={classNames(
+        'font-mono text-[0.625rem]/6 font-semibold',
+        variantStyles[variant],
+        colorStyles[color][variant],
+        className,
+      )}
+    >
+      {children}
+    </span>
+  )
+}

package/src/mdx/text.tsx

@@ -0,0 +1,98 @@
+import classNames from "classnames"
+import { useState } from "preact/hooks"
+
+
+export const h1 = function H1(props: preact.JSX.HTMLAttributes<HTMLHeadingElement>) {
+  return <h1 className="text-4xl font-bold mb-4 mt-12" {...props} />
+}
+
+export const h2 = function H2(props: preact.JSX.HTMLAttributes<HTMLHeadingElement>) {
+  return <h2 className="text-3xl font-bold mb-3 mt-10" {...props} />
+}
+
+export const h3 = function H3(props: preact.JSX.HTMLAttributes<HTMLHeadingElement>) {
+  return <h3 className="text-2xl font-bold mb-2 mt-8" {...props} />
+}
+
+export const h4 = function H4(props: preact.JSX.HTMLAttributes<HTMLHeadingElement>) {
+  return <h4 className="text-xl font-bold mb-2 mt-6" {...props} />
+}
+
+export const h5 = function H5(props: preact.JSX.HTMLAttributes<HTMLHeadingElement>) {
+  return <h5 className="text-lg font-bold mb-2" {...props} />
+}
+
+export const h6 = function H6(props: preact.JSX.HTMLAttributes<HTMLHeadingElement>) {
+  return <h6 className="text-base font-bold mb-2" {...props} />
+}
+
+export const p = function P(props: preact.JSX.HTMLAttributes<HTMLParagraphElement>) {
+  return <p className="mb-2 inline-block" {...props} />
+}
+
+export function Row({ children, cols = 1 }: { children: preact.ComponentChildren, cols?: number }) {
+  return (
+    <div className={`grid grid-cols-1 items-start gap-x-16 gap-y-10 xl:max-w-none`} style={{ gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))` }}>
+      {children}
+    </div>
+  )
+}
+
+export function Col({
+  children,
+  sticky = false,
+  rows = 1,
+  gap = 4
+}: {
+  children: preact.ComponentChildren
+  sticky?: boolean
+  rows?: number
+  gap?: number
+}) {
+  return (
+    <div
+      className={classNames("[&>:first-child]:mt-0 [&>:last-child]:mb-0", {
+        'xl:sticky xl:top-24': sticky,
+      })}
+      style={{ 
+        display: 'grid',
+        gridTemplateRows: `repeat(${rows}, minmax(0, 1fr))`,
+        gap: `${gap * 0.25}rem`
+      }}
+    >
+      {children}
+    </div>
+  )
+}
+
+
+export function Anchor({ children, href }: { children: preact.ComponentChildren, href: string }) {
+  return <a href={href} className="text-blue-500 hover:text-blue-600">{children}</a>
+}
+
+export function Image({ src, alt }: { src: string, alt: string }) {
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  return (
+    <>
+      <img 
+        src={src} 
+        alt={alt} 
+        className="w-full h-auto cursor-pointer" 
+        onClick={() => setIsExpanded(true)}
+      />
+      {isExpanded && (
+        <div 
+          className="fixed inset-0 bg-black bg-opacity-90 z-50 flex items-center justify-center"
+          onClick={() => setIsExpanded(false)}
+        >
+          <img 
+            src={src} 
+            alt={alt} 
+            className="max-h-[90vh] max-w-[90vw] object-contain"
+          />
+        </div>
+      )}
+    </>
+  );
+}

package/src/plugins/sanitize.ts

@@ -0,0 +1,15 @@
+import { visit } from 'unist-util-visit';
+
+export const remarkSafeVars = () => {
+  return (tree: any) => {
+    visit(tree, 'mdxTextExpression', (node: any, index: number | undefined, parent: any) => {
+      if (parent && typeof index === 'number') {
+        // Replace mdxTextExpression with inlineCode node for code formatting
+        parent.children[index] = {
+          type: 'inlineCode',
+          value: node.value
+        };
+      }
+    });
+  };
+};