docs-lens-chart-settings

<!-- Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. Elasticsearch B.V. licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> # Verifying Kibana Lens Chart Settings from Source Code When documenting Lens chart settings, always verify labels, options, and rendering order against the Kibana source code. Do NOT guess UI labels. ## Key Principles 1. **UI labels come from i18n `defaultMessage` strings** — always extract the exact label. 2. **Rendering order in JSX = rendering order in the UI** — document settings in the same order they appear in the component tree. 3. **Conditional rendering is everywhere** — many settings only appear under specific conditions (chart type, selected options, number of dimensions). Trace the conditions. 4. **Shared components are parameterized per chart** — the same `LegendSettings` component behaves differently for treemaps vs waffle vs pie based on props. ## Source Code Layout ### Partition charts (pie, donut, treemap, mosaic, waffle) All partition-type charts share code under: ``` x-pack/platform/plugins/shared/lens/public/visualizations/partition/ ├── partition_charts_meta.ts # Per-chart config (toolbar options, legend config) ├── toolbar/ │ ├── style_settings.tsx # Orchestrates Style panel sections │ ├── titles_and_text_settings.tsx # Slice labels + Slice values options │ ├── appearance_settings.tsx # Donut hole (pie/donut only) │ └── legend_settings.tsx # Partition-specific legend wrapper ``` Shared legend component: ``` x-pack/platform/plugins/shared/lens/public/shared_components/legend/ ├── legend_settings.tsx # Main legend settings (Visibility, Size, Truncation, Nested, Stats) ├── location/legend_location_settings.tsx # Position (only when `location` prop is defined) └── size/legend_size_settings.tsx # Width/Size dropdown ``` ### Other chart types Each chart type has its own directory under `visualizations/`: - `visualizations/xy/` for bar, line, area - `visualizations/heatmap/` - `visualizations/gauge/` - `visualizations/metric/` - `visualizations/tagcloud/` ## Verification Workflow ### Step 1: Find the chart metadata For partition charts, start with `partition_charts_meta.ts`. This file defines per-chart: - `toolbar.categoryOptions` — Slice labels options (or empty array if none) - `toolbar.numberOptions` — Slice values options (or empty array if none) - `toolbar.emptySizeRatioOptions` — Donut hole options (pie/donut only) - `toolbar.isDisabled` — Whether the Style panel is disabled entirely (waffle) - `legend.defaultLegendStats` — Enables Statistics/Show value in legend (waffle only) - `legend.hideNestedLegendSwitch` — Hides the Nested toggle (waffle) - `legend.getShowLegendDefault` — Default legend visibility behavior for Auto mode - `maxBuckets` — Maximum Group by dimensions ### Step 2: Trace the Style settings Read `toolbar/style_settings.tsx` to understand the Style panel structure: - If `emptySizeRatioOptions` exists → renders **Appearance** accordion + **Titles and text** accordion - If not → renders only `PartitionTitlesAndTextSettings` directly (no sub-headers) Then read `toolbar/titles_and_text_settings.tsx`: - `categoryOptions` renders as the first button group (label: check i18n key `xpack.lens.pieChart.labelSliceLabels`) - `numberOptions` renders as the second button group (label: check i18n key `xpack.lens.pieChart.sliceValues`) - If `numberDisplay === 'percent'`, a **Decimal places** input appears If `categoryOptions` is empty, the first button group is hidden. If `numberOptions` is empty, the second button group is hidden. If `isDisabled` is true, the entire section is disabled/hidden. ### Step 3: Trace the Legend settings Read `toolbar/legend_settings.tsx` (partition wrapper) to see what props are passed to the shared `LegendSettings` component. Key props to check: | Prop | What it controls | How to verify | |------|-----------------|---------------| | `legendOptions` | Visibility options (Auto/Show/Hide) | Always present for all partition charts | | `position` | Only renders if `location` is also passed | Partition charts do NOT pass `location` → Position hidden | | `renderNestedLegendSwitch` | Nested toggle | `!hideNestedLegendSwitch && groups > 1` | | `allowedLegendStats` | Statistics/Show value | Only if `defaultLegendStats` defined in chart meta | | `legendSize` / `onLegendSizeChange` | Width dropdown | Renders if `isVerticalLegend` is true | | `shouldTruncate` / `onTruncateLegendChange` | Label truncation toggle | Always present when legend not hidden | | `showAutoLegendSizeOption` | Auto in size dropdown | Only for pre-8.3 visualizations | ### Step 4: Determine rendering order Read the shared `legend_settings.tsx` JSX top to bottom. For partition charts (no `location` prop), the actual rendering order is: 1. **Visibility** (always) 2. **Width** (when legend not hidden, via LegendSizeSettings) 3. **Label truncation** + **Line limit** (when legend not hidden) 4. **Nested** (when legend not hidden AND multiple groups AND not hideNestedLegendSwitch) Settings that do NOT render for partition charts: - **Position** — requires `location` prop (only XY charts pass this) - **Statistics** — requires `allowedLegendStats.length > 1` - **Show value** — requires exactly 1 allowed legend stat of type Value/CurrentAndLastValue ### Step 5: Verify option labels For each button group or dropdown, check the `label` or `inputDisplay` in the options array. Common pitfalls: | What you might assume | Actual UI label | Source | |-----------------------|----------------|--------| | "Labels" | "Slice labels" | `xpack.lens.pieChart.labelSliceLabels` | | "Values" | "Slice values" | `xpack.lens.pieChart.sliceValues` | | "Legend size" | "Width" | `xpack.lens.shared.legendSizeSetting.label` | | "Truncate" | "Label truncation" | `xpack.lens.shared.labelTruncation` | | "Max lines" | "Line limit" | `xpack.lens.shared.maxLinesLabel` | | "Show" (legend) | "Show" | `xpack.lens.pieChart.legendVisibility.show` | ## Quick Reference: Per-Chart Differences | Feature | Pie/Donut | Treemap | Mosaic | Waffle | |---------|-----------|---------|--------|--------| | Slice labels | Hide/Inside/Auto | Hide/Show | (none) | (none) | | Slice values | Hide/Integer/Percentage | Hide/Integer/Percentage | Hide/Integer/Percentage | (none) | | Donut hole | Yes | No | No | No | | Style panel disabled | No | No | No | Yes | | Legend Position | No | No | No | No | | Legend Width | Yes | Yes | Yes | Yes | | Nested legend | Yes (>1 group) | Yes (>1 group) | Yes (>1 group) | No | | Show value | No | No | No | Yes | | Statistics | No | No | No | No | | Default legend visibility | Auto shows when >1 bucket | Auto hides | Auto hides | Auto shows always | | Max Group by dimensions | 3 | 2 | 2 | 1 | | Color mapping | First Group by only | First Group by only | Vertical axis | Group by | ## Common Mistakes to Avoid 1. **Assuming Position exists for partition charts** — it doesn't. Only XY-type charts have Position. 2. **Using "Legend size" instead of "Width"** — the actual label is "Width". 3. **Including Auto in Width options** — Auto only shows for pre-8.3 visualizations. 4. **Documenting Statistics for non-waffle charts** — only waffle has `defaultLegendStats`. 5. **Assuming "Titles and text" sub-header exists for all charts** — it only appears when `emptySizeRatioOptions` is defined (pie/donut). 6. **Getting the Nested legend condition wrong** — it requires both `hideNestedLegendSwitch !== true` AND multiple Group by dimensions. 7. **Assuming color mapping works on all Group by levels** — only available on the first dimension.