bestax-migrate 2.27.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/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"}

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

@@ -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`)
@@ -21,9 +22,10 @@ import { addTodo, findAttr, forgetJsxParens, jsxNameParts, literalValueOf, makeA
 import { collectBoundNames, makeReserve, prefersTabs, resolvesToBinding, } from '../_shared/imports.js';
 import { rewriteStylesheetImports } from '../_shared/css-imports.js';
 import { BESTAX, buildBestaxImport, placeBestaxImport, seedBestaxImport, } from '../_shared/bestax-import.js';
+import { glyphProps } from './glyph.js';
 import { fileContextTodo, plan, } from './plan.js';
 import { REACT_RUNTIMES, } from './project.js';
-import { PLACED, placedFor, ROOTS, rootFor } from './class-map.js';
+import { PLACED, placedFor, ROOTS, rootFor, WRAPPERS, } from './class-map.js';
 import { ruleId } from './rules.js';
 /**
  * A part imported under its flat export (`MenuList`, `FieldLabel`) is the
@@ -103,13 +105,25 @@ function spliceClassName(element, replacement, carried = []) {
     }
     attrs.splice(attrs.indexOf(classAttr), 1, ...replacement);
 }
-/** Put `props`, then what stays in `className`, where `className` was. */
-function writeClassName(j, element, props, className) {
-    const replacement = props.map(([name, value]) => makeAttr(j, name, value === true ? undefined : value));
+/**
+ * Put `lead`, then `props`, then what stays in `className`, where
+ * `className` was.
+ */
+function writeClassName(j, element, props, className, lead = []) {
+    const replacement = [
+        ...lead,
+        ...props.map(([name, value]) => makeAttr(j, name, value === true ? undefined : value)),
+    ];
     if (className)
         replacement.push(makeAttr(j, 'className', className));
     spliceClassName(element, replacement);
 }
+/** A glyph's props as JSX attributes, a list of features as an array. */
+function glyphAttributes(j, glyph) {
+    return glyphProps(glyph).map(([name, value]) => typeof value === 'string'
+        ? makeAttr(j, name, value)
+        : j.jsxAttribute(j.jsxIdentifier(name), j.jsxExpressionContainer(propValue(j, value, false))));
+}
 /**
  * The same, for a `className` a joiner builds: the classes a prop now
  * renders leave the call, each condition that became a prop moves onto it,
@@ -117,7 +131,7 @@ function writeClassName(j, element, props, className) {
  * conditional, no `className` when nothing is left). Returns whether the
  * call is gone.
  */
-function writeJoined(j, element, conversion, joined) {
+function writeJoined(j, element, conversion, joined, lead = []) {
     const { call, statics, parts } = joined;
     const kept = new Set(conversion.className?.split(' ') ?? []);
     const carried = [];
@@ -164,6 +178,7 @@ function writeJoined(j, element, conversion, joined) {
             classes.length > 0 ? [makeAttr(j, 'className', classes.join(' '))] : [];
     }
     spliceClassName(element, [
+        ...lead,
         ...conversion.props.map(([name, value]) => makeAttr(j, name, value === true ? undefined : value)),
         ...conditions,
         ...rest,
@@ -734,6 +749,83 @@ function staticContent(element) {
                 child.expression.type === 'StringLiteral' &&
                 child.expression.value !== '')));
 }
+/** The static classes of a plain HTML element, or undefined. */
+function htmlTokens(element) {
+    const name = element?.openingElement?.name;
+    if (name?.type !== 'JSXIdentifier' || !INTRINSIC.test(name.name)) {
+        return undefined;
+    }
+    const classAttr = findAttr(element, 'className');
+    const className = classAttr ? staticClassName(classAttr) : '';
+    return className === null
+        ? undefined
+        : className.split(/\s+/).filter(Boolean);
+}
+/** Whether a component builds content from props rather than children. */
+function buildsContent(entry) {
+    return (!!entry &&
+        (!!entry.buildsIcons ||
+            !!entry.buildsFile ||
+            entry.rendersText !== undefined ||
+            !!entry.countsChildren ||
+            !!entry.absorbs));
+}
+/**
+ * What names a link or button, as `ElementFacts.clickableAround` says, with
+ * `self` left out of its content: its own `aria-labelledby` or `aria-label`,
+ * written out and not empty, else static text in it that is not inside an
+ * icon or hidden, else nothing. Undefined when it can't be told: a name or
+ * content written as an expression, a `title`, or something inside that may
+ * name it some other way (`kindOf` says which, or an `alt`, an `<svg>` or a
+ * label of its own).
+ */
+function labelOf(clickable, self, kindOf) {
+    if (findAttr(clickable, 'title'))
+        return undefined;
+    for (const name of ['aria-labelledby', 'aria-label']) {
+        const attr = findAttr(clickable, name);
+        if (!attr)
+            continue;
+        const value = attributeValue(attr);
+        if (value === null)
+            return undefined;
+        if (typeof value === 'string' && value.trim() !== '')
+            return name;
+    }
+    let unsure = false;
+    const named = (node) => (node.children ?? []).some((child) => {
+        if (child === self || dropped(child))
+            return false;
+        if (child.type === 'JSXText') {
+            return /\S/.test(jsxTextRenders(child.value));
+        }
+        if (child.type === 'JSXFragment')
+            return named(child);
+        if (child.type !== 'JSXElement') {
+            if (isContent(child))
+                unsure = true;
+            return false;
+        }
+        const kind = kindOf(child);
+        if (kind === 'icon')
+            return false;
+        if (kind === 'opaque') {
+            unsure = true;
+            return false;
+        }
+        const hidden = findAttr(child, 'aria-hidden');
+        if (hidden && attributeValue(hidden) === 'true')
+            return false;
+        if (['alt', 'title', 'aria-label', 'aria-labelledby'].some(name => findAttr(child, name)) ||
+            child.openingElement.name.name === 'svg') {
+            unsure = true;
+        }
+        return named(child);
+    });
+    if (named(clickable))
+        return 'text';
+    return unsure ? undefined : 'none';
+}
 /**
  * An element's content as one prop value: its one element, or its text, or
  * a fragment of them all, each text written as the string it renders.
@@ -1012,6 +1104,121 @@ export default function transform(fileInfo, api, options = {}) {
         readings.set(child, reading);
         return reading;
     };
+    // A bestax component already in the file is read as the markup the table
+    // says it renders, so a TODO that reads what is around an element says the
+    // same once the elements around it have converted.
+    /** The table's entry for a bestax component, with its root class. */
+    const entryFor = (target) => {
+        const root = target &&
+            Object.keys(ROOTS).find(key => ROOTS[key].status === 'mapped' && ROOTS[key].target === target);
+        return root ? { root, entry: ROOTS[root] } : undefined;
+    };
+    /**
+     * The classes an element renders, as far as the file shows: a plain HTML
+     * element's static ones, or a bestax component's root class and the flags
+     * written out as `true` (`<Control hasIconsLeft>` as `control
+     * has-icons-left`).
+     */
+    const renderedTokens = (path) => {
+        const html = htmlTokens(path.node);
+        if (html)
+            return html;
+        const found = entryFor(bestaxTarget(path.node, path));
+        if (!found)
+            return undefined;
+        const flags = Object.entries(found.entry.modifiers ?? {})
+            .filter(([, modifier]) => {
+            const [write, ...more] = modifier.writes;
+            const attr = write && more.length === 0 && write.value === undefined
+                ? findAttr(path.node, write.prop)
+                : undefined;
+            return attr && attributeValue(attr) === true;
+        })
+            .map(([token]) => token);
+        return [found.root, ...flags];
+    };
+    /**
+     * The tag an element renders: its own, or a bestax component's, from a
+     * static `as` or the table; an empty string for a bestax component whose
+     * tag the table doesn't give, and undefined for any other component.
+     */
+    const renderedTag = (path) => {
+        const name = path.node.openingElement.name;
+        if (name.type === 'JSXIdentifier' && INTRINSIC.test(name.name)) {
+            return name.name;
+        }
+        const target = bestaxTarget(path.node, path);
+        if (!target)
+            return undefined;
+        const as = findAttr(path.node, 'as');
+        if (as) {
+            const value = attributeValue(as);
+            return typeof value === 'string' ? value : undefined;
+        }
+        return (entryFor(target)?.entry.tag ??
+            Object.keys(WRAPPERS).find(tag => WRAPPERS[tag] === target) ??
+            '');
+    };
+    /**
+     * Where an element whose target renders a glyph sits, for its TODO: the
+     * classes the element directly around it renders, and the nearest <a> or
+     * <button> around it, reached through markup and bestax components only,
+     * since any other component between could render anything, with what
+     * names that.
+     */
+    const glyphPlace = (elementPath) => {
+        const parent = elementPath.parent;
+        const parentTokens = parent?.node?.type === 'JSXElement' ? renderedTokens(parent) : undefined;
+        let clickable;
+        let tag;
+        for (let up = elementPath.parent; up && !clickable; up = up.parent) {
+            if (up.node?.type !== 'JSXElement')
+                continue;
+            tag = renderedTag(up);
+            if (tag === undefined)
+                break;
+            if (tag === 'a' || tag === 'button')
+                clickable = up;
+        }
+        const kindOf = (element) => {
+            const tokens = htmlTokens(element);
+            const entries = tokens
+                ? tokens.map(token => rootFor(token)).filter(Boolean)
+                : [entryFor(bestaxTarget(element, clickable))?.entry];
+            if (!tokens && !bestaxTarget(element, clickable))
+                return 'opaque';
+            if (entries.some(entry => entry?.readsGlyph))
+                return 'icon';
+            return entries.some(buildsContent) ? 'opaque' : 'open';
+        };
+        const label = clickable && labelOf(clickable.node, elementPath.node, kindOf);
+        return {
+            ...(parentTokens && { parentTokens }),
+            ...(clickable && {
+                clickableAround: { tag: tag, ...(label && { label }) },
+            }),
+        };
+    };
+    /**
+     * An element that goes with the one around it, which renders it from
+     * props, converts no more on its own, and nor does it when that one stays
+     * markup for a person: a re-run has to find the markup it found. Only its
+     * TODOs stay. It has a class to be found by, so it has been planned.
+     */
+    const forget = (node) => {
+        const own = { conversion: null, todos: planned.get(node).todos };
+        planned.set(node, own);
+        readings.delete(node);
+        const at = elements.findIndex(found => found.path.node === node);
+        if (at === -1)
+            return;
+        if (own.todos.length > 0) {
+            elements[at] = { ...elements[at], plan: own, converts: false };
+        }
+        else {
+            elements.splice(at, 1);
+        }
+    };
     /** The element directly around this one, when this is its only child. */
     const holderOf = (elementPath) => {
         const up = elementPath.parent?.node;
@@ -1065,6 +1272,9 @@ export default function transform(fileInfo, api, options = {}) {
             }),
             ...(textOf(element) !== undefined && { text: textOf(element) }),
         };
+        if (facts.tokens.some(token => rootFor(token)?.readsGlyph)) {
+            Object.assign(facts, glyphPlace(elementPath));
+        }
         // A joiner call the codemod can read converts exactly: its fixed classes
         // as for a static className, and each condition on a flag as its prop.
         const joined = className === null
@@ -1085,6 +1295,7 @@ export default function transform(fileInfo, api, options = {}) {
         }
         let result = exact ?? plan(facts);
         const builds = result.conversion?.icons;
+        const glyphs = result.conversion?.glyph !== undefined;
         const converts = result.conversion !== null || result.fold !== undefined;
         const becomes = result.conversion?.target ?? result.fold?.target;
         if (className === null && !exact && becomes) {
@@ -1117,27 +1328,14 @@ export default function transform(fileInfo, api, options = {}) {
             inner.numbers.push(...result.fold.numbers);
         }
         if (builds) {
-            // A `.icon` the target builds from props goes with the element, so it
-            // doesn't convert on its own, and nor does it when a computed
-            // `className` leaves the element to a person: a re-run has to find
-            // the markup it found.
+            // A `.icon` the target builds from props goes with the element.
             const inside = (element.children ?? []).filter((child) => !dropped(child));
-            for (const icon of builds) {
-                const node = inside[icon.index];
-                const own = { conversion: null, todos: planned.get(node).todos };
-                planned.set(node, own);
-                readings.delete(node);
-                const at = elements.findIndex(found => found.path.node === node);
-                if (at === -1)
-                    continue;
-                if (own.todos.length > 0) {
-                    elements[at] = { ...elements[at], plan: own, converts: false };
-                }
-                else {
-                    elements.splice(at, 1);
-                }
-            }
+            for (const icon of builds)
+                forget(inside[icon.index]);
         }
+        // So does the <i> a glyph the target renders takes the place of.
+        if (glyphs)
+            forget(sole);
         planned.set(element, result);
         if (result.conversion || result.fold || result.todos.length > 0) {
             elements.unshift({ path: elementPath, plan: result, converts });
@@ -1313,16 +1511,14 @@ export default function transform(fileInfo, api, options = {}) {
             }
         }
         // A target that renders the element's children itself takes their place:
-        // they go, and so does the closing tag, their comments and its own moving
-        // to the name that stays.
+        // they go, and so does the closing tag, their comments (in their tags
+        // and attributes too: a glyph's <i> has a `className`) and its own
+        // moving to the name that stays.
         const gone = conversion.rendersChildren
             ? [
                 ...(element.children ?? [])
                     .filter((node) => node.type === 'JSXElement')
-                    .flatMap((node) => [
-                    ...(node.comments ?? []),
-                    ...tagComments(node),
-                ]),
+                    .flatMap((node) => commentsWithin(node)),
                 ...[element.closingElement, element.closingElement?.name].flatMap((node) => node?.comments ?? []),
             ]
             : [];
@@ -1333,10 +1529,12 @@ export default function transform(fileInfo, api, options = {}) {
             removeAttr(holder, findAttr(holder, name));
         }
         const joined = joins.get(element);
+        // A glyph the target renders goes first, as the planner wrote it.
+        const lead = conversion.glyph ? glyphAttributes(j, conversion.glyph) : [];
         if (!joined) {
-            writeClassName(j, element, conversion.props, conversion.className);
+            writeClassName(j, element, conversion.props, conversion.className, lead);
         }
-        else if (writeJoined(j, element, conversion, joined)) {
+        else if (writeJoined(j, element, conversion, joined, lead)) {
             unjoined.add(joined.call.callee.name);
         }
         if (conversion.rendersChildren) {

package/dist/sources/rbx/mapping.d.ts

@@ -13,6 +13,16 @@
  * explicit conversions rather than guesses.
  */
 import type { ComponentMapping, PropAction } from '../../types.js';
+/**
+ * Components whose bestax counterpart really does accept `as`. An empty
+ * action passes the prop through untouched; its job is to claim the name so
+ * the universal `AS_TODO` never sees it.
+ *
+ * Several of these narrow `as` to a literal union (`Footer` is
+ * `'footer' | 'div'`, `Control` is `'div'`), so an `as={SomeComponent}` still
+ * surfaces — as a type error the user can see, rather than a silent rewrite.
+ */
+export declare const AS_OK: PropAction;
 /**
  * Helper props rbx mixes into every component via `HelpersProps`. Applied
  * after each component's own prop map, to whatever attributes are left.

package/dist/sources/rbx/mapping.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mapping.d.ts","sourceRoot":"","sources":["../../../src/sources/rbx/mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AA+BnE;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CA4CtD,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAOrD,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAQvD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAShE,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAitBpD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CA2FhD,CAAC;AAEF,sDAAsD;AACtD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,gBAAgB,GAAG,SAAS,CAM3E"}
+{"version":3,"file":"mapping.d.ts","sourceRoot":"","sources":["../../../src/sources/rbx/mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAoBnE;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,EAAE,UAAe,CAAC;AAEpC;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CA4CtD,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAOrD,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAQvD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAShE,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAutBpD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CA2FhD,CAAC;AAEF,sDAAsD;AACtD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,gBAAgB,GAAG,SAAS,CAM3E"}