/**
 * The small shapes the backend's resource traits emit over and over.
 *
 * These live in one place because they are *trait* output, not per-endpoint
 * output: `ResolvesApiPayloads` and `BuildsWebsiteFields` are mixed into
 * forty-three resources, so the same four or five literal shapes reappear
 * across every feature. Each type below names the PHP method it transcribes,
 * because the differences between them are the whole point — two of them look
 * interchangeable and are not.
 */

/**
 * A number the backend ran through `ar_num()`.
 *
 * `ar_num()` (`app/Support/helpers.php:262`) returns Eastern Arabic digits as a
 * **string** when the request locale is `ar`, and the untouched value
 * otherwise — so the same field is `18` in English and `"١٨"` in Arabic.
 *
 * `lib/api/client.ts` runs `normalizeDigitsDeep` over every axios response, so
 * a client reader sees `"18"` rather than `"١٨"`. It is still a *string*: the
 * normalizer rewrites the glyphs, it does not re-parse the value. Anything
 * doing arithmetic on one of these must coerce — `Number("١٨")` is `NaN`, and
 * `Number("18")` is fine, which is exactly why the bug only shows in Arabic.
 *
 * Server Components fetch through `features/<domain>/services/server.ts`, which pins
 * `Accept-Language: en` via `SERVER_API_HEADERS`, so those reads only ever see
 * the number half.
 */
export type ArabicNumeric = number | string;

/**
 * A choice embedded by `BuildsWebsiteFields::websiteChoicePayload()`.
 *
 * **Every key is optional**, and that is not defensive typing: the method ends
 * in `array_filter(…, fn ($value) => $value !== null)`, which *drops* null
 * entries from the array, so a null column arrives as a **missing key** rather
 * than as `null`. `choice_type` is only present when the caller passes one, and
 * most callers do not.
 *
 * Contrast `MasterChoiceDisplay`, which keeps its nulls and carries a `slug`.
 * Reading `.slug` off one of these is always `undefined`.
 */
/**
 * The least a reader needs to render a localized choice: the two labels, each
 * possibly absent *and* possibly null.
 *
 * Both halves happen, for different reasons — `websiteChoicePayload()` drops
 * a null key (absent), while `websiteInterestDisplay()` emits
 * `value_en ?? name_en`, which is null when both columns are empty. A helper
 * that only renders a label should take this rather than one of the concrete
 * shapes, so it accepts either.
 */
export interface LocalizedChoice {
  value_en?: string | null;
  value_ar?: string | null;
}

export interface WebsiteChoiceDisplay {
  id?: number;
  choice_type?: string;
  value_en?: string;
  value_ar?: string;
}

/**
 * A choice embedded by `ResolvesApiPayloads::masterChoicePayload()`.
 *
 * The detail-resource counterpart of `WebsiteChoiceDisplay`. It does **not**
 * filter nulls, so the keys are always present and may be null, and it adds
 * `slug` plus a `choice_type` resolved from the `choiceType` relation (so
 * `choice_type` is null when that relation is missing, not absent).
 */
export interface MasterChoiceDisplay {
  id: number;
  choice_type: string | null;
  value_en: string | null;
  value_ar: string | null;
  slug: string | null;
}

/**
 * A creator as the **website/card** resources emit it:
 * `BuildsWebsiteFields::websiteCreatorId()`.
 *
 * It is `{ id }` and nothing else. The card payloads carry no name, photo or
 * social links for the creator — reading `created_by.full_name` off a list row
 * yields `undefined`, silently. The detail resources use
 * `createdByPayload()` instead and do carry all of that; see
 * `OpportunityCreatorRecord`.
 */
export interface CreatorIdRecord {
  id: number;
}

/** A registered user id, from `websiteRegisteredUserIds()` / `allRegisteredUsersPayload()`. */
export interface RegisteredUserIdRecord {
  id: number;
}

/**
 * The `*_display` pair the two volunteer-category fields use.
 *
 * Note the keys: `en`/`ar`, **not** `value_en`/`value_ar` like every choice
 * payload beside it. It is built inline in the resources from
 * `labelEn()`/`labelAr()` rather than from a `MasterChoice` row.
 */
export interface EnArLabel {
  en: string;
  ar: string;
}
