@boxa-devops/depo-shared 1.0.1

package/src/errors.ts

@@ -0,0 +1,25 @@
+/** Error body shape used by all API 4xx responses: {code, message, detail?}. */
+export interface ApiErrorDetail {
+  code: string;
+  message: string;
+  detail?: string;
+}
+
+/** Thrown for any non-2xx response. status 0 = network failure. */
+export class ApiError extends Error {
+  status: number;
+  code: string;
+  detail?: string;
+  /** The whole refusal payload. Some refusals carry structured context the
+   *  UI must render (e.g. 409 ROLE_SCOPE_CHANGE lists the affected grants).
+   *  Defaults to `err` when the caller has no wider envelope to hand over. */
+  body: unknown;
+
+  constructor(status: number, err: ApiErrorDetail, body?: unknown) {
+    super(err.message);
+    this.status = status;
+    this.code = err.code;
+    this.detail = err.detail;
+    this.body = body ?? err;
+  }
+}

package/src/i18nGuard.ts

@@ -0,0 +1,77 @@
+/**
+ * The guard that would have caught it: no key the code CALLS may be missing
+ * from the dictionaries.
+ *
+ * On 2026-09-03 the admin locale files lost 141 keys and every screen that used
+ * them rendered its key verbatim — «orders.reasonPlanned» in the orders filter,
+ * «passport.stage.ANY» on the Texpasport tab. The suites went red one screen at
+ * a time, and the parity test (i18n.test.tsx) stayed GREEN throughout: it
+ * compares ru against uz, so a key missing from BOTH is perfectly symmetrical.
+ *
+ * This one reads the other direction — from the source to the dictionaries —
+ * and is deliberately static: it needs no screen to be rendered, so it covers
+ * pages no render test mounts. Its runtime twin lives in each app's
+ * test-setup.ts, where i18next is told to THROW on a miss; that one catches the
+ * keys a screen builds at runtime out of an enum code, which no scanner can
+ * resolve.
+ *
+ * The body lives here, the globs stay per app: each app feeds its own `src`
+ * PLUS this package, so a `t()` inside a shared component is checked against
+ * both dictionaries that render it.
+ */
+
+export type Dict = { [k: string]: string | Dict };
+
+/** `t("orders.reason")` / `i18n.t("...")` — a key spelled out in full. */
+const LITERAL = /\bt\(\s*"([a-z][a-zA-Z0-9_]*(?:\.[a-zA-Z0-9_]+)+)"/g;
+/** t(`passport.stage.${row.stages}`) — only the fixed head is knowable here. */
+const TEMPLATE = /\bt\(\s*`([a-z][a-zA-Z0-9_]*(?:\.[a-zA-Z0-9_]+)*)\.\$\{/g;
+
+function flat(d: Dict, prefix = ""): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(d)) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (typeof v === "string") out[key] = v;
+    else Object.assign(out, flat(v, key));
+  }
+  return out;
+}
+
+/** Does this path name a group of keys (an object), rather than one string? */
+function group(d: Dict, dotted: string): boolean {
+  let node: string | Dict | undefined = d;
+  for (const part of dotted.split(".")) {
+    if (typeof node !== "object" || node === null) return false;
+    node = node[part];
+  }
+  return typeof node === "object" && node !== null;
+}
+
+function used(sources: Record<string, string>, re: RegExp): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  for (const [path, text] of Object.entries(sources)) {
+    // the guard and the setup spell example keys out in their own regexes
+    if (path.endsWith("i18nKeys.test.ts") || path.endsWith("i18nGuard.ts")) continue;
+    if (path.endsWith("test-setup.ts")) continue;
+    for (const m of text.matchAll(re)) {
+      out.set(m[1], [...(out.get(m[1]) ?? []), path.replace("./", "")]);
+    }
+  }
+  return out;
+}
+
+/** Keys called in `sources` that are absent from any of `dicts`. */
+export function missingKeys(sources: Record<string, string>, dicts: Dict[]): string[] {
+  const flats = dicts.map((d) => flat(d));
+  return [...used(sources, LITERAL)]
+    .filter(([key]) => flats.some((f) => !(key in f)))
+    // named, not counted: the failure has to say WHICH screen prints a raw key
+    .map(([key, files]) => `${key} (${[...new Set(files)].join(", ")})`);
+}
+
+/** Heads of dynamic keys — t(`x.y.${code}`) — whose group is absent. */
+export function missingKeyGroups(sources: Record<string, string>, dicts: Dict[]): string[] {
+  return [...used(sources, TEMPLATE)]
+    .filter(([key]) => dicts.some((d) => !group(d, key)))
+    .map(([key, files]) => `${key}.* (${[...new Set(files)].join(", ")})`);
+}

package/src/i18nKeys.ts

@@ -0,0 +1,15 @@
+/**
+ * Every i18n key the components in this package resolve against the
+ * CONSUMER's dictionary. The components carry no dictionary of their own —
+ * they call the host app's `t()`, so a key that exists here and nowhere in
+ * depo-terminal / depo-admin throws at runtime (both apps configure i18next
+ * to throw on a miss).
+ *
+ * Before the split each app's i18nKeys.test.ts globbed
+ * ../../../packages/shared/src to catch this. That relative path cannot
+ * survive separate repos, so the list is explicit and guarded on the
+ * PRODUCING side instead: i18nKeys.test.ts here fails if a component calls
+ * t() with a key missing from this array, and each app asserts every key in
+ * the array exists in its own ru.json and uz.json.
+ */
+export const SHARED_I18N_KEYS = ["lang.switch"] as const;

package/src/index.ts

@@ -0,0 +1,168 @@
+// Generated API types land in src/api.ts via `pnpm generate` (openapi-typescript).
+import type { components } from "./api.js";
+
+export type Schemas = components["schemas"];
+
+export type TokenOut = Schemas["TokenOut"];
+export type EventOut = Schemas["EventOut"];
+
+// Admin web auth (B8): password + TOTP 2FA, httpOnly cookie session.
+export type LoginIn = Schemas["LoginIn"];
+export type EnrollIn = Schemas["EnrollIn"];
+export type EnrollConfirmIn = Schemas["EnrollConfirmIn"];
+export type EnrollBeginOut = Schemas["EnrollBeginOut"];
+export type SessionOut = Schemas["AdminSessionOut"];
+
+// Item card + history + work order (admin star screens, B8).
+export type ItemCard = Schemas["ItemCard"];
+export type ItemCandidate = Schemas["ItemCandidate"];
+export type HistoryEvent = Schemas["HistoryEvent"];
+export type HistoryPage = Schemas["HistoryPage"];
+export type DefectHistoryRow = Schemas["DefectHistoryRow"];
+export type DefectProposalRow = Schemas["DefectProposalRow"];
+export type NomenclatureReviewRow = Schemas["NomenclatureReviewRow"];
+export type StateAtOut = Schemas["StateAtOut"];
+
+// Part passport (B15): the FORM of a part type — every field the depot's
+// formular asks, measured or not — and the answers one instance carries.
+export type NomenclatureFieldRef = Schemas["NomenclatureFieldRef"];
+export type PassportOut = Schemas["PassportOut"];
+export type PassportValue = Schemas["PassportValue"];
+export type AttrsUpdateIn = Schemas["AttrsUpdateIn"];
+export type AttrsUpdateOut = Schemas["AttrsUpdateOut"];
+export type MeasurementAddIn = Schemas["MeasurementAddIn"];
+export type MeasurementAddOut = Schemas["MeasurementAddOut"];
+export type NomenclatureOperationRef = Schemas["NomenclatureOperationRef"];
+export type MeasurementValueIn = Schemas["MeasurementValueIn"];
+export type ItemMeasurementRow = Schemas["ItemMeasurementRow"];
+export type ItemMeasurements = Schemas["ItemMeasurementsOut"];
+export type ServiceHistoryRow = Schemas["ServiceHistoryRow"];
+export type NomenclatureFieldOut = Schemas["NomenclatureFieldOut"];
+export type NomenclatureOperationOut = Schemas["NomenclatureOperationOut"];
+export type NomenclatureRuleOut = Schemas["NomenclatureRuleOut"];
+export type RuleParamOut = Schemas["RuleParamOut"];
+export type RulePreviewOut = Schemas["RulePreviewOut"];
+export type RecommendationOut = Schemas["RecommendationOut"];
+export type WorkOrderOut = Schemas["WorkOrderOut"];
+export type WorkOrderDetail = Schemas["WorkOrderDetail"];
+export type TaskOut = Schemas["TaskOut"];
+export type AssignmentOut = Schemas["AssignmentOut"];
+export type SignatureOut = Schemas["SignatureOut"];
+export type SearchResults = Schemas["SearchResults"];
+
+// Staff card (B: person + role grants + badge saved as one unit).
+export type StaffOut = Schemas["StaffOut"];
+export type StaffSave = Schemas["StaffSave"];
+export type RoleGrantIn = Schemas["RoleGrantIn"];
+export type RoleGrantOut = Schemas["RoleGrantOut"];
+export type RoleTemplateOut = Schemas["RoleTemplateOut"];
+export type StaffImportRow = Schemas["ImportRowOut"];
+export type StaffImportResult = Schemas["ImportResultOut"];
+
+// Dictionary tabs: one xlsx importer and one record lifecycle for all of them
+// (services/dict_import, services/dict_refs).
+export type DictImportRow = Schemas["DictImportRow"];
+export type DictImportResult = Schemas["DictImportResult"];
+export type Deletable = Schemas["DeletableOut"];
+
+// Locomotive card (read-only admin card page).
+export type LocomotiveCard = Schemas["LocomotiveCard"];
+export type LocoComposition = Schemas["CompositionOut"];
+export type LocoCompositionAt = Schemas["CompositionAtOut"];
+export type LocoCompositionGroup = Schemas["CompositionGroup"];
+export type LocoCompositionItem = Schemas["CompositionItem"];
+export type LocoHistoryEvent = Schemas["LocoHistoryEvent"];
+export type LocoHistoryPage = Schemas["LocoHistoryPage"];
+
+// A «machine» is the (series, number) group of section rows — no such table
+// exists, the API groups on read (routers/loco_units.py).
+export type LocoUnitRow = Schemas["LocoUnitRow"];
+export type LocoUnitCard = Schemas["LocoUnitCard"];
+export type LocoUnitSection = Schemas["UnitSection"];
+
+// Terminal v2 master mode (B10): grid, field-register, co-signatures.
+export type LocoOverviewRow = Schemas["LocoOverviewRow"];
+export type LocoSeriesRow = Schemas["LocoSeriesOut"];
+export type FieldRegisterIn = Schemas["FieldRegisterIn"];
+export type FieldRegisterOut = Schemas["FieldRegisterOut"];
+export type WorkSignIn = Schemas["WorkSignIn"];
+export type WorkSignOut = Schemas["WorkSignOut"];
+export type NomenclatureSuggestRow = Schemas["NomenclatureSuggestRow"];
+export type NomenclatureCategoryRef = Schemas["NomenclatureCategoryRef"];
+export type NomenclatureRef = Schemas["NomenclatureRef"];
+export type NomenclatureQuickCreateOut = Schemas["NomenclatureQuickCreateOut"];
+
+// B13 «Ro'yxatga olish»: a whole pass over a machine under one signature.
+export type FieldRegisterBatchIn = Schemas["FieldRegisterBatchIn"];
+export type StockReceiveBatchIn = Schemas["StockReceiveBatchIn"];
+export type FieldRegisterBatchOut = Schemas["FieldRegisterBatchOut"];
+export type FieldRegisterEntry = Schemas["FieldRegisterEntry"];
+
+// Two-act custody handover (TZ 3.7): give (HANDOVER_GIVE) then accept/decline.
+export type HandoverGiveIn = Schemas["HandoverGiveIn"];
+export type HandoverAcceptIn = Schemas["HandoverAcceptIn"];
+export type HandoverDeclineIn = Schemas["HandoverDeclineIn"];
+export type HandoverOut = Schemas["HandoverOut"];
+export type PendingHandoverOut = Schemas["PendingHandoverOut"];
+
+/** Discriminated union of POST /api/v1/events command bodies. */
+export type EventCommand =
+  | Schemas["InstallCommand"]
+  | Schemas["MoveCommand"]
+  | Schemas["HandoverCommand"]
+  | Schemas["RemoveCommand"]
+  | Schemas["ReceiveOpeningCommand"]
+  | Schemas["FoundCommand"]
+  | Schemas["InspectCommand"]
+  | Schemas["DispositionCommand"]
+  | Schemas["StornoCommand"]
+  | Schemas["RepairStartCommand"]
+  | Schemas["RepairPauseCommand"]
+  | Schemas["RepairResumeCommand"]
+  | Schemas["RepairFinishCommand"]
+  | Schemas["GenericCommand"];
+
+export type EventType = EventCommand["event_type"];
+
+/** Runtime list of all journal event types (mirrors the EventCommand union). */
+export const EVENT_TYPES: readonly EventType[] = [
+  "INSTALL",
+  "MOVE",
+  "HANDOVER",
+  "REMOVE",
+  "RECEIVE_OPENING",
+  "FOUND",
+  "INSPECT",
+  "DISPOSITION",
+  "STORNO",
+  "RECEIVE_NEW",
+  "ISSUE_OUT",
+  "SEND_TO_REPAIR",
+  "REPAIR_START",
+  "REPAIR_PAUSE",
+  "REPAIR_RESUME",
+  "REPAIR_FINISH",
+  "QC_ACCEPT",
+  "QC_REJECT",
+  "STORE_IN",
+  "ASSEMBLE",
+  "DISASSEMBLE",
+  "SEND_TO_PLANT",
+  "RETURN_FROM_PLANT",
+  "PLANT_REJECT",
+  "COUNT",
+  "SCRAP",
+  "LOST",
+];
+
+export { ApiError } from "./errors.js";
+export type { ApiErrorDetail } from "./errors.js";
+export { statusDot } from "./status.js";
+export { LANGS, setLanguage, storedLanguage } from "./lang.js";
+export type { Lang } from "./lang.js";
+export { LangSwitch } from "./LangSwitch.js";
+export { PartPhoto } from "./PartPhoto.js";
+export { missingKeys, missingKeyGroups } from "./i18nGuard.js";
+export type { Dict } from "./i18nGuard.js";
+// i18n keys the components here resolve against the CONSUMER's dictionary
+export { SHARED_I18N_KEYS } from "./i18nKeys.js";

package/src/lang.ts

@@ -0,0 +1,26 @@
+import i18n from "i18next";
+
+export const LANGS = ["uz", "ru"] as const;
+export type Lang = (typeof LANGS)[number];
+
+const STORAGE_KEY = "depo.lang";
+
+/** The remembered choice, per browser. localStorage throws in a locked-down
+ *  profile (a kiosk is one) — the caller's default covers that. */
+export function storedLanguage(): Lang | null {
+  try {
+    const v = localStorage.getItem(STORAGE_KEY);
+    return LANGS.includes(v as Lang) ? (v as Lang) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function setLanguage(lng: Lang): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, lng);
+  } catch {
+    // private / locked-down mode: the choice just does not survive a reload
+  }
+  void i18n.changeLanguage(lng);
+}

package/src/status.ts

@@ -0,0 +1,23 @@
+/** Hue per part status, shared by the registry and the monoblock: the same
+ *  status keeps the same color everywhere. Tokens live in tokens.css
+ *  (--color-st-*); labels stay per-app, they differ by product wording. */
+const DOT: Record<string, string> = {
+  IN_STOCK_NEW: "bg-st-blue",
+  IN_STOCK_OK: "bg-st-green",
+  IN_STOCK_DEFECT: "bg-st-amber",
+  INSTALLED: "bg-st-teal",
+  REMOVED: "bg-st-slate",
+  IN_TRANSIT: "bg-st-sky",
+  IN_REPAIR: "bg-st-amber",
+  AWAITING_QC: "bg-st-purple",
+  AWAITING_DISPOSITION: "bg-st-orange",
+  PLANT_REPAIR: "bg-st-indigo",
+  SCRAPPED: "bg-st-red",
+  LOST: "bg-st-red-dark",
+  REPLACED: "bg-st-stone",
+};
+
+/** Dot class for a part status; unknown statuses render neutral. */
+export function statusDot(status: string): string {
+  return DOT[status] ?? "bg-st-slate";
+}

package/tokens.css

@@ -0,0 +1,141 @@
+/* ============================================================================
+   Design tokens — «технический формуляр депо».
+   THE ONLY place where color / radius / shadow / duration values live.
+   A hex code anywhere else in apps/admin is a review error.
+
+   WCAG AA contrast (computed, normal text needs >= 4.5):
+     ink      #1A2332 on steel #EEF0F2 = 13.82   ink   on paper #FFF = 15.78
+     ink-2    #44506A on paper         =  8.07   ink-2 on steel     =  7.07
+     ink-3    #66718A on paper         =  4.89
+     accent   #1E4D8C on paper         =  8.42   accent on steel    =  7.37
+     white on accent  #1E4D8C          =  8.42   white on ink       = 15.78
+     white on danger  #C62828          =  5.62   white on ok #2E7D32=  5.13
+     ink on warn      #F59F00          =  7.40  (amber tiles keep dark text)
+     warn-ink #7A4F00 on warn-tint     =  6.47
+     danger-ink #B71C1C on danger-tint =  5.65
+     ok-ink   #1B5E20 on ok-tint       =  6.86
+     sidebar text #C9D2E0 on ink       = 10.36
+     link     #2A5FA8 on paper         =  6.36
+   ========================================================================= */
+
+/* --- Self-hosted fonts (depot may live without internet: no CDN, ever) --- */
+@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: url("/fonts/inter-latin-wght.woff2") format("woff2-variations");
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA,
+    U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191,
+    U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: url("/fonts/inter-cyrillic-wght.woff2") format("woff2-variations");
+  unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
+}
+@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: url("/fonts/inter-cyrillic-ext-wght.woff2") format("woff2-variations");
+  unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F,
+    U+FE2E-FE2F;
+}
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 100 800;
+  font-display: swap;
+  src: url("/fonts/jetbrains-mono-latin-wght.woff2") format("woff2-variations");
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA,
+    U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191,
+    U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 100 800;
+  font-display: swap;
+  src: url("/fonts/jetbrains-mono-cyrillic-wght.woff2") format("woff2-variations");
+  unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
+}
+
+@theme {
+  /* Wipe the stock Tailwind palette: bg-gray-50 / text-indigo-600 & co stop
+     compiling, so every color goes through the tokens below. */
+  --color-*: initial;
+
+  /* --- Neutrals ---------------------------------------------------------- */
+  --color-steel: #eef0f2; /* app background — cold light grey */
+  --color-paper: #ffffff; /* surfaces: cards, tables, header */
+  --color-ink: #1a2332; /* primary text; also the sidebar fill */
+  --color-ink-2: #44506a; /* secondary text */
+  --color-ink-3: #66718a; /* muted text, placeholders (AA on paper) */
+  --color-line: #d5dae1; /* hairline borders */
+  --color-line-strong: #aeb6c2; /* emphasized rules (form header frame) */
+  --color-hover: #f4f6f8; /* row hover — half a tone off paper */
+  --color-white: #ffffff;
+  --color-transparent: transparent;
+
+  /* --- Accent: deep railway blue. Decor NEVER uses signal colors. -------- */
+  --color-accent: #1e4d8c;
+  --color-accent-2: #2a5fa8; /* links, hover of primary */
+  --color-accent-tint: #e8eef6; /* selected chip / active nav tint */
+  --color-accent-lt: #7fa8d9; /* accent lightened for dark (sidebar) surfaces */
+
+  /* --- Signals — reserved for statuses & alarms only --------------------- */
+  --color-danger: #c62828;
+  --color-danger-ink: #b71c1c;
+  --color-danger-tint: #fbeaea;
+  --color-warn: #f59f00;
+  --color-warn-ink: #7a4f00;
+  --color-warn-tint: #fdf3df;
+  --color-ok: #2e7d32;
+  --color-ok-ink: #1b5e20;
+  --color-ok-tint: #e8f2e9;
+
+  /* --- Status hues (badge dots, chart fills). Same semantics as before the
+         restyle: hue per status unchanged, execution unified. ------------- */
+  --color-st-blue: #1565c0; /* IN_STOCK_NEW */
+  --color-st-green: #2e7d32; /* IN_STOCK_OK */
+  --color-st-teal: #00796b; /* INSTALLED */
+  --color-st-slate: #64748b; /* REMOVED, neutral/unknown */
+  --color-st-sky: #0288d1; /* IN_TRANSIT, ACCEPTED */
+  --color-st-amber: #f59f00; /* IN_STOCK_DEFECT, IN_REPAIR, IN_PROGRESS */
+  --color-st-purple: #7b1fa2; /* AWAITING_QC */
+  --color-st-orange: #e65100; /* AWAITING_DISPOSITION */
+  --color-st-indigo: #3949ab; /* PLANT_REPAIR, OPEN orders */
+  --color-st-violet: #7e57c2; /* ON_HOLD */
+  --color-st-red: #c62828; /* SCRAPPED, RETURNED */
+  --color-st-red-dark: #8e1919; /* LOST */
+  --color-st-stone: #8d6e63; /* REPLACED */
+  --color-st-cyan: #0097a7; /* repair event group on the history ribbon */
+
+  /* --- Type -------------------------------------------------------------- */
+  --font-sans: "Inter", system-ui, -apple-system, "Segoe UI", sans-serif;
+  --font-mono: "JetBrains Mono", ui-monospace, "Cascadia Mono", Consolas,
+    monospace;
+
+  /* --- One radius. 6px. Not a zoo. (rounded-full stays for dots) --------- */
+  --radius-sm: 6px;
+  --radius-md: 6px;
+  --radius-lg: 6px;
+  --radius-xl: 6px;
+
+  /* --- Two shadows: rest and raise --------------------------------------- */
+  --shadow-rest: 0 1px 2px rgb(26 35 50 / 0.07);
+  --shadow-raise: 0 10px 28px rgb(26 35 50 / 0.16);
+
+  /* --- Motion: hover/focus 120ms, modals/toasts 200ms --------------------- */
+  --default-transition-duration: 120ms;
+  --duration-fast: 120ms;
+  --duration-slow: 200ms;
+}
+
+/* Spacing: stock Tailwind 4px base already yields the 4/8/12/16/24/32 scale
+   (p-1/2/3/4/6/8) — keep it, use only those steps. */