wings-plugin-ui 0.3.0 → 0.5.0

package/README.md

@@ -73,6 +73,7 @@ message.
 | `Board`, `BoardColumn` | `Board`: `label`; `BoardColumn`: `title`, `count`, `actions` | Columns that scroll sideways, each with a header, a count and a scrolling stack of cards (use `Card`). The board is a focusable region, so the arrow keys scroll it |
 | `Split` | `start`, `end`, `direction` (`horizontal`, `vertical`), `defaultSize` (px, 280), `min` (120), `max`, `onResize`, `label` | Two panes with a draggable handle, a `separator` with `aria-valuenow` in px. Arrow keys (Shift for bigger steps), Home and End resize it. A drag only changes a CSS variable and `onResize(size)` runs once when it ends, so save it with `wings.setTabState()` and pass it back as `defaultSize` |
 | `Dot`, `Spinner` | `tone`, `size`, `label`; `Dot` also `color` | A status dot or a spinner, announced only with a `label`. A dot's `color` comes from your data, like a work item type's `#cc293d` |
+| `Avatar` | `name`, `size` (`small`, `large`), `label` | A round avatar with the initials of a name on a colour that depends only on the name. Decoration next to the name; with a `label` it's announced |
 | `Pill`, `Tag` | `tone` | A filled pill, or an outlined tag like a branch |
 | `Loading`, `Empty` | `Empty`: `title`, `description` | Before the first data, and nothing to show |
 | `Button` | `variant` (`primary`, `ghost`, `danger`), `size` (`small`), `busy` | A button, `type="button"`; `busy` shows a spinner and ignores clicks, keeping focus |
@@ -85,7 +86,11 @@ message.
 | `Combobox` | `label`, `value`, `onInput`, `options: { value, label, detail? }[]`, `onPick`, `onEnter`, `onKeyDown`, `freeText`, `openOnFocus`, `open`, `filter`, `empty` | A text field with suggestions under it: arrows, Enter, Escape and Tab, and a press outside closes it. With `freeText` it keeps what you type; otherwise it picks one of `options`. `openOnFocus={false}` for a page that puts focus back into it after a render. Without `freeText` the picked label is selected when the field gets focus and after a pick, so typing replaces it. `onEnter(text)` runs on Enter when no option is highlighted, with the typed text, and stops the Enter from submitting a form around it. An `onKeyDown` you pass runs first; `e.preventDefault()` in it skips the combobox's own keys. ArrowDown on a closed combobox opens it and highlights the first option, as in the [WAI-ARIA APG combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). `open="whileText"` keeps the list shown for as long as the field has text and an option matches, even after Escape, Tab or a press outside (those only clear the highlighted option) and it closes when the text is emptied or an option is picked; `aria-expanded` follows whether the list is shown. Accessibility caveat: the APG pattern has Escape dismiss the popup and treats it as shown only while the user is working in the combobox, so this mode departs from it. Use it only where the suggestions are the page's main content, such as a people search that is useful to keep in view, and not for a field where a stray list would cover other controls |
 | `Menu` | `label`, `items: { id, label, onSelect, tone? }[]`, `align`, `variant`, `size` | A button that opens a menu: arrows, Home, End, Enter, Escape |
 | `Disclosure` | `summary` | More behind a line that opens it |
-| `Markdown` | `source`, `inline` | Markdown as React: headings, lists with read-only task checkboxes, GFM tables, fenced code, quotes, rules, bold, italics, strikethrough, links and bare https URLs, and images. No HTML is ever parsed; only `https:` links open (through `wings.openUrl`, so the manifest needs `permissions.openUrl` with an `https://` prefix) and images load only from `https:` or `data:image/` png, jpeg, gif or webp URLs up to 8,000 characters (`MAX_DATA_IMAGE`); an `https:` image shows as a "Load image from <host>" button and loads only when clicked (no option to turn that off), because the text may come from an agent and the URL could carry data out, and a `data:` image shows at once; `[![alt](img)](url)` is a link with the alt as its text. `inline` renders just the inline parts in a span. Memoized on `source` |
+| `Time`, `ago` | `Time`: `iso`, `prefix`; `ago(iso)` gives the text | A moment as how long ago it was ("5 min ago", "3 h ago", "2 d ago", then the date) in a `time` element with the exact date and time on hover |
+| `Summary`, `SummaryChip` | `SummaryChip`: `tone` (`info`, `success`, `warn`, `danger`), `onClick` | A row of small facts under a page's header, like "2 approved" or "Priority 1"; with `onClick` a chip is a button that goes to where the fact comes from |
+| `Skeletons`, `Skeleton` | `Skeletons`: `label`; `Skeleton`: `width`, `height` | Blocks that stand in for loading content, announced once as `label` with `aria-busy`; they shimmer unless the user asked for less motion |
+| `Timeline`, `TimelineCard`, `TimelineNote` | `Timeline`: `label`; `TimelineCard`: `author`, `at`, `tag`, `actions`, `quiet`, `clamp`; `TimelineNote`: `author`, `at` | A conversation or activity feed: a card per entry with the author's `Avatar`, name, time, an optional tag and actions, and the body as children (`Markdown` or your own); `quiet` for bots and the system; `clamp` cuts a long body with a "Show more" button that only appears when something was cut; a `TimelineNote` is a one-line entry like "Ada moved it to Active" |
+| `Markdown` | `source`, `inline` | Markdown as React: headings, lists with read-only task checkboxes, GFM tables, fenced code, quotes, rules, bold, italics, strikethrough, links and bare https URLs, images, and emoji shortcodes (`:white_check_mark:`, `:x:`, `:bulb:`: the GitHub and Slack names, flags left out; unknown names, and anything inside code, stay as typed). No HTML is ever parsed; only `https:` links open (through `wings.openUrl`, so the manifest needs `permissions.openUrl` with an `https://` prefix) and images load only from `https:` or `data:image/` png, jpeg, gif or webp URLs up to 8,000 characters (`MAX_DATA_IMAGE`); an `https:` image shows as a "Load image from <host>" button and loads only when clicked (no option to turn that off), because the text may come from an agent and the URL could carry data out, and a `data:` image shows at once; `[![alt](img)](url)` is a link with the alt as its text. `inline` renders just the inline parts in a span. Memoized on `source` |
 
 Every component passes other props, like `id`, `title`, `className`, `onClick` and `aria-*`, to its element.
 `TextInput` and `SearchField` pass `ref` to the input on React 19.
@@ -156,7 +161,7 @@ rather than styles.
 `w-title` with `data-size`; `w-heading`, `w-heading-row`; `w-card` with `data-size`; `w-gauge`, `w-gauge-label`, `w-gauge-value`,
 `w-gauge-note`, `w-meter` with `data-tone`, `w-meter-fill`; `w-stats`, `w-stat-label`, `w-stat-value`;
 `w-props`, `w-prop`, `w-prop-label`, `w-prop-value`; `w-list` with `data-density`, `w-list-item`,
-`w-list-button` with `data-align`; `w-dot` with `data-tone` or `data-color`; `w-pill`, `w-tag` with `data-tone`; `w-spinner` with `data-size`;
+`w-list-button` with `data-align`; `w-dot` with `data-tone` or `data-color`; `w-avatar` with `data-size` and `--w-hue`; `w-pill`, `w-tag` with `data-tone`; `w-spinner` with `data-size`;
 `w-loading`, `w-empty`, `w-empty-detail`; `w-button` with `data-variant`, `data-size`, `aria-disabled`; `w-chips`, `w-chip`;
 `w-tabs`, `w-tab`; `w-field` with `data-layout`, `w-field-row`, `w-field-label`, `w-field-hint`,
 `w-field-group`, `w-input`, `w-search`, `w-select`, `w-check`; `w-combobox`, `w-listbox`, `w-option`,