@discoveryjs/discovery/lib/pages/views-showcase/intro-web-render-md.d.ts

Frontend framework for rapid data (JSON) analysis, shareable serverless reports and dashboards

declare const _default: "\n## Working with views\n\nIn Discovery.js, presentations are organized as a tree of views. Views are defined using object notation, where the `view` property specifies the type, and additional properties allow further customization.\n\n```discovery-view\n{\n    view: \"view-name\"\n}\n```\n\nA view definition takes `data` and `context` values, which can be used to define properties and control rendering. Views can transform data and context (using the `data` and `context` properties) for use by the view and its descendant views, enabling clear data flow. Views are rendered by calling the render method:\n\n```js\ndiscovery.render(containerEl, viewDefinition, data, context)\n```\n\nDiscovery.js is designed to be declarative. For dynamic calculations or event handling, [jora](https://discoveryjs.github.io/jora/) queries are preferred over JavaScript functions.\n\nEach view can use the following properties:\n\n- `view` (required) \u2014 Specifies the view type.\n- `when` \u2014 Controls whether the view should be rendered. Evaluated before `data` transformation.\n- `context` \u2014 Transforms the input context for the view and its nested views.\n- `data` \u2014 Transforms the input data for the view and its nested views.\n- `whenData` \u2014 Controls rendering based on the computed `data`. Evaluated after `context` and `data` are set.\n- `className` \u2014 Adds CSS class name(s) to the root element of the view (see [ClassName](#!classname)).\n- `postRender` \u2014 A function executed after rendering the view but before placing it in the DOM.\n- `tooltip` \u2014 Sets up a tooltip for the view (only applicable to views with a container element, see [Tooltips](#!tooltips)).\n\nThe sequence of property evaluation during rendering (view render lifecycle):\n\n```\n[start]               render(data, context)\n \\                          |     |\n  * when()                  |     | stop rendering when value is falsy\n  |\\                        |     |\n  | * context() ------------|-----* (async) replace `context` with new value\n  |  \\                      |     |\n  |   * data() -------------*     | (async) replace `data` with new value\n  |    \\                    |     |\n  |     * whenData()        |     | stop rendering when value is falsy\n  |     |\\                  |     |\n  |     | * (render)        |     | (async) main render logic\n  |     |  \\                |     |\n  |     |   * postRender()  |     | do something once (render) is done\n  |     |    \\              |     |\n  |     |     * className() |     | compute className and apply to root element\n  |     |      \\            V     V\n  +-----+-----> * [finish render]\n```\n\n- `context` and `data` \u2014 Modify the flow of context or data based on the provided value:\n  - **String** \u2014 Treated as a jora query, and its result is used.\n  - **Function** (`fn(data, context)`) \u2014 The result of the function invocation is used.\n  - **Other values** \u2014 Directly used as a new value for data or context.\n- `when` and `whenData` \u2014 Determine if a view should be rendered:\n  - **String** \u2014 Treated as a jora query.\n  - `true` \u2014 Evaluated as an empty query, meaning the data itself is tested for truthiness.\n  - `undefined` \u2014 Treated as not specified, allowing rendering.\n  - **Function** (`fn(data, context)`) or other values \u2014 Evaluated for truthiness.\n  > Note: In jora, empty arrays and objects with no own keys are falsy, unlike JavaScript where they are truthy.\n\n```discovery-view\n{\n    view: 'list',\n    data: 'some.list.sort(name asc)', // Fetch an array for the list view, based on current data\n    whenData: 'size() > 0',  // Check if the array has elements, skip rendering if empty\n    item: 'text:name' // Render each element as text, displaying the name\n}\n```\n\n## Computable property values\n\nIf a property starts with `=`, it indicates a jora query used to compute the property's value before a rendering.\n\n```discovery-view\n{\n    view: 'list',\n    limit: '=size() <= 12 ? false : 10' // Dynamically computes the limit based on flow data\n}\n```\n\n> To pass a literal string that starts with `=`, use a query like `'=\"=some string\"'`.\n\n## Shorthand notations\n\nDiscovery.js supports shorthand notations for defining views, making the configuration more concise:\n\n| Shorthand notation                      | Expanded form                                      |\n| --------------------------------------- | -------------------------------------------------- |\n| `'name'`                                | `{ view: 'name' }`                                 |\n| `'name:<query>'`                        | `{ view: 'name', data: '<query>' }`                |\n| `'name{ foo: size() / 2, bar: \"qux\" }'` | `{ view: 'name', foo: '=size() / 2', bar: 'qux' }` |\n\n## Lists of views\n\nMultiple views can be combined into a list using an array:\n\n```discovery-view\n{\n    view: 'list',\n    item: [ // render two views as a content of a list item\n        'text:name',\n        { view: 'badge', data: 'something.size()' }\n    ]\n}\n```\n\n## ClassName\n\nThe `className` property uses a sequence of transformations to convert its input into a final array of class names. This process can start from different input forms \u2014 such as a jora query, a function, a string, or an array \u2014 and move through each step until a definitive result is obtained. At each stage, the current value is examined and transformed if applicable; if not, the process continues to the next step:\n\n1. **Jora Query (String Starting with `=`)**  \n   If the initial value begins with `=`, it is treated as a jora query and compiled into a function. That function is then processed as described in the next step.\n\n   ```discovery-view\n   {\n       view: \"text\",\n       className: \"=isValid ? 'valid' : 'invalid'\"\n   }\n   ```\n   <br>\n\n2. **Function**  \n   Once a function is available (either provided directly or obtained from a jora query) it is called with `(data, context)`. The return value can be a string or an array, otherwise discarded.\n\n   ```discovery-view\n   {\n       view: \"text\",\n       className: (data, context) => data.flag ? \"highlighted\" : null\n   }\n   ```\n   <br>\n\n3. **String**  \n   Any string (obtained from the previous steps or provided directly) is trimmed and split by whitespace to produce an array of class names, excluding empty entries.\n\n   ```discovery-view\n   {\n       view: \"text\",\n       className: \"primary emphasized\"\n   }\n   ```\n   <br>\n\n4. **Array**  \n   When the value is or becomes an array, each element is processed:\n   - If an element is a function, it is called with `(data, context)` and its result replaces the function.\n   - All falsy or empty results are removed.\n\n   ```discovery-view\n   {\n       view: \"text\",\n       className: [\n           \"base-class\",\n           data => data.error && \"error-indicator\",\n           \"\"\n       ]\n   }\n   ```\n\n   If `data.error` is true, this may result in `class=\"base-class error-indicator\"`. If `data.error` is false, the array would become `[\"base-class\", false, \"\"]`, and after filtering out falsy and empty values, it results in `class=\"base-class\"`.\n\nIf, after all steps, there are no valid class names, the `class` attribute is not applied. This cascading process ensures any initial input \u2014 jora query, function, string, or array \u2014 is consistently transformed into a meaningful final list of class names.\n\n## Tooltips\n\nTooltips can be configured using a simple view definition or an object with additional settings. When the `tooltip` value is a view definition, it becomes the `content` of the tooltip.\n\n```discovery-view\n{\n    view: 'button',\n    tooltip: 'md:\"Some **content**\"'\n}\n```\n\n```discovery-view\n{\n    view: 'button',\n    tooltip: {\n        position: 'trigger',\n        content: 'md:\"Some **content**\"'\n    }\n}\n```\n\n| Tooltip value                     | Normalized tooltip config                      |\n| --------------------------------- | ---------------------------------------------- |\n| `'shorthand-view-notation'`       | `{ content: 'shorthand-view-notation' }`       |\n| `{ view: 'name', ... }`           | `{ content: { view: 'name', ... } }`           |\n| `['view', { view: 'name', ... }]` | `{ content: ['view', { view: 'name', ... }] }` |\n\nTooltip options:\n\n- `className` \u2014 Additional class names for the tooltip element.\n- `position` \u2014 Where the tooltip is positioned. Options are `'trigger'` or `'pointer'` (default).\n- `positionMode` \u2014 Positioning mode. Options are `'natural'` (default) or `'safe'`.\n- `pointerOffsetX` \u2014 Horizontal offset from the pointer (default: 3).\n- `pointerOffsetY` \u2014 Vertical offset from the pointer (default: 3).\n- `hideOnTriggerClick` \u2013 Hide the tooltip when click a trigger element.\n- `showDelay` \u2014 Delay before showing the tooltip. Options are `true` (300ms, default), `false` (0ms), a number, or a function that returns a boolean or numeric value.\n- `content` \u2014 View configuration for tooltip content.\n";
export default _default;