@ziyarago/ui 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.14.0](https://github.com/ziyarago/ui/compare/v0.13.0...v0.14.0) (2026-10-21)
+
+### Features
+
+* plugin API (registerComponents, defineUiComponents, registerMeta, resolver and Nuxt plugins option) ([ab8b844](https://github.com/ziyarago/ui/commit/ab8b8442a9968cfc0c978d9a5d4c3dc22b28b467))
+
 ## [0.13.0](https://github.com/ziyarago/ui/compare/v0.12.0...v0.13.0) (2026-10-21)
 
 ### Features

package/dist/llms-full.txt

@@ -2,7 +2,7 @@
 
 > ZiyaraGo UI — glass design system for Umrah and Hajj products. OKLCH tokens, two palettes, dark and light, RTL, Thmanyah. One framework-neutral core with Vue 3, Nuxt and React adapters, 208 components and 40 page templates.
 
-Version 0.13.0. Docs: https://ziyara.vip . Manifest (machine readable): https://ziyara.vip/manifest.json
+Version 0.14.0. Docs: https://ziyara.vip . Manifest (machine readable): https://ziyara.vip/manifest.json
 
 ## Setup
 - import { UiButton } from '@ziyarago/ui/vue'

package/dist/llms.txt

@@ -2,7 +2,7 @@
 
 > ZiyaraGo UI — glass design system for Umrah and Hajj products. OKLCH tokens, two palettes, dark and light, RTL, Thmanyah. One framework-neutral core with Vue 3, Nuxt and React adapters, 208 components and 40 page templates.
 
-Version 0.13.0. Docs: https://ziyara.vip . Manifest (machine readable): https://ziyara.vip/manifest.json
+Version 0.14.0. Docs: https://ziyara.vip . Manifest (machine readable): https://ziyara.vip/manifest.json
 
 ## Setup
 - import { UiButton } from '@ziyarago/ui/vue'

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
  "name": "@ziyarago/ui",
- "version": "0.13.0",
+ "version": "0.14.0",
  "homepage": "https://ziyara.vip",
  "imports": {
   "vue": "import { UiButton } from '@ziyarago/ui/vue'",

package/docs/INTEGRATION.md

@@ -151,3 +151,14 @@ React types: `Ui<Name>Props` (props, callbacks, named slots as `ReactNode` props
 ## 7. Checking the types yourself
 
 `npm run test:types` in this repository runs vue-tsc and tsc over `tests/types/*`: valid usage must compile, invalid enum / missing required prop / wrong event payload / wrong model type / unknown slot / wrong slot type must fail with the expected message.
+
+## 8. Add-on packages (plugins)
+
+An add-on package (for example `@ziyarago/ui-pro`) plugs components into the same registry through `registerComponents` / `defineUiComponents`, so its definitions can use `C.Button` and the core components can reference them. A plugin ships its own stylesheet: import it after the core one.
+
+```ts
+import '@ziyarago/ui/style.css'
+import '@ziyarago/ui-pro/style.css'   // plugin css, always after style.css
+```
+
+Plugin CSS must only use the public design tokens (`--zg-*`, see `@ziyarago/ui/tokens.css`) and its own prefixed classes. Auto-import: pass `plugins: ['@ziyarago/ui-pro']` to the Nuxt module options (`ziyarago: { plugins: [...] }`) or to `ZiyaragoUiResolver({ plugins: [...] })`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziyarago/ui",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "ZiyaraGo UI — glass design system for Umrah and Hajj products. OKLCH tokens, two palettes, dark and light, RTL, Thmanyah. One framework-neutral core with Vue 3, Nuxt and React adapters, 208 components and 40 page templates.",
   "keywords": [
     "ui",

package/src/core/index.js

@@ -7,5 +7,11 @@ import { more6 } from './components6.js';
 import { more7 } from './components7.js';
 export const components = { ...base, ...more, ...more3, ...more4, ...more6, ...more7, ...pages };
 export { fmt, setIconBase, rules };
+/** Extension API: adds definitions to the shared registry (used by add-on packages such as @ziyarago/ui-pro). Registering the very same definition twice is a no-op (Vue and React adapters can both load one plugin). */
+export function registerComponents(defs, { override = false } = {}) {
+  for (const name of Object.keys(defs)) if (!override && name in components && components[name] !== defs[name]) throw new Error(`@ziyarago/ui: component "${name}" is already registered (pass { override: true } to replace it)`);
+  Object.assign(components, defs);
+  return components;
+}
 export { LOCALES, FREE_LOCALES, t, setUiLocale, getUiLocale, setUiMessages, isRtlLocale, subscribeUiLocale, getUiVersion, defineMessages } from '../i18n/index.js';
 import '../i18n/components/index.js';

package/src/meta/index.js

@@ -11,4 +11,17 @@ import domain from './domain.js';
 import pages from './pages.js';
 
 export const meta = { ...typography, ...layout, ...actions, ...forms, ...data, ...feedback, ...overlay, ...navigation, ...media, ...domain, ...pages };
+import { PRO_NAMES } from './tiers.js';
+import { GROUPS } from './groups.js';
+/** Extension API: adds API metadata for plugin components. `tiers` marks names as Pro, `groups` ({ id, title, blurb, names }) lists them in the manifest. */
+export function registerMeta(extra, { tiers, groups } = {}) {
+  Object.assign(meta, extra);
+  for (const n of tiers || []) PRO_NAMES.add(n);
+  for (const g of groups || []) {
+    const ex = GROUPS.find(x => x.id === g.id);
+    if (ex) ex.names.push(...g.names.filter(n => !ex.names.includes(n)));
+    else GROUPS.push({ blurb: '', title: g.id, ...g, names: [...g.names] });
+  }
+  return meta;
+}
 export default meta;

package/src/nuxt/module.mjs

@@ -1,11 +1,12 @@
 // Nuxt 3/4 module. nuxt.config: modules: ['@ziyarago/ui/nuxt'], ziyarago: { theme: true }
 import { defineNuxtModule, addComponent, addImports, addPlugin, createResolver } from '@nuxt/kit';
+import { createRequire } from 'node:module';
 import { components } from '../core/index.js';
 import { themeInitScript } from '../theme.js';
 
 export default defineNuxtModule({
   meta: { name: '@ziyarago/ui', configKey: 'ziyarago', compatibility: { nuxt: '>=3.0.0' } },
-  defaults: { css: true, prefix: 'Ui', theme: { theme: 'dark', palette: 'gold', dir: 'ltr', bg: 'none', locale: 'en' } },
+  defaults: { css: true, plugins: [], prefix: 'Ui', theme: { theme: 'dark', palette: 'gold', dir: 'ltr', bg: 'none', locale: 'en' } },
   setup(opts, nuxt) {
     const { resolve } = createResolver(import.meta.url);
     if (opts.css) nuxt.options.css.push('@ziyarago/ui/style.css');
@@ -13,6 +14,13 @@ export default defineNuxtModule({
     for (const name of Object.keys(components)) {
       addComponent({ name: opts.prefix + name, export: opts.prefix + name, filePath: '@ziyarago/ui/vue' });
     }
+    for (const pkg of opts.plugins) {
+      nuxt.options.build.transpile.push(pkg);
+      let names = [];
+      try { names = createRequire(import.meta.url)(pkg + '/names'); } catch { try { names = createRequire(nuxt.options.rootDir + '/')(pkg + '/names'); } catch { console.warn(`[@ziyarago/ui] plugin ${pkg}: cannot load ${pkg}/names`); } }
+      for (const name of names) addComponent({ name: opts.prefix + name, export: 'Ui' + name, filePath: pkg + '/vue' });
+      if (opts.css) nuxt.options.css.push(pkg + '/style.css');
+    }
     addImports([
       { name: 'useUiTheme', from: '@ziyarago/ui/theme' },
       { name: 'fmt', from: '@ziyarago/ui/vue' },

package/src/react/index.js

@@ -2,7 +2,7 @@
 // React 18+ adapter. Usage: import { UiButton, UiAppShell } from '@ziyarago/ui/react'
 import React, { useState, useRef, useEffect, useLayoutEffect, useSyncExternalStore, createElement, cloneElement, isValidElement } from 'react';
 import { createPortal } from 'react-dom';
-import { components, subscribeUiLocale, getUiVersion } from '../core/index.js';
+import { components, registerComponents, subscribeUiLocale, getUiVersion } from '../core/index.js';
 
 const C = {};
 const useIsoLayoutEffect = typeof document === 'undefined' ? useEffect : useLayoutEffect;
@@ -37,6 +37,13 @@ const wrap = (name, def) => {
   return Comp;
 };
 for (const [name, def] of Object.entries(components)) C[name] = wrap(name, def);
+/** Wraps definitions like the built-in ones, registers them in C (cross references work both ways) and returns { UiName: Component }. */
+export function defineUiComponents(defs, { override = false } = {}) {
+  registerComponents(defs, { override });
+  const out = {};
+  for (const [name, def] of Object.entries(defs)) out['Ui' + name] = C[name] = wrap(name, def);
+  return out;
+}
 
 // Explicit named exports (not destructuring): Next.js reads the export names of a 'use client' module statically.
 export const UiButton = C.Button;

package/src/resolver.js

@@ -3,20 +3,31 @@
 //   import { ZiyaragoUiResolver } from '@ziyarago/ui/resolver'
 //   Components({ resolvers: [ZiyaragoUiResolver()] })
 // Zero dependencies: it only maps <UiButton> to { name: 'UiButton', from: '@ziyarago/ui/vue' }.
+import { createRequire } from 'node:module';
 import { components } from './core/index.js';
 
 const NAMES = new Set(Object.keys(components));
 
+// Plugin packages (see docs-private/PRO-SPLIT.md, "Plugin contract") export ./names (JSON array of component names without the Ui prefix) and ./vue.
+// A plugin may be a package name or { from, names } for tests and custom setups.
+const loadPlugin = p => {
+  if (typeof p !== 'string') return { from: p.from, names: new Set(p.names) };
+  const req = createRequire(process.cwd() + '/');
+  return { from: p + '/vue', names: new Set(req(p + '/names')) };
+};
+
 /**
- * @param {{ prefix?: string, css?: boolean | string, exclude?: string[], from?: string }} [options]
+ * @param {{ prefix?: string, css?: boolean | string, exclude?: string[], from?: string, plugins?: Array<string | { from: string, names: string[] }> }} [options]
  *   prefix  component prefix, default 'Ui' (must match the registered names, which are always Ui*)
  *   css     true: import '@ziyarago/ui/style.css' as a side effect together with the first resolved component (once per module that uses one);
  *           a string: import that path instead (for example your own entry that imports the css inside a Tailwind @layer). Default false.
  *   exclude component names (without prefix) that must not be auto-imported, e.g. ['Button'] if you keep your own UiButton.
  *   from    module the components are imported from, default '@ziyarago/ui/vue'
+ *   plugins add-on packages whose components auto-import too: ['@ziyarago/ui-pro'] (needs its ./names and ./vue exports) or [{ from, names }]
  */
 export function ZiyaragoUiResolver(options = {}) {
-  const { prefix = 'Ui', css = false, exclude = [], from = '@ziyarago/ui/vue' } = options;
+  const { prefix = 'Ui', css = false, exclude = [], from = '@ziyarago/ui/vue', plugins = [] } = options;
+  const loaded = plugins.map(loadPlugin);
   const skip = new Set(exclude.map(n => n.replace(/^Ui/, '')));
   const sideEffects = css ? (css === true ? '@ziyarago/ui/style.css' : css) : undefined;
   return {
@@ -24,8 +35,10 @@ export function ZiyaragoUiResolver(options = {}) {
     resolve(name) {
       if (!name.startsWith(prefix)) return;
       const bare = name.slice(prefix.length);
-      if (!NAMES.has(bare) || skip.has(bare)) return;
-      return { name: 'Ui' + bare, from, ...(sideEffects ? { sideEffects } : {}) };
+      if (skip.has(bare)) return;
+      const pl = NAMES.has(bare) ? null : loaded.find(x => x.names.has(bare));
+      if (!pl && !NAMES.has(bare)) return;
+      return { name: 'Ui' + bare, from: pl ? pl.from : from, ...(sideEffects ? { sideEffects } : {}) };
     },
   };
 }

package/src/vue/index.js

@@ -1,6 +1,6 @@
 // Vue 3 adapter. Usage: import { UiButton, UiAppShell } from '@ziyarago/ui/vue'
 import { h, ref, reactive, defineComponent, onMounted, onBeforeUnmount, Teleport, cloneVNode, isVNode } from 'vue';
-import { components, subscribeUiLocale } from '../core/index.js';
+import { components, registerComponents, subscribeUiLocale } from '../core/index.js';
 import { BOOL_PROPS } from '../core/bools.js';
 
 const C = {};
@@ -28,6 +28,13 @@ const wrap = (name, def) => defineComponent({
   },
 });
 for (const [name, def] of Object.entries(components)) C[name] = wrap(name, def);
+/** Wraps definitions like the built-in ones, registers them in C (cross references work both ways) and returns { UiName: Component }. */
+export function defineUiComponents(defs, { override = false } = {}) {
+  registerComponents(defs, { override });
+  const out = {};
+  for (const [name, def] of Object.entries(defs)) out['Ui' + name] = C[name] = wrap(name, def);
+  return out;
+}
 
 export const { Button: UiButton, IconButton: UiIconButton, Badge: UiBadge, Avatar: UiAvatar, Switch: UiSwitch, Checkbox: UiCheckbox, SegmentedControl: UiSegmentedControl, Tabs: UiTabs, FilterChips: UiFilterChips, TextField: UiTextField, Select: UiSelect, CodeInput: UiCodeInput, Stepper: UiStepper, Card: UiCard, Modal: UiModal, Drawer: UiDrawer, Toast: UiToast, Breadcrumbs: UiBreadcrumbs, Pagination: UiPagination, Progress: UiProgress, Ring: UiRing, KpiTile: UiKpiTile, DataTable: UiDataTable, KanbanColumn: UiKanbanColumn, KanbanCard: UiKanbanCard, Timeline: UiTimeline, TopNav: UiTopNav, SideNav: UiSideNav, AppShell: UiAppShell, PageHeader: UiPageHeader, AuthLayout: UiAuthLayout, LeadCard: UiLeadCard, HotelCard: UiHotelCard, TourCard: UiTourCard, PrayerTimes: UiPrayerTimes, RamadanTracker: UiRamadanTracker, QiblaCompass: UiQiblaCompass, CallRow: UiCallRow, Alert: UiAlert, Banner: UiBanner, Accordion: UiAccordion, Skeleton: UiSkeleton, Spinner: UiSpinner, Divider: UiDivider, EmptyState: UiEmptyState, ErrorPage: UiErrorPage, DataState: UiDataState, LoadingOverlay: UiLoadingOverlay, ConfirmDialog: UiConfirmDialog, Popconfirm: UiPopconfirm, Carousel: UiCarousel, Gallery: UiGallery, Code: UiCode, PricingCard: UiPricingCard, IntegrationCard: UiIntegrationCard, IncomingCall: UiIncomingCall, CallCard: UiCallCard, Dropdown: UiDropdown, Menu: UiMenu, Tooltip: UiTooltip, HoverCard: UiHoverCard, Popover: UiPopover, CopyButton: UiCopyButton, CommandBar: UiCommandBar, CommandPalette: UiCommandPalette, NotificationBell: UiNotificationBell, ToggleGroup: UiToggleGroup, Fab: UiFab, Textarea: UiTextarea, NumberInput: UiNumberInput, PasswordInput: UiPasswordInput, SearchInput: UiSearchInput, RadioGroup: UiRadioGroup, Slider: UiSlider, Rating: UiRating, ChipInput: UiChipInput, InlineEdit: UiInlineEdit, ColorPicker: UiColorPicker, FileUpload: UiFileUpload, Combobox: UiCombobox, MultiSelect: UiMultiSelect, GroupedSelect: UiGroupedSelect, PhoneInput: UiPhoneInput, Calendar: UiCalendar, DatePicker: UiDatePicker, TimePicker: UiTimePicker, FormField: UiFormField, LoginForm: UiLoginForm, StepForm: UiStepForm, Tag: UiTag, Kbd: UiKbd, StatsCard: UiStatsCard, KpiInline: UiKpiInline, MiniChart: UiMiniChart, Descriptions: UiDescriptions, LazyImage: UiLazyImage, SystemStatus: UiSystemStatus, TreeView: UiTreeView, CalendarView: UiCalendarView, SubNav: UiSubNav, ActionRail: UiActionRail, SplitLayout: UiSplitLayout, SettingsSection: UiSettingsSection, ScrollArea: UiScrollArea, DealCard: UiDealCard, PipelineBoard: UiPipelineBoard, ContactPanel: UiContactPanel, SalesFunnel: UiSalesFunnel, BookingCard: UiBookingCard, GuestCard: UiGuestCard, RoomGrid: UiRoomGrid, RoomCalendar: UiRoomCalendar, OccupancyChart: UiOccupancyChart, Chip: UiChip, IconTile: UiIconTile, StatusIcon: UiStatusIcon, UserCell: UiUserCell, StatRow: UiStatRow, CountryRow: UiCountryRow, StatLine: UiStatLine, StatStrip: UiStatStrip, VersusBar: UiVersusBar, SegBar: UiSegBar, HeroBanner: UiHeroBanner, TabTiles: UiTabTiles, PillTabs: UiPillTabs, PillSelect: UiPillSelect, ChartCard: UiChartCard, ActionCard: UiActionCard, Snackbar: UiSnackbar, TourPopover: UiTourPopover, ProfileHeader: UiProfileHeader, AuthSplit: UiAuthSplit, AuthShowcase: UiAuthShowcase, SocialAuth: UiSocialAuth, StatusPage: UiStatusPage, ValidatedField: UiValidatedField, Footer: UiFooter, DataGroup: UiDataGroup, OptionCard: UiOptionCard, OptionCards: UiOptionCards, RichEditor: UiRichEditor, RangeSlider: UiRangeSlider, RangeCalendar: UiRangeCalendar, StepDialog: UiStepDialog, FullscreenDialog: UiFullscreenDialog, PageDashboard: UiPageDashboard, PagePatterns: UiPagePatterns, PageCrm: UiPageCrm, PageBookings: UiPageBookings, PageCatalog: UiPageCatalog, PageDetail: UiPageDetail, PageSettings: UiPageSettings, PageUserList: UiPageUserList, PageProfile: UiPageProfile, PageForm: UiPageForm, PageOrder: UiPageOrder, PageAccount: UiPageAccount, PagePricing: UiPagePricing, PageFaq: UiPageFaq, PageAnalytics: UiPageAnalytics, PageCalendar: UiPageCalendar, PageKanban: UiPageKanban, PageBilling: UiPageBilling, PageTeam: UiPageTeam, PageIntegrations: UiPageIntegrations, PageSearch: UiPageSearch, PageArticle: UiPageArticle, PageChangelog: UiPageChangelog, PageHelp: UiPageHelp, PageStates: UiPageStates, PageLegal: UiPageLegal, PageLocations: UiPageLocations, PageBookingFlow: UiPageBookingFlow, PageItinerary: UiPageItinerary, PagePrayer: UiPagePrayer, PageGroupManager: UiPageGroupManager, PageTourPublic: UiPageTourPublic, PageNotifications: UiPageNotifications, PageInbox: UiPageInbox, PageCheckout: UiPageCheckout, PageOnboarding: UiPageOnboarding, PageLanding: UiPageLanding, PageAuth: UiPageAuth, PageStatus: UiPageStatus, TreeSelect: UiTreeSelect, ContextMenu: UiContextMenu, Sortable: UiSortable, Map: UiMap, ImageUpload: UiImageUpload, Screensaver: UiScreensaver, Tour: UiTour, Heading: UiHeading, Text: UiText, Box: UiBox, Center: UiCenter, HStack: UiHStack, VStack: UiVStack, Grid: UiGrid, Link: UiLink, Pressable: UiPressable, Icon: UiIcon, Portal: UiPortal, LiquidGlass: UiLiquidGlass, BottomSheet: UiBottomSheet, Actionsheet: UiActionsheet, ImageViewer: UiImageViewer, ChatAi: UiChatAi } = C;
 export const install = app => { for (const [n, c] of Object.entries(C)) app.component('Ui' + n, c); };

package/types/core.d.ts

@@ -1,4 +1,7 @@
 // Core (framework-neutral) entry. Most apps import from '@ziyarago/ui/vue' or '@ziyarago/ui/react' instead.
 export { rules, setIconBase, fmt } from './shared';
 export type * from './shared';
+export interface ComponentDefinition { state?: Record<string, unknown>; slots?: string[]; render: (ctx: any) => unknown }
+/** Extension API for add-on packages: adds definitions to the shared registry. Throws on a name clash with a different definition unless { override: true }. */
+export function registerComponents(defs: Record<string, ComponentDefinition>, options?: { override?: boolean }): Record<string, ComponentDefinition>;
 export const components: Record<string, { state?: Record<string, unknown>; slots?: string[]; render: (ctx: any) => unknown }>;

package/types/meta.d.ts

@@ -1,4 +1,7 @@
 export interface MetaProp { type: string; values?: string[]; default?: unknown; description?: string; required?: boolean; model?: boolean; forwarded?: boolean }
 export interface ComponentMeta { description: string; props?: Record<string, MetaProp>; slots?: Record<string, string>; events?: Record<string, string>; notes?: string[] }
+export interface MetaGroup { id: string; title?: string; blurb?: string; names: string[] }
+/** Extension API: adds metadata for plugin components. `tiers` are marked as pro, `groups` list them in the manifest. */
+export function registerMeta(extra: Record<string, ComponentMeta>, options?: { tiers?: string[]; groups?: MetaGroup[] }): Record<string, ComponentMeta>;
 export const meta: Record<string, ComponentMeta>;
 export default meta;

package/types/nuxt.d.ts

@@ -1,6 +1,8 @@
 export interface ModuleOptions {
   css?: boolean;
   prefix?: string;
+  /** Add-on packages (for example '@ziyarago/ui-pro'): their components auto-import and their style.css is added after the core css. */
+  plugins?: string[];
   theme?: false | { theme?: 'dark' | 'light'; palette?: 'gold' | 'tamam'; dir?: 'ltr' | 'rtl'; bg?: 'none' | 'aurora' | 'sunset' | 'ocean' | 'emerald' | 'rose' | 'mesh' };
 }
 declare const _default: import('@nuxt/schema').NuxtModule<ModuleOptions>;

package/types/react.d.ts

@@ -7739,3 +7739,5 @@ export const UiVersusBar: ComponentType<UiVersusBarProps>;
 export const rules: typeof import('./shared').rules;
 export { useUiTheme } from './theme';
 export { fmt, setIconBase } from './shared';
+/** Extension API: wraps plugin component definitions like the built-in ones, registers them (C.Name cross references work) and returns { UiName: Component }. */
+export function defineUiComponents(defs: Record<string, import('./core').ComponentDefinition>, options?: { override?: boolean }): Record<string, ComponentType<any>>;

package/types/resolver.d.ts

@@ -7,6 +7,8 @@ export interface ZiyaragoUiResolverOptions {
   exclude?: string[];
   /** Module the components come from. Default '@ziyarago/ui/vue'. */
   from?: string;
+  /** Add-on packages whose components auto-import too: a package name exporting ./names and ./vue, or an explicit { from, names }. */
+  plugins?: Array<string | { from: string; names: string[] }>;
 }
 export interface ZiyaragoUiResolverResult { name: string; from: string; sideEffects?: string }
 export interface ZiyaragoUiResolver { type: 'component'; resolve(name: string): ZiyaragoUiResolverResult | undefined }

package/types/vue.d.ts

@@ -7217,6 +7217,8 @@ export const UiVersusBar: UiVueComponent<UiVersusBarProps, UiVersusBarSlots>;
 
 export const rules: typeof import('./shared').rules;
 export function install(app: import('vue').App): void;
+/** Extension API: wraps plugin component definitions like the built-in ones, registers them (C.Name cross references work) and returns { UiName: Component }. */
+export function defineUiComponents(defs: Record<string, import('./core').ComponentDefinition>, options?: { override?: boolean }): Record<string, import('vue').Component>;
 declare const _default: { install: typeof install };
 export default _default;
 export { useUiTheme } from './theme';