@reliability-design/web 1.4.6 → 1.4.8

package/dist/components/rel-badge/README.md

@@ -1,93 +1,97 @@
-# rel-badge
-
-## Overview
-A simple notification badge component displaying numeric counts or dot indicators. Supports three sizes (sm, md, lg) and two variants (number, dot). Ideal for indicating counts, status, or notifications in UI elements.
-
-## Usage
-```html
-<!-- Number badges -->
-<rel-badge number="5"></rel-badge>
-<rel-badge number="12" size="md"></rel-badge>
-<rel-badge number="99+" size="lg"></rel-badge>
-
-<!-- Dot badges (no number shown) -->
-<rel-badge variant="dot" size="sm"></rel-badge>
-<rel-badge variant="dot" size="md"></rel-badge>
-<rel-badge variant="dot" size="lg"></rel-badge>
-
-<!-- Common use case: Badge on icon/button -->
-<div style="position: relative; display: inline-block;">
-  <button>🔔 Notifications</button>
-  <rel-badge number="3" size="sm" style="position: absolute; top: -8px; right: -8px;"></rel-badge>
-</div>
-
-<!-- Sizes comparison -->
-<rel-badge number="1" size="sm"></rel-badge>
-<rel-badge number="2" size="md"></rel-badge>
-<rel-badge number="3" size="lg"></rel-badge>
-
-<!-- Custom colors -->
-<rel-badge number="3" color="#7d7d7d"></rel-badge>
-<rel-badge number="3" color="teal" text-color="#1a1a1a"></rel-badge>
-<rel-badge variant="dot" color="lavender"></rel-badge>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `number` | `string` | `""` | Text to display in number variant (can be numeric or text like "99+") |
-| `size` | `"sm" \| "md" \| "lg"` (reflected) | `"md"` | Size variant |
-| `variant` | `"dot" \| "number"` (reflected) | `"number"` | Display mode (number shows text, dot shows indicator only) |
-| `color` | `string` (reflected) | `""` | Direct CSS color override for the badge background. Accepts any valid CSS color (hex, rgb, hsl, named, `var(...)`). Falls back to the default token when empty |
-| `text-color` | `string` (reflected) | `""` | Direct CSS color override for the badge text/icon color. Accepts any valid CSS color. Falls back to white when empty |
-
-## Events
-None.
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-fonts-weight-body-semibold` - Font weight (number variant)
-- `--rel-body-xs-regular-font-size`, `--rel-body-sm-regular-font-size`, `--rel-body-xl-regular-font-size` - Font sizes for number variant sizes
-
-### Color Tokens
-- `--rel-bg-danger` - Background color
-- `--rel-bg-surface` - Text color
-
-## Accessibility
-- Purely visual indicator (no ARIA roles)
-- For critical information, ensure accompanying text or ARIA labels on parent elements
-- Screen readers will not announce badge content unless used with proper labeling
-
-### Keyboard Interactions
-- None (not focusable)
-
-### Focus Behavior
-- Not focusable
-
-## Notes / Edge Cases
-- **Number variant sizes**:
-  - **sm**: 20px × 20px, 12px font
-  - **md**: 28px × 28px, 14px font
-  - **lg**: 40px × 40px, 20px font
-- **Dot variant sizes**:
-  - **sm**: 8px × 8px
-  - **md**: 10px × 10px
-  - **lg**: 12px × 12px
-- All badges are circular (`border-radius: 50%`)
-- The `number` property accepts any string (e.g., "99+", "NEW", or numeric values)
-- In dot variant, the `number` property is ignored and nothing is rendered inside
-- The component is `display: inline-flex` for easy positioning
-- Badges use `justify-content: center` and `align-items: center` for centering content
-- `size` and `variant` are reflected attributes (appear in HTML when set)
-- Common pattern: position badges absolutely over parent elements (e.g., icons, avatar images)
-- For very large numbers, consider truncating or using "99+" format to avoid overflow
+# rel-badge
+
+`<rel-badge>` is the Figma "Badge" count indicator: a small `number` pill ("5", "99+") or an unlabeled `dot`, in four sizes (S/M/L/XL), filled with the danger token by default and overridable per instance through `color` / `text-color`. Use it to flag unread counts or unseen activity on an icon, tab, avatar or navigation item — you position it over the target yourself. It is not a text tag (use `rel-chip`) and not a status message (use `rel-alert` or `rel-toast`); it only carries a count or a "something is new" signal.
+
+## Usage
+
+```html
+<!-- Number badges -->
+<rel-badge number="5"></rel-badge>
+<rel-badge number="12" size="md"></rel-badge>
+<rel-badge number="99+" size="lg"></rel-badge>
+<rel-badge number="120" size="xl"></rel-badge>
+
+<!-- Dot badges (no text) -->
+<rel-badge variant="dot"></rel-badge>
+
+<!-- Positioned over an icon button -->
+<div style="position: relative; display: inline-block;">
+  <button aria-label="Notifications">🔔</button>
+  <rel-badge number="3" size="sm" style="position: absolute; top: -8px; right: -8px;"></rel-badge>
+</div>
+
+<!-- Accessible-name control -->
+<rel-badge number="3" suffix="unread messages"></rel-badge>
+<rel-badge variant="dot" arialabel="New activity"></rel-badge>
+
+<!-- Colour overrides: any CSS colour, including a token via var() -->
+<rel-badge number="3" color="#7d7d7d"></rel-badge>
+<rel-badge number="3" color="teal" text-color="#1a1a1a"></rel-badge>
+<rel-badge variant="dot" color="seagreen"></rel-badge>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-badge.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `number` | `number` | `string` | `""` | Text shown in the `number` variant (a count such as "5" or "99+"); not rendered by `variant="dot"` but still used to build the accessible name. |
+| `ariaLabel` | `arialabel` | `string` | `""` | Explicit accessible name; when empty it is composed as "<number> <suffix>" or, with no number, "New <suffix>". Attribute is `arialabel`. |
+| `suffix` | `suffix` | `string` | `"notifications"` | Noun appended to the count in the generated accessible name, e.g. "3 notifications". |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "extra-large" \| "sm" \| "md" \| "lg" \| "xl"` | `"medium"` | Badge scale (Figma Badge S/M/L/XL): number badges are 20 / 24 / 28 / 40px tall. `sm` / `md` / `lg` / `xl` are accepted and normalised to the full words. Ignored when `variant="dot"` — Figma models `Dot` as a fifth option of the same Size axis, so a dot has one size. Reflected. |
+| `variant` | `variant` | `"dot" \| "number"` | `"number"` | `number` renders the `number` text in a pill that widens with its content; `dot` renders a 6px disc with no text (Figma `Size=Dot`), ignoring `size`. Reflected. |
+| `color` | `color` | `string` | `""` | Direct CSS color override for the badge background. Accepts any valid CSS color value: hex, rgb(...), hsl(...), named color, or var(--token). Clear it (set to `''`) to fall back to the default token. Reflected. |
+| `textColor` | `text-color` | `string` | `""` | Direct CSS color override for the badge text/icon color. Accepts any valid CSS color value: hex, rgb(...), hsl(...), named color, or var(--token). Clear it (set to `''`) to fall back to the default (white). Reflected. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The `role="status"` pill / dot that carries the size, variant and colour overrides |
+
+## Tokens / CSS Variables
+
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-badge-bg` | `var(--rel-bg-danger)` | Background colour of the badge; the `color` prop writes this on the host |
+| `--rel-badge-color` | `var(--rel-text-static-light)` | Text colour of the count; the `text-color` prop writes this on the host |
+| `--rel-badge-dot-size` | `6px` | Diameter of the `dot` variant; default 6px, the single dot size Figma draws. Set it to restore the larger discs shipped previously. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The pill (`base` part) renders with `role="status"` and an `aria-label`. The label is `ariaLabel` when set; otherwise it is composed as `"<number> <suffix>"` (e.g. "3 notifications") or, when `number` is empty (dot badges), `"New <suffix>"` (e.g. "New notifications"). Set `suffix` so the announcement names the right thing, or `arialabel` for full control.
+- `role="status"` is an implicit polite live region, so a change to `number` may be announced without the badge ever taking focus; verify the behaviour with your target screen reader before relying on it.
+- The host is not focusable and handles no keys. Interactive meaning ("open notifications") belongs to the element the badge decorates — give that element its own accessible name.
+- A dot badge has no visible text; the generated name is the only thing a screen reader gets, and sighted users get colour alone. Pair it with nearby text when the meaning is not obvious from context.
+
+## Notes / Edge Cases
+
+- Number badge heights are 20 / 24 / 28 / 40px for `sm` / `md` / `lg` / `xl`; dot badges are 8 / 10 / 12 / 12px (`lg` and `xl` dots are the same size). The number badge sets `min-width`, not `width`, so a two-digit count stays a circle while "999+" grows into a pill.
+- The corner radius is a fixed `999px`, not `50%`, which is what lets wide content become a pill instead of clipping.
+- In `variant="dot"` the `number` text is not rendered but still feeds the accessible name ("3 notifications" for a dot with `number="3"`).
+- `color` and `text-color` are applied by writing `--rel-badge-bg` / `--rel-badge-color` as inline custom properties on the host; clearing the prop removes the inline value and falls back to whatever the hook resolves to (the danger / static-light tokens unless you set the hook in your own CSS).
+- The accessible-name property is `ariaLabel` with the attribute `arialabel` (no hyphen). A plain `aria-label` attribute on the host is not read by the component, and because the host has no role it does not reach the `role="status"` element either — use `arialabel`.
+- The host is `display: inline-flex`; the usual pattern is an absolutely positioned badge inside a `position: relative` wrapper around the decorated element.

package/dist/components/rel-breadcrumb/README.md

@@ -1,102 +1,96 @@
-#rel-breadcrumbs
-
-## Overview
-A breadcrumb navigation component that displays a hierarchical path of pages. Features accessible markup, automatic last-item detection, built-in chevron separators, and proper ARIA attributes. Automatically styles the last item as the current page.
-
-## Usage
-```html
-<!-- Basic breadcrumb -->
-<rel-breadcrumbs id="breadcrumb1"></rel-breadcrumbs>
-<script>
-  const breadcrumb = document.getElementById('breadcrumb1');
-  breadcrumb.items = [
-    { label: 'Home', url: '/' },
-    { label: 'Products', url: '/products' },
-    { label: 'Electronics', url: '/products/electronics' },
-    { label: 'Laptops' } // Last item has no URL
-  ];
-</script>
-
-<!-- Simple path -->
-<rel-breadcrumbs id="breadcrumb2"></rel-breadcrumbs>
-<script>
-  document.getElementById('breadcrumb2').items = [
-    { label: 'Dashboard', url: '/dashboard' },
-    { label: 'Settings' }
-  ];
-</script>
-
-<!-- Deep nested path -->
-<rel-breadcrumbs id="breadcrumb3"></rel-breadcrumbs>
-<script>
-  document.getElementById('breadcrumb3').items = [
-    { label: 'Docs', url: '/docs' },
-    { label: 'Components', url: '/docs/components' },
-    { label: 'Navigation', url: '/docs/components/navigation' },
-    { label: 'Breadcrumbs' }
-  ];
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `items` | `BreadcrumbItem[]` | `[]` | Array of breadcrumb items (see BreadcrumbItem interface below) |
-
-### BreadcrumbItem Interface
-```typescript
-interface BreadcrumbItem {
-  label: string;   // Display text
-  url?: string;    // Optional link URL (omit for current/last page)
-}
-```
-
-## Events
-None.
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-md-regular-font-size` - Font size
-- `--rel-fonts-weight-body-medium` - Font weight for links
-- `--rel-fonts-weight-body-semibold` - Font weight for current page
-
-### Color Tokens
-- `--rel-text-default` - Base text color
-- `--rel-text-label` - Link and current page text color
-- `--rel-bg-info` - Link hover color and focus outline
-
-## Accessibility
-- Uses semantic `<nav>` with `aria-label="Breadcrumb"`
-- Uses `<ol>` ordered list for proper structure
-- Last item has `aria-current="page"` to indicate current page
-- Links have focus visible states with blue outline
-- Chevron separator has `aria-hidden="true"` to hide from screen readers
-
-### Keyboard Interactions
-- `Tab` - Navigate through breadcrumb links
-- `Enter` - Follow focused link
-
-### Focus Behavior
-- Links show 2px blue outline with 2px offset when focused
-- Border radius applied to focus outline for visual consistency
-
-## Notes / Edge Cases
-- The last item in `items` array is automatically treated as the current page
-- Last item renders as a `<span class="current">` instead of `<a>`, even if it has a `url`
-- Chevron separators (SVG chevron-right arrows) appear between all items except after the last one
-- Chevrons are 16px × 16px with 10px horizontal margins
-- Chevron color inherits `currentColor` from parent
-- Links have `text-decoration: none` by default, `underline` on hover
-- The current page label is bold and not clickable (`cursor: default`)
-- The component is `display: block` and takes full width
-- The ordered list uses `flex-wrap: wrap` to handle overflow gracefully
+# rel-breadcrumbs
+
+Breadcrumb trail (element `<rel-breadcrumbs>`, folder `rel-breadcrumb`): a `<nav aria-label="Breadcrumb">` ordered list built from an `items` array, with chevron separators and the last entry rendered as the non-link current page. Use it to show where the current page sits in a hierarchy and to jump back up it; do not use it as primary navigation or for a single-level site.
+
+## Usage
+
+```html
+<!-- Basic trail: every item but the last is a link -->
+<rel-breadcrumbs id="trail"></rel-breadcrumbs>
+<script>
+  document.getElementById('trail').items = [
+    { label: 'Home', url: '/' },
+    { label: 'Products', url: '/products' },
+    { label: 'Electronics', url: '/products/electronics' },
+    { label: 'Laptops' } // current page — no url needed
+  ];
+</script>
+
+<!-- Two levels -->
+<rel-breadcrumbs id="short"></rel-breadcrumbs>
+<script>
+  document.getElementById('short').items = [
+    { label: 'Dashboard', url: '/dashboard' },
+    { label: 'Settings' }
+  ];
+</script>
+
+<!-- Restyle the current-page text through its part -->
+<style>
+  .muted::part(label) {
+    color: gray;
+  }
+</style>
+<rel-breadcrumbs class="muted" id="muted"></rel-breadcrumbs>
+<script>
+  document.getElementById('muted').items = [
+    { label: 'Docs', url: '/docs' },
+    { label: 'Components', url: '/docs/components' },
+    { label: 'Breadcrumbs' }
+  ];
+</script>
+```
+
+The `BreadcrumbItem` shape is `{ label: string; url?: string }`; the type is exported from the package.
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-breadcrumb.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `items` | `BreadcrumbItem[]` | `[]` | Ordered trail, root first: `{ label: string; url?: string }[]`. Items with a `url` render as links except the last one, which is always the current page (and never a link). Set as a property — arrays do not survive attribute serialisation. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The `<nav>` landmark wrapping the ordered list. |
+| `label` | The non-link current-page text (`aria-current="page"`), also used for any item without a `url`. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- Semantic `<nav aria-label="Breadcrumb">` landmark (the `base` part) containing an `<ol>`, so the trail is announced as an ordered list within a named navigation region.
+- The last item is a `<span aria-current="page">` (the `label` part), never a link, so the current page is identified without being actionable.
+- Chevron separators are inline SVGs with `aria-hidden="true"`.
+- Links show a 2px focus outline with 2px offset on `:focus-visible`.
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move between the breadcrumb links |
+| `Enter` | Follow the focused link (native anchor behaviour) |
+
+## Notes / Edge Cases
+
+- **The last item is always the current page**, even if it has a `url` — it renders as text, not a link. Any earlier item *without* a `url` also renders as text (and reuses the `label` part and `aria-current="page"`, so give every ancestor a `url`).
+- `items` must be assigned as a property (it is an array); setting an `items` attribute in HTML does not work.
+- Separators are 16px chevrons with 10px horizontal margins inheriting `currentColor`; the list wraps onto new lines when it runs out of width.
+- Links are plain anchors: navigation happens natively and no custom event is emitted. Intercept `click` on the host if you route client-side.