docs: improve table badge API / docstrings #974

py/examples/table.py

@@ -45,9 +45,9 @@ def __init__(self, text: str, status: str, progress: float, icon: str, state: st
     ui.table_column(name='views', label='Views', sortable=True, data_type='number'),
     ui.table_column(name='progress', label='Progress', cell_type=ui.progress_table_cell_type()),
     ui.table_column(name='badge', label='State', cell_type=ui.badge_table_cell_type(name='badges', badges=[
-        ui.badge(name='RUNNING', background_color='#D2E3F8'),
-        ui.badge(name='DONE', background_color='$red'),
-        ui.badge(name='SUCCESS', background_color='$mint'),
+        ui.badge(label='RUNNING', color='#D2E3F8'),
+        ui.badge(label='DONE', color='$red'),
+        ui.badge(label='SUCCESS', color='$mint'),
     ])),
     ui.table_column(name='created', label='Created', sortable=True, data_type='time'),
 ]

py/examples/table_badge.py

@@ -24,9 +24,9 @@ def __init__(self, text: str, badge: str):
 columns = [
     ui.table_column(name='text', label='Issue', min_width='400px'),
     ui.table_column(name='badge', label='Badge', cell_type=ui.badge_table_cell_type(name='badges', badges=[
-        ui.badge(name='FAIL', background_color='$red'),
-        ui.badge(name='DONE', background_color='#D2E3F8', color='#053975'),
-        ui.badge(name='SUCCESS', background_color='$mint'),
+        ui.badge(label='FAIL', color='$red'),
+        ui.badge(label='DONE', color='#D2E3F8', label_color='#053975'),
+        ui.badge(label='SUCCESS', color='$mint'),
     ])),
 ]
 

py/h2o_wave/types.py

@@ -3002,55 +3002,60 @@ class Badge:
     """
     def __init__(
             self,
-            name: str,
-            background_color: str,
-            color: Optional[str] = None,
+            label: str,
+            color: str,
+            label_color: Optional[str] = None,
     ):
-        _guard_scalar('Badge.name', name, (str,), False, False, False)
-        _guard_scalar('Badge.background_color', background_color, (str,), False, False, False)
-        _guard_scalar('Badge.color', color, (str,), False, True, False)
-        self.name = name
-        """Text specified within the badge."""
-        self.background_color = background_color
-        """Badge's background color."""
+        _guard_scalar('Badge.label', label, (str,), False, False, False)
+        _guard_scalar('Badge.color', color, (str,), False, False, False)
+        _guard_scalar('Badge.label_color', label_color, (str,), False, True, False)
+        self.label = label
+        """The text displayed within the badge."""
         self.color = color
-        """Badge's text color. If not specified, black or white will be picked based on correct contrast with background."""
+        """Badge's background color."""
+        self.label_color = label_color
+        """Badge's label color. If not specified, black or white will be picked based on correct contrast with background."""
 
     def dump(self) -> Dict:
         """Returns the contents of this object as a dict."""
-        _guard_scalar('Badge.name', self.name, (str,), False, False, False)
-        _guard_scalar('Badge.background_color', self.background_color, (str,), False, False, False)
-        _guard_scalar('Badge.color', self.color, (str,), False, True, False)
+        _guard_scalar('Badge.label', self.label, (str,), False, False, False)
+        _guard_scalar('Badge.color', self.color, (str,), False, False, False)
+        _guard_scalar('Badge.label_color', self.label_color, (str,), False, True, False)
         return _dump(
-            name=self.name,
-            background_color=self.background_color,
+            label=self.label,
             color=self.color,
+            label_color=self.label_color,
         )
 
     @staticmethod
     def load(__d: Dict) -> 'Badge':
         """Creates an instance of this class using the contents of a dict."""
-        __d_name: Any = __d.get('name')
-        _guard_scalar('Badge.name', __d_name, (str,), False, False, False)
-        __d_background_color: Any = __d.get('background_color')
-        _guard_scalar('Badge.background_color', __d_background_color, (str,), False, False, False)
+        __d_label: Any = __d.get('label')
+        _guard_scalar('Badge.label', __d_label, (str,), False, False, False)
         __d_color: Any = __d.get('color')
-        _guard_scalar('Badge.color', __d_color, (str,), False, True, False)
-        name: str = __d_name
-        background_color: str = __d_background_color
-        color: Optional[str] = __d_color
+        _guard_scalar('Badge.color', __d_color, (str,), False, False, False)
+        __d_label_color: Any = __d.get('label_color')
+        _guard_scalar('Badge.label_color', __d_label_color, (str,), False, True, False)
+        label: str = __d_label
+        color: str = __d_color
+        label_color: Optional[str] = __d_label_color
         return Badge(
-            name,
-            background_color,
+            label,
             color,
+            label_color,
         )
 
 
 class BadgeTableCellType:
-    """Creates a collection of chips, usually used for rendering state values.
-    Note: In case of multiple tags per row, make sure the row values are
+    """Creates a collection of badges, usually used for rendering state values.
+    In case of multiple badges per row, make sure the row values are
     separated by "," within a single cell string.
-    E.g. ui.table_row(name='...', cells=['cell1', 'BADGE1,BADGE2']).
+    E.g. ui.table_row(name="...", cells=["cell1", "BADGE1,BADGE2"]).
+    Each value should correspond to a `ui.badge.label` attr.
+    For the example above: [
+    ui.badge(label="BADGE1", color="red"),
+    ui.badge(label="BADGE2", color="green"),
+    ]
     """
     def __init__(
             self,

py/h2o_wave/ui.py

@@ -1173,34 +1173,39 @@ def icon_table_cell_type(
 
 
 def badge(
-        name: str,
-        background_color: str,
-        color: Optional[str] = None,
+        label: str,
+        color: str,
+        label_color: Optional[str] = None,
 ) -> Badge:
     """Create a badge.
 
     Args:
-        name: Text specified within the badge.
-        background_color: Badge's background color.
-        color: Badge's text color. If not specified, black or white will be picked based on correct contrast with background.
+        label: The text displayed within the badge.
+        color: Badge's background color.
+        label_color: Badge's label color. If not specified, black or white will be picked based on correct contrast with background.
     Returns:
         A `h2o_wave.types.Badge` instance.
     """
     return Badge(
-        name,
-        background_color,
+        label,
         color,
+        label_color,
     )
 
 
 def badge_table_cell_type(
         name: str,
         badges: Optional[List[Badge]] = None,
 ) -> TableCellType:
-    """Creates a collection of chips, usually used for rendering state values.
-    Note: In case of multiple tags per row, make sure the row values are
+    """Creates a collection of badges, usually used for rendering state values.
+    In case of multiple badges per row, make sure the row values are
     separated by "," within a single cell string.
-    E.g. ui.table_row(name='...', cells=['cell1', 'BADGE1,BADGE2']).
+    E.g. ui.table_row(name="...", cells=["cell1", "BADGE1,BADGE2"]).
+    Each value should correspond to a `ui.badge.label` attr.
+    For the example above: [
+    ui.badge(label="BADGE1", color="red"),
+    ui.badge(label="BADGE2", color="green"),
+    ]
 
     Args:
         name: An identifying name for this component.

r/R/ui.R

@@ -1373,30 +1373,35 @@ ui_icon_table_cell_type <- function(
 
 #' Create a badge.
 #'
-#' @param name Text specified within the badge.
-#' @param background_color Badge's background color.
-#' @param color Badge's text color. If not specified, black or white will be picked based on correct contrast with background.
+#' @param label The text displayed within the badge.
+#' @param color Badge's background color.
+#' @param label_color Badge's label color. If not specified, black or white will be picked based on correct contrast with background.
 #' @return A Badge instance.
 #' @export
 ui_badge <- function(
-  name,
-  background_color,
-  color = NULL) {
-  .guard_scalar("name", "character", name)
-  .guard_scalar("background_color", "character", background_color)
+  label,
+  color,
+  label_color = NULL) {
+  .guard_scalar("label", "character", label)
   .guard_scalar("color", "character", color)
+  .guard_scalar("label_color", "character", label_color)
   .o <- list(
-    name=name,
-    background_color=background_color,
-    color=color)
+    label=label,
+    color=color,
+    label_color=label_color)
   class(.o) <- append(class(.o), c(.wave_obj, "WaveBadge"))
   return(.o)
 }
 
-#' Creates a collection of chips, usually used for rendering state values.
-#' Note: In case of multiple tags per row, make sure the row values are
+#' Creates a collection of badges, usually used for rendering state values.
+#' In case of multiple badges per row, make sure the row values are
 #' separated by "," within a single cell string.
-#' E.g. ui.table_row(name='...', cells=['cell1', 'BADGE1,BADGE2']).
+#' E.g. ui.table_row(name="...", cells=["cell1", "BADGE1,BADGE2"]).
+#' Each value should correspond to a `ui.badge.label` attr.
+#' For the example above: [
+#' ui.badge(label="BADGE1", color="red"),
+#' ui.badge(label="BADGE2", color="green"),
+#' ]
 #'
 #' @param name An identifying name for this component.
 #' @param badges Badges to be rendered.

ui/src/badge_table_cell_type.test.tsx

@@ -20,8 +20,8 @@ const
   name = 'badge-cell',
   badgeCellProps: BadgeTableCellType = {
     name, badges: [
-      { name: 'DONE', background_color: '$red' },
-      { name: 'SUCCESS', background_color: '$green' },
+      { label: 'DONE', color: '$red' },
+      { label: 'SUCCESS', color: '$green' },
     ]
   }
 

ui/src/badge_table_cell_type.tsx

@@ -19,10 +19,15 @@ import { clas, cssVar, getContrast, padding } from './theme'
 
 
 /** 
- * Creates a collection of chips, usually used for rendering state values.
- * Note: In case of multiple tags per row, make sure the row values are
+ * Creates a collection of badges, usually used for rendering state values.
+ * In case of multiple badges per row, make sure the row values are
  * separated by "," within a single cell string.
- * E.g. ui.table_row(name='...', cells=['cell1', 'BADGE1,BADGE2']).
+ * E.g. ui.table_row(name="...", cells=["cell1", "BADGE1,BADGE2"]).
+ * Each value should correspond to a `ui.badge.label` attr.
+ * For the example above: [
+ *  ui.badge(label="BADGE1", color="red"),
+ *  ui.badge(label="BADGE2", color="green"),
+ * ]
  */
 export interface BadgeTableCellType {
   /** An identifying name for this component. */
@@ -35,12 +40,12 @@ export interface BadgeTableCellType {
  * Create a badge.
  */
 export interface Badge {
-  /** Text specified within the badge. */
-  name: S
+  /** The text displayed within the badge. */
+  label: S
   /** Badge's background color. */
-  background_color: S
-  /** Badge's text color. If not specified, black or white will be picked based on correct contrast with background. */
-  color?: S
+  color: S
+  /** Badge's label color. If not specified, black or white will be picked based on correct contrast with background. */
+  label_color?: S
 }
 const css = stylesheet({
   badge: {
@@ -56,10 +61,10 @@ export const XBadgeTableCellType = ({ model, serializedBadges }: { model: BadgeT
   const
     mapBadges = ((v: S, i: U) => {
       const
-        badge = model.badges?.find(({ name: label }) => label === v),
-        badgeColor = badge?.background_color || '$text',
+        badge = model.badges?.find(({ label: label }) => label === v),
+        badgeColor = badge?.color || '$text',
         background = cssVar(badgeColor),
-        color = cssVar(badge?.color || getContrast(badgeColor))
+        color = cssVar(badge?.label_color || getContrast(badgeColor))
 
       return <span key={i} style={{ background, color }} className={clas(css.badge, 'wave-s12 wave-w6')}>{v}</span>
     })