### Minimal Setup (Component)

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/exports-overview.md

Import and use the `StickToBottom` component directly in your templates for a minimal setup.

```APIDOC
## Minimal Setup (Component)

```typescript
import { StickToBottom } from 'vue-stick-to-bottom'

// In template:
// <StickToBottom>...</StickToBottom>
```
```

--------------------------------

### Install vue-stick-to-bottom

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/README.md

Install the library using pnpm, npm, or yarn.

```bash
pnpm add vue-stick-to-bottom
# or: npm install / yarn add
```

--------------------------------

### Install vue-stick-to-bottom

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/README.md

Install the package using npm, pnpm, or yarn. Ensure you are using Vue 3.3 or later as a peer dependency.

```bash
npm install vue-stick-to-bottom
# or
pnpm add vue-stick-to-bottom
# or
yarn add vue-stick-to-bottom
```

--------------------------------

### Minimal Component Setup

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/exports-overview.md

Shows the minimal import pattern for using the StickToBottom component directly in your template.

```typescript
import { StickToBottom } from 'vue-stick-to-bottom'

// In template:
// <StickToBottom>...</StickToBottom>
```

--------------------------------

### Configuration Example

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/composable-use-stick-to-bottom.md

Demonstrates how to configure the useStickToBottom composable with custom spring parameters and a targetScrollTop function for precise scroll control.

```typescript
const { scrollRef, contentRef, isAtBottom } = useStickToBottom({
  damping: 0.6,
  stiffness: 0.08,
  mass: 1.5,
  initial: 'smooth',
  resize: { damping: 0.7, stiffness: 0.05 },
  targetScrollTop: (defaultTarget, { scrollElement }) => {
    // Custom logic: always leave 50px of padding
    return Math.max(0, defaultTarget - 50)
  },
})
```

--------------------------------

### Full Chat Interface Example

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/composable-use-stick-to-bottom.md

A complete Vue.js chat interface example utilizing the useStickToBottom composable for automatic scrolling and managing new messages.

```vue
<script setup lang="ts">
import { ref, computed } from 'vue'
import { useStickToBottom } from 'vue-stick-to-bottom'

const messages = ref([
  { id: 1, text: 'Hello!' },
  { id: 2, text: 'How are you?' },
])

const { scrollRef, contentRef, isAtBottom, scrollToBottom, escapedFromLock } = useStickToBottom({
  damping: 0.7,
  stiffness: 0.05,
  mass: 1.25,
})

const newMessage = ref('')

const sendMessage = async () => {
  if (!newMessage.value.trim()) return
  
  messages.value.push({
    id: messages.value.length + 1,
    text: newMessage.value,
  })
  newMessage.value = ''
  
  // Auto-scroll to bottom
  await scrollToBottom({ wait: true })
}

const handleNewIncomingMessage = async (message: string) => {
  messages.value.push({
    id: messages.value.length + 1,
    text: message,
  })
  
  // Auto-scroll only if user is at bottom
  if (isAtBottom.value) {
    await scrollToBottom()
  }
}
</script>

<template>
  <div class="chat-container">
    <!-- Scroll area -->
    <div ref="scrollRef" class="messages-area">
      <div ref="contentRef">
        <div v-for="msg in messages" :key="msg.id" class="message">
          {{ msg.text }}
        </div>
      </div>
    </div>

    <!-- Back to latest button -->
    <button
      v-if="escapedFromLock"
      class="back-to-latest"
      @click="scrollToBottom()">
      ↓ New messages
    </button>

    <!-- Input area -->
    <div class="input-area">
      <input
        v-model="newMessage"
        placeholder="Type a message..."
        @keydown.enter="sendMessage"
      />
      <button @click="sendMessage">Send</button>
    </div>
  </div>
</template>

<style scoped>
.chat-container {
  display: flex;
  flex-direction: column;
  height: 100%;
}

.messages-area {
  overflow: auto;
  flex: 1;
  padding: 1rem;
  min-height: 0;
}

.message {
  padding: 0.5rem;
  margin: 0.5rem 0;
  background: #f0f0f0;
  border-radius: 4px;
}

.back-to-latest {
  position: absolute;
  bottom: 5rem;
  left: 50%;
  transform: translateX(-50%);
}

.input-area {
  padding: 1rem;
  border-top: 1px solid #ccc;
  display: flex;
  gap: 0.5rem;
}

.input-area input {
  flex: 1;
  padding: 0.5rem;
}

.input-area button {
  padding: 0.5rem 1rem;
}
</style>
```

--------------------------------

### Apply Premium Configuration to StickToBottom

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/configuration.md

Example of applying a custom configuration preset to the StickToBottom component using props. Ensure the configuration object is defined before use.

```vue
<StickToBottom
  :damping="premiumConfig.damping"
  :stiffness="premiumConfig.stiffness"
  :mass="premiumConfig.mass"
  :resize="premiumConfig.resize"
  :initial="premiumConfig.initial"
>
  ...
</StickToBottom>
```

--------------------------------

### Vue Component Example: Stop Scroll Animation

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/composable-use-stick-to-bottom.md

Demonstrates how to use `scrollToBottom` to start a scroll and `stopScroll` to immediately halt the animation and release control, typically used for user-initiated cancellation.

```vue
<script setup>
const { scrollToBottom, stopScroll } = useStickToBottom()

const startScrolling = () => {
  scrollToBottom({ duration: 5000 })
}

const cancel = () => {
  stopScroll()
  console.log('Stopped')
}
</script>

<template>
  <button @click="startScrolling">Scroll</button>
  <button @click="cancel">Stop</button>
</template>
```

--------------------------------

### Example of ScrollToBottomOptions Usage

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/configuration.md

Illustrates how to use ScrollToBottomOptions to customize a single scroll action. This example overrides the animation, sets a wait condition, and specifies a duration for the scroll lock.

```typescript
// Override animation for one scroll
await scrollToBottom({
  animation: { damping: 0.5, stiffness: 0.08, mass: 1.5 },
  wait: true,
  duration: 2000,
})
```

--------------------------------

### StickToBottom with Different Resize Animations

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/component-stick-to-bottom.md

Provides examples of using the 'resize' prop to control how the component reacts to content changes. Options include 'instant' for immediate scrolling and custom spring configurations for smooth, controlled animations.

```vue
<!-- Instant resize scroll -->
<StickToBottom resize="instant">...</StickToBottom>

<!-- Custom spring for resize -->
<StickToBottom :resize="{ damping: 0.6, stiffness: 0.08, mass: 1.5 }">
  ...
```

--------------------------------

### Mixed Resize and Initial Scroll Behaviors

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/configuration.md

Combine different animation behaviors for resize and initial scroll. This example sets instant resize with smooth initial scroll.

```vue
<StickToBottom resize="instant" initial="smooth">...</StickToBottom>
```

--------------------------------

### Basic <StickToBottom> Component Usage

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/component-stick-to-bottom.md

Demonstrates the basic usage of the StickToBottom component with default slots for content, overlay, and after content. It includes examples of how to use the 'isAtBottom' and 'scrollToBottom' functions provided by the slots.

```vue
<template>
  <StickToBottom
    :damping="0.7"
    :stiffness="0.05"
    :mass="1.25"
    resize="smooth"
    :initial="{ damping: 0.7 }"
    anchor="auto"
  >
    <!-- Default slot: scrollable content -->
    <template #default="{ isAtBottom, scrollToBottom }">
      <Message v-for="msg in messages" :key="msg.id" :message="msg" />
    </template>

    <!-- Overlay slot: floats above content (e.g., scroll-to-bottom button) -->
    <template #overlay="{ isAtBottom, scrollToBottom }">
      <button v-if="!isAtBottom" @click="scrollToBottom()">
        ↓ New messages
      </button>
    </template>

    <!-- After slot: outside scroll area (e.g., input box) -->
    <template #after="{ isAtBottom, scrollToBottom }">
      <ChatInput />
    </template>
  </StickToBottom>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { StickToBottom } from 'vue-stick-to-bottom'

const messages = ref([
  { id: 1, text: 'Hello' },
  { id: 2, text: 'How are you?' },
])
</script>
```

--------------------------------

### Advanced Scroll to Bottom Options Example

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/context-stick-to-bottom.md

Illustrates advanced usage of scrollToBottom with detailed options for custom animations, waiting for existing scrolls, and scroll duration.

```vue
<script setup>
const { scrollToBottom } = useStickToBottomContext()

const smoothScrollWithLock = async () => {
  // Scroll with custom animation, wait for existing scroll, maintain lock for 2 seconds
  const success = await scrollToBottom({
    animation: 'smooth',
    wait: true,
    duration: 2000,
  })
  console.log(success)
}

const instantScroll = async () => {
  await scrollToBottom('instant')
}

const lockedScroll = async () => {
  // User cannot interrupt this scroll
  await scrollToBottom({
    animation: { damping: 0.5, stiffness: 0.08, mass: 1.5 },
    ignoreEscapes: true,
  })
}
</script>

<template>
  <div>
    <button @click="smoothScrollWithLock">Smooth (locked)</button>
    <button @click="instantScroll">Jump</button>
    <button @click="lockedScroll">Scroll (user-proof)</button>
  </div>
</template>
```

--------------------------------

### Stiffness Examples

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/configuration.md

Illustrates how stiffness impacts the scroll animation's acceleration speed. Higher stiffness leads to faster acceleration.

```vue
<!-- Slow, smooth scroll -->
<StickToBottom :stiffness="0.02">...</StickToBottom>

<!-- Balanced (default) -->
<StickToBottom :stiffness="0.05">...</StickToBottom>

<!-- Fast, snappy scroll -->
<StickToBottom :stiffness="0.1">...</StickToBottom>
```

--------------------------------

### StickToBottom with Initial Scroll Options

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/component-stick-to-bottom.md

Illustrates the 'initial' prop for controlling the scroll behavior when the component first mounts. Examples show disabling initial scroll, using smooth CSS scrolling, and applying custom spring animations.

```vue
<!-- No initial scroll, start at top -->
<StickToBottom :initial="false">...</StickToBottom>

<!-- Smooth CSS scroll on mount -->
<StickToBottom initial="smooth">...</StickToBottom>

<!-- Custom spring for initial scroll -->
<StickToBottom :initial="{ damping: 0.5, stiffness: 0.08 }">
  ...
```

--------------------------------

### Vue Chat App Example with StickToBottom

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/component-stick-to-bottom.md

A complete example of a chat application using the StickToBottom component for managing the scrollable message area. It includes sending messages, handling incoming messages, and an auto-scroll feature.

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { StickToBottom } from 'vue-stick-to-bottom'

interface Message {
  id: number
  text: string
  timestamp: Date
}

const messages = ref<Message[]>([
  { id: 1, text: 'Hello!', timestamp: new Date() },
  { id: 2, text: 'How are you?', timestamp: new Date() },
])

const input = ref('')
const autoScroll = ref(true)

const sendMessage = async () => {
  if (!input.value.trim()) return

  messages.value.push({
    id: messages.value.length + 1,
    text: input.value,
    timestamp: new Date(),
  })
  input.value = ''
}

const handleIncomingMessage = (text: string) => {
  messages.value.push({
    id: messages.value.length + 1,
    text,
    timestamp: new Date(),
  })
  // Auto-scroll if user has enabled it
  if (autoScroll.value) {
    // Component will auto-scroll via resize observer
  }
}
</script>

<template>
  <div style="display: flex; flex-direction: column; height: 100vh; gap: 1rem; padding: 1rem;">
    <h1>Chat Room</h1>

    <!-- Sticky-to-bottom chat area -->
    <StickToBottom
      class="chat-scroll"
      resize="smooth"
      initial="smooth"
      :damping="0.7"
      :stiffness="0.05"
      :mass="1.25"
    >
      <!-- Messages -->
      <template #default>
        <div class="messages">
          <div v-for="msg in messages" :key="msg.id" class="message">
            <small class="timestamp">{{ msg.timestamp.toLocaleTimeString() }}</small>
            <div class="text">{{ msg.text }}</div>
          </div>
        </div>
      </template>

      <!-- Scroll-to-latest button -->
      <template #overlay="{ isAtBottom, scrollToBottom }">
        <button
          v-if="!isAtBottom"
          class="scroll-to-bottom-btn"
          @click="scrollToBottom()">
          ↓ New messages
        </button>
      </template>

      <!-- Input area -->
      <template #after>
        <div class="input-area">
          <input
            v-model="input"
            placeholder="Type a message..."
            @keydown.enter="sendMessage" />
          <button @click="sendMessage">Send</button>
          <label>
            <input v-model="autoScroll" type="checkbox" />
            Auto-scroll
          </label>
        </div>
      </template>
    </StickToBottom>
  </div>
</template>

<style scoped>
.chat-scroll {
  flex: 1;
  border: 1px solid #ddd;
  border-radius: 8px;
  background: #f9f9f9;
  min-height: 0;
}

.messages {
  display: flex;
  flex-direction: column;
  gap: 0.75rem;
  padding: 1rem;
}

.message {
  background: white;
  padding: 0.75rem 1rem;
  border-radius: 6px;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

.timestamp {
  color: #999;
  display: block;
  margin-bottom: 0.25rem;
}

.text {
  color: #333;
}

.scroll-to-bottom-btn {
  position: absolute;
  bottom: 1rem;
  left: 50%;
  transform: translateX(-50%);
  padding: 0.5rem 1rem;
  background: #007bff;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  z-index: 10;
}

.scroll-to-bottom-btn:hover {
  background: #0056b3;
}

.input-area {
  padding: 1rem;
  border-top: 1px solid #ddd;
  display: flex;
  gap: 0.5rem;
  align-items: center;
  background: white;
}

.input-area input[type="text"] {
  flex: 1;
  padding: 0.5rem;
  border: 1px solid #ddd;
  border-radius: 4px;
}

.input-area button {
  padding: 0.5rem 1rem;
  background: #28a745;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.input-area button:hover {
  background: #218838;
}

.input-area label {
  display: flex;
  align-items: center;
  gap: 0.25rem;
  white-space: nowrap;
}
</style>
```

--------------------------------

### Vue StickToBottom Reactivity Example

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/component-stick-to-bottom.md

Demonstrates how to dynamically update StickToBottom component properties like damping and mass at runtime. This allows for changing animation behavior based on application state.

```vue
<script setup>
import { ref } from 'vue'
import { StickToBottom } from 'vue-stick-to-bottom'

const animationSpeed = ref('normal')
const damping = ref(0.7)
const mass = ref(1.25)

const updateSpeed = (speed: 'slow' | 'normal' | 'fast') => {
  animationSpeed.value = speed
  if (speed === 'slow') {
    mass.value = 2.0
  } else if (speed === 'fast') {
    mass.value = 0.8
  }
}
</script>

<template>
  <StickToBottom :damping="damping" :mass="mass">
    ...
  </StickToBottom>
</template>
```

--------------------------------

### Basic Scroll to Bottom Example

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/context-stick-to-bottom.md

A simple Vue component example that uses the scrollToBottom function to scroll to the bottom when a button is clicked.

```vue
<script setup>
const { scrollToBottom } = useStickToBottomContext()

const handleButtonClick = async () => {
  const success = await scrollToBottom()
  if (success) {
    console.log('Scrolled to bottom')
  }
}
</script>

<template>
  <button @click="handleButtonClick">Jump to bottom</button>
</template>
```

--------------------------------

### Example Custom Target Scroll Top Function

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/types.md

Provides an example of a custom function to calculate the target scroll position, ensuring it scrolls to 10px before the actual bottom. Demonstrates usage of the GetTargetScrollTop type.

```typescript
const customTargetFn: GetTargetScrollTop = (defaultTarget, { scrollElement }) => {
  // Always scroll to 10px before the actual bottom
  return Math.max(0, defaultTarget - 10)
}
```

--------------------------------

### Package.json Export Configuration

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/exports-overview.md

Example of the 'exports' configuration in package.json for defining module resolution paths for ESM and TypeScript types.

```json
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.es.js"
    }
  }
}
```

--------------------------------

### Example Test for useStickToBottomContext

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/errors.md

This test suite demonstrates how to verify that ChildComponent renders correctly when inside StickToBottom and throws the expected error when not.

```typescript
import { mount } from '@vue/test-utils'
import { StickToBottom } from 'vue-stick-to-bottom'
import ChildComponent from './ChildComponent.vue'

describe('ChildComponent', () => {
  it('should render when inside StickToBottom', () => {
    const wrapper = mount({
      components: { StickToBottom, ChildComponent },
      template:
        '
        <StickToBottom>
          <ChildComponent />
        </StickToBottom>
      ',
    })
    
    expect(wrapper.find('[data-test="child"]').exists()).toBe(true)
  })

  it('should throw when not inside StickToBottom', () => {
    // This will throw during component setup
    expect(() => {
      mount(ChildComponent)
    }).toThrow('useStickToBottomContext must be used within <StickToBottom>')
  })
})
```

--------------------------------

### Damping Comparison Examples

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/configuration.md

Demonstrates how different damping values affect the scroll animation's bounce and oscillation. Use lower values for more bounce and higher values for less.

```vue
<!-- Bouncy animation -->
<StickToBottom :damping="0.3">...</StickToBottom>

<!-- Balanced (default) -->
<StickToBottom :damping="0.7">...</StickToBottom>

<!-- Stiff, no bounce -->
<StickToBottom :damping="0.95">...</StickToBottom>
```

--------------------------------

### Mass Examples

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/configuration.md

Shows how the mass parameter affects the perceived weight and inertia of the scroll animation. Higher mass results in slower, more deliberate movement.

```vue
<!-- Light animation for snappy feel -->
<StickToBottom :mass="0.8">...</StickToBottom>

<!-- Balanced (default) -->
<StickToBottom :mass="1.25">...</StickToBottom>

<!-- Heavy animation for smooth, deliberate feel -->
<StickToBottom :mass="2.0">...</StickToBottom>
```

--------------------------------

### StickToBottomEngine

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/types.md

The core interface for the scroll-to-bottom engine. It provides methods to attach, detach, destroy, set options, get state, subscribe to changes, and control scrolling.

```APIDOC
## StickToBottomEngine

### Description
Interface for the core scroll-to-bottom engine. It provides methods to attach, detach, destroy, set options, get state, subscribe to changes, and control scrolling.

### Methods

- **attach** `(scrollElement: HTMLElement, contentElement: HTMLElement) => void`
  Attaches the engine to DOM elements and sets up event listeners.

- **detach** `() => void`
  Detaches the engine from DOM elements and removes listeners, but preserves the engine instance.

- **destroy** `() => void`
  Completely destroys the engine, detaches from DOM, and clears all listeners.

- **setOptions** `(options: Partial<StickToBottomOptions>) => void`
  Updates engine options at runtime. Partial updates are merged with existing options.

- **getState** `() => StickToBottomPublicState`
  Returns a snapshot of the current state.

- **onChange** `(listener: (state: StickToBottomPublicState) => void) => () => void`
  Subscribes to state changes. Returns an unsubscribe function.

- **scrollToBottom** `ScrollToBottom`
  Programmatically scrolls to the bottom. See `ScrollToBottom` type.

- **stopScroll** `StopScroll`
  Stops the current scroll animation. See `StopScroll` type.

### Returned by
- `createStickToBottomEngine()` function
```

--------------------------------

### Vue Component Example: Update Runtime Options

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/composable-use-stick-to-bottom.md

Shows how to dynamically update the `useStickToBottom` composable's options at runtime using the `setOptions` function, allowing for changes in animation parameters based on user interaction or application state.

```vue
<script setup>
import { ref } from 'vue'
import { useStickToBottom } from 'vue-stick-to-bottom'

const speed = ref('normal')
const { setOptions } = useStickToBottom()

const updateSpeed = (newSpeed) => {
  speed.value = newSpeed
  
  if (newSpeed === 'slow') {
    setOptions({ mass: 2.0, damping: 0.8 })
  } else if (newSpeed === 'fast') {
    setOptions({ mass: 0.8, damping: 0.5 })
  } else {
    setOptions({ mass: 1.25, damping: 0.7 })
  }
}
</script>

<template>
  <select @change="e => updateSpeed(e.target.value)">
    <option value="slow">Slow</option>
    <option value="normal">Normal</option>
    <option value="fast">Fast</option>
  </select>
</template>
```

--------------------------------

### Default Plugin Usage

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/exports-overview.md

The default Vue plugin simplifies integration by globally registering the `<StickToBottom>` component. Use this in your Vue app's setup for easy access across your application.

```APIDOC
## Default Plugin

The package exports a default Vue plugin for convenience.

```typescript
import StickyBottom from 'vue-stick-to-bottom'

// In your Vue app setup:
app.use(StickyBottom)

// This registers the StickToBottom component globally,
// so you don't need to import it in every component
```

**What it does:** Registers the `<StickToBottom>` component as a global component via `app.component('StickToBottom', ...)`. 

**When to use:** App-level setup when you want the component available everywhere without explicit imports.
```

--------------------------------

### createStickToBottomEngine

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/engine.md

Creates and returns a new `StickToBottomEngine` instance with optional initial configuration.

```APIDOC
## createStickToBottomEngine()

### Description
Creates and returns a new `StickToBottomEngine` instance.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
#### `initialOptions` (StickToBottomOptions) - Optional
Initial configuration for spring animation, scroll behavior, and content size detection.

### Returns
**Type:** `StickToBottomEngine`
An object with methods to attach to DOM elements, manage state, and control scroll behavior.

### Example
```typescript
import { createStickToBottomEngine } from 'vue-stick-to-bottom'

const engine = createStickToBottomEngine({
  damping: 0.7,
  stiffness: 0.05,
  mass: 1.25,
  initial: 'smooth',
  resize: 'smooth',
})

// Later, after mounting your DOM elements:
const scrollContainer = document.getElementById('scroll-container')
const contentWrapper = document.getElementById('content')
engine.attach(scrollContainer, contentWrapper)

// Listen for state changes
const unsubscribe = engine.onChange((state) => {
  console.log('At bottom?', state.isAtBottom)
})

// Scroll to bottom with custom options
engine.scrollToBottom({
  animation: 'smooth',
  wait: true,
  ignoreEscapes: false,
})

// Clean up
unsubscribe()
engine.destroy()
```
```

--------------------------------

### Wait for existing scroll before starting new one

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/README.md

Initiates a scroll to the bottom, but waits for any ongoing scroll animation to complete before starting. This ensures sequential scrolling behavior.

```typescript
await scrollToBottom({ wait: true })
```

--------------------------------

### Low-Level Engine Instantiation

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/exports-overview.md

Instantiate the low-level `StickToBottomEngine` using the `createStickToBottomEngine` function for advanced control over the scrolling behavior.

```APIDOC
## Low-Level Engine

```typescript
import { createStickToBottomEngine } from 'vue-stick-to-bottom'
import type { StickToBottomEngine } from 'vue-stick-to-bottom'

const engine: StickToBottomEngine = createStickToBottomEngine()
```
```

--------------------------------

### Run Demo Command

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/README.md

Command to run the development server for the Vue Stick To Bottom demo. This opens a playground showcasing various features.

```bash
pnpm dev
```

--------------------------------

### Create a StickToBottomEngine Instance

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/engine.md

Initializes a new StickToBottomEngine with optional configuration for animation and behavior. Most applications should use the composable or component instead.

```typescript
import { createStickToBottomEngine } from 'vue-stick-to-bottom'

const engine = createStickToBottomEngine({
  damping: 0.7,
  stiffness: 0.05,
  mass: 1.25,
  initial: 'smooth',
  resize: 'smooth',
})

// Later, after mounting your DOM elements:
const scrollContainer = document.getElementById('scroll-container')
const contentWrapper = document.getElementById('content')
engine.attach(scrollContainer, contentWrapper)

// Listen for state changes
const unsubscribe = engine.onChange((state) => {
  console.log('At bottom?', state.isAtBottom)
})

// Scroll to bottom with custom options
engine.scrollToBottom({
  animation: 'smooth',
  wait: true,
  ignoreEscapes: false,
})

// Clean up
unsubscribe()
engine.destroy()
```

--------------------------------

### File Organization in Source

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/README.md

Overview of the directory structure for the vue-stick-to-bottom source code, showing the location of core logic, components, composables, and context.

```bash
src/
├── index.ts                          # Main entry point
├── types.ts                          # Type re-exports
├── core/
│   └── engine.ts                     # Core engine logic & types
├── components/
│   └── StickToBottom.vue             # Component
├── composables/
│   └── useStickToBottom.ts           # Composable
└── context/
    └── stickToBottom.ts              # Context hook & injection key
```

--------------------------------

### Low-Level Engine Creation

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/exports-overview.md

Shows how to import and create an instance of the low-level StickToBottom engine using createStickToBottomEngine.

```typescript
import { createStickToBottomEngine } from 'vue-stick-to-bottom'
import type { StickToBottomEngine } from 'vue-stick-to-bottom'

const engine: StickToBottomEngine = createStickToBottomEngine()
```

--------------------------------

### Scroll to Bottom Conditionally Example

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/context-stick-to-bottom.md

Shows how to use scrollToBottom with the 'preserveScrollPosition' option to only scroll if the user is already at the bottom of the content.

```vue
<script setup>
const { scrollToBottom } = useStickToBottomContext()

const handleNewMessage = async (message) => {
  messages.push(message)
  
  // Only auto-scroll if user is already at the bottom
  // Does not change the state, so user's scroll position is respected
  await scrollToBottom({
    preserveScrollPosition: true,
  })
}
</script>
```

--------------------------------

### StopScroll Function Example

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/context-stick-to-bottom.md

Demonstrates how to use the stopScroll function to immediately halt any ongoing scroll animation and release the scroll lock.

```vue
<script setup>
import { ref } from 'vue'
import { useStickToBottomContext } from 'vue-stick-to-bottom'

const isScrolling = ref(false)
const { scrollToBottom, stopScroll } = useStickToBottomContext()

const startScroll = async () => {
  isScrolling.value = true
  const success = await scrollToBottom({
    duration: 10000, // 10 second lock
  })
  isScrolling.value = false
}

const cancel = () => {
  stopScroll()
  isScrolling.value = false
}
</script>

<template>
  <div>
    <button @click="startScroll" :disabled="isScrolling">Start scroll</button>
    <button @click="cancel" v-if="isScrolling">Stop</button>
  </div>
</template>
```

--------------------------------

### useStickToBottom()

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/composable-use-stick-to-bottom.md

Creates a stick-to-bottom composable instance with reactive state management. It wraps the stick-to-bottom engine, providing reactive state and automatic lifecycle management.

```APIDOC
## useStickToBottom()

### Description
Creates a stick-to-bottom composable instance with reactive state management. It wraps the stick-to-bottom engine, providing reactive state and automatic lifecycle management.

### Signature
```typescript
function useStickToBottom(
  options?: StickToBottomOptions
): UseStickToBottomReturn
```

### Parameters
#### options
- **Type:** `StickToBottomOptions`
- **Required:** No
- **Default:** `{}`
- **Description:** Configuration for spring animation, initial scroll, and resize behavior.

### Returns
**Type:** `UseStickToBottomReturn`
An object containing template refs, reactive state refs, and control functions.

### Lifecycle
The composable automatically manages the lifecycle of the stick-to-bottom engine, including creation, attachment to DOM elements, state synchronization, detachment, and destruction.

### Example — Basic Usage
```vue
<script setup lang="ts">
import { useStickToBottom } from 'vue-stick-to-bottom'

const { scrollRef, contentRef, isAtBottom, scrollToBottom } = useStickToBottom({
  damping: 0.7,
  stiffness: 0.05,
  mass: 1.25,
})
</script>

<template>
  <div style="display: flex; flex-direction: column; height: 100vh;">
    <!-- Scroll container -->
    <div
      ref="scrollRef"
      style="overflow: auto; flex: 1; min-height: 0;"
    >
      <div ref="contentRef">
        <div v-for="message in messages" :key="message.id">
          {{ message.text }}
        </div>
      </div>
    </div>

    <!-- Scroll-to-bottom button -->
    <button
      v-if="!isAtBottom"
      @click="scrollToBottom()"
    >
      ↓ New messages
    </button>
  </div>
</template>
```

### Return Properties
#### scrollRef
- **Type:** `Ref<HTMLElement | null>`
- **Description:** A Vue template ref for the scrollable container element. Assign this to the `ref` attribute of the element with `overflow: auto`.

#### contentRef
- **Type:** `Ref<HTMLElement | null>`
- **Description:** A Vue template ref for the content wrapper element inside the scroll container. Assign this to the wrapper element that directly contains the scrollable content.

#### isAtBottom
- **Type:** `Ref<boolean>`
- **Description:** Reactive boolean ref indicating whether the scroll container is at the bottom. `true` when the scroll position is at or within ~70px of the bottom, `false` otherwise. Updates whenever scroll position changes, content resizes, or the user scrolls.

#### isNearBottom
- **Type:** `Ref<boolean>`
- **Description:** More granular reactive ref for proximity to the bottom. `true` when within ~70px of the bottom, `false` otherwise. `isAtBottom` is `true` if either at bottom OR near bottom, while `isNearBottom` is `true` only when near (but possibly not exactly at) bottom.

#### escapedFromLock
- **Type:** `Ref<boolean>`
- **Description:** Reactive ref tracking whether the user has scrolled up to cancel stickiness. `true` if the user scrolled up (or used the wheel) while at the bottom, `false` if the user scrolls back down or if a programmatic scroll sets `isAtBottom`. Use case: Distinguish between "user chose to look at older content" vs. "naturally not at bottom".
```

--------------------------------

### Assigning scrollRef to Scroll Container

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/composable-use-stick-to-bottom.md

Example of how to assign the `scrollRef` template ref to the scrollable container element. This is necessary for the composable to manage the scroll behavior.

```vue
<div ref="scrollRef" style="overflow: auto; height: 50vh;">
  <!-- content goes here -->
</div>
```

--------------------------------

### StickToBottomEngine Methods

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/engine.md

The `StickToBottomEngine` object provides methods to interact with and manage the scroll behavior.

```APIDOC
## StickToBottomEngine Methods

### engine.attach(scrollElement, contentElement)

#### Description
Attaches the engine to DOM elements and sets up all event listeners (scroll, wheel, resize).

#### Method
`attach`

#### Parameters
- **scrollElement** (`HTMLElement`) - The scrollable container (should have `overflow: auto` or `overflow: scroll`).
- **contentElement** (`HTMLElement`) - The wrapper element containing the scrollable content.

#### Behavior
- If the scroll element has `overflow: visible`, it is automatically changed to `overflow: auto`.
- Sets up listeners for scroll, wheel, and resize events.
- Initializes the `ResizeObserver` to track content size changes.
- State changes trigger listener callbacks registered via `onChange()`.

#### Example
```typescript
const engine = createStickToBottomEngine()
const scrollDiv = document.querySelector('.scroll-container')
const contentDiv = document.querySelector('.content')

engine.attach(scrollDiv, contentDiv)
```

### engine.detach()

#### Description
Removes all event listeners and the ResizeObserver, but preserves the engine instance and its state.

#### Method
`detach`

#### Behavior
- Unsubscribes from scroll, wheel, and resize events.
- Disconnects the ResizeObserver.
- The engine can be reattached to different elements via `attach()`.

#### Example
```typescript
// Detach when elements are about to be removed
engine.detach()

// Can reattach to new elements later
const newScroll = document.querySelector('.new-scroll-container')
const newContent = document.querySelector('.new-content')
engine.attach(newScroll, newContent)
```

### engine.destroy()

#### Description
Completely destroys the engine, detaches from DOM elements, and clears all listener subscriptions.

#### Method
`destroy`

#### Behavior
- Calls `detach()` internally.
- Clears all state change listeners.
- The engine instance should not be reused after calling `destroy()`.

#### Example
```typescript
onBeforeUnmount(() => {
  engine.destroy()
})
```

### engine.setOptions(options)

#### Description
Updates engine options at runtime. Passed options are merged with existing options.

#### Method
`setOptions`

#### Parameters
- **options** (`Partial<StickToBottomOptions>`) - Partial options object. Only specified fields are updated; others remain unchanged.

#### Behavior
- New spring parameters affect the next scroll animation.
- Changes to `resize` and `initial` affect the next content size change or automatic scroll.
- The `targetScrollTop` function is replaced immediately if provided.

#### Example
```typescript
// Slow down the animation
engine.setOptions({
  damping: 0.8,
  mass: 2.0,
})

// Change resize behavior
engine.setOptions({
  resize: 'instant',
})
```
```

--------------------------------

### Get Current Scroll State

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/engine.md

Retrieves a snapshot of the current scroll state, including whether the user is at the bottom, near the bottom, or has manually scrolled up.

```typescript
getState: () => StickToBottomPublicState
```

```typescript
const state = engine.getState()
if (state.isAtBottom) {
  console.log('User is viewing the latest content')
}
```

--------------------------------

### Instant Feedback Configuration Preset

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/configuration.md

This preset is ideal for applications where immediate responsiveness is critical. It uses 'instant' animation for resize and initial states.

```typescript
const instantConfig = {
  damping: 0.8,
  stiffness: 0.15,
  mass: 0.8,
  resize: 'instant',
  initial: 'instant',
}
```

--------------------------------

### Update Runtime Configuration with setOptions

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/configuration.md

Demonstrates how to dynamically update animation options like mass and damping at runtime using the `setOptions` function. This is useful for responding to user interactions or changing application states.

```vue
<script setup>
import { ref } from 'vue'
import { useStickToBottom } from 'vue-stick-to-bottom'

const { setOptions } = useStickToBottom()
const animationSpeed = ref('normal')

const updateSpeed = (speed) => {
  animationSpeed.value = speed
  
  if (speed === 'slow') {
    setOptions({ mass: 2.0, damping: 0.8 })
  } else if (speed === 'fast') {
    setOptions({ mass: 0.8, damping: 0.5 })
  } else {
    setOptions({ mass: 1.25, damping: 0.7 })
  }
}
</script>

<template>
  <select @change="e => updateSpeed(e.target.value)">
    <option value="slow">Slow</option>
    <option value="normal">Normal</option>
    <option value="fast">Fast</option>
  </select>

  <StickToBottom>...</StickToBottom>
</template>
```

--------------------------------

### Type-Only Imports

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/exports-overview.md

Recommended pattern for importing only types to improve build performance and clarity. Import necessary types like `StickToBottomOptions` and `ScrollToBottomOptions`.

```APIDOC
## Type-Only Imports (Recommended)

```typescript
import type {
  StickToBottomOptions,
  StickToBottomPublicState,
  ScrollToBottomOptions,
} from 'vue-stick-to-bottom'
```
```

--------------------------------

### Assigning contentRef to Content Wrapper

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/composable-use-stick-to-bottom.md

Example of how to assign the `contentRef` template ref to the wrapper element that contains the scrollable content. This helps the composable track content changes.

```vue
<div ref="scrollRef" style="overflow: auto; height: 50vh;">
  <div ref="contentRef">
    <div v-for="item in items" :key="item.id">{{ item }}</div>
  </div>
</div>
```

--------------------------------

### Package Configuration for Tree-Shaking

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/exports-overview.md

Shows the package.json configuration that marks the package as side-effect-free, enabling tree-shaking.

```json
{
  "sideEffects": false
}
```

--------------------------------

### Direct Usage Error: useStickToBottomContext at Root

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/errors.md

This example shows the error occurring when useStickToBottomContext is called directly at the root level of a component without a parent StickToBottom component.

```vue
<script setup>
// ❌ ERROR: useStickToBottomContext at root, no StickToBottom parent
const { scrollToBottom } = useStickToBottomContext()
</script>
```

--------------------------------

### StickToBottomOptions Interface

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/exports-overview.md

Defines the constructor configuration options for the stick-to-bottom functionality. It includes animation settings for resize and initial scroll, as well as a target scroll top getter.

```typescript
import type { StickToBottomOptions } from 'vue-stick-to-bottom'

interface StickToBottomOptions extends SpringAnimation {
  resize?: Animation
  initial?: Animation | boolean
  targetScrollTop?: GetTargetScrollTop
}
```

--------------------------------

### Using isNearBottom for Granular Proximity Indicators

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/composable-use-stick-to-bottom.md

Shows how to use both `isNearBottom` and `isAtBottom` to provide different UI indicators based on the scroll position relative to the bottom of the container.

```vue
<template>
  <!-- Show different indicators -->
  <span v-if="isNearBottom && !isAtBottom">Almost there...</span>
  <span v-else-if="isAtBottom">Latest</span>
  <span v-else>Scrolled up</span>
</template>
```

--------------------------------

### Basic Usage of useStickToBottom

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/composable-use-stick-to-bottom.md

Demonstrates how to use the `useStickToBottom` composable in a Vue 3 component. It sets up refs for the scroll container and content, and conditionally displays a button to scroll to the bottom.

```vue
<script setup lang="ts">
import { useStickToBottom } from 'vue-stick-to-bottom'

const { scrollRef, contentRef, isAtBottom, scrollToBottom } = useStickToBottom({
  damping: 0.7,
  stiffness: 0.05,
  mass: 1.25,
})
</script>

<template>
  <div style="display: flex; flex-direction: column; height: 100vh;">
    <!-- Scroll container -->
    <div
      ref="scrollRef"
      style="overflow: auto; flex: 1; min-height: 0;"
    >
      <div ref="contentRef">
        <div v-for="message in messages" :key="message.id">
          {{ message.text }}
        </div>
      </div>
    </div>

    <!-- Scroll-to-bottom button -->
    <button
      v-if="!isAtBottom"
      @click="scrollToBottom()"
    >
      ↓ New messages
    </button>
  </div>
</template>
```

--------------------------------

### Vue Component Example: Basic Scroll to Bottom

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/composable-use-stick-to-bottom.md

Demonstrates how to use the `scrollToBottom` function within a Vue component to scroll to the bottom when a new message is received. It logs whether the scroll was successful or cancelled.

```vue
<script setup>
const { scrollToBottom } = useStickToBottom()

const handleNewMessage = async () => {
  const scrolled = await scrollToBottom()
  if (scrolled) {
    console.log('Scrolled to bottom')
  } else {
    console.log('Scroll was cancelled by user')
  }
}
</script>
```

--------------------------------

### Advanced: Injecting StickToBottomContext using Injection Key

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/context-stick-to-bottom.md

Shows how to manually inject the context using `StickToBottomKey` and `inject`. This is an advanced use case and `useStickToBottomContext()` is generally recommended for its built-in error handling.

```typescript
import { StickToBottomKey } from 'vue-stick-to-bottom'
import { inject } from 'vue'

// Direct injection (not recommended unless you need null handling)
const context = inject(StickToBottomKey, null)
if (!context) {
  console.error('Not inside StickToBottom')
}
```

--------------------------------

### Import createStickToBottomEngine Function

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/exports-overview.md

Import the createStickToBottomEngine factory function for low-level control over the stick-to-bottom engine. This is rarely needed and typically used for very specific scenarios or non-Vue environments.

```typescript
import { createStickToBottomEngine } from 'vue-stick-to-bottom'

const engine = createStickToBottomEngine(options?)
```

--------------------------------

### StickToBottom with Custom Mass

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/component-stick-to-bottom.md

Demonstrates adjusting the 'mass' prop to influence the perceived weight and inertia of the animation. Lower mass leads to quicker movement, while higher mass results in slower, heavier motion.

```vue
<!-- Light, snappy animation -->
<StickToBottom :mass="0.8">...</StickToBottom>

<!-- Heavy, slower animation -->
<StickToBottom :mass="2.0">...</StickToBottom>
```

--------------------------------

### StickToBottom with Custom Stiffness

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/component-stick-to-bottom.md

Shows how to modify the 'stiffness' prop to alter the animation's acceleration. Lower values create smoother, slower curves, while higher values result in a snappier feel.

```vue
<!-- Snappier, faster acceleration -->
<StickToBottom :stiffness="0.1">...</StickToBottom>

<!-- Smoother, slower acceleration -->
<StickToBottom :stiffness="0.03">...</StickToBottom>
```

--------------------------------

### Custom Spring for Resize (Slower)

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/configuration.md

Use a custom spring configuration for resize animations, specifically tuned to be slower than the default or initial scroll animations.

```vue
<StickToBottom :resize="{ damping: 0.8, stiffness: 0.03, mass: 1.5 }">
  ...
</StickToBottom>
```

--------------------------------

### StickToBottomEngine Interface

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/exports-overview.md

The low-level engine interface provides direct control over the stick-to-bottom functionality. It allows for attaching scroll elements, detaching, setting options, and retrieving state.

```APIDOC
## StickToBottomEngine Interface

Low-level engine interface.

```typescript
interface StickToBottomEngine {
  attach: (scrollElement: HTMLElement, contentElement: HTMLElement) => void
  detach: () => void
  destroy: () => void
  setOptions: (options: Partial<StickToBottomOptions>) => void
  getState: () => StickToBottomPublicState
  onChange: (listener: (state: StickToBottomPublicState) => void) => () => void
  scrollToBottom: ScrollToBottom
  stopScroll: StopScroll
}
```
```

--------------------------------

### Chat Application Configuration Preset

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/configuration.md

Use this configuration for responsive chat interfaces. It balances animation smoothness with responsiveness.

```typescript
const chatConfig = {
  damping: 0.7,
  stiffness: 0.05,
  mass: 1.25,
  resize: 'smooth',
  initial: 'smooth',
}
```

--------------------------------

### Composable with Types

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/api-reference/exports-overview.md

Illustrates importing the useStickToBottom composable along with its associated types for options and return values.

```typescript
import { useStickToBottom } from 'vue-stick-to-bottom'
import type { UseStickToBottomReturn, StickToBottomOptions } from 'vue-stick-to-bottom'

const options: StickToBottomOptions = { damping: 0.7 }
const result: UseStickToBottomReturn = useStickToBottom(options)
```

--------------------------------

### Custom Spring for Initial Scroll (Faster)

Source: https://github.com/cwandev/vue-stick-to-bottom/blob/main/_autodocs/configuration.md

Apply custom spring parameters for the initial scroll animation, tuned to be faster than the default.

```vue
<StickToBottom :initial="{ damping: 0.6, stiffness: 0.1, mass: 0.9 }">
  ...
</StickToBottom>
```