@nocobase/plugin-flow-engine 2.1.0-alpha.1 → 2.1.0-alpha.3

package/dist/ai/docs/runjs/context/get-var.md

@@ -0,0 +1,151 @@
+# ctx.getVar()
+
+**Asynchronously** reads a variable from the current runtime context. Variable sources are the same as for SQL and template `{{ctx.xxx}}`: current user, current record, view params, popup context, etc.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock / JSField** | Get current record, user, resource, etc. for rendering or logic |
+| **Linkage / event flow** | Read `ctx.record`, `ctx.formValues`, etc. for conditions |
+| **Formulas / templates** | Same variable resolution as `{{ctx.xxx}}` |
+
+## Type
+
+```ts
+getVar(path: string): Promise<any>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | `string` | Variable path; **must start with `ctx.`**; supports dot and array index |
+
+**Returns**: `Promise<any>`; use `await` to get the resolved value. Returns `undefined` if the variable does not exist.
+
+> If the path does not start with `ctx.`, an error is thrown: `ctx.getVar(path) expects an expression starting with "ctx.", got: "..."`.
+
+## Common paths
+
+| Path | Description |
+|------|-------------|
+| `ctx.record` | Current record (when form/detail is bound to a record) |
+| `ctx.record.id` | Current record primary key |
+| `ctx.formValues` | Current form values (common in linkage/event flow; in form context prefer `ctx.form.getFieldsValue()` for live values) |
+| `ctx.user` | Current user |
+| `ctx.user.id` | Current user id |
+| `ctx.user.nickname` | Current user nickname |
+| `ctx.user.roles.name` | Current user role names (array) |
+| `ctx.popup.record` | Record in popup |
+| `ctx.popup.record.id` | Popup record primary key |
+| `ctx.urlSearchParams` | URL query params (from `?key=value`) |
+| `ctx.token` | Current API token |
+| `ctx.role` | Current role |
+
+## ctx.getVarInfos()
+
+Returns **structure info** (type, title, child properties, etc.) for variables that can be resolved in the current context. Useful to discover available paths. Values are static meta, not runtime values.
+
+### Type
+
+```ts
+getVarInfos(options?: { path?: string | string[]; maxDepth?: number }): Promise<Record<string, any>>;
+```
+
+Each key in the result is a variable path; each value is that path’s structure (e.g. `type`, `title`, `properties`).
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `path` | `string \| string[]` | Limit to paths under this; e.g. `'record'`, `'record.id'`, `'ctx.record'`, `'{{ ctx.record }}'`; array = multiple paths merged |
+| `maxDepth` | `number` | Max depth to expand; default `3`. Without path, top-level depth=1; with path, that node depth=1 |
+
+### Example
+
+```ts
+const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });
+
+const vars = await ctx.getVarInfos({ path: 'popup.record', maxDepth: 3 });
+
+const vars = await ctx.getVarInfos();
+```
+
+## Relation to ctx.getValue
+
+| Method | Context | Description |
+|--------|---------|-------------|
+| `ctx.getValue()` | JSField, JSItem, etc. | Sync; **current field** value; requires form binding |
+| `ctx.getVar(path)` | Any RunJS | Async; **any ctx variable**; path must start with `ctx.` |
+
+In JSField, use getValue/setValue for the field; use getVar for other context (record, user, formValues).
+
+## Notes
+
+- **Path must start with `ctx.`**: e.g. `ctx.record.id`; otherwise an error is thrown.
+- **Async**: Use `await`, e.g. `const id = await ctx.getVar('ctx.record.id')`.
+- **Missing variable**: Returns `undefined`; use `??` for default: `(await ctx.getVar('ctx.user.nickname')) ?? 'Guest'`.
+- **Form values**: Get via `await ctx.getVar('ctx.formValues')`; not exposed as `ctx.formValues`. In form context prefer `ctx.form.getFieldsValue()` for latest values.
+
+## Examples
+
+### Current record id
+
+```ts
+const recordId = await ctx.getVar('ctx.record.id');
+if (recordId) {
+  ctx.message.info(`Current record: ${recordId}`);
+}
+```
+
+### Popup record
+
+```ts
+const recordId = await ctx.getVar('ctx.popup.record.id');
+if (recordId) {
+  ctx.message.info(`Popup record: ${recordId}`);
+}
+```
+
+### Array field items
+
+```ts
+const roleNames = await ctx.getVar('ctx.user.roles.name');
+// e.g. ['admin', 'member']
+```
+
+### Default value
+
+```ts
+const userName = (await ctx.getVar('ctx.user.nickname')) ?? 'Guest';
+```
+
+### Form field value
+
+```ts
+const status = await ctx.getVar('ctx.formValues.status');
+if (status === 'draft') {
+  // ...
+}
+```
+
+### URL query params
+
+```ts
+const id = await ctx.getVar('ctx.urlSearchParams.id'); // ?id=xxx
+```
+
+### Explore variables
+
+```ts
+const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });
+// e.g. { 'record.id': { type: 'string', title: 'id' }, ... }
+```
+
+## Related
+
+- [ctx.getValue()](./get-value.md): sync current field value (JSField/JSItem only)
+- [ctx.form](./form.md): form instance; `ctx.form.getFieldsValue()` for live form values
+- [ctx.model](./model.md): current model
+- [ctx.blockModel](./block-model.md): parent block
+- [ctx.resource](./resource.md): resource in current context
+- SQL / template `{{ctx.xxx}}`: same resolution as `ctx.getVar('ctx.xxx')`

package/dist/ai/docs/runjs/context/i18n.md

@@ -0,0 +1,77 @@
+# ctx.i18n
+
+The i18n instance for the current context; used to read or change the language. **Use [ctx.t()](./t.md) for all translated text**; do not use `ctx.i18n.t`.
+
+## Use Cases
+
+Available in all RunJS environments (JSBlock, JSField, JSItem, JSColumn, event flow, linkage, etc.).
+
+## Type
+
+```typescript
+interface i18n: {
+  language: string;
+  changeLanguage(lng: string): Promise<any>;
+}
+```
+
+## Common Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `language` | `string` | Current language code (e.g. `zh-CN`, `en-US`) |
+
+## Common Methods
+
+### changeLanguage(lng)
+
+Change the current language.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `lng` | `string` | Target language code (e.g. `en-US`, `zh-CN`) |
+
+**Returns**: `Promise<any>`, resolves when the language has been changed.
+
+## Examples
+
+### Read current language
+
+```ts
+const lang = ctx.i18n.language;
+if (lang.startsWith('zh')) {
+  ctx.render(ctx.t('Chinese UI'));
+} else {
+  ctx.render(ctx.t('English UI'));
+}
+```
+
+### Change language
+
+```ts
+await ctx.i18n.changeLanguage('en-US');
+
+await ctx.i18n.changeLanguage('zh-CN');
+```
+
+### Language switch button
+
+```ts
+const { Button } = ctx.libs.antd;
+const isZh = ctx.i18n.language.startsWith('zh');
+ctx.render(
+  <Button onClick={async () => {
+    await ctx.i18n.changeLanguage(isZh ? 'en-US' : 'zh-CN');
+  }}>
+    {ctx.t(isZh ? 'Switch to English' : 'Switch to Chinese')}
+  </Button>,
+);
+```
+
+## Notes
+
+- **Translated text**: Use `ctx.t()` only; do not use `ctx.i18n.t`.
+
+## Related
+
+- [ctx.t()](./t.md): translation; use this for all copy

package/dist/ai/docs/runjs/context/import-async.md

@@ -0,0 +1,200 @@
+# ctx.importAsync()
+
+Dynamically loads **ESM modules** or **CSS** by URL; use in all RunJS scenarios. For third-party ESM use `ctx.importAsync()`; for UMD/AMD use `ctx.requireAsync()`. Pass a `.css` URL to load and inject styles.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock** | Load Vue, ECharts, Tabulator, etc. for custom charts, tables, boards |
+| **JSField / JSItem / JSColumn** | Load small ESM utils (e.g. dayjs plugins) for rendering |
+| **Event flow / action events** | Load dependencies then run logic |
+
+## Type
+
+```ts
+importAsync<T = any>(url: string): Promise<T>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | ESM or CSS URL. Supports shorthand `<package>@<version>` or subpath `<package>@<version>/<path>` (e.g. `vue@3.4.0`, `dayjs@1/plugin/relativeTime.js`), resolved with configured CDN prefix; full URLs also supported. For `.css` URLs, loads and injects styles. For React-dependent libs add `?deps=react@18.2.0,react-dom@18.2.0` to share the same React instance. |
+
+## Returns
+
+- Resolved module namespace object (Promise value).
+
+## URL format
+
+- **ESM and CSS**: Besides ESM, you can load CSS (pass a `.css` URL; it is injected into the page).
+- **Shorthand**: When not configured, **https://esm.sh** is used as CDN prefix. E.g. `vue@3.4.0` → `https://esm.sh/vue@3.4.0`.
+- **?deps**: For React-dependent libs (e.g. `@dnd-kit/core`, `react-big-calendar`) add `?deps=react@18.2.0,react-dom@18.2.0` to avoid Invalid hook call from multiple React instances.
+- **Self-hosted CDN**: Set env vars for intranet or custom service:
+  - **ESM_CDN_BASE_URL**: ESM CDN base (default `https://esm.sh`)
+  - **ESM_CDN_SUFFIX**: Optional suffix (e.g. jsDelivr `/+esm`)
+  - Reference: [nocobase/esm-server](https://github.com/nocobase/esm-server)
+
+## vs ctx.requireAsync()
+
+- **ctx.importAsync()**: Loads **ESM**; returns module namespace; good for Vue, dayjs, etc. (ESM builds).
+- **ctx.requireAsync()**: Loads **UMD/AMD** or global scripts; good for ECharts, FullCalendar (UMD), etc. If a lib has ESM, prefer `ctx.importAsync()`.
+
+## Examples
+
+### Basic
+
+```javascript
+const Vue = await ctx.importAsync('vue@3.4.0');
+
+const relativeTime = await ctx.importAsync('dayjs@1/plugin/relativeTime.js');
+
+const pkg = await ctx.importAsync('https://cdn.example.com/my-module.js');
+
+await ctx.importAsync('https://cdn.example.com/theme.css');
+```
+
+### ECharts
+
+```ts
+const echarts = await ctx.importAsync('echarts@5.4.3');
+
+const chartEl = document.createElement('div');
+chartEl.style.width = '100%';
+chartEl.style.height = '400px';
+ctx.render(chartEl);
+
+const chart = echarts.init(chartEl);
+
+const option = {
+  title: { text: 'Sales Overview', left: 'center' },
+  tooltip: { trigger: 'axis' },
+  legend: { data: ['Sales', 'Profit'], top: '10%' },
+  xAxis: { type: 'category', data: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'] },
+  yAxis: { type: 'value' },
+  series: [
+    { name: 'Sales', type: 'bar', data: [120, 200, 150, 80, 70, 110] },
+    { name: 'Profit', type: 'line', data: [20, 40, 30, 15, 12, 25] },
+  ],
+};
+
+chart.setOption(option);
+
+window.addEventListener('resize', () => chart.resize());
+
+chart.on('click', (params) => {
+  ctx.message.info(`Clicked ${params.seriesName} on ${params.name}, value: ${params.value}`);
+});
+```
+
+### Tabulator
+
+```ts
+await ctx.importAsync('tabulator-tables@6.2.5/dist/css/tabulator.min.css');
+
+const { TabulatorFull } = await ctx.importAsync('tabulator-tables@6.2.5');
+
+const tableEl = document.createElement('div');
+ctx.render(tableEl);
+
+const table = new TabulatorFull(tableEl, {
+  data: [
+    { id: 1, name: 'Alice', age: 25, city: 'Beijing' },
+    { id: 2, name: 'Bob', age: 30, city: 'Shanghai' },
+    { id: 3, name: 'Charlie', age: 28, city: 'Guangzhou' },
+  ],
+  columns: [
+    { title: 'ID', field: 'id', width: 80 },
+    { title: 'Name', field: 'name', width: 150 },
+    { title: 'Age', field: 'age', width: 100 },
+    { title: 'City', field: 'city', width: 150 },
+  ],
+  layout: 'fitColumns',
+  pagination: true,
+  paginationSize: 10,
+});
+
+table.on('rowClick', (e, row) => {
+  const rowData = row.getData();
+  ctx.message.info(`Row clicked: ${rowData.name}`);
+});
+```
+
+### FullCalendar (ESM)
+
+```ts
+const { Calendar } = await ctx.importAsync('@fullcalendar/core@6.1.20');
+const dayGridPlugin = await ctx.importAsync('@fullcalendar/daygrid@6.1.20');
+
+const calendarEl = document.createElement('div');
+calendarEl.id = 'calendar';
+ctx.render(calendarEl);
+
+const calendar = new Calendar(calendarEl, {
+  plugins: [dayGridPlugin.default || dayGridPlugin],
+  headerToolbar: {
+    left: 'prev,next today',
+    center: 'title',
+    right: 'dayGridMonth',
+  },
+});
+
+calendar.render();
+```
+
+### dnd-kit (with ?deps)
+
+For React-based libs like `@dnd-kit/core`, use `?deps=react@18.2.0,react-dom@18.2.0` so the same React instance is used and hooks work:
+
+```ts
+const React = await ctx.importAsync('react@18.2.0');
+const { createRoot } = await ctx.importAsync('react-dom@18.2.0/client');
+const core = await ctx.importAsync('@dnd-kit/core@6.3.1?deps=react@18.2.0,react-dom@18.2.0');
+// Use core (DndContext, useDraggable, useDroppable, etc.) with React
+```
+
+### react-big-calendar
+
+```tsx
+await ctx.importAsync('react-big-calendar@1.11.4/lib/css/react-big-calendar.css');
+
+const React = await ctx.importAsync('react@18.2.0');
+const { Calendar, dateFnsLocalizer } = await ctx.importAsync('react-big-calendar@1.11.4?deps=react@18.2.0,react-dom@18.2.0');
+const { format, parse, startOfWeek, getDay } = await ctx.importAsync('date-fns@2.30.0');
+const enUS = await ctx.importAsync('date-fns@2.30.0/locale/en-US.js');
+
+const localizer = dateFnsLocalizer({
+  format,
+  parse,
+  startOfWeek,
+  getDay,
+  locales: { 'en-US': enUS },
+});
+
+const events = [
+  { title: 'All Day Event', start: new Date(2026, 0, 28), end: new Date(2026, 0, 28), allDay: true },
+  { title: 'Meeting', start: new Date(2026, 0, 29, 10, 0), end: new Date(2026, 0, 29, 11, 0) },
+];
+
+ctx.render(
+  <Calendar
+    localizer={localizer}
+    events={events}
+    startAccessor="start"
+    endAccessor="end"
+    style={{ height: '80vh' }}
+  />
+);
+```
+
+## Notes
+
+- Depends on network/CDN; for intranet set **ESM_CDN_BASE_URL** to your own service.
+- When a lib has both ESM and UMD, prefer `ctx.importAsync()` for better module semantics.
+- For React-dependent libs always add `?deps=react@18.2.0,react-dom@18.2.0` (or the version your app uses) to avoid Invalid hook call.
+
+## Related
+
+- [ctx.requireAsync()](./require-async.md): load UMD/AMD or global scripts; good for ECharts, FullCalendar (UMD)
+- [ctx.render()](./render.md): render into container

package/dist/ai/docs/runjs/context/init-resource.md

@@ -0,0 +1,74 @@
+# ctx.initResource()
+
+**Initializes** the current context’s resource: if `ctx.resource` does not exist, creates one of the given type and binds it; otherwise uses the existing one. After that you can use `ctx.resource`.
+
+## Use Cases
+
+Typically used only in **JSBlock** (standalone block). Most blocks and popups already have `ctx.resource`; JSBlock does not, so call `ctx.initResource(type)` first, then use `ctx.resource`.
+
+## Type
+
+```ts
+initResource(
+  type: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource' | 'SQLResource'
+): FlowResource;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | `string` | Resource type: `'APIResource'`, `'SingleRecordResource'`, `'MultiRecordResource'`, `'SQLResource'` |
+
+**Returns**: The resource instance in the current context (i.e. `ctx.resource`).
+
+## Relation to ctx.makeResource()
+
+| Method | Behavior |
+|--------|----------|
+| `ctx.initResource(type)` | Creates and binds if `ctx.resource` is missing; otherwise returns existing. Ensures `ctx.resource` is set |
+| `ctx.makeResource(type)` | Creates a new instance and returns it; **does not** set `ctx.resource`. Use when you need multiple resources or a temporary one |
+
+## Examples
+
+### List data (MultiRecordResource)
+
+```ts
+ctx.initResource('MultiRecordResource');
+ctx.resource.setResourceName('users');
+await ctx.resource.refresh();
+const rows = ctx.resource.getData();
+ctx.render(<pre>{JSON.stringify(rows, null, 2)}</pre>);
+```
+
+### Single record (SingleRecordResource)
+
+```ts
+ctx.initResource('SingleRecordResource');
+ctx.resource.setResourceName('users');
+ctx.resource.setFilterByTk(1);
+await ctx.resource.refresh();
+const record = ctx.resource.getData();
+```
+
+### Specify data source
+
+```ts
+ctx.initResource('MultiRecordResource');
+ctx.resource.setDataSourceKey('main');
+ctx.resource.setResourceName('orders');
+await ctx.resource.refresh();
+```
+
+## Notes
+
+- In most blocks (form, table, detail, etc.) and popups, `ctx.resource` is already bound; no need to call `ctx.initResource`.
+- Only in contexts like JSBlock that have no resource by default do you need to initialize.
+- After init, call `setResourceName(name)` and then `refresh()` to load data.
+
+## Related
+
+- [ctx.resource](./resource.md): resource in current context
+- [ctx.makeResource()](./make-resource.md): create resource without binding to `ctx.resource`
+- [MultiRecordResource](../resource/multi-record-resource.md)
+- [SingleRecordResource](../resource/single-record-resource.md)
+- [APIResource](../resource/api-resource.md)
+- [SQLResource](../resource/sql-resource.md)

package/dist/ai/docs/runjs/context/libs.md

@@ -0,0 +1,109 @@
+# ctx.libs
+
+`ctx.libs` is the unified namespace for RunJS built-in libraries (React, Ant Design, dayjs, lodash, etc.). **No `import` or async loading**; use `ctx.libs.xxx` directly.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock / JSField / JSItem / JSColumn** | React + Ant Design for UI, dayjs for dates, lodash for data |
+| **Formulas / calculations** | formula or math for Excel-like formulas and math expressions |
+| **Event flow / linkage** | lodash, dayjs, formula, etc. in logic-only code |
+
+## Built-in libraries
+
+| Property | Description | Docs |
+|----------|-------------|------|
+| `ctx.libs.React` | React core for JSX and Hooks | [React](https://react.dev/) |
+| `ctx.libs.ReactDOM` | ReactDOM (e.g. `createRoot`) | [React DOM](https://react.dev/reference/react-dom) |
+| `ctx.libs.antd` | Ant Design (Button, Card, Table, Form, Input, Modal, etc.) | [Ant Design](https://ant.design/components/overview/) |
+| `ctx.libs.antdIcons` | Ant Design icons (PlusOutlined, UserOutlined, etc.) | [@ant-design/icons](https://ant.design/components/icon/) |
+| `ctx.libs.dayjs` | Date/time utilities | [dayjs](https://day.js.org/) |
+| `ctx.libs.lodash` | Utilities (get, set, debounce, etc.) | [Lodash](https://lodash.com/docs/) |
+| `ctx.libs.formula` | Excel-like formulas (SUM, AVERAGE, IF, etc.) | [Formula.js](https://formulajs.info/functions/) |
+| `ctx.libs.math` | Math expressions and evaluation | [Math.js](https://mathjs.org/docs/) |
+
+## Top-level aliases
+
+For backward compatibility, some libs are also on `ctx`: `ctx.React`, `ctx.ReactDOM`, `ctx.antd`, `ctx.dayjs`. **Prefer `ctx.libs.xxx`** for consistency and docs.
+
+## Lazy loading
+
+`lodash`, `formula`, `math` are **lazy-loaded**: the first access to `ctx.libs.lodash` triggers a dynamic import, then the result is cached. `React`, `antd`, `dayjs`, `antdIcons` are preloaded in context.
+
+## Examples
+
+### React and Ant Design
+
+```tsx
+const { Button, Card } = ctx.libs.antd;
+
+ctx.render(
+  <Card title="Title">
+    <Button type="primary">Click</Button>
+  </Card>
+);
+```
+
+### Hooks
+
+```tsx
+const { React } = ctx.libs;
+const { useState } = React;
+const { Button } = ctx.libs.antd;
+
+const App = () => {
+  const [count, setCount] = useState(0);
+  return <Button onClick={() => setCount((c) => c + 1)}>{count}</Button>;
+};
+ctx.render(<App />);
+```
+
+### Icons
+
+```tsx
+const { Button } = ctx.libs.antd;
+const { UserOutlined, HeartOutlined } = ctx.libs.antdIcons;
+
+ctx.render(<Button icon={<UserOutlined />}>User</Button>);
+```
+
+### dayjs
+
+```ts
+const now = ctx.libs.dayjs();
+const formatted = now.format('YYYY-MM-DD HH:mm:ss');
+ctx.message.info(formatted);
+```
+
+### lodash
+
+```ts
+const user = { profile: { name: 'Alice' } };
+const name = ctx.libs.lodash.get(user, 'profile.name', 'Unknown');
+```
+
+### formula
+
+```ts
+const values = [1, 2, 3, 4];
+const sum = ctx.libs.formula.SUM(values);
+const avg = ctx.libs.formula.AVERAGE(values);
+```
+
+### math
+
+```ts
+const result = ctx.libs.math.evaluate('2 + 3 * 4');
+// result === 14
+```
+
+## Notes
+
+- **Mixing with ctx.importAsync**: If you load external React via `ctx.importAsync('react@19')`, JSX uses that instance; **do not** mix with `ctx.libs.antd`. Load antd for that React version (e.g. `ctx.importAsync('antd@5.x')`, `ctx.importAsync('@ant-design/icons@5.x')`).
+- **Multiple React instances**: "Invalid hook call" or null hook dispatcher usually means multiple React instances. Before using `ctx.libs.React` or Hooks, run `await ctx.importAsync('react@version')` so the same React as the page is used.
+
+## Related
+
+- [ctx.importAsync()](./import-async.md): load external ESM (e.g. specific React, Vue)
+- [ctx.render()](./render.md): render into container

package/dist/ai/docs/runjs/context/location.md

@@ -0,0 +1,85 @@
+# ctx.location
+
+Current route location, equivalent to React Router’s `location`. Use with `ctx.router` and `ctx.route` to read pathname, search, hash, and state passed via navigation.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock / JSField** | Conditional render or logic based on path, query, or hash |
+| **Linkage / event flow** | Read URL params for filtering or use `location.state` for source |
+| **After navigation** | On target page, read `ctx.location.state` from `ctx.router.navigate` |
+
+> Note: `ctx.location` is only available in RunJS when a router context exists (e.g. JSBlock on a page, event flow); in pure backend or non-routed contexts (e.g. workflow) it may be empty.
+
+## Type
+
+```ts
+location: Location;
+```
+
+`Location` is from `react-router-dom`, same as `useLocation()`.
+
+## Common Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `pathname` | `string` | Current path, leading `/` (e.g. `/admin/users`) |
+| `search` | `string` | Query string, leading `?` (e.g. `?page=1&status=active`) |
+| `hash` | `string` | Hash fragment, leading `#` (e.g. `#section-1`) |
+| `state` | `any` | Data passed via `ctx.router.navigate(path, { state })`; not in URL |
+| `key` | `string` | Unique key for this location; initial page is `"default"` |
+
+## Relation to ctx.router, ctx.urlSearchParams
+
+| Use | Recommended |
+|-----|-------------|
+| **Path, hash, state** | `ctx.location.pathname` / `ctx.location.hash` / `ctx.location.state` |
+| **Query params as object** | `ctx.urlSearchParams` |
+| **Parse search** | `new URLSearchParams(ctx.location.search)` or `ctx.urlSearchParams` |
+
+`ctx.urlSearchParams` is derived from `ctx.location.search`; use it when you only need query params.
+
+## Examples
+
+### Branch by path
+
+```ts
+if (ctx.location.pathname.startsWith('/admin/users')) {
+  ctx.message.info('On user management page');
+}
+```
+
+### Parse query params
+
+```ts
+const page = ctx.urlSearchParams.page || 1;
+const status = ctx.urlSearchParams.status;
+
+const params = new URLSearchParams(ctx.location.search);
+const page = params.get('page') || '1';
+const status = params.get('status');
+```
+
+### Read state from navigation
+
+```ts
+const prevState = ctx.location.state;
+if (prevState?.from === 'dashboard') {
+  ctx.message.info('Navigated from dashboard');
+}
+```
+
+### Anchor by hash
+
+```ts
+const hash = ctx.location.hash;
+if (hash === '#edit') {
+  // Scroll to edit or run logic
+}
+```
+
+## Related
+
+- [ctx.router](./router.md): navigation; `state` from `ctx.router.navigate` is available as `ctx.location.state`
+- [ctx.route](./route.md): current route match (params, config); use with `ctx.location`