@hackcove/ui 0.2.5 → 0.2.6

package/README.md

@@ -40,7 +40,7 @@ export const Example = () => (
 ## What is exported
 
 - Primitives: `Card` (a bordered panel; `title` and `count` make a small heading; `flush` drops the padding and clips the corners, for a table that runs edge to edge; `bar` moves the title, count and `actions` into a tinted strip over the body; `dashed` is an empty-state shell with centred muted text; `as` is `section` (default), `article` or `div`),  `EpicHeader`, `Empty`, `PageTitle` (deprecated: use `PageHeader`), `Pill`, `groupByEpic`, `Markdown`.
-- Layout (see Layout): `AppShell`, `appShellRootClass`, `Container`, `PageHeader`, `Stack`, `Section`, and the page layouts `ListLayout`, `DetailLayout`, `FormLayout`, `ProseLayout`, `CardGrid`, `SidebarLayout`, `FullBleedLayout`, `CenteredLayout`.
+- Layout (see Layout): `AppShell`, `AppShellBrand`, `appShellRootClass`, `appShellRootClassFor`, `Container`, `PageHeader`, `Stack`, `Section`, and the page layouts `ListLayout`, `DetailLayout`, `FormLayout`, `ProseLayout`, `CardGrid`, `SidebarLayout`, `FullBleedLayout`, `CenteredLayout`.
 - Typography roles (each pins size + weight, takes a `color` and an `as`): `Display`, `Lead`,
   `PageHeading`, `SectionHeading`, `SubsectionHeading`, `ModalHeading`, `Subtitle`, `Overline`,
   `Body`, `BodyStrong`, `Caption`. Three opt-in props, none changing today's look: `SectionHeading rule`
@@ -137,9 +137,25 @@ import { AppShell, PageHeader, Section, Stack, appShellRootClass } from "@hackco
   with fixed `py-8`, and an optional `footer`. The header row is filled by slots, left to right:
   `brand` (logo and name, at the brand type with the logo gap), `nav` (a `NavTabs`), `header` (a
   free node, the escape hatch) and `controls` (end-aligned, `gap-2`, centred): no wrapper, no
-  `className`. `hideChromeInPrint` is opt-in: the header and footer are hidden in print and main
+  `className`. Nothing in `controls` shrinks, and a full-width control there (a `Select` at its
+  default `width="full"`) sizes to its content, so a `Select` next to a `ColourSchemeToggle` leaves
+  the toggle its square. `hideChromeInPrint` is opt-in: the header and footer are hidden in print and main
   drops its padding (the page margin is then your `@page`); without it a print is unchanged. `bleed` drops main's `Container` for a full-bleed
   page; the header keeps its own, so put a `Container` back around anything that should line up.
+- **`AppShellBrand`** is the `brand` slot as one link: `logo` and `label` inside the same `<a>`, so
+  the whole brand goes home (the label names the link; the logo is hidden from assistive tech). With
+  `render` it draws your router's `<Link>`, as `NavTabs`, `Breadcrumbs` and `TextLink` do:
+
+  ```tsx
+  <AppShell brand={<AppShellBrand logo={<Avatar name="Quotes" size="sm" />} label="Quotes"
+    render={(props) => <Link to="/" {...props} />} />} …>
+  ```
+
+  A plain node in `brand` still works. Stories: `Layout/AppShell › LinkedBrand`, `RouterBrand`.
+- **`appShellRootClassFor(scheme, schemes?)`** is what goes on `<html>` when the server knows the
+  scheme: that scheme's class and `appShellRootClass`, joined, so there is no string concatenation:
+  `<html className={appShellRootClassFor(scheme, schemes)}>`. `appShellRootClass` and `schemeClass`
+  stay exported.
 - **`Container`** is the only place the content width (`max-w-6xl`) and side padding
   (`px-4 sm:px-6`) are defined. **Pages never set their own width or outer padding**: no `max-w-*`,
   no `mx-auto`, no `px-*` on a page. AppShell already gives them the edge.

package/dist/AppShell.d.ts

@@ -1,9 +1,34 @@
 import { type ReactElement, type ReactNode } from "react";
+import { type ColourScheme, type ColourSchemeClasses } from "./colourScheme.js";
+import { type LinkRender } from "./link.js";
 /**
  * The class an app puts on its own `<html>`: it always reserves the scrollbar, so centred content
  * does not shift between a short page and a long one. AppShell never touches `<html>` itself.
  */
 export declare const appShellRootClass = "overflow-y-scroll";
+/**
+ * Everything an app puts on its own `<html>` from the scheme the server knows: that scheme's class
+ * (`schemeClass`) and `appShellRootClass`, joined. `<html className={appShellRootClassFor(scheme,
+ * schemes)}>` replaces `schemeClass(scheme, schemes) + " " + appShellRootClass`.
+ */
+export declare function appShellRootClassFor(scheme: ColourScheme, schemes?: ColourSchemeClasses): string;
+/**
+ * The `brand` slot as one link: a logo and a label inside the same `<a>`, so the whole brand is the
+ * way home. The label names the link; the logo is decoration and hidden from assistive tech. With
+ * `render` it draws the app's own router `<Link>` (`render={(p) => <Link to="/" {...p} />}`).
+ */
+export declare function AppShellBrand({ logo, label, href, render, }: {
+    /** The mark before the label, e.g. an `Avatar` or an `<img>`. */
+    logo?: ReactNode;
+    /** The name beside the logo. It is the link's accessible name. */
+    label: ReactNode;
+} & ({
+    href: string;
+    render?: LinkRender | undefined;
+} | {
+    href?: string | undefined;
+    render: LinkRender;
+})): ReactElement;
 /**
  * The page frame: a sticky one-row header, an optional second `subnav` row, the main area and an
  * optional footer. Header, main and footer each sit in a `Container`, so pages never set their own
@@ -15,11 +40,11 @@ export declare const appShellRootClass = "overflow-y-scroll";
  * `className` for any of them.
  */
 export declare function AppShell({ brand, nav, controls, header, subnav, footer, bleed, hideChromeInPrint, children, }: {
-    /** The brand: a logo and a name, in the header's brand type, with the gap between them. */
+    /** The brand: a logo and a name, in the header's brand type, with the gap between them. `AppShellBrand` makes both one link. */
     brand?: ReactNode;
     /** The main navigation, e.g. `NavTabs` (it is already a `<nav>`). */
     nav?: ReactNode;
-    /** The end of the row: a picker, a theme toggle. Gap-2, vertically centred. */
+    /** The end of the row: a picker, a theme toggle. Gap-2, vertically centred; no child shrinks, and a full-width control (a `Select` at its default) sizes to its content. */
     controls?: ReactNode;
     /** The escape hatch: a free node in the header row, after `brand` and `nav`. */
     header?: ReactNode;

package/dist/AppShell.js

@@ -1,12 +1,35 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
 import { Container } from "./Container.js";
-import { cx } from "./cx.js";
+import { schemeClass } from "./colourScheme.js";
+import { cx, focusRing } from "./cx.js";
+import { renderLink } from "./link.js";
 /**
  * The class an app puts on its own `<html>`: it always reserves the scrollbar, so centred content
  * does not shift between a short page and a long one. AppShell never touches `<html>` itself.
  */
 export const appShellRootClass = "overflow-y-scroll";
+/**
+ * Everything an app puts on its own `<html>` from the scheme the server knows: that scheme's class
+ * (`schemeClass`) and `appShellRootClass`, joined. `<html className={appShellRootClassFor(scheme,
+ * schemes)}>` replaces `schemeClass(scheme, schemes) + " " + appShellRootClass`.
+ */
+export function appShellRootClassFor(scheme, schemes) {
+    return cx(schemeClass(scheme, schemes), appShellRootClass);
+}
+/**
+ * The `brand` slot as one link: a logo and a label inside the same `<a>`, so the whole brand is the
+ * way home. The label names the link; the logo is decoration and hidden from assistive tech. With
+ * `render` it draws the app's own router `<Link>` (`render={(p) => <Link to="/" {...p} />}`).
+ */
+export function AppShellBrand({ logo, label, href, render, }) {
+    return renderLink({
+        href,
+        render,
+        className: cx("flex items-center gap-2 rounded", focusRing),
+        children: (_jsxs(_Fragment, { children: [logo && (_jsx("span", { "aria-hidden": "true", className: "flex shrink-0 items-center", children: logo })), _jsx("span", { children: label })] })),
+    });
+}
 // One fixed-height row that scrolls sideways and never wraps; its children keep their width.
 const ROW = "flex items-center gap-4 overflow-x-auto whitespace-nowrap *:shrink-0";
 // While a row has more to scroll to on a side, that edge fades out (a mask, so it follows any theme).
@@ -44,7 +67,7 @@ function ScrollRow({ className, children }) {
 }
 /** The header row's slots in order: brand, nav, the free `children`, then controls at the end. */
 function HeaderSlots({ brand, nav, controls, children, }) {
-    return (_jsxs(_Fragment, { children: [brand && (_jsx("div", { className: "flex items-center gap-2 text-base font-bold tracking-tight text-slate-900", children: brand })), nav, children, controls && _jsx("div", { className: "ml-auto flex items-center gap-2", children: controls })] }));
+    return (_jsxs(_Fragment, { children: [brand && (_jsx("div", { className: "flex items-center gap-2 text-base font-bold tracking-tight text-slate-900", children: brand })), nav, children, controls && (_jsx("div", { className: "ml-auto flex items-center gap-2 *:shrink-0 [&>.w-full]:w-auto", children: controls }))] }));
 }
 /**
  * The page frame: a sticky one-row header, an optional second `subnav` row, the main area and an

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { StatTile, type StatTileTone } from "./StatTile.js";
 export { ProgressBar, type BarSize, type BarTone } from "./ProgressBar.js";
 export { SplitBar } from "./SplitBar.js";
 export { Markdown } from "./Markdown.js";
-export { AppShell, appShellRootClass } from "./AppShell.js";
+export { AppShell, AppShellBrand, appShellRootClass, appShellRootClassFor } from "./AppShell.js";
 export { Container } from "./Container.js";
 export { PageHeader, type PageHeaderProps } from "./PageHeader.js";
 export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, ProseLayout, SidebarLayout, } from "./PageLayouts.js";

package/dist/index.js

@@ -4,7 +4,7 @@ export { StatTile } from "./StatTile.js";
 export { ProgressBar } from "./ProgressBar.js";
 export { SplitBar } from "./SplitBar.js";
 export { Markdown } from "./Markdown.js";
-export { AppShell, appShellRootClass } from "./AppShell.js";
+export { AppShell, AppShellBrand, appShellRootClass, appShellRootClassFor } from "./AppShell.js";
 export { Container } from "./Container.js";
 export { PageHeader } from "./PageHeader.js";
 export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, ProseLayout, SidebarLayout, } from "./PageLayouts.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackcove/ui",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Hack Cove React components: primitives, typography roles and a safe Markdown renderer, written against Tailwind v4 utilities. Pair with a @hackcove/theme-* package.",
   "keywords": [
     "components",