@cl-light-ds/ui 0.2.0 → 0.3.0

package/src/components/organisms/lightning-sidebar-nav/SidebarNavUsage.astro

@@ -0,0 +1,78 @@
+---
+/**
+ * @component SidebarNavUsage
+ * @title Sidebar Nav Usage
+ * @description Plan usage rows (label … used / limit) and an optional full-width upgrade CTA, pinned to the bottom of the sidebar.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=7514-198
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * <SidebarNavUsage
+ *   usage={[{ id: "recordings", label: "Recordings created", used: 5, limit: 5 }]}
+ *   upgrade={{ label: "Upgrade to Pro", href: "/billing" }}
+ * />
+ * ```
+ */
+
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import { Button } from "../../button";
+import { Separator } from "../../separator";
+import type { SidebarNavUpgrade, SidebarNavUsageMetric } from "./types";
+
+interface Props {
+  usage?: SidebarNavUsageMetric[];
+  upgrade?: SidebarNavUpgrade | null;
+  class?: string;
+}
+
+const {
+  usage = [],
+  upgrade = null,
+  class: className = "",
+} = Astro.props as Props;
+
+const formatValue = ({ used, limit }: SidebarNavUsageMetric) =>
+  limit === null ? `${used} / Unlimited` : `${used} / ${limit}`;
+---
+
+{
+  (usage.length > 0 || upgrade) && (
+    <div
+      data-slot="sidebar-nav-usage"
+      class={cn("flex flex-col gap-3", className)}
+    >
+      <Separator class="my-2" />
+      {usage.length > 0 && (
+        <dl class="flex flex-col gap-2 text-xs leading-4">
+          {usage.map((metric) => (
+            <div
+              data-slot="sidebar-nav-usage-metric"
+              data-at-limit={
+                metric.limit !== null && metric.used >= metric.limit
+                  ? ""
+                  : undefined
+              }
+              class="flex items-baseline justify-between gap-2"
+            >
+              <dt class="text-muted-foreground truncate">{metric.label}</dt>
+              <dd class="text-foreground shrink-0 font-semibold whitespace-nowrap">
+                {formatValue(metric)}
+              </dd>
+            </div>
+          ))}
+        </dl>
+      )}
+      {upgrade && (
+        <Button
+          as="a"
+          href={upgrade.href}
+          size="sm"
+          class="w-full font-semibold"
+        >
+          {upgrade.label}
+        </Button>
+      )}
+    </div>
+  )
+}

package/src/components/organisms/lightning-sidebar-nav/SidebarNavWorkspaceAvatar.astro

@@ -0,0 +1,46 @@
+---
+/**
+ * @component SidebarNavWorkspaceAvatar
+ * @description 24px workspace avatar: image when `avatarUrl` is set, else initials, else the user-round icon on primary.
+ */
+
+import { UserRound } from "@lucide/astro";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import { Avatar, AvatarFallback, AvatarImage } from "../../avatar";
+import type { SidebarNavWorkspace } from "./types";
+
+interface Props {
+  workspace: SidebarNavWorkspace;
+  class?: string;
+  slot?: string;
+}
+
+const { workspace, class: className = "", ...rest } = Astro.props as Props;
+
+const variant = workspace.avatarUrl
+  ? "image"
+  : workspace.initials
+    ? "initials"
+    : "icon";
+---
+
+<Avatar
+  {...rest}
+  size="sm"
+  variant={variant}
+  icon={variant === "icon" ? UserRound : undefined}
+  class={cn(
+    variant === "icon" &&
+      "bg-primary [&_[data-slot=avatar-icon]]:text-primary-foreground",
+    className,
+  )}
+>
+  {workspace.avatarUrl && <AvatarImage src={workspace.avatarUrl} alt="" />}
+  {
+    !workspace.avatarUrl && workspace.initials && (
+      <AvatarFallback class="bg-primary text-primary-foreground">
+        {workspace.initials}
+      </AvatarFallback>
+    )
+  }
+</Avatar>

package/src/components/organisms/lightning-sidebar-nav/SidebarNavWorkspaceSwitcher.astro

@@ -0,0 +1,130 @@
+---
+/**
+ * @component SidebarNavWorkspaceSwitcher
+ * @title Sidebar Nav Workspace Switcher
+ * @description Current workspace (avatar + name) at the top of the sidebar. With `workspaces`, it opens a DropdownMenu to switch.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=7514-183
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * <SidebarNavWorkspaceSwitcher
+ *   workspace={{ id: "nw", name: "Northwind Group" }}
+ *   workspaces={[{ id: "nw", name: "Northwind Group" }, { id: "ct", name: "Contoso", href: "/w/ct" }]}
+ * />
+ * ```
+ *
+ * ### Events
+ *
+ * | Event | Detail | Description |
+ * |-------|--------|-------------|
+ * | `sidebar-nav:workspace-change` | `{ id: string }` | Bubbles, cancelable. Fired when a workspace is picked. If the workspace has an `href` and the event isn't cancelled, the browser navigates there. |
+ */
+
+import { ChevronsUpDown } from "@lucide/astro";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from "../../dropdown-menu";
+import { Separator } from "../../separator";
+import type { SidebarNavWorkspace } from "./types";
+import SidebarNavWorkspaceAvatar from "./SidebarNavWorkspaceAvatar.astro";
+
+interface Props {
+  workspace: SidebarNavWorkspace;
+  /** Options in the switcher menu. Empty = static display, no menu. */
+  workspaces?: SidebarNavWorkspace[];
+  /** Heading shown at the top of the menu. */
+  menuLabel?: string;
+  class?: string;
+}
+
+const {
+  workspace,
+  workspaces = [],
+  menuLabel = "Workspaces",
+  class: className = "",
+} = Astro.props as Props;
+
+const hasMenu = workspaces.length > 0;
+const rowClass =
+  "flex w-full items-center gap-2 overflow-hidden rounded-lg p-2 text-left text-sm leading-5 font-medium text-foreground";
+---
+
+<div data-slot="sidebar-nav-workspace" class={cn("flex flex-col", className)}>
+  {
+    hasMenu ? (
+      <DropdownMenu
+        class="block w-full"
+        defaultValue={workspace.id}
+        highlightItemOnHover
+      >
+        <DropdownMenuTrigger asChild class="flex w-full">
+          <button
+            type="button"
+            aria-label={`Switch workspace, current: ${workspace.name}`}
+            class={cn(
+              rowClass,
+              "outline-none transition-colors hover:bg-muted focus-visible:ring-1 focus-visible:ring-sidebar-ring focus-visible:ring-inset",
+            )}
+          >
+            <SidebarNavWorkspaceAvatar workspace={workspace} />
+            <span class="min-w-0 flex-1 truncate">{workspace.name}</span>
+            <ChevronsUpDown
+              aria-hidden="true"
+              class="text-foreground size-4 shrink-0"
+            />
+          </button>
+        </DropdownMenuTrigger>
+        {/* --anchor-width isn't set by the runtime; match the 238px inner width of the 270px shell. */}
+        <DropdownMenuContent align="start" class="w-[238px]">
+          <DropdownMenuLabel>{menuLabel}</DropdownMenuLabel>
+          <DropdownMenuRadioGroup>
+            {workspaces.map((option) => (
+              <DropdownMenuRadioItem
+                value={option.id}
+                data-href={option.href}
+                avatar
+              >
+                <SidebarNavWorkspaceAvatar slot="avatar" workspace={option} />
+                {option.name}
+              </DropdownMenuRadioItem>
+            ))}
+          </DropdownMenuRadioGroup>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    ) : (
+      <div class={rowClass}>
+        <SidebarNavWorkspaceAvatar workspace={workspace} />
+        <span class="min-w-0 flex-1 truncate">{workspace.name}</span>
+      </div>
+    )
+  }
+  <Separator class="my-2" />
+</div>
+
+<script>
+  document
+    .querySelectorAll<HTMLElement>('[data-slot="sidebar-nav-workspace"]')
+    .forEach((root) => {
+      root.addEventListener("dropdown-menu:select", (event) => {
+        const { value, item } = (
+          event as CustomEvent<{ value: string; item: HTMLElement | null }>
+        ).detail;
+        const href = item?.dataset.href;
+        const proceed = root.dispatchEvent(
+          new CustomEvent("sidebar-nav:workspace-change", {
+            bubbles: true,
+            cancelable: true,
+            detail: { id: value },
+          }),
+        );
+        if (proceed && href) window.location.assign(href);
+      });
+    });
+</script>

package/src/components/organisms/lightning-sidebar-nav/icons.ts

@@ -0,0 +1,46 @@
+import {
+  BookOpen,
+  ChartColumn,
+  CircleHelp,
+  FileText,
+  Folder,
+  House,
+  Library,
+  Palette,
+  Settings,
+  Trash2,
+  UserRound,
+  Users,
+  Video,
+  type AstroComponent,
+} from "@lucide/astro";
+
+/**
+ * String → Lucide icon registry, so backend data can name icons without
+ * importing components. Extend this map when a new destination needs an icon.
+ */
+export const sidebarNavIcons = {
+  "book-open": BookOpen,
+  "chart-column": ChartColumn,
+  "circle-help": CircleHelp,
+  "file-text": FileText,
+  folder: Folder,
+  house: House,
+  library: Library,
+  palette: Palette,
+  settings: Settings,
+  "trash-2": Trash2,
+  "user-round": UserRound,
+  users: Users,
+  video: Video,
+} satisfies Record<string, AstroComponent>;
+
+export type SidebarNavIconName = keyof typeof sidebarNavIcons;
+
+export const resolveSidebarNavIcon = (
+  icon: SidebarNavIconName | AstroComponent | undefined,
+): AstroComponent | undefined => {
+  if (!icon) return undefined;
+  if (typeof icon === "string") return sidebarNavIcons[icon];
+  return icon;
+};

package/src/components/organisms/lightning-sidebar-nav/index.ts

@@ -0,0 +1,18 @@
+export { default as LightningSidebarNav } from "./LightningSidebarNav.astro";
+export { default as SidebarNav } from "./SidebarNav.astro";
+export { default as SidebarNavGroup } from "./SidebarNavGroup.astro";
+export { default as SidebarNavItem } from "./SidebarNavItem.astro";
+export { sidebarNavItemVariants } from "./SidebarNavItem.astro";
+export { default as SidebarNavProBadge } from "./SidebarNavProBadge.astro";
+export { default as SidebarNavSection } from "./SidebarNavSection.astro";
+export { default as SidebarNavSkeleton } from "./SidebarNavSkeleton.astro";
+export { default as SidebarNavSubItem } from "./SidebarNavSubItem.astro";
+export { default as SidebarNavUsage } from "./SidebarNavUsage.astro";
+export { default as SidebarNavWorkspaceAvatar } from "./SidebarNavWorkspaceAvatar.astro";
+export { default as SidebarNavWorkspaceSwitcher } from "./SidebarNavWorkspaceSwitcher.astro";
+export {
+  resolveSidebarNavIcon,
+  sidebarNavIcons,
+  type SidebarNavIconName,
+} from "./icons";
+export * from "./types";

package/src/components/organisms/lightning-sidebar-nav/types.ts

@@ -0,0 +1,77 @@
+import type { AstroComponent } from "@lucide/astro";
+import type { SidebarNavIconName } from "./icons";
+
+/**
+ * Backend contract for the Lightning Sidebar Nav.
+ * Everything except `AstroComponent` icons is JSON-serialisable, so a page can
+ * pass an API response straight into `<LightningSidebarNav />`.
+ */
+
+/** Registry key (from backend data) or a Lucide component (hand-authored markup). */
+export type SidebarNavIcon = SidebarNavIconName | AstroComponent;
+
+/** A top-level destination (Figma: Group Item / Variant=Default). */
+export interface SidebarNavLink {
+  id: string;
+  label: string;
+  href: string;
+  icon?: SidebarNavIcon;
+  /** Shows the Accent/Small "Pro" badge. The link still navigates. */
+  pro?: boolean;
+  disabled?: boolean;
+}
+
+/** A destination nested under a group (Figma: Group item / .Nav Item). */
+export interface SidebarNavSubLink {
+  id: string;
+  label: string;
+  href: string;
+  pro?: boolean;
+}
+
+/** An expandable parent (Figma: Group Item / Variant=Collapsed | Expanded). */
+export interface SidebarNavGroup {
+  id: string;
+  label: string;
+  icon?: SidebarNavIcon;
+  pro?: boolean;
+  children: SidebarNavSubLink[];
+  /** Force the initial open state. Groups with an active child open automatically. */
+  defaultOpen?: boolean;
+}
+
+export type SidebarNavEntry = SidebarNavLink | SidebarNavGroup;
+
+/** A block of entries, optionally headed by a category label (Figma: Variant=Category). */
+export interface SidebarNavSectionData {
+  id: string;
+  label?: string;
+  items: SidebarNavEntry[];
+}
+
+export interface SidebarNavWorkspace {
+  id: string;
+  name: string;
+  avatarUrl?: string;
+  initials?: string;
+  /** When set, choosing this workspace navigates here. Otherwise `sidebar-nav:workspace-change` fires. */
+  href?: string;
+}
+
+export interface SidebarNavUsageMetric {
+  id: string;
+  label: string;
+  used: number;
+  /** `null` means unlimited. */
+  limit: number | null;
+}
+
+export interface SidebarNavUpgrade {
+  label: string;
+  href: string;
+}
+
+export const isSidebarNavGroup = (
+  entry: SidebarNavEntry,
+): entry is SidebarNavGroup =>
+  Array.isArray((entry as SidebarNavGroup).children);

package/src/components/popover/CHANGELOG.md

@@ -1,20 +1,20 @@
-# Changelog
-
-All notable changes to the `Popover` component family (`Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverHeader`, `PopoverTitle`, `PopoverDescription`, `PopoverClose`) are documented in this file.
-
-## 2026-09-18 — Figma alignment (ClickLearn Lightning Design Library, node `5548-11795`)
-
-Figma documents Popover across two pages: Items (the trigger button's Default/Hover/Pressed/Focus/Disabled states) and the expanded popover (12 Side × Alignment combinations, all sharing the same panel styling).
-
-### Fixed
-
-- Added the missing `@figmaUrl` (this component never had one).
-- `PopoverContent`: replaced the `ring-1 ring-foreground/10` border approximation with a real `border border-border`, and `shadow-md` → `shadow-lg` — matching Figma's tokens (`border` = `#e4e4e7`, a named `shadow-lg`), same category of fix already made to `DialogContent`/`HoverCardContent`.
-- `PopoverContent`: removed a dead, redundant raw class string duplicating most of `contentVariants()` — same class of bug already fixed on `HoverCardContent`. It also carried two genuinely dead selectors, `data-[side=inline-start]:...`/`data-[side=inline-end]:...`, which the underlying `@data-slot/popover` behavior library never actually sets (confirmed by checking its source — it only ever sets physical `top`/`bottom`/`left`/`right`, matching the component's own `side` prop type). Also removed the dead `rounded-md` (a later `rounded-lg` always won anyway) and a `duration-100`/`duration-150` conflict (150ms was already winning).
-- `PopoverHeader`: `gap-1` (4px) → `gap-0.5` (2px) between `PopoverTitle`/`PopoverDescription`, matching Figma's measured 2px gap.
-- `PopoverTrigger`: now defaults to `variant="outline"` instead of inheriting `Button`'s own `default` (solid primary) variant — Figma's Default trigger state is a bordered/light button, matching outline exactly, and every existing usage example already passed `variant="outline"` explicitly. Visually a no-op for existing usages; makes new usages match the documented default without needing to repeat the prop.
-
-### Notes
-
-- The trigger's Hover/Pressed/Focus/Disabled states are entirely `Button`'s own responsibility (`PopoverTrigger` just renders a `Button`) — already verified correct in earlier passes, no changes needed here.
-- `bg-popover`/`text-popover-foreground`, `p-4`, and `rounded-lg` already matched Figma's tokens exactly.
+# Changelog
+
+All notable changes to the `Popover` component family (`Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverHeader`, `PopoverTitle`, `PopoverDescription`, `PopoverClose`) are documented in this file.
+
+## 2026-09-18 — Figma alignment (ClickLearn Lightning Design Library, node `5548-11795`)
+
+Figma documents Popover across two pages: Items (the trigger button's Default/Hover/Pressed/Focus/Disabled states) and the expanded popover (12 Side × Alignment combinations, all sharing the same panel styling).
+
+### Fixed
+
+- Added the missing `@figmaUrl` (this component never had one).
+- `PopoverContent`: replaced the `ring-1 ring-foreground/10` border approximation with a real `border border-border`, and `shadow-md` → `shadow-lg` — matching Figma's tokens (`border` = `#e4e4e7`, a named `shadow-lg`), same category of fix already made to `DialogContent`/`HoverCardContent`.
+- `PopoverContent`: removed a dead, redundant raw class string duplicating most of `contentVariants()` — same class of bug already fixed on `HoverCardContent`. It also carried two genuinely dead selectors, `data-[side=inline-start]:...`/`data-[side=inline-end]:...`, which the underlying `@data-slot/popover` behavior library never actually sets (confirmed by checking its source — it only ever sets physical `top`/`bottom`/`left`/`right`, matching the component's own `side` prop type). Also removed the dead `rounded-md` (a later `rounded-lg` always won anyway) and a `duration-100`/`duration-150` conflict (150ms was already winning).
+- `PopoverHeader`: `gap-1` (4px) → `gap-0.5` (2px) between `PopoverTitle`/`PopoverDescription`, matching Figma's measured 2px gap.
+- `PopoverTrigger`: now defaults to `variant="outline"` instead of inheriting `Button`'s own `default` (solid primary) variant — Figma's Default trigger state is a bordered/light button, matching outline exactly, and every existing usage example already passed `variant="outline"` explicitly. Visually a no-op for existing usages; makes new usages match the documented default without needing to repeat the prop.
+
+### Notes
+
+- The trigger's Hover/Pressed/Focus/Disabled states are entirely `Button`'s own responsibility (`PopoverTrigger` just renders a `Button`) — already verified correct in earlier passes, no changes needed here.
+- `bg-popover`/`text-popover-foreground`, `p-4`, and `rounded-lg` already matched Figma's tokens exactly.