@selimssevgi/cube-design-angular 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selimssevgi/cube-design-angular",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "cube design in angular: the pieces anlat, mosaic and cubes share, starting with the isometric cube picture.",
   "keywords": [
     "angular",
@@ -15,7 +15,8 @@
   },
   "peerDependencies": {
     "@angular/common": "^22.2.0",
-    "@angular/core": "^22.2.0"
+    "@angular/core": "^22.2.0",
+    "@angular/router": "^22.2.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"

package/types/selimssevgi-cube-design-angular.d.ts

@@ -1,5 +1,8 @@
 import * as i0 from "@angular/core";
-import { InjectionToken, TemplateRef } from "@angular/core";
+import { ErrorHandler, InjectionToken, Provider, TemplateRef } from "@angular/core";
+import { HttpInterceptorFn } from "@angular/common/http";
+import { ActivatedRouteSnapshot } from "@angular/router";
+import { Observable } from "rxjs";
 /**
  * drawing a cube of small cubes in isometric view: the left, right and top faces, each split into
  * n × n stickers. a sticker is coloured by a piece, or pale while nothing is known for it.
@@ -396,7 +399,7 @@ export declare class CubeCarry {
 /** the views a cube can be shown in, each drawn as its own shape. */
 export type CubeIconView = 'square' | 'one' | 'two' | 'three' | 'four' | 'grid-4x5' | 'grid-3x6';
 /** what a tile of a cube the app keeps is about (a context cube's parts and their choices). */
-export type CubeIconName = 'names' | 'name' | 'change' | 'move' | 'place' | 'whose' | 'library' | 'mine' | 'shown' | 'hidden' | 'view' | 'sort' | 'kept' | 'face' | 'added' | 'up' | 'down' | 'plus' | CubeIconView;
+export type CubeIconName = 'names' | 'name' | 'change' | 'move' | 'place' | 'whose' | 'library' | 'mine' | 'shown' | 'hidden' | 'view' | 'sort' | 'kept' | 'face' | 'added' | 'up' | 'down' | 'plus' | 'tell' | 'bug' | 'improvement' | 'idea' | 'not-known' | CubeIconView;
 /** every icon, in the order above. */
 export declare const CUBE_ICON_NAMES: readonly CubeIconName[];
 export interface CubeIconCell {
@@ -657,16 +660,24 @@ export declare function bringLevel(pieces: readonly CubeBring[], words?: BringWo
 }): ContextTile<CubeBring>[];
 /**
  * the parts a context cube can have. the seven are the ones cubes found, where (one piece in many
- * places, 0.3.0), and bring and order (bringing things in and my own order, 0.5.0); an app may add
- * its own, any string, and they come after the known ones.
+ * places, 0.3.0), bring and order (bringing things in and my own order, 0.5.0) and tell (telling us
+ * something about it, 0.6.0); an app may add its own, any string, and they come after the known
+ * ones, before tell.
  */
-export type ContextPartKey = 'names' | 'change' | 'bring' | 'view' | 'sort' | 'order' | 'move' | 'where' | 'whose' | 'hide' | (string & {});
+export type ContextPartKey = 'names' | 'change' | 'bring' | 'view' | 'sort' | 'order' | 'move' | 'where' | 'whose' | 'hide' | 'tell' | (string & {});
 /**
  * cubes' rows: how it is called (names, change, and bring things into it), how it is shown (view,
- * sort, my own order), what i do with it (move, where, whose, hide).
+ * sort, my own order), what i do with it (move, where, whose, hide), and last what i tell about it
+ * (tell; selim's decision of 4 november 2026: "tell us" is the last part of every context cube,
+ * after hide).
  */
 export declare const CONTEXT_PART_ORDER: readonly ContextPartKey[];
-/** the parts in their rows; parts an app added come last, in the order it gave them. twice is once. */
+/** the parts that stay last, after the parts an app added: tell. */
+export declare const CONTEXT_LAST_PARTS: readonly ContextPartKey[];
+/**
+ * the parts in their rows; parts an app added come after the known ones, in the order it gave
+ * them, and tell stays last. twice is once.
+ */
 export declare function orderParts(parts: readonly ContextPartKey[]): ContextPartKey[];
 /** one tile of a level. its title and line always come from the app. */
 export interface ContextTile<D = unknown> {
@@ -760,6 +771,18 @@ export interface ContextWords {
   inUse?: string;
   /** where's title and line for each place (`whereLevel`); the place's name and no line without. */
   where?: WhereWords;
+  /**
+   * tell's four pieces (`tellLevel`): something broke, make it better, an idea, and not known yet
+   * (the person says it without choosing). an app without them shows tell with empty titles.
+   */
+  tell?: TellWords;
+}
+/** the words of tell's level, one for each kind of report and one for not known yet. */
+export interface TellWords {
+  bug: ContextWord;
+  improvement: ContextWord;
+  idea: ContextWord;
+  notKnown: ContextWord;
 }
 /** the app's source of context cubes. */
 export declare const CONTEXT_CUBE_SOURCE: InjectionToken<ContextCubeSource<any>>;
@@ -779,6 +802,46 @@ export interface PartNow {
 export declare const PART_ICONS: Partial<Record<ContextPartKey, string>>;
 /** the top of a context cube: its parts in rows, each with its word and, when given, what it holds now. */
 export declare function partsLevel(parts: readonly ContextPartKey[], words: ContextWords, now?: Partial<Record<ContextPartKey, PartNow>>): ContextTile<ContextPartKey>[];
+/** what a report is about. a report may also be not known yet (null): the person did not say. */
+export type ReportKind = 'bug' | 'improvement' | 'idea';
+/** every kind, in the order a sheet offers them. */
+export declare const REPORT_KINDS: readonly ReportKind[];
+/** when and from what the app was built, as its `gen-build-info.mjs` writes it. */
+export interface ReportBuild {
+  commitShort?: string | null;
+  branch?: string | null;
+  builtAt?: string | null;
+}
+/** what the app tells the kit about itself, through `REPORT_APP`. */
+export interface ReportApp {
+  /** the app's id, sent as `app`: `cubes`, `anlat`; mosaic's sub-apps through `appOf`. */
+  id: string;
+  /** the backend's address, without `/feedback` (each app's `environment.apiBaseUrl`). */
+  apiBaseUrl: string;
+  /** the build, for the technical lines. */
+  build?: ReportBuild | null;
+  /**
+   * the app id for an address, when one app hosts several (mosaic: its sub-app, else `general`);
+   * `id` when not given or when it answers null.
+   */
+  appOf?: (url: string) => string | null;
+  /**
+   * the app's own words for a screen, from its route pattern and address: an id or the app's own
+   * name for that place, never a heading or a name a person wrote. the route pattern when not given.
+   */
+  screenOf?: (route: string, url: string) => string | null;
+  /** `prod`, `dev` or `local`; worked out from the address when not given (`environmentOf`). */
+  environment?: () => string;
+  /** where the unsent text is kept on the phone; `<id>.report.draft` when not given. */
+  draftKey?: string;
+  /**
+   * whether this account may read `GET /feedback` (only the owner may), which the never-twice
+   * check needs after a failed save. false when not given.
+   */
+  readsReports?: () => boolean;
+}
+/** the app's `ReportApp`. */
+export declare const REPORT_APP: InjectionToken<ReportApp>;
 /** what a names tile holds: a name, or the plus. */
 export type NamesData = {
   name: ContextName;
@@ -862,6 +925,15 @@ export interface AddWay {
  * it is only the plus, and then the app opens the name at once instead of this level).
  */
 export declare function addLevel(ways: readonly AddWay[]): ContextTile<AddWay>[];
+/** what a tell tile holds: the kind of report, or null for not known yet. */
+export type TellData = ReportKind | null;
+/**
+ * tell ("tell us"): what i want to tell about the held piece, as four pieces: something broke, make
+ * it better, an idea, and not known yet (said without choosing; empty is the point). a tap ends the
+ * journey: the app opens its own sheet with the kind in `data` and the held piece's key, and sends
+ * it with `ReportClient`. no kind is in use: nothing has been told yet.
+ */
+export declare function tellLevel(words: ContextWords): ContextTile<TellData>[];
 /** how close a square's places are: from one big tile (0) to only its icon or small cube (4). */
 export type SquareLevel = 0 | 1 | 2 | 3 | 4;
 /** cubes' steps (`levelFor`), by a cell's side in px: a tile says less as the square fills. */
@@ -1362,4 +1434,197 @@ export declare class CubeLoading {
       "isSignal": true;
     };
   }, {}, never, ["*", "[cubeLoadingRetry]"], true, never>;
+}
+/** how many incidents are kept, and for how long (mosaic's numbers). */
+export declare const REPORT_INCIDENTS_KEPT = 5;
+export declare const REPORT_INCIDENTS_MS: number;
+/** a request's address with its host, query and fragment taken off: `/kitchen/ingredients/abc`. */
+export declare function scrubbedPath(url: string): string;
+/** an error as one line: its name and the start of its message. */
+export declare function errorLine(error: unknown): string;
+/**
+ * remembers the last few errors and failed requests of the last ten minutes, so a bug report can
+ * carry them. nothing is sent anywhere unless a report is saved with them. a failed request keeps
+ * its method, path and status, never its query or body; an error its name and the first 300
+ * characters of its message.
+ */
+export declare class ReportDiagnostics {
+  private incidents;
+  constructor();
+  recordError(error: unknown): void;
+  recordFailedRequest(method: string, url: string, status: number): void;
+  /** the incidents of the last ten minutes, oldest first. */
+  recent(now?: number): string[];
+  private add;
+  static ɵfac: i0.ɵɵFactoryDeclaration<ReportDiagnostics, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/** angular's error handler, which also remembers the error for a bug report. */
+export declare class ReportErrorHandler extends ErrorHandler {
+  private readonly diagnostics;
+  handleError(error: unknown): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<ReportErrorHandler, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/** remembers failed requests, except the report calls themselves (`/feedback`). */
+export declare const reportInterceptor: HttpInterceptorFn;
+/**
+ * the error handler, for the app's providers. the interceptor goes in its own
+ * `provideHttpClient(withInterceptors([..., reportInterceptor]))`.
+ */
+export declare function provideReportDiagnostics(): Provider[];
+/**
+ * where a report was made, gathered without asking. only what the app and the address say: the
+ * route pattern, the page's path, the app's own words for the screen and the held piece's key;
+ * never a heading, a tile's name or anything a person wrote, never a query or a fragment (a
+ * personal link's token lives in one).
+ */
+export interface ReportContext {
+  /** the app id sent as `app`. */
+  app: string;
+  /** the app's own words for the screen (`ReportApp.screenOf`), else the route pattern. */
+  screen: string;
+  /** the route pattern: `kitchen/ingredient-catalog/:id`. */
+  route: string;
+  /** the page's address (its base href too) without its query and fragment. */
+  pageUrl: string;
+  /** `prod`, `dev` or `local`. */
+  environment: string;
+  /** the key of the piece held, when the report came from a context cube; else null. */
+  held: string | null;
+}
+/** the route pattern of the active route: `kitchen/ingredient-catalog/:id`. */
+export declare function routePattern(root: ActivatedRouteSnapshot | null): string;
+/** `local` on localhost, `dev` on a `dev--` or `dev.` host, else `prod`. */
+export declare function environmentOf(host: string): string;
+/** the context, from what the app says and where the phone is. pure. */
+export declare function contextOf(app: ReportApp, at: {
+  url: string;
+  route: string;
+  origin: string;
+  host: string;
+  pathname?: string;
+}, held?: string | null): ReportContext;
+/**
+ * where a report is being made now, from `REPORT_APP` and the router; call it in an injection
+ * context (a constructor, a field, `runInInjectionContext`), or use `ReportClient.context`.
+ */
+export declare function reportContext(opts?: {
+  held?: string | null;
+}): ReportContext;
+/**
+ * the technical lines a report carries, in the context note: the piece held, the build, the
+ * screen's size and browser, and (for a bug) the last incidents.
+ */
+export declare function technicalLines(input: {
+  held?: string | null;
+  build?: ReportBuild | null;
+  size?: {
+    width: number;
+    height: number;
+  } | null;
+  agent?: string | null;
+  incidents?: readonly string[];
+}): string[];
+/** how long after a failed save the same text found among the reports counts as that save. */
+export declare const JUST_SAVED_MINUTES = 15;
+/** what the never-twice check reads of a saved report. */
+export interface SavedReportLike {
+  detail?: string | null;
+  /** when it was saved, as the backend sends it. */
+  reported?: string | null;
+}
+/**
+ * the report a failed save may have made after all: a save can reach the backend while its answer
+ * is lost (a redeploy, a dropped connection), and saving again would file it twice. the first
+ * report with the same text saved in the last 15 minutes, or undefined. from mosaic's
+ * `findJustSaved`.
+ */
+export declare function findJustSaved<R extends SavedReportLike>(reports: readonly R[], detail: string, now?: Date): R | undefined;
+/**
+ * the unsent text, kept on this phone under the app's key, so a sheet closed by mistake opens
+ * with it again. a convenience: without storage it is simply not kept.
+ */
+export declare class ReportDraft {
+  readonly key: string;
+  constructor(key: string);
+  read(): string;
+  /** keeps the text; an empty one (spaces too) forgets it. */
+  write(text: string): void;
+  clear(): void;
+}
+/** what the person said. */
+export interface ReportInput {
+  /** bug, improvement, idea, or null: not known yet. */
+  kind: ReportKind | null;
+  /** their words, as they wrote or said them. */
+  text: string;
+  /** the held piece's key, when it came from a context cube's "tell us". */
+  held?: string | null;
+  /** whether the last errors and failed requests go with it; a bug's do by default. */
+  withIncidents?: boolean;
+}
+/** the body of `POST /feedback` (lang-app-be `NewFeedbackRequest`). */
+export interface ReportRequest {
+  /** left out when not known yet. */
+  type?: ReportKind;
+  detail: string;
+  app: string;
+  screen: string;
+  pageUrl: string;
+  route: string;
+  environment: string;
+  /** the technical lines, one a line. */
+  context: string;
+}
+/** what the backend answers for a saved report; the app reads what it needs (the id for undo). */
+export interface SavedReport extends SavedReportLike {
+  id: string;
+  number?: number | null;
+  [field: string]: unknown;
+}
+/**
+ * why the backend refused a report, in its own plain words, to show as it came (a 400: more than 20
+ * reports in a day, a text too long, an app the account does not use); null for any other failure,
+ * which is worth trying again.
+ */
+export declare function reportRefusal(error: unknown): string | null;
+/** the body a report is sent with, from what was said and where. pure. */
+export declare function reportRequest(input: ReportInput, ctx: ReportContext, technical: readonly string[]): ReportRequest;
+/**
+ * sends a report to the backend's `POST /feedback`, the one door every account may use, and takes
+ * it back (`undo`, the reporter's own within 15 minutes). it never reads the reports, except for
+ * the never-twice check when `REPORT_APP.readsReports` says this account may (the owner).
+ */
+export declare class ReportClient {
+  private readonly http;
+  private readonly app;
+  private readonly diagnostics;
+  private readonly injector;
+  private readonly url;
+  /** the draft, under the app's key. */
+  readonly draft: ReportDraft;
+  /** where a report is being made now. */
+  context(held?: string | null): ReportContext;
+  /** the last errors and failed requests, for "what goes with it". */
+  incidents(): string[];
+  /** the body that `capture` would send now, for a sheet that shows what goes with it. */
+  request(input: ReportInput, ctx?: ReportContext): ReportRequest;
+  /**
+   * sends it; the draft is forgotten once the backend has it. the same words sent again within 15
+   * minutes come back as the same report (the backend's never twice). a refusal's words are
+   * `reportRefusal(error)`.
+   */
+  capture(input: ReportInput, ctx?: ReportContext): Observable<SavedReport>;
+  /**
+   * after a failed save: the report it may have made after all, or null, so the sheet can say it was
+   * told instead of sending again. only an account that may read the reports can know
+   * (`readsReports`); for anyone else it is null. sending again is safe for everyone: the backend
+   * answers the same words from the same reporter within 15 minutes with the report it already has.
+   */
+  justSaved(text: string): Observable<SavedReport | null>;
+  /** takes a report back: the undo right after saving. */
+  undo(id: string): Observable<void>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<ReportClient, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }