@nlabs/gothamui 1.8.0

package/lib/docs/analytics.md

@@ -0,0 +1,231 @@
+# AWS RUM Analytics
+
+GothamUI emits analytics through its browser analytics channel by default. When an application is wrapped by both Gotham and Metropolis, Metropolis automatically receives these events and delivers them to Reaktor. Gotham does not load an analytics SDK or send network requests by itself.
+
+For local demos or troubleshooting, use the debug adapter to inspect the exact event passed to the analytics client:
+
+```tsx
+import {createAwsRumDebugClient} from '@nlabs/gothamui';
+
+const awsRum = createAwsRumDebugClient({
+  enabled: import.meta.env.DEV,
+  target: metropolisAwsRum
+});
+```
+
+When enabled, the adapter logs `[GothamUI] awsRum.track` and the event object. If a `target` is supplied, the same object is then forwarded for Metropolis delivery. Omitting `target` is useful for a console-only component demo.
+
+## Plug-and-play configuration
+
+```tsx
+import {Gotham} from '@nlabs/gothamui';
+import {Metropolis} from '@nlabs/metropolisjs';
+
+root.render(
+  <Metropolis config={metropolisConfig}>
+    <Gotham config={{routes}} />
+  </Metropolis>
+);
+```
+
+Set an application name and the shared Reaktor endpoint in Metropolis. The application name becomes the default analytics `appId`; `app.rum.appId` can override it:
+
+```ts
+const metropolisConfig = {
+  production: {
+    app: {
+      api: {
+        rum: 'https://analytics.example.com/public'
+      },
+      name: 'my-app',
+      rum: {
+        respectPrivacySignals: true
+      }
+    }
+  }
+};
+```
+
+If `app.api.rum` is omitted, Metropolis uses its configured public endpoint. Every application uses the same endpoint and supplies its own `appId`. This allows a future dashboard to filter the shared log collection by application.
+
+## Page views
+
+Gotham automatically calls `awsRum.track()` once when the route changes. Add stable analytics metadata so dynamic identifiers and titles never become dimensions:
+
+```tsx
+const routes = [{
+  analytics: {route: '/stories/:storyId', title: 'Story', viewId: 'story.detail'},
+  element: <StoryView />,
+  path: 'stories/:storyId'
+}];
+```
+
+## View performance
+
+Use one terminal measurement instead of separate start/end beacons. A measurement starts when a view begins loading and finishes with exactly one outcome: `success`, `failure`, `timeout`, or `cancelled`. Gotham emits the resulting `view_performance` event; Metropolis handles delivery.
+
+### React views
+
+Call `useViewPerformance()` inside the view being measured. Keep its status `pending` while required content is loading, then change it to `success` or `failure` when the view reaches a terminal state.
+
+```tsx
+import {useViewPerformance} from '@nlabs/gothamui';
+
+interface StoryViewProps {
+  readonly error?: Error;
+  readonly loading: boolean;
+}
+
+export const StoryView = ({error, loading}: StoryViewProps) => {
+  useViewPerformance({
+    route: '/stories/:storyId',
+    status: error ? 'failure' : loading ? 'pending' : 'success',
+    title: 'Story',
+    viewId: 'story.detail'
+  });
+
+  if(error) {
+    return <p>Unable to load this story.</p>;
+  }
+
+  if(loading) {
+    return <p>Loading story…</p>;
+  }
+
+  return <article>Story content</article>;
+};
+```
+
+Options:
+
+- `viewId` is required. Use a stable product identifier such as `story.detail`, never a database ID or URL.
+- `status` is required and must be `pending`, `success`, or `failure`.
+- `route` should be a stable route template such as `/stories/:storyId`, not the current dynamic pathname.
+- `title` is an optional stable display name for the view.
+- `timeoutMs` defaults to 30 seconds. Set it to `0` or a negative value to disable the automatic timeout.
+
+The hook starts a new measurement when `awsRum`, `route`, `timeoutMs`, `title`, or `viewId` changes. It reports `cancelled` if the view unmounts or one of those values changes before completion. Once a measurement finishes, later status changes cannot emit a second event.
+
+### Non-React lifecycles
+
+`startView()` only measures time; it does not send analytics by itself. Supply an `onComplete` callback and pass the completed measurement to `reportViewPerformance()`:
+
+```ts
+import {
+  createAwsRumBrowserClient,
+  reportViewPerformance,
+  startView
+} from '@nlabs/gothamui';
+
+const awsRum = createAwsRumBrowserClient();
+
+export const loadStory = async () => {
+  const view = startView({
+    onComplete: (measurement) => reportViewPerformance(awsRum, measurement),
+    route: '/stories/:storyId',
+    timeoutMs: 10_000,
+    title: 'Story',
+    viewId: 'story.detail'
+  });
+
+  try {
+    const story = await loadStoryData();
+    view.succeed();
+    return story;
+  } catch(error) {
+    view.fail();
+    throw error;
+  }
+};
+```
+
+The returned handle provides four terminal methods:
+
+- `succeed()` records `success`.
+- `fail()` records `failure`.
+- `timeout()` records `timeout` immediately; the configured timer does this automatically when it expires.
+- `cancel()` records `cancelled`, typically when navigation abandons unfinished work.
+
+Only the first terminal method has an effect. Later calls are ignored and the timeout is cleared.
+
+### Event payload
+
+Gotham sends the completed measurement in this shape:
+
+```ts
+{
+  name: 'view_performance',
+  path: '/stories/:storyId',
+  properties: {
+    durationMs: 842,
+    outcome: 'success',
+    viewId: 'story.detail',
+    viewTitle: 'Story'
+  },
+  type: 'view_performance'
+}
+```
+
+`path` and `viewTitle` are omitted when `route` and `title` are not supplied. `durationMs` is rounded to a non-negative whole number. Keep all identifiers stable and free of names, account IDs, query strings, or other identifying information.
+
+## Automatic interaction tracking
+
+Gotham automatically tracks semantic interactive elements rendered anywhere in the document while `GothamProvider` is mounted. This includes links, buttons, form controls, sliders, switches, tabs, menu items, editable regions, and keyboard-only form submissions. Delegated listeners also cover elements rendered later or in portals.
+
+Interaction events contain only the control type, interaction type, and current pathname. Gotham never reads visible text, URLs, query strings, or control values. Give important interactions a stable event name with `data-analytics-name`:
+
+```tsx
+<button data-analytics-name="checkout_started">Checkout</button>
+<input data-analytics-name="volume_changed" type="range" />
+```
+
+Use `data-analytics-track="false"` on a control or container for a private region that must not emit interaction events:
+
+```tsx
+<section data-analytics-track="false">...</section>
+```
+
+Automatic interaction tracking is enabled by default. It can be disabled application-wide when an application provides its own delegated tracker:
+
+```tsx
+<Gotham config={{analytics: {interactions: false}}} />
+```
+
+## Custom events
+
+Use `useAwsRum()` for domain events that need additional stable properties:
+
+```tsx
+import {useAwsRum} from '@nlabs/gothamui';
+
+export const SignupButton = () => {
+  const awsRum = useAwsRum();
+
+  const onClick = () => {
+    awsRum?.track({
+      name: 'signup_started',
+      path: window.location.pathname,
+      properties: {placement: 'header'},
+      type: 'click'
+    });
+  };
+
+  return <button onClick={onClick}>Sign up</button>;
+};
+```
+
+Properties must be strings, numbers, or booleans. Do not include names, email addresses, form values, account IDs, query strings, or other identifying information.
+
+## Delivery behavior
+
+Metropolis:
+
+- Generates a memory-only journey ID that resets with the application runtime.
+- Adds an event ID, timestamp, and sequence number.
+- Suppresses identical events during the deduplication window.
+- Debounces events into batches.
+- Throttles requests to the shared endpoint.
+- Sends JSON through Rip-Hunter.
+- Dispatches `AWS_RUM_TRACK_QUEUED`, `AWS_RUM_TRACK_SUCCESS`, and `AWS_RUM_TRACK_ERROR` Flux events.
+
+The shared Reaktor mutation stores standalone `logs` documents. Each document contains `appId`; no graph edge is required.

package/lib/docs/api-reference.md

@@ -0,0 +1,364 @@
+# GothamUI API Reference
+
+This document provides detailed information about the components and APIs available in GothamUI.
+
+## Core Components
+
+### `<Gotham>`
+
+The main component that bootstraps your GothamUI application.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `GothamConfiguration` | `{}` | Configuration object for the application |
+| `children` | `ReactNode` | - | Optional child components |
+| `classes` | `Record<string, string>` | - | Custom CSS classes |
+| `isAuth` | `() => boolean` | - | Authentication check function |
+
+**Example:**
+
+```jsx
+import { Gotham } from '@nlabs/gothamui';
+
+const config = {
+  app: {
+    name: 'my-app',
+    title: 'My Application'
+  },
+  routes: [
+    // Your routes
+  ]
+};
+
+const App = () => (
+  <Gotham config={config} />
+);
+```
+
+### `<GothamProvider>`
+
+Provider component that sets up the GothamUI context.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `GothamConfiguration` | Required | Configuration object for the application |
+| `children` | `ReactNode` | - | Child components |
+| `session` | `Record<string, unknown>` | `{}` | Initial session data |
+
+## Public Views
+
+All GothamUI views are public from both `@nlabs/gothamui` and `@nlabs/gothamui/views`.
+
+| View | Purpose |
+|------|---------|
+| `AuthSignInView` | Complete sign-in screen built on `AuthView` |
+| `AuthSignUpView` | Complete account-registration screen built on `AuthView` |
+| `AuthView` | Shared authentication layout |
+| `DefaultView` | Responsive application shell with standard navigation |
+| `Gotham` | GothamUI application bootstrap component |
+| `GothamProvider` | Configuration, session, and Flux provider |
+| `GothamRoot` | Root route outlet with notifications, loading state, and analytics |
+| `HomeView` | Responsive home-page shell |
+| `LoaderView` | Flux-connected full-screen loading state |
+| `MenuView` | Responsive sidebar application shell |
+| `NotFoundView` | Full-page missing-route view |
+
+## Form Components
+
+### `<Form>`
+
+Form component with built-in validation using Zod.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | Required | Form fields and controls |
+| `className` | `string` | - | Custom CSS class |
+| `defaultValues` | `Record<string, unknown>` | `{}` | Default form values |
+| `mode` | `'onSubmit'` \| `'onBlur'` \| `'onChange'` \| `'onTouched'` \| `'all'` | `'onBlur'` | Form validation mode |
+| `name` | `string` | `'default'` | Form name (used for test IDs) |
+| `onChange` | `(data: unknown) => void` | - | Change handler |
+| `onSubmit` | `(data: unknown, event: BaseSyntheticEvent, setError: (field: string, error: { type: string; message: string }) => void) => void` | Required | Submit handler |
+| `schema` | `z.ZodSchema<Record<string, unknown>>` | - | Zod validation schema |
+| `validate` | `(data: unknown) => void` | - | Custom validation function |
+| `validateOnBlur` | `boolean` | - | Whether to validate on blur |
+
+**Example:**
+
+```jsx
+import { Form, TextField, Button } from '@nlabs/gothamui';
+import { z } from 'zod';
+
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8)
+});
+
+const LoginForm = () => (
+  <Form
+    schema={schema}
+    onSubmit={(data) => console.log(data)}
+    defaultValues={{ email: '', password: '' }}
+  >
+    <TextField name="email" label="Email" />
+    <TextField name="password" type="password" label="Password" />
+    <Button type="submit" label="Submit" />
+  </Form>
+);
+```
+
+### `<TextField>`
+
+Text input component.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Custom CSS class |
+| `disabled` | `boolean` | `false` | Whether the field is disabled |
+| `error` | `string` | - | Error message |
+| `id` | `string` | - | Field ID |
+| `label` | `string` | - | Field label |
+| `name` | `string` | Required | Field name |
+| `onChange` | `(event: ChangeEvent<HTMLInputElement>) => void` | - | Change handler |
+| `placeholder` | `string` | - | Placeholder text |
+| `required` | `boolean` | `false` | Whether the field is required |
+| `type` | `'text'` \| `'password'` \| `'email'` \| `'number'` \| `'tel'` | `'text'` | Input type |
+| `value` | `string` | - | Field value |
+
+### `<SelectField>`
+
+Dropdown select component.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Custom CSS class |
+| `disabled` | `boolean` | `false` | Whether the field is disabled |
+| `error` | `string` | - | Error message |
+| `id` | `string` | - | Field ID |
+| `label` | `string` | - | Field label |
+| `name` | `string` | Required | Field name |
+| `onChange` | `(event: ChangeEvent<HTMLSelectElement>) => void` | - | Change handler |
+| `options` | `Array<{ label: string; value: string }>` | `[]` | Select options |
+| `placeholder` | `string` | - | Placeholder text |
+| `required` | `boolean` | `false` | Whether the field is required |
+| `value` | `string` | - | Field value |
+
+### `<RadioField>`
+
+Radio button group component.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Custom CSS class |
+| `disabled` | `boolean` | `false` | Whether the field is disabled |
+| `error` | `string` | - | Error message |
+| `id` | `string` | - | Field ID |
+| `label` | `string` | - | Field label |
+| `name` | `string` | Required | Field name |
+| `onChange` | `(event: ChangeEvent<HTMLInputElement>) => void` | - | Change handler |
+| `options` | `Array<{ label: string; value: string }>` | `[]` | Radio options |
+| `required` | `boolean` | `false` | Whether the field is required |
+| `value` | `string` | - | Field value |
+
+### `<DateField>`
+
+Date picker component.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Custom CSS class |
+| `disabled` | `boolean` | `false` | Whether the field is disabled |
+| `error` | `string` | - | Error message |
+| `id` | `string` | - | Field ID |
+| `label` | `string` | - | Field label |
+| `name` | `string` | Required | Field name |
+| `onChange` | `(date: Date) => void` | - | Change handler |
+| `placeholder` | `string` | - | Placeholder text |
+| `required` | `boolean` | `false` | Whether the field is required |
+| `value` | `Date` | - | Field value |
+
+## UI Components
+
+### `<Markdown>`
+
+Renders Markdown through `react-markdown` while providing GothamUI container styling, remote content loading, and template values.
+
+```tsx
+import {Markdown} from '@nlabs/gothamui';
+
+<Markdown
+  className="prose"
+  content="# Welcome, {{name}}"
+  values={{name: 'Bruce'}}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | `''` | Additional class names for the Markdown container |
+| `content` | `string` | - | Inline Markdown content |
+| `url` | `string` | - | URL whose response supplies the Markdown content |
+| `values` | `Record<string, unknown>` | `{}` | Values substituted into the Markdown template |
+
+### `<PaymentMethodPanel>`
+
+Displays an empty or masked saved-payment state and delegates add, replace, and remove workflows to application callbacks. It does not collect or store payment credentials.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `brand` | `string` | `''` | Display-safe payment brand |
+| `isAdding` | `boolean` | `false` | Shows add or replace progress and disables actions |
+| `isRemoving` | `boolean` | `false` | Shows removal progress and disables actions |
+| `last4` | `string` | `''` | Last four display digits |
+| `onAdd` | `() => void` | Required | Starts the provider-owned add or replace flow |
+| `onRemove` | `() => void` | `undefined` | Starts removal and controls whether the remove action is shown |
+
+See [Payment methods](./payments.md) for all props, examples, loading states, and security guidance.
+
+### `<Button>`
+
+Button component with multiple variants and states.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Button content |
+| `className` | `string` | - | Custom CSS class |
+| `color` | `GothamColor` | `'primary'` | Button color |
+| `disabled` | `boolean` | `false` | Whether the button is disabled |
+| `hasNotification` | `boolean` | `false` | Show notification indicator |
+| `hasShadow` | `boolean` | `false` | Show shadow effect |
+| `icon` | `ReactNode` | - | Button icon |
+| `isLoading` | `boolean` | `false` | Show loading spinner |
+| `label` | `string` | `''` | Button label (used if children not provided) |
+| `onClick` | `(event?: unknown) => void` | `() => {}` | Click handler |
+| `size` | `'sm'` \| `'md'` \| `'lg'` | `'md'` | Button size |
+| `tabIndex` | `number` | - | Tab index |
+| `type` | `'button'` \| `'reset'` \| `'submit'` | `'button'` | Button type |
+| `variant` | `'text'` \| `'contained'` \| `'outlined'` | - | Button variant |
+
+### `<Loader>`
+
+Loading indicator component.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Custom CSS class |
+| `color` | `string` | `'primary'` | Loader color |
+| `content` | `string` | - | Loading message |
+| `size` | `'sm'` \| `'md'` \| `'lg'` | `'md'` | Loader size |
+
+### `<Notify>`
+
+Notification component for displaying alerts and messages.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `actions` | `Array<{ label: string; onClick: () => void }>` | `[]` | Action buttons |
+| `anchorOrigin` | `{ horizontal: 'left' \| 'center' \| 'right', vertical: 'top' \| 'bottom' }` | `{ horizontal: 'center', vertical: 'bottom' }` | Position of the notification |
+| `autoHideDuration` | `number` | `5000` | Auto-hide duration in milliseconds |
+| `className` | `string` | - | Custom CSS class |
+| `isOpen` | `boolean` | `false` | Whether the notification is open |
+| `message` | `string` | Required | Notification message |
+| `onClose` | `() => void` | - | Close handler |
+| `severity` | `'success'` \| `'info'` \| `'warning'` \| `'error'` | `'info'` | Notification severity |
+
+### `<Svg>`
+
+SVG icon component.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | - | Custom CSS class |
+| `color` | `string` | - | Icon color |
+| `height` | `number` | - | Icon height |
+| `name` | `string` | Required | Icon name |
+| `width` | `number` | - | Icon width |
+
+## Navigation Components
+
+### `<GothamRoute>`
+
+Route component for defining routes with authentication.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `authenticate` | `boolean` | `false` | Whether the route requires authentication |
+| `element` | `ReactElement` | Required | Component to render |
+| `path` | `string` | Required | Route path |
+
+### `<AuthRoute>`
+
+Route component that handles authentication redirects.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `authenticate` | `boolean` | `false` | Whether the route requires authentication |
+| `element` | `ReactElement` | Required | Component to render |
+| `path` | `string` | Required | Route path |
+
+## Configuration Types
+
+### `GothamConfiguration`
+
+Configuration object for GothamUI applications.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `app` | `{ logo?: string; name?: string; title?: string; titleBarSeparator?: string; }` | `{ name: 'gotham', title: 'GothamUI' }` | Application metadata |
+| `baseUrl` | `string` | `''` | Base URL for the application |
+| `config` | `FluxOptions` | - | Flux configuration options |
+| `displayMode` | `'light'` \| `'dark'` | - | Theme display mode |
+| `flux` | `FluxFramework` | - | Custom Flux instance |
+| `isAuth` | `() => boolean` | `() => false` | Authentication check function |
+| `middleware` | `FluxMiddlewareType[]` | `[]` | Flux middleware |
+| `onInit` | `() => void` | - | Initialization callback |
+| `routes` | `GothamRouteData[]` | `[]` | Application routes |
+| `storageType` | `'local'` \| `'session'` | `'session'` | Storage type for persisted state |
+| `stores` | `unknown[]` | `[]` | Additional Flux stores |
+| `theme` | `Record<string, unknown>` | `{}` | Theme configuration |
+| `translations` | `Record<string, unknown>` | `{ translation: {} }` | i18n translations |
+
+## Actions
+
+### `GothamActions`
+
+Action creators for common operations.
+
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| `init` | `() => Promise<FluxAction>` | Initialize the application |
+| `loading` | `(isLoading: boolean, content?: string) => Promise<FluxAction>` | Show/hide loading indicator |
+| `navBack` | `() => Promise<FluxAction>` | Navigate back |
+| `navForward` | `() => Promise<FluxAction>` | Navigate forward |
+| `navGoto` | `(path: string, params?: Record<string, unknown>) => Promise<FluxAction>` | Navigate to a path |
+| `navReplace` | `(path: string, params?: Record<string, unknown>) => Promise<FluxAction>` | Replace current route |
+| `notify` | `(params: GothamNotifyParams) => Promise<FluxAction>` | Show notification |
+| `notifyClose` | `() => Promise<FluxAction>` | Close notification |
+| `setConfig` | `(config: GothamConfiguration) => Promise<FluxAction>` | Update configuration |
+| `signOut` | `() => Promise<FluxAction>` | Sign out user |
+| `updateTitle` | `(title: string, separator?: string) => Promise<FluxAction>` | Update page title |

package/lib/docs/comparison.md

@@ -0,0 +1,83 @@
+# GothamUI vs Other Frameworks
+
+This comparison highlights the key differences between GothamUI and other popular React frameworks.
+
+## Feature Comparison
+
+| Feature | GothamUI | Next.js | Create React App | Gatsby |
+|---------|----------|---------|-----------------|--------|
+| **Setup Complexity** | Low | Medium | Low | Medium |
+| **Routing** | Built-in (React Router) | Built-in (File-based) | Requires react-router | Built-in (Gatsby Router) |
+| **State Management** | Built-in (ArkhamJS/Flux) | External (Redux, etc.) | External (Redux, etc.) | External (Redux, etc.) |
+| **Form Handling** | Built-in (React Hook Form + Zod) | External | External | External |
+| **UI Components** | Built-in | External | External | External |
+| **Internationalization** | Built-in (i18next) | External | External | External |
+| **Authentication** | Built-in | External | External | External |
+| **Notifications** | Built-in | External | External | External |
+| **SSR/SSG Support** | No | Yes | No | Yes |
+| **Development Experience** | Streamlined | Comprehensive | Basic | Comprehensive |
+| **Bundle Size** | Medium | Large | Small | Large |
+| **Learning Curve** | Gentle | Steep | Gentle | Steep |
+| **Customization** | High | High | Medium | Medium |
+| **Community Size** | Small | Very Large | Very Large | Large |
+
+## When to Choose GothamUI
+
+### Choose GothamUI when:
+
+- You want a complete, ready-to-use React framework with minimal configuration
+- You prefer a Flux-based state management approach
+- You need built-in form handling with validation
+- You want a consistent UI component library out of the box
+- You're building a client-side application with authentication needs
+- You value developer experience and want to minimize boilerplate code
+
+### Choose Next.js when:
+
+- You need server-side rendering (SSR) or static site generation (SSG)
+- You want file-based routing
+- You need advanced deployment options (Vercel integration)
+- You're building a large-scale application with a large team
+- You need API routes built into your application
+
+### Choose Create React App when:
+
+- You want a minimal React setup with maximum flexibility
+- You prefer to add libraries as needed
+- You're building a simple client-side application
+- You're learning React and want to start with the basics
+
+### Choose Gatsby when:
+
+- You're building a static website or blog
+- You need excellent image optimization
+- You want to use GraphQL for data fetching
+- You need a large plugin ecosystem
+- You're building a content-heavy site
+
+## Migration Path
+
+If you're considering migrating to GothamUI from another framework, here's what you need to know:
+
+### From Create React App to GothamUI
+
+1. Install GothamUI and its dependencies
+2. Replace your root component with `<Gotham>`
+3. Configure your routes in the GothamUI config object
+4. Migrate your state management to ArkhamJS
+5. Replace form components with GothamUI form components
+6. Replace UI components with GothamUI components
+
+### From Next.js to GothamUI
+
+1. Install GothamUI and its dependencies
+2. Convert file-based routing to GothamUI route configuration
+3. Migrate server-side logic to API endpoints or serverless functions
+4. Migrate state management to ArkhamJS
+5. Replace UI components with GothamUI components
+
+## Conclusion
+
+GothamUI offers a comprehensive solution for React applications with a focus on developer experience and productivity. While it may not have the large ecosystem of Next.js or the SSR capabilities of Gatsby, it excels at providing a complete, ready-to-use framework for client-side applications with minimal configuration.
+
+By combining routing, state management, form handling, and UI components in a single package, GothamUI allows developers to focus on building features rather than configuring tools and libraries.

package/lib/docs/containers.md

@@ -0,0 +1,11 @@
+# Containers
+
+There are 2 included containers to choose from:
+
+*default*
+
+Has a top bar with logo and menu. The top bar is transparent and turns translucent with a backdrop blur when scrolling down. Use `transparentScrollBackdropFilter` to customize the blur while keeping the top state transparent.
+
+*menu*
+
+A side bar on the left.