winui-svelte 0.0.3 → 0.0.5

package/README.md

@@ -1,5 +1,7 @@
 # winui-svelte
 
+<img src="https://raw.githubusercontent.com/avi12/winui-svelte/main/ide/icon.svg" alt="The winui-svelte logo" width="96" height="96">
+
 [![npm version](https://img.shields.io/npm/v/winui-svelte)](https://www.npmjs.com/package/winui-svelte)
 
 WinUI 3 controls as Svelte components: native Windows apps written in Svelte,
@@ -10,6 +12,24 @@ controls animate and are accessible as WinUI makes them, and acrylic is a real
 backdrop
 No browser engine is involved; there is no DOM
 
+## Install
+
+```sh
+# pnpm
+pnpm add winui-svelte
+
+# npm
+npm install winui-svelte
+
+# bun
+bun add winui-svelte
+```
+
+The WinUI bindings, the Windows App SDK bootstrapper and the Vite plugin come
+with it
+The package installs with any of the three; an app runs on Node 24 or newer
+(`node main.ts`), as the [Requirements](#requirements) say
+
 ## Using it, at a glance
 
 Everything an app needs, in the order a new project hits it
@@ -42,6 +62,16 @@ signature
 - **Web APIs** (`Notification`, `navigator.geolocation`, the clipboard and the
   rest) are the browser's own, backed by Windows; call them as on the web
   ([Web APIs](#web-apis))
+- **Overlays:** `sizeToContent` and `anchor` on `<Window>` size a window to its
+  content with one corner pinned (a bottom-right pill grows upward),
+  `isActivatable` can change while the window is open, and `handle.dock()`
+  puts a window against a corner of the active display's work area; the window's
+  own `outerWidth`, `screenX`, `resizeTo` and `moveBy` are on `handle.geometry`
+  ([API.md](https://github.com/avi12/winui-svelte/blob/main/API.md))
+- **Window place:** `stateKey` on `<Window>` saves its bounds, maximized state
+  and presentation under that name and restores them on the next run, inside
+  the nearest display so a disconnected monitor never strands it
+  ([API.md](https://github.com/avi12/winui-svelte/blob/main/API.md))
 - **Errors** thrown in an event handler or a prop are caught on the UI thread,
   written to stderr with their stack and handed to `runWindow({ onerror })`;
   the app goes on ([API.md](https://github.com/avi12/winui-svelte/blob/main/API.md))
@@ -126,14 +156,22 @@ written with it
 | Svelte | 5.51.1 to 5.57.3 (the peer range `5.51.1 - 5.57.3` is what `pnpm check:svelte-matrix` proves; the package edits a few spots of Svelte's runtime and says so, naming the file and the release, when one no longer matches) |
 | Vite | 8 (for the dev server and hot reload) |
 
-## Install
+## Editor support
 
-```sh
-pnpm add winui-svelte
-```
+Two optional add-ons for `.svelte` files, one for each editor:
 
-The WinUI bindings, the Windows App SDK bootstrapper and the Vite plugin come
-with it
+- previews and completions for icon names, colours and installed fonts
+- Alt+Enter on a component's prop converts it to the CSS that sets the same
+  value
+
+| Editor | Download | Install |
+| --- | --- | --- |
+| VS Code | `winui-svelte-vscode-<version>.vsix`, or [the Visual Studio Marketplace page](https://marketplace.visualstudio.com/items?itemName=Avi.winui-svelte-vscode) | `code --install-extension winui-svelte-vscode-0.0.1.vsix`, or the Extensions view, the `...` menu, Install from VSIX |
+| WebStorm | `winui-svelte-webstorm-<version>.zip`, or [the JetBrains Marketplace page](https://plugins.jetbrains.com/plugin/35835-winui-svelte) | Settings, Plugins, the gear, Install Plugin from Disk |
+
+Both files are assets of the `editors-v*` releases, on their own tags apart
+from the package's: [open the editors releases](https://github.com/avi12/winui-svelte/releases?q=editors-v)
+and take the newest
 
 ## Quick start
 
@@ -195,104 +233,45 @@ any Svelte binding:
 
 <!-- hello/App.svelte:end -->
 
-`window.ts` runs on the UI thread
-`runOnUiThread` (the package's `/thread` entry) is a worker's first call: it
-enters the apartment before anything creates a WinRT object
-The
-window's modules come from the host's dev server through the module runner, and
-a timer takes the server's hot updates in (the thread's libuv turns between
-WinUI's messages, so `fs`, sockets, `fetch`, `WebSocket` and worker messages
-all complete there too; see [Timers and I/O](https://github.com/avi12/winui-svelte/blob/main/API.md#timers-and-io)):
-
-<!-- hello/window.ts:start -->
-
-```ts
-import { MessagePort, workerData } from "node:worker_threads";
-import { createWindowModuleRunner } from "winui-svelte/runner";
-import { runOnUiThread } from "winui-svelte/thread";
-import type * as WindowModule from "winui-svelte/window";
-import { z } from "zod";
-
-// The window: WinUI's thread. Its modules come from the host's dev server, and
-// the server's hot updates arrive as messages the window's loop delivers.
-
-const windowSize = {
-  width: 480,
-  height: 320
-};
-
-const workerDataSchema = z.object({ modules: z.instanceof(MessagePort) });
-
-await runOnUiThread(async () => {
-  const parsedData = workerDataSchema.safeParse(workerData);
-  if (!parsedData.success) {
-    throw new Error("the host passed no port to its dev server");
-  }
-
-  // Everything goes through the runner, so the window and the components
-  // share one renderer.
-  const { runner } = createWindowModuleRunner(parsedData.data.modules);
-  const { createWindow, runWindow } = await runner.import<typeof WindowModule>("winui-svelte/window");
-  const { default: appComponent } = await runner.import("/App.svelte");
-  await runWindow({
-    onStart() {
-      createWindow({
-        component: appComponent,
-        props: {},
-        title: "Hello",
-        size: windowSize,
-        // Set for an unattended run: the window opens without taking focus.
-        isBackground: process.env["WINUI_SVELTE_BACKGROUND"] === "1"
-      });
-    }
-  });
-});
-```
-
-<!-- hello/window.ts:end -->
-
-`main.ts` is the host: it starts the Windows App SDK, the dev server and the
-window:
+`main.ts` is the host: `startDev` (the package's `/dev` entry) starts the Windows
+App SDK, the dev server and the window on its own thread, so that a saved file
+updates the open window; the pieces it joins (`startModuleServer`,
+`createWindowModuleRunner`, `runOnUiThread`) stay available for a host that
+needs its own:
 
 <!-- hello/main.ts:start -->
 
 ```ts
-import path from "node:path";
-import { MessageChannel, Worker } from "node:worker_threads";
-import { initWindowsAppSdk } from "winui-svelte/bootstrap";
-import { startModuleServer } from "winui-svelte/vite";
+import { startDev } from "winui-svelte/dev";
 
-// The host: it starts the Windows App SDK, serves the window's modules from a
-// Vite dev server (so a saved .svelte file updates the open window) and starts
-// the window, which runs on a worker because WinUI keeps its thread.
+// The host: it opens App.svelte in a window and keeps it live, so a saved
+// file updates the open window.
 //
 //   node main.ts
 
-initWindowsAppSdk();
-
-const modules = new MessageChannel();
-await startModuleServer({
+process.exitCode = await startDev({
   root: import.meta.dirname,
-  configFile: path.join(import.meta.dirname, "vite.config.ts"),
-  port: modules.port1
-});
-const worker = new Worker(new URL("./window.ts", import.meta.url), {
-  workerData: {
-    modules: modules.port2
-  },
-  transferList: [modules.port2]
-});
-worker.on("error", error => {
-  process.stderr.write(`${error.stack ?? String(error)}\n`);
-  process.exitCode = 1;
-});
-worker.on("exit", code => {
-  process.exit(process.exitCode ?? code);
+  configFile: `${import.meta.dirname}/vite.config.ts`,
+  component: "/App.svelte",
+  window: {
+    title: "Hello",
+    size: {
+      width: 480,
+      height: 320
+    },
+    isBackground: process.env["WINUI_SVELTE_BACKGROUND"] === "1"
+  }
 });
 ```
 
 <!-- hello/main.ts:end -->
 
+A Tauri or Electron app starts a file like this as its sidecar (a Node process the
+framework owns), with `host: "stdio"` or a transport of its own; the component
+then receives the framework's state as a `channel` prop (see the [dev loop in
+API.md](https://github.com/avi12/winui-svelte/blob/main/API.md#dev-loop-winui-sveltedev) and the
+[hosts section](https://github.com/avi12/winui-svelte/blob/main/API.md#hosts-tauri-electron-and-node))
+
 ```sh
 node main.ts
 ```
@@ -548,6 +527,7 @@ build error with its file and line; nothing is silently ignored
 | `background-image` or `background` with `linear-gradient()` or `radial-gradient()` | a `LinearGradientBrush` or `RadialGradientBrush` Background (a sheet that uses one carries the parser; one that does not, does not) |
 | `width`, `height`, `min-*`, `max-*` | `Width`, `Height`, `MinWidth`... |
 | `font-size`, `font-weight`, `font-family`, `font-style`, `line-height`, `letter-spacing`, `text-align`, `text-wrap`, `text-overflow`, `text-decoration` | the `TextBlock` and `Control` font and text properties |
+| `font-variant-*`, `font-kerning`, `font-feature-settings`, `font: var(--type-body)` | the `Typography` attached properties of a TextBlock (small caps, numerals, ligatures, stylistic sets), and a step of WinUI's type ramp as the font size resource and weight of its style (`font-variation-settings` has no WinUI counterpart; see [`src/css/API.md`](https://github.com/avi12/winui-svelte/blob/main/src/css/API.md#typography-opentype-features-and-the-type-ramp)) |
 | `font-stretch`, `direction`, `background-clip`, `tab-index` | `FontStretch` (`ultra-condensed` to `ultra-expanded`), `FlowDirection` (`ltr`, `rtl`), `BackgroundSizing` (`border-box` is `OuterBorderEdge`, `padding-box` is `InnerBorderEdge`), `TabIndex` (a negative value sets `IsTabStop` to false) |
 | `gap`, `row-gap`, `column-gap` | `Spacing` (a stack), `RowSpacing` and `ColumnSpacing` (a grid) |
 | `flex-direction`, `display: flex` on a stack, `align-self`, `justify-self` | `Orientation`, `VerticalAlignment`, `HorizontalAlignment` |
@@ -555,14 +535,16 @@ build error with its file and line; nothing is silently ignored
 | `display: none`, `visibility`, `pointer-events`, `z-index`, `overflow` | `Visibility`, `IsHitTestVisible`, `Canvas.ZIndex`, the scroll bar visibilities |
 | `outline`, `outline-offset` | the focus visual: `FocusVisualPrimaryBrush`, `FocusVisualPrimaryThickness`, `FocusVisualMargin` |
 | `animation`, `@keyframes` | `Storyboard`s of key frames (opacity, size, colors, translate, scale, rotate, transform, and every keyword property such as `font-style` or `text-align`, which steps at the middle of an interval; `display` and `visibility` hold the visible value instead: a hide lands at the end of the animation and a show at its start), begun with the class |
+| `animation-timeline` (`scroll()`, `view()`, a name), `animation-range`, `scroll-timeline`, `view-timeline` | an `ExpressionAnimation` over the scroll viewer's manipulation property set that drives opacity, translate, scale and rotate on the compositor, so a header that collapses or a parallax runs while the UI thread is idle |
 | `box-shadow`, `aspect-ratio`, `user-select`, `object-fit`, `line-clamp`, `word-break` | a `ThemeShadow` of the blur's depth, a Height that follows the Width, `IsTextSelectionEnabled`, `Stretch`, `MaxLines`, `TextWrapping` |
 | `-winui-elevation` | a `ThemeShadow` lifted by its depth |
+| `-winui-shadow: composition`, `-winui-shadow-receiver`, `-winui-shadow-cast-on` | `box-shadow` drawn by a Composition `DropShadow` that keeps its colour, offset, blur and spread, and the Receivers of a `ThemeShadow` named by a group |
 | `filter`, `backdrop-filter`, `mix-blend-mode`, `mask-image` | an effect graph of Win2D effects (Gaussian blur, colour matrix, blend, alpha mask) that the element's Composition visual is drawn through; `backdrop-filter` samples a real backdrop brush |
 | `clip-path`: `inset()` (with `round`), `circle()`, `ellipse()`, `polygon()`, `path()` | a `CompositionGeometricClip` on the element's visual |
 | `translate`, `scale`, `rotate`, `transform-origin`, `transition`; `transform` (translate, scale, rotate, skew, matrix) | the UIElement transforms, their pivot (`CenterPoint`, 50% 50% as in CSS) and their implicit transitions; `transition` also runs a Storyboard for `width`, `height`, `min-` and `max-` sizes, `font-size`, `color` and `border-color` between values written out, and `allow-discrete` steps any keyword property: `display 200ms allow-discrete` keeps a hidden element shown until the transition ends, `text-align 200ms allow-discrete` changes it at the middle |
 | `var(--card-background-fill-color-default)` | `{ThemeResource CardBackgroundFillColorDefault}`: WinUI's own resources, so light and dark follow Windows |
 | `--name: value` on `:root`, or on a class | an app-wide resource, or one only the elements with that class (and their templates) see: `.danger { --button-background-pointer-over: red }` |
-| `.class`, `type`, `:hover`, `:focus`, `:active`, `:root`, `:where()` | class and type matching, the control's events, custom properties |
+| `.class`, `type`, `:hover`, `:focus`, `:active`, `:root`, `:where()` | class and type matching, the control's events (a Button's `:hover`, `:active` and `:disabled` brushes as the visual states of its template, see [`src/css/API.md`](https://github.com/avi12/winui-svelte/blob/main/src/css/API.md#pseudo-classes-on-a-templated-control-visual-states)), custom properties |
 
 </details>
 
@@ -577,6 +559,44 @@ is an error too, in the build and the editor, at the rule and naming the element
 that uses it, instead of a failure when the window opens
 The table of every unit is in [`src/css/API.md`](https://github.com/avi12/winui-svelte/blob/main/src/css/API.md#length-units)
 
+### Fonts
+
+A font file of the app is used by its family name: an `@font-face` whose `src`
+is a `url()` of the file, then the family in `font-family`
+
+```svelte
+<style>
+  @font-face {
+    font-family: "Material Symbols Rounded";
+    src: url("./fonts/MaterialSymbolsRounded.ttf");
+  }
+
+  .icon {
+    font-family: "Material Symbols Rounded";
+  }
+</style>
+```
+
+- The family must be the name written inside the font file; WinUI finds the
+  file by that name, and a different name falls back to the default font
+  without an error
+- A relative `url()` is relative to the stylesheet; in a built app the sheet is
+  part of the bundle, so the file is also looked for by its name beside the
+  bundle (copy the fonts there); a file that is not found is an error naming the
+  places looked
+- Only `font-family` and `src` mean something: WinUI takes the weight, style and
+  width from the font file itself, so `font-weight`, `font-style`,
+  `font-stretch` and `unicode-range` are a warning; the first `url()` of `src`
+  is used, and a web address is an error (a font is a file next to the app)
+- One file per family name; registering a name again replaces its file
+- It works in a plain Node process, the case that is tested (a packaged app is
+  not): the file is handed to WinUI as `ms-appx:///` and its absolute path, with
+  the family name after a `#`; nothing is installed on the machine
+- The same from code: `registerFont({ family, source })` from
+  `winui-svelte/css`, or the web `FontFace` and `document.fonts.add(face)` once
+  `installFontFaces()` from `winui-svelte/web-apis/fonts` has run; a family
+  added later is used by the controls created after it
+
 ### Scoping
 
 A rule in a component's `<style>` reaches only the elements and the component
@@ -716,6 +736,37 @@ The animation moves the control's `Opacity`, `Translation`, `Scale`,
 See
 [API.md](https://github.com/avi12/winui-svelte/blob/main/API.md) for the details and what WinUI cannot do
 
+A card whose content grows or shrinks glides to its new height with
+`@attach glideHeight()` (WinUI cannot animate `Height="Auto"`; this is a
+`ResizeObserver` plus `element.animate({ height })` in one attachment, and
+needs `enableElementAnimation()` once)
+
+</details>
+
+## Wrapping chips
+
+<details>
+<summary>A row that wraps onto further lines</summary>
+
+WinUI has no `flex-wrap`; a `RichTextBlock` wraps its inline children like
+words, and an `InlineUIContainer` makes a chip one of them, so chips of any width
+wrap (`VariableSizedWrapGrid` wraps too, with one cell size for all):
+
+```svelte
+<RichTextBlock>
+  <Paragraph>
+    {#each links as link (link.href)}
+      <InlineUIContainer>
+        <HyperlinkButton navigateUri={link.href}>{link.label}</HyperlinkButton>
+      </InlineUIContainer>
+    {/each}
+  </Paragraph>
+</RichTextBlock>
+```
+
+See
+[API.md](https://github.com/avi12/winui-svelte/blob/main/API.md) for the measured comparison
+
 </details>
 
 ## Accessibility and theming
@@ -802,7 +853,10 @@ conditions on `exports`), which your Vite compiles (`winuiSvelte()`)
 | `winui-svelte/state` | the window's side of host state |
 | `winui-svelte/state/host` | a JavaScript host's side: `diff`, transports, message types |
 | `winui-svelte/messaging` | `defineMessaging`: typed request and response messages over a transport, loadable in plain Node |
+| `winui-svelte/messaging/web-view2`, `/messaging/page` | `webView2Transport` and the `WebView2` helpers (scripts, cookies, downloads, permissions); the web page's end of the link, free of WinUI (both opt-in) |
+| `winui-svelte/messaging/web-view2`, `/messaging/page` | `webView2Transport` and the `WebView2` helpers (scripts, cookies, downloads, permissions); the web page's end of the link, free of WinUI (both opt-in) |
 | `winui-svelte/vite` | `winuiSvelte()` for `vite.config.ts`; `startModuleServer()` for hot reload; `buildApp()` for the production bundle |
+| `winui-svelte/dev` | `startDev()`, one call that opens a component in a window and keeps it live as the files are saved |
 | `winui-svelte/runner` | `createWindowModuleRunner()`, the window thread's side of the module server |
 | `winui-svelte/window` | `runWindow`, `createWindow`, `startTimer`, `exitApplication`, `systemSettings` |
 | `winui-svelte/thread` | `runOnUiThread`, the first call of the UI thread's worker |
@@ -812,16 +866,29 @@ conditions on `exports`), which your Vite compiles (`winuiSvelte()`)
 | `winui-svelte/element-animation` | `enableElementAnimation` (the Vite plugin calls it for you; Svelte's `transition:` and `animate:` run on WinUI) |
 | `winui-svelte/attached-owners` | `preloadAttachedOwners` (the Vite plugin calls it for a component that names `canvasLeft`, `gridRow` and the like, so a placed control has its place at its first layout; a prop named nowhere needs the call by hand) |
 | `winui-svelte/element-effects` | `enableElementEffects` (the Vite plugin calls it from a component that imports `blur` or `draw`): the blur transition blurs for real and `draw` measures a `path`, with Composition and Win2D |
-| `winui-svelte/app` | single-instance handling over a named pipe, and app notifications |
+| `winui-svelte/app` | single-instance handling over a named pipe, app notifications, `activateOrLaunch` to signal or start the app from another process, `relaunch` and restart after a crash |
+| `winui-svelte/app/activation` | `navigator.registerProtocolHandler`, `registerFileTypes`, `launchAtLogin` for the current user, and every start (link, file, sign-in, a later copy) as one typed `ActivationEvent` (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#activation-winui-svelteappactivation)) |
 | `winui-svelte/bindings/*` | Every bound WinRT and Windows App SDK class as it is named there, for the as-is kind (`winui-svelte/bindings/windows/storage/StorageFolder`) |
 | `winui-svelte/web-apis`, `/web-apis/notification`, `/web-apis/media-devices`, `/web-apis/speech`, `/web-apis/media-session` | `installWebApis`, `installPermissions` and the Web APIs as opt-in installers: `Notification` over app notifications, media devices, speech and the media session (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#web-apis-winui-svelteweb-apis)) |
 | `winui-svelte/data-transfer` | web-shaped drag and drop, `NativeFile`, pickers, the clipboard and the launcher (opt-in) |
+| `winui-svelte/input` | the web's pointer, wheel, key and focus events on any element (`enableInputEvents`), pointer capture, `activeElement`, `moveFocus`, `trapFocus` (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#input-events-and-focus-winui-svelteinput)) |
 | `winui-svelte/media` | `bitmapImageOf`, `svgImageSourceOf`, `createMediaPlayer`: image sources and a windowless `MediaPlayer` (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#media-winui-sveltemedia)) |
+| `winui-svelte/app/hotkeys` | `registerHotkey`: a system-wide key combination, heard in any app (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#global-hotkeys-winui-svelteapphotkeys)) |
 | `winui-svelte/tray` | `TrayIcon`, `createTrayIcon`, `hideToTray`: a notification-area icon (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#system-tray-winui-sveltetray)) |
+| `winui-svelte/tray/standalone` | `createStandaloneTray`: a notification-area icon and a native popup menu in a plain Node process, with no window, no WinUI and no components, that starts or signals the full app (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#tray-with-no-window-winui-sveltetraystandalone)) |
+| `winui-svelte/notice` | `showNotice`: a message box with no window or app, for a check that ends a run before it starts (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#notice-with-no-app-winui-sveltenotice)) |
+| `winui-svelte/window/taskbar` | `handle.taskbar`: a progress bar, an overlay icon or badge and flashing on the window's taskbar button, and the unpackaged `setAppBadge` fallback (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#taskbar-button-winui-sveltewindowtaskbar)) |
 | `winui-svelte/forms` | `Form`, `FormField` and the attachments that join a control to a form by name, with HTML's constraint validation and zod (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#forms-winui-svelteforms)) |
+| `winui-svelte/store` | `getAppLicense`, `watchLicense`, `checkForUpdates`, `watchPackages`, `getStartupTask`: the Store licence, updates, package events and startup task, answering `hasPackage: false` outside a package (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#store-and-package-winui-sveltestore)) |
+| `winui-svelte/accessibility`, `/accessibility/audit` | `announce` and `liveRegion` say a change to a screen reader (`aria-live`, `role="alert"`) over UI Automation notifications; `auditAccessibility` checks a window for unnamed buttons, unlabeled inputs, duplicate access keys and low contrast (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#accessibility-winui-svelteaccessibility)) |
 | `winui-svelte/devices`, `/devices/enumeration`, `/devices/input`, `/devices/bluetooth`, `/devices/printers`, `/devices/power`, `/devices/network`, `/devices/audio`, `/devices/display`, `/devices/gamepad`, `/devices/sensors` | device enumeration, input devices, Bluetooth, printers, power, network, displays, audio, gamepads, sensors: Windows' own device APIs as runes (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#windows-devices-winui-sveltedevices)) |
+| `winui-svelte/implicit-layout-animation` | `implicitLayoutAnimation`, `LayoutEasing`: the children of a panel slide to their new places when the layout moves them |
+| `winui-svelte/settings` | `SettingsCard`, `SettingsExpander`: Fluent settings cards after the Community Toolkit's |
+| `winui-svelte/scroll-timeline` | `installScrollTimeline`: `ScrollTimeline`, `ViewTimeline` and `element.animate(keyframes, { timeline })` over Composition (opt-in) |
+| `winui-svelte/view-transitions` | `installViewTransitions`: `document.startViewTransition` over WinUI's connected animations, paired by `view-transition-name` (opt-in) |
 | `winui-svelte/connected-animation` | `connectElement` and `startConnected`, WinUI's connected animation between pages |
-| `winui-svelte/css/transform`, `/css/animation`, `/css/effects`, `/css/filter`, `/css/clip`, `/css/focus`, `/css/surface`, `/css/position`, `/css/container`, `/css/queries`, `/css/environment`, `/css/compat`, `/css/resources` | the opt-in CSS groups: 2D transform, animations, aspect ratio, filters and masks, clip shapes, focus visuals, surfaces, position and inset, media and container queries, media preferences and display features, browser-stylesheet properties, theme resources ([`src/css/API.md`](https://github.com/avi12/winui-svelte/blob/main/src/css/API.md)) |
+| `winui-svelte/composition` | `animateOnCompositor`, `compositorAnimation`, `visualReference`, `createPropertySet` and springs: typed expression and spring animations the compositor runs off the UI thread (opt-in; [`API.md`](https://github.com/avi12/winui-svelte/blob/main/API.md#composition-animations-winui-sveltecomposition)) |
+| `winui-svelte/css/transform`, `/css/animation`, `/css/scroll-timeline`, `/css/typography`, `/css/visual-states`, `/css/effects`, `/css/filter`, `/css/clip`, `/css/focus`, `/css/surface`, `/css/shadow`, `/css/position`, `/css/container`, `/css/queries`, `/css/environment`, `/css/compat`, `/css/resources`, `/css/view-transition` | the opt-in CSS groups: 2D transform, animations, OpenType typography, the state brushes of a Button, aspect ratio, filters and masks, clip shapes, focus visuals, surfaces and Composition shadows, position and inset, media and container queries, media preferences and display features, browser-stylesheet properties, theme resources, view transition names ([`src/css/API.md`](https://github.com/avi12/winui-svelte/blob/main/src/css/API.md)) |
 | `winui-svelte/css`, `/css/vite`, `/css/sheet-module`, `/css/gradients`, `/css/shape`, `/css/control`, `/css/stylesheet` | the CSS runtime, its Vite plugin, the sheet module compiler, the gradient parser a sheet with a gradient imports and the type declaration for a `.css` import ([`src/css/API.md`](https://github.com/avi12/winui-svelte/blob/main/src/css/API.md)) |
 | `winui-svelte/preprocess`, `winui-svelte/stylelint`, `winui-svelte/vscode-css-data.json` | the editor side of the CSS: a Svelte preprocessor, a stylelint rule and VS Code custom data, all from the same validator and tables, so the editor, the linter and the build say the same thing ([`src/css/API.md`](https://github.com/avi12/winui-svelte/blob/main/src/css/API.md#diagnostics-in-the-editor-the-linter-and-the-build)) |
 
@@ -904,6 +971,13 @@ Stated plainly, so nobody finds them by surprise:
   `acrylicThin` put WinUI's `DesktopAcrylicController` behind the window, so
   `window.systemBackdrop` reads null for them (the controller holds the
   material)
+- **Transparent windows are a composition brush and a window frame.**
+  `backdrop="transparent"` puts a fully clear brush behind the content, since
+  the Windows App SDK's `TransparentTintBackdrop` is in no runtime from 2.3 to
+  2.6.5 and not in the metadata restored, and makes the whole window the window
+  manager's frame with square corners, which is what makes the clear pixels
+  show the desktop; `window.systemBackdrop` reads null for it, and the window
+  wants `isBorderless`
 - **Svelte is held to the releases checked.** The package reads a few spots of
   Svelte's runtime with edits, so the peer range is the span of releases the
   matrix (`pnpm check:svelte-matrix`) runs the tests against, and it widens
@@ -918,13 +992,16 @@ Stated plainly, so nobody finds them by surprise:
 - **A property whose name starts with "on"** (`ToggleSwitch.OnContent`) is a
   prop on components, but on a raw element Svelte takes the attribute for an
   event: write it as `On-content="On"` or `on-content={() => "On"}`
-- **No `:hover` or `:active` miracles on templated controls.** A pseudo-class
-  applies a Style when the control reports the event, but WinUI's own template
-  states (a Button's pointer-over and pressed brushes) take over from a Style's
-  setters while they are active, and a control that handles an event itself (a
-  Button handles `PointerPressed`) never reports it, so `:active` does nothing
-  there
-  Override the control's theme resources instead
+- **`:hover`, `:active` and `:disabled` reach a templated control as visual
+  states for a Button, not for every control.** On a `button`,
+  `repeat-button`, `hyperlink-button` and `drop-down-button` a rule's
+  `background-color`, `background-image`, `color` and `border-color` become
+  the `PointerOver`, `Pressed` and `Disabled` states of its template, so
+  `:active` works where the control handles the pointer itself
+  Any other control, any other property, `:checked` and a Button's `:focus`
+  stay a Style when the control reports the event, which WinUI's template
+  states take over from while they are active; override the control's theme
+  resources there ([`src/css/API.md`](https://github.com/avi12/winui-svelte/blob/main/src/css/API.md#pseudo-classes-on-a-templated-control-visual-states))
 - **Transitions on a raw element.** `blur` and `draw` need
   `winui-svelte/element-effects` (the Vite plugin turns it on for a component
   that imports either), and without it `blur` only fades; a directive goes on a
@@ -961,7 +1038,7 @@ Stated plainly, so nobody finds them by surprise:
   against the component's markup at build time
   A Style cannot reach an element's parent, children or siblings, so these are
   build errors that say what to write instead: `float`, `position: sticky`,
-  `right` and `bottom`, `flex-wrap` (WinUI has no wrapping panel), a % size other than
+  `right` and `bottom`, `flex-wrap` (WinUI has no wrapping panel; see "Wrapping chips"), a % size other than
   100%, `calc()` with a % or a variable, any unit but px, deg, s, ms, fr, auto and unitless numbers (the compiler and
   stylelint both refuse it), container style queries, `:has()`, `:focus-within`,
   `clip-path` as

package/dist/accessibility/announce.d.ts

@@ -0,0 +1,22 @@
+import { LivePriority } from "./live-priority.js";
+import { UIElement } from "#winui/microsoft/ui/xaml/UIElement";
+/** What `announce` takes. */
+export interface AnnounceOptions {
+    /** The text a screen reader speaks. */
+    readonly message: string;
+    /** An element of the window the message is raised from (an `elementRef`'s `current`). */
+    readonly element: UIElement;
+    /** `POLITE` queues behind speech; `ASSERTIVE` interrupts; `OFF` says nothing. Polite by default. */
+    readonly priority?: LivePriority | undefined;
+}
+/**
+ * Says something to a screen reader without moving focus: a UI Automation
+ * notification (`AutomationPeer.RaiseNotificationEvent`), as writing to an
+ * `aria-live` region, `role="status"` (polite) or `role="alert"` (assertive).
+ * A layout panel has no automation peer, so the notification is raised from
+ * the nearest element above it that has one.
+ *
+ * @param options - The message, the element to raise it from and the priority.
+ */
+export declare function announce({ message, element, priority }: AnnounceOptions): void;
+//# sourceMappingURL=announce.d.ts.map

package/dist/accessibility/announce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"announce.d.ts","sourceRoot":"","sources":["../../src/accessibility/announce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAOlD,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAE/D,6BAA6B;AAC7B,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAC9C;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,QAA8B,EAAE,EAAE,eAAe,QAM7F"}

package/dist/accessibility/announce.js

@@ -0,0 +1,52 @@
+import { LivePriority } from "./live-priority.js";
+import { raiseAnnouncement } from "./notification.js";
+import { projectAs, releaseProjected } from "#winui/lifetime";
+import { FrameworkElementAutomationPeer } from "#winui/microsoft/ui/xaml/automation/peers/FrameworkElementAutomationPeer";
+import { VisualTreeHelper } from "#winui/microsoft/ui/xaml/media/VisualTreeHelper";
+import { UIElement } from "#winui/microsoft/ui/xaml/UIElement";
+function peerOf(element) {
+    const existing = FrameworkElementAutomationPeer.fromElement(element);
+    return existing ?? FrameworkElementAutomationPeer.createPeerForElement(element);
+}
+// A layout panel has no automation peer; the notification is raised from the
+// nearest element above it that has one.
+function nearestPeer(element) {
+    const projected = [];
+    try {
+        for (let current = element;; current = projected[projected.length - 1] ?? current) {
+            const peer = peerOf(current);
+            const isFound = peer != null;
+            if (isFound) {
+                return peer;
+            }
+            const parent = VisualTreeHelper.getParent(current);
+            const isRoot = parent == null;
+            if (isRoot) {
+                throw new Error("announce needs an element in a window, with an automation peer or under one");
+            }
+            projected.push(projectAs(parent, UIElement));
+        }
+    }
+    finally {
+        for (const parent of projected) {
+            releaseProjected(parent);
+        }
+    }
+}
+/**
+ * Says something to a screen reader without moving focus: a UI Automation
+ * notification (`AutomationPeer.RaiseNotificationEvent`), as writing to an
+ * `aria-live` region, `role="status"` (polite) or `role="alert"` (assertive).
+ * A layout panel has no automation peer, so the notification is raised from
+ * the nearest element above it that has one.
+ *
+ * @param options - The message, the element to raise it from and the priority.
+ */
+export function announce({ message, element, priority = LivePriority.POLITE }) {
+    raiseAnnouncement({
+        peer: nearestPeer(element),
+        message,
+        priority
+    });
+}
+//# sourceMappingURL=announce.js.map

package/dist/accessibility/announce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"announce.js","sourceRoot":"","sources":["../../src/accessibility/announce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EACL,8BAA8B,EAC/B,MAAM,0EAA0E,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,iDAAiD,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAY/D,SAAS,MAAM,CAAC,OAAkB;IAChC,MAAM,QAAQ,GAAG,8BAA8B,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrE,OAAO,QAAQ,IAAI,8BAA8B,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAClF,CAAC;AAED,6EAA6E;AAC7E,yCAAyC;AACzC,SAAS,WAAW,CAAC,OAAkB;IACrC,MAAM,SAAS,GAAgB,EAAE,CAAC;IAClC,IAAI,CAAC;QACH,KAAK,IAAI,OAAO,GAAG,OAAO,GAAI,OAAO,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;YACnF,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;YAC7B,MAAM,OAAO,GAAG,IAAI,IAAI,IAAI,CAAC;YAC7B,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,IAAI,CAAC;YACd,CAAC;YAED,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YACnD,MAAM,MAAM,GAAG,MAAM,IAAI,IAAI,CAAC;YAC9B,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAC;YACjG,CAAC;YAED,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;YAAS,CAAC;QACT,KAAK,MAAM,MAAM,IAAI,SAAS,EAAE,CAAC;YAC/B,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAG,YAAY,CAAC,MAAM,EAAmB;IAC5F,iBAAiB,CAAC;QAChB,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC;QAC1B,OAAO;QACP,QAAQ;KACT,CAAC,CAAC;AACL,CAAC"}

package/dist/accessibility/audit/accessibility-rules.json

@@ -0,0 +1,100 @@
+[
+  {
+    "id": "unnamed-button",
+    "appliesTo": [
+      "Button",
+      "SplitButton"
+    ],
+    "message": "The button has no accessible name: a screen reader says only \"button\" (an icon-only button has no text to fall back on)",
+    "suggestion": "Set automationName, or give the button text or a label"
+  },
+  {
+    "id": "unlabeled-input",
+    "appliesTo": [
+      "Edit",
+      "ComboBox",
+      "Slider",
+      "Spinner",
+      "CheckBox",
+      "RadioButton"
+    ],
+    "message": "The input has no label: a screen reader cannot say what to enter",
+    "suggestion": "Set a header, automationName or automationLabeledBy (an elementRef of the label)"
+  },
+  {
+    "id": "duplicate-access-key",
+    "appliesTo": [
+      "Button",
+      "SplitButton",
+      "Edit",
+      "ComboBox",
+      "Slider",
+      "Spinner",
+      "CheckBox",
+      "RadioButton",
+      "Hyperlink",
+      "MenuItem",
+      "TabItem",
+      "ListItem",
+      "TreeItem"
+    ],
+    "message": "Another element has the same access key: Alt shortcuts reach only one of them",
+    "suggestion": "Give each element in the window its own accessKey"
+  },
+  {
+    "id": "zero-size-focusable",
+    "appliesTo": [
+      "Button",
+      "SplitButton",
+      "Edit",
+      "ComboBox",
+      "Slider",
+      "Spinner",
+      "CheckBox",
+      "RadioButton",
+      "Hyperlink",
+      "MenuItem",
+      "TabItem",
+      "ListItem",
+      "TreeItem"
+    ],
+    "message": "The element takes focus but has no size: keyboard focus lands on nothing visible",
+    "suggestion": "Give it a width and height, collapse it, or set isTabStop to false"
+  },
+  {
+    "id": "unreachable-by-keyboard",
+    "appliesTo": [
+      "Button",
+      "SplitButton",
+      "Edit",
+      "ComboBox",
+      "Slider",
+      "Spinner",
+      "CheckBox",
+      "RadioButton",
+      "Hyperlink",
+      "MenuItem",
+      "TabItem",
+      "ListItem",
+      "TreeItem"
+    ],
+    "message": "The control is no tab stop and has no access key or keyboard accelerator: a keyboard user cannot reach it",
+    "suggestion": "Set isTabStop to true, or give it an accessKey or a keyboardAccelerator"
+  },
+  {
+    "id": "low-contrast-text",
+    "appliesTo": [
+      "Text",
+      "Button",
+      "SplitButton",
+      "Edit",
+      "ComboBox",
+      "Slider",
+      "Spinner",
+      "CheckBox",
+      "RadioButton"
+    ],
+    "message": "The text is below the WCAG AA contrast (4.5 to 1, or 3 to 1 for large text) against its background",
+    "suggestion": "Use a darker or lighter foreground, or a theme brush"
+  }
+]

package/dist/accessibility/audit/audit-tree.d.ts

@@ -0,0 +1,48 @@
+import type { Rgba } from "./contrast.js";
+import type { AccessibilityRuleId } from "./rules.js";
+/** What a host (the real visual tree, or a test's stand-in) tells the audit of one element. */
+export interface ElementFacts {
+    readonly className: string;
+    readonly controlType: string;
+    readonly name: string;
+    readonly automationId: string;
+    readonly hasLabeledBy: boolean;
+    readonly accessKey: string;
+    readonly isEnabled: boolean;
+    readonly isTabStop: boolean;
+    readonly isKeyboardFocusable: boolean;
+    readonly hasAccelerator: boolean;
+    readonly width: number;
+    readonly height: number;
+    readonly foreground: Rgba | null;
+    readonly background: Rgba | null;
+    readonly fontSize: number;
+    readonly fontWeight: number;
+}
+/** A visual tree the audit can walk; `null` from `describe` skips the element and what is under it. */
+export interface AuditHost<Element extends object> {
+    childrenOf(element: Element): readonly Element[];
+    describe(element: Element): ElementFacts | null;
+}
+/** One problem the audit found, with where it is and what to do. */
+export interface AccessibilityFinding {
+    readonly ruleId: AccessibilityRuleId;
+    readonly message: string;
+    readonly suggestion: string;
+    /** The classes from the root, each with its index among its siblings: `Grid[0]/Button[1]`. */
+    readonly path: string;
+    readonly className: string;
+    readonly automationId: string;
+    readonly name: string;
+}
+/**
+ * Checks a visual tree against the table of rules.
+ *
+ * @param options - The tree's root and the host that reads it.
+ * @returns The findings, in tree order.
+ */
+export declare function auditTree<Element extends object>({ root, host }: {
+    root: Element;
+    host: AuditHost<Element>;
+}): AccessibilityFinding[];
+//# sourceMappingURL=audit-tree.d.ts.map