Feat/settings id keyed dependencies (#92)

* feat(settings): support plain field-id keys for dependency lookups

Plugin-ui's formatSettingsData() rebuilds dependency_key as a dot-path
(parent.child.field) and the values map is keyed by that dot-path.
Dependencies declared with a plain field id (e.g., 'commission_type'
instead of 'commission.commission.commission_type') therefore failed to
resolve via values[dep.key].

Add an id-keyed fallback so both formats work side by side:

- Export buildIdIndex(schema) from settings-formatter — produces a
  { field_id: dependency_key } map from the hierarchical schema.
- evaluateDependencies() accepts an optional idIndex argument. When
  values[dep.key] is undefined and an idIndex is supplied, the function
  resolves dep.key as a field id and re-reads values via the index.
- SettingsProvider builds the idIndex (memoised on schema) and threads
  it through shouldDisplay → evaluateDependencies.

Backwards compatible: callers that don't pass idIndex see identical
behavior. Consumers whose backend guarantees globally-unique field ids
(e.g., flat-storage schemas) can now use id-keyed dependencies, which
stay valid across structural moves (no parent path to update).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(settings): formatter preserves server-supplied dependency_key; falls back to id

The formatter used to rebuild `dependency_key` on every render by joining
the parent chain into a dot-path. That silently overwrote whatever the
server sent. Now we prefer the server value and fall back to the element
id when missing (Phase 1 of the dependency_key cleanup; consumers are
updated in Phase 2).

- formatSettingsData: keep `child.dependency_key` if present, else `child.id`
- formatSettingsData: same fallback for the root page (was hard-coded `''`)
- Add jest unit tests covering nested preservation, nested fallback, and
  the page-itself case

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(settings): consumers read element.id; dependency_key becomes vestigial

Now that the server emits and consumes flat element ids exclusively
(Phase 2 of the dependency_key cleanup), every plugin-ui consumer was
keying off element.dependency_key for values, errors, dirty tracking,
and onChange callbacks. Replace those reads with element.id:

- field-renderer.tsx: merged element value/validationError lookups
- fields.tsx: all 20 onChange(element.dependency_key!, ...) call sites
- settings-context.tsx: scopeFieldKeysMap, findElement, comments
- settings-formatter.ts:
  * extractValues now keys by el.id
  * validations/dependencies self pointer uses child.id
  * buildIdIndex collapses to identity (kept for API stability;
    evaluateDependencies fallback path is now a no-op for properly
    keyed schemas, slated for removal in Task 11)
- settings-types.ts: SettingsProps.values doc comment

dependency_key is left on the type and on the formatter back-compat
assignments to avoid breaking external consumers in this commit; Task 11
removes the residue.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(settings): drop dependency_key from types, formatter, and tests

Task 11 of the dependency_key cleanup. Removes:

- dependency_key field from the SettingsElement type
- formatter back-compat assignments (child.dependency_key = ... || id)
- buildIdIndex helper + idIndex parameter on evaluateDependencies (the
  helper collapsed to identity in Task 8 and is now dead — dep keys are
  plain field ids, read directly from the flat values map)
- buildIdIndex import + idIndex usage in settings-context
- ~472 dependency_key literals from Settings.stories.tsx fixtures
- example dependency_key fields from DeveloperGuide.mdx code samples

Rewrites the formatter unit tests to assert id preservation through
nested parent resolution and that dependency_key no longer materializes
on enriched elements. Settings.mdx prose mentions are left for Task 12
(documentation phase).

* docs(settings): drop dependency_key from developer guides and stories

Add DOKAN_NEXT_MAJOR deprecation callout to CLAUDE.md, DEVELOPER_GUIDE.md,
src/DeveloperGuide.mdx, and src/components/settings/Settings.mdx. Replace
prose and embedded code-example mentions of dependency_key with the field's
id, and update treeValues/flatValues descriptions and examples to the flat
id-keyed shape (no dot-paths).

* feat(settings): add danger_switch and info_preview field variants

danger_switch — a dedicated variant for destructive toggles (e.g. "clear all
data on uninstall"). Renders in a destructive-tinted card, always confirms the
off → on transition through an AlertDialog, and reads confirm_modal (title /
description / confirmText / cancelText / optional checkboxLabel for an
acknowledgement gate) from the schema. Built as a separate variant rather than
overloading SwitchField with should_confirm / switcher_type / is_danger flags,
so the simple switch stays simple.

info_preview — generic "pick a few things to display" field with an optional
preview on the right. Renders label, description, and a checkbox list driven
by element.options; value shape is Record<string, boolean> keyed by
option.value. Preview slot resolution order:
  1. ${hookPrefix}_settings_info_preview_field_preview filter
     (receives (null, element, value) → may return a React node).
  2. element.image_url rendered as <img>.
  3. nothing.

The filter-based preview slot lets consumers attach dynamic previews
(charts, mocks, live HTML) without re-implementing the whole field.

Strengthens switcher_type and confirm_modal types in settings-types.ts so
schema authors get autocomplete instead of Record<string, any>.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* feat(settings): cross-field sum_max validation rule + auto re-validation

Add a `sum_max` rule to validateField that accepts either:

  params: { field: 'sibling_id', max: 28 }              // single sibling
  params: { fields: ['a', 'b', 'c'], max: 100 }         // N siblings

The rule sums self + every referenced sibling and fails when the total
exceeds `max`. Defensive: when allValues is not supplied or any sibling
value is missing/non-numeric, the rule passes silently to avoid false
positives on partial value snapshots (e.g. during initial hydration).

validateField now takes an optional `allValues` snapshot parameter so any
future cross-field rule can read sibling state without callers having to
re-plumb every site. Single-field rules remain unchanged.

In settings-context, updateValue now:
  - Builds a local `nextValues` snapshot and feeds it to validateField.
  - Walks the schema to find every sibling whose `validations[*].params`
    references the just-changed key (via `field` or `fields[]`) and
    re-validates them. So when a user fixes one side of a cross-field
    constraint, the OTHER side's stale error auto-clears.

Use case: a schema can now declare `monthly_billing_day + due_period <= 28`
by attaching the same `sum_max` rule to both fields with the symmetric
`field` pointing at the sibling. Editing either field surfaces the
error on that field; fixing it clears both.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(ui): select dropdown overflow, trigger truncation, anchored-mode clipping

Three independent fixes in `Select`, all surfaced while wiring the AI
Assist provider/model selects:

1. Trigger value (SelectValue): add `min-w-0 truncate` so long titles
   ellipsis inside the fixed-width trigger instead of pushing the chevron
   out of the flex track and rendering over the value.

2. Dropdown options (SelectItem.ItemText): replace `shrink-0 whitespace-nowrap`
   with `min-w-0 whitespace-normal break-words text-start`. Pickers must
   never truncate the option label — the user needs the full text to
   choose. Long titles now wrap to multiple lines within the popup's
   `--anchor-width` and the popup scrolls vertically.

3. SelectContent default `alignItemWithTrigger`: flip from `true` to
   `false`. base-ui's anchored mode measures item heights at open time to
   position the popup so the selected option sits on the trigger; with
   wrap-enabled items the pre-paint measurement reports a smaller height
   than the actual wrapped height, so first-open positions the popup
   above the viewport and clips the top option. Subsequent opens use the
   settled heights and render fine. Defaulting to a standard "open below
   trigger" dropdown removes the inconsistency. Callers can still opt
   into anchored mode explicitly.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: mrabbani

CLAUDE.md

@@ -1,5 +1,13 @@
 # @wedevs/plugin-ui
 
+> **Note (DOKAN_NEXT_MAJOR):** The `dependency_key` attribute has been removed
+> from the settings schema. Use the field's `id` directly. `show_if` and
+> `dependencies` rule keys are now flat field ids — dot-paths are no longer
+> supported. See the [dependency_key cleanup plan][cleanup-plan] for migration
+> context.
+>
+> [cleanup-plan]: https://github.com/getdokan/dokan/blob/refactor/simplify-settings-to-flat-array/docs/superpowers/plans/2026-05-18-dependency-key-cleanup.md
+
 Scoped, themeable React component library for WordPress plugins. Built on ShadCN patterns, Tailwind CSS v4, and Base-UI primitives.
 
 ## Architecture
@@ -55,15 +63,15 @@ import { Settings } from '@wedevs/plugin-ui';
 
 <Settings
   schema={settingsSchema}        // SettingsElement[] (flat or hierarchical)
-  values={values}                // Record<string, any> keyed by dependency_key
+  values={values}                // Record<string, any> keyed by field id
   onChange={(scopeId, key, value) => {
     setValues(prev => ({ ...prev, [key]: value }));
   }}
   onSave={async (scopeId, treeValues, flatValues) => {
-    // treeValues: nested object built from dot-separated keys
-    //   e.g. { dokan: { general: { store_name: "..." } } }
-    // flatValues: original flat dot-keyed values
-    //   e.g. { "dokan.general.store_name": "..." }
+    // treeValues: object keyed by field id
+    //   e.g. { store_name: "...", enable_tax: true }
+    // flatValues: same shape — flat id-keyed values
+    //   e.g. { store_name: "...", enable_tax: true }
     await api.post(`/settings/${scopeId}`, treeValues);
   }}
   renderSaveButton={({ dirty, hasErrors, onSave }) => (
@@ -76,7 +84,7 @@ import { Settings } from '@wedevs/plugin-ui';
 
 ### Key Concepts
 
-- **`dependency_key`**: Unique key on each field element, used as the key in `values` and `flatValues`
+- **`id`**: Unique key on each field element, used as the key in `values` and `flatValues`
 - **Dependencies**: Elements can conditionally show/hide based on other field values via `dependencies` array
 - **Validation**: Per-field `validations` array with rules and error messages
 - **Dirty tracking**: Per-scope (subpage/page) dirty state; resets only on successful save

DEVELOPER_GUIDE.md

@@ -1,5 +1,13 @@
 # @wedevs/plugin-ui — Developer Guide
 
+> **Note (DOKAN_NEXT_MAJOR):** The `dependency_key` attribute has been removed
+> from the settings schema. Use the field's `id` directly. `show_if` and
+> `dependencies` rule keys are now flat field ids — dot-paths are no longer
+> supported. See the [dependency_key cleanup plan][cleanup-plan] for migration
+> context.
+>
+> [cleanup-plan]: https://github.com/getdokan/dokan/blob/refactor/simplify-settings-to-flat-array/docs/superpowers/plans/2026-05-18-dependency-key-cleanup.md
+
 A ShadCN-style React component library built for WordPress plugins. Provides 50+ themed, accessible UI components powered by Tailwind CSS v4, `@base-ui/react` headless primitives, and first-class WordPress integration.
 
 ---
@@ -1088,23 +1096,20 @@ const schema: SettingsElement[] = [
                 type: 'field',
                 variant: 'text',
                 label: __('Store Name', 'my-plugin'),
-                dependency_key: 'store_name',
                 default: '',
               },
               {
                 id: 'enable_tax',
                 type: 'field',
                 variant: 'switch',
                 label: __('Enable Tax', 'my-plugin'),
-                dependency_key: 'enable_tax',
                 default: false,
               },
               {
                 id: 'tax_rate',
                 type: 'field',
                 variant: 'number',
                 label: __('Tax Rate (%)', 'my-plugin'),
-                dependency_key: 'tax_rate',
                 dependencies: [{ key: 'enable_tax', value: true, comparison: '=' }],
               },
             ],

src/DeveloperGuide.mdx

@@ -6,6 +6,12 @@ import { Meta } from "@storybook/addon-docs/blocks";
 
 # @wedevs/plugin-ui — Developer Guide
 
+> **Note (DOKAN_NEXT_MAJOR):** The `dependency_key` attribute has been removed
+> from the settings schema. Use the field's `id` directly. `show_if` and
+> `dependencies` rule keys are now flat field ids — dot-paths are no longer
+> supported. See the [dependency_key cleanup plan](https://github.com/getdokan/dokan/blob/refactor/simplify-settings-to-flat-array/docs/superpowers/plans/2026-05-18-dependency-key-cleanup.md)
+> for migration context.
+
 A ShadCN-style React component library built for WordPress plugins. Provides 50+ themed, accessible UI components powered by Tailwind CSS v4, `@base-ui/react` headless primitives, and first-class WordPress integration.
 
 ---
@@ -892,9 +898,9 @@ const schema: SettingsElement[] = [
       children: [{
         id: 'basic_section', type: 'section', label: __('Basic Settings', 'my-plugin'),
         children: [
-          { id: 'store_name', type: 'field', variant: 'text', label: __('Store Name', 'my-plugin'), dependency_key: 'store_name', default: '' },
-          { id: 'enable_tax', type: 'field', variant: 'switch', label: __('Enable Tax', 'my-plugin'), dependency_key: 'enable_tax', default: false },
-          { id: 'tax_rate', type: 'field', variant: 'number', label: __('Tax Rate (%)', 'my-plugin'), dependency_key: 'tax_rate',
+          { id: 'store_name', type: 'field', variant: 'text', label: __('Store Name', 'my-plugin'), default: '' },
+          { id: 'enable_tax', type: 'field', variant: 'switch', label: __('Enable Tax', 'my-plugin'), default: false },
+          { id: 'tax_rate', type: 'field', variant: 'number', label: __('Tax Rate (%)', 'my-plugin'),
             dependencies: [{ key: 'enable_tax', value: true, comparison: '=' }] },
         ],
       }],

src/components/settings/Settings.mdx

@@ -6,6 +6,12 @@ import { Meta } from "@storybook/addon-docs/blocks";
 
 # Settings Component
 
+> **Note (DOKAN_NEXT_MAJOR):** The `dependency_key` attribute has been removed
+> from the settings schema. Use the field's `id` directly. `show_if` and
+> `dependencies` rule keys are now flat field ids — dot-paths are no longer
+> supported. See the [dependency_key cleanup plan](https://github.com/getdokan/dokan/blob/refactor/simplify-settings-to-flat-array/docs/superpowers/plans/2026-05-18-dependency-key-cleanup.md)
+> for migration context.
+
 A reusable, schema-driven settings page that renders a full UI from a JSON structure.
 Designed for WordPress plugin settings with built-in extensibility.
 
@@ -51,11 +57,10 @@ const schema: SettingsElement[] = [
             label: "Main",
             children: [
               {
-                id: "site_name_field",
+                id: "site_name",
                 type: "field",
                 variant: "text",
                 label: "Site Name",
-                dependency_key: "site_name",
                 default: "",
               },
             ],
@@ -78,8 +83,8 @@ function MySettingsPage() {
         setValues((prev) => ({ ...prev, [key]: value }));
       }}
       onSave={(scopeId, treeValues, flatValues) => {
-        // treeValues: nested object from dot-separated keys
-        // flatValues: original flat dot-keyed values
+        // treeValues: object keyed by field id
+        // flatValues: same shape — flat id-keyed values
         console.log("Saving", scopeId, treeValues, flatValues);
       }}
       renderSaveButton={({ dirty, hasErrors, onSave }) => (
@@ -277,15 +282,13 @@ Groups multiple fields in a horizontal row (e.g. min/max pair).
       "id": "min_price",
       "type": "field",
       "variant": "number",
-      "label": "Min",
-      "dependency_key": "min_price"
+      "label": "Min"
     },
     {
       "id": "max_price",
       "type": "field",
       "variant": "number",
-      "label": "Max",
-      "dependency_key": "max_price"
+      "label": "Max"
     }
   ]
 }
@@ -297,13 +300,12 @@ An individual form input. The `variant` determines which UI control renders.
 
 ```json
 {
-  "id": "store_name_field",
+  "id": "store_name",
   "type": "field",
   "variant": "text",
   "label": "Store Name",
   "description": "The display name of your store.",
   "tooltip": "Visible to customers.",
-  "dependency_key": "store_name",
   "default": "My Store",
   "placeholder": "Enter store name"
 }
@@ -400,8 +402,8 @@ Used by `select`, `radio_capsule`, `customize_radio`, and `multicheck`:
 
 ```json
 {
+  "id": "enable_feature",
   "variant": "switch",
-  "dependency_key": "enable_feature",
   "enable_state": { "value": "on", "title": "Enabled" },
   "disable_state": { "value": "off", "title": "Disabled" }
 }
@@ -430,11 +432,10 @@ const flatData = [
   { id: "basic_tab", type: "tab", label: "Basic", subpage_id: "store" },
   { id: "main_section", type: "section", label: "Main", tab_id: "basic_tab" },
   {
-    id: "name_field",
+    id: "store_name",
     type: "field",
     variant: "text",
     label: "Store Name",
-    dependency_key: "store_name",
     section_id: "main_section",
   },
 ];
@@ -510,7 +511,7 @@ Fired whenever a field value changes.
     <tr>
       <td><code>key</code></td>
       <td><code>string</code></td>
-      <td>The field's <code>dependency_key</code></td>
+      <td>The field's <code>id</code></td>
     </tr>
     <tr>
       <td><code>value</code></td>
@@ -550,12 +551,12 @@ Fired when the save button is clicked. Only receives values **scoped to the acti
     <tr>
       <td><code>treeValues</code></td>
       <td><code>{'Record<string, any>'}</code></td>
-      <td>Nested object built from dot-separated keys (e.g. <code>{'{"dokan":{"general":{"store_name":"..."}}}'}</code>)</td>
+      <td>Object keyed by field id (e.g. <code>{'{"store_name":"...","enable_tax":true}'}</code>)</td>
     </tr>
     <tr>
       <td><code>flatValues</code></td>
       <td><code>{'Record<string, any>'}</code></td>
-      <td>Original flat dot-keyed values (e.g. <code>{'{"dokan.general.store_name":"..."}'}</code>)</td>
+      <td>Same shape — flat id-keyed values (e.g. <code>{'{"store_name":"...","enable_tax":true}'}</code>)</td>
     </tr>
   </tbody>
 </table>
@@ -574,7 +575,7 @@ Fired when the save button is clicked. Only receives values **scoped to the acti
 ### Server-Side Validation Errors
 
 If your API returns field-level validation errors, **throw an object** with an `errors` property
-from `onSave`. The keys must match field `dependency_key` values:
+from `onSave`. The keys must match field `id` values:
 
 ```tsx
 <Settings
@@ -587,9 +588,9 @@ from `onSave`. The keys must match field `dependency_key` values:
 
     if (!res.ok) {
       const data = await res.json();
-      // Throw with { errors: { [dependency_key]: "message" } }
+      // Throw with { errors: { [fieldId]: "message" } }
       throw { errors: data.errors };
-      // e.g. { errors: { "dokan.general.store_name": "Store name already taken" } }
+      // e.g. { errors: { "store_name": "Store name already taken" } }
     }
   }}
 />
@@ -714,11 +715,10 @@ Fields can be conditionally shown/hidden based on other field values using the
 
 ```json
 {
-  "id": "tax_rate_field",
+  "id": "tax_rate",
   "type": "field",
   "variant": "number",
   "label": "Tax Rate (%)",
-  "dependency_key": "tax_rate",
   "dependencies": [
     {
       "key": "enable_tax",
@@ -745,7 +745,7 @@ This field only appears when `enable_tax` is `true`.
     <tr>
       <td><code>key</code></td>
       <td><code>string</code></td>
-      <td><code>dependency_key</code> of the field to watch</td>
+      <td><code>id</code> of the field to watch</td>
     </tr>
     <tr>
       <td><code>value</code></td>
@@ -803,7 +803,7 @@ const schema = formatSettingsData(flatApiResponse);
 
 ### `extractValues(schema)`
 
-Walks a hierarchical schema and extracts all `dependency_key` to `value` pairs into a flat object.
+Walks a hierarchical schema and extracts all `id` to `value` pairs into a flat object.
 Useful for initializing the `values` prop.
 
 ```tsx
@@ -839,7 +839,7 @@ const initialValues = extractValues(schema);
       <td><code>values</code></td>
       <td><code>{'Record<string, any>'}</code></td>
       <td><code>{'{}'}</code></td>
-      <td>Current field values keyed by <code>dependency_key</code></td>
+      <td>Current field values keyed by <code>id</code></td>
     </tr>
     <tr>
       <td><code>onChange</code></td>