@stainless-api/docs-ui 0.1.0-beta.2 → 0.1.0-beta.20

package/src/components/method.tsx

@@ -18,23 +18,24 @@ export const HttpMethodIcons: Record<HTTPMethod, LucideIcon> = {
 };
 
 export type MethodIconProps = {
-  httpMethod: string;
+  httpMethod?: string;
   showName?: boolean;
 };
 
 export function MethodIconBadge({ httpMethod, showName }: MethodIconProps) {
-  if (!HttpMethods.includes(httpMethod)) return null;
+  if (!httpMethod || !HttpMethods.includes(httpMethod)) return null;
 
   return (
     <span
       className={clsx(style.MethodRouteHttpMethod, style.MethodRouteHttpMethodIconOnly)}
       data-method={httpMethod}
     >
-      {React.createElement(HttpMethodIcons[httpMethod], {
-        size: 14,
-        strokeWidth: 3,
-        className: style.Icon,
-      })}
+      {HttpMethodIcons[httpMethod] &&
+        React.createElement(HttpMethodIcons[httpMethod], {
+          size: 14,
+          strokeWidth: 3,
+          className: style.Icon,
+        })}
       {showName && httpMethod}
     </span>
   );
@@ -42,15 +43,17 @@ export function MethodIconBadge({ httpMethod, showName }: MethodIconProps) {
 
 export type MethodHeaderProps = {
   title: ReactNode;
+  level?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5';
   signature?: ReactNode;
   badges?: ReactNode;
   children?: ReactNode;
 };
 
-export function MethodHeader({ title, badges, signature, children }: MethodHeaderProps) {
+export function MethodHeader({ title, badges, signature, children, level }: MethodHeaderProps) {
+  const Heading = level ?? 'h5';
   return (
     <div className={style.MethodHeader}>
-      <h5 className={style.MethodTitle}>{title}</h5>
+      <Heading className={style.MethodTitle}>{title}</Heading>
       {badges && <div className={style.MethodBadges}>{badges}</div>}
       {signature}
       {children}
@@ -133,8 +136,6 @@ export type MethodProps = {
 } & React.HTMLProps<HTMLDivElement>;
 
 export function Method({ id, header, children, className, ...props }: MethodProps) {
-  const Docs = useComponents();
-
   return (
     <div id={id} className={clsx(style.Method, className)} tabIndex={0} {...props}>
       {header}

package/src/components/overview.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { ChevronRight } from 'lucide-react';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type * as SDKJSON from '@stainless/sdk-json';
 
 import { flatResources, getResourceFromSpec } from '../utils';
 import { useDeclaration, useLanguage, useLanguageComponents, useSpec } from '../contexts';
@@ -54,10 +54,11 @@ export type SDKMethodSummaryProps = {
 export function SDKMethodSummary({ method }: SDKMethodSummaryProps) {
   const Docs = useComponents();
   const Lang = useLanguageComponents();
-  const decl = useDeclaration(method.stainlessPath);
+  const decl = useDeclaration(method.stainlessPath, true);
 
   return (
     <Docs.MethodHeader
+      level="h5"
       title={<Docs.Link stainlessPath={method.stainlessPath}>{method.summary ?? method.title}</Docs.Link>}
       signature={<Lang.MethodSignature decl={decl} />}
       badges={method.deprecated && <Docs.Badge id="deprecated">Deprecated</Docs.Badge>}
@@ -75,11 +76,11 @@ export function SDKResource({ resource, parents, showModels }: SDKResourceProps
   const spec = useSpec();
 
   const methods = Object.values(resource.methods).filter(
-    (method) => spec.decls?.[language]?.[method.stainlessPath],
+    (method) => spec?.decls?.[language]?.[method.stainlessPath],
   );
 
   const models = Object.values(resource.models).filter(
-    (model) => spec.decls?.[language]?.[`${model.stainlessPath} > (schema)`],
+    (model) => spec?.decls?.[language]?.[`${model.stainlessPath} > (schema)`],
   );
 
   return (
@@ -88,13 +89,11 @@ export function SDKResource({ resource, parents, showModels }: SDKResourceProps
         <Docs.SDKResourceHeader resource={resource} parents={parents} />
         {methods.length > 0 && (
           <div className={style.ResourceContentGroup}>
-            {methods
-              .toSorted((first, second) => first.name.localeCompare(second.name))
-              .map((method) => (
-                <div className={style.MethodSummary} key={method.stainlessPath}>
-                  <Docs.SDKMethodSummary method={method} />
-                </div>
-              ))}
+            {methods.map((method) => (
+              <div className={style.MethodSummary} key={method.stainlessPath}>
+                <Docs.SDKMethodSummary method={method} />
+              </div>
+            ))}
           </div>
         )}
 
@@ -145,15 +144,29 @@ export function SDKRoot({ stainlessPath }: SDKRootProps) {
   const Docs = useComponents();
 
   const parsed = parseStainlessPath(stainlessPath);
-  const resource = getResourceFromSpec(stainlessPath, spec);
+  const resource = spec && getResourceFromSpec(stainlessPath, spec);
 
-  if (!resource || !parsed) return null;
+  if (!resource || !parsed) {
+    console.warn(`Could not find resource or parsed path for '${stainlessPath}'`);
+    return null;
+  }
 
-  const content = parsed.method ? (
-    <Docs.SDKMethod method={resource.methods[parsed.method]} />
-  ) : (
-    <Docs.SDKOverview resource={resource} />
-  );
+  if (parsed.method) {
+    const method = resource.methods[parsed.method];
+    if (!method) {
+      console.warn(`Method '${parsed.method}' not found in resource '${resource.stainlessPath}'`);
+      return null;
+    }
+    return (
+      <div className={style.Root}>
+        <Docs.SDKMethod method={method} />
+      </div>
+    );
+  }
 
-  return <div className={style.Root}>{content}</div>;
+  return (
+    <div className={style.Root}>
+      <Docs.SDKOverview resource={resource} />
+    </div>
+  );
 }

package/src/components/primitives.tsx

@@ -10,7 +10,12 @@ type JoinProps = { items: ReactNode[]; limit?: number; children: ReactNode };
 export function Join({ items, limit, children }: JoinProps) {
   const arr =
     limit && items.length > limit + 1
-      ? [...items.slice(0, limit), <span className={style.Truncation}>{items.length - limit} more</span>]
+      ? [
+          ...items.slice(0, limit),
+          <span className={style.Truncation} key="truncation">
+            {items.length - limit} more
+          </span>,
+        ]
       : items;
 
   return arr.map((item, index) => (
@@ -31,7 +36,8 @@ type ExpanderProps = {
 };
 
 export function Expander({ id, open, summary, virtual, muted, children }: ExpanderProps) {
-  const { virtualExpanders } = useSettings();
+  const settings = useSettings();
+  const virtualExpanders = settings?.virtualExpanders;
 
   if (virtual || virtualExpanders)
     return (
@@ -154,8 +160,8 @@ export function Link({ stainlessPath, scroll = true, children, ...props }: LinkP
 
   const href = React.useMemo(() => {
     if (props.href) return props.href;
-    if (stainlessPath) return generateRoute(basePath, language, stainlessPath);
-  }, [basePath, language, stainlessPath]);
+    if (stainlessPath && basePath) return generateRoute(basePath, language, stainlessPath);
+  }, [basePath, language, stainlessPath, props.href]);
 
   const handleClick = React.useCallback(
     (e: React.MouseEvent<HTMLAnchorElement>) => {
@@ -163,7 +169,7 @@ export function Link({ stainlessPath, scroll = true, children, ...props }: LinkP
       if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
       if (href) onNavigate?.(e, { href, language, stainlessPath, scroll });
     },
-    [href, scroll, onNavigate],
+    [href, scroll, onNavigate, language, props, stainlessPath],
   );
 
   if (!href) return children;
@@ -180,7 +186,10 @@ export type InputProps = {
   right?: ReactNode;
 } & React.InputHTMLAttributes<HTMLInputElement>;
 
-export const Input = React.forwardRef<HTMLInputElement, InputProps>(({ left, right, ...props }, ref) => {
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(function Input(
+  { left, right, ...props },
+  ref,
+) {
   return (
     <div className={style.Input}>
       {left}
@@ -195,15 +204,16 @@ export type ToggleButtonProps = {
   selected?: boolean;
 } & React.ButtonHTMLAttributes<HTMLButtonElement>;
 
-export const ToggleButton = React.forwardRef<HTMLButtonElement, ToggleButtonProps>(
-  ({ children, selected, ...props }, ref) => {
-    return (
-      <button {...props} ref={ref} className={style.ToggleButton} data-stldocs-toggle-selected={selected}>
-        {children}
-      </button>
-    );
-  },
-);
+export const ToggleButton = React.forwardRef<HTMLButtonElement, ToggleButtonProps>(function ToggleButton(
+  { children, selected, ...props },
+  ref,
+) {
+  return (
+    <button {...props} ref={ref} className={style.ToggleButton} data-stldocs-toggle-selected={selected}>
+      {children}
+    </button>
+  );
+});
 
 export type ListViewProps<TItem> = {
   items: Array<TItem>;
@@ -222,6 +232,13 @@ export function ListView<TItem>({ items, itemDelegate, onSelectListItem, ...rest
     setKeyboardIndex(0);
   }, [items]);
 
+  const handleSelect = React.useCallback(() => {
+    const item = items[selectedIndex];
+    if (item) {
+      onSelectListItem?.(item);
+    }
+  }, [items, selectedIndex, onSelectListItem]);
+
   React.useEffect(() => {
     function handleKeyPress(ev: KeyboardEvent) {
       switch (ev.key) {
@@ -243,17 +260,17 @@ export function ListView<TItem>({ items, itemDelegate, onSelectListItem, ...rest
 
         case 'Enter':
           ev.preventDefault();
-          onSelectListItem?.(items[selectedIndex]);
+          handleSelect();
           break;
       }
     }
 
     addEventListener('keydown', handleKeyPress);
     return () => removeEventListener('keydown', handleKeyPress);
-  }, [items, selectedIndex]);
+  }, [items, selectedIndex, handleSelect]);
 
   React.useEffect(() => {
-    if (!keyboardIndex) {
+    if (!keyboardIndex || !itemRef.current || !listRef.current) {
       listRef?.current?.scroll(0, 0);
       return;
     }
@@ -273,7 +290,7 @@ export function ListView<TItem>({ items, itemDelegate, onSelectListItem, ...rest
           ref={index === selectedIndex ? itemRef : null}
           className={style.ListViewItem}
           data-stldocs-listview-selected={index === selectedIndex}
-          onClick={() => onSelectListItem?.(items[selectedIndex])}
+          onClick={handleSelect}
           onMouseMove={() => setSelectedIndex(index)}
         >
           {itemDelegate(item, index === selectedIndex)}

package/src/components/properties.tsx

@@ -1,4 +1,4 @@
-import React, { type ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import { useLanguage, useSettings } from '../contexts';
 import { useComponents } from '../contexts/use-components';
 import style from '../style';
@@ -72,7 +72,9 @@ export function Property({
   const Docs = useComponents();
   const language = useLanguage();
 
-  const { collapseDescription, types } = useSettings().properties ?? {};
+  const properties = useSettings()?.properties;
+  const collapseDescription = properties?.collapseDescription;
+  const types = properties?.types;
 
   const textContent = (
     <>

package/src/components/scripts/dropdown.ts

@@ -46,7 +46,7 @@ export function initDropdown({
   }
 
   // Toggle dropdown on button click
-  button.addEventListener('click', (e) => {
+  button.addEventListener('click', () => {
     toggleDropdown();
   });
 

package/src/components/sdk.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type * as SDKJSON from '@stainless/sdk-json';
 import { useComponents } from '../contexts/use-components';
 import {
   useLanguageComponents,
@@ -32,7 +32,7 @@ export type PropertyModelContextType = {
   propertyPath?: string;
 };
 
-export const PropertyModelContext = React.createContext<PropertyModelContextType>(null);
+export const PropertyModelContext = React.createContext<PropertyModelContextType>({});
 export function usePropertyModel() {
   return React.useContext(PropertyModelContext);
 }
@@ -93,16 +93,15 @@ type SDKDeclarationProps = {
 export function SDKDeclaration({ path, expand, depth = 0 }: SDKDeclarationProps) {
   const Lang = useLanguageComponents();
   const Docs = useComponents();
-  const decl = useDeclaration(path);
+  const decl = useDeclaration(path, true);
   const settings = useSettings();
   const model = usePropertyModel();
   const nesting = useReferenceNesting();
   const { selectedPath } = useNavigation();
 
-  if (!decl) return null;
-
   if (decl.kind.endsWith('Reference')) {
-    const refId = decl['type']['$ref'];
+    const refId =
+      'type' in decl && typeof decl.type !== 'string' && '$ref' in decl.type ? decl.type['$ref'] : undefined;
     if (refId && refId !== path && !nesting.includes(refId)) {
       return (
         <ReferenceNestingContext.Provider value={[...nesting, refId]}>
@@ -112,11 +111,14 @@ export function SDKDeclaration({ path, expand, depth = 0 }: SDKDeclarationProps)
     }
   }
 
-  const isUnion = 'childrenParentSchema' in decl && ['enum', 'union'].includes(decl.childrenParentSchema);
+  const isUnion =
+    'childrenParentSchema' in decl &&
+    decl.childrenParentSchema &&
+    ['enum', 'union'].includes(decl.childrenParentSchema);
   const id = model?.propertyPath ? `${model.propertyPath} + ${path}` : path;
   const shouldExpand =
-    (selectedPath.startsWith(path) && nesting.length < 1) ||
-    (settings.properties?.expandDepth && depth <= settings.properties?.expandDepth && !isUnion) ||
+    (selectedPath?.startsWith(path) && nesting.length < 1) ||
+    (settings?.properties?.expandDepth && depth <= settings?.properties?.expandDepth && !isUnion) ||
     expand;
 
   const content = (
@@ -125,18 +127,18 @@ export function SDKDeclaration({ path, expand, depth = 0 }: SDKDeclarationProps)
         <Docs.Property
           id={id}
           expand={shouldExpand}
-          constraints={decl['constraints'] && <Docs.SDKConstraints constraints={decl['constraints']} />}
+          constraints={'constraints' in decl && <Docs.SDKConstraints constraints={decl['constraints']} />}
           declaration={<Lang.Declaration decl={decl} />}
-          description={decl['docstring']}
+          description={'docstring' in decl ? decl['docstring'] : undefined}
           deprecated={decl.deprecated}
           {...props}
         >
           {'children' in decl &&
-            decl.children.length > 0 &&
-            (settings.properties?.includeModelProperties !== false || !('modelPath' in decl)) && (
+            (decl.children?.length ?? 0) > 0 &&
+            (settings?.properties?.includeModelProperties !== false || !('modelPath' in decl)) && (
               <>
                 {isUnion && <div className={style.PropertyAnnotation}>Accepts one of the following:</div>}
-                <Docs.SDKChildren paths={decl.children} depth={depth + 1} />
+                <Docs.SDKChildren paths={decl.children ?? []} depth={depth + 1} />
               </>
             )}
         </Docs.Property>
@@ -239,10 +241,11 @@ export type SDKMethodProps = {
 export function SDKMethodHeader({ method }: SDKMethodProps) {
   const Docs = useComponents();
   const Lang = useLanguageComponents();
-  const decl = useDeclaration(method.stainlessPath);
+  const decl = useDeclaration(method.stainlessPath, true);
 
   return (
     <Docs.MethodHeader
+      level="h1"
       title={method.summary ?? method.title}
       signature={<Lang.MethodSignature decl={decl} />}
       badges={method.deprecated && <Docs.Badge id="deprecated">Deprecated</Docs.Badge>}
@@ -255,7 +258,7 @@ export function SDKMethodHeader({ method }: SDKMethodProps) {
 export function SDKMethodInfo({ method }: SDKMethodProps) {
   const Docs = useComponents();
   const Lang = useLanguageComponents();
-  const decl = useDeclaration(method.stainlessPath);
+  const decl = useDeclaration(method.stainlessPath, true);
   const spec = useSpec();
   const language = useLanguage();
 
@@ -263,8 +266,10 @@ export function SDKMethodInfo({ method }: SDKMethodProps) {
 
   function shouldExpand(items: SDKJSON.ID[]) {
     if (items.length > 1) return false;
-    const decl = spec?.decls?.[language]?.[items[0]];
-    return decl && 'children' in decl && decl.children.length > 0;
+    const item = items[0];
+    if (!item) return false;
+    const decl = spec?.decls?.[language]?.[item];
+    return decl && 'children' in decl && decl.children && decl.children.length > 0;
   }
 
   return (
@@ -278,6 +283,7 @@ export function SDKMethodInfo({ method }: SDKMethodProps) {
       }
       returns={
         'responseChildren' in decl &&
+        decl.responseChildren &&
         decl.responseChildren.length > 0 && (
           <Docs.SDKChildren expand={shouldExpand(decl.responseChildren)} paths={decl.responseChildren} />
         )
@@ -288,7 +294,7 @@ export function SDKMethodInfo({ method }: SDKMethodProps) {
 
 export function SDKMethod({ method, transformRequestSnippet }: SDKMethodProps) {
   const Docs = useComponents();
-  const decl = useDeclaration(method?.stainlessPath);
+  const decl = useDeclaration(method?.stainlessPath, true);
   const layout = useContentPanelLayout();
 
   if (!decl) return;
@@ -323,7 +329,7 @@ export type SDKModelProps = {
 
 export function SDKModel({ model }: SDKModelProps) {
   const Docs = useComponents();
-  const decl = useDeclaration(`${model.stainlessPath} > (schema)`);
+  const decl = useDeclaration(`${model.stainlessPath} > (schema)`, true);
 
   if (!decl) return null;
 
@@ -383,9 +389,9 @@ export function SDKLanguageBlock({ language, version, install, links }: SDKLangu
 
       <div className={style.LanguageBlockInstall} data-stldocs-copy-parent>
         <pre data-stldocs-copy-content>{install}</pre>{' '}
-        <button data-stldocs-snippet-copy>
+        <Button variant="ghost" size="sm" data-stldocs-snippet-copy>
           <Copy size={16} className={style.Icon} />
-        </button>
+        </Button>
       </div>
 
       <div className={style.LanguageBlockLinks}>

package/src/components/sidebar.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type * as SDKJSON from '@stainless/sdk-json';
 import { useNavigation } from '../contexts';
 import { useComponents } from '../contexts/use-components';
 import { ChevronDown, ChevronRight } from 'lucide-react';
@@ -50,8 +50,8 @@ export type SidebarResourceProps = {
 
 export function SidebarResource({ resource }: SidebarResourceProps) {
   const Docs = useComponents();
-  const { selectedPath, navigationPath } = useNavigation();
-  const subresources = Object.values(resource.subresources).map((sub) => (
+  const { selectedPath } = useNavigation();
+  const subresources = Object.values(resource.subresources ?? {}).map((sub) => (
     <SidebarResource resource={sub} key={sub.stainlessPath} />
   ));
 

package/src/components/snippets.tsx

@@ -4,8 +4,9 @@ import { useDeclaration, useHighlight, useLanguage, useSnippet } from '../contex
 import { useComponents } from '../contexts/use-components';
 import style from '../style';
 import clsx from 'clsx';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type * as SDKJSON from '@stainless/sdk-json';
 import type { TransformRequestSnippetFn } from './sdk';
+import { Button } from '@stainless-api/ui-primitives';
 
 export type SnippetCodeProps = {
   content: string;
@@ -58,15 +59,24 @@ export function Snippet({ requestTitle, method, transformRequestSnippet }: Snipp
   const language = useLanguage();
   const [CopyButtonIcon, setCopyIcon] = React.useState<LucideIcon>(CopyIcon);
 
-  let snippet = useSnippet(method.stainlessPath, null, language === 'http' ? 'curl' : 'default');
-  const decl = useDeclaration(method.stainlessPath);
+  const originalSnippet = useSnippet(
+    method.stainlessPath,
+    undefined,
+    language === 'http' ? 'curl' : 'default',
+  );
+  const decl = useDeclaration(method.stainlessPath, false);
+
+  if (!originalSnippet) {
+    console.warn(`Snippet not found for method '${method.stainlessPath}'`);
+    return null;
+  }
 
-  const signature = 'qualified' in decl ? decl.qualified : undefined;
+  const signature = decl && 'qualified' in decl ? decl.qualified : undefined;
   const responses = method.exampleResponses;
 
-  if (transformRequestSnippet) {
-    snippet = transformRequestSnippet({ snippet, language });
-  }
+  const snippet = transformRequestSnippet
+    ? transformRequestSnippet({ snippet: originalSnippet, language })
+    : originalSnippet;
 
   async function handleCopy() {
     try {
@@ -90,9 +100,9 @@ export function Snippet({ requestTitle, method, transformRequestSnippet }: Snipp
                 <h5>{method.summary}</h5>
               </div>
               <div className={style.SnippetRequestTitleContent}>{requestTitle}</div>
-              <button data-stldocs-snippet-copy className={style.SnippetRequestTitleCopyButton}>
+              <Button variant="ghost" data-stldocs-snippet-copy>
                 <CopyButtonIcon size={16} className={style.Icon} onClick={handleCopy} />
-              </button>
+              </Button>
             </div>
             <Docs.SnippetCode content={snippet} signature={signature} />
           </div>
@@ -112,9 +122,15 @@ export function SnippetResponse({ responses }: { responses: SDKJSON.Method['exam
 
   const mappedResponses = Object.keys(responses)
     .map((key) => {
+      const responseContent = responses[key];
+      if (!responseContent) return null;
+
       // Get the first response type ie application/json or text/plain
-      const responseType = Object.keys(responses[key])[0];
-      const response = responses[key][responseType];
+      const responseType = Object.keys(responseContent)[0];
+      if (!responseType) return null;
+
+      const response = responseContent[responseType];
+      if (!response) return null;
 
       const examples = response?.examples;
 
@@ -122,6 +138,8 @@ export function SnippetResponse({ responses }: { responses: SDKJSON.Method['exam
 
       // Get the first example type, ie Example or html
       const exampleType = Object.keys(examples)[0];
+      if (!exampleType) return null;
+
       let value = examples[exampleType]?.value;
 
       if (!value) return null;

package/src/contexts/component-generics.tsx

@@ -1,6 +1,7 @@
 // This file should never import from ../components or ../languages to avoid circular dependencies
 
 import * as React from 'react';
+import { createStrictContext } from '../hooks/use-strict-context';
 
 type DeepPartialMap<L> = { [K in keyof L]?: Partial<L[K]> };
 
@@ -9,13 +10,10 @@ export type ComponentsContextType<C, L> = {
   language: L;
 };
 
-const ComponentContext = React.createContext<ComponentsContextType<any, any> | null>(null);
-ComponentContext.displayName = 'ComponentContext';
+const [Provider, useComponentContext] = createStrictContext<ComponentsContextType<any, any>>('Component');
 
-export function useComponents<C = unknown>() {
-  const ctx = React.useContext(ComponentContext);
-  if (!ctx) throw new Error('useComponents must be used within a ComponentContext.Provider');
-  return ctx.components as C;
+export function useComponents<C = unknown>(): C {
+  return useComponentContext().components as C;
 }
 
 export function customizeComponents<C, L>(
@@ -24,13 +22,10 @@ export function customizeComponents<C, L>(
 ): { components: C; language: L } {
   const mergedComponents = { ...defaults.components, ...(overrides.components ?? {}) } as C;
 
-  const mergedLanguage = Object.keys(defaults.language as Record<string, unknown>).reduce(
-    (acc, key) => {
-      acc[key] = { ...(defaults.language as any)[key], ...(overrides.language?.[key] ?? {}) };
-      return acc;
-    },
-    {} as any as L,
-  );
+  const mergedLanguage = Object.keys(defaults.language as Record<string, unknown>).reduce((acc, key) => {
+    acc[key] = { ...(defaults.language as any)[key], ...((overrides.language as any)?.[key] ?? {}) };
+    return acc;
+  }, {} as any);
 
   return { components: mergedComponents, language: mergedLanguage };
 }
@@ -42,7 +37,7 @@ export function ComponentProvider<C, L>({
   value: ComponentsContextType<C, L>;
   children: React.ReactNode;
 }) {
-  return <ComponentContext.Provider value={value}>{children}</ComponentContext.Provider>;
+  return <Provider value={value}>{children}</Provider>;
 }
 
-export { ComponentContext };
+export { useComponentContext };

package/src/contexts/docs.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { Spec, SpecLanguage } from '~/lib/json-spec-v2/types';
+import type { LanguageDeclNodes, SnippetLanguage, Spec, SpecLanguage } from '@stainless/sdk-json';
 
 export type ContentPanelLayout = 'double-pane' | 'single-pane';
 export type PropertySettingsType = {
@@ -40,13 +40,24 @@ export function useSettings() {
 }
 
 export function useSnippet(stainlessPath: string, language?: SpecLanguage, variant?: string) {
-  const snippetLanguage = [language ?? useLanguage(), variant ?? 'default'].join('.');
+  const defaultLanguage = useLanguage();
+  const snippetLanguage = [language ?? defaultLanguage, variant ?? 'default'].join('.') as SnippetLanguage;
 
   return useSpec()?.snippets?.[snippetLanguage]?.[stainlessPath];
 }
 
-export function useDeclaration(stainlessPath: string, language?: SpecLanguage) {
-  return useSpec()?.decls?.[language ?? useLanguage()]?.[stainlessPath];
+type Declaration = LanguageDeclNodes[SpecLanguage];
+export function useDeclaration<Required extends boolean>(
+  stainlessPath: string,
+  required: Required,
+  language?: SpecLanguage,
+): (Required extends true ? never : undefined) | Declaration {
+  const defaultLanguage = useLanguage();
+  const decl = useSpec()?.decls?.[language ?? defaultLanguage]?.[stainlessPath];
+  if (required && !decl) {
+    throw new Error(`Declaration not found for '${stainlessPath}'`);
+  }
+  return decl!;
 }
 
 export function useResource(name: string) {

package/src/contexts/index.tsx

@@ -1,7 +1,6 @@
-import * as React from 'react';
-import { ComponentContext } from './component-generics';
 import { useLanguage } from './docs';
 import { LanguageComponentDefinition } from '../languages';
+import { useComponentContext } from './component-generics';
 
 // DO NOT re-export component contexts from here. Only export generics.
 export * from './navigation';
@@ -10,8 +9,12 @@ export * from './component-generics';
 export * from './search';
 export * from './docs';
 
-export function useLanguageComponents() {
+export function useLanguageComponents(): LanguageComponentDefinition {
   const language = useLanguage();
-  const context = React.useContext(ComponentContext);
-  return context.language[language] as LanguageComponentDefinition;
+  const context = useComponentContext();
+  const definition = context.language[language];
+  if (!definition) {
+    throw new Error(`Language component definition not found for language: ${language}`);
+  }
+  return definition;
 }