`Hello ${name ?? "World"}`)} />

{ if (!dob) return "-"; let diff = dateDiff(new Date(), new Date(dob)); let years = diff / (365.25 * 24 * 60 * 60 * 1000); return `You're approximately ${years.toFixed(1)} years old...`; })} />

); ``` Let's break down the key parts: - **PageModel** - TypeScript interface defining the shape of your data - **TextField**, **DateField** - CxJS form widgets for text and date input - **LabelsTopLayout** - A layout that positions labels above form fields - **expr()** - Creates a computed expression that updates when dependencies change - **hasValue()** - Returns true if the bound value is defined - **createModel** - Creates a typed accessor model for store bindings When the user enters their name or date of birth, the bindings update the store and the UI re-renders automatically. This declarative data binding is a core concept in CxJS—you define what data each widget uses, and the framework handles synchronization. --- # Installation CxJS is distributed as npm packages and works with modern build tools like Vite and webpack. ## Packages The main packages you'll need: | Package | Description | | ---------- | ----------------------------------------------------- | | `cx` | Core framework with widgets, charts, and data-binding | | `cx-react` | React integration for rendering | Install both packages: ```bash npm install cx cx-react ``` ### Themes CxJS includes several [themes](/intro/themes). Install one to get started: ```bash npm install cx-theme-aquamarine ``` ## TypeScript Configuration CxJS is written in TypeScript and provides full type definitions. Configure your `tsconfig.json`: ```json { "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "cx", "moduleResolution": "bundler", "esModuleInterop": true } } ``` The key setting is `jsxImportSource: "cx"` which enables CxJS-specific JSX types and attributes like `visible`, `controller`, `layout`, and data-binding functions. ## Build Configuration ### Vite Vite is the recommended build tool for new projects. Create `vite.config.ts`: ```typescript import { defineConfig } from "vite"; export default defineConfig({ esbuild: { jsxImportSource: "cx", }, }); ``` ### webpack For webpack projects, configure TypeScript and JSX handling: ```javascript module.exports = { module: { rules: [ { test: /\.(ts|tsx)$/, loader: "ts-loader", }, ], }, }; ``` For large applications, consider using `swc-loader` instead of `ts-loader` for faster builds: ```javascript module.exports = { module: { rules: [ { test: /\.(ts|tsx)$/, loader: "swc-loader", options: { jsc: { transform: { react: { runtime: "automatic", importSource: "cx", }, }, }, }, }, ], }, }; ``` ## Entry Point In your main entry file, import the theme and start the application: ```tsx import { startAppLoop } from "cx/ui"; import { Store } from "cx/data"; import "cx-theme-aquamarine/dist/index.css"; const store = new Store(); startAppLoop( document.getElementById("app"), store,

Welcome to CxJS

); ``` --- # Tailwind CSS CxJS works well with Tailwind CSS. Use Tailwind's utility classes for layout and custom styling while leveraging CxJS widgets for complex UI components like grids, forms, and charts. ## Using with CxJS Apply Tailwind classes directly to CxJS components using the `class` attribute: ```tsx import { TextField, Button } from "cx/widgets"; import { createModel } from "cx/ui"; interface PageModel { name: string; } const m = createModel(); export default (

); ``` Tailwind is particularly useful for: - **Page layouts** - Use flexbox and grid utilities - **Spacing** - Apply margin and padding with utility classes - **Custom components** - Style wrappers and containers around CxJS widgets CxJS themes handle widget internals (inputs, dropdowns, grids), while Tailwind handles the surrounding layout and custom elements. ## Installation Install Tailwind CSS and its dependencies: ```bash npm install tailwindcss postcss autoprefixer npx tailwindcss init -p ``` ## Configuration Configure `tailwind.config.js` to scan your source files: ```javascript /** @type {import('tailwindcss').Config} */ export default { content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"], theme: { extend: {}, }, plugins: [], }; ``` Create a `tailwind.css` file with proper layer setup. Tailwind 4 uses CSS layers, and it's important to define a `cxjs` layer between `base` and `utilities` so CxJS styles have the correct specificity: ```css @layer theme, base, cxjs, utilities; @import "tailwindcss/theme.css" layer(theme); @import "tailwindcss/preflight.css" layer(base); @import "tailwindcss/utilities.css" layer(utilities); ``` Then import your CxJS theme styles into the `cxjs` layer in your main stylesheet: ```css @import "./tailwind.css"; @layer cxjs { @import "cx-theme-aquamarine/src/variables"; @import "cx-theme-aquamarine/src/index"; } ``` ## Build Setup ### Vite Vite has built-in PostCSS support. After running `npx tailwindcss init -p`, it creates a `postcss.config.js` file that Vite picks up automatically: ```javascript export default { plugins: { tailwindcss: {}, autoprefixer: {}, }, }; ``` ### webpack For webpack, install the PostCSS loader: ```bash npm install postcss-loader ``` Add PostCSS to your CSS/SCSS rule: ```javascript module.exports = { module: { rules: [ { test: /\.css$/, use: ["style-loader", "css-loader", "postcss-loader"], }, ], }, }; ``` ## Template For a complete example, see the [CxJS Tailwind CSS Template](https://github.com/codaxy/cxjs-tailwindcss-template) which includes a pre-configured webpack setup with layouts, dashboards, and sample pages. --- # JSX Syntax CxJS uses JSX to define user interfaces declaratively. If you're familiar with React, you'll find the syntax familiar — with some CxJS-specific extensions. ## Widgets vs HTML Elements CxJS follows a simple naming convention — widgets start with an uppercase letter (`Button`, `TextField`, `Grid`) while HTML elements start with a lowercase letter (`div`, `span`, `section`). You can freely mix them in the same component. CxJS widgets also support common attributes for controlling behavior and appearance. Use `visible` to conditionally render widgets, `class` or `className` for CSS classes, and `style` for inline styles: ```tsx import { createModel } from "cx/data"; import { Button, Switch, TextField } from "cx/widgets"; interface PageModel { name: string; showMessage: boolean; } const m = createModel(); export default (

Mixing Widgets and HTML

Greet

Visibility Control

Show message

This text is conditionally visible!

); ``` ## The `` Wrapper In earlier versions of CxJS, widget trees had to be wrapped in a `` element to instruct the Babel compiler to process them as CxJS configuration. With TypeScript and the new `jsxImportSource: "cx"` configuration, this wrapper is no longer required: ```tsx import { createModel } from "cx/data"; import { Button, TextField } from "cx/widgets"; interface PageModel { name: string; } const m = createModel(); export default (

Submit

); ``` The legacy `` syntax is still supported for backwards compatibility: ```tsx import { createModel } from "cx/data"; import { Button, TextField } from "cx/widgets"; interface PageModel { name: string; } const m = createModel(); export default (

Submit

); ``` ## Key Differences from React | Feature | React | CxJS | | ----------------- | ----------------- | ---------------------------- | | Class names | `className` only | `class` or `className` | | Two-way binding | Manual | Built-in via accessor chains | | State management | `useState`, Redux | Store with typed models | | Component wrapper | None | `` (optional) | --- # Typed Models CxJS uses **typed models** to provide type-safe access to data in the store. Instead of using string paths like `"user.firstName"`, you use accessor chains like `m.user.firstName` that are checked by TypeScript. ## Creating a Model Proxy Use `createModel()` to create a proxy object that mirrors your data structure. The proxy doesn't hold any data — it generates binding paths that connect widgets to the store. ```tsx import { createModel } from "cx/data"; import { TextField, Button } from "cx/widgets"; interface User { firstName: string; lastName: string; } interface PageModel { user: User; message: string; } const m = createModel(); export default (

Store content

 JSON.stringify(data, null, 2)} />
    

); ``` When you write `m.user.firstName`, CxJS creates a binding to the path `"user.firstName"` in the store. The TextField reads and writes to this path automatically. ## Why Typed Models? Typed models provide several benefits over string-based paths: - **Type safety** — TypeScript catches typos and invalid paths at compile time - **Autocomplete** — Your editor suggests available properties as you type - **Refactoring** — Rename a property and all usages update automatically - **Documentation** — Hover over a property to see its type ## Accessor Methods Accessor chains provide two useful methods for working with paths: | Method | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------- | | `toString()` | Returns the full string path represented by the accessor. Useful when you need to pass paths to APIs that expect strings. | | `nameOf()` | Returns only the last segment of the path (the property name). | ```tsx import { createModel } from "cx/data"; interface User { firstName: string; lastName: string; email: string; } interface PageModel { user: User; count: number; } const m = createModel(); export default (

Accessor	Result
m.user.firstName.toString()	"{m.user.firstName.toString()}"
m.user.email.toString()	"{m.user.email.toString()}"
m.count.toString()	"{m.count.toString()}"
m.user.lastName.nameOf()	"{m.user.lastName.nameOf()}"
m.count.nameOf()	"{m.count.nameOf()}"

); ``` ## Nested Structures Accessor chains work with deeply nested structures. Define your interfaces to match your data shape: ```tsx interface Address { street: string; city: string; country: string; } interface User { name: string; address: Address; } interface PageModel { user: User; } const m = createModel(); // Access nested properties m.user.address.city; // binds to "user.address.city" ``` The proxy automatically generates the correct path regardless of nesting depth. `createModel` can also be imported from `cx/ui`. `createAccessorModelProxy` is available as an alias for backward compatibility. --- # Store The **Store** is the central state container in CxJS. It holds all application data and notifies widgets when data changes, triggering automatic UI updates. ## Accessing the Store Every CxJS widget has access to the store through its instance. In event handlers, access it via the second parameter: ```tsx import { createModel, Store } from "cx/data"; import { Button } from "cx/widgets"; interface PageModel { count: number; } const m = createModel(); export default (

{ store.set(m.count, (store.get(m.count) || 0) - 1); }} > - { store.set(m.count, (store.get(m.count) || 0) + 1); }} > +

Store content

 JSON.stringify(data, null, 2)} />
    

); ``` The store is available in event handlers like `onClick`, `onChange`, and others. Use `store.get()` to read values and `store.set()` to write them. When using typed models with `createModel`, all store methods are fully typed. TypeScript catches type mismatches at compile time: ```tsx interface PageModel { count: number; name: string; } const m = createModel(); store.set(m.count, 5); // ✓ OK store.set(m.count, "five"); // ✗ Type error store.set(m.name, "John"); // ✓ OK ``` ## Store Methods The store provides several methods for working with data: | Method | Description | | ------------------------------ | ------------------------------------------------------------------ | | `get(accessor)` | Returns the value at the given path | | `set(accessor, value)` | Sets the value at the given path | | `init(accessor, value)` | Sets the value only if currently undefined | | `update(accessor, fn)` | Applies a function to the current value and stores the result | | `delete(accessor)` | Removes the value at the given path | | `toggle(accessor)` | Inverts a boolean value | | `copy(from, to)` | Copies a value from one path to another | | `move(from, to)` | Moves a value from one path to another | | `batch(fn)` | Batches multiple updates, notifying listeners only once at the end | | `silently(fn)` | Executes updates without triggering any notifications | | `notify(path?)` | Manually triggers change notifications | | `subscribe(fn)` | Registers a listener for changes; returns an unsubscribe function | | `ref(accessor, defaultValue?)` | Creates a reactive reference to store data | | `getData()` | Returns the entire store data object | ```tsx import { createModel } from "cx/data"; import { Button } from "cx/widgets"; interface PageModel { user: { name: string; age: number; }; } const m = createModel(); export default (

{ store.set(m.user.name, "John"); }} > set(m.user.name, "John") { store.update(m.user.age, (age) => (age || 0) + 1); }} > update(m.user.age, age => age + 1) { store.delete(m.user.name); }} > delete(m.user.name) { store.set(m.user, { name: "Jane", age: 25 }); }} > set(m.user, {...})

Store content

 JSON.stringify(data, null, 2)} />
    

); ``` ## Immutability The store treats all data as immutable. When you call `set()` or `update()`, CxJS creates new object references along the path to the changed value. This enables efficient change detection — widgets only re-render when their bound data actually changes. When updating objects or arrays, you must create new instances. Mutating existing objects directly will not trigger UI updates. ```tsx // Updating an object - spread the original and override properties store.update(m.user, (user) => ({ ...user, name: "John" })); // Adding to an array - create a new array store.update(m.items, (items) => [...items, newItem]); // Removing from an array - filter returns a new array store.update(m.items, (items) => items.filter((item) => item.id !== id)); ``` ## Immer Integration For complex nested updates, manually spreading objects can become tedious. The `cx-immer` package provides a `mutate` method that lets you write mutable-style code while CxJS handles immutability behind the scenes: ```tsx import { enableImmerMutate } from "cx-immer"; enableImmerMutate(); // Now you can use mutate with mutable syntax store.mutate(m.user, (user) => { user.name = "John"; user.scores.push(100); user.address.city = "New York"; }); ``` The `mutate` method uses [Immer](https://immerjs.github.io/immer/) to produce immutable updates from mutable code. This is especially useful when updating deeply nested structures or performing multiple changes at once. ## Creating a Store In most applications, CxJS creates the store automatically. If you need to create one manually (for testing or advanced scenarios), use the `Store` constructor: ```tsx import { Store } from "cx/data"; const store = new Store({ data: { count: 0, user: { name: "Guest" }, }, }); // Read and write data const count = store.get(m.count); store.set(m.count, count + 1); ``` --- # Data Binding Data binding connects your UI to the store, enabling automatic synchronization between widgets and application state. When store data changes, bound widgets update automatically. When users interact with widgets, their changes flow back to the store. ## Accessor Chains The primary way to bind data in CxJS is through **accessor chains** created with `createModel`. Pass an accessor directly to widget properties for two-way binding: ```tsx import { createModel } from "cx/data"; import { TextField, Slider } from "cx/widgets"; interface PageModel { name: string; volume: number; } const m = createModel(); export default (

Store content

 JSON.stringify(data, null, 2)} />
    

); ``` When you assign `m.name` to the `value` property, CxJS creates a two-way binding. The TextField displays the current value and writes changes back to the store. ### Default Values with bind Use `bind` to provide a default value when the store path is undefined: ```tsx import { createModel } from "cx/data"; import { bind } from "cx/ui"; import { TextField, NumberField } from "cx/widgets"; interface PageModel { username: string; count: number; } const m = createModel(); export default (

Username:

Count:

Store content

 JSON.stringify(data, null, 2)} />
    

); ``` When the widget initializes, if the store path is undefined, the default value is automatically written to the store. ## Computed Values with expr Use `expr` to compute values from one or more store paths. The function recalculates whenever any of its dependencies change: ```tsx import { createModel } from "cx/data"; import { TextField, NumberField } from "cx/widgets"; import { expr } from "cx/ui"; interface PageModel { firstName: string; lastName: string; price: number; quantity: number; } const m = createModel(); export default (

Full name: `${first || ""} ${last || ""}`.trim(), )} />

Total: { let total = (price || 0) * (qty || 0); return `$${total.toFixed(2)}`; })} />

); ``` The `expr` function takes accessor chains as arguments, followed by a compute function that receives the current values: ```tsx expr(m.firstName, m.lastName, (first, last) => `${first} ${last}`); ``` ## Computed Values with computable For complex calculations, use `computable` instead of `expr`. It works the same way but adds **memoization** — the result is cached and only recalculated when dependencies actually change: ```tsx import { computable } from "cx/data"; // Memoized computation - result cached until items or taxRate changes const total = computable(m.items, m.taxRate, (items, taxRate) => { const subtotal = items.reduce((sum, item) => sum + item.price * item.qty, 0); return subtotal * (1 + taxRate); }); ``` Use `computable` when the calculation is expensive or when the same value is used in multiple places. ## Formatting Values Use `format` to apply format strings to bound values: ```tsx import { format } from "cx/ui"; ``` Use `tpl` to combine multiple values into formatted text: ```tsx import { tpl } from "cx/ui"; // Positional placeholders

// With formatting

// With null fallback

``` See [Formatting](/docs/intro/formatting) for the complete format syntax reference. ## Expression Helpers CxJS provides type-safe helper functions for common boolean expressions. These return `Selector` and are useful for properties like `visible`, `disabled`, and `readOnly`: ```tsx import { truthy, isEmpty, greaterThan } from "cx/ui";

User has a name

No items available

User is an adult

``` | Helper | Description | | ------------------------------------- | ------------------------------------------------------ | | `truthy(accessor)` | Evaluates truthiness | | `falsy(accessor)` | Evaluates falsiness | | `isTrue(accessor)` | Strict `true` check | | `isFalse(accessor)` | Strict `false` check | | `hasValue(accessor)` | Checks for non-null/undefined | | `isEmpty(accessor)` | Checks for empty strings/arrays | | `isNonEmpty(accessor)` | Checks for non-empty strings/arrays | | `equal(accessor, value)` | Loose equality comparison | | `notEqual(accessor, value)` | Loose inequality comparison | | `strictEqual(accessor, value)` | Strict equality comparison | | `strictNotEqual(accessor, value)` | Strict inequality comparison | | `greaterThan(accessor, value)` | Numeric greater than | | `lessThan(accessor, value)` | Numeric less than | | `greaterThanOrEqual(accessor, value)` | Numeric greater than or equal | | `lessThanOrEqual(accessor, value)` | Numeric less than or equal | | `format(accessor, formatString)` | Formats value using [format strings](/core/formatting) | ## Legacy Binding Syntax The following binding methods are supported for backwards compatibility but are not recommended for new code. ### String-based bind Before typed models, bindings used string paths: ```tsx import { bind } from "cx/data"; // Legacy string-based binding // Modern accessor chain (preferred) ``` ### String-path templates The `tpl` function also supports string-path syntax: ```tsx import { tpl } from "cx/data"; // Legacy string-path template

// Modern typed accessor (preferred)

``` ### Attribute suffixes In older CxJS code, you may see attribute suffixes like `-bind`, `-expr`, and `-tpl`. These require Babel plugins and are not supported in the TypeScript-first approach: ```tsx // Legacy attribute suffixes (requires Babel plugin)

``` --- # Controllers Controllers contain the business logic for your views. They handle data initialization, event callbacks, computed values, and reactions to data changes. ## Creating a Controller Extend the `Controller` class and attach it to a widget using the `controller` property. The controller has access to the store and can define methods that widgets call: ```tsx import { createModel } from "cx/data"; import { Controller } from "cx/ui"; import { Button, TextField } from "cx/widgets"; interface PageModel { name: string; greeting: string; } const m = createModel(); class PageController extends Controller { onInit() { this.store.init(m.name, "World"); } greet() { let name = this.store.get(m.name); this.store.set(m.greeting, `Hello, ${name}!`); } clear() { this.store.delete(m.greeting); } } export default (

{ instance.getControllerByType(PageController).greet(); }} > Greet { instance.getControllerByType(PageController).clear(); }} > Clear

Store content

 JSON.stringify(data, null, 2)} />
    

); ``` The controller's methods are available to all widgets within its scope. In event handlers, access the controller through the second parameter. ## Inline Controllers For simple cases, define a controller inline using an object: ```tsx import { createModel } from "cx/data"; import { NumberField } from "cx/widgets"; import { tpl } from "cx/ui"; interface PageModel { count: number; double: number; } const m = createModel(); export default (

c * 2); }, }} class="flex items-center gap-4" >

); ``` The inline form supports lifecycle methods and controller features like `addTrigger` and `addComputable`. ## Lifecycle Methods Controllers have lifecycle methods that run at specific times: | Method | Description | | ------------- | -------------------------------------------------------------------------------- | | `onInit()` | Runs once when the controller is created. Use for data initialization and setup. | | `onExplore()` | Runs on every render cycle during the explore phase. | | `onDestroy()` | Runs when the controller is destroyed. Use for cleanup (timers, subscriptions). | ```tsx class PageController extends Controller { timer: number; onInit() { // Initialize data this.store.init(m.count, 0); // Start a timer this.timer = window.setInterval(() => { this.store.update(m.count, (c) => c + 1); }, 1000); } onDestroy() { // Clean up window.clearInterval(this.timer); } } ``` ## Typed Controller Access Use `getControllerByType` to get a typed reference to a controller. This provides full autocomplete and compile-time type checking: ```tsx import { createModel } from "cx/data"; import { Controller } from "cx/ui"; import { Button } from "cx/widgets"; interface PageModel { count: number; } const m = createModel(); class CounterController extends Controller { onInit() { this.store.init(m.count, 0); } increment(amount: number = 1) { this.store.update(m.count, (count) => count + amount); } decrement(amount: number = 1) { this.store.update(m.count, (count) => count - amount); } reset() { this.store.set(m.count, 0); } } export default (

{ ins.getControllerByType(CounterController).decrement(); }} > -1 { ins.getControllerByType(CounterController).increment(); }} > +1 { ins.getControllerByType(CounterController).increment(10); }} > +10 { ins.getControllerByType(CounterController).reset(); }} > Reset

); ``` The `getControllerByType` method searches up the widget tree and returns a typed controller instance. ## Triggers Triggers watch store paths and run callbacks when values change. Use `addTrigger` in `onInit`: ```tsx class PageController extends Controller { onInit() { this.addTrigger( "selection-changed", [m.selectedId], (selectedId) => { if (selectedId) { this.loadDetails(selectedId); } }, true, ); // true = run immediately } async loadDetails(id: string) { let data = await fetch(`/api/items/${id}`).then((r) => r.json()); this.store.set(m.details, data); } } ``` The trigger name allows you to remove it later with `removeTrigger("selection-changed")`. ## Computables Add computed values that automatically update when dependencies change: ```tsx class PageController extends Controller { onInit() { this.addComputable(m.fullName, [m.firstName, m.lastName], (first, last) => { return `${first || ""} ${last || ""}`.trim(); }); this.addComputable(m.total, [m.items], (items) => { return items?.reduce((sum, item) => sum + item.price, 0) || 0; }); } } ``` The first argument is the store path where the result is written. The computed value updates whenever any dependency changes. ## Accessing Parent Controllers Use `getParentControllerByType` to get a typed reference to a parent controller: ```tsx class ChildController extends Controller { onSave() { let parent = this.getParentControllerByType(PageController); parent.saveChild(this.getData()); } } ``` This provides full type safety and autocomplete. For dynamic method invocation by name, use `invokeParentMethod`: ```tsx this.invokeParentMethod("onSave", this.getData()); ``` --- # Formatting CxJS provides built-in support for formatting numbers, dates, and currencies. Formats can be applied to widgets via the `format` property or programmatically using `Format.value()`. ## Using Formats Widgets like `NumberField` and `DateField` accept a `format` property that controls how values are displayed: ```tsx import { createModel } from "cx/data"; import { Format } from "cx/util"; import { bind, expr, format, LabelsTopLayout } from "cx/ui"; import { NumberField, DateField } from "cx/widgets"; interface PageModel { price: number; quantity: number; date: Date; } const m = createModel(); export default (

Format	Result
currency;USD;2
n;0
d;yyMd
d;DDDDyyyyMMMMd	Format.value(date, "d;DDDDyyyyMMMMd"))} />

); ``` For formatting bound values in text, see the [Formatting Values](/docs/intro/data-binding#formatting-values) section in Data Binding. ## Culture-Sensitive Formatting Date, currency, and number formats depend on culture settings. Enable culture-sensitive formatting before use: ```tsx import { enableCultureSensitiveFormatting } from "cx/ui"; enableCultureSensitiveFormatting(); ``` This ensures formats respect locale-specific conventions for decimal separators, date order, currency symbols, and month/day names. ## Format Syntax Format strings use semicolons to separate parameters: ``` formatType;param1;param2 ``` Use a pipe `|` to specify text for null values: ``` n;2|N/A ``` Chain multiple formats with colons (applied left-to-right): ``` n;2:suffix; USD ``` ## Number Formats Number formats support min and max decimal places, plus optional flags: `n;minDecimals;maxDecimals;flags`. If only one decimal value is provided, it's used for both min and max. | Format | Description | Example Input | Example Output | | --------- | --------------------------- | ------------- | -------------- | | `n` | Number | `1234.5` | `1,234.5` | | `n;0` | No decimals | `1234.5` | `1,235` | | `n;2` | Exactly 2 decimals | `1234.5` | `1,234.50` | | `n;0;2` | 0-2 decimals | `1234.5` | `1,234.5` | | `n;0;0;+` | Plus sign for positive | `1234` | `+1,234` | | `n;0;0;a` | Accounting format | `-1234` | `(1,234)` | | `n;0;0;c` | Compact notation | `105000` | `105K` | | `p` | Percentage (×100) | `0.25` | `25%` | | `p;0;2` | Percentage, 0-2 decimals | `0.256` | `25.6%` | | `ps;0;2` | Percent sign only (no ×100) | `25.6` | `25.6%` | ## Currency Format The `currency` format supports an optional currency code, decimal places, and flags: `currency;code;minDecimals;maxDecimals;flags`. The currency code can be omitted to use the default currency. | Format | Description | Example Input | Example Output | | -------------------- | ---------------------------- | ------------- | -------------- | | `currency` | Default currency | `1234.5` | `$1,234.50` | | `currency;USD` | US Dollars | `1234.5` | `$1,234.50` | | `currency;EUR` | Euros | `1234.5` | `€1,234.50` | | `currency;USD;0` | USD, no decimals | `1234.5` | `$1,235` | | `currency;;2` | Default currency, 2 decimals | `1234.5` | `$1,234.50` | | `currency;USD;2;2;+` | Plus sign for positive | `1234.5` | `+$1,234.50` | | `currency;USD;2;2;a` | Accounting format | `-1234.5` | `($1,234.50)` | | `currency;;0;0;c` | Compact notation | `105000` | `$105K` | ## Format Flags These flags can be added to number and currency formats: | Flag | Description | | ---- | -------------------------------------------------- | | `+` | Display plus sign for positive numbers | | `a` | Accounting format (negative values in parentheses) | | `c` | Compact notation (e.g., 105K, 1M) | Flags can be combined, e.g., `+ac` for all three options. The default currency is determined by culture settings. ## String Formats String formats allow adding prefixes, suffixes, and wrapping values: | Format | Description | Example Input | Example Output | | ------------ | -------------------- | ------------- | -------------- | | `prefix;Hi ` | Add prefix | `"John"` | `"Hi John"` | | `suffix; cm` | Add suffix | `180` | `"180 cm"` | | `wrap;(;)` | Wrap with delimiters | `5` | `"(5)"` | These can be chained with other formats: ```tsx Format.value(5, "n;2:wrap;(;)"); // "(5.00)" Format.value(180, "n;0:suffix; cm"); // "180 cm" ``` ## Date Formats Date formats use pattern codes concatenated together. Separators are provided by the culture settings, not the pattern. | Format | Description | Example Output | | ----------------- | ------------------------- | ---------------------------- | | `d` | Default date | `2/1/2024` | | `d;yyMd` | Short year | `2/1/24` | | `d;yyMMdd` | 2-digit year, padded | `02/01/24` | | `d;yyyyMMdd` | Full date, padded | `02/01/2024` | | `d;yyyyMMMd` | Abbreviated month | `Feb 1, 2024` | | `d;yyyyMMMMdd` | Full month name | `February 01, 2024` | | `d;DDDyyyyMd` | Short weekday | `Thu, 2/1/2024` | | `d;DDDDyyyyMMMdd` | Full weekday, short month | `Thursday, Feb 01, 2024` | | `d;DDDDyyyyMMMMd` | Full weekday and month | `Thursday, February 1, 2024` | ### Date Pattern Characters Pattern codes are concatenated without separators. Four characters means full name, three is abbreviated, two is padded, one is numeric. | Character | Description | | --------- | ------------------- | | `yyyy` | 4-digit year | | `yy` | 2-digit year | | `MMMM` | Full month name | | `MMM` | Abbreviated month | | `MM` | 2-digit month | | `M` | Month number | | `dd` | 2-digit day | | `d` | Day number | | `DDDD` | Full weekday name | | `DDD` | Abbreviated weekday | ### Time Pattern Characters | Character | Description | | --------- | ------------------- | | `HH` | Hours (padded) | | `H` | Hours | | `mm` | Minutes (padded) | | `m` | Minutes | | `ss` | Seconds (padded) | | `s` | Seconds | | `a` / `A` | AM/PM indicator | | `N` | 24-hour format flag | Date and time patterns can be combined: `d;yyyyMMddHHmm` formats both date and time. Add `N` for 24-hour format: `d;yyyyMMddNHHmm`. For more details on culture-sensitive formatting, see [intl-io](https://github.com/codaxy/intl-io). ## Programmatic Formatting Use `Format.value()` to format values in code: ```tsx import { Format } from "cx/util"; Format.value(1234.5, "n;2"); // "1,234.50" Format.value(0.15, "p;0"); // "15%" Format.value(new Date(), "d;yyyyMMdd"); // "02/01/2024" ``` Use the `format` helper to format bound values: ```tsx import { format } from "cx/ui"; ; ``` Alternatively, use `expr` with `Format.value` for more control: ```tsx import { expr } from "cx/ui"; import { Format } from "cx/util"; Format.value(price, "currency;USD"))} />; ``` ## String Templates Use `StringTemplate.format` when you need to combine multiple values into a single formatted string: ```tsx import { StringTemplate } from "cx/util"; // Positional arguments StringTemplate.format( "{0} bought {1} items for {2:currency;USD}", "John", 5, 49.99, ); // "John bought 5 items for $49.99" // Named properties with an object StringTemplate.format("{name} - {date:d;yyyyMMdd}", { name: "Report", date: new Date(), }); // "Report - 02/01/2024" ``` Use `StringTemplate.compile` to create a reusable formatter function: ```tsx const formatter = StringTemplate.compile("{name}: {value:currency;USD}"); formatter({ name: "Total", value: 99.99 }); // "Total: $99.99" formatter({ name: "Tax", value: 7.5 }); // "Tax: $7.50" ``` ## Custom Formats Register custom formats using `Format.register`: ```tsx import { Format } from "cx/util"; // Simple format Format.register("brackets", (value) => `(${value})`); // Use it Format.value("test", "brackets"); // "(test)" ``` For formats with parameters, use `Format.registerFactory`: ```tsx Format.registerFactory("suffix", (format, suffix) => { return (value) => value + suffix; }); // Use it Format.value(100, "suffix; kg"); // "100 kg" ``` --- # HtmlElement The `HtmlElement` widget renders HTML elements with CxJS data binding support. The CxJS JSX runtime automatically converts all lowercase elements (like `div`, `span`, `p`) to `HtmlElement` instances with the corresponding `tag` property set. You can also use `HtmlElement` directly when you need to specify the tag dynamically or prefer explicit syntax. HTML elements can be freely mixed with CxJS widgets like `TextField`, allowing you to build forms and layouts that combine standard HTML with rich interactive components. ```tsx import { createModel } from "cx/data"; import { tpl } from "cx/ui"; import { HtmlElement, TextField } from "cx/widgets"; interface Model { name: string; } const m = createModel(); export const model = { name: "World", }; export default (

Heading

Paragraph with some text.

Using HtmlElement directly

---

); ``` ## Key Features - Lowercase JSX elements are automatically converted to `HtmlElement` by the JSX runtime - All standard HTML attributes and events work as expected - CxJS-specific attributes like `visible`, `layout`, `controller` are supported - Use `text` prop with `tpl()` for data-bound text content - Mix freely with CxJS widgets ## Configuration | Property | Type | Description | | -------- | ---- | ----------- | | `tag` | `string` | Name of the HTML element to render. Default is `div`. | | `text` / `innerText` | `string` | Inner text contents. | | `innerHtml` / `html` | `string` | HTML to be injected into the element. | | `tooltip` | `string \| object` | Tooltip configuration. | | `autoFocus` | `boolean` | Set to `true` to automatically focus the element when mounted. | | `baseClass` | `string` | Base CSS class to be applied to the element. | --- # PureContainer `PureContainer` groups multiple widgets together without adding any HTML markup to the DOM. This is useful when you need to control visibility or apply a layout to a group of elements. ```tsx import { createModel } from "cx/data"; import { LabelsTopLayout, PureContainer } from "cx/ui"; import { Checkbox, TextField } from "cx/widgets"; interface Model { showContactInfo: boolean; email: string; phone: string; } const m = createModel(); export const model = { showContactInfo: true, email: "", phone: "", }; export default (

Show contact information

Contact Information

We'll never share your contact information.

); ``` ## Common Use Cases - Toggle visibility of multiple widgets at once using `visible` - Apply a shared `layout` to a group of form fields - Base class for other CxJS components like `ValidationGroup`, `Repeater`, and `Route` ## Configuration | Property | Type | Description | | -------- | ---- | ----------- | | `visible` | `boolean` | Controls visibility of all children. | | `layout` | `string \| object` | Inner layout applied to children. | | `items` / `children` | `array` | List of child elements. | | `controller` | `object` | Controller instance for this container. | | `trimWhitespace` | `boolean` | Remove whitespace in text children. Default is `true`. | | `preserveWhitespace` / `ws` | `boolean` | Keep whitespace in text children. Default is `false`. | --- # ContentResolver `ContentResolver` dynamically resolves content at runtime based on data. Use it when the content to display is unknown at build time, depends on data values, or needs to be lazy loaded. ```tsx import { createModel } from "cx/data"; import { Checkbox, ContentResolver, DateField, LookupField, Switch, TextField, } from "cx/widgets"; interface Model { fieldType: string; text: string; date: string; checked: boolean; } const m = createModel(); const fieldTypes = [ { id: "textfield", text: "TextField" }, { id: "datefield", text: "DateField" }, { id: "checkbox", text: "Checkbox" }, { id: "switch", text: "Switch" }, ]; export default (

{ switch (type) { case "textfield": return ; case "datefield": return ; case "checkbox": return Checked; case "switch": return ; default: return null; } }} />

); ``` ## How It Works 1. The `params` prop binds to a value in the store 2. When `params` changes, `onResolve` is called with the new value 3. `onResolve` returns the widget configuration to render 4. For async loading, `onResolve` can return a Promise 5. Children are displayed as default content while loading ## Structured Params The `params` prop can be a structured object with multiple bindings: ```jsx { // resolve based on multiple parameters }} /> ``` When any of the bound values change, `onResolve` is called with the updated object. ## Configuration | Property | Type | Description | | -------- | ---- | ----------- | | `params` | `any` | Parameter binding. Can be a single value or structured object. Content is recreated when params change. | | `onResolve` | `function` | Callback taking `params` and returning widget configuration or a Promise. | | `mode` | `string` | How resolved content combines with children: `replace`, `prepend`, or `append`. Default is `replace`. | | `loading` | `boolean` | Writable binding set to `true` while a Promise is resolving. | | `children` | `any` | Default content displayed while `onResolve` Promise is loading. | --- # Functional Components Functional components provide a simple way to create reusable structures composed of CxJS widgets. Use `createFunctionalComponent` to define a CxJS functional component: ```tsx import { createModel } from "cx/data"; import type { AccessorChain } from "cx/ui"; import { bind, createFunctionalComponent } from "cx/ui"; import { Button } from "cx/widgets"; interface PageModel { count1: number; count2: number; } const m = createModel(); interface CounterProps { value: AccessorChain; label: string; } const Counter = createFunctionalComponent(({ value, label }: CounterProps) => (

{label}: store.update(value, (v) => (v || 0) + 1)} > + store.update(value, (v) => (v || 0) - 1)} > -

)); export default (

); ``` The `Counter` component can be reused with different props, each instance maintaining its own state through different store bindings. ## Example 2 Functional components are useful for creating reusable chart configurations: ```tsx import { createFunctionalComponent } from "cx/ui"; import { Svg } from "cx/svg"; import { Chart, Gridlines, LineGraph, NumericAxis } from "cx/charts"; interface LineChartProps { data: { x: number; y: number }[]; chartStyle?: string; lineStyle?: string; areaStyle?: string; } const LineChart = createFunctionalComponent( ({ data, chartStyle, lineStyle, areaStyle }: LineChartProps) => ( ), ); export default (

({ x, y: 75 - 50 * Math.random(), }))} /> ({ x, y: 75 - 50 * Math.random(), }))} /> ({ x, y: 75 - 50 * Math.random(), }))} />

); ``` The same `LineChart` component renders three different chart styles by passing different props. ## Conditional Logic Functional components can contain conditional logic: ```tsx import { createModel } from "cx/data"; import { createFunctionalComponent, LabelsLeftLayout, LabelsTopLayout, } from "cx/ui"; import { TextField } from "cx/widgets"; interface PageModel { form: { firstName: string; lastName: string; }; } const m = createModel(); interface MyFormProps { vertical?: boolean; } const MyForm = createFunctionalComponent(({ vertical }: MyFormProps) => { let layout = !vertical ? LabelsLeftLayout : { type: LabelsTopLayout, vertical: true }; return (

); }); export default (

); ``` The `vertical` prop changes the layout at render time. ## Reserved Properties These properties are handled by the framework and should not be used inside the function body: | Property | Type | Description | | ------------- | ------------ | ---------------------------------------------------------------------------------------- | | `visible` | `boolean` | If `false`, the component won't render and its controller won't initialize. Alias: `if`. | | `controller` | `Controller` | Controller that will be initialized with the component. | | `layout` | `Layout` | Inner layout applied to child elements. | | `outerLayout` | `Layout` | Outer layout that wraps the component. | | `putInto` | `string` | Content placeholder name for outer layouts. Alias: `contentFor`. | --- # Data View Components All application data in CxJS is stored inside a central [Store](/docs/intro/store). While convenient for global state, accessing deeply nested paths or working with collections can become cumbersome. Data View components wrap parts of the widget tree and provide a modified view of the Store data, making it easier to work with specific areas of the data model. ## Comparison | Component | Purpose | Use case | | -------------------------------------- | ------------------------------------------------- | ------------------------------------- | | [Repeater](./repeater) | Renders children for each record in a collection | Lists, tables, any repeated content | | [Rescope](./rescope) | Selects a common prefix for shorter binding paths | Deeply nested data structures | | [Sandbox](./sandbox) | Multiplexes data based on a dynamic key | Tabs, routes with isolated page data | | [PrivateStore](./private-store) | Creates an isolated store for a subtree | Reusable components with local state | | [DataProxy](./data-proxy) | Creates aliases with custom getter/setter logic | Computed values, data transformations | | [Route](./route) | Renders children when URL matches a pattern | Page routing, exposes `$route` params | ## How Data Views Work Each Data View component exposes the same interface as the Store to its children, but can introduce additional properties. For example, Repeater adds `$record` and `$index` for each item in the collection, Route exposes `$route` with matched URL parameters, while Sandbox might expose `$page` for route-specific data. These additional properties are only accessible within the scope of that Data View, allowing child widgets to bind to them just like any other Store data. ## How to Choose Use [Repeater](./repeater) when you need to render a list of items from an array. Use [Rescope](./rescope) when working with deeply nested data and you want shorter binding paths. Use [Sandbox](./sandbox) when you need to switch between different data contexts based on a key (e.g., tabs, route parameters). Use [PrivateStore](./private-store) (also known as Restate) when you need completely isolated state that doesn't affect the global store. Use [DataProxy](./data-proxy) when you need to transform data or create computed aliases with custom getter/setter logic. Use [Route](./route) when you need to conditionally render content based on URL and access matched route parameters. ## Store Mutation By default, Data View components write aliased data (like `$record`, `$page`) back to the parent store, all the way up to the global store. Regular data bindings propagate normally regardless of these settings. This default behavior is often fine and can improve performance by avoiding data copying. However, sometimes you want to prevent aliased fields from polluting your data. For example, when rendering a tree with nested Repeaters, fields like `$record` and `$index` would be written into your tree nodes. Two properties control this behavior: - `immutable` - Prevents aliased data from being written to the parent store. - `sealed` - Prevents child Data Views from writing aliased data to this Data View's store. --- # Repeater Repeater renders its children for each record in a collection. Use `recordAlias` to specify an accessor for accessing record data within the repeater. ## Example ```tsx import { createModel } from "cx/data"; import { Controller, expr } from "cx/ui"; import { Button, Checkbox, Repeater } from "cx/widgets"; interface Item { text: string; checked: boolean; } interface PageModel { items: Item[]; $record: Item; } const m = createModel(); class PageController extends Controller { onInit() { this.reset(); } reset() { this.store.set(m.items, [ { text: "Learn CxJS basics", checked: true }, { text: "Build a sample app", checked: false }, { text: "Master data binding", checked: false }, ]); } } export default (

{ store.delete(m.$record); }} />

Completed:{" "} items.filter((a) => a.checked).length, )} />{" "} of tasks

{ ins.getControllerByType(PageController).reset(); }} > Reset

); ``` ## Typed Model Add `$record` to your model interface to get type-safe access to record data: ```tsx interface PageModel { items: Item[]; $record: Item; } const m = createModel(); ``` Then use `recordAlias={m.$record}` to bind the record accessor: ```tsx ``` ## Accessing the Record Store Event handlers like `onClick` receive an instance object as the second argument. This instance contains a `store` that provides access to the record-specific data view. Use this to manipulate individual records: ```tsx { store.delete(m.$record); }} /> ``` The `store.delete(m.$record)` call removes the current record from the parent array. ## Sorting and Filtering Use `sortField` and `sortDirection` for sorting. For filtering, use `filterParams` with `onCreateFilter`: ```tsx import { createModel } from "cx/data"; import { Controller, expr } from "cx/ui"; import { getSearchQueryPredicate } from "cx/util"; import { HighlightedSearchText, Repeater, TextField } from "cx/widgets"; interface Product { name: string; price: number; } interface PageModel { products: Product[]; $record: Product; search: string; } const m = createModel(); class PageController extends Controller { onInit() { this.store.init(m.products, [ { name: "Banana", price: 1.2 }, { name: "Apple", price: 0.9 }, { name: "Orange", price: 1.5 }, { name: "Mango", price: 2.3 }, { name: "Pineapple", price: 3.5 }, { name: "Strawberry", price: 4.0 }, { name: "Grapes", price: 2.8 }, { name: "Watermelon", price: 5.0 }, ]); } } export default (

{ let predicate = getSearchQueryPredicate(params.search); return (item: Product) => predicate(item.name); }} >

` - $${price}`)} />

); ``` ## Nested Repeaters For nested repeaters, define separate record aliases in your model: ```tsx import { createModel } from "cx/data"; import { Controller } from "cx/ui"; import { Repeater } from "cx/widgets"; interface Transaction { id: number; description: string; amount: number; } interface Account { name: string; transactions: Transaction[]; } interface PageModel { accounts: Account[]; $account: Account; $transaction: Transaction; } const m = createModel(); class PageController extends Controller { onInit() { this.store.init(m.accounts, [ { name: "Checking", transactions: [ { id: 1, description: "Groceries", amount: -85.5 }, { id: 2, description: "Salary", amount: 3500 }, { id: 3, description: "Electric bill", amount: -120 }, ], }, { name: "Savings", transactions: [ { id: 4, description: "Transfer in", amount: 500 }, { id: 5, description: "Interest", amount: 12.5 }, ], }, ]); } } export default (

); ``` ## Configuration | Property | Type | Description | | ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `records` | `Prop` | An array of records to be displayed | | `recordAlias` | `AccessorChain` | Alias used to expose record data. Defaults to `$record`. | | `indexAlias` | `AccessorChain` | Alias used to expose record index. Defaults to `$index`. | | `sortField` | `StringProp` | A binding used to store the name of the field used for sorting the collection. Available only if `sorters` are not used. | | `sortDirection` | `Prop<"ASC" \| "DESC">` | A binding used to store the sort direction. Available only if `sorters` are not used. Possible values are `"ASC"` and `"DESC"`. Defaults to `"ASC"`. | | `sorters` | `SortersProp` | A binding used to store the sorting order list. This should be an array of objects with `field` and `direction` properties (equivalent to `sortField` and `sortDirection`). | | `sortOptions` | `object` | Options for data sorting. See [Intl.Collator options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator) for more info. | | `filterParams` | `StructuredProp` | Parameters that affect filtering | | `onCreateFilter` | `function` | Callback to create a filter function for given filter params | | `onTrackMappedRecords` | `function` | Callback function to track and retrieve displayed records. Accepts new records as a first argument. If `onCreateFilter` is defined, filtered records can be retrieved using this callback. | | `keyField` | `string` | Field used to get the unique identifier. Improves performance on sort operations. | | `cached` | `boolean` | Set to `true` to enable caching for improved performance on large datasets | --- # Sandbox Sandbox acts as a data multiplexer. It selects a value from a `storage` object based on a dynamic `key` and exposes it through a `recordAlias`. When the key changes, Sandbox automatically switches to the corresponding data in storage. ## Example ```tsx import { createModel } from "cx/data"; import { LabelsTopLayout, tpl } from "cx/ui"; import { Radio, Sandbox, TextField } from "cx/widgets"; interface Contestant { firstName: string; lastName: string; } interface PageModel { place: string; results: Record; $contestant: Contestant; } const m = createModel(); export default (

1st Place 2nd Place 3rd Place

Results

); ``` ## Typed Model Add `$contestant` (or your chosen alias) to your model interface: ```tsx interface PageModel { place: string; results: Record; $contestant: Contestant; } const m = createModel(); ``` Then use `recordAlias={m.$contestant}` to bind the record accessor: ```tsx ``` ## Sandboxed Routes Sandbox is commonly used in single-page applications to isolate data belonging to different pages identified by URL parameters. See [Routing](/docs/core/routing) for more info. ```tsx ``` ## Configuration | Property | Type | Description | | ----------------- | --------- | -------------------------------------------------------------------------- | | `storage` | `Prop` | Storage binding. All data will be stored inside. | | `key`/`accessKey` | `Prop` | Key value used to access the data from the `storage`. | | `recordAlias` | `string` | Alias used to expose local data. Defaults to `$page`. | | `immutable` | `boolean` | Indicate that the data in the parent store should not be mutated. | | `sealed` | `boolean` | Indicate that the data in the store should not be mutated by child stores. | --- # PrivateStore PrivateStore (also known as Restate) creates a separate, isolated data store for a part of the widget tree. This enables some parts of the application to behave independently from the rest. ## Example ```tsx import { createModel } from "cx/data"; import { PrivateStore, Slider } from "cx/widgets"; interface PageModel { value: number; } const m = createModel(); export default (

Global Store

Private Store A

Private Store B

); ``` Each PrivateStore has its own isolated data. Sliders within the same store share the same value, but don't affect sliders in other stores. ## Lifespan Private stores have the lifespan of the PrivateStore component. When a PrivateStore is destroyed, its data is lost. If you navigate away and come back, only sliders in the global store will retain their values. ## Sharing Data Data shared between the parent store and the private store must be explicitly defined with the `data` property. Bindings create two-way data flow, while expressions and computables are read-only. ```tsx import { createModel } from "cx/data"; import { LabelsTopLayout } from "cx/ui"; import { PrivateStore, Slider } from "cx/widgets"; interface PageModel { slider: number; } const m = createModel(); interface PrivateModel { globalValue: number; localValue: number; } const mPrivate = createModel(); export default (

Global Store

Private Store A

Private Store B

); ``` ## Performance PrivateStore can improve performance through: - **Detached rendering** - Use `detached` to render the subtree in its own render loop. Changes inside won't trigger the main render loop and vice versa. - **Deferred rendering** - Use `deferredUntilIdle` to defer rendering until the browser is idle, useful for heavy content. Heavy charts or tables can be wrapped in a detached PrivateStore to prevent them from re-rendering on every store change. Detached mode may break some advanced features that depend on shared context, such as form validation. ## Configuration | Property | Type | Description | | ------------------- | --------- | ------------------------------------------------------------------------------------ | | `data` | `object` | Object mapping internal binding names to values from the parent store. | | `detached` | `boolean` | Render in a separate render loop for performance. Breaks context-dependent features. | | `deferredUntilIdle` | `boolean` | Defer rendering until the browser is idle. | | `idleTimeout` | `number` | Time limit in milliseconds the browser can defer rendering. | | `immediate` | `boolean` | Disable batching of updates. | --- # DataProxy DataProxy creates aliases for store bindings with optional custom getter/setter logic. The simplest use case is creating a two-way alias for a binding. ## Example ```tsx import { createModel } from "cx/data"; import { DataProxy, LabelsTopLayout } from "cx/ui"; import { Slider } from "cx/widgets"; interface PageModel { level: number; } const m = createModel(); interface ProxyModel { $level: number; } const mProxy = createModel(); export default (

Original

Alias

); ``` Moving either slider affects the other since they both point to the same underlying value. ## Custom Transformations Use the `data` property to define multiple aliases with custom getter and setter logic: - `expr` - Defines getter logic using a computable or expression - `set` - Defines setter logic (receives value and instance with store) Omitting the `set` property makes the alias read-only. ```tsx import { createModel } from "cx/data"; import { computable, DataProxy, Instance, LabelsTopLayout } from "cx/ui"; import { Slider } from "cx/widgets"; interface PageModel { level: number; } const m = createModel(); interface ProxyModel { $inverted: number; $readOnly: number; } const mProxy = createModel(); export default (

100 - v), set: (value: number, { store }: Instance) => { store.set(m.level, 100 - value); }, }, $readOnly: { expr: computable(m.level, (v) => v), }, }} >

); ``` When using two-way mapping, both getter and setter must be reversible without data loss. For any alias value, you should be able to recover all store values used to calculate it. Prefix alias names with `$` to avoid name shadowing, which can cause infinite get-set loops and stack overflow errors. ## Configuration | Property | Type | Description | | ----------- | --------- | ------------------------------------------------------------------------------- | | `value` | `Prop` | Binding, computable, expression, or object with `expr` and/or `set` properties. | | `alias` | `string` | Alias name for the computed value. | | `data` | `object` | Object mapping alias names to `{ expr, set }` configurations. | | `immutable` | `boolean` | Prevent mutations to the parent store. | --- # Selections Selections enable users to select one or more items from widgets like Grid, List, and charts. CxJS provides three selection models, each suited for different use cases. ## Comparison | Model | Storage | Best for | | ------------------------------------------------------- | ---------------------------------- | ------------------------------- | | [KeySelection](./key-selection) | Key value(s) in separate variable | Selection survives data updates | | [SimpleSelection](./simple-selection) | Entire object in separate variable | Simple single select | | [PropertySelection](./property-selection) | Boolean flag on each record | Checkbox lists, toggles | ## How to Choose Use [KeySelection](./key-selection) when selection needs to survive data refreshes. Keys remain stable while object references change after updates. Use [SimpleSelection](./simple-selection) for simple single-select scenarios where you need immediate access to the selected object. Use [PropertySelection](./property-selection) for checkbox-based UIs where each record tracks its own selection state. --- # KeySelection KeySelection stores selected keys separately from the data. Only the key values are stored, not the entire objects. This is similar to how select controls work and is ideal when you need selection to survive data changes. ## When to Use - Selection must survive after records are updated (keys remain stable while object references change) - Grid or List with selection synced to other components (e.g., master-detail views) - When you need to persist selection independently of the data ## Example ```tsx import { createModel } from "cx/data"; import { KeySelection, Controller } from "cx/ui"; import { Grid } from "cx/widgets"; interface Item { id: number; name: string; } interface PageModel { items: Item[]; selection: number[]; } const m = createModel(); class PageController extends Controller { onInit() { this.store.init(m.items, [ { id: 1, name: "Apple" }, { id: 2, name: "Banana" }, { id: 3, name: "Cherry" }, { id: 4, name: "Date" }, ]); this.store.init(m.selection, [2]); } } export default (

Store content

 JSON.stringify({ selection: data.selection }, null, 2)}
      />
    

); ``` ## Configuration | Property | Type | Default | Description | | -------------------- | ----------- | --------- | -------------------------------------------------------- | | `keyField` | `string` | — | Field on each record used as the unique key | | `bind` / `selection` | `Prop` | — | Binding for the selected key(s) | | `storage` | `string` | `"array"` | Storage format: `array` or `hash` | | `multiple` | `boolean` | `false` | Enable multiple selection | | `toggle` | `boolean` | `false` | Enable toggle mode (clicking selected item deselects it) | --- # Routing CxJS includes built-in routing for single-page applications. Define routes that render content based on the URL, navigate programmatically, and handle deep linking. Both hash-based (`#/path`) and `pushState` based (`/path`) navigation modes are supported. ## Key Components | Component | Description | | ------------------------------------- | -------------------------------------------------------------------------- | | [Route](/core/route) | Conditionally renders content when the URL matches a pattern | | [RedirectRoute](/core/redirect-route) | Automatically redirects when the URL matches | | [Url](/core/url) | Helper class for URL path manipulation and resolution | | [History](/core/history) | Programmatic navigation with `pushState`, confirmations, and subscriptions | ## Basic Setup ```tsx import { Route } from "cx/widgets"; import { History } from "cx/ui"; // Connect History to store History.connect(store, "url"); // Define routes ``` The `~/` prefix resolves to your application's base path, making routes portable across different deployment paths. --- # Route Route is a container that renders its children only when the current URL matches the specified pattern. ## Example ```tsx import { createModel } from "cx/data"; import { Controller } from "cx/ui"; import { Route, Button } from "cx/widgets"; interface PageModel { url: string; } const m = createModel(); class PageController extends Controller { onInit() { this.store.init(m.url, "~/home"); } } export default (

store.set(m.url, "~/home")}> Home store.set(m.url, "~/about")}> About store.set(m.url, "~/contact")}> Contact

Home

Welcome to the home page.

About

Learn more about us.

Contact

Get in touch with us.

Current URL:

); ``` ## Route Patterns Routes support parameters, splats, and optional parts using [route-parser](https://github.com/rcs/route-parser#what-can-i-use-in-my-routes) syntax: | Pattern | Description | Example Match | | --------------- | -------------------- | -------------------------------- | | `~/users` | Exact match | `/users` | | `~/users/:id` | Named parameter | `/users/123` → `id: "123"` | | `~/files/*path` | Splat (rest of path) | `/files/a/b/c` → `path: "a/b/c"` | | `~/users(/:id)` | Optional parameter | `/users` or `/users/123` | ## Prefix Matching Use `prefix` to match routes that start with a pattern: ```tsx {/* Matches ~/admin, ~/admin/users, ~/admin/settings, etc. */} ``` ## Nested Routes Use `+/` to define routes relative to the parent: ```tsx ``` ## Configuration | Property | Type | Description | | ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `route` / `path` | `string` | Target route, e.g. `~/user/:userId`. Use `~/` to denote the application root path and `+/` in nested routes to append to the parent route. | | `url` | `Prop` | Url binding. Bind this to the global `url` variable. | | `prefix` | `boolean` | Match route even if given `route` is only a prefix of the current `url`. Used when a route contains nested subroutes. | | `params` | `Prop