@olenbetong/appframe-ds 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @olenbetong/appframe-ds
 
+## 0.5.0
+
+### Minor Changes
+
+- a118bef: Add Aksel-inspired `Page` primitives (`Page`, `Page.Block`, `Page.Header`) replacing the now-deprecated `AppLayout`, `AppLayoutDesktop`, `AppLayoutMobile` and `PageContainer`. `Page` supports both normal document scrolling and full-viewport app layouts (`layout="app"`, replacing `fullHeight`), `Page.Block` handles max-width/gutters/centering, and `Page.Header` comes in `appbar` (with responsive app menu drawer) and `plain` variants — both prepared for the upcoming sidebar-free site layout.
+
+  Add a `Paper` surface component (MUI `Paper` equivalent): neutral surface background, rounded corners and `--ds-shadow-*` elevation, with an optional `border` for an outlined variant. Pages using the `Page` primitive get a tinted body background (`--ds-color-neutral-background-tinted`) so surfaces stand out, matching the old site design.
+
+  Add `ItemList` components (`ItemList`, `ItemList.Item`, `ItemList.ItemText`) equivalent to MUI `List`/`ListItem`/`ListItemText`, for flex-row lists with dividers and primary/secondary text — typically rendered inside a `Paper` (`<Paper as={ItemList}>`).
+
 ## 0.4.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olenbetong/appframe-ds",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Components that bind Designsystemet components to Appframe data objects",
   "type": "module",
   "types": "./es/index.d.ts",

package/scripts/copyAssets.mjs

@@ -12,9 +12,17 @@ const files = [
 	["src/layout/index.css", "es/layout/index.css"],
 	["src/layout/ErrorBoundary.css", "es/layout/ErrorBoundary.css"],
 	["src/layout/PageContainer.css", "es/layout/PageContainer.css"],
+	["src/page/Page.css", "es/page/Page.css"],
+	["src/page/PageBlock.css", "es/page/PageBlock.css"],
+	["src/page/PageHeader.css", "es/page/PageHeader.css"],
+	["src/list/ItemList.css", "es/list/ItemList.css"],
+	["src/paper/Paper.css", "es/paper/Paper.css"],
 ];
 
 mkdirSync("es/layout", { recursive: true });
+mkdirSync("es/list", { recursive: true });
+mkdirSync("es/page", { recursive: true });
+mkdirSync("es/paper", { recursive: true });
 
 for (let [src, dest] of files) {
 	cpSync(src, dest);

package/src/index.ts

@@ -1,3 +1,6 @@
 export * from "./AfLookup/index.js";
 export * from "./binding/index.js";
 export * from "./layout/index.js";
+export * from "./list/index.js";
+export * from "./page/index.js";
+export * from "./paper/index.js";

package/src/layout/AppLayoutDesktop.tsx

@@ -21,6 +21,9 @@ function LoadingFallback() {
 	);
 }
 
+/**
+ * @deprecated Use the `Page` primitives instead (`Page`, `Page.Header`, `Page.Block`).
+ */
 export function AppLayoutDesktop({ AppMenuProps, children, menu, partner }: AppLayoutProps) {
 	let [open, setOpen] = useState(true);
 

package/src/layout/AppLayoutMobile.tsx

@@ -15,6 +15,9 @@ function Toggle({ onToggle }: { onToggle: () => void }) {
 	);
 }
 
+/**
+ * @deprecated Use the `Page` primitives instead (`Page`, `Page.Header`, `Page.Block`).
+ */
 export function AppLayoutMobile({ AppMenuProps, children, menu, partner }: AppLayoutProps) {
 	let [drawerOpen, setDrawerOpen] = useState(false);
 	let location = useLocation();

package/src/layout/AppMenu.css

@@ -7,6 +7,7 @@
 	letter-spacing: -0.02rem;
 	font-size: var(--ds-font-size-xl, 1.5rem);
 	margin: 0;
+	color: var(--ds-color-neutral-text-default, #1e2b3c);
 }
 
 .AppMenu-header .AppMenu-subTitle {

package/src/layout/PageContainer.tsx

@@ -8,6 +8,12 @@ export type PageContainerProps = React.HTMLAttributes<HTMLDivElement> & {
 	maxWidth?: "xs" | "sm" | "md" | "lg" | "xl" | false;
 };
 
+/**
+ * @deprecated Use `Page.Block` instead. `maxWidth` mapping: `xs`/`sm` →
+ * `width="text"`, `md` → `"md"`, `lg` → `"lg"`, `xl` → `"xl"`, `false` → omit
+ * `width`. Replace `fullHeight` with `<Page layout="app">` and
+ * `<Page.Block grow overflow="auto">`.
+ */
 export function PageContainer({ children, className, fullHeight, maxWidth, ...props }: PageContainerProps) {
 	return (
 		<div className={clsx("ObPageContainer-root", fullHeight && "ObPageContainer-fullHeight")}>

package/src/layout/index.tsx

@@ -54,6 +54,11 @@ export * from "./ErrorBoundary.js";
 export * from "./PageContainer.js";
 export * from "./PartnerToggle.js";
 
+/**
+ * @deprecated Use the `Page` primitives instead (`Page`, `Page.Header`,
+ * `Page.Block`). `<AppLayout menu={...} title={...}>` becomes
+ * `<Page layout="app"><Page.Header title={...} menu={...} />...</Page>`.
+ */
 export function AppLayout(props: AppLayoutProps) {
 	let isSmall = useIsMobile();
 	let Component = isSmall ? AppLayoutMobile : AppLayoutDesktop;

package/src/list/ItemList.css

@@ -0,0 +1,30 @@
+.ObItemList-root {
+	list-style: none;
+	margin: 0;
+	padding: 0;
+}
+
+.ObItemList-dividers > .ObItemListItem-root:not(:last-child) {
+	border-bottom: var(--ds-border-width-default, 1px) solid var(--ds-color-neutral-border-subtle, #dfdfdf);
+}
+
+.ObItemListItem-root {
+	display: flex;
+	align-items: center;
+	gap: var(--ds-size-3, 0.75rem);
+	padding: var(--ds-size-2, 0.5rem) var(--ds-size-3, 0.75rem);
+}
+
+.ObItemListItem-disablePadding {
+	padding: 0;
+}
+
+.ObItemListItemText-root {
+	flex: 1 1 auto;
+	min-width: 0;
+}
+
+.ObItemListItemText-secondary {
+	font-size: 0.875rem;
+	color: var(--ds-color-neutral-text-subtle, #666);
+}

package/src/list/ItemList.tsx

@@ -0,0 +1,52 @@
+import "./ItemList.css";
+
+import clsx from "clsx";
+import type React from "react";
+
+import { ItemListItem } from "./ItemListItem.js";
+import { ItemListItemText } from "./ItemListItemText.js";
+
+export type ItemListProps = React.HTMLAttributes<HTMLElement> & {
+	/**
+	 * Overrides the rendered element (e.g. `"ol"`, `"menu"`)
+	 * @default "ul"
+	 */
+	as?: React.ElementType;
+	children?: React.ReactNode;
+	/**
+	 * Renders a divider between items
+	 * @default true
+	 */
+	dividers?: boolean;
+};
+
+function ItemListComponent({ as: Component = "ul", children, className, dividers = true, ...props }: ItemListProps) {
+	return (
+		<Component className={clsx("ObItemList-root", dividers && "ObItemList-dividers", className)} {...props}>
+			{children}
+		</Component>
+	);
+}
+
+/**
+ * List of flex-row items, equivalent to MUI `List`/`ListItem`. Named
+ * `ItemList` to avoid clashing with the designsystemet `List` component
+ * (which renders regular text lists). Typically used inside a `Paper`.
+ *
+ * @example
+ * ```jsx
+ * <Paper as={ItemList}>
+ *   {records.map((record) => (
+ *     <ItemList.Item key={record.PrimKey}>
+ *       <img src="..." alt="" />
+ *       <ItemList.ItemText primary={record.Title} secondary={record.Slug} />
+ *       <Button>...</Button>
+ *     </ItemList.Item>
+ *   ))}
+ * </Paper>
+ * ```
+ */
+export const ItemList = Object.assign(ItemListComponent, {
+	Item: ItemListItem,
+	ItemText: ItemListItemText,
+});

package/src/list/ItemListItem.tsx

@@ -0,0 +1,41 @@
+import clsx from "clsx";
+import type React from "react";
+
+export type ItemListItemProps = React.HTMLAttributes<HTMLElement> & {
+	/**
+	 * Overrides the rendered element
+	 * @default "li"
+	 */
+	as?: React.ElementType;
+	children?: React.ReactNode;
+	ref?: React.Ref<HTMLElement>;
+	/**
+	 * Removes the inline/block padding, e.g. when the item content is a
+	 * link or button that should span the full row (add the padding on the
+	 * interactive child instead so the whole row is clickable).
+	 * @default false
+	 */
+	disablePadding?: boolean;
+};
+
+/**
+ * A single flex-row item inside an `ItemList`. Children are laid out
+ * horizontally with a standard gap; use `ItemList.ItemText` for the
+ * primary/secondary text block.
+ */
+export function ItemListItem({
+	as: Component = "li",
+	children,
+	className,
+	disablePadding,
+	...props
+}: ItemListItemProps) {
+	return (
+		<Component
+			className={clsx("ObItemListItem-root", disablePadding && "ObItemListItem-disablePadding", className)}
+			{...props}
+		>
+			{children}
+		</Component>
+	);
+}

package/src/list/ItemListItemText.tsx

@@ -0,0 +1,23 @@
+import clsx from "clsx";
+import type React from "react";
+
+export type ItemListItemTextProps = React.HTMLAttributes<HTMLElement> & {
+	children?: React.ReactNode;
+	/** Primary line. `children` can be used instead. */
+	primary?: React.ReactNode;
+	/** Secondary line, rendered smaller with subtle text color */
+	secondary?: React.ReactNode;
+};
+
+/**
+ * Text block inside an `ItemList.Item`. Fills the remaining row space and
+ * renders a primary and an optional secondary line, like MUI `ListItemText`.
+ */
+export function ItemListItemText({ children, className, primary, secondary, ...props }: ItemListItemTextProps) {
+	return (
+		<div className={clsx("ObItemListItemText-root", className)} {...props}>
+			<div className="ObItemListItemText-primary">{primary ?? children}</div>
+			{secondary != null && <div className="ObItemListItemText-secondary">{secondary}</div>}
+		</div>
+	);
+}

package/src/list/index.ts

@@ -0,0 +1,3 @@
+export * from "./ItemList.js";
+export * from "./ItemListItem.js";
+export * from "./ItemListItemText.js";

package/src/page/Page.css

@@ -0,0 +1,45 @@
+@media screen {
+	/*
+	 * Pages get a tinted background so surfaces (Paper, drawer, dialogs —
+	 * which use neutral-background/surface-default) stand out, matching the
+	 * old site design. Scoped to Page usage so the token itself is untouched.
+	 */
+	body:has(.ObPage-root) {
+		background-color: var(--ds-color-neutral-background-tinted, #f3f3f4);
+	}
+
+	.ObPage-root {
+		display: flex;
+		flex-direction: column;
+		box-sizing: border-box;
+	}
+
+	.ObPage-document {
+		min-height: 100%;
+	}
+
+	.ObPage-app {
+		height: 100vh;
+		height: 100dvh;
+		overflow: hidden;
+	}
+
+	/* Offset content when a docked Page.Header drawer is open (desktop) */
+	.ObPage-root:has(.ObPageHeader-drawer.ObPageHeader-drawerDocked.ObPageHeader-drawerOpen) {
+		padding-left: var(--ob-page-drawer-width, 20rem);
+		transition: padding-left 225ms cubic-bezier(0.4, 0, 0.2, 1);
+	}
+}
+
+@media print {
+	.ObPage-root,
+	.ObPage-app {
+		display: block;
+		height: auto;
+		overflow: visible;
+	}
+
+	.ObPage-root:has(.ObPageHeader-drawer.ObPageHeader-drawerDocked.ObPageHeader-drawerOpen) {
+		padding-left: 0;
+	}
+}

package/src/page/Page.tsx

@@ -0,0 +1,70 @@
+import "./Page.css";
+
+import clsx from "clsx";
+import type React from "react";
+
+import { PageBlock } from "./PageBlock.js";
+import { PageHeader } from "./PageHeader.js";
+
+export type PageLayout = "document" | "app";
+
+export type PageProps = React.HTMLAttributes<HTMLElement> & {
+	/**
+	 * Overrides the rendered element
+	 * @default "div"
+	 */
+	as?: React.ElementType;
+	children?: React.ReactNode;
+	/**
+	 * Top-level layout strategy for the page.
+	 *
+	 * - `"document"` (default): normal document flow — the page grows with its
+	 *   content and the document scrolls.
+	 * - `"app"`: the page fills the available viewport height with
+	 *   `overflow: hidden`, and scrolling is delegated down the tree (use
+	 *   `Page.Block` with `grow`/`overflow="auto"`, or utilities like
+	 *   `.scroll-view`). Replaces the old `PageContainer` `fullHeight` prop.
+	 *
+	 * @default "document"
+	 */
+	layout?: PageLayout;
+};
+
+function PageComponent({ as: Component = "div", children, className, layout = "document", ...props }: PageProps) {
+	return (
+		<Component
+			className={clsx("ObPage-root", layout === "app" ? "ObPage-app" : "ObPage-document", className)}
+			{...props}
+		>
+			{children}
+		</Component>
+	);
+}
+
+/**
+ * Top-level layout primitive for application pages, inspired by the Aksel
+ * `Page` primitives. Composes with `Page.Header` and `Page.Block`.
+ *
+ * Works both in the current sidebar-based site layout and the upcoming
+ * toolbar-based (sidebar-free) site layout.
+ *
+ * @example Document-style page (content scrolls with the document)
+ * ```jsx
+ * <Page>
+ *   <Page.Header variant="plain" title="Report issue" />
+ *   <Page.Block as="main" width="text" gutters>...</Page.Block>
+ * </Page>
+ * ```
+ *
+ * @example App-style page (fills the viewport, scrolling delegated down the tree)
+ * ```jsx
+ * <Page layout="app">
+ *   <Page.Header title="Products" menu={<ProductsMenu />} />
+ *   <Page.Block as="main" gutters grow overflow="auto">...</Page.Block>
+ * </Page>
+ * ```
+ */
+export const Page = Object.assign(PageComponent, {
+	Block: PageBlock,
+	Header: PageHeader,
+});

package/src/page/PageBlock.css

@@ -0,0 +1,59 @@
+.ObPageBlock-root {
+	box-sizing: border-box;
+	width: 100%;
+	margin-inline: auto;
+}
+
+.ObPageBlock-text {
+	max-width: calc(36rem + 2 * var(--ob-page-gutter, 0rem));
+}
+
+.ObPageBlock-md {
+	max-width: 48rem;
+}
+
+.ObPageBlock-lg {
+	max-width: 64rem;
+}
+
+.ObPageBlock-xl {
+	max-width: 80rem;
+}
+
+.ObPageBlock-2xl {
+	max-width: 90rem;
+}
+
+.ObPageBlock-gutters {
+	--ob-page-gutter: 1rem;
+
+	padding-inline: var(--ob-page-gutter);
+}
+
+@media screen and (min-width: 600px) {
+	.ObPageBlock-gutters {
+		--ob-page-gutter: 1.5rem;
+	}
+}
+
+@media screen {
+	.ObPageBlock-grow {
+		flex: 1 1 auto;
+		min-height: 0;
+	}
+
+	.ObPageBlock-overflowAuto {
+		overflow: auto;
+	}
+
+	.ObPageBlock-overflowHidden {
+		overflow: hidden;
+	}
+}
+
+@media print {
+	.ObPageBlock-overflowAuto,
+	.ObPageBlock-overflowHidden {
+		overflow: visible;
+	}
+}

package/src/page/PageBlock.tsx

@@ -0,0 +1,78 @@
+import "./PageBlock.css";
+
+import clsx from "clsx";
+import type React from "react";
+
+export const pageBlockWidths = ["text", "md", "lg", "xl", "2xl"] as const;
+
+export type PageBlockWidth = (typeof pageBlockWidths)[number];
+
+export type PageBlockProps = React.HTMLAttributes<HTMLElement> & {
+	/**
+	 * Overrides the rendered element (e.g. `"main"`, `"header"`, `"footer"`)
+	 * @default "div"
+	 */
+	as?: React.ElementType;
+	children?: React.ReactNode;
+	/**
+	 * Fills the remaining space of the parent `Page`. Combine with
+	 * `overflow="auto"` inside `<Page layout="app">` to make the block the
+	 * scroll container.
+	 * @default false
+	 */
+	grow?: boolean;
+	/**
+	 * Adds a standardised responsive inline padding
+	 * @default false
+	 */
+	gutters?: boolean;
+	/**
+	 * Overflow behaviour of the block. Only relevant inside
+	 * `<Page layout="app">`, where scrolling is delegated down the tree.
+	 */
+	overflow?: "auto" | "hidden";
+	/**
+	 * Predefined max-width. Content is horizontally centered.
+	 *
+	 * - `text`: 36rem (576px) — recommended line-length for running text
+	 * - `md`: 48rem (768px)
+	 * - `lg`: 64rem (1024px)
+	 * - `xl`: 80rem (1280px)
+	 * - `2xl`: 90rem (1440px)
+	 *
+	 * @default max-width: 100%
+	 */
+	width?: PageBlockWidth;
+};
+
+/**
+ * Layout block for defining max-width, gutters and horizontal centering.
+ * Replaces the deprecated `PageContainer` (`maxWidth` mapping: `xs`/`sm` →
+ * `text`, `md` → `md`, `lg` → `lg`, `xl` → `xl`, `false` → no `width`).
+ */
+export function PageBlock({
+	as: Component = "div",
+	children,
+	className,
+	grow,
+	gutters,
+	overflow,
+	width,
+	...props
+}: PageBlockProps) {
+	return (
+		<Component
+			className={clsx(
+				"ObPageBlock-root",
+				width && `ObPageBlock-${width}`,
+				gutters && "ObPageBlock-gutters",
+				grow && "ObPageBlock-grow",
+				overflow && `ObPageBlock-overflow${overflow === "auto" ? "Auto" : "Hidden"}`,
+				className,
+			)}
+			{...props}
+		>
+			{children}
+		</Component>
+	);
+}

package/src/page/PageHeader.css

@@ -0,0 +1,148 @@
+.ObPageHeader-root {
+	flex: 0 0 auto;
+}
+
+/* --- appbar variant --- */
+
+.ObPageHeader-appbar {
+	background-color: var(--ds-color-brand-base-default, #0062ba);
+	color: var(--ds-color-brand-base-contrast-default, #fff);
+}
+
+.ObPageHeader-appbar .ObPageHeader-bar {
+	display: flex;
+	align-items: center;
+	gap: 0.5rem;
+	min-height: var(--ob-page-appbar-height, 3.5rem);
+	padding-inline: 0.5rem 1rem;
+}
+
+.ObPageHeader-title {
+	flex: 1 1 auto;
+	margin: 0;
+	font-size: var(--ds-font-size-lg, 1.25rem);
+	font-weight: 500;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.ObPageHeader-actions {
+	display: flex;
+	align-items: center;
+	gap: 0.5rem;
+	margin-left: auto;
+}
+
+.ObPageHeader-title + .ObPageHeader-actions {
+	margin-left: 0;
+}
+
+.ObPageHeader-toggle {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	background: transparent;
+	border: none;
+	color: inherit;
+	cursor: pointer;
+	border-radius: 50%;
+	height: 2.75rem;
+	width: 2.75rem;
+	font-size: 1.5rem;
+	flex-shrink: 0;
+}
+
+.ObPageHeader-toggle:hover {
+	background-color: rgb(255 255 255 / 0.12);
+}
+
+/* --- plain variant --- */
+
+.ObPageHeader-plainInner {
+	display: flex;
+	align-items: center;
+	gap: 0.5rem;
+}
+
+.ObPageHeader-plainTitle {
+	margin: 0;
+	font-size: var(--ds-font-size-xl, 1.5rem);
+	font-weight: 500;
+}
+
+/*
+ * Reserved slot for the app-launcher and user profile menu in the future
+ * sidebar-free site layout. Hidden under the current sidebar layout; the
+ * activation mechanism is decided together with the new website template.
+ */
+.ObPageHeader-end {
+	display: none;
+}
+
+/* --- drawer --- */
+
+@media screen {
+	.ObPageHeader-drawer {
+		position: fixed;
+		top: 0;
+		left: 0;
+		bottom: 0;
+		width: var(--ob-page-drawer-width, 20rem);
+		max-width: 90%;
+		box-sizing: border-box;
+		background-color: var(--ds-color-neutral-background-default, #fff);
+		color: var(--ds-color-neutral-text-default, #1e2b3c);
+		transform: translateX(-100%);
+		transition: transform 225ms cubic-bezier(0, 0, 0.2, 1);
+		overflow: hidden;
+		display: flex;
+		flex-direction: column;
+	}
+
+	.ObPageHeader-drawer > .MenuItems-root {
+		flex: 1 1 auto;
+		min-height: 0;
+	}
+
+	.ObPageHeader-drawer.ObPageHeader-drawerOpen {
+		transform: translateX(0);
+	}
+
+	.ObPageHeader-drawerDocked {
+		border-right: 1px solid var(--ds-color-neutral-border-subtle, #dfdfdf);
+		z-index: 1100;
+	}
+
+	.ObPageHeader-drawerOverlayMode {
+		z-index: 1200;
+		box-shadow:
+			rgb(0 0 0 / 20%) 0px 8px 10px -5px,
+			rgb(0 0 0 / 14%) 0px 16px 24px 2px,
+			rgb(0 0 0 / 12%) 0px 6px 30px 5px;
+	}
+
+	.ObPageHeader-drawerOverlay {
+		position: fixed;
+		inset: 0;
+		background-color: rgb(0 0 0 / 50%);
+		z-index: 1199;
+		opacity: 0;
+		pointer-events: none;
+		transition: opacity 225ms cubic-bezier(0.4, 0, 0.2, 1);
+	}
+
+	.ObPageHeader-drawerOverlay.ObPageHeader-drawerOpen {
+		opacity: 1;
+		pointer-events: auto;
+	}
+}
+
+@media print {
+	.ObPageHeader-appbar .ObPageHeader-bar,
+	.ObPageHeader-drawer,
+	.ObPageHeader-drawerOverlay,
+	.ObPageHeader-toggle {
+		display: none !important;
+	}
+}