@cosmoops/connect-sdk 0.9.0 → 0.16.0

package/dist/esm/client/components/plan-pricing.js

@@ -31,6 +31,31 @@ export function formatPrice(paise) {
 export function monthlyOf(price, billingInterval) {
     return billingInterval === "annual" ? price / 12 : price;
 }
+/**
+ * How to name a plan's cadence, in the three forms the plan screens need.
+ *
+ * One table rather than a `=== "annual" ? "year" : "month"` at each call site.
+ * That ternary was correct while there were two intervals and quietly became
+ * wrong when `"one-time"` arrived: a plan paid for once was labelled
+ * "per month", which is not a rendering imperfection but a false price.
+ */
+const INTERVAL_LABELS = {
+    monthly: { per: "month", short: "mo", adverb: "monthly" },
+    annual: { per: "year", short: "yr", adverb: "annually" },
+    // "once" reads correctly in all three positions a cadence appears in -
+    // "₹4,999 once", "Total once", "Only sold once".
+    "one-time": { per: "once", short: "once", adverb: "once" },
+};
+export function intervalLabel(billingInterval) {
+    return INTERVAL_LABELS[billingInterval];
+}
+/**
+ * `/month`, `/year` - and nothing at all for a one-time plan, where a price
+ * with no slash is the honest rendering.
+ */
+export function pricePerLabel(billingInterval) {
+    return billingInterval === "one-time" ? "" : `/${INTERVAL_LABELS[billingInterval].per}`;
+}
 export function discountLabel(discount) {
     const amount = discount.discountType === "percentage" ? `${discount.value}% off` : `${formatPrice(discount.value)} off`;
     if (discount.duration === "forever")

package/dist/esm/client/components/plans.js

@@ -7,7 +7,7 @@ import { useConnect, useConnectEntitlements, useConnectPlans } from "../provider
 import { buildCancelUrl, buildCheckoutUrl, useConnectCheckout, } from "../use-checkout.js";
 import { AnimatePresence, ENTER, m, MotionProvider } from "./motion.js";
 import { ConnectSubscribeDialog } from "./subscribe-dialog.js";
-import { ACTION_LABEL, discountLabel, formatPrice, groupPlansByTier, resolveAction, } from "./plan-pricing.js";
+import { ACTION_LABEL, discountLabel, formatPrice, groupPlansByTier, intervalLabel, pricePerLabel, resolveAction, } from "./plan-pricing.js";
 /**
  * The plan table: monthly/annual toggle, features, add-ons, the discount
  * actually in effect, and the subscribe / upgrade / downgrade flows.
@@ -123,7 +123,7 @@ export function ConnectPlans({ planIds, hideCoupon = false, className }) {
                             (tier.monthly?.id === subscription.plan.id || tier.annual?.id === subscription.plan.id);
                         const isCurrent = action === "current";
                         const cadenceUnavailable = showAnnual ? tier.annual === null : tier.monthly === null;
-                        return (_jsx(m.div, { variants: { hidden: { opacity: 0, y: 12 }, show: { opacity: 1, y: 0, transition: ENTER } }, children: _jsxs(Card, { className: isCurrentTier ? "h-full border-accent" : "h-full", children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsx(Card.Title, { children: tier.name }), _jsxs("div", { className: "flex shrink-0 items-center gap-1.5", children: [tier.annualSavingPercent !== null && showAnnual && (_jsxs(Chip, { className: "bg-accent-soft text-accent", children: ["Save ", tier.annualSavingPercent, "%"] })), isCurrentTier && _jsx(Chip, { className: "bg-accent-soft text-accent", children: "Current" })] })] }), tier.description && _jsx(Card.Description, { children: tier.description })] }), _jsxs(Card.Content, { className: "flex flex-col gap-4", children: [_jsxs("div", { children: [_jsx(AnimatePresence, { mode: "popLayout", initial: false, children: _jsxs(m.div, { initial: { opacity: 0, y: 6 }, animate: { opacity: 1, y: 0 }, exit: { opacity: 0, y: -6 }, transition: { duration: 0.15 }, children: [_jsx("span", { className: "text-2xl font-semibold text-foreground", children: formatPrice(plan.price) }), _jsxs("span", { className: "text-sm text-muted", children: ["/", plan.billingInterval === "annual" ? "year" : "month"] })] }, plan.billingInterval) }), _jsxs("p", { className: "mt-1 text-xs text-muted", children: ["+", plan.gstRate, "% GST"] }), cadenceUnavailable && (_jsxs("p", { className: "mt-1 text-xs text-muted", children: ["Only sold ", plan.billingInterval === "annual" ? "annually" : "monthly", "."] }))] }), plan.trialDays ? (_jsxs("p", { className: "text-xs font-medium text-accent", children: [plan.trialDays, "-day free trial"] })) : null, plan.features.length > 0 && (_jsx("ul", { className: "flex flex-col gap-1.5", children: plan.features.map((feature) => (
+                        return (_jsx(m.div, { variants: { hidden: { opacity: 0, y: 12 }, show: { opacity: 1, y: 0, transition: ENTER } }, children: _jsxs(Card, { className: isCurrentTier ? "h-full border-accent" : "h-full", children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsx(Card.Title, { children: tier.name }), _jsxs("div", { className: "flex shrink-0 items-center gap-1.5", children: [tier.annualSavingPercent !== null && showAnnual && (_jsxs(Chip, { className: "bg-accent-soft text-accent", children: ["Save ", tier.annualSavingPercent, "%"] })), isCurrentTier && _jsx(Chip, { className: "bg-accent-soft text-accent", children: "Current" })] })] }), tier.description && _jsx(Card.Description, { children: tier.description })] }), _jsxs(Card.Content, { className: "flex flex-col gap-4", children: [_jsxs("div", { children: [_jsx(AnimatePresence, { mode: "popLayout", initial: false, children: _jsxs(m.div, { initial: { opacity: 0, y: 6 }, animate: { opacity: 1, y: 0 }, exit: { opacity: 0, y: -6 }, transition: { duration: 0.15 }, children: [_jsx("span", { className: "text-2xl font-semibold text-foreground", children: formatPrice(plan.price) }), _jsx("span", { className: "text-sm text-muted", children: pricePerLabel(plan.billingInterval) })] }, plan.billingInterval) }), _jsxs("p", { className: "mt-1 text-xs text-muted", children: ["+", plan.gstRate, "% GST"] }), cadenceUnavailable && (_jsxs("p", { className: "mt-1 text-xs text-muted", children: ["Only sold ", intervalLabel(plan.billingInterval).adverb, "."] }))] }), plan.trialDays ? (_jsxs("p", { className: "text-xs font-medium text-accent", children: [plan.trialDays, "-day free trial"] })) : null, plan.features.length > 0 && (_jsx("ul", { className: "flex flex-col gap-1.5", children: plan.features.map((feature) => (
                                                 // `name`, not `key` - the key is an identifier
                                                 // ("campaign-module"), and printing it here is what this
                                                 // card used to do. The description rides along as a

package/dist/esm/client/components/platform-gate.js

@@ -0,0 +1,45 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useConnectPlatformAccess } from "../provider.js";
+/**
+ * Renders `children` only for a Connect platform staff session.
+ *
+ * ```tsx
+ * <ConnectPlatformGate>
+ *   <LinkMasterConsole />
+ * </ConnectPlatformGate>
+ * ```
+ *
+ * Staff are Connect's own operators - `platform_admin`, `platform_manager`,
+ * `developer` - signing into *your* application. They belong to no workspace,
+ * so a staff session carries no `workspaceId`, no subscription and no member
+ * role; see `SessionAccess.staff`. Staff access is off by default and turned on
+ * per application by a Connect platform admin, so this gate renders nothing
+ * until that happens.
+ *
+ * **This is a UX gate, not a security boundary** - the same caveat every gate
+ * in this package carries, and it matters more here than anywhere else,
+ * because what is behind this one is usually an operator console. The browser
+ * can ignore this component entirely. Every route it reveals must re-check
+ * `staff` on your own server:
+ *
+ * ```ts
+ * const { staff, role } = await client.identity.getUser(sessionToken);
+ * if (!staff) return forbidden();
+ * ```
+ *
+ * Renders `loading` - not `fallback` - while the session is unknown, so an
+ * operator never flickers through the customer layout on the way in.
+ */
+export function ConnectPlatformGate({ roles, children, fallback = null, loading = null, }) {
+    const { isStaff, roles: held, isLoading } = useConnectPlatformAccess();
+    if (isLoading)
+        return _jsx(_Fragment, { children: loading });
+    if (!isStaff)
+        return _jsx(_Fragment, { children: fallback });
+    // An empty `roles` array is treated as "no constraint", same as omitting it.
+    // The alternative - refusing everyone - would turn a `roles={[]}` computed
+    // from an empty config into a silently dead console.
+    const accepted = !roles || roles.length === 0 || roles.some((role) => held.includes(role));
+    return _jsx(_Fragment, { children: accepted ? children : fallback });
+}

package/dist/esm/client/components/shell-context.js

@@ -0,0 +1,141 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use } from "react";
+import { m } from "./motion.js";
+/** A plain anchor - correct anywhere, and a full page load. See `ConnectLinkRenderer`. */
+export const defaultRenderLink = ({ children, ...props }) => _jsx("a", { ...props, children: children });
+/**
+ * The rail's two widths, in pixels, and the one place they are written down.
+ *
+ * They are numbers rather than Tailwind classes because the rail animates
+ * between them - `motion` interpolates a number and cannot interpolate
+ * `w-16` into `w-64`.
+ *
+ * **The pairing is load-bearing, not arbitrary.** Every row in the sidebar is
+ * laid out so its glyph sits exactly `RAIL_GUTTER + ROW_GUTTER + 10px` from
+ * the rail's left edge - 32px, which is also `RAIL_COLLAPSED / 2`. So the
+ * collapsed rail centres every icon *without a single centring rule*, and
+ * nothing moves horizontally while the width animates. Change either width
+ * and that identity breaks: the icons drift sideways during the transition,
+ * which is the exact stutter this geometry exists to avoid.
+ */
+export const RAIL_COLLAPSED = 64;
+export const RAIL_EXPANDED = 264;
+/** Horizontal padding inside the rail, on every region. Tailwind `px-3`. */
+export const RAIL_GUTTER = 12;
+/**
+ * The row shape every sidebar control shares - nav items, the workspace tile,
+ * the launcher, the user button.
+ *
+ * `overflow-hidden` + `whitespace-nowrap` is what makes the collapse smooth:
+ * the label is *clipped* by the shrinking rail rather than re-wrapped or
+ * re-measured, so a width animation costs no reflow. Fading the label with
+ * `SidebarLabel` on top of that hides the clip itself.
+ */
+export const SIDEBAR_ROW = "group/row relative flex h-10 w-full shrink-0 items-center justify-start gap-3 overflow-hidden whitespace-nowrap rounded-lg pe-2 text-sm font-normal transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
+/**
+ * Leading inset for a row whose glyph is 20px wide (a nav icon, the launcher).
+ * `10 + 10 = 20`, and `RAIL_GUTTER + 20 = 32`. See `RAIL_COLLAPSED`.
+ */
+export const SIDEBAR_ROW_ICON = "ps-[10px]";
+/**
+ * Leading inset for a row whose glyph is 32px wide (the avatar, the workspace
+ * tile). `4 + 16 = 20`, landing on the same 32px centre as `SIDEBAR_ROW_ICON`.
+ */
+export const SIDEBAR_ROW_TILE = "ps-[4px]";
+/**
+ * The class list for one sidebar row, in one place.
+ *
+ * Three different elements need it - a plain `<button>` (`ConnectSidebarRow`),
+ * a rendered link (`ConnectSidebarNav`), and a HeroUI `<Button>` acting as a
+ * `Modal`/`Dropdown` trigger (the account row, the launcher, the workspace
+ * tile). They cannot share a component, because a React Aria overlay has to
+ * own its own trigger element - so they share this instead. A second copy of
+ * the string is a row that drifts off the 32px centre and takes the collapse
+ * animation's smoothness with it.
+ *
+ * On the HeroUI trigger: these are all Tailwind *utilities*, and HeroUI's
+ * `.button` is a component class, so the utility layer wins - which is what
+ * lets a `w-fit`, centred, `px-`-padded button take this shape at all.
+ */
+export function sidebarRowClass(options) {
+    // The rail's two text tones, and both were wrong before.
+    //
+    // **Resting rows are `muted`, not `foreground`.** Against `--surface`,
+    // `--foreground` measures 17.6:1 in light and 15.8:1 in dark - body-copy
+    // weight, applied to eight items at once, in a column whose whole job is to
+    // sit still at the edge of the screen. The result reads as heavy and, worse,
+    // gives every inactive destination exactly the emphasis of the active one,
+    // so the selected row has to win on background alone. `--muted` is 4.8:1
+    // light and 6.2:1 dark - comfortably past AA for normal text, and quiet
+    // enough that "where am I" is answerable at a glance. Hover restores
+    // `foreground`, so pointing at a row is what brings it forward.
+    //
+    // **The active row uses `accent-soft-foreground`, never `accent`.**
+    // `text-accent` on `bg-accent-soft` is 2.8:1 in light and 4.0:1 in dark -
+    // both below AA, on the one row the user most needs to read. HeroUI derives
+    // `--accent-soft-foreground` for exactly this pairing (a color-mix of accent
+    // into foreground), which measures 4.8:1 and 5.6:1. It is derived rather
+    // than fixed, so a host that re-themes `--accent` keeps the contrast.
+    //
+    // **`bg-transparent` is not redundant.** Three of these rows are HeroUI
+    // `<Button variant="tertiary">` (the launcher, the account row, the
+    // workspace tile) because they trigger a `Modal` or a `Dropdown`, and
+    // `.button--tertiary` sets `--button-bg: var(--default)` - a real fill. Next
+    // to the plain anchors the nav renders, those three came out looking
+    // permanently hovered, as though three rows in the rail were selected at
+    // once. Only the resting tone clears it; the active tone paints its own.
+    const tone = options?.active
+        ? "bg-accent-soft font-medium text-accent-soft-foreground"
+        : "bg-transparent text-muted hover:bg-surface-secondary hover:text-foreground";
+    return [SIDEBAR_ROW, options?.tile ? SIDEBAR_ROW_TILE : SIDEBAR_ROW_ICON, tone, options?.className]
+        .filter(Boolean)
+        .join(" ");
+}
+const FALLBACK = {
+    collapsed: false,
+    collapsible: false,
+    setCollapsed: () => { },
+    renderLink: defaultRenderLink,
+};
+const ShellContext = createContext(null);
+/**
+ * Shared state for every part of the shell, so `ConnectSidebarNav`,
+ * `ConnectWorkspaceSwitcher` and `ConnectUserButton` all know whether the rail
+ * is collapsed without the host threading a prop through three layers.
+ *
+ * This is the piece that makes the shell *composable* rather than only
+ * configurable: the parts are exported and can be rearranged, and they still
+ * agree about collapse, routing and the mobile drawer because they read one
+ * context instead of one another's props.
+ */
+export function ConnectShellProvider({ value, children, }) {
+    return _jsx(ShellContext, { value: value, children: children });
+}
+/**
+ * The shell state a sidebar part is rendering inside.
+ *
+ * Falls back to "expanded, not collapsible, plain anchors" rather than
+ * throwing, because every part is also exported for use *outside* a shell -
+ * a host dropping `ConnectSidebarNav` into a layout it already owns should
+ * not have to mount a provider to get a nav column.
+ */
+export function useConnectShell() {
+    return use(ShellContext) ?? FALLBACK;
+}
+/**
+ * A sidebar row's text, faded out as the rail collapses.
+ *
+ * Opacity only - never width, height or margin. The rail's own width
+ * animation already moves the clip edge past this text; animating the text's
+ * box as well would make two things fight over the same pixels and is what
+ * makes a collapsing sidebar look like it stutters.
+ *
+ * Asymmetric timing on purpose. Collapsing, the label leaves *first* (no
+ * delay, quick) so the rail never appears to squeeze text; expanding, it
+ * arrives *after* the rail has opened enough to hold it.
+ */
+export function SidebarLabel({ children, className, }) {
+    const { collapsed } = useConnectShell();
+    return (_jsx(m.span, { className: `min-w-0 flex-1 truncate text-start ${className ?? ""}`, animate: { opacity: collapsed ? 0 : 1 }, transition: collapsed ? { duration: 0.1 } : { duration: 0.18, delay: 0.1 }, "aria-hidden": collapsed, children: children }));
+}

package/dist/esm/client/components/side-nav.js

@@ -1,53 +1,80 @@
 "use client";
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Tooltip } from "@heroui/react";
 import { ArrowUpRight } from "lucide-react";
+import { m } from "./motion.js";
+import { SidebarLabel, defaultRenderLink, sidebarRowClass, useConnectShell } from "./shell-context.js";
 import { useActivePath } from "../use-active-path.js";
 import { isNavItemActive, normalizeNav, resolveActivePath, } from "./nav.js";
-/** A plain anchor - correct anywhere, and a full page load. See `ConnectLinkRenderer`. */
-export const defaultRenderLink = ({ children, ...props }) => _jsx("a", { ...props, children: children });
-const ROW = "group relative flex items-center rounded-lg text-sm transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
-function rowClass(isActive, collapsed, depth) {
-    const shape = collapsed ? "size-10 justify-center" : `min-h-9 justify-start gap-3 px-3 py-2 ${depth > 0 ? "ml-4" : ""}`;
-    const tone = isActive
-        ? "bg-accent-soft font-medium text-accent"
-        : "text-foreground hover:bg-surface-secondary";
-    return `${ROW} ${shape} ${tone}`;
+export { defaultRenderLink };
+function rowClass(isActive, depth) {
+    // The indent is a *margin*, not padding, so a child row steps in while the
+    // glyph inside it keeps the shared 32px centre every other row uses.
+    return sidebarRowClass({
+        active: isActive,
+        className: depth > 0 ? "ms-4 w-[calc(100%-1rem)]" : undefined,
+    });
 }
 function NavRow({ item, isActive, hasActiveChild, collapsed, depth, renderLink, onNavigate, }) {
     const linkProps = {
         href: item.href,
-        className: rowClass(isActive, collapsed, depth),
+        className: rowClass(isActive, depth),
         "aria-label": item.label,
         "aria-current": isActive ? "page" : undefined,
         onClick: onNavigate,
         ...(item.external ? { target: "_blank", rel: "noopener noreferrer" } : {}),
-        children: (_jsxs(_Fragment, { children: [item.icon && _jsx("span", { className: "relative flex size-5 shrink-0 items-center justify-center", children: item.icon }), !collapsed && _jsx("span", { className: "relative flex-1 truncate", children: item.label }), !collapsed && item.badge, !collapsed && item.external && (_jsx(ArrowUpRight, { className: "size-3.5 shrink-0 text-muted", "aria-hidden": "true" })), collapsed && hasActiveChild && !isActive && (_jsx("span", { "aria-hidden": "true", className: "absolute bottom-1 size-1 rounded-full bg-accent" }))] })),
+        children: (_jsxs(_Fragment, { children: [_jsx("span", { className: "flex size-5 shrink-0 items-center justify-center", children: item.icon }), _jsx(SidebarLabel, { children: item.label }), (item.badge || item.external) && (_jsxs(m.span, { className: "flex shrink-0 items-center gap-1", animate: { opacity: collapsed ? 0 : 1 }, transition: collapsed ? { duration: 0.1 } : { duration: 0.18, delay: 0.1 }, "aria-hidden": collapsed, children: [item.badge, item.external && _jsx(ArrowUpRight, { className: "size-3.5 text-muted", "aria-hidden": "true" })] })), collapsed && hasActiveChild && !isActive && (_jsx("span", { "aria-hidden": "true", className: "absolute bottom-1 start-[18px] size-1 rounded-full bg-accent" }))] })),
     };
     // The tooltip stays mounted across expand/collapse and only toggles
     // `isDisabled`. Branching into two trees instead re-creates every item's
     // overlay and focus machinery on each toggle, which is what makes the width
     // animation stutter.
-    return (_jsxs(Tooltip, { delay: 200, isDisabled: !collapsed, children: [_jsx(Tooltip.Trigger, { "aria-label": item.label, children: renderLink(linkProps) }), _jsx(Tooltip.Content, { placement: "right", children: item.label })] }));
+    return (_jsxs(Tooltip, { delay: 400, isDisabled: !collapsed, children: [_jsx(Tooltip.Trigger, { children: renderLink(linkProps) }), _jsx(Tooltip.Content, { placement: "right", children: item.label })] }));
+}
+/**
+ * A section heading that keeps its box when the rail collapses.
+ *
+ * The old rail swapped the heading for a hairline, which changed the group's
+ * height and made every row below it jump at the moment the width was already
+ * moving. Here the box is a constant height in both states: the text fades out
+ * and a rule fades in, in the same place.
+ */
+function SectionHeading({ title, collapsed }) {
+    return (_jsxs("div", { className: "relative flex h-7 shrink-0 items-center px-[10px]", children: [_jsx(m.h2, { className: "truncate text-xs font-semibold uppercase tracking-wider text-muted", animate: { opacity: collapsed ? 0 : 1 }, transition: collapsed ? { duration: 0.1 } : { duration: 0.18, delay: 0.1 }, "aria-hidden": collapsed, children: title }), _jsx(m.span, { "aria-hidden": "true", className: "absolute inset-x-[10px] top-1/2 h-px bg-separator", animate: { opacity: collapsed ? 1 : 0 }, transition: { duration: 0.15 } })] }));
 }
 /**
  * The sidebar's nav column on its own - sections, items, one level of
  * children, and the active highlight.
  *
  * `AppShell` renders this inside its rail and its mobile drawer, and it
- * is exported for a host that wants the shell's navigation without its
- * chrome: the same items, the same active resolution, dropped into a layout
- * you already have.
+ * is exported for a host that wants the shell's navigation without its chrome:
+ * the same items, the same active resolution, dropped into a layout you
+ * already have.
+ *
+ * Every prop is optional except `nav`, because inside a shell they are all
+ * inherited from it. Passing one wins over what the shell says - which is how
+ * a second nav column (see `secondaryNav`) can share the rail's collapse state
+ * while keeping its own items.
  */
-export function ConnectSideNav({ nav, activePath, renderLink = defaultRenderLink, collapsed = false, onNavigate, className, }) {
-    const pathname = useActivePath(activePath);
+export function ConnectSidebarNav({ nav, activePath, renderLink, collapsed, onNavigate, className, }) {
+    const shell = useConnectShell();
+    const isCollapsed = collapsed ?? shell.collapsed;
+    const link = renderLink ?? shell.renderLink;
+    const navigate = onNavigate ?? shell.onNavigate;
+    const pathname = useActivePath(activePath ?? shell.activePath);
     const active = resolveActivePath(pathname, nav);
     const sections = normalizeNav(nav);
-    return (_jsx("div", { className: `flex flex-col gap-4 ${className ?? ""}`, children: sections.map((section, index) => (_jsxs("nav", { "aria-label": section.title ?? "Main", className: `flex flex-col gap-1 ${collapsed ? "items-center" : ""}`, children: [section.title && !collapsed && (_jsx("h2", { className: "px-3 pb-1 text-xs font-semibold uppercase tracking-wider text-muted", children: section.title })), section.title && collapsed && index > 0 && _jsx("span", { className: "my-1 h-px w-6 bg-separator", "aria-hidden": "true" }), section.items.map((item) => {
+    return (_jsx("div", { className: `flex flex-col gap-2 ${className ?? ""}`, children: sections.map((section, index) => (_jsxs("nav", { "aria-label": section.title ?? "Main", className: "flex flex-col gap-1", children: [section.title && _jsx(SectionHeading, { title: section.title, collapsed: isCollapsed }), section.items.map((item) => {
                     const isActive = isNavItemActive(item, active);
                     const activeChild = (item.items ?? []).some((child) => isNavItemActive(child, active));
-                    return (_jsxs("div", { className: `flex flex-col gap-1 ${collapsed ? "" : "w-full"}`, children: [_jsx(NavRow, { item: item, isActive: isActive, hasActiveChild: activeChild, collapsed: collapsed, depth: 0, renderLink: renderLink, onNavigate: onNavigate }), !collapsed &&
+                    return (_jsxs("div", { className: "flex w-full flex-col gap-1", children: [_jsx(NavRow, { item: item, isActive: isActive, hasActiveChild: activeChild, collapsed: isCollapsed, depth: 0, renderLink: link, onNavigate: navigate }), !isCollapsed &&
                                 (isActive || activeChild) &&
-                                item.items?.map((child) => (_jsx(NavRow, { item: child, isActive: isNavItemActive(child, active), hasActiveChild: false, collapsed: false, depth: 1, renderLink: renderLink, onNavigate: onNavigate }, child.href)))] }, item.href));
+                                item.items?.map((child) => (_jsx(NavRow, { item: child, isActive: isNavItemActive(child, active), hasActiveChild: false, collapsed: false, depth: 1, renderLink: link, onNavigate: navigate }, child.href)))] }, item.href));
                 })] }, section.title ?? index))) }));
 }
+/**
+ * @deprecated Renamed to `ConnectSidebarNav` in 0.12 - the rail is a
+ * `ConnectSidebar` now, and its pieces are named after it. Identical
+ * behaviour; this alias will be removed in a later minor.
+ */
+export const ConnectSideNav = ConnectSidebarNav;

package/dist/esm/client/components/sidebar.js

@@ -0,0 +1,120 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Tooltip } from "@heroui/react";
+import { PanelLeftClose, PanelLeftOpen } from "lucide-react";
+import { ConnectLogo } from "./logo.js";
+import { EASE_OUT_QUART, MotionProvider, m } from "./motion.js";
+import { RAIL_COLLAPSED, RAIL_EXPANDED, SidebarLabel, sidebarRowClass, useConnectShell } from "./shell-context.js";
+/**
+ * The rail's own transition.
+ *
+ * A tween, not a spring. A spring overshoots, and an overshooting *width*
+ * drags every row's clip edge past its resting place and back - which reads as
+ * the labels wobbling. 240ms on `--ease-out-quart` is long enough to follow
+ * and short enough that hammering the toggle never queues a visible backlog.
+ */
+const RAIL_TRANSITION = { duration: 0.24, ease: EASE_OUT_QUART };
+/** The chrome fades a touch faster than the rail moves, so nothing is caught mid-clip. */
+const CHROME_TRANSITION = { duration: 0.15, ease: EASE_OUT_QUART };
+/** Label fade timing, shared by the header wordmark and `SidebarLabel`. */
+function labelTransition(collapsed) {
+    return collapsed ? { duration: 0.1 } : { duration: 0.18, delay: 0.1 };
+}
+/**
+ * The application rail: a fixed-width column that animates between an
+ * icon-only 64px and a labelled 264px.
+ *
+ * **Why width, and nothing else, animates.** Every row inside puts its glyph
+ * on the same 32px centre in both states (see `RAIL_COLLAPSED`), and every
+ * label is clipped rather than re-measured (see `SIDEBAR_ROW`). So the only
+ * property in flight is this element's width: no child moves, no text
+ * re-wraps, and there is no per-frame layout pass on the rows. That is why the
+ * collapse looks smooth rather than merely fast.
+ *
+ * Hidden below `md`. The mobile drawer renders the same children with
+ * `collapsed: false`, because a 64px icon rail on a phone is a worse drawer,
+ * not a smaller one.
+ */
+export function ConnectSidebar({ children, label = "Sidebar", className }) {
+    const { collapsed } = useConnectShell();
+    return (
+    // Its own motion root, even though `AppShell` already mounts one.
+    // `LazyMotion` nests harmlessly, and without it a host composing the rail
+    // from these parts by hand gets a sidebar that jumps between widths
+    // instead of animating - a failure that looks like a styling bug and is
+    // really a missing provider.
+    _jsx(MotionProvider, { children: _jsx(m.aside, { "aria-label": label, className: `hidden shrink-0 flex-col overflow-hidden border-e border-border bg-surface md:flex ${className ?? ""}`, 
+            // `initial={false}` is what stops the rail sweeping open on first paint
+            // for a returning user whose stored preference is "collapsed".
+            initial: false, animate: { width: collapsed ? RAIL_COLLAPSED : RAIL_EXPANDED }, transition: RAIL_TRANSITION, children: children }) }));
+}
+/**
+ * The brand row, and the rail's own expand/collapse control.
+ *
+ * **Two states, one DOM.** The badge is mounted once and never re-created; the
+ * wordmark fades beside it and the collapse button fades at the trailing edge.
+ * Swapping which *element* renders the brand would remount it halfway through
+ * the width animation and flicker.
+ *
+ * Collapsed, hovering or focusing the badge swaps it for the expand glyph, so
+ * the rail needs no permanent control eating a row. Expanded, the control sits
+ * at the header's trailing edge, where it can be aimed at without covering the
+ * brand. The swap is pure CSS on a `group` - hovering re-renders nothing,
+ * which is what keeps it instant.
+ *
+ * The trade this makes, deliberately: **collapsed, the lockup is no longer a
+ * link home.** It has become the expand control, and one target that navigates
+ * on click but expands on click-after-hover would be worse than either. Put
+ * home in the nav; every application already does.
+ */
+export function ConnectSidebarHeader({ name, icon, homeHref = "/" }) {
+    const { collapsed, collapsible, setCollapsed, renderLink } = useConnectShell();
+    const logoExpands = collapsible && collapsed;
+    return (_jsxs("div", { className: "relative flex h-14 shrink-0 items-center overflow-hidden px-3", children: [_jsxs("div", { className: "group/brand relative flex size-10 shrink-0 items-center justify-center", children: [renderLink({
+                        href: homeHref,
+                        className: `flex size-10 items-center justify-center rounded-lg transition-opacity focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus ${logoExpands ? "group-hover/brand:opacity-0 group-focus-within/brand:opacity-0" : ""}`,
+                        // `ConnectLogo` names itself with `role="img"`, which the `<a>` around
+                        // it does not inherit as its own accessible name.
+                        "aria-label": `${name} home`,
+                        children: _jsx(ConnectLogo, { name: name, icon: icon, variant: "mark" }),
+                    }), logoExpands && (_jsxs(Tooltip, { delay: 400, children: [_jsx(Tooltip.Trigger, { children: _jsx("button", { type: "button", "aria-label": "Expand sidebar", onClick: () => setCollapsed(false), className: "absolute inset-0 flex items-center justify-center rounded-lg text-muted opacity-0 transition-opacity hover:bg-surface-secondary hover:text-foreground focus-visible:opacity-100 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus group-hover/brand:opacity-100 group-focus-within/brand:opacity-100", children: _jsx(PanelLeftOpen, { className: "size-5" }) }) }), _jsx(Tooltip.Content, { placement: "right", children: "Expand sidebar" })] }))] }), _jsx(m.span, { className: "ms-2 min-w-0 flex-1 truncate", animate: { opacity: collapsed ? 0 : 1 }, transition: labelTransition(collapsed), "aria-hidden": true, children: _jsx(ConnectLogo, { name: name, icon: icon, variant: "wordmark" }) }), collapsible && (
+            // Absolutely positioned so it never takes part in the row's layout: in
+            // flow, `ms-auto` inside a 40px-wide collapsed row would shove the
+            // badge sideways for the length of the animation.
+            _jsx(m.div, { className: "absolute end-3 top-1/2 -translate-y-1/2", animate: { opacity: collapsed ? 0 : 1 }, transition: CHROME_TRANSITION, 
+                // A faded-out control must not be reachable by keyboard or pointer.
+                // `inert` says that in one attribute; `hidden` would remove it from
+                // flow and make the header re-layout on every toggle.
+                inert: collapsed, children: _jsxs(Tooltip, { delay: 400, children: [_jsx(Tooltip.Trigger, { children: _jsx("button", { type: "button", "aria-label": "Collapse sidebar", onClick: () => setCollapsed(true), className: "flex size-8 items-center justify-center rounded-lg text-muted transition-colors hover:bg-surface-secondary hover:text-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus", children: _jsx(PanelLeftClose, { className: "size-4" }) }) }), _jsx(Tooltip.Content, { placement: "right", children: "Collapse sidebar" })] }) }))] }));
+}
+/**
+ * The rail's scrolling region, for the primary navigation. Everything else in
+ * the sidebar is `shrink-0`, so this is the only part that ever gives way.
+ */
+export function ConnectSidebarBody({ children }) {
+    return (_jsx("div", { className: "flex min-h-0 flex-1 flex-col gap-1 overflow-y-auto overflow-x-hidden px-3 py-2", children: children }));
+}
+/**
+ * A pinned region at the foot of the rail - the secondary nav, the launcher,
+ * the account row.
+ *
+ * `separated` draws the hairline above it. The account row wants one; a
+ * secondary nav sitting directly on top of the account row does not, or the
+ * rail ends in two rules a few pixels apart.
+ */
+export function ConnectSidebarFooter({ children, separated = true, }) {
+    return (_jsx("div", { className: `flex shrink-0 flex-col gap-1 px-3 py-2 ${separated ? "border-t border-border" : ""}`, children: children }));
+}
+/**
+ * A pressable row in the rail that is not a nav item - the launcher, the
+ * account button, anything a host adds to the footer.
+ *
+ * Exported so a host's own row lines up with the SDK's. It applies the same
+ * 32px glyph centre and the same label fade, which is what stops a partner's
+ * "Help" row drifting sideways while every row above it holds still.
+ */
+export function ConnectSidebarRow({ icon, label, tile = false, trailing, className, "aria-label": ariaLabel, ...props }) {
+    const { collapsed } = useConnectShell();
+    const name = ariaLabel ?? (typeof label === "string" ? label : undefined);
+    return (_jsxs(Tooltip, { delay: 400, isDisabled: !collapsed, children: [_jsx(Tooltip.Trigger, { children: _jsxs("button", { type: "button", "aria-label": name, className: sidebarRowClass({ tile, className }), ...props, children: [_jsx("span", { className: `flex ${tile ? "size-8" : "size-5"} shrink-0 items-center justify-center`, children: icon }), _jsx(SidebarLabel, { children: label }), trailing] }) }), _jsx(Tooltip.Content, { placement: "right", children: name ?? label })] }));
+}

package/dist/esm/client/components/subscribe-dialog.js

@@ -2,13 +2,13 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Button, Modal } from "@heroui/react";
 import { ArrowRight, ExternalLink, Info } from "lucide-react";
-import { formatPrice, monthlyOf } from "./plan-pricing.js";
+import { formatPrice, intervalLabel, monthlyOf } from "./plan-pricing.js";
 /** GST is quoted exclusive everywhere in Connect; this is the same arithmetic `calculateGST` does server-side. */
 function withGst(price, gstRate) {
     return price + Math.round(price * (gstRate / 100));
 }
 function cadenceOf(plan) {
-    return plan.billingInterval === "annual" ? "year" : "month";
+    return intervalLabel(plan.billingInterval).per;
 }
 const HEADING = {
     subscribe: "Confirm subscription",
@@ -47,7 +47,7 @@ export function ConnectSubscribeDialog({ plan, action, current, coupon, onClose,
     // member and the one most in need of it: the two prices differ by an order
     // of magnitude, and showing only the new one reads as a price rise.
     const isChange = action === "upgrade" || action === "downgrade" || isIntervalSwitch;
-    return (_jsx(Modal.Backdrop, { isOpen: plan !== null, onOpenChange: (open) => !open && onClose(), children: _jsx(Modal.Container, { size: "sm", children: _jsxs(Modal.Dialog, { children: [_jsx(Modal.CloseTrigger, { onPress: onClose }), _jsx(Modal.Header, { children: _jsx(Modal.Heading, { children: HEADING[action] }) }), plan && (_jsxs(_Fragment, { children: [_jsxs(Modal.Body, { className: "flex flex-col gap-4", children: [isChange && currentPlan ? (_jsxs("div", { className: "flex items-center gap-3 text-sm", children: [_jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "truncate text-muted", children: currentPlan.name }), _jsxs("p", { className: "text-xs text-muted", children: [formatPrice(currentPlan.price), "/", currentPlan.billingInterval === "annual" ? "yr" : "mo"] })] }), _jsx(ArrowRight, { className: "size-4 shrink-0 text-muted", "aria-hidden": "true" }), _jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "truncate font-medium text-foreground", children: plan.name }), _jsxs("p", { className: "text-xs text-muted", children: [formatPrice(plan.price), "/", plan.billingInterval === "annual" ? "yr" : "mo"] })] })] })) : (_jsxs("div", { children: [_jsx("p", { className: "font-medium text-foreground", children: plan.name }), plan.description && _jsx("p", { className: "text-xs text-muted", children: plan.description })] })), _jsxs("div", { className: "flex flex-col gap-1 border-t border-separator pt-3 text-sm", children: [_jsxs("div", { className: "flex justify-between text-muted", children: [_jsx("span", { children: plan.name }), _jsx("span", { children: formatPrice(plan.price) })] }), _jsxs("div", { className: "flex justify-between text-muted", children: [_jsxs("span", { children: ["GST (", plan.gstRate, "%)"] }), _jsx("span", { children: formatPrice(withGst(plan.price, plan.gstRate) - plan.price) })] }), _jsxs("div", { className: "flex justify-between border-t border-separator pt-1 font-semibold text-foreground", children: [_jsxs("span", { children: ["Per ", cadenceOf(plan)] }), _jsx("span", { children: formatPrice(withGst(plan.price, plan.gstRate)) })] }), plan.billingInterval === "annual" && (_jsxs("p", { className: "text-xs text-muted", children: ["Works out to ", formatPrice(monthlyOf(withGst(plan.price, plan.gstRate), "annual")), " a month, billed yearly."] }))] }), plan.trialDays ? (_jsxs("p", { className: "text-xs text-accent", children: [plan.trialDays, "-day free trial, if this workspace has not subscribed to this application before."] })) : null, coupon?.trim() ? (_jsxs("p", { className: "text-xs text-muted", children: ["Coupon ", _jsx("span", { className: "font-mono text-foreground", children: coupon.trim() }), " is carried over and validated on Connect."] })) : null, _jsxs("div", { className: "flex gap-2 rounded-lg bg-surface p-3 text-xs text-muted", children: [_jsx(Info, { className: "mt-0.5 size-4 shrink-0", "aria-hidden": "true" }), _jsxs("div", { className: "flex flex-col gap-1", children: [action === "subscribe" && (_jsx("p", { children: "Payment is completed on Connect, where your card or UPI mandate is set up and the tax invoice is issued. This page updates by itself once it is done." })), action === "upgrade" && (_jsxs("p", { children: ["Connect prices the difference for the days left in your current cycle and collects just that amount now. From the next cycle you are billed the ", plan.name, " rate."] })), action === "downgrade" && (_jsx("p", { children: "You keep what you have paid for. Connect works out the unused part of this cycle and applies it as credit or a refund, depending on how this application is configured." })), isIntervalSwitch && (
+    return (_jsx(Modal.Backdrop, { isOpen: plan !== null, onOpenChange: (open) => !open && onClose(), children: _jsx(Modal.Container, { size: "sm", children: _jsxs(Modal.Dialog, { children: [_jsx(Modal.CloseTrigger, { onPress: onClose }), _jsx(Modal.Header, { children: _jsx(Modal.Heading, { children: HEADING[action] }) }), plan && (_jsxs(_Fragment, { children: [_jsxs(Modal.Body, { className: "flex flex-col gap-4", children: [isChange && currentPlan ? (_jsxs("div", { className: "flex items-center gap-3 text-sm", children: [_jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "truncate text-muted", children: currentPlan.name }), _jsxs("p", { className: "text-xs text-muted", children: [formatPrice(currentPlan.price), "/", intervalLabel(currentPlan.billingInterval).short] })] }), _jsx(ArrowRight, { className: "size-4 shrink-0 text-muted", "aria-hidden": "true" }), _jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "truncate font-medium text-foreground", children: plan.name }), _jsxs("p", { className: "text-xs text-muted", children: [formatPrice(plan.price), "/", intervalLabel(plan.billingInterval).short] })] })] })) : (_jsxs("div", { children: [_jsx("p", { className: "font-medium text-foreground", children: plan.name }), plan.description && _jsx("p", { className: "text-xs text-muted", children: plan.description })] })), _jsxs("div", { className: "flex flex-col gap-1 border-t border-separator pt-3 text-sm", children: [_jsxs("div", { className: "flex justify-between text-muted", children: [_jsx("span", { children: plan.name }), _jsx("span", { children: formatPrice(plan.price) })] }), _jsxs("div", { className: "flex justify-between text-muted", children: [_jsxs("span", { children: ["GST (", plan.gstRate, "%)"] }), _jsx("span", { children: formatPrice(withGst(plan.price, plan.gstRate) - plan.price) })] }), _jsxs("div", { className: "flex justify-between border-t border-separator pt-1 font-semibold text-foreground", children: [_jsxs("span", { children: ["Per ", cadenceOf(plan)] }), _jsx("span", { children: formatPrice(withGst(plan.price, plan.gstRate)) })] }), plan.billingInterval === "annual" && (_jsxs("p", { className: "text-xs text-muted", children: ["Works out to ", formatPrice(monthlyOf(withGst(plan.price, plan.gstRate), "annual")), " a month, billed yearly."] }))] }), plan.trialDays ? (_jsxs("p", { className: "text-xs text-accent", children: [plan.trialDays, "-day free trial, if this workspace has not subscribed to this application before."] })) : null, coupon?.trim() ? (_jsxs("p", { className: "text-xs text-muted", children: ["Coupon ", _jsx("span", { className: "font-mono text-foreground", children: coupon.trim() }), " is carried over and validated on Connect."] })) : null, _jsxs("div", { className: "flex gap-2 rounded-lg bg-surface p-3 text-xs text-muted", children: [_jsx(Info, { className: "mt-0.5 size-4 shrink-0", "aria-hidden": "true" }), _jsxs("div", { className: "flex flex-col gap-1", children: [action === "subscribe" && (_jsx("p", { children: "Payment is completed on Connect, where your card or UPI mandate is set up and the tax invoice is issued. This page updates by itself once it is done." })), action === "upgrade" && (_jsxs("p", { children: ["Connect prices the difference for the days left in your current cycle and collects just that amount now. From the next cycle you are billed the ", plan.name, " rate."] })), action === "downgrade" && (_jsx("p", { children: "You keep what you have paid for. Connect works out the unused part of this cycle and applies it as credit or a refund, depending on how this application is configured." })), isIntervalSwitch && (
                                                     // Not a proration. The cycle you are on ends, so this is
                                                     // the one action where the amount collected can exceed a
                                                     // single cycle's list price - or be nothing at all, with

package/dist/esm/client/components/subscription.js

@@ -4,7 +4,7 @@ import { Button, Card, Chip, Skeleton } from "@heroui/react";
 import { AlertTriangle, ArrowRight, Clock, CreditCard, ExternalLink, Users } from "lucide-react";
 import { useConnect, useConnectEntitlements } from "../provider.js";
 import { m, MotionProvider } from "./motion.js";
-import { formatPrice } from "./plan-pricing.js";
+import { formatPrice, intervalLabel } from "./plan-pricing.js";
 import { ConnectLinkButton } from "./link-button.js";
 /** Where the plan catalogue lives in the host app. Overridable, because not every app mounts it at `/plans`. */
 const DEFAULT_PLANS_HREF = "/plans";
@@ -77,7 +77,7 @@ export function ConnectSubscriptionCard({ plansHref, className }) {
         return _jsx(Skeleton, { className: `h-48 rounded-xl ${className ?? ""}` });
     if (!detail || !plan)
         return _jsx(ConnectNoSubscriptionCard, { plansHref: plansHref, className: className });
-    return (_jsx(MotionProvider, { children: _jsx(m.div, { initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { duration: 0.2 }, children: _jsxs(Card, { className: className, children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsx(Card.Title, { children: plan.name }), _jsx(SubscriptionChip, { state: state })] }), _jsxs(Card.Description, { children: [formatPrice(plan.price), " + ", plan.gstRate, "% GST per", " ", plan.billingInterval === "annual" ? "year" : "month"] })] }), _jsxs(Card.Content, { className: "flex flex-col gap-2 text-sm", children: [_jsx(NextEvent, { detail: detail, state: state }), _jsx(ConnectSeatUsage, { plan: plan, detail: detail })] }), _jsxs(Card.Footer, { className: "flex flex-wrap gap-2", children: [_jsxs(Button, { variant: "secondary", onPress: () => window.open(`${appUrl}/billing/subscriptions/${detail.id}`, "_blank", "noopener,noreferrer"), children: ["Manage on Connect", _jsx(ExternalLink, { className: "size-3.5" })] }), _jsx(ConnectLinkButton, { href: plansHref ?? DEFAULT_PLANS_HREF, variant: "tertiary", children: "Change plan" })] })] }) }) }));
+    return (_jsx(MotionProvider, { children: _jsx(m.div, { initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { duration: 0.2 }, children: _jsxs(Card, { className: className, children: [_jsxs(Card.Header, { children: [_jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsx(Card.Title, { children: plan.name }), _jsx(SubscriptionChip, { state: state })] }), _jsxs(Card.Description, { children: [formatPrice(plan.price), " + ", plan.gstRate, "% GST per", " ", intervalLabel(plan.billingInterval).per] })] }), _jsxs(Card.Content, { className: "flex flex-col gap-2 text-sm", children: [_jsx(NextEvent, { detail: detail, state: state }), _jsx(ConnectSeatUsage, { plan: plan, detail: detail })] }), _jsxs(Card.Footer, { className: "flex flex-wrap gap-2", children: [_jsxs(Button, { variant: "secondary", onPress: () => window.open(`${appUrl}/billing/subscriptions/${detail.id}`, "_blank", "noopener,noreferrer"), children: ["Manage on Connect", _jsx(ExternalLink, { className: "size-3.5" })] }), _jsx(ConnectLinkButton, { href: plansHref ?? DEFAULT_PLANS_HREF, variant: "tertiary", children: "Change plan" })] })] }) }) }));
 }
 function SubscriptionChip({ state }) {
     switch (state) {