### Example Usage of RangeOptions

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/types.md

Illustrates how to instantiate RangeOptions with specific start and end dates, including min/max date constraints. This configuration synchronizes the start and end date managers.

```typescript
const rangeOptions: RangeOptions = {
  from: {
    date: new Date("2024-01-01"),
    minDate: new Date("2020-01-01")
  },
  to: {
    date: new Date(),
    maxDate: $NOW
  }
};
```

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

### Solid DateTime Input Example

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Solid.md

A complete example demonstrating how to use the `useTimescape` hook to create a reactive date and time input component in Solid.js.

```typescript
import { createEffect } from "solid-js";
import { useTimescape } from "timescape/solid";

function DateTimeInput() {
  const { getRootProps, getInputProps, options, ampm, update } = useTimescape({
    date: new Date(),
    hour12: true,
  });

  createEffect(() => {
    console.log("Date changed:", options.date);
  });

  return (
    <div {...getRootProps()}>
      <input {...getInputProps("months")} placeholder="MM" />
      <span>/
      <input {...getInputProps("days")} placeholder="DD" />
      <span>/
      <input {...getInputProps("years")} placeholder="YYYY" />
      <span> 
      <input {...getInputProps("hours")} placeholder="HH" />
      <span>:
      <input {...getInputProps("minutes")} placeholder="MM" />
      <select {...ampm.getSelectProps()}>
        <option value="am">AM</option>
        <option value="pm">PM</option>
      </select>
      <button onclick={() => update('date', new Date())}>
        Reset to today
      </button>
    </div>
  );
}
```

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

### Example Options Initialization

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/types.md

Demonstrates how to initialize the Options object with various settings for TimescapeManager.

```typescript
const options: Options = {
  date: new Date(),
  minDate: new Date("2020-01-01"),
  maxDate: $NOW,
  hour12: true,
  wrapAround: true,
  disallowPartial: false
};
```

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

### Install Timescape with npm, yarn, or pnpm

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/API-INDEX.md

Provides commands for installing the Timescape library using different package managers. All frameworks are optional peer dependencies.

```bash
npm install timescape
# or
yarn add timescape
# or
pnpm add timescape
```

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

### Example Renderings of Date/Time Fields

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/core-concepts.md

Demonstrates how different date/time fields can be rendered using HTML input elements with data-type attributes. These examples show various formats like MM/DD/YYYY HH:MM, YYYY-MM-DD, and HH:MM:SS.mmm.

```html
<!-- MM/DD/YYYY HH:MM -->
<input data-type="months" /> <span>/</span>
<input data-type="days" /> <span>/</span>
<input data-type="years" /> <span> </span>
<input data-type="hours" /> <span>:</span>
<input data-type="minutes" />
```

```html
<!-- YYYY-MM-DD -->
<input data-type="years" /> <span>-</span>
<input data-type="months" /> <span>-</span>
<input data-type="days" />
```

```html
<!-- HH:MM:SS.mmm -->
<input data-type="hours" /> <span>:</span>
<input data-type="minutes" /> <span>:</span>
<input data-type="seconds" /> <span>.</span>
<input data-type="milliseconds" />
```

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

### Date Range Picker Example with useTimescapeRange

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Preact.md

Demonstrates how to use the useTimescapeRange hook to build a date range picker component in Preact. It shows how to get root properties and input properties for both the start and end date inputs.

```typescript
import { useTimescapeRange } from "timescape/preact";

function DateRangePicker() {
  const { getRootProps, from, to } = useTimescapeRange({
    from: { date: new Date("2024-01-01") },
    to: { date: new Date() },
  });

  return (
    <div {...getRootProps()}>
      <div>
        <h3>From</h3>
        <input {...from.getInputProps("months")} />
        <span>/</span>
        <input {...from.getInputProps("days")} />
        <span>/</span>
        <input {...from.getInputProps("years")} />
      </div>
      <div>
        <h3>To</h3>
        <input {...to.getInputProps("months")} />
        <span>/</span>
        <input {...to.getInputProps("days")} />
        <span>/</span>
        <input {...to.getInputProps("years")} />
      </div>
    </div>
  );
}
```

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

### AmPmHandler Usage Example

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/types.md

Demonstrates how to use the AmPmHandler to set, toggle, and retrieve AM/PM state and select properties.

```typescript
const { ampm } = useTimescape({ hour12: true });

ampm.set("pm");           // Set to PM
ampm.toggle();            // Toggle to AM
ampm.value;               // "am" | "pm" | undefined
const selectProps = ampm.getSelectProps();
```

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

### Vue Example with useTimescape

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Vue.md

A complete Vue component example demonstrating the use of the `useTimescape` composable for creating a date and time input form. It includes input fields for month, day, year, hour, minute, and AM/PM selection, along with a button to reset the date.

```vue
<template>
  <div :ref="registerRoot()">
    <input 
      :ref="registerElement('months')" 
      placeholder="MM" 
      type="text"
    />
    <span>/
    </span>
    <input 
      :ref="registerElement('days')" 
      placeholder="DD" 
      type="text"
    />
    <span>/
    </span>
    <input 
      :ref="registerElement('years')" 
      placeholder="YYYY" 
      type="text"
    />
    <span> 
    </span>
    <input 
      :ref="registerElement('hours')" 
      placeholder="HH" 
      type="text"
    />
    <span>:
    </span>
    <input 
      :ref="registerElement('minutes')" 
      placeholder="MM" 
      type="text"
    />
    <select :ref="ampm.getSelectProps()">
      <option value="am">AM</option>
      <option value="pm">PM</option>
    </select>
  </div>

  <button @click="options.date = new Date()">Reset to today</button>
</template>

<script setup>
import { useTimescape } from "timescape/vue";
import { watchEffect } from "vue";

const { registerElement, registerRoot, options, ampm } = useTimescape({
  date: new Date(),
  hour12: true,
});

watchEffect(() => {
  console.log("Date changed:", options.value.date);
});
</script>
```

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

### Date Range Picker Example with useTimescapeRange

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/React.md

Demonstrates how to use the useTimescapeRange hook to build a date range picker component in React. It shows how to get props for the root element and individual date inputs, and how to handle date updates.

```typescript
import { useTimescapeRange } from "timescape/react";

function DateRangePicker() {
  const { getRootProps, from, to } = useTimescapeRange({
    from: { date: new Date("2024-01-01") },
    to: { date: new Date() },
  });

  return (
    <div {...getRootProps()}>
      <div>
        <h3>From</h3>
        <input {...from.getInputProps("months")} />
        <span>/</span>
        <input {...from.getInputProps("days")} />
        <span>/</span>
        <input {...from.getInputProps("years")} />
      </div>
      <div>
        <h3>To</h3>
        <input {...to.getInputProps("months")} />
        <span>/</span>
        <input {...to.getInputProps("days")} />
        <span>/</span>
        <input {...to.getInputProps("years")} />
      </div>
    </div>
  );
}
```

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

### React Example with Custom AM/PM Controls

Source: https://github.com/dan-lee/timescape/blob/main/README.md

This example demonstrates integrating custom AM/PM controls within a React component using the `useTimescape` hook. It showcases using `ampm.getSelectProps()` for a select dropdown, a toggle button, a checkbox, and radio buttons for AM/PM selection.

```tsx
import { useTimescape } from "timescape/react";

function CustomAmPmExample() {
  const { getInputProps, getRootProps, ampm } = useTimescape({
    date: new Date(),
    hour12: true,
  });

  return (
    <div {...getRootProps()}>
      <input {...getInputProps("hours")} />
      <span>:</span>
      <input {...getInputProps("minutes")} />

      {/* Example 1: Select with getSelectProps() */}
      <select {...ampm.getSelectProps()}>
        <option value="am">AM</option>
        <option value="pm">PM</option>
      </select>

      {/* Example 2: Toggle button */}
      <button onClick={ampm.toggle}>
        {ampm.value === "am" ? "☀️ AM" : "🌙 PM"}
      </button>

      {/* Example 3: Checkbox */}
      <input
        type="checkbox"
        checked={ampm.value === "pm"}
        onChange={ampm.toggle}
      />

      {/* Example 4: Radio buttons */}
      <label>
        <input
          type="radio"
          checked={ampm.value === "am"}
          onChange={() => ampm.set("am")}
        />
        AM
      </label>
      <label>
        <input
          type="radio"
          checked={ampm.value === "pm"}
          onChange={() => ampm.set("pm")}
        />
        PM
      </label>
    </div>
  );
}
```

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

### Date Range Picker with TimescapeRange

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/README.md

This example demonstrates how to use `useTimescapeRange` for selecting a date range. It provides separate input configurations for the start ('from') and end ('to') dates.

```typescript
const { getRootProps, from, to } = useTimescapeRange({
  from: { date: new Date("2024-01-01") },
  to: { date: new Date() },
});

return (
  <div {...getRootProps()}>
    <div>
      <input {...from.getInputProps("months")} /> /
      <input {...from.getInputProps("days")} /> /
      <input {...from.getInputProps("years")} />
    </div>
    <div>
      <input {...to.getInputProps("months")} /> /
      <input {...to.getInputProps("days")} /> /
      <input {...to.getInputProps("years")} />
    </div>
  </div>
);
```

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

### Install Timescape with npm

Source: https://github.com/dan-lee/timescape/blob/main/README.md

Use this command to add Timescape to your project using npm.

```shell
npm install --save timescape
```

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

### Install Timescape with yarn

Source: https://github.com/dan-lee/timescape/blob/main/README.md

Use this command to add Timescape to your project using yarn.

```shell
yarn add timescape
```

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

### Install Timescape with pnpm

Source: https://github.com/dan-lee/timescape/blob/main/README.md

Use this command to add Timescape to your project using pnpm.

```shell
pnpm add timescape
```

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

### Vue.js Example for useTimescapeRange

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Vue.md

This example demonstrates how to use the useTimescapeRange composable to create synchronized date range inputs in a Vue.js template. It includes input fields for the 'from' and 'to' dates and displays the selected range.

```vue
<template>
  <div :ref="registerRangeRoot()">
    <div>
      <h3>From</h3>
      <input :ref="from.registerElement('months')" placeholder="MM" />
      <span>/
      <input :ref="from.registerElement('days')" placeholder="DD" />
      <span>/
      <input :ref="from.registerElement('years')" placeholder="YYYY" />
    </div>
    <div>
      <h3>To</h3>
      <input :ref="to.registerElement('months')" placeholder="MM" />
      <span>/
      <input :ref="to.registerElement('days')" placeholder="DD" />
      <span>/
      <input :ref="to.registerElement('years')" placeholder="YYYY" />
    </div>
  </div>

  <p v-if="from.options.date && to.options.date">
    Range: {{ from.options.date.toLocaleDateString() }} to {{ to.options.date.toLocaleDateString() }}
  </p>
</template>

<script setup>
import { useTimescapeRange } from "timescape/vue";

const { registerRangeRoot, from, to } = useTimescapeRange({
  from: { date: new Date("2024-01-01") },
  to: { date: new Date() },
});
</script>
```

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

### Preact DateTimeInput Example

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Preact.md

Example demonstrating how to use the `useTimescape` hook in a Preact component to create a date and time input. It utilizes `effect` from `@preact/signals` to log date changes.

```typescript
import { effect } from "@preact/signals";
import { useTimescape } from "timescape/preact";

function DateTimeInput() {
  const { getRootProps, getInputProps, options, ampm } = useTimescape({
    date: new Date(),
    hour12: true,
  });

  effect(() => {
    console.log("Date changed:", options.value.date);
  });

  return (
    <div {...getRootProps()}>
      <input {...getInputProps("months")} placeholder="MM" />
      <span>/</span>
      <input {...getInputProps("days")} placeholder="DD" />
      <span>/</span>
      <input {...getInputProps("years")} placeholder="YYYY" />
      <span> </span>
      <input {...getInputProps("hours")} placeholder="HH" />
      <span>:</span>
      <input {...getInputProps("minutes")} placeholder="MM" />
      <select {...ampm.getSelectProps()}>
        <option value="am">AM</option>
        <option value="pm">PM</option>
      </select>
    </div>
  );
}
```

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

### Date Range Picker Example with useTimescapeRange

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Solid.md

Demonstrates how to use the useTimescapeRange hook to create a functional date range picker component in Solid.js. It shows how to bind input elements and display the selected range.

```typescript
import { useTimescapeRange } from "timescape/solid";

function DateRangePicker() {
  const { getRootProps, from, to } = useTimescapeRange({
    from: { date: new Date("2024-01-01") },
    to: { date: new Date() },
  });

  return (
    <div {...getRootProps()}>
      <div>
        <h3>From</h3>
        <input {...from.getInputProps("months")} />
        <span>/</span>
        <input {...from.getInputProps("days")} />
        <span>/</span>
        <input {...from.getInputProps("years")} />
      </div>
      <div>
        <h3>To</h3>
        <input {...to.getInputProps("months")} />
        <span>/</span>
        <input {...to.getInputProps("days")} />
        <span>/</span>
        <input {...to.getInputProps("years")} />
      </div>
      <p>
        Range: {from.options.date?.toLocaleDateString()} to {to.options.date?.toLocaleDateString()}
      </p>
    </div>
  );
}
```

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

### Full Svelte Example with createTimescape

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Svelte.md

A complete Svelte component demonstrating the usage of `createTimescape` for building a date and time input. It utilizes `inputProps` for input fields, `rootProps` for the container, and manages the `options` store, including AM/PM selection and a button to reset the date to today.

```svelte
<script lang="ts">
import { createTimescape, NOW } from "timescape/svelte";

const { inputProps, rootProps, options, update, ampm } = createTimescape({
  date: new Date(),
  hour12: true,
  minDate: NOW,
});

function handleDateChange() {
  options.update(prev => ({
    ...prev,
    date: new Date(),
  }));
}
</script>

<div use:rootProps>
  <input use:inputProps={'months'} placeholder="MM" />
  <span>/
  <input use:inputProps={'days'} placeholder="DD" />
  <span>/
  <input use:inputProps={'years'} placeholder="YYYY" />
  <span> 
  <input use:inputProps={'hours'} placeholder="HH" />
  <span>:
  <input use:inputProps={'minutes'} placeholder="MM" />
  <select {...ampm.getSelectProps()}>
    <option value="am">AM</option>
    <option value="pm">PM</option>
  </select>
</div>

{#if $options.date}
  <p>Selected: {$options.date.toLocaleDateString()}</p>
{/if}

<button on:click={handleDateChange}>Set to today</button>
```

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

### React DateTime Input Example

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/React.md

A complete React component demonstrating the use of the useTimescape hook to create a functional date and time input.

```typescript
import { useTimescape } from "timescape/react";

function DateTimeInput() {
  const { getRootProps, getInputProps, options, ampm } = useTimescape({
    date: new Date(),
    hour12: true,
    onChangeDate: (date) => {
      console.log("Date changed:", date);
    },
  });

  return (
    <div {...getRootProps()}>
      <input {...getInputProps("months")} placeholder="MM" />
      <span>/</span>
      <input {...getInputProps("days")} placeholder="DD" />
      <span>/</span>
      <input {...getInputProps("years")} placeholder="YYYY" />
      <span> </span>
      <input {...getInputProps("hours")} placeholder="HH" />
      <span>:</span>
      <input {...getInputProps("minutes")} placeholder="MM" />
      <select {...ampm.getSelectProps()}>
        <option value="am">AM</option>
        <option value="pm">PM</option>
      </select>
    </div>
  );
}
```

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

### RangeOptions

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/types.md

Configuration for paired start/end timescape instances. It allows setting options for both the start ('from') and end ('to') date managers, ensuring they remain synchronized.

```APIDOC
## RangeOptions

### Description
Configuration for paired start/end timescape instances. It allows setting options for both the start ('from') and end ('to') date managers, ensuring they remain synchronized.

### Type Definition
```typescript
type RangeOptions = {
  from?: Options & { date?: Date };
  to?: Options & { date?: Date };
};
```

### Properties
#### from
- **Type**: Options
- **Description**: Configuration for start date manager.

#### to
- **Type**: Options
- **Description**: Configuration for end date manager.

Both managers are automatically synchronized: the start date cannot exceed the end date, and vice versa.

### Used in
- `useTimescapeRange()`
- `useTimescapeRange()` (framework-specific)

### Example
```typescript
const rangeOptions: RangeOptions = {
  from: {
    date: new Date("2024-01-01"),
    minDate: new Date("2020-01-01")
  },
  to: {
    date: new Date(),
    maxDate: $NOW
  }
};
```
```

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

### Date and Time Input with Timescape

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/README.md

This example shows how to include time input alongside the date. Configure `hour12: false` for 24-hour format. It adds inputs for hours and minutes.

```typescript
const { getRootProps, getInputProps } = useTimescape({
  date: new Date(),
  hour12: false,
});

return (
  <div {...getRootProps()}>
    <input {...getInputProps("months")} /> /
    <input {...getInputProps("days")} /> /
    <input {...getInputProps("years")} />
    <input {...getInputProps("hours")} /> :
    <input {...getInputProps("minutes")} />
  </div>
);
```

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

### TimescapeManager Constructor

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/API-INDEX.md

Initializes a new instance of the TimescapeManager. It can be optionally initialized with a starting date and configuration options.

```APIDOC
## new TimescapeManager(initialDate?, options?)

### Description
Initializes a new instance of the TimescapeManager. It can be optionally initialized with a starting date and configuration options.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **initialDate** (Date) - Optional - The initial date to set for the manager.
- **options** (Options) - Optional - Configuration options for the manager.
```

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

### Example Usage of STOP_EVENT_PROPAGATION

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/types.md

Demonstrates how to use STOP_EVENT_PROPAGATION within a callback to conditionally stop further event processing.

```typescript
import { STOP_EVENT_PROPAGATION } from "timescape";

manager.on("changeDate", (date) => {
  if (date && date > someLimit) {
    manager.date = someLimit;
    return STOP_EVENT_PROPAGATION;
  }
});
```

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

### Callback with Propagation Control Example

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/types.md

Shows how to use a callback function to conditionally stop event propagation using STOP_EVENT_PROPAGATION.

```typescript
import { STOP_EVENT_PROPAGATION } from "timescape";

manager.on("changeDate", (date) => {
  if (someCondition) {
    return STOP_EVENT_PROPAGATION; // Stop other handlers
  }
});
```

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

### Svelte Timescape Range Example

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Svelte.md

This Svelte component demonstrates the usage of `createTimescapeRange` to set up date inputs for a range selection. It binds input elements using `use:fromInputProps` and `use:toInputProps`, and displays the selected date range.

```svelte
<script lang="ts">
import { createTimescapeRange } from "timescape/svelte";

const {
  rangeRootProps,
  fromInputProps,
  toInputProps,
  from,
  to,
} = createTimescapeRange({
  from: { date: new Date("2024-01-01") },
  to: { date: new Date() },
});
</script>

<div use:rangeRootProps>
  <div>
    <h3>From</h3>
    <input use:fromInputProps={'months'} placeholder="MM" />
    <span>/
    <input use:fromInputProps={'days'} placeholder="DD" />
    <span>/
    <input use:fromInputProps={'years'} placeholder="YYYY" />
  </div>
  <div>
    <h3>To</h3>
    <input use:toInputProps={'months'} placeholder="MM" />
    <span>/
    <input use:toInputProps={'days'} placeholder="DD" />
    <span>/
    <input use:toInputProps={'years'} placeholder="YYYY" />
  </div>
</div>

{#if $from.options.date && $to.options.date}
  <p>
    Range: {$from.options.date.toLocaleDateString()} to {$to.options.date.toLocaleDateString()}
  </p>
{/if}
```

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

### Create Timescape Range Store

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Svelte.md

Use `createTimescapeRange` to initialize a store for managing paired start and end date inputs. It provides actions to bind inputs and root elements, and exposes writable stores for date options.

```typescript
export function createTimescapeRange(options?: RangeOptions): {
  fromInputProps: (element: HTMLInputElement, type: DateType) => void;
  toInputProps: (element: HTMLInputElement, type: DateType) => void;
  rangeRootProps: (element: HTMLElement) => void;
  from: { inputProps: Function; options: Writable<Options>; update: Function };
  to: { inputProps: Function; options: Writable<Options>; update: Function };
}
```

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

### createTimescapeRange

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Svelte.md

Creates paired start and end timescape instances for date range selection. It returns functions to bind to input elements and a root element, along with stores for managing the date options and update functions.

```APIDOC
## createTimescapeRange Store

Create paired start/end timescape instances for date range selection.

```typescript
export function createTimescapeRange(options?: RangeOptions): {
  fromInputProps: (element: HTMLInputElement, type: DateType) => void;
  toInputProps: (element: HTMLInputElement, type: DateType) => void;
  rangeRootProps: (element: HTMLElement) => void;
  from: { inputProps: Function; options: Writable<Options>; update: Function };
  to: { inputProps: Function; options: Writable<Options>; update: Function };
}
```

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| options.from | Options | Start date options |
| options.to | Options | End date options |

### Return Object

**fromInputProps(element, type) / toInputProps(element, type)**

Action functions to register inputs for start/end dates. Use with `use:fromInputProps={'fieldType'}` or `use:toInputProps={'fieldType'}`.

**rangeRootProps(element)**

Action function to register the root container for both managers.

**from / to**

Each contains:
- `inputProps(element, type)` — Register input for start/end date
- `options` — Writable store for start/end options
- `update(fn)` — Update start/end options

Both managers are automatically synchronized: the start date cannot be after the end date, and vice versa.

### Example

```svelte
<script lang="ts">
import { createTimescapeRange } from "timescape/svelte";

const {
  rangeRootProps,
  fromInputProps,
  toInputProps,
  from,
  to,
} = createTimescapeRange({
  from: { date: new Date("2024-01-01") },
  to: { date: new Date() },
});
</script>

<div use:rangeRootProps>
  <div>
    <h3>From</h3>
    <input use:fromInputProps={'months'} placeholder="MM" />
    <span>/</span>
    <input use:fromInputProps={'days'} placeholder="DD" />
    <span>/</span>
    <input use:fromInputProps={'years'} placeholder="YYYY" />
  </div>
  <div>
    <h3>To</h3>
    <input use:toInputProps={'months'} placeholder="MM" />
    <span>/</span>
    <input use:toInputProps={'days'} placeholder="DD" />
    <span>/</span>
    <input use:toInputProps={'years'} placeholder="YYYY" />
  </div>
</div>

{#if $from.options.date && $to.options.date}
  <p>
    Range: {$from.options.date.toLocaleDateString()} to {$to.options.date.toLocaleDateString()}
  </p>
{/if}
```
```

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

### Main Entry Point (`timescape`)

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/API-INDEX.md

Provides access to the core headless manager class and utility functions for date/time state management.

```APIDOC
## Core Exports

### Classes

- **TimescapeManager** — Core headless manager class for date/time state and input registration

### Functions

- **marry(from, to)** — Synchronize two TimescapeManager instances for date range selection

### Constants

- **$NOW** — Special value for dynamic min/max dates
- **STOP_EVENT_PROPAGATION** — Symbol to halt event propagation in callbacks

### Types

- **DateType** — Union of all date/time field types
- **Options** — Configuration object for manager initialization
- **RangeOptions** — Configuration for paired managers
- **Callback** — Event listener callback type
- **$NOW (type)** — Type for the $NOW constant
```

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

### React Timescape Integration

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/00-START-HERE.md

Use the `useTimescape` hook to integrate Timescape with your React application. This example shows how to get input props for months, days, years, hours, and minutes, along with an AM/PM selector.

```typescript
import { useTimescape } from "timescape/react";

function App() {
  const { getRootProps, getInputProps, ampm } = useTimescape({
    date: new Date(),
    hour12: true,
  });

  return (
    <div {...getRootProps()}>
      <input {...getInputProps("months")} /> /
      <input {...getInputProps("days")} /> /
      <input {...getInputProps("years")} /> at
      <input {...getInputProps("hours")} /> :
      <input {...getInputProps("minutes")} />
      <select {...ampm.getSelectProps()}>
        <option value="am">AM</option>
        <option value="pm">PM</option>
      </select>
    </div>
  );
}
```

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

### Initialize TimescapeManager with Basic Date and Time Settings

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/configuration.md

Demonstrates basic initialization of TimescapeManager with a specific date and time format settings. Use for standard date/time input scenarios.

```typescript
const manager = new TimescapeManager(new Date(), {
  hour12: false,
  digits: "2-digit"
});
```

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

### useTimescapeRange Hook

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Preact.md

Creates paired start and end timescape instances for date range selection. It synchronizes the start and end dates, ensuring the start date is not after the end date, and vice versa.

```APIDOC
## useTimescapeRange Hook

### Description

Creates paired start/end timescape instances for date range selection. This hook synchronizes the start and end date managers automatically.

### Signature

```typescript
export function useTimescapeRange(options?: RangeOptions): {
  getRootProps: () => RootProps;
  from: { getInputProps: Function; options: Signal<Options> };
  to: { getInputProps: Function; options: Signal<Options> };
}
```

### Parameters

#### Options Object (`options`)

- **options.from** (Options) - Required - Start date options.
- **options.to** (Options) - Required - End date options.

### Return Object

- **getRootProps()** - Function - Registers both managers on the same root element.
- **from** - Object - Contains properties for the start date input.
  - `getInputProps(type, opts?)` - Function - Registers input for the start date.
  - `options` - Signal<Options> - Signal containing the start date options.
- **to** - Object - Contains properties for the end date input.
  - `getInputProps(type, opts?)` - Function - Registers input for the end date.
  - `options` - Signal<Options> - Signal containing the end date options.

### Example

```typescript
import { useTimescapeRange } from "timescape/preact";

function DateRangePicker() {
  const { getRootProps, from, to } = useTimescapeRange({
    from: { date: new Date("2024-01-01") },
    to: { date: new Date() },
  });

  return (
    <div {...getRootProps()}>
      <div>
        <h3>From</h3>
        <input {...from.getInputProps("months")} />
        <span>/</span>
        <input {...from.getInputProps("days")} />
        <span>/</span>
        <input {...from.getInputProps("years")} />
      </div>
      <div>
        <h3>To</h3>
        <input {...to.getInputProps("months")} />
        <span>/</span>
        <input {...to.getInputProps("days")} />
        <span>/</span>
        <input {...to.getInputProps("years")} />
      </div>
    </div>
  );
}
```
```

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

### Timescape Package Structure

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/API-INDEX.md

Illustrates the modular structure of the Timescape library, showing the main entry points for different framework integrations.

```bash
timescape/
├── index.js (TimescapeManager, types, utilities)
├── react.js (React integration)
├── preact.js (Preact integration)
├── vue.js (Vue integration)
├── svelte.js (Svelte integration)
└── solid.js (Solid integration)
```

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

### Options

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/types.md

Configuration object for TimescapeManager initialization. Defines various settings for date and time management.

```APIDOC
## Options

### Description
Configuration object for TimescapeManager initialization. Defines various settings for date and time management.

### Type Definition
```typescript
type Options = {
  date?: Date;
  minDate?: Date | $NOW;
  maxDate?: Date | $NOW;
  hour12?: boolean;
  digits?: "numeric" | "2-digit";
  wrapAround?: boolean;
  snapToStep?: boolean;
  wheelControl?: boolean;
  disallowPartial?: boolean;
};
```

### Properties
| Property | Type | Default | Description |
|---|---|---|---|
| date | Date | undefined | Initial date value |
| minDate | Date \| $NOW | undefined | Minimum selectable date (can be dynamic with $NOW) |
| maxDate | Date \| $NOW | undefined | Maximum selectable date (can be dynamic with $NOW) |
| hour12 | boolean | false | Use 12-hour format with AM/PM |
| digits | "numeric" \| "2-digit" | "2-digit" | Display format for days/months (1 or 01) |
| wrapAround | boolean | false | Wrap increment/decrement at boundaries |
| snapToStep | boolean | false | Snap to step attribute when using arrow keys |
| wheelControl | boolean | false | Enable mouse wheel input |
| disallowPartial | boolean | false | Require all fields completed before emit |

### Used in
- `TimescapeManager` constructor
- All framework integration functions
- Refs/stores returned by integration APIs

### Example
```typescript
const options: Options = {
  date: new Date(),
  minDate: new Date("2020-01-01"),
  maxDate: $NOW,
  hour12: true,
  wrapAround: true,
  disallowPartial: false
};
```
```

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

### useTimescapeRange Hook

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Solid.md

The useTimescapeRange hook creates paired start and end timescape instances for date range selection. It synchronizes the start and end dates, ensuring that one cannot be set after the other.

```APIDOC
## useTimescapeRange Hook

### Description

Creates paired start/end timescape instances for date range selection. This hook synchronizes the start and end date managers automatically, preventing invalid ranges (e.g., start date after end date).

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Method

None (Hook)

### Endpoint

None (Hook)

### Parameters

- **options** (RangeOptions) - Optional - An object containing options for the start and end date managers.
  - **options.from** (Options) - Optional - Start date options.
  - **options.to** (Options) - Optional - End date options.

### Return Object

- **getRootProps()** (Function) - Returns props to be spread onto a root element to register both date managers.
- **from** (Object) - Manager for the start date.
  - **getInputProps(type)** (Function) - Returns props for an input element to manage the start date.
  - **options** (Store<Options>) - The current start date options.
  - **update(key, value)** (SetStoreFunction) - Function to update specific keys within the start date options.
- **to** (Object) - Manager for the end date.
  - **getInputProps(type)** (Function) - Returns props for an input element to manage the end date.
  - **options** (Store<Options>) - The current end date options.
  - **update(key, value)** (SetStoreFunction) - Function to update specific keys within the end date options.

### Example

```typescript
import { useTimescapeRange } from "timescape/solid";

function DateRangePicker() {
  const { getRootProps, from, to } = useTimescapeRange({
    from: { date: new Date("2024-01-01") },
    to: { date: new Date() },
  });

  return (
    <div {...getRootProps()}>
      <div>
        <h3>From</h3>
        <input {...from.getInputProps("months")} />
        <span>/</span>
        <input {...from.getInputProps("days")} />
        <span>/</span>
        <input {...from.getInputProps("years")} />
      </div>
      <div>
        <h3>To</h3>
        <input {...to.getInputProps("months")} />
        <span>/</span>
        <input {...to.getInputProps("days")} />
        <span>/</span>
        <input {...to.getInputProps("years")} />
      </div>
      <p>
        Range: {from.options.date?.toLocaleDateString()} to {to.options.date?.toLocaleDateString()}
      </p>
    </div>
  );
}
```
```

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

### Solid Configuration with createEffect

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/configuration.md

Configure Timescape for Solid applications. Use `createEffect` to monitor date changes.

```typescript
const { options } = useTimescape({ date: new Date() });

createEffect(() => {
  console.log("Date changed:", options.date);
});
```

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

### Input with Step and Snap-to-Step

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/core-concepts.md

Shows an HTML input element configured with `step` and `snapToStep`. When `snapToStep` is true, arrow key increments will snap the value to the nearest multiple of the `step` value.

```html
<!-- With step="5" and snapToStep: true -->
<input data-type="minutes" step="5" />

<!-- User at 23 minutes presses ArrowUp → snaps to 25 -->
<!-- User at 28 minutes presses ArrowUp → snaps to 30 -->
```

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

### get

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/DateUtilities.md

Retrieves the numeric value of a specified time unit from a Date object.

```APIDOC
## get

Get the numeric value of a specific time unit.

```typescript
export function get(date: Date, type: DateType): number
```

### Parameters
#### Path Parameters
- **date** (Date) - Required - Source date
- **type** (DateType) - Required - Unit to retrieve: "days", "months", "years", "hours", "minutes", "seconds", "milliseconds", "am/pm"

### Returns
Numeric value of the unit.

### Notes
- Months return 0-based values (0 = January, 11 = December).
- Days return 1-based values (1-31).
- For "am/pm": Returns the hour value (0-23).

### Example
```typescript
const date = new Date("2024-06-15T14:30:45");
get(date, "years");        // 2024
get(date, "months");       // 5 (June, 0-based)
get(date, "days");         // 15
get(date, "hours");        // 14
get(date, "minutes");      // 30
get(date, "seconds");      // 45
get(date, "am/pm");        // 14 (PM)
```
```

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

### Initialize and Register TimescapeManager

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/TimescapeManager.md

Demonstrates how to create a TimescapeManager instance, register input elements for date and time components, and set up event listeners. This is useful for integrating Timescape into your application's UI.

```typescript
import TimescapeManager from "timescape";

const container = document.createElement("div");
container.id = "timescape";
container.innerHTML = `
  <input data-type="days" placeholder="dd" />
  <span>/</span>
  <input data-type="months" placeholder="mm" />
  <span>/</span>
  <input data-type="years" placeholder="yyyy" />
  <span> </span>
  <input data-type="hours" placeholder="--" />
  <span>:</span>
  <input data-type="minutes" placeholder="--" />
`;
document.body.appendChild(container);

const manager = new TimescapeManager(new Date(), {
  hour12: false,
  minDate: new Date("2020-01-01"),
  disallowPartial: true
});

manager.registerRoot(container);

manager.registerElement(
  container.querySelector('[data-type="days"]'),
  "days"
);
manager.registerElement(
  container.querySelector('[data-type="months"]'),
  "months"
);
manager.registerElement(
  container.querySelector('[data-type="years"]'),
  "years"
);
manager.registerElement(
  container.querySelector('[data-type="hours"]'),
  "hours"
);
manager.registerElement(
  container.querySelector('[data-type="minutes"]'),
  "minutes"
);

manager.on("changeDate", (date) => {
  console.log("Selected date:", date);
});

// Clean up
manager.remove();
```

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

### Initialize and Register TimescapeManager

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/README.md

Instantiate TimescapeManager with initial date and options, then register root and input elements. Listen for date changes.

```typescript
import TimescapeManager from "timescape";

const manager = new TimescapeManager(new Date(), {
  hour12: true,
  minDate: new Date("2020-01-01"),
  disallowPartial: false
});

manager.registerRoot(containerElement);
manager.registerElement(inputElement, "days");
manager.registerElement(inputElement, "months");
manager.registerElement(inputElement, "years");

manager.on("changeDate", (date) => {
  console.log("Date changed to:", date);
});
```

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

### TimescapeManager Properties

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/API-INDEX.md

Provides access to various properties of the TimescapeManager for getting and setting its state and behavior.

```APIDOC
## TimescapeManager Properties

### Description
Provides access to various properties of the TimescapeManager for getting and setting its state and behavior.

### Properties
- **date** (getter/setter) - Current date. Returns undefined if incomplete in partial mode.
- **ampm** (getter/setter) - AM/PM state. Only available when hour12 is true.
- **minDate** (getter/setter) - Minimum selectable date.
- **maxDate** (getter/setter) - Maximum selectable date.
- **hour12** (getter/setter) - Boolean indicating whether to use 12-hour format.
- **digits** (getter/setter) - Format for day/month display.
- **wrapAround** (getter/setter) - Boolean indicating whether values should wrap around at boundaries.
- **snapToStep** (getter/setter) - Boolean indicating whether to snap to step attribute.
- **wheelControl** (getter/setter) - Boolean indicating whether to enable mouse wheel input.
- **disallowPartial** (getter/setter) - Boolean indicating whether to require complete dates.
```

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

### Import Main Timescape Package

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/README.md

Import the main TimescapeManager and related utilities for general use.

```typescript
import TimescapeManager, { marry, $NOW, STOP_EVENT_PROPAGATION } from "timescape";
```

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

### Using $NOW Constant in Solid.js

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Solid.md

Demonstrates how to use the special $NOW constant from 'timescape/solid' to set dynamic min/max dates that always refer to the current date and time within a Solid.js component.

```typescript
import { $NOW } from "timescape/solid";

const { getInputProps, getRootProps } = useTimescape({
  minDate: $NOW, // Always current date
});
```

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

### Solid Integration (`timescape/solid`)

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/API-INDEX.md

Provides Solid hooks for integrating Timescape's date/time management into Solid applications.

```APIDOC
## Solid Integration (`timescape/solid`)

### Hooks

- **useTimescape()** — Solid hook for single date/time input
- **useTimescapeRange()** — Solid hook for date range selection

### Exports

- **$NOW**, **DateType**, **Options**, **RangeOptions**
```

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

### Hotel Booking Range

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Range.md

Configures a date range where both start and end dates must be today or later. Dates are synchronized automatically.

```typescript
const today = new Date();
const nextWeek = new Date(today);
nextWeek.setDate(nextWeek.getDate() + 7);

const { from, to, getRootProps } = useTimescapeRange({
  from: { date: today, minDate: $NOW },
  to: { date: nextWeek, minDate: $NOW },
});
```

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

### React Timescape Range Integration

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/README.md

Synchronize two Timescape managers for start and end date selection in React using the useTimescapeRange hook.

```typescript
import { useTimescapeRange } from "timescape/react";

const { getRootProps, from, to } = useTimescapeRange({
  from: { date: new Date("2024-01-01") },
  to: { date: new Date("2024-12-31") },
});

// from.options.date <= to.options.date always maintained
```

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

### Svelte Configuration with Store Subscription

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/configuration.md

Configure Timescape for Svelte applications. Subscribe to the `options` store to observe date changes.

```typescript
const { options } = createTimescape({ date: new Date() });

options.subscribe((value) => {
  console.log("Date changed:", value.date);
});
```

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

### Get Number of Days in Month

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/DateUtilities.md

Use this function to determine the number of days in a specific month of a given date. It accounts for leap years.

```typescript
export function daysInMonth(date: Date): number
```

```typescript
daysInMonth(new Date("2024-02-01")); // 29 (leap year)
daysInMonth(new Date("2024-01-01")); // 31
daysInMonth(new Date("2024-06-01")); // 30
```

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

### Subscribe to focusWrap Event

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/README.md

Handle focus boundary wrapping events. The callback indicates whether the focus moved to the 'start' or 'end' of the input sequence.

```typescript
manager.on("focusWrap", (direction) => {
  console.log("Focus wrapped to:", direction);
});
```

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

### Timescape Solid Import

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Solid.md

Import necessary hooks and constants from the Timescape Solid module.

```typescript
import { useTimescape, useTimescapeRange, $NOW } from "timescape/solid";
```

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

### AM/PM Handler Object

Source: https://github.com/dan-lee/timescape/blob/main/_autodocs/api-reference/Vue.md

Object for managing AM/PM state when 12-hour format is enabled. Provides methods to set, toggle, and get select props.

```typescript
ampm: {
  value: "am" | "pm" | undefined;
  set(value: "am" | "pm"): void;
  toggle(): void;
  getSelectProps(): { value: string; onChange: (e: Event) => void };
}
```