diff --git a/bestax-mcp/data/components/File.json b/bestax-mcp/data/components/File.json index 8095c2237..6b13c1dd1 100644 --- a/bestax-mcp/data/components/File.json +++ b/bestax-mcp/data/components/File.json @@ -173,7 +173,7 @@ "name": "hasName", "type": "boolean", "default": "false", - "description": "Show a file name area. Without `fileName` it shows what the user picked: the file's name, or a count when `multiple` lets them pick several (see `pickedFilesLabel`). Before a pick there is no name area. A reset of the input's form clears the name, but clearing the input from code fires no change event and leaves it showing, so pass `fileName` to control the text then.", + "description": "Show a file name area. Without `fileName` it shows what the user picked: the file's name, or a count when `multiple` lets them pick several (see `pickedFilesLabel`). Before a pick there is no name area, and the root takes Bulma's `is-empty`. A reset of the input's form clears the name, but clearing the input from code fires no change event and leaves it showing, so pass `fileName` to control the text then.", "required": false, "inherited": false, "deprecated": false diff --git a/bestax-mcp/data/skills.json b/bestax-mcp/data/skills.json index 9bc245941..bb4171f8f 100644 --- a/bestax-mcp/data/skills.json +++ b/bestax-mcp/data/skills.json @@ -103,7 +103,7 @@ { "id": "bulma-classes-component-map", "file": "references/bulma-classes/component-map.md", - "bytes": 24004 + "bytes": 24617 }, { "id": "bulma-classes-prop-map", @@ -113,7 +113,7 @@ { "id": "bulma-classes-unmappables", "file": "references/bulma-classes/unmappables.md", - "bytes": 23489 + "bytes": 23915 }, { "id": "css-migration", diff --git a/bestax-mcp/src/__tests__/bulma-classes-agree.test.ts b/bestax-mcp/src/__tests__/bulma-classes-agree.test.ts index 3c53498dd..6a8f9964e 100644 --- a/bestax-mcp/src/__tests__/bulma-classes-agree.test.ts +++ b/bestax-mcp/src/__tests__/bulma-classes-agree.test.ts @@ -127,7 +127,10 @@ function planned(tag: string, tokens: string[]): Outcome { counted = counts.prop; } // One that renders the whole `.file` tree holds it, inside a `.field`, - // which the lookup states as a condition. + // which the lookup states as a condition. Beside `has-name` the tree is + // the one the lookup's answer describes: with a name in it, unless + // Bulma's `is-empty` marks the slot empty, which `File` renders itself + // when it has no name and the lookup says so on that class's row. if (entry?.status === 'mapped' && entry.buildsFile && !childElements) { const bare = (tag: string, token: string, extra = {}) => ({ tag, @@ -152,6 +155,14 @@ function planned(tag: string, tokens: string[]): Outcome { }), ], }), + ...(tokens.includes('has-name') && !tokens.includes('is-empty') + ? [ + bare('span', 'file-name', { + staticContent: true, + text: 'cv.pdf', + }), + ] + : []), ], }), ]; @@ -368,6 +379,16 @@ describe('lookup_bulma_classes agrees with the codemod planner', () => { // own. The planner needs a tag, so it runs on that one: a heading's on

, // where its size is exact, and classes with no root on

, whose // Paragraph takes the same color props the no-tag answer names. + it('on a `.file` whose name slot is-empty marks, which File renders itself', () => { + const cases: Array<[string, string[]]> = [ + ['div', ['file', 'has-name', 'is-empty']], + ['div', ['file', 'has-name', 'is-empty', 'is-boxed', 'mt-2']], + // Without `has-name`, `File` renders no `is-empty`, so it stays a class. + ['div', ['file', 'is-empty']], + ]; + expect(compare(cases)).toEqual([]); + }); + it('with no tag, on the tag the component renders by itself', () => { const mismatches: string[] = []; const check = (tag: string, tokens: string[]) => { diff --git a/bestax-mcp/src/__tests__/server.test.ts b/bestax-mcp/src/__tests__/server.test.ts index 454ecf436..c071e43dd 100644 --- a/bestax-mcp/src/__tests__/server.test.ts +++ b/bestax-mcp/src/__tests__/server.test.ts @@ -984,6 +984,21 @@ describe('lookup_bulma_classes', () => { expect(out).toContain('bulma-classes-unmappables'); }); + it('says File renders is-empty itself beside has-name with no name', async () => { + // And that the name is pinned empty there, as the codemod writes it, so + // a pick shows no name where the markup shows none. + expect(await lookup('file has-name')).toContain( + 'With `hasName` and no `.file-name`, write `fileName=""`, so a file the user picks shows no name where the markup shows none. ' + + "It renders Bulma's `is-empty` there itself, so that class isn't needed." + ); + // The class's own row says the same, rather than keeping it as a class. + const out = await lookup('file has-name is-empty'); + expect(out).toContain( + '| `is-empty` | rendered by `File` | with no `.file-name` in the tree; beside one it stays in `className` |' + ); + expect(out).not.toMatch(/\| `is-empty` \| stays in `className` \|/); + }); + it('writes a prop typed as a number as a number', async () => { const out = await lookup('cell is-col-span-2', 'div'); expect(out).toContain('**Component:** `Cell`.'); diff --git a/bestax-mcp/src/bulma-classes.ts b/bestax-mcp/src/bulma-classes.ts index 1e7576300..3e175392a 100644 --- a/bestax-mcp/src/bulma-classes.ts +++ b/bestax-mcp/src/bulma-classes.ts @@ -173,6 +173,8 @@ export type Verdict = /** A family bestax converts as a whole, by hand. */ | { kind: 'family'; why: string } | { kind: 'prop'; writes: PropWrite[]; condition?: string } + /** A class the component renders itself, so it goes, on a condition. */ + | { kind: 'rendered'; target: string; condition: string } | { kind: 'class'; why: string }; export type Element = @@ -574,6 +576,22 @@ export function lookupClasses( }); } + // `File` renders Bulma's `is-empty` itself beside `hasName` while it has + // no name to show, so with no `.file-name` the class goes with the tree. + // The lookup can't see the tree, so the row says which tree it means. + if ( + entry.buildsFile && + writes.has('hasName') && + tokens.includes('is-empty') + ) { + verdicts.set('is-empty', { + kind: 'rendered', + target: target!, + condition: + 'with no `.file-name` in the tree; beside one it stays in `className`', + }); + } + let undone = false; /** Take a prop back, naming it: the class stays, but the prop is real. */ const undo = (prop: string, why: string) => { @@ -835,8 +853,11 @@ export function renderLookup(lookup: Lookup): string { `content as \`buttonLabel\` (left out for its default text), ` + `each \`.file-icon\`'s content as \`iconLeft\` or ` + `\`iconRight\`, and the \`.file-name\`'s text as \`fileName\` ` + - `beside \`hasName\`. Outside a \`Field\` it renders a ` + - `\`.field\` of its own around it.` + `beside \`hasName\`. With \`hasName\` and no \`.file-name\`, ` + + `write \`fileName=""\`, so a file the user picks shows no name ` + + `where the markup shows none. It renders Bulma's \`is-empty\` ` + + `there itself, so that class isn't needed. Outside a \`Field\` ` + + `it renders a \`.field\` of its own around it.` : '') + (element.topLevel ? ` It renders \`.${element.topLevel}\` only when no other ` + @@ -901,6 +922,12 @@ export function renderLookup(lookup: Lookup): string { verdict.writes.map(writeText).join(' '), verdict.condition ?? '', ]; + case 'rendered': + return [ + `\`${token}\``, + `rendered by \`${verdict.target}\``, + verdict.condition, + ]; case 'class': return [`\`${token}\``, 'stays in `className`', verdict.why]; } diff --git a/bestax-migrate/e2e/bulma-classes-props.test.ts b/bestax-migrate/e2e/bulma-classes-props.test.ts index 83778982e..80a535115 100644 --- a/bestax-migrate/e2e/bulma-classes-props.test.ts +++ b/bestax-migrate/e2e/bulma-classes-props.test.ts @@ -402,7 +402,8 @@ describe('every bulma-classes conversion typechecks', () => { ); } // The tree it renders from props: the 's attributes it takes as - // its own, its extra classes, the icons, the default text and a name. + // its own, its extra classes, the icons, the default text, a name and + // an empty name slot, its name pinned empty. if (entry.buildsFile) { const trees: FileTree[] = [ { label: 'Choose a file\u2026' }, @@ -441,6 +442,16 @@ describe('every bulma-classes conversion typechecks', () => { fileChildren({ name: 'cv.pdf' }) ) ); + add( + converted( + entry.tag!, + [root, 'has-name', 'is-empty'], + [], + undefined, + undefined, + fileChildren({}) + ) + ); } expect({ root, conversions: lines.length > 0 }).toEqual({ root, diff --git a/bestax-migrate/e2e/bulma-classes-truth.test.ts b/bestax-migrate/e2e/bulma-classes-truth.test.ts index 6cc34f10f..fc5428577 100644 --- a/bestax-migrate/e2e/bulma-classes-truth.test.ts +++ b/bestax-migrate/e2e/bulma-classes-truth.test.ts @@ -348,9 +348,13 @@ function factsFor( childElements: [iconChild(['fas', 'fa-home']), textChild()], }), // One that renders the whole `.file` tree holds that tree, inside a - // `.field`. + // `.field`, with a name in it beside `has-name`: with none, `File` renders + // Bulma's `is-empty` too, which the tree shapes below cover. ...(entries.some(entry => entry?.buildsFile) && { - childElements: fileChildren({ iconLeft: ['fas', 'fa-upload'] }), + childElements: fileChildren({ + iconLeft: ['fas', 'fa-upload'], + ...(tokens.includes('has-name') && { name: 'cv.pdf' }), + }), classesAround: ['field'], }), // One that needs element children holds one (`Icon` around an ). @@ -1202,7 +1206,11 @@ describe.each(mapped.filter(([, entry]) => entry.buildsFile))( input: { tabIndex: '0' }, }); same('with a name', { name: 'cv.pdf' }, ['has-name']); - same('with a name slot and no name', {}, ['has-name']); + same('with a name slot Bulma marks empty', {}, ['has-name', 'is-empty']); + same('with a name, and is-empty beside it', { name: 'cv.pdf' }, [ + 'has-name', + 'is-empty', + ]); same('with its modifiers together', { iconLeft: ['fas', 'fa-upload'] }, [ 'is-boxed', 'is-fullwidth', @@ -1211,6 +1219,16 @@ describe.each(mapped.filter(([, entry]) => entry.buildsFile))( 'mt-2', ]); }); + + it('leaves a name slot with no name and no is-empty as markup', () => { + // `File` would add the `is-empty` the markup doesn't have. + const facts: ElementFacts = { + ...factsFor(entry.tag!, [root, 'has-name']), + childElements: fileChildren({}), + classesAround: ['field'], + }; + expect(plan(facts).conversion).toBeNull(); + }); } ); diff --git a/bestax-migrate/src/sources/bulma-classes/__testfixtures__/file.input.tsx b/bestax-migrate/src/sources/bulma-classes/__testfixtures__/file.input.tsx index 453bce795..395f8dcb2 100644 --- a/bestax-migrate/src/sources/bulma-classes/__testfixtures__/file.input.tsx +++ b/bestax-migrate/src/sources/bulma-classes/__testfixtures__/file.input.tsx @@ -57,6 +57,28 @@ export function Uploads({ onPick }: { onPick: () => void }) { + {/* A name slot with nothing in it yet, which Bulma marks is-empty. */} +

+
+ +
+
+ {/* The same slot without is-empty, which File would add. */} +
+
+ +
+
{/* An attribute File would put on its input. */}
diff --git a/bestax-migrate/src/sources/bulma-classes/__testfixtures__/file.output.tsx b/bestax-migrate/src/sources/bulma-classes/__testfixtures__/file.output.tsx index 324e6e7db..87514c9cc 100644 --- a/bestax-migrate/src/sources/bulma-classes/__testfixtures__/file.output.tsx +++ b/bestax-migrate/src/sources/bulma-classes/__testfixtures__/file.output.tsx @@ -2,6 +2,7 @@ import { Field, File, Icon } from "@allxsmith/bestax-bulma"; export function Uploads({ onPick }: { onPick: () => void }) { // TODO(bestax-migrate): bestax `File` renders a `.field` of its own around the `.file` unless it sits inside a `Field`, and nothing around this element is one or becomes one here; keep it as markup, or convert the `.field` around it, then re-run // TODO(bestax-migrate): bestax `File` renders the whole `.file` tree itself, so this converts only when its tree is the one it renders: one bare `.file-label`
+ {/* A name slot with nothing in it yet, which Bulma marks is-empty. */} + + + + {/* The same slot without is-empty, which File would add. */} + +
+ +
+
{/* An attribute File would put on its input. */}
diff --git a/bestax-migrate/src/sources/bulma-classes/__tests__/component-map-doc.test.ts b/bestax-migrate/src/sources/bulma-classes/__tests__/component-map-doc.test.ts index 022f99c47..0fd3aadfd 100644 --- a/bestax-migrate/src/sources/bulma-classes/__tests__/component-map-doc.test.ts +++ b/bestax-migrate/src/sources/bulma-classes/__tests__/component-map-doc.test.ts @@ -3,13 +3,16 @@ * reaches agents through the MCP index and the create-bestax bundle), so it * must say what the table does. This holds its two tables to `ROOTS` and * `WRAPPERS`, and its lists of families and left-alone classes to the - * table's `todo` and `plain` roots. + * table's `todo` and `plain` roots. The recipe it gives for a `.file` with + * an empty name slot, which the unmappables reference repeats under that + * TODO, comes from the planner rather than the table, so it is held to `plan`. */ import fs from 'node:fs'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; import { ROOTS, WRAPPERS, type RootEntry } from '../class-map.js'; +import { plan, type ChildFacts, type ElementFacts } from '../plan.js'; const DOC = path.join( path.dirname(fileURLToPath(import.meta.url)), @@ -100,3 +103,121 @@ describe('the shipped bulma-classes component map matches the table', () => { } }); }); + +describe('the shipped .file recipe for a name slot with no name matches the planner', () => { + const unmappables = fs.readFileSync( + path.join(path.dirname(DOC), 'unmappables.md'), + 'utf8' + ); + + /** + * The paragraph in a heading's section that says `marker`, its lines + * joined, so rewrapping the prose moves nothing. + */ + function paragraph(text: string, heading: string, marker: string): string { + const start = text.indexOf(heading); + if (start === -1) return ''; + const end = text.indexOf('\n#', start + heading.length); + return ( + text + .slice(start, end === -1 ? undefined : end) + .split(/\n\s*\n/) + .map(lines => lines.replace(/\s+/g, ' ')) + .find(lines => lines.includes(marker)) ?? '' + ); + } + + const node = ( + tag: string, + tokens: string[], + extra: Partial = {} + ): ChildFacts => ({ + tag, + tokens, + attributes: new Map(), + hasSpread: false, + isEmpty: false, + ...extra, + }); + /** A `has-name` `.file` inside a `.field`, with no `.file-name`. */ + const nameless = (className: string, extra: Partial = {}) => + plan({ + tag: 'div', + tokens: className.split(' '), + attributes: new Map(), + hasSpread: false, + hasRef: false, + hasChildren: true, + classesAround: ['field'], + childElements: [ + node('label', ['file-label'], { + children: [ + node('input', ['file-input'], { + attributes: new Map([['type', 'file']]), + isEmpty: true, + }), + node('span', ['file-cta'], { + children: [ + node('span', ['file-label'], { + staticContent: true, + text: 'Upload', + }), + ], + }), + ], + }), + ], + ...extra, + }); + + const written = nameless('file has-name is-empty'); + const bare = nameless('file has-name'); + const conditional = nameless('file has-name', { + conditional: [['is-empty']], + }); + const rule = bare.todos.map(todo => todo.rule).join(' '); + // An agent sent to the unmappables by this TODO reads the section its rule + // names, so that is where the recipe has to be. + const recipes = { + 'component-map.md': paragraph( + doc, + '## A tree a component renders from props', + '`has-name` `.file` with no `.file-name`' + ), + 'unmappables.md': paragraph( + unmappables, + `### \`${rule.split(':')[0]}:\``, + '`has-name` `.file` with no `.file-name`' + ), + }; + + it('converts it only with is-empty written out, and the references say so', () => { + expect(written.conversion).not.toBeNull(); + expect(rule).toBe('defaults:File'); + expect(conditional.todos.map(todo => todo.rule).join(' ')).toBe(rule); + for (const [file, text] of Object.entries(recipes)) { + expect({ + file, + // Within one sentence: a code span's dot (`.file`) ends none. + static: /`is-empty` (?:[^.`]|`[^`]*`)*as a static class/.test(text), + condition: /a condition on (?:it|`is-empty`) can't stand in/.test(text), + }).toEqual({ file, static: true, condition: true }); + } + expect(recipes['component-map.md']).toContain(`\`${rule}\``); + }); + + it('pins the name empty, and the references say so', () => { + expect(written.conversion?.file?.fileName).toBe(''); + // The class goes with the rest of the tree, since `File` renders it. + expect(written.conversion?.className).toBeNull(); + for (const [file, text] of Object.entries(recipes)) { + expect({ file, pins: text.includes('`fileName=""`') }).toEqual({ + file, + pins: true, + }); + } + expect(recipes['component-map.md']).toContain( + 'The class then goes with the rest of the tree.' + ); + }); +}); diff --git a/bestax-migrate/src/sources/bulma-classes/__tests__/plan.test.ts b/bestax-migrate/src/sources/bulma-classes/__tests__/plan.test.ts index 10cb003ab..5ac98c855 100644 --- a/bestax-migrate/src/sources/bulma-classes/__tests__/plan.test.ts +++ b/bestax-migrate/src/sources/bulma-classes/__tests__/plan.test.ts @@ -1178,6 +1178,46 @@ describe('plan', () => { }); }); + it('takes is-empty on a name slot with no name, which File renders there itself', () => { + // Bulma's modifier for a `has-name` `.file` with nothing to name (#978). + const empty = file(tree(), 'file has-name is-empty').conversion!; + expect(empty.props).toEqual([['hasName', true]]); + expect(empty.className).toBeNull(); + // Its name is pinned empty: unpinned, `File` would show the file a + // user picks, and drop `is-empty` with it, where the markup never does. + expect(empty.file).toEqual({ + inputClassName: null, + buttonLabel: 0, + fileName: '', + }); + // Without it `File` adds a class the markup doesn't have, and a + // condition can't promise one `File` renders whatever it says. + const bare = file(tree(), 'file has-name'); + expect(rules(bare)).toEqual(['defaults:File']); + expect(bare.todos[0].message).toMatch(/`is-empty`/); + // And says what that conversion pins, so a pick never shows a name. + expect(bare.todos[0].message).toContain('converts with `fileName=""`'); + // A conditional `is-empty` refuses too, and the TODO says so, or an + // author who has one reads it as already met. + const conditional = file( + tree(), + 'file has-name', + {}, + { conditional: [['is-empty']] } + ); + expect(rules(conditional)).toEqual(['defaults:File']); + expect(conditional.todos[0].message).toContain( + "a condition on `is-empty` can't stand in for it; write `is-empty` here as a static class" + ); + // Beside a name `File` renders none, so one written there stays a class. + const named = file( + tree({ name: span('file-name', { text: 'cv.pdf' }) }), + 'file has-name is-empty' + ).conversion!; + expect(named.className).toBe('is-empty'); + expect(named.file?.fileName).toBe('cv.pdf'); + }); + it('converts only inside a Field, already there or becoming one', () => { expect(rules(file(tree(), 'file', {}, { classesAround: [] }))).toEqual([ 'context:File', diff --git a/bestax-migrate/src/sources/bulma-classes/plan.ts b/bestax-migrate/src/sources/bulma-classes/plan.ts index 4e946a40c..55ad1a9aa 100644 --- a/bestax-migrate/src/sources/bulma-classes/plan.ts +++ b/bestax-migrate/src/sources/bulma-classes/plan.ts @@ -241,13 +241,19 @@ export interface BuiltFile { /** Which of them holds the icon before that text, and after it. */ iconLeft?: number; iconRight?: number; - /** The `.file-name`'s text. */ + /** + * The `.file-name`'s text, or an empty string for a `has-name` `.file` + * with none, so the target shows no file a user picks. + */ fileName?: string; } /** The button text `File` renders when it's given none. */ const DEFAULT_FILE_LABEL = 'Choose a file\u2026'; +/** The class `File` renders beside `has-name` while it has no name to show. */ +const EMPTY_NAME = 'is-empty'; + /** * Why a target that `buildsFile` stays markup outside a `Field`, for the * planner here and for the transform, which can see whether the `.field` @@ -780,10 +786,28 @@ export function plan(facts: ElementFacts): Plan { } let file: BuiltFile | undefined; if (entry.buildsFile) { - const built = buildFile(facts.childElements, entry, writes.has('hasName')); + const hasName = writes.has('hasName'); + const built = buildFile(facts.childElements, entry, hasName); if ('why' in built) return refuse(built.kind, built.token, built.why); file = built.file; numbers.push(...built.numbers); + // With `has-name` and no `.file-name`, the target renders Bulma's + // `is-empty` too, whatever a condition says, so the markup has to carry + // it written out; it then goes with the rest of what the target renders. + // Its name is pinned empty, as a `.file-name` pins it to that text: + // unpinned, the target shows the file a user picks, and the markup never + // does. + if (hasName && file.fileName === undefined) { + if (!tokens.includes(EMPTY_NAME)) { + return refuse( + 'defaults', + target, + `bestax \`${target}\` renders Bulma's \`${EMPTY_NAME}\` on a \`has-name\` \`.file\` with no \`.file-name\`, whatever a condition says, so a condition on \`${EMPTY_NAME}\` can't stand in for it; write \`${EMPTY_NAME}\` here as a static class if that is what you want, then re-run, and it converts with \`fileName=""\`, so a file the user picks shows no name, as this markup shows none` + ); + } + converted.add(EMPTY_NAME); + file = { ...file, fileName: '' }; + } } const props: Array<[string, string | true]> = []; diff --git a/bulma-ui/src/form/CLAUDE.md b/bulma-ui/src/form/CLAUDE.md index 49717414d..e7b897b59 100644 --- a/bulma-ui/src/form/CLAUDE.md +++ b/bulma-ui/src/form/CLAUDE.md @@ -38,8 +38,8 @@ Conventions: as escape hatches, so they are public API too. - Basic inputs (Input, Select, TextArea, …) ship no CSS, but more of this folder has SCSS than you'd guess: even Checkbox and Radio have themed partials, File has one for its keyboard - focus ring, and every extended input (Autocomplete, DateInput, Numberinput, Rate, Slider, - Switch, Taginput, …) does too. Check `../scss/form/_index.scss` for the authoritative list - before changing visuals. + focus ring and a boxed CTA's corners, and every extended input (Autocomplete, DateInput, + Numberinput, Rate, Slider, Switch, Taginput, …) does too. Check `../scss/form/_index.scss` for + the authoritative list before changing visuals. Follow the anatomy rule in `bulma-ui/CLAUDE.md` (test + story + docs page + export + catalog). diff --git a/bulma-ui/src/form/File.stories.tsx b/bulma-ui/src/form/File.stories.tsx index 95b07bb9b..a21838266 100644 --- a/bulma-ui/src/form/File.stories.tsx +++ b/bulma-ui/src/form/File.stories.tsx @@ -39,6 +39,34 @@ export const PickedFileName: Story = { ), }; +/** + * Before a pick, a `hasName` File carries Bulma's `is-empty`, in each layout, + * until a name sits beside its button. + */ +export const NoNameYet: Story = { + render: () => ( + <> +