@quidgest/ui 0.28.0 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (203) hide show
  1. package/CHANGELOG.md +51 -8
  2. package/README.md +19 -0
  3. package/dist/json/api.json +1517 -86
  4. package/dist/manifest/components.json +0 -1
  5. package/dist/ui.css +59 -68
  6. package/dist/ui.esm.js +1031 -1043
  7. package/dist/ui.js +1000 -1013
  8. package/dist/ui.min.css +1 -1
  9. package/dist/ui.min.js +1000 -1013
  10. package/dist/ui.scss +83 -27
  11. package/esm/components/QAccordion/QAccordion.d.ts +3 -3
  12. package/esm/components/QAccordion/QAccordion.d.ts.map +1 -1
  13. package/esm/components/QAccordion/QAccordion.vue.js +33 -30
  14. package/esm/components/QAccordion/QAccordionItem.d.ts +4 -1
  15. package/esm/components/QAccordion/QAccordionItem.d.ts.map +1 -1
  16. package/esm/components/QAccordion/QAccordionItem.vue.js +37 -6
  17. package/esm/components/QAccordion/index.d.ts +20 -11
  18. package/esm/components/QAccordion/index.d.ts.map +1 -1
  19. package/esm/components/QAvatar/QAvatar.d.ts.map +1 -1
  20. package/esm/components/QAvatar/QAvatar.vue.js +19 -12
  21. package/esm/components/QAvatar/types.d.ts +2 -1
  22. package/esm/components/QAvatar/types.d.ts.map +1 -1
  23. package/esm/components/QBadge/QBadge.d.ts.map +1 -1
  24. package/esm/components/QBadge/QBadge.vue.js +36 -37
  25. package/esm/components/QButtonGroup/QButtonGroup.vue.js +18 -18
  26. package/esm/components/QCarousel/QCarousel.d.ts +1 -1
  27. package/esm/components/QCarousel/QCarousel.d.ts.map +1 -1
  28. package/esm/components/QCarousel/QCarousel.vue.js +99 -95
  29. package/esm/components/QCarousel/constants.d.ts +1 -0
  30. package/esm/components/QCarousel/constants.d.ts.map +1 -1
  31. package/esm/components/QCarousel/constants.js +2 -1
  32. package/esm/components/QCarousel/index.d.ts +3 -3
  33. package/esm/components/QCheckbox/QCheckbox.d.ts +0 -2
  34. package/esm/components/QCheckbox/QCheckbox.d.ts.map +1 -1
  35. package/esm/components/QCheckbox/QCheckbox.vue.js +33 -36
  36. package/esm/components/QCheckbox/index.d.ts +0 -1
  37. package/esm/components/QCheckbox/index.d.ts.map +1 -1
  38. package/esm/components/QColorPicker/QColorPicker.d.ts.map +1 -1
  39. package/esm/components/QColorPicker/QColorPicker.vue.js +1 -2
  40. package/esm/components/QCombobox/QCombobox.d.ts +9 -0
  41. package/esm/components/QCombobox/QCombobox.d.ts.map +1 -1
  42. package/esm/components/QCombobox/QCombobox.vue.js +142 -134
  43. package/esm/components/QCombobox/index.d.ts +10 -0
  44. package/esm/components/QCombobox/index.d.ts.map +1 -1
  45. package/esm/components/QCombobox/types.d.ts +8 -0
  46. package/esm/components/QCombobox/types.d.ts.map +1 -1
  47. package/esm/components/QDateTimePicker/QDateTimePicker.d.ts.map +1 -1
  48. package/esm/components/QDateTimePicker/QDateTimePicker.vue.js +199 -219
  49. package/esm/components/QDialog/QDialog.d.ts +1 -1
  50. package/esm/components/QDialog/QDialog.d.ts.map +1 -1
  51. package/esm/components/QDialog/QDialog.vue.js +4 -4
  52. package/esm/components/QDialog/QDialogProvider.d.ts.map +1 -1
  53. package/esm/components/QDialog/index.d.ts +6 -6
  54. package/esm/components/QDialog/types.d.ts +3 -3
  55. package/esm/components/QDialog/types.d.ts.map +1 -1
  56. package/esm/components/QDropdownMenu/QDropdownMenuContent.d.ts +8 -0
  57. package/esm/components/QDropdownMenu/QDropdownMenuContent.d.ts.map +1 -1
  58. package/esm/components/QDropdownMenu/QDropdownMenuContent.vue.js +136 -124
  59. package/esm/components/QFileUpload/QFileUpload.d.ts.map +1 -1
  60. package/esm/components/QFileUpload/QFileUpload.vue.js +82 -79
  61. package/esm/components/QFocusWrap/QFocusWrap.d.ts.map +1 -1
  62. package/esm/components/QIcon/QIconFont.d.ts.map +1 -1
  63. package/esm/components/QIcon/QSvgSymbol.d.ts.map +1 -1
  64. package/esm/components/QIcon/QSvgSymbol.vue.js +31 -31
  65. package/esm/components/QInputGroup/QInputGroup.d.ts.map +1 -1
  66. package/esm/components/QInputGroup/QInputGroup.vue.js +67 -41
  67. package/esm/components/QInputGroup/types.d.ts +15 -1
  68. package/esm/components/QInputGroup/types.d.ts.map +1 -1
  69. package/esm/components/QList/QList.d.ts +6 -0
  70. package/esm/components/QList/QList.d.ts.map +1 -1
  71. package/esm/components/QList/QList.vue.js +4 -1
  72. package/esm/components/QList/QListItem.d.ts +6 -2
  73. package/esm/components/QList/QListItem.d.ts.map +1 -1
  74. package/esm/components/QList/QListItem.vue.js +54 -41
  75. package/esm/components/QList/index.d.ts +6 -1
  76. package/esm/components/QList/index.d.ts.map +1 -1
  77. package/esm/components/QList/types.d.ts +16 -0
  78. package/esm/components/QList/types.d.ts.map +1 -1
  79. package/esm/components/QOverflow/QOverflow.d.ts +6 -1
  80. package/esm/components/QOverflow/QOverflow.d.ts.map +1 -1
  81. package/esm/components/QOverflow/QOverflow.vue.js +90 -95
  82. package/esm/components/QOverflow/index.d.ts +3 -3
  83. package/esm/components/QOverlay/QOverlay.d.ts.map +1 -1
  84. package/esm/components/QOverlay/QOverlay.vue.js +125 -117
  85. package/esm/components/QOverlay/types.d.ts +9 -2
  86. package/esm/components/QOverlay/types.d.ts.map +1 -1
  87. package/esm/components/QPasswordField/QPasswordField.d.ts +1 -0
  88. package/esm/components/QPasswordField/QPasswordField.d.ts.map +1 -1
  89. package/esm/components/QPasswordField/QPasswordField.vue.js +5 -0
  90. package/esm/components/QPasswordField/QPasswordFieldMeterOverlay.vue.js +1 -0
  91. package/esm/components/QPasswordField/index.d.ts +6 -0
  92. package/esm/components/QPasswordField/index.d.ts.map +1 -1
  93. package/esm/components/QPasswordField/types.d.ts +10 -0
  94. package/esm/components/QPasswordField/types.d.ts.map +1 -1
  95. package/esm/components/QPhoneField/QPhoneField.d.ts +184 -18
  96. package/esm/components/QPhoneField/QPhoneField.d.ts.map +1 -1
  97. package/esm/components/QPhoneField/index.d.ts +92 -9
  98. package/esm/components/QPhoneField/index.d.ts.map +1 -1
  99. package/esm/components/QPropertyList/QPropertyList.d.ts.map +1 -1
  100. package/esm/components/QPropertyList/QPropertyList.vue.js +62 -60
  101. package/esm/components/QPropertyList/QPropertyListRow.vue.js +2 -2
  102. package/esm/components/QPropertyList/index.d.ts.map +1 -1
  103. package/esm/components/QRadioGroup/QRadioButton.vue.js +2 -2
  104. package/esm/components/QRadioGroup/QRadioGroup.vue.js +46 -46
  105. package/esm/components/QRemoveScrollBar/QRemoveScrollBar.d.ts.map +1 -1
  106. package/esm/components/QRemoveScrollBar/QRemoveScrollBar.vue.js +7 -7
  107. package/esm/components/QRemoveScrollBar/utils/gap.d.ts +0 -6
  108. package/esm/components/QRemoveScrollBar/utils/gap.d.ts.map +1 -1
  109. package/esm/components/QRemoveScrollBar/utils/gap.js +12 -18
  110. package/esm/components/QRemoveScrollBar/utils/stylesheet.d.ts +11 -0
  111. package/esm/components/QRemoveScrollBar/utils/stylesheet.d.ts.map +1 -1
  112. package/esm/components/QRemoveScrollBar/utils/stylesheet.js +5 -5
  113. package/esm/components/QSelect/QSelect.d.ts +157 -0
  114. package/esm/components/QSelect/QSelect.d.ts.map +1 -1
  115. package/esm/components/QSelect/QSelect.vue.js +240 -212
  116. package/esm/components/QSelect/index.d.ts +84 -0
  117. package/esm/components/QSelect/index.d.ts.map +1 -1
  118. package/esm/components/QSelect/types.d.ts +8 -0
  119. package/esm/components/QSelect/types.d.ts.map +1 -1
  120. package/esm/components/QSidebar/QSidebar.d.ts.map +1 -1
  121. package/esm/components/QSidebar/QSidebar.vue.js +1 -2
  122. package/esm/components/QSidebar/QSidebarAnchor.vue.js +1 -1
  123. package/esm/components/QSidebar/QSidebarItem.d.ts.map +1 -1
  124. package/esm/components/QSidebar/QSidebarItem.vue.js +1 -1
  125. package/esm/components/QSidebar/QSidebarPanel.d.ts.map +1 -1
  126. package/esm/components/QSidebar/QSidebarPanel.vue.js +5 -5
  127. package/esm/components/QSidebar/context.d.ts +3 -3
  128. package/esm/components/QSidebar/context.d.ts.map +1 -1
  129. package/esm/components/QSteps/QSteps.d.ts +4 -4
  130. package/esm/components/QSteps/QSteps.d.ts.map +1 -1
  131. package/esm/components/QSteps/QSteps.vue.js +9 -15
  132. package/esm/components/QSteps/index.d.ts +2 -2
  133. package/esm/components/QSteps/types.d.ts +2 -1
  134. package/esm/components/QSteps/types.d.ts.map +1 -1
  135. package/esm/components/QTabs/QTab.d.ts.map +1 -1
  136. package/esm/components/QTabs/QTab.vue.js +2 -2
  137. package/esm/components/QTabs/QTabs.d.ts +4 -4
  138. package/esm/components/QTabs/QTabs.d.ts.map +1 -1
  139. package/esm/components/QTabs/QTabs.vue.js +86 -85
  140. package/esm/components/QTabs/context.d.ts +3 -3
  141. package/esm/components/QTabs/context.d.ts.map +1 -1
  142. package/esm/components/QTabs/index.d.ts +2 -2
  143. package/esm/components/QTextArea/QTextArea.d.ts +1 -1
  144. package/esm/components/QTextArea/QTextArea.d.ts.map +1 -1
  145. package/esm/components/QTextArea/QTextArea.vue.js +25 -24
  146. package/esm/components/QTextArea/index.d.ts +3 -3
  147. package/esm/components/QToast/QToast.d.ts.map +1 -1
  148. package/esm/components/QToast/QToast.vue.js +7 -4
  149. package/esm/components/QToast/QToaster.d.ts.map +1 -1
  150. package/esm/components/QToast/types.d.ts +3 -3
  151. package/esm/components/QToggleGroup/QToggleGroup.d.ts +3 -3
  152. package/esm/components/QToggleGroup/QToggleGroup.d.ts.map +1 -1
  153. package/esm/components/QToggleGroup/QToggleGroup.vue.js +34 -31
  154. package/esm/components/QToggleGroup/index.d.ts +8 -8
  155. package/esm/components/QTooltip/QTooltip.d.ts.map +1 -1
  156. package/esm/components/QTooltip/QTooltip.vue.js +1 -1
  157. package/esm/composables/defaults.d.ts +10 -0
  158. package/esm/composables/defaults.d.ts.map +1 -1
  159. package/esm/composables/defaults.js +8 -5
  160. package/esm/composables/useDialog/_internal.js +8 -11
  161. package/esm/composables/useDialog/index.js +1 -2
  162. package/esm/composables/useDialog/types.d.ts.map +1 -1
  163. package/esm/composables/useDropZone/index.d.ts +1 -11
  164. package/esm/composables/useDropZone/index.d.ts.map +1 -1
  165. package/esm/composables/useDropZone/index.js +23 -26
  166. package/esm/composables/useGroup/index.d.ts.map +1 -1
  167. package/esm/composables/useGroup/index.js +15 -15
  168. package/esm/composables/useOverlayScope/index.d.ts +29 -0
  169. package/esm/composables/useOverlayScope/index.d.ts.map +1 -0
  170. package/esm/composables/useOverlayScope/index.js +23 -0
  171. package/esm/composables/useTextareaAutosize/index.d.ts +3 -1
  172. package/esm/composables/useTextareaAutosize/index.d.ts.map +1 -1
  173. package/esm/composables/useTextareaAutosize/index.js +6 -6
  174. package/esm/composables/useToast/_internal.js +10 -15
  175. package/esm/composables/useToast/index.js +1 -2
  176. package/esm/composables/useToast/types.d.ts.map +1 -1
  177. package/esm/framework.js +14 -12
  178. package/esm/index.d.ts +1 -2
  179. package/esm/index.d.ts.map +1 -1
  180. package/esm/symbols/overlayScope.d.ts +4 -0
  181. package/esm/symbols/overlayScope.d.ts.map +1 -0
  182. package/esm/symbols/overlayScope.js +4 -0
  183. package/esm/types/component.d.ts +8 -0
  184. package/esm/types/component.d.ts.map +1 -1
  185. package/esm/types/index.d.ts +1 -1
  186. package/esm/types/index.d.ts.map +1 -1
  187. package/esm/utils/color/parse.d.ts.map +1 -1
  188. package/esm/utils/color/parse.js +3 -10
  189. package/esm/utils/date.d.ts +35 -13
  190. package/esm/utils/date.d.ts.map +1 -1
  191. package/esm/utils/date.js +313 -253
  192. package/esm/utils/mask.d.ts +1 -0
  193. package/esm/utils/mask.d.ts.map +1 -1
  194. package/esm/utils/mask.js +42 -100
  195. package/esm/utils/overlay.d.ts +13 -1
  196. package/esm/utils/overlay.d.ts.map +1 -1
  197. package/esm/utils/overlay.js +55 -41
  198. package/esm/utils/safeTriangle.d.ts.map +1 -1
  199. package/esm/utils/safeTriangle.js +2 -2
  200. package/esm/utils/setupPropsProxy.d.ts +3 -1
  201. package/esm/utils/setupPropsProxy.d.ts.map +1 -1
  202. package/esm/utils/setupPropsProxy.js +2 -2
  203. package/package.json +9 -6
package/CHANGELOG.md CHANGED
@@ -5,9 +5,56 @@ All notable changes to `@quidgest/ui` are documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
- On `0.x`, breaking changes typically ship as a **minor** bump. The `/release` workflow appends a section for each **major**/**minor** release (and for **patch** when there is something notable), including public API breaks with migration steps plus notable Added/Changed/Fixed entries. This file also ships in the npm package.
8
+ Entries below start at **0.16.0**. There's a section for every release (major, minor, and patch), including public API breaks with migration steps plus notable Added/Changed/Fixed entries. This file also ships in the npm package.
9
9
 
10
- Entries below start at **0.16.0**. Earlier history is in git / GitLab MRs. Patch releases within a minor line may be summarized under that minor unless a break shipped in between.
10
+ ## [0.29.0] - 2026-10-19
11
+
12
+ ### Added
13
+
14
+ - `QSelect` and `QCombobox` `overflow` — how long option labels behave: `wrap` (default) wraps them inside a menu as wide as the field, `truncate` keeps one line with an ellipsis and shows the full label as a `title` on hover, and `fit-content` widens the menu to the longest option. `QOptionOverflow` type exported from the package root
15
+ - `QList` `itemTitle` and `QListItem` `overflowTitle` — a label that is cut off shows its full text as a native `title` on hover
16
+ - `QPasswordField` `autocomplete` — `current-password` for login fields, `new-password` (default) for set/change password fields
17
+ - `QOverlay` `disabled` — its anchor does not open it, and an open overlay closes when it becomes disabled. `disabled` on `QPopover` and `QTooltip` now works through it
18
+ - `@quidgest/ui/api` export — the generated `api.json` catalog of components, composables, and utils. Storybook gains **API/Overview**, **API/Composables**, and **API/Utils** pages
19
+ - `parseDate` and `parseDateWithCompletion` accept `{ ignoreWeekday: true }`. `DateParserLabels` gains optional `getMonthName` and `getWeekdayName`, so typed text is read in the language it is shown in
20
+
21
+ ### Changed
22
+
23
+ - **Breaking:** `QSelect` / `QCombobox` — by default the menu no longer grows wider than the field for long labels; they wrap instead. Set `overflow="fit-content"` for the old wide menu
24
+ - **Breaking:** `QList` — `.q-list-item__check-container--top` is removed. Every option centers its check on the first line of its label. Remove CSS that targets the class
25
+ - **Breaking:** `QPasswordField` renders `autocomplete="new-password"` by default, so browsers no longer fill in a saved password. Login fields must set the token: `<q-password-field v-model="password" autocomplete="current-password" />`
26
+ - **Breaking:** `--q-overlay-bg` is renamed to `--q-overlay-background`. Apps that override it must use the new name
27
+ - **Breaking:** `.q-overlay__arrow` is a sibling of `.q-overlay__content`, no longer inside it. Target `.q-overlay .q-overlay__arrow` instead of `.q-overlay__content .q-overlay__arrow`. The arrow no longer inherits a background set on `.q-overlay__content`; set `--q-overlay-background` instead
28
+ - **Breaking:** Anchored overlays (`QPopover`, `QTooltip`, `QDropdownMenu`, `QSelect`, `QCombobox`, `QDateTimePicker`) no longer have the container's `max-height: calc(100vh - …)`. When neither side of the anchor has room, the overlay opens on the side with more room, and its content is limited to that room and scrolls
29
+ - **Breaking:** `--q-icon-size-sm-base`, `--q-icon-size-md-base`, and `--q-icon-size-lg-base` are removed. Set `--q-icon-size-sm`, `--q-icon-size-md`, and `--q-icon-size-lg` instead, in `em`, without multiplying by `--q-density-scale`. Outside regular density at medium size, icons change size to match their text: smaller in loose density and in `large` controls, larger in compact density and in `small` controls
30
+ - **Breaking:** `QCarousel` `texts` gains a `slide` key (`'Slide {0}'`), the alt text of an untitled slide image. `texts` is all-or-nothing, so apps that pass their own `texts` must add `slide`
31
+ - **Breaking:** `QOverflow.scrollElementIntoView` returns a Promise that settles after the scroll starts. Callers that ignore the result are not affected
32
+ - Props passed in camelCase (render functions, JSX, `v-bind` objects) now override provided and app defaults, as kebab-case props already did
33
+ - Clicking a click-triggered overlay anchor again closes the overlay, so a `QDropdownMenu` activator or a help button toggles
34
+ - `parseDate` returns `null` when a weekday name does not match the date (`Fri, Apr 9, 2026`)
35
+ - `createFramework` warns and uses the first theme when `defaultTheme` names none of the configured themes, instead of installing no theme
36
+
37
+ ### Fixed
38
+
39
+ - Overlays — the arrow points at the center of its anchor in every density; an overlay too large for either side of its anchor stays in view; `QOverlay` stops its position timer and window listeners when it unmounts while open; nested scroll locks no longer shift the page; the overlay offset follows density
40
+ - `QDropdownMenu` — an outside press closes every level of the menu, and a submenu no longer opens its own submenu by itself
41
+ - `QTooltip` — changing its anchor moves `aria-describedby` to the new anchor
42
+ - `QSelect` — long options no longer spill past the menu; the "+N" counter shows in full, every badge that fits is shown, and the count updates when badges resize; removing a badge removes its own value; the list stays open when the app sets the value; clicking the field while the list is open closes it
43
+ - `QCombobox` — the list scrolls only when the next option is out of view
44
+ - `QList` — emits `update:modelValue` only for changes made in the list
45
+ - `QPropertyList` — keeps the selected row while focus stays in the list, clears it when its group closes, and no longer cancels clicks on controls in its cells
46
+ - Multiple selection in `QToggleGroup`, `QAccordion`, `QSelect`, and `QList` keeps an array when the model is cleared or set to a single value from outside
47
+ - `QButtonGroup`, `QToggleGroup`, `QRadioGroup`, `QTabs`, and `QAccordion` no longer override an app's boolean defaults for their children, and components follow later changes to provided defaults
48
+ - `QInputGroup` — `disabled` and `readonly` reach the controls in the group
49
+ - `QFileUpload` — a refused drop no longer makes the browser open the file and leave the page; read-only keeps Download
50
+ - `QTextArea` — `autosize` resizes for values set from code
51
+ - `QDateTimePicker` — picking a range over an existing one edits the new range; typed text is read with localized month and weekday names; a stale weekday name is rewritten instead of rejected
52
+ - Date utils — `SSS` and `S` tokens, time zone tokens `X` / `XX` / `XXX`, one-digit segments before a separator, quoted literals in format checks, and missing years (no longer filled with zeros); `parseIsoDate` rejects impossible days; `addMonths` keeps the day and time and clamps to the target month's last day (31 January + 1 month = 28 February)
53
+ - `QDialog` — `buttons: []` hides the button row; `icon: null` is typed
54
+ - `QTabs` corrects a `v-model` set later to a disabled tab or a missing value, and a disabled `QTabs` with no `v-model` shows its first tab; `QSteps` scrolls a step active on mount into view; `QOverflow` arrows work in item mode
55
+ - `QCarousel` — opens at `currentSlide`; a tap no longer advances; autoplay stops at the last slide when `wrap` is off
56
+ - `QSidebar` — resizing no longer jumps at the start, reports the real width, cleans up when `resizable` turns off mid-drag, and never sets a negative width
57
+ - `QIcon` keeps its box while its SVG bundle loads; `QAvatar` shows its initials or `fallback` slot when its image fails; `QAccordionItem` forwards `QCollapsible` props by name; `QBadge` runs its click handler only from its button
11
58
 
12
59
  ## [0.28.0] - 2026-10-13
13
60
 
@@ -268,10 +315,6 @@ Entries below start at **0.16.0**. Earlier history is in git / GitLab MRs. Patch
268
315
  - `QDateTimePicker` — commit valid values on Enter/blur instead of masking while typing; tabbing / focus improvements
269
316
  - `QCollapsible` — full header is clickable
270
317
 
271
- ### Infrastructure
272
-
273
- - Storybook 10.5 and pnpm 11.21 bumps
274
-
275
318
  ## [0.17.0] - 2026-06-24
276
319
 
277
320
  ### Changed
@@ -296,7 +339,7 @@ Entries below start at **0.16.0**. Earlier history is in git / GitLab MRs. Patch
296
339
  - `QAccordion` now expects `QAccordionItem` children in the default slot
297
340
  - Remove `active` from `QButton`; use `QToggle` for stateful toggle behavior
298
341
 
299
- ### Added _(0.16.x through 0.16.75)_
342
+ ### Added
300
343
 
301
344
  - Layout: `QSidebar`, grid primitives (`QContainer` / `QRow` / `QCol` / `QSpacer`), `QDivider`, `QSpacing` utilities
302
345
  - Overlays / feedback: `QDialog` + `QDialogProvider` / `useDialog`, `QToast`, `QFocusWrap`, nested `QDropdownMenu`
@@ -304,7 +347,7 @@ Entries below start at **0.16.0**. Earlier history is in git / GitLab MRs. Patch
304
347
  - Theming / defaults: `QDefaultsProvider`, `QThemeProvider` accepts full `ThemeDefinition`, configurable `QField` / `QLabel` `labelPosition`
305
348
  - Tooling: `@category` JSDoc on props (api-generator / Storybook)
306
349
 
307
- ### Fixed _(highlights)_
350
+ ### Fixed
308
351
 
309
352
  - Broad accessibility and focus-trap work across `QOverlay`, `QSelect`, `QCheckbox`, `QRadioGroup`, and related controls
310
353
  - Mobile overlay dismissal and button hover sticky-state fixes
package/README.md CHANGED
@@ -68,6 +68,25 @@ Once installed, components can be used like so:
68
68
  </script>
69
69
  ```
70
70
 
71
+ ## Public API metadata
72
+
73
+ The package ships a machine-readable catalog of the public surface at `@quidgest/ui/api` (`dist/json/api.json`):
74
+
75
+ ```ts
76
+ // Node ESM (and environments that require an import attribute):
77
+ import api from '@quidgest/ui/api' with { type: 'json' }
78
+
79
+ // Bundlers often accept a bare JSON import; TypeScript needs `resolveJsonModule`.
80
+ // import api from '@quidgest/ui/api'
81
+
82
+ api.version // package version
83
+ api.components // Vue component docs (props, events, examples)
84
+ api.composables // symbols re-exported from `src/composables/index.ts`
85
+ api.utils // utils submodules re-exported from `src/utils/index.ts`
86
+ ```
87
+
88
+ The selective barrels are the allowlist: only what those entry files re-export appears under `composables` and `utils`. The file is produced by `pnpm build:api` (also run before Storybook and in the package publish pipeline). Component Storybook docs remain the primary human reference for props; use this export for tooling (codegen, Genio, audits) or the Storybook **API/** pages for composables and utils.
89
+
71
90
  ## Development
72
91
 
73
92
  The package utilizes Storybook for component development and organization. You can view the components locally in the Storybook documentation explorer.