@windmorph/react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the Windmorph authors
+
+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/NOTICE

@@ -0,0 +1,23 @@
+@windmorph/react
+Copyright (c) 2026 the Windmorph authors. Licensed under the MIT License.
+
+This package bundles @material/material-color-utilities
+(https://github.com/material-foundation/material-color-utilities),
+Copyright 2021 Google LLC, licensed under the Apache License, Version 2.0
+(https://www.apache.org/licenses/LICENSE-2.0).
+
+Design tokens are derived from Jetpack Compose Material 3
+(https://android.googlesource.com/platform/frameworks/support), Copyright The
+Android Open Source Project, licensed under the Apache License, Version 2.0.
+
+The shape library (androidx.graphics.shapes and Compose Material 3 MaterialShapes) is a
+TypeScript port of code from the Android Open Source Project
+(https://android.googlesource.com/platform/frameworks/support), Copyright 2022-2025 The
+Android Open Source Project, licensed under the Apache License, Version 2.0. It was
+modified: translated to TypeScript with 64-bit arithmetic, the SVG parser, serializer and
+validation were left out, a bounds calculation was fixed for shapes in negative space, and
+paths are emitted as SVG path data.
+
+The icons drawn inside components (such as send, close and the formatting buttons) are
+Material Symbols path data (https://github.com/google/material-design-icons), Copyright
+Google LLC, licensed under the Apache License, Version 2.0.

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# @windmorph/react
 
-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.
+React components implementing **Material Design 3 Expressive**, built on
+[React Aria](https://react-spectrum.adobe.com/react-aria/), [Tailwind CSS v4](https://tailwindcss.com)
+and [Motion](https://motion.dev). Semantic design tokens, component tokens, six built-in themes,
+light and dark modes with three contrast levels, M3 Expressive springs, right-to-left support and
+accessible components by default. Works with Vite and Next.js (App Router and Pages Router).
+
+**Docs and live examples: [windmorph.dev](https://windmorph.dev/)**
+
+## Install
+
+```bash
+npm i @windmorph/react motion
+```
+
+Peer dependencies: `react` and `react-dom` 19, `motion` 14, and optionally `tailwindcss` 4.1 or
+later and `next` 15 or later.
+
+### Browser support
+
+0.1.0 is tested on Chrome and Edge. Safari 17.5+ and Firefox 129+ are supported targets, with
+full testing coming next. Older browsers skip some entry animations (`@starting-style`).
+
+### With Tailwind CSS v4
+
+```css
+/* globals.css */
+@import 'tailwindcss';
+@import '@windmorph/react/styles.css';
+@source '../node_modules/@windmorph/react';
+```
+
+`@source` lets Tailwind see the classes the components use; adjust the path to where
+`node_modules` sits relative to your CSS file. The colour roles, type scale, shapes and motion
+are then Tailwind utilities in your own code too (`bg-surface`, `text-on-surface-variant`,
+`text-body-large`, `rounded-corner-large`, …).
+
+### Without Tailwind
+
+Import `@windmorph/react/styles.compiled.css` instead: the same styles, already compiled.
+
+### Fonts
+
+Fonts are not bundled. Load [Roboto Flex](https://fonts.google.com/specimen/Roboto+Flex) with
+`next/font` or Google Fonts; without it, the system UI font is used.
+
+## Use
+
+Wrap the app in `ThemeProvider`:
+
+```tsx
+import { Button, ThemeProvider } from '@windmorph/react';
+
+export function App() {
+  return (
+    <ThemeProvider defaultTheme="baseline">
+      <Button variant="filled">Label</Button>
+    </ThemeProvider>
+  );
+}
+```
+
+`ThemeProvider` holds the theme, the mode (`light`, `dark` or `system`), the contrast level and
+the motion scheme, remembers the visitor's choice, and exposes it through `useTheme`.
+`ThemeScope` gives part of a page its own theme.
+
+## Next.js
+
+Interactive components are client components (`"use client"`), so server components can render
+them. The `@windmorph/react/next` entry adds:
+
+- `NextRouterProvider`, so the library's links (`href` on `Button`, `ListItem`, `Tab`, …) navigate
+  with the Next.js router;
+- `getThemeFromCookies` and `themeAttributes`, so the App Router renders the visitor's theme on the
+  server with no flash (`ThemeScript` does the same for static pages and the Pages Router);
+- `useNavigationGuard` and `useGuardedNavigate`, to ask before leaving unsaved changes.
+
+See the [Next.js guide](https://windmorph.dev/nextjs).
+
+## Custom themes
+
+Six themes are built in (`baseline`, `ocean`, `forest`, `sunset`, `rose`, `slate`). Make your
+own from a brand colour with the M3 2025 colour spec, and pass it to `ThemeProvider`:
+
+```tsx
+import { createTheme, ThemeProvider } from '@windmorph/react';
+
+const brand = createTheme({
+  name: 'brand',
+  seed: '#1877F2',
+  variant: 'vibrant', // tonal-spot (default) | neutral | vibrant | expressive
+  // Optional: take any of the six palettes from another variant or a hex colour,
+  // e.g. vivid accents on calm, nearly neutral surfaces.
+  palettes: { neutral: 'tonal-spot', neutralVariant: 'tonal-spot' },
+});
+
+<ThemeProvider themes={['baseline', brand]} defaultTheme="brand">
+  {children}
+</ThemeProvider>;
+```
+
+For static sites, the `windmorph` CLI writes the same CSS to a file:
+
+```bash
+npx @windmorph/react theme --name brand --seed "#1877F2" --variant vibrant \
+  --palette neutral=tonal-spot --palette neutral-variant=tonal-spot --out brand.css
+```
+
+See the [Theming guide](https://windmorph.dev/theming) for modes, contrast levels,
+`ThemeScope`, mixing palettes and flash-free server rendering.
+
+## Entries
+
+| Import                                 | What it holds                                                           |
+| -------------------------------------- | ----------------------------------------------------------------------- |
+| `@windmorph/react`                     | The components, theming, tokens and `cn()`                              |
+| `@windmorph/react/next`                | The Next.js helpers above                                               |
+| `@windmorph/react/primitives`          | Lower-level building blocks, for components built on top of the library |
+| `@windmorph/react/styles.css`          | The tokens, themes and utilities, for Tailwind CSS v4                   |
+| `@windmorph/react/styles.compiled.css` | The same, compiled, for apps without Tailwind                           |
+
+## Vite 8 and `"use client"`
+
+Vite 8 logs a harmless `MODULE_LEVEL_DIRECTIVE` warning for each `"use client"` module in
+client-only builds. To silence it:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  build: {
+    rolldownOptions: {
+      onLog(level, log, handler) {
+        if (log.code !== 'MODULE_LEVEL_DIRECTIVE') handler(level, log);
+      },
+    },
+  },
+});
+```
+
+## Documentation
+
+[windmorph.dev](https://windmorph.dev/) has the getting-started, theming, motion,
+customisation, accessibility, Next.js and from-Compose guides, the spec status, the release
+notes, and a page per component with live examples and generated props tables.
+
+## Licence
+
+MIT. Bundles `@material/material-color-utilities` and code ported from the Android Open Source
+Project (Apache-2.0); see `NOTICE`.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { CONTRAST_LEVEL_NAMES, PALETTE_NAMES, SCHEME_VARIANTS } from "./tokens/color.js";
+import { createTheme } from "./theme/create-theme.js";
+import { parseCustomColors, parsePalettes, toKebabCase } from "./theme/parse-palettes.js";
+import { writeFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+//#region src/cli.ts
+const USAGE = `Usage: npx @windmorph/react theme --seed <hex> --name <name> [options]
+
+Generates a static CSS colour theme (light, dark and system modes for each
+contrast level) using the Material 3 2025 colour spec.
+
+Options:
+  --seed <hex>          Seed colour, e.g. "#0B57D0" (required)
+  --name <name>         Theme name for data-theme, lowercase kebab-case (required)
+  --variant <variant>   ${SCHEME_VARIANTS.join(" | ")} (default: tonal-spot)
+  --palette <name>=<source>
+                        Takes one palette from elsewhere; repeatable. <name> is
+                        ${PALETTE_NAMES.map(toKebabCase).join(", ")};
+                        <source> is a variant or a hex colour, e.g.
+                        --palette neutral=tonal-spot --palette tertiary=#00A07A
+  --custom <name>=<hex>  Sets the success or warning colour; repeatable, e.g.
+                        --custom success=#0B8043 --custom warning=#E37400
+  --no-harmonize        Keeps the custom colours' exact hues (by default they turn
+                        toward the seed, as in Material Theme Builder)
+  --contrast <levels>   Comma-separated: ${CONTRAST_LEVEL_NAMES.join(",")} (default: all)
+  --out <file>          Write to a file instead of stdout
+  -h, --help            Show this message
+`;
+function fail(message) {
+	process.stderr.write(`Error: ${message}\n\n${USAGE}`);
+	process.exit(1);
+}
+const { positionals, values } = parseArgs({
+	allowPositionals: true,
+	options: {
+		seed: { type: "string" },
+		name: { type: "string" },
+		variant: {
+			type: "string",
+			default: "tonal-spot"
+		},
+		palette: {
+			type: "string",
+			multiple: true,
+			default: []
+		},
+		custom: {
+			type: "string",
+			multiple: true,
+			default: []
+		},
+		"no-harmonize": {
+			type: "boolean",
+			default: false
+		},
+		contrast: {
+			type: "string",
+			default: CONTRAST_LEVEL_NAMES.join(",")
+		},
+		out: { type: "string" },
+		help: {
+			type: "boolean",
+			short: "h"
+		}
+	}
+});
+if (values.help) {
+	process.stdout.write(USAGE);
+	process.exit(0);
+}
+if (positionals[0] !== "theme") fail("unknown command. Only \"theme\" is supported.");
+if (!values.seed) fail("--seed is required.");
+if (!values.name) fail("--name is required.");
+if (!SCHEME_VARIANTS.includes(values.variant)) fail(`--variant must be one of ${SCHEME_VARIANTS.join(", ")}.`);
+const contrast = values.contrast.split(",").map((level) => level.trim());
+for (const level of contrast) if (!CONTRAST_LEVEL_NAMES.includes(level)) fail(`unknown contrast level "${level}".`);
+let palettes = {};
+try {
+	palettes = parsePalettes(values.palette);
+} catch (error) {
+	fail(error instanceof Error ? error.message : String(error));
+}
+let customColors = {};
+try {
+	customColors = parseCustomColors(values.custom);
+} catch (error) {
+	fail(error instanceof Error ? error.message : String(error));
+}
+let css;
+try {
+	css = createTheme({
+		name: values.name,
+		seed: values.seed,
+		variant: values.variant,
+		palettes,
+		customColors,
+		harmonize: !values["no-harmonize"],
+		contrast
+	}).css;
+} catch (error) {
+	fail(error instanceof Error ? error.message : String(error));
+}
+const paletteNote = values.palette.length > 0 ? `, palettes ${values.palette.join(" ")}` : "";
+const output = `/* @windmorph/react theme "${values.name}" from ${values.seed} (${values.variant}${paletteNote}). */\n\n${css}\n`;
+if (values.out) {
+	await writeFile(values.out, output);
+	process.stderr.write(`Wrote ${values.out}\n`);
+} else process.stdout.write(output);
+//#endregion
+
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { writeFile } from 'node:fs/promises';\nimport { parseArgs } from 'node:util';\nimport { createTheme } from './theme/create-theme';\nimport { parseCustomColors, parsePalettes, toKebabCase } from './theme/parse-palettes';\nimport {\n  CONTRAST_LEVEL_NAMES,\n  PALETTE_NAMES,\n  SCHEME_VARIANTS,\n  type ContrastLevel,\n  type SchemeVariant,\n  type ThemePalettes,\n} from './tokens/color';\n\nconst USAGE = `Usage: npx @windmorph/react theme --seed <hex> --name <name> [options]\n\nGenerates a static CSS colour theme (light, dark and system modes for each\ncontrast level) using the Material 3 2025 colour spec.\n\nOptions:\n  --seed <hex>          Seed colour, e.g. \"#0B57D0\" (required)\n  --name <name>         Theme name for data-theme, lowercase kebab-case (required)\n  --variant <variant>   ${SCHEME_VARIANTS.join(' | ')} (default: tonal-spot)\n  --palette <name>=<source>\n                        Takes one palette from elsewhere; repeatable. <name> is\n                        ${PALETTE_NAMES.map(toKebabCase).join(', ')};\n                        <source> is a variant or a hex colour, e.g.\n                        --palette neutral=tonal-spot --palette tertiary=#00A07A\n  --custom <name>=<hex>  Sets the success or warning colour; repeatable, e.g.\n                        --custom success=#0B8043 --custom warning=#E37400\n  --no-harmonize        Keeps the custom colours' exact hues (by default they turn\n                        toward the seed, as in Material Theme Builder)\n  --contrast <levels>   Comma-separated: ${CONTRAST_LEVEL_NAMES.join(',')} (default: all)\n  --out <file>          Write to a file instead of stdout\n  -h, --help            Show this message\n`;\n\nfunction fail(message: string): never {\n  process.stderr.write(`Error: ${message}\\n\\n${USAGE}`);\n  process.exit(1);\n}\n\nconst { positionals, values } = parseArgs({\n  allowPositionals: true,\n  options: {\n    seed: { type: 'string' },\n    name: { type: 'string' },\n    variant: { type: 'string', default: 'tonal-spot' },\n    palette: { type: 'string', multiple: true, default: [] },\n    custom: { type: 'string', multiple: true, default: [] },\n    'no-harmonize': { type: 'boolean', default: false },\n    contrast: { type: 'string', default: CONTRAST_LEVEL_NAMES.join(',') },\n    out: { type: 'string' },\n    help: { type: 'boolean', short: 'h' },\n  },\n});\n\nif (values.help) {\n  process.stdout.write(USAGE);\n  process.exit(0);\n}\nif (positionals[0] !== 'theme') fail('unknown command. Only \"theme\" is supported.');\nif (!values.seed) fail('--seed is required.');\nif (!values.name) fail('--name is required.');\nif (!(SCHEME_VARIANTS as readonly string[]).includes(values.variant)) {\n  fail(`--variant must be one of ${SCHEME_VARIANTS.join(', ')}.`);\n}\nconst contrast = values.contrast.split(',').map((level) => level.trim());\nfor (const level of contrast) {\n  if (!(CONTRAST_LEVEL_NAMES as readonly string[]).includes(level)) {\n    fail(`unknown contrast level \"${level}\".`);\n  }\n}\n\nlet palettes: ThemePalettes = {};\ntry {\n  palettes = parsePalettes(values.palette);\n} catch (error) {\n  fail(error instanceof Error ? error.message : String(error));\n}\n\nlet customColors = {};\ntry {\n  customColors = parseCustomColors(values.custom);\n} catch (error) {\n  fail(error instanceof Error ? error.message : String(error));\n}\n\nlet css: string;\ntry {\n  css = createTheme({\n    name: values.name,\n    seed: values.seed,\n    variant: values.variant as SchemeVariant,\n    palettes,\n    customColors,\n    harmonize: !values['no-harmonize'],\n    contrast: contrast as ContrastLevel[],\n  }).css;\n} catch (error) {\n  fail(error instanceof Error ? error.message : String(error));\n}\n\nconst paletteNote = values.palette.length > 0 ? `, palettes ${values.palette.join(' ')}` : '';\nconst output = `/* @windmorph/react theme \"${values.name}\" from ${values.seed} (${values.variant}${paletteNote}). */\\n\\n${css}\\n`;\nif (values.out) {\n  await writeFile(values.out, output);\n  process.stderr.write(`Wrote ${values.out}\\n`);\n} else {\n  process.stdout.write(output);\n}\n"],"mappings":";;;;;;;AAcA,MAAM,QAAQ;;;;;;;;0BAQY,gBAAgB,KAAK,KAAK,EAAE;;;0BAG5B,cAAc,IAAI,WAAW,CAAC,CAAC,KAAK,IAAI,EAAE;;;;;;;2CAOzB,qBAAqB,KAAK,GAAG,EAAE;;;;AAK1E,SAAS,KAAK,SAAwB;CACpC,QAAQ,OAAO,MAAM,UAAU,QAAQ,MAAM,OAAO;CACpD,QAAQ,KAAK,CAAC;AAChB;AAEA,MAAM,EAAE,aAAa,WAAW,UAAU;CACxC,kBAAkB;CAClB,SAAS;EACP,MAAM,EAAE,MAAM,SAAS;EACvB,MAAM,EAAE,MAAM,SAAS;EACvB,SAAS;GAAE,MAAM;GAAU,SAAS;EAAa;EACjD,SAAS;GAAE,MAAM;GAAU,UAAU;GAAM,SAAS,CAAC;EAAE;EACvD,QAAQ;GAAE,MAAM;GAAU,UAAU;GAAM,SAAS,CAAC;EAAE;EACtD,gBAAgB;GAAE,MAAM;GAAW,SAAS;EAAM;EAClD,UAAU;GAAE,MAAM;GAAU,SAAS,qBAAqB,KAAK,GAAG;EAAE;EACpE,KAAK,EAAE,MAAM,SAAS;EACtB,MAAM;GAAE,MAAM;GAAW,OAAO;EAAI;CACtC;AACF,CAAC;AAED,IAAI,OAAO,MAAM;CACf,QAAQ,OAAO,MAAM,KAAK;CAC1B,QAAQ,KAAK,CAAC;AAChB;AACA,IAAI,YAAY,OAAO,SAAS,KAAK,+CAA6C;AAClF,IAAI,CAAC,OAAO,MAAM,KAAK,qBAAqB;AAC5C,IAAI,CAAC,OAAO,MAAM,KAAK,qBAAqB;AAC5C,IAAI,CAAE,gBAAsC,SAAS,OAAO,OAAO,GACjE,KAAK,4BAA4B,gBAAgB,KAAK,IAAI,EAAE,EAAE;AAEhE,MAAM,WAAW,OAAO,SAAS,MAAM,GAAG,CAAC,CAAC,KAAK,UAAU,MAAM,KAAK,CAAC;AACvE,KAAK,MAAM,SAAS,UAClB,IAAI,CAAE,qBAA2C,SAAS,KAAK,GAC7D,KAAK,2BAA2B,MAAM,GAAG;AAI7C,IAAI,WAA0B,CAAC;AAC/B,IAAI;CACF,WAAW,cAAc,OAAO,OAAO;AACzC,SAAS,OAAO;CACd,KAAK,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;AAC7D;AAEA,IAAI,eAAe,CAAC;AACpB,IAAI;CACF,eAAe,kBAAkB,OAAO,MAAM;AAChD,SAAS,OAAO;CACd,KAAK,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;AAC7D;AAEA,IAAI;AACJ,IAAI;CACF,MAAM,YAAY;EAChB,MAAM,OAAO;EACb,MAAM,OAAO;EACb,SAAS,OAAO;EAChB;EACA;EACA,WAAW,CAAC,OAAO;EACT;CACZ,CAAC,CAAC,CAAC;AACL,SAAS,OAAO;CACd,KAAK,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;AAC7D;AAEA,MAAM,cAAc,OAAO,QAAQ,SAAS,IAAI,cAAc,OAAO,QAAQ,KAAK,GAAG,MAAM;AAC3F,MAAM,SAAS,8BAA8B,OAAO,KAAK,SAAS,OAAO,KAAK,IAAI,OAAO,UAAU,YAAY,WAAW,IAAI;AAC9H,IAAI,OAAO,KAAK;CACd,MAAM,UAAU,OAAO,KAAK,MAAM;CAClC,QAAQ,OAAO,MAAM,SAAS,OAAO,IAAI,GAAG;AAC9C,OACE,QAAQ,OAAO,MAAM,MAAM"}

package/dist/components/app-bar/AppBarItems.js

@@ -0,0 +1,23 @@
+"use client";
+import { ButtonContext, standardIconButtons } from "../button/ButtonContext.js";
+import { TooltipPlacementContext } from "../tooltip/tooltip-placement.js";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/app-bar/AppBarItems.tsx
+/**
+* What an app bar gives the controls inside it: `standard` icon buttons, and plain tooltips
+* below (the spec: "If the element is in an app bar, the plain tooltip appears below the
+* element"). Shared by `TopAppBar` and `SearchAppBar`.
+*/
+function AppBarItems({ children }) {
+	return /* @__PURE__ */ jsx(TooltipPlacementContext, {
+		value: "bottom",
+		children: /* @__PURE__ */ jsx(ButtonContext, {
+			value: standardIconButtons,
+			children
+		})
+	});
+}
+//#endregion
+export { AppBarItems };
+
+//# sourceMappingURL=AppBarItems.js.map

package/dist/components/app-bar/AppBarItems.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppBarItems.js","names":[],"sources":["../../../src/components/app-bar/AppBarItems.tsx"],"sourcesContent":["'use client';\n\nimport type { ReactNode } from 'react';\nimport { ButtonContext, standardIconButtons } from '../button/ButtonContext';\nimport { TooltipPlacementContext } from '../tooltip/tooltip-placement';\n\n/**\n * What an app bar gives the controls inside it: `standard` icon buttons, and plain tooltips\n * below (the spec: \"If the element is in an app bar, the plain tooltip appears below the\n * element\"). Shared by `TopAppBar` and `SearchAppBar`.\n */\nexport function AppBarItems({ children }: { children: ReactNode }) {\n  return (\n    <TooltipPlacementContext value=\"bottom\">\n      <ButtonContext value={standardIconButtons}>{children}</ButtonContext>\n    </TooltipPlacementContext>\n  );\n}\n"],"mappings":";;;;;;;;;;AAWA,SAAgB,YAAY,EAAE,YAAqC;CACjE,OACE,oBAAC,yBAAD;EAAyB,OAAM;EAC7B,UAAA,oBAAC,eAAD;GAAe,OAAO;GAAsB;EAAwB,CAAA;CAC7C,CAAA;AAE7B"}

package/dist/components/app-bar/TopAppBar.d.ts

@@ -0,0 +1,89 @@
+import { TopAppBarTitleAlign, TopAppBarVariant } from "./app-bar-styles.js";
+import { TopAppBarScrollBehavior } from "./use-app-bar-scroll.js";
+import { ComponentPropsWithRef, ReactNode, RefObject } from "react";
+//#region src/components/app-bar/TopAppBar.d.ts
+export interface TopAppBarClassNames {
+  /** The `<header>` container, merged with `className`. */
+  root?: string;
+  /** The 64px top row. */
+  row?: string;
+  /** The leading slot holding `navigationIcon`. */
+  navigation?: string;
+  /** The top row's title block. */
+  title?: string;
+  /** The top row's title text. */
+  titleText?: string;
+  /** The top row's subtitle text. */
+  subtitleText?: string;
+  /** The trailing slot holding `actions`. */
+  actions?: string;
+  /** The expanded title row of medium and large bars. */
+  expandedRow?: string;
+  /** The expanded row's title text. */
+  expandedTitle?: string;
+  /** The expanded row's subtitle text. */
+  expandedSubtitle?: string;
+  /** The accessory row below the title rows (`bottom`). */
+  bottom?: string;
+}
+interface TopAppBarOwnProps {
+  /**
+   * `small` is a 64px single row; `medium` and `large` are Compose's flexible two-row bars
+   * (112 / 120px, 136 / 152px with a subtitle) that collapse to 64px. @default "small"
+   */
+  variant?: TopAppBarVariant;
+  /** The title, e.g. the screen's name. Wrap it in a heading element if it names the page. */
+  title: ReactNode;
+  /** A second line under the title, e.g. the current section. */
+  subtitle?: ReactNode;
+  /** Align the title (and subtitle) to the start, or centre it. @default "start" */
+  titleAlign?: TopAppBarTitleAlign;
+  /** A leading control, usually a back or menu `IconButton`. */
+  navigationIcon?: ReactNode;
+  /** Trailing controls, usually `IconButton`s. */
+  actions?: ReactNode;
+  /**
+   * Respond to content scrolling under the bar: it sticks to the top, turns
+   * `surface-container`, and (for `enter-always` / `exit-until-collapsed`) collapses.
+   * Leave it out for a static bar positioned by the consumer.
+   */
+  scrollBehavior?: TopAppBarScrollBehavior;
+  /** The scroll container the bar responds to. Defaults to the window. */
+  scrollRef?: RefObject<HTMLElement | null>;
+  /**
+   * An accessory row below the title rows, such as a row of filter chips or tabs (M3: app
+   * bars "can animate on and off screen with another bar of controls, like a row of chips").
+   * It's part of the bar: it takes the bar's colour, stays below the collapsed top row of
+   * a medium or large bar, and hides and comes back with the bar under `enter-always` and
+   * a small bar's `exit-until-collapsed`. Give it its own padding.
+   */
+  bottom?: ReactNode;
+  /**
+   * The container's colour once content scrolls under the bar. `container` fills it with
+   * `surface-container` (M3's default); `transparent` lets the content show through (M3:
+   * "consider setting the app bar container to be transparent on scroll"); give the icon
+   * buttons a container fill then (e.g. `variant="tonal"`), so they stay legible over the
+   * content.
+   * @default "container"
+   */
+  scrolledColor?: TopAppBarScrolledColor;
+  /** Classes for each part, by slot. */
+  classNames?: TopAppBarClassNames;
+}
+/** The colour a {@link TopAppBar} takes when content scrolls under it. */
+export type TopAppBarScrolledColor = 'container' | 'transparent';
+export type TopAppBarProps = TopAppBarOwnProps & Omit<ComponentPropsWithRef<'header'>, keyof TopAppBarOwnProps | 'children'>;
+/**
+ * M3 Expressive top app bar: a small 64px bar, or the medium and large flexible bars whose
+ * large title collapses into the top row as the page scrolls. Titles can be centred and
+ * have a subtitle.
+ *
+ * @example
+ * <TopAppBar title={<h1>Inbox</h1>} subtitle="3 unread" variant="medium"
+ *   scrollBehavior="exit-until-collapsed"
+ *   navigationIcon={<IconButton icon={<MenuIcon />} aria-label="Menu" />}
+ *   actions={<IconButton icon={<SearchIcon />} aria-label="Search" />} />
+ */
+export declare function TopAppBar({ variant, title, subtitle, titleAlign, navigationIcon, actions, scrollBehavior, scrollRef, bottom, scrolledColor, classNames, className, ref, ...rest }: TopAppBarProps): import("react").JSX.Element;
+//#endregion
+//# sourceMappingURL=TopAppBar.d.ts.map

package/dist/components/app-bar/TopAppBar.js

@@ -0,0 +1,103 @@
+"use client";
+import { cn } from "../../utils/cn.js";
+import { mergeDataTokens } from "../../utils/merge-data-tokens.js";
+import { AppBarItems } from "./AppBarItems.js";
+import { topAppBarStyles } from "./app-bar-styles.js";
+import { useAppBarScroll } from "./use-app-bar-scroll.js";
+import { useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useObjectRef } from "react-aria";
+//#region src/components/app-bar/TopAppBar.tsx
+/**
+* M3 Expressive top app bar: a small 64px bar, or the medium and large flexible bars whose
+* large title collapses into the top row as the page scrolls. Titles can be centred and
+* have a subtitle.
+*
+* @example
+* <TopAppBar title={<h1>Inbox</h1>} subtitle="3 unread" variant="medium"
+*   scrollBehavior="exit-until-collapsed"
+*   navigationIcon={<IconButton icon={<MenuIcon />} aria-label="Menu" />}
+*   actions={<IconButton icon={<SearchIcon />} aria-label="Search" />} />
+*/
+function TopAppBar({ variant = "small", title, subtitle, titleAlign = "start", navigationIcon, actions, scrollBehavior, scrollRef, bottom, scrolledColor = "container", classNames, className, ref, ...rest }) {
+	const rootRef = useObjectRef(ref);
+	const expandedRowRef = useRef(null);
+	const twoRows = variant !== "small";
+	const scroll = useAppBarScroll({
+		behavior: scrollBehavior,
+		rootRef,
+		collapsibleRef: twoRows ? expandedRowRef : rootRef,
+		scrollRef,
+		twoRows
+	});
+	const styles = topAppBarStyles({
+		variant,
+		titleAlign,
+		hasNavigation: navigationIcon != null,
+		hasSubtitle: subtitle != null,
+		scrolling: scrollBehavior != null,
+		pinned: scrollBehavior === "pinned",
+		twoRows,
+		scrolledColor
+	});
+	const hideTopTitle = twoRows && !scroll.collapsed;
+	return /* @__PURE__ */ jsx("header", {
+		...rest,
+		ref: rootRef,
+		"data-tokens": mergeDataTokens("md-comp-app-bar", rest),
+		"data-variant": variant,
+		"data-scrolled": scroll.scrolled || void 0,
+		"data-collapsed": scroll.collapsed || void 0,
+		className: styles.root({ class: cn(classNames?.root, className) }),
+		children: /* @__PURE__ */ jsxs(AppBarItems, { children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: styles.row({ class: classNames?.row }),
+				children: [
+					navigationIcon != null && /* @__PURE__ */ jsx("div", {
+						"data-slot": "navigation",
+						className: styles.navigation({ class: classNames?.navigation }),
+						children: navigationIcon
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						"aria-hidden": hideTopTitle || void 0,
+						className: styles.title({ class: classNames?.title }),
+						children: [/* @__PURE__ */ jsx("div", {
+							"data-slot": "title",
+							className: styles.titleText({ class: classNames?.titleText }),
+							children: title
+						}), subtitle != null && /* @__PURE__ */ jsx("div", {
+							"data-slot": "subtitle",
+							className: styles.subtitleText({ class: classNames?.subtitleText }),
+							children: subtitle
+						})]
+					}),
+					actions != null && /* @__PURE__ */ jsx("div", {
+						"data-slot": "actions",
+						className: styles.actions({ class: classNames?.actions }),
+						children: actions
+					})
+				]
+			}),
+			twoRows && /* @__PURE__ */ jsxs("div", {
+				ref: expandedRowRef,
+				"aria-hidden": !hideTopTitle || void 0,
+				className: styles.expandedRow({ class: classNames?.expandedRow }),
+				children: [/* @__PURE__ */ jsx("div", {
+					className: styles.expandedTitle({ class: classNames?.expandedTitle }),
+					children: title
+				}), subtitle != null && /* @__PURE__ */ jsx("div", {
+					className: styles.expandedSubtitle({ class: classNames?.expandedSubtitle }),
+					children: subtitle
+				})]
+			}),
+			bottom != null && /* @__PURE__ */ jsx("div", {
+				className: styles.bottom({ class: classNames?.bottom }),
+				children: bottom
+			})
+		] })
+	});
+}
+//#endregion
+export { TopAppBar };
+
+//# sourceMappingURL=TopAppBar.js.map

package/dist/components/app-bar/TopAppBar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopAppBar.js","names":[],"sources":["../../../src/components/app-bar/TopAppBar.tsx"],"sourcesContent":["'use client';\n\nimport { useRef, type ComponentPropsWithRef, type ReactNode, type RefObject } from 'react';\nimport { useObjectRef } from 'react-aria';\nimport { cn } from '../../utils/cn';\nimport { AppBarItems } from './AppBarItems';\nimport { topAppBarStyles, type TopAppBarTitleAlign, type TopAppBarVariant } from './app-bar-styles';\nimport { useAppBarScroll, type TopAppBarScrollBehavior } from './use-app-bar-scroll';\nimport { mergeDataTokens } from '../../utils/merge-data-tokens';\n\nexport interface TopAppBarClassNames {\n  /** The `<header>` container, merged with `className`. */\n  root?: string;\n  /** The 64px top row. */\n  row?: string;\n  /** The leading slot holding `navigationIcon`. */\n  navigation?: string;\n  /** The top row's title block. */\n  title?: string;\n  /** The top row's title text. */\n  titleText?: string;\n  /** The top row's subtitle text. */\n  subtitleText?: string;\n  /** The trailing slot holding `actions`. */\n  actions?: string;\n  /** The expanded title row of medium and large bars. */\n  expandedRow?: string;\n  /** The expanded row's title text. */\n  expandedTitle?: string;\n  /** The expanded row's subtitle text. */\n  expandedSubtitle?: string;\n  /** The accessory row below the title rows (`bottom`). */\n  bottom?: string;\n}\n\ninterface TopAppBarOwnProps {\n  /**\n   * `small` is a 64px single row; `medium` and `large` are Compose's flexible two-row bars\n   * (112 / 120px, 136 / 152px with a subtitle) that collapse to 64px. @default \"small\"\n   */\n  variant?: TopAppBarVariant;\n  /** The title, e.g. the screen's name. Wrap it in a heading element if it names the page. */\n  title: ReactNode;\n  /** A second line under the title, e.g. the current section. */\n  subtitle?: ReactNode;\n  /** Align the title (and subtitle) to the start, or centre it. @default \"start\" */\n  titleAlign?: TopAppBarTitleAlign;\n  /** A leading control, usually a back or menu `IconButton`. */\n  navigationIcon?: ReactNode;\n  /** Trailing controls, usually `IconButton`s. */\n  actions?: ReactNode;\n  /**\n   * Respond to content scrolling under the bar: it sticks to the top, turns\n   * `surface-container`, and (for `enter-always` / `exit-until-collapsed`) collapses.\n   * Leave it out for a static bar positioned by the consumer.\n   */\n  scrollBehavior?: TopAppBarScrollBehavior;\n  /** The scroll container the bar responds to. Defaults to the window. */\n  scrollRef?: RefObject<HTMLElement | null>;\n  /**\n   * An accessory row below the title rows, such as a row of filter chips or tabs (M3: app\n   * bars \"can animate on and off screen with another bar of controls, like a row of chips\").\n   * It's part of the bar: it takes the bar's colour, stays below the collapsed top row of\n   * a medium or large bar, and hides and comes back with the bar under `enter-always` and\n   * a small bar's `exit-until-collapsed`. Give it its own padding.\n   */\n  bottom?: ReactNode;\n  /**\n   * The container's colour once content scrolls under the bar. `container` fills it with\n   * `surface-container` (M3's default); `transparent` lets the content show through (M3:\n   * \"consider setting the app bar container to be transparent on scroll\"); give the icon\n   * buttons a container fill then (e.g. `variant=\"tonal\"`), so they stay legible over the\n   * content.\n   * @default \"container\"\n   */\n  scrolledColor?: TopAppBarScrolledColor;\n  /** Classes for each part, by slot. */\n  classNames?: TopAppBarClassNames;\n}\n\n/** The colour a {@link TopAppBar} takes when content scrolls under it. */\nexport type TopAppBarScrolledColor = 'container' | 'transparent';\n\nexport type TopAppBarProps = TopAppBarOwnProps &\n  Omit<ComponentPropsWithRef<'header'>, keyof TopAppBarOwnProps | 'children'>;\n\n/**\n * M3 Expressive top app bar: a small 64px bar, or the medium and large flexible bars whose\n * large title collapses into the top row as the page scrolls. Titles can be centred and\n * have a subtitle.\n *\n * @example\n * <TopAppBar title={<h1>Inbox</h1>} subtitle=\"3 unread\" variant=\"medium\"\n *   scrollBehavior=\"exit-until-collapsed\"\n *   navigationIcon={<IconButton icon={<MenuIcon />} aria-label=\"Menu\" />}\n *   actions={<IconButton icon={<SearchIcon />} aria-label=\"Search\" />} />\n */\nexport function TopAppBar({\n  variant = 'small',\n  title,\n  subtitle,\n  titleAlign = 'start',\n  navigationIcon,\n  actions,\n  scrollBehavior,\n  scrollRef,\n  bottom,\n  scrolledColor = 'container',\n  classNames,\n  className,\n  ref,\n  ...rest\n}: TopAppBarProps) {\n  const rootRef = useObjectRef(ref);\n  const expandedRowRef = useRef<HTMLDivElement>(null);\n  const twoRows = variant !== 'small';\n  const scroll = useAppBarScroll({\n    behavior: scrollBehavior,\n    rootRef,\n    collapsibleRef: twoRows ? expandedRowRef : rootRef,\n    scrollRef,\n    twoRows,\n  });\n  const styles = topAppBarStyles({\n    variant,\n    titleAlign,\n    hasNavigation: navigationIcon != null,\n    hasSubtitle: subtitle != null,\n    scrolling: scrollBehavior != null,\n    pinned: scrollBehavior === 'pinned',\n    twoRows,\n    scrolledColor,\n  });\n  // Only one of a two-row bar's titles is announced: the expanded one until it is half collapsed.\n  const hideTopTitle = twoRows && !scroll.collapsed;\n\n  return (\n    <header\n      {...rest}\n      ref={rootRef}\n      data-tokens={mergeDataTokens('md-comp-app-bar', rest)}\n      data-variant={variant}\n      data-scrolled={scroll.scrolled || undefined}\n      data-collapsed={scroll.collapsed || undefined}\n      className={styles.root({ class: cn(classNames?.root, className) })}\n    >\n      <AppBarItems>\n        <div className={styles.row({ class: classNames?.row })}>\n          {navigationIcon != null && (\n            <div\n              data-slot=\"navigation\"\n              className={styles.navigation({ class: classNames?.navigation })}\n            >\n              {navigationIcon}\n            </div>\n          )}\n          <div\n            aria-hidden={hideTopTitle || undefined}\n            className={styles.title({ class: classNames?.title })}\n          >\n            <div data-slot=\"title\" className={styles.titleText({ class: classNames?.titleText })}>\n              {title}\n            </div>\n            {subtitle != null && (\n              <div\n                data-slot=\"subtitle\"\n                className={styles.subtitleText({ class: classNames?.subtitleText })}\n              >\n                {subtitle}\n              </div>\n            )}\n          </div>\n          {actions != null && (\n            <div data-slot=\"actions\" className={styles.actions({ class: classNames?.actions })}>\n              {actions}\n            </div>\n          )}\n        </div>\n        {twoRows && (\n          <div\n            ref={expandedRowRef}\n            aria-hidden={!hideTopTitle || undefined}\n            className={styles.expandedRow({ class: classNames?.expandedRow })}\n          >\n            <div className={styles.expandedTitle({ class: classNames?.expandedTitle })}>\n              {title}\n            </div>\n            {subtitle != null && (\n              <div className={styles.expandedSubtitle({ class: classNames?.expandedSubtitle })}>\n                {subtitle}\n              </div>\n            )}\n          </div>\n        )}\n        {bottom != null && (\n          <div className={styles.bottom({ class: classNames?.bottom })}>{bottom}</div>\n        )}\n      </AppBarItems>\n    </header>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAiGA,SAAgB,UAAU,EACxB,UAAU,SACV,OACA,UACA,aAAa,SACb,gBACA,SACA,gBACA,WACA,QACA,gBAAgB,aAChB,YACA,WACA,KACA,GAAG,QACc;CACjB,MAAM,UAAU,aAAa,GAAG;CAChC,MAAM,iBAAiB,OAAuB,IAAI;CAClD,MAAM,UAAU,YAAY;CAC5B,MAAM,SAAS,gBAAgB;EAC7B,UAAU;EACV;EACA,gBAAgB,UAAU,iBAAiB;EAC3C;EACA;CACF,CAAC;CACD,MAAM,SAAS,gBAAgB;EAC7B;EACA;EACA,eAAe,kBAAkB;EACjC,aAAa,YAAY;EACzB,WAAW,kBAAkB;EAC7B,QAAQ,mBAAmB;EAC3B;EACA;CACF,CAAC;CAED,MAAM,eAAe,WAAW,CAAC,OAAO;CAExC,OACE,oBAAC,UAAD;EACE,GAAI;EACJ,KAAK;EACL,eAAa,gBAAgB,mBAAmB,IAAI;EACpD,gBAAc;EACd,iBAAe,OAAO,YAAY,KAAA;EAClC,kBAAgB,OAAO,aAAa,KAAA;EACpC,WAAW,OAAO,KAAK,EAAE,OAAO,GAAG,YAAY,MAAM,SAAS,EAAE,CAAC;EAEjE,UAAA,qBAAC,aAAD,EAAA,UAAA;GACE,qBAAC,OAAD;IAAK,WAAW,OAAO,IAAI,EAAE,OAAO,YAAY,IAAI,CAAC;IAArD,UAAA;KACG,kBAAkB,QACjB,oBAAC,OAAD;MACE,aAAU;MACV,WAAW,OAAO,WAAW,EAAE,OAAO,YAAY,WAAW,CAAC;MAE7D,UAAA;KACE,CAAA;KAEP,qBAAC,OAAD;MACE,eAAa,gBAAgB,KAAA;MAC7B,WAAW,OAAO,MAAM,EAAE,OAAO,YAAY,MAAM,CAAC;MAFtD,UAAA,CAIE,oBAAC,OAAD;OAAK,aAAU;OAAQ,WAAW,OAAO,UAAU,EAAE,OAAO,YAAY,UAAU,CAAC;OAChF,UAAA;MACE,CAAA,GACJ,YAAY,QACX,oBAAC,OAAD;OACE,aAAU;OACV,WAAW,OAAO,aAAa,EAAE,OAAO,YAAY,aAAa,CAAC;OAEjE,UAAA;MACE,CAAA,CAEJ;;KACJ,WAAW,QACV,oBAAC,OAAD;MAAK,aAAU;MAAU,WAAW,OAAO,QAAQ,EAAE,OAAO,YAAY,QAAQ,CAAC;MAC9E,UAAA;KACE,CAAA;IAEJ;;GACJ,WACC,qBAAC,OAAD;IACE,KAAK;IACL,eAAa,CAAC,gBAAgB,KAAA;IAC9B,WAAW,OAAO,YAAY,EAAE,OAAO,YAAY,YAAY,CAAC;IAHlE,UAAA,CAKE,oBAAC,OAAD;KAAK,WAAW,OAAO,cAAc,EAAE,OAAO,YAAY,cAAc,CAAC;KACtE,UAAA;IACE,CAAA,GACJ,YAAY,QACX,oBAAC,OAAD;KAAK,WAAW,OAAO,iBAAiB,EAAE,OAAO,YAAY,iBAAiB,CAAC;KAC5E,UAAA;IACE,CAAA,CAEJ;;GAEN,UAAU,QACT,oBAAC,OAAD;IAAK,WAAW,OAAO,OAAO,EAAE,OAAO,YAAY,OAAO,CAAC;IAAI,UAAA;GAAY,CAAA;EAElE,EAAA,CAAA;CACP,CAAA;AAEZ"}