@sublime-ui/ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Mkandawire and Sublime UI contributors
+
+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/README.md

@@ -0,0 +1,40 @@
+# @sublime-ui/ui
+
+Cross-platform **navigation** and **layout primitives** for
+[Sublime UI](https://sublime-ui.github.io/sublime-ui/).
+
+Navigation is authored as a **storybook** — a `book` of `page`s, written once per
+platform — and compiled ahead of time (by `@sublime-ui/devkit`'s `build:nav`)
+into idiomatic React Navigation (mobile) and react-router (web), with a fully
+typed route map.
+
+```ts
+import { book, page, link } from '@sublime-ui/ui/navigation';
+import { Home } from '../screens/web/Home';
+
+export default book({
+  format: 'sidebar', // web: 'sidebar' | 'stack' | 'tabs'
+  pages: {
+    home: page(Home, { title: 'Home' }),
+  },
+});
+```
+
+At runtime, `useNav()` gives you type-checked navigation: `turnTo`, `turnBack`,
+`current`, and `params<T>()`. Layout primitives (`Screen`, `Stack`, `Row`,
+`Spacer`) render natively on each platform.
+
+## Install
+
+```bash
+npm install @sublime-ui/ui
+```
+
+## Documentation
+
+The storybook model and typed navigation:
+**https://sublime-ui.github.io/sublime-ui/docs/navigation/storybook**
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Screen } from './layout/Screen.js';
+export { ScreenProps } from './layout/Screen.types.js';
+export { Stack } from './layout/Stack.js';
+export { Row } from './layout/Row.js';
+export { Spacer } from './layout/Spacer.js';
+export { FlexAlign, FlexJustify, FlexProps, RowProps, SpacerProps } from './layout/Stack.types.js';
+import 'react';

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./layout";

package/dist/layout/Row.d.ts

@@ -0,0 +1,6 @@
+import * as react from 'react';
+import { RowProps } from './Stack.types.js';
+
+declare function Row({ children, gap, align, justify, wrap, testID }: RowProps): react.JSX.Element;
+
+export { Row };

package/dist/layout/Row.js

@@ -0,0 +1,29 @@
+import { jsx } from "react/jsx-runtime";
+const ALIGN = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  stretch: "stretch"
+};
+const JUSTIFY = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  between: "space-between",
+  around: "space-around",
+  evenly: "space-evenly"
+};
+function Row({ children, gap, align, justify, wrap, testID }) {
+  const style = {
+    display: "flex",
+    flexDirection: "row",
+    flexWrap: wrap ? "wrap" : void 0,
+    gap,
+    alignItems: align ? ALIGN[align] : void 0,
+    justifyContent: justify ? JUSTIFY[justify] : void 0
+  };
+  return /* @__PURE__ */ jsx("div", { "data-testid": testID, style, children });
+}
+export {
+  Row
+};

package/dist/layout/Screen.d.ts

@@ -0,0 +1,6 @@
+import * as react from 'react';
+import { ScreenProps } from './Screen.types.js';
+
+declare function Screen({ children, padded, testID }: ScreenProps): react.JSX.Element;
+
+export { Screen };

package/dist/layout/Screen.js

@@ -0,0 +1,7 @@
+import { jsx } from "react/jsx-runtime";
+function Screen({ children, padded = true, testID }) {
+  return /* @__PURE__ */ jsx("main", { "data-testid": testID, style: { padding: padded ? 16 : 0, minHeight: "100%" }, children });
+}
+export {
+  Screen
+};

package/dist/layout/Screen.types.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+
+interface ScreenProps {
+    children: ReactNode;
+    scroll?: boolean;
+    padded?: boolean;
+    testID?: string;
+}
+
+export type { ScreenProps };

package/dist/layout/Spacer.d.ts

@@ -0,0 +1,6 @@
+import * as react from 'react';
+import { SpacerProps } from './Stack.types.js';
+
+declare function Spacer({ size }: SpacerProps): react.JSX.Element;
+
+export { Spacer };

package/dist/layout/Spacer.js

@@ -0,0 +1,12 @@
+import { jsx } from "react/jsx-runtime";
+function Spacer({ size }) {
+  const style = {
+    flex: size === void 0 ? 1 : void 0,
+    height: size,
+    width: size
+  };
+  return /* @__PURE__ */ jsx("div", { style });
+}
+export {
+  Spacer
+};

package/dist/layout/Stack.d.ts

@@ -0,0 +1,6 @@
+import * as react from 'react';
+import { FlexProps } from './Stack.types.js';
+
+declare function Stack({ children, gap, align, justify, testID }: FlexProps): react.JSX.Element;
+
+export { Stack };

package/dist/layout/Stack.js

@@ -0,0 +1,28 @@
+import { jsx } from "react/jsx-runtime";
+const ALIGN = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  stretch: "stretch"
+};
+const JUSTIFY = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  between: "space-between",
+  around: "space-around",
+  evenly: "space-evenly"
+};
+function Stack({ children, gap, align, justify, testID }) {
+  const style = {
+    display: "flex",
+    flexDirection: "column",
+    gap,
+    alignItems: align ? ALIGN[align] : void 0,
+    justifyContent: justify ? JUSTIFY[justify] : void 0
+  };
+  return /* @__PURE__ */ jsx("div", { "data-testid": testID, style, children });
+}
+export {
+  Stack
+};

package/dist/layout/Stack.types.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+
+type FlexAlign = 'start' | 'center' | 'end' | 'stretch';
+type FlexJustify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+interface FlexProps {
+    children: ReactNode;
+    gap?: number;
+    align?: FlexAlign;
+    justify?: FlexJustify;
+    testID?: string;
+}
+interface RowProps extends FlexProps {
+    wrap?: boolean;
+}
+interface SpacerProps {
+    size?: number;
+}
+
+export type { FlexAlign, FlexJustify, FlexProps, RowProps, SpacerProps };

package/dist/layout/index.d.ts

@@ -0,0 +1,7 @@
+export { Screen } from './Screen.js';
+export { ScreenProps } from './Screen.types.js';
+export { Stack } from './Stack.js';
+export { Row } from './Row.js';
+export { Spacer } from './Spacer.js';
+export { FlexAlign, FlexJustify, FlexProps, RowProps, SpacerProps } from './Stack.types.js';
+import 'react';

package/dist/layout/index.js

@@ -0,0 +1,6 @@
+export * from "./Screen";
+export * from "./Screen.types";
+export * from "./Stack";
+export * from "./Row";
+export * from "./Spacer";
+export * from "./Stack.types";

package/dist/navigation/book.d.ts

@@ -0,0 +1,16 @@
+import { PrintFormat, Entry, BookDef, PageDef, LinkDef, RouteMap, PageOptions } from './types.js';
+
+declare function page<P = void>(component: unknown, options?: PageOptions): PageDef<P>;
+declare function link<RM extends RouteMap>(book: BookDef<PrintFormat, RM>, options?: PageOptions): LinkDef<RM>;
+type RoutesOf<Pages extends Record<string, Entry>> = {
+    [K in keyof Pages as Pages[K] extends PageDef<any> ? K : never]: Pages[K] extends PageDef<infer P> ? P : never;
+} & UnionToIntersection<{
+    [K in keyof Pages]: Pages[K] extends LinkDef<infer RM> ? RM : {};
+}[keyof Pages]>;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+declare function book<F extends PrintFormat, Pages extends Record<string, Entry>>(def: {
+    format: F;
+    pages: Pages;
+}): BookDef<F, RoutesOf<Pages> & RouteMap>;
+
+export { book, link, page };

package/dist/navigation/book.js

@@ -0,0 +1,14 @@
+function page(component, options = {}) {
+  return { kind: "page", component, options };
+}
+function link(book2, options = {}) {
+  return { kind: "link", book: book2, options };
+}
+function book(def) {
+  return { kind: "book", format: def.format, pages: def.pages };
+}
+export {
+  book,
+  link,
+  page
+};

package/dist/navigation/bridge.native.d.ts

@@ -0,0 +1,5 @@
+import { Nav } from './nav.types.js';
+
+declare function useNativeNav(): Nav;
+
+export { useNativeNav };

package/dist/navigation/bridge.native.js

@@ -0,0 +1,14 @@
+import { useNavigation, useRoute } from "@react-navigation/native";
+function useNativeNav() {
+  const navigation = useNavigation();
+  const route = useRoute();
+  return {
+    turnTo: (name, params) => navigation.navigate(name, params),
+    turnBack: () => navigation.goBack(),
+    current: () => route.name,
+    params: () => route.params ?? {}
+  };
+}
+export {
+  useNativeNav
+};

package/dist/navigation/bridge.web.d.ts

@@ -0,0 +1,5 @@
+import { Nav } from './nav.types.js';
+
+declare function useWebNav(pathOf: (name: string, params?: unknown) => string, nameOf: (path: string) => string): Nav;
+
+export { useWebNav };

package/dist/navigation/bridge.web.js

@@ -0,0 +1,15 @@
+import { useNavigate, useLocation, useParams } from "react-router-dom";
+function useWebNav(pathOf, nameOf) {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const params = useParams();
+  return {
+    turnTo: (name, p) => navigate(pathOf(name, p)),
+    turnBack: () => navigate(-1),
+    current: () => nameOf(location.pathname),
+    params: () => params
+  };
+}
+export {
+  useWebNav
+};

package/dist/navigation/index.d.ts

@@ -0,0 +1,5 @@
+export { book, link, page } from './book.js';
+export { NavContext, NavProvider, useNav } from './use-nav.js';
+export { BookDef, Entry, LinkDef, MobileFormat, PageDef, PageOptions, PrintFormat, RouteMap, WebFormat } from './types.js';
+export { Nav, TypedNav } from './nav.types.js';
+import 'react';

package/dist/navigation/index.js

@@ -0,0 +1,4 @@
+export * from "./book";
+export * from "./use-nav";
+export * from "./types";
+export * from "./nav.types";

package/dist/navigation/nav.types.d.ts

@@ -0,0 +1,15 @@
+interface Nav {
+    turnTo(name: string, params?: unknown): void;
+    turnBack(): void;
+    current(): string;
+    params<T = unknown>(): T;
+}
+type NoParams<P> = [P] extends [void] ? true : P extends undefined ? true : false;
+interface TypedNav<RM extends object> {
+    turnTo<K extends keyof RM & string>(...args: NoParams<RM[K]> extends true ? [name: K] : [name: K, params: RM[K]]): void;
+    turnBack(): void;
+    current(): keyof RM & string;
+    params<K extends keyof RM & string>(): RM[K];
+}
+
+export type { Nav, TypedNav };

package/dist/navigation/types.d.ts

@@ -0,0 +1,30 @@
+type MobileFormat = 'drawer' | 'stack' | 'bottomNav';
+type WebFormat = 'sidebar' | 'stack' | 'tabs';
+type PrintFormat = MobileFormat | WebFormat;
+interface PageOptions {
+    title?: string;
+    icon?: string;
+    path?: string;
+    initial?: boolean;
+}
+interface PageDef<P = void> {
+    readonly kind: 'page';
+    readonly component: unknown;
+    readonly options: PageOptions;
+    readonly __params?: P;
+}
+interface LinkDef<RM extends RouteMap = RouteMap> {
+    readonly kind: 'link';
+    readonly book: BookDef<PrintFormat, RM>;
+    readonly options: PageOptions;
+}
+type Entry = PageDef<any> | LinkDef<any>;
+type RouteMap = Record<string, unknown>;
+interface BookDef<F extends PrintFormat, RM extends RouteMap> {
+    readonly kind: 'book';
+    readonly format: F;
+    readonly pages: Record<string, Entry>;
+    readonly __routes?: RM;
+}
+
+export type { BookDef, Entry, LinkDef, MobileFormat, PageDef, PageOptions, PrintFormat, RouteMap, WebFormat };

package/dist/navigation/use-nav.d.ts

@@ -0,0 +1,13 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Nav, TypedNav } from './nav.types.js';
+import { RouteMap } from './types.js';
+
+declare const NavContext: react.Context<Nav | null>;
+declare function NavProvider(props: {
+    value: Nav;
+    children: ReactNode;
+}): react.FunctionComponentElement<react.ProviderProps<Nav | null>>;
+declare function useNav<RM extends object = RouteMap>(): TypedNav<RM>;
+
+export { NavContext, NavProvider, useNav };

package/dist/navigation/use-nav.js

@@ -0,0 +1,15 @@
+import { createContext, createElement, useContext } from "react";
+const NavContext = createContext(null);
+function NavProvider(props) {
+  return createElement(NavContext.Provider, { value: props.value }, props.children);
+}
+function useNav() {
+  const nav = useContext(NavContext);
+  if (nav === null) throw new Error("useNav() must be used within <Navigation> (NavProvider missing)");
+  return nav;
+}
+export {
+  NavContext,
+  NavProvider,
+  useNav
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@sublime-ui/ui",
+  "version": "0.1.0",
+  "description": "Cross-platform navigation (storybook → React Navigation / react-router) and layout primitives for Sublime UI.",
+  "keywords": ["sublime-ui", "navigation", "react-navigation", "react-router", "layout", "storybook", "cross-platform", "typescript"],
+  "homepage": "https://sublime-ui.github.io/sublime-ui/",
+  "bugs": "https://github.com/sublime-ui/sublime-ui/issues",
+  "repository": { "type": "git", "url": "git+https://github.com/sublime-ui/sublime-ui.git", "directory": "ui" },
+  "license": "MIT",
+  "author": "Aaron Mkandawire",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./navigation": { "types": "./dist/navigation/index.d.ts", "import": "./dist/navigation/index.js" },
+    "./navigation/bridge.native": { "types": "./dist/navigation/bridge.native.d.ts", "import": "./dist/navigation/bridge.native.js" },
+    "./navigation/bridge.web": { "types": "./dist/navigation/bridge.web.d.ts", "import": "./dist/navigation/bridge.web.js" }
+  },
+  "react-native": "./src/index.ts",
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.74",
+    "@react-navigation/native": ">=6",
+    "@react-navigation/native-stack": ">=6",
+    "@react-navigation/bottom-tabs": ">=6",
+    "@react-navigation/drawer": ">=6",
+    "react-native-safe-area-context": ">=4",
+    "react-router-dom": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "react-native": { "optional": true },
+    "@react-navigation/native": { "optional": true },
+    "@react-navigation/native-stack": { "optional": true },
+    "@react-navigation/bottom-tabs": { "optional": true },
+    "@react-navigation/drawer": { "optional": true },
+    "react-native-safe-area-context": { "optional": true },
+    "react-router-dom": { "optional": true }
+  },
+  "devDependencies": {
+    "@react-navigation/native": "^6.1.18",
+    "@react-navigation/native-stack": "^6.11.0",
+    "@react-navigation/bottom-tabs": "^6.6.1",
+    "@react-navigation/drawer": "^6.7.2",
+    "@testing-library/react": "^16.0.1",
+    "@types/node": "^22",
+    "@types/react": "^18.3.12",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-native": "^0.76.1",
+    "react-native-safe-area-context": "^4.14.0",
+    "react-router-dom": "^6.27.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './layout';

package/src/layout/Row.native.tsx

@@ -0,0 +1,34 @@
+import { View } from 'react-native';
+import type { ViewStyle } from 'react-native';
+import type { FlexAlign, FlexJustify, RowProps } from './Stack.types';
+
+const ALIGN: Record<FlexAlign, ViewStyle['alignItems']> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  stretch: 'stretch',
+};
+
+const JUSTIFY: Record<FlexJustify, ViewStyle['justifyContent']> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  between: 'space-between',
+  around: 'space-around',
+  evenly: 'space-evenly',
+};
+
+export function Row({ children, gap, align, justify, wrap, testID }: RowProps) {
+  const style: ViewStyle = {
+    flexDirection: 'row',
+    flexWrap: wrap ? 'wrap' : undefined,
+    gap,
+    alignItems: align ? ALIGN[align] : undefined,
+    justifyContent: justify ? JUSTIFY[justify] : undefined,
+  };
+  return (
+    <View testID={testID} style={style}>
+      {children}
+    </View>
+  );
+}

package/src/layout/Row.tsx

@@ -0,0 +1,34 @@
+import type { CSSProperties } from 'react';
+import type { FlexAlign, FlexJustify, RowProps } from './Stack.types';
+
+const ALIGN: Record<FlexAlign, CSSProperties['alignItems']> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  stretch: 'stretch',
+};
+
+const JUSTIFY: Record<FlexJustify, CSSProperties['justifyContent']> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  between: 'space-between',
+  around: 'space-around',
+  evenly: 'space-evenly',
+};
+
+export function Row({ children, gap, align, justify, wrap, testID }: RowProps) {
+  const style: CSSProperties = {
+    display: 'flex',
+    flexDirection: 'row',
+    flexWrap: wrap ? 'wrap' : undefined,
+    gap,
+    alignItems: align ? ALIGN[align] : undefined,
+    justifyContent: justify ? JUSTIFY[justify] : undefined,
+  };
+  return (
+    <div data-testid={testID} style={style}>
+      {children}
+    </div>
+  );
+}

package/src/layout/Screen.native.tsx

@@ -0,0 +1,12 @@
+import { SafeAreaView } from 'react-native-safe-area-context';
+import { ScrollView, View } from 'react-native';
+import type { ScreenProps } from './Screen.types';
+
+export function Screen({ children, scroll, padded = true, testID }: ScreenProps) {
+  const inner = <View style={{ padding: padded ? 16 : 0, flex: 1 }}>{children}</View>;
+  return (
+    <SafeAreaView style={{ flex: 1 }} testID={testID}>
+      {scroll ? <ScrollView>{inner}</ScrollView> : inner}
+    </SafeAreaView>
+  );
+}

package/src/layout/Screen.tsx

@@ -0,0 +1,9 @@
+import type { ScreenProps } from './Screen.types';
+
+export function Screen({ children, padded = true, testID }: ScreenProps) {
+  return (
+    <main data-testid={testID} style={{ padding: padded ? 16 : 0, minHeight: '100%' }}>
+      {children}
+    </main>
+  );
+}

package/src/layout/Screen.types.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+
+export interface ScreenProps {
+  children: ReactNode;
+  scroll?: boolean;
+  padded?: boolean;
+  testID?: string;
+}

package/src/layout/Spacer.native.tsx

@@ -0,0 +1,12 @@
+import { View } from 'react-native';
+import type { ViewStyle } from 'react-native';
+import type { SpacerProps } from './Stack.types';
+
+export function Spacer({ size }: SpacerProps) {
+  const style: ViewStyle = {
+    flex: size === undefined ? 1 : undefined,
+    height: size,
+    width: size,
+  };
+  return <View style={style} />;
+}

package/src/layout/Spacer.tsx

@@ -0,0 +1,11 @@
+import type { CSSProperties } from 'react';
+import type { SpacerProps } from './Stack.types';
+
+export function Spacer({ size }: SpacerProps) {
+  const style: CSSProperties = {
+    flex: size === undefined ? 1 : undefined,
+    height: size,
+    width: size,
+  };
+  return <div style={style} />;
+}

package/src/layout/Stack.native.tsx

@@ -0,0 +1,33 @@
+import { View } from 'react-native';
+import type { ViewStyle } from 'react-native';
+import type { FlexAlign, FlexJustify, FlexProps } from './Stack.types';
+
+const ALIGN: Record<FlexAlign, ViewStyle['alignItems']> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  stretch: 'stretch',
+};
+
+const JUSTIFY: Record<FlexJustify, ViewStyle['justifyContent']> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  between: 'space-between',
+  around: 'space-around',
+  evenly: 'space-evenly',
+};
+
+export function Stack({ children, gap, align, justify, testID }: FlexProps) {
+  const style: ViewStyle = {
+    flexDirection: 'column',
+    gap,
+    alignItems: align ? ALIGN[align] : undefined,
+    justifyContent: justify ? JUSTIFY[justify] : undefined,
+  };
+  return (
+    <View testID={testID} style={style}>
+      {children}
+    </View>
+  );
+}

package/src/layout/Stack.tsx

@@ -0,0 +1,33 @@
+import type { CSSProperties } from 'react';
+import type { FlexAlign, FlexJustify, FlexProps } from './Stack.types';
+
+const ALIGN: Record<FlexAlign, CSSProperties['alignItems']> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  stretch: 'stretch',
+};
+
+const JUSTIFY: Record<FlexJustify, CSSProperties['justifyContent']> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  between: 'space-between',
+  around: 'space-around',
+  evenly: 'space-evenly',
+};
+
+export function Stack({ children, gap, align, justify, testID }: FlexProps) {
+  const style: CSSProperties = {
+    display: 'flex',
+    flexDirection: 'column',
+    gap,
+    alignItems: align ? ALIGN[align] : undefined,
+    justifyContent: justify ? JUSTIFY[justify] : undefined,
+  };
+  return (
+    <div data-testid={testID} style={style}>
+      {children}
+    </div>
+  );
+}

package/src/layout/Stack.types.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react';
+
+export type FlexAlign = 'start' | 'center' | 'end' | 'stretch';
+export type FlexJustify =
+  | 'start'
+  | 'center'
+  | 'end'
+  | 'between'
+  | 'around'
+  | 'evenly';
+
+export interface FlexProps {
+  children: ReactNode;
+  gap?: number;
+  align?: FlexAlign;
+  justify?: FlexJustify;
+  testID?: string;
+}
+
+export interface RowProps extends FlexProps {
+  wrap?: boolean;
+}
+
+export interface SpacerProps {
+  size?: number;
+}

package/src/layout/index.ts

@@ -0,0 +1,6 @@
+export * from './Screen';
+export * from './Screen.types';
+export * from './Stack';
+export * from './Row';
+export * from './Spacer';
+export * from './Stack.types';

package/src/navigation/book.ts

@@ -0,0 +1,35 @@
+import type {
+  BookDef, Entry, LinkDef, PageDef, PageOptions, PrintFormat, RouteMap,
+} from './types';
+
+export function page<P = void>(component: unknown, options: PageOptions = {}): PageDef<P> {
+  return { kind: 'page', component, options };
+}
+
+export function link<RM extends RouteMap>(
+  book: BookDef<PrintFormat, RM>,
+  options: PageOptions = {},
+): LinkDef<RM> {
+  return { kind: 'link', book, options };
+}
+
+// Flatten Pages (page params + nested link routes) into one RouteMap at type level.
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-empty-object-type --
+   type-level matchers: `any` is the structural wildcard for the conditional checks and
+   `{}` is the identity element when a Page is not a LinkDef (intersected away). */
+type RoutesOf<Pages extends Record<string, Entry>> =
+  { [K in keyof Pages as Pages[K] extends PageDef<any> ? K : never]:
+      Pages[K] extends PageDef<infer P> ? P : never }
+  & UnionToIntersection<
+      { [K in keyof Pages]: Pages[K] extends LinkDef<infer RM> ? RM : {} }[keyof Pages]
+    >;
+
+type UnionToIntersection<U> =
+  (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-empty-object-type */
+
+export function book<F extends PrintFormat, Pages extends Record<string, Entry>>(
+  def: { format: F; pages: Pages },
+): BookDef<F, RoutesOf<Pages> & RouteMap> {
+  return { kind: 'book', format: def.format, pages: def.pages };
+}

package/src/navigation/bridge.native.ts

@@ -0,0 +1,16 @@
+import { useNavigation, useRoute } from '@react-navigation/native';
+import type { Nav } from './nav.types';
+
+export function useNativeNav(): Nav {
+  // react-navigation's hook is generic over the app's param list, which is only
+  // known at the call site; `any` defers that binding to the typed `Nav` facade.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const navigation = useNavigation<any>();
+  const route = useRoute();
+  return {
+    turnTo: (name, params) => navigation.navigate(name as never, params as never),
+    turnBack: () => navigation.goBack(),
+    current: () => route.name,
+    params: <T,>() => (route.params ?? {}) as T,
+  };
+}

package/src/navigation/bridge.web.ts

@@ -0,0 +1,17 @@
+import { useNavigate, useLocation, useParams } from 'react-router-dom';
+import type { Nav } from './nav.types';
+
+export function useWebNav(
+  pathOf: (name: string, params?: unknown) => string,
+  nameOf: (path: string) => string,
+): Nav {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const params = useParams();
+  return {
+    turnTo: (name, p) => navigate(pathOf(name, p)),
+    turnBack: () => navigate(-1),
+    current: () => nameOf(location.pathname),
+    params: <T,>() => params as unknown as T,
+  };
+}

package/src/navigation/index.ts

@@ -0,0 +1,4 @@
+export * from './book';
+export * from './use-nav';
+export * from './types';
+export * from './nav.types';

package/src/navigation/nav.types.ts

@@ -0,0 +1,21 @@
+export interface Nav {
+  turnTo(name: string, params?: unknown): void;
+  turnBack(): void;
+  current(): string;
+  params<T = unknown>(): T;
+}
+
+type NoParams<P> = [P] extends [void] ? true : P extends undefined ? true : false;
+
+// `RM extends object` (not `Record<string, unknown>`) so a generated `interface
+// AppRoutes { ... }` satisfies it. TypeScript interfaces lack an implicit index
+// signature and so do NOT extend `Record<string, unknown>`, but the route map is
+// always a concrete object type here, and `keyof`/indexing work on either.
+export interface TypedNav<RM extends object> {
+  turnTo<K extends keyof RM & string>(
+    ...args: NoParams<RM[K]> extends true ? [name: K] : [name: K, params: RM[K]]
+  ): void;
+  turnBack(): void;
+  current(): keyof RM & string;
+  params<K extends keyof RM & string>(): RM[K];
+}

package/src/navigation/types.ts

@@ -0,0 +1,37 @@
+export type MobileFormat = 'drawer' | 'stack' | 'bottomNav';
+export type WebFormat = 'sidebar' | 'stack' | 'tabs';
+export type PrintFormat = MobileFormat | WebFormat;
+
+export interface PageOptions {
+  title?: string;
+  icon?: string;
+  path?: string;       // web URL segment; defaults to kebab-cased key
+  initial?: boolean;
+}
+
+export interface PageDef<P = void> {
+  readonly kind: 'page';
+  readonly component: unknown;        // a React component; typed structurally at author site
+  readonly options: PageOptions;
+  readonly __params?: P;              // phantom: carries the page's param type
+}
+
+export interface LinkDef<RM extends RouteMap = RouteMap> {
+  readonly kind: 'link';
+  readonly book: BookDef<PrintFormat, RM>;
+  readonly options: PageOptions;
+}
+
+// `any` here is the structural wildcard: Entry must accept a PageDef/LinkDef of
+// any param or route-map shape before the flattening pass narrows them.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Entry = PageDef<any> | LinkDef<any>;
+
+export type RouteMap = Record<string, unknown>;
+
+export interface BookDef<F extends PrintFormat, RM extends RouteMap> {
+  readonly kind: 'book';
+  readonly format: F;
+  readonly pages: Record<string, Entry>;
+  readonly __routes?: RM;             // phantom: flattened route map
+}

package/src/navigation/use-nav.ts

@@ -0,0 +1,15 @@
+import { createContext, createElement, useContext, type ReactNode } from 'react';
+import type { Nav, TypedNav } from './nav.types';
+import type { RouteMap } from './types';
+
+export const NavContext = createContext<Nav | null>(null);
+
+export function NavProvider(props: { value: Nav; children: ReactNode }) {
+  return createElement(NavContext.Provider, { value: props.value }, props.children);
+}
+
+export function useNav<RM extends object = RouteMap>(): TypedNav<RM> {
+  const nav = useContext(NavContext);
+  if (nav === null) throw new Error('useNav() must be used within <Navigation> (NavProvider missing)');
+  return nav as unknown as TypedNav<RM>;
+}