@ziyarago/ui 0.0.0-stage → 0.1.0

package/src/meta/feedback.js

@@ -0,0 +1,153 @@
+// API metadata for the feedback group. Format: see src/meta/README.md
+const SIZE = "'xs' | 'sm' | 'md' | 'lg' | 'xl'";
+const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'];
+const size = (what) => ({ type: SIZE, values: SIZES, default: 'md', description: `Scale of ${what}.` });
+const TONE4 = "'info' | 'success' | 'warning' | 'danger'";
+
+const alertProps = {
+  tone: { type: TONE4, values: ['info', 'success', 'warning', 'danger'], default: 'info', description: 'Color and icon: info, check, triangle-alert or circle-alert.' },
+  title: { type: 'string', description: 'Bold first line above the message.' },
+  size: size('padding, icon and text'),
+};
+
+export default {
+  Alert: {
+    description: 'Inline message block with a tone icon, optional title and close button; use for form errors, notices and results inside a page.',
+    props: {
+      ...alertProps,
+      banner: { type: 'boolean', default: false, description: 'Removes the border radius so the alert spans the full width like a Banner.' },
+    },
+    slots: { default: 'Message text.' },
+    events: { close: 'Called when the close button is clicked. The button is rendered only when this handler is set.' },
+    notes: ['Has role="alert", so screen readers announce it when it appears.', 'Not self-dismissing: hide it yourself in the close handler.'],
+  },
+
+  Banner: {
+    description: 'Full-width Alert without rounded corners; use at the top of a page or section for system-wide notices.',
+    props: {
+      tone: { ...alertProps.tone, forwarded: true },
+      title: { ...alertProps.title, forwarded: true },
+      size: size('padding, icon and text'),
+    },
+    slots: { default: 'Message text.' },
+    events: { close: 'Called when the close button is clicked. The button is rendered only when this handler is set.' },
+    notes: ['Same as Alert with banner enabled; all Alert props are forwarded.'],
+  },
+
+  Toast: {
+    description: 'Static toast card with a tone icon, title and text; use for transient confirmations rendered in your own toast stack.',
+    props: {
+      tone: { type: TONE4, values: ['info', 'success', 'warning', 'danger'], default: 'info', description: 'Color and icon.' },
+      title: { type: 'string', description: 'Bold first line.' },
+      size: size('padding, icon, text and max width'),
+    },
+    slots: { default: 'Message text.' },
+    notes: ['Presentational only: it has no timer, close button or positioning. Mount and unmount it yourself.', 'Has role="status".'],
+  },
+
+  Snackbar: {
+    description: 'Compact dark bar with a message and one optional action; use for undo and short confirmations at the bottom of the screen.',
+    props: {
+      tone: { type: "'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral'", values: ['brand', 'sky', 'success', 'warning', 'danger', 'neutral'], default: 'brand', description: 'Accent color; affects the tonal background (and the action color: green for success, red otherwise).' },
+      variant: { type: "'solid' | 'tonal'", values: ['solid', 'tonal'], default: 'solid', description: 'Solid inverse background or a tone-tinted one.' },
+      action: { type: 'string', description: 'Label of the action button. The button is rendered only when set.' },
+      size: size('height, padding and text'),
+    },
+    slots: { default: 'Message text.' },
+    events: { action: 'Called when the action button is clicked.', close: 'Called when the close icon is clicked. The icon is rendered only when this handler is set.' },
+    notes: ['Presentational only: no timer or positioning.'],
+  },
+
+  Progress: {
+    description: 'Horizontal progress bar with optional label and meta text; use for uploads, quotas and completion.',
+    props: {
+      value: { type: 'number', default: 0, description: 'Progress from 0 to 100; clamped to this range.' },
+      tone: { type: "'success' | 'warning' | 'danger'", values: ['success', 'warning', 'danger'], description: 'Bar color. Omit for the brand color.' },
+      label: { type: 'string', description: 'Text above the bar on the left.' },
+      meta: { type: 'string', description: 'Monospace text above the bar on the right, e.g. "64%" or "3 / 5".' },
+      size: size('bar height and label text'),
+    },
+    notes: ['Exposes role="progressbar" with aria-valuenow; the label is not linked via aria-labelledby.'],
+  },
+
+  Spinner: {
+    description: 'Inline loading indicator; use inside buttons, cards or next to a loading label.',
+    props: {
+      size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | number", values: SIZES, default: 'md', description: 'Preset (14, 16, 20, 28, 36 px) or a number of pixels.' },
+    },
+    notes: ['Has role="status" and aria-label="Loading".'],
+  },
+
+  Skeleton: {
+    description: 'Shimmering placeholder for content that is loading; use text lines, circles or rectangles that match the final layout.',
+    props: {
+      variant: { type: "'text' | 'circle' | 'rect'", values: ['text', 'circle', 'rect'], default: 'text', description: 'Shape of the placeholder.' },
+      lines: { type: 'number', default: 1, description: 'Number of stacked lines. The last of several lines is 60% wide.' },
+      width: { type: 'string', default: '100%', description: 'CSS width of each line or rect.' },
+      height: { type: 'string', description: 'CSS height. Text lines take the height from size.' },
+      size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | number", values: SIZES, default: 'md', description: 'Text line height and gap; for variant "circle" the diameter (24, 32, 40, 56, 72 px) or a number of pixels.' },
+    },
+    notes: ['Purely visual and not announced to assistive tech; pair it with aria-busy on the container.'],
+  },
+
+  EmptyState: {
+    description: 'Centered icon (or image), title and description with optional actions; use when a list, search or section has no content.',
+    props: {
+      title: { type: 'string', required: true, description: 'Bold heading.' },
+      description: { type: 'string', description: 'Supporting text under the title.' },
+      icon: { type: 'string', default: 'inbox', description: 'Icon name shown in the tile. Ignored when image is set.' },
+      image: { type: 'string', description: 'Image URL shown instead of the icon.' },
+      size: size('padding, icon tile and text'),
+    },
+    slots: { default: 'Actions (buttons) shown under the text.' },
+  },
+
+  ErrorPage: {
+    description: 'Full-page error with a large code, title and description; use for 404, 500 and similar screens.',
+    props: {
+      code: { type: 'string', default: '404', description: 'Large number shown on top.' },
+      title: { type: 'string', default: 'Page not found', description: 'Heading.' },
+      description: { type: 'string', default: 'The page may have moved. Check the address or go back.', description: 'Supporting text.' },
+    },
+    slots: { default: 'Actions (buttons) shown under the text.' },
+  },
+
+  StatusPage: {
+    description: 'Ready-made full-page status screen (404, 401, maintenance, coming soon) with one action button.',
+    props: {
+      kind: { type: "'404' | '401' | 'maintenance' | 'soon'", values: ['404', '401', 'maintenance', 'soon'], default: '404', description: 'Preset that sets the code or icon, default title, description and button label.' },
+      title: { type: 'string', description: 'Overrides the preset heading.' },
+      description: { type: 'string', description: 'Overrides the preset text.' },
+      actionLabel: { type: 'string', description: 'Overrides the button text of the 404, 401 and maintenance presets (default "Back to home").' },
+      notifyLabel: { type: 'string', default: 'Notify me', description: 'Button text for kind "soon".' },
+      emailLabel: { type: 'string', default: 'name@email.com', description: 'Placeholder of the email field for kind "soon".' },
+      codeNode: { type: 'VNode', description: 'Replaces the big code or icon. Used by PageStatus for its code slot.' },
+      messageNode: { type: 'VNode', description: 'Replaces heading and description. Used by PageStatus for its message slot.' },
+      actionNode: { type: 'VNode', description: 'Replaces the button or email form. Used by PageStatus for its action slot.' },
+    },
+    slots: { default: 'Extra content rendered after the button.' },
+    events: { action: 'Called when the main button is clicked (not used for kind "soon").', notify: 'Called with the typed email string when the Notify button of kind "soon" is clicked.' },
+    notes: ['The email is not validated: check it in your onNotify handler.'],
+  },
+
+  DataState: {
+    description: 'Switches between loading, empty, error, offline and the real content based on one state value; wrap any data-driven block with it.',
+    props: {
+      state: { type: "'ready' | 'loading' | 'empty' | 'error' | 'offline'", values: ['ready', 'loading', 'empty', 'error', 'offline'], default: 'ready', description: 'Which view to show. "ready" renders the children.' },
+      title: { type: 'string', description: 'Overrides the default heading of the non-ready views ("Loading…", "Nothing here yet", "Something went wrong", "No internet").' },
+      description: { type: 'string', description: 'Supporting text for empty, error and offline views (offline defaults to "Saved guides still work.").' },
+      retryLabel: { type: 'string', description: 'Retry button label for error ("Retry") and offline ("Try again").' },
+    },
+    slots: { default: 'Content shown when state is "ready".' },
+    events: { retry: 'Called when the retry button of the error or offline view is clicked.' },
+  },
+
+  LoadingOverlay: {
+    description: 'Wrapper that dims its content and shows a spinner on top while loading; use over cards, tables or forms during a refresh.',
+    props: {
+      loading: { type: 'boolean', default: false, description: 'Shows the overlay with the spinner.' },
+      label: { type: 'string', description: 'Text shown under the spinner.' },
+    },
+    slots: { default: 'Content covered by the overlay.' },
+  },
+};

package/src/meta/forms.js

@@ -0,0 +1,453 @@
+// API metadata for the forms group. Format: see src/meta/README.md
+const SZ = "'xs' | 'sm' | 'md' | 'lg' | 'xl'";
+const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'];
+const size = (what = 'Control height, font and padding scale.', def = 'md') => ({ type: SZ, values: SIZES, default: def, description: what });
+const label = { type: 'string', forwarded: true, description: 'Label shown above the control.' };
+const hint = { type: 'string', forwarded: true, description: 'Helper text under the control. Hidden while error is set.' };
+const error = { type: 'string', forwarded: true, description: 'Error message under the control. Turns the control red and is announced with role="alert".' };
+const placeholder = (d) => ({ type: 'string', description: d || 'Placeholder text.' });
+const disabled = { type: 'boolean', default: false, description: 'Disables the control.' };
+const optShape = '{ value: string | number; label: string; disabled?: boolean }[]';
+const change = (d) => ({ change: d });
+
+export default {
+  TextField: {
+    description: '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).',
+    props: {
+      modelValue: { type: 'string', model: true, default: '', description: 'Current value.' },
+      label, placeholder: placeholder(), hint, error,
+      type: { type: 'string', default: 'text', description: 'Native input type: text, email, tel, url, number, date, etc.' },
+      icon: { type: 'string', description: 'Leading icon name.' },
+      suffix: { type: 'VNode | string', description: 'Trailing content inside the field (unit, button, icon).' },
+      variant: { type: "'filled' | 'underlined' | 'solo'", values: ['filled', 'underlined', 'solo'], description: 'Alternative field style. Omit for the default outlined look.' },
+      density: { type: "'compact' | 'default'", values: ['compact', 'default'], default: 'default', description: 'compact uses the small control height.' },
+      disabled,
+      readonly: { type: 'boolean', default: false, description: 'Makes the input read-only.' },
+      size: size(),
+    },
+    events: change('Called with the new string on every keystroke.'),
+    notes: ['Wrapped in a label, so clicking the label focuses the input.'],
+  },
+  Textarea: {
+    description: 'Multi-line text input. Use for comments, descriptions and other long text.',
+    props: {
+      modelValue: { type: 'string', model: true, default: '', description: 'Current value.' },
+      label, placeholder: placeholder(), hint, error, disabled,
+      rows: { type: 'number', default: 4, description: 'Visible text rows.' },
+      maxlength: { type: 'number', description: 'Maximum number of characters.' },
+      size: size(),
+    },
+    events: change('Called with the new string on every keystroke.'),
+  },
+  NumberInput: {
+    description: 'Numeric stepper with minus and plus buttons and a typed value. Use for quantities, guest counts and small integers.',
+    props: {
+      modelValue: { type: 'number | null', model: true, description: 'Current number, or null/undefined when the field is empty.' },
+      placeholder: placeholder('Shown while the field is empty.'),
+      min: { type: 'number', description: 'Lower bound. Default is unbounded.' },
+      max: { type: 'number', description: 'Upper bound. Default is unbounded.' },
+      step: { type: 'number', default: 1, description: 'Amount added or subtracted by the buttons.' },
+      label, hint, error,
+      size: size(),
+    },
+    events: change('Called with the new number, or null when the field is cleared. Typed values are emitted as-is and clamped to min and max on blur; the buttons clamp immediately. Text that is not a number is not emitted and reverts to the last valid value on blur.'),
+    notes: ['The field can be fully cleared (null); the + and - buttons start from 0 when empty.', 'Decimal separators . and , are both accepted.'],
+  },
+  PasswordInput: {
+    description: 'Password field with a show/hide toggle. Use for sign-in and password change forms.',
+    props: {
+      modelValue: { type: 'string', model: true, default: '', description: 'Current password.' },
+      label, placeholder: placeholder(), hint, error,
+      autocomplete: { type: 'string', default: 'current-password', description: 'Native autocomplete token. Use "new-password" on sign-up and password-change forms so managers offer to generate one.' },
+      size: size(),
+    },
+    events: change('Called with the new string on every keystroke.'),
+    notes: ['autocomplete defaults to "current-password"; pass "new-password" for sign-up forms.'],
+  },
+  SearchInput: {
+    description: 'Compact search field with a clear button and an Enter-to-search event. Use above lists and tables.',
+    props: {
+      modelValue: { type: 'string', model: true, default: '', description: 'Current query.' },
+      placeholder: placeholder('Placeholder text. Defaults to "Search".'),
+      size: size('Field height and font size.'),
+    },
+    events: { change: 'Called with the new query on every keystroke and with "" when cleared.', search: 'Called with the current query when Enter is pressed.' },
+    notes: ['Filtering is up to you: react to change for live search or to search for submit-on-enter.'],
+  },
+  PhoneInput: {
+    description: 'Phone field with a country code dropdown. Use for contact numbers where the dial code matters.',
+    props: {
+      modelValue: { type: '{ code?: string; number?: string }', model: true, default: '{}', description: 'Object with the dial code (e.g. "+998") and the national number as typed.' },
+      countries: { type: optShape, default: "[{ value: '+966', label: 'SA +966' }, { value: '+998', label: 'UZ +998' }, { value: '+7', label: 'RU +7' }, { value: '+90', label: 'TR +90' }, { value: '+20', label: 'EG +20' }]", description: 'Dial code options. value is the code, label is what the dropdown shows.' },
+      label,
+      placeholder: placeholder('Placeholder of the number field. Defaults to "90 123 45 67".'),
+      hint,
+      error,
+      size: size(),
+    },
+    events: change('Called with a new { code, number } object when either part changes.'),
+    notes: ['When code is missing the first entry of countries is shown but not written to the model until the user picks one.'],
+  },
+  CodeInput: {
+    description: 'One-time code input rendered as separate digit cells. Use for SMS or email verification codes.',
+    props: {
+      modelValue: { type: 'string', model: true, default: '', description: 'Digits entered so far.' },
+      length: { type: 'number', default: 6, description: 'Number of cells and maximum digits.' },
+      label: { type: 'string', default: 'Code', description: 'Accessible name of the hidden input (not rendered visibly).' },
+      size: size('Cell size.'),
+    },
+    events: { ...change('Called with the digits only (non-digits stripped), at most length characters.'), complete: 'Called once with the full code when the last cell gets filled (also on paste).' },
+    notes: ['Sets autocomplete="one-time-code" so mobile keyboards offer the SMS code.'],
+  },
+  ChipInput: {
+    description: 'Input that turns typed text into removable chips. Use for tags, keywords and email lists.',
+    props: {
+      modelValue: { type: 'string[]', model: true, default: '[]', description: 'Current chips.' },
+      maxItems: { type: 'number', description: 'Maximum number of chips. Extra entries are ignored.' },
+      label, placeholder: placeholder('Placeholder, shown only while there are no chips.'), hint, error,
+      size: size(),
+    },
+    events: change('Called with the new array when a chip is added or removed.'),
+    notes: ['Enter or comma adds a chip, Backspace on empty input removes the last one. Duplicates are ignored.'],
+  },
+  InlineEdit: {
+    description: 'Text that turns into an input on click. Use for renaming and quick edits without a form.',
+    props: {
+      modelValue: { type: 'string', model: true, default: '', description: 'Current text.' },
+      emptyText: { type: 'string', default: 'Click to edit', description: 'Shown when the value is empty.' },
+      size: size(),
+    },
+    events: change('Called with the edited text on Enter or on the save button. Escape cancels.'),
+  },
+  RichEditor: {
+    description: 'Rich text editor with a formatting toolbar, built on contenteditable. Use for formatted descriptions and notes.',
+    props: {
+      modelValue: { type: 'string', model: true, default: '', description: 'HTML string.' },
+      label: { type: 'string', default: 'Editor', description: 'Label above the editor. Also the accessible name.' },
+      placeholder: placeholder('Placeholder shown when empty. Defaults to "Write something…".'),
+      sanitize: { type: 'boolean', default: false, description: 'Strip script, style, iframe, object, embed and similar tags plus on* and javascript: attributes from the emitted HTML, using a small allowlist sanitizer.' },
+      size: size(),
+    },
+    events: change('Called with the editor innerHTML on every edit or toolbar action (sanitized when sanitize is set).'),
+    notes: ['The editor only rewrites its content when modelValue differs from what is already in the DOM, so the caret is kept while typing.', 'sanitize is a best-effort allowlist, not a full XSS guarantee: sanitize on the server too before storing or rendering the HTML elsewhere.', 'Toolbar: bold, italic, underline, strikethrough, alignment, lists, quote and code block.'],
+  },
+  Select: {
+    description: 'Single-choice dropdown. Use when the user picks one value from a known list.',
+    props: {
+      modelValue: { type: 'string | number', model: true, description: 'Value of the selected option.' },
+      options: { type: optShape, required: true, default: '[]', description: 'Available options. An option with disabled: true is dimmed and cannot be chosen.' },
+      label, placeholder: placeholder('Shown when nothing is selected. Defaults to "—".'),
+      disabled,
+      size: size(),
+    },
+    events: change('Called with the value of the chosen option.'),
+    notes: ['The popup closes on outside click and on Escape (focus returns to the trigger).'],
+  },
+  MultiSelect: {
+    description: 'Dropdown with checkboxes for choosing several values. Use for filters and multi-valued fields.',
+    props: {
+      modelValue: { type: '(string | number)[]', model: true, default: '[]', description: 'Values of the selected options.' },
+      options: { type: optShape, default: '[]', description: 'Available options. An option with disabled: true cannot be toggled.' },
+      label, placeholder: placeholder('Shown when nothing is selected. Defaults to "—".'),
+      disabled,
+      size: size(),
+    },
+    events: change('Called with the new array of values after toggling an option.'),
+    notes: ['The trigger shows "N selected"; the list stays open while picking and closes on outside click or Escape.'],
+  },
+  GroupedSelect: {
+    description: 'Single-choice dropdown with option groups under headings. Use for long lists that have natural categories.',
+    props: {
+      modelValue: { type: 'string | number', model: true, description: 'Value of the selected option.' },
+      groups: { type: '{ label: string; options: { value: string | number; label: string; disabled?: boolean }[] }[]', default: '[]', description: 'Groups with a heading and their options. Option values must be unique across groups. An option with disabled: true cannot be chosen.' },
+      label, placeholder: placeholder('Shown when nothing is selected. Defaults to "—".'),
+      disabled,
+      size: size(),
+    },
+    events: change('Called with the value of the chosen option.'),
+    notes: ['The popup closes on outside click and on Escape.'],
+  },
+  Combobox: {
+    description: 'Searchable single-choice dropdown. Use for long option lists where typing to filter is faster than scrolling.',
+    props: {
+      modelValue: { type: 'string | number', model: true, description: 'Value of the selected option.' },
+      options: { type: optShape, default: '[]', description: 'Available options. Filtering is a case-insensitive match on label. An option with disabled: true cannot be chosen.' },
+      label, hint, error,
+      placeholder: placeholder('Defaults to "Search…".'),
+      emptyText: { type: 'string', default: '—', description: 'Shown when no option matches the query.' },
+      disabled,
+      size: size(),
+    },
+    events: change('Called with the value of the chosen option.'),
+    notes: ['Selecting from the list is the only way to set a value: free text is never emitted.', 'The list closes on outside click and on Escape.'],
+  },
+  TreeSelect: {
+    description: 'Dropdown with a searchable tree. Use for hierarchical choices such as regions, categories or org units.',
+    props: {
+      modelValue: { type: 'string | number', model: true, description: 'id of the selected node.' },
+      nodes: { type: '{ id: string | number; label: string; children?: Node[]; disabled?: boolean }[]', default: '[]', description: 'Tree nodes. A node with disabled: true cannot be clicked. Top level is expanded by default.' },
+      selectGroups: { type: 'boolean', default: false, description: 'Allow selecting nodes that have children. By default clicking a parent only expands it.' },
+      label, placeholder: placeholder('Shown when nothing is selected. Defaults to "—".'),
+      disabled,
+      size: size(),
+    },
+    events: change('Called with the id of the chosen node.'),
+    notes: ['Typing in the search box expands all matching branches.', 'The popup closes on outside click and on Escape.'],
+  },
+  PillSelect: {
+    description: 'Small pill-shaped dropdown button. Use for inline filters and sort controls in toolbars.',
+    props: {
+      modelValue: { type: 'string | number', model: true, description: 'Value of the selected option.' },
+      value: { type: 'string | number', description: 'Alias of modelValue, used when modelValue is not set.' },
+      options: { type: optShape, default: '[]', description: 'Available options. A missing list renders an empty menu. An option with disabled: true cannot be chosen.' },
+      placeholder: { type: 'string', description: 'Shown when value matches no option.' },
+      disabled,
+      size: size('Pill height and font size.'),
+    },
+    events: change('Called with the value of the chosen option.'),
+    notes: ['The menu closes on outside click and on Escape.'],
+  },
+  Checkbox: {
+    description: 'Boolean checkbox with an inline label. Use for opt-ins and independent yes/no choices.',
+    props: {
+      modelValue: { type: 'boolean', model: true, default: false, description: 'Checked state.' },
+      label: { type: 'string', description: 'Text next to the box.' },
+      disabled,
+      size: size('Box and label size.'),
+    },
+    events: change('Called with the toggled boolean.'),
+    notes: ['Rendered as a button with role="checkbox". When disabled it is dimmed, shows a not-allowed cursor and ignores clicks.'],
+  },
+  Switch: {
+    description: 'On/off toggle with an inline label. Use for settings that apply immediately.',
+    props: {
+      modelValue: { type: 'boolean', model: true, default: false, description: 'On state.' },
+      label: { type: 'string', description: 'Text next to the toggle.' },
+      disabled,
+      size: size('Track and label size.'),
+    },
+    events: change('Called with the toggled boolean.'),
+    notes: ['Rendered as a button with role="switch". When disabled it is dimmed, shows a not-allowed cursor and ignores clicks.'],
+  },
+  RadioGroup: {
+    description: 'Group of radio options with optional hints. Use for a short single-choice list that should stay visible.',
+    props: {
+      modelValue: { type: 'string | number', model: true, description: 'Value of the selected option.' },
+      options: { type: '{ value: string | number; label: string; hint?: string; disabled?: boolean }[]', default: '[]', description: 'Radio options. hint is a second line under the label; disabled: true disables that option only.' },
+      label,
+      disabled,
+      size: size(),
+    },
+    events: change('Called with the value of the chosen option.'),
+  },
+  OptionCard: {
+    description: 'Selectable card with title, description, price and optional image or icon. Usually rendered by OptionCards.',
+    props: {
+      title: { type: 'string', description: 'Main text.' },
+      desc: { type: 'string', description: 'Secondary text under the title.' },
+      price: { type: 'string', description: 'Right-aligned price or value text.' },
+      image: { type: 'string', description: 'Image URL shown on the left. Takes priority over icon.' },
+      icon: { type: 'string', description: 'Icon name shown in a tile on the left.' },
+      checked: { type: 'boolean', default: false, description: 'Selected state.' },
+      multiple: { type: 'boolean', default: false, description: 'Checkbox look and role instead of radio.' },
+      size: size(),
+    },
+    events: { click: 'Called when the card is pressed. Toggle checked yourself.' },
+  },
+  OptionCards: {
+    description: 'Grid of selectable OptionCards, single or multiple choice. Use for plans, room types and delivery options.',
+    props: {
+      modelValue: { type: 'string | number | (string | number)[]', model: true, description: 'Selected value, or an array of values when multiple is true.' },
+      options: { type: '{ value: string | number; title: string; desc?: string; price?: string; image?: string; icon?: string }[]', default: '[]', description: 'Cards to show. Fields are passed to OptionCard.' },
+      multiple: { type: 'boolean', default: false, description: 'Allow several selected cards. modelValue becomes an array.' },
+      min: { type: 'number', default: 220, description: 'Minimum card width in px before the grid wraps.' },
+      label,
+      size: size(),
+    },
+    events: change('Called with the value (single) or the new array of values (multiple).'),
+  },
+  Slider: {
+    description: 'Single-handle range slider with a value readout. Use for picking one number in a bounded range.',
+    props: {
+      modelValue: { type: 'number', model: true, description: 'Current value. Defaults to min.' },
+      min: { type: 'number', default: 0, description: 'Lowest value.' },
+      max: { type: 'number', default: 100, description: 'Highest value.' },
+      step: { type: 'number', default: 1, description: 'Step between values.' },
+      showValue: { type: 'boolean', default: true, description: 'Show the current value to the right of the track.' },
+      formatValue: { type: '(value: number) => string', description: 'Formats the readout, e.g. v => v + " $".' },
+      label, hint, error,
+      size: size('Track and thumb size.'),
+    },
+    events: change('Called with the new number while dragging.'),
+  },
+  RangeSlider: {
+    description: 'Two-handle slider for a min-max range. Use for price, duration or date-number filters.',
+    props: {
+      modelValue: { type: '[number, number]', model: true, description: 'Tuple [from, to]. Defaults to [min, max].' },
+      min: { type: 'number', default: 0, description: 'Lowest value.' },
+      max: { type: 'number', default: 100, description: 'Highest value.' },
+      step: { type: 'number', default: 1, description: 'Step between values.' },
+      formatValue: { type: '(value: number) => string', description: 'Formats both ends in the readout.' },
+      label,
+      size: size('Track and thumb size.'),
+    },
+    events: change('Called with a new [from, to] tuple; the handles cannot cross.'),
+  },
+  Rating: {
+    description: 'Star rating input. Use for reviews and quick feedback.',
+    props: {
+      modelValue: { type: 'number', model: true, default: 0, description: 'Number of filled stars.' },
+      max: { type: 'number', default: 5, description: 'Number of stars.' },
+      readonly: { type: 'boolean', default: false, description: 'Disables the stars, for display only.' },
+      label: { type: 'string', default: 'Rating', description: 'Accessible name of the group (not rendered visibly).' },
+      size: size('Star size: 14, 18, 20, 26 or 32 px. A number is used as the pixel size directly.'),
+    },
+    events: change('Called with the clicked star count (1..max). Clicking the current value does not reset it.'),
+  },
+  ColorPicker: {
+    description: 'Swatch row for choosing a color from presets. Use for tags, labels and theme accents.',
+    props: {
+      modelValue: { type: 'string', model: true, description: 'Selected color, same string as in presets.' },
+      presets: { type: 'string[]', default: "['#BC926A', '#5FAACC', '#3FD13F', '#E26E5F', '#E8B964', '#A98BD6', '#1B1919']", description: 'CSS colors offered as swatches.' },
+      label,
+      size: size('Swatch size.'),
+    },
+    events: change('Called with the clicked color string.'),
+    notes: ['Preset-only: there is no free color input.'],
+  },
+  Calendar: {
+    description: 'Month grid for picking one date. Use inline, or inside a popover via DatePicker.',
+    props: {
+      modelValue: { type: 'Date | string | number', model: true, description: 'Selected date: a Date, ISO string or timestamp. Also sets the visible month. A date-only string like "2026-10-21" is read as a local date, so the day does not shift with the time zone.' },
+      locale: { type: 'string', default: 'en-GB', description: 'BCP 47 locale for month and weekday names.' },
+      weekStartsOn: { type: 'number', default: 1, description: 'First day of the week: 0 = Sunday, 1 = Monday.' },
+      events: { type: 'Record<string, string>', default: '{}', description: 'Marked days: keys are YYYY-MM-DD, values are the tooltip text.' },
+      size: size('Day cell and header size.'),
+    },
+    events: change('Called with a Date object (local time) for the clicked day.'),
+    notes: ['The event payload is a Date, not a string: convert to ISO yourself if the model is a string.'],
+  },
+  RangeCalendar: {
+    description: 'Month grid for picking a date range with hover preview. Use for stays, trips and report periods.',
+    props: {
+      modelValue: { type: '[Date | string | number | null, Date | string | number | null]', model: true, description: 'Controlled range [start, end]; either end may be null. Date-only ISO strings are read as local dates. When omitted the selection is kept internally.' },
+      start: { type: 'Date | string | number', description: 'Month to show initially when no range is set. Does not preselect a range.' },
+      locale: { type: 'string', default: 'en-GB', description: 'BCP 47 locale for month and weekday names.' },
+      weekStartsOn: { type: 'number', default: 1, description: 'First day of the week: 0 = Sunday, 1 = Monday.' },
+      size: size('Day cell and header size.'),
+    },
+    events: change('Called with [start, end] Date objects. In controlled mode (modelValue set) it also fires after the first click with [start, null]; uncontrolled it fires once the second date is picked.'),
+    notes: ['Pass modelValue to control the selection; pick a date earlier than the start to restart the range.'],
+  },
+  DatePicker: {
+    description: 'Field with a calendar popup for choosing a date. Use in forms where a single date is needed.',
+    props: {
+      modelValue: { type: 'string | Date | number', model: true, description: 'Selected date (ISO string recommended, e.g. 2026-10-21).' },
+      locale: { type: 'string', default: 'en-GB', description: 'BCP 47 locale used for the trigger text and the calendar.' },
+      weekStartsOn: { type: 'number', default: 1, description: 'First day of the week: 0 = Sunday, 1 = Monday.' },
+      label, hint, error,
+      placeholder: placeholder('Shown when no date is set. Defaults to "Select date".'),
+      disabled,
+      size: size(),
+    },
+    events: change('Called with a Date object (local midnight) for the chosen day. The popup closes after picking.'),
+    notes: ['The event payload is a Date, not a string: convert to ISO yourself if the model is a string.', 'The popup closes on outside click and on Escape.'],
+  },
+  TimePicker: {
+    description: 'Hour and minute selects for a time of day. Use for opening hours and appointment times.',
+    props: {
+      modelValue: { type: 'string', model: true, default: '09:00', description: 'Time as "HH:mm" (24 hour).' },
+      minuteStep: { type: 'number', default: 15, description: 'Step of the minute options in minutes (1 to 60). 15 gives 00, 15, 30, 45; 5 gives 00, 05, ... 55.' },
+      label,
+      disabled,
+      size: size(),
+    },
+    events: change('Called with a new "HH:mm" string. Minute options follow minuteStep.'),
+    notes: ['A model value outside the minute grid (e.g. 09:07) is added to the minute list so it still displays.', 'Both selects close on outside click and on Escape.'],
+  },
+  FileUpload: {
+    description: 'Drop-zone style file picker. Use for documents and attachments.',
+    props: {
+      title: { type: 'string', default: 'Drop files here or browse', description: 'Main text in the zone.' },
+      hint: { type: 'string', default: 'PDF, JPG up to 10 MB', description: 'Secondary text in the zone. Purely informational: use accept and maxSize to enforce limits.' },
+      accept: { type: 'string', description: 'Accepted types as in the native attribute, e.g. ".pdf,image/*". Also applied to dropped files.' },
+      maxSize: { type: 'number', description: 'Maximum size of one file in bytes. Larger files are rejected.' },
+      multiple: { type: 'boolean', default: false, description: 'Allow selecting several files.' },
+      image: { type: 'boolean', default: false, description: 'Use the image icon instead of the upload icon.' },
+      label, error,
+      size: size(),
+    },
+    events: { ...change('Called with the array of accepted File objects, from the picker or a drop. Without multiple only the first one is kept.'), reject: 'Called as (file, reason) for each refused file; reason is "type" (not in accept), "size" (over maxSize) or "count" (extra file when multiple is off).' },
+    notes: ['Click, Enter or Space opens the picker; files can also be dropped onto the zone, which highlights while dragging.', 'Stateless: the component does not list the chosen files, render them yourself.'],
+  },
+  ImageUpload: {
+    description: 'Image picker with a live preview, square or circular. Use for avatars, covers and logos.',
+    props: {
+      modelValue: { type: 'string', model: true, description: 'Image URL or data URL to show before the user picks a new file.' },
+      shape: { type: "'square' | 'circle'", values: ['square', 'circle'], default: 'square', description: 'circle gives a round avatar-style crop, otherwise rounded corners.' },
+      aspect: { type: 'string', default: '1/1', description: 'CSS aspect-ratio of the box, e.g. "16/9".' },
+      hint: { type: 'string', default: 'Upload', description: 'Text shown in the empty state.' },
+      label,
+      size: size('Maximum width: 112, 128, 160, 192 or 224 px. A number is used as px directly.'),
+    },
+    events: change('Called with (dataUrl, file): the picked image as a data URL and the original File.'),
+    notes: ['The preview is kept in internal state, so it updates even without updating modelValue.'],
+  },
+  FormField: {
+    description: 'Label, required marker, hint and error wrapper around any control. Use to build a field from custom inputs.',
+    props: {
+      label,
+      required: { type: 'boolean', default: false, description: 'Appends a red asterisk to the label. Does not validate.' },
+      hint, error,
+      size: size('Only marks the wrapper with data-size; sizes never leak into children by design, so set size on the inner control too.'),
+    },
+    slots: { default: 'The control(s) to wrap.' },
+    notes: ['Does not link label and control by id: put the control inside a label or pass an aria-label yourself.'],
+  },
+  ValidatedField: {
+    description: 'TextField (or PasswordInput) with built-in validation rules. Use for simple client-side validation without a form library.',
+    props: {
+      modelValue: { type: 'string', model: true, default: '', description: 'Current value.' },
+      rules: { type: '((value: string) => true | string)[]', default: '[]', description: 'Validators run in order; return true when valid or an error message. The first failure is shown.' },
+      type: { type: "'text' | 'password' | string", default: 'text', description: '"password" renders PasswordInput, any other value is passed to TextField as the input type.' },
+      error: { type: 'string', description: 'External error. Takes priority over rules.' },
+      label: { ...label, forwarded: true }, placeholder: { ...placeholder(), forwarded: true }, hint: { ...hint, forwarded: true },
+      icon: { type: 'string', description: 'Leading icon name (TextField only).', forwarded: true },
+      disabled: { ...disabled, forwarded: true },
+      size: size(),
+    },
+    events: change('Called with the new string on every keystroke.'),
+    notes: ['Rules start running after the first edit, so an untouched field shows no error.', 'All other props are forwarded to TextField / PasswordInput.'],
+  },
+  LoginForm: {
+    description: 'Ready sign-in form with login, password, remember-me, forgot link and submit button. Use as the body of an auth page.',
+    props: {
+      error: { type: 'string', description: 'Failure message shown in a danger alert above the fields.' },
+      loading: { type: 'boolean', default: false, description: 'Disables the submit button and shows a spinner.' },
+      showForgot: { type: 'boolean', default: true, description: 'Show the "Forgot password?" link.' },
+      submitLabel: { type: 'string', default: 'Sign in', description: 'Submit button text. Wins over labels.submit.' },
+      labels: { type: '{ email?: string; password?: string; remember?: string; forgot?: string; submit?: string }', default: "{ email: 'Email or phone', password: 'Password', remember: 'Remember device', forgot: 'Forgot password?', submit: 'Sign in' }", description: 'Texts of the form; any missing key keeps its English default.' },
+      size: size(),
+    },
+    events: { submit: 'Called with { email, password, remember } when the form is submitted.', forgot: 'Called when "Forgot password?" is clicked.' },
+    notes: ['Field values live inside the component: read them from the submit payload.', 'Translate the texts with labels; the "email" value holds an email or phone.'],
+  },
+  StepForm: {
+    description: 'Multi-step form shell: stepper, current step content and Back/Next buttons. Use for wizards and onboarding.',
+    props: {
+      steps: { type: '{ label: string; content: VNode }[]', default: '[]', description: 'Steps in order. content is rendered while the step is active.' },
+      finishLabel: { type: 'string', default: 'Finish', description: 'Text of the Next button on the last step.' },
+      size: size('Also sets the size of the Back/Next buttons.'),
+    },
+    events: { finish: 'Called when Next is pressed on the last step.' },
+    notes: ['The current step is internal; Next never validates, so guard the content yourself.'],
+  },
+  Stepper: {
+    description: 'Horizontal progress indicator with numbered steps. Use to show position in a multi-step flow.',
+    props: {
+      steps: { type: 'string[]', default: '[]', description: 'Step labels in order.' },
+      current: { type: 'number', required: true, description: 'Zero-based index of the active step. Earlier steps show a check mark.' },
+      size: size('Step circle and label size.'),
+    },
+  },
+};

package/src/meta/groups.js

@@ -0,0 +1,16 @@
+// Component groups: single source for the docs site, manifest and llms.txt.
+export const GROUPS = [
+  { id: 'typography', title: 'Typography', blurb: 'Headings and text.', names: ['Heading', 'Text', 'Code', 'Kbd', 'Link'] },
+  { id: 'layout', title: 'Layout', blurb: 'Stacks, grids and page structure.', names: ['Box', 'Center', 'HStack', 'VStack', 'Grid', 'Divider', 'ScrollArea', 'SplitLayout', 'AppShell', 'PageHeader', 'AuthLayout', 'SettingsSection', 'LiquidGlass', 'Footer', 'Sortable', 'Portal'] },
+  { id: 'actions', title: 'Actions', blurb: 'Buttons and things you press.', names: ['Button', 'IconButton', 'Pressable', 'Fab', 'CopyButton', 'ToggleGroup', 'SegmentedControl', 'FilterChips', 'Chip', 'Tag', 'Badge', 'ActionRail', 'ActionCard', 'NotificationBell'] },
+  { id: 'forms', title: 'Forms', blurb: 'Inputs, pickers and form building blocks.', names: ['TextField', 'Textarea', 'NumberInput', 'PasswordInput', 'SearchInput', 'PhoneInput', 'CodeInput', 'ChipInput', 'InlineEdit', 'RichEditor', 'Select', 'MultiSelect', 'GroupedSelect', 'Combobox', 'TreeSelect', 'PillSelect', 'Checkbox', 'Switch', 'RadioGroup', 'OptionCard', 'OptionCards', 'Slider', 'RangeSlider', 'Rating', 'ColorPicker', 'Calendar', 'RangeCalendar', 'DatePicker', 'TimePicker', 'FileUpload', 'ImageUpload', 'FormField', 'ValidatedField', 'LoginForm', 'StepForm', 'Stepper'] },
+  { id: 'data', title: 'Data display', blurb: 'Tables, stats, charts and lists.', names: ['Card', 'DataTable', 'DataGroup', 'Descriptions', 'Timeline', 'TreeView', 'CalendarView', 'KpiTile', 'KpiInline', 'StatsCard', 'StatRow', 'StatLine', 'StatStrip', 'CountryRow', 'VersusBar', 'SegBar', 'MiniChart', 'ChartCard', 'Ring', 'OccupancyChart', 'SalesFunnel', 'SystemStatus', 'UserCell', 'IconTile', 'StatusIcon', 'HeroBanner', 'TabTiles', 'PricingCard', 'IntegrationCard'] },
+  { id: 'feedback', title: 'Feedback', blurb: 'Alerts, progress and states.', names: ['Alert', 'Banner', 'Toast', 'Snackbar', 'Progress', 'Spinner', 'Skeleton', 'EmptyState', 'ErrorPage', 'StatusPage', 'DataState', 'LoadingOverlay'] },
+  { id: 'overlay', title: 'Overlay', blurb: 'Dialogs, sheets and popovers.', names: ['Modal', 'Drawer', 'ConfirmDialog', 'Popconfirm', 'StepDialog', 'FullscreenDialog', 'BottomSheet', 'Actionsheet', 'Popover', 'HoverCard', 'Tooltip', 'Dropdown', 'Menu', 'ContextMenu', 'CommandBar', 'CommandPalette', 'ImageViewer', 'Tour', 'TourPopover', 'Screensaver'] },
+  { id: 'navigation', title: 'Navigation', blurb: 'Menus, tabs and paging.', names: ['TopNav', 'SideNav', 'SubNav', 'Tabs', 'PillTabs', 'Breadcrumbs', 'Pagination', 'Accordion'] },
+  { id: 'media', title: 'Media and icons', blurb: 'Avatars, images, maps and icons.', names: ['Avatar', 'Icon', 'LazyImage', 'Gallery', 'Carousel', 'Map', 'ProfileHeader', 'ChatAi'] },
+  { id: 'domain', title: 'Domain', blurb: 'Umrah, Hajj, hotel and CRM blocks.', names: ['HotelCard', 'TourCard', 'PrayerTimes', 'RamadanTracker', 'BookingCard', 'GuestCard', 'RoomGrid', 'RoomCalendar', 'LeadCard', 'DealCard', 'PipelineBoard', 'ContactPanel', 'KanbanColumn', 'KanbanCard', 'CallRow', 'CallCard', 'IncomingCall', 'AuthSplit'] },
+  { id: 'pages', title: 'Page templates', blurb: 'Ready layouts with named slots.', names: ['PageDashboard', 'PagePatterns', 'PageCrm', 'PageBookings', 'PageCatalog', 'PageDetail', 'PageSettings', 'PageUserList', 'PageProfile', 'PageForm', 'PageOrder', 'PageAccount', 'PagePricing', 'PageFaq', 'PageAuth', 'PageStatus'] },
+];
+
+export const groupOf = name => GROUPS.find(g => g.names.includes(name));