@mark1russell7/site-pages 0.2.0 → 0.2.1

package/README.md

@@ -413,6 +413,41 @@ The file sets no look for the content. Buttons, cards, code and tables stay in t
 
 A site with its own look does not import `shell.css`. It uses only the plugin and `showBuild`, or nothing from this section.
 
+## The response explorer
+
+The entry `@mark1russell7/site-pages/explorer` shows a measured response in the browser. A visitor chooses a measure, varies one or two dimensions, and holds or facets the others. The view shows the measured points, the fitted curve or surface, and its held-out error in plain words. The record has the format `response-records/1` of `@mark1russell7/rigor-statistics`.
+
+```ts
+import { mountExplorer } from "@mark1russell7/site-pages/explorer";
+import "@mark1russell7/site-pages/explorer.css";
+import record from "./record.json";
+
+mountExplorer(document.getElementById("chart")!, record, { initial: { x: "boxes" } });
+```
+
+| Argument | Use |
+| --- | --- |
+| `host` | The element for the explorer |
+| `recordJson` | The record, as JSON text or as parsed data |
+| `options.initial` | The first measure, axes, panels and held values. The explorer corrects a value that does not apply. |
+| `options.budgetMs` | The time limit of one surface, in milliseconds. The default is 50. |
+| `options.now` | The clock, for tests |
+
+`mountExplorer` gives a handle: `state()` reads the current state, and `destroy()` removes the view.
+
+The explorer obeys these rules:
+
+- **A bad record.** The explorer reads a record only through `parseResponseRecord`. It shows each fault with its path, and it does not throw.
+- **Conditions.** A dimension with `when` has its parent at a level inside `when`. The controls disable a choice that a view refuses, and they tell why.
+- **The band.** The band shows `low` to `high`. It fades with the distance from the nearest measured point.
+- **The time of a surface.** The field `nearest` reads each point at each place. So `planSteps` bounds the grid from the point count before the call. After a surface that passes the budget, `nextStepsCap` makes the next grid smaller.
+- **A table model.** A table model has no smooth surface, so the view shows cells.
+- **No model.** A measure with no valid model shows only the points, and the view says so.
+
+The view draws SVG, and it needs no framework, no font and no script from another server. It reads the tokens of a site when they exist, and it has its own colors for the light and the dark scheme. The keyboard reaches each control, and the arrow keys move a cursor on a chart. "Show the numbers" opens a table of the values.
+
+The entry also exports the pure core, for a site with its own view. These functions are `settle`, `viewOf`, `axisChoices`, `facetChoices`, `holdControls`, `setMeasure`, `setAxis`, `setFacet`, `setHold`, `planSteps`, `nextStepsCap`, `openRecord` and `numberTable`.
+
 ## A GitHub Pages workflow
 
 This workflow builds the site, adds the two pages, and deploys. It also starts every 3 hours, so the status page stays current without a push. A scheduled run builds the newest commit of `main` that passed CI.

package/build/explorer/index.d.ts

@@ -0,0 +1,212 @@
+import { ParsedResponseRecord, ResponseHeldOutError, ResponseMeasure, ResponseRecord, ResponseSlice, ResponseSurface, ResponseValue } from "@mark1russell7/rigor-statistics";
+/** The largest number of values on a continuous axis. It is the default of `ResponseViewOptions.steps`. */
+export declare const MAX_STEPS = 33;
+/** The smallest number of values on a continuous axis. A smaller grid shows too little of the response. */
+export declare const MIN_STEPS = 5;
+/**
+ * The largest number of point reads of one view. The field `nearest` of each place reads each point, so the cost of a
+ * view is its number of places times the number of points. This number is a first bound, not a measured time.
+ * `SURFACE_BUDGET_MS` corrects the grid when a surface takes too long on the device.
+ */
+export declare const READ_BUDGET = 4e5;
+/** The time of one surface in milliseconds. A longer surface gives a smaller grid for the next surface. */
+export declare const SURFACE_BUDGET_MS = 50;
+/** The largest number of panels of one view. */
+export declare const MAX_PANELS = 8;
+/** The choices of a visitor. */
+interface ExplorerState {
+  /** The id of the measure. */
+  readonly measure: string;
+  /** The id of the dimension of the horizontal axis. */
+  readonly x: string;
+  /** The id of the dimension of the vertical axis of a surface. The value `null` gives a curve. */
+  readonly y: string | null;
+  /** The id of the dimension with one panel for each of its values. The value `null` gives one panel. */
+  readonly facet: string | null;
+  /** The held value of each dimension. A dimension on an axis keeps its value for a later view. */
+  readonly hold: Readonly<Record<string, ResponseValue>>;
+}
+/** The two axes of a view. */
+type AxisSlot = "x" | "y";
+/** A dimension that a control offers. */
+interface DimensionChoice {
+  readonly id: string;
+  readonly label: string;
+  readonly disabled: boolean;
+  /** The reason of a disabled choice. A good choice has an empty string. */
+  readonly reason: string;
+}
+/** A value that a hold control offers. */
+interface HoldOption {
+  readonly value: ResponseValue;
+  readonly text: string;
+  readonly disabled: boolean;
+  readonly reason: string;
+}
+/** The control of one held dimension. */
+interface HoldControl {
+  readonly id: string;
+  readonly label: string;
+  /** The value `levels` gives one button for each level. The value `stops` gives a slider over the measured values. */
+  readonly kind: "levels" | "stops";
+  /** The value `false` means that the dimension has no value at the held level of its parent. */
+  readonly applies: boolean;
+  /** The condition of the dimension, as text. A dimension with no condition has an empty string. */
+  readonly note: string;
+  readonly options: readonly HoldOption[];
+  readonly value: ResponseValue;
+}
+/** One axis of a chart. A number axis has a linear or log place. A level axis has one equal band for each level. */
+interface AxisSpec {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: "number" | "levels";
+  readonly log: boolean;
+  /** The two ends of a number axis. */
+  readonly range: readonly [number, number];
+  /** The levels of a level axis. */
+  readonly levels: readonly ResponseValue[];
+}
+/** The fields of each kind of panel. */
+interface PanelBase {
+  /** The name of the panel in a view with panels. The only panel of a view has an empty string. */
+  readonly title: string;
+  /** The value of the facet dimension in this panel. */
+  readonly level: ResponseValue | null;
+}
+/** A fitted curve with its band and the measured points. */
+interface CurvePanel extends PanelBase {
+  readonly kind: "curve";
+  readonly slice: ResponseSlice;
+}
+/** A fitted surface. With `cells`, the view shows separate cells with their values, not a smooth surface. */
+interface SurfacePanel extends PanelBase {
+  readonly kind: "surface";
+  readonly cells: boolean;
+  readonly surface: ResponseSurface;
+}
+/** A measured point of a panel with no model. */
+interface PlainPoint {
+  readonly id: string;
+  /** The value of each varied dimension. */
+  readonly at: readonly ResponseValue[];
+  readonly value: number;
+}
+/** The measured points of a measure with no model. */
+interface PointsPanel extends PanelBase {
+  readonly kind: "points";
+  readonly points: readonly PlainPoint[];
+}
+/** One panel of a view. */
+type ExplorerPanel = CurvePanel | SurfacePanel | PointsPanel;
+/** The data of one view. */
+interface ExplorerView {
+  readonly measure: ResponseMeasure;
+  readonly x: AxisSpec;
+  readonly y: AxisSpec | null;
+  readonly panels: readonly ExplorerPanel[];
+  /** The value `true` gives a log value axis. */
+  readonly log: boolean;
+  /** The held-out error. A measure with no model has none. */
+  readonly error: ResponseHeldOutError | null;
+  /** The held-out error in plain words. */
+  readonly errorText: string;
+  /** The kind of the model in plain words. */
+  readonly modelText: string;
+  /** The size of the grid of a surface in plain words. A curve has an empty string. */
+  readonly gridText: string;
+  /** The text of a request that the record refused. A good view has an empty string. */
+  readonly problem: string;
+  /** The number of values on a continuous axis of this view. */
+  readonly steps: number;
+  /** The time of this view in milliseconds. */
+  readonly elapsedMs: number;
+  /** The largest number of steps of the next view. */
+  readonly nextCap: number;
+}
+/** The inputs of `viewOf`. */
+interface ViewOptions {
+  /** The largest number of steps. The value of `nextCap` of the last view goes here. */
+  readonly stepsCap?: number;
+  /** The time of a surface in milliseconds. The default is `SURFACE_BUDGET_MS`. */
+  readonly budgetMs?: number;
+  /** The clock in milliseconds. The default gives 0, so a view with no clock does not drop its grid. */
+  readonly now?: () => number;
+}
+/** A rectangle of a table of numbers. */
+interface NumberTable {
+  readonly columns: readonly string[];
+  readonly rows: readonly (readonly string[])[];
+}
+/**
+ * This function reads a record from JSON text or from parsed data. It does not throw: bad data gives faults with
+ * their paths.
+ */
+export declare function openRecord(value: unknown): ParsedResponseRecord;
+/**
+ * This function gives the nearest good state for a wanted state. Each unknown or missing field takes its usual value.
+ * A parent moves to a level that a varied conditional dimension needs. A combination that a view refuses loses its
+ * second axis or its panels.
+ */
+export declare function settle(record: ResponseRecord, wanted?: Partial<ExplorerState>): ExplorerState;
+/** This function gives each dimension as a choice for an axis. A disabled choice tells its reason. */
+export declare function axisChoices(record: ResponseRecord, state: ExplorerState, slot: AxisSlot): readonly DimensionChoice[];
+/** This function gives each dimension as a choice for panels. A disabled choice tells its reason. */
+export declare function facetChoices(record: ResponseRecord, state: ExplorerState): readonly DimensionChoice[];
+/** This function gives the control of each held dimension. A dimension on an axis or in panels has no control. */
+export declare function holdControls(record: ResponseRecord, state: ExplorerState): readonly HoldControl[];
+/** This function gives the state with a new measure. */
+export declare function setMeasure(record: ResponseRecord, state: ExplorerState, measure: string): ExplorerState;
+/** This function gives the state with a new axis. It does not take a disabled choice. The value `null` removes the y axis. */
+export declare function setAxis(record: ResponseRecord, state: ExplorerState, slot: AxisSlot, id: string | null): ExplorerState;
+/** This function gives the state with new panels. It does not take a disabled choice. The value `null` gives one panel. */
+export declare function setFacet(record: ResponseRecord, state: ExplorerState, id: string | null): ExplorerState;
+/** This function gives the state with a new held value. It does not take a disabled value. */
+export declare function setHold(record: ResponseRecord, state: ExplorerState, id: string, value: ResponseValue): ExplorerState;
+/**
+ * This function gives the number of steps of a view, from the number of points, before the call. The field `nearest`
+ * reads each point at each place, so the number of places comes from `READ_BUDGET`.
+ *
+ * @param points - The number of points of the record.
+ * @param panels - The number of panels of the view.
+ * @param continuous - The number of continuous axes of the view.
+ * @param levels - The number of levels of a level axis of a surface, or 1.
+ * @param cap - The largest result.
+ */
+export declare function planSteps(points: number, panels: number, continuous: number, levels: number, cap?: number): number;
+/** This function gives the cap of the next view: a smaller grid when this surface took more than the budget. */
+export declare function nextStepsCap(steps: number, elapsedMs: number, budgetMs: number): number;
+/**
+ * This function gives the data of a view. It does not throw. A request that the record refuses gives the text in
+ * `problem`, and no panels. A measure with no model gives only the measured points, and a table model gives cells.
+ */
+export declare function viewOf(record: ResponseRecord, state: ExplorerState, options?: ViewOptions): ExplorerView;
+/** This function gives the numbers of a panel: each place of a curve, or the measured points of a surface. */
+export declare function numberTable(view: ExplorerView, panel: ExplorerPanel): NumberTable;
+/** The options of `mountExplorer`. */
+interface ExplorerOptions {
+  /** The first state. The explorer corrects a state that a record refuses. */
+  readonly initial?: Partial<ExplorerState>;
+  /** The time of a surface in milliseconds. The default is `SURFACE_BUDGET_MS`. */
+  readonly budgetMs?: number;
+  /** The clock in milliseconds. The default is `performance.now`. */
+  readonly now?: () => number;
+}
+/** The result of `mountExplorer`. */
+interface ExplorerHandle {
+  /** This method gives the choices of the visitor. It gives `null` for a record with faults. */
+  state(): ExplorerState | null;
+  /** This method removes the explorer from its host. */
+  destroy(): void;
+}
+/**
+ * This function shows a record of the format `response-records/1` in a host element. It reads the record only with
+ * `parseResponseRecord`. A bad record shows its faults with their paths, and the function does not throw.
+ *
+ * @param host - The element of the explorer. The function replaces its children.
+ * @param recordJson - The record as JSON text, or as parsed data.
+ * @param options - The first state, the time of a surface and the clock.
+ */
+export declare function mountExplorer(host: HTMLElement, recordJson: unknown, options?: ExplorerOptions): ExplorerHandle;
+export type { AxisSlot, AxisSpec, CurvePanel, DimensionChoice, ExplorerHandle, ExplorerOptions, ExplorerPanel, ExplorerState, ExplorerView, HoldControl, HoldOption, NumberTable, PlainPoint, PointsPanel, SurfacePanel, ViewOptions };
+//# sourceMappingURL=index.d.ts.map

package/build/explorer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/explorer/model.ts","../../src/explorer/view.ts"],"mappings":";;qBAgCa;;qBAEA;;;;;;qBAMA;;qBAEA;;qBAEA;;UASI;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA,MAAM,SAAS,eAAe;;;KAI7B;;UAGK;WACN;WACA;WACA;;WAEA;;;UAIM;WACN,OAAO;WACP;WACA;WACA;;;UAIM;WACN;WACA;;WAEA;;WAEA;;WAEA;WACA,kBAAkB;WAClB,OAAO;;;UAID;WACN;WACA;WACA;WACA;;WAEA;;WAEA,iBAAiB;;;UAIlB;;WAEC;;WAEA,OAAO;;;UAID,mBAAmB;WACzB;WACA,OAAO;;;UAID,qBAAqB;WAC3B;WACA;WACA,SAAS;;;UAIH;WACN;;WAEA,aAAa;WACb;;;UAIM,oBAAoB;WAC1B;WACA,iBAAiB;;;KAIhB,gBAAgB,aAAa,eAAe;;UAGvC;WACN,SAAS;WACT,GAAG;WACH,GAAG;WACH,iBAAiB;;WAEjB;;WAEA,OAAO;;WAEP;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;UAIM;;WAEN;;WAEA;;WAEA;;;UAIM;WACN;WACA;;;;;;wBAcK,WAAW,iBAAiB;;;;;;wBA0K5B,OAAO,QAAQ,gBAAgB,SAAQ,QAAQ,iBAAsB;;wBAqBrE,YAAY,QAAQ,gBAAgB,OAAO,eAAe,MAAM,oBAAoB;;wBAQpF,aAAa,QAAQ,gBAAgB,OAAO,yBAAyB;;wBAQrE,aAAa,QAAQ,gBAAgB,OAAO,yBAAyB;;wBAmBrE,WAAW,QAAQ,gBAAgB,OAAO,eAAe,kBAAkB;;wBAK3E,QAAQ,QAAQ,gBAAgB,OAAO,eAAe,MAAM,UAAU,oBAAoB;;wBAO1F,SAAS,QAAQ,gBAAgB,OAAO,eAAe,oBAAoB;;wBAM3E,QAAQ,QAAQ,gBAAgB,OAAO,eAAe,YAAY,OAAO,gBAAgB;;;;;;;;;;;wBAiBzF,UAAU,gBAAgB,gBAAgB,oBAAoB,gBAAgB;;wBAO9E,aAAa,eAAe,mBAAmB;;;;;wBAuF/C,OAAO,QAAQ,gBAAgB,OAAO,eAAe,UAAS,cAAmB;;wBAmLjF,YAAY,MAAM,cAAc,OAAO,gBAAgB;;UC9qBtD;;WAEN,UAAU,QAAQ;;WAElB;;WAEA;;;UAIM;;EAEf,SAAS;;EAET;;;;;;;;;;wBAmZc,cAAc,MAAM,aAAa,qBAAqB,UAAS,kBAAuB"}