wings-plugin-ui 0.4.0 → 0.5.0

package/README.md

@@ -86,6 +86,10 @@ 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 |
+| `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wings-plugin-ui",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "React components and the stylesheet for Wings plugin pages, on Base UI like the Wings app's shadcn/ui components.",
   "license": "MIT",
   "type": "module",

package/plugin-ui.css

@@ -1687,4 +1687,194 @@ span.w-md {
 .w-md-table [data-align="right"] {
   text-align: right;
 }
+
+/* Activity: a summary row, skeletons and a timeline, shared by pages like a pull request and a work item. */
+.w-summary {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 6px;
+}
+.w-summary-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  max-width: 100%;
+  height: 26px;
+  padding: 0 10px;
+  border: 1px solid var(--wings-hairline-strong);
+  border-radius: 999px;
+  background: var(--wings-surface);
+  color: var(--wings-fg);
+  font-size: 12px;
+  font-weight: 500;
+  white-space: nowrap;
+}
+button.w-summary-chip {
+  cursor: pointer;
+  transition: background-color 150ms;
+}
+button.w-summary-chip:hover {
+  background: var(--wings-hover);
+}
+button.w-summary-chip:focus-visible {
+  outline: 2px solid var(--wings-ring);
+  outline-offset: 2px;
+}
+.w-summary-chip[data-tone="info"] {
+  --w-tone: var(--wings-info);
+}
+.w-summary-chip[data-tone="success"] {
+  --w-tone: var(--wings-success);
+}
+.w-summary-chip[data-tone="warn"] {
+  --w-tone: var(--wings-warning);
+}
+.w-summary-chip[data-tone="danger"] {
+  --w-tone: var(--wings-danger);
+}
+.w-summary-chip[data-tone] {
+  border-color: color-mix(in srgb, var(--w-tone) 40%, transparent);
+  color: var(--w-tone);
+}
+
+.w-visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+.w-skeletons {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.w-skeleton {
+  display: block;
+  width: var(--w-width, 100%);
+  height: var(--w-height, 14px);
+  border-radius: var(--wings-radius);
+  background: linear-gradient(90deg, var(--wings-surface), var(--wings-hover), var(--wings-surface)) 0 0 / 200% 100%;
+  animation: w-shimmer 1.4s ease-in-out infinite;
+}
+@keyframes w-shimmer {
+  to {
+    background-position: -200% 0;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .w-skeleton {
+    animation: none;
+  }
+}
+
+.w-timeline {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.w-timeline-item {
+  min-width: 0;
+  content-visibility: auto;
+  contain-intrinsic-size: auto 96px;
+}
+.w-timeline-card {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  min-width: 0;
+  padding: 12px 14px;
+  border: 1px solid var(--wings-hairline);
+  border-radius: var(--wings-radius);
+  background: var(--wings-surface);
+}
+.w-timeline-item[data-quiet] > .w-timeline-card {
+  background: transparent;
+  font-size: 12px;
+}
+.w-timeline-head {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px 8px;
+  min-width: 0;
+}
+.w-timeline-author {
+  font-weight: 600;
+  overflow-wrap: anywhere;
+}
+.w-timeline-tag {
+  padding: 0 6px;
+  border: 1px solid var(--wings-hairline-strong);
+  border-radius: 999px;
+  color: var(--wings-muted);
+  font-size: 11px;
+  line-height: 16px;
+}
+.w-timeline-time {
+  color: var(--wings-muted);
+  font-size: 12px;
+}
+.w-timeline-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  margin-left: auto;
+}
+.w-timeline-note {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 0 14px;
+  color: var(--wings-muted);
+  font-size: 12px;
+}
+.w-timeline-note-text {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+.w-timeline-note-text strong {
+  color: var(--wings-fg);
+  font-weight: 600;
+}
+.w-clamp {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 4px;
+  min-width: 0;
+}
+.w-clamp-box {
+  width: 100%;
+  min-width: 0;
+}
+.w-clamp-box[data-clamped] {
+  max-height: 11em;
+  overflow: hidden;
+}
+.w-clamp-box[data-cut] {
+  mask-image: linear-gradient(to bottom, #000 70%, transparent);
+}
+.w-clamp-toggle {
+  padding: 2px 6px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--wings-info);
+  font-size: 12px;
+  cursor: pointer;
+}
+.w-clamp-toggle:hover {
+  background: var(--wings-hover);
+}
+.w-clamp-toggle:focus-visible {
+  outline: 2px solid var(--wings-ring);
+  outline-offset: 2px;
+}
 }

package/ui.d.ts

@@ -354,3 +354,28 @@ export function Disclosure(
 export function Markdown(props: Omit<Props<"div">, "children"> & { source: string; inline?: boolean }): ReactElement;
 /** The longest `data:image/` URL, in characters, that `Markdown` shows. */
 export const MAX_DATA_IMAGE: number;
+
+// ---------- activity: times, a summary row, skeletons and a timeline ----------
+
+/** "just now", "5 min ago", "3 h ago", "2 d ago", then the date; "" when `iso` isn't a date. `now` is for tests. */
+export function ago(iso: string, now?: number): string;
+/** A moment as a `time` element: how long ago (after `prefix`), the exact date and time as its title. Renders nothing when `iso` isn't a date. */
+export function Time(props: Omit<Props<"time">, "dateTime" | "children"> & { iso: string; prefix?: ReactNode; now?: number }): ReactElement | null;
+/** A row of `SummaryChip`s under a page's header. */
+export function Summary(props: Props<"div">): ReactElement;
+/** One fact in a `Summary`: a button when it has `onClick`, text otherwise. `tone` colours it. */
+export function SummaryChip(props: Omit<Props<"span">, "onClick"> & { tone?: "info" | "success" | "warn" | "danger"; onClick?: Props<"button">["onClick"]; type?: "button" | "submit" }): ReactElement;
+/** A block that stands in for loading content, `width` and `height` in px or any CSS length. Decoration: wrap a group in `Skeletons`. */
+export function Skeleton(props: Props<"span"> & { width?: number | string; height?: number | string }): ReactElement;
+/** A group of `Skeleton`s announced once as `label`, with `aria-busy`. */
+export function Skeletons(props: Omit<Props<"div">, "role" | "aria-label"> & { label: string }): ReactElement;
+/** An ordered list of `TimelineCard`s and `TimelineNote`s, named `label`. */
+export function Timeline(props: Props<"ol"> & { label: string }): ReactElement;
+/**
+ * An entry of a `Timeline`: the `Avatar`, name and time of `author` and `at` (ISO), an optional `tag` and `actions`
+ * at the right of that line, and `children` as the body. `quiet` for what a bot or the system wrote; `clamp` cuts a long
+ * body until "Show more".
+ */
+export function TimelineCard(props: Omit<Props<"li">, "children"> & { author: string; at?: string; tag?: ReactNode; actions?: ReactNode; quiet?: boolean; clamp?: boolean; children?: ReactNode }): ReactElement;
+/** A quiet one-line entry of a `Timeline`: a small avatar, the author in bold, `children`, then the time. */
+export function TimelineNote(props: Omit<Props<"li">, "children"> & { author: string; at?: string; children?: ReactNode }): ReactElement;

package/ui.js

@@ -903,3 +903,128 @@ export const Markdown = memo(function Markdown({ source, inline, className, ...r
     }),
   );
 });
+
+// ---------- activity: times, a summary row, skeletons and a timeline ----------
+
+/** "just now", "5 min ago", "3 h ago", "2 d ago", then the date. "" for something that isn't a date. */
+export function ago(iso, now = Date.now()) {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return "";
+  const minutes = Math.max(0, Math.round((now - t) / 60_000));
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes} min ago`;
+  if (minutes < 1440) return `${Math.round(minutes / 60)} h ago`;
+  if (minutes < 43_200) return `${Math.round(minutes / 1440)} d ago`;
+  return new Date(t).toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" });
+}
+
+/** A moment as a `time` element: how long ago, with the exact date and time on hover. Nothing when `iso` isn't a date. */
+export function Time({ iso, prefix, now, className, ...rest }) {
+  const text = ago(iso, now);
+  if (!text) return null;
+  return h("time", { title: new Date(iso).toLocaleString(), ...rest, className, dateTime: iso }, prefix, text);
+}
+
+/** A row of `SummaryChip`s under a page's header: the facts about the thing at a glance. */
+export function Summary({ className, ...rest }) {
+  return h("div", { ...rest, className: cx("w-summary", className) });
+}
+
+/** One fact in a `Summary`. With `onClick` it's a button (it takes you to where the fact comes from); without, plain text. */
+export function SummaryChip({ tone, className, onClick, type = "button", ...rest }) {
+  const props = { ...rest, className: cx("w-summary-chip", className), "data-tone": tone };
+  return onClick ? h("button", { ...props, type, onClick }) : h("span", props);
+}
+
+/** A grey block that stands in for content that is still loading, sized by `width` and `height` (CSS lengths or px). It shimmers unless the user asked for less motion. */
+export function Skeleton({ width, height, className, style, ...rest }) {
+  const size = (v) => (typeof v === "number" ? `${v}px` : v);
+  return h("span", {
+    ...rest,
+    className: cx("w-skeleton", className),
+    style: { ...style, ...(width === undefined ? null : { "--w-width": size(width) }), ...(height === undefined ? null : { "--w-height": size(height) }) },
+    "aria-hidden": true,
+  });
+}
+
+/** Skeletons that stand in for a section, announced once as `label` and `aria-busy`. */
+export function Skeletons({ label, children, className, ...rest }) {
+  // The label is text inside the region, which a live region announces; an aria-label alone isn't.
+  return h("div", { ...rest, className: cx("w-skeletons", className), role: "status", "aria-busy": true }, h("span", { className: "w-visually-hidden" }, label), children);
+}
+
+/** A conversation or an activity feed: an ordered list of `TimelineCard`s and `TimelineNote`s. */
+export function Timeline({ label, className, ...rest }) {
+  return h("ol", { ...rest, className: cx("w-timeline", className), "aria-label": label });
+}
+
+const FOCUSABLE = "a[href], button, input, select, textarea, summary, [tabindex]";
+
+/** Cuts `children` after a few lines until the reader asks for the rest; focusable things below the cut are inert meanwhile. The button only shows when something was cut. */
+function Clamped({ children }) {
+  const box = useRef(null);
+  const [more, setMore] = useState(false);
+  const [cut, setCut] = useState(false);
+  useLayoutEffect(() => {
+    const el = box.current;
+    if (!el) return;
+    if (more) {
+      for (const f of el.querySelectorAll(FOCUSABLE)) f.inert = false;
+      return;
+    }
+    const measure = () => {
+      setCut(el.scrollHeight > el.clientHeight + 1);
+      // What the cut hides can't be reached by keyboard or screen reader until "Show more".
+      const bottom = el.getBoundingClientRect().bottom;
+      for (const f of el.querySelectorAll(FOCUSABLE)) f.inert = f.getBoundingClientRect().top >= bottom - 1;
+    };
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    const watch = new ResizeObserver(measure);
+    watch.observe(el);
+    return () => watch.disconnect();
+  }, [more]);
+  return h(
+    "div",
+    { className: "w-clamp" },
+    h("div", { ref: box, className: "w-clamp-box", "data-clamped": more ? undefined : "", "data-cut": cut && !more ? "" : undefined }, children),
+    cut || more ? h("button", { type: "button", className: "w-clamp-toggle", "aria-expanded": more, onClick: () => setMore(!more) }, more ? "Show less" : "Show more") : null,
+  );
+}
+
+/**
+ * One entry of a `Timeline`, a card: the author's `Avatar`, name and when, a `tag` (like "Author") and `actions` on the
+ * right, and `children` as the body. `quiet` draws it without a fill, for what a bot or the system wrote. `clamp` cuts
+ * a long body until "Show more" is pressed.
+ */
+export function TimelineCard({ author, at, tag, actions, quiet, clamp, children, className, ...rest }) {
+  return h(
+    "li",
+    { ...rest, className: cx("w-timeline-item", className), "data-quiet": quiet ? "" : undefined },
+    h(
+      "article",
+      { className: "w-timeline-card", "aria-label": `By ${author}` },
+      h(
+        "div",
+        { className: "w-timeline-head" },
+        h(Avatar, { name: author }),
+        h("strong", { className: "w-timeline-author" }, author),
+        tag ? h("span", { className: "w-timeline-tag" }, tag) : null,
+        h(Time, { iso: at, className: "w-timeline-time" }),
+        actions ? h("span", { className: "w-timeline-actions" }, actions) : null,
+      ),
+      clamp ? h(Clamped, null, children) : children,
+    ),
+  );
+}
+
+/** A quiet one-line entry of a `Timeline`, like "Ada moved it to Active": a small avatar, then `children`, then when. */
+export function TimelineNote({ author, at, children, className, ...rest }) {
+  return h(
+    "li",
+    { ...rest, className: cx("w-timeline-item w-timeline-note", className) },
+    h(Avatar, { name: author, size: "small" }),
+    h("span", { className: "w-timeline-note-text" }, h("strong", null, author), " ", children),
+    h(Time, { iso: at, className: "w-timeline-time" }),
+  );
+}