@hanzogui/web 2.0.0

package/src/helpers/mergeProps.ts

@@ -0,0 +1,121 @@
+/**
+ * Preserves prop ordering, so that the order most closely matches the last spread objects
+ * Useful for having { ...defaultProps, ...props } that ensure props ordering is always kept
+ *
+ * Honestly this is somehwat backwards logically from Object.assign, reason was that we typically
+ * are merging defaultProps, givenProps, but we started using it elsewhere and now its a bit confusing
+ * Should look into refactoring this to match common usage
+ *
+ * Merges sub-objects if they start are pseudo-keys or media-key-like (start with "$")
+ *
+ *    Given:
+ *      mergeProps({ a: 1, b: 2 }, { b: 1, a: 2 })
+ *    The final key order will be:
+ *      b, a
+ *
+ */
+
+import { pseudoDescriptors } from './pseudoDescriptors'
+
+export type GenericProps = Record<string, any>
+
+export const mergeProps = (defaultProps: object, props: object) => {
+  const out: GenericProps = {}
+
+  // in general objects keys are sorted by order of insertion
+  // we merge "defaultProps" first as they should come first
+  // (so Object.keys(finalProps) will list [...defaultPropKeys] first)
+  // but we ignore any keys from props, and merge it after, that way
+  // final order is [...defaultPropKeys, ...propKeys]
+
+  // ⚠️ keep in sync with mergeComponentProps logic
+
+  for (const key in defaultProps) {
+    if (key in props) continue
+    out[key] = defaultProps[key]
+  }
+
+  for (const key in props) {
+    mergeProp(out, defaultProps, props, key)
+  }
+
+  return out
+}
+
+// merge props but also handles defaultProps + styledContext
+export const mergeComponentProps = (
+  // this is "a" in mergeProps
+  defaultProps: object | null | undefined,
+  contextProps: object | undefined,
+  // this is "b" in mergeProps
+  props: object
+) => {
+  let overriddenContext: GenericProps | null = null
+
+  if (!defaultProps && !contextProps) {
+    return [props, overriddenContext] as const
+  }
+
+  if (defaultProps && !contextProps) {
+    return [mergeProps(defaultProps, props), overriddenContext] as const
+  }
+
+  // the only unique case is contextProps, we need to track overrides and do something a bit tricky
+  // since we respect prop order for styles, we want to preserve the object key order in overriddenContext
+
+  const out: GenericProps = {}
+
+  // ⚠️ keep in sync with mergeProps logic
+  // same logic as mergeProps but tracking overrides!
+
+  for (const key in defaultProps) {
+    if (key in props) continue
+    out[key] = defaultProps[key]
+  }
+
+  // styled context props go after defaultProps but before props
+  for (const key in contextProps) {
+    if (key in props) continue
+    const contextValue = contextProps[key]
+    // don't merge undefined context values to preserve inheritance
+    if (contextValue !== undefined) {
+      out[key] = contextValue
+    }
+  }
+
+  for (const key in props) {
+    mergeProp(out, defaultProps, props, key)
+    if (contextProps && key in contextProps) {
+      overriddenContext ||= {}
+      overriddenContext[key] = props[key]
+    }
+  }
+
+  return [out, overriddenContext] as const
+}
+
+function mergeProp(
+  out: object,
+  defaultProps: object | undefined | null,
+  props: object,
+  key: string
+) {
+  let val = props[key]
+
+  // one special case - we merge hanzo-gui style sub-objects
+  if (
+    defaultProps &&
+    key in defaultProps &&
+    (key in pseudoDescriptors || key[0] === '$') &&
+    val &&
+    typeof val === 'object'
+  ) {
+    const defaultVal = defaultProps[key]
+    if (defaultVal && typeof defaultVal === 'object') {
+      // use merge props so we prefer the key ordering the the last merged
+      val = mergeProps(defaultVal, val)
+    }
+  }
+
+  out[key] = val
+}

package/src/helpers/mergeRenderElementProps.ts

@@ -0,0 +1,17 @@
+import { mergeSlotStyleProps } from './mergeSlotStyleProps'
+
+/**
+ * Merges props from a render element with viewProps from Gui.
+ * viewProps takes precedence, elementProps provides fallbacks.
+ * Style/className are merged, refs and event handlers are composed.
+ */
+export function mergeRenderElementProps(
+  elementProps: Record<string, any>,
+  viewProps: Record<string, any>,
+  children: any
+): Record<string, any> {
+  // elementProps as base, viewProps as overlay (viewProps wins)
+  const merged = mergeSlotStyleProps({ ...elementProps }, viewProps)
+  merged.children = children
+  return merged
+}

package/src/helpers/mergeSlotStyleProps.ts

@@ -0,0 +1,46 @@
+import { composeRefs } from '@hanzogui/compose-refs'
+import { composeEventHandlers } from '@hanzogui/helpers'
+
+const isEventHandler = /^on[A-Z]/
+
+/**
+ * Merges props with special handling for style, className, ref, and event handlers.
+ * Used by Slot and render prop implementations.
+ *
+ * @param base - Base props (typically from parent/slot)
+ * @param overlay - Props to merge on top (typically from child/element)
+ * @returns Merged props object (mutates and returns base for perf)
+ */
+export function mergeSlotStyleProps(
+  base: Record<string, any>,
+  overlay: Record<string, any>
+): Record<string, any> {
+  for (const key in overlay) {
+    const baseVal = base[key]
+    const overlayVal = overlay[key]
+
+    if (overlayVal === undefined) continue
+
+    if (key === 'style') {
+      base.style =
+        baseVal && overlayVal ? { ...baseVal, ...overlayVal } : overlayVal || baseVal
+    } else if (key === 'className') {
+      base.className =
+        baseVal && overlayVal ? `${baseVal} ${overlayVal}` : overlayVal || baseVal
+    } else if (key === 'ref') {
+      base.ref =
+        baseVal && overlayVal ? composeRefs(baseVal, overlayVal) : overlayVal || baseVal
+    } else if (
+      isEventHandler.test(key) &&
+      typeof baseVal === 'function' &&
+      typeof overlayVal === 'function'
+    ) {
+      base[key] = composeEventHandlers(baseVal, overlayVal)
+    } else {
+      // overlay wins for regular props
+      base[key] = overlayVal
+    }
+  }
+
+  return base
+}

package/src/helpers/mergeVariants.ts

@@ -0,0 +1,40 @@
+import type { GenericVariantDefinitions } from '../types'
+
+// deep merge variants
+// except for functions which override any parents
+
+export const mergeVariants = (
+  parentVariants: GenericVariantDefinitions,
+  ourVariants: GenericVariantDefinitions,
+  level = 0
+) => {
+  const variants = {}
+
+  for (const key in ourVariants) {
+    const parentVariant = parentVariants?.[key]
+    const ourVariant = ourVariants[key]
+    if (!parentVariant || typeof ourVariant === 'function') {
+      variants[key] = ourVariant
+    } else if (parentVariant && !ourVariant) {
+      variants[key] = parentVariant[key]
+    } else {
+      if (level === 0) {
+        variants[key] = mergeVariants(
+          parentVariant as Record<string, any>,
+          ourVariant as Record<string, any>,
+          level + 1
+        )
+      } else {
+        variants[key] = {
+          ...parentVariant,
+          ...ourVariant,
+        }
+      }
+    }
+  }
+
+  return {
+    ...parentVariants,
+    ...variants,
+  }
+}

package/src/helpers/nativeOnlyProps.ts

@@ -0,0 +1,38 @@
+/**
+ * Native-only props that should be skipped on web (both dev and prod)
+ */
+export const nativeOnlyProps = {
+  accessibilityElementsHidden: 1,
+  accessibilityIgnoresInvertColors: 1,
+  accessibilityLanguage: 1,
+  adjustsFontSizeToFit: 1,
+  allowFontScaling: 1,
+  android_hyphenationFrequency: 1,
+  dataDetectorType: 1,
+  dynamicTypeRamp: 1,
+  elevationAndroid: 1,
+  ellipsizeMode: 1,
+  hapticFeedback: 1,
+  hapticStyle: 1,
+  hitSlop: 1,
+  importantForAccessibility: 1,
+  lineBreakStrategyIOS: 1,
+  maxFontSizeMultiplier: 1,
+  minimumFontScale: 1,
+  needsOffscreenAlphaCompositing: 1,
+  nextFocusDown: 1,
+  nextFocusForward: 1,
+  nextFocusLeft: 1,
+  nextFocusRight: 1,
+  nextFocusUp: 1,
+  onAccessibilityAction: 1,
+  onAccessibilityEscape: 1,
+  onAccessibilityTap: 1,
+  onMagicTap: 1,
+  onTextLayout: 1,
+  pressRetentionOffset: 1,
+  selectionColor: 1,
+  shouldRasterizeIOS: 1,
+  suppressHighlighting: 1,
+  textBreakStrategy: 1,
+}

package/src/helpers/normalizeColor.native.ts

@@ -0,0 +1,29 @@
+import { normalizeCSSColor, rgba } from '@hanzogui/normalize-css-color'
+
+export { rgba } from '@hanzogui/normalize-css-color'
+
+export const normalizeColor = (color?: string | null, opacity?: number) => {
+  if (!color) return
+  // handle dynamic color objects (from $theme-dark/$theme-light)
+  if (typeof color !== 'string') return color
+  if (color[0] === '$') return color
+
+  const rgbaVal = getRgba(color)
+  if (rgbaVal) {
+    const colors = `${rgbaVal.r},${rgbaVal.g},${rgbaVal.b}`
+    return opacity === 1
+      ? `rgb(${colors})`
+      : `rgba(${colors},${opacity ?? rgbaVal.a ?? 1})`
+  }
+
+  return color
+}
+
+export const getRgba = (color: string) => {
+  // handle dynamic color objects (from $theme-dark/$theme-light)
+  if (typeof color !== 'string') return
+  const colorNum = normalizeCSSColor(color)
+  if (colorNum != null) {
+    return rgba(colorNum)
+  }
+}

package/src/helpers/normalizeColor.ts

@@ -0,0 +1,29 @@
+// web: use color-mix for opacity (CSS-native, works with variables and named colors)
+// animation drivers that need rgba handle their own conversion
+
+import { normalizeCSSColor, rgba } from '@hanzogui/normalize-css-color'
+
+export const normalizeColor = (color?: string | null, opacity?: number) => {
+  if (!color) return
+  if (typeof color !== 'string') return color
+
+  if (color === 'transparent') {
+    return 'rgba(0, 0, 0, 0)'
+  }
+
+  if (typeof opacity === 'number' && opacity < 1) {
+    return `color-mix(in srgb, ${color} ${Math.round(opacity * 100)}%, transparent)`
+  }
+
+  return color
+}
+
+export const getRgba = (
+  color: string
+): { r: number; g: number; b: number; a: number } | undefined => {
+  if (typeof color !== 'string') return
+  const colorNum = normalizeCSSColor(color)
+  if (colorNum != null) {
+    return rgba(colorNum)
+  }
+}

package/src/helpers/normalizeShadow.native.ts

@@ -0,0 +1,20 @@
+import { defaultOffset } from './defaultOffset'
+import { getRgba, normalizeColor } from './normalizeColor'
+
+export function normalizeShadow({
+  shadowColor,
+  shadowOffset,
+  shadowOpacity,
+  shadowRadius,
+}: Record<string, any>) {
+  const { height, width } = shadowOffset || defaultOffset
+  return {
+    shadowOffset: {
+      width: width || 0,
+      height: height || 0,
+    },
+    shadowRadius: shadowRadius || 0,
+    shadowColor: normalizeColor(shadowColor, 1),
+    shadowOpacity: shadowOpacity ?? (shadowColor ? getRgba(shadowColor)?.a : 1),
+  }
+}

package/src/helpers/normalizeShadow.ts

@@ -0,0 +1,21 @@
+import { defaultOffset } from './defaultOffset'
+
+export function normalizeShadow({
+  shadowColor,
+  shadowOffset,
+  shadowOpacity,
+  shadowRadius,
+}: Record<string, any>) {
+  const { height, width } = shadowOffset || defaultOffset
+  return {
+    shadowOffset: {
+      width: width || 0,
+      height: height || 0,
+    },
+    shadowRadius: shadowRadius || 0,
+    // pass color through as-is, opacity applied via color-mix in getCSSStylesAtomic
+    shadowColor: shadowColor,
+    // default to 1 if not specified (color-mix will handle the opacity)
+    shadowOpacity: shadowOpacity ?? 1,
+  }
+}

package/src/helpers/normalizeStyle.ts

@@ -0,0 +1,42 @@
+import { expandStyle } from './expandStyle'
+import { fixStyles } from './expandStyles'
+import { isObj } from './isObj'
+import { normalizeValueWithProperty } from './normalizeValueWithProperty'
+import { pseudoDescriptors } from './pseudoDescriptors'
+
+/**
+ * This is what you want to run before Object.assign() a style onto another.
+ * It does the following:
+ *   1. Shorthands into longhands, px = paddingHorizontal
+ *   2. Expands flex, borderColor and other properties that can expand into sub-parts
+ *   3. Normalizes all sub pseudo-media-etc styles
+ */
+
+export function normalizeStyle(style: Record<string, any>, disableNormalize = false) {
+  const res: Record<string, any> = {}
+
+  for (let key in style) {
+    const prop = style[key]
+    if (prop == null) continue
+    if (
+      key in pseudoDescriptors ||
+      // this should capture all parent-based styles like media, group, etc
+      (key[0] === '$' && isObj(prop))
+    ) {
+      res[key] = normalizeStyle(prop, disableNormalize)
+      continue
+    }
+    const value = disableNormalize ? prop : normalizeValueWithProperty(prop, key)
+    // expand react-native shorthands
+    const out = expandStyle(key, value)
+    if (out) {
+      Object.assign(res, Object.fromEntries(out))
+    } else {
+      res[key] = value
+    }
+  }
+
+  fixStyles(res)
+
+  return res
+}

package/src/helpers/normalizeStylePropKeys.native.ts

@@ -0,0 +1,12 @@
+export const normalizeStylePropKeys = {
+  backgroundColor: true,
+  borderColor: true,
+  borderTopColor: true,
+  borderRightColor: true,
+  borderBottomColor: true,
+  borderLeftColor: true,
+  color: true,
+  shadowColor: true,
+  textDecorationColor: true,
+  textShadowColor: true,
+}

package/src/helpers/normalizeStylePropKeys.ts

@@ -0,0 +1,3 @@
+// none for web, all for native
+
+export const normalizeStylePropKeys = {}

package/src/helpers/normalizeValueWithProperty.ts

@@ -0,0 +1,41 @@
+/**
+ * Some parts adapted from react-native-web
+ * Copyright (c) Nicolas Gallagher licensed under the MIT license.
+ */
+
+import { isWeb } from '@hanzogui/constants'
+import { stylePropsAll, stylePropsUnitless } from '@hanzogui/helpers'
+
+// only doing this on web on native it accepts pixel values
+
+const stylePropsAllPlusTransforms = {
+  ...stylePropsAll,
+  translateX: true,
+  translateY: true,
+}
+
+export function normalizeValueWithProperty(value: any, property = ''): any {
+  if (!isWeb) return value
+  if (
+    stylePropsUnitless[property] ||
+    (property && !stylePropsAllPlusTransforms[property]) ||
+    typeof value === 'boolean'
+  ) {
+    return value
+  }
+  if (value && typeof value === 'object') {
+    if (typeof value.__getValue === 'function') {
+      // resolve Animated.Value objects
+      value = value.__getValue()
+    } else {
+      return value
+    }
+  }
+  let res = value
+  if (typeof value === 'number') {
+    res = `${value}px`
+  } else if (property) {
+    res = `${res}`
+  }
+  return res
+}

package/src/helpers/objectIdentityKey.tsx

@@ -0,0 +1,20 @@
+export function objectIdentityKey(obj: object) {
+  let k = ''
+  for (const key in obj) {
+    k += key
+    const arg = obj[key]
+    let type = typeof arg
+    if (!arg || (type !== 'object' && type !== 'function')) {
+      k += type + arg
+    } else if (cache.has(arg)) {
+      k += cache.get(arg)
+    } else {
+      let v = Math.random()
+      cache.set(arg, v)
+      k += v
+    }
+  }
+  return k
+}
+
+const cache = new WeakMap()

package/src/helpers/parseBorderShorthand.native.ts

@@ -0,0 +1,74 @@
+import type { PropMappedValue } from '../types'
+
+// border style keywords
+const borderStyles = new Set([
+  'solid',
+  'dashed',
+  'dotted',
+  'double',
+  'groove',
+  'ridge',
+  'inset',
+  'outset',
+  'none',
+  'hidden',
+])
+
+// parses CSS border shorthand: "<width> <style> <color>"
+// components can appear in any order, all are optional
+// on native, expands directly to individual border properties
+export function parseBorderShorthand(value: string): PropMappedValue | undefined {
+  if (value === 'none' || value === '0') {
+    return [
+      ['borderTopWidth', 0],
+      ['borderRightWidth', 0],
+      ['borderBottomWidth', 0],
+      ['borderLeftWidth', 0],
+      ['borderStyle', 'solid'],
+    ]
+  }
+
+  const parts = value.trim().split(/\s+/)
+  let borderWidth: string | number | undefined
+  let borderStyle: string | undefined
+  let borderColor: string | undefined
+
+  for (const part of parts) {
+    // check if it's a border style keyword
+    if (borderStyles.has(part)) {
+      borderStyle = part
+    }
+    // check if it's a length (number or ends with px/em/rem/etc)
+    else if (/^[\d.]+(?:px|em|rem|%|pt|vw|vh)?$/.test(part)) {
+      const num = parseFloat(part)
+      borderWidth = part.endsWith('px') || !part.match(/[a-z%]/i) ? num : part
+    }
+    // otherwise assume it's a color
+    else {
+      borderColor = part
+    }
+  }
+
+  const result: PropMappedValue = []
+
+  // expand to individual width props (RN doesn't support borderWidth shorthand)
+  if (borderWidth !== undefined) {
+    result.push(['borderTopWidth', borderWidth])
+    result.push(['borderRightWidth', borderWidth])
+    result.push(['borderBottomWidth', borderWidth])
+    result.push(['borderLeftWidth', borderWidth])
+  }
+  // borderStyle is supported as-is on native
+  if (borderStyle !== undefined) {
+    result.push(['borderStyle', borderStyle])
+  }
+  // expand to individual color props (RN doesn't support borderColor shorthand)
+  if (borderColor !== undefined) {
+    result.push(['borderTopColor', borderColor])
+    result.push(['borderRightColor', borderColor])
+    result.push(['borderBottomColor', borderColor])
+    result.push(['borderLeftColor', borderColor])
+  }
+
+  return result.length > 0 ? result : undefined
+}

package/src/helpers/parseBorderShorthand.ts

@@ -0,0 +1,6 @@
+import type { PropMappedValue } from '../types'
+
+// no-op on web - border shorthand is passed through as CSS
+export function parseBorderShorthand(_value: string): PropMappedValue | undefined {
+  return undefined
+}