# Semantics List Page (`semantics-list-01`) - SignalOS page block

> A pipeline-list page block with filtering, pagination, and delete-confirmation dialog.

- **Version:** 0.4.15
- **Kind:** block (group: semantics) · **Category:** pages
- **Install:** `npx shadcn@4.1.2 add @signalos/semantics-list-01`
- **Registry dependencies (pulled automatically):** @signalos/tokens, @signalos/utils, @signalos/button, @signalos/tooltip, @signalos/dropdown-menu, @signalos/filter-toolbar, @signalos/page-header, @signalos/pagination, @signalos/confirm-dialog, @signalos/data-primitives, @signalos/select, @signalos/textarea, @signalos/skeleton, @signalos/input, @signalos/label, @signalos/dialog, @signalos/pipelinewizard-01
- **npm dependencies:** lucide-react@^1.7.0
- **Files installed:** `src/components/blocks/semantics-list-01/Semantics01.tsx`, `src/components/blocks/semantics-list-01/Semantics01.types.ts`, `src/components/blocks/semantics-list-01/Semantics01.constants.ts`, `src/components/blocks/semantics-list-01/components/EditPipelineDialog.tsx`, `src/components/blocks/semantics-list-01/components/PipelineCard.tsx`, `src/components/blocks/semantics-list-01/Semantics01.utils.ts`

## Access

This is a private registry: pulling source requires a `SIGNALOS_REGISTRY_TOKEN`
(GitHub fine-grained PAT with read access to the signal-widgets repo) and an
`@signalos` entry in components.json `"registries"`. Previews and this document are public.

## Usage

```tsx
// after: npx shadcn@4.1.2 add @signalos/semantics-list-01
// mount the pulled page in a route, e.g. src/app/semantics/page.tsx
import Semantics01 from "@/components/blocks/semantics-list-01/Semantics01"

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

## Props

### `KnownPipelineType`

```ts
export type KnownPipelineType =
  "single" | "multi_source" | "connector_onboarding"
```

### `SemanticsPipelineType`

```ts
export type SemanticsPipelineType = KnownPipelineType | (string & {})
```

### `PipelineLike`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | yes | - | Stable unique identifier. |
| `name` | `string` | yes | - | Display name. |
| `description` | `string \| null \| undefined` | no | - | Optional description. |
| `status` | `string` | yes | - | Pipeline status key, e.g. "created", "running", "completed". |
| `pipeline_type` | `SemanticsPipelineType \| null \| undefined` | no | - | Source topology: "multi_source" shows a Layers icon; anything else shows GitBranch. |
| `connector_count` | `number \| undefined` | no | - | Number of connectors attached. |
| `created_at` | `string \| undefined` | no | - | ISO-8601 creation timestamp. |
| `current_stage` | `string \| undefined` | no | - | Current processing stage key, looked up in STAGE_LABELS. |

### `Semantics01Props`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` | no | `"Semantics"` | Page heading. |
| `description` | `ReactNode` | no | `"Manage your data pipelines…"` | Sub-heading under the title. |
| `onCreatePipeline` | `(() => void) \| undefined` | no | - | Called when the "Create Pipeline" button is pressed. |
| `items` | `readonly TItem[]` | yes | - | Pipeline items to render. |
| `isLoading` | `boolean \| undefined` | no | - | Loading state — renders skeleton cards when true. |
| `isError` | `boolean \| undefined` | no | - | Error state — renders error message when true. |
| `errorMessage` | `ReactNode` | no | - | Error message shown when `isError` is true. |
| `searchValue` | `string \| undefined` | no | - | Current free-text search value. |
| `onSearchChange` | `((value: string) => void) \| undefined` | no | - | Called when the search input changes. |
| `searchPlaceholder` | `string \| undefined` | no | `"Search pipelines…"` |  |
| `statusFilter` | `string \| undefined` | no | `"all"` | Current value of the status filter dropdown. |
| `onStatusFilterChange` | `((value: string) => void) \| undefined` | no | - | Called when the status filter changes. |
| `onRefresh` | `(() => void) \| undefined` | no | - | Called when the refresh button is pressed. Omit to hide the button. |
| `isRefreshing` | `boolean \| undefined` | no | `false` |  |
| `onOpen` | `((item: TItem) => void) \| undefined` | no | - | Called when a pipeline card (or its "View" button) is activated. |
| `onEdit` | `((item: TItem) => void) \| undefined` | no | - | Called when the "Edit" menu item is selected. |
| `onDelete` | `((item: TItem) => void) \| undefined` | no | - | Called when the "Delete" menu item is selected. |
| `createWizardOpen` | `boolean \| undefined` | no | - | Whether the create wizard dialog is open. |
| `onCreateWizardOpenChange` | `((open: boolean) => void) \| undefined` | no | - | Called when the dialog open state changes. |
| `createWizardStep` | `number \| undefined` | no | - | The active step index (0 = Details, 1 = Context, 2 = Connectors, 3 = Review). The parent drives this so it can trigger per-step data fetches on advance. |
| `onCreateWizardStepChange` | `((step: number) => void) \| undefined` | no | - | Called when the wizard requests a step change; parent fetches data then updates `createWizardStep`. |
| `createWizardName` | `string \| undefined` | no | - | Pipeline name field value. |
| `onCreateWizardNameChange` | `((value: string) => void) \| undefined` | no | - | Called when the pipeline name changes. |
| `createWizardDescription` | `string \| undefined` | no | - | Pipeline description field value. |
| `onCreateWizardDescriptionChange` | `((value: string) => void) \| undefined` | no | - | Called when the pipeline description changes. |
| `createWizardSelectedConnectionIds` | `string[] \| undefined` | no | - | Selected connection ids. |
| `onCreateWizardSelectedConnectionIdsChange` | `((ids: string[]) => void) \| undefined` | no | - | Called when the selected connection ids change. |
| `createWizardFieldErrors` | `Record<string, string> \| undefined` | no | - | Per-field validation errors for the wizard. |
| `onCreateWizardFieldErrorsChange` | `((errors: Record<string, string>) => void) \| undefined` | no | - | Called when wizard field errors change. |
| `createWizardReasoningModel` | `string \| undefined` | no | - | Reasoning model canonical id. |
| `onCreateWizardReasoningModelChange` | `((canonical: string) => void) \| undefined` | no | - | Called when the reasoning model selection changes. |
| `createWizardSupportingModel` | `string \| undefined` | no | - | Supporting model canonical id. |
| `onCreateWizardSupportingModelChange` | `((canonical: string) => void) \| undefined` | no | - | Called when the supporting model selection changes. |
| `createWizardEmbeddingModel` | `string \| undefined` | no | - | Embedding model canonical id. |
| `onCreateWizardEmbeddingModelChange` | `((canonical: string) => void) \| undefined` | no | - | Called when the embedding model selection changes. |
| `llmModels` | `OrchestrationModelLike[] \| undefined` | no | - | LLM models for the model pickers (Step 1). |
| `embeddingModels` | `OrchestrationModelLike[] \| undefined` | no | - | Embedding models for the embedding picker (Step 1). |
| `isLoadingModels` | `boolean \| undefined` | no | - | True while LLM/embedding models are loading. |
| `contextQuestions` | `ContextQuestion[] \| undefined` | no | - | Onboarding context questions (Step 2). |
| `isLoadingQuestions` | `boolean \| undefined` | no | - | True while context questions are loading. |
| `contextAnswers` | `Record<string, string> \| undefined` | no | - | Current answers, keyed by `question_key`. |
| `onContextAnswerChange` | `((key: string, value: string) => void) \| undefined` | no | - | Called when the user types in an answer field. |
| `connections` | `ConnectionLike[] \| undefined` | no | - | Available platform connections (Step 3). |
| `isLoadingConnectors` | `boolean \| undefined` | no | - | True while connectors are loading. |
| `isSubmitting` | `boolean \| undefined` | no | - | True while the create mutation is in-flight. |
| `onSubmit` | `((payload: CreatePipelinePayload) => void) \| undefined` | no | - | Called with the collected payload when the user confirms creation. |
| `onCreateCustomModel` | `(() => void) \| undefined` | no | - | Called when the user clicks "Create model" inside the model picker. |
| `pendingEdit` | `TItem \| null \| undefined` | no | - | The pipeline currently being edited; controls the edit dialog. |
| `onPendingEditChange` | `((open: boolean) => void) \| undefined` | no | - | Called when the edit dialog open state changes. |
| `onSaveEdit` | `((id: string, fields: UpdatePipelineFields) => void) \| undefined` | no | - | Called with only the changed fields when the user saves. |
| `isUpdating` | `boolean \| undefined` | no | - | True while an update mutation is in-flight. |
| `pendingDelete` | `TItem \| null \| undefined` | no | - | The pipeline currently pending deletion; controls the confirm-dialog. |
| `onPendingDeleteChange` | `((open: boolean) => void) \| undefined` | no | - | Called when the confirm-dialog open state changes (e.g. user cancels). |
| `onConfirmDelete` | `(() => void) \| undefined` | no | - | Called when the user confirms deletion. |
| `isDeleting` | `boolean \| undefined` | no | - | True while a delete mutation is in-flight. |
| `currentPage` | `number \| undefined` | no | `1` |  |
| `pageSize` | `number \| undefined` | no | `12` | Number of items per page. |
| `totalItems` | `number \| undefined` | no | - | Total number of items across all pages. |
| `onPageChange` | `((page: number) => void) \| undefined` | no | - | Called when the user navigates to a different page. |
| `emptyLabel` | `ReactNode` | no | - | Override the empty-state label. |
| `emptyDescription` | `ReactNode` | no | - | Override the empty-state description. |
| `className` | `string \| undefined` | no | - |  |
| `data-testid` | `string \| undefined` | no | - | Test identifier rendered as `data-testid` on the root element. |
| `createWizardSupportingDocuments` | `File[] \| undefined` | no | - |  |
| `onCreateWizardSupportingDocumentsChange` | `((files: File[]) => void) \| undefined` | no | - | Called with the full next list whenever staged supporting documents change. |
| `subUseCaseProposals` | `SubUseCaseProposal[] \| undefined` | no | - | Proposed / confirmed / rejected sub use cases (Step 3). |
| `onSubUseCaseProposalsChange` | `((proposals: SubUseCaseProposal[]) => void) \| undefined` | no | - | Called whenever the proposal list changes (confirm, reject, edit, add, undo). |
| `isLoadingSubUseCases` | `boolean \| undefined` | no | - | True while the initial derivation call is in flight. |
| `subUseCasesFailed` | `boolean \| undefined` | no | - | True when the derivation call itself failed. |
| `subUseCaseResolvedUseCase` | `string \| undefined` | no | - |  |
| `subUseCaseResolvedOrgDomain` | `string \| undefined` | no | - | The organization domain as the backend resolved it, alongside `subUseCaseResolvedUseCase`. |
| `onRederiveSubUseCases` | `(() => void) \| undefined` | no | - | Called when the user asks to re-derive sub use cases from the current wording. |
| `isRederivingSubUseCases` | `boolean \| undefined` | no | - | True while a re-derive call is in flight. |
| `subUseCaseEditTargetId` | `string \| null \| undefined` | no | - | The proposal id currently being edited, or null when the dialog is closed. |
| `onSubUseCaseEditTargetIdChange` | `((id: string \| null) => void) \| undefined` | no | - | Called to open/close the edit dialog (opening also seeds the draft). |
| `subUseCaseEditDraftTitle` | `string \| undefined` | no | - | Draft title field value for the edit dialog. |
| `onSubUseCaseEditDraftTitleChange` | `((title: string) => void) \| undefined` | no | - | Called when the edit dialog's title field changes. |
| `subUseCaseEditDraftStatement` | `string \| undefined` | no | - | Draft statement field value for the edit dialog. |
| `onSubUseCaseEditDraftStatementChange` | `((statement: string) => void) \| undefined` | no | - | Called when the edit dialog's statement field changes. |
| `subUseCaseEditError` | `string \| null \| undefined` | no | - | Validation error shown in the edit dialog, if any. |
| `onSubmitSubUseCaseEdit` | `(() => void) \| undefined` | no | - | Called when the user submits the edit dialog. |
| `subUseCaseRejectTargetId` | `string \| null \| undefined` | no | - | The proposal id currently being rejected, or null when the dialog is closed. |
| `onSubUseCaseRejectTargetIdChange` | `((id: string \| null) => void) \| undefined` | no | - | Called to open/close the reject dialog. |
| `subUseCaseRejectNote` | `string \| undefined` | no | - | Reject-reason note field value. |
| `onSubUseCaseRejectNoteChange` | `((note: string) => void) \| undefined` | no | - | Called when the reject dialog's note field changes. |
| `onSubmitSubUseCaseReject` | `(() => void) \| undefined` | no | - | Called when the user submits the reject dialog. |
| `subUseCaseAddOpen` | `boolean \| undefined` | no | - | Whether the add dialog is open. |
| `onSubUseCaseAddOpenChange` | `((open: boolean) => void) \| undefined` | no | - | Called to open/close the add dialog. |
| `subUseCaseAddDraftTitle` | `string \| undefined` | no | - | Draft title field value for the add dialog. |
| `onSubUseCaseAddDraftTitleChange` | `((title: string) => void) \| undefined` | no | - | Called when the add dialog's title field changes. |
| `subUseCaseAddDraftStatement` | `string \| undefined` | no | - | Draft statement field value for the add dialog. |
| `onSubUseCaseAddDraftStatementChange` | `((statement: string) => void) \| undefined` | no | - | Called when the add dialog's statement field changes. |
| `subUseCaseAddError` | `string \| null \| undefined` | no | - | Validation error shown in the add dialog, if any. |
| `onSubmitSubUseCaseAdd` | `(() => void) \| undefined` | no | - | Called when the user submits the add dialog. |

### `SubUseCaseStatus`

```ts
export type SubUseCaseStatus = "proposed" | "confirmed" | "rejected"
```

### `SubUseCaseProposal`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | yes | - | Stable identity within this session — index-based ids (UC1.1, UC1.2, …) are assigned for display. |
| `title` | `string` | yes | - |  |
| `statement` | `string` | yes | - |  |
| `status` | `SubUseCaseStatus` | yes | - |  |
| `derivation_basis` | `string[] \| undefined` | no | - |  |
| `hand_added` | `boolean \| undefined` | no | - |  |
| `review_note` | `string \| undefined` | no | - | Recorded when rejected — why this proposal was declined. |

## Changelog

## 0.4.15

- Decompose `CreatePipelineWizard` into `WizardStepBar`, `WizardStepConnectors`, `WizardStepContext`, `WizardStepDetails`, and `WizardStepReview` subcomponents; extract `ModelSelect` to its own file.
- Define `WIZARD_STEPS` constant and typed step-component props interfaces for each wizard step.

## 0.4.8

- Fix cross-item imports to use canonical @/components paths; add missing signalos.category to manifests.

## 0.4.7

- `Semantics01.constants.ts`: remove `{ value: "running", label: "Running" }` from `STATUS_OPTIONS`; rename `metrics_baselines` → `functions` (label "Functions & Workflow") in `STAGE_LABELS`.
- `Semantics01.tsx`: default `data-testid` on the create button to `"semantics-create"` when no `dataTestId` prop is provided.
- `Semantics01.tsx`: change loading grid `data-testid` to `"pipeline-list-loading"`; wrap empty state in a `data-testid="pipeline-list-empty"` div.
- `Semantics01.types.ts`: add `KnownPipelineType` / `SemanticsPipelineType` union; allow `null` for `description` and `pipeline_type` on `PipelineLike`.
- `Semantics01.utils.ts`: remove stale JSDoc module comment block.
- `CreatePipelineWizard`: replace `FormDialog`+`TextField` with raw `Dialog`/`DialogContent`/`DialogHeader`/`DialogTitle`/`DialogDescription` and `Input`/`Label`.
- Remove `@signalos/form-dialog` and `@signalos/text-field` from `registryDependencies`.

## 0.4.6

- Replace raw Dialog with FormDialog in CreatePipelineWizard; footer=null, step indicator and wizard nav rendered as children.
- Replace raw Dialog with FormDialog in EditPipelineDialog; EditPipelineForm now owns open/dataTestId and renders FormDialog directly.
- Replace Label+Input with TextField for Pipeline name in both dialogs; Description and context Textarea fields keep inline label style.
- Fix raw token text-error-500 → text-text-error on context step required asterisk.
- Swap @signalos/dialog + @signalos/input + @signalos/label → @signalos/form-dialog + @signalos/text-field.

## 0.4.4

- Content updates.

## 0.4.2

- Lift CreatePipelineWizard form state (name, description, selectedConnectionIds, fieldErrors, reasoningModel, supportingModel, embeddingModel) to controlled props. Parent now owns all wizard form state.

# semantics-list-01
## 0.3.2
## 0.3.1

- Patch: no functional changes; version bump to resync content hash after file was added to the working tree.

## 0.3.0

- Lift wizard step control to the parent: `CreatePipelineWizard` now accepts `step`/`onStepChange` props so the parent owns step transitions and triggers per-step data fetches.
- Add `isLoadingQuestions` and `isLoadingConnectors` props to `CreatePipelineWizard`; wizard renders inline loading states for Steps 2 and 3.
- Expose all wizard props (`createWizardOpen`, `onCreateWizardOpenChange`, `createWizardStep`, `onCreateWizardStepChange`, `llmModels`, `embeddingModels`, `isLoadingModels`, `contextQuestions`, `isLoadingQuestions`, `contextAnswers`, `onContextAnswerChange`, `connections`, `isLoadingConnectors`, `isSubmitting`, `onSubmit`, `onCreateCustomModel`) on `Semantics01Props` and render `CreatePipelineWizard` from the parent.
- Re-export wizard structural types (`ConnectionLike`, `ContextQuestion`, `CreatePipelinePayload`, `OrchestrationModelLike`) from `Semantics01.types.ts`.

## 0.2.1
## 0.2.0

- **Breaking:** Component is now a pure presentational block — all API calls, state management, and business logic must be handled by the parent. Props updated accordingly (see `Semantics01.types.ts`).
- Add `Semantics01Props<TItem>` generic interface in `Semantics01.types.ts`; remove `any` throughout.
- Add `PipelineLike` structural interface — consumers map their domain type onto it.
- Remove `STATUS_ICON_BG` constant (used raw-scale tokens); `PipelineCard` now uses `STATUS_ICON_CLASSES` (semantic tokens only).
- `onCreatePipeline`, `onOpen`, `onEdit`, `onDelete`, `onRefresh` are optional — controls render only when their callback is provided.
- Fix manifest `name` from `semantics-list-01` to `semantics-list-01`; add missing `registryDependencies`.