dialkit 1.0.0 → 1.2.0

package/README.md

@@ -1,6 +1,14 @@
 # dialkit
 
-Real-time parameter tweaking for React + Motion.
+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 +71,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.
 
@@ -256,8 +265,47 @@ 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:
+
+**React:**
+```tsx
+<aside style={{ width: 300, height: '100vh', overflow: 'hidden' }}>
+  <DialRoot mode="inline" />
+</aside>
+```
+
+**Solid:**
+```tsx
+<aside style={{ width: '300px', height: '100vh', overflow: 'hidden' }}>
+  <DialRoot mode="inline" />
+</aside>
+```
+
+**Svelte:**
+```svelte
+<aside style:width="300px" style:height="100vh" style:overflow="hidden">
+  <DialRoot mode="inline" />
+</aside>
+```
 
-Mount once at your app root. The panel renders via a portal on `document.body`. It collapses to a small icon button and expands to 280px wide on click.
+In inline mode, the `position` prop is ignored and the collapse-to-icon behavior is disabled.
 
 ---
 
@@ -270,6 +318,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
@@ -307,6 +437,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();
@@ -328,6 +463,160 @@ function PhotoStack() {
 
 ---
 
+## Solid
+
+DialKit also works with Solid. Import from `dialkit/solid` instead of `dialkit` — the API mirrors the React version, with `createDialKit` replacing `useDialKit` and `DialRoot` as a Solid component.
+
+```bash
+npm install dialkit solid-js
+```
+
+```tsx
+// App.tsx
+import { DialRoot } from 'dialkit/solid';
+import 'dialkit/styles.css';
+
+export default function App() {
+  return (
+    <>
+      <MyComponent />
+      <DialRoot />
+    </>
+  );
+}
+```
+
+```tsx
+// component.tsx
+import { createDialKit } from 'dialkit/solid';
+
+function Card() {
+  const params = createDialKit('Card', {
+    blur: [24, 0, 100],
+    scale: 1.2,
+    color: '#ff5500',
+    visible: true,
+  });
+
+  return (
+    <div style={{
+      filter: `blur(${params().blur}px)`,
+      transform: `scale(${params().scale})`,
+      color: params().color,
+      opacity: params().visible ? 1 : 0,
+    }}>
+      ...
+    </div>
+  );
+}
+```
+
+`createDialKit` returns an accessor — call `params()` to read the current values. All control types, config shapes, and panel features (presets, copy, folders) work identically to the React version.
+
+---
+
+## Svelte
+
+DialKit works with Svelte 5 (≥5.8.0). Import from `dialkit/svelte` — no extra dependencies needed.
+
+```bash
+npm install dialkit
+```
+
+```svelte
+<!-- +layout.svelte -->
+<script>
+  import { DialRoot } from 'dialkit/svelte';
+  let { children } = $props();
+</script>
+
+{@render children()}
+<DialRoot />
+```
+
+```svelte
+<!-- Card.svelte -->
+<script>
+  import { createDialKit } from 'dialkit/svelte';
+
+  const params = createDialKit('Card', {
+    blur: [24, 0, 100],
+    scale: 1.2,
+    color: '#ff5500',
+    visible: true
+  });
+</script>
+
+<div style:filter={`blur(${params.blur}px)`} style:color={params.color}>
+  ...
+</div>
+```
+
+`createDialKit` returns a reactive object — access values directly (e.g. `params.blur`). Styles are injected automatically by `DialRoot` (no CSS import needed). Cleanup is automatic when the component unmounts. All control types, presets, folders, and transitions match the React/Solid entries.
+
+---
+
+## 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:
@@ -339,6 +628,8 @@ import type {
   SelectConfig,
   ColorConfig,
   TextConfig,
+  ShortcutConfig,
+  ShortcutMode,
   DialConfig,
   DialValue,
   ResolvedValues,