Skip to content
Merged
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/icon-model-groups-replaces.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/cli': patch
---

[experimental] `astryx docs cli/experimental/icon-sets` explains icon meaning groups and `replaces` in its overview: a match lists the other meanings of its group as `relatives` without changing which icon comes first, and a replaced meaning's old name keeps answering while `integration check` names the `map` key to rename. The search example now says the set's icon for a meaning answers where the set maps one.

@josephfarina
123 changes: 123 additions & 0 deletions packages/cli/api/template/no-dead-buttons.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
* @file Guards shipped templates and blocks against new warnings from
* `doctor`'s button check.
* @input Every page template and block folder under assets/templates.
* @output Assertions that `doctor`'s button check reads each folder, warns
* about no button in a block, and in page templates warns only about the
* named calls to action that keep a placeholder `#` link; the folders it
* does not judge are named too.
* @position Template contract test. A copied block or page template then gives
* `doctor` nothing new to warn about. The check stays silent on a button it
* cannot judge, so this test proves only what the check proves.
*/

import fs from 'node:fs';
import path from 'node:path';
import {fileURLToPath} from 'node:url';
import {describe, expect, it} from 'vitest';
import {findButtonsWithoutAction} from '../doctor/_adapter.mjs';

const templatesRoot = path.resolve(
path.dirname(fileURLToPath(import.meta.url)),
'../../assets/templates',
);

/** The note `doctor` gives a button whose only action is a `#` link. */
const PLACEHOLDER_HASH_LINK = /^placeholder link: replace `#`/;

/**
* The page-template calls to action that keep a placeholder `#` link, which
* `doctor` names as a link the builder replaces with a real one. This test
* keeps the list as it ships; a new one fails it.
*/
const PLACEHOLDER_CALLS_TO_ACTION = [
'pages/centered-hero/page.tsx "Get started"',
'pages/centered-hero/page.tsx "Learn more"',
'pages/documentation/page.tsx "Get started"',
'pages/gallery-hero/page.tsx "Get started"',
'pages/gallery-hero/page.tsx "Learn more"',
'pages/product-gallery/page.tsx "Get started"',
'pages/side-gallery/page.tsx "Explore"',
];

/**
* The folders whose own code listens for a press through the DOM, so the
* check judges none of their buttons: kanban-board drags its cards with
* window pointer listeners.
*/
const NOT_JUDGED = ['pages/kanban-board'];

/** @param {string} dir */
function folders(dir) {
return fs
.readdirSync(dir, {withFileTypes: true})
.filter(entry => entry.isDirectory())
.map(entry => path.join(dir, entry.name));
}

/**
* Each button the check reports in these folders, as `folder/file:line label
* (note)`; the buttons whose only action is a `#` link, as `folder/file
* label`; the folders it could not read in full; and the folders it judged
* no button in because their code may act on a press through the DOM.
* @param {string[]} dirs
*/
function report(dirs) {
/** @type {string[]} */
const buttons = [];
/** @type {string[]} */
const placeholders = [];
/** @type {string[]} */
const incomplete = [];
/** @type {string[]} */
const notJudged = [];
for (const dir of dirs) {
const folder = path.relative(templatesRoot, dir);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: on Windows path.relative joins with \, so notJudged gets pages\kanban-board and each placeholder key misses the same way. The page test then fails with no real warning. path.relative(templatesRoot, dir).split(path.sep).join('/') keeps the keys the same on every platform, as doctor's adapter does for its own paths.

const {found, incomplete: cut, domListener} = findButtonsWithoutAction(dir);
if (cut) incomplete.push(folder);
if (domListener) notJudged.push(folder);
for (const button of found) {
const label =
button.label == null ? button.component : `"${button.label}"`;
if (button.note && PLACEHOLDER_HASH_LINK.test(button.note)) {
placeholders.push(`${folder}/${button.file} ${label}`);
continue;
}
buttons.push(
`${folder}/${button.file}:${button.line} ${label}${button.note ? ` (${button.note})` : ''}`,
);
}
}
return {buttons, placeholders: placeholders.sort(), incomplete, notJudged};
}

describe('templates and blocks', () => {
const pages = folders(path.join(templatesRoot, 'pages'));
// Every block folder, in each group under blocks/.
const blocks = folders(path.join(templatesRoot, 'blocks')).flatMap(folders);

it('finds the page template and block folders', () => {
expect(pages.length).toBeGreaterThan(20);
expect(blocks.length).toBeGreaterThan(100);
});

it("a block gives doctor's button check nothing to warn about", () => {
expect(report(blocks)).toEqual({
buttons: [],
placeholders: [],
incomplete: [],
notJudged: [],
});
}, 120_000);

it("a page template gives doctor's button check only its named placeholder links to warn about", () => {
expect(report(pages)).toEqual({
buttons: [],
placeholders: [...PLACEHOLDER_CALLS_TO_ACTION].sort(),
incomplete: [],
notJudged: NOT_JUDGED,
});
}, 120_000);
});
6 changes: 5 additions & 1 deletion packages/cli/assets/docs/tree/icon-sets.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,11 @@ export const docs = {
},
{
type: 'prose',
text: "An agent asks by meaning: `astryx experimental icon <words>`. The icon a set maps to the definition those words name comes first, from the project's main set before its backups, with the exact import line. Related icons stay findable by their own words and definitions and rank after it: `search` answers with the set's search icon first, while `find in document` answers with the icon for `documentSearch`. So ask for the job the icon does, take the first match, and paste its import. Templates work the same way: each declares the definition its icons draw, so a project that switches sets gets the new set's icon for every definition that set maps.",
text: "An agent asks by meaning: `astryx experimental icon <words>`. The icon a set maps to the definition those words name comes first, from the project's main set before its backups, with the exact import line. Related icons stay findable by their own words and definitions and rank after it: `search` answers with the set's search icon first, while `find in document` answers with the set's icon for `documentSearch`, where the set maps one. So ask for the job the icon does, take the first match, and paste its import. Templates work the same way: each declares the definition its icons draw, so a project that switches sets gets the new set's icon for every definition that set maps.",
},
{
type: 'prose',
text: 'Related meanings belong to a `group`, such as `notifications` for `notification`, `notificationActive` and `notificationOff`. A match in `astryx experimental icon` lists the other meanings of its group as `relatives`, so an agent that asked for the bell sees that "mute" has a meaning of its own; a group never changes which icon comes first. A meaning can also declare `replaces`, naming an older meaning it takes the place of: the old name keeps answering, in an icon set\'s `map`, in a template\'s `icons` and in the search, and `integration check` names each `map` key to rename. A meaning your icon set adds may join an Astryx group or start its own, and may replace another of your own meanings, never an Astryx one.',
},
{
type: 'prose',
Expand Down
Loading