@ziyarago/ui 0.0.0-stage → 0.1.0

package/src/meta/data.js

@@ -0,0 +1,327 @@
+// API metadata for the data group. Format: see src/meta/README.md
+const SZ = ['xs', 'sm', 'md', 'lg', 'xl'];
+const SIZE = "'xs' | 'sm' | 'md' | 'lg' | 'xl'";
+const TONES = ['brand', 'sky', 'success', 'warning', 'danger', 'neutral'];
+const TONE = "'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral'";
+const size = (d, extra) => ({ type: SIZE, values: SZ, default: d || 'md', description: extra || 'Component scale.' });
+const delta = (d) => ({ type: 'string', description: d || 'Change indicator such as "+12%" or "-3.4%". A leading "-" renders as a decrease, anything else as an increase.' });
+
+export default {
+  Card: {
+    description: 'Glass surface container with an optional title header, used to group related content.',
+    props: {
+      title: { type: 'string', description: 'Header title. The header renders only when title or the actions slot is set.' },
+      subtitle: { type: 'string', description: 'Muted line under the title.' },
+      variant: { type: "'inverse' | 'gradient'", values: ['inverse', 'gradient'], description: 'inverse is a dark card regardless of the page theme; gradient is a tinted gradient card colored by tone. Omit for the default glass card.' },
+      tone: { type: "'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral' | 'rose' | 'violet'", values: ['brand', 'sky', 'success', 'warning', 'danger', 'neutral', 'rose', 'violet'], default: 'brand', description: 'Gradient color. Used only with variant="gradient".' },
+      intensity: { type: "'vivid'", values: ['vivid'], description: 'With variant="gradient", fills the card with a saturated color instead of a soft tint.' },
+      size: size('md', 'Padding, gap and title size.'),
+    },
+    slots: { default: 'Card body.', actions: 'Right side of the header, for buttons or menus.' },
+    notes: ['Vue slot names are React props (actions) and children (default).'],
+  },
+
+  DataTable: {
+    description: 'Table with sortable columns, custom cell rendering and optional row selection checkboxes.',
+    props: {
+      columns: { type: '{ key: string; label: string; sortable?: boolean; num?: boolean; render?: (value, row, h) => VNode | string }[]', required: true, default: [], description: 'Column definitions. key reads row[key]; num right-aligns numbers; render customizes the cell; sortable shows a sort button in the header.' },
+      rows: { type: '({ id: string | number; [key: string]: any })[]', required: true, default: [], description: 'Row objects. Every row needs a unique id; missing cell values render as an em dash.' },
+      selected: { type: '(string | number)[]', default: [], description: 'Ids of selected rows. Checkboxes show only when the select event is handled.' },
+      sortKey: { type: 'string', description: 'Key of the column currently sorted. The component does not sort rows itself.' },
+      sortDir: { type: "'asc' | 'desc'", values: ['asc', 'desc'], default: 'asc', description: 'Direction of the current sort, shown by the header arrow and aria-sort.' },
+      empty: { type: 'string', default: '—', description: 'Text shown when rows is empty.' },
+      labels: { type: '{ selectAll?: string; selectRow?: string }', default: "{ selectAll: 'Select all', selectRow: 'Select row' }", description: 'Accessible names of the selection checkboxes.' },
+      size: size('md', 'Row density and font size.'),
+    },
+    events: {
+      select: 'Called with the new array of selected row ids. Handling it enables the checkbox column and select-all.',
+      sort: 'Called with (key, dir) where dir is "asc" or "desc". Sort the rows yourself and pass sortKey/sortDir back.',
+    },
+    notes: ['Sorting and selection are fully controlled: the table never reorders rows or stores selection.', 'render receives (value, row) and, in React/Vue, the h function as third argument.'],
+  },
+
+  DataGroup: {
+    description: 'Table whose rows are collapsed into labeled groups, with optional per-row expandable details.',
+    props: {
+      columns: { type: '{ key: string; label: string; num?: boolean; render?: (value, row) => VNode | string }[]', required: true, default: [], description: 'Column definitions, same shape as DataTable without sorting.' },
+      groups: { type: '{ label: string; rows: ({ id: string | number; [key: string]: any })[] }[]', required: true, default: [], description: 'Groups shown as collapsible header rows with a row count. Group labels must be unique.' },
+      expand: { type: '(row) => VNode | string', description: 'Renders the detail panel under a row. When set, an expand chevron column appears.' },
+      size: size('md', 'Row density and font size.'),
+    },
+    notes: ['Open/collapsed state is internal; groups start expanded.'],
+  },
+
+  Descriptions: {
+    description: 'Definition list of label and value pairs for record details.',
+    props: {
+      items: { type: '{ label: string; value?: string | number | VNode }[]', required: true, default: [], description: 'Pairs rendered as dt/dd. Missing value renders an em dash.' },
+      size: size('md', 'Font size and spacing.'),
+    },
+  },
+
+  Timeline: {
+    description: 'Vertical list of events connected by a line, for activity history and status progress.',
+    props: {
+      items: { type: '{ title: string; text?: string; time: string }[]', required: true, default: [], description: 'Events from top to bottom. title is bold, text is optional detail, time is the caption.' },
+      size: size('md', 'Dot, spacing and font size.'),
+    },
+  },
+
+  TreeView: {
+    description: 'Expandable tree of nodes for hierarchies such as folders, categories or regions.',
+    props: {
+      nodes: { type: '{ id: string; label: string; icon?: string; children?: Node[] }[]', required: true, default: [], description: 'Root nodes. children nest recursively; icon is an icon name. Ids must be unique.' },
+      selected: { type: 'string', description: 'Id of the highlighted node.' },
+      size: size('md', 'Row height and font size.'),
+    },
+    events: { select: 'Called with the node id when a node is clicked. Nodes with children also toggle open.' },
+    notes: ['The first level is open by default; deeper levels start collapsed.'],
+  },
+
+  CalendarView: {
+    description: 'Month calendar that marks days with events, wrapping Calendar with a list-style events prop.',
+    props: {
+      events: { type: '{ date: string; label: string }[]', default: [], description: 'Marked days. date is "YYYY-MM-DD"; label shows as the day tooltip.' },
+      modelValue: { type: 'string | number | Date', model: true, forwarded: true, description: 'Selected date. Vue v-model, React modelValue + onChange.' },
+      locale: { type: 'string', default: 'en-GB', forwarded: true, description: 'BCP 47 locale for month and weekday names.' },
+      weekStartsOn: { type: '0 | 1 | 2 | 3 | 4 | 5 | 6', values: [0, 1, 2, 3, 4, 5, 6], default: 1, forwarded: true, description: 'First day of the week, 0 is Sunday and 1 is Monday.' },
+    },
+    events: { change: 'Called with the clicked Date (local time). Forwarded to Calendar.' },
+  },
+
+  KpiTile: {
+    description: 'Key metric tile with a label, large value and optional delta, for dashboards.',
+    props: {
+      label: { type: 'string', required: true, description: 'Metric name.' },
+      value: { type: 'string | number', required: true, description: 'Main value, shown large.' },
+      sub: { type: 'string', description: 'Small text next to the delta.' },
+      delta: delta(),
+      variant: { type: "'brand' | 'inverse'", values: ['brand', 'inverse'], description: 'Filled brand tile or dark inverse tile. Omit for the default glass tile.' },
+      size: size('md', 'Padding and value size.'),
+    },
+  },
+
+  KpiInline: {
+    description: 'Compact inline metric with a label, value and delta, for toolbars and card headers.',
+    props: {
+      label: { type: 'string', required: true, description: 'Metric name.' },
+      value: { type: 'string | number', required: true, description: 'Main value.' },
+      delta: delta(),
+      size: size('md', 'Value font size.'),
+    },
+  },
+
+  StatsCard: {
+    description: 'Metric card with an optional icon, value and an up or down trend.',
+    props: {
+      label: { type: 'string', required: true, description: 'Metric name.' },
+      value: { type: 'string | number', required: true, description: 'Main value.' },
+      icon: { type: 'string', description: 'Icon name shown before the label.' },
+      delta: { type: 'string', description: 'Change text such as "12%". The arrow is added automatically from trend.' },
+      trend: { type: "'up' | 'down'", values: ['up', 'down'], default: 'up', description: 'Direction and color of the delta.' },
+      size: size('md', 'Padding and value size.'),
+    },
+  },
+
+  StatRow: {
+    description: 'List row with an icon tile, title, subtitle and a right-aligned value with delta.',
+    props: {
+      title: { type: 'string', required: true, description: 'Primary text.' },
+      sub: { type: 'string', description: 'Muted secondary text.' },
+      value: { type: 'string | number', description: 'Right-aligned value.' },
+      delta: delta('Change shown under the value. A leading "-" is a decrease; the sign is stripped and an arrow added.'),
+      icon: { type: 'string', description: 'Icon name for the leading tile.' },
+      tone: { type: TONE, values: TONES, default: 'brand', description: 'Color of the icon tile. Unknown values fall back to brand.' },
+      size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | number", values: SZ, default: 'md', description: 'Row height and icon tile size. Named sizes map to a 28/34/40/48/56 px tile; a number is used as the tile size in px.' },
+    },
+  },
+
+  StatLine: {
+    description: 'Card with a large value, icon tile, label and an accent bar, for a single headline number.',
+    props: {
+      label: { type: 'string', required: true, description: 'Metric name under the value.' },
+      value: { type: 'string | number', required: true, description: 'Main value.' },
+      icon: { type: 'string', description: 'Icon name for the tile.' },
+      tone: { type: TONE, values: TONES, default: 'brand', description: 'Accent color of the tile and bar. Unknown values fall back to brand.' },
+      delta: delta(),
+      size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | number", values: SZ, default: 'md', description: 'Icon tile size. Named sizes map to 28/34/40/48/56 px; a number is used in px.' },
+    },
+  },
+
+  StatStrip: {
+    description: 'Horizontal strip of several icon, value and label stats in one card.',
+    props: {
+      items: { type: '{ icon?: string; tone?: ' + TONE + '; value: string | number; label: string }[]', required: true, default: [], description: 'Stats shown side by side. tone defaults to brand.' },
+      size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | number", values: SZ, default: 'md', description: 'Icon tile size. Named sizes map to 30/36/44/52/60 px; a number is used in px.' },
+    },
+  },
+
+  CountryRow: {
+    description: 'Row with a country code badge, amount, country name and a percentage change.',
+    props: {
+      code: { type: 'string', required: true, description: 'Short code shown in the circle, such as "UZ".' },
+      name: { type: 'string', required: true, description: 'Country name.' },
+      amount: { type: 'string | number', required: true, description: 'Formatted amount shown in bold.' },
+      pct: delta('Percentage change such as "+8%" or "-2%".'),
+    },
+  },
+
+  VersusBar: {
+    description: 'Head-to-head comparison of two values with a proportional two-color bar.',
+    props: {
+      left: { type: '{ label: string; value: number }', required: true, description: 'Left side. Its share of the bar is value / (left.value + right.value) in the brand color.' },
+      right: { type: '{ label: string; value: number }', required: true, description: 'Right side, filling the remainder of the bar in sky.' },
+      size: size('md', 'Value font size and bar thickness.'),
+    },
+    notes: ['A missing side renders an empty label and 0; with both at 0 the bar is split with no brand share.'],
+  },
+
+  SegBar: {
+    description: 'Single stacked bar split into proportional segments with a legend, for distributions.',
+    props: {
+      segments: { type: '{ label: string; value: number; color?: string }[]', required: true, default: [], description: 'Segments; widths are value / sum of values. color is any CSS color; the default cycles brand, sky, green, amber, red.' },
+    },
+  },
+
+  MiniChart: {
+    description: 'Tiny sparkline in bar or line form for trends inside cards and tables.',
+    props: {
+      values: { type: 'number[]', required: true, default: [], description: 'Non-negative data points, scaled to the maximum value.' },
+      type: { type: "'bar' | 'line'", values: ['bar', 'line'], default: 'bar', description: 'Bar columns or a single line.' },
+      highlightLast: { type: 'boolean', default: false, description: 'Bar type only: paints the last bar in the brand color.' },
+      height: { type: 'number', description: 'Height in px. Overrides size when set.' },
+      size: { type: SIZE, values: SZ, default: 'md', description: 'Preset height: xs 28, sm 36, md 48, lg 64, xl 80 px.' },
+    },
+    notes: ['The chart is decorative (no axes or values); pair it with a visible number.'],
+  },
+
+  ChartCard: {
+    description: 'Card shell for a chart with title, subtitle and an optional overflow menu; put the chart in the default slot.',
+    props: {
+      title: { type: 'string', required: true, description: 'Card title.' },
+      subtitle: { type: 'string', description: 'Muted line under the title.' },
+      menu: { type: 'string[]', description: 'Labels of overflow menu items shown behind a three-dot button. An item named "Delete" is styled as danger.' },
+      size: size('md', 'Padding, gap and title size.'),
+    },
+    slots: { default: 'Chart or any content shown below the header.' },
+    events: { menu: 'Called with the clicked menu item label (the string from menu); the menu closes afterwards.' },
+  },
+
+  Ring: {
+    description: 'Circular progress gauge with a percentage in the center and a tick scale around it.',
+    props: {
+      value: { type: 'number', required: true, default: 0, description: 'Progress from 0 to 100; values are clamped.' },
+      label: { type: 'string', description: 'Caption under the percentage.' },
+      color: { type: 'string', default: 'var(--zg-brand)', description: 'Any CSS color for the arc and ticks.' },
+      thickness: { type: 'number', description: 'Stroke width in px. Defaults to about 8% of the diameter, minimum 8.' },
+      ticks: { type: 'boolean', default: true, description: 'Shows the outer 60-tick scale; false removes it and enlarges the arc.' },
+      valueSize: { type: 'number', description: 'Percentage font size in px. Defaults to 22% of the diameter.' },
+      size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | number", values: SZ, default: 'md', description: 'Diameter: xs 72, sm 120, md 180, lg 240, xl 300 px; a number is used as px.' },
+    },
+  },
+
+  OccupancyChart: {
+    description: 'Bar chart of percentages by label, such as hotel occupancy per day or month.',
+    props: {
+      values: { type: 'number[]', required: true, default: [], description: 'Percentages from 0 to 100, one per bar. Values above 90 are highlighted in brand color.' },
+      labels: { type: 'string[]', default: [], description: 'Axis label under each bar, matched by index.' },
+    },
+  },
+
+  SalesFunnel: {
+    description: 'Horizontal funnel of steps with bars scaled to the largest value, for conversion flows.',
+    props: {
+      steps: { type: '{ label: string; value: number }[]', required: true, default: [], description: 'Steps from top to bottom. Bars scale to the max value; the last step is highlighted in brand color.' },
+    },
+  },
+
+  SystemStatus: {
+    description: 'List of services with a status dot and a value such as uptime or latency.',
+    props: {
+      items: { type: "{ name: string; value: string; state?: 'ok' | 'warn' | 'down' }[]", required: true, default: [], description: 'Services. state sets the color: ok green (default), warn amber, down red.' },
+    },
+  },
+
+  UserCell: {
+    description: 'Avatar with a name and optional subtitle, for table cells and lists of people.',
+    props: {
+      name: { type: 'string', required: true, description: 'Display name, also used for avatar initials.' },
+      sub: { type: 'string', description: 'Muted line under the name, such as an email or role.' },
+      src: { type: 'string', description: 'Avatar image URL. Initials are shown without it.' },
+      size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | number", values: SZ, default: 'md', description: 'Avatar diameter: xs 24, sm 30, md 36, lg 44, xl 56 px; a number is used as px.' },
+    },
+  },
+
+  IconTile: {
+    description: 'Square or circular tinted tile holding an icon, used as a leading visual in lists and cards.',
+    props: {
+      icon: { type: 'string', default: 'circle', description: 'Icon name.' },
+      tone: { type: TONE, values: TONES, default: 'brand', description: 'Tint color. Unknown values fall back to brand.' },
+      shape: { type: "'square' | 'circle'", values: ['square', 'circle'], default: 'square', description: 'Rounded square or full circle. Only "circle" changes the shape.' },
+      size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | number", values: SZ, default: 'md', description: 'Tile size: xs 28, sm 32, md 40, lg 48, xl 56 px; a number is used as px. The icon is half the tile.' },
+    },
+  },
+
+  StatusIcon: {
+    description: 'Round tinted icon with a hover and focus tooltip, for compact status markers.',
+    props: {
+      icon: { type: 'string', default: 'circle', description: 'Icon name.' },
+      tone: { type: TONE, values: TONES, default: 'brand', description: 'Tint color. Unknown values fall back to brand.' },
+      tip: { type: 'string', description: 'Tooltip text shown on hover and keyboard focus.' },
+      size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | number", values: SZ, default: 'md', description: 'Diameter: xs 24, sm 30, md 36, lg 44, xl 52 px; a number is used as px.' },
+    },
+    notes: ['Focusable (tabindex 0) so the tooltip works from the keyboard; the icon itself is aria-hidden, so put the meaning in tip.'],
+  },
+
+  HeroBanner: {
+    description: 'Wide promotional banner with title, text, a big value, optional action and a background image.',
+    props: {
+      title: { type: 'string', required: true, description: 'Banner heading.' },
+      text: { type: 'string', description: 'Supporting paragraph.' },
+      value: { type: 'string | number', description: 'Large number or price shown under the text.' },
+      cta: { type: 'string', description: 'Label of the primary button. The button renders only when set.' },
+      image: { type: 'string', description: 'Image URL shown on the right side.' },
+    },
+    events: { cta: 'Called when the call-to-action button is clicked.' },
+    slots: { default: 'Extra content placed before the button.' },
+  },
+
+  TabTiles: {
+    description: 'Row of icon tiles that work as tabs, with an optional add button.',
+    props: {
+      items: { type: '{ value: string; label: string; icon?: string }[]', required: true, default: [], description: 'Tiles. icon defaults to circle.' },
+      value: { type: 'string', description: 'Value of the active tile. Controlled; change it in the change handler.' },
+      addable: { type: 'boolean', default: false, description: 'Shows a trailing plus tile that fires the add event.' },
+    },
+    events: { change: 'Called with the value of the clicked tile.', add: 'Called when the plus tile is clicked.' },
+    notes: ['Active state is exposed as aria-pressed on buttons, not as a tablist.'],
+  },
+
+  PricingCard: {
+    description: 'Pricing plan card with price, feature list and a select button.',
+    props: {
+      name: { type: 'string', required: true, description: 'Plan name.' },
+      price: { type: 'string | number', required: true, description: 'Price text, shown large.' },
+      period: { type: 'string', description: 'Suffix after the price, such as "/mo".' },
+      features: { type: 'string[]', default: [], description: 'Feature bullets with check icons.' },
+      badge: { type: 'string', description: 'Brand badge next to the name, such as "Popular".' },
+      featured: { type: 'boolean', default: false, description: 'Highlights the card and makes the button primary.' },
+      cta: { type: 'string', default: 'Choose', description: 'Button label.' },
+      size: size('md', 'Card padding and title size.'),
+    },
+    events: { select: 'Called when the button is clicked.' },
+  },
+
+  IntegrationCard: {
+    description: 'Card for a third-party integration showing its connection status and a connect or manage button.',
+    props: {
+      name: { type: 'string', required: true, description: 'Integration name.' },
+      description: { type: 'string', description: 'Short explanation under the name.' },
+      status: { type: "'connected' | 'error' | 'off'", values: ['connected', 'error', 'off'], default: 'off', description: 'Connection state. Sets the badge (Connected, Error, Not linked) and button (Manage, Reconnect, Link).' },
+      labels: { type: '{ connected?: string; error?: string; off?: string; manage?: string; reconnect?: string; link?: string }', default: "{ connected: 'Connected', error: 'Error', off: 'Not linked', manage: 'Manage', reconnect: 'Reconnect', link: 'Link' }", description: 'Badge and button texts per status; missing keys keep the English defaults.' },
+      size: size('md', 'Card padding and title size.'),
+    },
+    events: { toggle: 'Called when the button is clicked, for connecting, reconnecting or managing.' },
+    notes: ['Translate badge and button texts with labels.', 'Unknown status values behave as "off".'],
+  },
+};

package/src/meta/domain.js

@@ -0,0 +1,212 @@
+// API metadata for the domain group. Format: see src/meta/README.md
+const SZ = "'xs' | 'sm' | 'md' | 'lg' | 'xl'";
+const size = { type: SZ, values: ['xs', 'sm', 'md', 'lg', 'xl'], default: 'md', description: 'Scales padding, text and avatars.' };
+const TONES = "'default' | 'brand' | 'success' | 'warning' | 'danger' | 'info'";
+const toneValues = ['default', 'brand', 'success', 'warning', 'danger', 'info'];
+
+export default {
+  HotelCard: {
+    description: 'Hotel listing card with photo, tags, stars, distance, rating and nightly price; use in catalogs and search results.',
+    props: {
+      name: { type: 'string', required: true, description: 'Hotel name.' },
+      image: { type: 'string', description: 'Photo URL, used as the card background image.' },
+      tags: { type: 'string[]', default: '[]', description: 'Brand badges over the photo, e.g. "Haram view".' },
+      stars: { type: 'number', default: 0, description: 'Star class 0-5, rendered as repeated stars.' },
+      distance: { type: 'string', description: 'Distance caption next to the stars, e.g. "120 m to the Haram".' },
+      rating: { type: 'string | number', description: 'Guest rating shown in a green badge, e.g. 9.2.' },
+      price: { type: 'number', description: 'Price per unit, formatted with thousand separators; the currency label is fixed to SAR.' },
+      night: { type: 'string', default: 'night', description: 'Unit after "SAR /", e.g. "night".' },
+      size,
+    },
+    notes: ['Currency is hard-coded to SAR.', 'Wrap in a clickable element yourself; the card has no click handler.'],
+  },
+  TourCard: {
+    description: 'Tour or virtual-tour card with session count and a seat-occupancy bar.',
+    props: {
+      name: { type: 'string', required: true, description: 'Tour title.' },
+      city: { type: 'string', description: 'City shown in the subtitle.' },
+      sessions: { type: 'number', description: 'Number of sessions, shown as "N sessions".' },
+      booked: { type: 'number', required: true, description: 'Seats already booked.' },
+      seats: { type: 'number', required: true, description: 'Total seats; the bar shows booked / seats.' },
+      size,
+    },
+    slots: { actions: 'Footer actions, usually Buttons.' },
+    notes: ['A fixed "360°" badge is always shown.', 'With seats = 0 or missing the bar is empty (0%) and the meta reads "0/0".'],
+  },
+  PrayerTimes: {
+    description: 'Row of daily prayer times with the upcoming prayer highlighted.',
+    props: {
+      items: { type: '{ name: string; time: string }[]', default: '[]', description: 'Prayers in display order; time is shown as-is, e.g. "05:12".' },
+      next: { type: 'number', description: 'Index in items of the next prayer; sets aria-current on it.' },
+      size,
+    },
+  },
+  RamadanTracker: {
+    description: 'Thirty-day Ramadan progress strip; the last ten days and odd nights are marked.',
+    props: {
+      day: { type: 'number', required: true, description: 'Current day 1-30. Earlier days render as past, later days as upcoming.' },
+      size,
+    },
+    notes: ['Exposed as role="img" with aria-label "Day N of 30".'],
+  },
+  BookingCard: {
+    description: 'Compact booking summary: code, status, guest, hotel, dates and total.',
+    props: {
+      code: { type: 'string', required: true, description: 'Booking reference, monospaced.' },
+      status: { type: "'Confirmed' | 'Pending' | 'Cancelled' | string", values: ['Confirmed', 'Pending', 'Cancelled'], description: 'Status text. Confirmed is green, Pending amber, Cancelled red; any other value gets a neutral badge.' },
+      guest: { type: 'string', description: 'Guest name, also drives the avatar initials.' },
+      hotel: { type: 'string', description: 'Hotel name under the guest.' },
+      dates: { type: 'string', description: 'Preformatted date range, e.g. "12-19 Mar".' },
+      amount: { type: 'number', description: 'Total, formatted as "SAR 1 200".' },
+      size,
+    },
+  },
+  GuestCard: {
+    description: 'Guest profile card with avatar, country, stay length and tags.',
+    props: {
+      name: { type: 'string', required: true, description: 'Guest name.' },
+      country: { type: 'string', description: 'Country shown in the subtitle.' },
+      nights: { type: 'number', description: 'Number of nights, shown as "N nights".' },
+      vip: { type: 'boolean', default: false, description: 'Shows a VIP badge.' },
+      tags: { type: 'string[]', default: '[]', description: 'Preference tags, e.g. "Halal", "Late check-in".' },
+      size,
+    },
+  },
+  RoomGrid: {
+    description: 'Tile grid of rooms colored by housekeeping status; use for front-desk room selection.',
+    props: {
+      rooms: { type: '{ no: string; type: string; status: "occupied" | "clean" | "dirty" | "blocked" }[]', default: '[]', description: 'Rooms; no is the room number and the unique key, type is the room class label, status sets the tile color (any other value renders neutral).' },
+      statusTones: { type: "Record<string, 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral'>", default: "{ occupied: 'brand', clean: 'success', dirty: 'warning', blocked: 'danger' }", description: 'Maps a room status to a tile tone. Merged over the defaults, so you can add custom statuses (e.g. { maintenance: "sky" }) or recolor known ones. Statuses without a tone render neutral.' },
+      size,
+    },
+    events: { select: 'Called with the room number (room.no) of the clicked tile.' },
+    notes: ['Each tile is a button; status is conveyed by color only, so add a legend.'],
+  },
+  RoomCalendar: {
+    description: 'Gantt-style occupancy calendar: rooms as rows, days as columns, bookings as bars.',
+    props: {
+      rooms: { type: '{ no: string; bookings?: { from: number; nights: number; guest: string }[] }[]', default: '[]', description: 'Rooms with their bookings; from is the zero-based day index of check-in, nights its length. guest is the cell tooltip.' },
+      days: { type: 'number', default: 14, description: 'Number of day columns, labelled 1..days.' },
+      size,
+    },
+    notes: ['Day headers are plain numbers 1..days; offset them yourself for a month view.'],
+  },
+  LeadCard: {
+    description: 'CRM lead card with avatar, code, phone and amount.',
+    props: {
+      name: { type: 'string', required: true, description: 'Lead name.' },
+      code: { type: 'string', description: 'Lead or deal code under the name, monospaced.' },
+      tag: { type: 'string', description: 'Optional badge text, e.g. a source or status.' },
+      tone: { type: TONES, values: toneValues, description: 'Badge tone for tag; neutral when omitted.' },
+      phone: { type: 'string', description: 'Phone number with a phone icon.' },
+      amount: { type: 'string | number', description: 'Amount shown on the right, rendered as given (format it yourself).' },
+      size,
+    },
+  },
+  DealCard: {
+    description: 'CRM deal card with stage badge, amount, win probability and owner; the card type inside PipelineBoard.',
+    props: {
+      title: { type: 'string', required: true, description: 'Deal title.' },
+      stage: { type: 'string', description: 'Stage badge text; no badge when omitted.' },
+      tone: { type: "'default' | 'brand' | 'success' | 'warning' | 'danger' | 'info'", values: toneValues, default: 'info', description: 'Badge tone for the stage.' },
+      amount: { type: 'string | number', description: 'Large amount, rendered as given.' },
+      probability: { type: 'number', default: 0, description: 'Win probability 0-100, shown as a progress bar and percent.' },
+      owner: { type: 'string', description: 'Owner name with avatar.' },
+      due: { type: 'string', description: 'Due date caption, right aligned.' },
+      size,
+    },
+  },
+  PipelineBoard: {
+    description: 'Horizontally scrolling kanban pipeline of stage columns filled with DealCards.',
+    props: {
+      stages: { type: '{ id: string | number; title: string; cards: DealCardProps[] }[]', default: '[]', description: 'Columns in order; cards take the DealCard props (title, stage, tone, amount, probability, owner, due). The column count badge is cards.length. Give cards an id so onMove can report which one moved (the index is used otherwise).' },
+      size,
+    },
+    events: { move: 'Called with { id, from, to } (card id, source stage id, target stage id) when a card is dropped on another stage. The board does not reorder itself: update stages in your state.' },
+    notes: ['Drag and drop is enabled only when a move handler is passed; without it the board renders and behaves as before.', 'Uses HTML5 drag and drop (mouse and desktop browsers); there is no keyboard alternative, so also offer a stage select on the card if you need one.', 'Cards are fixed to DealCard; for custom cards compose KanbanColumn and KanbanCard.'],
+  },
+  ContactPanel: {
+    description: 'Contact detail card with avatar, role, contact fields and Call / Message buttons.',
+    props: {
+      name: { type: 'string', required: true, description: 'Contact name.' },
+      role: { type: 'string', description: 'Role or company under the name.' },
+      phone: { type: 'string', description: 'Phone row.' },
+      telegram: { type: 'string', description: 'Telegram handle row.' },
+      email: { type: 'string', description: 'Email row.' },
+      city: { type: 'string', description: 'City row.' },
+      labels: { type: '{ call?: string; message?: string }', description: 'Override built-in English strings.' },
+      size,
+    },
+    events: { call: 'Called with no arguments when Call is clicked.', message: 'Called with no arguments when Message is clicked.' },
+  },
+  KanbanColumn: {
+    description: 'Single kanban column with a title, count badge and stacked cards.',
+    props: {
+      title: { type: 'string', required: true, description: 'Column heading.' },
+      count: { type: 'number', description: 'Count badge; defaults to the number of children.' },
+      size,
+    },
+    slots: { default: 'Cards, usually KanbanCard or DealCard. React passes them as children.' },
+  },
+  KanbanCard: {
+    description: 'Simple kanban card with title, subtitle, free content and an optional tag.',
+    props: {
+      title: { type: 'string', required: true, description: 'Card title.' },
+      sub: { type: 'string', description: 'Subtitle under the title.' },
+      tag: { type: 'string', description: 'Badge at the bottom.' },
+      tone: { type: TONES, values: toneValues, description: 'Badge tone for tag.' },
+      size,
+    },
+    slots: { default: 'Extra content between the subtitle and the tag. React passes it as children.' },
+  },
+  CallRow: {
+    description: 'One-line call log row with avatar, status, duration and a play button.',
+    props: {
+      name: { type: 'string', required: true, description: 'Caller name.' },
+      status: { type: 'string', description: 'Status text before the duration, e.g. "Answered".' },
+      duration: { type: 'number', description: 'Duration in seconds, formatted as "3 m 05 s" (units from durUnits); shows a dash when missing.' },
+      durUnits: { type: '{ m?: string; s?: string }', default: "{ m: 'm', s: 's' }", description: 'Minute and second unit labels for localized durations, e.g. { m: "min", s: "sec" }.' },
+      labels: { type: '{ play?: string }', description: 'Override built-in English strings. play is the aria-label of the play button.' },
+      size,
+    },
+    events: { play: 'Called with no arguments when the play button is clicked.' },
+  },
+  CallCard: {
+    description: 'Call recording card with status badge, a playback progress bar and duration.',
+    props: {
+      name: { type: 'string', required: true, description: 'Caller name.' },
+      phone: { type: 'string', description: 'Phone number.' },
+      status: { type: "'Answered' | 'Missed' | 'Voicemail' | 'Busy' | 'Declined' | string", values: ['Answered', 'Missed', 'Voicemail', 'Busy', 'Declined'], description: 'Badge text. Known statuses (case-insensitive): Answered green, Missed and Declined red, Voicemail and Busy amber, Ringing blue. Any other value is neutral. The badge is hidden when empty.' },
+      statusTones: { type: "Record<string, 'success' | 'danger' | 'warning' | 'info' | 'brand'>", description: 'Extra or overriding status to tone mapping, e.g. { "No answer": "warning" }.' },
+      progress: { type: 'number', default: 0, description: 'Playback progress 0-100.' },
+      duration: { type: 'number', description: 'Duration in seconds.' },
+      durUnits: { type: '{ m?: string; s?: string }', default: "{ m: 'm', s: 's' }", description: 'Minute and second unit labels for the duration.' },
+      labels: { type: '{ play?: string }', description: 'Override built-in English strings. play is the aria-label of the play button.' },
+      size,
+    },
+    events: { play: 'Called with no arguments when the play button is clicked.' },
+  },
+  IncomingCall: {
+    description: 'Glass banner for an incoming call with Decline and Answer buttons.',
+    props: {
+      name: { type: 'string', required: true, description: 'Caller name.' },
+      phone: { type: 'string', description: 'Caller number.' },
+      label: { type: 'string', default: 'Incoming call', description: 'Caption above the name.' },
+      onDecline: { type: '() => void', description: 'Decline button click.' },
+      onAnswer: { type: '() => void', description: 'Answer button click.' },
+      size,
+    },
+    events: { decline: 'Decline button clicked.', answer: 'Answer button clicked.' },
+  },
+  AuthSplit: {
+    description: 'Two-column sign-in layout with a brand panel on the left and the form on the right.',
+    props: {
+      title: { type: 'string', required: true, description: 'Form heading.' },
+      subtitle: { type: 'string', description: 'Text under the heading.' },
+      logo: { type: 'VNode', description: 'Logo node above the heading.' },
+      aside: { type: 'VNode', description: 'Content of the left brand panel (hidden on narrow screens).' },
+    },
+    slots: { default: 'Form content under the heading. React passes it as children.' },
+    notes: ['logo and aside are props in both Vue and React (pass a VNode / element).'],
+  },
+};