@lunit/oui 3.1.0 → 3.1.2

package/dist/types/components/TextField/TextInput.types.d.ts

@@ -1,27 +1,41 @@
 import type { BoxProps, InputProps as MuiInputProps } from '@mui/material';
 import type { RootTextFieldProps, HelperMsgProps } from '../BaseTextField/BaseTextField.types';
 interface RootTextInputProps extends RootTextFieldProps, Omit<MuiInputProps, 'size' | 'error' | 'ref' | 'value' | 'defaultValue' | 'onChange'> {
+    /** Uses the taller input height */
     large?: boolean;
+    /** Icon rendered inside the field, before the text */
     leftIcon?: React.ReactNode;
+    /** Icon rendered inside the field, after the text; replaces the clear button */
     rightIcon?: React.ReactNode;
+    /** Called on every keystroke */
     onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    /** Props for the wrapper Box around the field and its helper message */
     OuterBoxProps?: BoxProps;
+    /** Props for the Box wrapping the input and its icons */
     InputContainerProps?: BoxProps;
+    /** Style overrides for the input element itself, replacing the default icon padding */
     inputSX?: MuiInputProps['sx'];
 }
 interface InputWithHelperMsgProps extends Omit<RootTextInputProps, 'error'>, Omit<HelperMsgProps, 'error'> {
+    /** Error message shown under the field; also puts the field in its error state */
     error?: string;
 }
 interface PasswordInputWithHelperMsgProps extends Omit<InputWithHelperMsgProps, 'rightIcon' | 'readOnly' | 'onClearButtonClick' | 'InputContainerProps'> {
+    /** Renders a password field with a built-in reveal toggle */
     type: 'password';
 }
 interface NormalTextInputProps extends InputWithHelperMsgProps {
+    /** Called when the clear button is pressed; the button only renders when this is set */
     onClearButtonClick?: () => void;
+    /** Icon rendered inside the field, after the text; replaces the clear button */
     rightIcon?: React.ReactNode;
 }
 interface FileInputProps extends NormalTextInputProps {
+    /** Renders a file picker field */
     type: 'file';
+    /** Extensions the picker accepts, as an `accept` attribute value */
     accept: string;
+    /** Called when the field is clicked to open the picker */
     onClick: () => void;
 }
 interface PasswordTextInputProps extends PasswordInputWithHelperMsgProps {

package/dist/types/components/Toggle/Toggle.types.d.ts

@@ -1,17 +1,31 @@
 import type { BoxProps, Color, SwitchProps as MuiSwitchProps } from '@mui/material';
 export interface ToggleProps extends Omit<BoxProps<'span'>, 'onChange' | 'onChangeCapture'> {
+    /** Value submitted with the surrounding form */
     value?: MuiSwitchProps['value'];
+    /** Name of the underlying input */
     name?: MuiSwitchProps['name'];
+    /** Whether the switch is on, for controlled use */
     checked?: MuiSwitchProps['checked'];
+    /** Initial state, for uncontrolled use */
     defaultChecked?: MuiSwitchProps['defaultChecked'];
+    /** Blocks interaction and renders the muted disabled style */
     disabled?: MuiSwitchProps['disabled'];
+    /** Marks the input as required in the surrounding form */
     required?: MuiSwitchProps['required'];
+    /** Called when the switch is flipped */
     onChange?: MuiSwitchProps['onChange'];
+    /** Capture-phase change handler */
     onChangeCapture?: MuiSwitchProps['onChangeCapture'];
+    /** Attributes applied to the underlying input element */
     inputProps?: React.InputHTMLAttributes<HTMLInputElement>;
+    /** Ref to the underlying input element */
     inputRef?: React.Ref<HTMLInputElement>;
+    /** Renders the partial state; the change event still reports `checked: true` */
     indeterminate?: boolean;
+    /** Text shown beside the switch; makes the container a `<label>` */
     label?: string;
+    /** Which side of the switch the label sits on. Defaults to `right` */
     labelPlacement?: 'left' | 'right';
+    /** Track colour while the switch is on */
     toggleColor?: React.CSSProperties['color'] | Color;
 }

package/dist/types/components/Tooltip/Tooltip.types.d.ts

@@ -3,14 +3,19 @@ import type { TooltipClasses, TooltipProps as MuiTooltipProps } from '@mui/mater
 export type Position = Pick<TooltipProps, 'placement'>;
 export type TooltipSizes = 'small' | 'large';
 export interface TooltipSize {
+    /** Arrow width in px */
     width: number;
+    /** Arrow height in px */
     height: number;
 }
 export type TooltipPlacement = TooltipClasses['tooltipPlacementBottom'] | TooltipClasses['tooltipPlacementLeft'] | TooltipClasses['tooltipPlacementRight'] | TooltipClasses['tooltipPlacementTop'];
 export type ArrowSizeBySize = Record<TooltipSizes, TooltipSize>;
 export type TooltipPlacementToSize = Record<TooltipPlacement, ArrowSizeBySize>;
 export interface TooltipProps extends MuiTooltipProps {
+    /** Icon rendered before the title; `small` size only */
     icon?: ReactNode;
+    /** Padding and typography preset. Defaults to `small` */
     size?: TooltipSizes;
+    /** Removes the tooltip's inner padding, for content that brings its own */
     noPadding?: boolean;
 }

package/dist/types/components/UploadManager/UploadManager.types.d.ts

@@ -1,14 +1,23 @@
 import { UppyFile } from '@uppy/core';
 export interface UploadFileProps {
+    /** Uppy file whose name, size and progress are rendered */
     file: UppyFile;
+    /** Called with the file id when its cancel button is clicked */
     onCancel?: (id: string) => void;
+    /** Called with the file id when a failed upload is retried */
     onRetry?: (id: string) => void;
 }
 export interface UploadManagerProps {
+    /** Heading of the upload panel */
     title: string;
+    /** Secondary line under the title, e.g. overall progress */
     subTitle?: string;
+    /** Files listed in the panel */
     files: UppyFile[];
+    /** Called when the panel's close button is clicked */
     onClose?: () => void;
+    /** Called with the file id when a file's cancel button is clicked */
     onCancel?: (id: string) => void;
+    /** Called with the file id when a failed upload is retried */
     onRetry?: (id: string) => void;
 }

package/dist/types/presentations/Accordion/Accordion.types.d.ts

@@ -4,18 +4,29 @@ import { FreeTextProps } from '../FreeText';
 import { StatisticProps } from '../Statistic';
 import { ScoreProps } from '../Score';
 export interface AccordionSpec {
+    /** Discriminator identifying this spec as an accordion */
     componentType: 'accordion';
+    /** Section heading shown in the summary row */
     title: string;
+    /** Text size and weight preset for the summary row */
     size?: PresentationElementSize;
+    /** Components rendered inside the expanded section; must contain at least one item */
     items: (StatisticProps | FreeTextProps | ScoreProps)[];
+    /** Whether the section starts expanded */
     isOpen?: boolean;
+    /** Components rendered in a tooltip behind an info icon before the title */
     tooltip?: (StatisticProps | FreeTextProps)[];
+    /** Value appended to the title as `title: metrics` */
     metrics?: string;
 }
 interface AccordionProps extends AccordionSpec {
+    /** Props forwarded to the underlying MUI Accordion */
     MuiAccordionProps?: MuiAccordionProps;
+    /** Props forwarded to the underlying MUI AccordionSummary */
     AccordionSummaryProps?: AccordionSummaryProps;
+    /** Props forwarded to the underlying MUI AccordionDetails */
     AccordionDetailsProps?: AccordionDetailsProps;
+    /** Called with the next expanded state when the summary row is clicked */
     onChange?: (event: React.SyntheticEvent, expanded: boolean) => void;
 }
 export type { AccordionProps };

package/dist/types/presentations/AnalysisBar/AnalysisBar.types.d.ts

@@ -1,13 +1,30 @@
+/** A label placed at an explicit position on the bar */
+export interface AnalysisBarLevel {
+    /** Text displayed under the bar */
+    label: string;
+    /** Horizontal position on the bar, 0-100 (%) */
+    position: number;
+}
+/** Either a numeric string ('20', '20%') that doubles as its own label, or an explicitly positioned label */
+export type AnalysisBarExpressionLevel = string | AnalysisBarLevel;
 export interface AnalysisBarProps {
+    /** Discriminator identifying this spec as an analysis bar */
     componentType: 'analysisBar';
+    /** Widens segments of 1% or less to a fixed 12px so they stay visible */
     isCutoff?: boolean;
-    expressionLevels?: string[];
+    /** Axis labels under the bar. Numeric strings are placed at their own value; objects at their `position` */
+    expressionLevels?: AnalysisBarExpressionLevel[];
+    /** Caption rendered at the midpoint of the bar */
     caption?: string;
+    /** Colour segments making up the bar; widths are normalised to 100%. A `jet` colour renders a heatmap gradient */
     segments?: {
         color: 'jet' | string;
         width: number;
     }[];
+    /** Value of the point indicator, which also sets its position on the bar */
     expressionValue?: string;
+    /** Overrides the displayed text of the axis label at the same index, leaving its position unchanged */
     expressionLabels?: string[];
+    /** Renders the whole bar at reduced opacity */
     isDimmed?: boolean;
 }

package/dist/types/presentations/AnalysisBar/AnalysisBar.utils.d.ts

@@ -1,4 +1,11 @@
+import type { AnalysisBarExpressionLevel, AnalysisBarLevel } from './AnalysisBar.types';
 export declare function parseStringValToNumber(val: string): number;
+/**
+ * @description resolveExpressionLevel normalizes an expression level into a label and its position on the bar.
+ * @param level - A numeric string ('20', '20%') used as both label and position, or an object with an explicit label and position.
+ * @returns The label to display and its position on the bar.
+ */
+export declare function resolveExpressionLevel(level: AnalysisBarExpressionLevel): AnalysisBarLevel;
 export declare function clampNumericalPercentage(value: number): number;
 export declare function clampBarLabelPosition(value: number): number;
 /**

package/dist/types/presentations/AnalysisBar/index.d.ts

@@ -1,4 +1,4 @@
 import AnalysisBar from './AnalysisBar';
-import type { AnalysisBarProps } from './AnalysisBar.types';
+import type { AnalysisBarProps, AnalysisBarLevel, AnalysisBarExpressionLevel } from './AnalysisBar.types';
 export { AnalysisBar };
-export type { AnalysisBarProps };
+export type { AnalysisBarProps, AnalysisBarLevel, AnalysisBarExpressionLevel };

package/dist/types/presentations/FreeText/FreeText.types.d.ts

@@ -1,9 +1,14 @@
 import type { PresentationElementSize } from '../presentations.types';
 interface FreeTextProps {
+    /** Discriminator identifying this spec as free text */
     componentType: 'freeText';
+    /** Text size and weight preset */
     size?: PresentationElementSize;
+    /** Text to render; line breaks are preserved */
     content: string;
+    /** Fixed height in px; the text scrolls when it overflows. Grows with the content when omitted */
     height?: number;
+    /** Wraps the text in a rounded grey panel with padding */
     background?: boolean;
 }
 export type { FreeTextProps };

package/dist/types/presentations/Histogram/Histogram.types.d.ts

@@ -1,24 +1,38 @@
 import { FreeTextProps } from '../FreeText';
 export interface HistogramTab {
+    /** Tab label shown above the chart */
     label: string;
+    /** Bar heights, one entry per bucket */
     data: number[];
 }
 export interface HistogramProps {
+    /** Discriminator identifying this spec as a histogram */
     componentType: 'histogram';
+    /** Heading shown above the tabs */
     title?: string;
+    /** Free text blocks rendered under the chart */
     description?: FreeTextProps[];
+    /** Tick values along the x axis; must contain at least one item */
     xAxisLabels: number[];
+    /** Tick values along the y axis; must contain at least one item */
     yAxisLabels: number[];
+    /** Datasets selectable by tab; the first one is shown initially */
     tabs: HistogramTab[];
 }
 export interface HistogramTabsProps {
+    /** Tab labels in display order */
     options: string[];
+    /** Index of the selected tab */
     active: number;
+    /** Called with the index of the newly selected tab */
     onChange: (index: number) => void;
 }
 export interface HistogramChartProps {
+    /** Dataset to plot */
     dataset: HistogramTab;
+    /** Tick values along the x axis */
     xAxisLabels: number[];
+    /** Tick values along the y axis */
     yAxisLabels: number[];
 }
 interface HistogramDatapoint {

package/dist/types/presentations/HorizonDivider/HorizonDivider.types.d.ts

@@ -1,4 +1,5 @@
 interface HorizonDividerProps {
+    /** Discriminator identifying this spec as a divider */
     componentType: 'divider';
 }
 export type { HorizonDividerProps };

package/dist/types/presentations/ModelType/ModelType.types.d.ts

@@ -1,33 +1,50 @@
 import { SelectChangeEvent } from '@mui/material/Select';
 import { ScoreProps } from '../Score';
 interface ModelTypeOption {
+    /** Option label shown in the dropdown */
     title: string;
+    /** Visualization this option switches the viewer to. Read by the host app, not by this component */
     target: {
         visualizationType: string;
         annotation: {
+            /** Annotation name; must match the LOAR annotation it refers to */
             name: string;
+            /** Measurement region, also used as the option's dropdown value */
             dimension: string;
             color: string;
         };
     };
     key: string;
     value: number;
+    /** Sensitivity of this model type; must be a number */
     sensitivity: number;
+    /** Specificity of this model type; must be a number */
     specificity: number;
 }
 export interface ModelTypeSpec {
+    /** Discriminator identifying this spec as a model type selector */
     componentType: 'modelType';
+    /** Heading shown above the sensitivity and specificity scores */
     title: string;
+    /** Subtitle rendered at the top of the dropdown list */
     optionTitle?: string;
+    /** Scores to show per model type, keyed by the option's `target.annotation.dimension` */
     scoreItems: Record<string, ScoreProps[]>;
+    /** Sensitivity of the currently applied model type */
     currentSensitivity: ScoreProps;
+    /** Specificity of the currently applied model type */
     currentSpecificity: ScoreProps;
+    /** Selectable model types; must contain at least one item */
     options: ModelTypeOption[];
+    /** Dimension of the model type currently applied; selects the initial dropdown value */
     userModelType: string;
+    /** Guidance text rendered under the update button */
     description?: string;
 }
 export interface ModelTypeProps extends ModelTypeSpec {
+    /** Called when a different model type is picked from the dropdown */
     onChangeDropdown: (event: SelectChangeEvent) => void;
+    /** Called when the update button is pressed; the button is disabled until the selection changes */
     onClickUpdateConfiguration: () => void;
 }
 export {};

package/dist/types/presentations/Preview/Preview.types.d.ts

@@ -9,7 +9,9 @@ import { ThresholdProps } from '../Threshold';
 import { HistogramProps } from '../Histogram';
 import { ModelTypeProps } from '../ModelType';
 interface PreviewProps {
+    /** Layer toggles rendered in the upper section, in display order */
     visualizationControls: (ToggleControlProps | ToggleControlGroupProps | AnalysisBarProps)[];
+    /** Result summary components rendered in the lower section, in display order */
     analysisSummary: (AccordionProps | AnalysisBarProps | StatisticProps | ScoreProps | FreeTextProps | ThresholdProps | HistogramProps | ModelTypeProps)[];
 }
 export type { PreviewProps };

package/dist/types/presentations/Score/Score.types.d.ts

@@ -1,12 +1,20 @@
 import { PresentationElementSize } from '../presentations.types';
 interface ScoreProps {
+    /** Discriminator identifying this spec as a score */
     componentType: 'score';
+    /** Score name shown before the value */
     title: string;
+    /** Text size and weight preset */
     size?: PresentationElementSize;
+    /** The score value and how it is coloured */
     metrics: {
+        /** Formatted score value shown after the title */
         value?: string;
+        /** Qualitative result appended after the value, capitalised on render */
         scoreType?: 'positive' | 'negative';
+        /** Colour applied to the score type, and to the whole line when `isFullColored` is set */
         color?: string;
+        /** Applies `color` to the title and value as well, not just the score type */
         isFullColored?: boolean;
     };
 }

package/dist/types/presentations/Statistic/Statistic.types.d.ts

@@ -1,15 +1,24 @@
 import { BoxProps } from '@mui/material';
 import { PresentationSymbolProps } from '../presentations.types';
 export interface StatisticSpec extends BoxProps {
+    /** Discriminator identifying this spec as a statistic */
     componentType: 'statistic';
+    /** Label describing the metric */
     title: string;
+    /** `horizontal` puts the value on the same line as the title, `vertical` stacks them */
     layout?: 'horizontal' | 'vertical';
+    /** Formatted value shown next to the title */
     metrics?: string;
+    /** Text size and weight preset */
     size?: 'small-dimmed' | 'small' | 'small-bold' | 'medium' | 'medium-bold' | 'large-bold';
+    /** Shape of the legend marker drawn before the title; horizontal layout only */
     symbol?: PresentationSymbolProps['symbol'];
+    /** Fill colour of the legend marker */
     color?: string;
+    /** DOM id applied to the container */
     id?: string;
 }
 export interface StatisticProps extends StatisticSpec {
+    /** Renders the marker and title at reduced opacity */
     isDimmed?: boolean;
 }

package/dist/types/presentations/Threshold/Threshold.types.d.ts

@@ -4,9 +4,13 @@ import { SelectChangeEvent } from '@mui/material/Select';
 import { ScoreProps } from '../Score';
 import { StatisticProps } from '../Statistic';
 export interface ThresholdOption {
+    /** Option label shown in the dropdown, also used as its value */
     title: string;
+    /** Grouping key for the option. Read by the host app, not by this component */
     category: string;
+    /** Threshold this option applies, on the 0-100 intensity scale */
     value: number;
+    /** Marks the option as a fixed preset, which locks the slider. Read by the host app, not by this component */
     isPreset?: boolean;
 }
 export interface ThresholdMark {
@@ -16,33 +20,49 @@ export interface ThresholdMark {
     label?: string;
 }
 export interface ThresholdSpec {
+    /** Discriminator identifying this spec as a threshold control */
     componentType: 'threshold';
     /** Overall score summary shown above the cell statistics; omitted when the analysis has no score */
     totalScore?: ScoreProps;
+    /** Total cell count shown above the per-category statistics */
     totalCells: StatisticProps;
+    /** Per-category cell statistics shown under the total */
     statisticItems: StatisticProps[];
+    /** Heading shown above the option dropdown */
     title?: string;
+    /** Guidance text shown under the slider, chosen by whether a preset is selected */
     description?: {
         /** Guidance shown while a preset option is selected */
         preset?: string;
         /** Guidance shown while a user-adjustable option is selected */
         user?: string;
     };
+    /** Selectable threshold options listed in the dropdown */
     options: ThresholdOption[];
+    /** Slider increment; defaults to 1 */
     controlStep?: number;
     /** Labels the selected option's threshold on the slider, e.g. `Default: 40`; off by default */
     showDefaultMark?: boolean;
 }
 export interface ThresholdProps extends ThresholdSpec {
+    /** Current selection and slider position, owned by the host app */
     thresholdState?: {
+        /** Title of the selected option */
         selectedItem: string;
+        /** Current slider position on the 0-100 intensity scale */
         sliderValue: number;
+        /** Locks the slider and shows `description.preset` instead of `description.user` */
         isPresetSelected: boolean;
     };
+    /** Called when a different option is picked from the dropdown */
     onChangeDropdown: (event: SelectChangeEvent) => void;
+    /** Called on every slider movement */
     onChangeSlider: (event: Event | SyntheticEvent, value: number | number[]) => void;
+    /** Called once the slider is released */
     onSliderChangeCommitted: (event: Event | SyntheticEvent, value: number | number[]) => void;
+    /** Called when the update button is pressed */
     onClickUpdateConfiguration: () => void;
+    /** Shows a spinner on the update button and blocks it */
     isLoading?: boolean;
 }
 export interface BaseSliderProps extends SliderProps {

package/dist/types/presentations/ToggleControl/ToggleControl.types.d.ts

@@ -3,47 +3,76 @@ import type { AnalysisBarProps } from '../AnalysisBar';
 import type { PresentationElementSize, PresentationSymbol } from '../presentations.types';
 import { StatisticProps } from '../Statistic';
 export interface ToggleControlSpec {
+    /** Discriminator identifying this spec as a toggle */
     componentType: 'toggle';
+    /** Label shown next to the switch */
     title: string;
+    /** Text size and weight preset */
     size?: PresentationElementSize;
+    /** Shape of the legend marker drawn before the title */
     symbol?: PresentationSymbol;
+    /** Fill colour of the legend marker */
     color?: string;
+    /** Whether the switch is on; required */
     checked: boolean;
+    /** Components rendered in a tooltip behind an info icon before the title */
     tooltip?: (StatisticProps | FreeTextProps)[];
+    /** Statistics rendered under the toggle row */
     content?: StatisticProps[];
+    /** Analysis bar rendered under the toggle row, below `content` */
     bar?: AnalysisBarProps;
 }
 interface PixelAnnotationSpec {
+    /** Annotation name; must match the LOAR `pixelAnnotations` entry */
     name: string;
+    /** Single measurement region to render */
     dimension?: string;
+    /** Multiple measurement regions to render */
     dimensions?: string[];
 }
 interface CellAnnotationSpec {
+    /** Annotation name; must match the LOAR `cellAnnotations` entry */
     name: string;
 }
 interface GridAnnotationSpec {
+    /** Annotation name; must match the LOAR `gridAnnotations` entry */
     name: string;
 }
 interface CutOffLabelProps {
+    /** Colour applied to the label's segment */
     color: string;
+    /** Index of the label within the annotation's label set */
     labelIndex: number;
 }
+/** Visualization layer a toggle controls. Read by the host app, not by this component */
 interface TargetSpec {
+    /** Kind of visualization to render, e.g. `cell`, `grid`, `heatmap` */
     visualizationType: string;
     annotationId?: string;
+    /** Annotation to render, either a spec object or the annotation name */
     annotation: PixelAnnotationSpec | CellAnnotationSpec | GridAnnotationSpec | string;
+    /** Single annotation label to render */
     label?: string;
     labelId?: string;
+    /** Multiple annotation labels to render, optionally with per-label colours */
     labels?: (string | CutOffLabelProps)[];
+    /** Single colour applied to the layer */
     color?: string;
+    /** Per-label colours applied to the layer */
     colors?: string[];
 }
 export interface ToggleControlProps extends ToggleControlSpec {
+    /** Marks this toggle as a group header, adding spacing below it. Set by ToggleControlGroup */
     isParent?: boolean;
+    /** Renders the marker and title at reduced opacity, and blocks the switch */
     isDimmed?: boolean;
+    /** Blocks interaction with the switch */
     disabled?: boolean;
+    /** Visualization layer this toggle controls. Read by the host app, not by this component */
     target?: TargetSpec;
+    /** Marks this toggle as the master switch for every layer. Read by the host app, not by this component */
     isMaster?: boolean;
+    /** Called when the switch is flipped */
     onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
 }
 export {};

package/dist/types/presentations/ToggleControlGroup/ToggleControlGroup.types.d.ts

@@ -5,17 +5,28 @@ import { StatisticProps } from '../Statistic';
 import type { ToggleControlProps } from '../ToggleControl';
 export type ToggleControlGroupBehavior = 'exclusive' | 'multi';
 export interface ToggleGroupControlSpec {
+    /** Discriminator identifying this spec as a toggle group */
     componentType: 'toggleGroup';
+    /** Label shown next to the group's own switch */
     title: string;
+    /** Whether the children may be on together (`multi`) or only one at a time (`exclusive`). Read by the host app, not by this component */
     behavior?: ToggleControlGroupBehavior;
+    /** Text size and weight preset for the group header */
     size?: PresentationElementSize;
+    /** Components rendered in a tooltip behind an info icon before the title */
     tooltip?: (StatisticProps | FreeTextProps)[];
+    /** Analysis bar rendered under the group header row */
     bar?: AnalysisBarProps;
+    /** Whether the group switch is on; turning it off dims and disables every child. Required */
     checked: boolean;
+    /** Toggles rendered under the group header; must contain at least one item */
     childToggles: ToggleControlProps[];
 }
 export interface ToggleControlGroupProps extends ToggleGroupControlSpec {
+    /** Called when the group switch is flipped */
     onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    /** Blocks interaction with the group switch */
     disabled?: boolean;
+    /** Renders the group and its children at reduced opacity */
     isDimmed?: boolean;
 }

package/dist/types/presentations/presentations.types.d.ts

@@ -2,13 +2,19 @@ import { TypographyProps } from '@mui/material';
 export type PresentationElementSize = 'small-dimmed' | 'small' | 'small-bold' | 'medium' | 'medium-bold' | 'large-bold';
 export type PresentationSymbol = 'circle' | 'rectangle' | 'border-circle' | 'border-rectangle';
 interface PresentationSymbolProps {
+    /** Shape of the legend marker drawn next to a label */
     symbol?: PresentationSymbol;
+    /** Fill colour of the legend marker */
     color?: string;
+    /** Renders the marker at reduced opacity */
     isDimmed?: boolean;
 }
 interface PresentationTypographyProps extends TypographyProps {
+    /** Text size and weight preset */
     size?: PresentationElementSize;
+    /** Renders the text at reduced opacity */
     isDimmed?: boolean;
+    /** CSS display mode of the text element */
     display?: 'block' | 'inline-block' | 'flex' | 'inherit';
 }
 export type { PresentationSymbolProps, PresentationTypographyProps };

package/docs/COMPONENTS.md

@@ -99,6 +99,34 @@ Exported together from `@lunit/oui`. Composite components for the oncology analy
 
 `Accordion`, `AnalysisBar`, `FreeText`, `Histogram`, `HorizonDivider`, `ModelType`, `Preview`, `Score`, `Statistic`, `Threshold`, `ToggleControl`, `ToggleControlGroup`
 
+### AnalysisBar — `expressionLevels`
+
+Axis labels under the bar. Each item is either a numeric string, which is both the label and its position, or an object that places arbitrary text at an explicit position.
+
+```tsx
+// numeric strings: label and position are the same value
+<AnalysisBar componentType="analysisBar" expressionLevels={['0', '20', '100']} segments={segments} />
+
+// text labels at explicit positions (0-100)
+<AnalysisBar
+  componentType="analysisBar"
+  expressionLevels={[
+    { label: 'Low', position: 0 },
+    { label: 'High', position: 100 },
+  ]}
+  segments={segments}
+/>
+
+// the two forms can be mixed
+<AnalysisBar
+  componentType="analysisBar"
+  expressionLevels={['0', { label: 'Cutoff', position: 20 }, '100']}
+  segments={segments}
+/>
+```
+
+`expressionLabels[i]`, when present, still overrides the displayed text of the i-th level while its position is unchanged.
+
 ---
 
 ## Usage examples

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunit/oui",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "validate-branch-name": {
     "pattern": "^(main|develop)|(feature|fix|release|hotfix|qe)/.+$",
     "errorMsg": "The branch name is not correct. Please check the pattern. (ex. feature/add-something)"