@tristan2828/ui-foundation 4.9.1 → 4.10.0

package/conventions/docs/add-an-entity.md

@@ -265,6 +265,18 @@ is a filled-in example while the Widgets demo is still here).
      view is `rail`, with Details in the rail. The rail's sections come
      first in the page (header, rail, main) at every width, so the
      view's specs find them first too.
+   - **A notice** (`notice`), only when the plan names a state that
+     decides what you do with the record (held, overdue, archived and
+     read-only): a `<Notice tone=…>` saying what it means and what to do,
+     with at most one action. It goes under the header, across the page.
+     Pass `null` when the state doesn't hold; the view announces it
+     appearing or clearing. A badge still shows the state itself; the
+     notice is for the few states a badge is too quiet for.
+   - **A source credit** (`footer`), only when the record's data comes
+     from an outside service whose terms ask for one (many free APIs
+     do: a film database, a games catalogue): `<SourceCredit sources={[{
+     name, href, note }]} />`, with `note` the sentence the terms ask for,
+     word for word. Logos and their rules are the app's own.
    - **Every value renders the way its table cell does**: badges, names
      of linked records, a done-count, from the shared lookups in
      `<entity>-format.ts`. Never re-derive one for the view.

package/conventions/docs/design-language.md

@@ -346,3 +346,33 @@ const { data, isLoading, error, refetch } = useReadyTasksQuery() // one page of
 - Storybook's `app/WidgetCard` shows three widgets on a page and every
   one in each state; its checks run axe and the token and glyph checks in
   both themes and at `large`.
+
+## Notices
+
+A `Notice` says, across the page, a state that decides what you do with
+what's on it: held, overdue, archived and read-only. It's louder than a
+badge and stays until the state changes, unlike a toast. `EntityView`'s
+`notice` is its usual place (under the header); any page can render one
+under its own header.
+
+```tsx
+<Notice tone="warning" title="On hold" action={<Button size="sm" variant="outline">Release the hold</Button>}>
+  Read “Hyperion” first: this one follows it.
+</Notice>
+```
+
+- **The tone is the state's**, from the same grouping as its badge
+  (warning for held, destructive for overdue, info for "up next", success
+  rarely: a good state seldom needs saying across the page). `icon`
+  swaps the tone's own icon for a better one (a lock for read-only).
+- **A wash, not a fill:** the tone at 10% (20% in dark) with `foreground`
+  text and the tone's `*-text` icon. The message reads as body text, so
+  nothing inside it is muted. Storybook's `app/Notice` measures every
+  tone with axe and the glyph check in both themes.
+- **One or two sentences and at most one action**: what the state means
+  and what to do about it. More than that belongs in a section.
+- **Not an alert.** A notice there when the page opens is part of the
+  page, so it has no role of its own. `EntityView` keeps a `role="status"`
+  region in its place, so one appearing or clearing later is announced.
+  Elsewhere, put it in a status region that is rendered before it
+  changes.

package/dist/components/app/entity-view.d.ts

@@ -67,7 +67,19 @@ export type EntityViewProps = {
     badges?: ReactNode;
     /** The header's actions: an Edit button, a Delete with its confirm dialog. */
     actions?: ReactNode;
+    /**
+     * A state that decides what you do with the record, said before
+     * anything else (a `<Notice>`): under the header, across the page at
+     * every width. Announced when it appears or changes after the page loads.
+     */
+    notice?: ReactNode;
     sections: EntityViewSection[];
+    /**
+     * Below every section (both columns in the rail layout), in small muted
+     * type outside any card: where the record's data comes from
+     * (`<SourceCredit>`), when its source's terms ask for a credit.
+     */
+    footer?: ReactNode;
     /** `rail` puts the sections placed `rail` in a column on the right. Defaults to `column`. */
     layout?: EntityViewLayout;
     /** The rail's landmark name (its `<aside>`). Defaults to the title + " details". */
@@ -82,4 +94,4 @@ export type EntityViewProps = {
         label: string;
     };
 };
-export declare function EntityView({ title, titleEdit, badges, actions, sections, layout, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;
+export declare function EntityView({ title, titleEdit, badges, actions, notice, sections, footer, layout, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;

package/dist/components/app/entity-view.js

@@ -29,6 +29,10 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // autosave as it's typed (`autosave`), and be the editor itself, with no
 // click to open (`alwaysEditable`).
 //
+// Around the sections: `notice` (a <Notice>) under the header, across the
+// page, for a state that decides what you do with the record; `footer`
+// (a <SourceCredit>) after them all, for crediting the data's source.
+//
 // Two layouts. `column` (the default): every section in one column capped
 // at max-w-4xl. `rail`, for a record with long content: the page takes the
 // content area's whole width, sections placed `rail` go in a narrow column
@@ -136,7 +140,7 @@ function Rail({ label, sections }) {
     const [ref, fits] = useFitsWindow();
     return (_jsx("aside", { ref: ref, "aria-label": label, "data-fits": fits ? '' : undefined, className: cn(RAIL_LAYOUT.rail, RAIL_LAYOUT.sticky, 'flex min-w-0 flex-col gap-6'), children: sections.map((section) => (_jsx(ViewSection, { section: section, inRail: true }, section.title))) }));
 }
-export function EntityView({ title, titleEdit, badges, actions, sections, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
+export function EntityView({ title, titleEdit, badges, actions, notice, sections, footer, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
     // Editing in place: one store per view, and the leave-page prompt only
     // while a field is open (or one is always editable).
     const [store] = useState(() => new EditInPlaceStore());
@@ -152,5 +156,5 @@ export function EntityView({ title, titleEdit, badges, actions, sections, layout
         return _jsx(EntityViewSkeleton, { layout: layout });
     const railSections = sections.filter((section) => section.placement === 'rail');
     const mainSections = sections.filter((section) => section.placement !== 'rail');
-    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [editing && _jsx(LeaveGuard, { store: store }), _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), _jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) })] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title)))] }) }));
+    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [editing && _jsx(LeaveGuard, { store: store }), _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), _jsx("div", { role: "status", "data-slot": "entity-view-notice", className: "empty:hidden", children: notice }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), _jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) })] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title))), footer && (_jsx("footer", { "data-slot": "entity-view-footer", className: "type-caption text-muted-foreground", children: footer }))] }) }));
 }

package/dist/components/app/notice.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import { type LucideIcon } from 'lucide-react';
+export type NoticeTone = 'info' | 'success' | 'warning' | 'destructive';
+export type NoticeProps = {
+    /** What kind of state it is (design-language.md "Semantic tones"). Defaults to `info`. */
+    tone?: NoticeTone;
+    /** A short lead in bold ("On hold"), before the message. */
+    title?: ReactNode;
+    /** The message: one or two sentences saying what to do about it. */
+    children: ReactNode;
+    /** One way to act on it: a link or a small button (`<Button size="sm" variant="outline">`). */
+    action?: ReactNode;
+    /** Another icon than the tone's own, when the state has a better one (a lock for read-only). */
+    icon?: LucideIcon;
+    className?: string;
+};
+export declare function Notice({ tone, title, children, action, icon, className }: NoticeProps): import("react").JSX.Element;

package/dist/components/app/notice.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CircleAlertIcon, CircleCheckIcon, InfoIcon, TriangleAlertIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { Alert, AlertDescription, AlertTitle } from '../ui/alert.js';
+const TONE = {
+    info: { surface: 'border-info-text/30 bg-info/10 dark:bg-info/20', icon: 'text-info-text', Icon: InfoIcon },
+    success: {
+        surface: 'border-success-text/30 bg-success/10 dark:bg-success/20',
+        icon: 'text-success-text',
+        Icon: CircleCheckIcon,
+    },
+    warning: {
+        surface: 'border-warning-text/30 bg-warning/10 dark:bg-warning/20',
+        icon: 'text-warning-text',
+        Icon: TriangleAlertIcon,
+    },
+    destructive: {
+        surface: 'border-destructive-text/30 bg-destructive/10 dark:bg-destructive/20',
+        icon: 'text-destructive-text',
+        Icon: CircleAlertIcon,
+    },
+};
+export function Notice({ tone = 'info', title, children, action, icon, className }) {
+    const look = TONE[tone];
+    const Icon = icon ?? look.Icon;
+    return (_jsxs(Alert, { role: undefined, "data-slot": "notice", "data-tone": tone, 
+        // Flex, not Alert's grid, so the action wraps under the message on a
+        // narrow screen instead of squeezing it.
+        className: cn('flex flex-wrap items-start gap-x-3 gap-y-2 px-4 py-3 text-foreground', look.surface, className), children: [_jsx("span", { className: cn('mt-0.5 shrink-0', look.icon), children: _jsx(Icon, { "aria-hidden": "true", className: "size-4" }) }), _jsxs("div", { className: "flex min-w-0 flex-1 basis-48 flex-col gap-0.5", children: [title && _jsx(AlertTitle, { className: "font-semibold", children: title }), _jsx(AlertDescription, { className: "text-foreground", children: children })] }), action && _jsx("div", { className: "flex shrink-0 items-center gap-2 pl-7 sm:pl-0", children: action })] }));
+}

package/dist/components/app/source-credit.d.ts

@@ -0,0 +1,14 @@
+export type Source = {
+    /** The service's name, the link's text: "TMDB". */
+    name: string;
+    /** Its site; the link opens in a new tab. */
+    href: string;
+    /** A sentence the service's terms ask for, shown after the list as written. */
+    note?: string;
+};
+export type SourceCreditProps = {
+    sources: Source[];
+    /** What comes before the names. Defaults to "Data from". */
+    lead?: string;
+};
+export declare function SourceCredit({ sources, lead }: SourceCreditProps): import("react").JSX.Element | null;

package/dist/components/app/source-credit.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Credits the outside services a record's data comes from, as many free
+// APIs require on every screen showing their data ("This product uses the
+// TMDB API but is not endorsed or certified by TMDB"). EntityView's
+// `footer` is its usual home. Text and links only: a service's logo and
+// its usage rules are the app's.
+import { Fragment } from 'react';
+import { ExternalLinkIcon } from 'lucide-react';
+function joined(index, count) {
+    if (index === 0)
+        return '';
+    if (index === count - 1)
+        return count === 2 ? ' and ' : ', and ';
+    return ', ';
+}
+export function SourceCredit({ sources, lead = 'Data from' }) {
+    if (sources.length === 0)
+        return null;
+    const notes = sources.flatMap((source) => (source.note ? [source.note] : []));
+    return (_jsxs("p", { "data-slot": "source-credit", className: "type-caption text-muted-foreground", children: [lead, ' ', sources.map((source, index) => (_jsxs(Fragment, { children: [joined(index, sources.length), _jsxs("a", { href: source.href, target: "_blank", rel: "noreferrer", className: "rounded-sm underline underline-offset-2 outline-none hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50", children: [source.name, _jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "ml-0.5 inline size-3 align-baseline" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] })] }, source.name))), ".", notes.map((note) => ` ${note}`).join('')] }));
+}

package/dist/components/ui/alert.d.ts

@@ -0,0 +1,10 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+declare const alertVariants: (props?: ({
+    variant?: "default" | "destructive" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare function Alert({ className, variant, ...props }: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>): React.JSX.Element;
+declare function AlertTitle({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function AlertDescription({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function AlertAction({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+export { Alert, AlertTitle, AlertDescription, AlertAction };

package/dist/components/ui/alert.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { cn } from "cn";
+const alertVariants = cva("group/alert relative grid w-full gap-0.5 rounded-lg border px-2.5 py-2 text-left text-sm has-data-[slot=alert-action]:relative has-data-[slot=alert-action]:pr-18 has-[>svg]:grid-cols-[auto_1fr] has-[>svg]:gap-x-2 *:[svg]:row-span-2 *:[svg]:translate-y-0.5 *:[svg]:text-current *:[svg:not([class*='size-'])]:size-4", {
+    variants: {
+        variant: {
+            default: "bg-card text-card-foreground",
+            // Patched (ui-foundation): upstream's text-destructive is the solid
+            // fill's shade, 3.2:1 on the dark card; text is --destructive-text.
+            destructive: "bg-card text-destructive-text *:data-[slot=alert-description]:text-destructive-text *:[svg]:text-current",
+        },
+    },
+    defaultVariants: {
+        variant: "default",
+    },
+});
+function Alert({ className, variant, ...props }) {
+    return (_jsx("div", { "data-slot": "alert", role: "alert", className: cn(alertVariants({ variant }), className), ...props }));
+}
+function AlertTitle({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "alert-title", className: cn("font-medium group-has-[>svg]/alert:col-start-2 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground", className), ...props }));
+}
+function AlertDescription({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "alert-description", className: cn("text-sm text-balance text-muted-foreground md:text-pretty [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4", className), ...props }));
+}
+function AlertAction({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "alert-action", className: cn("absolute top-2 right-2", className), ...props }));
+}
+export { Alert, AlertTitle, AlertDescription, AlertAction };

package/dist/index.d.ts

@@ -22,6 +22,8 @@ export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { PillFilter, type PillFilterOption, type PillFilterProps } from './components/app/pill-filter.js';
 export { SecondaryFilters, type ActiveFilter, type SecondaryFiltersProps } from './components/app/secondary-filters.js';
 export { StageCircle, type StageCircleProps, type StageCircleStage, type StageCircleTone, } from './components/app/stage-circle.js';
+export { Notice, type NoticeProps, type NoticeTone } from './components/app/notice.js';
+export { SourceCredit, type Source, type SourceCreditProps } from './components/app/source-credit.js';
 export { WidgetCard, WidgetList, WidgetListItem, type WidgetCardProps, type WidgetListItemProps, } from './components/app/widget-card.js';
 export { ThemeProvider } from './components/theme-provider.js';
 export { LoginRoute, type LoginRouteProps } from './routes/login.js';

package/dist/index.js

@@ -27,6 +27,8 @@ export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { PillFilter } from './components/app/pill-filter.js';
 export { SecondaryFilters } from './components/app/secondary-filters.js';
 export { StageCircle, } from './components/app/stage-circle.js';
+export { Notice } from './components/app/notice.js';
+export { SourceCredit } from './components/app/source-credit.js';
 export { WidgetCard, WidgetList, WidgetListItem, } from './components/app/widget-card.js';
 export { ThemeProvider } from './components/theme-provider.js';
 // Screens outside the app shell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.9.1",
+  "version": "4.10.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {