Add Component Documentation

valdi_modules/navigation_internal/src/NavigationView.tsx

@@ -59,6 +59,10 @@ interface NavigationPresent extends NavigationInfo {}
 
 type NavigationOperation = (done: () => void) => void;
 
+/**
+ * Web/desktop navigation stack renderer that stacks components as full-screen views and animates push (slide-right) and present (slide-up) transitions.
+ * Manages a serial task queue so navigation animations run sequentially without overlap.
+ */
 export class NavigationView extends StatefulComponent<{}, State, NavigationViewContext> {
   state: State = { stack: [] };
 

valdi_modules/widgets/src/components/animation/AnimationSliding.tsx

@@ -23,6 +23,10 @@ interface AnimationSlidingState {
   progress: number;
 }
 
+/**
+ * Translates its children from a start X/Y offset to an end X/Y offset after an optional delay.
+ * Progress animates from 0 to 1 using the provided animationOptions.
+ */
 export class AnimationSliding extends StatefulComponent<AnimationSlidingViewModel, AnimationSlidingState> {
   state: AnimationSlidingState = {
     progress: 0,

valdi_modules/widgets/src/components/animation/AnimationSquishy.tsx

@@ -21,6 +21,9 @@ interface AnimationSquishyState {
   progress: number;
 }
 
+/**
+ * Scales its children in ("grow") or out ("shrink") after an optional delay, with optional tilt offsets applied to the translation.
+ */
 export class AnimationSquishy extends StatefulComponent<AnimationSquishyViewModel, AnimationSquishyState> {
   state: AnimationSquishyState = {
     progress: 0,

valdi_modules/widgets/src/components/button/ConfirmationButton.tsx

@@ -13,6 +13,9 @@ export interface ConfirmationButtonViewModel {
   accessibilityLabel?: string;
 }
 
+/**
+ * Full-width XL PRIMARY CoreButton pre-configured for confirmation actions; switches to INACTIVE coloring when disabled.
+ */
 export class ConfirmationButton extends Component<ConfirmationButtonViewModel> {
   onRender(): void {
     const viewModel = this.viewModel;

valdi_modules/widgets/src/components/button/FloatingActionButton.tsx

@@ -32,6 +32,10 @@ interface FloatingActionButtonColorTheme {
   icon: SemanticColor;
 }
 
+/**
+ * Absolutely-positioned circular search button anchored to the bottom-right corner.
+ * Slides in or out of view by animating its bottom margin; respects safe area insets on tall devices.
+ */
 export class FloatingActionButton extends StatefulComponent<
   FloatingActionButtonViewModel,
   FloatingActionButtonState,

valdi_modules/widgets/src/components/button/PillButton.tsx

@@ -18,6 +18,9 @@ export interface PillButtonViewModel {
   accessibilityLabel?: string;
 }
 
+/**
+ * SMALL SECONDARY CoreButton with optional icon and selection state; selected items render the foreground in brand primary color.
+ */
 export class PillButton extends Component<PillButtonViewModel> {
   onRender(): void {
     const viewModel = this.viewModel;

valdi_modules/widgets/src/components/card/Card.tsx

@@ -24,6 +24,9 @@ export enum CardShadow {
   NONE,
 }
 
+/**
+ * Rounded container (10pt radius by default) with an optional drop shadow, configurable background color, and tap handler.
+ */
 export class Card extends Component<CardViewModel> {
   onRender(): void {
     const viewModel = this.viewModel ?? {};

valdi_modules/widgets/src/components/card/CollapsibleCard.tsx

@@ -76,6 +76,10 @@ const animationOptions: PresetCurveAnimationOptions = {
   duration: 0.2,
 };
 
+/**
+ * Card that initially shows up to `maxNumCollapsedComponents` rows and animates height to reveal or hide additional rows.
+ * Rows can be supplied as render functions or ComponentDef objects; supply `rowHeight` to enable lazy rendering.
+ */
 export class CollapsibleCard<T extends {}> extends StatefulComponent<
   CollapsibleCardViewModel<T>,
   CollapsibleCardState

valdi_modules/widgets/src/components/cell/Cell.tsx

@@ -54,6 +54,10 @@ export interface CellViewModel {
   accessoryMarginRight?: number;
 }
 
+/**
+ * Standard list row with configurable packing density, left/right accessory slots, and label slots for
+ * title, subtitle, identity, meta, and reason text.
+ */
 export class Cell extends Component<CellViewModel> {
   identityAccessoryRef = new ElementRef();
   rightAccessoryRef = new ElementRef();

valdi_modules/widgets/src/components/cell/subtitle/DelimitedCellSubtitle.tsx

@@ -13,6 +13,9 @@ export interface GenericCellSubtitleViewModel {
   children?: RenderFunction;
 }
 
+/**
+ * Subtitle row that renders an array of render functions separated by a dot delimiter, with an optional left accessory slot.
+ */
 export class DelimitedCellSubtitle extends Component<GenericCellSubtitleViewModel> {
   onRender(): void {
     const viewModel = this.viewModel ?? {};

valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleBadge.tsx

@@ -4,6 +4,9 @@ import { TextStyleFont } from 'widgets/src/styles/TextStyleFont';
 import { SemanticColor } from 'widgets/src/styles/semanticColors';
 import { SubtitleText } from './SubtitleText';
 
+/**
+ * Subtitle label rendered in CAPTION_EMPHASIS font and brand-primary color, used to highlight a badge value in a cell subtitle.
+ */
 export class SubtitleBadge extends Component<CommonLabel & ViewAttributes> {
   onRender(): void {
     <SubtitleText {...this.viewModel} font={TextStyleFont.CAPTION_EMPHASIS} color={SemanticColor.Button.PRIMARY} />;

valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleBrand.tsx

@@ -4,6 +4,9 @@ import { TextStyleFont } from 'widgets/src/styles/TextStyleFont';
 import { SemanticColor } from 'widgets/src/styles/semanticColors';
 import { SubtitleText } from './SubtitleText';
 
+/**
+ * Subtitle label rendered in CAPTION font and primary text color, used for brand-name text in a cell subtitle.
+ */
 export class SubtitleBrand extends Component<CommonLabel & ViewAttributes> {
   onRender(): void {
     <SubtitleText {...this.viewModel} font={TextStyleFont.CAPTION} color={SemanticColor.Text.PRIMARY} />;

valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleText.tsx

@@ -2,6 +2,9 @@ import { Component } from 'valdi_core/src/Component';
 import { CommonLabel, CommonTextAttributes, ViewAttributes } from 'valdi_tsx/src/NativeTemplateElements';
 import { style } from '../../style';
 
+/**
+ * Base subtitle label that applies the shared cell subtitle style; used directly or via SubtitleBadge/SubtitleBrand.
+ */
 export class SubtitleText extends Component<CommonTextAttributes & ViewAttributes & CommonLabel> {
   onRender(): void {
     <label {...this.viewModel} accessibilityId='result-subtitle' style={style.label.subtitle} />;

valdi_modules/widgets/src/components/grid/GridView.tsx

@@ -37,6 +37,10 @@ interface GridViewContext<T> {
   renderItem(item: T, borderRadius: number, index: number): void;
 }
 
+/**
+ * Renders items in a multi-column grid with lazy layout; defaults to 3 columns with a square aspect ratio per item.
+ * Used internally by GridViewWrapper — prefer GridViewWrapper for most use cases.
+ */
 export class GridView<T> extends StatefulComponent<GridViewModel<T>, GridViewState, GridViewContext<T>> {
   defaultGridRowStyle = new Style<Layout>({
     flexDirection: 'row',

valdi_modules/widgets/src/components/indexview/IndexViewAnchor.tsx

@@ -7,6 +7,10 @@ export interface IndexViewAnchorViewModel {
   symbol: IndexViewSymbol;
 }
 
+/**
+ * Invisible zero-size layout registered to an IndexViewHandler under a given symbol key.
+ * Place this adjacent to the content section that should be reachable via IndexView.
+ */
 export class IndexViewAnchor extends Component<IndexViewAnchorViewModel> {
   onRender(): void {
     const viewModel = this.viewModel;

valdi_modules/widgets/src/components/indexview/IndexViewHandler.ts

@@ -1,6 +1,10 @@
 import { ElementRef } from 'valdi_core/src/ElementRef';
 import { IndexViewSymbol } from './IndexViewSymbol';
 
+/**
+ * Maintains a map of IndexViewSymbol keys to ElementRef instances so an IndexView can scroll to named anchors.
+ * Pass to IndexView and IndexViewAnchor to link them together.
+ */
 export class IndexViewHandler {
   private elementRefs: Map<string, ElementRef>;
   constructor() {

valdi_modules/widgets/src/components/inputs/FloatLabeledTextField.tsx

@@ -45,6 +45,9 @@ interface FloatLabeledTextFieldState {
   text: string;
 }
 
+/**
+ * Text field with a title label that floats above the input when the field is focused or has content, plus an optional inline error message.
+ */
 export class FloatLabeledTextField extends StatefulComponent<
   FloatLabeledTextFieldViewModel,
   FloatLabeledTextFieldState

valdi_modules/widgets/src/components/inputs/PillTextField.tsx

@@ -79,6 +79,9 @@ interface PillTextFieldState {
   status: string;
 }
 
+/**
+ * Horizontally-scrolling input that combines removable pill chips with an inline text field for token-based entry.
+ */
 export class PillTextField extends StatefulComponent<PillTextFieldViewModel, PillTextFieldState> {
   state: PillTextFieldState = {
     inputValue: '',

valdi_modules/widgets/src/components/inputs/SearchBox.tsx

@@ -59,6 +59,9 @@ interface SearchBoxState {
   status: string;
 }
 
+/**
+ * Rounded search bar with a leading magnifying-glass icon, inline text field, and a trailing clear button that appears when text is present.
+ */
 export class SearchBox extends StatefulComponent<SearchBoxViewModel, SearchBoxState, SearchBoxContext> {
   state: SearchBoxState = {
     inputValue: '',

valdi_modules/widgets/src/components/inputs/TextFieldHandler.ts

@@ -1,6 +1,9 @@
 import { TextFieldInteractive } from 'valdi_tsx/src/NativeTemplateElements';
 import { TextInputHandler } from './TextInputHandler';
 
+/**
+ * TextInputHandler specialized for TextField elements; adds a deprecated setValue helper for imperative value updates.
+ */
 export class TextFieldHandler extends TextInputHandler<TextFieldInteractive> {
   /**
    * @deprecated

valdi_modules/widgets/src/components/inputs/TextInputHandler.ts

@@ -7,6 +7,10 @@ export interface TextInputElement {
   focused?: boolean;
 }
 
+/**
+ * Manages focus state for a text input element; if setFocused(true) is called before the element is created,
+ * it defers focus until the element's onElementCreated callback fires.
+ */
 export class TextInputHandler<T> implements IRenderedElementHolder<T> {
   protected readonly elementRef = new ElementRef<T>();
 

valdi_modules/widgets/src/components/inputs/TextViewHandler.ts

@@ -1,6 +1,9 @@
 import { TextViewInteractive } from 'valdi_tsx/src/NativeTemplateElements';
 import { TextInputHandler } from './TextInputHandler';
 
+/**
+ * TextInputHandler specialized for TextView elements; adds a deprecated setValue helper for imperative value updates.
+ */
 export class TextViewHandler extends TextInputHandler<TextViewInteractive> {
   /**
    * @deprecated

valdi_modules/widgets/src/components/pickers/IndexPicker.tsx

@@ -10,6 +10,9 @@ export interface IndexPickerViewModel {
   onChange: (index: number) => void;
 }
 
+/**
+ * Drum-roll style picker that renders a native platform index picker (SCWidgetsIndexPicker on iOS, ValdiIndexPicker on Android).
+ */
 export class IndexPicker extends Component<IndexPickerViewModel, {}> {
   onRender(): void {
     const viewModel = this.viewModel;

valdi_modules/widgets/src/components/pickers/PickerActionSheet.tsx

@@ -34,6 +34,9 @@ export interface PickerActionSheetViewModel {
  *  android: 'com.snap.valdi.widgets.PickerActionSheet'
  * })
  */
+/**
+ * Bottom sheet containing a title label and a PickerView; fires haptic feedback on creation.
+ */
 export class PickerActionSheet extends StatefulComponent<PickerActionSheetViewModel, {}, {}> {
   override onCreate(): void {
     Device.performHapticFeedback(DeviceHapticFeedbackType.ACTION_SHEET);

valdi_modules/widgets/src/components/refresh/DataSyncingBar.tsx

@@ -26,6 +26,9 @@ const GRADIENT = linearGradient(
   GradientDirection.LeftToRight,
 );
 
+/**
+ * Animated horizontal loading bar that continuously scrolls a yellow-white-brand gradient to indicate background data syncing.
+ */
 export class DataSyncingBar extends StatefulComponent<{}, DataSyncingBarState> {
   state = {
     width: 0,

valdi_modules/widgets/src/components/rules/HorizontalRule.tsx

@@ -2,6 +2,9 @@ import { Component } from 'valdi_core/src/Component';
 import { SemanticColor } from 'widgets/src/styles/semanticColors';
 import { RuleViewModel } from './RuleViewModel';
 
+/**
+ * Full-width horizontal divider line; defaults to 1pt height and the DIVIDER semantic color.
+ */
 export class HorizontalRule extends Component<RuleViewModel> {
   onRender(): void {
     const color = this.viewModel?.color ?? SemanticColor.Layout.DIVIDER;

valdi_modules/widgets/src/components/rules/VerticalRule.tsx

@@ -2,6 +2,9 @@ import { Component } from 'valdi_core/src/Component';
 import { SemanticColor } from 'widgets/src/styles/semanticColors';
 import { RuleViewModel } from './RuleViewModel';
 
+/**
+ * Full-height vertical divider line; defaults to 1pt width and the DIVIDER semantic color.
+ */
 export class VerticalRule extends Component<RuleViewModel> {
   onRender(): void {
     const color = this.viewModel?.color ?? SemanticColor.Layout.DIVIDER;

valdi_modules/widgets/src/components/scroll/scrollbar/ScrollBarAnchor.tsx

@@ -6,6 +6,10 @@ export interface ScrollBarAnchorViewModel {
   readonly label: string;
 }
 
+/**
+ * Invisible zero-size layout registered to a ScrollBarHandler under a given label.
+ * Place this adjacent to content sections to enable scroll-bar position tracking.
+ */
 export class ScrollBarAnchor extends Component<ScrollBarAnchorViewModel> {
   onRender(): void {
     const { handler, label } = this.viewModel;

valdi_modules/widgets/src/components/scroll/snap/ScrollViewSnapAnchor.tsx

@@ -6,6 +6,10 @@ export interface ScrollViewSnapAnchorViewModel {
   controller: ScrollViewSnapController;
 }
 
+/**
+ * Wraps its slot content in a layout registered to a ScrollViewSnapController so the scroll view can snap to it.
+ * Set enabled=false to temporarily opt out of snapping without removing the anchor.
+ */
 export class ScrollViewSnapAnchor extends Component<ScrollViewSnapAnchorViewModel> {
   onRender(): void {
     const viewModel = this.viewModel;

valdi_modules/widgets/src/components/section/Section.tsx

@@ -4,6 +4,9 @@ import { SectionHeader, SectionHeaderViewModel } from './SectionHeader';
 
 export interface SectionViewModel extends SectionHeaderViewModel, SectionBodyViewModel {}
 
+/**
+ * Convenience wrapper that composes a SectionHeader and a SectionBody with header and content slots.
+ */
 export class Section extends Component<SectionViewModel> {
   onRender(): void {
     const { title, actionButton, actionButtonRenderFn, fullBleed, subtitle, description } = this.viewModel;

valdi_modules/widgets/src/components/section/SectionBadge.tsx

@@ -51,6 +51,10 @@ export interface SectionBadgeViewModel {
   theme?: SectionBadgeTheme;
 }
 
+/**
+ * Pill-shaped badge with uppercase text that animates in with a squishy scale effect after a 2.4s delay.
+ * Supports Yellow (default) and Red themes.
+ */
 export class SectionBadge extends Component<SectionBadgeViewModel> {
   onRender(): void {
     const text = this.viewModel?.text.toLocaleUpperCase();

valdi_modules/widgets/src/components/section/SectionBody.tsx

@@ -10,6 +10,9 @@ export interface SectionBodyViewModel {
   fullBleed?: boolean;
 }
 
+/**
+ * Content wrapper that applies the standard section gutter padding; set fullBleed=true to remove horizontal padding.
+ */
 export class SectionBody extends Component<SectionBodyViewModel> {
   onRender(): void {
     const paddingHorizontal = this.viewModel.fullBleed ? 0 : Subscreen.GUTTER_SIZE;

valdi_modules/widgets/src/components/section/SectionHeader.tsx

@@ -43,6 +43,10 @@ export interface SectionHeaderViewModel {
   titleMaxLines?: number;
 }
 
+/**
+ * Section header row rendering a bold title, optional subtitle, optional description, and an optional action button.
+ * Supports a slot for additional title-row content and themed text colors.
+ */
 export class SectionHeader extends Component<SectionHeaderViewModel, SectionHeaderContext> {
   private readonly theme = Theme.from(this.context.themeType);
   private readonly style = {

valdi_modules/widgets/src/components/section/SectionSeparator.tsx

@@ -6,6 +6,9 @@ export interface SectionSeparatorViewModel {
   spacing?: CSSValue;
 }
 
+/**
+ * Vertical spacer used between sections; defaults to MD spacing.
+ */
 export class SectionSeparator extends Component<SectionSeparatorViewModel> {
   onRender(): void {
     const { spacing = Spacing.MD } = this.viewModel; // Standardized value, taken from SearchV2 production value and applied to all features

valdi_modules/widgets/src/components/section/SectionStatusBar.tsx

@@ -27,6 +27,9 @@ export enum StatusColor {
   Purple,
 }
 
+/**
+ * Full-width status banner that renders text centered on a tinted background; supports Blue, Red, Green, and Purple color themes.
+ */
 export class SectionStatusBar extends StatefulComponent<SectionStatusBarViewModel, {}> {
   onRender(): void {
     <view

valdi_modules/widgets/src/components/sheet/Sheet.tsx

@@ -58,6 +58,9 @@ export interface SheetViewModel {
   grabberColor?: string;
 }
 
+/**
+ * Floating bottom sheet with a rounded top and an optional tap-to-dismiss backdrop and grabber handle.
+ */
 export class Sheet extends Component<SheetViewModel> {
   onRender(): void {
     const {

valdi_modules/widgets/src/components/slider/Slider.tsx

@@ -27,6 +27,9 @@ const BAR_SIZE = 25;
 const DEFAULT_HANDLE_SIZE = 20;
 const DEFAULT_LINE_HEIGHT = 4;
 
+/**
+ * Horizontal drag slider that reports a normalized value between 0 and 1 via onChange; supports customizable track colors and handle size.
+ */
 export class Slider extends StatefulComponent<ViewModel, State> {
   state: State = { value: 0, barWidth: 0 };
 

valdi_modules/widgets/src/components/subscreen/SubscreenSections.tsx

@@ -138,6 +138,10 @@ export interface SubscreenSectionViewModel {
   themingEnabled?: boolean;
 }
 
+/**
+ * Pre-wired Subscreen that renders a SectionList with optional IndexView, pull-to-refresh, and scroll-bar support.
+ * Manages ScrollViewHandler and IndexViewHandler internally unless overrides are provided.
+ */
 export class SubscreenSections extends Component<SubscreenSectionViewModel> {
   // To simplify the API, we provide default handlers if the consumer code doesn't need any special behavior
   private indexViewHandler = new IndexViewHandler();