Provider & Consumer

Rocketstyle includes a provider/consumer system for broadcasting pseudo-states between parent and child components, plus theme context management for light/dark mode.

Pseudo-States

Rocketstyle automatically tracks these pseudo-states:

State	Type	Auto-Tracked	Description
`hover`	`boolean`	Yes (mouseenter/mouseleave)	Mouse is over the element
`focus`	`boolean`	Yes (focus/blur)	Element has keyboard focus
`pressed`	`boolean`	Yes (mousedown/mouseup)	Mouse button is held down
`active`	`boolean`	No (manual only)	Element is in active state
`disabled`	`boolean`	No (manual only)	Element is disabled
`readOnly`	`boolean`	No (manual only)	Element is read-only

usePseudoState Hook

The usePseudoState hook manages automatic tracking internally:

const { state, events } = usePseudoState({
  onMouseEnter,   // Wraps user callback
  onMouseLeave,
  onMouseDown,
  onMouseUp,
  onFocus,
  onBlur,
})
// state: { hover: boolean, focus: boolean, pressed: boolean }
// events: { onMouseEnter, onMouseLeave, onMouseDown, onMouseUp, onFocus, onBlur }

Each wrapped event handler:

Updates the internal pseudo-state
Calls the user-provided callback (if any)

Special behavior: onMouseLeave also resets pressed to false (in addition to hover).

Accessing Pseudo-States in Styles

.styles((css) => css`
  ${({ $rocketstate }) => {
    const { hover, focus, pressed, disabled } = $rocketstate.pseudo

    if (disabled) {
      return css`
        opacity: 0.5;
        cursor: not-allowed;
      `
    }

    if (hover && !disabled) {
      return css`background-color: darkblue;`
    }

    if (focus) {
      return css`outline: 2px solid blue;`
    }
  }}
`)

Manual Pseudo-State Control

Override pseudo-states via props:

<Button hover={true} />     // Force hover appearance
<Button disabled={true} />  // Force disabled state
<Button focus={true} />     // Force focus appearance

Manual props merge with auto-tracked states — explicit props take priority. The pseudo-state object is constructed as:

{
  ...contextPseudo,              // From parent provider (if consumer)
  ...pick(props, pseudoKeys),    // hover, active, focus, pressed
  ...pick(props, metaKeys),      // disabled, readOnly
}

Provider Component

Enable a component to broadcast its pseudo-states to children:

const FormField = rocketstyle()({
  name: 'FormField',
  component: 'div',
}).config({
  provider: true,  // Enables pseudo-state broadcasting
})

How Provider Works

When provider: true, the component is wrapped with a createLocalProvider HOC that:

Intercepts mouse/focus events via usePseudoState()
Merges tracked pseudo-states into $rocketstate
Wraps children with <LocalProvider value={updatedState}>
Passes the wrapped events to the underlying component

// Simplified internal structure:
const ProviderHOC = (WrappedComponent) =>
  forwardRef((props, ref) => {
    const { state: pseudoState, events } = usePseudoState(props)

    const updatedState = {
      ...$rocketstate,
      pseudo: { ...$rocketstate.pseudo, ...pseudoState },
    }

    return (
      <LocalProvider value={updatedState}>
        <WrappedComponent {...props} {...events} ref={ref} $rocketstate={updatedState} />
      </LocalProvider>
    )
  })

The useStableValue() hook ensures the context value reference is stable (only changes when content changes), preventing unnecessary re-renders in consumers.

Consumer Component

Enable a component to read its parent's pseudo-states:

const FormLabel = rocketstyle()({
  name: 'FormLabel',
  component: 'label',
}).config({
  consumer: (ctx) =>
    ctx((parentProps) => ({
      parentHover: parentProps.pseudo?.hover,
      parentFocus: parentProps.pseudo?.focus,
      parentDisabled: parentProps.pseudo?.disabled,
    })),
})

Consumer Callback Signature

consumer: (ctx) => ctx((parentState) => mappedProps)

The callback receives a ctx function. You call ctx with a mapper function that:

Receives the parent's full $rocketstate (dimension values + pseudo-states)
Returns an object that is merged into the consumer's props

Parameter	Type	Description
`parentState.pseudo`	`Partial<PseudoState>`	Parent's pseudo-states
`parentState.[dimension]`	`string \| string[]`	Parent's active dimension values

useLocalContext Hook

Internally, the consumer reads the context via useLocalContext:

const useLocalContext = (consumer) => {
  const ctx = useContext(context)

  if (!consumer) return { pseudo: {} }

  const result = consumer((callback) => callback(ctx))
  return { pseudo: {}, ...result }
}

When no consumer is configured, returns { pseudo: {} } — no parent state is read.