# Oribet component library

> Every component an Oribet casino design can use, with the contract each one is built on. Each entry links to its own markdown file; /component-library.md has all of them in one file.

## How a site is put together

A site is a document rendered under a theme. The document holds the pages, the sections on each
page and their settings. The theme decides how each section looks.

Every widget has three layers:

1. Behaviour. A hook in `@oribet/core` fetches the data and exposes the actions.
2. Contract. The settings, data, parts and CSS vars the widget has. This file documents it.
3. Renderer. A React component in a theme that draws one contract.

A new design is a new renderer. It may look completely different from the current one, but it
gets the same settings and the same data.

## Rules for a design

- Map every widget in the design onto one contract below. If a widget needs data or a setting
  its contract doesn't list, mark it in the design as "needs a new contract" and say what is
  missing. Don't invent fields.
- Use tokens for every colour, radius, font, shadow and spacing. A brand changes the token
  values, so a raw hex or pixel value in a design breaks on every brand but one. The token list
  is in the Tokens section.
- Every DOM part a contract lists must exist in the design, because a brand's part CSS targets
  it by `data-part`. A design may add elements inside a part.
- Every `--m-*` var a contract lists must change something visible, because the brand edits it
  in the configurator.
- Back-office content comes as data: game names and artwork, provider logos, banner images,
  promotion and tournament copy. A design shows it but can't rewrite it.
- Settings marked `i18nText` hold a translation key, and the words are edited per language. Leave
  room for translations longer than the English.
- Desktop chrome (header, sidebar, footer) and mobile chrome (mobile header, bottom nav, drawers)
  are separate contracts. Design both.
- System flows (auth, wallet, bonuses, account and the rest) belong to the platform. A theme
  changes how they look through tokens only. Don't redesign their structure.

## Glossary

- Family. A widget kind, such as `hero` or `game-blocks`. The unit a theme replaces.
- Look. One of the drawings a family ships. Looks share the family's settings; each one lists
  the settings it draws.
- Setting. A value the brand sets per section in the configurator.
- Preset. A named set of setting values the configurator offers as a shortcut.
- Part. A DOM element a renderer exposes as `data-part="<id>"`, so brand CSS can style it.
- Var. A CSS custom property (`--m-*`) the renderer reads, so the brand can tune it without CSS.
- Slot. A place inside a widget where other widgets go. Only layout widgets have them.
- Chrome. The site frame around the pages: header, sidebar, footer, mobile bars and drawers.
- Chrome item. One entry in a chrome bar, such as the logo, the balance or a link. The brand
  orders and toggles them; the theme draws them.
- Token. A site-wide design value (`--t-*`) from the document's theme, exposed as a Tailwind
  utility.

## Tokens

- [Design tokens](/tokens.md): Every colour, radius, font, shadow and spacing a design may use, as Tailwind classes.

## Widgets

- [Active tournament](/widget/active-tournament.md): The tournament running now, beside its games, its leaderboard and its rules.
- [Custom HTML](/widget/custom-html.md): A block of sanitised HTML, for the copy no module covers.
- [Promotions](/widget/promotions-list.md): Grid of the promotions the back office publishes.
- [Tournaments](/widget/tournaments-list.md): Tabs and cards for the tournaments the back office runs.
- [Game grid](/widget/casino-grid.md): Filterable grid of the whole game catalogue.
- [Game rows](/widget/game-blocks.md): The game blocks the back office defines, as swiper rows.
- [Providers](/widget/provider-swiper.md): Game-provider logo strip.
- [Hero](/widget/hero.md): The banner carousel, or a welcome offer whose button follows the session.
- [Row](/widget/row.md): Two or three widgets side by side. Drop anything into its columns.
- [Spacer](/widget/spacer.md): Empty vertical space, with an optional divider line.
- [Category tiles](/widget/category-cards.md): Casino / Sport entry tiles.
- [Live bets](/widget/bets-table.md): Live bet feed: the rolling Live Bets stream and Lucky Wins.
- [Recent big wins](/widget/recent-wins.md): Live strip of the latest wins.
- [Top matches](/widget/top-matches.md): Sportsbook fixtures. Hides itself where there is no sportsbook.

## Chrome

- [What the brand controls](/chrome/composition.md): How the brand orders, hides and adds chrome items, and what ships by default.
- [Header (desktop)](/chrome/header.md): `chrome/header` — the desktop bar.
- [Sidebar (desktop rail)](/chrome/sidebar.md): Sidebar (desktop rail)
- [Footer](/chrome/footer.md): `chrome/footer` — the site footer.
- [CGA licence block (footer)](/chrome/cga-licence.md): The Curacao Gaming Authority licence block: the verification seal, and the operator statement.
- [Mobile header](/chrome/mobile-header.md): Mobile header
- [Bottom nav (mobile)](/chrome/bottom-nav.md): Bottom nav (mobile)
- [Menu drawer (mobile)](/chrome/menu-drawer.md): The mobile menu sheet: a Casino/Sport switcher, the welcome promo, the nav list, and a collapsible Promotions section that also carries the language control and the two brand rows.
- [Account menu (desktop dropdown)](/chrome/account-menu.md): The header's account dropdown: an avatar button, a panel of dashboard links, and a log-out confirmation.
- [Account drawer (mobile)](/chrome/account-drawer.md): The account drawer — the mobile form of the dropdown.
- [Balance pill (header)](/chrome/balance-pill.md): The header's wallet pill: the default wallet's total, a chevron that opens the panel, and the Wallet button.
- [Balance overview (balance panel)](/chrome/balance-overview.md): The default wallet's card, at the top of the balance panel.
- [Wallet row (balance panel)](/chrome/wallet-row.md): A wallet the player is not currently using, listed under the overview.
- [Bonus chip (header)](/chrome/bonus-chip.md): The BONUSES chip in the header: a mark, a label and an active/total count.

## Page components

- [Promotion detail](/page/promotion-detail.md): One promotion, in full: a back button, the title, a deposit CTA, an optional countdown, the hero image and the back office's HTML body.
- [Tournament detail](/page/tournament-detail.md): One tournament, in full: a hero, the stats bar, the per-place prizes, the leaderboard beside them, the tournament's games, and the terms the back office wrote.
- [Tournament leaderboard](/page/tournament-leaderboard.md): The tournament leaderboard: rank, player, wagered, prize.
- [Games list page](/page/games-page.md): The games list page: a title, a search field, a filter row, the grid, and an empty state.

## Platform components

- [Game card](/platform/game-card.md): The most repeated element on the site: one card for every theme, reshaped by brand options.
- [UI primitives](/platform/ui.md): Building blocks a renderer may use, all drawn from the tokens.

## System flows

- [App config](/system/app-config.md): The runtime configuration every flow reads.
- [Sidebar menus](/system/app-sidebar.md): The casino, sport and support menus inside the desktop rail.
- [Registration and recovery](/system/authorization.md): Sign-up, password reset and phone verification.
- [Blog](/system/blog.md): The blog index and article pages.
- [Bonus panel](/system/bonus-cluster.md): The header bonus panel: rank progress, active bonuses, cashback and rakeback.
- [Bonus modals](/system/bonus-modals.md): Claim, buy, cancel and wager dialogs for bonus money.
- [Bonus play](/system/bonus-play.md): Bonus mode: the bonus balance being wagered and the games it can be played on.
- [Bonus wheel](/system/bonus-wheel.md): The daily prize wheel.
- [Bonuses page](/system/bonuses.md): My gifts and bonuses: bonus money, cash prizes, free spins, rakeback and the marketplace.
- [Casino page](/system/casino.md): The casino landing page: banner, provider strip, filters and the game grid.
- [Chat](/system/chat.md): The community chat drawer.
- [Chat notices](/system/chat-notices.md): The notices pinned above the chat.
- [Country restriction](/system/country-restriction.md): The notice a player in a restricted country sees instead of the site.
- [Currency selection](/system/currency-selection.md): Choosing a wallet currency to finish a social sign-up.
- [Account dashboard](/system/dashboard.md): The account area: personal information, wallet, notifications, verification, preferences.
- [Discard guard](/system/discard-guard.md): The unsaved-changes confirm the account forms raise.
- [Search](/system/federated-search.md): Site search across games, providers and sport.
- [Fingerprint](/system/fingerprint.md): Device identification for fraud checks.
- [Game card](/system/game-card.md): The game card and its parts.
- [Game filters](/system/global-search.md): Provider, sort and visibility filters on game lists.
- [Head section](/system/head-section.md): Page title and meta tags.
- [Language select](/system/language-select.md): The language switcher, in the mobile menu.
- [Leaderboard page](/system/leaderboards-page.md): A tournament leaderboard: countdown, your position and the board.
- [Live chat](/system/live-chat.md): The support live-chat widget.
- [Marketplace](/system/marketplace.md): Bonus money for sale, bought with real balance.
- [Not found](/system/not-found.md): The 404 page.
- [Notifications](/system/notification.md): The header bell and its notification list.
- [Sign in](/system/oribet-authorization.md): The sign-in and sign-up modal.
- [Play game](/system/play-game.md): The game page: the provider frame with header and footer bars.
- [Policies](/system/policies.md): Terms, privacy and the other legal pages. Their text is the site document’s, written in the editor.
- [Provider card](/system/provider-card.md): One provider in the provider list.
- [Provider icon](/system/provider-icon.md): The provider mark on game cards and lists.
- [Provider list](/system/provider-list.md): Every provider, searchable.
- [Rank system](/system/rank-system.md): The ranks and levels page.
- [Account settings](/system/settings.md): The account area’s forms and section headers.
- [Sportsbook](/system/upgaming.md): The embedded sportsbook.
- [Player profile](/system/user-profile.md): A player’s profile: rank, statistics and favourites.
- [Wallet](/system/wallet.md): The cashier: deposit, withdraw and transactions per wallet.

## Data records

- [Banners from the back office](/record/banners.md): Banners from the back office, the `banners` data source.
- [Promotions](/record/content.promotions.md): Promotions, the `content.promotions` data source.
- [Tournaments](/record/engagement.tournaments.md): Tournaments, the `engagement.tournaments` data source.
- [Games](/record/games.catalogue.md): Games, the `games.catalogue` data source.
- [Game categories](/record/games.categories.md): Game categories, the `games.categories` data source.
- [Game blocks (curated rows)](/record/games.gameBlocks.md): Game blocks (curated rows), the `games.gameBlocks` data source.
- [Game providers](/record/games.providers.md): Game providers, the `games.providers` data source.
- [Live bets feed](/record/socket.lastBets.md): Live bets feed, the `socket.lastBets` data source.
- [Latest wins feed](/record/socket.lastWins.md): Latest wins feed, the `socket.lastWins` data source.
- [Sportsbook top matches](/record/sports.topMatches.md): Sportsbook top matches, the `sports.topMatches` data source.

## Optional

- [Everything in one file](/component-library.md)
- [Structured data](/library.json): the same entries as JSON, with settings, looks, presets, parts and vars as fields
