@cl-light-ds/ui 0.2.0 → 0.3.0

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

@@ -0,0 +1,176 @@
+---
+/**
+ * @component LightningSidebarNav
+ * @title Lightning Sidebar Nav
+ * @description Organism. The full workspace sidebar rendered from JSON-serialisable backend data: workspace switcher, navigation sections, footer links, usage and upgrade CTA.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=7513-60
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { LightningSidebarNav } from '@cl-light-ds/ui/components/organisms/lightning-sidebar-nav';
+ * const nav = await fetch('/api/navigation').then((r) => r.json());
+ * ---
+ *
+ * <LightningSidebarNav {...nav} currentPath={Astro.url.pathname} />
+ * ```
+ *
+ * Active item: `activeId` wins; otherwise the link whose `href` is the longest
+ * segment-prefix of `currentPath` (defaults to `Astro.url.pathname`).
+ * Groups containing the active link open automatically.
+ */
+
+import type { HTMLAttributes } from "astro/types";
+import { Separator } from "../../separator";
+import {
+  isSidebarNavGroup,
+  type SidebarNavLink,
+  type SidebarNavSectionData,
+  type SidebarNavSubLink,
+  type SidebarNavUpgrade,
+  type SidebarNavUsageMetric,
+  type SidebarNavWorkspace,
+} from "./types";
+import SidebarNav from "./SidebarNav.astro";
+import SidebarNavGroup from "./SidebarNavGroup.astro";
+import SidebarNavItem from "./SidebarNavItem.astro";
+import SidebarNavSection from "./SidebarNavSection.astro";
+import SidebarNavSkeleton from "./SidebarNavSkeleton.astro";
+import SidebarNavSubItem from "./SidebarNavSubItem.astro";
+import SidebarNavUsage from "./SidebarNavUsage.astro";
+import SidebarNavWorkspaceSwitcher from "./SidebarNavWorkspaceSwitcher.astro";
+
+interface Props extends HTMLAttributes<"nav"> {
+  workspace: SidebarNavWorkspace;
+  workspaces?: SidebarNavWorkspace[];
+  sections: SidebarNavSectionData[];
+  footerItems?: SidebarNavLink[];
+  currentPath?: string;
+  activeId?: string;
+  usage?: SidebarNavUsageMetric[];
+  upgrade?: SidebarNavUpgrade | null;
+  loading?: boolean;
+  class?: string;
+}
+
+const {
+  workspace,
+  workspaces = [],
+  sections,
+  footerItems = [],
+  currentPath = Astro.url.pathname,
+  activeId: activeIdProp,
+  usage = [],
+  upgrade = null,
+  loading = false,
+  ...rest
+} = Astro.props as Props;
+
+const allLinks: (SidebarNavLink | SidebarNavSubLink)[] = [
+  ...sections.flatMap((section) =>
+    section.items.flatMap((entry) =>
+      isSidebarNavGroup(entry) ? entry.children : [entry],
+    ),
+  ),
+  ...footerItems,
+];
+
+const stripPath = (value: string) =>
+  value.split(/[?#]/)[0]!.replace(/(.)\/+$/, "$1");
+
+const matches = (href: string, path: string) => {
+  const target = stripPath(href);
+  if (target === path) return true;
+  return target !== "/" && path.startsWith(`${target}/`);
+};
+
+const resolveActiveId = () => {
+  if (activeIdProp) return activeIdProp;
+  const path = stripPath(currentPath);
+  return allLinks
+    .filter((link) => matches(link.href, path))
+    .sort((a, b) => stripPath(b.href).length - stripPath(a.href).length)[0]?.id;
+};
+
+const activeId = resolveActiveId();
+---
+
+<SidebarNav {...rest} aria-busy={loading ? "true" : undefined}>
+  <SidebarNavWorkspaceSwitcher
+    slot="header"
+    workspace={workspace}
+    workspaces={workspaces}
+  />
+
+  {
+    loading ? (
+      <SidebarNavSkeleton usage={usage.length > 0 || Boolean(upgrade)} />
+    ) : (
+      <Fragment>
+        <div class="flex flex-col gap-3">
+          {sections.map((section) => (
+            <SidebarNavSection label={section.label}>
+              {section.items.map((entry) =>
+                isSidebarNavGroup(entry) ? (
+                  <SidebarNavGroup
+                    label={entry.label}
+                    icon={entry.icon}
+                    pro={entry.pro}
+                    open={
+                      entry.defaultOpen ??
+                      entry.children.some((child) => child.id === activeId)
+                    }
+                  >
+                    {entry.children.map((child) => (
+                      <SidebarNavSubItem
+                        href={child.href}
+                        label={child.label}
+                        pro={child.pro}
+                        active={child.id === activeId}
+                        data-nav-id={child.id}
+                      />
+                    ))}
+                  </SidebarNavGroup>
+                ) : (
+                  <SidebarNavItem
+                    href={entry.href}
+                    label={entry.label}
+                    icon={entry.icon}
+                    pro={entry.pro}
+                    disabled={entry.disabled}
+                    active={entry.id === activeId}
+                    data-nav-id={entry.id}
+                  />
+                ),
+              )}
+            </SidebarNavSection>
+          ))}
+          <Separator class="my-2" />
+        </div>
+
+        {footerItems.length > 0 && (
+          <SidebarNavSection density="compact">
+            {footerItems.map((item) => (
+              <SidebarNavItem
+                href={item.href}
+                label={item.label}
+                icon={item.icon}
+                pro={item.pro}
+                disabled={item.disabled}
+                active={item.id === activeId}
+                data-nav-id={item.id}
+              />
+            ))}
+          </SidebarNavSection>
+        )}
+      </Fragment>
+    )
+  }
+
+  {
+    !loading && (
+      <SidebarNavUsage slot="footer" usage={usage} upgrade={upgrade} />
+    )
+  }
+</SidebarNav>

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

@@ -0,0 +1,50 @@
+---
+/**
+ * @component SidebarNav
+ * @title Sidebar Nav
+ * @description The 270px sidebar shell. `header` slot (workspace switcher), a scrollable default slot (sections) and a `footer` slot (usage / upgrade).
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=7514-711
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * <SidebarNav aria-label="Workspace navigation">
+ *   <SidebarNavWorkspaceSwitcher slot="header" workspace={workspace} />
+ *   <SidebarNavSection>…</SidebarNavSection>
+ *   <SidebarNavUsage slot="footer" usage={usage} />
+ * </SidebarNav>
+ * ```
+ */
+
+import type { HTMLAttributes } from "astro/types";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+
+interface Props extends HTMLAttributes<"nav"> {
+  class?: string;
+}
+
+const {
+  class: className = "",
+  "aria-label": ariaLabel = "Workspace navigation",
+  ...rest
+} = Astro.props as Props;
+---
+
+<nav
+  {...rest}
+  aria-label={ariaLabel}
+  data-slot="sidebar-nav"
+  class={cn(
+    "bg-sidebar text-sidebar-foreground border-sidebar-border flex h-full w-[270px] shrink-0 flex-col overflow-hidden border-r p-4",
+    className,
+  )}
+>
+  <slot name="header" />
+  <div
+    data-slot="sidebar-nav-body"
+    class="flex min-h-0 flex-1 flex-col justify-between overflow-y-auto"
+  >
+    <slot />
+  </div>
+  <slot name="footer" />
+</nav>

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

@@ -0,0 +1,74 @@
+---
+/**
+ * @component SidebarNavGroup
+ * @title Sidebar Nav Group
+ * @description An expandable parent row (`<li>`) built on Collapsible. Holds SidebarNavSubItem children; the chevron flips when open.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=7514-258
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * <SidebarNavGroup label="Customization" icon="palette" open>
+ *   <SidebarNavSubItem href="/customization/templates" label="Templates" />
+ *   <SidebarNavSubItem href="/customization/branding" label="Branding" active />
+ * </SidebarNavGroup>
+ * ```
+ */
+
+import { ChevronDown } from "@lucide/astro";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "../../collapsible";
+import { resolveSidebarNavIcon } from "./icons";
+import type { SidebarNavIcon } from "./types";
+import SidebarNavProBadge from "./SidebarNavProBadge.astro";
+
+interface Props {
+  label: string;
+  icon?: SidebarNavIcon;
+  /** Initial open state. */
+  open?: boolean;
+  pro?: boolean;
+  class?: string;
+}
+
+const {
+  label,
+  icon,
+  open = false,
+  pro = false,
+  class: className = "",
+} = Astro.props as Props;
+
+const Icon = resolveSidebarNavIcon(icon);
+---
+
+<li data-slot="sidebar-nav-group" class={cn("flex flex-col", className)}>
+  <Collapsible open={open} class="flex flex-col">
+    <CollapsibleTrigger
+      class={cn(
+        "flex w-full items-center gap-2 rounded-lg p-2 text-left text-sm leading-5 font-medium text-muted-foreground outline-none transition-colors",
+        "group-data-[state=open]/collapsible:text-foreground",
+        "hover:bg-muted hover:font-semibold hover:text-foreground",
+        "focus-visible:text-foreground focus-visible:ring-1 focus-visible:ring-sidebar-ring focus-visible:ring-inset",
+        "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg]:size-4",
+      )}
+    >
+      {Icon && <Icon aria-hidden="true" />}
+      <span class="min-w-0 flex-1 truncate">{label}</span>
+      {pro && <SidebarNavProBadge />}
+      <ChevronDown
+        aria-hidden="true"
+        class="transition-transform duration-200 group-data-[state=open]/collapsible:rotate-180 motion-reduce:transition-none"
+      />
+    </CollapsibleTrigger>
+    <CollapsibleContent>
+      <ul data-slot="sidebar-nav-group-content" class="flex flex-col px-2 pb-2">
+        <slot />
+      </ul>
+    </CollapsibleContent>
+  </Collapsible>
+</li>

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

@@ -0,0 +1,94 @@
+---
+/**
+ * @component SidebarNavItem
+ * @title Sidebar Nav Item
+ * @description One row (`<li>`) of the workspace sidebar: a 16px Lucide icon, a label and an optional Pro badge. Active is carried by an accent fill AND a semibold label, never by colour alone.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=7514-237
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { SidebarNavItem } from '@cl-light-ds/ui/components/organisms/lightning-sidebar-nav';
+ * ---
+ *
+ * <SidebarNavItem href="/recordings" icon="video" label="Recordings" active />
+ * ```
+ */
+
+import type { HTMLAttributes } from "astro/types";
+import { cva } from "class-variance-authority";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import { resolveSidebarNavIcon } from "./icons";
+import type { SidebarNavIcon } from "./types";
+import SidebarNavProBadge from "./SidebarNavProBadge.astro";
+
+type Props = Omit<HTMLAttributes<"a">, "href"> & {
+  /** Renders an `<a>` when set, otherwise a `<button>`. */
+  href?: string;
+  label: string;
+  icon?: SidebarNavIcon;
+  active?: boolean;
+  pro?: boolean;
+  disabled?: boolean;
+  class?: string;
+};
+
+const {
+  href,
+  label,
+  icon,
+  active = false,
+  pro = false,
+  disabled = false,
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+
+export const sidebarNavItemVariants = cva(
+  [
+    "group/sidebar-nav-item flex w-full items-center gap-2 rounded-lg p-2 text-left text-sm leading-5 font-medium outline-none transition-colors",
+    "focus-visible:ring-1 focus-visible:ring-sidebar-ring focus-visible:ring-inset",
+    "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&>svg]:size-4",
+  ],
+  {
+    variants: {
+      active: {
+        true: "bg-sidebar-accent font-semibold text-sidebar-accent-foreground",
+        false:
+          "text-muted-foreground hover:bg-muted hover:font-semibold hover:text-foreground focus-visible:text-foreground",
+      },
+      disabled: {
+        true: "pointer-events-none opacity-50",
+        false: "",
+      },
+    },
+    defaultVariants: { active: false, disabled: false },
+  },
+);
+
+const Icon = resolveSidebarNavIcon(icon);
+const Tag = href && !disabled ? "a" : "button";
+const classes = cn(sidebarNavItemVariants({ active, disabled }), className);
+---
+
+<li data-slot="sidebar-nav-item-wrapper" class="flex">
+  <Tag
+    {...rest}
+    data-slot="sidebar-nav-item"
+    data-active={active ? "" : undefined}
+    href={Tag === "a" ? href : undefined}
+    type={Tag === "button" ? "button" : undefined}
+    aria-current={active ? "page" : undefined}
+    aria-disabled={disabled ? "true" : undefined}
+    disabled={Tag === "button" && disabled ? true : undefined}
+    class={classes}
+  >
+    {Icon && <Icon aria-hidden="true" />}
+    <span data-slot="sidebar-nav-item-label" class="min-w-0 flex-1 truncate"
+      >{label}</span
+    >
+    {pro && <SidebarNavProBadge />}
+    <slot />
+  </Tag>
+</li>

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

@@ -0,0 +1,26 @@
+---
+/**
+ * @component SidebarNavProBadge
+ * @description The Accent/Small "Pro" badge with a zap tail icon, shown on Pro-gated destinations.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=7514-237
+ */
+
+import { Zap } from "@lucide/astro";
+import { Badge } from "../../badge";
+
+interface Props {
+  class?: string;
+}
+
+const { class: className = "" } = Astro.props as Props;
+---
+
+<Badge
+  variant="accent"
+  size="sm"
+  data-slot="sidebar-nav-pro-badge"
+  class={className}
+>
+  Pro
+  <Zap slot="tail-icon" aria-hidden="true" />
+</Badge>

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

@@ -0,0 +1,71 @@
+---
+/**
+ * @component SidebarNavSection
+ * @title Sidebar Nav Section
+ * @description A list of SidebarNavItem / SidebarNavGroup rows, optionally headed by an uppercase category label.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=7514-242
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * <SidebarNavSection label="Customization">
+ *   <SidebarNavItem href="/templates" icon="file-text" label="Templates" />
+ * </SidebarNavSection>
+ * ```
+ */
+
+import type { HTMLAttributes } from "astro/types";
+import { cva } from "class-variance-authority";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+
+interface Props extends HTMLAttributes<"div"> {
+  /** Category heading (Figma: Group Item / Variant=Category). */
+  label?: string;
+  /** `default` = 12px between rows (primary nav); `compact` = 2px (footer links). */
+  density?: "default" | "compact";
+  class?: string;
+}
+
+const {
+  label,
+  density = "default",
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+
+const listVariants = cva("flex flex-col", {
+  variants: {
+    density: {
+      default: "gap-3",
+      compact: "gap-0.5",
+    },
+  },
+  defaultVariants: { density: "default" },
+});
+
+// Unique per render so several sidebars can share a page.
+const headingId = label
+  ? `sidebar-nav-section-${Math.random().toString(36).slice(2, 10)}`
+  : undefined;
+---
+
+<div
+  {...rest}
+  data-slot="sidebar-nav-section"
+  class={cn("flex flex-col gap-2", className)}
+>
+  {
+    label && (
+      <p
+        id={headingId}
+        data-slot="sidebar-nav-section-label"
+        class="text-muted-foreground truncate px-2 text-xs leading-none font-semibold uppercase"
+      >
+        {label}
+      </p>
+    )
+  }
+  <ul aria-labelledby={headingId} class={listVariants({ density })}>
+    <slot />
+  </ul>
+</div>

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

@@ -0,0 +1,67 @@
+---
+/**
+ * @component SidebarNavSkeleton
+ * @title Sidebar Nav Skeleton
+ * @description Loading placeholders for the sidebar body (Figma: Sidebar / State=Skeleton). The workspace switcher stays real while navigation loads.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=7514-710
+ */
+
+import { Separator } from "../../separator";
+import { Skeleton } from "../../skeleton";
+
+interface Props {
+  /** Placeholder rows in the primary list. */
+  items?: number;
+  /** Placeholder rows in the footer list. */
+  footerItems?: number;
+  /** Render usage/upgrade placeholders. */
+  usage?: boolean;
+}
+
+const { items = 5, footerItems = 2, usage = true } = Astro.props as Props;
+
+const row = (count: number) => Array.from({ length: count }, (_, i) => i);
+---
+
+<div
+  data-slot="sidebar-nav-skeleton"
+  aria-hidden="true"
+  class="flex min-h-0 flex-1 flex-col"
+>
+  <div class="flex min-h-0 flex-1 flex-col justify-between">
+    <div class="flex flex-col gap-3">
+      {
+        row(items).map(() => (
+          <div class="flex items-center gap-2 p-2">
+            <Skeleton class="size-4 rounded-[3px]" />
+            <Skeleton class="h-3.5 w-20 rounded-sm" />
+          </div>
+        ))
+      }
+      <Separator class="my-2" />
+    </div>
+    <div class="flex flex-col gap-0.5">
+      {
+        row(footerItems).map(() => (
+          <div class="flex items-center gap-2 p-2">
+            <Skeleton class="size-4 rounded-[3px]" />
+            <Skeleton class="h-3.5 w-20 rounded-sm" />
+          </div>
+        ))
+      }
+    </div>
+  </div>
+  {
+    usage && (
+      <div class="flex flex-col gap-3">
+        <Separator class="my-2" />
+        <div class="flex flex-col gap-2">
+          <Skeleton class="h-3.5 w-20 rounded-sm" />
+          <Skeleton class="h-3.5 w-20 rounded-sm" />
+        </div>
+        <Skeleton class="h-3.5 w-20 rounded-sm" />
+      </div>
+    )
+  }
+</div>
+<span class="sr-only" role="status">Loading navigation</span>

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

@@ -0,0 +1,69 @@
+---
+/**
+ * @component SidebarNavSubItem
+ * @title Sidebar Nav Sub Item
+ * @description A destination nested inside a SidebarNavGroup, drawn against a vertical guide rail. The active item darkens its segment of the rail.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=7514-323
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * <SidebarNavSubItem href="/customization/branding" label="Branding" active />
+ * ```
+ */
+
+import type { HTMLAttributes } from "astro/types";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import SidebarNavProBadge from "./SidebarNavProBadge.astro";
+
+interface Props extends HTMLAttributes<"a"> {
+  href: string;
+  label: string;
+  active?: boolean;
+  pro?: boolean;
+  class?: string;
+}
+
+const {
+  href,
+  label,
+  active = false,
+  pro = false,
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+---
+
+<li
+  data-slot="sidebar-nav-sub-item"
+  class={cn("relative flex pl-[22px]", className)}
+>
+  <span
+    aria-hidden="true"
+    class="bg-sidebar-rail absolute top-1/2 left-[7.5px] h-8 w-px -translate-y-1/2"
+  ></span>
+  {
+    active && (
+      <span
+        aria-hidden="true"
+        class="bg-sidebar-accent-foreground absolute top-1/2 left-[7.5px] h-7 w-px -translate-y-1/2"
+      />
+    )
+  }
+  <a
+    {...rest}
+    href={href}
+    data-active={active ? "" : undefined}
+    aria-current={active ? "page" : undefined}
+    class={cn(
+      "flex min-w-0 flex-1 items-center justify-between gap-2 rounded-sm px-2 py-0.5 text-xs leading-6 font-medium outline-none transition-colors",
+      "hover:bg-muted focus-visible:ring-1 focus-visible:ring-sidebar-ring focus-visible:ring-inset",
+      active
+        ? "text-sidebar-accent-foreground"
+        : "text-muted-foreground hover:text-zinc-800 focus-visible:text-zinc-800 dark:hover:text-foreground dark:focus-visible:text-foreground",
+    )}
+  >
+    <span class="min-w-0 flex-1 truncate">{label}</span>
+    {pro && <SidebarNavProBadge />}
+  </a>
+</li>