diff --git a/bestax-mcp/data/catalog.json b/bestax-mcp/data/catalog.json index d0f79f20c..3b0a4b85d 100644 --- a/bestax-mcp/data/catalog.json +++ b/bestax-mcp/data/catalog.json @@ -557,7 +557,7 @@ "slug": "layout/level", "import": "import { Level } from '@allxsmith/bestax-bulma';", "compound": true, - "propCount": 26, + "propCount": 23, "exampleCount": 5 }, { diff --git a/bestax-mcp/data/components/Level.json b/bestax-mcp/data/components/Level.json index f4c27b4ac..131954829 100644 --- a/bestax-mcp/data/components/Level.json +++ b/bestax-mcp/data/components/Level.json @@ -287,37 +287,10 @@ "required": false, "inherited": false, "deprecated": false - }, - { - "name": "href", - "type": "string", - "default": null, - "description": "Href for \"a\" tag.", - "required": false, - "inherited": false, - "deprecated": false - }, - { - "name": "target", - "type": "string", - "default": null, - "description": "Target for \"a\" tag", - "required": false, - "inherited": false, - "deprecated": false - }, - { - "name": "rel", - "type": "string", - "default": null, - "description": "Rel for \"a\" tag", - "required": false, - "inherited": false, - "deprecated": false } ], "extraProps": [], - "catchAll": "All standard
attributes and Bulma helper props", + "catchAll": "All standard /
/

attributes and Bulma helper props", "types": [] } ], diff --git a/bestax-mcp/data/components/SubTitle.json b/bestax-mcp/data/components/SubTitle.json index fc87a4d82..f54e82e26 100644 --- a/bestax-mcp/data/components/SubTitle.json +++ b/bestax-mcp/data/components/SubTitle.json @@ -128,7 +128,7 @@ "deprecated": false } ], - "catchAll": "All standard

–

attributes and Bulma helper props", + "catchAll": "All standard

–

/

attributes and Bulma helper props", "types": [] } ], diff --git a/bestax-mcp/data/components/Title.json b/bestax-mcp/data/components/Title.json index 286b6cc30..bcfa719f0 100644 --- a/bestax-mcp/data/components/Title.json +++ b/bestax-mcp/data/components/Title.json @@ -135,7 +135,7 @@ "deprecated": false } ], - "catchAll": "All standard

–

attributes and Bulma helper props", + "catchAll": "All standard

–

/

attributes and Bulma helper props", "types": [] } ], diff --git a/bestax-mcp/data/skills.json b/bestax-mcp/data/skills.json index 206fb6708..721a6c2d7 100644 --- a/bestax-mcp/data/skills.json +++ b/bestax-mcp/data/skills.json @@ -98,7 +98,7 @@ { "id": "bloomer-unmappables", "file": "references/bloomer/unmappables.md", - "bytes": 16259 + "bytes": 16354 }, { "id": "css-migration", @@ -118,7 +118,7 @@ { "id": "rbx-unmappables", "file": "references/rbx/unmappables.md", - "bytes": 13444 + "bytes": 13539 }, { "id": "react-bulma-components-component-map", @@ -133,7 +133,7 @@ { "id": "react-bulma-components-unmappables", "file": "references/react-bulma-components/unmappables.md", - "bytes": 9448 + "bytes": 9543 } ], "examples": [] diff --git a/bestax-migrate/e2e/as-unions.test.ts b/bestax-migrate/e2e/as-unions.test.ts index 94a296484..7132b9443 100644 --- a/bestax-migrate/e2e/as-unions.test.ts +++ b/bestax-migrate/e2e/as-unions.test.ts @@ -381,30 +381,6 @@ describe('the per-target link-attribute exception matches the library', () => { diagnostics: '', }); }); - - it('holds `Level.Item` to exactly the link attributes it declares', () => { - // Most href-capable targets either follow `as` or extend - // `AnchorHTMLAttributes`; this one enumerates, and the rule has a row for - // it. Asserted by use, both ways. - const rows: string[] = [ - "import { Level } from '@allxsmith/bestax-bulma';", - '', - `export const ok = {'x'};`, - ]; - for (const attr of Object.keys(LINK_ATTR_TABLE)) { - if (TARGET_LINK_ATTR_TABLE['Level.Item'].includes(attr)) continue; - rows.push(`// @ts-expect-error Level.Item declares no ${attr}`); - rows.push( - `export const n_${attr} = {'x'};` - ); - } - const source = rows.join('\n') + '\n'; - const { status, diagnostics } = typecheckTsx(source, 'target-link-attrs'); - expect({ status, diagnostics: annotate(diagnostics, source) }).toEqual({ - status: 0, - diagnostics: '', - }); - }); }); describe('the href-bearing intrinsics match what React types', () => { diff --git a/bestax-migrate/src/sources/_shared/polymorphic.ts b/bestax-migrate/src/sources/_shared/polymorphic.ts index 676f7ada2..c8e3515a8 100644 --- a/bestax-migrate/src/sources/_shared/polymorphic.ts +++ b/bestax-migrate/src/sources/_shared/polymorphic.ts @@ -92,8 +92,7 @@ const AS_ANY = new Set(['Button', 'Menu.Item', 'Navbar.Item', 'Navbar.Link']); * typechecking cannot answer the question on its own. `Level.Item` declares * `href` on its props at every `as`, so `` compiles -- * but it renders a

and forwards `href` only when the tag is an `` - * (`bulma-ui/src/layout/Level.tsx:227`), so the attribute is dropped at - * runtime. A table built from the types alone calls that supported; it is the + * (`LevelItem`'s anchor branch), so the attribute is dropped at runtime. A table built from the types alone calls that supported; it is the * same dead attribute this pass exists to remove. */ const HREF_OK: Record = { @@ -287,7 +286,7 @@ export const AS_ANY_TARGETS: readonly string[] = [...AS_ANY].sort(); * * They are excluded because the components disagree about what they forward, * so no shared set is right. `Menu.Item` strips `href` unless the tag is an - * `` or a custom component (`bulma-ui/src/components/Menu.tsx:212-222`), + * `` or a custom component (`MenuItem`'s `isLinkLike` guard), * while `Button` routes everything but `'button'` through its anchor path and * would forward it. Keeping `href` beside `as="area"` therefore typechecks on * both and does nothing on one of them, which is the silently-dead attribute @@ -333,12 +332,15 @@ const LINK_ATTR_ELEMENTS: Record = { /** * The link attributes a target accepts, where its props do not follow `as`. * - * Most components here either follow `as` (the element decides, above) or - * extend `AnchorHTMLAttributes` outright (`Pagination.*`, `Panel.Block`, so - * everything is fine). `Level.Item` is the exception that enumerates: it - * declares `href`, `target` and `rel` and nothing else, so `download`, - * `hrefLang`, `ping` and `referrerPolicy` are type errors there even at - * `as="a"`. + * Every component here either follows `as` (the element decides, above) or + * carries the anchor's attributes outright — `Pagination.*` and `Panel.Block` + * by extending `AnchorHTMLAttributes`, `Level.Item` since #672 by subtracting + * `HTMLAttributes` from it. So none is narrower than the element it renders, + * and none needs a row. + * + * A target that ENUMERATED a subset would be, and the rule would have to know: + * `Level.Item` listed `href`, `target` and `rel` and stopped, which made + * `download` a type error on its own ``. * * A target absent from `HREF_OK` needs no row: a component that takes no * `href` at any `as` takes none of its siblings either -- verified for @@ -346,7 +348,19 @@ const LINK_ATTR_ELEMENTS: Record = { * from that table rather than being a second list to keep. */ const TARGET_LINK_ATTRS: Record = { - 'Level.Item': ['target'], + // Empty since #672. `Level.Item` was the only row: it listed `href`, `target` + // and `rel` and stopped, so the element alone could not say that `download` + // was rejected. It now enumerates the anchor's attributes by SUBTRACTING + // `React.HTMLAttributes` from `React.AnchorHTMLAttributes`, which is all of + // them — and a row naming all of them decides nothing a row naming none does + // not, so the element decides and the row goes. + // + // The mechanism stays for a target that really is narrower than its element, + // and the e2e asserts the premise rather than assuming it: every href-capable + // target without a row accepts every link attribute on its anchor. + // `Level.Item` joins that sweep, so its coverage moved rather than going. + // NOTE that leaves the `rejectedBy = 'component'` arm with no live caller — + // worth deleting and restoring from git if nothing claims it. }; /** The rows the type test holds to the library. */ diff --git a/bulma-ui/src/__typetests__/polymorphic.tsx b/bulma-ui/src/__typetests__/polymorphic.tsx index 68fd08d82..7279b2bf0 100644 --- a/bulma-ui/src/__typetests__/polymorphic.tsx +++ b/bulma-ui/src/__typetests__/polymorphic.tsx @@ -20,6 +20,7 @@ */ import React from 'react'; import { Avatar } from '../components/Avatar'; +import { Level, type LevelItemProps } from '../layout/Level'; import { Dropdown, type DropdownItemElement, @@ -341,3 +342,57 @@ export const rejected = ( ); + +// -------------------------------------------------------------------------- +// `Level.Item` (#672). It is NOT polymorphic: it enumerates the anchor's +// attributes by subtracting `HTMLAttributes` from `AnchorHTMLAttributes`, and +// withholds them at runtime for any tag that is not an ``. Deriving them +// from `as` is the source-breaking half, deferred. +// +// These exist because the compatibility was checked with throwaway probes +// while the polymorphic version was written and reverted, and a probe proves +// nothing after it is deleted. Each line below is a shape that version broke. +// -------------------------------------------------------------------------- + +export const levelItemGained = ( + <> + {/* #641's symptom, and the two a hand-written list kept missing. */} + + + + +); + +// An event handler written against the ALIAS keeps its contextual type. The +// polymorphic version turned one handler over a union element into a union of +// three handler types, and this became an implicit `any`. +export const levelItemHandler: LevelItemProps = { + onClick: event => void event.currentTarget, +}; + +// A props bag spreads back into its own component — the canonical wrapper +// shape, and `TS2769` under the reverted version. +declare const levelItemBag: LevelItemProps; +export const levelItemSpread = ; + +// The alias stays assignable to a single element's attributes. +declare function wantsDivAttributes( + props: React.HTMLAttributes +): void; +export const levelItemAssignable = () => wantsDivAttributes(levelItemBag); + +// `ComponentProps` keeps its keys reachable: `keyof` a union is the +// INTERSECTION of its members' keys, so a union-shaped props type loses them. +type LevelItemDerived = React.ComponentProps; +export const levelItemKey: keyof LevelItemDerived = 'href'; +export const levelItemIndexed: LevelItemDerived['href'] = '/x'; +export const levelItemDerivedTag: LevelItemDerived = { as: 'p' }; + +// And a memo wrapper keeps every tag. +const MemoLevelItem = React.memo(Level.Item); +export const levelItemMemo = ( + <> + + + +); diff --git a/bulma-ui/src/layout/Level.stories.tsx b/bulma-ui/src/layout/Level.stories.tsx index 7bfd43c5a..bf357278b 100644 --- a/bulma-ui/src/layout/Level.stories.tsx +++ b/bulma-ui/src/layout/Level.stories.tsx @@ -168,3 +168,36 @@ export const CompoundUsage: StoryObj = { ), }; + +/** + * `Level.Item` renders an `` when told to, and that form takes the anchor's + * wider attributes — `download`, `hrefLang`, `ping`, `referrerPolicy` — not + * just `href`/`target`/`rel`. On any other `as` they are withheld rather than + * rendered as dead markup. + */ +export const AnchorItem: StoryObj = { + render: () => ( + + + + Download the report + + + + + Open example.com + + + + ), +}; diff --git a/bulma-ui/src/layout/Level.tsx b/bulma-ui/src/layout/Level.tsx index 466a606c8..df40aa54c 100644 --- a/bulma-ui/src/layout/Level.tsx +++ b/bulma-ui/src/layout/Level.tsx @@ -162,11 +162,46 @@ export const LevelRight: React.FC = ({ ); }; +/** + * Exactly what `` adds over the attributes every element has: `href`, + * `target`, `download`, `hrefLang`, `ping`, `referrerPolicy`, `media`, `type`. + * + * NOT `rel`, which React declares on `HTMLAttributes` for every element and the + * subtraction therefore removes. This component withholds it from a non-anchor + * anyway, because it always has — see `ANCHOR_ONLY` in the implementation, + * where it is named separately for that reason. + * + * Subtracted from React's own types rather than listed. Listing them is how this + * component came to reject `download` at `as="a"` — the list said `href`, + * `target`, `rel` and stopped, and #641 is the report. A list gains an entry only + * when someone notices; a subtraction gains it when React does. + * + * They reach the `` branch and no other: declared at every `as` because + * narrowing them to the anchor is source-breaking (#672, `next-major`), and + * withheld at runtime so the type's permissiveness costs no dead markup. + */ +type AnchorOnlyAttributes = Omit< + React.AnchorHTMLAttributes, + keyof React.HTMLAttributes +>; + /** * Props for the LevelItem component. + * + * The anchor attributes are enumerated here, at every `as`, and forwarded only + * when the tag is an `` — so `` compiles and + * renders a `

` without it. That asymmetry is deliberate for now: deriving + * them from `as` instead is what makes the dead pair a type error, and it also + * stops `const p: LevelItemProps = { href }` compiling for consumers who write + * it today. #672 carries that half, labelled `next-major`. + * + * What this list must NOT become is a shorter one. Enumerating only `href`, + * `target` and `rel` made every other anchor attribute a type error even at + * `as="a"`, which is what #641 reported. */ export interface LevelItemProps extends + AnchorOnlyAttributes, React.HTMLAttributes< HTMLDivElement | HTMLParagraphElement | HTMLAnchorElement >, @@ -185,12 +220,6 @@ export interface LevelItemProps className?: string; /** Content. */ children?: React.ReactNode; - /** Href for "a" tag. */ - href?: string; - /** Target for "a" tag */ - target?: string; - /** Rel for "a" tag */ - rel?: string; } /** @@ -205,9 +234,6 @@ export const LevelItem: React.FC = ({ hasTextCentered, className, children, - href, - target, - rel, color, bgColor, textColor, @@ -225,23 +251,47 @@ export const LevelItem: React.FC = ({ }); const levelItemClasses = classNames(mainClass, bulmaHelperClasses, className); - // If rendering as "a", only pass anchor-specific props + // The anchor's own attributes reach an `` and nothing else. The type + // declares them at every `as` — narrowing that is source-breaking (#672) — so + // the runtime is what keeps `` from rendering a + // dead attribute. + // + // Keyed off `AnchorOnlyAttributes` rather than repeated as a list, because a + // hand list beside a derived type drifts in the one direction that matters: + // the day React adds an anchor attribute, the type would accept it at every + // `as` while the list let it leak onto a `

`. `Record` makes that a + // compile error here until this object catches up. #682 is the issue for + // sharing the rule with the two components that keep their own copies. + const ANCHOR_ONLY: Record = { + href: true, + target: true, + download: true, + hrefLang: true, + ping: true, + referrerPolicy: true, + media: true, + type: true, + // `rel` is NOT in the subtraction: React declares it on `HTMLAttributes`, + // for every element. It is here because this component has always withheld + // it from a non-anchor, and it is named separately so the key set above + // stays honest about where each name comes from. + rel: true, + }; + if (Tag === 'a') { return ( - + {children} ); } + const withoutAnchorAttrs = Object.fromEntries( + Object.entries(rest).filter(([key]) => !(key in ANCHOR_ONLY)) + ); + return ( - + {children} ); diff --git a/bulma-ui/src/layout/__tests__/Level.test.tsx b/bulma-ui/src/layout/__tests__/Level.test.tsx index 6d04bc496..9e9585c4f 100644 --- a/bulma-ui/src/layout/__tests__/Level.test.tsx +++ b/bulma-ui/src/layout/__tests__/Level.test.tsx @@ -102,6 +102,78 @@ describe('Level', () => { expect(screen.getByTestId('level-item')).toHaveClass('m-2'); }); + it('forwards the wider anchor attributes to the ', () => { + // The ones #641 reported as rejected. They are not destructured — they reach + // the `` through `...rest`, and are filtered out of it for every other + // tag — so a change to that filter, or to `useBulmaClasses`, drops them and + // only this notices. + render( + + + Download + + + ); + const anchor = screen.getByTestId('wide'); + expect(anchor).toHaveAttribute('download', 'r.pdf'); + expect(anchor).toHaveAttribute('hreflang', 'en'); + expect(anchor).toHaveAttribute('ping', '/p'); + expect(anchor).toHaveAttribute('referrerpolicy', 'no-referrer'); + expect(anchor).toHaveAttribute('media', 'print'); + expect(anchor).toHaveAttribute('type', 'application/pdf'); + }); + + it('withholds them from a non-anchor tag', () => { + // They are declared at every `as` — the half #672 leaves to a major — so + // the type permits this and the runtime must not render a dead attribute. + render( + + + Text + + + ); + const p = screen.getByTestId('p'); + expect(p.tagName).toBe('P'); + // Every attribute the type admits has to be supplied here, or the assertion + // for it is vacuous — it would pass on a prop that was never sent. + for (const attr of [ + 'href', + 'target', + 'rel', + 'download', + 'hreflang', + 'ping', + 'referrerpolicy', + 'media', + 'type', + ]) { + expect(p).not.toHaveAttribute(attr); + } + }); + it('renders as when requested with href and anchor props', () => { render( diff --git a/docs/docs/api/elements/subtitle.md b/docs/docs/api/elements/subtitle.md index 59820c5af..90c688e81 100644 --- a/docs/docs/api/elements/subtitle.md +++ b/docs/docs/api/elements/subtitle.md @@ -164,7 +164,7 @@ Combine `Title` and `SubTitle` components for a structured heading and subheadin | `textColor` | [Bulma color](../helpers/valid-values.md) \| `'inherit'` \| `'current'` | — | Text color helper. | | `bgColor` | [Bulma color](../helpers/valid-values.md) \| `'inherit'` \| `'current'` | — | Background color helper. | | `skeleton` | `boolean` | — | Applies the `is-skeleton` class to the entire component. | -| `...` | All standard `

`–`

` attributes and Bulma helper props | — | See [Helper Props](../helpers/usebulmaclasses.md) | +| `...` | All standard `

`–`

` / `

` attributes and Bulma helper props | — | See [Helper Props](../helpers/usebulmaclasses.md) | diff --git a/docs/docs/api/elements/title.md b/docs/docs/api/elements/title.md index 06bab1f08..cedea1c49 100644 --- a/docs/docs/api/elements/title.md +++ b/docs/docs/api/elements/title.md @@ -174,7 +174,7 @@ When using `as="p"`, the element is visually styled as a heading but semanticall | `textColor` | [Bulma color](../helpers/valid-values.md) \| `'inherit'` \| `'current'` | — | Text color helper. | | `bgColor` | [Bulma color](../helpers/valid-values.md) \| `'inherit'` \| `'current'` | — | Background color helper. | | `skeleton` | `boolean` | — | Applies the `is-skeleton` class to the entire component. | -| `...` | All standard `

`–`

` attributes and Bulma helper props | — | See [Helper Props](../helpers/usebulmaclasses.md) | +| `...` | All standard `

`–`

` / `

` attributes and Bulma helper props | — | See [Helper Props](../helpers/usebulmaclasses.md) | diff --git a/docs/docs/api/layout/level.md b/docs/docs/api/layout/level.md index 19e683ffb..33e24e0d2 100644 --- a/docs/docs/api/layout/level.md +++ b/docs/docs/api/layout/level.md @@ -292,10 +292,7 @@ You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `` attributes and Bulma helper props | — | See [Helper Props](../helpers/usebulmaclasses.md) | +| `...` | All standard `` / `

` / `

` attributes and Bulma helper props | — | See [Helper Props](../helpers/usebulmaclasses.md) | diff --git a/scripts/lib/props-extract.mjs b/scripts/lib/props-extract.mjs index bcd6b94e5..6e9e21b86 100644 --- a/scripts/lib/props-extract.mjs +++ b/scripts/lib/props-extract.mjs @@ -1188,8 +1188,14 @@ function catchAllRow(external, markdown = true) { ); continue; } - const m = e.text.match(/HTML\w*Element/); - if (m) elements.add(DOM_ELEMENT_LABELS[m[0]] ?? 'HTML'); + // Every match, not the first. A component whose base is a UNION of elements + // — `Level.Item` is `HTMLDivElement | HTMLParagraphElement | HTMLAnchorElement` + // — was described by whichever one came first, so its page and the MCP index + // both said "

attributes" and named neither the `

` nor the `` it + // also renders. + for (const m of e.text.matchAll(/HTML\w*Element/g)) { + elements.add(DOM_ELEMENT_LABELS[m[0]] ?? 'HTML'); + } } // Surfaced so a test can hold every polymorphic component to a RECOGNIZED // constraint. 'unknown' silently takes the open wording, which over-promises diff --git a/scripts/props-extract.test.mjs b/scripts/props-extract.test.mjs index fd1d3bff3..a507db691 100644 --- a/scripts/props-extract.test.mjs +++ b/scripts/props-extract.test.mjs @@ -241,6 +241,28 @@ test('every polymorphic component has a recognized `as` constraint', () => { assert.deepEqual(table('Button', 'Button').catchAll.asKinds, ['open']); }); +test('a union element base names every element, not the first', () => { + // `catchAllRow` read the base with `String.match` and no `/g`, so a component + // whose props extend `HTMLAttributes` was described by whichever + // element came first. The regenerated pages are not the guard: a one-match + // implementation regenerates them just as incomplete, and `gen:*:check` calls + // that fresh. + assert.match( + table('Level', 'Level.Item').catchAll.text, + /`` \/ `

` \/ `

` attributes/ + ); + for (const [component, path] of [ + ['Title', 'Title'], + ['SubTitle', 'SubTitle'], + ]) { + assert.match( + table(component, path).catchAll.text, + /`

`/, + `${path} drops the

it also renders` + ); + } +}); + test('every polymorphic component names a concrete default element', () => { // A type parameter defaulting to the CONSTRAINT rather than to a tag — // `` — makes diff --git a/skills/bestax-migrate/references/bloomer/unmappables.md b/skills/bestax-migrate/references/bloomer/unmappables.md index b6a8ad175..f215dc123 100644 --- a/skills/bestax-migrate/references/bloomer/unmappables.md +++ b/skills/bestax-migrate/references/bloomer/unmappables.md @@ -156,8 +156,9 @@ on an `` inside, or make the element one that takes it. `rel` is never touched: React declares it on `HTMLAttributes`, so it is valid on every element. A component can be narrower than its element. One that takes no `href` at any `as` takes none of -these either, and `Level.Item` declares only `href`, `target` and `rel` — so `download` and the -rest go there even at `as="a"`. +these either. `Level.Item` is not narrower: it declares the anchor's whole attribute surface at +every `as` and forwards it only on the ``, so all of these survive at `as="a"` and none of +them reaches a `

` or a `

`. ## `prop:render` — the render prop diff --git a/skills/bestax-migrate/references/rbx/unmappables.md b/skills/bestax-migrate/references/rbx/unmappables.md index 18ce8fbc3..0b6ff9c60 100644 --- a/skills/bestax-migrate/references/rbx/unmappables.md +++ b/skills/bestax-migrate/references/rbx/unmappables.md @@ -91,8 +91,9 @@ on an `` inside, or make the element one that takes it. `rel` is never touched: React declares it on `HTMLAttributes`, so it is valid on every element. A component can be narrower than its element. One that takes no `href` at any `as` takes none of -these either, and `Level.Item` declares only `href`, `target` and `rel` — so `download` and the -rest go there even at `as="a"`. +these either. `Level.Item` is not narrower: it declares the anchor's whole attribute surface at +every `as` and forwards it only on the ``, so all of these survive at `as="a"` and none of +them reaches a `

` or a `

`. ## `component:Generic` — rbx's base element diff --git a/skills/bestax-migrate/references/react-bulma-components/unmappables.md b/skills/bestax-migrate/references/react-bulma-components/unmappables.md index 809508049..94c5c146b 100644 --- a/skills/bestax-migrate/references/react-bulma-components/unmappables.md +++ b/skills/bestax-migrate/references/react-bulma-components/unmappables.md @@ -189,8 +189,9 @@ on an `` inside, or make the element one that takes it. `rel` is never touched: React declares it on `HTMLAttributes`, so it is valid on every element. A component can be narrower than its element. One that takes no `href` at any `as` takes none of -these either, and `Level.Item` declares only `href`, `target` and `rel` — so `download` and the -rest go there even at `as="a"`. +these either. `Level.Item` is not narrower: it declares the anchor's whole attribute surface at +every `as` and forwards it only on the ``, so all of these survive at `as="a"` and none of +them reaches a `

` or a `

`. ## Helper props dropped from plain-element replacements