# 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](/platform/system.md): Auth, cashier, account, KYC, bonuses, game launch, sportsbook: restyled by tokens only.

## 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