ionbase-ui 0.26.0 → 0.28.0

package/dist/meta/components.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "generated": "by scripts/build-meta.mjs — do not edit; intent lives in meta/*.json",
   "hooks": [
     "useToast"
@@ -897,7 +897,7 @@
       "name": "Avatar",
       "source": "src/components/Avatar.tsx",
       "propsType": "AvatarProps",
-      "description": "Avatar picks its content the way Figma's `Type` variant does, but by\nprecedence rather than by a prop: image, then initials, then icon. A caller\npassing `src` and `initials` gets the image with the initials as its alt\nfallback, which is what you want when the image 404s.\n\nA failed `src` falls through to initials (then icon) rather than leaving the\nbrowser's broken-image glyph — that is why initials exist alongside `src`.\n\nIt is a `<span>`, not a `<div>`, so it can sit inline beside text without the\ncaller fighting a block element.",
+      "description": "Avatar picks its content the way Figma's `Type` variant does, but by\nprecedence rather than by a prop: image, then initials, then icon. A caller\npassing `src` and `initials` gets the image with the initials as its alt\nfallback, which is what you want when the image 404s.\n\nA failed `src` falls through to initials (then icon) rather than leaving the\nbrowser's broken-image glyph — that is why initials exist alongside `src`.\n\nIt is a `<span>`, not a `<div>`, so it can sit inline beside text without the\ncaller fighting a block element.\n\nTHE MEDIA IS A CHILD, AND IT HAS TO BE\n\nThe box that clips the image is `.ion-avatar__media`, not the root. The root\ncannot clip: a corner indicator sits outside a circle's clip path and would\nbe sliced in half by the `overflow: hidden` that crops the photo. Figma\ndraws exactly this — an unclipped frame holding a clipped `Media` child and\nthe indicators as its siblings.",
       "import": "import { Avatar } from 'ionbase-ui';",
       "status": "stable",
       "summary": "A person or entity marker. Content is chosen by precedence — image, then initials, then icon — not by a type prop.",
@@ -937,21 +937,67 @@
           "square": {
             "use": "organisations, projects, workspaces and other non-human entities"
           }
+        },
+        "topIndicator": {
+          "neutral": {
+            "use": "no state, or a state this system has no colour for"
+          },
+          "primary": {
+            "use": "attention rather than health — a request, an invite, a mention"
+          },
+          "success": {
+            "use": "online, available, verified, complete"
+          },
+          "warning": {
+            "use": "away, idle, needs attention but is not broken"
+          },
+          "error": {
+            "use": "offline, blocked, failed"
+          },
+          "information": {
+            "use": "a neutral fact about the person — a role or a badge, not a state"
+          }
+        },
+        "bottomIndicator": {
+          "neutral": {
+            "use": "no state, or a state this system has no colour for"
+          },
+          "primary": {
+            "use": "attention rather than health — a request, an invite, a mention"
+          },
+          "success": {
+            "use": "online, available, verified, complete"
+          },
+          "warning": {
+            "use": "away, idle, needs attention but is not broken"
+          },
+          "error": {
+            "use": "offline, blocked, failed"
+          },
+          "information": {
+            "use": "a neutral fact about the person — a role or a badge, not a state"
+          }
         }
       },
       "slots": {
         "icon": {
           "accepts": "Icon",
           "note": "the last fallback — rendered only when there is neither `src` nor `initials`"
+        },
+        "topIndicatorIcon": {
+          "accepts": "Icon",
+          "note": "replaces the top indicator's default check glyph. The bottom indicator takes no glyph — Figma draws it bare, and at Mini it is 8px, which nothing legible fits inside."
         }
       },
       "a11y": {
         "guarantees": [
           "`alt` falls back to `initials`, so the avatar is never announced as an unlabelled image",
-          "a `src` that fails to load falls through to initials, then icon — never the browser's broken-image glyph"
+          "a `src` that fails to load falls through to initials, then icon — never the browser's broken-image glyph",
+          "indicator labels are announced wherever they land: folded into the avatar's own `aria-label` when there is no image (the root is `role=\"img\"` and therefore a leaf), and carried as hidden text inside each indicator when there is"
         ],
         "requires": [
-          "`alt` describing the person, not the picture — \"Ada Lovelace\", not \"profile photo\""
+          "`alt` describing the person, not the picture — \"Ada Lovelace\", not \"profile photo\"",
+          "`topIndicatorLabel` / `bottomIndicatorLabel` on any indicator that carries meaning. An indicator with no label is decorative, which is the right answer only when the same fact is already stated in text beside it."
         ]
       },
       "antiPatterns": [
@@ -963,43 +1009,75 @@
           "dont": "using Avatar as a button",
           "do": "put the Avatar inside a Button or Link",
           "why": "Avatar renders a <span> with no role and takes no focus"
+        },
+        {
+          "dont": "using an indicator's colour as the only carrier of a status",
+          "do": "pass `topIndicatorLabel` / `bottomIndicatorLabel`, or state the status in text nearby",
+          "why": "WCAG 1.4.1. A green dot and a red dot are the same dot to a screen reader, and to a good share of sighted users too"
+        },
+        {
+          "dont": "reaching for `ring` to mean selected or focused",
+          "why": "it is a static brand ring from the design, not a focus indicator. Focus belongs on whatever interactive element wraps the avatar, and that element draws its own"
         }
       ],
       "stylesheet": "src/styles/avatar.css",
       "tokens": [
         "--border-strong",
+        "--border-subtle",
         "--border-width-default",
+        "--border-width-thick",
         "--font-family-sans",
         "--font-weight-medium",
+        "--font-weight-regular",
         "--icon-size-2xs",
         "--icon-size-lg",
         "--icon-size-md",
         "--icon-size-sm",
         "--icon-tertiary",
+        "--ion-avatar-border",
         "--ion-avatar-font-size",
+        "--ion-avatar-font-weight",
         "--ion-avatar-group-overlap",
         "--ion-avatar-icon",
+        "--ion-avatar-indicator-icon",
+        "--ion-avatar-indicator-ring",
+        "--ion-avatar-indicator-size",
         "--ion-avatar-line-height",
         "--ion-avatar-radius",
+        "--ion-avatar-ring-width",
         "--ion-avatar-size",
+        "--ion-avatar-surface",
         "--radius-full",
         "--radius-md",
         "--radius-sm",
         "--radius-xs",
+        "--ring-offset",
+        "--spacing-12",
+        "--spacing-14",
+        "--spacing-16",
         "--spacing-24",
         "--spacing-32",
         "--spacing-40",
         "--spacing-48",
+        "--spacing-8",
+        "--surface-error",
+        "--surface-information",
+        "--surface-inverse",
         "--surface-muted",
+        "--surface-placeholder",
+        "--surface-primary",
+        "--surface-success",
+        "--surface-warning",
+        "--text-on-color",
         "--text-tertiary",
         "--type-body",
+        "--type-body-lg",
+        "--type-body-lg-line-height",
         "--type-body-line-height",
         "--type-body-sm",
         "--type-body-sm-line-height",
         "--type-caption",
-        "--type-caption-line-height",
-        "--type-h5",
-        "--type-h5-line-height"
+        "--type-caption-line-height"
       ],
       "props": {
         "size": {
@@ -1047,15 +1125,269 @@
           "required": false,
           "origin": "own",
           "description": "Figma's `Type=Icon`. Rendered when there is neither `src` nor `initials`."
+        },
+        "ring": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Figma's `Show Ring` — a 1px/2px brand ring drawn inside the avatar's edge."
+        },
+        "topIndicator": {
+          "type": "AvatarIndicatorIntent | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Figma's `Show Top Indicator`, as the intent of the `Status Indicator`\ninstance it holds. Top-right, and it carries a glyph: this is the corner\nthat says something was verified or requested, not who is online.",
+          "values": [
+            "neutral",
+            "primary",
+            "success",
+            "warning",
+            "error",
+            "information"
+          ]
+        },
+        "topIndicatorIcon": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Replaces the top indicator's default check glyph."
+        },
+        "topIndicatorLabel": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Names the top indicator for assistive tech. Without it the mark is decorative."
+        },
+        "bottomIndicator": {
+          "type": "AvatarIndicatorIntent | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Figma's `Show Bottom Indicator`. Bottom-right and glyphless — the presence\ndot.",
+          "values": [
+            "neutral",
+            "primary",
+            "success",
+            "warning",
+            "error",
+            "information"
+          ]
+        },
+        "bottomIndicatorLabel": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Names the bottom indicator for assistive tech. Colour alone is not a status."
         }
       },
       "propCounts": {
-        "own": 6,
+        "own": 12,
         "aria": 0,
         "dom": 278,
         "other": 0
       }
     },
+    "AvatarGradient": {
+      "name": "AvatarGradient",
+      "source": "src/components/AvatarGradient.tsx",
+      "propsType": "AvatarGradientProps",
+      "description": "AvatarGradient is Avatar's initials-only sibling: a tinted, bevelled disc for\npeople who have no photo.\n\nIT IS A SEPARATE COMPONENT BECAUSE FIGMA DRAWS A SEPARATE COMPONENT, AND THE\nAXES ARE THE ARGUMENT\n\nIt has `Color`, which Avatar does not. It has no `Shape`, because a gradient\nthis directional only reads on a circle. It has no `Type`, because there is\nno image and no icon to fall back to — the initials are the whole content.\nFolding it into Avatar would mean a `color` prop that does nothing on three\nof Avatar's four states and a `shape` prop that this one has to reject.\n\nThere is no `icon` and no `src` fallback here on purpose. If you have a\nphoto, or nothing at all to put in the circle, that is `Avatar`.",
+      "import": "import { AvatarGradient } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "Avatar's initials-only sibling: a tinted, bevelled disc in one of seven colours, for people with no photo.",
+      "useWhen": [
+        "someone has no profile image and the fallback should still look deliberate rather than empty",
+        "a list of people reads better when each one is a different colour — the colour is recognisable long before the letters are legible"
+      ],
+      "useInstead": [
+        {
+          "when": "there is a photo, or there may be one later",
+          "use": "Avatar",
+          "why": "Avatar falls back from image to initials to icon on its own; this component has no image to fall back from"
+        },
+        {
+          "when": "the mark needs a square shape, an icon, a ring or a status indicator",
+          "use": "Avatar",
+          "why": "Figma draws none of those on this component, and a gradient this directional only reads on a circle"
+        },
+        {
+          "when": "the thing being marked is a status, count or category rather than a person",
+          "use": "Badge"
+        }
+      ],
+      "variants": {
+        "size": {
+          "mini": {
+            "use": "24px — inline beside body text, dense table rows"
+          },
+          "sm": {
+            "use": "32px — menu rows, compact lists"
+          },
+          "md": {
+            "use": "the default, 40px"
+          },
+          "lg": {
+            "use": "48px — profile headers and detail pages"
+          }
+        },
+        "color": {
+          "slate": {
+            "use": "the default. The one to reach for when nothing about the person suggests a colour"
+          },
+          "blue": {
+            "use": "one of seven, picked to tell people apart"
+          },
+          "violet": {
+            "use": "one of seven, picked to tell people apart"
+          },
+          "pink": {
+            "use": "one of seven, picked to tell people apart"
+          },
+          "orange": {
+            "use": "one of seven, picked to tell people apart"
+          },
+          "green": {
+            "use": "as the rest. Not a status — a green disc here does not mean online, and Avatar's `bottomIndicator` is what does"
+          },
+          "red": {
+            "use": "as the rest. Not an error — this is identity, not state"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "`alt` falls back to `initials`, so the disc is never announced as an unlabelled image",
+          "all seven colours clear WCAG AA for the initials against the palest end of their own gradient, which is the worst case the text sits on"
+        ],
+        "requires": [
+          "`alt` naming the person — \"Ada Lovelace\", not \"AB\". Two letters are not a name, and that is all a screen reader would otherwise get"
+        ],
+        "notes": [
+          "Colour is decoration here, never information. Nothing about which of the seven a person gets should be recoverable, because a screen reader cannot recover it.",
+          "The first version of this component was a saturated disc with white initials and failed AA on four of its colours. It was fixed in Figma by inverting it — pale disc, coloured initials — rather than in code. Do not reintroduce the saturated version."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "picking the colour from a status — green for online, red for failing",
+          "do": "use Avatar's `bottomIndicator`, or say it in text",
+          "why": "the colour is identity, not state. It is also invisible to assistive tech, so a status expressed only this way is not expressed at all"
+        },
+        {
+          "dont": "hashing a user id to a colour and treating it as stable",
+          "do": "store the chosen colour with the person, the way you would store their avatar",
+          "why": "the palette has eight entries and any hash of it will collide; worse, it silently reassigns everyone the day the palette or the hash changes"
+        },
+        {
+          "dont": "passing more than two letters",
+          "why": "Figma draws two. Three fit at 48 and clip at 24, so it looks correct in the story and wrong in the table"
+        }
+      ],
+      "stylesheet": "src/styles/avatar-gradient.css",
+      "tokens": [
+        "--color-blue-200",
+        "--color-blue-300",
+        "--color-blue-50",
+        "--color-blue-600",
+        "--color-gray-200",
+        "--color-gray-300",
+        "--color-gray-50",
+        "--color-gray-600",
+        "--color-green-200",
+        "--color-green-300",
+        "--color-green-50",
+        "--color-green-600",
+        "--color-orange-200",
+        "--color-orange-300",
+        "--color-orange-50",
+        "--color-orange-600",
+        "--color-pink-200",
+        "--color-pink-300",
+        "--color-pink-50",
+        "--color-pink-600",
+        "--color-purple-200",
+        "--color-purple-300",
+        "--color-purple-50",
+        "--color-purple-600",
+        "--color-red-200",
+        "--color-red-300",
+        "--color-red-50",
+        "--color-red-600",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--font-weight-regular",
+        "--ion-avatar-gradient-bevel",
+        "--ion-avatar-gradient-font-size",
+        "--ion-avatar-gradient-font-weight",
+        "--ion-avatar-gradient-from",
+        "--ion-avatar-gradient-line-height",
+        "--ion-avatar-gradient-mid",
+        "--ion-avatar-gradient-sheen",
+        "--ion-avatar-gradient-sheen-mid",
+        "--ion-avatar-gradient-size",
+        "--ion-avatar-gradient-text",
+        "--ion-avatar-gradient-to",
+        "--radius-full",
+        "--spacing-24",
+        "--spacing-32",
+        "--spacing-40",
+        "--spacing-48",
+        "--type-body",
+        "--type-body-lg",
+        "--type-body-lg-line-height",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "size": {
+          "type": "AvatarSize | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the Figma `Size` variant: Mini 24, Small 32, Medium 40, Large 48.",
+          "values": [
+            "sm",
+            "md",
+            "lg",
+            "mini"
+          ]
+        },
+        "color": {
+          "type": "AvatarGradientColor | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the Figma `Color` variant.",
+          "values": [
+            "slate",
+            "blue",
+            "violet",
+            "pink",
+            "orange",
+            "green",
+            "red"
+          ]
+        },
+        "initials": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The two letters. Figma's `Initials`."
+        },
+        "alt": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Describes the person, not the picture — \"Ada Lovelace\", not \"avatar\".\nWithout it the initials are announced as the letters they are, which is\nnot a name."
+        }
+      },
+      "propCounts": {
+        "own": 4,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
     "AvatarGroup": {
       "name": "AvatarGroup",
       "source": "src/components/Avatar.tsx",
@@ -1122,38 +1454,61 @@
       "stylesheet": "src/styles/avatar.css",
       "tokens": [
         "--border-strong",
+        "--border-subtle",
         "--border-width-default",
+        "--border-width-thick",
         "--font-family-sans",
         "--font-weight-medium",
+        "--font-weight-regular",
         "--icon-size-2xs",
         "--icon-size-lg",
         "--icon-size-md",
         "--icon-size-sm",
         "--icon-tertiary",
+        "--ion-avatar-border",
         "--ion-avatar-font-size",
+        "--ion-avatar-font-weight",
         "--ion-avatar-group-overlap",
         "--ion-avatar-icon",
+        "--ion-avatar-indicator-icon",
+        "--ion-avatar-indicator-ring",
+        "--ion-avatar-indicator-size",
         "--ion-avatar-line-height",
         "--ion-avatar-radius",
+        "--ion-avatar-ring-width",
         "--ion-avatar-size",
+        "--ion-avatar-surface",
         "--radius-full",
         "--radius-md",
         "--radius-sm",
         "--radius-xs",
+        "--ring-offset",
+        "--spacing-12",
+        "--spacing-14",
+        "--spacing-16",
         "--spacing-24",
         "--spacing-32",
         "--spacing-40",
         "--spacing-48",
+        "--spacing-8",
+        "--surface-error",
+        "--surface-information",
+        "--surface-inverse",
         "--surface-muted",
+        "--surface-placeholder",
+        "--surface-primary",
+        "--surface-success",
+        "--surface-warning",
+        "--text-on-color",
         "--text-tertiary",
         "--type-body",
+        "--type-body-lg",
+        "--type-body-lg-line-height",
         "--type-body-line-height",
         "--type-body-sm",
         "--type-body-sm-line-height",
         "--type-caption",
-        "--type-caption-line-height",
-        "--type-h5",
-        "--type-h5-line-height"
+        "--type-caption-line-height"
       ],
       "props": {
         "size": {
@@ -1489,6 +1844,7 @@
         "--ion-button-pressed",
         "--ion-button-raised",
         "--ion-button-ring",
+        "--ion-button-shadow",
         "--ion-button-size",
         "--ion-duration-base",
         "--ion-duration-fast",
@@ -1504,6 +1860,9 @@
         "--ion-shadow-raised-lifted-lg",
         "--ion-shadow-raised-lifted-sm",
         "--ion-shadow-raised-lifted-xs",
+        "--ion-shadow-shadow-md",
+        "--ion-shadow-shadow-sm",
+        "--ion-shadow-shadow-xs",
         "--radius-md",
         "--spacing-12",
         "--spacing-16",