✨ [FFL-2596] add flag overrides to the feature flags tab

Builds on FFL-2597: adds the override engine (writes to the inspected
page's localStorage via the DatadogDevtools contract), per-variant
override buttons + revert on each catalog row, a manual override-by-key
form, and clear-all / save-and-reload controls.

Author: kellyw1806

developer-extension/src/panel/components/tabs/flagsTab/flagCatalogList.tsx

@@ -1,18 +1,14 @@
-import { ActionIcon, Badge, Box, Code, CopyButton, Group, Loader, Space, Text, Tooltip } from '@mantine/core'
-import { IconCopy } from '@tabler/icons-react'
-import React from 'react'
-import type { CatalogFlag } from './flagCatalog'
-import type { FlagCatalogState } from './useFlagCatalog'
+import { ActionIcon, Box, Button, Code, CopyButton, Group, Loader, Space, Text, Tooltip } from '@mantine/core'
+import { IconArrowBackUp, IconCopy } from '@tabler/icons-react'
+import React, { type ReactNode } from 'react'
+import type { CatalogFlag } from './flagsRequests'
+import { useFlagsContext } from './flagsContext'
+import { validateOverrideValue } from './flagTypes'
+import { getOverride, type FlagOverride } from './inspectedPageFlags'
+
+export function FlagCatalogBody() {
+  const { catalog, bottomFlags } = useFlagsContext()
 
-export function FlagCatalogBody({
-  catalog,
-  flags,
-  total,
-}: {
-  catalog: FlagCatalogState
-  flags: CatalogFlag[]
-  total: number
-}) {
   if (catalog.loading) {
     return (
       <Group justify="center" py="xl">
@@ -28,31 +24,102 @@ export function FlagCatalogBody({
   return (
     <>
       <Text c="dimmed" size="xs">
-        {total} {total === 1 ? 'flag' : 'flags'}
+        {catalog.total} {catalog.total === 1 ? 'flag' : 'flags'}
       </Text>
       <Space h="xs" />
-      <Box style={{ border: '1px solid var(--mantine-color-gray-2)', borderRadius: 'var(--mantine-radius-sm)' }}>
-        {flags.length === 0 ? (
-          <Text c="dimmed" p="md">
-            No flags match.
-          </Text>
-        ) : (
-          flags.map((flag) => <FlagRow key={flag.key} flag={flag} />)
-        )}
-      </Box>
+      <FlagList
+        flags={bottomFlags}
+        borderColor="var(--mantine-color-gray-2)"
+        // `bottomFlags` is the page minus overridden flags (those are pinned above). Only call it "no
+        // match" when the server total is 0; otherwise this page's flags are all overridden.
+        emptyMessage={
+          catalog.total === 0 ? 'No flags match.' : 'All flags on this page are overridden — see Local overrides above.'
+        }
+      />
+    </>
+  )
+}
+
+/**
+ * The always-visible "Local overrides" section shown above the paginated catalog. Lists every
+ * overridden flag (regardless of which catalog page it's on), so overrides are never buried by
+ * pagination. The overridden flags' catalog data comes from the context (see useOverriddenFlags).
+ */
+export function OverridesSection() {
+  const { overriddenFlags } = useFlagsContext()
+
+  if (overriddenFlags.length === 0) {
+    return null
+  }
+  return (
+    <>
+      <Text fw={600} size="sm">
+        Local overrides ({overriddenFlags.length})
+      </Text>
+      <Space h="xs" />
+      <FlagList flags={overriddenFlags} borderColor="var(--mantine-color-violet-2)" />
     </>
   )
 }
 
-function FlagRow({ flag }: { flag: CatalogFlag }) {
+// Renders a bordered list of flag rows, or `emptyMessage` when there are none. Shared by the catalog
+// body and the "Local overrides" section — they differ only in border color and empty copy. Reads
+// the override state + actions from context so each row's wiring stays identical.
+function FlagList({
+  flags,
+  borderColor,
+  emptyMessage,
+}: {
+  flags: CatalogFlag[]
+  borderColor: string
+  emptyMessage?: ReactNode
+}) {
+  const { overrides, applyOverride, removeOverride } = useFlagsContext()
+  return (
+    <Box style={{ border: `1px solid ${borderColor}`, borderRadius: 'var(--mantine-radius-sm)' }}>
+      {flags.length === 0 ? (
+        <Text c="dimmed" p="md">
+          {emptyMessage}
+        </Text>
+      ) : (
+        flags.map((flag) => (
+          <FlagRow
+            key={flag.key}
+            flag={flag}
+            override={getOverride(overrides, flag.key)}
+            onSelectVariant={applyOverride}
+            onRevert={removeOverride}
+          />
+        ))
+      )}
+    </Box>
+  )
+}
+
+function FlagRow({
+  flag,
+  override,
+  onSelectVariant,
+  onRevert,
+}: {
+  flag: CatalogFlag
+  override: FlagOverride | undefined
+  onSelectVariant: (flagKey: string, override: FlagOverride) => void
+  onRevert: (flagKey: string) => void
+}) {
+  const overridden = override !== undefined
+
   return (
     <Group
       justify="space-between"
       wrap="nowrap"
       align="center"
       px="sm"
       py="xs"
-      style={{ borderBottom: '1px solid var(--mantine-color-gray-1)' }}
+      style={{
+        borderBottom: '1px solid var(--mantine-color-gray-1)',
+        backgroundColor: overridden ? 'var(--mantine-color-violet-0)' : undefined,
+      }}
     >
       <Box style={{ minWidth: 0, flex: 1 }}>
         <Text size="sm" fw={600} truncate>
@@ -61,16 +128,41 @@ function FlagRow({ flag }: { flag: CatalogFlag }) {
         <FlagKey value={flag.key} />
       </Box>
       <Group gap="xs" wrap="wrap" justify="flex-end" style={{ flexShrink: 0, maxWidth: '55%' }}>
+        {overridden && (
+          <Tooltip label="Revert override">
+            <ActionIcon variant="subtle" color="gray" size="sm" onClick={() => onRevert(flag.key)}>
+              <IconArrowBackUp size={16} />
+            </ActionIcon>
+          </Tooltip>
+        )}
         {flag.variants.length === 0 ? (
           <Text c="dimmed" size="xs">
             no variants
           </Text>
         ) : (
-          flag.variants.map((variant) => (
-            <Badge key={variant.name} variant="light" color="gray" title={formatValue(variant.value)}>
-              {variant.name}
-            </Badge>
-          ))
+          flag.variants.map((variant) => {
+            const isActive = overridden && valuesEqual(override.value, variant.value)
+            // The catalog falls back to the raw string when a variant doesn't parse as its
+            // declared type (see parseVariantValue) — writing that through would violate the
+            // same contract validateOverrideValue enforces for manual overrides. `allowNull` keeps
+            // a legitimate JSON `null` variant applyable (a raw-string type mismatch still fails).
+            const validationError = validateOverrideValue(flag.type, variant.value, { allowNull: true })
+            return (
+              <Button
+                key={variant.name}
+                size="compact-xs"
+                variant={isActive ? 'filled' : 'default'}
+                color={isActive ? 'violet' : 'gray'}
+                disabled={!!validationError}
+                onClick={() =>
+                  onSelectVariant(flag.key, { type: flag.type, value: variant.value as FlagOverride['value'] })
+                }
+                title={validationError ?? formatValue(variant.value)}
+              >
+                {variant.name}
+              </Button>
+            )
+          })
         )}
       </Group>
     </Group>
@@ -104,6 +196,10 @@ function FlagKey({ value }: { value: string }) {
   )
 }
 
+function valuesEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b)
+}
+
 function formatValue(value: unknown): string {
   return typeof value === 'string' ? value : JSON.stringify(value)
 }

developer-extension/src/panel/components/tabs/flagsTab/flagFilterBar.tsx

@@ -1,15 +1,16 @@
 import { Group, MultiSelect, Stack, TagsInput, TextInput } from '@mantine/core'
 import { IconSearch } from '@tabler/icons-react'
 import React from 'react'
-import { FLAG_TYPES, TYPE_LABELS } from './flagTypeConstants'
-import type { FlagCatalogView } from './useFlagCatalogView'
+import { FLAG_TYPES, FLAG_TYPE_CONFIG } from './flagTypes'
+import { useFlagsContext } from './flagsContext'
 
 // Type is a fixed set, so its options are static. There's no tags endpoint and we only load a page
 // at a time, so the Tag filter can't show every tag — instead it offers `tagSuggestions` (tags seen
 // on pages loaded so far) as autocomplete while still accepting any typed tag. Search/type/tags are
 // all applied server-side (see useFlagCatalog).
-export function FlagFilterBar({ view, tagSuggestions }: { view: FlagCatalogView; tagSuggestions: string[] }) {
-  const typeOptions = FLAG_TYPES.map((type) => ({ value: type, label: TYPE_LABELS[type] }))
+export function FlagFilterBar() {
+  const { view, tagSuggestions } = useFlagsContext()
+  const typeOptions = FLAG_TYPES.map((type) => ({ value: type, label: FLAG_TYPE_CONFIG[type].label }))
 
   return (
     <Stack gap="xs">

developer-extension/src/panel/components/tabs/flagsTab/flagTypeConstants.ts

@@ -0,0 +1,36 @@
+import { validateOverrideValue, type FlagType } from './flagTypes'
+
+describe('validateOverrideValue', () => {
+  it('accepts values matching their declared type', () => {
+    expect(validateOverrideValue('BOOLEAN', true)).toBeNull()
+    expect(validateOverrideValue('STRING', 'hello')).toBeNull()
+    expect(validateOverrideValue('INTEGER', 3)).toBeNull()
+    expect(validateOverrideValue('NUMERIC', 3.14)).toBeNull()
+    expect(validateOverrideValue('JSON', { a: 1 })).toBeNull()
+  })
+
+  it('returns an error (rather than crashing) for a value_type outside the known union', () => {
+    expect(validateOverrideValue('MYSTERY' as FlagType, 'x')).toContain('Unsupported flag type')
+  })
+
+  it('rejects null by default but accepts a JSON null when allowNull is set', () => {
+    expect(validateOverrideValue('STRING', null)).toBe('Value cannot be null')
+    expect(validateOverrideValue('JSON', null)).toBe('Value cannot be null')
+    // A JSON variant can legitimately be null (typeof null === 'object' matches JSON).
+    expect(validateOverrideValue('JSON', null, { allowNull: true })).toBeNull()
+    // allowNull still enforces the type — null isn't valid for a non-object type.
+    expect(validateOverrideValue('BOOLEAN', null, { allowNull: true })).toContain('must be a boolean')
+  })
+
+  it('rejects type mismatches', () => {
+    expect(validateOverrideValue('BOOLEAN', 'true')).toContain('must be a boolean')
+    expect(validateOverrideValue('STRING', 1)).toContain('must be a string')
+    expect(validateOverrideValue('NUMERIC', 'x')).toContain('must be a number')
+  })
+
+  it('rejects non-integer and unsafe INTEGER values', () => {
+    expect(validateOverrideValue('INTEGER', 3.5)).toContain('whole number')
+    // Beyond Number.MAX_SAFE_INTEGER: not a reliable integer, so reject it too.
+    expect(validateOverrideValue('INTEGER', Number.MAX_SAFE_INTEGER + 1)).toContain('safe integer range')
+  })
+})

developer-extension/src/panel/components/tabs/flagsTab/flagTypes.spec.ts

@@ -0,0 +1,102 @@
+// Shared flag and override types plus the per-type value logic (labels, parsing, validation) they
+// drive. One home for everything that is specific to a flag's value type, imported by both the
+// request/catalog layer and the inspected-page override layer.
+
+// Feature-flag value types, in display order (drives the catalog's Type filter).
+export const FLAG_TYPES = ['BOOLEAN', 'STRING', 'INTEGER', 'NUMERIC', 'JSON'] as const
+
+// The value type of a feature flag (and of an override for it), derived from FLAG_TYPES so the list
+// stays the single source of truth.
+export type FlagType = (typeof FLAG_TYPES)[number]
+
+interface FlagTypeConfig {
+  // Display label matching the webapp's Type filter (NUMERIC shows as "Number").
+  label: string
+  // The JS `typeof` an override of this type must have (the DatadogDevtools wrapper would otherwise
+  // throw at resolve time); used by validateOverrideValue.
+  expectedJsType: 'boolean' | 'string' | 'number' | 'object'
+  // Error copy shown when the manual form fails to parse input of this type. BOOLEAN never fails
+  // (its Switch yields a real boolean), so its message is unreachable but kept for completeness.
+  parseErrorMessage: string
+}
+
+// Per-type display + validation metadata in one descriptor: FLAG_TYPES stays the ordered list, while
+// this is the single exhaustive source of everything specific to each type.
+export const FLAG_TYPE_CONFIG = {
+  BOOLEAN: { label: 'Boolean', expectedJsType: 'boolean', parseErrorMessage: 'Enter true or false' },
+  STRING: { label: 'String', expectedJsType: 'string', parseErrorMessage: 'Enter a value' },
+  INTEGER: {
+    label: 'Integer',
+    expectedJsType: 'number',
+    parseErrorMessage: 'Enter a whole number within the safe integer range',
+  },
+  NUMERIC: { label: 'Number', expectedJsType: 'number', parseErrorMessage: 'Enter a valid number' },
+  JSON: { label: 'JSON', expectedJsType: 'object', parseErrorMessage: 'Enter valid JSON' },
+} satisfies Record<FlagType, FlagTypeConfig>
+
+export type TypedParseResult = { ok: true; value: unknown } | { ok: false }
+
+// Structural parsing rules for a flag value string, shared between the catalog (API variant values,
+// always strings, tolerant of malformed input) and the manual override form (user input, rejects
+// malformed input). BOOLEAN is excluded: the API sends it as the strings 'true'/'false' while the
+// form already gets a JS boolean from its Switch control, so there's no shared string-parsing rule
+// for it. Callers decide what an `{ ok: false }` result means for them (fall back vs. reject).
+export function parseTypedString(type: Exclude<FlagType, 'BOOLEAN'>, raw: string): TypedParseResult {
+  switch (type) {
+    case 'INTEGER': {
+      // Require the whole (trimmed) string to be an integer within the safe range, so a value like
+      // "5abc" or 9007199254740993 isn't silently rounded or truncated.
+      const trimmed = raw.trim()
+      const parsed = Number(trimmed)
+      return /^[+-]?\d+$/.test(trimmed) && Number.isSafeInteger(parsed) ? { ok: true, value: parsed } : { ok: false }
+    }
+    case 'NUMERIC': {
+      // Require a non-empty (trimmed) string that parses fully to a finite number — Number('') is 0
+      // and Number('  ') is also 0, so an all-whitespace input must not be treated as valid.
+      const trimmed = raw.trim()
+      const parsed = Number(trimmed)
+      return trimmed !== '' && Number.isFinite(parsed) ? { ok: true, value: parsed } : { ok: false }
+    }
+    case 'JSON':
+      try {
+        return { ok: true, value: JSON.parse(raw) as unknown }
+      } catch {
+        return { ok: false }
+      }
+    case 'STRING':
+      return { ok: true, value: raw }
+  }
+}
+
+/**
+ * Validates an already-parsed override value against its declared type, returning an error message
+ * or null if valid. This is the value-level counterpart to parseTypedString (which turns a string
+ * into a value): the catalog's variant-click path validates the catalog value directly, and the
+ * manual form validates after parseTypedString produces a value.
+ *
+ * `allowNull` accepts `null` (a valid JSON value that real flag variants can use) — the catalog
+ * passes it so a JSON `null` variant stays applyable; the manual-entry form leaves it off so a
+ * hand-typed empty value is still rejected. Either way a non-JSON `null` still fails the type check.
+ */
+export function validateOverrideValue(
+  type: FlagType,
+  value: unknown,
+  { allowNull = false }: { allowNull?: boolean } = {}
+): string | null {
+  if (value === null && !allowNull) {
+    return 'Value cannot be null'
+  }
+  const config: FlagTypeConfig | undefined = FLAG_TYPE_CONFIG[type]
+  if (!config) {
+    // The catalog API can return a value_type outside our union (a compile-time assumption, not a
+    // runtime guarantee — see parseVariantValue); reject rather than crash on a missing descriptor.
+    return `Unsupported flag type: ${type}`
+  }
+  if (typeof value !== config.expectedJsType) {
+    return `Value must be a ${config.expectedJsType} for type ${type}`
+  }
+  if (type === 'INTEGER' && !Number.isSafeInteger(value)) {
+    return 'INTEGER value must be a whole number within the safe integer range'
+  }
+  return null
+}