reactnatively-primitives 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2024 Hakizimana Fred
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,237 @@
+import React, { ReactNode } from 'react';
+import { ViewProps, StyleProp, ViewStyle, PressableProps, TextProps, TextStyle } from 'react-native';
+import { GlassElevation, GlassTintVariant, GlassHighlight, RadiiKey, ThemeColorKey, fontWeight, lineHeight } from 'reactnatively-theme';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Full glass configuration for when fine-grained control is needed.
+ * Pass this as the `glass` prop to Surface.
+ */
+interface GlassSurfaceConfig {
+    elevation?: GlassElevation;
+    variant?: GlassTintVariant;
+    highlight?: GlassHighlight | boolean;
+    border?: boolean;
+    borderWidth?: number;
+    blurOverride?: number;
+    tintOverride?: string;
+    glow?: {
+        color: string;
+        radius?: number;
+        opacity?: number;
+    } | false;
+}
+/**
+ * Surface is the unified rendering unit.
+ *
+ * - glass={true}                 → GlassView with optional shorthand elevation/variant
+ * - glass={GlassSurfaceConfig}   → GlassView with full config
+ * - glass={false} | undefined    → plain View with optional bg color
+ * - animated={true}              → wraps the output in Reanimated Animated.View
+ */
+interface SurfaceProps extends Omit<ViewProps, 'style'> {
+    /** Enable glass rendering. Pass true for defaults or a GlassSurfaceConfig for full control. */
+    glass?: boolean | GlassSurfaceConfig;
+    /** Shorthand glass elevation — only meaningful when glass=true */
+    elevation?: GlassElevation;
+    /** Shorthand glass variant — only meaningful when glass=true */
+    variant?: GlassTintVariant;
+    /** Solid background color (used when glass is false or undefined) */
+    bg?: string;
+    /** Border radius — accepts a RadiiKey token name or a raw pixel number */
+    borderRadius?: number | RadiiKey;
+    /** Show a border ring */
+    border?: boolean;
+    /** Border color override */
+    borderColor?: string;
+    /** Border width override */
+    borderWidth?: number;
+    /** Wrap in Reanimated Animated.View for animated transforms */
+    animated?: boolean;
+    style?: StyleProp<ViewStyle>;
+    /** Style applied to the inner content wrapper (passed through to GlassView contentStyle or plain View) */
+    contentStyle?: StyleProp<ViewStyle>;
+    children?: ReactNode;
+}
+
+/**
+ * Surface — the unified rendering primitive.
+ *
+ * Handles three rendering paths:
+ *   1. glass=true/config → GlassView (liquid glass layer stack)
+ *   2. solid bg          → plain View with backgroundColor
+ *   3. animated=true     → wraps whichever output in Animated.View
+ *
+ * All hooks are called unconditionally (Rules of Hooks). The glass/solid
+ * branch decision happens in the return, not at hook call sites.
+ */
+declare const Surface: React.NamedExoticComponent<SurfaceProps>;
+
+/**
+ * GlassPressable — animated pressable primitive built on Surface.
+ *
+ * Combines:
+ *   - Surface (glass or solid background rendering)
+ *   - Press scale + opacity animation via Reanimated
+ *   - Optional haptic feedback via expo-haptics
+ *
+ * Used as the interactive base for all interactive glass components
+ * (buttons, cards, pills, chips, etc.)
+ */
+interface GlassPressableProps extends Omit<PressableProps, 'style' | 'children'>, Omit<SurfaceProps, 'animated'> {
+    /** Scale factor applied on press. Default: 0.97 */
+    pressedScale?: number;
+    /** Opacity applied on press. Default: 0.90 */
+    pressedOpacity?: number;
+    /** Fire a haptic impact on press (requires expo-haptics). Default: false */
+    haptic?: boolean;
+    /** Show a loading state (disables interactions and passes through to children). Default: false */
+    loading?: boolean;
+    /** Disable all interactions. Default: false */
+    disabled?: boolean;
+}
+
+/**
+ * GlassPressable — the interactive foundation of the Reactnatively component system.
+ *
+ * Layer order (outer → inner):
+ *   Pressable (touch target)
+ *   └─ Animated.View (scale + opacity spring animation)
+ *      └─ Surface (glass or solid background)
+ *         └─ children
+ */
+declare const GlassPressable: React.NamedExoticComponent<GlassPressableProps>;
+
+interface PortalProps {
+    children: ReactNode;
+}
+/**
+ * Portal — mounts its children into the PortalProvider's host layer.
+ *
+ * Renders nothing at its own position in the tree; the children appear
+ * above all other content at zIndex 9999 via the PortalProvider.
+ *
+ * Usage:
+ * ```tsx
+ * <Portal>
+ *   <ModalContent />
+ * </Portal>
+ * ```
+ *
+ * Lifecycle:
+ *   - mount   → registers children in the portal registry
+ *   - update  → keeps the portal in sync when children change
+ *   - unmount → removes children from the registry
+ */
+declare function Portal({ children }: PortalProps): null;
+declare namespace Portal {
+    var displayName: string;
+}
+
+/**
+ * PortalHost — an additional named host for portals that need to be
+ * scoped below the root-level PortalProvider host.
+ *
+ * The root host is rendered automatically inside PortalProvider.
+ * Use PortalHost if you want a secondary portal target inside a specific
+ * screen or layout region (e.g. inside a bottom sheet for nested portals).
+ *
+ * Must be placed inside a PortalProvider.
+ */
+declare const PortalHost: React.MemoExoticComponent<() => react_jsx_runtime.JSX.Element>;
+
+interface PortalProviderProps {
+    children: ReactNode;
+}
+/**
+ * PortalProvider — must wrap the root of your app (alongside ThemeProvider).
+ *
+ * Maintains the registry of active portal entries and renders them in a
+ * full-screen host view layered above all other content (zIndex 9999).
+ *
+ * Architecture:
+ *   - entries state holds { key, element }[] — a plain array so React
+ *     reconciles portal renders without needing forceUpdate hacks.
+ *   - mount/update/unmount are stable references via useCallback.
+ */
+declare const PortalProvider: React.NamedExoticComponent<PortalProviderProps>;
+
+interface PortalEntry {
+    key: string;
+    element: ReactNode;
+}
+interface PortalContextValue {
+    mount: (key: string, element: ReactNode) => void;
+    unmount: (key: string) => void;
+    update: (key: string, element: ReactNode) => void;
+}
+
+/**
+ * usePortal — access the portal mount/unmount/update API.
+ *
+ * @throws if called outside a PortalProvider.
+ */
+declare function usePortal(): PortalContextValue;
+
+interface SlotProps {
+    children?: React.ReactNode;
+    style?: StyleProp<ViewStyle>;
+    [key: string]: unknown;
+}
+/**
+ * Slot — Radix-style render delegation primitive.
+ *
+ * Merges its own props with the single child element's props, then renders
+ * that child (not a wrapper element). Event handlers from both Slot and the
+ * child are composed so both fire. Styles are merged with the child's styles
+ * taking precedence.
+ *
+ * Usage — implementing `asChild` on a component:
+ * ```tsx
+ * function Button({ asChild, ...props }) {
+ *   const Comp = asChild ? Slot : Pressable;
+ *   return <Comp {...props} />;
+ * }
+ *
+ * // Render a Link as a button:
+ * <Button asChild>
+ *   <Link href="/home" />
+ * </Button>
+ * ```
+ */
+declare const Slot: React.ForwardRefExoticComponent<Omit<SlotProps, "ref"> & React.RefAttributes<unknown>>;
+
+/** Semantic text roles — map to predefined size + weight + line-height combos */
+type GlassTextVariant = 'display' | 'heading1' | 'heading2' | 'heading3' | 'heading4' | 'heading' | 'body' | 'bodyLarge' | 'label' | 'caption' | 'overline' | 'code';
+type GlassTextWeight = keyof typeof fontWeight;
+interface GlassTextProps extends Omit<TextProps, 'style'> {
+    /** Semantic variant. Defaults to 'body'. */
+    variant?: GlassTextVariant;
+    /** Theme color key or any valid CSS/RN color string */
+    color?: ThemeColorKey | string;
+    /** Override font weight token */
+    weight?: GlassTextWeight;
+    /** Override font size in pixels */
+    size?: number;
+    /** Override line height multiplier */
+    leading?: keyof typeof lineHeight;
+    /** Uppercase transform (auto-applied for 'overline' variant) */
+    uppercase?: boolean;
+    style?: TextStyle | TextStyle[];
+    children?: ReactNode;
+}
+/**
+ * GlassText — theme-aware text primitive.
+ *
+ * Automatically applies typography scale tokens and theme colors.
+ * All variants are memoized; only re-resolves when props change.
+ *
+ * ```tsx
+ * <GlassText variant="heading" color="primary">Hello</GlassText>
+ * <GlassText variant="caption" color="textMuted">Fine print</GlassText>
+ * <GlassText size={20} weight="bold">Custom size</GlassText>
+ * ```
+ */
+declare const GlassText: React.NamedExoticComponent<GlassTextProps>;
+
+export { GlassPressable, type GlassPressableProps, type GlassSurfaceConfig, GlassText, type GlassTextProps, type GlassTextVariant, type GlassTextWeight, Portal, type PortalContextValue, type PortalEntry, PortalHost, PortalProvider, Slot, Surface, type SurfaceProps, usePortal };

package/dist/index.d.ts

@@ -0,0 +1,237 @@
+import React, { ReactNode } from 'react';
+import { ViewProps, StyleProp, ViewStyle, PressableProps, TextProps, TextStyle } from 'react-native';
+import { GlassElevation, GlassTintVariant, GlassHighlight, RadiiKey, ThemeColorKey, fontWeight, lineHeight } from 'reactnatively-theme';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Full glass configuration for when fine-grained control is needed.
+ * Pass this as the `glass` prop to Surface.
+ */
+interface GlassSurfaceConfig {
+    elevation?: GlassElevation;
+    variant?: GlassTintVariant;
+    highlight?: GlassHighlight | boolean;
+    border?: boolean;
+    borderWidth?: number;
+    blurOverride?: number;
+    tintOverride?: string;
+    glow?: {
+        color: string;
+        radius?: number;
+        opacity?: number;
+    } | false;
+}
+/**
+ * Surface is the unified rendering unit.
+ *
+ * - glass={true}                 → GlassView with optional shorthand elevation/variant
+ * - glass={GlassSurfaceConfig}   → GlassView with full config
+ * - glass={false} | undefined    → plain View with optional bg color
+ * - animated={true}              → wraps the output in Reanimated Animated.View
+ */
+interface SurfaceProps extends Omit<ViewProps, 'style'> {
+    /** Enable glass rendering. Pass true for defaults or a GlassSurfaceConfig for full control. */
+    glass?: boolean | GlassSurfaceConfig;
+    /** Shorthand glass elevation — only meaningful when glass=true */
+    elevation?: GlassElevation;
+    /** Shorthand glass variant — only meaningful when glass=true */
+    variant?: GlassTintVariant;
+    /** Solid background color (used when glass is false or undefined) */
+    bg?: string;
+    /** Border radius — accepts a RadiiKey token name or a raw pixel number */
+    borderRadius?: number | RadiiKey;
+    /** Show a border ring */
+    border?: boolean;
+    /** Border color override */
+    borderColor?: string;
+    /** Border width override */
+    borderWidth?: number;
+    /** Wrap in Reanimated Animated.View for animated transforms */
+    animated?: boolean;
+    style?: StyleProp<ViewStyle>;
+    /** Style applied to the inner content wrapper (passed through to GlassView contentStyle or plain View) */
+    contentStyle?: StyleProp<ViewStyle>;
+    children?: ReactNode;
+}
+
+/**
+ * Surface — the unified rendering primitive.
+ *
+ * Handles three rendering paths:
+ *   1. glass=true/config → GlassView (liquid glass layer stack)
+ *   2. solid bg          → plain View with backgroundColor
+ *   3. animated=true     → wraps whichever output in Animated.View
+ *
+ * All hooks are called unconditionally (Rules of Hooks). The glass/solid
+ * branch decision happens in the return, not at hook call sites.
+ */
+declare const Surface: React.NamedExoticComponent<SurfaceProps>;
+
+/**
+ * GlassPressable — animated pressable primitive built on Surface.
+ *
+ * Combines:
+ *   - Surface (glass or solid background rendering)
+ *   - Press scale + opacity animation via Reanimated
+ *   - Optional haptic feedback via expo-haptics
+ *
+ * Used as the interactive base for all interactive glass components
+ * (buttons, cards, pills, chips, etc.)
+ */
+interface GlassPressableProps extends Omit<PressableProps, 'style' | 'children'>, Omit<SurfaceProps, 'animated'> {
+    /** Scale factor applied on press. Default: 0.97 */
+    pressedScale?: number;
+    /** Opacity applied on press. Default: 0.90 */
+    pressedOpacity?: number;
+    /** Fire a haptic impact on press (requires expo-haptics). Default: false */
+    haptic?: boolean;
+    /** Show a loading state (disables interactions and passes through to children). Default: false */
+    loading?: boolean;
+    /** Disable all interactions. Default: false */
+    disabled?: boolean;
+}
+
+/**
+ * GlassPressable — the interactive foundation of the Reactnatively component system.
+ *
+ * Layer order (outer → inner):
+ *   Pressable (touch target)
+ *   └─ Animated.View (scale + opacity spring animation)
+ *      └─ Surface (glass or solid background)
+ *         └─ children
+ */
+declare const GlassPressable: React.NamedExoticComponent<GlassPressableProps>;
+
+interface PortalProps {
+    children: ReactNode;
+}
+/**
+ * Portal — mounts its children into the PortalProvider's host layer.
+ *
+ * Renders nothing at its own position in the tree; the children appear
+ * above all other content at zIndex 9999 via the PortalProvider.
+ *
+ * Usage:
+ * ```tsx
+ * <Portal>
+ *   <ModalContent />
+ * </Portal>
+ * ```
+ *
+ * Lifecycle:
+ *   - mount   → registers children in the portal registry
+ *   - update  → keeps the portal in sync when children change
+ *   - unmount → removes children from the registry
+ */
+declare function Portal({ children }: PortalProps): null;
+declare namespace Portal {
+    var displayName: string;
+}
+
+/**
+ * PortalHost — an additional named host for portals that need to be
+ * scoped below the root-level PortalProvider host.
+ *
+ * The root host is rendered automatically inside PortalProvider.
+ * Use PortalHost if you want a secondary portal target inside a specific
+ * screen or layout region (e.g. inside a bottom sheet for nested portals).
+ *
+ * Must be placed inside a PortalProvider.
+ */
+declare const PortalHost: React.MemoExoticComponent<() => react_jsx_runtime.JSX.Element>;
+
+interface PortalProviderProps {
+    children: ReactNode;
+}
+/**
+ * PortalProvider — must wrap the root of your app (alongside ThemeProvider).
+ *
+ * Maintains the registry of active portal entries and renders them in a
+ * full-screen host view layered above all other content (zIndex 9999).
+ *
+ * Architecture:
+ *   - entries state holds { key, element }[] — a plain array so React
+ *     reconciles portal renders without needing forceUpdate hacks.
+ *   - mount/update/unmount are stable references via useCallback.
+ */
+declare const PortalProvider: React.NamedExoticComponent<PortalProviderProps>;
+
+interface PortalEntry {
+    key: string;
+    element: ReactNode;
+}
+interface PortalContextValue {
+    mount: (key: string, element: ReactNode) => void;
+    unmount: (key: string) => void;
+    update: (key: string, element: ReactNode) => void;
+}
+
+/**
+ * usePortal — access the portal mount/unmount/update API.
+ *
+ * @throws if called outside a PortalProvider.
+ */
+declare function usePortal(): PortalContextValue;
+
+interface SlotProps {
+    children?: React.ReactNode;
+    style?: StyleProp<ViewStyle>;
+    [key: string]: unknown;
+}
+/**
+ * Slot — Radix-style render delegation primitive.
+ *
+ * Merges its own props with the single child element's props, then renders
+ * that child (not a wrapper element). Event handlers from both Slot and the
+ * child are composed so both fire. Styles are merged with the child's styles
+ * taking precedence.
+ *
+ * Usage — implementing `asChild` on a component:
+ * ```tsx
+ * function Button({ asChild, ...props }) {
+ *   const Comp = asChild ? Slot : Pressable;
+ *   return <Comp {...props} />;
+ * }
+ *
+ * // Render a Link as a button:
+ * <Button asChild>
+ *   <Link href="/home" />
+ * </Button>
+ * ```
+ */
+declare const Slot: React.ForwardRefExoticComponent<Omit<SlotProps, "ref"> & React.RefAttributes<unknown>>;
+
+/** Semantic text roles — map to predefined size + weight + line-height combos */
+type GlassTextVariant = 'display' | 'heading1' | 'heading2' | 'heading3' | 'heading4' | 'heading' | 'body' | 'bodyLarge' | 'label' | 'caption' | 'overline' | 'code';
+type GlassTextWeight = keyof typeof fontWeight;
+interface GlassTextProps extends Omit<TextProps, 'style'> {
+    /** Semantic variant. Defaults to 'body'. */
+    variant?: GlassTextVariant;
+    /** Theme color key or any valid CSS/RN color string */
+    color?: ThemeColorKey | string;
+    /** Override font weight token */
+    weight?: GlassTextWeight;
+    /** Override font size in pixels */
+    size?: number;
+    /** Override line height multiplier */
+    leading?: keyof typeof lineHeight;
+    /** Uppercase transform (auto-applied for 'overline' variant) */
+    uppercase?: boolean;
+    style?: TextStyle | TextStyle[];
+    children?: ReactNode;
+}
+/**
+ * GlassText — theme-aware text primitive.
+ *
+ * Automatically applies typography scale tokens and theme colors.
+ * All variants are memoized; only re-resolves when props change.
+ *
+ * ```tsx
+ * <GlassText variant="heading" color="primary">Hello</GlassText>
+ * <GlassText variant="caption" color="textMuted">Fine print</GlassText>
+ * <GlassText size={20} weight="bold">Custom size</GlassText>
+ * ```
+ */
+declare const GlassText: React.NamedExoticComponent<GlassTextProps>;
+
+export { GlassPressable, type GlassPressableProps, type GlassSurfaceConfig, GlassText, type GlassTextProps, type GlassTextVariant, type GlassTextWeight, Portal, type PortalContextValue, type PortalEntry, PortalHost, PortalProvider, Slot, Surface, type SurfaceProps, usePortal };