Adding Configuration Fields

Overview

Configuration fields control combat conditions, buff stacks, and other build parameters that affect damage calculations. They are persisted in SaveData and editable via the Configuration tab UI.

When to Use

Adding a new toggle (boolean) or numeric parameter for damage calculations
Adding conditional combat states (e.g., "has X recently", "enemy has Y")
Adding stack counts for buffs/debuffs
Adding enemy stat overrides

Project File Locations

Purpose	File Path
Configuration interface & defaults	`src/tli/core.ts`
Zod validation schema	`src/lib/schemas/config.schema.ts`
Configuration tab UI	`src/components/configuration/ConfigurationTab.tsx`
Calculation usage	`src/tli/calcs/offense.ts` (and other calcs files)

Implementation Checklist

1. Add Field to Configuration Interface (`src/tli/core.ts`)

Add the field to the Configuration interface with a default comment:

Boolean field (default false):

// default to false
newFieldEnabled: boolean;

Required number field (has a sensible non-undefined default):

// default to 1
numThings: number;

Optional number field (undefined means "use calculated default/max"):

// default to max
someStacks?: number;

2. Add Default Value to `DEFAULT_CONFIGURATION` (`src/tli/core.ts`)

Add the matching default in DEFAULT_CONFIGURATION:

// Boolean → false, Required number → the default, Optional number → undefined
newFieldEnabled: false,
numThings: 1,
someStacks: undefined,

3. Add Schema Validation (`src/lib/schemas/config.schema.ts`)

Add to ConfigurationPageSchema using the d alias for defaults. The pattern depends on the field type:

Boolean:

newFieldEnabled: z.boolean().catch(d.newFieldEnabled),

Required number:

numThings: z.number().catch(d.numThings),

Optional number:

someStacks: z.number().optional().catch(d.someStacks),

The satisfies z.ZodType<Configuration> at the end of the schema ensures the schema stays in sync with the interface — a type error will occur if you miss a field or get the type wrong.

4. Add UI Controls (`src/components/configuration/ConfigurationTab.tsx`)

The configuration tab uses a 2-column grid: grid-cols-[auto_auto] with label on the left, control on the right.

NumberInput field (required number):

<label className="text-right text-zinc-50">
  Field Label
  <InfoTooltip text="Description of what this does. Defaults to X." />
</label>
<NumberInput
  value={config.numThings}
  onChange={(v) => onUpdate({ numThings: v ?? 1 })}
  min={1}
/>

NumberInput field (optional number, undefined = max/default):

<label className="text-right text-zinc-50">
  Stack Count
  <InfoTooltip text="Defaults to max" />
</label>
<NumberInput
  value={config.someStacks}
  onChange={(v) => onUpdate({ someStacks: v })}
  min={0}
/>

Checkbox field (boolean):

<label className="text-right text-zinc-50">Field Label</label>
<input
  type="checkbox"
  checked={config.newFieldEnabled}
  onChange={(e) => onUpdate({ newFieldEnabled: e.target.checked })}
  className="h-4 w-4 rounded border-zinc-600 bg-zinc-800 accent-amber-500"
/>

Checkbox with conditional child NumberInput (boolean toggle + optional stacks):

<label className="text-right text-zinc-50">Has Effect</label>
<input
  type="checkbox"
  checked={config.hasEffect}
  onChange={(e) => onUpdate({ hasEffect: e.target.checked })}
  className="h-4 w-4 rounded border-zinc-600 bg-zinc-800 accent-amber-500"
/>

{config.hasEffect && (
  <>
    <label className="text-right text-zinc-50">
      Effect Stacks
      <InfoTooltip text="Defaults to max" />
    </label>
    <NumberInput
      value={config.effectStacks}
      onChange={(v) => onUpdate({ effectStacks: v })}
      min={0}
    />
  </>
)}

Conditionally rendered field (only show when loadout has something):

{hasPactspirit("Some Pactspirit", loadout) && (
  <>
    <label className="text-right text-zinc-50">
      Some Stacks
      <InfoTooltip text="Defaults to max" />
    </label>
    <NumberInput
      value={config.someStacks}
      onChange={(v) => onUpdate({ someStacks: v })}
      min={0}
      max={6}
    />
  </>
)}

5. Use in Calculations (if applicable)

Access the field via the config parameter in calculation functions:

// In src/tli/calcs/offense.ts or related files
const numActiveTangles = config.numActiveTangles;

6. Verify

pnpm typecheck
pnpm check
pnpm test

Field Type Decision Guide

Scenario	Interface Type	Default	Schema
On/off toggle	`boolean`	`false`	`z.boolean().catch(d.x)`
Count with known default	`number`	the value	`z.number().catch(d.x)`
Count where undefined = "use max"	`number?`	`undefined`	`z.number().optional().catch(d.x)`
Override where undefined = "use calculated"	`number?`	`undefined`	`z.number().optional().catch(d.x)`

onChange Patterns for NumberInput

Required number: onChange={(v) => onUpdate({ field: v ?? defaultValue })} — fallback to default when cleared
Optional number: onChange={(v) => onUpdate({ field: v })} — allow undefined (cleared = use default/max)

Where to Place in the UI

Place new fields in the grid inside ConfigurationTab near related fields. General grouping:

Top: Level, Fervor, Frostbite, hero-specific
Middle: Player conditions (blessings, mana, movement, aggression)
Middle: Enemy conditions (resistances, armor, debuffs, ailments)
Bottom: Buff stacks, skill-specific counts

Automatic Persistence

No additional work is needed for persistence. The field flows through:

Configuration interface → DEFAULT_CONFIGURATION → ConfigurationPageSchema → SaveData → Zustand store → localStorage

The store's updateConfiguration action handles partial updates via spread, and the schema's .catch() ensures old saves without the new field get the default value.

add-configuration