[Tools](https://oods-foundry.com/tools) / component_map

# `component_map`

Manage component substitutions in your mapping store.

Generated from @oods/foundry 0.10.2

One of the 20 tools your assistant sees by default.

Use it when connecting React/Vue exports or shadcn source to OODS components; use catalog_list to find component names. Returns entries, matches or per-entry write outcomes. action selects draft/show/apply/create/list/resolve/update/delete. draft reads local shadcn or built Storybook files without executing code; show exposes evidence, adapter files and unmatched elements; apply with draftId and accept ids validates and atomically registers reviewed mappings. create accepts a single entry, mappings list or mappingsPath; lists validate completely before one write. substitution supplies exports and prop translations with exact package versions or installed localPath. React/Vue shadcn mappings use an installed project and module instead. Compose snapshots mappings; generation/preview apply them. apply controls mutation where supported. Full schema: oods\://schemas/component_map.input.json.

## Inputs

| Name | Type | Required | Description |
| - | - | - | - |
| `action` | `"apply" \| "create" \| "list" \| "resolve" \| "update" \| "delete" \| "draft" \| "show"` | yes | Selects the per-action handler to invoke. |
| `apply` | `boolean` | no | For apply: When true, persist registry mutations. Actions: apply, create, list, resolve, update, delete. See full schema for details. |
| `minConfidence` | `number` | no | Candidates below this threshold are routed to queued instead of being applied. Actions: apply. |
| `reportPath` | `string` | no | Filesystem path to a reconciliation_report.json artifact. Actions: apply. |
| `report` | `object` | no | Reconciliation report. Actions: apply. |
| `mappings` | `object[]` | no | Create entries, each without apply. All entries are checked before one atomic write. Actions: create. |
| `mappingsPath` | `string` | no | Absolute path to a JSON document { mappings: \[...] }, using the same entry shape. Actions: create. |
| `substitution` | `object` | no | Version 2 component substitution: an OODS Foundry id, React and/or Vue package exports, and OODS Foundry-to-team prop translations. Legacy trait-only mappings remain valid. Actions: create. |
| `externalSystem` | `string` | no | For create: External design system name (for example, 'team'). Actions: create, list, resolve (required), draft. See full schema for details. |
| `externalComponent` | `string` | no | For create: Component name in the external system (e.g., 'Button', 'TextField'). For resolve: Component name in the external system (e.g., 'Button'). Actions: create, resolve (required). |
| `oodsTraits` | `string[]` | no | OODS trait names this component maps to. Actions: create. |
| `propMappings` | `object[]` | no | Property translations from external to OODS prop names. Actions: create. |
| `confidence` | `"auto" \| "manual"` | no | 'auto' for machine-generated, 'manual' for human-curated. Actions: create. |
| `metadata` | `object` | no | Mapping metadata. Actions: create. |
| `disambiguation_decisions` | `object[]` | no | Draft v1.4.0-gated review-decision events to append to the registry's top-level disambiguation_decisions\[]. Additive stub only; does not gate mapping creation. Each entry uses the Stage1 disambiguation_decision shape. Actions: create. |
| `preferred_terms` | `object[]` | no | Draft v1.4.0-gated canonical-term entities to append to the registry's top-level preferred_terms\[]. Each entry uses the Stage1 preferred_term entity shape. Actions: create. |
| `capabilities` | `object[]` | no | Draft v1.4.0-gated first-class capability entities to append to the registry's top-level capabilities\[]. Each entry uses the Stage1 capability entity shape. Actions: create. |
| `projection_variants` | `object[]` | no | Stage1 v1.5.0 cross-surface identity variants. Each element describes one surface-specific projection of this component mapping (desktop/mobile/modal/sidebar). Actions: create. |
| `cursor` | `string` | no | Pagination cursor. Use the previous page's nextCursor to continue. When cursor or limit is provided, pagination defaults to 100 items per page. Actions: list. |
| `limit` | `integer` | no | Page size for pagination. Omitting both cursor and limit preserves the legacy full-list response. Actions: list. |
| `id` | `string` | no | For update: Mapping ID to update (e.g., 'team-button'). For delete: Mapping ID to delete (e.g., 'team-button'). Actions: update (required), delete (required). |
| `updates` | `object` | no | Fields to update. Only provided fields are changed. Actions: update (required). |
| `source` | `object` | no | Actions: draft (required). |
| `draftId` | `string` | no | Actions: show (required), apply (required). |
| `accept` | `string[]` | no | Actions: apply (required). |

## Outputs

The package ships no output schema for this tool.

## A real call

Recorded by this site's `harbor` run, step `mapping`, with the published OODS Foundry 0.10.2.

Its input:

```
{
  "action": "create",
  "apply": true,
  "externalSystem": "harbor",
  "externalComponent": "TeamButton",
  "oodsTraits": [
    "Stateful"
  ],
  "substitution": {
    "component": "Button",
    "react": {
      "package": "@harbor/example-components/react",
      "version": "1.0.0",
      "export": "TeamButton",
      "localPath": "<workspace>/harbor-design-system/team-components",
      "props": {
        "content": {
          "name": "caption"
        },
        "intent": {
          "name": "appearance",
          "values": {
            "neutral": "quiet",
            "primary": "prominent",
            "danger": "danger"
          }
        }
      }
    },
    "vue": {
      "package": "@harbor/example-components/vue",
      "version": "1.0.0",
      "export": "TeamButton",
      "localPath": "<workspace>/harbor-design-system/team-components",
      "props": {
        "content": {
          "name": "caption"
        },
        "intent": {
          "name": "appearance",
          "values": {
            "neutral": "quiet",
            "primary": "prominent",
            "danger": "danger"
          }
        }
      }
    }
  }
}
```

Its result:

```
{
  "status": "ok",
  "mapping": {
    "id": "harbor-team-button",
    "externalSystem": "harbor",
    "externalComponent": "TeamButton",
    "oodsTraits": [
      "Stateful"
    ],
    "substitution": {
      "component": "Button",
      "react": {
        "package": "@harbor/example-components/react",
        "version": "1.0.0",
        "export": "TeamButton",
        "localPath": "<workspace>/harbor-design-system/team-components",
        "props": {
          "content": {
            "name": "caption"
          },
          "intent": {
            "name": "appearance",
            "values": {
              "neutral": "quiet",
              "primary": "prominent",
              "danger": "danger"
            }
          }
        },
        "passthrough": true
      },
      "vue": {
        "package": "@harbor/example-components/vue",
        "version": "1.0.0",
        "export": "TeamButton",
        "localPath": "<workspace>/harbor-design-system/team-components",
        "props": {
          "content": {
            "name": "caption"
          },
          "intent": {
            "name": "appearance",
            "values": {
              "neutral": "quiet",
              "primary": "prominent",
              "danger": "danger"
            }
          }
        },
        "passthrough": true
      }
    },
    "confidence": "manual",
    "metadata": {
      "createdAt": "2026-10-09T00:44:13.851Z"
    }
  },
  "etag": "6ac3aa84b46dbfd3802719b6eaaf61d23f4424e582a5aa7a44f3b9ad0f1d3b6d",
  "applied": true
}
```

[The whole call, 3 KB of JSON](https://oods-foundry.com/tools/component-map/call.json)