Skip to content

Commit

Permalink
docs: update jsdoc-to-mdx and fix types (#47)
Browse files Browse the repository at this point in the history
  • Loading branch information
@daybrush
daybrush committed Aug 24, 2023
1 parent e3d19e9 commit 0210e64
Show file tree
Hide file tree
Showing 5 changed files with 252 additions and 122 deletions.
2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@
"@types/react": "^17.0.45",
"@types/react-dom": "^17.0.2",
"egjs-jsdoc-template": "^1.4.4",
"jsdoc-to-mdx": "^1.1.0",
"jsdoc-to-mdx": "^1.2.1",
"lerna": "^4.0.0",
"react": "^17.0.2",
"react-dom": "^17.0.2",
Expand Down
96 changes: 78 additions & 18 deletions packages/conveyer/src/types.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,32 +5,77 @@
*/
import { CONVEYER_METHODS } from "./consts";
import Conveyer from "./Conveyer";


/**
* @typedef
* @property - scroll direction. (true: Horizontal Scroll, false: Vertical Scroll) (default: true) <ko>스크롤 방향. (true: 가로 스크롤, false: 세로 스크롤) (default: true)</ko>
* @property - selector to find items inside. (default: "") <ko>내부의 아이템들을 찾기 위한 selector. (default: "")</ko>
* @property - Whether to use drag (default: true) <ko> 드래그를 사용할지 여부. (default: true)</ko>
* @property - Whether to use the mouse wheel in a direction aside from the scroll direction (default: false) <ko>스크롤 방향과 다른 방향의 마우스 휠 입력을 사용할지 여부. (default: false)</ko>
* @property - The minimum margin space for {@link Conveyer#event-reachStart reachStart}, {@link Conveyer#event-leaveStart leaveStart}, {@link Conveyer#event-reachEnd reachEnd}, and {@link Conveyer#event-leaveEnd leaveEnd} events to be triggered at the beginning and end of the scroll area. (default: 0)
* <ko> 스크롤 영역의 시작과 끝에서 {@link Conveyer#event-reachStart reachStart}, {@link Conveyer#event-leaveStart leaveStart}, {@link Conveyer#event-reachEnd reachEnd}, {@link Conveyer#event-leaveEnd leaveEnd} 이벤트들이 발생하기 위한 최소 여백. (default: 0)</ko>
* @property - The maximum amount of time the scroll event does not fire for the finishScroll event to be triggered. (default: 100) <ko> finishScroll 이벤트가 발생되기 위한 scroll 이벤트가 발생하지 않는 최대 시간. (default: 100)</ko>
* @property - Whether to prevent being selected. (default: true) <ko>셀렉트가 되는 것을 막을지 여부. (default: true) </ko>
* @property - Whether to prevent click event when dragging. (default: false) <ko>드래그하면 클릭이벤트를 막을지 여부. (default: true)</ko>
* @property - Whether to use the {@link https://developer.mozilla.org/ko/docs/Web/API/Event/preventDefault preventDefault} when the user starts dragging <ko>사용자가 드래그를 시작할 때 {@link https://developer.mozilla.org/ko/docs/Web/API/Event/preventDefault preventDefault} 실행 여부</ko>
* @property - Whether to automatically initialize when an instance is created. If set to false, initialization is possible while calling the init method. (default: true) <ko>인스턴스를 생성할 때 자동으로 초기화할지 여부. false로 설정하면 init 메서드를 호출하면서 초기화가 가능하다. (default: true)</ko>
* @property - If this option is enabled on a Conveyer placed inside an egjs component that has the same scroll direction including the Conveyer itself. The parent component moves in the same direction after the Conveyer reaches the first/last scroll position. <ko>Conveyer 자신을 포함해서 동일한 스크롤 방향을 가진 egjs 컴포넌트 내부에 배치된 Conveyer에서 이 옵션을 활성화하면 Conveyer가 첫/마지막 스크롤 위치에 도달한 뒤부터 같은 방향으로 상위 컴포넌트가 움직인다.</ko>
*/
export interface ConveyerOptions {
/**
* scroll direction. (true: Horizontal Scroll, false: Vertical Scroll)
* <ko>스크롤 방향. (true: 가로 스크롤, false: 세로 스크롤)</ko>
* @default true
*/
horizontal?: boolean;
/**
* selector to find items inside.
* <ko>내부의 아이템들을 찾기 위한 selector.</ko>
* @default ""
*/
itemSelector?: string;
/**
* Whether to use drag.
* <ko> 드래그를 사용할지 여부.</ko>
* @default true
*/
useDrag?: boolean;
/**
* Whether to use the mouse wheel in a direction aside from the scroll direction.
* <ko>스크롤 방향과 다른 방향의 마우스 휠 입력을 사용할지 여부.</ko>
* @default false
*/
useSideWheel?: boolean;
/**
* The minimum margin space for {@link Conveyer#event-reachStart reachStart}, {@link Conveyer#event-leaveStart leaveStart}, {@link Conveyer#event-reachEnd reachEnd}, and {@link Conveyer#event-leaveEnd leaveEnd} events to be triggered at the beginning and end of the scroll area.
* <ko> 스크롤 영역의 시작과 끝에서 {@link Conveyer#event-reachStart reachStart}, {@link Conveyer#event-leaveStart leaveStart}, {@link Conveyer#event-reachEnd reachEnd}, {@link Conveyer#event-leaveEnd leaveEnd} 이벤트들이 발생하기 위한 최소 여백.</ko>
* @default 0
*/
boundaryMargin?: number;
/**
* The maximum amount of time the scroll event does not fire for the finishScroll event to be triggered.
* <ko> finishScroll 이벤트가 발생되기 위한 scroll 이벤트가 발생하지 않는 최대 시간.</ko>
* @default 100
*/
scrollDebounce?: number;
/**
* Whether to prevent being selected.
* <ko>셀렉트가 되는 것을 막을지 여부.</ko>
* @default true
*/
preventDefault?: boolean;
/**
* Whether to prevent click event when dragging.
* <ko>드래그하면 클릭이벤트를 막을지 여부.</ko>
* @default false
*/
preventClickOnDrag?: boolean;
/**
* Whether to use the {@link https://developer.mozilla.org/ko/docs/Web/API/Event/preventDefault preventDefault} when the user starts dragging.
* <ko>사용자가 드래그를 시작할 때 {@link https://developer.mozilla.org/ko/docs/Web/API/Event/preventDefault preventDefault} 실행 여부</ko>
* @default false
*/
preventDefaultOnDrag?: boolean;
/**
* Whether to automatically initialize when an instance is created. If set to false, initialization is possible while calling the init method.
* <ko>인스턴스를 생성할 때 자동으로 초기화할지 여부. false로 설정하면 init 메서드를 호출하면서 초기화가 가능하다.</ko>
* @default true
*/
autoInit?: boolean;
/**
* If this option is enabled on a Conveyer placed inside an egjs component that has the same scroll direction including the Conveyer itself. The parent component moves in the same direction after the Conveyer reaches the first/last scroll position.
* <ko>Conveyer 자신을 포함해서 동일한 스크롤 방향을 가진 egjs 컴포넌트 내부에 배치된 Conveyer에서 이 옵션을 활성화하면 Conveyer가 첫/마지막 스크롤 위치에 도달한 뒤부터 같은 방향으로 상위 컴포넌트가 움직인다.</ko>
* @default false
*/
nested?: boolean;
}

Expand Down Expand Up @@ -65,8 +110,8 @@ export interface ConveyerReactiveState {
*/
export interface FindItemOptions {
/**
* size ratio to find items.
* <ko>아이템을 찾기 위한 사이즈 비율.</ko>
* size ratio to find items. Use it if `padding` inside the item plays the same role as `margin` or `gap`.
* <ko>아이템을 찾기 위한 사이즈 비율. 아이템 내부에 `padding`이 `margin`, `gap`과 같은 역할을 한다면 사용해라.</ko>
* @default 1
*/
hitTest?: number;
Expand All @@ -88,15 +133,30 @@ export interface FindItemOptions {
/**
* @typedef
* @extends FindItemOptions
* @property - Where to arrange the items in the container. (default: "start") <ko>아이템을 container안에서 정렬할 위치. (default: "start")</ko>
* @property - Whether to find the next item except sorting it in place. (default: false) <ko>아이템을 제자리에 정렬하는 것을 제외하고 다음 아이템을 찾을지 여부. (default: false)</ko>
* @property - The value to scroll further from the sort position. (default: 0) <ko>정렬하는 위치에서 얼만큼 더 스크롤할 값. (default: 0)</ko>
* @property - How long to scroll animation time. (default: 0) <ko>얼마동한 스크롤할 할지 애니메이션 시간. (default: 0)</ko>
*/
export interface ScrollIntoViewOptions extends FindItemOptions {
/**
* The position to align the target to.
* <ko>target을 정렬할 위치.</ko>
*/
align?: "start" | "end" | "center";
/**
* Whether to find the next item except sorting it in place.
* <ko>아이템을 제자리에 정렬하는 것을 제외하고 다음 아이템을 찾을지 여부.</ko>
* @default false
*/
excludeStand?: boolean;
/**
* The value to scroll further from the sort position.
* <ko>정렬하는 위치에서 얼만큼 더 스크롤할 값.</ko>
* @default 0
*/
offset?: number;
/**
* How long to scroll animation time.
* <ko>얼마동한 스크롤할 할지 애니메이션 시간.</ko>
* @default 0
*/
duration?: number;
}

Expand Down
10 changes: 8 additions & 2 deletions packages/docs/docs/examples/Intersection.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,16 @@ Also, if the `intersection` option is enabled, items overlapping on the side can


import Intersection from "@site/src/examples/Intersection";
import { ScrollIntoViewTargetWithIntersection } from "@site/src/examples/ScrollIntoViewTarget";
import {
ScrollIntoViewTargetWithIntersectionStartEnd,
ScrollIntoViewTargetWithIntersectionPrevNext,
} from "@site/src/examples/ScrollIntoViewTarget";
import ConveyerCodeTabs from "@site/docs/codes/ConveyerCodeTabs";

<ScrollIntoViewTargetWithIntersection />
<ScrollIntoViewTargetWithIntersectionStartEnd />

<ScrollIntoViewTargetWithIntersectionPrevNext />



### Example
Expand Down
173 changes: 107 additions & 66 deletions packages/docs/src/examples/ScrollIntoViewTarget.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,25 +11,56 @@ function updateItem(items, container, mark, target, className) {
}
}


function ConveyerItems(props: { itemsRef: React.RefObject<HTMLDivElement>; onScroll: () => void }) {
return <>
<div className="background-items">
<div className="item">1</div>
<div className="item">2</div>
<div className="item">3</div>
<div className="item">4</div>
<div className="item">5</div>
<div className="item">6</div>
<div className="item">7</div>
<div className="item">8</div>
<div className="item">9</div>
<div className="item">10</div>
</div>
<div className="items" ref={props.itemsRef} onScroll={props.onScroll}>
<div className="item">1</div>
<div className="item">2</div>
<div className="item">3</div>
<div className="item">4</div>
<div className="item">5</div>
<div className="item">6</div>
<div className="item">7</div>
<div className="item">8</div>
<div className="item">9</div>
<div className="item">10</div>
</div>
</>;
}

export default function ScrollIntoViewTarget() {
const ref = React.useRef<HTMLDivElement>(null);
const containerRef = React.useRef<HTMLDivElement>();
const containerRef = React.useRef<HTMLDivElement>(null);

const { findElement, scrollIntoView } = useConveyer(ref, {
horizontal: true,
});

const onScroll = React.useCallback(() => {
requestAnimationFrame(() => {
const container = containerRef.current;
const markPrev = document.querySelector(".mark.prev");
const markStart = document.querySelector(".mark.start");
const markEnd = document.querySelector(".mark.end");
const markNext = document.querySelector(".mark.next");
const items = document.querySelectorAll(".item");
const backgroundItems = document.querySelectorAll<HTMLElement>(".background-items .item");
const container = containerRef.current!;
const markPrev = container.querySelector(".mark.prev");
const markStart = container.querySelector(".mark.start");
const markEnd = container.querySelector(".mark.end");
const markNext = container.querySelector(".mark.next");
const items = container.querySelectorAll(".item");
const backgroundItems = container.querySelectorAll<HTMLElement>(".background-items .item");

backgroundItems.forEach(element => {
element!.style.transform = `translateX(${-ref.current.scrollLeft}px)`;
element!.style.transform = `translateX(${-ref.current!.scrollLeft}px)`;
});
items.forEach(item => {
item.classList.remove("prev", "start", "end", "next");
Expand Down Expand Up @@ -61,30 +92,7 @@ export default function ScrollIntoViewTarget() {
}, []);
return <div className="scroll-into-view-target" ref={containerRef}>
<p className="top">target</p>
<div className="background-items">
<div className="item">1</div>
<div className="item">2</div>
<div className="item">3</div>
<div className="item">4</div>
<div className="item">5</div>
<div className="item">6</div>
<div className="item">7</div>
<div className="item">8</div>
<div className="item">9</div>
<div className="item">10</div>
</div>
<div className="items" ref={ref} onScroll={onScroll}>
<div className="item">1</div>
<div className="item">2</div>
<div className="item">3</div>
<div className="item">4</div>
<div className="item">5</div>
<div className="item">6</div>
<div className="item">7</div>
<div className="item">8</div>
<div className="item">9</div>
<div className="item">10</div>
</div>
<ConveyerItems itemsRef={ref} onScroll={onScroll} />
<div className="mark prev"></div>
<div className="mark next"></div>
<div className="mark start"></div>
Expand All @@ -93,7 +101,7 @@ export default function ScrollIntoViewTarget() {
</div>;
}

export function ScrollIntoViewTargetWithIntersection() {
export function ScrollIntoViewTargetWithIntersectionStartEnd() {
const ref = React.useRef<HTMLDivElement>(null);
const containerRef = React.useRef<HTMLDivElement>(null);
const { findElement, scrollIntoView } = useConveyer(ref, {
Expand All @@ -102,13 +110,13 @@ export function ScrollIntoViewTargetWithIntersection() {

const onScroll = React.useCallback(() => {
requestAnimationFrame(() => {
const container = containerRef.current;
// const markPrev = document.querySelector(".mark.prev");
const markStart = document.querySelector(".mark.start");
const markEnd = document.querySelector(".mark.end");
// const markNext = document.querySelector(".mark.next");
const items = document.querySelectorAll(".item");
const backgroundItems = document.querySelectorAll<HTMLElement>(".background-items .item");
const container = containerRef.current!;
// const markPrev = container.querySelector(".mark.prev");
const markStart = container.querySelector(".mark.start");
const markEnd = container.querySelector(".mark.end");
// const markNext = container.querySelector(".mark.next");
const items = container.querySelectorAll(".item");
const backgroundItems = container.querySelectorAll<HTMLElement>(".background-items .item");

backgroundItems.forEach(element => {
element!.style.transform = `translateX(${-ref.current!.scrollLeft}px)`;
Expand Down Expand Up @@ -146,35 +154,68 @@ export function ScrollIntoViewTargetWithIntersection() {
});
}, []);
return <div className="scroll-into-view-target" ref={containerRef}>
<p className="top">target with intersection</p>
<div className="background-items">
<div className="item">1</div>
<div className="item">2</div>
<div className="item">3</div>
<div className="item">4</div>
<div className="item">5</div>
<div className="item">6</div>
<div className="item">7</div>
<div className="item">8</div>
<div className="item">9</div>
<div className="item">10</div>
</div>
<div className="items" ref={ref} onScroll={onScroll}>
<div className="item">1</div>
<div className="item">2</div>
<div className="item">3</div>
<div className="item">4</div>
<div className="item">5</div>
<div className="item">6</div>
<div className="item">7</div>
<div className="item">8</div>
<div className="item">9</div>
<div className="item">10</div>
</div>
<p className="top">target with intersection (start, end)</p>
<ConveyerItems itemsRef={ref} onScroll={onScroll} />
{/* <div className="mark prev"></div> */}
{/* <div className="mark next"></div> */}
<div className="mark start"></div>
<div className="mark end"></div>
<p className="bottom">align</p>
</div>;
}

export function ScrollIntoViewTargetWithIntersectionPrevNext() {
const ref = React.useRef<HTMLDivElement>(null);
const containerRef = React.useRef<HTMLDivElement>(null);
const { findElement, scrollIntoView } = useConveyer(ref, {
horizontal: true,
});

const onScroll = React.useCallback(() => {
requestAnimationFrame(() => {
const container = containerRef.current!;
const markPrev = container.querySelector(".mark.prev");
const markNext = container.querySelector(".mark.next");
const items = container.querySelectorAll(".item");
const backgroundItems = container.querySelectorAll<HTMLElement>(".background-items .item");

backgroundItems.forEach(element => {
element!.style.transform = `translateX(${-ref.current!.scrollLeft}px)`;
});
items.forEach(item => {
item.classList.remove("prev", "next");
});

const prev = findElement("prev", {
intersection: true,
});
const next = findElement("next", {
intersection: true,
});

prev?.classList.add("prev");
next?.classList.add("next");


updateItem(backgroundItems, container, markPrev, prev, "prev");
updateItem(backgroundItems, container, markNext, next, "next");
});
}, []);

React.useEffect(() => {
onScroll();
scrollIntoView("next", {
align: "center",
duration: 500,
});
}, []);
return <div className="scroll-into-view-target" ref={containerRef}>
<p className="top">target with intersection (prev, next)</p>
<ConveyerItems itemsRef={ref} onScroll={onScroll} />
<div className="mark prev"></div>
<div className="mark next"></div>
{/* <div className="mark start"></div>
<div className="mark end"></div> */}
<p className="bottom">align</p>
</div>;
}
Loading

0 comments on commit 0210e64

Please sign in to comment.