Add support for UI companion packages in AXSharp configuration

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: docs
+
+on:
+  push:
+    branches: [ "dev" ]
+    paths:
+      - 'src/**'
+      - 'docfx/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: [self-hosted, Windows, X64, L2, AX]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Install DocFX
+        run: dotnet tool restore || dotnet tool install docfx --global
+
+      - name: Build solution
+        run: .\build.ps1
+
+      - name: Generate documentation
+        run: dotnet docfx docfx/docfx.json
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CODEOWNERS

@@ -1 +1,2 @@
-@MTS spol. s r.o. @TomKovac
+@TomKovac
+@PTKu

docfx/api/index.md

@@ -1,3 +1,12 @@
 # AXSharp API Documentation
 
-![](~/images/banner.png)
+![](~/images/banner.png)
+
+Browse the auto-generated API reference for all AX# packages:
+
+- **AXSharp.Connector** — core connectivity layer, twin objects, and data exchange primitives
+- **AXSharp.Compiler** — twin compiler (ixc) internals and code generation
+- **AXSharp.Blazor** — Blazor UI rendering components and auto-generated views
+- **AXSharp.Abstractions** — shared interfaces and presentation attributes
+
+Use the table of contents on the left to navigate namespaces and types.

docfx/articles/compiler/CONFIG_FILE.MD

@@ -1,29 +1,53 @@
 # Ixc config file
 
-**AXSharp.config.json** can contain some settings for the compiler. Upon the first run of the ixc the default `AXSharp.config.json` file is created if not previoulsy created manually.
-
-Some compilation options can be overrided by CLI, such as `OutputProjectFolder` (-o) will override `OutputProjectFolder` setting in the config file.
+**AXSharp.config.json** can contain settings for the compiler. Upon the first run of `ixc` a default `AXSharp.config.json` file is created if one does not already exist.
 
+Some options can be overridden from the CLI. For example, the `-o` flag overrides `OutputProjectFolder`.
 
 **Default config file**
 
 ~~~json
 {
-    "OutputProjectFolder":"ix",   
+    "OutputProjectFolder": "ix"
 }
 ~~~
 
-**Config file example**
+**Config file example (library with UI companion)**
 
 ~~~json
 {
-    "OutputProjectFolder":"..\\ix-app"
+    "OutputProjectFolder": "../ix",
+    "UiHostProject": "../blazorapp/blazorapp.csproj"
 }
 ~~~
 
-|      Parameter      |                                                Meaning                                                 | Default |
-| ------------------- | ------------------------------------------------------------------------------------------------------ | ------- |
-| OutputProjectFolder | Sets the directory where the ixc will emmit the twin project.Use path relative to apax project folder. | 'ix'    |
-|                     | The value is overridable from the CLI                                                                  |         |
+## Parameters
+
+| Parameter | CLI flag | Meaning | Default |
+| --- | --- | --- | --- |
+| `OutputProjectFolder` | `-o` | Directory where `ixc` emits the twin project. Path relative to the AX project folder. | `ix` |
+| `ProjectFile` | `-p` | Name of the output `.csproj` file. | *(project name)* |
+| `UseBase` | `-b` | Use `$base` for base types in inherited classes. Obsolete. | `false` |
+| `NoDependencyUpdate` | `-u` | Prevent dependent twin packages from being installed via apax. | `false` |
+| `IgnoreS7Pragmas` | `-s` | Ignore `S7.extern` pragmas; compile all members regardless of communication settings. | `false` |
+| `SkipDependencyCompilation` | `-d` | Skip compilation of referenced AX# dependency projects. | `false` |
+| `TargetPlatfromMoniker` | `-t` | Target platform: `ax` or `tia`. | `ax` |
+| `UiHostProject` | `-a` | Path (relative to the AX project folder or absolute) of the `.csproj` that hosts or consumes UI companion NuGet packages. In library development this is the Blazor/UI application project; in application development this is the application project itself. When set, `ixc` automatically installs UI companion package references into this project. | *(none)* |
+
+## UI companion packages
+
+When a PLC library ships a UI companion package (Blazor components, auto-generated views, etc.), `ixc` can automatically wire up the dependency for you.
+
+**Library author** — set `UiHostProject` in the library's `AXSharp.config.json` to the path of the UI project that is built alongside the twin project. When `ixc` runs it will:
 
+1. Determine the UI package ID from the `<PackageId>` element in the referenced `.csproj`, or fall back to `<apax-package-name>.UI` when the file does not exist.
+2. Write that ID and the library version into `axsharp.companion.json` alongside the usual twin connector fields.
 
+**Consumer** — set `UiHostProject` in your project's `AXSharp.config.json` to point at the application project (e.g. a Blazor server app) that should receive the dependency. When `ixc` resolves a dependency that carries UI companion info, it automatically adds the corresponding NuGet package reference (or project reference when working directly from source) to the configured host project.
+
+~~~json
+{
+    "OutputProjectFolder": "../ix",
+    "UiHostProject": "../MyBlazorApp/MyBlazorApp.csproj"
+}
+~~~

docfx/articles/compiler/PACKAGING.md

@@ -25,4 +25,53 @@ Set the files in the `.meta` folder to build action to `Content`.
 ## Versioning
 
 > **Important**
-> The APAX package and respective Twin NuGet package must be released with the same version number. APAX package and NuGet package with the same version number are considered aligned.
+> The APAX package and respective Twin NuGet package must be released with the same version number. APAX package and NuGet package with the same version number are considered aligned.
+
+## UI companion packages
+
+A PLC library can ship a UI companion package alongside the twin connector — for example a set of auto-generated Blazor components. `ixc` handles the bookkeeping automatically via `axsharp.companion.json`.
+
+### Library author
+
+Set `UiHostProject` in your library's `AXSharp.config.json` to the path of the UI `.csproj` within your repository:
+
+~~~json
+{
+    "OutputProjectFolder": "../ix",
+    "UiHostProject": "../MyLib.UI/MyLib.UI.csproj"
+}
+~~~
+
+When `ixc` compiles the library it:
+
+1. Reads the `<PackageId>` from the UI project file (falls back to `<apax-name>.UI` if the file is absent).
+2. Writes `UiId` and `UiVersion` into `axsharp.companion.json` next to the existing twin connector fields.
+
+~~~json
+{
+  "Id": "MyLib.Twin",
+  "Version": "1.2.3",
+  "UiId": "MyLib.UI",
+  "UiVersion": "1.2.3"
+}
+~~~
+
+> The UI package version always matches the library version — publish both together.
+
+### Consumer
+
+Set `UiHostProject` in your application's `AXSharp.config.json` to the Blazor or UI host project that should receive the dependency:
+
+~~~json
+{
+    "OutputProjectFolder": "ix",
+    "UiHostProject": "../MyBlazorApp/MyBlazorApp.csproj"
+}
+~~~
+
+When `ixc` resolves a dependency whose `axsharp.companion.json` contains `UiId`/`UiVersion`, it automatically:
+
+- Adds a **NuGet package reference** to `UiHostProject` when the dependency is consumed as a NuGet package.
+- Adds a **project reference** to `UiHostProject` when the dependency is consumed directly from source (i.e. the dependency has its own `AXSharp.config.json` with `UiHostProject` set).
+
+If `UiHostProject` is not configured, the UI reference step is skipped and an informational message is logged.

docfx/articles/connectors/README.md

@@ -78,8 +78,8 @@ During the batched read operation, the values are stored in *LastValue* property
 
 During a batched write operation, the values written to the controller were retrieved from the *Cyclic* property of the corresponding Primitive Twin.
 
-> **NOTE** 
-> Accessing *Cyclic* property for **writing** will not result in an autmatic subscription for cyclic reading. Acessing the *LastValue* property will neither result in an automatic subcription for reading.
+> **NOTE**
+> Accessing *Cyclic* property for **writing** will not result in an automatic subscription for cyclic reading. Accessing the *LastValue* property will neither result in an automatic subscription for reading.
 
 ~~~ C#
 // in this namespace are extension methods for batched operations.
@@ -93,11 +93,11 @@ public class BatchedAccess
        await Entry.PlcTwin.Settings.ReadAsync();
 
         // Write values to the console
-        Console.WriteLine($"{Entry.PlcTwin.Settings.PosX.Symbol}:{Entry.PlcTwin.MAIN.Settings.PosX.LastValue});
+        Console.WriteLine($"{Entry.PlcTwin.Settings.PosX.Symbol}:{Entry.PlcTwin.Settings.PosX.LastValue}");
 
-        Console.WriteLine($"{Entry.PlcTwin.Settings.PosY.Symbol}:{Entry.PlcTwin.Settings.PosY.LastValue});
+        Console.WriteLine($"{Entry.PlcTwin.Settings.PosY.Symbol}:{Entry.PlcTwin.Settings.PosY.LastValue}");
 
-        Console.WriteLine($"{Entry.PlcTwin.Settings.PosZ.Symbol}:{Entry.PlcTwin.Settings.PosZ.LastValue});
+        Console.WriteLine($"{Entry.PlcTwin.Settings.PosZ.Symbol}:{Entry.PlcTwin.Settings.PosZ.LastValue}");
     }
 
 
@@ -108,11 +108,13 @@ public class BatchedAccess
        Entry.PlcTwin.Settings.PosZ.Cyclic = 130.0f;
 
         // Writes all values of the settings structure.
-       await Entry.PlcController.MAIN.Settings.WriteAsynch();
+       await Entry.PlcTwin.Settings.WriteAsync();
     }
 }
 ~~~
 
+## Polling
+
 Polling allows an application to query a structure or variable at different intervals. The values are stored in the `Cyclic` property of value types. The polled variables are retrieved from the controller in the same way as during cyclic reading but at a specified interval. Unlike automatic subscription mode, the polled values can be unsubscribed.
 
 To enable polling, the subscription of the twin connector must be set to `Polling`.
@@ -256,7 +258,7 @@ _length : REAL;
 ~~~
 
 ~~~ C#
-// Writes unit of the '_lenght' variable to the console.
+// Writes unit of the '_length' variable to the console.
 System.Console.WriteLine(PlcTwin._app._length.AttributeUnits);
 ~~~
 
@@ -334,10 +336,10 @@ VAR
     someWString : WSTRING;
 END_VAR
 
-someString := '<#This woule be localized#> and this would stay as it is';
+someString := '<#This would be localized#> and this would stay as it is';
 
 
-someWString := "<#This woule be localized#> and this would stay as it is";
+someWString := "<#This would be localized#> and this would stay as it is";
 ~~~
 
 Connectors implement features that allow localizing of the texts (controller defined and added attributes of string type). For the localization to work the twin assembly must be provided with a resource file (*.resx). Resource files can be generated using [ixr tool](~/articles/ixr/IXR.md). You will need to add the resource file to your **Twin project** and set the resource code generation to *public*.

docfx/articles/connectors/WebAPI.md

@@ -23,7 +23,7 @@ Here is an example on how to set polling subscription mode:
 Entry.Plc.Connector.SubscriptionMode = AXSharp.Connector.ReadSubscriptionMode.Polling;
 ```
 
-For more details about polling within your components, see [Polling Data from the Controller in Components](../blazor/LIBRARIES.md#polling-data-from-the-plc) and [General Polling](README.md#polling).
+For more details about polling within your components, see [Polling Data from the Controller in Components](../blazor/LIBRARIES.md#optimizing-plc-data-polling) and [General Polling](README.md#polling).
 
 ### Monitoring and Logging 
 

docfx/articles/intro.md

@@ -9,7 +9,7 @@
     * [Config file](~/articles/compiler/CONFIG_FILE.md)
     * [Packaging and dependencies](~/articles/compiler/PACKAGING.md)
 ---
-* [Documenation compiler](~/articles/ixd/IXD.md)
+* [Documentation compiler](~/articles/ixd/IXD.md)
 ---
 * [Resx compiler](~/articles/ixr/IXR.md)
 ---

docfx/articles/toc.yml

@@ -18,10 +18,12 @@
   - name: Packaging and dependencies
     href: ~/articles/compiler/PACKAGING.md
 
-- name: Documenation compiler
+- name: Documentation compiler
   href: ~/articles/ixd/IXD.md
 - name: Localizables compiler
   href: ~/articles/ixr/IXR.md
+- name: Localizables to Resx
+  href: ~/articles/ltr/LTR.md
 - name: Connectors
   href: ~/articles/connectors/README.md
   items:
@@ -38,4 +40,6 @@
     href: ~/articles/blazor/LIBRARIES.md
   - name: Blazor auto-rendering
     href: ~/articles/blazor/RENDERABLECONTENT.md
+- name: Coding style
+  href: ~/articles/general/CODING_STYLE.md
 

docfx/docfx.json

@@ -26,16 +26,16 @@
   ],
   "build": {
     "globalMetadata" : {
-        "_appTitle" : {"api/index.md" : "API"},
+        "_appTitle" : "AX#",
         "_appName" : "AX#",
-        "_appFooter" : " Generated by DocFx. © MTS spol. s r.o., MTS spol. s r.o., and awesome contributors",
+        "_appFooter" : " Generated by DocFx. © MTS spol. s r.o. and awesome contributors",
         "_enableSearch" : true,
         "_appFaviconPath" : "images/favicon.ico"        
     },
 
     "sitemap": {
       "baseUrl": "https://inxton.github.io/axsharp/",
-      "priority": 0.1,
+      "priority": 0.5,
       "changefreq": "weekly"
     },
 
@@ -65,17 +65,7 @@
         ]
       }
     ],
-    "overwrite": [
-      {
-        "files": [
-          "apidoc/**.md"
-        ],
-        "exclude": [
-          "obj/**",
-          "_site/**"
-        ]
-      }
-    ],
+    "overwrite": [],
     "dest": "../docs",
     "globalMetadataFiles": [],
     "fileMetadataFiles": [],