@alloy-js/csharp 0.21.0-dev.17 → 0.21.0-dev.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/csharp",
-  "version": "0.21.0-dev.17",
+  "version": "0.21.0-dev.19",
   "description": "Alloy components for CSharp language.",
   "exports": {
     ".": {

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

@@ -122,6 +122,12 @@ export interface AccessExpressionPartProps {
    * you provide a symbol or refkey and the symbol's nullable flag is set.
    */
   nullable?: boolean;
+
+  /**
+   * Wether this part is an attribute reference (used in an attribute context).
+   * In that case the "Attribute" suffix is trimmed from the name if present.
+   */
+  attribute?: boolean;
 }
 
 AccessExpression.Part = function (props: AccessExpressionPartProps) {

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

@@ -128,9 +128,12 @@ function createPartDescriptorFromProps(
       } else if (first && partProps.refkey) {
         return partProps.refkey;
       } else if (partProps.id !== undefined) {
-        return partProps.id;
+        return normalizeIfAttribute(partProps.id, partProps.attribute);
       } else if (symbolSource.value) {
-        return escapeId(symbolSource.value.name);
+        return normalizeIfAttribute(
+          escapeId(symbolSource.value.name),
+          partProps.attribute,
+        );
       } else {
         return "<unresolved symbol>";
       }
@@ -173,3 +176,24 @@ function createPartDescriptorFromProps(
 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
+ * ```ts
+ * normalizeAttributeName("TestAttribute") // returns "Test"
+ * ```
+ */
+export function normalizeAttributeName(name: string) {
+  if (name !== undefined && name.endsWith("Attribute")) {
+    return name.substring(0, name.length - "Attribute".length);
+  }
+  return name;
+}

package/src/components/attributes/attributes.test.tsx

@@ -1,4 +1,8 @@
-import { expect, it } from "vitest";
+import { ClassDeclaration } from "#components/class/declaration.jsx";
+import { createLibrary } from "#createLibrary";
+import { TestNamespace } from "#test/utils.jsx";
+import { List, namekey } from "@alloy-js/core";
+import { describe, expect, it } from "vitest";
 import { Attribute, AttributeList } from "./attributes.jsx";
 
 it("define attribute", () => {
@@ -7,6 +11,44 @@ it("define attribute", () => {
   `);
 });
 
+describe("Attribute suffix trimming", () => {
+  it("define attribute whose name ending with 'Attribute'", () => {
+    expect(<Attribute name="TestAttribute" />).toRenderTo(`
+      [Test]
+    `);
+  });
+
+  it("when using namekey", () => {
+    const key = namekey("TestAttribute");
+    expect(
+      <TestNamespace>
+        <List>
+          <Attribute name={key} />
+          <ClassDeclaration name={key} />
+        </List>
+      </TestNamespace>,
+    ).toRenderTo(`
+      [Test]
+      class TestAttribute;
+    `);
+  });
+
+  it("when referenced from library", () => {
+    const TestLib = createLibrary("TestLib", {
+      TestAttribute: { kind: "method", methodKind: "ordinary" },
+    });
+    expect(
+      <TestNamespace>
+        <Attribute name={TestLib.TestAttribute} />
+      </TestNamespace>,
+    ).toRenderTo(`
+      using TestLib;
+      
+      [Test]
+    `);
+  });
+});
+
 it("define attribute with single arg", () => {
   expect(<Attribute name="Test" args={[`"abc"`]} />).toRenderTo(`
       [Test("abc")]

package/src/components/attributes/attributes.tsx

@@ -1,15 +1,13 @@
+import { normalizeAttributeName } from "#components/access-expression/part-descriptors.js";
 import {
   Children,
   findKeyedChildren,
   For,
   Indent,
+  Refkeyable,
   taggedComponent,
 } from "@alloy-js/core";
-
-export interface AttributeItem {
-  name: string;
-  args?: string[];
-}
+import { ReferenceContext } from "../../contexts/reference-context.js";
 
 export type AttributesProp = Array<string | AttributeProps | Children>;
 
@@ -54,7 +52,7 @@ function renderAttribute(attr: string | AttributeProps | Children): Children {
 
 export interface AttributeProps {
   /** Attribute name */
-  name: Children;
+  name: string | Refkeyable;
 
   /** Argument */
   args?: Children[];
@@ -81,7 +79,8 @@ export const Attribute = taggedComponent(
   (props: AttributeProps) => {
     return (
       <group>
-        [{props.name}
+        [
+        <AttributeName name={props.name} />
         {props.args && props.args.length > 0 && (
           <>
             (
@@ -98,3 +97,11 @@ export const Attribute = taggedComponent(
     );
   },
 );
+
+function AttributeName(props: Pick<AttributeProps, "name">) {
+  return typeof props.name === "string" ?
+      normalizeAttributeName(props.name)
+    : <ReferenceContext.Provider value={"attribute"}>
+        {props.name}
+      </ReferenceContext.Provider>;
+}

package/src/components/parameters/parameters.test.tsx

@@ -148,3 +148,40 @@ it("can attach attributes", () => {
     }
   `);
 });
+
+it("can add modifiers: in | out | ref", () => {
+  expect(
+    <Wrapper>
+      <Method
+        name="MethodOne"
+        parameters={[
+          {
+            name: "param1",
+            type: "T1",
+            ref: true,
+          },
+          {
+            name: "param2",
+            type: "T2",
+            in: true,
+          },
+          {
+            name: "param3",
+            type: "T3",
+            out: true,
+          },
+          {
+            name: "param4",
+            type: "T4",
+            refReadonly: true,
+          },
+        ]}
+      />
+    </Wrapper>,
+  ).toRenderTo(`
+    public class TestClass
+    {
+        void MethodOne(ref T1 param1, in T2 param2, out T3 param3, ref readonly T4 param4) {}
+    }
+  `);
+});

package/src/components/parameters/parameters.tsx

@@ -22,6 +22,27 @@ export interface ParameterProps {
 
   refkey?: Refkey;
 
+  /**
+   * Parameter modifier: The argument must be initialized before calling the method. The method can't assign a new value to the parameter. The compiler might create a temporary variable to hold a copy of the argument to in parameters.
+   * @see https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/method-parameters#in-parameter-modifier
+   * */
+  in?: boolean;
+  /**
+   * Parameter modifier: The calling method isn't required to initialize the argument before calling the method. The method must assign a value to the parameter.
+   * @see https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/method-parameters#out-parameter-modifier
+   * */
+  out?: boolean;
+  /**
+   * Parameter modifier: The argument must be initialized before calling the method. The method can assign a new value to the parameter, but isn't required to do so.
+   * @see https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/method-parameters#ref-parameter-modifier
+   */
+  ref?: boolean;
+  /**
+   * Parameter modifier: The argument must be initialized before calling the method. The method can't assign a new value to the parameter.
+   * @see https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/method-parameters#ref-readonly-modifier
+   */
+  refReadonly?: boolean;
+
   /**
    * Define attributes to attach
    * @example
@@ -48,9 +69,26 @@ export function Parameter(props: ParameterProps) {
     isNullable: props.optional,
   });
 
+  // Only one of in, out, ref, ref readonly can be specified
+  const modifiers: (keyof ParameterProps)[] = (
+    ["in", "out", "ref", "refReadonly"] as (keyof ParameterProps)[]
+  ).filter((k) => props[k]);
+
+  if (modifiers.length > 1) {
+    throw new Error(
+      `Only one of 'in', 'out', 'ref', 'ref readonly' can be specified for parameter '${
+        typeof props.name === "string" ? props.name : props.name.name
+      }'`,
+    );
+  }
+  const modifier =
+    modifiers.length === 0 ? ""
+    : modifiers[0] === "refReadonly" ? "ref readonly "
+    : modifiers[0] + " ";
   return (
     <Declaration symbol={memberSymbol}>
       <AttributeList attributes={props.attributes} endline />
+      <>{modifier}</>
       <TypeSlot>{props.type}</TypeSlot>
       {props.optional ? "?" : ""} <Name />
       {props.default ? code` = ${props.default}` : ""}

package/src/contexts/reference-context.ts

@@ -0,0 +1,18 @@
+import { ComponentContext, createContext, useContext } from "@alloy-js/core";
+
+/** What kind of reference.
+ * - 'standard' Default reference nothing special.
+ * - 'attribute' means we are referencing an attribute and so the name should be trimmed of "Attribute" suffix.
+ */
+
+export type ReferenceContext = "standard" | "attribute";
+
+/**
+ * Provides scopes for instance and static private members.
+ */
+export const ReferenceContext: ComponentContext<ReferenceContext> =
+  createContext<ReferenceContext>();
+
+export function useReferenceContext(): "standard" | "attribute" {
+  return useContext(ReferenceContext) ?? "standard";
+}

package/src/create-library.ts

@@ -1,6 +1,7 @@
 import {
   Binder,
   LibrarySymbolReference,
+  namekey,
   refkey,
   REFKEYABLE,
   TO_SYMBOL,
@@ -123,7 +124,7 @@ export function createLibrary<T extends Record<string, Descriptor>>(
                 name,
               )! as NamespaceSymbol;
             } else {
-              ownerSymbol = new NamespaceSymbol(name, ownerSymbol!, {
+              ownerSymbol = new NamespaceSymbol(namekey(name), ownerSymbol!, {
                 binder,
                 refkeys: refkey(),
               });
@@ -213,24 +214,33 @@ function createSymbolFromDescriptor(
       if (ownerSymbol.members.symbolNames.has(name)) {
         return ownerSymbol.members.symbolNames.get(name)! as NamespaceSymbol;
       }
-      return new NamespaceSymbol(name, ownerSymbol as NamespaceSymbol, {
-        binder,
-        refkeys: refkey(),
-        lazyMemberInitializer,
-      });
+      return new NamespaceSymbol(
+        namekey(name),
+        ownerSymbol as NamespaceSymbol,
+        {
+          binder,
+          refkeys: refkey(),
+          lazyMemberInitializer,
+        },
+      );
     case "class":
     case "enum":
     case "interface":
     case "struct":
     case "record":
-      return new NamedTypeSymbol(name, ownerSymbol.members, descriptor.kind, {
-        binder,
-        refkeys: refkey(),
-        lazyMemberInitializer,
-      });
+      return new NamedTypeSymbol(
+        namekey(name),
+        ownerSymbol.members,
+        descriptor.kind,
+        {
+          binder,
+          refkeys: refkey(),
+          lazyMemberInitializer,
+        },
+      );
     case "method":
       return new MethodSymbol(
-        name,
+        namekey(name),
         ownerSymbol.members,
         descriptor.methodKind,
         {
@@ -240,7 +250,7 @@ function createSymbolFromDescriptor(
       );
     case "field":
     case "property":
-      return new CSharpSymbol(name, ownerSymbol.members, {
+      return new CSharpSymbol(namekey(name), ownerSymbol.members, {
         binder,
         refkeys: refkey(),
         type:
@@ -252,7 +262,7 @@ function createSymbolFromDescriptor(
         lazyMemberInitializer,
       });
     case "generic":
-      return new CSharpSymbol(name, ownerSymbol.members, {
+      return new CSharpSymbol(namekey(name), ownerSymbol.members, {
         binder,
         refkeys: refkey(),
       });

package/src/symbols/reference.tsx

@@ -7,6 +7,7 @@ import {
   resolve,
   unresolvedRefkey,
 } from "@alloy-js/core";
+import { useReferenceContext } from "../contexts/reference-context.js";
 import { CSharpScope } from "../scopes/csharp.js";
 import { CSharpNamespaceScope } from "../scopes/namespace.js";
 import { useSourceFileScope } from "../scopes/source-file.js";
@@ -56,12 +57,19 @@ export function ref(
     }
 
     const parts = [];
+    const referenceContext = useReferenceContext();
 
     for (const nsScope of pathDown) {
       parts.push(<AccessExpression.Part symbol={nsScope.ownerSymbol!} />);
     }
 
-    parts.push(<AccessExpression.Part symbol={lexicalDeclaration} />);
+    parts.push(
+      <AccessExpression.Part
+        symbol={lexicalDeclaration}
+        attribute={referenceContext === "attribute"}
+      />,
+    );
+
     for (const member of memberPath) {
       parts.push(<AccessExpression.Part symbol={member} />);
     }

package/temp/api.json

@@ -995,6 +995,33 @@
                 "endIndex": 4
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/csharp!AccessExpressionPartProps#attribute:member",
+              "docComment": "/**\n * Wether this part is an attribute reference (used in an attribute context).\n * In that case the \"Attribute\" suffix is trimmed from the name if present.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "attribute?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "attribute",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/csharp!AccessExpressionPartProps#children:member",
@@ -1577,78 +1604,6 @@
             "endIndex": 14
           }
         },
-        {
-          "kind": "Interface",
-          "canonicalReference": "@alloy-js/csharp!AttributeItem:interface",
-          "docComment": "",
-          "excerptTokens": [
-            {
-              "kind": "Content",
-              "text": "export interface AttributeItem "
-            }
-          ],
-          "fileUrlPath": "src/components/attributes/attributes.tsx",
-          "releaseTag": "Public",
-          "name": "AttributeItem",
-          "preserveMemberOrder": false,
-          "members": [
-            {
-              "kind": "PropertySignature",
-              "canonicalReference": "@alloy-js/csharp!AttributeItem#args:member",
-              "docComment": "",
-              "excerptTokens": [
-                {
-                  "kind": "Content",
-                  "text": "args?: "
-                },
-                {
-                  "kind": "Content",
-                  "text": "string[]"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";"
-                }
-              ],
-              "isReadonly": false,
-              "isOptional": true,
-              "releaseTag": "Public",
-              "name": "args",
-              "propertyTypeTokenRange": {
-                "startIndex": 1,
-                "endIndex": 2
-              }
-            },
-            {
-              "kind": "PropertySignature",
-              "canonicalReference": "@alloy-js/csharp!AttributeItem#name:member",
-              "docComment": "",
-              "excerptTokens": [
-                {
-                  "kind": "Content",
-                  "text": "name: "
-                },
-                {
-                  "kind": "Content",
-                  "text": "string"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";"
-                }
-              ],
-              "isReadonly": false,
-              "isOptional": false,
-              "releaseTag": "Public",
-              "name": "name",
-              "propertyTypeTokenRange": {
-                "startIndex": 1,
-                "endIndex": 2
-              }
-            }
-          ],
-          "extendsTokenRanges": []
-        },
         {
           "kind": "Function",
           "canonicalReference": "@alloy-js/csharp!AttributeList:function(1)",
@@ -1857,10 +1812,14 @@
                   "kind": "Content",
                   "text": "name: "
                 },
+                {
+                  "kind": "Content",
+                  "text": "string | "
+                },
                 {
                   "kind": "Reference",
-                  "text": "Children",
-                  "canonicalReference": "@alloy-js/core!Children:type"
+                  "text": "Refkeyable",
+                  "canonicalReference": "@alloy-js/core!Refkeyable:type"
                 },
                 {
                   "kind": "Content",
@@ -1873,7 +1832,7 @@
               "name": "name",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 2
+                "endIndex": 3
               }
             }
           ],
@@ -13690,6 +13649,33 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/csharp!ParameterProps#in:member",
+              "docComment": "/**\n * Parameter modifier: The argument must be initialized before calling the method. The method can't assign a new value to the parameter. The compiler might create a temporary variable to hold a copy of the argument to in parameters.\n *\n * @see\n *\n *  https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/method-parameters#in-parameter-modifier\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "in?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "in",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/csharp!ParameterProps#name:member",
@@ -13749,6 +13735,60 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/csharp!ParameterProps#out:member",
+              "docComment": "/**\n * Parameter modifier: The calling method isn't required to initialize the argument before calling the method. The method must assign a value to the parameter.\n *\n * @see\n *\n *  https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/method-parameters#out-parameter-modifier\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "out?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "out",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/csharp!ParameterProps#ref:member",
+              "docComment": "/**\n * Parameter modifier: The argument must be initialized before calling the method. The method can assign a new value to the parameter, but isn't required to do so.\n *\n * @see\n *\n *  https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/method-parameters#ref-parameter-modifier\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "ref?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "ref",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/csharp!ParameterProps#refkey:member",
@@ -13777,6 +13817,33 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/csharp!ParameterProps#refReadonly:member",
+              "docComment": "/**\n * Parameter modifier: The argument must be initialized before calling the method. The method can't assign a new value to the parameter.\n *\n * @see\n *\n *  https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/method-parameters#ref-readonly-modifier\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "refReadonly?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "refReadonly",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/csharp!ParameterProps#type:member",