@alloy-js/csharp 0.22.0 → 0.23.0-dev.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/csharp",
-  "version": "0.22.0",
+  "version": "0.23.0-dev.1",
   "description": "Alloy components for CSharp language.",
   "exports": {
     ".": {
@@ -32,23 +32,23 @@
   "author": "jhendrix@microsoft.com",
   "license": "MIT",
   "dependencies": {
+    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.1",
+    "@alloy-js/msbuild": "~0.22.0 || >= 0.23.0-dev.0",
     "change-case": "^5.4.4",
     "marked": "^16.1.1",
-    "pathe": "^2.0.3",
-    "@alloy-js/msbuild": "~0.22.0",
-    "@alloy-js/core": "~0.22.0"
+    "pathe": "^2.0.3"
   },
   "devDependencies": {
+    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.1",
+    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.0",
+    "@alloy-js/typescript": "~0.22.0 || >= 0.23.0-dev.2",
     "@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",
-    "@alloy-js/rollup-plugin": "~0.1.0",
-    "@alloy-js/typescript": "~0.22.0",
-    "@alloy-js/cli": "~0.22.0"
+    "vitest": "^3.2.4"
   },
   "type": "module",
   "scripts": {

package/src/components/source-file/source-file.test.tsx

@@ -1,6 +1,15 @@
+import { Attribute } from "#components/attributes/attributes.jsx";
 import { ClassDeclaration } from "#components/class/declaration.jsx";
 import { Namespace } from "#components/namespace/namespace.jsx";
-import { Children, FormatOptions, Indent, Output, Prose } from "@alloy-js/core";
+import {
+  Children,
+  FormatOptions,
+  Indent,
+  List,
+  Output,
+  Prose,
+} from "@alloy-js/core";
+import { Serialization } from "@alloy-js/csharp/global/System/Text/Json";
 import { describe, expect, it } from "vitest";
 import { CSharpFormatOptions } from "../../contexts/format-options.js";
 import { SourceFile } from "./source-file.jsx";
@@ -93,4 +102,29 @@ describe("format options", () => {
          indented 3 spaces
     `);
   });
+
+  it("respect docComment and using (and docComment before using)", () => {
+    expect(
+      <Output>
+        <SourceFile
+          path="Test1.cs"
+          headerComment={"This is a file comment"}
+          header={<Prose>// ---------Some Fake Heder-----------</Prose>}
+        >
+          <List>
+            <Attribute name={Serialization.JsonConverterAttribute} />
+            <ClassDeclaration public name="TestClass1" />
+          </List>
+        </SourceFile>
+      </Output>,
+    ).toRenderTo(`
+      /// This is a file comment
+      // ---------Some Fake Heder-----------
+
+      using System.Text.Json.Serialization;
+      
+      [JsonConverter]
+      public class TestClass1;
+    `);
+  });
 });

package/src/components/source-file/source-file.tsx

@@ -1,3 +1,4 @@
+import { DocComment } from "#components/doc/comment.jsx";
 import { NamespaceScopes } from "#components/namespace-scopes.jsx";
 import { NamespaceName } from "#components/namespace/namespace-name.jsx";
 import { Reference } from "#components/Reference.jsx";
@@ -7,7 +8,9 @@ import {
   Children,
   computed,
   SourceFile as CoreSourceFile,
+  List,
   Scope,
+  Show,
   useBinder,
 } from "@alloy-js/core";
 import {
@@ -34,6 +37,10 @@ export interface SourceFileProps extends CSharpFormatOptions {
    * explicit usings is not necessary when referencing symbols via refkeys.
    */
   using?: string[];
+  /* * Optional header content to include at the top of the file */
+  header?: Children;
+  /* * Optional doc comment to include at the top of the file, this will be before 'header' if both are provided */
+  headerComment?: string;
 }
 
 /** A C# source file exists within the context of a namespace contains using statements and declarations */
@@ -59,12 +66,21 @@ export function SourceFile(props: SourceFileProps) {
     useTabs: props.useTabs,
   });
 
+  const header =
+    props.header || props.headerComment ?
+      <SourceFileHeader
+        header={props.header}
+        headerComment={props.headerComment}
+      />
+    : undefined;
+
   return (
     <CoreSourceFile
       path={props.path}
       filetype="cs"
       reference={Reference}
       {...opts}
+      header={header}
     >
       <Scope value={sourceFileScope}>
         {(sourceFileScope.usings.size > 0 ||
@@ -96,3 +112,20 @@ export function SourceFile(props: SourceFileProps) {
     </CoreSourceFile>
   );
 }
+
+interface SourceFileHeaderProps {
+  header?: Children;
+  headerComment?: string;
+}
+
+function SourceFileHeader(props: SourceFileHeaderProps) {
+  return (
+    <List>
+      <Show when={props.headerComment !== undefined}>
+        <DocComment>{props.headerComment}</DocComment>
+      </Show>
+      <Show when={props.header !== undefined}>{props.header}</Show>
+      <hbr />
+    </List>
+  );
+}

package/temp/api.json

@@ -15651,6 +15651,61 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/csharp!SourceFileProps#header:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "header?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Children",
+                  "canonicalReference": "@alloy-js/core!Children:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "header",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@alloy-js/csharp!SourceFileProps#headerComment:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "headerComment?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "headerComment",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@alloy-js/csharp!SourceFileProps#path:member",