@ethlete/cli 3.0.0-next.24 → 3.0.0-next.25

package/src/lib/design/system/complete.d.ts

@@ -1,16 +1,28 @@
 import { chromiumOf } from '../browser';
 import { DesignConfig } from '../paths';
-import { ResolvedProduct } from './resolve-product';
+import { Browser } from '../thumb';
+import { ResolvedPart, ResolvedProduct } from './resolve-product';
+import { SketchVariant, SystemModules } from './system-modules';
+import { ListedException } from './exceptions';
+import { InventoryState } from './inventory-approval';
 /** One requirement of a part that `design complete` finds without evidence. `target` is `<part>[.<control>[.<requirement>]]`. */
 export type CompletenessGap = {
     code: string;
     target: string;
     detail: string;
 };
+/** A box in the pixels of a drawn frame, as its `/__design/shot` picture shows it. */
+export type FrameBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
 /**
  * An element of a drawn frame that looks interactive. `control` is a native control, an interactive role or a known
  * SDK control; `unclassified` has a pointer cursor or a matched `:hover` rule and sits in no control. `marked` is the
- * `data-et-control` that declares it, `within` every `data-et-control` around it, nearest first.
+ * `data-et-control` that declares it, `within` every `data-et-control` around it, nearest first. `owner` is the
+ * embedded part whose `data-et-part` root draws it, or `null` for the frame's own part.
  */
 export type FoundControl = {
     kind: 'control' | 'unclassified';
@@ -18,6 +30,33 @@ export type FoundControl = {
     path: string;
     marked: string | null;
     within: string[];
+    owner?: string | null;
+    box?: FrameBox | null;
+};
+/** A rule of the part's own stylesheet that sets `properties` on `path`, an element the embedded part `owner` draws. */
+export type FoundOverride = {
+    owner: string;
+    selector: string;
+    path: string;
+    properties: string[];
+};
+/** A forced interaction on a drawn element: whether its box differs from rest, and which colours change in one frame. */
+export type SeenForce = {
+    interaction: string;
+    differs: boolean;
+    still?: string[];
+};
+/**
+ * An option or menu item inside a drawn surface. `selected` is its ARIA selected, checked, pressed or current
+ * state, `look` its computed colours, so two options can be told apart without their text. `named` is set when an
+ * `aria-activedescendant` in the frame names its id, `keyboard` when it carries `data-active-source="keyboard"`.
+ */
+export type SeenOption = {
+    selected: boolean;
+    look: string;
+    forced: SeenForce[];
+    named?: boolean;
+    keyboard?: boolean;
 };
 /** What one drawn frame of a state shows of the controls and surfaces its markup marks. */
 export type SeenFrame = {
@@ -25,20 +64,34 @@ export type SeenFrame = {
     interaction: string | null;
     controls: {
         id: string;
-        forced: {
-            interaction: string;
-            differs: boolean;
-            still?: string[];
-        }[];
+        forced: SeenForce[];
+        selected?: boolean;
+        disabled?: boolean;
+        look?: string;
+        keyboard?: boolean;
+        box?: FrameBox | null;
     }[];
     surfaces: {
         id: string;
         shown: boolean;
+        options?: SeenOption[];
     }[];
     found?: FoundControl[];
+    overrides?: FoundOverride[];
+};
+export type DeclaredControl = {
+    kind: string;
+    input: string[];
+    part: string | null;
+    surfaces: Record<string, string>;
+    disabled: boolean;
 };
 /** The gaps of each part a control names in `part`, or why it could not be checked. */
 export type ReferencedParts = Record<string, CompletenessGap[] | string>;
+export declare const declaredControlsOf: (value: unknown) => Record<string, DeclaredControl> | null;
+/** Whether a discovered element is an undeclared or unclassified finding of the part, not owned or declared. */
+export declare const isFindingOf: (declared: Record<string, DeclaredControl>) => (found: FoundControl) => boolean;
+export declare const findingKeyOf: (found: FoundControl) => string;
 /**
  * The gaps of one part, from its `controls` declaration, its state names and what each drawn frame showed.
  * A part that is not `reviewed` (its files differ from its merged.json hash) has no reviewed evidence at all.
@@ -51,21 +104,66 @@ export declare const completenessGapsOf: (options: {
     reviewed: boolean;
     grid?: unknown;
     referenced?: ReferencedParts;
+    inventory?: InventoryState;
 }) => CompletenessGap[];
 export declare const completenessGapLineOf: (gap: CompletenessGap) => string;
+/** Where a rest frame of a part is drawn: its state at a preset, or at a width, as `/__design/shot` takes it. */
+export type FrameAddress = {
+    state: string;
+    preset: string | null;
+    width: number | null;
+};
+/**
+ * Draws every state of one part of the product, at rest and, unless `restOnly`, in each interaction it declares,
+ * once at its first preset or width, and answers what each frame showed, or why its module did not load as a string.
+ */
+export declare const seePart: (options: {
+    product: ResolvedProduct;
+    part: ResolvedPart;
+    system: SystemModules;
+    base: string;
+    load: (id: string) => Promise<unknown>;
+    draw: <T>(job: (browser: Browser) => Promise<T>) => Promise<T>;
+    restOnly?: boolean;
+    sketch?: SketchVariant | null;
+}) => Promise<string | {
+    definition: {
+        states?: unknown;
+        interactions?: unknown;
+        widths?: unknown;
+        controls?: unknown;
+        grid?: unknown;
+    } | undefined;
+    states: string[];
+    seen: SeenFrame[];
+    refused: string[];
+    addresses: FrameAddress[];
+    owner: ResolvedProduct | {
+        dir: string;
+        base: null;
+    };
+    hash: string;
+}>;
+/** The control ids a page draws at rest, the set its inventory approval holds. */
+export declare const inventoryIdsOf: (frames: SeenFrame[]) => string[];
 /**
  * Draws every state of one part, at rest and in each interaction it declares, once at its first preset or width,
- * and answers the gaps of its `controls` declaration, or why it could not draw. A part a control names in `part`
- * is checked the same way, and its gaps fail the control.
+ * and answers the gaps of its `controls` declaration, or why it could not draw. A part a control names in `part`,
+ * and an embedded part whose `data-et-part` root draws a control, is checked the same way, and its gaps fail it.
+ * A page fails until the user approves its control inventory in Studio. An exception the user approved in Studio
+ * drops the gap it names until the part changes; a pending one still fails. With `sketch`, every part is drawn as
+ * that variant draws it, and a part the variant changes is not merged yet, so it never fails as unreviewed.
  */
 export declare const completenessOf: (options: {
     target: string;
     config: DesignConfig;
     product: ResolvedProduct;
     part: string;
+    sketch?: SketchVariant | null;
     chromiumOf?: typeof chromiumOf;
 }) => Promise<{
     gaps: CompletenessGap[];
+    exceptions?: ListedException[];
 } | {
     unavailable: string;
 } | {