@ncdai/react-wheel-picker 1.0.0 → 1.0.2

package/README.md

@@ -1,3 +1,153 @@
-# react-wheel-picker
+# React Wheel Picker
 
 iOS-like wheel picker for React with smooth inertia scrolling and infinite loop support.
+
+Check out the live demo: [react-wheel-picker.chanhdai.com](https://react-wheel-picker.chanhdai.com)
+
+## Installation
+
+```bash
+pnpm add @ncdai/react-wheel-picker
+# or
+yarn add @ncdai/react-wheel-picker
+# or
+npm install @ncdai/react-wheel-picker
+```
+
+## Anatomy
+
+The wheel picker consists of two main components:
+
+### WheelPickerWrapper
+
+The wrapper component that contains one or more wheel pickers. It provides the container structure and handles the layout of multiple wheels.
+
+```tsx
+<WheelPickerWrapper>
+  <WheelPicker />
+  <WheelPicker />
+  <WheelPicker />
+</WheelPickerWrapper>
+```
+
+### WheelPicker
+
+The core component that renders a single wheel of options. Each wheel picker consists of:
+
+- A container with a 3D perspective
+- A scrollable list of options
+- A highlight area that indicates the selected option
+- A mask that creates the fade effect at the top and bottom
+
+```tsx
+<WheelPicker
+  options={[
+    { label: "React", value: "react" },
+    { label: "Vue", value: "vue" },
+    { label: "Angular", value: "angular" },
+  ]}
+/>
+```
+
+## Usage
+
+### Import CSS
+
+```tsx
+import "@ncdai/react-wheel-picker/dist/style.css";
+```
+
+This CSS file includes only the core layout for the wheel picker. For custom visuals, use the `classNames` prop as shown in the Tailwind CSS example below.
+
+### Import components
+
+```tsx
+import {
+  WheelPicker,
+  WheelPickerWrapper,
+  type WheelPickerOption,
+  type WheelPickerClassNames,
+} from "@ncdai/react-wheel-picker";
+```
+
+### Example with Tailwind CSS
+
+```tsx
+const options: WheelPickerOption[] = [
+  {
+    label: "React",
+    value: "react",
+  },
+  {
+    label: "Vue",
+    value: "vue",
+  },
+  {
+    label: "Angular",
+    value: "angular",
+  },
+  {
+    label: "Svelte",
+    value: "svelte",
+  },
+];
+
+const classNames: WheelPickerClassNames = {
+  optionItem: "text-zinc-400",
+  highlightWrapper: "bg-zinc-100 text-zinc-950",
+};
+
+export function WheelPickerDemo() {
+  return (
+    <WheelPickerWrapper className="max-w-56 rounded-md border border-zinc-200 bg-white shadow-xs">
+      <WheelPicker options={options} classNames={classNames} />
+    </WheelPickerWrapper>
+  );
+}
+```
+
+## API
+
+### WheelPicker
+
+Props for the WheelPicker component:
+
+| Prop              | Type                      | Default    | Description                                                    |
+| ----------------- | ------------------------- | ---------- | -------------------------------------------------------------- |
+| `options`         | `WheelPickerOption[]`     | (required) | Array of options to display in the wheel                       |
+| `value`           | `string`                  | -          | Current value of the picker (controlled mode)                  |
+| `defaultValue`    | `string`                  | -          | Default value of the picker (uncontrolled mode)                |
+| `onValueChange`   | `(value: string) => void` | -          | Callback fired when the selected value changes                 |
+| `infinite`        | `boolean`                 | `false`    | Enable infinite scrolling                                      |
+| `visibleCount`    | `number`                  | `20`       | Number of options visible on the wheel (must be multiple of 4) |
+| `dragSensitivity` | `number`                  | `3`        | Sensitivity of the drag interaction (higher = more sensitive)  |
+| `classNames`      | `WheelPickerClassNames`   | -          | Custom class names for styling                                 |
+
+### WheelPickerWrapper
+
+Props for the WheelPickerWrapper component:
+
+| Prop        | Type              | Default    | Description                |
+| ----------- | ----------------- | ---------- | -------------------------- |
+| `className` | `string`          | -          | CSS class name for wrapper |
+| `children`  | `React.ReactNode` | (required) | WheelPicker components     |
+
+### Types
+
+```tsx
+type WheelPickerOption = {
+  /** Value that will be returned when this option is selected */
+  value: string;
+  /** Text label displayed for this option */
+  label: string;
+};
+
+type WheelPickerClassNames = {
+  /** Class name for individual option items */
+  optionItem?: string;
+  /** Class name for the wrapper of the highlighted area */
+  highlightWrapper?: string;
+  /** Class name for the highlighted item */
+  highlightItem?: string;
+};
+```

package/dist/index.js

@@ -446,10 +446,7 @@ const WheelPicker = ({ defaultValue, value: valueProp, onValueChange, options: o
         container.addEventListener("wheel", handleWheelEvent, opts);
         document.addEventListener("mousedown", handleDragStartEvent, opts);
         document.addEventListener("mouseup", handleDragEndEvent, opts);
-        return ()=>{
-            console.log("cleanup");
-            controller.abort();
-        };
+        return ()=>controller.abort();
     }, [
         handleDragEndEvent,
         handleDragStartEvent,
@@ -462,7 +459,6 @@ const WheelPicker = ({ defaultValue, value: valueProp, onValueChange, options: o
         value,
         valueProp
     ]);
-    console.log("render WheelPicker", valueProp);
     return /*#__PURE__*/ React__default.default.createElement("div", {
         ref: containerRef,
         "data-rwp": true,

package/dist/index.mjs

@@ -440,10 +440,7 @@ const WheelPicker = ({ defaultValue, value: valueProp, onValueChange, options: o
         container.addEventListener("wheel", handleWheelEvent, opts);
         document.addEventListener("mousedown", handleDragStartEvent, opts);
         document.addEventListener("mouseup", handleDragEndEvent, opts);
-        return ()=>{
-            console.log("cleanup");
-            controller.abort();
-        };
+        return ()=>controller.abort();
     }, [
         handleDragEndEvent,
         handleDragStartEvent,
@@ -456,7 +453,6 @@ const WheelPicker = ({ defaultValue, value: valueProp, onValueChange, options: o
         value,
         valueProp
     ]);
-    console.log("render WheelPicker", valueProp);
     return /*#__PURE__*/ React.createElement("div", {
         ref: containerRef,
         "data-rwp": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ncdai/react-wheel-picker",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "iOS-like wheel picker for React with smooth inertia scrolling and infinite loop support.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -27,11 +27,16 @@
     "type-check": "tsc --noEmit",
     "copy-assets": "cp -r ./src/style.css ./dist/style.css",
     "dev:website": "turbo run dev --filter=website...",
-    "lint": "eslint . --ext .ts,.tsx --ignore-pattern 'website/**'",
+    "prettier:check": "prettier --check .",
     "format": "prettier --write .",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "keywords": [],
+  "keywords": [
+    "react",
+    "wheel picker",
+    "wheel",
+    "picker"
+  ],
   "author": "Nguyen Chanh Dai <dai@chanhdai.com>",
   "license": "MIT",
   "homepage": "https://react-wheel-picker.chanhdai.com",
@@ -55,4 +60,4 @@
   "peerDependencies": {
     "react": "^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc"
   }
-}
+}