create-bestax 4.2.7 → 4.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bestax",
-  "version": "4.2.7",
+  "version": "4.2.8",
   "description": "Create a new bestax-bulma project",
   "type": "module",
   "bin": {
@@ -39,7 +39,7 @@
     "figures": "^6.1.0",
     "fs-extra": "^11.4.0",
     "prompts": "^2.4.2",
-    "@allxsmith/bestax-bulma": "^5.15.0"
+    "@allxsmith/bestax-bulma": "^5.15.1"
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",

package/templates/skills/bestax-custom-component/references/library-contributor.md

@@ -97,6 +97,34 @@ Rules that keep components consistent:
 - **Spread `rest`, not `props`**, onto the DOM node — `useBulmaClasses` has already stripped the
   helper props out of `rest`, so they don't leak to the DOM as invalid attributes.
 - **Set `displayName`** on `forwardRef` components (needed for tests and Storybook autodocs).
+- **A polymorphic `as` means the props follow it, and usually the ref too.** If `as` accepts any
+  `React.ElementType`, do not pin the props to one element — split them into a
+  `FooOwnProps` interface and intersect it with `ComponentPropsWithoutRef<T>`, then cast
+  the `forwardRef` result to `PolymorphicComponent<FooOwnProps, 'default-tag'>`
+  (`src/helpers/polymorphic.ts`). `Button.tsx` is the reference.
+  **Write that intersection out in the alias; do not build it from
+  `PolymorphicProps<T, FooOwnProps>`.** The API-docs extractor walks heritage
+  syntactically, and it cannot see through a generic alias or a distributive
+  conditional — routing the alias through the helper drops most of the props
+  table without failing (#667). `PolymorphicProps` is for consumer and wrapper
+  types; `PolymorphicComponent<FooOwnProps, 'default-tag'>` is the cast target,
+  and `PolymorphicComponentWithoutRef` the one for a component that forwards no
+  ref. Add type-level checks in `src/__typetests__/` both ways — that the
+  default `as` accepts its element's props and a different `as` rejects them —
+  since nothing else in the repo type-checks this. Pinning the props instead
+  rejects correct code and accepts incorrect code at the same time, which is what #641 fixed
+  across eight components. A literal union (`Title.tsx`) escapes the generic only when its
+  members genuinely **share** a prop and ref surface — `h1`–`h6` and `p` all carry plain
+  `HTMLAttributes`, so one interface describes them all. It is not a general exemption:
+  `Dropdown.Item`'s `'a' | 'div' | 'button'` differ in `href`, `disabled`, `type` and their ref
+  element, and pinning them to one interface reproduces exactly this defect (#663). When the
+  members differ, constrain `T` to the union rather than dropping the generic.
+  Forward the ref unless the component owns the node it needs: `Reveal` observes
+  an element for scroll intersection and wraps a custom `as` in its own `div`,
+  so the element `as` names is not the one it holds — it uses
+  `PolymorphicComponentWithoutRef` and forwards none. That is the exception, not
+  a licence to skip refs; everything a consumer might focus or measure should
+  forward one.
 - **Element sizing uses an inline `'small' | 'medium' | 'large'` union**, mapped to `is-small` /
   `is-medium` / `is-large` (see `Tabs.tsx`, `Control.tsx`). Do **not** reach for the `validSizes`
   constant — that one is `'0'…'6' | 'auto'` and exists for **spacing** helpers, not element size.

package/templates/skills/bestax-layout-scaffold/references/layout-components.md

@@ -243,7 +243,8 @@ a navbar that mounts conditionally.
 
 **Routing:** in a routed app, don't use `href="#"` — render items as the router's link
 component. `Menu.Item as={Link} to="/x"` and `Navbar.Item as={Link} to="/x"` both compile
-without casts (their props allow extra keys). Drive `active` from `useLocation().pathname`.
+without casts (their props follow `as`, so `to` is checked against the router's own link
+type). Drive `active` from `useLocation().pathname`.
 Full patterns (including Buttons that navigate and Next.js `href`): the docs guide at
 https://bestax.io/docs/guides/features/routing.