# @ziyarago/ui

> ZiyaraGo UI — glass design system for Umrah and Hajj products. OKLCH tokens, two palettes, dark and light, RTL, Thmanyah. One framework-neutral core with Vue 3, Nuxt and React adapters, 184 components and 17 page templates.

Version 0.6.1. Docs: https://ziyara.vip . Manifest (machine readable): https://ziyara.vip/manifest.json

## Setup
- import { UiButton } from '@ziyarago/ui/vue'
- import { UiButton } from '@ziyarago/ui/react'
- modules: ['@ziyarago/ui/nuxt']
- import '@ziyarago/ui/style.css'
- import { useUiTheme } from '@ziyarago/ui/theme'

## Conventions
- Component names are Ui<Name>. Vue and React share names and props.
- Controlled inputs: Vue v-model, React modelValue + onChange(value). Components that read value/page use :value + @change (React onChange).
- Slots: Vue named slots; React props with the same name, default slot = children.
- Sizes: size="xs|sm|md|lg|xl" (default md) where documented.
- Style only with tokens: var(--zg-*). Theme: data-theme dark|light, data-palette gold|tamam, dir ltr|rtl.
- Cards: variant default|inverse|gradient (tone, intensity soft|vivid).

## Typography
Headings and text.
- UiHeading: Semantic heading h1-h6 with a responsive type scale; use for page and section titles.
- UiText: Body text paragraph (or any inline/block tag via as) with size, tone and truncation.
- UiCode: Code block with a header (title or language) and a copy button; use for snippets and commands.
- UiKbd: Keyboard key cap for shortcuts such as Ctrl or K.
- UiLink: Styled anchor for in-text and standalone links, with optional external-link behavior.

## Layout
Stacks, grids and page structure.
- UiBox: Generic container with optional padding and glass background.
- UiCenter: Centers its children horizontally and vertically.
- UiHStack: Horizontal flex row with a configurable gap.
- UiVStack: Vertical flex column with a configurable gap.
- UiGrid: CSS grid with a fixed column count or auto-fit columns of a minimum width.
- UiDivider: Horizontal separator line with an optional centered label.
- UiScrollArea: Vertically scrollable container with a max height and styled scrollbar.
- UiSplitLayout: Two-column layout with configurable column widths; use for master-detail or side-by-side content.
- UiAppShell: Application frame with a top or side navigation and a main content area.
- UiPageHeader: Page title block with optional breadcrumbs, subtitle and an actions area.
- UiAuthLayout: Centered card layout for sign-in and sign-up pages.
- UiSettingsSection: Settings block with a title and description on the left and fields below.
- UiLiquidGlass: Frosted liquid-glass panel with adjustable corner radius and blur.
- UiFooter: Page footer with a copyright line and a row of links.
- UiSortable: Drag-and-drop reorderable list with grip handles and up/down buttons.
- UiPortal: Renders its children outside the component tree, for example into document.body.

## Actions
Buttons and things you press.
- UiButton: Primary action control with visual variants, tones, sizes, icons and a loading state.
- UiIconButton: Square button with only an icon; use for toolbars and compact actions.
- UiPressable: Unstyled pressable wrapper that makes any content a button with press feedback.
- UiFab: Floating action button for the main action of a screen; extended when a label is given.
- UiCopyButton: Button that copies a value to the clipboard and briefly confirms with a check icon, or reports a failure.
- UiToggleGroup: Group of toggle buttons with single or multiple selection, optionally icon-only.
- UiSegmentedControl: Segmented switch for choosing exactly one of a few options.
- UiFilterChips: Row of selectable filter chips with single or multiple selection.
- UiChip: Compact label with optional icon and remove button; use for statuses, filters and attributes.
- UiTag: Small pill label, optionally removable; use for keywords and selected values.
- UiBadge: Status badge with a colored tone and optional dot.
- UiActionRail: Floating vertical or horizontal rail of icon buttons with a highlighted active item.
- UiActionCard: Card with a title and built-in collapse, refresh and remove controls.
- UiNotificationBell: Bell icon button with an unread counter and a dropdown list of notifications.

## Forms
Inputs, pickers and form building blocks.
- UiTextField: Single-line text input with label, icon, suffix, hint and error. Use for any short free-text or typed value (email, url, number as text).
- UiTextarea: Multi-line text input. Use for comments, descriptions and other long text.
- UiNumberInput: Numeric stepper with minus and plus buttons and a typed value. Use for quantities, guest counts and small integers.
- UiPasswordInput: Password field with a show/hide toggle. Use for sign-in and password change forms.
- UiSearchInput: Compact search field with a clear button and an Enter-to-search event. Use above lists and tables.
- UiPhoneInput: Phone field with a country code dropdown. Use for contact numbers where the dial code matters.
- UiCodeInput: One-time code input rendered as separate digit cells. Use for SMS or email verification codes.
- UiChipInput: Input that turns typed text into removable chips. Use for tags, keywords and email lists.
- UiInlineEdit: Text that turns into an input on click. Use for renaming and quick edits without a form.
- UiRichEditor: Rich text editor with a formatting toolbar, built on contenteditable. Use for formatted descriptions and notes.
- UiSelect: Single-choice dropdown. Use when the user picks one value from a known list.
- UiMultiSelect: Dropdown with checkboxes for choosing several values. Use for filters and multi-valued fields.
- UiGroupedSelect: Single-choice dropdown with option groups under headings. Use for long lists that have natural categories.
- UiCombobox: Searchable single-choice dropdown. Use for long option lists where typing to filter is faster than scrolling.
- UiTreeSelect: Dropdown with a searchable tree. Use for hierarchical choices such as regions, categories or org units.
- UiPillSelect: Small pill-shaped dropdown button. Use for inline filters and sort controls in toolbars.
- UiCheckbox: Boolean checkbox with an inline label. Use for opt-ins and independent yes/no choices.
- UiSwitch: On/off toggle with an inline label. Use for settings that apply immediately.
- UiRadioGroup: Group of radio options with optional hints. Use for a short single-choice list that should stay visible.
- UiOptionCard: Selectable card with title, description, price and optional image or icon. Usually rendered by OptionCards.
- UiOptionCards: Grid of selectable OptionCards, single or multiple choice. Use for plans, room types and delivery options.
- UiSlider: Single-handle range slider with a value readout. Use for picking one number in a bounded range.
- UiRangeSlider: Two-handle slider for a min-max range. Use for price, duration or date-number filters.
- UiRating: Star rating input. Use for reviews and quick feedback.
- UiColorPicker: Swatch row for choosing a color from presets. Use for tags, labels and theme accents.
- UiCalendar: Month grid for picking one date. Use inline, or inside a popover via DatePicker.
- UiRangeCalendar: Month grid for picking a date range with hover preview. Use for stays, trips and report periods.
- UiDatePicker: Field with a calendar popup for choosing a date. Use in forms where a single date is needed.
- UiTimePicker: Hour and minute selects for a time of day. Use for opening hours and appointment times.
- UiFileUpload: Drop-zone style file picker. Use for documents and attachments.
- UiImageUpload: Image picker with a live preview, square or circular. Use for avatars, covers and logos.
- UiFormField: Label, required marker, hint and error wrapper around any control. Use to build a field from custom inputs.
- UiValidatedField: TextField (or PasswordInput) with built-in validation rules. Use for simple client-side validation without a form library.
- UiLoginForm: Ready sign-in form with login, password, remember-me, forgot link and submit button. Use as the body of an auth page.
- UiStepForm: Multi-step form shell: stepper, current step content and Back/Next buttons. Use for wizards and onboarding.
- UiStepper: Horizontal progress indicator with numbered steps. Use to show position in a multi-step flow.

## Data display
Tables, stats, charts and lists.
- UiCard: Glass surface container with an optional title header, used to group related content.
- UiDataTable: Table with sortable columns, custom cell rendering and optional row selection checkboxes.
- UiDataGroup: Table whose rows are collapsed into labeled groups, with optional per-row expandable details.
- UiDescriptions: Definition list of label and value pairs for record details.
- UiTimeline: Vertical list of events connected by a line, for activity history and status progress.
- UiTreeView: Expandable tree of nodes for hierarchies such as folders, categories or regions.
- UiCalendarView: Month calendar that marks days with events, wrapping Calendar with a list-style events prop.
- UiKpiTile: Key metric tile with a label, large value and optional delta, for dashboards.
- UiKpiInline: Compact inline metric with a label, value and delta, for toolbars and card headers.
- UiStatsCard: Metric card with an optional icon, value and an up or down trend.
- UiStatRow: List row with an icon tile, title, subtitle and a right-aligned value with delta.
- UiStatLine: Card with a large value, icon tile, label and an accent bar, for a single headline number.
- UiStatStrip: Horizontal strip of several icon, value and label stats in one card.
- UiCountryRow: Row with a country code badge, amount, country name and a percentage change.
- UiVersusBar: Head-to-head comparison of two values with a proportional two-color bar.
- UiSegBar: Single stacked bar split into proportional segments with a legend, for distributions.
- UiMiniChart: Tiny sparkline in bar or line form for trends inside cards and tables.
- UiChartCard: Card shell for a chart with title, subtitle and an optional overflow menu; put the chart in the default slot.
- UiRing: Circular progress gauge with a percentage in the center and a tick scale around it.
- UiOccupancyChart: Bar chart of percentages by label, such as hotel occupancy per day or month.
- UiSalesFunnel: Horizontal funnel of steps with bars scaled to the largest value, for conversion flows.
- UiSystemStatus: List of services with a status dot and a value such as uptime or latency.
- UiUserCell: Avatar with a name and optional subtitle, for table cells and lists of people.
- UiIconTile: Square or circular tinted tile holding an icon, used as a leading visual in lists and cards.
- UiStatusIcon: Round tinted icon with a hover and focus tooltip, for compact status markers.
- UiHeroBanner: Wide promotional banner with title, text, a big value, optional action and a background image.
- UiTabTiles: Row of icon tiles that work as tabs, with an optional add button.
- UiPricingCard: Pricing plan card with price, feature list and a select button.
- UiIntegrationCard: Card for a third-party integration showing its connection status and a connect or manage button.

## Feedback
Alerts, progress and states.
- UiAlert: Inline message block with a tone icon, optional title and close button; use for form errors, notices and results inside a page.
- UiBanner: Full-width Alert without rounded corners; use at the top of a page or section for system-wide notices.
- UiToast: Static toast card with a tone icon, title and text; use for transient confirmations rendered in your own toast stack.
- UiSnackbar: Compact dark bar with a message and one optional action; use for undo and short confirmations at the bottom of the screen.
- UiProgress: Horizontal progress bar with optional label and meta text; use for uploads, quotas and completion.
- UiSpinner: Inline loading indicator; use inside buttons, cards or next to a loading label.
- UiSkeleton: Shimmering placeholder for content that is loading; use text lines, circles or rectangles that match the final layout.
- UiEmptyState: Centered icon (or image), title and description with optional actions; use when a list, search or section has no content.
- UiErrorPage: Full-page error with a large code, title and description; use for 404, 500 and similar screens.
- UiStatusPage: Ready-made full-page status screen (404, 401, maintenance, coming soon) with one action button.
- UiDataState: Switches between loading, empty, error, offline and the real content based on one state value; wrap any data-driven block with it.
- UiLoadingOverlay: Wrapper that dims its content and shows a spinner on top while loading; use over cards, tables or forms during a refresh.

## Overlay
Dialogs, sheets and popovers.
- UiModal: Centered dialog with a title, close button, body and optional footer; use for forms and focused tasks that block the page.
- UiDrawer: Side panel that slides over the page; use for filters, details and secondary forms.
- UiConfirmDialog: Small Modal with a message and Cancel/Confirm buttons; use to confirm destructive or irreversible actions.
- UiPopconfirm: Button that opens a small confirmation popover with cancel/confirm buttons (No/Yes by default); use for quick inline confirmation of a single action.
- UiStepDialog: Wide Modal with a vertical step list on the left and Previous/Next buttons; use for multi-step wizards.
- UiFullscreenDialog: Full-screen dialog with a close button, title and Save action in the header; use for long editing flows on mobile.
- UiBottomSheet: Panel anchored to the bottom of the screen with a grab handle; use for mobile pickers and short forms.
- UiActionsheet: Bottom sheet with a list of actions and a Cancel button; use for mobile "more actions" menus.
- UiPopover: Button that toggles a floating panel with arbitrary content; use for small forms and extra info next to a control.
- UiHoverCard: Rich card shown on hover or keyboard focus of a trigger; use for previews of users, links or entities.
- UiTooltip: Short text bubble shown on hover or focus of the wrapped element; use for icon-only controls and hints.
- UiDropdown: Button that opens a menu of actions; use for "more" menus and action lists.
- UiMenu: Static vertical list of actions rendered inline; use in sidebars and custom popovers.
- UiContextMenu: Wraps an area and shows a menu at the cursor on right click; use for row and canvas actions.
- UiCommandBar: Floating glass toolbar of icon buttons; use for selection actions or editor tools.
- UiCommandPalette: Searchable list of commands in a top-aligned dialog; use for a Cmd+K launcher.
- UiImageViewer: Full-screen lightbox for one or several images with previous/next buttons and a counter.
- UiTour: Guided product tour that dims the page, highlights a target element and shows a step popover.
- UiTourPopover: Step card of a tour with title, text, step counter and Back/Next buttons; used by Tour and usable standalone.
- UiScreensaver: Full-screen idle screen with a large clock, date and the brand mark; show it after inactivity.

## Navigation
Menus, tabs and paging.
- UiTopNav: Horizontal app header with a brand area, navigation items and an actions area.
- UiSideNav: Vertical sidebar with a brand, grouped navigation items, a footer and an optional collapse toggle.
- UiSubNav: Compact vertical list of sections with an optional title; use for settings and secondary page navigation.
- UiTabs: Underlined tab strip for switching between views of the same page.
- UiPillTabs: Pill-style tab buttons with optional icons, horizontal or vertical; use for settings and profile sections.
- UiBreadcrumbs: Path trail with chevron separators; the last item is the current page.
- UiPagination: Page navigation with numbered buttons, ellipsis windowing and previous/next; use under tables and lists.
- UiAccordion: Vertical list of collapsible sections where one is open at a time; use for FAQs and grouped details.

## Media and icons
Avatars, images, maps and icons.
- UiAvatar: Round user picture that falls back to initials when there is no image.
- UiIcon: Renders a named icon from the library at a chosen size.
- UiLazyImage: Image box with a fixed aspect ratio and rounded corners, rendered as a background image.
- UiGallery: Large image with a counter and a thumbnail strip for browsing a set of photos.
- UiCarousel: Slideshow of image slides with captions, arrows and dot pagination.
- UiMap: Interactive raster map with panning, zoom buttons and clickable markers, using OpenStreetMap data via CARTO tiles.
- UiProfileHeader: Profile card with a cover image, large avatar, name and a row of meta items.
- UiChatAi: Chat panel with message bubbles, a typing indicator and an input, for AI assistant UIs.

## Domain
Umrah, Hajj, hotel and CRM blocks.
- UiHotelCard: Hotel listing card with photo, tags, stars, distance, rating and nightly price; use in catalogs and search results.
- UiTourCard: Tour or virtual-tour card with session count and a seat-occupancy bar.
- UiPrayerTimes: Row of daily prayer times with the upcoming prayer highlighted.
- UiRamadanTracker: Thirty-day Ramadan progress strip; the last ten days and odd nights are marked.
- UiBookingCard: Compact booking summary: code, status, guest, hotel, dates and total.
- UiGuestCard: Guest profile card with avatar, country, stay length and tags.
- UiRoomGrid: Tile grid of rooms colored by housekeeping status; use for front-desk room selection.
- UiRoomCalendar: Gantt-style occupancy calendar: rooms as rows, days as columns, bookings as bars.
- UiLeadCard: CRM lead card with avatar, code, phone and amount.
- UiDealCard: CRM deal card with stage badge, amount, win probability and owner; the card type inside PipelineBoard.
- UiPipelineBoard: Horizontally scrolling kanban pipeline of stage columns filled with DealCards.
- UiContactPanel: Contact detail card with avatar, role, contact fields and Call / Message buttons.
- UiKanbanColumn: Single kanban column with a title, count badge and stacked cards.
- UiKanbanCard: Simple kanban card with title, subtitle, free content and an optional tag.
- UiCallRow: One-line call log row with avatar, status, duration and a play button.
- UiCallCard: Call recording card with status badge, a playback progress bar and duration.
- UiIncomingCall: Glass banner for an incoming call with Decline and Answer buttons.
- UiAuthSplit: Two-column sign-in layout with a brand panel on the left and the form on the right.
- UiAuthShowcase: Sign-in layout with a media panel: dark photo card with floating avatars, light gradient card with a social-proof pill, or a tinted panel with a glass caption. The default slot is the form.
- UiSocialAuth: Continue with Google and Apple buttons with an "or" divider. Place it under the sign-in form.

## Page templates
Ready layouts with named slots.
- UiPageDashboard: Dashboard template: greeting hero, KPI tiles, occupancy chart, sales funnel, top list and activity feed.
- UiPagePatterns: Showcase template combining twelve recurring dashboard card patterns (banner, strips, stat lines, charts, lists).
- UiPageCrm: CRM template: summary tiles, filters, pipeline board and call queue.
- UiPageBookings: Bookings list template: stats, toolbar, bulk-action bar, table and pagination.
- UiPageCatalog: Catalog template with a filter sidebar and a card grid (hotels, tours).
- UiPageDetail: Detail page template (hotel, tour): gallery, summary, tabs, history and a booking side card.
- UiPageSettings: Settings template with a section sub-navigation and stacked settings sections.
- UiPageUserList: User or customer list template: stats, filters, toolbar, table and a right-hand add/edit drawer.
- UiPageProfile: User profile template: cover header, tabs and two columns of about, activity and plan cards.
- UiPageForm: Create/edit form template: main column, media, side column and header actions.
- UiPageOrder: Order/booking details template: status chips, items table, timeline and side info cards.
- UiPageAccount: Account settings template with pill tabs and a swappable panel.
- UiPagePricing: Pricing template: billing-period toggle, plan cards and an FAQ.
- UiPageFaq: Help center template: search, categories, answers accordion and a contact block.
- UiPageAuth: Sign-in page template without the app shell, as a centered card or a split layout.
- UiPageStatus: Full-page status screen (404, 401, maintenance, coming soon) with one action.

Page templates: UiPageDashboard (header, hero, kpis, occupancy, funnel, top, activity); UiPageCrm (header, summary, filters, board, calls); UiPageBookings (header, stats, toolbar, bulk, table, pager); UiPageCatalog (header, filters, toolbar, grid, pager); UiPageDetail (header, gallery, summary, tabs, booking, history); UiPageSettings (header, subnav, profile, notifications, integrations, danger); UiPageAuth (background, logo, form, footer); UiPagePatterns (header, hero, strip, statlines, chartcard, listrows, countries, tiles, versus, segbar, activity, actioncard); UiPageUserList (header, stats, filters, toolbar, table, drawer); UiPageProfile (profile, tabs, about, activity, plan); UiPageForm (header, main, media, side, actions); UiPageOrder (header, status, items, shipping, side); UiPageAuth (aside, logo, form, footer); UiPageStatus (code, message, action); UiPageAccount (header, tabs, panel); UiPageFaq (search, cats, answers, contact); UiPagePricing (toggle, plans, faq)

Full API of every component: llms-full.txt