@cl-light-ds/ui 0.3.0 → 0.5.0

package/src/components/profile-menu/ProfileMenu.astro

@@ -0,0 +1,236 @@
+---
+/**
+ * @component ProfileMenu
+ * @title Profile Menu
+ * @description The signed-in user's menu: the avatar itself is the trigger; the menu shows the avatar, name and email, an upgrade button that follows the plan, and account actions.
+ *
+ * @preview
+ *
+ * <ProfileMenu name="Wiley Fox" email="wiley.fox@northwind.com" plan="trial" />
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { ProfileMenu } from '@cl-light-ds/ui/components/profile-menu';
+ * ---
+ *
+ * <ProfileMenu
+ *   name="Wiley Fox"
+ *   email="wiley.fox@northwind.com"
+ *   avatarSrc="/avatars/wiley.png"
+ *   plan="pro"
+ *   upgradeHref="/billing"
+ * />
+ * ```
+ *
+ * @api
+ *
+ * ### Trigger
+ *
+ * The avatar is the trigger: a chrome-less, round `<button>` around the DS `Avatar`, with a focus ring and no
+ * hover ring (C15). `aria-haspopup` / `aria-expanded` and focus return on Esc land on it.
+ *
+ * ### Upgrade
+ *
+ * `plan` is looked up in `upgradeLabels` (default: `trial` → "Upgrade to Pro", `pro` → "Upgrade to Enterprise",
+ * `enterprise` → none). `upgradeLabel` overrides the lookup (`false` hides it); the `upgrade` slot replaces the button.
+ * The button is a menu item (value `"upgrade"`), so arrow keys reach it.
+ *
+ * ### Events (on the `[data-slot="profile-menu"]` root)
+ *
+ * | Event | Detail | Description |
+ * |-------|--------|-------------|
+ * | `profile-menu:select` | `{ id }` | Bubbles, cancelable. An item or the upgrade button (`id: "upgrade"`) was chosen. If it has an `href` and the event isn't cancelled, the browser navigates there. |
+ *
+ * The underlying `dropdown-menu:*` events are available too.
+ */
+
+import type { HTMLAttributes } from "astro/types";
+import { LogOut, Monitor, User } from "@lucide/astro";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import { Avatar, AvatarFallback, AvatarImage } from "../avatar";
+import { Button } from "../button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+} from "../dropdown-menu";
+import {
+  defaultProfileMenuUpgradeLabels,
+  type ProfileMenuItemData,
+  type ProfileMenuUpgradeLabels,
+} from "./types";
+
+interface Props extends HTMLAttributes<"div"> {
+  name: string;
+  email?: string;
+  avatarSrc?: string;
+  /** Avatar fallback. Default: the first letters of the first two words of `name`. */
+  initials?: string;
+  /** The account's plan, looked up in `upgradeLabels`. */
+  plan?: string;
+  upgradeLabels?: ProfileMenuUpgradeLabels;
+  /** Overrides the plan lookup; `false` hides the button. */
+  upgradeLabel?: string | false;
+  /** Where the upgrade button goes. Without it, listen for `profile-menu:select` (`id: "upgrade"`). */
+  upgradeHref?: string;
+  /** Menu rows. Default: Manage profile, Get desktop app, Log out. The default slot replaces them. */
+  items?: ProfileMenuItemData[];
+  /** Trigger's accessible name; `{name}` is replaced. */
+  triggerLabel?: string;
+  side?: "top" | "bottom" | "left" | "right";
+  align?: "start" | "center" | "end";
+  /** Gap below the avatar. 6px, like a Popover, so it clears a top bar's border (C28). */
+  sideOffset?: number;
+  /** Lock page scroll while open. Off by default: locking shifts pages that don't scroll. */
+  lockScroll?: boolean;
+  /** Classes for the menu panel. */
+  contentClass?: string;
+  class?: string;
+}
+
+const defaultItems: ProfileMenuItemData[] = [
+  { id: "manage-profile", label: "Manage profile", icon: User },
+  { id: "desktop-app", label: "Get desktop app", icon: Monitor },
+  { id: "log-out", label: "Log out", icon: LogOut, separatorBefore: true },
+];
+
+const {
+  name,
+  email,
+  avatarSrc,
+  initials = name
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((w) => w[0]!.toUpperCase())
+    .join(""),
+  plan,
+  upgradeLabels = defaultProfileMenuUpgradeLabels,
+  upgradeLabel,
+  upgradeHref,
+  items = defaultItems,
+  triggerLabel = "{name} — account menu",
+  side = "bottom",
+  align = "end",
+  sideOffset = 6,
+  lockScroll = false,
+  contentClass = "",
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+
+const lookup = (p?: string) => {
+  if (!p) return null;
+  const key = Object.keys(upgradeLabels).find((k) => k.toLowerCase() === p.toLowerCase());
+  return key ? upgradeLabels[key] : null;
+};
+const upgrade = upgradeLabel === false ? null : (upgradeLabel ?? lookup(plan));
+const hasUpgradeSlot = Astro.slots.has("upgrade");
+const hasHeaderSlot = Astro.slots.has("header");
+const hasItemsSlot = Astro.slots.has("default");
+---
+
+<div {...rest} data-slot="profile-menu" data-plan={plan} class={cn("flex", className)}>
+  {/* `flex`, not inline-block: no extra line-height under the avatar. */}
+  <DropdownMenu lockScroll={lockScroll} class="flex">
+    {/*
+      The avatar is the trigger itself (C15, D103): a reset round button, so the
+      runtime's aria-haspopup / aria-expanded and focus return land on it.
+      Focus ring only; no hover ring.
+    */}
+    <button
+      type="button"
+      data-slot="dropdown-menu-trigger"
+      aria-label={triggerLabel.replace("{name}", name)}
+      class="focus-visible:ring-ring cursor-pointer rounded-full outline-none focus-visible:ring-2"
+    >
+      <Avatar>
+        {avatarSrc && <AvatarImage src={avatarSrc} alt="" />}
+        <AvatarFallback>{initials}</AvatarFallback>
+      </Avatar>
+    </button>
+
+    <DropdownMenuContent side={side} align={align} sideOffset={sideOffset} class={cn("w-64", contentClass)}>
+      <div data-slot="profile-menu-header" class="flex flex-col gap-3 p-2">
+        {
+          hasHeaderSlot ? (
+            <slot name="header" />
+          ) : (
+            <div class="flex items-center gap-3">
+              <Avatar>
+                {avatarSrc && <AvatarImage src={avatarSrc} alt="" />}
+                <AvatarFallback>{initials}</AvatarFallback>
+              </Avatar>
+              <div class="flex min-w-0 flex-col">
+                <span class="truncate text-sm font-semibold">{name}</span>
+                {email && <span class="text-muted-foreground truncate text-xs">{email}</span>}
+              </div>
+            </div>
+          )
+        }
+        {
+          hasUpgradeSlot ? (
+            <slot name="upgrade" />
+          ) : (
+            upgrade && (
+              <Button
+                type="button"
+                size="sm"
+                class="w-full"
+                role="menuitem"
+                data-slot="dropdown-menu-item"
+                data-value="upgrade"
+                data-href={upgradeHref}
+                data-profile-menu-upgrade
+              >
+                {upgrade}
+              </Button>
+            )
+          )
+        }
+      </div>
+      <DropdownMenuSeparator />
+      {
+        hasItemsSlot ? (
+          <slot />
+        ) : (
+          items.map((item) => {
+            const Icon = item.icon;
+            return (
+              <>
+                {item.separatorBefore && <DropdownMenuSeparator />}
+                <DropdownMenuItem value={item.id} variant={item.variant} data-href={item.href}>
+                  {Icon && <Icon slot="leading-icon" />}
+                  {item.label}
+                </DropdownMenuItem>
+              </>
+            );
+          })
+        )
+      }
+    </DropdownMenuContent>
+  </DropdownMenu>
+</div>
+
+<script>
+  document.querySelectorAll<HTMLElement>('[data-slot="profile-menu"]').forEach((root) => {
+    if (root.dataset.profileMenuWired) return;
+    root.dataset.profileMenuWired = "";
+    root.addEventListener("dropdown-menu:select", (event) => {
+      const { value, item } = (event as CustomEvent<{ value: string; item: HTMLElement | null }>)
+        .detail;
+      const proceed = root.dispatchEvent(
+        new CustomEvent("profile-menu:select", {
+          bubbles: true,
+          cancelable: true,
+          detail: { id: value },
+        }),
+      );
+      const href = item?.dataset.href;
+      if (proceed && href) window.location.assign(href);
+    });
+  });
+</script>

package/src/components/profile-menu/index.ts

@@ -0,0 +1,2 @@
+export { default as ProfileMenu } from "./ProfileMenu.astro";
+export * from "./types";

package/src/components/profile-menu/types.ts

@@ -0,0 +1,27 @@
+import type { AstroComponent } from "@lucide/astro";
+
+/** One row of the profile menu. */
+export interface ProfileMenuItemData {
+  /** Sent as `value` in `dropdown-menu:select` / `profile-menu:select`. */
+  id: string;
+  label: string;
+  icon?: AstroComponent;
+  /** Navigate here when chosen (unless `profile-menu:select` is cancelled). */
+  href?: string;
+  variant?: "default" | "destructive";
+  /** Draw a separator above this item. */
+  separatorBefore?: boolean;
+}
+
+/**
+ * Upgrade-button label per plan. A plan mapped to `null` (or missing) gets no
+ * button. Keys are matched case-insensitively against the `plan` prop.
+ */
+export type ProfileMenuUpgradeLabels = Record<string, string | null>;
+
+/** Documented defaults: Trial → Pro, Pro → Enterprise, Enterprise → none. */
+export const defaultProfileMenuUpgradeLabels: ProfileMenuUpgradeLabels = {
+  trial: "Upgrade to Pro",
+  pro: "Upgrade to Enterprise",
+  enterprise: null,
+};

package/src/components/search-field/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to the `SearchField` component will be documented in this file.
+
+## Date 15th Oct 2026
+## Workspace selection handover (N20)
+
+### Added
+
+- `SearchField`: an `InputGroup` (search icon, `type="search"` input) joined to an outline `Button` in a `ButtonGroup`. The single focus ring round both while typing, and the button's own ring when tabbed to, come from `ButtonGroup` (C4); the outline button keeps its plain border on hover (C3).
+- Props: `label` (the field's `aria-label`, required), `placeholder` (defaults to `label`), `buttonLabel` (default "Search"), `name`, `value`, `inputId`, `size` (`sm` / `default` / `lg`, applied to field and button), `disabled`, `class`.
+- Submitting: Enter in the field or the button fires `search-field:submit` (`{ value }`, bubbles, cancelable) on the root. Without `action` the root is a `<div role="search">` and nothing else happens. With `action` (and `method`, default `get`) it is a `<form role="search">` whose submit button is the Search button; cancelling the event stops the submission.
+- Behaviour is a bundled script, bound once per field.
+- Storybook: "Search Field" under Forms.

package/src/components/search-field/SearchField.astro

@@ -0,0 +1,163 @@
+---
+/**
+ * @component SearchField
+ * @title Search Field
+ * @description A search input joined to a Search button: an `InputGroup` and an outline `Button` in a `ButtonGroup`, with one focus ring round both while typing and the button's own ring when tabbed to. Submits on Enter or on the button.
+ *
+ * @preview
+ *
+ * <SearchField label="Search workspaces" placeholder="Search workspaces" />
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { SearchField } from '@cl-light-ds/ui/components/search-field';
+ * ---
+ *
+ * <!-- In the page: listen for the event -->
+ * <SearchField label="Search workspaces" placeholder="Search workspaces" id="workspace-search" />
+ * <script>
+ *   document.getElementById("workspace-search")?.addEventListener("search-field:submit", (e) => {
+ *     runSearch(e.detail.value);
+ *   });
+ * </script>
+ *
+ * <!-- Or as a form: a GET to /search?q=… -->
+ * <SearchField label="Search" name="q" action="/search" />
+ * ```
+ *
+ * @api
+ *
+ * ### Events
+ *
+ * | Event | Detail | Description |
+ * |-------|--------|-------------|
+ * | `search-field:submit` | `{ value: string }` | On Enter in the field or a click on the button. Bubbles; cancelable: with `action`, cancelling it stops the form from submitting. |
+ *
+ * Without `action` the root is a `<div role="search">` and nothing is
+ * submitted: Enter and the button only fire the event. With `action` it is a
+ * `<form role="search">` and the button is its submit button.
+ */
+
+import type { HTMLAttributes } from "astro/types";
+import { Search } from "@lucide/astro";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import { Button } from "../button";
+import { ButtonGroup } from "../button-group";
+import { InputGroup, InputGroupAddon, InputGroupInput } from "../input-group";
+
+interface Props extends Omit<HTMLAttributes<"div">, "class"> {
+  /** Accessible name of the field (`aria-label`), e.g. "Search workspaces". */
+  label: string;
+  /** Placeholder; defaults to `label`. */
+  placeholder?: string;
+  /** Button text. */
+  buttonLabel?: string;
+  /** Field name (form submission). */
+  name?: string;
+  /** Initial value. */
+  value?: string;
+  /** id for the input. */
+  inputId?: string;
+  /** Renders a `<form role="search">` that submits here. */
+  action?: string;
+  method?: "get" | "post";
+  size?: "sm" | "default" | "lg";
+  disabled?: boolean;
+  class?: string;
+}
+
+const {
+  label,
+  placeholder = label,
+  buttonLabel = "Search",
+  name,
+  value,
+  inputId,
+  action,
+  method = "get",
+  size = "default",
+  disabled = false,
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+
+const isForm = action !== undefined;
+const Tag = isForm ? "form" : "div";
+---
+
+<Tag
+  {...rest}
+  {...(isForm ? { action, method } : {})}
+  role="search"
+  data-slot="search-field"
+  class={cn("flex w-full min-w-0", className)}
+>
+  <ButtonGroup class="w-full">
+    <InputGroup size={size} class="min-w-0 flex-1">
+      <InputGroupAddon align="inline-start">
+        <Search />
+      </InputGroupAddon>
+      <InputGroupInput
+        id={inputId}
+        type="search"
+        name={name}
+        value={value}
+        placeholder={placeholder}
+        aria-label={label}
+        enterkeyhint="search"
+        autocomplete="off"
+        disabled={disabled}
+        data-search-field-input
+      />
+    </InputGroup>
+    <Button
+      type={isForm ? "submit" : "button"}
+      variant="outline"
+      size={size}
+      disabled={disabled}
+      data-search-field-submit
+    >
+      {buttonLabel}
+    </Button>
+  </ButtonGroup>
+</Tag>
+
+<script>
+  const bound = new WeakSet<HTMLElement>();
+
+  function bind(root: HTMLElement) {
+    if (bound.has(root)) return;
+    bound.add(root);
+
+    const input = root.querySelector<HTMLInputElement>("[data-search-field-input]");
+    const button = root.querySelector<HTMLButtonElement>("[data-search-field-submit]");
+
+    // Returns false when a listener cancelled it.
+    const emit = () =>
+      root.dispatchEvent(
+        new CustomEvent("search-field:submit", {
+          detail: { value: input?.value ?? "" },
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+
+    if (root instanceof HTMLFormElement) {
+      root.addEventListener("submit", (event) => {
+        if (!emit()) event.preventDefault();
+      });
+      return;
+    }
+
+    input?.addEventListener("keydown", (event) => {
+      if (event.key !== "Enter" || event.isComposing) return;
+      event.preventDefault();
+      emit();
+    });
+    button?.addEventListener("click", () => emit());
+  }
+
+  document.querySelectorAll<HTMLElement>('[data-slot="search-field"]').forEach(bind);
+</script>

package/src/components/search-field/index.ts

@@ -0,0 +1 @@
+export { default as SearchField } from "./SearchField.astro";

package/src/components/table/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to the `Table` component family (`Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption`) are documented in this file.
 
+## Date 15th Oct 2026
+## Workspace selection handover (C13)
+
+- **`pinned="end"`** on `TableHead` and `TableCell`: the column sticks to the right edge while the table scrolls (an actions column). Works without `interactive`. The cells take the row's background (`bg-inherit`), so they follow the row's hover and its colour transition. The existing `pinnedColumns` pins from the start only.
+- **Row focus:** put `data-row-focus` on the element that leads a row (e.g. the name link) and its keyboard focus ring (`inset-ring-3 ring/50`) is drawn round the whole row. `TableRow` is now `position: relative`, and the cell holding a `data-row-focus` element is `static`.
+- Empty and error rows (`TableEmpty`) were already white; no change.
+- Storybook: "Pinned actions column and row focus" preview.
+
+
 ## 2026-09-18 — Figma alignment (ClickLearn Lightning Design Library, node `5548-9089`)
 
 Note: Figma's own canvas for this component is named "Table (⚠️)" — the designer's own marker that this page isn't fully finalized. Aligned against what's clearly evidenced (the overall container treatment) and left ambiguous details (see Notes) rather than guess.

package/src/components/table/TableCell.astro

@@ -12,6 +12,8 @@ interface Props extends HTMLAttributes<"td"> {
   numeric?: boolean;
   /** Nesting level (1–3). Indents the cell content 20px per level. */
   level?: 1 | 2 | 3;
+  /** "end" sticks the cell to the right edge while the table scrolls (pair with the same on its `TableHead`). */
+  pinned?: "end";
 }
 
 const {
@@ -20,6 +22,7 @@ const {
   numeric = false,
   align = numeric ? "right" : "left",
   level,
+  pinned,
   style,
   ...rest
 } = Astro.props as Props;
@@ -30,6 +33,7 @@ const indent = levelIndentStyle(level);
 <td
   data-slot="table-cell"
   data-column={column}
+  data-pinned-end={pinned === "end" ? "" : undefined}
   style={indent ? [indent, typeof style === "string" ? style : ""].filter(Boolean).join("; ") : style}
   class={cn(
     cellBase,
@@ -37,6 +41,8 @@ const indent = levelIndentStyle(level);
     "h-12 py-2 font-medium",
     numeric && "font-semibold tabular-nums",
     "[&:has([type=checkbox])]:w-15 [&:has([type=checkbox])]:text-center",
+    // A row-focus element's ring is drawn by the row, so its cell mustn't be the positioning box.
+    "has-[[data-row-focus]]:static",
     className,
   )}
   {...rest}

package/src/components/table/TableHead.astro

@@ -19,6 +19,8 @@ interface Props extends HTMLAttributes<"th"> {
   resizable?: boolean;
   /** Initial column width, e.g. "240px". */
   width?: string;
+  /** "end" sticks the column to the right edge while the table scrolls (an actions column). */
+  pinned?: "end";
 }
 
 const {
@@ -29,6 +31,7 @@ const {
   align = "left",
   resizable = false,
   width,
+  pinned,
   ...rest
 } = Astro.props as Props;
 
@@ -42,6 +45,7 @@ const ariaSort =
   data-sortable={sortable ? "" : undefined}
   data-sort={sortable ? sort : undefined}
   data-align={align}
+  data-pinned-end={pinned === "end" ? "" : undefined}
   aria-sort={ariaSort}
   scope="col"
   style={width ? `width: ${width}; min-width: ${width}` : undefined}
@@ -49,7 +53,7 @@ const ariaSort =
     cellBase,
     cellAlign({ align }),
     "group/th h-11 bg-muted text-xs font-semibold text-foreground uppercase",
-    "group-data-[sticky-header]/table:sticky group-data-[sticky-header]/table:top-0 group-data-[sticky-header]/table:z-10 data-[pinned]:z-20 data-[pinned]:bg-muted",
+    "group-data-[sticky-header]/table:sticky group-data-[sticky-header]/table:top-0 group-data-[sticky-header]/table:z-10 data-[pinned]:z-20 data-[pinned]:bg-muted data-[pinned-end]:z-20 data-[pinned-end]:bg-muted",
     "[&:has([type=checkbox])]:w-15 [&:has([type=checkbox])]:text-center",
     className,
   )}

package/src/components/table/TableRow.astro

@@ -42,7 +42,9 @@ const {
   aria-expanded={folder ? String(expanded) : undefined}
   aria-selected={selected ? "true" : undefined}
   class={cn(
-    "group/row bg-background transition-colors",
+    "group/row relative bg-background transition-colors",
+    // Row focus: an element marked `data-row-focus` (e.g. the row's name link) draws its focus ring round the whole row.
+    "[&_[data-row-focus]]:outline-none [&_[data-row-focus]]:after:pointer-events-none [&_[data-row-focus]]:after:absolute [&_[data-row-focus]]:after:inset-0 [&_[data-row-focus]]:after:z-[3] [&_[data-row-focus]:focus-visible]:after:inset-ring-3 [&_[data-row-focus]:focus-visible]:after:inset-ring-ring/50",
     "[tbody_&]:hover:bg-table-row-hover data-[state=selected]:bg-table-row-selected [tbody_&]:data-[state=selected]:hover:bg-table-row-selected",
     className,
   )}

package/src/components/table/table-cell-variants.ts

@@ -5,6 +5,8 @@ export const cellBase = [
   "relative border-b border-border px-4 align-middle whitespace-nowrap first:pl-6 last:pr-6",
   "outline-none focus-visible:z-[2] focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
   "data-[pinned]:sticky data-[pinned]:z-[1] data-[pinned]:bg-inherit data-[pinned-last]:shadow-[inset_-1px_0_0_var(--border)]",
+  // pinned="end": stuck to the right edge (an actions column), on the row's own background so it follows hover.
+  "data-[pinned-end]:sticky data-[pinned-end]:right-0 data-[pinned-end]:z-[1] data-[pinned-end]:bg-inherit",
 ];
 
 export const cellAlign = cva("", {

package/src/components/toast/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to the `Toast` component family (`Toaster`, `Toast`, and the `toast()` API in `@cl-light-ds/ui/lib/toast`) are documented in this file.
+
+## Date 15th Oct 2026
+## Workspace selection handover (N9)
+
+New component, replacing the workspace-selection screen's hand-composed `Toast.astro`, the toast stack in `TopBar.astro` and `restackToasts` (gap G14).
+
+### `Toaster`
+
+- Built on `@data-slot/toast` (`createToast`): the runtime renders toasts from a `<template>`, keeps their order, sets `role`/`aria-live` per kind (error → `alert`, assertive; others → `status`, polite), pauses timers on hover and focus, unfurls on hover or focus within (`data-expanded`), supports swipe to dismiss and measures heights (`--toast-*` tokens).
+- Placement (D160): fixed under the top bar's right end. Props `top` (where the bar ends, default 41px), `offset` (gap, default 0.5rem), `right` (inset, default 1rem, 1.5rem from md). The right edge adds `var(--data-slot-scrollbar-width, 0px)` so the stack stays put while a dialog hides the page scrollbar.
+- Stacking (D161, D164, D167): the newest in front, two more peeking out 10px below, 5% smaller each and blank; a fourth and beyond hidden while stacked. Unfurled: a list 12px apart, each at its own height, with a softer shadow (`shadow-xs`). All moves take 300ms.
+- Clear all (D170–D172, C23): with two or more toasts, unfurling shows a link button above the list, flush under the bar (the gap closes), no hover background, underline only. Label via `clearAllLabel`.
+- Toasts stay until closed by default (`duration={0}`, D166); `limit` (default 5) caps how many are kept visible.
+- Entrance (D160): slides in 2rem from the right and fades; slides back out on close.
+- Attention (D164, D175): once in (300ms), a ring ripples out three times (info blue, success green) or the card shakes 12px, seven swings (error). Only the newest toast. Skipped with `prefers-reduced-motion`, which also drops the slide (fade only).
+
+### `Toast`
+
+- Kinds `info` (blue `Info` icon), `success` (green `CircleCheck`), `error` (`callout-background-error` tint, `destructive/40` border, red `CircleX` icon and title, foreground text). Icon and ✕ at the top, outline action button centred on the right (D168, D169).
+- Usable on its own as a static toast (docs, previews).
+
+### `toast()` (`@cl-light-ds/ui/lib/toast`)
+
+- `toast({ kind, title, description, action: { label, onClick, href, download }, duration, id })` returns the id; `toast.update`, `toast.dismiss`, `toast.clear`. Wraps the runtime's inbound `toast:*` events; calls made before the Toaster is bound are queued.
+- `action.href` (+ `download`) opens or downloads a file: added on top of the runtime, whose action is a plain button.
+
+### Storybook
+
+- "Toast" section: static kinds, live buttons per kind, a stack of three, and Clear all.