@cboxdk/cbox-ui 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentProps, ComponentType } from 'react';
 import { LucideIcon } from 'lucide-react';
 import { ClassValue } from 'clsx';
+export { T as TimePoint, n as niceTicks, t as timeTicks } from './scale-BaaY5qJs.js';
 
 /**
  * Identity contract every Cbox-family app must populate.
@@ -22,7 +23,8 @@ import { ClassValue } from 'clsx';
  */
 type CboxAppKey = string;
 type CboxUser = {
-    id: number;
+    /** Cbox ID's user id: numeric in id itself, a prefixed string (`usr_…`) in the apps that mirror it. */
+    id: number | string;
     name: string;
     email: string;
     avatar_url?: string | null;
@@ -32,7 +34,8 @@ type CboxUser = {
     timezone?: string | null;
 };
 type CboxOrganization = {
-    id: number;
+    /** Cbox ID's organization id: numeric in id itself, a prefixed string (`org_…`) in the apps that mirror it. */
+    id: number | string;
     slug: string;
     name: string;
     /**
@@ -255,6 +258,8 @@ type LinkComponent = ComponentType<{
     className?: string;
     title?: string;
     'aria-label'?: string;
+    /** Set on the link of the page the person is on. */
+    'aria-current'?: 'page';
 }>;
 type CboxAppSidebarProps = {
     /** App key for the brand submark (and aria labels). */
@@ -494,6 +499,67 @@ type AppLauncherProps = {
  */
 declare function AppLauncher({ className, onLockedAppClick }: AppLauncherProps): react_jsx_runtime.JSX.Element | null;
 
+/** One app as the host's catalog endpoint lists it. */
+type CboxCatalogApp = {
+    key: string;
+    name: string;
+    launch_url: string;
+    icon_url?: string | null;
+    description?: string | null;
+};
+type CboxAppCatalogState = {
+    status: 'idle' | 'loading';
+} | {
+    status: 'ready';
+    apps: CboxCatalogApp[];
+    refreshAfter: number;
+} | {
+    status: 'authorization_required';
+    authorizeUrl: string | null;
+} | {
+    status: 'unavailable';
+};
+type CboxAppCatalogProps = {
+    /**
+     * Same-origin URL the host serves the person's app catalog from (a proxy of Cbox ID's
+     * catalog, authorized for the signed-in person). `null` renders the control disabled, so the
+     * chrome keeps its shape on pages without an organization.
+     */
+    endpoint: string | null;
+    /** The app key of this app; its tile is marked current and does not navigate. */
+    currentAppKey: string;
+    /**
+     * Marks per app key, rendered instead of the catalog's `icon_url` (a host that bundles the
+     * family's service marks). An app without one shows its `icon_url`, then its initials.
+     */
+    icons?: Record<string, ReactNode>;
+    className?: string;
+};
+/**
+ * Interpret the catalog endpoint's answer. The contract every Cbox app serves:
+ *
+ * - `200 { apps: [{ key, name, launch_url, icon_url?, description? }], refresh_after?: seconds }`
+ * - `401`/`403 { authorize_url?: string }` or `{ state: 'authorization_required' }`: the
+ *   person has to (re)connect their catalog grant; `authorize_url` is where.
+ * - anything else: unavailable right now.
+ *
+ * Only `http(s)` launch URLs are kept: the tiles are links the person will click.
+ */
+declare function parseAppCatalog(ok: boolean, body: unknown): CboxAppCatalogState;
+/** The authorize link with `return_to` set to where the person is, when it is on this origin. */
+declare function authorizeHref(authorizeUrl: string | null, location: {
+    origin: string;
+    pathname: string;
+    search: string;
+}): string | null;
+/**
+ * The Switch-app control: a grid of the Cbox apps this person can open, read live from the
+ * host's catalog endpoint. The host owns the endpoint and the grant; this renders the answer,
+ * refreshes it when it expires while the panel is open, and offers the way back to Cbox ID
+ * when the grant is missing.
+ */
+declare function CboxAppCatalog({ endpoint, currentAppKey, icons, className }: CboxAppCatalogProps): react_jsx_runtime.JSX.Element;
+
 type AppSwitcherProps = {
     className?: string;
     /**
@@ -595,7 +661,14 @@ type Props$3 = {
      * is consistency across apps.
      */
     extras?: ReactNode;
+    placement?: 'bottom-end' | 'top-start';
     className?: string;
+    /**
+     * The router's link for the account and organization rows, when they are pages of this
+     * app (an Inertia `Link` keeps the visit client-side). Default: a plain anchor, which is
+     * right when the rows deep-link into Cbox ID on another origin.
+     */
+    LinkComponent?: LinkComponent;
 };
 /**
  * User-menu dropdown. Always exposes:
@@ -605,7 +678,7 @@ type Props$3 = {
  *
  * The arrows signal cross-app navigation — id is canonical.
  */
-declare function UserMenu({ extras, className }: Props$3): react_jsx_runtime.JSX.Element;
+declare function UserMenu({ extras, className, placement, LinkComponent: Link }: Props$3): react_jsx_runtime.JSX.Element;
 
 /**
  * Combobox — the canonical select replacement for the Cbox suite.
@@ -1380,4 +1453,75 @@ declare function parseUrlSearch<S extends UrlSchema>(search: string, schema: S):
  */
 declare function buildUrlSearch<S extends UrlSchema>(state: InferUrlState<S>, schema: S): string;
 
-export { AppContent, AppLauncher, AppShell, AppSwitcher, type CboxAppKey, type CboxAppLink, CboxAppShell, type CboxAppShellProps, CboxAppSidebar, type CboxAppSidebarProps, CboxBrand, type CboxBrandProps, type CboxIdContextValue, CboxIdProvider, CboxMobileNavDrawer, type CboxMobileNavDrawerProps, type CboxNavItem, type CboxNavSection, type CboxNotificationPreviewItem, type CboxNotificationsState, CboxOrgContextBar, type CboxOrgContextBarProps, type CboxOrganization, CboxSurfaces, type CboxSurfacesProps, type CboxUser, Combobox, type ComboboxAvatar, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type ContextAvatar, ContextAvatarChip, ContextBar, type ContextCrumb, type ContextItem, DataPanel, EmptyState, Heading, type InboxState, type InferUrlState, KeyValue, KeyValueList, type LinkComponent, NotificationsBell, OrgSwitcher, PageHeader, PageShell, type PageTabSpec, PageTabs, type PageTabsProps, type PageWidth, PanelBody, type RealtimeState, type RealtimeStatus, RowLink, type RowLinkProps, SearchTrigger, SectionHeader, StatTile, StatusPill, type SurfaceArgs, type SurfaceConfig, type SurfaceController, type SurfaceId, TopBar, type Transport, type UrlField, type UrlSchema, UserMenu, buildUrlSearch, cn, defineUrlSchema, parseUrlSearch, urlBoolean, urlEnum, urlNumber, urlString, urlStringArray, useCboxId, useCboxIdOptional, useCboxSurfaces, useCboxSurfacesOptional };
+type CboxTranslationValues = Record<string, string | number>;
+type CboxTranslator = (message: string, values?: CboxTranslationValues) => string;
+declare function interpolate(message: string, values?: CboxTranslationValues): string;
+/** Optional and additive: without a provider existing consumers retain English. */
+declare function CboxLocalizationProvider({ locale, translate, formatDate, children }: {
+    locale: string;
+    translate: CboxTranslator;
+    formatDate?: (value: string) => string;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useCboxLocalization(): {
+    locale: string;
+    t: CboxTranslator;
+    formatDate: (value: string) => string;
+};
+
+type CboxNavArea = CboxNavItem & {
+    items?: CboxNavItem[];
+};
+type CboxWorkspaceShellProps = {
+    appKey: string;
+    brandSubmark: string;
+    areas: CboxNavArea[];
+    currentPath: string;
+    LinkComponent: LinkComponent;
+    context: ReactNode;
+    tools: ReactNode;
+    account: ReactNode;
+    children: ReactNode;
+    /** Where the brand row links. Default `/`. */
+    brandHref?: string;
+    /** `id` of the `<main>` landmark, so a host's skip link can target it. Default `main-content`. */
+    mainId?: string;
+    /**
+     * Rail pinned open. Pass `pinned` + `onPinnedChange` to control it (the host persists the
+     * preference, in a cookie or Cbox ID), or `defaultPinned` to seed the shell's own state.
+     */
+    pinned?: boolean;
+    defaultPinned?: boolean;
+    onPinnedChange?: (pinned: boolean) => void;
+    /** Contextual subnav collapsed to its strip. Controlled and uncontrolled as `pinned`. */
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+};
+/**
+ * How well `href` matches `path`: the href's length when the path is the href or beneath it,
+ * -1 otherwise. `/` matches only itself, so a home item never claims every page.
+ */
+declare function navMatchLength(path: string, href: string): number;
+/** The item whose href is the most specific match for `path`, or undefined. */
+declare function activeNavItem<T extends CboxNavItem>(path: string, items: readonly T[]): T | undefined;
+/**
+ * The area `path` is in: the one holding the most specific match among its own href and its
+ * items' hrefs. A first-match would put every page beneath an area at `/` (an overview, a
+ * dashboard) under that area and never show another area's subnav.
+ */
+declare function activeNavArea<T extends CboxNavArea>(path: string, areas: readonly T[]): T | undefined;
+/** Two-tier workspace navigation. Route ownership and preference persistence stay with the host. */
+declare function CboxWorkspaceShell({ appKey, brandSubmark, areas, currentPath, LinkComponent: Link, context, tools, account, children, brandHref, mainId, pinned: pinnedProp, defaultPinned, onPinnedChange, collapsed: collapsedProp, defaultCollapsed, onCollapsedChange }: CboxWorkspaceShellProps): react_jsx_runtime.JSX.Element;
+
+/** The chart tokens in order, for series that set their own colour. */
+declare const CHART_PALETTE: string[];
+/** A row's shape over the window, small: a line with a faint area, zero at the bottom. Decorative. */
+declare function Sparkline({ values, color, width, height }: {
+    values: number[];
+    color?: string;
+    width?: number;
+    height?: number;
+}): react_jsx_runtime.JSX.Element | null;
+
+export { AppContent, AppLauncher, AppShell, AppSwitcher, CHART_PALETTE, CboxAppCatalog, type CboxAppCatalogProps, type CboxAppCatalogState, type CboxAppKey, type CboxAppLink, CboxAppShell, type CboxAppShellProps, CboxAppSidebar, type CboxAppSidebarProps, CboxBrand, type CboxBrandProps, type CboxCatalogApp, type CboxIdContextValue, CboxIdProvider, CboxLocalizationProvider, CboxMobileNavDrawer, type CboxMobileNavDrawerProps, type CboxNavArea, type CboxNavItem, type CboxNavSection, type CboxNotificationPreviewItem, type CboxNotificationsState, CboxOrgContextBar, type CboxOrgContextBarProps, type CboxOrganization, CboxSurfaces, type CboxSurfacesProps, type CboxTranslationValues, type CboxTranslator, type CboxUser, CboxWorkspaceShell, type CboxWorkspaceShellProps, Combobox, type ComboboxAvatar, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type ContextAvatar, ContextAvatarChip, ContextBar, type ContextCrumb, type ContextItem, DataPanel, EmptyState, Heading, type InboxState, type InferUrlState, KeyValue, KeyValueList, type LinkComponent, NotificationsBell, OrgSwitcher, PageHeader, PageShell, type PageTabSpec, PageTabs, type PageTabsProps, type PageWidth, PanelBody, type RealtimeState, type RealtimeStatus, RowLink, type RowLinkProps, SearchTrigger, SectionHeader, Sparkline, StatTile, StatusPill, type SurfaceArgs, type SurfaceConfig, type SurfaceController, type SurfaceId, TopBar, type Transport, type UrlField, type UrlSchema, UserMenu, activeNavArea, activeNavItem, authorizeHref, buildUrlSearch, cn, defineUrlSchema, interpolate, navMatchLength, parseAppCatalog, parseUrlSearch, urlBoolean, urlEnum, urlNumber, urlString, urlStringArray, useCboxId, useCboxIdOptional, useCboxLocalization, useCboxSurfaces, useCboxSurfacesOptional };