@newtonedev/components 0.1.2 → 0.1.3

package/src/primitives/Frame/Frame.types.ts

@@ -0,0 +1,315 @@
+import type { View, ViewStyle, GestureResponderEvent } from 'react-native';
+import type { ThemeName, FrameElevation } from '../../theme/types';
+
+// ── Spacing Types ──────────────────────────────────────────────
+
+/** Design system spacing tokens (represent px values at Medium preset) */
+export type SpacingToken = '00' | '02' | '04' | '06' | '08' | '10' | '12' | '16' | '20' | '24' | '32' | '40' | '48';
+
+/** 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 value — supports three forms:
+ *
+ * - **Uniform**: `'12'` or `16` — same padding on all sides
+ * - **Axis shorthand**: `{ x: '16', y: '08' }` — horizontal/vertical
+ * - **Per-side**: `{ top: 8, bottom: 16, left: '12', right: '12' }` — individual sides
+ *
+ * Token names (`'00'` through `'48'`) resolve to pixel values from the theme.
+ */
+export type PaddingProp = SpacingValue | SpacingAxes | SpacingSides;
+
+/** Gap axis shorthand */
+export interface GapAxes {
+  readonly row?: SpacingValue;
+  readonly column?: SpacingValue;
+}
+
+/**
+ * Gap value — supports two forms:
+ *
+ * - **Uniform**: `'12'` or `12` — same gap between all children
+ * - **Row/column**: `{ row: '08', column: '16' }` — different gaps per axis
+ *
+ * Token names (`'00'` through `'48'`) resolve to pixel values from the theme.
+ */
+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;
+}
+
+/**
+ * Border radius — supports two forms:
+ *
+ * - **Uniform**: `'md'` or `8` — same radius on all corners
+ * - **Per-corner**: `{ topLeft: 'lg', topRight: 'lg', bottomLeft: 0, bottomRight: 0 }`
+ *
+ * Token names (`'none'` through `'pill'`) resolve to pixel values from the theme.
+ */
+export type RadiusProp = RadiusValue | RadiusCorners;
+
+// ── Sizing Types ───────────────────────────────────────────────
+
+/**
+ * Figma-like sizing mode:
+ *
+ * - `'hug'` — shrink to fit content (default, no explicit dimension set)
+ * - `'fill'` — expand to fill available space (`flexGrow: 1` + `width/height: '100%'`)
+ * - `number` — fixed pixel dimension (e.g., `200`)
+ */
+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 ──────────────────────────────────────────────────────
+
+/**
+ * Props for Frame — the foundational layout building block.
+ *
+ * Frame provides theme/elevation context, layout (flex/grid), spacing,
+ * sizing, appearance, and interactivity. Frames can be nested — inner
+ * frames override outer frames for their subtree.
+ *
+ * @example
+ * ```tsx
+ * // Horizontal toolbar with consistent spacing
+ * <Frame direction="horizontal" gap="md" padding="lg" align="center">
+ *   <Button onPress={() => {}}>Save</Button>
+ *   <Button variant="ghost" onPress={() => {}}>Cancel</Button>
+ * </Frame>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Elevated card with primary theme
+ * <Frame theme="primary" elevation={2} radius="lg" padding="xl" bordered>
+ *   <Text>Elevated card content</Text>
+ * </Frame>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Clickable card with link
+ * <Frame radius="md" padding="md" bordered onPress={() => navigate('/details')}>
+ *   <Text>Tap to navigate</Text>
+ * </Frame>
+ * ```
+ */
+export interface FrameProps {
+  /**
+   * Child elements. Inherits this Frame's theme and elevation context.
+   * Raw strings/numbers are auto-wrapped in `<Text>` with theme-appropriate styling.
+   */
+  readonly children: React.ReactNode;
+
+  // ── Theme & Elevation ──
+
+  /**
+   * Theme override for this frame and all descendants.
+   * When omitted, inherits from parent Frame or NewtoneProvider.
+   *
+   * @example
+   * ```tsx
+   * <Frame theme="primary">  // Blue-ish surface
+   * <Frame theme="strong">   // High-contrast surface
+   * ```
+   */
+  readonly theme?: ThemeName;
+
+  /**
+   * Surface elevation: controls background lightness and shadow.
+   *
+   * | Value | Effect |
+   * |:-----:|:-------|
+   * | -2 | Deeply sunken (inset shadow) |
+   * | -1 | Sunken |
+   * |  0 | Default surface |
+   * |  1 | Elevated |
+   * |  2 | Prominently elevated (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 inside the frame.
+   *
+   * @example
+   * ```tsx
+   * <Frame padding="md" />                        // uniform
+   * <Frame padding={16} />                         // uniform px
+   * <Frame padding={{ x: 'lg', y: 'sm' }} />      // axis shorthand
+   * <Frame padding={{ top: 8, bottom: 16 }} />     // per-side
+   * ```
+   */
+  readonly padding?: PaddingProp;
+
+  /**
+   * Gap between children.
+   *
+   * @example
+   * ```tsx
+   * <Frame gap="md" />                             // uniform
+   * <Frame gap={12} />                             // uniform px
+   * <Frame gap={{ row: 'sm', column: 'lg' }} />    // per-axis
+   * ```
+   */
+  readonly gap?: GapProp;
+
+  // ── Sizing ──
+
+  /**
+   * Width sizing: `'hug'` (shrink to content), `'fill'` (expand), or fixed px.
+   * @example
+   * ```tsx
+   * <Frame width="fill" />   // expand to fill parent
+   * <Frame width={300} />    // fixed 300px
+   * ```
+   */
+  readonly width?: SizingMode;
+
+  /**
+   * Height sizing: `'hug'` (shrink to content), `'fill'` (expand), or fixed px.
+   * @example
+   * ```tsx
+   * <Frame height="fill" />  // expand to fill parent
+   * <Frame height={200} />   // fixed 200px
+   * ```
+   */
+  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.
+   *
+   * @example
+   * ```tsx
+   * <Frame radius="md" />                          // uniform token
+   * <Frame radius={8} />                           // uniform px
+   * <Frame radius={{ topLeft: 'lg', topRight: 'lg' }} />  // per-corner
+   * <Frame radius="pill" />                        // fully rounded
+   * ```
+   */
+  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;
+
+  // ── Accessibility ──
+
+  /** Accessible label read by screen readers. Use for icon-only or non-textual frames. */
+  readonly accessibilityLabel?: string;
+
+  /** Additional hint read after the label (e.g. "Opens settings page"). */
+  readonly accessibilityHint?: string;
+
+  // ── Testing & Platform ──
+
+  /** Test identifier — maps to `data-testid` on web. Used by testing libraries. */
+  readonly testID?: string;
+
+  /** DOM id — maps to `id` attribute on web. Used for anchors and scroll targets. */
+  readonly nativeID?: string;
+
+  /** Ref to the underlying View or Pressable element. */
+  readonly ref?: React.Ref<View>;
+
+  // ── Style override ──
+
+  /** Custom style overrides (applied last). */
+  readonly style?: ViewStyle | ViewStyle[];
+}

package/src/{Frame → primitives/Frame}/Frame.utils.ts

@@ -1,5 +1,5 @@
 import type { ViewStyle } from 'react-native';
-import type { ResolvedTokens } from '../tokens/types';
+import type { ResolvedTokens } from '../../tokens/types';
 import type {
   SpacingValue,
   SpacingAxes,
@@ -15,27 +15,33 @@ import type {
 } from './Frame.types';
 
 // ── Spacing ──────────────────────────────────────────────────────
+// These functions convert spacing props (token names like 'md' or pixel numbers)
+// into actual pixel values that React Native can use for padding and gap.
 
-/** Resolve a spacing token or number to a pixel value */
+/** Convert a spacing token name (like 'md') or raw number into pixels. */
 export function resolveSpacing(
   value: SpacingValue,
   tokens: ResolvedTokens,
 ): number {
+  // If already a number, use it directly as pixels.
   if (typeof value === 'number') return value;
+  // Otherwise look up the token name in the theme's spacing scale.
   return tokens.spacing[value];
 }
 
-/** Resolve padding prop to per-side pixel values */
+/** Convert a padding prop into pixel values for all four sides. */
 export function resolvePadding(
   prop: PaddingProp,
   tokens: ResolvedTokens,
 ): { readonly top: number; readonly right: number; readonly bottom: number; readonly left: number } {
+  // Uniform: same padding on all sides (e.g. padding="md" or padding={16}).
   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? }
+  // Axis shorthand: separate horizontal (x) and vertical (y) padding.
+  // Example: padding={{ x: 'lg', y: 'sm' }}
   if ('x' in prop || 'y' in prop) {
     const axes = prop as SpacingAxes;
     const x = axes.x !== undefined ? resolveSpacing(axes.x, tokens) : 0;
@@ -43,7 +49,8 @@ export function resolvePadding(
     return { top: y, right: x, bottom: y, left: x };
   }
 
-  // Per-side: { top?, right?, bottom?, left? }
+  // Per-side: different padding on each side.
+  // Example: padding={{ top: 8, bottom: 16, left: 'md', right: 'md' }}
   const sides = prop as SpacingSides;
   return {
     top: sides.top !== undefined ? resolveSpacing(sides.top, tokens) : 0,
@@ -53,17 +60,19 @@ export function resolvePadding(
   };
 }
 
-/** Resolve gap prop to rowGap/columnGap pixel values */
+/** Convert a gap prop into row and column gap pixel values. */
 export function resolveGap(
   prop: GapProp,
   tokens: ResolvedTokens,
 ): { readonly rowGap: number; readonly columnGap: number } {
+  // Uniform: same gap in both directions (e.g. gap="md" or gap={12}).
   if (typeof prop === 'string' || typeof prop === 'number') {
     const px = resolveSpacing(prop, tokens);
     return { rowGap: px, columnGap: px };
   }
 
-  // { row?, column? }
+  // Per-axis: different gap for rows vs columns.
+  // Example: gap={{ row: 'sm', column: 'lg' }}
   return {
     rowGap: prop.row !== undefined ? resolveSpacing(prop.row, tokens) : 0,
     columnGap: prop.column !== undefined ? resolveSpacing(prop.column, tokens) : 0,
@@ -71,8 +80,10 @@ export function resolveGap(
 }
 
 // ── Radius ───────────────────────────────────────────────────────
+// These functions convert radius props (token names like 'lg' or pixel numbers)
+// into actual pixel values for rounding corners.
 
-/** Resolve a radius token or number to a pixel value */
+/** Convert a radius token name (like 'lg') or raw number into pixels. */
 export function resolveRadius(
   value: RadiusValue,
   tokens: ResolvedTokens,
@@ -81,7 +92,7 @@ export function resolveRadius(
   return tokens.radius[value];
 }
 
-/** Resolved per-corner radius values */
+/** Pixel values for each corner of a rounded rectangle. */
 export interface ResolvedCorners {
   readonly topLeft: number;
   readonly topRight: number;
@@ -89,17 +100,19 @@ export interface ResolvedCorners {
   readonly bottomRight: number;
 }
 
-/** Resolve radius prop to per-corner pixel values */
+/** Convert a radius prop into pixel values for all four corners. */
 export function resolveRadiusCorners(
   prop: RadiusProp,
   tokens: ResolvedTokens,
 ): ResolvedCorners {
+  // Uniform: same radius on all corners (e.g. radius="lg" or radius={8}).
   if (typeof prop === 'string' || typeof prop === 'number') {
     const px = resolveRadius(prop, tokens);
     return { topLeft: px, topRight: px, bottomLeft: px, bottomRight: px };
   }
 
-  // Per-corner object
+  // Per-corner: different radius on each corner.
+  // Example: radius={{ topLeft: 'lg', topRight: 'lg', bottomLeft: 0, bottomRight: 0 }}
   return {
     topLeft: prop.topLeft !== undefined ? resolveRadius(prop.topLeft, tokens) : 0,
     topRight: prop.topRight !== undefined ? resolveRadius(prop.topRight, tokens) : 0,
@@ -108,7 +121,7 @@ export function resolveRadiusCorners(
   };
 }
 
-/** Check if any corner has a positive radius (for auto-clip) */
+/** Check if any corner is rounded (used to decide whether to clip overflowing content). */
 export function hasPositiveRadius(corners: ResolvedCorners): boolean {
   return corners.topLeft > 0
     || corners.topRight > 0
@@ -117,8 +130,9 @@ export function hasPositiveRadius(corners: ResolvedCorners): boolean {
 }
 
 // ── Sizing ───────────────────────────────────────────────────────
+// Converts Figma-like sizing modes into React Native style properties.
 
-/** Resolve width/height sizing modes to ViewStyle properties */
+/** Convert width/height sizing modes to style properties. */
 export function resolveSizing(
   width: SizingMode | undefined,
   height: SizingMode | undefined,
@@ -127,29 +141,43 @@ export function resolveSizing(
 
   if (width !== undefined) {
     if (width === 'fill') {
+      // 'fill' = expand to take all available space in the parent.
+      // flexGrow tells the layout engine to give this element extra space.
+      // width: 100% ensures it spans the full width.
       style.flexGrow = 1;
       style.width = '100%';
     } else if (typeof width === 'number') {
+      // Fixed pixel width (e.g. 300).
       style.width = width;
     }
-    // 'hug' = default RN behavior, no explicit dimension
+    // 'hug' = shrink to fit the content (React Native's default behavior).
   }
 
   if (height !== undefined) {
     if (height === 'fill') {
-      style.flexGrow = style.flexGrow === 1 ? 1 : 1;
+      // Same as width 'fill' — expand to fill all available vertical space.
+      style.flexGrow = 1;
       style.height = '100%';
     } else if (typeof height === 'number') {
+      // Fixed pixel height (e.g. 200).
       style.height = height;
     }
-    // 'hug' = default RN behavior
+    // 'hug' = shrink to fit the content (React Native's default behavior).
   }
 
   return style as ViewStyle;
 }
 
 // ── Layout ───────────────────────────────────────────────────────
-
+// These functions convert our friendly prop names (like 'start', 'between')
+// into the actual CSS flexbox values that React Native uses internally.
+
+// Maps our alignment names to flexbox cross-axis values:
+//   'start'    → push children to the top/left edge
+//   'center'   → center children in the cross direction
+//   'end'      → push children to the bottom/right edge
+//   'stretch'  → stretch children to fill the cross dimension
+//   'baseline' → align children by their text baseline
 const ALIGN_MAP: Record<Alignment, ViewStyle['alignItems']> = {
   start: 'flex-start',
   center: 'center',
@@ -158,6 +186,13 @@ const ALIGN_MAP: Record<Alignment, ViewStyle['alignItems']> = {
   baseline: 'baseline',
 };
 
+// Maps our justification names to flexbox main-axis values:
+//   'start'   → pack children at the beginning
+//   'center'  → pack children in the middle
+//   'end'     → pack children at the end
+//   'between' → spread children with equal space between them
+//   'around'  → spread children with equal space around each
+//   'evenly'  → spread children with equal space everywhere
 const JUSTIFY_MAP: Record<Justification, ViewStyle['justifyContent']> = {
   start: 'flex-start',
   center: 'center',
@@ -167,21 +202,22 @@ const JUSTIFY_MAP: Record<Justification, ViewStyle['justifyContent']> = {
   evenly: 'space-evenly',
 };
 
-/** Resolve alignment prop to ViewStyle alignItems */
+/** Convert our alignment name to the flexbox value React Native expects. */
 export function resolveAlignment(align: Alignment): ViewStyle['alignItems'] {
   return ALIGN_MAP[align];
 }
 
-/** Resolve justification prop to ViewStyle justifyContent */
+/** Convert our justification name to the flexbox value React Native expects. */
 export function resolveJustification(justify: Justification): ViewStyle['justifyContent'] {
   return JUSTIFY_MAP[justify];
 }
 
-/** Resolve direction + reverse to ViewStyle flexDirection */
+/** Convert direction ('horizontal'/'vertical') + reverse flag to flexbox direction. */
 export function resolveFlexDirection(
   direction: Direction,
   reverse: boolean,
 ): ViewStyle['flexDirection'] {
+  // 'horizontal' → children in a row, 'vertical' → children in a column.
   if (direction === 'horizontal') {
     return reverse ? 'row-reverse' : 'row';
   }

package/src/primitives/Icon/Icon.tsx

@@ -0,0 +1,89 @@
+import React, { useMemo } from 'react';
+import { Text, type TextStyle } from 'react-native';
+import { srgbToHex } from 'newtone';
+import { useTokens } from '../../tokens/useTokens';
+import type { IconProps } from './Icon.types';
+
+/**
+ * Material Symbols icon component with variable font support.
+ *
+ * Uses global icon configuration (variant, weight, auto-grade) from theme config,
+ * with per-instance control over size, fill, and color.
+ *
+ * @example
+ * ```tsx
+ * <Icon name="home" />
+ * <Icon name="settings" size={24} fill={1} />
+ * <Icon name="check" color="#00ff00" />
+ * ```
+ */
+export function Icon({
+  name,
+  size,
+  opticalSize,
+  fill = 0,
+  color,
+  elevation = 1,
+  style,
+  onPress,
+  // Accessibility
+  accessibilityLabel,
+  // Testing & platform
+  testID,
+  nativeID,
+  ref,
+}: IconProps) {
+  // Get the current theme's design tokens for colors, typography, and icon settings.
+  const tokens = useTokens(elevation);
+
+  // Build the icon's style from the theme tokens and props.
+  // Wrapped in useMemo so it only recalculates when the inputs change,
+  // instead of rebuilding the style object on every render.
+  const iconStyle = useMemo<TextStyle>(() => {
+    // Use the provided size, or fall back to the theme's default text size.
+    const fontSize = size ?? tokens.typography.size.base;
+    // Optical size adjusts stroke weight for readability at small sizes.
+    const opsz = opticalSize ?? fontSize;
+    // Use the provided color, or fall back to the theme's primary text color.
+    const iconColor = color ?? srgbToHex(tokens.textPrimary.srgb);
+
+    // Build the font family name from the theme's icon variant setting.
+    // Example: variant 'rounded' → 'Material Symbols Rounded'
+    // The charAt(0).toUpperCase() + slice(1) capitalizes the first letter.
+    const fontFamily = `Material Symbols ${tokens.icons.variant.charAt(0).toUpperCase() + tokens.icons.variant.slice(1)}`;
+
+    // Material Symbols is a variable font with 4 adjustable axes:
+    //   FILL: 0 = outlined (hollow), 1 = filled (solid)
+    //   wght: font weight (thinner or bolder strokes)
+    //   GRAD: grade (fine-tune weight without changing overall size)
+    //   opsz: optical size (adjusts detail level for the display size)
+    const fontVariationSettings = `'FILL' ${fill}, 'wght' ${tokens.icons.weight}, 'GRAD' ${tokens.icons.grade}, 'opsz' ${opsz}`;
+
+    return {
+      fontFamily,
+      fontSize,
+      color: iconColor,
+      userSelect: 'none', // web-only: prevents users from selecting the icon as text
+      fontVariationSettings, // web-only: controls the variable font axes listed above
+      ...style,
+    } as TextStyle; // Cast needed because web-only properties aren't in RN's type definitions
+  }, [tokens, size, opticalSize, fill, color, style]);
+
+  // Material Symbols renders icons as text ligatures — the icon name (like "home")
+  // is passed as text content, and the font renders it as the icon glyph.
+  return (
+    <Text
+      ref={ref}
+      testID={testID}
+      nativeID={nativeID}
+      accessibilityLabel={accessibilityLabel}
+      // When no label is provided, the icon is decorative — hide it from screen readers
+      // so assistive technology doesn't try to read the ligature text (e.g. "home").
+      importantForAccessibility={accessibilityLabel ? 'yes' : 'no-hide-descendants'}
+      style={iconStyle}
+      onPress={onPress} // When provided, makes the icon tappable
+    >
+      {name}
+    </Text>
+  );
+}