@djangocfg/ui-tools 2.1.431 → 2.1.432

package/src/tools/dev/Map/layers/symbol.ts

@@ -0,0 +1,93 @@
+import type { LayerProps, SymbolLayerSpecification } from 'react-map-gl/maplibre'
+import type { SymbolLayerOptions } from '../types'
+
+/**
+ * `layout` / `paint` on `SymbolLayerSpecification` are declared optional
+ * (`layout?: {…}`), so `SymbolLayerSpecification['layout']` widens to
+ * `{…} | undefined`. Indexing that union per-key (e.g.
+ * `SymbolLayerSpecification['layout']['icon-image']`) is what leaks
+ * TS2339 into stricter consumer typechecks (cmdop's `tsc --noEmit`).
+ * Strip the `| undefined` once here so the rest of the file builds a
+ * single, fully-typed object literal instead of per-key indexed casts.
+ */
+type SymbolLayout = NonNullable<SymbolLayerSpecification['layout']>
+type SymbolPaint = NonNullable<SymbolLayerSpecification['paint']>
+
+/**
+ * Create a `symbol` layer that draws a registered icon (and optional text
+ * label) per feature — the data-driven path for many icons at scale.
+ *
+ * Register the icon image first with the `useMapImages` hook, then pass its
+ * id (or a data-driven expression like `['get', 'icon']`) as `iconImage`.
+ *
+ * Two ways to do custom markers:
+ * - **For a few rich markers**, use a DOM `MapMarker` with `children` (or its
+ *   `color`/`size` props) — full React content per marker.
+ * - **For many data-driven icons at scale**, use this symbol layer over a
+ *   GeoJSON source: MapLibre renders the icons on the GPU from the sprite.
+ *
+ * @example
+ * ```tsx
+ * useMapImages([{ id: 'pin', url: '/icons/pin.png' }])
+ * const layer = createSymbolLayer({
+ *   id: 'places',
+ *   sourceId: 'places-src',
+ *   iconImage: 'pin',
+ *   iconSize: 0.5,
+ *   textField: ['get', 'name'],
+ * })
+ * ```
+ */
+export function createSymbolLayer({
+  id,
+  sourceId,
+  iconImage,
+  iconSize,
+  iconAllowOverlap = true,
+  textField,
+  textSize = 12,
+  textColor = '#1f2937',
+  textOffset = [0, 1.2],
+  minZoom,
+  maxZoom,
+}: SymbolLayerOptions): LayerProps {
+  // Build one fully-typed `layout` literal up front (all keys present-or-
+  // omitted), so TS checks it as a unit against `SymbolLayout` rather than
+  // assigning per-key into a `… | undefined` indexed type. The option
+  // values are the author's loosened `DataDrivenValue<…>` (static value OR
+  // expression array); each is asserted to its concrete layout-property
+  // type via the non-nullable `SymbolLayout[…]` indexed access.
+  const labelKeys: Partial<SymbolLayout> =
+    textField !== undefined
+      ? {
+          'text-field': textField as SymbolLayout['text-field'],
+          'text-size': textSize as SymbolLayout['text-size'],
+          'text-offset': textOffset,
+          'text-anchor': 'top',
+        }
+      : {}
+
+  const layout: SymbolLayout = {
+    'icon-image': iconImage as SymbolLayout['icon-image'],
+    'icon-allow-overlap': iconAllowOverlap,
+    ...(iconSize !== undefined
+      ? { 'icon-size': iconSize as SymbolLayout['icon-size'] }
+      : {}),
+    ...labelKeys,
+  }
+
+  const paint: SymbolPaint = textField !== undefined ? { 'text-color': textColor } : {}
+
+  const layer: LayerProps = {
+    id,
+    type: 'symbol',
+    source: sourceId,
+    layout,
+    paint,
+  }
+
+  if (minZoom !== undefined) layer.minzoom = minZoom
+  if (maxZoom !== undefined) layer.maxzoom = maxZoom
+
+  return layer
+}

package/src/tools/dev/Map/lazy.tsx

@@ -78,19 +78,50 @@ export {
   CustomOverlay,
   MapLegend,
   LayerSwitcher,
+  MeasureControl,
+  DraggableMarkers,
+  GeocoderInput,
+  GeocoderControl,
+  CompassChip,
+  MarkerCard,
+  MapMarkers,
 } from './components';
 
+export type { DraggableMarkersProps, DraggablePoint } from './components';
+export type { GeocoderInputProps, GeocoderControlProps } from './components';
+export type { CompassChipProps } from './components';
+// Marker info-cards — light wrappers (no maplibre at module scope), safe on
+// the synchronous surface. `MarkerCard` data type lives in `./cards`.
+export type {
+  MarkerCardProps,
+  MapMarkersProps,
+  MarkerWithCard,
+  MarkerCardAction,
+  MarkerCardData,
+  MarkerCardActionData,
+} from './components';
+// Card-data shape under `MarkerCardInfo` (the `MarkerCard` value is the
+// component re-exported above).
+export type { MarkerCard as MarkerCardInfo } from './cards';
+
+// Geocoder resolver — pure, key-free Photon (light; no maplibre runtime).
+export { photonResolve, cameraForResult } from './geocode';
+export type { GeocodeResult, GeocodeKind, ResolveGeocode } from './geocode';
+
 export { MapProvider, useMapContext, MapContext } from './context';
 export type { MapProviderProps } from './context';
 
 export type {
   MapContainerProps,
+  GeolocateOptions,
+  GeolocatePosition,
   MapMarkerProps,
   MapPopupProps,
   MapClusterProps,
   MapSourceProps,
   MapLayerProps,
   MapControlsProps,
+  MeasureControlProps,
 } from './components';
 
 export type {
@@ -98,3 +129,92 @@ export type {
   MapStyleKey,
   MarkerData,
 } from './types';
+
+// Basemap styles (incl. free OpenFreeMap keys) + PMTiles protocol helper —
+// light, safe to load synchronously alongside the lazy container.
+export {
+  MAP_STYLES,
+  getMapStyle,
+  MAP_STYLE_LABELS,
+  KEY_FREE_STYLES,
+  resolveBasemapOptions,
+  TERRAIN_DEM,
+  TERRAIN_DEM_URL,
+} from './styles';
+export { addPMTilesProtocol, pmtilesSourceUrl } from './protocols/pmtiles';
+
+// Hooks — pure React glue (maplibre is a TYPE-only import here, so these
+// add no runtime weight and are safe on the synchronous lazy surface).
+export {
+  useMap,
+  useMapControl,
+  useMarkers,
+  useMapEvents,
+  useMapViewport,
+  useMapLayers,
+  useSpiderfy,
+  useMapTouchMode,
+  useMapScrollProtection,
+  useMapImages,
+  useMeasure,
+  useTerrain,
+  useCompass,
+  useGeolocation,
+  useControl,
+  useDraggableMarkers,
+  useGeocoder,
+  useMarkerCard,
+  type UseMarkerCardResult,
+  type UseCompassResult,
+  type UseGeocoderOptions,
+  type UseGeocoderResult,
+  type UseSpiderfyOptions,
+  type UseSpiderfyResult,
+  type MapImage,
+  type UseMapImagesResult,
+  type UseMeasureResult,
+  type MeasureMode,
+  type UseTerrainOptions,
+  type GeolocationFix,
+  type GeolocationStatus,
+  type UseGeolocationOptions,
+  type UseGeolocationResult,
+  type UseDraggableMarkersOptions,
+  type UseDraggableMarkersResult,
+  type DraggableMarkerHandlers,
+} from './hooks';
+
+// Layer factories — pure functions returning `LayerProps` (type-only deps).
+export {
+  createClusterLayers,
+  createPointLayer,
+  createHeatmapLayer,
+  createPolygonLayer,
+  createPolygonOutlineLayer,
+  createHighlightLayer,
+  createLineLayer,
+  createRouteLayers,
+  createDashedLineLayer,
+  createAnimatedLineLayer,
+  createSymbolLayer,
+} from './layers';
+
+// Geometry + spiderfy utils — pure, dependency-free helpers.
+export {
+  calculateBounds,
+  calculateCenter,
+  calculateDistance,
+  isPointInBounds,
+  expandBounds,
+  toGeoJSON,
+  fromGeoJSON,
+  createPoint,
+  createPolygon,
+  createLineString,
+  createFeatureCollection,
+  offsetOverlappingMarkers,
+  getSpiderfyPositions,
+  groupOverlappingMarkers,
+  hasOverlappingMarkers,
+  getOverlapStats,
+} from './utils';

package/src/tools/dev/Map/protocols/pmtiles.ts

@@ -0,0 +1,73 @@
+'use client'
+
+/**
+ * PMTiles protocol registration for MapLibre.
+ *
+ * PMTiles is a single-file basemap format (Protomaps, BSD + ODbL) that
+ * MapLibre reads DIRECTLY in the browser via HTTP range requests — no tile
+ * server, no API key. Host one `.pmtiles` file on any static CDN (S3/R2/
+ * GitHub Pages) for a self-hosted / offline basemap.
+ *
+ * Usage (register ONCE per app lifecycle, e.g. in a top-level effect):
+ *
+ * ```ts
+ * import maplibregl from 'maplibre-gl';
+ * import { addPMTilesProtocol } from '@djangocfg/ui-tools/map';
+ *
+ * useEffect(() => addPMTilesProtocol(maplibregl), []); // returns a cleanup fn
+ * ```
+ *
+ * Then reference the file from a style/source with a `pmtiles://` URL:
+ *
+ * ```ts
+ * // source url:  pmtiles://https://your-cdn.example/basemap.pmtiles
+ * ```
+ *
+ * The `pmtiles` package is dynamically imported so it costs nothing until a
+ * consumer actually opts into PMTiles.
+ */
+
+/** Minimal shape of the maplibre-gl module we touch (avoids a hard dep). */
+interface MapLibreLike {
+  addProtocol: (
+    name: string,
+    handler: (...args: unknown[]) => unknown,
+  ) => void
+  removeProtocol: (name: string) => void
+}
+
+const PROTOCOL = 'pmtiles'
+
+/**
+ * Register the `pmtiles://` protocol on the given maplibre-gl module.
+ * Returns a cleanup function that removes it — wire it as an effect's
+ * teardown. Safe to call once; calling again re-registers (idempotent at
+ * the maplibre level, last handler wins).
+ */
+export function addPMTilesProtocol(maplibregl: MapLibreLike): () => void {
+  let cancelled = false
+
+  // Dynamic import keeps `pmtiles` out of the bundle until used.
+  void import('pmtiles').then(({ Protocol }) => {
+    if (cancelled) return
+    const protocol = new Protocol()
+    maplibregl.addProtocol(
+      PROTOCOL,
+      protocol.tile as (...args: unknown[]) => unknown,
+    )
+  })
+
+  return () => {
+    cancelled = true
+    try {
+      maplibregl.removeProtocol(PROTOCOL)
+    } catch {
+      // protocol may not have registered yet (import still in flight)
+    }
+  }
+}
+
+/** Build a `pmtiles://` source URL from a plain https URL to a `.pmtiles` file. */
+export function pmtilesSourceUrl(fileUrl: string): string {
+  return `${PROTOCOL}://${fileUrl}`
+}

package/src/tools/dev/Map/styles/index.ts

@@ -1,8 +1,28 @@
+/**
+ * Built-in basemap styles.
+ *
+ * `light` / `dark` / `streets` — CARTO, free, no API key.
+ * `satellite` — MapTiler, **needs an API key** in the URL (not injected
+ *   here; pass your own keyed style URL to `mapStyle` to use it).
+ * `liberty` / `bright` / `positron` — **OpenFreeMap** public instance:
+ *   genuinely free, no key, no limits, commercial use allowed (donation-
+ *   funded, no SLA). See `@plans/plan14-map-capabilities`.
+ *
+ * For a self-hosted / offline single-file basemap, use the PMTiles helper
+ * (`addPMTilesProtocol`) and pass a `pmtiles://…`-backed style instead.
+ */
+// Free DEM source for 3D terrain + hillshade (AWS Terrarium, key-free).
+export { TERRAIN_DEM, TERRAIN_DEM_URL } from './terrain'
+
 export const MAP_STYLES = {
   light: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
   dark: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
   streets: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json',
   satellite: 'https://api.maptiler.com/maps/satellite/style.json',
+  // OpenFreeMap — key-free, no limits, commercial OK.
+  liberty: 'https://tiles.openfreemap.org/styles/liberty',
+  bright: 'https://tiles.openfreemap.org/styles/bright',
+  positron: 'https://tiles.openfreemap.org/styles/positron',
 } as const
 
 export type MapStyleKey = keyof typeof MAP_STYLES
@@ -13,3 +33,45 @@ export function getMapStyle(key: MapStyleKey | string): string {
   }
   return key
 }
+
+/** Human label for the basemap switcher menu. */
+export const MAP_STYLE_LABELS: Record<MapStyleKey, string> = {
+  light: 'Light',
+  dark: 'Dark',
+  streets: 'Streets',
+  satellite: 'Satellite',
+  liberty: 'Liberty',
+  bright: 'Bright',
+  positron: 'Positron',
+}
+
+/** Basemap keys that work with NO API key (safe to always offer). */
+export const KEY_FREE_STYLES: readonly MapStyleKey[] = [
+  'light',
+  'dark',
+  'streets',
+  'liberty',
+  'bright',
+  'positron',
+]
+
+/**
+ * Pick the basemap options to show in the switcher, smartly:
+ * - all key-free built-ins, PLUS
+ * - `satellite` ONLY when usable — i.e. the host passed its own keyed
+ *   satellite style (a full URL via `mapStyle`/`current`), since the
+ *   built-in MapTiler satellite needs a key we don't ship.
+ *
+ * A host can override entirely by passing an explicit `requested` list.
+ */
+export function resolveBasemapOptions(
+  requested: readonly MapStyleKey[] | undefined,
+  current: MapStyleKey | string | undefined,
+): MapStyleKey[] {
+  if (requested && requested.length) return [...requested]
+  const opts: MapStyleKey[] = [...KEY_FREE_STYLES]
+  // Offer satellite only if the active style is a host-supplied URL (keyed)
+  // OR the current key is already 'satellite' (host wired a key elsewhere).
+  if (current === 'satellite') opts.push('satellite')
+  return opts
+}

package/src/tools/dev/Map/styles/terrain.ts

@@ -0,0 +1,29 @@
+'use client'
+
+/**
+ * Free DEM (digital-elevation-model) source for 3D terrain + hillshade.
+ *
+ * Uses **AWS Terrain Tiles** — Terrarium-encoded elevation PNGs served as
+ * free, open data from the public `elevation-tiles-prod` S3 bucket. No API
+ * key, no account, no usage limit. MapLibre renders 3D terrain and hillshade
+ * natively from a `raster-dem` source — no external tile service needed.
+ *
+ * See `@plans/plan14-map-capabilities` / `reports/research.md` §2.
+ */
+import type { RasterDEMSourceSpecification } from 'maplibre-gl'
+
+/** Terrarium-encoded DEM tile URL template (AWS open data, key-free). */
+export const TERRAIN_DEM_URL =
+  'https://elevation-tiles-prod.s3.amazonaws.com/terrarium/{z}/{x}/{y}.png'
+
+/**
+ * Ready-to-use `raster-dem` source spec for the free AWS Terrarium DEM.
+ * Pass straight to `map.addSource(id, TERRAIN_DEM)`.
+ */
+export const TERRAIN_DEM: RasterDEMSourceSpecification = {
+  type: 'raster-dem',
+  tiles: [TERRAIN_DEM_URL],
+  encoding: 'terrarium',
+  tileSize: 256,
+  maxzoom: 15,
+}

package/src/tools/dev/Map/types.ts

@@ -65,7 +65,7 @@ export interface MapContextValue {
 export interface MapControlActions {
   flyTo: (center: [number, number], zoom?: number, options?: { duration?: number }) => void
   easeTo: (center: [number, number], zoom?: number, options?: { duration?: number }) => void
-  fitBounds: (bounds: LngLatBoundsLike, options?: { padding?: number; duration?: number }) => void
+  fitBounds: (bounds: LngLatBoundsLike, options?: { padding?: number; duration?: number; maxZoom?: number }) => void
   zoomIn: () => void
   zoomOut: () => void
   resetView: (initialViewport: MapViewport) => void
@@ -80,7 +80,7 @@ export interface MarkerActions {
   removeMarker: (id: string) => void
   updateMarker: (id: string, updates: Partial<Omit<MarkerData, 'id'>>) => void
   clearMarkers: () => void
-  fitToMarkers: (padding?: number) => void
+  fitToMarkers: (paddingOrOpts?: number | { padding?: number; maxZoom?: number }) => void
 }
 
 // ============================================================================
@@ -108,7 +108,9 @@ export interface MapMouseEvent {
 // Style Types
 // ============================================================================
 
-export type MapStyleKey = 'light' | 'dark' | 'streets' | 'satellite'
+// Single source of truth — derived from `MAP_STYLES` so new basemap keys
+// (e.g. OpenFreeMap `liberty`/`bright`/`positron`) flow through automatically.
+export type { MapStyleKey } from './styles'
 
 // ============================================================================
 // Layer Types (from react-map-gl & maplibre-gl)
@@ -167,6 +169,32 @@ export interface RouteLayerOptions extends Omit<LineLayerOptions, 'id'> {
   sourceId: string
 }
 
+// ============================================================================
+// Symbol Layer Types
+// ============================================================================
+
+/** A data-driven expression (e.g. `['get', 'icon']`) or a static value. */
+export type DataDrivenValue<T> = T | unknown[]
+
+export interface SymbolLayerOptions {
+  id: string
+  sourceId: string
+  /**
+   * Registered image id (see `useMapImages`) OR a data-driven expression
+   * selecting one per feature, e.g. `['get', 'icon']`.
+   */
+  iconImage: DataDrivenValue<string>
+  iconSize?: DataDrivenValue<number>
+  iconAllowOverlap?: boolean
+  /** Property name or expression for an optional text label. */
+  textField?: DataDrivenValue<string>
+  textSize?: DataDrivenValue<number>
+  textColor?: string
+  textOffset?: [number, number]
+  minZoom?: number
+  maxZoom?: number
+}
+
 // ============================================================================
 // Control Types
 // ============================================================================

package/src/tools/dev/api/OpenapiViewer/components/DocsLayout/EndpointDoc/Header/MetaActions.tsx

@@ -47,7 +47,7 @@ function IconButton({ label, onClick, children, active }: IconButtonProps) {
                     className={cn(
                         'shrink-0 h-6 w-6 inline-flex items-center justify-center rounded',
                         'text-muted-foreground/60 hover:text-foreground hover:bg-muted transition-colors',
-                        active && 'text-emerald-500 hover:text-emerald-500',
+                        active && 'text-success hover:text-success',
                     )}
                 >
                     {children}

package/src/tools/dev/api/OpenapiViewer/components/DocsLayout/EndpointDoc/Responses/StatusTag.tsx

@@ -2,25 +2,18 @@
 
 import { cn } from '@djangocfg/ui-core/lib';
 
+import { getStatusCodeStyle } from '../../../shared/http-colors';
+
 interface StatusTagProps {
     code: string;
 }
 
-/** HTTP status pill. Colours map to the usual conventions: 2xx green,
- *  3xx blue, 4xx amber, 5xx red, non-numeric (``default``) neutral.
+/** HTTP status pill. Colours map to the usual conventions: 2xx success,
+ *  3xx info, 4xx warning, 5xx destructive, non-numeric (``default``) neutral.
  *  Codes that don't parse as integers render in the neutral style so we
  *  never flash a wrong-severity colour at the user. */
 export function StatusTag({ code }: StatusTagProps) {
-    const numeric = Number.parseInt(code, 10);
-    const cls = !Number.isFinite(numeric)
-        ? 'bg-muted text-muted-foreground border-border'
-        : numeric >= 500
-            ? 'bg-red-500/10 text-red-600 dark:text-red-400 border-red-500/25'
-            : numeric >= 400
-                ? 'bg-amber-500/10 text-amber-600 dark:text-amber-400 border-amber-500/25'
-                : numeric >= 300
-                    ? 'bg-blue-500/10 text-blue-600 dark:text-blue-400 border-blue-500/25'
-                    : 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border-emerald-500/25';
+    const cls = getStatusCodeStyle(code);
     return (
         <span className={cn(
             'inline-flex items-center justify-center rounded border px-2 py-0.5 font-mono text-[11px] font-bold leading-none shrink-0 tabular-nums',

package/src/tools/dev/api/OpenapiViewer/components/DocsLayout/EndpointDoc/Section/SectionHeader.tsx

@@ -77,7 +77,7 @@ export function SectionHeader({ sectionId, title, badge, open, onToggle }: Secti
                 className={cn(
                     'ml-auto shrink-0 p-1 rounded text-muted-foreground/40 hover:text-foreground hover:bg-muted transition-all',
                     'opacity-0 group-hover/section:opacity-100 focus-visible:opacity-100',
-                    copied && 'opacity-100 text-emerald-500',
+                    copied && 'opacity-100 text-success',
                 )}
             >
                 {copied ? <Check className="h-3 w-3" /> : <Link2 className="h-3 w-3" />}

package/src/tools/dev/api/OpenapiViewer/components/DocsLayout/SchemaCopyMenu.tsx

@@ -167,7 +167,7 @@ export function SchemaCopyMenu({ schema, endpoints, baseUrl, variant = 'button',
                             <div className="flex w-full items-center gap-2">
                                 <span className="text-xs font-medium flex-1">{label.title}</span>
                                 {isDone ? (
-                                    <span className="inline-flex items-center gap-1 text-[10px] text-emerald-500">
+                                    <span className="inline-flex items-center gap-1 text-[10px] text-success">
                                         <Check className="h-3 w-3" /> Copied
                                     </span>
                                 ) : size ? (

package/src/tools/dev/api/OpenapiViewer/components/shared/SendButton.tsx

@@ -62,7 +62,7 @@ export function SendButton({ className }: SendButtonProps) {
     return (
         <div className={cn('space-y-2', className)}>
             {blockers.length > 0 && (
-                <div className="flex items-start gap-2 rounded-md border border-amber-500/25 bg-amber-500/[0.06] px-3 py-2 text-[11px] text-amber-600 dark:text-amber-400">
+                <div className="flex items-start gap-2 rounded-md border border-warning-border bg-warning-background px-3 py-2 text-[11px] text-warning-foreground">
                     <AlertCircle className="h-3.5 w-3.5 shrink-0 mt-px" />
                     <span className="leading-snug">{blockers[0]}</span>
                 </div>

package/src/tools/dev/api/OpenapiViewer/components/shared/http-colors.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared HTTP method + status → semantic status-token mappings.
+ *
+ * Single source of truth for the badge colours used across the OpenAPI
+ * viewer (method pills in the request list, status pills in responses).
+ * Uses ui-core's semantic status surface tokens (the tinted banner set:
+ * `bg-{status}-background` + `text-{status}-foreground` + `border-{status}-border`)
+ * so badges adapt to theme + preset instead of hardcoded colour scales.
+ *
+ * HTTP → status mapping:
+ *   2xx / GET → success · 3xx → info · 4xx / PUT / PATCH → warning ·
+ *   5xx / DELETE → destructive · POST → info.
+ */
+
+type StatusKind = 'success' | 'info' | 'warning' | 'destructive';
+
+const BADGE_CLASS: Record<StatusKind, string> = {
+    success: 'bg-success-background text-success-foreground border-success-border',
+    info: 'bg-info-background text-info-foreground border-info-border',
+    warning: 'bg-warning-background text-warning-foreground border-warning-border',
+    destructive: 'bg-destructive-background text-destructive-foreground border-destructive-border',
+};
+
+const NEUTRAL_BADGE = 'bg-muted text-muted-foreground border-border';
+
+const METHOD_KIND: Record<string, StatusKind> = {
+    GET: 'success',
+    POST: 'info',
+    PUT: 'warning',
+    PATCH: 'warning',
+    DELETE: 'destructive',
+};
+
+/** Badge classes for an HTTP method. Unknown methods fall back to neutral. */
+export function getMethodStyle(method: string): string {
+    const kind = METHOD_KIND[method.toUpperCase()];
+    return kind ? BADGE_CLASS[kind] : NEUTRAL_BADGE;
+}
+
+function statusKind(status: number): StatusKind {
+    if (status >= 500) return 'destructive';
+    if (status >= 400) return 'warning';
+    if (status >= 300) return 'info';
+    return 'success';
+}
+
+/** Badge classes for a numeric HTTP status code. */
+export function getStatusStyle(status: number): string {
+    return BADGE_CLASS[statusKind(status)];
+}
+
+/**
+ * Badge classes for an HTTP status *code string* (e.g. ``"200"``,
+ * ``"default"``). Non-numeric codes render neutral so we never flash a
+ * wrong-severity colour at the user.
+ */
+export function getStatusCodeStyle(code: string): string {
+    const numeric = Number.parseInt(code, 10);
+    if (!Number.isFinite(numeric)) return NEUTRAL_BADGE;
+    return getStatusStyle(numeric);
+}

package/src/tools/dev/api/OpenapiViewer/components/shared/ui.tsx

@@ -12,27 +12,10 @@ import React from 'react';
 import { cn } from '@djangocfg/ui-core/lib';
 
 // ─── Style helpers ────────────────────────────────────────────────────────────
-
-const METHOD_STYLES: Record<string, string> = {
-    GET:    'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border-emerald-500/25',
-    POST:   'bg-blue-500/10    text-blue-600    dark:text-blue-400    border-blue-500/25',
-    PUT:    'bg-amber-500/10   text-amber-600   dark:text-amber-400   border-amber-500/25',
-    PATCH:  'bg-orange-500/10  text-orange-600  dark:text-orange-400  border-orange-500/25',
-    DELETE: 'bg-red-500/10     text-red-600     dark:text-red-400     border-red-500/25',
-} as const;
-
-const METHOD_FALLBACK = 'bg-muted text-muted-foreground border-border';
-
-export function getMethodStyle(method: string): string {
-    return METHOD_STYLES[method.toUpperCase()] ?? METHOD_FALLBACK;
-}
-
-export function getStatusStyle(status: number): string {
-    if (status >= 500) return 'bg-red-500/10 text-red-500 dark:text-red-400 border-red-500/25';
-    if (status >= 400) return 'bg-amber-500/10 text-amber-600 dark:text-amber-400 border-amber-500/25';
-    if (status >= 300) return 'bg-blue-500/10 text-blue-600 dark:text-blue-400 border-blue-500/25';
-    return 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border-emerald-500/25';
-}
+// Method/status → semantic status-token mappings live in ./http-colors and are
+// re-exported here so existing imports of `./ui` keep working.
+export { getMethodStyle, getStatusStyle } from './http-colors';
+import { getMethodStyle, getStatusStyle } from './http-colors';
 
 // ``relativePath`` lives in utils/url.ts now — re-exported here so every
 // component that used to import it from ``./ui`` keeps working.