# Props

> The prop types of a component, how an attribute becomes a value, and the schema of a prop.

> Generated from the contract schemas of `@taggor/contract` 1.10.0 by `pnpm docs:contract`; do not edit.

A prop is declared with a `type`. The runtime reads the attribute text of the custom element, checks it against the declaration and hands the component a typed value; text that does not fit falls back to the declared `default`.

## PropDeclaration

Exactly one of:

- type `"string"`, fields below
- type `"number"`, fields below
- type `"boolean"`, fields below
- type `"enum"`, fields below
- type `"color"`, fields below
- type `"url"`, fields below
- type `"date"`, fields below
- type `"array"`, fields below
- type `"object"`, fields below

### PropDeclaration, type "string"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"string"` | yes | The prop type. It decides how the attribute text is read and which other fields apply. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `minLength` | `integer`, 0 to 10000 | no | Shortest text accepted, in characters. |
| `maxLength` | `integer`, 1 to 10000 | no | Defaults to 10000. |
| `format` | one of `"email"`, `"url"`, `"tel"`, `"date"`, `"date-time"` | no | A well-known text format the value must follow. |
| `default` | `string`, at most 10000 characters | no | The value used when the attribute is missing or does not fit the declaration. Must fit the declaration itself. |

### PropDeclaration, type "number"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"number"` | yes | The prop type. It decides how the attribute text is read and which other fields apply. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `min` | `number` | no | Smallest value accepted; dates are ISO text. |
| `max` | `number` | no | Largest value accepted; dates are ISO text. |
| `integer` | `boolean` | no | When true, only whole numbers are accepted. |
| `default` | `number` | no | The value used when the attribute is missing or does not fit the declaration. Must fit the declaration itself. |
| `step` | `number`, greater than 0 | no | A hint for editors (the step of a slider). It does not change what is accepted. |

### PropDeclaration, type "boolean"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"boolean"` | yes | The prop type. It decides how the attribute text is read and which other fields apply. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `default` | the constant `false` | no | The value used when the attribute is missing or does not fit the declaration. Must fit the declaration itself. |

### PropDeclaration, type "enum"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"enum"` | yes | The prop type. It decides how the attribute text is read and which other fields apply. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `values` | array of [EnumValue](../manifest/#named-types), 1 to 50 items, no repeats | yes | The allowed values, in the order an editor shows them. |
| `default` | `string`, at most 64 characters | no | The value used when the attribute is missing or does not fit the declaration. Must fit the declaration itself. |

### PropDeclaration, type "color"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"color"` | yes | The prop type. It decides how the attribute text is read and which other fields apply. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `default` | `string`, 1 to 64 characters, a fixed pattern (see the JSON Schema) | no | The value used when the attribute is missing or does not fit the declaration. Must fit the declaration itself. |

### PropDeclaration, type "url"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"url"` | yes | The prop type. It decides how the attribute text is read and which other fields apply. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `protocols` | array of one of `"https"`, `"http"`, `"mailto"`, 1 to 3 items, no repeats | no | Accepted URL schemes; defaults to ["https"]. |
| `default` | `string`, at most 2048 characters, a fixed pattern (see the JSON Schema) | no | The value used when the attribute is missing or does not fit the declaration. Must fit the declaration itself. |

### PropDeclaration, type "date"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"date"` | yes | The prop type. It decides how the attribute text is read and which other fields apply. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `min` | `string`, a fixed pattern (see the JSON Schema) | no | Smallest value accepted; dates are ISO text. |
| `max` | `string`, a fixed pattern (see the JSON Schema) | no | Largest value accepted; dates are ISO text. |
| `default` | `string`, a fixed pattern (see the JSON Schema) | no | The value used when the attribute is missing or does not fit the declaration. Must fit the declaration itself. |

### PropDeclaration, type "array"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"array"` | yes | The prop type. It decides how the attribute text is read and which other fields apply. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `items` | [ValueSchemaDepth2](#valueschemadepth2) | yes | The schema every item of the array follows. |
| `minItems` | `integer`, 0 to 1000 | no | Fewest items accepted. |
| `maxItems` | `integer`, 1 to 1000 | no | Defaults to 1000. |
| `default` | array of [DefaultValueDepth2](#defaultvaluedepth2), at most 1000 items | no | The value used when the attribute is missing or does not fit the declaration. Must fit the declaration itself. |

### PropDeclaration, type "object"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"object"` | yes | The prop type. It decides how the attribute text is read and which other fields apply. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `fields` | map to [ValueSchemaDepth2](#valueschemadepth2) (keys: [FieldName](../manifest/#named-types)), at most 50 entries | yes | The fields of the object, by name. |
| `required` | array of [FieldName](../manifest/#named-types), 1 to 50 items, no repeats | no | The names of the fields that must be present. Each is one of `fields`. |
| `default` | map to [DefaultValueDepth2](#defaultvaluedepth2) (keys: [FieldName](../manifest/#named-types)), at most 50 entries | no | The value used when the attribute is missing or does not fit the declaration. Must fit the declaration itself. |

## DefaultValueDepth2

Any of:

- `string`, at most 10000 characters or `number` or `boolean`
- array of [DefaultValueDepth1](#defaultvaluedepth1), at most 1000 items
- map to [DefaultValueDepth1](#defaultvaluedepth1) (keys: [FieldName](../manifest/#named-types)), at most 50 entries

## DefaultValueDepth1

Any of:

- `string`, at most 10000 characters or `number` or `boolean`
- array of `string`, at most 10000 characters or `number` or `boolean`, at most 1000 items
- map to `string`, at most 10000 characters or `number` or `boolean` (keys: [FieldName](../manifest/#named-types)), at most 50 entries

## ValueSchema

Declarative description of a JSON value. Plain data only: no code, no regular expressions.

Exactly one of:

- [StringValueSchema](#stringvalueschema)
- [NumberValueSchema](#numbervalueschema)
- [BooleanValueSchema](#booleanvalueschema)
- [EnumValueSchema](#enumvalueschema)
- type `"array"`, fields below
- type `"object"`, fields below

### ValueSchema, type "array"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"array"` | yes | The value type: `string`, `number`, `boolean`, `enum`, `array` or `object`. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `items` | [ValueSchemaDepth2](#valueschemadepth2) | yes | The schema every item of the array follows. |
| `minItems` | `integer`, 0 to 1000 | no | Fewest items accepted. |
| `maxItems` | `integer`, 1 to 1000 | no | Defaults to 1000. |

### ValueSchema, type "object"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"object"` | yes | The value type: `string`, `number`, `boolean`, `enum`, `array` or `object`. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `fields` | map to [ValueSchemaDepth2](#valueschemadepth2) (keys: [FieldName](../manifest/#named-types)), at most 50 entries | yes | The fields of the object, by name. |
| `required` | array of [FieldName](../manifest/#named-types), 1 to 50 items, no repeats | no | The names of the fields that must be present. Each is one of `fields`. |

## ValueSchemaDepth2

Exactly one of:

- [StringValueSchema](#stringvalueschema)
- [NumberValueSchema](#numbervalueschema)
- [BooleanValueSchema](#booleanvalueschema)
- [EnumValueSchema](#enumvalueschema)
- type `"array"`, fields below
- type `"object"`, fields below

### ValueSchemaDepth2, type "array"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"array"` | yes | The value type: `string`, `number`, `boolean`, `enum`, `array` or `object`. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `items` | [ValueSchemaDepth1](#valueschemadepth1) | yes | The schema every item of the array follows. |
| `minItems` | `integer`, 0 to 1000 | no | Fewest items accepted. |
| `maxItems` | `integer`, 1 to 1000 | no | Defaults to 1000. |

### ValueSchemaDepth2, type "object"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"object"` | yes | The value type: `string`, `number`, `boolean`, `enum`, `array` or `object`. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `fields` | map to [ValueSchemaDepth1](#valueschemadepth1) (keys: [FieldName](../manifest/#named-types)), at most 50 entries | yes | The fields of the object, by name. |
| `required` | array of [FieldName](../manifest/#named-types), 1 to 50 items, no repeats | no | The names of the fields that must be present. Each is one of `fields`. |

## ValueSchemaDepth1

Exactly one of:

- [StringValueSchema](#stringvalueschema)
- [NumberValueSchema](#numbervalueschema)
- [BooleanValueSchema](#booleanvalueschema)
- [EnumValueSchema](#enumvalueschema)
- type `"array"`, fields below
- type `"object"`, fields below

### ValueSchemaDepth1, type "array"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"array"` | yes | The value type: `string`, `number`, `boolean`, `enum`, `array` or `object`. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `items` | [ScalarValueSchema](#scalarvalueschema) | yes | The schema every item of the array follows. |
| `minItems` | `integer`, 0 to 1000 | no | Fewest items accepted. |
| `maxItems` | `integer`, 1 to 1000 | no | Defaults to 1000. |

### ValueSchemaDepth1, type "object"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"object"` | yes | The value type: `string`, `number`, `boolean`, `enum`, `array` or `object`. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `fields` | map to [ScalarValueSchema](#scalarvalueschema) (keys: [FieldName](../manifest/#named-types)), at most 50 entries | yes | The fields of the object, by name. |
| `required` | array of [FieldName](../manifest/#named-types), 1 to 50 items, no repeats | no | The names of the fields that must be present. Each is one of `fields`. |

## ScalarValueSchema

Exactly one of:

- [StringValueSchema](#stringvalueschema)
- [NumberValueSchema](#numbervalueschema)
- [BooleanValueSchema](#booleanvalueschema)
- [EnumValueSchema](#enumvalueschema)

## StringValueSchema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"string"` | yes | Always `string`. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `minLength` | `integer`, 0 to 10000 | no | Shortest text accepted, in characters. |
| `maxLength` | `integer`, 1 to 10000 | no | Defaults to 10000. |
| `format` | one of `"email"`, `"url"`, `"tel"`, `"date"`, `"date-time"` | no | A well-known text format the value must follow. |

## NumberValueSchema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"number"` | yes | Always `number`. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `min` | `number` | no | Smallest value accepted. |
| `max` | `number` | no | Largest value accepted. |
| `integer` | `boolean` | no | When true, only whole numbers are accepted. |

## BooleanValueSchema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"boolean"` | yes | Always `boolean`. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |

## EnumValueSchema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"enum"` | yes | Always `enum`. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `values` | array of [EnumValue](../manifest/#named-types), 1 to 50 items, no repeats | yes | The allowed values. |

## How an attribute becomes a value

| Type | Attribute text accepted | Value the component receives |
| --- | --- | --- |
| `string` | the text as is, within `minLength`/`maxLength` and the `format` | the same string |
| `number` | decimal (`-1.5`, `2e3`; no `+`, spaces, hex, `Infinity`), up to 32 characters, within `min`/`max`/`integer` | finite `number` (`step` is a hint only; `-0` becomes `0`) |
| `boolean` | attribute presence, any text (even `"false"`) | `true`; absent = `false` |
| `enum` | exactly one of the `values` | the same string |
| `color` | CSS value from the allowlist, up to 64 characters, balanced parentheses | the same string (the runtime also requires `CSS.supports`) |
| `url` | lowercase `https://`, `http://` or `mailto:` as `protocols` allows, printable ASCII without space, quotes, `<>`, backtick or `\`, up to 2048 characters, accepted by `new URL()`, no userinfo; `mailto:` with one address and only `subject`/`body` | the same string |
| `date` | existing ISO date `YYYY-MM-DD`, within `min`/`max` | the same ISO string |
| `array` | JSON up to 32768 characters and 3 levels, checked against `items` | a new list; inner objects keep only declared fields |
| `object` | JSON up to 32768 characters and 3 levels, checked against `fields`/`required` | a new object with only the declared fields |