@newtonedev/components 0.1.2 → 0.1.3

package/src/primitives/Icon/Icon.types.ts

@@ -0,0 +1,70 @@
+import type { Text as RNText, TextStyle } from 'react-native';
+import type { ElevationLevel } from '../../theme/types';
+
+/**
+ * Props for Icon — Material Symbols icon with variable font support.
+ *
+ * Uses the icon variant, weight, and grade from the theme config.
+ * 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" />
+ * <Icon name="delete" size={20} onPress={() => handleDelete()} />
+ * ```
+ *
+ * @see {@link https://fonts.google.com/icons Material Symbols icon reference}
+ */
+export interface IconProps {
+  /**
+   * Material Symbols ligature name.
+   *
+   * @example `'home'`, `'settings'`, `'check'`, `'expand_more'`, `'delete'`, `'add'`, `'search'`
+   * @see {@link https://fonts.google.com/icons Browse all icons}
+   */
+  readonly name: string;
+
+  /** Font size in pixels. @default tokens.typography.size.base (~16px) */
+  readonly size?: number;
+
+  /** Optical size for variable font axis. Adjusts stroke weight for readability at small sizes. @default same as size */
+  readonly opticalSize?: number;
+
+  /**
+   * Fill state for the icon.
+   *
+   * - `0` — Outlined (default)
+   * - `1` — Filled (solid)
+   */
+  readonly fill?: 0 | 1;
+
+  /** Icon color as hex string. @default tokens.textPrimary */
+  readonly color?: string;
+
+  /** Elevation level for token computation. @default 1 */
+  readonly elevation?: ElevationLevel;
+
+  /** Additional styles applied to the icon Text element. */
+  readonly style?: TextStyle;
+
+  /** Press handler — makes the icon tappable. */
+  readonly onPress?: () => void;
+
+  // ── Accessibility ──
+
+  /** Label read by screen readers. When omitted, the icon is treated as decorative (hidden from assistive technology). */
+  readonly accessibilityLabel?: 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 Text element. */
+  readonly ref?: React.Ref<RNText>;
+}

package/src/primitives/Icon/index.ts

@@ -0,0 +1,2 @@
+export { Icon } from './Icon';
+export type { IconProps } from './Icon.types';

package/src/primitives/Text/Text.tsx

@@ -0,0 +1,90 @@
+import React, { useMemo } from 'react';
+import { Text as RNText } from 'react-native';
+import type { TextStyle } from 'react-native';
+import { srgbToHex } from 'newtone';
+import { useTokens } from '../../tokens/useTokens';
+import type { TextProps, TextColor } from './Text.types';
+
+// Maps user-friendly color names to the actual token keys in the theme.
+// Example: color="primary" → looks up tokens.textPrimary to get the hex color.
+const COLOR_MAP: Record<TextColor, 'textPrimary' | 'textSecondary' | 'interactive'> = {
+  primary: 'textPrimary',
+  secondary: 'textSecondary',
+  interactive: 'interactive',
+};
+
+/**
+ * Token-aware text primitive.
+ *
+ * Reads typography tokens from the nearest NewtoneProvider and maps
+ * semantic props (size, weight, color, font, lineHeight) to resolved values.
+ *
+ * @example
+ * ```tsx
+ * <Text>Body text</Text>
+ * <Text size="sm" weight="semibold" color="secondary">Label</Text>
+ * <Text size="xl" font="display">Heading</Text>
+ * ```
+ */
+export function Text({
+  children,
+  size = 'base',
+  weight = 'regular',
+  color = 'primary',
+  font = 'default',
+  lineHeight = 'normal',
+  align,
+  numberOfLines,
+  elevation = 1,
+  style,
+  // Accessibility
+  accessibilityRole,
+  // Testing & platform
+  testID,
+  nativeID,
+  ref,
+}: TextProps) {
+  // Get the current theme's design tokens (colors, fonts, spacing).
+  // The elevation parameter affects which background shade the tokens reference.
+  const tokens = useTokens(elevation);
+
+  // Build the text style from the theme tokens.
+  // Wrapped in useMemo so it only recalculates when the inputs actually change,
+  // instead of recalculating on every render (which would be wasteful).
+  const resolvedStyle = useMemo<TextStyle>(() => {
+    // Look up the pixel size for the chosen size token (e.g. 'base' → 16px).
+    const fontSize = tokens.typography.size[size];
+    return {
+      // Font family from the theme (e.g. 'default' → 'Inter', 'mono' → 'JetBrains Mono').
+      fontFamily: tokens.typography.fonts[font],
+      fontSize,
+      // Font weight is stored as a number (e.g. 400, 600) but React Native expects a string.
+      fontWeight: String(tokens.typography.weight[weight]) as TextStyle['fontWeight'],
+      // Convert the theme color from internal sRGB format to a hex string (e.g. '#1a1a1a').
+      color: srgbToHex(tokens[COLOR_MAP[color]].srgb),
+      // Line height = font size × multiplier (e.g. 16px × 1.5 = 24px line height).
+      lineHeight: fontSize * tokens.typography.lineHeight[lineHeight],
+      textAlign: align,
+    };
+  }, [tokens, size, weight, color, font, lineHeight, align]);
+
+  return (
+    <RNText
+      ref={ref}
+      testID={testID}
+      nativeID={nativeID}
+      accessibilityRole={accessibilityRole}
+      // If the user passed custom styles, merge them after the theme styles.
+      // The last style in the array wins, so user styles can override theme defaults.
+      // Normalize: the user can pass a single style or an array of styles.
+      style={style
+        ? [resolvedStyle, ...(Array.isArray(style) ? style : [style])]
+        : resolvedStyle
+      }
+      // When set, text is cut off after this many lines with "..." at the end.
+      numberOfLines={numberOfLines}
+    >
+      {children}
+    </RNText>
+  );
+}

package/src/primitives/Text/Text.types.ts

@@ -0,0 +1,108 @@
+import type { Text as RNText, TextStyle } from 'react-native';
+import type { ElevationLevel } from '../../theme/types';
+
+/** Typography size tokens — maps to `tokens.typography.size.*` pixel values. */
+export type TextSize = 'xs' | 'sm' | 'base' | 'md' | 'lg' | 'xl' | 'xxl';
+
+/** Typography weight tokens — maps to `tokens.typography.weight.*` numeric values. */
+export type TextWeight = 'regular' | 'medium' | 'semibold' | 'bold';
+
+/** Semantic text color tokens — resolved from the current theme's token palette. */
+export type TextColor = 'primary' | 'secondary' | 'interactive';
+
+/** Font family tokens — maps to `tokens.typography.fonts.*` font stacks. */
+export type TextFont = 'default' | 'display' | 'mono';
+
+/** Line height multiplier tokens — maps to `tokens.typography.lineHeight.*` values. */
+export type TextLineHeight = 'tight' | 'normal' | 'relaxed';
+
+/** Text alignment. */
+export type TextAlign = 'left' | 'center' | 'right';
+
+/**
+ * Props for Text — themed typography component.
+ *
+ * All visual properties are token-driven: size, weight, color, font,
+ * and line height resolve from the current theme context. Use semantic
+ * tokens rather than raw values for consistency.
+ *
+ * @example
+ * ```tsx
+ * <Text>Default body text</Text>
+ * <Text size="lg" weight="bold">Heading</Text>
+ * <Text color="secondary" size="sm">Caption text</Text>
+ * <Text font="mono" size="sm">const x = 42;</Text>
+ * <Text numberOfLines={2}>Long text that truncates after two lines...</Text>
+ * ```
+ */
+export interface TextProps {
+  /**
+   * Text content. Accepts strings, numbers, and nested `<Text>` elements
+   * for inline formatting (e.g., bold spans within a paragraph).
+   *
+   * @example
+   * ```tsx
+   * <Text>Plain string</Text>
+   * <Text>Count: {42}</Text>
+   * <Text>Normal <Text weight="bold">bold</Text> normal</Text>
+   * ```
+   */
+  readonly children: React.ReactNode;
+
+  /** Typography size token. @default 'base' */
+  readonly size?: TextSize;
+
+  /** Font weight token. @default 'regular' */
+  readonly weight?: TextWeight;
+
+  /**
+   * Semantic color token.
+   *
+   * - `'primary'` — Main text color (default)
+   * - `'secondary'` — Subdued/muted text
+   * - `'interactive'` — Accent color for links/actions
+   *
+   * @default 'primary'
+   */
+  readonly color?: TextColor;
+
+  /** Font family token. @default 'default' */
+  readonly font?: TextFont;
+
+  /** Line height multiplier token. @default 'normal' */
+  readonly lineHeight?: TextLineHeight;
+
+  /** Text alignment. */
+  readonly align?: TextAlign;
+
+  /** Maximum number of lines before truncation with ellipsis. When omitted, text wraps freely. */
+  readonly numberOfLines?: number;
+
+  /** Elevation level for token computation. @default 1 */
+  readonly elevation?: ElevationLevel;
+
+  /** Style overrides (applied last). Supports a single style or an array of styles. */
+  readonly style?: TextStyle | readonly TextStyle[];
+
+  // ── Accessibility ──
+
+  /**
+   * Semantic role for screen readers.
+   *
+   * - `'header'` — Marks this as a heading (e.g. page title, section header)
+   * - `'text'` — Default text role (usually omitted)
+   * - `'link'` — Marks this as a navigable link
+   */
+  readonly accessibilityRole?: 'header' | 'text' | 'link';
+
+  // ── 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 React Native Text element. */
+  readonly ref?: React.Ref<RNText>;
+}

package/src/primitives/Text/index.ts

@@ -0,0 +1,10 @@
+export { Text } from './Text';
+export type {
+  TextProps,
+  TextSize,
+  TextWeight,
+  TextColor,
+  TextFont,
+  TextLineHeight,
+  TextAlign,
+} from './Text.types';

package/src/primitives/Wrapper/Wrapper.styles.ts

@@ -0,0 +1,113 @@
+import type { ViewStyle } from 'react-native';
+import { StyleSheet } from 'react-native';
+import type { ResolvedTokens } from '../../tokens/types';
+import type {
+  Direction,
+  Alignment,
+  Justification,
+  PaddingProp,
+  GapProp,
+  SizingMode,
+} from '../Frame/Frame.types';
+import {
+  resolvePadding,
+  resolveGap,
+  resolveSizing,
+  resolveFlexDirection,
+  resolveAlignment,
+  resolveJustification,
+} from '../Frame/Frame.utils';
+
+export interface WrapperStyleInput {
+  readonly tokens: ResolvedTokens;
+  readonly direction?: Direction;
+  readonly wrap?: boolean;
+  readonly reverse?: boolean;
+  readonly align?: Alignment;
+  readonly justify?: Justification;
+  readonly padding?: PaddingProp;
+  readonly gap?: GapProp;
+  readonly width?: SizingMode;
+  readonly height?: SizingMode;
+  readonly minWidth?: number;
+  readonly maxWidth?: number;
+  readonly minHeight?: number;
+  readonly maxHeight?: number;
+}
+
+/**
+ * Build the layout styles for a Wrapper.
+ *
+ * Unlike Frame, this only handles structure (direction, spacing, sizing).
+ * No background, border, shadow, or radius — Wrapper is always invisible.
+ * Reuses the same helper functions that Frame uses for layout.
+ */
+export function getWrapperStyles(input: WrapperStyleInput): ViewStyle {
+  const {
+    tokens,
+    direction = 'vertical',
+    wrap = false,
+    reverse = false,
+    align,
+    justify,
+    padding,
+    gap,
+    width,
+    height,
+    minWidth,
+    maxWidth,
+    minHeight,
+    maxHeight,
+  } = input;
+
+  // We build styles as a plain object first, then validate it through
+  // StyleSheet.create() at the end. Using Record<string, unknown> allows us
+  // to set properties conditionally without TypeScript complaining.
+  const container: Record<string, unknown> = {};
+
+  // ── Layout ──
+  // Set whether children are arranged in a row or column (and optionally reversed).
+  container.flexDirection = resolveFlexDirection(direction, reverse);
+  // Allow children to flow onto multiple lines when they don't fit in one.
+  if (wrap) container.flexWrap = 'wrap';
+
+  // ── Alignment ──
+  // Cross-axis: how children are positioned perpendicular to the main direction.
+  if (align) container.alignItems = resolveAlignment(align);
+  // Main-axis: how children are distributed along the main direction.
+  if (justify) container.justifyContent = resolveJustification(justify);
+
+  // ── Padding ──
+  // Convert spacing tokens (like 'md') or pixel values into actual padding.
+  if (padding !== undefined) {
+    const p = resolvePadding(padding, tokens);
+    container.paddingTop = p.top;
+    container.paddingRight = p.right;
+    container.paddingBottom = p.bottom;
+    container.paddingLeft = p.left;
+  }
+
+  // ── Gap ──
+  // Space between children (row gap for vertical stacks, column gap for horizontal).
+  if (gap !== undefined) {
+    const g = resolveGap(gap, tokens);
+    container.rowGap = g.rowGap;
+    container.columnGap = g.columnGap;
+  }
+
+  // ── Sizing ──
+  // Merge width/height settings into the container.
+  // 'hug' = shrink to fit content, 'fill' = expand to fill parent, number = fixed pixels.
+  Object.assign(container, resolveSizing(width, height));
+
+  // ── Constraints ──
+  // Set min/max boundaries for width and height.
+  if (minWidth !== undefined) container.minWidth = minWidth;
+  if (maxWidth !== undefined) container.maxWidth = maxWidth;
+  if (minHeight !== undefined) container.minHeight = minHeight;
+  if (maxHeight !== undefined) container.maxHeight = maxHeight;
+
+  // Pass through StyleSheet.create() to validate and optimize the styles,
+  // then extract the single style object with `.c`.
+  return StyleSheet.create({ c: container as ViewStyle }).c;
+}

package/src/primitives/Wrapper/Wrapper.tsx

@@ -0,0 +1,104 @@
+import React, { useMemo } from 'react';
+import { View } from 'react-native';
+import type { WrapperProps } from './Wrapper.types';
+import { getWrapperStyles } from './Wrapper.styles';
+import { useTokens } from '../../tokens/useTokens';
+
+/**
+ * Wrapper — Lightweight, invisible layout container.
+ *
+ * Same layout API as Frame (direction, spacing, alignment, sizing)
+ * but with zero appearance overhead. No background, border, shadow,
+ * theme context, or interactivity. Always renders a plain View.
+ *
+ * Use Wrapper for structural layout. Use Frame when you need visual
+ * appearance or theme/elevation context.
+ *
+ * @example
+ * ```tsx
+ * <Wrapper direction="horizontal" gap="md" align="center">
+ *   <Button onPress={() => {}}>Save</Button>
+ *   <Button variant="ghost" onPress={() => {}}>Cancel</Button>
+ * </Wrapper>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Wrapper padding={{ x: 'lg', y: 'md' }} gap="sm">
+ *   <Text>Spaced content with no background</Text>
+ * </Wrapper>
+ * ```
+ */
+export function Wrapper({
+  children,
+  direction,
+  wrap,
+  reverse,
+  align,
+  justify,
+  padding,
+  gap,
+  width,
+  height,
+  minWidth,
+  maxWidth,
+  minHeight,
+  maxHeight,
+  style,
+  // Testing & platform
+  testID,
+  nativeID,
+  ref,
+}: WrapperProps) {
+  // Get the theme's design tokens so we can convert spacing names (like 'md')
+  // into pixel values. The "1" is the default elevation level — Wrapper doesn't
+  // have its own elevation, but tokens need one for the spacing lookups.
+  const tokens = useTokens(1);
+
+  // Calculate the layout styles (direction, spacing, alignment, sizing).
+  // Wrapped in useMemo so it only recalculates when one of the props changes,
+  // instead of running on every render.
+  const containerStyle = useMemo(
+    () => getWrapperStyles({
+      tokens,
+      direction,
+      wrap,
+      reverse,
+      align,
+      justify,
+      padding,
+      gap,
+      width,
+      height,
+      minWidth,
+      maxWidth,
+      minHeight,
+      maxHeight,
+    }),
+    [
+      tokens, direction, wrap, reverse,
+      align, justify, padding, gap,
+      width, height, minWidth, maxWidth, minHeight, maxHeight,
+    ],
+  );
+
+  // Normalize user's custom styles into an array so we can merge them.
+  // The user can pass a single style object or an array of style objects.
+  const userStyles = Array.isArray(style) ? style : style ? [style] : [];
+
+  // Render a plain View — no background, no border, no interactivity.
+  // User's custom styles are applied last so they can override layout defaults.
+  return (
+    <View
+      ref={ref}
+      testID={testID}
+      nativeID={nativeID}
+      // Wrapper is a layout-only container with no semantic meaning.
+      // "none" tells screen readers to skip this element and read its children directly.
+      accessibilityRole="none"
+      style={[containerStyle, ...userStyles]}
+    >
+      {children}
+    </View>
+  );
+}

package/src/primitives/Wrapper/Wrapper.types.ts

@@ -0,0 +1,149 @@
+import type { View, ViewStyle } from 'react-native';
+import type {
+  Direction,
+  Alignment,
+  Justification,
+  PaddingProp,
+  GapProp,
+  SizingMode,
+} from '../Frame/Frame.types';
+
+/**
+ * Props for Wrapper — a lightweight, invisible layout container.
+ *
+ * Same layout API as Frame (direction, spacing, alignment, sizing) but
+ * with zero appearance: no background, border, shadow, radius, theme
+ * context, or interactivity. Always renders a plain `<View>`.
+ *
+ * Use Wrapper for structural layout. Use Frame when you need visual
+ * appearance or theme/elevation context.
+ *
+ * @example
+ * ```tsx
+ * // Horizontal row with spacing
+ * <Wrapper direction="horizontal" gap="md" align="center">
+ *   <Button onPress={() => {}}>Save</Button>
+ *   <Button variant="ghost" onPress={() => {}}>Cancel</Button>
+ * </Wrapper>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Padded vertical stack
+ * <Wrapper padding={{ x: 'lg', y: 'md' }} gap="sm">
+ *   <Text>First item</Text>
+ *   <Text>Second item</Text>
+ * </Wrapper>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Full-width centered container
+ * <Wrapper width="fill" align="center" justify="center">
+ *   <Text>Centered content</Text>
+ * </Wrapper>
+ * ```
+ */
+export interface WrapperProps {
+  /**
+   * Child elements. Must be React Native elements (View, Text, etc.).
+   * Unlike Frame, raw strings are NOT auto-wrapped in `<Text>`.
+   */
+  readonly children: React.ReactNode;
+
+  // ── Layout ──
+
+  /** Flex direction. @default 'vertical' */
+  readonly direction?: Direction;
+
+  /** Enable flex wrap. @default false */
+  readonly wrap?: boolean;
+
+  /** Reverse flex direction. @default false */
+  readonly reverse?: boolean;
+
+  // ── Alignment ──
+
+  /** Cross-axis alignment of children. */
+  readonly align?: Alignment;
+
+  /** Main-axis justification of children. */
+  readonly justify?: Justification;
+
+  // ── Spacing ──
+
+  /**
+   * Padding inside the wrapper.
+   *
+   * @example
+   * ```tsx
+   * <Wrapper padding="md" />                        // uniform token
+   * <Wrapper padding={16} />                         // uniform px
+   * <Wrapper padding={{ x: 'lg', y: 'sm' }} />      // axis shorthand
+   * <Wrapper padding={{ top: 8, bottom: 16 }} />     // per-side
+   * ```
+   */
+  readonly padding?: PaddingProp;
+
+  /**
+   * Gap between children.
+   *
+   * @example
+   * ```tsx
+   * <Wrapper gap="md" />                             // uniform token
+   * <Wrapper gap={12} />                             // uniform px
+   * <Wrapper gap={{ row: 'sm', column: 'lg' }} />    // per-axis
+   * ```
+   */
+  readonly gap?: GapProp;
+
+  // ── Sizing ──
+
+  /**
+   * Width sizing: `'hug'` (shrink to content), `'fill'` (expand), or fixed px.
+   * @example
+   * ```tsx
+   * <Wrapper width="fill" />   // expand to fill parent
+   * <Wrapper width={300} />    // fixed 300px
+   * ```
+   */
+  readonly width?: SizingMode;
+
+  /**
+   * Height sizing: `'hug'` (shrink to content), `'fill'` (expand), or fixed px.
+   * @example
+   * ```tsx
+   * <Wrapper height="fill" />  // expand to fill parent
+   * <Wrapper 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;
+
+  // ── 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 element. */
+  readonly ref?: React.Ref<View>;
+
+  // ── Style override ──
+
+  /** Custom style overrides (applied last). */
+  readonly style?: ViewStyle | ViewStyle[];
+}

package/src/primitives/Wrapper/index.ts

@@ -0,0 +1,2 @@
+export { Wrapper } from './Wrapper';
+export type { WrapperProps } from './Wrapper.types';