timepicker-ui-mcp 1.0.2 → 2.0.0

package/README.md

@@ -1,45 +1,52 @@
 # timepicker-ui MCP server
 
-An MCP server for `timepicker-ui`. Connect it to Claude Code, Claude Desktop or another MCP client and the model can look up options, events and themes, generate setup snippets and custom themes, and migrate v3 code. Everything it returns comes from the library source, not from the model's memory.
+An MCP server for `timepicker-ui`. Connect it to Claude Code, Claude Desktop or another MCP client and the model can look up options, events, CSS variables and themes, search the reference, generate setup snippets and custom themes, and get migration steps. Options, events, payloads, CSS variables, classes, troubleshooting and the 5.0 rename tables are generated from the library source and the docs site. Themes, modes, plugins, the method list, framework recipes and migration notes are written by hand in `src/data.ts` and `src/content.ts`.
 
-It runs over stdio and needs Node 18 or newer.
+Every tool only reads this reference data and is marked `readOnlyHint`. Deprecated options and events are flagged, and left out of lists unless a tool is asked for them. Results link to the docs at https://timepicker-ui.vercel.app.
+
+It runs over stdio and needs Node 20 or newer. It is built on the MCP TypeScript SDK v2 and serves clients on the 2025 protocol (`initialize`) and on the 2026-07-28 revision.
 
 ## Tools
 
-| Tool                     | Description                                                                             |
-| ------------------------ | --------------------------------------------------------------------------------------- |
-| `list_themes`            | Built-in themes and their CSS import paths.                                             |
-| `list_modes`             | UI modes (`clock`, `wheel`, `compact-wheel`) and the plugin each needs.                 |
-| `list_plugins`           | Optional plugins (range, timezone, wheel) with import paths.                            |
-| `list_events`            | Every EventEmitter event with its payload fields.                                       |
-| `list_api`               | Public instance and static API, plus the `getValue`/`setValue` contract.                |
-| `list_css_classes`       | The `tp-ui-` class names rendered by the templates.                                     |
-| `get_options`            | Grouped options with type, default and description. Optional `group` filter.            |
-| `explain_option`         | Full detail for one option (`group` + `name`).                                          |
-| `get_theme`              | The `--tp-` variables a built-in theme overrides.                                       |
-| `framework_recipe`       | Integration recipe and SSR notes for vanilla, react, next, vue, angular, svelte.        |
-| `migration_guide`        | `v3->v4` field mapping, or the `v4.3->v4.4` / `v4.4->v4.5` changes.                     |
-| `generate_snippet`       | Vanilla JS or React setup (CSS imports and plugin registration).                        |
-| `generate_custom_theme`  | A `[data-theme]` CSS block from `overrides`, or a full scaffold.                        |
-| `validate_time`          | Checks `HH:MM`, `HH:MM:SS`, `h:MM AM/PM` or `h:MM:SS AM/PM` against a 12h or 24h clock. |
-| `validate_disabled_time` | Checks a `clock.disabledTime` config (hours, minutes, seconds, range strings).          |
+| Tool                     | Description                                                                                         |
+| ------------------------ | --------------------------------------------------------------------------------------------------- |
+| `search_reference`       | Keyword search across options, nested fields, events, CSS variables, classes, methods and fixes.    |
+| `get_options`            | Grouped options with type, default, description and nested fields. `group`, `includeDeprecated`.  |
+| `explain_option`         | One option (`group` + `name`, dotted for nested fields such as `disabledTime.ranges`).            |
+| `list_events`            | Events with payload fields. `includeInternal`, `includeDeprecated`.                                |
+| `list_api`               | Instance and static methods with deprecations, plus the `getValue`/`setValue` contract.            |
+| `list_css_variables`     | `--tp-` variables with group and default. `group`, `includeUnread`.                               |
+| `list_css_classes`       | `tp-ui-` class names and state modifiers with example selectors.                                   |
+| `list_themes`            | Built-in themes and their CSS import paths.                                                         |
+| `get_theme`              | The `--tp-` variables a built-in theme sets.                                                       |
+| `list_modes`             | UI modes (`clock`, `wheel`, `compact-wheel`) and the plugin each needs.                             |
+| `list_plugins`           | Optional plugins (range, timezone, wheel) with import paths and registration.                       |
+| `framework_recipe`       | Recipe and SSR notes for vanilla, react, react-wrapper (`timepicker-ui-react`), next, vue, angular, svelte. |
+| `migration_guide`        | `v3->v4`, `v4.3->v4.4`, `v4.4->v4.5` (with every renamed option) or `v4.5->v5` (draft).           |
+| `generate_snippet`       | Vanilla JS or React setup with theme, mode, clock type, seconds and plugins.                        |
+| `generate_custom_theme`  | CSS for a theme applied with `ui.cssClass`, from `overrides` or as a scaffold.                     |
+| `validate_time`          | Checks `HH:MM`, `HH:MM:SS`, `h:MM AM/PM` or `h:MM:SS AM/PM` against a 12h or 24h clock.             |
+| `validate_disabled_time` | Checks a `clock.disabledTime` config (hours, minutes, seconds, range strings).                      |
+
+Wrong arguments, such as an unknown option name, come back with `isError: true` and a hint, so the model can correct the call.
 
 ## Resources
 
-| URI                                  | Description                             |
-| ------------------------------------ | --------------------------------------- |
-| `timepicker-ui://reference`          | Grouped-options summary.                |
-| `timepicker-ui://css-variables`      | Every `--tp-` variable and its default. |
-| `timepicker-ui://custom-theme-guide` | How to author a custom theme.           |
-| `timepicker-ui://troubleshooting`    | Common symptoms, causes and fixes.      |
+| URI                                  | Description                                              |
+| ------------------------------------ | -------------------------------------------------------- |
+| `timepicker-ui://reference`          | Grouped-options summary.                                 |
+| `timepicker-ui://css-variables`      | Every `--tp-` variable with group, default and notes.    |
+| `timepicker-ui://custom-theme-guide` | How to style the picker with `ui.cssClass`.              |
+| `timepicker-ui://troubleshooting`    | The docs troubleshooting entries with fixes and code.    |
 
 ## Prompts
 
-| Prompt               | Argument      | Purpose                                |
-| -------------------- | ------------- | -------------------------------------- |
-| `integrate`          | `framework`   | Walk through a framework integration.  |
-| `build-custom-theme` | `description` | Turn a palette into a theme.           |
-| `migrate-v3-to-v4`   | `code`        | Convert v3 code to v4 grouped options. |
+| Prompt               | Argument      | Purpose                                                  |
+| -------------------- | ------------- | -------------------------------------------------------- |
+| `integrate`          | `framework`   | Walk through a framework integration (with completion).  |
+| `build-custom-theme` | `description` | Turn a palette into a theme.                             |
+| `migrate-v3-to-v4`   | `code`        | Convert v3 code to v4 grouped options.                   |
+| `prepare-for-v5`     | `code`        | Replace deprecated 4.x API with the names 5.0 keeps.     |
 
 ## Build and test
 
@@ -53,9 +60,12 @@ npm run inspect    # open the MCP Inspector against the built server
 
 ## Where the data comes from
 
-`npm run build` first runs `scripts/generate.mjs`. It reads the library source in `../app` and writes `src/generated/*.json`: options and event payloads from `options.d.ts` and `types.d.ts`, the EventEmitter map, the theme stylesheets and `variables.scss`, and the `tp-ui-` classes from the templates.
+`npm run build` first runs `scripts/generate.mjs`, which writes `src/generated/*.json`:
+
+- From the library source in `../app` and the root `package.json`: options with defaults, examples, nested fields and `@deprecated` notes (`options.d.ts`), events and payloads (`EventEmitter.ts`, `types.d.ts`), the variables each built-in theme sets, and the library version.
+- From the docs site in `../docs-app`: CSS variables and classes (`lib/generated/css-reference.json`, built from the published package CSS), the troubleshooting entries, and the renamed and removed tables of the 5.0 migration guide.
 
-The generated JSON is committed, so the server works without the `app/` source next to it. After changing the library, run `npm run build` again to refresh it.
+The generated JSON is committed, so the server works without `app/` and `docs-app/` next to it. A source that is missing keeps its existing JSON. After changing the library or those docs pages, run `npm run build` again. When the CSS changes, regenerate the docs CSS reference first.
 
 ## Adding it to Claude Code
 

package/build/content.js

@@ -1,4 +1,5 @@
-export const FRAMEWORK_NAMES = ['vanilla', 'react', 'next', 'vue', 'angular', 'svelte'];
+export const FRAMEWORK_NAMES = ['vanilla', 'react', 'react-wrapper', 'next', 'vue', 'angular', 'svelte'];
+const WRAPPER_NOTE = 'Render the input inside <div class="tp-ui">. Given a bare input, the picker wraps it in a new div.tp-ui, and destroy() leaves that div in place, which can break the framework when it removes the input.';
 export const FRAMEWORK_RECIPES = {
     vanilla: {
         title: 'Vanilla JS / TS',
@@ -11,65 +12,110 @@ export const FRAMEWORK_RECIPES = {
             "import 'timepicker-ui/main.css';",
             '',
             "const input = document.querySelector('#time');",
-            'const picker = new TimepickerUI(input, { clock: { type: \'24h\' } });',
+            "const picker = new TimepickerUI(input, { clock: { type: '24h' } });",
             'picker.create();',
         ].join('\n'),
+        docs: '/docs/quick-start',
     },
     react: {
         title: 'React',
         notes: [
-            'Construct in an effect after mount; destroy in the cleanup. Never construct during render.',
-            'Empty dependency array so it initializes once. Read values via picker.getValue() or the events.',
-            'There is also an official wrapper: the `timepicker-ui-react` package.',
+            'Construct in an effect after mount and destroy in the cleanup. Never construct during render.',
+            'Empty dependency array so it initializes once. Read values with picker.getValue() or the events.',
+            WRAPPER_NOTE,
+            'The picker sets input.value directly and does not dispatch input or change events, so React onChange never runs. Update state in callbacks.onConfirm or picker.on("confirm", ...).',
+            'The official wrapper `timepicker-ui-react` does this for you: see the react-wrapper recipe.',
         ],
         code: [
             "import { useEffect, useRef } from 'react';",
             "import { TimepickerUI } from 'timepicker-ui';",
             "import 'timepicker-ui/main.css';",
             '',
-            'export function TimePicker() {',
-            '  const ref = useRef<HTMLInputElement>(null);',
+            'export function TimeField() {',
+            '  const inputRef = useRef<HTMLInputElement>(null);',
+            '',
             '  useEffect(() => {',
-            '    if (!ref.current) return;',
-            '    const picker = new TimepickerUI(ref.current, { clock: { type: \'24h\' } });',
+            '    if (!inputRef.current) return;',
+            "    const picker = new TimepickerUI(inputRef.current, { clock: { type: '24h' } });",
             '    picker.create();',
             "    picker.on('confirm', (d) => console.log(d.hour, d.minutes));",
             '    return () => picker.destroy();',
             '  }, []);',
-            '  return <input ref={ref} />;',
+            '',
+            '  return (',
+            '    <div className="tp-ui">',
+            '      <input ref={inputRef} type="text" placeholder="Select time" />',
+            '    </div>',
+            '  );',
+            '}',
+        ].join('\n'),
+        docs: '/docs/guides/server-rendering',
+    },
+    'react-wrapper': {
+        title: 'React with timepicker-ui-react',
+        notes: [
+            'Install with `npm install timepicker-ui-react`. It depends on timepicker-ui, so the CSS imports below resolve.',
+            'Props: value / defaultValue, onConfirm, onUpdate, options (the grouped timepicker-ui options) and the usual input attributes such as name, required and placeholder.',
+            'Keep a controlled value in state and update it in onConfirm (on OK) or onUpdate (on every change).',
+        ],
+        code: [
+            "import { useState } from 'react';",
+            "import { Timepicker } from 'timepicker-ui-react';",
+            "import 'timepicker-ui/main.css';",
+            '',
+            'export function TimeField() {',
+            "  const [time, setTime] = useState('10:00 AM');",
+            '',
+            '  return (',
+            '    <Timepicker',
+            '      value={time}',
+            "      options={{ clock: { type: '12h' } }}",
+            '      onConfirm={({ hour, minutes, type }) => setTime(`${hour}:${minutes} ${type}`)}',
+            '    />',
+            '  );',
             '}',
         ].join('\n'),
+        docs: '/react/quick-start',
     },
     next: {
         title: 'Next.js (App Router)',
         notes: [
-            'The component must be a Client Component — add "use client" at the top.',
-            'timepicker-ui touches the DOM, so keep all usage inside useEffect (runs only in the browser). The library is SSR-safe (no DOM access at import time), but you still must not call create() on the server.',
-            'If you ever see hydration/DOM errors, dynamic-import the picker component with { ssr: false }.',
+            "Pages and layouts are Server Components by default. Put the picker in a file that starts with 'use client'.",
+            'Importing timepicker-ui on the server is safe: loading the package does not touch window or document. new TimepickerUI() on the server throws "TimepickerUI requires browser environment", so create it in useEffect, which runs only in the browser.',
+            WRAPPER_NOTE,
         ],
         code: [
             "'use client';",
+            '',
             "import { useEffect, useRef } from 'react';",
             "import { TimepickerUI } from 'timepicker-ui';",
             "import 'timepicker-ui/main.css';",
             '',
-            'export function TimePicker() {',
-            '  const ref = useRef<HTMLInputElement>(null);',
+            'export function TimeField() {',
+            '  const inputRef = useRef<HTMLInputElement>(null);',
+            '',
             '  useEffect(() => {',
-            '    if (!ref.current) return;',
-            '    const picker = new TimepickerUI(ref.current);',
+            '    if (!inputRef.current) return;',
+            '    const picker = new TimepickerUI(inputRef.current);',
             '    picker.create();',
             '    return () => picker.destroy();',
             '  }, []);',
-            '  return <input ref={ref} />;',
+            '',
+            '  return (',
+            '    <div className="tp-ui">',
+            '      <input ref={inputRef} type="text" placeholder="Select time" />',
+            '    </div>',
+            '  );',
             '}',
         ].join('\n'),
+        docs: '/docs/guides/server-rendering',
     },
     vue: {
         title: 'Vue 3',
         notes: [
-            'Create in onMounted, destroy in onBeforeUnmount.',
+            'Create in onMounted and destroy in onBeforeUnmount. Keep the instance outside reactive state.',
             'Use a template ref to the input element.',
+            WRAPPER_NOTE,
         ],
         code: [
             '<script setup lang="ts">',
@@ -79,25 +125,31 @@ export const FRAMEWORK_RECIPES = {
             '',
             'const el = ref<HTMLInputElement | null>(null);',
             'let picker: TimepickerUI | null = null;',
+            '',
             'onMounted(() => {',
             '  if (!el.value) return;',
-            '  picker = new TimepickerUI(el.value, { clock: { type: \'24h\' } });',
+            "  picker = new TimepickerUI(el.value, { clock: { type: '24h' } });",
             '  picker.create();',
             '});',
+            '',
             'onBeforeUnmount(() => picker?.destroy());',
             '</script>',
             '',
             '<template>',
-            '  <input ref="el" />',
+            '  <div class="tp-ui">',
+            '    <input ref="el" type="text" />',
+            '  </div>',
             '</template>',
         ].join('\n'),
+        docs: '/docs/quick-start',
     },
     angular: {
         title: 'Angular',
         notes: [
-            'Create in ngAfterViewInit (the view/input exists), destroy in ngOnDestroy.',
-            'Add timepicker-ui/main.css to angular.json styles or import it in styles.css.',
+            'Create in ngAfterViewInit (the input exists) and destroy in ngOnDestroy.',
+            'Add timepicker-ui/main.css to the styles array in angular.json or import it in styles.css.',
             'Use ViewChild + ElementRef to reach the input.',
+            WRAPPER_NOTE,
         ],
         code: [
             "import { AfterViewInit, Component, ElementRef, OnDestroy, ViewChild } from '@angular/core';",
@@ -105,25 +157,30 @@ export const FRAMEWORK_RECIPES = {
             '',
             '@Component({',
             "  selector: 'app-time',",
-            "  template: '<input #time />',",
+            '  template: \'<div class="tp-ui"><input #time type="text" /></div>\',',
             '})',
             'export class TimeComponent implements AfterViewInit, OnDestroy {',
             "  @ViewChild('time') input!: ElementRef<HTMLInputElement>;",
             '  private picker?: TimepickerUI;',
+            '',
             '  ngAfterViewInit() {',
-            '    this.picker = new TimepickerUI(this.input.nativeElement, { clock: { type: \'24h\' } });',
+            "    this.picker = new TimepickerUI(this.input.nativeElement, { clock: { type: '24h' } });",
             '    this.picker.create();',
             '  }',
+            '',
             '  ngOnDestroy() {',
             '    this.picker?.destroy();',
             '  }',
             '}',
         ].join('\n'),
+        docs: '/docs/quick-start',
     },
     svelte: {
         title: 'Svelte',
         notes: [
-            'Bind the input, create in onMount, destroy in the returned cleanup.',
+            'Bind the input, create in onMount and destroy in the returned cleanup.',
+            'For SvelteKit the same code runs only in the browser, because onMount does not run on the server.',
+            WRAPPER_NOTE,
         ],
         code: [
             '<script lang="ts">',
@@ -132,21 +189,26 @@ export const FRAMEWORK_RECIPES = {
             "  import 'timepicker-ui/main.css';",
             '',
             '  let input: HTMLInputElement;',
+            '',
             '  onMount(() => {',
-            '    const picker = new TimepickerUI(input, { clock: { type: \'24h\' } });',
+            "    const picker = new TimepickerUI(input, { clock: { type: '24h' } });",
             '    picker.create();',
             '    return () => picker.destroy();',
             '  });',
             '</script>',
             '',
-            '<input bind:this={input} />',
+            '<div class="tp-ui">',
+            '  <input bind:this={input} type="text" />',
+            '</div>',
         ].join('\n'),
+        docs: '/docs/guides/server-rendering',
     },
 };
 export const MIGRATION_V3_TO_V4 = {
     summary: [
-        'v4 replaced the flat options object (40+ fields) with grouped options. There is NO backward-compatibility layer — all v3 code must be updated.',
+        'v4 replaced the flat options object (40+ fields) with grouped options. There is no backward-compatibility layer, so all v3 code must be updated.',
         'Event handling also moved to the EventEmitter API (picker.on(event, handler)) and the grouped callbacks.* options.',
+        'The "to" column uses the 4.5.0 names. 4.0-4.4 used older names for some of them; the v4.4->v4.5 path lists every rename.',
     ],
     mappings: [
         {
@@ -208,8 +270,7 @@ export const MIGRATION_V3_TO_V4 = {
                 { from: 'onUpdate', to: 'callbacks.onUpdate' },
                 { from: 'onSelectHour', to: 'callbacks.onSelectHour' },
                 { from: 'onSelectMinute', to: 'callbacks.onSelectMinute' },
-                { from: 'onSelectAM', to: 'callbacks.onSelectAM' },
-                { from: 'onSelectPM', to: 'callbacks.onSelectPM' },
+                { from: 'onSelectAM / onSelectPM', to: 'callbacks.onSelectPeriod' },
                 { from: 'onError', to: 'callbacks.onError' },
             ],
         },
@@ -233,49 +294,39 @@ export const MIGRATION_V44_TO_V45 = [
     'Range edges in clock.disabledTime.ranges may carry seconds. An edge without seconds covers its whole minute, so 4.4 ranges disable the same minutes.',
     'setOptions() (and update()) with an invalid disabledTime reports it through the error event and keeps the previous options instead of throwing.',
     'behavior.returnFocus (formerly focusInputAfterClose) still defaults to false; 5.0 makes true the default, so set it to true now.',
-    'Renamed options; the old names still work and are removed in 5.0: ui.mobile -> ui.initialView, ui.enableSwitchIcon -> ui.viewSwitch, ui.enableScrollbar -> ui.allowPageScroll, ui.appendModalSelector -> ui.appendTo, ui.iconTemplate / iconTemplateMobile -> ui.keyboardIcon / clockIcon, ui.inline.containerId -> ui.inline.container, clock.currentTime -> clock.defaultTime, clock.smoothHourSnap -> clock.discreteHourJump (inverted), clock.disabledTime.interval -> ranges, behavior.focusInputAfterClose -> returnFocus, timezone.whitelist -> list, clearBehavior.clearInput -> ui.clearButton: { clearInput }. Labels: one key per unit (labels.hour, labels.minute, labels.second), labels.clockTitle / keyboardTitle, labels.clock / period / timeFields / range / switchToKeyboard / switchToClock, and range.fromLabel / toLabel / timezone.label move to labels.rangeFrom / rangeTo / timezone.',
+    'Many options were renamed. The old names still work and are removed in 5.0; when both are set, the new name wins. `renamed` below lists every pair.',
     'New: setOptions(), select:period with onSelectPeriod, switch:face with onSwitchFace, clock.type: "auto" (12h or 24h from the browser locale); ui.appendTo and ui.inline.container also accept an element.',
     'The focus ring is a single 3px ring in --tp-focus-ring; --tp-focus-ring-halo was removed.',
     'Deprecated (removed in 5.0): OptionTypes (use TimepickerOptions), labels.timezoneSelectorLabel, labels.format24Label, labels.toggleLabel, clock.currentTime.locales, getValue().degreesHours / degreesMinutes, the hide event, update() (use setOptions()), select:am / select:pm with onSelectAM / onSelectPM (use select:period / onSelectPeriod) and the renamed option names.',
 ];
-export const TROUBLESHOOTING = [
-    {
-        symptom: 'Picker opens but is completely unstyled.',
-        cause: "The core stylesheet was not imported.",
-        fix: "Always import 'timepicker-ui/main.css'. For a non-basic theme also import 'timepicker-ui/theme-<name>.css'.",
-    },
-    {
-        symptom: "An 'error' event fires / a feature option is ignored.",
-        cause: 'A plugin (range, timezone, wheel) was used without being registered.',
-        fix: "Import the plugin and call PluginRegistry.register(Plugin) once at startup before creating the picker.",
-    },
-    {
-        symptom: 'Wheel / compact-wheel mode renders as a normal clock.',
-        cause: 'The wheel plugin is required for those modes.',
-        fix: "Register WheelPlugin from 'timepicker-ui/plugins/wheel' and set ui.mode to 'wheel' or 'compact-wheel'.",
-    },
-    {
-        symptom: 'Modal appears in the wrong place or behind other UI.',
-        cause: 'It is appended to <body> by default.',
-        fix: "Set ui.appendTo to a container selector or element, or check stacking context / z-index of ancestors.",
-    },
-    {
-        symptom: 'Setting ui.theme to a custom name does nothing.',
-        cause: 'The theme CSS was not loaded, or the data-theme name does not match.',
-        fix: "Author [data-theme='name'] { --tp-*: ... }, import it after main.css, and pass ui.theme = 'name'.",
-    },
-    {
-        symptom: 'Listeners or modal linger after the input is removed (e.g. SPA route change).',
-        cause: 'The instance was not destroyed.',
-        fix: 'Call picker.destroy() in your framework cleanup hook (useEffect cleanup, onBeforeUnmount, ngOnDestroy).',
-    },
-    {
-        symptom: 'TypeScript complains about a custom theme name.',
-        cause: 'ui.theme is a union of built-in theme names.',
-        fix: "Cast the custom name: ui: { theme: 'ocean' as any }.",
-    },
-];
+export const MIGRATION_V45_TO_V5 = {
+    status: '5.0 is not released and the guide is a draft: it lists what is decided so far. Every step under stepsNow works on 4.5.0 today.',
+    stepsNow: [
+        'Upgrade to 4.5.0. Editors show deprecated APIs with a strikethrough; replace each one using `removed`.',
+        'Move to the option names in `renamed`, and replace update() with setOptions().',
+        'If you use callbacks.onSelectHour or select:hour to notice that the clock face changed, use switch:face or callbacks.onSwitchFace.',
+        'Set behavior.returnFocus: true, so the 5.0 default does not change how your page behaves.',
+        'Move code you pass as a callback to open() or destroy() to the line after the call. 5.0 removes these callback arguments.',
+        'Keep custom CSS that targets tp-ui-* classes in one place, so the 5.0 class rename touches few files.',
+    ],
+    changedDefaults: [
+        'behavior.returnFocus defaults to true in 5.0: on close, focus goes back to the input or to the data-open element that opened the picker. In 4.5.0 the default is false.',
+        "New ui.colorScheme defaults to 'auto', so the picker matches a light or dark page and basic shows its dark version on a dark page. Set ui.colorScheme: 'light' to keep the light picker everywhere.",
+    ],
+    otherChanges: [
+        'select:hour, select:minute and select:second fire once when a value of their unit is picked, in every mode. In 4.5.0 clock mode they fire when a field is activated; listen to switch:face for face changes.',
+        'ui.footer replaces ui.inline.showButtons and wheel.hideFooter.',
+        'behavior.commitOnChange replaces ui.inline.autoUpdate and wheel.commitOnScroll: each picked value is written to the input and confirm fires with autoCommit: true.',
+        'behavior.ignoreOutsideClick replaces wheel.ignoreOutsideClick and works in every mode.',
+        'ui.cssClass is applied to one element instead of two. Check CSS that uses your class.',
+        'TimepickerEventMap loses the internal events range:minute:commit and animation:*, and its catch-all index signature, so on("typo") becomes a type error.',
+        'Removed without a 4.5.0 deprecation warning: behavior.delayHandler, TimepickerUI.isAvailable() (use document.querySelector(...) !== null), the instance getters hour / minutes / okButton / cancelButton / clockHand, the callback arguments of open() and destroy(), and the RangeManager / TimezoneManager / WheelManager exports.',
+        'Plugins get a new registration API (not designed yet). Import paths timepicker-ui/plugins/range, /timezone and /wheel stay; the ./plugins/* wildcard export and the plugin UMD builds are removed.',
+        'CSS classes keep the tp-ui- prefix but are renamed after Material Design component names. About 50 custom properties that no rule reads are removed.',
+        "The dark theme is removed: use ui.colorScheme: 'dark'. crane-straight becomes a variant of crane. ui.keyboardIcon and ui.clockIcon take an element or a factory function instead of an HTML string.",
+    ],
+};
 export const IO_CONTRACT = {
-    getValue: 'getValue() returns { hour: string; minutes: string; type?: string; time: string; degreesHours: number | null; degreesMinutes: number | null }.',
-    setValue: 'setValue(time, updateInput?) accepts "HH:MM" (24h) or "h:MM AM/PM" (12h), e.g. "14:30" or "2:30 PM". updateInput defaults to writing the input value.',
+    getValue: 'getValue() returns { hour: string; minutes: string; seconds?: string; type?: string; time: string; degreesHours: number | null; degreesMinutes: number | null }. seconds is present only with clock.showSeconds; type is the period (AM/PM) on a 12h clock. degreesHours / degreesMinutes are deprecated (removed in 5.0). While the picker is open the value is the shown selection, otherwise the input value.',
+    setValue: 'setValue(time, updateInput = true) accepts "HH:MM" (24h) or "h:MM AM/PM" (12h); with clock.showSeconds also "HH:MM:SS" / "h:MM:SS AM/PM" (no seconds means :00). A valid time in the other clock format is converted ("2:30 PM" sets 14:30 on a 24h picker). An invalid string changes nothing and emits error; an empty string is ignored.',
 };

package/build/data.js

@@ -1,4 +1,28 @@
-export const PACKAGE_VERSION = '4.5';
+import { META } from './generated.js';
+export const LIBRARY_VERSION = META.library;
+export const SITE_URL = META.siteUrl;
+export function docsUrl(path) {
+    return `${SITE_URL}${path}`;
+}
+export function optionGroupDocs(group) {
+    if (group === 'clearBehavior')
+        return docsUrl('/docs/features/clear-button');
+    return docsUrl(`/docs/api/options#${group.toLowerCase()}-options`);
+}
+export const DOCS = {
+    methods: docsUrl('/docs/api/methods'),
+    events: docsUrl('/docs/api/events#available-events'),
+    cssVariables: docsUrl('/docs/api/css-variables'),
+    cssClasses: docsUrl('/docs/api/css-classes'),
+    styling: docsUrl('/docs/advanced/styling'),
+    themes: docsUrl('/docs/features/themes'),
+    plugins: docsUrl('/docs/features/plugins'),
+    migrationV4: docsUrl('/docs/migration-guide'),
+    migrationV5: docsUrl('/docs/migration-guide-v5'),
+    renamed: docsUrl('/docs/api/options#renamed'),
+    troubleshooting: docsUrl('/docs/guides/troubleshooting'),
+    llms: docsUrl('/llms.txt'),
+};
 export const THEMES = [
     { name: 'basic', cssImport: 'timepicker-ui/main.css', note: 'default theme, bundled in main.css' },
     { name: 'ai', cssImport: 'timepicker-ui/theme-ai.css' },
@@ -18,12 +42,12 @@ export const MODES = [
     { name: 'clock', description: 'Analog clock face with draggable hands (default).' },
     {
         name: 'wheel',
-        description: 'Scrollable wheel picker for hours/minutes.',
+        description: 'Scroll wheel spinner.',
         requiresPlugin: 'wheel',
     },
     {
         name: 'compact-wheel',
-        description: 'Condensed inline wheel variant.',
+        description: 'Wheel without the header. Opens as a modal, or as a popover next to the input with wheel.placement.',
         requiresPlugin: 'wheel',
     },
 ];
@@ -54,28 +78,54 @@ export const PLUGINS = [
 export const PLUGIN_NAMES = PLUGINS.map((p) => p.name);
 export const API_METHODS = [
     { signature: 'new TimepickerUI(selectorOrElement, options?)', description: 'Construct an instance.' },
-    { signature: 'create()', description: 'Initialize and render the picker.' },
-    { signature: 'open(callback?)', description: 'Open the modal.' },
-    { signature: 'close(update?, callback?)', description: 'Close the modal.' },
+    { signature: 'create()', description: 'Initialize and render the picker. An inline picker mounts right away.' },
+    {
+        signature: 'open(callback?)',
+        description: 'Open the picker.',
+        deprecated: 'The callback argument is removed in 5.0. Run that code after the call or use picker.once("open", ...).',
+    },
+    {
+        signature: 'close(update?, callback?)',
+        description: 'Close the picker. update: true commits the selection like OK (updates the input and emits confirm); otherwise the selection is discarded.',
+    },
     {
         signature: 'destroy(options?)',
-        description: 'Clean up DOM and listeners. options: { keepInputValue?, callback? }.',
+        description: 'Remove listeners and DOM. options: { keepInputValue?, callback? } or a callback.',
+        deprecated: 'The callback forms destroy(cb) and destroy({ callback }) are removed in 5.0.',
     },
     {
         signature: 'getValue()',
-        description: 'Returns { hour, minutes, type?, time, degreesHours, degreesMinutes }.',
+        description: 'Returns { hour, minutes, seconds?, type?, time, degreesHours, degreesMinutes }. seconds is present only with clock.showSeconds. While open it is the shown selection, otherwise the input value.',
+    },
+    {
+        signature: 'setValue(time, updateInput = true)',
+        description: 'Set the time, e.g. "14:30", "2:30 PM" or "14:30:15". Invalid strings emit error and change nothing.',
     },
-    { signature: 'setValue(time, updateInput?)', description: 'Set time, e.g. "14:30" or "2:30 PM".' },
     { signature: 'setOptions(options)', description: 'Change options at runtime; groups you leave out keep their values.' },
     {
         signature: 'update({ options, create? }, callback?)',
-        description: 'Deprecated, use setOptions(). Removed in 5.0.',
+        description: 'Change options at runtime.',
+        deprecated: 'Use setOptions(options). Removed in 5.0.',
+    },
+    { signature: 'getElement()', description: 'The root .tp-ui element of the instance.' },
+    { signature: 'instanceId', description: 'Getter: the unique instance id.' },
+    { signature: 'options', description: 'Getter: the merged options. Returns the old option names until 5.0.' },
+    { signature: 'isInitialized / isDestroyed', description: 'Getters for the lifecycle state.' },
+    {
+        signature: 'hour / minutes / okButton / cancelButton / clockHand',
+        description: 'Undocumented getters that return internal DOM elements.',
+        deprecated: 'Removed in 5.0. Read the time with getValue().',
     },
     { signature: 'on(event, handler)', description: 'Subscribe to an event.' },
     { signature: 'once(event, handler)', description: 'Subscribe once.' },
     { signature: 'off(event, handler?)', description: 'Unsubscribe.' },
-    { signature: 'TimepickerUI.getById(id)', description: 'Get an instance by custom behavior.id.', static: true },
+    { signature: 'TimepickerUI.getById(id)', description: 'Get an instance by its behavior.id.', static: true },
     { signature: 'TimepickerUI.getAllInstances()', description: 'All live instances.', static: true },
-    { signature: 'TimepickerUI.isAvailable(selector)', description: 'Check the element exists.', static: true },
+    {
+        signature: 'TimepickerUI.isAvailable(selectorOrElement)',
+        description: 'Check the element exists.',
+        static: true,
+        deprecated: 'Removed in 5.0. Use document.querySelector(...) !== null.',
+    },
     { signature: 'TimepickerUI.destroyAll()', description: 'Destroy every instance.', static: true },
 ];