@cl-light-ds/ui 0.4.0 → 0.5.0

package/src/components/empty-state/illustrations/NothingMatches.astro

@@ -0,0 +1,66 @@
+---
+/**
+ * Illustration "nothing-matches" (184×124, with its own padding inside the viewBox).
+ * The designer's artwork; colours mapped to design tokens so it follows the theme.
+ * Decorative. Generated from the workspace selection handover assets (N15).
+ */
+import type { HTMLAttributes } from "astro/types";
+
+type Props = Omit<HTMLAttributes<"svg">, "width" | "height">;
+
+const props = Astro.props as Props;
+// Unique ids per instance, so several illustrations on one page don't share filters.
+const uid = `es-nothing-matches-${Math.random().toString(36).slice(2, 8)}`;
+---
+
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  width="184"
+  height="124"
+  viewBox="-12 -12 184 124"
+  fill="none"
+  aria-hidden="true"
+  focusable="false"
+  {...props}
+>
+  <defs>
+    <filter id={`${uid}-sBack`} x="-30%" y="-30%" width="160%" height="160%" color-interpolation-filters="sRGB">
+      <feDropShadow dx="0" dy="1.5" stdDeviation="2" flood-color="#051729" flood-opacity="0.05"></feDropShadow>
+    </filter>
+    <filter id={`${uid}-sFront`} x="-40%" y="-30%" width="180%" height="170%" color-interpolation-filters="sRGB">
+      <feDropShadow dx="0" dy="5" stdDeviation="6" flood-color="#051729" flood-opacity="0.10"></feDropShadow>
+    </filter>
+    <filter id={`${uid}-sLens`} x="-60%" y="-60%" width="220%" height="220%" color-interpolation-filters="sRGB">
+      <feDropShadow dx="0" dy="4" stdDeviation="4" flood-opacity="0.28" style="flood-color:var(--primary)"></feDropShadow>
+    </filter>
+  </defs>
+  <circle cx="80" cy="50" r="44" stroke-width="12" style="stroke:color-mix(in oklab, var(--primary-50) 50%, var(--background))"></circle>
+  <circle cx="80" cy="50" r="24" stroke-width="10" style="stroke:var(--primary-50)"></circle>
+  <g transform="rotate(-12 44 52)">
+    <g filter={`url(#${uid}-sBack)`}><rect x="22" y="26" width="44" height="52" rx="8" style="fill:var(--background)"></rect></g>
+    <rect x="22.5" y="26.5" width="43" height="51" rx="7.5" stroke-opacity="0.06" style="stroke:var(--foreground)"></rect>
+    <rect x="28" y="32" width="14" height="14" rx="4" style="fill:var(--primary-100)"></rect>
+    <rect x="28" y="54" width="24" height="4" rx="2" style="fill:var(--border)"></rect>
+    <rect x="28" y="62" width="16" height="4" rx="2" style="fill:var(--muted)"></rect>
+  </g>
+  <g transform="rotate(12 116 52)">
+    <g filter={`url(#${uid}-sBack)`}><rect x="94" y="26" width="44" height="52" rx="8" style="fill:var(--background)"></rect></g>
+    <rect x="94.5" y="26.5" width="43" height="51" rx="7.5" stroke-opacity="0.06" style="stroke:var(--foreground)"></rect>
+    <rect x="100" y="34" width="28" height="4" rx="2" style="fill:var(--border)"></rect>
+    <rect x="100" y="42" width="32" height="4" rx="2" style="fill:var(--muted)"></rect>
+    <rect x="100" y="50" width="22" height="4" rx="2" style="fill:var(--muted)"></rect>
+    <rect x="100" y="58" width="28" height="4" rx="2" style="fill:var(--muted)"></rect>
+  </g>
+  <g filter={`url(#${uid}-sFront)`}><rect x="56" y="18" width="48" height="58" rx="9" style="fill:var(--background)"></rect></g>
+  <rect x="56.5" y="18.5" width="47" height="57" rx="8.5" stroke-opacity="0.06" style="stroke:var(--foreground)"></rect>
+  <rect x="62" y="24" width="36" height="22" rx="5" style="fill:var(--primary-50)"></rect>
+  <path d="M77 30.5 L84.5 35 L77 39.5 Z" stroke-width="1.5" stroke-linejoin="round" style="fill:var(--primary-300);stroke:var(--primary-300)"></path>
+  <rect x="62" y="53" width="28" height="4" rx="2" style="fill:var(--border)"></rect>
+  <rect x="62" y="61" width="18" height="4" rx="2" style="fill:var(--muted)"></rect>
+  <g filter={`url(#${uid}-sLens)`}>
+    <line x1="113.5" y1="79.5" x2="122" y2="88" stroke-width="6" stroke-linecap="round" style="stroke:var(--primary-700)"></line>
+    <circle cx="104" cy="70" r="13" stroke-width="4" style="fill:var(--background);stroke:var(--primary)"></circle>
+  </g>
+  <line x1="100" y1="66" x2="108" y2="74" stroke-width="2.2" stroke-linecap="round" style="stroke:var(--primary-300)"></line>
+  <line x1="108" y1="66" x2="100" y2="74" stroke-width="2.2" stroke-linecap="round" style="stroke:var(--primary-300)"></line>
+</svg>

package/src/components/empty-state/illustrations/index.ts

@@ -0,0 +1,27 @@
+import AllCaughtUp from "./AllCaughtUp.astro";
+import EmptyWorkspaces from "./EmptyWorkspaces.astro";
+import LoadError from "./LoadError.astro";
+import NoResults from "./NoResults.astro";
+import NothingMatches from "./NothingMatches.astro";
+
+/**
+ * Built-in empty state illustrations. Each has its own padding inside the
+ * viewBox; `pull` is the negative vertical margin that takes it back out, so
+ * the drawing sits at the message's normal spacing.
+ */
+export const emptyStateIllustrations = {
+  /** Nothing created yet (280×200, page). */
+  empty: { component: EmptyWorkspaces, width: 280, height: 200, pull: "-my-6" },
+  /** A search found nothing (280×200, page). */
+  "no-results": { component: NoResults, width: 280, height: 200, pull: "-my-6" },
+  /** Something failed to load (280×200, page). */
+  error: { component: LoadError, width: 280, height: 200, pull: "-my-6" },
+  /** Nothing new, e.g. notifications (144×104, menu). */
+  "all-caught-up": { component: AllCaughtUp, width: 144, height: 104, pull: "-my-2" },
+  /** A search in a menu or command palette found nothing (184×124, menu). */
+  "nothing-matches": { component: NothingMatches, width: 184, height: 124, pull: "-my-3" },
+} as const;
+
+export type EmptyStateIllustrationName = keyof typeof emptyStateIllustrations;
+
+export const EMPTY_STATE_ILLUSTRATIONS = Object.keys(emptyStateIllustrations) as EmptyStateIllustrationName[];

package/src/components/empty-state/index.ts

@@ -0,0 +1,7 @@
+export { default as EmptyState } from "./EmptyState.astro";
+export { emptyStateVariants } from "./EmptyState.astro";
+export {
+  EMPTY_STATE_ILLUSTRATIONS,
+  emptyStateIllustrations,
+  type EmptyStateIllustrationName,
+} from "./illustrations";

package/src/components/favorite-toggle/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to the `FavoriteToggle` component will be documented in this file.
+
+## Date 15th Oct 2026
+## Workspace selection handover (N8)
+
+### Added
+
+- `FavoriteToggle`: a `Toggle` with `variant="ghost"` and a Lucide `Star`. Pressed fills the star with the `favorite` token (was `badge-warning` in the screen, gap G3); no pressed background, the normal hover background on hover (C12).
+- Props: `label` (the accessible name, required), `defaultPressed`, `disabled`, `size` (Toggle sizes, default `sm`, 32px), `class`, and any button attribute. State is `aria-pressed`; changes fire the Toggle runtime's `toggle:change`. `data-favorite-toggle` marks it for scripts.
+- "Only on a favourite, or on hover or focus" is left to the consumer: documented as a `group/*` + `opacity-0 group-hover/*:opacity-100 group-focus-within/*:opacity-100 aria-pressed:opacity-100` recipe, so the star stays in the Tab order.
+- Storybook: "Favorite Toggle" under Actions.

package/src/components/favorite-toggle/FavoriteToggle.astro

@@ -0,0 +1,94 @@
+---
+/**
+ * @component FavoriteToggle
+ * @title Favorite Toggle
+ * @description A star that adds something to favourites or takes it out. A ghost `Toggle`: pressed shows as a star filled with the `favorite` colour, with no pressed background.
+ *
+ * @preview
+ *
+ * <div class="flex items-center gap-2">
+ *   <FavoriteToggle label="Favourite Acme Logistics" />
+ *   <FavoriteToggle label="Favourite Northwind" defaultPressed />
+ * </div>
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { FavoriteToggle } from '@cl-light-ds/ui/components/favorite-toggle';
+ * ---
+ *
+ * <FavoriteToggle label="Favourite Acme Logistics" defaultPressed={item.starred} />
+ * ```
+ *
+ * `label` names what is favourited ("Favourite Acme Logistics"); the state is
+ * announced through `aria-pressed`, so the label stays the same either way.
+ *
+ * ## Only when favourited, or on hover / focus
+ *
+ * Not built in. Put a `group/<name>` on the container and reveal the star with
+ * classes, so it is always there for keyboard and screen reader users:
+ *
+ * ```astro nocollapse
+ * <div class="group/card relative ...">
+ *   <FavoriteToggle
+ *     label="Favourite Acme Logistics"
+ *     class="opacity-0 group-hover/card:opacity-100 group-focus-within/card:opacity-100 aria-pressed:opacity-100"
+ *   />
+ * </div>
+ * ```
+ *
+ * @api
+ *
+ * ### Events
+ *
+ * | Event | Detail | Description |
+ * |-------|--------|-------------|
+ * | `toggle:change` | `{ pressed: boolean }` | Fired by the Toggle runtime when the state changes |
+ *
+ * Set it from outside with `toggle:set` (`{ detail: { value: true } }`), as for `Toggle`.
+ */
+
+import type { HTMLAttributes } from "astro/types";
+import { Star } from "@lucide/astro";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { ToggleSize } from "@cl-light-ds/ui/lib/toggle-shared";
+import { Toggle } from "../toggle";
+
+interface Props extends Omit<HTMLAttributes<"button">, "class"> {
+  /** Accessible name, e.g. "Favourite Acme Logistics". */
+  label: string;
+  /** Initially a favourite. */
+  defaultPressed?: boolean;
+  disabled?: boolean;
+  /** Toggle size; the star is 16px at every size. */
+  size?: ToggleSize;
+  class?: string;
+}
+
+const {
+  label,
+  defaultPressed = false,
+  disabled = false,
+  size = "sm",
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+---
+
+<Toggle
+  {...rest}
+  variant="ghost"
+  size={size}
+  defaultPressed={defaultPressed}
+  disabled={disabled}
+  aria-label={label}
+  data-favorite-toggle
+  class={cn("transition-[color,box-shadow,opacity]", className)}
+>
+  <Star
+    data-slot="favorite-toggle-icon"
+    class="size-4 group-aria-pressed/toggle:fill-favorite group-aria-pressed/toggle:text-favorite"
+    aria-hidden="true"
+  />
+</Toggle>

package/src/components/favorite-toggle/index.ts

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

package/src/components/input-group/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to the `InputGroup` component family (`InputGroup`, `InputGroupAddon`, `InputGroupButton`, `InputGroupInput`, `InputGroupText`, `InputGroupTextarea`) are documented in this file.
 
+## Date 15th Oct 2026
+## Workspace selection handover (C5)
+
+- An input directly after an `InputGroupAddon align="inline-start"` holding `InputGroupText` has no left padding, so a prefix such as `lightning.com/` runs straight into what's typed. Icon prefixes are unchanged. Needs the addon before the input in the markup.
+- Storybook: "Text prefix" preview.
+
+
 ## 2026-09-10 — Figma alignment (ClickLearn Lightning Design Library, node `2282-6923`)
 
 Figma documents a single "Default" composition with three example rows: a lead-icon search input with trailing supportive text, a plain input with a trailing icon, and a multi-line textarea with a toolbar (icon button + ghost text button + supportive text + separator + circular primary send button). No Sizes/States/Variants pages exist for this component in Figma (unlike `Input`) — scope is narrower accordingly.

package/src/components/input-group/InputGroup.astro

@@ -99,6 +99,8 @@ const {
   data-slot="input-group"
   data-size={size}
   class={cn(
+    // A text prefix ("…lightning.com/"): the input starts right after it, with no left padding.
+    "[&>[data-align=inline-start]:has(>[data-slot=input-group-text])+[data-slot=input-group-control]]:pl-0!",
     "group/input-group border-input bg-card has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-ring/50 has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[[data-slot][aria-invalid=true]]:border-destructive dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40 data-[size=sm]:h-8 data-[size=default]:h-9 data-[size=lg]:h-10 rounded-lg border shadow-xs transition-[color,box-shadow] in-data-[slot=combobox-content]:focus-within:border-inherit in-data-[slot=combobox-content]:focus-within:ring-0 has-[[data-slot=input-group-control]:focus-visible]:ring-3 has-[[data-slot][aria-invalid=true]]:ring-3 has-[>[data-align=block-end]]:h-auto! has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-start]]:h-auto! has-[>[data-align=block-start]]:flex-col has-[>[data-align=block-end]]:[&>input]:pt-3 has-[>[data-align=block-start]]:[&>input]:pb-3 has-[>[data-align=inline-end]]:[&>input]:pr-1.5 has-[>[data-align=inline-start]]:[&>input]:pl-1.5 relative flex w-full min-w-0 items-center outline-none has-[>textarea]:h-auto!",
     className,
   )}

package/src/components/loading-overlay/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to the `LoadingOverlay` component (and its controller in `@cl-light-ds/ui/lib/loading-overlay`) are documented in this file.
+
+## Date 15th Oct 2026
+## Workspace selection handover (N14)
+
+New component, replacing the workspace-selection screen's hand-composed `OpeningOverlay.astro` and its `runOverlay` / `revealWorkspace` / `hideOverlay` code.
+
+### `LoadingOverlay`
+
+- The whole screen dimmed and blurred (`bg-foreground/60`, `backdrop-blur-sm`), a 48px `Spinner`, a 30px title (`font-heading text-3xl font-semibold`) and a status line (`text-base`, `background/80`) (D117, D120).
+- Props: `title`, `lines` (status lines), `interval` (ms between lines, default 900, D135), `loop` (cycle instead of stopping on the last line), `open` (render shown).
+- `behind` slot: content shown under the dimming, faded in with `setLoadingOverlayBehind(true)` or `showLoadingOverlay({ behind: true | ms })` (D135, D191). Generalises the screen's workspace iframe.
+- Reveal (D143): `revealLoadingOverlay()` fades the dimming (700ms) and the spinner and text (500ms) away, then hides; returns a Promise.
+- A11y: `aria-busy="true"` while running; the title and status line are a polite live region (`role="status"`); the spinner is hidden from assistive tech (the text says it). On show, focus moves to the overlay (off whatever it covers) and returns on hide.
+- `prefers-reduced-motion`: no fades on reveal or behind.
+
+### Controller (`@cl-light-ds/ui/lib/loading-overlay`)
+
+- `showLoadingOverlay`, `setLoadingOverlayBehind`, `revealLoadingOverlay`, `hideLoadingOverlay`, and the matching `loading-overlay:*` events on the element; fires `loading-overlay:change` (`{ open }`).
+
+### Storybook
+
+- "Loading Overlay" section: run it with changing lines and a reveal, with content behind, and pinned open in a frame.

package/src/components/loading-overlay/LoadingOverlay.astro

@@ -0,0 +1,179 @@
+---
+/**
+ * @component LoadingOverlay
+ * @title Loading Overlay
+ * @description The global loading pattern: the whole screen dimmed and blurred, a 48px spinner, a 30px title and status lines that change as the work goes on. It can show what comes next behind the dimming, then fade away to reveal it.
+ *
+ * @preview
+ *
+ * <LoadingOverlay
+ *   id="demo-overlay"
+ *   title="Opening workspace…"
+ *   lines={["Loading your recordings…", "Fetching guides and assets…", "Getting your workspace ready…"]}
+ * />
+ * <Button data-demo-overlay>Show for 4 seconds</Button>
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { LoadingOverlay } from '@cl-light-ds/ui/components/loading-overlay';
+ * ---
+ *
+ * <LoadingOverlay title="Creating workspace…" lines={["Creating scaffolding…", "Setting up roles and permissions…"]} />
+ *
+ * <script>
+ *   import { showLoadingOverlay, revealLoadingOverlay } from '@cl-light-ds/ui/lib/loading-overlay';
+ *
+ *   showLoadingOverlay();
+ *   await createWorkspace();
+ *   await revealLoadingOverlay();
+ * </script>
+ * ```
+ *
+ * @api
+ *
+ * ### JS (`@cl-light-ds/ui/lib/loading-overlay`)
+ *
+ * | Function | Description |
+ * |----------|-------------|
+ * | `showLoadingOverlay({ title, lines, interval, loop, behind, overlay })` | Show it (or restart with new text) |
+ * | `setLoadingOverlayBehind(show)` | Fade the `behind` slot in or out under the dimming |
+ * | `revealLoadingOverlay({ duration })` | Fade the dimming and text away, then hide; returns a Promise |
+ * | `hideLoadingOverlay()` | Hide at once |
+ *
+ * ### Events (on the overlay)
+ *
+ * Inbound: `loading-overlay:show` (detail: show options), `loading-overlay:hide`, `loading-overlay:reveal` (`{ duration }`), `loading-overlay:behind` (`{ show }`).
+ * Outbound: `loading-overlay:change` (`{ open }`).
+ *
+ * ### Data attributes
+ *
+ * `data-reveal` (`on` | `off`), `data-behind` (`on` | `off`), `aria-busy` while running.
+ */
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+import Spinner from "../spinner/Spinner.astro";
+
+interface Props extends HTMLAttributes<"div"> {
+  /** The big title, e.g. "Opening workspace…". */
+  title?: string;
+  /** Status lines shown in turn under the title. */
+  lines?: string[];
+  /** ms between status lines (D135: 0.9s). */
+  interval?: number;
+  /** Start again after the last line instead of staying on it. */
+  loop?: boolean;
+  /** Render it shown (static screens, docs). Otherwise hidden until shown from JS. */
+  open?: boolean;
+  class?: string;
+}
+
+const {
+  title = "Loading…",
+  lines = [],
+  interval = 900,
+  loop = false,
+  open = false,
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+
+const hasBehind = Astro.slots.has("behind");
+---
+
+<div
+  data-slot="loading-overlay"
+  data-lines={JSON.stringify(lines)}
+  data-interval={interval}
+  data-loop={loop ? "true" : "false"}
+  data-reveal="off"
+  data-behind="off"
+  aria-busy={open ? "true" : undefined}
+  tabindex="-1"
+  hidden={!open}
+  class={cn(
+    "group/overlay text-background fixed inset-0 z-50 flex flex-col items-center justify-center gap-5 outline-none",
+    className,
+  )}
+  {...rest}
+>
+  {
+    /* D135, D191 — what comes next, behind the dimming; fades in on `data-behind="on"`. Not interactive. */
+    hasBehind && (
+      <div
+        data-slot="loading-overlay-behind"
+        aria-hidden="true"
+        inert
+        class="pointer-events-none absolute inset-0 opacity-0 transition-opacity duration-700 group-data-[behind=on]/overlay:opacity-100 motion-reduce:transition-none"
+      >
+        <slot name="behind" />
+      </div>
+    )
+  }
+  {/* D117 — the dimming; D143 — fades away on reveal. */}
+  <div
+    data-slot="loading-overlay-backdrop"
+    aria-hidden="true"
+    class="bg-foreground/60 absolute inset-0 backdrop-blur-sm transition-opacity duration-700 group-data-[reveal=on]/overlay:opacity-0 motion-reduce:transition-none"
+  >
+  </div>
+  <Spinner
+    aria-hidden="true"
+    role="presentation"
+    class="relative size-12 transition-opacity duration-500 group-data-[reveal=on]/overlay:opacity-0 motion-reduce:transition-none"
+  />
+  <div
+    role="status"
+    aria-live="polite"
+    class="relative flex flex-col items-center gap-1 px-6 text-center transition-opacity duration-500 group-data-[reveal=on]/overlay:opacity-0 motion-reduce:transition-none"
+  >
+    <p data-slot="loading-overlay-title" class="font-heading text-3xl font-semibold tracking-tight">
+      {title}
+    </p>
+    <p
+      data-slot="loading-overlay-status"
+      class="text-background/80 text-base"
+      hidden={lines.length === 0}
+    >
+      {lines[0]}
+    </p>
+  </div>
+</div>
+
+<script>
+  import {
+    hideLoadingOverlay,
+    revealLoadingOverlay,
+    setLoadingOverlayBehind,
+    showLoadingOverlay,
+    type LoadingOverlayShowOptions,
+  } from "@cl-light-ds/ui/lib/loading-overlay";
+
+  document.querySelectorAll<HTMLElement>('[data-slot="loading-overlay"]').forEach((root) => {
+    if (root.dataset.wired === "true") return;
+    root.dataset.wired = "true";
+    root.addEventListener("loading-overlay:show", (event) =>
+      showLoadingOverlay({
+        ...((event as CustomEvent<LoadingOverlayShowOptions>).detail ?? {}),
+        overlay: root,
+      }),
+    );
+    root.addEventListener("loading-overlay:hide", () => hideLoadingOverlay(root));
+    root.addEventListener("loading-overlay:reveal", (event) =>
+      revealLoadingOverlay({
+        ...((event as CustomEvent<{ duration?: number }>).detail ?? {}),
+        overlay: root,
+      }),
+    );
+    root.addEventListener("loading-overlay:behind", (event) =>
+      setLoadingOverlayBehind(
+        (event as CustomEvent<{ show?: boolean }>).detail?.show ?? true,
+        root,
+      ),
+    );
+    // Rendered open: run its status lines.
+    if (!root.hidden) showLoadingOverlay({ overlay: root });
+  });
+</script>

package/src/components/loading-overlay/index.ts

@@ -0,0 +1,8 @@
+export { default as LoadingOverlay } from "./LoadingOverlay.astro";
+export {
+  showLoadingOverlay,
+  hideLoadingOverlay,
+  revealLoadingOverlay,
+  setLoadingOverlayBehind,
+} from "../../lib/loading-overlay";
+export type { LoadingOverlayShowOptions } from "../../lib/loading-overlay";

package/src/components/notifications-menu/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to the `NotificationsMenu` component family (`NotificationsMenu`, `NotificationsMenuItem`) are documented in this file.
+
+## Date 15th Oct 2026
+## Workspace selection handover (N10)
+
+### Added
+
+- `NotificationsMenu`: a ghost `icon-sm` bell (`PopoverTrigger`) with a red `destructive` dot while any notification is unseen, opening a 360px (`w-90`) `PopoverContent` (`align="end"`, `sideOffset` 6): a header with the title and a link-style **Clear all**, a separator, a scrolling list (max 320px), and an empty state.
+- `NotificationsMenuItem`: avatar (DS `Avatar size="sm"`, initials or image) or a 24px icon chip (`tone`: `default` / `success` / `warning` / `destructive`), title, text, a "context · time" line (`<time>` when `datetime` is given), a blue `primary` "new" dot centred on the right (D154, no tint, D162) with sr-only "(new)", and a ✕ (`Button` ghost `icon-xs`, C25) shown on hover / focus-within (always on coarse pointers). Default slot for extra content (e.g. a Download button); `media` slot to replace the avatar / icon.
+- Items come from the `notifications` prop (JSON-serialisable data) and/or slotted `NotificationsMenuItem`s.
+- Seen logic (D141, D165): an item counts as seen once `seenThreshold` (60%) of it has been in view in the open list, or at once when hovered or keyboard-focused. Hovered / focused items lose their dot immediately; scrolled-to ones when the popover closes. The bell's dot and accessible name ("Notifications — {count} new") stay in sync.
+- Empty state (D203): the designer's `all-caught-up.svg` (144×104) with "You're all caught up". Copy, illustration (`emptyIllustration`, or `false`) and the whole block (`empty` slot) are overridable.
+- Events on the root: `notifications:dismiss` `{ id }` and `notifications:clear` `{ ids }` (both cancelable), `notifications:seen` `{ ids }`, `notifications:change` `{ total, unseen }`. Inbound `notifications:add` `{ item, position }`; any other DOM change to the list is picked up by a `MutationObserver`.
+- After a dismiss, focus moves to the next (or previous) item's ✕, else to the popover.
+
+### Generalised from the reference (cl-design `NotificationsPopover.astro`)
+
+- "workspace · time" → `context` + `time`; all copy (title, labels, empty state) is props, with the reference's English as defaults except the empty description, which is now generic.
+- Screen-specific export/duplicate templates are not part of the component: render a `NotificationsMenuItem` (e.g. in a `<template>`) and add it with `notifications:add`.
+- The bell is the trigger itself (`PopoverTrigger` renders the `Button`), so `aria-expanded` / `aria-controls` land on it, not on a wrapper.