@ziyarago/ui 0.0.0-stage → 0.1.1

package/dist/llms.txt

@@ -0,0 +1,239 @@
+# @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, 160+ components and 16 page templates.
+
+Version 0.1.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.
+
+## 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