dialkit 1.2.1 → 1.3.0

package/README.md

@@ -72,6 +72,8 @@ const params = useDialKit(name, config, options?)
 |-------|------|-------------|
 | `name` | `string` | Panel title displayed in the UI |
 | `config` | `DialConfig` | Parameter definitions (see Control Types below) |
+| `options.id` | `string` | Stable logical id for sharing values across remounts/pages |
+| `options.persist` | `DialKitPersistOptions` | Persist values to browser storage |
 | `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)) |
 
@@ -79,6 +81,122 @@ Returns a fully typed object matching your config shape with live values. Updati
 
 ---
 
+## Stable IDs and Persistence
+
+By default, a DialKit panel is tied to the lifecycle of the component that calls `useDialKit`. Pass `id` when multiple mounts should reconnect to the same logical panel, and pass `persist: true` when values should survive reloads and browser sessions.
+
+```tsx
+// dials/useOnboardingDials.ts
+import { useDialKit } from 'dialkit';
+
+export function useOnboardingDials() {
+  return useDialKit('Onboarding', {
+    name: { type: 'text', default: 'Avery', placeholder: 'Name' },
+    avatarScale: [1, 0.6, 1.6, 0.01],
+    accent: { type: 'color', default: '#6C5CE7' },
+  }, {
+    id: 'onboarding',
+    persist: true,
+  });
+}
+```
+
+Use that helper anywhere the shared values are needed:
+
+```tsx
+function PageTwo() {
+  const onboarding = useOnboardingDials();
+
+  const page = useDialKit('Page Two', {
+    cardRadius: [16, 0, 64],
+  });
+
+  return (
+    <Card
+      name={onboarding.name}
+      radius={page.cardRadius}
+      accent={onboarding.accent}
+    />
+  );
+}
+```
+
+When `PageTwo` is mounted, the single `<DialRoot />` shows both `Onboarding` and `Page Two` as top-level sections. If another page calls `useOnboardingDials()`, DialKit reconnects to the same `id` and keeps the shared values.
+
+`persist: true` stores values, presets, and the active preset in `localStorage` using `dialkit:${id}` as the key. Use the object form to customize storage:
+
+```tsx
+useDialKit('Onboarding', config, {
+  id: 'onboarding',
+  persist: {
+    key: 'my-app:onboarding-dials',
+    storage: 'sessionStorage',
+    presets: false,
+  },
+});
+```
+
+The `id` string has no special format; it only needs to be reused wherever you want the same logical panel. Without `id` or `persist`, DialKit behaves exactly as before.
+
+---
+
+## useDialKitController
+
+Use the controller API when your app code also needs to update DialKit values, such as reset buttons, URL sync, or app-defined preset buttons.
+
+```tsx
+import { useDialKitController } from 'dialkit';
+
+function Card() {
+  const dial = useDialKitController('Card', {
+    blur: [24, 0, 100],
+    scale: 1.2,
+    color: '#ff5500',
+    visible: true,
+    shadow: {
+      radius: [16, 0, 64],
+    },
+  });
+
+  return (
+    <>
+      <button onClick={() => dial.setValues({
+        blur: 48,
+        scale: 1,
+        shadow: { radius: 28 },
+      })}>
+        Apply preset
+      </button>
+      <button onClick={() => dial.resetValues()}>Reset</button>
+
+      <div style={{
+        filter: `blur(${dial.values.blur}px)`,
+        transform: `scale(${dial.values.scale})`,
+        color: dial.values.color,
+        opacity: dial.values.visible ? 1 : 0,
+        borderRadius: dial.values.shadow.radius,
+      }}>
+        ...
+      </div>
+    </>
+  );
+}
+```
+
+Controller methods:
+
+| Method | Description |
+|--------|-------------|
+| `values` | The same live resolved values returned by `useDialKit` |
+| `setValue(path, value)` | Updates one control by dot path, like `'shadow.radius'` |
+| `setValues(values)` | Updates multiple controls with a typed nested partial object |
+| `resetValues()` | Restores the current config defaults and clears the active preset |
+| `getValues()` | Reads the latest resolved values outside render callbacks |
+
+Programmatic updates use the same state as panel edits. If a saved preset is active, updates are saved into that preset; otherwise they update the base "Version 1" values. Action controls are triggers, so they are not set by `setValues`.
+
+---
+
 ## Control Types
 
 ### Slider
@@ -269,9 +387,47 @@ const values = useDialKit('Controls', {
 | `defaultOpen` | `boolean` | `true` |
 | `mode` | `'popover' \| 'inline'` | `'popover'` |
 | `productionEnabled` | `boolean` | `false` in production, `true` otherwise |
+| `onOpenChange` | `(open: boolean) => void` | `undefined` |
 
 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.
 
+### Multiple panels
+
+If multiple `useDialKit` calls are registered under the same root, DialKit renders one shared shell and shows each panel as a collapsible top-level section. No extra API is needed:
+
+```tsx
+function PhotoStack() {
+  const photo = useDialKit('Photo Stack', {
+    blur: [12, 0, 40],
+    scale: [1, 0.5, 2],
+  });
+
+  const stage = useDialKit('Stage', {
+    pagePadding: [40, 16, 96],
+    background: '#ffffff',
+  });
+
+  return (
+    <div style={{ padding: stage.pagePadding, background: stage.background }}>
+      <img style={{ filter: `blur(${photo.blur}px)`, transform: `scale(${photo.scale})` }} />
+    </div>
+  );
+}
+```
+
+The mounted `<DialRoot />` stays the same. With a single registered panel, the panel title and layout stay unchanged. This behavior works the same way in React, Solid, Svelte, and Vue.
+
+Use `onOpenChange` when you need to persist whether the floating panel is open or collapsed:
+
+```tsx
+<DialRoot
+  defaultOpen={localStorage.getItem('dialkit-open') !== '0'}
+  onOpenChange={(open) => {
+    localStorage.setItem('dialkit-open', open ? '1' : '0');
+  }}
+/>
+```
+
 DialKit is automatically hidden in production builds. To enable it in production, pass `productionEnabled`:
 
 ```tsx
@@ -513,7 +669,22 @@ function Card() {
 }
 ```
 
-`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.
+`createDialKit` returns an accessor — call `params()` to read the current values. All control types, config shapes, and panel features (presets, copy, folders, and `DialRoot` props like `onOpenChange`) work identically to the React version.
+
+Use `createDialKitController` when Solid code needs to update values:
+
+```tsx
+import { createDialKitController } from 'dialkit/solid';
+
+const dial = createDialKitController('Card', {
+  blur: [24, 0, 100],
+  shadow: { radius: [16, 0, 64] },
+});
+
+dial.setValues({ blur: 48, shadow: { radius: 28 } });
+dial.resetValues();
+dial.values().blur;
+```
 
 ---
 
@@ -554,7 +725,30 @@ npm install dialkit
 </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.
+`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, transitions, and `DialRoot` props like `onOpenChange` match the React/Solid entries.
+
+Use `createDialKitController` when Svelte code needs to update values:
+
+```svelte
+<script>
+  import { createDialKitController } from 'dialkit/svelte';
+
+  const dial = createDialKitController('Card', {
+    blur: [24, 0, 100],
+    shadow: { radius: [16, 0, 64] }
+  });
+
+  const params = dial.values;
+</script>
+
+<button onclick={() => dial.setValues({ blur: 48, shadow: { radius: 28 } })}>
+  Apply preset
+</button>
+
+<div style:filter={`blur(${params.blur}px)`} style:border-radius={`${params.shadow.radius}px`}>
+  ...
+</div>
+```
 
 ---
 
@@ -586,7 +780,7 @@ import Card from './Card.vue';
 
 <template>
   <Card />
-  <DialRoot />
+  <DialRoot @open-change="(open) => localStorage.setItem('dialkit-open', open ? '1' : '0')" />
 </template>
 ```
 
@@ -617,6 +811,25 @@ const params = useDialKit('Card', {
 
 `useDialKit` returns a reactive object. All control types, presets, folders, keyboard shortcuts, and transitions work identically to the other frameworks.
 
+Use `useDialKitController` when Vue code needs to update values:
+
+```vue
+<script setup>
+import { useDialKitController } from 'dialkit/vue';
+
+const { values, setValues, resetValues } = useDialKitController('Card', {
+  blur: [24, 0, 100],
+  shadow: { radius: [16, 0, 64] },
+});
+</script>
+
+<template>
+  <button @click="setValues({ blur: 48, shadow: { radius: 28 } })">Apply preset</button>
+  <button @click="resetValues()">Reset</button>
+  <div :style="{ filter: `blur(${values.blur}px)`, borderRadius: `${values.shadow.radius}px` }" />
+</template>
+```
+
 ---
 
 ## Types
@@ -626,6 +839,8 @@ All config and value types are exported:
 ```tsx
 import type {
   SpringConfig,
+  EasingConfig,
+  TransitionConfig,
   ActionConfig,
   SelectConfig,
   ColorConfig,
@@ -634,6 +849,8 @@ import type {
   ShortcutMode,
   DialConfig,
   DialValue,
+  DialKitController,
+  DialKitValueUpdates,
   ResolvedValues,
   ControlMeta,
   PanelConfig,

package/dist/dropdown-position.d.ts

@@ -0,0 +1,15 @@
+type DropdownPosition = {
+    top: number;
+    left: number;
+    width: number;
+    above: boolean;
+};
+type DropdownPositionOptions = {
+    dropdownHeight?: number;
+    gap?: number;
+    allowAbove?: boolean;
+};
+declare function getDropdownPosition(trigger: HTMLElement, portalRoot: HTMLElement, options?: DropdownPositionOptions): DropdownPosition;
+declare function getDialKitPortalRoot(trigger: HTMLElement | null | undefined): HTMLElement | null;
+
+export { type DropdownPosition, type DropdownPositionOptions, getDialKitPortalRoot, getDropdownPosition };

package/dist/dropdown-position.js

@@ -0,0 +1,22 @@
+// src/dropdown-position.ts
+function getDropdownPosition(trigger, portalRoot, options = {}) {
+  const { dropdownHeight = 0, gap = 4, allowAbove = true } = options;
+  const triggerRect = trigger.getBoundingClientRect();
+  const rootRect = portalRoot.getBoundingClientRect();
+  const spaceBelow = window.innerHeight - triggerRect.bottom - gap;
+  const above = allowAbove && spaceBelow < dropdownHeight && triggerRect.top > spaceBelow;
+  return {
+    top: above ? triggerRect.top - rootRect.top - dropdownHeight - gap : triggerRect.bottom - rootRect.top + gap,
+    left: triggerRect.left - rootRect.left,
+    width: triggerRect.width,
+    above
+  };
+}
+function getDialKitPortalRoot(trigger) {
+  return trigger?.closest(".dialkit-root") ?? null;
+}
+export {
+  getDialKitPortalRoot,
+  getDropdownPosition
+};
+//# sourceMappingURL=dropdown-position.js.map

package/dist/dropdown-position.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/dropdown-position.ts"],"sourcesContent":["export type DropdownPosition = {\n  top: number;\n  left: number;\n  width: number;\n  above: boolean;\n};\n\nexport type DropdownPositionOptions = {\n  dropdownHeight?: number;\n  gap?: number;\n  allowAbove?: boolean;\n};\n\nexport function getDropdownPosition(\n  trigger: HTMLElement,\n  portalRoot: HTMLElement,\n  options: DropdownPositionOptions = {}\n): DropdownPosition {\n  const { dropdownHeight = 0, gap = 4, allowAbove = true } = options;\n  const triggerRect = trigger.getBoundingClientRect();\n  const rootRect = portalRoot.getBoundingClientRect();\n  const spaceBelow = window.innerHeight - triggerRect.bottom - gap;\n  const above = allowAbove && spaceBelow < dropdownHeight && triggerRect.top > spaceBelow;\n\n  return {\n    top: above\n      ? triggerRect.top - rootRect.top - dropdownHeight - gap\n      : triggerRect.bottom - rootRect.top + gap,\n    left: triggerRect.left - rootRect.left,\n    width: triggerRect.width,\n    above,\n  };\n}\n\nexport function getDialKitPortalRoot(trigger: HTMLElement | null | undefined): HTMLElement | null {\n  return (trigger?.closest('.dialkit-root') as HTMLElement | null) ?? null;\n}\n"],"mappings":";AAaO,SAAS,oBACd,SACA,YACA,UAAmC,CAAC,GAClB;AAClB,QAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,aAAa,KAAK,IAAI;AAC3D,QAAM,cAAc,QAAQ,sBAAsB;AAClD,QAAM,WAAW,WAAW,sBAAsB;AAClD,QAAM,aAAa,OAAO,cAAc,YAAY,SAAS;AAC7D,QAAM,QAAQ,cAAc,aAAa,kBAAkB,YAAY,MAAM;AAE7E,SAAO;AAAA,IACL,KAAK,QACD,YAAY,MAAM,SAAS,MAAM,iBAAiB,MAClD,YAAY,SAAS,SAAS,MAAM;AAAA,IACxC,MAAM,YAAY,OAAO,SAAS;AAAA,IAClC,OAAO,YAAY;AAAA,IACnB;AAAA,EACF;AACF;AAEO,SAAS,qBAAqB,SAA6D;AAChG,SAAQ,SAAS,QAAQ,eAAe,KAA4B;AACtE;","names":[]}