@olenbetong/appframe-ds 0.6.0 → 0.7.0

package/src/sortable/DropIndicator.tsx

@@ -0,0 +1,27 @@
+import "./DropIndicator.css";
+
+import type { Edge } from "@atlaskit/pragmatic-drag-and-drop-hitbox/types";
+import clsx from "clsx";
+import type { CSSProperties } from "react";
+
+export type DropIndicatorProps = {
+	/** Which edge of the item the dragged item will be dropped on */
+	edge: Edge;
+	/** Distance from the edge, e.g. to account for a gap between items */
+	gap?: string;
+	className?: string;
+};
+
+/**
+ * Line rendered on the edge of a list item to show where a dragged item will
+ * be placed. Must be rendered inside a positioned (`position: relative`)
+ * element, normally the list item itself.
+ */
+export function DropIndicator({ edge, gap, className }: DropIndicatorProps) {
+	return (
+		<div
+			className={clsx("ObDropIndicator-root", `ObDropIndicator-${edge}`, className)}
+			style={{ "--ob-drop-indicator-gap": gap ?? "0rem" } as CSSProperties}
+		/>
+	);
+}

package/src/sortable/SortableItemList.css

@@ -0,0 +1,21 @@
+.ObSortableItemList-item {
+	position: relative;
+
+	&.ObSortableItemList-dragging {
+		outline: 3px dashed;
+		outline-offset: -3px;
+	}
+}
+
+.ObSortableItemList-handle {
+	cursor: grab;
+	flex-shrink: 0;
+}
+
+.ObSortableItemList-handle:active {
+	cursor: grabbing;
+}
+
+.ObSortableItemList-empty {
+	color: var(--ds-color-neutral-text-subtle, #666);
+}

package/src/sortable/SortableItemList.tsx

@@ -0,0 +1,264 @@
+import "./SortableItemList.css";
+
+import { Button, Dropdown } from "@digdir/designsystemet-react";
+import { DragVerticalIcon } from "@navikt/aksel-icons";
+import { getLocalizedString } from "@olenbetong/appframe-core";
+import clsx from "clsx";
+import type React from "react";
+import { createContext, useContext, useId, useRef } from "react";
+
+import { ItemList } from "../list/ItemList.js";
+import { Paper } from "../paper/Paper.js";
+import { DropIndicator } from "./DropIndicator.js";
+import type { SortableRecord } from "./types.js";
+import { type SortableItemState, useSortableItem } from "./useSortableItem.js";
+import { type SortableList, type SortableListOptions, useSortableList } from "./useSortableList.js";
+
+export interface SortableItemContextValue<T extends SortableRecord = SortableRecord> {
+	record: T;
+	/** Index of the record in the sorted list */
+	index: number;
+	/** Number of records in the list */
+	count: number;
+	/** Records in the list, sorted by `SortOrder` */
+	records: T[];
+	/** Current drag state of the item */
+	state: SortableItemState;
+	/** Element that starts the drag. Attach with `<SortableItemList.DragHandle />` */
+	handleRef: React.RefObject<HTMLButtonElement | null>;
+	enabled: boolean;
+	moveItem: SortableList<T>["moveItem"];
+	/** Moves the item one step up, to the top, one step down or to the bottom */
+	moveTo: (position: "top" | "up" | "down" | "bottom") => Promise<void>;
+}
+
+const SortableItemContext = createContext<SortableItemContextValue | null>(null);
+
+/**
+ * Gives access to the state of the surrounding sortable item, e.g. to
+ * suppress click handlers while the item is being dragged.
+ */
+export function useSortableItemContext<T extends SortableRecord = SortableRecord>(): SortableItemContextValue<T> {
+	let context = useContext(SortableItemContext);
+	if (!context) {
+		throw new Error("useSortableItemContext must be used inside a SortableItemList item");
+	}
+
+	return context as SortableItemContextValue<T>;
+}
+
+export type SortableDragHandleProps = Omit<React.ComponentProps<typeof Button>, "ref" | "icon"> & {
+	/** Accessible label for the handle */
+	label?: string;
+	/**
+	 * Adds a menu with move up/down/top/bottom actions, so the list can be
+	 * reordered without a pointer.
+	 * @default true
+	 */
+	menu?: boolean;
+	children?: React.ReactNode;
+};
+
+/**
+ * Drag handle for a `SortableItemList` item. Dragging is only started from
+ * this element, so the rest of the item stays clickable. By default it also
+ * opens a menu with keyboard accessible move actions.
+ */
+export function SortableDragHandle({
+	label,
+	menu = true,
+	children,
+	className,
+	disabled,
+	...props
+}: SortableDragHandleProps) {
+	let { handleRef, index, count, enabled, moveTo } = useSortableItemContext();
+	let dropdownId = useId();
+	let isDisabled = disabled || !enabled;
+
+	return (
+		<>
+			<Button
+				ref={handleRef}
+				icon
+				variant="tertiary"
+				data-color="neutral"
+				className={clsx("ObSortableItemList-handle", className)}
+				aria-label={label ?? getLocalizedString("Change order")}
+				disabled={isDisabled}
+				popoverTarget={menu && !isDisabled ? dropdownId : undefined}
+				{...props}
+			>
+				{children ?? <DragVerticalIcon aria-hidden />}
+			</Button>
+			{menu && !isDisabled && (
+				<Dropdown id={dropdownId}>
+					<Dropdown.List>
+						<Dropdown.Item>
+							<Dropdown.Button disabled={index === 0} onClick={() => moveTo("top")}>
+								{getLocalizedString("Move to top")}
+							</Dropdown.Button>
+						</Dropdown.Item>
+						<Dropdown.Item>
+							<Dropdown.Button disabled={index === 0} onClick={() => moveTo("up")}>
+								{getLocalizedString("Move up")}
+							</Dropdown.Button>
+						</Dropdown.Item>
+						<Dropdown.Item>
+							<Dropdown.Button disabled={index === count - 1} onClick={() => moveTo("down")}>
+								{getLocalizedString("Move down")}
+							</Dropdown.Button>
+						</Dropdown.Item>
+						<Dropdown.Item>
+							<Dropdown.Button disabled={index === count - 1} onClick={() => moveTo("bottom")}>
+								{getLocalizedString("Move to bottom")}
+							</Dropdown.Button>
+						</Dropdown.Item>
+					</Dropdown.List>
+				</Dropdown>
+			)}
+		</>
+	);
+}
+
+function SortableItem<T extends SortableRecord>({
+	record,
+	index,
+	list,
+	className,
+	indicatorGap,
+	children,
+}: {
+	record: T;
+	index: number;
+	list: SortableList<T>;
+	className?: string;
+	indicatorGap?: string;
+	children: (context: SortableItemContextValue<T>) => React.ReactNode;
+}) {
+	let itemRef = useRef<HTMLElement>(null);
+	let handleRef = useRef<HTMLButtonElement>(null);
+	let { records, moveItem, enabled, type } = list;
+	let state = useSortableItem({ type, record, itemRef, handleRef, enabled });
+
+	async function moveTo(position: "top" | "up" | "down" | "bottom") {
+		let target =
+			position === "top"
+				? records[0]
+				: position === "up"
+					? records[index - 1]
+					: position === "down"
+						? records[index + 1]
+						: records[records.length - 1];
+		if (!target || target.PrimKey === record.PrimKey) return;
+
+		await moveItem(record.PrimKey, target.PrimKey, position === "top" || position === "up" ? null : "bottom");
+	}
+
+	let context: SortableItemContextValue<T> = {
+		record,
+		index,
+		count: records.length,
+		records,
+		state,
+		handleRef,
+		enabled,
+		moveItem,
+		moveTo,
+	};
+
+	return (
+		<SortableItemContext.Provider value={context as SortableItemContextValue}>
+			<ItemList.Item
+				ref={itemRef}
+				className={clsx(
+					"ObSortableItemList-item",
+					state.type === "is-dragging" && "ObSortableItemList-dragging",
+					className,
+				)}
+			>
+				{children(context)}
+				{state.type === "is-dragging-over" && state.edge && <DropIndicator edge={state.edge} gap={indicatorGap} />}
+			</ItemList.Item>
+		</SortableItemContext.Provider>
+	);
+}
+
+export type SortableItemListProps<T extends SortableRecord> = SortableListOptions<T> & {
+	/** Renders the content of a single item. Include a `<SortableItemList.DragHandle />` to allow dragging */
+	children: (record: T, context: SortableItemContextValue<T>) => React.ReactNode;
+	/** Rendered instead of the items when the list is empty */
+	empty?: React.ReactNode;
+	/** Wraps the list in a `Paper` surface @default true */
+	paper?: boolean;
+	/** Renders a divider between items @default true */
+	dividers?: boolean;
+	className?: string;
+	/** Class name added to every item */
+	itemClassName?: string;
+	/** Distance between the drop indicator and the item edge, when items have a gap */
+	indicatorGap?: string;
+};
+
+function SortableItemListComponent<T extends SortableRecord>({
+	children,
+	empty,
+	paper = true,
+	dividers = true,
+	className,
+	itemClassName,
+	indicatorGap,
+	...options
+}: SortableItemListProps<T>) {
+	let list = useSortableList<T>(options);
+
+	let items = list.records.map((record, index) => (
+		<SortableItem
+			key={record.PrimKey}
+			record={record}
+			index={index}
+			list={list}
+			className={itemClassName}
+			indicatorGap={indicatorGap}
+		>
+			{(context) => children(record, context)}
+		</SortableItem>
+	));
+
+	let content = list.records.length === 0 && empty ? <li className="ObSortableItemList-empty">{empty}</li> : items;
+
+	let listElement = (
+		<ItemList dividers={dividers} className={paper ? undefined : className}>
+			{content}
+		</ItemList>
+	);
+
+	return paper ? <Paper className={className}>{listElement}</Paper> : listElement;
+}
+
+/**
+ * `ItemList` bound to a data object, where the items can be reordered by
+ * dragging them or through the menu on the drag handle. The list is sorted by
+ * the `SortOrder` column, and dropping an item writes a new sort order between
+ * its new neighbours through the data object.
+ *
+ * @example
+ * ```jsx
+ * <SortableItemList
+ *   dataObject={dsRelatedProducts}
+ *   filter={(record) => record.ProductRef === productRef}
+ *   empty={<Paragraph>No related products added yet.</Paragraph>}
+ * >
+ *   {(record) => (
+ *     <>
+ *       <SortableItemList.DragHandle label="Change related product order" />
+ *       <ItemList.ItemText primary={record.Title} secondary={record.Slug} />
+ *     </>
+ *   )}
+ * </SortableItemList>
+ * ```
+ */
+export const SortableItemList = Object.assign(SortableItemListComponent, {
+	DragHandle: SortableDragHandle,
+	ItemText: ItemList.ItemText,
+});

package/src/sortable/index.ts

@@ -0,0 +1,8 @@
+export * from "./DropIndicator.js";
+export * from "./SortableItemList.js";
+export * from "./reorderSortOrder.js";
+export * from "./sortOrder.js";
+export * from "./types.js";
+export * from "./useSortableContainer.js";
+export * from "./useSortableItem.js";
+export * from "./useSortableList.js";

package/src/sortable/reorderSortOrder.ts

@@ -0,0 +1,126 @@
+import type { Edge } from "@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge";
+import type { DataObject } from "@olenbetong/appframe-data";
+
+import { DEFAULT_SORT_ORDER_SPACING, ensureNonZeroSortOrder } from "./sortOrder.js";
+import type { SortableRecord } from "./types.js";
+
+function hasDuplicateSortOrders<T extends SortableRecord>(records: T[]) {
+	if (records.length < 2) return false;
+	let values = new Set(records.map((record) => record.SortOrder ?? 0));
+	return values.size !== records.length;
+}
+
+export interface ReorderSortOrderOptions<T extends SortableRecord> {
+	/** Records in their current (sorted) order */
+	records: T[];
+	/** `PrimKey` of the record being moved */
+	sourcePrimKey: string;
+	/** `PrimKey` of the record it is dropped on */
+	targetPrimKey: string;
+	/** Which edge of the target it was dropped on. `"bottom"` places it after the target */
+	edge: Edge | null;
+	/** Spacing used when appending to the end of the list */
+	spacing?: number;
+	/**
+	 * Called when the list contains duplicate sort orders, which means there is
+	 * no free decimal slot to move an item into. Typically executes a stored
+	 * procedure that renumbers the list with even spacing.
+	 */
+	onNormalize?: () => Promise<void>;
+	/** Reloads the records after normalizing. Required for `onNormalize` to have an effect */
+	refreshRecords?: () => Promise<T[]>;
+	/** Data object holding the list records. Updated locally for an optimistic render */
+	listDataObject: DataObject<T>;
+	/** Data object used to persist the new sort order. Defaults to `listDataObject` */
+	updateDataObject: DataObject<any>;
+}
+
+/**
+ * Moves a record to a new position by giving it a sort order between its new
+ * neighbours, normalizing the list first if there is no room left.
+ */
+export async function reorderSortOrder<T extends SortableRecord>({
+	records,
+	sourcePrimKey,
+	targetPrimKey,
+	edge,
+	spacing = DEFAULT_SORT_ORDER_SPACING,
+	onNormalize,
+	refreshRecords,
+	listDataObject,
+	updateDataObject,
+}: ReorderSortOrderOptions<T>) {
+	let currentRecords = records;
+	if (onNormalize && hasDuplicateSortOrders(currentRecords)) {
+		await onNormalize();
+		if (refreshRecords) {
+			currentRecords = await refreshRecords();
+		}
+	}
+
+	let from = currentRecords.findIndex((record) => record.PrimKey === sourcePrimKey);
+	let to = currentRecords.findIndex((record) => record.PrimKey === targetPrimKey);
+	if (from < 0 || to < 0) return;
+
+	let targetIndex = to;
+	if (edge === "bottom") {
+		targetIndex += 1;
+	}
+	if (targetIndex === from) return;
+
+	let existingSortOrders = currentRecords
+		.filter((_, idx) => idx !== from)
+		.map((record) => (record.SortOrder ?? 0) as number);
+
+	let newSort = currentRecords[from].SortOrder ?? spacing;
+	let beforeSort: number | null = null;
+	let afterSort: number | null = null;
+
+	if (targetIndex === 0) {
+		afterSort = currentRecords[0]?.SortOrder ?? null;
+		newSort = afterSort == null ? spacing : afterSort / 2;
+	} else if (targetIndex >= currentRecords.length) {
+		beforeSort = currentRecords[currentRecords.length - 1]?.SortOrder ?? null;
+		newSort = beforeSort == null ? spacing : beforeSort + spacing;
+	} else {
+		beforeSort = currentRecords[targetIndex - 1].SortOrder ?? null;
+		afterSort = currentRecords[targetIndex].SortOrder ?? null;
+		let beforeValue = beforeSort ?? spacing;
+		let afterValue = afterSort ?? spacing;
+		newSort = (beforeValue + afterValue) / 2;
+	}
+
+	newSort = ensureNonZeroSortOrder(newSort, {
+		before: beforeSort,
+		after: afterSort,
+		existing: existingSortOrders,
+		step: spacing,
+	});
+
+	let primKey = currentRecords[from].PrimKey;
+
+	let applyLocalSortOrder = <TRecord extends SortableRecord>(
+		dataObject: DataObject<TRecord>,
+		updated: Partial<TRecord>,
+	) => {
+		if (!updated.PrimKey) return;
+		let index = dataObject.findIndex((record) => record.PrimKey === updated.PrimKey);
+		if (index < 0) return;
+
+		dataObject.updateRow(index, updated);
+	};
+
+	let changes = { PrimKey: primKey, SortOrder: newSort } as Partial<T>;
+	applyLocalSortOrder(listDataObject, changes);
+	if (updateDataObject !== listDataObject) {
+		applyLocalSortOrder(updateDataObject, changes);
+	}
+
+	let updatedRow = await updateDataObject.dataHandler.update(changes);
+	if (updatedRow && typeof updatedRow === "object") {
+		applyLocalSortOrder(listDataObject, updatedRow);
+		if (updateDataObject !== listDataObject) {
+			applyLocalSortOrder(updateDataObject, updatedRow);
+		}
+	}
+}

package/src/sortable/sortOrder.ts

@@ -0,0 +1,101 @@
+export const DEFAULT_SORT_ORDER_SPACING = 128;
+
+export interface EnsureSortOrderOptions {
+	before?: number | null;
+	after?: number | null;
+	existing?: number[];
+	step?: number;
+}
+
+function sanitizeExisting(values: number[] | undefined): number[] {
+	if (!values?.length) {
+		return [];
+	}
+
+	return values.map((value) => (typeof value === "number" && Number.isFinite(value) ? value : 0)).sort((a, b) => a - b);
+}
+
+/**
+ * Zero is treated as "no sort order" by the database, so a computed sort order
+ * of exactly zero must be nudged to a nearby free value.
+ *
+ * @param candidate The computed sort order
+ * @param options Neighbouring and existing sort orders used to find a free slot
+ * @returns A non-zero sort order that keeps the intended position
+ */
+export function ensureNonZeroSortOrder(candidate: number, options: EnsureSortOrderOptions = {}): number {
+	if (candidate !== 0) {
+		return candidate;
+	}
+
+	let { before = null, after = null, existing, step = DEFAULT_SORT_ORDER_SPACING } = options;
+	let sanitizedExisting = sanitizeExisting(existing);
+
+	if (typeof before === "number" && before < 0) {
+		let adjusted = before / 2;
+		let attempts = 0;
+		while ((adjusted === 0 || sanitizedExisting.includes(adjusted)) && attempts < 10) {
+			adjusted /= 2;
+			attempts += 1;
+		}
+
+		if (adjusted !== 0 && !sanitizedExisting.includes(adjusted)) {
+			return adjusted;
+		}
+	}
+
+	if (before == null && typeof after === "number" && after > 0) {
+		let adjusted = -Math.abs(after) / 2;
+		let attempts = 0;
+		while ((adjusted === 0 || sanitizedExisting.includes(adjusted)) && attempts < 10) {
+			adjusted /= 2;
+			attempts += 1;
+		}
+
+		if (adjusted !== 0 && !sanitizedExisting.includes(adjusted)) {
+			return adjusted;
+		}
+	}
+
+	let negativeValues = sanitizedExisting.filter((value) => value < 0);
+	if (negativeValues.length > 0) {
+		let adjusted = negativeValues[negativeValues.length - 1] / 2;
+		let attempts = 0;
+		while ((adjusted === 0 || sanitizedExisting.includes(adjusted)) && attempts < 10) {
+			adjusted /= 2;
+			attempts += 1;
+		}
+
+		if (adjusted !== 0 && !sanitizedExisting.includes(adjusted)) {
+			return adjusted;
+		}
+	}
+
+	let minValue = sanitizedExisting.length ? sanitizedExisting[0] : 0;
+	let adjusted = minValue <= 0 ? minValue - step : -step;
+	while (adjusted === 0 || sanitizedExisting.includes(adjusted)) {
+		adjusted -= step;
+	}
+
+	return adjusted;
+}
+
+/**
+ * Computes the sort order to use for a new item appended to the end of a list.
+ * The next sort order is the highest existing sort order plus the default
+ * spacing, or the default spacing if the list is empty. The result is
+ * guaranteed to be non-zero, since zero is used as "no sort order" in the
+ * database.
+ *
+ * @param existingSortOrders Sort orders of the items already in the list
+ * @returns The sort order to assign to the new item
+ */
+export function getNextSortOrder(existingSortOrders: (number | null | undefined)[]): number {
+	let sortOrders = existingSortOrders
+		.map((value) => (typeof value === "number" && Number.isFinite(value) ? value : 0))
+		.sort((a, b) => a - b);
+	let beforeSort = sortOrders.length > 0 ? sortOrders[sortOrders.length - 1] : null;
+	let newSort = beforeSort == null ? DEFAULT_SORT_ORDER_SPACING : beforeSort + DEFAULT_SORT_ORDER_SPACING;
+
+	return ensureNonZeroSortOrder(newSort, { after: beforeSort, existing: sortOrders });
+}

package/src/sortable/types.ts

@@ -0,0 +1,9 @@
+/**
+ * Minimum shape a record must have to take part in a sortable list.
+ *
+ * `PrimKey` is the `uniqueidentifier` primary key every Appframe table has,
+ * and `SortOrder` is a `decimal(18, 6)` column. Because the sort order is a
+ * decimal, items can be moved by placing them halfway between their new
+ * neighbours instead of renumbering the whole list.
+ */
+export type SortableRecord = { PrimKey: string; SortOrder?: number | null };

package/src/sortable/useSortableContainer.ts

@@ -0,0 +1,53 @@
+import { monitorForElements } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
+import { type Edge, extractClosestEdge } from "@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge";
+import { useEffect, useRef } from "react";
+
+import type { SortableRecord } from "./types.js";
+
+export type SortableDragData<T extends SortableRecord> = { type: string; record: T };
+
+export function isSortableDragData<T extends SortableRecord>(value: any, type: string): value is SortableDragData<T> {
+	return value?.type === type;
+}
+
+export interface UseSortableContainerOptions<T extends SortableRecord> {
+	/** Identifies the list. Only items sharing the same type can be dropped on each other */
+	type: string;
+	enabled?: boolean;
+	onDrop: (args: { source: T; target: T; edge: Edge | null }) => void;
+}
+
+/**
+ * Monitors drops for a sortable list and reports which record was dropped
+ * where. Use together with {@link useSortableItem}.
+ */
+export function useSortableContainer<T extends SortableRecord>({
+	type,
+	enabled = true,
+	onDrop,
+}: UseSortableContainerOptions<T>) {
+	let onDropRef = useRef(onDrop);
+	onDropRef.current = onDrop;
+
+	useEffect(() => {
+		if (!enabled) return;
+
+		return monitorForElements({
+			canMonitor({ source }) {
+				return isSortableDragData<T>(source.data, type);
+			},
+			onDrop({ location, source }) {
+				let target = location.current.dropTargets[0];
+				if (!target) return;
+
+				let sourceData = source.data;
+				let targetData = target.data;
+
+				if (isSortableDragData<T>(sourceData, type) && isSortableDragData<T>(targetData, type)) {
+					let edge = extractClosestEdge(targetData);
+					onDropRef.current({ source: sourceData.record, target: targetData.record, edge });
+				}
+			},
+		});
+	}, [enabled, type]);
+}