ov-configurator 1.0.0 → 1.1.1

package/README.md

@@ -1,11 +1,16 @@
-# ov-cart
+# ov-configurator
 
-Universal frontend shopping cart module. Exports `createCart(options)`.
+Universal frontend product configurator module. Exports `Calculator` and `initConfigurator`.
+
+The package ships two complementary tools:
+
+- **`Calculator`** — a low-level class that renders a form, tracks selected values and computes derived fields (price, labels, etc.). Configure everything in JS.
+- **`initConfigurator`** — a higher-level helper that reads an inline JS config from the DOM (`[data-configurator-options]`) and builds a fully wired `Calculator` for a product element. Designed for server-rendered pages where the config lives in HTML.
 
 ## Installation
 
 ```bash
-npm install ov-cart
+npm install ov-configurator
 ```
 
 ## CDN
@@ -13,158 +18,221 @@ npm install ov-cart
 No build step required — include directly via [jsDelivr](https://www.jsdelivr.com/) or [unpkg](https://unpkg.com/):
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/ov-cart/dist/ov-cart.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/ov-configurator/dist/ov-configurator.iife.js"></script>
 <script>
-    const cart = OvCart.createCart({ element: '#cart', currency: '$' })
+    const { Calculator, initConfigurator } = OvConfiurator
 </script>
 ```
 
-The IIFE bundle exposes a global `OvCart` with `createCart` and `Cart`.
+The IIFE bundle exposes a global `OvConfiurator` with `Calculator` and `initConfigurator`.
+
+---
+
+## Calculator
+
+Renders a `<form>` with radio/checkbox sections and recomputes fields on every change.
 
-## Usage
+### Basic usage
 
 ```ts
-import { createCart } from 'ov-cart'
-
-const cart = createCart({
-    element: '#my-cart',
-    currency: '$',
-    storageKey: 'shop-cart',
-    attr: 'mycart',             // uses data-mycart-* instead of data-cart-*
-    classes: {
-        countButton: 'btn btn-sm',
-    },
-    onUpdate(state) {
-        // state: { products, productsCount, totalSum, count, isEmpty }
-        if (state.isEmpty) MicroModal.close('modal-cart')
+import { Calculator } from 'ov-configurator'
+
+interface ProductData {
+    sizes: Array<{ label: string; value: string; price: number }>
+}
+
+const calc = new Calculator<ProductData>({
+    id: 'my-product',
+    parentSelector: '#product-card',
+    data: { sizes: [{ label: 'S', value: 's', price: 100 }] },
+    sectionsOptions: [
+        {
+            title: 'Size',
+            type: 'size',
+            inputs: [{ label: 'S', value: 's' }],
+        },
+    ],
+})
+
+calc.addField({
+    selector: 'price',
+    calculateFunction(values, data) {
+        return data.sizes.find(s => s.value === values.size)?.price ?? 0
     },
 })
 
-if (window.clearCart) cart.clear()
+calc.renderInNode(document.getElementById('form-place')!)
+calc.init()
 ```
 
-## Multiple carts on the same page
+The form is rendered into the given node. On each `change` event all fields are recomputed and written to matching `[data-calc="<selector>"]` elements inside `parentSelector`.
 
-Each `createCart()` call is an independent instance. When using multiple carts on a page, assign different `attr` values (and `storageKey` if separate storage is needed).
+### `CalculatorOptions`
 
-```ts
-const cartA = createCart({ element: '#cart-a', attr: 'cart-a', storageKey: 'cart-a' })
-const cartB = createCart({ element: '#cart-b', attr: 'cart-b', storageKey: 'cart-b' })
-```
+| option | type | default | description |
+|---|---|---|---|
+| `id` | `string` | — | unique identifier for the instance |
+| `parentSelector` | `string` | — | CSS selector of the container element |
+| `data` | `TData \| null` | `null` | arbitrary data object passed to `calculateFunction` |
+| `editableFields` | `FieldOptions[]` | `[]` | fields to register on construction |
+| `sectionsOptions` | `SectionOptions[]` | `[]` | sections to render in the form |
+| `prefix` | `string` | `'card'` | input name prefix (`{prefix}-{id}-{type}`) |
+| `stylePrefix` | `string` | `'calculator'` | BEM block name for generated HTML |
+| `dataAttributePrefix` | `string` | `'calc'` | prefix for `data-{prefix}="<selector>"` attributes |
 
-## Options
+### `FieldOptions`
 
 | option | type | default | description |
 |---|---|---|---|
-| `element` | `string \| Element` | `'#cart'` | cart render container |
-| `icon` | `string \| Element \| null` | `'#cart-icon'` | icon element with counter and total |
-| `currency` | `string` | `'zł'` | currency symbol |
-| `storageKey` | `string` | `'cart'` | `localStorage` key |
-| `attr` | `string` | `'cart'` | data-attribute prefix (`'cart'` → `data-cart-*`) |
-| `shouldAnimateIconSum` | `function(state, trigger)` | `() => true` | controls whether the icon sum animation plays |
-| `renderItem` | `function(id, product, count, currency)` | built-in template | returns HTML string for a single cart item |
-| `renderFooter` | `function(total, currency)` | built-in template | returns HTML string for the cart footer |
-| `onUpdate` | `function(state)` | `null` | called after every cart change |
-| `validateCart` | `function(products)` | `null` | called on init after loading from `localStorage`; receives and returns `CartProductEntry[]` — use to filter out stale items |
-| `classes` | `object` | Tailwind classes | partial override of CSS classes (unset keys fall back to defaults) |
-| `text` | `object` | see below | partial override of text strings |
-
-## Default CSS classes (`classes`)
-
-| key | description |
+| `selector` | `string` | — | matches `data-{dataAttributePrefix}="<selector>"` in the DOM |
+| `calculateFunction` | `(values, data) => unknown` | `() => null` | returns the new value; `null` is ignored |
+| `attribute` | `boolean` | `false` | write value as an attribute instead of `innerHTML` (reads `data-calc-attribute` from the node) |
+| `animated` | `boolean` | `false` | animate block on value change (requires Animate.css) |
+| `animatedNode` | `'parent' \| 'self' \| 'closest'` | `'parent'` | which node to animate |
+| `animatedNodeSelector` | `string` | — | selector for `closest()` when `animatedNode='closest'` |
+| `animation` | `string[]` | `['animate__faster', 'animate__pulse']` | Animate.css classes |
+| `duration` | `number` | `800` | number animation duration (ms) |
+| `dots` | `number` | `0` | decimal places for number animation |
+
+### `SectionOptions`
+
+| option | type | default | description |
+|---|---|---|---|
+| `type` | `string` | — | key used in `values` object and input `name` |
+| `title` | `string` | — | section heading |
+| `inputs` | `SectionInput[] \| (data) => SectionInput[]` | — | static list or factory function |
+| `className` | `string` | `''` | extra class on each `.{stylePrefix}__section-col` |
+| `checked` | `boolean` | `true` | pre-select first matching value |
+| `inputType` | `string` | `'radio'` | input type (`'radio'` or `'checkbox'`) |
+
+### Instance methods
+
+| method | description |
 |---|---|
-| `list` | `<ul>` product list |
-| `item` | `<li>` product row |
-| `itemInner` | inner wrapper (flex container) |
-| `itemContent` | block with title and description |
-| `itemTitle` | product title |
-| `itemDescription` | product description |
-| `itemImage` | product image |
-| `itemPriceBox` | price block |
-| `itemPriceHidden` | hidden `<span>` with price (for form submission) |
-| `controls` | +/− button group |
-| `countButton` | +/− buttons |
-| `countSpan` | `<span>` with item count |
-| `removeButton` | remove item button |
-| `footer` | cart total block |
-| `iconHidden` | class applied to hide the cart icon |
-| `iconSumVisible` | class applied to animate the icon sum |
-
-## Default text (`text`)
-
-| key | default | description |
-|---|---|---|
-| `sumLabel` | `'Total:'` | label before the total sum |
-| `orderInputName` | `'order-sum'` | `name` attribute of the hidden order sum input |
-| `addButton` | `'+'` | increment button text |
-| `removeButton` | `'−'` | decrement button text |
-| `clearButton` | `'✕'` | remove item button text |
+| `addField(options)` | register a new field |
+| `addSection(options)` | add a section to the form |
+| `init()` | attach DOM nodes to fields and wire the `change` listener |
+| `renderInNode(node)` | write generated HTML into `node` and store a reference |
+| `refresh()` | re-render HTML and re-init (use when inputs change dynamically) |
+| `getValues()` | return current `{ [type]: value }` map |
+| `getValue(key)` | return the last saved value for a field `selector` |
+| `saveValue(key, value)` | manually persist a value accessible via `getValue` |
 
-### `shouldAnimateIconSum(state, trigger)`
+---
 
-Called before the icon sum animation. Return `false` to suppress the animation. Not called on initial render.
+## initConfigurator
 
-- `state` — current cart state `{ products, productsCount, totalSum, count, isEmpty }`
-- `trigger` — the `<button>` element that triggered the change
+Higher-level helper for server-rendered pages. Reads the config from an inline `<script type="text/plain" data-configurator-options>` element, receives product data externally, and builds a `Calculator` with standard fields (`price`, `old-price`, `params`, per-section value/view fields, and mirrored attribute fields).
 
-```ts
-shouldAnimateIconSum: () => true
-```
+### HTML structure
 
-### `validateCart(products)`
+```html
+<div data-calc-id="product-a">
+    <!-- output fields -->
+    <span data-calc="price"></span>
+    <span data-calc="old-price"></span>
+    <span data-calc="params"></span>
+
+    <!-- Calculator renders the form here -->
+    <div data-calc-place="product-a"></div>
+
+    <!-- inline config (JS object syntax, functions allowed) -->
+    <script type="text/plain" data-configurator-options>
+    {
+        oldPricePercent: 20,
+        getPrice: function(values, item) {
+            return item.basePrice + (item.sizePrices[values.size] || 0)
+        },
+        sections: [
+            {
+                key: 'size',
+                title: 'Size',
+                path: '$.sizes[*]',
+                postfix: ' m'
+            }
+        ]
+    }
+    </script>
+</div>
+```
 
-Called once on initialization, after restoring the cart from `localStorage`. Receives and must return a `CartProductEntry[]` array (`CartProduct & { id: string }`). Use it to filter or update stale products. The result is saved back to `localStorage`.
+### JS initialization
 
 ```ts
-validateCart(products) {
-    const validIds = new Set(['sku-1', 'sku-3'])
-    return products.filter(p => validIds.has(p.id))
+import { initConfigurator } from 'ov-configurator'
+import type { DataSource } from 'ov-configurator'
+
+const data: DataSource = {
+    'product-a': {
+        basePrice: 45_000,
+        sizes: ['3x4', '3x6'],
+        sizePrices: { '3x4': 0, '3x6': 15_000 },
+    },
 }
+
+document.querySelectorAll<HTMLElement>('[data-calc-id]').forEach((el) => {
+    initConfigurator(data, el)
+})
 ```
 
-## Data attributes
+`initConfigurator` is also exported as `Configurator` (alias).
+
+### `ConfiguratorOptions` (inline config object)
+
+| key | type | description |
+|---|---|---|
+| `getPrice` | `(values, item, id) => number` | returns the current price |
+| `oldPricePercent` | `number` | discount % — old price = `price / ((100 - n) / 100)` |
+| `sections` | `ConfiguratorSection[]` | sections to build |
+| `fields` | `ConfiguratorField[]` | optional extra fields |
 
-By default the prefix is `data-cart-`. With `attr: 'mycart'` it becomes `data-mycart-`.
+### `ConfiguratorSection`
 
-**Buttons:**
-- `data-cart-action="add"` — increment item
-- `data-cart-action="remove"` — decrement item
-- `data-cart-action="clear"` — remove item from cart
+| key | type | description |
+|---|---|---|
+| `key` | `string` | field selector and value key in `values` |
+| `title` | `string` | section heading |
+| `path` | `string` | JSONPath / pipe expression to extract inputs from item data |
+| `postfix` | `string` | suffix appended to values in labels and `params` |
+| `inputs` | `SectionInput[]` | static inputs list (overrides `path`) |
+| `labelMapping` | `Record<string, string>` | map raw values to display labels |
+| `selectorDisplay` | `(selected, sectionData) => string` | custom display for the `*-view` field |
 
-**Item container:**
-- `data-cart-item="<id>"` — product identifier
+### Built-in fields registered by `initConfigurator`
 
-**Item parameters** (on descendants of `data-cart-item`):
-- `data-cart-item-title` — name (attribute value, or `"self"` to use `textContent`)
-- `data-cart-item-price` — price
-- `data-cart-item-image` — image URL
-- `data-cart-item-description` — description (multiline, separated by `\n`)
-- `data-cart-item-params` — additional parameters
+For each `section` with key `k` the following `data-calc` targets are populated:
 
-**Icon** (`icon`):
-- `data-cart-icon-count` — element displaying item count
-- `data-cart-icon-sum` — element displaying the total (must contain a `<span>`)
+| selector | content |
+|---|---|
+| `price` | result of `getPrice` |
+| `old-price` | price before discount |
+| `params` | space-joined `value + postfix` for every section |
+| `params-view` | newline-joined `title: value + postfix` |
+| `k` | selected raw value |
+| `k-view` | display label (via `labelMapping` / `selectorDisplay`) |
+| `price` *(attr)* | same value written as an HTML attribute |
+| `old-price` *(attr)* | same |
+| `k` *(attr)* | same |
 
-> All attributes use the prefix from the `attr` option. With `attr: 'mycart'` → `data-mycart-action`, `data-mycart-item`, `data-mycart-icon-count`, etc.
+### `queryByPath`
 
+Utility used internally by `initConfigurator` to traverse item data. Available as a named export for advanced custom fields.
 
-```js
-import { createCart } from '../../libs/cart/cart.js'
+```ts
+import { queryByPath } from 'ov-configurator'
 
-const cart = createCart({
-    element: '#my-cart',
-    currency: '₽',
-    storageKey: 'shop-cart',
-    attr: 'mycart',             // data-mycart-* вместо data-cart-*
-    classes: {
-        countButton: 'btn btn-sm',
-    },
-    onUpdate(state) {
-        // state: { products, productsCount, totalSum, count, isEmpty }
-        if (state.isEmpty) MicroModal.close('modal-cart')
-    },
-})
+// JSONPath
+queryByPath(data, '$.sizes[*]')
+
+// chained operations
+queryByPath(data, '$.variants > $first')
 
-if (window.clearCart) cart.clear()
+// fallback chain
+queryByPath(data, '$.primary || $.fallback')
+
+// save/get across operations
+queryByPath(data, '$save:key > $.next')
 ```
 
+Supported special operations: `$root`, `$first`, `$last`, `$save:<key>`, `$get:<key>`, any JSONPath expression.
+

package/dist/calculator-form.d.ts

@@ -0,0 +1,20 @@
+import { SectionOptions, SectionInput } from './types';
+export interface ResolvedSection {
+    options: SectionOptions;
+    inputs: SectionInput[];
+    checkedValue: string;
+}
+export interface CalculatorFormProps {
+    sections: SectionOptions[];
+    initialSections: ResolvedSection[];
+    initialValues: Record<string, string>;
+    stylePrefix: string;
+    dataAttributePrefix: string;
+    prefix: string;
+    id: string;
+    onValuesChange: (values: Record<string, string>) => void;
+}
+export declare const resolveInputs: (section: SectionOptions, values: Record<string, string>) => SectionInput[];
+export declare function resolveSections(sections: SectionOptions[], values: Record<string, string>): ResolvedSection[];
+export declare function renderCalculatorForm(container: HTMLElement, props: CalculatorFormProps): void;
+export declare function unmountCalculatorForm(container: HTMLElement): void;

package/dist/calculator.d.ts

@@ -13,14 +13,14 @@ interface GetNodeOptions {
 declare class Field<TData = unknown> {
     selector: string;
     options: Required<FieldOptions<TData>>;
-    node: HTMLElement | null;
-    animationId: number;
+    nodes: HTMLElement[];
+    animationIds: number[];
     prevValue: unknown;
     constructor(options: FieldOptions<TData>);
-    getNode(options: GetNodeOptions): HTMLElement | null;
+    getNode(options: GetNodeOptions): HTMLElement[];
     changeValue(value: unknown): void;
     animateBlock(value: unknown): void;
-    animateNumber(to: number): void;
+    animateNumber(to: number, node: HTMLElement, index: number): void;
 }
 export default class Calculator<TData = unknown> {
     static fieldTypes: {
@@ -43,18 +43,16 @@ export default class Calculator<TData = unknown> {
     };
     data: TData | null;
     fields: Field<TData>[];
-    private form;
     constructor(options: CalculatorOptions<TData>);
     addField(field: FieldOptions<TData>): void;
     addSection(section: SectionOptions): void;
-    init(): void;
+    private sortSections;
+    private buildInitialSections;
+    private processFields;
+    render(node: HTMLElement): void;
     getValues(): Record<string, string>;
-    changeHandler(form: HTMLFormElement): void;
     saveValue(key: string, value: unknown): void;
     getValue(key: string): unknown;
-    getHTML(): string;
-    getSectionHTML(options: SectionOptions): string;
-    renderInNode(node: HTMLElement): void;
     refresh(): void;
 }
 export {};

package/dist/configurator.d.ts

@@ -1,11 +1,11 @@
-import { DataSource } from './types';
-export declare function getOptions(dataSource: DataSource, element: HTMLElement): {
+import { DataSource, InitConfiguratorOptions } from './types';
+export declare function getOptions(dataSource: DataSource, element: HTMLElement, { calcIdAttribute, calcPlaceSelector, }: InitConfiguratorOptions): {
     data: unknown;
     uniqId: string;
     id: string;
     placeNode: HTMLElement;
 } | null;
 export declare function queryByPath(data: unknown, path: string, values?: Record<string, string>): unknown;
-export declare function initConfigurator(dataSource: DataSource, element: HTMLElement): void;
+export declare function initConfigurator(dataSource: DataSource, element: HTMLElement, initOptions: InitConfiguratorOptions): void;
 /** Alias for {@link initConfigurator} */
 export declare const Configurator: typeof initConfigurator;