mirror of
https://github.com/elastic/kibana.git
synced 2025-04-24 17:59:23 -04:00
1ff181c5df
Closes https://github.com/elastic/kibana/issues/191306 ## Summary This PR updates the collision resolution algorithm to handle the edge case described in the linked issue. In the old algorithm, we checked each panel for collisions a **single time** - however, this caused a bug where panels could get re-ordered depending on the order that we pushed panels down + how much distance we were pushing them down by. While this algorithm was extremely efficient (approximately $`O \left({ { n^2 + n } \over 2 }\right)`$ before compaction where `n` is the number of panels), it was not as simple as "fixing" the bug because, no matter what, there was always an edge case that could not be handled without adding some sort of backtracking - instead, we had to come up with a new algorithm. ### Example of Edge Case To better understand how the old and new algorithms compare (and how they work), consider a scenario where the grid layout has 8 columns and the panels are laid out as follows:  Now, what happens when panel 4 (yellow) is dragged to the left so that it overlaps both panel 3 (red) and panel 4 (blue)? <details> <summary><b>Old Algorithm</b></summary> With the old algorithm, we get the following behaviour:  This is because we are **only** pushing the collided panels down **once**. So, to describe what happens in detail, we start by gathering up the panels **in order** (top-bottom, left-right, where dragged panels take priority when rows are equal) - this results in an order of `[panel4, panel3, panel1, panel2]`. We start checking for collisions in this order - starting with panel 4 (yellow), we determine that it is colliding with panel 3 (red) and panel 2 (blue). We start with panel 3 (since we are once again doing this "in order"), and we push it down by 5 rows (since this is the overlap of the panel 3 and panel 4). Then, to "resolve" the second collision with panel 4, we push down panel 2 by 3 rows. This leaves the layout in the following state:  Now, since panel 4 (yellow) is "resolved", we move on to the next panel in the `[panel4, panel3, panel1, panel2]` order - panel 3 (red). Panel 3 now collides with panel 2, so we push panel 2 down by two rows. This is the only collision with panel 3, so we check panel 1 and panel 2, neither of which report collisions at this point. So the layout ends in the following state:  So, what's the problem here? Well, panel 1 (green) is now "out of sync" with the old panel ordering because it got "left behind" in the collision resolution. Instead, we should have moved panel 1 by the same amount as panel 2. </details> <details> <summary><b>New Algorithm</b></summary> With the new algorithm, we get the expected behaviour:  If we run through the algorithm, we identify that the **first** collision in the layout (based on left to right, top to bottom ordering, with priority being the panel being dragged) is panel 4 (yellow) - so, we enter the `while` loop and recurse to resolve all collisions with panel 4 via `resolvePanelCollisions`. The recursion within `resolvePanelCollisions` works as follows - get **all** collisions with panel 4 (which, at this point, returns panel 3 (red) and panel 2 (blue)) and push them down by a single row, then recurse on **those** panels to resolve any of the resulting collisions. It's difficult to describe recursion, but let me try my best :) During the collision resolution on panel 4, we start by pushing panel 3 down and then recursively resolving the collisions on panel 3. Since pushing panel 3 causes collisions with panel 1 and 2 (in order), we push them both down by one row - starting with panel 1. We recurse to resolve the collisions on panel 1, which has no collisions - then we do the same for panel 2, which also reports no collisions. The collisions with panel 3 are "resolved" (i.e. we can "back out" of the recursion on panels 1 and 2), so we go back to resolving panel 4, push panel **2** down, and then resolve the collisions on panel 2 - which reports no collisions. In summary:  Therefore, after the first iteration of the `while` loop, this results in the following layout, where panel 3 (red) has been pushed down by one row, panel 1 (green) has been pushed down by one row, and panel 2 (blue) has been pushed down by two rows:  We then return to the `while` loop and check if the layout has any other collisions - and panel 4 is still our "first" collision! So we repeat the process above and push both panel 4 and panel 2 down and recurse to resolve the resulting collisions on those panels. This continues as follows: | Steps | Resulting Layout | |--------|--------| | <img width="400" src="https://github.com/user-attachments/assets/d2691a1c-5f0b-4333-bfd4-3cc57e1a3098"/> | <img width="400" src="https://github.com/user-attachments/assets/85325df3-7fbf-46fa-af98-10bbd883cf8d"/> | | <img width="400" src="https://github.com/user-attachments/assets/e31a400f-d0d1-408d-baec-efa708ad0c52"/> | <img width="400" src="https://github.com/user-attachments/assets/c81762d4-443b-451c-b8fc-dabaf4e32ba1"/> | | <img width="400" src="https://github.com/user-attachments/assets/4292e4a9-4157-4d77-9b69-b0f6a07338ac"/> | <img width="400" src="https://github.com/user-attachments/assets/bdd2dad5-6531-4d56-b8c2-dfb121fb6b5b"/> | | <img width="400" src="https://github.com/user-attachments/assets/6d194a89-3ed6-46a6-9dcc-2b3fa0de9942"/> | <img width="400" src="https://github.com/user-attachments/assets/7e0b0fb5-bacb-49ad-ac86-02665a779b59"/> | And so, after our fifth iteration of the `while` loop, the layout is **no longer** reporting collisions - so, our layout is now fully resolved! </details> ### Performance Comparison This algorithm is more-or-less the same as the algorithm used in `react-grid-layout` - however, instead of running on **every frame**, our layout engine only resolves collisions **as they happen** (hence why the while loop is necessary). This results in much better rendering performance. To test this, I opened the Logs sample dashboard in both the example app (which is obviously using `kbn-grid-layout`) and Dashboard (which is still using `react-grid-layout`) and performed various drag actions on both while recording their performance. For example, consider the following capture of a drag that doesn't cause **any** collisions: | `kbn-grid-layout` | `react-grid-layout` | |--------|--------| |  |  | You can see that, even with no collisions, the performance is slightly better with `kbn-grid-layout` because we don't **ever** recurse on collisions in this scenario. But it gets even better when actual collisions happen - for example, consider the performance when the dragged panel only causes a **single** collision: | `kbn-grid-layout` | `react-grid-layout` | |--------|--------| |  |  | Versus when the dragged panel causes multiple collisions at the top of the dashboard that causes a chain reaction of panels needing to be pushed down: | `kbn-grid-layout` | `react-grid-layout` | |--------|--------| |  |  | In all of the above scenarios, performance is improved overall **and** there are fewer red "spikes" / bottlenecks due to [forced reflow](https://web.dev/articles/avoid-large-complex-layouts-and-layout-thrashing?utm_source=devtools#avoid-forced-synchronous-layouts) along the way. Most of the time saved is caused by significant reductions to both `rendering` and `painting` time in `kbn-grid-layout` when compared to `react-grid-layout`. While some of this improvement may be explained by differences in the example grid plugin versus the Dashboard plugin, this is enough proof that performance of `kbn-grid-layout` is **at least as good as** `react-grid-layout` and so swapping out the layout engine should not cause any performance regressions. ### Other Notable Algorithm Attempts I tried a few **drag/resize event specific** algorithms that **only work** when an interaction event is happening - i.e. they rely on information from the panel that is being interacted with in order to function. Note that, if we decided to go this route, we would still need some generic collision resolution algorithm (such as the one proposed in this PR) that we could use to resolve a layout when **no** interaction event is happening. After all, we cannot assume that the grid layout that is sent as a prop is valid (i.e. it **could** have overlapping panels **at the start**, before any dragging and/or resizing has occurred) and we need a way to verify + resolve it. Unfortunately, both of the "interaction-event necessary" collision resolution algorithms that I tried suffered from bugs so, while it might be **possible** to make a more efficient algorithm for this, I ultimately threw them away in favour of using the "generic" collision resolution algorithm proposed in this PR. That being said, I figured it was worth documenting the things that I tried and why they failed. <details> <summary><b>Algorithm 1</b></summary> I tried a modification of the **original** collision resolution algorithm where, instead of **just** moving the colliding panels down by the `rowOverlap` amount, we move **all** panels in or below the targeted grid row down by the **height** of the panel being dragged. However, due to the compaction algorithm ignoring **all** panels that have collisions, you can end up in an infinite "push panels down" loop like so:  This is because panel 3 is **always** colliding with panel 1 and 4, so they never get pushed up to "close" the gaps. To try and get around this, I modified the collision detection used for panel compaction so that collisions only "stop" compaction if the collision occurs on a panel **above** the given panel we are trying to compact. However, this caused a **different** bug:  In the above GIF, consider what happens when panel 3 (red) targets row 3. As expected, we move all other panels (1, 2, and 4) down by a single row. Then, when we reach the compaction step, we start by trying to push panel 1 up (since it is now the top-left-most panel) - and, since we are filtering out the collision with panel 3 (since it occurs "below" panel 1), it gets pushed all the way to the top. Then, we push panel 4 all the way to the top (because it is also ignoring the collision with panel 3), followed by pushing panel 2 up until it would collide with panel 3. Unfortunately though, we didn't account for the full height of panel 4 - so panel 3 is now stuck colliding with panel 4. I modified this algorithm **further** to move the panels down by the "row overlap" with the dragged panel rather than the dragged panel's height - but this also suffers from a bug:  At which point, I abandoned this approach becase it felt like there were too many edge cases that could not all be accounted for. It's possible we could explore this further but, given the limitations of this algorithm **only working** for resolving collisions given an interaction event, I opted to move on. </details> <details> <summary><b>Algorithm 2</b></summary> I tried an algorithm where, similar to the algorithm proposed in this PR, I recorded the panel IDs in each cell that a given panel occupied - however, instead of moving things down row by row and handling the resulting collisions, we moved **every** panel that was **below** the targetted row down by the **height** of the panel being dragged. In theory, the compaction algorithm would then take control of closing all the resulting gaps. Unfortunately, this didn't quite work in practice. Consider the following:  According to the algorithm defined above, panel 2 (blue) and panel 4 (yellow) both need to move down when panel 3 (red) is dragged to target row 4 (remember that row **zero** is the first row), since they both occupy this row - so we push both of them down by 1 (the height of panel 3). However, once we start compacting the layout in order to finish our collision resolution, we hit a snag with panel 4 (yellow) - when we start trying to compact panel 4, `getAllCollisionsWithPanel` returns that **panel 3** is colliding with panel 4 and so we **break out** of the compaction - hence why panel 4 continues to float. This then has a snowball effect on all other panels as they report collisions and therefore do not get pushed up. </details> <details> <summary><b>Algorithm 3</b></summary> This was the algorithm we **almost** went with, because it works! But it suffered from two things - one, the code was complicated and difficult to maintain and two, the collision resolution behaviour felt less natural because it **always** favoured the dragged panel. This made it too sensitive to pushing items down; so even if a panel was targeting the bottom row of a different panel, it would push that panel down to make room for the dragged panel. In the simplest terms, this algorithm worked as follows: after creating a 3D array representing the current grid (a 2D array of panel ID arrays), for each row, while there are collisions, push panels down in **reverse order** (bottom right to top left); continue until all rows have no collisions. This algorithm hd an efficiency of approximately $`O\left(r * c \right)`$ to set up the 3D array and $`O \left( c * h * n \right)`$ to resolve the conflicts, where `r` is the number of rows, `c` is the number of columns (minus 1), `h` is the height of the dragged panel, and `n` is the number of panels. This results in an overall speed of about $`O \left( (r * c) + (c * h * n) \right)`$ To better understand how this algorithm works, consider how it handles the edge case described above: <details> <summary>Algorithm 3 - Edge Case Example</summary> Rather than checking every **panel** for collisions a single time, we check and resolve each **row** for collisions and resolve them. This gives the following behaviour:  We start by creating a 3D array representing the grid - at the **first** point of collision, it looks like: | | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | |--------|--------|--------|--------|--------|--------|--------|--------|--------| | **0** | `[panel3]` | `[panel3]` | `[panel3]` | `[panel3, panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **1** | `[panel3]` | `[panel3]` | `[panel3]` | `[panel3, panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **2** | `[panel1]` | `[panel1]` | `[panel2]` | `[panel2, panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **3** | `[panel1]` | `[panel1]` | `[panel2]` | `[panel2, panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **4** | `[panel1]` | `[panel1]` | `[panel2]` | `[panel2, panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | Then, we start checking and resolving collisions, row by row. Starting with row 0, we see that column 3 has a collision between panel 3 and panel 4 - we **ignore** the panel being dragged (panel 4), so we push down panel 3 by one row. Row 0 has no more collisions, so we move on to row 1 and, following the same logic as above, we push down panel 3 again. This leaves the grid in the following state:  | | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | |--------|--------|--------|--------|--------|--------|--------|--------|--------| | **0** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **1** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **2** | `[panel1, panel3]` | `[panel1, panel3]` | `[panel2, panel3]` | `[panel3, panel2, panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **3** | `[panel1, panel3]` | `[panel1, panel3]` | `[panel2, panel3]` | `[panel3, panel2, panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **4** | `[panel1]` | `[panel1]` | `[panel2]` | `[panel2, panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | Now, on row 2, we have collisions in columns zero through three, so we push the panels in **reverse order** (i.e from the bottom right to the top left) - this results in pushing panel 2 down, then panel 1, and finally panel 3. We have to add a row in order to accomplish this because otherwise we "lose" the bottom of panel 2, so our layout now looks like this and row 2 has no more collisions:  | | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | |--------|--------|--------|--------|--------|--------|--------|--------|--------| | **0** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **1** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **2** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **3** | `[panel1, panel3]` | `[panel1, panel3]` | `[panel2, panel3]` | `[panel3, panel2, panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **4** | `[panel1, panel3]` | `[panel1, panel3]` | `[panel2, panel3]` | `[panel3, panel2, panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **5** | `[panel1]` | `[panel1]` | `[panel2]` | `[panel2]` | `[]` | `[]` | `[]` | `[]` | Continuing this behaviour, we push panel 2, panel 1, and panel 3 down in row 3; then again in row 4. Once we reach and resolve row 5 (i.e. get row 5 to the point where there are no collisions with panel 3), our layout looks like so:  | | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | |--------|--------|--------|--------|--------|--------|--------|--------|--------| | **0** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **1** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **2** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **3** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **4** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **5** | `[panel3]` | `[panel3]` | `[panel3]` | `[panel3]` | `[]` | `[]` | `[]` | `[]` | | **6** | `[panel3, panel1]` | `[panel3, panel1]` | `[panel2, panel3]` | `[panel2, panel3]` | `[]` | `[]` | `[]` | `[]` | | **7** | `[panel1]` | `[panel1]` | `[panel2]` | `[panel2]` | `[]` | `[]` | `[]` | `[]` | | **8** | `[panel1]` | `[panel1]` | `[panel2]` | `[panel2]` | `[]` | `[]` | `[]` | `[]` | At this point, all collisions on panel 4 have been resolved. So, in row 6, we see that panels 2 and 1 are now colliding with panel 3 - so, we push both of them down. At that point, row 6 does not have collisions so we **don't** push panel 3 down any further - and our layout is resolved!  | | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | |--------|--------|--------|--------|--------|--------|--------|--------|--------| | **0** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **1** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **2** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **3** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **4** | `[]` | `[]` | `[]` | `[panel4]` | `[panel4]` | `[panel4]` | `[panel4]` | `[]` | | **5** | `[panel3]` | `[panel3]` | `[panel3]` | `[panel3]` | `[]` | `[]` | `[]` | `[]` | | **6** | `[panel3]` | `[panel3]` | `[panel3]` | `[panel3]` | `[]` | `[]` | `[]` | `[]` | | **7** | `[panel1]` | `[panel1]` | `[panel2]` | `[panel2]` | `[]` | `[]` | `[]` | `[]` | | **8** | `[panel1]` | `[panel1]` | `[panel2]` | `[panel2]` | `[]` | `[]` | `[]` | `[]` | | **9** | `[panel1]` | `[panel1]` | `[panel2]` | `[panel2]` | `[]` | `[]` | `[]` | `[]` | </details> </details> ### Checklist - [x] [Unit or functional tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html) were updated or added to match the most common scenarios - [x] The PR description includes the appropriate Release Notes section, and the correct `release_note:*` label is applied per the [guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process) ### Identify risks There are no risks to this PR, since all work is contained in the `examples` plugin. --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> |
||
|---|---|---|
| .. | ||
| analytics/utils/analytics_collection_utils | ||
| cloud | ||
| content-management | ||
| core | ||
| deeplinks/shared | ||
| home | ||
| kbn-ambient-common-types | ||
| kbn-ambient-ftr-types | ||
| kbn-ambient-storybook-types | ||
| kbn-ambient-ui-types | ||
| kbn-analytics | ||
| kbn-apm-config-loader | ||
| kbn-apm-synthtrace | ||
| kbn-apm-synthtrace-client | ||
| kbn-axe-config | ||
| kbn-babel-preset | ||
| kbn-babel-register | ||
| kbn-babel-transform | ||
| kbn-bazel-runner | ||
| kbn-calculate-auto | ||
| kbn-calculate-width-from-char-count | ||
| kbn-capture-oas-snapshot-cli | ||
| kbn-chart-icons | ||
| kbn-charts-theme | ||
| kbn-check-mappings-update-cli | ||
| kbn-check-prod-native-modules-cli | ||
| kbn-ci-stats-core | ||
| kbn-ci-stats-performance-metrics | ||
| kbn-ci-stats-reporter | ||
| kbn-ci-stats-shipper-cli | ||
| kbn-cli-dev-mode | ||
| kbn-code-owners | ||
| kbn-coloring | ||
| kbn-config | ||
| kbn-config-mocks | ||
| kbn-config-schema | ||
| kbn-crypto | ||
| kbn-crypto-browser | ||
| kbn-cypress-config | ||
| kbn-data-service | ||
| kbn-dependency-ownership | ||
| kbn-dependency-usage | ||
| kbn-dev-cli-errors | ||
| kbn-dev-cli-runner | ||
| kbn-dev-proc-runner | ||
| kbn-dev-utils | ||
| kbn-docs-utils | ||
| kbn-dom-drag-drop | ||
| kbn-ebt-tools | ||
| kbn-es | ||
| kbn-es-archiver | ||
| kbn-es-errors | ||
| kbn-es-types | ||
| kbn-eslint-config | ||
| kbn-eslint-plugin-css | ||
| kbn-eslint-plugin-disable | ||
| kbn-eslint-plugin-eslint | ||
| kbn-eslint-plugin-i18n | ||
| kbn-eslint-plugin-imports | ||
| kbn-eslint-plugin-telemetry | ||
| kbn-event-annotation-common | ||
| kbn-event-annotation-components | ||
| kbn-expect | ||
| kbn-failed-test-reporter-cli | ||
| kbn-find-used-node-modules | ||
| kbn-formatters | ||
| kbn-ftr-common-functional-services | ||
| kbn-ftr-common-functional-ui-services | ||
| kbn-ftr-screenshot-filename | ||
| kbn-gen-ai-functional-testing | ||
| kbn-generate | ||
| kbn-generate-console-definitions | ||
| kbn-generate-csv | ||
| kbn-get-repo-files | ||
| kbn-grid-layout | ||
| kbn-guided-onboarding | ||
| kbn-handlebars | ||
| kbn-hapi-mocks | ||
| kbn-health-gateway-server | ||
| kbn-i18n | ||
| kbn-i18n-react | ||
| kbn-import-locator | ||
| kbn-import-resolver | ||
| kbn-interpreter | ||
| kbn-io-ts-utils | ||
| kbn-item-buffer | ||
| kbn-jest-serializers | ||
| kbn-journeys | ||
| kbn-json-ast | ||
| kbn-kibana-manifest-schema | ||
| kbn-lens-formula-docs | ||
| kbn-lint-packages-cli | ||
| kbn-lint-ts-projects-cli | ||
| kbn-logging | ||
| kbn-logging-mocks | ||
| kbn-managed-content-badge | ||
| kbn-managed-vscode-config | ||
| kbn-managed-vscode-config-cli | ||
| kbn-management | ||
| kbn-manifest | ||
| kbn-mock-idp-plugin | ||
| kbn-mock-idp-utils | ||
| kbn-monaco | ||
| kbn-object-versioning | ||
| kbn-object-versioning-utils | ||
| kbn-openapi-bundler | ||
| kbn-openapi-generator | ||
| kbn-optimizer | ||
| kbn-optimizer-webpack-helpers | ||
| kbn-palettes | ||
| kbn-peggy | ||
| kbn-peggy-loader | ||
| kbn-performance-testing-dataset-extractor | ||
| kbn-picomatcher | ||
| kbn-plugin-check | ||
| kbn-plugin-generator | ||
| kbn-plugin-helpers | ||
| kbn-react-mute-legacy-root-warning | ||
| kbn-recently-accessed | ||
| kbn-relocate | ||
| kbn-repo-file-maps | ||
| kbn-repo-linter | ||
| kbn-repo-path | ||
| kbn-repo-source-classifier | ||
| kbn-repo-source-classifier-cli | ||
| kbn-reporting | ||
| kbn-router-to-openapispec | ||
| kbn-safer-lodash-set | ||
| kbn-saved-objects-settings | ||
| kbn-saved-search-component | ||
| kbn-scout | ||
| kbn-scout-info | ||
| kbn-scout-reporting | ||
| kbn-screenshotting-server | ||
| kbn-security-hardening | ||
| kbn-server-http-tools | ||
| kbn-set-map | ||
| kbn-shared-ux-utility | ||
| kbn-some-dev-log | ||
| kbn-sort-package-json | ||
| kbn-sort-predicates | ||
| kbn-std | ||
| kbn-stdio-dev-helpers | ||
| kbn-storybook | ||
| kbn-telemetry-tools | ||
| kbn-test | ||
| kbn-test-eui-helpers | ||
| kbn-test-jest-helpers | ||
| kbn-test-subj-selector | ||
| kbn-timelion-grammar | ||
| kbn-tinymath | ||
| kbn-tooling-log | ||
| kbn-transpose-utils | ||
| kbn-ts-projects | ||
| kbn-ts-type-check-cli | ||
| kbn-ui-actions-browser | ||
| kbn-use-tracked-promise | ||
| kbn-user-profile-components | ||
| kbn-utility-types | ||
| kbn-validate-next-docs-cli | ||
| kbn-visualization-ui-components | ||
| kbn-visualization-utils | ||
| kbn-web-worker-stub | ||
| kbn-whereis-pkg-cli | ||
| kbn-yarn-lock-validator | ||
| kbn-zod | ||
| react | ||
| response-ops | ||
| serverless | ||
| shared-ux | ||
| README.md | ||
Kibana-related packages
This folder contains packages that are intended for use in Kibana and Kibana plugins.
tl;dr:
- Don't publish to npm registry
- Always use the
@kbnnamespace - Always set
"private": trueinpackage.json
Using these packages
We no longer publish these packages to the npm registry. Now, instead of specifying a version when including these packages, we rely on yarn workspaces, which sets up a symlink to the package.
For example if you want to use the @kbn/i18n package in Kibana itself, you
can specify the dependency like this:
"@kbn/i18n": "1.0.0"
However, if you want to use this from a Kibana plugin, you need to use a link:
dependency and account for the relative location of the Kibana repo, so it would
instead be:
"@kbn/i18n": "link:../../kibana/packages/kbn-i18n"
then run yarn kbn bootstrap from the plugin directory.
Creating a new package
Run the following command from the root of the Kibana repo:
node scripts/generate package @kbn/<PACKAGE_NAME> --web --owner @elastic/<TEAM_NAME>
Unit tests for a package
Currently there is only one tool being used in order to test packages which is Jest. Below we will explain how it should be done.
Jest
A package should follow the pattern of having .test.js files as siblings of the source code files, and these run by Jest.
A package using the .test.js naming convention will have those tests automatically picked up by Jest and run by the unit test runner, currently mapped to the Kibana test script in the root package.json.
yarn testruns all unit tests.yarn jestruns all Jest tests in Kibana.
In order for the plugin or package to use Jest, a jest.config.js file must be present in it's root. However, there are safeguards for this in CI should a test file be added without a corresponding config file.
Each package can also specify its own test script in the package's package.json, for cases where you'd prefer to run the tests from the local package directory.