Rows, Settings, and Focus

Rows and Settings

A data source row points to AppConfig by settingsKey. When settingsOverrides is present, Hosanna resolves the base row style and deep-merges the row override into it before rendering.

For the AppConfig reference pages, see Rows and Cells. This page focuses on how CollectionView consumes those styles at runtime.

Rows choose layout, cell footprint, focus behavior, and the default cell fragment; the CollectionView keeps focus movement in row/item coordinates.

const row: ICollectionViewDataSourceRow = {
  id: 'featured',
  settingsKey: 'rows.regular',
  settingsOverrides: {
    height: 420,
    cellSize: [640, 360],
    cellSettingsKey: 'cells.featured',
  },
  data: { label: 'Featured' },
  items,
};

The most common row settings are:

• rowType: HorizontalRow, ListRow, GridRow, or a custom row type.
• customViewType: the view class used by a custom row.
• height, contentOffset, screenPosition, spacing, cellSize, numCols.
• cellSettingsKey: default cell style for the row.
• headerSettings: label and placement settings for row headers.
• focusSettings: indicator, scale, footprint, and long-press behavior.
• useMixedCellStyleKeys: allow items in one row to choose their own cellSettingsKey.

Row Type Defaults

HorizontalRow is the common default. Use GridRow for multi-column rows, ListRow for vertical lists inside the collection, and custom rows when a whole row should be a real Hosanna view.

AppConfig Inheritance

Use $extends to compose row and cell styles without duplicating every field.

{
  "rows": {
    "regular": {
      "rowType": "HorizontalRow",
      "height": 317,
      "cellSettingsKey": "cells.regular",
      "focusSettings": { "indicatorAppearance": "onTop" }
    },
    "featured": {
      "$extends": "rows.regular",
      "height": 430,
      "cellSize": [640, 360],
      "cellSettingsKey": "cells.featured"
    }
  }
}

~ references resolve another AppConfig value. They are useful for shared tokens such as fonts, colors, images, and repeated style blocks.

{
  "theme": {
    "fonts": {
      "row-header": "pkg:/assets/fonts/Poppins-SemiBold.ttf, 24"
    }
  },
  "rows": {
    "regular": {
      "headerSettings": {
        "fontKey": "~theme.fonts.row-header"
      }
    }
  }
}

Focus Settings

Focus is driven by the collection view, not by individual application event handlers. Row focus settings define how the focused item appears and how row movement feels.

• horizAnimSettings: choose floating or fixed horizontal focus behavior.
• vertAnimSettings: choose fixed vertical row movement.
• indicatorAppearance: none, onTop, or behind.
• indicatorImageUri and indicatorBlendColor: define the focus indicator art.
• focusedScale: scales focused cells when the row applies focused state.
• canLongPress: enables long-press selection events for the row.
• displayMode, feedbackOffsets, and footprint settings tune visual feedback.

Cell Fragments

DynamicCell renders fragment config from cells.*. Fragments usually define base views plus state-specific updates.

{
  "cells": {
    "regular": {
      "$supportsDataMap": true,
      "views": {
        "base": [
          { "id": "poster", "subType": "Poster", "width": 384, "height": 216 }
        ],
        "normal": {
          "poster": { "uri": "${data.posterUrl}" }
        },
        "focused": {
          "poster": { "scale": [1.05, 1.05] }
        },
        "selected": {
          "poster": { "opacity": 0.85 }
        }
      }
    }
  }
}

Mixed Cell Styles

When a row enables useMixedCellStyleKeys, each item can provide a cellSettingsKey. This is useful for rails that mix poster, hero, and metadata cells without creating separate rows.

Fragment Data and Callbacks

Fragments support richer behavior than static JSON. With $supportsDataMap, ${data.*} values are tracked in a data map and updated when row item data changes. ${fn.name(args)} bindings compute a single field through an onSpecificViewDataChange registration. AppConfig also supports fragment callback groups:

• onMount: run after the fragment is created.
• onUnmount: run before the fragment is released.
• onApplyViewStatus: run when normal, focused, selected, or disabled state is applied.
• onDataChange: run after data-bound values change.
• onSpecificViewDataChange: compute a specific SG field from data, field name, and callback arguments when a fragment uses ${fn.name(args)}.

Use direct bindings for simple text, image, scale, and opacity changes. Use fragment constraints for metadata-driven layout relationships such as pinning, filling, insetting, and aspect ratios. Use callbacks only when derived layout needs custom code, multiple child updates, or measurement side effects.

See Fragment Styles for the full fragment lifecycle, data-map, constraints, provider, and callback reference.