Document Badge component #180

content/modules/flow-ui/pages/vc/components/badge.adoc

@@ -0,0 +1,216 @@
+= badge
+
+[.since]
+Since Jmix 3.1
+
+`badge` displays a small piece of information, such as a status, a count or a label.
+
+[cols="1h,1", options="autowidth", grid=none, frame=none]
+|===
+|XML Element
+|`badge`
+
+|Java Class
+|`Badge`
+|===
+
+[[basics]]
+== Basics
+
+++++
+<div class="jmix-ui-live-demo-container">
+    <a href="https://demo.jmix.io/ui-samples/sample/badge-simple" class="live-demo-btn" target="_blank">LIVE DEMO</a>
+</div>
+++++
+
+The xref:vc/common-attributes.adoc#text[text] attribute sets the label of the badge. Keep it short: one or two words. The `success`, `warning` and `error` <<theme-variants,theme variants>> set the color of the badge. Without a variant, the badge uses the accent color of the theme.
+
+[source,xml,indent=0]
+----
+include::example$ui-samples/main/resources/io/jmix/uisamples/view/flowui/components/badge/simple/badge-simple.xml[tags=basics]
+----
+
+image::visual-components/components/badge-basics.png["Badges with the default and success, warning and error colors", align="center", width="322"]
+
+Badges look like buttons, but they are not interactive.
+
+[[data-binding]]
+== Data-aware `badge`
+
+++++
+<div class="jmix-ui-live-demo-container">
+    <a href="https://demo.jmix.io/ui-samples/sample/badge-dataaware" class="live-demo-btn" target="_blank">LIVE DEMO</a>
+</div>
+++++
+
+A badge can show the value of an entity attribute. Bind it to a xref:data/data-containers.adoc[data container] using the xref:vc/common-attributes.adoc#dataContainer[dataContainer] and xref:vc/common-attributes.adoc#property[property] attributes:
+
+[source,xml,indent=0]
+----
+include::example$ui-samples/main/resources/io/jmix/uisamples/view/flowui/components/badge/dataaware/badge-dataaware.xml[tags=data-binding]
+----
+
+The binding is read-only. The badge shows the attribute value as text and updates it when the value changes. The value is formatted according to its datatype. For example, an enumeration value is shown as its localized caption, and a `null` value is shown as an empty badge.
+
+If the current user has no permission to view the attribute, the badge is hidden.
+
+[[icons]]
+== Icons
+
+++++
+<div class="jmix-ui-live-demo-container">
+    <a href="https://demo.jmix.io/ui-samples/sample/badge-icons" class="live-demo-btn" target="_blank">LIVE DEMO</a>
+</div>
+++++
+
+A badge can show an icon before its text. Set the icon using the <<icon,icon>> attribute or the nested `icon` element:
+
+[source,xml,indent=0]
+----
+include::example$ui-samples/main/resources/io/jmix/uisamples/view/flowui/components/badge/icons/badge-icons.xml[tags=icons]
+----
+
+image::visual-components/components/badge-icons.png["Badges with an icon before the text", align="center", width="374"]
+
+The `icon-only` variant shows only the icon. Set the text anyway. It is hidden on the screen, but screen readers announce it.
+
+[source,xml,indent=0]
+----
+include::example$ui-samples/main/resources/io/jmix/uisamples/view/flowui/components/badge/icons/badge-icons.xml[tags=icon-only]
+----
+
+[[numbers]]
+== Number
+
+++++
+<div class="jmix-ui-live-demo-container">
+    <a href="https://demo.jmix.io/ui-samples/sample/badge-theme-variant" class="live-demo-btn" target="_blank">LIVE DEMO</a>
+</div>
+++++
+
+The <<number,number>> attribute shows a number in the badge, for example, the number of unread messages. If the badge has both text and a number, it shows both.
+
+The `number-only` variant shows only the number. As with `icon-only`, set the text for screen readers:
+
+[source,xml,indent=0]
+----
+include::example$ui-samples/main/resources/io/jmix/uisamples/view/flowui/components/badge/themevariant/badge-theme-variant.xml[tags=number-only]
+----
+
+In the view controller, use the `setNumber()` method to change the number and `setNumber(null)` to remove it.
+
+Screen readers read only the content of the badge. A number alone can confuse users, so set a text that says what is counted. If the number changes while the view is open, set <<ariaRole,ariaRole>> to `status`, and screen readers will announce the new value.
+
+[[theme-variants]]
+== Theme Variants
+
+++++
+<div class="jmix-ui-live-demo-container">
+    <a href="https://demo.jmix.io/ui-samples/sample/badge-theme-variant" class="live-demo-btn" target="_blank">LIVE DEMO</a>
+</div>
+++++
+
+Use the xref:vc/common-attributes.adoc#themeNames[themeNames] attribute to apply variants. You can combine several variants, for example, `themeNames="success filled"`. In the view controller, use the `addThemeVariants()` method with the `BadgeVariant` enumeration.
+
+image::visual-components/components/badge-visual-variants.png["Badges with the filled, icon-only, number-only and dot variants", align="center", width="191"]
+
+[cols="1,4,1", options="header"]
+|===
+|Variant
+|Description
+|Supported By
+
+|`success`, `warning`, `error`
+|Applies a semantic color.
+|Aura, Lumo
+
+|`contrast`
+|Applies a neutral high-contrast color.
+|Lumo
+
+|`filled`
+|Uses a solid background instead of a tinted one to draw more attention. Can be combined with all other variants.
+|Aura, Lumo
+
+|`small`
+|Makes the badge smaller.
+|Aura, Lumo
+
+|`icon-only`
+|Shows only the icon. See <<icons>>.
+|Aura, Lumo
+
+|`number-only`
+|Shows only the number. See <<numbers>>.
+|Aura, Lumo
+
+|`dot`
+|Shows the badge as a small dot and hides all its content.
+|Aura, Lumo
+|===
+
+[[attributes]]
+== Attributes
+
+xref:vc/common-attributes.adoc[Common attributes] serve the same purpose for all components.
+The following attributes are specific to `badge`:
+
+[cols="2,5,1", options="header"]
+|===
+|Name
+|Description
+|Default
+
+|[[ariaRole]]`ariaRole`
+|Sets the ARIA role of the badge, which screen readers use. For example, `status` makes screen readers announce changes of the badge content. See <<numbers>>.
+|—
+
+|[[icon]]`icon`
+|Sets the icon displayed before the text. See <<icons>>.
+|—
+
+|[[number]]`number`
+|Sets the number displayed in the badge. See <<numbers>>.
+|—
+
+|[[themeNames]]`themeNames`
+|Applies one or more variants listed in <<theme-variants>>.
+|—
+|===
+
+The following shared attributes are supported by `badge`:
+
+xref:vc/common-attributes.adoc#id[id] -
+xref:vc/common-attributes.adoc#alignSelf[alignSelf] -
+xref:vc/common-attributes.adoc#classNames[classNames] -
+xref:vc/common-attributes.adoc#colspan[colspan] -
+xref:vc/common-attributes.adoc#css[css] -
+xref:vc/common-attributes.adoc#dataContainer[dataContainer] -
+xref:vc/common-attributes.adoc#height[height] -
+xref:vc/common-attributes.adoc#justifySelf[justifySelf] -
+xref:vc/common-attributes.adoc#maxHeight[maxHeight] -
+xref:vc/common-attributes.adoc#maxWidth[maxWidth] -
+xref:vc/common-attributes.adoc#minHeight[minHeight] -
+xref:vc/common-attributes.adoc#minWidth[minWidth] -
+xref:vc/common-attributes.adoc#property[property] -
+xref:vc/common-attributes.adoc#text[text] -
+xref:vc/common-attributes.adoc#visible[visible] -
+xref:vc/common-attributes.adoc#whiteSpace[whiteSpace] -
+xref:vc/common-attributes.adoc#width[width]
+
+[[handlers]]
+== Handlers
+
+The following shared handlers are supported by `badge`:
+
+xref:vc/common-handlers.adoc#AttachEvent[AttachEvent] -
+xref:vc/common-handlers.adoc#DetachEvent[DetachEvent]
+
+[[elements]]
+== Elements
+
+A `badge` can include the `icon` nested element. See <<icons>>.
+
+== See Also
+
+* https://vaadin.com/docs/v25/components/badge[Vaadin Badge documentation^]

content/modules/flow-ui/partials/nav.adoc

@@ -14,6 +14,7 @@
 ** xref:flow-ui:visual-components.adoc[]
 *** xref:flow-ui:vc/components.adoc[]
 **** xref:flow-ui:vc/components/avatar.adoc[]
+**** xref:flow-ui:vc/components/badge.adoc[]
 **** xref:flow-ui:vc/components/bigDecimalField.adoc[]
 **** xref:flow-ui:vc/components/button.adoc[]
 **** xref:flow-ui:vc/components/chart.adoc[]

content/modules/whats-new/pages/release-3.1.adoc

@@ -167,6 +167,11 @@ New components let users select a number or a range of numbers by dragging handl
 * xref:flow-ui:vc/components/integerSlider.adoc[integerSlider] and xref:flow-ui:vc/components/decimalSlider.adoc[decimalSlider] select an `Integer` or a `Double` value. Like other fields, they can be bound to an entity attribute and support validators.
 * xref:flow-ui:vc/components/integerRangeSlider.adoc[integerRangeSlider] and xref:flow-ui:vc/components/decimalRangeSlider.adoc[decimalRangeSlider] select a range of values, for example, to filter data.
 
+[[badge-component]]
+=== Badge Component
+
+The new xref:flow-ui:vc/components/badge.adoc[badge] component displays a small piece of information, such as a status, a count or a label. A badge can show text, an icon and a number, and theme variants set its color and size. You can bind a badge to an entity attribute using the `dataContainer` and `property` attributes to show the attribute value.
+
 [[lookup-field]]
 === Lookup Field Annotation