@newtonedev/components 0.1.0 → 0.1.2

package/src/Frame/Frame.tsx

@@ -0,0 +1,242 @@
+import React, { useMemo } from 'react';
+import { View, Pressable, Text } from 'react-native';
+import type { ViewStyle, TextStyle } from 'react-native';
+import type { FrameProps } from './Frame.types';
+import type { ElevationLevel, FrameElevation } from '../theme/types';
+import { srgbToHex } from 'newtone';
+import { FrameContext, useFrameContext } from '../theme/FrameContext';
+import { useNewtoneTheme } from '../theme/NewtoneProvider';
+import { computeTokens } from '../tokens/computeTokens';
+import { getFrameStyles } from './Frame.styles';
+
+/**
+ * Wrap raw string/number children in <Text> to prevent
+ * react-native-web "Unexpected text node" console errors.
+ */
+function wrapTextChildren(
+  children: React.ReactNode,
+  textStyle: TextStyle,
+): React.ReactNode {
+  return React.Children.map(children, (child) => {
+    if (typeof child === 'string' || typeof child === 'number') {
+      return <Text style={textStyle}>{child}</Text>;
+    }
+    return child;
+  });
+}
+
+/**
+ * Convert user-facing FrameElevation (-2..2) to internal ElevationLevel (0..2).
+ *
+ * | Frame | Internal | Background |
+ * |:-----:|:--------:|:-----------|
+ * |  -2   |    0     | Sunken     |
+ * |  -1   |    0     | Sunken     |
+ * |   0   |    1     | Default    |
+ * |   1   |    2     | Elevated   |
+ * |   2   |    2     | Elevated   |
+ */
+function toElevationLevel(frameElevation: FrameElevation): ElevationLevel {
+  if (frameElevation <= -1) return 0;
+  if (frameElevation === 0) return 1;
+  return 2;
+}
+
+/**
+ * Frame — Foundational layout building block.
+ *
+ * Frame is a container that provides theme and elevation context to all
+ * descendants, plus layout (flex/grid), spacing, sizing, appearance,
+ * and interactivity capabilities.
+ *
+ * Frames can be nested. Inner frames override outer frames for their subtree.
+ * Unspecified props inherit from the nearest parent Frame.
+ *
+ * @example
+ * ```tsx
+ * // Basic layout
+ * <Frame direction="horizontal" gap="md" padding="lg" align="center">
+ *   <Button onPress={() => {}}>Save</Button>
+ *   <Button variant="ghost" onPress={() => {}}>Cancel</Button>
+ * </Frame>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Card-like frame
+ * <Frame
+ *   theme="primary"
+ *   elevation={2}
+ *   radius="lg"
+ *   padding="xl"
+ *   bordered
+ *   onPress={() => navigate('/details')}
+ * >
+ *   <Text>Clickable card</Text>
+ * </Frame>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Grid layout (web)
+ * <Frame layout="grid" columns={3} gap="md" padding="lg">
+ *   <Frame radius="md" padding="md" bordered>Cell 1</Frame>
+ *   <Frame radius="md" padding="md" bordered>Cell 2</Frame>
+ *   <Frame radius="md" padding="md" bordered>Cell 3</Frame>
+ * </Frame>
+ * ```
+ */
+export function Frame({
+  children,
+  // Theme & elevation
+  theme,
+  elevation,
+  // Layout
+  layout,
+  direction,
+  wrap,
+  reverse,
+  columns,
+  rows,
+  // Alignment
+  align,
+  justify,
+  // Spacing
+  padding,
+  gap,
+  // Sizing
+  width,
+  height,
+  minWidth,
+  maxWidth,
+  minHeight,
+  maxHeight,
+  // Appearance
+  radius,
+  bordered,
+  // Interactivity
+  onPress,
+  href,
+  disabled = false,
+  // Style override
+  style,
+}: FrameProps) {
+  const { config, mode, theme: providerTheme } = useNewtoneTheme();
+  const parentFrameCtx = useFrameContext();
+
+  // Resolve theme: prop > parent Frame > NewtoneProvider
+  const resolvedTheme = theme ?? parentFrameCtx?.theme ?? providerTheme;
+
+  // Resolve frame elevation (user-facing, for shadow/style decisions)
+  const resolvedFrameElevation: FrameElevation = elevation ?? 0;
+
+  // Map to internal elevation level for token computation
+  const resolvedElevation: ElevationLevel = elevation !== undefined
+    ? toElevationLevel(elevation)
+    : parentFrameCtx?.elevation ?? 1;
+
+  // Compute tokens directly (not useTokens) to avoid reading our own FrameContext
+  const tokens = useMemo(() => {
+    const themeMapping = config.themes[resolvedTheme];
+    return computeTokens(
+      config.colorSystem,
+      mode,
+      themeMapping,
+      resolvedElevation,
+      config.elevation.offsets,
+      config.spacing,
+      config.radius,
+      config.typography,
+      config.icons,
+    );
+  }, [config, mode, resolvedTheme, resolvedElevation]);
+
+  const styles = useMemo(
+    () => getFrameStyles({
+      tokens,
+      frameElevation: resolvedFrameElevation,
+      layout,
+      direction,
+      wrap,
+      reverse,
+      columns,
+      rows,
+      align,
+      justify,
+      padding,
+      gap,
+      width,
+      height,
+      minWidth,
+      maxWidth,
+      minHeight,
+      maxHeight,
+      radius,
+      bordered,
+      disabled,
+    }),
+    [
+      tokens, resolvedFrameElevation,
+      layout, direction, wrap, reverse, columns, rows,
+      align, justify, padding, gap,
+      width, height, minWidth, maxWidth, minHeight, maxHeight,
+      radius, bordered, disabled,
+    ],
+  );
+
+  // Memoize context value
+  const contextValue = useMemo(
+    () => ({ theme: resolvedTheme, elevation: resolvedElevation }),
+    [resolvedTheme, resolvedElevation],
+  );
+
+  // Build the style array with web-specific overrides
+  const webOverrides: ViewStyle[] = [];
+  if (styles.gridWebStyle) {
+    webOverrides.push(styles.gridWebStyle as unknown as ViewStyle);
+  }
+  if (styles.insetBoxShadow) {
+    webOverrides.push({ boxShadow: styles.insetBoxShadow } as unknown as ViewStyle);
+  }
+
+  const userStyles = Array.isArray(style) ? style : style ? [style] : [];
+
+  const isInteractive = onPress !== undefined || href !== undefined;
+
+  // Wrap raw string/number children in <Text> for RN compatibility
+  const textStyle = useMemo<TextStyle>(
+    () => ({
+      color: srgbToHex(tokens.textPrimary.srgb),
+      fontSize: tokens.typography.size.base,
+      fontFamily: tokens.typography.fonts.default,
+      lineHeight: tokens.typography.size.base * tokens.typography.lineHeight.normal,
+    }),
+    [tokens],
+  );
+  const wrappedChildren = wrapTextChildren(children, textStyle);
+
+  return (
+    <FrameContext.Provider value={contextValue}>
+      {isInteractive ? (
+        <Pressable
+          onPress={onPress}
+          disabled={disabled}
+          // react-native-web renders Pressable with href as <a>
+          {...(href ? { href, accessibilityRole: 'link' as const } : { accessibilityRole: 'button' as const })}
+          style={({ pressed }) => [
+            styles.container,
+            pressed && !disabled && styles.pressed,
+            ...webOverrides,
+            ...userStyles,
+          ]}
+        >
+          {wrappedChildren}
+        </Pressable>
+      ) : (
+        <View style={[styles.container, ...webOverrides, ...userStyles]}>
+          {wrappedChildren}
+        </View>
+      )}
+    </FrameContext.Provider>
+  );
+}

package/src/Frame/Frame.types.ts

@@ -0,0 +1,181 @@
+import type { ViewStyle, GestureResponderEvent } from 'react-native';
+import type { ThemeName, FrameElevation } from '../theme/types';
+
+// ── Spacing Types ──────────────────────────────────────────────
+
+/** Design system spacing tokens */
+export type SpacingToken = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+
+/** A spacing value: either a design token name or a pixel number */
+export type SpacingValue = SpacingToken | number;
+
+/** Per-side spacing */
+export interface SpacingSides {
+  readonly top?: SpacingValue;
+  readonly right?: SpacingValue;
+  readonly bottom?: SpacingValue;
+  readonly left?: SpacingValue;
+}
+
+/** Axis-based spacing shorthand */
+export interface SpacingAxes {
+  readonly x?: SpacingValue;
+  readonly y?: SpacingValue;
+}
+
+/** Padding: uniform, axis shorthand, or per-side */
+export type PaddingProp = SpacingValue | SpacingAxes | SpacingSides;
+
+/** Gap axis shorthand */
+export interface GapAxes {
+  readonly row?: SpacingValue;
+  readonly column?: SpacingValue;
+}
+
+/** Gap: uniform or row/column */
+export type GapProp = SpacingValue | GapAxes;
+
+// ── Radius Types ───────────────────────────────────────────────
+
+/** Design system radius tokens */
+export type RadiusToken = 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'pill';
+
+/** A radius value: either a design token name or a pixel number */
+export type RadiusValue = RadiusToken | number;
+
+/** Per-corner radius */
+export interface RadiusCorners {
+  readonly topLeft?: RadiusValue;
+  readonly topRight?: RadiusValue;
+  readonly bottomLeft?: RadiusValue;
+  readonly bottomRight?: RadiusValue;
+}
+
+/** Radius: uniform or per-corner */
+export type RadiusProp = RadiusValue | RadiusCorners;
+
+// ── Sizing Types ───────────────────────────────────────────────
+
+/**
+ * Figma-like sizing mode:
+ * - 'hug': shrink to content (default)
+ * - 'fill': expand to fill available space
+ * - number: fixed pixel dimension
+ */
+export type SizingMode = 'hug' | 'fill' | number;
+
+// ── Layout Types ───────────────────────────────────────────────
+
+/** Layout mode */
+export type LayoutMode = 'flex' | 'grid';
+
+/** Flex direction (Figma-like naming) */
+export type Direction = 'horizontal' | 'vertical';
+
+/** Cross-axis alignment */
+export type Alignment = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+
+/** Main-axis justification */
+export type Justification = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+
+// ── Props ──────────────────────────────────────────────────────
+
+export interface FrameProps {
+  /** Child elements that inherit this Frame's theme and elevation context */
+  readonly children: React.ReactNode;
+
+  // ── Theme & Elevation ──
+
+  /**
+   * Theme override for this frame and all descendants.
+   * When omitted, inherits from parent Frame or NewtoneProvider.
+   */
+  readonly theme?: ThemeName;
+
+  /**
+   * Surface elevation: -2 (deeply sunken with inset shadow), -1 (sunken),
+   * 0 (default), 1 (elevated), 2 (prominently elevated with drop shadow).
+   * When omitted, inherits from parent Frame or defaults to 0.
+   */
+  readonly elevation?: FrameElevation;
+
+  // ── Layout ──
+
+  /** Layout mode. @default 'flex' */
+  readonly layout?: LayoutMode;
+
+  /** Flex direction. @default 'vertical' */
+  readonly direction?: Direction;
+
+  /** Enable flex wrap. @default false */
+  readonly wrap?: boolean;
+
+  /** Reverse flex direction. @default false */
+  readonly reverse?: boolean;
+
+  /** CSS Grid column count (web-only, requires layout='grid') */
+  readonly columns?: number;
+
+  /** CSS Grid row count (web-only, requires layout='grid') */
+  readonly rows?: number;
+
+  // ── Alignment ──
+
+  /** Cross-axis alignment of children */
+  readonly align?: Alignment;
+
+  /** Main-axis justification of children */
+  readonly justify?: Justification;
+
+  // ── Spacing ──
+
+  /** Padding: uniform token/number, axis shorthand, or per-side */
+  readonly padding?: PaddingProp;
+
+  /** Gap between children: uniform or row/column */
+  readonly gap?: GapProp;
+
+  // ── Sizing ──
+
+  /** Width: 'hug' (content-sized), 'fill' (expand), or fixed number */
+  readonly width?: SizingMode;
+
+  /** Height: 'hug' (content-sized), 'fill' (expand), or fixed number */
+  readonly height?: SizingMode;
+
+  /** Minimum width in pixels */
+  readonly minWidth?: number;
+
+  /** Maximum width in pixels */
+  readonly maxWidth?: number;
+
+  /** Minimum height in pixels */
+  readonly minHeight?: number;
+
+  /** Maximum height in pixels */
+  readonly maxHeight?: number;
+
+  // ── Appearance ──
+
+  /** Border radius: token, number, or per-corner object */
+  readonly radius?: RadiusProp;
+
+  /** Show 1px border using theme border color. @default false */
+  readonly bordered?: boolean;
+
+  // ── Interactivity ──
+
+  /** Press handler — switches rendering from View to Pressable */
+  readonly onPress?: (event: GestureResponderEvent) => void;
+
+  /** Navigation URL — switches rendering to Pressable with link role */
+  readonly href?: string;
+
+  /** Disable interaction. @default false */
+  readonly disabled?: boolean;
+
+  // ── Style override ──
+
+  /** Custom style overrides (applied last) */
+  readonly style?: ViewStyle | ViewStyle[];
+}

package/src/Frame/Frame.utils.ts

@@ -0,0 +1,189 @@
+import type { ViewStyle } from 'react-native';
+import type { ResolvedTokens } from '../tokens/types';
+import type {
+  SpacingValue,
+  SpacingAxes,
+  SpacingSides,
+  PaddingProp,
+  GapProp,
+  RadiusValue,
+  RadiusProp,
+  SizingMode,
+  Direction,
+  Alignment,
+  Justification,
+} from './Frame.types';
+
+// ── Spacing ──────────────────────────────────────────────────────
+
+/** Resolve a spacing token or number to a pixel value */
+export function resolveSpacing(
+  value: SpacingValue,
+  tokens: ResolvedTokens,
+): number {
+  if (typeof value === 'number') return value;
+  return tokens.spacing[value];
+}
+
+/** Resolve padding prop to per-side pixel values */
+export function resolvePadding(
+  prop: PaddingProp,
+  tokens: ResolvedTokens,
+): { readonly top: number; readonly right: number; readonly bottom: number; readonly left: number } {
+  if (typeof prop === 'string' || typeof prop === 'number') {
+    const px = resolveSpacing(prop, tokens);
+    return { top: px, right: px, bottom: px, left: px };
+  }
+
+  // Axis shorthand: { x?, y? }
+  if ('x' in prop || 'y' in prop) {
+    const axes = prop as SpacingAxes;
+    const x = axes.x !== undefined ? resolveSpacing(axes.x, tokens) : 0;
+    const y = axes.y !== undefined ? resolveSpacing(axes.y, tokens) : 0;
+    return { top: y, right: x, bottom: y, left: x };
+  }
+
+  // Per-side: { top?, right?, bottom?, left? }
+  const sides = prop as SpacingSides;
+  return {
+    top: sides.top !== undefined ? resolveSpacing(sides.top, tokens) : 0,
+    right: sides.right !== undefined ? resolveSpacing(sides.right, tokens) : 0,
+    bottom: sides.bottom !== undefined ? resolveSpacing(sides.bottom, tokens) : 0,
+    left: sides.left !== undefined ? resolveSpacing(sides.left, tokens) : 0,
+  };
+}
+
+/** Resolve gap prop to rowGap/columnGap pixel values */
+export function resolveGap(
+  prop: GapProp,
+  tokens: ResolvedTokens,
+): { readonly rowGap: number; readonly columnGap: number } {
+  if (typeof prop === 'string' || typeof prop === 'number') {
+    const px = resolveSpacing(prop, tokens);
+    return { rowGap: px, columnGap: px };
+  }
+
+  // { row?, column? }
+  return {
+    rowGap: prop.row !== undefined ? resolveSpacing(prop.row, tokens) : 0,
+    columnGap: prop.column !== undefined ? resolveSpacing(prop.column, tokens) : 0,
+  };
+}
+
+// ── Radius ───────────────────────────────────────────────────────
+
+/** Resolve a radius token or number to a pixel value */
+export function resolveRadius(
+  value: RadiusValue,
+  tokens: ResolvedTokens,
+): number {
+  if (typeof value === 'number') return value;
+  return tokens.radius[value];
+}
+
+/** Resolved per-corner radius values */
+export interface ResolvedCorners {
+  readonly topLeft: number;
+  readonly topRight: number;
+  readonly bottomLeft: number;
+  readonly bottomRight: number;
+}
+
+/** Resolve radius prop to per-corner pixel values */
+export function resolveRadiusCorners(
+  prop: RadiusProp,
+  tokens: ResolvedTokens,
+): ResolvedCorners {
+  if (typeof prop === 'string' || typeof prop === 'number') {
+    const px = resolveRadius(prop, tokens);
+    return { topLeft: px, topRight: px, bottomLeft: px, bottomRight: px };
+  }
+
+  // Per-corner object
+  return {
+    topLeft: prop.topLeft !== undefined ? resolveRadius(prop.topLeft, tokens) : 0,
+    topRight: prop.topRight !== undefined ? resolveRadius(prop.topRight, tokens) : 0,
+    bottomLeft: prop.bottomLeft !== undefined ? resolveRadius(prop.bottomLeft, tokens) : 0,
+    bottomRight: prop.bottomRight !== undefined ? resolveRadius(prop.bottomRight, tokens) : 0,
+  };
+}
+
+/** Check if any corner has a positive radius (for auto-clip) */
+export function hasPositiveRadius(corners: ResolvedCorners): boolean {
+  return corners.topLeft > 0
+    || corners.topRight > 0
+    || corners.bottomLeft > 0
+    || corners.bottomRight > 0;
+}
+
+// ── Sizing ───────────────────────────────────────────────────────
+
+/** Resolve width/height sizing modes to ViewStyle properties */
+export function resolveSizing(
+  width: SizingMode | undefined,
+  height: SizingMode | undefined,
+): ViewStyle {
+  const style: Record<string, unknown> = {};
+
+  if (width !== undefined) {
+    if (width === 'fill') {
+      style.flexGrow = 1;
+      style.width = '100%';
+    } else if (typeof width === 'number') {
+      style.width = width;
+    }
+    // 'hug' = default RN behavior, no explicit dimension
+  }
+
+  if (height !== undefined) {
+    if (height === 'fill') {
+      style.flexGrow = style.flexGrow === 1 ? 1 : 1;
+      style.height = '100%';
+    } else if (typeof height === 'number') {
+      style.height = height;
+    }
+    // 'hug' = default RN behavior
+  }
+
+  return style as ViewStyle;
+}
+
+// ── Layout ───────────────────────────────────────────────────────
+
+const ALIGN_MAP: Record<Alignment, ViewStyle['alignItems']> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  stretch: 'stretch',
+  baseline: 'baseline',
+};
+
+const JUSTIFY_MAP: Record<Justification, ViewStyle['justifyContent']> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  between: 'space-between',
+  around: 'space-around',
+  evenly: 'space-evenly',
+};
+
+/** Resolve alignment prop to ViewStyle alignItems */
+export function resolveAlignment(align: Alignment): ViewStyle['alignItems'] {
+  return ALIGN_MAP[align];
+}
+
+/** Resolve justification prop to ViewStyle justifyContent */
+export function resolveJustification(justify: Justification): ViewStyle['justifyContent'] {
+  return JUSTIFY_MAP[justify];
+}
+
+/** Resolve direction + reverse to ViewStyle flexDirection */
+export function resolveFlexDirection(
+  direction: Direction,
+  reverse: boolean,
+): ViewStyle['flexDirection'] {
+  if (direction === 'horizontal') {
+    return reverse ? 'row-reverse' : 'row';
+  }
+  return reverse ? 'column-reverse' : 'column';
+}

package/src/Frame/index.ts

@@ -0,0 +1,21 @@
+export { Frame } from './Frame';
+export type {
+  FrameProps,
+  SpacingToken,
+  SpacingValue,
+  SpacingSides,
+  SpacingAxes,
+  PaddingProp,
+  GapAxes,
+  GapProp,
+  RadiusToken,
+  RadiusValue,
+  RadiusCorners,
+  RadiusProp,
+  SizingMode,
+  LayoutMode,
+  Direction,
+  Alignment,
+  Justification,
+} from './Frame.types';
+export type { ResolvedCorners } from './Frame.utils';