SOR Config 01 - Source mapping editor

v0.1.1

Maps a record to an external source: which connection to read, which fields identify and date it, and which source status values roll up into which outcome. Fully generic over the field and category keys the caller defines.

View as Markdown

Preview

Open full page ↗

Install & usage

npx shadcn@4.1.2 add @signalos/sor-config-01

Pulls the page source plus its widget dependencies (@signalos/tokens, @signalos/utils, @signalos/button, @signalos/input, @signalos/skeleton, @signalos/combobox, @signalos/confirm-dialog, @signalos/data-primitives, @signalos/page-header, @signalos/status-badge, @signalos/text-field) into your app - you own the copy. Requires access.

usage

// after: npx shadcn@4.1.2 add @signalos/sor-config-01
// mount the pulled page in a route, e.g. src/app/sor-config/page.tsx
import { SorConfig01 } from "@/components/blocks/sor-config-01/SorConfig01"

export default function Page() {
  return <SorConfig01 />
}

Props

SorConfig01LinkProps

Prop	Type	Default
href*	`string`	-
className	`string \| undefined`	-
children*	`ReactNode`	-

ConnectionLike

Prop	Type	Default	Description
id*	`string`	-
name*	`string`	-

SorConfig01Check

Prop	Type	Default	Description
message*	`ReactNode`	-

SorConfig01FieldSpec

Prop	Type	Default
key*	`TFieldKey`	-
label*	`string`	-
placeholder	`string \| undefined`	-
required	`boolean \| undefined`	false
helper	`ReactNode`	-

SorConfig01CategorySpec

Prop	Type	Default	Description
key*	`TCategoryKey`	-
label*	`ReactNode`	-	Display label, e.g. "Resolved".
reward*	`ReactNode`	-	Score or weight shown beside the label, e.g. "+1.0".
tone	`"neutral" \| "positive" \| "negative" \| "partial" \| undefined`	"neutral"
placeholder	`string \| undefined`	-

SorConfig01Diff

Prop	Type	Default
field*	`string`	-
label*	`string`	-
draftValue*	`string`	-
proposedValue*	`string`	-

SorConfig01ApiError

Prop	Type	Default	Description
kind*	`"outage" \| "refused" \| "absent" \| "unknown"`	-	`outage` - the source could not be reached, offers a retry. `refused` - the source was reached and rejected the request. `absent` - the requested record does not exist. `unknown` - anything else.
detail*	`ReactNode`	-

SorConfig01SaveOutcome

Prop	Type	Default	Description
ok*	`boolean`	-
droppedFieldLabels*	`string[]`	-	Field labels that did not round-trip when `ok` is false.

SorConfig01Props

Prop	Type	Default	Description
recordName*	`ReactNode`	-	Name of the record this mapping belongs to, e.g. a pipeline name.
isMapped	`boolean \| undefined`	false
savedCaption	`ReactNode`	-	Pre-formatted "Last saved …" caption; omit to hide.
backHref*	`string`	-
backLabel	`ReactNode`	-
LinkComponent	`ComponentType<SorConfig01LinkProps> \| undefined`	-	Router link renderer for the back link; a plain `<a>` by default.
connections*	`ConnectionLike[]`	-
connectionId*	`string`	-
onConnectionChange*	`(id: string) => void`	-
isConnectionMissing	`boolean \| undefined`	false
connectionSearchPlaceholder	`string \| undefined`	-
onPropose*	`() => void`	-
isProposing	`boolean \| undefined`	false
canPropose	`boolean \| undefined`	false
proposeError	`SorConfig01ApiError \| null \| undefined`	-
isProposalWrongConnection	`boolean \| undefined`	-	True once a proposal exists but points at a different connection than the form.
onClearFields	`(() => void) \| undefined`	-
proposalSummary	`ReactNode`	-
isProposalUnverified	`boolean \| undefined`	false
proposalUnverifiedDetail	`ReactNode`	-
isProposalBlocked	`boolean \| undefined`	false
proposalBlockedReason	`ReactNode`	-
proposalDiff	`SorConfig01Diff[] \| undefined`	-
onUseProposal	`(() => void) \| undefined`	-
fields*	`SorConfig01FieldSpec<TFieldKey>[]`	-
fieldValues*	`Record<TFieldKey, string>`	-
onFieldChange*	`(key: TFieldKey, value: string) => void`	-
fieldErrors	`Partial<Record<TFieldKey, ReactNode>> \| undefined`	-
fieldSuggestions	`Partial<Record<TFieldKey, string[]>> \| undefined`	-	Catalog-derived value suggestions per field, keyed by field key.
multiValueFieldKeys	`TFieldKey[] \| undefined`	-	Field keys whose value is a comma-separated list, e.g. free-text search fields.
categories*	`SorConfig01CategorySpec<TCategoryKey>[]`	-
categoryValues*	`Record<TCategoryKey, string>`	-
onCategoryChange*	`(key: TCategoryKey, value: string) => void`	-
inFlightValuesByCategory	`Partial<Record<TCategoryKey, string[]>> \| undefined`	-	Values that look like they mean "in progress", shown as a warning per category.
observedValues	`string[] \| undefined`	-	Every value actually observed in a sample of source records.
observedValuesCaption	`ReactNode`	-
blockingChecks	`SorConfig01Check[] \| undefined`	-	Local, blocking checks - shown once `onSave` has been attempted.
verifyBlockingChecks	`SorConfig01Check[] \| undefined`	-	Checks a verification pass ran against real records refused.
isVerifyUnverified	`boolean \| undefined`	false
verifyUnverifiedDetail	`ReactNode`	-
warningChecks	`SorConfig01Check[] \| undefined`	-
warningsCaption	`ReactNode`	-
unsavedFieldLabels	`string[] \| undefined`	-	Coordinates the draft has changed but not yet saved.
onSave*	`() => void`	-
isSaving	`boolean \| undefined`	false
isVerifying	`boolean \| undefined`	false
canSave	`boolean \| undefined`	true
saveError	`SorConfig01ApiError \| null \| undefined`	-
verifyError	`SorConfig01ApiError \| null \| undefined`	-
saveOutcome	`SorConfig01SaveOutcome \| null \| undefined`	-
savedDetectorCount	`number \| undefined`	-
onReset*	`() => void`	-
canReset	`boolean \| undefined`	false
resetLabel	`ReactNode`	-
onRemove	`(() => void) \| undefined`	-
isRemoving	`boolean \| undefined`	false
removeError	`SorConfig01ApiError \| null \| undefined`	-
removeConfirmDescription	`ReactNode`	-
removeConfirmLabel	`ReactNode`	-
isLoading	`boolean \| undefined`	false
loadError	`SorConfig01ApiError \| null \| undefined`	-
className	`string \| undefined`	-
data-testid	`string \| undefined`	-	Test identifier rendered as `data-testid` on the root element.

Changelog

sor-config-01

0.1.1

Initial release: a source-mapping editor page - connection picker, propose flow with a field-by-field diff against the current draft, generic field and status/category mapping cards, save/reset/remove actions, and every check and async state as a prop. Fully controlled: the caller owns the draft, the checks, and the field/category vocabulary via generic TFieldKey/TCategoryKey type parameters - no fetching, no domain types.