@tea-ui/ux-standards 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 landnevermore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @tea-ui/ux-standards
+
+The written rules components are held to, as data rather than prose.
+
+Part of [TEA UI](https://landnevermore.github.io/TEAui/) — a design system built once and reused across
+products. The whole system is documented at https://landnevermore.github.io/TEAui/docs/.
+
+## Install
+
+```bash
+npm install @tea-ui/ux-standards
+```
+
+React 18.2 or 19 is expected as a peer dependency.
+
+## Use
+
+```ts
+import { tokens } from "@tea-ui/ux-standards";
+```
+
+## Licence
+
+MIT. See [LICENSE](./LICENSE).

package/dist/destructive.d.ts

@@ -0,0 +1,58 @@
+/**
+ * TEA UI — destructive action policy.
+ *
+ * The rule that matters: choose the *weakest* protection that is sufficient
+ * for the consequence. Every unnecessary confirmation dialog is a dialog the
+ * user learns to dismiss without reading, and that habit is what makes the one
+ * dialog they should have read get dismissed too. So confirmation is spent
+ * where it buys something, and undo is used wherever it is available.
+ *
+ * The audit found the opposite at both source projects: a reversible two-step
+ * inline confirmation sitting next to an irreversible `DELETE` with no
+ * confirmation at all.
+ */
+declare const CONSEQUENCE_LEVELS: readonly ["reversible", "recoverable", "irreversible"];
+type ConsequenceLevel = (typeof CONSEQUENCE_LEVELS)[number];
+/** How a destructive action must be protected. */
+type Protection = "undo" | "confirm" | "confirm-typed" | "confirm-hold";
+interface DestructivePolicy {
+    /** What the action destroys. */
+    readonly level: ConsequenceLevel;
+    /** The protection TEA UI requires. */
+    readonly protection: Protection;
+    /** Whether the consequence must be spelled out in the dialog body. */
+    readonly explainConsequence: boolean;
+    /** Whether the primary button may be the destructive one. */
+    readonly destructivePrimary: boolean;
+}
+/**
+ * The policy table.
+ *
+ * `reversible`   — undo is offered instead of a dialog. Nothing is asked.
+ * `recoverable`  — a confirm dialog, because the data can be recovered but the
+ *                  user would notice its absence. The primary button is NOT
+ *                  destructive: cancelling must be the easy path.
+ * `irreversible` — a confirm dialog that names the consequence, and for
+ *                  anything that cannot be undone at all, requires typing the
+ *                  resource name. Cancelling stays the default focus.
+ */
+declare const DESTRUCTIVE_POLICY: Readonly<Record<ConsequenceLevel, DestructivePolicy>>;
+declare function destructivePolicy(level: ConsequenceLevel): DestructivePolicy;
+/** The verb pair an alert dialog uses, per the content standard (§22). */
+declare const DESTRUCTIVE_VERBS: {
+    readonly confirm: {
+        readonly reversible: "Ausführen";
+        readonly recoverable: "Trotzdem fortfahren";
+        readonly irreversible: "Endgültig löschen";
+    };
+    readonly cancel: "Abbrechen";
+};
+/**
+ * The consequence sentence a dialog body must contain. Written as a function
+ * rather than a template so the noun stays in one place — a dialog that says
+ * "wird gelöscht" next to a button that says "Wiederherstellen" is worse than
+ * no dialog.
+ */
+declare function consequenceSentence(what: string, level: ConsequenceLevel): string;
+
+export { CONSEQUENCE_LEVELS, type ConsequenceLevel, DESTRUCTIVE_POLICY, DESTRUCTIVE_VERBS, type DestructivePolicy, type Protection, consequenceSentence, destructivePolicy };

package/dist/destructive.js

@@ -0,0 +1,50 @@
+const CONSEQUENCE_LEVELS = ["reversible", "recoverable", "irreversible"];
+const DESTRUCTIVE_POLICY = {
+  reversible: {
+    level: "reversible",
+    protection: "undo",
+    explainConsequence: false,
+    destructivePrimary: false
+  },
+  recoverable: {
+    level: "recoverable",
+    protection: "confirm",
+    explainConsequence: true,
+    destructivePrimary: false
+  },
+  irreversible: {
+    level: "irreversible",
+    protection: "confirm-typed",
+    explainConsequence: true,
+    destructivePrimary: false
+  }
+};
+function destructivePolicy(level) {
+  return DESTRUCTIVE_POLICY[level];
+}
+const DESTRUCTIVE_VERBS = {
+  confirm: {
+    reversible: "Ausf\xFChren",
+    recoverable: "Trotzdem fortfahren",
+    irreversible: "Endg\xFCltig l\xF6schen"
+  },
+  cancel: "Abbrechen"
+};
+function consequenceSentence(what, level) {
+  switch (level) {
+    case "reversible":
+      return `${what} wird kurz zur\xFCckgenommen werden k\xF6nnen.`;
+    case "recoverable":
+      return `${what} wird endg\xFCltig entfernt. Eine Wiederherstellung ist nur aus einer Sicherung m\xF6glich.`;
+    case "irreversible":
+      return `${what} wird endg\xFCltig entfernt. Dieser Schritt kann nicht r\xFCckg\xE4ngig gemacht werden.`;
+  }
+}
+export {
+  CONSEQUENCE_LEVELS,
+  DESTRUCTIVE_POLICY,
+  DESTRUCTIVE_VERBS,
+  consequenceSentence,
+  destructivePolicy
+};
+//# sourceMappingURL=destructive.js.map

package/dist/destructive.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/destructive.ts"],"sourcesContent":["/**\n * TEA UI — destructive action policy.\n *\n * The rule that matters: choose the *weakest* protection that is sufficient\n * for the consequence. Every unnecessary confirmation dialog is a dialog the\n * user learns to dismiss without reading, and that habit is what makes the one\n * dialog they should have read get dismissed too. So confirmation is spent\n * where it buys something, and undo is used wherever it is available.\n *\n * The audit found the opposite at both source projects: a reversible two-step\n * inline confirmation sitting next to an irreversible `DELETE` with no\n * confirmation at all.\n */\n\nexport const CONSEQUENCE_LEVELS = [\"reversible\", \"recoverable\", \"irreversible\"] as const;\n\nexport type ConsequenceLevel = (typeof CONSEQUENCE_LEVELS)[number];\n\n/** How a destructive action must be protected. */\nexport type Protection = \"undo\" | \"confirm\" | \"confirm-typed\" | \"confirm-hold\";\n\nexport interface DestructivePolicy {\n  /** What the action destroys. */\n  readonly level: ConsequenceLevel;\n  /** The protection TEA UI requires. */\n  readonly protection: Protection;\n  /** Whether the consequence must be spelled out in the dialog body. */\n  readonly explainConsequence: boolean;\n  /** Whether the primary button may be the destructive one. */\n  readonly destructivePrimary: boolean;\n}\n\n/**\n * The policy table.\n *\n * `reversible`   — undo is offered instead of a dialog. Nothing is asked.\n * `recoverable`  — a confirm dialog, because the data can be recovered but the\n *                  user would notice its absence. The primary button is NOT\n *                  destructive: cancelling must be the easy path.\n * `irreversible` — a confirm dialog that names the consequence, and for\n *                  anything that cannot be undone at all, requires typing the\n *                  resource name. Cancelling stays the default focus.\n */\nexport const DESTRUCTIVE_POLICY: Readonly<Record<ConsequenceLevel, DestructivePolicy>> = {\n  reversible: {\n    level: \"reversible\",\n    protection: \"undo\",\n    explainConsequence: false,\n    destructivePrimary: false,\n  },\n  recoverable: {\n    level: \"recoverable\",\n    protection: \"confirm\",\n    explainConsequence: true,\n    destructivePrimary: false,\n  },\n  irreversible: {\n    level: \"irreversible\",\n    protection: \"confirm-typed\",\n    explainConsequence: true,\n    destructivePrimary: false,\n  },\n};\n\nexport function destructivePolicy(level: ConsequenceLevel): DestructivePolicy {\n  return DESTRUCTIVE_POLICY[level];\n}\n\n/** The verb pair an alert dialog uses, per the content standard (§22). */\nexport const DESTRUCTIVE_VERBS = {\n  confirm: {\n    reversible: \"Ausführen\",\n    recoverable: \"Trotzdem fortfahren\",\n    irreversible: \"Endgültig löschen\",\n  },\n  cancel: \"Abbrechen\",\n} as const;\n\n/**\n * The consequence sentence a dialog body must contain. Written as a function\n * rather than a template so the noun stays in one place — a dialog that says\n * \"wird gelöscht\" next to a button that says \"Wiederherstellen\" is worse than\n * no dialog.\n */\nexport function consequenceSentence(what: string, level: ConsequenceLevel): string {\n  switch (level) {\n    case \"reversible\":\n      return `${what} wird kurz zurückgenommen werden können.`;\n    case \"recoverable\":\n      return `${what} wird endgültig entfernt. Eine Wiederherstellung ist nur aus einer Sicherung möglich.`;\n    case \"irreversible\":\n      return `${what} wird endgültig entfernt. Dieser Schritt kann nicht rückgängig gemacht werden.`;\n  }\n}\n"],"mappings":"AAcO,MAAM,qBAAqB,CAAC,cAAc,eAAe,cAAc;AA6BvE,MAAM,qBAA4E;AAAA,EACvF,YAAY;AAAA,IACV,OAAO;AAAA,IACP,YAAY;AAAA,IACZ,oBAAoB;AAAA,IACpB,oBAAoB;AAAA,EACtB;AAAA,EACA,aAAa;AAAA,IACX,OAAO;AAAA,IACP,YAAY;AAAA,IACZ,oBAAoB;AAAA,IACpB,oBAAoB;AAAA,EACtB;AAAA,EACA,cAAc;AAAA,IACZ,OAAO;AAAA,IACP,YAAY;AAAA,IACZ,oBAAoB;AAAA,IACpB,oBAAoB;AAAA,EACtB;AACF;AAEO,SAAS,kBAAkB,OAA4C;AAC5E,SAAO,mBAAmB,KAAK;AACjC;AAGO,MAAM,oBAAoB;AAAA,EAC/B,SAAS;AAAA,IACP,YAAY;AAAA,IACZ,aAAa;AAAA,IACb,cAAc;AAAA,EAChB;AAAA,EACA,QAAQ;AACV;AAQO,SAAS,oBAAoB,MAAc,OAAiC;AACjF,UAAQ,OAAO;AAAA,IACb,KAAK;AACH,aAAO,GAAG,IAAI;AAAA,IAChB,KAAK;AACH,aAAO,GAAG,IAAI;AAAA,IAChB,KAAK;AACH,aAAO,GAAG,IAAI;AAAA,EAClB;AACF;","names":[]}

package/dist/error-anatomy.d.ts

@@ -0,0 +1,82 @@
+/**
+ * TEA UI — error anatomy.
+ *
+ * An error message is not a string, it is an answer to four questions. A
+ * message that answers fewer than all four is not "brief" — it is
+ * unactionable, and the user is forced to file a support request to find out
+ * what happened.
+ *
+ *   1. What happened?
+ *   2. Why did it happen?
+ *   3. What can the user do?
+ *   4. Can the system recover on its own?
+ *
+ * The audit found `"Error 500"`, `"Failed"` and `"IPC-Fehler"` in user-facing
+ * positions, the last of which was not merely unhelpful but actively wrong: the
+ * transport was HTTP, not IPC.
+ *
+ * {@link ErrorAnatomy} is the type every error surface in TEA UI accepts, and
+ * {@link renderErrorMessage} produces the headline sentence from it. The
+ * technical detail is optional and belongs behind a disclosure — it is for the
+ * person filing the report, not for the person who hit the problem.
+ */
+type ErrorRecovery = 
+/** Nothing the user can do; the system will retry on its own. */
+"automatic"
+/** A single obvious action, offered as the primary action. */
+ | "action"
+/** Several possible causes, so the message must not guess. */
+ | "choice"
+/** Nothing can be done here; the user must leave the screen. */
+ | "none";
+interface ErrorAnatomy {
+    /** Short, human summary of what failed. Never a status code alone. */
+    readonly title: string;
+    /** Why it failed, in one sentence. "The connection to the server timed out." */
+    readonly detail: string;
+    /** What the user can do next. Empty only when `recovery` is `automatic`. */
+    readonly action?: string;
+    /** Label for `action`, e.g. "Erneut versuchen". */
+    readonly actionLabel?: string;
+    /** Whether the system can recover without the user. */
+    readonly recovery: ErrorRecovery;
+    /** Raw detail — stack, request id, upstream body. Disclosure material. */
+    readonly technical?: string;
+    /** A support or debug reference the user can quote. */
+    readonly reference?: string;
+}
+declare const ERROR_TITLES: {
+    readonly network: "Verbindung fehlgeschlagen";
+    readonly timeout: "Zeitüberschreitung";
+    readonly unauthorized: "Nicht angemeldet";
+    readonly forbidden: "Keine Berechtigung";
+    readonly notFound: "Nicht gefunden";
+    readonly validation: "Eingabe prüfen";
+    readonly conflict: "Konflikt";
+    readonly rateLimit: "Zu viele Anfragen";
+    readonly server: "Serverfehler";
+    readonly unknown: "Unerwarteter Fehler";
+};
+type ErrorKind = keyof typeof ERROR_TITLES;
+/**
+ * The headline a user reads: what happened, plus why, in one sentence.
+ * Deliberately never a bare code, and deliberately never "Something went
+ * wrong", which states nothing and asks the user to do the diagnosis.
+ */
+declare function renderErrorMessage(error: ErrorAnatomy): string;
+/**
+ * Whether an error surface should expose a retry affordance. Only true when a
+ * retry is a real, likely-to-succeed action — offering it for a validation
+ * error teaches people that buttons do nothing.
+ */
+declare function shouldOfferRetry(error: ErrorAnatomy): boolean;
+/** Whether technical detail belongs behind a disclosure rather than inline. */
+declare function hasTechnicalDetail(error: ErrorAnatomy): boolean;
+/**
+ * Build an {@link ErrorAnatomy} from anything thrown, without inventing a
+ * message. Unrecognised values produce a real title and a real next step, and
+ * never leak `[object Object]`.
+ */
+declare function toErrorAnatomy(cause: unknown, fallback?: Partial<ErrorAnatomy>): ErrorAnatomy;
+
+export { ERROR_TITLES, type ErrorAnatomy, type ErrorKind, type ErrorRecovery, hasTechnicalDetail, renderErrorMessage, shouldOfferRetry, toErrorAnatomy };

package/dist/error-anatomy.js

@@ -0,0 +1,68 @@
+const ERROR_TITLES = {
+  network: "Verbindung fehlgeschlagen",
+  timeout: "Zeit\xFCberschreitung",
+  unauthorized: "Nicht angemeldet",
+  forbidden: "Keine Berechtigung",
+  notFound: "Nicht gefunden",
+  validation: "Eingabe pr\xFCfen",
+  conflict: "Konflikt",
+  rateLimit: "Zu viele Anfragen",
+  server: "Serverfehler",
+  unknown: "Unerwarteter Fehler"
+};
+function renderErrorMessage(error) {
+  const detail = error.detail.trim();
+  if (!detail) return error.title;
+  return `${error.title}. ${detail}`;
+}
+function shouldOfferRetry(error) {
+  return error.recovery === "action" || error.recovery === "automatic";
+}
+function hasTechnicalDetail(error) {
+  return typeof error.technical === "string" && error.technical.trim().length > 0;
+}
+function toErrorAnatomy(cause, fallback = {}) {
+  if (isErrorAnatomy(cause)) return cause;
+  if (cause instanceof Error) {
+    return {
+      title: ERROR_TITLES.unknown,
+      detail: cause.message || "Der Vorgang konnte nicht abgeschlossen werden.",
+      recovery: "action",
+      action: "Der Vorgang kann wiederholt werden.",
+      actionLabel: "Erneut versuchen",
+      // The stack is disclosure material, not a headline. It is attached here so
+      // an error surface can offer it without the product having to remember.
+      ...isDevelopment() && cause.stack ? { technical: cause.stack } : {},
+      ...fallback
+    };
+  }
+  return {
+    title: ERROR_TITLES.unknown,
+    detail: "Der Vorgang konnte nicht abgeschlossen werden.",
+    recovery: "action",
+    action: "Der Vorgang kann wiederholt werden.",
+    actionLabel: "Erneut versuchen",
+    ...fallback
+  };
+}
+function isDevelopment() {
+  try {
+    const meta = import.meta;
+    const dev = meta.env?.DEV ?? meta.env?.MODE;
+    if (typeof dev === "boolean") return dev;
+    if (typeof dev === "string") return dev === "development";
+  } catch {
+  }
+  return false;
+}
+function isErrorAnatomy(value) {
+  return typeof value === "object" && value !== null && typeof value.title === "string" && typeof value.detail === "string";
+}
+export {
+  ERROR_TITLES,
+  hasTechnicalDetail,
+  renderErrorMessage,
+  shouldOfferRetry,
+  toErrorAnatomy
+};
+//# sourceMappingURL=error-anatomy.js.map

package/dist/error-anatomy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/error-anatomy.ts"],"sourcesContent":["/**\n * TEA UI — error anatomy.\n *\n * An error message is not a string, it is an answer to four questions. A\n * message that answers fewer than all four is not \"brief\" — it is\n * unactionable, and the user is forced to file a support request to find out\n * what happened.\n *\n *   1. What happened?\n *   2. Why did it happen?\n *   3. What can the user do?\n *   4. Can the system recover on its own?\n *\n * The audit found `\"Error 500\"`, `\"Failed\"` and `\"IPC-Fehler\"` in user-facing\n * positions, the last of which was not merely unhelpful but actively wrong: the\n * transport was HTTP, not IPC.\n *\n * {@link ErrorAnatomy} is the type every error surface in TEA UI accepts, and\n * {@link renderErrorMessage} produces the headline sentence from it. The\n * technical detail is optional and belongs behind a disclosure — it is for the\n * person filing the report, not for the person who hit the problem.\n */\n\nexport type ErrorRecovery =\n  /** Nothing the user can do; the system will retry on its own. */\n  | \"automatic\"\n  /** A single obvious action, offered as the primary action. */\n  | \"action\"\n  /** Several possible causes, so the message must not guess. */\n  | \"choice\"\n  /** Nothing can be done here; the user must leave the screen. */\n  | \"none\";\n\nexport interface ErrorAnatomy {\n  /** Short, human summary of what failed. Never a status code alone. */\n  readonly title: string;\n  /** Why it failed, in one sentence. \"The connection to the server timed out.\" */\n  readonly detail: string;\n  /** What the user can do next. Empty only when `recovery` is `automatic`. */\n  readonly action?: string;\n  /** Label for `action`, e.g. \"Erneut versuchen\". */\n  readonly actionLabel?: string;\n  /** Whether the system can recover without the user. */\n  readonly recovery: ErrorRecovery;\n  /** Raw detail — stack, request id, upstream body. Disclosure material. */\n  readonly technical?: string;\n  /** A support or debug reference the user can quote. */\n  readonly reference?: string;\n}\n\nexport const ERROR_TITLES = {\n  network: \"Verbindung fehlgeschlagen\",\n  timeout: \"Zeitüberschreitung\",\n  unauthorized: \"Nicht angemeldet\",\n  forbidden: \"Keine Berechtigung\",\n  notFound: \"Nicht gefunden\",\n  validation: \"Eingabe prüfen\",\n  conflict: \"Konflikt\",\n  rateLimit: \"Zu viele Anfragen\",\n  server: \"Serverfehler\",\n  unknown: \"Unerwarteter Fehler\",\n} as const;\n\nexport type ErrorKind = keyof typeof ERROR_TITLES;\n\n/**\n * The headline a user reads: what happened, plus why, in one sentence.\n * Deliberately never a bare code, and deliberately never \"Something went\n * wrong\", which states nothing and asks the user to do the diagnosis.\n */\nexport function renderErrorMessage(error: ErrorAnatomy): string {\n  const detail = error.detail.trim();\n  if (!detail) return error.title;\n  return `${error.title}. ${detail}`;\n}\n\n/**\n * Whether an error surface should expose a retry affordance. Only true when a\n * retry is a real, likely-to-succeed action — offering it for a validation\n * error teaches people that buttons do nothing.\n */\nexport function shouldOfferRetry(error: ErrorAnatomy): boolean {\n  return error.recovery === \"action\" || error.recovery === \"automatic\";\n}\n\n/** Whether technical detail belongs behind a disclosure rather than inline. */\nexport function hasTechnicalDetail(error: ErrorAnatomy): boolean {\n  return typeof error.technical === \"string\" && error.technical.trim().length > 0;\n}\n\n/**\n * Build an {@link ErrorAnatomy} from anything thrown, without inventing a\n * message. Unrecognised values produce a real title and a real next step, and\n * never leak `[object Object]`.\n */\nexport function toErrorAnatomy(cause: unknown, fallback: Partial<ErrorAnatomy> = {}): ErrorAnatomy {\n  if (isErrorAnatomy(cause)) return cause;\n\n  if (cause instanceof Error) {\n    return {\n      title: ERROR_TITLES.unknown,\n      detail: cause.message || \"Der Vorgang konnte nicht abgeschlossen werden.\",\n      recovery: \"action\",\n      action: \"Der Vorgang kann wiederholt werden.\",\n      actionLabel: \"Erneut versuchen\",\n      // The stack is disclosure material, not a headline. It is attached here so\n      // an error surface can offer it without the product having to remember.\n      ...(isDevelopment() && cause.stack ? { technical: cause.stack } : {}),\n      ...fallback,\n    };\n  }\n\n  return {\n    title: ERROR_TITLES.unknown,\n    detail: \"Der Vorgang konnte nicht abgeschlossen werden.\",\n    recovery: \"action\",\n    action: \"Der Vorgang kann wiederholt werden.\",\n    actionLabel: \"Erneut versuchen\",\n    ...fallback,\n  };\n}\n\n/**\n * Environment check that does not assume a bundler.\n *\n * This package is imported by browser bundles, by Node scripts and by tests, so\n * neither `process` nor `import.meta.env` is available everywhere it runs — which\n * is why both are behind a guard and why nothing here declares a Node type\n * dependency. A package that cannot say where it runs cannot be used everywhere.\n */\nfunction isDevelopment(): boolean {\n  try {\n    const meta = import.meta as ImportMeta & { env?: Record<string, unknown> };\n    const dev = meta.env?.DEV ?? meta.env?.MODE;\n    if (typeof dev === \"boolean\") return dev;\n    if (typeof dev === \"string\") return dev === \"development\";\n  } catch {\n    /* not a bundler context */\n  }\n  return false;\n}\n\nfunction isErrorAnatomy(value: unknown): value is ErrorAnatomy {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as ErrorAnatomy).title === \"string\" &&\n    typeof (value as ErrorAnatomy).detail === \"string\"\n  );\n}\n"],"mappings":"AAkDO,MAAM,eAAe;AAAA,EAC1B,SAAS;AAAA,EACT,SAAS;AAAA,EACT,cAAc;AAAA,EACd,WAAW;AAAA,EACX,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,SAAS;AACX;AASO,SAAS,mBAAmB,OAA6B;AAC9D,QAAM,SAAS,MAAM,OAAO,KAAK;AACjC,MAAI,CAAC,OAAQ,QAAO,MAAM;AAC1B,SAAO,GAAG,MAAM,KAAK,KAAK,MAAM;AAClC;AAOO,SAAS,iBAAiB,OAA8B;AAC7D,SAAO,MAAM,aAAa,YAAY,MAAM,aAAa;AAC3D;AAGO,SAAS,mBAAmB,OAA8B;AAC/D,SAAO,OAAO,MAAM,cAAc,YAAY,MAAM,UAAU,KAAK,EAAE,SAAS;AAChF;AAOO,SAAS,eAAe,OAAgB,WAAkC,CAAC,GAAiB;AACjG,MAAI,eAAe,KAAK,EAAG,QAAO;AAElC,MAAI,iBAAiB,OAAO;AAC1B,WAAO;AAAA,MACL,OAAO,aAAa;AAAA,MACpB,QAAQ,MAAM,WAAW;AAAA,MACzB,UAAU;AAAA,MACV,QAAQ;AAAA,MACR,aAAa;AAAA;AAAA;AAAA,MAGb,GAAI,cAAc,KAAK,MAAM,QAAQ,EAAE,WAAW,MAAM,MAAM,IAAI,CAAC;AAAA,MACnE,GAAG;AAAA,IACL;AAAA,EACF;AAEA,SAAO;AAAA,IACL,OAAO,aAAa;AAAA,IACpB,QAAQ;AAAA,IACR,UAAU;AAAA,IACV,QAAQ;AAAA,IACR,aAAa;AAAA,IACb,GAAG;AAAA,EACL;AACF;AAUA,SAAS,gBAAyB;AAChC,MAAI;AACF,UAAM,OAAO;AACb,UAAM,MAAM,KAAK,KAAK,OAAO,KAAK,KAAK;AACvC,QAAI,OAAO,QAAQ,UAAW,QAAO;AACrC,QAAI,OAAO,QAAQ,SAAU,QAAO,QAAQ;AAAA,EAC9C,QAAQ;AAAA,EAER;AACA,SAAO;AACT;AAEA,SAAS,eAAe,OAAuC;AAC7D,SACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAAuB,UAAU,YACzC,OAAQ,MAAuB,WAAW;AAE9C;","names":[]}

package/dist/feedback.d.ts

@@ -0,0 +1,65 @@
+import { Tone } from '@tea-ui/tokens';
+
+/**
+ * TEA UI — the feedback state model.
+ *
+ * Every asynchronous surface in a TEA product is in exactly one of these
+ * states, and the states are named here so that two products handling the same
+ * situation behave the same way. The audit found eight independent
+ * "Lade …" loaders, ten empty states, nine error banners and four dialects of
+ * each, with no shared naming and inconsistent live-region behaviour.
+ *
+ * The progression the model expects, and the reason for it:
+ *
+ *   action -> immediate acknowledgement -> progress -> result -> next action
+ *
+ * A user action must never be silent. It must never show a spinner over
+ * content the user is already reading, either.
+ */
+declare const FEEDBACK_STATES: readonly ["idle", "loading", "refreshing", "processing", "success", "warning", "error", "empty", "disabled", "offline", "unauthorized", "forbidden", "notFound", "maintenance", "stale", "syncing", "retrying"];
+type FeedbackState = (typeof FEEDBACK_STATES)[number];
+type FeedbackKind = "initial" | "background" | "blocking";
+interface FeedbackMeta {
+    /**
+     * `initial`  — nothing to show yet, so a skeleton or a spinner replaces the
+     *              content. Used once, on first load.
+     * `background`— content exists and stays visible; the state is communicated
+     *              without replacing anything. Used for refresh, sync, save.
+     * `blocking`  — the user cannot proceed; a spinner or progress is required.
+     */
+    readonly kind: FeedbackKind;
+    /** The tone this state should render in, where a colour applies. */
+    readonly tone: Tone;
+    /**
+     * Whether this state is a problem the user must resolve, or merely
+     * information. Drives whether the surface offers a recovery action.
+     */
+    readonly blocking: boolean;
+    /** Whether a live region should announce a change into this state. */
+    readonly announce: boolean;
+    /** Default German noun phrase for a progress line, e.g. "Wird geladen". */
+    readonly label: string;
+}
+declare const FEEDBACK: Readonly<Record<FeedbackState, FeedbackMeta>>;
+/**
+ * States that must never replace content that is already on screen.
+ *
+ * The audit's clearest single defect: both source projects replace a whole
+ * region with a centred spinner on every poll, so a five-second auto-refresh
+ * flashes the UI away from content the user was reading. `refreshing`,
+ * `syncing`, `stale` and `retrying` must be communicated as an overlay or a
+ * quiet indicator over preserved content.
+ */
+declare const NON_DESTRUCTIVE_STATES: readonly ["refreshing", "syncing", "stale", "retrying"];
+type NonDestructiveState = (typeof NON_DESTRUCTIVE_STATES)[number];
+declare function isNonDestructive(state: FeedbackState): state is NonDestructiveState;
+declare function feedbackMeta(state: FeedbackState): FeedbackMeta;
+/**
+ * Build a `data-tea-state` value for a surface, so a state is inspectable from
+ * the DOM and assertable in a test rather than only visible.
+ */
+declare function feedbackAttr(state: FeedbackState): {
+    "data-tea-state": FeedbackState;
+};
+
+export { FEEDBACK, FEEDBACK_STATES, type FeedbackKind, type FeedbackMeta, type FeedbackState, NON_DESTRUCTIVE_STATES, type NonDestructiveState, feedbackAttr, feedbackMeta, isNonDestructive };

package/dist/feedback.js

@@ -0,0 +1,159 @@
+const FEEDBACK_STATES = [
+  "idle",
+  "loading",
+  "refreshing",
+  "processing",
+  "success",
+  "warning",
+  "error",
+  "empty",
+  "disabled",
+  "offline",
+  "unauthorized",
+  "forbidden",
+  "notFound",
+  "maintenance",
+  "stale",
+  "syncing",
+  "retrying"
+];
+const FEEDBACK = {
+  idle: {
+    kind: "background",
+    tone: "neutral",
+    blocking: false,
+    announce: false,
+    label: "Bereit"
+  },
+  loading: {
+    kind: "initial",
+    tone: "neutral",
+    blocking: true,
+    announce: true,
+    label: "Wird geladen"
+  },
+  refreshing: {
+    kind: "background",
+    tone: "neutral",
+    blocking: false,
+    announce: true,
+    label: "Wird aktualisiert"
+  },
+  processing: {
+    kind: "blocking",
+    tone: "info",
+    blocking: true,
+    announce: true,
+    label: "Wird verarbeitet"
+  },
+  success: {
+    kind: "background",
+    tone: "positive",
+    blocking: false,
+    announce: true,
+    label: "Erfolgreich"
+  },
+  warning: {
+    kind: "background",
+    tone: "caution",
+    blocking: false,
+    announce: true,
+    label: "Hinweis"
+  },
+  error: {
+    kind: "background",
+    tone: "critical",
+    blocking: false,
+    announce: true,
+    label: "Fehler"
+  },
+  empty: {
+    kind: "initial",
+    tone: "neutral",
+    blocking: false,
+    announce: true,
+    label: "Keine Eintr\xE4ge"
+  },
+  disabled: {
+    kind: "background",
+    tone: "neutral",
+    blocking: false,
+    announce: false,
+    label: "Nicht verf\xFCgbar"
+  },
+  offline: {
+    kind: "background",
+    tone: "caution",
+    blocking: false,
+    announce: true,
+    label: "Offline"
+  },
+  unauthorized: {
+    kind: "background",
+    tone: "caution",
+    blocking: true,
+    announce: true,
+    label: "Nicht angemeldet"
+  },
+  forbidden: {
+    kind: "background",
+    tone: "caution",
+    blocking: true,
+    announce: true,
+    label: "Keine Berechtigung"
+  },
+  notFound: {
+    kind: "background",
+    tone: "neutral",
+    blocking: false,
+    announce: true,
+    label: "Nicht gefunden"
+  },
+  maintenance: {
+    kind: "background",
+    tone: "info",
+    blocking: true,
+    announce: true,
+    label: "Wartungsmodus"
+  },
+  stale: {
+    kind: "background",
+    tone: "caution",
+    blocking: false,
+    announce: true,
+    label: "Veraltete Daten"
+  },
+  syncing: {
+    kind: "background",
+    tone: "info",
+    blocking: false,
+    announce: true,
+    label: "Wird synchronisiert"
+  },
+  retrying: {
+    kind: "background",
+    tone: "info",
+    blocking: false,
+    announce: true,
+    label: "Neuer Versuch"
+  }
+};
+const NON_DESTRUCTIVE_STATES = ["refreshing", "syncing", "stale", "retrying"];
+function isNonDestructive(state) {
+  return NON_DESTRUCTIVE_STATES.includes(state);
+}
+function feedbackMeta(state) {
+  return FEEDBACK[state];
+}
+function feedbackAttr(state) {
+  return { "data-tea-state": state };
+}
+export {
+  FEEDBACK,
+  FEEDBACK_STATES,
+  NON_DESTRUCTIVE_STATES,
+  feedbackAttr,
+  feedbackMeta,
+  isNonDestructive
+};
+//# sourceMappingURL=feedback.js.map

package/dist/feedback.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/feedback.ts"],"sourcesContent":["import type { Tone } from \"@tea-ui/tokens\";\n\n/**\n * TEA UI — the feedback state model.\n *\n * Every asynchronous surface in a TEA product is in exactly one of these\n * states, and the states are named here so that two products handling the same\n * situation behave the same way. The audit found eight independent\n * \"Lade …\" loaders, ten empty states, nine error banners and four dialects of\n * each, with no shared naming and inconsistent live-region behaviour.\n *\n * The progression the model expects, and the reason for it:\n *\n *   action -> immediate acknowledgement -> progress -> result -> next action\n *\n * A user action must never be silent. It must never show a spinner over\n * content the user is already reading, either.\n */\n\nexport const FEEDBACK_STATES = [\n  \"idle\",\n  \"loading\",\n  \"refreshing\",\n  \"processing\",\n  \"success\",\n  \"warning\",\n  \"error\",\n  \"empty\",\n  \"disabled\",\n  \"offline\",\n  \"unauthorized\",\n  \"forbidden\",\n  \"notFound\",\n  \"maintenance\",\n  \"stale\",\n  \"syncing\",\n  \"retrying\",\n] as const;\n\nexport type FeedbackState = (typeof FEEDBACK_STATES)[number];\n\nexport type FeedbackKind = \"initial\" | \"background\" | \"blocking\";\n\nexport interface FeedbackMeta {\n  /**\n   * `initial`  — nothing to show yet, so a skeleton or a spinner replaces the\n   *              content. Used once, on first load.\n   * `background`— content exists and stays visible; the state is communicated\n   *              without replacing anything. Used for refresh, sync, save.\n   * `blocking`  — the user cannot proceed; a spinner or progress is required.\n   */\n  readonly kind: FeedbackKind;\n  /** The tone this state should render in, where a colour applies. */\n  readonly tone: Tone;\n  /**\n   * Whether this state is a problem the user must resolve, or merely\n   * information. Drives whether the surface offers a recovery action.\n   */\n  readonly blocking: boolean;\n  /** Whether a live region should announce a change into this state. */\n  readonly announce: boolean;\n  /** Default German noun phrase for a progress line, e.g. \"Wird geladen\". */\n  readonly label: string;\n}\n\nexport const FEEDBACK: Readonly<Record<FeedbackState, FeedbackMeta>> = {\n  idle: {\n    kind: \"background\",\n    tone: \"neutral\",\n    blocking: false,\n    announce: false,\n    label: \"Bereit\",\n  },\n  loading: {\n    kind: \"initial\",\n    tone: \"neutral\",\n    blocking: true,\n    announce: true,\n    label: \"Wird geladen\",\n  },\n  refreshing: {\n    kind: \"background\",\n    tone: \"neutral\",\n    blocking: false,\n    announce: true,\n    label: \"Wird aktualisiert\",\n  },\n  processing: {\n    kind: \"blocking\",\n    tone: \"info\",\n    blocking: true,\n    announce: true,\n    label: \"Wird verarbeitet\",\n  },\n  success: {\n    kind: \"background\",\n    tone: \"positive\",\n    blocking: false,\n    announce: true,\n    label: \"Erfolgreich\",\n  },\n  warning: {\n    kind: \"background\",\n    tone: \"caution\",\n    blocking: false,\n    announce: true,\n    label: \"Hinweis\",\n  },\n  error: {\n    kind: \"background\",\n    tone: \"critical\",\n    blocking: false,\n    announce: true,\n    label: \"Fehler\",\n  },\n  empty: {\n    kind: \"initial\",\n    tone: \"neutral\",\n    blocking: false,\n    announce: true,\n    label: \"Keine Einträge\",\n  },\n  disabled: {\n    kind: \"background\",\n    tone: \"neutral\",\n    blocking: false,\n    announce: false,\n    label: \"Nicht verfügbar\",\n  },\n  offline: {\n    kind: \"background\",\n    tone: \"caution\",\n    blocking: false,\n    announce: true,\n    label: \"Offline\",\n  },\n  unauthorized: {\n    kind: \"background\",\n    tone: \"caution\",\n    blocking: true,\n    announce: true,\n    label: \"Nicht angemeldet\",\n  },\n  forbidden: {\n    kind: \"background\",\n    tone: \"caution\",\n    blocking: true,\n    announce: true,\n    label: \"Keine Berechtigung\",\n  },\n  notFound: {\n    kind: \"background\",\n    tone: \"neutral\",\n    blocking: false,\n    announce: true,\n    label: \"Nicht gefunden\",\n  },\n  maintenance: {\n    kind: \"background\",\n    tone: \"info\",\n    blocking: true,\n    announce: true,\n    label: \"Wartungsmodus\",\n  },\n  stale: {\n    kind: \"background\",\n    tone: \"caution\",\n    blocking: false,\n    announce: true,\n    label: \"Veraltete Daten\",\n  },\n  syncing: {\n    kind: \"background\",\n    tone: \"info\",\n    blocking: false,\n    announce: true,\n    label: \"Wird synchronisiert\",\n  },\n  retrying: {\n    kind: \"background\",\n    tone: \"info\",\n    blocking: false,\n    announce: true,\n    label: \"Neuer Versuch\",\n  },\n};\n\n/**\n * States that must never replace content that is already on screen.\n *\n * The audit's clearest single defect: both source projects replace a whole\n * region with a centred spinner on every poll, so a five-second auto-refresh\n * flashes the UI away from content the user was reading. `refreshing`,\n * `syncing`, `stale` and `retrying` must be communicated as an overlay or a\n * quiet indicator over preserved content.\n */\nexport const NON_DESTRUCTIVE_STATES = [\"refreshing\", \"syncing\", \"stale\", \"retrying\"] as const;\n\nexport type NonDestructiveState = (typeof NON_DESTRUCTIVE_STATES)[number];\n\nexport function isNonDestructive(state: FeedbackState): state is NonDestructiveState {\n  return (NON_DESTRUCTIVE_STATES as readonly string[]).includes(state);\n}\n\nexport function feedbackMeta(state: FeedbackState): FeedbackMeta {\n  return FEEDBACK[state];\n}\n\n/**\n * Build a `data-tea-state` value for a surface, so a state is inspectable from\n * the DOM and assertable in a test rather than only visible.\n */\nexport function feedbackAttr(state: FeedbackState): { \"data-tea-state\": FeedbackState } {\n  return { \"data-tea-state\": state };\n}\n"],"mappings":"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","names":[]}

package/dist/forms.d.ts

@@ -0,0 +1,86 @@
+/**
+ * TEA UI — form standards.
+ *
+ * The audit found the same form field implemented five times in one project and
+ * three times in the other, with four of the five using a `<label>` that was
+ * never associated with its control — so most inputs in both products had no
+ * accessible name at all. These constants are what make a field correct by
+ * default rather than by remembering.
+ */
+type FieldControl = "text" | "email" | "password" | "search" | "number" | "date" | "time" | "url" | "tel" | "textarea" | "select" | "checkbox" | "radio" | "switch" | "slider" | "file" | "otp";
+/**
+ * When validation runs. "Too eager" and a form nobody can finish are the same
+ * defect, so the default is: validate on blur, re-validate on change *after*
+ * the field has been touched, and validate on submit. Never on every keystroke
+ * from the first character.
+ */
+declare const VALIDATION_TIMING: {
+    readonly onSubmit: "always";
+    readonly onBlur: true;
+    readonly onChangeAfterTouched: true;
+    readonly onChangeFromFirstKeystroke: false;
+};
+interface FormFieldRules {
+    /** The control type, which decides the association and keyboard contract. */
+    readonly control: FieldControl;
+    /** `htmlFor` is mandatory. A label without it does not name the control. */
+    readonly requiresLabelAssociation: true;
+    /** A description must be linked with `aria-describedby`, not merely placed nearby. */
+    readonly requiresDescribedBy: true;
+    /** An error must be linked with `aria-describedby` AND announced. */
+    readonly requiresErrorAnnouncement: true;
+    /** Icon-only controls require an accessible name. */
+    readonly requiresAccessibleName: true;
+    /** Required state must be conveyed programmatically, not only with an asterisk. */
+    readonly requiresRequiredState: true;
+}
+declare const FIELD_RULES: Readonly<Record<FieldControl, FormFieldRules>>;
+/**
+ * `autocomplete` tokens. Auto-fill is an accessibility feature, not a
+ * convenience: without it a user relying on a password manager has to type
+ * what the browser already knows.
+ */
+declare const AUTOCOMPLETE: {
+    readonly name: "name";
+    readonly givenName: "given-name";
+    readonly familyName: "family-name";
+    readonly email: "email";
+    readonly username: "username";
+    readonly currentPassword: "current-password";
+    readonly newPassword: "new-password";
+    readonly oneTimeCode: "one-time-code";
+    readonly organization: "organization";
+    readonly streetAddress: "street-address";
+    readonly postalCode: "postal-code";
+    readonly addressLevel1: "address-level1";
+    readonly addressLevel2: "address-level2";
+    readonly country: "country";
+    readonly tel: "tel";
+    readonly url: "url";
+    readonly newPasswordConfirm: "new-password";
+};
+/**
+ * The unsaved-changes standard. Losing typed input to a navigation is a data
+ * loss bug, so the guard is mandatory wherever a form can be abandoned — and
+ * it is a TEA UI pattern, not something each product re-implements.
+ */
+declare const UNSAVED_CHANGES: {
+    /** Wording of the guard. `du` register, per the content standard. */
+    readonly title: "Ungespeicherte Änderungen";
+    readonly detail: "Deine Änderungen wurden noch nicht gespeichert. Wenn du die Seite verlässt, gehen sie verloren.";
+    readonly confirmLabel: "Verwerfen und verlassen";
+    readonly cancelLabel: "Weiter bearbeiten";
+    /** Saving before navigating is the better path, so it is offered first. */
+    readonly preferSave: true;
+};
+/** Paste is never blocked. Masking an input must not break paste. */
+declare const FORM_INTERACTION: {
+    readonly blockPaste: false;
+    readonly blockAutofill: false;
+    /** Multi-step forms must allow going back without losing input. */
+    readonly allowStepBack: true;
+    /** Validation must be correctable: a field the user cannot fix is a bug. */
+    readonly allowFixingErrors: true;
+};
+
+export { AUTOCOMPLETE, FIELD_RULES, FORM_INTERACTION, type FieldControl, type FormFieldRules, UNSAVED_CHANGES, VALIDATION_TIMING };