@proyecto-viviana/solidaria 0.2.2 → 0.2.4

package/src/dnd/createDroppableItem.ts

@@ -0,0 +1,213 @@
+/**
+ * createDroppableItem - ARIA hook for droppable items within a collection.
+ *
+ * Provides accessibility props for items that can receive drops.
+ */
+
+import { createMemo, type Accessor } from 'solid-js';
+import type { JSX } from 'solid-js';
+import type {
+  DroppableCollectionState,
+  DropTarget,
+  DropOperation,
+} from '@proyecto-viviana/solid-stately';
+import {
+  DragTypesImpl,
+  DROP_OPERATION,
+  DROP_OPERATION_ALLOWED,
+  DROP_OPERATION_TO_DROP_EFFECT,
+  getGlobalAllowedDropOperations,
+} from './utils';
+
+export interface DroppableItemOptions {
+  /** The unique key of the item. */
+  key: string | number;
+  /** Reference to the item element. */
+  ref: Accessor<HTMLElement | null>;
+  /** Whether this item is disabled for dropping. */
+  isDisabled?: boolean;
+}
+
+export interface DroppableItemAria {
+  /** Props for the droppable item element. */
+  dropProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Whether the item is currently a drop target. */
+  isDropTarget: boolean;
+}
+
+/**
+ * Creates ARIA props for a droppable item within a collection.
+ *
+ * @param options - Accessor returning item options
+ * @param state - Droppable collection state
+ * @returns Droppable item ARIA props
+ */
+export function createDroppableItem(
+  options: Accessor<DroppableItemOptions>,
+  state: DroppableCollectionState
+): DroppableItemAria {
+  const getOptions = createMemo(() => options());
+
+  const isDropTarget = createMemo(() => {
+    const { key } = getOptions();
+    const target = state.target;
+    return target?.type === 'item' && target.key === key;
+  });
+
+  const getTarget = (dropPosition: 'before' | 'on' | 'after'): DropTarget => {
+    const { key } = getOptions();
+    return {
+      type: 'item',
+      key,
+      dropPosition,
+    };
+  };
+
+  const getDropOperation = (
+    e: DragEvent,
+    target: DropTarget
+  ): DropOperation => {
+    if (!e.dataTransfer) return 'cancel';
+
+    const types = new DragTypesImpl(e.dataTransfer);
+    let allowedBits =
+      DROP_OPERATION_ALLOWED[e.dataTransfer.effectAllowed] || DROP_OPERATION.all;
+
+    // Use global allowed operations for internal drags
+    const globalAllowed = getGlobalAllowedDropOperations();
+    if (globalAllowed) {
+      allowedBits &= globalAllowed;
+    }
+
+    const allowedOperations: DropOperation[] = [];
+    if (allowedBits & DROP_OPERATION.move) allowedOperations.push('move');
+    if (allowedBits & DROP_OPERATION.copy) allowedOperations.push('copy');
+    if (allowedBits & DROP_OPERATION.link) allowedOperations.push('link');
+
+    return state.getDropOperation(target, types, allowedOperations);
+  };
+
+  let dropActivateTimer: ReturnType<typeof setTimeout> | undefined;
+  const DROP_ACTIVATE_TIMEOUT = 800;
+
+  const onDragEnter = (e: DragEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+
+    const opts = getOptions();
+    if (opts.isDisabled) return;
+
+    // Determine drop position based on cursor position
+    const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
+    const y = e.clientY - rect.y;
+    const height = rect.height;
+
+    let dropPosition: 'before' | 'on' | 'after';
+    if (y < height * 0.25) {
+      dropPosition = 'before';
+    } else if (y > height * 0.75) {
+      dropPosition = 'after';
+    } else {
+      dropPosition = 'on';
+    }
+
+    const target = getTarget(dropPosition);
+    const operation = getDropOperation(e, target);
+
+    if (operation !== 'cancel') {
+      state.setTarget(target);
+      e.dataTransfer!.dropEffect = DROP_OPERATION_TO_DROP_EFFECT[operation] as DataTransfer['dropEffect'];
+    }
+  };
+
+  const onDragOver = (e: DragEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+
+    const opts = getOptions();
+    if (opts.isDisabled) return;
+
+    // Update drop position based on cursor
+    const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
+    const y = e.clientY - rect.y;
+    const height = rect.height;
+
+    let dropPosition: 'before' | 'on' | 'after';
+    if (y < height * 0.25) {
+      dropPosition = 'before';
+    } else if (y > height * 0.75) {
+      dropPosition = 'after';
+    } else {
+      dropPosition = 'on';
+    }
+
+    const target = getTarget(dropPosition);
+    const operation = getDropOperation(e, target);
+
+    if (operation !== 'cancel') {
+      state.setTarget(target);
+      e.dataTransfer!.dropEffect = DROP_OPERATION_TO_DROP_EFFECT[operation] as DataTransfer['dropEffect'];
+
+      // Handle drop activate for 'on' position
+      clearTimeout(dropActivateTimer);
+      if (dropPosition === 'on') {
+        dropActivateTimer = setTimeout(() => {
+          // Would trigger onDropActivate
+        }, DROP_ACTIVATE_TIMEOUT);
+      }
+    } else {
+      e.dataTransfer!.dropEffect = 'none';
+    }
+  };
+
+  const onDragLeave = (e: DragEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+
+    clearTimeout(dropActivateTimer);
+
+    // Only clear target if leaving this item
+    const relatedTarget = e.relatedTarget as HTMLElement | null;
+    const currentTarget = e.currentTarget as HTMLElement;
+    if (!relatedTarget || !currentTarget.contains(relatedTarget)) {
+      // Clear if no longer over this item
+      const { key } = getOptions();
+      if (state.target?.type === 'item' && state.target.key === key) {
+        // State clearing handled by parent collection
+      }
+    }
+  };
+
+  const onDrop = (e: DragEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+
+    clearTimeout(dropActivateTimer);
+
+    // Drop handling is done by the parent collection
+  };
+
+  const dropProps = createMemo(() => {
+    const opts = getOptions();
+
+    if (opts.isDisabled) {
+      return {};
+    }
+
+    return {
+      onDragEnter,
+      onDragOver,
+      onDragLeave,
+      onDrop,
+    };
+  });
+
+  return {
+    get dropProps() {
+      return dropProps() as DroppableItemAria['dropProps'];
+    },
+    get isDropTarget() {
+      return isDropTarget();
+    },
+  };
+}

package/src/dnd/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Drag and Drop module for solidaria.
+ *
+ * Provides ARIA hooks for drag and drop interactions.
+ */
+
+// Basic drag/drop hooks
+export { createDrag } from './createDrag';
+export { createDrop } from './createDrop';
+
+// Collection hooks
+export { createDraggableCollection, setGlobalDraggingCollectionRef, getGlobalDraggingCollectionRef } from './createDraggableCollection';
+export { createDroppableCollection, setGlobalDropCollectionRef, getGlobalDropCollectionRef } from './createDroppableCollection';
+
+// Item hooks
+export { createDraggableItem } from './createDraggableItem';
+export { createDroppableItem } from './createDroppableItem';
+
+// Types
+export type { AriaDragOptions, DragAria, AriaDropOptions, DropAria } from './types';
+export type { DraggableCollectionOptions, DraggableCollectionAria } from './createDraggableCollection';
+export type { DroppableCollectionOptions, DroppableCollectionAria, DropTargetDelegate } from './createDroppableCollection';
+export type { DraggableItemOptions, DraggableItemAria } from './createDraggableItem';
+export type { DroppableItemOptions, DroppableItemAria } from './createDroppableItem';
+
+// Utilities
+export {
+  CUSTOM_DRAG_TYPE,
+  NATIVE_DRAG_TYPES,
+  GENERIC_TYPE,
+  DROP_OPERATION,
+  DROP_OPERATION_ALLOWED,
+  EFFECT_ALLOWED,
+  DROP_EFFECT_TO_DROP_OPERATION,
+  DROP_OPERATION_TO_DROP_EFFECT,
+  getTypes,
+  writeToDataTransfer,
+  readFromDataTransfer,
+  DragTypesImpl,
+  isTextDropItem,
+  isFileDropItem,
+  isDirectoryDropItem,
+  setGlobalDropEffect,
+  getGlobalDropEffect,
+  setGlobalAllowedDropOperations,
+  getGlobalAllowedDropOperations,
+} from './utils';

package/src/dnd/types.ts

@@ -0,0 +1,89 @@
+/**
+ * Drag and Drop ARIA types for solidaria.
+ */
+
+import type { JSX } from 'solid-js';
+import type {
+  DragItem,
+  DragStartEvent,
+  DragMoveEvent,
+  DragEndEvent,
+  DropEnterEvent,
+  DropMoveEvent,
+  DropActivateEvent,
+  DropExitEvent,
+  DropEvent,
+  DropOperation,
+  DragTypes,
+  DragPreviewRenderer,
+} from '@proyecto-viviana/solid-stately';
+
+export interface AriaDragOptions {
+  /** A function that returns the items being dragged. */
+  getItems: () => DragItem[];
+  /** Function that returns the allowed drop operations. */
+  getAllowedDropOperations?: () => DropOperation[];
+  /** Handler that is called when a drag operation is started. */
+  onDragStart?: (e: DragStartEvent) => void;
+  /** Handler that is called when the drag is moved. */
+  onDragMove?: (e: DragMoveEvent) => void;
+  /** Handler that is called when the drag operation ends. */
+  onDragEnd?: (e: DragEndEvent) => void;
+  /** Whether there is a separate drag button affordance. */
+  hasDragButton?: boolean;
+  /** Whether the drag operation is disabled. */
+  isDisabled?: boolean;
+  /** Preview renderer function ref. */
+  preview?: { current: DragPreviewRenderer | null };
+}
+
+export interface DragAria {
+  /** Props for the draggable element. */
+  dragProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the explicit drag button affordance, if any. */
+  dragButtonProps: JSX.ButtonHTMLAttributes<HTMLButtonElement>;
+  /** Whether the element is currently being dragged. */
+  isDragging: boolean;
+}
+
+export interface AriaDropOptions {
+  /**
+   * A function returning the drop operation to be performed.
+   */
+  getDropOperation?: (
+    types: DragTypes,
+    allowedOperations: DropOperation[]
+  ) => DropOperation;
+  /**
+   * A function returning the drop operation for a specific point.
+   */
+  getDropOperationForPoint?: (
+    types: DragTypes,
+    allowedOperations: DropOperation[],
+    x: number,
+    y: number
+  ) => DropOperation;
+  /** Handler that is called when a valid drag enters the drop target. */
+  onDropEnter?: (e: DropEnterEvent) => void;
+  /** Handler that is called when a valid drag is moved within the drop target. */
+  onDropMove?: (e: DropMoveEvent) => void;
+  /** Handler that is called after a valid drag is held over the drop target. */
+  onDropActivate?: (e: DropActivateEvent) => void;
+  /** Handler that is called when a valid drag exits the drop target. */
+  onDropExit?: (e: DropExitEvent) => void;
+  /** Handler that is called when a valid drag is dropped on the drop target. */
+  onDrop?: (e: DropEvent) => void;
+  /** Whether there is a separate drop button affordance. */
+  hasDropButton?: boolean;
+  /** Whether the drop target is disabled. */
+  isDisabled?: boolean;
+}
+
+export interface DropAria {
+  /** Props for the droppable element. */
+  dropProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Whether the drop target is currently being hovered or focused. */
+  isDropTarget: boolean;
+  /** Props for the explicit drop button affordance, if any. */
+  dropButtonProps: JSX.ButtonHTMLAttributes<HTMLButtonElement>;
+}

package/src/dnd/utils.ts

@@ -0,0 +1,294 @@
+/**
+ * Drag and Drop utilities for solidaria.
+ */
+
+import type {
+  DragItem,
+  DropItem,
+  TextDropItem,
+  FileDropItem,
+  DirectoryDropItem,
+  DropOperation,
+} from '@proyecto-viviana/solid-stately';
+
+// Native drag types that can be transferred between applications
+export const NATIVE_DRAG_TYPES: Set<string> = new Set([
+  'text/plain',
+  'text/uri-list',
+  'text/html',
+]);
+
+// Custom drag type for serializing multiple items
+export const CUSTOM_DRAG_TYPE = 'application/vnd.solidaria.items+json';
+
+// Generic type for unknown file types
+export const GENERIC_TYPE = 'application/octet-stream';
+
+// Drop operation bit flags
+export enum DROP_OPERATION {
+  none = 0,
+  cancel = 0,
+  move = 1 << 0,
+  copy = 1 << 1,
+  link = 1 << 2,
+  all = (1 << 0) | (1 << 1) | (1 << 2),
+}
+
+// Map from effectAllowed to DROP_OPERATION
+export const DROP_OPERATION_ALLOWED: Record<string, number> = {
+  none: DROP_OPERATION.none,
+  copy: DROP_OPERATION.copy,
+  copyLink: DROP_OPERATION.copy | DROP_OPERATION.link,
+  copyMove: DROP_OPERATION.copy | DROP_OPERATION.move,
+  link: DROP_OPERATION.link,
+  linkMove: DROP_OPERATION.link | DROP_OPERATION.move,
+  move: DROP_OPERATION.move,
+  all: DROP_OPERATION.all,
+  uninitialized: DROP_OPERATION.all,
+};
+
+// Map from DROP_OPERATION to effectAllowed
+export const EFFECT_ALLOWED: Record<number, string> = {
+  [DROP_OPERATION.none]: 'none',
+  [DROP_OPERATION.move]: 'move',
+  [DROP_OPERATION.copy]: 'copy',
+  [DROP_OPERATION.copy | DROP_OPERATION.move]: 'copyMove',
+  [DROP_OPERATION.link]: 'link',
+  [DROP_OPERATION.link | DROP_OPERATION.move]: 'linkMove',
+  [DROP_OPERATION.copy | DROP_OPERATION.link]: 'copyLink',
+  [DROP_OPERATION.all]: 'all',
+};
+
+// Map from dropEffect to DropOperation
+export const DROP_EFFECT_TO_DROP_OPERATION: Record<string, DropOperation> = {
+  none: 'cancel',
+  link: 'link',
+  copy: 'copy',
+  move: 'move',
+};
+
+// Map from DropOperation to dropEffect
+export const DROP_OPERATION_TO_DROP_EFFECT: Record<DropOperation, string> = {
+  cancel: 'none',
+  link: 'link',
+  copy: 'copy',
+  move: 'move',
+};
+
+/**
+ * Get the types present in drag items.
+ */
+export function getTypes(items: DragItem[]): Set<string> {
+  const types = new Set<string>();
+  for (const item of items) {
+    for (const type of Object.keys(item)) {
+      types.add(type);
+    }
+  }
+  return types;
+}
+
+/**
+ * Write drag items to a DataTransfer object.
+ */
+export function writeToDataTransfer(
+  dataTransfer: DataTransfer,
+  items: DragItem[]
+): void {
+  const groupedByType = new Map<string, string[]>();
+  let needsCustomData = false;
+  const customData: object[] = [];
+
+  for (const item of items) {
+    const types = Object.keys(item);
+    if (types.length > 1) {
+      needsCustomData = true;
+    }
+
+    const dataByType: Record<string, string> = {};
+    for (const type of types) {
+      let typeItems = groupedByType.get(type);
+      if (!typeItems) {
+        typeItems = [];
+        groupedByType.set(type, typeItems);
+      } else {
+        needsCustomData = true;
+      }
+
+      const data = item[type];
+      dataByType[type] = data;
+      typeItems.push(data);
+    }
+
+    customData.push(dataByType);
+  }
+
+  for (const [type, typeItems] of groupedByType) {
+    if (NATIVE_DRAG_TYPES.has(type)) {
+      // Join all items of this type with newlines
+      const data = typeItems.join('\n');
+      dataTransfer.items.add(data, type);
+    } else {
+      // Set first item for non-native types
+      dataTransfer.items.add(typeItems[0], type);
+    }
+  }
+
+  if (needsCustomData) {
+    const data = JSON.stringify(customData);
+    dataTransfer.items.add(data, CUSTOM_DRAG_TYPE);
+  }
+}
+
+/**
+ * Read drop items from a DataTransfer object.
+ */
+export function readFromDataTransfer(dataTransfer: DataTransfer): DropItem[] {
+  const items: DropItem[] = [];
+
+  if (!dataTransfer) {
+    return items;
+  }
+
+  // Check for custom drag type first
+  let hasCustomType = false;
+  if (dataTransfer.types.includes(CUSTOM_DRAG_TYPE)) {
+    try {
+      const data = dataTransfer.getData(CUSTOM_DRAG_TYPE);
+      const parsed = JSON.parse(data);
+      for (const item of parsed) {
+        items.push({
+          kind: 'text',
+          types: new Set(Object.keys(item)),
+          getText: (type) => Promise.resolve(item[type]),
+        });
+      }
+      hasCustomType = true;
+    } catch {
+      // ignore parsing errors
+    }
+  }
+
+  // Fall back to native items
+  if (!hasCustomType) {
+    const stringItems = new Map<string, string>();
+
+    for (const item of dataTransfer.items) {
+      if (item.kind === 'string') {
+        const type = item.type || GENERIC_TYPE;
+        stringItems.set(type, dataTransfer.getData(item.type));
+      } else if (item.kind === 'file') {
+        const file = item.getAsFile();
+        if (file) {
+          items.push(createFileItem(file));
+        }
+      }
+    }
+
+    if (stringItems.size > 0) {
+      items.push({
+        kind: 'text',
+        types: new Set(stringItems.keys()),
+        getText: (type) => Promise.resolve(stringItems.get(type) ?? ''),
+      });
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Create a FileDropItem from a File object.
+ */
+function createFileItem(file: File): FileDropItem {
+  return {
+    kind: 'file',
+    type: file.type || GENERIC_TYPE,
+    name: file.name,
+    getText: () => file.text(),
+    getFile: () => Promise.resolve(file),
+  };
+}
+
+/**
+ * DragTypes implementation for checking drag types.
+ */
+export class DragTypesImpl {
+  private types: Set<string>;
+  private includesUnknownTypes: boolean;
+
+  constructor(dataTransfer: DataTransfer) {
+    this.types = new Set<string>();
+    let hasFiles = false;
+
+    for (const item of dataTransfer.items) {
+      if (item.type !== CUSTOM_DRAG_TYPE) {
+        if (item.kind === 'file') {
+          hasFiles = true;
+        }
+        if (item.type) {
+          this.types.add(item.type);
+        } else {
+          this.types.add(GENERIC_TYPE);
+        }
+      }
+    }
+
+    // Safari doesn't expose file types until drop
+    this.includesUnknownTypes =
+      !hasFiles && dataTransfer.types.includes('Files');
+  }
+
+  has(type: string | symbol): boolean {
+    if (
+      this.includesUnknownTypes ||
+      (typeof type === 'symbol' && this.types.has(GENERIC_TYPE))
+    ) {
+      return true;
+    }
+    return typeof type === 'string' && this.types.has(type);
+  }
+}
+
+/**
+ * Check if a drop item is a text item.
+ */
+export function isTextDropItem(dropItem: DropItem): dropItem is TextDropItem {
+  return dropItem.kind === 'text';
+}
+
+/**
+ * Check if a drop item is a file item.
+ */
+export function isFileDropItem(dropItem: DropItem): dropItem is FileDropItem {
+  return dropItem.kind === 'file';
+}
+
+/**
+ * Check if a drop item is a directory item.
+ */
+export function isDirectoryDropItem(
+  dropItem: DropItem
+): dropItem is DirectoryDropItem {
+  return dropItem.kind === 'directory';
+}
+
+// Global state for tracking drag operations
+let globalDropEffect: string | undefined;
+let globalAllowedDropOperations: number = DROP_OPERATION.none;
+
+export function setGlobalDropEffect(effect: string | undefined): void {
+  globalDropEffect = effect;
+}
+
+export function getGlobalDropEffect(): string | undefined {
+  return globalDropEffect;
+}
+
+export function setGlobalAllowedDropOperations(ops: number): void {
+  globalAllowedDropOperations = ops;
+}
+
+export function getGlobalAllowedDropOperations(): number {
+  return globalAllowedDropOperations;
+}