bestax-migrate 2.26.0 → 2.28.0

package/dist/sources/bulma-classes/plan.js

@@ -7,10 +7,14 @@
  * renders exactly the markup the element did. Anything that would change the
  * markup is either left in `className` (a class with no prop here) or refuses
  * the whole element with a TODO (an attribute or tag the component would
- * render differently).
+ * render differently). One exception, on purpose: Font Awesome's own
+ * `<i aria-hidden="true">` alone in a `.icon` that carries nothing assistive
+ * tech reads (the table's `hiddenMovesBeside`) converts to `Icon`, which writes that attribute
+ * on the `.icon` instead (`movesHidden`), since the glyph is hidden either
+ * way.
  */
 import { FORWARDS_REF, HELPER_PROPS, HELPER_TOKENS, inTagSet, legacyHint, modifierFor, numberAttrsOf, placedFor, PRECEDENCE, rootFor, WRAPPER_OWN_PROPS, wrapperFor, } from './class-map.js';
-import { readGlyph } from './glyph.js';
+import { glyphProps, readDrawnGlyph, readGlyph, readHiddenGlyph, } from './glyph.js';
 import { ruleId } from './rules.js';
 /** The button text `File` renders when it's given none. */
 const DEFAULT_FILE_LABEL = 'Choose a file\u2026';
@@ -227,7 +231,19 @@ export function plan(facts) {
         : naming === 'unsure'
             ? { ...unnamed, ...entry.namedDefaults.defaults }
             : unnamed;
-    const missing = [...Object.entries(defaults), ...written].filter(([name]) => !attributes.has(name));
+    // Font Awesome's own markup hides the <i> rather than the element around
+    // it, and a target that renders the glyph from props writes the same
+    // `aria-hidden` on the element in its place: it moves up, and the glyph is
+    // hidden either way. The one difference in markup a conversion makes, on
+    // purpose; the render tests compare it with the attribute moved up. Only
+    // onto an element that carries nothing assistive tech reads, by name and
+    // whatever the value: an expression may render as anything.
+    const moved = entry.readsGlyph &&
+        defaults['aria-hidden'] === 'true' &&
+        [...attributes.keys()].every(name => movesBeside(entry, name))
+        ? readHiddenGlyph(facts.soleChild)
+        : undefined;
+    const missing = [...Object.entries(defaults), ...written].filter(([name]) => !attributes.has(name) && !(moved && name === 'aria-hidden'));
     const drop = [];
     for (const name of entry.untypedAttrs ?? []) {
         if (!attributes.has(name))
@@ -316,7 +332,10 @@ export function plan(facts) {
     }
     if (missing.length > 0) {
         const list = missing.map(([name, value]) => `\`${name}="${value}"\``);
-        return refuse('defaults', target, `bestax \`${target}\` renders ${list.join(' and ')} when the element does not set ${missing.length === 1 ? 'it' : 'them'}; add ${missing.length === 1 ? 'it' : 'them'} here if that is what you want, then re-run`);
+        const usual = `bestax \`${target}\` renders ${list.join(' and ')} when the element does not set ${missing.length === 1 ? 'it' : 'them'}; add ${missing.length === 1 ? 'it' : 'them'} here if that is what you want, then re-run`;
+        return refuse('defaults', target, entry.readsGlyph && naming === 'unnamed'
+            ? hiddenAdvice(facts, entry, usual)
+            : usual);
     }
     for (const [name, rule] of Object.entries(entry.writesAttr ?? {})) {
         const value = attributes.get(name);
@@ -326,8 +345,14 @@ export function plan(facts) {
             return refuse('attr', name, `bestax \`${target}\` keeps a <${tag}>'s \`${name}\` only as ${orList(rule.keeps)}, and writes \`${name}="${rule.fallback}"\` in place of anything else, so this one converts only ${rule.implicit ? `with no \`${name}\` or as one of those` : 'as one of those, written out'}; keep this element as markup`);
         }
     }
+    // Only on a tag the target renders: on any other, the tag check below is
+    // the refusal, and a `drops` one would call an attribute inert that may not
+    // be (`type` on a <button>) and promise a conversion a re-run still refuses.
+    const tagReached = tag === entry.tag ||
+        entry.as === 'any' ||
+        (entry.as?.includes(tag) ?? false);
     for (const [name, tags] of Object.entries(entry.dropsAttr ?? {})) {
-        if (attributes.has(name) && inTagSet(tags, tag)) {
+        if (tagReached && attributes.has(name) && inTagSet(tags, tag)) {
             // Bulma greys out `.button[disabled]` on any tag, so there it is not
             // inert: dropping it changes how the element looks.
             const visible = name === 'disabled' && target === 'Button';
@@ -353,9 +378,6 @@ export function plan(facts) {
     if (renders !== tag) {
         const reachable = entry.as === 'any' || (entry.as?.includes(tag) ?? false);
         if (!reachable) {
-            if (entry.otherTagsStay?.tags.includes(tag)) {
-                return { conversion: null, todos };
-            }
             return refuse('tag', target, `bestax \`${target}\` renders ${tagsItReaches(entry)}, not a <${tag}>; keep the markup, or change the tag and re-run`);
         }
         as = tag;
@@ -441,6 +463,8 @@ export function plan(facts) {
     if (entry.classNameReplaces && (rest.length > 0 || conditionalStays)) {
         return refuse('attr', 'className', `bestax \`${target}\` writes a \`className\` it's given in place of \`.${root}\`, so this converts only with no other class; keep it as markup`);
     }
+    // A glyph the target renders from props takes the place of the only child.
+    const glyph = moved ?? (entry.readsGlyph ? readGlyph(facts.soleChild) : undefined);
     return {
         conversion: {
             target,
@@ -449,9 +473,11 @@ export function plan(facts) {
             drop,
             numbers,
             ...(absorbed ? { absorbs: absorbed } : {}),
-            ...(counts || entry.rendersText !== undefined
+            ...(counts || entry.rendersText !== undefined || glyph
                 ? { rendersChildren: true }
                 : {}),
+            ...(glyph ? { glyph } : {}),
+            ...(moved ? { movesHidden: true } : {}),
             ...(parent ? { replacesParent: true } : {}),
             ...(conditional.length > 0 ? { conditional } : {}),
             ...(icons ? { icons } : {}),
@@ -555,6 +581,128 @@ function namingOf(entry, attributes) {
     }
     return given.includes(null) ? 'unsure' : 'unnamed';
 }
+/**
+ * Whether an element may carry `name` and still take Font Awesome's
+ * `aria-hidden` up off its <i>, by the table's `hiddenMovesBeside`, where a
+ * name ending in `*` stands for every attribute it starts.
+ */
+function movesBeside(entry, name) {
+    return (entry.readsGlyph?.hiddenMovesBeside ?? []).some(allowed => allowed.endsWith('*')
+        ? name.startsWith(allowed.slice(0, -1))
+        : name === allowed);
+}
+/**
+ * What to do about an unnamed element whose target hides it with an
+ * `aria-hidden` it doesn't carry, and that renders a glyph from props
+ * (`Icon`), for its `defaults` TODO: from what it holds (Font Awesome's own
+ * `<i aria-hidden>`, the `<svg>` its script draws) and where it sits (a
+ * link or button its label names, or one nothing names). Each says what a
+ * re-run converts it to once the attribute is in place, when that's sure,
+ * and inside a `.control` with icons, the `Control` prop that renders it.
+ * `usual` is the message for anything else.
+ */
+function hiddenAdvice(facts, entry, usual) {
+    const target = entry.target;
+    const sole = facts.soleChild;
+    // Font Awesome's own markup hides the <i>, not the `.icon` around it.
+    const flag = sole?.attributes.get('aria-hidden');
+    const hiddenFont = sole?.tag === 'i' && (flag === 'true' || flag === true);
+    const drawn = readDrawnGlyph(sole);
+    // The element as a re-run would find it, the attribute in place (moved up
+    // off the <i> that carries it): the planner says what that converts to.
+    const attributes = new Map(facts.attributes).set('aria-hidden', 'true');
+    const retry = plan({
+        ...facts,
+        attributes,
+        ...(hiddenFont && {
+            soleChild: {
+                ...sole,
+                attributes: new Map([...sole.attributes].filter(([name]) => name !== 'aria-hidden')),
+            },
+        }),
+    }).conversion;
+    // Only where nothing in it converts on its own, which would change what a
+    // re-run finds: an <i> the glyph takes the place of, or an <svg>.
+    const outcome = retry?.glyph
+        ? `, and this converts to \`${target}\` with ${jsxProps(glyphProps(retry.glyph))}`
+        : retry && sole?.tag === 'svg'
+            ? `, and this converts to \`${target}\` around the <svg> as it is`
+            : '';
+    const hint = controlHint(facts, retry, retry?.glyph ?? drawn);
+    // A bare <i> naming a glyph moves it up by itself, onto an element that
+    // carries nothing else assistive tech reads, so this one carries more.
+    const exposed = readHiddenGlyph(sole)
+        ? [...facts.attributes.keys()].find(name => !movesBeside(entry, name))
+        : undefined;
+    if (exposed) {
+        return `bestax \`${target}\` takes Font Awesome's \`aria-hidden\` up off a bare <i> like this one only onto a \`.icon\` that carries nothing assistive tech reads, and this one carries \`${exposed}\`, which the move would hide, or, beside a \`role\` or \`tabIndex\`, leave with no \`aria-hidden\` at all; if the icon means something, give the \`.icon\` an \`aria-label\` and \`role="img"\`, and if it is decoration, drop \`${exposed}\`, then re-run`;
+    }
+    if (hiddenFont) {
+        // A bare <i> naming a glyph moves it up by itself, so this one isn't.
+        return `bestax \`${target}\` writes \`aria-hidden="true"\` on the \`.icon\`, and takes it from the <i> inside only when that <i> is empty, carries nothing else and names a glyph it renders from props, which this one doesn't; the \`.icon\` holds nothing else, so the attribute hides the same glyph there: move it up onto the \`.icon\`, then re-run${outcome}${hint}`;
+    }
+    if (drawn) {
+        return `this \`.icon\` holds the <svg> Font Awesome's script draws in place of an <i>, and bestax \`${target}\` writes \`aria-hidden="true"\` on the \`.icon\`, which this one doesn't carry; add it, then re-run${outcome}; or write \`${target}\` with ${jsxProps(glyphProps(drawn))} in its place, which renders the <i> the script draws from, and shows only where Font Awesome's stylesheet or script is loaded${hint}`;
+    }
+    const around = facts.clickableAround;
+    const label = around?.label;
+    const tag = around && `${/^[aeiou]/.test(around.tag) ? 'an' : 'a'} <${around.tag}>`;
+    if (label && label !== 'none') {
+        const by = label === 'text' ? 'its own text' : `its \`${label}\``;
+        return `this \`.icon\` sits in ${tag} that ${by} names, so the icon is decoration there, and bestax \`${target}\` writes \`aria-hidden="true"\` on an icon with no name of its own, which this one doesn't carry; add it, then re-run${outcome}${hint}`;
+    }
+    if (label === 'none' && readGlyph(sole)) {
+        return `nothing names the <${around.tag}> around this \`.icon\`: it has no \`aria-label\` and no text outside its icons, and a font icon's glyph is no name a screen reader can read; give the <${around.tag}> an \`aria-label\` that says what it does, then add \`aria-hidden="true"\` here, which bestax \`${target}\` writes on an icon with no name of its own, and re-run${outcome}${hint}`;
+    }
+    return `${usual}${outcome}${hint}`;
+}
+/**
+ * Inside a `.control` with icons on this element's side, the `Control` prop
+ * that renders the element once it's hidden as `converted` is: given the
+ * glyph, the props its classes write and nothing else, since `Control`
+ * writes the side's own class over any `className` it's given. Empty when
+ * the element carries anything more: another class, an attribute of its own
+ * or a class a condition adds.
+ */
+function controlHint(facts, converted, glyph) {
+    const side = converted?.className === 'is-left'
+        ? 'Left'
+        : converted?.className === 'is-right'
+            ? 'Right'
+            : undefined;
+    const has = `has-icons-${side?.toLowerCase()}`;
+    if (!glyph ||
+        !side ||
+        facts.conditional?.length ||
+        !facts.parentTokens?.includes('control') ||
+        !facts.parentTokens.includes(has) ||
+        facts.attributes.size > 0) {
+        return '';
+    }
+    const object = [...glyphProps(glyph), ...converted.props]
+        .map(([name, value]) => `${name}: ${value === true
+        ? 'true'
+        : converted.numbers.includes(name)
+            ? String(Number(value))
+            : valueText(value)}`)
+        .join(', ');
+    return `; or, since the \`.control\` around it has \`${has}\`, drop this \`.icon\` and give that \`Control\` \`icon${side}={{ ${object} }}\`, which it renders after its children as a \`.icon.is-${side.toLowerCase()}\` around the glyph's <i>, hidden the way \`Icon\` hides it`;
+}
+/** A glyph's props as JSX attributes, for a message. */
+function jsxProps(props) {
+    const text = props
+        .map(([name, value]) => typeof value === 'string'
+        ? `${name}="${value}"`
+        : `${name}={${valueText(value)}}`)
+        .join(' ');
+    return `\`${text}\``;
+}
+/** A prop's value as code, for a message: a list as an array of strings. */
+function valueText(value) {
+    return typeof value === 'string'
+        ? JSON.stringify(value)
+        : `[${value.map(item => JSON.stringify(item)).join(', ')}]`;
+}
 /**
  * The icons a target that `buildsIcons` builds from an element's children:
  * each `.icon` that converts to `Icon` on its own and holds a glyph `Icon`
@@ -583,25 +731,13 @@ function buildIcons(children, target) {
             const loose = [...child.attributes.keys()].some(name => name === 'key' ||
                 name === 'ref' ||
                 (name.includes('-') && !name.startsWith('aria-')));
-            const glyph = readGlyph(child.soleChild);
+            // The `.icon` read its glyph itself when it converted on its own.
+            const glyph = icon.glyph;
             if (!glyph || loose)
                 return { why: shape };
-            const props = [
-                ['library', glyph.library],
-                ['name', glyph.name],
-            ];
-            if (glyph.variant)
-                props.push(['variant', glyph.variant]);
-            const { features } = glyph;
-            if (features) {
-                props.push([
-                    'features',
-                    features.length === 1 ? features[0] : features,
-                ]);
-            }
             icons.push({
                 index,
-                props: [...props, ...icon.props],
+                props: [...glyphProps(glyph), ...icon.props],
                 className: icon.className,
                 drop: icon.drop,
                 numbers: icon.numbers,

package/dist/sources/bulma-classes/project.d.ts

@@ -2,7 +2,8 @@
  * What the bulma-classes transform needs to know about the project and cannot
  * see from one file: which files a Next.js App Router may render as server
  * components, which packages render JSX through a runtime other than React,
- * and which are written in TypeScript, for the module an HTML page becomes.
+ * and, for the module an HTML page becomes, which are written in TypeScript
+ * and which are Next.js apps, where that module imports no stylesheet.
  *
  * Read once per run, from every package.json the run touches: the nearest one
  * above each target, and every one below it, so a monorepo run from its root
@@ -26,11 +27,16 @@ export interface ServerComponentRoot {
     dir: string;
     except: string[];
 }
-/** A package, and whether a module it gains should be TypeScript. */
+/** A package, and what a module it gains should be written for. */
 export interface PackageLanguage {
     dir: string;
     /** It has a `tsconfig.json`, or depends on `typescript`. */
     typescript: boolean;
+    /**
+     * It depends on `next`, whose Pages Router takes a global stylesheet only
+     * in `pages/_app`, so a page's module imports none there.
+     */
+    nextjs?: boolean;
 }
 export interface ProjectFacts {
     serverComponentRoots: ServerComponentRoot[];
@@ -49,4 +55,6 @@ export declare function analyzeProject(targets: string[]): ProjectFacts;
  * innermost package around it says, and no when no package does.
  */
 export declare function writesTypeScript(file: string, languages: unknown): boolean;
+/** Whether the innermost package around `file` is a Next.js app. */
+export declare function inNextApp(file: string, languages: unknown): boolean;
 //# sourceMappingURL=project.d.ts.map

package/dist/sources/bulma-classes/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../../src/sources/bulma-classes/project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,qDAAqD;AACrD,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAK7C,CAAC;AAqBH,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,oBAAoB,EAAE,mBAAmB,EAAE,CAAC;IAC5C,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,gBAAgB,EAAE,eAAe,EAAE,CAAC;CACrC;AA2GD;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GACjD,MAAM,GAAG,IAAI,CAKf;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,YAAY,CAsD9D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAO1E"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../../src/sources/bulma-classes/project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,qDAAqD;AACrD,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAK7C,CAAC;AAqBH,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,UAAU,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,oBAAoB,EAAE,mBAAmB,EAAE,CAAC;IAC5C,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,gBAAgB,EAAE,eAAe,EAAE,CAAC;CACrC;AA2GD;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GACjD,MAAM,GAAG,IAAI,CAKf;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,YAAY,CAuD9D;AAcD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAE1E;AAED,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAEnE"}

package/dist/sources/bulma-classes/project.js

@@ -2,7 +2,8 @@
  * What the bulma-classes transform needs to know about the project and cannot
  * see from one file: which files a Next.js App Router may render as server
  * components, which packages render JSX through a runtime other than React,
- * and which are written in TypeScript, for the module an HTML page becomes.
+ * and, for the module an HTML page becomes, which are written in TypeScript
+ * and which are Next.js apps, where that module imports no stylesheet.
  *
  * Read once per run, from every package.json the run touches: the nearest one
  * above each target, and every one below it, so a monorepo run from its root
@@ -206,20 +207,28 @@ export function analyzeProject(targets) {
             dir,
             typescript: Boolean(deps.typescript) ||
                 fs.existsSync(path.join(dir, 'tsconfig.json')),
+            nextjs: Boolean(deps.next),
         });
     }
     return facts;
 }
+/** The innermost package around `file` of those the run read, if any. */
+function packageAround(file, languages) {
+    if (!Array.isArray(languages))
+        return undefined;
+    const resolved = path.resolve(file);
+    return languages
+        .filter(entry => resolved.startsWith(`${entry.dir}${path.sep}`))
+        .sort((a, b) => b.dir.length - a.dir.length)[0];
+}
 /**
  * Whether a new module beside `file` should be TypeScript: what the
  * innermost package around it says, and no when no package does.
  */
 export function writesTypeScript(file, languages) {
-    if (!Array.isArray(languages))
-        return false;
-    const resolved = path.resolve(file);
-    const found = languages
-        .filter(entry => resolved.startsWith(`${entry.dir}${path.sep}`))
-        .sort((a, b) => b.dir.length - a.dir.length)[0];
-    return found?.typescript ?? false;
+    return packageAround(file, languages)?.typescript ?? false;
+}
+/** Whether the innermost package around `file` is a Next.js app. */
+export function inNextApp(file, languages) {
+    return packageAround(file, languages)?.nextjs ?? false;
 }

package/dist/sources/bulma-classes/transform.d.ts

@@ -4,7 +4,8 @@
  * Unlike the library sources there is no import to anchor on: a file is in
  * scope when a lowercase JSX element carries a `className` with a Bulma class
  * `class-map.ts` knows. Each such element goes through `plan()`, which
- * converts it only when the component renders exactly the same markup.
+ * converts it only when the component renders exactly the same markup, but
+ * for the one exception it states (Font Awesome's hidden `<i>`).
  *
  * Passes, in order:
  *   1. the shared stylesheet-import pass (a no-op under the default `keep`)

package/dist/sources/bulma-classes/transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../../src/sources/bulma-classes/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAW,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AA26BvD,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,GAAG,EACR,OAAO,GAAE,gBAAqB,GAC7B,MAAM,GAAG,SAAS,CA02BpB"}
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../../src/sources/bulma-classes/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAW,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAkiCvD,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,GAAG,EACR,OAAO,GAAE,gBAAqB,GAC7B,MAAM,GAAG,SAAS,CAs9BpB"}