@alloy-js/core 0.7.0 → 0.9.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>;
 
 /**
@@ -311,6 +317,10 @@ export interface Binder {
     key: Refkey,
   ): Ref<ResolutionResult<TScope, TSymbol> | undefined>;
 
+  getSymbolForRefkey<TSymbol extends OutputSymbol>(
+    refkey: Refkey,
+  ): Ref<TSymbol | undefined>;
+
   /**
    * Find a symbol with a given name in the given scope. Returns a ref
    * for the symbol, such that when the symbol is available, the ref value
@@ -370,15 +380,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,
@@ -424,6 +430,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     createSymbol,
     deleteSymbol,
     resolveDeclarationByKey,
+    getSymbolForRefkey,
     addStaticMembersToSymbol,
     addInstanceMembersToSymbol,
     instantiateSymbolInto,
@@ -467,6 +474,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       parent,
       owner,
       flags = OutputScopeFlags.None,
+      metadata = {},
       ...rest
     } = args;
 
@@ -499,6 +507,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       flags,
       owner,
       binder,
+      metadata,
       ...rest,
       getSymbolNames: symbolNames(symbols),
     }) as T;
@@ -525,19 +534,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 +572,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       refkeys: allRefkeys,
       binder,
       flags,
+      metadata,
       ...rest,
     }) as T;
 
@@ -634,8 +637,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 +711,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: [],
@@ -810,6 +806,25 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     }
   }
 
+  function getSymbolForRefkey<TSymbol extends OutputSymbol>(
+    refkey: Refkey,
+  ): Ref<TSymbol | undefined> {
+    const symbol = knownDeclarations.get(refkey);
+    if (symbol) {
+      return shallowRef(symbol as TSymbol);
+    } else {
+      if (waitingDeclarations.has(refkey)) {
+        return waitingDeclarations.get(refkey)! as ShallowRef<
+          TSymbol | undefined
+        >;
+      } else {
+        const declSignal = shallowRef();
+        waitingDeclarations.set(refkey, declSignal);
+        return declSignal;
+      }
+    }
+  }
+
   function waitForRefkey<
     TScope extends OutputScope,
     TSymbol extends OutputSymbol,

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>
@@ -9,6 +9,7 @@ export type ForCallbackArgs<T> =
   : T extends (infer U)[] ? [value: U]
   : T extends Map<infer U, infer V> ? [key: U, value: V]
   : T extends Set<infer U> ? [value: U]
+  : T extends IterableIterator<infer U> ? [value: U]
   : [];
 
 export interface ForProps<
@@ -27,9 +28,20 @@ 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>;
+export type ForSupportedCollections =
+  | any[]
+  | Map<any, any>
+  | Set<any>
+  | IterableIterator<any>;
 /**
  * The For component iterates over the provided array and invokes the child
  * callback for each item. It can optionally be provided with a `joiner` which
@@ -66,7 +78,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>;
+}