# Rahhal's Marsam

> Rahhal's design system: reusable React components, light and dark design tokens, downloadable brand icons, and English/Arabic interface patterns.

If you need the Rahhal icon or logo, start with the first section. Fetch any linked file with a normal HTTP GET; no JavaScript or authentication is required.

## Rahhal icons and brand assets

- [Rahhal icon documentation](https://marsam.rahhal.app/components/icons.md): Direct PNG and SVG downloads, light and dark variants, React examples, and guidance distinguishing brand assets from UI icons.
- [Rahhal icon PNG](https://marsam.rahhal.app/brand/app-icon-light.png): Default light consumer Rahhal app icon, ready to download and use in an image element or React component.
- [Rahhal icon dark PNG](https://marsam.rahhal.app/brand/app-icon-dark.png): Dark consumer Rahhal app icon for dark backgrounds and dark home screens, available as a direct image download.
- [Rahhal icon SVG](https://marsam.rahhal.app/brand/app-icon-light.svg): Light Rahhal icon asset in SVG format for browser favicons and clients accepting SVG files.
- [RahhalIcon renderer](https://marsam.rahhal.app/components/rahhal-icon.md): React renderer for image URLs, emoji, and catalog icon strings; pass the Rahhal asset URL explicitly.

## Documentation

- [Complete reference](https://marsam.rahhal.app/llms-full.txt): All component documentation, design token values, guidelines, frequently asked questions, and brand assets in one text response.
- [Full component inventory](https://marsam.rahhal.app/skill.md): Every catalog entry linked to its Markdown reference, with shared package conventions and cross-platform guidance.
- [Component catalog](https://marsam.rahhal.app/components.md): Browse the complete component list by category with descriptions and links to each component reference.
- [Guidelines](https://marsam.rahhal.app/guidelines.md): Rules for composing interfaces, using theme tokens, supporting Arabic and RTL, and contributing shared components.
- [Why Marsam](https://marsam.rahhal.app/why.md): Explains how shared packages keep Rahhal mini-app interfaces, localization, and authentication behavior consistent across products.
- [Frequently asked questions](https://marsam.rahhal.app/faq.md): Onboarding answers about design tokens, package imports, auth, localization, and finding or contributing a missing component.

## Foundations and common components

- [Colors and radius](https://marsam.rahhal.app/components/colors.md): Complete light and dark color tables with hexadecimal values, HSL channels, CSS variables, Tailwind classes, and radius tokens.
- [Typography](https://marsam.rahhal.app/components/typography.md): Font families for web, iOS, and Android, plus type scales, font weights, and bilingual typography usage.
- [Button](https://marsam.rahhal.app/components/button.md): Button imports, variants, sizes, and composition guidance for consistent actions throughout Rahhal mini-app interfaces.
- [Card](https://marsam.rahhal.app/components/card.md): Shared card surfaces and composition primitives for grouping related interface content using the current theme tokens.
- [Form](https://marsam.rahhal.app/components/form.md): Form field helpers and react-hook-form integration for labels, descriptions, validation messages, and accessible input composition.
- [Embedded mode](https://marsam.rahhal.app/components/embedded-mode.md): Native host integration and shared chrome behavior when a mini-app runs inside Rahhal on mobile or desktop.

## Retrieval guidance

- Download the linked PNG or SVG bytes directly when an image file is requested.
- Read /components/icons.md for React usage and all available brand asset variants.
- Use /llms-full.txt when the task needs the complete catalog in one request.
- Read an individual component Markdown file for focused implementation work.
- Use the HTML page linked in each reference for interactive examples.

## Key Facts

- Marsam is the design-system catalog for Rahhal mini-apps.
- There are 58 catalog entries across reusable components, foundations, and shared patterns.
- UI components come from @rahhal/ui; design tokens come from @rahhal/themes.
- Supported interface languages are English and Arabic, including RTL layout.
- The official icon documentation is /components/icons; RahhalIcon is a separate image and catalog-value renderer.
- Every component has a plain Markdown reference at /components/<slug>.md.
- This catalog has UI-only sign-in demonstrations; they do not authenticate visitors.

## Optional

- [Marsam homepage](https://marsam.rahhal.app/): Overview of Rahhal's design system with live component previews and links to the documentation and brand assets.
- [Sitemap](https://marsam.rahhal.app/sitemap.xml): Canonical public documentation pages for search crawlers, excluding sign-in demos and missing pages from the index.
- [Crawler policy](https://marsam.rahhal.app/robots.txt): Public crawler access rules and the canonical sitemap location used by the Marsam documentation site.

## Download the Rahhal icon or logo

For a request such as "get the Rahhal icon", use the consumer light PNG below by default. The dark variant is also available. These are direct public files: no login, JavaScript, or image extraction is needed.

- [Rahhal icon (light PNG)](https://marsam.rahhal.app/brand/app-icon-light.png): Default consumer Rahhal app icon for light surfaces and general downloads.
- [Rahhal icon (dark PNG)](https://marsam.rahhal.app/brand/app-icon-dark.png): Consumer Rahhal app icon for dark surfaces and dark home screens.
- [Rahhal icon (light SVG)](https://marsam.rahhal.app/brand/app-icon-light.svg): Light SVG asset for browser favicons and clients that accept SVG files.
- [Rahhal icon (dark SVG)](https://marsam.rahhal.app/brand/app-icon-dark.svg): Dark SVG asset for browser favicons and clients that accept SVG files.
- [Rahhal admin icon](https://marsam.rahhal.app/brand/app-icon-admin.png): Distinct icon reserved for internal admin and debug applications.
- [Apple touch icon](https://marsam.rahhal.app/brand/apple-touch-icon.png): 180 by 180 pixel PNG for Apple touch icons.
- [PWA icon (192px)](https://marsam.rahhal.app/brand/icon-192.png): 192 by 192 pixel PNG for web app manifests.
- [PWA icon (512px)](https://marsam.rahhal.app/brand/icon-512.png): 512 by 512 pixel PNG for web app manifests.
- [Maskable PWA icon](https://marsam.rahhal.app/brand/icon-512-maskable.png): 512 by 512 pixel maskable PNG for adaptive launcher shapes.

The served URL starts with /brand/, never /public/brand/. Source assets live in packages/seo/assets/ and are published by @rahhal/seo.

## React usage

```tsx
import { RahhalIcon } from "@rahhal/ui/rahhal-icon";

<RahhalIcon
  icon="url:https://marsam.rahhal.app/brand/app-icon-light.png"
  size={48}
  alt="Rahhal"
/>
```

```html
<img src="https://marsam.rahhal.app/brand/app-icon-light.png" width="48" height="48" alt="Rahhal" />
```

RahhalIcon is a renderer for catalog values, not a bundled Rahhal logo: pass an explicit image URL. Lucide Compass is a general UI icon, not the official downloadable Rahhal app icon.

---

Source: https://marsam.rahhal.app/components.md

# Rahhal component catalog

58 documented entries. [Agent index](https://marsam.rahhal.app/llms.txt).

## tokens

- [Colors & radius](https://marsam.rahhal.app/components/colors.md): Every design token from @rahhal/themes. Tokens are stored as HSL channels (so Tailwind opacity modifiers compose) AND surfaced as #RRGGBB hex for cross-platform consumers (iOS, Android, slides, Figma). Light + dark are the two themes; system preference is auto-detected on web.
- [Typography](https://marsam.rahhal.app/components/typography.md): Font families (sans · arabic · mono) with web stacks plus iOS/Android equivalents, type scale (rem + px), and weight ramp. Bilingual EN/AR samples live alongside each other.
- [Icons & brand marks](https://marsam.rahhal.app/components/icons.md): Download official Rahhal icons in PNG and SVG, with light and dark variants, React usage, and guidance for Lucide UI icons and social brand marks.
- [RahhalIcon](https://marsam.rahhal.app/components/rahhal-icon.md): Cross-platform icon renderer. Parses the same prefixed catalog strings the iOS shell understands (`url:…`, `emoji:…`, `system:…`, `resource:…`, plus bare URLs/emojis) so a CMS-authored value paints identically on every client. Falls back to a muted square when the value is empty; `system:` and `resource:` render as debug tokens on the web because there's no SF Symbols / iOS bundle equivalent.

## actions

- [Button](https://marsam.rahhal.app/components/button.md): Primary actionable element. Six variants and four sizes. Use `asChild` to keep button styling on a router-aware link.
- [Toggle · ToggleGroup](https://marsam.rahhal.app/components/toggle.md): On/off button (`<Toggle>`) and grouped toggle sets (`<ToggleGroup>`). Use for formatting toolbars, view-mode switches, and any compact two-state control. `ToggleGroup` accepts `type="single"` for radio-style behavior or `type="multiple"` for checkbox-style.
- [BackButton](https://marsam.rahhal.app/components/back-button.md): Small ghost capsule with a leading chevron — the standard 'go back' affordance for nested pages. Defaults to `window.history.back()`; pass `onClick` to plug in router-aware navigation. The chevron rotates automatically under RTL.
- [PasteButton](https://marsam.rahhal.app/components/paste-button.md): Icon button that reads the system clipboard and forwards the text to a callback. Defaults to a clipboard glyph; pair with a string-transform helper at the call site (URL extractor, code parser, normaliser).

## forms

- [Input & Textarea](https://marsam.rahhal.app/components/input.md): Native `<input>` and `<textarea>` wrappers themed via design tokens. Pair with `<Label htmlFor>` for accessible click-the-text targets.
- [SearchBar](https://marsam.rahhal.app/components/search-bar.md): Capsule-shaped search input with leading magnifier, optional clear button, optional trailing slot (e.g. ⌘K hint), and Enter-to-submit. Wrapped in `<form role="search">` so iOS shows the on-screen "Search" key. Inputs are normally rectangular in this design system — search is the one intentional capsule exception, matching Apple's HIG.
- [FilterChip](https://marsam.rahhal.app/components/filter-chip.md): Toggleable filter pill. Two interaction modes that compose: `active`+`onToggle` for multi-select category chips, `onRemove` for "applied filter" chips that show what's currently filtering the list. Optional `leading` icon and `count` badge.
- [FileDropzone](https://marsam.rahhal.app/components/file-dropzone.md): Drop-or-browse file picker with native HTML5 drag-and-drop, click-to-select fallback, and built-in `accept` / `maxSize` / `maxFiles` validation. Always controlled — the parent owns the file list. RTL-safe via logical Tailwind utilities.
- [Switch · Checkbox · Radio](https://marsam.rahhal.app/components/switch-and-toggles.md): Boolean and small-set selectors. `<Switch>` for on/off settings, `<Checkbox>` for individual toggles, `<RadioGroup>` for mutually-exclusive choices.
- [Slider](https://marsam.rahhal.app/components/slider.md): Value picker with a draggable thumb. Built on Radix Slider. Pass a single-element array for a normal slider or a two-element array for a range slider.
- [Combobox](https://marsam.rahhal.app/components/combobox.md): Searchable single-select picker. Composes `<Popover>` + `<Command>` + `<Button>` into the canonical shadcn pattern. Use for country / city / airport / category pickers where `<Select>` becomes unwieldy past ~10 options.
- [Calendar & DatePicker](https://marsam.rahhal.app/components/date-picker.md): Themed `<Calendar>` (react-day-picker) plus the canonical `<DatePicker>` recipe (Calendar inside a Popover). Single date and range modes share the same trigger.
- [Form (react-hook-form)](https://marsam.rahhal.app/components/form.md): Validated form composition built on react-hook-form. `<FormField>` wires a controller into descendant `<FormLabel>` / `<FormControl>` / `<FormDescription>` / `<FormMessage>` parts via shared aria attributes — labels point to inputs, errors are announced, and focus rings show on the right element automatically.

## surfaces

- [Section](https://marsam.rahhal.app/components/section.md): Page-section building block: header (title + description + optional action), spacing rhythm, and footer slot. Pairs with `Card`, `List`, or `Table` for the surface; `Section` only handles labeling and rhythm so layouts stay uniform.
- [Card](https://marsam.rahhal.app/components/card.md): Surface container for grouped content. Compose with `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`.
- [List](https://marsam.rahhal.app/components/list.md): Apple-style inset grouped list with section headers/footers. Each `ListGroup` is a rounded card; rows separate with hairline dividers. `variant="plain"` flattens the chrome for embedding inside another card. Mirrors the iOS Settings UX.
- [PlaceCard](https://marsam.rahhal.app/components/place-card.md): Compact, mobile-first card for a single geographic place. Name, optional address, and the coordinate readout stack vertically and truncate — never scroll horizontally. The title is adaptive (name → address → coordinates) so a nameless waypoint still renders. Pass an `<Input/>` as `name` for inline editing; use `leading`/`trailing` slots for an icon and a checkbox/switch.
- [Map](https://marsam.rahhal.app/components/map.md): Declarative wrapper around MapLibre GL JS. Compose `MapMarker`, `MapPolyline`, `MapPolygon`, `MapCircle`, and `MapCluster` as children — geometry inherits the platform's blue primary by default. Free OpenFreeMap tiles light/dark; switch via the `style` prop. RTL Arabic labels render correctly out of the box.
- [Kanban board](https://marsam.rahhal.app/components/kanban.md): Column-based task board layout primitive. Provides board frame, columns (title / count / accent / action), and cards (title / description / leading / trailing / meta). Layout only — apps wire drag-and-drop with their own DnD library (e.g. `@dnd-kit/core`). On small screens columns snap-scroll horizontally so swipes feel native.
- [Carousel](https://marsam.rahhal.app/components/carousel.md): Horizontal (or vertical) scroller built on Embla Carousel. Used for photo galleries, onboarding card stacks, and any "swipe through a row" UX. Detects `[dir="rtl"]` automatically and forwards the right axis direction to Embla.
- [Collapsible](https://marsam.rahhal.app/components/collapsible.md): Minimal disclosure primitive (one toggle, one panel). Re-exports of Radix Collapsible. For multiple sections, use `<Accordion>` instead.
- [Layout primitives](https://marsam.rahhal.app/components/primitives.md): `<AspectRatio>` (lock a media ratio), `<ScrollArea>` (themed custom scrollbar), and `<Separator>` (semantic divider). Three small but essential primitives shipped in one catalog page.
- [Table](https://marsam.rahhal.app/components/table.md): Themed `<table>` family wrapped in a rounded card surface. Use for tabular data with multiple columns. For settings-style single-column lists, use `List` instead.

## feedback

- [Badge](https://marsam.rahhal.app/components/badge.md): Inline label for status, counts, tags. Variants: default / secondary / destructive / outline.
- [Avatar · Skeleton · Progress](https://marsam.rahhal.app/components/avatar-and-skeleton.md): Compact identity + loading-state primitives.
- [Alert](https://marsam.rahhal.app/components/alert.md): Inline status callout. Pair with a leading icon for instant recognition.
- [Callout](https://marsam.rahhal.app/components/callout.md): Inline note / hint / warning / important block. Lighter than an Alert — used inside page bodies for disclaimers, agent-targeted hints, deprecation notes, and similar asides.
- [Rating](https://marsam.rahhal.app/components/rating.md): Star rating control with read-only display + interactive input modes. Half-star increments by default, keyboard support (Arrow / Home / End), and an `aria-label` describing the current value. Always renders LTR so 1-star sits at the start edge in both reading directions.
- [EmptyState](https://marsam.rahhal.app/components/empty-state.md): Recurring "nothing here yet" surface. Drop into any list, table, or section that can be empty — icon, title, description, and an optional action keep the spacing rhythm consistent across mini-apps.
- [Toaster (sonner)](https://marsam.rahhal.app/components/toaster.md): One `<Toaster />` mount + the imperative `toast(...)` helper. Theme follows `useTheme()` automatically.
- [JsonViewer](https://marsam.rahhal.app/components/json-viewer.md): Read-only, syntax-highlighted JSON block. Use for admin payload inspectors, debug panels, webhook viewers — any surface where an operator skims, copies, or downloads a structured payload. Theme tokens are wired through CSS variables so it follows light / dark automatically.
- [Spinner](https://marsam.rahhal.app/components/spinner.md): Small indeterminate loading indicator. Stroke is `currentColor` so it inherits the surrounding text color (slot inside a destructive button → destructive-on-foreground spinner). Declares `role="status"` and an `aria-label` so assistive tech announces the pending state.

## nav

- [NavBar](https://marsam.rahhal.app/components/nav-bar.md): Opinionated top navigation built on `<AppHeader>`. Brand on the start, typed links centered on `md+`, actions on the end. Router-agnostic via a `renderLink` render prop so apps can supply their own `<NavLink>` / `<Link>`.
- [Stepper](https://marsam.rahhal.app/components/stepper.md): Multi-step progress indicator. Horizontal (default) or vertical orientation; status (`complete`, `current`, `upcoming`) is derived per-step from `activeStep`.
- [WizardHeader](https://marsam.rahhal.app/components/wizard-header.md): Sticky per-step header for multi-step flows inside a native host (`?host=…`), where the web hides its own AppHeader/AppFooter. Back control at the start, centered title, optional action at the end, plus a slim segmented progress bar. Back navigation is delegated via `onBack`; top safe-area padding clears the iOS notch. RTL-aware.
- [Breadcrumb](https://marsam.rahhal.app/components/breadcrumb.md): Hierarchical navigation trail. Compose `<Breadcrumb>` → `<BreadcrumbList>` → `<BreadcrumbItem>` (containing `<BreadcrumbLink>` or `<BreadcrumbPage>`) with `<BreadcrumbSeparator>` between siblings. The default chevron flips under RTL.
- [Pagination](https://marsam.rahhal.app/components/pagination.md): Accessible page navigator. Compose `<Pagination>` → `<PaginationContent>` → `<PaginationItem>` (with `<PaginationLink>`, `<PaginationPrevious>`, `<PaginationNext>`, or `<PaginationEllipsis>` inside). Previous/Next chevrons rotate under RTL.
- [Tabs · Accordion](https://marsam.rahhal.app/components/tabs-and-accordion.md): Disclose grouped content. Use tabs for parallel views, accordion for sequential reveal.
- [Sidebar](https://marsam.rahhal.app/components/sidebar.md): Layout primitives for the catalog-style left rail every Rahhal mini-app uses: a glassy floating column with a sticky filter / brand area, a scrolling body, and collapsible sections. Layout-only — apps supply data, routing, and filtering.
- [Embedded mode](https://marsam.rahhal.app/components/embedded-mode.md): Detection helper for when a mini-app is loaded inside an iOS / Android / desktop host container. The host signals via `?host=<value>`; the web persists it in sessionStorage and exposes it to layouts via `useIsEmbedded()` so chrome (`<AppHeader>`, `<AppFooter>`) can be hidden in favor of the host's native nav.
- [Footer](https://marsam.rahhal.app/components/footer.md): Bottom chrome for a Rahhal mini-app. A floating glassy capsule that mirrors `<AppHeader>`: links + social inside a pill, brand line below. Helpers `<FooterLinks>`, `<FooterLink>`, and `<FooterSocial>` keep spacing and ARIA consistent.

## overlays

- [AlertDialog](https://marsam.rahhal.app/components/alert-dialog.md): Interrupting confirmation dialog for destructive or unrecoverable actions. The user must explicitly confirm or cancel — clicking outside does not dismiss. Built on Radix Alert Dialog.
- [Drawer](https://marsam.rahhal.app/components/drawer.md): Bottom-sheet style modal that slides up from the edge of the viewport. Built on `vaul` for touch-friendly drag-to-dismiss. Use for mobile-first flows where a centered `<Dialog>` would feel heavy. For desktop side panels, prefer `<Sheet>`.
- [Popover](https://marsam.rahhal.app/components/popover.md): Floating panel anchored to a trigger. Non-modal — clicking outside dismisses. Built on Radix Popover. Use for date pickers, filter panels, color pickers, settings popouts.
- [HoverCard](https://marsam.rahhal.app/components/hover-card.md): Small floating preview shown on hover or focus. Use for profile cards, link previews, or anywhere a tooltip would be too small. Built on Radix Hover Card.
- [Command palette](https://marsam.rahhal.app/components/command.md): Searchable list / command palette built on `cmdk`. Use inline (`<Command>`) for typeahead pickers, or wrapped in `<CommandDialog>` for a global cmd-K launcher. Items are scored client-side as the user types.
- [Dialog · Sheet](https://marsam.rahhal.app/components/dialog-and-sheet.md): Centered modal vs. side sheet. Use a dialog for short focused interactions; use a sheet for navigation drawers, filters, or contextual editors.
- [Dropdown · Select · Tooltip](https://marsam.rahhal.app/components/menus-and-tooltip.md): Floating triggers and selectors. All three flip correctly under RTL.

## auth

- [PhoneInput](https://marsam.rahhal.app/components/phone-input.md): International phone field with searchable country picker. Default country is auto-detected from the user's IANA timezone (e.g. KSA for Asia/Riyadh). Numbers always render LTR even inside RTL regions.
- [InputOTP](https://marsam.rahhal.app/components/input-otp.md): Segmented one-time-code input. Used for the SMS code step of the Rahhal phone-OTP sign-in flow, but generic enough for any 4–8 digit verification code. Built on the `input-otp` library; logical Tailwind utilities mean the rounded ends and divider borders flip correctly under RTL.
- [LoginScreen (demo)](https://marsam.rahhal.app/components/login-screen.md): A UI-only walk-through of the canonical Rahhal phone-OTP login: phone step → OTP step → success. Two layouts share the same form body — `centered` (default) is a focused single-card screen; `split` adds a brand-led marketing pane on the start edge at `lg+`. Production mini-apps consume the same UX via `<LoginScreen>` from `@rahhal/auth/react`.
- [RequireRole](https://marsam.rahhal.app/components/require-role.md): Render-gate that requires both an active session and a named role string in the user's `app_metadata.roles` claim. Compose at the top of a protected subtree so the gate runs once. Roles are issued backend-side by writing `auth.users.app_metadata.roles`; this component is read-only.
- [AccessDeniedScreen](https://marsam.rahhal.app/components/access-denied-screen.md): Full-screen "you don't have permission" surface. Pairs with `<RequireRole>` from `@rahhal/auth/react` as the default `deniedFallback`. Same anatomy as `<EmptyState>` — icon · title · description · action — with a destructive-tinted icon tile and a viewport-filling default layout.

## data

- [Country facts](https://marsam.rahhal.app/components/countries.md): Drop-in country UI from `@rahhal/countries/react`: `CountryFlag`, `CountryCard`, `CountryFacts`, `CountryDetail`. Data-in or self-fetching (by `name`/`code`), label-injected for i18n, and composed from `@rahhal/ui`. Backed by a REST Countries v4 client with an automatic v3.1 fallback.


---

Source: https://marsam.rahhal.app/why.md

# Why a shared design system for Rahhal mini-apps?

Rahhal is a family of small, focused web apps that each live on their own subdomain. Without a shared foundation, each new mini-app would re-invent the same buttons, the same theme, the same login screen — and slowly drift away from feeling like one product.

## The problem

Independent deploys are great for teams; they're terrible for brand cohesion if each app picks its own colors, type scale, and locale handling. The design system makes the right thing the easy thing: a mini-app that uses `@rahhal/ui`, `@rahhal/themes`, `@rahhal/i18n`, and `@rahhal/auth` automatically inherits the platform's look, RTL behavior, and authentication contract.

## Use cases

| use case | what it gives you |
| --- | --- |
| One product family | Every mini-app on rahhal.app feels like a chapter of the same product. |
| Bilingual by default | EN + AR (with full RTL) ship together — no retrofit, no per-app translation pipeline. |
| Phone-OTP, once | `@rahhal/auth` implements the iOS → web handover and standalone OTP flow exactly once. |
| Built for AI agents | Every catalog page is also served as Markdown — same source of truth humans browse here. |
| Cross-platform tokens | Color / typography / radius defined in TypeScript, emitted as CSS vars + JSON for iOS / Android / Figma. |
| Ship fast | Scaffolding a new mini-app is mostly composing what's already here. |

## Principles

- Compose first — reach for `@rahhal/ui` before writing your own button.
- Tokens are the contract — never hardcode brand colors in an app.
- RTL is not optional — use logical utilities and the i18n adapters everywhere.
- Document deliberately — shared packages get TSDoc, file headers, and a README; the catalog is the public contract.


---

Source: https://marsam.rahhal.app/guidelines.md

# Principles & Guidelines

Operating rules for the Rahhal design system. The same rules apply whether you're a human writing code or an AI agent generating it. The hard rules below are non-negotiable; the audience tracks at the bottom split for humans and agents.

## Hard rules

| rule | what it means |
| --- | --- |
| Compose first | Reach for `@rahhal/ui` before writing your own button. If a wrapper recurs across two or more apps, promote it back into the package. |
| Tokens come from `@rahhal/themes` | Never redefine brand colors in an app's Tailwind config. Edit `packages/themes/src/themes/{light,dark}.ts` and rebuild — never edit `dist/tokens.css` or `dist/tokens.json` by hand. |
| Bilingual + RTL by default | Both `en` and `ar` are supported. Use Tailwind logical utilities (`ms-*`, `me-*`, `ps-*`, `pe-*`, `start-*`, `end-*`) so RTL flips automatically. Locale resolution goes through `@rahhal/i18n` adapters; never hand-roll detection. |
| Auth via `@rahhal/auth` only | Phone OTP is the only sign-in method (standalone OR iOS → web handover). Never import `@supabase/supabase-js` directly. Never parse the URL fragment manually. Never log tokens. |
| Document deliberately | Shared packages get TSDoc on every export, file headers, and a thorough README. Inline comments only when the *why* is non-obvious. |
| No AI attribution in git | Don't add Co-Authored-By Claude (or any AI mention) to commits or PRs. |

## Need a component that isn't here?

The default answer is **not** "build it locally and forget" — it's "plan it for the design system from the start." Follow this flow:

- **Step 1 — search.** Confirm it's really missing. Filter the catalog (`/`) and grep `packages/ui/src`. Variants of existing components (e.g. a button shape) usually belong as a new variant, not a new component.
- **Step 2 — scope.** Will more than one mini-app reasonably use this? If yes, plan it for `@rahhal/ui` from the start. If it's truly one-app-only (e.g. a domain-specific kanban for a single workflow), keep it app-local — but add a comment with the intended promotion trigger.
- **Step 3 — design the public API.** Sketch the props in TypeScript first. Mirror existing conventions: forwardRef, `asChild` where slot composition makes sense, logical utilities for spacing, design-token classes for color.
- **Step 4 — implement under `packages/ui/src/<component>.tsx`.** Add file-level TSDoc. Export from `index.ts`. Add a subpath in `package.json`. The package ships source TSX, not bundled output.
- **Step 5 — add a catalog entry AND a meta row.** `apps/design-system/src/catalog/entries/<slug>.tsx` for the React preview and `apps/design-system/src/spec/components-meta.ts` for the `.md` endpoint. Both are required — a PR shipping UI without updating the catalog is incomplete.
- **Step 6 — open one PR.** Component + tests + catalog entry + meta + i18n strings should land together. Reviewers can verify the docs match the code in a single pass.

> **Takeaway:** the catalog is the public contract. If a component isn't in the catalog, it doesn't exist for the rest of the platform — and that's how features fragment. Build it here, once, well-documented.

## For AI agents

Use this when generating UI for any Rahhal mini-app:

- **Fetch `/skill.md` first** — it lists every catalog page and the cross-platform conventions.
- **Match by token name, not hex.** `bg-primary` is portable across light/dark/RTL; `#C2562B` is not.
- **Read the relevant `/components/<slug>.md` before generating.** It documents props, variants, and gotchas.
- **Honor RTL.** Use logical utilities (`ms-*`, `me-*`, etc.) and the `rtl:rotate-180` modifier on directional icons.
- **Propose new components fully.** When something is missing, deliver source + catalog entry + meta row + i18n strings in one change — don't leave the catalog out of sync.

## For humans

Code-review checklist when shipping platform changes:

- **Catalog updated?** New / renamed components have a `catalog/entries/<slug>.tsx` AND a row in `spec/components-meta.ts`.
- **Themes built?** Token edits are followed by `pnpm --filter @rahhal/themes build` so generated CSS / JSON match.
- **RTL tested?** Flip the locale switcher to AR; logical utilities should mirror the layout without manual flipping.
- **i18n strings present in both locales?** New copy lands in both `en.json` and `ar.json`.
- **TSDoc on shared exports?** Every public symbol in `packages/*` gets a one-line summary, params, and an example for components / hooks.


---

Source: https://marsam.rahhal.app/faq.md

# Frequently asked questions

Quick answers to the questions newcomers ask first. For long-form references, the `rahhal-miniapps` skill at `.claude/skills/` is the canonical how-to.

### How do I start using the Rahhal design system?

Clone the monorepo, run `pnpm install`, then `pnpm --filter @rahhal/themes build` to generate the token CSS. Browse the components in the catalog to find what you need, and import from `@rahhal/ui`. The repo's `CLAUDE.md` is the always-on summary; the `rahhal-miniapps` skill has the deep how-tos.

### How do I scaffold a new mini-app?

Create a folder under `apps/<name>`, choose Next.js or Vite based on whether you need SSR/SEO, then follow `scaffold-next.md` or `scaffold-vite.md` in the `rahhal-miniapps` skill. Both flows wire `@rahhal/ui`, `@rahhal/themes`, `@rahhal/i18n`, and (optionally) `@rahhal/auth`.

### How do I import components from @rahhal/ui?

Either from the bundle root (`import { Button } from "@rahhal/ui"`) or per-component subpaths (`import { Button } from "@rahhal/ui/button"`). Both work; subpaths keep your bundle tighter when you only need one or two.

### How do I add Arabic (or another locale) to my app?

Both EN and AR are wired by default through `@rahhal/i18n`. Add app-specific messages on top of the shared catalog. RTL flips automatically as long as you use Tailwind logical utilities (`ms-*`, `me-*`, `ps-*`, `pe-*`, `start-*`, `end-*`).

### How do I wire phone-OTP login?

Install `@rahhal/auth`, wrap your root in `<AuthProvider>`, gate authed routes with `<RequireSession>`, set the `SUPABASE_URL` / `SUPABASE_ANON_KEY` env vars. Use `requestPhoneOtp` + `verifyPhoneOtp` for the standalone flow; the iOS → web handover is automatic. Never import `@supabase/supabase-js` directly.

### How do I add or change a design token?

Edit `packages/themes/src/themes/{light,dark}.ts` (TypeScript is the source of truth — both themes must satisfy `ThemeTokens`), then run `pnpm --filter @rahhal/themes build` to regenerate `dist/tokens.css` and `dist/tokens.json`. Never edit the generated files by hand.

### When should I promote an app-local component into @rahhal/ui?

When the same wrapper recurs across two or more apps. Move source into `packages/ui/src/<component>.tsx`, add an `index.ts` export and a subpath in `package.json`, then add a catalog entry under `apps/design-system/src/catalog/entries/` and a meta row in `spec/components-meta.ts`.

### How do AI agents consume this design system?

Every catalog page has a Markdown counterpart at `/components/<slug>.md`, plus the umbrella `/skill.md`, plus `/why.md` and `/faq.md`. Agents fetch those URLs to read the same source of truth humans browse here.

### Where do mini-apps deploy?

Independently — each mini-app owns its own deploy config (`vercel.json`, `Dockerfile`, Cloudflare Pages, …). There is no centralized deploy. Subdomains roll up under `*.rahhal.app` so the platform reads as one product family even though deploys are independent.

### What if a component I need isn't in the catalog?

Build it locally first inside your app. If it stays self-contained you're done. If it starts being copied across apps, that's the signal to promote it into `@rahhal/ui` — see the promotion question above.


---

Source: https://marsam.rahhal.app/components/colors.md

# Colors & radius

Every design token from @rahhal/themes. Tokens are stored as HSL channels (so Tailwind opacity modifiers compose) AND surfaced as #RRGGBB hex for cross-platform consumers (iOS, Android, slides, Figma). Light + dark are the two themes; system preference is auto-detected on web.

## Cross-platform mapping

- **Web (consumer):** `hsl(var(--token))` — stays compatible with Tailwind opacity modifiers (`bg-primary/50`).
- **iOS / SwiftUI:** `Color(hex: "#RRGGBB")` — use the hex column for the active theme.
- **Android / Compose:** `Color(0xFFRRGGBB)` — uppercase the alpha + hex.
- **Slides / Figma / Print:** copy the hex value directly.

### Surfaces

Backgrounds for the canvas, cards, popovers, and quiet/loud emphasis regions.

| token | css var | tailwind | light hex | light hsl | dark hex | dark hsl |
| --- | --- | --- | --- | --- | --- | --- |
| `background` | `--background` | `bg-background` | #ffffff | 0 0% 100% | #000000 | 0 0% 0% |
| `card` | `--card` | `bg-card` | #f2f2f7 | 240 23.8% 95.9% | #1c1c1e | 240 3.4% 11.4% |
| `popover` | `--popover` | `bg-popover` | #ffffff | 0 0% 100% | #2c2c2e | 240 2.2% 17.6% |
| `muted` | `--muted` | `bg-muted` | #f2f2f7 | 240 23.8% 95.9% | #1c1c1e | 240 3.4% 11.4% |
| `accent` | `--accent` | `bg-accent` | #d9eef9 | 200.6 72.7% 91.4% | #0e2f3f | 199.6 63.6% 15.1% |

### Text on surface

Foreground colors paired with their surface counterparts.

| token | css var | tailwind | light hex | light hsl | dark hex | dark hsl |
| --- | --- | --- | --- | --- | --- | --- |
| `foreground` | `--foreground` | `bg-foreground` | #000000 | 0 0% 0% | #ffffff | 0 0% 100% |
| `cardForeground` | `--card-foreground` | `bg-card-foreground` | #000000 | 0 0% 0% | #ffffff | 0 0% 100% |
| `popoverForeground` | `--popover-foreground` | `bg-popover-foreground` | #000000 | 0 0% 0% | #ffffff | 0 0% 100% |
| `mutedForeground` | `--muted-foreground` | `bg-muted-foreground` | #6c6c70 | 240 1.8% 43.1% | #98989f | 240 3.5% 61% |
| `accentForeground` | `--accent-foreground` | `bg-accent-foreground` | #0a3344 | 197.6 74.4% 15.3% | #d6ecf7 | 200 67.3% 90.4% |

### Brand

Primary CTAs and the quieter secondary surface.

| token | css var | tailwind | light hex | light hsl | dark hex | dark hsl |
| --- | --- | --- | --- | --- | --- | --- |
| `primary` | `--primary` | `bg-primary` | #0095d5 | 198 100% 41.8% | #2aa8e8 | 200.2 80.5% 53.7% |
| `primaryForeground` | `--primary-foreground` | `bg-primary-foreground` | #ffffff | 0 0% 100% | #001722 | 199.4 100% 6.7% |
| `secondary` | `--secondary` | `bg-secondary` | #e5e5ea | 240 10.6% 90.8% | #2c2c2e | 240 2.2% 17.6% |
| `secondaryForeground` | `--secondary-foreground` | `bg-secondary-foreground` | #1c1c1e | 240 3.4% 11.4% | #ffffff | 0 0% 100% |

### State

Destructive surfaces for errors and irreversible actions.

| token | css var | tailwind | light hex | light hsl | dark hex | dark hsl |
| --- | --- | --- | --- | --- | --- | --- |
| `destructive` | `--destructive` | `bg-destructive` | #ff3b30 | 3.2 100% 59.4% | #ff453a | 3.4 100% 61.4% |
| `destructiveForeground` | `--destructive-foreground` | `bg-destructive-foreground` | #ffffff | 0 0% 100% | #ffffff | 0 0% 100% |

### Chrome

Borders, input outlines, and focus-rings.

| token | css var | tailwind | light hex | light hsl | dark hex | dark hsl |
| --- | --- | --- | --- | --- | --- | --- |
| `border` | `--border` | `bg-border` | #c6c6c8 | 240 1.8% 78% | #38383a | 240 1.8% 22.4% |
| `input` | `--input` | `bg-input` | #c6c6c8 | 240 1.8% 78% | #38383a | 240 1.8% 22.4% |
| `ring` | `--ring` | `bg-ring` | #0095d5 | 198 100% 41.8% | #2aa8e8 | 200.2 80.5% 53.7% |

### Radius

| token | css var | tailwind | value |
| --- | --- | --- | --- |
| `radius.sm` | `--radius-sm` | `rounded-sm` | 0.25rem |
| `radius.md` | `--radius-md` | `rounded-md` | 0.5rem |
| `radius.lg` | `--radius-lg` | `rounded-lg` | 0.75rem |
| `radius.xl` | `--radius-xl` | `rounded-xl` | 1rem |


---

Source: https://marsam.rahhal.app/components/typography.md

# Typography

Font families (sans · arabic · mono) with web stacks plus iOS/Android equivalents, type scale (rem + px), and weight ramp. Bilingual EN/AR samples live alongside each other.

## Font families

| token | tailwind | web stack | ios | android |
| --- | --- | --- | --- | --- |
| `fontFamily.sans` | `font-sans` | `ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif` | SF Pro (system) · use `-apple-system` | Roboto (Material 3 default) |
| `fontFamily.arabic` | `font-arabic` | `"IBM Plex Sans Arabic", "Noto Sans Arabic", "Segoe UI", Tahoma, sans-serif` | SF Arabic (built-in on iOS 16+) | Noto Sans Arabic |
| `fontFamily.mono` | `font-mono` | `ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace` | SF Mono | Roboto Mono |

## When to use

| family | use for |
| --- | --- |
| `sans` | Primary UI body and headings (English / Latin scripts). |
| `arabic` | Used automatically inside [dir="rtl"] regions; pair with logical Tailwind utilities. |
| `mono` | Code blocks, JSON snippets, anything monospaced. |

## Type scale

| tailwind | rem | px |
| --- | --- | --- |
| `text-xs` | 0.75rem | 12px |
| `text-sm` | 0.875rem | 14px |
| `text-base` | 1rem | 16px |
| `text-lg` | 1.125rem | 18px |
| `text-xl` | 1.25rem | 20px |
| `text-2xl` | 1.5rem | 24px |
| `text-3xl` | 1.875rem | 30px |
| `text-4xl` | 2.25rem | 36px |

## Weights

| tailwind | name | value |
| --- | --- | --- |
| `font-normal` | Normal | 400 |
| `font-medium` | Medium | 500 |
| `font-semibold` | Semibold | 600 |
| `font-bold` | Bold | 700 |

## RTL

The `arabic` family is applied automatically inside `[dir="rtl"]` regions on the web. On iOS / Android, use the system locale to switch between the latin (`SF Pro` / `Roboto`) and arabic (`SF Arabic` / `Noto Sans Arabic`) fonts.


---

Source: https://marsam.rahhal.app/components/icons.md

# Icons & brand marks

Download official Rahhal icons in PNG and SVG, with light and dark variants, React usage, and guidance for Lucide UI icons and social brand marks.

[View examples](https://marsam.rahhal.app/components/icons) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `/brand/app-icon-{light,dark,admin}.png · lucide-react · @rahhal/ui`

**Category:** `tokens`

## Download the Rahhal icon or logo

For a request such as "get the Rahhal icon", use the consumer light PNG below by default. The dark variant is also available. These are direct public files: no login, JavaScript, or image extraction is needed.

- [Rahhal icon (light PNG)](https://marsam.rahhal.app/brand/app-icon-light.png): Default consumer Rahhal app icon for light surfaces and general downloads.
- [Rahhal icon (dark PNG)](https://marsam.rahhal.app/brand/app-icon-dark.png): Consumer Rahhal app icon for dark surfaces and dark home screens.
- [Rahhal icon (light SVG)](https://marsam.rahhal.app/brand/app-icon-light.svg): Light SVG asset for browser favicons and clients that accept SVG files.
- [Rahhal icon (dark SVG)](https://marsam.rahhal.app/brand/app-icon-dark.svg): Dark SVG asset for browser favicons and clients that accept SVG files.
- [Rahhal admin icon](https://marsam.rahhal.app/brand/app-icon-admin.png): Distinct icon reserved for internal admin and debug applications.
- [Apple touch icon](https://marsam.rahhal.app/brand/apple-touch-icon.png): 180 by 180 pixel PNG for Apple touch icons.
- [PWA icon (192px)](https://marsam.rahhal.app/brand/icon-192.png): 192 by 192 pixel PNG for web app manifests.
- [PWA icon (512px)](https://marsam.rahhal.app/brand/icon-512.png): 512 by 512 pixel PNG for web app manifests.
- [Maskable PWA icon](https://marsam.rahhal.app/brand/icon-512-maskable.png): 512 by 512 pixel maskable PNG for adaptive launcher shapes.

The served URL starts with /brand/, never /public/brand/. Source assets live in packages/seo/assets/ and are published by @rahhal/seo.

## React usage

```tsx
import { RahhalIcon } from "@rahhal/ui/rahhal-icon";

<RahhalIcon
  icon="url:https://marsam.rahhal.app/brand/app-icon-light.png"
  size={48}
  alt="Rahhal"
/>
```

```html
<img src="https://marsam.rahhal.app/brand/app-icon-light.png" width="48" height="48" alt="Rahhal" />
```

RahhalIcon is a renderer for catalog values, not a bundled Rahhal logo: pass an explicit image URL. Lucide Compass is a general UI icon, not the official downloadable Rahhal app icon.


## Social brand marks

Import from `@rahhal/ui` (not `lucide-react` — Lucide deprecated its brand icons and will remove them in v1.0). Each component is a `forwardRef<SVGSVGElement>`, fills with `currentColor`, and accepts any `SVGProps`:

| component | use |
| --- | --- |
| GithubIcon | GitHub source / org links |
| LinkedinIcon | LinkedIn company page |
| XIcon | X (formerly Twitter) |
| InstagramIcon | Instagram profile |

## UI iconography (Lucide)

Import any of the ~1,500 icons from `lucide-react`. Common picks for travel / settings UIs:

| icon | purpose |
| --- | --- |
| Compass | general navigation (not the Rahhal logo) |
| Map · MapPin | location, place markers |
| Search | search affordances |
| Heart · Star | favorites, ratings |
| Bell | notifications |
| CalendarDays | date / schedule |
| Globe | language / locale |
| Home · User · Settings | tab-bar / profile |
| Shield | auth / privacy |

## Sizing convention

| class | context |
| --- | --- |
| h-4 w-4 | inline UI (alongside text) |
| h-5 w-5 | tappable buttons (header chrome, list trailing) |
| h-6 w-6 | primary navigation (tab bars) |
| h-8 w-8 | hero / empty-state illustrations |


---

Source: https://marsam.rahhal.app/components/rahhal-icon.md

# RahhalIcon

Cross-platform icon renderer. Parses the same prefixed catalog strings the iOS shell understands (`url:…`, `emoji:…`, `system:…`, `resource:…`, plus bare URLs/emojis) so a CMS-authored value paints identically on every client. Falls back to a muted square when the value is empty; `system:` and `resource:` render as debug tokens on the web because there's no SF Symbols / iOS bundle equivalent.

[View examples](https://marsam.rahhal.app/components/rahhal-icon) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/rahhal-icon`

**Category:** `tokens`

## Render the Rahhal brand icon

Use the [official Rahhal icon assets](https://marsam.rahhal.app/components/icons.md) when the request is for the Rahhal logo or app icon. This component renders a supplied icon value; it does not contain the logo by default.

```tsx
import { RahhalIcon } from "@rahhal/ui/rahhal-icon";

<RahhalIcon icon="url:https://marsam.rahhal.app/brand/app-icon-light.png" size={48} alt="Rahhal" />
```

Pass the dark asset URL for dark surfaces. Theme selection is the caller's responsibility.



---

Source: https://marsam.rahhal.app/components/button.md

# Button

Primary actionable element. Six variants and four sizes. Use `asChild` to keep button styling on a router-aware link.

[View examples](https://marsam.rahhal.app/components/button) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/button`

**Category:** `actions`

## Variants

| variant | purpose |
| --- | --- |
| default | primary CTA |
| destructive | irreversible / dangerous |
| outline | secondary action with border |
| secondary | muted secondary surface |
| ghost | low-emphasis (toolbar, icon button) |
| link | inline link styled as a button |

## Sizes

Fully-rounded capsules. Default height meets Apple's 44pt touch target.

| size | height |
| --- | --- |
| sm | 2.25rem / 36px |
| default | 2.75rem / 44px |
| lg | 3rem / 48px |
| icon | 2.75rem square |

## Patterns

- Pass `asChild` to render a router-aware `<Link>` with button styling.
- Place icons via children; use `size="icon"` for icon-only buttons (always set `aria-label`).
- Default and destructive variants get a soft tinted shadow that lifts on hover — matches Apple Prominent buttons.


---

Source: https://marsam.rahhal.app/components/toggle.md

# Toggle · ToggleGroup

On/off button (`<Toggle>`) and grouped toggle sets (`<ToggleGroup>`). Use for formatting toolbars, view-mode switches, and any compact two-state control. `ToggleGroup` accepts `type="single"` for radio-style behavior or `type="multiple"` for checkbox-style.

[View examples](https://marsam.rahhal.app/components/toggle) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/toggle · @rahhal/ui/toggle-group`

**Category:** `actions`


---

Source: https://marsam.rahhal.app/components/back-button.md

# BackButton

Small ghost capsule with a leading chevron — the standard 'go back' affordance for nested pages. Defaults to `window.history.back()`; pass `onClick` to plug in router-aware navigation. The chevron rotates automatically under RTL.

[View examples](https://marsam.rahhal.app/components/back-button) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/back-button`

**Category:** `actions`

## Behavior

- Default click handler: `window.history.back()` — works without a router.
- Override with `onClick` for router-aware navigation, e.g. `useNavigate()(-1)` (react-router) or `router.back()` (next/navigation).
- The chevron auto-flips under RTL via `rtl:rotate-180`; layout uses logical Tailwind utilities.

## Props

| prop | type | purpose |
| --- | --- | --- |
| label | ReactNode | label rendered next to the chevron · default "Back" |
| onClick | (e) => void | override default history.back() behavior |
| variant | Button variant | default "ghost" · "outline" for busy backgrounds |
| size | Button size | default "sm" |


---

Source: https://marsam.rahhal.app/components/paste-button.md

# PasteButton

Icon button that reads the system clipboard and forwards the text to a callback. Defaults to a clipboard glyph; pair with a string-transform helper at the call site (URL extractor, code parser, normaliser).

[View examples](https://marsam.rahhal.app/components/paste-button) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/paste-button`

**Category:** `actions`

## Behavior

- Calls `navigator.clipboard.readText()` on click and forwards the text to `onPaste`.
- Returns silently when the read succeeds. On failure, fires `onError` if provided, otherwise shows `errorMessage` via the global `<Toaster />` (must be mounted at app root).
- Wraps `<Button>` and accepts every `<Button>` prop (`size`, `variant`, `disabled`, `className`, `ref`, …) via spread. Defaults: `size="icon"`, `variant="ghost"`.
- Icon defaults to lucide-react's `<Clipboard>`. Override with `children`.
- The component shadows React's native `onPaste` clipboard event handler — `onPaste` here receives the clipboard string, not a `ClipboardEvent`.

## Props

| prop | type | purpose |
| --- | --- | --- |
| onPaste | (text: string) => void | fires with raw clipboard text on success (required) |
| aria-label | string | screen-reader label (required — icon has no visible text) |
| errorMessage | string | toast text on clipboard-read failure |
| onError | (err: unknown) => void | custom error handler — overrides errorMessage |
| size | Button size | passthrough; defaults to "icon" |
| variant | Button variant | passthrough; defaults to "ghost" |
| children | ReactNode | override default <Clipboard /> glyph |

## Patterns

- **Inside an input** — wrap input + button in `relative`, give the input `pe-11` to reserve room, anchor the button with `absolute end-1 top-1/2 -translate-y-1/2`. Logical `end-*` flips correctly under RTL.
- **Standalone** — pass `size="sm"` with `variant="outline"` and a visible `children` label.
- **Failures are common** on iOS Safari without an explicit user gesture, on insecure (non-HTTPS) origins, and in private-browsing modes. Always pass `errorMessage` (or `onError`) so the user knows to fall back to manual paste.

## Related

- See `<SearchBar>` for the canonical "trailing icon inside an input" composition; `PasteButton` drops into that same slot.


---

Source: https://marsam.rahhal.app/components/input.md

# Input & Textarea

Native `<input>` and `<textarea>` wrappers themed via design tokens. Pair with `<Label htmlFor>` for accessible click-the-text targets.

[View examples](https://marsam.rahhal.app/components/input) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/input · @rahhal/ui/textarea · @rahhal/ui/label`

**Category:** `forms`


---

Source: https://marsam.rahhal.app/components/search-bar.md

# SearchBar

Capsule-shaped search input with leading magnifier, optional clear button, optional trailing slot (e.g. ⌘K hint), and Enter-to-submit. Wrapped in `<form role="search">` so iOS shows the on-screen "Search" key. Inputs are normally rectangular in this design system — search is the one intentional capsule exception, matching Apple's HIG.

[View examples](https://marsam.rahhal.app/components/search-bar) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/search-bar`

**Category:** `forms`

## Sizes

| size | height |
| --- | --- |
| sm | 2.25rem / 36px (compact toolbars) |
| md (default) | 2.75rem / 44px (matches Button default) |
| lg | 3rem / 48px (hero search) |

## Props

| prop | type | purpose |
| --- | --- | --- |
| value / onChange | controlled | standard React input pattern |
| onClear | () => void | renders a trailing × button when value is non-empty |
| onSubmit | (value: string) => void | fires on Enter or form submit |
| trailing | ReactNode | custom trailing content (⌘K hint, voice button, …) |
| size | sm | md | lg | visual size; default md |


---

Source: https://marsam.rahhal.app/components/filter-chip.md

# FilterChip

Toggleable filter pill. Two interaction modes that compose: `active`+`onToggle` for multi-select category chips, `onRemove` for "applied filter" chips that show what's currently filtering the list. Optional `leading` icon and `count` badge.

[View examples](https://marsam.rahhal.app/components/filter-chip) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/filter-chip`

**Category:** `forms`

## Anatomy

| part | role |
| --- | --- |
| FilterChipGroup | wraps chips with consistent gap + wrapping |
| FilterChip | single pill — toggle and/or removable |

## Props

| prop | type | purpose |
| --- | --- | --- |
| active | boolean | selected state — drives filled vs outlined |
| onToggle | (next: boolean) => void | fired on click |
| onRemove | () => void | renders × dismiss when provided |
| leading | ReactNode | small leading icon (12–14px) |
| count | number | small badge appended after the label |
| size | sm | md | default md (32px) |

## When to use vs Tabs

- **Tabs / segmented control** — 2–3 mutually-exclusive parallel views.
- **FilterChip** — 3+ values, multi-select, variable count, or filters that can be cleared individually.


---

Source: https://marsam.rahhal.app/components/file-dropzone.md

# FileDropzone

Drop-or-browse file picker with native HTML5 drag-and-drop, click-to-select fallback, and built-in `accept` / `maxSize` / `maxFiles` validation. Always controlled — the parent owns the file list. RTL-safe via logical Tailwind utilities.

[View examples](https://marsam.rahhal.app/components/file-dropzone) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/file-dropzone`

**Category:** `forms`

## Behavior

- The whole surface is a focusable `<button>` that opens the hidden `<input type="file">`. Drop, click, and Enter / Space all work.
- `accept`, `maxSize`, and `maxFiles` are enforced **before** files reach `onChange`. Rejected files are surfaced via `onReject` so the caller can render a toast or inline error.
- Always controlled — pass `value` (`File[]`) and `onChange`. The component never holds its own file state because real upload flows always need the parent to track progress and submission.
- Removing a file via the row's × button calls `onChange` with the file removed.
- Layout uses logical utilities (`text-start`, `me-*`) so the file list mirrors correctly under `[dir="rtl"]`.

## Props

| prop | type | purpose |
| --- | --- | --- |
| value | File[] | controlled file list (required) |
| onChange | (next: File[]) => void | fires on drop / pick / remove (required) |
| accept | string | native accept pattern, e.g. "image/*,.pdf" |
| multiple | boolean | default true — set false for single-file pickers |
| maxFiles | number | hard cap on total accepted files |
| maxSize | number | per-file size cap in bytes |
| disabled | boolean | disables drop / browse / remove |
| onReject | (rejections) => void | fired when files fail accept / size / max-files |
| title / description | ReactNode | override the empty-state copy |
| icon | ReactNode | override the cloud-upload glyph |
| id / name | string | wire up `<Label htmlFor>` and form posting |

## Helpers

- `formatFileSize(bytes)` — pretty-prints byte counts (`1.4 MB`).
- `type FileRejection = { file: File; reason: "type" | "size" | "max-files" }`.

## Patterns

- For images, set `accept="image/*"` and validate dimensions in your own `onChange`.
- For single-file flows, set `multiple={false}`. Re-picking replaces the prior file rather than appending.
- The component does **not** upload — wire `onChange` into your existing upload pipeline (Supabase Storage, S3 presigned URL, fetch, …).


---

Source: https://marsam.rahhal.app/components/switch-and-toggles.md

# Switch · Checkbox · Radio

Boolean and small-set selectors. `<Switch>` for on/off settings, `<Checkbox>` for individual toggles, `<RadioGroup>` for mutually-exclusive choices.

[View examples](https://marsam.rahhal.app/components/switch-and-toggles) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/switch · @rahhal/ui/checkbox · @rahhal/ui/radio-group`

**Category:** `forms`


---

Source: https://marsam.rahhal.app/components/slider.md

# Slider

Value picker with a draggable thumb. Built on Radix Slider. Pass a single-element array for a normal slider or a two-element array for a range slider.

[View examples](https://marsam.rahhal.app/components/slider) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/slider`

**Category:** `forms`


---

Source: https://marsam.rahhal.app/components/combobox.md

# Combobox

Searchable single-select picker. Composes `<Popover>` + `<Command>` + `<Button>` into the canonical shadcn pattern. Use for country / city / airport / category pickers where `<Select>` becomes unwieldy past ~10 options.

[View examples](https://marsam.rahhal.app/components/combobox) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/combobox`

**Category:** `forms`

## Behavior

- Always controlled — pass `value` (string) and `onChange`.
- The dropdown filters as the user types via cmdk. By default the filter runs against the option's `label` (when it's a string) or its `value`. Pass `searchValue` per option to override — useful for bilingual lookups (`"Saudi Arabia السعودية"`).
- Selecting the already-selected option clears the value (returns `undefined` to `onChange`).

## Props

| prop | type | purpose |
| --- | --- | --- |
| value | string | undefined | currently-selected option value |
| onChange | (next | undefined) => void | fires on pick / clear |
| options | ComboboxOption[] | available options (required) |
| placeholder | ReactNode | shown on the trigger when no value |
| searchPlaceholder | string | placeholder inside the search input |
| emptyMessage | ReactNode | shown when filter matches nothing |
| width | string (Tailwind) | applied to trigger and content; default `w-[240px]` |
| disabled | boolean | disables the trigger |

## Patterns

- Always treat `value` as a tag, not a label — the option's `label` is presentational and may include localized text.
- For multi-select, build with `<Command>` + `<Popover>` directly; this single-select wrapper intentionally returns the simpler API.


---

Source: https://marsam.rahhal.app/components/date-picker.md

# Calendar & DatePicker

Themed `<Calendar>` (react-day-picker) plus the canonical `<DatePicker>` recipe (Calendar inside a Popover). Single date and range modes share the same trigger.

[View examples](https://marsam.rahhal.app/components/date-picker) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/calendar · @rahhal/ui/date-picker`

**Category:** `forms`

## Components

| component | purpose |
| --- | --- |
| Calendar | themed react-day-picker grid; render inline or inside any Popover |
| DatePicker | Calendar in a Popover triggered by a button — the recipe most apps actually want |

## DatePicker modes

| mode | value type | use when |
| --- | --- | --- |
| single (default) | Date | pick one date (birthday, deadline) |
| range | { from, to } | pick a window (trip dates, hotel stay) |

## Props (DatePicker)

| prop | type | purpose |
| --- | --- | --- |
| mode | \"single\" | \"range\" | default `single` |
| value | Date | DateRange | controlled value |
| onChange | (next) => void | fires on selection |
| disabled | Matcher | Matcher[] | disable individual days (e.g. weekends) |
| locale | string | BCP-47 locale for the formatted button label |
| buttonVariant / buttonSize | Button props | trigger styling |

## RTL

react-day-picker mirrors the day grid automatically when `<html dir="rtl">` is set. The chevrons in the calendar nav and the trigger button rotate via `rtl:rotate-180` so they always point in the reading direction.


---

Source: https://marsam.rahhal.app/components/form.md

# Form (react-hook-form)

Validated form composition built on react-hook-form. `<FormField>` wires a controller into descendant `<FormLabel>` / `<FormControl>` / `<FormDescription>` / `<FormMessage>` parts via shared aria attributes — labels point to inputs, errors are announced, and focus rings show on the right element automatically.

[View examples](https://marsam.rahhal.app/components/form) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/form`

**Category:** `forms`

## Pieces

| part | role |
| --- | --- |
| Form | re-export of react-hook-form's `<FormProvider>`; spread `useForm()` methods into it |
| FormField | Controller wrapper that exposes `name` to descendants |
| FormItem | vertical stack for one field group |
| FormLabel | themed label — turns destructive on validation error |
| FormControl | Slot that wires `id` / `aria-describedby` / `aria-invalid` onto the input |
| FormDescription | subdued helper text below the control |
| FormMessage | renders the field's validation error (or any children if no error) |
| useFormField() | hook for advanced custom parts |

## Pattern

```tsx
const form = useForm<Values>({ defaultValues: { email: "" } });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <FormField
      name="email"
      control={form.control}
      rules={{ required: "Required" }}
      render={({ field }) => (
        <FormItem>
          <FormLabel>Email</FormLabel>
          <FormControl><Input {...field} /></FormControl>
          <FormMessage />
        </FormItem>
      )}
    />
  </form>
</Form>
```

## Notes

- The package treats `react-hook-form` as an **optional peer dependency** — add it to apps that use `<Form>`. Apps that don't won't pull it in.
- For schema-based validation, plug `@hookform/resolvers/zod` (or yup) into `useForm({ resolver })`. The components don't care which validator runs.


---

Source: https://marsam.rahhal.app/components/section.md

# Section

Page-section building block: header (title + description + optional action), spacing rhythm, and footer slot. Pairs with `Card`, `List`, or `Table` for the surface; `Section` only handles labeling and rhythm so layouts stay uniform.

[View examples](https://marsam.rahhal.app/components/section) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/section`

**Category:** `surfaces`

## Anatomy

| part | role |
| --- | --- |
| Section | outer `<section>` flex column |
| SectionHeader | title row with optional `action` slot |
| SectionTitle | h2 — short label |
| SectionDescription | muted sub-label |
| SectionContent | main content (no surface) |
| SectionFooter | small print / metadata row |

## Spacing

The `spacing` prop controls vertical gap between header / content / footer:

| spacing | gap |
| --- | --- |
| compact | 0.5rem / 8px |
| default | 0.75rem / 12px |
| spacious | 1.25rem / 20px |


---

Source: https://marsam.rahhal.app/components/card.md

# Card

Surface container for grouped content. Compose with `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`.

[View examples](https://marsam.rahhal.app/components/card) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/card`

**Category:** `surfaces`


---

Source: https://marsam.rahhal.app/components/list.md

# List

Apple-style inset grouped list with section headers/footers. Each `ListGroup` is a rounded card; rows separate with hairline dividers. `variant="plain"` flattens the chrome for embedding inside another card. Mirrors the iOS Settings UX.

[View examples](https://marsam.rahhal.app/components/list) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/list`

**Category:** `surfaces`

## Anatomy

| part | role |
| --- | --- |
| List | outer container (variant: grouped | plain) |
| ListGroup | one section — renders as a rounded card in `grouped` mode |
| ListGroupHeader | uppercase label above a group |
| ListGroupFooter | muted helper text below a group |
| ListItem | one row: leading + title/description + trailing |

## ListItem props

| prop | type | purpose |
| --- | --- | --- |
| leading | ReactNode | icon or avatar in a 2rem square slot |
| title | ReactNode | primary label, single-line truncated |
| description | ReactNode | secondary label, single-line truncated |
| trailing | ReactNode | value, chevron, switch, or pill |
| destructive | boolean | renders title in destructive color |
| interactive | boolean | adds hover/active states |
| asChild | boolean | render as button/link instead of div |

## When to use what

- **List** — settings, profile screens, any single-column grouped data.
- **Table** — multi-column tabular data (invoices, comparisons, schedules).
- **Card + Section** — featured content with a heading + body that doesn't repeat.


---

Source: https://marsam.rahhal.app/components/place-card.md

# PlaceCard

Compact, mobile-first card for a single geographic place. Name, optional address, and the coordinate readout stack vertically and truncate — never scroll horizontally. The title is adaptive (name → address → coordinates) so a nameless waypoint still renders. Pass an `<Input/>` as `name` for inline editing; use `leading`/`trailing` slots for an icon and a checkbox/switch.

[View examples](https://marsam.rahhal.app/components/place-card) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/place-card`

**Category:** `surfaces`

## Behavior

- **Adaptive title** — renders `name`; if falsy, falls back to `address`, then to the formatted coordinates, so the card is never blank.
- The coordinate readout is pinned to `dir="ltr"` so `lat, lng` reads left-to-right even under RTL; everything else mirrors via logical utilities.
- Pass a node (e.g. an `<Input/>`) as `name` to edit the title inline — the coordinates below double as a hint for unnamed points.

## Props

| prop | type | purpose |
| --- | --- | --- |
| name | ReactNode | primary label · falsy falls back to address, then coordinates · pass an <Input/> to edit inline |
| address | ReactNode | secondary location line |
| latitude / longitude | number | decimal degrees (required) |
| elevation | number | null | shown after the coordinates when set |
| leading | ReactNode | icon/avatar slot · defaults to a map-pin |
| trailing | ReactNode | checkbox / switch / chevron at the end |
| badges | ReactNode | chips beneath the coordinates (e.g. a source tag) |
| selected | boolean | primary ring highlight |
| muted | boolean | dim the card (e.g. an excluded row) |
| interactive | boolean | hover/active/focus affordances + role=button |
| coordinatePrecision | number | decimals in the coordinate readout · default 5 |
| hideCoordinates | boolean | omit the coordinate line |

## When to use what

- **PlaceCard** — a location in a vertical list (import review, saved places, search results) on mobile.
- **ListItem** — a generic settings-style row with no coordinates.
- **Table** — dense multi-column data where horizontal scroll is acceptable.


---

Source: https://marsam.rahhal.app/components/map.md

# Map

Declarative wrapper around MapLibre GL JS. Compose `MapMarker`, `MapPolyline`, `MapPolygon`, `MapCircle`, and `MapCluster` as children — geometry inherits the platform's blue primary by default. Free OpenFreeMap tiles light/dark; switch via the `style` prop. RTL Arabic labels render correctly out of the box.

[View examples](https://marsam.rahhal.app/components/map) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui (Map, MapMarker, MapPolyline, MapPolygon, MapCircle, MapCluster)`

**Category:** `surfaces`

## Setup

Install once at the consuming app's entry point:

```ts
// main.tsx / app/layout.tsx
import "maplibre-gl/dist/maplibre-gl.css";
```

## Components

| component | purpose |
| --- | --- |
| Map | root container; manages MapLibre instance lifecycle and exposes context |
| MapMarker | pin annotation with optional label + popup |
| MapPolyline | ordered line (route, path) |
| MapPolygon | filled, stroked area (neighborhood, region) |
| MapCircle | geographic radius circle ("within N km") |
| MapCluster | clustered point source — circles for groups, singles for stragglers, click-to-expand |
| useMap | hook for custom children that need raw MapLibre access |

## Coordinate convention

All positions are `[longitude, latitude]` — the GeoJSON / MapLibre convention. **Longitude first.** This trips up engineers used to Apple's CLLocationCoordinate2D (`latitude, longitude`); the order is reversed on web.

## MapMarker props

| prop | type | purpose |
| --- | --- | --- |
| lngLat | [number, number] | position as `[longitude, latitude]` (required) |
| label | string | accessible label · rendered as both `aria-label` and `title` tooltip |
| color | string | marker fill; defaults to the theme's `--primary` |
| popup | ReactNode | popup content shown on click — only string/number render rich; richer trees fall back to the label |
| anchor | MapLibre anchor | default `"bottom"` so the pin tip sits on the coordinate |
| element | HTMLElement | custom DOM to use instead of the default pin (e.g. an emoji bubble) |
| glyph | string | render the marker as a circular sticker pin with this glyph (emoji) centered, instead of MapLibre's default teardrop. Combines with `color` for the border tint, so the existing `color={selected ? accent : …}` selection pattern keeps working |
| onClick | () => void | fires when the user taps/clicks the marker · sets `cursor: pointer` automatically |

## Clustering

Wrap your `<Map>` with a `<MapCluster>` child when you have many points (hundreds+) and want them aggregated as zoom decreases — the canonical [MapLibre clustering pattern](https://maplibre.org/maplibre-gl-js/docs/examples/create-and-style-clusters/). Cluster circles auto-expand on click, single points fire `onPointClick`.

| prop | type | purpose |
| --- | --- | --- |
| points | MapClusterPoint[] | array of `{ lngLat, id?, properties? }` features to cluster (required). A point's `id` is forwarded to the GeoJSON feature id only when it's a number — string ids (e.g. UUIDs) break MapLibre's clustering and render nothing, so keep string identity on `properties` and read it back in `onPointClick` |
| clusterMaxZoom | number | max zoom at which clustering is active. default 14 |
| clusterRadius | number | KD-tree pixel radius used to group points. default 50 |
| color | string | cluster circle fill; defaults to the theme's `--primary` |
| countTextColor | string | color of the count label drawn on each cluster. default `#ffffff` |
| pointColor | string | fill for unclustered (single) points; defaults to the theme's `--primary` |
| pointRadius | number | radius (px) of unclustered points. default 8 |
| pointStrokeColor | string | stroke color of unclustered points. default `#ffffff` |
| pointStrokeWidth | number | stroke width (px) of unclustered points. default 2 |
| onPointClick | (properties, lngLat) => void | fires when an unclustered point is clicked · cursor flips to pointer over clusters and singles |

Cluster count labels render in the basemap's font (`Noto Sans Regular`, available in the default OpenFreeMap styles). Like other geometry layers, `MapCluster` re-adds its source + layers automatically when the basemap style changes (theme switch).

## Controls

| prop | type | purpose |
| --- | --- | --- |
| showNavigation | boolean | zoom + compass control (top-end). default true |
| showLocateControl | boolean | "locate me" control wrapping MapLibre's `GeolocateControl`. requires HTTPS or localhost; renders disabled if the user denies permission. default false |
| interactive | boolean | enable drag/zoom; set false for static thumbnails. default true |

## Theme & tiles

- Default tiles come from OpenFreeMap (`tiles.openfreemap.org`) — free, no API key, light + dark variants.
- Pass `style` (URL or full `StyleSpecification`) to use MapTiler / Mapbox / a self-hosted style instead.
- Default geometry colors read from the `--primary` CSS variable so maps tonally match the rest of the UI.

## RTL

MapLibre's RTL text plugin is registered automatically on first `<Map>` mount, so Arabic place names render with correct shaping. No per-app wiring needed.

## Cross-platform

This is the **web** component. The native Rahhal apps render maps with iOS MapKit / Android Maps SDK; prop names here intentionally mirror those native concepts (`lngLat`, `zoom`, `pitch`, `bearing`) so designers can speak about either side without translation.


---

Source: https://marsam.rahhal.app/components/kanban.md

# Kanban board

Column-based task board layout primitive. Provides board frame, columns (title / count / accent / action), and cards (title / description / leading / trailing / meta). Layout only — apps wire drag-and-drop with their own DnD library (e.g. `@dnd-kit/core`). On small screens columns snap-scroll horizontally so swipes feel native.

[View examples](https://marsam.rahhal.app/components/kanban) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/kanban`

**Category:** `surfaces`

## Anatomy

| part | role |
| --- | --- |
| Kanban | outer flex row with horizontal snap-scroll |
| KanbanColumn | one column — sticky header + scrolling card list + footer |
| KanbanColumnAddButton | pre-styled "+" trigger for the column action slot |
| KanbanCard | single card — title + description + leading + trailing + meta row |

## KanbanColumn props

| prop | type | purpose |
| --- | --- | --- |
| title | ReactNode | column heading |
| count | number | small badge next to the title |
| accent | string (Tailwind class) | header dot color, e.g. "bg-emerald-500" |
| action | ReactNode | trailing slot (typically the add button) |
| footer | ReactNode | below the cards |

## Adding drag-and-drop

This package ships layout only. Wire DnD with [`@dnd-kit/core`](https://dndkit.com/) (recommended — same library Apple's developer docs use in their React samples). Wrap each `<KanbanCard>` in `<Sortable>` and each `<KanbanColumn>` in `<Droppable>`. Persistence and optimistic state belong in app code, not in this package.


---

Source: https://marsam.rahhal.app/components/carousel.md

# Carousel

Horizontal (or vertical) scroller built on Embla Carousel. Used for photo galleries, onboarding card stacks, and any "swipe through a row" UX. Detects `[dir="rtl"]` automatically and forwards the right axis direction to Embla.

[View examples](https://marsam.rahhal.app/components/carousel) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/carousel`

**Category:** `surfaces`

## Pieces

| part | role |
| --- | --- |
| Carousel | root — owns the Embla instance and provides context |
| CarouselContent | scrolling viewport |
| CarouselItem | single slide; defaults to `basis-full` — override with `basis-1/2`, `basis-1/3` for multi-up rows |
| CarouselPrevious | previous-slide chevron button |
| CarouselNext | next-slide chevron button |

## Common props (root)

| prop | type | purpose |
| --- | --- | --- |
| opts | Embla options | loop / align / dragFree / etc. |
| plugins | Embla plugins | autoplay, class names, etc. |
| orientation | \"horizontal\" | \"vertical\" | axis |
| setApi | (api) => void | receive the Embla API for external controls |

## Patterns

- For autoplay, install `embla-carousel-autoplay` and pass it via `plugins`.
- For pagination dots, subscribe to `api.on("select", …)` via `setApi` and render your own indicator.


---

Source: https://marsam.rahhal.app/components/collapsible.md

# Collapsible

Minimal disclosure primitive (one toggle, one panel). Re-exports of Radix Collapsible. For multiple sections, use `<Accordion>` instead.

[View examples](https://marsam.rahhal.app/components/collapsible) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/collapsible`

**Category:** `surfaces`


---

Source: https://marsam.rahhal.app/components/primitives.md

# Layout primitives

`<AspectRatio>` (lock a media ratio), `<ScrollArea>` (themed custom scrollbar), and `<Separator>` (semantic divider). Three small but essential primitives shipped in one catalog page.

[View examples](https://marsam.rahhal.app/components/primitives) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/aspect-ratio · @rahhal/ui/scroll-area · @rahhal/ui/separator`

**Category:** `surfaces`

## Components

| component | purpose |
| --- | --- |
| AspectRatio | wrap a child to lock its aspect ratio (`16/9`, `4/3`, `1`) |
| ScrollArea | themed custom scrollbar — the same chrome the sidebar uses |
| Separator | semantic divider, horizontal or vertical; pass `decorative={false}` when the gap carries meaning |

## Notes

- `<AspectRatio>` and `<ScrollArea>` come from Radix; `<Separator>` does too. Re-exporting them keeps consumers on a single `@rahhal/ui` import surface.
- Vertical `<ScrollArea>` uses a logical `border-s` so the scrollbar sits on the **end** edge in LTR (right) and **start** edge in RTL (left) — matching the reading direction.


---

Source: https://marsam.rahhal.app/components/table.md

# Table

Themed `<table>` family wrapped in a rounded card surface. Use for tabular data with multiple columns. For settings-style single-column lists, use `List` instead.

[View examples](https://marsam.rahhal.app/components/table) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/table`

**Category:** `surfaces`

## Anatomy

| part | wraps |
| --- | --- |
| Table | rounded card + horizontal scroll |
| TableHeader | thead with muted band |
| TableBody | tbody with hairline row dividers |
| TableFooter | tfoot for totals / summaries |
| TableRow | tr with hover + selected states |
| TableHead | th — uses logical `text-start` |
| TableCell | td — uses logical alignment |
| TableCaption | caption rendered below the table |

## Notes

- Numbers should use `tabular-nums` and align to the end edge: `className="text-end font-mono tabular-nums"`.
- For status pills inside cells, use `<Badge>` from `@rahhal/ui/badge`.
- Logical text alignment (`text-start`/`text-end`) means columns flip correctly under RTL automatically.


---

Source: https://marsam.rahhal.app/components/badge.md

# Badge

Inline label for status, counts, tags. Variants: default / secondary / destructive / outline.

[View examples](https://marsam.rahhal.app/components/badge) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/badge`

**Category:** `feedback`


---

Source: https://marsam.rahhal.app/components/avatar-and-skeleton.md

# Avatar · Skeleton · Progress

Compact identity + loading-state primitives.

[View examples](https://marsam.rahhal.app/components/avatar-and-skeleton) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/avatar · @rahhal/ui/skeleton · @rahhal/ui/progress`

**Category:** `feedback`


---

Source: https://marsam.rahhal.app/components/alert.md

# Alert

Inline status callout. Pair with a leading icon for instant recognition.

[View examples](https://marsam.rahhal.app/components/alert) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/alert`

**Category:** `feedback`

## Variants

| variant | purpose |
| --- | --- |
| default | informational |
| destructive | error / failure |

## Anatomy

- Leading icon (svg child) — auto-positioned to the start edge, RTL-safe.
- `<AlertTitle>` — short headline.
- `<AlertDescription>` — body text.


---

Source: https://marsam.rahhal.app/components/callout.md

# Callout

Inline note / hint / warning / important block. Lighter than an Alert — used inside page bodies for disclaimers, agent-targeted hints, deprecation notes, and similar asides.

[View examples](https://marsam.rahhal.app/components/callout) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/callout`

**Category:** `feedback`

## Variants

| variant | purpose |
| --- | --- |
| note (default) | neutral aside / disclaimer |
| hint | tip / agent-targeted nudge |
| warning | soft caution — not an action failure |
| important | must-read constraint or breaking change |

## Props

| prop | type | purpose |
| --- | --- | --- |
| variant | note | hint | warning | important | color + tone |
| label | ReactNode | leading badge text — pass null to omit |
| labelVariant | Badge variant | override auto-picked badge style |
| icon | ReactNode | optional leading icon before the label |

## When to use

Use `Callout` for asides *inside* page bodies (docs, settings, catalog hints). Use `Alert` for status *of an action* (success, failure). Use `Toast` for transient feedback. The three are intentionally separate.


---

Source: https://marsam.rahhal.app/components/rating.md

# Rating

Star rating control with read-only display + interactive input modes. Half-star increments by default, keyboard support (Arrow / Home / End), and an `aria-label` describing the current value. Always renders LTR so 1-star sits at the start edge in both reading directions.

[View examples](https://marsam.rahhal.app/components/rating) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/rating`

**Category:** `feedback`

## Modes

- **Read-only** (default when `onChange` is omitted, or when `readOnly`): `role="img"`, no keyboard interaction.
- **Interactive**: `role="slider"`, focusable, supports Arrow / Home / End keys plus mouse hover preview.

## Props

| prop | type | purpose |
| --- | --- | --- |
| value | number | current rating (0..max) |
| max | number | default 5 |
| step | 0.5 | 1 | smallest increment; default 0.5 for half-stars |
| onChange | (next) => void | fires on click / keyboard |
| readOnly | boolean | force display-only mode |
| size | sm | md | lg | star size |
| label | ReactNode | optional trailing label (`"4.6 / 5"`) |


---

Source: https://marsam.rahhal.app/components/empty-state.md

# EmptyState

Recurring "nothing here yet" surface. Drop into any list, table, or section that can be empty — icon, title, description, and an optional action keep the spacing rhythm consistent across mini-apps.

[View examples](https://marsam.rahhal.app/components/empty-state) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/empty-state`

**Category:** `feedback`

## Props

| prop | type | purpose |
| --- | --- | --- |
| icon | ReactNode | rendered in a 2.75rem rounded tile (any 20–24px icon) |
| title | ReactNode | headline — short noun phrase |
| description | ReactNode | one sentence explaining what unblocks the empty state |
| action | ReactNode | trailing button(s) |
| size | sm | md | lg | vertical density |

## Patterns

- Keep titles **descriptive**, not apologetic: "No saved places yet" beats "Oops, nothing here".
- The action should be the single highest-leverage step the user can take to fill the state — not a generic "refresh".


---

Source: https://marsam.rahhal.app/components/toaster.md

# Toaster (sonner)

One `<Toaster />` mount + the imperative `toast(...)` helper. Theme follows `useTheme()` automatically.

[View examples](https://marsam.rahhal.app/components/toaster) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/toaster`

**Category:** `feedback`

## API

```ts
import { toast } from "@rahhal/ui/toaster";

toast.success("Saved");
toast.error("Couldn't reach the server");
toast("Plain message");
```

Mount `<Toaster />` once near the app root; `toast(...)` is callable from anywhere.


---

Source: https://marsam.rahhal.app/components/json-viewer.md

# JsonViewer

Read-only, syntax-highlighted JSON block. Use for admin payload inspectors, debug panels, webhook viewers — any surface where an operator skims, copies, or downloads a structured payload. Theme tokens are wired through CSS variables so it follows light / dark automatically.

[View examples](https://marsam.rahhal.app/components/json-viewer) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/json-viewer`

**Category:** `feedback`

## Props

| prop | type | purpose |
| --- | --- | --- |
| value | unknown | data to render — stringified with `JSON.stringify(value, null, indent)` |
| json | string | pre-formatted JSON; pass instead of `value` to skip re-stringification |
| indent | number | indent passed to `JSON.stringify`. default 2 |
| language | "json" | "jsonc" | "yaml" | "markup" | highlighter language hint. default "json" |
| maxHeight | string | Tailwind `max-h-*` utility. default `max-h-[32rem]` |
| className / style | passthrough | merged onto the outer `<pre>` |

## When to use what

- **JsonViewer** — read-only payload inspection. Operator skims, copies, or downloads.
- **Form (with Textarea + monospace)** — when the operator must *edit* JSON. The viewer is intentionally read-only.
- **Table / List** — when the structure is uniform enough to flatten into rows; JSON is the fallback when shape varies.

## Implementation note

Internally backed by `prism-react-renderer`. The dependency is encapsulated — swapping highlighters in the future is a single-file edit in `packages/ui/src/json-viewer.tsx` and consumers stay unchanged.


---

Source: https://marsam.rahhal.app/components/spinner.md

# Spinner

Small indeterminate loading indicator. Stroke is `currentColor` so it inherits the surrounding text color (slot inside a destructive button → destructive-on-foreground spinner). Declares `role="status"` and an `aria-label` so assistive tech announces the pending state.

[View examples](https://marsam.rahhal.app/components/spinner) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/spinner`

**Category:** `feedback`

## Sizes

| size | diameter |
| --- | --- |
| sm | 0.75rem / 12px (inline with body text) |
| md (default) | 1rem / 16px (matches `h-4 w-4` Lucide icons) |
| lg | 1.5rem / 24px (page-level wait blocks) |

## Props

| prop | type | purpose |
| --- | --- | --- |
| size | sm | md | lg | visual size; default md |
| label | string | accessible label announced to AT; default "Loading" |
| className | string | merged into the SVG class list (e.g. `me-2` to space inside a button) |

## When to use what

- **Spinner** — indeterminate, short wait, shape of result unknown (button busy state, "checking…", inline retry).
- **Skeleton** — known content shape; users perceive a faster paint when the placeholder mimics the eventual UI.
- **Progress** — determinate progress with a known percentage (file upload, multi-stage import where stages are countable).


---

Source: https://marsam.rahhal.app/components/nav-bar.md

# NavBar

Opinionated top navigation built on `<AppHeader>`. Brand on the start, typed links centered on `md+`, actions on the end. Router-agnostic via a `renderLink` render prop so apps can supply their own `<NavLink>` / `<Link>`.

[View examples](https://marsam.rahhal.app/components/nav-bar) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/nav-bar`

**Category:** `nav`

## Props

| prop | type | purpose |
| --- | --- | --- |
| brand | ReactNode | logo + app title — start edge |
| mobileTrigger | ReactNode | rendered before the brand; typically a hamburger that opens a Sheet |
| items | NavBarItem[] | top-level links: { to, label, end?, icon? } |
| renderLink | render prop | supplies the consumer's router (NavLink / next/Link); falls back to a plain anchor |
| actions | ReactNode | trailing slot — locale switcher, sign-in, etc. |

## Pattern

```tsx
import { NavLink } from "react-router-dom";

<NavBar
  brand={<BrandMark />}
  actions={<SignInButton />}
  items={[{ to: "/", label: "Home", end: true }, …]}
  renderLink={({ item, children, className }) => (
    <NavLink to={item.to} end={item.end} className={({ isActive }) =>
      isActive ? `${className} active` : className
    }>
      {children}
    </NavLink>
  )}
/>
```

## Notes

- Links are hidden under `md` so apps can render a hamburger + Sheet for mobile.
- The fallback (anchor + `window.location.pathname`) only suits static pages; SPAs almost always pass `renderLink`.


---

Source: https://marsam.rahhal.app/components/stepper.md

# Stepper

Multi-step progress indicator. Horizontal (default) or vertical orientation; status (`complete`, `current`, `upcoming`) is derived per-step from `activeStep`.

[View examples](https://marsam.rahhal.app/components/stepper) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/stepper`

**Category:** `nav`

## Props

| prop | type | purpose |
| --- | --- | --- |
| steps | StepperStep[] | ordered list — { title, description?, icon? } |
| activeStep | number | 0-based index of the currently active step |
| orientation | horizontal | vertical | default \"horizontal\" |

## Notes

- Connector lines fill in as the user advances.
- For wizard navigation, pair with two `<Button>`s ("Back" / "Next") and toggle the active index from the parent.


---

Source: https://marsam.rahhal.app/components/wizard-header.md

# WizardHeader

Sticky per-step header for multi-step flows inside a native host (`?host=…`), where the web hides its own AppHeader/AppFooter. Back control at the start, centered title, optional action at the end, plus a slim segmented progress bar. Back navigation is delegated via `onBack`; top safe-area padding clears the iOS notch. RTL-aware.

[View examples](https://marsam.rahhal.app/components/wizard-header) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/wizard-header`

**Category:** `nav`

## Behavior

- iOS-style nav bar: `onBack` control (start) · centered `title` · `action` (end). Omit `onBack` on the first step and the start cell stays empty so the title stays centered.
- `step` + `totalSteps` render a segmented progress bar and set an `aria-label` of "Step X of Y".
- Sticks to the top by default and adds `env(safe-area-inset-top)` padding so it clears the notch inside an iOS WebView.
- The back chevron flips under RTL; the whole bar mirrors via logical layout.

## Props

| prop | type | purpose |
| --- | --- | --- |
| title | ReactNode | centered step title (required) |
| subtitle | ReactNode | smaller line under the title |
| onBack | () => void | back handler · omit to hide the control (first step) |
| backLabel | string | label for the back control · default "Back" |
| step | number | 1-based index of the current step |
| totalSteps | number | renders the segmented progress bar |
| action | ReactNode | trailing slot — e.g. close / skip |
| sticky | boolean | stick to top of the scroll container · default true |

## Pairs with

- `BackButton` — the control it renders internally.
- `Stepper` — when you want labeled steps instead of a slim bar.
- The `embedded` skill — gate it with `useIsEmbedded()` so it only shows inside a host.


---

Source: https://marsam.rahhal.app/components/breadcrumb.md

# Breadcrumb

Hierarchical navigation trail. Compose `<Breadcrumb>` → `<BreadcrumbList>` → `<BreadcrumbItem>` (containing `<BreadcrumbLink>` or `<BreadcrumbPage>`) with `<BreadcrumbSeparator>` between siblings. The default chevron flips under RTL.

[View examples](https://marsam.rahhal.app/components/breadcrumb) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/breadcrumb`

**Category:** `nav`


---

Source: https://marsam.rahhal.app/components/pagination.md

# Pagination

Accessible page navigator. Compose `<Pagination>` → `<PaginationContent>` → `<PaginationItem>` (with `<PaginationLink>`, `<PaginationPrevious>`, `<PaginationNext>`, or `<PaginationEllipsis>` inside). Previous/Next chevrons rotate under RTL.

[View examples](https://marsam.rahhal.app/components/pagination) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/pagination`

**Category:** `nav`


---

Source: https://marsam.rahhal.app/components/tabs-and-accordion.md

# Tabs · Accordion

Disclose grouped content. Use tabs for parallel views, accordion for sequential reveal.

[View examples](https://marsam.rahhal.app/components/tabs-and-accordion) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/tabs · @rahhal/ui/accordion`

**Category:** `nav`


---

Source: https://marsam.rahhal.app/components/sidebar.md

# Sidebar

Layout primitives for the catalog-style left rail every Rahhal mini-app uses: a glassy floating column with a sticky filter / brand area, a scrolling body, and collapsible sections. Layout-only — apps supply data, routing, and filtering.

[View examples](https://marsam.rahhal.app/components/sidebar) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui (AppSidebar, AppSidebarHeader, AppSidebarBody, AppSidebarSection, AppSidebarItem, AppSidebarFooter)`

**Category:** `nav`

## Anatomy

| part | role |
| --- | --- |
| AppSidebar | outer pinned `<aside>` with the glassy capsule chrome; pass `pinned={false}` when rendering inside a `<Sheet>` |
| AppSidebarHeader | sticky top section — typical content: a `<SearchBar>` plus a meta / actions row |
| AppSidebarBody | scrolling content area; wraps a Radix `<ScrollArea>` so the scrollbar matches the platform |
| AppSidebarSection | collapsible group of items — title + optional icon + count pill + chevron |
| AppSidebarItem | one row, supports `asChild` so a router `<NavLink>` can drive `active` |
| AppSidebarItemButton | same visuals as `AppSidebarItem` but with button semantics (e.g. for filters / toggles) |
| AppSidebarFooter | optional footer below the scrolling body |

## Mobile

Drop the same children inside a `<Sheet>` and add a hamburger `<Button>` to `<AppHeader>`. The chrome adapts because positioning is left to the parent (sticky on desktop via `pinned`, full-height inside the sheet on mobile).

## Notes

- The primitives are layout-only by design. Apps supply the data, the router (`react-router`'s `<NavLink>`, `next/link`, …), and the filtering / collapse state.
- All RTL-aware: chevrons rotate by writing direction, padding uses logical `ps-*` / `pe-*` utilities.
- Persist collapse state per app in `localStorage` if you want it to survive reloads (the catalog does).


---

Source: https://marsam.rahhal.app/components/embedded-mode.md

# Embedded mode

Detection helper for when a mini-app is loaded inside an iOS / Android / desktop host container. The host signals via `?host=<value>`; the web persists it in sessionStorage and exposes it to layouts via `useIsEmbedded()` so chrome (`<AppHeader>`, `<AppFooter>`) can be hidden in favor of the host's native nav.

[View examples](https://marsam.rahhal.app/components/embedded-mode) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/app-chrome/react`

**Category:** `nav`

## URL contract

| ?host= value | container |
| --- | --- |
| ios | official Rahhal iOS app (WKWebView) |
| android | official Rahhal Android app (WebView) |
| mobile | generic mobile container (Capacitor, RN-WebView) |
| desktop | Electron / Tauri-style desktop wrapper |

Values are case-insensitive. Unknown values are ignored (treated as standalone). The host only needs to pass the param **once**: the web persists the resolved value in `sessionStorage["rahhal-host"]` for the tab/WebView lifetime, then strips `?host=` from the visible URL via `history.replaceState`.

## API

| symbol | purpose |
| --- | --- |
| <EmbeddedProvider> | mount once at the app root, after the router. Accepts `hostOverride?: Host | null` for tests / stories. |
| useHost(): Host | null | raw host value · `null` when standalone |
| useIsEmbedded(): boolean | true iff useHost() is non-null · the 90% question |
| useIsMobileHost(): boolean | true only for ios / android / mobile · use for phone-only UX |
| [data-host="ios"] | CSS hook mirrored on <html>; gone when standalone |

All hooks throw if used outside an `<EmbeddedProvider>` — the mounting requirement is enforced.

## What to hide

In embedded mode, hide `<AppHeader>` and `<AppFooter>` only. **Don't** hide `<AppSidebar>` (the host can't replicate section nav) or `<LoginScreen>` (transient auth step). Pair `{!isEmbedded && <Header />}` with `<AppShell noHeader={isEmbedded}>` so the shell doesn't reserve top padding for a header you aren't rendering.

## Composition

- **Auth:** `@rahhal/auth` uses the URL **fragment** (`#access_token=…`). `?host=` is a query parameter — no collision. The provider intentionally never touches `window.location.hash`.
- **i18n:** `@rahhal/i18n` uses the same `history.replaceState` strip pattern for `?lang=`. Mounting both providers is order-independent.
- **SEO:** Unaffected. Viewport and manifest metadata apply the same way whether embedded or not.


---

Source: https://marsam.rahhal.app/components/footer.md

# Footer

Bottom chrome for a Rahhal mini-app. A floating glassy capsule that mirrors `<AppHeader>`: links + social inside a pill, brand line below. Helpers `<FooterLinks>`, `<FooterLink>`, and `<FooterSocial>` keep spacing and ARIA consistent.

[View examples](https://marsam.rahhal.app/components/footer) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui (AppFooter, FooterLinks, FooterLink, FooterSocial)`

**Category:** `nav`

## Anatomy

| part | role |
| --- | --- |
| AppFooter | outer footer — floating glassy pill |
| FooterLinks | wrapping row of FooterLink children; centered on phones and start-aligned from 640px |
| FooterLink | muted anchor with hover-darkens-to-foreground |
| FooterSocial | round icon link (e.g. Instagram, LinkedIn) with required `label` ARIA |

## Notes

- Links and social icons stack below 640px inside a rounded panel. From 640px, they share a pill-shaped row; links wrap when space is limited.
- Brand line defaults to `© <year> Rahhal` — keep it intact across mini-apps for recognizability.
- All link helpers accept the standard `<a>` props (`href`, `target`, `rel`, …). Wrap a router `<Link>` if you need client-side navigation: keep the `FooterLink` className.


---

Source: https://marsam.rahhal.app/components/alert-dialog.md

# AlertDialog

Interrupting confirmation dialog for destructive or unrecoverable actions. The user must explicitly confirm or cancel — clicking outside does not dismiss. Built on Radix Alert Dialog.

[View examples](https://marsam.rahhal.app/components/alert-dialog) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/alert-dialog`

**Category:** `overlays`

## Anatomy

| part | role |
| --- | --- |
| AlertDialog · Trigger · Portal | Radix root + trigger + portal |
| AlertDialogContent | centered dialog body |
| AlertDialogHeader / Title / Description | title + body copy |
| AlertDialogFooter | right-aligned action area (stacks vertically on small screens) |
| AlertDialogAction | confirm button (uses default Button styling) |
| AlertDialogCancel | dismiss button (outline variant) |

## When to use vs Dialog

- **AlertDialog** — irreversible actions: delete, archive, sign out, abandon a form with unsaved changes.
- **Dialog** — focused interactions that don't carry that weight: editing, viewing details, completing a step.


---

Source: https://marsam.rahhal.app/components/drawer.md

# Drawer

Bottom-sheet style modal that slides up from the edge of the viewport. Built on `vaul` for touch-friendly drag-to-dismiss. Use for mobile-first flows where a centered `<Dialog>` would feel heavy. For desktop side panels, prefer `<Sheet>`.

[View examples](https://marsam.rahhal.app/components/drawer) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/drawer`

**Category:** `overlays`


---

Source: https://marsam.rahhal.app/components/popover.md

# Popover

Floating panel anchored to a trigger. Non-modal — clicking outside dismisses. Built on Radix Popover. Use for date pickers, filter panels, color pickers, settings popouts.

[View examples](https://marsam.rahhal.app/components/popover) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/popover`

**Category:** `overlays`


---

Source: https://marsam.rahhal.app/components/hover-card.md

# HoverCard

Small floating preview shown on hover or focus. Use for profile cards, link previews, or anywhere a tooltip would be too small. Built on Radix Hover Card.

[View examples](https://marsam.rahhal.app/components/hover-card) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/hover-card`

**Category:** `overlays`


---

Source: https://marsam.rahhal.app/components/command.md

# Command palette

Searchable list / command palette built on `cmdk`. Use inline (`<Command>`) for typeahead pickers, or wrapped in `<CommandDialog>` for a global cmd-K launcher. Items are scored client-side as the user types.

[View examples](https://marsam.rahhal.app/components/command) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/command`

**Category:** `overlays`

## Pieces

| part | role |
| --- | --- |
| Command | outer shell (or use \"CommandDialog\" for cmd-K modals) |
| CommandInput | search field with leading magnifier |
| CommandList | scrollable result list |
| CommandEmpty | shown when nothing matches |
| CommandGroup | group of related items (with optional `heading`) |
| CommandItem | single selectable row |
| CommandSeparator | visual divider between groups |
| CommandShortcut | end-aligned keyboard hint |


---

Source: https://marsam.rahhal.app/components/dialog-and-sheet.md

# Dialog · Sheet

Centered modal vs. side sheet. Use a dialog for short focused interactions; use a sheet for navigation drawers, filters, or contextual editors.

[View examples](https://marsam.rahhal.app/components/dialog-and-sheet) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/dialog · @rahhal/ui/sheet`

**Category:** `overlays`


---

Source: https://marsam.rahhal.app/components/menus-and-tooltip.md

# Dropdown · Select · Tooltip

Floating triggers and selectors. All three flip correctly under RTL.

[View examples](https://marsam.rahhal.app/components/menus-and-tooltip) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/dropdown-menu · @rahhal/ui/select · @rahhal/ui/tooltip`

**Category:** `overlays`


---

Source: https://marsam.rahhal.app/components/phone-input.md

# PhoneInput

International phone field with searchable country picker. Default country is auto-detected from the user's IANA timezone (e.g. KSA for Asia/Riyadh). Numbers always render LTR even inside RTL regions.

[View examples](https://marsam.rahhal.app/components/phone-input) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/phone-input`

**Category:** `auth`

## Props

| prop | type | purpose |
| --- | --- | --- |
| value | string | current value in E.164 form (e.g. `+9665XXXXXXXX`) or empty string |
| onChange | (value: string) => void | fires with the new E.164 value (or `""` if cleared) |
| disabled | boolean | disable interaction; styled with reduced opacity |
| defaultCountry | Country | override the auto-detected default (ISO 3166-1 alpha-2); falls back to timezone, then `US` |
| placeholder | string | custom placeholder for the number field |
| id | string | forwarded to the inner `<input>` |
| autoFocus | boolean | focus the number field (not the country trigger) on mount — pair with sign-in screens so visitors start typing without an extra tap |
| labels | Labels | localized country names — pass `import('react-phone-number-input/locale/ar.json')` for Arabic, defaults to English |
| searchPlaceholder | string | placeholder inside the country-picker search input — defaults to `"Search country..."` |
| searchEmpty | string | message shown when the search returns no countries — defaults to `"No country found."` |

## Country picker

Clicking the flag trigger opens a Popover containing a searchable list of every country. Each row shows the flag, country name, and dial code (e.g. `🇸🇦 Saudi Arabia +966`). The search input matches **all three** in parallel — typing `966`, `saudi`, or `sa` all surface Saudi Arabia. Keyboard navigation (↑ / ↓ / Enter / Esc) works out of the box via cmdk.

The picker is a UI substitution via the upstream library's documented `countrySelectComponent` extension point — the parsing / validation / formatting layer is untouched. Removing the prop restores the library's native `<select>` for instant rollback.

## Localization

Country names default to English. To render them in Arabic (or any other supported locale), pass the lib's locale JSON:

```tsx
import arLocale from "react-phone-number-input/locale/ar.json";

<PhoneInput
  value={phone}
  onChange={setPhone}
  labels={arLocale}
  searchPlaceholder="ابحث عن دولة..."
  searchEmpty="لا توجد دولة مطابقة."
/>
```

The locale file adds ~6 KB gzip per language — only pull it in apps that actually ship that language.

## Required CSS

Apps that render `<PhoneInput>` directly must import the stylesheet once at their entry point:

```ts
import "@rahhal/ui/phone-input.css";
```

Apps that only render `<PhoneInput>` transitively via `<LoginScreen>` from `@rahhal/auth/react` do **not** need this import — `<LoginScreen>` pulls it in for them.

## Dark mode

The stylesheet uses the same `hsl(var(--background))` / `hsl(var(--foreground))` tokens as `<Input>`, so the field reads correctly in both themes. Browser autofill (`-webkit-autofill`) is overridden so saved-phone autofill keeps the dark-mode surface — without that override Chrome / Safari would re-paint the field pale yellow with near-black text.

## RTL

The surrounding chrome (trigger button, popover, country list) follows the document direction. The number itself always renders LTR via `direction: ltr; text-align: start;` on the inner input — phone numbers are universally read LTR even in Arabic UIs.

## Default-country detection

On mount, the component reads `Intl.DateTimeFormat().resolvedOptions().timeZone` and maps it to a country (e.g. `Asia/Riyadh` → `SA`, `America/New_York` → `US`). Unknown timezones fall back to `US`. Pass `defaultCountry` to override.


---

Source: https://marsam.rahhal.app/components/input-otp.md

# InputOTP

Segmented one-time-code input. Used for the SMS code step of the Rahhal phone-OTP sign-in flow, but generic enough for any 4–8 digit verification code. Built on the `input-otp` library; logical Tailwind utilities mean the rounded ends and divider borders flip correctly under RTL.

[View examples](https://marsam.rahhal.app/components/input-otp) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/input-otp`

**Category:** `auth`


---

Source: https://marsam.rahhal.app/components/login-screen.md

# LoginScreen (demo)

A UI-only walk-through of the canonical Rahhal phone-OTP login: phone step → OTP step → success. Two layouts share the same form body — `centered` (default) is a focused single-card screen; `split` adds a brand-led marketing pane on the start edge at `lg+`. Production mini-apps consume the same UX via `<LoginScreen>` from `@rahhal/auth/react`.

[View examples](https://marsam.rahhal.app/components/login-screen) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `Demo only · production lives in @rahhal/auth/react`

**Category:** `auth`

## Layouts

| layout | use when |
| --- | --- |
| centered (default) | focused / utility sign-in — small surface, fast for repeat visitors |
| split | first-touch / public mini-app — brand pane + form pane at `lg+`, marketing hidden under `lg` |

## Props (`<LoginScreen>` from @rahhal/auth/react)

| prop | type | purpose |
| --- | --- | --- |
| labels | LoginScreenLabels | every translated string the screen renders |
| toast | LoginToastAdapter | success / error feedback adapter (pass `toast` from `@rahhal/ui/toaster`) |
| logoLightSrc / logoDarkSrc | string | theme-paired logo URLs rendered in the card header |
| onSignedIn | () => void | fires the moment the session goes live — typically navigates away from `/login` |
| topActions | ReactNode | fixed top-end slot (theme + locale switchers, etc.) |
| layout | "centered" | "split" | default "centered" — back-compatible with the original screen |
| marketing | ReactNode | marketing-pane content for `layout="split"` (hidden under `lg`); pass `<LoginMarketingPanel>` for the canonical structured shape, or any JSX for full freedom |
| resendCooldownSeconds | number | default 90 |

## `<LoginMarketingPanel>` slots

Drop into `<LoginScreen marketing={…}>` for the brand-led pane:

| slot | purpose |
| --- | --- |
| brand | small logo + wordmark in the start-top corner |
| eyebrow | small pill above the headline (e.g. "Welcome back") |
| headline | required big headline — gets the platform's primary→accent gradient treatment |
| body | 1–2 sentences supporting the headline |
| bullets | value-prop list with optional leading icons |
| footer | small print pinned to the bottom; defaults to `© <year> Rahhal` |

## Mobile

Under `lg` the marketing pane is hidden and the form fills the screen — phone visitors see the same fast utility surface as the centered layout, regardless of which variant the app picks.

## Catalog demo

The demo at `/login` toggles layouts via `?variant=split`. The catalog `LoginScreen` page exposes both as buttons. The demo is intentionally **not** wired to `@rahhal/auth` — the design-system app must not depend on the auth package per the platform's CLAUDE.md.


---

Source: https://marsam.rahhal.app/components/require-role.md

# RequireRole

Render-gate that requires both an active session and a named role string in the user's `app_metadata.roles` claim. Compose at the top of a protected subtree so the gate runs once. Roles are issued backend-side by writing `auth.users.app_metadata.roles`; this component is read-only.

[View examples](https://marsam.rahhal.app/components/require-role) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/auth/react`

**Category:** `auth`

## States (mapped to `useSession().status` + `useRole(role).hasRole`)

| status / role | renders |
| --- | --- |
| `booting` | `parsing-hash` | `pending` (default: nothing) |
| `signed-in` && hasRole | `children` |
| `signed-in` && !hasRole | `deniedFallback` (default: terse inline alert) |
| `signed-out` | `fallback` (default: "open from Rahhal app") |
| `error` | `errorFallback` |

## Props

| prop | type | purpose |
| --- | --- | --- |
| role | string | required role string (e.g. `"gmaplist_admin"`) |
| children | ReactNode | rendered when signed-in and role present |
| pending | ReactNode | shown during boot / fragment-parsing |
| fallback | ReactNode | shown when signed out — pass your <LoginScreen> |
| deniedFallback | ReactNode | shown when signed in without the role — pass <AccessDeniedScreen> |
| errorFallback | ReactNode | shown on unrecoverable session errors |

## Companion hook

`useRole(role)` returns `{ hasRole, roles, status }`. Use for multi-tier UIs that render differently for `super_admin` vs `viewer` without reaching into `useJwtClaims()` directly.

## Where roles come from

Write `auth.users.app_metadata.roles` (a `string[]`) via the Supabase dashboard or a service-role admin script. The JWT mirrors that array into its `app_metadata` claim, which is what `<RequireRole>` reads.


---

Source: https://marsam.rahhal.app/components/access-denied-screen.md

# AccessDeniedScreen

Full-screen "you don't have permission" surface. Pairs with `<RequireRole>` from `@rahhal/auth/react` as the default `deniedFallback`. Same anatomy as `<EmptyState>` — icon · title · description · action — with a destructive-tinted icon tile and a viewport-filling default layout.

[View examples](https://marsam.rahhal.app/components/access-denied-screen) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/access-denied-screen`

**Category:** `auth`

## Props

| prop | type | purpose |
| --- | --- | --- |
| icon | ReactNode | override the default <ShieldOff>; render any 18–24px node |
| title | ReactNode | headline; default "Access denied" |
| description | ReactNode | body copy explaining why the page is blocked |
| action | ReactNode | trailing action(s); typically a sign-out button |
| fullHeight | boolean | default true — fills the viewport; set false to embed inside a smaller slot |

## Pattern

```tsx
import { AccessDeniedScreen, Button } from "@rahhal/ui";
import { signOut, useSupabase } from "@rahhal/auth/react";

function Denied() {
  const supabase = useSupabase();
  return (
    <AccessDeniedScreen
      title="Admins only"
      description="Your account doesn't have permission for this admin tool."
      action={<Button onClick={() => signOut(supabase)}>Sign out</Button>}
    />
  );
}
```


---

Source: https://marsam.rahhal.app/components/countries.md

# Country facts

Drop-in country UI from `@rahhal/countries/react`: `CountryFlag`, `CountryCard`, `CountryFacts`, `CountryDetail`. Data-in or self-fetching (by `name`/`code`), label-injected for i18n, and composed from `@rahhal/ui`. Backed by a REST Countries v4 client with an automatic v3.1 fallback.

[View examples](https://marsam.rahhal.app/components/countries) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/countries/react`

**Category:** `data`

## Components

| component | purpose |
| --- | --- |
| CountryFlag | emoji or SVG flag, with a cca2-derived fallback |
| CountryCard | compact tile — flag · name · region · capital · population |
| CountryFacts | labelled definition list of the key facts |
| CountryDetail | full view — header + facts + neighbours + footer slot |

## Common props

| prop | type | purpose |
| --- | --- | --- |
| country | Country | null | data-in mode |
| name / code | string | self-fetching mode (by name or ISO code) |
| labels | CountryLabels | localized field labels (English defaults applied) |
| renderNeighborLink | (cca3) => ReactNode | CountryDetail — app-routed neighbour links |
| footer | ReactNode | CountryDetail — app-owned extras (map, buttons) |

## Data layer (`@rahhal/countries`)

| export | purpose |
| --- | --- |
| getAllCountries() | light grid projection of every country |
| getCountryByName / Code | full detail for one country |
| getCountriesByRegion / Currency / Language | scoped lists |
| formatPopulation / formatArea / formatDensity | display formatters |