@lessly/ui 1.6.0 → 2.0.0

package/README.md

@@ -5,12 +5,11 @@ and Tailwind preset. This package is the shared singleton the Lessly workspace
 Module Federation host provides to federation extension remotes at runtime, and
 it is published to the public npm registry (npmjs.com).
 
-> **Contract:** the package name (`@lessly/ui`), its exports (`.`,
-> `./tailwind-preset`, `./styles.css`, `./styles-federated.css`), and its peer
-> dependencies (React 19,
-> react-router 7, optional `tailwindcss >=3.4`) are a cross-project contract. Do
-> not change them without coordinating the workspace host and every federation
-> remote.
+> **Contract:** the package name, its exports and its peer dependencies — all
+> declared in `package.json` — are a cross-project contract. Do not change them
+> without coordinating the workspace host and every federation remote.
+> `scripts/check-package-contract.mjs` refuses a change to any of them, and says
+> the same thing when it does.
 
 ## What's inside
 
@@ -24,7 +23,8 @@ it is published to the public npm registry (npmjs.com).
   [`@lessly/tokens`](https://www.npmjs.com/package/@lessly/tokens) (generated
   upstream in `lessly-hub/design-system`) with `darkMode: 'class'` added, and
   `styles.css` bundles the package's `theme.css` (CSS variables, `.light`
-  overrides, typography classes) plus this library's fonts and base layer.
+  overrides, typography classes) plus this library's fonts and base layer, and a
+  `@theme` block that declares every colour token to Tailwind v4.
   `styles-federated.css` is the same sheet without the `@font-face` rules and
   the `@layer base` block, and with its variables declared on `:where(:root)` /
   `:where(.light)` so a shell's own tokens outrank the remote's whatever loaded
@@ -47,6 +47,16 @@ import { Button, useTheme } from '@lessly/ui';
 import '@lessly/ui/styles.css';
 ```
 
+The four components that need a router — `AppShell`, `AppSidebar`, `SidebarNav`
+and `ExtensionLink` — come from `@lessly/ui/router` instead, and only that entry
+imports `react-router`. The main entry never does, which is what makes
+`react-router` an optional peer: an app that navigates with plain `href`s can
+use the rest of the kit without installing one.
+
+```ts
+import { AppShell, SidebarNav } from '@lessly/ui/router';
+```
+
 Tailwind is what turns the kit's class names into CSS. The package ships **no
 compiled utility CSS** — every consumer runs its own Tailwind over the token
 preset (`tailwindcss >= 3.4`, an optional peer dependency, required only if you
@@ -54,15 +64,13 @@ consume the preset).
 
 ### Tailwind v4 (CSS-first)
 
-Everything is declared in your CSS entry:
+Everything is declared in your CSS entry. The minimum is three lines:
 
 ```css
 @import 'tailwindcss';
-/* The token preset. v4 has no `presets:` key of its own, so the preset is
-   loaded from a JS/TS config file — without this, `bg-bg-surface`,
-   `text-text-primary` and `gap-gutter` emit nothing at all. */
-@config './tailwind.config.ts';
-/* Token variables, `.light` overrides, fonts, base layer. */
+/* Token variables, `.light` overrides, fonts, base layer — and a `@theme` block
+   declaring every colour token, so `bg-bg-surface`, `text-text-primary` and
+   `ring-border-selected` compile from this import alone. */
 @import '@lessly/ui/styles.css';
 /* Scan the library. v4 does not scan `node_modules` on its own, and the kit's
    components (Grid, Col, …) carry literal utilities (`md:col-span-5`,
@@ -72,7 +80,16 @@ Everything is declared in your CSS entry:
 @source './node_modules/@lessly/ui/dist/**/*.js';
 ```
 
-with the config file next to it holding nothing but the preset:
+The rest of the token vocabulary is not colour and does not travel in CSS: the
+spacing scale, the grid gutter (`gap-gutter`), radii, shadows, z-index and
+durations come from the JS preset, and v4 has no `presets:` key of its own, so a
+config file is what loads it:
+
+```css
+@config './tailwind.config.ts';
+```
+
+with that file holding nothing but the preset:
 
 ```ts
 import type { Config } from 'tailwindcss';

package/dist/chunk-F5RMHSPS.js

@@ -0,0 +1,433 @@
+// src/lib/utils.ts
+import { clsx } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+var TOKEN_FONT_WEIGHTS = ["regular", "medium", "semibold", "bold", "extrabold"];
+var TOKEN_BORDER_WIDTHS = ["none", "thin", "medium", "thick", "heavy"];
+var twMerge = extendTailwindMerge((config) => {
+  config.theme["font-weight"] = [...config.theme["font-weight"] ?? [], ...TOKEN_FONT_WEIGHTS];
+  for (const group of Object.keys(config.classGroups)) {
+    if (group !== "border-w" && !group.startsWith("border-w-")) continue;
+    config.classGroups[group] = [
+      ...config.classGroups[group] ?? [],
+      { [group.replace("border-w", "border")]: TOKEN_BORDER_WIDTHS }
+    ];
+  }
+  for (const entry of config.classGroups["outline-w"] ?? []) {
+    if (typeof entry !== "object" || Array.isArray(entry)) continue;
+    for (const [name, members] of Object.entries(entry)) {
+      if (Array.isArray(members)) {
+        entry[name] = members.filter((m) => m !== "");
+      }
+    }
+  }
+  config.conflictingClassGroups["font-size"] = [];
+  return config;
+});
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+
+// src/components/button.tsx
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva } from "class-variance-authority";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var buttonVariants = cva(
+  "inline-flex cursor-pointer items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      // Every variant names its own `focus-visible:ring-*` colour and the base names none, because
+      // `buttonVariants` is exported: called raw it concatenates rather than merging, so a base
+      // colour would reach the element beside the variant's and stylesheet order would pick.
+      variant: {
+        default: "bg-blue-400 text-text-on-brand focus-visible:ring-border-focus hover:bg-blue-350",
+        /** The frame carries the danger at rest and the text stays neutral, because a hover-only
+         *  signal is no signal on a touch device. Hover adds the wash and the red label; keyboard
+         *  focus reddens the ring alone. */
+        destructive: "border border-border-danger bg-transparent text-text-primary focus-visible:ring-border-danger hover:bg-bg-danger-subtle hover:text-text-danger",
+        /** The borderless form of `destructive`, for an icon-only revoke repeated down a list — a row
+         *  of framed ✕ buttons would shout. */
+        "destructive-ghost": "text-text-tertiary focus-visible:ring-border-focus hover:bg-bg-danger-subtle hover:text-text-danger",
+        /** @deprecated A resting red fill. It belongs on a confirm inside a window that has already
+         *  stated the stakes, and the kit sanctions two: `ConfirmDialog`'s confirm and a
+         *  `StepUpChallenge destructive` one. Use `destructive` for any trigger that sits on a page. */
+        "destructive-solid": "bg-bg-danger text-text-on-danger focus-visible:ring-border-focus hover:bg-bg-danger-a90",
+        outline: "border border-border-default bg-transparent text-text-primary focus-visible:ring-border-focus hover:bg-bg-secondary",
+        secondary: "bg-bg-secondary text-text-primary focus-visible:ring-border-focus hover:bg-bg-secondary-a80",
+        /** The frameless console tone, and the add affordance — `variant="ghost" size="xs"` with a
+         *  leading `+`. It rests at `text-text-primary` because a button's variant differs by frame
+         *  and fill, never by text colour; `destructive-ghost` keeps its quieter rest on purpose. */
+        ghost: "text-text-primary focus-visible:ring-border-focus hover:bg-bg-secondary",
+        link: "text-text-link underline-offset-4 focus-visible:ring-border-focus hover:underline hover:text-text-link-hover"
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        /** Card-header and page-header scale — the size an `+ Add` trigger rides at. */
+        xs: "h-7 gap-1.5 rounded-md px-2",
+        lg: "h-11 rounded-md px-8",
+        /**
+         * A 40px square. Predates the icon-only form and every call site in this repo overrode it
+         * with a `className`. Prefer passing `icon` with no children: the box then squares itself
+         * from whatever `size` the button already has, so an icon button lines up with the text
+         * button beside it. Kept because `buttonVariants({ size: 'icon' })` is used directly by
+         * `Pagination`.
+         */
+        icon: "h-10 w-10"
+      }
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default"
+    }
+  }
+);
+var ICON_ONLY_BOX = {
+  xs: "size-7 p-0",
+  sm: "size-9 p-0",
+  default: "size-10 p-0",
+  lg: "size-11 p-0",
+  icon: "size-10 p-0"
+};
+var ICON_GLYPH = {
+  xs: "[&>svg]:size-3.5",
+  sm: "[&>svg]:size-4",
+  default: "[&>svg]:size-4",
+  lg: "[&>svg]:size-4",
+  icon: "[&>svg]:size-4"
+};
+var Button = React.forwardRef((props, ref) => {
+  const {
+    className,
+    variant,
+    size,
+    asChild = false,
+    icon,
+    iconPosition = "leading",
+    children,
+    type,
+    ...rest
+  } = props;
+  const resolvedSize = size ?? "default";
+  const iconOnly = icon != null && children == null;
+  if (process.env.NODE_ENV !== "production") {
+    const label = rest["aria-label"];
+    const labelledBy = rest["aria-labelledby"];
+    if (iconOnly && !label?.trim() && !labelledBy?.trim()) {
+      console.warn(
+        "[Button] an icon-only button needs an accessible name: pass `aria-label` (#269, Guidelines/Icons & tooltips). It owes a tooltip too \u2014 wrap it in <Tooltip>."
+      );
+    }
+    if (asChild && icon != null) {
+      console.warn("[Button] `icon` is ignored with `asChild`: the consumer owns the element.");
+    }
+  }
+  const Comp = asChild ? Slot : "button";
+  const typeProps = { type: asChild ? type : type ?? "button" };
+  const glyph = icon == null ? null : /* @__PURE__ */ jsx(
+    "span",
+    {
+      className: cn("inline-flex shrink-0 items-center justify-center", ICON_GLYPH[resolvedSize]),
+      "aria-hidden": true,
+      children: icon
+    }
+  );
+  return /* @__PURE__ */ jsx(
+    Comp,
+    {
+      className: cn(
+        buttonVariants({ variant, size }),
+        iconOnly && ICON_ONLY_BOX[resolvedSize],
+        className
+      ),
+      ref,
+      ...typeProps,
+      ...rest,
+      children: asChild ? children : iconPosition === "trailing" ? /* @__PURE__ */ jsxs(Fragment, { children: [
+        children,
+        glyph
+      ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+        glyph,
+        children
+      ] })
+    }
+  );
+});
+Button.displayName = "Button";
+
+// src/components/tooltip.tsx
+import * as React2 from "react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var TooltipProvider = TooltipPrimitive.Provider;
+var TriggerContext = React2.createContext({ trigger: null, setTrigger: () => {
+} });
+function directionOf(trigger) {
+  if (!trigger) return "ltr";
+  const declared = trigger.closest('[dir="rtl"], [dir="ltr"]')?.getAttribute("dir");
+  if (declared) return declared.toLowerCase() === "rtl" ? "rtl" : "ltr";
+  const computed = trigger.ownerDocument.defaultView?.getComputedStyle(trigger).direction;
+  return computed === "rtl" ? "rtl" : "ltr";
+}
+var Tooltip = ({
+  children,
+  ...props
+}) => {
+  const [trigger, setTrigger] = React2.useState(null);
+  const value = React2.useMemo(() => ({ trigger, setTrigger }), [trigger]);
+  return /* @__PURE__ */ jsx2(TriggerContext.Provider, { value, children: /* @__PURE__ */ jsx2(TooltipPrimitive.Root, { ...props, children }) });
+};
+Tooltip.displayName = "Tooltip";
+var TooltipTrigger = React2.forwardRef((props, ref) => {
+  const { setTrigger } = React2.useContext(TriggerContext);
+  const composedRef = React2.useCallback(
+    (node) => {
+      setTrigger(node);
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    },
+    [ref, setTrigger]
+  );
+  return /* @__PURE__ */ jsx2(TooltipPrimitive.Trigger, { ref: composedRef, ...props });
+});
+TooltipTrigger.displayName = TooltipPrimitive.Trigger.displayName;
+var TooltipContent = React2.forwardRef(({ className, sideOffset = 4, dir, ...props }, ref) => {
+  const { trigger } = React2.useContext(TriggerContext);
+  return /* @__PURE__ */ jsx2(TooltipPrimitive.Portal, { children: /* @__PURE__ */ jsx2(
+    TooltipPrimitive.Content,
+    {
+      ref,
+      dir: dir ?? directionOf(trigger),
+      sideOffset,
+      className: cn(
+        "z-50 max-w-[min(var(--layout-80),var(--radix-popper-available-width))] overflow-hidden break-words rounded-md border border-border-subtle bg-bg-elevated px-3 py-1.5 text-xs text-text-primary shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+        className
+      ),
+      ...props
+    }
+  ) });
+});
+TooltipContent.displayName = TooltipPrimitive.Content.displayName;
+
+// src/components/sheet.tsx
+import * as React3 from "react";
+import * as SheetPrimitive from "@radix-ui/react-dialog";
+import { cva as cva2 } from "class-variance-authority";
+import { X } from "lucide-react";
+import { jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
+var Sheet = SheetPrimitive.Root;
+var SheetTrigger = SheetPrimitive.Trigger;
+var SheetClose = SheetPrimitive.Close;
+var SheetPortal = SheetPrimitive.Portal;
+var SheetOverlay = React3.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx3(
+  SheetPrimitive.Overlay,
+  {
+    ref,
+    className: cn(
+      "fixed inset-0 z-50 bg-black/50 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      className
+    ),
+    ...props
+  }
+));
+SheetOverlay.displayName = SheetPrimitive.Overlay.displayName;
+var sheetVariants = cva2(
+  "fixed z-50 gap-4 bg-bg-elevated p-6 shadow-lg transition ease-in-out data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:duration-500",
+  {
+    variants: {
+      side: {
+        top: "inset-x-0 top-0 border-b border-border-subtle data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
+        bottom: "inset-x-0 bottom-0 border-t border-border-subtle data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom",
+        left: "inset-y-0 left-0 h-full w-3/4 border-r border-border-subtle data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left sm:max-w-sm",
+        right: "inset-y-0 right-0 h-full w-3/4 border-l border-border-subtle data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right sm:max-w-sm"
+      }
+    },
+    defaultVariants: {
+      side: "right"
+    }
+  }
+);
+var SheetContent = React3.forwardRef(({ side = "right", className, children, ...props }, ref) => /* @__PURE__ */ jsxs2(SheetPortal, { children: [
+  /* @__PURE__ */ jsx3(SheetOverlay, {}),
+  /* @__PURE__ */ jsxs2(
+    SheetPrimitive.Content,
+    {
+      ref,
+      className: cn(sheetVariants({ side }), className),
+      ...props,
+      children: [
+        children,
+        /* @__PURE__ */ jsxs2(SheetPrimitive.Close, { className: "absolute right-4 top-4 rounded-sm text-text-tertiary opacity-70 transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-border-focus disabled:pointer-events-none", children: [
+          /* @__PURE__ */ jsx3(X, { className: "h-4 w-4" }),
+          /* @__PURE__ */ jsx3("span", { className: "sr-only", children: "Close" })
+        ] })
+      ]
+    }
+  )
+] }));
+SheetContent.displayName = SheetPrimitive.Content.displayName;
+var SheetHeader = ({ className, ...props }) => /* @__PURE__ */ jsx3(
+  "div",
+  {
+    className: cn("flex flex-col gap-1.5 text-left", className),
+    ...props
+  }
+);
+SheetHeader.displayName = "SheetHeader";
+var SheetFooter = ({ className, ...props }) => /* @__PURE__ */ jsx3(
+  "div",
+  {
+    className: cn("flex flex-col-reverse gap-2 sm:flex-row sm:justify-end", className),
+    ...props
+  }
+);
+SheetFooter.displayName = "SheetFooter";
+var SheetTitle = React3.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx3(
+  SheetPrimitive.Title,
+  {
+    ref,
+    className: cn("text-lg font-semibold text-text-primary", className),
+    ...props
+  }
+));
+SheetTitle.displayName = SheetPrimitive.Title.displayName;
+var SheetDescription = React3.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx3(
+  SheetPrimitive.Description,
+  {
+    ref,
+    className: cn("text-sm text-text-secondary", className),
+    ...props
+  }
+));
+SheetDescription.displayName = SheetPrimitive.Description.displayName;
+
+// src/hooks/use-mobile.ts
+import { useEffect, useState as useState2 } from "react";
+var MD_BREAKPOINT = 768;
+function useIsMobile() {
+  const [isMobile, setIsMobile] = useState2(
+    typeof window !== "undefined" ? window.innerWidth < MD_BREAKPOINT : false
+  );
+  useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${String(MD_BREAKPOINT - 1)}px)`);
+    const handler = (e) => {
+      setIsMobile(e.matches);
+    };
+    mql.addEventListener("change", handler);
+    setIsMobile(mql.matches);
+    return () => {
+      mql.removeEventListener("change", handler);
+    };
+  }, []);
+  return isMobile;
+}
+
+// src/hooks/use-sidebar.ts
+import { useCallback as useCallback2, useState as useState3 } from "react";
+function useSidebar(options = {}) {
+  const { collapsed: controlled, defaultCollapsed = false, onCollapsedChange } = options;
+  const isControlled = controlled !== void 0;
+  const [internal, setInternal] = useState3(defaultCollapsed);
+  const collapsed = isControlled ? controlled : internal;
+  const setCollapsed = useCallback2(
+    (next) => {
+      if (!isControlled) setInternal(next);
+      onCollapsedChange?.(next);
+    },
+    [isControlled, onCollapsedChange]
+  );
+  const toggle = useCallback2(() => {
+    setCollapsed(!collapsed);
+  }, [collapsed, setCollapsed]);
+  return { collapsed, setCollapsed, toggle };
+}
+
+// src/components/nav-row.tsx
+import * as React4 from "react";
+import { Slot as Slot2 } from "@radix-ui/react-slot";
+import { Fragment as Fragment2, jsx as jsx4, jsxs as jsxs3 } from "react/jsx-runtime";
+var base = "flex w-full items-center text-left text-sm transition-colors focus-visible:outline-none";
+var ring = "focus-visible:ring-2 focus-visible:ring-border-focus";
+var plate = "relative isolate after:pointer-events-none after:absolute after:inset-x-1.5 after:inset-y-1 after:-z-10 after:rounded-lg";
+var shape = {
+  rail: `gap-[14px] rounded-xl px-2.5 py-2 ${ring}`,
+  menu: `gap-2 rounded-md px-2 py-1.5 ${ring}`,
+  card: `gap-3 px-4 py-3 ${plate} focus-visible:after:ring-2 focus-visible:after:ring-inset focus-visible:after:ring-border-focus`
+};
+var state = {
+  rail: {
+    idle: "font-medium text-text-secondary hover:bg-[var(--hov-bg)] hover:text-text-primary",
+    active: "bg-bg-sunken font-semibold text-text-primary"
+  },
+  menu: {
+    idle: "font-medium text-text-secondary hover:bg-[var(--menu-hov)]",
+    active: "font-semibold text-text-brand hover:bg-[var(--menu-hov)]"
+  },
+  // A settings line reads as a label, not as navigation, so it idles at the body weight the rest of
+  // the card is set in — and never marks itself current, because it isn't.
+  card: {
+    idle: "text-text-primary hover:after:bg-bg-elevated",
+    active: "text-text-primary hover:after:bg-bg-elevated"
+  }
+};
+var NavRow = React4.forwardRef(function NavRow2({ icon, label, sub, active = false, variant, trailing, mutedTrailing = false, hideLabel = false, asChild = false, className, children, ...props }, ref) {
+  const card = variant === "card";
+  const content = /* @__PURE__ */ jsxs3(Fragment2, { children: [
+    Boolean(icon) && /* @__PURE__ */ jsx4(
+      "span",
+      {
+        className: cn(
+          "flex shrink-0 items-center justify-center",
+          card ? "size-4 text-text-tertiary [&_svg]:size-4" : "size-5 [&_svg]:size-[18px]"
+        ),
+        "aria-hidden": "true",
+        children: icon
+      }
+    ),
+    !hideLabel && (card ? /* @__PURE__ */ jsxs3("span", { className: "min-w-0 flex-1", children: [
+      /* @__PURE__ */ jsx4("span", { className: "block truncate", children: label }),
+      Boolean(sub) && /* @__PURE__ */ jsx4("span", { className: "block truncate text-xs text-text-secondary", children: sub })
+    ] }) : /* @__PURE__ */ jsx4("span", { className: "min-w-0 flex-1 truncate", children: label })),
+    Boolean(trailing) && /* @__PURE__ */ jsx4(
+      "span",
+      {
+        className: cn(
+          "flex shrink-0 items-center",
+          mutedTrailing ? "text-text-tertiary" : card && "text-text-secondary"
+        ),
+        children: trailing
+      }
+    ),
+    card && /* @__PURE__ */ jsx4("span", { className: "size-4 shrink-0", "aria-hidden": "true" })
+  ] });
+  const classes = cn(base, shape[variant], state[variant][active ? "active" : "idle"], className);
+  if (asChild) {
+    const child = React4.Children.only(children);
+    return /* @__PURE__ */ jsx4(Slot2, { ref, className: classes, "aria-label": hideLabel ? label : void 0, ...props, children: React4.cloneElement(child, void 0, content) });
+  }
+  return /* @__PURE__ */ jsx4("button", { ref, type: "button", className: classes, "aria-label": hideLabel ? label : void 0, ...props, children: content });
+});
+NavRow.displayName = "NavRow";
+
+export {
+  cn,
+  buttonVariants,
+  Button,
+  TooltipProvider,
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+  Sheet,
+  SheetTrigger,
+  SheetClose,
+  SheetPortal,
+  SheetOverlay,
+  SheetContent,
+  SheetHeader,
+  SheetFooter,
+  SheetTitle,
+  SheetDescription,
+  useIsMobile,
+  useSidebar,
+  NavRow
+};