@alloy-js/core 0.6.0 → 0.8.0

package/src/components/Prose.tsx

@@ -0,0 +1,35 @@
+import { childrenArray, computed } from "@alloy-js/core";
+import { Children } from "@alloy-js/core/jsx-runtime";
+
+export interface Prose {
+  children: Children;
+}
+
+/**
+ * Create a block of text which will break once a word exceeds the configured line width.
+ * The children are expected to be strings, and a <br /> is added between each word.
+ */
+export function Prose(props: Prose) {
+  const brokenChildren = computed(() => {
+    const children = childrenArray(() => props.children);
+    return children
+      .map((child) => {
+        if (typeof child === "string") {
+          return child
+            .trim()
+            .split(/\s+/)
+            .map((word) => (
+              <>
+                {word}
+                <br />
+              </>
+            ));
+        }
+
+        return child;
+      })
+      .flat(2);
+  });
+
+  return <fill>{brokenChildren.value}</fill>;
+}

package/src/components/Scope.tsx

@@ -4,21 +4,61 @@ import { BinderContext } from "../context/binder.js";
 import { ScopeContext } from "../context/scope.js";
 import { Children } from "../jsx-runtime.js";
 
-export interface ScopeProps {
+/**
+ * Declare a scope by providing an already created scope. The scope is merely
+ * exposed via {@link ScopeContext}.
+ */
+export interface ScopePropsWithValue {
+  /**
+   * The scope to use. If not provided, a new scope will be created.
+   */
+  value: OutputScope;
+
+  children?: Children;
+}
+
+/**
+ * Create a scope by providing a name and optional metadata.
+ */
+export interface ScopePropsWithInfo {
+  /**
+   * The kind of scope. This may be used by application code to determine how
+   * to handle symbols in this scope. It is not used by the core framework.
+   */
   kind?: string;
+
+  /**
+   * The name of this scope.
+   */
   name?: string;
-  value?: OutputScope;
+
+  /**
+   * Additional metadata for the scope.
+   */
+  metadata?: Record<string, unknown>;
+
   children?: Children;
 }
 
+export type ScopeProps = ScopePropsWithValue | ScopePropsWithInfo;
+
+/**
+ * Declare a scope for this component's children. Any symbols and scopes
+ * declared in the children of this component will be in this scope.
+ *
+ * @see {@link ScopeContext}
+ */
 export function Scope(props: ScopeProps) {
   let scope: OutputScope;
-  if (props.value) {
+  if ("value" in props) {
     scope = props.value;
   } else {
-    const kind = props.kind ?? "file";
     const binder = useContext(BinderContext)!;
-    scope = binder.createScope({ kind, name: props.name! });
+    scope = binder.createScope({
+      kind: props.kind,
+      metadata: props.metadata,
+      name: props.name ?? "",
+    });
   }
 
   return (

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,26 +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>;
@@ -357,6 +463,8 @@ export function taggedComponent<TProps = Props>(
 export const intrinsicElementKey = Symbol();
 
 export type IndentIntrinsicElement = IntrinsicElementBase<"indent">;
+export type IndentIfBreakIntrinsicElement =
+  IntrinsicElementBase<"indentIfBreak">;
 export type BrIntrinsicElement = IntrinsicElementBase<"br">;
 export type LineIntrinsicElement = IntrinsicElementBase<"line">;
 export type HbrIntrinsicElement = IntrinsicElementBase<"hbr">;
@@ -379,6 +487,7 @@ export type IfBreakIntrinsicElement = IntrinsicElementBase<"ifBreak">;
 
 export type IntrinsicElement =
   | IndentIntrinsicElement
+  | IndentIfBreakIntrinsicElement
   | BrIntrinsicElement
   | LineIntrinsicElement
   | HbrIntrinsicElement
@@ -514,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/render.ts

@@ -32,6 +32,7 @@ const {
     group,
     hardline,
     indent,
+    indentIfBreak,
     line,
     lineSuffix,
     lineSuffixBoundary,
@@ -348,6 +349,19 @@ function appendChild(node: RenderedTextTree, rawChild: Child) {
       switch (child.name) {
         case "indent":
           return formatHookWithChildren(indent);
+        case "indentIfBreak":
+          node.push(
+            createRenderTreeHook(newNode, {
+              print(tree, print) {
+                return indentIfBreak(print(tree), {
+                  groupId: child.props.groupId,
+                  negate: child.props.negate,
+                });
+              },
+            }),
+          );
+          renderWorker(newNode, child.props.children);
+          return;
         case "fill":
           return formatHookWithChildren(fill as any);
         case "group":

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;
+  };
+}