@issuegraph/editor 0.10.0 → 0.23.0

package/dist/audit/panel.d.ts

@@ -0,0 +1,277 @@
+/**
+ * §17d's findings panel: the three RELATIONSHIP findings, as a list.
+ *
+ * `./surface.ts` draws the ambient half — the persistent header count and the
+ * left-bar on an affected rail row. Neither says what was found. This module
+ * draws the list, so a reader who sees a count has somewhere to read it.
+ *
+ * ## Three classes, not four — the fourth is `./refused.ts`'
+ *
+ * `encoding-refused` is drawn OUTSIDE this panel, and SPEC is why: a refusal is
+ * *"surfaced on the issue itself, because until it parses the issue has no
+ * edges at all and would otherwise look simply unencoded"*. The other three
+ * say something about a relationship that exists; that one says the
+ * relationships cannot be read.
+ *
+ * SO THERE ARE TWO COUNTS NOW, AND THEY ARE DIFFERENT NUMBERS ON PURPOSE.
+ * `./surface.ts`'s ambient count stays every finding — it is the persistent
+ * control, it sits in the workspace chrome beside both surfaces, and a reader
+ * works through all four classes. The count in THIS panel's head is this
+ * panel's own cards, because it is enclosed by the list it counts. See
+ * {@link renderAuditPanel}.
+ *
+ * ## It is the module `./surface.ts` predicted
+ *
+ * That file's rule is *"findings travel as data; whatever lists them owns their
+ * escaping"*, and it is still true of it: `renderAuditHeader` concatenates by
+ * hand and is safe because the only value reaching it is a COUNT. A `detail` is
+ * not a number — it is prose about issues a host supplied — so this module is
+ * the lister that owns the escaping, and it owns it the way every other leaf in
+ * this package does: it builds an {@link ElementSpec} tree and the caller renders
+ * it through the viewer's `renderMarkup`. Nothing here writes a tag.
+ *
+ * ## The card is THREE lines, or FOUR when the finding carries a walk
+ *
+ * The frame draws a chip, a title, a mono line of the refs, and a prose
+ * paragraph. This module long drew three, on this argument: `AuditFinding.detail`
+ * ALREADY OPENS WITH THE MEMBERS — `${members.join(' · ')} form a blocked-by
+ * cycle; …` — so *"drawing a members line beside it prints every reference
+ * twice"*.
+ *
+ * THAT ARGUMENT WAS RIGHT ABOUT A LINE THE FRAME DOES NOT DRAW. The frame's
+ * third line is `#544 → #551 → #560 → #544` — a WALK, not the `·`-joined set
+ * the sentence opens with. Calling it "a mono line of the refs" was the slip:
+ * the line that was declined and the line drawn below are not the same line, and
+ * the refs are the only thing they have in common.
+ *
+ * SO THE COST IS CONCEDED RATHER THAN ARGUED AWAY. On a card that carries a
+ * walk the refs really do appear twice, and the head three times. What buys it
+ * is the one thing the sentence cannot say: `#544 · #551 · #560` does not say
+ * who waits on whom, and a stuck group's ordering is the first thing a groomer
+ * needs in order to pick an edge to cut. Direction appears nowhere else on the
+ * card.
+ *
+ * `detail` IS LEFT BYTE-IDENTICAL, and composing the walk INTO it was the
+ * alternative. It is rejected on §17d rather than on the accessible name — a
+ * walk-composed sentence would be collision-free by the same construction the
+ * current one is, so that cost is not real. The reason is that the frame draws a
+ * SEPARATE line and this section is delivered as a frame/implementation pair, so
+ * folding it into the sentence deviates from the artifact the work is measured
+ * against; and it would give `detail` two shapes, since a component §6.6
+ * declines to order has no walk to compose.
+ *
+ * THE ARROW GLYPH IS `aria-hidden`, AND THAT IS A GAP RATHER THAN A WIN. The
+ * only thing the line adds is direction, and the glyph does not carry it: `→`
+ * announces as "right arrow", not "waits on". Announcing the line anyway would
+ * repeat three refs `detail` has just named, in a form that has lost the reason
+ * it was drawn — the same trade `renderAuditPanel`'s `◆` makes below. The
+ * remaining options were a visually-hidden utility this package does not have,
+ * or an `aria-label` on a `p` with no role, which is not reliably announced. So
+ * a screen reader hears exactly what it heard before this line existed, and the
+ * ordering is genuinely lost to it. Filed, not resolved here.
+ *
+ * THE TITLE IS PER CLASS, AND THE FRAME'S ARE PER FINDING. `AuditFinding` has no
+ * title field, and this package appends numbers rather than interpolating them
+ * (`WorkspaceWords.whyRank` records why), so a per-finding title would need a
+ * template language this package has twice refused to ship. Four fixed titles
+ * keep the frame's type hierarchy at no cost to the data model; the difference
+ * is a stated deviation rather than a silent one.
+ *
+ * ## The chip carries `data-ig-audit-kind`, NEVER `data-ig-audit`
+ *
+ * `./styles.ts` ends with an UNQUALIFIED `[data-ig-audit]` rule — deliberately,
+ * because it lands on a row the viewer rendered and this layer may not rewrite
+ * that row's `class`. So an element out here carrying the same attribute picks
+ * up the rail's 2px gold left-bar whatever hue it was given, and the four-hue
+ * chip mapping would draw one gold bar on all four. The severity attribute stays
+ * reserved for the rail rows it was scoped for.
+ *
+ * ## There is no filter control here, and that is SPEC's call rather than a cut
+ *
+ * The frame's panel header carries `filter the rail to these`. SPEC §17a gives
+ * the workspace *"an audit **filter** … for focus; an audit **mode** does not"*,
+ * and §17d gives the header count one job — *"always the same click"*. That is
+ * one control, which `./surface.ts` already draws and which is on screen beside
+ * this panel. A second element on `data-ig-audit-filter` would be a second
+ * TOGGLE for one boolean (`workspace/host.ts` flips rather than sets), one
+ * announcing `aria-pressed` and one not.
+ *
+ * The frame needs its own because it draws the panel STANDALONE, with no
+ * workspace header in the artboard. Composed, it has one.
+ *
+ * ## `Show the loop` is in, because §17d's rule is navigation
+ *
+ * `./surface.ts` states the section's own doctrine: *"every finding is a
+ * judgment call, so the surface offers navigation and never a remedy."* The
+ * frame's other three buttons are remedies and are deferred. Without this one
+ * the panel is a paragraph you cannot act on or navigate from, sitting at the
+ * top of a column whose whole job is the selection.
+ *
+ * IT PUBLISHES `reveal-issue`, NOT the `select-issue` the inspector's hold rows
+ * use, and the difference is the whole of the control's safety. `select-issue`
+ * is a POINTER: with a relationship draft awaiting its target, `workspace/host
+ * .ts` reads a pointer as CHOOSING that target and emits the create proposal.
+ * So "go and look" would have declared a relationship — a write, from the one
+ * surface whose stated rule is that it never offers one. `reveal-issue` moves
+ * the selection and abandons the draft, and can produce no edit at all.
+ *
+ * AND IT IS DRAWN ONLY FOR A LOADED MEMBER — see {@link navigableMember}.
+ *
+ * @see https://github.com/autnmy/issuegraph/blob/main/SPEC.md
+ */
+import { type ElementSpec } from '@issuegraph/viewer';
+import type { AuditClass } from './findings.ts';
+import type { AuditOverlay } from './surface.ts';
+/**
+ * The attribute a severity chip carries.
+ *
+ * ITS OWN NAME RATHER THAN `AUDIT_SEVERITY_ATTRIBUTE`, for the reason in this
+ * module's header: that one is matched by an unqualified rule meant for rail
+ * rows, and a chip wearing it would draw the ambient bar.
+ */
+export declare const AUDIT_KIND_ATTRIBUTE = "data-ig-audit-kind";
+/**
+ * The words this package will not invent.
+ *
+ * TOTAL RECORDS OVER {@link AuditClass}, the shape `AUDIT_CLASS_SPECS` already
+ * uses, so adding a fifth class is a type error here rather than a chip that
+ * silently draws its own key.
+ */
+export interface AuditWords {
+    /** Reads the panel's header after the count — the frame's `encoding problems`. */
+    readonly heading: string;
+    /** The chip on each card. The frame's `cycle`, `stale`, `dead ref`, `refused`. */
+    readonly classes: Readonly<Record<AuditClass, string>>;
+    /**
+     * The card's title line.
+     *
+     * ONE PER CLASS. See this module's header for why the frame's per-finding
+     * titles are not reconstructible.
+     */
+    readonly titles: Readonly<Record<AuditClass, string>>;
+    /** The navigation control on each card — the frame's `Show the loop`. */
+    readonly show: string;
+    /**
+     * The panel head's filter control — the frame's `filter the rail to these`.
+     *
+     * IT LIVES HERE NOW RATHER THAN IN THE HEADER. §17d draws it in the panel
+     * head, and `RULINGS.md` §3 gives the header count one job instead: anchoring
+     * this overlay. One control, one meaning, each.
+     */
+    readonly filter: string;
+    /**
+     * §17d's REMEDIES, one label per control the frame draws.
+     *
+     * `RULINGS.md` §3 makes these required and forbids auto-fix in the same
+     * breath: *"Every button it draws costs one deliberate human keystroke."*
+     * None of them writes. Each selects the finding's subject and hands the work
+     * to the inspector, which already owns every edit affordance — so the label
+     * names the reader's INTENT and the inspector performs it.
+     *
+     * ONE RECORD, NOT ONE PER CLASS, because the frame gives each class its own
+     * wording rather than a shared verb: a `blocked-by` is removed, a
+     * `duplicate-of` is repointed, and a cycle is neither.
+     */
+    readonly remedies: AuditRemedyWords;
+    /**
+     * The refused block's own heading — the frame's `Encoding refused`.
+     *
+     * THE LAST THREE BELONG TO `./refused.ts`, AND THEY LIVE HERE ANYWAY. §17d is
+     * one section and its words are one record: a host wiring the audit supplies
+     * `AuditWords` once, and splitting a second record off for the fourth class
+     * would let a host supply half a section. `classes` and `titles` are already
+     * total over `AuditClass`, which includes `encoding-refused` — so the words
+     * for that class were never going to sit anywhere else.
+     */
+    readonly refusedHeading: string;
+    /** The outward link's label. The package draws the `↗`. */
+    readonly refusedOpen: string;
+    /** The reveal control's label — the frame's `Rewrite from editor`. */
+    readonly refusedRewrite: string;
+}
+/**
+ * The four remedy labels §17d draws, and no others.
+ *
+ * NOT TOTAL OVER `AuditClass`, unlike `classes` and `titles`. The frame gives
+ * `cycle` one remedy, `stale-blocker` two, `dead-duplicate-ref` one and
+ * `encoding-refused` none — the refusal's own controls are `refusedOpen` and
+ * `refusedRewrite`, which already exist. A record keyed by class would make a
+ * host supply a label for a button nothing draws.
+ */
+export interface AuditRemedyWords {
+    /** The frame's `pick one edge to drop`, on a cycle. */
+    readonly pickEdge: string;
+    /** The frame's `Remove the edge`, on a stale blocker. */
+    readonly removeEdge: string;
+    /**
+     * The frame's `Keep as history`, on a stale blocker and nowhere else.
+     *
+     * Drawn from {@link AuditFinding.keepAsHistory}, which the class table
+     * already sets — `true` for `stale-blocker` alone. The field predates this
+     * control and was waiting for it.
+     */
+    readonly keepAsHistory: string;
+    /** The frame's `Repoint or clear`, on a dead duplicate ref. */
+    readonly repoint: string;
+}
+export interface AuditPanelOptions {
+    readonly words: AuditWords;
+    /**
+     * The edge ids the drawn surface actually holds.
+     *
+     * THE SAME ARGUMENT `known` MAKES ONE FIELD UP, and it needs its own field
+     * for the reason a review round proved: the endpoints do not answer it. Two
+     * issues can both be on the drawn page while the edge between them is NOT —
+     * `mount.ts` deliberately preserves such omissions — and a remedy gated on
+     * the ends alone then publishes `select-edge` for an edge the host cannot
+     * resolve, leaving the reader with a button that clears their selection and
+     * opens an inspector with no subject.
+     *
+     * That was the first fix's mistake: "both ends drawn" is a PROXY for "the
+     * edge is drawn", and this is the thing itself.
+     */
+    readonly edges: ReadonlySet<string>;
+    /**
+     * Whether the rail is currently narrowed to these findings.
+     *
+     * The panel DRAWS the state and never holds it: §2's ruling makes the filter
+     * a thing the reader can see is on and clear in one click, and the host owns
+     * which rows the rail is showing.
+     */
+    readonly filtered?: boolean | undefined;
+    /**
+     * The keys the surface being drawn actually carries, so navigation can only
+     * name somewhere the reader can arrive.
+     *
+     * REQUIRED, AND IT IS THE CALLER'S ANSWER RATHER THAN ONE DERIVED HERE. The
+     * audit reads a document that is not always the document on screen: a host
+     * audits the whole repository it holds and renders a page of it — the demo's
+     * own projection audits `held` while drawing `landed`, which can be empty —
+     * so a ref present in `AuditInput.document` may still have no row to reach.
+     * The overlay cannot see that difference, and neither can this module.
+     *
+     * THE SAME SET AND THE SAME RULE `holdRow` ALREADY USES. A hold's subject
+     * control is withheld for "a subject the inspector could not resolve", which
+     * is this question asked one panel over; `renderWorkspace` computes the set
+     * once, off the NORMALIZED document it draws, and hands it to both.
+     */
+    readonly known: ReadonlySet<string>;
+}
+/**
+ * The panel, or `null` when there is nothing to list.
+ *
+ * `null` RATHER THAN AN EMPTY PANEL, and it is not the same decision as the
+ * header count's. The count is drawn at zero on purpose — `./surface.ts`:
+ * *"a control that appears when there is bad news is a control the eye has to
+ * re-find"* — because it IS the control. A list of nothing is not a control; it
+ * is a heading over an empty region in a column whose space belongs to the
+ * selection. So the ambient half stays put at zero and the list goes away.
+ *
+ * IT IS THE LISTED FINDINGS THAT DECIDE, NOT `overlay.findings`. A document
+ * whose only findings are encoding refusals has a non-zero count, a bar on
+ * every affected row, and NOTHING for this panel to list — so it draws the
+ * refused block and no panel at all. Testing the overlay instead would have
+ * drawn a panel whose head said `2` above an empty list.
+ */
+export declare function renderAuditPanel(overlay: AuditOverlay, options: AuditPanelOptions): ElementSpec | null;
+//# sourceMappingURL=panel.d.ts.map

package/dist/audit/panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel.d.ts","sourceRoot":"","sources":["../../src/audit/panel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwHG;AAGH,OAAO,EAAE,KAAK,WAAW,EAAW,MAAM,oBAAoB,CAAC;AAE/D,OAAO,KAAK,EAAE,UAAU,EAA2B,MAAM,eAAe,CAAC;AAEzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACrC;AAuQD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,iBAAiB,GACzB,WAAW,GAAG,IAAI,CAgGpB"}