vue-pane 0.0.0 → 0.7.0

package/README.md

@@ -2,14 +2,15 @@
 
 Compact debug panel components for Vue 3. A spiritual replacement for [Tweakpane](https://tweakpane.github.io/docs/) — same visual style, Vue-native API.
 
+**[Documentation](https://unstoppablecarl.github.io/vue-pane/)**
+
 ## Features
 
 - Inputs: text, number (drag-to-change), slider, checkbox, select, color picker, 2D point
-- Display: single-line monitor, multi-line monitor, graph/sparkline
+- Display: single-line monitor, multiline monitor, graph/sparkline
 - Layout: collapsible pane, collapsible folders, tabs, separator
-- Folder state persisted to `localStorage` via a `name` prop
-- BEM CSS class names (`vp-pane`, `vp-folder__title`, etc.) — fully themeable via CSS custom properties
-- TypeScript throughout
+- Pane and folder state persisted to `localStorage` via the `id` prop
+- Polling: `pollingRef` reads plain (non-reactive) JS objects on an interval — pauses automatically when the pane is collapsed
 
 ## Installation
 
@@ -25,10 +26,10 @@ import 'vue-pane/dist/vue-pane.css'
 
 ### Nuxt / source-first bundlers
 
-The package exposes a `"source"` export condition pointing at the raw `.vue` and `.scss` files. Bundlers that understand this condition (Nuxt, Vite with explicit `resolve.conditions: ['source']`) will process the source directly — no CSS import needed, and templates are compiled once by your own build.
+The package exposes a `"source"` export condition pointing at the raw `.vue` and `.scss` files. Bundlers that understand this condition (Nuxt, Vite with explicit `resolve.conditions: ['source']`) will process the source directly — no CSS import needed.
 
 ```ts
-// vite.config.ts — opt in explicitly if needed
+// vite.config.ts
 export default defineConfig({
   resolve: { conditions: ['source'] },
 })
@@ -37,9 +38,9 @@ export default defineConfig({
 ## Quick start
 
 ```vue
-<script setup lang="ts">
+<script setup>
 import { ref } from 'vue'
-import { VPane, VPFolder, VPNumber, VPCheckbox, VPButton } from 'vue-pane'
+import { VPane, PNumber, PCheckbox, PMonitor, pollingRef } from 'vue-pane'
 
 const speed = ref(1)
 const enabled = ref(true)
@@ -47,376 +48,14 @@ const enabled = ref(true)
 
 <template>
   <VPane title="Controls" style="width: 280px">
-    <VPNumber v-model="speed" label="Speed" :min="0" :max="10" :step="0.1" />
-    <VPCheckbox v-model="enabled" label="Enabled" />
-    <VPButton label="Reset" @click="speed = 1; enabled = true" />
-
-    <VPFolder title="Advanced" name="advanced">
-      <VPNumber v-model="speed" label="Fine" :step="0.01" />
-    </VPFolder>
+    <PNumber v-model="speed" label="Speed" :min="0" :max="10" :step="0.1" />
+    <PCheckbox v-model="enabled" label="Enabled" />
+    <PMonitor :value="speed" label="Speed" />
   </VPane>
 </template>
 ```
 
----
-
-## Component reference
-
-### `VPane`
-
-Root container. Applies theming (font, colors, shadow, border-radius) to all children.
-
-```vue
-<VPane title="My Panel" :expanded="true" style="width: 300px">
-  <!-- components -->
-</VPane>
-```
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `title` | `string` | — | Title text. If omitted the header button is hidden and the pane is always open. |
-| `expanded` | `boolean` | `true` | Initial open/closed state. Only applies when `title` is set. |
-| `disabled` | `boolean` | — | Applies `vp--disabled` — disables pointer events. |
-| `hidden` | `boolean` | — | Applies `vp--hidden` — `display: none`. |
-
----
-
-### `VPFolder`
-
-Collapsible folder. Expanded state is saved to `localStorage` when `name` is provided.
-
-```vue
-<VPFolder title="Transform" name="transform">
-  <!-- components -->
-</VPFolder>
-```
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `title` | `string` | **required** | Folder title. |
-| `name` | `string` | — | localStorage key (`vp-folder-{name}`). Without it, state is not persisted. |
-| `expanded` | `boolean` | `true` | Initial open/closed state (overridden by localStorage when `name` is set). |
-| `disabled` | `boolean` | — | Disables pointer events on the folder. |
-| `hidden` | `boolean` | — | Hides the folder. |
-
----
-
-### `VPText`
-
-Plain text input.
-
-```vue
-<VPText v-model="name" label="Name" />
-```
-
-| Prop | Type | Description |
-|---|---|---|
-| `modelValue` | `string` | **required** |
-| `label` | `string` | Label text. Omit for full-width input. |
-
----
-
-### `VPNumber`
-
-Number input with a drag-to-change knob on the left edge. Keyboard: `↑`/`↓` steps by `step`; `Shift+↑`/`↓` steps by `step × 10`.
-
-```vue
-<VPNumber v-model="count" label="Count" :min="0" :max="100" :step="1" />
-```
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `modelValue` | `number` | **required** | |
-| `label` | `string` | — | |
-| `min` | `number` | — | Clamp minimum. |
-| `max` | `number` | — | Clamp maximum. |
-| `step` | `number` | `1` | Drag and arrow key increment. |
-
----
-
-### `VPSlider`
-
-Horizontal track-and-knob slider.
-
-```vue
-<VPSlider v-model="opacity" label="Opacity" :min="0" :max="1" :step="0.01" />
-```
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `modelValue` | `number` | **required** | |
-| `label` | `string` | — | |
-| `min` | `number` | `0` | |
-| `max` | `number` | `1` | |
-| `step` | `number` | `0.01` | |
-
----
-
-### `VPCheckbox`
-
-Boolean toggle.
-
-```vue
-<VPCheckbox v-model="visible" label="Visible" />
-```
-
-| Prop | Type | Description |
-|---|---|---|
-| `modelValue` | `boolean` | **required** |
-| `label` | `string` | |
-
----
-
-### `VPSelect`
-
-Dropdown list.
-
-```vue
-<VPSelect v-model="mode" :options="options" label="Mode" />
-```
-
-```ts
-const options = [
-  { value: 'linear', label: 'Linear' },
-  { value: 'ease',   label: 'Ease'   },
-]
-```
-
-| Prop | Type | Description |
-|---|---|---|
-| `modelValue` | `string \| number` | **required** |
-| `options` | `{ value: string \| number; label: string }[]` | **required** |
-| `label` | `string` | |
-
----
-
-### `VPColor`
-
-Color picker. Clicking the swatch opens an inline HSV palette with a hue slider and RGB inputs.
-
-```vue
-<VPColor v-model="fill" label="Fill" />
-```
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `modelValue` | `string` | **required** | Hex color string, e.g. `#ff5500`. |
-| `label` | `string` | — | |
-| `alpha` | `boolean` | `false` | Show alpha channel controls. |
-
----
-
-### `VPPoint2d`
-
-Two-axis coordinate input. Click the crosshair button to open an interactive 2D canvas picker.
-
-```vue
-<VPPoint2d v-model="position" label="Position" :min="-1" :max="1" />
-```
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `modelValue` | `{ x: number; y: number }` | **required** | |
-| `label` | `string` | — | |
-| `min` | `number` | `-1` | Range minimum for both axes. |
-| `max` | `number` | `1` | Range maximum for both axes. |
-
----
-
-### `VPButton`
-
-Clickable action button.
-
-```vue
-<VPButton label="Apply" @click="apply" />
-```
-
-| Prop | Type | Description |
-|---|---|---|
-| `label` | `string` | **required** |
-
-| Event | Description |
-|---|---|
-| `click` | Emitted on button press. |
-
----
-
-### `VPSeparator`
-
-Horizontal rule for visual grouping.
-
-```vue
-<VPSeparator />
-```
-
----
-
-### `VPTab`
-
-Tab container with named slots per tab. Slot names match the strings in the `tabs` array.
-
-```vue
-<VPTab :tabs="['Settings', 'Info']" v-model="activeTab">
-  <template #Settings>
-    <VPNumber v-model="speed" label="Speed" />
-  </template>
-  <template #Info>
-    <VPMonitor :value="speed" label="Speed" />
-  </template>
-</VPTab>
-```
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `tabs` | `string[]` | **required** | Tab labels (also the slot names). |
-| `modelValue` | `number` | `0` | Active tab index. |
-
----
-
-### `VPMonitor`
-
-Read-only single-line display.
-
-```vue
-<VPMonitor :value="fps" label="FPS" />
-```
-
-| Prop | Type | Description |
-|---|---|---|
-| `value` | `unknown` | **required** — rendered with `{{ value }}`. |
-| `label` | `string` | |
-
----
-
-### `VPMonitorMulti`
-
-Read-only multi-line display (3 rows).
-
-```vue
-<VPMonitorMulti :value="`x: ${pos.x}\ny: ${pos.y}`" label="Position" />
-```
-
-| Prop | Type | Description |
-|---|---|---|
-| `value` | `unknown` | Rendered verbatim. Use `\n` for line breaks. |
-| `label` | `string` | |
-
----
-
-### `VPGraph`
-
-Sparkline chart. Pass a rolling array of numbers; the component normalises the range automatically.
-
-```vue
-<VPGraph :values="history" label="FPS" />
-```
-
-| Prop | Type | Description |
-|---|---|---|
-| `values` | `number[]` | **required** |
-| `label` | `string` | |
-| `min` | `number` | Auto from data. |
-| `max` | `number` | Auto from data. |
-
----
-
-### `VPLabel`
-
-Layout primitive that pairs a label with any arbitrary content. Used internally by all inputs — available for custom components.
-
-```vue
-<VPLabel label="Custom">
-  <MyWidget />
-</VPLabel>
-```
-
-| Prop | Type | Description |
-|---|---|---|
-| `label` | `string` | Omit for full-width (no-label) layout. |
-
----
-
-## Theming
-
-Override the default dark theme by setting CSS custom properties on any ancestor element (or `:root`).
-
-```css
-.my-app {
-  --vp-base-background-color:    #1e1e2e;
-  --vp-container-foreground-color: #cdd6f4;
-  --vp-input-background-color:   rgba(205, 214, 244, 0.06);
-  --vp-blade-value-width:        180px;
-  --vp-container-unit-size:      22px;
-}
-```
-
-### Full variable reference
-
-| Variable | Default | Description |
-|---|---|---|
-| `--vp-base-background-color` | `#28292e` | Pane background |
-| `--vp-base-border-radius` | `6px` | Pane corner radius |
-| `--vp-base-font-family` | `Roboto Mono, monospace` | Font stack |
-| `--vp-base-shadow-color` | `rgba(0,0,0,0.2)` | Drop shadow |
-| `--vp-blade-border-radius` | `2px` | Input element corner radius |
-| `--vp-blade-horizontal-padding` | `4px` | Input horizontal padding |
-| `--vp-blade-value-width` | `160px` | Width of the value column |
-| `--vp-button-background-color` | `#adafb8` | Button fill |
-| `--vp-button-foreground-color` | `#28292e` | Button text |
-| `--vp-container-background-color` | `rgba(...)` | Folder/tab header fill |
-| `--vp-container-foreground-color` | `#bbbcc4` | Folder/tab header text |
-| `--vp-container-unit-size` | `20px` | Row height |
-| `--vp-container-unit-spacing` | `4px` | Gap between rows |
-| `--vp-container-vertical-padding` | `4px` | Folder content top/bottom padding |
-| `--vp-input-background-color` | `rgba(...)` | Input fill |
-| `--vp-input-foreground-color` | `#bbbcc4` | Input text |
-| `--vp-label-foreground-color` | `rgba(...)` | Label text (slightly dimmed) |
-| `--vp-monitor-background-color` | `rgba(...)` | Monitor/display fill |
-| `--vp-monitor-foreground-color` | `rgba(...)` | Monitor text |
-| `--vp-groove-foreground-color` | `rgba(...)` | Separator line colour |
-
----
-
-## TypeScript
-
-All components are typed. Named exports only — import what you need:
-
-```ts
-import type { } from 'vue-pane' // no public types beyond the components themselves
-import { VPane, VPNumber, VPColor } from 'vue-pane'
-```
-
----
-
-## CSS class names
-
-Classes follow BEM with a `vp-` prefix. Useful for targeted overrides:
-
-```css
-/* make all labels uppercase */
-.vp-label__text { text-transform: uppercase; }
-
-/* widen value column in one pane only */
-#my-pane { --vp-blade-value-width: 200px; }
-```
-
-Global state classes applied automatically:
-
-| Class | Description |
-|---|---|
-| `vp--disabled` | Pointer events off, element dimmed |
-| `vp--hidden` | `display: none` |
-| `vp--first` | First visible child in a container |
-| `vp--last` | Last visible child |
-
----
-
-## Monorepo
-
-```
-packages/vue-pane/   ← npm package
-apps/example/        ← development example app
-```
+## Development
 
 ```sh
 pnpm dev        # start the example app (resolves vue-pane from source, no build needed)

package/dist/src/components/PCheckbox.vue.d.ts

@@ -1,15 +1,18 @@
+import { PollingRef } from '../composables/pollingRef';
 type __VLS_Props = {
+    poll?: PollingRef<boolean>;
     label?: string;
     tooltip?: string;
+    readonly?: boolean;
 };
 type __VLS_ModelProps = {
-    modelValue: boolean;
+    modelValue?: boolean;
 };
 type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
 declare const __VLS_export: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-    "update:modelValue": (value: boolean) => any;
+    "update:modelValue": (value: boolean | undefined) => any;
 }, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
-    "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: boolean | undefined) => any) | undefined;
 }>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/src/components/PColor.vue.d.ts

@@ -1,16 +1,19 @@
+import { PollingRef } from '../composables/pollingRef';
 type __VLS_Props = {
+    poll?: PollingRef<string>;
     label?: string;
     tooltip?: string;
     alpha?: boolean;
+    readonly?: boolean;
 };
 type __VLS_ModelProps = {
-    modelValue: string;
+    modelValue?: string;
 };
 type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
 declare const __VLS_export: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-    "update:modelValue": (value: string) => any;
+    "update:modelValue": (value: string | undefined) => any;
 }, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
-    "onUpdate:modelValue"?: ((value: string) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: string | undefined) => any) | undefined;
 }>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/src/components/PGraph.vue.d.ts

@@ -1,5 +1,8 @@
+import { PollingRef } from '../composables/pollingRef';
 type __VLS_Props = {
-    values: number[];
+    poll?: PollingRef<number>;
+    historyLength?: number;
+    values?: number[];
     label?: string;
     tooltip?: string;
     min?: number;

package/dist/src/components/PMonitor.vue.d.ts

@@ -1,5 +1,7 @@
+import { PollingRef } from '../composables/pollingRef';
 type __VLS_Props = {
-    value: unknown;
+    poll?: PollingRef<unknown>;
+    value?: unknown;
     label?: string;
     tooltip?: string;
 };

package/dist/src/components/{PMonitorMulti.vue.d.ts → PMonitorMultiline.vue.d.ts}

@@ -1,5 +1,7 @@
+import { PollingRef } from '../composables/pollingRef';
 type __VLS_Props = {
-    value: unknown;
+    poll?: PollingRef<unknown>;
+    value?: unknown;
     label?: string;
     tooltip?: string;
 };

package/dist/src/components/PNumber.vue.d.ts

@@ -1,18 +1,21 @@
+import { PollingRef } from '../composables/pollingRef';
 type __VLS_Props = {
+    poll?: PollingRef<number>;
     label?: string;
     tooltip?: string;
     min?: number;
     max?: number;
     step?: number;
+    readonly?: boolean;
 };
 type __VLS_ModelProps = {
-    modelValue: number;
+    modelValue?: number;
 };
 type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
 declare const __VLS_export: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-    "update:modelValue": (value: number) => any;
+    "update:modelValue": (value: number | undefined) => any;
 }, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
-    "onUpdate:modelValue"?: ((value: number) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: number | undefined) => any) | undefined;
 }>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/src/components/PPoint2d.vue.d.ts

@@ -1,11 +1,17 @@
+import { PollingRef } from '../composables/pollingRef';
 type __VLS_Props = {
+    poll?: PollingRef<{
+        x: number;
+        y: number;
+    }>;
     label?: string;
     tooltip?: string;
     min?: number;
     max?: number;
+    readonly?: boolean;
 };
 type __VLS_ModelProps = {
-    modelValue: {
+    modelValue?: {
         x: number;
         y: number;
     };
@@ -15,12 +21,12 @@ declare const __VLS_export: import('vue').DefineComponent<__VLS_PublicProps, {},
     "update:modelValue": (value: {
         x: number;
         y: number;
-    }) => any;
+    } | undefined) => any;
 }, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
     "onUpdate:modelValue"?: ((value: {
         x: number;
         y: number;
-    }) => any) | undefined;
+    } | undefined) => any) | undefined;
 }>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/src/components/PSelect.vue.d.ts

@@ -1,19 +1,22 @@
+import { PollingRef } from '../composables/pollingRef';
 type __VLS_Props = {
+    poll?: PollingRef<string | number>;
     label?: string;
     tooltip?: string;
     options: {
         value: string | number;
         label: string;
     }[];
+    readonly?: boolean;
 };
 type __VLS_ModelProps = {
-    modelValue: string | number;
+    modelValue?: string | number;
 };
 type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
 declare const __VLS_export: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-    "update:modelValue": (value: string | number) => any;
+    "update:modelValue": (value: string | number | undefined) => any;
 }, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
-    "onUpdate:modelValue"?: ((value: string | number) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: string | number | undefined) => any) | undefined;
 }>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/src/components/PSlider.vue.d.ts

@@ -1,18 +1,21 @@
+import { PollingRef } from '../composables/pollingRef';
 type __VLS_Props = {
+    poll?: PollingRef<number>;
     label?: string;
     tooltip?: string;
     min?: number;
     max?: number;
     step?: number | null;
+    readonly?: boolean;
 };
 type __VLS_ModelProps = {
-    modelValue: number;
+    modelValue?: number;
 };
 type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
 declare const __VLS_export: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-    "update:modelValue": (value: number) => any;
+    "update:modelValue": (value: number | undefined) => any;
 }, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
-    "onUpdate:modelValue"?: ((value: number) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: number | undefined) => any) | undefined;
 }>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/src/components/PText.vue.d.ts

@@ -1,15 +1,18 @@
+import { PollingRef } from '../composables/pollingRef';
 type __VLS_Props = {
+    poll?: PollingRef<string>;
     label?: string;
     tooltip?: string;
+    readonly?: boolean;
 };
 type __VLS_ModelProps = {
-    modelValue: string;
+    modelValue?: string;
 };
 type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
 declare const __VLS_export: import('vue').DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
-    "update:modelValue": (value: string) => any;
+    "update:modelValue": (value: string | undefined) => any;
 }, string, import('vue').PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
-    "onUpdate:modelValue"?: ((value: string) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: string | undefined) => any) | undefined;
 }>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/src/composables/pollingRef.d.ts

@@ -0,0 +1,9 @@
+import { Ref } from 'vue';
+export declare const POLLING_REF: unique symbol;
+export interface PollingRef<T> extends Ref<T> {
+    readonly [POLLING_REF]: true;
+    subscribe(): void;
+    unsubscribe(): void;
+}
+export declare function pollingRef<O extends object, K extends keyof O>(obj: O, key: K, interval?: number): PollingRef<O[K]>;
+export declare function isPollingRef<T>(r: Ref<T> | unknown): r is PollingRef<T>;

package/dist/src/composables/useFoldable.d.ts

@@ -1,5 +1,8 @@
-import { Ref } from 'vue';
+import { InjectionKey, Ref } from 'vue';
 export declare function useFoldable(containerRef: Ref<HTMLElement | null>, expandedRef: Ref<boolean>, storageKey?: string, expandedClass?: string): {
     isExpanded: Ref<boolean>;
     toggle: () => void;
 };
+export declare const EXPANDED_KEY: InjectionKey<Ref<boolean>>;
+export declare function getPaneExpanded(): Ref<boolean>;
+export declare function cascadeExpanded(isExpanded: Ref<boolean>): void;

package/dist/src/composables/usePolling.d.ts

@@ -0,0 +1,4 @@
+import { Ref } from 'vue';
+import { PollingRef } from './pollingRef';
+export declare function usePolling(r: PollingRef<any>, visible?: Ref<boolean, boolean>): void;
+export declare function usePollingOrModel<T, S = T>(poll: PollingRef<T> | undefined, modelValue: Ref<T, S>, visible?: Ref<boolean, boolean>): Ref<NonNullable<T>, NonNullable<S>>;