@newtonedev/components 0.1.18 → 0.1.19

package/src/layout/Section/Section.tsx

@@ -0,0 +1,57 @@
+import React, { useMemo } from 'react';
+import { View } from 'react-native';
+import type { SectionProps } from './Section.types';
+import { getSectionStyles } from './Section.styles';
+import { useTokens } from 'newtone-api';
+
+/**
+ * Section — Full-width layout container that constrains content width.
+ *
+ * Section fills all available horizontal space and centers its content
+ * within a maximum width determined by the `size` preset. It provides
+ * horizontal padding so content doesn't touch the viewport edges when
+ * the screen is narrower than the max width.
+ *
+ * Section is invisible — no background, border, or shadow. It is purely
+ * a layout tool for structuring page-level content regions.
+ *
+ * @example
+ * ```tsx
+ * <Section size="md" gap={24} padding={{ y: 48 }}>
+ *   <Text role="heading">Documentation</Text>
+ *   <Text role="body">Content constrained to 768px max width.</Text>
+ * </Section>
+ * ```
+ */
+export function Section({
+  children,
+  size,
+  fill,
+  gap,
+  padding,
+  testID,
+  nativeID,
+  ref,
+  style,
+}: SectionProps) {
+  const tokens = useTokens();
+
+  const containerStyle = useMemo(
+    () => getSectionStyles({ tokens, size, fill, gap, padding }),
+    [tokens, size, fill, gap, padding],
+  );
+
+  const userStyles = Array.isArray(style) ? style : style ? [style] : [];
+
+  return (
+    <View
+      ref={ref}
+      testID={testID}
+      nativeID={nativeID}
+      accessibilityRole="none"
+      style={[containerStyle, ...userStyles]}
+    >
+      {children}
+    </View>
+  );
+}

package/src/layout/Section/Section.types.ts

@@ -0,0 +1,85 @@
+import type { View, ViewStyle } from 'react-native';
+import type { GapProp, PaddingProp } from '../../primitives/Frame/Frame.types';
+
+/**
+ * Content width preset for Section.
+ *
+ * | Size   | Max Width | Horizontal Padding |
+ * |:------:|:---------:|:------------------:|
+ * | `'xs'` | 480px     | 24px               |
+ * | `'sm'` | 640px     | 24px               |
+ * | `'md'` | 768px     | 24px               |
+ * | `'lg'` | 1024px    | 32px               |
+ * | `'xl'` | 1280px    | 40px               |
+ * | `'full'` | none    | 0px                |
+ */
+export type SectionSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+
+/**
+ * Props for Section — a full-width layout container that constrains content width.
+ *
+ * Section fills all available horizontal space and centers its content
+ * within a maximum width. It provides horizontal padding so content
+ * doesn't touch the edges when the viewport is narrower than the max width.
+ *
+ * Section is invisible — no background, border, or shadow.
+ *
+ * @example
+ * ```tsx
+ * <Section size="md" gap={24}>
+ *   <Text role="heading">Page Title</Text>
+ *   <Text role="body">Content constrained to 768px.</Text>
+ * </Section>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Section size="full">
+ *   <HeroImage />
+ * </Section>
+ * ```
+ */
+export interface SectionProps {
+  /** Child elements. */
+  readonly children?: React.ReactNode;
+
+  /**
+   * Content width preset. Controls the maximum width and default horizontal padding.
+   *
+   * @default 'lg'
+   */
+  readonly size?: SectionSize;
+
+  /**
+   * Gap between children.
+   */
+  readonly gap?: GapProp;
+
+  /**
+   * When true, the Section expands to fill all available vertical space (`flex: 1`).
+   * Useful inside a Viewport when content is shorter than the screen.
+   *
+   * @default false
+   */
+  readonly fill?: boolean;
+
+  /**
+   * Vertical padding (top and bottom).
+   * Horizontal padding is determined by the size preset.
+   */
+  readonly padding?: PaddingProp;
+
+  // ── Testing & Platform ──
+
+  /** Test identifier — maps to `data-testid` on web. */
+  readonly testID?: string;
+
+  /** DOM id — maps to `id` attribute on web. */
+  readonly nativeID?: string;
+
+  /** Ref to the underlying View element. */
+  readonly ref?: React.Ref<View>;
+
+  /** Custom style overrides (applied last). */
+  readonly style?: ViewStyle | ViewStyle[];
+}

package/src/layout/Section/index.ts

@@ -0,0 +1,2 @@
+export { Section } from './Section';
+export type { SectionProps, SectionSize } from './Section.types';

package/src/layout/Viewport/Viewport.tsx

@@ -0,0 +1,52 @@
+import React from 'react';
+import { ScrollView, StyleSheet } from 'react-native';
+import type { ViewportProps } from './Viewport.types';
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+  },
+  content: {
+    flexGrow: 1,
+  },
+});
+
+/**
+ * Viewport — Full-height scrollable layout root.
+ *
+ * Viewport fills all available height (`flex: 1`) and scrolls vertically
+ * when content overflows. It stacks children in a column.
+ *
+ * Viewport is invisible — no background, border, or shadow. It is purely
+ * a layout tool for structuring the outermost page container.
+ *
+ * @example
+ * ```tsx
+ * <Viewport>
+ *   <Section size="lg" padding={{ y: 48 }}>
+ *     <Text role="heading">Welcome</Text>
+ *   </Section>
+ * </Viewport>
+ * ```
+ */
+export function Viewport({
+  children,
+  testID,
+  nativeID,
+  ref,
+  style,
+}: ViewportProps) {
+  const userStyles = Array.isArray(style) ? style : style ? [style] : [];
+
+  return (
+    <ScrollView
+      ref={ref}
+      testID={testID}
+      nativeID={nativeID}
+      style={styles.root}
+      contentContainerStyle={[styles.content, ...userStyles]}
+    >
+      {children}
+    </ScrollView>
+  );
+}

package/src/layout/Viewport/Viewport.types.ts

@@ -0,0 +1,40 @@
+import type { ScrollView, ViewStyle } from 'react-native';
+
+/**
+ * Props for Viewport — a full-height scrollable layout root.
+ *
+ * Viewport fills all available height and scrolls vertically when its
+ * content overflows. It stacks children in a column and provides no
+ * visual styling — no background, border, or shadow.
+ *
+ * Use Viewport as the outermost layout container for a page or screen.
+ *
+ * @example
+ * ```tsx
+ * <Viewport>
+ *   <Section size="sm" fill>
+ *     <Frame elevation={1}>
+ *       <Text>Centered content</Text>
+ *     </Frame>
+ *   </Section>
+ * </Viewport>
+ * ```
+ */
+export interface ViewportProps {
+  /** Child elements (typically Sections). */
+  readonly children?: React.ReactNode;
+
+  // ── Testing & Platform ──
+
+  /** Test identifier — maps to `data-testid` on web. */
+  readonly testID?: string;
+
+  /** DOM id — maps to `id` attribute on web. */
+  readonly nativeID?: string;
+
+  /** Ref to the underlying ScrollView element. */
+  readonly ref?: React.Ref<ScrollView>;
+
+  /** Custom style overrides applied to the scroll content container. */
+  readonly style?: ViewStyle | ViewStyle[];
+}

package/src/layout/Viewport/index.ts

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

package/src/{primitives → layout}/Wrapper/Wrapper.styles.ts

@@ -11,7 +11,7 @@ import type {
   PositionType,
   OffsetValue,
   OverflowMode,
-} from '../Frame/Frame.types';
+} from '../../primitives/Frame/Frame.types';
 import {
   resolvePadding,
   resolveGap,
@@ -19,7 +19,7 @@ import {
   resolveFlexDirection,
   resolveAlignment,
   resolveJustification,
-} from '../Frame/Frame.utils';
+} from '../../primitives/Frame/Frame.utils';
 
 export interface WrapperStyleInput {
   readonly tokens: ResolvedTokens;
@@ -45,7 +45,6 @@ export interface WrapperStyleInput {
   readonly left?: OffsetValue;
   readonly zIndex?: number;
   readonly overflow?: OverflowMode;
-  readonly opacity?: number;
 }
 
 /**
@@ -78,28 +77,19 @@ export function getWrapperStyles(input: WrapperStyleInput): ViewStyle {
     left,
     zIndex,
     overflow,
-    opacity,
   } = 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;
@@ -109,7 +99,6 @@ export function getWrapperStyles(input: WrapperStyleInput): ViewStyle {
   }
 
   // ── 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;
@@ -117,19 +106,15 @@ export function getWrapperStyles(input: WrapperStyleInput): ViewStyle {
   }
 
   // ── 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;
 
   // ── Positioning ──
-  // Set CSS position mode and offsets for absolute/fixed/sticky positioning.
   if (position) container.position = position;
   if (top !== undefined) container.top = top;
   if (right !== undefined) container.right = right;
@@ -137,9 +122,6 @@ export function getWrapperStyles(input: WrapperStyleInput): ViewStyle {
   if (left !== undefined) container.left = left;
   if (zIndex !== undefined) container.zIndex = zIndex;
   if (overflow) container.overflow = overflow;
-  if (opacity !== undefined) container.opacity = opacity;
 
-  // 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 → layout}/Wrapper/Wrapper.tsx

@@ -13,21 +13,6 @@ import { useTokens } from 'newtone-api';
  *
  * 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="tertiary" 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,
@@ -44,7 +29,6 @@ export function Wrapper({
   maxWidth,
   minHeight,
   maxHeight,
-  // Positioning
   position,
   top,
   right,
@@ -53,20 +37,13 @@ export function Wrapper({
   zIndex,
   overflow,
   pointerEvents,
-  opacity,
   style,
-  // Testing & platform
   testID,
   nativeID,
   ref,
 }: WrapperProps) {
-  // Get the theme's design tokens so we can convert spacing names (like 'md')
-  // into pixel values. Wrapper inherits elevation from FrameContext automatically.
   const tokens = useTokens();
 
-  // 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,
@@ -90,30 +67,23 @@ export function Wrapper({
       left,
       zIndex,
       overflow,
-      opacity,
     }),
     [
       tokens, direction, wrap, reverse,
       align, justify, padding, gap,
       width, height, minWidth, maxWidth, minHeight, maxHeight,
-      position, top, right, bottom, left, zIndex, overflow, opacity,
+      position, top, right, bottom, left, zIndex, overflow,
     ],
   );
 
-  // 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}
       pointerEvents={pointerEvents}
-      // 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]}
     >

package/src/{primitives → layout}/Wrapper/Wrapper.types.ts

@@ -10,7 +10,7 @@ import type {
   OffsetValue,
   OverflowMode,
   PointerEventsMode,
-} from '../Frame/Frame.types';
+} from '../../primitives/Frame/Frame.types';
 
 /**
  * Props for Wrapper — a lightweight, invisible layout container.
@@ -173,9 +173,6 @@ export interface WrapperProps {
    */
   readonly pointerEvents?: PointerEventsMode;
 
-  /** Opacity of the element (0 = fully transparent, 1 = fully opaque). */
-  readonly opacity?: number;
-
   // ── Testing & Platform ──
 
   /** Test identifier — maps to `data-testid` on web. Used by testing libraries. */

package/src/layout/index.ts

@@ -0,0 +1,15 @@
+// Page
+export { Page } from './Page';
+export type { PageProps } from './Page';
+
+// Viewport
+export { Viewport } from './Viewport';
+export type { ViewportProps } from './Viewport';
+
+// Wrapper
+export { Wrapper } from './Wrapper';
+export type { WrapperProps } from './Wrapper';
+
+// Section
+export { Section } from './Section';
+export type { SectionProps, SectionSize } from './Section';

package/src/primitives/Card/Card.styles.ts

@@ -0,0 +1,182 @@
+import type { ViewStyle } from 'react-native';
+import { StyleSheet } from 'react-native';
+import type { ResolvedTokens, AppearanceTokens } from 'newtone-api';
+import type { ThemeName, AppearanceName } from 'newtone-api';
+import type {
+  PaddingProp,
+  GapProp,
+  SizingMode,
+  Direction,
+  Alignment,
+  Justification,
+  RadiusProp,
+} from '../Frame/Frame.types';
+import {
+  resolvePadding,
+  resolveGap,
+  resolveSizing,
+  resolveFlexDirection,
+  resolveAlignment,
+  resolveJustification,
+  resolveRadiusCorners,
+  hasPositiveRadius,
+} from '../Frame/Frame.utils';
+
+// ── Input ────────────────────────────────────────────────────────
+
+export interface CardStyleInput {
+  readonly tokens: ResolvedTokens;
+
+  // Theme / Appearance (theme is inherited, not user-supplied)
+  readonly theme: ThemeName;
+  readonly appearance?: AppearanceName;
+
+  // Layout
+  readonly direction?: Direction;
+  readonly wrap?: boolean;
+  readonly reverse?: boolean;
+
+  // Alignment
+  readonly align?: Alignment;
+  readonly justify?: Justification;
+
+  // Spacing
+  readonly padding?: PaddingProp;
+  readonly gap?: GapProp;
+
+  // Sizing
+  readonly width?: SizingMode;
+  readonly height?: SizingMode;
+  readonly minWidth?: number;
+  readonly maxWidth?: number;
+  readonly minHeight?: number;
+  readonly maxHeight?: number;
+
+  // Appearance
+  readonly radius?: RadiusProp;
+
+  // Interactivity
+  readonly disabled?: boolean;
+}
+
+// ── Output ───────────────────────────────────────────────────────
+
+export interface CardStyles {
+  /** Main container style */
+  readonly container: ViewStyle;
+  /** Style applied when pressed (background shift) */
+  readonly pressed: ViewStyle;
+}
+
+// ── Builder ──────────────────────────────────────────────────────
+
+/**
+ * Build all visual styles for a Card.
+ *
+ * Cards are always elevated with a border and drop shadow.
+ * Takes the Card's props + design tokens and produces:
+ * - container: the main style (background, border, shadow, layout, spacing, etc.)
+ * - pressed: style override applied when the user is pressing
+ */
+export function getCardStyles(input: CardStyleInput): CardStyles {
+  const {
+    tokens,
+    theme,
+    appearance = 'main',
+    direction = 'vertical',
+    wrap = false,
+    reverse = false,
+    align,
+    justify,
+    padding,
+    gap,
+    width,
+    height,
+    minWidth,
+    maxWidth,
+    minHeight,
+    maxHeight,
+    radius,
+    disabled = false,
+  } = input;
+
+  const container: Record<string, unknown> = {};
+
+  // ── Background & foreground ──
+  const appearanceTokens: AppearanceTokens = tokens.colors[theme][appearance];
+  container.backgroundColor = appearanceTokens.background;
+  container.color = appearanceTokens.fontPrimary;
+
+  // ── Layout ──
+  container.display = 'flex';
+  container.flexDirection = resolveFlexDirection(direction, reverse);
+  if (wrap) container.flexWrap = 'wrap';
+
+  // ── Alignment ──
+  if (align) container.alignItems = resolveAlignment(align);
+  if (justify) container.justifyContent = resolveJustification(justify);
+
+  // ── 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 ──
+  if (gap !== undefined) {
+    const g = resolveGap(gap, tokens);
+    container.rowGap = g.rowGap;
+    container.columnGap = g.columnGap;
+  }
+
+  // ── Sizing ──
+  Object.assign(container, resolveSizing(width, height));
+
+  // ── Constraints ──
+  if (minWidth !== undefined) container.minWidth = minWidth;
+  if (maxWidth !== undefined) container.maxWidth = maxWidth;
+  if (minHeight !== undefined) container.minHeight = minHeight;
+  if (maxHeight !== undefined) container.maxHeight = maxHeight;
+
+  // ── Radius ──
+  if (radius !== undefined) {
+    const corners = resolveRadiusCorners(radius, tokens);
+    container.borderTopLeftRadius = corners.topLeft;
+    container.borderTopRightRadius = corners.topRight;
+    container.borderBottomLeftRadius = corners.bottomLeft;
+    container.borderBottomRightRadius = corners.bottomRight;
+
+    if (hasPositiveRadius(corners)) {
+      container.overflow = 'hidden';
+    }
+  }
+
+  // ── Border (always on) ──
+  container.borderWidth = 1;
+  container.borderColor = appearanceTokens.divider;
+
+  // ── Shadow (always elevated) ──
+  container.shadowColor = '#000';
+  container.shadowOffset = { width: 0, height: 2 };
+  container.shadowOpacity = 0.12;
+  container.shadowRadius = 6;
+  container.elevation = 4; // Android-specific shadow depth
+
+  // ── Disabled ──
+  if (disabled) {
+    container.opacity = 0.5;
+  }
+
+  // ── Pressed state ──
+  const pressed = StyleSheet.create({
+    s: { backgroundColor: appearanceTokens.fontSecondary },
+  }).s;
+
+  return {
+    container: StyleSheet.create({ c: container as ViewStyle }).c,
+    pressed,
+  };
+}