@ziyarago/ui 0.0.0-stage → 0.1.0

package/src/meta/index.js

@@ -0,0 +1,14 @@
+import typography from './typography.js';
+import layout from './layout.js';
+import actions from './actions.js';
+import forms from './forms.js';
+import data from './data.js';
+import feedback from './feedback.js';
+import overlay from './overlay.js';
+import navigation from './navigation.js';
+import media from './media.js';
+import domain from './domain.js';
+import pages from './pages.js';
+
+export const meta = { ...typography, ...layout, ...actions, ...forms, ...data, ...feedback, ...overlay, ...navigation, ...media, ...domain, ...pages };
+export default meta;

package/src/meta/layout.js

@@ -0,0 +1,159 @@
+// API metadata for the layout group. Format: see src/meta/README.md
+const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'];
+const sizeProp = (def = 'md', desc = 'Component size.') => ({ type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'", values: SIZES, default: def, description: desc });
+const as = { type: 'string', default: 'div', description: 'HTML tag to render.' };
+const style = { type: 'Record<string, string | number>', description: 'Inline styles merged over the component styles.' };
+const gap = { type: 'number | string', default: 12, description: 'Gap between children. Numbers are pixels, strings any CSS length.' };
+const stackProps = {
+  gap: { ...gap, forwarded: true },
+  align: { forwarded: true, type: 'string', description: 'CSS align-items value, for example center, flex-start, stretch.' },
+  justify: { forwarded: true, type: 'string', description: 'CSS justify-content value, for example space-between, center.' },
+  wrap: { forwarded: true, type: 'boolean', default: false, description: 'Allows children to wrap onto several lines.' },
+  as: { ...as, forwarded: true },
+  style: { ...style, forwarded: true },
+};
+
+export default {
+  Box: {
+    description: 'Generic container with optional padding and glass background.',
+    props: {
+      p: { type: 'number | string', description: 'Padding. Numbers are pixels, strings any CSS value.' },
+      glass: { type: 'boolean', default: false, description: 'Applies the glass surface style.' },
+      as,
+      style,
+    },
+    slots: { default: 'Box content.' },
+  },
+  Center: {
+    description: 'Centers its children horizontally and vertically.',
+    props: { as, style },
+    slots: { default: 'Centered content.' },
+  },
+  HStack: {
+    description: 'Horizontal flex row with a configurable gap.',
+    props: { ...stackProps },
+    slots: { default: 'Items laid out in a row.' },
+  },
+  VStack: {
+    description: 'Vertical flex column with a configurable gap.',
+    props: { ...stackProps },
+    slots: { default: 'Items laid out in a column.' },
+  },
+  Grid: {
+    description: 'CSS grid with a fixed column count or auto-fit columns of a minimum width.',
+    props: {
+      cols: { type: 'number', description: 'Fixed number of equal columns. When set, min is ignored.' },
+      min: { type: 'number | string', default: 240, description: 'Minimum column width for auto-fit layout (used when cols is not set).' },
+      gap: { type: 'number | string', default: 16, description: 'Gap between cells. Numbers are pixels, strings any CSS length.' },
+      as,
+      style,
+    },
+    slots: { default: 'Grid items.' },
+  },
+  Divider: {
+    description: 'Horizontal separator line with an optional centered label.',
+    props: {
+      label: { type: 'string', description: 'Text shown in the middle of the line.' },
+      size: sizeProp('md', 'Label font size and spacing.'),
+    },
+    notes: ['Renders role="separator".'],
+  },
+  ScrollArea: {
+    description: 'Vertically scrollable container with a max height and styled scrollbar.',
+    props: {
+      maxHeight: { type: 'string', default: '240px', description: 'CSS max-height; content scrolls beyond it. Must be a string with a unit.' },
+    },
+    slots: { default: 'Scrollable content.' },
+  },
+  SplitLayout: {
+    description: 'Two-column layout with configurable column widths; use for master-detail or side-by-side content.',
+    props: {
+      columns: { type: 'string', default: '1fr 1fr', description: 'CSS grid-template-columns value, for example "280px 1fr".' },
+    },
+    slots: { left: 'First column. Falls back to the first child.', right: 'Second column. Falls back to the second child.' },
+    notes: ['Exactly two columns; extra children beyond the second are ignored.'],
+  },
+  AppShell: {
+    description: 'Application frame with a top or side navigation and a main content area.',
+    props: {
+      nav: { type: "'top' | 'side'", values: ['top', 'side'], default: 'top', description: 'Navigation placement: TopNav or SideNav.' },
+      brand: { type: 'VNode | string', description: 'Brand/logo content shown in the navigation.' },
+      items: { type: '{ value: string; label: string; icon?: string }[]', description: 'Navigation items, passed to TopNav or SideNav.' },
+      value: { type: 'string', description: 'Value of the active navigation item. Changed via the change event.' },
+      actions: { type: 'VNode', description: 'Right side of the top navigation (nav="top" only).' },
+      collapsed: { type: 'boolean', description: 'Controlled collapsed state of the side navigation. Uncontrolled (internal state, initially false) when omitted.' },
+      collapsible: { type: 'boolean', default: true, description: 'Shows the collapse toggle in the side navigation. Set false to hide it.' },
+      collapseLabel: { type: 'string', description: 'Label of the collapse toggle in the side navigation.' },
+      frame: { type: 'boolean', default: false, description: 'Renders the shell as a framed block instead of full viewport (useful in previews).' },
+    },
+    events: { change: 'Called with the value of the clicked navigation item.', collapse: 'Called with the new collapsed boolean when the toggle is pressed.' },
+    slots: { default: 'Main page content.', footer: 'Bottom area of the side navigation (nav="side" only).' },
+    notes: ['The footer slot and collapse props apply only to nav="side".'],
+  },
+  PageHeader: {
+    description: 'Page title block with optional breadcrumbs, subtitle and an actions area.',
+    props: {
+      title: { type: 'string', required: true, description: 'Page title (rendered as h1).' },
+      subtitle: { type: 'string', description: 'Secondary text below the title.' },
+      crumbs: { type: '{ label: string; href?: string }[]', description: 'Breadcrumb items shown above the title.' },
+      size: sizeProp('md', 'Title and subtitle size.'),
+    },
+    slots: { actions: 'Right side of the header, usually buttons.' },
+  },
+  AuthLayout: {
+    description: 'Centered card layout for sign-in and sign-up pages.',
+    props: {
+      title: { type: 'string', required: true, description: 'Heading inside the card.' },
+      subtitle: { type: 'string', description: 'Text below the title.' },
+      logo: { type: 'VNode', description: 'Logo element shown at the top of the card.' },
+      style,
+    },
+    slots: { default: 'Card body, usually a form.' },
+  },
+  SettingsSection: {
+    description: 'Settings block with a title and description on the left and fields below.',
+    props: {
+      title: { type: 'string', required: true, description: 'Section title.' },
+      description: { type: 'string', description: 'Helper text under the title.' },
+      size: sizeProp('md', 'Padding, title and field spacing.'),
+    },
+    slots: { default: 'Fields and controls of the section.' },
+  },
+  LiquidGlass: {
+    description: 'Frosted liquid-glass panel with adjustable corner radius and blur.',
+    props: {
+      radius: { type: 'number | string', default: 24, description: 'Corner radius. Numbers are pixels.' },
+      blur: { type: 'number | string', default: 18, description: 'Backdrop blur radius. Numbers are pixels.' },
+      size: sizeProp('md', 'Inner padding.'),
+    },
+    slots: { default: 'Panel content.' },
+    notes: ['Backdrop blur is visible only over a colorful or image background.'],
+  },
+  Footer: {
+    description: 'Page footer with a copyright line and a row of links.',
+    props: {
+      copyright: { type: 'string', default: '© 2026 ZiyaraGo', description: 'Copyright text.' },
+      links: { type: '{ label: string; href?: string }[]', default: '[]', description: 'Footer links; href defaults to "#".' },
+      size: sizeProp('md', 'Padding and font size.'),
+    },
+    slots: { default: 'Extra content after the links.' },
+  },
+  Sortable: {
+    description: 'Drag-and-drop reorderable list with grip handles and up/down buttons.',
+    props: {
+      items: { type: '{ id?: string | number; label: string }[]', default: '[]', required: true, description: 'Items in current order. id is used as the key, falling back to the index.' },
+      render: { type: '(item, index) => VNode', description: 'Custom item renderer. Defaults to the bold item label.' },
+      size: sizeProp('md', 'Row padding, gap and font size.'),
+    },
+    events: { change: 'Called with the reordered items array after a drop or up/down click.' },
+    notes: ['Controlled: the parent must store the array from change and pass it back as items.', 'Keyboard-friendly reordering is available through the up/down buttons.'],
+  },
+  Portal: {
+    description: 'Renders its children outside the component tree, for example into document.body.',
+    props: {
+      to: { type: 'string | HTMLElement', description: 'Target element or CSS selector. The adapter default (body) is used when omitted.' },
+    },
+    slots: { default: 'Content to teleport.' },
+    notes: ['Renders nothing when the framework adapter provides no portal.'],
+  },
+};

package/src/meta/media.js

@@ -0,0 +1,104 @@
+// API metadata for the media group. Format: see src/meta/README.md
+const SZ = ['xs', 'sm', 'md', 'lg', 'xl'];
+const SIZE = "'xs' | 'sm' | 'md' | 'lg' | 'xl'";
+const size = (d, extra) => ({ type: SIZE, values: SZ, default: d || 'md', description: extra || 'Thumbnail strip size.' });
+
+export default {
+  Avatar: {
+    description: 'Round user picture that falls back to initials when there is no image.',
+    props: {
+      name: { type: 'string', description: 'Full name. Shown as the tooltip and used for up to two initials; "?" when empty.' },
+      src: { type: 'string', description: 'Image URL. Initials are shown without it.' },
+      size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | number", values: SZ, default: 'md', description: 'Diameter: xs 24, sm 32, md 40, lg 56, xl 72 px. A number is used directly as px.' },
+    },
+    notes: ['Avatar sizes differ from other components (lg 56, xl 72), and a number gives any custom size.'],
+  },
+
+  Icon: {
+    description: 'Renders a named icon from the library at a chosen size.',
+    props: {
+      name: { type: 'string', default: 'circle', description: 'Icon name from the library, for example "check" or "map-pin".' },
+      size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | number", values: SZ, default: 'md', description: 'Pixel size: xs 14, sm 16, md 20, lg 24, xl 32. A number is used directly as px.' },
+    },
+    notes: ['The icon is aria-hidden; add a label on the surrounding control for accessibility.', 'Icons load lazily, so the glyph may appear a moment after first render.'],
+  },
+
+  LazyImage: {
+    description: 'Image box with a fixed aspect ratio and rounded corners, rendered as a background image.',
+    props: {
+      src: { type: 'string', description: 'Image URL. An empty placeholder is shown without it.' },
+      alt: { type: 'string', default: '', description: 'Accessible description, exposed as aria-label on role="img".' },
+      aspectRatio: { type: 'string', default: '16/9', description: 'CSS aspect-ratio value such as "1/1" or "4/3".' },
+      rounded: { type: 'number', default: 20, description: 'Corner radius in px.' },
+    },
+  },
+
+  Gallery: {
+    description: 'Large image with a counter and a thumbnail strip for browsing a set of photos.',
+    props: {
+      images: { type: 'string[]', required: true, default: [], description: 'Image URLs. The first one is shown initially; clicking a thumbnail switches the main image.' },
+      alt: { type: 'string', default: '', description: 'Accessible description of the main image.' },
+      index: { type: 'number', description: 'Controlled active image index. When set, the gallery only changes image when you update it from onChange; when omitted it keeps its own state starting at 0.' },
+      labels: { type: '{ photo?: string }', default: "{ photo: 'Photo' }", description: 'Override the thumbnail aria-label prefix.' },
+      size: size('md'),
+    },
+    events: { change: 'Called with the new image index when a thumbnail is clicked.' },
+    notes: ['An empty or missing images array renders an empty frame (no counter, no thumbnails). Invalid index values are clamped to the available range.'],
+  },
+
+  Carousel: {
+    description: 'Slideshow of image slides with captions, arrows and dot pagination.',
+    props: {
+      items: { type: '{ image?: string; title: string; sub?: string }[]', required: true, default: [], description: 'Slides. title and sub form the caption over the image.' },
+      index: { type: 'number', description: 'Controlled active slide index. When set, the carousel only changes slide when you update it from onChange; when omitted it keeps its own state starting at 0.' },
+      autoplay: { type: 'number | boolean', description: 'Advance automatically every N milliseconds (true = 5000). Starts only in the browser, pauses while the pointer is over or focus is inside the carousel and while the tab is hidden, and is disabled for prefers-reduced-motion and data-motion="off". Needs at least 2 slides.' },
+      label: { type: 'string', description: 'Accessible name of the carousel region.' },
+      labels: { type: '{ prev?: string; next?: string; slide?: string }', default: "{ prev: 'Previous', next: 'Next', slide: 'Slide' }", description: 'Override the aria-labels of the arrows and dots.' },
+      size: size('md', 'Slide aspect ratio and caption size: xs 16/6, sm 16/7, md 16/8, lg 16/9, xl 16/10.'),
+    },
+    events: { change: 'Called with the new slide index on arrow, dot, keyboard (left and right arrows) and autoplay changes.' },
+    notes: ['Arrows wrap around at both ends and are hidden with fewer than 2 slides; an empty items array renders an empty frame.', 'Autoplay has no visible pause button; hover or focus pauses it. Prefer a manual carousel for essential content.'],
+  },
+
+  Map: {
+    description: 'Interactive raster map with panning, zoom buttons and clickable markers, using OpenStreetMap data via CARTO tiles.',
+    props: {
+      lat: { type: 'number', default: 21.4225, description: 'Initial center latitude.' },
+      lon: { type: 'number', default: 39.8262, description: 'Initial center longitude.' },
+      zoom: { type: 'number', default: 14, description: 'Initial zoom level; the zoom buttons clamp it to 3..18.' },
+      markers: { type: "{ lat: number; lon: number; label?: string; icon?: string; tone?: 'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral' }[]", default: [], description: 'Pins. label is the tooltip, icon defaults to "map-pin".' },
+      width: { type: 'number', default: 640, description: 'Pixel width used to compute which tiles to load; the map element itself fills its container.' },
+      height: { type: 'number', default: 360, description: 'Height in px.' },
+      theme: { type: "'light' | 'dark'", values: ['light', 'dark'], description: 'Tile theme. If omitted, dark is used when the page is inside a dark data-theme.' },
+      style: { type: 'string', description: 'CARTO tile style path, for example "light_all" or "dark_all". Overrides theme.' },
+      label: { type: 'string', default: 'Map', description: 'aria-label of the map region.' },
+      labels: { type: '{ zoomIn?: string; zoomOut?: string }', default: "{ zoomIn: 'Zoom in', zoomOut: 'Zoom out' }", description: 'Accessible names of the zoom buttons.' },
+    },
+    events: { select: 'Called with the marker object when a marker is clicked.' },
+    notes: ['The center and zoom props are initial values; user panning and zooming is kept in internal state.', 'Tiles come from a third-party CDN, so it needs network access.'],
+  },
+
+  ProfileHeader: {
+    description: 'Profile card with a cover image, large avatar, name and a row of meta items.',
+    props: {
+      name: { type: 'string', required: true, description: 'Person or organization name.' },
+      src: { type: 'string', description: 'Avatar image URL; initials are shown without it.' },
+      cover: { type: 'string', description: 'Cover image URL.' },
+      meta: { type: '{ icon: string; label: string }[]', default: [], description: 'Facts under the name such as location or join date. label must be unique.' },
+    },
+    slots: { default: 'Extra content on the right of the name row, usually action buttons.' },
+  },
+
+  ChatAi: {
+    description: 'Chat panel with message bubbles, a typing indicator and an input, for AI assistant UIs.',
+    props: {
+      messages: { type: "{ role: 'user' | 'ai'; text: string }[]", required: true, default: [], description: 'Conversation in order. Any role other than "user" renders as an assistant bubble.' },
+      loading: { type: 'boolean', default: false, description: 'Shows the typing dots and disables sending.' },
+      title: { type: 'string', default: 'Assistant', description: 'Header title; also the aria-label. The header renders only when set.' },
+      subtitle: { type: 'string', description: 'Muted text next to the title.' },
+      placeholder: { type: 'string', default: 'Ask anything…', description: 'Input placeholder.' },
+    },
+    events: { send: 'Called with the trimmed message text when the user presses Enter or the send button. The component does not append it to messages.' },
+    notes: ['Append the user message and the reply to messages yourself; set loading while waiting.'],
+  },
+};

package/src/meta/navigation.js

@@ -0,0 +1,99 @@
+// API metadata for the navigation 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 current = { type: 'string', description: 'Value of the active item (aria-current="page").' };
+
+export default {
+  TopNav: {
+    description: 'Horizontal app header with a brand area, navigation items and an actions area.',
+    props: {
+      brand: { type: 'string | VNode', description: 'Logo or product name on the left.' },
+      items: { type: '{ value: string; label: string; icon?: string; count?: string | number }[]', default: '[]', description: 'Navigation entries. count renders a small counter after the label.' },
+      value: current,
+      size: size('header padding, item height and text'),
+    },
+    slots: { actions: 'Right side of the header (buttons, avatar). React also accepts an actions prop.' },
+    events: { change: 'Called with the value of the clicked item.' },
+    notes: ['Controlled: update value yourself in the change handler.', 'Items use count; SubNav uses badge for the same purpose.'],
+  },
+
+  SideNav: {
+    description: 'Vertical sidebar with a brand, grouped navigation items, a footer and an optional collapse toggle.',
+    props: {
+      brand: { type: 'string | VNode', description: 'Logo or product name at the top.' },
+      items: { type: '({ value: string; label: string; icon?: string; count?: string | number } | { group: string })[]', default: '[]', description: 'Entries. An object with group renders a section heading (hidden when collapsed); others are links with an optional icon and count.' },
+      value: current,
+      collapsed: { type: 'boolean', default: false, description: 'Icon-only mode; labels move to the title tooltip.' },
+      collapseLabel: { type: 'string', default: 'Collapse', description: 'Label of the collapse button.' },
+      size: size('width (216 to 336 px), padding and item height'),
+    },
+    slots: { footer: 'Bottom area above the collapse button, e.g. user card. React also accepts a footer prop.' },
+    events: { change: 'Called with the value of the clicked item.', toggle: 'Called when the collapse button is clicked. The button is rendered only when this handler is set.' },
+    notes: ['Collapsing is controlled: flip collapsed in the toggle handler.', 'Group entries are keyed by their title, so keep group names unique.'],
+  },
+
+  SubNav: {
+    description: 'Compact vertical list of sections with an optional title; use for settings and secondary page navigation.',
+    props: {
+      title: { type: 'string', description: 'Small heading above the list; also the aria-label.' },
+      items: { type: '{ value: string; label: string; icon?: string; badge?: string | number }[]', default: '[]', description: 'Entries. badge renders a counter on the right.' },
+      value: current,
+      size: size('item height and text'),
+    },
+    events: { change: 'Called with the value of the clicked item.' },
+  },
+
+  Tabs: {
+    description: 'Underlined tab strip for switching between views of the same page.',
+    props: {
+      modelValue: { type: 'string', model: true, description: 'Value of the selected tab. Vue v-model, React modelValue + onChange.' },
+      items: { type: '{ value: string; label: string }[]', default: '[]', description: 'Tabs.' },
+      size: size('tab height and text'),
+    },
+    events: { change: 'Called with the value of the clicked tab.' },
+    notes: ['Renders only the tab buttons (role="tablist"); you show the matching panel yourself.'],
+  },
+
+  PillTabs: {
+    description: 'Pill-style tab buttons with optional icons, horizontal or vertical; use for settings and profile sections.',
+    props: {
+      items: { type: '{ value: string; label: string; icon?: string }[]', default: '[]', description: 'Tabs.' },
+      value: { type: 'string', description: 'Value of the selected tab. Changed via the change event.' },
+      vertical: { type: 'boolean', default: false, description: 'Stacks the tabs in a column.' },
+      size: size('button height, gap and text'),
+    },
+    events: { change: 'Called with the value of the clicked tab.' },
+    notes: ['Renders only the tab buttons; you show the matching panel yourself.'],
+  },
+
+  Breadcrumbs: {
+    description: 'Path trail with chevron separators; the last item is the current page.',
+    props: {
+      items: { type: '{ label: string; href?: string }[]', default: '[]', description: 'Trail from root to current. All but the last render as links (href defaults to "#"); the last is bold with aria-current="page".' },
+      size: size('text and separator size'),
+    },
+  },
+
+  Pagination: {
+    description: 'Page navigation with numbered buttons, ellipsis windowing and previous/next; use under tables and lists.',
+    props: {
+      page: { type: 'number', description: 'Current page, 1-based. Changed via the change event.' },
+      pages: { type: 'number', default: 1, description: 'Total number of pages.' },
+      siblings: { type: 'number', default: 1, description: 'Page buttons shown on each side of the current page. First and last page are always shown; gaps become an ellipsis.' },
+      label: { type: 'string', default: 'Pagination', description: 'Accessible name of the navigation landmark.' },
+      size: size('button size and text'),
+    },
+    events: { change: 'Called with the clicked page number (also from the previous and next buttons).' },
+    notes: ['Shows first, last and current plus or minus siblings with an ellipsis for gaps, so it scales to hundreds of pages. A gap of a single page shows that page instead of an ellipsis.', 'Previous and next buttons carry aria-label "Previous page" and "Next page" and are disabled at the ends; the current page has aria-current="page".'],
+  },
+
+  Accordion: {
+    description: 'Vertical list of collapsible sections where one is open at a time; use for FAQs and grouped details.',
+    props: {
+      items: { type: '{ id: string; title: string; body: string | VNode }[]', default: '[]', description: 'Sections. id must be unique; body is shown when the section is open.' },
+      size: size('header padding and text'),
+    },
+    notes: ['Open state is internal and single: opening one closes the others, all start closed.'],
+  },
+};