@cratis/components 3.6.1 → 4.0.0

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,35 @@
+# Third-party notices
+
+`@cratis/components` includes or redistributes the following third-party assets in its published artifact.
+
+## Allotment structural stylesheet
+
+MIT License
+
+Copyright (c) 2021 - present John Walley
+
+Copyright (c) 2021 - present Gobalsky Labs Ltd.
+
+Copyright (c) 2015 - present Microsoft Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## Tailwind CSS generated theme and utility output
+
+MIT License
+
+Copyright (c) Tailwind Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## Patrick Hand font
+
+Canvas Note includes Patrick Hand under the SIL Open Font License 1.1. The complete notice is published as `dist/esm/PatrickHand-OFL.txt`.

package/compat-manifest.json

@@ -0,0 +1,305 @@
+{
+    "schemaVersion": 2,
+    "releaseStatus": "publication-authorized",
+    "publicationEnabled": true,
+    "gaScope": {
+        "publicPackages": [
+            "@cratis/components",
+            "@cratis/eslint-plugin-components",
+            "@cratis/components.migrator",
+            "@cratis/components.conformance",
+            "@cratis/components.mui",
+            "@cratis/components.primereact",
+            "@cratis/components.primereact10"
+        ],
+        "privateEvidence": [
+            {
+                "id": "plain",
+                "name": "Plain DOM renderer conformance falsification fixture",
+                "purpose": "private-conformance-evidence",
+                "private": true,
+                "published": false
+            },
+            {
+                "id": "storybook",
+                "name": "Composed renderer Storybook",
+                "purpose": "private-renderer-evidence",
+                "private": true,
+                "published": false
+            }
+        ]
+    },
+    "toolingCompatibility": {
+        "componentsCore": ">=4 <5",
+        "eslint": ">=4 <5",
+        "migrator": ">=4 <5"
+    },
+    "supportWindows": {
+        "components3": {
+            "components": ">=3 <4",
+            "status": "maintenance-security-critical",
+            "migrationRole": "source",
+            "migrationTarget": ">=4 <5",
+            "tooling": ">=4 <5",
+            "eolAt": null,
+            "eolApprovedByOwners": false,
+            "ownerDecisionPolicy": "Set and approve EOL no later than 12 months after Components 4 GA."
+        },
+        "components4": {
+            "components": ">=4 <5",
+            "status": "current",
+            "migrationRole": "target",
+            "rendererAbi": 1,
+            "coreProfile": "core/v1",
+            "adapterProfile": "stable-presentation/v1",
+            "tooling": {
+                "eslint": ">=4 <5",
+                "migrator": ">=4 <5"
+            },
+            "adapters": {
+                "@cratis/components.conformance": ">=4 <5",
+                "@cratis/components.mui": ">=4 <5",
+                "@cratis/components.primereact": ">=4 <5",
+                "@cratis/components.primereact10": ">=4 <5"
+            }
+        }
+    },
+    "packages": [
+        {
+            "name": "@cratis/components",
+            "role": "core",
+            "version": "4.0.0",
+            "releaseMajorRange": ">=4 <5",
+            "independentRelease": false,
+            "private": false,
+            "packageAccess": "public",
+            "peerDependencies": {
+                "@cratis/arc": ">=20.3.1 <23",
+                "@cratis/arc.react": ">=20.3.1 <23",
+                "@cratis/fundamentals": "^7.10.3",
+                "pixi.js": "^8.20.0",
+                "react": "^19.0.0",
+                "react-dom": "^19.0.0",
+                "reflect-metadata": "0.2.2",
+                "tsyringe": "4.10.0"
+            },
+            "upstream": {
+                "react": "^19.0.0"
+            },
+            "rendererAbi": 1,
+            "rendererProfile": "core/v1"
+        },
+        {
+            "name": "@cratis/eslint-plugin-components",
+            "role": "eslint",
+            "version": "4.0.0",
+            "releaseMajorRange": ">=4 <5",
+            "independentRelease": false,
+            "private": false,
+            "packageAccess": "public",
+            "peerDependencies": {
+                "eslint": ">=9"
+            },
+            "upstream": {}
+        },
+        {
+            "name": "@cratis/components.migrator",
+            "role": "migrator",
+            "version": "4.0.0",
+            "releaseMajorRange": ">=4 <5",
+            "independentRelease": false,
+            "private": false,
+            "packageAccess": "public",
+            "peerDependencies": {},
+            "upstream": {}
+        },
+        {
+            "name": "@cratis/components.conformance",
+            "role": "conformance",
+            "version": "4.0.0",
+            "releaseMajorRange": ">=4 <5",
+            "independentRelease": false,
+            "private": false,
+            "packageAccess": "public",
+            "peerDependencies": {
+                "@cratis/components": ">=4 <5",
+                "react": "^19.0.0",
+                "react-dom": "^19.0.0"
+            },
+            "upstream": {},
+            "rendererAbi": 1
+        },
+        {
+            "name": "@cratis/components.mui",
+            "role": "renderer-adapter",
+            "version": "4.0.0",
+            "releaseMajorRange": ">=4 <5",
+            "independentRelease": false,
+            "private": false,
+            "packageAccess": "public",
+            "peerDependencies": {
+                "@cratis/components": ">=4 <5",
+                "@emotion/react": ">=11.5 <12",
+                "@emotion/styled": ">=11.11 <12",
+                "@mui/material": ">=9 <10",
+                "react": "^19.0.0",
+                "react-dom": "^19.0.0"
+            },
+            "upstream": {
+                "@emotion/react": ">=11.5 <12",
+                "@emotion/styled": ">=11.11 <12",
+                "@mui/material": ">=9 <10",
+                "react": "^19.0.0",
+                "react-dom": "^19.0.0"
+            },
+            "rendererAbi": 1,
+            "rendererProfile": "stable-presentation/v1",
+            "verifiedPeers": {
+                "minimum": {
+                    "@cratis/arc": "22.6.2",
+                    "@cratis/arc.react": "22.6.2",
+                    "@cratis/fundamentals": "7.18.1",
+                    "@emotion/react": "11.5.0",
+                    "@emotion/styled": "11.11.0",
+                    "@mui/material": "9.0.0",
+                    "@types/react": "19.0.0",
+                    "react": "19.0.0",
+                    "react-dom": "19.0.0",
+                    "reflect-metadata": "0.2.2",
+                    "rxjs": "7.8.2",
+                    "tsyringe": "4.10.0"
+                },
+                "current": {
+                    "@cratis/arc": "22.6.2",
+                    "@cratis/arc.react": "22.6.2",
+                    "@cratis/fundamentals": "7.18.1",
+                    "@emotion/react": "11.14.0",
+                    "@emotion/styled": "11.14.1",
+                    "@mui/material": "9.4.0",
+                    "@types/react": "19.2.18",
+                    "react": "19.2.8",
+                    "react-dom": "19.2.8",
+                    "reflect-metadata": "0.2.2",
+                    "rxjs": "7.8.2",
+                    "tsyringe": "4.10.0"
+                }
+            }
+        },
+        {
+            "name": "@cratis/components.primereact",
+            "role": "renderer-adapter",
+            "version": "4.0.0",
+            "releaseMajorRange": ">=4 <5",
+            "independentRelease": false,
+            "private": false,
+            "packageAccess": "public",
+            "peerDependencies": {
+                "@cratis/components": ">=4 <5",
+                "@primereact/core": ">=11 <12",
+                "@primereact/ui": ">=11 <12",
+                "@primeuix/themes": ">=3 <4",
+                "primereact": ">=11 <12",
+                "react": "^19.0.0",
+                "react-dom": "^19.0.0"
+            },
+            "upstream": {
+                "@primereact/core": ">=11 <12",
+                "@primereact/ui": ">=11 <12",
+                "@primeuix/themes": ">=3 <4",
+                "primereact": ">=11 <12",
+                "react": "^19.0.0",
+                "react-dom": "^19.0.0"
+            },
+            "rendererAbi": 1,
+            "rendererProfile": "stable-presentation/v1",
+            "verifiedPeers": {
+                "minimum": {
+                    "@cratis/arc": "22.6.2",
+                    "@cratis/arc.react": "22.6.2",
+                    "@cratis/fundamentals": "7.18.1",
+                    "@primereact/core": "11.0.0",
+                    "@primereact/headless": "11.0.0",
+                    "@primereact/styles": "11.0.0",
+                    "@primereact/ui": "11.0.0",
+                    "@primeuix/motion": "1.0.0",
+                    "@primeuix/themes": "3.0.0",
+                    "@primeuix/utils": "0.8.0",
+                    "@types/react": "19.0.0",
+                    "primereact": "11.0.0",
+                    "react": "19.0.0",
+                    "react-dom": "19.0.0",
+                    "reflect-metadata": "0.2.2",
+                    "rxjs": "7.8.2",
+                    "tsyringe": "4.10.0"
+                },
+                "current": {
+                    "@cratis/arc": "22.6.2",
+                    "@cratis/arc.react": "22.6.2",
+                    "@cratis/fundamentals": "7.18.1",
+                    "@primereact/core": "11.1.0",
+                    "@primereact/headless": "11.1.0",
+                    "@primereact/styles": "11.1.0",
+                    "@primereact/ui": "11.1.0",
+                    "@primeuix/motion": "1.0.0",
+                    "@primeuix/themes": "3.0.0",
+                    "@primeuix/utils": "0.8.1",
+                    "@types/react": "19.2.18",
+                    "primereact": "11.1.0",
+                    "react": "19.2.8",
+                    "react-dom": "19.2.8",
+                    "reflect-metadata": "0.2.2",
+                    "rxjs": "7.8.2",
+                    "tsyringe": "4.10.0"
+                }
+            }
+        },
+        {
+            "name": "@cratis/components.primereact10",
+            "role": "renderer-adapter",
+            "version": "4.0.0",
+            "releaseMajorRange": ">=4 <5",
+            "independentRelease": false,
+            "private": false,
+            "packageAccess": "public",
+            "peerDependencies": {
+                "@cratis/components": ">=4 <5",
+                "primereact": ">=10.9.9 <11",
+                "react": "^19.0.0",
+                "react-dom": "^19.0.0"
+            },
+            "upstream": {
+                "primereact": ">=10.9.9 <11",
+                "react": "^19.0.0",
+                "react-dom": "^19.0.0"
+            },
+            "rendererAbi": 1,
+            "rendererProfile": "stable-presentation/v1",
+            "verifiedPeers": {
+                "minimum": {
+                    "@cratis/arc": "22.6.2",
+                    "@cratis/arc.react": "22.6.2",
+                    "@cratis/fundamentals": "7.18.1",
+                    "@types/react": "19.0.0",
+                    "primereact": "10.9.9",
+                    "react": "19.0.0",
+                    "react-dom": "19.0.0",
+                    "reflect-metadata": "0.2.2",
+                    "rxjs": "7.8.2",
+                    "tsyringe": "4.10.0"
+                },
+                "current": {
+                    "@cratis/arc": "22.6.2",
+                    "@cratis/arc.react": "22.6.2",
+                    "@cratis/fundamentals": "7.18.1",
+                    "@types/react": "19.2.18",
+                    "primereact": "10.9.9",
+                    "react": "19.2.8",
+                    "react-dom": "19.2.8",
+                    "reflect-metadata": "0.2.2",
+                    "rxjs": "7.8.2",
+                    "tsyringe": "4.10.0"
+                }
+            }
+        }
+    ]
+}

package/dist/esm/Canvas/Canvas.d.ts

@@ -1,69 +1,158 @@
 import React from 'react';
 import * as PIXI from 'pixi.js';
-import { CanvasControlsLabels } from './CanvasControls';
-import { MinimapItem } from './CanvasMinimap';
+import { type CanvasControlsLabels } from './CanvasControls.js';
+import type { MinimapItem } from './CanvasMinimap.js';
+/** Measured world-space bounds for one registered {@link CanvasItem}. */
 export interface CanvasItemRegistryEntry {
+    /** World-space horizontal position. */
     x: number;
+    /** World-space vertical position. */
     y: number;
+    /** Measured width. */
     width: number;
+    /** Measured height. */
     height: number;
+    /**
+     * Whether this entry is registered under an internally generated id rather than one the caller
+     * supplied through {@link CanvasItem}'s `id` prop. An anonymous entry still feeds every consumer
+     * of the registry — the minimap, fit-to-content — but `Region` (via `itemsWithinRegion`) never
+     * reports it as a region member, since there is no caller-owned id a host could recognize it by.
+     */
+    anonymous?: boolean;
 }
+/** Registry contract used by {@link CanvasItem} to publish measured bounds. */
 export interface CanvasItemRegistryContextValue {
+    /** Adds or updates one measured item. */
     register: (id: string, entry: CanvasItemRegistryEntry) => void;
+    /** Removes one measured item. */
     unregister: (id: string) => void;
+    /**
+     * The registry's current content, as a stable-reference snapshot: the returned map's identity only
+     * changes when the content actually changed (an item registered, unregistered, or moved/resized),
+     * making it safe to feed straight into `useSyncExternalStore`. The map is rebuilt on change — never
+     * mutated in place — so a held snapshot stays internally consistent. Optional so a consumer
+     * providing its own registry value predating this member keeps type-checking; readers must
+     * fall back gracefully when absent.
+     */
     getSnapshot?: () => ReadonlyMap<string, CanvasItemRegistryEntry>;
+    /**
+     * Subscribes to registry changes; the listener fires after every register/unregister/bounds-update
+     * that actually changed content. Bounds updates can arrive per-frame during a drag — listeners
+     * decide how much work to do per notification. Returns the unsubscribe function.
+     * `useSyncExternalStore`-compatible. Optional for the same compatibility reason as
+     * {@link getSnapshot}.
+     */
     subscribe?: (listener: () => void) => () => void;
 }
+/** Context carrying the nearest Canvas item registry. */
 export declare const CanvasItemRegistryContext: React.Context<CanvasItemRegistryContextValue | null>;
+/** Minimum data shape for an optional Pixi-rendered canvas item. */
 export interface CanvasItemData {
+    /** Stable item identity. */
     id: string;
+    /** World-space horizontal position. */
     x: number;
+    /** World-space vertical position. */
     y: number;
 }
+/** Pixi objects supplied after the Canvas renderer initializes. */
 export interface CanvasContext {
+    /** Pixi application owned by the Canvas. */
     app: PIXI.Application;
+    /** Pixi world container receiving rendered items. */
     world: PIXI.Container;
 }
+/** Imperative camera and measurement operations exposed by {@link Canvas}. */
 export interface CanvasHandle {
+    /** Smoothly centers a world point. */
     smoothPanToWorld(worldX: number, worldY: number, durationMs?: number): void;
+    /** Smoothly centers a world point while animating to a target zoom. */
     smoothPanZoomToWorld(worldX: number, worldY: number, targetZoom?: number, durationMs?: number): void;
+    /** Returns the current viewport rectangle, or `null` before mounting. */
     getContainerRect(): DOMRect | null;
+    /** Returns world-space bounds for every registered CanvasItem. */
     getItemBounds(): MinimapItem[];
 }
+/** Optional product compositor/capture marker names applied by {@link Canvas}. */
+export interface CanvasCaptureAttributes {
+    /** Attribute placed on the Pixi canvas so a product capture pipeline can exclude it. */
+    layer?: string;
+    /** Attribute placed on non-plain integrated controls that own composited content. */
+    content?: string;
+    /** Attribute placed on pan/zoom transform hosts whose churn moves existing layers. */
+    transformHost?: string;
+}
+/** Props for the pan, zoom, item, minimap, and control surface. */
 export interface CanvasProps<T extends CanvasItemData = CanvasItemData> {
+    /** DOM content positioned inside the transformed world. */
     children?: React.ReactNode;
+    /** Optional Pixi-rendered item data. */
     items?: T[];
+    /** Builds a Pixi display object for one item. */
     renderItem?: (item: T) => PIXI.Container;
+    /** Receives pointer activation for a Pixi-rendered item. */
     onItemPointerDown?: (item: T, event: PIXI.FederatedPointerEvent) => void;
+    /** Receives the initialized Pixi application and world. */
     onReady?: (context: CanvasContext) => void;
+    /** Reports every camera transform change. */
     onTransformChange?: (zoom: number, pan: {
         x: number;
         y: number;
     }) => void;
+    /** Initial zoom factor. Defaults to `1`. */
     initialZoom?: number;
+    /** Initial viewport translation. Defaults to `{ x: 0, y: 0 }`. */
     initialPan?: {
         x: number;
         y: number;
     };
+    /** Minimum zoom factor. Defaults to `0.1`. */
     minZoom?: number;
+    /** Maximum zoom factor. Defaults to `5`. */
     maxZoom?: number;
+    /** Whether integrated zoom controls render. Defaults to `true`. */
     showControls?: boolean;
+    /** Whether controls expose the minimap toggle. Defaults to `false`. */
     showMinimap?: boolean;
+    /** World width represented by the minimap. */
     minimapWorldWidth?: number;
+    /** World height represented by the minimap. */
     minimapWorldHeight?: number;
+    /** Explicit minimap item rectangles; measured CanvasItem bounds are used otherwise. */
     minimapItems?: MinimapItem[];
+    /** Edge used by the integrated control bar. Defaults to `'bottom-left'`. */
     controlsPlacement?: 'bottom-left' | 'bottom-right';
+    /** Extra class name for the Canvas root. */
     className?: string;
+    /** Inline style for the Canvas root. */
     style?: React.CSSProperties;
+    /** Invoked when the optional help action is activated. */
     onHelp?: () => void;
+    /** Accessible label and tooltip for the help action. */
     helpTitle?: string;
-    disableControlsGlass?: boolean;
-    controlsGlassSurface?: React.ReactNode;
+    /** Localized labels for integrated zoom/minimap/help controls. */
     controlsLabels?: CanvasControlsLabels;
+    /** Optional product-owned glass/acrylic surface behind integrated controls. */
+    controlsGlassSurface?: React.ReactNode;
+    /** Uses a low-cost CSS frosted pill instead of a consumer-supplied glass surface. */
+    disableControlsGlass?: boolean;
+    /** Product-owned capture/compositor marker names. Canvas has no capture-provider dependency. */
+    captureAttributes?: CanvasCaptureAttributes;
+    /** Receives imperative camera and measurement operations. */
     onHandleReady?: (handle: CanvasHandle) => void;
+    /** Keeps pan/zoom available while absorbing interaction with canvas content. */
     readOnly?: boolean;
+    /**
+     * Whether mouse/pen drag on empty background pans the board. Disable when
+     * the product owns that gesture for selection; wheel, middle-button, and
+     * touch panning remain available.
+     */
     backgroundDragPans?: boolean;
 }
-declare function Canvas<T extends CanvasItemData = CanvasItemData>({ children, items, renderItem, onItemPointerDown, onReady, onTransformChange, onHandleReady, initialZoom, initialPan, minZoom, maxZoom, showControls, showMinimap, minimapWorldWidth, minimapWorldHeight, minimapItems, controlsPlacement, className, style, onHelp, helpTitle, disableControlsGlass, controlsGlassSurface, controlsLabels, readOnly, backgroundDragPans, }: CanvasProps<T>): React.ReactElement;
+/**
+ * A pan/zoom/Pixi-backed infinite canvas with optional HTML overlay items, integrated minimap, and
+ * zoom controls. Renders Pixi-backed sprites and DOM content under one synchronized camera, manages
+ * wheel/touch/trackpad gestures, and exposes imperative camera navigation.
+ */
+declare function Canvas<T extends CanvasItemData = CanvasItemData>({ children, items, renderItem, onItemPointerDown, onReady, onTransformChange, onHandleReady, initialZoom, initialPan, minZoom, maxZoom, showControls, showMinimap, minimapWorldWidth, minimapWorldHeight, minimapItems, controlsPlacement, className, style, onHelp, helpTitle, controlsLabels, controlsGlassSurface, disableControlsGlass, captureAttributes, readOnly, backgroundDragPans, }: CanvasProps<T>): React.ReactElement;
 export { Canvas };
-//# sourceMappingURL=Canvas.d.ts.map