@forwardreach/saas-ui 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.13.0
+
+### Minor Changes
+
+- **The chrome a host draws its own main pages with, so a page built only from shared
+  parts is indistinguishable from one the host draws by hand.** Reviewing ReachMe's
+  PeopleThread extension beside PeopleThread's Timeline found three gaps in this
+  package — no reference pill, no shared page column, and a `PageHeader` whose default
+  was not the host's heading shape — and each was being filled locally, in the wrong
+  place. This release fills them here.
+
+  - **Pill tokens.** `--ssui-pill-<tone>-bg` / `-text` for five tones: `reference` (a
+    link to a record), `tag`, `attribute` (a field), `date`, `category` (a grouping
+    tag). Every default is a _derivation_ of the status and accent ramps, never a
+    literal, so a consumer that has mapped the base contract sees a coherent pair in
+    both themes before it maps a pill token. That is now the rule for any token added
+    for a role a consumer may already color, and a test enforces it. A second test
+    holds the documented token list equal to the shipped declarations, so a consumer
+    can check its mapping for completeness against the docs.
+  - **`PageContainer`.** The centered page column: `width="narrow"` (a reading
+    column, 48rem), `"wide"` (a working column, 64rem), or `"full"` (a workspace, no
+    gutters). A page opts in; a host never wraps another product's page in it.
+  - **`Card`.** The bordered surface — `--ssui-surface` on `--ssui-border` at
+    `--ssui-radius-lg` — with `elevated`, an `interactive` border-hover for a card
+    whose parts are clickable, and `asChild`. Padding is the consumer's. `ListShell`
+    is a different thing and stays.
+  - **`Pill`.** An inline reference chip in the five tones, `align-baseline` so it
+    sits in a line of text, with `asChild` so the consumer's own link carries the
+    presentation. The `reference` tone carries a hairline border, which is what
+    separates a chip that reaches its record from one that is only a label. **The
+    previous `Pill` export was an alias of `Badge`**; the gallery was its only
+    consumer and is updated here, no product consumed it, and the name now means this
+    component. A badge-shaped pill is `Badge variant="outline"`.
+  - **`PageHeader` takes the host's heading shape.** The title ramp is now
+    `text-xl sm:text-2xl` (was `text-2xl`); the bottom rule is an opt-in `divider`
+    prop (was always drawn); a new `aside` slot renders on the title's baseline at
+    the right edge of the title row, for context that is not an action — a date, a
+    count — while `actions` keeps its own slot, so the two never share a line at
+    narrow widths. From `sm` up the header row now wraps: actions too wide to sit
+    beside the full title move to a row beneath it instead of shrinking the title
+    to nothing. **This is a visual change for every consumer that relied on the
+    rule and the larger title.** Pass `divider` where the rule is wanted; both known
+    consumers do so in the commit that takes this version.
+
 ## 0.12.0
 
 ### Minor Changes
@@ -47,7 +91,7 @@
   visible change to an existing component: `Combobox` renders the same list, so
   its popup picks all three corrections up. Options take the full text colour
   rather than the muted one, which came from a popup that hangs under a field
-  holding the answer; where the popup *is* the choice, options dimmer than the
+  holding the answer; where the popup _is_ the choice, options dimmer than the
   heading over them read as less available than the label for them. The current
   option carries a check and a medium weight rather than a fill alone, because
   that fill is `--ssui-surface-muted` on `--ssui-surface-elevated` — a clear step

package/dist/components/badge.d.ts

@@ -6,4 +6,3 @@ export declare const badgeVariants: (props?: ({
 export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {
 }
 export declare const Badge: React.ForwardRefExoticComponent<BadgeProps & React.RefAttributes<HTMLSpanElement>>;
-export declare const Pill: React.ForwardRefExoticComponent<BadgeProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/badge.js

@@ -20,4 +20,3 @@ export const badgeVariants = cva("inline-flex items-center gap-1 rounded-full bo
 });
 export const Badge = React.forwardRef(({ className, variant, ...props }, ref) => (_jsx("span", { ref: ref, className: cn(badgeVariants({ variant, className })), ...props })));
 Badge.displayName = "Badge";
-export const Pill = Badge;

package/dist/components/card.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
+    asChild?: boolean;
+    /** Sit on `--ssui-surface-elevated` instead of `--ssui-surface`. */
+    elevated?: boolean;
+    /** Strengthen the border on hover, for a card whose parts are clickable. Nothing else changes. */
+    interactive?: boolean;
+}
+/**
+ * The bordered surface: `--ssui-surface` on `--ssui-border` at `--ssui-radius-lg`. Padding is
+ * the consumer's (`className`), because a card holding a row and a card holding a form pad
+ * differently and a default would be overridden everywhere. `ListShell` is a different thing —
+ * the divided list container with header, toolbar, footer, and empty slots — and both stay.
+ */
+export declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/card.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Slot } from "@radix-ui/react-slot";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+/**
+ * The bordered surface: `--ssui-surface` on `--ssui-border` at `--ssui-radius-lg`. Padding is
+ * the consumer's (`className`), because a card holding a row and a card holding a form pad
+ * differently and a default would be overridden everywhere. `ListShell` is a different thing —
+ * the divided list container with header, toolbar, footer, and empty slots — and both stay.
+ */
+export const Card = React.forwardRef(({ asChild = false, className, elevated = false, interactive = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "div";
+    return (_jsx(Comp, { ref: ref, className: cn("rounded-[var(--ssui-radius-lg)] border border-[color:var(--ssui-border)] text-[color:var(--ssui-text)]", elevated
+            ? "bg-[color:var(--ssui-surface-elevated)]"
+            : "bg-[color:var(--ssui-surface)]", interactive && "transition-colors hover:border-[color:var(--ssui-border-strong)]", className), ...props }));
+});
+Card.displayName = "Card";

package/dist/components/index.d.ts

@@ -4,6 +4,7 @@ export * from "./avatar.js";
 export * from "./badge.js";
 export * from "./brand-icons.js";
 export * from "./button.js";
+export * from "./card.js";
 export * from "./checkbox.js";
 export * from "./choice-card.js";
 export * from "./collapsible.js";
@@ -23,7 +24,9 @@ export * from "./input.js";
 export * from "./list-shell.js";
 export * from "./login.js";
 export * from "./overflow-menu.js";
+export * from "./page-container.js";
 export * from "./page-header.js";
+export * from "./pill.js";
 export * from "./popover.js";
 export * from "./rail-toggle.js";
 export * from "./request-access.js";

package/dist/components/index.js

@@ -4,6 +4,7 @@ export * from "./avatar.js";
 export * from "./badge.js";
 export * from "./brand-icons.js";
 export * from "./button.js";
+export * from "./card.js";
 export * from "./checkbox.js";
 export * from "./choice-card.js";
 export * from "./collapsible.js";
@@ -23,7 +24,9 @@ export * from "./input.js";
 export * from "./list-shell.js";
 export * from "./login.js";
 export * from "./overflow-menu.js";
+export * from "./page-container.js";
 export * from "./page-header.js";
+export * from "./pill.js";
 export * from "./popover.js";
 export * from "./rail-toggle.js";
 export * from "./request-access.js";

package/dist/components/page-container.d.ts

@@ -0,0 +1,7 @@
+import * as React from "react";
+export type PageContainerWidth = "narrow" | "wide" | "full";
+export interface PageContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+    asChild?: boolean;
+    width?: PageContainerWidth;
+}
+export declare const PageContainer: React.ForwardRefExoticComponent<PageContainerProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/page-container.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Slot } from "@radix-ui/react-slot";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+/**
+ * The centered column a page sits in. The widths are a vocabulary, not numbers: `narrow` is a
+ * reading column (a timeline, a record), `wide` a working column (a collection, a list of
+ * things to act on), and `full` a workspace that fills what it is given (an inbox, an editor).
+ * `full` exists so a full-bleed page still declares that it made a choice.
+ */
+const widthClasses = {
+    narrow: "mx-auto w-full max-w-3xl px-4 py-5 md:px-8 md:py-8",
+    wide: "mx-auto w-full max-w-5xl px-4 py-5 md:px-8 md:py-8",
+    full: "w-full"
+};
+export const PageContainer = React.forwardRef(({ asChild = false, className, width = "wide", ...props }, ref) => {
+    const Comp = asChild ? Slot : "div";
+    return (_jsx(Comp, { ref: ref, className: cn(widthClasses[width], className), "data-width": width, ...props }));
+});
+PageContainer.displayName = "PageContainer";

package/dist/components/page-header.d.ts

@@ -1,10 +1,30 @@
 import * as React from "react";
 export interface PageHeaderProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
     actions?: React.ReactNode;
+    /**
+     * Context that is not an action — today's date, a count — rendered on the title's baseline
+     * at the right edge of the title row. The slot sets no type; size it as the page wants.
+     * `actions` keeps its own slot, so the two never share a line at narrow widths.
+     */
+    aside?: React.ReactNode;
     breadcrumbs?: React.ReactNode;
     description?: React.ReactNode;
+    /** Draw the bottom rule. Off by default: a main page has none, a settings page opts in. */
+    divider?: boolean;
     eyebrow?: React.ReactNode;
     metadata?: React.ReactNode;
     title: React.ReactNode;
 }
-export declare function PageHeader({ actions, breadcrumbs, className, description, eyebrow, metadata, title, ...props }: PageHeaderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The page title in the shape a host draws its own main pages in: `text-xl` rising to
+ * `text-2xl` at the small breakpoint, no rule beneath unless asked for. A page built only
+ * from shared parts should be indistinguishable from one the host draws by hand, which is
+ * why the default is the host's shape and the previous one is a prop away.
+ *
+ * From the small breakpoint the title and actions share a row only while both fit: the row
+ * wraps, so a toolbar wider than the space beside the title drops beneath it (as it does on a
+ * phone) rather than squeezing the title to nothing or running past the page edge. The title
+ * column's basis is its own min-content — the whole title, since the heading does not wrap — so
+ * the row breaks exactly when the full title and the actions no longer fit side by side.
+ */
+export declare function PageHeader({ actions, aside, breadcrumbs, className, description, divider, eyebrow, metadata, title, ...props }: PageHeaderProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/page-header.js

@@ -1,6 +1,18 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../utils/cn.js";
-export function PageHeader({ actions, breadcrumbs, className, description, eyebrow, metadata, title, ...props }) {
-    return (_jsxs("header", { className: cn("flex flex-col gap-4 border-b border-[color:var(--ssui-border)] pb-4 sm:flex-row sm:items-end sm:justify-between", className), ...props, children: [_jsxs("div", { className: "min-w-0 space-y-2", children: [breadcrumbs ? _jsx("div", { children: breadcrumbs }) : null, eyebrow ? (_jsx("div", { className: "text-xs font-medium uppercase text-[color:var(--ssui-text-muted)]", children: eyebrow })) : null, _jsxs("div", { className: "space-y-1", children: [_jsx("h1", { className: "truncate text-2xl font-semibold text-[color:var(--ssui-text)]", children: title }), description ? (_jsx("div", { className: "max-w-3xl text-sm text-[color:var(--ssui-text-muted)]", children: description })) : null] }), metadata ? _jsx("div", { className: "flex flex-wrap gap-2", children: metadata }) : null] }), actions ? _jsx("div", { className: "flex shrink-0 flex-wrap gap-2", children: actions }) : null] }));
+/**
+ * The page title in the shape a host draws its own main pages in: `text-xl` rising to
+ * `text-2xl` at the small breakpoint, no rule beneath unless asked for. A page built only
+ * from shared parts should be indistinguishable from one the host draws by hand, which is
+ * why the default is the host's shape and the previous one is a prop away.
+ *
+ * From the small breakpoint the title and actions share a row only while both fit: the row
+ * wraps, so a toolbar wider than the space beside the title drops beneath it (as it does on a
+ * phone) rather than squeezing the title to nothing or running past the page edge. The title
+ * column's basis is its own min-content — the whole title, since the heading does not wrap — so
+ * the row breaks exactly when the full title and the actions no longer fit side by side.
+ */
+export function PageHeader({ actions, aside, breadcrumbs, className, description, divider = false, eyebrow, metadata, title, ...props }) {
+    return (_jsxs("header", { className: cn("flex flex-col gap-4 sm:flex-row sm:flex-wrap sm:items-end sm:justify-between", divider && "border-b border-[color:var(--ssui-border)] pb-4", className), ...props, children: [_jsxs("div", { className: "min-w-0 flex-[1_1_min-content] space-y-2", children: [breadcrumbs ? _jsx("div", { children: breadcrumbs }) : null, eyebrow ? (_jsx("div", { className: "text-xs font-medium uppercase text-[color:var(--ssui-text-muted)]", children: eyebrow })) : null, _jsxs("div", { className: "space-y-1", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsx("h1", { className: "min-w-0 truncate text-xl font-semibold text-[color:var(--ssui-text)] sm:text-2xl", children: title }), aside ? (_jsx("div", { className: "ml-auto shrink-0", "data-slot": "aside", children: aside })) : null] }), description ? (_jsx("div", { className: "max-w-3xl text-sm text-[color:var(--ssui-text-muted)]", children: description })) : null] }), metadata ? _jsx("div", { className: "flex flex-wrap gap-2", children: metadata }) : null] }), actions ? _jsx("div", { className: "flex max-w-full shrink-0 flex-wrap gap-2", children: actions }) : null] }));
 }

package/dist/components/pill.d.ts

@@ -0,0 +1,20 @@
+import * as React from "react";
+/**
+ * The tones are roles, not colors: what the pill refers to. `reference` is a link to a record
+ * (a person's name), `tag` a label attached to one, `attribute` a field, `date` a point in
+ * time, `category` a grouping tag. Each reads its own `--ssui-pill-<tone>-bg` / `-text` pair.
+ */
+export type PillTone = "reference" | "tag" | "attribute" | "date" | "category";
+export interface PillProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /**
+     * Render the consumer's own element (a router link, a button) with the pill's presentation.
+     * The pill carries no `href` or `onClick` of its own: the consumer's element does.
+     */
+    asChild?: boolean;
+    tone?: PillTone;
+}
+/**
+ * An inline reference chip. Sized to sit in a line of text (`align-baseline`), which is where
+ * a reference lives; for a status, use `StatusPill`, whose capitalization and dot say "state".
+ */
+export declare const Pill: React.ForwardRefExoticComponent<PillProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/pill.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Slot } from "@radix-ui/react-slot";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+const toneClasses = {
+    // A reference reaches the record it names, so it carries a hairline border: that, and the
+    // border strengthening under a pointer when the consumer has made it a link, is what
+    // separates it from a chip that is only a label.
+    reference: "border border-[color:var(--ssui-border)] bg-[color:var(--ssui-pill-reference-bg)] text-[color:var(--ssui-pill-reference-text)] [&:is(a,button)]:hover:border-[color:var(--ssui-border-strong)]",
+    tag: "bg-[color:var(--ssui-pill-tag-bg)] text-[color:var(--ssui-pill-tag-text)]",
+    attribute: "bg-[color:var(--ssui-pill-attribute-bg)] text-[color:var(--ssui-pill-attribute-text)]",
+    date: "bg-[color:var(--ssui-pill-date-bg)] text-[color:var(--ssui-pill-date-text)]",
+    category: "bg-[color:var(--ssui-pill-category-bg)] text-[color:var(--ssui-pill-category-text)]"
+};
+/**
+ * An inline reference chip. Sized to sit in a line of text (`align-baseline`), which is where
+ * a reference lives; for a status, use `StatusPill`, whose capitalization and dot say "state".
+ */
+export const Pill = React.forwardRef(({ asChild = false, className, tone = "reference", ...props }, ref) => {
+    const Comp = asChild ? Slot : "span";
+    return (_jsx(Comp, { ref: ref, className: cn("inline-flex items-center gap-1 whitespace-nowrap rounded-[var(--ssui-radius)] px-1.5 py-0.5 align-baseline text-xs font-medium leading-tight transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[color:var(--ssui-bg)]", toneClasses[tone], className), "data-tone": tone, ...props }));
+});
+Pill.displayName = "Pill";

package/dist/styles/index.css

@@ -63,6 +63,20 @@
   --ssui-avatar-4-text: #9d174d;
   --ssui-avatar-5-bg: #f0f9ff;
   --ssui-avatar-5-text: #075985;
+  /* Pill tones: a reference (a link to a record), a tag, an attribute (a field), a date, and
+     a category (a grouping tag). Each defaults to a DERIVATION of the base contract rather
+     than a literal, so a consumer that has mapped the status and accent ramps sees a
+     coherent pair in both of its themes before it maps a single pill token. */
+  --ssui-pill-reference-bg: var(--ssui-accent-subtle);
+  --ssui-pill-reference-text: var(--ssui-accent-subtle-foreground);
+  --ssui-pill-tag-bg: var(--ssui-status-info-bg);
+  --ssui-pill-tag-text: var(--ssui-status-info-text);
+  --ssui-pill-attribute-bg: var(--ssui-status-neutral-bg);
+  --ssui-pill-attribute-text: var(--ssui-status-neutral-text);
+  --ssui-pill-date-bg: var(--ssui-status-warning-bg);
+  --ssui-pill-date-text: var(--ssui-status-warning-text);
+  --ssui-pill-category-bg: var(--ssui-status-success-bg);
+  --ssui-pill-category-text: var(--ssui-status-success-text);
 }
 
 @media (prefers-reduced-motion: reduce) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardreach/saas-ui",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Brand-neutral React UI primitives and SaaS app patterns for ForwardReach-owned business applications.",
   "type": "module",
   "private": false,
@@ -73,7 +73,7 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },
-  "gitHead": "7517a542f48380e40fb8d7632f12ce352151487d",
+  "gitHead": "519fa3eab663bd95bba8a6dae8ac056538d25431",
   "scripts": {
     "build": "pnpm clean && tsc -p tsconfig.build.json && node scripts/copy-styles.mjs",
     "dev": "node scripts/copy-styles.mjs && tsc -p tsconfig.build.json --watch",