@issuegraph/editor 0.10.0 → 0.23.0

package/dist/audit/panel.js

@@ -0,0 +1,462 @@
+/**
+ * §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 { element } from '@issuegraph/viewer';
+import { AUDIT_FILTER_ATTRIBUTE } from "./surface.js";
+/**
+ * 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 const AUDIT_KIND_ATTRIBUTE = 'data-ig-audit-kind';
+/**
+ * The navigable member of a finding, or `undefined` when it has none.
+ *
+ * THE FIRST MEMBER THE DRAWN SURFACE CARRIES, and the filter is not defensive
+ * tidying. An encoding refusal is a fact the HOST asserted about an issue it
+ * read, and `findings.ts` keeps one whose ref lies outside the loaded document
+ * ON PURPOSE — filtering findings to the loaded set would drop them on exactly
+ * the issues a paging boundary has not reached. So a finding's members are not
+ * all rows, and a control targeting one that is not advertises a move it cannot
+ * make: the mount reconciles the unknown selection straight back away.
+ *
+ * IT ASKS THE CALLER, NOT THE OVERLAY, AND THE DIFFERENCE IS NOT PEDANTRY. An
+ * earlier revision used `overlay.rowFor`, which answers "does the AUDIT's
+ * document carry this ref" — a different question, and the two come apart
+ * exactly where a host audits more than it draws. The demo does: it audits the
+ * repository it holds and renders a page of it, so a ref can be audited, have
+ * an overlay row, and still reach a view with nothing in it.
+ *
+ * FIRST RATHER THAN "MOST IMPORTANT": a finding names a component, no member of
+ * it leads, and a rule invented here would be a second ranking nothing else in
+ * the package agrees with.
+ */
+function navigableMember(finding, known) {
+    return finding.members.find((ref) => known.has(ref));
+}
+/**
+ * The card for one finding.
+ *
+ * A card whose finding names no loaded issue draws no control — see
+ * {@link navigableMember}. It keeps its chip, title and sentence, because the
+ * FINDING is still true and still worth reading; what it loses is a move that
+ * would not have moved anything.
+ */
+function cardSpec(finding, known, edges, words) {
+    const target = navigableMember(finding, known);
+    return element('li', {
+        class: 'ig-audit-card',
+        [AUDIT_KIND_ATTRIBUTE]: finding.kind,
+        // THE SEVERITY IS PUBLISHED, NOT DRAWN FROM. A host styling the four
+        // differently needs it, and on the card — which this package owns — it
+        // carries no rule of its own, so it cannot collide the way it would on a
+        // chip. See the header.
+        'data-ig-audit-severity': finding.severity,
+    }, [
+        element('span', { class: 'ig-audit-chip', [AUDIT_KIND_ATTRIBUTE]: finding.kind }, [
+            words.classes[finding.kind],
+        ]),
+        element('p', { class: 'ig-audit-title' }, [words.titles[finding.kind]]),
+        // THE FRAME'S THIRD LINE, and only where the reader named an ordering —
+        // see this module's header for the amendment that admits it, the cost it
+        // concedes, and why it is hidden from the accessibility tree.
+        //
+        // THE HEAD REPEATS HERE AND NOWHERE ELSE. `AuditFinding.walk` names each
+        // member once and implies the return edge, because closing the loop is a
+        // drawing decision — this is the drawing.
+        //
+        // NO `AuditWords` ENTRY. The arrow is a glyph the package draws, the same
+        // call `refusedOpen`'s `↗` makes; a host supplies words, not punctuation.
+        // GATED ON THE CLASS AS WELL AS THE FIELD. `AuditFinding` is a public
+        // export and so is this renderer, so a host can hand it a hand-built
+        // finding — and a walk drawn under a `stale blocker` chip would be an
+        // ordering of an edge that has none. The field's own doc says "only ever
+        // on a cycle finding"; this is what makes that a fact here rather than a
+        // hope about callers.
+        finding.kind !== 'cycle' || finding.walk === undefined || finding.walk.length === 0
+            ? null
+            : element('p', { class: 'ig-audit-walk', 'aria-hidden': 'true' }, [
+                [...finding.walk, finding.walk[0]].join(' → '),
+            ]),
+        element('p', { class: 'ig-audit-detail' }, [finding.detail]),
+        target === undefined
+            ? null
+            : element('button', {
+                type: 'button',
+                class: 'ig-audit-show',
+                // `reveal-issue`, NEVER `select-issue`. The latter is a POINTER,
+                // and with a draft awaiting its target `workspace/host.ts` reads a
+                // pointer as choosing that target and emits the create proposal —
+                // so this button would declare a relationship. §17d's surface
+                // "offers navigation and never a remedy", and a control that can
+                // write is a remedy whatever its label says.
+                'data-ig-command': 'reveal-issue',
+                // THE NAME IS THE FINDING'S OWN SENTENCE, AND THAT IS A CLASS
+                // REMOVED RATHER THAN A THIRD ATTEMPT AT IT.
+                //
+                // Several findings mean several of these buttons, and in the one
+                // navigation mode that strips the surrounding card — a screen
+                // reader's BUTTON LIST — the name is all a reader has. Three
+                // revisions tried to SUMMARISE a finding into that name, and each
+                // summary collided on a shape the last had not met: the host's
+                // word alone collided everywhere; adding the ref collided when
+                // one issue carried two findings; adding the class collided when
+                // two findings shared a class AND a target — `a blocked-by y` and
+                // `a blocked-by z`, two closed blockers on one issue.
+                //
+                // The PATTERN is the defect. Any hand-picked subset of a
+                // finding's attributes has two findings that agree on it, so
+                // counting the collisions was never going to end. `detail` is the
+                // one value that cannot collide by construction: `findings.ts`
+                // composes it from the specific edge or members the finding is
+                // about, and documents it as "what the reader can be told, in one
+                // sentence" — so two findings with one sentence are one finding.
+                //
+                // IT ADDS NO ENGLISH. `detail` is already this card's visible
+                // prose, so nothing is announced that is not on screen, and the
+                // host's word still leads. Appended, never interpolated, the
+                // `WorkspaceWords.whyRank` idiom.
+                //
+                // A LONG NAME IS THE RIGHT TRADE. In a button list a name is an
+                // identifier before it is a label, and a distinct sentence beats
+                // a short ambiguous phrase; the VISIBLE label stays the short
+                // word.
+                //
+                // `WorkspaceWords.remove` has the same shape one leaf over and is
+                // deliberately untouched — filed as #176 rather than widened.
+                'data-ig-target': target,
+                'aria-label': `${words.show} ${finding.detail}`,
+            }, [words.show]),
+        // §17d's REMEDIES. Drawn after the navigation control, which is the
+        // frame's order: `Show the loop` then `pick one edge to drop`.
+        remedySpec(finding, known, edges, words),
+    ]);
+}
+/**
+ * The remedy controls for one finding, or `null` where the frame draws none.
+ *
+ * NOT ONE OF THEM WRITES. `RULINGS.md` §3 requires remedies and forbids
+ * auto-fix in one breath, and the mechanism it names is the same for all of
+ * them: *"Taking a remedy selects the finding's issue or edge and hands the
+ * work to the inspector, which already owns every edit affordance."* So every
+ * button here publishes a SELECTION, and the label says what the reader has
+ * decided to do once they are there.
+ *
+ * THE SUBJECT IS THE FINDING'S EDGE WHERE IT HAS ONE. {@link AuditFinding.edge}
+ * carries it for the two edge classes; a cycle names no single edge on purpose
+ * — choosing which to drop is the judgment §17d keeps with the owner — so its
+ * remedy selects the walk's head instead and the reader picks from there.
+ *
+ * WITHHELD RATHER THAN DRAWN INERT when the subject is missing. A finding whose
+ * edge the drawn document does not carry would give a button that selects
+ * nothing: §17d's own `Show the loop` already declines for exactly that reason
+ * one function up, and this follows it rather than inventing a second rule.
+ */
+function remedySpec(finding, known, edges, words) {
+    const { remedies } = words;
+    // A SELECT-EDGE BUTTON, BUILT ONCE. The two edge classes differ only in their
+    // label, so the shape is written once and the difference stays a word.
+    // THE EDGE ITSELF MUST BE DRAWN — not merely its two ends.
+    //
+    // A remedy publishes `select-edge`, and the host resolves that against the
+    // document IT is drawing, which is not always the one the audit read. A
+    // remedy naming an edge that document does not hold is a button that clears
+    // the reader's selection and opens an inspector with no subject.
+    //
+    // THE FIRST VERSION OF THIS GUARD ASKED WHETHER BOTH ENDS WERE KNOWN, and a
+    // review round reproduced the hole: two issues drawn, the edge between them
+    // omitted — which `mount.ts` does on purpose — and both remedies rendered
+    // anyway. Endpoint presence is a PROXY for edge presence and they come apart
+    // exactly where it matters.
+    //
+    // `Show the loop` follows the same rule one function up, asking `known` about
+    // the ref it will actually navigate to. This asks `edges` about the id it
+    // will actually select.
+    const reachable = (edge) => edges.has(edge.id);
+    const onEdge = (label, tag) => finding.edge === undefined || !reachable(finding.edge)
+        ? null
+        : element('button', {
+            type: 'button',
+            class: 'ig-audit-remedy',
+            'data-ig-remedy': tag,
+            // `select-edge`, WHICH SELECTS AND DOES NOT WRITE. The inspector
+            // draws the edge's own controls once it is selected; this only
+            // says which edge the reader is judging.
+            'data-ig-command': 'select-edge',
+            'data-ig-target': finding.edge.id,
+            // THE FINDING'S OWN SENTENCE, for the reason `Show the loop`
+            // records above: in a screen reader's button list the name is all
+            // a reader has, and any hand-picked subset of a finding's
+            // attributes has two findings that agree on it.
+            'aria-label': `${label} ${finding.detail}`,
+        }, [label]);
+    switch (finding.kind) {
+        case 'stale-blocker': {
+            // TWO CONTROLS, AND THE SECOND IS GATED ON THE FINDING'S OWN FIELD rather
+            // than on the class. `keepAsHistory` is read from `AUDIT_CLASS_SPECS` and
+            // is `true` for this class alone — it predates this control and was
+            // waiting for it — so asking the finding keeps the two in step instead of
+            // restating the table here.
+            const remove = onEdge(remedies.removeEdge, 'remove-edge');
+            const keep = finding.keepAsHistory ? onEdge(remedies.keepAsHistory, 'keep-as-history') : null;
+            const both = [remove, keep].filter((spec) => spec !== null);
+            return both.length === 0 ? null : element('div', { class: 'ig-audit-remedies' }, both);
+        }
+        case 'dead-duplicate-ref': {
+            const repoint = onEdge(remedies.repoint, 'repoint');
+            return repoint === null ? null : element('div', { class: 'ig-audit-remedies' }, [repoint]);
+        }
+        case 'cycle': {
+            // THE WALK'S HEAD, NOT AN EDGE. See this function's header: the cycle is
+            // about a component, and the reader chooses the edge in the inspector.
+            // `walk` is absent whenever the reader declined to order the component,
+            // and then there is no defensible head to name — so no button.
+            const head = finding.walk?.[0];
+            // AND THE HEAD HAS TO BE DRAWN, for the reason `reachable` records above.
+            if (head === undefined || !known.has(head))
+                return null;
+            return element('div', { class: 'ig-audit-remedies' }, [
+                element('button', {
+                    type: 'button',
+                    class: 'ig-audit-remedy',
+                    'data-ig-remedy': 'pick-edge',
+                    // `reveal-issue`, NEVER `select-issue`, for the reason the
+                    // navigation control above records: with a draft awaiting its
+                    // target, `workspace/host.ts` reads a POINTER as choosing that
+                    // target and emits a create proposal — so `select-issue` here
+                    // would declare a relationship while claiming to remove one.
+                    'data-ig-command': 'reveal-issue',
+                    'data-ig-target': head,
+                    'aria-label': `${remedies.pickEdge} ${finding.detail}`,
+                }, [remedies.pickEdge]),
+            ]);
+        }
+        // NO REMEDY. The refusal's controls are `refusedOpen` and `refusedRewrite`
+        // in `./refused.ts`, and this panel does not list that class at all.
+        default:
+            return null;
+    }
+}
+/**
+ * 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 function renderAuditPanel(overlay, options) {
+    const listed = overlay.findings.filter((finding) => finding.kind !== 'encoding-refused');
+    if (listed.length === 0)
+        return null;
+    const { words } = options;
+    return element('section', {
+        class: 'ig-audit-panel',
+        // A `section` WITH NO NAME IS NOT A LANDMARK AT ALL — the implicit `region`
+        // role is conditional on an accessible name, so an unnamed one is exposed
+        // as nothing and a reader navigating by landmark cannot find the panel.
+        // `firstpass/render.ts` already names its own section from its words; this
+        // is the same rule one leaf over.
+        'aria-label': words.heading,
+        // A TAB STOP, AND THE REASON IS NOW THE SECOND ONE ALONE. It was the
+        // scroll container itself while #177's half-column bound sat on this
+        // element; since §17d's fourth class moved to `./refused.ts` the bound and
+        // the scrolling belong to the REGION holding both surfaces, and this panel
+        // does not shrink inside it. So "there is content only scrolling reaches"
+        // is no longer a fact about the panel — but the stop stays, because:
+        //
+        // ITS CARDS CANNOT BE RELIED ON TO CARRY THE KEYBOARD. `cardSpec` draws
+        // its navigation control only for a member the drawn document actually
+        // holds, so an audit whose findings all name issues outside the loaded
+        // page renders no button at all. That panel has no focusable descendant,
+        // and browsers disagree about putting a generic scroll container in the
+        // tab order — some do, some never have. Declaring it removes the
+        // disagreement rather than depending on which engine is running.
+        //
+        // It is already named, so this makes a NAMED region focusable rather than
+        // adding an anonymous stop. `styles.ts` draws the ring it now needs.
+        tabindex: '0',
+    }, [
+        element('div', { class: 'ig-audit-panel-head' }, [
+            // THE MARK IS THE FRAME'S, AND IT IS NOT A WORD. `◆` is the same glyph
+            // §17a puts before the ambient count, so the panel and the chip that
+            // counts it read as one thing. `aria-hidden`, because it says nothing a
+            // reader needs said twice — the count and the heading beside it do.
+            element('span', { class: 'ig-audit-mark', 'aria-hidden': 'true' }, ['◆']),
+            // THIS PANEL'S OWN CARDS, NOT `overlay.count`, AND THE TWO ARE NOW
+            // DIFFERENT NUMBERS. `./surface.ts`'s header count is the persistent
+            // control §17d gives one job — "always the same click" — and it counts
+            // every finding, because the reader works through all four classes. This
+            // number is ENCLOSED IN THE SAME BOUNDED, SCROLLING SECTION AS THE LIST
+            // UNDER IT, so once `encoding-refused` moved to `./refused.ts` it would
+            // have printed `4` directly above three cards.
+            //
+            // THE FRAME AGREES: §17d's panel head reads `3 encoding problems` over
+            // exactly its own three cards, with the refusal a separate card outside.
+            // A count enclosed by the thing it counts is a count OF that thing.
+            element('span', { class: 'ig-audit-panel-count' }, [String(listed.length)]),
+            // A REAL HEADING, AT THE LEVEL ITS PLACE IN THE ZONE EARNS. A `span` left
+            // the panel invisible to heading navigation and put a gap in the column's
+            // outline; the caps are the stylesheet's, as they are for every other
+            // heading here, so the host's word stays a word.
+            //
+            // `h2`, NOT `h3`, AND THE LEVEL FOLLOWS THE COMPOSITION. It was an `h3`
+            // while the panel was drawn INSIDE `.ig-inspector`, under that column's
+            // own `h2`. The panel is a SIBLING of it now, and `renderWorkspace`
+            // concatenates the panel first — so an `h3` announced a level three
+            // before the level two it claimed to sit under, describing a nesting the
+            // markup does not have. Two peers, two `h2`s.
+            element('h2', { class: 'ig-audit-panel-heading' }, [words.heading]),
+            // §17d's OWN ENTRY POINT, drawn where the frame draws it. `RULINGS.md` §2
+            // already settled what it does — *"The filter hides ROWS. It never
+            // touches the ORDER"* — and §3 moved it here from the header count so
+            // that count could become this panel's anchor.
+            //
+            // `aria-pressed` IS RIGHT HERE AND WRONG ON THE HEADER. This one really
+            // is a toggle with an ON state; the header's is a disclosure.
+            element('button', {
+                type: 'button',
+                class: 'ig-audit-filter',
+                'aria-pressed': options.filtered === true ? 'true' : 'false',
+                // ONE CHANNEL, NOT TWO. The mount routes this on the published
+                // attribute alone, and a control carrying `data-ig-command` as well
+                // would be two entries in the a11y baseline for one button.
+                [AUDIT_FILTER_ATTRIBUTE]: '',
+            }, [words.filter]),
+        ]),
+        // ORDERED BY THE CLASS TABLE, WHICH `auditOverlay` ALREADY DID. `findings`
+        // arrives in `AUDIT_CLASSES` order because `auditDocument` concatenates its
+        // four detectors in that order; re-sorting here would be a second opinion
+        // about severity next to `AUDIT_CLASS_SPECS`, which is the one that ranks.
+        element('ul', { class: 'ig-audit-list' }, listed.map((finding) => cardSpec(finding, options.known, options.edges, words))),
+    ]);
+}
+//# sourceMappingURL=panel.js.map

package/dist/audit/panel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel.js","sourceRoot":"","sources":["../../src/audit/panel.ts"],"names":[],"mappings":"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"}

package/dist/audit/refused.d.ts

@@ -0,0 +1,99 @@
+/**
+ * §17d's fourth class, drawn on its own rather than in the findings list.
+ *
+ * `./panel.ts` lists the three RELATIONSHIP findings — a cycle, a stale
+ * blocker, a dead duplicate ref. This module draws the fourth, and the
+ * separation is SPEC's rather than a layout preference: an encoding 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; this one says the relationships
+ * cannot be read, which is a statement about an ISSUE.
+ *
+ * ## It reads the host's refusals, not the audit's findings
+ *
+ * The two are the same set — `auditDocument` turns every refusal into a finding
+ * — but only the refusal carries `diagnostic` and `sourceLine`, and only the
+ * refusal is meant to. `AuditFinding` is one shape over four classes, so
+ * declaring two fields three of them can never hold would render an absence as
+ * a value in the module whose fourth class exists to refuse that; and
+ * `AuditFinding.detail` is "one sentence, never parsed, never a code", so
+ * recovering a source line out of it would make a sentence a wire format. See
+ * {@link EncodingRefusal}.
+ *
+ * THE COST IS ONE DUPLICATED RULE AND IT IS STATED RATHER THAN HIDDEN.
+ * `encodingRefusedFindings` deduplicates refusals by ref, first occurrence
+ * winning, and {@link refusalsToDraw} applies the same rule here — so a host
+ * that reports one issue twice gets one finding and one card rather than one
+ * and two. `findings.ts` warns against exactly this shape ("a renderer doing it
+ * would leave the HEADER COUNT wrong"), and the warning is answered rather than
+ * ignored: the count is not computed here, the rule is one line rather than a
+ * detector, and `./panel.test.ts` pins the arithmetic across both surfaces.
+ *
+ * The alternative was to drive this off `overlay.findings` filtered to the
+ * class, using the refusals only as a `ref -> fields` map. That makes the two
+ * surfaces a partition of one list and cannot drift by construction — a real
+ * advantage — but it makes the block read a finding whose only role at that
+ * point is to be a key, in order to learn a ref it was already handed.
+ *
+ * ## Nothing here decides that a refusal is worth drawing
+ *
+ * A refusal naming an issue the drawn page does not carry STILL DRAWS ITS CARD.
+ * `findings.ts` keeps such a refusal on purpose — filtering to the loaded set
+ * would drop findings on exactly the issues a paging boundary has not reached —
+ * and `./surface.ts` deliberately gives it no rail row. What it loses is the
+ * move that needs a row: see {@link revealControl}. It keeps the outward link,
+ * because leaving the application does not need a local row, and it keeps its
+ * prose, because the finding is true.
+ *
+ * ## The block is a tab stop for the same reason the panel is
+ *
+ * Every control here is conditional, so a block whose refusals all name
+ * unloaded issues, with no URL resolver supplied, has NO focusable descendant —
+ * and browsers disagree about putting a generic container in the tab order.
+ * `./panel.ts` met this and settled it; this is the same answer one leaf over.
+ *
+ * @see https://github.com/autnmy/issuegraph/blob/main/SPEC.md
+ */
+import type { IssueRef } from '@issuegraph/store';
+import { type ElementSpec } from '@issuegraph/viewer';
+import type { EncodingRefusal } from './findings.ts';
+import { type AuditWords } from './panel.ts';
+export interface EncodingRefusedBlockOptions {
+    readonly words: AuditWords;
+    /**
+     * The keys the DRAWN surface carries.
+     *
+     * THE SAME SET AND THE SAME RULE `./panel.ts` AND `holdRow` USE, and it is
+     * the caller's answer rather than one derived here: a host audits the whole
+     * repository it holds and renders a page of it, so a ref can be audited and
+     * still have no row to arrive at. Neither this module nor the overlay can see
+     * that difference.
+     */
+    readonly known: ReadonlySet<string>;
+    /**
+     * Where this issue lives, in the host's own world.
+     *
+     * THE HOST'S ANSWER BECAUSE IT IS THE ONLY PARTY THAT HAS ONE. An
+     * {@link IssueRef} is opaque here and this package holds no repository
+     * identity — `check:isolation` is what keeps it that way — so a URL is not
+     * derivable, only supplied.
+     *
+     * ABSENT, `null`, OR NOT LINKABLE ALL MEAN THE SAME THING: no link is drawn.
+     * The last of those is not tidiness. An `href` runs in the host's origin, so
+     * `javascript:` and `data:` are script-execution sinks that escaping does not
+     * close — `renderMarkup` escapes attribute TEXT and has no opinion about
+     * schemes. `@issuegraph/viewer` already owns that allowlist and canonicalizes
+     * the way a URL parser does, which is what a naive scan gets wrong; a second
+     * copy out here would be the mirror whose input space drifts.
+     */
+    readonly issueUrl?: ((ref: IssueRef) => string | null) | undefined;
+}
+/**
+ * The refused block, or `null` when the host reported no refusals.
+ *
+ * `null` RATHER THAN AN EMPTY BLOCK, the same call `renderAuditPanel` makes: a
+ * heading over an empty region is not a control, and this zone's space belongs
+ * to the selection.
+ */
+export declare function renderEncodingRefusedBlock(encodingRefused: readonly EncodingRefusal[], options: EncodingRefusedBlockOptions): ElementSpec | null;
+//# sourceMappingURL=refused.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refused.d.ts","sourceRoot":"","sources":["../../src/audit/refused.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,KAAK,WAAW,EAAuB,MAAM,oBAAoB,CAAC;AAE3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAanE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;CACpE;AAwMD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,SAAS,eAAe,EAAE,EAC3C,OAAO,EAAE,2BAA2B,GACnC,WAAW,GAAG,IAAI,CA+BpB"}