Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# TKCode.Arc agent guide

TKCode.Arc is an Arc-style (uiarc.dev) component library for Avalonia 12.1.5. Every package depends only on Avalonia and the in-house MIT `TKCode.Arc.Foundation` (token runtime, theme manager, package registration, localization; design/architecture/foundation.md); the exceptions are `TKCode.Arc.Markdown` and `TKCode.Arc.Highlighting`, which bring StreamMark (and through it Markdig and TextMate) so that `TKCode.Arc` does not (design/decisions/0050-markdown-and-highlighting-packages.md).
Design source of truth: `design/` (start at `design/overview.md`).
TKCode.Arc is an Arc-style (uiarc.dev) component library for Avalonia 12 (the version is `AvaloniaVersion` in `build/Versions.props`). Every package depends only on Avalonia and the in-house MIT `TKCode.Arc.Foundation` (token runtime, theme manager, package registration, localization; design/architecture/foundation.md); the exceptions are `TKCode.Arc.Markdown` and `TKCode.Arc.Highlighting`, which bring StreamMark (and through it Markdig and TextMate) so that `TKCode.Arc` does not (design/decisions/0050-markdown-and-highlighting-packages.md).
Design source of truth: `design/` (start at `design/overview.md`). It is the maintainers' local working area and is not in the repository (`.gitignore`, since commit 4092a675): a fresh clone has no `design/`, and the `design/...` paths below and in the CHANGELOG point into it. Without it, this file, the XML docs and the code are the reference; the rules below stand on their own.

## Layout

Expand All @@ -20,17 +20,22 @@ Read `design/engineering/implementation-guide.md` before writing a component: fi
## Non-negotiable rules

- Controls derive from Avalonia base types; only public Avalonia APIs are used. No AtomUI code or packages, and none of its source is consulted (clean room; design/decisions/0031-replace-atomui.md).
- Class names have no prefix; flat namespace `TKCode.Arc`; xmlns `https://github.com/AIDotNet/TKCode.Arc`.
- Class names have no prefix; flat namespace `TKCode.Arc`; xmlns `https://github.com/AIDotNet/TKCode.Arc`. `TKCode.Arc.Mobile` is the exception: namespace `TKCode.Arc.Mobile`, xmlns `https://github.com/AIDotNet/TKCode.Arc.Mobile` (prefix `arcm`), and a few of its types share a desktop name (`Button`, `ButtonVariant`, `Checkbox`, `Dialog`, `RadioCard`, `RadioCardOption`, `RadioCards`, `Switch`, `Toast`; pinned by `MobileClassNameTests`, #152). New Mobile types do not reuse desktop names; a C# file that imports both namespaces aliases one side (`using MobileButton = TKCode.Arc.Mobile.Button;`).
- `TKCode.Arc.Terminal` is a standalone terminal library published with Arc (#150, ADR 0052): it depends on Avalonia alone, keeps its `TKCode.Terminal.*` namespaces, needs no `UseArc` entry, and takes its colors from the terminal core's palette (the host sets it), so the token, theme and registration rules below do not apply to it. Its default font starts with Geist Mono.
- Every public control has a `[ControlDesignToken]` `<Control>Token` in the same namespace with at least one property (ARCF003). Its identity (class name minus `Token`, or `[ControlDesignToken(Identity = "...")]`) is unique across all Arc packages, Mobile included (Mobile uses `MobileButton`, `MobileSwitch`, ...; design/engineering/reserved-token-names.md). Token property types are limited to those in foundation.md section 3.4 (ARCF001).
- Colors, radii, shadows and fonts come from `{arc:ArcDesignTokenResource ...}`; control tokens hold geometry and accent-independent derived colors only.
- Themes live in `<Component>/Themes/<Component>Theme.axaml` with `x:Class="<RootNamespace>.<FileName>" x:ClassModifier="internal"` (flat, e.g. `TKCode.Arc.ButtonTheme`, `TKCode.Arc.Mobile.PageTheme`; the generator supplies the class and loads the file on first use; ARCF010–014). A `ControlTheme` key is defined by one file only (ARCF013). Never create `*Themes.axaml` aggregates.
- Avalonia built-ins inside templates (`ScrollViewer`, `ScrollBar`, `ItemsControl`, `PathIcon`, `TextSelectionHandle`, popup hosts) get their theme from Core's base theme (`src/TKCode.Arc.Core/Theme/Base/`), which steps aside when the app uses Fluent or Simple. Other built-ins (e.g. `TextBox`) have no template: use the Arc control. Scroll bars auto-hide; set `ScrollViewer.AllowAutoHide="False"` to keep them.
- Theme changes go through `ArcTheme.Apply(t => ...)` / `ArcThemeManager.Apply`; never block on `ArcThemeManager.ApplyAsync` from the UI thread (its publish step needs the UI thread, so `.Wait()` / `.Result` deadlocks; await it or call `Apply`).
- A control that draws in `Render` (charts, text effects, per-frame motion) takes every color and size from its tokens or from brush properties, never hard-coded, because a new template does not change what it draws. The gallery's API tables say for each control whether it is templated or drawn (#154).
- Use Core's shared helpers instead of writing your own (#148): `ArcColor` (Lerp, LerpOklab, WithOpacity) for blending, `ArcFormatting` (Compact, Bytes, ToParts) for numbers and sizes, `ListKeyboardNavigator` for arrow-key lists, `DragTracker` / `DragRecognizer` / `VelocityTracker` for dragging, `Springs` / `MotionValue<T>` for springs. `DuplicateHelperTests` keeps allow-lists (`tests/TKCode.Arc.Tests/Architecture/Allowlists/`) of the files that still have their own copy. They only shrink: when you change one of those files, move it over and remove its line.
- Transitions are declared in ControlTheme setters under `^:motion-full` / `^:motion-reduced` (set `arc:ArcMotion.Tracks="True"`); code-driven motion uses `MotionValue<T>` and must say why ControlTheme cannot express it.
- Keep a source file to about 1200 lines: split a large control into `partial` files by concern (`Xxx.Input.cs`, `Xxx.Layout.cs`, `Xxx.Render.cs`, ...) and give each extra type its own file, when you next work on it (#153; `TreeSelect`, `Table`, `RichTextEditor` and `RichTextEditorSurface` show the shape). A guide, not a test.
- C# control-flow bodies always use braces. No reflection; AOT and trimming safe.
- Every Arc component needs gallery docs pages `Docs/<Category>/<Component>/{en-US,zh-CN,zh-TW}.md` in the ArcGallery repository (`../ArcGallery/gallery/TKCode.Arc.Gallery/`, checked by its `GalleryDocsTests`; design/engineering/gallery-app.md section 6.6), and its public properties and events need XML `<summary>` text here (they feed the API tables).
- Every new component or block gets the gallery's "New" badge: its catalog entry carries `AddedOn: "yyyy-MM-dd"` (the day it joins the gallery; the badge shows for `GalleryCatalog.NewWindowDays`). Arc components: the entry in ArcGallery's `Catalog/GalleryCatalog.g.cs` (keep it when regenerating); Extras, Special and Workflow: the entry in `GalleryCatalog.cs`; Blocks and Mobile: the `s_addedOn` table in `GalleryCatalog.cs` (checked by `GalleryNewBadgeTests`).
- Versions follow [Semantic Versioning](https://semver.org/): from 1.0.0 on, breaking API changes come only with a new major version. Record each release's changes and migration notes in `CHANGELOG.md`. A `-preview` suffix only allows changing members that no published package contains yet; for members that have shipped, preview included, the deprecation rule below applies.
- Every packable project lists its public API in `PublicAPI.Shipped.txt` (what released packages contain) and `PublicAPI.Unshipped.txt` (added since), checked by Microsoft.CodeAnalysis.PublicApiAnalyzers (#146): a public member that is in neither file (RS0016), or listed but gone (RS0017), fails the build. Add new members to `PublicAPI.Unshipped.txt` (`dotnet format analyzers <project> --diagnostics RS0016` writes them; for source-generated members, such as a new token property, copy the symbol from the RS0016 message). The stable release commit moves the Unshipped lines into Shipped. In Blocks and Special a block's root control, its item and data models, event args and token are public; the parts it is built from are internal unless an app needs to place them on their own.
- Public API is never removed or renamed in one step. The old member stays, marked `[Obsolete("Use X instead (deprecated in 1.Y.Z).")]` and forwarding to the new one, and is listed in `CHANGELOG.md` with its migration. It may be deleted only in a new major version, and only after it has carried `[Obsolete]` for at least two stable releases. This covers properties, events, methods, types, enum members and token names, and also changing a default, a parameter or what an event means. Code here and in ArcGallery moves to the new API in the same change and builds without CS0618, and a test keeps each obsolete member's forwarding working until it is removed.
- Item classes that a control lists (rows, options, actions: `SidebarItem`, `SegmentedOption`, ...) and controls with a selected state follow `design/engineering/implementation-guide.md` section 8: `IsEnabled` and `IsVisible` on every such item class (default `true`), `SelectionChanged` / `ValueChanged` for changes and `ItemInvoked` for "the user chose it".
- Releases go through one or more `X.Y.Z-preview.N` versions and end with a stable `X.Y.Z` of the same number; a new version number starts only after the previous one has shipped stable.
Expand Down
35 changes: 35 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,27 @@ looks different after the upgrade; see Changed for how to get the old look back.

### Added

- `ArcColor` (Core: `Lerp`, `LerpOklab`, `WithOpacity`) and `ArcFormatting.Bytes` ("512 B", "19 KB", "2.4 MB",
"1.5 GB"). These are the shared helpers that controls used to write for themselves
([#148](https://github.com/AIDotNet/TKCode.Arc/issues/148)). The activity components' byte sizes now come from
`ArcFormatting.Bytes`, which also shows gigabytes; before, sizes over 1 GB read in MB.
- `UseArcFonts()` and `UseArcPixelFonts()` (TKCode.Arc.Fonts) register Geist, Geist Mono and the pixel fonts from
`UseArc(...)`, the same as `WithArcFonts()` / `WithArcPixelFonts()`; calling both is harmless. TKCode.Arc.Fonts now
references TKCode.Arc.Foundation ([#151](https://github.com/AIDotNet/TKCode.Arc/issues/151)).
- **Backends follow late arrivals** ([#149](https://github.com/AIDotNet/TKCode.Arc/issues/149)):
- `ArcAudio.BackendChanged` and `ArcPdf.BackendChanged` join `ArcVideo.BackendChanged`. All three are raised once per
change, and setting the same backend again raises nothing.
- `VideoPlayer` and `MediaPlayer` replace their player when the process backend changes, for example when a browser's
`UseAsync()` finishes after they were created. `MediaPlayer` does so only when its `AudioBackend` is not set.
- `PdfViewer` and the attached `Pdf.Source` open the source again when it failed with `BackendUnavailable`.
- **`UseArc(...)` entries for the platform backends** ([#149](https://github.com/AIDotNet/TKCode.Arc/issues/149),
[#151](https://github.com/AIDotNet/TKCode.Arc/issues/151)):
- `UseArcAudioNative()`, `UseArcAudioBrowser()`, `UseArcVideoNative()`, `UseArcVideoBrowser()`, `UseArcPdfNative()`
and `UseArcPdfBrowser(assetsUrl)` enable the backend when the app starts and show up in `ArcRuntime.Packages`.
- The Video and Pdf ones also enable `UseArcVideo()` / `UseArcPdf()`.
- The browser ones start loading without waiting; the controls move over when the backend arrives.
- The static `Use()` / `UseAsync()` methods stay as they are.
- `TKCode.Arc.Audio.Native` and `TKCode.Arc.Audio.Browser` now reference `TKCode.Arc.Foundation` for this.
- **`TKCode.Arc.Terminal`, text** ([#139](https://github.com/AIDotNet/TKCode.Arc/issues/139)): SGR 1 and 3 draw with the
family's bold, italic and bold-italic faces, or synthesized ones when it has none; a fallback font is asked for the
same style. New `TerminalView` properties: `FontWeight`, `BoldFontWeight` (default `Bold`; below `SemiBold` it is not
Expand Down Expand Up @@ -60,6 +81,20 @@ looks different after the upgrade; see Changed for how to get the old look back.
- set `UnfocusedCursorStyle="Same"` to stop drawing a hollow cursor while the view does not have focus;
- set `CursorBlink="Never"` and `TextBlink="False"` to stop blinking;
- set `CustomGlyphs="False"` to take box drawing and block characters from the font again.
- `TerminalView`'s default `FontFamily` starts with Geist Mono (`fonts:GeistMono#Geist Mono`), Arc's code font, when the
app registers it with `WithArcFonts()` or `UseArcFonts()`; otherwise it is the same list as before
([#150](https://github.com/AIDotNet/TKCode.Arc/issues/150)). Set `FontFamily` to keep the old look.
- `ArcPdfNative.Use()` no longer waits for PDFium to start while it holds its lock. A second caller waits for the same
start, and the three native packages share one way of finding their library under `runtimes/<rid>/native`
([#149](https://github.com/AIDotNet/TKCode.Arc/issues/149)).
- **Dependencies** ([#147](https://github.com/AIDotNet/TKCode.Arc/issues/147)): `TKCode.Arc.Special` no longer depends
on `TKCode.Arc.Markdown` or `TKCode.Arc.Highlighting`, and `TKCode.Arc.Blocks` no longer depends on
`TKCode.Arc.Highlighting`. An app that uses Special no longer carries StreamMark, Markdig or TextMate; one that uses
Blocks no longer carries TextMate. The Special components that show code (AskYourData, CodeSuggestion, DesignToCode,
InstallSnippet) and the AI and support blocks color it through the same highlighter as `CodeBlock`, which
`UseArcHighlighting()` installs. **To keep colored code**, add `TKCode.Arc.Highlighting` and call
`UseArcHighlighting()` in `UseArc(...)`: `UseArcSpecial()` and `UseArcBlocks()` no longer enable it, and without it
that code is plain text. `UseArcBlocks()` still enables `UseArcMarkdown()`.

## 1.1.1 - 2026-11-17

Expand Down
2 changes: 2 additions & 0 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@
<!-- Gallery source generator (build-time only). -->
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="5.9.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="5.9.0" />
<!-- Tracks each package's public API in PublicAPI.Shipped.txt / PublicAPI.Unshipped.txt (#146). -->
<PackageVersion Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="5.6.0" />
<!-- Tests -->
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.11.0" />
<PackageVersion Include="xunit.v3" Version="3.2.2" />
Expand Down
17 changes: 17 additions & 0 deletions build/Arc.Repository.targets
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,21 @@
</ItemGroup>
<Import Project="$(ArcRepositoryRoot)src/TKCode.Arc.Icons.Lucide/buildTransitive/TKCode.Arc.Icons.Lucide.targets"
Condition="'$(ArcLucideGenerator)' == 'true'" />
<!-- Public API tracking (#146): every packable library lists its public surface in PublicAPI.Shipped.txt (what released
packages contain) and PublicAPI.Unshipped.txt (added since). A public member missing from both, or listed but gone,
fails the build (RS0016, RS0017). At a stable release the Unshipped lines move to Shipped. -->
<PropertyGroup>
<ArcPublicApi Condition="'$(ArcPublicApi)' == '' And '$(IsPackable)' != 'false' And '$(IsTestProject)' != 'true' And '$(IsRoslynComponent)' != 'true' And '$(PackageType)' != 'Template'">true</ArcPublicApi>
</PropertyGroup>
<PropertyGroup Condition="'$(ArcPublicApi)' == 'true'">
<!-- Only the tracking: a public member missing from the files (RS0016) or listed but gone (RS0017). The analyzer's
design rules (optional parameters, oblivious types, constructors) are not what this is for. -->
<WarningsAsErrors>$(WarningsAsErrors);RS0016;RS0017</WarningsAsErrors>
<NoWarn>$(NoWarn);RS0022;RS0026;RS0027;RS0041</NoWarn>
</PropertyGroup>
<ItemGroup Condition="'$(ArcPublicApi)' == 'true'">
<PackageReference Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" PrivateAssets="all" />
<AdditionalFiles Include="$(MSBuildProjectDirectory)/PublicAPI.Shipped.txt" />
<AdditionalFiles Include="$(MSBuildProjectDirectory)/PublicAPI.Unshipped.txt" />
</ItemGroup>
</Project>
53 changes: 53 additions & 0 deletions src/Shared/ArcNativeLibrary.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
using System.Reflection;
using System.Runtime.InteropServices;

namespace TKCode.Arc;

/// <summary>
/// Finding a native library next to the app (#149): the runtime identifier, the platform file name and the
/// <c>runtimes/&lt;rid&gt;/native</c> folder the packages put it in. Linked as source into Audio.Native, Video.Native and
/// Pdf.Native, so each keeps its own copy of these few lines as an internal type.
/// </summary>
internal static class ArcNativeLibrary
{
/// <summary>The runtime identifier of the running process, such as <c>osx-arm64</c>.</summary>
public static string CurrentRid()
{
var os = OperatingSystem.IsWindows() ? "win" : OperatingSystem.IsMacOS() ? "osx" : "linux";
var arch = RuntimeInformation.ProcessArchitecture switch
{
Architecture.Arm64 => "arm64",
Architecture.X86 => "x86",
_ => "x64",
};
return $"{os}-{arch}";
}

/// <summary>The file name of library <paramref name="name"/> on this platform: <c>name.dll</c>, <c>libname.dylib</c> or <c>libname.so</c>.</summary>
public static string FileName(string name)
=> OperatingSystem.IsWindows() ? name + ".dll" : OperatingSystem.IsMacOS() ? "lib" + name + ".dylib" : "lib" + name + ".so";

/// <summary>Loads library <paramref name="name"/> from <c>runtimes/&lt;rid&gt;/native</c> under the app's folder.</summary>
public static bool TryLoadFromRuntimes(string name, out nint handle)
=> NativeLibrary.TryLoad(Path.Combine(AppContext.BaseDirectory, "runtimes", CurrentRid(), "native", FileName(name)), out handle);

/// <summary>
/// Sets <paramref name="resolver"/> for <paramref name="assembly"/> once; a resolver the host set first is kept.
/// </summary>
public static void SetResolverOnce(Assembly assembly, DllImportResolver resolver, ref bool set)
{
if (set)
{
return;
}
set = true;
try
{
NativeLibrary.SetDllImportResolver(assembly, resolver);
}
catch (InvalidOperationException)
{
// A resolver was already set for this assembly by the host; keep it.
}
}
}
Loading
Loading