@cl-light-ds/ui 0.3.0 → 0.5.0

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/logo/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to the `Logo` component will be documented in this file.
+
+## 2026-10-06 — Initial implementation
+
+### Added
+
+- `Logo` — inline SVG ClickLearn logo. Props: `variant` (`full` | `mark` | `wordmark`), `tone` (`color` | `dark` | `white`), `size` (`sm` 24px | `default` 32px | `lg` 48px | `xl` 64px height, width auto), `title` (accessible name; `""` marks it decorative).
+- `logoSvg(variant, tone)` — returns standalone SVG markup for the same artwork (used for the downloads on the Foundations → Logos page).
+- `LOGO_COLORS` — mark `#3785E0` (`--primary-500`), wordmark `#112843` (`--primary-950`).
+
+### Notes
+
+- Artwork taken from the logo previously inlined in the storybook sidebar. The Figma "ClickLearn Logo" component set (library key `87ef4404…`) was not reachable through the Figma API at the time of writing; align variants/tones with it once a node link is available.
+- Fills are fixed brand hex values (not theme tokens) so the logo stays on-brand regardless of theme; use `tone="white"` on dark or brand-coloured surfaces.
+- No `clipPath`/`id`s are used, so multiple logos on a page never clash.

package/src/components/logo/Logo.astro

@@ -0,0 +1,90 @@
+---
+/**
+ * @component Logo
+ * @title Logo
+ * @description The ClickLearn logo as an inline SVG: full lockup, mark only or wordmark only, in brand colour, dark or white.
+ * @status stable
+ * @since 0.4.0
+ *
+ * @preview
+ *
+ * <Logo />
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { Logo } from '@cl-light-ds/ui/components/logo';
+ * ---
+ * <Logo variant="full" tone="color" size="default" />
+ * ```
+ */
+import { cva } from "class-variance-authority";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+import {
+  LOGO_VIEWBOX,
+  MARK_PATHS,
+  WORDMARK_PATHS,
+  logoFills,
+  type LogoTone,
+  type LogoVariant,
+} from "./logo-paths";
+
+type LogoSize = "sm" | "default" | "lg" | "xl";
+
+interface Props extends HTMLAttributes<"svg"> {
+  variant?: LogoVariant;
+  tone?: LogoTone;
+  size?: LogoSize;
+  /** Accessible name. Pass an empty string when the logo is decorative (e.g. next to visible "ClickLearn" text). */
+  title?: string;
+  class?: string;
+}
+
+const {
+  class: className = "",
+  variant = "full",
+  tone = "color",
+  size = "default",
+  title = "ClickLearn",
+  ...rest
+} = Astro.props as Props;
+
+const logoVariants = cva("w-auto shrink-0", {
+  variants: {
+    size: {
+      sm: "h-6",
+      default: "h-8",
+      lg: "h-12",
+      xl: "h-16",
+    },
+  },
+  defaultVariants: {
+    size: "default",
+  },
+});
+
+const fills = logoFills(tone);
+const showMark = variant !== "wordmark";
+const showWordmark = variant !== "mark";
+const decorative = title === "";
+---
+
+<svg
+  {...rest}
+  data-slot="logo"
+  data-variant={variant}
+  data-tone={tone}
+  viewBox={LOGO_VIEWBOX[variant]}
+  fill="none"
+  xmlns="http://www.w3.org/2000/svg"
+  role={decorative ? undefined : "img"}
+  aria-label={decorative ? undefined : title}
+  aria-hidden={decorative ? "true" : undefined}
+  class={cn(logoVariants({ size }), className)}
+>
+  {!decorative && <title>{title}</title>}
+  {showWordmark && WORDMARK_PATHS.map((d) => <path d={d} fill={fills.wordmark} />)}
+  {showMark && MARK_PATHS.map((d) => <path d={d} fill={fills.mark} />)}
+</svg>

package/src/components/logo/index.ts

@@ -0,0 +1,3 @@
+export { default as Logo } from "./Logo.astro";
+export { LOGO_COLORS, LOGO_VIEWBOX, logoSvg } from "./logo-paths";
+export type { LogoTone, LogoVariant } from "./logo-paths";

package/src/components/logo/logo-paths.ts

@@ -0,0 +1,57 @@
+/**
+ * ClickLearn logo artwork. Single source for the `Logo` component and for
+ * generating downloadable SVG files.
+ */
+
+export type LogoVariant = "full" | "mark" | "wordmark";
+export type LogoTone = "color" | "dark" | "white";
+
+/** Brand colours of the logo artwork (mark = primary-500, wordmark = primary-950). */
+export const LOGO_COLORS = {
+  mark: "#3785E0",
+  wordmark: "#112843",
+  white: "#FFFFFF",
+} as const;
+
+/** Paths for the speech-bubble mark, in the full lockup's coordinate space. */
+export const MARK_PATHS = [
+  "M54.4204 27.2102C39.3935 27.2102 27.2102 39.3936 27.2102 54.4204C27.2102 69.4472 39.3935 81.6306 54.4204 81.6306C69.4472 81.6306 81.6306 69.4472 81.6306 54.4204C81.6306 39.3936 69.4472 27.2102 54.4204 27.2102ZM54.4204 68.0255C46.9172 68.0255 40.8153 61.9236 40.8153 54.4204C40.8153 46.9172 46.9172 40.8153 54.4204 40.8153C61.9236 40.8153 68.0255 46.9172 68.0255 54.4204C68.0255 61.9236 61.9236 68.0255 54.4204 68.0255Z",
+  "M54.4204 0C24.3633 0 0 24.3633 0 54.4204C0 79.8291 17.4104 101.169 40.9529 107.162C48.2346 109.015 54.4204 114.932 54.4204 122.446C77.8586 122.446 108.841 95.4465 108.841 54.4204C108.841 24.3633 84.4774 0 54.4204 0ZM54.4204 95.2357C31.9141 95.2357 13.6051 76.9266 13.6051 54.4204C13.6051 31.9142 31.9141 13.6051 54.4204 13.6051C76.9266 13.6051 95.2357 31.9142 95.2357 54.4204C95.2357 76.9266 76.9266 95.2357 54.4204 95.2357Z",
+] as const;
+
+/** Paths for the "ClickLearn" wordmark, in the full lockup's coordinate space. */
+export const WORDMARK_PATHS = [
+  "M136.051 54.4202C136.051 73.1851 151.22 88.433 170.002 88.433C176.325 88.433 182.192 86.8106 187.07 83.8311V69.7566C183.186 74.0864 177.227 76.7938 170.274 76.7938C157.812 76.7938 148.241 67.0492 148.241 54.4202C148.241 41.7913 157.812 32.0467 170.274 32.0467C177.227 32.0467 183.189 34.7541 187.07 39.0839V25.0094C182.192 22.0333 176.325 20.4075 170.002 20.4075C151.22 20.4075 136.051 35.6554 136.051 54.4202Z",
+  "M227.079 40.8152H215.175V87.0725H227.079V40.8152Z",
+  "M233.307 64.1139C233.307 78.0897 244.643 88.433 257.888 88.433C261.969 88.433 265.779 87.5248 268.68 85.8922V74.4572C265.867 76.7258 262.874 77.9945 258.612 77.9945C251.174 77.9945 244.735 72.2769 244.735 64.1105C244.735 55.944 251.174 50.3183 258.612 50.3183C262.874 50.3183 265.867 51.5904 268.68 53.7672V42.3321C265.779 40.6995 261.969 39.7914 257.888 39.7914C244.647 39.7914 233.307 50.138 233.307 64.1139Z",
+  "M384.334 39.7948C371.654 39.7948 360.514 50.2265 360.514 64.2057C360.514 78.1849 371.654 88.433 386.235 88.433C392.031 88.433 398.371 86.9806 402.99 83.8038V73.2769C399.003 76.5421 393.119 78.4502 387.684 78.4502C379.17 78.4502 373.011 74.3653 371.742 67.1988H406.34C406.432 66.1989 406.432 65.2907 406.432 64.3826C406.432 50.5904 399.007 39.7914 384.334 39.7914V39.7948ZM372.106 59.2126C373.735 53.223 378.354 49.4102 384.15 49.4102C390.946 49.4102 394.656 54.3148 395.201 59.2126H372.106Z",
+  "M193.872 87.0725H205.777V19.047C201.355 20.4075 198.634 20.7476 193.872 20.7476V87.0725Z",
+  "M317.614 40.8152H303.523L287.387 59.2603V19.047C282.965 20.4075 280.244 20.7476 275.483 20.7476V87.0725H287.387V66.09L304.155 87.0725H318.339L298.013 62.318L317.614 40.8152Z",
+  "M471.103 40.873H459.151V87.0725H471.056V64.5969C471.056 55.6311 476.447 51.9203 483.331 51.9203C484.236 51.9203 485.025 51.9475 486.021 52.0394V40.0873C478.879 39.4546 473.641 43.5906 471.103 48.0293V40.873Z",
+  "M517.004 39.7948C511.096 39.7948 506.279 42.5906 503.824 46.2912V40.1995H491.824V87.0725H503.728V60.6378C503.728 55.1345 507.184 50.5326 512.912 50.5326C518.64 50.5326 521.755 55.1345 521.755 60.5493V87.0759H534V57.393C534 47.1075 527.728 39.7982 517.004 39.7982V39.7948Z",
+  "M430.645 39.7948C424.584 39.7948 418.55 41.5396 414.931 43.5362V54.0801C418.642 51.8999 423.224 50.138 428.111 50.138C435.081 50.138 439.063 53.7706 439.063 58.4882V61.6888C437.162 59.6922 432.819 57.8521 427.57 57.8521C417.884 57.8521 409.829 63.9336 409.829 72.9164C409.829 82.4467 417.884 88.433 427.207 88.433C432.999 88.433 437.363 86.1916 439.08 84.0113V87.0725H450.645V57.9406C450.645 46.5973 443.043 39.7948 430.645 39.7948ZM429.921 79.5387C425.217 79.5387 420.782 77.1782 420.782 72.9164C420.782 68.6546 425.217 66.1989 429.921 66.1989C434.625 66.1989 439.244 68.6478 439.244 72.9164C439.244 77.185 434.536 79.5387 429.921 79.5387Z",
+  "M221.083 33.2065C224.84 33.2065 227.885 30.1609 227.885 26.404C227.885 22.647 224.84 19.6014 221.083 19.6014C217.326 19.6014 214.28 22.647 214.28 26.404C214.28 30.1609 217.326 33.2065 221.083 33.2065Z",
+  "M333.984 22.4483C329.563 23.8088 326.842 24.1489 322.08 24.1489V87.0725H359.494V76.8687H333.984V22.4483Z",
+] as const;
+
+/** viewBox per variant — crops the shared coordinate space. */
+export const LOGO_VIEWBOX: Record<LogoVariant, string> = {
+  full: "0 0 534 122.446",
+  mark: "0 0 108.841 122.446",
+  wordmark: "136.051 19.047 397.949 69.386",
+};
+
+export function logoFills(tone: LogoTone) {
+  if (tone === "white") return { mark: LOGO_COLORS.white, wordmark: LOGO_COLORS.white };
+  if (tone === "dark") return { mark: LOGO_COLORS.wordmark, wordmark: LOGO_COLORS.wordmark };
+  return { mark: LOGO_COLORS.mark, wordmark: LOGO_COLORS.wordmark };
+}
+
+/** Standalone SVG markup, e.g. for download links. */
+export function logoSvg(variant: LogoVariant, tone: LogoTone = "color"): string {
+  const fills = logoFills(tone);
+  const [, , width, height] = LOGO_VIEWBOX[variant].split(" ").map(Number);
+  const mark = variant === "wordmark" ? [] : MARK_PATHS.map((d) => `<path d="${d}" fill="${fills.mark}"/>`);
+  const word = variant === "mark" ? [] : WORDMARK_PATHS.map((d) => `<path d="${d}" fill="${fills.wordmark}"/>`);
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${LOGO_VIEWBOX[variant]}" width="${width}" height="${height}" fill="none"><title>ClickLearn</title>${[...word, ...mark].join("")}</svg>`;
+}

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.