@pyreon/rocketstyle 0.15.0 → 0.18.0

package/src/index.ts

@@ -4,7 +4,7 @@ import type { Rocketstyle } from './init'
 import rocketstyle from './init'
 import type { IsRocketComponent } from './isRocketComponent'
 import isRocketComponent from './isRocketComponent'
-import type { AttrsCb } from './types/attrs'
+import type { AttrsCb, AttrsHelpers } from './types/attrs'
 import type {
   ConfigAttrs,
   ConsumerCb,
@@ -37,6 +37,7 @@ import type { ComponentFn, ElementType, ExtractProps, MergeTypes, TObj } from '.
 
 export type {
   AttrsCb,
+  AttrsHelpers,
   ComponentFn,
   ComposeParam,
   ConfigAttrs,

package/src/rocketstyle.ts

@@ -9,7 +9,12 @@ import type { Configuration, ExtendedConfiguration } from './types/configuration
 import type { RocketComponent } from './types/rocketComponent'
 import type { InnerComponentProps, RocketStyleComponent } from './types/rocketstyle'
 import type { ComponentFn } from './types/utils'
-import { calculateChainOptions, calculateStylingAttrs, pickStyledAttrs } from './utils/attrs'
+import {
+  calculateChainOptions,
+  calculateStylingAttrs,
+  mergeDescriptors,
+  pickStyledAttrs,
+} from './utils/attrs'
 import { chainOptions, chainOrOptions, chainReservedKeyOptions } from './utils/chaining'
 import { calculateHocsFuncs } from './utils/compose'
 import { getDimensionsMap } from './utils/dimensions'
@@ -38,18 +43,42 @@ type CloneAndEnhance = (
   opts: Partial<ExtendedConfiguration>,
 ) => ReturnType<typeof rocketComponent>
 
-/** Clones the current configuration and merges new options, returning a fresh rocketComponent. */
-const cloneAndEnhance: CloneAndEnhance = (defaultOpts, opts) =>
-  rocketComponent({
+/**
+ * Clones the current configuration and merges new options, returning a fresh
+ * rocketComponent.
+ *
+ * Component-swap reset: when `opts.component` is set AND differs from the
+ * current `defaultOpts.component`, the prior `attrs`, `priorityAttrs`,
+ * `filterAttrs`, and `compose` chains are dropped — they were tailored to the
+ * previous component's prop shape, and applying them to a different component
+ * silently leaks invalid props through to the DOM (e.g. `disabled` on an
+ * `<a>`). Callers who want to preserve them must re-chain explicitly:
+ *
+ *   const NewBtn = Button.config({ component: 'a' }).attrs(sharedAttrs)
+ */
+const cloneAndEnhance: CloneAndEnhance = (defaultOpts, opts) => {
+  const componentChanged =
+    opts.component != null && opts.component !== defaultOpts.component
+
+  return rocketComponent({
     ...defaultOpts,
-    attrs: chainOptions(opts.attrs, defaultOpts.attrs),
-    filterAttrs: [...(defaultOpts.filterAttrs ?? []), ...(opts.filterAttrs ?? [])],
-    priorityAttrs: chainOptions(opts.priorityAttrs, defaultOpts.priorityAttrs),
+    attrs: componentChanged
+      ? chainOptions(opts.attrs, [])
+      : chainOptions(opts.attrs, defaultOpts.attrs),
+    filterAttrs: componentChanged
+      ? [...(opts.filterAttrs ?? [])]
+      : [...(defaultOpts.filterAttrs ?? []), ...(opts.filterAttrs ?? [])],
+    priorityAttrs: componentChanged
+      ? chainOptions(opts.priorityAttrs, [])
+      : chainOptions(opts.priorityAttrs, defaultOpts.priorityAttrs),
     statics: { ...defaultOpts.statics, ...opts.statics },
-    compose: { ...defaultOpts.compose, ...opts.compose },
+    compose: componentChanged
+      ? { ...opts.compose }
+      : { ...defaultOpts.compose, ...opts.compose },
     ...chainOrOptions(CONFIG_KEYS, opts, defaultOpts),
     ...chainReservedKeyOptions([...defaultOpts.dimensionKeys, ...STYLING_KEYS], opts, defaultOpts),
   } as Parameters<typeof rocketComponent>[0])
+}
 
 // --------------------------------------------------------
 // rocketComponent
@@ -239,23 +268,46 @@ const rocketComponent: RocketComponent = (options) => {
       // Read reactive inputs (tracks theme + mode signals)
       const theme = themeAttrs.theme
       const mode = themeAttrs.mode
+      const propsRec = props as Record<string, unknown>
+
+      // Resolve active dimensions FIRST so the cache key uses the RESOLVED
+      // dimension values, not the raw prop names. Under `useBooleans: true`
+      // the user writes `<X primary />` / `<X secondary />` — both map to
+      // `state="primary"` / `state="secondary"` after _calculateStylingAttrs
+      // resolves the boolean shorthand. Keying off `propsRec[dimName]` would
+      // read `undefined` for both (the dimension prop itself was never set)
+      // and collide every variant onto the first cached entry. Reading
+      // `rocketstateRaw[dimName]` gives the resolved string and partitions
+      // them correctly.
+      // Resolved from props (not localCtx which has pseudo getters).
+      const rocketstateRaw = _calculateStylingAttrs({
+        props: pickStyledAttrs(propsRec, reservedPropNames),
+        dimensions,
+      })
 
-      // Build key: mode | dimensionProps | pseudoState. Reading dimension
+      // Build key: mode | dimensionValues | pseudoState. Reading dimension
       // props + pseudo signals here tracks them in the surrounding computed
       // so any change re-runs us with a different key.
       let key = mode as string
-      const propsRec = props as Record<string, unknown>
       for (const dimName in dimensions) {
-        const v = propsRec[dimName]
-        // String/number/boolean serialize directly. Anything else (including
-        // undefined / objects) gets a typeof tag so we don't collide.
-        key +=
-          '|' +
-          (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'
-            ? String(v)
-            : v === undefined
-              ? ''
-              : '~' + typeof v)
+        const v = rocketstateRaw[dimName]
+        // Multi-key dimensions (e.g. variant={['primary', 'rounded']}) are
+        // arrays. Sort + join so equivalent sets hash identically; without
+        // this both `['a','b']` and `['b','a']` would produce different keys.
+        if (Array.isArray(v)) {
+          key +=
+            '|' + (v.length === 0 ? '' : (v as unknown[]).slice().sort().join(','))
+        } else {
+          // String/number/boolean serialize directly. Anything else (including
+          // undefined / objects) gets a typeof tag so we don't collide.
+          key +=
+            '|' +
+            (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'
+              ? String(v)
+              : v === undefined
+                ? ''
+                : '~' + typeof v)
+        }
       }
       for (const k of ALL_PSEUDO_KEYS) {
         const propV = propsRec[k]
@@ -307,12 +359,6 @@ const rocketComponent: RocketComponent = (options) => {
       }
       const themes = dimHelper.get(theme)
 
-      // Resolve active dimensions from props (not localCtx which has pseudo getters)
-      const rocketstateRaw = _calculateStylingAttrs({
-        props: pickStyledAttrs(propsRec, reservedPropNames),
-        dimensions,
-      })
-
       // Resolve mode-specific theme
       const modeBaseHelper = ThemeManager.modeBaseTheme[mode]
       if (modeBaseHelper.has(baseTheme)) {
@@ -375,30 +421,68 @@ const rocketComponent: RocketComponent = (options) => {
       _omitSetCache.set(RESERVED_STYLING_PROPS_KEYS, omitSet)
     }
 
-    // Merge localCtx + props without an intermediate spread object.
-    // omit() handles 'pseudo' removal (included in STATIC_OMIT_KEYS).
-    const mergeProps = localCtx ? { ...localCtx, ...props } : props
+    // Merge localCtx + props via descriptor-copy so reactive getter
+    // props on `props` (compiler-emitted `_rp(() => signal())` wrappers
+    // converted to getters by `makeReactiveProps`) survive the merge.
+    // A plain `{ ...localCtx, ...props }` spread would fire every getter
+    // and collapse to static values, defeating reactivity for any
+    // downstream JSX accessor reading `props.x`.
+    const mergeProps = localCtx ? mergeDescriptors(localCtx, props) : props
 
-    // omit() already returns a fresh object — assign directly onto it
-    // instead of spreading into another {} (saves one object allocation).
+    // omit() preserves descriptors (since ui-core's omit was updated to
+    // copy descriptors), so reactive getters carry through to finalProps.
     const finalProps = omit(mergeProps as Record<string, unknown>, omitSet) as Record<string, any>
 
     if (options.passProps) {
       const passed = pick(mergeProps, options.passProps)
-      for (const k in passed) finalProps[k] = passed[k]
+      // Copy descriptors so any reactive getters in passProps survive.
+      // Plain `finalProps[k] = passed[k]` would fire getters at setup time
+      // AND silently fail when finalProps[k] is already a getter-only
+      // descriptor (assignment to a getter-only property is a no-op in
+      // non-strict mode, throws in strict mode).
+      const passedDescriptors = Object.getOwnPropertyDescriptors(passed)
+      for (const k of Object.keys(passedDescriptors)) {
+        Object.defineProperty(finalProps, k, passedDescriptors[k]!)
+      }
     }
 
-    finalProps.ref = props.ref
+    // Use defineProperty for these last writes too — if props.ref or
+    // an existing finalProps slot happened to carry a getter-only
+    // descriptor, plain assignment would silently fail. defineProperty
+    // explicitly replaces the descriptor regardless of shape.
+    const refDescriptor = Object.getOwnPropertyDescriptor(props, 'ref')
+    if (refDescriptor) {
+      Object.defineProperty(finalProps, 'ref', refDescriptor)
+    }
     // Function accessors — DynamicStyled wraps them in a computed() so
     // mode/dimension changes produce a new CSS class reactively. The
     // computed tracks only these two accessors; the resolve itself runs
     // untracked to prevent exponential cascade from theme deep-reads.
-    finalProps.$rocketstyle = $rocketstyleAccessor
-    finalProps.$rocketstate = $rocketstateAccessor
+    Object.defineProperty(finalProps, '$rocketstyle', {
+      value: $rocketstyleAccessor,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    })
+    Object.defineProperty(finalProps, '$rocketstate', {
+      value: $rocketstateAccessor,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    })
 
     // development debugging — tree-shaken in production via import.meta.env.DEV
     if (__DEV__) {
-      finalProps['data-rocketstyle'] = componentName
+      // defineProperty rather than `=` to be safe against any preserved
+      // descriptor in this slot (defense-in-depth — `data-rocketstyle`
+      // is unlikely to be passed as a user prop, but the writes above
+      // use defineProperty for the same reason).
+      Object.defineProperty(finalProps, 'data-rocketstyle', {
+        value: componentName,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      })
 
       if (options.DEBUG) {
         const debugPayload = {
@@ -529,8 +613,8 @@ const rocketComponent: RocketComponent = (options) => {
         {
           render,
           mode,
-          isDark: mode === 'light',
-          isLight: mode === 'dark',
+          isDark: mode === 'dark',
+          isLight: mode === 'light',
         },
       ]),
   })

package/src/types/attrs.ts

@@ -1,13 +1,23 @@
 import type { render } from '@pyreon/ui-core'
 import type { ThemeModeKeys } from './theme'
 
-export type AttrsCb<A, T> = (
-  props: Partial<A>,
-  theme: T,
-  helpers: {
-    mode?: ThemeModeKeys
-    isDark?: boolean
-    isLight?: boolean
-    createElement: typeof render
-  },
-) => Partial<A>
+/** Helpers object passed as the 3rd arg to every `.attrs(callback)`. */
+export type AttrsHelpers = {
+  mode?: ThemeModeKeys
+  isDark?: boolean
+  isLight?: boolean
+  createElement: typeof render
+}
+
+/**
+ * Callback signature for `.attrs((props, theme, helpers) => …)`.
+ *
+ * `Partial<A>` on the return is for the strict-typing form when callers
+ * pass `AttrsCb<DFP, Theme<T>>` directly. In the rocketstyle `.attrs()`
+ * callback overload itself we use a different shape that decouples the
+ * props arg (narrow, full DFP) from the return type (loose — only the
+ * user's explicit `<P>` generic is checked, with `Record<string,
+ * unknown>` allowing runtime extras like `_documentProps`). See
+ * `IRocketStyleComponent.attrs` for the call-site shape.
+ */
+export type AttrsCb<A, T> = (props: Partial<A>, theme: T, helpers: AttrsHelpers) => Partial<A>

package/src/types/rocketstyle.ts

@@ -1,5 +1,5 @@
 import type { VNodeChild } from '@pyreon/core'
-import type { AttrsCb } from './attrs'
+import type { AttrsHelpers } from './attrs'
 import type { ConfigAttrs } from './config'
 import type { DefaultProps } from './configuration'
 import type {
@@ -76,7 +76,27 @@ export interface IRocketStyleComponent<
   // dimension key props
   DKP extends TDKP = TDKP,
   // calculated final props
-  DFP = MergeTypes<[OA, EA, DefaultProps, ExtractDimensionProps<D, DKP, UB>]>,
+  //
+  // `OA extends infer O` distributes over OA's union branches — future-proofs
+  // against the overload-aware `ExtractProps` (follow-up PR); for today's
+  // single-typed OA the distribution collapses to a single branch.
+  //
+  // **OA-overlapping EA keys are widened**. When `.attrs({ tag: 'a' })` sets
+  // a default for `tag` on a wrapper whose OA has `tag: HTMLTags`, we strip
+  // `tag` from OA and re-add it as `Partial<Pick<O, 'tag'>>` — taking O's
+  // WIDER type (`HTMLTags`), not EA's narrow literal `'a'`. The runtime
+  // default is `'a'`; the JSX call site still accepts any `HTMLTags` value
+  // (so `<Btn tag="span" />` is valid). `Partial<Omit<EA, keyof O>>` handles
+  // net-new EA-only keys (no OA conflict) and marks them optional too —
+  // every `.attrs()` value is semantically a default, never required of the
+  // consumer. Mirrors vitus-labs/ui-system PR #225.
+  DFP = OA extends infer O
+    ? Omit<O, keyof EA & keyof O> &
+        Partial<Pick<O, keyof EA & keyof O>> &
+        MergeTypes<
+          [Partial<Omit<EA, keyof O>>, DefaultProps, ExtractDimensionProps<D, DKP, UB>]
+        >
+    : never,
 > {
   // The component is callable — Pyreon components are plain functions
   (props: DFP): VNodeChild
@@ -95,23 +115,52 @@ export interface IRocketStyleComponent<
     : RocketStyleComponent<OA, EA, T, CSS, S, HOC, D, UB, DKP>
 
   // ATTRS chaining method
-  attrs: <P extends TObj | unknown = unknown>(
-    param: P extends TObj
-      ?
-          | Partial<DFP & P>
-          | ((
-              props: Partial<DFP & P>,
-              theme: Theme<T>,
-              helpers: any,
-            ) => Partial<P> & Record<string, unknown>)
-      : Partial<DFP> | AttrsCb<DFP, Theme<T>>,
-    config?: Partial<{
-      priority: boolean
-      filter: P extends TObj ? Partial<keyof (EA & P)>[] : Partial<keyof EA>[]
-    }>,
-  ) => P extends TObj
-    ? RocketStyleComponent<OA, MergeTypes<[EA, P]>, T, CSS, S, HOC, D, UB, DKP>
-    : RocketStyleComponent<OA, EA, T, CSS, S, HOC, D, UB, DKP>
+  //
+  // Two overloads. TS resolves in declaration order; the callback form is
+  // listed FIRST so a function argument matches it before falling through to
+  // the object form. Mirrors vitus-labs/ui-system PR #227 Issue 2 (callback
+  // overload split).
+  //
+  // **Callback overload — asymmetric props/return**: the `props` arg is
+  // typed strictly as `Partial<DFP & P>` (so reading `props.x` narrows
+  // against the wrapped component's full surface), while the RETURN is
+  // `Partial<P> & Record<string, unknown>` — only the user's explicit `<P>`
+  // generic is checked, with a wildcard for runtime extras. This preserves
+  // Pyreon's documented convention where `.attrs(callback)` returns can
+  // carry runtime-only fields (`_documentProps` markers for the document-
+  // export pipeline, `tag: 'a'` overrides on Text-based components where
+  // the rendered DOM tag is outside the component's narrow `tag` union,
+  // etc.). The runtime is loose by design — `.attrs(cb, { filter })`
+  // strips keys before forwarding to the DOM. Consumers wanting strict
+  // typed extras pass `<P>` with the precise keys they expect.
+  //
+  // **Object overload — `P & Partial<NoInfer<DFP>>`**: TS infers P from
+  // the param's keys. `NoInfer<DFP>` (TS 5.4+) prevents DFP from
+  // contributing to P inference. Combined with DFP widening above, this
+  // makes `.attrs({ tag: 'a' })` keys optional at the JSX call site —
+  // every `.attrs()` value is a default, not a required prop. Mirrors
+  // vitus-labs PR #225.
+  attrs: {
+    <P extends TObj = {}>(
+      param: (
+        props: Partial<DFP & P>,
+        theme: Theme<T>,
+        helpers: AttrsHelpers,
+      ) => Partial<P> & Record<string, unknown>,
+      config?: Partial<{
+        priority: boolean
+        filter: (keyof MergeTypes<[EA, P]>)[]
+      }>,
+    ): RocketStyleComponent<OA, MergeTypes<[EA, P]>, T, CSS, S, HOC, D, UB, DKP>
+
+    <P extends TObj = {}>(
+      param: P & Partial<NoInfer<DFP>>,
+      config?: Partial<{
+        priority: boolean
+        filter: (keyof MergeTypes<[EA, P]>)[]
+      }>,
+    ): RocketStyleComponent<OA, MergeTypes<[EA, P]>, T, CSS, S, HOC, D, UB, DKP>
+  }
 
   // THEME chaining method
   theme: <P extends TObj = TObj>(

package/src/types/styles.ts

@@ -4,7 +4,7 @@ import type { TObj } from './utils'
 
 export interface StylesDefault {}
 
-export type Styles<S = unknown> = StylesDefault
+export type Styles<_S = unknown> = StylesDefault
 
 export type Css = typeof config.css
 export type Style = ReturnType<Css>

package/src/types/utils.ts

@@ -51,5 +51,48 @@ export type Spread<A extends readonly [...any]> = A extends [infer L, ...infer R
 export type MergeTypes<A extends readonly [...any]> = ExtractNullableKeys<Spread<A>>
 
 // ─── ExtractProps ─────────────────────────────────────────────
-export type ExtractProps<TComponentOrTProps> =
-  TComponentOrTProps extends ComponentFn<infer TProps> ? TProps : TComponentOrTProps
+/**
+ * Extracts the props type from a Pyreon component function — or passes
+ * through the input unchanged when it's already a props type.
+ *
+ * Multi-overload aware: matches up to 4 call signatures and produces the
+ * UNION of their first-argument types. A single-overload function still
+ * works (the union of 4 copies of the same props type dedupes back to
+ * the single shape).
+ *
+ * **Why this shape**. `T extends (props: infer P) => any ? P : never` only
+ * captures the LAST overload of a multi-overload function — TS's overload-
+ * resolution-against-conditional-types semantics. Iterator / List / Element
+ * are 3-overload primitives where the LAST overload (`ChildrenProps`) is the
+ * loosest; without overload-aware extraction, `ExtractProps<Iterator>`
+ * returned just `ChildrenProps` and lost both `SimpleProps<T>` and
+ * `ObjectProps<T>` — wrapping Iterator through `rocketstyle()` /
+ * `attrs()` silently downgraded the public prop surface.
+ *
+ * The pattern-match shape `T extends { (props: infer P1, ...args: any): any;
+ * (props: infer P2, ...args: any): any; ... }` is the canonical TS trick
+ * for extracting overload sets — see also `Parameters<T>` semantics.
+ *
+ * Mirrors vitus-labs PR #222.
+ */
+export type ExtractProps<TComponentOrTProps> = TComponentOrTProps extends {
+  (props: infer P1, ...args: any): any
+  (props: infer P2, ...args: any): any
+  (props: infer P3, ...args: any): any
+  (props: infer P4, ...args: any): any
+}
+  ? P1 | P2 | P3 | P4
+  : TComponentOrTProps extends {
+        (props: infer P1, ...args: any): any
+        (props: infer P2, ...args: any): any
+        (props: infer P3, ...args: any): any
+      }
+    ? P1 | P2 | P3
+    : TComponentOrTProps extends {
+          (props: infer P1, ...args: any): any
+          (props: infer P2, ...args: any): any
+        }
+      ? P1 | P2
+      : TComponentOrTProps extends ComponentFn<infer TProps>
+        ? TProps
+        : TComponentOrTProps

package/src/utils/attrs.ts

@@ -3,13 +3,60 @@ import type { MultiKeys } from '../types/dimensions'
 // --------------------------------------------------------
 // remove undefined props
 // --------------------------------------------------------
-/** Strips keys with `undefined` values so they don't shadow default props during merging. */
+/**
+ * Strips keys with `undefined` values so they don't shadow default props during merging.
+ *
+ * Copies own property DESCRIPTORS rather than values so that reactive
+ * getter-shaped props (compiler-emitted `_rp(() => signal())` converted
+ * to getters by `makeReactiveProps`) survive the pipeline with their
+ * subscription intact. Reading `props[key]` here would fire the getter
+ * at HOC setup time (outside any tracking scope) and collapse the prop
+ * to a static value — every downstream JSX accessor that reads
+ * `props.x` would see the captured-once value, not the live signal.
+ *
+ * For getter descriptors we keep the descriptor as-is (the
+ * undefined-filter doesn't apply — we can't peek into the getter
+ * without firing it). For data descriptors we drop entries whose
+ * value is `undefined` to preserve the original merge semantics.
+ */
 type RemoveUndefinedProps = <T extends Record<string, any>>(props: T) => Partial<T>
 
 export const removeUndefinedProps: RemoveUndefinedProps = (props) => {
   const result: Partial<typeof props> = {}
-  for (const key in props) {
-    if (props[key] !== undefined) result[key] = props[key]
+  const descriptors = Object.getOwnPropertyDescriptors(props)
+  for (const key of Object.keys(descriptors)) {
+    const d = descriptors[key]!
+    if (d.get || d.value !== undefined) {
+      Object.defineProperty(result, key, d)
+    }
+  }
+  return result
+}
+
+// --------------------------------------------------------
+// merge descriptors
+// --------------------------------------------------------
+/**
+ * Like `Object.assign(target, ...sources)` but copies own property
+ * DESCRIPTORS instead of reading + writing values. Later sources
+ * override earlier ones (same semantics as spread / Object.assign).
+ *
+ * Required for reactive-prop preservation through the rocketstyle
+ * pipeline: a plain `{ ...A, ...B }` spread fires every getter on A
+ * and B and stores the resolved value, breaking the reactive
+ * subscription. This helper copies descriptors so getters survive
+ * the merge.
+ */
+export const mergeDescriptors = (
+  ...sources: ReadonlyArray<Record<string, any> | null | undefined>
+): Record<string, any> => {
+  const result: Record<string, any> = {}
+  for (const source of sources) {
+    if (!source) continue
+    const descriptors = Object.getOwnPropertyDescriptors(source)
+    for (const key of Object.keys(descriptors)) {
+      Object.defineProperty(result, key, descriptors[key]!)
+    }
   }
   return result
 }