@cl-light-ds/ui 0.3.0 → 0.5.0

package/src/components/toast/Toast.astro

@@ -0,0 +1,145 @@
+---
+/**
+ * @component Toast
+ * @title Toast
+ * @description One toast: an icon, a title and a line of text, an optional action and a ✕. `Toaster` uses it as the template for every toast it shows; on its own it renders a static toast (docs, screenshots).
+ *
+ * @preview
+ *
+ * <ol class="flex w-96 max-w-full list-none flex-col gap-3 p-0">
+ *   <Toast kind="info" title="Export started" description="We'll let you know when Acme Finance is ready." />
+ *   <Toast kind="success" title="Export ready" description="Acme Finance export.zip" action="Download" />
+ *   <Toast kind="error" title="Couldn't open workspace" description="Something went wrong opening Acme Finance." />
+ * </ol>
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { Toast } from '@cl-light-ds/ui/components/toast';
+ * ---
+ *
+ * <ol class="list-none p-0">
+ *   <Toast kind="success" title="Export ready" description="Acme.zip" action="Download" />
+ * </ol>
+ * ```
+ *
+ * Kinds: `info` (blue icon), `success` (green icon), `error` (light red tint,
+ * red border, red icon and title). The icon and the ✕ sit at the top; the
+ * action (an outline button) is centred on the right (D168, D169).
+ *
+ * Inside a `Toaster`, `@data-slot/toast` fills `toast-title`,
+ * `toast-description` and `toast-action`, and sets `data-type` (the kind),
+ * `data-front`, `data-expanded` and `data-state` on the item. Once a toast is
+ * in, the Toaster sets `data-attention="on"` for 2.4s: a ring ripples out
+ * three times (info, success) or the card shakes (error) (D164, D175).
+ */
+import { CircleCheck, CircleX, Info, X } from "@lucide/astro";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+import Button from "../button/Button.astro";
+
+interface Props extends HTMLAttributes<"li"> {
+  kind?: "info" | "success" | "error";
+  title?: string;
+  description?: string;
+  /** The action button's label; no action when left out. */
+  action?: string;
+  /** Accessible name of the ✕. */
+  closeLabel?: string;
+  class?: string;
+}
+
+const {
+  kind = "info",
+  title = "",
+  description = "",
+  action = "",
+  closeLabel = "Close",
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+
+const error = kind === "error";
+---
+
+<li
+  data-slot="toast-item"
+  data-type={kind}
+  role={error ? "alert" : "status"}
+  aria-live={error ? "assertive" : "polite"}
+  aria-atomic="true"
+  class={cn("group/toast list-none", className)}
+  {...rest}
+>
+  {/* D164, D175 — the ripple: three rings in the kind's colour (not on errors). */}
+  <span
+    data-slot="toast-ripple"
+    aria-hidden="true"
+    class="ring-primary group-data-[type=success]/toast:ring-success pointer-events-none absolute inset-0 rounded-lg opacity-0 ring-2 group-data-[type=error]/toast:hidden group-data-[attention=on]/toast:animate-out group-data-[attention=on]/toast:fade-out group-data-[attention=on]/toast:zoom-out-105 group-data-[attention=on]/toast:fill-mode-forwards group-data-[attention=on]/toast:repeat-3 group-data-[attention=on]/toast:animation-duration-700 group-data-[attention=on]/toast:opacity-100 motion-reduce:hidden"
+  ></span>
+  <div
+    data-slot="toast-card"
+    class="bg-popover text-popover-foreground group-data-[type=error]/toast:bg-callout-error group-data-[type=error]/toast:border-destructive/40 relative h-full overflow-hidden rounded-lg border p-4 pe-10 shadow-md transition-shadow group-data-[expanded=true]/toast:shadow-xs group-data-[attention=on]/toast:group-data-[type=error]/toast:animate-in group-data-[attention=on]/toast:group-data-[type=error]/toast:slide-in-from-left-3 group-data-[attention=on]/toast:group-data-[type=error]/toast:direction-alternate group-data-[attention=on]/toast:group-data-[type=error]/toast:repeat-7 group-data-[attention=on]/toast:group-data-[type=error]/toast:animation-duration-75 motion-reduce:animate-none!"
+  >
+    <div data-slot="toast-body" class="flex items-start gap-3">
+      <Info
+        aria-hidden="true"
+        class="text-primary mt-0.5 size-5 shrink-0 group-data-[type=error]/toast:hidden group-data-[type=success]/toast:hidden"
+      />
+      <CircleCheck
+        aria-hidden="true"
+        class="text-success mt-0.5 hidden size-5 shrink-0 group-data-[type=success]/toast:block"
+      />
+      <CircleX
+        aria-hidden="true"
+        class="text-destructive mt-0.5 hidden size-5 shrink-0 group-data-[type=error]/toast:block"
+      />
+      <div class="flex min-w-0 flex-1 flex-col gap-1">
+        <p
+          data-slot="toast-title"
+          class="text-sm font-semibold group-data-[type=error]/toast:text-destructive"
+        >
+          {title}
+        </p>
+        <p
+          data-slot="toast-description"
+          class="text-muted-foreground text-sm group-data-[type=error]/toast:text-foreground"
+          hidden={!description}
+        >
+          {description}
+        </p>
+      </div>
+      <Button
+        data-slot="toast-action"
+        type="button"
+        size="sm"
+        variant="outline"
+        class="shrink-0 self-center"
+        hidden={!action}
+      >
+        {action}
+      </Button>
+    </div>
+    <Button
+      data-slot="toast-close"
+      type="button"
+      variant="ghost"
+      size="icon-sm"
+      aria-label={closeLabel}
+      class="group-data-[type=error]/toast:hover:bg-destructive/10 absolute top-2 right-2"
+    >
+      <X />
+    </Button>
+  </div>
+</li>
+
+<style is:global>
+  /* In a layer, so the Toaster's stack rules (more specific) take over inside it. */
+  @layer components {
+    [data-slot="toast-item"] {
+      position: relative;
+    }
+  }
+</style>

package/src/components/toast/Toaster.astro

@@ -0,0 +1,322 @@
+---
+/**
+ * @component Toaster
+ * @title Toaster
+ * @description The toast stack: a live region under the top bar's right end where toasts slide in from the right, stack (the newest in front, two peeking out below) and unfurl into a list with Clear all on hover or keyboard focus.
+ *
+ * @preview
+ *
+ * <Toaster />
+ * <Button variant="outline" data-demo-toast="success">Show a toast</Button>
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { Toaster } from '@cl-light-ds/ui/components/toast';
+ * ---
+ *
+ * <!-- once per page, e.g. in the layout -->
+ * <Toaster top="41px" />
+ *
+ * <script>
+ *   import { toast } from '@cl-light-ds/ui/lib/toast';
+ *
+ *   toast({ kind: 'success', title: 'Export ready', description: 'Acme Finance export.zip',
+ *           action: { label: 'Download', href: '/exports/acme.zip', download: true } });
+ * </script>
+ * ```
+ *
+ * @api
+ *
+ * ### JS (`@cl-light-ds/ui/lib/toast`)
+ *
+ * | Function | Description |
+ * |----------|-------------|
+ * | `toast({ kind, title, description, action, duration, id, closeLabel, toaster })` | Show a toast, returns its id |
+ * | `toast.update(id, patch)` | Change a showing toast |
+ * | `toast.dismiss(id)` | Close one |
+ * | `toast.clear()` | Close all |
+ *
+ * ### Events (on the `[data-slot="toast"]` root, from `@data-slot/toast`)
+ *
+ * Inbound: `toast:show` (`{ title, description, type, action, duration, id }`), `toast:update`, `toast:dismiss`, `toast:clear`.
+ * Outbound: `toast:change` (`{ id, action: "show" | "dismiss" }`), `toast:action` (`{ id, value }`), and `toaster:ready` once bound.
+ *
+ * ### Placement
+ *
+ * Fixed; `top` is where the top bar ends (default 41px, the top bar's height), `offset` the gap under it, `right` the inset from the
+ * window's right edge (plus `--data-slot-scrollbar-width` while a dialog hides the scrollbar). Unfurled with two or more toasts the
+ * gap closes so Clear all sits flush under the bar (D172).
+ */
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+import Button from "../button/Button.astro";
+import Toast from "./Toast.astro";
+
+interface Props extends HTMLAttributes<"ol"> {
+  /** Where the bar above ends (CSS length). Default 41px. */
+  top?: string;
+  /** Gap between the bar and the stack (CSS length). Default 0.5rem. */
+  offset?: string;
+  /** Inset from the window's right edge (CSS length). Default 1rem, 1.5rem from md. */
+  right?: string;
+  /** ms before a toast closes by itself; 0 = stays until closed (D166). */
+  duration?: number;
+  /** Toasts kept visible at once; older ones wait, hidden, until others close. */
+  limit?: number;
+  /** Accessible name of the region. */
+  label?: string;
+  clearAllLabel?: string;
+  closeLabel?: string;
+  /** Root id, to target this Toaster from `toast({ toaster })`. */
+  id?: string;
+  class?: string;
+}
+
+const {
+  top,
+  offset,
+  right,
+  duration = 0,
+  limit = 5,
+  label = "Notifications",
+  clearAllLabel = "Clear all",
+  closeLabel = "Close",
+  id,
+  class: className = "",
+  style,
+  ...rest
+} = Astro.props as Props;
+
+const vars = [
+  top && `--toaster-top: ${top}`,
+  offset && `--toaster-offset: ${offset}`,
+  right && `--toaster-right: ${right}`,
+]
+  .filter(Boolean)
+  .join("; ");
+---
+
+<div
+  data-slot="toast"
+  data-position="top-right"
+  data-duration={duration}
+  data-limit={limit}
+  id={id}
+  class="contents"
+>
+  <template data-slot="toast-template">
+    <Toast closeLabel={closeLabel} />
+  </template>
+  <ol
+    data-slot="toast-viewport"
+    role="region"
+    aria-label={label}
+    class={cn("group/toaster", className)}
+    style={[vars, style].filter(Boolean).join("; ") || undefined}
+    {...rest}
+  >
+    {/* D171, D172, C23 — above the unfurled list: a link button, no hover background, only the underline. */}
+    <li data-slot="toaster-clear-all">
+      <Button
+        type="button"
+        variant="link"
+        size="sm"
+        class="bg-background hover:bg-background rounded-none px-2"
+        data-toaster-clear
+      >
+        {clearAllLabel}
+      </Button>
+    </li>
+  </ol>
+</div>
+
+<style is:global>
+  /*
+   * Stack geometry on top of @data-slot/toast's tokens (--toast-index,
+   * --toast-offset, --toast-initial-height, --toast-front-height,
+   * --toast-count, --toast-expanded-stack-size). D161, D164, D167: the newest
+   * in front, two more peeking out 10px below it, 5% smaller each and blank;
+   * unfurled, one under the other 12px apart at their own heights; 300ms.
+   */
+  @layer components {
+    [data-slot="toast-viewport"] {
+      --toast-gap: 12px;
+      --toast-collapsed-peek: 10px;
+      --toaster-slide: 2rem;
+      --toaster-band: 0px;
+      --toaster-lift: 0px;
+      position: fixed;
+      z-index: 50;
+      top: calc(
+        var(--toaster-top, 41px) + var(--toaster-offset, 0.5rem) -
+          var(--toaster-lift)
+      );
+      right: calc(
+        var(--toaster-right, 1rem) + var(--data-slot-scrollbar-width, 0px)
+      );
+      width: min(24rem, calc(100vw - 2 * var(--toaster-right, 1rem)));
+      height: calc(
+        var(--toast-front-height, 0px) +
+          min(var(--toast-count, 0) - 1, 2) * var(--toast-collapsed-peek)
+      );
+      margin: 0;
+      padding: 0;
+      list-style: none;
+      transition:
+        top 300ms ease-out,
+        height 300ms ease-out;
+    }
+    @media (min-width: 48rem) {
+      [data-slot="toast-viewport"] {
+        --toaster-right: 1.5rem;
+      }
+    }
+    [data-slot="toast-viewport"][data-expanded] {
+      height: calc(
+        var(--toast-expanded-stack-size, 0px) + var(--toaster-band)
+      );
+    }
+    /* D170–D172 — two or more, unfurled: room for Clear all, flush under the bar. */
+    [data-slot="toast-viewport"][data-expanded]:has(
+        > [data-slot="toast-item"][data-front="false"][data-removed="false"]
+      ) {
+      --toaster-band: 2rem;
+      --toaster-lift: var(--toaster-offset, 0.5rem);
+    }
+    [data-slot="toaster-clear-all"] {
+      display: none;
+      position: absolute;
+      top: 0;
+      right: 0;
+      z-index: 1000;
+    }
+    [data-slot="toast-viewport"][data-expanded]:has(
+        > [data-slot="toast-item"][data-front="false"][data-removed="false"]
+      )
+      > [data-slot="toaster-clear-all"] {
+      display: block;
+    }
+
+    [data-slot="toast-viewport"] > [data-slot="toast-item"] {
+      --toast-y: min(
+        calc(var(--toast-index, 0) * var(--toast-collapsed-peek)),
+        calc(2 * var(--toast-collapsed-peek))
+      );
+      --toast-s: calc(1 - min(var(--toast-index, 0), 3) * 0.05);
+      position: absolute;
+      inset-inline: 0;
+      top: 0;
+      height: var(--toast-initial-height, auto);
+      transform-origin: bottom;
+      translate: var(--toaster-slide) var(--toast-y);
+      scale: var(--toast-s);
+      opacity: 0;
+      transition:
+        translate 300ms ease-out,
+        scale 300ms ease-out,
+        opacity 300ms ease-out,
+        height 300ms ease-out;
+    }
+    [data-slot="toast-viewport"] > [data-slot="toast-item"][data-expanded="true"] {
+      --toast-y: calc(var(--toast-offset, 0px) + var(--toaster-band));
+      --toast-s: 1;
+    }
+    [data-slot="toast-viewport"]
+      > [data-slot="toast-item"][data-expanded="false"][data-front="false"] {
+      height: var(--toast-front-height);
+    }
+    /* In: slid home; a fourth one and beyond stay out of sight while stacked. */
+    [data-slot="toast-viewport"] > [data-slot="toast-item"][data-mounted="true"] {
+      translate: 0 var(--toast-y);
+      opacity: clamp(0, 3 - var(--toast-index, 0), 1);
+    }
+    [data-slot="toast-viewport"]
+      > [data-slot="toast-item"][data-mounted="true"][data-expanded="true"] {
+      opacity: 1;
+    }
+    [data-slot="toast-viewport"] > [data-slot="toast-item"][data-swiping="true"] {
+      translate: var(--toast-swipe-amount-x, 0px) var(--toast-y);
+      transition: none;
+    }
+    /* Out: back to the right, fading (or off where it was swiped). */
+    [data-slot="toast-viewport"]
+      > [data-slot="toast-item"][data-mounted][data-removed="true"],
+    [data-slot="toast-viewport"]
+      > [data-slot="toast-item"][data-mounted][data-visible="false"] {
+      translate: var(--toaster-slide) var(--toast-y);
+      opacity: 0;
+    }
+    [data-slot="toast-viewport"]
+      > [data-slot="toast-item"][data-mounted][data-swipe-out="true"] {
+      translate: var(--toast-swipe-end-x, 0px) var(--toast-y);
+    }
+    /* Stacked: the ones behind are blank. */
+    [data-slot="toast-viewport"]
+      > [data-slot="toast-item"]
+      :is([data-slot="toast-body"], [data-slot="toast-close"]) {
+      transition: opacity 300ms ease-out;
+    }
+    [data-slot="toast-viewport"]
+      > [data-slot="toast-item"][data-expanded="false"][data-front="false"]
+      :is([data-slot="toast-body"], [data-slot="toast-close"]) {
+      opacity: 0;
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      [data-slot="toast-viewport"] {
+        --toaster-slide: 0px;
+        transition: none;
+      }
+      [data-slot="toast-viewport"] > [data-slot="toast-item"] {
+        transition: opacity 150ms linear;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { createToast } from "@data-slot/toast";
+
+  /** D164 — the attention effect starts once the slide in (300ms) is done. */
+  const IN_MS = 300;
+  /** D175 — three 700ms ripples (or seven 75ms swings each way). */
+  const ATTENTION_MS = 2400;
+  const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
+
+  document.querySelectorAll<HTMLElement>('[data-slot="toast"]').forEach((root) => {
+    if (root.dataset.toasterReady === "true") return;
+    const viewport = root.querySelector<HTMLElement>('[data-slot="toast-viewport"]');
+    if (!viewport) return;
+
+    const item = (id: string) =>
+      viewport.querySelector<HTMLElement>(
+        `[data-slot="toast-item"][data-id="${CSS.escape(id)}"]`,
+      );
+
+    const controller = createToast(root, {
+      onShow: (id) => {
+        // Only the newest draws the eye.
+        viewport
+          .querySelectorAll<HTMLElement>('[data-slot="toast-item"][data-attention]')
+          .forEach((el) => el.removeAttribute("data-attention"));
+        if (reducedMotion.matches) return;
+        window.setTimeout(() => {
+          const el = item(id);
+          if (!el || el.dataset.state !== "open" || el.dataset.front !== "true") return;
+          el.dataset.attention = "on";
+          window.setTimeout(() => el.removeAttribute("data-attention"), ATTENTION_MS);
+        }, IN_MS);
+      },
+    });
+
+    viewport
+      .querySelector<HTMLElement>("[data-toaster-clear]")
+      ?.addEventListener("click", () => controller.dismissAll());
+
+    root.dataset.toasterReady = "true";
+    root.dispatchEvent(new CustomEvent("toaster:ready"));
+  });
+</script>

package/src/components/toast/index.ts

@@ -0,0 +1,9 @@
+export { default as Toast } from "./Toast.astro";
+export { default as Toaster } from "./Toaster.astro";
+export { toast } from "../../lib/toast";
+export type {
+  ToastKind,
+  ToastShowOptions,
+  ToastUpdateOptions,
+  ToastActionOptions,
+} from "../../lib/toast";

package/src/components/toggle/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to the `Toggle` component will be documented in this file.
 
+## Date 15th Oct 2026
+## Workspace selection handover (C12)
+
+- Added `variant="ghost"`: no pressed background (the content shows the state, e.g. a filled `favorite` star); the normal hover background on hover, pressed or not. `default` and `outline` are unchanged, since `ToggleGroup` shows its selection with the pressed background.
+- Storybook: "Ghost" preview with the favourite star.
+
+
 ## 2026-09-18 — Figma alignment (ClickLearn Lightning Design Library, node `5455-19034`)
 
 Figma documents Toggle across four pages: Contents (Default, Clean, Tail Icon, Complex), States (Default, Hover, Pressed, Focus Default, Focus Pressed, Disabled), and Sizes (Small 28px, Medium 32px, Large 36px). Sizing/variant fixes live in the shared `toggleVariants` (`packages/ui/src/lib/toggle-shared.ts`), used by both `Toggle` and `ToggleGroup`.

package/src/lib/command-search.ts

@@ -0,0 +1,73 @@
+/**
+ * Helpers for the `CommandSearch` component
+ * (`@cl-light-ds/ui/components/command-search`).
+ *
+ * ```ts
+ * import { setCommandSearchResults } from "@cl-light-ds/ui/lib/command-search";
+ *
+ * // mode="remote": search on your side, then hand the results back.
+ * palette.addEventListener("command-search:search", async (event) => {
+ *   const { query } = event.detail;
+ *   setCommandSearchResults(palette, await api.search(query), { query });
+ * });
+ * ```
+ */
+
+export interface CommandSearchResultItem {
+  /** Unique value, sent with `command-search:select`. */
+  value: string;
+  /** The row's text. */
+  label: string;
+  /** Muted text on the right, e.g. the workspace it is in. */
+  description?: string;
+  /** Navigate here when chosen. */
+  href?: string;
+  disabled?: boolean;
+}
+
+export interface CommandSearchResultGroup {
+  heading: string;
+  items: CommandSearchResultItem[];
+  /** Total matches, when more exist than `items` holds. Defaults to `items.length`. */
+  count?: number;
+}
+
+type Target = string | HTMLElement | undefined;
+
+const findRoot = (target: Target): HTMLElement | null => {
+  if (typeof document === "undefined") return null;
+  if (target instanceof HTMLElement) return target;
+  if (typeof target === "string") return document.getElementById(target);
+  return document.querySelector<HTMLElement>("[data-command-search]");
+};
+
+/** Open the palette (empty, focused). Defaults to the first on the page. */
+export function openCommandSearch(target?: Target) {
+  findRoot(target)?.dispatchEvent(
+    new CustomEvent("dialog:set", { detail: { open: true } }),
+  );
+}
+
+/** Close the palette. */
+export function closeCommandSearch(target?: Target) {
+  findRoot(target)?.dispatchEvent(
+    new CustomEvent("dialog:set", { detail: { open: false } }),
+  );
+}
+
+/**
+ * End a search in `mode="remote"`: render these groups as the results (or,
+ * with no groups, keep the rows you have put in the list yourself). `query`
+ * guards against stale answers: results for an older query are ignored.
+ */
+export function setCommandSearchResults(
+  target: Target,
+  groups?: CommandSearchResultGroup[],
+  options: { query?: string } = {},
+) {
+  findRoot(target)?.dispatchEvent(
+    new CustomEvent("command-search:results", {
+      detail: { groups, query: options.query },
+    }),
+  );
+}