# Definitions

Definitions are a shared lookup system for label/value pairs used across forms, filters, and tags.

## Storage and Management

Definitions are database-backed records. There is no admin CRUD UI for them — they are managed via seeders and migrations.

- Migration: `database/migrations/2026_03_12_001950_create_definitions_table.php`
- Seeder: `database/seeders/_02_DefinitionSeeder.php`

## Database Columns

The `definitions` table has the following columns:

| Column | Type | Notes |
|---|---|---|
| `key` | string | indexed; groups related definitions |
| `value` | string | the stored value |
| `label` | string | human-readable display label |
| `explanation` | text | nullable; additional description |
| `severity` | string | nullable; e.g. `info`, `warning`, `danger` |
| `icon` | string | nullable; icon identifier |
| `is_active` | boolean | defaults to `true` |
| `order` | integer | defaults to `0`; controls sort order |
| `visibility` | boolean | defaults to `true` |
| `lang` | string(35) | defaults to `en`; supports i18n |

A unique constraint is enforced on `(key, value, lang)`.

> **Why `lang` is 35 characters, not 255.** The composite unique index over three default 255-character `utf8mb4` columns measures 3060 bytes against InnoDB's 3072-byte key limit — one character of headroom on any one column away from breaking outright. The `2026_08_31_120000_narrow_definitions_unique_index_columns` migration narrows `lang` to 35, the widest locale value the kit accepts anywhere (`content_languages.code`), leaving ~892 bytes of headroom; `key` and `value` keep their published 255. The migration measures every existing row first — soft-deleted ones included — and **refuses, leaving the schema unchanged, if a single row would be truncated**. Both directions end by asserting the unique index exists (name, uniqueness and the exact `{key, value, lang}` column set), so a table that arrives with a drifted or missing index gets the real one rebuilt instead of being recorded as migrated without its guarantee. See [UPGRADE.md](https://starter-kit.lvntr.dev/docs/upgrade).

## Access Points

- web service route: `/definitions`
- API route: `/api/v1/definitions`
- frontend composable: `useDefinition()`

## Frontend Benefits

Definitions make it easy to:

- populate select options
- render status tags consistently
- share the same meaning across pages and modules

## Common Methods

From `useDefinition()`:

- `load(keys)`
- `loadAll()`
- `list(key)`
- `options(key)`
- `find(key, value)`
- `clearCache()`