drift-slider-react 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# drift-slider-react
+
+Official React wrapper for [DriftSlider](https://github.com/hanfour/drift-slider).
+
+## Install
+
+```bash
+npm i drift-slider drift-slider-react
+```
+
+## Usage
+
+```tsx
+'use client';
+import { DriftSlider, Slide } from 'drift-slider-react';
+import { Navigation, Pagination } from 'drift-slider/modules';
+import 'drift-slider/css/bundle';
+
+export function Carousel() {
+  return (
+    <DriftSlider
+      options={{ loop: true, navigation: true, pagination: true }}
+      modules={[Navigation, Pagination]}
+      onSlideChange={(s) => console.log(s.realIndex)}
+    >
+      <Slide>Slide 1</Slide>
+      <Slide>Slide 2</Slide>
+    </DriftSlider>
+  );
+}
+```
+
+### Imperative control (ref)
+
+```tsx
+const ref = useRef<DriftSliderHandle>(null);
+// ref.current.slideNext(); ref.current.slideTo(2); ref.current.update();
+<DriftSlider ref={ref}>…</DriftSlider>
+```
+
+### Headless hook
+
+```tsx
+const [containerRef] = useDriftSlider({ loop: true });
+return <div className="drift-slider" ref={containerRef}>…your scaffold…</div>;
+```
+
+## Notes
+
+- SSR-safe: the slider initialises in `useEffect` (client only); add `'use client'` in Next.js App Router.
+- Slides should carry stable `key`s; changing the key set re-runs `update()`.
+- Dynamic per-slide add/remove without recompute is not supported (use `ref.update()`).
+- Memoize `options` and `modules` (e.g. with `useMemo`) — the slider re-initialises when their identity changes, and an inline `{}`/`[]` literal changes every render, which would tear down and recreate the slider (and drop event handlers between renders).

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import * as react from 'react';
+import { CSSProperties, ReactNode, LiHTMLAttributes } from 'react';
+import CoreDriftSlider, { DriftSliderEvents, DriftSliderOptions, DriftSliderModule } from 'drift-slider';
+
+declare function cx(...parts: Array<string | false | undefined>): string;
+interface SlideProps extends LiHTMLAttributes<HTMLLIElement> {
+    children?: ReactNode;
+}
+declare function Slide({ className, children, ...rest }: SlideProps): react.JSX.Element;
+declare function useDriftSlider(options?: DriftSliderOptions, deps?: unknown[]): readonly [react.RefObject<HTMLDivElement>, react.MutableRefObject<CoreDriftSlider | null>];
+interface DriftSliderHandle {
+    slideTo: (...args: Parameters<CoreDriftSlider['slideTo']>) => CoreDriftSlider | undefined;
+    slideNext: (...args: Parameters<CoreDriftSlider['slideNext']>) => CoreDriftSlider | undefined;
+    slidePrev: (...args: Parameters<CoreDriftSlider['slidePrev']>) => CoreDriftSlider | undefined;
+    update: () => void;
+    instance: CoreDriftSlider | null;
+}
+type EventShortcuts = {
+    onInit?: DriftSliderEvents['init'];
+    onSlideChange?: DriftSliderEvents['slideChange'];
+    onReachBeginning?: DriftSliderEvents['reachBeginning'];
+    onReachEnd?: DriftSliderEvents['reachEnd'];
+    onTouchStart?: DriftSliderEvents['touchStart'];
+    onTouchEnd?: DriftSliderEvents['touchEnd'];
+};
+interface DriftSliderProps extends EventShortcuts {
+    options?: DriftSliderOptions;
+    modules?: DriftSliderModule[];
+    on?: Partial<DriftSliderEvents>;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+declare const DriftSlider: react.ForwardRefExoticComponent<DriftSliderProps & react.RefAttributes<DriftSliderHandle>>;
+
+export { DriftSlider, type DriftSliderHandle, type DriftSliderProps, Slide, type SlideProps, cx, DriftSlider as default, useDriftSlider };

package/dist/index.js

@@ -0,0 +1,99 @@
+'use client';
+
+// src/index.tsx
+import { useEffect, useImperativeHandle, useRef, forwardRef, Children, isValidElement } from "react";
+import CoreDriftSlider from "drift-slider";
+import { jsx } from "react/jsx-runtime";
+function cx(...parts) {
+  return parts.filter(Boolean).join(" ");
+}
+function childrenKeys(children) {
+  return Children.toArray(children).map((c, i) => isValidElement(c) && c.key != null ? String(c.key) : `__i${i}`).join("|");
+}
+function Slide({ className, children, ...rest }) {
+  return /* @__PURE__ */ jsx("li", { className: cx("drift-slide", className), ...rest, children });
+}
+function useDriftSlider(options, deps = []) {
+  const containerRef = useRef(null);
+  const sliderRef = useRef(null);
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const slider = new CoreDriftSlider(el, options);
+    sliderRef.current = slider;
+    return () => {
+      slider.destroy();
+      sliderRef.current = null;
+    };
+  }, deps);
+  return [containerRef, sliderRef];
+}
+var SHORTCUTS = {
+  onInit: "init",
+  onSlideChange: "slideChange",
+  onReachBeginning: "reachBeginning",
+  onReachEnd: "reachEnd",
+  onTouchStart: "touchStart",
+  onTouchEnd: "touchEnd"
+};
+function collectHandlers(optionsOn, onProp, shortcuts) {
+  const handlers = { ...optionsOn, ...onProp };
+  Object.keys(SHORTCUTS).forEach((key) => {
+    const handler = shortcuts[key];
+    if (handler) handlers[SHORTCUTS[key]] = handler;
+  });
+  return handlers;
+}
+function forwardEvents(handlers, handlersRef) {
+  const on = {};
+  (/* @__PURE__ */ new Set([...Object.values(SHORTCUTS), ...Object.keys(handlers)])).forEach((name) => {
+    on[name] = (...args) => {
+      const map = handlersRef.current;
+      map[name]?.(...args);
+    };
+  });
+  return on;
+}
+var DriftSlider = forwardRef(
+  function DriftSlider2(props, ref) {
+    const { options, modules, on, className, style, children, ...shortcuts } = props;
+    const handlers = collectHandlers(options?.on, on, shortcuts);
+    const handlersRef = useRef(handlers);
+    useEffect(() => {
+      handlersRef.current = handlers;
+    });
+    const sliderOptions = {
+      ...options,
+      modules: [...options?.modules ?? [], ...modules ?? []],
+      on: forwardEvents(handlers, handlersRef)
+    };
+    const [containerRef, sliderRef] = useDriftSlider(sliderOptions, [options, modules]);
+    const keySig = childrenKeys(children);
+    const didMount = useRef(false);
+    useEffect(() => {
+      if (!didMount.current) {
+        didMount.current = true;
+        return;
+      }
+      sliderRef.current?.update();
+    }, [keySig]);
+    useImperativeHandle(ref, () => ({
+      slideTo: (...args) => sliderRef.current?.slideTo(...args),
+      slideNext: (...args) => sliderRef.current?.slideNext(...args),
+      slidePrev: (...args) => sliderRef.current?.slidePrev(...args),
+      update: () => sliderRef.current?.update(),
+      get instance() {
+        return sliderRef.current;
+      }
+    }), [sliderRef]);
+    return /* @__PURE__ */ jsx("div", { className: cx("drift-slider", className), style, ref: containerRef, children: /* @__PURE__ */ jsx("div", { className: "drift-track", children: /* @__PURE__ */ jsx("ul", { className: "drift-list", children }) }) });
+  }
+);
+var index_default = DriftSlider;
+export {
+  DriftSlider,
+  Slide,
+  cx,
+  index_default as default,
+  useDriftSlider
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "drift-slider-react",
+  "version": "0.1.0",
+  "description": "Official React wrapper for DriftSlider",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "files": ["dist", "src"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "drift-slider": ">=0.7.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "drift-slider": "*",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.0",
+    "jsdom": "^29.0.0"
+  },
+  "keywords": ["react", "slider", "carousel", "drift-slider"],
+  "license": "MIT"
+}

package/src/index.tsx

@@ -0,0 +1,172 @@
+import { useEffect, useImperativeHandle, useRef, forwardRef, Children, isValidElement } from 'react';
+import type { CSSProperties, LiHTMLAttributes, ReactNode } from 'react';
+import CoreDriftSlider, {
+  type DriftSliderOptions,
+  type DriftSliderModule,
+  type DriftSliderEvents,
+} from 'drift-slider';
+
+export function cx(...parts: Array<string | false | undefined>): string {
+  return parts.filter(Boolean).join(' ');
+}
+
+function childrenKeys(children: ReactNode): string {
+  return Children.toArray(children)
+    .map((c, i) => (isValidElement(c) && c.key != null ? String(c.key) : `__i${i}`))
+    .join('|');
+}
+
+export interface SlideProps extends LiHTMLAttributes<HTMLLIElement> {
+  children?: ReactNode;
+}
+
+export function Slide({ className, children, ...rest }: SlideProps) {
+  return (
+    <li className={cx('drift-slide', className)} {...rest}>
+      {children}
+    </li>
+  );
+}
+
+export function useDriftSlider(
+  options?: DriftSliderOptions,
+  deps: unknown[] = [],
+) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const sliderRef = useRef<CoreDriftSlider | null>(null);
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const slider = new CoreDriftSlider(el, options);
+    sliderRef.current = slider;
+    return () => {
+      slider.destroy();
+      sliderRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+
+  return [containerRef, sliderRef] as const;
+}
+
+export interface DriftSliderHandle {
+  slideTo: (...args: Parameters<CoreDriftSlider['slideTo']>) => CoreDriftSlider | undefined;
+  slideNext: (...args: Parameters<CoreDriftSlider['slideNext']>) => CoreDriftSlider | undefined;
+  slidePrev: (...args: Parameters<CoreDriftSlider['slidePrev']>) => CoreDriftSlider | undefined;
+  update: () => void;
+  instance: CoreDriftSlider | null;
+}
+
+type EventShortcuts = {
+  onInit?: DriftSliderEvents['init'];
+  onSlideChange?: DriftSliderEvents['slideChange'];
+  onReachBeginning?: DriftSliderEvents['reachBeginning'];
+  onReachEnd?: DriftSliderEvents['reachEnd'];
+  onTouchStart?: DriftSliderEvents['touchStart'];
+  onTouchEnd?: DriftSliderEvents['touchEnd'];
+};
+
+const SHORTCUTS: Record<keyof EventShortcuts, keyof DriftSliderEvents> = {
+  onInit: 'init',
+  onSlideChange: 'slideChange',
+  onReachBeginning: 'reachBeginning',
+  onReachEnd: 'reachEnd',
+  onTouchStart: 'touchStart',
+  onTouchEnd: 'touchEnd',
+};
+
+// Merge `options.on`, the `on` prop, and the shortcut props into one event map.
+function collectHandlers(
+  optionsOn: Partial<DriftSliderEvents> | undefined,
+  onProp: Partial<DriftSliderEvents> | undefined,
+  shortcuts: EventShortcuts,
+): Partial<DriftSliderEvents> {
+  const handlers: Partial<DriftSliderEvents> = { ...optionsOn, ...onProp };
+  (Object.keys(SHORTCUTS) as (keyof EventShortcuts)[]).forEach((key) => {
+    const handler = shortcuts[key];
+    if (handler) (handlers as Record<string, unknown>)[SHORTCUTS[key]] = handler;
+  });
+  return handlers;
+}
+
+// Build a stable `on` map whose forwarders read the latest handler from the ref
+// on each emit — so changing a handler prop takes effect without re-init. Covers
+// the shortcut events plus any keys present on the handler map.
+function forwardEvents(
+  handlers: Partial<DriftSliderEvents>,
+  handlersRef: { current: Partial<DriftSliderEvents> },
+): Partial<DriftSliderEvents> {
+  const on: Record<string, (...args: unknown[]) => void> = {};
+  new Set<string>([...Object.values(SHORTCUTS), ...Object.keys(handlers)]).forEach((name) => {
+    on[name] = (...args) => {
+      const map = handlersRef.current as Record<string, ((...a: unknown[]) => void) | undefined>;
+      map[name]?.(...args);
+    };
+  });
+  return on as Partial<DriftSliderEvents>;
+}
+
+export interface DriftSliderProps extends EventShortcuts {
+  options?: DriftSliderOptions;
+  modules?: DriftSliderModule[];
+  on?: Partial<DriftSliderEvents>;
+  className?: string;
+  style?: CSSProperties;
+  children?: ReactNode;
+}
+
+export const DriftSlider = forwardRef<DriftSliderHandle, DriftSliderProps>(
+  function DriftSlider(props, ref) {
+    const { options, modules, on, className, style, children, ...shortcuts } = props;
+
+    // Keep the latest handlers in a ref so changing a handler prop takes effect
+    // without tearing the slider down and recreating it.
+    const handlers = collectHandlers(options?.on, on, shortcuts as EventShortcuts);
+    const handlersRef = useRef(handlers);
+    useEffect(() => {
+      handlersRef.current = handlers;
+    });
+
+    const sliderOptions: DriftSliderOptions = {
+      ...options,
+      modules: [...(options?.modules ?? []), ...(modules ?? [])],
+      on: forwardEvents(handlers, handlersRef),
+    };
+
+    // Compose the lifecycle from the shared hook; re-init only when
+    // options/modules identity changes.
+    const [containerRef, sliderRef] = useDriftSlider(sliderOptions, [options, modules]);
+
+    // Recompute on children key-set changes (skip the initial mount).
+    const keySig = childrenKeys(children);
+    const didMount = useRef(false);
+    useEffect(() => {
+      if (!didMount.current) {
+        didMount.current = true;
+        return; // initial render already built the right DOM
+      }
+      sliderRef.current?.update();
+    }, [keySig]);
+
+    useImperativeHandle(ref, () => ({
+      slideTo: (...args) => sliderRef.current?.slideTo(...args),
+      slideNext: (...args) => sliderRef.current?.slideNext(...args),
+      slidePrev: (...args) => sliderRef.current?.slidePrev(...args),
+      update: () => sliderRef.current?.update(),
+      get instance() {
+        return sliderRef.current;
+      },
+    }), [sliderRef]);
+
+    return (
+      <div className={cx('drift-slider', className)} style={style} ref={containerRef}>
+        <div className="drift-track">
+          <ul className="drift-list">{children}</ul>
+        </div>
+      </div>
+    );
+  },
+);
+
+export default DriftSlider;