@flamingo-stack/openframe-frontend-core 0.0.578 → 0.0.579-1956.5350.1

package/src/hooks/ui/.use-drag-and-drop-enabled.md

@@ -0,0 +1,32 @@
+<!-- source-hash: manual -->
+The one rule for whether drag-and-drop is initialized anywhere in the UI. `SortableList` and
+`Board` consume it themselves, so hosts get correct touch behavior without wiring anything.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `useDragAndDropEnabled` | Hook | `true` only when `(pointer: fine) and (hover: hover) and (min-width: 800px)` matches |
+| `DRAG_AND_DROP_MEDIA_QUERY` | Const | The query itself, composed from `breakpoints.md` — no new breakpoint |
+
+## Why pointer type AND breakpoint
+
+- A breakpoint alone fails on tablets: an iPad in landscape is 1024-1366px wide and would pass any
+  sane `min-width` — exactly the case being excluded, because the HTML5 drag-and-drop API Pragmatic
+  builds on does not fire under touch.
+- `pointer: coarse` alone fails the other way: a touchscreen laptop with a trackpad reports
+  `pointer: fine` and should keep DnD, but in a narrow window its lists collapse to the mobile
+  layout where a drag handle is out of place.
+- No `'ontouchstart' in window`, no UA sniffing: the first is true on touch laptops, the second is
+  neither accurate nor reactive. A media query re-evaluates live when a mouse is attached or the
+  window resizes.
+
+## SSR
+
+Returns `false` during SSR and the first client render (`useMediaQuery` is still `undefined`):
+DnD off means no dead drag handle in server HTML, and the layout effect settles the real answer
+before first paint, so a desktop user never sees the touch fallback flash.
+
+## Source
+
+[`use-drag-and-drop-enabled.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-drag-and-drop-enabled.ts)

package/src/hooks/ui/index.ts

@@ -2,6 +2,7 @@
 export * from './use-auto-limit-tags';
 export * from './use-debounce';
 export * from './use-deferred-error';
+export * from './use-drag-and-drop-enabled';
 export * from './use-focus-trap';
 export * from './use-header-height';
 export * from './use-horizontal-scrollbar';

package/src/hooks/ui/use-drag-and-drop-enabled.ts

@@ -0,0 +1,37 @@
+'use client';
+
+import { breakpoints, useMediaQuery } from './use-media-query';
+
+/**
+ * The one rule for whether drag-and-drop is initialized at all.
+ *
+ * Pointer type AND breakpoint, never either alone:
+ * - A breakpoint alone fails on tablets: an iPad in landscape is 1024-1366px
+ *   wide and would pass any sane `min-width` — exactly the case being excluded,
+ *   because the HTML5 drag-and-drop API Pragmatic builds on does not fire under
+ *   touch.
+ * - `pointer: coarse` alone fails the other way: a touchscreen laptop with a
+ *   trackpad reports `pointer: fine` and should keep DnD, but in a narrow
+ *   window its lists collapse to the mobile layout where a drag handle is out
+ *   of place.
+ * - No `'ontouchstart' in window`, no UA sniffing: the first is true on touch
+ *   laptops, the second is neither accurate nor reactive. A media query
+ *   re-evaluates live when a mouse is attached or the window resizes.
+ *
+ * `breakpoints.md` (800px) is the existing tablet step — no new breakpoint.
+ */
+export const DRAG_AND_DROP_MEDIA_QUERY = `(pointer: fine) and (hover: hover) and ${breakpoints.md}`;
+
+/**
+ * Whether drag-and-drop should be available on this device/viewport.
+ *
+ * `false` on touch/narrow screens — there the reordering surfaces render
+ * explicit controls (`SortableMoveButtons`) instead of a drag handle, and no
+ * DnD is initialized at all. Also `false` during SSR and the first client
+ * render (`useMediaQuery` is still `undefined`): defaulting to "off" renders
+ * no dead drag handle, and the underlying layout effect settles the real
+ * answer before first paint, so a desktop user never sees the fallback flash.
+ */
+export function useDragAndDropEnabled(): boolean {
+  return useMediaQuery(DRAG_AND_DROP_MEDIA_QUERY) ?? false;
+}

package/src/hooks/ui/use-media-query.ts

@@ -1,6 +1,7 @@
 'use client';
 
-import { useLayoutEffect, useState } from 'react';
+import { useState } from 'react';
+import { useIsomorphicLayoutEffect } from './use-isomorphic-layout-effect';
 
 /**
  * Hook to check if a media query matches
@@ -10,7 +11,7 @@ import { useLayoutEffect, useState } from 'react';
 export function useMediaQuery(query: string): boolean | undefined {
   const [matches, setMatches] = useState<boolean | undefined>(undefined);
 
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     const matchMedia = window.matchMedia(query);
 
     const handleChange = () => {