@pyreon/rocketstyle 0.11.0 → 0.11.2

package/src/rocketstyle.ts

@@ -0,0 +1,320 @@
+import { compose, config, hoistNonReactStatics, omit, pick, render } from "@pyreon/ui-core"
+import { LocalThemeManager } from "./cache"
+import { CONFIG_KEYS, PSEUDO_KEYS, PSEUDO_META_KEYS, STYLING_KEYS } from "./constants"
+import createLocalProvider from "./context/createLocalProvider"
+import { useLocalContext } from "./context/localContext"
+import { rocketstyleAttrsHoc } from "./hoc"
+import { useTheme } from "./hooks"
+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 { chainOptions, chainOrOptions, chainReservedKeyOptions } from "./utils/chaining"
+import { calculateHocsFuncs } from "./utils/compose"
+import { getDimensionsMap } from "./utils/dimensions"
+import { createStaticsChainingEnhancers, createStaticsEnhancers } from "./utils/statics"
+import { calculateStyles } from "./utils/styles"
+import { getDimensionThemes, getTheme, getThemeByMode, getThemeFromChain } from "./utils/theme"
+
+/**
+ * Core rocketstyle component factory. Creates a fully-featured Pyreon component
+ * that integrates theme management (with light/dark mode support), multi-tier
+ * WeakMap caching, dimension-based styling props, pseudo-state detection, and
+ * chainable static methods (`.attrs()`, `.theme()`, `.styles()`, `.config()`, etc.).
+ *
+ * In Pyreon, components are plain functions that run once per mount.
+ * No forwardRef, useMemo, useState — ref flows as a normal prop.
+ */
+
+// --------------------------------------------------------
+// cloneAndEnhance
+// --------------------------------------------------------
+type CloneAndEnhance = (
+  defaultOpts: Configuration,
+  opts: Partial<ExtendedConfiguration>,
+) => ReturnType<typeof rocketComponent>
+
+/** Clones the current configuration and merges new options, returning a fresh rocketComponent. */
+const cloneAndEnhance: CloneAndEnhance = (defaultOpts, opts) =>
+  rocketComponent({
+    ...defaultOpts,
+    attrs: chainOptions(opts.attrs, defaultOpts.attrs),
+    filterAttrs: [...(defaultOpts.filterAttrs ?? []), ...(opts.filterAttrs ?? [])],
+    priorityAttrs: chainOptions(opts.priorityAttrs, defaultOpts.priorityAttrs),
+    statics: { ...defaultOpts.statics, ...opts.statics },
+    compose: { ...defaultOpts.compose, ...opts.compose },
+    ...chainOrOptions(CONFIG_KEYS, opts, defaultOpts),
+    ...chainReservedKeyOptions([...defaultOpts.dimensionKeys, ...STYLING_KEYS], opts, defaultOpts),
+  } as Parameters<typeof rocketComponent>[0])
+
+// --------------------------------------------------------
+// rocketComponent
+// --------------------------------------------------------
+// @ts-expect-error
+const rocketComponent: RocketComponent = (options) => {
+  const { component, styles } = options
+  const { styled } = config
+
+  const _calculateStylingAttrs = calculateStylingAttrs({
+    multiKeys: options.multiKeys,
+    useBooleans: options.useBooleans,
+  })
+
+  const componentName = options.name ?? options.component.displayName ?? options.component.name
+
+  // Create styled component with all options.styles if available.
+  // boost: true doubles the class selector so rocketstyle wrapper styles
+  // always override inner library component styles.
+  const STYLED_COMPONENT =
+    (component.IS_ROCKETSTYLE ?? options.styled !== true)
+      ? component
+      : styled(component, { boost: true })`
+          ${calculateStyles(styles)};
+        `
+
+  // --------------------------------------------------------
+  // COMPONENT - Final component to be rendered
+  // --------------------------------------------------------
+  const RenderComponent: ComponentFn<any> = options.provider
+    ? createLocalProvider(STYLED_COMPONENT)
+    : STYLED_COMPONENT
+
+  // --------------------------------------------------------
+  // THEME - Cached & Calculated theme(s)
+  // --------------------------------------------------------
+  const ThemeManager = new LocalThemeManager()
+
+  // --------------------------------------------------------
+  // COMPOSE - high-order components
+  // --------------------------------------------------------
+  const hocsFuncs = [rocketstyleAttrsHoc(options), ...calculateHocsFuncs(options.compose)]
+
+  // --------------------------------------------------------
+  // ENHANCED COMPONENT
+  // --------------------------------------------------------
+  // In Pyreon, components are plain functions — no forwardRef needed.
+  // Ref flows as a normal prop through the chain.
+  const EnhancedComponent: ComponentFn<InnerComponentProps> = (props) => {
+    // --------------------------------------------------
+    // hover - focus - pressed state passed via context from parent component
+    // --------------------------------------------------
+    const localCtx = useLocalContext(options.consumer)
+
+    // --------------------------------------------------
+    // general theme and theme mode dark / light passed in context
+    // --------------------------------------------------
+    const { theme, mode } = useTheme(options)
+
+    // --------------------------------------------------
+    // calculate themes for all defined styling dimensions
+    // --------------------------------------------------
+
+    // BASE / DEFAULT THEME Object (cached by theme identity)
+    const baseThemeHelper = ThemeManager.baseTheme
+    if (!baseThemeHelper.has(theme)) {
+      baseThemeHelper.set(theme, getThemeFromChain(options.theme, theme))
+    }
+    const baseTheme = baseThemeHelper.get(theme)
+
+    // DIMENSION(S) THEMES Object (cached by theme identity)
+    const dimHelper = ThemeManager.dimensionsThemes
+    if (!dimHelper.has(theme)) {
+      dimHelper.set(theme, getDimensionThemes(theme, options))
+    }
+    const themes = dimHelper.get(theme)
+
+    // BASE / DEFAULT MODE THEME Object (cached by mode + baseTheme)
+    const modeBaseHelper = ThemeManager.modeBaseTheme[mode]
+    if (!modeBaseHelper.has(baseTheme)) {
+      modeBaseHelper.set(baseTheme, getThemeByMode(baseTheme, mode))
+    }
+    const currentModeBaseTheme = modeBaseHelper.get(baseTheme)
+
+    // DIMENSION(S) MODE THEMES Object (cached by mode + themes)
+    const modeDimHelper = ThemeManager.modeDimensionTheme[mode]
+    if (!modeDimHelper.has(themes)) {
+      modeDimHelper.set(themes, getThemeByMode(themes, mode))
+    }
+    const currentModeThemes = modeDimHelper.get(themes)
+
+    // --------------------------------------------------
+    // dimension map & reserved prop names
+    // --------------------------------------------------
+    const { keysMap: dimensions, keywords: reservedPropNames } = getDimensionsMap({
+      themes,
+      useBooleans: options.useBooleans,
+    })
+
+    const RESERVED_STYLING_PROPS_KEYS = Object.keys(reservedPropNames)
+
+    // --------------------------------------------------
+    // get final props: merged styling from context + attrs + direct props
+    // --------------------------------------------------
+    const { pseudo, ...mergeProps } = {
+      ...localCtx,
+      ...props,
+    }
+
+    // --------------------------------------------------
+    // pseudo rocket state
+    // --------------------------------------------------
+    const pseudoRocketstate = {
+      ...pseudo,
+      ...pick(props, [...PSEUDO_KEYS, ...PSEUDO_META_KEYS]),
+    }
+
+    // --------------------------------------------------
+    // rocketstate — active dimension values
+    // --------------------------------------------------
+    const rocketstate = _calculateStylingAttrs({
+      props: pickStyledAttrs(mergeProps, reservedPropNames),
+      dimensions,
+    })
+
+    const finalRocketstate = { ...rocketstate, pseudo: pseudoRocketstate }
+
+    // --------------------------------------------------
+    // rocketstyle — computed theme based on active dimensions
+    // --------------------------------------------------
+    const computedRocketstyle = getTheme({
+      rocketstate,
+      themes: currentModeThemes,
+      baseTheme: currentModeBaseTheme,
+      transformKeys: options.transformKeys,
+      appTheme: theme,
+    })
+
+    // --------------------------------------------------
+    // final props passed to WrappedComponent
+    // --------------------------------------------------
+    const finalProps: Record<string, any> = {
+      ...omit(mergeProps, [...RESERVED_STYLING_PROPS_KEYS, ...PSEUDO_KEYS, ...options.filterAttrs]),
+      ...(options.passProps ? pick(mergeProps, options.passProps) : {}),
+      // ref flows as a normal prop in Pyreon
+      ref: props.ref,
+      $rocketstyle: computedRocketstyle,
+      $rocketstate: finalRocketstate,
+    }
+
+    // development debugging
+    if (process.env.NODE_ENV !== "production") {
+      finalProps["data-rocketstyle"] = componentName
+
+      if (options.DEBUG) {
+        const debugPayload = {
+          component: componentName,
+          rocketstate: finalRocketstate,
+          rocketstyle: computedRocketstyle,
+          dimensions,
+          mode,
+          reservedPropNames: RESERVED_STYLING_PROPS_KEYS,
+          filteredAttrs: options.filterAttrs,
+        }
+
+        // biome-ignore lint/suspicious/noConsole: debug logging controlled by DEBUG option
+        console.debug(`[rocketstyle] ${componentName} render:`, debugPayload)
+      }
+    }
+
+    return RenderComponent(finalProps)
+  }
+
+  // ------------------------------------------------------
+  // Compose HOC chain and create final component
+  // ------------------------------------------------------
+  const FinalComponent: RocketStyleComponent = compose(...hocsFuncs)(EnhancedComponent)
+  FinalComponent.IS_ROCKETSTYLE = true
+  FinalComponent.displayName = componentName
+
+  hoistNonReactStatics(FinalComponent as Record<string, unknown>, options.component)
+
+  // ------------------------------------------------------
+  // enhance for chaining methods
+  // ------------------------------------------------------
+  createStaticsChainingEnhancers({
+    context: FinalComponent,
+    dimensionKeys: options.dimensionKeys,
+    func: cloneAndEnhance,
+    options,
+  })
+
+  FinalComponent.IS_ROCKETSTYLE = true
+  FinalComponent.displayName = componentName
+  FinalComponent.meta = {}
+
+  // ------------------------------------------------------
+  // enhance for statics
+  // ------------------------------------------------------
+  createStaticsEnhancers({
+    context: FinalComponent.meta,
+    options: options.statics,
+  })
+
+  // Also assign statics directly onto the component so they are
+  // discoverable via `"key" in Component` checks (e.g. _documentType).
+  createStaticsEnhancers({
+    context: FinalComponent,
+    options: options.statics,
+  })
+
+  Object.assign(FinalComponent, {
+    attrs: (attrs: any, { priority, filter }: any = {}) => {
+      const result: Record<string, any> = {}
+
+      if (filter) {
+        result.filterAttrs = filter
+      }
+
+      if (priority) {
+        result.priorityAttrs = attrs as ExtendedConfiguration["priorityAttrs"]
+
+        return cloneAndEnhance(options, result)
+      }
+
+      result.attrs = attrs as ExtendedConfiguration["attrs"]
+
+      return cloneAndEnhance(options, result)
+    },
+
+    config: (opts: any = {}) => {
+      const result = pick(opts, CONFIG_KEYS) as ExtendedConfiguration
+
+      return cloneAndEnhance(options, result)
+    },
+
+    statics: (opts: any) => cloneAndEnhance(options, { statics: opts }),
+
+    getStaticDimensions: (theme: any) => {
+      const themes = getDimensionThemes(theme, options)
+
+      const { keysMap, keywords } = getDimensionsMap({
+        themes,
+        useBooleans: options.useBooleans,
+      })
+
+      return {
+        dimensions: keysMap,
+        keywords,
+        useBooleans: options.useBooleans,
+        multiKeys: options.multiKeys,
+      }
+    },
+
+    getDefaultAttrs: (props: any, theme: any, mode: any) =>
+      calculateChainOptions(options.attrs)([
+        props,
+        theme,
+        {
+          render,
+          mode,
+          isDark: mode === "light",
+          isLight: mode === "dark",
+        },
+      ]),
+  })
+
+  return FinalComponent
+}
+
+export default rocketComponent

package/src/types/attrs.ts

@@ -0,0 +1,13 @@
+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>

package/src/types/config.ts

@@ -0,0 +1,48 @@
+import type { DimensionBooleanAttrs, Dimensions, ExtractDimensions, TDKP } from "./dimensions"
+import type { PseudoState } from "./pseudo"
+import type { ElementType, TObj } from "./utils"
+
+// --------------------------------------------------------
+// CONFIG
+// --------------------------------------------------------
+export type RocketComponentType = ElementType & {
+  IS_ROCKETSTYLE: true
+  $$rocketstyle: Record<string, unknown>
+}
+
+export type RocketProviderState<T extends RocketComponentType | TObj | unknown = unknown> =
+  T extends RocketComponentType ? Partial<T["$$rocketstyle"]> & { pseudo: PseudoState } : T
+
+export type ConsumerCtxCBValue<
+  T extends RocketComponentType,
+  D extends Dimensions,
+  DKP extends TDKP,
+> = (
+  attrs: RocketProviderState<T>,
+) => DKP extends TDKP ? Partial<ExtractDimensions<D, DKP> & { pseudo: PseudoState }> : TObj
+
+export type ConsumerCtxCb<D extends Dimensions, DKP extends TDKP = TDKP> = <
+  T extends RocketComponentType,
+>(
+  attrs: ConsumerCtxCBValue<T, D, DKP>,
+) => ReturnType<ConsumerCtxCBValue<T, D, DKP>>
+
+export type ConsumerCb<D extends Dimensions, DKP extends TDKP = TDKP> = (
+  ctx: ConsumerCtxCb<D, DKP>,
+) => ReturnType<ConsumerCtxCb<D, DKP>>
+
+export type ConfigAttrs<
+  C extends ElementType | unknown,
+  D extends Dimensions,
+  DKP extends TDKP,
+  UB extends boolean,
+> = Partial<{
+  name: string
+  component: C
+  provider: boolean
+  consumer: ConsumerCb<D, DKP>
+  DEBUG: boolean
+  inversed: boolean
+  passProps: UB extends true ? keyof DimensionBooleanAttrs<D, DKP>[] : never
+  styled: boolean
+}>

package/src/types/configuration.ts

@@ -0,0 +1,69 @@
+import type { ConsumerCb } from "./config"
+import type { Dimensions, MultiKeys } from "./dimensions"
+import type { PseudoProps } from "./pseudo"
+import type { StylesCbArray } from "./styles"
+import type { ArrayOfKeys, ArrayOfValues, ElementType, TFn } from "./utils"
+
+export type __ROCKETSTYLE__ = {
+  dimensions: Record<string, string>
+  reservedPropNames: Record<string, true>
+  baseTheme: Record<string, unknown>
+  themes: Record<string, unknown>
+}
+
+export type OptionFunc = (...arg: unknown[]) => Record<string, unknown>
+
+export type InitConfiguration<C, D> = {
+  name?: string | undefined
+  component: C
+  useBooleans: boolean
+  dimensions: D
+  dimensionKeys: ArrayOfKeys<D>
+  dimensionValues: ArrayOfValues<D>
+  multiKeys: MultiKeys
+  transformKeys: Partial<Record<string, true>>
+}
+
+export type Configuration<
+  C = ElementType | unknown,
+  D extends Dimensions = Dimensions,
+> = InitConfiguration<C, D> & {
+  provider?: boolean | undefined
+  consumer?: ConsumerCb<D> | undefined
+  DEBUG?: boolean | undefined
+  inversed?: boolean | undefined
+  passProps?: string[] | undefined
+  styled?: boolean | undefined
+
+  // array chaining options
+  attrs: OptionFunc[]
+  priorityAttrs: OptionFunc[]
+  filterAttrs: string[]
+  theme: OptionFunc[]
+  styles: StylesCbArray
+  compose: Record<string, TFn | null | undefined | false>
+  statics: Record<string, any>
+} & Record<string, any>
+
+export type ExtendedConfiguration<
+  C = ElementType | unknown,
+  D extends Dimensions = Dimensions,
+> = InitConfiguration<C, D> & {
+  provider?: boolean | undefined
+  consumer?: ConsumerCb<D> | undefined
+  DEBUG?: boolean | undefined
+  inversed?: boolean | undefined
+  passProps?: string[] | undefined
+  styled?: boolean | undefined
+
+  // array chaining options
+  attrs: OptionFunc
+  priorityAttrs: OptionFunc
+  filterAttrs: string[]
+  theme: OptionFunc
+  styles: StylesCbArray
+  compose: Record<string, TFn | null | undefined | false>
+  statics: Record<string, any>
+} & Record<string, any>
+
+export type DefaultProps = Partial<PseudoProps>

package/src/types/dimensions.ts

@@ -0,0 +1,106 @@
+import type { DefaultDimensions } from "../constants/defaultDimensions"
+import type { Css } from "./styles"
+import type { ThemeModeCallback } from "./theme"
+import type { CallBackParam, NullableKeys, ReturnCbParam, Spread, TObj, ValueOf } from "./utils"
+
+export type { DefaultDimensions }
+
+export type ExtractNullableDimensionKeys<T> = {
+  [P in keyof T as T[P] extends false ? never : P]: T[P]
+}
+
+export type ExtractDimensionKey<T extends DimensionValue> = T extends DimensionValueObj
+  ? T["propName"]
+  : T
+
+export type ExtractDimensionMulti<T extends DimensionValue> = T extends DimensionValueObj
+  ? true
+  : false
+
+export type ExtractDimensionAttrsKeys<D extends Dimensions> = {
+  [I in keyof D]: ExtractDimensionKey<D[I]>
+}[keyof D]
+
+export type DimensionValuePrimitive = string
+export type DimensionValueObj = {
+  propName: string
+  multi?: boolean
+  /** When true, this dimension is evaluated last and its values receive the accumulated theme as argument. */
+  transform?: boolean
+}
+
+export type DimensionValue = DimensionValuePrimitive | DimensionValueObj
+export type Dimensions = Record<string, DimensionValue>
+
+export type MultiKeys<T extends Dimensions = Dimensions> = Partial<
+  Record<ExtractDimensionKey<T[keyof T]>, true>
+>
+
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends (...args: any[]) => any
+    ? T[K]
+    : NonNullable<T[K]> extends Record<string, any>
+      ? DeepPartial<NonNullable<T[K]>> | Extract<T[K], null>
+      : T[K]
+}
+
+export type DimensionResult<CT, T = any> = Record<
+  string,
+  | boolean
+  | null
+  | DeepPartial<CT>
+  | ((theme: CT, appTheme: T, mode: ThemeModeCallback, css: Css) => DeepPartial<CT>)
+>
+export type DimensionObj<CT, T = any> = DimensionResult<CT, T>
+
+export type DimensionCb<T, CT> = (
+  theme: T,
+  mode: ThemeModeCallback,
+  css: Css,
+) => DimensionResult<CT, T>
+
+export type DimensionCallbackParam<T, CT> = DimensionObj<CT, T> | DimensionCb<T, CT>
+
+export type DimensionReturn<P, A> = P extends TObj ? A & P : A
+
+export type TDKP = Record<string, unknown>
+
+export type DimensionProps<
+  K extends DimensionValue,
+  D extends Dimensions,
+  P extends CallBackParam,
+  DKP extends TDKP,
+> = {
+  [I in ExtractDimensionKey<D[keyof D]>]: I extends ExtractDimensionKey<K>
+    ? ExtractNullableDimensionKeys<Spread<[DKP[I], NullableKeys<ReturnCbParam<P>>]>>
+    : DKP[I]
+}
+
+type DimensionTypesHelper<D extends Dimensions, DKP extends TDKP> = {
+  [I in ExtractDimensionKey<D[keyof D]> & keyof DKP]: keyof DKP[I]
+}
+
+export type DimensionObjAttrs<D extends Dimensions, DKP extends TDKP> = {
+  [I in ExtractDimensionKey<D[keyof D]> & keyof DKP]: ExtractDimensionMulti<
+    D[I & keyof D]
+  > extends true
+    ? Array<keyof DKP[I]>
+    : keyof DKP[I]
+}
+
+export type DimensionBooleanAttrs<D extends Dimensions, DKP extends TDKP> = Partial<
+  Record<ValueOf<DimensionTypesHelper<D, DKP>>, boolean>
+>
+
+export type ExtractDimensionProps<
+  D extends Dimensions,
+  DKP extends TDKP,
+  UB extends boolean,
+> = UB extends true
+  ? Partial<ExtractNullableDimensionKeys<DimensionObjAttrs<D, DKP> & DimensionBooleanAttrs<D, DKP>>>
+  : Partial<ExtractNullableDimensionKeys<DimensionObjAttrs<D, DKP>>>
+
+export type ExtractDimensions<
+  D extends Dimensions,
+  DKP extends TDKP,
+> = ExtractNullableDimensionKeys<DimensionObjAttrs<D, DKP>>

package/src/types/hoc.ts

@@ -0,0 +1,5 @@
+import type { ElementType } from "./utils"
+
+export type GenericHoc = (component: ElementType) => ElementType
+
+export type ComposeParam = Record<string, GenericHoc | null | undefined | false>

package/src/types/pseudo.ts

@@ -0,0 +1,19 @@
+export type PseudoActions = {
+  onMouseEnter: (e: MouseEvent) => void
+  onMouseLeave: (e: MouseEvent) => void
+  onMouseDown: (e: MouseEvent) => void
+  onMouseUp: (e: MouseEvent) => void
+  onFocus: (e: FocusEvent) => void
+  onBlur: (e: FocusEvent) => void
+}
+
+export type PseudoState = {
+  active: boolean
+  hover: boolean
+  focus: boolean
+  pressed: boolean
+  disabled: boolean
+  readOnly: boolean
+}
+
+export type PseudoProps = Partial<PseudoState & PseudoActions>

package/src/types/rocketComponent.ts

@@ -0,0 +1,24 @@
+import type { Configuration } from "./configuration"
+import type { DefaultDimensions, Dimensions } from "./dimensions"
+import type { RocketStyleComponent } from "./rocketstyle"
+import type { ElementType, ExtractProps, TObj } from "./utils"
+
+export type RocketComponent<
+  C extends ElementType = ElementType,
+  T extends TObj = {},
+  CSS extends TObj = {},
+  D extends Dimensions = DefaultDimensions,
+  UB extends boolean = boolean,
+> = (props: Configuration<C, D>) => RocketStyleComponent<
+  // keep original component props + extract dimension props
+  ExtractProps<C>,
+  // set default extending props
+  {},
+  T,
+  CSS,
+  {},
+  {},
+  D,
+  UB,
+  {}
+>