drawnui-react 0.1.0-preview.8 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/README.md +229 -22
  2. package/SKIPPED.md +38 -29
  3. package/dist/controls/AnimatedFramesRenderer.d.ts +9 -0
  4. package/dist/controls/AnimatedFramesRenderer.js +18 -1
  5. package/dist/controls/DrawnGame.d.ts +44 -0
  6. package/dist/controls/DrawnGame.js +82 -0
  7. package/dist/controls/GridStructure.d.ts +25 -3
  8. package/dist/controls/GridStructure.js +81 -5
  9. package/dist/controls/SkiaBackdrop.d.ts +8 -2
  10. package/dist/controls/SkiaBackdrop.js +42 -14
  11. package/dist/controls/SkiaButton.d.ts +17 -3
  12. package/dist/controls/SkiaButton.js +26 -8
  13. package/dist/controls/SkiaCarousel.d.ts +22 -3
  14. package/dist/controls/SkiaCarousel.js +85 -9
  15. package/dist/controls/SkiaCheckbox.d.ts +0 -1
  16. package/dist/controls/SkiaCheckbox.js +2 -7
  17. package/dist/controls/SkiaDrawer.d.ts +15 -0
  18. package/dist/controls/SkiaDrawer.js +42 -7
  19. package/dist/controls/SkiaEditor.d.ts +51 -2
  20. package/dist/controls/SkiaEditor.js +292 -58
  21. package/dist/controls/SkiaGif.d.ts +7 -0
  22. package/dist/controls/SkiaGif.js +25 -4
  23. package/dist/controls/SkiaImage.d.ts +10 -0
  24. package/dist/controls/SkiaImage.js +80 -19
  25. package/dist/controls/SkiaLabel.d.ts +200 -11
  26. package/dist/controls/SkiaLabel.js +925 -93
  27. package/dist/controls/SkiaLabelFps.d.ts +12 -0
  28. package/dist/controls/SkiaLabelFps.js +35 -0
  29. package/dist/controls/SkiaLayout.d.ts +89 -9
  30. package/dist/controls/SkiaLayout.js +397 -23
  31. package/dist/controls/SkiaLottie.js +5 -3
  32. package/dist/controls/SkiaProgress.d.ts +2 -1
  33. package/dist/controls/SkiaProgress.js +8 -5
  34. package/dist/controls/SkiaRadioButton.d.ts +2 -0
  35. package/dist/controls/SkiaRadioButton.js +16 -4
  36. package/dist/controls/SkiaRichLabel.d.ts +1 -1
  37. package/dist/controls/SkiaRichLabel.js +11 -1
  38. package/dist/controls/SkiaScroll.d.ts +86 -7
  39. package/dist/controls/SkiaScroll.js +361 -40
  40. package/dist/controls/SkiaScrollBar.d.ts +27 -0
  41. package/dist/controls/SkiaScrollBar.js +51 -2
  42. package/dist/controls/SkiaShaderCarousel.d.ts +11 -1
  43. package/dist/controls/SkiaShaderCarousel.js +27 -5
  44. package/dist/controls/SkiaShape.d.ts +15 -2
  45. package/dist/controls/SkiaShape.js +57 -10
  46. package/dist/controls/SkiaShell.d.ts +282 -0
  47. package/dist/controls/SkiaShell.js +972 -0
  48. package/dist/controls/SkiaSlider.d.ts +20 -2
  49. package/dist/controls/SkiaSlider.js +61 -7
  50. package/dist/controls/SkiaSprite.d.ts +4 -0
  51. package/dist/controls/SkiaSprite.js +27 -11
  52. package/dist/controls/SkiaSvg.d.ts +4 -0
  53. package/dist/controls/SkiaSvg.js +28 -4
  54. package/dist/controls/SkiaSwitch.d.ts +0 -1
  55. package/dist/controls/SkiaSwitch.js +4 -8
  56. package/dist/controls/SkiaToggle.d.ts +25 -5
  57. package/dist/controls/SkiaToggle.js +58 -5
  58. package/dist/controls/SnappingLayout.d.ts +12 -1
  59. package/dist/controls/SnappingLayout.js +21 -2
  60. package/dist/controls/TooltipStyle.d.ts +52 -0
  61. package/dist/controls/TooltipStyle.js +88 -0
  62. package/dist/core/Accessibility.d.ts +162 -11
  63. package/dist/core/Accessibility.js +882 -22
  64. package/dist/core/Animators.d.ts +37 -1
  65. package/dist/core/Animators.js +102 -9
  66. package/dist/core/Canvas.d.ts +307 -8
  67. package/dist/core/Canvas.js +1202 -66
  68. package/dist/core/ControlStyle.d.ts +2 -0
  69. package/dist/core/ControlStyle.js +2 -0
  70. package/dist/core/DesignerActions.d.ts +32 -0
  71. package/dist/core/DesignerActions.js +68 -0
  72. package/dist/core/Easing.d.ts +12 -1
  73. package/dist/core/Easing.js +25 -1
  74. package/dist/core/Gestures.d.ts +86 -2
  75. package/dist/core/Gestures.js +184 -4
  76. package/dist/core/Hover.d.ts +51 -0
  77. package/dist/core/Hover.js +140 -0
  78. package/dist/core/ImageEffects.d.ts +2 -0
  79. package/dist/core/ImageEffects.js +2 -0
  80. package/dist/core/KeyboardManager.d.ts +40 -0
  81. package/dist/core/KeyboardManager.js +98 -8
  82. package/dist/core/PopupWindows.d.ts +94 -0
  83. package/dist/core/PopupWindows.js +207 -0
  84. package/dist/core/Props.d.ts +11 -0
  85. package/dist/core/Props.js +44 -0
  86. package/dist/core/ScrollAnimators.d.ts +6 -0
  87. package/dist/core/ScrollAnimators.js +16 -1
  88. package/dist/core/Shaping.d.ts +40 -0
  89. package/dist/core/Shaping.js +224 -0
  90. package/dist/core/SkiaControl.d.ts +306 -13
  91. package/dist/core/SkiaControl.js +681 -75
  92. package/dist/core/SkiaEffect.d.ts +29 -1
  93. package/dist/core/SkiaEffect.js +78 -16
  94. package/dist/core/SkiaImageManager.d.ts +101 -18
  95. package/dist/core/SkiaImageManager.js +318 -63
  96. package/dist/core/Styles.js +7 -1
  97. package/dist/core/Super.d.ts +33 -2
  98. package/dist/core/Super.js +58 -12
  99. package/dist/core/TextInputProxy.d.ts +31 -1
  100. package/dist/core/TextInputProxy.js +97 -15
  101. package/dist/core/Tooltips.d.ts +71 -0
  102. package/dist/core/Tooltips.js +205 -0
  103. package/dist/core/Types.d.ts +11 -1
  104. package/dist/core/Types.js +32 -1
  105. package/dist/core/ViewsAdapter.d.ts +7 -2
  106. package/dist/core/ViewsAdapter.js +10 -3
  107. package/dist/index.d.ts +8 -0
  108. package/dist/index.js +8 -0
  109. package/dist/react/SkiaShell.d.ts +8 -74
  110. package/dist/react/SkiaShell.js +163 -475
  111. package/dist/react/index.d.ts +48 -4
  112. package/dist/react/index.js +210 -43
  113. package/dist/react/reconciler.d.ts +32 -0
  114. package/dist/react/reconciler.js +71 -40
  115. package/dist/vite/index.d.ts +9 -0
  116. package/dist/vite/index.js +36 -3
  117. package/package.json +103 -5
package/README.md CHANGED
@@ -1,13 +1,15 @@
1
- # DrawnUi.React
1
+ # DrawnUI for React
2
2
 
3
- [DrawnUi](https://drawnui.net) engine ptototype for React, TypeScript on top of
4
- [CanvasKit](https://skia.org/docs/user/modules/canvaskit/) (Skia for the browser), composed with React
5
- through a custom `react-reconciler` renderer.
3
+ ![DrawnUI for React: the Hello app in desktop browsers, on iPhone and on Android](.github/images/banner.png)
6
4
 
7
- Check out latest playbook: [helloreact.drawnui.net](https://helloreact.drawnui.net/) 👈
5
+ [![npm](https://img.shields.io/npm/v/drawnui-react.svg)](https://www.npmjs.com/package/drawnui-react)
6
+ ![License](https://img.shields.io/github/license/DrawnUi/DrawnUi.React.svg)
8
7
 
9
- *Work in progress*: the goal is same API surface and semantics as DrawnUi (.NET) — same control names, same PascalCase
10
- property names, same measure/arrange/paint contract — so knowledge and docs transfer 1:1.
8
+ Build rich, fluid UI for the web by drawing it. Every control is painted on one hardware-accelerated canvas by
9
+ DrawnUI, the Skia engine behind DrawnUI for .NET and Rust, and you compose it with React: JSX, hooks, state, the
10
+ way you already work.
11
+
12
+ Live demo: [helloreact.drawnui.net](https://helloreact.drawnui.net) · Playground: [drawfiddle.com](https://drawfiddle.com) · Docs: [drawnui.net](https://drawnui.net/articles/react/index.html)
11
13
 
12
14
  ```tsx
13
15
  await Super.UseDrawnUi()
@@ -22,15 +24,195 @@ await Super.UseDrawnUi()
22
24
  </Canvas>
23
25
  ```
24
26
 
27
+ ## One family
28
+
29
+ DrawnUI for React is the same engine as [DrawnUI for .NET](https://github.com/DrawnUi/DrawnUi.Net) (MAUI, Blazor,
30
+ WPF, OpenTK, WebAssembly) and [DrawnUI for Rust](https://github.com/DrawnUi/DrawnUi.Rust): the same controls,
31
+ property names, layout and drawing rules. What you learn here works there, and screens move between them.
32
+
33
+ ## What you get, all drawn on one canvas
34
+
35
+ - **Layouts:** stacks, rows, grids, wrap and masonry, layers with any alignment.
36
+ - **Lists that stay smooth:** 100 000 recycled rows, items of different heights, load more at both ends.
37
+ - **Animations:** a frame loop for anything, Lottie and GIF, spritesheets.
38
+ - **Transforms in 2D and 3D:** rotate, scale, skew, perspective and depth; taps still land on the right control.
39
+ - **Gestures:** tap, long press, pan, swipe, drag to reorder, mouse hover, right-click menus.
40
+ - **Shaders:** SkSL effects on any control, shader transitions between images.
41
+ - **Navigation:** shell with pages, popups, modals, toasts, carousel and drawer.
42
+ - **Text:** rich spans, markdown, emoji and symbols, a drawn text editor.
43
+ - **Keyboard:** Tab, arrows, Enter and Escape move through every control, list, menu and dialog.
44
+ - **Accessibility:** screen readers read your drawn UI, names, values and dialogs included.
45
+ - **Games:** a game loop and sprites, with Pong as a sample.
46
+ - **AI-ready:** a [skill file](https://helloreact.drawnui.net/skills/drawnui-react/SKILL.md) teaches coding agents to build with it.
47
+
48
+ ## MIT, everywhere
49
+
50
+ DrawnUI is MIT licensed in every language and on every platform: desktop, mobile, web and embedded devices. Ship it in commercial products with no attribution badge, no about screen and no per-device royalty.
51
+
52
+ ## What's new in 1.0.1
53
+
54
+ - **First stable release:** `drawnui-react` and the 3D add-on `drawnui-react-add3d` are 1.0.1. Projects on
55
+ `0.1.0-preview.x` move to it with `npm i drawnui-react@^1.0.1` (and `drawnui-react-add3d@^1.0.1`): npm does not
56
+ take a major step by itself.
57
+ - **Smooth pictures on 3D models:** images on materials are drawn with their mipmaps and anisotropic filtering (the
58
+ product box of the [demo](https://add3dreact.drawnui.net)).
59
+ - **FPS counter:** the FPS counter shows the real frame rate: `SkiaLabelFps` keeps the canvas drawing while it is
60
+ shown, as in DrawnUI for .NET and Rust.
61
+
62
+ ## What's new in 0.1.0-preview.43
63
+
64
+ - **3D add-on:** [`drawnui-react-add3d`](https://www.npmjs.com/package/drawnui-react-add3d) puts real 3D inside the
65
+ drawn UI: glTF models with their animations, a product viewer that turns, zooms and resets, many animated
66
+ characters on a 2D field in one pass, shapes made in code, Lit, Toon and Flat looks. Live demo:
67
+ [add3dreact.drawnui.net](https://add3dreact.drawnui.net), article:
68
+ [drawnui.net/articles/add3d.html](https://drawnui.net/articles/add3d.html).
69
+ - **Text selection:** selectable labels (`AccessibilityTextSelectable`) select as in DrawnUi.Net, drawn in
70
+ `SkiaLabel.TextSelectionColor`: a mouse drag (across several labels, in reading order), a double click for a word, a
71
+ long press on touch with a Copy button; Ctrl+C copies, and the context menu sees the selection
72
+ (`canvas.SelectedText`, `CopyTextSelection()`, `ClearTextSelection()`).
73
+ - **Long press on touch:** a long press raises the context menu on phones and tablets too, in every browser; on
74
+ selectable text it selects the word first, or keeps the selection it presses on.
75
+ - **Long press time:** 0.75 s, the same in every DrawnUI engine; set it with `TouchEffect.LongPressTimeMsDefault`.
76
+ - **Text fields on phones:** a tap opens the on-screen keyboard at once, its return key ends editing in a single-line
77
+ field, and a keyboard the user closed stays closed while the page scrolls.
78
+ - **Fields above the keyboard:** `SkiaScroll.AdaptToKeyboardAuto` (opt-in, with `AdaptToKeyboardGap`) keeps the focused
79
+ field above the on-screen keyboard, the last field of a form too.
80
+ - **Double tap:** a double tap reaches the controls as two taps in iOS Safari too, and counts by when the taps
81
+ happened, so it holds while frames are busy (a 3D viewer's reset).
82
+ - **Screen readers:** the texts inside a button, radio, switch, tab or image are read once, as the control's name;
83
+ inside a scroll the reading and Tab order follow the content.
84
+ - **Password fields:** screen readers hear a password field's placeholder, never the typed text.
85
+ - **React 19.2:** the package declares React 19.2 or newer, the version its renderer runs on.
86
+ - **Right click in a text field:** a right click keeps the caret and the selection, so the context menu sees what was
87
+ selected.
88
+ - **Mouse wheel over text fields:** a focused text field no longer stops the mouse wheel: the page scrolls over the field
89
+ and around it.
90
+ - **Tab at typing speed:** Tab moves on at typing speed when focus scrolls the page.
91
+ - **Reading and Tab order:** the reading and Tab order of a page stays the same while it scrolls: Tab after the last
92
+ control comes back to the top.
93
+ - **Keyboard focus:** when the control with the keyboard focus disappears, the focus moves to the next control.
94
+ - **`FillBlendMode`** on controls and shapes.
95
+ - **Image loads:** a cancelled image load reports a cancel, as in DrawnUi.Net.
96
+
97
+ ## What's new in 0.1.0-preview.42
98
+
99
+ - **Images:** images that show the same file or URL share one decoded copy; image memory stays within a budget
100
+ (`SkiaImageManager.CacheBudgetMb`, 128 MB by default), and the images no control shows go first. Cached images
101
+ refresh after 30 minutes or on `RemoveFromCache`, and an image stays on screen as long as a control shows it. The
102
+ image manager follows DrawnUi.Net: `ReuseBitmaps`, `UseCache`, retries of failed loads, `RegisterImage`,
103
+ `IsLoadingLocked`; `LoadImageAsync` is a direct load outside the cache.
104
+ - **Controls on a new canvas:** a control shown on a new canvas redraws its GPU and image caches there.
105
+ - **Changes during a cache recording:** a control that changes while a cached parent records it (shown from another
106
+ control's paint, or from an event raised as it draws) is drawn on the next frame.
107
+ - **Parent-independent controls:** a control marked `IsParentIndependent` lays itself out again in its own slot when its
108
+ content changes, so a live counter in a row shows every new value without laying out the row.
109
+ - **`End` in stacks:** a child with `End` in a row or column sits at the stack's end, as in DrawnUI for Rust (a button
110
+ after a text in a full-width row lines up on the right).
111
+ - **Zoom wheels:** `TouchActionEventArgs.Wheel.IsZoom` tells a Ctrl / Cmd + wheel or a touchpad pinch from a plain wheel.
112
+ - **Add-on packages:** `Registry` and `DrawnProps` let a separate package register its own JSX tags.
113
+ - **`SkiaShell` without React:** the shell is an engine control in `drawnui-react/core`: build it in code with
114
+ controls as pages, popups, modals and toasts. The JSX `<SkiaShell>` works as before on top of it.
115
+ - **Quiet console:** WebGL starts and comes back after a lost context without browser warnings, in Chromium and WebKit.
116
+ - **Dialogs for keyboard and screen readers:** an open dialog reads as one named dialog, the keyboard goes into it
117
+ (also when its buttons show a moment later) and comes back to the control that opened it when it closes, also
118
+ after one dialog hands over to another.
119
+ - **`Super.OpenLink` and `UpdateNonStop()`:** open an address in a new tab, and keep a self-animating control (a
120
+ time-driven shader, a clock) drawing every frame while it is shown, as in DrawnUi .NET.
121
+ - **Layout rules as in DrawnUI for .NET and Rust:** a Fill control with a size request keeps the requested size; a
122
+ layer without a size of its own fits its sized children, and an empty Fill background takes that size; Center with
123
+ unequal margins moves by the full margin difference.
124
+ - **Shader time:** `iTime` counts from the first shader frame, shared by every effect, so animated shaders stay smooth
125
+ however long the page has been open.
126
+ - **Screen readers and opacity:** a control faded to opacity 0 is left out of the screen-reader tree, like a hidden one,
127
+ and is read again when it shows.
128
+ - **Styles with code-behind:** a control built in code keeps every property the code set; a registered style fills in
129
+ only the rest.
130
+ - **Nested scrolls:** a drag that starts on an inner list already at its end scrolls the page around it, so a page full
131
+ of lists drags all the way to its end. The mouse wheel works the same way, as in browsers: one spin stays on the list
132
+ it started on, the next one moves the page.
133
+ - **Paragraph spacing:** text with line breaks gets a quarter line between paragraphs by default (`ParagraphSpacing`
134
+ 0.25), as in DrawnUi .NET, and a growing editor (`AutoHeight`) fits each of its lines at its own height.
135
+ - **Line spacing from the font:** fonts with built-in leading keep it between lines (times `LineSpacing`), and
136
+ `LineHeightUniform` gives every line of a label the tallest line's height.
137
+ - **Text placed as in DrawnUi .NET:** label lines are whole pixels high and text sits on the same baseline as in
138
+ DrawnUi .NET; with `LineHeight` the extra space is shared above and below the text.
139
+ - **Sharp at any display scale:** the canvas matches the screen's device pixels exactly at fractional display scales,
140
+ so text and lines stay crisp.
141
+ - **Moving inside a composite cache:** a control moved by its translation inside an `ImageComposite` layer draws at its
142
+ new place right away.
143
+
144
+ ## What's new in 0.1.0-preview.41
145
+
146
+ - **System light and dark:** `Canvas.SystemTheme` and `SystemThemeChanged` report the browser's light or dark appearance
147
+ at start and on every change.
148
+ - **Designer actions:** `designerAction`, `useDesignerAction` and `<DesignerAction>` name app states the DrawnUI Designer
149
+ can jump to.
150
+ - **Animations never stop each other:** an animation whose code fails is logged once, and the other animations and the
151
+ frame keep going.
152
+ - **Quiet replaced animations:** a fade or move replaced by a new one is silent unless your code waits on it.
153
+
154
+ ## What's new in 0.1.0-preview.40
155
+
156
+ - **Context menus from the keyboard:** the Menu key, Shift+F10 and a screen reader's context-menu command (VoiceOver
157
+ VO+Shift+M) open the context menu of the control in keyboard focus, at its center, from that control or the first one
158
+ above it with a `ContextMenu` handler, then the `Canvas` one; `e.Source` is `"keyboard"`. Controls with a context
159
+ menu are reachable without a mouse.
160
+ - **Editor caret and the window:** a focused `SkiaEditor` keeps its focus while the browser window or tab is inactive,
161
+ its caret hidden and still (no redraws); when the window gets the keyboard back the caret shows again in the same
162
+ field. `Canvas.IsWindowActive` and `Canvas.WindowActiveChanged` tell your own controls the same.
163
+
164
+ ## What's new in 0.1.0-preview.39
165
+
166
+ - **Tap feedback for the primary pointer:** tap and press animations (`AnimationTapped="Ripple"`, `SkiaButton`'s press
167
+ ripple, a tappable span's ripple) play for a finger, a pen or the left mouse button. A right or middle click raises its
168
+ events as before (`Tapped` with `Button` `"Right"`, `ContextMenu`) with no ripple. `SkiaControl.IsPrimaryPointer(args)`
169
+ tells your own controls the same.
170
+
171
+ ## What's new in 0.1.0-preview.38
172
+
173
+ - **SkiaScroll size, as in DrawnUI for .NET and Rust:** a `SkiaScroll` without a `WidthRequest` / `HeightRequest` that
174
+ is not `Fill` on that axis sizes to its content on that axis, up to the space it is given. Set `HorizontalOptions` /
175
+ `VerticalOptions` to `Fill` for a scroll that fills its space (a page scroll, a list).
176
+ - **Multi-touch:** a `Panning` while two or more fingers are down carries `Manipulation`: `Scale` (pinch), `Rotation`
177
+ (turn, in degrees), `Center` / `PreviousCenter`, their totals and the finger count. A press that had a second finger
178
+ down is no tap.
179
+ - **Keys, one order everywhere:** the canvas keyboard navigation (activation, arrows in lists and menus, slider steps,
180
+ Escape closing a popup window) gets each key first, then your `KeyboardManager` handlers run with
181
+ `KeyboardManager.IsKeyHandled` telling whether navigation used it. Skip handled keys so one press does one thing.
182
+ - **Desktop menu bars from the keyboard:** Alt alone puts the keyboard on the bar, the arrows go round the titles and
183
+ the lines, Escape closes one level. New for your own menus: `KeyboardWrap` (the arrows go round a group),
184
+ `canvas.SetAccessibilityFocus(control)` (it wins over the canvas' own focus move of the same frame; `undefined`
185
+ keeps the focus where it is), `canvas.KeyboardFocusNode`, `AccessibilityExpanded`.
186
+ - **Frame players:** `SpeedRatio` is the real speed (0.5 plays at half speed, 2 at double) on `SkiaSprite`, `SkiaGif`
187
+ and `SkiaLottie`. `DefaultFrame` and `CurrentFrame` are frame indexes, -1 is the last frame.
188
+ - **Images:** `Aspect="Tile"` repeats a `SkiaImage` or `SkiaSvg` at its natural size over the whole control, starting
189
+ from the copy its alignment places. `AddEffect="Grayscale"` uses the 0.21 / 0.72 / 0.07 luminance weights;
190
+ `BlackAndWhite` keeps 0.2989 / 0.587 / 0.114.
191
+ - **Gradients:** a gradient's `Light` above 1 multiplies each color's lightness, below 1 its red, green and blue, as in
192
+ DrawnUI for .NET. A `SkiaLabel` with a `BackgroundColor` takes its `FillGradient` on the background and keeps its
193
+ `TextColor`; without one the gradient fills the text.
194
+ - **Drawers:** `AutoClose` closes on a press outside the drawer's content, so a full-screen drawer with a smaller panel
195
+ closes from a press above the panel. A touch that lands on a drawer while it slides lets it finish the slide.
196
+ - **Shell modals:** `ModalsCount`, `CanGoBack` and `Navigated` (Pop) follow a modal the moment its close starts,
197
+ whether by `PopModalAsync`, a swipe or `IsOpen = false`; the modal slides out after that.
198
+ - **Carousels:** a second swipe during a shader carousel's transition raises `Stopped` once, at rest, and a move by
199
+ code takes over a queued swipe. `IsUserFocused` is false after every release, a tap included.
200
+ - **Removed controls:** a control removed from the canvas pauses its animations until it is added back; a disposed
201
+ one stops them. A removed text field lets go of the keyboard, and a `DrawnGame` gets keys while it is on a canvas.
202
+ - **Accessibility:** shell popups and modals read as dialogs, a live region's new text is read on the next frame, and
203
+ a menu or list whose items sit in several layouts is walked in reading order.
204
+ - **Tools:** `Canvas.PopupWindowRoots` lists the open popup windows, `Canvas.WasDrawnListeners` runs handlers after
205
+ every drawn frame, and `DesignerSourceOf(control)` gives the React element that created a control in dev builds.
206
+
25
207
  ## Install
26
208
 
27
209
  ```
28
- npm i drawnui-react@preview react react-dom
210
+ npm i drawnui-react react react-dom
29
211
  ```
30
212
 
31
213
  `drawnui-react` = React tags + every engine type, `drawnui-react/core` = the engine only. Ships ES modules + `.d.ts`;
32
214
  CanvasKit's `.wasm` is referenced with a `?url` import, so use Vite (or any bundler that understands `?url`) and
33
- put your fonts under `public/fonts`. Preview releases carry the `preview` dist-tag (the first publish also became `latest`, as npm always does).
215
+ put your fonts under `public/fonts`. Releases are published with the `latest` dist-tag.
34
216
 
35
217
  ## Run
36
218
 
@@ -65,6 +247,15 @@ accessibility all live in the engine and would work identically under Vue, Svelt
65
247
  That is also why the demo pages describe DrawnUi features, not React ones: the same pages are meant to be reused as
66
248
  the showcase for other frameworks on this engine.
67
249
 
250
+ ## Games
251
+
252
+ `DrawnGame` (from DrawnUi.Gaming) is ported: a layout with a game loop. Subclass it, build your sprites in the
253
+ constructor, call `StartLoop()`, and override `GameLoop(deltaSeconds)` and `OnKeyDown` / `OnKeyUp` (DOM `event.code`
254
+ names). Move sprites with `Left` / `Top` on cached controls, as in C#. The demo's `#/pong` page is the .NET Pong
255
+ sample (`src/Shared/Samples/Pong.Shared`) ported line for line: the game classes are plain TypeScript in
256
+ `samples/demo/pages/pong`, mounted from `PongPage.tsx` with `AddSubView`, and a small `RescalingLayout` fits the
257
+ 360×640 field to any screen by changing the children's rendering scale.
258
+
68
259
  ## Context menu (right click)
69
260
 
70
261
  A right click on the canvas normally opens the browser's own menu ("Save image as…"). Every mouse button goes
@@ -82,18 +273,34 @@ The request is routed like a tap: deepest visible control under the point first
82
273
  parents, then the `Canvas` prop. The first handler returning `true` takes it and the browser menu is suppressed;
83
274
  with no handler the browser menu shows as before. `e` carries `Location` (points on the canvas), `Pixels`, `Local`
84
275
  (pixels inside the handling control), `Source` (`"mouse"`, `"touch"` for a long press, `"keyboard"` for the Menu
85
- key) and `Native` (the DOM event, for modifiers). Web-only: DrawnUi.Net has no mouse buttons.
276
+ key or Shift+F10 on the control in keyboard focus, opened at its center) and `Native` (the DOM event, for modifiers). Web-only: DrawnUi.Net has no mouse buttons.
277
+
278
+ ## Menu bar
279
+
280
+ A desktop menu bar is a row of titles (`Aria.RoleMenuBar`), each opening its menu below it with
281
+ `OpenPopupWindow(canvas, menu, title)`. The demo's menu bar works the way desktop users expect, from the mouse and from
282
+ the keyboard alone: a click opens a menu and the mouse over another title opens that one; Alt alone puts the keyboard
283
+ on the bar and Alt+F opens File; Left / Right go round the titles, Down, Enter or Space open one on its first item; Up /
284
+ Down / Home / End go round its lines, Right / Left move to the next / previous menu, Enter runs the line, Escape closes
285
+ one level and Alt leaves, giving the keyboard back. The keyboard's place shows the selected look in the accent color,
286
+ the hover keeps its lighter look. Screen readers hear menubar, menu and menu item roles, the titles' expanded state
287
+ (`AccessibilityExpanded`) and every line the keys light (`canvas.SetAccessibilityFocus(control)`). Shortcuts (Ctrl+S,
288
+ F1) work with the menus closed too. Code: `samples/demo/pages/MenusPage.tsx`.
86
289
 
87
290
  ## Accessibility
88
291
 
89
- Same model as DrawnUi.Blazor: the `<canvas>` is `aria-hidden`, an invisible DOM overlay mirrors every
90
- accessible drawn control (`role`, `aria-label`, `title` hint, `aria-pressed`, `aria-live`, `tabindex`), rebuilt
91
- at most once per second from the arranged rects. Keyboard (Tab / Enter / Space) and screen-reader activation
92
- are routed back into the gesture pipeline as a `Tapped` on the control.
292
+ Same model as DrawnUI for .NET in the browser: the `<canvas>` is `aria-hidden`, and an invisible ARIA layer mirrors
293
+ every accessible drawn control (role, name, hint, value, pressed state, live regions). Tab, the arrow keys, Home /
294
+ End, PageUp / PageDown, Enter, Space and Escape move through controls, lists, menus and dialogs; screen-reader
295
+ activation reaches the control as a `Tapped`. A dialog marked `AccessibilityModal` (shell popups and modals are by
296
+ themselves) keeps readers and the keyboard inside it, and a live region's new text is read on the next frame.
93
297
 
94
298
  Per control (C# names): `AccessibilityRole` (enables the node; use `Aria.*`), `AccessibilityLabel`
95
299
  (defaults to the control's text), `AccessibilityHint`, `AccessibilityCanInteract` (defaults to "has a
96
- `Tapped` handler"), `AccessibilityIsPressed`, `AccessibilityLive`. `Aria.RolePresentation` hides a control that
300
+ `Tapped` handler"), `AccessibilityIsPressed`, `AccessibilityExpanded`, `AccessibilityLive`, `KeyboardWrap` (the arrows
301
+ go round a group); `canvas.SetAccessibilityFocus(control)` moves the keyboard and screen-reader focus from app code.
302
+ The canvas navigation gets every key first, then `KeyboardManager` subscribers run with `KeyboardManager.IsKeyHandled`
303
+ telling whether navigation used it, so one press does one thing. `Aria.RolePresentation` hides a control that
97
304
  would otherwise get a default role.
98
305
 
99
306
  App-wide opt-in (React extension): `SkiaLabel.DefaultAccessibilityRole = Aria.RoleText` and
@@ -103,13 +310,13 @@ label readable and every button focusable without touching each control.
103
310
  The overlay has `pointer-events: none`, so hover and all pointer gestures still reach the canvas — the
104
311
  Blazor "accessible control loses hover" limitation does not apply.
105
312
 
106
- Text selection (React extension, opt-in): `AccessibilityTextSelectable` on a `SkiaLabel` renders its laid-out lines
107
- as real, invisible DOM text in the overlay — one span per drawn line, in the same font (registered fonts are also
108
- installed as CSS `FontFace`s) and stretched to the drawn line width — with pointer events on. The browser then
109
- selects, copies (Ctrl+C / context menu) and reads it like an HTML paragraph, and the wheel over it still scrolls the
110
- drawn content. It is off by default and must stay off on anything gesture-driven (buttons, carousels, drawers): the
111
- selectable text owns the pointer, so taps and pans under it never reach the drawn control. Everything else in the
112
- overlay is `user-select: none`, so select-all only highlights opted-in text.
313
+ Text selection (opt-in, as DrawnUi.Net): `AccessibilityTextSelectable` on a `SkiaLabel` lets the user select and copy
314
+ its text, drawn by the label in `SkiaLabel.TextSelectionColor`. Mouse: drag (across several labels in reading order, a
315
+ drag held past a scroll's edge scrolls it), double click for a word; Ctrl+C / Cmd+C copies, a click elsewhere clears.
316
+ Touch: a long press selects a word and shows a drawn Copy button; drag to extend. A right click or a long press raises
317
+ the control's `ContextMenu` with the selection kept (`canvas.SelectedText`, `CopyTextSelection()`,
318
+ `ClearTextSelection()`). The label takes the mouse press for this, so keep it off on labels inside gesture-driven
319
+ controls. The overlay stays for screen readers and the keyboard only: nothing in it is ever selected in the DOM.
113
320
 
114
321
  ## Crawlers and AI agents: static HTML from the accessibility tree
115
322