@alloy-js/csharp 0.23.0-dev.3 → 0.23.0-dev.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/csharp",
-  "version": "0.23.0-dev.3",
+  "version": "0.23.0-dev.4",
   "description": "Alloy components for CSharp language.",
   "repository": {
     "type": "git",
@@ -36,7 +36,7 @@
   "author": "jhendrix@microsoft.com",
   "license": "MIT",
   "dependencies": {
-    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.8",
+    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.10",
     "@alloy-js/msbuild": "~0.22.0 || >= 0.23.0-dev.1",
     "change-case": "^5.4.4",
     "marked": "^16.1.1",
@@ -45,7 +45,7 @@
   "devDependencies": {
     "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.3",
     "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.1",
-    "@alloy-js/typescript": "~0.22.0 || >= 0.23.0-dev.4",
+    "@alloy-js/typescript": "~0.22.0 || >= 0.23.0-dev.5",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
     "@types/js-yaml": "^4.0.9",

package/src/components/access-expression/access-expression.tsx

@@ -1,76 +1,126 @@
 import {
   Children,
-  childrenArray,
-  ComponentDefinition,
   computed,
+  createAccessExpression,
   For,
-  isComponentCreator,
   Refkeyable,
   Show,
-  takeSymbols,
 } from "@alloy-js/core";
 import { CSharpSymbol } from "../../symbols/csharp.js";
-import {
-  childrenToPartDescriptors,
-  isArgsPart,
-  isIdPart,
-  PartDescriptor,
-  PartDescriptorWithArgs,
-  PartDescriptorWithId,
-  PartDescriptorWithIndex,
-} from "./part-descriptors.js";
+import { normalizeAttributeName } from "./part-descriptors.js";
 
 export interface AccessExpressionProps {
   children: Children;
 }
 
-export function AccessExpression(props: AccessExpressionProps) {
-  const children = flattenAccessExpression(childrenArray(() => props.children));
-  const parts = childrenToPartDescriptors(children);
+type CSharpPartDescriptor = {
+  id: Children | undefined;
+  indexerArgs: Children[];
+  conditional: boolean;
+  nullable: boolean;
+  args: Children[] | undefined;
+  typeArgs: Children[] | undefined;
+};
 
-  // any symbols emitted from the children won't be relevant to parent scopes.
-  takeSymbols();
+const exclusiveParts: (keyof AccessExpressionPartProps)[] = [
+  "children",
+  "args",
+  "refkey",
+  "symbol",
+  "id",
+];
+
+const { Expression, Part, registerOuterComponent } = createAccessExpression<
+  AccessExpressionPartProps,
+  CSharpPartDescriptor
+>({
+  createDescriptor(partProps, sym, first) {
+    const foundProps = exclusiveParts.filter((key) => key in partProps);
+    if (foundProps.length > 1) {
+      throw new Error(
+        `Only one of ${foundProps.join(", ")} can be used for a MemberExpression part at a time`,
+      );
+    }
 
-  if (parts.length === 0) {
-    return <></>;
-  }
+    let id: Children | undefined;
+    if (
+      partProps.args ||
+      partProps.index !== undefined ||
+      partProps.indexerArgs
+    ) {
+      id = undefined;
+    } else if (partProps.children !== undefined) {
+      id = partProps.children;
+    } else if (first && partProps.refkey) {
+      id = partProps.refkey;
+    } else if (partProps.id !== undefined) {
+      id = normalizeIfAttribute(partProps.id, partProps.attribute);
+    } else if (sym) {
+      id = normalizeIfAttribute(escapeId(sym.name), partProps.attribute);
+    } else {
+      id = "<unresolved symbol>";
+    }
 
-  const isCallChain = computed(() => {
-    let callCount = 0;
-    for (const part of parts) {
-      if (isArgsPart(part)) callCount++;
+    let indexerArgs: Children[] = [];
+    if (partProps.indexerArgs) {
+      indexerArgs = partProps.indexerArgs;
+    } else if (partProps.index !== undefined) {
+      indexerArgs = [partProps.index];
     }
 
-    return callCount > 1;
-  });
+    return {
+      id,
+      indexerArgs,
+      conditional: !!partProps.conditional,
+      nullable:
+        partProps.nullable ? true
+        : sym ? (sym as CSharpSymbol).isNullable
+        : false,
+      args:
+        partProps.args === true ? []
+        : Array.isArray(partProps.args) ? partProps.args
+        : undefined,
+      typeArgs: partProps.typeArgs,
+    };
+  },
 
-  // construct a member expression from the parts. When a part is nullish,
-  // and there is a subsequent part, we use `?.` instead of `.`. accessStyle determines
-  // whether we use dot or bracket notation.
+  getBase(part) {
+    if (part.id !== undefined) {
+      return (
+        <>
+          {part.id}
+          <TypeArgs args={part.typeArgs} />
+        </>
+      );
+    }
+    return part.indexerArgs;
+  },
+
+  formatPart(part, prevPart, inCallChain) {
+    if (part.args !== undefined) {
+      return formatCallExpr(part);
+    } else if (part.id !== undefined) {
+      return formatMemberAccess(prevPart, part, inCallChain);
+    } else {
+      return formatElementAccess(prevPart, part);
+    }
+  },
 
-  return computed(() => {
-    return isCallChain.value ?
-        formatCallChain(parts)
-      : formatNonCallChain(parts);
-  });
-}
+  isCallPart(part) {
+    return part.args !== undefined;
+  },
+});
 
 /**
- * Flattens nested access expressions into a single array of parts.
+ * Create a C# access expression from parts. Each part can be a member access,
+ * element access, or invocation. Supports conditional access (`?.`), generic
+ * type arguments, and call chain formatting.
  */
-function flattenAccessExpression(children: Children[]): Children[] {
-  const flattened: Children[] = [];
-  for (const child of children) {
-    if (isComponentCreator(child, AccessExpression)) {
-      flattened.push(
-        ...flattenAccessExpression(childrenArray(() => child.props.children)),
-      );
-    } else {
-      flattened.push(child);
-    }
-  }
-  return flattened;
+export function AccessExpression(props: AccessExpressionProps) {
+  return Expression(props);
 }
+AccessExpression.Part = Part;
+registerOuterComponent(AccessExpression);
 
 export interface AccessExpressionPartProps {
   children?: Children;
@@ -130,170 +180,19 @@ export interface AccessExpressionPartProps {
   attribute?: boolean;
 }
 
-AccessExpression.Part = function (props: AccessExpressionPartProps) {
-  /** renders nothing, the parent AccessExpression will use these args */
-};
-
-/**
- * Formatting of call chains (i.e. member expressions which have more than one
- * call in them). The general approach is that line breaks occur after each
- * call, and there is only one call per line. When there are non-call elements,
- * they occur prior to the call part. The first part of the member expression
- * contains all but the last non-call part.
- *
- * The following is an example of proper formatting:
- *
- * ```ts
- * z.dummy             // all but the last non-call part for the first element
- *   .object({         // the first call part with line break after
- *      a: 1,
- *   })
- *   .dummy.partial()  // the next call part with non-call parts before it
- * ```
- */
-function formatCallChain(parts: PartDescriptor[]): Children {
-  return computed(() => {
-    const expression: Children[] = [];
-
-    // break the expression into parts.
-    const chunks: PartDescriptor[][] = [];
-
-    // the first part is all the non-call parts
-    let partIndex = 0;
-
-    function pushPart() {
-      const part = parts[partIndex];
-      if (!part) throw new Error("No part to push");
-      chunks.at(-1)!.push(part);
-      partIndex++;
-    }
-
-    function pushChunk() {
-      chunks.push([]);
-    }
-
-    // For the first chunk, take all the non-call parts except the last one
-    // and put them in a chunk.
-    pushChunk();
-    while (
-      partIndex < parts.length &&
-      (partIndex === parts.length - 1 ||
-        chunks.at(-1)!.length === 0 ||
-        !isArgsPart(parts[partIndex + 1]))
-    ) {
-      pushPart();
-      if (isArgsPart(chunks.at(-1)!.at(-1)!)) {
-        // the first segment always ends after we see a call
-        // if we happen to take one
-        break;
-      }
-    }
-
-    // then for all remaining parts, collect all the non-call parts and end with
-    // a call chunk
-    while (partIndex < parts.length) {
-      pushChunk();
-      while (partIndex < parts.length && !isArgsPart(parts[partIndex])) {
-        pushPart();
-      }
-      while (partIndex < parts.length && isArgsPart(parts[partIndex])) {
-        pushPart();
-      }
-    }
-
-    for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex++) {
-      const chunk = chunks[chunkIndex];
-      const chunkExpression = [];
-      for (let partIndex = 0; partIndex < chunk.length; partIndex++) {
-        if (chunkIndex === 0 && partIndex === 0) {
-          // first part is just gonna be the id
-          const firstPart =
-            isIdPart(chunk[0]) ?
-              chunk[0].id
-            : (chunk[0] as PartDescriptorWithIndex).indexerArgs;
-          chunkExpression.push(firstPart);
-          continue;
-        }
-        const part = chunk[partIndex];
-        const prevPart =
-          partIndex === 0 ?
-            chunks[chunkIndex - 1].at(-1)!
-          : chunk[partIndex - 1];
-
-        if (isArgsPart(part)) {
-          // For parts with only args (no name), append function call directly with appropriate nullish operator
-          chunkExpression.push(formatCallExpr(prevPart, part));
-        } else if (isIdPart(part)) {
-          chunkExpression.push(formatMemberAccess(prevPart, part, true));
-        } else {
-          // bracket notation - don't include the dot
-          chunkExpression.push(formatElementAccess(prevPart, part));
-        }
-      }
-
-      expression.push(
-        chunkIndex === 0 ? chunkExpression : (
-          <>
-            <sbr />
-            {chunkExpression}
-          </>
-        ),
-      );
-    }
-
-    return (
-      <group>
-        <indent>{expression}</indent>
-      </group>
-    );
-  });
-}
-
-function formatNonCallChain(parts: PartDescriptor[]): Children {
-  return computed(() => {
-    const expression: Children[] = [];
-
-    for (let i = 0; i < parts.length; i++) {
-      const part = parts[i];
-      const base =
-        isIdPart(part) ?
-          part.id
-        : (part as PartDescriptorWithIndex).indexerArgs;
-      if (i === 0) {
-        expression.push(base, <TypeArgs args={(part as any).typeArgs} />);
-      } else {
-        // Determine if we should use nullish operator from previous part
-        const prevPart = parts[i - 1];
-
-        if (isArgsPart(part)) {
-          // For parts with only args (no name), append function call directly with appropriate nullish operator
-          expression.push(formatCallExpr(prevPart, part));
-        } else if (isIdPart(part)) {
-          expression.push(formatMemberAccess(prevPart, part));
-        } else {
-          // bracket notation - don't include the dot
-          expression.push(formatElementAccess(prevPart, part));
-        }
-      }
-    }
-
-    return expression;
-  });
-}
+// --- Formatting helpers ---
 
 function formatElementAccess(
-  prevPart: PartDescriptor,
-  part: PartDescriptorWithIndex,
+  prevPart: CSharpPartDescriptor,
+  part: CSharpPartDescriptor,
 ) {
+  const indexerArgs = computed(() => part.indexerArgs);
   return (
     <group>
-      {part.conditional || ("nullable" in prevPart && prevPart.nullable) ?
-        "?"
-      : ""}
-      [
+      {part.conditional || prevPart.nullable ? "?" : ""}[
       <indent>
         <sbr />
-        <For each={part.indexerArgs} comma line>
+        <For each={indexerArgs} comma line>
           {(arg) => arg}
         </For>
       </indent>
@@ -303,41 +202,34 @@ function formatElementAccess(
 }
 
 function formatMemberAccess(
-  prevPart: PartDescriptor,
-  part: PartDescriptorWithId,
-  noIndent = false,
+  prevPart: CSharpPartDescriptor,
+  part: CSharpPartDescriptor,
+  noIndent: boolean,
 ) {
-  let Wrapping: ComponentDefinition<{ children: Children }>;
+  const content = (
+    <>
+      {part.conditional || prevPart.nullable ? "?." : "."}
+      {part.id}
+      <TypeArgs args={part.typeArgs} />
+    </>
+  );
+
   if (noIndent) {
-    Wrapping = function (props) {
-      return (
-        <group>
-          <sbr />
-          {props.children}
-        </group>
-      );
-    };
-  } else {
-    Wrapping = function (props) {
-      return (
-        <group>
-          <indent>
-            <sbr />
-            {props.children}
-          </indent>
-        </group>
-      );
-    };
+    return (
+      <group>
+        <sbr />
+        {content}
+      </group>
+    );
   }
 
   return (
-    <Wrapping>
-      {part.conditional || ("nullable" in prevPart && prevPart.nullable) ?
-        "?."
-      : "."}
-      {isIdPart(part) ? part.id : (part as PartDescriptorWithIndex).indexerArgs}
-      <TypeArgs args={part.typeArgs} />
-    </Wrapping>
+    <group>
+      <indent>
+        <sbr />
+        {content}
+      </indent>
+    </group>
   );
 }
 
@@ -359,17 +251,15 @@ function TypeArgs(props: { args?: Children[] }) {
   );
 }
 
-function formatCallExpr(
-  prevPart: PartDescriptor,
-  part: PartDescriptorWithArgs,
-) {
+function formatCallExpr(part: CSharpPartDescriptor) {
+  const args = computed(() => part.args ?? []);
   return (
     <group>
-      (<Show when={part.args.length <= 1}>{part.args[0]}</Show>
-      <Show when={part.args.length > 1}>
+      (<Show when={args.value.length <= 1}>{args.value[0]}</Show>
+      <Show when={args.value.length > 1}>
         <indent>
           <sbr />
-          <For each={part.args} comma line>
+          <For each={args} comma line>
             {(arg) => arg}
           </For>
         </indent>
@@ -379,3 +269,16 @@ function formatCallExpr(
     </group>
   );
 }
+
+// --- Utilities ---
+
+function escapeId(id: string) {
+  return id.replace(/"/g, '\\"');
+}
+
+function normalizeIfAttribute(id: string, isAttribute?: boolean) {
+  if (isAttribute) {
+    return normalizeAttributeName(id);
+  }
+  return id;
+}

package/src/components/access-expression/part-descriptors.ts

@@ -1,189 +1,3 @@
-import {
-  Children,
-  computed,
-  isComponentCreator,
-  reactive,
-  ref,
-  symbolForRefkey,
-  ToRefs,
-} from "@alloy-js/core";
-import { CSharpSymbol } from "../../index.js";
-import {
-  AccessExpression,
-  AccessExpressionPartProps,
-} from "./access-expression.jsx";
-
-export interface PartDescriptorWithId extends PartDescriptorBase {
-  /**
-   * The identifier of the access expression part. Will use member access, so must be a valid
-   * C# identifier.
-   */
-  id: Children;
-  conditional: boolean;
-  typeArgs?: Children[];
-}
-
-export function isIdPart(part: PartDescriptor): part is PartDescriptorWithId {
-  return "id" in part && part.id !== undefined;
-}
-
-export interface PartDescriptorWithIndex extends PartDescriptorBase {
-  /**
-   * The index of the access expression part. Will use element access.
-   */
-  indexerArgs: Children[];
-  conditional: boolean;
-}
-
-export function isIndexPart(
-  part: PartDescriptor,
-): part is PartDescriptorWithIndex {
-  return "indexerArgs" in part && part.indexerArgs !== undefined;
-}
-
-export interface PartDescriptorWithArgs extends PartDescriptorBase {
-  args: Children[];
-}
-
-export function isArgsPart(
-  part: PartDescriptor,
-): part is PartDescriptorWithArgs {
-  return "args" in part && part.args !== undefined;
-}
-
-export interface PartDescriptorBase {
-  nullable: boolean;
-}
-
-export type PartDescriptor =
-  | PartDescriptorWithId
-  | PartDescriptorWithIndex
-  | PartDescriptorWithArgs;
-
-/**
- * Build part descriptors from the children of a MemberExpression.
- */
-export function childrenToPartDescriptors(
-  children: Children[],
-): PartDescriptor[] {
-  const parts: PartDescriptor[] = [];
-  for (const child of children) {
-    if (!isComponentCreator(child, AccessExpression.Part)) {
-      // we ignore non-parts
-      continue;
-    }
-
-    parts.push(
-      createPartDescriptorFromProps(child.props, child === children[0]),
-    );
-  }
-
-  return parts;
-}
-
-const exclusiveParts: (keyof AccessExpressionPartProps)[] = [
-  "children",
-  "args",
-  "refkey",
-  "symbol",
-  "id",
-];
-/**
- * Creates a reactive part descriptor from the given part props.
- *
- * @param partProps The props for the part.
- * @param first Whether this is the first part in the expression. Refkeys are
- * handled specially for the first part.
- */
-function createPartDescriptorFromProps(
-  partProps: AccessExpressionPartProps,
-  first: boolean,
-) {
-  const foundProps = exclusiveParts.filter((key) => {
-    return key in partProps;
-  });
-
-  if (foundProps.length > 1) {
-    throw new Error(
-      `Only one of ${foundProps.join(", ")} can be used for a MemberExpression part at a time`,
-    );
-  }
-
-  const symbolSource = computed(() => {
-    if (partProps.refkey) {
-      return symbolForRefkey(partProps.refkey).value as CSharpSymbol;
-    } else if (partProps.symbol) {
-      return partProps.symbol;
-    } else {
-      return undefined;
-    }
-  });
-
-  const part: ToRefs<PartDescriptor> = {
-    id: computed(() => {
-      if (partProps.args || partProps.index || partProps.indexerArgs) {
-        return undefined;
-      } else if (partProps.children !== undefined) {
-        return partProps.children;
-      } else if (first && partProps.refkey) {
-        return partProps.refkey;
-      } else if (partProps.id !== undefined) {
-        return normalizeIfAttribute(partProps.id, partProps.attribute);
-      } else if (symbolSource.value) {
-        return normalizeIfAttribute(
-          escapeId(symbolSource.value.name),
-          partProps.attribute,
-        );
-      } else {
-        return "<unresolved symbol>";
-      }
-    }),
-    indexerArgs: computed(() => {
-      if (partProps.indexerArgs) {
-        return partProps.indexerArgs;
-      }
-
-      if (partProps.index !== undefined) {
-        return [partProps.index];
-      }
-
-      return [];
-    }),
-    conditional: computed(() => {
-      return !!partProps.conditional;
-    }),
-    nullable: computed(() => {
-      if (partProps.nullable) {
-        return true;
-      }
-
-      if (symbolSource.value) {
-        return symbolSource.value.isNullable;
-      }
-
-      return false;
-    }),
-    args: ref<any>(partProps.args === true ? [] : partProps.args),
-    typeArgs: ref<any>(partProps.typeArgs),
-  };
-
-  return reactive(part);
-}
-
-/**
- * replaces quotes with escaped quotes
- */
-function escapeId(id: string) {
-  return id.replace(/"/g, '\\"');
-}
-
-function normalizeIfAttribute(id: string, isAttribute?: boolean) {
-  if (isAttribute) {
-    return normalizeAttributeName(id);
-  }
-  return id;
-}
-
 /**
  * Normalize attribute name by removing the "Attribute" suffix if present.
  * @example

package/src/components/doc/from-markdown.tsx

@@ -17,7 +17,10 @@ function renderTokens(tokens: Token[]) {
       {tokens.map((token, index) => (
         <>
           <DocFromMarkedToken token={token} />
-          {token.type === "paragraph" && index !== tokens.length - 1 && <br />}
+          {
+            /*@once*/ token.type === "paragraph" &&
+              index !== tokens.length - 1 && <br />
+          }
         </>
       ))}
     </>