@alloy-js/core 0.7.0 → 0.8.0

package/src/binder.ts

@@ -127,6 +127,11 @@ export interface OutputSymbol {
    * one static member symbol in the output (i.e., the symbol is unique).
    */
   staticMemberScope?: OutputScope;
+
+  /**
+   * Additional custom metadata about this symbol.
+   */
+  metadata: Record<string, unknown>;
 }
 
 /**
@@ -175,7 +180,7 @@ export interface OutputScope {
    * The kind of scope. Subtypes will likely provide a set of known scope kinds.
    * The kind is not used by the binder itself.
    */
-  kind: string;
+  kind?: string;
 
   /**
    * The name of the scope.
@@ -227,9 +232,9 @@ export interface OutputScope {
 export type CreateSymbolOptions<T extends OutputSymbol = OutputSymbol> = {
   name: string;
   scope?: OutputScope;
-  refkey?: Refkey;
-  refkeys?: Refkey[];
+  refkey?: Refkey | Refkey[];
   flags?: OutputSymbolFlags;
+  metadata?: Record<string, unknown>;
 } & Omit<T, keyof OutputSymbol>;
 
 export type CreateScopeOptions<T extends OutputScope = OutputScope> = {
@@ -238,6 +243,7 @@ export type CreateScopeOptions<T extends OutputScope = OutputScope> = {
   parent?: OutputScope | undefined;
   flags?: OutputScopeFlags;
   owner?: OutputSymbol;
+  metadata?: Record<string, unknown>;
 } & Omit<T, keyof OutputScope>;
 
 /**
@@ -370,15 +376,11 @@ export interface Binder {
  * When we resolve the refkey for `bar` from within `namespace scope 2`, we will get the following
  * resolution result:
  *
- * **targetDeclaration**: symbol bar, the symbol we resolved.
- *
- * **commonScope**: global scope, because this is the most specific scope that contains both the declaration and the reference.
- *
- * **pathUp**: [namespace scope 2], because this is the scope between the reference and the common scope.
- *
- * **pathDown**: [namespace scope 1], because this is the scope between the common scope and the declaration
- *
- * **memberPath**: [foo, bar], because we resolved a member symbol and these are the symbols that lead from the base declaration to the member symbol.
+ * * **targetDeclaration**: symbol bar, the symbol we resolved.
+ * * **commonScope**: global scope, because this is the most specific scope that contains both the declaration and the reference.
+ * * **pathUp**: [namespace scope 2], because this is the scope between the reference and the common scope.
+ * * **pathDown**: [namespace scope 1], because this is the scope between the common scope and the declaration
+ * * **memberPath**: [foo, bar], because we resolved a member symbol and these are the symbols that lead from the base declaration to the member symbol.
  */
 export interface ResolutionResult<
   TScope extends OutputScope,
@@ -467,6 +469,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       parent,
       owner,
       flags = OutputScopeFlags.None,
+      metadata = {},
       ...rest
     } = args;
 
@@ -499,6 +502,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       flags,
       owner,
       binder,
+      metadata,
       ...rest,
       getSymbolNames: symbolNames(symbols),
     }) as T;
@@ -525,19 +529,12 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       name,
       scope = useDefaultScope(args.flags),
       refkey,
-      refkeys,
       flags = OutputSymbolFlags.None,
+      metadata = {},
       ...rest
     } = args;
 
-    const allRefkeys = [];
-    if (refkey) {
-      allRefkeys.push(refkey);
-    }
-
-    if (refkeys) {
-      allRefkeys.push(...refkeys);
-    }
+    const allRefkeys = [refkey ?? []].flat();
 
     if (!scope) {
       throw new Error(
@@ -570,6 +567,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       refkeys: allRefkeys,
       binder,
       flags,
+      metadata,
       ...rest,
     }) as T;
 
@@ -634,8 +632,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
         createSymbol({
           name: sym.name,
           scope: target.instanceMemberScope!,
-          // todo: fix this or change this or something??
-          refkeys: [refkey(target.refkeys[0], sym.refkeys[0])],
+          refkey: [refkey(target.refkeys[0], sym.refkeys[0])],
           flags: sym.flags | OutputSymbolFlags.InstanceMember,
         });
       }
@@ -709,12 +706,6 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     targetDeclarationBase: TSymbol,
   ): ResolutionResult<TScope, TSymbol> {
     if (targetDeclarationBase.flags & OutputSymbolFlags.InstanceMember) {
-      if (targetDeclarationBase.scope !== currentMemberScope) {
-        throw new Error(
-          "Cannot resolve member symbols from a different member scope",
-        );
-      }
-
       // todo: handle referencing nested objects by refkey
       return {
         pathUp: [],

package/src/code.ts

@@ -1,17 +1,51 @@
 // this code is split into a tokenizer and a parser of sorts because I feel like
-// it should be psosible to share logic between this and the babel transform, but
+// it should be possible to share logic between this and the babel transform, but
 // this is an exercise for the future.
-import { hbr, indent } from "./components/stc/index.js";
+import { hbr, indent } from "./components/stc/sti.js";
 import { Child, Children } from "./jsx-runtime.js";
+
+export function text(
+  template: TemplateStringsArray,
+  ...substitutions: Children[]
+): Children {
+  const children = [];
+  // push the literal parts and the substitutions into the children array. The
+  // first part has all leading whitespace removed, the last part has all
+  // trailing whitespace removed, and each part in the middle replaces any
+  // amount of whitespace with a single space.
+
+  for (let i = 0; i < template.length; i++) {
+    let part = template[i];
+    part = part
+      .replace(/(^(\s*\r?\n\s*)+)|((\s*\r?\n\s*)+$)/g, "")
+      .replace(/(\s*\r?\n\s*)+/g, " ");
+    children.push(part);
+    if (i < substitutions.length) {
+      children.push(substitutions[i]);
+    }
+  }
+
+  return children;
+}
+
 interface IndentLevelData {
   kind: "indent";
   children: (string | Children | IndentLevelData)[];
   pendingLines: string[];
 }
+
+/**
+ * Turn the provided string template into Children by replacing literal line
+ * breaks with hardlines and automatically indenting indented content. Similar
+ * in spirit to the `<code>` element in HTML.
+ *
+ * @see {@link text} for a similar function which treats whitespace similar to
+ * JSX template bodies.
+ */
 export function code(
   template: TemplateStringsArray,
   ...substitutions: Children[]
-) {
+): Children {
   const indentNodes: IndentLevelData[] = [
     {
       kind: "indent",

package/src/components/Block.tsx

@@ -23,8 +23,8 @@ export interface BlockProps {
 
 /**
  * Create an indented block of source text. The block has `opener` text which is
- * added prior to the block, which defaults to "\{", and `closer` text which is
- * added after the block, which defaults to "\}".
+ * added prior to the block, which defaults to `"{"`, and `closer` text which is
+ * added after the block, which defaults to `"}"`.
  */
 export function Block(props: BlockProps) {
   const childCount = computed(() => childrenArray(() => props.children).length);
@@ -32,12 +32,9 @@ export function Block(props: BlockProps) {
     <group>
       {props.newline && <br />}
       {props.opener ?? "{"}
-      <Indent break={childCount.value > 0 ? "hard" : "soft"}>
+      <Indent softline={childCount.value === 0} trailingBreak>
         {props.children}
       </Indent>
-      {childCount.value > 0 ?
-        <hbr />
-      : <sbr />}
       {props.closer ?? "}"}
     </group>
   );

package/src/components/Declaration.tsx

@@ -3,15 +3,48 @@ import { useContext } from "../context.js";
 import { BinderContext } from "../context/binder.js";
 import { DeclarationContext } from "../context/declaration.js";
 import { Children, onCleanup } from "../jsx-runtime.js";
-import { Refkey, refkey } from "../refkey.js";
+import { Refkey } from "../refkey.js";
+
+/**
+ * Create a declaration by providing an already created symbol. The symbol is
+ * merely exposed via {@link DeclarationContext}.
+ */
+export interface DeclarationPropsWithSymbol {
+  /**
+   * The symbol being declared. When provided, the name, refkey, and metadata
+   * props are ignored.
+   */
+  symbol: OutputSymbol;
+
+  children?: Children;
+}
+
+/**
+ * Create a declaration by providing a symbol name and optional symbol metadata.
+ */
+export interface DeclarationPropsWithInfo {
+  /**
+   * The name of this declaration.
+   */
+  name: string;
+
+  /**
+   * The unique key or array of unique keys for this declaration.
+   */
+  refkey?: Refkey | Refkey[];
+
+  /**
+   * Additional metadata for the declared symbol.
+   */
+  metadata?: Record<string, unknown>;
 
-export interface DeclarationProps {
-  name?: string;
-  refkey?: Refkey;
-  symbol?: OutputSymbol;
   children?: Children;
 }
 
+export type DeclarationProps =
+  | DeclarationPropsWithSymbol
+  | DeclarationPropsWithInfo;
+
 /**
  * Declares a symbol in the current scope for this component's children.
  *
@@ -20,11 +53,10 @@ export interface DeclarationProps {
  * 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 (provided by
- * {@link ScopeContext}) with that name and refkey. If a refkey is not provided,
- * `refkey(props.name)` is used.
+ * {@link ScopeContext}) with that name and refkey.
  *
  * When called with a symbol, that symbol is merely exposed via
- * {@link DeclarationContext }. It is assumed that the caller of this component
+ * {@link DeclarationContext}. It is assumed that the caller of this component
  * has created the symbol with the `createSymbol` API on the
  * {@link BinderContext }.
  *
@@ -37,13 +69,13 @@ export function Declaration(props: DeclarationProps) {
   }
 
   let declaration;
-  if (props.symbol) {
+  if ("symbol" in props) {
     declaration = props.symbol;
   } else {
-    const rk = props.refkey ? props.refkey : refkey(props.name);
     declaration = binder.createSymbol({
       name: props.name!,
-      refkey: rk,
+      refkey: props.refkey,
+      metadata: props.metadata,
     });
 
     onCleanup(() => {

package/src/components/For.tsx

@@ -1,7 +1,7 @@
 import { Children, memo } from "@alloy-js/core/jsx-runtime";
 import { isRef, Ref } from "@vue/reactivity";
-import { mapJoin } from "../utils.js";
-import { BaseListProps, baseListPropsToMapJoinArgs } from "./List.jsx";
+import { baseListPropsToMapJoinArgs, mapJoin } from "../utils.js";
+import { BaseListProps } from "./List.jsx";
 
 export type ForCallbackArgs<T> =
   T extends Ref<infer U> ? ForCallbackArgs<U>
@@ -27,6 +27,13 @@ export interface ForProps<
    * A function to call for each item.
    */
   children: (...args: [...ForCallbackArgs<T>, index: number]) => U;
+
+  /**
+   * Whether to skip falsy values. By default, falsy values are mapped. However,
+   * when mapping children, it is useful to skip falsy values, as it enables
+   * omitting list elements via patterns like `{condition && <ListItem />}`.
+   */
+  skipFalsy?: boolean;
 }
 
 export type ForSupportedCollections = any[] | Map<any, any> | Set<any>;
@@ -66,7 +73,7 @@ export function For<
 >(props: ForProps<T, U>) {
   const cb = props.children;
   const options = baseListPropsToMapJoinArgs(props);
-  options.skipFalsy = true;
+  options.skipFalsy = props.skipFalsy;
   return memo(() => {
     const maybeRef = props.each;
 

package/src/components/Indent.tsx

@@ -2,17 +2,50 @@ import { Children } from "@alloy-js/core/jsx-runtime";
 
 export interface IndentProps {
   children: Children;
+  /**
+   * Don't include a line break. The new indentation level will start after the
+   * first linebreak within the children.
+   */
   nobreak?: boolean;
-  break?: "space" | "soft" | "hard";
+
+  /**
+   * Use a regular line (`<br />`) to start (and optionally end with
+   * `trailingBreak`) the new indentation level.
+   */
+  line?: boolean;
+
+  /**
+   * Use a soft line (`<sbr />`) to start (and optionally end with
+   * `trailingBreak`) the new indentation level.
+   */
+  softline?: boolean;
+
+  /**
+   * Use a hard line (`<hbr />`) to start (and optionally end with
+   * `trailingBreak`) the new indentation level.
+   */
+  hardline?: boolean;
+
+  /**
+   * Place the configured line break at the end of the block after restoring the
+   * indentation level.
+   */
   trailingBreak?: boolean;
 }
+
+/**
+ * Create an indented block of source text. The indented block starts a new line
+ * at the new indentation level and, with `trailingBreak`, ends with a new line
+ * after restoring the indentation level. The default line break is a hard line
+ * break suitable for typical blocks of statements but can be configured.
+ */
 export function Indent(props: IndentProps) {
-  const breakStyle = props.break ?? "hard";
   const breakElem =
     props.nobreak ? ""
-    : breakStyle === "hard" ? <hbr />
-    : breakStyle === "soft" ? <sbr />
-    : <br />;
+    : props.hardline ? <hbr />
+    : props.softline ? <sbr />
+    : props.line ? <br />
+    : <hbr />;
 
   return (
     <>

package/src/components/List.tsx

@@ -1,9 +1,7 @@
 import { Children, memo, splitProps } from "@alloy-js/core/jsx-runtime";
-import { childrenArray, JoinOptions } from "../utils.js";
+import { childrenArray } from "../utils.js";
 import { For } from "./For.jsx";
 
-export type BreakKind = "none" | "space" | "soft" | "hard" | "literal";
-
 export interface BaseListProps {
   /** Text to place between each element */
   joiner?: Children;
@@ -14,10 +12,22 @@ export interface BaseListProps {
   /** Place a semicolon between each element */
   semicolon?: boolean;
 
+  /** Place a regular line (`<br />`) between each element */
   line?: boolean;
+
+  /** Place a softline (`<sbr />`) between each element */
   softline?: boolean;
+
+  /** Place a hardline (`<hbr />`) between each element */
   hardline?: boolean;
+
+  /** Place two hardlines between each element */
+  doubleHardline?: boolean;
+
+  /** Place a literal line (`<lbr />`) between each element */
   literalline?: boolean;
+
+  /** Place a space between each element */
   space?: boolean;
 
   /**
@@ -32,42 +42,6 @@ export interface BaseListProps {
   enderPunctuation?: boolean;
 }
 
-export function baseListPropsToMapJoinArgs(props: BaseListProps): JoinOptions {
-  let joiner, punctuation;
-  if ("joiner" in props) {
-    joiner = props.joiner;
-  } else {
-    punctuation =
-      props.comma ? ","
-      : props.semicolon ? ";"
-      : "";
-
-    joiner = (
-      <>
-        {punctuation}
-        {props.softline ?
-          <sbr />
-        : props.hardline ?
-          <hbr />
-        : props.literalline ?
-          <lbr />
-        : props.line ?
-          <br />
-        : props.space ?
-          <> </>
-        : <hbr />}
-      </>
-    );
-  }
-
-  const ender =
-    "ender" in props ? props.ender
-    : props.enderPunctuation ? punctuation
-    : undefined;
-
-  return { joiner, ender };
-}
-
 export interface ListProps extends BaseListProps {
   children?: Children;
 }
@@ -87,7 +61,7 @@ export function List(props: ListProps) {
     }),
   );
   return (
-    <For each={resolvedChildren} {...forProps}>
+    <For each={resolvedChildren} {...forProps} skipFalsy>
       {(child) => child}
     </For>
   );

package/src/components/MemberDeclaration.tsx

@@ -3,16 +3,54 @@ import { useContext } from "../context.js";
 import { BinderContext } from "../context/binder.js";
 import { MemberDeclarationContext } from "../context/member-declaration.js";
 import { Children } from "../jsx-runtime.js";
-import { Refkey, refkey } from "../refkey.js";
+import { Refkey } from "../refkey.js";
 
-export interface MemberDeclarationProps {
-  name?: string;
-  refkey?: Refkey;
-  symbol?: OutputSymbol;
-  children?: Children;
+/**
+ * Create a member declaration by providing a symbol name and optional symbol
+ * metadata.
+ */
+export interface MemberDeclarationPropsWithInfo {
+  /**
+   * The name of this declaration.
+   */
+  name: string;
+
+  /**
+   * The refkey or array refkeys for this declaration.
+   */
+  refkey?: Refkey | Refkey[];
+
+  /**
+   * Additional metadata for the declared symbol.
+   */
+  metadata?: Record<string, unknown>;
+
+  /**
+   * Whether this is a static member. If not provided, the member is an instance
+   * member.
+   */
   static?: boolean;
+  children?: Children;
 }
 
+/**
+ * Create a declaration by providing an already created symbol. The symbol is
+ * merely exposed via {@link DeclarationContext}.
+ */
+export interface MemberDeclarationPropsWithSymbol {
+  /**
+   * The symbol being declared. When provided, the name, refkey, and metadata
+   * props are ignored.
+   */
+  symbol: OutputSymbol;
+
+  children?: Children;
+}
+
+export type MemberDeclarationProps =
+  | MemberDeclarationPropsWithInfo
+  | MemberDeclarationPropsWithSymbol;
+
 /**
  * Declares a symbol in the current member scope for this component's children.
  *
@@ -38,20 +76,21 @@ export function MemberDeclaration(props: MemberDeclarationProps) {
   }
 
   let declaration;
-  if (props.symbol) {
+  if ("symbol" in props && props.symbol) {
     declaration = props.symbol;
   } else {
-    if (!props.name) {
+    const infoProps = props as MemberDeclarationPropsWithInfo;
+    if (!infoProps.name) {
       throw new Error(
         "Must provide a member name, or else provide a member symbol",
       );
     }
-    const rk = props.refkey ? props.refkey : refkey(props.name);
     declaration = binder.createSymbol({
-      name: props.name!,
-      refkey: rk,
+      name: infoProps.name!,
+      refkey: infoProps.refkey,
+      metadata: infoProps.metadata,
       flags:
-        props.static ?
+        infoProps.static ?
           OutputSymbolFlags.StaticMember
         : OutputSymbolFlags.InstanceMember,
     });

package/src/components/MemberScope.tsx

@@ -28,6 +28,8 @@ export interface MemberScopeProps {
  *
  * The member scope contains scopes for both instance and static members.
  * However, it does not affect the resolution of static members.
+ *
+ * @see {@link (MemberScopeContext:variable)}
  */
 export function MemberScope(props: MemberScopeProps) {
   const context: MemberScopeContext = {

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 (