dialkit 0.2.1 → 1.0.0

package/README.md

@@ -72,12 +72,24 @@ Returns a fully typed object matching your config shape with live values. Updati
 
 ### Slider
 
+Numbers create sliders. There are three ways to define them:
+
+**Explicit range** — `[default, min, max]`:
+```tsx
+blur: [24, 0, 100]
+```
+
+**Explicit range + step** — `[default, min, max, step]`:
 ```tsx
-blur: [24, 0, 100]      // [default, min, max] — explicit range
-scale: 1.2              // auto-infers range from value
+blur: [24, 0, 100, 5]    // snaps in increments of 5
 ```
+When `step` is omitted, it's inferred from the range (see table below).
 
-Numbers create sliders. With a tuple `[default, min, max]` you set the range explicitly. A bare number auto-infers a reasonable range:
+**Auto-inferred** — bare number:
+```tsx
+scale: 1.2
+```
+A single number auto-infers a reasonable min, max, and step:
 
 | Value range | Inferred min/max | Step |
 |-------------|-----------------|------|
@@ -194,22 +206,42 @@ const p = useDialKit('Controls', {
 ```
 
 Action buttons trigger callbacks without storing any value. The `label` defaults to the formatted key name (camelCase becomes Title Case). Multiple adjacent actions are grouped vertically.
+Action buttons can be placed at the root or nested inside folders.
 
 ### Folder
 
+Any nested plain object becomes a collapsible folder. Folders can nest arbitrarily deep.
+
 ```tsx
 shadow: {
   blur: [10, 0, 50],
   opacity: [0.25, 0, 1],
   color: '#000000',
 }
+
+// Access nested values:
+params.shadow.blur     // number
+params.shadow.color    // string
 ```
 
-Any nested plain object becomes a collapsible folder. Folders can nest arbitrarily deep. Access nested values with dot notation on the returned object:
+Folders are open by default. Add `_collapsed: true` to start a folder closed. This is a reserved metadata key — it controls the UI only and won't appear in your returned values.
 
 ```tsx
-params.shadow.blur     // number
-params.shadow.color    // string
+shadow: {
+  _collapsed: true,    // folder starts closed
+  blur: [10, 0, 50],
+  opacity: [0.25, 0, 1],
+}
+```
+
+DialKit also supports dynamic config updates. If your config shape, defaults, options, or labels change over time, the panel updates while preserving current values where paths still exist.
+
+Dynamic configs work with both inline objects and memoized configs — no special consumer action needed:
+
+```tsx
+const values = useDialKit('Controls', {
+  style: { type: 'select', options: dynamicOptions },
+});
 ```
 
 ---
@@ -223,6 +255,7 @@ params.shadow.color    // string
 | Prop | Type | Default |
 |------|------|---------|
 | `position` | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'top-right'` |
+| `defaultOpen` | `boolean` | `true` |
 
 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.