@yelison/forma-ui 0.0.1-bootstrap.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @yelison/forma-ui
+
+## 0.1.0
+
+### Minor Changes
+
+- d76f066: Publish the color pairs the package keeps readable, with their WCAG thresholds, as `@yelison/forma-ui/contrast-pairs.json`, so that a consumer can measure them against `tokens.json`.
+- 35bef50: `Field` and `Input` take an `announce` prop: `'off'` shows the error without announcing it (for specimens and documentation, never for a form people fill in), and the default `'assertive'` keeps the `role="alert"` it always had.
+- e06c795: First release of Forma UI: accessible React components and semantic design tokens, extracted from Resolve.
+
+  - **Components:** `Button`, `IconButton`, `Badge`, `Field`, `Input`, `Icon`, `Tooltip` and `Dialog` (also exported as `Modal`), with their props types.
+  - **Tokens:** the design tokens as CSS custom properties for the light, dark and system themes (`@yelison/forma-ui/tokens.css`), the resolved values (`tokens.json`), the `tokenNames` list and the `contrastRatio` helper.
+  - **Theme:** `createThemeStore`, `useTheme` and `themeScript` to own the light, dark or system preference and avoid a flash on first paint.
+  - **`FormaProvider`:** replaces the few strings the components show on their own, which default to English.
+  - **Distribution:** ES modules with declarations, three stylesheets (`tokens.css`, `styles.css`, `base.css`) and `react` and `react-dom` (`^19.2`) as peer dependencies.
+
+### Patch Changes
+
+- ce8e511: Publish the library as one module per source file, so that a bundler keeps in each chunk only the components it uses. The public API, the stylesheets and their import paths do not change.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yelison Ortiz
+
+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/README.md

@@ -0,0 +1,244 @@
+# @yelison/forma-ui
+
+Accessible React components and semantic design tokens, extracted from [Resolve](https://github.com/Yelison/resolve).
+Light, dark and system themes, English text by default that you can replace, and native HTML semantics first.
+
+## Install
+
+```sh
+npm install @yelison/forma-ui react react-dom
+```
+
+React and React DOM are peer dependencies (`^19.2`): the package never bundles its own copy.
+
+## Quick start
+
+Import the three stylesheets once, in the entry point of your application, then use the components:
+
+```tsx
+import '@yelison/forma-ui/tokens.css'
+import '@yelison/forma-ui/styles.css'
+import '@yelison/forma-ui/base.css'
+// then your own CSS
+
+import { Button, FormaProvider } from '@yelison/forma-ui'
+
+export function App() {
+  return (
+    <FormaProvider>
+      <Button variant="primary">Save</Button>
+    </FormaProvider>
+  )
+}
+```
+
+## The CSS you import
+
+The package ships its CSS as three files, in this order:
+
+| Import                         | What it holds                                                                               |
+| ------------------------------ | ------------------------------------------------------------------------------------------- |
+| `@yelison/forma-ui/tokens.css` | The design tokens as CSS custom properties, for the light, dark and system themes.          |
+| `@yelison/forma-ui/styles.css` | The rules of every component, in one file.                                                  |
+| `@yelison/forma-ui/base.css`   | Two utility classes, `.forma-visually-hidden` and `.forma-scroll-locked`, and nothing else. |
+
+- The package's files go before your own CSS. A `className` you pass to a component has the same specificity as the
+  component's own rule (for example `.forma-badge__blue`), so the later stylesheet wins: yours has to come after
+  `styles.css`.
+- `tokens.css` is the foundation: the component rules read its custom properties, and without it they render unstyled.
+- Importing `@yelison/forma-ui` pulls in no CSS and has no side effects: the components are tree-shakeable (see
+  [Bundle size](#bundle-size)), and the stylesheet is yours to place. `styles.css` is one file for all the components, whether you use them all or not.
+- `base.css` holds only plain `.forma-*` class selectors, so nothing in it can match your own markup. A modal dialog
+  applies `.forma-scroll-locked` to `<html>` while it is open: import `base.css` unless you use no such component.
+- A consumer without React, such as an identity provider's login theme, imports `tokens.css` alone.
+- `tokens.json` (`@yelison/forma-ui/tokens.json`) holds the resolved token values, and `tokenNames` lists the custom
+  properties.
+- `contrast-pairs.json` (`@yelison/forma-ui/contrast-pairs.json`) lists the color pairs the package keeps readable: for
+  each one, the foreground and background tokens (without the `--color-` prefix), the kind of use (`text`, held to 4.5:1,
+  or `nonText`, held to 3:1) and the themes it is painted in, with the two thresholds. To check your own theme
+  overrides, measure each pair with `contrastRatio` over your values, taking from `tokens.json` the tokens you do not
+  override.
+
+The component classes are named `forma-<module>__<class>` and are not a styling API: restyle through the tokens, and
+pass your own `className` to a component.
+
+## `FormaProvider` and the library's text
+
+The few strings the components show on their own have English defaults. A `FormaProvider` replaces them for the part of
+the application it wraps; entries you leave out keep the value of the closest provider above, or the default.
+
+| Key             | Default    | Where it appears                                                                  |
+| --------------- | ---------- | --------------------------------------------------------------------------------- |
+| `buttonLoading` | `Loading…` | The accessible name of a `Button` while it is `loading`.                          |
+| `dialogClose`   | `Close`    | Returned by `useFormaStrings()`, for a close button you put in a `Dialog` footer. |
+
+```tsx
+<FormaProvider strings={{ buttonLoading: 'Enviando…', dialogClose: 'Cerrar' }}>
+  <App />
+</FormaProvider>
+```
+
+A prop on a component wins over the provider (`<Button loading loadingLabel="Saving…">`), and the provider wins over the
+default. The provider is optional for an application in English. Read the current strings in your own components with
+`useFormaStrings()`.
+
+## Theme
+
+`tokens.css` paints the light theme, follows `prefers-color-scheme` until a theme is chosen, and switches by the
+`data-theme` attribute on `<html>`: `light` or `dark` set it, and `system` removes it. The package gives you the pieces
+to own that choice:
+
+- `createThemeStore({ storageKey })` creates the store of one application: the preference (`light`, `dark` or
+  `system`), kept in `localStorage` under your key and in memory when storage is unavailable. Creating it does not touch
+  the page.
+- `useTheme(store)` reads it in a component and returns `preference`, `resolved`, `setPreference` and `toggle`.
+- `themeScript({ storageKey })` returns a string for an inline `<script>` in `<head>`, so that a reload does not flash
+  the theme the operating system prefers before React renders. It must use the same key as the store, and it must be in
+  the HTML that is served: a script that React renders does not run.
+
+```tsx
+import { createThemeStore, themeScript, useTheme } from '@yelison/forma-ui'
+
+const themeStore = createThemeStore({ storageKey: 'my-app-theme' })
+
+// In the HTML your server or build sends, in <head>:
+const firstPaint = `<script>${themeScript({ storageKey: 'my-app-theme' })}</script>`
+
+function ThemeToggle() {
+  const { resolved, toggle } = useTheme(themeStore)
+  return <button onClick={toggle}>{resolved === 'dark' ? 'Light theme' : 'Dark theme'}</button>
+}
+```
+
+## Components
+
+`Badge`, `Button`, `IconButton`, `Icon` and `Input` forward the attributes of their native element. `Field`, `Tooltip` and `Dialog` take only the props they document.
+
+| Component               | Use it for                                              | Accessibility                                                                                                                                                            |
+| ----------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Button`                | An action; `primary`, `secondary`, `ghost` or `danger`. | A native `button` whose `type` is `button` unless set. While `loading` it stays focusable with `aria-busy` and `aria-disabled`; `disabled` is for an unavailable action. |
+| `IconButton`            | An action with an icon and no visible text.             | `label` is required and becomes `aria-label`; show it in a `Tooltip` too.                                                                                                |
+| `Badge`                 | A short status or category tag, in five tones.          | The tone only colors it: the text has to say the same thing.                                                                                                             |
+| `Field`                 | A label, hint and error around a control you provide.   | Links them with `id` and `aria-describedby`, sets `aria-invalid` and announces the error with `role="alert"`; `announce="off"` shows it without announcing it.           |
+| `Input`                 | A native text input with its `Field`.                   | Same linking as `Field`, and it forwards `announce` to it; `disabled` and `readOnly` stay different states.                                                              |
+| `Icon`                  | One of the library's icons, as inline SVG.              | Decorative and hidden from screen readers unless you give it a `label`.                                                                                                  |
+| `Tooltip`               | A short description for a control.                      | Opens on hover and on keyboard focus, stays open while the pointer travels onto it, `Escape` closes it, and it describes the trigger with `aria-describedby`.            |
+| `Dialog` (also `Modal`) | A modal on the native `<dialog>`.                       | Opened with `showModal()`: focus stays inside and the page behind is inert. `Escape` and a backdrop click call `onClose`, and focus returns to the opener.               |
+
+Also exported: `buttonClassName` (the classes of a button, for a link that must look like one), `useScrollLock` (the
+scroll lock of the dialog, for an overlay of your own), `useFormaStrings` and `defaultStrings` (the text the components show
+on their own), `contrastRatio` and `relativeLuminance` (WCAG contrast, over `#rgb` and `#rrggbb` colors) and every props
+type next to its component.
+
+## Bundle size
+
+The package is published as one ES module per source file (`dist/components/Badge/Badge.js`), and `dist/index.js` only
+re-exports them. Your bundler keeps what you import, chunk by chunk: a dialog that loads on demand brings its own code
+with it, and the entry chunk of your application does not carry the code of components it never shows on the first
+screen.
+
+- **`sideEffects`:** `package.json` declares `"sideEffects": ["*.css"]`. The JavaScript has no effect at import time, so
+  a bundler may drop any module you do not use; the three stylesheets are the only files it must keep, because importing
+  one is all they are for.
+- **Styles:** unchanged. Importing the package still pulls in no CSS: `styles.css` is built beside the modules as one
+  file for every component, and you import it yourself, once, as shown in [The CSS you import](#the-css-you-import).
+- **Imports:** from the package, `import { Dialog } from '@yelison/forma-ui'`. `exports` is the only way in, so the
+  layout of `dist/` can change without breaking you, and there are no per-component subpaths: a bundler that tree-shakes
+  already gets the same result from the package root, and each subpath would be a public name to keep.
+
+`npm run pack:check` prints the current sizes, minified and gzipped, and fails when one grows past its budget; its output
+is the source of truth. At the time of writing they are:
+
+| What you import | Size    |
+| --------------- | ------- |
+| Everything      | 6.76 kB |
+| `{ Button }`    | 2.91 kB |
+| `{ Badge }`     | 0.23 kB |
+| `styles.css`    | 1.47 kB |
+
+`Button` is not small because `Icon` looks its path up in one object that holds every icon, so the whole table travels
+with any component that draws an icon.
+
+## Compatibility
+
+- **React:** 19.2 or a later 19.x release (`^19.2`), with `react-dom`.
+- **Module format:** ES modules only. `import` it; `require()` of the entry point works too, on the Node versions the
+  package supports (22.12 or later), which load an ES module from CommonJS.
+- **TypeScript:** declarations are included. Use `moduleResolution` `bundler`, `node16` or `nodenext`. `node10`
+  resolves the entry point and its types through `main` and `types`, but it ignores `exports`, so it cannot resolve the
+  CSS and JSON subpaths: import those through your bundler.
+- **Node:** 22.12 or later (`engines`), for server rendering and tooling: it is what the package is tested on.
+- **Browsers:** `Dialog` uses the native `<dialog>` element and `showModal()`.
+
+## How the package is verified
+
+The repository's CI checks the packed tarball, as a consumer receives it, not the sources.
+
+`npm run check:consumer` packs the package, installs it into a throwaway project, compiles that project with
+`moduleResolution: nodenext` and runs it. It fails if a CSS export does not resolve, if a module of `dist/` imports CSS, if a
+class in `styles.css` lacks the `forma-` prefix, if a rendered component carries a class with no rule or if a CSS
+module has no class rendered at all. The build lists the classes of every module in `dist/css-modules.json`, which is
+not packed. A component that ships CSS is added to `scripts/consumer/main.tsx`.
+
+`npm run pack:check` fails with a message that names the file or the rule:
+
+- **Contents:** only `dist/**` (without `dist/css-modules.json`), `package.json`, `README.md`, `LICENSE` and, once it
+  exists, `CHANGELOG.md`; everything `main`, `types` and `exports` point at is in it; `react` and `react-dom` are peer
+  dependencies, never dependencies; `LICENSE` is the repository's. The list of `dist/` is closed by a rule, not by
+  hand: every module is imported from the entry point, every import resolves to a packed file, and the only other files
+  are the stylesheets, `tokens.json` and `contrast-pairs.json`. An orphan module, a test, a source map or a missing
+  import fails.
+- **Types and exports:** [publint](https://publint.dev) in strict mode and
+  [Are The Types Wrong?](https://arethetypeswrong.github.io) read the packed `package.json` and resolve the typed
+  entry point in `node10`, `node16` (CommonJS and ESM) and `bundler`; the consumer is compiled under `bundler`; and
+  `require()` of the entry point must load on Node 22.12+.
+- **One copy of React:** no packed module imports anything but `react`, `react-dom` and its own modules or holds React code, and
+  the production bundle of a Vite consumer (`scripts/consumer/client.tsx`) resolves `react`, `react-dom` and
+  `scheduler` to one folder each. React inlined into the library cannot be seen from the module graph alone, so the
+  first half reads every file.
+- **Side effects:** `sideEffects` is a list of patterns that covers every stylesheet in `exports` and no JavaScript.
+  The promise behind it is checked too: with the field taken out of a copy of the packed `package.json`, so that the
+  bundler has to read every module to know whether it does anything, a bare `import '@yelison/forma-ui'` in a Vite
+  consumer (React left external, as in an application) renders no code of the package. A module that sets an attribute
+  or a global when it is imported fails there, naming the file. The three stylesheets each emit their CSS when imported.
+- **Lazy chunks:** an application that uses `Button` and loads `Dialog` on demand has no `Dialog` code in its entry chunk,
+  and the chunk loaded on demand has it. A package that reached the bundler as one module fails this, because the entry
+  chunk would carry everything the other chunks use. The entry chunk has a weight budget too
+  (`scripts/pack-check/lazy-chunk.ts`).
+- **Size budget:** what a Vite consumer's bundler makes of the tarball, bundled as an application, minified and
+  gzipped (level 9), with React left out: every export, `import { Button }` alone, `import { Badge }` alone (the
+  smallest component, with no icon, so that what `Button` carries cannot hide a regression in it) and
+  `dist/styles.css`. Each budget is the size measured plus about 20% and lives in
+  `scripts/pack-check/size-budget.ts`; the message names the budget, the size and the excess.
+
+## Versions and publishing
+
+The package follows [Semantic Versioning](https://semver.org), from `0.1.0`. While the version is below 1.0, a minor
+release may include breaking changes, and each one is marked **Breaking** in the
+[changelog](https://github.com/Yelison/forma-ui/blob/main/packages/forma-ui/CHANGELOG.md): pin an exact version, and
+read the changelog before you update.
+
+How a release is made, in short; [CONTRIBUTING.md](https://github.com/Yelison/forma-ui/blob/main/CONTRIBUTING.md) has
+the steps, the recovery and the first publication:
+
+- **Versioning:** each pull request that changes what the package ships adds a [Changesets](https://github.com/changesets/changesets)
+  file, and the `Changeset` job of CI fails one that does not. A regular pull request runs `npm run version-packages`,
+  which bumps the version, writes the changelog and consumes the changesets.
+- **Who publishes:** only the `Release` workflow, when that pull request is merged into `main` and npm does not have
+  the version yet. It authenticates with npm trusted publishing (OIDC) and no token is stored. Nobody publishes from a
+  workstation, and `publishConfig.provenance` makes `npm publish` fail anywhere else.
+- **Provenance:** every release is published with [provenance](https://docs.npmjs.com/generating-provenance-statements),
+  a signed statement that the tarball was built from this repository by that workflow run. The package page on npm shows
+  it, with a link to the run.
+- **Verify it:** in a project that installs the package, `npm audit signatures` checks the registry signature and the
+  provenance attestation of every installed package that has one.
+- **Rebuild it:** `npm run pack:reproducible` builds a commit twice from clean checkouts and fails unless both tarballs
+  have the same sha256. To compare a release with its source, check out the tag `@yelison/forma-ui@<version>`, use the
+  Node version in `.nvmrc` (other npm versions may pack the same files into different bytes), run `npm ci`,
+  `npm run build -w @yelison/forma-ui` and `npm pack -w @yelison/forma-ui`, and compare the tarball's SHA-512
+  (`openssl dgst -sha512 -binary <file>.tgz | base64`) with `npm view @yelison/forma-ui@<version> dist.integrity`, which
+  holds it after `sha512-`.
+
+## License
+
+[MIT](https://github.com/Yelison/forma-ui/blob/main/LICENSE)

package/dist/base.css

@@ -0,0 +1,25 @@
+/*
+ * The utility classes that the library and its consumers apply by name.
+ *
+ * The application imports this file, so it holds plain `.forma-*` class selectors and nothing else: an element,
+ * universal or pseudo-class selector here would reach into the consumer's own markup (base.css.test.ts fails on any
+ * other selector). Resets, focus rings and motion rules live in each component's module, or stay in the consumer.
+ */
+
+/* Hides content visually and keeps it in the accessibility tree, for labels that a screen reader announces. */
+.forma-visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* Set on <html> by the scroll lock (src/lib/scrollLock.ts) while a modal overlay is open. */
+.forma-scroll-locked {
+  overflow: hidden;
+}

package/dist/components/Badge/Badge.d.ts

@@ -0,0 +1,14 @@
+import type { ComponentProps } from 'react';
+/** The color roles a badge can take. */
+export type BadgeTone = 'blue' | 'green' | 'amber' | 'red' | 'neutral';
+/** Props of {@link Badge}: the native `span` attributes plus the tone. */
+export interface BadgeProps extends ComponentProps<'span'> {
+    /** Color of the badge. Defaults to `neutral`. */
+    tone?: BadgeTone;
+}
+/**
+ * A short label that tags an item with a status or category.
+ *
+ * The tone only colors the badge: its text must say the same thing, because color alone does not convey meaning.
+ */
+export declare function Badge({ tone, className, ...props }: BadgeProps): import("react").JSX.Element;

package/dist/components/Badge/Badge.js

@@ -0,0 +1,12 @@
+import { cx as e } from "../../lib/cx.js";
+import t from "./Badge.module.css.js";
+import { jsx as n } from "react/jsx-runtime";
+//#region src/components/Badge/Badge.tsx
+function r({ tone: r = "neutral", className: i, ...a }) {
+	return /* @__PURE__ */ n("span", {
+		className: e(t.badge, t[r], i),
+		...a
+	});
+}
+//#endregion
+export { r as Badge };

package/dist/components/Badge/Badge.module.css.js

@@ -0,0 +1,11 @@
+//#region src/components/Badge/Badge.module.css
+var e = "forma-badge", t = "forma-badge__blue", n = "forma-badge__green", r = "forma-badge__amber", i = "forma-badge__red", a = "forma-badge__neutral", o = {
+	badge: e,
+	blue: t,
+	green: n,
+	amber: r,
+	red: i,
+	neutral: a
+};
+//#endregion
+export { r as amber, e as badge, t as blue, o as default, n as green, a as neutral, i as red };

package/dist/components/Badge/index.d.ts

@@ -0,0 +1 @@
+export { Badge, type BadgeProps, type BadgeTone } from './Badge.js';

package/dist/components/Button/Button.d.ts

@@ -0,0 +1,23 @@
+import type { ComponentProps, ReactNode } from 'react';
+import { type IconName } from '../Icon/index.js';
+import { type ButtonStyleOptions } from './buttonClassName.js';
+/** Props of {@link Button}: the native `button` attributes plus the style options and the loading state. */
+export interface ButtonProps extends ComponentProps<'button'>, ButtonStyleOptions {
+    /** Icon shown before the content. A spinner takes its place while `loading`. */
+    icon?: IconName;
+    /** Ignores clicks and shows `loadingLabel` in place of the content while an action runs. Defaults to `false`. */
+    loading?: boolean;
+    /**
+     * Content that replaces the button's own while `loading`, and so its accessible name. Without it the button shows
+     * the `buttonLoading` string of the closest `FormaProvider`, or `Loading…` when there is none.
+     */
+    loadingLabel?: ReactNode;
+}
+/**
+ * A button for an action. `type` is `button` unless set, so a button inside a form does not submit it by accident.
+ *
+ * While `loading` the button stays focusable: it is `aria-disabled` and `aria-busy`, not `disabled`, because a
+ * disabled button drops out of the tab order and a keyboard user would lose their place. Use `disabled` for an action
+ * that is not available at all.
+ */
+export declare function Button({ variant, block, className, icon, loading, loadingLabel, type, onClick, children, ...props }: ButtonProps): import("react").JSX.Element;

package/dist/components/Button/Button.js

@@ -0,0 +1,34 @@
+import { useFormaStrings as e } from "../../provider/useFormaStrings.js";
+import { Icon as t } from "../Icon/Icon.js";
+import n from "./Button.module.css.js";
+import { buttonClassName as r } from "./buttonClassName.js";
+import { jsx as i, jsxs as a } from "react/jsx-runtime";
+//#region src/components/Button/Button.tsx
+function o({ variant: o, block: s, className: c, icon: l, loading: u = !1, loadingLabel: d, type: f = "button", onClick: p, children: m, ...h }) {
+	let { buttonLoading: g } = e();
+	function _(e) {
+		if (u) {
+			e.preventDefault();
+			return;
+		}
+		p?.(e);
+	}
+	return /* @__PURE__ */ a("button", {
+		...h,
+		type: f,
+		className: r({
+			variant: o,
+			block: s,
+			className: c
+		}),
+		"aria-busy": u || h["aria-busy"],
+		"aria-disabled": u || h["aria-disabled"],
+		onClick: _,
+		children: [u ? /* @__PURE__ */ i("span", {
+			className: n.spinner,
+			"aria-hidden": "true"
+		}) : l && /* @__PURE__ */ i(t, { name: l }), u ? d ?? g : m]
+	});
+}
+//#endregion
+export { o as Button };

package/dist/components/Button/Button.module.css.js

@@ -0,0 +1,13 @@
+//#region src/components/Button/Button.module.css
+var e = "forma-button", t = "forma-button__block", n = "forma-button__primary", r = "forma-button__secondary", i = "forma-button__ghost", a = "forma-button__danger", o = "forma-button__spinner", s = "forma-button__spin", c = {
+	button: e,
+	block: t,
+	primary: n,
+	secondary: r,
+	ghost: i,
+	danger: a,
+	spinner: o,
+	spin: s
+};
+//#endregion
+export { t as block, e as button, a as danger, c as default, i as ghost, n as primary, r as secondary, s as spin, o as spinner };

package/dist/components/Button/IconButton.d.ts

@@ -0,0 +1,17 @@
+import type { ComponentProps } from 'react';
+import { type IconName } from '../Icon/index.js';
+/** Props of {@link IconButton}: the native `button` attributes, without `children`, plus the icon and its name. */
+export interface IconButtonProps extends Omit<ComponentProps<'button'>, 'children'> {
+    /** The icon to draw, or several to draw side by side, overlapping, as one glyph, such as a double arrow. */
+    icon: IconName | readonly IconName[];
+    /** Mirrors the icon horizontally, so one drawing serves two directions. Defaults to `false`. */
+    flip?: boolean;
+    /** The accessible name. Required: the button has no visible text, so without it a screen reader has nothing to say. */
+    label: string;
+}
+/**
+ * A square button that holds only an icon. `type` is `button` unless set.
+ *
+ * `label` names the button for screen readers; show it as a tooltip too, so that sighted users can read it.
+ */
+export declare function IconButton({ icon, flip, label, className, type, ...props }: IconButtonProps): import("react").JSX.Element;

package/dist/components/Button/IconButton.js

@@ -0,0 +1,20 @@
+import { cx as e } from "../../lib/cx.js";
+import { Icon as t } from "../Icon/Icon.js";
+import n from "./IconButton.module.css.js";
+import { jsx as r } from "react/jsx-runtime";
+//#region src/components/Button/IconButton.tsx
+function i({ icon: i, flip: a = !1, label: o, className: s, type: c = "button", ...l }) {
+	let u = typeof i == "string" ? [i] : i;
+	return /* @__PURE__ */ r("button", {
+		...l,
+		type: c,
+		"aria-label": o,
+		className: e(n.iconButton, s),
+		children: /* @__PURE__ */ r("span", {
+			className: e(n.icons, a && n.flip),
+			children: u.map((e, n) => /* @__PURE__ */ r(t, { name: e }, n))
+		})
+	});
+}
+//#endregion
+export { i as IconButton };

package/dist/components/Button/IconButton.module.css.js

@@ -0,0 +1,8 @@
+//#region src/components/Button/IconButton.module.css
+var e = "forma-button-icon-button", t = "forma-button-icon-button__icons", n = "forma-button-icon-button__flip", r = {
+	iconButton: e,
+	icons: t,
+	flip: n
+};
+//#endregion
+export { r as default, n as flip, e as iconButton, t as icons };

package/dist/components/Button/buttonClassName.d.ts

@@ -0,0 +1,17 @@
+/** The visual weights a button can take. */
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
+/** The options that decide how a button looks, shared by `Button` and by `buttonClassName`. */
+export interface ButtonStyleOptions {
+    /** Visual weight of the button. Defaults to `primary`. */
+    variant?: ButtonVariant;
+    /** Makes the button fill the width of its container. Defaults to `false`. */
+    block?: boolean;
+    /** Extra class names, added after the library's own. */
+    className?: string;
+}
+/**
+ * Returns the class names of a button, for an element that is not a `Button` but must look like one, such as a link.
+ *
+ * The result only styles the element: a link keeps its own semantics and its own keyboard behavior.
+ */
+export declare function buttonClassName({ variant, block, className }?: ButtonStyleOptions): string;

package/dist/components/Button/buttonClassName.js

@@ -0,0 +1,8 @@
+import { cx as e } from "../../lib/cx.js";
+import t from "./Button.module.css.js";
+//#region src/components/Button/buttonClassName.ts
+function n({ variant: n = "primary", block: r = !1, className: i } = {}) {
+	return e(t.button, t[n], r && t.block, i);
+}
+//#endregion
+export { n as buttonClassName };

package/dist/components/Button/index.d.ts

@@ -0,0 +1,3 @@
+export { Button, type ButtonProps } from './Button.js';
+export { IconButton, type IconButtonProps } from './IconButton.js';
+export { buttonClassName, type ButtonStyleOptions, type ButtonVariant } from './buttonClassName.js';

package/dist/components/Dialog/Dialog.d.ts

@@ -0,0 +1,51 @@
+import { type ReactNode } from 'react';
+/** Props of {@link Dialog}. */
+export interface DialogProps {
+    /** Whether the dialog is open. */
+    open: boolean;
+    /**
+     * Called when the user asks to close the dialog: `Escape`, a click on the backdrop or a native close such as a
+     * `method="dialog"` form. Set `open` to `false` in it: the dialog stays open until the parent decides.
+     * It is not called when the parent closes the dialog by setting `open` itself.
+     */
+    onClose: () => void;
+    /** The dialog's title and its accessible name. */
+    title: ReactNode;
+    /** Text under the title. It becomes the dialog's accessible description. */
+    description?: ReactNode;
+    /**
+     * The actions at the bottom, usually a secondary and a primary `Button`. Put the way to dismiss the dialog here: a
+     * `Button` labeled with `useFormaStrings().dialogClose` follows the language of the closest `FormaProvider`.
+     */
+    footer?: ReactNode;
+    /** Width of the dialog: `--dialog-width` for `default` and `--dialog-width-wide` for `wide`. Defaults to `default`. */
+    size?: 'default' | 'wide';
+    /** Extra class names for the `<dialog>`, added after the library's own. */
+    className?: string;
+    /** The content between the description and the footer. It is rendered only while the dialog is open. */
+    children?: ReactNode;
+}
+/**
+ * A modal dialog on the native `<dialog>`: it opens with `showModal()`, so the focus stays inside it and the page
+ * behind is inert. `Escape` and a click on the backdrop call `onClose`, and the focus goes back to the element that
+ * had it when the dialog opened. While it is open the page scroll is locked, which needs `@yelison/forma-ui/base.css`.
+ *
+ * A click on the backdrop closes the dialog only if the pointer was pressed and released on the backdrop, so a drag
+ * that ends there, such as the end of a text selection, does not. If the element that had the focus is no longer in the
+ * document when the dialog closes, such as the item of a menu that unmounted, nothing takes the focus back and it
+ * falls to the page. Place it from an effect of the parent that runs when `open` becomes false: it runs after the
+ * dialog has closed, when the page is no longer inert. Do it in `onClose` and the page is still inert.
+ *
+ * The entrance moves the dialog for 200 ms, and a floating element is placed against where its anchor is when it opens.
+ * A `Tooltip` on the control that takes the initial focus opens in that time and ends a few pixels off its trigger:
+ * put another control first, or give the dialog `animation: none` through `className`. With `prefers-reduced-motion`
+ * the dialog does not move.
+ *
+ * The dialog is always in the document and its content only while `open`, so a closed dialog renders no children and
+ * a form inside starts empty each time.
+ */
+export declare function Dialog({ open, onClose, title, description, footer, size, className, children, }: DialogProps): import("react").JSX.Element;
+/** The name Resolve gave the dialog. The same component, so that Resolve adopts the package without renaming. */
+export declare const Modal: typeof Dialog;
+/** Props of {@link Modal}: the same type as {@link DialogProps}. */
+export type ModalProps = DialogProps;

package/dist/components/Dialog/Dialog.js

@@ -0,0 +1,38 @@
+import { cx as e } from "../../lib/cx.js";
+import { useModalDialog as t } from "../../lib/useModalDialog.js";
+import n from "./Dialog.module.css.js";
+import { useId as r } from "react";
+import { jsx as i, jsxs as a } from "react/jsx-runtime";
+//#region src/components/Dialog/Dialog.tsx
+function o({ open: o, onClose: s, title: c, description: l, footer: u, size: d = "default", className: f, children: p }) {
+	let m = r(), h = r(), g = t(o, s);
+	return /* @__PURE__ */ i("dialog", {
+		...g,
+		className: e(n.dialog, d === "wide" && n.wide, f),
+		"aria-labelledby": m,
+		"aria-describedby": l ? h : void 0,
+		children: o && /* @__PURE__ */ a("div", {
+			className: n.content,
+			children: [
+				/* @__PURE__ */ i("h2", {
+					id: m,
+					className: n.title,
+					children: c
+				}),
+				l && /* @__PURE__ */ i("p", {
+					id: h,
+					className: n.description,
+					children: l
+				}),
+				p,
+				u && /* @__PURE__ */ i("div", {
+					className: n.footer,
+					children: u
+				})
+			]
+		})
+	});
+}
+var s = o;
+//#endregion
+export { o as Dialog, s as Modal };

package/dist/components/Dialog/Dialog.module.css.js

@@ -0,0 +1,12 @@
+//#region src/components/Dialog/Dialog.module.css
+var e = "forma-dialog", t = "forma-dialog__enter", n = "forma-dialog__wide", r = "forma-dialog__content", i = "forma-dialog__title", a = "forma-dialog__description", o = "forma-dialog__footer", s = {
+	dialog: e,
+	enter: t,
+	wide: n,
+	content: r,
+	title: i,
+	description: a,
+	footer: o
+};
+//#endregion
+export { r as content, s as default, a as description, e as dialog, t as enter, o as footer, i as title, n as wide };

package/dist/components/Dialog/index.d.ts

@@ -0,0 +1 @@
+export { Dialog, Modal, type DialogProps, type ModalProps } from './Dialog.js';