Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/docs-package-sections-collide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/cli': patch
---

[fix] Two packages that add a section with one title to the same docs topic or guide both keep it. Across packages, a section replaces another only when one carries an authored `id` that is the other's key or a title query the other's title answers. When one package's section holds the key another package's later section derives from its title, the later one is read by a key that starts with its package's provider id (its package name unless it sets one), such as `acme-dune-theme-install`, so `astryx docs`, `--index`, namespace reads and search show both. This includes titles that differ only in letter case: the later of two packages' `Install` and `INSTALL` was read as `install-2` and is now read by its provider key. Every other key collision keeps its numeric suffix. Sections of the topic itself still take a replacement from any package, the last configured winning.

@josephfarina
2 changes: 1 addition & 1 deletion .changeset/item-current-on-focus-target.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@
'@astryxdesign/core': patch
---

[fix] On an interactive Item or ListItem row (with onClick, href or a delegated control), the current marker (`aria-current`) is now on the element that takes focus, so a screen reader announces "current" when the row's button or link is focused. Rows whose root takes focus, and rows that are not interactive, keep it on the root. A selected row still carries `data-selected` on its root and looks the same at rest; while it slides past other rows, a selected row now keeps its fill whatever its `aria-current` value.
[fix] On an interactive Item or ListItem row (with onClick, href or a delegated control), the current marker (`aria-current`) is now on the element that takes focus, so a screen reader announces "current" when the row's button or link is focused. Before, it sat on the row's root, so a screen reader did not announce it on the focused button or link (WCAG 2.2 SC 4.1.2, Name, Role, Value). Rows whose root takes focus, and rows that are not interactive, keep it on the root. A selected row still carries `data-selected` on its root and looks the same at rest; while it slides past other rows, a selected row now keeps its fill whatever its `aria-current` value.

@josephfarina
2 changes: 1 addition & 1 deletion .changeset/multiselector-search-required.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@
'@astryxdesign/core': patch
---

[fix] `MultiSelector` with `hasSearch`: the trigger button no longer carries `aria-required`, which ARIA does not allow on a button. A required field still says so: the field label's visible marker is part of the trigger's name, or a hidden "Required" description is added when the marker is not shown, and the search box carries `aria-required` while the list is open. This matches `Selector`.
[fix] `MultiSelector` with `hasSearch`: the trigger button no longer carries `aria-required`, which ARIA does not allow on a button (WCAG 2.2 SC 4.1.2, Name, Role, Value). Before, the button carried it, an attribute a button may not have. A required field still says so: the field label's visible marker is part of the trigger's name, or a hidden "Required" description is added when the marker is not shown, and the search box carries `aria-required` while the list is open. This matches `Selector`.

@josephfarina
11 changes: 10 additions & 1 deletion docs/specs/AST-046-docs-tree/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,13 @@
The tree is the backbone of one docs graph. Every provider's docs are its nodes,
each with one home in the tree; the links between docs (a command and its API
function, a token reference, a replacement) are its other edges, named by doc
identity. Phase 1 builds the backbone for the CLI's own docs and each

Check warning on line 37 in docs/specs/AST-046-docs-tree/spec.md

View workflow job for this annotation

GitHub Actions / lint

Project status in a record

"phase 1"

Check warning on line 37 in docs/specs/AST-046-docs-tree/spec.md

View workflow job for this annotation

GitHub Actions / lint

Project status in a record

"phase 1"

Check warning on line 37 in docs/specs/AST-046-docs-tree/spec.md

View workflow job for this annotation

GitHub Actions / test-ui (1/4)

Project status in a record

"phase 1"
integration's, and `spec:AST-047` turns the edges into moves a reader can
follow.

This record owns how a doc gets its one home in the tree, how a route is formed,
how `astryx docs` reads the tree, and what `astryx doctor` checks. It rolls out
in phases: phase 1 places the CLI's own docs and the namespace docs and guides

Check warning on line 43 in docs/specs/AST-046-docs-tree/spec.md

View workflow job for this annotation

GitHub Actions / lint

Project status in a record

"phase 1"

Check warning on line 43 in docs/specs/AST-046-docs-tree/spec.md

View workflow job for this annotation

GitHub Actions / lint

Project status in a record

"phase 1"

Check warning on line 43 in docs/specs/AST-046-docs-tree/spec.md

View workflow job for this annotation

GitHub Actions / test-ui (1/4)

Project status in a record

"phase 1"
each integration ships, and gives every other doc a home in a generated
level named for its category, Guides or Foundations; later phases may move
those docs into real sections.
Expand Down Expand Up @@ -176,7 +176,7 @@
route, and when a link between docs names no doc (`spec:AST-047` FR9). These
checks warn, so a project that passed without them keeps passing. The progressive-disclosure check MUST hold each guide the tree
places to the same size budget as every topic.
- **FR9 — Phase 1 places the CLI's own docs.** The CLI MUST ship the `cli`

Check warning on line 179 in docs/specs/AST-046-docs-tree/spec.md

View workflow job for this annotation

GitHub Actions / lint

Project status in a record

"phase 1"

Check warning on line 179 in docs/specs/AST-046-docs-tree/spec.md

View workflow job for this annotation

GitHub Actions / lint

Project status in a record

"phase 1"

Check warning on line 179 in docs/specs/AST-046-docs-tree/spec.md

View workflow job for this annotation

GitHub Actions / test-ui (1/4)

Project status in a record

"phase 1"
namespace with the `commands` and `api` namespaces under it, and the
`authoring` namespace, the one home for integration authors. Every command
doc MUST have a route under `cli/commands`, and every function, schema, and
Expand Down Expand Up @@ -225,7 +225,16 @@
adds one; the JSON read already names each section's package. A replaced
topic or guide MUST name the package it replaced as `replacedPackage`,
beside `replaces`. A `replaces` or `extends` that names no topic and no
guide, such as a namespace, changes nothing.
guide, such as a namespace, changes nothing. An extension's section MAY
replace a section of the doc it extends by an authored `id` that is that
section's key, by its exact title, or by a title whose key is that section's
`id`, and the last package configured wins it. It MUST NOT replace a section
another package added unless one of the two carries an authored `id` that is
the other's key or a title fragment of the other, so two packages that add
sections of one title both keep them. When a section one package added holds
the key that a section of another package, placed after it, derives from its
title, the later section MUST be read by the key its provider id derives, a
hyphen, and its title key, with a numeric suffix when that key is taken.
When two providers claim one route, the CLI's own docs MUST keep it,
including its flat topics' names and the generated topic levels, then integrations
in configured order; between integrations a namespace keeps its route over a
Expand Down
6 changes: 4 additions & 2 deletions packages/cli/api/docs/_adapter.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -1663,7 +1663,7 @@ export async function packageDocTargets(integration, discovered) {
let owner = null;
/** @type {string | null} */
let basePath = null;
/** @type {ReadonlyArray<{path: string}>} every extension of the target, in configured order */
/** @type {ReadonlyArray<{package: string, path: string, providerId?: string}>} every extension of the target, in configured order */
let extensions = [];
/** @type {string[]} */
let guidesBelow = [];
Expand Down Expand Up @@ -1713,7 +1713,9 @@ export async function packageDocTargets(integration, discovered) {
if (doc == null) break;
const file = (await loadTopicFile(extension.path, null)).doc;
if (file == null) continue;
const merged = mergeTopicReport(doc, file);
const merged = mergeTopicReport(doc, file, {
contributor: extension.providerId ?? extension.package,
});
if (extension.path === record.path) {
unplaced = merged.unplaced;
break;
Expand Down
50 changes: 35 additions & 15 deletions packages/cli/api/search/_gather-docs.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import {nodeView} from '../docs/node/node.mjs';
import {
sectionKey,
sectionSummary,
sectionTitleKey,
} from '../../foundation/discovery/docs-section-key.mjs';
import {sectionProse, codeTerms, headings, plain} from './_doc-text.mjs';
import {loadAuthoringSelfDocs} from '../../foundation/discovery/authoring-self-docs.mjs';
Expand Down Expand Up @@ -75,16 +76,24 @@ export async function gatherDocs(cwd) {
}
const read = lowered?.doc ?? null;
if (isExperimentalDoc(read)) continue;
const hiddenHere = new Set([
...hidden,
...(await experimentalSectionKeys(entry.extensions)),
]);
const experimental = await experimentalSections(entry.extensions);
/** @param {any} section */
const isHidden = section => {
if (hidden.has(section.id)) return true;
const provider = lowered?.sectionProviders?.[section.id];
const titleKey = sectionTitleKey(lowered?.sourceTitles?.[section.id]);
return [section.id, titleKey].some(key =>
experimental.has(sectionOf(provider, key)),
);
};
const doc =
read && hiddenHere.size > 0 && Array.isArray(read.sections)
read &&
(hidden.size > 0 || experimental.size > 0) &&
Array.isArray(read.sections)
? {
...read,
sections: read.sections.filter(
(/** @type {any} */ section) => !hiddenHere.has(section.id),
(/** @type {any} */ each) => !isHidden(each),
),
}
: read;
Expand Down Expand Up @@ -207,14 +216,16 @@ export async function gatherDocs(cwd) {
}

/**
* The keys of the sections that experimental extensions add to a topic: like
* an experimental topic, they are read on their own and never searched.
* @param {ReadonlyArray<{path: string}>} extensions
* @returns {Promise<string[]>}
* The sections that experimental extensions add to a topic: like an
* experimental topic, they are read on their own and never searched. Each is
* named by its provider and the key its file gives it, because the merged
* topic may read it by a key that names its package.
* @param {ReadonlyArray<{package: string, path: string, providerId?: string}>} extensions
* @returns {Promise<Set<string>>}
*/
async function experimentalSectionKeys(extensions) {
/** @type {string[]} */
const keys = [];
async function experimentalSections(extensions) {
/** @type {Set<string>} */
const sections = new Set();
for (const extension of extensions) {
let doc;
try {
Expand All @@ -223,11 +234,20 @@ async function experimentalSectionKeys(extensions) {
continue;
}
if (!isExperimentalDoc(doc) || !Array.isArray(doc.sections)) continue;
keys.push(...doc.sections.map(sectionKey));
const provider = extension.providerId ?? extension.package;
for (const section of doc.sections) {
sections.add(sectionOf(provider, sectionKey(section)));
}
}
return keys;
return sections;
}

/**
* @param {string | undefined} provider
* @param {string} key
*/
const sectionOf = (provider, key) => `${provider}\u0000${key}`;

/**
* Is this experimental guide one that search returns (spec:AST-017 FR27): a
* CLI guide whose own doc sets `searchable: true` beside
Expand Down
Loading
Loading