@quidgest/ui 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -9,6 +9,33 @@ On `0.x`, breaking changes typically ship as a **minor** bump. The `/release` wo
 
 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.
 
+## [0.21.0] - 2026-09-10
+
+### Changed
+
+- **Breaking:** `useId` — no longer returns a UUID-based `Ref` (`uid-…`); wraps Vue `useId` as a `ComputedRef` with `q-…` ids (custom `app.config.idPrefix` becomes `q-<prefix>-…`) and must run during setup. Drop any reliance on the removed `uuid` dependency from `@quidgest/ui`.
+- **Breaking:** `useDialog` / `useToast` — require `createFramework` plus a mounted `QDialogProvider` / `QToaster`. `addDialog` / `addToast` no longer take a separate `id` argument and return `Promise<string>`; prefer `await addDialog(props)` / `await addToast(props)`, pass overrides via `props.id`, and use `cancelDialog` / `cancelToast` before registration. `removeDialog` / `removeToast` throw if the id is missing; do not mutate the public `dialogs` / `toasts` lists to update the store.
+- **Breaking:** Package exports — the `./*` catch-all export was removed; import only via documented entry points.
+- **Breaking:** Color utilities — public `isCssColor` removed; use `isThemeColor` for utility/BEM classification, or `tryParseColor` / `parseColor` to test parseability. Unsupported / unparsed CSS colors no longer silently fall back to primary-like CSS vars (expect `undefined` style and a non-production warning). Contrasting/`on*` text for custom colors may change where WCAG luminance disagrees with the old HSL-lightness heuristic.
+- **Breaking:** `QButton` / `QBadge` / `QToast` — utility color BEM modifiers (`q-button--primary`, `q-badge--…`, `q-toast--…`, etc.) are no longer emitted; style via bound `--q-*-main-color` / hover CSS variables (`.q-button--background` remains for that special case). Do not target those color modifier classes in consumer CSS.
+- Theme / `useColor` — Light/Dark schemes and default `on*` tokens aligned with WCAG; pure `on*` surface tokens; utility colors always bind style (including Dark-scheme hover).
+
+### Fixed
+
+- `QInputGroup` — restore radius for solo addons; equalize sibling control heights
+- `QIcon` — size uncropped SVGs correctly in controls
+- Storybook — set per-story Vue `idPrefix` to avoid id collisions across stories
+
+## [0.20.1] - 2026-09-04
+
+### Added
+
+- `QGauge` — gauge / meter UI component
+
+### Fixed
+
+- Distributed SCSS — preserve `url(...)` references so asset paths survive packaging
+
 ## [0.20.0] - 2026-09-01
 
 ### Changed
@@ -73,7 +100,7 @@ Entries below start at **0.16.0**. Earlier history is in git / GitLab MRs. Patch
 - **Breaking:** Unified group / toggle APIs for consistency:
     - Rename `QButtonToggle` → `QToggleButton`; pass items via the default slot (`options` prop removed)
     - `QAccordion` now expects `QAccordionItem` children in the default slot
-    - Remove `active` from `QButton`; use `QToggle` for stateful toggle behaviour
+    - Remove `active` from `QButton`; use `QToggle` for stateful toggle behavior
 
 ### Added _(0.16.x through 0.16.75)_
 

package/README.md

@@ -42,6 +42,16 @@ import framework from './plugins/quidgest-ui'
 createApp(App).use(framework).mount('#app')
 ```
 
+Mount **one** `QDialogProvider` and **one** `QToaster` in the app root (for example `App.vue`). `useDialog` / `useToast` share a single list per app; mounting a second provider or toaster for the same app throws.
+
+```vue
+<template>
+	<q-dialog-provider />
+	<q-toaster />
+	<router-view />
+</template>
+```
+
 Once installed, components can be used like so:
 
 ```vue

package/dist/json/api.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.20.0",
+  "version": "0.21.0",
   "components": [
     {
       "name": "QAccordion",
@@ -123,7 +123,7 @@
       "examples": [
         {
           "title": "Default",
-          "description": "Default behaviour of the accordion.",
+          "description": "Default behavior of the accordion.",
           "code": "<q-accordion v-bind=\"args\">\n\t\t  <q-accordion-item title=\"Section 1\" value=\"1\">\n\t\t\tContent for section 1\n\t\t  </q-accordion-item>\n\t\t  <q-accordion-item title=\"Section 2\" value=\"2\">\n\t\t\tContent for section 2\n\t\t  </q-accordion-item>\n\t\t  <q-accordion-item title=\"Section 3\" value=\"3\">\n\t\t\tContent for section 3\n\t\t  </q-accordion-item>\n\t\t</q-accordion>"
         },
         {
@@ -1008,32 +1008,32 @@
       "examples": [
         {
           "title": "Default",
-          "description": "Default behaviour of the card.",
+          "description": "Default behavior of the card.",
           "code": "<q-card v-bind=\"args\">\n\t\t\t\t<q-text-field label=\"Text input\"/>\n\t\t\t</q-card>"
         },
         {
           "title": "Clickable",
-          "description": "Default behaviour of a clickable card.",
+          "description": "Default behavior of a clickable card.",
           "code": "<q-card v-bind=\"args\" @click=\"onClick\">\n\t\t\t\t\t{{ args.subtitle }}\n\t\t\t\t</q-card>"
         },
         {
           "title": "Link",
-          "description": "Default behaviour of a card with a link/url.",
+          "description": "Default behavior of a card with a link/url.",
           "code": "<q-card v-bind=\"args\">\n\t\t\t\t{{ args.subtitle }}\n\t\t\t</q-card>"
         },
         {
           "title": "Loading",
-          "description": "Default behaviour of a loading card.",
+          "description": "Default behavior of a loading card.",
           "code": "<q-card v-bind=\"args\">\n\t\t\t\t<q-text-field label=\"Text input\"/>\n\t\t\t</q-card>"
         },
         {
           "title": "Borderless",
-          "description": "Default behaviour of a borderless card.",
+          "description": "Default behavior of a borderless card.",
           "code": "<q-card v-bind=\"args\">\n\t\t\t\t<q-text-field label=\"Text input\"/>\n\t\t\t</q-card>"
         },
         {
           "title": "Elevation",
-          "description": "Default behaviour of a card with elevation.",
+          "description": "Default behavior of a card with elevation.",
           "code": "<div style=\"display: flex; gap: 1rem;\">\n\t\t\t\t<q-card v-bind=\"args\" title=\"Elevated Low\" elevation=\"low\">\n\t\t\t\t\tSome quick example text to build on the card title.\n\t\t\t\t</q-card>\n\t\t\t\t<q-card v-bind=\"args\" title=\"Elevated Medium\" elevation=\"medium\">\n\t\t\t\t\tSome quick example text to build on the card title.\n\t\t\t\t</q-card>\n\t\t\t\t<q-card v-bind=\"args\" title=\"Elevated High\" elevation=\"high\">\n\t\t\t\t\tSome quick example text to build on the card title.\n\t\t\t\t</q-card>\n\t\t\t</div>"
         },
         {
@@ -1689,22 +1689,22 @@
       "examples": [
         {
           "title": "Default",
-          "description": "Default behaviour of the collapsible.",
+          "description": "Default behavior of the collapsible.",
           "code": "<q-collapsible v-bind=\"args\">\n\t\t\t\t<q-text-field label=\"Text input\"/>\n\t\t\t</q-collapsible>"
         },
         {
           "title": "Starts Expanded",
-          "description": "Behaviour of a collapsible that starts expanded.",
+          "description": "Behavior of a collapsible that starts expanded.",
           "code": "<q-collapsible v-bind=\"args\">\n\t\t\t\t<q-text-field label=\"Text input\"/>\n\t\t\t</q-collapsible>"
         },
         {
           "title": "Subtitle",
-          "description": "Behaviour of the collapsible with a title.",
+          "description": "Behavior of the collapsible with a title.",
           "code": "<q-collapsible v-bind=\"args\">\n\t\t\t\t<q-text-field label=\"Text input\"/>\n\t\t\t</q-collapsible>"
         },
         {
           "title": "Required",
-          "description": "Behaviour of the collapsible when there are required fields inside.",
+          "description": "Behavior of the collapsible when there are required fields inside.",
           "code": "<q-collapsible v-bind=\"args\">\n\t\t\t\t<q-text-field label=\"Text input\" required/>\n\t\t\t</q-collapsible>"
         },
         {
@@ -2871,6 +2871,16 @@
             "default": "DEFAULT_ICONS",
             "required": false,
             "category": "Configuration"
+          },
+          {
+            "name": "entryKey",
+            "type": {
+              "kind": "primitive",
+              "name": "string"
+            },
+            "description": "",
+            "default": "undefined",
+            "required": false
           }
         ],
         "events": [
@@ -2919,7 +2929,7 @@
       "examples": [
         {
           "title": "Default",
-          "description": "Default behaviour of the dialog.",
+          "description": "Default behavior of the dialog.",
           "code": "<q-button label=\"Click me\" @click=\"args.modelValue = true\" />\n\t\t\t<q-dialog v-model=\"args.modelValue\" v-bind=\"args\" />"
         },
         {
@@ -2939,7 +2949,7 @@
         },
         {
           "title": "Custom Buttons",
-          "description": "Custom buttons on the dialog allow the user to customize its look and behaviour.",
+          "description": "Custom buttons on the dialog allow the user to customize its look and behavior.",
           "code": "<QDialog :text=\"What shall we do?\" :icon=\"{\n\t\t\ticon: 'help-circle-outline'\n\t\t}\" :buttons=\"[\n\t\t\t{\n\t\t\t\tid: 'scroll-btn',\n\t\t\t\ticon: {\n\t\t\t\t\ticon: 'arrow-up'\n\t\t\t\t},\n\t\t\t\taction: () => {\n\t\t\t\t\twindow.scrollTo({ top: 0, behavior: 'smooth' })\n\t\t\t\t},\n\t\t\t\tprops: {\n\t\t\t\t\tlabel: 'Scroll to Top',\n\t\t\t\t\tvariant: 'bold'\n\t\t\t\t}\n\t\t\t},\n\t\t\t{\n\t\t\t\tid: 'refresh-btn',\n\t\t\t\ticon: {\n\t\t\t\t\ticon: 'refresh'\n\t\t\t\t},\n\t\t\t\taction: () => {\n\t\t\t\t\tlocation.reload()\n\t\t\t\t},\n\t\t\t\tprops: {\n\t\t\t\t\tlabel: 'Refresh the page!',\n\t\t\t\t\tvariant: 'bold',\n\t\t\t\t\tcolor: 'danger'\n\t\t\t\t}\n\t\t\t},\n\t\t\t{\n\t\t\t\tid: 'cancel-btn',\n\t\t\t\ticon: {\n\t\t\t\t\ticon: 'cancel'\n\t\t\t\t},\n\t\t\t\tprops: {\n\t\t\t\t\tlabel: 'Cancel'\n\t\t\t\t}\n\t\t\t}\n\t\t]\" />"
         },
         {
@@ -3857,6 +3867,269 @@
         }
       ]
     },
+    {
+      "name": "QGauge",
+      "description": "A gauge displays a KPI within a bounded scale and can highlight semantic performance ranges.",
+      "meta": {
+        "props": [
+          {
+            "name": "modelValue",
+            "type": {
+              "kind": "primitive",
+              "name": "number"
+            },
+            "description": "",
+            "required": false
+          },
+          {
+            "name": "id",
+            "type": {
+              "kind": "primitive",
+              "name": "string"
+            },
+            "description": "The component unique identifier.",
+            "required": false,
+            "category": "Identification"
+          },
+          {
+            "name": "min",
+            "type": {
+              "kind": "primitive",
+              "name": "number"
+            },
+            "description": "Lowest value represented by the scale.",
+            "default": "0",
+            "required": false,
+            "category": "Configuration"
+          },
+          {
+            "name": "max",
+            "type": {
+              "kind": "primitive",
+              "name": "number"
+            },
+            "description": "Highest value represented by the scale.",
+            "default": "100",
+            "required": false,
+            "category": "Configuration"
+          },
+          {
+            "name": "ranges",
+            "type": {
+              "kind": "array",
+              "elementType": {
+                "name": "object",
+                "value": {}
+              }
+            },
+            "description": "Colored intervals displayed over the neutral gauge track.",
+            "required": false,
+            "category": "Configuration"
+          },
+          {
+            "name": "ticks",
+            "type": {
+              "kind": "array",
+              "elementType": {
+                "name": "number"
+              }
+            },
+            "description": "Explicit values to label on the scale. Overrides tickCount.",
+            "required": false,
+            "category": "Configuration"
+          },
+          {
+            "name": "tickCount",
+            "type": {
+              "kind": "primitive",
+              "name": "number"
+            },
+            "description": "Number of evenly spaced scale labels generated when ticks is omitted.",
+            "default": "5",
+            "required": false,
+            "category": "Configuration"
+          },
+          {
+            "name": "label",
+            "type": {
+              "kind": "primitive",
+              "name": "string"
+            },
+            "description": "KPI title displayed above the gauge.",
+            "required": false,
+            "category": "Content"
+          },
+          {
+            "name": "valueLabel",
+            "type": {
+              "kind": "union",
+              "types": [
+                {
+                  "name": "string"
+                },
+                {
+                  "name": "other",
+                  "value": "(value: number, min: number, max: number): string"
+                }
+              ]
+            },
+            "description": "Text or formatter used as the fallback display and as the current-value part\nof `aria-valuetext`. Set this when the `value` slot changes how the value\nshould be announced, because slot markup cannot be inferred reliably for\naccessibility. When provided, it is treated as complete current-value text,\nso the unit is not appended there automatically.",
+            "required": false,
+            "category": "Content"
+          },
+          {
+            "name": "target",
+            "type": {
+              "kind": "primitive",
+              "name": "number"
+            },
+            "description": "Target value highlighted on the gauge track.",
+            "required": false,
+            "category": "Configuration"
+          },
+          {
+            "name": "targetComparison",
+            "type": {
+              "kind": "enum",
+              "values": [
+                "at-least",
+                "at-most"
+              ]
+            },
+            "description": "Target comparison mode. Use `at-least` when values should reach or exceed\nthe target, and `at-most` when values should stay at or below it.",
+            "default": "at-least",
+            "required": false,
+            "category": "Configuration"
+          },
+          {
+            "name": "targetLabel",
+            "type": {
+              "kind": "union",
+              "types": [
+                {
+                  "name": "string"
+                },
+                {
+                  "name": "other",
+                  "value": "(target: number, min: number, max: number): string"
+                }
+              ]
+            },
+            "description": "Text or formatter used to describe the target value.",
+            "required": false,
+            "category": "Content"
+          },
+          {
+            "name": "showTargetValue",
+            "type": {
+              "kind": "primitive",
+              "name": "boolean"
+            },
+            "description": "Whether the target value label is displayed next to the target marker.",
+            "required": false,
+            "category": "Presentation"
+          },
+          {
+            "name": "showLegend",
+            "type": {
+              "kind": "primitive",
+              "name": "boolean"
+            },
+            "description": "Whether the legend is displayed below the gauge.",
+            "default": "true",
+            "required": false,
+            "category": "Presentation"
+          },
+          {
+            "name": "showTargetLegend",
+            "type": {
+              "kind": "primitive",
+              "name": "boolean"
+            },
+            "description": "Whether target status items are included in the legend when a target marker\nis visible. The legend itself must also be enabled with `showLegend`.",
+            "default": "true",
+            "required": false,
+            "category": "Presentation"
+          },
+          {
+            "name": "unit",
+            "type": {
+              "kind": "primitive",
+              "name": "string"
+            },
+            "description": "Unit displayed next to the current value.",
+            "required": false,
+            "category": "Content"
+          },
+          {
+            "name": "secondaryLabel",
+            "type": {
+              "kind": "primitive",
+              "name": "string"
+            },
+            "description": "Supporting information displayed below the current value.",
+            "required": false,
+            "category": "Content"
+          },
+          {
+            "name": "texts",
+            "type": {
+              "kind": "object",
+              "fields": {}
+            },
+            "description": "Custom text configurations.",
+            "default": "DEFAULT_TEXTS",
+            "required": false,
+            "category": "Configuration"
+          },
+          {
+            "name": "tickFormatter",
+            "type": {
+              "kind": "unknown",
+              "raw": "((value: number) => string) | undefined"
+            },
+            "description": "Formatter used for scale labels.",
+            "required": false,
+            "category": "Configuration"
+          }
+        ],
+        "events": [
+          {
+            "name": "update:modelValue",
+            "description": "",
+            "type": "[value: number]"
+          }
+        ],
+        "slots": [
+          {
+            "name": "value",
+            "description": "Custom markup for the visible current value. Also set `valueLabel` when the\nslot changes how the value should be announced, because slot content does\nnot replace `aria-valuetext`."
+          }
+        ]
+      },
+      "examples": [
+        {
+          "title": "Default",
+          "description": "The default gauge uses semantic ranges and supporting KPI information.",
+          "code": "<QGauge :model-value=\"76\" :label=\"Delivery performance\" :target=\"80\" :target-label=\"Target 80%\" :show-target-value=\"true\" :unit=\"%\" :secondary-label=\"+4.2% from last month\" />"
+        },
+        {
+          "title": "Lower Is Better",
+          "description": "Range order and colors can represent metrics where lower values are better.",
+          "code": "<QGauge :model-value=\"18\" :label=\"Average response time\" :max=\"60\" :target=\"20\" :target-comparison=\"at-most\" :target-label=\"Target 20 min\" :show-target-value=\"true\" :unit=\"min\" :secondary-label=\"-3 min from last month\" :ranges=\"[\n\t\t\t{ from: 0, to: 20, color: 'success', label: 'On target' },\n\t\t\t{ from: 20, to: 40, color: 'warning', label: 'Attention' },\n\t\t\t{ from: 40, to: 60, color: 'danger', label: 'Critical' }\n\t\t]\" />"
+        },
+        {
+          "title": "Explicit Ticks",
+          "description": "Explicit ticks and formatters support domain-specific values.",
+          "code": "<QGauge :model-value=\"10.6\" :label=\"Revenue\" :max=\"21\" :target=\"15\" :target-label=\"Target 15M\" :show-target-value=\"true\" :unit=\"Dollars\" :ticks=\"0,3,6,9,12,15,18,21\" :value-label=\"(value: number) => `${value.toFixed(1)}M`\" :tick-formatter=\"(value: number) => (value === 0 ? '0' : `${value}M`)\" :ranges=\"[\n\t\t\t{ from: 0, to: 6, color: 'danger', label: 'Below target' },\n\t\t\t{ from: 6, to: 15, color: 'warning', label: 'Approaching target' },\n\t\t\t{ from: 15, to: 21, color: 'success', label: 'On target' }\n\t\t]\" />"
+        },
+        {
+          "title": "Responsive Composition",
+          "description": "Gauges remain responsive when composed into a KPI dashboard owned by the consumer.",
+          "code": "<div class=\"q-gauge-story-grid\">\n\t\t\t\t<q-gauge\n\t\t\t\t\tv-for=\"item in items\"\n\t\t\t\t\t:key=\"item.label\"\n\t\t\t\t\t:model-value=\"item.value\"\n\t\t\t\t\t:label=\"item.label\"\n\t\t\t\t\t:target=\"item.target\"\n\t\t\t\t\t:unit=\"item.unit\"\n\t\t\t\t\t:ranges=\"performanceRanges\"\n\t\t\t\t\t:show-legend=\"false\"\n\t\t\t\t/>\n\t\t\t</div>"
+        }
+      ]
+    },
     {
       "name": "QIcon",
       "description": "Displays an icon. Note: This Storybook includes a Material Design Icons v7.3.67 SVG bundle for demonstration purposes. For the complete list of available icons, visit the official [Material Design Icons](https://pictogrammers.com/library/mdi/) page.",
@@ -4134,6 +4407,16 @@
           "description": "Groups buttons with fields.",
           "code": "<q-input-group v-bind=\"args\">\n\t\t\t\t<q-text-field placeholder=\"Search\" />\n\t\t\t\t<template #append>\n\t\t\t\t\t<q-button>\n\t\t\t\t\t\t<q-icon icon=\"magnify\" />\n\t\t\t\t\t</q-button>\n\t\t\t\t</template>\n\t\t\t</q-input-group>"
         },
+        {
+          "title": "Append Only",
+          "description": "Append-only group — all four corners of the control should be rounded.",
+          "code": "<q-input-group v-bind=\"args\">\n\t\t\t\t<template #append>\n\t\t\t\t\t<q-button>\n\t\t\t\t\t\t<q-icon icon=\"cog\" />\n\t\t\t\t\t</q-button>\n\t\t\t\t</template>\n\t\t\t</q-input-group>"
+        },
+        {
+          "title": "Prepend Only",
+          "description": "Prepend-only group — all four corners of the control should be rounded.",
+          "code": "<q-input-group v-bind=\"args\">\n\t\t\t\t<template #prepend>\n\t\t\t\t\t<q-button>\n\t\t\t\t\t\t<q-icon icon=\"cog\" />\n\t\t\t\t\t</q-button>\n\t\t\t\t</template>\n\t\t\t</q-input-group>"
+        },
         {
           "title": "Button Group Addon",
           "description": "Further extends button addons with multiple buttons.",
@@ -4144,6 +4427,11 @@
           "description": "Provides a textual description for the group.",
           "code": "<QInputGroup :label=\"Full name\" :required=\"true\" />"
         },
+        {
+          "title": "Mixed Heights",
+          "description": "Keeps sibling controls aligned when one child has a larger intrinsic height.",
+          "code": "<q-input-group v-bind=\"args\">\n\t\t\t\t<q-text-field placeholder=\"Name\" />\n\t\t\t\t<q-text-area placeholder=\"Notes\" :rows=\"3\" />\n\t\t\t</q-input-group>"
+        },
         {
           "title": "Advanced Usage",
           "description": "Supports the creation of custom input groups using selects, text fields, buttons, and more.",
@@ -9222,6 +9510,16 @@
             "default": "DEFAULT_ICONS",
             "required": false,
             "category": "Configuration"
+          },
+          {
+            "name": "entryKey",
+            "type": {
+              "kind": "primitive",
+              "name": "string"
+            },
+            "description": "",
+            "default": "undefined",
+            "required": false
           }
         ],
         "events": [

package/dist/manifest/components.json

@@ -23,6 +23,7 @@
   "QField",
   "QFileUpload",
   "QFocusWrap",
+  "QGauge",
   "QCol",
   "QContainer",
   "QRow",