tldraw 5.6.0 → 5.7.0-next.433c23fa9ce6

package/DOCS.md

@@ -1,6 +1,6 @@
 # tldraw Documentation
 
-Version: `5.6.0`
+Version: `5.7.0-next.433c23fa9ce6`
 
 This file is generated during package publishing from the tldraw docs content for this exact package version.
 
@@ -4482,19 +4482,19 @@ Keyboard shortcuts are bound automatically. The `useKeyboardShortcuts` hook pars
 
 The `TLUiActionItem` interface defines what an action contains:
 
-| Property               | Description                                                                                                                                                   |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`                   | Unique identifier for the action (e.g., `'duplicate'`, `'zoom-in'`)                                                                                           |
-| `label`                | Translation key for display text. Can be a string or an object mapping contexts to different keys (see [Context-sensitive labels](#context-sensitive-labels)) |
-| `icon`                 | Icon name from tldraw's icon set, or a custom React element                                                                                                   |
-| `kbd`                  | Keyboard shortcut string. Use commas to bind several combinations, e.g. `'cmd+g,ctrl+g'` (see [Keyboard shortcuts](#keyboard-shortcuts))                      |
-| `readonlyOk`           | When `true`, the action works in readonly mode. Defaults to `false`                                                                                           |
-| `checkbox`             | When `true`, renders as a toggle with a checkmark indicator in menus                                                                                          |
-| `isRequiredA11yAction` | When `true`, the keyboard shortcut works even when shortcuts are normally disabled (e.g., while editing a shape). Used for accessibility actions              |
-| `isAvailable`          | Optional `(editor) => boolean`. When it returns `false`, menus hide the action (see [Enabling and checking actions](#enabling-and-checking-actions))          |
-| `isEnabled`            | Optional `(editor) => boolean`. When it returns `false`, menus disable or hide the action                                                                     |
-| `isChecked`            | Optional `(editor) => boolean`. For checkbox actions, whether the item shows as checked                                                                       |
-| `onSelect`             | Handler called when the action is triggered. Receives a `TLUiEventSource` indicating the trigger origin (`'kbd'`, `'menu'`, `'toolbar'`, etc.)             |
+| Property               | Description                                                                                                                                                                      |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                   | Unique identifier for the action (e.g., `'duplicate'`, `'zoom-in'`)                                                                                                              |
+| `label`                | Translation key for display text. Can be a string or an object mapping contexts to different keys (see [Context-sensitive labels](#context-sensitive-labels))                    |
+| `icon`                 | Icon name from tldraw's icon set, or a custom React element                                                                                                                      |
+| `kbd`                  | Keyboard shortcut string. Use commas to bind several combinations, e.g. `'cmd+g,ctrl+g'` (see [Keyboard shortcuts](#keyboard-shortcuts))                                         |
+| `readonlyOk`           | When `true`, the action runs in readonly mode; otherwise it doesn't run, however it's triggered. Defaults to `false`                                                             |
+| `checkbox`             | When `true`, renders as a toggle with a checkmark indicator in menus                                                                                                             |
+| `isRequiredA11yAction` | When `true`, the keyboard shortcut works even when shortcuts are normally disabled (e.g., while editing a shape). Used for accessibility actions                                 |
+| `isAvailable`          | Optional `(editor) => boolean`. When it returns `false`, menus hide the action, and the action doesn't run (see [Enabling and checking actions](#enabling-and-checking-actions)) |
+| `isEnabled`            | Optional `(editor) => boolean`. When it returns `false`, menus disable or hide the action, and the action doesn't run                                                            |
+| `isChecked`            | Optional `(editor) => boolean`. For checkbox actions, whether the item shows as checked                                                                                          |
+| `onSelect`             | Handler called when the action is triggered. Receives a `TLUiEventSource` indicating the trigger origin (`'kbd'`, `'menu'`, `'toolbar'`, etc.)                                |
 
 #### Accessing actions
 
@@ -4523,13 +4523,14 @@ The default actions cover most editing operations you'd expect in a canvas appli
 | Category    | Action ids                                                                                                                                                                 |
 | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Editing     | `undo`, `redo`, `duplicate`, `delete`, `copy`, `cut`, `paste`                                                                                                              |
-| Grouping    | `group`, `ungroup`                                                                                                                                                         |
+| Grouping    | `group`, `ungroup`, `toggle-group`                                                                                                                                         |
+| Frames      | `frame-selection`, `remove-frame`, `toggle-frame`, `fit-frame-to-content`                                                                                                  |
 | Arrangement | `bring-to-front`, `bring-forward`, `send-backward`, `send-to-back`, `align-left`, `align-center-horizontal`, `align-right`, `distribute-horizontal`, `distribute-vertical` |
 | Export      | `export-as-svg`, `export-as-png`, `copy-as-svg`, `copy-as-png`                                                                                                             |
 | Zoom        | `zoom-in`, `zoom-out`, `zoom-to-100`, `zoom-to-fit`, `zoom-to-selection`, `select-zoom-tool`                                                                               |
 | Preferences | `toggle-dark-mode`, `toggle-snap-mode`, `toggle-grid`, `toggle-focus-mode`                                                                                                 |
 
-The full list is in the [default actions source](https://github.com/tldraw/tldraw/blob/main/packages/tldraw/src/lib/ui/context/actions.tsx). Most actions guard themselves inside their handlers. For example, `group` and the arrangement actions do nothing unless shapes are selected and the select tool is active.
+The full list is in the [default actions source](https://github.com/tldraw/tldraw/blob/main/packages/tldraw/src/lib/ui/context/actions.tsx). An action doesn't run when its `isAvailable` or `isEnabled` returns false, or when the editor is readonly and it isn't `readonlyOk`, including when you call `onSelect` on an action from `useActions()`. For example, `group` does nothing unless two or more unlocked shapes are selected in the select tool.
 
 #### Overriding actions
 
@@ -4555,7 +4556,9 @@ function App() {
 }
 ```
 
-The `copy`, `cut`, and `paste` shortcuts are handled by native clipboard events rather than the `kbd` system, so changing their `kbd` has no effect.
+The `copy`, `cut`, and `paste` shortcuts are handled by native clipboard events rather than the `kbd` system, so changing their `kbd` or `isEnabled` has no effect on them.
+
+Cmd+G and Cmd+Alt+G belong to `toggle-group` and `toggle-frame`, which run `group` or `ungroup`, and `frame-selection` or `remove-frame`, depending on the selection. To change or remove those shortcuts, override the toggle actions, not `group` or `frame-selection`.
 
 ##### Modifying behavior
 
@@ -4581,7 +4584,7 @@ You can call the original handler before or after your custom logic, or replace
 
 ##### Adding custom actions
 
-Add new actions by inserting them into the actions record:
+Add new actions by inserting them into the actions record. The `actions` map passed to `overrides` isn't gated yet, so calling a built-in's `onSelect` on it from inside a custom action skips the readonly check, `isAvailable` and `isEnabled`. Before you call it, check `editor.getIsReadonly()` (unless it's `readonlyOk`) and whichever of `isAvailable` and `isEnabled` it defines. Actions you get from `useActions()` in component code are gated.
 
 ```typescript
 const overrides: TLUiOverrides = {
@@ -4720,7 +4723,7 @@ actions['make-red'] = {
 }
 ```
 
-Keyboard shortcuts ignore `isAvailable` and `isEnabled`, so `onSelect` should still check its own preconditions.
+Menus, keyboard shortcuts and `onSelect` calls on actions from `useActions()` all respect `isEnabled`, so `onSelect` doesn't need to check it again. The gate comes from the action as `overrides` returned it, so changing `isEnabled` on a copy of an action from `useActions()` doesn't change when it runs; override it instead. The exception is the copy, cut and paste shortcuts: they come from native clipboard events, which don't check the action's `isEnabled`.
 
 When you change a built-in action, spread the original so it keeps its `isAvailable`, `isEnabled` and `isChecked`:
 
@@ -4728,7 +4731,7 @@ When you change a built-in action, spread the original so it keeps its `isAvaila
 actions['group'] = { ...actions['group'], onSelect: myGroup }
 ```
 
-Replacing an action with a new object drops them: menus show it as always enabled, and a checkbox item for it always shows as unchecked.
+Replacing an action with a new object drops them, along with `readonlyOk`: menus show it as always enabled, a checkbox item for it always shows as unchecked, shortcuts and `onSelect` calls run it whatever the selection, and if the built-in was `readonlyOk`, it stops running while the editor is readonly.
 
 Use `isAvailable` instead when the action doesn't exist in the current context at all, rather than being blocked right now. Every menu item hides an unavailable action, whatever `whenDisabled` says; only the keyboard shortcuts dialog still lists it. The built-in paste (without clipboard read access), copy as PNG (without clipboard write access), copy as JSON (outside debug mode), cursor chat (on touch), exit pen mode, stop following, and back to content work this way.
 
@@ -10947,7 +10950,7 @@ editor.createShape({
 
 #### Creating frames
 
-You can create a frame programmatically with `Editor#createShape`, or interactively with the frame tool. The frame tool ships in the default toolbar; users can also press `F` to switch to it. The **Frame selection** action (`Cmd/Ctrl+Alt+G`) wraps the current selection in a new frame.
+You can create a frame programmatically with `Editor#createShape`, or interactively with the frame tool. The frame tool ships in the default toolbar; users can also press `F` to switch to it. The **Frame selection** action wraps the current selection in a new frame. `Cmd/Ctrl+Alt+G` runs the `toggle-frame` action: it frames the selection, or removes the frame if only frames are selected. Override `toggle-frame` to rebind it.
 
 When the user drags a frame around existing shapes, the frame tool reparents any sibling shapes that fall fully inside the frame's bounds. Locked shapes are skipped. This is what makes "draw a frame around the things I want to group" work as a single gesture.
 
@@ -11030,7 +11033,7 @@ import { removeFrame } from 'tldraw'
 removeFrame(editor, [frameId])
 ```
 
-The **Remove frame** and **Fit frame to content** actions in the main menu and the context menu's Edit submenu call these helpers when a frame is selected. **Frame selection** (`Cmd/Ctrl+Alt+G`) also removes frames when every selected shape is a frame.
+The **Remove frame** and **Fit frame to content** actions in the main menu and the context menu's Edit submenu call these helpers when a frame is selected. **Remove frame** (`remove-frame`) has its own shortcut, `Cmd/Ctrl+Alt+Shift+G`.
 
 #### Exporting frames
 
@@ -11934,7 +11937,7 @@ editor.groupShapes([shapeId1, shapeId2], {
 })
 ```
 
-Grouping requires at least two shapes. The method does nothing if you pass fewer, and it skips [locked shapes](https://tldraw.dev/sdk-features/locked-shapes). Users can also group shapes with Ctrl+G (Cmd+G on Mac); when the only selected shape is a group, the same shortcut ungroups it.
+Grouping requires at least two shapes. The method does nothing if you pass fewer, and it skips [locked shapes](https://tldraw.dev/sdk-features/locked-shapes). Users can also group shapes with Ctrl+G (Cmd+G on Mac). Pressing the shortcut again with the resulting group selected ungroups it. The shortcut belongs to the `toggle-group` action, so override that action to rebind it.
 
 The new group is positioned at the top-left of the combined bounds of all grouped shapes. It takes the z-index of the topmost grouped shape, so it sits where that shape was in its parent's layer stack.
 
@@ -16976,6 +16979,8 @@ editor.flipShapes([box1, box2], 'vertical')
 
 When flipping groups, the editor includes all children of the group so the whole hierarchy flips together. Shapes can opt out of flipping by returning `false` from `ShapeUtil#canBeLaidOut`; arrows do this when the shape they're bound to isn't part of the flip.
 
+The default UI only offers flip for a single selected shape when `ShapeUtil#canFlip` returns `true`, meaning flipping changes the shape itself by mirroring it or toggling its stored flip. `Editor#flipShapes` doesn't check it. It defaults to `false`; the built-in group, image, arrow, line, draw, highlight and geo shapes return `true`. Override it in your shape util if your shape changes when flipped. Shapes that return `false` still move with the rest of a multi-shape flip.
+
 ##### Rotation
 
 `Editor#rotateShapesBy` rotates shapes by a delta in radians around a common center point. The editor calculates the center of all the shapes' rotated bounds, then rotates each shape around that point and around its own origin: shapes orbit the selection center while also rotating individually. Pass `{ center }` to rotate around a different point.

package/RELEASE_NOTES.md

@@ -1,43 +1,9 @@
 # Releases
 
-Version: `5.6.0`
+Version: `5.7.0-next.433c23fa9ce6`
 
 This file is generated during package publishing from the tldraw release notes content for this exact package version.
 
-## v5.6.0
-
-So far this release adds a `ThrottledFunction` type to `@tldraw/utils`, thins the hinted shape outline, and fixes bugs in resizing, page duplication, local persistence, the store, and sync.
-
-### API changes
-
-- Add a `ThrottledFunction<T>` type to `@tldraw/utils` for annotating the result of `throttle`. `throttle` now returns this type, with the same runtime behavior. ([#10927](https://github.com/tldraw/tldraw/pull/10927))
-- Add `isAvailable(editor)`, `isEnabled(editor)` and `isChecked(editor)` to actions. Menu items built with `TldrawUiMenuActionItem` and `TldrawUiMenuActionCheckboxItem` read them: an unavailable action is hidden, a disabled one is greyed out or hidden depending on `whenDisabled: 'hide' | 'disable'`. `useSomeActionsEnabled` returns whether any of the given actions is available and enabled, so a submenu can hide when none of its items can run. If you replace a built-in action with a new object instead of spreading it, it loses its gating, and a toggle's checkbox always shows as unchecked. ([#11038](https://github.com/tldraw/tldraw/pull/11038))
-- `TldrawUiMenuActionItem` now disables itself when its action's `isEnabled` returns false, so custom menus that render built-in actions grey them out when they can't run. The public menu item wrappers, such as `GroupMenuItem`, `FrameSelectionMenuItem` and `ArrangeMenuSubmenu`, now also hide outside the select tool, where their actions do nothing. ([#11038](https://github.com/tldraw/tldraw/pull/11038))
-
-### Improvements
-
-- Menus no longer offer actions that would do nothing: grouping locked shapes, flipping a locked shape, unlocking when nothing is locked, exporting all shapes on an empty page, moving to a new page at the page limit, and grouping an arrow away from a shape it's bound to. The main menu hides Paste, instead of disabling it, in browsers that can't read the clipboard. ([#11038](https://github.com/tldraw/tldraw/pull/11038))
-- Draw the hinted outline around shapes, such as a frame you're dragging a shape into, at 2px instead of 2.5px. ([#10952](https://github.com/tldraw/tldraw/pull/10952))
-- Speed up `store.query.index()` and `store.query.ids()` updates by no longer allocating for each change. ([#10228](https://github.com/tldraw/tldraw/pull/10228))
-
-### Bug fixes
-
-- Fix the edge scrolling preference showing as off when edge scrolling is on at a speed other than 1, such as 0.5 or 2. ([#11038](https://github.com/tldraw/tldraw/pull/11038))
-- Fix three resize issues: flipping a rotated selection gave its children the wrong rotation, shapes not aligned with the selection received `onResizeStart` and `onResizeEnd` more than once, and `resizeBox` slid the fixed edge when a shape hit its `maxWidth` or `maxHeight`. ([#10351](https://github.com/tldraw/tldraw/pull/10351))
-- Fix duplicating a page moving its shapes when they were off screen, and starting the new page with the current page's camera instead of the duplicated page's. ([#10465](https://github.com/tldraw/tldraw/pull/10465))
-- Fix the arrow tool's precise mode carrying over when you move to a different target shape. ([#10244](https://github.com/tldraw/tldraw/pull/10244))
-- Fix holding Cmd/Ctrl+Shift+Arrow switching from selecting a parent or child to selecting the adjacent shape once the key starts repeating. ([#10184](https://github.com/tldraw/tldraw/pull/10184))
-- Fix `editor.setCursor` throwing for the rotate and resize cursor types, and hex cursor colors breaking SVG cursors. ([#10350](https://github.com/tldraw/tldraw/pull/10350))
-- Fix edits being lost when an editor remounts with the same `persistenceKey` while the previous one is still saving. ([#10752](https://github.com/tldraw/tldraw/pull/10752))
-- Fix store changes made in the last frame before a listener is removed never reaching that listener. ([#10802](https://github.com/tldraw/tldraw/pull/10802))
-- Fix a reaction that writes to the store re-running on every unrelated store change. ([#10236](https://github.com/tldraw/tldraw/pull/10236))
-- Fix undo restoring an in-between state after a single `put` updated the same record twice. ([#10203](https://github.com/tldraw/tldraw/pull/10203))
-- Fix `migrateStoreSnapshot` throwing on a malformed persisted schema instead of returning a migration error. ([#10220](https://github.com/tldraw/tldraw/pull/10220))
-- Fix migrations rerunning on records when a persisted schema's sequence version isn't a number. ([#10917](https://github.com/tldraw/tldraw/pull/10917))
-- Fix a resumed sync session on a hibernating host skipping the version checks made on first connect, so after a server redeploy a client could be sent changes its schema couldn't handle. It's now rejected with `SERVER_TOO_OLD` or `CLIENT_TOO_OLD`, as on connect. ([#10122](https://github.com/tldraw/tldraw/pull/10122))
-- Fix a record field set to `undefined` getting the sync session kicked with `INVALID_RECORD`, and ignore `__proto__` keys in incoming changes. ([#10118](https://github.com/tldraw/tldraw/pull/10118))
-- Fix older sync clients (protocol version 7) silently falling out of sync when the server sent them text-append changes they don't support. ([#10095](https://github.com/tldraw/tldraw/pull/10095))
-
 ## v5.5.0
 
 [View on GitHub](https://github.com/tldraw/tldraw/releases/tag/v5.5.0)

package/dist-cjs/index.d.ts

@@ -432,6 +432,7 @@ export declare class ArrowShapeUtil extends ShapeUtil<TLArrowShape> {
     } & Partial<Omit<TLArrowShape, "id" | "meta" | "props" | "type">>) | undefined;
     onTranslate(initialShape: TLArrowShape, shape: TLArrowShape): void;
     private readonly _resizeInitialBindings;
+    canFlip(): boolean;
     onResize(shape: TLArrowShape, info: TLResizeInfo<TLArrowShape>): {
         props: {
             bend: number;
@@ -1685,6 +1686,7 @@ export declare class DrawShapeUtil extends ShapeUtil<TLDrawShape> {
     getIndicatorPath(shape: TLDrawShape): Path2D;
     toSvg(shape: TLDrawShape, ctx: SvgExportContext): JSX.Element;
     getCanvasSvgDefs(): TLShapeUtilCanvasSvgDef[];
+    canFlip(): boolean;
     onResize(shape: TLDrawShape, info: TLResizeInfo<TLDrawShape>): {
         props: {
             scaleX: number;
@@ -2304,6 +2306,7 @@ export declare class GeoShapeUtil extends BaseBoxShapeUtil<TLGeoShape> {
     getIndicatorPath(shape: TLGeoShape): Path2D | undefined;
     toSvg(shape: TLGeoShape, ctx: SvgExportContext): JSX.Element;
     getCanvasSvgDefs(): TLShapeUtilCanvasSvgDef[];
+    canFlip(): boolean;
     onResize(shape: TLGeoShape, { handle, newPoint, scaleX, scaleY, initialShape }: TLResizeInfo<TLGeoShape>): {
         props: {
             flipX: boolean;
@@ -2779,6 +2782,7 @@ export declare class HighlightShapeUtil extends ShapeUtil<TLHighlightShape> {
     getIndicatorPath(shape: TLHighlightShape): Path2D;
     toSvg(shape: TLHighlightShape, ctx: SvgExportContext): JSX.Element;
     toBackgroundSvg(shape: TLHighlightShape, ctx: SvgExportContext): JSX.Element;
+    canFlip(): boolean;
     onResize(shape: TLHighlightShape, info: TLResizeInfo<TLHighlightShape>): {
         props: {
             scaleX: number;
@@ -2844,6 +2848,7 @@ export declare class ImageShapeUtil extends BaseBoxShapeUtil<TLImageShape> {
     createShapeForAsset(asset: TLAsset, position: VecModel): null | TLShapePartial;
     getGeometry(shape: TLImageShape): Geometry2d;
     getAriaDescriptor(shape: TLImageShape): string;
+    canFlip(): boolean;
     onResize(shape: TLImageShape, info: TLResizeInfo<TLImageShape>): TLImageShape;
     component(shape: TLImageShape): JSX.Element;
     getIndicatorPath(shape: TLImageShape): Path2D | undefined;
@@ -2923,6 +2928,7 @@ export declare class LineShapeUtil extends ShapeUtil<TLLineShape> {
     getDefaultProps(): TLLineShape['props'];
     getGeometry(shape: TLLineShape): PathBuilderGeometry2d;
     getHandles(shape: TLLineShape): TLHandle[];
+    canFlip(): boolean;
     onResize(shape: TLLineShape, info: TLResizeInfo<TLLineShape>): {
         props: {
             points: {
@@ -4932,19 +4938,21 @@ export declare interface TLUiActionItem<TransationKey extends string = string, I
     label?: {
         [key: string]: TransationKey;
     } | TransationKey;
+    /** When `true`, the action runs while the editor is readonly. Defaults to `false`. */
     readonlyOk?: boolean;
     checkbox?: boolean;
     isRequiredA11yAction?: boolean;
     /**
      * Whether the action exists in the current context at all, e.g. clipboard support or debug
-     * mode. Menus hide the item when it returns false (the keyboard shortcuts dialog still lists
-     * it); keyboard shortcuts ignore it. Must be pure and read only editor state.
+     * mode. When false, menus hide the item (the keyboard shortcuts dialog still lists it) and the
+     * action doesn't run from a menu, a shortcut or `useActions()`. Must be pure and read only
+     * editor state.
      */
     isAvailable?(editor: Editor): boolean;
     /**
-     * Whether the action can run now. Menus disable or hide the item when it returns false;
-     * keyboard shortcuts ignore it. Must be pure and read only editor state: menus re-run it when
-     * that state changes, so anything else it reads goes stale.
+     * Whether the action can run now. When false, menus disable or hide the item and the action
+     * doesn't run from a menu, a shortcut or `useActions()`. Must be pure and read only editor
+     * state: menus re-run it when that state changes, so anything else it reads goes stale.
      */
     isEnabled?(editor: Editor): boolean;
     /** For checkbox actions: whether the item shows as checked. Must be pure and read only editor state. */
@@ -5635,6 +5643,10 @@ export declare type TLUiOverrideHelpers = ReturnType<typeof useDefaultHelpers>;
 
 /** @public */
 export declare interface TLUiOverrides {
+    /**
+     * The `actions` passed in aren't gated yet: calling one's `onSelect` here skips the readonly
+     * check, `isAvailable` and `isEnabled`.
+     */
     actions?(editor: Editor, actions: TLUiActionsContextType, helpers: TLUiOverrideHelpers): TLUiActionsContextType;
     tools?(editor: Editor, tools: TLUiToolsContextType, helpers: TLUiOverrideHelpers): TLUiToolsContextType;
     translations?: TLUiTranslationProviderProps['overrides'];

package/dist-cjs/index.js

@@ -671,7 +671,7 @@ var import_buildFromV1Document = require("./lib/utils/tldr/buildFromV1Document")
 var import_file = require("./lib/utils/tldr/file");
 (0, import_editor.registerTldrawLibraryVersion)(
   "tldraw",
-  "5.6.0",
+  "5.7.0-next.433c23fa9ce6",
   "cjs"
 );
 //# sourceMappingURL=index.js.map

package/dist-cjs/lib/shapes/arrow/ArrowShapeUtil.js

@@ -512,6 +512,9 @@ class ArrowShapeUtil extends import_editor.ShapeUtil {
     }
   }
   _resizeInitialBindings = new import_editor.WeakCache();
+  canFlip() {
+    return true;
+  }
   onResize(shape, info) {
     const { scaleX, scaleY } = info;
     const bindings = this._resizeInitialBindings.get(