`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

); ``` --- # Themes CxJS provides pre-built themes that style all framework widgets consistently. See them in action at the [CxJS Gallery](https://gallery.cxjs.io/). ## Available Themes | Theme | Package | Description | | ---------- | --------------------- | ------------------------------------------- | | Aquamarine | `cx-theme-aquamarine` | Clean, modern theme with aquamarine accents | | Material | `cx-theme-material` | Google Material Design inspired theme | | Frost | `cx-theme-frost` | Light theme with subtle blue tones | | Dark | `cx-theme-dark` | Dark theme for low-light environments | | Space Blue | `cx-theme-space-blue` | Dark blue theme | ## Installation Install the theme package of your choice: ```bash npm install cx-theme-aquamarine ``` ## Usage Import the theme CSS in your entry file: ```tsx import "cx-theme-aquamarine/dist/index.css"; ``` ## Customization Instead of importing the precompiled CSS file, you can import the theme's SCSS source files directly. This is a common approach that allows you to customize theme variables. Create an `index.scss` file: ```scss // Pre-set theme variables $cx-theme-primary-color: #3b82f6; // Import theme variables @import "cx-theme-aquamarine/src/variables"; // Advanced customizations go here // Import theme styles @import "cx-theme-aquamarine/src/index"; // Add classes that override default theme behavior ``` Then import it in your entry file: ```tsx import "./index.scss"; ``` Check the theme's repository for available SCSS variables. --- # 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. --- # Application Templates The fastest way to start a new CxJS project is with a template. ## Project Templates | Template | Description | | --------------------------------------------------------------------------------- | ------------------------------------------------ | | [CxJS Vite Template](https://github.com/codaxy/cxjs-vite-template) | Recommended for new projects | | [CxJS Tailwind CSS Template](https://github.com/codaxy/cxjs-tailwindcss-template) | webpack with layout, dashboard, and page samples | ## CxJS CLI The CxJS CLI can generate new projects from the command line: ```bash npx cx-cli create my-app ``` This creates a new project with all necessary configuration and dependencies. --- # AI CxJS documentation is optimized for AI coding assistants and large language models (LLMs). We provide machine-readable documentation files that help AI tools understand the framework and generate accurate CxJS code. ## LLMs.txt Files Following the [llms.txt](https://llmstxt.org/) standard, CxJS provides documentation in formats optimized for AI consumption: | File | Description | Use Case | | ---- | ----------- | -------- | | [llms.txt](/llms.txt) | Index with links to all documentation pages | Quick overview and navigation | | [llms-small.txt](/llms-small.txt) | Essential documentation (~100KB) | Fast context loading, basic usage | | [llms-full.txt](/llms-full.txt) | Complete documentation (~500KB) | Comprehensive reference, advanced features | ### Usage with AI Assistants When working with AI coding assistants like Claude, ChatGPT, or Cursor, you can: 1. **Reference the documentation URL** - Point the AI to `https://cxjs.io/llms-full.txt` for complete framework knowledge 2. **Include in system prompts** - Add the llms-small.txt content to your AI assistant's context for CxJS-aware code generation 3. **Use with RAG systems** - Index the documentation for retrieval-augmented generation ## CxJS Skill for Coding Agents A dedicated CxJS skill for AI coding agents is coming soon. This skill will provide: - Deep understanding of CxJS patterns and best practices - Accurate code generation for widgets, forms, grids, and charts - TypeScript-first approach with proper type inference - Integration with popular AI coding tools Stay tuned for updates. --- # 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`. | --- # Custom Components CxJS includes many built-in components, but you can create custom ones when needed. Custom components extend base classes like `Widget`, `HtmlElement`, `Field`, or `PureContainer`. ## Example This example creates a `Square` component with bindable color properties. Click the square to set a random color. **Square.tsx** - The widget class (uses React JSX): **Usage** - CxJS application code: ```tsx import { createModel } from "cx/data"; import { bind, LabelsLeftLayout } from "cx/ui"; import { Slider } from "cx/widgets"; import { Square } from "./Square"; interface PageModel { red: number; green: number; blue: number; } const m = createModel(); export default (

); ``` ## React JSX Pragma Widget files must use the React JSX pragma because the `render` method returns React elements: ```tsx /** @jsxImportSource react */ ``` ## Config Interface Define a config interface for your component's properties. Use prop types like `StringProp`, `NumberProp`, `BooleanProp` for bindable properties: ```tsx interface SquareConfig extends WidgetConfig { red?: NumberProp; green?: NumberProp; blue?: NumberProp; } ``` ## Widget Class Extend `Widget` (or another base class) with your config type. Use `declare` for properties to avoid overwriting config values: ```tsx class Square extends Widget { declare red: number; declare green: number; declare blue: number; } ``` ## Widget Methods ### declareData Register bindable properties. Properties declared here can use data binding: ```tsx declareData(...args) { super.declareData(...args, { red: undefined, green: undefined, blue: undefined, }); } ``` Use `{ structured: true }` for object properties with bindable sub-properties. ### render Returns React elements for the component's visual representation: ```tsx render(context: RenderingContext, instance: Instance, key: string) { const { data } = instance; return (

); } ``` Parameters: - `context` - Passes information between parent and child widgets - `instance` - Contains `data`, `store`, and instance-specific properties - `key` - Unique identifier for React reconciliation ### init Called once when the widget class is initialized, before any rendering. ### initInstance Called for each widget instance. Use this to set up instance-specific data: ```tsx initInstance(context: RenderingContext, instance: Instance) { instance.customData = {}; super.initInstance(context, instance); } ``` ### initState Sets the initial internal state for stateful components. ### explore Evaluates data-bound attributes and explores children. Called before `prepare`: ```tsx explore(context: RenderingContext, instance: Instance) { super.explore(context, instance); // Access instance.data here } ``` ### prepare Additional preparation after `explore`, before `render`. Use to get information from context. ### cleanup Called after rendering to perform cleanup work. ## Prototype Defaults Set default property values on the prototype: ```tsx Square.prototype.red = 0; Square.prototype.green = 0; Square.prototype.blue = 0; ``` ## Base Classes | Base Class | Use Case | | --------------- | ---------------------------------------------------- | | `Widget` | Basic widgets | | `HtmlElement` | Widgets rendering HTML elements with styling support | | `Field` | Form input widgets with validation | | `PureContainer` | Containers without HTML wrapper | | `Container` | Containers with HTML wrapper | --- # Changelog ## cx@26.2.1 **Fixes** - Relaxed `LookupFieldConfig` type constraints to improve subclass extensibility - Changed generic type defaults from `unknown` to `any` for better compatibility with existing code - Added `LookupFieldUniversalConfig` export for extending LookupField in subclasses ## cx@25.1.0 **Features** - Date only (2025-01-01) strings are now parsed as local time, instead of UTC. - `encodeDate` function can be used to format date objects as date only strings, i.e. 2025-01-01. This function can be set as `encoding` for the `DateField`, `MonthField`, `Calendar`, and `MonthPicker` components. - `MonthField` and `MonthPicker` now include a flag `inclusiveTo` which allow month ranges to end with the last day of the month, instead of the first day of the next month. --- ## cx@24.6.2 **Features** - Add SnapPointFinder convertX and convertY functions --- ## cx@24.6.1 **Fixes** - Fix on validate arguments for multiple lookups --- ## cx@24.5.2 **Features** - New formats: `capitalize` and `titleCase`. --- ## cx@24.5.1 **Features** - `Window.pad` option. See [Breaking changes](/intro/breaking-changes). --- ## cx@24.4.9 **Features** - Swimlane component --- ## cx@24.4.8 **Features** - Set caption style and class even when caption is defined as items/children. **Fixes** - Fix grid grouping text property description. --- ## cx@24.4.7 **Features** - Improve selection of dropzone based on distance to the center. - Allow grid column caption to be specified as false. - Support dynamic chart height based on the number of categories. **Fixes** - Avoid rendering shape prop. - Fix grid rendering when column caption is defined via items only. --- ## cx@24.4.6 **Features** - Allow grid column caption to be specified as false. - Support dynamic chart height based on the number of categories. **Fixes** - Fix grid rendering when column caption is defined via items only. --- ## cx@24.4.5 **Features** - Introduce new feature for grid: merging cells. --- ## cx@24.4.4 **Features** - Introducing the new `zeropad` format. --- ## cx@24.4.3 **Fixes** - Corrected distortion in pie-chart shapes caused by mathematical errors. - Resolved grid resize issues by implementing element existence checks prior to resizing. --- ## cx@24.4.2 **Fixes** - Addressed a bug where RangeMarkers were not functioning correctly when used alongside SWC. --- ## cx@24.4.1 **Features** - Enhanced dropInsertionIndex positioning within the grid - Introduced CultureScope widget - Introduced RangeMarker widget - Added functionality for adjusting pie chart gaps **Fixes** - Types for ColumnGraph and LineGraph --- ## cx@24.3.3 **Features** - Swimlanes widget - Allow aggregates via aggregateAlias inside Grid **Fixes** - Fix getCursorPos properly resolves position within iframes in Firefox - Fix drag and drop within iframes --- ## cx@24.3.0 **Features** - Support specifying `borderRadius` on `PieChart` slices. --- ## cx@24.2.0 **Features** - Documentation updates and additions - Currency formatting features - Field configurations and enhancements - Localization examples and updates - Row reordering, drag-and-drop for CodeSnippet - Configuration props for data views - Copy button tooltip and display enhancements --- ## cx@24.1.3 **Features** - Support tooltips and additional configuration on field icons --- ## cx@24.1.0 **Features** - Allow using the `fmt` function inside expressions and string templates. For example, this template works: `{[fmt({amount}, "currency;${currency};0;2")]}` - Add number formatting flags, i.e. `n;0;2;+ca;` - `+` to show sign for positive number, `c` for compact number formatting, `a` for accounting mode (brackets for negative numbers) - Add `Culture.setNumberCulture` and `Culture.setDateTimeCulture` methods which enable using different cultures for numbers and date formatting. --- ## cx@23.4.1 **Features** - Allow Validator to render children, i.e. ValidationError --- ## cx@23.4.0 **Fixes** - Expose SimpleSelection --- ## cx@23.3.1 **Fixes** - Allow up to eight typed parameters in triggers and computables - Allow entering negative decimal numbers in NumberFields with reactOn="change" --- ## cx@23.3.0 **Fixes** - Fix `quoteStr` handling of special characters (used for multiline string templates) --- ## cx@23.2.1 **Features** - Allow Grid to render children, i.e. loading mask **Fixes** - Make AccessorChain<T> assignable to AccessorChain<any> --- ## cx@23.2.0 **Features** - Dart Sass compatibility (see [Breaking Changes](/intro/breaking-changes)) - Dropping IE support --- ## cx@22.11.3 **Fixes** - Typing for `Dropdown.relatedElement` - Typing for `List.keyField` --- ## cx@22.11.2 **Features** - Add the `constrain` property to limit NumberField inputs **Fixes** - Typing for Url.setBaseFromScript - Typing for the `bind` function - Typing for the LineGraph - Propagate colSpan to grid column footers --- ## cx@22.11.1 **Features** - Add the `dayData` property for calendar day styling **Fixes** - Add typing for LookupField bindings - Improve typing for openContextMenu --- ## cx@22.10.3 **Features** - Add LookupField onCreateVisibleOptionsFilter callback docs and example --- ## cx@22.10.2 **Fixes** - Properly sort by the second column if the values in first column are null --- ## cx@22.10.1 **Features** - Add the onTrackMappedRecords callback for easier manipulation of sorted and filtered grid data - Document onGetGrouping **Fixes** - Recalculate the widget on store change to correctly propagate the new store to widget's children --- ## cx@22.10.0 **Fixes** - Prevent late autofocus for touch devices --- ## cx@22.9.0 **Fixes** - Add text ellipsis to all form fields - Fix problems with datetime field dropdowns --- ## cx@22.8.2 **Fixes** - Various typing improvements --- ## cx@22.8.0 **Fixes** - Allow onContextMenu on all HTML elements in TypeScript - Properly handle context menus within windows and dropdowns - Allow get/set props in TypeScript - Allow accessor chains for the Sandbox.storage prop - Orient vertical Sliders to be bottom up, instead of top to bottom with the invert flag to control the behavior --- ## cx@22.7.1 **Fixes** - Render overlay backdrop before the body and allow propagation of `mousedown` event to allow integration of other libraries (i.e. prosemirror) which catch events on the document level. --- ## cx@22.7.0 **Features** - TreeAdapter now supports preserving expanded state through a flag `restoreExpandedNodesOnLoad` - Added an example for stateful tree grids --- ## cx@22.6.3 **Features** - TreeAdapter now support the flag `hideRootNodes` - Added the function `findTreePath` to `cx/data`. **Fixes** - Typings for MenuItem - Typings for PieSlice - Skip focusing disabled LookupField options - Typings for Window --- ## cx@22.6.0 **Fixes** - Fix for onCellEdited firing twice - Fix for grid cell editing not working in the first column - Allow accessor chains for `value` and `text` props in lookup fields --- ## cx@22.5.3 **Features** - Allow tooltips in grid headers --- ## cx@22.5.2 **Fixes** - Fix MenuItem typing --- ## cx@22.5.1 **Fixes** - Fix typings for the `Repeater` widget --- ## cx@22.5.0 **Fixes** - Fix bugs related to `startWithMonday` in `Calendar` widgets - Typing improvements - Fix detection of touch events inside modal windows --- # Breaking Changes Sometimes we are forced to introduce breaking changes to the framework. This page will provide information about breaking changes and how to migrate your applications to the latest versions of the framework. ## 26.2.0 ### LookupField: Improved TypeScript discrimination The `LookupField` component now uses TypeScript discriminated unions based on the `infinite` and `multiple` props. This provides better type inference and catches invalid prop combinations at compile time. #### `onQueryPage` replaces `onQuery` for infinite mode When using `LookupField` with `infinite: true`, you must now use the `onQueryPage` prop instead of `onQuery`. **Before:** ```tsx fetchData(query, page, pageSize)} /> ``` **After:** ```tsx fetchData(query, page, pageSize)} /> ``` The `onQuery` prop now only accepts a string query parameter for standard (non-infinite) mode: ```tsx fetchData(query)} /> ``` **Backwards Compatibility:** The runtime includes a compatibility shim that copies `onQuery` to `onQueryPage` when `infinite: true` is set. This allows existing code to continue working, but TypeScript will report type errors. We recommend updating your code to use the new API. #### `pageSize` is now exclusive to infinite mode The `pageSize` prop is now only available when `infinite: true`. If you were using `pageSize` without `infinite`, remove it as it had no effect. #### Props are now discriminated by `multiple` - When `multiple: true`: use `records` and/or `values` props - When `multiple` is not set or `false`: use `value` and `text` props TypeScript will now report errors if you mix props from different modes (e.g., using `value` with `multiple: true`). ## 26.1.0 ### TypeScript Migration The CxJS framework has been fully migrated to TypeScript. This is a major change that brings improved type safety, better IDE support, and enhanced developer experience. ### Separation from React JSX Types CxJS now provides its own JSX type definitions instead of relying on React's JSX types. This separation was necessary because CxJS JSX has fundamental differences from React JSX. To use the new JSX types, update your `tsconfig.json`: ```json { "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "cx" } } ``` With this configuration, TypeScript will use CxJS-specific JSX types, providing proper type checking for CxJS attributes and components. ### Package Upgrades Required The following packages have been updated and should be upgraded to version 26.x: | Package | Description | | ----------------------------------- | ------------------------------------------- | | `cx` | Core framework package | | `cx-react` | React adapter (now written in TypeScript) | | `babel-plugin-transform-cx-imports` | Babel plugin for optimizing imports | | `swc-plugin-transform-cx-jsx` | SWC plugin for CxJS JSX transformation | | `swc-plugin-transform-cx-imports` | SWC plugin for optimizing imports | | `cx-scss-manifest-webpack-plugin` | Webpack plugin for SCSS manifest generation | Some projects have copied `cx-scss-manifest-webpack-plugin` and used it in source form. These projects should now transition to using the official npm package instead. These versions will not work with the 26.x releases due to internal path changes and CSS will appear broken. Alternatively, the plugin can be patched to use the `build` folder instead of the `src` folder to detect which components are actually being used in the project. ### React 18+ Required CxJS 26.x requires React 18 or later. The framework now uses the modern React 18 APIs including `createRoot` from `react-dom/client`. If your application is still using React 17 or earlier, you will need to upgrade React before upgrading to CxJS 26.x. ### Migration Guide For a comprehensive guide on migrating your applications to TypeScript and taking advantage of the new type system, please refer to the [Migration Guide](/intro/migration-guide). --- ## 24.10.0 ### Legend and LegendEntry rendering Legend and LegendEntry components have been refactored to use the flexbox layout. This change might affect the appearance if you have custom styles applied to these components. ## 24.5.1 ### Default Window body padding The Window body now have a default padding. Previously, a few options were used to add padding such as `bodyStyle`, `bodyClass`, or adding margin/padding to the inner content. All these options lead to problems with layout consistency across different themes. If you want to revert to the old behavior, you can set the `pad` property to `false` on the prototype of the Window widget. This will effectively remove the default padding from the Window body, unless `pad` is explicitly set to `true` on the Window. ```javascript import { Window } from "cx/widgets"; Window.prototype.pad = false; ``` Alternatively, you can reset the Sass variable to remove default padding, before importing the CxJS variables. ```scss $cx-default-window-body-padding: 0; @import "~cx/src/variables"; ``` However, the best way forward would be to go through your codebase and remove `bodyStyle`, `bodyClass` values, or padding/margins used for this purpose within the window content. ## 23.2.0 ### Dropped support for Internet Explorer If you need to support Internet Explorer please use an older version of CxJS. ### Dart Sass Transition CxJS theming support is based on Sass. Since the beginning, the `node-sass` package was used to compile `.scss` files to CSS. This package is [deprecated](https://sass-lang.com/blog/libsass-is-deprecated) for some time and we're gradually replacing it with the [`sass`](https://www.npmjs.com/package/sass) package which doesn't rely on native code and therefore offers less compatibility problems, but has some of its own quirks. In the first phase both `node-sass` and `sass` will be supported. Later on, we're going to make a permanent switch after which `node-sass` will not work anymore. These are the steps required to start using `sass` today in your project: 1. remove `node-sass` from `package.json` 2. install `sass` 3. make the following changes in the root `index.scss` file: - add `@use 'sass:math';` at the top of the file - replace `cx-divide` function, after it's been imported ```scss @use 'sass:math'; # define variables ... @import '~cx/src/variables'; @function cx-divide($a, $b) { @return math.div($a, $b); } ``` Voila, your project now compiles CSS using `sass`. No more annoying `node-sass` issues. ## 21.3.0 ### Babel 7 The source code now uses the optional chaining operator. Please upgrade Babel to the latest version or add this plugin to your existing configuration. ### JSX runtime This release contains a new version of `babel-preset-cx-env` plugin which uses the new React JSX transform. This should result in slightly smaller bundle sizes and in some cases it's not required to import VDOM for React components. For more information check [this post on the official React blog](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html). The new release also removes Babel plugins which are now part of the @babel/preset-env preset out of the box, i.e. `@babel/transform-object-spread`. ### Whitespace trimming on generated `cx` code There are new version of `babel-plugin-cx-env` and `babel-plugin-transfrom-cx-jsx` which allow whitespace trimming in the generated code. This might help a bit with the generated bundle sizes. You can set this up in your `babel-config.js` file: ```javascript { presets: [ [ "babel-preset-cx-env", { cx: { jsx: { trimWhitespace: true, trimWhitespaceExceptions: ["Md", "CodeSnippet", "CodeSplit"], }, imports: { useSrc: true, }, }, }, ], ]; } ``` For more information, check the NPM page for [babel-plugin-transform-cx-jsx](https://www.npmjs.com/package/babel-plugin-transform-cx-jsx). ## 21.1.0 ### Change in invokeParentMethod Previously [`invokeParentMethod`](/concepts/controllers#-code-invokeparentmethod-code-) could be used to invoke Controller's own method. If the specified method was not found on current Controller instance, parent instances would be checked until the one with the specified method is found. With this change, `invokeParentMethod` now **skips** the current Controller instance and tries to invoke the specified method in one of the parent instances, as the name suggests. This can cause the code to break if, for example, `invokeParentMethod` was used in one of the inline event handlers: ```javascript

{ let controller = instance.controller; // This will cause an error: // Uncaught Error: Cannot invoke controller // method "onSubmit" as controller is not assigned to the widget. controller.invokeParentMethod("onSubmit", 1); }} text="Submit" />

``` To fix this, make the following change in the `onClick` handler: ```javascript onClick={(e, instance) => { let controller = instance.controller; // Use invokeMethod instead of invokeParentMethod controller.invokeMethod('onSubmit', 1); }} ``` [`invokeMethod`](/concepts/controllers#-code-invokemethod-code-) has the same behaviour as the previous implementation of `invokeParentMethod`, hence it can be used as a fail-safe replacement for `invokeParentMethod` in this version of CxJS. ## 20.1.0 ### Format change for DateTimeField `DateTimeField` now expects regular formats, e.g. `datetime;yyyyMMMdd` (previously only `yyyyMMMdd` part was required). This change enables non-standard, custom formats to be used. ## 19.1.0 ### Babel 7 Starting with this version CxJS tooling requires Babel 7. New versions of the `babel-preset-cx-env`, `babel-plugin-transform-cx-jsx`, and `babel-plugin-transform-cx-imports` packages do not support Babel 6 anymore. These are the steps required to migrate your applications to Babel 7: In `package.json`, update the following packages: - `"babel-core"` => `"@babel/core": "^7.2.2"`, - `"babel-preset-env"` => `"@babel/preset-env": "^7.2.3"` - `"babel-polyfill"` => `"@babel/polyfill": "^7.2.5"` In `babel.config`, replace `useBuiltIns: true` with `useBuiltIns: 'usage'`. In `polyfill.js`, remove `import "babel-polyfill";` If some other Babel plugins are used please make sure that these are also upgraded to versions which target Babel 7. That's it. #### TypeScript One of the benefits that Babel 7 brings is support for TypeScript without the TypeScript tooling. You can easily enable TypeScript in your project by installing the `@babel/preset-typescript` npm package and registering the preset in your `babel.config` file. You'll also have to tweak rules in `webpack.config.js` to support `.ts` and `.tsx` files. Replace ```javascript test: /\.js$/, loader: 'babel-loader', ``` with: ```javascript test: /\.(js|ts|tsx)$/, loader: 'babel-loader', ``` You can now mix `.js`, `.ts` and `.tsx` files. However, some of the [JSX in TS related quirks still apply](https://github.com/codaxy/cx-typescript-boilerplate). ## 18.12.0 ### Functional Components and CxJS attributes In order to support [store refs](https://github.com/codaxy/cxjs/issues/487) some changes were made to how functional components handle CxJS-specific attributes such as `visible`, `controller` and `layout`. For example, let's take a simple Tab component. ```javascript const TabCmp = ({ prop1, children }) => (

{children}

); ``` In previous versions of CxJS, if the `visible` attribute is used on a functional component, it would be applied on all top-level elements. ```javascript Tab1 Content ``` This example above would expand to: ```javascript

Tab1 Content

``` From this version, a PureContainer wrapper is added to all functional components and all CxJS-specific attributes are applied on the wrapper element. ```javascript

Tab1 Content

``` Please note that this is a breaking change only if top-level component is `Rescope`, `Restate` or `DataProxy`. With this change, both functional components and functional controllers can receive the `store` prop which enables [an alternative syntax for accessing data using store references](https://github.com/codaxy/cxjs/issues/487). ## 17.12.0 ### `babel-preset-env` `babel-preset-env` is now a peer dependency of `babel-preset-cx-env`. Therefore it needs to be installed in your project. This change enables the `babel-preset-env` package to be updated independently from the `babel-preset-cx-env` package. ``` npm install babel-preset-env --saveDev yarn add babel-preset-env --dev ``` ### `-bind`, `-tpl`, `-expr` syntax Data-binding attributes can now be written in an alternative syntax with a dash instead of a colon, for example `value:bind` instead of `value-bind`. Although not necessarily a breaking change, both methods are supported which solves a long standing problem of syntax errors that [Visual Studio Code](https://code.visualstudio.com) reports if XML namespaces are used inside JSX. ## 17.7.0 This release adds support for CxJS applications with an extremely short start up time such as [CxJS Hacker News](https://github.com/codaxy/cxjs-hackernews). Bigger applications will improve startup time through incremental app loading and adopting [the app shell architecture](https://developers.google.com/web/fundamentals/architecture/app-shell). In order for us to support minimal application shells some internal CxJS dependencies had to be broken. ### Confirmation Dialogs The `Button` requires `MsgBox` and `Window` components in order to support user confirmation dialogs. This (`confirm`) function is not always necessary, but when needed. it's better to load these additional classes after the application launch. In order to enable CxJS based confirmation dialogs, use the `enableMsgBoxAlerts` method. Otherwise, the browser default `prompt` dialog will appear. To enable the confirmation function on application startup, use the following snippet: ```javascript import { enableMsgBoxAlerts } from "cx/widgets"; enableMsgBoxAlerts(); ``` ### Tooltips Tooltips are not automatically loaded anymore. The following example will not work because tooltips first need to be enabled using the `enableTooltips` method. ```jsx

``` Use the following code to enable tooltips: ```javascript import { enableTooltips } from "cx/widgets"; enableTooltips(); ``` ### Culture-Sensitive Number, Date and Currency Formatting Culture-sensitive formats for dates and numbers are not automatically registered. Formatting is auto-enabled if `NumberField`, `DateField` or any other culture dependent widget is used; otherwise it needs to be enabled using the `enableCultureSensitiveFormatting` method. ```javascript import { enableCultureSensitiveFormatting } from "cx/ui"; enableCultureSensitiveFormatting(); ``` ### Fat Arrow Expansion In order to support fat arrows in expressions CxJS includes a transformer which rewrites fat arrows into the standard function notation. This allows fat arrows to be used in Internet Explorer and older versions of Safari, like in the following example. ```jsx

``` Code from the snippet above will not work in IE anymore because fat arrow expansion is now optional and needs to be enabled using the `enableFatArrowExpansion` method. ```javascript import { enableFatArrowExpansion } from "cx/data"; enableFatArrowExpansion(); ``` ### Enable All For apps that do not use code-splitting and the developers want to enable all internal dependencies, you may use `enableAllInternalDependencies` and everything will be as it was in previous versions. ```javascript import { enableAllInternalDependencies } from "cx/widgets"; enableAllInternalDependencies(); ``` ## 17.4.0 We're proud to announce that we obtained ownership of the `cx` package at [npmjs](https://www.npmjs.com/package/cx) and therefore our `cx-core` package will be replaced with `cx` and deprecated. To migrate your apps, please do the following: In `package.json` replace `cx-core` with `cx`. ``` yarn remove cx-core yarn add cx ``` Additionally, if `babel-plugin-transform-cx-imports` is used with `useSrc` option, in `webpack.config.js` `cx` package should be whitelisted instead of `cx-core` in the `babel-loader` configuration. ```js test: /\.js$/, loader: 'babel-loader', include: /(app|cx)/, //previously (app|cx-core) ``` If `cx-core` reference is used in `.scss` files, replace it with `cx`. ```scss @import "~cx/src/variables"; //cx-core => cx @import "~cx/src/index"; //cx-core => cx ``` After you're done, please upgrade all Cx related packages to the latest version. ```bash yarn upgrade-interactive ``` Also, upgrade `cx-cli` tools globally. ```bash yarn global add cx-cli ``` That's it. The `cx-core` package will continue to work, but we recommend that all users to switch to the new package. The benefit of this change is that the code completion will now work as IDEs will now be able to find the `cx` package. --- # Migration Guide Starting with CxJS 26.x, the core framework has been migrated to TypeScript. This guide covers the patterns and best practices for working with TypeScript in CxJS applications, whether you're migrating an existing project or starting fresh. ## Project Setup ### TypeScript Configuration Configure your `tsconfig.json` with the following settings for optimal CxJS support: ```json { "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "cx", "moduleResolution": "bundler", "esModuleInterop": true } } ``` The key setting is `"jsxImportSource": "cx"`. CxJS now provides its own JSX type definitions instead of relying on React's JSX types. This means CxJS-specific attributes like `visible`, `controller`, `layout`, and data-binding functions (`bind()`, `expr()`, `tpl()`) are properly typed without conflicts with React's typings. ### Webpack Configuration With TypeScript, you no longer need `babel-loader` or special Babel plugins for CxJS. Simply use `ts-loader` to handle TypeScript files: ```javascript { test: /\.(ts|tsx)$/, loader: 'ts-loader', exclude: /node_modules/ } ``` ### Vite Support CxJS also supports Vite as a build tool. Vite provides faster development experience with hot module replacement. Configure Vite with the appropriate React plugin and ensure `jsxImportSource` is set to `cx` in your configuration. ### Without `transform-cx-jsx` Plugin Applications should continue to work with the `transform-cx-jsx` plugin enabled. However, if you want to run your application without this plugin, the following requirements apply: 1. All functional components must be wrapped in `createFunctionalComponent` calls 2. The special JSX prop syntax (`-bind`, `-expr`, `-tpl`) must be converted to function calls (`bind()`, `tpl()`, `expr()`) or object form like `{{ bind: "prop" }}`, `{{ tpl: "template" }}`, or `{{ expr: "1+1" }}` 3. All components previously developed in JavaScript must be ported to TypeScript. ### Bundle Size Optimization (Optional) While not required, you can use `babel-plugin-transform-cx-imports` to minimize bundle size by transforming CxJS imports to more specific paths: ```bash # Install the plugin npm install babel-plugin-transform-cx-imports --save-dev # In babel.config.js { plugins: [ ["transform-cx-imports", { useSrc: true }] ] } ``` If using this plugin, chain `babel-loader` after `ts-loader`: ```javascript { test: /\.(ts|tsx)$/, exclude: /node_modules/, use: ['babel-loader', 'ts-loader'] } ``` ## General Improvements ### Renamed: createModel The `createAccessorModelProxy` function has been renamed to `createModel` for brevity. The old name remains available as an alias for backward compatibility, but `createModel` is now preferred. ```typescript // Before import { createAccessorModelProxy } from "cx/data"; const m = createAccessorModelProxy(); // After (preferred) import { createModel } from "cx/data"; const m = createModel(); ``` ### Typed Controller Methods With TypeScript, you can use `getControllerByType` to get a typed controller reference instead of using string method names. This provides compile-time safety and IDE autocomplete. ```typescript import { Controller, bind } from "cx/ui"; import { Button, Section } from "cx/widgets"; class PageController extends Controller { onSave() { // save logic } onDelete(id: string) { // delete logic } } export default (

{/* Type-safe controller method calls */} instance.getControllerByType(PageController).onSave() } > Save instance.getControllerByType(PageController).onDelete("123") } > Delete

); ``` The `getControllerByType(ControllerClass)` method searches up the widget tree and returns a typed controller instance, enabling full autocomplete and compile-time type checking for controller methods and their parameters. ### Typed RenderingContext CxJS uses a `RenderingContext` object to pass information down the widget tree during rendering. Different widget families define typed context interfaces that extend `RenderingContext` for type-safe access to context properties. **Available typed contexts:** - `FormRenderingContext` - Form validation context (`parentDisabled`, `parentReadOnly`, `validation`, etc.) - `SvgRenderingContext` - SVG layout context (`parentRect`, `inSvg`, `addClipRect`) - `ChartRenderingContext` - Chart context extending SVG (`axes`) When creating custom widgets that consume these context properties, import and use the typed context interface in your method signatures: ```typescript import type { FormRenderingContext } from "cx/widgets"; export class MyFormWidget extends Field { explore(context: FormRenderingContext, instance: Instance) { // Type-safe access to form context properties if (context.parentDisabled) { // handle disabled state } super.explore(context, instance); } } ``` ### Typed ContentResolver The `ContentResolver` widget now supports type inference for the `onResolve` callback params. TypeScript automatically infers the resolved types from your params definition: ```typescript import { ContentResolver } from "cx/widgets"; import { createModel } from "cx/data"; interface AppModel { user: { name: string; age: number }; } const model = createModel(); age: model.user.age, // AccessorChain limit: 10, // number literal }} onResolve={(params) => { // TypeScript infers: // params.name: string // params.age: number // params.limit: number return

{params.name} is {params.age} years old

; }} /> ``` **Type resolution behavior:** | Param Type | Resolved Type | | ------------------------------- | ----------------------------------- | | Literal values (`42`, `"text"`) | Preserves type (`number`, `string`) | | `AccessorChain` | `T` | | `Selector` / `GetSet` | `T` | | `bind()` / `tpl()` / `expr()` | `any` (runtime-only) | The utility types `ResolveProp

` and `ResolveStructuredProp` are exported from `cx/ui` if you need to use them in your own generic components. ### Expression Helpers CxJS provides type-safe selector functions for reactive bindings. These helpers return `Selector` which can be used anywhere a boolean binding is expected: ```typescript import { truthy, isEmpty, equal, greaterThan } from "cx/ui"; import { createModel } from "cx/data"; interface AppModel { user: { name: string; age: number }; items: string[]; } const model = createModel(); // Using expression helpers for type-safe boolean bindings

User has a name

No items available

User is an adult

``` **Available expression helpers:** | 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 Helper The `format` helper creates a selector that formats values using CxJS format strings. This is useful for displaying formatted numbers, dates, or percentages in text props: ```typescript import { createModel } from "cx/data"; import { format } from "cx/ui"; interface Product { name: string; price: number; discount: number; } const m = createModel(); // Format as number with 2 decimal places

// Format as percentage

// With custom null text

``` The format string uses CxJS format syntax (e.g., `"n;2"` for numbers, `"p;0"` for percentages, `"d"` for dates). The optional third parameter specifies text to display for null/undefined values. ### Template Helper with Accessor Chains The `tpl` function now supports accessor chains in addition to its original string-only form. This allows you to create formatted strings from multiple values with full type safety: ```typescript import { createModel } from "cx/data"; import { tpl } from "cx/ui"; interface Person { firstName: string; lastName: string; age: number; } const m = createModel(); // Original string-only form still works

// New accessor chain form with positional placeholders

// Supports formatting in placeholders

// Supports null text

``` The accessor chain form uses positional placeholders (`{0}`, `{1}`, etc.) and supports all StringTemplate features including formatting (`:format`) and null text (`|nullText`). ### Typed Config Properties Several widget config properties now have improved type definitions that provide better autocomplete and type checking when using the `type` or `$type` pattern. #### Selection Grid, PieChart, and BubbleGraph support typed `selection` configs: ```typescript import { Grid } from "cx/widgets"; import { KeySelection } from "cx/ui"; ``` Supported selection types: `Selection`, `KeySelection`, `PropertySelection`, `SimpleSelection`. #### Chart Axes Chart axes support typed configs for different axis types: ```typescript import { Chart } from "cx/charts"; import { NumericAxis, CategoryAxis } from "cx/charts"; {/* chart content */} ``` Supported axis types: `Axis`, `NumericAxis`, `CategoryAxis`, `TimeAxis`. #### Data Adapters Grid and List support typed `dataAdapter` configs: ```typescript import { Grid } from "cx/widgets"; import { GroupAdapter } from "cx/ui"; ``` Supported adapter types: `ArrayAdapter`, `GroupAdapter`, `TreeAdapter`. #### Dropdown Options Form fields with dropdowns (ColorField, DateTimeField, MonthField, LookupField) accept typed `dropdownOptions`: ```typescript import { DateTimeField } from "cx/widgets"; ``` #### Typed Controllers The `controller` property accepts multiple forms: a class, a config object with `type`/`$type`, an inline config, or a factory function. Because this type is intentionally flexible ("open"), TypeScript's generic inference may not catch extra or misspelled properties in config objects. Use the `validateConfig` helper to enable strict property checking: ```typescript import { validateConfig } from "cx/util"; import { Controller } from "cx/ui"; interface MyControllerConfig { apiEndpoint: string; maxRetries: number; } class MyController extends Controller { declare apiEndpoint: string; declare maxRetries: number; constructor(config?: MyControllerConfig) { super(config); } } // validateConfig enables strict checking

``` The `validateConfig` function is a compile-time helper that returns its input unchanged at runtime. It can be used with any config object that follows the `{ type: Class, ...props }` pattern. ## Authoring Widgets Previously, CxJS widgets had to be written in JavaScript with optional TypeScript declaration files (`.d.ts`) for typing. With CxJS 26.x, you can now author widgets entirely in TypeScript. > **Important:** Widget files must use the `/** @jsxImportSource react */` pragma because > the widget's `render` method uses React JSX. ### Complete Widget Example Here's a complete example showing all the steps to create a CxJS widget in TypeScript: ```typescript /** @jsxImportSource react */ import { BooleanProp, StringProp, RenderingContext, VDOM } from "cx/ui"; import { HtmlElement, HtmlElementConfig } from "cx/widgets"; // 1. Define the Config interface export interface MyButtonConfig extends HtmlElementConfig { icon?: StringProp; pressed?: BooleanProp; } // 2. Extend the appropriate generic base class (Instance type argument is optional) export class MyButton extends HtmlElement { // 3. Use declare for all properties from config/prototype declare icon?: string; declare pressed?: boolean; declare baseClass: string; // 4. Declare bindable props in declareData declareData(...args) { super.declareData(...args, { icon: undefined, pressed: undefined, }); } // 5. Add constructor accepting the config type constructor(config?: MyButtonConfig) { super(config); } // 6. Implement render method with React JSX render( context: RenderingContext, instance: Instance, key: string ): React.ReactNode { return ( this.handleClick(e, instance)} > {this.icon && {Icon.render(instance.data.icon)}} {this.renderChildren(context, instance)} ); } } // 7. Initialize prototype properties MyButton.prototype.baseClass = "mybutton"; ``` ### Key Steps 1. **Add React JSX pragma** - Use `/** @jsxImportSource react */` at the top of widget files 2. **Define Config interface** - Name it `[WidgetName]Config` and extend the parent's config 3. **Extend generic base class** - Use `HtmlElement`, `ContainerBase`, etc. 4. **Use `declare` for properties** - Prevents TypeScript from overwriting config/prototype values 5. **Declare bindable props in `declareData`** - Register props that support data binding 6. **Add typed constructor** - Accepts the config type for proper type inference 7. **Implement render method** - Returns React JSX elements ### Config Property Types Use these types for bindable properties in your Config interface: | Type | Usage | | ------------- | ---------------------------------- | | `StringProp` | Bindable string property | | `BooleanProp` | Bindable boolean property | | `NumberProp` | Bindable number property | | `Prop` | Bindable property of custom type T | | `RecordsProp` | Array data (Grid, List) | ### Using `declare` for Properties > **Important:** Widget properties must use `declare` to avoid being overwritten. Without `declare`, > TypeScript class fields will override values passed through the config (via `Object.assign` in the > constructor) or values defined on the prototype. ```typescript // WRONG - these fields will override config values with undefined export class MyWidget extends HtmlElement { icon?: string; // Overwrites config.icon! pressed?: boolean; // Overwrites config.pressed! } // CORRECT - declare tells TypeScript the field exists without initializing it export class MyWidget extends HtmlElement { declare icon?: string; declare pressed?: boolean; declare baseClass: string; // Non-nullable when defined in prototype } ``` ### Base Classes CxJS provides generic base classes for creating typed widgets. The second type argument (Instance) is optional: | Base Class | Use Case | | --------------------------- | -------------------------------- | | `HtmlElement` | Widgets rendering HTML elements | | `ContainerBase` | Widgets containing other widgets | | `PureContainerBase` | Containers without HTML wrapper | | `Field` | Form input widgets | ### Custom Instance Types When a widget needs custom properties on its instance, create a custom instance interface: ```typescript export interface MyWidgetInstance extends Instance { customData: SomeType; } export class MyWidget extends HtmlElement { initInstance(context: RenderingContext, instance: MyWidgetInstance): void { instance.customData = initializeSomething(); super.initInstance(context, instance); } } ``` ### Migration Checklist When migrating a widget from JavaScript to TypeScript: 1. Add JSX pragma `/** @jsxImportSource react */` if file contains JSX 2. Create `[WidgetName]Config` interface extending appropriate parent 3. Add generic type parameters to base class if needed 4. Add constructor accepting the config type 5. Add `declare` statements for all class properties 6. Add type annotations to all methods 7. Create custom instance interface if needed 8. Fix prototype initializations (use `undefined` not `null` where needed) 9. Declare `baseClass` as non-nullable if defined in prototype 10. Delete the corresponding `.d.ts` file ### File Organization After migration, each widget should have: - `Widget.tsx` - The implementation with inline types - No separate `Widget.d.ts` - Types are in the source file Index files (`index.ts`) should re-export all public types: ```typescript export { Button, ButtonConfig } from "./Button"; export { FlexBox, FlexBoxConfig } from "./FlexBox"; ``` --- # Sample Applications Explore full-featured applications built with CxJS to see how various framework features work together in real-world scenarios. | Application | Description | Demo | Source | | -------------------- | ------------------------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------- | | Tdo | Task management app with forms, lists, and local storage | [App](https://tdoapp.com) | [GitHub](https://github.com/codaxy/tdo) | | Hacker News | HN clone with routing, data fetching, and infinite scrolling | [App](https://hn.cxjs.io) | [GitHub](https://github.com/codaxy/cxjs-hackernews) | | State of JS Explorer | Interactive visualization of JavaScript survey data | [App](https://codaxy.github.io/state-of-js-2016-explorer) | [GitHub](https://github.com/codaxy/state-of-js-2016-explorer) | | Starter Kit | Admin/dashboard boilerplate with routing and charts | [App](https://cxjs.io/starter) | [GitHub](https://github.com/codaxy/cx-starter-kit) | | Tailwind Template | CxJS + Tailwind CSS application template | [App](https://twapp.cxjs.io) | [GitHub](https://github.com/codaxy/cxjs-tailwindcss-template) | | Wealth Management | Enterprise dashboard with forms, tables, and charts | [App](https://wealth-management.cxjs.io) | [GitHub](https://github.com/codaxy/wealth-management-demo) | | Worldoscope | World Bank data reporting tool with customizable templates | [App](https://worldoscope.cxjs.io) | [GitHub](https://github.com/codaxy/worldoscope) | | Home Expenses | Expense tracking tutorial app with forms and charts | [App](https://home-expenses.cxjs.io) | [GitHub](https://github.com/codaxy/cxjs-home-expenses-app-tutorial) | --- # Component Libraries These are add-on libraries that extend CxJS with additional components for specific use cases. | Library | Description | Website | Source | | -------------------- | ------------------------------------------------------------ | ----------------------------------------- | -------------------------------------------------- | | CxJS Diagrams | SVG-based diagram library for flowcharts and shapes | [Website](https://diagrams.cxjs.io) | [GitHub](https://github.com/codaxy/cx-diagrams) | | Cx Google Maps | Google Maps wrapper with markers, polygons, and heatmaps | [Website](https://maps.cxjs.io) | [GitHub](https://github.com/codaxy/cx-google-maps) | --- # 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. | --- # Rescope Rescope selects a common prefix for data bindings, enabling shorter paths within its scope. This is useful when working with deeply nested data structures. ## Example ```tsx import { createModel } from "cx/data"; import { Controller, LabelsTopLayout, Rescope } from "cx/ui"; import { TextField } from "cx/widgets"; interface Manager { name: string; email: string; } interface Team { manager: Manager; size: number; } interface PageModel { company: { name: string; team: Team; }; } const m = createModel(); // Model for rescoped context (bound to company.team.manager) const mManager = createModel(); class PageController extends Controller { onInit() { this.store.set(m.company, { name: "Acme Corp", team: { manager: { name: "John Doe", email: "john@acme.com", }, size: 10, }, }); } } export default (

Without Rescope (long paths):

With Rescope (short paths):

); ``` ## Typed Model When using Rescope, create a separate model proxy for the rescoped context: ```tsx const m = createModel(); // Model for rescoped context const mManager = createModel(); ``` Then use the rescoped model within the Rescope children: ```tsx ``` ## Accessing Outside Data Within the scope, outside data can be accessed using the `$root.` prefix or by using the `data` property to explicitly bring in external bindings: ```tsx

``` ## Configuration | Property | Type | Description | | ---------- | -------- | ------------------------------------------------------------- | | `bind` | `string` | Prefix path to be used for data binding. Defaults to `$page`. | | `data` | `object` | Outside data that will be carried into this scope. | | `rootName` | `string` | Alias used to expose root data. Defaults to `$root`. | --- # 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) | --- # SimpleSelection SimpleSelection is the most basic selection model. It stores the entire selected object in the bound variable. Only single selection is supported. ## When to Use - Simple single-select scenarios - When you need immediate access to the full selected object - Quick prototyping or simple lists Note that selection is lost if the selected object changes in the data source, since the reference will no longer match. For more robust selection, consider [KeySelection](./key-selection). ## Example ```tsx import { createModel } from "cx/data"; import { SimpleSelection, Controller } from "cx/ui"; import { List } from "cx/widgets"; interface Item { id: number; name: string; } interface PageModel { items: Item[]; selection: Item; $record: Item; } 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" }, ]); } } export default (

Store content

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

); ``` ## Configuration | Property | Type | Default | Description | | -------- | ----------- | ------- | -------------------------------------------------------- | | `bind` | `Prop` | — | Binding for the selected object | | `toggle` | `boolean` | `false` | Enable toggle mode (clicking selected item deselects it) | --- # PropertySelection PropertySelection tracks selection state using a boolean property on each record. When an item is selected, its `selected` property (or custom field) is set to `true`. ## When to Use - Checkbox-based selection where each row has a checkbox - When selection state should be saved with the data - When you need to easily filter or count selected items - Scatter graphs and other charts with selectable points ## Example ```tsx import { createModel } from "cx/data"; import { PropertySelection, Controller } from "cx/ui"; import { Grid, Checkbox } from "cx/widgets"; interface Item { id: number; name: string; selected: boolean; } interface PageModel { items: Item[]; $record: Item; } const m = createModel(); class PageController extends Controller { onInit() { this.store.init(m.items, [ { id: 1, name: "Apple", selected: false }, { id: 2, name: "Banana", selected: true }, { id: 3, name: "Cherry", selected: false }, { id: 4, name: "Date", selected: false }, ]); } } export default (

, align: "center", width: 30, }, { header: "Name", field: "name" }, ]} />

Store content

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

); ``` ## Configuration | Property | Type | Default | Description | | --------------- | --------- | ------------ | --------------------------------------------------------- | | `selectedField` | `string` | `"selected"` | Field name on each record that stores the selection state | | `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