@alloy-js/core 0.7.0 → 0.8.0

package/src/components/SourceFile.tsx

@@ -5,6 +5,7 @@ import { SourceFileContext } from "../context/source-file.js";
 import { Children, ComponentDefinition, getContext } from "../jsx-runtime.js";
 import { Refkey } from "../refkey.js";
 import { PrintTreeOptions } from "../render.js";
+import { Show } from "./Show.jsx";
 
 export interface SourceFileProps extends PrintTreeOptions {
   /**
@@ -24,6 +25,11 @@ export interface SourceFileProps extends PrintTreeOptions {
    * contents.
    */
   reference?: ComponentDefinition<{ refkey: Refkey }>;
+  /**
+   * The header of the file. This is rendered before the contents of the file.
+   * This is useful for adding license headers or other metadata to the file.
+   */
+  header?: Children;
 }
 
 export function SourceFile(props: SourceFileProps) {
@@ -45,6 +51,10 @@ export function SourceFile(props: SourceFileProps) {
 
   return (
     <SourceFileContext.Provider value={context}>
+      <Show when={props.header !== undefined}>
+        {props.header}
+        <hbr />
+      </Show>
       {props.children}
     </SourceFileContext.Provider>
   );

package/src/components/index.tsx

@@ -8,6 +8,7 @@ export * from "./MemberName.jsx";
 export * from "./MemberScope.jsx";
 export * from "./Name.jsx";
 export * from "./Output.js";
+export * from "./Prose.jsx";
 export * from "./Scope.js";
 export * from "./Show.jsx";
 export * from "./SourceDirectory.js";

package/src/components/stc/index.ts

@@ -1,4 +1,4 @@
-import { stc, sti } from "../../stc.js";
+import { stc } from "../../stc.js";
 import * as base from "../index.js";
 
 export const Block = stc(base.Block);
@@ -11,6 +11,7 @@ export const MemberName = stc(base.MemberName);
 export const MemberScope = stc(base.MemberScope);
 export const Name = stc(base.Name);
 export const Output = stc(base.Output);
+export const Prose = stc(base.Prose);
 export const Scope = stc(base.Scope);
 export const Show = stc(base.Show);
 export const StatementList = stc(base.StatementList);
@@ -19,8 +20,4 @@ export const SourceFile = stc(base.SourceFile);
 export const Switch = stc(base.Switch);
 export const Wrap = stc(base.Wrap);
 
-export const indent = sti("indent");
-export const hbr = sti("hbr");
-export const sbr = sti("sbr");
-export const lbr = sti("lbr");
-export const br = sti("br");
+export * from "./sti.js";

package/src/components/stc/sti.ts

@@ -0,0 +1,10 @@
+import { sti } from "../../sti.js";
+
+export const indent = sti("indent");
+export const group = sti("group");
+export const ifBreak = sti("ifBreak");
+export const hbr = sti("hbr");
+export const sbr = sti("sbr");
+export const lbr = sti("lbr");
+export const br = sti("br");
+export const dedentToRoot = sti("dedentToRoot");

package/src/context/assignment.ts

@@ -52,7 +52,13 @@ export function createAssignmentContext(
   };
 }
 
-export function getAssignmentSymbol() {
+/**
+ * Get the symbol being defined.
+ *
+ * @returns The symbol currently being defined, or `undefined` if no symbol is
+ * being defined.
+ */
+export function getAssignmentSymbol(): OutputSymbol | undefined {
   const assignmentContext = useContext(AssignmentContext);
   if (assignmentContext) {
     return assignmentContext.target;

package/src/context.ts

@@ -5,11 +5,13 @@ import {
   effect,
   getContext,
 } from "./jsx-runtime.js";
+import { stc, StcSignature } from "./stc.js";
 
 export interface ComponentContext<T> {
   id: symbol;
   default: T | undefined;
   Provider: ComponentDefinition<ContextProviderProps<T>>;
+  ProviderStc: StcSignature<ContextProviderProps<T>>;
   name?: string;
 }
 
@@ -38,21 +40,23 @@ export function createContext<T = unknown>(
   name?: string,
 ): ComponentContext<T> {
   const id = Symbol(name ?? "context");
+  function Provider(props: ContextProviderProps<T>) {
+    const context = getContext();
+
+    const rendered = shallowRef();
+    effect(() => {
+      context!.context![id] = props.value;
+      rendered.value = () => props.children;
+    }, undefined);
+
+    return rendered.value;
+  }
   const ctx = {
     id,
     default: defaultValue,
     name,
-    Provider(props: ContextProviderProps<T>) {
-      const context = getContext();
-
-      const rendered = shallowRef();
-      effect(() => {
-        context!.context![id] = props.value;
-        rendered.value = () => props.children;
-      }, undefined);
-
-      return rendered.value;
-    },
+    Provider,
+    ProviderStc: stc(Provider),
   };
   contextsByKey.set(id, ctx);
   return ctx;

package/src/index.ts

@@ -18,6 +18,7 @@ export * from "./name-policy.js";
 export * from "./refkey.js";
 export * from "./render.js";
 export * from "./stc.js";
+export * from "./sti.js";
 export * from "./tap.js";
 export * from "./utils.js";
 export * from "./write-output.js";

package/src/jsx-runtime.ts

@@ -1,6 +1,7 @@
 // Much of the implementations in this file are inspired by vuerx-js
 // See: https://github.com/ryansolid/vuerx-jsx.
 import {
+  computed,
   isReactive,
   pauseTracking,
   proxyRefs,
@@ -294,27 +295,131 @@ export function isComponentCreator(item: unknown): item is ComponentCreator {
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace JSX {
   export interface IntrinsicElements {
+    /**
+     * Attempt to render the children on a single line if possible. If a group
+     * contains `<breakParent />` or a hard line, or if the group exceeds the
+     * print width, all linebreaks in the group will be broken.
+     */
     group: { shouldBreak?: boolean; id?: symbol; children: Children };
+
+    /**
+     * A regular line break. This will break if the line exceeds the print
+     * width, otherwise it will be a space.
+     */
     line: {};
+
+    /**
+     * A regular line break. This will break if the line exceeds the print
+     * width, otherwise it will be a space.
+     */
     br: {};
+
+    /**
+     * A hard line break. This is a line that will always break, even if the
+     * group does not exceed print width.
+     */
     hardline: {};
+
+    /**
+     * A hard line break. This is a line that will always break, even if the
+     * group does not exceed print width.
+     */
     hbr: {};
+
+    /**
+     * A soft line break. This will break if the line exceeds the print width,
+     * otherwise it will be be nothing.
+     */
     softline: {};
+
+    /**
+     * A soft line break. This will break if the line exceeds the print width,
+     * otherwise it will be be nothing.
+     */
     sbr: {};
+
+    /**
+     * A literal line break. This will always break, even if the group does not
+     * exceed print width. The new line will ignore indentation.
+     */
     literalline: {};
+
+    /**
+     * A literal line break. This will always break, even if the group does not
+     * exceed print width. The new line will ignore indentation.
+     */
     lbr: {};
+
+    /**
+     * Increase the indentation level of the children of this component.
+     * Indentation is determined by the print options provided to the Output
+     * component or source file.
+     */
     indent: { children: Children };
+
+    /**
+     * Indent the children of this component if the group specified by `groupId`
+     * is broken (or not broken if `negate` is passed). The specified group must
+     * already be printed.
+     */
     indentIfBreak: { children: Children; groupId: symbol; negate?: boolean };
+
+    /**
+     * Similar to `group`, but will only place a line break before the last
+     * segment to exceed the print width. This is useful for formatting
+     * paragraphs of text where breaks are inserted prior to words which would
+     * otherwise exceed the print width.
+     */
     fill: { children: Children };
+
+    /**
+     * Force the parent group to break.
+     */
     breakParent: {};
+
+    /**
+     * Print children if the current group or already printed group specified by
+     * `groupId` is broken. Otherwise, `flatContents` is printed instead.
+     */
     ifBreak: { children: Children; flatContents?: Children; groupId?: symbol };
+
+    /**
+     * Print this content at the end of the line. Useful for things like line
+     * comments.
+     */
     lineSuffix: { children: Children };
+
+    /**
+     * Force any line suffixes to print at this point.
+     */
     lineSuffixBoundary: {};
+
+    /**
+     * Decrease the indentation level of the children of this component.
+     * Indentation is determined by the print options provided to the Output
+     * component or source file.
+     */
     dedent: { children: Children };
+
+    /**
+     * Indent the children of this component by either the number of characters
+     * indicated by the `width` prop, or by the provided string indicated by the
+     * `string` prop.
+     */
     align:
       | { children: Children; width: number }
       | { children: Children; string: string };
+
+    /**
+     * Mark the current indentation level as "root" for the purposes of literal
+     * line breaks and `dedentToRoot`.
+     */
     markAsRoot: { children: Children };
+
+    /**
+     * Decrease the indentation level to the root level specified by
+     * `<markAsRoot />`, or else to no indentation.
+     */
     dedentToRoot: { children: Children };
   }
   export type ElementType = string | ComponentDefinition<any>;
@@ -518,6 +623,59 @@ export function splitProps<
   return [...result, remaining] as any;
 }
 
+/**
+ * Applies default values to a props object. Reactive props are handled properly
+ * by ensuring that their value is not accessed by `defaultProps`, avoiding any
+ * unintended side effects.
+ */
+export function defaultProps<T extends {}>(props: T, defaults: Partial<T>): T {
+  if (isReactive(props)) {
+    const refs = untrack(() => toRefs(props));
+    for (const key in defaults) {
+      const originalRef = refs[key];
+      refs[key] = computed(() =>
+        originalRef.value === undefined ? defaults[key] : originalRef.value,
+      ) as any;
+    }
+
+    return proxyRefs(refs);
+  }
+  const withDefaults = {} as T;
+  const copied = new Set<string>();
+  for (const key in defaults) {
+    copied.add(key);
+    const desc = Object.getOwnPropertyDescriptor(props, key);
+    if (!desc) {
+      withDefaults[key] = defaults[key]!;
+      continue;
+    }
+
+    if (desc.get) {
+      const originalGet = desc.get;
+      desc.get = function () {
+        const value = originalGet.call(this);
+        return value === undefined ? defaults[key as keyof T] : value;
+      };
+      Object.defineProperty(withDefaults, key, desc);
+    } else {
+      desc.value =
+        desc.value === undefined ? defaults[key as keyof T] : desc.value;
+      Object.defineProperty(withDefaults, key, desc);
+    }
+  }
+
+  const descriptors = Object.getOwnPropertyDescriptors(props);
+  for (const key in descriptors) {
+    if (copied.has(key)) {
+      continue;
+    }
+
+    Object.defineProperty(withDefaults, key, descriptors[key]);
+  }
+
+  return withDefaults;
+}
+
 function shouldDebug() {
   return typeof process !== "undefined" && !!process.env?.ALLOY_DEBUG;
 }

package/src/stc.ts

@@ -2,71 +2,40 @@ import {
   Children,
   ComponentCreator,
   ComponentDefinition,
-  createIntrinsic,
-  IntrinsicElementBase,
-  JSX,
 } from "@alloy-js/core/jsx-runtime";
-import { code } from "./code.js";
-
-export function sti<T extends keyof JSX.IntrinsicElements>(name: T) {
-  return (
-    ...args: unknown extends T ? []
-    : {} extends Omit<JSX.IntrinsicElements[T], "children"> ?
-      [props?: JSX.IntrinsicElements[T]]
-    : [props: JSX.IntrinsicElements[T]]
-  ) => {
-    const props: JSX.IntrinsicElements[T] | undefined = args[0];
-    const fn = () => createIntrinsic(name, props!);
-    fn.children = (
-      ...children: Children[]
-    ): (() => IntrinsicElementBase<T>) => {
-      const propsWithChildren = {
-        ...(props ?? {}),
-        children,
-      };
-
-      return () => createIntrinsic(name, propsWithChildren as any);
-    };
-
-    fn.code = (
-      template: TemplateStringsArray,
-      ...substitutions: Children[]
-    ): (() => IntrinsicElementBase<T>) => {
-      const propsWithChildren = {
-        ...(args[0] ?? {}),
-        children: code(template, ...substitutions),
-      };
-
-      return () => createIntrinsic(name, propsWithChildren as any);
-    };
-    return fn;
-  };
-}
+import { code, text } from "./code.js";
 
 export type MakeChildrenOptional<T extends object> =
   T extends { children?: any } ?
     Omit<T, "children"> & Partial<Pick<T, "children">>
   : T;
 
-export function stc<T extends {}>(Component: ComponentDefinition<T>) {
-  return (
-    ...args: unknown extends T ? []
-    : {} extends Omit<T, "children"> ? [props?: MakeChildrenOptional<T>]
-    : [props: MakeChildrenOptional<T>]
-  ) => {
-    const fn: ComponentCreator<T> & {
-      code(
-        template: TemplateStringsArray,
-        ...substitutions: Children[]
-      ): ComponentCreator<T>;
-      children(...children: Children[]): ComponentCreator<T>;
-    } = () => Component(args[0] as any);
+export type StcSignature<T extends {}> = (
+  ...args: unknown extends T ? []
+  : {} extends Omit<T, "children"> ? [props?: MakeChildrenOptional<T>]
+  : [props: MakeChildrenOptional<T>]
+) => StcComponentCreator<T>;
+
+export type StcComponentCreator<T> = ComponentCreator<T> & {
+  code(
+    template: TemplateStringsArray,
+    ...substitutions: Children[]
+  ): ComponentCreator<T>;
+  text(
+    template: TemplateStringsArray,
+    ...substitutions: Children[]
+  ): ComponentCreator<T>;
+  children(...children: Children[]): ComponentCreator<T>;
+};
+
+export function stc<T extends {}>(
+  Component: ComponentDefinition<T>,
+): StcSignature<T> {
+  return (...args) => {
+    const fn: StcComponentCreator<T> = () => Component(args[0] as any);
     fn.component = Component;
     fn.props = args[0]!;
-    fn.code = (
-      template: TemplateStringsArray,
-      ...substitutions: Children[]
-    ): ComponentCreator<T> => {
+    fn.code = (template, ...substitutions): ComponentCreator<T> => {
       const propsWithChildren = {
         ...(args[0] ?? {}),
         children: code(template, ...substitutions),
@@ -77,7 +46,17 @@ export function stc<T extends {}>(Component: ComponentDefinition<T>) {
       fn.props = args[0]!;
       return fn;
     };
+    fn.text = (template, ...substitutions) => {
+      const propsWithChildren = {
+        ...(args[0] ?? {}),
+        children: text(template, ...substitutions),
+      };
 
+      const fn = () => Component(propsWithChildren as any);
+      fn.component = Component;
+      fn.props = args[0]!;
+      return fn;
+    };
     fn.children = (...children: Children[]): ComponentCreator<T> => {
       const propsWithChildren = {
         ...(args[0] ?? {}),

package/src/sti.ts

@@ -0,0 +1,63 @@
+import {
+  Children,
+  createIntrinsic,
+  IntrinsicElementBase,
+  JSX,
+} from "@alloy-js/core/jsx-runtime";
+import { code, text } from "./code.js";
+
+export type StiSignature<T extends keyof JSX.IntrinsicElements> = (
+  ...args: unknown extends T ? []
+  : {} extends Omit<JSX.IntrinsicElements[T], "children"> ?
+    [props?: JSX.IntrinsicElements[T]]
+  : [props: JSX.IntrinsicElements[T]]
+) => StiComponentCreator<T>;
+
+export type StiComponentCreator<T extends keyof JSX.IntrinsicElements> =
+  (() => IntrinsicElementBase<T>) & {
+    code(
+      template: TemplateStringsArray,
+      ...substitutions: Children[]
+    ): () => IntrinsicElementBase<T>;
+    text(
+      template: TemplateStringsArray,
+      ...substitutions: Children[]
+    ): () => IntrinsicElementBase<T>;
+    children(...children: Children[]): () => IntrinsicElementBase<T>;
+  };
+
+export function sti<T extends keyof JSX.IntrinsicElements>(
+  name: T,
+): StiSignature<T> {
+  return (...args) => {
+    const props: JSX.IntrinsicElements[T] | undefined = args[0];
+    const fn: StiComponentCreator<T> = () => createIntrinsic(name, props!);
+    fn.children = (...children: Children[]) => {
+      const propsWithChildren = {
+        ...(props ?? {}),
+        children,
+      };
+
+      return () => createIntrinsic(name, propsWithChildren as any);
+    };
+
+    fn.code = (template, ...substitutions) => {
+      const propsWithChildren = {
+        ...(args[0] ?? {}),
+        children: code(template, ...substitutions),
+      };
+
+      return () => createIntrinsic(name, propsWithChildren as any);
+    };
+
+    fn.text = (template, ...substitutions) => {
+      const propsWithChildren = {
+        ...(args[0] ?? {}),
+        children: text(template, ...substitutions),
+      };
+
+      return () => createIntrinsic(name, propsWithChildren as any);
+    };
+    return fn;
+  };
+}

package/src/tap.ts

@@ -7,21 +7,72 @@ import { useScope } from "./context/scope.js";
 import { SourceFileContext } from "./context/source-file.js";
 import { ComponentDefinition } from "./jsx-runtime.js";
 
+/**
+ * The return value of {@link createTap}, this holds a reference to the tapped
+ * value. It will be undefined until the tapped value is initialized.
+ */
 export interface Tap<T> extends ComponentDefinition {
+  /** Ref for the tapped value */
   ref: ShallowRef<T | undefined>;
 }
 
+/**
+ * A function called when the Tap is rendered.
+ *
+ * @returns The tapped value.
+ */
 export interface Tapper<T> {
   (): T | undefined;
 }
 
-export interface Handler<T> {
+/**
+ * A function that is called when the tapped value is available.
+ */
+export interface TapHandler<T> {
   (value: T): void;
 }
 
+/**
+ * Create a component that when rendered, initializes the tapped value
+ * with the provided callback. This is useful for accessing context
+ * provided by child components inside a parent component.
+ *
+ * @example
+ * ```tsx
+ * import { type Children, computed, createTap } from "@alloy-js/core";
+ *
+ * // context we will tap into
+ * const SomeContext = createContext<string>();
+ *
+ * // a component which provides some specific context
+ * function MyDeclaration(props: { children: Children }) {
+ *   return <SomeContext.Provider value="Hello World">
+ *     {props.children}
+ *   </SomeContext.Provider>;
+ * }
+ *
+ * // a parent component which wants to know about the context set
+ * // by its children
+ * function MySpecialDeclaration() {
+ *   const SomeContextTap = createTap(() => useContext(SomeContext));
+ *
+ *   return <>
+ *     The declaration context is: {SomeContextTap.ref}
+ *     <MyDeclaration>
+ *       <SomeContextTap />
+ *     </MyDeclaration>
+ *   </>
+ * }
+ *
+ * @see {@link createDeclarationTap} for tapping {@link DeclarationContext}.
+ * @see {@link createMemberTap} for tapping {@link MemberDeclarationContext}.
+ * @see {@link createScopeTap} for tapping {@link OutputScope}.
+ * @see {@link createSourceFileTap} for tapping {@link SourceFileContext}.
+ * ```
+ */
 export function createTap<T = unknown>(
   tapper: Tapper<T>,
-  handler?: Handler<T>,
+  handler?: TapHandler<T>,
 ): Tap<T> {
   const signal = shallowRef<T | undefined>(undefined);
   const fn = () => {
@@ -38,31 +89,43 @@ export function createTap<T = unknown>(
   return fn;
 }
 
+/**
+ * Create a tap for {@link DeclarationContext}.
+ */
 export function createDeclarationTap<
   TSymbol extends OutputSymbol = OutputSymbol,
->(handler?: Handler<TSymbol>) {
+>(handler?: TapHandler<TSymbol>) {
   return createTap<TSymbol>(() => {
     return useContext(DeclarationContext) as any;
   }, handler);
 }
 
+/**
+ * Create a tap for {@link MemberDeclarationContext}.
+ */
 export function createMemberTap<TSymbol extends OutputSymbol = OutputSymbol>(
-  handler?: Handler<TSymbol>,
+  handler?: TapHandler<TSymbol>,
 ) {
   return createTap<TSymbol>(() => {
     return useContext(MemberDeclarationContext) as any;
   }, handler);
 }
 
+/**
+ * Create a tap for {@link OutputScope}.
+ */
 export function createScopeTap<TScope extends OutputScope = OutputScope>(
-  handler?: Handler<TScope>,
+  handler?: TapHandler<TScope>,
 ) {
   return createTap<TScope>(() => {
     return useScope() as any;
   }, handler);
 }
 
-export function createSourceFileTap(handler?: Handler<SourceFileContext>) {
+/**
+ * Create a tap for {@link (SourceFileContext:interface)}.
+ */
+export function createSourceFileTap(handler?: TapHandler<SourceFileContext>) {
   return createTap(() => {
     return useContext(SourceFileContext);
   }, handler);