Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update jsdoc-to-mdx and fix types #47

Merged
merged 1 commit into from
Aug 24, 2023
Merged

docs: update jsdoc-to-mdx and fix types #47

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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>;
}