Begin doc site implementation

package.json

@@ -20,6 +20,7 @@
       "esbuild": "0.23"
     }
   },
+  "dependencies": {},
   "devDependencies": {
     "@babel/preset-typescript": "catalog:",
     "babel-preset-alloy": "workspace:~",

packages/core/api-extractor.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "<projectFolder>/dist/src/index.d.ts",
+  "apiReport": {
+    "enabled": false
+  },
+  "dtsRollup": {
+    "enabled": false
+  },
+  "docModel": {
+    "enabled": true,
+    "apiJsonFilePath": "temp/api.json"
+  },
+  "messages": {
+    "extractorMessageReporting": {
+      "ae-missing-release-tag": {
+        "logLevel": "none"
+      }
+    }
+  }
+}

packages/core/package.json

@@ -45,6 +45,7 @@
   },
   "devDependencies": {
     "@babel/cli": "catalog:",
+    "@microsoft/api-extractor": "^7.47.7",
     "@rollup/plugin-babel": "catalog:",
     "@rollup/plugin-typescript": "catalog:",
     "concurrently": "catalog:",

packages/core/src/binder.ts

@@ -1,9 +1,8 @@
 import { memo } from "@alloy-js/core/jsx-runtime";
 import { computed, reactive, Ref, shallowRef } from "@vue/reactivity";
-import { useScope } from "./components/Scope.js";
-import { createContext, useContext } from "./context.js";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { useScope } from "./context/scope.js";
 import { Refkey } from "./refkey.js";
-
 export type Metadata = object;
 
 export interface OutputSymbol {
@@ -23,12 +22,6 @@ export interface OutputScope {
   getSymbolNames(): Set<string>;
 }
 
-export const BinderContext = createContext<Binder>();
-
-export function useBinder() {
-  return useContext(BinderContext)!;
-}
-
 /**
  * The binder tracks all output scopes and symbols. Scopes are nested containers
  * for symbols.

packages/core/src/components/Declaration.tsx

@@ -1,16 +1,33 @@
 import { Children } from "@alloy-js/core/jsx-runtime";
-import { BinderContext, OutputSymbol } from "../binder.js";
-import { createContext, useContext } from "../context.js";
+import { OutputSymbol } from "../binder.js";
+import { createContext, useContext, ComponentContext } from "../context.js";
 import { Refkey, refkey } from "../refkey.js";
-
-export const DeclarationContext = createContext<OutputSymbol>();
+import { BinderContext } from "../context/binder.js";
+import { DeclarationContext } from "../context/declaration.js";
 
 export interface DeclarationProps {
   name?: string;
   refkey?: Refkey;
   symbol?: OutputSymbol;
   children?: Children;
 }
+
+/**
+ * Declares a symbol in the current scope for this component's children.
+ *
+ * @remarks
+ *
+ * This component must be called in one of two ways: with a name and an optional refkey,
+ * or else passing in the symbol. When called with a name and refkey, a symbol will be
+ * created in the current scope with that name and refkey. If a refkey is not provided,
+ * `refkey(props.name)` is used.
+ *
+ * When called with a symbol, that symbol is merely exposed via {@link DeclarationContext }. It
+ * is assumed that the caller of this component has created the symbol with the `createSymbol` API
+ * on the {@link BinderContext }.
+ *
+ * @see {@link BinderContext}
+ */
 export function Declaration(props: DeclarationProps) {
   const binder = useContext(BinderContext);
   if (!binder) {

packages/core/src/components/Indent.tsx

@@ -1,11 +1,6 @@
 import { Children } from "@alloy-js/core/jsx-runtime";
-import { createContext, useContext } from "../context.js";
-
-export const IndentContext = createContext<IndentState>({
-  level: 0,
-  indent: "  ",
-  indentString: "",
-});
+import { useContext } from "../context.js";
+import { IndentContext } from "../context/indent.js";
 
 export interface IndentProps {
   children?: Children;

packages/core/src/components/Output.tsx

@@ -1,13 +1,17 @@
 import { Children } from "@alloy-js/core/jsx-runtime";
 import {
-  BinderContext,
   createOutputBinder,
   getSymbolCreator,
   SymbolCreator,
 } from "../binder.js";
-import { NamePolicy, NamePolicyContext } from "../name-policy.js";
+import { NamePolicy } from "../name-policy.js";
 import { SourceDirectory } from "./SourceDirectory.js";
 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { SourceFile } from "./SourceFile.js";
+import { BinderContext } from "../context/binder.js";
+import { NamePolicyContext } from "../context/name-policy.js";
+
 export interface OutputProps {
   children?: Children;
   /**
@@ -31,6 +35,13 @@ export interface OutputProps {
   basePath?: string;
 }
 
+/**
+ * This component is the root component for all your emitted output. Place your
+ * various {@link SourceDirectory} and {@link SourceFile} components inside
+ * `Output` to create directories and files in your output directory.
+ *
+ * @see {@link NamePolicyContext}
+ */
 export function Output(props: OutputProps) {
   const basePath = props.basePath ?? "./";
   const binder = createOutputBinder({

packages/core/src/components/Scope.tsx

@@ -1,6 +1,8 @@
 import { Children } from "@alloy-js/core/jsx-runtime";
-import { BinderContext, OutputScope } from "../binder.js";
-import { createContext, useContext } from "../context.js";
+import { OutputScope } from "../binder.js";
+import { useContext } from "../context.js";
+import { BinderContext } from "../context/binder.js";
+import { ScopeContext } from "../context/scope.js";
 
 export interface ScopeProps {
   kind?: string;
@@ -9,12 +11,6 @@ export interface ScopeProps {
   children?: Children;
 }
 
-export const ScopeContext = createContext<OutputScope>();
-
-export function useScope() {
-  return useContext(ScopeContext)!;
-}
-
 export function Scope(props: ScopeProps) {
   let scope: OutputScope;
   if (props.value) {

packages/core/src/components/SourceDirectory.tsx

@@ -1,16 +1,8 @@
 import { Children, getContext } from "@alloy-js/core/jsx-runtime";
 import { shallowReactive } from "@vue/reactivity";
 import { join } from "pathe";
-import { createContext, useContext } from "../context.js";
-import { SourceFileContext } from "./SourceFile.js";
-
-export interface SourceDirectoryContext {
-  contents: (SourceDirectoryContext | SourceFileContext)[];
-  addContent(content: SourceDirectoryContext | SourceFileContext): void;
-  path: string;
-}
-
-export const SourceDirectoryContext = createContext<SourceDirectoryContext>();
+import { useContext } from "../context.js";
+import { SourceDirectoryContext } from "../context/source-directory.js";
 
 export interface SourceDirectoryProps {
   path: string;
@@ -37,7 +29,7 @@ function createSourceDirectoryContext(
 ): SourceDirectoryContext {
   const contents = shallowReactive([] as any);
   const context: SourceDirectoryContext = {
-    path,
+    path: parentDir ? join(parentDir.path, path) : path,
     contents,
     addContent(content) {
       contents.push(content);

packages/core/src/components/SourceFile.tsx

@@ -4,9 +4,10 @@ import {
   getContext,
 } from "@alloy-js/core/jsx-runtime";
 import { join } from "pathe";
-import { createContext, useContext } from "../context.js";
+import { useContext } from "../context.js";
 import { Refkey } from "../refkey.js";
-import { SourceDirectoryContext } from "./SourceDirectory.js";
+import { SourceDirectoryContext } from "../context/source-directory.js";
+import { SourceFileContext } from "../context/source-file.js";
 
 export interface SourceFileProps {
   path: string;
@@ -15,14 +16,6 @@ export interface SourceFileProps {
   reference?: ComponentDefinition<{ refkey: Refkey }>;
 }
 
-export interface SourceFileContext {
-  path: string;
-  filetype: string;
-  reference?: ComponentDefinition<{ refkey: Refkey }>;
-}
-
-export const SourceFileContext = createContext<SourceFileContext>();
-
 export function SourceFile(props: SourceFileProps) {
   const parentDirectory = useContext(SourceDirectoryContext)!;
   const context: SourceFileContext = {

packages/core/src/index.ts

@@ -1,14 +1,4 @@
 export * from "@alloy-js/core/jsx-runtime";
-export * from "./binder.js";
-export * from "./code.js";
-export * from "./components/index.js";
-export * from "./context.js";
-export * from "./jsx-runtime.js";
-export * from "./name-policy.js";
-export * from "./refkey.js";
-export * from "./render.js";
-export * from "./utils.js";
-
 export {
   computed,
   isProxy,
@@ -19,3 +9,13 @@ export {
   toRaw,
   type Ref,
 } from "@vue/reactivity";
+export * from "./binder.js";
+export * from "./code.js";
+export * from "./components/index.js";
+export * from "./context.js";
+export * from "./context/index.js";
+export * from "./jsx-runtime.js";
+export * from "./name-policy.js";
+export * from "./refkey.js";
+export * from "./render.js";
+export * from "./utils.js";

packages/core/src/name-policy.ts

@@ -1,19 +1,7 @@
-import { createContext, useContext } from "./context.js";
-
 export interface NamePolicy<TElements extends string> {
   getName(originalName: string, element: TElements): string;
 }
 
-export const NamePolicyContext = createContext<NamePolicy<string>>({
-  getName(name) {
-    return name;
-  },
-});
-
-export function useNamePolicy() {
-  return useContext(NamePolicyContext)!;
-}
-
 export function createNamePolicy<T extends string>(
   namer: (name: string, elements: T) => string,
 ): NamePolicy<T> {

packages/core/src/render.ts

@@ -9,9 +9,10 @@ import {
   untrack,
 } from "@alloy-js/core/jsx-runtime";
 import { isRef } from "@vue/reactivity";
-import { Indent, IndentContext, IndentState } from "./components/Indent.js";
-import { SourceFileContext } from "./components/SourceFile.js";
+import { Indent, IndentState } from "./components/Indent.js";
 import { useContext } from "./context.js";
+import { IndentContext } from "./context/indent.js";
+import { SourceFileContext } from "./context/source-file.js";
 import { isRefkey } from "./refkey.js";
 
 /**

packages/core/src/utils.ts

@@ -101,22 +101,23 @@ export function mapJoin<T, U, V>(
  *
  * @see {@link mapJoin} for mapping before joining.
  * @param src
- * @param rawOptions
+ * @param options
  * @returns The joined array
  */
 export function join<T>(
   src: T[] | Iterator<T>,
-  rawOptions: JoinOptions = {},
+  options: JoinOptions = {},
 ): (T | string)[] {
-  const options = { ...defaultJoinOptions, ...rawOptions };
+  const mergedOptions = { ...defaultJoinOptions, ...options };
   const joined = [];
-  const ender = options.ender === true ? options.joiner : options.ender;
+  const ender =
+    mergedOptions.ender === true ? mergedOptions.joiner : mergedOptions.ender;
   src = Array.from(src as Iterable<T>);
 
   for (const [index, item] of src.entries()) {
     joined.push(item);
     if (index !== src.length - 1) {
-      joined.push(options.joiner!);
+      joined.push(mergedOptions.joiner!);
     }
   }
 
@@ -129,9 +130,9 @@ export function join<T>(
 
 /**
  * Returns a memo which is a list of all the provided children.
- * If you want this as an array, see childrenArray.
+ * If you want this as an array, see {@link childrenArray}.
  */
-export function children(fn: () => Children) {
+export function children(fn: () => Children): () => Children {
   return memo(() => collectChildren(fn()));
 
   function collectChildren(children: Children): Children {
@@ -148,7 +149,7 @@ export function children(fn: () => Children) {
   }
 }
 
-export function childrenArray(fn: () => Children) {
+export function childrenArray(fn: () => Children): Child[] {
   const c = children(fn)();
   if (Array.isArray(c)) {
     return c;

packages/core/test/components/source-file.test.tsx

@@ -3,12 +3,12 @@ import {
   Output,
   render,
   renderTree,
-  SourceDirectoryContext,
   SourceFile,
   useContext,
 } from "@alloy-js/core";
 import { expect, it } from "vitest";
 import "../../testing/extend-expect.js";
+import { SourceDirectoryContext } from "../../src/context/source-directory.js";
 
 it("tracks its content", () => {
   let context;

packages/docs/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

packages/docs/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

packages/docs/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}