dialkit 1.1.0 → 1.2.1

package/README.md

@@ -1,6 +1,16 @@
-# dialkit
+# dialkit v1.2.0
 
-Real-time parameter tweaking for React, Solid, and Svelte.
+<img src="https://joshpuckett.me/images/dialkit.png" width="100%" />
+
+Real-time parameter tweaking for React, Solid, Svelte, and Vue, created by Josh Puckett.
+
+To learn more about how I use DialKit, and approach design in general, feel free to check out [Interface Craft](http://interfacecraft.dev/).
+
+## Contributing
+
+- **Open an issue first.** All pull requests should reference an existing issue. PRs without a corresponding issue will be closed.
+- **Keep PRs small and focused.** Each pull request should address a single change — one bug fix, one feature, or one refactor. Avoid bundling unrelated changes together.
+- **No unnecessary dependencies.** If your change can be accomplished without adding a new dependency, it should be. Any new dependency needs justification in the PR description.
 
 ## Quick Start
 
@@ -63,6 +73,7 @@ const params = useDialKit(name, config, options?)
 | `name` | `string` | Panel title displayed in the UI |
 | `config` | `DialConfig` | Parameter definitions (see Control Types below) |
 | `options.onAction` | `(path: string) => void` | Callback when action buttons are clicked |
+| `options.shortcuts` | `Record<string, ShortcutConfig>` | Keyboard shortcuts for controls (see [Keyboard Shortcuts](#keyboard-shortcuts)) |
 
 Returns a fully typed object matching your config shape with live values. Updating a control in the UI immediately updates the returned values.
 
@@ -257,9 +268,20 @@ const values = useDialKit('Controls', {
 | `position` | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'top-right'` |
 | `defaultOpen` | `boolean` | `true` |
 | `mode` | `'popover' \| 'inline'` | `'popover'` |
+| `productionEnabled` | `boolean` | `false` in production, `true` otherwise |
 
 Mount once at your app root. In the default `popover` mode, the panel renders via a portal on `document.body`. It collapses to a small icon button and expands to 280px wide on click.
 
+DialKit is automatically hidden in production builds. To enable it in production, pass `productionEnabled`:
+
+```tsx
+<DialRoot productionEnabled />
+```
+
+### Draggable panel
+
+In popover mode, the collapsed panel bubble can be dragged to any position on the screen. When you click to open the panel, it snaps to the nearest side — top-left if the bubble is on the left half of the screen, top-right if on the right half. When the panel is closed again, it returns to where you last dragged it.
+
 ### Inline mode
 
 Use `mode="inline"` to render DialKit directly in your layout instead of as a floating popover. The panel fills its container and scrolls internally, which is useful for embedding in a sidebar or resizable panel. Inline mode works across all frameworks:
@@ -298,6 +320,88 @@ When the panel is open, the toolbar provides:
 
 ---
 
+## Keyboard Shortcuts
+
+Assign keyboard shortcuts to controls so you can adjust values without touching the panel. Pass a `shortcuts` map in the options object:
+
+```tsx
+const p = useDialKit('Card', {
+  blur: [24, 0, 100],
+  scale: 1.2,
+  opacity: [1, 0, 1],
+  borderRadius: [16, 0, 64],
+  darkMode: true,
+  shadow: {
+    blur: [10, 0, 50],
+  },
+}, {
+  shortcuts: {
+    blur:          { key: 'b', mode: 'fine' },                          // B+Scroll
+    scale:         { key: 's', interaction: 'drag', mode: 'coarse' },   // S+Drag
+    opacity:       { key: 'o', interaction: 'move' },                   // O+Move
+    borderRadius:  { interaction: 'scroll-only' },                      // Scroll (no key)
+    darkMode:      { key: 'm' },                                        // press M
+    'shadow.blur': { key: 'd', mode: 'fine' },                          // D+Scroll
+  },
+});
+```
+
+### ShortcutConfig
+
+```tsx
+type ShortcutConfig = {
+  key?: string;                                       // trigger key (e.g. 'b', 's') — optional for scroll-only
+  modifier?: 'alt' | 'shift' | 'meta';               // optional modifier key
+  mode?: 'fine' | 'normal' | 'coarse';               // precision level (default: 'normal')
+  interaction?: 'scroll' | 'drag' | 'move' | 'scroll-only'; // input method (default: 'scroll')
+};
+```
+
+### Interaction types
+
+| Interaction | Description | Example pill |
+|-------------|-------------|-------------|
+| `scroll` | Hold key + scroll wheel to adjust (default) | `B+Scroll` |
+| `drag` | Hold key + click and drag horizontally | `S+Drag` |
+| `move` | Hold key + move mouse (no click needed) | `O+Move` |
+| `scroll-only` | Just scroll anywhere, no key needed | `Scroll` |
+
+### Supported controls
+
+| Control | Interactions | Description |
+|---------|-------------|-------------|
+| **Slider** | `scroll`, `drag`, `move`, `scroll-only` | Adjust value with chosen input method |
+| **Toggle** | key press | Press the assigned key to flip on/off |
+
+### Precision modes
+
+For sliders, the `mode` controls how much each scroll tick or drag pixel changes the value:
+
+| Mode | Step multiplier | Use case |
+|------|----------------|----------|
+| `fine` | step &divide; 10 | Precision tweaking |
+| `normal` | step &times; 1 | Default behavior |
+| `coarse` | step &times; 10 | Big sweeps |
+
+### Nested paths
+
+For controls inside folders, use dot notation:
+
+```tsx
+shortcuts: {
+  'shadow.blur': { key: 'd' },
+  'shadow.opacity': { key: 'a', interaction: 'drag', mode: 'fine' },
+}
+```
+
+### UI indicators
+
+Each control with a shortcut displays a pill badge next to its label showing the key and interaction (e.g. `B+Scroll`, `S+Drag`, `O+Move`, `Scroll`). The pill highlights when the shortcut key is actively held.
+
+Shortcuts are automatically disabled when a text input is focused.
+
+---
+
 ## Full Example
 
 ```tsx
@@ -335,6 +439,11 @@ function PhotoStack() {
     next: { type: 'action' },
     previous: { type: 'action' },
   }, {
+    shortcuts: {
+      'backPhoto.offsetX': { key: 'x', interaction: 'drag', mode: 'coarse' },
+      'backPhoto.scale': { key: 's', interaction: 'move', mode: 'fine' },
+      darkMode: { key: 'm' },
+    },
     onAction: (action) => {
       if (action === 'next') goNext();
       if (action === 'previous') goPrevious();
@@ -449,6 +558,67 @@ npm install dialkit
 
 ---
 
+## Vue
+
+DialKit works with Vue 3 (≥3.3.0). Import from `dialkit/vue`.
+
+```bash
+npm install dialkit motion-v vue
+```
+
+```ts
+// main.ts
+import { createApp } from 'vue';
+import { DialRoot } from 'dialkit/vue';
+import 'dialkit/styles.css';
+import App from './App.vue';
+
+const app = createApp(App);
+app.mount('#app');
+```
+
+```vue
+<!-- App.vue -->
+<script setup>
+import { DialRoot } from 'dialkit/vue';
+import Card from './Card.vue';
+</script>
+
+<template>
+  <Card />
+  <DialRoot />
+</template>
+```
+
+```vue
+<!-- Card.vue -->
+<script setup>
+import { useDialKit } from 'dialkit/vue';
+
+const params = useDialKit('Card', {
+  blur: [24, 0, 100],
+  scale: 1.2,
+  color: '#ff5500',
+  visible: true,
+});
+</script>
+
+<template>
+  <div :style="{
+    filter: `blur(${params.blur}px)`,
+    transform: `scale(${params.scale})`,
+    color: params.color,
+    opacity: params.visible ? 1 : 0,
+  }">
+    ...
+  </div>
+</template>
+```
+
+`useDialKit` returns a reactive object. All control types, presets, folders, keyboard shortcuts, and transitions work identically to the other frameworks.
+
+---
+
 ## Types
 
 All config and value types are exported:
@@ -460,6 +630,8 @@ import type {
   SelectConfig,
   ColorConfig,
   TextConfig,
+  ShortcutConfig,
+  ShortcutMode,
   DialConfig,
   DialValue,
   ResolvedValues,

package/dist/icons.d.ts

@@ -0,0 +1,19 @@
+declare const ICON_CHEVRON = "M6 9.5L12 15.5L18 9.5";
+declare const ICON_CHECK = "M5 12.75L10 19L19 5";
+declare const ICON_CLIPBOARD: {
+    board: string;
+    sparkle: string;
+    body: string;
+};
+declare const ICON_ADD_PRESET: string[];
+declare const ICON_TRASH: string[];
+declare const ICON_PANEL: {
+    path: string;
+    circles: {
+        cx: string;
+        cy: string;
+        r: string;
+    }[];
+};
+
+export { ICON_ADD_PRESET, ICON_CHECK, ICON_CHEVRON, ICON_CLIPBOARD, ICON_PANEL, ICON_TRASH };

package/dist/icons.js

@@ -0,0 +1,39 @@
+// src/icons.ts
+var ICON_CHEVRON = "M6 9.5L12 15.5L18 9.5";
+var ICON_CHECK = "M5 12.75L10 19L19 5";
+var ICON_CLIPBOARD = {
+  board: "M8 6C8 4.34315 9.34315 3 11 3H13C14.6569 3 16 4.34315 16 6V7H8V6Z",
+  sparkle: "M19.2405 16.1852L18.5436 14.3733C18.4571 14.1484 18.241 14 18 14C17.759 14 17.5429 14.1484 17.4564 14.3733L16.7595 16.1852C16.658 16.4493 16.4493 16.658 16.1852 16.7595L14.3733 17.4564C14.1484 17.5429 14 17.759 14 18C14 18.241 14.1484 18.4571 14.3733 18.5436L16.1852 19.2405C16.4493 19.342 16.658 19.5507 16.7595 19.8148L17.4564 21.6267C17.5429 21.8516 17.759 22 18 22C18.241 22 18.4571 21.8516 18.5436 21.6267L19.2405 19.8148C19.342 19.5507 19.5507 19.342 19.8148 19.2405L21.6267 18.5436C21.8516 18.4571 22 18.241 22 18C22 17.759 21.8516 17.5429 21.6267 17.4564L19.8148 16.7595C19.5507 16.658 19.342 16.4493 19.2405 16.1852Z",
+  body: "M16 5H17C18.6569 5 20 6.34315 20 8V11M8 5H7C5.34315 5 4 6.34315 4 8V18C4 19.6569 5.34315 21 7 21H12"
+};
+var ICON_ADD_PRESET = [
+  "M4 6H20",
+  "M4 12H10",
+  "M15 15L21 15",
+  "M18 12V18",
+  "M4 18H10"
+];
+var ICON_TRASH = [
+  "M5 6.5L5.80734 18.2064C5.91582 19.7794 7.22348 21 8.80023 21H15.1998C16.7765 21 18.0842 19.7794 18.1927 18.2064L19 6.5",
+  "M10 11V16",
+  "M14 11V16",
+  "M3.5 6H20.5",
+  "M8.07092 5.74621C8.42348 3.89745 10.0485 2.5 12 2.5C13.9515 2.5 15.5765 3.89745 15.9291 5.74621"
+];
+var ICON_PANEL = {
+  path: "M6.84766 11.75C6.78583 11.9899 6.75 12.2408 6.75 12.5C6.75 12.7592 6.78583 13.0101 6.84766 13.25H2C1.58579 13.25 1.25 12.9142 1.25 12.5C1.25 12.0858 1.58579 11.75 2 11.75H6.84766ZM14 11.75C14.4142 11.75 14.75 12.0858 14.75 12.5C14.75 12.9142 14.4142 13.25 14 13.25H12.6523C12.7142 13.0101 12.75 12.7592 12.75 12.5C12.75 12.2408 12.7142 11.9899 12.6523 11.75H14ZM3.09766 7.25C3.03583 7.48994 3 7.74075 3 8C3 8.25925 3.03583 8.51006 3.09766 8.75H2C1.58579 8.75 1.25 8.41421 1.25 8C1.25 7.58579 1.58579 7.25 2 7.25H3.09766ZM14 7.25C14.4142 7.25 14.75 7.58579 14.75 8C14.75 8.41421 14.4142 8.75 14 8.75H8.90234C8.96417 8.51006 9 8.25925 9 8C9 7.74075 8.96417 7.48994 8.90234 7.25H14ZM7.59766 2.75C7.53583 2.98994 7.5 3.24075 7.5 3.5C7.5 3.75925 7.53583 4.01006 7.59766 4.25H2C1.58579 4.25 1.25 3.91421 1.25 3.5C1.25 3.08579 1.58579 2.75 2 2.75H7.59766ZM14 2.75C14.4142 2.75 14.75 3.08579 14.75 3.5C14.75 3.91421 14.4142 4.25 14 4.25H13.4023C13.4642 4.01006 13.5 3.75925 13.5 3.5C13.5 3.24075 13.4642 2.98994 13.4023 2.75H14Z",
+  circles: [
+    { cx: "6", cy: "8", r: "0.998596" },
+    { cx: "10.4999", cy: "3.5", r: "0.998657" },
+    { cx: "9.75015", cy: "12.5", r: "0.997986" }
+  ]
+};
+export {
+  ICON_ADD_PRESET,
+  ICON_CHECK,
+  ICON_CHEVRON,
+  ICON_CLIPBOARD,
+  ICON_PANEL,
+  ICON_TRASH
+};
+//# sourceMappingURL=icons.js.map

package/dist/icons.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/icons.ts"],"sourcesContent":["// Shared SVG icon geometry — single source of truth across all framework adapters.\n\nexport const ICON_CHEVRON = 'M6 9.5L12 15.5L18 9.5';\n\nexport const ICON_CHECK = 'M5 12.75L10 19L19 5';\n\nexport const ICON_CLIPBOARD = {\n  board: 'M8 6C8 4.34315 9.34315 3 11 3H13C14.6569 3 16 4.34315 16 6V7H8V6Z',\n  sparkle: 'M19.2405 16.1852L18.5436 14.3733C18.4571 14.1484 18.241 14 18 14C17.759 14 17.5429 14.1484 17.4564 14.3733L16.7595 16.1852C16.658 16.4493 16.4493 16.658 16.1852 16.7595L14.3733 17.4564C14.1484 17.5429 14 17.759 14 18C14 18.241 14.1484 18.4571 14.3733 18.5436L16.1852 19.2405C16.4493 19.342 16.658 19.5507 16.7595 19.8148L17.4564 21.6267C17.5429 21.8516 17.759 22 18 22C18.241 22 18.4571 21.8516 18.5436 21.6267L19.2405 19.8148C19.342 19.5507 19.5507 19.342 19.8148 19.2405L21.6267 18.5436C21.8516 18.4571 22 18.241 22 18C22 17.759 21.8516 17.5429 21.6267 17.4564L19.8148 16.7595C19.5507 16.658 19.342 16.4493 19.2405 16.1852Z',\n  body: 'M16 5H17C18.6569 5 20 6.34315 20 8V11M8 5H7C5.34315 5 4 6.34315 4 8V18C4 19.6569 5.34315 21 7 21H12',\n};\n\nexport const ICON_ADD_PRESET = [\n  'M4 6H20',\n  'M4 12H10',\n  'M15 15L21 15',\n  'M18 12V18',\n  'M4 18H10',\n];\n\nexport const ICON_TRASH = [\n  'M5 6.5L5.80734 18.2064C5.91582 19.7794 7.22348 21 8.80023 21H15.1998C16.7765 21 18.0842 19.7794 18.1927 18.2064L19 6.5',\n  'M10 11V16',\n  'M14 11V16',\n  'M3.5 6H20.5',\n  'M8.07092 5.74621C8.42348 3.89745 10.0485 2.5 12 2.5C13.9515 2.5 15.5765 3.89745 15.9291 5.74621',\n];\n\nexport const ICON_PANEL = {\n  path: 'M6.84766 11.75C6.78583 11.9899 6.75 12.2408 6.75 12.5C6.75 12.7592 6.78583 13.0101 6.84766 13.25H2C1.58579 13.25 1.25 12.9142 1.25 12.5C1.25 12.0858 1.58579 11.75 2 11.75H6.84766ZM14 11.75C14.4142 11.75 14.75 12.0858 14.75 12.5C14.75 12.9142 14.4142 13.25 14 13.25H12.6523C12.7142 13.0101 12.75 12.7592 12.75 12.5C12.75 12.2408 12.7142 11.9899 12.6523 11.75H14ZM3.09766 7.25C3.03583 7.48994 3 7.74075 3 8C3 8.25925 3.03583 8.51006 3.09766 8.75H2C1.58579 8.75 1.25 8.41421 1.25 8C1.25 7.58579 1.58579 7.25 2 7.25H3.09766ZM14 7.25C14.4142 7.25 14.75 7.58579 14.75 8C14.75 8.41421 14.4142 8.75 14 8.75H8.90234C8.96417 8.51006 9 8.25925 9 8C9 7.74075 8.96417 7.48994 8.90234 7.25H14ZM7.59766 2.75C7.53583 2.98994 7.5 3.24075 7.5 3.5C7.5 3.75925 7.53583 4.01006 7.59766 4.25H2C1.58579 4.25 1.25 3.91421 1.25 3.5C1.25 3.08579 1.58579 2.75 2 2.75H7.59766ZM14 2.75C14.4142 2.75 14.75 3.08579 14.75 3.5C14.75 3.91421 14.4142 4.25 14 4.25H13.4023C13.4642 4.01006 13.5 3.75925 13.5 3.5C13.5 3.24075 13.4642 2.98994 13.4023 2.75H14Z',\n  circles: [\n    { cx: '6', cy: '8', r: '0.998596' },\n    { cx: '10.4999', cy: '3.5', r: '0.998657' },\n    { cx: '9.75015', cy: '12.5', r: '0.997986' },\n  ],\n};\n"],"mappings":";AAEO,IAAM,eAAe;AAErB,IAAM,aAAa;AAEnB,IAAM,iBAAiB;AAAA,EAC5B,OAAO;AAAA,EACP,SAAS;AAAA,EACT,MAAM;AACR;AAEO,IAAM,kBAAkB;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,aAAa;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,aAAa;AAAA,EACxB,MAAM;AAAA,EACN,SAAS;AAAA,IACP,EAAE,IAAI,KAAK,IAAI,KAAK,GAAG,WAAW;AAAA,IAClC,EAAE,IAAI,WAAW,IAAI,OAAO,GAAG,WAAW;AAAA,IAC1C,EAAE,IAAI,WAAW,IAAI,QAAQ,GAAG,WAAW;AAAA,EAC7C;AACF;","names":[]}