@tujyane/alf 1.0.0

package/README.md

@@ -0,0 +1,226 @@
+### Tujyane Application Layout Framework (ALF)
+
+Modern, typed primitives for building consistent application layouts across web and React Native targets.
+
+## Overview
+
+ALF provides:
+
+- **Theme provider**: Context-driven theming with `Provider`, `useTheme`, and predefined `themes` and `palette`.
+- **Atoms**: Minimal, composable building blocks exposed via `src/atoms`.
+- **Tokens**: Design tokens exported as `tokens` for consistent spacing, typography, and colors.
+- **Utilities**: Helper utilities like `alpha`, `leading`, `flatten`, and `select` for style composition.
+- **Platform helpers**: `platform.select` wrapper and guards (`web`, `ios`, `android`, `native`) to keep code portable.
+
+The package re-exports from `src/index.tsx` so consumers can import from a single entrypoint.
+
+## Installation
+
+```bash
+pnpm add @tujyane/alf
+# or
+npm install @tujyane/alf
+# or
+yarn add @tujyane/alf
+```
+
+Peer dependencies expected:
+
+- `react`
+- `react-native` (for shared types like `ViewStyle`, even on web)
+
+## Quick Start
+
+```tsx
+import { Provider, themes } from "@tujyane/alf";
+
+export function App() {
+  return (
+    <Provider
+      activeTheme="light"
+      themes={{ light: themes.light, dark: themes.dark }}
+    >
+      {/* app routes/components */}
+    </Provider>
+  );
+}
+```
+
+Access the theme anywhere:
+
+```tsx
+import { useTheme } from "@tujyane/alf";
+
+export const Header = () => {
+  const theme = useTheme();
+  return (
+    <header style={{ backgroundColor: theme.background, color: theme.text }}>
+      My App
+    </header>
+  );
+};
+```
+
+## Exports
+
+From `src/index.tsx`:
+
+- `Provider`: React provider to set the active theme.
+- `useTheme`: Hook to read the current theme (returns `Theme` with `scheme`, `palette`, `semantic`, `atoms`).
+- `Context`: Internal context (typed) for advanced usage.
+- `themes`: Theme presets (`light`, `dark`).
+- `palette`: Color palette helpers.
+- `platform`: Platform helpers and selectors.
+- `tokens`: Design tokens namespace (spacing, typography, borders).
+- `utils`: Utility helpers namespace (alpha, leading, flatten, select).
+- `TextStyleProp`, `ViewStyleProp`: Convenience prop types for components.
+- `atoms`: All atoms from `src/atoms` are re-exported.
+
+## Theming
+
+```tsx
+import { Provider, themes } from "@tujyane/alf";
+
+type ThemeKey = "light" | "dark";
+
+const appThemes = { light: themes.light, dark: themes.dark } as const;
+
+export const Root = ({ children }: React.PropsWithChildren) => (
+  <Provider<ThemeKey, typeof appThemes> activeTheme="light" themes={appThemes}>
+    {children}
+  </Provider>
+);
+```
+
+`useTheme()` returns the active `Theme` object so you can style components consistently.
+
+## Design System
+
+### Color Scales
+
+The framework provides semantic color scales mapped from the palette:
+
+- **Primary** (neutral): `primary_25` through `primary_900` - used for text, backgrounds, and borders
+- **Success**: `positive_100` through `positive_900` - green/success states
+- **Error**: `negative_100` through `negative_900` - red/error states
+- **Warning**: `warning_100` through `warning_900` - yellow/warning states
+- **Info**: `info_100` through `info_900` - blue/information states
+- **Secondary**: `secondary_100` through `secondary_900` - accent colors
+
+### Theme Atoms
+
+Access pre-composed atoms via `theme.atoms`:
+
+**Base (using primary neutral scale):**
+
+- Text: `text`, `text_low`, `text_medium`, `text_high`, `text_inverted`
+- Backgrounds: `bg`, `bg_25`, `bg_50`
+- Borders: `border_low`, `border_medium`, `border_high`
+
+**Semantic (using color scales):**
+
+- Text: `text_primary`, `text_success`, `text_error`, `text_warning`, `text_info`, `text_secondary`
+- Backgrounds: `bg_primary`, `bg_success`, `bg_error`, `bg_warning`, `bg_info`, `bg_secondary`
+- Borders: `border_primary`, `border_success`, `border_error`, `border_warning`, `border_info`, `border_secondary`
+
+```tsx
+import { useTheme } from "@tujyane/alf";
+
+const Button = () => {
+  const theme = useTheme();
+  return (
+    <button style={{ ...theme.atoms.bg_primary, ...theme.atoms.text_inverted }}>
+      Click me
+    </button>
+  );
+};
+```
+
+### Accessing Semantic Colors
+
+```tsx
+const theme = useTheme();
+
+// Access semantic color scales directly
+const primaryColor = theme.semantic.primary[500];
+const errorText = theme.semantic.error[900];
+```
+
+## Platform Helpers
+
+The framework exposes safe platform helpers in `src/platform/index.ts`:
+
+- `web(value)`, `ios(value)`, `android(value)`, `native(value)`: Return `value` on the matching platform, `undefined` otherwise.
+- `platform(selectors)`: Equivalent to `Platform.select` returning the `web` option on web builds.
+
+Usage:
+
+```ts
+import { web, android, platform } from "@tujyane/alf";
+
+const maybeWebOnly = web({ behavior: "sticky" });
+
+const style = platform({
+  web: { cursor: "pointer" },
+  android: { elevation: 2 },
+  default: {},
+});
+```
+
+## Utilities
+
+Available under the `utils` namespace:
+
+- `alpha(color, amount)`: Apply alpha to a color.
+- `leading(value)`: Compute leading (line-height) helpers.
+- `flatten(...)`: Flatten style arrays into a single object.
+- `select(map, key)`: Safe selection helper.
+
+Import examples:
+
+```ts
+import { utils } from "@tujyane/alf";
+
+const translucent = utils.alpha("#000", 0.2);
+```
+
+## Atoms and Types
+
+- All atoms are re-exported from `src/atoms` via `src/atoms/index.ts`.
+- Reusable types like `ShadowStyle` are defined in `src/atoms/types.ts`.
+
+```ts
+import { ShadowStyle } from "@tujyane/alf";
+```
+
+## Contributing
+
+1. Clone the repo
+2. Install dependencies
+
+```bash
+pnpm i
+```
+
+3. Build
+
+```bash
+pnpm build
+```
+
+4. Develop against a local app or storybook of your choice.
+
+## FAQ
+
+- Why React Native types on web?
+  - We use `react-native` types like `ViewStyle` for cross-platform consistency. On web, they compile to plain objects.
+
+- How do I add new themes?
+  - Export them from `src/themes.ts` and pass via `Provider` as the `themes` prop.
+
+- Can I tree-shake utilities?
+  - Yes, everything is module-scoped and re-exported. Use ESM imports for best results.
+
+## License
+
+MIT