@cosmoops/connect-sdk 0.9.0 → 0.15.0

package/dist/types/ui/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Page-composition primitives - the layer between HeroUI and your features.
+ *
+ * Deliberately **not** `"use client"`. Everything here is presentational, with
+ * no hooks and no state, so it renders in a Server Component and stays out of
+ * the browser bundle. That is the whole reason this is a separate entry point
+ * from `@cosmoops/connect-sdk/client`: that module's barrel carries a
+ * `"use client"` directive, so re-exporting a `<Card>` wrapper through it
+ * would turn every page shell in your app into a client boundary for no gain.
+ *
+ * The interactive counterparts - a confirm dialog, cursor pagination, filter
+ * tabs - hold state and live in `/client` alongside the rest of the browser
+ * half.
+ *
+ * ```tsx
+ * import { ConnectPageShell, ConnectSection } from "@cosmoops/connect-sdk/ui";
+ *
+ * export default function ContactsPage() {
+ *   return (
+ *     <ConnectPageShell title="Contacts" description="Everyone you do business with.">
+ *       <ConnectPageShell.Async fallback={<TableSkeleton />}>
+ *         <ContactsTable />
+ *       </ConnectPageShell.Async>
+ *     </ConnectPageShell>
+ *   );
+ * }
+ * ```
+ */
+export { ConnectPageShell } from "./page-shell.js";
+export type { ConnectPageShellProps } from "./page-shell.js";
+export { ConnectPageHeader } from "./page-header.js";
+export type { ConnectPageHeaderProps } from "./page-header.js";
+export { ConnectSection } from "./section.js";
+export type { ConnectSectionProps } from "./section.js";
+export { ConnectEmptyState } from "./empty-state.js";
+export type { ConnectEmptyStateProps } from "./empty-state.js";
+export { ConnectSettingRow } from "./setting-row.js";
+export type { ConnectSettingRowProps } from "./setting-row.js";
+export { ConnectStatusChip } from "./status-chip.js";
+export type { ConnectStatusTone, ConnectStatusPresentation } from "./status-chip.js";

package/dist/types/ui/page-header.d.ts

@@ -0,0 +1,34 @@
+import type { ReactNode } from "react";
+export interface ConnectPageHeaderProps {
+    title: ReactNode;
+    description?: ReactNode;
+    /**
+     * Rendered opposite the title. Keep it to one control - a page has one
+     * primary action, and a second here has nothing to align against.
+     */
+    action?: ReactNode;
+    /** Set `false` when the description carries a link that must stay readable on a phone. */
+    clamp?: boolean;
+    className?: string;
+}
+/**
+ * The title / description / action block a page opens with.
+ *
+ * The structure is the point, not the styling. The action is a peer of the
+ * **title**, not of the block, so nothing below the first line can move it -
+ * the common hand-rolled shape puts the action after the description, which
+ * makes the vertical position of a page's primary control a function of how
+ * long someone wrote the paragraph above it. On a phone that pushes it most of
+ * a thumb's reach down the screen.
+ *
+ * Mobile-first, and the two axes are separate decisions: the title row is a
+ * `justify-between` at every width (title left, action right, where a thumb
+ * expects it), while the description is clamped to two lines on a phone and
+ * released from `sm` up.
+ *
+ * An `h2`, because the document's `h1` is the application itself.
+ *
+ * No hooks and no state, so this renders from a Server Component - which is
+ * why it lives in `@cosmoops/connect-sdk/ui` rather than `/client`.
+ */
+export declare function ConnectPageHeader({ title, description, action, clamp, className, }: Readonly<ConnectPageHeaderProps>): import("react").JSX.Element;

package/dist/types/ui/page-shell.d.ts

@@ -0,0 +1,39 @@
+import { type ReactNode } from "react";
+import { ConnectPageHeader } from "./page-header.js";
+export interface ConnectPageShellProps {
+    title?: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+    clamp?: boolean;
+    /** Rendered above the header - a breadcrumb trail, a back link, a banner. */
+    above?: ReactNode;
+    children?: ReactNode;
+}
+/**
+ * The frame a page opens with: its vertical rhythm, its header, and the
+ * suspended regions beneath.
+ *
+ * **The header is a prop, so it renders in the static shell** - above and
+ * outside every `<Suspense>` boundary. That is the one bug this component
+ * exists to make unrepresentable: rendering the header inside the async child
+ * makes a page's own title wait on a data read, and under Next's partial
+ * prefetching the route's shared App Shell loses it as well. There is no
+ * arrangement of `children` that reaches the header slot.
+ *
+ * A detail route is the honest exception, and it has its own door:
+ * `ConnectPageShell.Header` renders the identical header from inside an async
+ * child, for a page whose title is data it does not have yet. Pair it with a
+ * skeleton header in the fallback. The rule is that a *static* title must
+ * never be made to wait, not that every title can be static.
+ *
+ * `space-y-5` is the page gap, owned here so it has exactly one definition.
+ */
+export declare function ConnectPageShell({ title, description, action, clamp, above, children, }: Readonly<ConnectPageShellProps>): import("react").JSX.Element;
+export declare namespace ConnectPageShell {
+    var Header: typeof ConnectPageHeader;
+    var Async: ({ fallback, children, }: Readonly<{
+        /** Omit where the region has nothing to draw while it waits. */
+        fallback?: ReactNode;
+        children: ReactNode;
+    }>) => import("react").JSX.Element;
+}

package/dist/types/ui/section.d.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+export interface ConnectSectionProps {
+    title: ReactNode;
+    /** What the block is for. Omit when the title says everything. */
+    description?: ReactNode;
+    /** Rendered opposite the title. One control - a section has one action. */
+    action?: ReactNode;
+    /** Set to reference the heading from an `aria-labelledby` in the body. */
+    titleId?: string;
+    className?: string;
+    bodyClassName?: string;
+    children?: ReactNode;
+}
+/**
+ * One titled block inside a page: a card, its heading, what it is for, and the
+ * one control that acts on it.
+ *
+ * The heading is an `h3` - `ConnectPageHeader` renders the page title as an
+ * `h2`, so a block *inside* a page is a level below it. Hand-rolled sections
+ * reliably use `h2`, which makes every settings block a sibling of the page it
+ * sits in and flattens the outline a screen reader announces.
+ *
+ * As in the page header, the action is a peer of the title rather than of the
+ * block, so its position does not move with the length of the description.
+ */
+export declare function ConnectSection({ title, description, action, titleId, className, bodyClassName, children, }: Readonly<ConnectSectionProps>): import("react").JSX.Element;

package/dist/types/ui/setting-row.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from "react";
+export interface ConnectSettingRowProps {
+    title: ReactNode;
+    description?: ReactNode;
+    /** The control this row is about - a switch, a button, a value with an edit link. */
+    action?: ReactNode;
+    /** Rendered under both, full width - a validation message, or a nested field the row reveals. */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * One labelled setting inside a `ConnectSection`.
+ *
+ * Stacks on a phone and goes side-by-side from `sm` up, rather than shrinking
+ * a two-column row until neither column is readable. The control keeps its
+ * intrinsic width so truncation lands on the description.
+ */
+export declare function ConnectSettingRow({ title, description, action, children, className, }: Readonly<ConnectSettingRowProps>): import("react").JSX.Element;

package/dist/types/ui/status-chip.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The closed set of tones a status may resolve to.
+ *
+ * Deliberately five, and deliberately narrower than HeroUI's `Chip` colour
+ * union: a status is either fine, needs attention, is broken, is in progress,
+ * or is inert. A sixth tone would have to mean one of those five again, which
+ * is where hand-written status chips start disagreeing with each other.
+ */
+export type ConnectStatusTone = "success" | "warning" | "danger" | "accent" | "default";
+/**
+ * How one domain's status union is presented: a tone and a human label per
+ * member.
+ *
+ * Both are **total** `Record`s, and that is the load-bearing property - adding
+ * a member to the status union fails the type gate until it has been given a
+ * presentation. A loose `Record<string, …>` map silently renders the new
+ * status as `undefined`.
+ */
+export interface ConnectStatusPresentation<TStatus extends string> {
+    readonly tone: Readonly<Record<TStatus, ConnectStatusTone>>;
+    readonly label: Readonly<Record<TStatus, string>>;
+}
+/**
+ * One status, rendered the way every status should be.
+ *
+ * Domain knowledge stays in the domain: each caller exports its own
+ * `ConnectStatusPresentation` next to the union it describes, and this renders
+ * it. A status whose *rendering* carries real logic - a scheduled cancellation
+ * outranking a running trial, say - keeps its own component and calls this for
+ * the final chip. A map cannot express precedence.
+ */
+export declare function ConnectStatusChip<TStatus extends string>({ status, presentation, className, }: Readonly<{
+    status: TStatus;
+    presentation: ConnectStatusPresentation<TStatus>;
+    className?: string;
+}>): import("react").JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.9.0",
+  "version": "0.15.0",
   "description": "Official server-side SDK for the CosmoOps Connect platform API - Login with Connect, entitlements, billing and metering.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -36,6 +36,11 @@
       "import": "./dist/esm/client/index.js",
       "require": "./dist/cjs/client/index.js"
     },
+    "./ui": {
+      "types": "./dist/types/ui/index.d.ts",
+      "import": "./dist/esm/ui/index.js",
+      "require": "./dist/cjs/ui/index.js"
+    },
     "./theme.css": "./dist/theme.css",
     "./package.json": "./package.json"
   },
@@ -67,7 +72,6 @@
     "verify:pack": "bun run scripts/verify-pack.ts",
     "prepublishOnly": "bun run build && bun run verify:pack",
     "test": "bun test",
-    "docs": "typedoc",
     "docs:md": "typedoc --options typedoc.markdown.json",
     "storybook": "storybook dev -p 6106",
     "build:storybook": "storybook build -o storybook-static"