diff --git a/README.md b/README.md index f2cb894..e2d84fb 100644 --- a/README.md +++ b/README.md @@ -399,7 +399,7 @@ Application screens (`type: "desktop-app"`) are built from eight primitives on t #### Overlays -Six overlays draw screen states: an open menu, a comment popover, a confirm dialog, a toast. Put each in a state variant (`canvas_add_variant` with `menu-open`, `comment-open`, `confirm-delete` or `toast`); coverage lists those states and never demands them. Wherever an overlay sits in the tree, it renders in one layer after the content, so a pane never clips it and a sticky bar never covers it. `x` / `y` are offsets from the root's top-left, not from the parent. Layers are fixed by kind, with no z-index property: `popover` and `menu` 400, the modal's scrim 500, `modal` and `drawer` 510, `toast` 600, `tooltip` 800. `anchor` names the node that opens an overlay; it is never rendered (the overlay rules of a later release read it). Colours come from `$bg-surface`, `$border`, `$text-primary` and `$text-secondary`, depth from `$elevation.overlay`. +Six overlays draw screen states: an open menu, a comment popover, a confirm dialog, a toast. Put each in a state variant (`canvas_add_variant` with `menu-open`, `comment-open`, `confirm-delete` or `toast`); coverage lists those states and never demands them. Wherever an overlay sits in the tree, it renders in one layer after the content, so a pane never clips it and a sticky bar never covers it. `x` / `y` are offsets from the root's top-left, not from the parent. Layers are fixed by kind, with no z-index property: `popover` and `menu` 400, the modal's scrim 500, `modal` and `drawer` 510, `toast` 600, `tooltip` 800. `anchor` names the node that opens an overlay; it is never rendered, and `desktop-app-overlay` checks that it names something clickable. Colours come from `$bg-surface`, `$border`, `$text-primary` and `$text-secondary`, depth from `$elevation.overlay`. | Type | Key props | What it is | |---|---|---| @@ -414,7 +414,7 @@ Six overlays draw screen states: an open menu, a comment popover, a confirm dial I("document", { type: "modal", title: "Delete \"Checkout\"?", actions: [{ label: "Cancel" }, { label: "Delete", variant: "destructive" }] }) ``` -A modal and a drawer are panes of their own for `desktop-app-current` and `desktop-app-primary-count`; a modal's close button and actions and a toast's action are pointer targets. An undeclared canvas holding an overlay warns until it declares a type (`desktop-app-artboard`); web and mobile canvases may hold overlays freely. +A modal and a drawer are panes of their own for `desktop-app-current` and `desktop-app-primary-count`; a modal's close button and actions and a toast's action are pointer targets. An undeclared canvas holding an overlay warns until it declares a type (`desktop-app-artboard`); web and mobile canvases may hold overlays freely. On a desktop-app canvas `desktop-app-overlay` warns on a second modal, a tooltip with children, a long table or a sideways scroller inside a modal, an overlay that leaves the viewport, and a popover or menu under the scrim of a modal or a drawer with `scrim: true` (popovers and menus stack below it); a second toast, a danger toast and an anchor that names nothing clickable are infos. ### `find_nodes` @@ -926,6 +926,7 @@ Every result also carries a **`surface`** field: `{ type, device, source, rulesO | `desktop-app-row-rhythm` | consistency | warning / info | Desktop-app only, on detected tables: a header row more than 1px off the one-line body rows warns; a body row off its siblings is an info (title-over-subtitle rows compared only with each other); detailed mode adds a cell off its column's left edge as an info. Fast mode reads authored heights only. | | `desktop-app-truncation` | usability | warning / info | Desktop-app only: a truncating column header warns; a hand-built ellipsis with no `title` is an info. Detailed mode: a `tabs` node whose every label is cut warns, and an ellipsis leaving fewer than four characters is an info. | | `desktop-app-primary-count` | structure | info | Desktop-app only: two or more primary `button`s in one pane (any variant but `secondary`, `ghost` or `destructive` renders filled, so it counts; no variant included). A modal's `actions` with `variant: "primary"` count in the modal's pane. Primaries inside three or more same-shaped sibling frames, such as a card grid, don't count. | +| `desktop-app-overlay` | usability | warning / info | Desktop-app only: warns on a second `modal`; a `tooltip` with children; inside a modal, a table of more than ten body rows or a frame with `overflow: "auto"` that renders wider than the modal or scrolls sideways; an overlay that leaves the viewport (the root's size, else the window's; a modal wider than the viewport less 32px in both modes, in fast mode a popover or menu with numeric `x`/`y`/`width`/`height` and a placed modal's sides, in detailed mode every rendered overlay); a `popover` or `menu` on a canvas with a modal or a scrimmed drawer, which renders under the scrim. Infos: a second `toast`, a `danger` toast, an `anchor` naming no node or nothing clickable. | Repeated findings fold in this result: three or more warnings or infos with the same severity, category, rule (or tell) and theme come back as one entry when they also share their message — on its shape for members that carry a fix (each fix op holds its node's specifics), word for word apart from quoted node text for members without one. The entry keeps the first one's message and adds `nodeIds` (distinct), `count` and, when they had fixes, `fixes: [{ nodeId, op }]`. Errors never fold, and `canvas_autofix` works from the unfolded list. diff --git a/VISION.md b/VISION.md index c8399bb..63764a6 100644 --- a/VISION.md +++ b/VISION.md @@ -570,7 +570,7 @@ Run on its own viewer (2026-11-08), framesmith scored every page's usability 100 - [x] Slice D — panes: resolution for any number of types, six desktop-app realisations (workbench, list-detail, editor-inspector, browser, dashboard, settings) and the `data-table-app` / `skeleton-table-app` components under the pattern gate, scrolling panes that stress reads as scrolling, and stress runs that triple app rows and card grids - [ ] Follow-up — the web scaffolds' tint tokens (`success-tint` and the rest) are seeded dark and survive a later light `apply_preset`, as `accent-tint` did before Phase 31 slice D stopped seeding it; derive them from the applied palette instead - [x] Slice E — overlays: one overlay layer at the root with a fixed ladder, and the `tooltip`, `popover`, `menu`, `modal`, `toast` and `drawer` primitives, with overlay screen states as variants -- [ ] Slice F — overlay rules: one modal, text-only tooltips, no large tables in modals, overlays inside the viewport, and advisories on stacked toasts and error toasts +- [x] Slice F — overlay rules: one modal, text-only tooltips, no large tables in modals, overlays inside the viewport, nothing under a scrim, and advisories on stacked toasts, error toasts and dangling anchors - [ ] Slice G — element states: hover, focus, pressed and disabled as a primitive property, drawn from state tokens - [ ] Slice H — state checks: focus rings, active indicators, disabled renders and control boundaries checked analytically on every interactive primitive, without being drawn - [ ] Slice I — the acceptance re-run: the viewer's gallery, detail with inspector and archive rebuilt as canvases, with the comment popover and delete-confirm states diff --git a/docs/GUIDELINES.md b/docs/GUIDELINES.md index 0cc2fbb..b068240 100644 --- a/docs/GUIDELINES.md +++ b/docs/GUIDELINES.md @@ -95,6 +95,13 @@ Two terms the rules share. A **pane** is a frame that scrolls on its own (`overf - **`desktop-app-row-rhythm`** (consistency), on detected tables. A header row (its content is text, plus icons and controls such as a select-all checkbox; a first row holding a control counts only when its text is styled apart from the next row's, since a row-select data row looks the same) more than 1px taller or shorter than the one-line body rows **warns**, as Carbon sets them equal. A body row more than 1px off its siblings is an **info**; rows with a title over a subtitle are compared only with each other. Detailed mode adds a cell whose left edge is more than 1px off its column as an **info**. Fast mode reads authored `height`s only, so rows sized by padding are judged in detailed mode. - **`desktop-app-truncation`** (usability). A column header text with `textOverflow: "ellipsis"` **warns**: a header is never cut. A hand-built text with an ellipsis and no `title` is an **info**, since the full text must be reachable (primitives add their own `title`). Detailed mode adds: a `tabs` node whose every label is cut **warns** (tabs shrink to fit their tablist, so too many tabs in too little width leaves nothing readable), and an ellipsis that leaves fewer than four visible characters, on a text or a primitive's label, is an **info**. - **`desktop-app-primary-count`** (structure, info). Two or more primary `button`s in one pane. Any variant but `secondary`, `ghost` or `destructive` renders filled with the accent, so it counts (no variant included); a disabled one doesn't. Primaries inside three or more same-shaped sibling frames (a grid of cards) are each card's own and don't count. A modal is a region of its own: its `actions` with `variant: "primary"` count there with any primary in its body (a `destructive` action is not a primary), never against the page behind it. +- **`desktop-app-overlay`** (usability). Overlays that cannot work as drawn. + - **Warnings**: a second `modal` on one canvas (one dialog at a time; design the other as its own variant); a `tooltip` with children (they never render); inside a modal, a detected table of more than ten body rows (a header row does not count) or a frame with `overflow: "auto"` that renders wider than the modal or scrolls sideways (a dialog is for a short decision, not for browsing data); an overlay whose box leaves the viewport; and each `popover` or `menu` on a canvas that holds a `modal`, or a `drawer` with `scrim: true`, because it renders under the scrim and looks disabled. + - **Infos**: a second `toast`; a `toast` with `tone: "danger"` (a transient toast is easy to miss, so put the error inline or in a banner); an `anchor` that names no node, or a node that is not a clickable primitive or control (a frame cannot be clicked). An overlay with no `anchor` raises nothing. Each finding is its own entry, so a second toast with `tone: "danger"` gets two infos. + - "Inside a modal" means the modal is the node's nearest overlay ancestor: a popover inside a modal is lifted out, so a table in it is the popover's, not the modal's (the popover itself still gets the scrim warning). "Wider than the modal" compares with the modal's outer width. + - The viewport is the root's numeric `width` and `height`, else the window's (1440×900). A modal wider than the viewport less 32px warns in both modes, since the render squeezes it to fit. + - Detailed mode checks every rendered overlay's box. Fast mode has no render, so it boxes only what your numbers decide: a `popover` or `menu` with numeric `x`, `y`, `width` and `height` (its width as the render resolves it: shrunk to the viewport, held by a `minWidth`, a menu never under 192), and a placed `modal` with numeric `x` and `y` at its own width (its height is its content, so only detailed mode judges its bottom edge). A `tooltip` and a `toast` size to their text and a `drawer` is pinned to the right edge, so only detailed mode sees them leave the window. + - A bare px `width` is squeezed to its parent by the render (`max-width: 100%`), so fast mode reads only a `minWidth`, or a `width` with a `maxWidth` that lets it stay wider (px, %, vw, or `"none"`), as wider than a modal. Start an application screen from a desktop-app realisation, not a web page: see [Starting an application screen](#starting-an-application-screen-desktop-app-realisations). @@ -127,11 +134,11 @@ Repeated desktop-app primitives count as component reuse. On an unthemed canvas, An overlay is a **screen state**: the same screen with a menu open, a comment popover up, a confirm dialog or a toast. Design it as a state variant, not on the base screen: `canvas_add_variant({ canvasId, state: "confirm-delete" })` clones the screen, then insert the overlay into the clone. The recommended state names are `menu-open`, `comment-open`, `confirm-delete` and `toast`. Coverage lists every designed state in `coverage.states` and never demands an overlay state: an overlay is a design choice, not a data obligation. -Wherever you insert an overlay in the tree, it renders in **one overlay layer** after the content: a menu authored inside a sticky toolbar or a scrolling pane is never clipped by the pane and never sits under a sticky or fixed bar. So insert it where it belongs logically (a menu beside the button that opens it) and set `anchor` to that node's id (it is never rendered; the overlay rules of a later release read it). Four things follow: +Wherever you insert an overlay in the tree, it renders in **one overlay layer** after the content: a menu authored inside a sticky toolbar or a scrolling pane is never clipped by the pane and never sits under a sticky or fixed bar. So insert it where it belongs logically (a menu beside the button that opens it) and set `anchor` to that node's id (it is never rendered; `desktop-app-overlay` reads it and flags an anchor that names no node or a node that cannot be clicked). Four things follow: - **`x` / `y` are root coordinates**: offsets from the root's top-left, not from the parent. To open a menu under a button, read the button's box with `snapshot_layout` and use its `x` and its `y` plus its height, whatever toolbar it sits in. The layer is the artboard box, so a centred modal and a bottom toast sit in the artboard. - **Overlays nest freely**: an overlay inside another overlay (a tooltip in a modal, a submenu `menu` in a `menu`) is lifted too and stacks by its own kind, so a tooltip shows above a modal and a menu below it. -- **Layers are fixed by kind**, and there is no `zIndex` property: `popover` and `menu` 400, the scrim of a modal or a drawer 500, `modal` and `drawer` 510, `toast` 600, `tooltip` 800. Everything in the layer sits above all content (`fixed` 10, `sticky` 5, a sheet 30). A menu inside a modal therefore renders under the modal. +- **Layers are fixed by kind**, and there is no `zIndex` property: `popover` and `menu` 400, the scrim of a modal or a drawer 500, `modal` and `drawer` 510, `toast` 600, `tooltip` 800. Everything in the layer sits above all content (`fixed` 10, `sticky` 5, a sheet 30). A menu or popover on a screen with a modal (or a drawer with a scrim) therefore renders under the scrim, and `desktop-app-overlay` warns: put its content in the dialog, or design it open on a variant without one. A variant clones everything on the screen, so a confirm dialog designed from a `menu-open` variant must delete the menu from its clone. - **`snapshot_layout` lists every overlay as a child of the root**, at root coordinates, and a modal (or a drawer with a scrim) carries `scrim: { x, y, width, height }`. The detailed overlap check never counts an overlay as overlapping its siblings. The six overlays take their colours from `$bg-surface`, `$border`, `$text-primary` and `$text-secondary`, and their depth from `$elevation.overlay` (a fallback shadow without it); `fill`, `stroke` and `color` override. diff --git a/docs/specs/PHASE-31-SPEC.md b/docs/specs/PHASE-31-SPEC.md index 8e47a41..6cbf3ee 100644 --- a/docs/specs/PHASE-31-SPEC.md +++ b/docs/specs/PHASE-31-SPEC.md @@ -307,6 +307,31 @@ One profile ships, keyed by id so a second size is one table row later. Values i **Slice F: overlay rules (FR-F1)** - `src/evaluate.ts`: `desktop-app-overlay`; fast bounds from authored rects, detailed bounds from rendered rects. +**Slice F — contracts pinned before build (2026-11-15; frozen at the commit that adds this block).** No pre-freeze verifier: the rule reads one canvas, depends on no earlier run or state, and gates no generated output. +- **Spec change S8 (Victor-approved, 2026-11-15): the scrim covers popovers and menus.** Slice E's L5: a `popover` or `menu` renders at z 400, under a scrim (500), so on a canvas that holds a `modal`, or a `drawer` with `scrim: true`, it shows dimmed behind the dialog. FR-F1 gains a warning on each such popover and menu. Tooltips (800) and toasts (600) sit above the scrim and are not flagged. +- **M1: the rule.** `desktop-app-overlay` joins `DESKTOP_APP_RULES` (desktop-app only; web and mobile never run it), category `usability`. `checkOverlays(ctx, tableIds)` in `src/desktop-app-rules.ts` reads the resolved tree with instances expanded (`DesktopContext`), and its findings go through `reportOnInstances` as the other app rules' do. +- **M2: the viewport and coordinates.** The viewport is the overlay layer's box: width = the root's numeric `width`, else the window profile's width; height = the root's numeric `height`, else the profile's height (the size evaluate renders at). Fast mode reads an overlay's authored `x`/`y` as root coordinates, never adding its parents' offsets. Detailed mode reads the overlay's rect minus the root rect's origin, with 1px of tolerance for rounding. +- **M3: "inside a modal"** means the node's nearest overlay ancestor in the tree is that `modal`. An overlay nested in a modal is lifted out of it (K1), so a table inside a popover inside a modal belongs to the popover, not the modal. +- **M4: the warnings**, each once per offending node: + (a) every `modal` after the first (in tree order) on a canvas; the message gives the count. + (b) a `tooltip` with any child (its children never render, K3). + (c) a detected table (`tableIds`) inside a modal with more than ten body rows: the rows `rowsOf` counts, less the first when `isHeaderRow` says it is a header (Victor, 2026-11-15: a header row does not count). + (d) a `frame` with `overflow: "auto"` inside a modal that is wider than it (the fast clause is corrected by N1 below): fast mode compares the frame's numeric `width`, else its numeric `minWidth`, with `modalWidth(modal)`; detailed mode flags a rect more than 1px wider than the modal's rect, or one whose content scrolls sideways (`scrollWidth` more than 1px past `clientWidth`), which is the horizontal scrolling FR-F1 cites. + (e) an overlay whose box leaves the viewport. The modal clause runs in both modes: a modal whose `modalWidth` exceeds the viewport width less 32 warns, since the renderer clamps it to that (`max-width: calc(100% - 32px)`) and its content is laid out for a width it does not get. Fast mode also checks every overlay except a `drawer` (pinned, it ignores `x`/`y`) that has numeric `x`, `y`, `width` and `height`: `x < 0`, `y < 0`, `x + width` past the viewport width or `y + height` past its height. Detailed mode checks every overlay that has a rect (the scrim excluded) by the same four edges, and falls back to the fast check for an overlay with no rect. One finding per overlay, whichever clause fires first (the modal clause first). + (f) S8: each `popover` and `menu` on a canvas that holds a `modal`, or a `drawer` with `scrim: true`. +- **M5: the infos.** (g) every `toast` after the first. (h) each `toast` with `tone: "danger"`, the suggestion naming an inline error or a banner. (i) an overlay whose `anchor` is a non-blank string that names no node, or a node that is not a clickable primitive (`CLICKABLE_PRIMITIVES` plus the four controls; a `tabs` node counts, as its tabs are targets). An anchor resolves in the expanded tree: inside an instance, first as the overlay's own id prefix (`inst/`) plus the anchor, then as written, so an anchor between two nodes of one component resolves in each instance. +- **M6: agent surfaces.** The `canvas_evaluate` docstring, `INSTRUCTIONS` where it lists the app rules, GUIDELINES' desktop-app rule list, README's rule table and its overlay paragraph (the L5 sentence now names the warning), `test-discoverability.ts`'s rule-id list, and the VISION phase checklist. +- **M7: acceptance in this slice.** The viewer rebuild is slice I, so FR-F1's acceptance runs on two stand-ins in the test, built from `list-detail-app` on a desktop-app canvas: `confirm-delete` (a `sm` modal titled "Delete project?", a body paragraph, actions Cancel and Delete with `variant: "destructive"`) and `comment-open` (a `popover` anchored to a `button`, holding a `text-input` and two `sm` buttons, placed inside the viewport). Both raise no `desktop-app-overlay` finding in fast or detailed mode. Each warning and info of M4 and M5 has a fixture that raises it and a twin, as close as possible, that must not. +- **M8: the inputs the rule must cover** (hard rule 6, the verifier's list): each of the six kinds; authored as a root child, inside a frame, inside a `sticky` bar, inside a component instance, inside another overlay (and a table or scrolling frame inside a popover inside a modal, M3); with and without `x`/`y`, and with only one of them; modal `size` sm / md / lg, a numeric `width`, and none; root `width` and `height` numeric and unset; fast and detailed modes, and a detailed run whose overlay has no rect; tables with and without a header row at ten and eleven body rows, and nested deeper in the modal body; `anchor` absent, blank, unknown, naming a non-clickable node, a clickable primitive, a control, a `tabs` node, a node inside the same instance, and the instance node itself; one and two of modal, toast; a drawer with and without a scrim; `web`, `mobile` and `desktop-app` canvases (only desktop-app raises it); the `categories` filter without `usability`. + +**Slice F — as built (recorded 2026-11-15).** Spec change S8 above; M1 to M8 held except N1. +- **N1: M4(d)'s fast clause read the wrong width.** The renderer shrinks a bare numeric `width` to its parent (`max-width: 100%` unless the node sets `maxWidth`), so a 900px scroller in a 640px modal renders 598 wide and neither overflows nor scrolls; flagging it in fast mode would disagree with detailed mode. Fast mode reads a `minWidth`, or a `width` with a `maxWidth` (capped by a numeric one), which the render keeps. Found by the detailed test before verify; the same holds for a drawer (a bare 1600 width is squeezed to the window, a 1600 `minWidth` leaves it). +- **N2: fast boxes are authored estimates.** M4(e)'s fast check uses authored `width` and `height` even where the render ignores them (a tooltip is `max-content` up to 240, a modal's height is its content); detailed mode is authoritative. +- **N3:** when a canvas holds both a modal and a scrimmed drawer, the S8 message names the modal. Both M7 stand-ins raise no blocking finding of any rule, in fast and detailed mode. +- **Verify round 1 fixes** (each proved red on 64b0856 and green on the fix, with its nearest keep-cases unchanged). (a) A scroller's `width` with a non-numeric `maxWidth` (`"100%"`, a calc) was kept wide in fast mode, though the render squeezes it: `shrunkWidth` now caps a numeric width by a px `maxWidth` (a number or `"…px"`) and otherwise by the parent, so only a px cap past the modal keeps it wide. (b) A modal authored inside a table-shaped frame never had its body tables checked, because the table walk (`extractInventory`) consumes a detected table's subtree: each modal's own subtree is searched too, M3 still deciding ownership. (c) N2 tightened: fast boxes are capped as the render caps them (a tooltip at 240 wide, a toast at 480 and the viewport less 32, a modal at the viewport less 32 by less 64, any other width at the viewport through `shrunkWidth`), so a 2000px popover at x 0 or a 400px tooltip at x 1100 no longer warns; a placed modal 2000 tall at y 100 still warns, since its 836px cap ends at 936. Mutation testing (112 mutants) left boundary, severity, category and fallback survivors; tests now kill them (exact-fit edges, the top edge, fast mode's zero tolerance, the root rect's origin, a missing root rect, the frame-only scroller, a 12-row icon list that is not a table, a placed modal off the edge, each finding's severity, every finding's category, and failing twins for both M7 stand-ins). +- **After verify round 2 (3b)** (proved red on a94c8c9 and green on the fix; not re-verified by an agent). **N4: fast mode boxes only what authored numbers decide, narrowing M4(e)'s fast clause.** Fix (c) still built boxes from numbers the render ignores: a tooltip and a toast take `max-content` and ignore `width`, and a modal's height is its content, so a short tooltip at x 1300, a short toast and a short placed modal at y 700 warned in fast mode while the render was clean. Fast mode now boxes a `popover` or `menu` with numeric `x`, `y`, `width` and `height`, its width as the render resolves it (`shrunkWidth`: shrunk to the viewport, a `minWidth` wins, a menu is at least 192, both of which fast mode had ignored), and a placed `modal` with numeric `x` and `y` at `modalWidth` (left, right and top; its bottom is left to detailed mode). Tooltips, toasts and drawers are detailed-only. `maxWidth` is read as CSS reads it: px, % (of the parent) and vw caps, `"none"` and a negative value (an invalid declaration) uncapped, any other unit as the parent. A test now runs ten popover, menu and modal scenes in both modes and asserts the verdicts agree. Left as found: fast mode has no tolerance and detailed mode 1px, so an overlay exactly 1px past an edge warns in fast mode only (M2). +- **Accepted as specced:** a headerless table of plain-text rows has its first row read as a header by `isHeaderRow`, so eleven such rows count ten (M4(c) follows that test); a fast-mode scroller exactly 1px wider than the modal warns while detailed mode treats 1px as rounding (M2 gives tolerance to detailed only); two overlays sharing one id keep only the later rect (ids must be unique). + **Slice G: element states (FR-G1)** - `src/types.ts`: `state`. `src/renderer.ts`: state layers from the `state` tokens, the focus ring and the double ring. diff --git a/src/desktop-app-rules.ts b/src/desktop-app-rules.ts index 8cba60b..1d42209 100644 --- a/src/desktop-app-rules.ts +++ b/src/desktop-app-rules.ts @@ -4,8 +4,9 @@ import type { EvaluationIssue } from './evaluate.js'; import type { LayoutRect } from './screenshot.js'; import type { SceneNode } from './types.js'; -import { CLICKABLE_PRIMITIVES, DESKTOP_APP_PRIMITIVES, OVERLAY_TYPES, modalActions, tabsItems } from './primitives.js'; +import { CLICKABLE_PRIMITIVES, DESKTOP_APP_PRIMITIVES, OVERLAY_TYPES, MENU_MIN_WIDTH, modalActions, modalWidth, tabsItems } from './primitives.js'; import { fontPx, paddingSides, proseWords } from './mobile-rules.js'; +import { extractInventory } from './drift.js'; import { shapeHash } from './shape-hash.js'; import { windowProfile, DEFAULT_WINDOW, WINDOW_PROFILES, type SurfaceDeclaration, type WindowProfile } from './surfaces.js'; @@ -606,3 +607,212 @@ export function checkPrimaryCount(ctx: DesktopContext): EvaluationIssue[] { } return issues; } + +// ── desktop-app-overlay (FR-F1) ──────────────────────────────────────────── + +/** A modal's body table past this many body rows belongs on a page (a house + * value; Atlassian: no large tables in a modal). */ +const MODAL_TABLE_ROWS = 10; +/** The renderer clamps a modal to the viewport less this (max-width). */ +const MODAL_CLAMP = 32; +const OVERLAY_TOLERANCE = 1; + +/** The width the renderer gives a numeric `width` inside `parent` (`view` is + * the viewport width, for vw), as CSS reads its max-width: a bare width + * shrinks to its parent (max-width: 100%); a px, % or vw `maxWidth` caps it; + * "none" or a negative px (an invalid declaration) leaves it uncapped; any + * other value (a calc, rem) is read as the parent. A `minWidth` wins. */ +function shrunkWidth(n: SceneNode, parent: number, view: number): number | undefined { + if (!isNum(n.width)) return undefined; + const cap = maxWidthCap(n.maxWidth, parent, view); + return Math.max(Math.min(n.width, cap), isNum(n.minWidth) ? n.minWidth : 0); +} + +function maxWidthCap(v: SceneNode['maxWidth'], parent: number, view: number): number { + if (v === undefined) return parent; + if (isNum(v)) return v < 0 ? Infinity : v; + if (typeof v !== 'string') return parent; + const t = v.trim().toLowerCase(); + if (t === 'none') return Infinity; + const m = /^(-?\d*\.?\d+)(px|%|vw)$/.exec(t); + if (!m) return parent; + const num = parseFloat(m[1]); + if (num < 0) return Infinity; + return m[2] === 'px' ? num : (num / 100) * (m[2] === '%' ? parent : view); +} + +/** What an overlay's anchor may name: a clickable primitive or a control. */ +const ANCHOR_TARGETS = new Set([...CLICKABLE_PRIMITIVES, ...CONTROLS]); + +/** The overlay rules: one modal per canvas, text-only tooltips, no large + * tables or sideways scrolling inside a modal, every overlay inside the + * viewport, and no popover or menu under a scrim (spec change S8) warn; a + * second toast, a danger toast and an anchor that names no clickable node are + * infos. The viewport is the overlay layer's box (the root's numeric size, + * else the window profile's); fast mode reads authored rects as root + * coordinates, detailed mode the rendered rects. */ +export function checkOverlays(ctx: DesktopContext, tableIds: Set): EvaluationIssue[] { + const issues: EvaluationIssue[] = []; + const rule = 'desktop-app-overlay'; + const view = { + width: isNum(ctx.root.width) ? ctx.root.width : ctx.profile.width, + height: isNum(ctx.root.height) ? ctx.root.height : ctx.profile.height, + }; + const rootRect = ctx.rects?.get(ctx.root.id); + const byId = new Map(); + const overlays: SceneNode[] = []; + // Each node's nearest overlay ancestor (M3: a lifted overlay owns its subtree). + const owner = new Map(); + (function walk(n: SceneNode, over: SceneNode | undefined) { + byId.set(n.id, n); + owner.set(n, over); + if (OVERLAY_TYPES.has(n.type)) overlays.push(n); + const next = OVERLAY_TYPES.has(n.type) ? n : over; + n.children?.forEach((c) => walk(c, next)); + })(ctx.root, undefined); + if (overlays.length === 0) return issues; + + const modals = overlays.filter((n) => n.type === 'modal'); + if (modals.length > 1) { + for (const m of modals.slice(1)) { + issues.push(issue('usability', rule, 'warning', m, + `This canvas holds ${modals.length} modals — one dialog is open at a time, and a second one stacks over the first behind two scrims.`, + 'Keep one modal per screen state; design the other as its own variant (canvas_add_variant).')); + } + } + // A modal authored inside a table-shaped frame is consumed by that table's + // entry in tableIds, so its own body is searched too (M3: it owns it). + const modalTables = new Set([...tableIds, ...modals.flatMap((m) => extractInventory(m).tables.map((t) => t.nodeId))]); + const scrimmed = modals.length > 0 || overlays.some((n) => n.type === 'drawer' && n.scrim === true); + + for (const n of overlays) { + if (n.type === 'tooltip' && (n.children?.length ?? 0) > 0) { + issues.push(issue('usability', rule, 'warning', n, + `Tooltip "${nameOf(n)}" has ${n.children!.length} child node${n.children!.length === 1 ? '' : 's'} — a tooltip is text only, and its children never render.`, + 'Put the words in its text (U(id, { text: "…" })); for richer content use a popover.')); + } + if (scrimmed && (n.type === 'popover' || n.type === 'menu')) { + issues.push(issue('usability', rule, 'warning', n, + `${n.type === 'menu' ? 'Menu' : 'Popover'} "${nameOf(n)}" renders under the ${modals.length > 0 ? 'modal' : 'drawer'}'s scrim — it shows dimmed behind the dialog and looks disabled.`, + `Put its content in the ${modals.length > 0 ? 'modal' : 'drawer'} itself, or design the ${n.type} open on a variant without the dialog.`)); + } + const out = leavesViewport(n); + if (out) { + issues.push(issue('usability', rule, 'warning', n, out.message, out.suggestion)); + } + } + + // Inside a modal (M3): large tables and frames that scroll sideways. + for (const [n, over] of owner) { + if (over?.type !== 'modal') continue; + if (modalTables.has(n.id)) { + const rows = rowsOf(n); + const body = rows.length > 0 && isHeaderRow(rows[0], rows[1]) ? rows.length - 1 : rows.length; + if (body > MODAL_TABLE_ROWS) { + issues.push(issue('usability', rule, 'warning', n, + `Table "${nameOf(n)}" shows ${body} rows inside modal "${nameOf(over)}" — a dialog is for a short decision, not for browsing data (Atlassian).`, + `Keep the table to ${MODAL_TABLE_ROWS} rows or fewer in the modal, or move it to a page or a drawer.`)); + } + } + if (n.type === 'frame' && n.overflow === 'auto') { + const wide = sidewaysScroll(n, over); + if (wide) { + issues.push(issue('usability', rule, 'warning', n, + `Scrolling frame "${nameOf(n)}" inside modal "${nameOf(over)}" ${wide} — horizontal scrolling inside a dialog is easy to miss (Atlassian).`, + 'Fit the content to the modal (fewer columns, wrapping), give the modal a larger size, or move the content to a page.')); + } + } + } + + const toasts = overlays.filter((n) => n.type === 'toast'); + for (const t of toasts.slice(1)) { + issues.push(issue('usability', rule, 'info', t, + `This canvas shows ${toasts.length} toasts at once — toasts stack over each other and each one gets less attention.`, + 'Show one toast at a time; fold related messages into one.')); + } + for (const t of toasts) { + if (t.tone !== 'danger') continue; + issues.push(issue('usability', rule, 'info', t, + `Toast "${nameOf(t)}" carries an error (tone "danger") — a transient toast is easy to miss, and the error disappears before it is read (NN/g).`, + 'Show the error inline next to what failed, or in a banner that stays until it is dismissed.')); + } + for (const n of overlays) { + if (typeof n.anchor !== 'string' || n.anchor.trim() === '') continue; + const slash = n.id.lastIndexOf('/'); + const target = (slash >= 0 ? byId.get(n.id.slice(0, slash + 1) + n.anchor) : undefined) ?? byId.get(n.anchor); + if (!target) { + issues.push(issue('usability', rule, 'info', n, + `${n.type} "${nameOf(n)}" is anchored to "${n.anchor}", which names no node on this canvas.`, + 'Point anchor at the id of the control that opens it.')); + } else if (!ANCHOR_TARGETS.has(target.type)) { + issues.push(issue('usability', rule, 'info', n, + `${n.type} "${nameOf(n)}" is anchored to "${nameOf(target)}", a ${target.type} — nothing the user can click opens it.`, + 'Anchor it to the button, link or control that opens it (a frame cannot be clicked or reached by keyboard).')); + } + } + return issues; + + /** M4(e): the modal clamp in both modes, then the four edges. */ + function leavesViewport(n: SceneNode): { message: string; suggestion: string } | undefined { + if (n.type === 'modal' && modalWidth(n) > view.width - MODAL_CLAMP) { + return { + message: `Modal "${nameOf(n)}" is ${modalWidth(n)}px wide in a ${view.width}px viewport — the render squeezes it to ${view.width - MODAL_CLAMP}px, narrower than its content was laid out for.`, + suggestion: 'Use a smaller size (sm 480, md 640, lg 960) or width that fits the viewport with 16px each side.', + }; + } + const rect = ctx.rects?.get(n.id); + let box: { x: number; y: number; width: number; height?: number } | undefined; + let tol = 0; + if (rect && rootRect) { + box = { x: rect.x - rootRect.x, y: rect.y - rootRect.y, width: rect.width, height: rect.height }; + tol = OVERLAY_TOLERANCE; + } else { + box = fastBox(n); + } + if (!box) return undefined; + const edges = [ + box.x < -tol && 'left', + box.y < -tol && 'top', + box.x + box.width > view.width + tol && 'right', + box.height !== undefined && box.y + box.height > view.height + tol && 'bottom', + ].filter((e): e is string => !!e); + if (edges.length === 0) return undefined; + return { + message: `${n.type} "${nameOf(n)}" leaves the ${view.width}×${view.height} viewport past its ${edges.join(' and ')} edge${edges.length === 1 ? '' : 's'} (at ${box.x}, ${box.y}, ${box.width}${box.height !== undefined ? `×${box.height}` : ' wide'}) — part of it is cut off.`, + suggestion: 'Move it (x / y are root coordinates) or shrink it so the whole box sits inside the window.', + }; + } + + /** Fast mode's box, only where authored numbers decide the render (N4): a + * popover or menu with numeric x, y, width and height, its width as the + * render resolves it (shrunk to the viewport, its minWidth, a menu's 192 + * floor); a placed modal with numeric x and y, at its own width (its height + * is its content, so its bottom edge is left to detailed mode). A tooltip + * and a toast size to their text, and a drawer is pinned right, so fast + * mode never boxes them. */ + function fastBox(n: SceneNode): { x: number; y: number; width: number; height?: number } | undefined { + if (!isNum(n.x) || !isNum(n.y)) return undefined; + if (n.type === 'modal') return { x: n.x, y: n.y, width: modalWidth(n) }; + if ((n.type !== 'popover' && n.type !== 'menu') || !isNum(n.height)) return undefined; + const width = shrunkWidth(n, view.width, view.width); + if (width === undefined) return undefined; + return { x: n.x, y: n.y, width: n.type === 'menu' ? Math.max(width, MENU_MIN_WIDTH) : width, height: n.height }; + } + + /** M4(d): why a scrolling frame in a modal scrolls sideways, if it does. */ + function sidewaysScroll(n: SceneNode, modal: SceneNode): string | undefined { + if (ctx.rects) { + const r = ctx.rects.get(n.id); + const m = ctx.rects.get(modal.id); + if (r && m && r.width > m.width + OVERLAY_TOLERANCE) return `is ${r.width}px wide in a ${m.width}px modal`; + if (r && isNum(r.scrollWidth) && isNum(r.clientWidth) && r.scrollWidth > r.clientWidth + OVERLAY_TOLERANCE) { + return `scrolls sideways (${r.scrollWidth}px of content in ${r.clientWidth}px)`; + } + if (r) return undefined; + } + // N1: a numeric width shrinks to the modal unless its maxWidth (px, %, vw, + // "none") lets it stay wider; a minWidth always holds. + const w = shrunkWidth(n, modalWidth(modal), view.width) ?? (isNum(n.minWidth) ? n.minWidth : 0); + return w > modalWidth(modal) ? `is ${w}px wide in a ${modalWidth(modal)}px modal` : undefined; + } +} diff --git a/src/evaluate.ts b/src/evaluate.ts index 098dee8..5038f99 100644 --- a/src/evaluate.ts +++ b/src/evaluate.ts @@ -4,7 +4,7 @@ import { getCanvasTokens } from './workspaces.js'; import { renderToHtml, resolveInstance } from './renderer.js'; import { computeLayout, type LayoutRect } from './screenshot.js'; import { - checkCurrent, checkDesktopArtboard, checkHandbuiltTargetsApp, checkIconLabels, checkPrimaryCount, checkRowRhythm, checkTruncation, + checkCurrent, checkDesktopArtboard, checkHandbuiltTargetsApp, checkIconLabels, checkOverlays, checkPrimaryCount, checkRowRhythm, checkTruncation, checkTypeLadder, type DesktopContext, } from './desktop-app-rules.js'; import { extractInventory, expandInstances, isDataLike } from './drift.js'; @@ -2684,6 +2684,7 @@ export async function evaluateCanvas( ...(desktop && ruleOn.has('desktop-app-icon-label') ? checkIconLabels(desktop) : []), ...(desktop && ruleOn.has('desktop-app-current') ? checkCurrent(desktop) : []), ...(desktop && ruleOn.has('desktop-app-truncation') ? checkTruncation(desktop, desktopTables) : []), + ...(desktop && ruleOn.has('desktop-app-overlay') ? checkOverlays(desktop, desktopTables) : []), ], owners); results.set('usability', withRuleIssues(usability, extra)); } diff --git a/src/index.ts b/src/index.ts index 7f6a557..6bd7be8 100644 --- a/src/index.ts +++ b/src/index.ts @@ -85,7 +85,7 @@ Point-and-tell feedback: the user toggles Comment mode in the viewer and clicks Phone app screens: declare the medium. canvas_create({ type: "mobile" }) makes a phone screen — the device artboard (390×844 for the default device "iphone-390") with the root reserving the safe-area insets as safeArea: { top: 47, bottom: 34 } (the renderer adds them to the root's own top/bottom padding, and the root grows with long content keeping that padding past it, so in-flow content never sits under the status bar or home indicator). type: "web" (the default) is a web page; canvas_set_type changes or clears the declaration on an existing canvas (it never resizes or writes safeArea — its result's hint names the op that does). The type selects a ruleset and defaults, never the render: generate_design_system on a mobile canvas pivots the type scale on the device body size (17px; 16px for data-dense), and every evaluate result carries a "surface" report ({ type, device, source "declared" | "default", rulesOn, rulesOff, conflicts }) naming the rule ids the type + genre + preset rulesets turned on and off — a rule both enabled and disabled stays on (in rulesOn) and is listed in conflicts. Start a phone screen from a mobile realisation: apply_structure on a mobile canvas resolves the anatomy name to it — dashboard → dashboard-mobile, settings → settings-mobile, auth → auth-mobile, onboarding → onboarding-mobile, and the mobile-first feed → feed-mobile (a list of rows, pinned tab bar) and detail → detail-mobile (an item with a primary action pinned over the home indicator) — each built from the primitives and gated to pass the mobile ruleset in fast and detailed mode and canvas_stress CLEAN (unthemed and under every personality); stamp it after generate_design_system (the dark, light and material presets carry a 14–15px body that mobile-type-floor flags on a phone). Resolution reads the DECLARED type: an undeclared 390px canvas stamps the web structure, so declare type "mobile" first. Its placeholders include every copy field of its primitives, with prop the field's path (title, subtitle, label, trailing.text, leading.initials, leading.label, items[0].label — a path, not an op key: set a nested one by writing its whole object or array, siblings included). An anatomy with no mobile realisation (the other web pages such as pricing, catalogue or bento-grid; web-only components such as data-table) is refused with the list of those that have one; realisation: "web" stamps the web one anyway. Of the components, form-field, stat-card, empty-state, skeleton-card, skeleton-stat-card, kpi-card, status-chip and initials-avatar stamp on every type. Build phone screens from the mobile primitives (batch_design lists them): status-bar and home-indicator (device chrome), nav-bar, tab-bar, button, list-row, sheet — never hand-built frames — and pin bars with position "fixed" (the renderer reserves room for pinned chrome, so content never starts or ends under it). A mobile canvas runs the mobile ruleset; every finding names its rule in a "rule" field: mobile-touch-target (ERROR: a tap target below 44px — a control (its row counts only when the row is a horizontal frame holding that one tappable), a button (size "sm" is 32, "xs" 24), a list-row, each tab-bar tab and FAB, each nav-bar action; primitives are measured by their own box, inside instances too), mobile-safe-area (WARNING: content under the 47px status-bar or 34px home-indicator inset, or left under a pinned bar at the start or end of the scroll; with root safeArea or pinned chrome the renderer reserves the insets and only positioned content (absolute / fixed / sticky) and pinned bars are checked — padding ≥32px scales down on a phone, so clear a pinned bar with a spacer frame inside your content frame; detailed mode is authoritative), mobile-tab-bar (WARNING: a tab bar with fewer than 2 or more than 5 tabs, an unlabeled tab, or one not pinned to the bottom), mobile-type-floor (WARNING: text below 11px, $body below 16px, prose of 5+ words below 13px), mobile-handbuilt-target (info: an icon-shaped frame below 44px — rebuild it as a button), mobile-one-column (info: two or more side-by-side children each holding 8+ words), and on every type mobile-artboard (a mobile canvas 500px+ wide WARNS; an undeclared canvas narrower than 500px WARNS until canvas_set_type declares it either way). -Application screens: canvas_create({ type: "desktop-app" }) for a tool you work in — an editor, an admin console, a file browser, a viewer: persistent chrome, panes, dense controls, a current selection, in a browser tab or a native window. The test is what the user does: a page you read and scroll is "web", a tool you work in is "desktop-app". It gets the window artboard (1440×900 for the default device "window-1440", no insets); generate_design_system pivots its type on 14px (13 for data-dense); its ruleset turns OFF type-scale-ratio (the adjacent font-size ratio check — dense apps step 12/13/14 on purpose), and desktop-app-artboard (on every type) WARNS when a desktop-app canvas is narrower than 1024px, and when a canvas holding a desktop-app primitive (nav-item, tabs, tree-row, menu-row, property-row) never declared its type or is declared mobile (declared web gets an info); an undeclared canvas holding an overlay (tooltip, popover, menu, modal, toast, drawer) warns too, while web and mobile canvases may hold overlays freely. Build app screens from the desktop-app primitives (batch_design lists them): link, text-input, nav-item, tabs, tree-row, menu-row, property-row, divider, plus button size "xs" (24px) with ariaLabel for icon-only buttons and links — never hand-built frames, which no target rule can measure. A nav-item's dotColor is an identity dot and never counts as a competing accent. Start an app screen from a desktop-app realisation: apply_structure on a desktop-app canvas resolves the anatomy name to it — split-workbench → split-workbench-app, dashboard → dashboard-app, settings → settings-app, and three app-only anatomies: list-detail → list-detail-app (navigation, a searchable list, a detail pane with a "nothing selected" placeholder), editor-inspector → editor-inspector-app (a work area beside a 70/30 inspector of tabs and property-rows), browser → browser-app (a filter bar over an adaptive card grid); data-table → data-table-app (32px toolbar, header, rows and pager; stamp it into a pane at least 480px wide, not a 300px side panel) and skeleton-table → skeleton-table-app (its loading state). Each is built from the primitives and gated: > 95 with no warning, error, tell or desktop-app finding in fast and detailed mode under the presets, every personality and an inherited system, canvas_stress CLEAN at 1440, 1280 and 1024 wide, data-table stamped into a pane at least 480px wide clean too — so a fresh stamp is READY TO PRESENT unless coverage asks for a state. They fill the window: the stamp sets root overflow "hidden" (the root keeps the artboard height) and every pane is overflow "auto", so long content scrolls inside its pane — keep new content inside a pane, and never give a pane's direct child a fixed height or an overflow (the pane squashes it instead of scrolling). Coverage still asks for states: dashboard-app and data-table-app need "empty" + "loading", editor-inspector-app and settings-app (forms) need "error". toolbar, toggle-row, segmented-control and breadcrumb stay web-only (realisation: "web" forces one). On web and desktop-app every pointer target — the four controls and the clickable primitives (button, list-row, tab-bar tabs, nav-bar actions, link, text-input, nav-item, each tab of a tabs, tree-row, menu-row; inline text links are exempt) — meets the 24px WCAG 2.5.8 floor or its spacing exception (nothing else within a 24px circle around it): detailed mode runs that circle test (ERROR on failure), fast mode WARNS on anything under 24 and names detailed mode. The desktop-app ruleset (each finding carries its "rule"; canvas_evaluate lists them) adds: name every icon-only button and link (ariaLabel); mark exactly one current place — one active nav-item per pane — a frame with overflow "auto", so give a rail and a sidebar each their own (a parent may stay active over its active child), one active tab per tabs, one active row per tree; a dense type ladder (desktop-app-type-ladder, replacing type-scale-ratio: 12/13/14 steps are fine, nothing below 11px, prose ≥12px, $body ≥13px); table header rows as tall as their body rows; column headers never truncated; one primary button per pane (info); and frames shaped like small buttons are named as hand-built targets (info) — rebuild them as button or link. Before presenting a desktop-app screen run mode "detailed" too: it measures rendered rows, column edges and truncation (a tablist whose every label is cut warns). Overlays (tooltip, popover, menu, modal, toast, drawer) are screen states: add a variant ("menu-open", "comment-open", "confirm-delete", "toast") with canvas_add_variant and insert the overlay there; wherever it sits in the tree it renders in one layer above all content, stacked by kind (no z-index exists), at x / y in ROOT coordinates; a modal and a drawer are panes of their own (one active nav-item, one primary — a modal's "primary" action counts). +Application screens: canvas_create({ type: "desktop-app" }) for a tool you work in — an editor, an admin console, a file browser, a viewer: persistent chrome, panes, dense controls, a current selection, in a browser tab or a native window. The test is what the user does: a page you read and scroll is "web", a tool you work in is "desktop-app". It gets the window artboard (1440×900 for the default device "window-1440", no insets); generate_design_system pivots its type on 14px (13 for data-dense); its ruleset turns OFF type-scale-ratio (the adjacent font-size ratio check — dense apps step 12/13/14 on purpose), and desktop-app-artboard (on every type) WARNS when a desktop-app canvas is narrower than 1024px, and when a canvas holding a desktop-app primitive (nav-item, tabs, tree-row, menu-row, property-row) never declared its type or is declared mobile (declared web gets an info); an undeclared canvas holding an overlay (tooltip, popover, menu, modal, toast, drawer) warns too, while web and mobile canvases may hold overlays freely. Build app screens from the desktop-app primitives (batch_design lists them): link, text-input, nav-item, tabs, tree-row, menu-row, property-row, divider, plus button size "xs" (24px) with ariaLabel for icon-only buttons and links — never hand-built frames, which no target rule can measure. A nav-item's dotColor is an identity dot and never counts as a competing accent. Start an app screen from a desktop-app realisation: apply_structure on a desktop-app canvas resolves the anatomy name to it — split-workbench → split-workbench-app, dashboard → dashboard-app, settings → settings-app, and three app-only anatomies: list-detail → list-detail-app (navigation, a searchable list, a detail pane with a "nothing selected" placeholder), editor-inspector → editor-inspector-app (a work area beside a 70/30 inspector of tabs and property-rows), browser → browser-app (a filter bar over an adaptive card grid); data-table → data-table-app (32px toolbar, header, rows and pager; stamp it into a pane at least 480px wide, not a 300px side panel) and skeleton-table → skeleton-table-app (its loading state). Each is built from the primitives and gated: > 95 with no warning, error, tell or desktop-app finding in fast and detailed mode under the presets, every personality and an inherited system, canvas_stress CLEAN at 1440, 1280 and 1024 wide, data-table stamped into a pane at least 480px wide clean too — so a fresh stamp is READY TO PRESENT unless coverage asks for a state. They fill the window: the stamp sets root overflow "hidden" (the root keeps the artboard height) and every pane is overflow "auto", so long content scrolls inside its pane — keep new content inside a pane, and never give a pane's direct child a fixed height or an overflow (the pane squashes it instead of scrolling). Coverage still asks for states: dashboard-app and data-table-app need "empty" + "loading", editor-inspector-app and settings-app (forms) need "error". toolbar, toggle-row, segmented-control and breadcrumb stay web-only (realisation: "web" forces one). On web and desktop-app every pointer target — the four controls and the clickable primitives (button, list-row, tab-bar tabs, nav-bar actions, link, text-input, nav-item, each tab of a tabs, tree-row, menu-row; inline text links are exempt) — meets the 24px WCAG 2.5.8 floor or its spacing exception (nothing else within a 24px circle around it): detailed mode runs that circle test (ERROR on failure), fast mode WARNS on anything under 24 and names detailed mode. The desktop-app ruleset (each finding carries its "rule"; canvas_evaluate lists them) adds: name every icon-only button and link (ariaLabel); mark exactly one current place — one active nav-item per pane — a frame with overflow "auto", so give a rail and a sidebar each their own (a parent may stay active over its active child), one active tab per tabs, one active row per tree; a dense type ladder (desktop-app-type-ladder, replacing type-scale-ratio: 12/13/14 steps are fine, nothing below 11px, prose ≥12px, $body ≥13px); table header rows as tall as their body rows; column headers never truncated; one primary button per pane (info); and frames shaped like small buttons are named as hand-built targets (info) — rebuild them as button or link; overlays that cannot work as drawn warn (desktop-app-overlay: a second modal, a tooltip with children, a table of more than 10 body rows or a sideways scroller inside a modal, an overlay leaving the viewport, a popover or menu under the scrim of a modal or a scrim: true drawer) and a second toast, a danger toast and an anchor naming nothing clickable are infos. Before presenting a desktop-app screen run mode "detailed" too: it measures rendered rows, column edges and truncation (a tablist whose every label is cut warns). Overlays (tooltip, popover, menu, modal, toast, drawer) are screen states: add a variant ("menu-open", "comment-open", "confirm-delete", "toast") with canvas_add_variant and insert the overlay there; wherever it sits in the tree it renders in one layer above all content, stacked by kind (no z-index exists), at x / y in ROOT coordinates; a modal and a drawer are panes of their own (one active nav-item, one primary — a modal's "primary" action counts). A menu or popover on a screen with a modal (or a drawer with scrim: true) renders under the scrim: put its content in the dialog, or design it open on a variant without one. Gotchas (current sharp edges): - Row rules and accent bars are per-side borders — borderTop: { width: 1, color: "$border" } on each table row, borderLeft: { width: 3, color: "$primary" } for an accent edge (style "dashed"|"dotted" for forecast/draft outlines; strokeDasharray dashes SVG paths). Never fake hairlines with gap: 1 + background bleed-through. @@ -125,7 +125,7 @@ const GOTCHAS = [ 'The bar: craft beautiful UI/UX a designer would sign off on, and polish to it YOURSELF — start from a pattern, use the whole toolkit (icons/fonts/controls/components), and run canvas_evaluate → resolve EVERY comment → re-evaluate until CLEAN (zero blocking issues) BEFORE presenting. Readiness turns on blocking findings, not the score — the score is always reported and worth climbing toward (aim for > 95), but a clean, sub-bar design is still READY. The evaluate result\'s "directive" field says when it\'s safe to present. Never show the user an unpolished design.', 'Icons: Lucide ({ type: "icon", icon: "search" }) and Material Symbols (icon: "material:check", iconStyle outlined/rounded/sharp, "-fill" suffix for filled) render by name — never fake them with Unicode glyphs. Spelling differs by set: Lucide hyphenates ("chevron-right"), Material keeps underscores AND needs the prefix ("material:chevron_right") — a bare "chevron_right" is looked up in Lucide and renders nothing; canvas_evaluate warns on any icon that resolves in neither set. Casing: use textTransform: "uppercase", not uppercased content.', 'Controls: toggle / checkbox / radio / select are real node types with checked / disabled / value, token-styled — never assemble them from frames + ellipses. For application screens (type "desktop-app") use the desktop-app primitives — link, text-input, nav-item, tabs, tree-row, menu-row, property-row, divider, button size "xs" — never hand-built frames: a frame is not a measured target.', - 'Overlays: tooltip / popover / menu / modal / toast / drawer render in one layer above ALL content whatever their parent (never clipped by a pane, never under a sticky bar), stacked by kind (popover/menu 400 < scrim 500 < modal/drawer 510 < toast 600 < tooltip 800 — a menu inside a modal renders under it). x / y are ROOT coordinates, not offsets from the parent. Put each in a screen-state variant (canvas_add_variant "menu-open" / "comment-open" / "confirm-delete" / "toast"), not on the base screen.', + 'Overlays: tooltip / popover / menu / modal / toast / drawer render in one layer above ALL content whatever their parent (never clipped by a pane, never under a sticky bar), stacked by kind (popover/menu 400 < scrim 500 < modal/drawer 510 < toast 600 < tooltip 800 — a menu or popover on a screen with a modal (or a scrimmed drawer) renders under its scrim, and desktop-app-overlay warns). x / y are ROOT coordinates, not offsets from the parent. Put each in a screen-state variant (canvas_add_variant "menu-open" / "comment-open" / "confirm-delete" / "toast"), not on the base screen.', 'Bulk edits & queries: replace_matching_properties changes a property across every node matching a value predicate in one call (scope/type filters; dryRun previews the match set); find_nodes is the read-only twin — locate nodes by property/text/name and get ids + paths instead of guessing from read_nodes trees. canvas_autofix apply: true writes the whole mechanical fix set in one call.', 'Component scaffolds: apply_structure with kind "component" structures (data-table, form-field, toolbar, stat-card, toggle-row, the state scaffolds empty-state, skeleton-table, skeleton-card, skeleton-stat-card — plus the Phase 28 dashboard micro-patterns: kpi-card, status-chip, segmented-control, breadcrumb, initials-avatar, all on the tint pair) + targetId stamps reusable fragments with re-keyed IDs — build tables/forms from these, not node-by-node.', 'Charts: the chart node type is data-driven ({ kind: "line"|"bar"|"donut"|"sparkline", series: [{ data, stroke, highlight?, barGradient?, … }], segments? for donuts, gridlines?, xLabels? }) — it does the value→coordinate math, dashes mark projected vs actual, highlight (an index or an array of indices) renders the selected bar solid over muted siblings, donuts take segments + centerValue/centerLabel, sparklines are axis-free with the latest point emphasized. Never hand-compute path d-strings, conic-hack a donut, or hand-place sparkline bars.', @@ -603,7 +603,7 @@ Desktop-app primitives (application screens — canvas_create type "desktop-app" Of these, only property-row renders children; link, text-input, nav-item, tabs, tree-row, menu-row and divider draw their own anatomy and drop any children you give them (of the overlays below, popover, menu, modal and drawer render children; tooltip and toast do not). Labels truncate to one line with an ellipsis and carry their full text as a title; text nodes take title too. On web and desktop-app canvases every one of these except property-row and divider is a pointer target held to the 24px floor. A canvas that holds a nav-item, tabs, tree-row, menu-row or property-row must declare its type (desktop-app-artboard). -Overlays (screen states — put one in a state variant made with canvas_add_variant, e.g. "menu-open", "comment-open", "confirm-delete", "toast"): wherever you insert an overlay in the tree, it renders in ONE overlay layer above all content — never clipped by a scrolling or clipping pane, never under a sticky or fixed bar — stacked by kind, never by a z-index (there is none): popover and menu 400, the modal's scrim 500, modal and drawer 510, toast 600, tooltip 800 (so a menu authored inside a modal renders under it). x / y are offsets from the ROOT's top-left (root coordinates), not from the parent; the layer is the artboard box. Insert it wherever it belongs logically (a menu beside the button that opens it) and set anchor: "" (never rendered; the overlay rules of a later release read it). To open a menu under a button, its y is the button's ROOT y plus its height: read both from snapshot_layout. Colours default from $bg-surface / $border / $text-primary / $text-secondary and $elevation.overlay depth; fill / stroke / color override. +Overlays (screen states — put one in a state variant made with canvas_add_variant, e.g. "menu-open", "comment-open", "confirm-delete", "toast"): wherever you insert an overlay in the tree, it renders in ONE overlay layer above all content — never clipped by a scrolling or clipping pane, never under a sticky or fixed bar — stacked by kind, never by a z-index (there is none): popover and menu 400, the modal's scrim 500, modal and drawer 510, toast 600, tooltip 800 (so a menu or popover on a screen with a modal, or a drawer with scrim: true, renders under the scrim; desktop-app-overlay warns). x / y are offsets from the ROOT's top-left (root coordinates), not from the parent; the layer is the artboard box. Insert it wherever it belongs logically (a menu beside the button that opens it) and set anchor: "" (never rendered; desktop-app-overlay reads it: an anchor naming no node, or a node that is not a clickable primitive or control, is an info). To open a menu under a button, its y is the button's ROOT y plus its height: read both from snapshot_layout. Colours default from $bg-surface / $border / $text-primary / $text-secondary and $elevation.overlay depth; fill / stroke / color override. - tooltip { text, x, y } — inverted ($text-primary fill), wraps at 240px; text only, never children. - popover { x, y, size?: "xs"|"sm"|"md"|"lg" (192/320/480/640, default 320) or width, children } — a panel (vertical, padding 12 by default; layout / gap / padding apply as on a frame): a comment box, a filter form. - menu { x, y, children: menu-row and divider nodes } — padding 4, at least 192 wide, hugs its rows. @@ -2152,7 +2152,7 @@ THE HEURISTIC DIRECTIVE IS THE PRESENTATION GATE. mode: "llm" adds optional dept The result's "genre" field (present whenever cliche ran) makes the genre decision auditable: { active, source ("explicit" param | "provenance" stamp | null), relaxed (tells skipped, by the genre and by the applied preset), notRelaxed ([{ tell, relaxedBy }] — tells still flagging that a DIFFERENT genre would relax), byPreset ({ preset, relaxed } — present when the applied preset relaxed tells on its own, e.g. the material preset) }. active is the canonical genre: an alias reports as its canonical name ("dashboard" → "data", "checkout" → "commerce"). If the score is pinned by tells listed in notRelaxed, the genre is probably wrong — genre follows what the screen is FOR (read screens with the user's own figures → "data"; a screen you complete a purchase on → "commerce"; the Material style → "material" (an editor or admin console is a type, not a genre: declare it with canvas_create / canvas_set_type type "desktop-app")), not what it contains. -The result's "surface" field (always present) reports the canvas TYPE and the rules it selected: { type ("web" | "mobile" | "desktop-app"), device (the profile: a phone such as "iphone-390" on mobile, a window such as "window-1440" on desktop-app, null on web), source ("declared" by canvas_create type / canvas_set_type, or "default" — never declared, judged as web), rulesOn (rule ids the composed type + genre + preset rulesets turned on), rulesOff (rule ids they turned off), conflicts (ids both enabled and disabled — those stay ON) }. On a web canvas rulesOn is ["desktop-app-artboard", "mobile-artboard"] (the base rules, on for every type). On a desktop-app canvas rulesOff lists "type-scale-ratio" (the adjacent font-size ratio check, which tags its warnings with that rule id on web and mobile; dense apps step 12/13/14 on purpose), and desktop-app-artboard (structure, every type) WARNS when a desktop-app canvas is narrower than its window's 1024px minimum, and when a canvas holding a desktop-app primitive (nav-item, tabs, tree-row, menu-row, property-row) never declared its type or is declared mobile — a canvas declared web gets an info instead; an undeclared canvas holding an overlay (tooltip, popover, menu, modal, toast, drawer) warns too, while declared web or mobile canvases may hold overlays. On a desktop-app canvas rulesOn also lists the desktop-app ruleset, each finding tagged with its "rule": desktop-app-target (usability: the 24px floor above, named — fast WARNING, detailed ERROR when the 24px circle reaches a neighbour; an unlabelled link with no width (or "auto") measures its glyphs, 14px wide or 30 with external, on web too), desktop-app-handbuilt-target (usability info, never blocks: a frame below 32px holding one icon, an icon plus a label of ≤3 words, or a bordered padded frame holding one such label — the shape an imported text button takes; never inside a clickable primitive; rebuild it as a button or link if clickable), desktop-app-icon-label (usability WARNING: an icon-only button or link with no ariaLabel, a collapsed nav-item with a blank label), desktop-app-current (usability WARNING: in one pane — a frame with overflow "auto", a modal, a drawer, or the root; each node belongs to its nearest, so give each navigation region its own pane — two active nav-items at one depth, or two or more nav-items with none active; a tabs node with no active tab or more than one; two active tree-rows under one parent; info: a tree with a current row nesting past two levels), desktop-app-type-ladder (typography WARNING, replaces type-scale-ratio: adjacent sizes a { + const r = await evaluateCanvas(canvasOf(children), { mode }); + return r.issues.filter((i) => i.rule === RULE); +} +const show = (f: EvaluationIssue[]) => JSON.stringify(f.map((i) => `${i.severity} ${i.nodeId}: ${i.message}`)); +const text = (id: string, content: string, extra: Partial = {}): SceneNode => + ({ id, name: id, type: 'text', content, fontSize: 14, color: '#111111', ...extra }); +const frame = (id: string, children: SceneNode[], extra: Partial = {}): SceneNode => + ({ id, name: id, type: 'frame', layout: 'vertical', children, ...extra }); +const LONG = 'Rename this canvas; the new name shows in the gallery and in every link that points at it'; + +// ── M4(e): rendered boxes ────────────────────────────────────────────────── +{ + const tip = (x: number): SceneNode => ({ id: 'tip', name: 'tip', type: 'tooltip', text: LONG, x, y: 100 }); + let f = await findings([tip(1300)]); + check('(e) a wrapped tooltip placed at x 1300 leaves the right edge (rendered)', f.length === 1 && f[0].nodeId === 'tip' && /right edge/.test(f[0].message), show(f)); + f = await findings([tip(1300)], 'fast'); + check('(e) twin: fast mode cannot size it, so it is silent', f.length === 0, show(f)); + f = await findings([tip(1100)]); + check('(e) twin: at x 1100 the 240px tooltip fits', f.length === 0, show(f)); + + const pop = (y: number): SceneNode => ({ id: 'pop', name: 'pop', type: 'popover', x: 200, y, children: Array.from({ length: 8 }, (_, i) => text(`p${i}`, `Option ${i + 1}`)) }); + f = await findings([pop(780)]); + check('(e) a popover whose content runs past the bottom warns (rendered height)', f.length === 1 && /bottom edge/.test(f[0].message), show(f)); + f = await findings([pop(200)]); + check('(e) twin: placed higher it fits', f.length === 0, show(f)); + + f = await findings([{ id: 'dr', name: 'dr', type: 'drawer', minWidth: 1600, children: [text('d', 'Details')] }]); + check('(e) a drawer with a minWidth past the window leaves its left edge (rendered)', f.length === 1 && /left edge/.test(f[0].message), show(f)); + f = await findings([{ id: 'dr', name: 'dr', type: 'drawer', width: 1600, children: [text('d', 'Details')] }]); + check('(e) twin: a bare 1600px drawer width is squeezed to the window, so it is silent', f.length === 0, show(f)); + + f = await findings([{ id: 'm', name: 'm', type: 'modal', title: 'Rename', width: 1420, children: [text('b', 'Body')] }]); + check('(e) a modal wider than the viewport less 32 warns in detailed mode too', f.length === 1 && /squeezes it to 1408px/.test(f[0].message), show(f)); + f = await findings([{ id: 'm', name: 'm', type: 'modal', title: 'Rename', size: 'lg', children: [text('b', 'Body')] }, { id: 'to', name: 'to', type: 'toast', text: 'Saved' }]); + check('(e) twin: a centred modal and a default toast sit inside the viewport (scrim not judged)', f.length === 0, show(f)); +} + +// ── verify round 2: what fast mode leaves to detailed, and agreement ─────── +{ + let f = await findings([{ id: 'tip', name: 'tip', type: 'tooltip', text: LONG, x: -4, y: 100 }]); + check('R2 a tooltip past the left edge warns in detailed mode', f.length === 1 && /left edge/.test(f[0].message), show(f)); + f = await findings([{ id: 'to', name: 'to', type: 'toast', text: LONG, x: 1200, y: 800 }]); + check('R2 a placed toast hugging long text past the right edge warns in detailed mode', f.length === 1 && /right edge/.test(f[0].message), show(f)); + f = await findings([{ id: 'to', name: 'to', type: 'toast', text: 'Saved', x: 1200, y: 800 }]); + check('R2 twin: a short toast there fits', f.length === 0, show(f)); + const body = (n: number) => Array.from({ length: n }, (_, i) => text(`b${i}`, `Paragraph ${i} of the dialog body, long enough to take a line.`)); + f = await findings([{ id: 'm', name: 'm', type: 'modal', title: 'Tall', size: 'sm', x: 100, y: 100, children: body(60) }]); + check('R2 a placed modal with tall content at y 100 leaves the bottom (capped at 836)', f.length === 1 && /bottom edge/.test(f[0].message), show(f)); + f = await findings([{ id: 'm', name: 'm', type: 'modal', title: 'Short', size: 'sm', x: 100, y: 700, height: 300, children: body(1) } as SceneNode]); + check('R2 twin: a short placed modal at y 700 fits whatever its authored height', f.length === 0, show(f)); + + // Fast and detailed agree wherever fast mode boxes an overlay. + const scenes: Array<[string, SceneNode]> = [ + ['popover in', { id: 'o', name: 'o', type: 'popover', x: 1120, y: 100, width: 320, height: 200, children: [] }], + ['popover out', { id: 'o', name: 'o', type: 'popover', x: 1200, y: 100, width: 320, height: 200, children: [] }], + ['popover shrunk', { id: 'o', name: 'o', type: 'popover', x: 0, y: 0, width: 2000, height: 100, children: [] }], + ['popover none', { id: 'o', name: 'o', type: 'popover', x: 0, y: 0, width: 2000, height: 100, maxWidth: 'none', children: [] }], + ['popover 50%', { id: 'o', name: 'o', type: 'popover', x: 700, y: 0, width: 2000, height: 100, maxWidth: '50%', children: [] }], + ['popover minWidth', { id: 'o', name: 'o', type: 'popover', x: 0, y: 0, width: 300, height: 100, minWidth: 1500, children: [] }], + ['menu floor', { id: 'o', name: 'o', type: 'menu', x: 1300, y: 10, width: 100, height: 100, children: [] }], + ['menu fits', { id: 'o', name: 'o', type: 'menu', x: 1248, y: 10, width: 100, height: 100, children: [] }], + ['popover bottom', { id: 'o', name: 'o', type: 'popover', x: 100, y: 850, width: 320, height: 100, children: [] }], + ['modal right', { id: 'o', name: 'o', type: 'modal', title: 'x', size: 'sm', x: 1100, y: 100, children: [text('mb', 'Body')] }], + ]; + for (const [name, node] of scenes) { + const [fast, det] = [await findings([node], 'fast'), await findings([node])]; + check(`R2 fast and detailed agree: ${name}`, fast.length === det.length, `fast ${show(fast)} detailed ${show(det)}`); + } +} + +// ── M4(d): sideways scrolling inside a modal ─────────────────────────────── +{ + const strip = (w: number) => frame('scroll', [frame('row', [text('r', 'Wide row')], { minWidth: w, height: 40, layout: 'horizontal' })], { overflow: 'auto', width: '100%' } as Partial); + const m = (child: SceneNode): SceneNode => ({ id: 'm', name: 'm', type: 'modal', title: 'Columns', size: 'md', children: [child] }); + let f = await findings([m(strip(900))]); + check('(d) a full-width scroller whose content is 900px scrolls sideways in a 640px modal', f.length === 1 && f[0].nodeId === 'scroll' && /scrolls sideways/.test(f[0].message), show(f)); + f = await findings([m(strip(900))], 'fast'); + check('(d) twin: fast mode has no numeric width to compare, so it is silent', f.length === 0, show(f)); + f = await findings([m(strip(400))]); + check('(d) twin: 400px of content does not scroll', f.length === 0, show(f)); + f = await findings([m(frame('scroll', [text('w', 'x')], { overflow: 'auto', minWidth: 900 }))]); + check('(d) a 900px minWidth scroller renders wider than the modal', f.length === 1 && /900px wide in a 640px modal/.test(f[0].message), show(f)); + f = await findings([m(frame('scroll', [text('w', 'x')], { overflow: 'auto', width: 900 }))]); + check('(d) twin: a bare 900px width renders squeezed to the modal, so it is silent', f.length === 0, show(f)); +} + +// ── M7: the acceptance stand-ins, detailed ───────────────────────────────── +async function standIn(overlay: SceneNode[]): Promise<{ overlay: EvaluationIssue[]; blocking: EvaluationIssue[] }> { + const c = createCanvas('accept', undefined, {}, { type: 'desktop-app' }); + applyStructure(c, 'list-detail'); + c.root.children = [...(c.root.children ?? []), ...overlay]; + const r = await evaluateCanvas(c, { mode: 'detailed' }); + return { overlay: r.issues.filter((i) => i.rule === RULE), blocking: r.issues.filter((i) => i.severity !== 'info') }; +} +{ + const confirm = await standIn([{ + id: 'confirm', name: 'Confirm delete', type: 'modal', title: 'Delete project?', size: 'sm', + actions: [{ label: 'Cancel' }, { label: 'Delete', variant: 'destructive' }], + children: [{ id: 'confirm-body', name: 'Body', type: 'text', content: 'This removes the project and its 12 canvases. You cannot undo this.', fontSize: 14, color: '$text-secondary' }], + } as SceneNode]); + check('M7: confirm-delete raises no desktop-app-overlay finding (detailed)', confirm.overlay.length === 0, show(confirm.overlay)); + console.log(` confirm-delete blocking findings (any rule): ${confirm.blocking.length} ${show(confirm.blocking)}`); + const comment = await standIn([ + { id: 'comment-btn', name: 'Comment', type: 'button', label: 'Comment', variant: 'secondary', size: 'sm', icon: 'message-square', position: 'absolute', x: 1200, y: 120 } as SceneNode, + { + id: 'comment', name: 'Comment', type: 'popover', anchor: 'comment-btn', x: 1000, y: 160, size: 'sm', gap: 8, + children: [ + { id: 'comment-input', name: 'Comment', type: 'text-input', label: 'Comment', placeholder: 'Add a comment' } as SceneNode, + frame('comment-actions', [ + { id: 'cancel', name: 'Cancel', type: 'button', label: 'Cancel', variant: 'ghost', size: 'sm' } as SceneNode, + { id: 'post', name: 'Post', type: 'button', label: 'Post', variant: 'primary', size: 'sm' } as SceneNode, + ], { layout: 'horizontal', gap: 8, justifyContent: 'flex-end' }), + ], + } as SceneNode, + ]); + check('M7: comment-open raises no desktop-app-overlay finding (detailed)', comment.overlay.length === 0, show(comment.overlay)); + console.log(` comment-open blocking findings (any rule): ${comment.blocking.length} ${show(comment.blocking)}`); +} + +await shutdown(); +console.log(allPass ? '\nAll desktop-app-overlay detailed tests passed.' : '\nSOME TESTS FAILED'); +process.exit(allPass ? 0 : 1); diff --git a/test-desktop-app-overlay.ts b/test-desktop-app-overlay.ts new file mode 100644 index 0000000..3e24c10 --- /dev/null +++ b/test-desktop-app-overlay.ts @@ -0,0 +1,459 @@ +// Phase 31 slice F — desktop-app-overlay (FR-F1, spec change S8) in fast +// mode. Every finding has a twin, as close as possible, that must stay silent; +// the rule is shown silent on web and mobile. The detailed-mode clauses +// (rendered boxes, rendered modal widths, sideways scrolling) live in +// test-desktop-app-overlay-detailed.ts. +// +// Usage: npx tsx test-desktop-app-overlay.ts + +import './test-env.js'; +import { evaluateCanvas, type EvaluationIssue } from './src/evaluate.js'; +import { checkOverlays } from './src/desktop-app-rules.js'; +import { WINDOW_PROFILES } from './src/surfaces.js'; +import { createCanvas } from './src/scene-graph.js'; +import { applyStructure } from './src/structures.js'; +import type { Canvas, SceneNode } from './src/types.js'; + +let allPass = true; +function check(name: string, cond: boolean, extra?: string) { + if (!cond) allPass = false; + console.log(`${cond ? 'PASS' : 'FAIL'} ${name}${extra ? ` — ${extra}` : ''}`); +} + +type Kind = 'web' | 'mobile' | 'desktop-app'; +interface Opts { type?: Kind; root?: Partial; components?: Record } +function canvasOf(children: SceneNode[], o: Opts = {}): Canvas { + const type = o.type ?? 'desktop-app'; + return { + id: 'c', name: 'c', projectId: 'p', components: o.components ?? {}, variables: {}, createdAt: '', lastModified: '', + root: { id: 'document', type: 'document', name: 'Document', width: 1440, height: 900, fill: '#FFFFFF', layout: 'vertical', padding: 24, children, ...o.root }, + metadata: { surface: type === 'desktop-app' ? { type, device: 'window-1440' } : type === 'mobile' ? { type, device: 'iphone-15' } : { type } }, + } as Canvas; +} +const RULE = 'desktop-app-overlay'; +async function findings(children: SceneNode[], o: Opts = {}): Promise { + const r = await evaluateCanvas(canvasOf(children, o), { mode: 'fast' }); + const f = r.issues.filter((i) => i.rule === RULE); + for (const i of f) if (i.category !== 'usability') wrongCategory.push(`${i.nodeId}: ${i.category}`); + return f; +} +const wrongCategory: string[] = []; +const show = (f: EvaluationIssue[]) => JSON.stringify(f.map((i) => `${i.severity} ${i.nodeId}: ${i.message}`)); +const text = (id: string, content: string, extra: Partial = {}): SceneNode => + ({ id, name: id, type: 'text', content, fontSize: 14, color: '#111111', ...extra }); +const frame = (id: string, children: SceneNode[], extra: Partial = {}): SceneNode => + ({ id, name: id, type: 'frame', layout: 'vertical', children, ...extra }); +const modal = (id: string, children: SceneNode[] = [], extra: Partial = {}): SceneNode => + ({ id, name: id, type: 'modal', title: 'Rename', size: 'sm', children, ...extra }); +const btn = (id: string, extra: Partial = {}): SceneNode => ({ id, name: id, type: 'button', label: id, variant: 'secondary', size: 'sm', ...extra }); + +// ── M4(a): one modal per canvas ──────────────────────────────────────────── +{ + let f = await findings([modal('m1'), modal('m2')]); + check('(a) two modals warn once, on the second', f.length === 1 && f[0].nodeId === 'm2' && f[0].severity === 'warning' && /2 modals/.test(f[0].message), show(f)); + f = await findings([modal('m1')]); + check('(a) twin: one modal is silent', f.length === 0, show(f)); + // Two instances of a component holding a modal render two modals. + const comp: SceneNode = frame('dlg', [modal('cm')]); + f = await findings([{ id: 'i1', name: 'i1', type: 'instance', componentId: 'dlg' }, { id: 'i2', name: 'i2', type: 'instance', componentId: 'dlg' }], { components: { dlg: comp } }); + check('(a) two instances of a modal component warn, on the second instance', f.length === 1 && f[0].nodeId === 'i2' && /inside instance/.test(f[0].message), show(f)); + f = await findings([{ id: 'i1', name: 'i1', type: 'instance', componentId: 'dlg' }], { components: { dlg: comp } }); + check('(a) twin: one instance is silent', f.length === 0, show(f)); + // A modal nested in another modal is still a second modal. + f = await findings([modal('m1', [modal('m2')])]); + check('(a) a modal inside a modal warns', f.length === 1 && f[0].nodeId === 'm2', show(f)); +} + +// ── M4(b): tooltips are text only ────────────────────────────────────────── +{ + const tip = (children?: SceneNode[]): SceneNode => ({ id: 'tip', name: 'tip', type: 'tooltip', text: 'Rename', x: 100, y: 100, ...(children ? { children } : {}) }); + let f = await findings([tip([text('t', 'Rename (F2)')])]); + check('(b) a tooltip with a child warns', f.length === 1 && f[0].nodeId === 'tip' && /text only/.test(f[0].message), show(f)); + f = await findings([tip()]); + check('(b) twin: a text-only tooltip is silent', f.length === 0, show(f)); + f = await findings([tip([])]); + check('(b) twin: an empty children array is silent', f.length === 0, show(f)); +} + +// ── M4(c): no large tables in a modal ────────────────────────────────────── +{ + const cell = (id: string, s: string, extra: Partial = {}) => frame(id, [text(`${id}t`, s, extra)], { width: 120 }); + const header = frame('h', [cell('h1', 'Name', { fontWeight: 600 }), cell('h2', 'Owner', { fontWeight: 600 }), cell('h3', 'Status', { fontWeight: 600 })], { layout: 'horizontal', height: 32 }); + const row = (i: number) => frame(`r${i}`, [cell(`r${i}a`, `Project ${i}`), cell(`r${i}b`, 'Ana'), cell(`r${i}c`, 'Active')], { layout: 'horizontal', height: 32 }); + const table = (rows: number, withHeader = true, id = 'tbl') => frame(id, [...(withHeader ? [header] : []), ...Array.from({ length: rows }, (_, i) => row(i))]); + let f = await findings([modal('m', [table(11)], { size: 'lg' })]); + check('(c) a header plus 11 body rows in a modal warns', f.length === 1 && f[0].nodeId === 'tbl' && /11 rows/.test(f[0].message), show(f)); + f = await findings([modal('m', [table(10)], { size: 'lg' })]); + check('(c) twin: a header plus 10 body rows is silent (the header does not count)', f.length === 0, show(f)); + f = await findings([modal('m', [frame('wrap', [frame('deep', [table(11)])])], { size: 'lg' })]); + check('(c) a table nested deeper in the modal body warns', f.length === 1 && f[0].nodeId === 'tbl', show(f)); + f = await findings([table(20)]); + check('(c) twin: the same table on the page is silent', f.length === 0, show(f)); + // Row-select rows read as data, not a header (isHeaderRow), so all count. + const selRow = (i: number) => frame(`s${i}`, [{ id: `s${i}c`, name: 'c', type: 'checkbox' }, cell(`s${i}a`, `File ${i}`), cell(`s${i}b`, 'Ana')], { layout: 'horizontal', height: 32 }); + const selTable = (n: number) => frame('sel', Array.from({ length: n }, (_, i) => selRow(i))); + f = await findings([modal('m', [selTable(11)], { size: 'lg' })]); + check('(c) 11 rows with no header row warn', f.length === 1 && f[0].nodeId === 'sel' && /11 rows/.test(f[0].message), show(f)); + f = await findings([modal('m', [selTable(10)], { size: 'lg' })]); + check('(c) twin: 10 rows with no header row are silent', f.length === 0, show(f)); + // M3: a table in a popover inside a modal belongs to the popover (lifted). + f = await findings([modal('m', [{ id: 'pop', name: 'pop', type: 'popover', x: 10, y: 10, children: [table(11)] }], { size: 'lg' })]); + check('(c) a table inside a popover inside a modal is not the modal\'s (only S8 fires, on the popover)', f.length === 1 && f[0].nodeId === 'pop' && /scrim/.test(f[0].message), show(f)); +} + +// ── M4(d): no sideways scrolling in a modal ──────────────────────────────── +{ + const pane = (extra: Partial) => frame('scroll', [text('s', 'Wide content')], { overflow: 'auto', ...extra }); + let f = await findings([modal('m', [pane({ minWidth: 700 })], { size: 'md' })]); + check('(d) a 700px minWidth scrolling frame in a 640px modal warns', f.length === 1 && f[0].nodeId === 'scroll' && /700px wide in a 640px modal/.test(f[0].message), show(f)); + f = await findings([modal('m', [pane({ minWidth: 640 })], { size: 'md' })]); + check('(d) twin: a 640px minWidth in a 640px modal is silent', f.length === 0, show(f)); + f = await findings([modal('m', [pane({ width: 900 })], { size: 'md' })]); + check('(d) twin: a bare 900px width is squeezed to the modal by the render, so it is silent', f.length === 0, show(f)); + f = await findings([modal('m', [pane({ width: 900, maxWidth: 1000 })], { size: 'md' })]); + check('(d) a 900px width with a maxWidth keeps its size and warns', f.length === 1 && /900px wide/.test(f[0].message), show(f)); + f = await findings([modal('m', [pane({ width: 900, maxWidth: 600 })], { size: 'md' })]); + check('(d) twin: a maxWidth below the modal caps it', f.length === 0, show(f)); + f = await findings([modal('m', [pane({ minWidth: 900, overflow: 'hidden' })], { size: 'md' })]); + check('(d) twin: a wide frame that clips (overflow hidden) is not a scroller', f.length === 0, show(f)); + f = await findings([modal('m', [pane({ minWidth: 900 })], { width: 1000 })]); + check('(d) twin: a numeric modal width wins over size', f.length === 0, show(f)); + f = await findings([pane({ minWidth: 2000 })]); + check('(d) twin: a wide scroller on the page is silent', f.length === 0, show(f)); +} + +// ── M4(e): overlays stay in the viewport ─────────────────────────────────── +{ + let f = await findings([modal('m', [], { size: 'lg' })]); + check('(e) a centred lg modal (960) in 1440 is silent', f.length === 0, show(f)); + f = await findings([modal('m', [], { width: 1409 })]); + check('(e) a modal wider than the viewport less 32 warns (the render squeezes it)', f.length === 1 && /squeezes it to 1408px/.test(f[0].message), show(f)); + f = await findings([modal('m', [], { width: 1408 })]); + check('(e) twin: exactly the viewport less 32 is silent', f.length === 0, show(f)); + f = await findings([modal('m', [], { size: 'lg' })], { root: { width: 900 } }); + check('(e) an lg modal in a 900px root warns', f.length === 1 && /900px viewport/.test(f[0].message), show(f)); + f = await findings([modal('m', [], { size: 'md' })], { root: { width: 900 } }); + check('(e) twin: an md modal in a 900px root is silent', f.length === 0, show(f)); + f = await findings([modal('m', [], { width: 1430, x: 0, y: 0 })]); + check('(e) the clamp applies to a placed modal too', f.length === 1 && /squeezes/.test(f[0].message), show(f)); + // Root width unset: the window profile's 1440. + f = await findings([modal('m', [], { width: 1420 })], { root: { width: undefined } }); + check('(e) with no root width, the profile width (1440) is the viewport', f.length === 1 && /1440px viewport/.test(f[0].message), show(f)); + + const pop = (extra: Partial): SceneNode => ({ id: 'pop', name: 'pop', type: 'popover', children: [text('p', 'Hi')], ...extra }); + f = await findings([pop({ x: 1300, y: 100, width: 320, height: 200 })]); + check('(e) a popover past the right edge warns', f.length === 1 && /right edge/.test(f[0].message), show(f)); + f = await findings([pop({ x: 1120, y: 100, width: 320, height: 200 })]); + check('(e) twin: one that ends at the right edge is silent', f.length === 0, show(f)); + f = await findings([pop({ x: 1300, y: 100, width: 320 })]); + check('(e) twin: fast mode skips a box with no authored height', f.length === 0, show(f)); + f = await findings([pop({ x: 1300, width: 320, height: 200 })]); + check('(e) twin: fast mode skips a box with only x', f.length === 0, show(f)); + f = await findings([pop({ x: -4, y: 10, width: 60, height: 24 })]); + check('(e) a popover past the left edge warns', f.length === 1 && /left edge/.test(f[0].message), show(f)); + f = await findings([{ id: 'tip', name: 'tip', type: 'tooltip', text: 'Hi', x: -4, y: 10, width: 60, height: 24 }]); + check('(e) twin: a tooltip sizes to its text, so fast mode never boxes it (detailed does)', f.length === 0, show(f)); + f = await findings([pop({ x: 100, y: 850, width: 320, height: 100 })]); + check('(e) past the bottom of a 900px root warns', f.length === 1 && /bottom edge/.test(f[0].message), show(f)); + f = await findings([pop({ x: 100, y: 850, width: 320, height: 100 })], { root: { height: 1200 } }); + check('(e) twin: the same box in a 1200px root is silent', f.length === 0, show(f)); + f = await findings([pop({ x: 100, y: 850, width: 320, height: 100 })], { root: { height: undefined } }); + check('(e) with no root height, the profile height (900) is the viewport', f.length === 1 && /bottom edge/.test(f[0].message), show(f)); + f = await findings([{ id: 'dr', name: 'dr', type: 'drawer', x: -200, y: -50, width: 320, height: 2000, children: [text('d', 'Details')] }]); + check('(e) twin: a drawer ignores x / y (pinned right), so fast mode skips it', f.length === 0, show(f)); + // Root coordinates: a parent's offset is never added. + f = await findings([frame('bar', [pop({ x: 1100, y: 100, width: 320, height: 200 })], { x: 300, position: 'sticky', top: 0 } as Partial)]); + check('(e) twin: inside an offset sticky bar, x / y stay root coordinates', f.length === 0, show(f)); +} + +// ── verify round 1 fixes: what the render shrinks, modals inside tables ──── +{ + const pane = (extra: Partial) => frame('scroll', [text('s', 'Wide content')], { overflow: 'auto', ...extra }); + let f = await findings([modal('m', [pane({ width: 900, maxWidth: '100%' })], { size: 'md' })]); + check('R1.1 a width with maxWidth "100%" is squeezed to the modal: silent', f.length === 0, show(f)); + f = await findings([modal('m', [pane({ width: 900, maxWidth: 'calc(100% - 8px)' })], { size: 'md' })]); + check('R1.1 a width with a calc maxWidth is read as the parent: silent', f.length === 0, show(f)); + f = await findings([modal('m', [pane({ width: 900, maxWidth: '1000px' })], { size: 'md' })]); + check('R1.1 keep: a width with a px-string maxWidth stays wide and warns', f.length === 1 && /900px wide/.test(f[0].message), show(f)); + + // A modal authored in a table-shaped frame (a per-row confirm dialog). + const cell = (id: string, s: string, extra: Partial = {}) => frame(id, [text(`${id}t`, s, extra)], { width: 120 }); + const hdr = (p: string) => frame(`${p}h`, [cell(`${p}h1`, 'Name', { fontWeight: 600 }), cell(`${p}h2`, 'Owner', { fontWeight: 600 })], { layout: 'horizontal', height: 32 }); + const row = (p: string, i: number, extra: SceneNode[] = []) => frame(`${p}r${i}`, [cell(`${p}r${i}a`, `Item ${i}`), cell(`${p}r${i}b`, 'Ana'), ...extra], { layout: 'horizontal', height: 32 }); + const inner = (rows: number) => frame('inner', [hdr('i'), ...Array.from({ length: rows }, (_, i) => row('i', i))]); + const outer = (rows: number) => frame('outer', [hdr('o'), row('o', 0), row('o', 1), row('o', 2, [frame('oc', [modal('m', [inner(rows)], { size: 'lg' })])])]); + f = await findings([outer(11)]); + check('R1.2 a modal inside a table-shaped frame still has its 11-row table checked', f.length === 1 && f[0].nodeId === 'inner' && /11 rows/.test(f[0].message), show(f)); + f = await findings([outer(10)]); + check('R1.2 twin: 10 body rows there are silent', f.length === 0, show(f)); + + // Fast boxes as the render caps them (N2). + const pop = (extra: Partial): SceneNode => ({ id: 'pop', name: 'pop', type: 'popover', children: [text('p', 'Hi')], ...extra }); + f = await findings([pop({ x: 0, y: 0, width: 2000, height: 100 })]); + check('R1.3 a 2000px popover at x 0 shrinks to the viewport: silent', f.length === 0, show(f)); + f = await findings([pop({ x: 100, y: 0, width: 2000, height: 100 })]); + check('R1.3 keep: shrunk to 1440 at x 100 it still leaves the right edge', f.length === 1 && /right edge/.test(f[0].message), show(f)); + const tip = (x: number, width: number): SceneNode => ({ id: 'tip', name: 'tip', type: 'tooltip', text: 'hi', x, y: 10, width, height: 40 }); + f = await findings([tip(1100, 400)]); + check('R1.3 a tooltip never renders past 240 wide: x 1100 + 400 is silent', f.length === 0, show(f)); + f = await findings([tip(1300, 200)]); + check('R2 a tooltip ignores an authored width, so fast mode never boxes it', f.length === 0, show(f)); + f = await findings([modal('m', [], { x: 100, y: 700, width: 400, height: 300 })]); + check('R2 a placed modal\'s height is its content: fast mode leaves its bottom edge to detailed', f.length === 0, show(f)); + f = await findings([modal('m', [], { x: 1100, y: 100, size: 'sm' })]); + check('R2 keep: a placed sm modal (480) at x 1100 leaves the right edge, no height needed', f.length === 1 && /right edge/.test(f[0].message) && /480 wide/.test(f[0].message), show(f)); + f = await findings([modal('m', [], { x: 900, y: 100, size: 'sm' })]); + check('R2 twin: at x 900 it ends at 1380, silent', f.length === 0, show(f)); + f = await findings([modal('m', [], { x: 100, y: -10, size: 'sm' })]); + check('R2 keep: a placed modal above the top warns', f.length === 1 && /top edge/.test(f[0].message), show(f)); + f = await findings([modal('m', [], { x: 1100, size: 'sm' })]); + check('R2 twin: a modal with only x is not boxed in fast mode', f.length === 0, show(f)); + const toast = (x: number): SceneNode => ({ id: 'to', name: 'to', type: 'toast', text: 'Saved', x, y: 800, width: 600, height: 40 }); + f = await findings([toast(900)]); + check('R1.3 a toast is at most 480 wide: x 900 + 600 is silent', f.length === 0, show(f)); + f = await findings([toast(1300)]); + check('R2 a toast sizes to its text, so fast mode never boxes it (detailed does)', f.length === 0, show(f)); + + // maxWidth read as CSS reads it; minWidth and the menu's 192 floor. + f = await findings([pop({ x: 0, y: 0, width: 2000, height: 100, maxWidth: 'none' })]); + check('R2 maxWidth "none" leaves a 2000px popover uncapped: it leaves the right edge', f.length === 1 && /right edge/.test(f[0].message), show(f)); + f = await findings([pop({ x: 0, y: 0, width: 2000, height: 100, maxWidth: -5 })]); + check('R2 a negative maxWidth is an invalid declaration: uncapped, it warns', f.length === 1, show(f)); + for (const mw of ['50%', '50vw']) { + f = await findings([pop({ x: 700, y: 0, width: 2000, height: 100, maxWidth: mw })]); + check(`R2 maxWidth "${mw}" caps it at 720: at x 700 it fits`, f.length === 0, show(f)); + } + f = await findings([pop({ x: 800, y: 0, width: 2000, height: 100, maxWidth: '50%' })]); + check('R2 twin: at x 800 the 720px box leaves', f.length === 1, show(f)); + f = await findings([pop({ x: 0, y: 0, width: 300, height: 100, minWidth: 1500 })]); + check('R2 a minWidth past the viewport wins over width: it leaves', f.length === 1 && /1500/.test(f[0].message), show(f)); + f = await findings([pop({ x: 0, y: 0, width: 300, height: 100, minWidth: 1400 })]); + check('R2 twin: a minWidth that fits is silent', f.length === 0, show(f)); + const menuAt = (x: number): SceneNode => ({ id: 'menu', name: 'menu', type: 'menu', x, y: 10, width: 100, height: 100, children: [] }); + f = await findings([menuAt(1300)]); + check('R2 a menu is at least 192 wide: 100px authored at x 1300 leaves', f.length === 1 && /192/.test(f[0].message), show(f)); + f = await findings([menuAt(1248)]); + check('R2 twin: at x 1248 its 192px box ends at the edge', f.length === 0, show(f)); + const wide = (mw: string, width = 900) => modal('m', [frame('scroll', [text('s', 'x')], { overflow: 'auto', width, maxWidth: mw })], { size: 'md' }); + f = await findings([wide(' 900PX ')]); + check('R2 a px maxWidth is read trimmed and case-blind', f.length === 1 && /900px wide/.test(f[0].message), show(f)); + f = await findings([wide('640.5px', 700)]); + check('R2 a fractional px maxWidth keeps its fraction (640.5 > 640 warns)', f.length === 1, show(f)); + f = await findings([wide('60rem')]); + check('R2 an unknown unit is read as the parent: silent', f.length === 0, show(f)); +} + +// ── M4(f) / S8: nothing under a scrim ────────────────────────────────────── +{ + const menu: SceneNode = { id: 'menu', name: 'menu', type: 'menu', x: 40, y: 40, children: [{ id: 'mr', name: 'mr', type: 'menu-row', label: 'Rename' }] }; + let f = await findings([modal('m'), menu]); + check('(f) a menu beside a modal warns', f.length === 1 && f[0].nodeId === 'menu' && /under the modal's scrim/.test(f[0].message), show(f)); + f = await findings([modal('m', [menu])]); + check('(f) a menu inside a modal warns', f.length === 1 && f[0].nodeId === 'menu', show(f)); + f = await findings([menu]); + check('(f) twin: a menu alone is silent', f.length === 0, show(f)); + const pop: SceneNode = { id: 'pop', name: 'pop', type: 'popover', x: 40, y: 40, children: [text('p', 'Hi')] }; + const drawer = (scrim: boolean): SceneNode => ({ id: 'dr', name: 'dr', type: 'drawer', scrim, children: [text('d', 'Details')] }); + f = await findings([drawer(true), pop]); + check('(f) a popover with a scrimmed drawer warns', f.length === 1 && f[0].nodeId === 'pop' && /drawer's scrim/.test(f[0].message), show(f)); + f = await findings([drawer(false), pop]); + check('(f) twin: a drawer without a scrim leaves the popover alone', f.length === 0, show(f)); + f = await findings([modal('m'), { id: 'tip', name: 'tip', type: 'tooltip', text: 'Hi', x: 40, y: 40 }, { id: 'to', name: 'to', type: 'toast', text: 'Saved' }]); + check('(f) twin: a tooltip and a toast sit above the scrim', f.length === 0, show(f)); +} + +// ── M5(g, h): toasts ─────────────────────────────────────────────────────── +{ + const toast = (id: string, extra: Partial = {}): SceneNode => ({ id, name: id, type: 'toast', text: 'Saved', ...extra }); + let f = await findings([toast('t1'), toast('t2')]); + check('(g) two toasts are one info, on the second', f.length === 1 && f[0].nodeId === 't2' && f[0].severity === 'info', show(f)); + f = await findings([toast('t1')]); + check('(g) twin: one toast is silent', f.length === 0, show(f)); + f = await findings([toast('t1', { tone: 'danger', text: 'Could not save' })]); + check('(h) a danger toast is an info naming an inline error or banner', f.length === 1 && f[0].severity === 'info' && /inline/.test(f[0].suggestion ?? '') && /banner/.test(f[0].suggestion ?? ''), show(f)); + f = await findings([toast('t1', { tone: 'warning' })]); + check('(h) twin: a warning toast is silent', f.length === 0, show(f)); +} + +// ── M5(i): anchors ───────────────────────────────────────────────────────── +{ + const tip = (anchor?: unknown): SceneNode => ({ id: 'tip', name: 'tip', type: 'tooltip', text: 'Rename', x: 40, y: 80, ...(anchor !== undefined ? { anchor } : {}) } as SceneNode); + const page = [btn('save'), frame('card', [text('c', 'Card')]), { id: 'cb', name: 'cb', type: 'checkbox' } as SceneNode, + { id: 'tabs', name: 'tabs', type: 'tabs', items: [{ label: 'One', active: true }, { label: 'Two' }] } as SceneNode]; + let f = await findings([...page, tip('nope')]); + check('(i) an anchor naming no node is an info', f.length === 1 && f[0].severity === 'info' && /names no node/.test(f[0].message), show(f)); + f = await findings([...page, tip('card')]); + check('(i) an anchor naming a frame is an info', f.length === 1 && /a frame/.test(f[0].message), show(f)); + for (const [name, a] of [['a button', 'save'], ['a control', 'cb'], ['a tabs node', 'tabs']] as const) { + f = await findings([...page, tip(a)]); + check(`(i) twin: an anchor naming ${name} is silent`, f.length === 0, show(f)); + } + for (const [name, a] of [['absent', undefined], ['blank', ' ']] as const) { + f = await findings([...page, tip(a)]); + check(`(i) twin: an ${name} anchor is silent`, f.length === 0, show(f)); + } + // Inside an instance, an anchor resolves within that instance first. + const comp: SceneNode = frame('cardc', [btn('b'), { id: 'ctip', name: 'ctip', type: 'tooltip', text: 'More', x: 0, y: 0, anchor: 'b' } as SceneNode]); + const inst = (id: string): SceneNode => ({ id, name: id, type: 'instance', componentId: 'cardc' }); + f = await findings([inst('i1'), inst('i2')], { components: { cardc: comp } }); + check('(i) an anchor between two nodes of one component resolves in each instance', f.length === 0, show(f)); + const stray: SceneNode = frame('strayc', [{ id: 'ctip', name: 'ctip', type: 'tooltip', text: 'More', x: 0, y: 0, anchor: 'missing' } as SceneNode]); + f = await findings([{ id: 'i1', name: 'i1', type: 'instance', componentId: 'strayc' }], { components: { strayc: stray } }); + check('(i) twin: an unresolvable anchor inside an instance is reported on the instance', f.length === 1 && f[0].nodeId === 'i1' && /names no node/.test(f[0].message), show(f)); + // An anchor naming the instance itself reads its resolved root (a frame). + f = await findings([inst('i1'), tip('i1')], { components: { cardc: frame('cardc', [btn('b')]) } }); + check('(i) an anchor naming an instance of a frame component is an info', f.length === 1 && /a frame/.test(f[0].message), show(f)); +} + +// ── M4(e): a detailed run whose overlay has no rect falls back to fast ───── +{ + const root = canvasOf([{ id: 'pop', name: 'pop', type: 'popover', x: 1300, y: 100, width: 320, height: 200, children: [] } as SceneNode]).root; + const rootRect = { nodeId: 'document', x: 0, y: 0, width: 1440, height: 900 }; + const profile = WINDOW_PROFILES['window-1440']; + let f = checkOverlays({ root, profile, rects: new Map([['document', rootRect]]) }, new Set()); + check('(e) detailed with no rect for the overlay uses its authored box', f.length === 1 && /right edge/.test(f[0].message), show(f)); + f = checkOverlays({ root, profile, rects: new Map([['document', rootRect], ['pop', { nodeId: 'pop', x: 1000, y: 100, width: 320, height: 200 }]]) }, new Set()); + check('(e) twin: a rendered rect inside the viewport wins over the authored box', f.length === 0, show(f)); + f = checkOverlays({ root, profile, rects: new Map([['document', rootRect], ['pop', { nodeId: 'pop', x: 1121, y: 100, width: 320, height: 200 }]]) }, new Set()); + check('(e) twin: 1px past the edge is rounding (tolerance)', f.length === 0, show(f)); + f = checkOverlays({ root, profile, rects: new Map([['document', rootRect], ['pop', { nodeId: 'pop', x: 1122, y: 100, width: 320, height: 200 }]]) }, new Set()); + check('(e) 2px past the edge in a rendered rect warns', f.length === 1, show(f)); + f = checkOverlays({ root, profile, rects: new Map([['document', { ...rootRect, x: 100, y: 50 }], ['pop', { nodeId: 'pop', x: 1200, y: 150, width: 320, height: 200 }]]) }, new Set()); + check('(e) rendered rects are read relative to the root rect', f.length === 0, show(f)); +} + +// ── verify round 1: boundaries, severities and fallbacks (mutation survivors) ─ +{ + const pop = (extra: Partial): SceneNode => ({ id: 'pop', name: 'pop', type: 'popover', children: [text('p', 'Hi')], ...extra }); + let f = await findings([pop({ x: 0, y: 0, width: 320, height: 200 })]); + check('B: a box at exactly x 0, y 0 is inside', f.length === 0, show(f)); + f = await findings([pop({ x: 100, y: 700, width: 320, height: 200 })]); + check('B: a box ending exactly at the bottom (900) is inside', f.length === 0, show(f)); + f = await findings([pop({ x: 100, y: -2, width: 320, height: 200 })]); + check('B: a box at y -2 leaves the top edge', f.length === 1 && /top edge/.test(f[0].message), show(f)); + f = await findings([pop({ x: -1, y: 10, width: 320, height: 200 })]); + check('B: fast mode has no tolerance: x -1 leaves the left edge', f.length === 1 && /left edge/.test(f[0].message), show(f)); + f = await findings([pop({ x: 1121, y: 10, width: 320, height: 200 })]); + check('B: fast mode has no tolerance: 1px past the right edge warns', f.length === 1 && /right edge/.test(f[0].message), show(f)); + f = await findings([pop({ y: 850, width: 320, height: 100 })]); + check('B: fast mode skips a box with no x', f.length === 0, show(f)); + f = await findings([modal('m', [], { x: 1300, y: 100, width: 400, height: 300 })]); + check('B: a placed modal past the right edge warns', f.length === 1 && /right edge/.test(f[0].message), show(f)); + + // Detailed rects, injected: root origin y, the fallbacks, the sideways clauses. + const profile = WINDOW_PROFILES['window-1440']; + const rect = (nodeId: string, x: number, y: number, width: number, height: number, extra = {}) => ({ nodeId, x, y, width, height, ...extra }); + const popRoot = canvasOf([pop({ x: 100, y: 800, width: 320, height: 100 })]).root; + f = checkOverlays({ root: popRoot, profile, rects: new Map([['document', rect('document', 0, 100, 1440, 900)], ['pop', rect('pop', 100, 900, 320, 100)]]) }, new Set()); + check('B: rendered y is read from the root rect\'s top (ends at 900 relative)', f.length === 0, show(f)); + f = checkOverlays({ root: popRoot, profile, rects: new Map([['document', rect('document', 0, 100, 1440, 900)], ['pop', rect('pop', 100, 902, 320, 100)]]) }, new Set()); + check('B: twin: 2px further it leaves the bottom', f.length === 1 && /bottom edge/.test(f[0].message), show(f)); + f = checkOverlays({ root: popRoot, profile, rects: new Map([['pop', rect('pop', 100, 0, 320, 100)]]) }, new Set()); + check('B: with no root rect the authored box is used (it fits)', f.length === 0, show(f)); + const tallRoot = canvasOf([pop({ x: 100, y: 850, width: 320, height: 100 })]).root; + f = checkOverlays({ root: tallRoot, profile, rects: new Map([['pop', rect('pop', 100, 0, 320, 100)]]) }, new Set()); + check('B: twin: with no root rect a leaving authored box warns', f.length === 1 && /bottom edge/.test(f[0].message), show(f)); + + const scrollRoot = (extra: Partial) => canvasOf([modal('m', [frame('scroll', [text('s', 'x')], { overflow: 'auto', ...extra })], { size: 'md' })]).root; + const modalRect = rect('m', 400, 300, 640, 300); + const sideways = (frameRect: object | undefined, extra: Partial = {}) => checkOverlays({ + root: scrollRoot(extra), profile, + rects: new Map>([['document', rect('document', 0, 0, 1440, 900)], ['m', modalRect], ...(frameRect ? [['scroll', frameRect] as [string, ReturnType]] : [])]), + }, new Set()); + f = sideways(rect('scroll', 400, 340, 641, 20)); + check('B: a rendered scroller 1px wider than the modal is rounding', f.length === 0, show(f)); + f = sideways(rect('scroll', 400, 340, 642, 20)); + check('B: 2px wider warns', f.length === 1 && /642px wide in a 640px modal/.test(f[0].message), show(f)); + f = sideways(rect('scroll', 400, 340, 600, 20, { scrollWidth: 601, clientWidth: 600 })); + check('B: content 1px past the scroller is rounding', f.length === 0, show(f)); + f = sideways(rect('scroll', 400, 340, 600, 20, { scrollWidth: 602, clientWidth: 600 })); + check('B: content 2px past it scrolls sideways', f.length === 1 && /scrolls sideways/.test(f[0].message), show(f)); + f = sideways(rect('scroll', 400, 340, 500, 20), { minWidth: 900 }); + check('B: a rendered rect wins over an authored minWidth', f.length === 0, show(f)); + f = sideways(undefined, { minWidth: 900 }); + check('B: twin: with no rect for the scroller its minWidth is read', f.length === 1 && /900px wide/.test(f[0].message), show(f)); + + f = await findings([modal('m', [{ id: 'box', name: 'box', type: 'rectangle', overflow: 'auto', minWidth: 900, height: 40 } as SceneNode], { size: 'md' })]); + check('B: only a frame is a scroller (a wide rectangle is not)', f.length === 0, show(f)); + // A navigation list of icon rows is not a table (FR-A5), whatever its length. + const navRows = Array.from({ length: 12 }, (_, i) => frame(`nr${i}`, [{ id: `ni${i}`, name: 'i', type: 'icon', icon: 'folder' } as SceneNode, text(`nt${i}`, `Folder ${i}`)], { layout: 'horizontal', height: 32 })); + f = await findings([modal('m', [frame('folders', navRows)], { size: 'lg' })]); + check('B: 12 icon-led rows in a modal are a list, not a table: silent', f.length === 0, show(f)); + + // Every warning and info at its severity. + const sev = new Map(); + const all = await findings([ + { id: 'tip', name: 'tip', type: 'tooltip', text: 'x', x: 10, y: 10, children: [text('tc', 'child')] } as SceneNode, + modal('m', [frame('tbl', [frame('h', [text('h1', 'A', { fontWeight: 600 }), text('h2', 'B', { fontWeight: 600 })], { layout: 'horizontal' }), + ...Array.from({ length: 11 }, (_, i) => frame(`r${i}`, [text(`a${i}`, 'a'), text(`b${i}`, 'b')], { layout: 'horizontal' }))]), + frame('scroll', [text('s', 'x')], { overflow: 'auto', minWidth: 2000 })], { size: 'lg' }), + { id: 'menu', name: 'menu', type: 'menu', x: 10, y: 10, children: [] } as SceneNode, + pop({ id: 'off', x: 1300, y: 10, width: 320, height: 100, anchor: 'tbl' }), + ]); + for (const i of all) sev.set(`${i.nodeId}:${/text only/.test(i.message) ? 'tip' : /scrim/.test(i.message) ? 'scrim' : /viewport/.test(i.message) ? 'view' : /rows inside/.test(i.message) ? 'table' : /sideways|wide in a/.test(i.message) ? 'scroll' : /anchored/.test(i.message) ? 'anchor' : 'other'}`, i.severity); + const want: Record = { 'tip:tip': 'warning', 'tbl:table': 'warning', 'scroll:scroll': 'warning', 'menu:scrim': 'warning', 'off:scrim': 'warning', 'off:view': 'warning', 'off:anchor': 'info' }; + const got = Object.fromEntries(sev); + check('B: each finding at its severity (tooltip, table, scroller, scrim, viewport warn; anchor info)', JSON.stringify(got, Object.keys(want).sort()) === JSON.stringify(want, Object.keys(want).sort()) && sev.size === Object.keys(want).length, JSON.stringify(got)); + + // Twins for earlier passes. + f = await findings([{ id: 'i1', name: 'i1', type: 'instance', componentId: 'bc' }, { id: 'tip', name: 'tip', type: 'tooltip', text: 'x', x: 10, y: 80, anchor: 'i1' } as SceneNode], + { components: { bc: btn('bc') } }); + check('B: an anchor naming an instance of a button component is silent', f.length === 0, show(f)); + const r = await evaluateCanvas(canvasOf([modal('m1'), modal('m2')]), { mode: 'fast', categories: ['usability'] }); + check('B: twin: the categories filter with usability raises it', r.issues.some((i) => i.rule === RULE)); +} + +// ── only desktop-app runs it; the categories filter ──────────────────────── +{ + const bad = [modal('m1'), modal('m2'), { id: 'to', name: 'to', type: 'toast', text: 'x', tone: 'danger' } as SceneNode]; + for (const type of ['web', 'mobile'] as const) { + const f = await findings(bad, { type }); + check(`the rule is silent on ${type}`, f.length === 0, show(f)); + } + check('twin: the same canvas on desktop-app raises it', (await findings(bad)).length === 2); + const r = await evaluateCanvas(canvasOf(bad), { mode: 'fast', categories: ['structure', 'color'] }); + check('the categories filter without usability skips it', r.issues.every((i) => i.rule !== RULE)); +} + +// ── M7: the acceptance stand-ins ─────────────────────────────────────────── +async function standIn(overlay: (c: Canvas) => SceneNode[]): Promise<{ overlay: EvaluationIssue[]; blocking: EvaluationIssue[] }> { + const c = createCanvas('accept', undefined, {}, { type: 'desktop-app' }); + applyStructure(c, 'list-detail'); + c.root.children = [...(c.root.children ?? []), ...overlay(c)]; + const r = await evaluateCanvas(c, { mode: 'fast' }); + return { overlay: r.issues.filter((i) => i.rule === RULE), blocking: r.issues.filter((i) => i.severity !== 'info') }; +} +{ + const confirm = await standIn(() => [{ + id: 'confirm', name: 'Confirm delete', type: 'modal', title: 'Delete project?', size: 'sm', + actions: [{ label: 'Cancel' }, { label: 'Delete', variant: 'destructive' }], + children: [{ id: 'confirm-body', name: 'Body', type: 'text', content: 'This removes the project and its 12 canvases. You cannot undo this.', fontSize: 14, color: '$text-secondary' }], + } as SceneNode]); + check('M7: confirm-delete raises no desktop-app-overlay finding (fast)', confirm.overlay.length === 0, show(confirm.overlay)); + console.log(` confirm-delete blocking findings (any rule): ${confirm.blocking.length} ${show(confirm.blocking)}`); + const comment = await standIn(() => [ + { id: 'comment-btn', name: 'Comment', type: 'button', label: 'Comment', variant: 'secondary', size: 'sm', icon: 'message-square', position: 'absolute', x: 1200, y: 120 } as SceneNode, + { + id: 'comment', name: 'Comment', type: 'popover', anchor: 'comment-btn', x: 1000, y: 160, size: 'sm', gap: 8, + children: [ + { id: 'comment-input', name: 'Comment', type: 'text-input', label: 'Comment', placeholder: 'Add a comment' } as SceneNode, + frame('comment-actions', [btn('Cancel', { variant: 'ghost' }), btn('Post', { variant: 'primary' })], { layout: 'horizontal', gap: 8, justifyContent: 'flex-end' }), + ], + } as SceneNode, + ]); + check('M7: comment-open raises no desktop-app-overlay finding (fast)', comment.overlay.length === 0, show(comment.overlay)); + console.log(` comment-open blocking findings (any rule): ${comment.blocking.length} ${show(comment.blocking)}`); +} + +// M7 failing twins: the same stand-ins broken on one axis. +{ + const twice = await standIn(() => ['a', 'b'].map((k) => ({ id: `confirm-${k}`, name: 'Confirm', type: 'modal', title: 'Delete project?', size: 'sm', actions: [{ label: 'Cancel' }, { label: 'Delete', variant: 'destructive' }] } as SceneNode))); + check('M7 twin: confirm-delete with a second modal warns', twice.overlay.length === 1 && twice.overlay[0].severity === 'warning', show(twice.overlay)); + const toFrame = await standIn((c) => [{ id: 'comment', name: 'Comment', type: 'popover', anchor: c.root.children![0].id, x: 1000, y: 160, size: 'sm', children: [] } as SceneNode]); + check('M7 twin: comment-open anchored to a frame is an info', toFrame.overlay.length === 1 && toFrame.overlay[0].severity === 'info' && /anchored/.test(toFrame.overlay[0].message), show(toFrame.overlay)); +} + +check('every desktop-app-overlay finding is category usability', wrongCategory.length === 0, wrongCategory.join(', ')); + +console.log(allPass ? '\nAll desktop-app-overlay tests passed.' : '\nSOME TESTS FAILED'); +process.exit(allPass ? 0 : 1); diff --git a/test-desktop-app-rules.ts b/test-desktop-app-rules.ts index 6aa55bf..ce8cd41 100644 --- a/test-desktop-app-rules.ts +++ b/test-desktop-app-rules.ts @@ -291,11 +291,12 @@ const nav = (id: string, extra: Partial = {}): SceneNode => ({ id, na text('big', 'Title', 36), text('small', 'Label', 13), frame('users', [frame('head', cells('h', { textOverflow: 'ellipsis' }), { layout: 'horizontal', height: 40 }), ...[0, 1, 2].map((i) => frame(`r${i}`, cells(`r${i}`), { layout: 'horizontal', height: 32 }))]), frame('bar', [{ id: 'p1', name: 'p1', type: 'button', label: 'Save', variant: 'primary' }, { id: 'p2', name: 'p2', type: 'button', label: 'Publish', variant: 'primary' }], { layout: 'horizontal' }), + { id: 'oops', name: 'oops', type: 'toast', text: 'Could not save', tone: 'danger' }, ]; const expected: Record = { 'desktop-app-target': 'usability', 'desktop-app-handbuilt-target': 'usability', 'desktop-app-icon-label': 'usability', 'desktop-app-current': 'usability', 'desktop-app-type-ladder': 'typography', 'desktop-app-row-rhythm': 'consistency', - 'desktop-app-truncation': 'usability', 'desktop-app-primary-count': 'structure', + 'desktop-app-truncation': 'usability', 'desktop-app-primary-count': 'structure', 'desktop-app-overlay': 'usability', }; check('the combined tree covers every registered desktop-app rule', JSON.stringify(Object.keys(expected).sort()) === JSON.stringify([...DESKTOP_APP_RULES].sort())); const app = (await evaluateCanvas(canvasOf(everything), { mode: 'fast' })).issues;