wiki-formant 0.30.0 → 0.31.0

package/README.md

@@ -258,6 +258,13 @@ const { query, setQuery, items, highlight, setHighlight, onKeyDown, reset } =
 
 `useLinkPreview` is the Wikipedia-style hover card: one delegated listener rather than a component per link, which is what makes it viable over an article holding hundreds of anchors. Two wikis had written the same ninety lines — same intent delay, same grace period for the cursor to cross into the card, same clamp arithmetic, same cache. They differed in three things, and those three are the options: which anchors are eligible, what fetches a preview, and how tall the card is.
 
+`useSnapRow` is a carousel as a row scrolled sideways under `scroll-snap-type: x mandatory`, so a finger swipes it with no script; AcuiQ's protocol card, which swapped one point for the next in state, could not be swiped at all. The hook is the rest: `step` for arrows and arrow keys, wrapping round at either end, `go(i)` for a dot or for opening a lightbox on the picture clicked, and `at` for the counter. It ships no markup and no class names, since miow's rows hold pictures and AcuiQ's hold whole acupoints.
+
+```tsx
+const { ref, onScroll, at, step, go } = useSnapRow();
+<div ref={ref} onScroll={onScroll} className="row">{items}</div>
+```
+
 `useClickOutside` is fifteen lines and was in all three. Only one had the `offsetParent` check, and without it a container hidden at the current breakpoint still answers outside-clicks — so on a phone, a tap anywhere dismisses the popover the reader is looking at, because the hidden desktop copy got there first.
 
 ### The listbox contract

package/dist/react.d.ts

@@ -349,6 +349,31 @@ export declare function useCopy<K extends string = string>(revertAfter?: number)
     copied: K | null;
     copy: (text: string, key?: K) => Promise<boolean>;
 };
+export interface SnapRow<T extends HTMLElement> {
+    /** The row: give it `overflow-x: auto` and `scroll-snap-type: x mandatory`, and its children `scroll-snap-align: start`. */
+    ref: RefObject<T | null>;
+    /** The row's `onScroll`, which keeps `at` current. */
+    onScroll: () => void;
+    /** The item in view, or the last once the row is scrolled to its end: for a counter or dots. */
+    at: number;
+    /** Most of a view along, as an arrow or an arrow key moves it, wrapping round from either end. */
+    step: (dir: 1 | -1) => void;
+    /** Item `i` to the start of the row, as a dot moves it; `smooth: false` to open on it. */
+    go: (i: number, smooth?: boolean) => void;
+}
+/**
+ * A carousel as a row scrolled sideways and snapping into place. A finger
+ * swipes it with no script at all, which a carousel that swaps one item for
+ * the next in state cannot do: AcuiQ's protocol card moved only by its
+ * buttons. This is the rest, with no markup and no class names, since what the
+ * row holds differs from one use to the next.
+ *
+ * `step` scrolls by most of a view and lets the snap settle it, so a row of
+ * items narrower than itself pages a screenful at a time and a row of full-width
+ * ones moves one. It wraps at either end, because an arrow that does nothing
+ * there reads as broken. Motion honours `prefers-reduced-motion`.
+ */
+export declare function useSnapRow<T extends HTMLElement = HTMLDivElement>(): SnapRow<T>;
 /**
  * The one thing hooks cannot express, so it is worth owning once.
  *

package/dist/react.js

@@ -698,6 +698,52 @@ export function useCopy(revertAfter = 2000) {
     }, [revertAfter]);
     return { copied, copy };
 }
+/**
+ * A carousel as a row scrolled sideways and snapping into place. A finger
+ * swipes it with no script at all, which a carousel that swaps one item for
+ * the next in state cannot do: AcuiQ's protocol card moved only by its
+ * buttons. This is the rest, with no markup and no class names, since what the
+ * row holds differs from one use to the next.
+ *
+ * `step` scrolls by most of a view and lets the snap settle it, so a row of
+ * items narrower than itself pages a screenful at a time and a row of full-width
+ * ones moves one. It wraps at either end, because an arrow that does nothing
+ * there reads as broken. Motion honours `prefers-reduced-motion`.
+ */
+export function useSnapRow() {
+    const ref = useRef(null);
+    const [at, setAt] = useState(0);
+    const onScroll = useCallback(() => {
+        const row = ref.current;
+        if (!row)
+            return;
+        const items = [...row.children];
+        const left = row.getBoundingClientRect().left;
+        const offsets = items.map(el => Math.abs(el.getBoundingClientRect().left - left));
+        setAt(row.scrollLeft >= snapEnd(row) - 1 ? items.length - 1 : offsets.indexOf(Math.min(...offsets)));
+    }, []);
+    const go = useCallback((i, smooth = true) => {
+        const row = ref.current;
+        const n = row?.children.length ?? 0;
+        const el = row?.children[((i % n) + n) % n];
+        if (row && el)
+            snapTo(row, row.scrollLeft + el.getBoundingClientRect().left - row.getBoundingClientRect().left, smooth);
+    }, []);
+    const step = useCallback((dir) => {
+        const row = ref.current;
+        if (!row)
+            return;
+        if (dir > 0 && row.scrollLeft >= snapEnd(row) - 1)
+            snapTo(row, 0);
+        else if (dir < 0 && row.scrollLeft <= 1)
+            snapTo(row, snapEnd(row));
+        else
+            snapTo(row, row.scrollLeft + dir * row.clientWidth * 0.8);
+    }, []);
+    return { ref, onScroll, at, step, go };
+}
+const snapEnd = (row) => row.scrollWidth - row.clientWidth;
+const snapTo = (row, left, smooth = true) => row.scrollTo({ left, behavior: smooth && !matchMedia('(prefers-reduced-motion: reduce)').matches ? 'smooth' : 'auto' });
 // ---- error boundary ---------------------------------------------------------
 /**
  * The one thing hooks cannot express, so it is worth owning once.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, and conditional-GET plumbing.",
   "type": "module",
   "license": "MIT",