@locusgraph/blocks 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LocusGraph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @locusgraph/blocks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Product sections built from `@locusgraph/components` and its Rule Grid: the same usage, billing and API-key screens in every LocusGraph app. Blocks take plain data and callbacks; they never fetch.
+
+```bash
+pnpm add @locusgraph/blocks @locusgraph/components
+```
+
+```css
+@import "@locusgraph/components/theme.css";
+@import "@locusgraph/blocks/sources.css";
+```
+
+| Block | Props |
+|---|---|
+| `UsageSummary` | `quotas`, optional `label`, `emptyText` |
+| `QuotaMeter` | `quota` (`key`, `period`, `used`, `included`) |
+| `UsageAttention` | `balanceMicroUsd`, `quotas`, `paidPlan`, `buyCreditsHref`, `upgradeHref`, `linkComponent`. Renders nothing when credits are fine and no quota is over |
+| `WalletPanel` | `balanceMicroUsd`, `debtMicroUsd`, `grants`. A Rule Grid cell |
+| `CreditPacks` | `packs`, `onBuy(packId)`, `pending`. A Rule Grid cell |
+| `PlanOptions` | `plans`, `actionFor(plan)` for plans that are not current |
+| `KeysTable` | `keys`, `actions(key)` |
+| `NoKeys` | `newKeyHref` (omit for read-only roles), `linkComponent` |
+
+`WalletPanel` and `CreditPacks` are cells, so put them in a `RuleGrid`:
+
+```tsx
+<RuleGrid columns={2}>
+  <WalletPanel balanceMicroUsd={wallet.balanceMicroUsd} grants={grants} />
+  <CreditPacks packs={wallet.packs} onBuy={buy} pending={pending} />
+</RuleGrid>
+```
+
+Pass your router's link as `linkComponent` (for example Next.js `Link`); plain `<a>` is the default.

package/dist/billing/credit-packs.d.ts

@@ -0,0 +1,9 @@
+import type { CreditPack } from "../types.js";
+type CreditPacksProps = {
+    packs: CreditPack[];
+    onBuy: (packId: string) => void;
+    pending?: boolean;
+    description?: string;
+};
+export declare function CreditPacks({ packs, onBuy, pending, description, }: CreditPacksProps): import("react").JSX.Element;
+export {};

package/dist/billing/credit-packs.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, RuleGridCell, RuleGridDescription, RuleGridLabel } from "@locusgraph/components";
+import { centsToMicroUsd, formatCents, formatMicroUsd } from "@locusgraph/utils";
+export function CreditPacks({ packs, onBuy, pending = false, description = "Pay once with Stripe. Credits never expire and never renew on their own.", }) {
+    return (_jsxs(RuleGridCell, { className: "gap-4", children: [_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(RuleGridLabel, { children: "Buy credits" }), _jsx(RuleGridDescription, { children: description })] }), _jsx("div", { className: "flex flex-wrap gap-2", children: packs.map((pack) => (_jsxs(Button, { variant: "outline", disabled: pending, onClick: () => onBuy(pack.id), children: [_jsx("span", { className: "tabular-nums", children: formatMicroUsd(pack.amountMicroUsd) }), centsToMicroUsd(pack.priceCents) !== pack.amountMicroUsd && (_jsxs("span", { className: "text-muted-foreground tabular-nums", children: ["for ", formatCents(pack.priceCents)] }))] }, pack.id))) })] }));
+}

package/dist/billing/plan-options.d.ts

@@ -0,0 +1,8 @@
+import type * as React from "react";
+import type { PlanOffer } from "../types.js";
+type PlanOptionsProps = {
+    plans: PlanOffer[];
+    actionFor?: (plan: PlanOffer) => React.ReactNode;
+};
+export declare function PlanOptions({ plans, actionFor }: PlanOptionsProps): React.JSX.Element;
+export {};

package/dist/billing/plan-options.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge, RuleGrid, RuleGridCell, RuleGridDescription, RuleGridTitle, } from "@locusgraph/components";
+export function PlanOptions({ plans, actionFor }) {
+    return (_jsx(RuleGrid, { columns: plans.length >= 3 ? 3 : 2, children: plans.map((plan) => {
+            const action = plan.current ? null : actionFor?.(plan);
+            return (_jsxs(RuleGridCell, { "data-current": plan.current || undefined, className: "gap-4", children: [_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsxs(RuleGridTitle, { className: "flex items-center gap-2", children: [plan.name, plan.current && _jsx(Badge, { variant: "secondary", children: "Current" })] }), _jsx(RuleGridDescription, { children: plan.price })] }), _jsx("ul", { className: "flex flex-col gap-1.5 text-sm text-muted-foreground", children: plan.points.map((point) => (_jsx("li", { children: point }, point))) }), action && _jsx("div", { className: "mt-auto", children: action })] }, plan.name));
+        }) }));
+}

package/dist/billing/wallet-panel.d.ts

@@ -0,0 +1,8 @@
+import type { WalletGrant } from "../types.js";
+type WalletPanelProps = {
+    balanceMicroUsd: number;
+    debtMicroUsd?: number;
+    grants: WalletGrant[];
+};
+export declare function WalletPanel({ balanceMicroUsd, debtMicroUsd, grants }: WalletPanelProps): import("react").JSX.Element;
+export {};

package/dist/billing/wallet-panel.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge, RuleGridCell, RuleGridLabel } from "@locusgraph/components";
+import { balanceLevel, formatDate, formatMicroUsd } from "@locusgraph/utils";
+const levelHint = {
+    low: { badge: "Low", text: "Add credits before usage stops.", tone: "text-warn" },
+    empty: {
+        badge: "Empty",
+        text: "Paid usage is paused until you add credits.",
+        tone: "text-destructive",
+    },
+};
+export function WalletPanel({ balanceMicroUsd, debtMicroUsd = 0, grants }) {
+    const level = balanceLevel(balanceMicroUsd);
+    const hint = level === "fine" ? null : levelHint[level];
+    return (_jsxs(RuleGridCell, { "data-level": level, className: "gap-4", children: [_jsxs("span", { className: "flex items-center justify-between", children: [_jsx(RuleGridLabel, { children: "Prepaid credits" }), hint && (_jsx(Badge, { variant: level === "empty" ? "destructive" : "secondary", className: level === "low" ? "text-warn" : undefined, children: hint.badge }))] }), _jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "font-heading text-3xl font-semibold tracking-[-0.02em] tabular-nums", children: formatMicroUsd(balanceMicroUsd) }), hint && _jsx("p", { className: `text-sm ${hint.tone}`, children: hint.text })] }), _jsxs("div", { className: "flex flex-col gap-3 text-sm", children: [grants.length > 0 ? (_jsx("ul", { className: "flex flex-col divide-y divide-line", children: grants.map((grant) => (_jsxs("li", { className: "flex justify-between gap-4 py-2", children: [_jsx("span", { children: grant.label }), _jsxs("span", { className: "text-muted-foreground tabular-nums", children: [formatMicroUsd(grant.remainingMicroUsd), " \u00B7", " ", grant.expiresAt ? `expires ${formatDate(grant.expiresAt)}` : "never expires"] })] }, `${grant.label}:${grant.expiresAt}`))) })) : (_jsx("p", { className: "text-muted-foreground", children: "No credits yet. Buy a pack to keep using paid features." })), debtMicroUsd > 0 && (_jsxs("p", { className: "text-destructive", children: [formatMicroUsd(debtMicroUsd), " owed. It comes out of the next credits you add."] }))] })] }));
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { CreditPacks } from "./billing/credit-packs.js";
+export { PlanOptions } from "./billing/plan-options.js";
+export { WalletPanel } from "./billing/wallet-panel.js";
+export { KeysTable } from "./keys/keys-table.js";
+export { NoKeys } from "./keys/no-keys.js";
+export * from "./types.js";
+export { QuotaMeter } from "./usage/quota-meter.js";
+export { UsageAttention } from "./usage/usage-attention.js";
+export { UsageSummary } from "./usage/usage-summary.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { CreditPacks } from "./billing/credit-packs.js";
+export { PlanOptions } from "./billing/plan-options.js";
+export { WalletPanel } from "./billing/wallet-panel.js";
+export { KeysTable } from "./keys/keys-table.js";
+export { NoKeys } from "./keys/no-keys.js";
+export * from "./types.js";
+export { QuotaMeter } from "./usage/quota-meter.js";
+export { UsageAttention } from "./usage/usage-attention.js";
+export { UsageSummary } from "./usage/usage-summary.js";

package/dist/keys/keys-table.d.ts

@@ -0,0 +1,8 @@
+import type * as React from "react";
+import type { ApiKeyRow } from "../types.js";
+type KeysTableProps = {
+    keys: ApiKeyRow[];
+    actions?: (key: ApiKeyRow) => React.ReactNode;
+};
+export declare function KeysTable({ keys, actions }: KeysTableProps): React.JSX.Element;
+export {};

package/dist/keys/keys-table.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow, } from "@locusgraph/components";
+import { formatDate } from "@locusgraph/utils";
+export function KeysTable({ keys, actions }) {
+    return (_jsxs(Table, { children: [_jsx(TableHeader, { children: _jsxs(TableRow, { children: [_jsx(TableHead, { children: "Name" }), _jsx(TableHead, { className: "hidden md:table-cell", children: "Key" }), _jsx(TableHead, { children: "Product" }), _jsx(TableHead, { className: "hidden md:table-cell", children: "Created by" }), _jsx(TableHead, { className: "hidden sm:table-cell", children: "Created" }), _jsx(TableHead, { children: "Expires" }), actions && _jsx(TableHead, { className: "w-0" })] }) }), _jsx(TableBody, { children: keys.map((key) => (_jsxs(TableRow, { children: [_jsx(TableCell, { className: "font-medium", children: key.name ?? "Untitled" }), _jsx(TableCell, { className: "hidden font-mono text-muted-foreground md:table-cell", children: key.maskedKey }), _jsx(TableCell, { children: key.productLabel }), _jsx(TableCell, { className: "hidden md:table-cell", children: key.createdBy }), _jsx(TableCell, { className: "hidden sm:table-cell", children: formatDate(key.createdAt) }), _jsx(TableCell, { children: formatDate(key.expiresAt, "Never") }), actions && _jsx(TableCell, { className: "text-right", children: actions(key) })] }, key.id))) })] }));
+}

package/dist/keys/no-keys.d.ts

@@ -0,0 +1,8 @@
+import type { LinkComponent } from "../types.js";
+type NoKeysProps = {
+    newKeyHref?: string;
+    description?: string;
+    linkComponent?: LinkComponent | "a";
+};
+export declare function NoKeys({ newKeyHref, description, linkComponent: Link, }: NoKeysProps): import("react").JSX.Element;
+export {};

package/dist/keys/no-keys.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, RuleGrid, RuleGridCell, RuleGridDescription, RuleGridLabel, } from "@locusgraph/components";
+import { KeyRoundIcon, PlusIcon } from "lucide-react";
+export function NoKeys({ newKeyHref, description = newKeyHref
+    ? "Create a key to let a service call LocusGraph products for this organization."
+    : "Ask an owner to create a key for this organization.", linkComponent: Link = "a", }) {
+    return (_jsx(RuleGrid, { columns: 1, children: _jsxs(RuleGridCell, { className: "items-center gap-3 py-12 text-center", children: [_jsx(KeyRoundIcon, { className: "size-5 text-muted-foreground" }), _jsx(RuleGridLabel, { children: "No API keys yet" }), _jsx(RuleGridDescription, { className: "max-w-sm", children: description }), newKeyHref && (_jsx(Button, { asChild: true, size: "sm", children: _jsxs(Link, { href: newKeyHref, children: [_jsx(PlusIcon, {}), "New key"] }) }))] }) }));
+}

package/dist/sources.css

@@ -0,0 +1 @@
+@source "./";

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+export type { LinkComponent } from "@locusgraph/components";
+export type QuotaPeriod = "month" | "lifetime";
+export type Quota = {
+    key: string;
+    period: QuotaPeriod;
+    used: number;
+    included: number;
+};
+export type CreditPack = {
+    id: string;
+    priceCents: number;
+    amountMicroUsd: number;
+};
+export type WalletGrant = {
+    label: string;
+    remainingMicroUsd: number;
+    expiresAt: string | null;
+};
+export type PlanOffer = {
+    name: string;
+    price: string;
+    points: string[];
+    current: boolean;
+};
+export type ApiKeyRow = {
+    id: string;
+    name: string | null;
+    maskedKey: string;
+    productLabel: string;
+    createdBy: string;
+    createdAt: string | null;
+    expiresAt: string | null;
+};
+export declare function periodLabel(period: QuotaPeriod): string;

package/dist/types.js

@@ -0,0 +1,3 @@
+export function periodLabel(period) {
+    return period === "month" ? "this month" : "lifetime";
+}

package/dist/usage/quota-meter.d.ts

@@ -0,0 +1,4 @@
+import { type Quota } from "../types.js";
+export declare function QuotaMeter({ quota }: {
+    quota: Quota;
+}): import("react").JSX.Element;

package/dist/usage/quota-meter.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Progress } from "@locusgraph/components";
+import { formatCount, quotaPercent, quotaStatus } from "@locusgraph/utils";
+import { periodLabel } from "../types.js";
+const statusIndicator = {
+    ok: "",
+    near: "[&_[data-slot=progress-indicator]]:bg-warn",
+    over: "[&_[data-slot=progress-indicator]]:bg-destructive",
+};
+export function QuotaMeter({ quota }) {
+    const percent = quotaPercent(quota);
+    return (_jsxs("div", { "data-slot": "quota-meter", "data-status": quotaStatus(quota), className: "flex flex-col gap-2", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-4 text-sm", children: [_jsx("span", { className: "font-mono", children: quota.key }), _jsxs("span", { className: "text-muted-foreground tabular-nums", children: [formatCount(quota.used), " of ", formatCount(quota.included), " ", periodLabel(quota.period)] })] }), _jsx(Progress, { value: percent, "aria-label": `${quota.key} ${percent}% of quota`, className: statusIndicator[quotaStatus(quota)] })] }));
+}

package/dist/usage/usage-attention.d.ts

@@ -0,0 +1,11 @@
+import { type LinkComponent, type Quota } from "../types.js";
+type UsageAttentionProps = {
+    balanceMicroUsd: number | null;
+    quotas: Quota[];
+    paidPlan: boolean;
+    buyCreditsHref: string;
+    upgradeHref: string;
+    linkComponent?: LinkComponent | "a";
+};
+export declare function UsageAttention({ balanceMicroUsd, quotas, paidPlan, buyCreditsHref, upgradeHref, linkComponent: Link, }: UsageAttentionProps): import("react").JSX.Element | null;
+export {};

package/dist/usage/usage-attention.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Alert, AlertDescription, AlertTitle, Button } from "@locusgraph/components";
+import { balanceLevel, formatCount, formatMicroUsd, quotaStatus } from "@locusgraph/utils";
+import { CircleAlertIcon } from "lucide-react";
+import { periodLabel } from "../types.js";
+function attentionTitle(empty, overCount) {
+    if (empty)
+        return "Out of credits";
+    return overCount > 0 ? "Usage is over your plan" : "Credits are running low";
+}
+export function UsageAttention({ balanceMicroUsd, quotas, paidPlan, buyCreditsHref, upgradeHref, linkComponent: Link = "a", }) {
+    const level = balanceMicroUsd === null ? "fine" : balanceLevel(balanceMicroUsd);
+    const over = quotas.filter((quota) => quotaStatus(quota) === "over");
+    if (level === "fine" && over.length === 0)
+        return null;
+    const empty = level === "empty";
+    return (_jsxs(Alert, { variant: empty ? "destructive" : "default", className: empty ? undefined : "text-warn *:data-[slot=alert-description]:text-warn/85", children: [_jsx(CircleAlertIcon, {}), _jsx(AlertTitle, { children: attentionTitle(empty, over.length) }), _jsxs(AlertDescription, { className: "flex flex-wrap items-end justify-between gap-4", children: [_jsxs("ul", { className: "flex flex-col gap-1", children: [over.map((quota) => (_jsxs("li", { children: [_jsx("span", { className: "font-mono", children: quota.key }), " is at ", formatCount(quota.used), " of", " ", formatCount(quota.included), " ", periodLabel(quota.period), "."] }, quota.key))), balanceMicroUsd !== null && level !== "fine" && (_jsx("li", { children: empty
+                                    ? "Paid usage is paused until you add credits."
+                                    : `${formatMicroUsd(balanceMicroUsd)} of credits left.` }))] }), _jsxs("div", { className: "flex items-center gap-4", children: [!paidPlan && (_jsx(Link, { href: upgradeHref, className: "text-sm text-foreground underline-offset-4 hover:underline", children: "Upgrade to Pro" })), _jsx(Button, { asChild: true, size: "sm", children: _jsx(Link, { href: buyCreditsHref, children: "Buy credits" }) })] })] })] }));
+}

package/dist/usage/usage-summary.d.ts

@@ -0,0 +1,8 @@
+import type { Quota } from "../types.js";
+type UsageSummaryProps = {
+    quotas: Quota[];
+    label?: string;
+    emptyText?: string;
+};
+export declare function UsageSummary({ quotas, label, emptyText, }: UsageSummaryProps): import("react").JSX.Element;
+export {};

package/dist/usage/usage-summary.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { RuleGrid, RuleGridCell, RuleGridLabel } from "@locusgraph/components";
+import { QuotaMeter } from "./quota-meter.js";
+export function UsageSummary({ quotas, label = "Usage", emptyText = "No plan includes metered usage yet.", }) {
+    return (_jsx(RuleGrid, { columns: 1, children: _jsxs(RuleGridCell, { className: "gap-5", children: [_jsx(RuleGridLabel, { children: label }), quotas.length > 0 ? (quotas.map((quota) => _jsx(QuotaMeter, { quota: quota }, quota.key))) : (_jsx("p", { className: "text-sm text-muted-foreground", children: emptyText }))] }) }));
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@locusgraph/blocks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Product sections built from @locusgraph/components: usage meters and alerts, wallet, credit packs, plan options and API keys.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/locusgraph/design.git",
+    "directory": "packages/blocks"
+  },
+  "homepage": "https://design.locusgraph.com",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./sources.css": "./dist/sources.css"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@locusgraph/components": "^0.1.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "dependencies": {
+    "@locusgraph/utils": "0.1.1",
+    "lucide-react": "^1.28.0"
+  },
+  "devDependencies": {
+    "@locusgraph/components": "0.1.1",
+    "@locusgraph/config": "0.1.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/sources.css dist/sources.css && node ../../scripts/esm-extensions.mjs dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }