@oh-just-another/react-ui 0.57.3 → 0.58.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @oh-just-another/react-ui
 
+## 0.58.0
+
+### Minor Changes
+
+- b4b252b: Arrange operations for the selection. **Flip** mirrors the selection about its bounding-box centre — horizontal (`Shift+H`) and vertical (`Shift+V`); a single shape flips about its own centre. **Align** flushes two or more shapes to the left / right / top / bottom edge or the horizontal / vertical centre of their bounding box (`Alt+←/→/↑/↓` for the four edges; centres via the panel / menu). **Distribute** evenly spaces three or more shapes so the gaps between them are equal, on the horizontal (`Alt+H`) or vertical (`Alt+V`) axis, keeping the outermost shapes fixed. All three are available from the selection property panel and the right-click menu. New engine API: `Editor.flipSelection(axis)`, `Editor.alignSelection(edge)`, and `Editor.distributeSelection(axis)`.
+- 578e728: Clear the whole canvas with `Cmd/Ctrl+Delete` (or `Backspace`), from the command palette, or the right-click menu. Because it wipes every shape and isn't undoable, it always asks for confirmation first.
+- d20d50a: Copy and paste a shape's visual style. `Cmd/Ctrl+Alt+C` captures the fill / stroke / dash / opacity of the selected shape into an in-editor buffer; `Cmd/Ctrl+Alt+V` applies it to the current selection (one undo step). Also available from the right-click menu. New engine API: `Editor.copySelectionStyle()` / `Editor.pasteSelectionStyle()` and the `hasStyleClipboard` flag.
+- 09a096c: Add `PortalContainerProvider` / `usePortalContainer` — floating UI (tooltips, popovers, context menus, hover chips) now portals into a configurable container instead of always `document.body`. Defaults to `document.body`, so existing usage is unchanged; a host mounting the editor in a shadow root points it at a node inside the root so portaled content stays styled.
+
+### Patch Changes
+
+- 7217cac: The canvas surface no longer draws a focus ring on a mouse click. The surface
+  takes focus on press (so keyboard shortcuts work right after clicking), which
+  made it light up with an outline like a focused text input. The ring is now
+  gated on `:focus-visible`, so it appears only for keyboard focus (Tab) and never
+  for a pointer press.
+- 60e315e: Fix the context menu (and any chrome reading the legacy `--menu-*` / `--panel` /
+  `--text` aliases) ignoring an explicit app theme. The aliases forward to the
+  `--du-*` theme variables via `var()`, but were declared only on `:root` — and a
+  `var()` inside a custom property resolves on the element where it's declared. So
+  under an OS dark preference the alias baked in `:root`'s dark value and inherited
+  that frozen colour straight past a `[data-theme="light"]` override, leaving a
+  dark menu on a light app. The aliases are now declared at every theme scope
+  (`:root`, `[data-theme="light"]`, `[data-theme="dark"]`) so each re-resolves
+  against the scoped `--du-*`.
+- 60e315e: Fix floating chrome ignoring the app theme. The selection / property panel,
+  popovers, tooltips and the right-click context menu portal out of the editor
+  root, which also escaped the `data-theme` set there — so under an OS dark
+  preference they showed a dark surface even when the app was set to light (and
+  vice-versa). They now portal into a wrapper that mirrors the editor's theme, so
+  they always match the app. The context menu additionally portals into that
+  wrapper and its colours forward to the `--du-*` theme variables (no more
+  hard-coded dark fallbacks / hover).
+- Updated dependencies [b4b252b]
+- Updated dependencies [1c7cc6c]
+- Updated dependencies [d20d50a]
+- Updated dependencies [0152ed6]
+- Updated dependencies [938e7c8]
+- Updated dependencies [9673846]
+- Updated dependencies [f370dba]
+- Updated dependencies [1c7cc6c]
+- Updated dependencies [e1fd495]
+- Updated dependencies [8f00738]
+- Updated dependencies [1c7cc6c]
+- Updated dependencies [ff90a95]
+- Updated dependencies [da91d59]
+- Updated dependencies [3152317]
+- Updated dependencies [fc47ecc]
+- Updated dependencies [8fc6b69]
+- Updated dependencies [f98730f]
+- Updated dependencies [904cc09]
+- Updated dependencies [edde5d0]
+- Updated dependencies [1c7cc6c]
+- Updated dependencies [c5be6e5]
+  - @oh-just-another/state@0.59.0
+  - @oh-just-another/renderer-canvas@0.59.0
+  - @oh-just-another/scene@0.59.0
+  - @oh-just-another/renderer-core@0.58.0
+  - @oh-just-another/math@0.58.0
+  - @oh-just-another/renderer-svg@0.57.2
+  - @oh-just-another/templates@0.57.2
+  - @oh-just-another/versioning@0.57.2
+
 ## 0.57.3
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,8 @@
 
 React 18+ wrappers around the editor — `DiagramCanvas`, `Toolbar`, `Palette`, `PropertyPanel`, plus a small set of hooks. Mount it with three lines of JSX, customize with hooks for everything else.
 
+The React binding layer (L5) over `@oh-just-another/state`; needs React + DOM. For a single drop-in component, use `@oh-just-another/editor`.
+
 ## Install
 
 ```bash
@@ -30,25 +32,123 @@ export const App = () => (
 
 `DiagramCanvas` constructs the underlying `Editor` and supplies it to every descendant via context. Toolbar / Palette / PropertyPanel are independent — drop them anywhere in the subtree, layered with normal CSS.
 
-## API
+## Components
+
+Every component reads the editor from context, so most take no required props.
+
+### Mounting & layout
+
+| Name                             | Purpose                                                          |
+| -------------------------------- | ---------------------------------------------------------------- |
+| `DiagramCanvas`                  | Mounts a host element, instantiates `Editor`, provides context.  |
+| `DiagramRoot` / `DiagramSurface` | Lower-level split of the canvas: provider root + render surface. |
+| `DiagramProvider`                | Standalone provider for hosts that build their own editor.       |
+| `UILayer`                        | Positioned overlay layer for placing chrome over the canvas.     |
+| `TopBar` / `BottomBar`           | Edge-anchored bars for toolbars and status chrome.               |
+| `Sidebar`                        | Collapsible side container for panels.                           |
+| `BottomSheet`                    | Sliding bottom container (touch / mobile layouts).               |
+
+### Toolbar & zoom
+
+| Name                                                                                     | Purpose                                                                          |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `Toolbar` / `DEFAULT_TOOLBAR` / `DEFAULT_VERTICAL_TOOLBAR`                               | Declarative tool/action bar. Items: `mode`, `action`, `divider`, `undo`, `redo`. |
+| `openImageFilePicker`                                                                    | Opens the OS file picker and inserts the chosen image.                           |
+| `ZoomWidget` / `FloatingZoomControls`                                                    | Composite zoom controls.                                                         |
+| `ZoomInButton` / `ZoomOutButton` / `ResetZoomButton` / `ZoomToFitButton` / `ZoomDisplay` | Individual zoom controls.                                                        |
+| `ResetToContentButton`                                                                   | Recenters the viewport on scene content.                                         |
+
+### Palettes & shape catalog
+
+| Name                                                                                              | Purpose                                            |
+| ------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `Palette`                                                                                         | Drag-and-drop catalog of templates.                |
+| `LibraryPanel`                                                                                    | Browsable template library panel.                  |
+| `ColorSwatchPicker`                                                                               | Color swatch grid picker.                          |
+| `ELEMENT_PALETTE_LIGHT` / `ELEMENT_PALETTE_DARK` / `CANVAS_PALETTE_LIGHT` / `CANVAS_PALETTE_DARK` | Built-in color palettes.                           |
+| `resolvePaletteTheme`                                                                             | Picks the light/dark palette for the active theme. |
+
+### Inspectors & property panels
+
+| Name                     | Purpose                                      |
+| ------------------------ | -------------------------------------------- |
+| `PropertyPanel`          | Inspector for the current selection.         |
+| `LinkStylePanel`         | Edge/link styling controls.                  |
+| `LayerPanel`             | Layer list with visibility / ordering.       |
+| `FramePanel`             | Frame list and controls.                     |
+| `SelectionFloatingPanel` | Floating controls anchored to the selection. |
+
+### Menus, dialogs & overlays
+
+| Name                                   | Purpose                                            |
+| -------------------------------------- | -------------------------------------------------- |
+| `MainMenu`                             | Top-level application menu with submenus.          |
+| `ContextMenu` / `DEFAULT_CONTEXT_MENU` | Right-click menu over the canvas.                  |
+| `CommandPalette`                       | Searchable command launcher.                       |
+| `Modal` / `Popover`                    | Generic modal dialog and anchored popover.         |
+| `Tooltip` / `TooltipProvider`          | Hover tooltips (wrap the subtree in the provider). |
+| `HelpButton` / `HelpDialog`            | Keyboard-shortcut / help dialog and its trigger.   |
+| `ToastHost`                            | Renders transient toasts; pair with `useToast`.    |
+
+### Collaboration & versioning
+
+| Name                                | Purpose                                   |
+| ----------------------------------- | ----------------------------------------- |
+| `CommentsPanel` / `CommentsPopover` | Thread list and anchored comment popover. |
+| `VersionPanel`                      | Snapshot history browser.                 |
+| `MergeDialog`                       | Resolve conflicts when merging versions.  |
+| `DiffPanel`                         | Visual diff between two scenes.           |
+
+### Editing overlays
+
+| Name                                                         | Purpose                                |
+| ------------------------------------------------------------ | -------------------------------------- |
+| `TextEditorOverlay` / `FrameNameEditorOverlay`               | In-place text editors over the canvas. |
+| `LinkHoverPopup` / `LinkDropShapeMenu` / `LinkCaptionEditor` | Link interaction overlays.             |
+| `Markdown`                                                   | Renders markdown (comments, captions). |
+
+### Primitives
+
+| Name                          | Purpose                            |
+| ----------------------------- | ---------------------------------- |
+| `IconButton` / `ButtonGroup`  | Buttons and grouped button rows.   |
+| `SegmentedControl` / `Slider` | Segmented toggle and range slider. |
+
+## Hooks
+
+| Name                                                                     | Purpose                                                        |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| `useDiagram()` / `useDiagramOptional()`                                  | Live `Editor` (imperative; no re-render on change).            |
+| `useDiagramContext()` / `useDiagramContextOptional()`                    | Raw context value.                                             |
+| `useEditorSelector(select)`                                              | Custom selector — re-renders when the projected value changes. |
+| `useScene()` / `useSelection()` / `useMode()`                            | Reactive slices of editor state.                               |
+| `useHistory()`                                                           | `canUndo` / `canRedo` + `undo` / `redo`.                       |
+| `useLayers()` / `useActiveLayerId()`                                     | Layer list and active layer.                                   |
+| `useAnnotations()` / `useSelectedAnnotation()` / `useSelectedLink()`     | Annotation and link selection state.                           |
+| `useMobileLayout()`                                                      | Whether the compact / touch layout is active.                  |
+| `useToast()` / `useToastOptional()` / `useEphemeralToast()`              | Toast API (pair with `ToastHost`).                             |
+| `useSnapshotStore()`                                                     | Snapshot store backing `VersionPanel`.                         |
+| `useHelpDialogHotkey()`                                                  | Wires the help-dialog hotkey.                                  |
+| `useContextMenuController()` / `ContextMenuControllerProvider`           | Imperative control of `ContextMenu`.                           |
+| `usePaletteDropHandler()` / `usePalettePlacement()` / `usePaletteDrag()` | Palette drop / placement / drag wiring.                        |
+| `getActivePaletteDrag()` / `subscribePaletteDrag()`                      | Read/observe the active palette drag outside React.            |
+
+## Layout constants
+
+Tunable sizes for the built-in panels and toolbar:
+`PALETTE_WIDTH`, `PALETTE_ITEM_SIZE`, `PROPERTY_PANEL_WIDTH`, `PROPERTY_SWATCH_SIZE`,
+`LAYER_PANEL_WIDTH`, `LAYER_TOGGLE_ICON_SIZE`, `LAYER_SWATCH_SIZE`,
+`COMMENTS_PANEL_WIDTH`, `TOOLBAR_SEPARATOR_HEIGHT`.
 
-| Name                                                           | Purpose                                                                                   |
-| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `DiagramCanvas` / `DiagramCanvasProps`                         | Mounts a host element, instantiates `Editor`, wraps children in `DiagramProvider`.        |
-| `DiagramProvider` (+ `useDiagramContext`)                      | Standalone provider for advanced hosts that build their own editor.                       |
-| `useDiagram()`                                                 | Live `Editor`. Imperative access (no re-render on change).                                |
-| `useScene()` / `useSelection()` / `useMode()` / `useHistory()` | Reactive slices. `useHistory` exposes `canUndo` / `canRedo` + `undo` / `redo`.            |
-| `useEditorSelector(select)`                                    | Build your own selector — re-renders when the projected value changes.                    |
-| `Toolbar` / `DEFAULT_TOOLBAR` / `ToolbarItem`                  | Items: `mode`, `action`, `divider`, `undo`, `redo`. Action items receive the live editor. |
-| `Palette` / `PaletteProps`                                     | Drag-and-drop catalog of templates. Defaults to `defaultRegistry`.                        |
-| `usePaletteDropHandler()`                                      | Convert an HTML5 drop event on any element into `editor.addShape(template.factory(...))`. |
-| `PropertyPanel` / `PropertyPanelProps`                         | Read-only inspector for the current selection.                                            |
+Each component also exports its `*Props` type (e.g. `ToolbarProps`, `PaletteProps`); menu, toast,
+help, and context-menu modules additionally export their item/section types (`ToolbarItem`,
+`ContextMenuItem`, `ToastKind`, `HelpRow`, etc.).
 
 ## Design notes
 
 - **`<DiagramCanvas>` owns the editor's lifetime.** Created in `useLayoutEffect` so children's effects see the provider value on first paint; disposed on unmount. `initialScene` and `initialMode` are read once — runtime updates go through the editor API (`editor.loadScene`, `editor.setMode`).
-- **Hooks subscribe via the editor's `subscribe`.** Mode changes were previously not announced; `Editor.setMode` now calls `notify()` so `useMode` (and similar bespoke selectors) re-render correctly.
+- **Hooks subscribe via the editor's `subscribe`.** `Editor.setMode` calls `notify()` so `useMode` (and similar bespoke selectors) re-render on mode changes.
 - **No global state.** Every editor instance is independent — composition via context lets multiple canvases live on the same page (useful for diff viewers, presentation modes).
 - **Toolbar item kinds are a discriminated union.** Hosts can mix builtin `mode` / `undo` / `redo` items with arbitrary `action` items in one declarative array.
-- **Palette uses SVG icons through `dangerouslySetInnerHTML`.** Template authors define the icon markup; same SVG goes through the canvas renderer's SVG-parser (Phase 6b). No cross-package surprises.
+- **Palette uses SVG icons through `dangerouslySetInnerHTML`.** Template authors define the icon markup; the same SVG goes through the canvas renderer's SVG parser, so palette and canvas stay visually identical.
 - **Tests run under `jsdom`.** `tests/setup.ts` stubs `HTMLCanvasElement.prototype.getContext`, pointer-capture, and `ResizeObserver` — enough for the editor to mount without pulling the native `canvas` npm package.