@arbol-ai/ui 0.0.0-stage → 0.1.0

package/skills/arbol-ui/references/setup.md

@@ -0,0 +1,79 @@
+# Setting up an app with @arbol-ai/ui
+
+## 1. Install
+
+```bash
+bun add @arbol-ai/ui react-aria-components react-aria
+# Optional entries:
+bun add echarts                 # @arbol-ai/ui/charts
+bun add @tanstack/react-form    # @arbol-ai/ui/form
+```
+
+Peers: React 19, `react-aria-components` ≥1.21, `react-aria` ≥3.52, Tailwind CSS ≥4.1. Keep one copy of
+React Aria in the app (`bun pm ls react-aria-components`): two copies split the locale and router contexts.
+
+## 2. Styles
+
+In the app's entry stylesheet, after Tailwind:
+
+```css
+@import 'tailwindcss';
+@import '@arbol-ai/ui/theme.css';
+```
+
+The theme adds the tokens (`bg-primary`, `text-muted-foreground`, `rounded-field`, `shadow-md`, the gray
+and status ramps), the base layer and an `@source` for the library's files, so Tailwind generates the
+classes the components use. Dark mode is the `dark` class on `<html>`; the grayscale appearance is
+`data-theme="mono"` on `<html>`. Set them before the first paint (an inline script in `index.html`) to
+avoid a flash.
+
+Fonts are named, never shipped: load your faces with `@font-face`, or the brand's open ones (Schibsted
+Grotesk, Martian Mono) from Fontsource, or override `--ui-font-sans`, `--ui-font-heading`, `--ui-font-mono`.
+
+## 3. The provider
+
+Render `UIProvider` once, above every component:
+
+```tsx
+import { UIProvider } from '@arbol-ai/ui';
+import { useRouter } from '@tanstack/react-router';
+
+export const Providers = ({ children }: { children: React.ReactNode }) => {
+  const router = useRouter();
+  return (
+    <UIProvider
+      locale={locale}
+      navigate={(to, options) => router.navigate({ ...options, to })}
+      useHref={(to) => router.buildLocation({ to }).href}
+    >
+      {children}
+    </UIProvider>
+  );
+};
+```
+
+- `locale`: the app's language as a BCP 47 tag. React Aria formats dates and numbers with it, and the
+  library picks its own strings by language (`es-*` → Spanish, anything else → English).
+  - Paraglide: `locale={getLocale() === 'es' ? 'es-CO' : 'en-US'}`.
+  - i18next: `locale={i18n.language}`.
+  - Spanish only: `locale="es-CO"`.
+- `navigate` / `useHref`: every `href` in the library (links, menu items, tabs, table rows, breadcrumbs,
+  navigation) then navigates client-side. Type the hrefs with React Aria's `RouterConfig`:
+
+```ts
+import type { NavigateOptions, ToOptions } from '@tanstack/react-router';
+
+declare module 'react-aria-components' {
+  interface RouterConfig {
+    href: ToOptions['to'];
+    routerOptions: Omit<NavigateOptions, keyof ToOptions>;
+  }
+}
+```
+
+- `messages`: optional replacements for the library's own strings (see `i18n.md`).
+
+## 4. Toasts
+
+Mount `<Toaster />` once inside `UIProvider` (usually in the root layout), then call
+`toast.success(...)` / `toast.error(...)` from anywhere.