@deadragdoll/reactnu 0.1.30 → 0.1.52

package/README.md

@@ -70,6 +70,7 @@ This package includes the complete Markdown documentation set:
 - [Component Index](./docs/COMPONENT_INDEX.md)
 - [Architecture](./docs/ARCHITECTURE.md)
 - [Theme Provider](./docs/NuThemeProvider.md)
+- [Shared Drag and Drop](./docs/NuDragDropProvider.md)
 - [Window Provider](./docs/NuWindowProvider.md)
 - [Storybook guidance](./docs/STORYBOOK.md)
 
@@ -80,6 +81,7 @@ Each public component has a dedicated page in [`docs/`](./docs/).
 ### Providers and desktop shell
 
 - `NuThemeProvider` — supplies themes, typography, desktop pattern, and theme context.
+- `NuDragDropProvider` — coordinates application-owned transfers among icon grids, lists, and trees.
 - `NuDesktop` — fullscreen desktop shell with workspace and app-bar regions.
 - `NuAppHostProvider` — owns application-level main-menu state.
 - `NuWindowProvider` — manages windows, dialogs, modal state, and window-manager hooks.

package/dist/components/DragDrop/NuDragDropProvider.d.ts

@@ -0,0 +1,46 @@
+import { PointerEvent, PropsWithChildren } from "react";
+export type NuDragDropItem<T = unknown> = {
+    data: T;
+    id: string;
+    type: string;
+};
+export type NuDragDropContext = {
+    clientX: number;
+    clientY: number;
+    source: {
+        element: HTMLElement;
+        type: string;
+    };
+    target: {
+        element: HTMLElement;
+        type: string;
+    };
+};
+export type NuDropTargetOptions = {
+    accepts?: (item: NuDragDropItem) => boolean;
+    onDrop: (item: NuDragDropItem, context: NuDragDropContext) => boolean | void;
+    type: string;
+};
+type NuDragDropController = {
+    beginDrag: (item: NuDragDropItem, sourceElement: HTMLElement, sourceType: string) => void;
+    cancelDrag: () => void;
+    dropAt: (clientX: number, clientY: number) => boolean;
+    moveDrag: (clientX: number, clientY: number) => void;
+    registerTarget: (element: HTMLElement, options: NuDropTargetOptions) => () => void;
+};
+export declare function NuDragDropProvider({ children }: PropsWithChildren): import("react/jsx-runtime").JSX.Element;
+export declare function useNuDragDrop(): NuDragDropController;
+export declare function useNuDropTarget(element: HTMLElement | null, options: NuDropTargetOptions | undefined): void;
+type NuDragSourceOptions = {
+    disabled?: boolean;
+    getItem: () => NuDragDropItem | false;
+    onDropAccepted?: () => void;
+    sourceType: string;
+};
+export declare function useNuDragSource({ disabled, getItem, onDropAccepted, sourceType }: NuDragSourceOptions): {
+    onPointerCancel(event: PointerEvent<HTMLElement>): void;
+    onPointerDown(event: PointerEvent<HTMLElement>): void;
+    onPointerMove(event: PointerEvent<HTMLElement>): void;
+    onPointerUp(event: PointerEvent<HTMLElement>): void;
+};
+export {};

package/dist/components/DragDrop/index.d.ts

@@ -0,0 +1 @@
+export * from "./NuDragDropProvider";

package/dist/components/IconGrid/IconGrid.types.d.ts

@@ -16,6 +16,8 @@ export type NuIconDefinition = {
     onContextMenu?: MouseEventHandler<HTMLButtonElement>;
     onDoubleClick?: MouseEventHandler<HTMLButtonElement>;
     onPositionChange?: (position: NuIconPosition, icon: NuIconInfo) => void;
+    /** Application-defined data preserved when the icon moves to another grid. */
+    payload?: unknown;
     position?: NuIconPosition;
 };
 export type NuIconInfo = Omit<NuIconDefinition, "id" | "position"> & {
@@ -33,3 +35,10 @@ export type NuIconManager = {
     updateIcon: (id: string, patch: Partial<Omit<NuIconDefinition, "id">>) => void;
 };
 export type NuIconContextMenuItems = MainMenuNode[] | ((manager: NuIconManager) => MainMenuNode[]);
+export type NuIconDropContext = {
+    position: NuIconPosition;
+    source: NuIconManager;
+    sourceGrid: HTMLElement;
+    target: NuIconManager;
+    targetGrid: HTMLElement;
+};

package/dist/components/IconGrid/NuIconGrid.d.ts

@@ -1,7 +1,22 @@
 import { HTMLAttributes } from "react";
-import { NuIconContextMenuItems, NuIconArrangeMode } from "./IconGrid.types";
-export type NuIconGridProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+import { NuDragDropContext, NuDragDropItem } from "../DragDrop";
+import { NuIconContextMenuItems, NuIconArrangeMode, NuIconDropContext, NuIconInfo } from "./IconGrid.types";
+export type NuIconGridProps = Omit<HTMLAttributes<HTMLDivElement>, "children" | "onDrop"> & {
+    /** Filters icons accepted from another IconGrid before `onIconDrop` is called. */
+    accepts?: (icon: NuIconInfo) => boolean;
+    /** Filters non-icon shared drag items accepted by this grid. */
+    acceptsDrop?: (item: NuDragDropItem) => boolean;
     contextMenuItems?: NuIconContextMenuItems;
     defaultArrangeMode?: NuIconArrangeMode;
+    /** Enables hit testing for a non-interactive grid surface behind other content. */
+    dropTarget?: boolean;
+    /** Called by the target grid before an icon is transferred. Return false to reject the drop. */
+    onIconDrop?: (icon: NuIconInfo, context: NuIconDropContext) => boolean | void;
+    /** Called by the source grid after its icon was transferred to another grid. */
+    onIconMoveOut?: (icon: NuIconInfo, context: NuIconDropContext) => void;
+    /** Called after an icon was accepted by a non-IconGrid shared drop target. */
+    onDragOut?: (item: NuDragDropItem<NuIconInfo>) => void;
+    /** Receives non-icon shared drag items. Return false to reject the drop. */
+    onDrop?: (item: NuDragDropItem, context: NuDragDropContext) => boolean | void;
 };
-export declare function NuIconGrid({ className, contextMenuItems: contextMenuItemsSource, defaultArrangeMode, onContextMenu, onPointerDown, ...props }: NuIconGridProps): import("react/jsx-runtime").JSX.Element;
+export declare function NuIconGrid({ accepts, acceptsDrop, className, contextMenuItems: contextMenuItemsSource, defaultArrangeMode, dropTarget, onDragOut, onIconDrop, onIconMoveOut, onDrop, onContextMenu, onPointerDown, ...props }: NuIconGridProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ListBox/ListBox.d.ts

@@ -1,5 +1,6 @@
-import { ForwardedRef, HTMLAttributes, RefAttributes } from "react";
+import { ForwardedRef, HTMLAttributes, MouseEvent, RefAttributes } from "react";
 import { ListBoxGroup, ListBoxItem } from "./internals/types";
+import { NuDragDropContext, NuDragDropItem } from "../DragDrop";
 export type { ListBoxCategory, ListBoxGroup, ListBoxItem, ListBoxLabel } from "./internals/types";
 export type ListBoxHandle = {
     activateItem: (itemId: string) => void;
@@ -8,16 +9,25 @@ export type ListBoxHandle = {
     scrollToItem: (itemId: string) => void;
     toggleItemCheck: (itemId: string) => void;
 };
-export type ListBoxProps = Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> & {
+export type ListBoxProps = Omit<HTMLAttributes<HTMLDivElement>, "onDrop" | "onSelect"> & {
+    /** Decides whether this list can receive a shared drag item. */
+    acceptsDrop?: (item: NuDragDropItem) => boolean;
     data: ListBoxGroup[];
     checkedIds?: string[];
+    /** Returns the shared drag item for a row, or false to keep it static. */
+    getDragItem?: (item: ListBoxItem, group: ListBoxGroup) => NuDragDropItem | false;
+    onPopupMenu?: (event: MouseEvent<HTMLDivElement>, item: ListBoxItem, group: ListBoxGroup) => void;
     emptyText?: string;
     onItemCheckChange?: (item: ListBoxItem, group: ListBoxGroup, checked: boolean) => void;
     onItemDoubleClick?: (item: ListBoxItem, group: ListBoxGroup) => void;
+    /** Called after this list row was accepted by a different shared drop target. */
+    onItemDragOut?: (item: ListBoxItem, group: ListBoxGroup) => void;
     rightCheckBox?: boolean;
     selectedId?: string;
     uncheckedShape?: "box" | "none";
     onItemSelect?: (item: ListBoxItem, group: ListBoxGroup) => void;
+    /** Receives a shared drag item. Return false to reject it. */
+    onDrop?: (item: NuDragDropItem, context: NuDragDropContext) => boolean | void;
 };
-declare function ListBoxInner({ className, data, checkedIds, emptyText, onItemCheckChange, onItemDoubleClick, onItemSelect, rightCheckBox, selectedId, uncheckedShape, ...props }: ListBoxProps, ref: ForwardedRef<ListBoxHandle>): import("react/jsx-runtime").JSX.Element;
+declare function ListBoxInner({ acceptsDrop, className, data, checkedIds, emptyText, getDragItem, onPopupMenu, onItemCheckChange, onItemDoubleClick, onItemDragOut, onItemSelect, onDrop, rightCheckBox, selectedId, uncheckedShape, ...props }: ListBoxProps, ref: ForwardedRef<ListBoxHandle>): import("react/jsx-runtime").JSX.Element;
 export declare const ListBox: (props: ListBoxProps & RefAttributes<ListBoxHandle>) => ReturnType<typeof ListBoxInner>;

package/dist/components/ListBox/internals/ListBoxGroupView.d.ts

@@ -1,11 +1,16 @@
+import { MouseEvent } from "react";
 import { ListBoxGroup, ListBoxItem } from "./types";
+import { NuDragDropItem } from "../../DragDrop";
 type ListBoxGroupViewProps = {
     group: ListBoxGroup;
     groupIndex: number;
+    getDragItem?: (item: ListBoxItem, group: ListBoxGroup) => NuDragDropItem | false;
     isItemChecked: (item: ListBoxItem) => boolean;
     listboxId: string;
     onActivateItem: (item: ListBoxItem, group: ListBoxGroup, itemId: string) => void;
     onDoubleClickItem?: (item: ListBoxItem, group: ListBoxGroup) => void;
+    onItemDragOut?: (item: ListBoxItem, group: ListBoxGroup) => void;
+    onPopupMenuItem?: (event: MouseEvent<HTMLDivElement>, item: ListBoxItem, group: ListBoxGroup, itemId: string) => void;
     onToggleItemCheck: (itemId: string) => void;
     registerItemRef: (itemId: string, node: HTMLDivElement | null) => void;
     resolvedActiveId: string | null;
@@ -13,5 +18,5 @@ type ListBoxGroupViewProps = {
     selectedId?: string;
     uncheckedShape: "box" | "none";
 };
-export declare function ListBoxGroupView({ group, groupIndex, isItemChecked, listboxId, onActivateItem, onDoubleClickItem, onToggleItemCheck, registerItemRef, resolvedActiveId, rightCheckBox, selectedId, uncheckedShape }: ListBoxGroupViewProps): import("react/jsx-runtime").JSX.Element;
+export declare function ListBoxGroupView({ group, groupIndex, getDragItem, isItemChecked, listboxId, onActivateItem, onDoubleClickItem, onItemDragOut, onPopupMenuItem, onToggleItemCheck, registerItemRef, resolvedActiveId, rightCheckBox, selectedId, uncheckedShape }: ListBoxGroupViewProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/ListBox/internals/ListBoxItemView.d.ts

@@ -1,6 +1,9 @@
+import { MouseEvent } from "react";
+import { NuDragDropItem } from "../../DragDrop";
 import { ListBoxGroup, ListBoxItem } from "./types";
 type ListBoxItemViewProps = {
     group: ListBoxGroup;
+    getDragItem?: (item: ListBoxItem, group: ListBoxGroup) => NuDragDropItem | false;
     isActive: boolean;
     isChecked: boolean;
     isSelected: boolean;
@@ -8,11 +11,13 @@ type ListBoxItemViewProps = {
     itemId: string;
     onActivate: (item: ListBoxItem, group: ListBoxGroup, itemId: string) => void;
     onDoubleClick?: (item: ListBoxItem, group: ListBoxGroup) => void;
+    onDragOut?: (item: ListBoxItem, group: ListBoxGroup) => void;
+    onPopupMenu?: (event: MouseEvent<HTMLDivElement>, item: ListBoxItem, group: ListBoxGroup, itemId: string) => void;
     onToggleCheck: (itemId: string) => void;
     registerItemRef: (itemId: string, node: HTMLDivElement | null) => void;
     rightCheckBox: boolean;
     uncheckedShape: "box" | "none";
 };
-declare function ListBoxItemViewInner({ group, isActive, isChecked, isSelected, item, itemId, onActivate, onDoubleClick, onToggleCheck, registerItemRef, rightCheckBox, uncheckedShape }: ListBoxItemViewProps): import("react/jsx-runtime").JSX.Element;
+declare function ListBoxItemViewInner({ group, getDragItem, isActive, isChecked, isSelected, item, itemId, onActivate, onPopupMenu, onDoubleClick, onDragOut, onToggleCheck, registerItemRef, rightCheckBox, uncheckedShape }: ListBoxItemViewProps): import("react/jsx-runtime").JSX.Element;
 export declare const ListBoxItemView: import("react").MemoExoticComponent<typeof ListBoxItemViewInner>;
 export {};

package/dist/components/TreeListView/TreeListView.d.ts

@@ -1,5 +1,6 @@
-import { ForwardedRef, HTMLAttributes, RefAttributes } from "react";
-import { TreeListColumn, TreeListGetCellContent, TreeListItemBase } from "./internals/types";
+import { ForwardedRef, HTMLAttributes, MouseEvent, RefAttributes } from "react";
+import { TreeListColumn, TreeListCellContext, TreeListGetCellContent, TreeListItemBase } from "./internals/types";
+import { NuDragDropContext, NuDragDropItem } from "../DragDrop";
 export type { TreeListCellContext, TreeListColumn, TreeListGetCellContent, TreeListItemBase } from "./internals/types";
 export type TreeListViewHandle = {
     activateItem: (itemId: string) => void;
@@ -10,9 +11,12 @@ export type TreeListViewHandle = {
     scrollToItem: (itemId: string) => void;
     toggleItemCheck: (itemId: string) => void;
 };
-export type TreeListViewProps<T extends TreeListItemBase<T>> = Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> & {
+export type TreeListViewProps<T extends TreeListItemBase<T>> = Omit<HTMLAttributes<HTMLDivElement>, "onDrop" | "onSelect"> & {
+    /** Decides whether this tree can receive a shared drag item. */
+    acceptsDrop?: (item: NuDragDropItem) => boolean;
     activeItemId?: string;
     checkedIds?: string[];
+    onPopupMenu?: (event: MouseEvent<HTMLDivElement>, item: T, context: TreeListCellContext<T>) => void;
     columns: TreeListColumn<T>[];
     data: T[];
     dataVersion?: number;
@@ -20,14 +24,20 @@ export type TreeListViewProps<T extends TreeListItemBase<T>> = Omit<HTMLAttribut
     defaultExpandedIds?: string[];
     emptyText?: string;
     expandedIds?: string[];
+    /** Returns the shared drag item for a row, or false to keep it static. */
+    getDragItem?: (item: T, context: TreeListCellContext<T>) => NuDragDropItem | false;
     getCellContent?: TreeListGetCellContent<T>;
     onActiveItemChange?: (item: T) => void;
     onExpandedIdsChange?: (expandedIds: string[]) => void;
     onItemCheckChange?: (item: T, checked: boolean) => void;
     onItemDoubleClick?: (item: T) => void;
+    /** Called after this tree row was accepted by a different shared drop target. */
+    onItemDragOut?: (item: T, context: TreeListCellContext<T>) => void;
     onItemSelect?: (item: T) => void;
+    /** Receives a shared drag item. Return false to reject it. */
+    onDrop?: (item: NuDragDropItem, context: NuDragDropContext) => boolean | void;
     selectedId?: string;
     uncheckedShape?: "box" | "none";
 };
-declare function TreeListViewInner<T extends TreeListItemBase<T>>({ activeItemId: activeItemIdProp, checkedIds, className, columns, data, dataVersion, defaultActiveItemId, defaultExpandedIds, emptyText, expandedIds, getCellContent, onActiveItemChange, onExpandedIdsChange, onItemCheckChange, onItemDoubleClick, onItemSelect, selectedId, uncheckedShape, ...props }: TreeListViewProps<T>, ref: ForwardedRef<TreeListViewHandle>): import("react/jsx-runtime").JSX.Element;
+declare function TreeListViewInner<T extends TreeListItemBase<T>>({ acceptsDrop, activeItemId: activeItemIdProp, checkedIds, className, columns, onPopupMenu, data, dataVersion, defaultActiveItemId, defaultExpandedIds, emptyText, expandedIds, getDragItem, getCellContent, onActiveItemChange, onExpandedIdsChange, onItemCheckChange, onItemDoubleClick, onItemDragOut, onItemSelect, onDrop, selectedId, uncheckedShape, ...props }: TreeListViewProps<T>, ref: ForwardedRef<TreeListViewHandle>): import("react/jsx-runtime").JSX.Element;
 export declare const TreeListView: <T extends TreeListItemBase<T>>(props: TreeListViewProps<T> & RefAttributes<TreeListViewHandle>) => ReturnType<typeof TreeListViewInner>;

package/dist/components/TreeListView/internals/TreeListViewRow.d.ts

@@ -1,4 +1,6 @@
-import { TreeListColumn, TreeListGetCellContent, TreeListItemBase } from "./types";
+import { MouseEvent } from "react";
+import { NuDragDropItem } from "../../DragDrop";
+import { TreeListCellContext, TreeListColumn, TreeListGetCellContent, TreeListItemBase } from "./types";
 type TreeListViewRowProps<T extends TreeListItemBase<T>> = {
     activeItemId: string | null;
     checkedIds?: string[];
@@ -6,12 +8,15 @@ type TreeListViewRowProps<T extends TreeListItemBase<T>> = {
     depth: number;
     expandedIdSet: Set<string>;
     getCellContent?: TreeListGetCellContent<T>;
+    getDragItem?: (item: T, context: TreeListCellContext<T>) => NuDragDropItem | false;
     guideMask: boolean[];
     guideOffsets: number[];
     hasNextSibling: boolean;
     item: T;
     onActivateItem: (item: T, itemId: string) => void;
     onDoubleClickItem?: (item: T) => void;
+    onItemDragOut?: (item: T, context: TreeListCellContext<T>) => void;
+    onPopupMenuItem?: (event: MouseEvent<HTMLDivElement>, item: T, context: TreeListCellContext<T>) => void;
     onToggleItemCheck?: (item: T, checked: boolean) => void;
     onToggleItemExpanded: (item: T, expanded: boolean) => void;
     originOffset: number;
@@ -23,6 +28,6 @@ type TreeListViewRowProps<T extends TreeListItemBase<T>> = {
     treeId: string;
     uncheckedShape: "box" | "none";
 };
-declare function TreeListViewRowInner<T extends TreeListItemBase<T>>({ activeItemId, checkedIds, columns, depth, expandedIdSet, getCellContent, guideMask, guideOffsets, hasNextSibling, item, onActivateItem, onDoubleClickItem, onToggleItemCheck, onToggleItemExpanded, originOffset, registerItemRef, rowIndexMap, selectedItemId, templateColumns, treeColumnId, treeId, uncheckedShape }: TreeListViewRowProps<T>): import("react/jsx-runtime").JSX.Element;
+declare function TreeListViewRowInner<T extends TreeListItemBase<T>>({ activeItemId, checkedIds, columns, depth, expandedIdSet, getCellContent, getDragItem, guideMask, guideOffsets, hasNextSibling, item, onActivateItem, onDoubleClickItem, onItemDragOut, onPopupMenuItem, onToggleItemCheck, onToggleItemExpanded, originOffset, registerItemRef, rowIndexMap, selectedItemId, templateColumns, treeColumnId, treeId, uncheckedShape }: TreeListViewRowProps<T>): import("react/jsx-runtime").JSX.Element;
 export declare const TreeListViewRow: typeof TreeListViewRowInner;
 export {};