@jcsoftdev/ui 0.1.6 → 0.2.0

package/dist/primitives/use-focus-scope.js

@@ -0,0 +1,91 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { getTabbables, resolveTabFromInside, resolveTabWrap } from "./focusable.js";
+const LIVE_OR_IGNORED = '[aria-live]:not([aria-live="off"]), [data-ui-overlay-ignore]';
+function focusWithoutScroll(element) {
+  element?.focus({ preventScroll: true });
+}
+function useFocusScope(options) {
+  const latest = useRef(options);
+  latest.current = options;
+  const returnTarget = useRef(null);
+  const activation = useRef(0);
+  const { active, trapped } = options;
+  useEffect(() => {
+    if (!active) return;
+    const container = latest.current.ref.current;
+    if (!container) return;
+    const mine = ++activation.current;
+    const previous = document.activeElement;
+    if (previous && !container.contains(previous)) returnTarget.current = previous;
+    if (!container.contains(previous)) {
+      const event = new Event("ui.focusScope.mount", { cancelable: true });
+      latest.current.onMountAutoFocus?.(event);
+      if (!event.defaultPrevented) {
+        const candidates = getTabbables(container).filter((el) => el.tagName !== "A");
+        focusWithoutScroll(candidates[0] ?? container);
+      }
+    }
+    return () => {
+      const target = returnTarget.current;
+      setTimeout(() => {
+        if (activation.current !== mine) return;
+        const event = new Event("ui.focusScope.unmount", { cancelable: true });
+        latest.current.onUnmountAutoFocus?.(event);
+        if (!event.defaultPrevented) {
+          focusWithoutScroll(target && document.contains(target) ? target : document.body);
+        }
+      }, 0);
+    };
+  }, [active]);
+  useEffect(() => {
+    const container = latest.current.ref.current;
+    if (!active || !trapped || !container) return;
+    const isActiveScope = () => !latest.current.isTop || latest.current.isTop();
+    let lastFocused = container.contains(document.activeElement) ? document.activeElement : null;
+    const onKeyDown = (event) => {
+      if (event.key !== "Tab" || event.altKey || event.ctrlKey || event.metaKey) return;
+      if (!isActiveScope()) return;
+      const items = getTabbables(container);
+      if (items.length === 0) {
+        event.preventDefault();
+        return;
+      }
+      const active2 = document.activeElement;
+      const target = active2 && active2 !== container && container.contains(active2) && !items.includes(active2) ? resolveTabFromInside(items, active2, event.shiftKey) : resolveTabWrap(items, active2, event.shiftKey);
+      if (target) {
+        event.preventDefault();
+        focusWithoutScroll(target);
+      }
+    };
+    const onFocusIn = (event) => {
+      const target = event.target;
+      if (!target || !(target instanceof Element)) return;
+      if (container.contains(target)) {
+        lastFocused = target;
+        return;
+      }
+      if (!isActiveScope() || target.closest(LIVE_OR_IGNORED)) return;
+      if (latest.current.allowFocus?.(target)) return;
+      const fallback = getTabbables(container)[0] ?? container;
+      focusWithoutScroll(lastFocused && container.contains(lastFocused) ? lastFocused : fallback);
+    };
+    const observer = new MutationObserver((mutations) => {
+      if (document.activeElement !== document.body || !isActiveScope()) return;
+      if (mutations.some((mutation) => mutation.removedNodes.length > 0)) {
+        focusWithoutScroll(container);
+      }
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+    container.addEventListener("keydown", onKeyDown);
+    document.addEventListener("focusin", onFocusIn);
+    return () => {
+      observer.disconnect();
+      container.removeEventListener("keydown", onKeyDown);
+      document.removeEventListener("focusin", onFocusIn);
+    };
+  }, [active, trapped]);
+}
+export {
+  useFocusScope
+};

package/dist/primitives/use-layer.d.ts

@@ -0,0 +1,2 @@
+/** Registers an overlay in the global layer stack while `active`; `isTop()` is stable. */
+export declare function useLayer(active: boolean): () => boolean;

package/dist/primitives/use-layer.js

@@ -0,0 +1,14 @@
+"use client";
+import { useCallback, useEffect, useRef } from "react";
+import { overlayLayers } from "./layer-stack.js";
+function useLayer(active) {
+  const layer = useRef({});
+  useEffect(() => {
+    if (!active) return;
+    return overlayLayers.push(layer.current);
+  }, [active]);
+  return useCallback(() => overlayLayers.isTop(layer.current), []);
+}
+export {
+  useLayer
+};

package/dist/primitives/use-presence.d.ts

@@ -0,0 +1,14 @@
+import { type RefObject } from "react";
+/**
+ * Longest exit effect on the node, in ms: its own animation (when `animation-name`
+ * is set) or a transition of an exit-relevant property. Unrelated transitions such
+ * as `transition-colors` are ignored so unmounting never waits for the safety timeout.
+ */
+export declare function exitDuration(node: Element): number;
+/**
+ * Keeps a node mounted while its exit animation or transition runs. Returns
+ * whether to render. The node must already carry its closed `data-state` when
+ * `present` turns false; it unmounts on `animationend`/`transitionend`, after a
+ * safety timeout, or immediately without motion or under reduced motion.
+ */
+export declare function usePresence(present: boolean, ref: RefObject<HTMLElement | null>): boolean;

package/dist/primitives/use-presence.js

@@ -0,0 +1,87 @@
+"use client";
+import { useLayoutEffect, useState } from "react";
+const SAFETY_MS = 50;
+function toMs(value) {
+  return value.split(",").map((part) => {
+    const text = part.trim();
+    const number = Number.parseFloat(text);
+    if (Number.isNaN(number)) return 0;
+    return text.endsWith("ms") ? number : number * 1e3;
+  });
+}
+const EXIT_PROPERTIES = /* @__PURE__ */ new Set([
+  "all",
+  "opacity",
+  "transform",
+  "translate",
+  "scale",
+  "rotate",
+  "filter",
+  "backdrop-filter",
+  "clip-path",
+  "visibility",
+  "width",
+  "height",
+  "max-width",
+  "max-height",
+  "top",
+  "right",
+  "bottom",
+  "left",
+  "inset"
+]);
+const cycle = (list, index) => list[index % list.length] ?? 0;
+function exitDuration(node) {
+  const style = getComputedStyle(node);
+  const total = (durations, delays, index = 0) => cycle(toMs(durations), index) + cycle(toMs(delays), index);
+  const animated = style.animationName === "none" ? 0 : Math.max(
+    0,
+    ...toMs(style.animationDuration).map(
+      (_, i) => total(style.animationDuration, style.animationDelay, i)
+    )
+  );
+  const properties = style.transitionProperty.split(",").map((part) => part.trim());
+  const transitioned = Math.max(
+    0,
+    ...properties.map(
+      (property, i) => EXIT_PROPERTIES.has(property) ? total(style.transitionDuration, style.transitionDelay, i) : 0
+    )
+  );
+  return Math.max(animated, transitioned);
+}
+function prefersReducedMotion() {
+  return typeof window.matchMedia === "function" ? window.matchMedia("(prefers-reduced-motion: reduce)").matches : false;
+}
+function usePresence(present, ref) {
+  const [mounted, setMounted] = useState(present);
+  if (present && !mounted) setMounted(true);
+  useLayoutEffect(() => {
+    if (present || !mounted) return;
+    const node = ref.current;
+    const duration = node && !prefersReducedMotion() ? exitDuration(node) : 0;
+    if (!node || duration <= 0) {
+      setMounted(false);
+      return;
+    }
+    const finish = () => setMounted(false);
+    const onEnd = (event) => {
+      if (event.target !== node) return;
+      const property = event.propertyName;
+      if (event.type === "transitionend" && !EXIT_PROPERTIES.has(property)) return;
+      finish();
+    };
+    node.addEventListener("animationend", onEnd);
+    node.addEventListener("transitionend", onEnd);
+    const timer = setTimeout(finish, duration + SAFETY_MS);
+    return () => {
+      node.removeEventListener("animationend", onEnd);
+      node.removeEventListener("transitionend", onEnd);
+      clearTimeout(timer);
+    };
+  }, [present, mounted, ref]);
+  return present || mounted;
+}
+export {
+  exitDuration,
+  usePresence
+};

package/dist/rich-text/index.d.ts

@@ -1,2 +1,2 @@
-export { RichTextEditor, type RichTextEditorProps, RichTextView, type RichTextViewProps, richTextContentClass, } from "./rich-text-editor.js";
+export { RichTextEditor, type RichTextEditorPart, type RichTextEditorProps, RichTextView, type RichTextViewProps, richTextContentClass, } from "./rich-text-editor.js";
 export { htmlToText, isSafeUrl, sanitizeHtml } from "./sanitize.js";

package/dist/rich-text/rich-text-editor.d.ts

@@ -1,5 +1,7 @@
+import type { ClassNames } from "../utils/class-names.js";
 /** Typography for editor and read-only content; preflight resets lists and headings. */
 export declare const richTextContentClass = "text-body text-ink [&_a]:text-accent-ink [&_a]:underline [&_blockquote]:border-line-strong [&_blockquote]:border-l-2 [&_blockquote]:pl-3 [&_blockquote]:text-ink-2 [&_h2]:font-semibold [&_h2]:text-card-title [&_h3]:font-semibold [&_h3]:text-row-title [&_li]:my-0.5 [&_ol]:list-decimal [&_ol]:pl-5 [&_p]:my-1 [&_ul]:list-disc [&_ul]:pl-5 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0 [overflow-wrap:anywhere]";
+export type RichTextEditorPart = "root" | "toolbar" | "tool" | "linkForm" | "linkInput" | "linkApply" | "linkRemove" | "body" | "placeholder" | "content";
 export interface RichTextEditorProps {
     /** Controlled HTML. It is sanitized before it reaches the editor. */
     value?: string;
@@ -13,6 +15,8 @@ export interface RichTextEditorProps {
     "aria-label"?: string;
     "aria-labelledby"?: string;
     className?: string;
+    /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+    classNames?: ClassNames<RichTextEditorPart>;
 }
 /**
  * Rich text editor on a plain `contenteditable`, with no dependencies. Supports bold, italic,
@@ -22,7 +26,7 @@ export interface RichTextEditorProps {
  * It uses `document.execCommand`: deprecated on paper but still the only dependency-free way to
  * edit rich text natively, and implemented by every engine.
  */
-export declare function RichTextEditor({ value, defaultValue, onChange, placeholder, disabled, minHeightRem, className, ...aria }: RichTextEditorProps): import("react").JSX.Element;
+export declare function RichTextEditor({ value, defaultValue, onChange, placeholder, disabled, minHeightRem, className, classNames, ...aria }: RichTextEditorProps): import("react").JSX.Element;
 export interface RichTextViewProps {
     html: string;
     className?: string;

package/dist/rich-text/rich-text-editor.js

@@ -1,6 +1,5 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { Bold, Heading2, Italic, Link2, List, ListOrdered, Underline, Unlink } from "lucide-react";
 import {
   useCallback,
   useEffect,
@@ -9,6 +8,16 @@ import {
   useRef,
   useState
 } from "react";
+import {
+  Bold,
+  Heading2,
+  Italic,
+  Link2,
+  List,
+  ListOrdered,
+  Underline,
+  Unlink
+} from "../icons/index.js";
 import { cn } from "../utils/cn.js";
 import { htmlToText, isSafeUrl, sanitizeHtml } from "./sanitize.js";
 const richTextContentClass = "text-body text-ink [&_a]:text-accent-ink [&_a]:underline [&_blockquote]:border-line-strong [&_blockquote]:border-l-2 [&_blockquote]:pl-3 [&_blockquote]:text-ink-2 [&_h2]:font-semibold [&_h2]:text-card-title [&_h3]:font-semibold [&_h3]:text-row-title [&_li]:my-0.5 [&_ol]:list-decimal [&_ol]:pl-5 [&_p]:my-1 [&_ul]:list-disc [&_ul]:pl-5 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0 [overflow-wrap:anywhere]";
@@ -75,6 +84,7 @@ function RichTextEditor({
   disabled,
   minHeightRem = 8,
   className,
+  classNames,
   ...aria
 }) {
   const baseId = useId();
@@ -226,6 +236,7 @@ function RichTextEditor({
       className: cn(
         "@container/rte flex w-full min-w-0 flex-col overflow-hidden rounded-input border-control bg-surface-control focus-within:outline-2 focus-within:outline-accent-ink focus-within:-outline-offset-1",
         disabled && "opacity-60",
+        classNames?.root,
         className
       ),
       children: [
@@ -237,7 +248,10 @@ function RichTextEditor({
             "aria-label": "Formato",
             "aria-controls": `${baseId}-editor`,
             onKeyDown: onToolbarKeyDown,
-            className: "flex flex-wrap items-center gap-0.5 border-b-divider p-1",
+            className: cn(
+              "flex flex-wrap items-center gap-0.5 border-b-divider p-1",
+              classNames?.toolbar
+            ),
             children: [
               tools.map((tool, index) => /* @__PURE__ */ jsx(
                 "button",
@@ -252,7 +266,10 @@ function RichTextEditor({
                   onFocus: () => setFocusIndex(index),
                   onMouseDown: (event) => event.preventDefault(),
                   onClick: tool.run,
-                  className: "pressable grid size-8 place-items-center rounded-button text-ink-2 hover:bg-surface-sunken hover:text-ink focus-visible:focus-ring disabled:cursor-not-allowed aria-pressed:bg-accent-soft aria-pressed:text-accent-ink [&_svg]:size-4",
+                  className: cn(
+                    "pressable grid size-8 place-items-center rounded-button text-ink-2 hover:bg-surface-sunken hover:text-ink focus-visible:focus-ring disabled:cursor-not-allowed aria-pressed:bg-accent-soft aria-pressed:text-accent-ink [&_svg]:size-4",
+                    classNames?.tool
+                  ),
                   children: tool.icon
                 },
                 tool.id
@@ -260,7 +277,10 @@ function RichTextEditor({
               linkOpen ? /* @__PURE__ */ jsxs(
                 "form",
                 {
-                  className: "flex min-w-0 basis-full items-center gap-1 pt-1 @md/rte:basis-auto @md/rte:flex-1 @md/rte:pt-0",
+                  className: cn(
+                    "flex min-w-0 basis-full items-center gap-1 pt-1 @md/rte:basis-auto @md/rte:flex-1 @md/rte:pt-0",
+                    classNames?.linkForm
+                  ),
                   onSubmit: (event) => {
                     event.preventDefault();
                     applyLink();
@@ -284,14 +304,20 @@ function RichTextEditor({
                             closeLink();
                           }
                         },
-                        className: "h-control-sm min-w-0 flex-1 rounded-input border-control bg-surface-control px-2 text-control text-ink focus:border-transparent focus:outline-2 focus:outline-accent-ink focus:-outline-offset-1 aria-[invalid=true]:border-danger"
+                        className: cn(
+                          "h-control-sm min-w-0 flex-1 rounded-input border-control bg-surface-control px-2 text-control text-ink focus:border-transparent focus:outline-2 focus:outline-accent-ink focus:-outline-offset-1 aria-[invalid=true]:border-danger",
+                          classNames?.linkInput
+                        )
                       }
                     ),
                     /* @__PURE__ */ jsx(
                       "button",
                       {
                         type: "submit",
-                        className: "h-control-sm rounded-button bg-accent px-2.5 font-semibold text-control text-on-accent focus-visible:focus-ring",
+                        className: cn(
+                          "h-control-sm rounded-button bg-accent px-2.5 font-semibold text-control text-on-accent focus-visible:focus-ring",
+                          classNames?.linkApply
+                        ),
                         children: "Aplicar"
                       }
                     ),
@@ -302,7 +328,10 @@ function RichTextEditor({
                         title: "Quitar enlace",
                         "aria-label": "Quitar enlace",
                         onClick: removeLink,
-                        className: "grid size-8 place-items-center rounded-button text-ink-2 hover:bg-surface-sunken focus-visible:focus-ring [&_svg]:size-4",
+                        className: cn(
+                          "grid size-8 place-items-center rounded-button text-ink-2 hover:bg-surface-sunken focus-visible:focus-ring [&_svg]:size-4",
+                          classNames?.linkRemove
+                        ),
                         children: /* @__PURE__ */ jsx(Unlink, {})
                       }
                     )
@@ -312,12 +341,15 @@ function RichTextEditor({
             ]
           }
         ),
-        /* @__PURE__ */ jsxs("div", { className: "relative", children: [
+        /* @__PURE__ */ jsxs("div", { className: cn("relative", classNames?.body), children: [
           empty ? /* @__PURE__ */ jsx(
             "span",
             {
               "aria-hidden": "true",
-              className: "pointer-events-none absolute top-0 left-0 px-3 py-2 text-body text-ink-3",
+              className: cn(
+                "pointer-events-none absolute top-0 left-0 px-3 py-2 text-body text-ink-3",
+                classNames?.placeholder
+              ),
               children: placeholder
             }
           ) : null,
@@ -340,7 +372,7 @@ function RichTextEditor({
               onKeyDown: onEditorKeyDown,
               onBlur: emit,
               style: { minHeight: `${minHeightRem}rem` },
-              className: cn("w-full px-3 py-2 outline-none", richTextContentClass)
+              className: cn("w-full px-3 py-2 outline-none", richTextContentClass, classNames?.content)
             }
           )
         ] })

package/dist/shell/app-shell/app-shell.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode, type RefObject } from "react";
+import { type ComponentPropsWithRef, type ReactNode, type RefObject } from "react";
 /** Container width (px) below which the shell is compact: the sidebar becomes a drawer. */
 export declare const APP_SHELL_BREAKPOINT = 900;
 /**
@@ -11,14 +11,13 @@ interface AppShellState {
 }
 /** `null` outside an `AppShell`; otherwise whether the shell is narrower than 900 px. */
 export declare function useAppShell(): AppShellState | null;
-export interface AppShellProps {
+export interface AppShellProps extends ComponentPropsWithRef<"div"> {
     children: ReactNode;
-    className?: string;
 }
 /**
  * Root of the app frame (sidebar + topbar + page). It is the `app` container: the sidebar turns
  * into a drawer and the topbar shows its menu button when the SHELL is under 900 px wide,
  * whatever the viewport is, so the same shell works in a full page, a preview or a story.
  */
-export declare function AppShell({ children, className }: AppShellProps): import("react").JSX.Element;
+export declare function AppShell({ children, className, ref: forwardedRef, ...props }: AppShellProps): import("react").JSX.Element;
 export {};

package/dist/shell/app-shell/app-shell.js

@@ -9,6 +9,7 @@ import {
   useState
 } from "react";
 import { cn } from "../../utils/cn.js";
+import { useComposedRefs } from "../../utils/compose.js";
 const APP_SHELL_BREAKPOINT = 900;
 const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 function useCompactContainer(ref, resolve = (element) => element, enabled = true) {
@@ -29,10 +30,11 @@ const AppShellContext = createContext(null);
 function useAppShell() {
   return useContext(AppShellContext);
 }
-function AppShell({ children, className }) {
+function AppShell({ children, className, ref: forwardedRef, ...props }) {
   const ref = useRef(null);
   const compact = useCompactContainer(ref);
-  return /* @__PURE__ */ jsx(AppShellContext.Provider, { value: { compact }, children: /* @__PURE__ */ jsx("div", { ref, className: cn("@container/app flex min-w-0", className), children }) });
+  const composedRef = useComposedRefs(ref, forwardedRef);
+  return /* @__PURE__ */ jsx(AppShellContext.Provider, { value: { compact }, children: /* @__PURE__ */ jsx("div", { ref: composedRef, ...props, className: cn("@container/app flex min-w-0", className), children }) });
 }
 export {
   APP_SHELL_BREAKPOINT,

package/dist/shell/sidebar/index.d.ts

@@ -1 +1 @@
-export { Sidebar, type SidebarGroup, type SidebarItem, type SidebarLinkProps, type SidebarProps, type SidebarRenderLink, } from "./sidebar.js";
+export { Sidebar, type SidebarGroup, type SidebarItem, type SidebarLinkProps, type SidebarPart, type SidebarProps, type SidebarRenderLink, } from "./sidebar.js";

package/dist/shell/sidebar/sidebar.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from "react";
+import type { ClassNames } from "../../utils/class-names.js";
 export interface SidebarLinkProps {
     href: string;
     className: string;
@@ -24,6 +25,7 @@ export interface SidebarGroup {
     label: string;
     items: SidebarItem[];
 }
+export type SidebarPart = "root" | "group" | "groupLabel" | "item" | "link" | "label" | "badge" | "footer" | "scrim";
 export interface SidebarProps {
     groups: SidebarGroup[];
     /** Accessible name of the sidebar landmark. */
@@ -38,6 +40,8 @@ export interface SidebarProps {
     open?: boolean;
     onClose?: () => void;
     className?: string;
+    /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+    classNames?: ClassNames<SidebarPart>;
 }
 /**
  * Main navigation. Always visible when its app container is wide; an off-canvas drawer under
@@ -45,4 +49,4 @@ export interface SidebarProps {
  * Render it inside `AppShell`: the container decides, never the viewport. Without an `AppShell`
  * it measures its parent element instead.
  */
-export declare function Sidebar({ groups, ariaLabel, header, footer, renderLink, open, onClose, className, }: SidebarProps): import("react").JSX.Element;
+export declare function Sidebar({ groups, ariaLabel, header, footer, renderLink, open, onClose, className, classNames, }: SidebarProps): import("react").JSX.Element;

package/dist/shell/sidebar/sidebar.js

@@ -12,7 +12,8 @@ function Sidebar({
   renderLink = defaultRenderLink,
   open = false,
   onClose,
-  className
+  className,
+  classNames
 }) {
   const shell = useAppShell();
   const asideRef = useRef(null);
@@ -52,45 +53,56 @@ function Sidebar({
             closedOnMobile ? "-translate-x-full" : "translate-x-0"
           ),
           openOnMobile && "shadow-overlay",
+          classNames?.root,
           className
         ),
         children: [
           header,
-          groups.map((group) => /* @__PURE__ */ jsxs("nav", { "aria-label": group.label, className: "flex flex-col gap-px", children: [
-            /* @__PURE__ */ jsx("div", { className: "px-2.5 pb-1.5 text-overline text-ink-3", children: group.label }),
-            group.items.map((item) => {
-              const badgeTone = item.badgeTone === "danger" ? "bg-danger-soft text-danger" : "bg-surface-2 text-ink-2";
-              return /* @__PURE__ */ jsx("div", { children: renderLink({
-                href: item.href,
-                "aria-current": item.active ? "page" : void 0,
-                className: cn(
-                  "flex items-center gap-2.5 rounded-control px-2.5 py-2 text-control text-ink-2 hover:bg-surface-2 hover:text-ink [&_svg]:size-4.25 [&_svg]:shrink-0",
-                  item.active && "bg-accent-soft font-bold text-accent-ink"
-                ),
-                children: /* @__PURE__ */ jsxs(Fragment, { children: [
-                  item.icon,
-                  /* @__PURE__ */ jsx("span", { className: "min-w-0 truncate", children: item.label }),
-                  item.badge !== void 0 ? /* @__PURE__ */ jsxs(
-                    "span",
-                    {
-                      className: cn(
-                        "ml-auto shrink-0 rounded-chip px-1.5 py-0.75 text-count",
-                        badgeTone
-                      ),
-                      children: [
-                        item.badge,
-                        item.badgeLabel ? /* @__PURE__ */ jsxs("span", { className: "sr-only", children: [
-                          " ",
-                          item.badgeLabel
-                        ] }) : null
-                      ]
-                    }
-                  ) : null
-                ] })
-              }) }, item.id);
-            })
-          ] }, group.id)),
-          footer ? /* @__PURE__ */ jsx("div", { className: "mt-auto", children: footer }) : null
+          groups.map((group) => /* @__PURE__ */ jsxs(
+            "nav",
+            {
+              "aria-label": group.label,
+              className: cn("flex flex-col gap-px", classNames?.group),
+              children: [
+                /* @__PURE__ */ jsx("div", { className: cn("px-2.5 pb-1.5 text-overline text-ink-3", classNames?.groupLabel), children: group.label }),
+                group.items.map((item) => {
+                  const badgeTone = item.badgeTone === "danger" ? "bg-danger-soft text-danger" : "bg-surface-2 text-ink-2";
+                  return /* @__PURE__ */ jsx("div", { className: classNames?.item, children: renderLink({
+                    href: item.href,
+                    "aria-current": item.active ? "page" : void 0,
+                    className: cn(
+                      "flex items-center gap-2.5 rounded-control px-2.5 py-2 text-control text-ink-2 hover:bg-surface-2 hover:text-ink [&_svg]:size-4.25 [&_svg]:shrink-0",
+                      item.active && "bg-accent-soft font-bold text-accent-ink",
+                      classNames?.link
+                    ),
+                    children: /* @__PURE__ */ jsxs(Fragment, { children: [
+                      item.icon,
+                      /* @__PURE__ */ jsx("span", { className: cn("min-w-0 truncate", classNames?.label), children: item.label }),
+                      item.badge !== void 0 ? /* @__PURE__ */ jsxs(
+                        "span",
+                        {
+                          className: cn(
+                            "ml-auto shrink-0 rounded-chip px-1.5 py-0.75 text-count",
+                            badgeTone,
+                            classNames?.badge
+                          ),
+                          children: [
+                            item.badge,
+                            item.badgeLabel ? /* @__PURE__ */ jsxs("span", { className: "sr-only", children: [
+                              " ",
+                              item.badgeLabel
+                            ] }) : null
+                          ]
+                        }
+                      ) : null
+                    ] })
+                  }) }, item.id);
+                })
+              ]
+            },
+            group.id
+          )),
+          footer ? /* @__PURE__ */ jsx("div", { className: cn("mt-auto", classNames?.footer), children: footer }) : null
         ]
       }
     ),
@@ -100,7 +112,7 @@ function Sidebar({
         "data-sidebar-scrim": true,
         "aria-hidden": "true",
         onClick: onClose,
-        className: "fixed inset-0 z-44 bg-scrim"
+        className: cn("fixed inset-0 z-44 bg-scrim", classNames?.scrim)
       }
     ) : null
   ] });

package/dist/shell/topbar/index.d.ts

@@ -1 +1 @@
-export { Topbar, type TopbarProps } from "./topbar.js";
+export { Topbar, type TopbarPart, type TopbarProps } from "./topbar.js";

package/dist/shell/topbar/topbar.d.ts

@@ -1,4 +1,6 @@
 import { type ReactNode, type Ref } from "react";
+import type { ClassNames } from "../../utils/class-names.js";
+export type TopbarPart = "root" | "inner" | "menuButton" | "breadcrumbs" | "crumb" | "separator" | "current" | "search" | "searchText" | "shortcut";
 export interface TopbarProps {
     /** Breadcrumb trail in order; the last entry is the current view. */
     breadcrumbs: string[];
@@ -18,5 +20,7 @@ export interface TopbarProps {
     /** Slot at the far end (e.g. the account menu). */
     end?: ReactNode;
     className?: string;
+    /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+    classNames?: ClassNames<TopbarPart>;
 }
-export declare function Topbar({ breadcrumbs, breadcrumbsLabel, onOpenMenu, menuLabel, menuButtonRef, onSearch, searchLabel, searchPlaceholder, actions, end, className, }: TopbarProps): import("react").JSX.Element;
+export declare function Topbar({ breadcrumbs, breadcrumbsLabel, onOpenMenu, menuLabel, menuButtonRef, onSearch, searchLabel, searchPlaceholder, actions, end, className, classNames, }: TopbarProps): import("react").JSX.Element;