@alloy-js/csharp 0.23.0-dev.7 → 0.23.0

package/docs/api/components/Constructor.md

@@ -9,6 +9,7 @@ Properties for [Constructor](../constructor/) component.
 
 
   <Constructor
+    baseConstructor={Children[]}
     doc={Children}
     file
     internal
@@ -17,6 +18,7 @@ Properties for [Constructor](../constructor/) component.
     protected
     public
     refkey={Refkey}
+    thisConstructor={Children[]}
   >
     {children}
   </Constructor>
@@ -29,6 +31,7 @@ Properties for [Constructor](../constructor/) component.
 
 
   Constructor({
+    baseConstructor: Children[],
     doc: Children,
     file: boolean,
     internal: boolean,
@@ -37,19 +40,22 @@ Properties for [Constructor](../constructor/) component.
     protected: boolean,
     public: boolean,
     refkey: Refkey,
+    thisConstructor: Children[],
   }).children(children)
   ```
 
 ## Props
 
-|            |                                                    |                        |
-| ---------- | -------------------------------------------------- | ---------------------- |
-| children   | optional [Children](../../../core/types/children/) | Constructor body       |
-| doc        | optional [Children](../../../core/types/children/) | Doc comment            |
-| file       | optional boolean                                   |                        |
-| internal   | optional boolean                                   |                        |
-| parameters | optional [ParameterProps](../parameter/)\[]        | Constructor parameters |
-| private    | optional boolean                                   |                        |
-| protected  | optional boolean                                   |                        |
-| public     | optional boolean                                   |                        |
-| refkey     | optional [Refkey](../../../core/types/refkey/)     | Refkey                 |
+|                 |                                                       |                                                                                                                     |
+| --------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| baseConstructor | optional [Children](../../../core/types/children/)\[] | Arguments to pass to the base class constructor. Renders `: base(args)` between parameter list and body.            |
+| children        | optional [Children](../../../core/types/children/)    | Constructor body                                                                                                    |
+| doc             | optional [Children](../../../core/types/children/)    | Doc comment                                                                                                         |
+| file            | optional boolean                                      |                                                                                                                     |
+| internal        | optional boolean                                      |                                                                                                                     |
+| parameters      | optional [ParameterProps](../parameter/)\[]           | Constructor parameters                                                                                              |
+| private         | optional boolean                                      |                                                                                                                     |
+| protected       | optional boolean                                      |                                                                                                                     |
+| public          | optional boolean                                      |                                                                                                                     |
+| refkey          | optional [Refkey](../../../core/types/refkey/)        | Refkey                                                                                                              |
+| thisConstructor | optional [Children](../../../core/types/children/)\[] | Arguments to pass to another constructor in the same class. Renders `: this(args)` between parameter list and body. |

package/docs/api/components/Property.md

@@ -16,7 +16,7 @@ Properties for [Property](../property/) component
     doc={Children}
     extern
     file
-    get
+    get={boolean | Children}
     init
     initializer={Children}
     internal
@@ -31,7 +31,7 @@ Properties for [Property](../property/) component
     refkey={Refkey}
     required
     sealed
-    set
+    set={boolean | Children}
     static
     type={Children}
     virtual
@@ -50,7 +50,7 @@ Properties for [Property](../property/) component
     doc: Children,
     extern: boolean,
     file: boolean,
-    get: boolean,
+    get: boolean | Children,
     init: boolean,
     initializer: Children,
     internal: boolean,
@@ -65,7 +65,7 @@ Properties for [Property](../property/) component
     refkey: Refkey,
     required: boolean,
     sealed: boolean,
-    set: boolean,
+    set: boolean | Children,
     static: boolean,
     type: Children,
     virtual: boolean,
@@ -74,32 +74,32 @@ Properties for [Property](../property/) component
 
 ## Props
 
-|             |                                                        |                                                                                                                          |
-| ----------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| abstract    | optional boolean                                       |                                                                                                                          |
-| attributes  | optional [AttributesProp](../../types/attributesprop/) | Define attributes to attach                                                                                              |
-| doc         | optional [Children](../../../core/types/children/)     | Doc comment                                                                                                              |
-| extern      | optional boolean                                       |                                                                                                                          |
-| file        | optional boolean                                       |                                                                                                                          |
-| get         | optional boolean                                       | If property should have a getter                                                                                         |
-| init        | optional boolean                                       | If property should only be set on the type creation                                                                      |
-| initializer | optional [Children](../../../core/types/children/)     | Property initializer                                                                                                     |
-| internal    | optional boolean                                       |                                                                                                                          |
-| name        | [Namekey](../../../core/types/namekey/) \| string      |                                                                                                                          |
-| new         | optional boolean                                       |                                                                                                                          |
-| nullable    | optional boolean                                       | Property initializer                                                                                                     |
-| override    | optional boolean                                       |                                                                                                                          |
-| private     | optional boolean                                       |                                                                                                                          |
-| protected   | optional boolean                                       |                                                                                                                          |
-| public      | optional boolean                                       |                                                                                                                          |
-| readonly    | optional boolean                                       |                                                                                                                          |
-| refkey      | optional [Refkey](../../../core/types/refkey/)         |                                                                                                                          |
-| required    | optional boolean                                       | Set required modifier on property <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/required> |
-| sealed      | optional boolean                                       |                                                                                                                          |
-| set         | optional boolean                                       | If property should have a setter                                                                                         |
-| static      | optional boolean                                       |                                                                                                                          |
-| type        | [Children](../../../core/types/children/)              | Property type                                                                                                            |
-| virtual     | optional boolean                                       |                                                                                                                          |
+|             |                                                               |                                                                                                                                |
+| ----------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| abstract    | optional boolean                                              |                                                                                                                                |
+| attributes  | optional [AttributesProp](../../types/attributesprop/)        | Define attributes to attach                                                                                                    |
+| doc         | optional [Children](../../../core/types/children/)            | Doc comment                                                                                                                    |
+| extern      | optional boolean                                              |                                                                                                                                |
+| file        | optional boolean                                              |                                                                                                                                |
+| get         | optional boolean \| [Children](../../../core/types/children/) | If property should have a getter. Pass `true` for an auto-property getter (`get;`), or pass children for a getter with a body. |
+| init        | optional boolean                                              | If property should only be set on the type creation                                                                            |
+| initializer | optional [Children](../../../core/types/children/)            | Property initializer                                                                                                           |
+| internal    | optional boolean                                              |                                                                                                                                |
+| name        | [Namekey](../../../core/types/namekey/) \| string             |                                                                                                                                |
+| new         | optional boolean                                              |                                                                                                                                |
+| nullable    | optional boolean                                              | Property initializer                                                                                                           |
+| override    | optional boolean                                              |                                                                                                                                |
+| private     | optional boolean                                              |                                                                                                                                |
+| protected   | optional boolean                                              |                                                                                                                                |
+| public      | optional boolean                                              |                                                                                                                                |
+| readonly    | optional boolean                                              |                                                                                                                                |
+| refkey      | optional [Refkey](../../../core/types/refkey/)                |                                                                                                                                |
+| required    | optional boolean                                              | Set required modifier on property <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/required>       |
+| sealed      | optional boolean                                              |                                                                                                                                |
+| set         | optional boolean \| [Children](../../../core/types/children/) | If property should have a setter. Pass `true` for an auto-property setter (`set;`), or pass children for a setter with a body. |
+| static      | optional boolean                                              |                                                                                                                                |
+| type        | [Children](../../../core/types/children/)                     | Property type                                                                                                                  |
+| virtual     | optional boolean                                              |                                                                                                                                |
 
 ## Example
 

package/docs/api/contexts/csharp-context.md

@@ -0,0 +1,21 @@
+# csharp context
+
+C# contextual keywords that are reserved in certain contexts. While not always reserved, treating them as keywords in generated code avoids subtle context-dependent issues.
+
+```ts
+const csharpContextualKeywords: ReadonlySet<string>
+```
+
+## Accessor
+
+```ts
+const myContext = useContext(csharpContext);
+```
+
+## Context interface
+
+string
+
+## See also
+
+* <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/#contextual-keywords>

package/docs/api/contexts/index.md

@@ -0,0 +1,3 @@
+# csharp — contexts
+
+- [csharp context](csharp-context.md) — C# contextual keywords that are reserved in certain contexts.

package/docs/api/functions/createCSharpNamePolicy.md

@@ -1,5 +1,9 @@
 # createCSharpNamePolicy
 
+Creates the C# naming policy with case conversion and keyword escaping.
+
+After applying the appropriate case conversion for each element kind, the resulting name is checked against C# reserved and contextual keywords. If it matches (case-sensitively), the name is prefixed with `@`.
+
 ```ts
 import { createCSharpNamePolicy } from "@alloy-js/csharp";
 

package/docs/api/functions/index.md

@@ -4,7 +4,7 @@
 - [accessibilityFromProps](accessibilityFromProps.md) — import { accessibilityFromProps } from "@alloy-js/csharp";
 - [computeModifiersPrefix](computeModifiersPrefix.md) — Resolve the modifier prefix
 - [createClassScope](createClassScope.md) — import { createClassScope } from "@alloy-js/csharp";
-- [createCSharpNamePolicy](createCSharpNamePolicy.md) — import { createCSharpNamePolicy } from "@alloy-js/csharp";
+- [createCSharpNamePolicy](createCSharpNamePolicy.md) — Creates the C# naming policy with case conversion and keyword escaping.
 - [createCSharpNamespaceScope](createCSharpNamespaceScope.md) — import { createCSharpNamespaceScope } from "@alloy-js/csharp";
 - [createFieldSymbol](createFieldSymbol.md) — import { createFieldSymbol } from "@alloy-js/csharp";
 - [createLibrary](createLibrary.md) — import { createLibrary } from "@alloy-js/csharp";
@@ -19,9 +19,13 @@
 - [createVariableSymbol](createVariableSymbol.md) — import { createVariableSymbol } from "@alloy-js/csharp";
 - [getAccessModifier](getAccessModifier.md) — import { getAccessModifier } from "@alloy-js/csharp";
 - [getAsyncModifier](getAsyncModifier.md) — import { getAsyncModifier } from "@alloy-js/csharp";
+- [isCSharpContextualKeyword](isCSharpContextualKeyword.md) — Returns true if the given name is a C# contextual keyword.
+- [isCSharpKeyword](isCSharpKeyword.md) — Returns true if the given name is a C# reserved keyword.
+- [isValidCSharpIdentifier](isValidCSharpIdentifier.md) — Checks whether the provided name is a valid C# identifier (without `@` prefix).
 - [makeModifiers](makeModifiers.md) — import { makeModifiers } from "@alloy-js/csharp";
 - [nonAccessibilityFromProps](nonAccessibilityFromProps.md) — import { nonAccessibilityFromProps } from "@alloy-js/csharp";
 - [ref](ref.md) — import { ref } from "@alloy-js/csharp";
+- [sanitizeCSharpIdentifier](sanitizeCSharpIdentifier.md) — Transforms an arbitrary string into a valid C# identifier by replacing invalid characters.
 - [useCsharpFormatOptions](useCsharpFormatOptions.md) — import { useCsharpFormatOptions } from "@alloy-js/csharp";
 - [useCSharpNamePolicy](useCSharpNamePolicy.md) — import { useCSharpNamePolicy } from "@alloy-js/csharp";
 - [useCSharpScope](useCSharpScope.md) — import { useCSharpScope } from "@alloy-js/csharp";

package/docs/api/functions/isCSharpContextualKeyword.md

@@ -0,0 +1,20 @@
+# isCSharpContextualKeyword
+
+Returns true if the given name is a C# contextual keyword. Contextual keywords are only reserved in specific language contexts and are generally valid as identifiers.
+
+```ts
+import { isCSharpContextualKeyword } from "@alloy-js/csharp";
+
+
+function isCSharpContextualKeyword(name: string): boolean;
+```
+
+## Parameters
+
+|      |        |   |
+| ---- | ------ | - |
+| name | string |   |
+
+## Returns
+
+boolean

package/docs/api/functions/isCSharpKeyword.md

@@ -0,0 +1,22 @@
+# isCSharpKeyword
+
+Returns true if the given name is a C# reserved keyword. The check is case-sensitive, matching C# language semantics.
+
+Note: this only checks reserved keywords, not contextual keywords. Contextual keywords are only reserved in specific language contexts and are valid identifiers elsewhere (e.g., `value` is valid as a parameter name). Use [isCSharpContextualKeyword](../iscsharpcontextualkeyword/) to check contextual keywords separately.
+
+```ts
+import { isCSharpKeyword } from "@alloy-js/csharp";
+
+
+function isCSharpKeyword(name: string): boolean;
+```
+
+## Parameters
+
+|      |        |   |
+| ---- | ------ | - |
+| name | string |   |
+
+## Returns
+
+boolean

package/docs/api/functions/isValidCSharpIdentifier.md

@@ -0,0 +1,20 @@
+# isValidCSharpIdentifier
+
+Checks whether the provided name is a valid C# identifier (without `@` prefix). Does not account for keyword conflicts — use [isCSharpKeyword](../iscsharpkeyword/) for that.
+
+```ts
+import { isValidCSharpIdentifier } from "@alloy-js/csharp";
+
+
+function isValidCSharpIdentifier(name: string): boolean;
+```
+
+## Parameters
+
+|      |        |   |
+| ---- | ------ | - |
+| name | string |   |
+
+## Returns
+
+boolean true if the name matches C# identifier rules (letter or underscore start, word chars after).

package/docs/api/functions/sanitizeCSharpIdentifier.md

@@ -0,0 +1,24 @@
+# sanitizeCSharpIdentifier
+
+Transforms an arbitrary string into a valid C# identifier by replacing invalid characters. The result may still be a C# keyword — callers should combine with keyword escaping if needed.
+
+* If the first character is not a letter or underscore, a `_` prefix is added.
+* Subsequent non-word characters are replaced with `_`.
+* Empty strings become `_`.
+
+```ts
+import { sanitizeCSharpIdentifier } from "@alloy-js/csharp";
+
+
+function sanitizeCSharpIdentifier(name: string): string;
+```
+
+## Parameters
+
+|      |        |   |
+| ---- | ------ | - |
+| name | string |   |
+
+## Returns
+
+string A string that satisfies C# identifier character rules.

package/docs/api/index.md

@@ -1,6 +1,7 @@
 # @alloy-js/csharp API Reference
 
 - [components](components/index.md) (53 items)
-- [functions](functions/index.md) (31 items)
+- [contexts](contexts/index.md) (1 items)
+- [functions](functions/index.md) (35 items)
 - [types](types/index.md) (60 items)
-- [variables](variables/index.md) (1 items)
+- [variables](variables/index.md) (2 items)

package/docs/api/variables/csharpKeywords.md

@@ -0,0 +1,11 @@
+# csharpKeywords
+
+C# reserved keywords that cannot be used as identifiers without `@` prefix. These are case-sensitive in C#.
+
+```ts
+csharpKeywords: ReadonlySet<string>
+```
+
+## See also
+
+* <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/>

package/docs/api/variables/index.md

@@ -1,3 +1,4 @@
 # csharp — variables
 
 - [Attribute](Attribute.md) — Render a csharp attribute.
+- [csharpKeywords](csharpKeywords.md) — C# reserved keywords that cannot be used as identifiers without `@` prefix.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/csharp",
-  "version": "0.23.0-dev.7",
+  "version": "0.23.0",
   "description": "Alloy components for CSharp language.",
   "repository": {
     "type": "git",
@@ -43,23 +43,23 @@
   "author": "jhendrix@microsoft.com",
   "license": "MIT",
   "dependencies": {
-    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.16",
-    "@alloy-js/msbuild": "~0.22.0 || >= 0.23.0-dev.2",
     "change-case": "^5.4.4",
     "marked": "^16.1.1",
-    "pathe": "^2.0.3"
+    "pathe": "^2.0.3",
+    "@alloy-js/core": "~0.23.0",
+    "@alloy-js/msbuild": "~0.23.0"
   },
   "devDependencies": {
-    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.6",
-    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.2",
-    "@alloy-js/typescript": "~0.22.0 || >= 0.23.0-dev.9",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
     "@types/js-yaml": "^4.0.9",
     "concurrently": "^9.2.0",
     "js-yaml": "^4.1.0",
     "typescript": "^5.8.3",
-    "vitest": "3.2.4"
+    "vitest": "3.2.4",
+    "@alloy-js/rollup-plugin": "~0.1.1",
+    "@alloy-js/cli": "~0.23.0",
+    "@alloy-js/typescript": "~0.23.0"
   },
   "type": "module",
   "scripts": {

package/src/components/constructor/constructor.test.tsx

@@ -60,3 +60,67 @@ it("renders doc comment", () => {
     }
   `);
 });
+
+it("renders : base() initializer", () => {
+  expect(
+    <TestNamespace>
+      <ClassDeclaration public name="DerivedClass" baseType="BaseClass">
+        <Constructor
+          public
+          parameters={[{ name: "name", type: "string" }]}
+          baseConstructor={["name"]}
+        >
+          // body
+        </Constructor>
+      </ClassDeclaration>
+    </TestNamespace>,
+  ).toRenderTo(`
+    public class DerivedClass : BaseClass
+    {
+        public DerivedClass(string name) : base(name)
+        {
+            // body
+        }
+    }
+  `);
+});
+
+it("renders : this() initializer", () => {
+  expect(
+    <TestNamespace>
+      <ClassDeclaration public name="MyClass">
+        <Constructor public thisConstructor={["0", "0"]}>
+          // body
+        </Constructor>
+      </ClassDeclaration>
+    </TestNamespace>,
+  ).toRenderTo(`
+    public class MyClass
+    {
+        public MyClass() : this(0, 0)
+        {
+            // body
+        }
+    }
+  `);
+});
+
+it("renders : base() with no arguments", () => {
+  expect(
+    <TestNamespace>
+      <ClassDeclaration public name="DerivedClass" baseType="BaseClass">
+        <Constructor public baseConstructor={[]}>
+          // body
+        </Constructor>
+      </ClassDeclaration>
+    </TestNamespace>,
+  ).toRenderTo(`
+    public class DerivedClass : BaseClass
+    {
+        public DerivedClass() : base()
+        {
+            // body
+        }
+    }
+  `);
+});

package/src/components/constructor/constructor.tsx

@@ -1,5 +1,12 @@
 import { MethodScope } from "#components/method-scope.jsx";
-import { Block, MemberDeclaration, MemberName, Refkey } from "@alloy-js/core";
+import {
+  Block,
+  For,
+  Indent,
+  MemberDeclaration,
+  MemberName,
+  Refkey,
+} from "@alloy-js/core";
 import { Children } from "@alloy-js/core/jsx-runtime";
 import {
   AccessModifiers,
@@ -24,11 +31,51 @@ export interface ConstructorProps extends AccessModifiers {
   /** Refkey */
   refkey?: Refkey;
 
+  /**
+   * Arguments to pass to the base class constructor.
+   * Renders `: base(args)` between parameter list and body.
+   *
+   * @example
+   * ```tsx
+   * <Constructor public baseConstructor={["name", "42"]}>
+   * ```
+   * This will produce:
+   * ```csharp
+   * public MyClass(...) : base(name, 42)
+   * {
+   * }
+   * ```
+   */
+  baseConstructor?: Children[];
+
+  /**
+   * Arguments to pass to another constructor in the same class.
+   * Renders `: this(args)` between parameter list and body.
+   *
+   * @example
+   * ```tsx
+   * <Constructor public thisConstructor={["0", "0"]}>
+   * ```
+   * This will produce:
+   * ```csharp
+   * public MyClass() : this(0, 0)
+   * {
+   * }
+   * ```
+   */
+  thisConstructor?: Children[];
+
   /** Constructor body */
   children?: Children;
 }
 
 export function Constructor(props: ConstructorProps) {
+  if (props.baseConstructor && props.thisConstructor) {
+    throw new Error(
+      "Cannot use both 'baseConstructor' and 'thisConstructor' on the same constructor",
+    );
+  }
+
   const scope = useNamedTypeScope();
 
   const name = scope.ownerSymbol.name;
@@ -39,6 +86,13 @@ export function Constructor(props: ConstructorProps) {
 
   const modifiers = computeModifiersPrefix([getAccessModifier(props)]);
 
+  const initializer =
+    props.baseConstructor ?
+      <ConstructorInitializer keyword="base" args={props.baseConstructor} />
+    : props.thisConstructor ?
+      <ConstructorInitializer keyword="this" args={props.thisConstructor} />
+    : null;
+
   return (
     <MemberDeclaration symbol={ctorSymbol}>
       <MethodScope>
@@ -46,8 +100,34 @@ export function Constructor(props: ConstructorProps) {
         {modifiers}
         <MemberName />
         <Parameters parameters={props.parameters} />
+        {initializer}
         <Block newline>{props.children}</Block>
       </MethodScope>
     </MemberDeclaration>
   );
 }
+
+interface ConstructorInitializerProps {
+  keyword: "base" | "this";
+  args: Children[];
+}
+
+function ConstructorInitializer(props: ConstructorInitializerProps) {
+  return (
+    <group>
+      {" : "}
+      {props.keyword}(
+      <Indent nobreak>
+        <For each={props.args} joiner={", "}>
+          {(arg) => (
+            <>
+              <softline />
+              {arg}
+            </>
+          )}
+        </For>
+      </Indent>
+      <softline />)
+    </group>
+  );
+}

package/src/components/method/method.test.tsx

@@ -207,3 +207,39 @@ describe("format", () => {
   `);
   });
 });
+
+describe("name policy deduplication", () => {
+  it("deduplicates parameters that collide after case conversion", () => {
+    const params = [
+      { name: "my-param", type: "int" },
+      { name: "myParam", type: "string" },
+    ];
+    expect(
+      <Wrapper>
+        <Method public name="MethodOne" parameters={params} />
+      </Wrapper>,
+    ).toRenderTo(`
+      public class TestClass
+      {
+          public void MethodOne(int myParam, string myParam_2) {}
+      }
+    `);
+  });
+
+  it("deduplicates parameters that are keywords", () => {
+    const params = [
+      { name: "string", type: "int" },
+      { name: "string", type: "bool" },
+    ];
+    expect(
+      <Wrapper>
+        <Method public name="MethodOne" parameters={params} />
+      </Wrapper>,
+    ).toRenderTo(`
+      public class TestClass
+      {
+          public void MethodOne(int @string, bool string_2) {}
+      }
+    `);
+  });
+});

package/src/components/namespace/namespace.test.tsx

@@ -138,8 +138,10 @@ it("define nested namespace in sourcefile", () => {
   );
 
   expect(tree).toRenderTo(`
-    namespace Base {
-        namespace Namespace1.Namespace2 {
+    namespace Base
+    {
+        namespace Namespace1.Namespace2
+        {
             public class Model1;
         }
     }
@@ -170,7 +172,8 @@ it("contains a struct with a private field initialized by a constructor", () =>
   );
 
   expect(tree).toRenderTo(d`
-    namespace TestNamespace.Test {
+    namespace TestNamespace.Test
+    {
         public struct MyStruct
         {
             private int _value;

package/src/components/namespace/namespace.tsx

@@ -38,8 +38,8 @@ export function Namespace(props: NamespaceProps) {
         <NamespaceName
           symbol={namespaceSymbol}
           relative={!!hasOuterNamespace}
-        />{" "}
-        <Block>
+        />
+        <Block newline>
           <NamespaceScopes symbol={namespaceSymbol} stopAt={nsContext?.symbol}>
             {props.children}
           </NamespaceScopes>