@igne-agency/react-web-ui 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IGNE
+
+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

@@ -1,3 +1,240 @@
-# Temporary Holding Version
+# @igne-agency/react-web-ui
 
-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.
+IGNE's React component kit for the web: base-ui and react-aria primitives wrapped as compound parts, presets over them, every form control in three tiers with a TanStack Form bridge, and DTCG design tokens that each app themes. It is the web counterpart of `@igne-agency/react-native-ui`, with the same names and semantics where both have the concept.
+
+The package ships built ESM, one module per source file, each importing only its own CSS. An app needs no Vite, Sass or React Compiler configuration for it.
+
+## Install
+
+```sh
+bun add @igne-agency/react-web-ui
+bun add react react-dom @base-ui/react react-aria-components @internationalized/date @tanstack/react-form temporal-polyfill
+```
+
+Some entry points need an optional peer as well:
+
+| Import | Needs |
+| --- | --- |
+| `@igne-agency/react-web-ui/composer` | `lexical`, `@lexical/react`, `@lexical/history`, `@lexical/plain-text` |
+| `@igne-agency/react-web-ui/data-table` | `@tanstack/react-table` |
+| `@igne-agency/react-web-ui/data-view` | `@tanstack/react-query` |
+| `@igne-agency/react-web-ui/unsaved-changes/tanstack-router` | `@tanstack/react-router` |
+| `@igne-agency/react-web-ui/terrazzo` | `@terrazzo/cli`, `@terrazzo/plugin-css` |
+
+Lexical is a peer because it must be a single copy per app: an app that uses Lexical itself shares the kit's.
+
+## Imports
+
+Import each component from its own subpath, such as `@igne-agency/react-web-ui/button`. Everything else has one too: `./forms`, `./hooks`, `./storage`, `./table-storage`, `./tone` and `./unsaved-changes`. The app then loads the CSS of what it imports and of the components those render, and no other.
+
+The root, `@igne-agency/react-web-ui`, re-exports all of it but the entries that need an optional peer. A production build tree-shakes it, but Vite's dev server pre-bundles a package import with every export it has, so a single import from the root loads every component's stylesheet in development.
+
+## Styles
+
+Import the reset and a theme once, at the app's entry:
+
+```ts
+import "@igne-agency/react-web-ui/base.css";
+import "@igne-agency/react-web-ui/tokens.css";
+```
+
+`base.css` resets the user agent's styles and sets the body's font and colour, `::selection`, links and their focus ring. It also sets `isolation: isolate` on `#root` and `position: relative` on `body`, which base-ui's popups need. It loads no fonts; the app loads its own.
+
+`tokens.css` is the kit's default theme: the `--ref-*` ramps and the `--sys-*` roles, light on `:root` and dark on `html[data-theme="dark"]`, and under `prefers-color-scheme: dark` unless `data-theme="light"`.
+
+All kit CSS sits in the cascade layers `kit.reset`, `kit.base` and `kit.components`, so any unlayered CSS in the app wins without a specificity fight. Each component reads its own custom properties ("knobs"), defaulting to a `--sys-*` role, so a stylesheet can retheme one component by setting its knobs.
+
+## Theming
+
+An app with its own brand builds its own `tokens.css` instead of importing the kit's. Its resolver layers the kit's token files and the app's own overrides:
+
+```json
+{
+	"$schema": "https://www.designtokens.org/schemas/2025.10/resolver.json",
+	"name": "App",
+	"version": "2025.10",
+	"sets": {
+		"base": {
+			"sources": [
+				{
+					"$ref": "../../node_modules/@igne-agency/react-web-ui/tokens/ref.tokens.json"
+				},
+				{
+					"$ref": "../../node_modules/@igne-agency/react-web-ui/tokens/sys.tokens.json"
+				},
+				{ "$ref": "brand.tokens.json" }
+			]
+		}
+	},
+	"modifiers": {
+		"theme": {
+			"contexts": {
+				"light": [],
+				"dark": [
+					{
+						"$ref": "../../node_modules/@igne-agency/react-web-ui/tokens/dark.tokens.json"
+					}
+				]
+			},
+			"default": "light"
+		}
+	},
+	"resolutionOrder": [
+		{ "$ref": "#/sets/base" },
+		{ "$ref": "#/modifiers/theme" }
+	]
+}
+```
+
+The `./terrazzo` preset builds it into the custom properties the components read:
+
+```ts
+// terrazzo.config.ts
+import { defineConfig } from "@terrazzo/cli";
+import kitTokens from "@igne-agency/react-web-ui/terrazzo";
+
+export default defineConfig({
+	tokens: ["./src/style/tokens/app.resolver.json"],
+	outDir: "./src/style/",
+	plugins: [kitTokens({ filename: "tokens.gen.css" })],
+});
+```
+
+The resolver needs a `theme` modifier with `light` and `dark` contexts. Like the kit's own `tokens.css`, the file the preset writes opens with the kit's layer order and keeps every rule in `kit.base`, so an unlayered override in the app still wins. The preset names every token by its path with dots as hyphens (`sys.color.primary` becomes `--sys-color-primary`), and writes a shadow tagged `$extensions["nl.igne.css"].property: "filter"` as `drop-shadow()` filters.
+
+The kit owns no breakpoints and no gutters; those are the app's layout.
+
+## Providers
+
+The kit has no catch-all provider. Wrap the app in the ones it uses:
+
+```tsx
+import { LocaleProvider } from "@igne-agency/react-web-ui/locale-provider";
+import { TimeZoneProvider } from "@igne-agency/react-web-ui/time-zone-provider";
+import { ToastProvider } from "@igne-agency/react-web-ui/toast";
+import { Tooltip } from "@igne-agency/react-web-ui/tooltip";
+
+export const Providers = ({
+	children,
+}: Readonly<{ children: React.ReactNode }>) => (
+	<LocaleProvider locale="nl-NL">
+		<TimeZoneProvider timeZone="Europe/Amsterdam">
+			<Tooltip.Provider>
+				<ToastProvider
+					closeLabel="Close"
+					viewportLabel="Notifications">
+					{children}
+				</ToastProvider>
+			</Tooltip.Provider>
+		</TimeZoneProvider>
+	</LocaleProvider>
+);
+```
+
+`LocaleProvider` takes a BCP 47 locale and `TimeZoneProvider` an IANA time zone. Both are required: `useLocale()` and `useTimeZone()` throw outside them, and nothing falls back to the device.
+
+The kit has no copy of its own. Every string a component shows or announces is a prop named for what it says, such as `clearLabel` or `retryLabel`, so the app passes its own translations.
+
+## Forms
+
+Every control comes in three tiers:
+
+- the raw compound, such as `TextInput` or `Select`
+- the field shorthand with label, description and errors, such as `TextField` or `SelectField`
+- the TanStack Form bridge, such as `TSFTextField`, which the app registers on its form hook
+
+`createAppForm` builds the app's form hook from the bridges it registers, once, in a module of the app's own. A form reaches each bridge through `form.AppField` under its key, and loads the code and CSS of those bridges only:
+
+```ts
+// src/form.ts
+import { TSFEmailField } from "@igne-agency/react-web-ui/email-field";
+import { createAppForm } from "@igne-agency/react-web-ui/forms";
+
+export const { useAppForm, withForm, withFieldGroup } =
+	createAppForm({ EmailField: TSFEmailField });
+```
+
+```tsx
+import { Form } from "@igne-agency/react-web-ui/form";
+import { useAppForm } from "./form.ts";
+
+const SignUp = () => {
+	const form = useAppForm({
+		defaultValues: { email: "" },
+		validators: { onSubmit: schema },
+		onSubmit: ({ value }) => save(value),
+	});
+	return (
+		<Form.Root form={form}>
+			<form.AppField name="email">
+				{field => (
+					<field.EmailField
+						label="Email"
+						requiredness="required"
+						optionalLabel="optional"
+					/>
+				)}
+			</form.AppField>
+			<Form.Errors />
+			<Form.Submit busyLabel="Signing up">
+				Sign up
+			</Form.Submit>
+		</Form.Root>
+	);
+};
+```
+
+Related fields, such as the parts of an address, share one legend and one error in a field group, which lines them up side by side. Register `TSFFieldGroup` as a form component and name the fields whose errors it shows:
+
+```ts
+import { TSFFieldGroup } from "@igne-agency/react-web-ui/fieldset";
+import { TSFTextField } from "@igne-agency/react-web-ui/text-field";
+
+export const { useAppForm, withForm, withFieldGroup } =
+	createAppForm(
+		{ TextField: TSFTextField },
+		{ FieldGroup: TSFFieldGroup },
+	);
+```
+
+```tsx
+<form.FieldGroup
+	legend="Address"
+	optionalLabel="optional"
+	names={["postalCode", "houseNumber"]}>
+	<form.AppField name="postalCode">
+		{field => (
+			<field.TextField
+				label="Postal code"
+				requiredness="required"
+				optionalLabel="optional"
+			/>
+		)}
+	</form.AppField>
+	<form.AppField name="houseNumber">
+		{field => (
+			<field.TextField
+				label="House number"
+				requiredness="required"
+				optionalLabel="optional"
+			/>
+		)}
+	</form.AppField>
+</form.FieldGroup>
+```
+
+Every field takes `requiredness` (`"required"`, `"optional"`, or left out to show neither mark) and `errors`, which accepts strings and anything with a string `message`, such as Standard Schema issues. Validation is the app's own, through Standard Schema; the kit ships no validators.
+
+`Form.Root` reports unsaved changes to the page's leave guards (`useLeaveGuard`, or `useRouterLeaveGuard` from `./unsaved-changes/tanstack-router`) while its `leaveGuard` policy returns true for the form's live state. The default, `whenDirty`, guards while the values differ from their defaults and no submit is in flight. Pass `never` for a form whose edits need not survive leaving, or any `(state) => boolean`:
+
+```tsx
+import { never } from "@igne-agency/react-web-ui/unsaved-changes";
+
+<Form.Root form={filters} leaveGuard={never}>
+	…
+</Form.Root>;
+```
+
+## License
+
+MIT

package/dist/assets/spinner.js

@@ -0,0 +1,28 @@
+import "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+// src/assets/spinner.svg?react
+var SvgSpinner = (props) => /* @__PURE__ */ jsxs("svg", {
+	xmlns: "http://www.w3.org/2000/svg",
+	stroke: "currentColor",
+	viewBox: "0 0 24 24",
+	...props,
+	children: [/* @__PURE__ */ jsx("style", { children: "@keyframes spinner_zKoa{to{transform:rotate(360deg)}}@keyframes spinner_YpZS{0%{stroke-dasharray:0 150;stroke-dashoffset:0}47.5%{stroke-dasharray:42 150;stroke-dashoffset:-16}95%,to{stroke-dasharray:42 150;stroke-dashoffset:-59}}" }), /* @__PURE__ */ jsx("g", {
+		style: {
+			transformOrigin: "center",
+			animation: "spinner_zKoa 2s linear infinite"
+		},
+		children: /* @__PURE__ */ jsx("circle", {
+			cx: 12,
+			cy: 12,
+			r: 9.5,
+			fill: "none",
+			strokeWidth: 3,
+			className: "spinner_V8m1",
+			style: {
+				strokeLinecap: "round",
+				animation: "spinner_YpZS 1.5s ease-in-out infinite"
+			}
+		})
+	})]
+});
+export { SvgSpinner as default };

package/dist/base.css

@@ -0,0 +1,171 @@
+@layer kit.reset, kit.base, kit.components;
+@layer kit.reset {
+  /***
+      The new CSS reset - version 1.11.3 (last updated 25.08.2024)
+      GitHub page: https://github.com/elad2412/the-new-css-reset
+  ***/
+  /*
+      Remove all the styles of the "User-Agent-Stylesheet", except for the 'display' property
+      - The "symbol *" part is to solve Firefox SVG sprite bug
+      - The "html" element is excluded, otherwise a bug in Chrome breaks the CSS hyphens property (https://github.com/elad2412/the-new-css-reset/issues/36)
+   */
+  *:where(:not(html, iframe, canvas, img, svg, video, audio):not(svg *, symbol *)) {
+    all: unset;
+    display: revert;
+  }
+  /* Preferred box-sizing value */
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+  /* Fix mobile Safari increase font-size on landscape mode */
+  html {
+    -moz-text-size-adjust: none;
+    -webkit-text-size-adjust: none;
+    text-size-adjust: none;
+  }
+  /* Reapply the pointer cursor for anchor tags */
+  a, button {
+    cursor: revert;
+  }
+  /* Remove list styles (bullets/numbers) */
+  ol, ul, menu, summary {
+    list-style: none;
+  }
+  /* Firefox: solve issue where nested ordered lists continue numbering from parent (https://bugzilla.mozilla.org/show_bug.cgi?id=1881517) */
+  ol {
+    counter-reset: revert;
+  }
+  /* For images to not be able to exceed their container */
+  img {
+    max-inline-size: 100%;
+    max-block-size: 100%;
+  }
+  /* removes spacing between cells in tables */
+  table {
+    border-collapse: collapse;
+  }
+  /* Safari - solving issue when using user-select:none on the <body> text input doesn't working */
+  input, textarea {
+    -webkit-user-select: auto;
+  }
+  /* revert the 'white-space' property for textarea elements on Safari */
+  textarea {
+    white-space: revert;
+  }
+  /* minimum style to allow to style meter element */
+  meter {
+    -webkit-appearance: revert;
+    appearance: revert;
+  }
+  /* preformatted text - use only for this feature */
+  :where(pre) {
+    all: revert;
+    box-sizing: border-box;
+  }
+  /* reset default text opacity of input placeholder */
+  ::placeholder {
+    color: unset;
+  }
+  /* fix the feature of 'hidden' attribute.
+     display:revert; revert to element instead of attribute */
+  :where([hidden]) {
+    display: none;
+  }
+  /* revert for bug in Chromium browsers
+     - fix for the content editable attribute will work properly.
+     - webkit-user-select: auto; added for Safari in case of using user-select:none on wrapper element*/
+  :where([contenteditable]:not([contenteditable=false])) {
+    -moz-user-modify: read-write;
+    -webkit-user-modify: read-write;
+    overflow-wrap: break-word;
+    -webkit-line-break: after-white-space;
+    -webkit-user-select: auto;
+  }
+  /* apply back the draggable feature - exist only in Chromium and Safari */
+  :where([draggable=true]) {
+    -webkit-user-drag: element;
+  }
+  /* Revert Modal native behavior */
+  :where(dialog:modal) {
+    all: revert;
+    box-sizing: border-box;
+  }
+  /* Remove details summary webkit styles */
+  ::-webkit-details-marker {
+    display: none;
+  }
+}
+@layer kit.base {
+  #root {
+    isolation: isolate;
+  }
+  body {
+    position: relative;
+    background-color: var(--sys-color-bg);
+    color: var(--sys-color-text);
+    font: var(--sys-font-body-medium);
+  }
+  @media not (prefers-reduced-motion) {
+    body {
+      transition: background-color var(--sys-motion-medium) var(--sys-motion-standard), color var(--sys-motion-medium) var(--sys-motion-standard);
+    }
+  }
+  button,
+  select,
+  summary,
+  a[href],
+  [type=button],
+  [type=checkbox],
+  [type=color],
+  [type=file],
+  [type=image],
+  [type=radio],
+  [type=range],
+  [type=reset],
+  [type=submit],
+  [role=button],
+  [role=checkbox],
+  [role=menuitem],
+  [role=menuitemcheckbox],
+  [role=menuitemradio],
+  [role=option],
+  [role=radio],
+  [role=switch],
+  [role=tab] {
+    cursor: pointer;
+  }
+  :disabled,
+  [aria-disabled=true],
+  [data-disabled] {
+    cursor: not-allowed;
+  }
+  [aria-readonly=true]:not(:where(input, textarea, [contenteditable])),
+  [data-readonly]:not(:where(input, textarea, [contenteditable])) {
+    cursor: default;
+  }
+  :where(input[aria-hidden=true][tabindex="-1"]) {
+    inset-block-start: 0;
+    inset-inline-start: 0;
+  }
+  ::selection {
+    background-color: var(--sys-color-selection-bg);
+    color: var(--sys-color-selection-fg);
+  }
+  :where(a[href]) {
+    color: var(--sys-color-primary);
+    text-decoration: underline;
+    text-underline-offset: var(--sys-unit-1);
+  }
+  :where(a[href]) {
+    outline: 0 solid var(--sys-color-focus-ring);
+    outline-offset: var(--sys-focus-ring-offset);
+  }
+  :where(a[href]):focus-visible {
+    outline-width: var(--sys-focus-ring-width);
+  }
+  :where(a[href]):hover {
+    color: var(--sys-color-on-primary-container);
+  }
+}

package/dist/components/accordion/accordion.css

@@ -0,0 +1,93 @@
+@layer kit.reset, kit.base, kit.components;
+@layer kit.components {
+  ._root_1u0up_3 {
+    display: flex;
+    flex-direction: column;
+    gap: var(--accordion-gap, var(--sys-unit-2));
+  }
+  ._item_1u0up_8 {
+    display: flex;
+    flex-direction: column;
+  }
+  ._trigger_1u0up_12 {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--accordion-trigger-gap, var(--sys-unit-4));
+    box-sizing: border-box;
+    inline-size: 100%;
+    border: none;
+    border-radius: var(--accordion-trigger-radius, var(--sys-radius-sm));
+    background: var(--accordion-trigger-bg, transparent);
+    padding: var(--accordion-trigger-pad-y, var(--sys-unit-4)) var(--accordion-trigger-pad-x, var(--sys-unit-6));
+    color: var(--accordion-trigger-fg, var(--sys-color-text));
+    font: var(--accordion-trigger-font, var(--sys-font-label-large));
+    text-align: start;
+    cursor: pointer;
+  }
+  ._trigger_1u0up_12 {
+    outline: 0 solid var(--sys-color-focus-ring);
+    outline-offset: var(--sys-focus-ring-offset);
+  }
+  ._trigger_1u0up_12:focus-visible {
+    outline-width: var(--sys-focus-ring-width);
+  }
+  ._trigger_1u0up_12 {
+    position: relative;
+    isolation: isolate;
+  }
+  ._trigger_1u0up_12::after {
+    content: "";
+    position: absolute;
+    z-index: -1;
+    inset: 0;
+    border-radius: inherit;
+    background: currentcolor;
+    opacity: 0;
+    pointer-events: none;
+  }
+  @media not (prefers-reduced-motion) {
+    ._trigger_1u0up_12::after {
+      transition: opacity var(--sys-motion-instant) var(--sys-motion-standard);
+    }
+  }
+  ._trigger_1u0up_12:hover:not(:disabled, [data-disabled])::after {
+    opacity: var(--sys-state-hover);
+  }
+  ._trigger_1u0up_12:active:not(:disabled, [data-disabled])::after {
+    opacity: var(--sys-state-pressed);
+  }
+  ._trigger_1u0up_12[data-disabled] {
+    color: var(--sys-color-disabled-fg);
+    cursor: not-allowed;
+  }
+  ._chevron_1u0up_64 {
+    flex-shrink: 0;
+  }
+  @media not (prefers-reduced-motion) {
+    ._chevron_1u0up_64 {
+      transition: rotate var(--sys-motion-short) var(--sys-motion-standard);
+    }
+  }
+  [data-panel-open] > ._chevron_1u0up_64 {
+    rotate: 180deg;
+  }
+  ._panel_1u0up_75 {
+    overflow: hidden;
+  }
+  ._panel_1u0up_75[hidden]:not([hidden=until-found]) {
+    display: none;
+  }
+  @media not (prefers-reduced-motion) {
+    ._panel_1u0up_75 {
+      block-size: var(--accordion-panel-height);
+      transition: block-size var(--sys-motion-short) var(--sys-motion-standard);
+    }
+    ._panel_1u0up_75[data-starting-style], ._panel_1u0up_75[data-ending-style] {
+      block-size: 0;
+    }
+  }
+  ._content_1u0up_90 {
+    padding: var(--accordion-pad-y, var(--sys-unit-4)) var(--accordion-pad-x, var(--sys-unit-6));
+  }
+}

package/dist/components/accordion/accordion.d.ts

@@ -0,0 +1,46 @@
+import { Accordion as BaseAccordion } from "@base-ui/react/accordion";
+import type { ReactNode } from "react";
+export type AccordionRootProps = Omit<BaseAccordion.Root.Props<string>, "className"> & Readonly<{
+    className?: string;
+}>;
+export type AccordionItemProps = Omit<BaseAccordion.Item.Props, "className" | "value"> & Readonly<{
+    className?: string;
+    /** Identifies the item in the root's `value`. */
+    value?: string;
+}>;
+export type AccordionTriggerProps = Omit<BaseAccordion.Trigger.Props, "className" | "children"> & Readonly<{
+    className?: string;
+    /** What the item's panel holds, as the trigger's label. */
+    children: ReactNode;
+}>;
+export type AccordionPanelProps = Omit<BaseAccordion.Panel.Props, "className"> & Readonly<{
+    className?: string;
+}>;
+declare const Root: ({ className, ...props }: AccordionRootProps) => ReactNode;
+declare const Item: ({ className, ...props }: AccordionItemProps) => ReactNode;
+declare const Trigger: ({ className, children, ...props }: AccordionTriggerProps) => ReactNode;
+declare const Panel: ({ className, children, ...props }: AccordionPanelProps) => ReactNode;
+type AccordionNamespace = Readonly<{
+    Root: typeof Root;
+    Item: typeof Item;
+    Header: typeof BaseAccordion.Header;
+    Trigger: typeof Trigger;
+    Panel: typeof Panel;
+}>;
+/**
+ * A stack of panels that fold open and shut, each under a heading whose
+ * trigger names it, on base-ui's `Accordion`. `Header` renders an `<h3>`; pass
+ * `render={<h2 />}` where the page's outline needs another level.
+ *
+ * @example
+ * <Accordion.Root>
+ * 	<Accordion.Item value="fees">
+ * 		<Accordion.Header>
+ * 			<Accordion.Trigger>Fees</Accordion.Trigger>
+ * 		</Accordion.Header>
+ * 		<Accordion.Panel>{fees}</Accordion.Panel>
+ * 	</Accordion.Item>
+ * </Accordion.Root>
+ */
+export declare const Accordion: AccordionNamespace;
+export {};