docs: add element docs (#18)

docs/.vitepress/config.ts

@@ -1,5 +1,14 @@
 import { defineConfig } from 'vitepress'
-import { generalItems, numberItems, stringItems, arrayItems, functionItems, collectionItems, mathItems } from './items'
+import {
+  generalItems,
+  numberItems,
+  stringItems,
+  arrayItems,
+  functionItems,
+  collectionItems,
+  mathItems,
+  elementItems,
+} from './items'
 
 function withI18n(items: { link: string; text: string }[], locale: 'zh') {
   return items.map((item) => {
@@ -59,6 +68,10 @@ export default defineConfig({
             text: '函数',
             items: withI18n(functionItems, 'zh'),
           },
+          {
+            text: '元素',
+            items: withI18n(elementItems, 'zh'),
+          },
         ],
 
         docFooter: {
@@ -113,6 +126,10 @@ export default defineConfig({
         text: 'Function',
         items: functionItems,
       },
+      {
+        text: 'Element',
+        items: elementItems,
+      },
     ],
 
     socialLinks: [{ icon: 'github', link: 'https://github.com/varletjs/rattail' }],

docs/.vitepress/items/element.ts

@@ -0,0 +1,16 @@
+export const elementItems = [
+  { text: 'requestAnimationFrame', link: '/element/request-animation-frame' },
+  { text: 'cancelAnimationFrame', link: '/element/cancel-animation-frame' },
+  { text: 'raf', link: '/element/raf' },
+  { text: 'doubleRaf', link: '/element/double-raf' },
+  { text: 'getStyle', link: '/element/get-style' },
+  { text: 'getRect', link: '/element/get-rect' },
+  { text: 'inViewport', link: '/element/in-viewport' },
+  { text: 'getParentScroller', link: '/element/get-parent-scroller' },
+  { text: 'getAllParentScroller', link: '/element/get-all-parent-scroller' },
+  { text: 'preventDefault', link: '/element/prevent-default' },
+  { text: 'getScrollTop', link: '/element/get-scroll-top' },
+  { text: 'getScrollLeft', link: '/element/get-scroll-left' },
+  { text: 'classes', link: '/element/classes' },
+  { text: 'createNamespaceFn', link: '/element/create-namespace-fn' },
+]

docs/.vitepress/items/index.ts

@@ -5,3 +5,4 @@ export * from './array'
 export * from './collection'
 export * from './function'
 export * from './math'
+export * from './element'

docs/element/cancel-animation-frame.md

@@ -0,0 +1,24 @@
+# cancelAnimationFrame
+
+Cancels a `requestAnimationFrame` request using the provided handle, with a fallback to `clearTimeout`.
+
+### Usage
+
+```ts
+import { cancelAnimationFrame } from 'rattail'
+
+const handle = requestAnimationFrame(() => {})
+cancelAnimationFrame(handle)
+```
+
+### Arguments
+
+| Arg      | Type     | Defaults |
+| -------- | -------- | -------- |
+| `handle` | `number` |          |
+
+### Return
+
+| Type   |
+| ------ |
+| `void` |

docs/element/classes.md

@@ -0,0 +1,23 @@
+# classes
+
+Generates a list of class names based on a given condition or directly returns class names.
+
+### Usage
+
+```ts
+import { classes } from 'rattail'
+
+const classList = classes('active', [true, 'visible', 'hidden'])
+```
+
+### Arguments
+
+| Arg       | Type      | Defaults |
+| --------- | --------- | -------- |
+| `classes` | `Classes` |          |
+
+### Return
+
+| Type    |
+| ------- |
+| `any[]` |

docs/element/create-namespace-fn.md

@@ -0,0 +1,25 @@
+# createNamespaceFn
+
+Creates a namespace function that allows BEM-style naming of components and classes.
+
+### Usage
+
+```ts
+import { createNamespaceFn } from 'rattail'
+
+const ns = createNamespaceFn('my-app')
+const bem = ns('button')
+console.log(bem.n('--active'))
+```
+
+### Arguments
+
+| Arg         | Type     | Defaults |
+| ----------- | -------- | -------- |
+| `namespace` | `string` |          |
+
+### Return
+
+| Type                                               |
+| -------------------------------------------------- |
+| `{ name: string; n: Function; classes: Function }` |

docs/element/double-raf.md

@@ -0,0 +1,19 @@
+# doubleRaf
+
+Creates a Promise-based double `requestAnimationFrame` that resolves after two frames.
+
+### Usage
+
+```ts
+import { doubleRaf } from 'rattail'
+
+doubleRaf().then(() => {
+  console.log('Two frames later')
+})
+```
+
+### Return
+
+| Type            |
+| --------------- |
+| `Promise<void>` |

docs/element/get-all-parent-scroller.md

@@ -0,0 +1,23 @@
+# getAllParentScroller
+
+Retrieves all scrollable ancestor elements of an element in an array, including the `window` as the last item.
+
+### Usage
+
+```ts
+import { getAllParentScroller } from 'rattail'
+
+const scrollers = getAllParentScroller(document.querySelector('div'))
+```
+
+### Arguments
+
+| Arg  | Type          | Defaults |
+| ---- | ------------- | -------- |
+| `el` | `HTMLElement` |          |
+
+### Return
+
+| Type                           |
+| ------------------------------ |
+| `Array<HTMLElement \| Window>` |

docs/element/get-parent-scroller.md

@@ -0,0 +1,23 @@
+# getParentScroller
+
+Finds the closest scrollable ancestor of an element. If no scrollable ancestor is found, returns the `window`.
+
+### Usage
+
+```ts
+import { getParentScroller } from 'rattail'
+
+const scroller = getParentScroller(document.querySelector('div'))
+```
+
+### Arguments
+
+| Arg  | Type          | Defaults |
+| ---- | ------------- | -------- |
+| `el` | `HTMLElement` |          |
+
+### Return
+
+| Type                    |
+| ----------------------- |
+| `HTMLElement \| Window` |

docs/element/get-rect.md

@@ -0,0 +1,23 @@
+# getRect
+
+Gets the dimensions and position of an element or window as a `DOMRect` object.
+
+### Usage
+
+```ts
+import { getRect } from 'rattail'
+
+const rect = getRect(document.querySelector('div'))
+```
+
+### Arguments
+
+| Arg       | Type      | Defaults |
+| --------- | --------- | -------- |
+| `element` | `Element` | `Window` |
+
+### Return
+
+| Type      |
+| --------- |
+| `DOMRect` |

docs/element/get-scroll-left.md

@@ -0,0 +1,23 @@
+# getScrollLeft
+
+Gets the horizontal scroll position of an element or window.
+
+### Usage
+
+```ts
+import { getScrollLeft } from 'rattail'
+
+const scrollLeft = getScrollLeft(window)
+```
+
+### Arguments
+
+| Arg       | Type                | Defaults |
+| --------- | ------------------- | -------- |
+| `element` | `Element \| Window` |          |
+
+### Return
+
+| Type     |
+| -------- |
+| `number` |

docs/element/get-scroll-top.md

@@ -0,0 +1,23 @@
+# getScrollTop
+
+Gets the vertical scroll position of an element or window.
+
+### Usage
+
+```ts
+import { getScrollTop } from 'rattail'
+
+const scrollTop = getScrollTop(window)
+```
+
+### Arguments
+
+| Arg       | Type                | Defaults |
+| --------- | ------------------- | -------- |
+| `element` | `Element \| Window` |          |
+
+### Return
+
+| Type     |
+| -------- |
+| `number` |

docs/element/get-style.md

@@ -0,0 +1,23 @@
+# getStyle
+
+Retrieves computed CSS styles for a given DOM element.
+
+### Usage
+
+```ts
+import { getStyle } from 'rattail'
+
+const elementStyle = getStyle(document.querySelector('div'))
+```
+
+### Arguments
+
+| Arg       | Type      | Defaults |
+| --------- | --------- | -------- |
+| `element` | `Element` |          |
+
+### Return
+
+| Type                  |
+| --------------------- |
+| `CSSStyleDeclaration` |

docs/element/in-viewport.md

@@ -0,0 +1,23 @@
+# inViewport
+
+Determines if an element is visible within the viewport.
+
+### Usage
+
+```ts
+import { inViewport } from 'rattail'
+
+const isVisible = inViewport(document.querySelector('div'))
+```
+
+### Arguments
+
+| Arg       | Type          | Defaults |
+| --------- | ------------- | -------- |
+| `element` | `HTMLElement` |          |
+
+### Return
+
+| Type      |
+| --------- |
+| `boolean` |

docs/element/prevent-default.md

@@ -0,0 +1,23 @@
+# preventDefault
+
+Prevents the default action of an event if it is cancelable.
+
+### Usage
+
+```ts
+import { preventDefault } from 'rattail'
+
+document.addEventListener('click', preventDefault)
+```
+
+### Arguments
+
+| Arg     | Type    | Defaults |
+| ------- | ------- | -------- |
+| `event` | `Event` |          |
+
+### Return
+
+| Type   |
+| ------ |
+| `void` |

docs/element/raf.md

@@ -0,0 +1,19 @@
+# raf
+
+Creates a Promise-based `requestAnimationFrame` that resolves on the next frame.
+
+### Usage
+
+```ts
+import { raf } from 'rattail'
+
+raf().then(() => {
+  console.log('Next animation frame')
+})
+```
+
+### Return
+
+| Type            |
+| --------------- |
+| `Promise<void>` |

docs/element/request-animation-frame.md

@@ -0,0 +1,25 @@
+# requestAnimationFrame
+
+Provides a cross-browser compatible `requestAnimationFrame` function, with a fallback to `setTimeout`.
+
+### Usage
+
+```ts
+import { requestAnimationFrame } from 'rattail'
+
+requestAnimationFrame(() => {
+  console.log('Frame requested')
+})
+```
+
+### Arguments
+
+| Arg  | Type                   | Defaults |
+| ---- | ---------------------- | -------- |
+| `fn` | `FrameRequestCallback` |          |
+
+### Return
+
+| Type     |
+| -------- |
+| `number` |